@crouton-kit/capture 1.3.21 → 1.4.1

package/src/cdp/commands/page/shot.ts

@@ -19,11 +19,13 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
-import { captureScreenshotWithCssViewport, type CapturedRegion } from '../../screenshot.js';
+import { captureScreenshotWithCssViewport, type CapturedRegion, type ScreenshotCrop } from '../../screenshot.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
 import { parseColorScheme, withAppliedColorScheme, type ColorScheme } from '../../color-scheme.js';
 import { nextStepPath } from '../../../session-context.js';
 import { createOneshotSession } from '../../../session/commands.js';
+import { resolveLiveTarget, type LiveClient, type ResolutionFailure } from '../../../interact.js';
+import { emitResolutionError } from './click.js';
 import { assertUnderCaptureRoot, writeBinaryPrivate } from '../../../session/artifacts.js';
 import {
   emitResult,
@@ -39,13 +41,17 @@ input:
   --viewport <WxH>  transient device-metrics override for this capture; grammar: <positive-safe-int>x<positive-safe-int>, exact lowercase x with no whitespace — preset names are not accepted. Absent → no emulation, the browser's actual current viewport is captured
   --full-page       transient override to the full scrollable content height for this capture
   --color-scheme <dark|light>  transient prefers-color-scheme override for this capture; cleared afterward
+  --crop <x,y,w,h>  capture this page-coordinate CSS-pixel rect, intersected with the live visual viewport; x/y may be fractional, w/h must be positive
+  --crop-selector <sel>  resolve exactly one live target (bare CSS, ax:<name>, axid:<id>, or backend:<id>), scroll it into view, then crop its border box and surroundings
+  --pad <px>        nonnegative integer CSS pixels added on every side of --crop-selector (default: 0; not accepted with --crop)
+  --zoom <factor>   positive decimal CSS-to-image scale requested for a CSS crop; the 1600px image cap may produce a smaller reported scale
   --out <path>      destination file; default: the active session's shots/ sequence, or a fresh oneshot-*/page/ dir under the capture root when no session is active
   --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
   --json            mirror the result as JSON
 output:
-  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… emulation=none|viewport|full-page color-scheme=dark|light> — saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, byte size, and any requested transient emulation
+  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… emulation=none|viewport|full-page color-scheme=dark|light> — saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, byte size, crop provenance, and any requested transient emulation
 effects:
-  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture.`;
+  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture. --crop-selector scrolls its resolved target into view. CSS crops are intersected with the source visual viewport; an empty intersection fails without writing an image. --crop/--crop-selector cannot be combined with --full-page.`;
 
 // ---------------------------------------------------------------------------
 // Test-injectable dependency seam (the CDP-stub test pattern; the capture
@@ -119,6 +125,15 @@ function writeScreenshot(outPath: string, png: Buffer): void {
 
 export type EmulationMode = 'none' | 'viewport' | 'full-page';
 
+interface CropProvenance {
+  readonly source: 'coordinates' | 'selector';
+  readonly requested: ScreenshotCrop;
+  readonly selector?: string;
+  readonly backendNodeId?: number;
+  readonly pad?: number;
+  readonly zoom: number;
+}
+
 /** Renders a CSS-pixel measurement without inventing precision: an integer stays an integer, a fractional zoomed viewport keeps six decimals. */
 function round6(value: number): number {
   return Math.round(value * 1e6) / 1e6;
@@ -132,6 +147,7 @@ export function buildScreenshotResult(f: {
   emulation: EmulationMode;
   viewport?: { width: number; height: number };
   colorScheme?: ColorScheme;
+  crop?: CropProvenance;
 }): RenderableResult {
   // The denominator is the CSS region the image was actually cut from, so the
   // ratio stays true under page zoom, device pixel ratio, and the local
@@ -143,6 +159,9 @@ export function buildScreenshotResult(f: {
     scale && f.cssViewport
       ? fact`CSS-to-image scale: ${scale.x.toFixed(6)} image px/CSS px horizontally and ${scale.y.toFixed(6)} image px/CSS px vertically (captured CSS region ${round6(f.cssViewport.width)}×${round6(f.cssViewport.height)} at page origin ${round6(f.cssViewport.x)},${round6(f.cssViewport.y)}).`
       : text`CSS-to-image scale unavailable: the browser did not return the CSS region this capture covers.`,
+    f.crop
+      ? fact`CSS crop: ${f.crop.source === 'selector' ? `selector ${f.crop.selector} (backend:${f.crop.backendNodeId}), border box plus ${f.crop.pad}px padding` : 'coordinates'} requested ${formatRect(f.crop.requested)} at zoom ${f.crop.zoom}; the captured CSS region above is its intersection with the source visual viewport.`
+      : text`CSS crop: none — the captured CSS region above is the source visual viewport.`,
     f.emulation === 'none'
       ? text`viewport emulation: none — the browser's actual current viewport was captured.`
       : f.emulation === 'viewport'
@@ -168,6 +187,10 @@ export function buildScreenshotResult(f: {
       'css-to-image-y': scale?.y.toFixed(6),
       emulation: f.emulation,
       'color-scheme': f.colorScheme,
+      'crop-source': f.crop?.source,
+      'crop-selector': f.crop?.selector,
+      'crop-backend-node-id': f.crop?.backendNodeId,
+      'requested-zoom': f.crop?.zoom,
     },
     summary: f.dimensions
       ? fact`saved ${f.path} — ${f.dimensions.width}x${f.dimensions.height}px, ${f.bytes} bytes.`
@@ -176,6 +199,38 @@ export function buildScreenshotResult(f: {
   };
 }
 
+function formatRect(rect: ScreenshotCrop): string {
+  return `x=${round6(rect.x)} y=${round6(rect.y)} w=${round6(rect.width)} h=${round6(rect.height)}`;
+}
+
+function parseCrop(value: string): ScreenshotCrop | undefined {
+  const match = /^(-?(?:\d+\.?\d*|\.\d+)),(-?(?:\d+\.?\d*|\.\d+)),(\d+(?:\.\d*)?|\.\d+),(\d+(?:\.\d*)?|\.\d+)$/.exec(value);
+  if (!match) return undefined;
+  const [x, y, width, height] = match.slice(1).map(Number);
+  if (![x, y, width, height].every(Number.isFinite) || width <= 0 || height <= 0) return undefined;
+  return { x, y, width, height };
+}
+
+function parseZoom(value: string): number | undefined {
+  if (!/^(?:\d+\.?\d*|\.\d+)$/.test(value)) return undefined;
+  const zoom = Number(value);
+  return Number.isFinite(zoom) && zoom > 0 ? zoom : undefined;
+}
+
+function borderRect(model: unknown): ScreenshotCrop | undefined {
+  const border = (model as { border?: unknown } | undefined)?.border;
+  if (!Array.isArray(border) || border.length !== 8 || !border.every((point) => typeof point === 'number' && Number.isFinite(point))) return undefined;
+  const xs = [border[0], border[2], border[4], border[6]] as number[];
+  const ys = [border[1], border[3], border[5], border[7]] as number[];
+  const x = Math.min(...xs);
+  const y = Math.min(...ys);
+  return { x, y, width: Math.max(...xs) - x, height: Math.max(...ys) - y };
+}
+
+function padded(rect: ScreenshotCrop, pad: number): ScreenshotCrop {
+  return { x: rect.x - pad, y: rect.y - pad, width: rect.width + 2 * pad, height: rect.height + 2 * pad };
+}
+
 // ---------------------------------------------------------------------------
 // page shot
 // ---------------------------------------------------------------------------
@@ -191,7 +246,7 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
       {
         tag: 'error',
         attrs: { command: 'page shot', code: 'invalid_input' },
-        summary: fact`received: ${parsed.positional.length} positional arguments; expected none — \`capture page shot [--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--out <path>]\`.`,
+        summary: fact`received: ${parsed.positional.length} positional arguments; expected none — \`capture page shot [--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--crop <x,y,w,h> | --crop-selector <sel> [--pad <px>]] [--zoom <factor>] [--out <path>]\`.`,
       },
       { json: parsed.json },
     );
@@ -199,6 +254,44 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
     return;
   }
 
+  const crop = parsed.crop === undefined ? undefined : parseCrop(parsed.crop);
+  if (parsed.crop !== undefined && !crop) {
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'invalid_crop' }, summary: fact`received: --crop ${parsed.crop}; expected x,y,w,h as finite CSS pixels without whitespace, with positive w and h.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.crop !== undefined && parsed.cropSelector !== undefined) {
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'conflicting_crop' }, summary: text`--crop and --crop-selector cannot be combined; choose coordinates or one live target.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.cropSelector !== undefined && !parsed.cropSelector.trim()) {
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'invalid_crop_selector' }, summary: text`received an empty --crop-selector; expected a bare CSS selector, ax:<name>, axid:<id>, or backend:<id>.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.pad !== undefined && parsed.cropSelector === undefined) {
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'pad_requires_crop_selector' }, summary: text`--pad applies only to --crop-selector.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  const zoom = parsed.zoom === undefined ? 1 : parseZoom(parsed.zoom);
+  if (!zoom) {
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'invalid_zoom' }, summary: fact`received: --zoom ${parsed.zoom}; expected a positive decimal factor.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.zoom !== undefined && !crop && parsed.cropSelector === undefined) {
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'zoom_requires_crop' }, summary: text`--zoom requires --crop or --crop-selector.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.fullPage && (crop || parsed.cropSelector !== undefined)) {
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'crop_conflicts_with_full_page' }, summary: text`--crop and --crop-selector capture from the visual viewport and cannot be combined with --full-page.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
   let viewport: Viewport | undefined;
   if (parsed.viewport !== undefined) {
     try {
@@ -241,13 +334,32 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
   const result = await deps.withConnection(
     { ...parsed, command: 'shot' },
     async (client) => withAppliedColorScheme(client, colorScheme, async () => {
-      const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage });
+      let cropProvenance: CropProvenance | undefined;
+      let requestedCrop = crop;
+      if (parsed.cropSelector !== undefined) {
+        const resolved = await resolveLiveTarget(client as unknown as LiveClient, parsed.cropSelector);
+        if (!resolved.ok) return { failure: resolved } as const;
+        await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId: resolved.backendNodeId });
+        const box = (await client.send('DOM.getBoxModel', { backendNodeId: resolved.backendNodeId })) as { model?: unknown };
+        const rect = borderRect(box.model);
+        if (!rect) throw new Error(`Resolved target backend:${resolved.backendNodeId} has no measurable border box for --crop-selector.`);
+        const pad = parsed.pad ?? 0;
+        requestedCrop = padded(rect, pad);
+        cropProvenance = { source: 'selector', requested: requestedCrop, selector: parsed.cropSelector, backendNodeId: resolved.backendNodeId, pad, zoom };
+      } else if (requestedCrop) {
+        cropProvenance = { source: 'coordinates', requested: requestedCrop, zoom };
+      }
+      const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage, crop: requestedCrop, zoom });
       const outPath = await resolveOutPath(parsed);
       writeScreenshot(outPath, screenshot.png);
-      return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport };
+      return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport, crop: cropProvenance } as const;
     }),
     { settle: 0 },
   );
 
+  if ('failure' in result) {
+    emitResolutionError(parsed, 'page shot', result.failure as ResolutionFailure);
+    return;
+  }
   emitResult(buildScreenshotResult({ ...result, emulation, viewport, colorScheme }), { json: parsed.json });
 }

package/src/cdp/connection.ts

@@ -1,7 +1,8 @@
 import * as fs from 'fs';
 import { performance } from 'node:perf_hooks';
 import { CDPClient } from './client.js';
-import { findTabByIdAcrossEndpoints, findTabByUrlAcrossEndpoints } from './targets.js';
+import { detectCdpPortsAsync } from './detect.js';
+import { AmbiguousPageTargetError, findTabByIdAcrossEndpoints, findTabByUrlAcrossEndpoints, findUnambiguousPageTabInPorts } from './targets.js';
 import { type CDPTarget, type ParsedArgs } from './types.js';
 import { ConsoleRecorder, printConsoleSummary } from './console-recorder.js';
 import { HARRecorder } from './har-recorder.js';
@@ -13,7 +14,7 @@ import { getActiveSession, updateActiveSession, type ActiveSessionState } from '
 import { withSessionScopeLifecycle } from '../session/coordinator.js';
 import { RecorderHeldClient, isRecorderHeldClient } from './recorder-client.js';
 import { recDirFor, readRecorderJson } from './motion/recorder.js';
-import { captureError, invalidInput } from '../errors.js';
+import { captureError } from '../errors.js';
 
 function getPortFromWebSocketDebuggerUrl(url?: string): number | null {
   if (!url) return null;
@@ -51,10 +52,10 @@ export interface ConnectionSeams {
   sleep: (ms: number) => Promise<void>;
 }
 
-function defaultResolveTab(parsed: ParsedArgs): Promise<{ port: number; tab: CDPTarget } | null> {
-  return parsed.target
-    ? findTabByIdAcrossEndpoints(parsed.target, parsed.port)
-    : findTabByUrlAcrossEndpoints(parsed.url!, parsed.port);
+async function defaultResolveTab(parsed: ParsedArgs): Promise<{ port: number; tab: CDPTarget } | null> {
+  if (parsed.target) return findTabByIdAcrossEndpoints(parsed.target, parsed.port);
+  if (parsed.url) return findTabByUrlAcrossEndpoints(parsed.url, parsed.port);
+  return findUnambiguousPageTabInPorts(parsed.port === undefined ? (await detectCdpPortsAsync()).map((endpoint) => endpoint.port) : [parsed.port]);
 }
 
 let seams: ConnectionSeams = {
@@ -210,11 +211,15 @@ export async function connectForCommand(
     return routed;
   }
 
-  if (!parsed.target && !parsed.url) {
-    throw invalidInput('Use --target <tabId> or --url <pattern> to target a tab. Run "capture tab list" to see available tabs.', 'missing_target');
+  let resolved: { port: number; tab: CDPTarget } | null;
+  try {
+    resolved = await seams.resolveTab(parsed);
+  } catch (error) {
+    if (error instanceof AmbiguousPageTargetError) {
+      throw captureError('precondition', 'target_unavailable', error.message, error);
+    }
+    throw error;
   }
-
-  const resolved = await seams.resolveTab(parsed);
   const tab = resolved?.tab ?? null;
 
   if (!tab) {
@@ -222,7 +227,9 @@ export async function connectForCommand(
     throw captureError(
       'precondition',
       'target_unavailable',
-      `No tab found for ${parsed.target ? 'target' : 'URL pattern'} "${query}". Run "capture tab list" to see available tabs.`,
+      query === undefined
+        ? 'No page tab found. Run "capture tab list" to see available tabs.'
+        : `No tab found for ${parsed.target ? 'target' : 'URL pattern'} "${query}". Run "capture tab list" to see available tabs.`,
     );
   }
 
@@ -320,7 +327,7 @@ async function finishLocalHar(parsed: ParsedArgs, collectors: Collectors): Promi
   if (batch.entries.length > 0 || batch.incompleteLifecycles.length > 0) {
     await seams.appendHar(parsed.har, batch);
     console.error(
-      `  [har:${parsed.har}] +${batch.entries.length} entries +${batch.incompleteLifecycles.length} incomplete`,
+      `  [har:${parsed.har}] +${batch.entries.length} entries +${batch.incompleteLifecycles.length} incomplete — incomplete lifecycles are retained as their own records (request plus whatever response was observed), separate from log.entries; read them with capture session har`,
     );
   }
 }

package/src/cdp/detect.ts

@@ -1,4 +1,56 @@
 import { execSync } from 'child_process';
+import * as http from 'http';
+
+/**
+ * A CDP-endpoint JSON probe that CANNOT leak a socket handle. Node's built-in
+ * `fetch` (undici) leaves a dangling socket + request handle when a
+ * connect-phase abort fires against a port that accepts TCP but never sends an
+ * HTTP response (e.g. a docker-proxied or half-open listener). That handle
+ * keeps this short-lived CLI process alive for undici's ~7s internal socket
+ * timeout AFTER all real work is done, so a single dead port on the machine
+ * adds ~7s to every command that runs port detection. A raw `http.get` whose
+ * request we explicitly `destroy()` on timeout releases the handle immediately.
+ *
+ * Resolves to the parsed JSON body on a 2xx response, or `null` on any
+ * timeout, connection error, non-2xx status, or unparseable body.
+ */
+function httpGetJson(
+  port: number,
+  path: string,
+  timeoutMs: number,
+): Promise<unknown | null> {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: 'localhost', port, path, timeout: timeoutMs },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        if (status < 200 || status >= 300) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        let body = '';
+        res.setEncoding('utf-8');
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(body));
+          } catch {
+            resolve(null);
+          }
+        });
+        res.on('error', () => resolve(null));
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.on('error', () => resolve(null));
+  });
+}
 
 export const BROWSER_PATTERNS: Record<string, string[]> = {
   'company.thebrowser.browser': ['arc'],
@@ -40,18 +92,12 @@ interface CdpProbeResult {
 // being confused for the intended browser.
 async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 500);
-    const resp = await fetch(`http://localhost:${port}/json/version`, {
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    if (resp.ok) {
-      const version = (await resp.json()) as {
-        Browser?: string;
-        'User-Agent'?: string;
-        webSocketDebuggerUrl?: string;
-      };
+    const version = (await httpGetJson(port, '/json/version', 500)) as {
+      Browser?: string;
+      'User-Agent'?: string;
+      webSocketDebuggerUrl?: string;
+    } | null;
+    if (version) {
       const browser = version.Browser;
       const userAgent = version['User-Agent'] ?? '';
       if (!browser) return null;
@@ -83,14 +129,9 @@ async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
 
 async function probeHasPageTarget(port: number): Promise<boolean> {
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 500);
-    const resp = await fetch(`http://localhost:${port}/json/list`, {
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    if (!resp.ok) return false;
-    const list = (await resp.json()) as Array<{ type?: string }>;
+    const list = (await httpGetJson(port, '/json/list', 500)) as Array<{
+      type?: string;
+    }> | null;
     return Array.isArray(list) && list.some((t) => t.type === 'page');
   } catch {
     return false;

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

@@ -284,6 +284,7 @@ function buildGeometryWalkScript(maxElements: number): string {
           idx: idx,
           tag: tag.toLowerCase(),
           selector: __selectorOf(el),
+          attributes: Array.prototype.map.call(el.attributes, function (attr) { return [attr.name, attr.value]; }),
           domPath: __domPathOf(el),
           text: directText(el),
           frame: { frameId: frameId, isTopFrame: isTop, ancestorFrameIds: ancestorFrameIds.slice() },
@@ -292,6 +293,16 @@ function buildGeometryWalkScript(maxElements: number): string {
           stackingContext: { creates: reasons.length > 0, reasons: reasons },
           visibility: { visible: visible, opacity: opacity, displayNone: displayNone, visibilityHidden: visibilityHidden, zeroSize: zeroSize },
           clipping: clippingInfo(el, rect),
+          paint: {
+            'box-shadow': style.boxShadow,
+            'outline-width': style.outlineWidth,
+            'outline-style': style.outlineStyle,
+            'outline-offset': style.outlineOffset,
+            filter: style.filter,
+            transform: style.transform,
+            'clip-path': style.clipPath,
+            'border-radius': style.borderRadius,
+          },
           layout: {
             boxSizing: style.boxSizing,
             position: style.position,
@@ -342,14 +353,11 @@ function buildGeometryWalkScript(maxElements: number): string {
           pushedFact.iframeContentUnavailable = true;
           pushedFact.iframeContentUnavailableReason = 'content-document-read-threw';
         }
-        if (innerDoc && innerDoc.body) {
+        if (innerDoc && innerDoc.documentElement) {
           frameCounter += 1;
           var childFrameId = 'frame-' + frameCounter;
           var childAncestors = ancestorFrameIds.concat([frameId]);
-          var innerKids = innerDoc.body.children;
-          for (var ii = 0; ii < innerKids.length; ii++) {
-            walk(innerKids[ii], childFrameId, false, childAncestors, null);
-          }
+          walk(innerDoc.documentElement, childFrameId, false, childAncestors, null);
         }
         return;
       }
@@ -360,10 +368,7 @@ function buildGeometryWalkScript(maxElements: number): string {
       }
     }
 
-    var bodyKids = document.body ? document.body.children : [];
-    for (var bi = 0; bi < bodyKids.length; bi++) {
-      walk(bodyKids[bi], 'frame-0', true, [], null);
-    }
+    if (document.documentElement) walk(document.documentElement, 'frame-0', true, [], null);
 
     return { facts: facts, elements: elements, meta: { elementsTruncated: elementsOverflowCount } };
   })()`;
@@ -569,6 +574,17 @@ interface RawGridFact {
   };
 }
 
+interface RawPaintFact {
+  readonly 'box-shadow': string;
+  readonly 'outline-width': string;
+  readonly 'outline-style': string;
+  readonly 'outline-offset': string;
+  readonly filter: string;
+  readonly transform: string;
+  readonly 'clip-path': string;
+  readonly 'border-radius': string;
+}
+
 interface RawLayoutFact {
   readonly boxSizing: string;
   readonly position: string;
@@ -609,6 +625,7 @@ interface RawGeometryFact {
   readonly idx: number;
   readonly tag: string;
   readonly selector?: string;
+  readonly attributes?: readonly (readonly [string, string])[];
   readonly domPath: string;
   readonly text?: string;
   readonly frame: RawFrameFact;
@@ -617,6 +634,8 @@ interface RawGeometryFact {
   readonly stackingContext: RawStackingContextFact;
   readonly visibility: RawVisibilityFact;
   readonly clipping: RawClippingFact | null;
+  /** Ink-relevant computed styles retained here rather than styles.json so every retained geometry element is queryable, including shadow/iframe records and records beyond styles.json's 150-element cap. */
+  readonly paint: RawPaintFact;
   readonly layout: RawLayoutFact;
   /** Present only on an `<iframe>` element's own fact when its `contentDocument` read threw (G6) -- see {@link GeometryElementRecord.iframeContentUnavailable}. */
   readonly iframeContentUnavailable?: boolean;
@@ -639,6 +658,10 @@ export interface GeometryBoxModel {
 export interface GeometryElementRecord extends Omit<ElementRecord, 'backendNodeId'> {
   readonly id: string;
   readonly tag: string;
+  /** The element's own HTML attributes, capped by {@link capAttributes}. */
+  readonly attributes: Readonly<Record<string, string>>;
+  /** Number of own attributes omitted by the per-element cap, when nonzero. */
+  readonly attributesTruncated?: number;
   readonly domPath: string;
   readonly frame: RawFrameFact;
   readonly shadow: RawShadowFact | null;
@@ -649,6 +672,8 @@ export interface GeometryElementRecord extends Omit<ElementRecord, 'backendNodeI
   readonly stackingContext: RawStackingContextFact;
   readonly visibility: RawVisibilityFact;
   readonly clipping: RawClippingFact | null;
+  /** Uncapped, per-geometry-record computed styles used for ink extents and clip-source description. Absent in snapshots captured before ink evidence existed. */
+  readonly paint?: RawPaintFact;
   readonly layout: LayoutFact;
   /** `null` (never an omitted key) when this record's identity did not resolve — see {@link identityUnresolved}. */
   readonly backendNodeId: number | null;
@@ -723,9 +748,24 @@ function resolvedIdentity(backendNodeId: number | undefined): { backendNodeId: n
 
 /** Cap for ordinary computed-CSS-value strings (position/display/min-max sizes/flex+grid provenance). */
 const CSS_VALUE_MAX = 200;
+/** Cap on how many HTML attributes are retained for one geometry element. */
+const MAX_ATTRIBUTES = 32;
+/** Cap on attribute names; values use the ordinary CSS/page-string cap. */
+const ATTRIBUTE_NAME_MAX = 100;
 /** Cap on how many grid template-track strings are kept per axis. */
 const MAX_GRID_TRACKS = 64;
 
+function capAttributes(attributes: readonly (readonly [string, string])[]): { readonly values: Readonly<Record<string, string>>; readonly truncated: number } {
+  const capped = capArray(attributes, MAX_ATTRIBUTES);
+  return {
+    values: Object.fromEntries(capped.items.map(([name, value]) => [
+      sanitizeString(name, { max: ATTRIBUTE_NAME_MAX }),
+      sanitizeString(value, { max: CSS_VALUE_MAX }),
+    ])),
+    truncated: capped.truncated,
+  };
+}
+
 function capTrackList(values: readonly string[]): { items: string[]; truncated: number } {
   const { items, truncated } = capArray(values, MAX_GRID_TRACKS);
   return { items: items.map((v) => sanitizeString(v, { max: CSS_VALUE_MAX })), truncated };
@@ -976,6 +1016,7 @@ export const collectGeometry: Collector = async (ctx) => {
           }
 
           const geometryUnavailable = geometryUnavailableReason !== undefined;
+          const capturedAttributes = capAttributes(fact.attributes ?? []);
           const rect = quads.length > 0 ? unionRect(quads) : { x: 0, y: 0, width: 0, height: 0 };
           // Only a REAL (non-throwing) quads read can strengthen zeroSize/visible
           // beyond the JS-side facts -- when the quads read itself never proved
@@ -988,6 +1029,8 @@ export const collectGeometry: Collector = async (ctx) => {
             id: `el-${fact.idx}`,
             tag: sanitizeString(fact.tag, { max: 64 }),
             selector: fact.selector !== undefined ? sanitizeString(fact.selector, { max: 300 }) : undefined,
+            attributes: capturedAttributes.values,
+            ...(capturedAttributes.truncated ? { attributesTruncated: capturedAttributes.truncated } : {}),
             domPath: sanitizeString(fact.domPath, { max: 500 }),
             ...resolvedIdentity(backendNodeId),
             text: fact.text !== undefined ? sanitizeString(fact.text, { max: 200 }) : undefined,
@@ -1012,6 +1055,20 @@ export const collectGeometry: Collector = async (ctx) => {
                   clippedFraction: fact.clipping.clippedFraction,
                 }
               : null,
+            ...(fact.paint
+              ? {
+                  paint: {
+                    'box-shadow': sanitizeString(fact.paint['box-shadow']),
+                    'outline-width': sanitizeString(fact.paint['outline-width']),
+                    'outline-style': sanitizeString(fact.paint['outline-style']),
+                    'outline-offset': sanitizeString(fact.paint['outline-offset']),
+                    filter: sanitizeString(fact.paint.filter),
+                    transform: sanitizeString(fact.paint.transform),
+                    'clip-path': sanitizeString(fact.paint['clip-path']),
+                    'border-radius': sanitizeString(fact.paint['border-radius']),
+                  },
+                }
+              : {}),
             layout: capLayoutFact(fact.layout),
             ...(geometryUnavailable ? { geometryUnavailable: true as const, geometryUnavailableReason } : {}),
             ...(fact.iframeContentUnavailable

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

@@ -272,6 +272,7 @@ export const collectPixels: Collector = async (ctx) => {
     ctx.write.json('pixels.json', {
       scope: PIXELS_SCOPE,
       elements: [],
+      cropsByBackend: {},
       backgroundOverrideRestored,
       captureFailed: true,
       elementsTotal: 0,
@@ -311,6 +312,10 @@ export const collectPixels: Collector = async (ctx) => {
   const described = await Promise.all(nodeIds.map((nodeId) => describeElementForCrop(client, nodeId)));
 
   const elements: PixelElementRecord[] = [];
+  // Direct lookup from a live/snapshot backend id to its existing crop path.
+  // The element rows remain the authoritative complete records; this map
+  // removes filename-search arithmetic for the common `backend:<id>` lookup.
+  const cropsByBackend: Record<string, string> = {};
   let index = 0;
   let elementsSkipped = 0;
   let elementsReadFailed = 0;
@@ -361,6 +366,7 @@ export const collectPixels: Collector = async (ctx) => {
     const cropFilename = `crops/${cropFileBase(index, entry)}.png`;
     ctx.write.binary(cropFilename, encodePng(applyMaskTransparent(normalCrop, mask)));
 
+    const crop = `${ctx.snapId}/${cropFilename}`;
     elements.push({
       id: `px-${index}`,
       backendNodeId: entry.backendNodeId,
@@ -372,7 +378,7 @@ export const collectPixels: Collector = async (ctx) => {
       ...(entry.clipInfo.unavailable
         ? { ancestorClipUnavailable: true as const, ancestorClipUnavailableReason: entry.clipInfo.unavailableReason }
         : {}),
-      crop: `${ctx.snapId}/${cropFilename}`,
+      crop,
       maskedPixelFraction: round3(mask.count / (pixelRect.width * pixelRect.height)),
       hash: averageHash(normalCrop, mask),
       avgColor: averageColor(normalCrop, mask),
@@ -381,12 +387,14 @@ export const collectPixels: Collector = async (ctx) => {
       alphaFraction: alphaFraction(transparentCrop, mask),
       visiblePixelFraction: visiblePixelFraction(transparentCrop, mask),
     });
+    if (entry.backendNodeId !== null) cropsByBackend[String(entry.backendNodeId)] = crop;
     index += 1;
   }
 
   ctx.write.json('pixels.json', {
     scope: PIXELS_SCOPE,
     elements,
+    cropsByBackend,
     backgroundOverrideRestored,
     captureFailed: false,
     elementsTotal,