@crouton-kit/capture 1.4.2 → 1.4.11

package/src/cdp/host/lifecycle.ts

@@ -0,0 +1,123 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { stopBridge } from '../bridge/spawn.js';
+import { processPidBirthProvider, readPrivateFile, removeArtifactTree, sameBirth, unlinkPrivateFile, writeJsonPrivate } from '../../session/artifacts.js';
+import { collectorKind, COLLECTOR_KINDS } from './kinds.js';
+import { sendHostRequest } from './client.js';
+import { scanCollectorHost, type CollectorHostHandle } from './handle.js';
+import type { CollectorKind, TeardownOutcome } from './collector.js';
+
+export type CollectorHostTeardown =
+  | { status: 'absent' }
+  | { status: 'drained'; outcomes: readonly TeardownOutcome[] }
+  | { status: 'reaped'; outcomes: readonly TeardownOutcome[] }
+  | { status: 'terminal'; error: string };
+
+export class TerminalCollectorHostStopFailure extends Error {
+  constructor(readonly outcome: Extract<CollectorHostTeardown, { status: 'terminal' }>) {
+    super(`collector host teardown failed: ${outcome.error}`);
+    this.name = 'TerminalCollectorHostStopFailure';
+  }
+}
+
+export function isTerminalCollectorHostStopFailure(error: unknown): error is TerminalCollectorHostStopFailure {
+  return error instanceof TerminalCollectorHostStopFailure;
+}
+
+function isCollectorKind(value: unknown): value is CollectorKind {
+  return typeof value === 'string' && value in COLLECTOR_KINDS;
+}
+
+function readCollecting(dir: string): { id: string; kind: CollectorKind; startedAt: string } | null {
+  try {
+    const raw = JSON.parse(readPrivateFile(path.join(dir, 'collecting.json')).toString('utf8')) as Record<string, unknown>;
+    if (typeof raw.id !== 'string' || !isCollectorKind(raw.kind) || typeof raw.startedAt !== 'string') return null;
+    return { id: raw.id, kind: raw.kind, startedAt: raw.startedAt };
+  } catch {
+    return null;
+  }
+}
+
+function collectingDirectories(root: string): string[] {
+  const dirs: string[] = [];
+  const walk = (dir: string): void => {
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    if (entries.some(entry => entry.isFile() && entry.name === 'collecting.json')) dirs.push(dir);
+    for (const entry of entries) if (entry.isDirectory()) walk(path.join(dir, entry.name));
+  };
+  walk(root);
+  return dirs;
+}
+
+function reapOrphanedCollectors(sessionDir: string): TeardownOutcome[] {
+  const outcomes: TeardownOutcome[] = [];
+  for (const dir of collectingDirectories(sessionDir)) {
+    const collecting = readCollecting(dir);
+    if (!collecting) continue;
+    try {
+      const reconstructed = collectorKind(collecting.kind).reconstruct(dir);
+      const summary = reconstructed.summary && typeof reconstructed.summary === 'object' && !Array.isArray(reconstructed.summary)
+        ? reconstructed.summary as Record<string, unknown>
+        : { value: reconstructed.summary };
+      writeJsonPrivate(path.join(dir, 'meta.json'), {
+        id: collecting.id,
+        kind: collecting.kind,
+        completion: 'orphaned',
+        reason: 'host_died',
+        startedAt: collecting.startedAt,
+        endedAt: new Date().toISOString(),
+        files: reconstructed.files,
+        summary,
+        ...summary,
+      });
+      unlinkPrivateFile(path.join(dir, 'collecting.json'));
+      outcomes.push({ status: 'reaped', id: collecting.id, kind: collecting.kind, dir });
+    } catch (error) {
+      outcomes.push({ status: 'terminal', id: collecting.id, kind: collecting.kind, dir, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return outcomes;
+}
+
+async function waitForHostExit(handle: CollectorHostHandle, timeoutMs = 2_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const observed = processPidBirthProvider.read(handle.pid);
+    if (observed.status === 'absent' || (observed.status === 'found' && !sameBirth(observed.identity, handle.birth))) return;
+    if (Date.now() >= deadline) {
+      stopBridge(handle.pid, handle.socketPath);
+      return;
+    }
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+}
+
+function terminal(error: string): CollectorHostTeardown {
+  return { status: 'terminal', error };
+}
+
+/** Stops a session's host before immutable bundle construction. A terminal result means the caller must not commit. */
+export async function stopAndReapCollectorHostAtSessionStop(sessionDir: string): Promise<CollectorHostTeardown> {
+  const scanned = scanCollectorHost(sessionDir);
+  if (scanned.classification === 'absent') return { status: 'absent' };
+  if (!scanned.handle) return terminal(`collector host handle is ${scanned.classification}`);
+  if (scanned.classification === 'unknown') return terminal('collector host liveness is unknown');
+  if (scanned.classification === 'dead') {
+    const outcomes = reapOrphanedCollectors(sessionDir);
+    removeArtifactTree(scanned.path);
+    const failure = outcomes.find(outcome => outcome.status === 'terminal');
+    return failure ? terminal(failure.error) : { status: 'reaped', outcomes };
+  }
+  try {
+    const response = await sendHostRequest(scanned.handle.socketPath, { type: 'session-teardown', nonce: scanned.handle.nonce }, 30_000);
+    if (!response.ok) return terminal(response.error ?? 'collector host refused session teardown');
+    const outcomes = Array.isArray(response.outcomes) ? response.outcomes as TeardownOutcome[] : [];
+    const failure = outcomes.find(outcome => outcome.status === 'terminal');
+    if (failure) return terminal(failure.error);
+    await waitForHostExit(scanned.handle);
+    return { status: 'drained', outcomes };
+  } catch (error) {
+    return terminal(error instanceof Error ? error.message : String(error));
+  }
+}

package/src/cdp/host/server.ts

@@ -0,0 +1,88 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CDPClient } from '../client.js';
+import { findTabByIdAcrossEndpoints } from '../targets.js';
+import { closeNdjsonSocket, installProcessCleanup, listenNdjsonSocket } from '../bridge/server.js';
+import { collectorHostSocketPath } from '../bridge/spawn.js';
+import { processPidBirthProvider, removeArtifactTree, writeJsonPrivate } from '../../session/artifacts.js';
+import { readSessionState } from '../../session-context.js';
+import { applyActiveSessionNetworkConditions } from '../connection.js';
+import { CollectorHost, type HostSnapshot } from './core.js';
+import type { CollectorKind } from './collector.js';
+
+export interface RunCollectorHostOptions { socketPath: string; sessionDir: string; targetId: string; port: number; }
+
+function sameNonce(expected: string, actual: unknown): boolean {
+  if (typeof actual !== 'string') return false;
+  const a = Buffer.from(expected); const b = Buffer.from(actual);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+export async function runCollectorHost(options: RunCollectorHostOptions): Promise<void> {
+  if (options.socketPath !== collectorHostSocketPath(options.sessionDir)) throw new Error('collector host socket path must match its session');
+  const target = await findTabByIdAcrossEndpoints(options.targetId, options.port);
+  if (!target?.tab.webSocketDebuggerUrl) throw new Error(`No tab found for target "${options.targetId}" on port ${options.port}.`);
+  const birth = processPidBirthProvider.read(process.pid);
+  if (birth.status !== 'found') throw new Error('could not establish collector host process identity');
+  const nonce = crypto.randomBytes(32).toString('hex');
+  const client = new CDPClient(target.tab.webSocketDebuggerUrl);
+  await client.waitReady();
+  const session = readSessionState(options.sessionDir);
+  if (session.targetId !== options.targetId) throw new Error('collector host target does not match session state');
+  await applyActiveSessionNetworkConditions(client, session, options.targetId);
+  let server: import('node:net').Server | undefined;
+  const handlePath = path.join(options.sessionDir, '.collector-host.json');
+  const publish = (snapshot: HostSnapshot): void => writeJsonPrivate(handlePath, {
+    pid: process.pid, birth: birth.identity, socketPath: options.socketPath, targetId: options.targetId, nonce, startedAt: new Date().toISOString(), ...snapshot,
+  });
+  const cleanup = (): void => {
+    if (server) closeNdjsonSocket(server, options.socketPath);
+    try { client.close(); } catch {}
+  };
+  const host = new CollectorHost(client, options.sessionDir, { pid: process.pid, birth: birth.identity, targetId: options.targetId }, publish, () => {
+    cleanup();
+    try { removeArtifactTree(handlePath); } catch {}
+  });
+  publish(host.snapshot());
+  server = await listenNdjsonSocket(options.socketPath, async (line, socket) => {
+    let request: Record<string, unknown>;
+    try { request = JSON.parse(line) as Record<string, unknown>; } catch { return; }
+    const reqId = typeof request.reqId === 'number' ? request.reqId : 0;
+    const type = typeof request.type === 'string' ? request.type : 'cdp';
+    const answer = (body: Record<string, unknown>): void => { socket.write(JSON.stringify({ reqId, type, ...body }) + '\n'); };
+    if (!sameNonce(nonce, request.nonce)) { answer({ ok: false, error: 'unauthorized' }); return; }
+    try {
+      switch (type) {
+        case 'host-status': answer({ ok: true, ...host.snapshot() }); return;
+        case 'claim-reserve': {
+          const claims = Array.isArray(request.claims) ? request.claims as never : [];
+          const reservation = host.reserve(claims, String(request.holderLabel ?? 'external command'), Number(request.pid), request.birth as never, request.exclusive === true);
+          answer({ ok: true, reservation }); return;
+        }
+        case 'claim-release': host.releaseReservation(String(request.token ?? '')); answer({ ok: true }); return;
+        case 'collector-start': {
+          const row = await host.start(request.kind as CollectorKind, request.config);
+          answer({ ok: true, collector: row }); return;
+        }
+        case 'collector-stop': answer({ ok: true, ...(await host.stop(String(request.id ?? ''))) }); return;
+        case 'session-teardown': answer({ ok: true, outcomes: await host.teardown('session-stop') }); cleanup(); return;
+        case 'har-flush': await host.control({ type: 'har-flush' }); answer({ ok: true }); return;
+        case 'cdp': {
+          const dispatched = await host.dispatch(
+            String(request.method ?? ''),
+            request.params as Record<string, unknown> ?? {},
+            typeof request.annotation === 'string' ? request.annotation : undefined,
+            typeof request.waitEvent === 'string' ? request.waitEvent : undefined,
+            typeof request.timeoutMs === 'number' ? request.timeoutMs : undefined,
+            request.observeDocumentResponse === true,
+          ) as { result?: unknown; event?: unknown; waitOutcome?: unknown; documentResponse?: unknown };
+          answer({ ok: true, ...(dispatched && typeof dispatched === 'object' ? dispatched as Record<string, unknown> : { result: dispatched }) });
+          return;
+        }
+        default: answer({ ok: false, error: `unknown collector host request: ${type}` }); return;
+      }
+    } catch (error) { answer({ ok: false, error: error instanceof Error ? error.message : String(error) }); }
+  });
+  installProcessCleanup(() => { host.abandon(); cleanup(); }, client);
+}

package/src/cdp/measure/check.ts

@@ -12,6 +12,7 @@ export type CheckName = (typeof CHECK_NAMES)[number];
 export interface CheckFinding {
   readonly kind: CheckName;
   readonly elementId?: string;
+  readonly backendNodeId?: number;
   readonly selector?: string;
   readonly rect?: Rect;
   readonly detail: string;
@@ -214,19 +215,166 @@ function readRequired<T>(ref: SnapRef, filename: string): T {
 }
 
 function finding(kind: CheckName, element: GeometryElement | undefined, detail: string, provenance?: string): Omit<CheckFinding, 'caveats'> {
-  return { kind, elementId: element?.id, selector: element?.selector, rect: element ? rectOf(element.rect) : undefined, detail, provenance };
+  return { kind, elementId: element?.id, backendNodeId: element?.backendNodeId ?? undefined, selector: element?.selector, rect: element ? rectOf(element.rect) : undefined, detail, provenance };
 }
 
-function rgb(value: string | null | undefined): [number, number, number] | undefined {
-  const m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(value ?? '');
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+function isSelfOrDescendant(target: GeometryElement, receiver: GeometryElement): boolean {
+  if (target.backendNodeId != null && target.backendNodeId === receiver.backendNodeId) return true;
+  return target.domPath !== undefined && receiver.domPath !== undefined && receiver.domPath.startsWith(`${target.domPath}/`);
 }
+
+interface Rgba { readonly red: number; readonly green: number; readonly blue: number; readonly alpha: number }
+interface StyleElement { readonly selector?: string; readonly backendNodeId?: number | null; readonly computed?: Record<string, string | null> }
+
+function bounded(value: number): number { return Math.min(1, Math.max(0, value)); }
+
+function rgbChannel(token: string): number {
+  const value = token.trim();
+  return value.endsWith('%') ? Number(value.slice(0, -1)) * 2.55 : Number(value);
+}
+
+function fromOklab(lightness: number, a: number, b: number, alpha: number): Rgba | undefined {
+  if (![lightness, a, b, alpha].every(Number.isFinite) || alpha < 0 || alpha > 1) return undefined;
+  const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (lightness - 0.0894841775 * a - 1.2914855480 * b) ** 3;
+  const linear = [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s];
+  const channel = (value: number): number => 255 * (value <= 0.0031308 ? 12.92 * bounded(value) : 1.055 * bounded(value) ** (1 / 2.4) - 0.055);
+  return { red: channel(linear[0]!), green: channel(linear[1]!), blue: channel(linear[2]!), alpha };
+}
+
+function rgba(value: string | null | undefined): Rgba | undefined {
+  const input = value?.trim().toLowerCase();
+  if (!input) return undefined;
+  if (input === 'transparent') return { red: 0, green: 0, blue: 0, alpha: 0 };
+  const hex = /^#([\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.exec(input);
+  if (hex) {
+    const digits = hex[1]!.length <= 4 ? hex[1]!.split('').map((digit) => digit + digit).join('') : hex[1]!;
+    return { red: parseInt(digits.slice(0, 2), 16), green: parseInt(digits.slice(2, 4), 16), blue: parseInt(digits.slice(4, 6), 16), alpha: digits.length === 8 ? parseInt(digits.slice(6, 8), 16) / 255 : 1 };
+  }
+  const rgb = /^rgba?\(\s*([^,\s]+)(?:\s*,\s*|\s+)([^,\s]+)(?:\s*,\s*|\s+)([^,\s]+)(?:\s*(?:,|\/)\s*([^\s)]+))?\s*\)$/i.exec(input);
+  if (rgb) {
+    const channels = [rgbChannel(rgb[1]!), rgbChannel(rgb[2]!), rgbChannel(rgb[3]!)];
+    const alpha = rgb[4] === undefined ? 1 : parseAlphaToken(rgb[4]);
+    return channels.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 255) || !Number.isFinite(alpha) || alpha < 0 || alpha > 1 ? undefined : { red: channels[0]!, green: channels[1]!, blue: channels[2]!, alpha };
+  }
+  const oklab = /^oklab\(\s*([\d.]+)(?:\s*,\s*|\s+)([-\d.]+)(?:\s*,\s*|\s+)([-\d.]+)(?:\s*(?:,|\/)\s*([^\s)]+))?\s*\)$/i.exec(input);
+  if (oklab) return fromOklab(Number(oklab[1]), Number(oklab[2]), Number(oklab[3]), oklab[4] === undefined ? 1 : parseAlphaToken(oklab[4]));
+  const oklch = /^oklch\(\s*([\d.]+)(?:\s*,\s*|\s+)([\d.]+)(?:\s*,\s*|\s+)([-\d.]+)(?:\s*(?:,|\/)\s*([^\s)]+))?\s*\)$/i.exec(input);
+  if (oklch) {
+    const chroma = Number(oklch[2]);
+    const hue = Number(oklch[3]) * Math.PI / 180;
+    return fromOklab(Number(oklch[1]), chroma * Math.cos(hue), chroma * Math.sin(hue), oklch[4] === undefined ? 1 : parseAlphaToken(oklch[4]));
+  }
+  return undefined;
+}
+
+function composite(over: Rgba, under: Rgba): Rgba {
+  const alpha = over.alpha + under.alpha * (1 - over.alpha);
+  if (alpha === 0) return { red: 0, green: 0, blue: 0, alpha: 0 };
+  return {
+    red: (over.red * over.alpha + under.red * under.alpha * (1 - over.alpha)) / alpha,
+    green: (over.green * over.alpha + under.green * under.alpha * (1 - over.alpha)) / alpha,
+    blue: (over.blue * over.alpha + under.blue * under.alpha * (1 - over.alpha)) / alpha,
+    alpha,
+  };
+}
+
+function applyOpacity(paint: Rgba, opacity: number): Rgba {
+  return { ...paint, alpha: paint.alpha * opacity };
+}
+
+function styleFor(element: GeometryElement, stylesByNode: Map<number, StyleElement>, stylesBySelector: Map<string, StyleElement>): StyleElement | undefined {
+  return (element.backendNodeId === null || element.backendNodeId === undefined ? undefined : stylesByNode.get(element.backendNodeId)) ?? (element.selector === undefined ? undefined : stylesBySelector.get(element.selector)) ?? (element.tag === undefined ? undefined : stylesBySelector.get(element.tag));
+}
+
+function remainingOpacityIsOne(element: GeometryElement, byPath: Map<string, GeometryElement>): boolean {
+  let ancestor = element.domPath === undefined ? undefined : byPath.get(parentPath(element.domPath) ?? '');
+  while (ancestor) {
+    if ((ancestor.visibility?.opacity ?? 1) !== 1) return false;
+    ancestor = ancestor.domPath === undefined ? undefined : byPath.get(parentPath(ancestor.domPath) ?? '');
+  }
+  return true;
+}
+
+function effectiveBackground(target: GeometryElement, byPath: Map<string, GeometryElement>, stylesByNode: Map<number, StyleElement>, stylesBySelector: Map<string, StyleElement>): { readonly color: [number, number, number]; readonly source: GeometryElement } | undefined {
+  let element: GeometryElement | undefined = target;
+  let background: Rgba = { red: 0, green: 0, blue: 0, alpha: 0 };
+  let source: GeometryElement | undefined;
+  while (element) {
+    const style = styleFor(element, stylesByNode, stylesBySelector);
+    const paint = rgba(style?.computed?.backgroundColor ?? style?.computed?.['background-color']);
+    if (!paint) return undefined;
+    const wasOpaque = background.alpha === 1;
+    background = applyOpacity(composite(background, paint), element.visibility?.opacity ?? 1);
+    if (!wasOpaque && background.alpha === 1) source = element;
+    else if (background.alpha < 1) source = undefined;
+    if (background.alpha === 1 && source && remainingOpacityIsOne(element, byPath)) return { color: [Math.round(background.red), Math.round(background.green), Math.round(background.blue)], source };
+    element = element.domPath === undefined ? undefined : byPath.get(parentPath(element.domPath) ?? '');
+  }
+  return undefined;
+}
+
+function effectiveForeground(foreground: Rgba, target: GeometryElement, byPath: Map<string, GeometryElement>, stylesByNode: Map<number, StyleElement>, stylesBySelector: Map<string, StyleElement>): [number, number, number] | undefined {
+  let element: GeometryElement | undefined = target;
+  let background: Rgba = { red: 0, green: 0, blue: 0, alpha: 0 };
+  let rendered = foreground;
+  while (element) {
+    const style = styleFor(element, stylesByNode, stylesBySelector);
+    const paint = rgba(style?.computed?.backgroundColor ?? style?.computed?.['background-color']);
+    if (!paint) return undefined;
+    const opacity = element.visibility?.opacity ?? 1;
+    background = applyOpacity(composite(background, paint), opacity);
+    rendered = applyOpacity(composite(rendered, paint), opacity);
+    if (background.alpha === 1 && remainingOpacityIsOne(element, byPath)) return [Math.round(rendered.red), Math.round(rendered.green), Math.round(rendered.blue)];
+    element = element.domPath === undefined ? undefined : byPath.get(parentPath(element.domPath) ?? '');
+  }
+  return undefined;
+}
+
 function contrastRatio(foreground: [number, number, number], background: [number, number, number]): number {
   const lum = (channels: [number, number, number]) => channels.reduce((sum, channel, index) => { const v = channel / 255; return sum + (v <= .03928 ? v / 12.92 : ((v + .055) / 1.055) ** 2.4) * [0.2126, 0.7152, 0.0722][index]; }, 0);
   const a = lum(foreground), b = lum(background);
   return (Math.max(a, b) + .05) / (Math.min(a, b) + .05);
 }
 
+export type ElementContrastMeasurement =
+  | { readonly available: true; readonly foreground: readonly [number, number, number]; readonly background: readonly [number, number, number]; readonly ratio: number; readonly backgroundSource: string; readonly backgroundSourceElementId: string; readonly provenance: string }
+  | { readonly available: false; readonly uncertainty: string };
+
+/** Computes one selected element's effective rendered color pair from the snapshot's recorded styles and ancestor paint. */
+export function measureElementContrast(ref: SnapRef, elementId: string): ElementContrastMeasurement {
+  const elements = readGeometry<{ elements?: GeometryElement[] }>(ref).elements ?? [];
+  const element = elements.find((candidate) => candidate.id === elementId);
+  if (!element) return { available: false, uncertainty: 'the selected geometry record is not present in geometry.json' };
+  const styles = readRequired<{ elements?: StyleElement[] }>(ref, 'styles.json').elements ?? [];
+  const stylesByNode = new Map<number, StyleElement>();
+  const stylesBySelector = new Map<string, StyleElement>();
+  const byPath = new Map<string, GeometryElement>();
+  for (const candidate of elements) if (candidate.domPath) byPath.set(candidate.domPath, candidate);
+  for (const style of styles) {
+    if (style.backendNodeId != null) stylesByNode.set(style.backendNodeId, style);
+    if (style.selector) stylesBySelector.set(style.selector, style);
+  }
+  const style = styleFor(element, stylesByNode, stylesBySelector);
+  const foreground = rgba(style?.computed?.color);
+  if (!foreground) return { available: false, uncertainty: 'the selected element has no parseable recorded computed color' };
+  const background = effectiveBackground(element, byPath, stylesByNode, stylesBySelector);
+  if (!background) return { available: false, uncertainty: 'an opaque effective background could not be resolved from recorded ancestor paint and opacity' };
+  const renderedForeground = effectiveForeground(foreground, element, byPath, stylesByNode, stylesBySelector);
+  if (!renderedForeground) return { available: false, uncertainty: 'the effective foreground could not be resolved through recorded ancestor paint and opacity' };
+  const backgroundSource = label(background.source);
+  return {
+    available: true,
+    foreground: renderedForeground,
+    background: background.color,
+    ratio: contrastRatio(renderedForeground, background.color),
+    backgroundSource,
+    backgroundSourceElementId: background.source.id,
+    provenance: `computed color; effective background supplied by ${backgroundSource}'s opaque paint after compositing recorded descendant backgrounds`,
+  };
+}
+
 /** Read-only analysis over a completed snapshot. Browser driving belongs solely to measure snap. */
 export function checkSnapshot(ref: SnapRef, requested: readonly CheckName[]): { findings: CheckFinding[]; elementCount: number; settled: boolean; viewport: { width: number; height: number } } {
   const geometry = readGeometry<{ elements: GeometryElement[] }>(ref);
@@ -270,24 +418,41 @@ export function checkSnapshot(ref: SnapRef, requested: readonly CheckName[]): {
   if (selected.has('tap-targets')) for (const e of visible) if (/^(button|a|input|select|textarea)$/i.test((e as { tag?: string }).tag ?? '') && (e.rect.width < 44 || e.rect.height < 44)) findings.push(finding('tap-targets', e, `${label(e)} measures ${e.rect.width}×${e.rect.height}px; threshold is 44×44px`));
 
   if (selected.has('contrast')) {
-    const styles = readRequired<{ elements?: Array<{ selector?: string; backendNodeId?: number | null; computed?: Record<string, string | null> }> }>(ref, 'styles.json');
-    for (const style of styles.elements ?? []) {
-      const foreground = rgb(style.computed?.color);
-      const background = rgb(style.computed?.backgroundColor ?? style.computed?.['background-color']);
-      if (!foreground || !background) continue;
-      const ratio = contrastRatio(foreground, background);
+    const styles = readRequired<{ elements?: StyleElement[] }>(ref, 'styles.json').elements ?? [];
+    const stylesByNode = new Map<number, StyleElement>();
+    const stylesBySelector = new Map<string, StyleElement>();
+    const byPath = new Map<string, GeometryElement>();
+    for (const element of elements) if (element.domPath) byPath.set(element.domPath, element);
+    for (const style of styles) {
+      if (style.backendNodeId != null) stylesByNode.set(style.backendNodeId, style);
+      if (style.selector) stylesBySelector.set(style.selector, style);
+    }
+    for (const style of styles) {
+      const foreground = rgba(style.computed?.color);
+      const element = elements.find((candidate) => (style.backendNodeId != null && candidate.backendNodeId === style.backendNodeId) || candidate.selector === style.selector);
+      if (!foreground || !element) continue;
+      const background = effectiveBackground(element, byPath, stylesByNode, stylesBySelector);
+      const renderedForeground = effectiveForeground(foreground, element, byPath, stylesByNode, stylesBySelector);
+      if (!background || !renderedForeground) continue;
+      const ratio = contrastRatio(renderedForeground, background.color);
       if (ratio < 4.5) {
-        const e = elements.find((x) => (style.backendNodeId != null && x.backendNodeId === style.backendNodeId) || x.selector === style.selector);
-        findings.push(finding('contrast', e, `${style.selector ?? label(e ?? {})} foreground ${style.computed?.color} against background ${style.computed?.backgroundColor ?? style.computed?.['background-color']} has contrast ratio ${ratio.toFixed(2)}:1`, 'computed color and background-color'));
+        const source = label(background.source);
+        findings.push(finding('contrast', element, `contrast ratio ${ratio.toFixed(2)}:1 — ${style.selector ?? label(element)} foreground ${style.computed?.color} against composited background rgb(${background.color.join(', ')})`, `computed color; effective background supplied by ${source}'s opaque paint after compositing recorded descendant backgrounds`));
       }
     }
   }
   if (selected.has('hit-test')) {
-    const hit = readHittest<{ elements?: Array<{ selector?: string; backendNodeId?: number | null; selfHitCount?: number; selfHitTotal?: number; points?: Array<{ result?: { topReceiver?: { selector?: string } | null; x?: number; y?: number; stack?: Array<{ selector?: string; pointerEvents?: string; opacity?: number }> } }> }> }>(ref);
-    for (const sample of hit.elements ?? []) if ((sample.selfHitCount ?? 0) < (sample.selfHitTotal ?? 0)) {
+    const hit = readHittest<{ elements?: Array<{ selector?: string; backendNodeId?: number | null; points?: Array<{ result?: { topReceiver?: { selector?: string; backendNodeId?: number | null } | null; x?: number; y?: number; stack?: Array<{ selector?: string; pointerEvents?: string; opacity?: number }> } }> }> }>(ref);
+    for (const sample of hit.elements ?? []) {
       const e = elements.find((x) => (sample.backendNodeId != null && x.backendNodeId === sample.backendNodeId) || (sample.selector && x.selector === sample.selector));
-      const point = sample.points?.find((p) => p.result?.topReceiver?.selector !== sample.selector)?.result;
-      findings.push(finding('hit-test', e, `${label(e ?? sample)} resolves ${sample.selfHitCount ?? 0} of ${sample.selfHitTotal ?? 0} sampled points to itself${point ? `; sampled point (${point.x},${point.y}) receiver ${point.topReceiver?.selector ?? 'none'}` : ''}`, point?.stack?.map((x) => `${x.selector ?? x.pointerEvents ?? 'element'}${x.opacity === 0 ? ' opacity 0' : ''}`).join(', ')));
+      if (!e) continue;
+      const point = sample.points?.find((p) => {
+        const receiver = p.result?.topReceiver;
+        const receiverElement = receiver && elements.find((x) => receiver.backendNodeId != null && x.backendNodeId === receiver.backendNodeId);
+        return receiverElement !== undefined && !isSelfOrDescendant(e, receiverElement);
+      })?.result;
+      if (!point?.topReceiver) continue;
+      findings.push(finding('hit-test', e, `${label(e)} sampled point (${point.x},${point.y}) resolves to non-descendant receiver ${point.topReceiver.selector ?? 'unidentified element'}`, point.stack?.map((x) => `${x.selector ?? x.pointerEvents ?? 'element'}${x.opacity === 0 ? ' opacity 0' : ''}`).join(', ')));
     }
   }
   if (selected.has('truncation')) for (const t of readText<{ elements?: Array<{ selector?: string; backendNodeId?: number | null; truncated?: boolean; scrollWidth?: number; clientWidth?: number }> }>(ref).elements ?? []) if (t.truncated) {

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

@@ -1,7 +1,7 @@
 /**
  * `hittest.json` collector — point-sampled hit-test results (what element
- * actually receives a click at a given coordinate): a 9-point lattice
- * (center + 4 corners + 4 edge-midpoints) per walked element, plus a
+ * actually receives a click at a given coordinate): a 9-point interior lattice
+ * (center + 4 inset corners + 4 inset edge-midpoints) per walked element, plus a
  * coarse whole-viewport grid independent of any element.
  *
  * The ENTIRE walk + sampling happens inside ONE `Runtime.evaluate` script
@@ -330,16 +330,22 @@ function buildHittestScript(maxElements: number, latticeStep: number, latticeMax
     function pointLabelsFor(rect) {
       var cx = rect.x + rect.width / 2;
       var cy = rect.y + rect.height / 2;
+      // Exact border coordinates belong to the adjacent element or outside
+      // the viewport under CSS hit testing. Sample the box interior instead.
+      var insetX = Math.min(1, rect.width / 4);
+      var insetY = Math.min(1, rect.height / 4);
+      var left = rect.x + insetX, right = rect.x + rect.width - insetX;
+      var top = rect.y + insetY, bottom = rect.y + rect.height - insetY;
       return [
         { label: 'center', x: cx, y: cy },
-        { label: 'top-left', x: rect.x, y: rect.y },
-        { label: 'top-right', x: rect.x + rect.width, y: rect.y },
-        { label: 'bottom-left', x: rect.x, y: rect.y + rect.height },
-        { label: 'bottom-right', x: rect.x + rect.width, y: rect.y + rect.height },
-        { label: 'top-mid', x: cx, y: rect.y },
-        { label: 'bottom-mid', x: cx, y: rect.y + rect.height },
-        { label: 'left-mid', x: rect.x, y: cy },
-        { label: 'right-mid', x: rect.x + rect.width, y: cy },
+        { label: 'top-left', x: left, y: top },
+        { label: 'top-right', x: right, y: top },
+        { label: 'bottom-left', x: left, y: bottom },
+        { label: 'bottom-right', x: right, y: bottom },
+        { label: 'top-mid', x: cx, y: top },
+        { label: 'bottom-mid', x: cx, y: bottom },
+        { label: 'left-mid', x: left, y: cy },
+        { label: 'right-mid', x: right, y: cy },
       ];
     }
 

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

@@ -121,7 +121,12 @@ const SCROLL_TOPOLOGY_SCRIPT = `/* __captureScrollTopology */
     }
     return { items: out, truncated: i < kids.length };
   }
-  function visibleChildren(el) {
+  function visibleChildrenAt(el, requestedTop) {
+    // A projected rect is wrong for sticky/fixed and scroll-reactive content.
+    // Measure the actual layout at each offset; the outer finally restores
+    // every original offset before this one evaluation returns.
+    el.scrollTop = requestedTop;
+    var actualTop = el.scrollTop;
     var band = el.getBoundingClientRect();
     var out = [];
     var kids = el.children;
@@ -129,9 +134,9 @@ const SCROLL_TOPOLOGY_SCRIPT = `/* __captureScrollTopology */
     for (i = 0; i < kids.length && out.length < 30; i++) {
       var r = kids[i].getBoundingClientRect();
       var intersects = r.bottom > band.top && r.top < band.bottom && r.right > band.left && r.left < band.right;
-      if (intersects) out.push({ scrollId: tagId(kids[i]), selector: selectorOf(kids[i]), rect: rectOf(kids[i]) });
+      if (intersects) out.push({ scrollId: tagId(kids[i]), selector: selectorOf(kids[i]), rect: { x: r.x, y: r.y, width: r.width, height: r.height } });
     }
-    return { items: out, truncated: i < kids.length };
+    return { offsetTop: actualTop, items: out, truncated: i < kids.length };
   }
 
   var root = document.scrollingElement || document.documentElement;
@@ -186,10 +191,13 @@ const SCROLL_TOPOLOGY_SCRIPT = `/* __captureScrollTopology */
       [originalTop, 0, maxTop].forEach(function(v) { if (!(v in seen)) { seen[v] = true; offsetsToSample.push(v); } });
       for (var s = 0; s < offsetsToSample.length; s++) {
         var top = offsetsToSample[s];
-        el.scrollTop = top;
-        var vc = isRoot ? { items: [], truncated: false } : visibleChildren(el);
-        samples.push({ offsetTop: top, visibleChildren: vc.items, visibleChildrenTruncated: vc.truncated });
+        var vc = isRoot ? { offsetTop: top, items: [], truncated: false } : visibleChildrenAt(el, top);
+        samples.push({ offsetTop: vc.offsetTop, visibleChildren: vc.items, visibleChildrenTruncated: vc.truncated });
       }
+      // Sampling above leaves el scrolled to its last sampled offset;
+      // restore before measuring sticky/fixed/snap descendants so their
+      // rects reflect the container's real (unscrolled) position, not
+      // whichever sample offset was visited last.
       el.scrollTop = originalTop;
       el.scrollLeft = originalLeft;
 
@@ -461,7 +469,7 @@ function toContainerOut(c: ScrollContainerRaw, backendById: Map<string, number>)
 async function resolveMarkerBackendIds(client: CDPClient, markerAttr: string): Promise<Map<string, number>> {
   const map = new Map<string, number>();
   try {
-    const doc = (await client.send('DOM.getDocument', { depth: -1, pierce: false })) as { root?: { nodeId?: number } };
+    const doc = (await client.send('DOM.getDocument', { depth: 0, pierce: false })) as { root?: { nodeId?: number } };
     const rootId = doc.root?.nodeId;
     if (rootId === undefined) return map;
     const res = (await client.send('DOM.querySelectorAll', { nodeId: rootId, selector: `[${markerAttr}]` })) as { nodeIds?: number[] };

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

@@ -38,6 +38,7 @@
 import { resolveAuthoredSourceLocation, type ResolvedSourceLocation } from '../../source-map.js';
 import { sanitizeString } from '../redaction.js';
 import type { CDPClient } from '../../client.js';
+import { isMotionHeldClient } from '../../host/held-client.js';
 
 // ============================================================================
 // Output shape
@@ -597,6 +598,16 @@ export async function captureStyleSheetHeaders(
   client: CDPClient,
 ): Promise<{ urls: Map<string, string>; stop: () => void; available: boolean; reason?: string }> {
   const urls = new Map<string, string>();
+  // A recorder-routed command cannot subscribe through its one-request socket;
+  // ask the recorder's owning CDP connection to collect the same redelivery.
+  if (isMotionHeldClient(client)) {
+    try {
+      for (const header of await client.collectStyleSheetHeaders()) urls.set(header.styleSheetId, header.sourceURL);
+      return { urls, stop: () => {}, available: true };
+    } catch {
+      return { urls, stop: () => {}, available: false, reason: 'stylesheet-header-redelivery-failed' };
+    }
+  }
   if (typeof client.on !== 'function') {
     return { urls, stop: () => {}, available: false, reason: 'client-lacks-event-support' };
   }

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

@@ -123,10 +123,9 @@ export type StylesUnavailableReason = 'styles-evaluate-returned-no-value' | 'sty
 // In-page script — cssPath + computed style facts, no DOM domain calls
 // ============================================================================
 
-// `html`/`body` are excluded: `cssPathFromBody` is rooted AT `document.body`, so it produces `''` for
-// the body element itself and `body > html` for the (out-of-subtree) html element — neither is a valid
-// `body > ...` selector for `resolveNodeIds` to query. Both are structural roots, not measurable subjects.
-const EXCLUDED_TAGS = ['html', 'body', 'script', 'style', 'head', 'meta', 'link', 'title', 'template', 'noscript', 'br', 'wbr'];
+// `html` is excluded because `cssPathFromBody` is rooted at `document.body`, so it would produce
+// an out-of-subtree selector. `body` remains: it supplies the canvas background behind transparent descendants.
+const EXCLUDED_TAGS = ['html', 'script', 'style', 'head', 'meta', 'link', 'title', 'template', 'noscript', 'br', 'wbr'];
 
 interface StylesFact {
   cssPath: string;
@@ -149,6 +148,7 @@ const STYLES_SCRIPT = `/* __captureStylesInventory */
   for (var e = 0; e < EXCLUDED.length; e++) excludedSet[EXCLUDED[e]] = true;
 
   function cssPathFromBody(el) {
+    if (el === document.body) return 'body';
     var parts = [];
     var node = el;
     var depth = 0;

package/src/cdp/measure/explain.ts

@@ -116,7 +116,16 @@ export interface ExplainMissingSelector {
   readonly available: MissingSelectorRecovery;
 }
 
-export type ExplainSnapshotResult = ExplainSuccess | ExplainMissingSelector;
+export interface ExplainAmbiguousSelector {
+  readonly kind: 'ambiguous-selector';
+  readonly ref: SnapRef;
+  readonly selector: string;
+  readonly meta: { readonly settled?: boolean; readonly settleMs?: number };
+  readonly matchCount: number;
+  readonly candidates: readonly ElementRecord[];
+}
+
+export type ExplainSnapshotResult = ExplainSuccess | ExplainMissingSelector | ExplainAmbiguousSelector;
 
 type RawSection = { kind: ExplainSection['kind']; facts: ExplainFact[] };
 
@@ -333,7 +342,7 @@ function stackingClippingSection(target: GeometryElement, geometry: readonly Geo
       : `paint extents could not be resolved: ${ink.unresolved.join(', ')}`;
     facts.push(factFor(target, fact`Ink box (${source.provenance}) was not calculated because ${reason}.`));
   } else {
-    facts.push(factFor(target, text`Ink box was not calculated because ${source.unavailable}.`));
+    facts.push(factFor(target, fact`Ink box was not calculated because ${source.unavailable}.`));
   }
 
   const overflowAncestors = ancestors.filter((element) => {
@@ -567,6 +576,9 @@ export function explainSnapshot(ref: SnapRef, selector: string, detailOpts: Expl
   if (!matches.length) {
     return { kind: 'missing-selector', ref, selector, meta, available: recoveryForms(selectable, selector) };
   }
+  if (matches.length > 1) {
+    return { kind: 'ambiguous-selector', ref, selector, meta, matchCount: matches.length, candidates: matches.slice(0, RECOVERY_CANDIDATE_LIMIT) };
+  }
 
   const selectedId = matches[0]!.id;
   const target = geometry.find((element) => element.id === selectedId)!;