@ultimat3/cli 28.0.0 → 29.1.0

package/src/page-navigation.ts

@@ -11,10 +11,14 @@ import type { Ctx, NavigationSurface } from '@ultimat3/core';
 import { CLIENT_NAVIGATION_SCOPE_HEADER } from '@ultimat3/core';
 import type { Route, RouteNavigation, UltimateRequest } from '@ultimat3/http';
 import { locationFor, navigationPurpose, relocate } from '@ultimat3/http';
+import type { Translator } from '@ultimat3/i18n';
 import type { ClientNavigationHead, HeadTag, RouteEntry } from '@ultimat3/render';
 import {
   clientNavigationTags,
   documentCarriesScope,
+  modalRouteList,
+  navigationModeOf,
+  navigationPrefetches,
   RouteNavigationInvalidError,
   routeEntries,
 } from '@ultimat3/render';
@@ -36,6 +40,11 @@ export interface NavigationDocumentHead {
   readonly buildId: string;
   /** `app.config.ts`'s `name`: two apps on one origin (web and admin) are two routers. */
   readonly app: string;
+  /**
+   * Per opted-in surface, its modal routes as `modalRouteList` orders them — what lets a click
+   * open the dialog before the answer. Absent or empty: the documents name none.
+   */
+  readonly modalRoutes?: ReadonlyMap<string, readonly string[]>;
 }
 
 export interface PageNavigation {
@@ -71,7 +80,7 @@ export function assertRouteNavigation(
   entries: readonly RouteEntry[] = routeEntries(),
 ): void {
   for (const entry of entries) {
-    const mode = entry.config.navigation;
+    const mode = navigationModeOf(entry.config.navigation);
     if (mode === undefined || surfaces.some((surface) => surface === entry.surface)) continue;
     throw new RouteNavigationInvalidError(
       `${entry.file} declares navigation: '${mode}', and its surface (${entry.surface}) is not in app.config.ts navigation.client`,
@@ -79,6 +88,28 @@ export function assertRouteNavigation(
   }
 }
 
+/**
+ * Each opted-in surface's modal routes, from the whole table: a page of ANY surface may outrank a
+ * modal pattern on the shared URL space, and the router must not open a frame the server will
+ * answer with that page.
+ */
+export function modalRoutesOf(
+  surfaces: readonly NavigationSurface[],
+  entries: readonly RouteEntry[] = routeEntries(),
+): ReadonlyMap<string, readonly string[]> {
+  return new Map(
+    surfaces.map((surface) => [
+      surface,
+      modalRouteList(
+        entries.map((entry) => ({
+          path: entry.path,
+          modal: entry.surface === surface && navigationModeOf(entry.config.navigation) === 'modal',
+        })),
+      ),
+    ]),
+  );
+}
+
 /**
  * Built at boot, never on the watcher tick — the router is framework code, and a tab that loaded
  * it keeps it across every soft navigation, so a URL that changed per save would be one no tab
@@ -109,6 +140,7 @@ export async function pageNavigation(
       scriptUrl: script.url,
       buildId,
       app: declared.app,
+      modalRoutes: modalRoutesOf(declared.surfaces),
     },
   };
 }
@@ -117,13 +149,25 @@ export async function pageNavigation(
 export const surfaceKey = (head: NavigationDocumentHead, surface: string): string =>
   `${head.app}:${surface}`;
 
-/** The head for one document, or `undefined` when its surface did not opt in. */
+/**
+ * The head for one document, or `undefined` when its surface did not opt in. With `t`, and modal
+ * routes on the surface, it names them and the frame's two words in the document's own locale
+ * (the framework catalog's `ui.close` and `ui.loading`, which an app may override).
+ */
 export function navigationHeadFor(
   head: NavigationDocumentHead | undefined,
   surface: string,
+  t?: Translator,
 ): ClientNavigationHead | undefined {
   if (head === undefined || !head.surfaces.has(surface)) return undefined;
-  return { surface: surfaceKey(head, surface), buildId: head.buildId, scriptUrl: head.scriptUrl };
+  const base = {
+    surface: surfaceKey(head, surface),
+    buildId: head.buildId,
+    scriptUrl: head.scriptUrl,
+  };
+  const routes = head.modalRoutes?.get(surface) ?? [];
+  if (t === undefined || routes.length === 0) return base;
+  return { ...base, modals: { routes, close: t('ui.close'), loading: t('ui.loading') } };
 }
 
 /**
@@ -137,15 +181,15 @@ export function navigationHeadFor(
 export function navigationTagsOf(
   head: NavigationDocumentHead | undefined,
   entry: Pick<RouteEntry, 'surface' | 'config'>,
+  t?: Translator,
 ): readonly HeadTag[] {
-  if (entry.config.navigation === 'document') return [];
-  const tags = navigationHeadFor(head, entry.surface);
+  const mode = navigationModeOf(entry.config.navigation);
+  if (mode === 'document') return [];
+  const tags = navigationHeadFor(head, entry.surface, t);
   if (tags === undefined) return [];
   // A modal says so in its own document: the router shows it over the page beneath, never decided
   // from a link — a redirect's target and a pasted `#/…` address are answered alike.
-  return clientNavigationTags(
-    entry.config.navigation === 'modal' ? { ...tags, modal: true } : tags,
-  );
+  return clientNavigationTags(mode === 'modal' ? { ...tags, modal: true } : tags);
 }
 
 /** `{ navigation }` for `metaOf`'s spread, or nothing. */
@@ -167,10 +211,10 @@ export function routeNavigationOf(
   head: NavigationDocumentHead | undefined,
 ): RouteNavigation | undefined {
   if (head === undefined || !head.surfaces.has(entry.surface)) return undefined;
-  if (entry.config.navigation === 'document') return undefined;
+  if (navigationModeOf(entry.config.navigation) === 'document') return undefined;
   return {
     surface: surfaceKey(head, entry.surface),
-    prefetch: entry.config.navigation === 'prefetch',
+    prefetch: navigationPrefetches(entry.config.navigation),
   };
 }
 

package/src/page-speculation.ts

@@ -12,6 +12,8 @@ import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
 import {
   describePages,
+  navigationModeOf,
+  navigationPrefetches,
   renderHead,
   routeEntries,
   speculationPattern,
@@ -37,8 +39,9 @@ export async function loadSpeculation(root: string): Promise<SpeculationConfig>
  *   no policy, no `no-store`. Such a page ran its `load` at build time, for nobody. An `ssr` page
  *   there has no way to declare that its GET records something (`navigation` is refused on a
  *   surface that did not opt in), so it is never a candidate.
- * - On a client-routed surface: only a page that declared `navigation: 'prefetch'` — the app's own
- *   statement that its GET is a pure read, the same one the router's prefetch obeys.
+ * - On a client-routed surface: only a page that declared `navigation: 'prefetch'` (or a modal
+ *   that declared `prefetch: 'intent'`) — the app's own statement that its GET is a pure read,
+ *   the same one the router's prefetch obeys.
  * - Never an `api/` route, a `navigation: 'document'` page, or an `offline: 'network-only'` one.
  */
 export function speculationCandidate(
@@ -47,8 +50,9 @@ export function speculationCandidate(
   client: ReadonlySet<string>,
 ): boolean {
   if (entry.surface !== 'site' && entry.surface !== 'app') return false;
-  if (entry.config.navigation === 'document' || described.offline === 'network-only') return false;
-  if (client.has(entry.surface)) return entry.config.navigation === 'prefetch';
+  const mode = navigationModeOf(entry.config.navigation);
+  if (mode === 'document' || described.offline === 'network-only') return false;
+  if (client.has(entry.surface)) return navigationPrefetches(entry.config.navigation);
   return (described.mode === 'static' || described.mode === 'isr') && !described.personal;
 }
 

package/src/prerender.ts

@@ -195,6 +195,8 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const theme = themeBoot(await loadThemeMode(options.root));
   // The brand the served process carries, so an exported page and a served one paint alike.
   const brand = await loadThemeBrand(options.root);
+  // The app's own favicon is resolved by the DOCUMENT, per render, from the app root below — the
+  // link the served surfaces emit, so an exported document and a served one carry the same icon.
   // The client router, for the surfaces that opted in: written BEFORE any document names it, for
   // the register's reason below — `measureDocumentJs` weighs it off disk, and it is charged to
   // the route (the interactivity the app asked for), so it must be there to be weighed.
@@ -266,6 +268,9 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // Started on the first route that needs weighing, and released however the loop ends.
   const database = measureDatabase(options.root);
   const documentOptions = {
+    // The app root: the document resolves the app's own favicon from it, per render. `writeSiteAssets`
+    // above copied the icon into the artifact under the same hashed URL this resolves.
+    root: options.root,
     resolveIsland: (file: string) => islands.resolverFor(file),
     realtimeIslands: () => islands.realtime,
     themeHead: theme.head,

package/src/runtime-jobs.ts

@@ -1,10 +1,16 @@
-// The queues a `worker` serves and the slots each gets: `jobs.queues`, `jobs.concurrency` and
-// `jobs.visibilityTimeoutMs` off the app's own `app.config.ts`, and `WORKER_QUEUES` off the
+// The queues a `worker` serves and the slots each gets: `jobs.queues`, `jobs.concurrency`,
+// `jobs.maxInFlight` and `jobs.visibilityTimeoutMs` off the app's own `app.config.ts`, and `WORKER_QUEUES` off the
 // Deployment's env — the one per-Deployment answer, since every Deployment runs the same image and
 // the same config (issues #673, #676).
 
 import type { AppConfig, JobsConcurrency } from '@ultimat3/core';
-import { ConfigInvalidError, logger, renderCauseValue, renderFixShellArg } from '@ultimat3/core';
+import {
+  ConfigInvalidError,
+  logger,
+  renderCauseValue,
+  renderFixShellArg,
+  UltimateError,
+} from '@ultimat3/core';
 import { registeredJobs, type WorkerOptions } from '@ultimat3/jobs';
 import type { Env } from './runtime-bindings';
 
@@ -19,7 +25,14 @@ export interface WorkerConfig {
    * queues registered jobs are enqueued on. `false` is the union `workerQueuesFor` explains.
    */
   readonly exact: boolean;
+  /**
+   * `jobs.queues` as the app configured them, kept when `WORKER_QUEUES` replaced `queues`: with
+   * the registered jobs' queues, the set an exact entry must belong to (`refuseUnknownQueues`).
+   */
+  readonly configured: readonly string[];
   readonly concurrency: JobsConcurrency | undefined;
+  /** `jobs.maxInFlight`: runs across every queue this process serves. Unset: no process cap. */
+  readonly maxInFlight?: number | undefined;
   readonly visibilityTimeoutMs: number | undefined;
 }
 
@@ -27,7 +40,9 @@ export interface WorkerConfig {
 const NO_WORKER_CONFIG: WorkerConfig = Object.freeze({
   queues: [],
   exact: false,
+  configured: [],
   concurrency: undefined,
+  maxInFlight: undefined,
   visibilityTimeoutMs: undefined,
 });
 
@@ -45,7 +60,7 @@ export function workerQueuesFromEnv(env: Env): readonly string[] | undefined {
   if (!names.includes('')) return named;
   throw new ConfigInvalidError({
     cause: `${WORKER_QUEUES_ENV} ${renderCauseValue(raw)} contains an empty queue name — every comma-separated entry must name a queue`,
-    fix: `WORKER_QUEUES=${renderFixShellArg(named.join(','), '<queue>,<queue>')} on this Deployment — or unset WORKER_QUEUES to serve jobs.queues and every registered job's queue`,
+    fix: `WORKER_QUEUES=${renderFixShellArg(named.join(','), '<queue>,<queue>')}   # on this Deployment; or unset WORKER_QUEUES to serve jobs.queues and every registered job's queue`,
     meta: { key: WORKER_QUEUES_ENV },
   });
 }
@@ -58,7 +73,9 @@ export function workerConfigOf(config: AppConfig | undefined, env: Env = {}): Wo
       : {
           queues: config.jobs.queues,
           exact: false,
+          configured: config.jobs.queues,
           concurrency: config.jobs.concurrency,
+          maxInFlight: config.jobs.maxInFlight,
           visibilityTimeoutMs: config.jobs.visibilityTimeoutMs,
         };
   return fromEnv === undefined ? base : { ...base, queues: fromEnv, exact: true };
@@ -97,16 +114,74 @@ function reportUnserved(served: readonly string[], registered: readonly string[]
   });
 }
 
-type WorkerConfigOptions = Pick<WorkerOptions, 'queues' | 'concurrency' | 'visibilityTimeoutMs'>;
+/**
+ * A `WORKER_QUEUES` entry no registered job and no `jobs.queues` entry names. The worker would
+ * claim a queue nothing is enqueued on and leave the real ones waiting while its pod stays Ready —
+ * a 15-minute outage behind a healthy roll (`banks-*`, never expanded, 2026-10-27). Refused at
+ * boot instead, so the new pods crash and a rolling update stalls on the old ones.
+ */
+export class WorkerQueueUnknownError extends UltimateError {
+  constructor(input: {
+    unknown: readonly string[];
+    known: readonly string[];
+    named: readonly string[];
+  }) {
+    const patterns = input.unknown.filter((queue) => /[*?[\]{}]/.test(queue));
+    // A pattern's fix is its expansion over the known queues: the list the author meant to write.
+    const meant = input.named.flatMap((queue) =>
+      patterns.includes(queue)
+        ? input.known.filter((name) => new Bun.Glob(queue).match(name))
+        : input.unknown.includes(queue)
+          ? []
+          : [queue],
+    );
+    const list = [...new Set(meant)].join(',');
+    // Every name through `renderCauseValue`: an env value can carry a newline, and a cause is one line.
+    const names = (queues: readonly string[]) => queues.map((q) => renderCauseValue(q)).join(', ');
+    const pattern =
+      patterns.length === 0
+        ? ''
+        : ` — WORKER_QUEUES is never expanded, so ${names(patterns)} is a literal queue name`;
+    super({
+      code: 'X_WORKER_QUEUE_UNKNOWN',
+      cause: `${WORKER_QUEUES_ENV} names ${names(input.unknown)}, which no registered job is enqueued on and jobs.queues does not list${pattern}; the queues this app knows are ${input.known.length === 0 ? 'none' : names(input.known)}`,
+      // The prose after `#`, so the line pasted into a shell sets the variable and runs nothing.
+      fix: `WORKER_QUEUES=${renderFixShellArg(list === '' ? undefined : list, '<queue>,<queue>')}   # on this Deployment; or add the queue to jobs.queues in app.config.ts when jobs reach it by enqueue({ queue }) alone`,
+      meta: { key: WORKER_QUEUES_ENV, unknown: input.unknown, known: input.known },
+    });
+  }
+}
+
+/**
+ * An exact worker's entries, held to what the app knows: `jobs.queues` plus every registered
+ * job's queue — the union an unset `WORKER_QUEUES` would serve. Thrown, never logged: an info line
+ * is what let the worker run claiming nothing (2026-10-27).
+ */
+function refuseUnknownQueues(
+  named: readonly string[],
+  configured: readonly string[],
+  registered: readonly string[],
+): void {
+  const known = [...new Set([...configured, ...registered])].sort();
+  const unknown = named.filter((queue) => !known.includes(queue));
+  if (unknown.length > 0) throw new WorkerQueueUnknownError({ unknown, known, named });
+}
+
+type WorkerConfigOptions = Pick<
+  WorkerOptions,
+  'queues' | 'concurrency' | 'maxInFlight' | 'visibilityTimeoutMs'
+>;
 
 /**
  * The `jobWorker` options the config supplies, read at START so every job the app registered
- * on import is counted. A key the config leaves unset is omitted, never passed as `undefined`, so
- * the worker's own default applies (`exactOptionalPropertyTypes`).
+ * on import is counted — and an exact entry the app does not know is refused there. A key the
+ * config leaves unset is omitted, never passed as `undefined`, so the worker's own default applies
+ * (`exactOptionalPropertyTypes`).
  */
 export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfigOptions {
   const registered = registeredJobs().map((handle) => handle.queue);
   const exact = config?.exact === true;
+  if (exact) refuseUnknownQueues(config?.queues ?? [], config?.configured ?? [], registered);
   const queues = workerQueuesFor(config?.queues ?? [], registered, exact);
   if (exact) reportUnserved(queues ?? [], registered);
   // Passed as written: `jobWorker` reads a table by own key and runs a queue it does not name at
@@ -115,6 +190,7 @@ export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfig
   return {
     ...(queues === undefined ? {} : { queues }),
     ...(concurrency === undefined ? {} : { concurrency }),
+    ...(config?.maxInFlight === undefined ? {} : { maxInFlight: config.maxInFlight }),
     ...(config?.visibilityTimeoutMs === undefined
       ? {}
       : { visibilityTimeoutMs: config.visibilityTimeoutMs }),

package/src/runtime-render.ts

@@ -6,7 +6,7 @@
 import { actionPathStyle } from '@ultimat3/action';
 import { clientScopeOf } from '@ultimat3/auth';
 import type { Actor, Ctx } from '@ultimat3/core';
-import { CLIENT_SCOPE_HEADER, singleFlight } from '@ultimat3/core';
+import { CLIENT_SCOPE_HEADER, escapeHtml, singleFlight } from '@ultimat3/core';
 import type {
   RouteMeta as HttpRouteMeta,
   RedirectIntent,
@@ -44,6 +44,7 @@ import {
   staticHeaders,
   streamResult,
 } from '@ultimat3/render/server';
+import { loadAppConfig } from './app-config-load';
 import type { DocumentOptions } from './document-options';
 import { routeQuery } from './isr-query-guard';
 import {
@@ -56,13 +57,28 @@ import { bootScript, collectorFor } from './route-islands';
 import { addressedUrl } from './runtime-address';
 import { attachedIsr } from './runtime-isr';
 import { isrOutcome } from './runtime-isr-outcome';
+import { siteAssetTable } from './site-assets';
 import type { StaticResult } from './static-document';
 import { createStaticMemo, staticMemoKey, staticResponse } from './static-document';
 import { styleBundle } from './style-bundle';
 
 export type { DocumentOptions, IslandResolver } from './document-options';
 
-export interface DevRenderOptions extends DocumentOptions {
+/**
+ * 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 };
+
+export interface DevRenderOptions extends RenderOptions {
   readonly buildId: string;
   /**
    * The boot's own controller, attached and released by it (`runtime-isr.ts`). Omitted, one is
@@ -76,38 +92,35 @@ export interface DevRenderOptions extends DocumentOptions {
    */
   readonly memoStatic?: boolean;
 }
-
 /** 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`, 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.
+ * 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.
  */
 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 (`static`, `isr`, ungated `ssr`) carries NO scope
- * tag — absent means "not rendered for anyone", a different answer from `''`, the anonymous page.
+ * one store per principal. A shareable document carries NO scope tag — absent means "not rendered
+ * for anyone", a different answer from `''`, the anonymous page.
  */
 const headFor = async (
   entry: RouteEntry,
   ctx: DevRouteData,
   data: RouteData,
-  options: DocumentOptions,
+  options: RenderOptions,
   scope?: string,
 ): Promise<string> => {
   const meta = metaContextFor(ctx, data);
   const url = new URL(ctx.url);
-  const router = navigationTagsOf(options.navigation, entry);
+  const router = navigationTagsOf(options.navigation, entry, meta.t);
   return (
     renderHead(
       headFromMeta(
@@ -132,7 +145,7 @@ const headFor = async (
           ...router,
           // The page boot rides the scope tag: its whole job — restoring a principal's persisted
           // records and replaying its queued writes — is per principal, and a shareable document
-          // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
+          // (no scope tag) has neither.
           ...(scope === undefined
             ? []
             : [clientScopeTag(scope), ...clientPersistTags(options.persisted?.() ?? [])]),
@@ -142,6 +155,9 @@ const headFor = async (
     (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 ?? ''))
   );
@@ -149,19 +165,17 @@ const headFor = async (
 
 /**
  * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface
- * imports none. Inlined until 2026-09-06: every `app/` document of ai-maxxing then carried the same
- * 156,738-byte `<style>` (92% of it) under `no-store`, re-paid on every navigation.
+ * 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, is what
- * would introduce a flash — never do that here.
+ * 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 — and `appRoutes` is on this
- * package's public surface, called as `appRoutes({ buildId })` by both tracked apps' contract
- * tests. One reader, and it is the same one `styleRoutes` serves from.
+ * 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);
@@ -175,8 +189,7 @@ const stylesFor = (entry: RouteEntry, options: DocumentOptions): string =>
 /**
  * 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, which is why every `spa` route ever declared served
- * `<div id="x-root"></div>` and painted nothing.
+ * that never reached this function, so every `spa` route ever declared served an empty root.
  */
 export async function routeBody(
   entry: RouteEntry,
@@ -204,28 +217,27 @@ export async function routeBody(
 }
 
 /**
- * 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.
+ * Head + body for one route render — the document `x dev` serves, which the build's prerenderer
+ * must emit too.
  */
 export async function routeDocument(
   entry: RouteEntry,
   ctx: DevRouteData,
-  options: DocumentOptions = {},
+  options: RenderOptions = {},
 ): Promise<string> {
   return documentFrom(entry, ctx, await routeDataFor(entry.config, ctx), options);
 }
 
 /**
  * The document a request by `actor` is SERVED: `routeDocument` plus the scope the response would
- * carry, which is what earns the page boot. The build weighs an app/ page through this, because a
- * budget is a promise about what that page's browser downloads — and an unscoped render of a
- * scoped page weighed a runtime chunk it never fetches and no boot it always does (#505).
+ * carry, which is what earns the page boot. The build weighs an app/ page through this — a budget
+ * is a promise about what that page's browser downloads (#505).
  */
 export async function servedDocument(
   entry: RouteEntry,
   ctx: DevRouteData,
   actor: Actor,
-  options: DocumentOptions & { readonly buildId: string },
+  options: RenderOptions & { readonly buildId: string },
 ): Promise<string> {
   const data = await routeDataFor(entry.config, ctx);
   return documentFrom(entry, ctx, data, options, documentScope(entry, options.buildId, actor));
@@ -233,9 +245,8 @@ export async function servedDocument(
 
 /**
  * Whether, and as whom, a mode's response is scoped — ONE decision for the request path and for
- * `servedDocument`. A stream is always `private, no-store`; an ssr page carries the scope exactly
- * when the headers `renderSsr` sends are private (an ungated page is `public, s-maxage`, and a CDN
- * may hand it to anyone); a static or isr document is shareable by construction.
+ * `servedDocument`. A stream is always `private, no-store`; an ssr page carries the scope when the
+ * headers `renderSsr` sends are private; a static or isr document is shareable.
  */
 function documentScope(entry: RouteEntry, buildId: string, actor: Actor): string | undefined {
   switch (entry.config.render) {
@@ -257,14 +268,14 @@ function documentScope(entry: RouteEntry, buildId: string, actor: Actor): string
  * 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.
+ * 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.
  */
 async function documentFrom(
   entry: RouteEntry,
   ctx: DevRouteData,
   data: RouteData,
-  options: DocumentOptions,
+  options: RenderOptions,
   scope?: string,
 ): Promise<string> {
   const islands = collectorFor(entry, options, scope);
@@ -298,11 +309,10 @@ async function resultFor(
       return { status, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'stream': {
-      // 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.
+      // The shell IS the component: nothing can yet mark a subtree as a hole, and Solid's
+      // `Suspense` cannot be the missing piece — it calls `getContextId()`, which throws outside a
+      // Solid renderer. Until a hole marker of the framework's own exists, the first flush carries
+      // the whole body — correct output, no streaming benefit.
       // A stream is always `private, no-store` (`streamResult`), so it always carries the scope.
       const scope = documentScope(entry, options.buildId, ctx.actor);
       const islands = collectorFor(entry, options, scope);
@@ -316,7 +326,7 @@ async function resultFor(
             head: `<!doctype html><html lang="${lang()}"><head>${head}${stylesFor(entry, options)}</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.
+            // them — the first-click-lost failure `interaction` replay exists for.
             shell: `${shell}${bootScript(entry, islands, options, scope)}${hydrateRuntime(islands.directives)}`,
             holes: [],
           },
@@ -345,8 +355,7 @@ async function resultFor(
 
 /**
  * A private document's scope, as a RESPONSE header too: the service worker partitions its offline
- * pages by principal and never parses HTML, so the meta alone cannot reach it. Exactly the
- * documents that carry the scope tag carry this — a shareable one carries neither.
+ * pages by principal and never parses HTML, so the meta alone cannot reach it.
  */
 const withScope = (result: RenderResult, scope: string | undefined): RenderResult =>
   scope === undefined
@@ -355,16 +364,14 @@ const withScope = (result: RenderResult, scope: string | undefined): RenderResul
 
 /**
  * A loader's redirect. No declared `cache` means `private, no-store`: the loader decided it for
- * THIS request (it recorded an open, it checked a token), and the mode's default would offer that
- * decision to a CDN, which would then answer every later request without running the loader. A
- * declared one is the pipeline's to apply, off `meta.cache`, exactly as for any handler.
+ * THIS request, and the mode's default would offer that decision to a CDN, which would then answer
+ * every later request without running the loader.
  */
 function loadRedirect(entry: RouteEntry, to: RedirectIntent): Response {
   const response = redirect(to.location, to.status);
   if (entry.config.cache === undefined) response.headers.set('cache-control', 'private, no-store');
   return response;
 }
-
 const responseOf = (result: RenderResult): Response =>
   typeof result.body === 'string'
     ? html(result.body, { status: result.status, headers: result.headers })
@@ -381,8 +388,7 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
   localeSource: entry.surface === 'site' ? 'path' : 'request',
   ...(entry.config.policy === undefined ? {} : { policy: entry.config.policy.permission }),
   // Projected so the router screens its ages at mount (`assertRouteCache`) and the `cache-headers`
-  // stage applies it to a response that wrote none — a loader's redirect. The rendered document
-  // carries its own header, from `ssrHeaders`, which the stage reviews rather than replaces.
+  // stage applies it to a response that wrote none — a loader's redirect.
   ...(entry.config.cache === undefined
     ? {}
     : { cache: entry.config.cache === 'no-store' ? NO_STORE : entry.config.cache }),
@@ -397,13 +403,9 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
  * handler renders AND the `meta` the pipeline enforces — is read back from the table on every
  * request. `x dev` re-registers a route module when its source changes (`app-load.ts`), and a
  * handler closing over the entry it was built from kept serving the first component after every
- * save — the table had moved and this closure had not. `meta` was the same defect one stage
- * earlier: a snapshot taken here, so a `policy` added in a save was not enforced until a restart
- * while the page behind it was already the new one — the pipeline's `auth` and `authz` stages read
- * `route.meta` per request, and this getter is what makes that read the table's. The path cannot
- * move under a reload (the table derives it from the file, and the file is the reload's key), so
- * the entry captured here is only the fallback for a table cleared under a running server, which
- * only a test does — and then guard and page fall back together.
+ * save. `meta` was the same defect one stage earlier, and this getter is what makes that read the
+ * table's: the pipeline's `auth` and `authz` stages read `route.meta` per request. The path cannot
+ * move under a reload, so the captured entry is only the fallback for a cleared table.
  */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
   const isr = options.isr ?? attachedIsr({ buildId: options.buildId }).isr;

package/src/serve-web.ts

@@ -69,6 +69,9 @@ export async function webSurface(
   // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
   const site = await loadSiteSettings(options.root);
   const origin = publicOrigin(options.env, site);
+  // The app's own favicon is NOT resolved here: the document resolves it, per render, from the app
+  // root below — the same link `x dev` serves, so the tab icon does not change between a laptop
+  // and the image.
   // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
   // Before the service worker, which precaches those scripts.
   const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
@@ -150,6 +153,8 @@ export async function webSurface(
     }),
     ...appRoutes({
       buildId,
+      // The app root: the document resolves the app's own favicon from it, per render.
+      root: options.root,
       resolveIsland: (file) => islands.resolverFor(file),
       realtimeIslands: () => islands.realtime,
       ...(sync.head === undefined ? {} : { sync: sync.head }),