@ultimat3/cli 20.2.1 → 22.0.0

package/src/live-routes.ts

@@ -12,29 +12,35 @@ import { join, posix } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { ISLAND_EXTENSION, routeEntries } from '@ultimat3/render';
+import { discoverIslands } from './island-bundle';
 import type { Finding } from './output';
 
 /**
- * The exports that only work with a registered `LiveClient`. Each one either subscribes, mutates
- * or reads the connection, so a module naming one is a module that needs a browser to have booted
- * it — `hasLiveClient` and `LiveClient` itself are deliberately absent: the first IS the guard, and
- * the second is what an island's `mount()` constructs.
+ * The exports that only work in a booted browser page: each one reads the page's store, its socket
+ * or its connection, so a module naming one needs an island to have run it. `hasPageSocket` is
+ * deliberately absent — it IS the guard — and so is `installRealtime`, which the island bundle
+ * writes for the author (plan 101, slice 14).
  */
 export const LIVE_HOOKS = [
-  'useLive',
-  'liveHookFor',
+  'useQuery',
   'useConnection',
   'useMutation',
   'useMutationQueue',
+  'useRecord',
+  'useChannel',
 ] as const;
 
 /**
- * The one escape hatch, and it is a call an author writes on purpose: a module that ASKS whether
- * there is a client has already written what happens when there is none. `app/update-banner.tsx`
- * in the reference app is the shape — imported by the layout, so by every page, and correct on all
- * of them.
+ * NOT an escape hatch, `As of 2026-09-22`: `hasPageSocket()` answers false on the server, every
+ * time, so a module that guards on it and never runs in a browser renders nothing forever. It was
+ * exempted here — "a module that asks has handled the absence" — and that is exactly how
+ * `examples/dummy`'s update banner, in a layout no island imports, never showed "A new version is
+ * ready.". It is a browser-only read like any hook, so it is reported like one.
  */
-const GUARD = 'hasLiveClient';
+const GUARD = 'hasPageSocket';
+
+/** Everything that only means something in a booted browser page: the hooks, and the guard. */
+const BROWSER_ONLY: readonly string[] = [GUARD, ...LIVE_HOOKS];
 
 /** Value imports only: `import type` is erased, so it boots nothing and needs nothing. */
 const REALTIME_IMPORT = /import\s+([^;]*?)from\s*['"]@ultimat3\/realtime(?:\/[\w-]+)?['"]/g;
@@ -45,18 +51,14 @@ const bindingsOf = (clause: string): readonly string[] =>
     .map((entry) => entry.split(/\bas\b/)[0]?.trim() ?? '')
     .filter((name) => name.length > 0 && !name.startsWith('type '));
 
-/**
- * Which live hooks one module imports, or `[]` — including for a module that guards, which is a
- * per-FILE verdict on purpose: the guard is written next to the read it protects.
- */
+/** Which browser-only reads one module imports — the hooks and `hasPageSocket` — or `[]`. */
 export function liveHooksIn(source: string): readonly string[] {
   const hooks: string[] = [];
   for (const match of source.matchAll(REALTIME_IMPORT)) {
     const clause = match[1] ?? '';
     if (clause.trimStart().startsWith('type ')) continue;
     const names = bindingsOf(clause);
-    if (names.includes(GUARD)) return [];
-    for (const hook of LIVE_HOOKS) if (names.includes(hook)) hooks.push(hook);
+    for (const hook of BROWSER_ONLY) if (names.includes(hook)) hooks.push(hook);
   }
   return hooks;
 }
@@ -88,14 +90,18 @@ export interface LiveReach {
 }
 
 /**
- * Walk the route module's own import graph and answer the first live hook in it.
+ * Walk a module's own import graph and answer the first thing `probe` finds in it.
  *
  * Relative specifiers only. A bare one resolves through `node_modules` or a workspace name, and
  * following either would mean guessing which package a name came from — the limit `fix-imports.ts`
  * records for the same walk. So this UNDER-reports rather than over-reports: a finding here is
  * always a real one, which is what lets the rule ship with no pin table.
  */
-export async function liveReachOf(root: string, file: string): Promise<LiveReach | undefined> {
+export async function firstInGraph<T>(
+  root: string,
+  file: string,
+  probe: (source: string, path: string) => T | undefined,
+): Promise<T | undefined> {
   const seen = new Set<string>();
   const queue = [file];
   while (queue.length > 0) {
@@ -104,8 +110,8 @@ export async function liveReachOf(root: string, file: string): Promise<LiveReach
     seen.add(next);
     const module = await readModule(root, next);
     if (module === undefined) continue;
-    const hook = liveHooksIn(module.source)[0];
-    if (hook !== undefined) return { at: module.path, hook };
+    const found = probe(module.source, module.path);
+    if (found !== undefined) return found;
     const loader = module.path.endsWith('x') ? 'tsx' : 'ts';
     // Bun's transpiler is the parser, exactly as in `scripts/boundaries.ts`: it erases type-only
     // imports and finds the dynamic ones, which no regex over this source could do.
@@ -117,6 +123,36 @@ export async function liveReachOf(root: string, file: string): Promise<LiveReach
   return undefined;
 }
 
+/** Every module in a file's relative import graph, app-root-relative — one walk, no probe. */
+export async function graphModules(root: string, file: string): Promise<ReadonlySet<string>> {
+  const seen = new Set<string>();
+  await firstInGraph(root, file, (_source, path) => {
+    seen.add(path);
+    return undefined;
+  });
+  return seen;
+}
+
+/** Every module a browser can run: the union of every island's graph in the app. */
+async function islandModules(root: string): Promise<ReadonlySet<string>> {
+  const modules = new Set<string>();
+  for (const island of await discoverIslands(root)) {
+    for (const path of await graphModules(root, island)) modules.add(path);
+  }
+  return modules;
+}
+
+/** Each module in the route's graph that reads a browser-only name, with the first name it reads. */
+async function browserOnlyReads(root: string, file: string): Promise<readonly LiveReach[]> {
+  const reads: LiveReach[] = [];
+  await firstInGraph(root, file, (source, path) => {
+    const hook = liveHooksIn(source)[0];
+    if (hook !== undefined) reads.push({ at: path, hook });
+    return undefined;
+  });
+  return reads;
+}
+
 export interface LiveRouteGap extends LiveReach {
   readonly route: string;
   readonly file: string;
@@ -132,28 +168,34 @@ const generatorFor = (file: string): string => {
 };
 
 /**
- * Every route that reads live rows with nothing to receive them. Two shapes, one condition — no
- * island at all, and an island the route declares `hydrate: 'never'` for. `X_ISLAND_NOT_HYDRATED`
- * covers the second only at render time, and only for a render that reaches the island, so a route
- * can hold the contradiction and never be asked.
+ * Every browser-only read a route's SERVER graph holds that no browser will ever run. A page's
+ * imports are server-rendered — an island is reached by a `src` string, never an import — so a
+ * module there runs in a browser only if some island's own graph imports it too. Anything else
+ * renders its server state (nothing, or `loading`) forever, at 200. `hydrate: 'never'` boots no
+ * island at all, so every read on such a route is reported. One finding per MODULE: a layout every
+ * page imports is one mistake, not one per route.
  */
 export async function liveRouteGaps(
   root: string,
   entries: readonly RouteEntry[],
 ): Promise<readonly LiveRouteGap[]> {
+  const inBrowser = await islandModules(root);
+  const reported = new Set<string>();
   const gaps: LiveRouteGap[] = [];
   for (const entry of entries) {
     if (entry.surface === 'api') continue;
-    if (entry.islands.length > 0 && entry.config.hydrate !== 'never') continue;
-    const reach = await liveReachOf(root, entry.file);
-    if (reach === undefined) continue;
-    gaps.push({
-      ...reach,
-      route: entry.path,
-      file: entry.file,
-      hydrate: entry.config.hydrate,
-      islands: entry.islands,
-    });
+    const never = entry.config.hydrate === 'never';
+    for (const read of await browserOnlyReads(root, entry.file)) {
+      if (reported.has(read.at) || (!never && inBrowser.has(read.at))) continue;
+      reported.add(read.at);
+      gaps.push({
+        ...read,
+        route: entry.path,
+        file: entry.file,
+        hydrate: entry.config.hydrate,
+        islands: entry.islands,
+      });
+    }
   }
   return gaps;
 }
@@ -161,14 +203,12 @@ export async function liveRouteGaps(
 export const liveRouteFindingFor = (gap: LiveRouteGap): Finding => ({
   code: 'X_LIVE_ROUTE_NO_ISLAND',
   cause:
-    `${gap.route} reads ${gap.hook}() (${gap.at}) and ` +
-    (gap.islands.length === 0
-      ? 'declares no island'
-      : `declares hydrate: 'never' beside ${gap.islands.join(', ')}`) +
-    ', so no module of this route ever runs in a browser: its rows have nowhere to arrive and the page renders its loading branch forever, at 200',
+    `${gap.route} reads ${gap.hook}() in ${gap.at}, which ` +
+    (gap.hydrate === 'never' ? `sits on a route declaring hydrate: 'never'` : 'no island imports') +
+    ' — so it only ever runs on the server, where it answers its server state (nothing, or loading) forever, at 200',
   fix:
-    `${generatorFor(gap.file)}, declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) above defineRoute in ${gap.file}, ` +
-    `and move the ${gap.hook}() read into its mount() — which is where setLiveClient() can be called`,
+    `move it into an island: ${generatorFor(gap.file)}, import ${gap.at} from that island's mount(), and declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) in ${gap.file}` +
+    (gap.hydrate === 'never' ? `, with a hydrate other than 'never'` : ''),
   docs: ERROR_DOCS_URL,
   at: gap.at,
 });

package/src/load-findings.ts

@@ -0,0 +1,51 @@
+// One cause, one step. A module that will not import was reported by up to four steps at once —
+// `contract-diff`, `budgets`, `policy` and `manifest` all load the app, and each carried the load's
+// findings — so one syntax error read as four red steps and four copies of one line (plan 101
+// slice 11 i). The `manifest` step owns them: it runs in every repo, and "does the projection
+// describe the code?" is the question a module that will not import answers first.
+
+import { loadApp } from './app-load';
+import type { Finding } from './output';
+import type { StepOutcome, VerifyStepName } from './verify-step';
+
+/** The step that reports the app's load failures. Every other step points at it. */
+export const LOAD_OWNER: VerifyStepName = 'manifest';
+
+/** What the app load reports, as the step sees it. */
+export type LoadProbe = (root: string) => Promise<{ readonly findings: readonly Finding[] }>;
+
+const keyOf = (finding: Finding): string =>
+  [finding.code, finding.at ?? '', finding.cause].join('\u0000');
+
+/**
+ * `findings` without the ones the app load raised, and an `output` line saying where they went.
+ * The step's own verdict stands on what is left: a budget the broken module left unmeasured is
+ * still this step's finding, only its cause moved.
+ */
+export async function withoutLoadFindings(
+  root: string,
+  findings: readonly Finding[],
+  load: LoadProbe = loadApp,
+): Promise<StepOutcome> {
+  const loaded = new Set((await load(root)).findings.map(keyOf));
+  const kept = findings.filter((finding) => !loaded.has(keyOf(finding)));
+  const moved = findings.length - kept.length;
+  return {
+    ok: kept.length === 0,
+    findings: kept,
+    ...(moved === 0
+      ? {}
+      : { output: `skipped: ${moved} module-load finding(s) — see ${LOAD_OWNER}` }),
+  };
+}
+
+/** The owner's half: every load finding exactly once, beside what the step found itself. */
+export async function withLoadFindings(
+  root: string,
+  findings: readonly Finding[],
+  load: LoadProbe = loadApp,
+): Promise<readonly Finding[]> {
+  const own = (await load(root)).findings;
+  const seen = new Set(own.map(keyOf));
+  return [...own, ...findings.filter((finding) => !seen.has(keyOf(finding)))];
+}

package/src/mcp-db-target.ts

@@ -10,7 +10,7 @@ import { tryResolveEnvironment } from '@ultimat3/core';
 import { pgliteDataDir } from '@ultimat3/db';
 import type { DatabaseTarget } from '@ultimat3/mcp';
 import { branchNameOf, pgliteBranchName } from './db-branch';
-import type { DevServices, Env } from './dev-services';
+import type { DevServices, Env } from './runtime-bindings';
 import { safeUrlLabel } from './safe-url-label';
 
 /**

package/src/mcp-errors.ts

@@ -54,7 +54,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --json   # the package-shape finding carries the dependency line to add',
   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_SHOT_BROWSER_MISSING: 'export CHROME_PATH=/usr/bin/google-chrome',
   X_UI_SHOT_ROUTE_UNKNOWN:
     'x routes --json   # then call the ui.* tool with one of its path values',
   X_UI_SHOT_ROUTE_UNBUDGETED:
@@ -69,6 +69,12 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x routes --json   # then resend ui.interact with steps that stay on one of its paths',
   X_UI_INTERACT_STEP_FAILED:
     'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  X_SHOT_HOST_REFUSED: 'x shot /route --allow-hosts cdn.example.com --json',
+  X_SHOT_ELEMENT_MISSING:
+    'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  X_SHOT_ELEMENT_UNREADY:
+    'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  X_SHOT_KEY_INVALID: 'x help shot --json   # a chord is modifiers then one key: Meta+K',
   // The three `ui.diff` codes. Every capture it can compare was written by `x shot` or a `ui.*`
   // tool under `.x/shot/`, so the runnable half is the command that writes one there.
   X_UI_DIFF_PATH_OUTSIDE:
@@ -88,29 +94,6 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x help shot --json   # the cause lists every request the state must answer under routes',
   X_SHOT_ISLAND_MISSING:
     'x help shot --json   # every absent picture carries its own named refusal in the run above',
-  // The six e2e-driver codes. Every one of them is raised inside a running suite, so the runnable
-  // half is the command that re-runs that suite — the cause already names the closure, the locator
-  // call or the budget, and no `x` command can edit a test for its author.
-  X_E2E_EVALUATE_UNSUPPORTED:
-    'x test e2e --json   # the cause quotes the closure; page.evaluate takes a zero-parameter arrow',
-  X_E2E_EVALUATE_CAPTURED:
-    'x test e2e --json   # the fix line names the binding to inline into the closure',
-  X_E2E_EVALUATE_THREW:
-    'x dev --json   # then run the expression the cause quotes in the browser console; the throw is the page\u2019s',
-  X_E2E_LOCATOR_EMPTY:
-    'x test e2e --json   # the fix line carries the toBeVisible() assertion to await first',
-  X_E2E_LOCATOR_AMBIGUOUS:
-    'x test e2e --json   # the fix line carries the same call with .first() on it',
-  X_E2E_SERVICE_WORKER_ABSENT: 'x build --target static --json',
-  // The four raw-CDP codes. `x doctor` for the missing browser, because that is the command whose
-  // whole job is reporting what this machine does not have; the other three are raised inside a
-  // running suite, so the runnable half is the command that re-runs it.
-  X_CDP_BROWSER_MISSING:
-    'x doctor --json   # or set CHROME_PATH to a Chrome binary; unset, the browser-backed suite skips',
-  X_CDP_LAUNCH_FAILED:
-    'x test e2e --json   # the cause carries the last lines of the browser\u2019s own stderr',
-  X_CDP_CALL_FAILED: 'x test e2e --json   # the cause names the DevTools call the browser refused',
-  X_CDP_TIMEOUT: 'x test e2e --json   # the cause names the call that never answered',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',
@@ -122,8 +105,11 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
   X_ERROR_CODE_UNRESOLVED:
     'x verify --json   # the finding names the file, the line and the name it could not resolve',
+  X_ERROR_CODE_UNTHROWN:
+    'x errors explain X_ERROR_CODE_UNTHROWN --json   # then mark the row "registered, thrown by nothing since <version>"',
   X_CLI_UNEXPECTED: 'x doctor --json',
-  X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
+  // `-p .`: an app root has no `references`, so the gate's own step runs this form (#450).
+  X_TYPECHECK_FAILED: 'bunx tsc -p . --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',
   X_TEST_FAILED: 'x test --json   # the finding carries the exact bun test invocation that failed',
   // The same two edits `vanishedSuiteFinding` names, verbatim, so both surfaces of this code hand
@@ -179,6 +165,10 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PORT_INVALID: 'docker run -e PORT=3000 my-app:latest',
   X_RUNTIME_DRIVER_SPLIT: 'x dev --json   # the boot names the driver the app installed twice',
   X_GENERATE_CONFLICT: 'x g route posts --force --json',
+  X_APP_NAME_EMPTY:
+    'x new my-app --json   # a name with letters or digits; it becomes the directory',
+  X_APP_EMPTY:
+    'x doctor --json   # then check the app root: no module under apps/ or packages/ loaded',
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   X_DEV_ALREADY_RUNNING:
     'x dev --json   # after stopping the x dev that already owns this checkout',
@@ -218,8 +208,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // consent and stays in the cause: it is the answer only for a container with a fixed argv.
   X_SEED_ENVIRONMENT:
     'x db seed --dry-run --json   # then name the tier: x db seed <name> --tier dev --json',
+  // The finding's own `fix:` is the concrete edit (`boundary-findings.ts`): the file and the import.
   X_BOUNDARY_SITE_TO_APP:
-    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+    'x verify --only boundaries --json   # each finding names the import to delete, and where',
   X_BOUNDARY_SHARED_LEAF:
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
   X_BOUNDARY_APP_TO_API:
@@ -228,6 +219,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
   X_BOUNDARY_SERVICE_TO_HTTP:
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_SURFACE_IMPORT:
+    'x verify --only boundaries --json   # then move the imported code into shared/',
   // The app's own guards. All three are reported by the gate and by nothing else, so the runnable
   // half is the gate — the narrowing behind the `#` is the edit, because only the finding knows
   // which file in `guards/` is the one to open.
@@ -242,6 +235,17 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // Render's code, thrown here by the bundler half: the cause names the specifier and the file it
   // resolved to, and `x g island` is what puts that file where the page already says it is.
   X_ISLAND_INVALID: 'x routes --json   # the cause names the src; then: x g island <name>',
+  // The four slice-11 codes: generated code that passed the gate and failed at runtime.
+  X_PERMISSION_UNGRANTED:
+    'x verify --only policy --json   # then add the permission to a role in apps/web/shared/roles.ts',
+  X_JOB_UNREGISTERED:
+    'x manifest --json   # after listing the module under jobs: [...] in apps/web/api/index.ts',
+  X_FEATURE_UNKNOWN:
+    'x entities --json   # then x g resource <feature> for the one the cause names',
+  X_BUDGET_PARAMS_UNDECLARED:
+    'x build --target static --json   # after adding prerender() with one real path to the route',
+  X_ROUTE_ASYNC_PAGE:
+    'x verify --only budgets --json   # after moving each await in Page into export const load',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/mcp-host.ts

@@ -34,12 +34,8 @@ import { loadApp } from './app-load';
 import { appManifest, policyFacts } from './app-manifest';
 import { runVerify, VERIFY_STEPS } from './cmd-verify';
 import { declareDevEnvironment } from './dev-environment';
-import type { RunningServices } from './dev-runtime';
-import { startServices } from './dev-runtime';
-import type { DevServices, Env } from './dev-services';
-import { resolveServices } from './dev-services';
 import { loadCodeFixes } from './error-fixes';
-import { CliNotImplementedError } from './errors';
+import { BadFlagError, CliNotImplementedError } from './errors';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
@@ -48,6 +44,10 @@ import { parseBunTest } from './mcp-test-output';
 import { type UiCapabilities, uiCapabilities } from './mcp-ui';
 import { readMigrations } from './migrations';
 import { retryMemo } from './retry-memo';
+import type { DevServices, Env } from './runtime-bindings';
+import { resolveServices } from './runtime-bindings';
+import type { RunningServices } from './runtime-services';
+import { startServices } from './runtime-services';
 import { testEnvOverrides } from './test-dotenv';
 
 export interface DevHostInput {
@@ -180,6 +180,24 @@ export async function readOnlyRows(
   return { columns, rows: kept.map((row) => columns.map((column) => row[column])), guards };
 }
 
+/**
+ * `bun test`'s argv for a `test.run` filter. A filter is a PATH, and one starting with `-` is a
+ * `bun test` flag — `--preload ./x.ts` loads a module into the child — so it is refused rather
+ * than forwarded: a filter is a path, and no path this suite has starts with `-`.
+ */
+export function testRunArgv(filter: string | undefined): readonly string[] {
+  if (filter === undefined) return ['bun', 'test'];
+  if (filter.trimStart().startsWith('-')) {
+    throw new BadFlagError({
+      flag: 'filter',
+      command: 'mcp serve',
+      reason: `test.run's filter "${filter}" starts with "-", which bun test would read as its own flag`,
+      fix: 'call test.run with a path filter such as packages/cli/src, or with no filter',
+    });
+  }
+  return ['bun', 'test', filter];
+}
+
 function capabilities(
   input: DevHostInput,
   lazy: LazyServices,
@@ -249,13 +267,10 @@ function capabilities(
       // 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 }),
-        },
-      );
+      const result = await runner(testRunArgv(filter), {
+        cwd: root,
+        ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
+      });
       return parseBunTest(execOutput(result), result.durationMs);
     },
 

package/src/mcp-ui-diff.ts

@@ -81,6 +81,32 @@ async function readCapture(root: string, relative: string, field: string): Promi
   return file.bytes();
 }
 
+/**
+ * The symlink half for the one path this tool WRITES: `realpath` of the nearest directory that
+ * exists above `out`, held under the shot directory's real location — `readCapture`'s rule. The
+ * lexical check alone let `.x/shot/<link-to-elsewhere>/diff.png` write wherever the link pointed.
+ */
+async function assertWritable(root: string, path: string): Promise<void> {
+  let dir = dirname(path);
+  while (!(await exists(dir)) && dirname(dir) !== dir) dir = dirname(dir);
+  const real = await realpath(dir);
+  const shotDir = await realpath(resolve(root, SHOT_DIR));
+  if (!under(real, shotDir)) {
+    throw new UltimateError({
+      code: 'X_UI_DIFF_PATH_OUTSIDE',
+      cause: `out is under a link to ${real}, which is not inside ${shotDir}`,
+      fix: SHOT_FIX,
+      meta: { field: 'out', path, real, shotDir },
+    });
+  }
+}
+
+const exists = (dir: string): Promise<boolean> =>
+  realpath(dir).then(
+    () => true,
+    () => false,
+  );
+
 /**
  * The seam reads 8-bit RGBA and nothing else. A PNG in any other shape — Chrome's RGB when the page
  * is opaque, a palette from an optimiser — goes once through Bun's codecs, which always write the
@@ -126,6 +152,7 @@ export async function diffShots(deps: DiffDeps, input: UiDiffInput): Promise<UiD
   }
   const { width, height } = after;
   const result = diffPixels(before.pixels, after.pixels, width, height, input.threshold);
+  await assertWritable(root, diff);
   await Bun.write(diff, encodeImage({ width, height, pixels: result.diffRgba }));
   return {
     ok: true,

package/src/mcp-ui-inspect.ts

@@ -11,8 +11,8 @@
 import { join } from 'node:path';
 import type { UiInspectInput, UiInspectResult, UiInspectSelector } from '@ultimat3/mcp';
 import { UI_INSPECT_LIMITS } from '@ultimat3/mcp';
-import type { AxNode, ScrapeDriver, ScrapePage } from '@ultimat3/scraping';
-import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
+import type { AxNode, ShotDriver, ShotPage } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
 import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import type { ShotServer } from './shot-server';
 import type { ShotVerdict } from './shot-verdict';
@@ -23,7 +23,7 @@ export interface InspectDeps {
   readonly root: string;
   /** The memoised scratch server (or the running `x dev`), as `uiCapabilities` hands it out. */
   readonly boot: () => Promise<ShotServer>;
-  readonly driver: (viewport: UiInspectInput['viewport']) => Promise<ScrapeDriver>;
+  readonly driver: (viewport: UiInspectInput['viewport']) => Promise<ShotDriver>;
 }
 
 /** What the page answered before the parser had a say — `null` selectors when it answered nothing. */
@@ -45,7 +45,7 @@ export type InspectSpecInput = Pick<
  * a page that refuses evaluation is a page with no facts, and the verdict — not a throw here — is
  * what says why. Shared by `ui.inspect` and `ui.interact`, so both read the same facts.
  */
-export async function readInspect(page: ScrapePage, spec: InspectSpecInput): Promise<Seen> {
+export async function readInspect(page: ShotPage, spec: InspectSpecInput): Promise<Seen> {
   const expression = inspectExpression({
     selectors: spec.selectors,
     styles: spec.styles,

package/src/mcp-ui-interact.ts

@@ -14,8 +14,8 @@ import { join } from 'node:path';
 import { isUltimateError, toUltimateError, UltimateError } from '@ultimat3/core';
 import type { UiInteractInput, UiInteractResult, UiInteractStepResult } from '@ultimat3/mcp';
 import { UI_INTERACT_LIMITS } from '@ultimat3/mcp';
-import type { ScrapePage } from '@ultimat3/scraping';
-import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
+import type { ShotPage } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS } from './cdp-shot-clock';
 import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import type { InspectDeps, Seen } from './mcp-ui-inspect';
 import { readInspect, selectorsOf } from './mcp-ui-inspect';
@@ -130,7 +130,7 @@ const describe = (step: InteractStep): string => {
 };
 
 async function perform(
-  page: ScrapePage,
+  page: ShotPage,
   step: InteractStep,
   sleep: (ms: number) => Promise<void>,
 ): Promise<void> {
@@ -153,19 +153,25 @@ async function perform(
  * Before any keystroke: a password field's value would land in the PNG, the verdict's console and
  * an agent's transcript. The read is the driver's own `query`, so the fake answers it offline.
  */
-async function refuseSecretField(
-  page: ScrapePage,
-  step: InteractStep,
-  index: number,
-): Promise<void> {
-  if (step.kind !== 'type') return;
-  const [first] = await page.query(step.selector);
-  if (first?.attrs['type'] !== 'password') return;
+/** The `type` of the focused element — what a `press` step's key lands in. */
+export const ACTIVE_FIELD_TYPE =
+  '(function(){var a=document.activeElement;return a&&a.getAttribute?a.getAttribute("type"):null})()';
+
+async function refuseSecretField(page: ShotPage, step: InteractStep, index: number): Promise<void> {
+  if (step.kind !== 'type' && step.kind !== 'press') return;
+  // A `press` goes to whatever has focus: `focus` a password field, then eleven presses, typed
+  // the password the `type` guard refused — so the focused element is asked before each key.
+  const secret =
+    step.kind === 'type'
+      ? (await page.query(step.selector))[0]?.attrs['type'] === 'password'
+      : (await page.evaluate(ACTIVE_FIELD_TYPE)) === 'password';
+  if (!secret) return;
+  const target = step.kind === 'type' ? JSON.stringify(step.selector) : 'the focused element';
   throw new UltimateError({
     code: 'X_UI_INTERACT_SECRET_FIELD',
-    cause: `step ${index} would type into ${JSON.stringify(step.selector)}, an <input type="password">`,
+    cause: `step ${index} would type into ${target}, an <input type="password">`,
     fix: FIX.secret,
-    meta: { step: index, selector: step.selector },
+    meta: { step: index, ...(step.kind === 'type' ? { selector: step.selector } : {}) },
   });
 }
 
@@ -177,11 +183,11 @@ export interface StepsRun {
 
 /**
  * The steps in order, each followed by a settle and one poll interval, each checked against the
- * origin. A scraping error is wrapped, never passed through: the agent needs to know WHICH step,
+ * origin. A driver error is wrapped, never passed through: the agent needs to know WHICH step,
  * and the fix is a selector `ui.inspect` reports rather than whatever the driver's fix names.
  */
 export async function runSteps(
-  page: ScrapePage,
+  page: ShotPage,
   steps: readonly InteractStep[],
   settle: () => Promise<IslandCount | null>,
   origin: string,