@deeeed/metamask-harness 0.37.0 → 0.38.0

package/library/actions/extension/swap_bridge/set_slippage.mjs

@@ -0,0 +1,121 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+async function pause(page) {
+  await page.evaluate('new Promise((resolve) => setTimeout(resolve, 200))');
+}
+
+async function visible(page, selector) {
+  return page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+  })()`);
+}
+
+async function clickUntil(page, trigger, result, deadline, message) {
+  while (Date.now() < deadline) {
+    if (await visible(page, result)) return;
+    if (await visible(page, trigger)) {
+      try {
+        await page.click(trigger);
+      } catch {
+        await pause(page);
+      }
+    }
+    await pause(page);
+  }
+  throw new Error(message);
+}
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const percent = Number(input.node?.percent);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
+  if (!Number.isFinite(percent) || percent <= 0 || percent > 50) {
+    throw new Error('metamask.swap_bridge.set_slippage requires percent greater than 0 and at most 50.');
+  }
+  const deadline = Date.now() + timeoutMs;
+  const settings = dataTestId('bridge__header-settings-button');
+  const edit = dataTestId('slippage-edit-button');
+  const custom = dataTestId('bridge__tx-settings-modal-custom-button');
+  const inputSelector = dataTestId('bridge__tx-settings-modal-custom-input');
+  const submit = dataTestId('bridge__tx-settings-modal-submit-button');
+  const opener = (await visible(page, edit)) ? edit : settings;
+  await clickUntil(page, opener, custom, deadline, 'Swap transaction settings did not open.');
+  await clickUntil(page, custom, inputSelector, deadline, 'Custom slippage input did not open.');
+  await page.setInput(inputSelector, String(percent));
+  for (const type of ['keyDown', 'keyUp']) {
+    await page.session.call('Input.dispatchKeyEvent', {
+      type,
+      key: 'Tab',
+      code: 'Tab',
+      windowsVirtualKeyCode: 9,
+    });
+  }
+  while (Date.now() < deadline) {
+    const enabled = await page.evaluate(`document.querySelector(${JSON.stringify(submit)})?.disabled === false`);
+    if (enabled) break;
+    await pause(page);
+  }
+  if (!(await page.evaluate(`document.querySelector(${JSON.stringify(submit)})?.disabled === false`))) {
+    throw new Error('Custom slippage did not enable Submit.');
+  }
+  await page.click(submit);
+  let observed = null;
+  while (Date.now() < deadline) {
+    observed = await page.evaluate(`(() => {
+      const button = document.querySelector('[data-testid="slippage-edit-button"]');
+      return String(button?.parentElement?.innerText || '').replace(/\\s+/gu, ' ').trim();
+    })()`);
+    if (observed.includes(`${percent}%`)) break;
+    await pause(page);
+  }
+  if (!observed?.includes(`${percent}%`)) {
+    throw new Error(`Swap quote did not display Slippage: ${percent}%.`);
+  }
+  await page.evaluate('new Promise((resolve) => setTimeout(resolve, 500))');
+  let stableSince = null;
+  let quote = null;
+  let lastRefreshAt = 0;
+  while (Date.now() < deadline) {
+    quote = await page.evaluate(`(() => {
+      const destination = document.querySelector('[data-testid="to-amount"]');
+      const input = destination?.matches('input, textarea') ? destination : destination?.querySelector('input, textarea');
+      const cta = document.querySelector('[data-testid="bridge-cta-button"]');
+      return {
+        loading: Boolean(document.querySelector('[data-testid="multichain-bridge-quote-card-loading"]')),
+        destinationAmount: String(input?.value ?? '').trim(),
+        cta: String(cta?.innerText || '').replace(/\\s+/gu, ' ').trim(),
+        ctaEnabled: Boolean(cta && !cta.disabled),
+      };
+    })()`);
+    if (/^(?:Get new quote|Refresh quote)$/iu.test(quote.cta) && quote.ctaEnabled && Date.now() - lastRefreshAt >= 1000) {
+      await page.click(dataTestId('bridge-cta-button'));
+      lastRefreshAt = Date.now();
+      stableSince = null;
+      await pause(page);
+      continue;
+    }
+    const ready = !quote.loading && Number(quote.destinationAmount) > 0 && quote.ctaEnabled
+      && /^(?:Swap|Bridge)$/iu.test(quote.cta);
+    if (ready) {
+      stableSince ??= Date.now();
+      if (Date.now() - stableSince >= 1000) break;
+    } else {
+      stableSince = null;
+    }
+    await pause(page);
+  }
+  if (stableSince === null || quote?.loading || !(Number(quote?.destinationAmount) > 0) || !quote?.ctaEnabled
+    || !/^(?:Swap|Bridge)$/iu.test(String(quote?.cta))) {
+    throw new Error('Swap quote did not finish refreshing after custom slippage was applied.');
+  }
+  return {
+    action: input.action,
+    percent,
+    observed,
+    quote,
+    proofPath: 'trusted-pointer-keyboard-visible-ui',
+  };
+}));

package/library/actions/extension/swap_bridge/submit_transaction.mjs

@@ -0,0 +1,363 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { bodyState, tokenRow, transactionState, visible, waitFor } from '../assets/send.mjs';
+
+const selectors = {
+  cta: dataTestId('bridge-cta-button'),
+  warningProceed: `${dataTestId('bridge-alert-modal-proceed-button')}:not([disabled])`,
+  confirm: dataTestId('confirm-sign-and-send-transaction-confirm-snap-footer-button'),
+  close: 'button[aria-label="Close"]',
+  activity: dataTestId('bottom-nav-activity'),
+  home: dataTestId('bottom-nav-home'),
+  swap: dataTestId('bottom-nav-swaps'),
+};
+
+async function pause(page, timeoutMs = 200) {
+  await page.evaluate(`new Promise((resolve) => setTimeout(resolve, ${JSON.stringify(timeoutMs)}))`);
+}
+
+async function activatePoint(page, point) {
+  await page.session.call('Input.dispatchMouseEvent', { type: 'mouseMoved', x: point.x, y: point.y });
+  await page.session.call('Input.dispatchMouseEvent', {
+    type: 'mousePressed',
+    x: point.x,
+    y: point.y,
+    button: 'left',
+    clickCount: 1,
+  });
+  await page.session.call('Input.dispatchMouseEvent', {
+    type: 'mouseReleased',
+    x: point.x,
+    y: point.y,
+    button: 'left',
+    clickCount: 1,
+  });
+}
+
+async function activateSelector(page, selector) {
+  const point = await page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return null;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0) return null;
+    return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+  })()`);
+  if (!point) return false;
+  await activatePoint(page, point);
+  return true;
+}
+
+function isActivityRoute(route) {
+  return route.includes('/activity') || /[?&]tab=activity(?:&|$)/u.test(route);
+}
+
+function transactionIdentifier(value) {
+  const identifier = String(value);
+  return /^0x/iu.test(identifier) ? identifier.toLowerCase() : identifier;
+}
+
+async function openActivity(page, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastActivationAt = 0;
+  let lastResetAt = 0;
+  while (Date.now() < deadline) {
+    const state = await bodyState(page);
+    if (isActivityRoute(state.route) && await visible(page, dataTestId('activity-list-item'))) return state;
+    if (isActivityRoute(state.route) && await visible(page, selectors.swap) && Date.now() - lastResetAt >= 1000) {
+      await activateSelector(page, selectors.swap);
+      lastResetAt = Date.now();
+      await pause(page);
+      continue;
+    }
+    if (await visible(page, selectors.activity) && Date.now() - lastActivationAt >= 1000) {
+      await activateSelector(page, selectors.activity);
+      lastActivationAt = Date.now();
+    }
+    await pause(page);
+  }
+  throw new Error('Activity did not open after swap.');
+}
+
+async function quoteState(page) {
+  return page.evaluate(`(() => {
+    const value = (testId) => {
+      const root = document.querySelector('[data-testid="' + testId + '"]');
+      const input = root?.matches('input, textarea') ? root : root?.querySelector('input, textarea');
+      return String(input?.value ?? '').trim();
+    };
+    const label = (testId) => String(document.querySelector('[data-testid="' + testId + '"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
+    const cta = document.querySelector('[data-testid="bridge-cta-button"]');
+    return {
+      route: location.hash,
+      sourceSymbol: label('bridge-source-button'),
+      destinationSymbol: label('bridge-destination-button'),
+      sourceAmount: value('from-amount'),
+      destinationAmount: value('to-amount'),
+      cta: cta ? String(cta.innerText || '').replace(/\\s+/gu, ' ').trim() : null,
+      ctaEnabled: Boolean(cta && !cta.disabled),
+      loading: Boolean(document.querySelector('[data-testid="multichain-bridge-quote-card-loading"]')),
+      warning: String(document.body?.innerText || '').match(/(?:might be reverted|may fail|likely to fail|insufficient funds|trade route isn't available)[^.]{0,300}/iu)?.[0] || null,
+    };
+  })()`);
+}
+
+async function submittableQuote(page, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const quote = await quoteState(page);
+    if (/^(?:Get new quote|Refresh quote)$/iu.test(String(quote.cta)) && quote.ctaEnabled) {
+      await page.click(selectors.cta);
+      await pause(page, 500);
+      continue;
+    }
+    if (/^(?:Swap|Bridge)$/iu.test(String(quote.cta)) && quote.ctaEnabled && !quote.loading) return quote;
+    await pause(page);
+  }
+  throw new Error('Swap did not expose a fresh submittable quote.');
+}
+
+async function activityRow(page, sourceSymbol, destinationSymbol, occurrence = 0) {
+  return page.evaluate(`(() => {
+    const source = ${JSON.stringify(sourceSymbol)};
+    const destination = ${JSON.stringify(destinationSymbol)};
+    const occurrence = ${JSON.stringify(occurrence)};
+    let matched = 0;
+    for (const row of document.querySelectorAll('[data-testid="activity-list-item"]')) {
+      const label = String(row.innerText || row.textContent || '').replace(/\\s+/gu, ' ').trim();
+      const upper = label.toUpperCase();
+      const pair = upper.includes(source + ' → ' + destination)
+        || upper.includes(source + ' -> ' + destination);
+      const bridgeSource = upper.includes('BRIDGED ' + source);
+      if (!pair && !bridgeSource) continue;
+      const style = getComputedStyle(row);
+      const rect = row.getBoundingClientRect();
+      if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0) continue;
+      if (matched < occurrence) {
+        matched += 1;
+        continue;
+      }
+      return {
+        label: label.slice(0, 1000),
+        status: String(row.getAttribute('data-tx-status') || ''),
+        x: rect.left + rect.width / 2,
+        y: rect.top + rect.height / 2,
+      };
+    }
+    return null;
+  })()`);
+}
+
+async function activateActivityRow(page, row) {
+  await activatePoint(page, row);
+}
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const sourceSymbol = String(input.node?.source_symbol || '').trim().toUpperCase();
+  const destinationSymbol = String(input.node?.destination_symbol || '').trim().toUpperCase();
+  const requestedAmount = String(input.node?.amount || '').trim();
+  const resumeSubmitted = input.node?.resume_submitted === true;
+  const resumedHash = String(input.node?.transaction_hash || '').trim();
+  const activityOccurrence = Number(input.node?.activity_occurrence ?? 0);
+  const requireDestinationBalance = input.node?.require_destination_balance !== false;
+  const timeoutMs = Number(input.node?.timeout_ms ?? 300_000);
+  if (!sourceSymbol || !destinationSymbol || !requestedAmount || !Number.isInteger(activityOccurrence) || activityOccurrence < 0) {
+    throw new Error('metamask.swap_bridge.submit_transaction requires source_symbol, destination_symbol, and amount.');
+  }
+  if (!resumeSubmitted && input.node?.confirm_live !== true) {
+    throw new Error('metamask.swap_bridge.submit_transaction requires confirm_live=true.');
+  }
+  if (resumeSubmitted && !resumedHash) {
+    throw new Error('metamask.swap_bridge.submit_transaction resume_submitted=true requires transaction_hash.');
+  }
+
+  let submitted = resumeSubmitted;
+  let confirmed = resumeSubmitted;
+  let amount = requestedAmount;
+  let beforeTransactionIdentifiers = new Set();
+  if (!resumeSubmitted) {
+    let quote = await submittableQuote(page, Math.min(timeoutMs, 60_000));
+    if (requestedAmount === 'visible') amount = quote.sourceAmount;
+    if (!quote.sourceSymbol.toUpperCase().includes(sourceSymbol)
+      || !quote.destinationSymbol.toUpperCase().includes(destinationSymbol)
+      || quote.sourceAmount !== amount
+      || !(Number(quote.destinationAmount) > 0)
+      || !quote.ctaEnabled
+      || quote.loading
+      || quote.warning) {
+      throw new Error(`Swap quote is not safe to submit: ${JSON.stringify(quote)}.`);
+    }
+    await pause(page, 2000);
+    quote = await submittableQuote(page, Math.min(timeoutMs, 60_000));
+    if (!quote.sourceSymbol.toUpperCase().includes(sourceSymbol)
+      || !quote.destinationSymbol.toUpperCase().includes(destinationSymbol)
+      || quote.sourceAmount !== amount
+      || !(Number(quote.destinationAmount) > 0)
+      || !quote.ctaEnabled
+      || quote.loading
+      || quote.warning) {
+      throw new Error(`Swap quote changed before submission: ${JSON.stringify(quote)}.`);
+    }
+    const beforeTransactions = await transactionState(page);
+    if (!beforeTransactions.available) {
+      throw new Error('Transaction state is unavailable; refusing to submit without proof binding.');
+    }
+    beforeTransactionIdentifiers = new Set(beforeTransactions.transactions.flatMap((transaction) => [
+      transaction.id,
+      transaction.hash,
+    ].filter(Boolean).map(transactionIdentifier)));
+    await page.click(selectors.cta);
+    const submissionDeadline = Date.now() + Math.min(timeoutMs, 120_000);
+    while (Date.now() < submissionDeadline) {
+      if (await visible(page, selectors.warningProceed)) {
+        await page.click(selectors.warningProceed);
+        await pause(page);
+        continue;
+      }
+      if (await visible(page, selectors.confirm)) {
+        await page.click(selectors.confirm);
+        confirmed = true;
+        submitted = true;
+        await pause(page);
+        continue;
+      }
+      const state = await bodyState(page);
+      if (state.route !== '#/cross-chain/swaps/prepare-bridge-page'
+        && !state.route.includes('/confirmation')) {
+        submitted = true;
+      }
+      if (submitted && (state.route === '' || state.route === '#/' || isActivityRoute(state.route) || /Processing|Transaction complete|submitted/iu.test(state.text))) {
+        break;
+      }
+      await pause(page);
+    }
+    if (!submitted) {
+      throw new Error('Swap submission did not reach a signed or submitted state.');
+    }
+  }
+
+  let activity = null;
+  let details = await bodyState(page);
+  const resumedFromDetails = details.route.includes('/tx/')
+    && /\bConfirmed\b/u.test(details.text)
+    && /\bYou sent\b/u.test(details.text)
+    && /\bYou received\b/u.test(details.text)
+    && details.text.toUpperCase().includes(sourceSymbol)
+    && details.text.toUpperCase().includes(destinationSymbol);
+  if (!resumedFromDetails) {
+    await waitFor(page, async () => {
+      const state = await bodyState(page);
+      if (isActivityRoute(state.route) || await visible(page, selectors.activity)) return state;
+      if (await visible(page, selectors.close)) await page.click(selectors.close);
+      return null;
+    }, 'Swap did not expose Activity after submission.', timeoutMs);
+    await openActivity(page, timeoutMs);
+
+    let lastActivityRefresh = 0;
+    const activityTarget = await waitFor(page, async () => {
+      const row = await activityRow(page, sourceSymbol, destinationSymbol, activityOccurrence);
+      if (row?.status === 'failed') throw new Error(`Swap Activity failed: ${row.label}.`);
+      if (row?.status === 'confirmed') return row;
+      if (Date.now() - lastActivityRefresh >= 5000 && await visible(page, selectors.home)) {
+        await page.click(selectors.home);
+        await pause(page, 500);
+        await openActivity(page, Math.min(10_000, Math.max(1, timeoutMs)));
+        lastActivityRefresh = Date.now();
+      }
+      return null;
+    }, `Swap ${sourceSymbol} to ${destinationSymbol} did not reach Confirmed in Activity.`, timeoutMs);
+    activity = { label: activityTarget.label, status: activityTarget.status };
+    confirmed = true;
+    let lastDetailsActivationAt = 0;
+    details = await waitFor(page, async () => {
+      const current = await bodyState(page);
+      if (current.route.includes('/tx/') && /\bConfirmed\b/u.test(current.text)) return current;
+      if (Date.now() - lastDetailsActivationAt >= 1000) {
+        await activateActivityRow(page, activityTarget);
+        lastDetailsActivationAt = Date.now();
+      }
+      return null;
+    }, 'Confirmed swap transaction details did not open.', timeoutMs);
+  }
+  const explorerUrl = await page.evaluate(`document.querySelector('[data-testid="transaction-details-block-explorer"]')?.getAttribute('data-explorer-url') || null`);
+  const routeIdentifier = details.route.match(/\/([^/?#]+)(?:\?|$)/u)?.[1] ?? null;
+  const transactionHash = details.route.match(/\/(0x[0-9a-f]{64})(?:\?|$)/iu)?.[1]
+    ?? details.text.match(/\b0x[0-9a-f]{64}\b/iu)?.[0]
+    ?? String(explorerUrl || '').match(/\/(0x[0-9a-f]{64})(?:[/?#]|$)/iu)?.[1]
+    ?? (/^[1-9A-HJ-NP-Za-km-z]{64,100}$/u.test(String(routeIdentifier)) ? routeIdentifier : null)
+    ?? String(explorerUrl || '').match(/\/(?:tx|transaction)\/([1-9A-HJ-NP-Za-km-z]{64,100})(?:[/?#]|$)/u)?.[1]
+    ?? null;
+  if (!transactionHash) throw new Error('Confirmed swap details did not expose a full transaction hash.');
+  if (resumeSubmitted && transactionIdentifier(transactionHash) !== transactionIdentifier(resumedHash)) {
+    throw new Error(`Confirmed swap details opened ${transactionHash}, expected ${resumedHash}.`);
+  }
+  if (!resumeSubmitted) {
+    const confirmedIdentifier = transactionIdentifier(transactionHash);
+    if (beforeTransactionIdentifiers.has(confirmedIdentifier)) {
+      throw new Error(`Confirmed swap details opened pre-existing transaction ${transactionHash}.`);
+    }
+    const afterTransactions = await transactionState(page);
+    const submittedTransaction = afterTransactions.transactions.find((transaction) =>
+      transactionIdentifier(transaction.hash) === confirmedIdentifier &&
+      !beforeTransactionIdentifiers.has(transactionIdentifier(transaction.id)));
+    if (!submittedTransaction) {
+      throw new Error(`Confirmed swap ${transactionHash} is not bound to a newly created transaction record.`);
+    }
+  }
+  const detailText = details.text.toUpperCase();
+  const sentSource = new RegExp('YOU SENT[\\s\\S]{0,120}\\b' + sourceSymbol + '\\b', 'u');
+  const receivedDestination = new RegExp('YOU RECEIVED[\\s\\S]{0,120}\\b' + destinationSymbol + '\\b', 'u');
+  if (!sentSource.test(detailText) || !receivedDestination.test(detailText)) {
+    throw new Error(`Confirmed swap details do not prove ${sourceSymbol} to ${destinationSymbol}.`);
+  }
+  const back = dataTestId('transaction-details-back-button');
+  let lastBackActivationAt = 0;
+  await waitFor(page, async () => {
+    const current = await bodyState(page);
+    if (isActivityRoute(current.route)) return current;
+    if (await visible(page, back) && Date.now() - lastBackActivationAt >= 1000) {
+      await page.click(back);
+      lastBackActivationAt = Date.now();
+    }
+    return null;
+  }, 'Swap details did not return to Activity.', timeoutMs);
+  await waitFor(page, async () => await visible(page, selectors.home), 'Home navigation did not return after swap details.', timeoutMs);
+  let lastHomeActivationAt = 0;
+  await waitFor(page, async () => {
+    const current = await bodyState(page);
+    if (current.route === '' || current.route === '#/' || current.route.startsWith('#/?')) return current;
+    if (await visible(page, selectors.home) && Date.now() - lastHomeActivationAt >= 1000) {
+      await page.click(selectors.home);
+      lastHomeActivationAt = Date.now();
+    }
+    return null;
+  }, 'Home did not open after the confirmed swap.', timeoutMs);
+  const destinationAfter = requireDestinationBalance
+    ? await waitFor(
+      page,
+      async () => {
+        const row = await tokenRow(page, destinationSymbol);
+        const numeric = Number(String(row?.amount || '').replace(/[^0-9.eE+-]/gu, ''));
+        return row && Number.isFinite(numeric) && numeric > 0 ? row : null;
+      },
+      `${destinationSymbol} did not reach a positive Home balance after the transaction.`,
+      timeoutMs,
+    )
+    : null;
+  return {
+    action: input.action,
+    sourceSymbol,
+    destinationSymbol,
+    amount,
+    submitted,
+    confirmed,
+    activity,
+    details,
+    destinationAfter,
+    explorerUrl,
+    transactionHash,
+    resumed: resumeSubmitted,
+    activityOccurrence,
+    destinationBalanceRequired: requireDestinationBalance,
+    proofPath: 'trusted-pointer-visible-ui',
+  };
+}));

package/library/actions/extension/ui/activate_and_observe.mjs

@@ -0,0 +1,96 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+function nonEmpty(value, name) {
+  if (value == null) return undefined;
+  const result = String(value).trim();
+  if (!result) throw new Error(`ui.activate_and_observe ${name} must not be empty.`);
+  return result;
+}
+
+function boundedInteger(value, fallback, minimum, maximum, name) {
+  const result = value == null ? fallback : Number(value);
+  if (!Number.isInteger(result) || result < minimum || result > maximum) {
+    throw new Error(`ui.activate_and_observe ${name} must be an integer from ${minimum} to ${maximum}.`);
+  }
+  return result;
+}
+
+function stringList(value, name) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) throw new Error(`ui.activate_and_observe ${name} must be an array.`);
+  return [...new Set(value.map((entry) => String(entry).trim()).filter(Boolean))];
+}
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const testId = nonEmpty(input.node?.test_id ?? input.node?.testID, 'test_id');
+  const selector = nonEmpty(input.node?.selector, 'selector');
+  if (Number(Boolean(testId)) + Number(Boolean(selector)) !== 1) {
+    throw new Error('ui.activate_and_observe requires exactly one of test_id or selector.');
+  }
+  const target = selector ?? dataTestId(testId);
+  const timeoutMs = boundedInteger(input.node?.timeout_ms, 10_000, 1, 60_000, 'timeout_ms');
+  const settleMs = boundedInteger(input.node?.settle_ms, 250, 0, 10_000, 'settle_ms');
+  const maxItems = boundedInteger(input.node?.max_items, 100, 1, 200, 'max_items');
+  const requireTestIds = stringList(input.node?.require_test_ids, 'require_test_ids');
+  const requireText = stringList(input.node?.require_text, 'require_text');
+
+  const deadline = Date.now() + timeoutMs;
+  let targetVisible = false;
+  while (Date.now() <= deadline) {
+    targetVisible = await page.evaluate(`(() => {
+      const element = document.querySelector(${JSON.stringify(target)});
+      if (!element) return false;
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+    })()`);
+    if (targetVisible) break;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  if (!targetVisible) throw new Error(`ui.activate_and_observe target did not become visible: ${target}`);
+  const interaction = await page.click(target);
+  if (settleMs > 0) await new Promise((resolve) => setTimeout(resolve, settleMs));
+  const observed = await page.evaluate(`(() => {
+    const maximum = ${JSON.stringify(maxItems)};
+    const controls = [];
+    for (const element of document.querySelectorAll('[data-testid]')) {
+      const testId = element.getAttribute('data-testid');
+      if (!testId) continue;
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0) continue;
+      controls.push({
+        testId,
+        label: String(element.getAttribute('aria-label') || element.innerText || '')
+          .replace(/\\s+/gu, ' ')
+          .trim()
+          .slice(0, 500),
+      });
+      if (controls.length >= maximum) break;
+    }
+    return {
+      route: location.hash,
+      text: String(document.body?.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 20_000),
+      controls,
+    };
+  })()`);
+  const observedTestIds = observed.controls.map((entry) => entry.testId);
+  const observedText = [observed.text, ...observed.controls.map((entry) => entry.label)].join(' ');
+  const missingTestIds = requireTestIds.filter((entry) => !observedTestIds.includes(entry));
+  const missingText = requireText.filter((entry) => !observedText.includes(entry));
+  if (missingTestIds.length > 0 || missingText.length > 0) {
+    throw new Error([
+      missingTestIds.length > 0 ? `missing test IDs: ${missingTestIds.join(', ')}` : '',
+      missingText.length > 0 ? `missing text: ${missingText.join(', ')}` : '',
+    ].filter(Boolean).join('; '));
+  }
+  return {
+    action: input.action,
+    interaction,
+    route: observed.route,
+    controls: observed.controls,
+    observedTestIds,
+    matchedText: requireText,
+    proofPath: 'trusted-pointer-visible-ui',
+  };
+}));