@ultimat3/cli 20.1.2 → 20.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "20.1.2",
+  "version": "20.1.4",
   "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": "20.1.2",
-    "@ultimat3/admin": "20.1.2",
-    "@ultimat3/ai": "20.1.2",
-    "@ultimat3/auth": "20.1.2",
-    "@ultimat3/cache": "20.1.2",
-    "@ultimat3/core": "20.1.2",
-    "@ultimat3/db": "20.1.2",
-    "@ultimat3/entity": "20.1.2",
-    "@ultimat3/flags": "20.1.2",
-    "@ultimat3/http": "20.1.2",
-    "@ultimat3/i18n": "20.1.2",
-    "@ultimat3/jobs": "20.1.2",
-    "@ultimat3/mail": "20.1.2",
-    "@ultimat3/manifest": "20.1.2",
-    "@ultimat3/mcp": "20.1.2",
-    "@ultimat3/money": "20.1.2",
-    "@ultimat3/notify": "20.1.2",
-    "@ultimat3/policy": "20.1.2",
-    "@ultimat3/pwa": "20.1.2",
-    "@ultimat3/query": "20.1.2",
-    "@ultimat3/realtime": "20.1.2",
-    "@ultimat3/render": "20.1.2",
-    "@ultimat3/schema": "20.1.2",
-    "@ultimat3/scraping": "20.1.2",
-    "@ultimat3/seo": "20.1.2",
-    "@ultimat3/storage": "20.1.2",
-    "@ultimat3/testing": "20.1.2",
-    "@ultimat3/time": "20.1.2",
+    "@ultimat3/action": "20.1.4",
+    "@ultimat3/admin": "20.1.4",
+    "@ultimat3/ai": "20.1.4",
+    "@ultimat3/auth": "20.1.4",
+    "@ultimat3/cache": "20.1.4",
+    "@ultimat3/core": "20.1.4",
+    "@ultimat3/db": "20.1.4",
+    "@ultimat3/entity": "20.1.4",
+    "@ultimat3/flags": "20.1.4",
+    "@ultimat3/http": "20.1.4",
+    "@ultimat3/i18n": "20.1.4",
+    "@ultimat3/jobs": "20.1.4",
+    "@ultimat3/mail": "20.1.4",
+    "@ultimat3/manifest": "20.1.4",
+    "@ultimat3/mcp": "20.1.4",
+    "@ultimat3/money": "20.1.4",
+    "@ultimat3/notify": "20.1.4",
+    "@ultimat3/policy": "20.1.4",
+    "@ultimat3/pwa": "20.1.4",
+    "@ultimat3/query": "20.1.4",
+    "@ultimat3/realtime": "20.1.4",
+    "@ultimat3/render": "20.1.4",
+    "@ultimat3/schema": "20.1.4",
+    "@ultimat3/scraping": "20.1.4",
+    "@ultimat3/seo": "20.1.4",
+    "@ultimat3/storage": "20.1.4",
+    "@ultimat3/testing": "20.1.4",
+    "@ultimat3/time": "20.1.4",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/browser-launcher.ts

@@ -13,7 +13,7 @@ import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
 import { localBrowser, remoteBrowser } from '@ultimat3/scraping';
-import { CHROME_CANDIDATES } from './cdp-launch';
+import { CHROME_CANDIDATES, CONTAINER_CHROME_ARGS } from './cdp-launch';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -231,8 +231,15 @@ export async function appBrowser(options: AppBrowserOptions): Promise<ScrapeDriv
     ...(options.executablePath === undefined ? {} : { executablePath: options.executablePath }),
     // `LocalBrowserOptions.options` is passed through to `launch()` untouched, which is the seam
     // that lets the CLI size a browser without `@ultimat3/scraping` naming a puppeteer type.
-    ...(options.viewport === undefined
-      ? {}
-      : { options: { defaultViewport: { ...options.viewport } } }),
+    //
+    // `args` carries `CONTAINER_CHROME_ARGS` on EVERY local launch, viewport or not — the same
+    // `--no-sandbox` / `--disable-dev-shm-usage` `cdp-launch.ts`'s e2e driver already needed for
+    // this container, read from the one export rather than restated. Before this, `x shot` was the
+    // only browser-launching command in the tree with neither, so a box where the e2e gate ran
+    // green could not run `x shot` at all — Chrome exits "No usable sandbox".
+    options: {
+      args: [...CONTAINER_CHROME_ARGS],
+      ...(options.viewport === undefined ? {} : { defaultViewport: { ...options.viewport } }),
+    },
   });
 }

package/src/cdp-launch.ts

@@ -36,6 +36,19 @@ export async function findChrome(
   return undefined;
 }
 
+/**
+ * The two flags a CONTAINER needs, regardless of which process launches Chrome: the sandbox needs
+ * privileges CI (and an Ubuntu 23.10+ host with AppArmor's unprivileged-user-namespace restriction
+ * — Chrome exits "No usable sandbox" there with neither) does not grant, and `/dev/shm` is 64 MB in
+ * a default container, which crashes the renderer on any real page.
+ *
+ * Exported so `browser-launcher.ts`'s `appBrowser` — a DIFFERENT launch path, `puppeteer-core`'s
+ * own `launch()` rather than the `Bun.spawn` below — passes the SAME two, rather than a second
+ * list that agrees today and drifts the next time either changes. `x shot` had neither before this
+ * export existed, so a box where `x verify`'s e2e gate ran green could not run `x shot` at all.
+ */
+export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disable-dev-shm-usage'];
+
 /**
  * The flags, and every one of them earns its line.
  *
@@ -43,16 +56,12 @@ export async function findChrome(
  * asks the OS for a free port, so two suites on one machine never collide — the port is read back
  * off stderr, which is the only place Chrome states the one it took. A throwaway `--user-data-dir`
  * because a run sharing a profile with a real browser inherits its cookies and locks its files.
- * `--no-sandbox` and `--disable-dev-shm-usage` are the two a container needs: the sandbox needs
- * privileges CI does not grant, and `/dev/shm` is 64 MB in a default container, which crashes the
- * renderer on any real page.
  */
 const flags = (profileDir: string): readonly string[] => [
   '--headless=new',
   '--remote-debugging-port=0',
   `--user-data-dir=${profileDir}`,
-  '--no-sandbox',
-  '--disable-dev-shm-usage',
+  ...CONTAINER_CHROME_ARGS,
   '--disable-gpu',
   // Nothing here should reach the network on its own account, and a first-run bubble or an update
   // check is a page load the test did not ask for.

package/src/cmd-dev.ts

@@ -24,6 +24,7 @@ import type { CliCommand, CommandContext } from './command';
 import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { declareDevEnvironment } from './dev-environment';
 import { liveFeedLabel } from './dev-live-feed';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
@@ -374,6 +375,9 @@ export const devCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('dev', ctx.cwd).dir;
+    // BEFORE `startDev` imports a single app module — see `dev-environment.ts` for why this must
+    // run this early, and why it mutates the real `process.env` rather than `startDev`'s `env`.
+    declareDevEnvironment(ctx.env);
     // Validated, not `parseInt`'d: `x dev --port abc` handed `NaN` to `Bun.serve`, which binds an
     // arbitrary port — a dev server reachable at an address nothing printed.
     const port = intFlagOr(

package/src/cmd-generate.ts

@@ -72,12 +72,19 @@ export const generateCommand: CliCommand = {
     // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
     const catalogModule = await resolveCatalogModule(root);
     // Read for the same reason: which errors the slice declares is written on THIS app's disk.
-    const sliceErrors = await readSliceErrors(root, kind, sliceDir(surface, featureFlag ?? name));
+    const slice = sliceDir(surface, featureFlag ?? name);
+    const sliceErrors = await readSliceErrors(root, kind, slice);
+    // Same reason again: whether `job`/`task` may assume the tenant-scoped shape is a fact about
+    // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
+    const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
+    const sliceRepo = await readSliceFile(root, kind, slice, 'repo.ts');
     const files = generate({
       kind,
       name,
       ...(featureFlag === undefined ? {} : { feature: featureFlag }),
       ...(sliceErrors === undefined ? {} : { sliceErrors }),
+      ...(sliceEntity === undefined ? {} : { sliceEntity }),
+      ...(sliceRepo === undefined ? {} : { sliceRepo }),
       ...(at === undefined ? {} : { at }),
       ...(permission === undefined ? {} : { permission }),
       surface,
@@ -157,3 +164,19 @@ async function readSliceErrors(
   const file = containedPath(root, `${slice}/errors.ts`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
+
+/**
+ * `job` and `task` only: the slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the
+ * generator's kind is neither or the file does not exist yet. `readSliceErrors`'s reason —
+ * whichever generator reads it decides on THIS app's disk, not on a default the template assumes.
+ */
+async function readSliceFile(
+  root: string,
+  kind: Generator,
+  slice: string,
+  name: 'entity.ts' | 'repo.ts',
+): Promise<string | undefined> {
+  if (kind !== 'job' && kind !== 'task') return undefined;
+  const file = containedPath(root, `${slice}/${name}`);
+  return existsSync(file) ? await Bun.file(file).text() : undefined;
+}

package/src/cmd-mcp.ts

@@ -1,4 +1,4 @@
-// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 13 tools, the JSON-RPC
+// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 15 tools, the JSON-RPC
 // dispatch, both transports and the structural SQL refusals all come from `@ultimat3/mcp`; the CLI
 // supplies only the app, the caller and the socket. A tool answered here would be a second answer
 // to a question the framework already answers.
@@ -117,7 +117,7 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
  * What the session reports when it is over — on STDERR, which is the half this file's header
  * claimed and did not have. `dispatch` renders a `CommandResult` only after `run` resolves, and
  * this resolves when the peer closes stdin, so nothing lands mid-session; but fd 1 under this
- * transport carries JSON-RPC frames, and `✓ mcp stdio serving 13 tools` arriving on it after the
+ * transport carries JSON-RPC frames, and `✓ mcp stdio serving 15 tools` arriving on it after the
  * loop is a malformed frame to a peer still draining, and a second document under `--json`.
  *
  * Its own function so the addressing is testable without a live peer: `serveStdio` resolves only

package/src/cmd-shot.ts

@@ -8,7 +8,7 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
-import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
+import type { ColorScheme, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
@@ -190,6 +190,12 @@ export interface ShotRun {
    * with `--port 0` the port — and therefore the origin — does not exist until after the boot.
    */
   readonly extraHosts?: string | undefined;
+  /**
+   * What `prefers-color-scheme` the page sees, emulated BEFORE navigation so the boot script's
+   * "system" branch answers the same on every box. Absent means the box's own preference — what
+   * `x shot` has always done — and `ui.shot` names one explicitly for exactly that reason.
+   */
+  readonly colorScheme?: ColorScheme | undefined;
   readonly now?: (() => Date) | undefined;
 }
 
@@ -219,6 +225,7 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
+    if (options.colorScheme !== undefined) await page.colorScheme(options.colorScheme);
     await page.goto(requestedUrl, { timeout: options.timeoutMs });
     if (options.settleMs > 0) await Bun.sleep(options.settleMs);
     // The probe may legitimately answer nothing — a page that refuses evaluation, a driver with no

package/src/cmd-test.ts

@@ -197,6 +197,7 @@ export const testCommand: CliCommand = {
     const result = await runShards({
       root: ctx.cwd,
       runner: ctx.runner,
+      env: ctx.env,
       files,
       workers,
       ...(only === undefined ? {} : { only }),

package/src/cmd-verify.ts

@@ -59,6 +59,7 @@ export const verifyCommand: CliCommand = {
     return runVerify(VERIFY_STEPS, {
       root,
       runner: ctx.runner,
+      env: ctx.env,
       ...(workers === undefined ? {} : { workers }),
       ...(only === undefined ? {} : { only }),
     });

package/src/dev-environment.ts

@@ -0,0 +1,42 @@
+// Single responsibility: whether `x dev` must declare `ULTIMATE_ENV` for the app it is about to
+// boot, and the one-liner side effect that declares it. Split out of `cmd-dev.ts` (which the
+// filesize gate holds to ~500 lines) rather than folded into it — this is one decision with one
+// consumer, and keeping it separate is what lets a test pin the decision without paying for a
+// whole app boot.
+
+import { ENVIRONMENT_KEY } from '@ultimat3/core';
+
+/**
+ * Whether `x dev` must declare `ULTIMATE_ENV` for the app it is about to boot: true only when
+ * NEITHER key `@ultimat3/core`'s `resolveEnvironment` reads is set to a real value. Empty-string
+ * matches that reader's own rule (`packages/core/src/environment.ts`'s `readEnvironment`):
+ * `ULTIMATE_ENV=''` is treated as unset, so "already set" here means non-empty, exactly as there.
+ *
+ * `NODE_ENV=ci` (or any other non-`Environment` value) counts as "already set" and is left alone
+ * even though `resolveEnvironment` would still fall through it to `DEFAULT_ENVIRONMENT` — an
+ * operator who set SOMETHING gets no override from this process, only a process that named
+ * NEITHER key does.
+ */
+export function needsDevEnvironmentDeclaration(
+  env: Readonly<Record<string, string | undefined>>,
+): boolean {
+  const declared = env[ENVIRONMENT_KEY];
+  const nodeEnv = env['NODE_ENV'];
+  return (declared === undefined || declared === '') && (nodeEnv === undefined || nodeEnv === '');
+}
+
+/**
+ * The one-liner side effect, split from the decision so a test can pin either without paying for
+ * a whole app boot: `process.env[ENVIRONMENT_KEY] = 'development'`, and only when
+ * `needsDevEnvironmentDeclaration` says neither key was set.
+ *
+ * Mutates the real `process.env`, not a copy: `cmd-dev.ts`'s `run` passes `ctx.env`, which IS
+ * `Bun.env` (probed on 1.4.2 — `Bun.env === process.env`), and it is `process.env` that
+ * `resolveEnvironment`'s default reader (no explicit `env` passed) and every app module loaded
+ * in-process actually consult. The call has to land before `startDev` imports a single app
+ * module — see `cmd-dev.ts`'s `run` for why that means the top of the command, not inside
+ * `startDev` itself, which stays a pure function of the `env` it is handed.
+ */
+export function declareDevEnvironment(env: Readonly<Record<string, string | undefined>>): void {
+  if (needsDevEnvironmentDeclaration(env)) process.env[ENVIRONMENT_KEY] = 'development';
+}

package/src/error-codes.ts

@@ -154,6 +154,9 @@ export const CLI_OWNED_ERROR_CODES = [
   // repair is an install, and only `duplicate-packages.ts` can see that.
   'X_PACKAGE_DUPLICATED',
   'X_SHOT_BROWSER_MISSING',
+  // `ui.shot` (the dev MCP server): a route it will not photograph, and why.
+  'X_UI_SHOT_ROUTE_UNKNOWN',
+  'X_UI_SHOT_ROUTE_UNBUDGETED',
   // `x shot --island` — one code per way a component's named state fails to become a picture.
   // The last of the four is the one that gates: it is checked against the expansion computed
   // before a browser existed, so a capture loop that swallowed a failure cannot exit 0.
@@ -297,6 +300,8 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
   X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
   X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
+  X_UI_SHOT_ROUTE_UNKNOWN: 'ui.shot was asked for a path no route answers',
+  X_UI_SHOT_ROUTE_UNBUDGETED: 'ui.shot refused a route that declares no budget.js',
   X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',

package/src/exec.ts

@@ -21,7 +21,16 @@ export interface ExecResult {
 
 export interface ExecOptions {
   readonly cwd: string;
-  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Overlaid onto `Bun.env`, key by key: a string sets/overrides it for the child, and
+   * `undefined` UNSETS it — the child does not inherit it at all, even though the parent has it.
+   * The delete case exists for one caller (`test-dotenv.ts`'s `testEnvOverrides`, spent by
+   * `test-shards.ts`/`verify-tests.ts`/`verify-test-run.ts`/`mcp-host.ts`): a `bun test` child
+   * must not inherit a key that reached the parent only through Bun auto-loading
+   * `.env.development`. A merge that only ever adds or overrides (`{ ...Bun.env, ...env }`) cannot
+   * express that — `Bun.env` is always the base, so a key just absent from `env` survives from it.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>;
   readonly stdin?: string;
 }
 
@@ -48,12 +57,34 @@ const now = (): number => performance.now();
  *
  * The return type is inferred so this stays one statement of `Bun.spawn`'s own shape.
  */
+/**
+ * `Bun.env` overlaid with `overrides`, an `undefined` value deleting the key rather than setting
+ * it to the string `"undefined"` — see `ExecOptions.env`'s own comment for why a delete has to be
+ * expressible here at all.
+ */
+function mergedEnv(
+  overrides: Readonly<Record<string, string | undefined>>,
+): Record<string, string> {
+  // A `Map`, not an object indexed by `key`: the keys are DATA (environment variable names), and
+  // a plain-object table read or deleted by a computed key is the `Object.prototype` hazard
+  // `scripts/proto-index.ts` ratchets. `Object.fromEntries` builds the record once, at the end.
+  const merged = new Map<string, string>();
+  for (const [key, value] of Object.entries(Bun.env)) {
+    if (value !== undefined) merged.set(key, value);
+  }
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) merged.delete(key);
+    else merged.set(key, value);
+  }
+  return Object.fromEntries(merged);
+}
+
 function spawnOrRefuse(command: readonly string[], options: ExecOptions) {
   const [head = '', ...rest] = command;
   try {
     return Bun.spawn([head, ...rest], {
       cwd: options.cwd,
-      env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
+      env: options.env === undefined ? Bun.env : mergedEnv(options.env),
       stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
       stdout: 'pipe',
       stderr: 'pipe',

package/src/generate-files.ts

@@ -55,6 +55,16 @@ export interface GenerateOptions {
    * import of a class the app never declared. Read at `sliceDir(surface, feature)/errors.ts`.
    */
   readonly sliceErrors?: string;
+  /**
+   * `job` and `task`: the slice's `entity.ts` as it stands on disk, absent when the feature has no
+   * entity yet. Supplied by `run` for `sliceErrors`'s reason — whether the feature is
+   * tenant-scoped is a fact about THIS app, and a template that assumed `tenant: 'orgId'` wrote
+   * `repo.byId`/`repo.listByOrg` calls into a feature whose entity names no tenant column. Read at
+   * `sliceDir(surface, feature)/entity.ts`.
+   */
+  readonly sliceEntity?: string;
+  /** `job` and `task`: the slice's `repo.ts` as it stands on disk, absent alongside `sliceEntity`. */
+  readonly sliceRepo?: string;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -110,9 +120,21 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
     case 'query':
       return dedupe(queryFiles(options.name, { ...target, live: options.live === true }));
     case 'job':
-      return dedupe(jobFiles(options.name, target));
+      return dedupe(
+        jobFiles(options.name, {
+          ...target,
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
+        }),
+      );
     case 'task':
-      return dedupe(taskFiles(options.name, target));
+      return dedupe(
+        taskFiles(options.name, {
+          ...target,
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
+        }),
+      );
     case 'island':
       return dedupe(islandFiles(options.name, { dir: options.at ?? `${surfaceDir}/${feature}` }));
     // No `--at`, no surface, no feature: `guards/` is the one directory the gate discovers, and a

package/src/island-capture.ts

@@ -267,6 +267,7 @@ export async function captureIslandState(
       box: seen?.box ?? { x: 0, y: 0, width: 0, height: 0 },
       mounted: seen?.mounted === true,
       unstubbed: seen?.unstubbed ?? [],
+      sockets: seen?.sockets ?? [],
       console: page.console(),
       pageErrors: page.pageErrors(),
       overflow: seen?.overflow ?? { x: false, y: false },

package/src/island-harness-script.ts

@@ -65,10 +65,54 @@ var method=(init&&init.method)||(typeof input==='object'&&input&&input.method)||
 var path=pathOf(url);var k=method.toUpperCase()+' '+path;
 var respond=stubFor(method,path);bump();
 return answer(respond,k).then(function(r){bump();return r},function(e){bump();throw e})};
-// A socket and an event stream have no stub vocabulary at all, so both are refused outright and
-// recorded: a live component that opened one would otherwise sit in its loading branch forever.
-window.WebSocket=function(url){W.unstubbed.push('WS '+url);throw refuse('WS '+url)};
-window.EventSource=function(url){W.unstubbed.push('SSE '+url);throw refuse('SSE '+url)};
+// A socket or an event stream needs no stub, because a SNAPSHOT of an island does not need a
+// LIVE one: every state's fixture already rides \`props\`/\`routes\`, so the component's own
+// realtime layer has nothing to tell it that the fetch/XHR seal does not already say. Refusing
+// the construction outright — as this did until the defect that made every live island
+// unphotographable — fails a component for opening a channel whose data this harness was never
+// asked to carry, in EVERY state, because \`mount()\` dials it unconditionally.
+//
+// So the stand-in is INERT rather than refused: no real dial, no network, no message and no error
+// ever delivered. \`close()\`/\`send()\` are no-ops. Recorded on \`W.sockets\`, never on
+// \`W.unstubbed\` — a real unanswered fetch still fails the run (the refusal above is unchanged),
+// but a socket a component merely opened and heard nothing from is not the same fact as a request
+// nobody stubbed, and \`stateShotOk\` must not conflate the two; neither field is hidden from the
+// verdict, both ride \`--json\` plainly, so this is not a candidate for \`ISLAND_BLIND_SPOTS\` —
+// that list is for a fact a PICTURE cannot show, and a socket's inertness is a fact this JSON
+// already states.
+//
+// \`readyState\` DOES leave CONNECTING, on a zero-delay timer, once: a component whose \`mount()\`
+// awaits the socket's own \`open\` before it renders anything — never true of the reference app's
+// \`LiveClient\`, whose \`connect()\` registers callbacks and returns, but not a fact this harness
+// may assume of every app — would otherwise hang the mount forever, trading one impossible
+// \`X_SHOT_ISLAND_UNSTUBBED_REQUEST\` fix for an unreachable \`--settle\` deadline, the same defect
+// under a different name. So \`onopen\`/an \`'open'\` listener fires exactly once; \`onmessage\` and
+// \`onerror\` never do, because this is a channel that opened and then heard nothing, not one that
+// received data no fixture could have supplied.
+function inertSocket(kind,url){
+W.sockets.push(kind+' '+url);
+var listeners={};
+var self={
+readyState:0,url:String(url),
+addEventListener:function(type,fn){(listeners[type]=listeners[type]||[]).push(fn)},
+removeEventListener:function(type,fn){var l=listeners[type];if(!l)return;
+var i=l.indexOf(fn);if(i>=0)l.splice(i,1)},
+dispatchEvent:function(){return true},
+send:function(){},
+close:function(){},
+onopen:null,onmessage:null,onerror:null,onclose:null};
+setTimeout(function(){
+self.readyState=1;
+var ev={type:'open',target:self};
+if(typeof self.onopen==='function')self.onopen(ev);
+var handlers=listeners['open'];
+if(handlers)for(var i=0;i<handlers.length;i+=1)handlers[i](ev)},0);
+return self}
+window.WebSocket=function(url){return inertSocket('WS',url)};
+window.WebSocket.CONNECTING=0;window.WebSocket.OPEN=1;
+window.WebSocket.CLOSING=2;window.WebSocket.CLOSED=3;
+window.EventSource=function(url){return inertSocket('SSE',url)};
+window.EventSource.CONNECTING=0;window.EventSource.OPEN=1;window.EventSource.CLOSED=2;
 var RealXHR=window.XMLHttpRequest;
 window.XMLHttpRequest=function(){var xhr=new RealXHR();var open=xhr.open;
 xhr.open=function(method,url){W.unstubbed.push(String(method).toUpperCase()+' '+pathOf(url));
@@ -117,7 +161,7 @@ requestAnimationFrame(tick)}
 /** The whole prelude, in the one order that works: state, seal, clock, then the readiness watch. */
 export function harnessScript(options: HarnessScriptOptions): string {
   return [
-    `window.${HARNESS_GLOBAL}={harness:true,activity:0,ready:false,unstubbed:[]};`,
+    `window.${HARNESS_GLOBAL}={harness:true,activity:0,ready:false,unstubbed:[],sockets:[]};`,
     sealScript(options.stubs),
     clockScript(options.now, options.timeZone),
     readyScript(),
@@ -138,6 +182,11 @@ export const readinessProbe = (selector: string): string =>
   'var r=box?box.getBoundingClientRect():{width:0,height:0,x:0,y:0};' +
   'return{harness:W.harness===true,ready:W.ready===true,' +
   'unstubbed:(W.unstubbed||[]).slice(),' +
+  // Recorded beside `unstubbed`, never merged into it: a socket a component opened and never
+  // heard back from is not the same fact as a request nobody stubbed, and `stateShotOk` reads
+  // neither — a component may legitimately hold an open, silent channel in a state that is
+  // otherwise clean.
+  'sockets:(W.sockets||[]).slice(),' +
   'attached:host!==null&&document.body.contains(host),' +
   'mounted:host!==null&&host.hasAttribute("data-x-mounted"),' +
   'failed:host&&host.hasAttribute("data-x-failed")?host.getAttribute("data-x-failed"):null,' +

package/src/island-verdict.ts

@@ -54,6 +54,13 @@ export interface IslandReadiness {
   readonly harness: boolean;
   readonly ready: boolean;
   readonly unstubbed: readonly string[];
+  /**
+   * `"WS <url>"` / `"SSE <url>"` for every socket a component constructed — recorded, never
+   * gating. The harness's stand-in is inert (constructs, never opens, `close()` is a no-op), so
+   * a component dialing `@ultimat3/realtime`'s `LiveClient.connect()` does not fail the state it
+   * is mounted in; this is the fact a picture cannot carry about that.
+   */
+  readonly sockets: readonly string[];
   readonly attached: boolean;
   readonly mounted: boolean;
   readonly failed: string | null;
@@ -86,6 +93,7 @@ const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
   harness: t.boolean,
   ready: t.boolean,
   unstubbed: t.array(t.string),
+  sockets: t.array(t.string),
   attached: t.boolean,
   mounted: t.boolean,
   failed: t.nullable(t.string),
@@ -115,6 +123,8 @@ export interface IslandStateShot {
   readonly box: IslandBox;
   readonly mounted: boolean;
   readonly unstubbed: readonly string[];
+  /** See `IslandReadiness.sockets` — recorded, and read by neither `stateShotOk` nor the gate. */
+  readonly sockets: readonly string[];
   readonly console: readonly ConsoleLine[];
   readonly pageErrors: readonly PageError[];
   /**
@@ -184,6 +194,7 @@ const shotJson = (shot: IslandStateShot): JsonValue => ({
   warnings: stateShotWarnings(shot).length,
   overflow: { x: shot.overflow.x, y: shot.overflow.y },
   unstubbed: [...shot.unstubbed],
+  sockets: [...shot.sockets],
   console: shot.console.map((line) => ({ level: line.level, text: line.text, at: line.at })),
   pageErrors: shot.pageErrors.map((error) => ({
     message: error.message,

package/src/mcp-errors.ts

@@ -55,6 +55,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PACKAGE_DUPLICATED:
     'x i18n check --json   # the finding names both copies and the package.json to pin',
   X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
+  X_UI_SHOT_ROUTE_UNKNOWN: 'x routes --json   # then ui.shot with one of its path values',
+  X_UI_SHOT_ROUTE_UNBUDGETED:
+    "x build --target static --json && x verify --only budgets --json   # after declaring budget: { js: '<n>kb' } in the route file",
   // The four island-capture codes. Each one's real repair is an edit to the app's own states file
   // or component, which no command can perform — so each names the command that REPRODUCES it with
   // the file and the reason attached, which is the runnable half.

package/src/mcp-host.ts

@@ -44,8 +44,10 @@ import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
+import { uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
+import { testEnvOverrides } from './test-dotenv';
 
 export interface DevHostInput {
   readonly root: string;
@@ -178,7 +180,7 @@ export async function readOnlyRows(
 }
 
 function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities {
-  const { root, runner } = input;
+  const { root, runner, env } = input;
   // Layer 1 is seven idempotent DDL statements, and `db.query` is a tool an agent calls in a
   // loop — resolve the role once per process and reuse the answer, `null` included. A FAILED
   // resolution is not an answer: `??=` kept the rejection, so a statement timeout on the DDL
@@ -239,10 +241,14 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
 
     // `bun test <filter>` matches on the test path, the same rule `x test`'s `discoverTests` uses.
     async runTests(filter: string | undefined) {
+      // Same leak the CLI's own `x test`/`x verify` had: `.env.development` auto-loaded into
+      // THIS process must not ride along into the `bun test` child the dev MCP server spawns.
+      const envOverrides = testEnvOverrides(root, env);
       const result = await runner(
         filter === undefined ? ['bun', 'test'] : ['bun', 'test', filter],
         {
           cwd: root,
+          ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
         },
       );
       return parseBunTest(execOutput(result), result.durationMs);
@@ -276,6 +282,8 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
 
     explainError: explainErrorCode,
 
+    ...uiCapabilities({ root, env }),
+
     async verify(fix: boolean): Promise<VerifyResult> {
       // The one safe autofix this repo actually has. Anything more would be the gate rewriting
       // code it was asked to judge.