@crouton-kit/capture 1.3.21 → 1.4.0

package/src/cdp/measure/ink-source.ts

@@ -0,0 +1,116 @@
+import type { InkRect, InkStyles } from './ink.js';
+
+/**
+ * Selects which recorded rect + computed-style table an ink derivation runs over:
+ * the base-state geometry record, or one element's post-force values under a
+ * requested `--state`. Both callers of `deriveInkBox` over snapshot artifacts
+ * (`measure explain` and `measure map paint`) resolve their input here so the
+ * two leaves cannot disagree about what a forced-state ink box is derived from.
+ */
+export interface InkSource {
+  readonly rect: InkRect;
+  readonly styles: InkStyles;
+  /** Factual description of where `rect` and `styles` were read from, for the caller to report. */
+  readonly provenance: string;
+}
+
+export interface InkSourceUnavailable {
+  /** Factual reason no rect/style pair was found, phrased for direct inclusion in output. */
+  readonly unavailable: string;
+}
+
+export type InkSourceResult = InkSource | InkSourceUnavailable;
+
+export function isInkSource(result: InkSourceResult): result is InkSource {
+  return (result as InkSource).rect !== undefined;
+}
+
+export interface InkTargetIdentity {
+  readonly selector?: string;
+  readonly backendNodeId?: number | null;
+}
+
+interface GeometryLike extends InkTargetIdentity {
+  readonly boxModel?: Record<string, unknown> | null;
+  /** Ink-relevant computed styles recorded beside geometry; absent on snapshots taken before that collection existed. */
+  readonly paint?: Record<string, string | null>;
+}
+
+/** Converts a CDP box-model quad (8 numbers) to its axis-aligned bounding rect. */
+export function quadRect(value: unknown): InkRect | undefined {
+  if (!Array.isArray(value) || value.length !== 8 || !value.every((entry) => Number.isFinite(entry))) return undefined;
+  const xs = [value[0], value[2], value[4], value[6]] as number[];
+  const ys = [value[1], value[3], value[5], value[7]] as number[];
+  const left = Math.min(...xs), top = Math.min(...ys);
+  return { x: left, y: top, width: Math.max(...xs) - left, height: Math.max(...ys) - top };
+}
+
+export function baseInkSource(element: GeometryLike): InkSourceResult {
+  const rect = quadRect((element.boxModel ?? {}).border);
+  if (!rect) return { unavailable: `this target's border-box quad was not captured` };
+  return { rect, styles: element.paint ?? {}, provenance: 'base-state geometry record' };
+}
+
+function rectFrom(value: unknown): InkRect | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const raw = value as Record<string, unknown>;
+  const [x, y, width, height] = [raw.x, raw.y, raw.width ?? raw.w, raw.height ?? raw.h];
+  if (![x, y, width, height].every((entry) => typeof entry === 'number' && Number.isFinite(entry))) return undefined;
+  return { x: x as number, y: y as number, width: width as number, height: height as number };
+}
+
+function stylesFrom(value: unknown): InkStyles | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const after = (value as Record<string, unknown>).after;
+  if (!after || typeof after !== 'object') return undefined;
+  return after as InkStyles;
+}
+
+function identityMatches(row: InkTargetIdentity, target: InkTargetIdentity): boolean {
+  if (typeof target.backendNodeId === 'number' && typeof row.backendNodeId === 'number') return row.backendNodeId === target.backendNodeId;
+  return Boolean(target.selector && row.selector === target.selector);
+}
+
+interface StateRow extends InkTargetIdentity {
+  readonly relation?: string;
+  readonly geometry?: unknown;
+  readonly style?: unknown;
+}
+
+/**
+ * Resolves one element's post-force rect and computed styles from `states.json`.
+ * The rect is that element's `getBoundingClientRect` AABB after the force was
+ * applied — a border box, which is what `deriveInkBox` grows. Under a forced
+ * state the paint change frequently lands on a descendant of the forced target
+ * (a hover ring drawn on a child), so `affected.elements` rows are searched
+ * alongside the forced target's own record.
+ */
+export function forcedStateInkSource(states: unknown, target: InkTargetIdentity, state: string): InkSourceResult {
+  const elements = (states && typeof states === 'object' && Array.isArray((states as Record<string, unknown>).elements))
+    ? (states as { elements: unknown[] }).elements.filter((entry): entry is Record<string, unknown> => Boolean(entry && typeof entry === 'object'))
+    : [];
+  const forState = elements.filter((record) => String(record.state ?? '') === state);
+  if (!forState.length) {
+    const recorded = [...new Set(elements.map((record) => String(record.state ?? '')).filter(Boolean))];
+    return { unavailable: `this snapshot recorded no "${state}" state${recorded.length ? `; it recorded ${recorded.join(', ')}` : ''}` };
+  }
+  const unsupported = forState.filter((record) => record.supported === false);
+  for (const record of forState) {
+    if (record.supported === false) continue;
+    const affected = (record.affected && typeof record.affected === 'object' && Array.isArray((record.affected as Record<string, unknown>).elements))
+      ? ((record.affected as { elements: unknown[] }).elements.filter((entry): entry is StateRow => Boolean(entry && typeof entry === 'object')))
+      : [];
+    const own: StateRow = { selector: record.selector as string | undefined, backendNodeId: record.backendNodeId as number | null | undefined, relation: 'target', geometry: record.geometry, style: record.style };
+    for (const row of [own, ...affected]) {
+      if (!identityMatches(row, target)) continue;
+      const rect = rectFrom((row.geometry as Record<string, unknown> | undefined)?.after);
+      const styles = stylesFrom(row.style);
+      if (!rect) return { unavailable: `the "${state}" record for this target captured no post-force rect` };
+      if (!styles) return { unavailable: `the "${state}" record for this target captured no post-force computed styles` };
+      const id = String(record.id ?? state);
+      return { rect, styles, provenance: `forced state "${state}" (states.json record ${id}, ${row.relation ?? 'affected'} row, post-force values)` };
+    }
+  }
+  if (unsupported.length === forState.length) return { unavailable: `state "${state}" was recorded as unsupported on its forced target` };
+  return { unavailable: `no "${state}" record matched this target; forced-state rows cover the forced target, its light-DOM descendants, and its following-sibling subtrees` };
+}

package/src/cdp/measure/ink.ts

@@ -0,0 +1,180 @@
+export interface InkRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface InkStyles {
+  readonly 'box-shadow'?: string | null;
+  readonly 'outline-width'?: string | null;
+  readonly 'outline-style'?: string | null;
+  readonly 'outline-offset'?: string | null;
+  readonly filter?: string | null;
+  readonly transform?: string | null;
+}
+
+export interface InkEdges {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+
+export interface InkContributor {
+  readonly source: 'box-shadow' | 'outline' | 'filter:drop-shadow';
+  readonly index?: number;
+  readonly edges: InkEdges;
+  /** A blur has no finite specified painted edge; its radius is a nominal AABB convention. */
+  readonly nominal?: true;
+}
+
+export interface InkResult {
+  /** `null` when a needed computed-style value was not captured or a paint-growing filter could not be resolved. */
+  readonly inkBox: InkRect | null;
+  readonly contributors: readonly InkContributor[];
+  readonly missingStyles: readonly string[];
+  readonly unresolved: readonly string[];
+  /** True when an included blur uses the parser's nominal blur-radius extent. */
+  readonly nominal: boolean;
+}
+
+const REQUIRED_STYLES = ['box-shadow', 'outline-width', 'outline-style', 'outline-offset', 'filter', 'transform'] as const;
+
+function zeroEdges(): InkEdges {
+  return { top: 0, right: 0, bottom: 0, left: 0 };
+}
+
+function splitTopLevel(value: string, delimiter: ',' | ' '): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]!;
+    if (char === '(') depth += 1;
+    else if (char === ')' && depth > 0) depth -= 1;
+    else if (depth === 0 && (delimiter === ',' ? char === ',' : /\s/.test(char))) {
+      const part = value.slice(start, index).trim();
+      if (part) parts.push(part);
+      start = index + 1;
+    }
+  }
+  const tail = value.slice(start).trim();
+  if (tail) parts.push(tail);
+  return parts;
+}
+
+function px(value: string): number | undefined {
+  const match = /^(-?(?:\d+|\d*\.\d+))px$/.exec(value) ?? (/^-?(?:\d+|\d*\.\d+)$/.test(value) ? [value, value] : undefined);
+  if (!match) return undefined;
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function edgesForShadow(offsetX: number, offsetY: number, blur: number, spread: number): InkEdges {
+  // CSS computes these values to px. Blur's painted boundary is not a hard CSS edge;
+  // its radius is the recorded geometric extent used for this conservative ink AABB.
+  const growth = Math.max(0, blur + spread);
+  return {
+    left: Math.max(0, growth - offsetX),
+    right: Math.max(0, growth + offsetX),
+    top: Math.max(0, growth - offsetY),
+    bottom: Math.max(0, growth + offsetY),
+  };
+}
+
+function parseShadow(value: string, source: InkContributor['source'], index: number, allowSpread: boolean): InkContributor | undefined {
+  const tokens = splitTopLevel(value, ' ').filter((token) => token.toLowerCase() !== 'inset');
+  const lengths = tokens.map(px).filter((length): length is number => length !== undefined);
+  if (lengths.length < 2 || lengths.length > (allowSpread ? 4 : 3)) return undefined;
+  const [offsetX, offsetY, blur = 0, spread = 0] = lengths;
+  return { source, index, edges: edgesForShadow(offsetX!, offsetY!, blur, allowSpread ? spread : 0), ...(blur > 0 ? { nominal: true as const } : {}) };
+}
+
+function dropShadowArguments(filter: string): string[] {
+  const out: string[] = [];
+  const lower = filter.toLowerCase();
+  let cursor = 0;
+  while (cursor < lower.length) {
+    const start = lower.indexOf('drop-shadow(', cursor);
+    if (start < 0) break;
+    let depth = 1;
+    let end = start + 'drop-shadow('.length;
+    while (end < filter.length && depth > 0) {
+      if (filter[end] === '(') depth += 1;
+      else if (filter[end] === ')') depth -= 1;
+      end += 1;
+    }
+    if (depth === 0) out.push(filter.slice(start + 'drop-shadow('.length, end - 1));
+    cursor = end;
+  }
+  return out;
+}
+
+function containsUnresolvedPaintFilter(filter: string): boolean {
+  const remainder = filter.replace(/drop-shadow\((?:[^()]|\([^()]*\))*\)/gi, '').trim();
+  return /(?:\bblur\(|\burl\()/i.test(remainder);
+}
+
+function combineEdges(contributors: readonly InkContributor[]): InkEdges {
+  return contributors.reduce<InkEdges>((extent, contributor) => ({
+    top: Math.max(extent.top, contributor.edges.top),
+    right: Math.max(extent.right, contributor.edges.right),
+    bottom: Math.max(extent.bottom, contributor.edges.bottom),
+    left: Math.max(extent.left, contributor.edges.left),
+  }), zeroEdges());
+}
+
+/** Derives an axis-aligned ink box from a recorded border box and computed-style table without a browser. */
+export function deriveInkBox(rect: InkRect, styles: InkStyles): InkResult {
+  const missingStyles = REQUIRED_STYLES.filter((property) => styles[property] === undefined || styles[property] === null);
+  if (missingStyles.length) return { inkBox: null, contributors: [], missingStyles, unresolved: [], nominal: false };
+  if (styles.transform !== 'none') return { inkBox: null, contributors: [], missingStyles: [], unresolved: ['transform'], nominal: false };
+
+  const contributors: InkContributor[] = [];
+  const unresolved: string[] = [];
+  const boxShadow = styles['box-shadow']!.trim();
+  if (boxShadow && boxShadow !== 'none') {
+    splitTopLevel(boxShadow, ',').forEach((shadow, index) => {
+      if (/\binset\b/i.test(shadow)) return;
+      const contributor = parseShadow(shadow, 'box-shadow', index + 1, true);
+      if (contributor) contributors.push(contributor);
+      else unresolved.push(`box-shadow ${index + 1}`);
+    });
+  }
+
+  if (styles['outline-style'] !== 'none') {
+    const width = px(styles['outline-width']!.trim());
+    const offset = px(styles['outline-offset']!.trim());
+    if (width === undefined || offset === undefined) unresolved.push('outline');
+    else {
+      const extent = Math.max(0, width + offset);
+      contributors.push({ source: 'outline', edges: { top: extent, right: extent, bottom: extent, left: extent } });
+    }
+  }
+
+  const filter = styles.filter!.trim();
+  if (filter && filter !== 'none') {
+    dropShadowArguments(filter).forEach((shadow, index) => {
+      const contributor = parseShadow(shadow, 'filter:drop-shadow', index + 1, false);
+      if (contributor) contributors.push(contributor);
+      else unresolved.push(`filter drop-shadow ${index + 1}`);
+    });
+    if (containsUnresolvedPaintFilter(filter)) unresolved.push('filter');
+  }
+
+  if (unresolved.length) return { inkBox: null, contributors, missingStyles: [], unresolved, nominal: contributors.some((contributor) => contributor.nominal) };
+  const extent = combineEdges(contributors);
+  return {
+    inkBox: {
+      x: rect.x - extent.left,
+      y: rect.y - extent.top,
+      width: rect.width + extent.left + extent.right,
+      height: rect.height + extent.top + extent.bottom,
+    },
+    contributors,
+    missingStyles: [],
+    unresolved: [],
+    nominal: contributors.some((contributor) => contributor.nominal),
+  };
+}

package/src/cdp/measure/snapshot.ts

@@ -253,6 +253,8 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
   const state = options.state ?? [];
   const viewport = options.viewport ?? null;
   const colorScheme = options.colorScheme;
+  // This narrow extension is parsed by `measure snap`; the shared SnapshotContext remains backwards-compatible for every other collector.
+  const stateDiffPaddingCssPx = (options as CaptureSnapshotOptions & { stateDiffPaddingCssPx?: number }).stateDiffPaddingCssPx ?? 8;
   // Apply the shared artifact-string cap once at the source. URL contents
   // otherwise survive unchanged in meta.json, the result, and collector context.
   const url = options.url ? sanitizeString(options.url) : null;
@@ -377,6 +379,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
         pixels,
         state,
         unstableRegions,
+        ...({ stateDiffPaddingCssPx } as {}),
         write: makeWriter(dir, artifacts),
       };
 

package/src/cdp/screenshot.ts

@@ -16,6 +16,16 @@ export interface CapturedRegion {
   readonly height: number;
 }
 
+/** A CSS-pixel crop request. The capture is intersected with the live visual viewport before it reaches CDP. */
+export interface ScreenshotCrop {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+type ScreenshotOptions = { fullPage?: boolean; crop?: ScreenshotCrop; zoom?: number };
+
 /** A region is reportable only if every number is finite and its size is positive; anything else would produce a fabricated scale. */
 function validRegion(region: CapturedRegion): CapturedRegion | undefined {
   const finite = [region.x, region.y, region.width, region.height].every((n) => typeof n === 'number' && Number.isFinite(n));
@@ -23,6 +33,15 @@ function validRegion(region: CapturedRegion): CapturedRegion | undefined {
   return region;
 }
 
+/** Intersects page-coordinate CSS regions without rounding their geometry. */
+function intersectRegions(a: CapturedRegion, b: CapturedRegion): CapturedRegion | undefined {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return validRegion({ x, y, width: right - x, height: bottom - y });
+}
+
 /**
  * Downscales a PNG so its longest side fits within maxDim, using a box
  * filter. Used when a clipped/scaled CDP capture is unavailable and the raw
@@ -82,7 +101,7 @@ function downscalePngToFit(png: Buffer, maxDim: number): Buffer {
 export async function captureScreenshot(
   client: CDPClient,
   viewport?: { width: number; height: number },
-  options?: { fullPage?: boolean },
+  options?: ScreenshotOptions,
 ): Promise<Buffer> {
   const result = await withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
     viewportScopedCapture(client, viewport, options),
@@ -100,7 +119,7 @@ export async function captureScreenshot(
 export async function captureScreenshotWithCssViewport(
   client: CDPClient,
   viewport?: { width: number; height: number },
-  options?: { fullPage?: boolean },
+  options?: ScreenshotOptions,
 ): Promise<{ png: Buffer; cssViewport?: CapturedRegion }> {
   return withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
     viewportScopedCapture(client, viewport, options, true),
@@ -117,7 +136,7 @@ export async function captureScreenshotWithCssViewport(
 async function viewportScopedCapture(
   client: CDPClient,
   viewport?: { width: number; height: number },
-  options?: { fullPage?: boolean },
+  options?: ScreenshotOptions,
   includeCssViewport = false,
 ): Promise<{ png: Buffer; cssViewport?: CapturedRegion }> {
   const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
@@ -185,16 +204,29 @@ async function viewportScopedCapture(
       }, 5000)) as { result: { value: number } };
       const dpr = dprResult.result.value ?? 1;
 
-      const actualMaxSide = Math.max(vw, vh) * dpr;
-      const scale = actualMaxSide > MAX_DIM ? MAX_DIM / actualMaxSide : 1 / dpr;
+      const visualViewport = validRegion({ x: sx, y: sy, width: vw, height: vh });
+      const requestedCrop = options?.crop;
+      const crop = requestedCrop && visualViewport
+        ? intersectRegions(requestedCrop, visualViewport)
+        : visualViewport;
+      if (!crop) {
+        throw new Error('The requested CSS crop does not intersect the live visual viewport.');
+      }
+      const zoom = options?.zoom ?? 1;
+      const actualMaxSide = Math.max(crop.width, crop.height) * dpr * zoom;
+      const scale = actualMaxSide > MAX_DIM ? MAX_DIM / (Math.max(crop.width, crop.height) * dpr) : zoom / dpr;
       screenshotOpts = {
         ...screenshotOpts,
-        clip: { x: sx, y: sy, width: vw, height: vh, scale },
+        clip: { x: crop.x, y: crop.y, width: crop.width, height: crop.height, scale },
       };
-      // The clip is what the image is cut from, rounding included — not the
-      // fractional viewport it was derived from.
-      capturedRegion = validRegion({ x: sx, y: sy, width: vw, height: vh });
-    } catch {
+      // The clip is what the image is cut from, including a CSS crop's
+      // viewport intersection — not the fractional viewport it was derived from.
+      capturedRegion = crop;
+    } catch (error) {
+      // A crop without CSS viewport metrics cannot be located honestly; unlike
+      // an ordinary full-viewport shot, it must not silently become an
+      // unrelated uncropped image.
+      if (options?.crop) throw error;
       // Capture without downscaling when the optional metrics probe is unavailable.
     }
 
@@ -221,7 +253,7 @@ async function viewportScopedCapture(
 
     // If the browser rejects clipped capture entirely, an unclipped viewport
     // capture is still better than a false successful 0-byte artifact.
-    if (png.length === 0 && screenshotOpts.clip && !options?.fullPage) {
+    if (png.length === 0 && screenshotOpts.clip && !options?.fullPage && !options?.crop) {
       const retry = (await client.send('Page.captureScreenshot', {
         format: 'png',
         captureBeyondViewport: false,

package/src/cdp/targets.ts

@@ -122,6 +122,30 @@ export async function findTabByIdInPorts(
   return null;
 }
 
+export class AmbiguousPageTargetError extends Error {
+  constructor(candidates: readonly { readonly port: number; readonly tab: CDPTarget }[]) {
+    super(`More than one page tab is available:\n${candidates.map(({ port, tab }) => `  ${tab.id.slice(0, 8)}  port ${port}  ${tab.url}`).join('\n')}\nUse --target <tabId> or --url <pattern> to target a tab.`);
+    this.name = 'AmbiguousPageTargetError';
+  }
+}
+
+/** Resolves an omitted target only when all selected endpoints expose one page tab. */
+export async function findUnambiguousPageTabInPorts(
+  ports: readonly number[],
+  lister: (port: number) => Promise<CDPTarget[]> = listTargets,
+): Promise<{ port: number; tab: CDPTarget } | null> {
+  const candidates: Array<{ port: number; tab: CDPTarget }> = [];
+  for (const port of ports) {
+    try {
+      for (const tab of await lister(port)) if (tab.type === 'page') candidates.push({ port, tab });
+    } catch {
+      // An unavailable endpoint cannot supply a target.
+    }
+  }
+  if (candidates.length > 1) throw new AmbiguousPageTargetError(candidates);
+  return candidates[0] ?? null;
+}
+
 function normalizeUrlForMatch(value: string): { full: string; host: string; path: string } | null {
   try {
     const url = new URL(value);

package/src/cdp/types.ts

@@ -78,6 +78,21 @@ export interface ParsedArgs {
   pixels?: boolean;
   /** `snap --state <state[:selector]>` — repeatable; one entry per occurrence. */
   state?: string[];
+  /** `snap --state-padding <px>` — CSS-px padding around the state target when
+   * cropping its rendered/diff artifact. */
+  statePadding?: number;
+  /** `snap --list-crops` — print every crop path instead of the count and dir. */
+  listCrops?: boolean;
+  /** `shot --crop <x,y,w,h>` — crop region in CSS px; composite grammar is
+   * validated by the owning leaf, which documents it. */
+  crop?: string;
+  /** `shot --crop-selector <selector>` — crop to this element's live box. */
+  cropSelector?: string;
+  /** `shot --pad <px>` — CSS-px padding added around a resolved crop rect. */
+  pad?: number;
+  /** `shot --zoom <factor>` — scale multiplier for the captured crop;
+   * fractional grammar is validated by the owning leaf, which documents it. */
+  zoom?: string;
   /** `check --for <list>` — comma-separated check names or categories. */
   for?: string;
   /** `diff --before <snap>` */

package/src/contracts/index.ts

@@ -5,8 +5,6 @@
  * until the atomic U15 public cutover.
  */
 export * from './primitives.js';
-export * from './results.js';
-export * from './routes.js';
 export * from './snapshot.js';
 export * from './neutral.js';
 export * from './a11y.js';

package/src/output/render.ts

@@ -34,6 +34,7 @@ export const RESULT_TAGS = [
   'focus-map',
   'scroll-map',
   'layer-map',
+  'paint-map',
   'recording',
   'motion-mask',
   'timeline',