llm-switcher 1.2.6 → 1.2.8

package/state.mjs

@@ -134,6 +134,10 @@ export const paths = {
   envClaudeSh: path.join(STATE_DIR, 'env-claude.sh'),
   envCodexCmd: path.join(STATE_DIR, 'env-codex.cmd'),
   envCodexSh: path.join(STATE_DIR, 'env-codex.sh'),
+  // One line per tool, written with that tool's env file: what the launcher shows the person at
+  // launch. Empty exactly when the tool is not routed, so the launcher needs no second condition.
+  routeClaude: path.join(STATE_DIR, 'route-claude.txt'),
+  routeCodex: path.join(STATE_DIR, 'route-codex.txt'),
   // The gateway port of the last switch on. The shim scrubs a stale loopback base URL
   // against it, so a shell opened before a port change still reaches the right gateway.
   gatewayPort: path.join(STATE_DIR, 'gateway.port'),
@@ -454,6 +458,11 @@ export function validateProfileInput(p) {
   return null;
 }
 
+/** True while a profile still carries the example config's placeholder baseURL or apiKey. */
+export function hasPlaceholder(p) {
+  return !p?.baseURL || /YOUR-|REPLACE-ME/i.test(`${p.baseURL} ${p.apiKey ?? ''}`);
+}
+
 export function needsMigration(cfg) {
   if (!cfg || typeof cfg !== 'object') return false;
   if (Object.hasOwn(cfg, 'activeProfile')) return true;
@@ -1227,8 +1236,9 @@ export function setTargetProfile(cfg, target, profileKey) {
   if (!profileAcceptsTarget(p, tool)) {
     return `Profile "${profileKey}" only accepts "${p.tool || p.inFormat}" input and cannot serve target "${tool}"`;
   }
+  // No legacy `activeProfile` here: needsMigration flags it, so every switch would re-run the
+  // migration on the next load and leave another config.json.bak-* holding the API keys.
   map[tool] = profileKey;
-  cfg.activeProfile = profileKey;
   return null;
 }
 
@@ -1240,7 +1250,6 @@ export function activateProfile(cfg, profileKey) {
   for (const t of TOOLS) {
     if (profileAcceptsTarget(p, t)) map[t] = profileKey;
   }
-  cfg.activeProfile = profileKey;
   return null;
 }
 
@@ -1300,6 +1309,16 @@ export function primaryModel(profile) {
   return '';
 }
 
+// What a person needs at launch: which profile took the traffic, the host it goes to, the model it
+// maps to, and whether the 1M window is on, because that changes what the session costs. Never the
+// API key: a desktop notification reads this line, and so can any shell.
+function routeLine(tool, key, profile) {
+  let host = '';
+  try { host = new URL(profile.baseURL).host; } catch { /* a profile may carry no address yet */ }
+  return [`${tool} -> ${key}`, host, primaryModel(profile), anyTier1M(profile) ? '1M' : '']
+    .filter(Boolean).join(' | ');
+}
+
 // Derive launcher state from activeProfiles (single source of truth).
 export function computeLaunchState(cfg, port) {
   const map = getActiveMap(cfg);
@@ -1310,7 +1329,15 @@ export function computeLaunchState(cfg, port) {
 
   // One interceptor serves both tools (R3) and its port lives at the top level of config.json
   // (R3b). The per-profile port went with the per-profile host and prefix.
-  const bfPort = parsePort(cfg?.blindfold?.port) || DEFAULT_BLINDFOLD_PORT;
+  // Precedence mirrors resolvePort for the gateway: the environment, then the file, then the
+  // default. Without the variable a second instance could not move the interceptor, and a gateway
+  // sent to 3457 by --port or by LLM_SWITCHER_PORT landed on the interceptor's own port.
+  let bfPort = parsePort(process.env.LLM_SWITCHER_BLINDFOLD_PORT)
+    || parsePort(cfg?.blindfold?.port)
+    || DEFAULT_BLINDFOLD_PORT;
+  if (bfPort === port) {
+    bfPort = port === DEFAULT_BLINDFOLD_PORT ? DEFAULT_BLINDFOLD_PORT + 1 : DEFAULT_BLINDFOLD_PORT;
+  }
   const interceptor = `http://127.0.0.1:${bfPort}`;
   const loopbackOnly = '127.0.0.1,localhost';
   const proxyPairs = () => [
@@ -1339,7 +1366,10 @@ export function computeLaunchState(cfg, port) {
     // no --config (F1, F3, F4). The shim of the tool may therefore never capture the traffic
     // of the other tool, and a restart cannot leave a stale override behind.
     envClaude: [],
-    envCodex: []
+    envCodex: [],
+    // The launcher notice, one line per tool. Empty for a tool that is not routed (A1).
+    routeClaude: claude ? routeLine('claude', map.claude, claude) : '',
+    routeCodex: codex ? routeLine('codex', map.codex, codex) : ''
   };
 
   // NODE_EXTRA_CA_CERTS is deliberately absent from env-claude: the shim decides it at launch,
@@ -1446,6 +1476,7 @@ export function emptyToolEnvFiles(tool) {
     const before = codex ? readOrEmpty(paths.envCodexSh) : '';
     writeAtomic(codex ? paths.envCodexCmd : paths.envClaudeCmd, '');
     writeAtomic(codex ? paths.envCodexSh : paths.envClaudeSh, '');
+    writeAtomic(codex ? paths.routeCodex : paths.routeClaude, '');
     return before !== '';
   });
   return { codexRouteChanged, codexDaemon: codexRouteChanged ? restartCodexDaemon([]) : undefined };
@@ -1513,6 +1544,10 @@ function writeLaunchState(cfg, port) {
   try {
     writeToolFiles(st.envClaude, paths.envClaudeSh, paths.envClaudeCmd);
     writeToolFiles(st.envCodex, paths.envCodexSh, paths.envCodexCmd);
+    writeAtomic(paths.routeClaude, st.routeClaude ? `${st.routeClaude}
+` : '');
+    writeAtomic(paths.routeCodex, st.routeCodex ? `${st.routeCodex}
+` : '');
     st.codexRouteChanged = readOrEmpty(paths.envCodexSh) !== codexBefore;
     // Recorded on switch on so a shell opened while the gateway ran can still recognize its own
     // stale loopback URL later, after the port changed (R8).
@@ -1537,7 +1572,8 @@ export function clearLaunchState(port) {
     // leave env.sh present and containing no export and no unset.
     writeAtomic(paths.envCmd, STUB_CMD);
     writeAtomic(paths.envSh, STUB_SH);
-    for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh]) {
+    for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh,
+      paths.routeClaude, paths.routeCodex]) {
       writeAtomic(f, '');
     }
     return codexBefore !== '';

package/switch.cmd

@@ -1,2 +1,2 @@
-@echo off
-node "%~dp0switch.mjs" %*
+@echo off
+node "%~dp0switch.mjs" %*

package/switch.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn, execFileSync } from 'node:child_process';
 import {
-  ROOT_DIR, STATE_DIR, TOOLS, configPath, claudeSettingsPath, paths, certCoversHost, loadConfig, getConfigLoadError, saveConfig,
+  ROOT_DIR, STATE_DIR, TOOLS, configPath, hasPlaceholder, claudeSettingsPath, paths, certCoversHost, loadConfig, getConfigLoadError, saveConfig,
   resolvePort, parsePort, findProfileKey, getActiveMap, setTargetProfile, activateProfile, deactivateAll,
   applyLaunchState, clearLaunchState, computeLaunchState,
   modelSlotsForProfile, modelForSlot, model1MForSlot, readAdminToken, adminTokenPath, openLog,
@@ -14,6 +14,7 @@ import {
   casClearToolPointers, emptyToolEnvFiles, syncInterceptorTools
 } from './state.mjs';
 import { runProbe, runCheck } from './contract.mjs';
+import { installPlugin, uninstallPlugin, pluginStatus, PLUGIN_NAME } from './plugin.mjs';
 import {
   SHIM_DIR, installShims, uninstallShims, shimStatus, pathExportLine, pathOrderHint,
   suggestedRcFiles, auditRunningProcesses
@@ -391,6 +392,10 @@ async function turnOn(profileName, cliTarget) {
 
   // Plan on a copy. Nothing is written until every check below passes.
   let planned = planSwitch(config, key, cliTarget);
+  // The example config routes to YOUR-ROUTER-HOST; activating it silently makes every request fail.
+  if (hasPlaceholder(planned.profiles[key])) {
+    console.warn(`[WARN] Profile "${show(key)}" still has a placeholder baseURL/apiKey. Edit ${configPath} first, or requests will fail.`);
+  }
   console.log(`Activating profile: [${show(planned.profiles[key].name || key)}] (${show(key)})${cliTarget ? ` for ${cliTarget}` : ''} on port ${port}...`);
 
   const gatewayState = await probeGateway(port);
@@ -777,6 +782,47 @@ async function manageService(action) {
   console.log('Usage: switch service [install|uninstall]');
 }
 
+// The launch notice, as a hook inside each tool. Opt-in: the routing does not depend on it, and a
+// person who installs nothing still gets the toast from the shim.
+async function managePlugin(action = 'status') {
+  const act = (action || 'status').toLowerCase();
+
+  if (act === 'install' || act === 'on') {
+    const { CURRENT_VERSION } = await import('./version.mjs');
+    const { installed, failed, paths } = installPlugin({}, CURRENT_VERSION);
+    for (const tool of installed) console.log(`[OK] ${tool}: ${paths[tool]}`);
+    for (const f of failed) console.error(`[Error] ${f.tool}: ${f.reason}`);
+    if (installed.length) {
+      console.log('\nNeither settings.json nor config.toml was opened. Each tool reads a file of its own.');
+      console.log(`Claude Code loads it on the next session as ${PLUGIN_NAME}@skills-dir.`);
+      console.log('Codex asks you once to trust a new hook. Accept it, or the hook stays off.');
+      console.log('\nTo remove it:  switch plugin uninstall');
+    }
+    if (failed.length) process.exit(1);
+    return;
+  }
+
+  if (act === 'uninstall' || act === 'off' || act === 'remove') {
+    const { installed, failed, paths } = uninstallPlugin();
+    for (const tool of installed) console.log(`[OK] ${tool}: removed from ${paths[tool]}`);
+    for (const f of failed) console.error(`[Error] ${f.tool}: ${f.reason}`);
+    if (failed.length) process.exit(1);
+    return;
+  }
+
+  const st = pluginStatus();
+  console.log('=== Launch notice (hook inside each coding tool) ===\n');
+  console.log(`Claude Code: ${st.claude.installed ? `INSTALLED as ${st.claude.id}` : 'not installed'}`);
+  console.log(`             ${st.claude.path}`);
+  console.log(`Codex      : ${st.codex.installed ? 'INSTALLED' : 'not installed'}`);
+  console.log(`             ${st.codex.path}`);
+  if (!st.claude.installed || !st.codex.installed) {
+    console.log(`\nThe notice is optional. Without it the gateway still routes every request,`);
+    console.log(`and the shim still raises its own notice at launch.`);
+    console.log(`To add it:  switch plugin install`);
+  }
+}
+
 async function manageShim(action = 'status') {
   const act = (action || 'status').toLowerCase();
 
@@ -862,7 +908,7 @@ async function runDoctor() {
     if (!key) continue;
     const p = config.profiles[key];
     if (!p) warn(`[WARN] Target ${t} points to missing profile "${show(key)}".`);
-    else if (!p.baseURL || /YOUR-|REPLACE-ME/i.test(`${p.baseURL} ${p.apiKey}`)) warn(`[WARN] Profile "${show(key)}" (${t}) still has placeholder baseURL/apiKey.`);
+    else if (hasPlaceholder(p)) warn(`[WARN] Profile "${show(key)}" (${t}) still has placeholder baseURL/apiKey.`);
     if (p && t === 'codex') {
       const codexWarning = codexPublicModelsWarning(show(key), p);
       if (codexWarning) warn(`[WARN] ${codexWarning}`);
@@ -1109,6 +1155,8 @@ if (cmd === 'off' || cmd === 'stop') {
   await manageService(subArg.toLowerCase() || 'status');
 } else if (cmd === 'shim' || cmd === 'shims') {
   await manageShim(subArg.toLowerCase() || 'status');
+} else if (cmd === 'plugin' || cmd === 'plugins') {
+  await managePlugin(subArg.toLowerCase() || 'status');
 } else if (Object.hasOwn(TARGET_ALIASES, cmd)) {
   await turnOn(subArg, TARGET_ALIASES[cmd]);
 } else if (cmd === 'ui' || cmd === 'web' || cmd === 'gui') {
@@ -1141,6 +1189,9 @@ if (cmd === 'off' || cmd === 'stop') {
   console.log('  switch shim install            # Auto-inject env into resumed sessions (claude --resume)');
   console.log('  switch shim status             # Check shims + detect sessions bypassing the gateway');
   console.log('  switch shim uninstall          # Remove launcher shims');
+  console.log('  switch plugin install          # Optional launch notice inside Claude Code & Codex');
+  console.log('  switch plugin status           # Is that notice installed');
+  console.log('  switch plugin uninstall        # Remove that notice');
   console.log('  switch off [target]            # Restore official endpoints (all, or one target)');
   console.log('  switch models [--refresh]      # Show discovered models catalog for Claude Code & Codex');
   console.log('  switch contract-probe [--model m] # Drive the contract-lab variants through the gateway');

package/tests/blindfold.test.mjs

@@ -137,7 +137,7 @@ test('a compressed response body is decoded for the capture', () => {
   assert.equal(decodeBody(zlib.gzipSync(Buffer.from(sse)), 'GZIP'), sse, 'must be case-insensitive');
   assert.equal(decodeBody(zlib.brotliCompressSync(Buffer.from(sse)), 'br'), sse);
   assert.equal(decodeBody(zlib.deflateSync(Buffer.from(sse)), 'deflate'), sse);
-  assert.equal(decodeBody(zlib.zstdCompressSync(Buffer.from(sse)), 'zstd'), sse);
+  if (typeof zlib.zstdCompressSync === 'function') assert.equal(decodeBody(zlib.zstdCompressSync(Buffer.from(sse)), 'zstd'), sse);
 });
 
 test('an unencoded body is passed through untouched', () => {

package/tests/cdp.mjs

@@ -0,0 +1,297 @@
+// A headless Chromium and one page, driven over the Chrome DevTools Protocol with no dependency.
+// The tests use it to press the real dashboard the way a person does: a click is a mouse event at
+// the pixel where the element is drawn, so a control that is hidden or covered fails the test.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CANDIDATES = [
+  process.env.LLM_SWITCHER_CHROMIUM,
+  '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+].filter(Boolean);
+
+export function findChromium() {
+  return CANDIDATES.find(p => fs.existsSync(p)) || null;
+}
+
+// undefined when this machine can run the browser tests, otherwise the reason to skip them.
+export function skipReason() {
+  if (typeof WebSocket === 'undefined') return 'needs a global WebSocket (Node 22 or newer)';
+  if (!findChromium()) return 'needs a Chromium or Chrome binary (set LLM_SWITCHER_CHROMIUM)';
+  return undefined;
+}
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+const KEYS = {
+  Enter: { code: 'Enter', vk: 13, text: '\r' },
+  Escape: { code: 'Escape', vk: 27 },
+  Tab: { code: 'Tab', vk: 9 },
+  ArrowDown: { code: 'ArrowDown', vk: 40 },
+  ArrowUp: { code: 'ArrowUp', vk: 38 },
+  Backspace: { code: 'Backspace', vk: 8 }
+};
+
+export async function launchBrowser() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lsw-chromium-'));
+  const args = [
+    '--headless=new', '--remote-debugging-port=0', `--user-data-dir=${dir}`,
+    '--no-first-run', '--no-default-browser-check', '--disable-extensions', '--disable-gpu',
+    '--disable-background-networking', '--window-size=1280,900',
+    ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
+    'about:blank'
+  ];
+  const child = spawn(findChromium(), args, { stdio: 'ignore', env: { ...process.env, HOME: dir } });
+  let port = 0;
+  for (let i = 0; i < 150 && !port; i++) {
+    try { port = Number(fs.readFileSync(path.join(dir, 'DevToolsActivePort'), 'utf8').split('\n')[0]) || 0; } catch { /* not written yet */ }
+    if (!port) await sleep(100);
+  }
+  if (!port) { child.kill(); throw new Error('Chromium did not open a debugging port'); }
+
+  const pages = [];
+  return {
+    async newPage() {
+      const list = await (await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: 'PUT' })).json();
+      const page = new Page(list.webSocketDebuggerUrl);
+      await page.ready();
+      pages.push(page);
+      return page;
+    },
+    async close() {
+      for (const p of pages) p.close();
+      child.kill();
+      await new Promise(r => { child.once('exit', r); setTimeout(r, 2000); });
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  };
+}
+
+export class Page {
+  constructor(wsUrl) {
+    this.ws = new WebSocket(wsUrl);
+    this.nextId = 1;
+    this.pending = new Map();
+    this.listeners = new Map();
+    // What a person would notice or what the code would report: kept so a test can assert on it.
+    this.problems = [];      // console errors, uncaught exceptions, failed loads
+    this.badResponses = [];  // { url, status } for every HTTP 4xx and 5xx
+    this.dialogs = [];       // { type, message } for every alert, confirm and prompt
+    this.dialogPolicy = 'accept';
+    this.inflight = new Map();   // requestId -> url, so a stuck request can be named
+    this.requests = [];      // { method, url } for every request, so a double submit is countable
+    this.ws.addEventListener('message', (ev) => this.#onMessage(JSON.parse(ev.data)));
+  }
+
+  async ready() {
+    if (this.ws.readyState !== 1) await new Promise((res, rej) => { this.ws.addEventListener('open', res, { once: true }); this.ws.addEventListener('error', rej, { once: true }); });
+    await Promise.all(['Page', 'Runtime', 'Network', 'Log'].map(d => this.send(`${d}.enable`)));
+    this.on('Runtime.consoleAPICalled', (e) => {
+      if (e.type === 'error' || e.type === 'assert') this.problems.push(`console.${e.type}: ${e.args.map(a => a.value ?? a.description ?? '').join(' ')}`);
+    });
+    this.on('Runtime.exceptionThrown', (e) => this.problems.push(`exception: ${e.exceptionDetails.exception?.description || e.exceptionDetails.text}`));
+    this.on('Log.entryAdded', (e) => { if (e.entry.level === 'error') this.problems.push(`log: ${e.entry.text} ${e.entry.url || ''}`.trim()); });
+    this.on('Network.requestWillBeSent', (e) => {
+      this.inflight.set(e.requestId, e.request.url);
+      this.requests.push({ method: e.request.method, url: e.request.url });
+    });
+    // A new document ends every request of the old one, and no event says so for some of them.
+    this.on('Page.frameNavigated', (e) => { if (!e.frame.parentId) this.inflight.clear(); });
+    this.on('Network.loadingFinished', (e) => this.inflight.delete(e.requestId));
+    this.on('Network.responseReceived', (e) => { if (e.response.status >= 400) this.badResponses.push({ url: e.response.url, status: e.response.status }); });
+    this.on('Network.loadingFailed', (e) => {
+      this.inflight.delete(e.requestId);
+      if (!e.canceled) this.problems.push(`load failed: ${e.errorText} ${e.requestId}`);
+    });
+    this.on('Page.javascriptDialogOpening', (e) => {
+      this.dialogs.push({ type: e.type, message: e.message });
+      this.send('Page.handleJavaScriptDialog', { accept: this.dialogPolicy === 'accept' }).catch(() => {});
+    });
+  }
+
+  #onMessage(msg) {
+    if (msg.id && this.pending.has(msg.id)) {
+      const { resolve, reject } = this.pending.get(msg.id);
+      this.pending.delete(msg.id);
+      if (msg.error) reject(new Error(`${msg.error.message} (${msg.error.code})`)); else resolve(msg.result);
+    } else if (msg.method) {
+      for (const cb of this.listeners.get(msg.method) || []) cb(msg.params);
+    }
+  }
+
+  on(method, cb) {
+    if (!this.listeners.has(method)) this.listeners.set(method, []);
+    this.listeners.get(method).push(cb);
+  }
+
+  send(method, params = {}) {
+    const id = this.nextId++;
+    this.ws.send(JSON.stringify({ id, method, params }));
+    return new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
+  }
+
+  close() { try { this.ws.close(); } catch { /* already closed */ } }
+
+  // Forget what happened so far, so a test asserts only on the action it just made.
+  clearProblems() {
+    this.problems.length = 0;
+    this.badResponses.length = 0;
+    this.dialogs.length = 0;
+    this.requests.length = 0;
+  }
+
+  // Every request of one method whose URL holds `part`. A double submit is two entries here.
+  sent(method, part) { return this.requests.filter(r => r.method === method && r.url.includes(part)); }
+
+  // A real viewport change, the way a narrow window is, so a media query takes effect.
+  async resize(width, height) {
+    await this.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
+    // A layout pass runs on the next frame, so a measurement taken at once reads the old box.
+    await this.evaluate('new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)))');
+  }
+
+  // Wait until no request is in flight for `quiet` ms. A click starts a request, and the page then
+  // starts a second one to read the state back, so one quiet moment is not enough.
+  async idle(quiet = 250, timeout = 8000) {
+    const end = Date.now() + timeout;
+    let quietSince = Date.now();
+    while (Date.now() < end) {
+      if (this.inflight.size > 0) quietSince = Date.now();
+      else if (Date.now() - quietSince >= quiet) return;
+      await sleep(25);
+    }
+    throw new Error(`the page still has ${this.inflight.size} request(s) in flight after ${timeout} ms: ${[...this.inflight.values()].join(', ')}`);
+  }
+
+  #loaded(timeout = 10000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`the page did not finish loading in ${timeout} ms`)), timeout);
+      const done = () => {
+        clearTimeout(timer);
+        const handlers = this.listeners.get('Page.loadEventFired');
+        handlers.splice(handlers.indexOf(done), 1);
+        resolve();
+      };
+      this.on('Page.loadEventFired', done);
+    });
+  }
+
+  async goto(url) {
+    const loaded = this.#loaded();
+    const { errorText, loaderId } = await this.send('Page.navigate', { url });
+    if (errorText) throw new Error(`could not open ${url}: ${errorText}`);
+    // A change of the #hash alone stays in the same document: no load event will follow.
+    if (loaderId) await loaded; else loaded.catch(() => {});
+  }
+
+  async reload() {
+    const loaded = this.#loaded();
+    await this.send('Page.reload');
+    await loaded;
+  }
+
+  async evaluate(expression) {
+    const r = await this.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true });
+    if (r.exceptionDetails) throw new Error(`evaluate failed: ${r.exceptionDetails.exception?.description || r.exceptionDetails.text}\n${expression}`);
+    return r.result.value;
+  }
+
+  // Poll until the page expression is truthy. The message says what the test was waiting for.
+  async waitFor(expression, message, timeout = 5000) {
+    const end = Date.now() + timeout;
+    let last;
+    while (Date.now() < end) {
+      try { last = await this.evaluate(expression); if (last) return last; } catch (e) { last = e.message; }
+      await sleep(50);
+    }
+    throw new Error(`timed out after ${timeout} ms waiting for: ${message}\nlast value: ${JSON.stringify(last)}\nexpression: ${expression}`);
+  }
+
+  q(selector) { return `document.querySelector(${JSON.stringify(selector)})`; }
+  text(selector) { return this.evaluate(`${this.q(selector)}?.textContent.trim() ?? null`); }
+  value(selector) { return this.evaluate(`${this.q(selector)}?.value ?? null`); }
+  count(selector) { return this.evaluate(`document.querySelectorAll(${JSON.stringify(selector)}).length`); }
+  exists(selector) { return this.evaluate(`Boolean(${this.q(selector)})`); }
+  // Visible means drawn with a size and not hidden by display, visibility or an ancestor.
+  visible(selector) {
+    return this.evaluate(`(() => { const e = ${this.q(selector)}; if (!e) return false; const r = e.getBoundingClientRect(); const s = getComputedStyle(e); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none' && e.getClientRects().length > 0; })()`);
+  }
+
+  // The centre of the element after it scrolled into view, and what the browser draws there.
+  async #target(selector) {
+    return this.evaluate(`(() => {
+      const e = ${this.q(selector)};
+      if (!e) return { missing: true };
+      e.scrollIntoView({ block: 'center', inline: 'center' });
+      const r = e.getBoundingClientRect();
+      if (r.width === 0 || r.height === 0) return { hidden: true };
+      const x = r.left + r.width / 2, y = r.top + r.height / 2;
+      const hit = document.elementFromPoint(x, y);
+      const label = e.closest('label');
+      const reachable = hit && (e.contains(hit) || hit.contains(e) || (label && label.contains(hit)));
+      return { x, y, reachable, hit: hit ? hit.tagName + (hit.id ? '#' + hit.id : '') + (hit.className && typeof hit.className === 'string' ? '.' + hit.className.split(' ').join('.') : '') : null };
+    })()`);
+  }
+
+  async click(selector) {
+    const t = await this.#target(selector);
+    if (t.missing) throw new Error(`click: no element matches ${selector}`);
+    if (t.hidden) throw new Error(`click: ${selector} has no size, a person cannot press it`);
+    if (!t.reachable) throw new Error(`click: ${selector} is covered by ${t.hit}, a person cannot press it`);
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: t.x, y: t.y });
+    await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: t.x, y: t.y, button: 'left', clickCount: 1 });
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: t.x, y: t.y, button: 'left', clickCount: 1 });
+  }
+
+  // A press at a pixel, for a target that has no element of its own: the dark area outside a dialog.
+  async clickAt(x, y) {
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y });
+    await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 });
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 });
+  }
+
+  // Press the visible button or link whose label is `text`, the way a person finds it by reading.
+  async clickText(scope, text) {
+    const marked = await this.evaluate(`(() => {
+      document.querySelectorAll('[data-test-target]').forEach(e => e.removeAttribute('data-test-target'));
+      const hit = [...document.querySelectorAll(${JSON.stringify(scope)})].filter(e => e.textContent.trim() === ${JSON.stringify(text)} && e.getClientRects().length > 0);
+      if (hit.length !== 1) return hit.length;
+      hit[0].setAttribute('data-test-target', '1');
+      return 1;
+    })()`);
+    if (marked !== 1) throw new Error(`clickText: ${marked} visible match(es) for "${text}" in ${scope}, expected exactly 1`);
+    await this.click('[data-test-target="1"]');
+    await this.evaluate(`document.querySelector('[data-test-target]')?.removeAttribute('data-test-target')`);
+  }
+
+  // Focus the field with a click, drop the old text, then type like a person: one input event.
+  async type(selector, text) {
+    await this.click(selector);
+    await this.evaluate(`${this.q(selector)}.select()`);
+    if (text === '') await this.key('Backspace'); else await this.send('Input.insertText', { text });
+  }
+
+  async key(name) {
+    const k = KEYS[name];
+    if (!k) throw new Error(`key: unknown key ${name}`);
+    const base = { key: name, code: k.code, windowsVirtualKeyCode: k.vk, nativeVirtualKeyCode: k.vk };
+    await this.send('Input.dispatchKeyEvent', { type: k.text ? 'keyDown' : 'rawKeyDown', ...base, ...(k.text ? { text: k.text } : {}) });
+    await this.send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
+  }
+
+  // A native <select> opens an operating system popup that no protocol call can press, so this sets
+  // the value the way the popup would and fires the same events.
+  async select(selector, value) {
+    await this.click(selector);
+    await this.evaluate(`(() => { const s = ${this.q(selector)}; s.value = ${JSON.stringify(value)}; if (s.value !== ${JSON.stringify(value)}) throw new Error('select: no option ' + ${JSON.stringify(value)}); s.dispatchEvent(new Event('input', { bubbles: true })); s.dispatchEvent(new Event('change', { bubbles: true })); })()`);
+  }
+
+  async screenshot(file) {
+    const { data } = await this.send('Page.captureScreenshot', { format: 'png' });
+    fs.writeFileSync(file, Buffer.from(data, 'base64'));
+    return file;
+  }
+}