@ultimat3/render 29.4.0 → 30.1.0

package/src/render-html.ts

@@ -11,6 +11,8 @@ import {
   IslandPropsInvalidError,
   PrerenderFailedError,
 } from './errors';
+import type { HoleNode } from './hole';
+import { isHoleNode } from './hole';
 import { renderAttributes, VOID_ELEMENTS } from './html';
 import { emitIslandAttributes, emitIslandProps } from './hydrate';
 import type { IslandNode } from './island';
@@ -19,6 +21,8 @@ import type { IslandCollector } from './island-collector';
 import { islandWithoutCollector } from './island-collector';
 import type { JsxComponent, JsxProps } from './jsx';
 import { isJsxNode } from './jsx';
+import type { StreamHole } from './render-stream';
+import { holeMarker } from './render-stream';
 
 /**
  * The id of the element every document wraps its route component in — one name, because a service
@@ -50,6 +54,48 @@ function assertDepth(depth: number): void {
  */
 export interface RenderHtmlOptions {
   readonly islands?: IslandCollector;
+  /**
+   * Where a `<Hole>` goes instead of being awaited. Only the `stream` branch passes one: every
+   * other render has one flush, so a hole there is its children, inline, and is weighed.
+   */
+  readonly holes?: HoleSink;
+}
+
+/** One render's holes, and the counter their ids come from. Per render, as the collector is. */
+export interface HoleSink {
+  readonly holes: readonly StreamHole[];
+  /** The next id, taken before the walk awaits anything so ids follow the tree. */
+  nextId(): string;
+  add(hole: StreamHole): void;
+  /** Runs a hole's children under its signal: the host's seam for what is ambient inside one. */
+  readonly enter: HoleEnter;
+}
+
+/**
+ * How a host runs a hole's children: given the hole's signal (aborted at its deadline and on a
+ * client disconnect; a hole that settled keeps it un-aborted), in whatever scope it builds. The CLI makes that signal
+ * the ambient one and refuses response headers after the flush; render knows neither.
+ */
+export type HoleEnter = (signal: AbortSignal, run: () => Promise<string>) => Promise<string>;
+
+export interface HoleSinkOptions {
+  readonly enter?: HoleEnter;
+}
+
+export function holeSink(options: HoleSinkOptions = {}): HoleSink {
+  const holes: StreamHole[] = [];
+  let last = 0;
+  return {
+    holes,
+    enter: options.enter ?? ((_signal, run) => run()),
+    nextId() {
+      last += 1;
+      return String(last);
+    },
+    add(hole) {
+      holes.push(hole);
+    },
+  };
 }
 
 /**
@@ -69,6 +115,7 @@ async function unwrap(value: unknown, depth: number, walk: RenderHtmlOptions): P
   // configured `JSX.Element` admits — so the generic branch would render its empty contents and
   // drop the island, its props script and its budget line without a word.
   if (isIslandNode(value)) return renderIsland(value, depth, walk);
+  if (isHoleNode(value)) return renderHole(value, depth, walk);
   if (Array.isArray(value)) {
     const parts = await Promise.all(value.map((item) => unwrap(item, depth + 1, walk)));
     return parts.join('');
@@ -118,6 +165,54 @@ async function renderIsland(
   return `<${tag} ${emitIslandAttributes(directive)}>${shell}${emitIslandProps(directive)}</${tag}>`;
 }
 
+/**
+ * A promise already running when the tree was built is awaited only once the stream starts, after
+ * the fallback rendered; a rejection before then is unhandled. Marked through arrays and JSX
+ * children — never by calling a thunk or a component, which have not run — and the hole still
+ * awaits and sees it. `seen` stops a self-referencing array.
+ */
+function observeEagerPromises(value: unknown, seen: Set<object>): void {
+  if (value instanceof Promise) {
+    value.catch(() => undefined);
+    return;
+  }
+  if (typeof value !== 'object' || value === null || seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) for (const item of value) observeEagerPromises(item, seen);
+  // An island or hole node is an array whose own items are empty: its tree is in `props`.
+  if (isJsxNode(value) || isIslandNode(value) || isHoleNode(value)) {
+    const props = value.props as { children?: unknown; fallback?: unknown; error?: unknown };
+    observeEagerPromises(props.children, seen);
+    observeEagerPromises(props.fallback, seen);
+    observeEagerPromises(props.error, seen);
+  }
+}
+
+/**
+ * Everything under a hole walks with no sink: a nested hole is inline inside the outer one, since
+ * the set of pending holes is fixed at the first flush (`renderStreamHtml`). `resolve` is a thunk,
+ * so `children` start inside `start()`, in the request's async context, after the shell is out.
+ */
+async function renderHole(node: HoleNode, depth: number, walk: RenderHtmlOptions): Promise<string> {
+  const sink = walk.holes;
+  const inner: RenderHtmlOptions = walk.islands === undefined ? {} : { islands: walk.islands };
+  const { children, error, fallback } = node.props;
+  if (sink === undefined) return unwrap(children, depth + 1, inner);
+  const id = sink.nextId();
+  observeEagerPromises(children, new Set());
+  const [shown, failed] = await Promise.all([
+    unwrap(fallback, depth + 1, inner),
+    error === undefined ? undefined : unwrap(error, depth + 1, inner),
+  ]);
+  sink.add({
+    id,
+    fallback: shown,
+    ...(failed === undefined ? {} : { error: failed }),
+    resolve: (signal) => sink.enter(signal, () => unwrap(children, depth + 1, inner)),
+  });
+  return holeMarker(id, shown);
+}
+
 async function renderNode(
   type: string | JsxComponent,
   props: JsxProps,

package/src/render-isr-key.ts

@@ -15,17 +15,23 @@ import { unlocalizedPath } from '@ultimat3/i18n';
  */
 export const ISR_LOCALE_PARAM = '__x_locale';
 
+/**
+ * The reserved parameter a request's origin rides in when the app declares none, a parameter for
+ * the same reason: canonical and `og:url` are absolute against that origin, so a foreign `Host` is
+ * its own entry and never names itself in the page a later visitor is answered. Beside the locale,
+ * as `static-document.ts`'s memo keys. `RESERVED_QUERY_PREFIX` stops a route declaring it.
+ */
+export const ISR_ORIGIN_PARAM = '__x_origin';
+
 /**
  * The URL an `isr` route is rendered FOR: the request's, keeping only the query parameters the
  * route declared in `revalidate.query`, one value each, in sorted order.
  *
- * Undeclared (`null`), the key carries the whole query, so `/blog?x=1`, `/blog?x=2`, … are each a
- * miss, a render and a stored entry: any visitor can make an `isr` route render on demand and push
- * real pages out of the bounded store, and `utm_*` / `fbclid` / `gclid` split one page into as
- * many entries as there are campaigns — each of which a withdrawal then has to reach. An `isr`
- * document is a shared artifact, so what it may vary on is the route's to declare, never the
- * visitor's to choose. `null` is kept only because flipping it changes what a page that reads an
- * undeclared parameter renders, and that waits for a major; `query: []` is the safe declaration.
+ * Undeclared (`null`) is none, the same as `query: []`. An `isr` document is a shared artifact, so
+ * what it may vary on is the route's to declare, never the visitor's to choose: a key carrying the
+ * whole query made `/blog?x=1`, `/blog?x=2`, … each a miss, a render and a stored entry, so any
+ * visitor could make a route render on demand and push real pages out of the bounded store, and
+ * `utm_*` / `fbclid` / `gclid` split one page into as many entries as there are campaigns.
  *
  * The SAME narrowed URL is what `load`, `meta` and the page are given (`data.url`, `props.query`),
  * so a parameter that is not in the key cannot change the document stored under it. Nothing is
@@ -33,9 +39,8 @@ export const ISR_LOCALE_PARAM = '__x_locale';
  * A repeated parameter keeps its FIRST value — `?p=1&p=2` and `?p=1&p=3` are one entry, not two.
  */
 export function isrRequestUrl(url: URL, query: readonly string[] | null): URL {
-  if (query === null) return url;
   const kept = new URLSearchParams();
-  for (const name of [...new Set(query)].sort()) {
+  for (const name of [...new Set(query ?? [])].sort()) {
     const value = url.searchParams.get(name);
     if (value !== null) kept.set(name, value);
   }
@@ -46,8 +51,8 @@ export function isrRequestUrl(url: URL, query: readonly string[] | null): URL {
 }
 
 /**
- * The request's parameter names the route did not declare: what `isrRequestUrl` drops — or, for a
- * route that declared nothing (`null`), what a visitor just used to mint a stored page.
+ * The request's parameter names the route did not declare (`null` declares none): what
+ * `isrRequestUrl` drops.
  */
 export function undeclaredQuery(url: URL, query: readonly string[] | null): readonly string[] {
   const declared = new Set(query ?? []);
@@ -75,10 +80,16 @@ export function undeclaredQuery(url: URL, query: readonly string[] | null): read
  * visitor 1 — for the whole TTL, and with `s-maxage` telling the CDN to do the same. The time zone
  * is deliberately NOT a dimension: it is unbounded where a locale set is declared, and an `isr`
  * page is a shared artifact, so a date on one belongs in an explicit zone the page itself names.
+ *
+ * `origin` is the caller's when the app declares no public origin, so the document's absolute URLs
+ * are the request's own (`ISR_ORIGIN_PARAM`). Added here, after `isrRequestUrl` narrowed, so neither
+ * `revalidate.query` nor its default can drop it; omitted, the request cannot supply it either.
  */
-export function isrKey(url: URL, locale: string): string {
+export function isrKey(url: URL, locale: string, origin?: string): string {
   const params = new URLSearchParams(url.search);
   params.set(ISR_LOCALE_PARAM, locale);
+  if (origin === undefined) params.delete(ISR_ORIGIN_PARAM);
+  else params.set(ISR_ORIGIN_PARAM, origin);
   params.sort();
   return `${canonicalPath(url.pathname)}?${params.toString()}`;
 }

package/src/render-stream.ts

@@ -1,17 +1,25 @@
 /**
  * `stream` — the default for `app/` pages. A genuinely static shell is flushed on the
- * first tick; every `<Suspense>` boundary becomes a hole that is filled out of order, in
+ * first tick; every `<Hole>` becomes a slot that is filled out of order, in
  * completion order, as its data resolves.
  *
  * Why the shell is free here: Solid compiles templates to DOM operations and tracks
  * updates with signals, so there is no VDOM tree to replay and no hydration pass over the
  * shell. A resolved hole patches the exact nodes bound to it; the surrounding markup is
  * never re-executed. In a VDOM framework a streamed shell still pays to hydrate the whole
- * tree, which buys TTFB but not TBT — here it buys both, so a `<Suspense>` boundary that
+ * tree, which buys TTFB but not TBT — here it buys both, so a `<Hole>` that
  * contains no interactive island costs literally zero JS.
  */
 
-import { BUILD_ID_HEADER, escapeHtml, finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import {
+  BUILD_ID_HEADER,
+  escapeHtml,
+  finiteCount,
+  logger,
+  renderThrowable,
+  reportError,
+  UltimateError,
+} from '@ultimat3/core';
 import { finiteStatus } from './finite-status';
 import type { RenderResult } from './route';
 import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
@@ -19,8 +27,15 @@ import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
 export interface StreamHole {
   /** Stable within a response; becomes the DOM id, so keep it short. */
   readonly id: string;
-  /** Rendered synchronously into the first flush (the `<Suspense fallback>`). */
+  /** Rendered synchronously into the first flush (`<Hole fallback>`). */
   readonly fallback: string;
+  /** This hole's own markup when it rejects or misses its deadline (`<Hole error>`). */
+  readonly error?: string;
+  /**
+   * Scripts for the chunk, after its `$X()`: asked once `resolve` answered, so it can see what the
+   * hole's render recorded (a hole's island needs a runtime the first flush could not know of).
+   */
+  readonly after?: (outcome: 'filled' | 'failed') => string;
   /**
    * `signal` aborts when the response is cancelled — a client that disconnected mid-stream. A
    * hole that ignores it still finishes; it just finishes into a document nobody reads.
@@ -62,12 +77,12 @@ export function holeMarker(id: string, fallback: string): string {
  */
 export const REVEAL_SCRIPT = `<script>${REVEAL_BODY}</script>`;
 
-export function revealChunk(id: string, html: string): string {
+export function revealChunk(id: string, html: string, after = ''): string {
   // The id reaches markup ONLY through `escapeHtml` — never a script — so a quote in it
   // cannot close anything, and no per-hole body exists for a CSP to fail to list.
   return (
     `<template data-x-hole="${escapeHtml(holeId(id))}">${html}</template>` +
-    `<script>${REVEAL_CALL}</script>`
+    `<script>${REVEAL_CALL}</script>${after}`
   );
 }
 
@@ -90,8 +105,22 @@ export interface StreamOptions {
    * its own timeout, never the default, because "forever" is not a deadline anyone chose.
    */
   readonly holeTimeoutMs?: number | null;
+  /**
+   * While a hole is open, an empty comment every this many ms. Nothing else is written while a hole
+   * waits, and Bun closes a socket idle for `idleTimeout` — `@ultimat3/http` derives it from
+   * `requestTimeoutMs` (+2 s), so a 1 s deadline cut a 6 s hole at 3 s with no `</html>`. A write
+   * resets Bun's idle timer (measured, Bun 1.4.4); clamping the hole deadline instead would cut a
+   * legitimately slow hole, and render cannot see the socket's timeout to clamp to.
+   */
+  readonly keepAliveMs?: number;
 }
 
+/** Under the shortest `idleTimeout` `@ultimat3/http` derives: `ceil(requestTimeoutMs / 1000) + 2` ≥ 3 s. */
+export const DEFAULT_STREAM_KEEPALIVE_MS = 1_000;
+
+/** The keep-alive write: a comment, inert wherever the parser is between two chunks. */
+export const STREAM_KEEPALIVE_CHUNK = '<!---->';
+
 /**
  * `null` is the declared "this hole owns its own timeout" opt-out; every other value is a
  * deadline, and a deadline of 0 is not one — `setTimeout(fn, 0)` fires on the next tick and the
@@ -104,6 +133,40 @@ const declaredTimeoutMs = (declared: number | null | undefined): number | null =
       ? null
       : finiteCount('renderStreamHtml', 'holeTimeoutMs', declared, 1);
 
+/**
+ * A hole's `resolve`, its synchronous throw included. `StreamHole` is public, so nothing makes it an
+ * async function, and one that throws before returning a promise threw out of `renderStreamHtml`
+ * with no byte sent. Called here and now, not a microtask later: every hole starts as the stream does.
+ */
+const startHole = (hole: StreamHole, signal: AbortSignal): Promise<string> => {
+  try {
+    return Promise.resolve(hole.resolve(signal));
+  } catch (error) {
+    return Promise.reject(error);
+  }
+};
+
+/** A hole's `after`, which is app-shaped code too: a throw there costs the scripts, never the reveal. */
+const afterOf = (hole: StreamHole, outcome: 'filled' | 'failed'): string => {
+  try {
+    return hole.after?.(outcome) ?? '';
+  } catch (error) {
+    logger.warn('render.stream.hole_after_failed', {
+      hole: hole.id,
+      error: renderThrowable(error),
+    });
+    return '';
+  }
+};
+
+/** What a monitor hears when a hole misses its deadline: the visitor got the error markup. */
+const holeDeadlineMissed = (id: string, timeoutMs: number): UltimateError =>
+  new UltimateError({
+    code: 'X_TIMEOUT',
+    cause: `stream hole ${id} did not settle within ${timeoutMs} ms, so its error markup was shown`,
+    fix: 'fetch(url, { signal: AbortSignal.timeout(5_000) }) — bound the read under the <Hole>',
+  });
+
 /**
  * Flush order is completion order, not declaration order — a fast hole never waits behind
  * a slow one. The stream closes only after every hole has settled, so a rejected boundary
@@ -122,6 +185,12 @@ export function renderStreamHtml(
   // is `setTimeout(fn, 0)`, so every hole would miss a deadline nobody set and the document would
   // be all fallbacks. `null` is the declared opt-out; there is no spelling that means "immediately".
   const timeoutMs = declaredTimeoutMs(options.holeTimeoutMs);
+  const keepAliveMs = finiteCount(
+    'renderStreamHtml',
+    'keepAliveMs',
+    options.keepAliveMs ?? DEFAULT_STREAM_KEEPALIVE_MS,
+    1,
+  );
   /**
    * The response's own lifetime. A client that disconnects mid-stream cancels the stream, and
    * both halves of that have to be honoured: nothing more may be enqueued — `settle`'s
@@ -131,6 +200,7 @@ export function renderStreamHtml(
    */
   const holes = new AbortController();
   let closed = false;
+  let keepAlive: ReturnType<typeof setInterval> | undefined;
 
   return new ReadableStream<Uint8Array>({
     start(controller) {
@@ -144,6 +214,7 @@ export function renderStreamHtml(
       const close = (): void => {
         if (closed) return;
         closed = true;
+        clearInterval(keepAlive);
         controller.close();
       };
 
@@ -157,6 +228,9 @@ export function renderStreamHtml(
         return;
       }
 
+      keepAlive = setInterval(() => write(STREAM_KEEPALIVE_CHUNK), keepAliveMs);
+      keepAlive.unref?.();
+
       const settle = (): void => {
         pending -= 1;
         if (pending === 0) {
@@ -170,46 +244,65 @@ export function renderStreamHtml(
         // its rejection, or its deadline. A late resolve after the deadline writes nothing —
         // the placeholder it would fill was replaced by the fallback and the document is closed.
         let revealed = false;
-        const reveal = (html: string): void => {
+        // The hole's own lifetime: the response's, cut short by its deadline. The document closes
+        // only once every hole settled or missed its deadline, so nothing is left to stop at close,
+        // and a hole that finished keeps an un-aborted signal (`render-stream.test.ts` pins it).
+        const own = new AbortController();
+        const signal = AbortSignal.any([holes.signal, own.signal]);
+        const reveal = (html: string, after = ''): void => {
           if (revealed) return;
           revealed = true;
           if (timer !== undefined) clearTimeout(timer);
-          write(revealChunk(hole.id, html));
+          write(revealChunk(hole.id, html, after));
           settle();
         };
+        const failed = (): string => hole.error ?? errorFallback(hole.id);
         const timer =
           timeoutMs === null
             ? undefined
             : setTimeout(() => {
                 logger.warn('render.stream.hole_deadline', { hole: hole.id, timeoutMs });
-                reveal(errorFallback(hole.id));
+                const missed = holeDeadlineMissed(hole.id, timeoutMs);
+                // A client that left is nobody's fault: the abort below stopped the work on purpose.
+                if (!signal.aborted) reportError(missed, { source: 'http' });
+                own.abort(missed);
+                // `after` on every path: the error markup may carry an island of its own.
+                reveal(failed(), afterOf(hole, 'failed'));
               }, timeoutMs);
         // A response nobody is reading must not hold the process open until its deadline.
         timer?.unref?.();
 
-        void hole.resolve(holes.signal).then(
-          (html) => {
-            reveal(html);
-          },
-          (error: unknown) => {
-            // `renderThrowable`, never `.message`/`String()`: the value is whatever the hole threw,
-            // and a read that raises here skips the `reveal` below — the hole never fills and the
-            // response is held to its deadline for a failure that was already handled.
-            // A FIELD, never the message: `logger` redacts fields and never `msg`, so a hole's
-            // failure text interpolated into the message reached the log past every redactor.
-            logger.warn('render.stream.hole_rejected', {
-              hole: hole.id,
-              error: renderThrowable(error),
-            });
-            reveal(errorFallback(hole.id));
-          },
-        );
+        // `after` inside the chain: a throw there is this hole's failure, never an unhandled
+        // rejection that holds the document to its deadline.
+        void startHole(hole, signal)
+          // Asked only for a reveal that will write: a hole past its deadline already answered.
+          .then((html) => ({ html, after: revealed || closed ? '' : afterOf(hole, 'filled') }))
+          .then(
+            ({ html, after }) => {
+              reveal(html, after);
+            },
+            (error: unknown) => {
+              // `renderThrowable`, never `.message`/`String()`: the value is whatever the hole threw,
+              // and a read that raises here skips the `reveal` below — the hole never fills and the
+              // response is held to its deadline for a failure that was already handled.
+              // A FIELD, never the message: `logger` redacts fields and never `msg`, so a hole's
+              // failure text interpolated into the message reached the log past every redactor.
+              logger.warn('render.stream.hole_rejected', {
+                hole: hole.id,
+                error: renderThrowable(error),
+              });
+              // Aborted means its deadline or the client already answered for it.
+              if (!signal.aborted) reportError(error, { source: 'http' });
+              reveal(failed(), afterOf(hole, 'failed'));
+            },
+          );
       }
     },
 
     /** The client went away. Stop enqueueing, and stop the work that was going to be enqueued. */
     cancel(reason: unknown) {
       closed = true;
+      clearInterval(keepAlive);
       holes.abort(reason);
     },
   });

package/src/route-status.ts

@@ -1,6 +1,6 @@
 // The one way a loader answers a response STATUS while still rendering the route's own page.
 //
-// Measured in ai-maxxing, 2026-09-07: `/fleet/nope` — a host id the fleet does not have — rendered
+// Measured in one adopter, 2026-09-07: `/fleet/nope` — a host id the fleet does not have — rendered
 // the app's own "Not found" page inside its shell, the right page, and answered **200**. The only
 // route to a 404 was throwing, and a throw renders the framework's error page OUTSIDE the shell.
 // So an app that did the right thing for its visitor could not do the right thing for a crawler,

package/src/route.ts

@@ -78,8 +78,7 @@ export interface RevalidateConfig {
    * The query parameters this page varies on. ONLY these are part of the stored page's key and
    * of the `url` / `query` that `load`, `meta` and the page are given; every other parameter is
    * dropped before either, so `?utm_source=…` is the same stored page and no visitor can mint one.
-   * `[]` is "none", and what most pages want. OMITTED, the key is the whole query string — any
-   * visitor can then mint stored pages (`x verify` says so) — until the next major makes it `[]`.
+   * OMITTED is `[]`, none: list every parameter the page reads (`x verify` warns on one it can see).
    */
   readonly query?: readonly string[];
 }

package/src/sass-cache.ts

@@ -1,7 +1,7 @@
 // A content-addressed disk cache for one Sass compilation: keyed by the compiler, the file and its
 // source, and valid only while every file that compilation READ still hashes the same. Sass has no
 // cache across compilations, so every `.module.scss` re-parses `@ultimat3/ui/tokens` — measured on
-// notificado.co (140 modules), 3.7 s wall and 12 s CPU of `x manifest --check`'s 6.5 s wall.
+// one adopter's app (140 modules), 3.7 s wall and 12 s CPU of `x manifest --check`'s 6.5 s wall.
 
 // why: `compileStylesheet` is synchronous — Bun's loader `onLoad` path calls it inline — and Bun
 // ships no synchronous file read, write or rename; `node:fs` is the only sync file API.

package/src/server.ts

@@ -38,8 +38,8 @@ export {
 } from './module-loader';
 export { enumeratePrerenderEntries } from './prerender-enumerate';
 // ---- the render pipeline: one entry point per mode ----------------------------------------------
-export type { RenderHtmlOptions } from './render-html';
-export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
+export type { HoleEnter, HoleSink, HoleSinkOptions, RenderHtmlOptions } from './render-html';
+export { holeSink, ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
 export {
   DEFAULT_ISR_REGENERATE_DEADLINE_MS,
   invalidateAndRevalidate,
@@ -80,11 +80,13 @@ export type { StreamHole, StreamOptions, StreamPlan } from './render-stream';
 export {
   collectStream,
   DEFAULT_HOLE_TIMEOUT_MS,
+  DEFAULT_STREAM_KEEPALIVE_MS,
   holeId,
   holeMarker,
   REVEAL_SCRIPT,
   renderStreamHtml,
   revealChunk,
+  STREAM_KEEPALIVE_CHUNK,
   streamResult,
 } from './render-stream';
 // ---- the Sass compile cache: where it lives, and how often this process ran Sass instead --------

package/src/type-pins.tsx

@@ -8,6 +8,7 @@
 // apps, so the `<ContactSales />` below is checked against the SAME `JSX.Element` a page is —
 // which is the only way a regression to `IslandNode` fails a build rather than a reader's review.
 
+import { Hole } from './hole';
 import type { IslandComponent } from './island';
 import { island } from './island';
 import type { JsonValue } from './island-props';
@@ -126,3 +127,10 @@ type UnprojectedBudgetKey = Exclude<keyof RouteBudget, BudgetKeyOf<keyof RouteDe
 export type _EveryBudgetKeyIsProjected = Assert<
   [UnprojectedBudgetKey] extends [never] ? true : false
 >;
+
+/** `<Hole>` is an ordinary JSX component, and its children are a thunk: `unknown`, as a shell's are. */
+export const _HoleIsJsx = (): unknown => (
+  <Hole fallback={<p>waiting</p>} error={<p>failed</p>}>
+    {async () => <p>filled</p>}
+  </Hole>
+);

package/src/zone-script.ts

@@ -0,0 +1,38 @@
+// The detected-zone script: one inline cookie write from `Intl`'s own zone, on `app/` documents
+// only (never `site/`, axiom 6), so a document navigation — which sends no `x-timezone` — still
+// tells the next request where the visitor is. The first paint stays the default; the second is right.
+
+import { serializeSetCookie } from '@ultimat3/core';
+import { DEFAULT_TZ_CONFIG } from '@ultimat3/http';
+import type { HeadTag } from './head';
+
+/** A script past this is no longer "one cookie write"; the test holds the body under it. */
+export const ZONE_SCRIPT_MAX_BYTES = 200;
+
+/** A year: the zone a device is in changes rarely, and every load rewrites it anyway. */
+const MAX_AGE_SECONDS = 31_536_000;
+
+/**
+ * The body alone, so the CSP hash and the tag come from one string (`themeScriptBody`'s rule).
+ * The name is `@ultimat3/http`'s `detectedCookie` — the one `resolvePreferences` reads, ranked
+ * below the chosen cookie — and never the chosen one: a guess written there would erase a pick.
+ * The attributes are core's one serializer's, split around an empty value the browser fills with
+ * the zone: `httpOnly: false` because a script writes it, and an IANA name is all cookie octets.
+ */
+export function zoneScriptBody(): string {
+  const line = serializeSetCookie(DEFAULT_TZ_CONFIG.detectedCookie, '', {
+    maxAge: MAX_AGE_SECONDS,
+    httpOnly: false,
+  });
+  const at = line.indexOf(';');
+  return (
+    `try{document.cookie=${JSON.stringify(line.slice(0, at))}+` +
+    'Intl.DateTimeFormat().resolvedOptions().timeZone+' +
+    `${JSON.stringify(line.slice(at))}}catch(e){}`
+  );
+}
+
+/** As a `HeadTag`, deduped by its key like the theme flip. */
+export function zoneScript(): HeadTag {
+  return { kind: 'script', key: 'script:zone', content: zoneScriptBody() };
+}