@ultimat3/cli 27.16.1 → 29.0.0

package/src/i18n-registration.ts

@@ -25,6 +25,7 @@ import { loadApp } from './app-load';
 import type { DuplicateProbe } from './duplicate-packages';
 import { duplicateCause, duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import { auditApp } from './i18n-audit';
+import { localeParityFindings } from './i18n-locale-parity';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { CATALOG_ROOT, catalogPath } from './templates/locales';
@@ -287,6 +288,10 @@ export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
  * Both halves of one question — does every string this app renders resolve? — for a caller that
  * wants the verdict and not the table. `x verify`'s `i18n` step is that caller; `cmd-i18n.ts`
  * composes the same two pieces itself because it also renders per-locale rows.
+ *
+ * The locale parity joins them: a catalog can hold every key source uses and still be wrong in
+ * the two ways only a comparison with the reference locale can see — a slot one side does not
+ * have, and a string nobody translated.
  */
 export async function catalogFindings(root: string): Promise<readonly Finding[]> {
   const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
@@ -294,5 +299,6 @@ export async function catalogFindings(root: string): Promise<readonly Finding[]>
   return [
     ...missingKeyFindings(withPlaceholdersMissing(report, catalogs)),
     ...registration.findings,
+    ...localeParityFindings(catalogs),
   ];
 }

package/src/mcp-errors.ts

@@ -306,6 +306,12 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only boundaries --json   # then move each declaration in X.ts to X/<name>.ts, one primitive per file',
   X_SLICE_POLICY_INCOMPLETE:
     'x policy list --json   # names the slice policy module; add the export lines the thrown fix spells out to it, then run the generator again',
+  X_CATALOG_SLOT_MISMATCH:
+    'x i18n check --json   # the finding names the locale, the key and the slots that differ',
+  X_CATALOG_UNTRANSLATED:
+    'x i18n check --json   # the finding names the locale and the key still carrying the reference value',
+  X_WORKER_QUEUE_UNKNOWN:
+    'x jobs list --json   # set WORKER_QUEUES to queues it lists, or add the queue to jobs.queues in app.config.ts',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -139,6 +139,10 @@ const CATALOG = {
   'cli.i18n.dynamic': '{count} dynamic t() call(s) the extractor cannot verify:',
   'cli.i18n.gaps': '{missing} missing key(s) across {locales} locale(s)',
   'cli.i18n.ok': '{locales} locale(s), {keys} key(s) used — no gaps',
+  // The summary a locale-parity finding needs: `cli.i18n.gaps` counts MISSING KEYS, so it cannot
+  // say "this locale's slots drifted and this string was never translated".
+  'cli.i18n.parity':
+    '{count} locale-parity finding(s) across {locales} locale(s) — a slot or an untranslated copy against {reference}',
   'cli.i18n.synced': 'synced {locale} from {from} — {added} key(s) added, {total} total',
   'cli.i18n.unused': '{count} key(s) defined in {locale} and never used:',
   'cli.jobs.backfillNoCursor': 'no cursor yet',

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,33 +92,30 @@ 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);
@@ -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 }),

package/src/site-config.ts

@@ -1,9 +1,9 @@
-// The public origin and the crawler rules out of `app.config.ts` — `site.origin`,
-// `seo.robots.disallow` and `seo.robots.groups` — and the one resolution of "which origin is this site served on" every
+// The public origin, the app's favicon and the crawler rules out of `app.config.ts` — `site.origin`,
+// `site.favicon`, `seo.robots.disallow` and `seo.robots.groups` — and the one resolution of "which origin is this site served on" every
 // absolute URL a document, a sitemap or a robots file carries is built against. Read off the one
 // loader (`app-config-load.ts`).
 
-import type { Environment, SeoRobotsGroup, SeoSitemapConfig } from '@ultimat3/core';
+import type { Environment, SeoRobotsGroup, SeoSitemapConfig, SiteFavicon } from '@ultimat3/core';
 import { loadAppConfig } from './app-config-load';
 
 export interface SiteSettings {
@@ -18,6 +18,14 @@ export interface SiteSettings {
   readonly robotsGroups?: readonly SeoRobotsGroup[] | undefined;
   /** `seo.sitemap` — public `app/` pages to list, where `<lastmod>` comes from, sections, page size. */
   readonly sitemap: SeoSitemapConfig;
+  /**
+   * `site.favicon` — the app's SVG favicon, named as a site asset path (`assets/brand/icon.svg`).
+   * `undefined` when the app declares none. The boot resolves it ONCE, through the site asset
+   * table (`siteAssetTable(root).resolve(path).url` — the table `/assets/*` serves and `asset()`
+   * answers from), into the content-hashed URL every document carries. Optional so a
+   * `SiteSettings` literal written before it existed still compiles.
+   */
+  readonly favicon?: SiteFavicon | undefined;
 }
 
 export const NO_SITE_SETTINGS: SiteSettings = {
@@ -25,6 +33,7 @@ export const NO_SITE_SETTINGS: SiteSettings = {
   disallow: [],
   robotsGroups: [],
   sitemap: { extra: [], lastmod: 'none', sections: [], pageSize: 50_000 },
+  favicon: undefined,
 };
 
 const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
@@ -32,12 +41,13 @@ const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
 export async function loadSiteSettings(root: string): Promise<SiteSettings> {
   const config = await loadAppConfig(root);
   if (config === undefined) return NO_SITE_SETTINGS;
-  const { origin } = config.site;
+  const { origin, favicon } = config.site;
   return {
     origin: origin === null ? null : trimSlash(origin),
     disallow: [...config.seo.robots.disallow],
     robotsGroups: [...(config.seo.robots.groups ?? [])],
     sitemap: config.seo.sitemap,
+    favicon,
   };
 }
 

package/src/templates/scaffold-container.ts

@@ -32,16 +32,16 @@ const dockerfile = (
 # from the file itself, and without it the frozen install cannot find what the lockfile names.
 # The tag names the series for the reader; the digest is what builds — a tag is a pointer its
 # publisher can move. Dependabot's docker ecosystem moves the digest together with the tag.
-# The digest is \`oven/bun:1.4.2-alpine\`'s, the patch the framework that wrote this file was
+# The digest is \`oven/bun:1.4.4-alpine\`'s, the patch the framework that wrote this file was
 # tested on — the same patch as \`engines.bun\` in package.json.
-FROM oven/bun:1.4-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f AS manifests
+FROM oven/bun:1.4-alpine@sha256:4cf82f5686b196504fe119db3fcd9185b191f82ece82c40680e597228ec6070a AS manifests
 WORKDIR /app
 COPY . .
 RUN find . ! -type d ! -name package.json ! -name bunfig.toml ! -name '*.tgz' -delete \\
  && find . -type d -empty -delete
 
 # ---------- deps: runtime dependencies only, cached on the lockfile and the manifests ----------
-FROM oven/bun:1.4-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f AS deps
+FROM oven/bun:1.4-alpine@sha256:4cf82f5686b196504fe119db3fcd9185b191f82ece82c40680e597228ec6070a AS deps
 WORKDIR /app
 COPY --from=manifests /app ./
 COPY bun.lock ./

package/src/templates/scaffold-repo.ts

@@ -45,11 +45,11 @@ const TYPESCRIPT_VERSION = '^7.0.2';
 
 /**
  * The Solid runtime every island and `@ultimat3/ui` component renders with, exact for the reason
- * `BIOME_VERSION` is: the CLI compiles islands with `babel-preset-solid ^1.9.15`, and a scaffold
+ * `BIOME_VERSION` is: the CLI compiles islands with `babel-preset-solid ^1.9.16`, and a scaffold
  * that installed an older runtime than the compiler targets drifted as a buried literal (1.9.14
  * beside the repository's 1.9.15). `scaffold-repo.test.ts` holds it equal to the root manifest's.
  */
-const SOLID_VERSION = '1.9.15';
+const SOLID_VERSION = '1.9.17';
 
 // `engines.bun` is `REQUIRED_BUN`, the floor the SHIPPED `x` enforces
 // (`packages/cli/src/app-root.ts`), and not a second literal. It was one: `>=1.3.0`, a whole minor