@ultimat3/cli 23.0.0 → 25.0.0

package/src/role-sync.ts

@@ -2,25 +2,35 @@
 // Split from `role-start.ts` because it is the one role with an authenticator, a presence registry
 // 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 { ctxOf, logger, type RealtimeConfig, UltimateError } from '@ultimat3/core';
+import {
+  clientAddress,
+  configuredHttp,
+  defineHttpConfig,
+  mergeHttpConfig,
+  type WebSocketMount,
+} from '@ultimat3/http';
 import { listQueries } from '@ultimat3/query';
 import type { SyncNode, SyncWs } from '@ultimat3/realtime/server';
 import {
   ChannelHub,
-  createSyncNode,
   LiveQueryRegistry,
   listenSyncNode,
   liveQueryDefinition,
   PresenceRegistry,
   RingChangeBuffer,
   SocketRegistry,
+  syncNode,
 } from '@ultimat3/realtime/server';
 import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
 import type { StartRolesOptions } from './role-start';
+import type { Env } from './runtime-bindings';
 import { syncAuthenticator } from './sync-authenticator';
 import { syncOriginsFrom } from './sync-url';
+// A value edge back into `role-start.ts`, read only inside a call: the one parser of
+// `TRUSTED_PROXY_HOPS`, never a second copy of it.
+import { trustedHopsFromEnv } from './trusted-hops';
 import { DEV_BINDING } from './web-binding';
 
 /**
@@ -120,7 +130,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. */
@@ -153,18 +164,26 @@ export interface RunningSync {
  * close. And no default is defensible: one tenant is a single person and the next is five
  * thousand seats, so any number here is either unreachable or an outage on a Monday morning. The
  * per-socket 128 stands because a socket is one browser tab, which is a bound the framework can
- * actually know. A deployment that wants the tenant cap passes both:
+ * actually know, and so does the per-ACTOR 1,000 (`realtime.maxSubscriptionsPerActor`): one
+ * principal's share is knowable where a tenant's is not. A deployment that wants the tenant cap
+ * passes both:
  *
  *   new LiveQueryRegistry({ …, maxPerTenant: 5_000, tenantOf: (actor) => actor?.orgId ?? null })
  */
 export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegistry {
+  // `?.` because a caller that builds only the registry (`role-sync-resume.test.ts`) hands no
+  // runtime; unset is the registry's own `DEFAULT_MAX_PER_ACTOR`, which is what core leaves it.
+  const maxPerActor = options.runtime?.realtime?.maxSubscriptionsPerActor;
   const registry = new LiveQueryRegistry({
     source: new RingChangeBuffer(),
+    // One actor's — or one anonymous address's — share of this node's live queries, from the app's
+    // `realtime.maxSubscriptionsPerActor`. Without it 79 sockets of one actor filled the node.
+    ...(maxPerActor === undefined ? {} : { maxPerActor }),
     // A withheld row is a metric, never a frame and never an error: telling a client "there is a
     // row you may not see" is the leak the gate exists to prevent.
     onRowDenied: (event) => logger.debug('live.rows_denied', { ...event }),
   });
-  const ctx = createContext({ role: 'sync', buildId: options.buildId });
+  const ctx = ctxOf({ role: 'sync', buildId: options.buildId });
   // The position a snapshot claims: the newest change this node had received when the read began.
   // The read then holds at least that change, so claiming it is true, and every later change is
   // above it. Unwired, every snapshot claimed `''` and a read that landed after any fan-out was
@@ -176,6 +195,74 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
   return registry;
 }
 
+/**
+ * Who dialled the socket, resolved by `@ultimat3/http`'s `clientAddress()` — the rule the web role's
+ * `ctx.ip` follows, at the same `TRUSTED_PROXY_HOPS`. It keys an anonymous live reader's rate
+ * limit: read off the socket alone, a node behind an ingress put every anonymous viewer of the
+ * fleet in the ingress's one bucket, and one visitor looping subscribes locked out the rest.
+ *
+ * The config is built only to carry the hops — `rateLimit.scope` is declared because
+ * `defineHttpConfig` requires it, and this node runs no HTTP limiter that would read it.
+ */
+export function syncClientAddressOf(
+  env: Env,
+): (request: Request, socketAddress: string | null) => string | null {
+  const hops = trustedHopsFromEnv(env);
+  const config = defineHttpConfig(
+    mergeHttpConfig(configuredHttp(), {
+      rateLimit: { scope: 'process' },
+      ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
+    }),
+  );
+  return (request, socketAddress) =>
+    clientAddress({
+      headers: request.headers,
+      config,
+      socketAddress,
+      urlProtocol: new URL(request.url).protocol,
+    });
+}
+
+/**
+ * The node's half of the app's per-actor caps: `realtime.maxSocketsPerActor`, the sockets one
+ * principal may hold here. Absent, the node keeps its own default (16) — which is core's too.
+ */
+export function syncNodeCaps(realtime: RealtimeConfig | undefined): {
+  readonly maxSocketsPerActor?: number;
+} {
+  const max = realtime?.maxSocketsPerActor;
+  return max === undefined ? {} : { maxSocketsPerActor: max };
+}
+
+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,16 +282,27 @@ 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 node = createSyncNode({
+  const origins = syncOriginsFrom(options.env);
+  const node = syncNode({
     hub,
     registry,
     transport: options.runtime.transport,
     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),
+    clientAddressOf: syncClientAddressOf(options.env),
+    ...syncNodeCaps(options.runtime.realtime),
     // 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 +321,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 +336,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/root-env.ts

@@ -1,9 +1,9 @@
 // The `.env*` files of the APP ROOT, whatever directory `x` was started from. Bun auto-loads them
 // from the process cwd only, while every command finds its root by walking up — so `x db migrate`
 // run from `apps/web` found the app and none of its `.env`, and silently used the embedded
-// database. Loaded once, after the root is known, never overriding a variable already set.
+// database. Loaded once, after the root is known, never overriding a real environment variable.
 
-import { isAbsolute, join, resolve } from 'node:path'; // why: Bun ships no path join/resolve.
+import { isAbsolute, join, relative, resolve } from 'node:path'; // why: Bun ships no path join/resolve.
 import { findAppRoot } from './app-root';
 
 type Env = Readonly<Record<string, string | undefined>>;
@@ -25,43 +25,172 @@ export const rootEnvFiles = (envName: string): readonly string[] => [
   `.env.${envName}.local`,
 ];
 
+const QUOTES = new Set(['"', "'", '`']);
+
+/**
+ * The quoted value opening at `text[open]`, read the way Bun reads it: across lines until the first
+ * unescaped closing quote, a backslash keeping the character after it (so `\"` never closes), and
+ * only double quotes turning `\n` and `\r` into the characters. `undefined` when the quote never
+ * closes — Bun then keeps the line as written, opening quote and all.
+ */
+function quoted(text: string, open: number): { value: string; end: number } | undefined {
+  const quote = text[open];
+  let value = '';
+  for (let at = open + 1; at < text.length; at += 1) {
+    const char = text[at];
+    if (char === quote) return { value, end: at + 1 };
+    if (char === '\\' && at + 1 < text.length) {
+      const next = text[at + 1];
+      value +=
+        quote !== '"'
+          ? `${char}${next}`
+          : next === 'n'
+            ? '\n'
+            : next === 'r'
+              ? '\r'
+              : `${char}${next}`;
+      at += 1;
+      continue;
+    }
+    value += char;
+  }
+  return undefined;
+}
+
 /**
- * One dotenv line: `KEY=value`, an optional `export `, a `#` comment, a value in single or double
- * quotes (double quotes read `\n`). No `${VAR}` expansion — a root-level default that needs one
- * belongs in the process environment, which always wins here anyway.
+ * Bun's expansion pass, the one part of it reproduced: `\$` is a literal `$` in every kind of
+ * value, quoted or not. Run after the quote pass, which is why `"a\\$x"` reads `a\$x` in Bun too.
  */
-export function parseDotenv(text: string): ReadonlyMap<string, string> {
+const literalDollars = (value: string): string => value.replaceAll('\\$', '$');
+
+/**
+ * A dotenv file, parsed to agree with Bun's own loader on the same bytes — a root `.env` must mean
+ * the same thing whether Bun read it (the process started in the root) or this did (it started
+ * below it). `KEY=value`, an optional `export `, `#` comments (an unquoted value ends at the first
+ * `#`), values quoted with `"`, `'` or a backtick and free to span lines, so a PEM key parses. A
+ * bare `\r` separates lines as `\n` does, inside a quoted value too.
+ * Bun's `$VAR` expansion is NOT reproduced: it resolves lazily across every loaded file and the
+ * process env, so a root default that needs one belongs in the process environment.
+ */
+export function parseDotenv(source: string): ReadonlyMap<string, string> {
+  const text = source.replace(/\r\n?/g, '\n');
   const out = new Map<string, string>();
-  for (const raw of text.split(/\r?\n/)) {
-    const line = raw.trim();
-    if (line === '' || line.startsWith('#')) continue;
-    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*(.*)$/.exec(line);
+  let start = 0;
+  while (start < text.length) {
+    const newline = text.indexOf('\n', start);
+    const eol = newline === -1 ? text.length : newline;
+    const line = text.slice(start, eol);
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*/.exec(line);
+    const open = start + (match?.[0].length ?? 0);
+    start = eol + 1;
     if (match === null) continue;
-    const value = (match[2] ?? '').trim();
-    const quote = value[0];
-    if ((quote === '"' || quote === "'") && value.lastIndexOf(quote) > 0) {
-      const inner = value.slice(1, value.lastIndexOf(quote));
-      out.set(match[1] ?? '', quote === '"' ? inner.replaceAll('\\n', '\n') : inner);
-    } else {
-      out.set(match[1] ?? '', value.replace(/\s+#.*$/, ''));
+    const key = match[1] ?? '';
+    const read = QUOTES.has(text[open] ?? '') ? quoted(text, open) : undefined;
+    if (read !== undefined) {
+      out.set(key, literalDollars(read.value));
+      // Whatever follows the closing quote on its line is a comment to Bun.
+      const after = text.indexOf('\n', read.end);
+      start = after === -1 ? text.length : after + 1;
+      continue;
     }
+    const value = line.slice(match[0].length);
+    const hash = value.indexOf('#');
+    out.set(key, literalDollars((hash === -1 ? value : value.slice(0, hash)).trim()));
   }
   return out;
 }
 
-/**
- * The variables the root's `.env*` files add to `env`: only keys `env` does not already hold, so a
- * real environment variable — and anything Bun already loaded from the cwd — always wins. Empty
- * when there is no app root or the cwd IS the root (Bun loaded those files itself).
- */
-export async function rootEnvAdditions(cwd: string, env: Env): Promise<Record<string, string>> {
-  const root = findAppRoot(cwd);
-  if (root === undefined || resolve(root.dir) === resolve(cwd)) return {};
+/** Where the command runs, and where the PROCESS started — not the same once `--cwd` is passed. */
+export interface RootEnvInput {
+  /** The `--cwd`-resolved directory the command works in; its app root is the one loaded. */
+  readonly cwd: string;
+  /** The directory the process started in: the only one whose `.env*` Bun loaded itself. */
+  readonly processCwd: string;
+  readonly env: Env;
+}
+
+/** Every `.env*` file in `dir`, merged in Bun's precedence for `envName`. */
+async function envFilesIn(dir: string, names: readonly string[]): Promise<Map<string, string>> {
   const merged = new Map<string, string>();
-  for (const name of rootEnvFiles(env['NODE_ENV'] ?? 'development')) {
-    const file = Bun.file(join(root.dir, name));
+  for (const name of names) {
+    const file = Bun.file(join(dir, name));
     if (!(await file.exists())) continue;
     for (const [key, value] of parseDotenv(await file.text())) merged.set(key, value);
   }
-  return Object.fromEntries([...merged].filter(([key]) => env[key] === undefined));
+  return merged;
+}
+
+/** True when `dir` is `root` or below it. */
+const isWithin = (root: string, dir: string): boolean => {
+  const rel = relative(resolve(root), resolve(dir));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+/** What one command's env owes the app root: keys to set, and another app's keys to remove. */
+export interface RootEnvChanges {
+  readonly set: Readonly<Record<string, string>>;
+  readonly unset: readonly string[];
+}
+
+/**
+ * What the root's `.env*` files change in `env`. A real environment variable always wins. Nothing
+ * when there is no app root or the process STARTED in the root (Bun loaded those files itself).
+ * Judged against `processCwd`, never `cwd`: `x --cwd <app>` run from elsewhere resolves `cwd` to
+ * the root, and Bun loaded the other directory's files, not the app's.
+ *
+ * What Bun loaded from the starting directory is not a real variable. Started below the root
+ * (`apps/web`), it is the same app's own, more specific file, and it wins. Started OUTSIDE the
+ * root — `x --cwd ../app-b db migrate` run in app-a — it is another app's: a key whose value is
+ * exactly what that directory's files say is overridden by the target's, and REMOVED when the
+ * target does not define it — left in place, app-a's DATABASE_URL migrated app-b, which relies on
+ * its default. A value that differs from the file is one Bun did not write (it never overrides a
+ * real variable), so it is real and stays.
+ */
+export async function rootEnvChanges(input: RootEnvInput): Promise<RootEnvChanges> {
+  const { env } = input;
+  const root = findAppRoot(input.cwd);
+  if (root === undefined || resolve(root.dir) === resolve(input.processCwd)) {
+    return { set: {}, unset: [] };
+  }
+  const outside = !isWithin(root.dir, input.processCwd);
+  // A superset of what Bun loads from a cwd, so a key from any of them is recognised as file-made.
+  const filesAt = (dir: string, name: string) =>
+    envFilesIn(dir, [...rootEnvFiles(name), '.env.local']);
+  let envName = env['NODE_ENV'] ?? 'development';
+  let foreign = outside ? await filesAt(input.processCwd, envName) : new Map<string, string>();
+  // A NODE_ENV another app's file wrote is not one the operator chose: Bun picked that directory's
+  // file set with no real NODE_ENV, so with its default — and the target's set is picked the same
+  // way, never from the foreign value (app-a's `NODE_ENV=test` loaded app-b's `.env.test`).
+  if (foreign.has('NODE_ENV') && env['NODE_ENV'] === foreign.get('NODE_ENV')) {
+    envName = 'development';
+    foreign = await filesAt(input.processCwd, envName);
+  }
+  const merged = await envFilesIn(root.dir, rootEnvFiles(envName));
+  const fromFile = (key: string): boolean => foreign.has(key) && env[key] === foreign.get(key);
+  return {
+    set: Object.fromEntries([...merged].filter(([key]) => env[key] === undefined || fromFile(key))),
+    unset: [...foreign.keys()].filter((key) => fromFile(key) && !merged.has(key)).sort(),
+  };
+}
+
+type MutableEnv = Record<string, string | undefined>;
+
+/**
+ * The env a command runs with. When `env` IS the process env, it is changed in place — a package
+ * reading `Bun.env` directly must see what the command sees, and an unset key must be GONE, not
+ * merely shadowed. An injected env is never mutated: the command gets a rebuilt copy.
+ */
+export function applyRootEnv(
+  env: Env,
+  changes: RootEnvChanges,
+  processEnv: MutableEnv = Bun.env,
+): Env {
+  if (env === processEnv) {
+    for (const key of changes.unset) delete processEnv[key];
+    Object.assign(processEnv, changes.set);
+    return processEnv;
+  }
+  const rebuilt: MutableEnv = { ...env, ...changes.set };
+  for (const key of changes.unset) delete rebuilt[key];
+  return rebuilt;
 }

package/src/route-islands.ts

@@ -0,0 +1,69 @@
+// Which islands one route render collects, and the realtime page boot that render earns. Split
+// from `runtime-render.ts` so the document builder stays one job; both `documentFrom` and the
+// `stream` branch read the same two answers.
+
+// why: Bun ships no path API; an island's file is its route file's directory joined to its `src`.
+import { posix } from 'node:path';
+import type { IslandCollector, RouteEntry } from '@ultimat3/render';
+import {
+  clientBootTags,
+  islandCollector,
+  islandModuleId,
+  islandModuleIds,
+  renderHead,
+} from '@ultimat3/render';
+import type { DocumentOptions } from './document-options';
+import { realtimeIslandFiles } from './island-realtime';
+
+/**
+ * One collector per RENDER, never module-global: two requests render different params, and a
+ * shared collector would bill one page for the other's islands. `hydrate` comes off the route, so
+ * an island never declares its own timing, and `resolve` is the build's — identity when nothing
+ * built any, which fails at the first island by name rather than emitting an unusable entry.
+ */
+export const collectorFor = (
+  entry: RouteEntry,
+  options: DocumentOptions,
+  scope: string | undefined,
+): IslandCollector =>
+  islandCollector({
+    file: entry.file,
+    hydrate: entry.config.hydrate,
+    ...(options.resolveIsland === undefined ? {} : { resolve: options.resolveIsland(entry.file) }),
+    // #506: on a document that carries the page boot (the same two conditions as `bootScript`), a
+    // realtime island's server markup is held off screen until it mounts over the restored store.
+    ...(scope === undefined || options.sync === undefined
+      ? {}
+      : { hold: (src: string) => reachesRealtime(entry, src) }),
+  });
+
+/** Whether `src`, as the page at `entry` wrote it, is an island the last build found realtime. */
+const reachesRealtime = (entry: RouteEntry, src: string): boolean =>
+  realtimeIslandFiles().has(posix.join(posix.dirname(entry.file), src));
+
+/**
+ * Realtime's page boot, as one deferred script — or nothing. Two conditions, both exact: the
+ * document carries a principal scope (restoring persisted records and replaying queued writes are
+ * per principal; a shareable document has neither), AND one of the islands this render emitted
+ * reaches `@ultimat3/realtime` (a page whose islands never touch a record has nothing to restore
+ * into and no write to replay). After the body, because which islands rendered is a fact the walk
+ * just recorded; still before the hydration runtime, so it runs first among the deferred scripts.
+ */
+export function bootScript(
+  entry: RouteEntry,
+  islands: IslandCollector,
+  options: DocumentOptions,
+  scope: string | undefined,
+): string {
+  if (scope === undefined || options.sync === undefined) return '';
+  const rendered = new Set(islandModuleIds(islands.directives));
+  if (rendered.size === 0) return '';
+  // An island's module id is derived from its `src`, written relative to the page that renders it:
+  // each realtime island file, spelled from THIS page, is the id its directive would carry.
+  const pageDir = posix.dirname(entry.file);
+  const reaches = [...realtimeIslandFiles()].some((file) => {
+    const src = posix.relative(pageDir, file);
+    return rendered.has(islandModuleId(src.startsWith('.') ? src : `./${src}`));
+  });
+  return reaches ? renderHead(clientBootTags(options.sync)) : '';
+}

package/src/runtime-admin.ts

@@ -28,7 +28,8 @@ const declared = (): ReadonlyMap<string, AdminApp> => {
   return held instanceof Map ? (held as ReadonlyMap<string, AdminApp>) : new Map();
 };
 
-export interface AdminMountOptions extends Pick<DocumentOptions, 'themeHead' | 'origin'> {
+export interface AdminMountOptions
+  extends Pick<DocumentOptions, 'themeHead' | 'brandHead' | 'origin'> {
   readonly buildId: string;
 }
 
@@ -103,6 +104,8 @@ async function answer(
     () =>
       routeDocument(entry, data, {
         ...(options.themeHead === undefined ? {} : { themeHead: options.themeHead }),
+        // The app's brand restyles its admin too: a screen is a document of the `app/` surface.
+        ...(options.brandHead === undefined ? {} : { brandHead: options.brandHead }),
         ...(options.origin === undefined ? {} : { origin: options.origin }),
       }),
     { buildId: options.buildId, status: response.status },

package/src/runtime-assets.ts

@@ -9,9 +9,9 @@ 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 { DEFAULT_QUALITY, isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
 import { faviconRoute } from './favicon';
 // The icon matrix's source, its base path and its renderer live in their own module so that
 // `pwa-artifacts.ts` — which this file imports for the manifest route — can reach them without
@@ -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,33 @@ 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);
+
+/**
+ * The same question for `?q=`. `@ultimat3/seo` never writes a quality into a variant URL, so the
+ * framework mints exactly one — the default — and `variantKey` already spells the default and an
+ * absent one as the same key. Every other value from 1 to 100 was its own stored object per
+ * minted width per format: a hundred writes a caller drives with a loop. Served, never stored.
+ */
+const isMintableQuality = (quality: number | undefined): boolean =>
+  quality === undefined || quality === DEFAULT_QUALITY;
 
 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,
   );
 
@@ -142,7 +155,11 @@ async function transformedVariant(
     ...(query.format === undefined ? {} : { format: query.format }),
     ...(query.quality === undefined ? {} : { quality: query.quality }),
   });
-  if (cached !== undefined && isMintableWidth(query.width, intrinsic)) {
+  if (
+    cached !== undefined &&
+    isMintableWidth(query.width, intrinsic) &&
+    isMintableQuality(query.quality)
+  ) {
     await disk.put(cached, variant.bytes, { contentType: variant.contentType });
   }
   return imageResponse(variant.bytes, variant.contentType, cache);
@@ -174,7 +191,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