amalgm 0.1.91 → 0.1.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.91",
+  "version": "0.1.92",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/browser/attach.js

@@ -0,0 +1,238 @@
+'use strict';
+
+/**
+ * Attached mode — drive the browser surface the user is watching.
+ *
+ * The desktop app advertises its chromium over CDP; the UI mounts the in-tab
+ * split-view <webview> with a marker URL. This module owns the handshake:
+ *
+ *  1. Ask the UI to open the surface (a browser_surfaces state event — the
+ *     renderer subscribes and mounts the webview; an event, not an RPC).
+ *  2. Select the session's webview target by marker (fallbacks: previously
+ *     selected target, then the only webview). Fail closed if none appears —
+ *     never silently drive the outer app window, never silently go headless.
+ *  3. One focus pass — chromium drops CDP Input.* events to a <webview>
+ *     guest until the guest widget has focus (reads work unfocused; clicks
+ *     would "succeed" without landing).
+ *
+ * run() is the command transport every verb uses: it ensures the handshake,
+ * then shells out to agent-browser, re-attaching once if the connection was
+ * lost (app restart, webview remount).
+ */
+
+const cli = require('./cli');
+const backend = require('./backend');
+const cdp = require('./cdp');
+const { attachedSessions, knownSessions } = require('./sessions');
+
+const SURFACE_EVENT_RESOURCE = 'browser_surfaces';
+const WEBVIEW_MARKER_PREFIX = 'amalgm-bsid-';
+const WEBVIEW_WAIT_MS = 15_000;
+const WEBVIEW_POLL_MS = 500;
+
+function marker(session) {
+  return `${WEBVIEW_MARKER_PREFIX}${session}`;
+}
+
+/** Options every cli call needs for the current backend. */
+function cliOptions(session, extra = {}) {
+  const options = { session, ...extra };
+  if (backend.mode() === 'attached') options.cdp = backend.cdpEndpoint();
+  return options;
+}
+
+function requestSurfaceOpen(session, context) {
+  try {
+    const { appendStateEvent } = require('../state/events');
+    appendStateEvent({
+      resource: SURFACE_EVENT_RESOURCE,
+      op: 'insert',
+      id: session,
+      value: {
+        browserSessionId: session,
+        callerSessionId: context?.callerSessionId || null,
+        marker: marker(session),
+        requestedAt: new Date().toISOString(),
+      },
+      source: 'browser-engine',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listWebviewTabs(session) {
+  const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
+  const list = tabs?.data?.tabs || tabs?.tabs || [];
+  return list.filter((tab) => tab.type === 'webview');
+}
+
+/**
+ * The session's webview rectangle in the app window, or null when the
+ * splitview is hidden (0x0) or gone. Raw CDP, deadline-bounded.
+ */
+async function surfaceRect(session, hintUrl) {
+  const endpoint = backend.cdpEndpoint();
+  if (!endpoint) return null;
+  try {
+    return await cdp.findSurfaceRect(endpoint, marker(session), hintUrl || '');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Attached mode's product promise is a surface the user can see. A webview
+ * target can exist while the splitview panel is hidden — input silently
+ * drops and captures have nothing to show. When that happens, ask the UI to
+ * reopen it (repeat browser_surfaces events open or focus the existing
+ * surface) and poll until it has real on-screen geometry.
+ */
+async function ensureSurfaceVisible(session, hintUrl, context, waitMs = WEBVIEW_WAIT_MS) {
+  let found = await surfaceRect(session, hintUrl);
+  if (found) return found;
+  requestSurfaceOpen(session, context);
+  const deadlineAt = Date.now() + waitMs;
+  while (Date.now() < deadlineAt) {
+    await new Promise((resolve) => setTimeout(resolve, WEBVIEW_POLL_MS));
+    found = await surfaceRect(session, hintUrl);
+    if (found) return found;
+  }
+  return null;
+}
+
+function matchWebview(webviews, session) {
+  const markerText = marker(session);
+  const byMarker = webviews.find((tab) => String(tab.url || '').includes(markerText)
+    || String(tab.title || '').includes(markerText));
+  if (byMarker) return byMarker;
+  const previous = knownSessions.get(session)?.webviewTabId;
+  if (previous) {
+    const byPrevious = webviews.find((tab) => tab.tabId === previous);
+    if (byPrevious) return byPrevious;
+  }
+  if (webviews.length === 1) return webviews[0];
+  return null;
+}
+
+/**
+ * Connect the session to the advertised chromium on first use and select the
+ * in-tab webview target so commands drive the surface the user is looking at.
+ */
+async function ensureReady(session, context) {
+  if (backend.mode() !== 'attached' || attachedSessions.has(session)) return;
+
+  let webviews = await listWebviewTabs(session);
+  let selected = matchWebview(webviews, session);
+
+  if (!selected) {
+    requestSurfaceOpen(session, context);
+    const deadline = Date.now() + WEBVIEW_WAIT_MS;
+    while (!selected && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, WEBVIEW_POLL_MS));
+      webviews = await listWebviewTabs(session);
+      selected = matchWebview(webviews, session);
+    }
+  }
+
+  if (!selected && webviews.length === 0 && process.env.AMALGM_BROWSER_CDP_URL) {
+    // Explicit external CDP endpoints (plain chromium) have page targets,
+    // not webviews — drive whatever the daemon selected by default.
+    attachedSessions.add(session);
+    return;
+  }
+
+  if (!selected) {
+    throw new Error(
+      'Browser surface did not open in the desktop app. '
+      + 'Retry, or force a headless browser with AMALGM_BROWSER_BACKEND=cli.',
+    );
+  }
+
+  await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+
+  // The webview target existing is not enough — the splitview panel must be
+  // on screen, or input drops and captures have nothing to render.
+  const visible = await ensureSurfaceVisible(session, selected.url, context);
+  if (!visible) {
+    throw new Error(
+      'The browser surface is hidden in the desktop app and did not reopen. '
+      + 'Bring the Amalgm window forward, or force a headless browser with AMALGM_BROWSER_BACKEND=cli.',
+    );
+  }
+
+  await focusWebviewHost(session, selected);
+  knownSessions.set(session, { ...knownSessions.get(session), webviewTabId: selected.tabId });
+  attachedSessions.add(session);
+}
+
+/**
+ * Chromium drops CDP Input events to an Electron <webview> guest until the
+ * guest widget has focus (verified live: clicks report success but never
+ * land). One focus pass after target selection fixes input for the session:
+ * focus the <webview> element from the embedder page, then self-focus the
+ * guest. Best-effort — failures leave snapshot/eval working regardless.
+ */
+async function focusWebviewHost(session, selected) {
+  const markerText = marker(session);
+  try {
+    const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
+    const list = tabs?.data?.tabs || tabs?.tabs || [];
+    const outer = list.find((tab) => tab.type === 'page');
+    if (outer) {
+      const script = `(() => {
+        const views = [...document.querySelectorAll('webview')];
+        const target = views.find((w) => (w.getAttribute('src') || '').includes(${JSON.stringify(markerText)}))
+          || views.find((w) => (w.src || '') === ${JSON.stringify(String(selected.url || ''))})
+          || views[views.length - 1];
+        if (target) target.focus();
+        return views.length;
+      })()`;
+      await cli.runCli(['tab', outer.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+      await cli.runCli(['eval', script], cliOptions(session, { timeoutMs: 15_000 }));
+      await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+    }
+    await cli.runCli(['eval', 'window.focus()'], cliOptions(session, { timeoutMs: 15_000 }));
+  } catch {
+    // Snapshot/eval still work without focus; input may need a retry.
+  }
+}
+
+function looksLikeLostConnection(err) {
+  return /clos|connect|target|socket|detach/i.test(String(err?.message || err || ''));
+}
+
+async function run(session, commandArgs, options = {}) {
+  const { context, ...cliExtra } = options;
+  await ensureReady(session, context);
+  try {
+    return await cli.runCli(commandArgs, cliOptions(session, cliExtra));
+  } catch (err) {
+    if (backend.mode() === 'attached' && attachedSessions.has(session) && looksLikeLostConnection(err)) {
+      // The app restarted or the webview remounted; re-attach once.
+      attachedSessions.delete(session);
+      await ensureReady(session, context);
+      return cli.runCli(commandArgs, cliOptions(session, cliExtra));
+    }
+    throw err;
+  }
+}
+
+async function readText(session, commandArgs, timeoutMs) {
+  await ensureReady(session);
+  return cli.readText(commandArgs, session, timeoutMs, backend.mode() === 'attached' ? backend.cdpEndpoint() : null);
+}
+
+module.exports = {
+  SURFACE_EVENT_RESOURCE,
+  WEBVIEW_MARKER_PREFIX,
+  cliOptions,
+  ensureReady,
+  ensureSurfaceVisible,
+  marker,
+  matchWebview,
+  readText,
+  requestSurfaceOpen,
+  run,
+};

package/runtime/scripts/amalgm-mcp/browser/auth-tools.js

@@ -1,9 +1,15 @@
 'use strict';
 
 /**
- * Browser auth tools — durable profiles, encrypted auth bundles, and
- * temporary login links. Split from the core browser surface: these manage
- * login state, they don't drive pages.
+ * Browser auth actions — durable profiles, encrypted auth bundles, and
+ * temporary login links. Split from the core surface: these manage login
+ * state, they don't drive pages.
+ *
+ * The human-handoff flow: auth_link_create mints a short-lived link → the
+ * user signs in on a visible surface → auth_save captures the session as an
+ * encrypted bundle → auth_load replays it into a profile later. Raw cookies
+ * and tokens never appear in tool results, and bundles never leave this
+ * computer.
  */
 
 const { textResult, errorResult } = require('../lib/tool-result');
@@ -36,44 +42,24 @@ function authDomainsFrom(inputDomains, fallbackUrl) {
 
 module.exports = [
   {
-    name: 'browser_profiles_list',
-    description: 'List durable Amalgm browser profiles on this computer.',
+    name: 'auth_list',
+    description: 'List saved browser auth state on this computer: durable profiles, encrypted auth bundles, and pending login links. Raw cookies and tokens are never returned.',
     inputSchema: { type: 'object', properties: {} },
     async handler() {
       try {
-        return jsonText({ profiles: listBrowserProfiles() });
-      } catch (err) {
-        return errorResult(`List browser profiles failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_auth_bundles_list',
-    description: 'List encrypted browser auth bundles available on this computer. Raw cookies/storage are never returned.',
-    inputSchema: { type: 'object', properties: {} },
-    async handler() {
-      try {
-        return jsonText({ bundles: listBrowserAuthBundles() });
-      } catch (err) {
-        return errorResult(`List browser auth bundles failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_login_sessions_list',
-    description: 'List temporary browser login links on this computer. Raw tokens and cookies are never returned.',
-    inputSchema: { type: 'object', properties: {} },
-    async handler() {
-      try {
-        return jsonText({ sessions: listBrowserLoginSessions() });
+        return jsonText({
+          profiles: listBrowserProfiles(),
+          bundles: listBrowserAuthBundles(),
+          loginSessions: listBrowserLoginSessions(),
+        });
       } catch (err) {
-        return errorResult(`List browser login sessions failed: ${err.message}`);
+        return errorResult(`auth_list failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_auth_link_create',
-    description: 'Create a short-lived browser login link for the user. Use this when an agent needs the user to log into a site before QA or browser work.',
+    name: 'auth_link_create',
+    description: 'Create a short-lived login link for the user when a site needs them to sign in. The user logs in on a visible browser surface; follow with auth_save to keep the session for later runs.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -108,13 +94,13 @@ module.exports = [
           message: `Open this temporary login link: ${result.authLink}`,
         });
       } catch (err) {
-        return errorResult(`Create browser auth link failed: ${err.message}`);
+        return errorResult(`auth_link_create failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_auth_save',
-    description: 'Save the current browser profile cookies/storage into an encrypted auth bundle for later agent use.',
+    name: 'auth_save',
+    description: 'Save the current browser session cookies/storage into an encrypted auth bundle for later agent use.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -140,13 +126,13 @@ module.exports = [
         }, { source: 'browser-auth-save' });
         return jsonText({ bundle });
       } catch (err) {
-        return errorResult(`Save browser auth bundle failed: ${err.message}`);
+        return errorResult(`auth_save failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_auth_load',
-    description: 'Load an encrypted browser auth bundle into a durable browser profile so an agent can start past login.',
+    name: 'auth_load',
+    description: 'Load an encrypted auth bundle into a durable browser profile so an agent can start past login.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -172,7 +158,7 @@ module.exports = [
         }, { source: 'browser-auth-load' });
         return jsonText({ bundle: updated, loaded });
       } catch (err) {
-        return errorResult(`Load browser auth bundle failed: ${err.message}`);
+        return errorResult(`auth_load failed: ${err.message}`);
       }
     },
   },

package/runtime/scripts/amalgm-mcp/browser/backend.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Backend routing — which browser this runtime drives.
+ *
+ * Exactly two backends:
+ *  - "attached": the visible chromium the Amalgm desktop app advertises over
+ *    CDP (or an explicit AMALGM_BROWSER_CDP_URL endpoint). The user watches
+ *    this browser in the app's split view.
+ *  - "cli": a standalone agent-browser chromium, headless. The deterministic
+ *    path for npm-only machines, servers, Fly workers, and the web client.
+ *
+ * The rule: a fresh advertisement (or explicit CDP env) ⇒ attached;
+ * otherwise ⇒ cli. "Fresh" means the advertising pid is alive. Nothing else
+ * may influence the choice — visibility must be deterministic per entrypoint.
+ * AMALGM_BROWSER_BACKEND forces a backend for debugging.
+ */
+
+function pidIsRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return Boolean(err && err.code === 'EPERM');
+  }
+}
+
+/**
+ * Bridge advertisement candidates, most specific first. Every runtime
+ * generation can find the file written by the desktop app:
+ *  - Electron-spawned and LaunchAgent runtimes have AMALGM_RUNTIME_STATE_DIR;
+ *  - runtimes with only AMALGM_DIR (+ label) derive the same path;
+ *  - bare dev runtimes fall back to the unscoped roots.
+ */
+function bridgeFileCandidates() {
+  const path = require('path');
+  const os = require('os');
+  const dirs = [];
+  if (process.env.AMALGM_RUNTIME_STATE_DIR) dirs.push(process.env.AMALGM_RUNTIME_STATE_DIR);
+  const amalgmDir = process.env.AMALGM_DIR;
+  const label = process.env.AMALGM_RUNTIME_LABEL || process.env.AMALGM_BRANCH;
+  if (amalgmDir && label) dirs.push(path.join(amalgmDir, 'runtimes', label));
+  if (amalgmDir) dirs.push(amalgmDir);
+  dirs.push(path.join(os.homedir(), '.amalgm'));
+  return [...new Set(dirs)].map((dir) => path.join(dir, 'electron-browser-bridge.json'));
+}
+
+function readBridgeAdvertisement() {
+  const fs = require('fs');
+  for (const file of bridgeFileCandidates()) {
+    try {
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (typeof data?.cdpUrl !== 'string' || !data.cdpUrl) continue;
+      if (typeof data?.pid === 'number' && !pidIsRunning(data.pid)) continue;
+      return { cdpUrl: data.cdpUrl, cdpPort: data.cdpPort, label: data.label, file };
+    } catch {}
+  }
+  return null;
+}
+
+/** Reduce a CDP url/port advertisement to the value agent-browser's --cdp flag takes. */
+function cdpFlagValue(input) {
+  const raw = String(input || '').trim();
+  if (!raw) return null;
+  if (/^\d+$/.test(raw)) return raw;
+  try {
+    const url = new URL(raw);
+    if (url.port) return url.port;
+  } catch {}
+  return raw;
+}
+
+/**
+ * The CDP endpoint for attached mode, as a --cdp flag value. agent-browser's
+ * `connect` command launches a managed browser; raw --cdp attach is the mode
+ * that discovers Electron <webview> targets, so that is all we use.
+ */
+function cdpEndpoint() {
+  if (process.env.AMALGM_BROWSER_CDP_URL) return cdpFlagValue(process.env.AMALGM_BROWSER_CDP_URL);
+  const advertisement = readBridgeAdvertisement();
+  if (!advertisement) return null;
+  if (advertisement.cdpPort) return String(advertisement.cdpPort);
+  return cdpFlagValue(advertisement.cdpUrl);
+}
+
+function mode() {
+  const requested = (process.env.AMALGM_BROWSER_BACKEND || '').toLowerCase();
+  if (['agent-browser', 'external', 'cli', 'headless'].includes(requested)) return 'cli';
+  if (['attached', 'cdp', 'electron'].includes(requested)) return 'attached';
+  return cdpEndpoint() ? 'attached' : 'cli';
+}
+
+module.exports = {
+  bridgeFileCandidates,
+  cdpEndpoint,
+  cdpFlagValue,
+  mode,
+  readBridgeAdvertisement,
+};

package/runtime/scripts/amalgm-mcp/browser/capture.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * Raster capture — screenshots and recording frames, over raw CDP.
+ *
+ * Pixels never go through the agent-browser daemon. Two reasons, both
+ * verified live against the desktop app:
+ *
+ *  - Electron <webview> guest targets do not implement raster capture:
+ *    Page.captureScreenshot never resolves and Page.startScreencast emits
+ *    zero frames. (Playwright's screenshot waits on them forever.)
+ *  - A capture stuck inside the per-session daemon starves every later
+ *    command of that session — one hung screenshot used to wedge the whole
+ *    browser until close.
+ *
+ * So captures resolve their own CDP target:
+ *  - cli (headless) sessions capture their page target, which rasters fine.
+ *  - attached sessions capture the app's top-level window — which also
+ *    rasters fine — clipped (screenshots) or cropped (recordings) to the
+ *    session's <webview> rectangle. The image is exactly the page the user
+ *    sees; the surrounding app UI never reaches a tool result or a file.
+ *
+ * Every exchange carries a hard deadline (cdp.js): a capture may fail, it
+ * can never wedge a session.
+ */
+
+const backend = require('./backend');
+const cli = require('./cli');
+const attach = require('./attach');
+const cdp = require('./cdp');
+
+const SCREENSHOT_TIMEOUT_MS = 20_000;
+const FULL_PAGE_MAX_PX = 16_384;
+
+/**
+ * Page.captureScreenshot clip (CSS px) for a webview rectangle. The capture
+ * renders at the device scale factor, so scale divides it back out — the
+ * image is CSS-pixel sized and its coordinates map 1:1 onto cua_click/
+ * cua_move input coordinates (the contract vision loops rely on).
+ */
+function clipFor(rect) {
+  return {
+    x: Math.max(0, Math.round(rect.x)),
+    y: Math.max(0, Math.round(rect.y)),
+    width: Math.max(1, Math.round(rect.width)),
+    height: Math.max(1, Math.round(rect.height)),
+    scale: 1 / (rect.dpr || 1),
+  };
+}
+
+/**
+ * ffmpeg crop for a webview rectangle, expressed in viewport fractions so it
+ * holds for whatever resolution the screencast emits (frames arrive in
+ * device pixels, the rect is measured in CSS pixels — fractions cancel the
+ * scale). Crop happens before any frame reaches disk, so the recording file
+ * only ever contains the page, not the app around it.
+ */
+function cropFilterFor(rect) {
+  const fraction = (value, total) => Math.min(Math.max(value / total, 0), 1).toFixed(6);
+  const w = fraction(rect.width, rect.vw);
+  const h = fraction(rect.height, rect.vh);
+  const x = fraction(rect.x, rect.vw);
+  const y = fraction(rect.y, rect.vh);
+  return `crop=floor(iw*${w}/2)*2:floor(ih*${h}/2)*2:floor(iw*${x}):floor(ih*${y})`;
+}
+
+/** The cli-mode daemon's CDP url (spawns the daemon on first use). */
+async function daemonCdpUrl(session) {
+  const result = await cli.runCli(['get', 'cdp-url'], { session, timeoutMs: 15_000 });
+  return result?.data?.cdpUrl || result?.cdpUrl || null;
+}
+
+/**
+ * Where to capture from for this session:
+ *   { wsUrl, clip, crop } — clip bounds screenshots, crop bounds recordings;
+ *   both null when the target's own surface is capturable as-is.
+ */
+async function plan(session, context) {
+  if (backend.mode() !== 'attached') {
+    const raw = await daemonCdpUrl(session);
+    if (!raw) throw new Error('Could not resolve a CDP endpoint for this browser session.');
+    let wsUrl = raw;
+    if (/\/devtools\/browser\//.test(raw)) {
+      const page = cdp.pageTargets(await cdp.listTargets(raw))[0];
+      if (!page) throw new Error('No capturable page target on the browser endpoint.');
+      wsUrl = page.webSocketDebuggerUrl;
+    }
+    return { wsUrl, clip: null, crop: null };
+  }
+
+  await attach.ensureReady(session, context);
+  const endpoint = backend.cdpEndpoint();
+  const targets = await cdp.listTargets(endpoint);
+
+  if (!targets.some((t) => t.type === 'webview')) {
+    // Explicit external CDP endpoint (plain chromium): its page targets
+    // raster fine — capture the driven page directly.
+    const page = cdp.pageTargets(targets)[0];
+    if (!page) throw new Error('No capturable page target on the CDP endpoint.');
+    return { wsUrl: page.webSocketDebuggerUrl, clip: null, crop: null };
+  }
+
+  // Desktop app: capture the window hosting this session's webview, bounded
+  // to the webview's on-screen rectangle. If the splitview is hidden, ask
+  // the UI to reopen it and wait briefly — captures self-heal instead of
+  // failing on a closed panel.
+  let currentUrl = '';
+  try { currentUrl = await attach.readText(session, ['get', 'url']); } catch {}
+  const surface = await attach.ensureSurfaceVisible(session, currentUrl, context, 5_000);
+  if (!surface) {
+    throw new Error(
+      'The browser surface is not visible in the desktop app — bring the Amalgm window forward and retry.',
+    );
+  }
+  return {
+    wsUrl: surface.pageWsUrl,
+    clip: clipFor(surface.rect),
+    crop: cropFilterFor(surface.rect),
+  };
+}
+
+async function screenshot(session, args = {}, context) {
+  const fullPage = Boolean(args.fullPage);
+  const source = await plan(session, context);
+  const client = await cdp.connectCdp(source.wsUrl);
+  try {
+    const params = { format: 'png' };
+    if (source.clip) {
+      params.clip = source.clip;
+    } else if (fullPage) {
+      const metrics = await client.call('Page.getLayoutMetrics');
+      const size = metrics.cssContentSize || metrics.contentSize;
+      if (size) {
+        params.clip = {
+          x: 0,
+          y: 0,
+          width: Math.min(Math.ceil(size.width), FULL_PAGE_MAX_PX),
+          height: Math.min(Math.ceil(size.height), FULL_PAGE_MAX_PX),
+          scale: 1,
+        };
+        params.captureBeyondViewport = true;
+      }
+    }
+    const { data } = await client.call('Page.captureScreenshot', params, SCREENSHOT_TIMEOUT_MS);
+    if (!data) throw new Error('Empty screenshot response');
+    return {
+      base64: data,
+      bytes: Buffer.byteLength(data, 'base64'),
+      mode: source.clip ? 'visible surface' : (fullPage ? 'full page' : 'viewport'),
+    };
+  } finally {
+    client.close();
+  }
+}
+
+module.exports = {
+  clipFor,
+  connectCdp: cdp.connectCdp,
+  cropFilterFor,
+  deadline: cdp.deadline,
+  listTargets: cdp.listTargets,
+  pageTargets: cdp.pageTargets,
+  plan,
+  rectScript: cdp.rectScript,
+  screenshot,
+  targetListUrl: cdp.targetListUrl,
+};