@crouton-kit/capture 1.4.13 → 1.4.15

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;
@@ -5899,7 +5923,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 +5935,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 +5952,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 +6011,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 {
@@ -6071,7 +6099,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 +6109,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 +10541,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.13";
+  const version = "1.4.15";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12614,7 +12643,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.13";
+  const version = "1.4.15";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -15409,6 +15438,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`;
@@ -16091,7 +16121,7 @@ var init_commands = __esm({
     };
     SESSION_TAB_ATTACH_TIMEOUT_MS = 5e3;
     COMMAND_BLOCK = `<command name="session">
-the artifact container \u2014 a session records HAR and bundles every artifact; it may open or adopt a tab, and once it has one, every command auto-targets it
+the work's evidence bundle \u2014 \`start\` opens or adopts a tab, records its network traffic (HAR) and external logs, and collects every artifact into one directory; while running, every command auto-targets its tab
 use when collecting or reading the traffic, logs, and artifacts of scoped work against one page
 </command>`;
     START_USAGE = `capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>] [--artifact-dir <path>] \u2014 open or adopt a tab, record HAR, and set the active capture context.
@@ -229755,6 +229785,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,
@@ -230686,7 +230717,7 @@ var init_tab = __esm({
     init_network();
     init_mock();
     COMMAND_BLOCK3 = `<command name="tab">
-browser and tab plumbing \u2014 the existence of a browser capture owns, endpoint/tab discovery, tab lifecycle, and the conditions the tab's network runs under (connectivity, mocked responses)
+browser and tab plumbing \u2014 launch or quit a browser capture owns, discover endpoints and tabs, open/close/reset tabs, and set the tab's network conditions (throttling, offline, mocked responses)
 use when starting, finding, opening, closing, or resetting a browser tab, or changing its network conditions
 </command>`;
     TAB_USAGE = `<command name="tab" description="browser and tab lifecycle">
@@ -239412,7 +239443,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` });
@@ -243961,11 +243992,11 @@ var init_measure = __esm({
     init_map_ax2();
     init_map_paint();
     COMMAND_BLOCK6 = `<command name="measure">
-the settled-snapshot substrate \u2014 static facts at one moment; \`snap\` writes the substrate, every other leaf is a read-only query over it
-use for static rendered-page facts from a settled snapshot: layout, content, cascade provenance, targetability, and snapshot diffs
+static page measurement \u2014 \`snap\` waits for the page to settle, then records its layout, styles, text, and accessibility into one artifact; every other leaf answers questions from that artifact without re-driving the browser
+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 +244007,7 @@ use for static rendered-page facts from a settled snapshot: layout, content, cas
 <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."/>
@@ -245996,8 +246027,8 @@ var init_motion2 = __esm({
     init_jank2();
     init_response2();
     COMMAND_BLOCK7 = `<command name="motion">
-the screencast-recording substrate \u2014 what changed on screen across frames; \`rec\` writes the recording, every other leaf is a read-only query over it
-use for per-element frame geometry, changed regions, and input-to-settle timing; use \`perf\` instead for trace-event timing
+screen recording \u2014 \`rec\` screencasts the tab through an interaction; every other leaf answers what moved, where, and how long it took from that recording's frames
+use when a claim depends on change over time: element motion across frames, which screen regions changed, layout shifts and long tasks, or the time from an input to a settled screen; for trace-event timing use \`perf\` instead
 </command>`;
     MOTION_USAGE = `<command name="motion" description="recording lifecycle and read-only queries over a finalized recording">
 <model>\`rec\` drives and records the browser, one-shot or composed across intervening commands; every other leaf below reads the finalized recording artifact. Findings exit 0 \u2014 a report, not a failure; input and precondition errors exit 1. No leaf accepts --gate.</model>
@@ -265772,8 +265803,8 @@ var init_perf = __esm({
     init_vitals();
     init_insights2();
     COMMAND_BLOCK8 = `<command name="perf">
-the Chrome performance-trace substrate \u2014 \`trace\` records one, \`vitals\` and \`insights\` are read-only queries over it
-use for Core Web Vitals and DevTools insights over a page load or one interaction, timed from trace events
+Chrome performance tracing \u2014 \`trace\` records a DevTools performance trace over a page load or an interaction; \`vitals\` and \`insights\` read it back without re-running anything
+use when a claim depends on runtime performance: LCP, INP, and CLS with attribution, or DevTools' computed insights such as render-blocking requests, forced reflow, and layout-shift culprits
 </command>`;
     HELP7 = `<command name="perf" description="the Chrome performance-trace substrate">
 <model>\`trace\` drives (and records) the browser, one-shot or composed across intervening commands; the other leaves are cheap reads over the finalized trace artifact. Findings exit 0 \u2014 a report, not a failure; input/precondition errors exit 1. No leaf accepts --gate.</model>
@@ -266726,8 +266757,8 @@ var init_heap2 = __esm({
     init_retainers();
     init_diff4();
     COMMAND_BLOCK9 = `<command name="heap">
-the tab's JavaScript heap \u2014 \`snapshot\` records the heap as a V8 snapshot, every other leaf is a read-only graph query over it
-use for JavaScript-heap retention: constructor totals, retained sizes, retaining paths, duplicate strings, and before/after comparison
+JavaScript memory \u2014 \`snapshot\` writes the tab's V8 heap snapshot; every other leaf queries that object graph without touching the browser
+use when a claim depends on memory: what the heap holds per constructor, which objects exist, what keeps one alive, duplicated strings, or what grew between two snapshots when hunting a leak
 </command>`;
     HELP13 = `<command name="heap" description="the V8 heap-snapshot substrate">
 <model>\`snapshot\` drives the browser; every other leaf is a read of the finalized snapshot artifact and never touches Chrome. Retained sizes are dominator-subtree sums of Chrome's own self_size. Findings exit 0; input/precondition errors exit 1. No leaf accepts --gate.</model>
@@ -266843,7 +266874,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 +267081,7 @@ var init_lighthouse = __esm({
     import_node_module = require("node:module");
     init_detect();
     init_errors();
+    init_loopback();
     init_selection();
     init_artifacts();
     init_session_context();
@@ -267060,7 +267092,7 @@ var init_lighthouse = __esm({
     init_lifecycle();
     init_render();
     COMMAND_BLOCK10 = `<command name="lighthouse">
-a third-party scored diagnostic report \u2014 capture runs Lighthouse against a URL and stores its report unmodified
+Google Lighthouse audits \u2014 capture runs Lighthouse against a URL and stores its scored report unmodified
 use for one Lighthouse report's audited accessibility, SEO, performance, or best-practices conditions, categories, scores, and audits
 </command>`;
     HELP14 = `capture lighthouse <url> [--categories <list>] [--preset mobile|desktop] [--limit <N>] [--out <path>] \u2014 run Lighthouse's third-party scored diagnostic sweep against a URL and store its report
@@ -267289,14 +267321,14 @@ function rootHelp() {
 
 ${ROOT_BLOCKS.join("\n\n")}
 
-Selecting a noun: session, page, and tab address the live browser context; measure, motion, perf, and heap each own a distinct recorded substrate; lighthouse, cdp, and lib are respectively third-party audit, raw protocol, and local-library surfaces. Use a substrate noun when its recorded artifact is the source of the facts you need.
+Selecting a noun: session, page, and tab address the live browser; measure, motion, perf, and heap each record once and then answer many questions from that recording \u2014 a settled snapshot, a screencast, a performance trace, a heap snapshot; lighthouse, cdp, and lib are third-party audit, raw protocol, and local-library surfaces. Record with the noun whose artifact holds the facts you need, then query it.
 
 I/O contract: flags and positionals on input; one rendered prose block on stdout. --json mirrors the same result as JSON, but the rendered block is the contract. stderr carries in-flight diagnostics only. --artifact-dir <path> selects the root for a session bundle (\`session start\`) or a sessionless artifact-producing leaf's one-shot bundle; leaf help states when it writes one. --out always names one caller-owned file, never a bundle directory.
 
 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.13";
+  const declared = "1.4.15";
   if (declared) {
     console.log(declared);
     return;

package/package.json

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

package/src/capture.ts

@@ -61,7 +61,7 @@ function rootHelp(): string {
 
 ${ROOT_BLOCKS.join('\n\n')}
 
-Selecting a noun: session, page, and tab address the live browser context; measure, motion, perf, and heap each own a distinct recorded substrate; lighthouse, cdp, and lib are respectively third-party audit, raw protocol, and local-library surfaces. Use a substrate noun when its recorded artifact is the source of the facts you need.
+Selecting a noun: session, page, and tab address the live browser; measure, motion, perf, and heap each record once and then answer many questions from that recording — a settled snapshot, a screencast, a performance trace, a heap snapshot; lighthouse, cdp, and lib are third-party audit, raw protocol, and local-library surfaces. Record with the noun whose artifact holds the facts you need, then query it.
 
 I/O contract: flags and positionals on input; one rendered prose block on stdout. --json mirrors the same result as JSON, but the rendered block is the contract. stderr carries in-flight diagnostics only. --artifact-dir <path> selects the root for a session bundle (\`session start\`) or a sessionless artifact-producing leaf's one-shot bundle; leaf help states when it writes one. --out always names one caller-owned file, never a bundle directory.
 

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/heap/index.ts

@@ -7,8 +7,8 @@ import { cmdHeapRetainers } from './retainers.js';
 import { cmdHeapDiff } from './diff.js';
 
 export const COMMAND_BLOCK = `<command name="heap">
-the tab's JavaScript heap — \`snapshot\` records the heap as a V8 snapshot, every other leaf is a read-only graph query over it
-use for JavaScript-heap retention: constructor totals, retained sizes, retaining paths, duplicate strings, and before/after comparison
+JavaScript memory — \`snapshot\` writes the tab's V8 heap snapshot; every other leaf queries that object graph without touching the browser
+use when a claim depends on memory: what the heap holds per constructor, which objects exist, what keeps one alive, duplicated strings, or what grew between two snapshots when hunting a leak
 </command>`;
 
 const HELP = `<command name="heap" description="the V8 heap-snapshot substrate">

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';
@@ -16,7 +17,7 @@ import { stopAndReapCollectorHostAtSessionStop } from '../host/lifecycle.js';
 import { capped, emitResult, fact, formatArtifactList, line, lineList, text, type FactLine, type JsonValue, type RenderableResult } from '../../output/render.js';
 
 export const COMMAND_BLOCK = `<command name="lighthouse">
-a third-party scored diagnostic report — capture runs Lighthouse against a URL and stores its report unmodified
+Google Lighthouse audits — capture runs Lighthouse against a URL and stores its scored report unmodified
 use for one Lighthouse report's audited accessibility, SEO, performance, or best-practices conditions, categories, scores, and audits
 </command>`;
 
@@ -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

@@ -24,12 +24,12 @@ import { cmdMeasureMapPaint } from './map-paint.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="measure">
-the settled-snapshot substrate — static facts at one moment; \`snap\` writes the substrate, every other leaf is a read-only query over it
-use for static rendered-page facts from a settled snapshot: layout, content, cascade provenance, targetability, and snapshot diffs
+static page measurement — \`snap\` waits for the page to settle, then records its layout, styles, text, and accessibility into one artifact; every other leaf answers questions from that artifact without re-driving the browser
+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>`;
 
 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/motion/index.ts

@@ -16,8 +16,8 @@ import { cmdMotionResponse } from './response.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="motion">
-the screencast-recording substrate — what changed on screen across frames; \`rec\` writes the recording, every other leaf is a read-only query over it
-use for per-element frame geometry, changed regions, and input-to-settle timing; use \`perf\` instead for trace-event timing
+screen recording — \`rec\` screencasts the tab through an interaction; every other leaf answers what moved, where, and how long it took from that recording's frames
+use when a claim depends on change over time: element motion across frames, which screen regions changed, layout shifts and long tasks, or the time from an input to a settled screen; for trace-event timing use \`perf\` instead
 </command>`;
 
 export const MOTION_USAGE = `<command name="motion" description="recording lifecycle and read-only queries over a finalized recording">

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

@@ -5,8 +5,8 @@ import { cmdPerfVitals } from './vitals.js';
 import { cmdPerfInsights } from './insights.js';
 
 export const COMMAND_BLOCK = `<command name="perf">
-the Chrome performance-trace substrate — \`trace\` records one, \`vitals\` and \`insights\` are read-only queries over it
-use for Core Web Vitals and DevTools insights over a page load or one interaction, timed from trace events
+Chrome performance tracing — \`trace\` records a DevTools performance trace over a page load or an interaction; \`vitals\` and \`insights\` read it back without re-running anything
+use when a claim depends on runtime performance: LCP, INP, and CLS with attribution, or DevTools' computed insights such as render-blocking requests, forced reflow, and layout-shift culprits
 </command>`;
 
 const HELP = `<command name="perf" description="the Chrome performance-trace substrate">

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

@@ -21,7 +21,7 @@ import { tabMockMain } from './mock/index.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="tab">
-browser and tab plumbing — the existence of a browser capture owns, endpoint/tab discovery, tab lifecycle, and the conditions the tab's network runs under (connectivity, mocked responses)
+browser and tab plumbing — launch or quit a browser capture owns, discover endpoints and tabs, open/close/reset tabs, and set the tab's network conditions (throttling, offline, mocked responses)
 use when starting, finding, opening, closing, or resetting a browser tab, or changing its network conditions
 </command>`;
 

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 {
@@ -276,7 +281,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

@@ -383,7 +383,7 @@ export async function waitForPageLoad(
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="session">
-the artifact container — a session records HAR and bundles every artifact; it may open or adopt a tab, and once it has one, every command auto-targets it
+the work's evidence bundle — \`start\` opens or adopts a tab, records its network traffic (HAR) and external logs, and collects every artifact into one directory; while running, every command auto-targets its tab
 use when collecting or reading the traffic, logs, and artifacts of scoped work against one page
 </command>`;
 
@@ -1103,6 +1103,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`;