@ultimat3/cli 23.0.0 → 24.0.0

package/src/prerender.ts

@@ -21,6 +21,7 @@ import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';
 import { measureDocumentJs, writeBuildStats } from './budgets';
 import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
+import { PrerenderLoadFailedError } from './errors';
 import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
@@ -168,15 +169,17 @@ const NOT_FOUND_STATUS = 404;
  */
 const declaresBudget = (entry: RouteEntry): boolean => {
   const budget = entry.config.budget;
-  return budget !== undefined && (budget.js !== undefined || budget.lcp !== undefined);
+  return budget?.js !== undefined;
 };
 
 export async function prerenderSite(options: PrerenderOptions): Promise<PrerenderReport> {
-  // The same load `x dev` and `x manifest` perform: importing the app's modules IS what fills the
-  // route registry, so there is no route table to prerender before this runs.
-  // Emptied FIRST: the export only ever gained files, so a deleted route's HTML kept shipping.
+  // The load `x dev` and `x manifest` perform: importing the app's modules fills the route registry.
+  // A module that would not import registered nothing, so its page would vanish from the export
+  // under a green build — refused BEFORE the export is emptied, so the last good artifact survives.
+  const loaded = await loadApp(options.root);
+  if (loaded.findings.length > 0) throw new PrerenderLoadFailedError(loaded.findings);
+  // Emptied before anything is written: a deleted route's HTML kept shipping when it only grew.
   await clearPrerenderOut(options.out, options.root);
-  await loadApp(options.root);
   const buildId = (await appManifest(options.root)).manifest.buildId;
   const declaredOrigin =
     options.origin ?? publicOrigin(process.env, await loadSiteSettings(options.root));

package/src/pwa-artifacts.ts

@@ -15,15 +15,10 @@
 // build behind them — `wiki/PWA-And-Offline.md` says so — and a bad `sw.js` is sticky in a way a
 // manifest is not, so the worker lands behind a real browser check rather than beside this.
 
-// why: Bun exposes no synchronous file-existence primitive, and this read is the same one
-// `app-auth.ts` and `runtime-cache.ts` each make before importing an app's config — a root with no
-// `app.config.ts` is an ordinary answer here (a scratch root, `x build` outside an app).
-import { existsSync } from 'node:fs';
-// why: Bun exposes no path-join primitive, and `APP_CONFIG_FILE` is app-root-relative — the same
-// necessity `favicon.ts` and `runtime-assets.ts` each record for their own root-relative constant.
+// why: Bun exposes no path-join primitive, and the export writes each icon under an out directory.
 import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
-import { localeSegment } from '@ultimat3/core';
+import { escapeHtml, localeSegment } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import {
@@ -34,9 +29,7 @@ import {
 } from '@ultimat3/pwa';
 import type { AssetPath } from '@ultimat3/render';
 import { assetPathProblem } from '@ultimat3/render';
-import { escapeAttribute } from '@ultimat3/seo';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { hasSourceIcon, iconPlan, iconRenderer } from './icon-assets';
 import type { AppLocales } from './pwa-manifest-locales';
 import { appLocales, localeMembers, spellIn } from './pwa-manifest-locales';
@@ -80,47 +73,14 @@ export interface PwaArtifacts {
   /** The `<head>` for a document in `locale` — it links that locale's manifest. */
   headFor(locale: string): string;
   /**
-   * The three `pwa` keys the SERVICE WORKER needs, carried here because this is the one module
-   * that reads an app's config file — `sw-artifacts.ts` needs the route table and the island
-   * bundle as well, and a second `await import` of `app.config.ts` would be a second answer to
-   * "what did this app declare".
+   * The three `pwa` keys the SERVICE WORKER needs, carried here so `sw-artifacts.ts` — which needs
+   * the route table and the island bundle as well — reads them off the same resolved block.
    */
   readonly offline: PwaOfflineConfig;
   readonly backgroundSync: boolean;
   readonly push: boolean;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-const text = (value: unknown): string | undefined =>
-  typeof value === 'string' && value.trim() !== '' ? value : undefined;
-
-/**
- * `colors` read structurally, for `loadSignInPath`'s reason: `defineConfig` returns a plain object
- * and a config resolved through an older core simply has no such key. `validate()` already refused
- * a blank one an `await import` above this line, so anything this rejects is a hand-written config
- * object — and the honest answer for one is no manifest at all, never a colour we invented.
- */
-function colorsOf(value: unknown): PwaColors | undefined {
-  if (!isRecord(value)) return undefined;
-  const light = isRecord(value['light']) ? value['light'] : undefined;
-  const dark = isRecord(value['dark']) ? value['dark'] : undefined;
-  if (light === undefined || dark === undefined) return undefined;
-  const [lt, lb, dt, db] = [
-    text(light['themeColor']),
-    text(light['backgroundColor']),
-    text(dark['themeColor']),
-    text(dark['backgroundColor']),
-  ];
-  if (lt === undefined || lb === undefined || dt === undefined || db === undefined)
-    return undefined;
-  return {
-    light: { themeColor: lt, backgroundColor: lb },
-    dark: { themeColor: dt, backgroundColor: db },
-  };
-}
-
 /** The `pwa` block, as much of it as this file needs, or `undefined` when the app declares none. */
 interface InstallableApp {
   readonly name: string;
@@ -133,60 +93,30 @@ interface InstallableApp {
   readonly push: boolean;
 }
 
-async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return undefined;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return undefined;
-  const pwa = config['pwa'];
-  // `pwa.enabled`, read. Not a truthiness test: `enabled` is the key this whole file exists to
-  // give a reader, and `=== true` is what makes a hand-written `enabled: 'yes'` produce no
-  // manifest rather than one nobody asked for.
-  if (!isRecord(pwa) || pwa['enabled'] !== true) return undefined;
-  const name = text(pwa['name']);
-  const colors = colorsOf(pwa['colors']);
-  if (name === undefined || colors === undefined) return undefined;
-  return {
-    name,
-    colors,
-    block: pwa,
-    locales: appLocales(config),
-    offline: offlineOf(pwa['offline']),
-    ...flags(pwa),
-  };
-}
-
 /**
- * The offline block, read structurally for `colorsOf`'s reason: `defineConfig` refuses
- * `enabled: true` without an absolute `offline.fallback`, but a HAND-WRITTEN config object never
- * passed through it. A missing or relative fallback answers `null`, and `serviceWorkerArtifacts`
- * then emits no worker at all — never a path the framework invented, which offline would be a
- * cached 404 answering every navigation.
+ * `pwa.enabled`, read, off the one loader (`app-config-load.ts`). Core's validator refuses an
+ * enabled block without a name, both colour schemes or an absolute `offline.fallback`, so nothing
+ * here invents a colour or a fallback route; `colors` is optional only in the type.
  */
-function offlineOf(value: unknown): PwaOfflineConfig {
-  const block = isRecord(value) ? value : {};
-  const fallback = text(block['fallback']);
-  const patterns = block['neverCache'];
+async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
+  const config = await loadAppConfig(root);
+  const pwa = config?.pwa;
+  if (config === undefined || pwa === undefined || !pwa.enabled || pwa.colors === undefined) {
+    return undefined;
+  }
   return {
-    fallback: fallback?.startsWith('/') === true ? fallback : null,
-    image: text(block['image']) ?? null,
-    font: text(block['font']) ?? null,
-    neverCache: Array.isArray(patterns)
-      ? patterns.filter((entry): entry is string => typeof entry === 'string')
-      : [],
-    personalPages: block['personalPages'] === 'last-member' ? 'last-member' : 'never',
+    name: pwa.name,
+    colors: pwa.colors,
+    block: { ...pwa },
+    locales: appLocales({ locales: config.locales, defaultLocale: config.defaultLocale }),
+    offline: pwa.offline,
+    backgroundSync: pwa.backgroundSync,
+    push: pwa.push,
   };
 }
 
-/** `=== true` for `enabled`'s reason: a hand-written `backgroundSync: 'yes'` wires nothing. */
-const flags = (pwa: Record<string, unknown>): { backgroundSync: boolean; push: boolean } => ({
-  backgroundSync: pwa['backgroundSync'] === true,
-  push: pwa['push'] === true,
-});
-
 /**
- * Resolved ONCE at boot, like `loadSignInPath` and `loadCacheTiers` and unlike `faviconBytes`:
+ * Resolved ONCE at boot, like `loadSignInPath` and unlike `faviconBytes`: the loader's
  * `await import` caches the module, so re-reading per request would answer the same object at a
  * per-request cost, and the head string has to be available synchronously while a document renders.
  */
@@ -219,7 +149,7 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
       path,
       body: serializeWebManifest(result.manifest),
       head:
-        `<link rel="manifest" href="${escapeAttribute(path)}">` +
+        `<link rel="manifest" href="${escapeHtml(path)}">` +
         renderThemeColorMeta(result.themeColorMeta) +
         (icons === undefined ? '' : appleTouchLinks(icons)),
     };
@@ -244,7 +174,9 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
  * `asset()` does in a page. The site serves an asset ONLY at its hashed URL, and the manifest took
  * `src` verbatim, so an app had to hash its own screenshots to avoid shipping a 404 in the install
  * sheet (notificado.co's `pwa-install.ts`). A missing file is `X_ASSET_MISSING` at boot, never a
- * broken image in an install prompt; any other `src` (absolute, already hashed) passes untouched.
+ * broken image in an install prompt; any other `src` passes untouched — an absolute path outside
+ * `/assets/`, an already hashed one, or a shortcut icon's off-site URL (core screens screenshots and
+ * shortcut urls to absolute paths, not icon sources).
  */
 function withHashedAssets<M extends ReturnType<typeof localeMembers>>(members: M, root: string): M {
   const resolve = (src: string): string => {

package/src/registry.ts

@@ -7,6 +7,7 @@
 // dev server it never started (plan 101 slice 12 d).
 
 import { affectedSpec } from './cmd-affected-spec';
+import { authSpec } from './cmd-auth-spec';
 import { buildSpec } from './cmd-build-spec';
 import { ciSpec } from './cmd-ci-spec';
 import { dbSpec } from './cmd-db-spec';
@@ -85,6 +86,7 @@ export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(deploySpec, async () => (await import('./cmd-deploy')).deployCommand),
   lazy(envSpec, async () => (await import('./cmd-env')).envCommand),
   lazy(secretsSpec, async () => (await import('./cmd-secrets')).secretsCommand),
+  lazy(authSpec, async () => (await import('./cmd-auth')).authCommand),
   lazy(manifestSpec, async () => (await import('./cmd-manifest')).manifestCommand),
   lazy(routesSpec, async () => (await import('./cmd-routes')).routesCommand),
   lazy(actionsSpec, async () => (await import('./cmd-registries')).actionsCommand),

package/src/revalidated-response.ts

@@ -4,6 +4,7 @@
 // name that outlives its bytes is a file no client refreshes for a year.
 
 import type { UltimateRequest } from '@ultimat3/http';
+import { contentHash } from '@ultimat3/render/server';
 import { etagMatches } from './runtime-storage';
 
 /**
@@ -14,8 +15,8 @@ import { etagMatches } from './runtime-storage';
 export const REVALIDATE_CACHE_CONTROL = 'public, max-age=0, must-revalidate';
 
 /**
- * A strong validator from the bytes — xxHash32, the function `contentHash` applies to a document,
- * taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
+ * A strong validator from the bytes — `@ultimat3/render`'s `contentHash`, the function a document's
+ * ETag is, taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
  */
 export function revalidatedResponse(
   request: UltimateRequest,
@@ -25,7 +26,7 @@ export function revalidatedResponse(
   // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
   // `SharedArrayBuffer`, which `Response` does not accept — `runtime-assets.ts`'s rule, verbatim.
   const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : new Uint8Array(body);
-  const etag = `"${Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0')}"`;
+  const etag = `"${contentHash(bytes)}"`;
   const headers = {
     'content-type': contentType,
     'cache-control': REVALIDATE_CACHE_CONTROL,

package/src/role-replicator.ts

@@ -3,6 +3,7 @@
 // a `ROLE=replicator` container starts; the only difference is that this process also runs the
 // roles reading the other end of that transport.
 
+import { registerReadinessCheck } from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { ReplicatorSlotHeldError } from '@ultimat3/realtime';
 import type { Replicator, Transport } from '@ultimat3/realtime/server';
@@ -72,6 +73,18 @@ const noEntitiesRefusal = (): BadFlagError =>
     fix: 'x g entity Post title:text — then x dev --role replicator',
   });
 
+/** The name `/readyz` reports the replicator under. */
+export const REPLICATOR_READINESS_CHECK = 'replicator';
+
+/**
+ * Ready means REPLICATING. A stream that ends is restarted by the replicator itself, and until it
+ * is back `running` is `false`: this process holds no slot and publishes nothing, so it must not be
+ * counted as the database's replicator. Returns the unregister.
+ */
+export function watchReplicatorReadiness(replicator: Pick<Replicator, 'running'>): () => void {
+  return registerReadinessCheck(REPLICATOR_READINESS_CHECK, () => replicator.running);
+}
+
 /**
  * Lock first, feed second. A replicator that opened its slot before losing the lock race would
  * have already consumed WAL the holder is responsible for, and `pg_try_advisory_lock` is the only
@@ -95,11 +108,14 @@ export async function startReplicator(options: StartReplicatorOptions): Promise<
   if (!(await replicator.start())) {
     throw new ReplicatorSlotHeldError({ key: replicatorLockKey(slot) });
   }
+  const unregister = watchReplicatorReadiness(replicator);
   return {
     replicator,
     slot,
     detail: selection.detail,
     async stop() {
+      // First: a replicator being stopped on purpose is not a failing one.
+      unregister();
       await replicator.stop();
     },
   };

package/src/role-start.ts

@@ -7,7 +7,7 @@
 // something every `x dev` in a team should do to the same server by simply starting.
 
 import type { Role } from '@ultimat3/core';
-import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
+import { createContext, isRole, logger, markReady, ROLES } from '@ultimat3/core';
 import type { RateLimitStore, Route, ServerHandle, WebSocketMount } from '@ultimat3/http';
 import {
   configuredAuthenticator,
@@ -28,7 +28,7 @@ import {
 } from '@ultimat3/jobs';
 import type { SyncWs } from '@ultimat3/realtime/server';
 import { errorPageHook } from './error-pages';
-import { BadFlagError, PortInvalidError, RuntimeDriverSplitError } from './errors';
+import { BadFlagError, RuntimeDriverSplitError } from './errors';
 import {
   DEFAULT_METRICS_PORT,
   startMetricsEndpoint,
@@ -49,6 +49,7 @@ import type { RunningServices } from './runtime-services';
 import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
 import { syncConnectSources } from './sync-url';
+import { TrustedProxyHopsInvalidError } from './trusted-hops-error';
 import { DEV_BINDING } from './web-binding';
 
 // Declared beside the option types so `x dev`'s spec reads it without loading this module.
@@ -160,8 +161,8 @@ export function trustedHopsFromEnv(env: Env): number | null {
   const hops = Number(raw);
   // A malformed count is refused rather than defaulted: reading the header at the wrong index is
   // trusting a value the client typed, which is the failure trusting a proxy exists to avoid.
-  if (!Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
-    throw new PortInvalidError({ value: raw, name: 'TRUSTED_PROXY_HOPS' });
+  if (!/^\d+$/.test(raw) || !Number.isInteger(hops) || hops < 1 || hops > MAX_PROXY_HOPS) {
+    throw new TrustedProxyHopsInvalidError({ value: raw });
   }
   return hops;
 }
@@ -406,6 +407,10 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       replicatorHere: replicator !== null,
     });
     started.push(async () => live.stop());
+    // The web server and the sync node mark ready when they bind; a process with neither — a
+    // worker, scheduler or replicator pod — is ready once its roles started, which is what the
+    // scrape port's `/readyz` answers (`metrics-endpoint.ts`). The checks still decide after this.
+    if (server === null && sync === null) markReady();
 
     return {
       roles: selected,

package/src/role-sync.ts

@@ -3,7 +3,7 @@
 // and a listener of its own — and because that file is the boot's index, not its detail.
 
 import { createContext, logger, UltimateError } from '@ultimat3/core';
-import type { WebSocketMount } from '@ultimat3/http';
+import { configuredHttp, type WebSocketMount } from '@ultimat3/http';
 import { listQueries } from '@ultimat3/query';
 import type { SyncNode, SyncWs } from '@ultimat3/realtime/server';
 import {
@@ -120,7 +120,8 @@ export interface PreparedSync {
   readonly mount: WebSocketMount<SyncWs>;
   /**
    * Bind `PORT + 1`, and answer with the same object `startSync` always did. `appUrl` is the web
-   * role's own origin when one runs here, for the line below that names both doors.
+   * role's own origin when one runs here: named in the boot line beside the node's, and — under
+   * `x dev` with an `APP_URL` declared — admitted as a page origin (`devOrigins`).
    */
   listen(appUrl: string | null): Promise<RunningSync>;
   /** Release the node when nothing ever bound it — a `web` role that threw after it was built. */
@@ -176,6 +177,35 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
   return registry;
 }
 
+const healthDetailPeersOf = (
+  peers: readonly string[] | undefined,
+): { readonly healthDetailPeers?: readonly string[] } =>
+  peers === undefined ? {} : { healthDetailPeers: peers };
+
+/**
+ * What `x dev` adds to a DECLARED list: the origin its own web role is serving pages on, under
+ * each loopback spelling a browser may have been pointed at. A declaration is the whole list, and
+ * the scaffold's `.env` declares `APP_URL=http://localhost:3000` — so `x dev --port 4000`, or dev
+ * opened as `127.0.0.1`, was a page on an origin nothing named and every socket was refused.
+ *
+ * Nothing is added to an EMPTY list: an undeclared node admits the origin it was reached on, which
+ * already covers these and a forwarded host besides — and one entry would end that rule. Nothing
+ * is added outside dev either: in a container the declaration is the operator's, and a wrong one
+ * must refuse rather than be papered over by whatever address the process bound.
+ */
+function devOrigins(
+  options: StartRolesOptions,
+  declared: readonly string[],
+  appUrl: string | null,
+): string[] {
+  if (!(options.http ?? DEV_BINDING).dev || appUrl === null || declared.length === 0) return [];
+  const own = new URL(appUrl);
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].map(
+    (host) => `${own.protocol}//${host}:${own.port}`,
+  );
+  return [own.origin, ...loopback].filter((origin) => !declared.includes(origin));
+}
+
 /**
  * The node itself: its hub, its registry, its authenticator and its change subscription. Nothing
  * bound — `listen()` and the `web` role's mount are the two doors, and this is what is behind both.
@@ -195,6 +225,7 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
   // `exp`), or resolves identity from a header the adapter deliberately does not retain.
   const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
   const registry = registerLiveQueries(options);
+  const origins = syncOriginsFrom(options.env);
   const node = createSyncNode({
     hub,
     registry,
@@ -202,9 +233,17 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     buildId: options.buildId,
     sockets,
     ...(authenticate === undefined ? {} : { authenticate }),
-    // The page's origin when it is served on another host than this node; the node's own host is
-    // admitted without it. Anything else is refused before `authenticate` (X_SOCKET_ORIGIN_REFUSED).
-    allowedOrigins: syncOriginsFrom(options.env),
+    // `APP_URL`'s origin, and when one is declared it is the WHOLE list: the origin this node was
+    // reached on is no longer admitted beside it. Undeclared, that origin (and its https spelling
+    // when TLS ended at a proxy) is what is admitted; anything else is refused before
+    // `authenticate` (X_SOCKET_ORIGIN_REFUSED). Held by reference: `listen` adds `x dev`'s own.
+    allowedOrigins: origins,
+    // Dev may keep the reached-on origin beside a declaration and a container may not: `x dev`
+    // binds loopback, so a `Host` reaches it only through a forward its own user set up.
+    ...((options.http ?? DEV_BINDING).dev ? { admitReachedOrigin: true } : {}),
+    // Who this node's OWN `/healthz` and `/readyz` tell the detail to: the app's one declaration,
+    // the same list the web role reads. Unset, the node keeps its default (the box itself).
+    ...healthDetailPeersOf(configuredHttp()?.healthDetailPeers),
     // Tier 1 is presence, and without a registry the node answers a topic subscribe with no member
     // list at all — the KV bucket the transport just created would hold nothing and every `sync`
     // container would run a presence-less protocol. It reads and writes `transport.shared`, so it
@@ -223,7 +262,10 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     // second copy of `/_x/sync` here is the copy that stays behind when it moves.
     mount: { path: node.path, fetch: node.fetch, websocket: node.websocket },
     stop: () => node.stop(),
-    listen: async (appUrl) => await listen(options, node, { registry, hub }, appUrl),
+    listen: async (appUrl) => {
+      origins.push(...devOrigins(options, origins, appUrl));
+      return await listen(options, node, { registry, hub }, appUrl);
+    },
   };
 }
 
@@ -235,27 +277,20 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
  * neighbouring port, and reversing the order would answer a second `x dev` on this checkout with
  * "port 3001 is in use" when the fact worth printing is that 3000 is.
  *
- * Port 0 is NOT passed through to the kernel. It cannot be incremented (`+ 1` would ask for port
- * 1), but the web role has bound by the time this runs and `appUrl` carries the port it got — and
- * `PORT + 1` is the contract every scaffolded `sync-url.ts` computes from and the wiki states. A
- * scratch server (`x shot`, `ui.shot`) always asks for 0, so before this every one of its
- * pictures carried `WebSocket … ERR_CONNECTION_REFUSED` for every live island, on the framework's
- * own account. With no web role to follow, 0 still goes to the kernel. The reported url is the
- * listener's own bound address either way, never a string built from the port that was requested.
+ * Port 0 IS passed through to the kernel, web role or not. A scratch server (`x shot`, `ui.shot`,
+ * a test) asks for 0, and its pages dial `/_x/sync` on their OWN origin — the web role's mount
+ * (`sync-url.ts`) — so nothing computes this listener's port from the web port's. Deriving
+ * `PORT + 1` from the kernel's answer asked for one specific port nobody had checked, and under
+ * load another socket held it: the boot died `X_PORT_IN_USE` (role-realtime.test.ts, 6 of 20 with
+ * 12,000 loopback connections held). The reported url is the listener's own bound address.
  */
-function syncPortFrom(requested: number, appUrl: string | null): number {
-  if (requested !== 0 || appUrl === null) return syncPortFor(requested);
-  const bound = Number(new URL(appUrl).port);
-  return Number.isInteger(bound) && bound > 0 ? syncPortFor(bound) : 0;
-}
-
 async function listen(
   options: StartRolesOptions,
   node: SyncNode,
   feeds: Pick<RunningSync, 'registry' | 'hub'>,
   appUrl: string | null,
 ): Promise<RunningSync> {
-  const port = syncPortFrom(options.port, appUrl);
+  const port = syncPortFor(options.port);
   try {
     // The SAME interface the web role binds, resolved from the same option and the same default.
     // Without this the sync node took Bun's `0.0.0.0` while `x dev`'s web role took `localhost`,

package/src/runtime-assets.ts

@@ -9,7 +9,7 @@ import { probeImage } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
-import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
+import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery, usableWidths } from '@ultimat3/seo';
 import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
 import { isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
 import { faviconRoute } from './favicon';
@@ -29,6 +29,7 @@ import {
 } from './runtime-storage';
 import { siteAssetRoutes } from './site-asset-routes';
 import { siteAssetTable } from './site-assets';
+import { storedObjectHeaders } from './stored-object-headers';
 
 /**
  * Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it.
@@ -58,21 +59,24 @@ const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
  * blast radius and does not close it: 8192 stored objects per source, per format, is amplification
  * a tenant drives with a `for` loop.
  *
- * The set is `DEFAULT_WIDTHS` **plus the source's intrinsic width**, which is exactly what
- * `usableWidths` puts in a `srcset` — clamping to the constant alone would refuse the widest entry
- * of every image whose intrinsic width is not one of the eight, a URL the framework mints itself.
+ * The set is `usableWidths(intrinsic, DEFAULT_WIDTHS)` — the function that writes the `srcset`,
+ * asked rather than restated. A restatement (`DEFAULT_WIDTHS` plus the intrinsic width) disagreed
+ * with it for a source wider than `MAX_IMAGE_WIDTH`, whose widest candidate is the ceiling: that
+ * URL, minted by the framework itself, was decoded on every request and never stored.
  * Anything outside it is still SERVED: this decides what is written, not what is answered, so no
  * caller gains a new 4xx and the disk stops growing on a stranger's key.
  */
 const isMintableWidth = (width: number | undefined, intrinsic: number): boolean =>
-  width === undefined || width === intrinsic || DEFAULT_WIDTHS.includes(width);
+  width === undefined || usableWidths(intrinsic, DEFAULT_WIDTHS).includes(width);
 
 const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint): Response =>
   applyCacheHeaders(
     // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
     // `SharedArrayBuffer`, which `Response` does not accept, and copying is what makes that true
     // by construction rather than by a cast that would only silence it.
-    new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
+    new Response(new Uint8Array(bytes), {
+      headers: { 'content-type': contentType, ...storedObjectHeaders(contentType) },
+    }),
     cache,
   );
 
@@ -174,7 +178,7 @@ export interface AssetRoutesOptions {
   /** App root. The source icon is resolved against it; storage keys never are. */
   readonly root: string;
   readonly storage: Storage;
-  /** Replaces `builtinImageDriver` for `/media/*`. Omitted, core's PNG/JPEG pipeline. */
+  /** Replaces `builtinImageDriver` for `/media/*`. Omitted, core's PNG/JPEG/WebP pipeline. */
   readonly images?: ImageTransformDriver;
   /**
    * `manifest.webmanifest`, resolved at boot by `pwa-artifacts.ts`. Absent when the app declares

package/src/runtime-bindings.ts

@@ -24,10 +24,10 @@ export interface DevServices {
   readonly storage: ServiceBinding;
   readonly stateDir: string;
   /**
-   * The app directory itself, carried rather than re-derived from `stateDir`. A boot that needs to
-   * read the app's own `app.config.ts` — `loadInboxRetention` does — otherwise has to undo the
-   * `join(root, '.x')` above, and a `dirname` that silently disagrees with this file's join is a
-   * path bug nothing would catch.
+   * The app directory itself, carried rather than re-derived from `stateDir`. A boot that needs
+   * to read the app's own `app.config.ts` — `startServices`' `loadAppConfig` does — otherwise has
+   * to undo the `join(root, '.x')` above, and a `dirname` that silently disagrees with this
+   * file's join is a path bug nothing would catch.
    */
   readonly root: string;
 }