@ultimat3/cli 20.2.1 → 22.0.0

package/src/browser-launcher-fake-html.ts

@@ -0,0 +1,80 @@
+// CSS selectors over an HTML string, on Bun's own `HTMLRewriter`: the `query()` the offline
+// `fakeShotDriver` answers from markup. The selector subset is lol-html's — type, `#id`, `.class`,
+// `[attr]`, `[attr=value]`, descendant and child combinators. No box and no hit-target on any
+// answer: this has no layout engine, and a fabricated box would make a covered button clickable.
+import type { ElementSnapshot } from './browser-launcher-port';
+
+/** Elements with no end tag: `onEndTag` never fires for them, so they close on open. */
+const VOID_TAGS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'source',
+  'track',
+  'wbr',
+]);
+
+const HIDDEN_STYLE = /(?:^|;)\s*(?:display\s*:\s*none|visibility\s*:\s*hidden)\s*(?:;|$)/i;
+
+const visible = (tag: string, attrs: ReadonlyMap<string, string>): boolean =>
+  !attrs.has('hidden') &&
+  !(tag === 'input' && attrs.get('type')?.toLowerCase() === 'hidden') &&
+  !HIDDEN_STYLE.test(attrs.get('style') ?? '') &&
+  attrs.get('aria-hidden') !== 'true';
+
+interface Open {
+  readonly tag: string;
+  readonly attrs: Map<string, string>;
+  readonly parts: string[];
+}
+
+const finish = (open: Open): ElementSnapshot => ({
+  tag: open.tag,
+  attrs: Object.fromEntries(open.attrs),
+  text: open.parts.join('').replaceAll(/\s+/g, ' ').trim(),
+  value: open.attrs.get('value') ?? '',
+  visible: visible(open.tag, open.attrs),
+  enabled: !open.attrs.has('disabled') && open.attrs.get('aria-disabled') !== 'true',
+});
+
+/** Every element matching `selector`, as the markup states it. A selector lol-html refuses throws. */
+export async function queryHtml(
+  html: string,
+  selector: string,
+): Promise<readonly ElementSnapshot[]> {
+  const done: ElementSnapshot[] = [];
+  const open: Open[] = [];
+  const rewriter = new HTMLRewriter().on(selector, {
+    element(element): void {
+      const tag = element.tagName.toLowerCase();
+      const attrs = new Map<string, string>();
+      for (const [name, value] of element.attributes) attrs.set(name.toLowerCase(), value);
+      const record: Open = { tag, attrs, parts: [] };
+      if (VOID_TAGS.has(tag)) {
+        done.push(finish(record));
+        return;
+      }
+      open.push(record);
+      element.onEndTag(() => {
+        const index = open.lastIndexOf(record);
+        if (index !== -1) open.splice(index, 1);
+        done.push(finish(record));
+      });
+    },
+    text(chunk): void {
+      // Every OPEN match: `div, span` matches both, and both contain the text.
+      for (const record of open) record.parts.push(chunk.text);
+    },
+  });
+  await rewriter.transform(new Response(html)).text();
+  // Never closed is malformed markup; the element still matched, so it is still reported.
+  for (const record of open) done.push(finish(record));
+  return done;
+}

package/src/browser-launcher-fake.ts

@@ -0,0 +1,165 @@
+// `fakeShotDriver`: a `ShotDriver` over recorded pages, so every `x shot` and `ui.*` test runs with
+// no Chrome. It parses markup and runs none of it — `query()` is answered from the HTML,
+// `evaluate()` from a recorded table, and a click follows `data-goto` or an `<a href>`. What it
+// cannot know it refuses by name rather than inventing: no layout box, and no accessibility tree.
+import { hostDecision, notImplemented } from '@ultimat3/core';
+import { CdpCallFailedError } from '@ultimat3/testing';
+import { queryHtml } from './browser-launcher-fake-html';
+import type {
+  CaptureClip,
+  ElementSnapshot,
+  NetworkEntry,
+  ShotColorScheme,
+  ShotDriver,
+  ShotPage,
+  ShotSession,
+  ShotSessionInit,
+} from './browser-launcher-port';
+import { awaitReady } from './cdp-shot-element';
+import { ShotHostRefusedError } from './cdp-shot-errors';
+import { parseKeyChord } from './cdp-shot-keys';
+
+export const FAKE_SHOT_DRIVER = 'fake';
+
+/** One recorded page: its url, its markup, and `expression -> JSON text` for `evaluate()`. */
+export interface FakeShotPage {
+  readonly url: string;
+  readonly html: string;
+  readonly evaluate?: Readonly<Record<string, string>> | undefined;
+}
+
+/** A PNG signature, and nothing behind it: deterministic bytes, never a render. */
+export const FAKE_PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * Different deterministic bytes for every framing fact that was set — one per rectangle, one per
+ * colour preference — so a caller that dropped the clip or the scheme fails a test here, which is
+ * the only place a framing knob can be proved without a browser (issue #338).
+ */
+export const framedPng = (clip: CaptureClip | undefined, scheme: ShotColorScheme): Uint8Array => {
+  const notes =
+    (clip === undefined
+      ? ''
+      : ` clip ${String(clip.x)},${String(clip.y)},${String(clip.width)},${String(clip.height)}`) +
+    (scheme === 'no-preference' ? '' : ` scheme ${scheme}`);
+  if (notes === '') return FAKE_PNG;
+  const suffix = new TextEncoder().encode(notes);
+  const out = new Uint8Array(FAKE_PNG.length + suffix.length);
+  out.set(FAKE_PNG);
+  out.set(suffix, FAKE_PNG.length);
+  return out;
+};
+
+const normalise = (url: string): string => {
+  try {
+    return new URL(url).toString();
+  } catch {
+    return url;
+  }
+};
+
+function fakePage(byUrl: ReadonlyMap<string, FakeShotPage>, init: ShotSessionInit): ShotPage {
+  let current: FakeShotPage | undefined;
+  let scheme: ShotColorScheme = 'no-preference';
+  const network: NetworkEntry[] = [];
+  const url = (): string => current?.url ?? 'about:blank';
+
+  const navigate = (to: string): void => {
+    const page = byUrl.get(normalise(to));
+    if (page === undefined) {
+      throw new CdpCallFailedError({
+        method: `Page.navigate to ${to}`,
+        detail: 'fakeShotDriver() has no page recorded at that url',
+      });
+    }
+    current = page;
+    network.push({
+      method: 'GET',
+      url: page.url,
+      status: 200,
+      resourceType: 'document',
+      at: init.clock.now().getTime(),
+    });
+  };
+
+  const query = (selector: string): Promise<readonly ElementSnapshot[]> =>
+    queryHtml(current?.html ?? '', selector);
+
+  const ready = (selector: string, options?: Parameters<ShotPage['waitFor']>[1]) =>
+    awaitReady({
+      selector,
+      state: options?.state ?? 'actionable',
+      timeoutMs: options?.timeout ?? init.timeoutMs,
+      clock: init.clock,
+      url,
+      snapshot: async () => (await query(selector))[0],
+    });
+
+  return {
+    url,
+    async goto(to) {
+      if (!hostDecision(to, init.rules.allowHosts).allowed) {
+        throw new ShotHostRefusedError({ url: to, allowHosts: init.rules.allowHosts });
+      }
+      navigate(to);
+    },
+    waitFor: (selector, options) => ready(selector, options),
+    async click(selector, options) {
+      const target = await ready(selector, options);
+      // What the browser would do with the click, as far as markup can say: follow the link.
+      const next =
+        target.attrs['data-goto'] ?? (target.tag === 'a' ? target.attrs['href'] : undefined);
+      if (next !== undefined) navigate(new URL(next, url()).toString());
+    },
+    async type(selector, _text, options) {
+      await ready(selector, options);
+    },
+    async focus(selector, options) {
+      await ready(selector, options);
+    },
+    async press(chord) {
+      parseKeyChord(chord);
+    },
+    async accessibility() {
+      return notImplemented(
+        'accessibility() on fakeShotDriver()',
+        'assert on the markup with page.query(selector) — a role read off the HTML would hide the element a screen reader cannot name, which is the finding this read exists for',
+      );
+    },
+    query,
+    async evaluate(expression) {
+      const table = current?.evaluate ?? {};
+      const recorded = Object.hasOwn(table, expression) ? table[expression] : undefined;
+      if (recorded === undefined) {
+        throw new CdpCallFailedError({
+          method: 'Runtime.evaluate',
+          detail: 'fakeShotDriver() has no answer recorded for that expression on this page',
+        });
+      }
+      return JSON.parse(recorded) as unknown;
+    },
+    async screenshot(options) {
+      return framedPng(options?.clip, scheme);
+    },
+    async colorScheme(next) {
+      scheme = next;
+    },
+    async prepare() {},
+    console: () => [],
+    pageErrors: () => [],
+    pageErrorsDropped: () => 0,
+    network: () => [...network],
+    networkDropped: () => 0,
+  };
+}
+
+/** A driver whose every session reads from `pages`. An unrecorded url is refused, never fetched. */
+export function fakeShotDriver(pages: readonly FakeShotPage[]): ShotDriver {
+  const byUrl = new Map(pages.map((page) => [normalise(page.url), page]));
+  return {
+    name: FAKE_SHOT_DRIVER,
+    async open(init): Promise<ShotSession> {
+      return { page: fakePage(byUrl, init), close: async () => undefined };
+    },
+  };
+}

package/src/browser-launcher-port.ts

@@ -0,0 +1,159 @@
+// The browser surface `x shot` and the dev MCP server's `ui.*` tools drive, declared here and
+// nowhere else. `cdp-shot-driver.ts` implements it over raw CDP; a test hands in a fake. Every
+// member is one a shot or a `ui.*` call reads. A member nothing reads is one the raw driver would
+// have to build and nothing would test, and that is how a port rots.
+import type { Clock } from '@ultimat3/core';
+
+/** What the browser is told the OS prefers. `'no-preference'` CLEARS the override. */
+export type ShotColorScheme = 'light' | 'dark' | 'no-preference';
+
+/** CSS pixels, top-left origin: the space `getBoundingClientRect()` answers in. */
+export interface CaptureClip {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** `fullPage`, or a `clip` — never both. */
+export interface ShotCapture {
+  readonly fullPage?: boolean | undefined;
+  readonly clip?: CaptureClip | undefined;
+}
+
+export interface ConsoleLine {
+  readonly level: 'log' | 'info' | 'warn' | 'error' | 'debug';
+  readonly text: string;
+  readonly at: number;
+}
+
+/** An uncaught exception the page threw. Not a `ConsoleLine`: a throw calls no console method. */
+export interface PageError {
+  readonly message: string;
+  /** Absent when the exception carried no stack, never `''`. */
+  readonly stack?: string | undefined;
+  readonly at: number;
+}
+
+export type ShotResourceType =
+  | 'document'
+  | 'stylesheet'
+  | 'image'
+  | 'media'
+  | 'font'
+  | 'script'
+  | 'xhr'
+  | 'fetch'
+  | 'websocket'
+  | 'other';
+
+export interface NetworkEntry {
+  readonly method: string;
+  readonly url: string;
+  /** Absent while in flight, or when the request was refused. */
+  readonly status?: number | undefined;
+  readonly resourceType: ShotResourceType;
+  readonly at: number;
+  /** `host`: the allow list refused it. The other two are what a scraping driver can also say. */
+  readonly refused?: 'blocked' | 'host' | 'robots' | undefined;
+}
+
+/** What a screen reader is told about one element — the browser's computed role and name. */
+export interface AxNode {
+  readonly role: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly value?: string | undefined;
+  readonly focused?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly ignored: boolean;
+}
+
+export interface ElementBox {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** One element as of one observation — a value, never a live handle. */
+export interface ElementSnapshot {
+  readonly tag: string;
+  readonly attrs: Readonly<Record<string, string>>;
+  readonly text: string;
+  readonly value: string;
+  readonly visible: boolean;
+  readonly enabled: boolean;
+  /** Absent on a driver with no layout engine; never a fabricated zero box. */
+  readonly box?: ElementBox | undefined;
+  /** Whether a click at the element's centre lands on it. Absent: no layout. */
+  readonly hitTarget?: boolean | undefined;
+}
+
+/** Each level implies the ones before it. */
+export type ActionabilityState = 'attached' | 'visible' | 'enabled' | 'actionable';
+
+export interface WaitOptions {
+  readonly state?: ActionabilityState | undefined;
+  /** Milliseconds. Falls back to the session's `timeoutMs`. */
+  readonly timeout?: number | undefined;
+}
+
+export interface AccessibilityOptions {
+  readonly max?: number | undefined;
+}
+
+/** Every wait goes through this, so a test of a 30-second deadline finishes in microseconds. */
+export interface ShotClock extends Clock {
+  sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+
+export interface ShotPage {
+  url(): string;
+  /** Refused before a byte leaves when the host is outside the session's `allowHosts`. */
+  goto(url: string, options?: { readonly timeout?: number | undefined }): Promise<void>;
+  /** Blocks until the first match reaches `state` (default `actionable`), then answers it. */
+  waitFor(selector: string, options?: WaitOptions): Promise<ElementSnapshot>;
+  click(selector: string, options?: WaitOptions): Promise<void>;
+  /** Appends. */
+  type(selector: string, text: string, options?: WaitOptions): Promise<void>;
+  focus(selector: string, options?: WaitOptions): Promise<void>;
+  /** `'Meta+K'`, `'Escape'`, `'Shift+Tab'` — on whatever holds focus. */
+  press(chord: string): Promise<void>;
+  accessibility(selector: string, options?: AccessibilityOptions): Promise<readonly AxNode[]>;
+  query(selector: string): Promise<readonly ElementSnapshot[]>;
+  /** The expression's result, `unknown` — parse it, never cast it. */
+  evaluate(expression: string): Promise<unknown>;
+  /** PNG bytes. */
+  screenshot(options?: ShotCapture): Promise<Uint8Array>;
+  colorScheme(scheme: ShotColorScheme): Promise<void>;
+  /** Runs in every document this page navigates to, before the document's own scripts. */
+  prepare(expression: string): Promise<void>;
+  /** The bounded tails, and how many entries each bound threw away. */
+  console(): readonly ConsoleLine[];
+  pageErrors(): readonly PageError[];
+  pageErrorsDropped(): number;
+  network(): readonly NetworkEntry[];
+  networkDropped(): number;
+}
+
+export interface ShotSessionInit {
+  /** Every error cause raised inside the session carries it. */
+  readonly name: string;
+  /** Never `*` from a shot: a headless browser inside your network is an SSRF surface. */
+  readonly rules: { readonly allowHosts: readonly string[] };
+  readonly clock: ShotClock;
+  /** Per-operation default, in ms. */
+  readonly timeoutMs: number;
+}
+
+export interface ShotSession {
+  readonly page: ShotPage;
+  /** Idempotent and never throws: it runs in a `finally`, beside the run's real failure. */
+  close(): Promise<void>;
+}
+
+export interface ShotDriver {
+  readonly name: string;
+  open(init: ShotSessionInit): Promise<ShotSession>;
+}

package/src/browser-launcher.ts

@@ -1,26 +1,14 @@
-// The app's own browser library, resolved from the app's own `node_modules` — never a dependency
-// of this package. `@ultimat3/scraping` declares the launcher's shape structurally (`cdp-port.ts`)
-// precisely so the framework can drive a browser without shipping one, and `x shot` is a CLI
-// command holding to the same bargain: the app installs `puppeteer-core`, the CLI asks for it.
-//
-// Two ways to get a browser, and the second is the one production uses. `localBrowser()` starts
-// Chrome in this container; `remoteBrowser({ cdpUrl })` ATTACHES to one somebody else is running,
-// which is what every stealth provider sells — a session created over their API answers with a
-// `wss://` CDP endpoint and a real, unfingerprintable Chromium behind it. `driver-cdp.ts` has
-// called attach its primary path since it shipped, and until now no CLI command could reach it.
+// Which browser `x shot` drives, and the raw-CDP driver over it (`cdp-shot-driver.ts`). No browser
+// library, in the app or here: Chrome is launched on its debugging pipe by `@ultimat3/testing`'s
+// launcher — the one `x verify`'s e2e step already runs on — or ATTACHED to over `--cdp-url`,
+// which is what every stealth provider sells. Until 22.0.0 this resolved the APP's `puppeteer-core`,
+// so `x shot` needed an install the framework could not make, and two launchers drifted.
 
 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, CONTAINER_CHROME_ARGS } from './cdp-launch';
-
-/**
- * The one library this works against. Playwright is not an alternative and is not a flag:
- * `packages/scraping/src/cdp-port.ts` records that its `connectOverCDP` cannot perform the
- * WebSocket upgrade under Bun (oven-sh/bun#9911), verified against puppeteer-core 25.8.0.
- */
-export const BROWSER_PACKAGE = 'puppeteer-core';
+import { CHROME_CANDIDATES } from '@ultimat3/testing';
+import type { ShotDriver } from './browser-launcher-port';
+import { cdpShotDriver } from './cdp-shot-driver';
 
 /** Where a browser binary is named when the flag does not name one. Read in this order. */
 export const BROWSER_PATH_VARS = ['PUPPETEER_EXECUTABLE_PATH', 'CHROME_PATH'] as const;
@@ -37,33 +25,7 @@ export const BROWSER_CDP_URL_VAR = 'SCRAPE_CDP_URL';
 const CDP_SCHEMES = ['ws:', 'wss:', 'http:', 'https:'] as const;
 
 /**
- * A missing browser is an instruction, not a crash (axiom 4). The cause distinguishes the two
- * shapes — nothing resolved, or something resolved that is not a launcher — while the fix is the
- * same install either way, because both are answered by putting the real package in the app.
- */
-export class ShotBrowserMissingError extends UltimateError {
-  constructor(input: { root: string; detail: string }) {
-    super({
-      code: 'X_SHOT_BROWSER_MISSING',
-      // The same install either way: attaching over CDP needs no Chrome on this box, but it still
-      // needs a client that speaks the protocol, and `puppeteer-core` is that client.
-      cause: `x shot drives a real browser and ${BROWSER_PACKAGE} ${input.detail} from ${input.root}`,
-      // One literal, not `bun add -d ${BROWSER_PACKAGE}`: `fix-scan.ts` can only read a fix that IS
-      // one literal, and a fix line the gate cannot read is a fix line nothing holds to the
-      // contract. `browser-launcher.test.ts` pins it against the constant instead.
-      fix: 'bun add -d puppeteer-core',
-      meta: { root: input.root, package: BROWSER_PACKAGE },
-    });
-  }
-}
-
-/**
- * The OTHER half of "no browser": the library is installed and there is no Chrome for it to start.
- *
- * The same code as the class above because it is the same question to a reader — `x shot` has no
- * browser — and a code is a stable public name, not a taxonomy. The cause and the fix are what
- * differ, and they are the half that is acted on: `bun add -d puppeteer-core` cannot install
- * Chrome, and `export CHROME_PATH=…` cannot install a client that speaks CDP.
+ * `x shot` has no browser: none was named and none of the probed paths is on disk.
  *
  * Raised BEFORE the dev server, which is the whole point of it: the launch that used to report this
  * happens inside `driver.open()`, one embedded Postgres past the point where the answer was already
@@ -74,8 +36,7 @@ export class ShotChromeMissingError extends UltimateError {
     super({
       code: 'X_SHOT_BROWSER_MISSING',
       cause: `x shot launches a browser here and none was named or found — no ${BROWSER_PATH_VARS.join(' or ')} is set, and none of ${CHROME_CANDIDATES.join(', ')} is on disk`,
-      // One literal, for `fix-scan.ts`'s reason — the same rule the class above states. It names an
-      // export rather than an install because a path is the one repair that works whatever the
+      // One literal, so `fix-scan.ts` can read it. A path is the one repair that works whatever the
       // browser is and wherever the distribution put it; `--cdp-url` is the answer for a box that
       // will never have one, and it is a flag `x shot` already ships.
       fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome or Chromium binary; a box that will never have one attaches instead: x shot / --cdp-url wss://cdp.example.com/session/abc',
@@ -84,47 +45,20 @@ export class ShotChromeMissingError extends UltimateError {
   }
 }
 
-/**
- * Structural, because this is somebody else's module: a namespace object, a CJS `default`, or a
- * transpiled interop wrapper are all shapes `import()` legitimately hands back, and only one
- * question decides — is the method this run needs there to call?
- *
- * WHICH method is the run's, not this function's. `cdp-port.ts` declares `launch` and `connect`
- * both optional precisely so an attach-only provider SDK satisfies the port, and asking for
- * `launch` when the run is going to `connect` would refuse exactly the library that works.
- */
-const launcherIn = (module: unknown, method: 'launch' | 'connect'): CdpLauncherLike | undefined => {
-  if (typeof module !== 'object' || module === null) return undefined;
-  const candidate = module as Record<string, unknown>;
-  if (typeof candidate[method] === 'function') return candidate as CdpLauncherLike;
-  // `module.exports.default = module.exports` is a real CJS interop shape, so the self-reference is
-  // refused rather than followed: one unbounded recursion here is a stack overflow instead of the
-  // instruction this whole function exists to produce.
-  const inner = candidate['default'];
-  if (inner === undefined || inner === candidate) return undefined;
-  return launcherIn(inner, method);
-};
-
 export interface AppBrowserOptions {
-  readonly root: string;
-  /** `--browser`, then `PUPPETEER_EXECUTABLE_PATH`, then `CHROME_PATH`. */
+  /** `--browser`, then `PUPPETEER_EXECUTABLE_PATH`, then `CHROME_PATH`, then the probe. */
   readonly executablePath?: string | undefined;
   /**
    * A CDP endpoint to ATTACH to. When it is set nothing is launched here and `executablePath` is
-   * not read: the browser is somebody else's, and closing it ends their session too — which
-   * `remoteBrowser()` does deliberately, so a provider stops billing for a run that ended.
+   * not read: the browser is somebody else's, and closing it ends their session too — deliberately,
+   * so a provider stops billing for a run that ended.
    */
   readonly cdpUrl?: string | undefined;
   /**
-   * The page size this browser lays out at. A LAUNCH option and not a per-capture one, because
-   * that is the only place the shipped port has for it: `CaptureRequest` is `fullPage` alone
-   * (`packages/scraping/src/page.ts`), so the viewport IS the frame of every picture taken with
-   * this driver — which is why `x shot --island` builds one browser per declared viewport.
+   * The page size this browser lays out at — the frame of every viewport picture, which is why
+   * `x shot --island` builds one browser per declared viewport.
    */
   readonly viewport?: { readonly width: number; readonly height: number } | undefined;
-  /** Test seam: the resolver and the loader, so a test proves the refusal without an install. */
-  readonly resolve?: (specifier: string, from: string) => string;
-  readonly load?: (path: string) => Promise<unknown>;
 }
 
 /** True when a named executable is really there — a bad `--browser` is refused before a boot. */
@@ -133,12 +67,9 @@ export const browserBinaryExists = (path: string): boolean => existsSync(path);
 /**
  * The path a run will launch, or `undefined` when this machine has no browser to launch.
  *
- * NOT "let the library find its own": `puppeteer-core` ships no browser and has no default, so a
- * launch with no `executablePath` throws ``An `executablePath` or `channel` must be specified``
- * from inside somebody else's library, one dev-server boot after the point where the answer was
- * knowable. So the last step is a PROBE — the same four paths `cdp-launch.ts` already tries for the
- * e2e driver, imported rather than restated, because two lists of Chrome locations that must agree
- * is the drift axiom 2 refuses.
+ * The last step is a PROBE — the four paths `cdp-launch.ts` tries for the e2e driver, imported
+ * rather than restated, because two lists of Chrome locations that must agree is the drift axiom 2
+ * refuses — so a box with no browser is refused before a dev-server boot, not one launch later.
  *
  * A value NAMED in the flag or the environment is answered without touching the filesystem, even
  * when nothing is there: an operator who typed a path has a belief about which binary runs, and
@@ -192,54 +123,16 @@ export const cdpUrlProblem = (url: string): string | undefined => {
 };
 
 /**
- * The app's `puppeteer-core`, as a `ScrapeDriver`. Resolved FROM THE APP ROOT rather than from
- * this module: `import('puppeteer-core')` here would find the CLI's own tree, which by design has
- * no such dependency, and would answer "missing" for an app that installed it correctly.
+ * The driver a run photographs with. Refused HERE when there is nothing to launch and nothing to
+ * attach to, so a missing browser costs no dev-server boot.
  */
-export async function appBrowser(options: AppBrowserOptions): Promise<ScrapeDriver> {
-  const resolve = options.resolve ?? ((specifier, from) => Bun.resolveSync(specifier, from));
-  const load = options.load ?? ((path: string) => import(path) as Promise<unknown>);
-  const method = options.cdpUrl === undefined ? 'launch' : 'connect';
-  let entry: string;
-  try {
-    entry = resolve(BROWSER_PACKAGE, options.root);
-  } catch {
-    throw new ShotBrowserMissingError({ root: options.root, detail: 'does not resolve' });
-  }
-  const launcher = launcherIn(await load(entry), method);
-  if (launcher === undefined) {
-    throw new ShotBrowserMissingError({
-      root: options.root,
-      detail: `resolved to ${entry}, which exports no ${method}()`,
-    });
-  }
-  if (options.cdpUrl !== undefined) {
-    return remoteBrowser({
-      launcher,
-      cdpUrl: options.cdpUrl,
-      // The viewport reaches `connect()` the same way it reaches `launch()` — through the
-      // pass-through slot — so `x shot --island`'s one-browser-per-viewport loop is unchanged by
-      // which half of the port a run took.
-      ...(options.viewport === undefined
-        ? {}
-        : { options: { defaultViewport: { ...options.viewport } } }),
-    });
+export async function appBrowser(options: AppBrowserOptions): Promise<ShotDriver> {
+  if (options.cdpUrl === undefined && options.executablePath === undefined) {
+    throw new ShotChromeMissingError();
   }
-  return localBrowser({
-    launcher,
-    headless: true,
+  return cdpShotDriver({
+    ...(options.cdpUrl === undefined ? {} : { cdpUrl: options.cdpUrl }),
     ...(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.
-    //
-    // `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 } }),
-    },
+    ...(options.viewport === undefined ? {} : { viewport: options.viewport }),
   });
 }