@crouton-kit/capture 1.4.14 → 1.4.16

package/bin/capture

@@ -3769,6 +3769,14 @@ var init_client = __esm({
   }
 });
 
+// src/cdp/loopback.ts
+var CDP_LOOPBACK_HOST;
+var init_loopback = __esm({
+  "src/cdp/loopback.ts"() {
+    CDP_LOOPBACK_HOST = "127.0.0.1";
+  }
+});
+
 // src/cdp/detect.ts
 var detect_exports = {};
 __export(detect_exports, {
@@ -3784,7 +3792,7 @@ __export(detect_exports, {
 function httpGetJson(port, path48, timeoutMs) {
   return new Promise((resolve12) => {
     const req = http.get(
-      { host: "localhost", port, path: path48, timeout: timeoutMs },
+      { host: CDP_LOOPBACK_HOST, port, path: path48, timeout: timeoutMs },
       (res) => {
         const status = res.statusCode ?? 0;
         if (status < 200 || status >= 300) {
@@ -3962,6 +3970,7 @@ var init_detect = __esm({
   "src/cdp/detect.ts"() {
     import_child_process = require("child_process");
     http = __toESM(require("http"));
+    init_loopback();
     BROWSER_PATTERNS = {
       "company.thebrowser.browser": ["arc"],
       "com.google.chrome": ["chrome", "google chrome"],
@@ -5664,7 +5673,7 @@ async function reap(record5) {
 }
 async function endpointAnswers(port) {
   try {
-    const response = await fetch(`http://127.0.0.1:${port}/json/version`, {
+    const response = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`, {
       signal: AbortSignal.timeout(ENDPOINT_PROBE_MS)
     });
     return response.ok;
@@ -5765,12 +5774,26 @@ function devToolsPort(profileDir) {
     return null;
   }
 }
+function assertPortUnbound(port) {
+  try {
+    const output = (0, import_node_child_process2.execFileSync)("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-F", "n"], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+    if (output.trim()) {
+      throw captureError("precondition", "browser_port_in_use", `received: port ${port}; expected: no TCP listener on that port. Capture refuses to launch because the endpoint would be ambiguous across loopback address families.`);
+    }
+  } catch (error4) {
+    if (error4.status === 1) return;
+    if (error4 instanceof CaptureError && error4.descriptor.code === "browser_port_in_use") throw error4;
+    throw captureError("world", "browser_port_check_failed", `received: port ${port}; checking TCP listeners with lsof failed, so Capture cannot prove the port is unbound: ${error4 instanceof Error ? error4.message : String(error4)}`, error4);
+  }
+}
 async function launchOwnedBrowser(options) {
+  if (options.port !== void 0) assertPortUnbound(options.port);
   const executablePath = resolveBrowserExecutable(options.headless);
   const token2 = crypto2.randomBytes(8).toString("hex");
   const profileDir = ensurePrivateDir(profilePath(token2));
   const args = [
     `--remote-debugging-port=${options.port ?? 0}`,
+    `--remote-debugging-address=${CDP_LOOPBACK_HOST}`,
     `--user-data-dir=${profileDir}`,
     "--no-first-run",
     "--no-default-browser-check",
@@ -5841,6 +5864,7 @@ var init_browser_process = __esm({
     os2 = __toESM(require("node:os"));
     path2 = __toESM(require("node:path"));
     init_errors();
+    init_loopback();
     init_artifacts();
     IDLE_REAP_MS = 30 * 60 * 1e3;
     READY_TIMEOUT_MS = 15e3;
@@ -5886,6 +5910,7 @@ var targets_exports = {};
 __export(targets_exports, {
   AmbiguousPageTargetError: () => AmbiguousPageTargetError,
   closeTarget: () => closeTarget,
+  findResponsivePageTabByUrl: () => findResponsivePageTabByUrl,
   findTab: () => findTab,
   findTabById: () => findTabById,
   findTabByIdAcrossEndpoints: () => findTabByIdAcrossEndpoints,
@@ -5899,7 +5924,7 @@ __export(targets_exports, {
   scoreTabUrlMatch: () => scoreTabUrlMatch
 });
 async function getBrowserClient(port) {
-  const versionResp = await fetch(`http://localhost:${port}/json/version`);
+  const versionResp = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`);
   if (!versionResp.ok) {
     throw new Error(
       `Failed to connect to CDP on port ${port}: ${versionResp.status}`
@@ -5911,10 +5936,12 @@ async function getBrowserClient(port) {
       `Port ${port} answers CDP's /json/version but has no browser-level WebSocket debugger URL \u2014 it's not a real browser (e.g. a Node/workerd inspector), so it can't host tabs. Run "capture tab list" to find a real browser endpoint, or pass --port explicitly.`
     );
   }
-  const client = new CDPClient(version.webSocketDebuggerUrl);
+  const browserWsUrl = new URL(version.webSocketDebuggerUrl);
+  browserWsUrl.hostname = CDP_LOOPBACK_HOST;
+  const client = new CDPClient(browserWsUrl.toString());
   await client.waitReady();
   touchOwnedBrowser(port);
-  return { client, browserWsUrl: version.webSocketDebuggerUrl };
+  return { client, browserWsUrl: browserWsUrl.toString() };
 }
 async function listTargets(port) {
   const { client } = await getBrowserClient(port);
@@ -5926,7 +5953,7 @@ async function listTargets(port) {
       title: t.title,
       url: t.url,
       type: t.type,
-      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${t.targetId}`
+      webSocketDebuggerUrl: `ws://${CDP_LOOPBACK_HOST}:${port}/devtools/page/${t.targetId}`
     }));
   } finally {
     client.close();
@@ -5985,7 +6012,9 @@ function normalizeUrlForMatch(value) {
     const path48 = url.pathname.replace(/\/+$/, "") || "/";
     return {
       full: `${url.origin}${path48}${url.search}${url.hash}`.toLowerCase(),
-      host: url.hostname.toLowerCase(),
+      // `host` (not `hostname`): two local dev servers on the same loopback
+      // address but different ports must not register as a host match.
+      host: url.host.toLowerCase(),
       path: path48.toLowerCase()
     };
   } catch {
@@ -6021,6 +6050,25 @@ async function findTabByIdAcrossEndpoints(targetId, preferredPort) {
   const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
   return findTabByIdInPorts(targetId, ports);
 }
+async function findResponsivePageTabByUrl(port, url) {
+  const pages = (await listTargets(port)).filter((target) => target.type === "page");
+  const scores = pages.map((target) => scoreTabUrlMatch(target.url, url));
+  const bestScore = Math.max(0, ...scores);
+  if (bestScore === 0) return null;
+  for (const target of pages.filter((_, index) => scores[index] === bestScore)) {
+    if (!target.webSocketDebuggerUrl) continue;
+    const client = new CDPClient(target.webSocketDebuggerUrl);
+    try {
+      await client.waitReady();
+      await client.send("Page.captureScreenshot", { format: "png" }, 5e3);
+      return target;
+    } catch {
+    } finally {
+      client.close();
+    }
+  }
+  return null;
+}
 async function findTabByUrlAcrossEndpoints(url, preferredPort) {
   const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
   let best = null;
@@ -6071,7 +6119,7 @@ async function openTab(port, url) {
       title: "",
       url,
       type: "page",
-      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${targetId}`
+      webSocketDebuggerUrl: `ws://${CDP_LOOPBACK_HOST}:${port}/devtools/page/${targetId}`
     };
   } finally {
     client.close();
@@ -6081,6 +6129,7 @@ var AmbiguousPageTargetError;
 var init_targets = __esm({
   "src/cdp/targets.ts"() {
     init_client();
+    init_loopback();
     init_detect();
     init_browser_process();
     AmbiguousPageTargetError = class extends Error {
@@ -10512,7 +10561,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.14";
+  const version = "1.4.16";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12614,7 +12663,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.14";
+  const version = "1.4.16";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -15111,6 +15160,7 @@ async function start(parsed) {
     let bridgeSocket = null;
     let bridgePid = null;
     let cdpPort = null;
+    let targetWasOpened = false;
     let selectedBrowser = null;
     let endpointSelectionReason = null;
     try {
@@ -15137,22 +15187,28 @@ async function start(parsed) {
         }
       }
       if (url) {
+        let opened = false;
         try {
           target = await startWorld.openTab(cdpPort, url);
+          opened = true;
+          targetWasOpened = true;
         } catch (error4) {
           const message = error4 instanceof Error ? error4.message : String(error4);
-          if (message.toLowerCase().includes("not supported")) {
+          if (!message.toLowerCase().includes("not supported")) throw error4;
+          target = await startWorld.findResponsivePageTabByUrl?.(cdpPort, url) ?? null;
+          if (!target) {
             throw worldFailure(
-              `Target.createTarget is unsupported on port ${cdpPort}. Use an existing tab: \`capture tab list --port ${cdpPort}\`, then \`capture session start --target <target-id> --port ${cdpPort}\`.`,
+              `Target.createTarget is unsupported on port ${cdpPort}, and no matching existing page target answered a screenshot. Run \`capture tab list --port ${cdpPort}\` to inspect its targets.`,
               error4
             );
           }
-          throw error4;
         }
-        const openedPort = cdpPort;
-        const openedTargetId = target.id;
-        acquired.push({ label: "opened target", release: () => startWorld.closeTarget(openedPort, openedTargetId) });
-        pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        if (opened) {
+          const openedPort = cdpPort;
+          const openedTargetId = target.id;
+          acquired.push({ label: "opened target", release: () => startWorld.closeTarget(openedPort, openedTargetId) });
+          pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        }
       }
       if (hold) {
         const bridge = await startWorld.startBridge(dir, cdpPort);
@@ -15182,7 +15238,7 @@ async function start(parsed) {
       return;
     }
     const rows = [fact`bundle dir: ${dir}`];
-    if (target) rows.push(url ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
+    if (target) rows.push(targetWasOpened ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
     if (cdpPort !== null) rows.push(
       parsed.portSource === "env" ? fact`CDP endpoint on port ${cdpPort} selected from ambient CDP_PORT; --port overrides endpoint selection and --target overrides tab selection.` : parsed.port !== void 0 ? fact`CDP endpoint on port ${cdpPort} selected by explicit --port; --port overrides endpoint selection and --target overrides tab selection.` : fact`${selectedBrowser ?? "CDP endpoint"} on port ${cdpPort} auto-selected because it ${endpointSelectionReason ?? "was selected by automatic endpoint detection"}; capture-launched browser recency does not affect selection. --port overrides endpoint selection and --target overrides tab selection.`
     );
@@ -15409,6 +15465,7 @@ function responseEndDateTime(requestWallTime, requestMonotonic, terminalMonotoni
   return Number.isNaN(end.getTime()) ? null : end.toISOString();
 }
 function completedTiming(e) {
+  if ("_resourceType" in e) return fact`WebSocket: ${e._webSocketMessages.length} frame(s) recorded`;
   const { clocks, terminal: terminal2 } = e._capture;
   if (terminal2.kind === "failed") {
     return fact`duration ${e.time} ms — response incomplete: failed`;
@@ -16098,10 +16155,10 @@ use when collecting or reading the traffic, logs, and artifacts of scoped work a
 
 input:
   --url <url>       Absolute URL to open in a fresh tab through CDP's
-                    Target.createTarget. Some endpoints, including Electron,
-                    expose existing tabs but reject Target.createTarget; on
-                    those endpoints --url cannot be used. Conflicts with
-                    --target.
+                    Target.createTarget. If an endpoint, including Electron,
+                    rejects Target.createTarget, capture adopts the matching
+                    existing page target that answers a screenshot. Conflicts
+                    with --target.
   --target <tab-id>  Existing page tab to adopt. Resolves a full target id or
                     an unambiguous prefix of at least four characters at the
                     selected CDP endpoint; start fails if it does not resolve.
@@ -16247,6 +16304,10 @@ effects:
         const { findTabById: findTabById2 } = await Promise.resolve().then(() => (init_targets(), targets_exports));
         return findTabById2(port, targetId);
       },
+      async findResponsivePageTabByUrl(port, url) {
+        const { findResponsivePageTabByUrl: findResponsivePageTabByUrl2 } = await Promise.resolve().then(() => (init_targets(), targets_exports));
+        return findResponsivePageTabByUrl2(port, url);
+      },
       async closeTarget(port, targetId) {
         const { closeTarget: closeTarget2 } = await Promise.resolve().then(() => (init_targets(), targets_exports));
         return closeTarget2(port, targetId);
@@ -229755,6 +229816,7 @@ async function cmdTabLaunch(parsed, _args) {
     console.log(USAGE9);
     return;
   }
+  if (parsed.port !== void 0) assertPortUnbound(parsed.port);
   const swept = await sweepOwnedBrowsers();
   const browser = await launchOwnedBrowser({
     url: parsed.url,
@@ -239412,7 +239474,7 @@ function artifactEntries(dir, artifacts, listCrops) {
     if (!listCrops && name.startsWith("crops/")) continue;
     entries.push({
       name,
-      ...name === "geometry.json" && geometryCount !== void 0 ? { note: `${geometryCount} elements` } : {}
+      ...name === "geometry.json" && geometryCount !== void 0 ? { note: `${geometryCount} elements at .elements[]` } : {}
     });
   }
   if (!listCrops && crops.length) entries.push({ name: "crops/", note: `${crops.length} crops; pass --list-crops for paths` });
@@ -243965,7 +244027,7 @@ static page measurement \u2014 \`snap\` waits for the page to settle, then recor
 use when a claim depends on what is rendered right now: element geometry, overflow, clipping, stacking, computed style and where it came from, text and contrast, focus order, scroll containers, paint coverage, or the difference between two snapshots
 </command>`;
     MEASURE_USAGE = `<command name="measure" description="enriched snapshot substrate and read-only queries">
-<model>\`snap\` drives the page (or a base snapshot) and writes one settled artifact directory; every other leaf below reads that artifact and never re-drives the browser unless its target is a URL, which first creates a snapshot. Findings exit 0 \u2014 a report, not a failure. \`--gate\` (exit 2 on findings or changes) is accepted only by check and diff.</model>
+<model>\`snap\` drives the page (or a base snapshot) and writes one settled artifact directory; every other leaf below reads that artifact and never re-drives the browser unless its target is a URL, which first creates a snapshot. Findings exit 0 \u2014 a report, not a failure. \`--gate\` (exit 2 on findings or changes) is accepted only by check and diff. \`explain\` (and \`map paint\`) take the snapshot as \`<snap>\` positionally and name the element with a required \`--selector\`, unlike every other leaf's plain \`[url|snap]\` target.</model>
 <subcommand name="snap" description="settled snapshot artifact" whenToUse="Use to capture the static rendered-page substrate that measure queries read."/>
 <subcommand name="check" description="snapshot threshold measurements" whenToUse="Use to measure selected layout and content thresholds from one snapshot."/>
 <subcommand name="diff" description="snapshot delta" whenToUse="Use to compare the measured facts from two snapshots."/>
@@ -243976,7 +244038,7 @@ use when a claim depends on what is rendered right now: element geometry, overfl
 <subcommand name="map" description="one snapshot facet" whenToUse="Use to read focus, scroll, layer, accessibility, or paint facts from a snapshot."/>
 </command>`;
     MEASURE_MAP_USAGE = `<command name="map" description="one facet of a snapshot's substrate">
-<model>Focus, scroll, layers, and ax accept a URL target and create a snapshot first; paint requires an existing snapshot and reads it without browser driving.</model>
+<model>Focus, scroll, layers, and ax accept a URL target and create a snapshot first; paint requires an existing snapshot (\`<snap>\`, no URL) plus a required \`--selector\` naming the element, and reads it without browser driving.</model>
 <subcommand name="focus" description="keyboard traversal order" whenToUse="Use to inspect focus order from a snapshot."/>
 <subcommand name="scroll" description="scroll-container topology" whenToUse="Use to inspect scroll containers and their relationships."/>
 <subcommand name="layers" description="paint and compositor layers" whenToUse="Use to inspect layer allocation and paint order."/>
@@ -266843,7 +266905,7 @@ async function releaseTracing(reservation) {
 async function pageForSessionTarget(port, targetId) {
   const lighthouseRequire = (0, import_node_module.createRequire)(require.resolve("lighthouse"));
   const puppeteer = lighthouseRequire("puppeteer-core");
-  const browser = await puppeteer.connect({ browserURL: `http://localhost:${port}`, defaultViewport: null });
+  const browser = await puppeteer.connect({ browserURL: `http://${CDP_LOOPBACK_HOST}:${port}`, defaultViewport: null });
   try {
     for (const page of await browser.pages()) {
       const session = await page.target().createCDPSession();
@@ -267050,6 +267112,7 @@ var init_lighthouse = __esm({
     import_node_module = require("node:module");
     init_detect();
     init_errors();
+    init_loopback();
     init_selection();
     init_artifacts();
     init_session_context();
@@ -267296,7 +267359,7 @@ I/O contract: flags and positionals on input; one rendered prose block on stdout
 A CDP-enabled browser must be running; \`capture tab list\` is the probe, and \`capture tab launch\` starts one capture owns and reaps when nothing is (never hand-roll a detached browser \u2014 nothing reaps that). Capture never signals a browser it did not start, so attaching to your own with --port is unchanged. CDP_PORT / CDP_TARGET pin the browser + tab for target-selecting commands \u2014 precedence: explicit flag > active session > env. \`session start\` adopts only an explicit --target.`;
 }
 function printVersion() {
-  const declared = "1.4.14";
+  const declared = "1.4.16";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.14",
+  "version": "1.4.16",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/cdp/browser-process.ts

@@ -35,12 +35,13 @@
  *      rather than living until reboot.
  */
 
-import { spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { captureError } from '../errors.js';
+import { CaptureError, captureError } from '../errors.js';
+import { CDP_LOOPBACK_HOST } from './loopback.js';
 import {
   CAPTURE_ROOT,
   assertUnderCaptureRoot,
@@ -230,7 +231,7 @@ async function reap(record: OwnedBrowser): Promise<void> {
 
 async function endpointAnswers(port: number): Promise<boolean> {
   try {
-    const response = await fetch(`http://127.0.0.1:${port}/json/version`, {
+    const response = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`, {
       signal: AbortSignal.timeout(ENDPOINT_PROBE_MS),
     });
     return response.ok;
@@ -421,6 +422,23 @@ function devToolsPort(profileDir: string): number | null {
   }
 }
 
+/** Refuses an explicit debugging port already listened on through either
+ * address family. `lsof` exits 1 when it found no listener; every other
+ * failure is a failed precondition check, never permission to launch into an
+ * endpoint whose identity capture cannot establish. */
+export function assertPortUnbound(port: number): void {
+  try {
+    const output = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-F', 'n'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (output.trim()) {
+      throw captureError('precondition', 'browser_port_in_use', `received: port ${port}; expected: no TCP listener on that port. Capture refuses to launch because the endpoint would be ambiguous across loopback address families.`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).status === 1) return;
+    if (error instanceof CaptureError && error.descriptor.code === 'browser_port_in_use') throw error;
+    throw captureError('world', 'browser_port_check_failed', `received: port ${port}; checking TCP listeners with lsof failed, so Capture cannot prove the port is unbound: ${error instanceof Error ? error.message : String(error)}`, error);
+  }
+}
+
 export interface LaunchOptions {
   /** First page to open; `about:blank` when unset. */
   url?: string;
@@ -436,11 +454,13 @@ export interface LaunchOptions {
  * `startBridge()` applies to the bridge process it spawns.
  */
 export async function launchOwnedBrowser(options: LaunchOptions): Promise<OwnedBrowser> {
+  if (options.port !== undefined) assertPortUnbound(options.port);
   const executablePath = resolveBrowserExecutable(options.headless);
   const token = crypto.randomBytes(8).toString('hex');
   const profileDir = ensurePrivateDir(profilePath(token));
   const args = [
     `--remote-debugging-port=${options.port ?? 0}`,
+    `--remote-debugging-address=${CDP_LOOPBACK_HOST}`,
     `--user-data-dir=${profileDir}`,
     '--no-first-run',
     '--no-default-browser-check',

package/src/cdp/commands/lighthouse.ts

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module';
 import { detectCdpPort } from '../detect.js';
 import { captureError } from '../../errors.js';
 import { type ParsedArgs } from '../types.js';
+import { CDP_LOOPBACK_HOST } from '../loopback.js';
 import { selectRecords } from '../../output/selection.js';
 import { CAPTURE_ROOT, ensurePrivateDir, processPidBirthProvider, registerArtifactRoot, writeJsonPrivate, writePrivateFile } from '../../session/artifacts.js';
 import { getActiveSession } from '../../session-context.js';
@@ -191,7 +192,7 @@ async function releaseTracing(reservation: TracingReservation): Promise<void> {
 async function pageForSessionTarget(port: number, targetId: string): Promise<{ browser: PuppeteerBrowser; page: LighthousePage }> {
   const lighthouseRequire = createRequire(require.resolve('lighthouse'));
   const puppeteer = lighthouseRequire('puppeteer-core') as PuppeteerModule;
-  const browser = await puppeteer.connect({ browserURL: `http://localhost:${port}`, defaultViewport: null });
+  const browser = await puppeteer.connect({ browserURL: `http://${CDP_LOOPBACK_HOST}:${port}`, defaultViewport: null });
   try {
     for (const page of await browser.pages()) {
       const session = await page.target().createCDPSession();

package/src/cdp/commands/measure/index.ts

@@ -29,7 +29,7 @@ use when a claim depends on what is rendered right now: element geometry, overfl
 </command>`;
 
 export const MEASURE_USAGE = `<command name="measure" description="enriched snapshot substrate and read-only queries">
-<model>\`snap\` drives the page (or a base snapshot) and writes one settled artifact directory; every other leaf below reads that artifact and never re-drives the browser unless its target is a URL, which first creates a snapshot. Findings exit 0 — a report, not a failure. \`--gate\` (exit 2 on findings or changes) is accepted only by check and diff.</model>
+<model>\`snap\` drives the page (or a base snapshot) and writes one settled artifact directory; every other leaf below reads that artifact and never re-drives the browser unless its target is a URL, which first creates a snapshot. Findings exit 0 — a report, not a failure. \`--gate\` (exit 2 on findings or changes) is accepted only by check and diff. \`explain\` (and \`map paint\`) take the snapshot as \`<snap>\` positionally and name the element with a required \`--selector\`, unlike every other leaf's plain \`[url|snap]\` target.</model>
 <subcommand name="snap" description="settled snapshot artifact" whenToUse="Use to capture the static rendered-page substrate that measure queries read."/>
 <subcommand name="check" description="snapshot threshold measurements" whenToUse="Use to measure selected layout and content thresholds from one snapshot."/>
 <subcommand name="diff" description="snapshot delta" whenToUse="Use to compare the measured facts from two snapshots."/>
@@ -41,7 +41,7 @@ export const MEASURE_USAGE = `<command name="measure" description="enriched snap
 </command>`;
 
 export const MEASURE_MAP_USAGE = `<command name="map" description="one facet of a snapshot's substrate">
-<model>Focus, scroll, layers, and ax accept a URL target and create a snapshot first; paint requires an existing snapshot and reads it without browser driving.</model>
+<model>Focus, scroll, layers, and ax accept a URL target and create a snapshot first; paint requires an existing snapshot (\`<snap>\`, no URL) plus a required \`--selector\` naming the element, and reads it without browser driving.</model>
 <subcommand name="focus" description="keyboard traversal order" whenToUse="Use to inspect focus order from a snapshot."/>
 <subcommand name="scroll" description="scroll-container topology" whenToUse="Use to inspect scroll containers and their relationships."/>
 <subcommand name="layers" description="paint and compositor layers" whenToUse="Use to inspect layer allocation and paint order."/>

package/src/cdp/commands/measure/snap.ts

@@ -83,7 +83,7 @@ function artifactEntries(dir: string, artifacts: readonly string[], listCrops: b
     if (!listCrops && name.startsWith('crops/')) continue;
     entries.push({
       name,
-      ...(name === 'geometry.json' && geometryCount !== undefined ? { note: `${geometryCount} elements` } : {}),
+      ...(name === 'geometry.json' && geometryCount !== undefined ? { note: `${geometryCount} elements at .elements[]` } : {}),
     });
   }
   if (!listCrops && crops.length) entries.push({ name: 'crops/', note: `${crops.length} crops; pass --list-crops for paths` });

package/src/cdp/commands/tab/launch.ts

@@ -9,7 +9,7 @@
  * Ownership, registry, and reaping all live in `../../browser-process.ts`; this
  * leaf is the surface over them.
  */
-import { launchOwnedBrowser, sweepOwnedBrowsers, IDLE_REAP_MS } from '../../browser-process.js';
+import { assertPortUnbound, launchOwnedBrowser, sweepOwnedBrowsers, IDLE_REAP_MS } from '../../browser-process.js';
 import { type ParsedArgs } from '../../types.js';
 import { data, emitResult, fact, line, lineList, text, type RenderableResult } from '../../../output/render.js';
 
@@ -54,6 +54,9 @@ export async function cmdTabLaunch(parsed: ParsedArgs, _args: string[]): Promise
     return;
   }
 
+  // An explicit port must be checked before a sweep can reap an owned listener
+  // on it: this invocation must reject ambiguity, never create it by replacement.
+  if (parsed.port !== undefined) assertPortUnbound(parsed.port);
   const swept = await sweepOwnedBrowsers();
   const browser = await launchOwnedBrowser({
     url: parsed.url,

package/src/cdp/detect.ts

@@ -1,5 +1,6 @@
 import { execSync } from 'child_process';
 import * as http from 'http';
+import { CDP_LOOPBACK_HOST } from './loopback.js';
 
 /**
  * A CDP-endpoint JSON probe that CANNOT leak a socket handle. Node's built-in
@@ -21,7 +22,7 @@ function httpGetJson(
 ): Promise<unknown | null> {
   return new Promise((resolve) => {
     const req = http.get(
-      { host: 'localhost', port, path, timeout: timeoutMs },
+      { host: CDP_LOOPBACK_HOST, port, path, timeout: timeoutMs },
       (res) => {
         const status = res.statusCode ?? 0;
         if (status < 200 || status >= 300) {

package/src/cdp/loopback.ts

@@ -0,0 +1,4 @@
+/** Capture addresses CDP endpoints on one literal loopback address, never the
+ * hostname `localhost`: the hostname can resolve to either address family,
+ * which makes two listeners sharing a port an ambiguous endpoint. */
+export const CDP_LOOPBACK_HOST = '127.0.0.1';

package/src/cdp/targets.ts

@@ -1,4 +1,5 @@
 import { CDPClient } from './client.js';
+import { CDP_LOOPBACK_HOST } from './loopback.js';
 import { detectCdpPortsAsync } from './detect.js';
 import { touchOwnedBrowser } from './browser-process.js';
 import { type CDPTarget } from './types.js';
@@ -13,7 +14,7 @@ import { type CDPTarget } from './types.js';
 export async function getBrowserClient(
   port: number,
 ): Promise<{ client: CDPClient; browserWsUrl: string }> {
-  const versionResp = await fetch(`http://localhost:${port}/json/version`);
+  const versionResp = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`);
   if (!versionResp.ok) {
     throw new Error(
       `Failed to connect to CDP on port ${port}: ${versionResp.status}`,
@@ -29,13 +30,15 @@ export async function getBrowserClient(
         `Run "capture tab list" to find a real browser endpoint, or pass --port explicitly.`,
     );
   }
-  const client = new CDPClient(version.webSocketDebuggerUrl);
+  const browserWsUrl = new URL(version.webSocketDebuggerUrl);
+  browserWsUrl.hostname = CDP_LOOPBACK_HOST;
+  const client = new CDPClient(browserWsUrl.toString());
   await client.waitReady();
   // Every browser-level connection funnels through here, which makes this the
   // one place that can tell capture's idle sweep the browser is still in use.
   // A port capture did not launch has no registry record and this is a no-op.
   touchOwnedBrowser(port);
-  return { client, browserWsUrl: version.webSocketDebuggerUrl };
+  return { client, browserWsUrl: browserWsUrl.toString() };
 }
 
 export async function listTargets(port: number): Promise<CDPTarget[]> {
@@ -59,7 +62,7 @@ export async function listTargets(port: number): Promise<CDPTarget[]> {
       title: t.title,
       url: t.url,
       type: t.type,
-      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${t.targetId}`,
+      webSocketDebuggerUrl: `ws://${CDP_LOOPBACK_HOST}:${port}/devtools/page/${t.targetId}`,
     }));
   } finally {
     client.close();
@@ -152,7 +155,9 @@ function normalizeUrlForMatch(value: string): { full: string; host: string; path
     const path = url.pathname.replace(/\/+$/, '') || '/';
     return {
       full: `${url.origin}${path}${url.search}${url.hash}`.toLowerCase(),
-      host: url.hostname.toLowerCase(),
+      // `host` (not `hostname`): two local dev servers on the same loopback
+      // address but different ports must not register as a host match.
+      host: url.host.toLowerCase(),
       path: path.toLowerCase(),
     };
   } catch {
@@ -200,6 +205,28 @@ export async function findTabByIdAcrossEndpoints(
   return findTabByIdInPorts(targetId, ports);
 }
 
+export async function findResponsivePageTabByUrl(port: number, url: string): Promise<CDPTarget | null> {
+  const pages = (await listTargets(port)).filter((target) => target.type === 'page');
+  const scores = pages.map((target) => scoreTabUrlMatch(target.url, url));
+  const bestScore = Math.max(0, ...scores);
+  if (bestScore === 0) return null;
+
+  for (const target of pages.filter((_, index) => scores[index] === bestScore)) {
+    if (!target.webSocketDebuggerUrl) continue;
+    const client = new CDPClient(target.webSocketDebuggerUrl);
+    try {
+      await client.waitReady();
+      await client.send('Page.captureScreenshot', { format: 'png' }, 5_000);
+      return target;
+    } catch {
+      // Electron can expose a page target that never answers screenshot requests.
+    } finally {
+      client.close();
+    }
+  }
+  return null;
+}
+
 export async function findTabByUrlAcrossEndpoints(
   url: string,
   preferredPort?: number,
@@ -276,7 +303,7 @@ export async function openTab(port: number, url: string): Promise<CDPTarget> {
       title: '',
       url,
       type: 'page',
-      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${targetId}`,
+      webSocketDebuggerUrl: `ws://${CDP_LOOPBACK_HOST}:${port}/devtools/page/${targetId}`,
     };
   } finally {
     client.close();

package/src/session/commands.ts

@@ -391,10 +391,10 @@ const START_USAGE = `capture session start [--url <url> | --target <tab-id>] [--
 
 input:
   --url <url>       Absolute URL to open in a fresh tab through CDP's
-                    Target.createTarget. Some endpoints, including Electron,
-                    expose existing tabs but reject Target.createTarget; on
-                    those endpoints --url cannot be used. Conflicts with
-                    --target.
+                    Target.createTarget. If an endpoint, including Electron,
+                    rejects Target.createTarget, capture adopts the matching
+                    existing page target that answers a screenshot. Conflicts
+                    with --target.
   --target <tab-id>  Existing page tab to adopt. Resolves a full target id or
                     an unambiguous prefix of at least four characters at the
                     selected CDP endpoint; start fails if it does not resolve.
@@ -563,6 +563,7 @@ export interface SessionStartWorld {
   detectCdpPort(): Promise<number | { port: number; app: string; selectionReason: string }>;
   openTab(port: number, url: string): Promise<CDPTarget>;
   findTabById(port: number, targetId: string): Promise<CDPTarget | null>;
+  findResponsivePageTabByUrl?(port: number, url: string): Promise<CDPTarget | null>;
   closeTarget(port: number, targetId: string): Promise<void>;
   /** Attach to the freshly-opened tab and wait for load; returns page-load-timed-out. */
   awaitTabReady(target: CDPTarget, url: string): Promise<boolean>;
@@ -588,6 +589,10 @@ const productionStartWorld: SessionStartWorld = {
     const { findTabById } = await import('../cdp/targets.js');
     return findTabById(port, targetId);
   },
+  async findResponsivePageTabByUrl(port, url) {
+    const { findResponsivePageTabByUrl } = await import('../cdp/targets.js');
+    return findResponsivePageTabByUrl(port, url);
+  },
   async closeTarget(port, targetId) {
     const { closeTarget } = await import('../cdp/targets.js');
     return closeTarget(port, targetId);
@@ -692,6 +697,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     let bridgeSocket: string | null = null;
     let bridgePid: number | null = null;
     let cdpPort: number | null = null;
+    let targetWasOpened = false;
     let selectedBrowser: string | null = null;
     let endpointSelectionReason: string | null = null;
 
@@ -723,22 +729,28 @@ async function start(parsed: ParsedArgs): Promise<void> {
       }
 
       if (url) {
+        let opened = false;
         try {
           target = await startWorld.openTab(cdpPort!, url);
+          opened = true;
+          targetWasOpened = true;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          if (message.toLowerCase().includes('not supported')) {
+          if (!message.toLowerCase().includes('not supported')) throw error;
+          target = await startWorld.findResponsivePageTabByUrl?.(cdpPort!, url) ?? null;
+          if (!target) {
             throw worldFailure(
-              `Target.createTarget is unsupported on port ${cdpPort}. Use an existing tab: \`capture tab list --port ${cdpPort}\`, then \`capture session start --target <target-id> --port ${cdpPort}\`.`,
+              `Target.createTarget is unsupported on port ${cdpPort}, and no matching existing page target answered a screenshot. Run \`capture tab list --port ${cdpPort}\` to inspect its targets.`,
               error,
             );
           }
-          throw error;
         }
-        const openedPort = cdpPort!;
-        const openedTargetId = target.id;
-        acquired.push({ label: 'opened target', release: () => startWorld.closeTarget(openedPort, openedTargetId) });
-        pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        if (opened) {
+          const openedPort = cdpPort!;
+          const openedTargetId = target.id;
+          acquired.push({ label: 'opened target', release: () => startWorld.closeTarget(openedPort, openedTargetId) });
+          pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        }
       }
 
       // Hold a CDP browser connection open for the session's lifetime so
@@ -778,7 +790,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     }
 
     const rows: FactLine[] = [fact`bundle dir: ${dir}`];
-    if (target) rows.push(url ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
+    if (target) rows.push(targetWasOpened ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
     if (cdpPort !== null) rows.push(
       parsed.portSource === 'env'
         ? fact`CDP endpoint on port ${cdpPort} selected from ambient CDP_PORT; --port overrides endpoint selection and --target overrides tab selection.`
@@ -1103,6 +1115,7 @@ function responseEndDateTime(
 }
 
 function completedTiming(e: HAREntry): FactLine {
+  if ('_resourceType' in e) return fact`WebSocket: ${e._webSocketMessages.length} frame(s) recorded`;
   const { clocks, terminal } = e._capture;
   if (terminal.kind === 'failed') {
     return fact`duration ${e.time} ms — response incomplete: failed`;