@crouton-kit/capture 1.3.8 → 1.3.10

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

@@ -1,27 +1,152 @@
 import { type ParsedArgs } from '../../types.js';
-import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+import {
+  ArtifactResolutionError,
+  resolveRecRef,
+} from '../../../output/artifact.js';
+import {
+  MotionTimelineSelectionError,
+  analyzeMotionTimeline,
+  readTimelineMeta,
+} from '../../motion/timeline.js';
+import {
+  emitResult,
+  fact,
+  formatArtifactList,
+  line,
+  lineList,
+  text,
+  type FactLine,
+  type RenderableResult,
+} from '../../../output/render.js';
 
-const USAGE = `Usage: capture motion timeline <rec> --element <sel> [--prop <prop>]
+const USAGE = `capture motion timeline <rec> --element <sel> — per-frame geometry/scroll/property timeline for one element across a finalized recording
 
-Per-frame geometry/scroll/property values for one element across a
-finalized recording.
-
-Options:
-  --element <sel>   Element selector to track (required)
-  --prop <prop>     Additional CSS/computed property to sample per frame
-
-Not yet implemented.`;
+input:
+  <rec>             recording id in the active session or an absolute recording path (required; the recording must be finalized)
+  --element <sel>   element selector to track (required): a tag, #id, .class, or their simple combination; descendant/child/sibling combinators, pseudo-classes, and attribute selectors are not supported — the recording retains no DOM tree, so the selector is matched against sampled bounding boxes only
+  --prop <prop>     report one sampled geometry, scroll, or recorded property per frame
+output: <timeline …> — per-frame bounding-box geometry, sampled scroll offsets, and optional sampled property values; the recorder samples bounding boxes, not DOM quads, and frame-derived timestamps carry ±1-frame uncertainty; --json mirrors
+effects: read-only — reads the finalized recording artifact, never drives the browser`;
 
 export async function cmdMotionTimeline(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
-    process.exit(0);
+    return;
+  }
+
+  const recArg = parsed.positional[0];
+  if (!recArg || parsed.positional.length !== 1 || !parsed.element?.trim()) {
+    return emitCommandError(
+      parsed,
+      'invalid_input',
+      'Expected exactly one recording id/path and a non-empty --element selector.',
+      'capture motion timeline <rec> --element <sel> [--prop <prop>]',
+    );
+  }
+
+  try {
+    const ref = resolveRecRef(recArg);
+    const meta = readTimelineMeta(ref);
+    const timeline = analyzeMotionTimeline(ref, parsed.element, parsed.prop);
+    if (parsed.prop && !timeline.propertyAvailable) {
+      return emitCommandError(
+        parsed,
+        'property_unavailable',
+        `The recording has no sampled value for property ${JSON.stringify(parsed.prop)} on the selected element. rects.jsonl records bounding boxes and only includes scroll/property values when the recorder sampled them.`,
+        `Re-run without --prop for bounding-box geometry, or record with a substrate that samples ${JSON.stringify(parsed.prop)}.`,
+        ref,
+        meta.state,
+      );
+    }
+
+    const rows = timeline.points.map((point) => formatPoint(point, parsed.prop));
+    const result: RenderableResult = {
+      tag: 'timeline',
+      attestation: {
+        kind: 'recording',
+        id: ref.id,
+        path: ref.dir,
+        note: timeline.timingDomain === 'screencast-relative'
+          ? text`Times are milliseconds from the first screencast frame; each is frame-derived (±1 frame), not an exact performance.now() timestamp.`
+          : text`Screencast timestamps were unavailable; rows are ordered by sampled frame and have frame-derived timing uncertainty.`,
+      },
+      attrs: {
+        state: meta.state,
+        frames: timeline.frameCount,
+        samples: timeline.points.length,
+        element: parsed.element,
+        prop: parsed.prop,
+        'timestamp-uncertainty': '±1 frame',
+        geometry: 'bounding-box',
+      },
+      summary: fact`${timeline.points.length} sampled frame(s) matched selector ${parsed.element}; identity continuity uses ${timeline.selectionMethod}. ${timeline.eventsRead} event record(s) were read with the recording.`,
+      artifacts: formatArtifactList([
+        { name: 'rects.jsonl', note: 'per-frame sampled bounding boxes and optional scroll/property values' },
+        { name: 'events.jsonl', note: `${timeline.eventsRead} recording event records read` },
+        { name: 'markers.json', note: 'clock baseline provenance' },
+        { 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.`,
+    };
+    emitResult(result, { json: parsed.json });
+  } catch (err) {
+    if (err instanceof MotionTimelineSelectionError) {
+      return emitCommandError(
+        parsed,
+        'element_not_found',
+        err.message,
+        'Pass a tag, #id, .class, or simple tag/id/class combination that appears in rects.jsonl.',
+      );
+    }
+    if (err instanceof ArtifactResolutionError) {
+      return emitCommandError(parsed, 'artifact_unavailable', err.message, err.creatingCommand ?? 'Create a finalized recording, then re-run this query.');
+    }
+    return emitCommandError(parsed, 'timeline_failed', err instanceof Error ? err.message : String(err), 'Inspect the finalized recording artifacts and re-run the query.');
   }
+}
+
+function formatPoint(
+  point: ReturnType<typeof analyzeMotionTimeline>['points'][number],
+  requestedProp?: string,
+): FactLine {
+  const time = point.timeMs === null ? fact`frame=${point.frame}` : fact`t=${point.timeMs.toFixed(1)}ms frame=${point.frame}`;
+  const geometry = fact`x=${point.x} y=${point.y} w=${point.width} h=${point.height}`;
+  const scroll: FactLine[] = [];
+  if (point.scrollTop !== undefined) scroll.push(fact`scrollTop=${point.scrollTop}`);
+  if (point.scrollLeft !== undefined) scroll.push(fact`scrollLeft=${point.scrollLeft}`);
+  const prop = point.property
+    ? fact`${point.property.name}=${String(point.property.value)}`
+    : requestedProp
+      ? text`property=not-sampled`
+      : text``;
+  return line(time, text` · `, geometry, ...(scroll.length ? [text` · `, line(...joinWithSeparator(scroll))] : []), text` · `, prop, text` · timestamp uncertainty ±1 frame`);
+}
+
+function joinWithSeparator(parts: readonly FactLine[]): FactLine[] {
+  const out: FactLine[] = [];
+  parts.forEach((part, index) => {
+    if (index) out.push(text` `);
+    out.push(part);
+  });
+  return out;
+}
+
+function emitCommandError(
+  parsed: ParsedArgs,
+  status: string,
+  message: string,
+  recovery: string,
+  ref?: { id: string; dir: string },
+  state?: string,
+): void {
   const result: RenderableResult = {
     tag: 'error',
-    attrs: { command: 'motion timeline', status: 'not_implemented' },
-    summary: fact`\`motion timeline\` is not implemented yet.`,
+    ...(ref ? { attestation: { kind: 'recording' as const, id: ref.id, path: ref.dir } } : {}),
+    attrs: { command: 'motion timeline', status, state },
+    summary: fact`${message}`,
+    sections: [fact`Recovery: ${recovery}`],
   };
   emitResult(result, { json: parsed.json });
-  process.exit(1);
+  process.exitCode = 1;
 }

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

@@ -0,0 +1,194 @@
+/**
+ * `page click <target>` — dispatch one real click on exactly one live-resolved
+ * element (design D3).
+ *
+ * This file also owns the small substrate the three input-dispatching page
+ * verbs (`click`, `type`, `scroll`) share: the test-injectable dependency
+ * seam, the active-session-keyed settle defaults (Resolved 2), and the
+ * structured rendering of `resolveLiveTarget` failures (candidate list +
+ * `backend:<id>` recovery, `text:` prefix rejection). `type.ts` and
+ * `scroll.ts` import these rather than duplicating them.
+ */
+import { type ParsedArgs } from '../../types.js';
+import { withPageAction } from '../../connection.js';
+import { autoScreenshot } from '../../screenshot.js';
+import { getActiveSession } from '../../../session-context.js';
+import {
+  resolveLiveTarget,
+  clickResolved,
+  type LiveClient,
+  type ResolutionFailure,
+} from '../../../interact.js';
+import {
+  emitResult,
+  fact,
+  line,
+  lineList,
+  text,
+  data,
+  type FactLine,
+} from '../../../output/render.js';
+
+// ---------------------------------------------------------------------------
+// Shared substrate for the three input-dispatching page verbs
+// ---------------------------------------------------------------------------
+
+export interface PageInputDeps {
+  withPageAction: typeof withPageAction;
+  getActiveSession: typeof getActiveSession;
+  autoScreenshot: typeof autoScreenshot;
+}
+
+let deps: PageInputDeps = { withPageAction, getActiveSession, autoScreenshot };
+
+/** Swap the connection/session/screenshot seams for the CDP-stub tests. */
+export function __setPageInputDepsForTest(overrides: Partial<PageInputDeps>): () => void {
+  const previous = deps;
+  deps = { ...deps, ...overrides };
+  return () => { deps = previous; };
+}
+
+export function pageInputDeps(): PageInputDeps {
+  return deps;
+}
+
+/**
+ * The verb's settle window: `--settle <ms>` (including 0) wins outright;
+ * otherwise the default is keyed off active-session presence (the in-session
+ * bump exists so the session HAR captures the network the action triggers).
+ */
+export function effectiveSettle(
+  parsed: ParsedArgs,
+  defaults: { standalone: number; session: number },
+): number {
+  if (parsed.settle !== undefined) return parsed.settle;
+  return deps.getActiveSession() !== null ? defaults.session : defaults.standalone;
+}
+
+/** Structured `<error>` for a plain invalid-invocation case (exit 1). */
+export function emitInvalidInput(parsed: ParsedArgs, command: string, summary: FactLine, followUp?: FactLine): void {
+  emitResult(
+    { tag: 'error', attrs: { command, code: 'invalid_input' }, summary, followUp },
+    { json: parsed.json },
+  );
+  process.exitCode = 1;
+}
+
+/**
+ * Structured `<error>` for a live-resolution failure (exit 1): zero/many
+ * matches carry the candidate list (role, name, `backend:<id>`) as the
+ * recovery payload; a `text:` target names the accepted prefixes.
+ */
+export function emitResolutionError(parsed: ParsedArgs, command: string, failure: ResolutionFailure): void {
+  if (failure.code === 'unsupported-prefix') {
+    emitResult(
+      {
+        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>.`,
+        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 },
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const code = failure.code === 'no-match' ? 'no_match' : 'ambiguous_target';
+  const candidateRows: FactLine[] = failure.candidates.map((c) =>
+    line(data(c.role ?? 'unknown'), text` "`, data(c.name ?? ''), text`" — backend:`, data(c.backendNodeId)),
+  );
+  const sections: FactLine[] = [];
+  if (candidateRows.length > 0) {
+    const shown =
+      failure.matchCount > failure.candidates.length
+        ? fact`candidates (first ${failure.candidates.length} of ${failure.matchCount}):`
+        : text`candidates:`;
+    sections.push(lineList([shown, ...candidateRows]));
+  }
+  emitResult(
+    {
+      tag: 'error',
+      attrs: { command, code },
+      summary: fact`received: target \`${failure.input}\` matched ${failure.matchCount} live elements; expected exactly one.`,
+      sections,
+      followUp:
+        failure.code === 'no-match'
+          ? text`Run \`capture page elements\` to list live targets with their backend:<id> keys.`
+          : fact`Retry \`${command}\` with \`backend:<id>\` from the candidate list.`,
+    },
+    { json: parsed.json },
+  );
+  process.exitCode = 1;
+}
+
+// ---------------------------------------------------------------------------
+// page click
+// ---------------------------------------------------------------------------
+
+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.
+  --settle <ms>     network-settle window applied after the click (default: 1000; 2500 with an active session; 0 disables)
+  --no-screenshot   skip the auto-screenshot
+output:
+  <clicked backend-node-id=… role=… name=…> — resolved identity, dispatched coordinates, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+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`;
+
+export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  const target = parsed.positional[0];
+  if (!target || parsed.positional.length !== 1) {
+    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>).`,
+    );
+  }
+
+  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
+  // a routed click's landmark stays `click:<target>`.
+  const { result: outcome, settle: settleFacts } = await deps.withPageAction(
+    { ...parsed, command: 'click' },
+    { settleMs: settle },
+    async (client) => {
+      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 screenshot = await deps.autoScreenshot(client, 'click', target, parsed.noScreenshot);
+      return { dispatch, screenshot } as const;
+    },
+  );
+
+  if ('failure' in outcome) {
+    return emitResolutionError(parsed, 'page click', outcome.failure);
+  }
+
+  const { dispatch, screenshot } = outcome;
+  const rows: FactLine[] = [
+    fact`clicked ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) at x=${dispatch.x} y=${dispatch.y}`,
+    fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
+  ];
+  if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+
+  emitResult(
+    {
+      tag: 'clicked',
+      attrs: {
+        'backend-node-id': dispatch.backendNodeId,
+        role: dispatch.role ?? undefined,
+        name: dispatch.name ?? undefined,
+      },
+      summary: lineList(rows),
+    },
+    { json: parsed.json },
+  );
+}

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

@@ -0,0 +1,154 @@
+/**
+ * `page elements` — the live targeting navigator (the D1 split's first
+ * half): what can be acted on in the live tab right now, selection-shaped
+ * for the next `page` call.
+ *
+ * Default lists interactive elements only; every record carries the three
+ * discriminators the next `page click`/`type` needs — role, accessible
+ * name, `backendNodeId` (I-3) — straight from the live
+ * `Accessibility.getFullAXTree` fetch. `--all` widens to the full exposed
+ * tree. There is no computed-CSS-selector field: `backend:<id>` is the
+ * canonical retry/targeting key (D1).
+ *
+ * Read-only: the AX fetch is CDP-side — no page-observable writes (I-1/
+ * I-2). During a live composed recording the connection routes through the
+ * recorder unmarked (no input landmark — this leaf dispatches no input).
+ * A truncated list states the total as an explicit `elements-truncated`
+ * fact (I-5); "0 interactive elements" is itself the measurement (I-8).
+ */
+import { type ParsedArgs } from '../../types.js';
+import { invalidInput } from '../../../errors.js';
+import { withConnection } from '../../connection.js';
+import { INTERACTIVE_ROLES, readFullAXTree } from '../../a11y.js';
+import {
+  emitResult,
+  fact,
+  text,
+  lineList,
+  type FactLine,
+  type RenderableResult,
+} from '../../../output/render.js';
+
+/** `--limit` default (Resolved 4): keeps the list selection-shaped on dense
+ * pages while covering normal pages untruncated. */
+export const DEFAULT_LIMIT = 100;
+
+const USAGE = `capture page elements — list what can be acted on in the live tab: role, accessible name, backend:<id> per element.
+
+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)
+  --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
+  --json              mirror the result as JSON
+
+Output:
+  <elements scope="interactive|all" count=<total>> — one row per element: role "name" backend:<id>
+
+Effects: read-only — the accessibility fetch is CDP-side, no page-observable writes; routes unmarked through an active composed recording.`;
+
+/** The minimal CDP surface this leaf reads through — `CDPClient` and the
+ * recorder-held adapter both satisfy it structurally. */
+export interface ElementsClient {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+/** One listed element. `backendNodeId` is always present on the default
+ * (interactive) records — the drivability discriminator — and `null` only
+ * for `--all` tree nodes the browser exposes without a DOM node. */
+export interface ElementRecord {
+  readonly role: string;
+  readonly name: string;
+  readonly backendNodeId: number | null;
+}
+
+/**
+ * Fetches the live AX tree and flattens it to element records in document
+ * order. Default keeps interactive roles with a `backendNodeId` (the
+ * actionable set); `all` keeps every non-ignored node with a role. Pure
+ * CDP reads — no page-observable calls.
+ */
+export async function collectElements(
+  client: ElementsClient,
+  opts: { all?: boolean } = {},
+): Promise<ElementRecord[]> {
+  const nodes = await readFullAXTree(client);
+
+  const records: ElementRecord[] = [];
+  for (const node of nodes) {
+    if (node.ignored) continue;
+    const role = node.role?.value ?? '';
+    if (!role) continue;
+    if (!opts.all) {
+      if (!INTERACTIVE_ROLES.has(role)) continue;
+      if (node.backendDOMNodeId === undefined) continue;
+    }
+    records.push({
+      role,
+      name: node.name?.value ?? '',
+      backendNodeId: node.backendDOMNodeId ?? null,
+    });
+  }
+  return records;
+}
+
+/**
+ * Assembles the `<elements>` result. Every page-derived value (role, name)
+ * flows through the `fact` interpolation lane — escaped and capped (I-9).
+ * Truncation is an explicit fact carrying the total count (I-5); an empty
+ * list renders count 0 with no advice (I-8).
+ */
+export function buildElementsResult(
+  records: readonly ElementRecord[],
+  opts: { all: boolean; limit: number },
+): RenderableResult {
+  const total = records.length;
+  const shown = records.slice(0, opts.limit);
+
+  const rows = shown.map((r) =>
+    r.backendNodeId !== null
+      ? fact`${r.role} "${r.name}" backend:${r.backendNodeId}`
+      : fact`${r.role} "${r.name}"`,
+  );
+
+  const sections: FactLine[] = [];
+  if (rows.length > 0) sections.push(lineList(rows));
+  if (total > shown.length) {
+    sections.push(fact`elements-truncated: listing capped at ${shown.length} of ${total} elements (--limit)`);
+  }
+
+  return {
+    tag: 'elements',
+    attrs: { scope: opts.all ? 'all' : 'interactive', count: total },
+    summary: opts.all
+      ? fact`${total} elements in the exposed accessibility tree`
+      : fact`${total} interactive elements`,
+    sections,
+    followUp: text`capture page click <target> · capture measure map ax <url|snap>`,
+  };
+}
+
+export async function cmdPageElements(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  // Positional cardinality (exactly 0) is enforced by `validateCliInvocation`
+  // before dispatch reaches this leaf; this guard covers direct programmatic
+  // callers only. Failures cross the boundary as typed CaptureErrors —
+  // capture.ts is the sole renderer/exit-status owner.
+  const limit = parsed.limit ?? DEFAULT_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw invalidInput(`received: --limit ${String(parsed.limit)}; expected: a positive integer.`, 'invalid_flag');
+  }
+
+  const records = await withConnection(
+    parsed,
+    (client) => collectElements(client, { all: parsed.all }),
+    { settle: 0 },
+  );
+
+  emitResult(buildElementsResult(records, { all: Boolean(parsed.all), limit }), {
+    json: parsed.json,
+  });
+}