@crouton-kit/capture 1.3.20 → 1.4.0

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

@@ -52,6 +52,33 @@ export function pageInputDeps(): PageInputDeps {
   return deps;
 }
 
+export interface PageInputScreenshot {
+  readonly screenshot: string | null;
+  readonly screenshotWarning: string | null;
+}
+
+/** A dispatched page action stays successful when only its follow-up screenshot times out. */
+export async function capturePageInputScreenshot(
+  client: Parameters<typeof autoScreenshot>[0],
+  action: string,
+  label: string,
+  noScreenshot?: boolean,
+): Promise<PageInputScreenshot> {
+  try {
+    return {
+      screenshot: await deps.autoScreenshot(client, action, label, noScreenshot),
+      screenshotWarning: null,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/^CDP request timeout \(\d+ms\): Page\.captureScreenshot$/.test(message)) throw error;
+    return {
+      screenshot: null,
+      screenshotWarning: `automatic screenshot timed out after the page action completed; no screenshot was saved (${message})`,
+    };
+  }
+}
+
 /**
  * The verb's settle window: `--settle <ms>` (including 0) wins outright;
  * otherwise the default is keyed off active-session presence (the in-session
@@ -147,7 +174,7 @@ input:
   --settle <ms>     network-settle window applied after the click (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <clicked backend-node-id=… role=… name=…> — resolved identity, dispatched coordinates, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+  <clicked backend-node-id=… role=… name=…> — resolved identity, dispatched coordinates, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
   scrolls the target into view, then dispatches a real mouse press/release at its center; writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
@@ -177,8 +204,8 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
       const resolved = await resolveLiveTarget(live, target);
       if (!resolved.ok) return { failure: resolved } as const;
       const dispatch = await clickResolved(live, resolved);
-      const screenshot = await deps.autoScreenshot(client, 'click', target, parsed.noScreenshot);
-      return { dispatch, screenshot } as const;
+      const screenshotResult = await capturePageInputScreenshot(client, 'click', target, parsed.noScreenshot);
+      return { dispatch, ...screenshotResult } as const;
     },
   );
 
@@ -186,12 +213,13 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
     return emitResolutionError(parsed, 'page click', outcome.failure);
   }
 
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows: FactLine[] = [
     fact`clicked ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) at x=${dispatch.x} y=${dispatch.y}`,
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+  if (screenshotWarning) rows.push(fact`screenshot-warning: ${screenshotWarning}`);
 
   emitResult(
     {

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

@@ -50,7 +50,7 @@ input:
   <code>           JS source as one argument (exactly one of <code> / --file)
   --file <path>    read the JS source from a file instead of inline
   --settle <ms>    network-settle window after execution so an active session's HAR captures the requests the code triggers (default: ${DEFAULT_SETTLE_MS}; 0 disables); the block reports the measured requested/waited settle
-  --target <id>    target a tab explicitly (default: the active session tab; with no active session, --target or --url is required)
+  --target <id>    target a tab explicitly (default: the active session tab, else exactly one available page tab; multiple page tabs require --target or --url)
   --url <pattern>  target the first tab whose URL matches <pattern>
 output:
   <exec-result result-chars=…> — the JSON-serialized return value inline, escaped and capped at ${GENEROUS_RESULT_CAP} chars; a larger result is also written whole to a private artifact file (the active session's page/ dir, else a one-shot artifact dir) whose absolute path appears in the block. --json mirrors the same block with the value at full fidelity.

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

@@ -22,7 +22,7 @@ import { cmdPageElements } from './elements.js';
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="page">
 verbs against the live session tab — act (click, type, scroll, navigate, exec) and look (shot, elements)
-use when driving or inspecting the page a session opened; all verbs auto-target the active session tab, --target/--url override
+use when driving or inspecting the tab a session opened or adopted; all verbs auto-target the active session tab, --target/--url override
   click · type · scroll · navigate · exec · shot · elements — \`capture page -h\`
 </command>`;
 
@@ -39,7 +39,7 @@ During a live composed recording every verb routes through the recorder.
 <subcommand name="scroll" args="<target> --to <top|bottom|px> [--no-screenshot]" whenToUse="scroll one resolved container to a position"/>
 <subcommand name="navigate" args="<url> [--settle <ms>]" whenToUse="navigate the tab and wait for load + settle"/>
 <subcommand name="exec" args="<code> | --file <path>" whenToUse="run arbitrary JS in the tab (expressions, return, await)"/>
-<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--out <path>]" whenToUse="look at the page right now without acting"/>
+<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--crop <x,y,w,h> | --crop-selector <sel> [--pad <px>]] [--zoom <factor>] [--out <path>]" whenToUse="look at the page right now without acting"/>
 <subcommand name="elements" args="[--all] [--limit <n>]" whenToUse="list what can be acted on — role, name, backend:<id> per element"/>
 
 capture page <leaf> -h    Per-leaf usage`;

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

@@ -13,6 +13,7 @@ import { resolveLiveTarget, scrollResolved, type LiveClient } from '../../../int
 import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
 import {
   pageInputDeps,
+  capturePageInputScreenshot,
   effectiveSettle,
   emitInvalidInput,
   emitResolutionError,
@@ -26,7 +27,7 @@ input:
   --settle <ms>     network-settle window applied after the scroll (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <scrolled backend-node-id=… role=… name=…> — resolved identity, destination, the container's resulting scrollTop, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+  <scrolled backend-node-id=… role=… name=…> — resolved identity, destination, the container's resulting scrollTop, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
   assigns the container's scrollTop in-page (may trigger lazy-load network); writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
@@ -74,8 +75,8 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
       // Same landmark shape `motion rec --do scroll:` records; carried by
       // the one mutating call when the transport records landmarks.
       const dispatch = await scrollResolved(live, resolved, to, { mark: `scroll:${target},to=${to}` });
-      const screenshot = await deps.autoScreenshot(client, 'scroll', target, parsed.noScreenshot);
-      return { dispatch, screenshot } as const;
+      const screenshotResult = await capturePageInputScreenshot(client, 'scroll', target, parsed.noScreenshot);
+      return { dispatch, ...screenshotResult } as const;
     },
   );
 
@@ -83,12 +84,13 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
     return emitResolutionError(parsed, 'page scroll', outcome.failure);
   }
 
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows: FactLine[] = [
     fact`scrolled ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) to ${dispatch.to} — scrollTop now ${dispatch.scrollTop}`,
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+  if (screenshotWarning) rows.push(fact`screenshot-warning: ${screenshotWarning}`);
 
   emitResult(
     {

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/commands/page/type.ts

@@ -18,6 +18,7 @@ import {
 import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
 import {
   pageInputDeps,
+  capturePageInputScreenshot,
   effectiveSettle,
   emitInvalidInput,
   emitResolutionError,
@@ -31,7 +32,7 @@ input:
   --settle <ms>     network-settle window applied after typing (default: 500; 1500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <typed> — the typed text, the resolved field identity (backend-node-id, role, name) and focus-click coordinates when --into was given, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+  <typed> — the typed text, the resolved field identity (backend-node-id, role, name) and focus-click coordinates when --into was given, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
   dispatches a real focus click (when --into) followed by real text insertion; writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
@@ -69,8 +70,8 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
         await typeText(live, textArg);
       }
       // Screenshot label identifies the field, never the typed content.
-      const screenshot = await deps.autoScreenshot(client, 'type', parsed.into ?? 'focused element', parsed.noScreenshot);
-      return { dispatch, screenshot } as const;
+      const screenshotResult = await capturePageInputScreenshot(client, 'type', parsed.into ?? 'focused element', parsed.noScreenshot);
+      return { dispatch, ...screenshotResult } as const;
     },
   );
 
@@ -78,7 +79,7 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
     return emitResolutionError(parsed, 'page type', outcome.failure);
   }
 
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows: FactLine[] = [
     dispatch
       ? fact`typed "${textArg}" into ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}), focus click at x=${dispatch.x} y=${dispatch.y}`
@@ -86,6 +87,7 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+  if (screenshotWarning) rows.push(fact`screenshot-warning: ${screenshotWarning}`);
 
   emitResult(
     {

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/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