@ultimat3/cli 19.3.3 → 20.0.0

package/CLAUDE.md

@@ -259,6 +259,7 @@ change, and CI does not install one.
 |---|---|---|
 | `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` — launching Chrome here, or **attaching** to one over `--cdp-url` / `SCRAPE_CDP_URL`, which is what every stealth provider sells and what `remoteBrowser()` has called its primary path since it shipped | the static build — `--target static` prerenders `site/` only, so an `app/` route would photograph the landing page |
 | `x shot --island <name>` | the same server and the same browser, plus the app's own `*.island.states.ts` | a second command — photographing a route and photographing a component are one job with two subjects, and `--island` with a route positional is refused by name |
+| `x shot --all-islands` | every `*.island.states.ts` in the app, one boot, one browser per declared VIEWPORT across all of them | a second capture loop — one island and every island are `runIslandSweep` with one argument, because two loops are two answers to what a run produced |
 | `x pr review\|resolve\|reply` | `gh api graphql`, through the injected `Runner` | `gh pr view --comments`, which shows *issue* comments and not the line-anchored threads that carry the findings |
 | `x ci` | `gh run view --log-failed`, one call | a per-job log fetch — the run and all its jobs come back together |
 
@@ -277,10 +278,12 @@ ones a running app will not produce on request. `--island` takes them, one addre
 | `island-harness.ts` | the document that mounts ONE island over `data-x-entry` / `data-x-props` |
 | `island-harness-script.ts` | what runs before the chunk does: the sealed network, the pinned clock, the readiness watch |
 | `island-harness-route.ts` | `GET /_x/island`, mounted by `x dev` |
-| `island-shot.ts` | the capture loop, the assertions before each shutter, the missing-shot gate |
+| `island-shot.ts` | the RUN: which islands, in which order, which artifacts — and the missing-shot gate |
+| `island-capture.ts` | ONE picture: the assertions before the shutter, the crop rectangle, the one session |
+| `island-shot-index.ts` | `index.md` as a PURE function of (manifests, targets, verdicts) — no I/O in the rule |
 | `shot-browser.ts` | which browser a run gets — launch one here, or attach over `--cdp-url` / `SCRAPE_CDP_URL` — as three rules over plain inputs |
 | `island-verdict.ts` | the per-state verdict — a PNG cannot say the component threw or logged |
-| `cmd-shot-island.ts` | the flags, and the one browser per declared viewport |
+| `cmd-shot-island.ts` | the flags, the refusals, and the one browser per declared viewport |
 
 The vocabulary is **`@ultimat3/testing`'s**, not this package's: `defineIslandStates`,
 `islandShotTargets`, `islandAddress` / `parseIslandAddress`, `findIslandStates`,
@@ -312,6 +315,43 @@ mount that never finished, a page that never went quiet, a zero-sized box, a box
 and no text. Then a byte floor as a backstop. Every one of them otherwise comes out as a plausible
 image of the wrong thing.
 
+**`--all-islands` is a spelling, never `--island` with no value.** The parser refuses a bare
+`--island` ("expects a value") and `--island=` is an empty NAME, so "every island" had no form a
+reader could type that could not be read as a mistyped one. A boolean cannot be confused with a
+name. Every contradictory pair is refused BY NAME and before a value is read — beside `--island`,
+beside a route positional, and beside `--state`, which belongs to ONE manifest's vocabulary
+(`empty` in two manifests is two unrelated states). An app declaring no states at all is refused
+too, rather than answered with an empty gallery: "produced nothing and exited 0" is the one outcome
+a reader cannot tell from success. Its `fix:` names `x g island`, and deliberately not a states
+generator — a `fix:` may only cite a command this build ships (`fix-command.ts`), and there is none.
+
+**A sweep never aborts on a failure.** Every state the app CAN photograph is captured, every
+per-island `verdict.json` and the index are written, and only then does the missing-picture gate
+turn the reasons into a non-zero exit. One island that will not mount must not cost a reader the
+other nineteen — which is the same rule the per-state loop already followed, one level up.
+
+**`.x/shot/island/index.md` is the file an agent opens**, and it is written for a SINGLE-island run
+too: the file that says what a picture IS cannot be a property of how many islands were asked for.
+`island-shot-index.ts` is a pure renderer over (manifests, targets, verdicts) — no disk, no browser
+— and the caller does the writing, which is the split every check in this repo uses. It carries the
+counts, the re-run commands, the verdict's own `blind` list (handed in, never reworded: two
+wordings drift), and per state the `id`, the `title`, the `note` — the *"you cannot reach this by
+clicking, because …"* line, which is the whole reason a reviewer knows what they are looking at.
+
+**A console WARNING and an overflowing box are recorded and gate NOTHING.** `stateShotOk` reads
+neither, on purpose: a signal that fails a run is a signal an author switches off. The warnings were
+already in `page.console()` and already in `--json`; what was missing is that nobody counted them.
+The overflow is new and is the readiness probe's own answer — `scrollWidth > clientWidth` on the
+crop target, measured in the same round trip, because a fact measured after the shutter is a fact
+about a different page.
+
+**The clip carries a margin, clamped to the document.** It was the readiness box EXACTLY, and a
+pixel-tight rectangle shaves off everything a component paints outside its border box — a
+`box-shadow`, an outline, a focus ring, a hairline border on a subpixel — so a reviewer reads a
+component with no elevation as flat. `ISLAND_CROP_MARGIN_PX` is the one constant; the clamp reads
+the document's own extent off the probe (`page`), never the viewport, and it may only ever make the
+frame BIGGER than the component's box — a clamp that could shrink it would crop the subject.
+
 **One session per picture, and that is not an optimisation to collapse.** `page.console()` and
 `page.pageErrors()` are bounded rings over the whole SESSION, so a shared one files state A's
 console errors under state B — and per-state attribution is the half of the artifact that gates.
@@ -1487,7 +1527,20 @@ refuses). A guard returning `[1n]` is `X_GUARD_FINDING_INVALID`, per candidate,
 entry costs its own line and not the real findings beside it. The mechanism whose job is producing
 structured failures handing back a stack trace is the one outcome it exists to prevent.
 
-**`x new` ships four guards, `As of 2026-08-22`.** The scaffolded `AGENTS.md` states nine
+**`x new` ships NINE guards, `As of 2026-09-08`** — the four below plus five interface rules
+(`semantic-interactive`, `focus-visible`, `image-dimensions`, `animated-layout-property`,
+`island-without-states`), each statically decidable and each carrying a legitimate-lookalike test
+that must NOT be reported. **Two of the original four were broken the whole time and nobody could
+see it**, because no guard had ever run against a real app: `raw-colour` reported all 87 uses of
+`rgb(var(--color-…))` — which IS the token form `_colors.scss` emits, so its own cause line ("a
+value no theme can restate") was false of every one — and `untranslated-string`'s JSX mask
+`/\{[^{}]*\}/g` does not nest, so `{t('k', { org: x })}` lost its inner brace group first and the
+remnant read as prose, flagging every `t()` call with an interpolation object or a template-literal
+key. Both are fixed and both now report zero against `examples/dummy`, which is the first tracked
+app to carry a `guards/` directory at all. Read the count, never this sentence:
+`bun -e "import {scaffoldGuardFiles} from './packages/cli/src/templates/scaffold-guards'; console.log(scaffoldGuardFiles().length)"`.
+
+The scaffolded `AGENTS.md` states nine
 non-negotiables, and five of them used to be prose — each proven green on `x verify`: a hardcoded
 JSX string beside a `t()` call, `color: #ff0000` in a stylesheet whose own scaffolded header called
 it "a lint failure", `toLocaleDateString('en-US')` with no `timeZone`, `t.number` money, and a bare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.3.3",
+  "version": "20.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "19.3.3",
-    "@ultimat3/admin": "19.3.3",
-    "@ultimat3/ai": "19.3.3",
-    "@ultimat3/auth": "19.3.3",
-    "@ultimat3/cache": "19.3.3",
-    "@ultimat3/core": "19.3.3",
-    "@ultimat3/db": "19.3.3",
-    "@ultimat3/entity": "19.3.3",
-    "@ultimat3/flags": "19.3.3",
-    "@ultimat3/http": "19.3.3",
-    "@ultimat3/i18n": "19.3.3",
-    "@ultimat3/jobs": "19.3.3",
-    "@ultimat3/mail": "19.3.3",
-    "@ultimat3/manifest": "19.3.3",
-    "@ultimat3/mcp": "19.3.3",
-    "@ultimat3/money": "19.3.3",
-    "@ultimat3/notify": "19.3.3",
-    "@ultimat3/policy": "19.3.3",
-    "@ultimat3/pwa": "19.3.3",
-    "@ultimat3/query": "19.3.3",
-    "@ultimat3/realtime": "19.3.3",
-    "@ultimat3/render": "19.3.3",
-    "@ultimat3/schema": "19.3.3",
-    "@ultimat3/scraping": "19.3.3",
-    "@ultimat3/seo": "19.3.3",
-    "@ultimat3/storage": "19.3.3",
-    "@ultimat3/testing": "19.3.3",
-    "@ultimat3/time": "19.3.3",
+    "@ultimat3/action": "20.0.0",
+    "@ultimat3/admin": "20.0.0",
+    "@ultimat3/ai": "20.0.0",
+    "@ultimat3/auth": "20.0.0",
+    "@ultimat3/cache": "20.0.0",
+    "@ultimat3/core": "20.0.0",
+    "@ultimat3/db": "20.0.0",
+    "@ultimat3/entity": "20.0.0",
+    "@ultimat3/flags": "20.0.0",
+    "@ultimat3/http": "20.0.0",
+    "@ultimat3/i18n": "20.0.0",
+    "@ultimat3/jobs": "20.0.0",
+    "@ultimat3/mail": "20.0.0",
+    "@ultimat3/manifest": "20.0.0",
+    "@ultimat3/mcp": "20.0.0",
+    "@ultimat3/money": "20.0.0",
+    "@ultimat3/notify": "20.0.0",
+    "@ultimat3/policy": "20.0.0",
+    "@ultimat3/pwa": "20.0.0",
+    "@ultimat3/query": "20.0.0",
+    "@ultimat3/realtime": "20.0.0",
+    "@ultimat3/render": "20.0.0",
+    "@ultimat3/schema": "20.0.0",
+    "@ultimat3/scraping": "20.0.0",
+    "@ultimat3/seo": "20.0.0",
+    "@ultimat3/storage": "20.0.0",
+    "@ultimat3/testing": "20.0.0",
+    "@ultimat3/time": "20.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-shot-island.ts

@@ -1,7 +1,11 @@
-// `--island`'s half of `x shot`: read the flags, resolve the manifest, refuse the combinations
-// that cannot mean anything, and hand `runIslandShot` values. Split from `cmd-shot.ts` so neither
-// file has to hold both a route capture and a component capture — the two share a boot, a browser
-// and an output tree, and nothing else.
+// `--island` and `--all-islands`: read the flags, resolve the manifests, refuse the combinations
+// that cannot mean anything, and hand the run its values. Split from `cmd-shot.ts` so neither file
+// has to hold both a route capture and a component capture — the two share a boot, a browser and
+// an output tree, and nothing else.
+//
+// One island and every island are one code path with one argument (`runIslandSweep`), never two
+// loops: two would be two answers to what a run produced, and the sweep is the form an agent
+// reaches for first.
 
 // why: no Bun native joins or resolves a path; `--out` is resolved against the app root.
 import { join, resolve } from 'node:path';
@@ -11,10 +15,16 @@ import { findIslandStates } from '@ultimat3/testing';
 import { appBrowser } from './browser-launcher';
 import { BadFlagError } from './errors';
 import type { IslandBrowser } from './island-shot';
-import { ISLAND_SHOT_DIR, runIslandShot } from './island-shot';
+import { ISLAND_SHOT_DIR, runIslandShot, runIslandSweep } from './island-shot';
 import { loadIslandStates } from './island-states-load';
-import type { IslandArtifacts } from './island-verdict';
-import { islandShotLines, islandShotSummary, islandVerdictJson } from './island-verdict';
+import type { IslandArtifacts, IslandSweepArtifacts } from './island-verdict';
+import {
+  islandShotLines,
+  islandShotSummary,
+  islandSweepLines,
+  islandSweepSummary,
+  islandVerdictJson,
+} from './island-verdict';
 import type { CommandResult } from './output';
 import type { ShotServer } from './shot-server';
 import { SHOT_DIR } from './shot-server';
@@ -79,6 +89,62 @@ export function refuseRouteWithIsland(route: string | undefined, island: string)
   });
 }
 
+/**
+ * An app with no `*.island.states.ts` anywhere. Refused by NAME rather than answered with an empty
+ * gallery: a run that produces no picture and exits 0 is the one outcome a reader cannot tell from
+ * success, and it is what this whole command exists to make impossible.
+ *
+ * The `fix:` is the generator that exists. It deliberately does not name a states generator: a
+ * `fix:` may only cite a command this build ships (`fix-command.ts`), and there is none.
+ */
+export function refuseNoIslandStates(flag: 'island' | 'all-islands'): never {
+  throw new BadFlagError({
+    flag,
+    command: 'shot',
+    reason: 'this app declares no island states at all, so there is nothing to photograph',
+    fix: "x g island settings --at apps/web/app/settings   # then declare its states beside it with defineIslandStates({ island: '…', states: [...] })",
+  });
+}
+
+/**
+ * `--all-islands` is the WHOLE app and `--island <name>` is one component, so naming both is two
+ * subjects and one command. Refused by name for `refuseRouteWithIsland`'s reason: a reader who
+ * typed both has a belief about which one runs, and half of them would be wrong.
+ */
+export function refuseSweepWithIsland(island: string): never {
+  throw new BadFlagError({
+    flag: 'all-islands',
+    command: 'shot',
+    reason: `--all-islands photographs every island and --island ${island} photographs one; x shot takes one subject`,
+    fix: 'x shot --all-islands --json',
+  });
+}
+
+/** A route and every island are two subjects too, and the same rule decides it. */
+export function refuseSweepWithRoute(route: string): never {
+  throw new BadFlagError({
+    flag: 'all-islands',
+    command: 'shot',
+    reason: `--all-islands photographs every island and "${route}" is a route; x shot takes one subject`,
+    fix: 'x shot --all-islands --json',
+  });
+}
+
+/**
+ * A state id belongs to ONE island's vocabulary — `empty` in two manifests is two unrelated
+ * states — so a filter across every island either means nothing or silently means whichever
+ * islands happen to share the word. The fix names the one-island form, which is where a state id
+ * can be resolved at all.
+ */
+export function refuseSweepWithState(state: string): never {
+  throw new BadFlagError({
+    flag: 'state',
+    command: 'shot',
+    reason: `--state ${state} names one island's declared state, and --all-islands spans every island`,
+    fix: 'x shot --island <name> --state <id> --json',
+  });
+}
+
 export interface IslandShotInput {
   readonly root: string;
   readonly island: string;
@@ -96,6 +162,9 @@ export interface IslandShotInput {
   readonly minBytes?: number | undefined;
 }
 
+/** Every field the one-island form takes, minus the two that name one island and one state. */
+export type IslandSweepInput = Omit<IslandShotInput, 'island' | 'state'>;
+
 /**
  * The states are loaded, expanded and the name resolved BEFORE a browser or a dev server exists —
  * a typo must not cost an embedded Postgres to report, and the expected picture list has to be
@@ -103,14 +172,7 @@ export interface IslandShotInput {
  */
 export async function islandShot(input: IslandShotInput): Promise<IslandArtifacts> {
   const all = await loadIslandStates(input.root);
-  if (all.length === 0) {
-    throw new BadFlagError({
-      flag: 'island',
-      command: 'shot',
-      reason: 'this app declares no island states at all, so there is nothing to photograph',
-      fix: "x g island settings --at apps/web/app/settings   # then declare its states beside it with defineIslandStates({ island: '…', states: [...] })",
-    });
-  }
+  if (all.length === 0) refuseNoIslandStates('island');
   // `findIslandStates` is loose on the way in — `Settings`, `settings`, `settings.island.tsx` and
   // the full path are one name — and refuses an unresolved one by listing every valid name, which
   // is what tells a typo apart from an island whose states were never declared.
@@ -138,6 +200,48 @@ export async function islandShot(input: IslandShotInput): Promise<IslandArtifact
   });
 }
 
+/**
+ * Every island in the app, one boot, one browser per declared viewport across ALL of them — the
+ * memo lives in the `islandBrowser` closure built here, so a sweep of forty states at one size is
+ * still one launch. The manifests are loaded before a browser or a dev server exists, for
+ * `islandShot`'s reason: the complete expected picture list has to be knowable without either.
+ */
+export async function islandSweep(input: IslandSweepInput): Promise<IslandSweepArtifacts> {
+  const all = await loadIslandStates(input.root);
+  if (all.length === 0) refuseNoIslandStates('all-islands');
+  return runIslandSweep({
+    manifests: all,
+    outDir:
+      input.out === undefined
+        ? join(input.root, SHOT_DIR, ISLAND_SHOT_DIR)
+        : resolve(input.root, input.out),
+    driver:
+      input.driver ??
+      islandBrowser({
+        root: input.root,
+        ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+        ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
+      }),
+    boot: input.boot,
+    settleMs: input.settleMs,
+    timeoutMs: input.timeoutMs,
+    ...(input.extraHosts === undefined ? {} : { extraHosts: input.extraHosts }),
+    ...(input.minBytes === undefined ? {} : { minBytes: input.minBytes }),
+  });
+}
+
+export const islandSweepResult = (artifacts: IslandSweepArtifacts): CommandResult => ({
+  ok: artifacts.ok,
+  command: 'shot',
+  summary: islandSweepSummary(artifacts),
+  lines: islandSweepLines(artifacts),
+  data: {
+    dir: artifacts.dir,
+    indexFile: artifacts.indexFile,
+    islands: artifacts.verdicts.map(islandVerdictJson),
+  },
+});
+
 export const islandShotResult = (artifacts: IslandArtifacts): CommandResult => ({
   ok: artifacts.verdict.ok,
   command: 'shot',
@@ -146,6 +250,7 @@ export const islandShotResult = (artifacts: IslandArtifacts): CommandResult => (
   data: {
     dir: artifacts.dir,
     verdictFile: artifacts.verdictFile,
+    indexFile: artifacts.indexFile,
     verdict: islandVerdictJson(artifacts.verdict),
   },
 });

package/src/cmd-shot.ts

@@ -12,7 +12,16 @@ import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
-import { islandShot, islandShotResult, refuseRouteWithIsland } from './cmd-shot-island';
+import {
+  islandShot,
+  islandShotResult,
+  islandSweep,
+  islandSweepResult,
+  refuseRouteWithIsland,
+  refuseSweepWithIsland,
+  refuseSweepWithRoute,
+  refuseSweepWithState,
+} from './cmd-shot-island';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
 import { intFlagOr, PORT_RANGE } from './flag-number';
@@ -275,9 +284,9 @@ export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
 export const shotCommand: CliCommand = {
   spec: {
     name: 'shot',
-    summary: 'photograph one route, or one island in a state it declares, from a real browser',
+    summary: 'photograph one route, one island in a state it declares, or every island in the app',
     usage:
-      'x shot <route> | --island <name> [--state <id>] [--port 0] [--out <dir>] [--settle 2000] [--json]',
+      'x shot <route> | --island <name> [--state <id>] | --all-islands [--port 0] [--out <dir>] [--settle 2000] [--json]',
     requiresApp: true,
     flags: [
       { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
@@ -305,6 +314,15 @@ export const shotCommand: CliCommand = {
         type: 'string',
         summary: 'one declared state of that island, not all of them',
       },
+      // Its own SPELLING and never `--island` with no value: the parser refuses a bare `--island`
+      // ("expects a value") and `--island=` is an empty name, so "every island" had no form a
+      // reader could type that could not be read as a mistyped one. A boolean cannot be confused
+      // with a name, and `x shot --all-islands` says what it does beside `x shot --island <name>`.
+      {
+        name: 'all-islands',
+        type: 'boolean',
+        summary: 'every island in the app, in every state it declares, plus an index.md',
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -312,11 +330,20 @@ export const shotCommand: CliCommand = {
     // Every value read before anything boots: a typo must not cost a browser and a dev server to
     // report, which is the rule `x routes` and `x mcp` already follow.
     const island = flagString(ctx.args, 'island');
+    const state = flagString(ctx.args, 'state');
     const positional = ctx.args.positionals[0];
+    const sweep = flagBool(ctx.args, 'all-islands');
+    // Every ambiguous pair refused BY NAME, before a value is read: a reader who typed two
+    // subjects has a belief about which one runs, and half of them would be wrong.
+    if (sweep && island !== undefined && island !== '') refuseSweepWithIsland(island);
+    if (sweep && positional !== undefined) refuseSweepWithRoute(positional);
+    // A state id is one manifest's vocabulary, so it cannot mean anything across every island.
+    if (sweep && state !== undefined && state !== '') refuseSweepWithState(state);
     if (island !== undefined && island !== '' && positional !== undefined) {
       refuseRouteWithIsland(positional, island);
     }
-    const route = island === undefined || island === '' ? readRoute(positional) : '';
+    const component = sweep || (island !== undefined && island !== '');
+    const route = component ? '' : readRoute(positional);
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
     const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
@@ -332,24 +359,22 @@ export const shotCommand: CliCommand = {
     });
     const out = flagString(ctx.args, 'out');
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
+    const shared = {
+      root,
+      ...(out === undefined ? {} : { out }),
+      settleMs,
+      timeoutMs,
+      ...(executablePath === undefined ? {} : { executablePath }),
+      ...(cdpUrl === undefined ? {} : { cdpUrl }),
+      ...(flagString(ctx.args, 'allow-hosts') === undefined
+        ? {}
+        : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
+      boot,
+    };
+    if (sweep) return islandSweepResult(await islandSweep(shared));
     if (island !== undefined && island !== '') {
       return islandShotResult(
-        await islandShot({
-          root,
-          island,
-          ...(flagString(ctx.args, 'state') === undefined
-            ? {}
-            : { state: flagString(ctx.args, 'state') }),
-          ...(out === undefined ? {} : { out }),
-          settleMs,
-          timeoutMs,
-          ...(executablePath === undefined ? {} : { executablePath }),
-          ...(cdpUrl === undefined ? {} : { cdpUrl }),
-          ...(flagString(ctx.args, 'allow-hosts') === undefined
-            ? {}
-            : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
-          boot,
-        }),
+        await islandShot({ ...shared, island, ...(state === undefined ? {} : { state }) }),
       );
     }
     // Resolved before the boot for the same reason: an app with no browser installed must not pay

package/src/dev-roles.ts

@@ -8,7 +8,13 @@
 
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
-import type { RateLimitStore, Route, ServerHandle, ServerHooks } from '@ultimat3/http';
+import type {
+  RateLimitStore,
+  Route,
+  ServerHandle,
+  ServerHooks,
+  WebSocketMount,
+} from '@ultimat3/http';
 import {
   configuredAuthenticator,
   configuredHttp,
@@ -26,7 +32,7 @@ import {
   jobDriver,
   pgSchedulerState,
 } from '@ultimat3/jobs';
-import type { LiveQueryRegistry } from '@ultimat3/realtime/server';
+import type { LiveQueryRegistry, SyncWs } from '@ultimat3/realtime/server';
 import type { LiveReplicator } from '@ultimat3/testing';
 import { devHooks } from './dev-hooks';
 import type { LiveFeed } from './dev-live-feed';
@@ -36,7 +42,7 @@ import type { RunningReplicator } from './dev-replicator';
 import { startReplicator } from './dev-replicator';
 import type { RunningServices } from './dev-runtime';
 import type { Env } from './dev-services';
-import { startSync } from './dev-sync';
+import { prepareSync, type RunningSync } from './dev-sync';
 import { errorPageHook } from './error-pages';
 import { BadFlagError, PortInvalidError, RuntimeDriverSplitError } from './errors';
 import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
@@ -270,7 +276,9 @@ function rateLimitStoreFor(options: StartRolesOptions): RateLimitStore | undefin
   return supplied;
 }
 
-function startWeb(options: StartRolesOptions): ServerHandle {
+/** `mount` is the sync node's socket, served on THIS port as well as its own — why, in `dev-sync`.
+ * Undefined without the `sync` role, and then this server opens no websocket, as it always did. */
+function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): ServerHandle {
   warnIfUnauthenticatable(options.routes);
   const binding = options.http ?? DEV_BINDING;
   const hops = trustedHopsFromEnv(options.env);
@@ -278,6 +286,7 @@ function startWeb(options: StartRolesOptions): ServerHandle {
   return createServer({
     routes: options.routes,
     role: 'web',
+    ...(mount === undefined ? {} : { websocket: mount }),
     hooks: devHooks({
       ...(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
       ...(options.root === undefined ? {} : { errorPage: errorPageHook(options.root) }),
@@ -373,11 +382,20 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     });
     started.push(async () => metrics.stop());
 
-    const server = selected.includes('web') ? startWeb(options) : null;
+    // BUILT here, BOUND below, the web role between them: `web` serves the node's socket on its
+    // own port and a listening server cannot be handed one, while the neighbouring-port refusals
+    // are only the right answer once the web port's own has been given.
+    const prepared = selected.includes('sync') ? await prepareSync(options) : null;
+    // One rollback entry, kept current — two would stop the node twice out of a failed boot.
+    let releaseSync = prepared?.stop ?? null;
+    if (prepared !== null) started.push(async () => await releaseSync?.());
+
+    const server = selected.includes('web') ? startWeb(options, prepared?.mount) : null;
     if (server !== null) started.push(() => server.stop());
 
-    const sync = selected.includes('sync') ? await startSync(options) : null;
-    if (sync !== null) started.push(sync.stop);
+    const sync: RunningSync | null =
+      prepared === null ? null : await prepared.listen(server === null ? null : server.url());
+    if (sync !== null) releaseSync = sync.stop;
 
     const worker = selected.includes('worker')
       ? createWorker({

package/src/dev-sync.ts

@@ -3,7 +3,9 @@
 // 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 { listQueries } from '@ultimat3/query';
+import type { SyncNode, SyncWs } from '@ultimat3/realtime/server';
 import {
   ChannelHub,
   createSyncNode,
@@ -98,6 +100,32 @@ export function syncPortFor(port: number): number {
   return port + 1;
 }
 
+/**
+ * A node that is built and subscribed but bound to nothing yet — the one moment the `web` role can
+ * still mount its socket, since `web` binds its port first and a mount handed over after that is a
+ * server already listening without it.
+ */
+export interface PreparedSync {
+  readonly node: SyncNode;
+  readonly registry: LiveQueryRegistry;
+  /**
+   * The socket as the WEB role can serve it, on the port that role already publishes.
+   *
+   * `x dev` does BOTH: this mount on `PORT`, and the node's own listener on `PORT + 1` below. They
+   * are one node behind two doors, not two nodes — the sockets share the registry, the grants and
+   * the change subscription — and which door a browser uses is whichever one it can reach.
+   * `docker/` publishes the second; a laptop reached through one forwarded port uses the first.
+   */
+  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.
+   */
+  listen(appUrl: string | null): Promise<RunningSync>;
+  /** Release the node when nothing ever bound it — a `web` role that threw after it was built. */
+  stop(): Promise<void>;
+}
+
 /** What `startRoles` holds on to: where the node listens, and how to take it down. */
 export interface RunningSync {
   readonly url: string;
@@ -141,13 +169,10 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
 }
 
 /**
- * The sync role owns its own socket: websockets and the request pipeline drain differently.
- *
- * Port 0 is passed straight through rather than incremented — `+ 1` would ask the kernel for
- * port 1 instead of an ephemeral one — and the reported url is the listener's own bound address,
- * never a string built from the port that was requested.
+ * 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.
  */
-export async function startSync(options: StartRolesOptions): Promise<RunningSync> {
+export async function prepareSync(options: StartRolesOptions): Promise<PreparedSync> {
   const sockets = new SocketRegistry();
   const hub = new ChannelHub({ transport: options.runtime.transport, sockets });
   // The node evaluated no credential of its own and no host ever handed it one, so every socket
@@ -180,6 +205,35 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     }),
   });
   await node.start();
+  return {
+    node,
+    registry,
+    // The node's OWN path, asked rather than restated: `SyncNodeOptions.path` is settable and a
+    // 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, appUrl),
+  };
+}
+
+/**
+ * The node's own socket, on `PORT + 1`. The sync role owns it because websockets and the request
+ * pipeline drain differently, and `docker/` publishes it as a service of its own.
+ *
+ * Kept a step of its own so `web` binds BEFORE it: the two refusals below are about a taken
+ * 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 passed straight through rather than incremented — `+ 1` would ask the kernel for
+ * port 1 instead of an ephemeral one — and the reported url is the listener's own bound address,
+ * never a string built from the port that was requested.
+ */
+async function listen(
+  options: StartRolesOptions,
+  node: SyncNode,
+  registry: LiveQueryRegistry,
+  appUrl: string | null,
+): Promise<RunningSync> {
   const port = syncPortFor(options.port);
   try {
     // The SAME interface the web role binds, resolved from the same option and the same default.
@@ -192,6 +246,14 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     // seconds of every Ctrl-C (measured 2026-09-06, 5.0s of 5.1s) spent on a reconnect frame
     // whose target does not exist yet.
     const listener = listenSyncNode(node, { port, hostname: binding.hostname, drainGraceMs: 0 });
+    // BOTH doors, named, once. `sync node ready` said only that a node existed: the first question
+    // a failing browser socket raises — "is the ws server up, and where?" — had no answer anywhere
+    // in the boot output, and the port was never printed at all. It is also what an editor's port
+    // forwarding reads: a url in the terminal is how VS Code and a Codespace learn a port exists.
+    logger.info('sync reachable', {
+      node: `${listener.url}${node.path}`,
+      app: appUrl === null ? null : `${appUrl}${node.path}`,
+    });
     return {
       url: listener.url,
       registry,
@@ -207,3 +269,9 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     throw error;
   }
 }
+
+/** Both steps, for a caller with no web role to mount anything on. */
+export async function startSync(options: StartRolesOptions): Promise<RunningSync> {
+  const prepared = await prepareSync(options);
+  return await prepared.listen(null);
+}