browser-commander 0.17.1 → 0.18.0

package/src/interactions/click-activation.js

@@ -0,0 +1,317 @@
+/**
+ * Orthogonal click activation options.
+ *
+ * `noAutoScroll: true` used to be translated into Playwright's `{ force: true }`,
+ * which skips actionability checks but still scrolls the element into view. The
+ * option therefore promised something the engine never delivered. These three
+ * axes are independent and each one means exactly what it says:
+ *
+ * - `activation`: how the click is delivered ('pointer' | 'dom')
+ * - `scroll`: what may happen to the scroll position ('auto' | 'preserve' | 'none')
+ * - `actionability`: whether engine pre-checks are skipped ('normal' | 'force')
+ */
+
+import { TIMING } from '../core/constants.js';
+import { createDeadline } from '../core/readiness.js';
+
+/** How the click is delivered to the element. */
+export const CLICK_ACTIVATION = Object.freeze({
+  /** Real pointer input at the element's click point. */
+  POINTER: 'pointer',
+  /** `HTMLElement.click()` - an untrusted event that skips pointer handlers. */
+  DOM: 'dom',
+});
+
+/** What the click is allowed to do to the scroll position. */
+export const CLICK_SCROLL = Object.freeze({
+  /** Let the engine scroll the element into view (default). */
+  AUTO: 'auto',
+  /** Allow scrolling, then restore the original scroll position. */
+  PRESERVE: 'preserve',
+  /** Never scroll; fail if the click cannot be delivered without scrolling. */
+  NONE: 'none',
+});
+
+/** Whether the engine's actionability pre-checks run. */
+export const CLICK_ACTIONABILITY = Object.freeze({
+  NORMAL: 'normal',
+  /** Skip engine pre-checks. Does NOT disable scrolling. */
+  FORCE: 'force',
+});
+
+/**
+ * Thrown when `scroll: 'none'` cannot be honored.
+ *
+ * Failing loudly is the point: the previous behavior scrolled anyway and
+ * reported success, so callers who needed the viewport to stay put had no way
+ * to find out that it had moved.
+ */
+export class ScrollConstraintError extends Error {
+  /**
+   * @param {string} message - What made the constraint impossible to honor
+   * @param {Object} [detail] - Structured detail about the element and viewport
+   */
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = 'ScrollConstraintError';
+    this.detail = detail;
+  }
+}
+
+/**
+ * Resolve the activation options, applying the `noAutoScroll` compatibility
+ * mapping.
+ *
+ * @param {Object} options - Raw caller options
+ * @param {string} [options.activation] - Activation mode
+ * @param {string} [options.scroll] - Scroll policy
+ * @param {string} [options.actionability] - Actionability policy
+ * @param {boolean} [options.noAutoScroll] - Deprecated alias for `scroll: 'none'`
+ * @param {Function} [options.log] - Logger used for the deprecation notice
+ * @returns {{activation: string, scroll: string, actionability: string, deprecations: string[]}} Resolved options
+ */
+export function resolveActivationOptions(options = {}) {
+  const { activation, scroll, actionability, noAutoScroll, log } = options;
+  const deprecations = [];
+
+  let resolvedScroll = scroll;
+
+  if (noAutoScroll !== undefined) {
+    deprecations.push(
+      'noAutoScroll is deprecated; use scroll: "none" (no scrolling at all) ' +
+        'or actionability: "force" (skip engine pre-checks, scrolling still allowed)'
+    );
+    if (resolvedScroll === undefined) {
+      resolvedScroll = noAutoScroll ? CLICK_SCROLL.NONE : CLICK_SCROLL.AUTO;
+    }
+  }
+
+  const resolved = {
+    activation: activation ?? CLICK_ACTIVATION.POINTER,
+    scroll: resolvedScroll ?? CLICK_SCROLL.AUTO,
+    actionability: actionability ?? CLICK_ACTIONABILITY.NORMAL,
+    deprecations,
+  };
+
+  assertOneOf('activation', resolved.activation, CLICK_ACTIVATION);
+  assertOneOf('scroll', resolved.scroll, CLICK_SCROLL);
+  assertOneOf('actionability', resolved.actionability, CLICK_ACTIONABILITY);
+
+  if (deprecations.length > 0 && log?.debug) {
+    deprecations.forEach((message) => log.debug(() => `⚠️  ${message}`));
+  }
+
+  return resolved;
+}
+
+/**
+ * Start a click action: open one deadline and resolve the activation options.
+ *
+ * Both `clickElement` and `clickButton` need a clock and the same option
+ * resolution, and both must do it *before* anything can throw so that
+ * failures still report how long they took. The clock is the deadline's, so
+ * every later step - dispatch, probe, verification - measures against one
+ * monotonic budget rather than each starting a wall-clock timer of its own.
+ *
+ * @param {Object} options - Raw caller options, as accepted by {@link resolveActivationOptions}
+ * @param {number} [options.timeout] - Total budget for the whole click
+ * @returns {{deadline: Object, elapsed: Function, activationOptions: Object}} Deadline, elapsed-ms reader and resolved options
+ */
+export function beginClickAction(options = {}) {
+  const { timeout = TIMING.VERIFICATION_TIMEOUT } = options;
+  const deadline = createDeadline({ timeout });
+
+  return {
+    deadline,
+    elapsed: () => deadline.elapsedMs(),
+    activationOptions: resolveActivationOptions(options),
+  };
+}
+
+function assertOneOf(name, value, allowed) {
+  const values = Object.values(allowed);
+  if (!values.includes(value)) {
+    throw new Error(
+      `${name} must be one of ${values.map((v) => `'${v}'`).join(', ')}, got '${value}'`
+    );
+  }
+}
+
+/**
+ * Measure an element's click point and whether it is reachable right now.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.adapter - Engine adapter
+ * @param {Object} options.locatorOrElement - Element or locator
+ * @returns {Promise<Object>} Geometry and hit-test result
+ */
+export function measureClickPoint(options = {}) {
+  const { adapter, locatorOrElement } = options;
+
+  return adapter.evaluateOnElement(locatorOrElement, (el) => {
+    const rect = el.getBoundingClientRect();
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    const inViewport =
+      rect.width > 0 &&
+      rect.height > 0 &&
+      x >= 0 &&
+      y >= 0 &&
+      x <= window.innerWidth &&
+      y <= window.innerHeight;
+    const hit = inViewport ? document.elementFromPoint(x, y) : null;
+
+    return {
+      x,
+      y,
+      width: rect.width,
+      height: rect.height,
+      top: rect.top,
+      left: rect.left,
+      viewport: { width: window.innerWidth, height: window.innerHeight },
+      scroll: { x: window.scrollX, y: window.scrollY },
+      inViewport,
+      hitsTarget: Boolean(hit && (hit === el || el.contains(hit))),
+    };
+  });
+}
+
+/**
+ * Read the current window scroll position.
+ *
+ * @param {Object} adapter - Engine adapter
+ * @returns {Promise<{x: number, y: number}>} Scroll offsets
+ */
+export async function readScrollPosition(adapter) {
+  if (typeof adapter?.evaluateOnPage !== 'function') {
+    return null;
+  }
+  try {
+    return await adapter.evaluateOnPage(() => ({
+      x: window.scrollX,
+      y: window.scrollY,
+    }));
+  } catch {
+    // Scroll position is evidence, not a precondition - never fail a click
+    // because we could not read it.
+    return null;
+  }
+}
+
+/**
+ * Restore a previously captured scroll position.
+ *
+ * @param {Object} adapter - Engine adapter
+ * @param {{x: number, y: number}} position - Position to restore
+ * @returns {Promise<void>} Resolves once restored
+ */
+export async function restoreScrollPosition(adapter, position) {
+  if (!position || typeof adapter?.evaluateOnPage !== 'function') {
+    return;
+  }
+  // `evaluateOnPage` takes an argument *list*, so the position has to be
+  // wrapped - passing the object directly made Playwright try to spread it.
+  await adapter.evaluateOnPage(
+    (pos) => window.scrollTo(pos.x, pos.y),
+    [position]
+  );
+}
+
+/**
+ * Deliver a click according to the resolved activation options.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {Object} options.adapter - Engine adapter
+ * @param {Object} options.locatorOrElement - Element or locator to click
+ * @param {Object} options.activationOptions - Result of {@link resolveActivationOptions}
+ * @param {Function} [options.log] - Logger instance
+ * @returns {Promise<{mode: string, scrollBefore: Object|null, scrollAfter: Object|null, point: Object|null}>} Dispatch detail
+ * @throws {ScrollConstraintError} When `scroll: 'none'` cannot be honored
+ */
+export async function dispatchClick(options = {}) {
+  const {
+    page,
+    adapter,
+    locatorOrElement,
+    activationOptions,
+    log = { debug: () => {} },
+  } = options;
+
+  const { activation, scroll, actionability } = activationOptions;
+
+  if (activation === CLICK_ACTIVATION.DOM) {
+    log.debug(
+      () =>
+        '🖱️  Dispatching DOM activation (HTMLElement.click(); untrusted event, no scrolling)'
+    );
+    const scrollBefore = await readScrollPosition(adapter);
+    await adapter.evaluateOnElement(locatorOrElement, (el) => el.click());
+    return {
+      mode: CLICK_ACTIVATION.DOM,
+      scrollBefore,
+      scrollAfter: await readScrollPosition(adapter),
+      point: null,
+    };
+  }
+
+  if (scroll === CLICK_SCROLL.NONE) {
+    return dispatchPointerWithoutScrolling({
+      page,
+      adapter,
+      locatorOrElement,
+      log,
+    });
+  }
+
+  const scrollBefore = await readScrollPosition(adapter);
+  const engineOptions =
+    actionability === CLICK_ACTIONABILITY.FORCE ? { force: true } : {};
+  await adapter.click(locatorOrElement, engineOptions);
+
+  if (scroll === CLICK_SCROLL.PRESERVE) {
+    await restoreScrollPosition(adapter, scrollBefore);
+  }
+
+  return {
+    mode: CLICK_ACTIVATION.POINTER,
+    scrollBefore,
+    scrollAfter: await readScrollPosition(adapter),
+    point: null,
+  };
+}
+
+async function dispatchPointerWithoutScrolling(options) {
+  const { page, adapter, locatorOrElement, log } = options;
+
+  const point = await measureClickPoint({ adapter, locatorOrElement });
+
+  if (!point.inViewport) {
+    throw new ScrollConstraintError(
+      'scroll: "none" was requested but the element is outside the viewport, ' +
+        'so a real pointer click cannot reach it without scrolling. Use ' +
+        'scroll: "preserve" to scroll and restore, scroll: "auto" to allow ' +
+        'scrolling, or activation: "dom" to dispatch an untrusted click.',
+      point
+    );
+  }
+
+  if (!point.hitsTarget) {
+    throw new ScrollConstraintError(
+      'scroll: "none" was requested but another element covers the target at ' +
+        'its click point, so a real pointer click would hit the wrong element.',
+      point
+    );
+  }
+
+  log.debug(
+    () =>
+      `🖱️  Pointer click at (${Math.round(point.x)}, ${Math.round(point.y)}) without scrolling`
+  );
+
+  const scrollBefore = { x: point.scroll.x, y: point.scroll.y };
+  await page.mouse.click(point.x, point.y);
+  const scrollAfter = await readScrollPosition(adapter);
+
+  return { mode: CLICK_ACTIVATION.POINTER, scrollBefore, scrollAfter, point };
+}

package/src/interactions/click-result.js

@@ -0,0 +1,108 @@
+/**
+ * Truthful result model for click operations.
+ *
+ * The old model answered every click with two booleans, and both of them were
+ * optimistic: a button that did nothing still reported `verified: true`. This
+ * model separates three questions that used to be conflated - did we dispatch
+ * the click, did the page react, and how did the operation end - and records
+ * the evidence behind each answer.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+/** How a click operation ended. */
+export const CLICK_STATUS = Object.freeze({
+  /** Click dispatched and its effect was confirmed. */
+  SUCCEEDED: 'succeeded',
+  /** Click could not be dispatched, or dispatch provably failed. */
+  FAILED: 'failed',
+  /** The operation ran out of its budget. */
+  TIMED_OUT: 'timed_out',
+  /** Navigation or an explicit stop cut the operation short. */
+  INTERRUPTED: 'interrupted',
+  /** Click dispatched, but nothing confirmed or denied that it had an effect. */
+  UNVERIFIED: 'unverified',
+});
+
+/** What the page did in response to the click. */
+export const CLICK_EFFECT = Object.freeze({
+  /** Observed evidence that the click did something. */
+  CONFIRMED: 'confirmed',
+  /** No evidence either way. */
+  NOT_OBSERVED: 'not-observed',
+  /** Observed evidence that the click did NOT do what was expected. */
+  CONTRADICTED: 'contradicted',
+});
+
+/**
+ * Build one piece of evidence for a click or readiness decision.
+ *
+ * @param {string} type - Evidence kind, e.g. 'element-state' or 'navigation'
+ * @param {Object} [detail] - Arbitrary structured detail
+ * @returns {{type: string, detail: Object}} Evidence entry
+ */
+export function evidence(type, detail = {}) {
+  return { type, detail };
+}
+
+/**
+ * Build a click result, deriving the legacy booleans conservatively.
+ *
+ * `verified` is deliberately derived from `effect === 'confirmed'` rather than
+ * from "nothing went wrong", which is what made the old value meaningless.
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.status - One of {@link CLICK_STATUS}
+ * @param {boolean} [options.dispatched=false] - Whether the click reached the element
+ * @param {string} [options.effect] - One of {@link CLICK_EFFECT}
+ * @param {Array} [options.evidence] - Evidence entries
+ * @param {number} [options.elapsedMs=0] - Duration of the operation
+ * @param {string} [options.reason=''] - Human-readable summary
+ * @param {boolean} [options.navigated=false] - Whether navigation was attributed to this click
+ * @param {string} [options.actionId] - Correlation ID for this click
+ * @returns {Object} Click result
+ */
+export function makeClickResult(options = {}) {
+  const {
+    status,
+    dispatched = false,
+    effect = CLICK_EFFECT.NOT_OBSERVED,
+    evidence: evidenceList = [],
+    elapsedMs = 0,
+    reason = '',
+    navigated = false,
+    actionId,
+    ...rest
+  } = options;
+
+  return {
+    status,
+    dispatched,
+    effect,
+    evidence: evidenceList,
+    elapsedMs,
+    reason,
+    navigated,
+    ...(actionId === undefined ? {} : { actionId }),
+
+    // Legacy booleans, kept so existing callers keep working - but now derived
+    // from what was actually observed.
+    clicked: dispatched,
+    verified: effect === CLICK_EFFECT.CONFIRMED,
+    ...rest,
+  };
+}
+
+/**
+ * Mint a correlation ID so navigation evidence can be tied to one click.
+ *
+ * The random half comes from the system CSPRNG rather than `Math.random()`.
+ * The ID is only a correlation key, but it travels into logs and trace
+ * bundles, where a reader cannot tell a correlation key from a token; taking
+ * the characters from `randomUUID` costs nothing and settles the question.
+ *
+ * @returns {string} Opaque action ID
+ */
+export function nextActionId() {
+  return `click-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+}