@ultimat3/cli 24.0.0 → 25.1.0

package/src/dev-child-watch.ts

@@ -5,6 +5,10 @@
 // 100% CPU, measured at ~50 MB/s of heap growth). Found on a laptop, 2026-09-29: two children of
 // `cmd-dev-restart.live.test.ts`, six hours old, ppid 1, cwd deleted, one at 7 GB.
 //
+// Both facts and the stop itself hold on Windows: the supervisor is asked for by pid
+// (`process.kill(pid, 0)`), since a Windows child's ppid never changes, and a stop arrives as a
+// `drain` message over IPC — `kill('SIGTERM')` there is TerminateProcess, with no drain at all.
+//
 // And a stop that does not finish is finished for it. A drain is bounded by core's deadline, but a
 // loop starved by a spin like the one above reaches its timers late or never, so every stop this
 // child begins — a signal, the watch below, a restart — carries a hard exit past that bound.
@@ -29,8 +33,8 @@ export interface DevChildWatchInput {
   readonly env: Readonly<Record<string, string | undefined>>;
   /** Called once, when the child decides to leave. */
   readonly leave: (why: DevChildGone) => void;
-  /** Test seams: the defaults read the process and the disk. */
-  readonly parentPid?: () => number;
+  /** Test seams: the defaults read the process table and the disk. */
+  readonly supervisorAlive?: (pid: number) => boolean;
   readonly rootExists?: (root: string) => boolean;
   readonly intervalMs?: number;
 }
@@ -43,21 +47,46 @@ export function supervisorPid(
   return Number.isInteger(said) && said > 0 ? said : undefined;
 }
 
+/** `process.kill(pid, 0)`'s answer: delivered, or refused for permission — both mean it exists. */
+export function pidAlive(
+  pid: number,
+  kill: (pid: number, signal: 0) => void = process.kill,
+): boolean {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as { readonly code?: unknown } | null)?.code === 'EPERM';
+  }
+}
+
+/**
+ * Whether the supervisor at `pid` still runs this child. POSIX asks the ppid — immune to a reused
+ * pid, and a supervisor that died before the first tick is still caught, since the child is
+ * reparented. Windows never reparents (the ppid stays the dead supervisor's forever), so there the
+ * process table is asked directly.
+ */
+export function defaultSupervisorAlive(
+  platform: string = process.platform,
+): (pid: number) => boolean {
+  return platform === 'win32' ? (pid) => pidAlive(pid) : (pid) => process.ppid === pid;
+}
+
 /**
- * Polls both facts until one fails, then calls `leave` once and stops. Answers the stop.
- * `process.ppid` rather than a pipe from the supervisor: stdin is the terminal's (`inherit`), and
- * a supervisor that died before the first tick is still caught — its pid is never ours again.
+ * Polls both facts until one fails, then calls `leave` once and stops. Answers the stop. Polled
+ * rather than a pipe from the supervisor: stdin is the terminal's (`inherit`), and IPC closing is
+ * not a fact Bun reports to the child.
  */
 export function watchDevChild(input: DevChildWatchInput): () => void {
   const expected = supervisorPid(input.env);
-  const parent = input.parentPid ?? (() => process.ppid);
+  const alive = input.supervisorAlive ?? defaultSupervisorAlive();
   const exists = input.rootExists ?? existsSync;
   let left = false;
   const timer = setInterval(
     () => {
       if (left) return;
       const why: DevChildGone | undefined =
-        expected !== undefined && parent() !== expected
+        expected !== undefined && !alive(expected)
           ? 'supervisor'
           : exists(input.root)
             ? undefined
@@ -116,10 +145,26 @@ export function hardExit(
   };
 }
 
+/** What the supervisor sends for a stop: the signal it would have forwarded on POSIX. */
+export interface DevDrainMessage {
+  readonly type: 'x-dev-drain';
+  readonly signal: 'SIGINT' | 'SIGTERM';
+}
+
+export function isDevDrainMessage(message: unknown): message is DevDrainMessage {
+  if (typeof message !== 'object' || message === null) return false;
+  const { type, signal } = message as Record<string, unknown>;
+  return type === 'x-dev-drain' && (signal === 'SIGINT' || signal === 'SIGTERM');
+}
+
+/** The exit code a stop for `signal` answers: 128 + its number, as a shell reports it. */
+export const signalExitCode = (signal: 'SIGINT' | 'SIGTERM'): number =>
+  signal === 'SIGINT' ? 130 : 143;
+
 /**
- * The child's watch, wired to core's drain: the supervisor's death or the root's, and SIGINT or
- * SIGTERM, each begin a stop that ends within `devHardExitMs` however the drain fares. `onGone`
- * marks why, so the hold's exit can answer a code.
+ * The child's watch, wired to core's drain: the supervisor's death or the root's, SIGINT or
+ * SIGTERM, and the supervisor's `drain` message each begin a stop that ends within
+ * `devHardExitMs` however the drain fares. `onGone` marks why, so the hold's exit can answer a code.
  */
 export function startDevChildWatch(
   root: string,
@@ -128,8 +173,14 @@ export function startDevChildWatch(
 ): { readonly stopping: (code: number) => void } {
   const stopping = hardExit((code) => process.exit(code));
   // Beside core's own handlers, never instead of them: the drain is theirs, the deadline is this.
-  process.on('SIGINT', () => stopping(130));
-  process.on('SIGTERM', () => stopping(143));
+  process.on('SIGINT', () => stopping(signalExitCode('SIGINT')));
+  process.on('SIGTERM', () => stopping(signalExitCode('SIGTERM')));
+  // The supervisor's stop, on every platform: the same drain a signal begins, by message.
+  process.on('message', (message: unknown) => {
+    if (!isDevDrainMessage(message)) return;
+    stopping(signalExitCode(message.signal));
+    void drain(message.signal);
+  });
   watchDevChild({
     root,
     env,

package/src/dev-dashboard-guard.ts

@@ -4,7 +4,7 @@
 
 import { proveSameOrigin, renderFixShellArg, UltimateError } from '@ultimat3/core';
 import type { UltimateRequest } from '@ultimat3/http';
-import { csrfBlocked, HttpError, json as jsonResponse, selfOrigin } from '@ultimat3/http';
+import { csrfBlocked, HttpError, jsonResponse, selfOrigin } from '@ultimat3/http';
 import { t } from '@ultimat3/schema';
 import { isLoopbackHostname } from './loopback-host';
 

package/src/dev-dashboard.ts

@@ -24,7 +24,7 @@ import {
 import { recentInvalidations } from '@ultimat3/cache';
 import type { Role } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { json as jsonResponse } from '@ultimat3/http';
+import { jsonResponse } from '@ultimat3/http';
 import type { MemoryMailDriver } from '@ultimat3/mail';
 import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
@@ -38,6 +38,7 @@ import type { Finding } from './output';
 import type { DevServices } from './runtime-bindings';
 import type { RunningServices } from './runtime-services';
 import { loopFacts } from './statement-loop';
+import { styleBundle } from './style-bundle';
 
 export interface DevStatus {
   readonly url: string;
@@ -241,6 +242,9 @@ export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
     basePath: DEV_BASE_PATH,
     panels,
     sources: devSources(input),
+    // The drawn tabs render ui's components, whose rules ride the `app/` surface's bundle — the
+    // same URL an `app/` document links, asked per request because a rebuild moves the hash.
+    stylesheetHref: () => styleBundle().hrefFor('app'),
     ...(input.env === undefined ? {} : { env: input.env }),
   });
 

package/src/dev-lock.ts

@@ -14,7 +14,7 @@
 // The lock file is what makes the second one nameable at all: nothing else in the process can tell
 // "another dev server owns this directory" from "the database is broken".
 
-import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
@@ -142,6 +142,26 @@ export class DevLockUnreadableError extends UltimateError {
   }
 }
 
+/**
+ * The state directory refused the claim itself: it could not be created, the lock could not be
+ * staged in it, or the filesystem would not hard-link the staged file into place. None of that is
+ * another `x dev` — only `EEXIST` is — and escaping raw it reached the operator as
+ * `X_CLI_UNEXPECTED` with `fix: x doctor --json`, which says nothing about `.x/`.
+ */
+export class DevStateUnwritableError extends UltimateError {
+  constructor(input: { readonly stateDir: string; readonly error: unknown }) {
+    // Read the field, never cast and dereference: `unknown` is what a catch hands over.
+    const errno = stringField(input.error, 'code') ?? 'an unreported errno';
+    super({
+      code: 'X_DEV_STATE_UNWRITABLE',
+      cause: `${input.stateDir} could not be created, written, or hard-linked into (${errno}), so x dev cannot take its lock — a read-only checkout, a .x/ this user may not write, or a filesystem without hard links`,
+      fix: `ls -ld ${quoteArg(input.stateDir)}   # make it writable by this user, on a filesystem that supports hard links, then re-run x dev`,
+      meta: { stateDir: input.stateDir, errno },
+      sourceError: input.error,
+    });
+  }
+}
+
 /** Whatever is listening, as far as the OS will say. Both fields absent when it will not say. */
 export interface PortHolder {
   readonly pid?: number;
@@ -151,7 +171,8 @@ export interface PortHolder {
 
 /**
  * Who holds the port. `ss` first because it is present on every Linux box the framework targets and
- * needs no elevation for your own processes; `lsof` is the macOS answer.
+ * needs no elevation for your own processes; `lsof` is the macOS answer; `netstat -ano` plus
+ * `tasklist` the Windows one.
  *
  * Through `exec.ts`, like every other subprocess the CLI runs, so a test injects a fake `Runner`
  * rather than racing a real socket.
@@ -159,7 +180,7 @@ export interface PortHolder {
  * EVERY PROBE IS CAUGHT SEPARATELY. `exec` refuses a missing program with `X_CLI_UNEXPECTED`, and
  * letting that escape would mean a box without `ss` gets the CLI's catch-all instead of
  * `X_PORT_IN_USE` — the exact substitution this module exists to end. A missing `ss` must fall
- * through to `lsof`, and a box with neither still gets the refusal, just without a pid in it.
+ * through to `lsof`, and a box with none still gets the refusal, just without a pid in it.
  */
 export const portHolder = async (port: number, runner: Runner = exec): Promise<PortHolder> => {
   const probe = async (command: readonly string[]): Promise<string> => {
@@ -185,9 +206,38 @@ export const portHolder = async (port: number, runner: Runner = exec): Promise<P
   if (pid !== undefined && /^\d+$/.test(pid)) {
     return command === undefined ? { pid: Number(pid) } : { command, pid: Number(pid) };
   }
-  return {};
+
+  // Windows has neither: `netstat -ano` names the listening pid, `tasklist` its image.
+  const listener = netstatListener(await probe(['netstat', '-ano', '-p', 'TCP']), port);
+  if (listener === undefined) return {};
+  const image = tasklistImage(
+    await probe(['tasklist', '/FI', `PID eq ${String(listener)}`, '/FO', 'CSV', '/NH']),
+  );
+  return image === undefined ? { pid: listener } : { command: image, pid: listener };
 };
 
+/**
+ * The pid `netstat -ano` reports LISTENING on `port`, any local address: `TCP 127.0.0.1:3000
+ * 0.0.0.0:0 LISTENING 4242`, and `[::1]:3000` for IPv6. The state column is the word Windows
+ * prints in English on every locale this was read on; an unrecognised line is skipped.
+ */
+export function netstatListener(text: string, port: number): number | undefined {
+  for (const line of text.split(/\r?\n/)) {
+    const [proto, local, , state, pid] = line.trim().split(/\s+/);
+    if (proto !== 'TCP' || state !== 'LISTENING' || pid === undefined || !/^\d+$/.test(pid)) {
+      continue;
+    }
+    if (local?.endsWith(`:${String(port)}`) === true) return Number(pid);
+  }
+  return undefined;
+}
+
+/** The image name off `tasklist /FO CSV /NH`'s one row — `"bun.exe","4242",…` — or `undefined`. */
+export function tasklistImage(text: string): string | undefined {
+  const name = /^"([^"]+)","\d+"/m.exec(text.trim())?.[1];
+  return name === undefined || name === '' ? undefined : name;
+}
+
 /**
  * The port is bound by something that is not us. Named separately from the lock case because the
  * remedy is different: a stranger's port is worked around with `--port`, while a second `x dev` on
@@ -241,33 +291,46 @@ export const isPortBound = (port: number, hostname: string): boolean => {
   }
 };
 
+/** A sibling of the lock, unique to this process and call, where its bytes are staged. */
+const stagingPath = (path: string): string =>
+  `${path}.${process.pid}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+
+const lockText = (lock: DevLock): string => `${JSON.stringify(lock, null, 2)}\n`;
+
 /**
  * Take the lock, or answer `false` because someone else holds it.
  *
- * `wx` is the whole mechanism: the create and the exclusivity are ONE syscall, so two boots racing
- * this cannot both come back `true`. A check followed by a write is what this replaces, and the
- * window between those two was seconds wide — `startDev` boots embedded Postgres, the queue, the
- * transport and the app's modules before anything was written down.
+ * Written whole to a staging file first, then `linkSync`ed into place: the link is the create AND
+ * the exclusivity in ONE syscall (`EEXIST` when the name is taken), so two boots racing this cannot
+ * both come back `true` — and the lock path never exists without its contents. It was `openSync(
+ * path, 'wx')` and THEN a write; a racing preflight that read the file between the two parsed an
+ * empty lock as stale, unlinked the live claim and took the slot itself.
  *
- * Only `EEXIST` is "someone else has it". Anything else — a read-only checkout, a `.x/` nobody may
- * write — is rethrown as it arrives: it is the same failure `writeLock` would have raised seconds
- * later, and inventing a code for it here would be a second answer to one condition.
+ * Only `EEXIST` is "someone else has it". Any other refusal of the staging write or the link — a
+ * `.x/` this user may not write, a filesystem without hard links — is `X_DEV_STATE_UNWRITABLE`
+ * naming the directory and the errno, the original kept as its `sourceError`.
  */
-function claimExclusive(path: string, lock: DevLock): boolean {
-  let fd: number;
+function claimExclusive(stateDir: string, path: string, lock: DevLock): boolean {
+  const staged = stagingPath(path);
   try {
-    fd = openSync(path, 'wx');
+    writeFileSync(staged, lockText(lock));
   } catch (error) {
-    // Same rule as `isProcessAlive` above: read the field, never cast and dereference.
-    if (stringField(error, 'code') === 'EEXIST') return false;
-    throw error;
+    throw new DevStateUnwritableError({ stateDir, error });
   }
   try {
-    writeFileSync(fd, `${JSON.stringify(lock, null, 2)}\n`);
+    linkSync(staged, path);
+    return true;
+  } catch (error) {
+    // Same rule as `isProcessAlive` above: read the field, never cast and dereference.
+    if (stringField(error, 'code') === 'EEXIST') return false;
+    throw new DevStateUnwritableError({ stateDir, error });
   } finally {
-    closeSync(fd);
+    try {
+      unlinkSync(staged);
+    } catch {
+      // Already gone; the staging name is unique to this call, so nothing else can need it.
+    }
   }
-  return true;
 }
 
 /** Whatever is on disk right now, or `null` if it is absent or half-written. */
@@ -321,7 +384,11 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
   const release = (): void => clearLock(input.stateDir);
   // The lock lives inside the state directory, which the database has not created yet — this runs
   // before anything boots, which is the whole point of it.
-  mkdirSync(input.stateDir, { recursive: true });
+  try {
+    mkdirSync(input.stateDir, { recursive: true });
+  } catch (error) {
+    throw new DevStateUnwritableError({ stateDir: input.stateDir, error });
+  }
   const mine: DevLock = {
     pid: process.pid,
     port: input.port,
@@ -332,7 +399,7 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
   };
   let clearedStale = false;
 
-  if (!claimExclusive(path, mine)) {
+  if (!claimExclusive(input.stateDir, path, mine)) {
     const held = await readLock(path);
     if (held !== null && alive(held.pid)) {
       throw new DevAlreadyRunningError({
@@ -349,7 +416,7 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
       // Already gone, or not ours to remove. The claim below is what decides.
     }
     clearedStale = true;
-    if (!claimExclusive(path, mine)) {
+    if (!claimExclusive(input.stateDir, path, mine)) {
       // Lost the race for the slot we just cleared. `held` is the best identity available — a
       // half-written file parses as `null` for microseconds — and refusing on a stale pid beats
       // the alternative, which is two processes writing one single-writer data directory.
@@ -388,7 +455,12 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
  * with the address the server actually bound, which is the one field the preflight could not know.
  */
 export const writeLock = async (stateDir: string, lock: DevLock): Promise<void> => {
-  await Bun.write(lockPath(stateDir), `${JSON.stringify(lock, null, 2)}\n`);
+  // Staged and renamed over the claim, never rewritten in place: a truncate-then-write leaves an
+  // empty lock for an instant, and a preflight reading it then would clear a live claim as stale.
+  const path = lockPath(stateDir);
+  const staged = stagingPath(path);
+  writeFileSync(staged, lockText(lock));
+  renameSync(staged, path);
 };
 
 /** Remove it. Safe to call twice — shutdown paths overlap, and a throw here would mask the real one. */

package/src/dev-rebuild.ts

@@ -0,0 +1,80 @@
+// The `x dev` reload: one save in, the manifest, the findings and the island bundles rebuilt as
+// one generation, the ISR store emptied, and a save this process cannot serve handed to the
+// supervisor as a restart. Coalesced, so a tick arriving mid-build is one trailing rebuild.
+
+import type { Manifest } from '@ultimat3/manifest';
+import type { IsrController } from '@ultimat3/render/server';
+import { appManifest } from './app-manifest';
+import type { StalePin } from './app-reload-graph';
+import { takeStalePins } from './app-reload-graph';
+import type { ReloadTrigger } from './dev-reload';
+import { coalesceReloads } from './dev-reload';
+import { restartFinding } from './dev-supervisor';
+import type { IslandBundle } from './island-bundle';
+import { buildIslands } from './island-bundle';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+export interface DevState {
+  manifest: Manifest;
+  reloads: number;
+  /** A save that will not build. Replaced on every attempt, so a fixed file clears it. */
+  reloadFinding: Finding | undefined;
+  /**
+   * Modules that would not import and primitives that would not register, as of the LAST scan —
+   * the boot's, then each rebuild's. A page saved with a syntax error is a finding here until the
+   * save that fixes it, and the boot's list alone would never show it.
+   */
+  appFindings: readonly Finding[];
+  /**
+   * The client entries, rebuilt on the same tick as the manifest. An island is the one module this
+   * process never imports, so a fresh `Bun.build` is the whole of its reload. The route module
+   * beside it is re-imported by that same scan (`app-load.ts`) — the two are one generation, or
+   * a save serves a new island under an old page, which is what it did until 2026-09-07.
+   */
+  islands: IslandBundle;
+}
+
+/** What a rebuild reports to, read off `StartDevOptions`. */
+export interface DevRebuildOptions {
+  readonly root: string;
+  readonly onReload?: (file: string, durationMs: number) => void;
+  readonly onRestart?: (pins: readonly StalePin[]) => void;
+}
+
+/** The watcher's `onChange`: rebuild `state` for the saved `file`, never rejecting. */
+export function devRebuilder(
+  options: DevRebuildOptions,
+  state: DevState,
+  isr: IsrController,
+): ReloadTrigger {
+  // One rebuild at a time, and the last save wins: a tick arriving mid-build coalesces into ONE
+  // trailing rebuild instead of racing the one in flight for `state.manifest` and `state.islands`.
+  return coalesceReloads(
+    async (file) => {
+      const started = performance.now();
+      const [{ manifest, findings }, islands] = await Promise.all([
+        appManifest(options.root),
+        buildIslands(options.root),
+      ]);
+      state.manifest = manifest;
+      state.appFindings = findings;
+      state.islands = islands;
+      for (const path of isr.store().paths()) isr.store().delete(path);
+      state.reloads += 1;
+      // Read on EVERY rebuild, so a pin one save reached is never reported against the next save.
+      const pins = takeStalePins();
+      state.reloadFinding =
+        pins.length > 0 && options.onRestart === undefined
+          ? restartFinding(options.root, pins)
+          : undefined;
+      if (pins.length > 0 && options.onRestart !== undefined) options.onRestart(pins);
+      else options.onReload?.(file, Math.round(performance.now() - started));
+    },
+    // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
+    // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
+    (error: unknown, file: string) => {
+      state.reloadFinding = { ...findingFrom(error), at: file };
+    },
+  );
+}

package/src/dev-restart-retire.ts

@@ -0,0 +1,46 @@
+// `x dev`'s restart, worker first (issue #677). A save that reaches a primitive-defining module
+// restarts the child, and the drain that ends it used to be the FIRST thing it did: a job that ran
+// past the drain budget was aborted `X_DRAINING` and requeued, so a non-idempotent one (a bank
+// login) ran twice. The worker is retired first — `stop()` claims nothing and aborts nothing — and
+// only then is the drain asked to release the port, the lock and the embedded database.
+
+import { drain, logger, renderThrowable } from '@ultimat3/core';
+import type { Worker } from '@ultimat3/jobs';
+import { msg } from './messages';
+import { writeErrorLine } from './write-line';
+
+/** The two calls a retire makes, so a test hands in a worker without booting a queue. */
+export type RetiringWorker = Pick<Worker, 'stats' | 'stop'>;
+
+export interface RetireDeps {
+  /** The process drain the restart ends in. Default: core's `drain`. */
+  readonly drain: (reason: string) => Promise<void>;
+  /** Where the wait is said. Default: stderr — fd 1 may be `--json`'s one document. */
+  readonly say: (line: string) => void;
+}
+
+const DEFAULT_DEPS: RetireDeps = { drain, say: writeErrorLine };
+
+/**
+ * Retire `worker`, then drain. Unbounded on purpose: in development a restart that waits for a
+ * long job is the cheaper failure than a side effect run twice, and the line it prints says how to
+ * stop waiting — Ctrl-C is a real drain, which binds the worker's teardown to the drain deadline
+ * and cuts off what is still running there. A retire that FAILS still drains: a restart left
+ * half-done is a child that stopped claiming and never exits.
+ */
+export async function retireThenDrain(
+  worker: RetiringWorker | null,
+  deps: RetireDeps = DEFAULT_DEPS,
+): Promise<void> {
+  try {
+    if (worker !== null) {
+      const { inFlight } = await worker.stats();
+      if (inFlight > 0) deps.say(msg('cli.dev.restartWaiting', { count: inFlight }));
+      await worker.stop('x dev restart');
+    }
+  } catch (error) {
+    logger.warn('cli.dev.restart-retire-failed', { error: renderThrowable(error) });
+  } finally {
+    await deps.drain('restart');
+  }
+}

package/src/dev-route-table.ts

@@ -4,21 +4,23 @@
 
 import type { RealtimeConfig } from '@ultimat3/core';
 import type { RateLimitStore, Route } from '@ultimat3/http';
-import { describeRoutes } from '@ultimat3/render';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
+import { describePages } from '@ultimat3/render';
 import type { IsrController } from '@ultimat3/render/server';
+import type { ImageTransformDriver } from '@ultimat3/seo';
 import type { Storage } from '@ultimat3/storage';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { mountAppMcp } from './app-mcp';
 import type { DevDashboardInput } from './dev-dashboard';
 import { devDashboardRoutes } from './dev-dashboard';
-import { errorPageStyleSources } from './error-page-csp';
+import { errorPageStyleBodies } from './error-page-csp';
 import type { IslandBundle } from './island-bundle';
 import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
 import { loadNavigation, pageNavigation } from './page-navigation';
 import type { PageSpeculation } from './page-speculation';
-import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { loadSpeculation, otherLocaleSegments, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { adminMountRoutes } from './runtime-admin';
@@ -33,6 +35,7 @@ import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 import type { ThemeBoot } from './theme-boot';
 import { loadThemeMode, themeBoot } from './theme-boot';
+import { loadThemeBrand } from './theme-brand';
 
 export interface DevRouteTableInput {
   readonly root: string;
@@ -53,6 +56,12 @@ export interface DevRouteTableInput {
    * empty it: a stored render outlives the module that produced it.
    */
   readonly isr?: IsrController | undefined;
+  /**
+   * `apps/<app>/runtime.ts`'s `images` driver, handed to `/media` exactly as the container hands it
+   * (`serve-web.ts`): dropped here, dev answered every variant from the builtin pipeline and a
+   * CDN-backed transform was first exercised in production.
+   */
+  readonly images?: ImageTransformDriver | undefined;
 }
 
 export interface DevRouteTable {
@@ -61,8 +70,11 @@ export interface DevRouteTable {
   readonly theme: ThemeBoot;
   /** The speculation rules, admitted the same way — `undefined` when no document carries any. */
   readonly speculation: PageSpeculation | undefined;
-  /** The app's own error pages' inline styles, admitted the same way. */
-  readonly errorStyles: readonly string[];
+  /**
+   * Every inline `<style>` body these routes put in a document: the app's error pages' and its
+   * brand's (`theme-brand.ts`) — what `startRoles({ inlineStyles })` hashes into `style-src`.
+   */
+  readonly inlineStyles: readonly string[];
   /** Where the app's default MCP endpoint was mounted, or `null`. */
   readonly mcpPath: string | null;
   /** Every mounted MCP endpoint's path, default first — one per population the app serves. */
@@ -74,6 +86,8 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   // is mounted, and the 0kb baseline is not spent on a `<link>` to a file that does not exist.
   const pwa = await loadPwaArtifacts(input.root);
   const theme = themeBoot(await loadThemeMode(input.root));
+  // Read at boot, like the theme mode: a save to the theme module is applied on the next `x dev`.
+  const brand = await loadThemeBrand(input.root);
   // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
   const site = await loadSiteSettings(input.root);
   const origin = publicOrigin(input.env, site);
@@ -87,8 +101,12 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   const speculation = pageSpeculation({
     config: await loadSpeculation(input.root),
     client: declared.surfaces,
+    localeSegments: otherLocaleSegments(await appLocaleSet(input.root)),
   });
-  const errorStyles = await errorPageStyleSources(input.root);
+  const inlineStyles = [
+    ...(await errorPageStyleBodies(input.root)),
+    ...(brand === undefined ? [] : [brand.style]),
+  ];
   // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
   // changes under a page it controls is the update path, and one per keystroke exercises it per save.
   const serviceWorker =
@@ -97,7 +115,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       : serviceWorkerArtifacts({
           pwa,
           buildId: input.buildId,
-          routes: describeRoutes(),
+          routes: describePages(),
           islands: input.islands(),
           styles: styleBundle(),
           scripts: [
@@ -126,6 +144,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...assetRoutes({
       root: input.root,
       storage: served,
+      ...(input.images === undefined ? {} : { images: input.images }),
       ...(pwa === undefined ? {} : { pwa }),
     }),
     ...storageRoutes({ storage: served }),
@@ -146,6 +165,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...islandHarnessRoutes({
       islands: () => input.islands(),
       states: () => loadIslandStates(input.root),
+      devUrl: () => input.dashboard.status().url,
     }),
     ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...sync.routes,
@@ -157,6 +177,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...adminMountRoutes({
       buildId: input.buildId,
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(origin === undefined ? {} : { origin }),
     }),
     ...appRoutes({
@@ -167,6 +188,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined
@@ -179,7 +201,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     routes,
     theme,
     speculation,
-    errorStyles,
+    inlineStyles,
     mcpPath: mcpMount.path,
     mcpPaths: mcpMount.paths,
   };