@ultimat3/cli 11.2.0 → 11.3.0

package/CLAUDE.md

@@ -166,7 +166,7 @@ change, and CI does not install one.
 
 | | Reaches for | Never |
 |---|---|---|
-| `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` | the static build — `--target static` prerenders `site/` only, so an `app/` route would photograph the landing page |
+| `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 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 |
@@ -187,6 +187,7 @@ ones a running app will not produce on request. `--island` takes them, one addre
 | `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 |
+| `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 |
 

package/package.json

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

package/src/browser-launcher.ts

@@ -2,11 +2,17 @@
 // 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.
 
 import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
-import { localBrowser } from '@ultimat3/scraping';
+import { localBrowser, remoteBrowser } from '@ultimat3/scraping';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -18,6 +24,17 @@ export const BROWSER_PACKAGE = 'puppeteer-core';
 /** 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;
 
+/**
+ * Where a CDP endpoint is named when `--cdp-url` does not name one. `SCRAPE_CDP_URL` and not a
+ * name of this command's own: `@ultimat3/scraping`'s `remoteRequired` refusal already tells its
+ * reader `remoteBrowser({ cdpUrl: env.SCRAPE_CDP_URL })`, and a second spelling would make the
+ * package's own instruction wrong for the CLI that follows it.
+ */
+export const BROWSER_CDP_URL_VAR = 'SCRAPE_CDP_URL';
+
+/** The schemes a CDP endpoint can arrive as: a provider's `wss://`, a sidecar's `http://`. */
+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
@@ -27,6 +44,8 @@ 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
@@ -40,23 +59,34 @@ export class ShotBrowserMissingError 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 there a `launch` to call?
+ * 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): CdpLauncherLike | undefined => {
+const launcherIn = (module: unknown, method: 'launch' | 'connect'): CdpLauncherLike | undefined => {
   if (typeof module !== 'object' || module === null) return undefined;
-  const candidate = module as { launch?: unknown; default?: unknown };
-  if (typeof candidate.launch === 'function') return candidate as CdpLauncherLike;
+  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.
-  if (candidate.default === undefined || candidate.default === candidate) return undefined;
-  return launcherIn(candidate.default);
+  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`. */
   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.
+   */
+  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
@@ -85,6 +115,33 @@ export const executablePathFrom = (
 /** True when a named executable is really there — a bad `--browser` is refused before a boot. */
 export const browserBinaryExists = (path: string): boolean => existsSync(path);
 
+/** The endpoint a run will attach to, or `undefined` for "launch one here". */
+export const cdpUrlFrom = (
+  flag: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined => {
+  if (flag !== undefined && flag.length > 0) return flag;
+  const value = env[BROWSER_CDP_URL_VAR];
+  return value !== undefined && value.length > 0 ? value : undefined;
+};
+
+/**
+ * The scheme, checked here rather than at `connect()`. A `--cdp-url` naming an https page or a
+ * bare host is a typo, and a typo must not cost an embedded Postgres and a provider session to
+ * report — the same rule `--browser` follows against the filesystem one line above.
+ */
+export const cdpUrlProblem = (url: string): string | undefined => {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return 'is not a URL';
+  }
+  return CDP_SCHEMES.includes(parsed.protocol as (typeof CDP_SCHEMES)[number])
+    ? undefined
+    : `has scheme "${parsed.protocol}", and a CDP endpoint is ${CDP_SCHEMES.join(', ')}`;
+};
+
 /**
  * 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
@@ -93,17 +150,30 @@ export const browserBinaryExists = (path: string): boolean => existsSync(path);
 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));
+  const launcher = launcherIn(await load(entry), method);
   if (launcher === undefined) {
     throw new ShotBrowserMissingError({
       root: options.root,
-      detail: `resolved to ${entry}, which exports no launch()`,
+      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 } } }),
     });
   }
   return localBrowser({

package/src/cmd-shot-island.ts

@@ -27,6 +27,7 @@ import { SHOT_DIR } from './shot-server';
 export function islandBrowser(input: {
   readonly root: string;
   readonly executablePath?: string | undefined;
+  readonly cdpUrl?: string | undefined;
 }): IslandBrowser {
   const byViewport = new Map<string, Promise<ScrapeDriver>>();
   return (viewport: IslandViewport): Promise<ScrapeDriver> => {
@@ -36,6 +37,7 @@ export function islandBrowser(input: {
     const started = appBrowser({
       root: input.root,
       ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+      ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
       viewport: { width: viewport.width, height: viewport.height },
     });
     byViewport.set(key, started);
@@ -86,6 +88,8 @@ export interface IslandShotInput {
   readonly timeoutMs: number;
   readonly extraHosts?: string | undefined;
   readonly executablePath?: string | undefined;
+  /** A provider's session, or a sidecar. One attach per viewport, memoised like a launch. */
+  readonly cdpUrl?: string | undefined;
   readonly boot: () => Promise<ShotServer>;
   /** Injected by a test, so the whole path is proved on a machine with no Chrome. */
   readonly driver?: IslandBrowser | undefined;
@@ -124,6 +128,7 @@ export async function islandShot(input: IslandShotInput): Promise<IslandArtifact
       islandBrowser({
         root: input.root,
         ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+        ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
       }),
     boot: input.boot,
     settleMs: input.settleMs,

package/src/cmd-shot.ts

@@ -11,7 +11,7 @@ import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
-import { appBrowser, browserBinaryExists, executablePathFrom } from './browser-launcher';
+import { appBrowser } from './browser-launcher';
 import { islandShot, islandShotResult, refuseRouteWithIsland } from './cmd-shot-island';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
@@ -19,6 +19,7 @@ import { intFlagOr, PORT_RANGE } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
+import { shotBrowserChoice } from './shot-browser';
 import type { BootDevServer, ShotServer } from './shot-server';
 import { allowHostsFrom, devServerFor, SHOT_DIR } from './shot-server';
 import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
@@ -285,6 +286,11 @@ export const shotCommand: CliCommand = {
       { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
       { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
       { name: 'browser', type: 'string', summary: 'browser executable puppeteer-core launches' },
+      {
+        name: 'cdp-url',
+        type: 'string',
+        summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
+      },
       { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
       // A FLAG on `x shot` and never a second command: photographing a route and photographing a
       // component are one job with two subjects, and a parallel command would be the second path
@@ -314,15 +320,14 @@ export const shotCommand: CliCommand = {
     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);
-    const executablePath = executablePathFrom(flagString(ctx.args, 'browser'), ctx.env);
-    if (executablePath !== undefined && !browserBinaryExists(executablePath)) {
-      throw new BadFlagError({
-        flag: 'browser',
-        command: 'shot',
-        reason: `no executable at "${executablePath}"`,
-        fix: 'x shot / --browser /usr/bin/chromium',
-      });
-    }
+    // Which browser this run gets — start one here, or attach to one somebody else is running.
+    // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
+    // provider session exists to pay for a typo.
+    const { cdpUrl, executablePath } = shotBrowserChoice({
+      cdpFlag: flagString(ctx.args, 'cdp-url'),
+      browserFlag: flagString(ctx.args, 'browser'),
+      env: ctx.env,
+    });
     const out = flagString(ctx.args, 'out');
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
     if (island !== undefined && island !== '') {
@@ -337,6 +342,7 @@ export const shotCommand: CliCommand = {
           settleMs,
           timeoutMs,
           ...(executablePath === undefined ? {} : { executablePath }),
+          ...(cdpUrl === undefined ? {} : { cdpUrl }),
           ...(flagString(ctx.args, 'allow-hosts') === undefined
             ? {}
             : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
@@ -349,6 +355,7 @@ export const shotCommand: CliCommand = {
     const driver = await appBrowser({
       root,
       ...(executablePath === undefined ? {} : { executablePath }),
+      ...(cdpUrl === undefined ? {} : { cdpUrl }),
     });
     return shotResult(
       await runShot({

package/src/compile-externals.ts

@@ -8,10 +8,13 @@
  * `package.json` inside a `catch` — and both sit in `loadCtsDefault`, which only runs while Babel
  * loads a `.cts` CONFIG FILE. `solid-loader.ts` passes `babelrc: false, configFile: false`, so no
  * config file is ever loaded and neither line is reachable at run time. The bundler walks them
- * anyway, and that is the whole failure: Bun 1.3 (what CI pins and what `docker/Dockerfile` builds
- * on) refuses the build with `Could not resolve: "@babel/preset-typescript/package.json"`, while
- * Bun 1.4 bundles the unresolvable `require` as a runtime throw — so one tree compiled on a laptop
- * and did not in CI.
+ * anyway, and that is the whole failure: Bun 1.3 refuses the build with
+ * `Could not resolve: "@babel/preset-typescript/package.json"`, while Bun 1.4 bundles the
+ * unresolvable `require` as a runtime throw — so one tree compiled on a laptop and did not in CI.
+ * That skew is closed `As of 2026-08-20`: CI pins `1.4.x` (`.github/actions/setup/action.yml`),
+ * `docker/Dockerfile` builds on `oven/bun:1.4-slim` and `scripts/setup.ts` holds contributors to
+ * 1.4.0, so every builder now takes the second branch. The external stays regardless — it is the
+ * `--compile` graph that must not reach an unresolvable `require`, on either Bun.
  *
  * Marking the dead specifier external rather than the two live ones: `serve.ts` calls
  * `buildIslands` on every boot, unconditionally, so a binary with `@babel/core` external is a

package/src/island-bundle.ts

@@ -10,7 +10,6 @@ import { renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
-import { solidProductionPlugin } from './island-solid-production';
 import { islandStylesPlugin } from './island-styles';
 import { solidJsxPlugin } from './solid-loader';
 
@@ -84,12 +83,24 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // classic `React.createElement` — emitted into a browser chunk that imports no React, with
       // `success: true` and no log. Every island shipped that way through five majors.
       //
-      // The other two close the same shape of failure — a wrong answer `Bun.build` reports as
-      // `success: true`: without the second, `target: 'browser'` resolves the `development`
-      // export condition and the chunk carries Solid's dev build; without the third, Bun's file
-      // loader resolves a `.module.scss` to its asset PATH, so `styles['x']` is `undefined` and
-      // every element renders unclassed.
-      plugins: [solidJsxPlugin, solidProductionPlugin, islandStylesPlugin],
+      // The second closes the same shape of failure — a wrong answer `Bun.build` reports as
+      // `success: true`: without it, Bun's file loader resolves a `.module.scss` to its asset
+      // PATH, so `styles['x']` is `undefined` and every element renders unclassed.
+      plugins: [solidJsxPlugin, islandStylesPlugin],
+      // The third one, and it is a `define` rather than the plugin this used to be: Bun selects
+      // the `development`/`production` export condition from the BUILD PROCESS's own `NODE_ENV`,
+      // and a defined `process.env.NODE_ENV` overrides it. Measured on 1.4.0, `solid-js` plus
+      // `solid-js/web` plus `solid-js/store`: unset → dev build, `test` → dev build, `production`
+      // → production build, this line → production build in all three, byte for byte.
+      //
+      // So without it a chunk built anywhere a container did not run — `x dev`, `x build` on a
+      // laptop, `bun test` — ships Solid's development build, and the island's own
+      // `process.env.NODE_ENV` reads `"development"` in the file a browser downloads.
+      //
+      // Pinned rather than inherited, because an island chunk is only ever built to be shipped:
+      // `x dev` serves the same chunk the container does, and bytes that depend on the ambient
+      // NODE_ENV are a content hash and a byte budget measured on a build nobody ships.
+      define: { 'process.env.NODE_ENV': '"production"' },
     });
   } catch (error) {
     throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });

package/src/shot-browser.ts

@@ -0,0 +1,84 @@
+// Which browser a `x shot` run gets: start one in this container, or ATTACH to one somebody else is
+// running. Three rules over plain inputs and no `ParsedArgs`, so each is testable without a boot —
+// the `cmd-jobs.ts` / `jobs-report.ts` split, repeated for the one decision that is easy to get
+// silently wrong.
+
+import {
+  browserBinaryExists,
+  cdpUrlFrom,
+  cdpUrlProblem,
+  executablePathFrom,
+} from './browser-launcher';
+import { BadFlagError } from './errors';
+
+/** A runnable example, not a placeholder: every refusal below hands one of these back. */
+const CDP_FIX = 'x shot / --cdp-url wss://cdp.example.com/session/abc';
+
+/**
+ * Exactly one of these is set. `undefined` on both is the ordinary local run where the library
+ * finds its own Chrome — which is why neither is required rather than a union of two shapes.
+ */
+export interface ShotBrowserChoice {
+  /** Attach here. When set, nothing about a local executable was read. */
+  readonly cdpUrl?: string | undefined;
+  /** Launch this. Already proved to exist on disk. */
+  readonly executablePath?: string | undefined;
+}
+
+export interface ShotBrowserInput {
+  /** `--cdp-url` as typed. The env fallback is applied here, not by the caller. */
+  readonly cdpFlag?: string | undefined;
+  /** `--browser` as typed, before `PUPPETEER_EXECUTABLE_PATH` / `CHROME_PATH`. */
+  readonly browserFlag?: string | undefined;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * Decided before anything boots, because a typo must not cost an embedded Postgres — and, on the
+ * attach path, a provider session — to report.
+ *
+ * The three rules, each chosen against a silent failure rather than for symmetry:
+ *
+ * 1. **Both FLAGS is refused, never ranked.** One names a Chrome to START and the other says the
+ *    browser is somebody else's, so honouring either ignores what was typed.
+ * 2. **An exported `SCRAPE_CDP_URL` loses to `--browser`.** A shell-wide default is not a typed
+ *    intent. The alternative is a flag that parses, reports nothing and quietly attaches somewhere
+ *    else — the `--critical` defect class `flag-reads.ts` exists for and cannot see here, because
+ *    the flag IS read.
+ * 3. **On an attach, no executable is read at all.** Checking the filesystem for a binary this run
+ *    will never execute is how a correct remote capture gets refused on a box with no Chrome.
+ */
+export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
+  if (input.cdpFlag !== undefined && input.browserFlag !== undefined) {
+    throw new BadFlagError({
+      flag: 'cdp-url',
+      command: 'shot',
+      reason:
+        '--browser names a Chrome to launch here and --cdp-url attaches to one already running',
+      fix: CDP_FIX,
+    });
+  }
+  const cdpUrl = input.browserFlag === undefined ? cdpUrlFrom(input.cdpFlag, input.env) : undefined;
+  if (cdpUrl !== undefined) {
+    const problem = cdpUrlProblem(cdpUrl);
+    if (problem !== undefined) {
+      throw new BadFlagError({
+        flag: 'cdp-url',
+        command: 'shot',
+        reason: `"${cdpUrl}" ${problem}`,
+        fix: CDP_FIX,
+      });
+    }
+    return { cdpUrl };
+  }
+  const executablePath = executablePathFrom(input.browserFlag, input.env);
+  if (executablePath !== undefined && !browserBinaryExists(executablePath)) {
+    throw new BadFlagError({
+      flag: 'browser',
+      command: 'shot',
+      reason: `no executable at "${executablePath}"`,
+      fix: 'x shot / --browser /usr/bin/chromium',
+    });
+  }
+  return executablePath === undefined ? {} : { executablePath };
+}

package/src/island-solid-production.ts

@@ -1,129 +0,0 @@
-// Every `solid-js` import in an island chunk resolves to Solid's PRODUCTION browser build.
-// `Bun.build({ target: 'browser' })` always adds the `development` export condition and offers no
-// option that removes it — `conditions`, `production`, `env` and `define` were each measured under
-// Bun 1.4 and none of them does — so without this seam an island ships the dev bundle silently.
-
-// `node:path` by necessity: Bun ships no path API, and this file resolves a package entry back
-// to the directory its `exports` map is relative to.
-import { dirname, join } from 'node:path';
-import type { BunPlugin } from 'bun';
-import { IslandBuildFailedError } from './errors';
-
-/**
- * The conditions an island's `solid-js` subpath is resolved under. `development` is the one NOT in
- * the set, which is the whole point of the file; `production` is in it because an island chunk is
- * only ever built to be shipped — `x dev` serves the same chunk the container does, so a second
- * answer here would be a bundle the byte budget never measured.
- */
-const ISLAND_CONDITIONS: ReadonlySet<string> = new Set([
-  'production',
-  'browser',
-  'module',
-  'import',
-  'default',
-]);
-
-/** `solid-js` and its subpaths, and nothing else: Solid is the runtime an island is compiled for. */
-const SOLID_SPECIFIER = /^solid-js(?:\/|$)/;
-
-/**
- * Node's conditional-exports walk, restricted to what this file needs: the first key of the object
- * that the build's condition set contains, depth-first, with an array as an ordered fallback list.
- * Written out rather than delegated to `Bun.resolveSync` because the ONE thing it has to do
- * differently from Bun's resolver is refuse `development` — and `types` with it, which would
- * otherwise win on Solid's map and hand the bundler a `.d.ts`.
- */
-export function selectCondition(node: unknown, conditions: ReadonlySet<string>): string | null {
-  if (typeof node === 'string') return node;
-  if (Array.isArray(node)) {
-    for (const alternative of node as readonly unknown[]) {
-      const picked = selectCondition(alternative, conditions);
-      if (picked !== null) return picked;
-    }
-    return null;
-  }
-  if (typeof node !== 'object' || node === null) return null;
-  for (const [condition, value] of Object.entries(node)) {
-    if (!conditions.has(condition)) continue;
-    const picked = selectCondition(value, conditions);
-    if (picked !== null) return picked;
-  }
-  return null;
-}
-
-/** One parse per manifest: an island imports Solid from several files, and every file asks again. */
-const exportsCache = new Map<string, unknown>();
-
-async function exportsOf(manifest: string): Promise<unknown> {
-  const hit = exportsCache.get(manifest);
-  if (hit !== undefined || exportsCache.has(manifest)) return hit;
-  const parsed: unknown = JSON.parse(await Bun.file(manifest).text());
-  const field =
-    typeof parsed === 'object' && parsed !== null && 'exports' in parsed
-      ? (parsed as { readonly exports?: unknown }).exports
-      : undefined;
-  exportsCache.set(manifest, field);
-  return field;
-}
-
-/** Test seam: the cache is process-global because `x dev` rebuilds in one process. */
-export function clearSolidExportsCache(): void {
-  exportsCache.clear();
-}
-
-/**
- * The absolute file `specifier` must resolve to, or `null` for "Bun's own answer is already the
- * right one" — which is every subpath Solid declares as a plain string or a pattern, since a
- * declaration with no conditions on it cannot select the development build.
- */
-export async function solidProductionEntry(
-  specifier: string,
-  resolveDir: string,
-  importer: string,
-): Promise<string | null> {
-  let manifest: string;
-  try {
-    // `solid-js/package.json` is an `exports` entry of Solid's own map, so this reaches the exact
-    // copy the island would have imported — not a hoisted sibling at a different version.
-    manifest = Bun.resolveSync('solid-js/package.json', resolveDir);
-  } catch {
-    // Solid is not installed here. Bun's resolver says so, in its own words, naming the importer.
-    return null;
-  }
-  const field = await exportsOf(manifest);
-  const subpath = specifier === 'solid-js' ? '.' : `.${specifier.slice('solid-js'.length)}`;
-  if (typeof field !== 'object' || field === null || !(subpath in field)) return null;
-
-  const entry = selectCondition((field as Record<string, unknown>)[subpath], ISLAND_CONDITIONS);
-  const file = entry === null ? null : join(dirname(manifest), entry);
-  if (file === null || !(await Bun.file(file).exists())) {
-    throw new IslandBuildFailedError({
-      file: importer.length > 0 ? importer : specifier,
-      logs:
-        `${specifier} has no production browser entry: ${manifest} answers ` +
-        `${entry === null ? 'nothing' : JSON.stringify(entry)} under ` +
-        `[${[...ISLAND_CONDITIONS].join(', ')}], and an island may not ship Solid's ` +
-        'development build',
-    });
-  }
-  return file;
-}
-
-/**
- * The plugin `island-bundle.ts` hands `Bun.build`, beside `solidJsxPlugin`. Stateless apart from
- * the manifest cache, so one frozen descriptor serves every concurrent island build.
- *
- * The absolute path it answers with no longer matches `SOLID_SPECIFIER`, so Solid's own internal
- * `import … from 'solid-js'` is the only re-entry — and that one is wanted: it is how `web.js`
- * reaches `solid.js` rather than `dev.js`.
- */
-export const solidProductionPlugin: BunPlugin = {
-  name: 'ultimate-island-solid-production',
-  setup(build): void {
-    build.onResolve({ filter: SOLID_SPECIFIER }, async ({ path, importer, resolveDir }) => {
-      const from = resolveDir.length > 0 ? resolveDir : dirname(importer);
-      const entry = await solidProductionEntry(path, from, importer);
-      return entry === null ? undefined : { path: entry };
-    });
-  },
-};