@crouton-kit/capture 1.3.18 → 1.3.20

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

@@ -13,6 +13,7 @@ import {
   pickPreferredEndpoint,
 } from '../../detect.js';
 import { listTargets } from '../../targets.js';
+import { ownedBrowsersByPort, sweepOwnedBrowsers } from '../../browser-process.js';
 import { type ParsedArgs } from '../../types.js';
 import {
   data,
@@ -30,8 +31,8 @@ const USAGE = `capture tab list — discover CDP endpoints and list the page tab
 input:
   --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint
 
-output: <tabs endpoints=… tabs=…> — one section per reachable endpoint (port, app, page-tab count, preferred marker) listing each page tab's target id (first 8 chars, enough for --target), title, and url; an endpoint that failed the tab fetch is an endpoints-unreachable fact, never a silent omission.
-effects: read-only — probes local CDP endpoints over HTTP/WebSocket; no page-observable writes.`;
+output: <tabs endpoints=… tabs=…> — one section per reachable endpoint (port, app, page-tab count, preferred marker, and a capture-owned pid marker on any browser \`tab launch\` started) listing each page tab's target id (first 8 chars, enough for --target), title, and url; an endpoint that failed the tab fetch is an endpoints-unreachable fact, never a silent omission.
+effects: probes local CDP endpoints over HTTP/WebSocket; no page-observable writes. Also sweeps capture-launched browsers, stopping any that have exited, stopped answering CDP, or gone idle — browsers capture did not start are never signalled.`;
 
 export interface TabRow {
   id: string;
@@ -45,6 +46,9 @@ export interface EndpointTabs {
   app?: string;
   /** Marked on the endpoint auto-discovery would pick for port-less commands. */
   preferred: boolean;
+  /** The pid of the capture-launched browser serving this endpoint, when this
+   * is one capture owns — absent for every foreign/user-owned endpoint. */
+  ownedPid?: number;
   pages: TabRow[];
 }
 
@@ -76,6 +80,7 @@ export function buildTabsResult(
       ...(ep.app !== undefined ? [line(text` — `, data(ep.app, 80))] : []),
       fact` — ${ep.pages.length} page tab(s)`,
       ...(ep.preferred ? [text` [preferred]`] : []),
+      ...(ep.ownedPid !== undefined ? [line(fact` [capture-owned pid=${ep.ownedPid}]`)] : []),
     );
     const rows = ep.pages.map((t) =>
       line(text`  `, data(t.id.slice(0, 8)), text`  "`, data(t.title, 120), text`"  `, data(t.url, 300)),
@@ -121,6 +126,11 @@ export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<v
     return;
   }
 
+  // The probe agents run constantly is also where abandoned owned browsers
+  // die: sweeping here is what keeps a launch from outliving the agent that
+  // made it, without any daemon in the picture.
+  await sweepOwnedBrowsers();
+  const owned = ownedBrowsersByPort();
   const reachable: EndpointTabs[] = [];
   const unreachable: UnreachableEndpoint[] = [];
 
@@ -130,6 +140,7 @@ export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<v
       reachable.push({
         port: parsed.port,
         preferred: false,
+        ...(owned.has(parsed.port) ? { ownedPid: owned.get(parsed.port)!.pid } : {}),
         pages: targets
           .filter((t) => t.type === 'page')
           .map((t) => ({ id: t.id, title: t.title, url: t.url })),
@@ -149,6 +160,7 @@ export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<v
             port: ep.port,
             app: ep.app,
             preferred: ep.port === preferredPort,
+            ...(owned.has(ep.port) ? { ownedPid: owned.get(ep.port)!.pid } : {}),
             pages: targets
               .filter((t) => t.type === 'page')
               .map((t) => ({ id: t.id, title: t.title, url: t.url })),

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

@@ -0,0 +1,78 @@
+/**
+ * `capture tab quit [<port>] [--all]` — stop browsers capture started.
+ *
+ * Named `quit` rather than `close` deliberately: `capture tab close` closes one
+ * TAB inside a browser, this ends the browser process itself. It reaches only
+ * browsers in capture's own registry, verified by PID birth — a port capture
+ * never launched (the user's own browser, or one an agent started by hand)
+ * matches nothing here and is never signalled.
+ */
+import { quitOwnedBrowsers, sweepOwnedBrowsers, type ReapedBrowser } from '../../browser-process.js';
+import { invalidInput } from '../../../errors.js';
+import { type ParsedArgs } from '../../types.js';
+import { data, emitResult, fact, line, lineList, text, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `capture tab quit — stop a browser capture started.
+
+input:
+  <port>          the port of a capture-launched browser (as reported by tab launch / tab list)
+  --all           stop every browser capture launched
+
+output: <browser-quit stopped=…> — one line per stopped browser (port, pid) and the reason it ended.
+effects: SIGTERM (then SIGKILL if needed) to capture-launched browsers only, verified by process-birth identity, and removes their private profiles. A browser capture did not start is never signalled — a port with no capture record stops nothing.`;
+
+/** Pure `<browser-quit>` result builder — exported for tests. */
+export function buildBrowserQuitResult(stopped: readonly ReapedBrowser[], selector: string): RenderableResult {
+  return {
+    tag: 'browser-quit',
+    attrs: { stopped: stopped.length },
+    summary:
+      stopped.length === 0
+        ? line(text`no capture-launched browser matched `, data(selector), text`; nothing was signalled.`)
+        : fact`stopped ${stopped.length} capture-launched browser(s).`,
+    sections:
+      stopped.length === 0
+        ? []
+        : [
+            lineList(
+              stopped.map((browser) =>
+                line(
+                  text`port `,
+                  data(browser.port ?? 'unstarted'),
+                  fact`  pid ${browser.pid}  `,
+                  data(browser.reason),
+                ),
+              ),
+            ),
+          ],
+  };
+}
+
+export async function cmdTabQuit(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const token = parsed.positional[0];
+  if (!parsed.all && token === undefined) {
+    throw invalidInput('received: no target; expected: capture tab quit <port> or capture tab quit --all.', 'missing_argument');
+  }
+  if (parsed.all && token !== undefined) {
+    throw invalidInput('received: both a port and --all; expected: one or the other.');
+  }
+  if (token !== undefined && !/^\d+$/.test(token)) {
+    throw invalidInput(`Invalid port: ${token}.`);
+  }
+  const port = token === undefined ? undefined : Number(token);
+
+  // The sweep runs first so a browser that already exited is reported as
+  // reaped rather than as "no match" for the port the caller remembered.
+  const swept = await sweepOwnedBrowsers();
+  const stopped = await quitOwnedBrowsers({ port, all: parsed.all });
+  const matchedSweep = swept.filter((browser) => parsed.all || browser.port === port);
+
+  emitResult(buildBrowserQuitResult([...stopped, ...matchedSweep], parsed.all ? '--all' : String(port)), {
+    json: parsed.json,
+  });
+}

package/src/cdp/har-recorder.ts

@@ -164,8 +164,6 @@ export class HARRecorder {
   private readonly recordedKeys = new Set<string>();
   /** Snapshot mode only — streaming mode retains no materialized values. */
   private readonly materializedByKey = new Map<string, Materialized>();
-  /** Last terminal remains comparable until this CDP id opens its next generation. */
-  private readonly closedTerminals = new Map<string, Terminal>();
   /** Sockets opened while this recorder is attached — CDP does not replay creation events for pre-existing sockets. */
   private readonly webSockets = new Map<string, WebSocketConnection>();
   private readonly bodyTasks = new Set<Promise<void>>();
@@ -245,11 +243,13 @@ export class HARRecorder {
     const hasRedirect = 'redirectResponse' in params && params.redirectResponse !== undefined;
     if (previous && !hasRedirect) fail('duplicate active requestId without redirectResponse');
     if (hasRedirect && previous) {
-      const redirect = this.parseResponse(params.redirectResponse, 'redirectResponse');
-      if (redirect.status < 300 || redirect.status > 399) fail('redirectResponse.status');
+      // CDP uses status 0 when a redirect response is observable but never
+      // reached HTTP (for example, an extension redirect during navigation).
+      // Preserve that factual response rather than aborting the whole session.
+      const redirect = this.parseResponse(params.redirectResponse, 'redirectResponse', true);
+      if (redirect.status !== 0 && (redirect.status < 300 || redirect.status > 399)) fail('redirectResponse.status');
       this.assignTerminal(previous, { kind: 'redirect', timestamp: monotonic }, redirect);
     }
-    this.closedTerminals.delete(requestId);
     const generation = this.nextGenerationByRequestId.get(requestId) ?? 1;
     this.nextGenerationByRequestId.set(requestId, generation + 1);
     this.activeByRequestId.set(requestId, {
@@ -338,11 +338,11 @@ export class HARRecorder {
     });
   }
 
-  private parseResponse(value: unknown, name: string): RedirectResponse {
+  private parseResponse(value: unknown, name: string, allowNoHttpStatus = false): RedirectResponse {
     if (!isPlainObject(value)) fail(name);
     nonempty(value.url, `${name}.url`);
     const status = finite(value.status, `${name}.status`);
-    if (!Number.isInteger(status) || status < 100 || status > 599) fail(`${name}.status`);
+    if (!Number.isInteger(status) || status < 0 || status > 599 || (status < 100 && !(allowNoHttpStatus && status === 0))) fail(`${name}.status`);
     return { status, headers: headers(value.headers, `${name}.headers`) };
   }
 
@@ -366,11 +366,13 @@ export class HARRecorder {
     const requestId = this.eventRequestId(params);
     if (!requestId) return;
     const current = this.activeByRequestId.get(requestId);
-    const closed = this.closedTerminals.has(requestId);
-    if (!current && !closed) return;
+    // Chromium can follow a loadingFailed with loadingFinished for the same
+    // request (for example, a blocked iframe during navigation). Once the
+    // first terminal materializes its generation, a later terminal cannot be
+    // assigned safely, so the first factual terminal remains authoritative.
+    if (!current) return;
     const event = params as Record<string, unknown>;
     const terminal: Terminal = { kind: 'finished', timestamp: finite(event.timestamp, 'timestamp'), encodedDataLength: finite(event.encodedDataLength, 'encodedDataLength') };
-    if (!current) return this.compareClosedTerminal(requestId, terminal);
     if (!current.response) fail('loadingFinished without responseReceived');
     this.assignTerminal(current, terminal);
   }
@@ -379,8 +381,7 @@ export class HARRecorder {
     const requestId = this.eventRequestId(params);
     if (!requestId) return;
     const current = this.activeByRequestId.get(requestId);
-    const closed = this.closedTerminals.has(requestId);
-    if (!current && !closed) return;
+    if (!current) return;
     const event = params as Record<string, unknown>;
     const terminal: Terminal = {
       kind: 'failed',
@@ -390,22 +391,15 @@ export class HARRecorder {
       blockedReason: event.blockedReason === undefined ? null : typeof event.blockedReason === 'string' ? event.blockedReason : fail('blockedReason'),
       resourceType: event.type === undefined ? null : typeof event.type === 'string' ? event.type : fail('type'),
     };
-    if (!current) return this.compareClosedTerminal(requestId, terminal);
     this.assignTerminal(current, terminal);
   }
 
-  private compareClosedTerminal(requestId: string, terminal: Terminal): void {
-    const previous = this.closedTerminals.get(requestId);
-    if (previous && !same(previous, terminal)) fail('conflicting terminal event');
-  }
-
   private assignTerminal(current: Generation, terminal: Terminal, redirectResponse?: RedirectResponse): void {
     if (current.terminal) {
-      if (!same(current.terminal, terminal)) fail('conflicting terminal event');
+      if (!same(current.terminal, terminal)) fail(`conflicting terminal event for requestId ${current.requestId} generation ${current.generation}`);
       return;
     }
     current.terminal = terminal;
-    this.closedTerminals.set(current.requestId, terminal);
     if (redirectResponse) {
       current.redirectResponse = redirectResponse;
       this.materialize(current, { state: 'not_applicable', reason: 'redirect' });

package/src/cdp/measure/collectors/ax.ts

@@ -7,10 +7,9 @@
  * shared with `styles.json`/`media.json` per the U04 contract — no
  * coordination with those files is needed.
  *
- * "geometry ids ... when possible": U07's `geometry.json` is a
- * concurrently-written sibling collector (`Promise.all` in `snapshot.ts`,
- * no cross-collector read ordering) that this file must not depend on or
- * read at capture time. Read here as "attach a `rect` fact directly per AX
+ * "geometry ids ... when possible": `geometry.json` is a separate
+ * collector artifact that this file does not depend on or read at capture
+ * time. Read here as "attach a `rect` fact directly per AX
  * node via a best-effort `DOM.getBoxModel` lookup" rather than a join
  * against `geometry.json` — a deliberate, bounded reading documented in
  * the U08 build-plan report, not a defect.

package/src/cdp/measure/collectors/forms.ts

@@ -41,9 +41,8 @@
  * turns into a `backendNodeId`. A page can predefine a setter for any
  * global name it can guess; it can observe nothing here, because nothing
  * is ever set on it. No DOM mutation and no page-observable global either,
- * so nothing in the emitted `screenshot.png`/`dom.html`/any other baseline
- * collector running concurrently in the same `Promise.all` can ever
- * observe this collector having run.
+ * so nothing in the emitted `screenshot.png`/`dom.html` can observe this
+ * collector having run.
  */
 
 import type { CDPClient } from '../../client.js';
@@ -628,9 +627,8 @@ async function resolveIndexedObjectIds(
 export const collectForms: Collector = async (ctx) => {
   // The walk's return value is a plain in-memory `{ facts, elements }`
   // object — never a `window` global, never a live-DOM attribute — so
-  // nothing another baseline collector or the `screenshot.png`/`dom.html`
-  // capture running concurrently in the same `Promise.all` (see
-  // `snapshot.ts`) could ever observe. `Runtime.evaluate({returnByValue:
+  // nothing another baseline artifact capture could ever observe.
+  // `Runtime.evaluate({returnByValue:
   // false})` hands that object back as a CDP `RemoteObject` (an `objectId`
   // with zero page visibility into it); every held `objectId` (the
   // container, `facts`, `elements`) is released via `Runtime.releaseObject`

package/src/cdp/measure/collectors/media.ts

@@ -4,8 +4,7 @@
  * state, and (for `object-fit`-bearing elements) computed crop/letterbox
  * facts. One `Runtime.evaluate` gathers raw per-element facts in-page;
  * `backendNodeId` correlation reuses `resolveNodeIds` from `./styles.js`
- * (this file issues its own `DOM.getDocument` call — collectors run
- * concurrently, so no CDP call is shared across files).
+ * while issuing its own `DOM.getDocument` call.
  *
  * This is a `phase: 'baseline'` collector, so it must not create or pin
  * any page-observable state: `canvas.getContext(...)` is deliberately NOT

package/src/cdp/measure/collectors/states.ts

@@ -5,12 +5,7 @@
  * Written ONLY when at least one `--state` was requested (`ctx.state.length
  * > 0`); otherwise this is a no-op (no file written). Owned by U12.
  *
- * Independent of the other 13 collectors (they all fan out via
- * `Promise.all` in `snapshot.ts` — there is no cross-collector read
- * ordering, and `geometry.json`/`styles.json`/`hittest.json` may not exist
- * yet when this runs), so this collector drives its own minimal
- * geometry/style/hittest re-capture per forced element rather than reading
- * those files. Scope: top-frame light DOM only — elements inside an
+ * This collector drives its own minimal geometry/style/hittest re-capture per forced element rather than reading those files. Scope: top-frame light DOM only — elements inside an
  * iframe or a shadow root are out of reach of `DOM.querySelectorAll`'s
  * plain (non-piercing) subtree walk and are not visited here; frame/shadow
  * stitching is `geometry.json`'s concern, not this collector's.

package/src/cdp/measure/collectors/style-provenance.ts

@@ -29,22 +29,10 @@
  * re-invoking `CSS.enable` while the domain is ALREADY enabled is a
  * no-op that redelivers nothing — only a `CSS.disable` + `CSS.enable`
  * pair forces Chrome to resend every currently-known stylesheet's
- * header). Both `styles.ts` and `layers.ts` run in the same `baseline`
- * `Promise.all` (see `snapshot.ts`), and `enableDomainsForSnap` already
- * enabled CSS once before either collector starts — so a caller-owned
- * listener registered only after that point would otherwise never see
- * the headers for stylesheets already parsed at that time. Each caller
- * runs `captureStyleSheetHeaders` independently, as the very first thing
- * it does (before any other CSS-domain call), and awaits it before
- * issuing any of its own `CSS.*` calls. Because listener registration is
- * synchronous (before any `await`), and JS never yields to socket I/O
- * mid-way through `Promise.all`'s synchronous dispatch of every baseline
- * collector, both this file's and the other collector's listeners are
- * always attached before either's disable/enable pair reaches Chrome —
- * so neither can miss the other's redelivery burst, and once both
- * callers' own `captureStyleSheetHeaders` calls resolve, the CSS domain
- * is stably enabled for the rest of the snapshot (neither file disables
- * it again).
+ * header). `enableDomainsForSnap` already enabled CSS before either
+ * collector starts, so each collector captures its own headers as its
+ * first CSS-domain action and awaits that capture before its provenance
+ * reads. This keeps either artifact self-contained.
  */
 
 import { resolveAuthoredSourceLocation, type ResolvedSourceLocation } from '../../source-map.js';

package/src/cdp/measure/collectors/styles.ts

@@ -14,9 +14,8 @@
  * file's `CSS.getMatchedStylesForNode` calls (which need a CDP `nodeId`,
  * not just a `backendNodeId`) and reused by `media.ts` for its own
  * per-element `backendNodeId` correlation. Both `styles.ts` and `media.ts`
- * independently issue their own `Runtime.evaluate`/`DOM.getDocument`
- * calls — they run concurrently in `snapshot.ts`'s `Promise.all`, so there
- * is no cross-collector call sharing beyond this shared, stateless logic.
+ * independently issue their own `Runtime.evaluate`/`DOM.getDocument` calls,
+ * so there is no cross-collector call sharing beyond this shared, stateless logic.
  */
 
 import type { ResolvedSourceLocation } from '../../source-map.js';
@@ -35,6 +34,7 @@ export { computeSpecificity, resolveNodeIds };
 export type { Specificity, CSSRange, WinningDeclaration } from './style-provenance.js';
 
 const STYLES_MAX_ELEMENTS = 150;
+const PROVENANCE_CONCURRENCY = 8;
 
 /** Full computed-style snapshot tracked per element — broad, cheap (no CDP round trip; read via `getComputedStyle` in one `Runtime.evaluate`). */
 const COMPUTED_PROPERTIES = [
@@ -205,6 +205,20 @@ function resolvedIdentity(backendNodeId: number | undefined): { backendNodeId: n
   return backendNodeId === undefined ? { backendNodeId: null, identityUnresolved: true } : { backendNodeId };
 }
 
+/** Limits expensive per-element CDP provenance reads without changing document order. */
+async function mapWithConcurrency<T, R>(values: readonly T[], limit: number, fn: (value: T, index: number) => Promise<R>): Promise<R[]> {
+  const result = new Array<R>(values.length);
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < values.length) {
+      const index = next++;
+      result[index] = await fn(values[index]!, index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, values.length) }, worker));
+  return result;
+}
+
 // ============================================================================
 // Collector
 // ============================================================================
@@ -213,9 +227,8 @@ export const collectStyles: Collector = async (ctx) => {
   const { client } = ctx;
 
   // Registers the CSS.styleSheetAdded listener and forces header redelivery
-  // BEFORE anything else touches the CSS domain — see style-provenance.ts's
-  // module doc for why this must run first and why it's safe alongside the
-  // concurrently-running `layers` collector's own copy of the same step.
+  // BEFORE this collector uses the CSS domain — see style-provenance.ts's
+  // module doc for why header capture must begin before provenance reads.
   const {
     urls: styleSheetUrls,
     stop: stopTrackingStyleSheets,
@@ -292,8 +305,7 @@ async function collectStylesInner(
 
   const sourceCache = new Map<string, Promise<ResolvedSourceLocation>>();
 
-  const elements: StylesElementRecord[] = await Promise.all(
-    facts.map(async (fact, index) => {
+  const elements = await mapWithConcurrency(facts, PROVENANCE_CONCURRENCY, async (fact, index): Promise<StylesElementRecord> => {
       const ref = resolved[index];
       const computed = normalizeComputed(fact.computed);
 
@@ -334,8 +346,7 @@ async function collectStylesInner(
         winningDeclarations,
         provenanceUnavailable,
       };
-    }),
-  );
+    });
 
   ctx.write.json('styles.json', {
     elements,

package/src/cdp/measure/collectors/text.ts

@@ -27,8 +27,7 @@
  * identifier `CSS.getPlatformFontsForNode` accepts — and `backendNodeId`.
  * No `setAttribute`/`removeAttribute` pair and no page-observable global
  * either, so nothing in the emitted `screenshot.png`/`dom.html`/any other
- * baseline collector running concurrently in the same `Promise.all` (see
- * `snapshot.ts`) can ever observe this collector having run.
+ * baseline artifact capture can ever observe this collector having run.
  */
 
 import type { CDPClient } from '../../client.js';
@@ -421,9 +420,8 @@ async function resolveIndexedObjectIds(
 export const collectText: Collector = async (ctx) => {
   // The walk's return value is a plain in-memory `{ facts, elements }`
   // object — never a `window` global, never a live-DOM attribute — so
-  // nothing another baseline collector or the `screenshot.png`/`dom.html`
-  // capture running concurrently in the same `Promise.all` (see
-  // `snapshot.ts`) could ever observe. `Runtime.evaluate({returnByValue:
+  // nothing another baseline artifact capture could ever observe.
+  // `Runtime.evaluate({returnByValue:
   // false})` hands that object back as a CDP `RemoteObject` (an `objectId`
   // with zero page visibility into it); every held `objectId` (the
   // container, `facts`, `elements`) is released via `Runtime.releaseObject`