@crouton-kit/capture 1.4.1 → 1.4.10

package/src/cdp/commands/motion/rec.ts

@@ -6,7 +6,7 @@ import { type ParsedArgs } from '../../types.js';
 import { CDPClient } from '../../client.js';
 import { findTabById, openTab } from '../../targets.js';
 import { detectCdpPort } from '../../detect.js';
-import { RecorderSession } from '../../recorder-bridge.js';
+import { RecorderSession } from '../../host/collectors/motion.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
 import {
   emitResult,
@@ -18,7 +18,7 @@ import {
 import { getActiveSession } from '../../../session-context.js';
 import { createOneshotSession } from '../../../session/commands.js';
 import { parseDoAction } from '../../leaf-grammar.js';
-import { ensurePrivateDir, writeBinaryPrivate, writeJsonPrivate, writeNdjsonPrivate, type RecMeta } from '../../../session/artifacts.js';
+import { ensurePrivateDir, readPrivateFile, writeBinaryPrivate, writeJsonPrivate, writeNdjsonPrivate, writePrivateFile, type RecMeta } from '../../../session/artifacts.js';
 import {
   startComposedRecorder,
   stopComposedRecorder,
@@ -34,6 +34,8 @@ import {
   type ResolutionFailure,
 } from '../../../interact.js';
 import { CaptureError } from '../../../errors.js';
+import { sendHostRequest } from '../../host/client.js';
+import { scanCollectorHost } from '../../host/handle.js';
 
 interface RecCommandDeps {
   detectCdpPort: typeof detectCdpPort;
@@ -72,10 +74,11 @@ const USAGE = `capture motion rec — record the page over time: composed (whate
 input:
   [url] --do <action>       one-shot: open <url> (or record the active session tab when <url> is omitted), record one action, finalize
     action                  click:<target> | scroll:<target>,to=<top|bottom|px>
-    target                  css selector (bare string) | ax:<name> (case-insensitive substring) | axid:<id> | backend:<id>
+    target                  css selector (takes precedence) or exact accessible name when CSS finds none (bare string) | ax:<name> (case-insensitive substring) | axid:<id> | backend:<id>
                             must resolve to exactly one live element; text: is not accepted by driving actions
     --duration <seconds>    keep recording after the action (default: 0)
     --viewport <WxH>        emulate a viewport for the recording window (restored after); exact <positive-safe-int>x<positive-safe-int> grammar with lowercase x and no whitespace
+    --artifact-dir <path>   root for a sessionless one-shot recording bundle
   --start                   arm the composed recorder on the active session tab (requires \`capture session start\`)
     --viewport <WxH>        as above; restored on --stop
   --stop                    finalize the composed recording
@@ -83,9 +86,10 @@ input:
 
 output:
   <recording> block — frames, fps, duration, state, event-records, video status, artifact list; --json mirrors.
+  Caveat: screencast frames are change-driven, not a dropped-frame measurement; use \`capture perf trace\` for frame-timing questions.
 
 effects:
-  One-shot on a URL opens a new tab and writes a private one-shot artifact dir; with <url> omitted it records the active session tab and writes under the session. Composed writes under the active session. Scripted actions dispatch real input, marked as labeled landmarks in events.jsonl. Video encodes via ffmpeg when available.`;
+  One-shot on a URL opens a new tab and writes a private one-shot artifact dir under --artifact-dir when supplied; with <url> omitted it records the active session tab through the session collector host and writes under the session. If that active-session one-shot process is interrupted after recording starts, the collector remains live and \`capture motion rec --stop\` finalizes it. Composed writes under the active session. Scripted actions dispatch real input, marked as labeled landmarks in events.jsonl. Video encodes via ffmpeg when available.`;
 
 export async function cmdMotionRec(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
@@ -132,7 +136,12 @@ async function handleOneShot(parsed: ParsedArgs, viewport: Viewport | undefined)
     }
   }
 
-  const oneshot = active ? undefined : deps.createOneshotSession('motion');
+  // The active-session form uses the detached collector host so an external
+  // timeout cannot take its only recorder down with the CLI process. The
+  // host row is then discoverable through session collectors and --stop.
+  if (active && !parsedUrl && active.harId) return handleHostedSessionOneShot(parsed, active, viewport);
+
+  const oneshot = active ? undefined : deps.createOneshotSession('motion', parsed.artifactDir);
   const destination = active ? path.join(active.dir, 'motion', 'recs') : oneshot!.artifactsDir;
   const recId = `rec-${crypto.randomBytes(2).toString('hex')}`;
   const recDir = path.join(destination, recId);
@@ -140,6 +149,7 @@ async function handleOneShot(parsed: ParsedArgs, viewport: Viewport | undefined)
   ensurePrivateDir(path.join(recDir, 'frames'));
 
   let client: CDPClient | undefined;
+  let originalViewport: ActualViewport | undefined;
   let viewportMayHaveApplied = false;
   let failure: string | null = null;
   let failureStatus = 'oneshot_failed';
@@ -157,8 +167,12 @@ async function handleOneShot(parsed: ParsedArgs, viewport: Viewport | undefined)
     client = deps.createClient(tab.webSocketDebuggerUrl);
     await client.waitReady();
     await client.send('Page.enable');
-    viewportMayHaveApplied = viewport !== undefined;
-    await applyViewportOverride(client, viewport);
+    if (viewport) {
+      // Clear is unreliable on adopted headed tabs; restoration must set and verify this measured state.
+      originalViewport = await readActualViewport(client);
+      viewportMayHaveApplied = true;
+      await applyViewportOverride(client, viewport);
+    }
     await waitForPageReady(client);
 
     const recorder = deps.createRecorderSession({ client, recDir });
@@ -168,7 +182,7 @@ async function handleOneShot(parsed: ParsedArgs, viewport: Viewport | undefined)
     const stopped = await recorder.stop();
     let viewportRestored: boolean | null = null;
     if (viewportMayHaveApplied) {
-      viewportRestored = await restoreSessionViewportForClient(client);
+      viewportRestored = await restoreSessionViewportForClient(client, originalViewport!);
       viewportMayHaveApplied = false;
     }
     const finalized = finalizeOneShotRecording(recDir, recId, parsedUrl?.toString() ?? tab.url, parsed.do, stopped, deps.encodeVideo, viewportRestored);
@@ -178,7 +192,7 @@ async function handleOneShot(parsed: ParsedArgs, viewport: Viewport | undefined)
     if (err instanceof DoActionError) failureStatus = err.status;
   } finally {
     let restored: boolean | null = null;
-    if (client && viewportMayHaveApplied) restored = await restoreSessionViewportForClient(client);
+    if (client && viewportMayHaveApplied) restored = await restoreSessionViewportForClient(client, originalViewport!);
     client?.close();
     if (failure !== null) {
       // A failed action is not a completed measurement. Keep the private partial
@@ -188,6 +202,43 @@ async function handleOneShot(parsed: ParsedArgs, viewport: Viewport | undefined)
   }
 }
 
+async function handleHostedSessionOneShot(parsed: ParsedArgs, session: NonNullable<ReturnType<typeof getActiveSession>>, viewport: Viewport | undefined): Promise<void> {
+  let started: StartRecorderResult | undefined;
+  try {
+    started = await deps.startComposedRecorder({ sessionDir: session.dir, viewport });
+    const scanned = scanCollectorHost(session.dir);
+    if (scanned.classification !== 'live' || !scanned.handle) throw new Error(`collector host is ${scanned.classification} after recording start`);
+    const host = scanned.handle;
+    await driveOneShotAction({
+      async handleCdp(request) {
+        const response = await sendHostRequest(host.socketPath, {
+          type: 'cdp', nonce: host.nonce, method: request.method, params: request.params ?? {}, ...(request.mark ? { annotation: request.mark } : {}),
+        }, 30_000);
+        if (!response.ok) throw new Error(response.error ?? `collector host rejected ${request.method}`);
+        return response as { result: unknown };
+      },
+    }, parsed.do!);
+    if (parsed.duration) await sleep(parsed.duration);
+    const stopped = await deps.stopComposedRecorder({ sessionDir: session.dir, recId: started.recId });
+    ensureFinalizedInventory(stopped.recDir);
+    const video = deps.encodeVideo(stopped.recDir, stopped.durationMs);
+    const metaPath = path.join(stopped.recDir, 'meta.json');
+    if (fs.existsSync(metaPath)) {
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')) as Record<string, unknown>;
+      writeJsonPrivate(metaPath, { ...meta, video });
+    }
+    (stopped as FinalizedRecording & { video?: VideoEncoding }).video = video;
+    emitFinalizedResult(parsed, stopped);
+  } catch (err) {
+    const status = err instanceof DoActionError ? err.status : 'oneshot_failed';
+    const message = err instanceof Error ? err.message : String(err);
+    const recovery = started
+      ? `${message}. Recording ${started.recId} remains live at ${started.recDir}; finalize it with \`capture motion rec --stop\` (or inspect \`capture session collectors\`).`
+      : message;
+    emitCommandError(parsed, status, recovery);
+  }
+}
+
 /** A one-shot `--do` failure carrying a precise status for the `<error>` block. */
 export class DoActionError extends Error {
   constructor(message: string, readonly status: string) {
@@ -212,7 +263,7 @@ function recorderLiveClient(recorder: Pick<RecorderSession, 'handleCdp'>): LiveC
 function resolutionError(failure: ResolutionFailure): DoActionError {
   if (failure.code === 'unsupported-prefix') {
     return new DoActionError(
-      `Unsupported --do target prefix in "${failure.input}": text: is query-leaf-only. Accepted prefixes: bare css selector, ax:<name>, axid:<id>, backend:<id>.`,
+      `Unsupported --do target prefix in "${failure.input}": text: is query-leaf-only. Accepted prefixes: bare css selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, backend:<id>.`,
       'unsupported_target_prefix',
     );
   }
@@ -255,9 +306,9 @@ export async function driveOneShotAction(recorder: Pick<RecorderSession, 'handle
   await scrollResolved(live, resolved, parsedAction.to, { mark: action });
 }
 
-/** Exported for the focused artifact-layout test. This is the one-shot
- * counterpart of U14's composed finalizer: it writes the same finalized
- * inventory and deliberately never creates recorder.json. */
+/** Exported for the focused artifact-layout test. This one-shot counterpart
+ * of the composed host finalizer writes the same finalized inventory without
+ * creating a live collector-host handle. */
 export function finalizeOneShotRecording(
   recDir: string,
   recId: string,
@@ -268,11 +319,11 @@ export function finalizeOneShotRecording(
   viewportRestored: boolean | null = null,
 ): FinalizedRecording & { action: string; video: VideoEncoding } {
   ensureFinalizedInventory(recDir);
+  writeJsonPrivate(path.join(recDir, 'markers.json'), stopped.markers);
   const video = encodeVideo(recDir, stopped.durationMs);
   const fps = stopped.durationMs > 0 ? Math.round((stopped.frameCount / (stopped.durationMs / 1000)) * 10) / 10 : 0;
   const state = stopped.frameCount > 0 ? 'finalized' : 'partial';
-  writeJsonPrivate(path.join(recDir, 'markers.json'), stopped.markers);
-  const meta: RecMeta & { url: string; fps: number; eventCount: number; video: VideoEncoding; viewportRestored: boolean | null; reason?: 'no_frames' } = {
+  const meta: RecMeta & { url: string; fps: number; eventCount: number; video: VideoEncoding; viewportRestored: boolean | null; viewportRetained: boolean; reason?: 'no_frames' } = {
     id: recId,
     action,
     frames: stopped.frameCount,
@@ -284,9 +335,10 @@ export function finalizeOneShotRecording(
     eventCount: stopped.eventCount,
     video,
     viewportRestored,
+    viewportRetained: false,
   };
   writeJsonPrivate(path.join(recDir, 'meta.json'), meta);
-  return { recId, recDir, frames: stopped.frameCount, durationMs: stopped.durationMs, fps, state, eventCount: stopped.eventCount, viewportRestored, action, video };
+  return { recId, recDir, frames: stopped.frameCount, durationMs: stopped.durationMs, fps, state, eventCount: stopped.eventCount, viewportRestored, viewportRetained: false, action, video };
 }
 
 function ensureFinalizedInventory(recDir: string): void {
@@ -325,10 +377,36 @@ async function applyViewportOverride(client: Pick<CDPClient, 'send'>, viewport:
   return true;
 }
 
-async function restoreSessionViewportForClient(client: Pick<CDPClient, 'send'>): Promise<boolean> {
+interface ActualViewport {
+  width: number;
+  height: number;
+  deviceScaleFactor: number;
+}
+
+async function readActualViewport(client: Pick<CDPClient, 'send'>): Promise<ActualViewport> {
+  const response = await client.send('Runtime.evaluate', {
+    expression: '(() => ({ width: window.innerWidth, height: window.innerHeight, deviceScaleFactor: window.devicePixelRatio }))()',
+    returnByValue: true,
+  }) as { result?: { value?: Partial<ActualViewport> } };
+  const viewport = response.result?.value;
+  if (!viewport || ![viewport.width, viewport.height, viewport.deviceScaleFactor].every((value) => typeof value === 'number' && Number.isFinite(value) && value > 0)) {
+    throw new Error('Could not read the target’s actual viewport before recording; refusing to apply an override that cannot be verified on restore.');
+  }
+  return viewport as ActualViewport;
+}
+
+async function restoreSessionViewportForClient(client: Pick<CDPClient, 'send'>, original: ActualViewport): Promise<boolean> {
   try {
-    await client.send('Emulation.clearDeviceMetricsOverride');
-    return true;
+    await client.send('Emulation.setDeviceMetricsOverride', {
+      width: original.width,
+      height: original.height,
+      deviceScaleFactor: original.deviceScaleFactor,
+      mobile: false,
+    });
+    const restored = await readActualViewport(client);
+    return restored.width === original.width
+      && restored.height === original.height
+      && restored.deviceScaleFactor === original.deviceScaleFactor;
   } catch {
     return false;
   }
@@ -381,25 +459,66 @@ export function classifyEncodeFailure(result: { error?: (Error & { code?: string
   return 'ffmpeg_encoding_failed';
 }
 
+/** Builds the concat manifest from the recorder's frame timestamps. A screencast is
+ * change-driven, but each retained frame's presentation timestamp is factual; a
+ * recording without a complete, ordered timestamp sequence cannot produce a
+ * timestamp-faithful video. */
+function timestampedFrameManifest(recDir: string, frames: readonly string[], manifestPath: string): VideoEncoding | undefined {
+  let rects: unknown[];
+  let markers: Record<string, unknown>;
+  try {
+    rects = readPrivateFile(path.join(recDir, 'rects.jsonl')).toString('utf8').trim().split('\n').filter(Boolean).map(line => JSON.parse(line));
+    markers = JSON.parse(readPrivateFile(path.join(recDir, 'markers.json')).toString('utf8')) as Record<string, unknown>;
+  } catch {
+    return { status: 'unavailable', reason: 'frame_timestamps_unavailable' };
+  }
+  const timestamps = new Map<string, number>();
+  for (const rect of rects) {
+    if (!rect || typeof rect !== 'object') continue;
+    const { file, screencastTimestamp } = rect as { file?: unknown; screencastTimestamp?: unknown };
+    if (typeof file !== 'string' || typeof screencastTimestamp !== 'number' || !Number.isFinite(screencastTimestamp) || timestamps.has(file)) return { status: 'unavailable', reason: 'frame_timestamps_unavailable' };
+    timestamps.set(file, screencastTimestamp * 1000);
+  }
+  const frameTimes = frames.map(frame => timestamps.get(frame));
+  if (frameTimes.some((timestamp): timestamp is undefined => timestamp === undefined)) return { status: 'unavailable', reason: 'frame_timestamps_unavailable' };
+  if (frameTimes.some((timestamp, index) => index > 0 && timestamp <= frameTimes[index - 1]!)) return { status: 'unavailable', reason: 'frame_timestamps_unordered' };
+  const stoppedAtWallClockMs = markers.stoppedAtWallClockMs;
+  if (typeof stoppedAtWallClockMs !== 'number' || !Number.isFinite(stoppedAtWallClockMs)) return { status: 'unavailable', reason: 'frame_timestamps_unavailable' };
+  const finalDurationMs = stoppedAtWallClockMs - frameTimes[frameTimes.length - 1]!;
+  if (!(finalDurationMs > 0)) return { status: 'unavailable', reason: 'frame_timestamps_unavailable' };
+  const durationsMs = frameTimes.slice(1).map((timestamp, index) => timestamp - frameTimes[index]!);
+  durationsMs.push(finalDurationMs);
+  const quote = (filename: string) => filename.replace(/'/g, "'\\''");
+  const lines = ['ffconcat version 1.0'];
+  for (let index = 0; index < frames.length; index++) {
+    lines.push(`file '${quote(path.join(recDir, 'frames', frames[index]!))}'`, 'option framerate 1000', `duration ${(durationsMs[index]! / 1000).toFixed(9)}`);
+  }
+  // ffconcat applies a duration to the following file, so repeat the final
+  // image at the recorder's observed stop boundary to retain its final hold.
+  lines.push(`file '${quote(path.join(recDir, 'frames', frames[frames.length - 1]!))}'`, 'option framerate 1000');
+  writePrivateFile(manifestPath, lines.join('\n') + '\n');
+  return undefined;
+}
+
 /** Encodes inside a new private directory, then installs through the shared
- * atomic no-follow writer. Frame cadence is measured from the recording's
- * duration rather than assumed from a display refresh rate. */
-export function encodeVideoIfAvailable(recDir: string, durationMs: number): VideoEncoding {
+ * atomic no-follow writer. The concat demuxer receives every recorded
+ * screencast presentation timestamp instead of a fabricated constant cadence. */
+export function encodeVideoIfAvailable(recDir: string, _durationMs: number): VideoEncoding {
   const framesDir = path.join(recDir, 'frames');
   const frames = fs.existsSync(framesDir) ? fs.readdirSync(framesDir).filter((name) => name.endsWith('.png')).sort() : [];
   if (frames.length === 0) return { status: 'unavailable', reason: 'no_frames' };
-  if (durationMs <= 0) return { status: 'unavailable', reason: 'recording_duration_unavailable' };
   const probe = spawnSync('ffmpeg', ['-hide_banner', '-encoders'], { encoding: 'utf8', timeout: 5_000 });
   if (probe.error || probe.status !== 0 || !String(probe.stdout ?? '').includes('libvpx-vp9')) return { status: 'unavailable', reason: 'ffmpeg_or_vp9_encoder_unavailable' };
   const tempDir = path.join(recDir, `.video-encode-${crypto.randomBytes(8).toString('hex')}`);
   ensurePrivateDir(tempDir);
   const tempOutput = path.join(tempDir, 'video.webm');
-  const cadence = String(frames.length / (durationMs / 1000));
-  const result = spawnSync('ffmpeg', [
-    '-y', '-framerate', cadence, '-pattern_type', 'glob', '-i', path.join(framesDir, '*.png'),
-    '-c:v', 'libvpx-vp9', '-pix_fmt', 'yuv420p', tempOutput,
-  ], { stdio: 'ignore', timeout: encodeTimeoutMs(frames.length) });
   try {
+    const manifestOutcome = timestampedFrameManifest(recDir, frames, path.join(tempDir, 'frames.ffconcat'));
+    if (manifestOutcome) return manifestOutcome;
+    const result = spawnSync('ffmpeg', [
+      '-y', '-f', 'concat', '-safe', '0', '-i', path.join(tempDir, 'frames.ffconcat'), '-fps_mode', 'vfr',
+      '-c:v', 'libvpx-vp9', '-pix_fmt', 'yuv420p', tempOutput,
+    ], { stdio: 'ignore', timeout: encodeTimeoutMs(frames.length) });
     if (result.error || result.status !== 0 || !fs.existsSync(tempOutput)) {
       return { status: 'failed', reason: classifyEncodeFailure(result) };
     }
@@ -473,8 +592,88 @@ async function handleStop(parsed: ParsedArgs): Promise<void> {
   emitFinalizedResult(parsed, stopped);
 }
 
+type RecordingLossCounts =
+  | { rectSampleElementsDropped: number; bindingRecordsDropped: number; rectSampleFramesTruncated: number; rectSampleFramesCandidateTruncated: number }
+  | { unavailableReason: string };
+
+function recordingLossCounts(recDir: string): RecordingLossCounts {
+  let raw: string;
+  try {
+    raw = readPrivateFile(path.join(recDir, 'events.jsonl')).toString('utf8');
+  } catch (error) {
+    return { unavailableReason: `events.jsonl could not be read (${error instanceof Error ? error.message : String(error)})` };
+  }
+  let rectSampleElementsDropped = 0;
+  let bindingRecordsDropped = 0;
+  let rectSampleFramesTruncated = 0;
+  let rectSampleFramesCandidateTruncated = 0;
+  for (const line of raw.split('\n').filter(Boolean)) {
+    let event: unknown;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      return { unavailableReason: 'events.jsonl contains a malformed event record' };
+    }
+    if (!event || typeof event !== 'object') continue;
+    const { kind, count } = event as { kind?: unknown; count?: unknown };
+    if (kind !== 'rect-sample-dropped' && kind !== 'binding-dropped') continue;
+    if (!Number.isSafeInteger(count) || count < 0) return { unavailableReason: `${String(kind)} has no non-negative integer count` };
+    if (kind === 'rect-sample-dropped') {
+      if (!Number.isSafeInteger(rectSampleElementsDropped + count)) return { unavailableReason: 'rect-sample-dropped count exceeds the safe integer range' };
+      rectSampleElementsDropped += count;
+    } else {
+      if (!Number.isSafeInteger(bindingRecordsDropped + count)) return { unavailableReason: 'binding-dropped count exceeds the safe integer range' };
+      bindingRecordsDropped += count;
+    }
+  }
+  let rectsRaw: string;
+  try {
+    rectsRaw = readPrivateFile(path.join(recDir, 'rects.jsonl')).toString('utf8');
+  } catch (error) {
+    return { unavailableReason: `rects.jsonl could not be read (${error instanceof Error ? error.message : String(error)})` };
+  }
+  for (const line of rectsRaw.split('\n').filter(Boolean)) {
+    let rect: unknown;
+    try {
+      rect = JSON.parse(line);
+    } catch {
+      return { unavailableReason: 'rects.jsonl contains a malformed rect record' };
+    }
+    if (!rect || typeof rect !== 'object') continue;
+    if ((rect as { elementSampleTruncated?: unknown }).elementSampleTruncated === true) {
+      if (!Number.isSafeInteger(rectSampleFramesTruncated + 1)) return { unavailableReason: 'rect-sample truncation count exceeds the safe integer range' };
+      rectSampleFramesTruncated++;
+    }
+    if ((rect as { candidateSampleTruncated?: unknown }).candidateSampleTruncated === true) {
+      if (!Number.isSafeInteger(rectSampleFramesCandidateTruncated + 1)) return { unavailableReason: 'rect-sample candidate truncation count exceeds the safe integer range' };
+      rectSampleFramesCandidateTruncated++;
+    }
+  }
+  return { rectSampleElementsDropped, bindingRecordsDropped, rectSampleFramesTruncated, rectSampleFramesCandidateTruncated };
+}
+
 function emitFinalizedResult(parsed: ParsedArgs, stopped: FinalizedRecording & { action?: string }): void {
   const durationS = `${(stopped.durationMs / 1000).toFixed(1)}s`;
+  const lossCounts = recordingLossCounts(stopped.recDir);
+  const lossAttrs = 'unavailableReason' in lossCounts
+    ? { 'rect-sample-elements-dropped': 'unavailable', 'binding-records-dropped': 'unavailable', 'rect-sample-frames-truncated': 'unavailable', 'rect-sample-frames-candidate-truncated': 'unavailable' }
+    : {
+      'rect-sample-elements-dropped': lossCounts.rectSampleElementsDropped,
+      'binding-records-dropped': lossCounts.bindingRecordsDropped,
+      'rect-sample-frames-truncated': lossCounts.rectSampleFramesTruncated,
+      'rect-sample-frames-candidate-truncated': lossCounts.rectSampleFramesCandidateTruncated,
+    };
+  const lossFacts = 'unavailableReason' in lossCounts
+    ? [fact`Dropped rect-sample element and binding-record counts and rect-sample truncation state are unavailable: ${lossCounts.unavailableReason}.`]
+    : [
+      fact`Retained rect samples contain only the frame and element facts the recorder retained; ${lossCounts.rectSampleElementsDropped} rect-sample element fact(s) and ${lossCounts.bindingRecordsDropped} binding record(s) were dropped.`,
+      ...(lossCounts.rectSampleFramesTruncated > 0
+        ? [fact`${lossCounts.rectSampleFramesTruncated} rect sample frame(s) stopped after 4000 non-zero-size elements; remaining DOM candidates were not sampled because of the element cap.`]
+        : []),
+      ...(lossCounts.rectSampleFramesCandidateTruncated > 0
+        ? [fact`${lossCounts.rectSampleFramesCandidateTruncated} rect sample frame(s) sampled rect geometry from 8000 DOM element candidates; remaining DOM candidates were not sampled because of the geometry-read cap.`]
+        : []),
+    ];
   const result: RenderableResult = {
     tag: 'recording',
     attestation: { kind: 'recording', id: stopped.recId, path: stopped.recDir },
@@ -484,9 +683,11 @@ function emitFinalizedResult(parsed: ParsedArgs, stopped: FinalizedRecording & {
       duration: durationS,
       state: stopped.state,
       'event-records': stopped.eventCount ?? 'unavailable',
+      ...lossAttrs,
       'baseline-availability': baselineAvailability(stopped.recDir),
       ...(stopped.action ? { action: stopped.action } : {}),
       ...(stopped.viewportRestored !== null ? { 'viewport-restored': stopped.viewportRestored } : {}),
+      ...(stopped.viewportRetained ? { 'viewport-retained': true } : {}),
       ...('video' in stopped ? { video: (stopped as { video?: VideoEncoding }).video?.status ?? 'unavailable' } : {}),
       'timestamp-uncertainty': '±1 frame for frame-derived timestamps',
     },
@@ -497,6 +698,7 @@ function emitFinalizedResult(parsed: ParsedArgs, stopped: FinalizedRecording & {
         : stopped.eventCount !== null
           ? fact`Recording finalized: ${stopped.frames} frame(s) over ${durationS}, ${stopped.eventCount} event record(s).`
           : fact`Recording finalized: ${stopped.frames} frame(s) over ${durationS}.`,
+    sections: lossFacts,
     artifacts: formatArtifactList(listRecordingArtifacts(stopped.recDir)),
   };
   emitResult(result, { json: parsed.json });

package/src/cdp/commands/motion/timeline.ts

@@ -87,7 +87,7 @@ export async function cmdMotionTimeline(parsed: ParsedArgs, _args: string[]): Pr
         { name: 'meta.json', note: `recording state ${meta.state}` },
       ]),
       sections: rows.length ? [lineList(rows)] : [text`The selected element had no complete bounding-box samples.`],
-      followUp: text`Use \`capture motion jank <rec>\` for dropped-frame and observer-event facts, or \`capture motion response <rec>\` for input-to-settle timing facts.`,
+      followUp: text`Use \`capture motion jank <rec>\` for observer-event facts, or \`capture motion response <rec>\` for input-to-settle timing facts.`,
     };
     emitResult(result, { json: parsed.json });
   } catch (err) {

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

@@ -63,10 +63,11 @@ export async function capturePageInputScreenshot(
   action: string,
   label: string,
   noScreenshot?: boolean,
+  out?: string,
 ): Promise<PageInputScreenshot> {
   try {
     return {
-      screenshot: await deps.autoScreenshot(client, action, label, noScreenshot),
+      screenshot: await deps.autoScreenshot(client, action, label, noScreenshot, out),
       screenshotWarning: null,
     };
   } catch (error) {
@@ -112,7 +113,7 @@ export function emitResolutionError(parsed: ParsedArgs, command: string, failure
       {
         tag: 'error',
         attrs: { command, code: 'unsupported_prefix' },
-        summary: fact`received: target \`${failure.input}\` — the \`text:\` prefix is not accepted by live driving verbs; expected one of: bare CSS selector, ax:<name>, axid:<id>, backend:<id>.`,
+        summary: fact`received: target \`${failure.input}\` — the \`text:\` prefix is not accepted by live driving verbs; expected one of: bare CSS selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, backend:<id>.`,
         followUp: fact`Retry \`${command}\` with \`ax:<name>\` (accessible-name substring) or a CSS selector; \`text:\` matching exists only on the query leaves.`,
       },
       { json: parsed.json },
@@ -170,13 +171,14 @@ export function emitResolutionError(parsed: ParsedArgs, command: string, failure
 const USAGE = `capture page click <target> — dispatch one real click on exactly one resolved element
 
 input:
-  <target>          resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring over accessible names), axid:<id>, backend:<id>. text: is not accepted. Exactly one match required — zero or many matches is a structured error listing candidates with backend:<id> retry keys.
+  <target>          resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring over accessible names), axid:<id>, backend:<id>. text: is not accepted. Exactly one match required — zero or many matches is a structured error listing candidates with backend:<id> retry keys.
   --settle <ms>     network-settle window applied after the click (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
+  --out <path>      destination for the auto-screenshot; same semantics as page shot — overrides the active session's shots/ sequence and enables the screenshot without an active session
 output:
-  <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
+  <clicked backend-node-id=… role=… name=…> — resolved identity, dispatched coordinates, a hit-test receiver fact when another node covers that dispatch point, 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`;
+  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. --out writes that screenshot to the caller-chosen path instead and works without an active session`;
 
 export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
@@ -188,10 +190,13 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
     return emitInvalidInput(
       parsed,
       'page click',
-      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector, ax:<name>, axid:<id>, or backend:<id>).`,
+      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector or exact accessible name, ax:<name>, axid:<id>, or backend:<id>).`,
     );
   }
 
+  const settleDefaultSource = parsed.settle === undefined
+    ? deps.getActiveSession() === null ? 'standalone default' : 'active-session default'
+    : undefined;
   const settle = effectiveSettle(parsed, { standalone: 1000, session: 2500 });
   // connection.ts derives the recorder landmark label from parsed.command,
   // which the router leaves as the branch token 'page' — restore the verb so
@@ -203,8 +208,8 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
       const live = client as unknown as LiveClient;
       const resolved = await resolveLiveTarget(live, target);
       if (!resolved.ok) return { failure: resolved } as const;
-      const dispatch = await clickResolved(live, resolved);
-      const screenshotResult = await capturePageInputScreenshot(client, 'click', target, parsed.noScreenshot);
+      const dispatch = await clickResolved(live, resolved, { inspectHitTest: true });
+      const screenshotResult = await capturePageInputScreenshot(client, 'click', target, parsed.noScreenshot, parsed.out);
       return { dispatch, ...screenshotResult } as const;
     },
   );
@@ -216,7 +221,11 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
   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}`,
+    ...(dispatch.hitTestReceiverBackendNodeId === undefined
+      ? []
+      : [fact`dispatch hit test at x=${dispatch.x} y=${dispatch.y} resolved to backend:${dispatch.hitTestReceiverBackendNodeId}, not target backend:${dispatch.backendNodeId}`]),
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
+    ...(settleDefaultSource === undefined ? [] : [fact`settle source: ${settleDefaultSource}; no --settle flag was passed.`]),
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
   if (screenshotWarning) rows.push(fact`screenshot-warning: ${screenshotWarning}`);
@@ -228,6 +237,7 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
         'backend-node-id': dispatch.backendNodeId,
         role: dispatch.role ?? undefined,
         name: dispatch.name ?? undefined,
+        'hit-test-receiver-backend-node-id': dispatch.hitTestReceiverBackendNodeId,
       },
       summary: lineList(rows),
     },

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

@@ -18,6 +18,7 @@
  */
 import { type ParsedArgs } from '../../types.js';
 import { invalidInput } from '../../../errors.js';
+import { selectRecords } from '../../../output/selection.js';
 import { withConnection } from '../../connection.js';
 import { INTERACTIVE_ROLES, readFullAXTree } from '../../a11y.js';
 import {
@@ -37,7 +38,8 @@ const USAGE = `capture page elements — list what can be acted on in the live t
 
 Input:
   --all               full exposed accessibility tree instead of interactive elements only
-  --limit <n>         max elements listed (positive integer, default ${DEFAULT_LIMIT}; a capped list states the total as an elements-truncated fact)
+  --name <text>       case-insensitive substring filter over each exposed accessibility name; applies before --limit
+  --limit <n>         max filtered elements returned in prose and JSON (positive integer, default ${DEFAULT_LIMIT}; a capped list states the total as an elements-truncated fact)
   --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
   --json              mirror the result as JSON
 
@@ -69,9 +71,24 @@ export interface ElementRecord {
  */
 export async function collectElements(
   client: ElementsClient,
-  opts: { all?: boolean } = {},
+  opts: { all?: boolean; name?: string } = {},
 ): Promise<ElementRecord[]> {
   const nodes = await readFullAXTree(client);
+  const nodesById = new Map(nodes.map((node) => [node.nodeId, node]));
+  const parents = new Map<string, (typeof nodes)[number]>();
+  for (const node of nodes) {
+    for (const childId of node.childIds ?? []) parents.set(childId, node);
+  }
+  const nameOf = (node: (typeof nodes)[number]): string => {
+    const ownName = node.name?.value ?? '';
+    if (ownName) return ownName;
+    return (node.childIds ?? [])
+      .map((childId) => nodesById.get(childId))
+      .filter((child): child is (typeof nodes)[number] => child?.role?.value === 'StaticText')
+      .map((child) => child.name?.value ?? '')
+      .filter(Boolean)
+      .join(' ');
+  };
 
   const records: ElementRecord[] = [];
   for (const node of nodes) {
@@ -81,14 +98,29 @@ export async function collectElements(
     if (!opts.all) {
       if (!INTERACTIVE_ROLES.has(role)) continue;
       if (node.backendDOMNodeId === undefined) continue;
+    } else {
+      const parent = parents.get(node.nodeId);
+      const duplicateParentText =
+        parent !== undefined &&
+        (node.name?.value === parent.name?.value || (role === 'StaticText' && !parent.name?.value));
+      if (
+        (role === 'StaticText' || role === 'InlineTextBox') &&
+        typeof node.name?.value === 'string' &&
+        node.name.value.length > 0 &&
+        duplicateParentText
+      ) {
+        continue;
+      }
     }
     records.push({
       role,
-      name: node.name?.value ?? '',
+      name: nameOf(node),
       backendNodeId: node.backendDOMNodeId ?? null,
     });
   }
-  return records;
+  return opts.name === undefined
+    ? records
+    : records.filter((record) => record.name.toLowerCase().includes(opts.name!.toLowerCase()));
 }
 
 /**
@@ -99,10 +131,10 @@ export async function collectElements(
  */
 export function buildElementsResult(
   records: readonly ElementRecord[],
-  opts: { all: boolean; limit: number },
+  opts: { all: boolean; limit: number; name?: string },
 ): RenderableResult {
   const total = records.length;
-  const shown = records.slice(0, opts.limit);
+  const shown = selectRecords(records, { limit: opts.limit }, opts.limit);
 
   const rows = shown.map((r) =>
     r.backendNodeId !== null
@@ -118,10 +150,10 @@ export function buildElementsResult(
 
   return {
     tag: 'elements',
-    attrs: { scope: opts.all ? 'all' : 'interactive', count: total },
+    attrs: { scope: opts.all ? 'all' : 'interactive', count: total, 'name-filter': opts.name },
     summary: opts.all
-      ? fact`${total} elements in the exposed accessibility tree`
-      : fact`${total} interactive elements`,
+      ? opts.name === undefined ? fact`${total} elements in the exposed accessibility tree` : fact`${total} elements in the exposed accessibility tree with accessible name containing ${opts.name}`
+      : opts.name === undefined ? fact`${total} interactive elements` : fact`${total} interactive elements with accessible name containing ${opts.name}`,
     sections,
     followUp: text`capture page click <target> · capture measure map ax <url|snap>`,
   };
@@ -144,11 +176,11 @@ export async function cmdPageElements(parsed: ParsedArgs, _args: string[]): Prom
 
   const records = await withConnection(
     parsed,
-    (client) => collectElements(client, { all: parsed.all }),
+    (client) => collectElements(client, { all: parsed.all, name: parsed.name }),
     { settle: 0 },
   );
 
-  emitResult(buildElementsResult(records, { all: Boolean(parsed.all), limit }), {
+  emitResult(buildElementsResult(records, { all: Boolean(parsed.all), limit, name: parsed.name }), {
     json: parsed.json,
   });
 }