@ultimat3/cli 1.2.0 → 2.0.0

package/src/dev-n-plus-one.ts

@@ -0,0 +1,191 @@
+// The N+1 ledger: one count per statement shape per request, and a verdict once a shape crosses
+// the threshold. Counting state hangs off the request's own `Ctx` in a `WeakMap`, so it is
+// collected with the request and never swept. Installed by `x dev` and by nothing else — a
+// production process pays the one `undefined` branch `@ultimat3/db`'s seam already costs (axiom 6).
+// It counts and it warns once; what a verdict *means* — which code, which `fix:` — is
+// `statement-loop.ts`'s, so all four surfaces read one answer.
+
+import type { Ctx } from '@ultimat3/core';
+import { assert, tryUseContext } from '@ultimat3/core';
+import type { StatementAttribution, StatementEvent, StatementObserver } from '@ultimat3/db';
+import { statementFingerprint, statementKind } from '@ultimat3/db';
+import { N_PLUS_ONE_THRESHOLD } from '@ultimat3/entity';
+import { loopFacts, warnLoop } from './statement-loop';
+
+/** Verdicts retained. A dev diagnostic shows the recent loops; it does not page through history. */
+const DEFAULT_LIMIT = 50;
+
+/** One statement shape, repeated inside one request past the threshold. */
+export interface RepeatedStatement {
+  /** What was repeated: `members.findById` when attributed, else the statement's own text. */
+  readonly fingerprint: string;
+  /** Which loop this is, and therefore which fix a report can name. */
+  readonly kind: 'read' | 'write';
+  /** The entity and operation that compiled it, absent for hand-written SQL and queue traffic. */
+  readonly attribution?: StatementAttribution | undefined;
+  /** One of the statements, verbatim — the SQL a report shows under the fingerprint. */
+  readonly sample: string;
+  /** Statements of this shape the request has issued so far. Never below the threshold. */
+  readonly count: number;
+  /** The request the loop happened in; a report and its log line name the same one. */
+  readonly requestId: string;
+  readonly traceId: string;
+}
+
+export interface StatementLedger {
+  /** Hand this to `setStatementObserver()`. */
+  readonly observer: StatementObserver;
+  /** Shapes that crossed the threshold, newest first. */
+  repeats(): readonly RepeatedStatement[];
+  /**
+   * The same verdicts, for one request. What the browser overlay shows next to an error: a page
+   * that looped names its loop on the page, not only in a terminal the author is not looking at.
+   */
+  repeatsFor(ctx: Ctx): readonly RepeatedStatement[];
+  reset(): void;
+}
+
+export interface StatementLedgerOptions {
+  /**
+   * Statements of one shape in one request that trip a verdict. Defaults to
+   * `N_PLUS_ONE_THRESHOLD` — `@ultimat3/entity`'s, so this ledger and the strict test fixture
+   * cannot disagree about how many of one shape is a loop.
+   */
+  readonly threshold?: number;
+  /** Verdicts retained before the oldest is dropped. Default `50`. */
+  readonly limit?: number;
+}
+
+/** The live count behind a `RepeatedStatement`: reported once, then still counting. */
+interface RepeatGroup {
+  readonly fingerprint: string;
+  readonly kind: 'read' | 'write';
+  readonly attribution: StatementAttribution | undefined;
+  readonly sample: string;
+  readonly requestId: string;
+  readonly traceId: string;
+  count: number;
+  /** Whether this shape is already a verdict. The flag, not the count, so a `threshold` of 1 works. */
+  promoted: boolean;
+}
+
+/** The verdict a surface reads, without the bookkeeping the group keeps for the ledger itself. */
+const snapshot = (group: RepeatGroup): RepeatedStatement => ({
+  fingerprint: group.fingerprint,
+  kind: group.kind,
+  attribution: group.attribution,
+  sample: group.sample,
+  count: group.count,
+  requestId: group.requestId,
+  traceId: group.traceId,
+});
+
+/**
+ * Count statement shapes per request and report the ones that repeat past `threshold`.
+ *
+ * Three rules, each load-bearing. **Per request, keyed by the context object** — the map dies with
+ * the `Ctx` that owns it, so a dev server up for a week accumulates nothing and no sweep has to
+ * decide when a request ended. A statement issued outside a request (a migration, a boot probe, a
+ * script) is not counted at all: "five of one shape" only means something inside one unit of work.
+ * A `withChildContext` scope is its own key and therefore its own tally, which is the price of
+ * keying on identity rather than on `requestId` and holding the counts forever.
+ *
+ * **An expected statement is not counted** — `expectedQueryLoop` suppresses a verdict, and this
+ * ledger *is* the verdict. The statement is still sent, still observed and still a span, so the
+ * timeline keeps showing the loop while the thing that warns is told the author already answered.
+ *
+ * **A shape is promoted exactly once**, on the statement that crosses the threshold, and the group
+ * behind it keeps counting — so a loop of fifty is one verdict reading `count: 50`, not
+ * forty-six verdicts. The report list is bounded and drops its oldest entry.
+ *
+ * Promotion is also the moment the log line goes out, and it is **one line per request per code**:
+ * a request that loops three different shapes of read has three verdicts and one `X_N_PLUS_ONE_QUERY`
+ * warning, because a log is read to learn that this request looped and the three shapes are what
+ * `x dev`'s findings, `/_x` and the overlay are for. The line names the count as it stood when the
+ * threshold was crossed; every other surface reads the count as it stands when asked.
+ */
+export function createStatementLedger(options: StatementLedgerOptions = {}): StatementLedger {
+  const threshold = options.threshold ?? N_PLUS_ONE_THRESHOLD;
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  assert(
+    Number.isInteger(threshold) && threshold >= 1,
+    `createStatementLedger() was given a threshold of ${threshold}, which no statement count can reach`,
+    'pass a whole number of statements: createStatementLedger({ threshold: 5 })',
+  );
+  assert(
+    Number.isInteger(limit) && limit >= 1,
+    `createStatementLedger() was given a limit of ${limit}, so no verdict could be kept`,
+    'pass how many verdicts to retain: createStatementLedger({ limit: 50 })',
+  );
+  const byRequest = new WeakMap<Ctx, Map<string, RepeatGroup>>();
+  // Which codes this request has already warned about. Its own map rather than a field on the
+  // groups: the rule is one line per *code*, and the groups are per shape — three shapes of read
+  // in one request share one warning and each keeps its own verdict.
+  const warned = new WeakMap<Ctx, Set<string>>();
+  const reported: RepeatGroup[] = [];
+
+  const warnOnce = (ctx: Ctx, group: RepeatGroup): void => {
+    const facts = loopFacts(snapshot(group));
+    let codes = warned.get(ctx);
+    if (codes === undefined) {
+      codes = new Set();
+      warned.set(ctx, codes);
+    }
+    if (codes.has(facts.code)) return;
+    codes.add(facts.code);
+    warnLoop(facts);
+  };
+
+  const onStatement = (event: StatementEvent): void => {
+    if (event.expected !== undefined) return;
+    const ctx = tryUseContext();
+    if (ctx === undefined) return;
+    let groups = byRequest.get(ctx);
+    if (groups === undefined) {
+      groups = new Map();
+      byRequest.set(ctx, groups);
+    }
+    const fingerprint = statementFingerprint(event);
+    let group = groups.get(fingerprint);
+    if (group === undefined) {
+      group = {
+        fingerprint,
+        kind: statementKind(event.text),
+        attribution: event.attribution,
+        sample: event.text,
+        requestId: ctx.requestId,
+        traceId: ctx.traceId,
+        count: 0,
+        promoted: false,
+      };
+      groups.set(fingerprint, group);
+    }
+    // A statement that threw is still a statement: fifty identical timeouts are still a loop, and
+    // one that reports them as four is a loop nobody is told about.
+    group.count += 1;
+    if (group.promoted || group.count < threshold) return;
+    group.promoted = true;
+    reported.push(group);
+    if (reported.length > limit) reported.shift();
+    warnOnce(ctx, group);
+  };
+
+  return {
+    observer: { onStatement },
+    repeats(): readonly RepeatedStatement[] {
+      // Snapshotted, because the groups behind these are still counting — and newest first,
+      // matching the trace recorder: the loop that just happened is the one being looked at.
+      return reported.map(snapshot).reverse();
+    },
+    repeatsFor(ctx: Ctx): readonly RepeatedStatement[] {
+      // Read off this request's own tally rather than filtered out of `reported`, so a verdict the
+      // bound already dropped is still shown on the page it happened on.
+      const groups = byRequest.get(ctx);
+      if (groups === undefined) return [];
+      return [...groups.values()].filter((group) => group.promoted).map(snapshot);
+    },
+    reset(): void {
+      reported.length = 0;
+    },
+  };
+}

package/src/dev-queue.ts

@@ -1,19 +1,40 @@
 // The database and the job queue, started together and released together. Split from
 // `dev-runtime.ts` because `x jobs` needs exactly this pair and nothing else — and because a
-// process that installs two ambient accessors (`db()`, `jobDriver()`) must have one place that
-// takes both back, or the next command in the same process inherits a driver over a closed socket.
+// process that installs ambient accessors (`db()`, `jobDriver()`, the jobs facade, the event bus)
+// must have one place that takes them all back, or the next command in the same process inherits
+// a driver over a closed socket.
 
-import type { PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
+import {
+  postgresIdempotencyStore,
+  resetIdempotency,
+  SQL_IDEMPOTENCY_TABLE,
+  setIdempotencyStore,
+} from '@ultimat3/action';
+import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
 import {
   createPgliteClient,
   createPostgresClient,
+  currentTx,
   pgliteDataDir,
   raw,
   setDbClient,
 } from '@ultimat3/db';
-import type { JobDriver, PgExecutor } from '@ultimat3/jobs';
-import { createPgDriver, resetJobDriver, SQL_JOBS_TABLE, setJobDriver } from '@ultimat3/jobs';
+import type { Tx } from '@ultimat3/entity';
+import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
+import {
+  createJobsFacade,
+  createPgDriver,
+  createPgEventBus,
+  createPgOutboxStore,
+  resetJobDriver,
+  resetJobsFacade,
+  SQL_JOBS_TABLE,
+  setEventBus,
+  setJobDriver,
+  setJobsFacade,
+} from '@ultimat3/jobs';
 import type { DevServices } from './dev-services';
+import type { RuntimeOverrides } from './runtime-overrides';
 
 /** Both embedded and external clients boot lazily and close explicitly. */
 export type DevDbClient = PgliteClient | PostgresClient;
@@ -21,6 +42,13 @@ export type DevDbClient = PgliteClient | PostgresClient;
 export interface RunningQueue {
   readonly db: DevDbClient;
   readonly jobs: JobDriver;
+  /**
+   * The `x_outbox` store this boot installed behind `handle.enqueue()`. Returned because the
+   * relay that drains it is a ROLE's decision, not the queue's — `dev-roles.ts` starts one.
+   */
+  readonly outbox: OutboxStore;
+  /** The `x_job_events` bus a `step.waitForEvent` resumes from. Durable, not per-process. */
+  readonly events: EventBus;
   stop(): Promise<void>;
 }
 
@@ -43,38 +71,94 @@ function startDb(services: DevServices): DevDbClient {
  * The fragment is assembled by hand rather than through `sql`` ` because the driver hands over
  * `$1..$n` text it wrote itself plus already-bound values — there is no interpolation to guard.
  */
-function executorFor(client: DevDbClient): PgExecutor {
+export function pgExecutorFor(client: DbClient): PgExecutor {
   return {
     query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
       client.query<R>({ text, values } satisfies SqlFragment),
   };
 }
 
+/**
+ * Every table this process's framework packages own, applied before anything reads one.
+ *
+ * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL is
+ * applied statement by statement. Safe to split on `;`: both constants are fixed, with no
+ * semicolon inside a literal, and each package's own SQL test is where that stays true.
+ *
+ * `SQL_IDEMPOTENCY_TABLE` is here and not in `@ultimat3/action` because a package that holds no
+ * database dependency cannot apply its own schema — the same reason `SQL_JOBS_TABLE` is applied
+ * here. Without it `postgresIdempotencyStore` is a store whose first reservation fails on a
+ * missing relation, which is how a retried `POST /api/payments/charge` charges a card twice.
+ */
+async function applySchema(client: DevDbClient): Promise<void> {
+  for (const ddl of [SQL_JOBS_TABLE, SQL_IDEMPOTENCY_TABLE]) {
+    for (const statement of ddl.split(';')) {
+      if (statement.trim().length > 0) await client.execute(raw(statement));
+    }
+  }
+}
+
 /**
  * The dev queue is the real Postgres queue on the embedded Postgres — claiming, leases and the
  * one-live-job-per-key index all behave here exactly as in production. A memory queue in dev
  * would hide every bug this driver exists to make impossible.
  *
- * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL
- * is applied statement by statement. Safe to split on `;`: `SQL_JOBS_TABLE` is a fixed constant
- * with no semicolon inside a literal, and `driver-pg-sql.test.ts` is where that stays true.
+ * Three ambient installs, not one, and they go in together because they are one decision:
+ *
+ * - `setJobDriver` is what `jobDriver()` answers and what a worker claims from.
+ * - `setJobsFacade` is what `handle.enqueue()` routes through, so an enqueue inside a request's
+ *   transaction STAGES a row that commits or vanishes with the business rows. Without it the
+ *   fallback facade publishes straight to the driver, and a job for a transaction that rolled
+ *   back still runs. `currentTx()` resolves the executor because a `DbTx` IS a client on the
+ *   transaction's own connection, while the `Tx` token `@ultimat3/entity` hands over is not that
+ *   object — so the token is a key and the ALS is the lookup.
+ * - `setEventBus` makes `step.waitForEvent` durable. The memory bus this replaced forgot every
+ *   pending correlation on restart, which is a job that waits forever.
+ * - `setIdempotencyStore` makes `idempotent: true` mean it across replicas. The memory default is
+ *   one process' worth of keys, so a client retrying `POST /api/payments/charge` after a timeout
+ *   lands on a replica that has never seen the key and charges the card a second time.
+ *
+ * The idempotency store is installed HERE and not from the app, even though
+ * `@ultimat3/action` documents `postgresIdempotencyStore({ executor: Bun.sql })`: `Bun.sql` has no
+ * `.query(text, values)` — it is a tagged template whose positional form is `unsafe` — so that
+ * line does not satisfy `PgExecutor` at all, and a second executor would open a second pool
+ * against a URL this boot already resolved. Boot owns the connection, so boot supplies it.
+ * `startServices` runs before `loadApp`, so the store is in place before `registerAction`
+ * evaluates a `scope: 'shared'` declaration against it.
  */
-async function startJobs(client: DevDbClient): Promise<JobDriver> {
-  for (const statement of SQL_JOBS_TABLE.split(';')) {
-    if (statement.trim().length > 0) await client.execute(raw(statement));
-  }
-  const driver = createPgDriver({ executor: executorFor(client) });
+async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Promise<RunningQueue> {
+  await applySchema(client);
+  const executor = pgExecutorFor(client);
+  const driver = overrides?.jobs ?? createPgDriver({ executor });
   setJobDriver(driver);
-  return driver;
+  const outbox = createPgOutboxStore({
+    executor,
+    // The open transaction is a client on its own connection; the `Tx` token is not that object.
+    txExecutor: () => pgExecutorFor(currentTx() ?? client),
+  });
+  setJobsFacade(
+    createJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),
+  );
+  const events = createPgEventBus({ executor });
+  setEventBus(events);
+  setIdempotencyStore(postgresIdempotencyStore({ executor }));
+  return { db: client, jobs: driver, outbox, events, stop: () => releaseQueue(client, driver) };
 }
 
 /**
- * Release both ambient accessors, then the resources behind them, in that order: a driver reset
+ * Release every ambient accessor, then the resources behind them, in that order: a driver reset
  * after its database is closed leaves a window where `jobDriver()` answers over a dead socket.
  * A stale driver is worse than none — the next command sees one installed and skips queue
  * startup entirely, so every query it makes fails on a connection this process already dropped.
+ *
+ * The facade goes with the driver for the same reason: an enqueue routed through a store bound to
+ * a closed client is a staged row nothing will ever publish.
  */
 async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promise<void> {
+  // 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();
+  resetJobsFacade();
   resetJobDriver();
   setDbClient(undefined);
   await jobs?.close?.();
@@ -87,14 +171,16 @@ async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promi
  * would pay for services it cannot even use. `startServices` builds on this so there is one boot
  * path for "which database" and "which queue", not two.
  */
-export async function startQueue(services: DevServices): Promise<RunningQueue> {
+export async function startQueue(
+  services: DevServices,
+  overrides?: RuntimeOverrides,
+): Promise<RunningQueue> {
   const db = startDb(services);
   try {
     // Pay the Postgres boot here, so the first request is not the slow one and a broken database
     // fails at boot rather than on some later query.
     await db.ping();
-    const jobs = await startJobs(db);
-    return { db, jobs, stop: () => releaseQueue(db, jobs) };
+    return await startJobs(db, overrides);
   } catch (error) {
     // `db.ping()` or `startJobs` is where a broken database is supposed to fail. Without this,
     // the caller exits holding the PGlite lock and the ambient accessors, and nothing is left to

package/src/dev-render.ts

@@ -2,29 +2,55 @@
 // `@ultimat3/render`'s own function for that mode — the CLI picks the mode and supplies the
 // document, it never decides what a mode means or what headers it earns.
 //
-// The document is head + shell. Islands are the compiled client graph's, and there is no
-// compiled graph before `x build`, so a dev page serves its real `<head>`, its real status and
-// its real cache headers around an empty root — never a 404.
+// The document is head + the route's own component, rendered by `@ultimat3/render`'s server JSX
+// writer, with the surface's compiled CSS inlined. Inlined rather than linked because a `site/`
+// page is a 0kb-JS artifact a CDN serves as one file: a stylesheet link would add a round trip to
+// the render path the mode exists to make cheap, and a static export would need a second file.
 
 import type { Ctx } from '@ultimat3/core';
 import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
 import { asCtx, html, stream } from '@ultimat3/http';
-import type { IsrController, RenderResult, RouteEntry } from '@ultimat3/render';
+import { currentLocale } from '@ultimat3/i18n';
+import type {
+  IslandCollector,
+  IsrController,
+  RenderResult,
+  RouteData,
+  RouteEntry,
+} from '@ultimat3/render';
 import {
   contentHash,
+  createIslandCollector,
   createIsrController,
   headFromMeta,
+  hydrateRuntime,
+  metaContextFor,
+  renderComponent,
   renderHead,
   renderSpa,
   renderSsr,
+  routeDataFor,
   routeEntries,
   SPA_ROOT_ID,
   seoRenderers,
   staticHeaders,
   streamResult,
+  stylesFor,
 } from '@ultimat3/render';
 
-export interface DevRenderOptions {
+/**
+ * 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;
+}
+
+export interface DevRenderOptions extends DocumentOptions {
   readonly buildId: string;
   /** Injected so a test can drive the ISR store without a timer. */
   readonly isr?: IsrController;
@@ -36,67 +62,173 @@ export interface DevRouteData extends Record<string, unknown> {
   readonly params: RouteParams;
 }
 
-const LANG = 'en';
+/**
+ * `<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`, wrong for a CDN
+ * keying on `content-language`. Outside a request (`x build`'s prerender) it is the app's own
+ * configured fallback, which is the only defensible answer there.
+ */
+const lang = (): string => currentLocale();
 
-const headFor = async (entry: RouteEntry, data: DevRouteData): Promise<string> =>
+const headFor = async (entry: RouteEntry, ctx: DevRouteData, data: RouteData): Promise<string> =>
   renderHead(
-    headFromMeta(await entry.config.meta(data), seoRenderers({ path: new URL(data.url).pathname })),
+    headFromMeta(
+      await entry.config.meta(metaContextFor(ctx, data)),
+      seoRenderers({ path: new URL(ctx.url).pathname }),
+    ),
+  );
+
+/** `<style>` for the surface's own stylesheets, or nothing at all when the surface imports none. */
+const styleTag = (entry: RouteEntry): string => {
+  const css = stylesFor(entry.surface);
+  return css.length === 0 ? '' : `<style>${css}</style>`;
+};
+
+/**
+ * The route's rendered body, inside the hydration root. A module that exports no component (an
+ * `api/` route, or a `spa` whose data is all client-side) renders an empty root, which is the
+ * shell those modes are defined to serve — not a fallback for a component that failed.
+ */
+export async function routeBody(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  islands: IslandCollector,
+): Promise<string> {
+  if (entry.component === undefined) return `<div id="${SPA_ROOT_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: Object.fromEntries(url.searchParams) as Readonly<Record<string, string>>,
+    },
+    entry.file,
+    { islands },
   );
+  return `<div id="${SPA_ROOT_ID}">${html}</div>`;
+}
+
+/**
+ * One collector per RENDER, never module-global: two requests render different params, and a
+ * shared collector would bill one page for the other's islands. `hydrate` comes off the route, so
+ * an island never declares its own timing, and `resolve` is the build's — identity when nothing
+ * built any, which fails at the first island by name rather than emitting an unusable entry.
+ */
+const collectorFor = (entry: RouteEntry, options: DocumentOptions): IslandCollector =>
+  createIslandCollector({
+    file: entry.file,
+    hydrate: entry.config.hydrate,
+    ...(options.resolveIsland === undefined ? {} : { resolve: options.resolveIsland(entry.file) }),
+  });
 
 /**
- * Head + shell for one route render. Exported because the build's prerenderer must emit the same
+ * Head + body for one route render. Exported because the build's prerenderer must emit the same
  * document `x dev` serves — two document builders is how a page that works in dev ships broken.
  */
-export async function routeDocument(entry: RouteEntry, data: DevRouteData): Promise<string> {
-  return shellFor(await headFor(entry, data));
+export async function routeDocument(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  options: DocumentOptions = {},
+): Promise<string> {
+  return documentFrom(entry, ctx, await routeDataFor(entry.config, ctx), options);
 }
 
-const shellFor = (head: string): string =>
-  `<!doctype html><html lang="${LANG}"><head>${head}</head>` +
-  `<body><div id="${SPA_ROOT_ID}"></div></body></html>`;
+/**
+ * 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 either guess or
+ * ship the whole runtime to a page with no island — the 0kb baseline, spent on nothing.
+ */
+async function documentFrom(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  options: DocumentOptions,
+): Promise<string> {
+  const islands = collectorFor(entry, options);
+  const [head, body] = await Promise.all([
+    headFor(entry, ctx, data),
+    routeBody(entry, ctx, data, islands),
+  ]);
+  return (
+    `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head>` +
+    `<body>${body}${hydrateRuntime(islands.directives)}</body></html>`
+  );
+}
 
 async function resultFor(
   entry: RouteEntry,
-  data: DevRouteData,
+  request: DevRouteData,
   options: DevRenderOptions,
   isr: IsrController,
   ctx: Ctx,
 ): Promise<RenderResult> {
-  const url = new URL(data.url);
+  const url = new URL(request.url);
+  // ONCE per request, before the mode is chosen. Every branch below reads this same object, so a
+  // route's `load` runs exactly once however its mode splits head from body.
+  const data = await routeDataFor(entry.config, request);
   switch (entry.config.render) {
     case 'static': {
       // Not `renderStatic`: that enumerates every prerendered path for the build. A request
       // names exactly one, and it earns the same content-hashed headers.
-      const body = await routeDocument(entry, data);
+      const body = await documentFrom(entry, request, data, options);
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      const served = await isr.serve(url.pathname, () => routeDocument(entry, data));
+      const served = await isr.serve(url.pathname, () =>
+        documentFrom(entry, request, data, options),
+      );
       return served.result;
     }
     case 'spa':
+      // The shell renders no body by definition, but it still carries the surface's CSS: the
+      // client paints into `#x-root` and a flash of unstyled shell is the mode's own regression.
       return renderSpa({
         entry,
         buildId: options.buildId,
-        head: await headFor(entry, data),
+        head: (await headFor(entry, request, data)) + styleTag(entry),
         chunks: [],
-        lang: LANG,
+        lang: lang(),
       });
     case 'stream': {
-      const head = await headFor(entry, data);
+      // The shell IS the component: nothing can yet mark a subtree as a hole. Solid's `Suspense`
+      // is not the missing piece and never will be here — it calls `getContextId()`, which throws
+      // outside a Solid renderer, and this package's JSX factory is inert by design. A hole marker
+      // has to be the framework's own. Until it exists the first flush carries the whole body —
+      // correct output, no streaming benefit.
+      const islands = collectorFor(entry, options);
+      const [head, shell] = await Promise.all([
+        headFor(entry, request, data),
+        routeBody(entry, request, data, islands),
+      ]);
       return streamResult(
         {
-          head: `<!doctype html><html lang="${LANG}"><head>${head}</head><body>`,
-          shell: `<div id="${SPA_ROOT_ID}"></div>`,
+          head: `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head><body>`,
+          // The runtime rides the first flush, with the shell it boots. A later chunk would leave
+          // the window between flush one and the close with inert islands and no listeners on
+          // them — which is exactly the first-click-lost failure `interaction` replay exists for.
+          shell: `${shell}${hydrateRuntime(islands.directives)}`,
           holes: [],
         },
         { buildId: options.buildId },
       );
     }
     default:
-      return renderSsr({ entry, params: data.params, url, ctx }, () => routeDocument(entry, data), {
-        buildId: options.buildId,
-      });
+      return renderSsr(
+        { entry, params: request.params, url, ctx },
+        () => documentFrom(entry, request, data, options),
+        { buildId: options.buildId },
+      );
   }
 }