browser-commander 0.29.0 → 0.30.0

package/src/traces/recorder.js

@@ -16,10 +16,13 @@ import { openTraceLinks } from './links.js';
 import { createTraceIdentity } from './identity.js';
 import { withDeadline } from './deadline.js';
 import { createMutationStream } from './mutation-stream.js';
-import { attachTimelineObservers } from './observers.js';
+import { createUserActionStream } from './user-actions.js';
+import { startTraceDrain } from './drain-timer.js';
+import { attachRecorderObservers } from './observers.js';
 import { attachNetwork, validateNetworkOptions } from './network.js';
 import { startRecording } from '../capture/recording.js';
 import { normalizePrivacyOptions, redactValue } from './redaction.js';
+import path from 'node:path';
 import {
   DEFAULT_CAPTURE_TIMEOUT,
   TRACE_CHECKPOINT_REASON,
@@ -94,13 +97,19 @@ function normalizeTraceOptions(options) {
   return {
     ...options,
     page: options.page ?? options.commander?.page,
-    mode: options.mode ?? TRACE_MODE.CHECKPOINTS,
+    mode: options.mode ?? TRACE_MODE.CONTINUOUS,
     screenshots: options.screenshots ?? 'checkpoints',
     dom: options.dom ?? {},
     privacy: options.privacy ?? {},
     limits: options.limits ?? {},
-    links: options.links ?? null,
-    network: options.network ?? false,
+    links:
+      options.links === false || options.links === null
+        ? null
+        : (options.links ?? {
+            output: path.join(options.output ?? '', 'trace.lino'),
+            dom: 'full',
+          }),
+    network: options.network ?? { har: true },
     strict: options.strict ?? false,
     captureTimeoutMs: options.captureTimeoutMs ?? DEFAULT_CAPTURE_TIMEOUT,
     commanderVersion: options.commanderVersion ?? null,
@@ -110,6 +119,7 @@ function normalizeTraceOptions(options) {
 }
 
 export async function startTrace(options = {}) {
+  options = normalizeTraceOptions(options);
   if (options.limits?.rotate) {
     const { startRollingTrace } = await import('./rolling.js');
     return startRollingTrace(options, startTrace);
@@ -151,8 +161,8 @@ export async function startTrace(options = {}) {
   // Otherwise a rejected start (for example `links: {}`) strands the bundle's
   // events handle because no running trace is returned for the caller to stop.
   validateLinksOptions(links);
-  const engine = commander?.engine ?? null;
-  const identity = createTraceIdentity({ page });
+  const engine = commander?.engine ?? null,
+    identity = createTraceIdentity({ page });
 
   // A continuous trace records changes, and a change is only meaningful against
   // something. Taking the base snapshot automatically is the safe default,
@@ -243,6 +253,18 @@ export async function startTrace(options = {}) {
     captureTimeoutMs,
     evaluateInPage,
   });
+  const userActions = createUserActionStream({
+    page,
+    record,
+    identity,
+    note,
+    privacyOptions,
+    limits,
+    enabled: eventSources.includes('interaction'),
+    ignoreSelectors: domOptions.ignoreSelectors,
+    evaluateInPage,
+    captureTimeoutMs,
+  });
 
   async function screenshot(reason) {
     const wanted =
@@ -289,7 +311,7 @@ export async function startTrace(options = {}) {
     detachNetwork = async () => {},
     video = null;
   try {
-    detachers = attachTimelineObservers({
+    const observers = attachRecorderObservers({
       commander,
       page,
       eventSources,
@@ -298,6 +320,7 @@ export async function startTrace(options = {}) {
       identity,
       now,
     });
+    detachers = observers.detachers;
     detachNetwork = attachNetwork({
       page,
       network,
@@ -344,7 +367,11 @@ export async function startTrace(options = {}) {
       events: eventSources,
       initialCheckpoint: Boolean(baseCheckpoint),
     });
-    await mutations.install();
+    await Promise.all([mutations.install(), userActions.install()]);
+    detachers.push(async () => {
+      await userActions.drain();
+      await userActions.stop();
+    });
 
     if (baseCheckpoint) {
       await checkpoint(
@@ -356,23 +383,10 @@ export async function startTrace(options = {}) {
       );
     }
 
-    let drainTask;
-    if (domOptions.mutations) {
-      const timer = setInterval(() => {
-        if (!drainTask) {
-          drainTask = mutations
-            .drain(captureState.index)
-            .catch((error) => note(error.message))
-            .finally(() => {
-              drainTask = null;
-            });
-        }
-      }, 500);
-      timer.unref?.();
-      detachers.push(async () => {
-        clearInterval(timer);
-        await drainTask;
-      });
+    if (domOptions.mutations || eventSources.includes('interaction')) {
+      detachers.push(
+        startTraceDrain({ mutations, userActions, captureState, note })
+      );
     }
 
     /**
@@ -424,6 +438,7 @@ export async function startTrace(options = {}) {
         return bundle.bytesWritten;
       },
       checkpoint,
+      attachCommander: observers.attachCommander,
       /**
        * Record an event a caller cares about on the same timeline.
        *
@@ -460,6 +475,12 @@ export async function startTrace(options = {}) {
 
 function requireTraceSupport(options) {
   validateNetworkOptions(options.network);
+  const maxQueued = options.limits.maxQueuedUserActions ?? 5000;
+  if (!Number.isSafeInteger(maxQueued) || maxQueued < 1) {
+    throw new RangeError(
+      'maxQueuedUserActions must be a positive safe integer'
+    );
+  }
   (options.page ?? options.commander?.page)?.requireFeature?.('tracing');
 }
 

package/src/traces/user-actions.js

@@ -0,0 +1,405 @@
+import { withDeadline } from './deadline.js';
+import { framesOf, installInitScript } from './init-script.js';
+import { TRACE_EVENT, TRACE_DROP_REASON } from './schema.js';
+
+const bindings = new WeakMap();
+const USER_ACTION_BINDING = '__browserCommanderUserActionsEmit__';
+
+async function attachBinding(page, route, emit) {
+  if (!page.exposeFunction) {
+    return null;
+  }
+  let binding = bindings.get(page);
+  if (!binding) {
+    const callbacks = new Map();
+    binding = {
+      callbacks,
+      ready: page.exposeFunction(USER_ACTION_BINDING, (id, payload) =>
+        callbacks.get(id)?.(payload)
+      ),
+    };
+    bindings.set(page, binding);
+  }
+  await binding.ready;
+  binding.callbacks.set(route, emit);
+  return () => binding.callbacks.delete(route);
+}
+
+/** Runs in each document. Event descriptions never read control values. */
+export function installUserActionRecorderInPage(options) {
+  const {
+    globalName,
+    binding,
+    maxQueued,
+    redactSelectors,
+    ignoreSelectors,
+    redacted,
+  } = options;
+  if (window[globalName]?.observing) {
+    return;
+  }
+  const state = {
+    observing: true,
+    queue: [],
+    dropped: 0,
+    frameId: `frame-${Math.random().toString(36).slice(2, 10)}`,
+  };
+  const matches = (node, selectors) => {
+    for (let at = node; at; at = at.getRootNode?.()?.host) {
+      if (
+        selectors.some((selector) => {
+          try {
+            return Boolean(at.closest?.(selector));
+          } catch {
+            return false;
+          }
+        })
+      ) {
+        return true;
+      }
+    }
+    return false;
+  };
+  const privateNode = (node) => matches(node, redactSelectors);
+  const pathOf = (node) => {
+    const steps = [];
+    let separator = '';
+    for (let at = node; at?.nodeType === 1 && steps.length < 20;) {
+      const siblings = [...(at.parentElement?.children ?? [])].filter(
+        (child) => child.localName === at.localName
+      );
+      const step = at.id
+        ? `#${window.CSS.escape(at.id)}`
+        : `${at.localName}${siblings.length > 1 ? `:nth-of-type(${siblings.indexOf(at) + 1})` : ''}`;
+      steps.unshift(`${step}${separator}`);
+      if (at.id) {
+        break;
+      }
+      separator = at.parentElement ? ' > ' : ' >>> ';
+      at = at.parentElement ?? at.getRootNode()?.host;
+    }
+    return steps.join('');
+  };
+  const visibleText = (node, depth = 0, budget = { remaining: 500 }) => {
+    if (
+      !node ||
+      depth >= 20 ||
+      --budget.remaining < 0 ||
+      matches(node.nodeType === 1 ? node : node.parentElement, [
+        'input',
+        'textarea',
+        'select',
+        '[contenteditable]',
+        ...ignoreSelectors,
+      ])
+    ) {
+      return '';
+    }
+    if (privateNode(node.nodeType === 1 ? node : node.parentElement)) {
+      return redacted;
+    }
+    if (node.nodeType === 3) {
+      return node.nodeValue ?? '';
+    }
+    if (
+      node.nodeType === 1 &&
+      (!node.getClientRects().length ||
+        window.getComputedStyle(node).visibility === 'hidden')
+    ) {
+      return '';
+    }
+    let text = '';
+    for (const child of node.childNodes ?? []) {
+      text += visibleText(child, depth + 1, budget);
+      if (text.length >= 500) {
+        break;
+      }
+    }
+    return text.slice(0, 500);
+  };
+  const describe = (target) => {
+    const secret = privateNode(target);
+    const text = secret ? redacted : visibleText(target).trim();
+    const labelled = (target.getAttribute('aria-labelledby') ?? '')
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((id) => visibleText(target.getRootNode().getElementById?.(id)))
+      .join(' ')
+      .trim();
+    const label = [...(target.labels ?? [])]
+      .slice(0, 20)
+      .map((node) => visibleText(node))
+      .join(' ')
+      .trim();
+    const roles = {
+      button: 'button',
+      a: 'link',
+      textarea: 'textbox',
+      select: 'combobox',
+      form: 'form',
+    };
+    const inputRole =
+      target.type === 'checkbox'
+        ? 'checkbox'
+        : target.type === 'radio'
+          ? 'radio'
+          : ['submit', 'button', 'reset'].includes(target.type)
+            ? 'button'
+            : 'textbox';
+    return {
+      path: pathOf(target),
+      role:
+        target.getAttribute('role') ??
+        (target.localName === 'input'
+          ? inputRole
+          : (roles[target.localName] ?? null)),
+      name: secret
+        ? redacted
+        : (
+            labelled ||
+            target.getAttribute('aria-label') ||
+            label ||
+            target.getAttribute('alt') ||
+            target.getAttribute('title') ||
+            text
+          ).slice(0, 500),
+      text,
+    };
+  };
+  const nonTextKeys =
+    /^(?:Enter|Escape|Tab|Backspace|Delete|Insert|Home|End|PageUp|PageDown|Arrow(?:Up|Down|Left|Right)|F(?:[1-9]|1\d|2[0-4]))$/;
+  const listener = (event) => {
+    if (
+      !event.isTrusted ||
+      (event.type === 'keydown' &&
+        (!nonTextKeys.test(event.key) || event.isComposing))
+    ) {
+      return;
+    }
+    const nodes = event.composedPath?.() ?? [event.target];
+    let target = nodes.find((node) => node?.nodeType === 1);
+    if (!target || matches(target, ignoreSelectors)) {
+      return;
+    }
+    // Only suppress engine input aimed at the commander's current target.
+    // A person using another control while an automation call waits is still
+    // recorded. Trusted input outside commander methods is always user input.
+    const commanderInput = (window.__browserCommanderActions__ ?? []).some(
+      (action) => {
+        if (!action.types.includes(event.type)) {
+          return false;
+        }
+        if (action.element) {
+          return (
+            action.element === target ||
+            action.element.contains(target) ||
+            (event.type === 'click' &&
+              event.detail === 0 &&
+              action.types.includes('keydown') &&
+              action.element.form &&
+              action.element.form === target.form) ||
+            (event.type === 'submit' && target.contains(action.element))
+          );
+        }
+        if (!action.selector) {
+          return event.type === 'keydown';
+        }
+        try {
+          return (
+            Boolean(target.closest(action.selector)) ||
+            (event.type === 'submit' &&
+              Boolean(target.querySelector(action.selector)))
+          );
+        } catch {
+          return false;
+        }
+      }
+    );
+    if (commanderInput) {
+      return;
+    }
+    if (event.type !== 'keydown') {
+      target =
+        target.closest(
+          'button, a, input, select, textarea, form, [role], [contenteditable]'
+        ) ?? target;
+    }
+    const payload = {
+      source: 'user',
+      actor: 'user',
+      action: event.type,
+      target: describe(target),
+      at: new Date().toISOString(),
+      url: location.href,
+      frameId: state.frameId,
+      mainFrame: window.top === window,
+      ...(event.type === 'keydown'
+        ? {
+            key: event.key,
+            altKey: event.altKey,
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            shiftKey: event.shiftKey,
+          }
+        : {}),
+    };
+    const enqueue = () => {
+      if (!state.observing) {
+        return;
+      }
+      if (state.queue.length < maxQueued) {
+        state.queue.push(payload);
+      } else {
+        state.dropped += 1;
+      }
+    };
+    if (binding && typeof window[binding] === 'function') {
+      // Bindings deliver the action before the app's request/response callbacks;
+      // engines without bindings use the bounded polling queue instead.
+      Promise.resolve(window[binding](globalName, payload)).catch(enqueue);
+    } else {
+      enqueue();
+    }
+  };
+  const types = ['click', 'pointerdown', 'keydown', 'submit', 'contextmenu'];
+  for (const type of types) {
+    document.addEventListener(type, listener, true);
+  }
+  state.stop = () => {
+    state.observing = false;
+    for (const type of types) {
+      document.removeEventListener(type, listener, true);
+    }
+  };
+  window[globalName] = state;
+}
+
+function drainUserActionsInPage(globalName) {
+  const state = window[globalName];
+  if (!state) {
+    return { actions: [], dropped: 0 };
+  }
+  const result = { actions: state.queue.splice(0), dropped: state.dropped };
+  state.dropped = 0;
+  return result;
+}
+
+function stopUserActionsInPage(globalName) {
+  window[globalName]?.stop();
+}
+
+/** Host half, shared by raw launched pages and commander traces. */
+export function createUserActionStream(options) {
+  const {
+    page,
+    enabled,
+    record,
+    identity,
+    note,
+    privacyOptions,
+    limits,
+    evaluateInPage,
+    captureTimeoutMs,
+  } = options;
+  const globalName = `__browserCommanderUserActions_${identity.traceId}`;
+  let active = true,
+    detachInit,
+    detachBinding;
+  const pending = new Set();
+  const emit = (payload) => {
+    if (!active) {
+      return Promise.resolve();
+    }
+    if (pending.size >= (limits.maxQueuedUserActions ?? 5000)) {
+      return Promise.reject(new Error('user action writer busy'));
+    }
+    const promise = record(TRACE_EVENT.INTERACTION, {
+      ...payload,
+      actionId: identity.nextActionId(),
+    });
+    pending.add(promise);
+    promise.finally(() => pending.delete(promise)).catch(() => {});
+    return promise;
+  };
+  const evaluate = async (fn, arg) => {
+    const frames = framesOf(page);
+    return await withDeadline(
+      frames.length
+        ? Promise.all(
+            frames.map((frame) => frame.evaluate(fn, arg).catch(() => null))
+          )
+        : Promise.resolve(evaluateInPage(fn, arg)).then((result) => [result]),
+      captureTimeoutMs,
+      'trace user actions'
+    );
+  };
+  async function install() {
+    if (!enabled) {
+      return;
+    }
+    try {
+      detachBinding = await attachBinding(page, globalName, emit).catch(
+        (error) => {
+          note(`using queued user actions: ${error.message}`);
+          return null;
+        }
+      );
+      const config = {
+        globalName,
+        binding: detachBinding ? USER_ACTION_BINDING : null,
+        maxQueued: limits.maxQueuedUserActions ?? 5000,
+        redactSelectors: privacyOptions.redactSelectors,
+        ignoreSelectors: options.ignoreSelectors ?? [],
+        redacted: '[redacted]',
+      };
+      detachInit = await installInitScript({
+        page,
+        fn: installUserActionRecorderInPage,
+        arg: config,
+        note,
+      });
+      await evaluate(installUserActionRecorderInPage, config);
+    } catch (error) {
+      note(`could not install user action recorder: ${error.message}`);
+      await record(TRACE_EVENT.DROPPED, {
+        reason: TRACE_DROP_REASON.CAPTURE_FAILED,
+        member: 'user-actions',
+        detail: error.message,
+      });
+    }
+  }
+  async function drain() {
+    if (!enabled) {
+      return;
+    }
+    try {
+      for (const result of await evaluate(drainUserActionsInPage, globalName)) {
+        for (const action of result?.actions ?? []) {
+          await emit(action);
+        }
+        if (result?.dropped) {
+          await record(TRACE_EVENT.DROPPED, {
+            reason: TRACE_DROP_REASON.SIZE_LIMIT,
+            member: 'user-actions',
+            detail: `${result.dropped} user actions over the queue limit`,
+          });
+        }
+      }
+      await Promise.all([...pending]);
+    } catch (error) {
+      note(`could not drain user actions: ${error.message}`);
+    }
+  }
+  async function stop() {
+    active = false;
+    await evaluate(stopUserActionsInPage, globalName).catch((error) =>
+      note(error.message)
+    );
+    try {
+      await detachInit?.();
+    } finally {
+      detachBinding?.();
+    }
+  }
+  return { install, drain, stop };
+}