@crouton-kit/capture 1.4.2 → 1.4.11

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

@@ -21,7 +21,7 @@
  */
 import { connectForCommand, withPageAction, type SettleFacts } from '../../connection.js';
 import { EventBroker } from '../../bridge/server.js';
-import { isRecorderHeldClient, type RecorderHeldClient } from '../../recorder-client.js';
+import { isMotionHeldClient, type MotionHeldClient } from '../../host/held-client.js';
 import { type CDPClient } from '../../client.js';
 import { type ParsedArgs } from '../../types.js';
 import { CaptureError, captureError, invalidInput } from '../../../errors.js';
@@ -60,12 +60,15 @@ picks which tab navigates. Navigate never creates a tab — use "tab open" for
 that; an unresolvable source is a targeting error, not a new tab.
 
 Output:
-  One <navigated url=… settle=… load-outcome=… deadline-exceeded=…> block:
+  One <navigated url=… settle=… load-outcome=… document-outcome=… deadline-exceeded=…> block:
   the tab URL after navigation, the measured settle, and — reported
-  separately — the load outcome (observed | bounded-timeout), whether the
-  nav phase exceeded its deadline, the dispatched navigation's loaderId (and
+  separately — the load outcome (observed | bounded-timeout), the document/network
+  outcome (http-response | http-error-document | not-observed; the latter has no
+  document status or URL), whether the nav phase exceeded its deadline, the
+  dispatched navigation's loaderId (and
   any about:blank bounce for a same-document target), and whether the CDP
-  routed through an active recording. --json mirrors the same fields.
+  routed through an active recording. A document HTTP error does not change the
+  navigation dispatch or load outcome. --json mirrors the same fields.
 
 Effects:
   Navigates the source tab (exactly one Page.navigate for the destination;
@@ -78,8 +81,13 @@ Effects:
 /** Load outcome plus the dispatched navigation's own facts, produced by one
  * navigation core (recorder-routed or direct). Distinct fields so the render
  * layer can report the load result separately from the method result. */
+type DocumentOutcome =
+  | { kind: 'http-response' | 'http-error-document'; status: number; url: string }
+  | { kind: 'not-observed' };
+
 interface NavCore {
   loadOutcome: 'observed' | 'bounded-timeout';
+  documentOutcome: DocumentOutcome;
   /** The dispatched navigation's loaderId (present on a real cross-document
    * navigation; absent for a same-document target before the bounce). */
   loaderId?: string;
@@ -96,18 +104,23 @@ interface NavCore {
  * target returns no loaderId — recover with exactly one dest→about:blank→dest
  * bounce, bundling the wait only on the final re-navigate.
  */
-async function navigateViaRecorder(client: RecorderHeldClient, url: string): Promise<NavCore> {
-  const first = await client.dispatch('Page.navigate', { url }, LOAD_EVENT_NAME, timing.innerTimeoutMs);
+function documentOutcomeFor(response?: { status: number; url: string }): DocumentOutcome {
+  if (!response) return { kind: 'not-observed' };
+  return { kind: response.status >= 400 ? 'http-error-document' : 'http-response', status: response.status, url: response.url };
+}
+
+async function navigateViaRecorder(client: MotionHeldClient, url: string): Promise<NavCore> {
+  const first = await client.dispatch('Page.navigate', { url }, LOAD_EVENT_NAME, timing.innerTimeoutMs, true);
   const loaderId = (first.result as { loaderId?: string } | undefined)?.loaderId;
   if (loaderId) {
-    return { loadOutcome: first.waitOutcome ?? 'bounded-timeout', loaderId, bounced: false };
+    return { loadOutcome: first.waitOutcome ?? 'bounded-timeout', documentOutcome: documentOutcomeFor(first.documentResponse), loaderId, bounced: false };
   }
   // Same-document target: the destination is already committed (no loaderId);
   // bounce through about:blank and re-navigate so a fresh document mounts.
   await client.dispatch('Page.navigate', { url: 'about:blank' });
-  const final = await client.dispatch('Page.navigate', { url }, LOAD_EVENT_NAME, timing.innerTimeoutMs);
+  const final = await client.dispatch('Page.navigate', { url }, LOAD_EVENT_NAME, timing.innerTimeoutMs, true);
   const finalLoaderId = (final.result as { loaderId?: string } | undefined)?.loaderId;
-  return { loadOutcome: final.waitOutcome ?? 'bounded-timeout', loaderId: finalLoaderId, bounced: true };
+  return { loadOutcome: final.waitOutcome ?? 'bounded-timeout', documentOutcome: documentOutcomeFor(final.documentResponse), loaderId: finalLoaderId, bounced: true };
 }
 
 /** Arms a bounded `Page.loadEventFired` wait on a direct client's broker and
@@ -134,43 +147,66 @@ function armLoadWait(broker: EventBroker): {
  * exactly one dest→about:blank→dest bounce, re-arming the wait before the
  * final send.
  */
+function observeDocumentResponses(client: CDPClient): { outcomeFor(loaderId?: string): DocumentOutcome; dispose(): void } {
+  const responses: Array<{ loaderId: string; status: number; url: string }> = [];
+  const handler = (params: unknown) => {
+    if (!params || typeof params !== 'object' || Array.isArray(params)) return;
+    const event = params as { type?: unknown; loaderId?: unknown; response?: unknown };
+    if (event.type !== 'Document' || typeof event.loaderId !== 'string' || !event.response || typeof event.response !== 'object' || Array.isArray(event.response)) return;
+    const response = event.response as { status?: unknown; url?: unknown };
+    if (typeof response.status !== 'number' || !Number.isFinite(response.status) || typeof response.url !== 'string') return;
+    responses.push({ loaderId: event.loaderId, status: response.status, url: response.url });
+  };
+  client.on('Network.responseReceived', handler);
+  return {
+    outcomeFor(loaderId) {
+      const response = loaderId === undefined ? undefined : responses.filter((candidate) => candidate.loaderId === loaderId).at(-1);
+      if (!response) return { kind: 'not-observed' };
+      return { kind: response.status >= 400 ? 'http-error-document' : 'http-response', status: response.status, url: response.url };
+    },
+    dispose() { client.off('Network.responseReceived', handler); },
+  };
+}
+
 async function navigateDirect(
   client: CDPClient,
   url: string,
   armed?: { cancel: () => void },
 ): Promise<NavCore> {
   await client.send('Page.enable');
+  await client.send('Network.enable');
+  const documents = observeDocumentResponses(client);
   const broker = new EventBroker(client);
 
-  const first = armLoadWait(broker);
-  // Publish the currently-armed wait's canceller so an outer-deadline
-  // abandonment can clear its inner timer instead of letting it fire on its own.
-  if (armed) armed.cancel = () => first.wait.cancel();
-  let nav: { loaderId?: string } | undefined;
   try {
-    nav = (await client.send('Page.navigate', { url })) as { loaderId?: string };
-  } catch (err) {
-    first.wait.cancel();
-    throw err;
-  }
-  if (nav?.loaderId) {
-    return { loadOutcome: await first.outcome, loaderId: nav.loaderId, bounced: false };
-  }
+    const first = armLoadWait(broker);
+    if (armed) armed.cancel = () => first.wait.cancel();
+    let nav: { loaderId?: string } | undefined;
+    try {
+      nav = (await client.send('Page.navigate', { url })) as { loaderId?: string };
+    } catch (err) {
+      first.wait.cancel();
+      throw err;
+    }
+    if (nav?.loaderId) {
+      return { loadOutcome: await first.outcome, documentOutcome: documents.outcomeFor(nav.loaderId), loaderId: nav.loaderId, bounced: false };
+    }
 
-  // Same-document target: discard the first wait, bounce through about:blank,
-  // re-arm the wait, then re-navigate to the destination.
-  first.wait.cancel();
-  await client.send('Page.navigate', { url: 'about:blank' });
-  const second = armLoadWait(broker);
-  if (armed) armed.cancel = () => second.wait.cancel();
-  let navFinal: { loaderId?: string } | undefined;
-  try {
-    navFinal = (await client.send('Page.navigate', { url })) as { loaderId?: string };
-  } catch (err) {
-    second.wait.cancel();
-    throw err;
+    first.wait.cancel();
+    await client.send('Page.navigate', { url: 'about:blank' });
+    const second = armLoadWait(broker);
+    if (armed) armed.cancel = () => second.wait.cancel();
+    let navFinal: { loaderId?: string } | undefined;
+    try {
+      navFinal = (await client.send('Page.navigate', { url })) as { loaderId?: string };
+    } catch (err) {
+      second.wait.cancel();
+      throw err;
+    }
+    return { loadOutcome: await second.outcome, documentOutcome: documents.outcomeFor(navFinal?.loaderId), loaderId: navFinal?.loaderId, bounced: true };
+  } finally {
+    documents.dispose();
   }
-  return { loadOutcome: await second.outcome, loaderId: navFinal?.loaderId, bounced: true };
 }
 
 /** Races the nav+load phase against the outer deadline. The deadline never
@@ -200,6 +236,7 @@ interface NavigatedFacts {
   tabUrl: string;
   requestedUrl: string;
   loadOutcome: 'observed' | 'bounded-timeout';
+  documentOutcome: DocumentOutcome;
   deadlineExceeded: boolean;
   loaderId?: string;
   bounced: boolean;
@@ -212,6 +249,9 @@ function buildNavigatedResult(f: NavigatedFacts): RenderableResult {
     f.loadOutcome === 'observed'
       ? fact`load: ${LOAD_EVENT_NAME} observed within the ${timing.innerTimeoutMs}ms load-wait window.`
       : fact`load: ${LOAD_EVENT_NAME} not observed within the ${timing.innerTimeoutMs}ms load-wait window (bounded-timeout); the navigation still dispatched.`,
+    f.documentOutcome.kind === 'not-observed'
+      ? fact`document/network outcome: no matching HTTP document response was observed.`
+      : fact`document/network outcome: HTTP ${f.documentOutcome.status} at ${f.documentOutcome.url}${f.documentOutcome.kind === 'http-error-document' ? ' (HTTP error document)' : ''}.`,
     fact`navigation dispatched: loaderId ${f.loaderId ?? '(none)'}${f.bounced ? '; delivered via dest→about:blank→dest bounce (same-document target)' : ''}.`,
     fact`settle: requested ${f.settle.requestedMs}ms, waited ${f.settle.waitedMs}ms.`,
   ];
@@ -229,6 +269,9 @@ function buildNavigatedResult(f: NavigatedFacts): RenderableResult {
       url: f.tabUrl,
       settle: f.settle.requestedMs,
       'load-outcome': f.loadOutcome,
+      'document-outcome': f.documentOutcome.kind,
+      'document-status': f.documentOutcome.kind === 'not-observed' ? undefined : f.documentOutcome.status,
+      'document-url': f.documentOutcome.kind === 'not-observed' ? undefined : f.documentOutcome.url,
       'deadline-exceeded': f.deadlineExceeded || undefined,
       routed: f.routed || undefined,
     },
@@ -276,12 +319,12 @@ export async function cmdPageNavigate(parsed: ParsedArgs, _args: string[]): Prom
     { ...parsed, command: 'navigate' },
     { settleMs: settle },
     async (client, _tab) => {
-      const routed = isRecorderHeldClient(client);
+      const routed = isMotionHeldClient(client);
       // Holder for the direct path's currently-armed load wait, so an
       // outer-deadline abandonment can cancel it (clearing its inner timer).
       const armed = { cancel: () => {} };
       const work = routed
-        ? navigateViaRecorder(client as unknown as RecorderHeldClient, url)
+        ? navigateViaRecorder(client as unknown as MotionHeldClient, url)
         : navigateDirect(client, url, armed);
       let raced: Awaited<ReturnType<typeof raceNavDeadline>>;
       try {
@@ -305,6 +348,7 @@ export async function cmdPageNavigate(parsed: ParsedArgs, _args: string[]): Prom
       armed.cancel();
       return {
         loadOutcome: 'bounded-timeout' as const,
+        documentOutcome: { kind: 'not-observed' } as const,
         loaderId: undefined,
         bounced: false,
         deadlineExceeded: true,
@@ -319,6 +363,7 @@ export async function cmdPageNavigate(parsed: ParsedArgs, _args: string[]): Prom
       tabUrl: core.tabUrl,
       requestedUrl: url,
       loadOutcome: core.loadOutcome,
+      documentOutcome: core.documentOutcome,
       deadlineExceeded: core.deadlineExceeded,
       loaderId: core.loaderId,
       bounced: core.bounced,

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

@@ -0,0 +1,176 @@
+import { type ParsedArgs } from '../../types.js';
+import { resolveLiveTarget, clickResolved, focusAndType, typeText, type ClickDispatch, type LiveClient, type ResolutionFailure } from '../../../interact.js';
+import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
+import { effectiveSettle, emitInvalidInput, pageInputDeps } from './click.js';
+
+const MAX_STEPS = 20;
+const MAX_ITERATIONS = 100;
+
+const USAGE = `capture page repeat --steps <json> --iterations <n> [--settle <ms>] — repeat one bounded declarative click/type sequence
+
+input:
+  --steps <json>       required JSON array of 1..${MAX_STEPS} action objects, in order: {"action":"click","target":"<live target>"} or {"action":"type","text":"<text>","into":"<live target>"}; type omits into to insert into the focused element
+  --iterations <n>     required repeat count from 1 to ${MAX_ITERATIONS}
+  --settle <ms>        network-settle window applied after each completed sequence (default: 1000; 2500 with an active session; 0 disables)
+  --target <tabId> | --url <pattern> | --port <n>  tab targeting; defaults to the active session tab
+output:
+  <repeated iterations=… steps=…> — one factual completion record per iteration with step action, resolved identity when applicable, dispatch coordinates, elapsed duration, and measured requested/waited settle
+effects:
+  drives every click through the same live target resolution and real mouse dispatch as page click, and every type through the same focused/targeted real text insertion as page type; each completed iteration receives its own action lifecycle and settle window; no automatic screenshots are written`;
+
+type RepeatStep =
+  | { readonly action: 'click'; readonly target: string }
+  | { readonly action: 'type'; readonly text: string; readonly into?: string };
+
+interface ActionRecord {
+  readonly action: 'click' | 'type';
+  readonly target?: string;
+  readonly text?: string;
+  readonly backendNodeId?: number;
+  readonly role?: string;
+  readonly name?: string;
+  readonly x?: number;
+  readonly y?: number;
+  readonly focused?: boolean;
+  readonly hitTestReceiverBackendNodeId?: number;
+}
+
+interface FailureRecord {
+  readonly code: string;
+  readonly target: string;
+  readonly matches?: number;
+}
+
+interface IterationRecord {
+  readonly iteration: number;
+  readonly completion: 'completed' | 'failed';
+  readonly durationMs: number;
+  readonly settle?: { readonly requestedMs: number; readonly waitedMs: number };
+  readonly actions: readonly ActionRecord[];
+  readonly failure?: FailureRecord;
+}
+
+class RepeatResolutionFailure extends Error {
+  constructor(readonly failure: ResolutionFailure, readonly actions: readonly ActionRecord[]) {
+    super('page repeat target resolution did not complete.');
+  }
+}
+
+function parseSteps(raw: string | undefined): RepeatStep[] | null {
+  if (raw === undefined || raw.length > 10_000) return null;
+  try {
+    const value = JSON.parse(raw) as unknown;
+    if (!Array.isArray(value) || value.length < 1 || value.length > MAX_STEPS) return null;
+    const out: RepeatStep[] = [];
+    for (const valueStep of value) {
+      if (!valueStep || typeof valueStep !== 'object' || Array.isArray(valueStep)) return null;
+      const step = valueStep as Record<string, unknown>;
+      if (step.action === 'click' && Object.keys(step).length === 2 && typeof step.target === 'string' && step.target.length > 0) {
+        out.push({ action: 'click', target: step.target });
+      } else if (step.action === 'type' && Object.keys(step).every(key => key === 'action' || key === 'text' || key === 'into') && typeof step.text === 'string' && (step.into === undefined || (typeof step.into === 'string' && step.into.trim().length > 0))) {
+        out.push({ action: 'type', text: step.text, ...(typeof step.into === 'string' ? { into: step.into } : {}) });
+      } else return null;
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+function actionRecord(action: 'click' | 'type', dispatch: ClickDispatch, target: string, text?: string): ActionRecord {
+  return {
+    action,
+    target,
+    ...(text === undefined ? {} : { text }),
+    backendNodeId: dispatch.backendNodeId,
+    ...(dispatch.role === null ? {} : { role: dispatch.role }),
+    ...(dispatch.name === null ? {} : { name: dispatch.name }),
+    x: dispatch.x,
+    y: dispatch.y,
+    ...(action === 'type' ? { focused: true } : {}),
+    ...(dispatch.hitTestReceiverBackendNodeId === undefined ? {} : { hitTestReceiverBackendNodeId: dispatch.hitTestReceiverBackendNodeId }),
+  };
+}
+
+function emitRepeatResult(parsed: ParsedArgs, steps: number, settle: number, records: readonly IterationRecord[], completion: 'completed' | 'partial'): void {
+  const sections: FactLine[] = records.map(record => lineList([
+    record.completion === 'completed'
+      ? fact`iteration ${record.iteration} completed in ${record.durationMs.toFixed(1)}ms; settle requested ${record.settle!.requestedMs}ms, waited ${record.settle!.waitedMs}ms.`
+      : fact`iteration ${record.iteration} did not complete in ${record.durationMs.toFixed(1)}ms; target ${record.failure!.target} resolution returned ${record.failure!.code}${record.failure!.matches === undefined ? '' : ` with ${record.failure!.matches} live matches`}.`,
+    ...record.actions.map(action => action.action === 'click'
+      ? fact`click ${action.target ?? '(unknown)'} → backend:${action.backendNodeId ?? '(unknown)'}${action.role === undefined ? '' : ` role=${action.role}`}${action.name === undefined ? '' : ` name=${action.name}`} at x=${action.x ?? '(unknown)'} y=${action.y ?? '(unknown)'}${action.hitTestReceiverBackendNodeId === undefined ? '' : `; hit-test receiver backend:${action.hitTestReceiverBackendNodeId}`}`
+      : action.backendNodeId === undefined
+        ? fact`type into focused element: ${action.text ?? ''}`
+        : fact`type into ${action.target ?? '(unknown)'} → backend:${action.backendNodeId}${action.role === undefined ? '' : ` role=${action.role}`}${action.name === undefined ? '' : ` name=${action.name}`} at x=${action.x ?? '(unknown)'} y=${action.y ?? '(unknown)'}${action.hitTestReceiverBackendNodeId === undefined ? '' : `; hit-test receiver backend:${action.hitTestReceiverBackendNodeId}`}: ${action.text ?? ''}`),
+  ]));
+  emitResult({
+    tag: 'repeated',
+    attrs: { iterations: records.length, steps, 'settle-ms': settle, completion, ...(completion === 'partial' ? { 'failed-iteration': records.at(-1)!.iteration, 'failure-code': records.at(-1)!.failure!.code } : {}) },
+    summary: completion === 'completed'
+      ? fact`${records.length} iteration(s) completed; each record is one ordered ${steps}-step sequence against the live tab.`
+      : fact`${records.length - 1} iteration(s) completed before iteration ${records.at(-1)!.iteration} did not complete; completed action records remain in this result.`,
+    sections,
+    jsonSections: { iterations: records },
+  }, { json: parsed.json });
+  if (completion === 'partial') process.exitCode = 1;
+}
+
+export async function cmdPageRepeat(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  const steps = parseSteps(parsed.steps);
+  const iterations = parsed.iterations;
+  if (parsed.positional.length !== 0 || steps === null || iterations === undefined || !Number.isSafeInteger(iterations) || iterations < 1 || iterations > MAX_ITERATIONS) {
+    return emitInvalidInput(parsed, 'page repeat', fact`received: ${parsed.positional.length} positional arguments, --steps=${parsed.steps === undefined ? '(missing)' : 'provided'}, --iterations=${String(iterations ?? '(missing)')}; expected no positionals, a JSON array of 1..${MAX_STEPS} click/type step objects, and an iteration count from 1 to ${MAX_ITERATIONS}.`);
+  }
+
+  const deps = pageInputDeps();
+  const settle = effectiveSettle(parsed, { standalone: 1000, session: 2500 });
+  const records: IterationRecord[] = [];
+
+  for (let iteration = 1; iteration <= iterations; iteration++) {
+    const started = performance.now();
+    try {
+      const { result, settle: settleFacts } = await deps.withPageAction(
+        { ...parsed, command: 'repeat' },
+        { settleMs: settle },
+        async (client) => {
+          const live = client as unknown as LiveClient;
+          const actions: ActionRecord[] = [];
+          for (const step of steps) {
+            if (step.action === 'click') {
+              const resolved = await resolveLiveTarget(live, step.target);
+              if (!resolved.ok) throw new RepeatResolutionFailure(resolved, actions);
+              const dispatch = await clickResolved(live, resolved, { inspectHitTest: true, includeHitTestReceiver: true });
+              actions.push(actionRecord('click', dispatch, step.target));
+            } else if (step.into !== undefined) {
+              const resolved = await resolveLiveTarget(live, step.into);
+              if (!resolved.ok) throw new RepeatResolutionFailure(resolved, actions);
+              const dispatch = await focusAndType(live, resolved, step.text, { inspectHitTest: true, includeHitTestReceiver: true });
+              actions.push(actionRecord('type', dispatch, step.into, step.text));
+            } else {
+              await typeText(live, step.text);
+              actions.push({ action: 'type', text: step.text, focused: true });
+            }
+          }
+          return { actions } as const;
+        },
+      );
+      records.push({ iteration, completion: 'completed', durationMs: performance.now() - started, settle: { requestedMs: settleFacts.requestedMs, waitedMs: settleFacts.waitedMs }, actions: result.actions });
+    } catch (error) {
+      if (!(error instanceof RepeatResolutionFailure)) throw error;
+      const failure = error.failure;
+      const failureRecord: FailureRecord = {
+        code: failure.code,
+        target: failure.input,
+        ...('matchCount' in failure ? { matches: failure.matchCount } : {}),
+      };
+      records.push({ iteration, completion: 'failed', durationMs: performance.now() - started, actions: error.actions, failure: failureRecord });
+      return emitRepeatResult(parsed, steps.length, settle, records, 'partial');
+    }
+  }
+
+  emitRepeatResult(parsed, steps.length, settle, records, 'completed');
+}

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

@@ -22,14 +22,15 @@ import {
 const USAGE = `capture page scroll <target> --to <top|bottom|px> — scroll one resolved container to a position
 
 input:
-  <target>          resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required — zero or many matches is a structured error listing candidates
+  <target>          resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required — zero or many matches is a structured error listing candidates. This leaf does not enumerate scroll containers; when the target is unknown, use \`capture measure map scroll\`.
   --to <dest>       required destination: top, bottom, or a pixel offset (scrollTop value)
+  --behavior <instant|smooth> dispatch behavior; instant is the default, smooth waits at most 5000ms for scrollend before reporting the measured offset
   --settle <ms>     network-settle window applied after the scroll (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <scrolled backend-node-id=… role=… name=…> — resolved identity, destination, the container's resulting scrollTop, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
+  <scrolled backend-node-id=… role=… name=…> — resolved identity, destination, scrollTop before/after, the container's maximum scrollTop, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
-  assigns the container's scrollTop in-page (may trigger lazy-load network); writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
+  drives the container's in-page scroll (instant by default; may trigger lazy-load network); writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
 export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
@@ -74,7 +75,7 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
       if (!resolved.ok) return { failure: resolved } as const;
       // Same landmark shape `motion rec --do scroll:` records; carried by
       // the one mutating call when the transport records landmarks.
-      const dispatch = await scrollResolved(live, resolved, to, { mark: `scroll:${target},to=${to}` });
+      const dispatch = await scrollResolved(live, resolved, to, { mark: `scroll:${target},to=${to}`, behavior: parsed.behavior ?? 'instant' });
       const screenshotResult = await capturePageInputScreenshot(client, 'scroll', target, parsed.noScreenshot);
       return { dispatch, ...screenshotResult } as const;
     },
@@ -86,7 +87,8 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
 
   const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows: FactLine[] = [
-    fact`scrolled ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) to ${dispatch.to} — scrollTop now ${dispatch.scrollTop}`,
+    fact`scrolled ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) to ${dispatch.to} — scrollTop ${dispatch.scrollTopBefore} → ${dispatch.scrollTop} within 0…${dispatch.maxScrollTop}`,
+    fact`traversed ${Math.abs(dispatch.scrollTop - dispatch.scrollTopBefore)} CSS px of the container's ${dispatch.maxScrollTop} CSS px vertical range`,
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
@@ -100,7 +102,10 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
         role: dispatch.role ?? undefined,
         name: dispatch.name ?? undefined,
         to: dispatch.to,
+        'scroll-top-before': dispatch.scrollTopBefore,
         'scroll-top': dispatch.scrollTop,
+        'max-scroll-top': dispatch.maxScrollTop,
+        'scroll-range-traversed': Math.abs(dispatch.scrollTop - dispatch.scrollTopBefore),
       },
       summary: lineList(rows),
     },