@crouton-kit/capture 1.3.7 → 1.3.9

package/src/cdp/screenshot.ts

@@ -1,84 +1,215 @@
-import * as fs from 'fs';
+import { PNG } from 'pngjs';
 import { CDPClient } from './client.js';
 import { nextStepPath } from '../session-context.js';
+import { writeBinaryPrivate } from '../session/artifacts.js';
+import { withScopeSerialization } from './scope-lock.js';
 
+/**
+ * Downscales a PNG so its longest side fits within maxDim, using a box
+ * filter. Used when a clipped/scaled CDP capture is unavailable and the raw
+ * capture exceeds the dimension budget.
+ */
+function downscalePngToFit(png: Buffer, maxDim: number): Buffer {
+  const src = PNG.sync.read(png);
+  const maxSide = Math.max(src.width, src.height);
+  if (maxSide <= maxDim) return png;
+  const ratio = maxDim / maxSide;
+  const dstW = Math.max(1, Math.round(src.width * ratio));
+  const dstH = Math.max(1, Math.round(src.height * ratio));
+  const dst = new PNG({ width: dstW, height: dstH });
+  for (let y = 0; y < dstH; y++) {
+    const sy0 = Math.floor((y * src.height) / dstH);
+    const sy1 = Math.max(sy0 + 1, Math.floor(((y + 1) * src.height) / dstH));
+    for (let x = 0; x < dstW; x++) {
+      const sx0 = Math.floor((x * src.width) / dstW);
+      const sx1 = Math.max(sx0 + 1, Math.floor(((x + 1) * src.width) / dstW));
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      let a = 0;
+      let n = 0;
+      for (let sy = sy0; sy < sy1 && sy < src.height; sy++) {
+        for (let sx = sx0; sx < sx1 && sx < src.width; sx++) {
+          const i = (sy * src.width + sx) * 4;
+          r += src.data[i];
+          g += src.data[i + 1];
+          b += src.data[i + 2];
+          a += src.data[i + 3];
+          n++;
+        }
+      }
+      const j = (y * dstW + x) * 4;
+      dst.data[j] = Math.round(r / n);
+      dst.data[j + 1] = Math.round(g / n);
+      dst.data[j + 2] = Math.round(b / n);
+      dst.data[j + 3] = Math.round(a / n);
+    }
+  }
+  return PNG.sync.write(dst);
+}
+
+/**
+ * Captures one screenshot, applying (and always clearing) a device-metrics
+ * override when a viewport or full-page capture is requested. The override
+ * is target-visible state driven over the connection: a direct connection's
+ * override dies with its own websocket session, but the recorder-held
+ * connection is shared across commands, so the entire
+ * setDeviceMetricsOverride→capture→clear scope serializes under the owning
+ * session's `.viewport-scope.lock` (`withScopeSerialization`) when the
+ * client is the recorder-held adapter — otherwise a concurrent routed
+ * caller could clear this capture's live override mid-scope (or capture
+ * inside someone else's).
+ */
 export async function captureScreenshot(
   client: CDPClient,
   viewport?: { width: number; height: number },
   options?: { fullPage?: boolean },
+): Promise<Buffer> {
+  return withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
+    viewportScopedCapture(client, viewport, options),
+  );
+}
+
+/**
+ * The one viewport/capture state transaction: override (when requested) →
+ * capture → clear. Restoration ownership is claimed BEFORE the override is
+ * awaited (a lost response does not prove Chrome rejected it); a clear
+ * failure prevents success — alone it throws, paired with a primary failure
+ * it throws an `AggregateError` preserving both facts.
+ */
+async function viewportScopedCapture(
+  client: CDPClient,
+  viewport?: { width: number; height: number },
+  options?: { fullPage?: boolean },
 ): Promise<Buffer> {
   const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
+  let ownsDeviceMetricsOverride = false;
+  let primaryFailed = false;
+  let primaryError: unknown;
 
-  // Apply viewport emulation if requested
-  if (viewport) {
-    await client.send('Emulation.setDeviceMetricsOverride', {
-      width: viewport.width,
-      height: viewport.height,
-      deviceScaleFactor: 1,
-      mobile: false,
-    });
-    // Let the page re-layout at the new size
-    await new Promise((r) => setTimeout(r, 150));
-  }
+  try {
+    if (viewport) {
+      // A rejected response does not prove that Chrome rejected the request.
+      // Claim cleanup responsibility before awaiting every override request.
+      ownsDeviceMetricsOverride = true;
+      await client.send('Emulation.setDeviceMetricsOverride', {
+        width: viewport.width,
+        height: viewport.height,
+        deviceScaleFactor: 1,
+        mobile: false,
+      });
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
 
-  // For full-page capture, resize viewport to the full content height
-  if (options?.fullPage) {
-    const layoutMetrics = (await client.send('Page.getLayoutMetrics')) as {
-      contentSize?: { width: number; height: number };
-      cssVisualViewport?: { clientWidth: number };
+    if (options?.fullPage) {
+      const layoutMetrics = (await client.send('Page.getLayoutMetrics')) as {
+        contentSize?: { width: number; height: number };
+        cssVisualViewport?: { clientWidth: number };
+      };
+      const contentWidth = layoutMetrics.cssVisualViewport?.clientWidth ?? viewport?.width ?? 1280;
+      const contentHeight = layoutMetrics.contentSize?.height ?? viewport?.height ?? 800;
+      ownsDeviceMetricsOverride = true;
+      await client.send('Emulation.setDeviceMetricsOverride', {
+        width: contentWidth,
+        height: Math.ceil(contentHeight),
+        deviceScaleFactor: 1,
+        mobile: false,
+      });
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+
+    let screenshotOpts: Record<string, unknown> = {
+      format: 'png',
+      captureBeyondViewport: false,
     };
-    const contentWidth = layoutMetrics.cssVisualViewport?.clientWidth ?? viewport?.width ?? 1280;
-    const contentHeight = layoutMetrics.contentSize?.height ?? viewport?.height ?? 800;
-    await client.send('Emulation.setDeviceMetricsOverride', {
-      width: contentWidth,
-      height: Math.ceil(contentHeight),
-      deviceScaleFactor: 1,
-      mobile: false,
-    });
-    await new Promise((r) => setTimeout(r, 150));
-  }
 
-  let screenshotOpts: Record<string, unknown> = {
-    format: 'png',
-    captureBeyondViewport: false,
-  };
+    try {
+      const metrics = (await client.send('Page.getLayoutMetrics')) as {
+        cssVisualViewport?: { clientWidth: number; clientHeight: number; pageX: number; pageY: number };
+      };
+      // Snap the clip to integer CSS pixels: browser zoom (e.g. 110%) makes the
+      // CSS viewport fractional, and some Chromium-based browsers (Arc, at
+      // least) answer a clipped Page.captureScreenshot whose output dimensions
+      // are fractional with a SUCCESSFUL response carrying empty `data`.
+      const vw = Math.round(metrics.cssVisualViewport?.clientWidth ?? 0);
+      const vh = Math.round(metrics.cssVisualViewport?.clientHeight ?? 0);
+      const sx = Math.floor(metrics.cssVisualViewport?.pageX ?? 0);
+      const sy = Math.floor(metrics.cssVisualViewport?.pageY ?? 0);
 
-  try {
-    const metrics = (await client.send('Page.getLayoutMetrics')) as {
-      cssVisualViewport?: { clientWidth: number; clientHeight: number; pageX: number; pageY: number };
-    };
-    const vw = metrics.cssVisualViewport?.clientWidth ?? 0;
-    const vh = metrics.cssVisualViewport?.clientHeight ?? 0;
-    const sx = metrics.cssVisualViewport?.pageX ?? 0;
-    const sy = metrics.cssVisualViewport?.pageY ?? 0;
-
-    const dprResult = (await client.send('Runtime.evaluate', {
-      expression: 'window.devicePixelRatio',
-      returnByValue: true,
-    })) as { result: { value: number } };
-    const dpr = dprResult.result.value ?? 1;
-
-    const actualMaxSide = Math.max(vw, vh) * dpr;
-    const scale = actualMaxSide > MAX_DIM ? MAX_DIM / actualMaxSide : 1 / dpr;
-    screenshotOpts = {
-      ...screenshotOpts,
-      clip: { x: sx, y: sy, width: vw, height: vh, scale },
-    };
-  } catch {
-    // Fallback: capture without downscaling
-  }
+      const dprResult = (await client.send('Runtime.evaluate', {
+        expression: 'window.devicePixelRatio',
+        returnByValue: true,
+      })) as { result: { value: number } };
+      const dpr = dprResult.result.value ?? 1;
 
-  const result = (await client.send(
-    'Page.captureScreenshot',
-    screenshotOpts,
-  )) as { data: string };
+      const actualMaxSide = Math.max(vw, vh) * dpr;
+      const scale = actualMaxSide > MAX_DIM ? MAX_DIM / actualMaxSide : 1 / dpr;
+      screenshotOpts = {
+        ...screenshotOpts,
+        clip: { x: sx, y: sy, width: vw, height: vh, scale },
+      };
+    } catch {
+      // Capture without downscaling when the optional metrics probe is unavailable.
+    }
 
-  // Reset emulation so the browser window isn't stuck at the overridden size
-  if (viewport || options?.fullPage) {
-    await client.send('Emulation.clearDeviceMetricsOverride');
-  }
+    const result = (await client.send(
+      'Page.captureScreenshot',
+      screenshotOpts,
+    )) as { data?: string };
+    let png = Buffer.from(result.data ?? '', 'base64');
+
+    // A fractional scale (1/devicePixelRatio) can still produce fractional
+    // output dimensions, which the browsers above answer with empty data.
+    // Retry the same integer clip at scale 1, preserving full-page captures,
+    // then enforce the dimension budget locally.
+    if (png.length === 0 && screenshotOpts.clip) {
+      const clip = screenshotOpts.clip as Record<string, unknown>;
+      const retry = (await client.send('Page.captureScreenshot', {
+        ...screenshotOpts,
+        clip: { ...clip, scale: 1 },
+      })) as { data?: string };
+      png = Buffer.from(retry.data ?? '', 'base64');
+      if (png.length > 0) png = downscalePngToFit(png, MAX_DIM);
+    }
+
+    // If the browser rejects clipped capture entirely, an unclipped viewport
+    // capture is still better than a false successful 0-byte artifact.
+    if (png.length === 0 && screenshotOpts.clip && !options?.fullPage) {
+      const retry = (await client.send('Page.captureScreenshot', {
+        format: 'png',
+        captureBeyondViewport: false,
+      })) as { data?: string };
+      png = Buffer.from(retry.data ?? '', 'base64');
+      if (png.length > 0) png = downscalePngToFit(png, MAX_DIM);
+    }
 
-  return Buffer.from(result.data, 'base64');
+    if (png.length === 0) {
+      throw new Error(
+        'Page.captureScreenshot returned no image data (the tab may not be rendering); refusing to write a 0-byte PNG',
+      );
+    }
+
+    return png;
+  } catch (error) {
+    primaryFailed = true;
+    primaryError = error;
+    throw error;
+  } finally {
+    if (ownsDeviceMetricsOverride) {
+      try {
+        await client.send('Emulation.clearDeviceMetricsOverride');
+      } catch (cleanupError) {
+        if (primaryFailed) {
+          throw new AggregateError(
+            [primaryError, cleanupError],
+            'Screenshot capture failed and device-metrics cleanup also failed.',
+            { cause: primaryError },
+          );
+        }
+        throw cleanupError;
+      }
+    }
+  }
 }
 
 export async function autoScreenshot(
@@ -88,13 +219,15 @@ export async function autoScreenshot(
   noScreenshot?: boolean,
 ): Promise<string | null> {
   if (noScreenshot) return null;
-  const shotPath = nextStepPath(action, label);
+  const shotPath = await nextStepPath(action, label);
   if (!shotPath) return null;
 
   // Brief settle for UI to update
   await new Promise((r) => setTimeout(r, 300));
   const png = await captureScreenshot(client);
-  fs.writeFileSync(shotPath, png);
+  // Shot path always resolves under the session dir (CAPTURE_ROOT); the
+  // private writer creates the file 0600 and re-ensures shots/ is 0700.
+  writeBinaryPrivate(shotPath, png);
   console.error(`  [screenshot] ${shotPath}`);
   return shotPath;
 }

package/src/cdp/source-map.ts

@@ -0,0 +1,309 @@
+/**
+ * Source provenance helper: resolves a generated CSS/JS location (as reported by
+ * `CSS.getMatchedStylesForNode`'s stylesheet ranges, or any other generated-source location)
+ * to an authored file/line/column via the standard source-map-v3 `mappings` VLQ format, when
+ * the generated source carries a `sourceMappingURL`. Degrades to the generated source URL when
+ * no source map is present, fails to fetch, or fails to parse — this module never throws for
+ * "no source map available"; it throws only for a malformed CDP response.
+ *
+ * No `source-map` npm dependency is added (this unit does not own `package.json`); the VLQ
+ * decoder below is a self-contained implementation of the standard algorithm.
+ *
+ * Selector/specificity fields that round out full provenance (used by `styles.json`) are the
+ * caller's (U08 styles collector's) responsibility — this module resolves source *location*
+ * only.
+ */
+
+import type { CDPClient } from './client.js';
+
+/** Where a generated location came from and which position in it to resolve. */
+export interface GeneratedSourceRef {
+  /** A CDP stylesheet id — when present, the generated text is read via `CSS.getStyleSheetText`. */
+  styleSheetId?: string;
+  /**
+   * Absolute URL of the generated source. Used as the fetch target when `styleSheetId` is
+   * absent, as the base URL for resolving a relative `sourceMappingURL`, and as the reported
+   * generated-source URL either way.
+   */
+  sourceURL?: string;
+  /** 0-indexed line in the generated source. */
+  line: number;
+  /** 0-indexed column in the generated source. */
+  column: number;
+}
+
+export interface GeneratedLocation {
+  kind: 'generated';
+  sourceURL: string;
+  line: number;
+  column: number;
+}
+
+export interface AuthoredLocation {
+  kind: 'authored';
+  generated: { sourceURL: string; line: number; column: number };
+  /** Authored source file path/URL as recorded in the source map's `sources` (joined with `sourceRoot` when present). */
+  file: string;
+  /** 1-indexed authored line. */
+  line: number;
+  /** 0-indexed authored column. */
+  column: number;
+  /** Inlined authored source text, when the source map carries `sourcesContent` for this source. */
+  sourceContent?: string;
+}
+
+export type ResolvedSourceLocation = AuthoredLocation | GeneratedLocation;
+
+/**
+ * Resolves `ref` to an authored file/line/column when a `sourceMappingURL` is present and
+ * resolvable, otherwise returns the generated source location unchanged.
+ */
+export async function resolveAuthoredSourceLocation(
+  client: CDPClient,
+  ref: GeneratedSourceRef,
+): Promise<ResolvedSourceLocation> {
+  const { text, sourceURL } = await fetchGeneratedText(client, ref);
+  const generated: GeneratedLocation = { kind: 'generated', sourceURL, line: ref.line, column: ref.column };
+
+  if (!text) return generated;
+
+  const mappingURL = extractSourceMappingURL(text);
+  if (!mappingURL) return generated;
+
+  const rawMap = await loadSourceMap(mappingURL, sourceURL);
+  if (!rawMap) return generated;
+
+  const authored = mapGeneratedPosition(rawMap, ref.line, ref.column);
+  if (!authored) return generated;
+
+  return {
+    kind: 'authored',
+    generated: { sourceURL, line: ref.line, column: ref.column },
+    file: authored.file,
+    line: authored.line,
+    column: authored.column,
+    sourceContent: authored.sourceContent,
+  };
+}
+
+async function fetchGeneratedText(
+  client: CDPClient,
+  ref: GeneratedSourceRef,
+): Promise<{ text: string | null; sourceURL: string }> {
+  if (ref.styleSheetId) {
+    try {
+      const result = (await client.send('CSS.getStyleSheetText', {
+        styleSheetId: ref.styleSheetId,
+      })) as { text: string };
+      return { text: result.text, sourceURL: ref.sourceURL ?? ref.styleSheetId };
+    } catch {
+      // Stylesheet text unavailable (e.g. a stale styleSheetId) — fall through to a direct fetch.
+    }
+  }
+
+  if (ref.sourceURL) {
+    try {
+      const text = await fetchText(ref.sourceURL);
+      return { text, sourceURL: ref.sourceURL };
+    } catch {
+      return { text: null, sourceURL: ref.sourceURL };
+    }
+  }
+
+  return { text: null, sourceURL: '' };
+}
+
+const SOURCE_MAPPING_URL_RE = /\/\*[#@]\s*sourceMappingURL=([^\s*]+)\s*\*\/|\/\/[#@]\s*sourceMappingURL=([^\s]+)/g;
+
+/** Finds the `sourceMappingURL` comment in generated CSS/JS text. When more than one is present, the last wins (spec convention). */
+export function extractSourceMappingURL(text: string): string | null {
+  SOURCE_MAPPING_URL_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  let last: string | null = null;
+  while ((match = SOURCE_MAPPING_URL_RE.exec(text)) !== null) {
+    last = match[1] ?? match[2] ?? last;
+  }
+  return last;
+}
+
+export interface RawSourceMap {
+  version: number;
+  sources: string[];
+  sourcesContent?: (string | null)[];
+  names?: string[];
+  mappings: string;
+  sourceRoot?: string;
+  file?: string;
+}
+
+async function loadSourceMap(mappingURL: string, baseURL: string): Promise<RawSourceMap | null> {
+  if (mappingURL.startsWith('data:')) {
+    return parseDataURISourceMap(mappingURL);
+  }
+
+  try {
+    const resolved = baseURL ? new URL(mappingURL, baseURL).toString() : mappingURL;
+    const text = await fetchText(resolved);
+    return JSON.parse(text) as RawSourceMap;
+  } catch {
+    return null;
+  }
+}
+
+function parseDataURISourceMap(dataURI: string): RawSourceMap | null {
+  const commaIndex = dataURI.indexOf(',');
+  if (commaIndex === -1) return null;
+  const meta = dataURI.slice('data:'.length, commaIndex);
+  const payload = dataURI.slice(commaIndex + 1);
+  try {
+    const json = meta.includes(';base64') ? Buffer.from(payload, 'base64').toString('utf8') : decodeURIComponent(payload);
+    return JSON.parse(json) as RawSourceMap;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchText(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Fetching ${url} returned HTTP ${response.status}`);
+  }
+  return response.text();
+}
+
+export interface AuthoredPosition {
+  file: string;
+  /** 1-indexed authored line. */
+  line: number;
+  /** 0-indexed authored column. */
+  column: number;
+  sourceContent?: string;
+}
+
+/**
+ * Maps a 0-indexed (generatedLine, generatedColumn) position through a parsed source-map-v3
+ * `mappings` string to the nearest preceding authored position on that generated line. Pure —
+ * no I/O, no CDP — so it is directly testable against a fixture map.
+ */
+export function mapGeneratedPosition(
+  rawMap: RawSourceMap,
+  generatedLine: number,
+  generatedColumn: number,
+): AuthoredPosition | null {
+  const entries = decodeMappings(rawMap.mappings).filter(
+    (entry) => entry.generatedLine === generatedLine && entry.sourceIndex !== undefined,
+  );
+  if (entries.length === 0) return null;
+
+  let best: MappingEntry | undefined;
+  for (const entry of entries) {
+    if (entry.generatedColumn <= generatedColumn && (!best || entry.generatedColumn > best.generatedColumn)) {
+      best = entry;
+    }
+  }
+  best = best ?? entries[0];
+
+  const sourceIndex = best.sourceIndex as number;
+  const sourcePath = rawMap.sources[sourceIndex];
+  if (sourcePath === undefined) return null;
+
+  const file = rawMap.sourceRoot ? joinSourceRoot(rawMap.sourceRoot, sourcePath) : sourcePath;
+  const sourceContent = rawMap.sourcesContent?.[sourceIndex] ?? undefined;
+
+  return {
+    file,
+    line: (best.sourceLine ?? 0) + 1,
+    column: best.sourceColumn ?? 0,
+    sourceContent,
+  };
+}
+
+function joinSourceRoot(root: string, source: string): string {
+  if (source.startsWith('/') || /^[a-z]+:\/\//i.test(source)) return source;
+  return root.endsWith('/') ? `${root}${source}` : `${root}/${source}`;
+}
+
+interface MappingEntry {
+  generatedLine: number;
+  generatedColumn: number;
+  sourceIndex?: number;
+  sourceLine?: number;
+  sourceColumn?: number;
+  nameIndex?: number;
+}
+
+const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const BASE64_LOOKUP = new Map<string, number>(Array.from(BASE64_CHARS).map((char, index) => [char, index]));
+
+const VLQ_BASE_SHIFT = 5;
+const VLQ_BASE = 1 << VLQ_BASE_SHIFT;
+const VLQ_BASE_MASK = VLQ_BASE - 1;
+const VLQ_CONTINUATION_BIT = VLQ_BASE;
+
+/** Decodes every VLQ-encoded number concatenated in one comma-delimited mapping segment. */
+function decodeVLQSegment(segment: string): number[] {
+  const values: number[] = [];
+  let shift = 0;
+  let result = 0;
+
+  for (const char of segment) {
+    const digit = BASE64_LOOKUP.get(char);
+    if (digit === undefined) {
+      throw new Error(`Invalid base64 VLQ character in source map mappings: ${JSON.stringify(char)}`);
+    }
+    const continuation = digit & VLQ_CONTINUATION_BIT;
+    const bits = digit & VLQ_BASE_MASK;
+    result += bits << shift;
+    if (continuation) {
+      shift += VLQ_BASE_SHIFT;
+    } else {
+      const negate = result & 1;
+      result >>= 1;
+      values.push(negate ? -result : result);
+      result = 0;
+      shift = 0;
+    }
+  }
+
+  return values;
+}
+
+/** Decodes a full source-map-v3 `mappings` string into per-generated-position entries with sources/names deltas resolved. */
+function decodeMappings(mappings: string): MappingEntry[] {
+  const entries: MappingEntry[] = [];
+  const lines = mappings.split(';');
+
+  let sourceIndex = 0;
+  let sourceLine = 0;
+  let sourceColumn = 0;
+  let nameIndex = 0;
+
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const lineText = lines[lineIndex];
+    if (lineText === '') continue;
+
+    let generatedColumn = 0;
+    for (const segment of lineText.split(',')) {
+      if (segment === '') continue;
+      const fields = decodeVLQSegment(segment);
+      generatedColumn += fields[0];
+
+      const entry: MappingEntry = { generatedLine: lineIndex, generatedColumn };
+      if (fields.length > 1) {
+        sourceIndex += fields[1];
+        sourceLine += fields[2];
+        sourceColumn += fields[3];
+        entry.sourceIndex = sourceIndex;
+        entry.sourceLine = sourceLine;
+        entry.sourceColumn = sourceColumn;
+        if (fields.length > 4) {
+          nameIndex += fields[4];
+          entry.nameIndex = nameIndex;
+        }
+      }
+      entries.push(entry);
+    }
+  }
+
+  return entries;
+}

package/src/cdp/targets.ts

@@ -25,7 +25,7 @@ export async function getBrowserClient(
     throw new Error(
       `Port ${port} answers CDP's /json/version but has no browser-level WebSocket debugger URL — ` +
         `it's not a real browser (e.g. a Node/workerd inspector), so it can't host tabs. ` +
-        `Run "capture detect" to find a real browser endpoint, or pass --port explicitly.`,
+        `Run "capture tab list" to find a real browser endpoint, or pass --port explicitly.`,
     );
   }
   const client = new CDPClient(version.webSocketDebuggerUrl);
@@ -208,6 +208,26 @@ export function requireTargetId(
   return targetId;
 }
 
+/**
+ * Closes exactly one target through the browser-level connection, the mirror of
+ * `openTab`. Transactional owners (session-start rollback) call this to release
+ * ONLY the target this attempt opened; it never touches foreign/pre-existing
+ * tabs. Throws when `Target.closeTarget` reports the target was not closed.
+ */
+export async function closeTarget(port: number, targetId: string): Promise<void> {
+  const { client } = await getBrowserClient(port);
+  try {
+    const result = (await client.send('Target.closeTarget', { targetId })) as {
+      success?: boolean;
+    };
+    if (result?.success === false) {
+      throw new Error(`Target.closeTarget reported no close for target ${targetId} on port ${port}.`);
+    }
+  } finally {
+    client.close();
+  }
+}
+
 export async function openTab(port: number, url: string): Promise<CDPTarget> {
   const { client } = await getBrowserClient(port);