@deeeed/metamask-harness 0.48.0 → 0.49.0

package/library/actions/extension/perps/read_snapshot.mjs

@@ -1,3 +1,5 @@
+// Read bounded, normalized Perps snapshots through background APIs, optionally sampling market changes.
+// History checks can require a matching visible activity card identity.
 import { pathToFileURL } from 'node:url';
 
 import { normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';

package/library/actions/extension/perps/read_visible_state.mjs

@@ -1,3 +1,5 @@
+// Capture Perps DOM controls, order-entry values, and layout within configured item and visibility bounds.
+// Normalize the observation and check requested visible-state expectations.
 import { pathToFileURL } from 'node:url';
 
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';

package/library/actions/extension/perps/search_markets.mjs

@@ -1,3 +1,4 @@
+// Enter a Perps market search query and wait for at least one displayed result row.
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 runAdapter(async (input) => withExtensionPage(input, async (page) => {

package/library/actions/extension/perps/select_activity_filter.mjs

@@ -1,3 +1,4 @@
+// Select a Perps activity filter and wait for its route, label, and loaded cards or empty state.
 import { pathToFileURL } from 'node:url';
 
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';

package/library/actions/extension/perps/select_market_filter.mjs

@@ -1,3 +1,4 @@
+// Select a Perps market category through the dropdown or category rail and inspect the resulting list.
 import { pathToFileURL } from 'node:url';
 
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';

package/library/actions/extension/perps/set_market_favorite.mjs

@@ -1,3 +1,4 @@
+// Set the current market's favorite state through its visible control, or require it to be unchanged.
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 runAdapter(async (input) => withExtensionPage(input, async (page) => {

package/library/actions/extension/perps/state.mjs

@@ -1,3 +1,4 @@
+// Build a page expression that reads Perps provider, network, initialization, and eligibility from state hooks.
 export function readPerpsRuntimeStateExpression() {
   return `(async () => {
     const hooks = globalThis.stateHooks || {};

package/library/actions/extension/perps/update_position_tpsl.mjs

@@ -1,3 +1,5 @@
+// Submit live take-profit and stop-loss changes through visible controls with mutation receipts.
+// Check the funded position identity and observe the exact requested prices.
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import {
   assertTrustedExternalMutationTarget,

package/library/actions/extension/perps/visible-mutation-identity.mjs

@@ -1,3 +1,5 @@
+// Parse and match visible Perps position and order identities using USD base-unit tolerances.
+// Also wait for a stable, loaded Perps home view, optionally requiring zero positions and orders.
 const INTEGER = /^(0|[1-9][0-9]{0,29})$/u;
 
 export function parseUsdBaseUnits(value) {

package/library/actions/extension/platform/cdp.mjs

@@ -1,3 +1,6 @@
+// Provide checkout-bound Extension CDP sessions, page actions and screenshot helpers.
+// Bind browser and service-worker observation to the selected runtime.
+
 import {
   constants,
   access,
@@ -736,6 +739,24 @@ export class ExtensionPage extends CdpWebPage {
     });
   }
 
+  async connectServiceWorker() {
+    const browserVersion = await jsonGet(`http://127.0.0.1:${this.port}/json/version`);
+    const current = extensionRuntimeIdentity({ port: this.port, target: this.target, browserVersion });
+    if (current.runtimeSessionId !== this.runtimeIdentity.runtimeSessionId) {
+      throw new Error('Extension browser changed before service-worker observation.');
+    }
+    const targets = await jsonGet(`http://127.0.0.1:${this.port}/json/list`);
+    const workers = targets.filter((target) => target.type === 'service_worker'
+      && String(target.url).startsWith(`${this.origin}/`));
+    if (workers.length !== 1) throw new Error('Extension requires one matching service worker for order observation.');
+    const worker = workers[0];
+    const socket = new URL(worker.webSocketDebuggerUrl);
+    if (socket.protocol !== 'ws:' || socket.hostname !== '127.0.0.1' || Number(socket.port) !== this.port) {
+      throw new Error('Extension service-worker observation requires this browser localhost endpoint.');
+    }
+    return { session: await CdpSession.connect(socket.href), targetId: worker.id };
+  }
+
   async setInput(selector, value) {
     const input = String(value ?? '');
     const target = await this.evaluate(`(() => {
@@ -747,8 +768,14 @@ export class ExtensionPage extends CdpWebPage {
       if (typeof element.select === 'function') element.select();
       return { tagName: element.tagName, previousLength: String(element.value ?? '').length };
     })()`);
-    await this.session.call('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Backspace' });
-    await this.session.call('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Backspace' });
+    await this.session.call('Input.dispatchKeyEvent', {
+      type: 'keyDown', key: 'Backspace', code: 'Backspace',
+      windowsVirtualKeyCode: 8, nativeVirtualKeyCode: 8,
+    });
+    await this.session.call('Input.dispatchKeyEvent', {
+      type: 'keyUp', key: 'Backspace', code: 'Backspace',
+      windowsVirtualKeyCode: 8, nativeVirtualKeyCode: 8,
+    });
     for (const character of input) {
       const upper = character.toUpperCase();
       const isLetter = /^[A-Z]$/u.test(upper);

package/library/actions/extension/settings/set_basic_functionality.mjs

@@ -1,3 +1,4 @@
+// Sets Basic Functionality in Privacy settings, accepting the disable confirmation when needed.
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 const TOGGLE_SELECTOR = dataTestId('basic-functionality-toggle');

package/library/actions/extension/swap_bridge/quote-state.mjs

@@ -1,3 +1,5 @@
+// Compares exposed bridge quote state with the selected assets and displayed amounts.
+// Requires debug store access to distinguish matching, stale, loading, and unavailable quotes.
 export async function readQuoteInputIdentity(page) {
   return page.evaluate(`(() => {
     const state = globalThis.stateHooks?.store?.getState?.();

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

@@ -1,3 +1,4 @@
+// Reads displayed swap/bridge inputs and quote details, optionally checking quote identity in the store.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { readQuoteInputIdentity } from './quote-state.mjs';
 import {

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

@@ -1,3 +1,4 @@
+// Opens Swap and selects source and destination assets by exact ID or unambiguous chain and symbol.
 import { runAdapter, withExtensionPage, dataTestId } from '../platform/cdp.mjs';
 import { openSwap } from '../ui/navigate.mjs';
 import { resolveAssetSelectionOptions } from '../../shared/swap-bridge/transaction.mjs';

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

@@ -1,3 +1,4 @@
+// Enters a swap/bridge amount and optionally waits for a matching usable quote or an unavailable route.
 import { runAdapter, withExtensionPage, dataTestId } from '../platform/cdp.mjs';
 import { resolveAmountOptions } from '../../shared/swap-bridge/transaction.mjs';
 import { readQuoteInputIdentity } from './quote-state.mjs';

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

@@ -1,3 +1,4 @@
+// Uses the visible Max control and optionally waits for a matching usable quote or an unavailable route.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { resolveAmountOptions } from '../../shared/swap-bridge/transaction.mjs';
 import { requireVisibleObservation } from '../../shared/ui/locators.mjs';

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

@@ -1,3 +1,4 @@
+// Saves custom swap/bridge slippage and waits for the displayed quote and submit control to refresh.
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 async function pause(page) {

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

@@ -1,3 +1,4 @@
+// Derives locator candidates from the Extension page's current visible-UI observation.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import {
   locatorsFromObservation,

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

@@ -1,3 +1,5 @@
+// Opens named wallet screens through UI controls or history, and accepts direct URL/hash navigation.
+// Named navigation may dismiss tutorials or drawers and add a missing network before selecting its filter.
 import { pathToFileURL } from 'node:url';
 
 import {

package/library/actions/extension/wallet/ensure_unlocked.mjs

@@ -1,3 +1,5 @@
+// Unlocks an existing wallet with the supplied or fixture password when a password input is present.
+// Rejects onboarding profiles and waits for the password input to disappear after submission.
 import { readFile } from 'node:fs/promises';
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';

package/library/actions/extension/wallet/import.mjs

@@ -1,3 +1,5 @@
+// Imports a wallet through onboarding or verifies an existing profile against the expected account.
+// May unlock the wallet, finish onboarding, and select the expected account through visible UI.
 import { resolveWalletImportCredentials, validateWalletImportOptions, walletImportMethod } from '../../shared/wallet/import-source.mjs';
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { pasteSecretRecoveryPhrase, setSecretInput } from './secret-input.mjs';

package/library/actions/extension/wallet/list_accounts.mjs

@@ -1,3 +1,4 @@
+// Lists account identities from Extension state hooks, filtered by selected, named, EVM, or all scope.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { listWalletAccountsExpression } from './state.mjs';
 

package/library/actions/extension/wallet/lock.mjs

@@ -1,3 +1,5 @@
+// Locks the wallet through visible menu controls and waits for the unlock page.
+// Opens Home first when the account menu is unavailable.
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 const MENU = dataTestId('account-options-menu-button');

package/library/actions/extension/wallet/read_state.mjs

@@ -1,3 +1,4 @@
+// Reads wallet identity, onboarding, and network state from state hooks alongside the password-input marker.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { readWalletStateExpression } from './state.mjs';
 

package/library/actions/extension/wallet/reset.mjs

@@ -1,3 +1,5 @@
+// Clears the wallet through the visible forgot-password reset flow unless it is already fresh.
+// Checks that onboarding is incomplete, the route is onboarding, and no account is selected.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { readWalletStateExpression } from './state.mjs';
 

package/library/actions/extension/wallet/secret-input.mjs

@@ -1,3 +1,5 @@
+// Enters wallet secrets through CDP input events and checks their retained length.
+// Recovery-phrase paste reloads the page to install a temporary clipboard bridge, then removes it.
 export async function setSecretInput(page, selector, value) {
   const found = await page.evaluate(`(() => {
     const element = document.querySelector(${JSON.stringify(selector)});

package/library/actions/extension/wallet/select_account.mjs

@@ -1,3 +1,5 @@
+// Selects an account by address, ID, or name through the background request hook.
+// Falls back to visible account search when that hook is unavailable and checks the selected address.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import {
   listWalletAccountsExpression,

package/library/actions/extension/wallet/setup.mjs

@@ -1,3 +1,4 @@
+// Checks for a seeded wallet profile via a password input or completed onboarding with a selected account.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { readWalletStateExpression } from './state.mjs';
 

package/library/actions/extension/wallet/state.mjs

@@ -1,3 +1,5 @@
+// Builds page expressions for reading wallet/account state and changing the selected account through state hooks.
+// Account selection sends a background request and polls until the selected ID matches.
 const walletStatePreamble = `
     const readWalletState = async () => {
       const hooks = globalThis.stateHooks || {};

package/library/actions/extension/wallet/visible-session.mjs

@@ -1,3 +1,5 @@
+// Dismisses onboarding completion and navigates the account list to select and check an expected EVM account.
+// Validates address search with an alternate-address control and returns a hash of the matched identity.
 import { createHash } from 'node:crypto';
 
 const ACCOUNT_SEARCH = 'input[data-testid="multichain-account-list-search"], [data-testid="multichain-account-list-search"] input';

package/library/actions/mobile/analytics/consent-settings.mjs

@@ -1,3 +1,4 @@
+// Set analytics and marketing consent through Settings switch handlers, then verify stored consent.
 import { evalAsync, navigate } from '../platform/bridge.mjs';
 
 const SWITCH_IDS = {

package/library/actions/mobile/analytics/set_consent.mjs

@@ -1,3 +1,4 @@
+// Apply requested Mobile analytics consent and return the verified Settings result.
 import { runAdapter } from '../platform/bridge.mjs';
 import { consentParams } from '../../shared/analytics/consent.mjs';
 import { setMobileConsent } from './consent-settings.mjs';

package/library/actions/mobile/app/network-control.mjs

@@ -1,3 +1,5 @@
+// Toggle airplane mode on the selected Android device and verify the requested state.
+// Foreground MetaMask if needed and wait for the configured settling period.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 

package/library/actions/mobile/app/network.mjs

@@ -1,3 +1,4 @@
+// Run the Android network-state action, which toggles airplane mode and ensures app focus.
 import { runAdapter } from '../platform/bridge.mjs';
 import { setMobileNetworkState } from './network-control.mjs';
 

package/library/actions/mobile/app/network_assert.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Expose shared network-capture assertions through the Mobile action runner.
 import { pathToFileURL } from 'node:url';
 
 import { assertNetwork } from '../../shared/app/network-assert.mjs';

package/library/actions/mobile/app/network_capture.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Start or end filtered Mobile network capture through the bridge and save the summary artifact.
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';

package/library/actions/mobile/assets/import_custom_token.mjs

@@ -1,3 +1,5 @@
+// Import an ERC-20 token through the native form after checking its resolved metadata.
+// Confirm the imported symbol appears in the token list.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/assets/open_details.mjs

@@ -1,3 +1,4 @@
+// Open a token's native details view and wait for the requested symbol to appear.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/assets/read_details.mjs

@@ -1,3 +1,4 @@
+// Check visible token details for a formatted price and optional chart or market cap requirements.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/assets/read_visible_state.mjs

@@ -1,3 +1,4 @@
+// Normalize token rows from Mobile accessibility observations into visible asset state.
 import { runAdapter } from '../platform/bridge.mjs';
 import { observeNativeUi } from '../platform/observe-ui.mjs';
 import {

package/library/actions/mobile/assets/set_token_visibility.mjs

@@ -1,3 +1,5 @@
+// Import or remove a token through native controls and check its resulting visibility state.
+// Reject ambiguous symbol matches and unsupported exact asset IDs.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/assets/verify_sorting.mjs

@@ -1,3 +1,5 @@
+// Switch token sorting to check alphabetical and declining fiat order in visible rows.
+// Restore the original sort preference and report restoration failures.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,
@@ -31,7 +33,8 @@ function assetRows(snapshot) {
 
 function isAlphabetical(rows) {
   const names = rows.map((row) => row.name);
-  const expected = [...names].sort((left, right) => left.localeCompare(right, 'en', { sensitivity: 'base' }));
+  // MetaMask's SES lockdown compares names by UTF-16 code units.
+  const expected = [...names].sort();
   return names.length >= 2 && names.every((name, index) => name === expected[index]);
 }
 
@@ -40,18 +43,78 @@ function isDeclining(rows) {
   return values.length >= 2 && values.every((value, index) => index === 0 || values[index - 1] >= value);
 }
 
-async function choose(session, option, timeoutMs) {
+async function openSortMenu(session, timeoutMs) {
+  if (sessionNode(await session.snapshot(), 'sort-alphabetical')) return;
   await session.execute('ui.press', { test_id: 'token-sort-button', timeout_ms: timeoutMs, settle: false });
+}
+
+async function selectedSort(session, timeoutMs) {
+  await openSortMenu(session, timeoutMs);
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const snapshot = await session.snapshot();
+    const byIndex = new Map(snapshot.nodes.map((node) => [node.index, node]));
+    const selected = ['sort-alphabetical', 'sort-declining-balance'].filter((option) => {
+      const row = sessionNode(snapshot, option);
+      if (!row) return false;
+      // ListItemSelect renders a checkbox child only for the selected option.
+      return snapshot.nodes.some((node) => {
+        if (node.visibleToUser === false || !/checkbox$/iu.test(String(node.type))) return false;
+        let parent = byIndex.get(node.parentIndex);
+        for (let depth = 0; depth < 40 && parent; depth += 1) {
+          if (parent.index === row.index) return true;
+          parent = byIndex.get(parent.parentIndex);
+        }
+        return false;
+      });
+    });
+    if (selected.length === 1) return selected[0];
+    if (Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 200));
+  } while (Date.now() < deadline);
+  throw new Error('Asset sort preference is unavailable or ambiguous.\nNext: mm-harness call ui.screenshot --adapter mobile');
+}
+
+async function choose(session, option, timeoutMs) {
+  await openSortMenu(session, timeoutMs);
   await session.execute('ui.press', { test_id: option, timeout_ms: timeoutMs, settle: false });
   const deadline = Date.now() + timeoutMs;
   let rows = [];
   while (Date.now() <= deadline) {
     const snapshot = await session.snapshot();
     rows = assetRows(snapshot);
-    if (rows.length >= 2 && !sessionNode(snapshot, option)) return rows;
+    const ordered = option === 'sort-alphabetical' ? isAlphabetical(rows) : isDeclining(rows);
+    if (ordered && !sessionNode(snapshot, option)) return rows;
     await new Promise((resolve) => setTimeout(resolve, 200));
   }
-  throw new Error(`Asset sort ${option} did not return to a visible token list: ${JSON.stringify(rows)}.`);
+  throw new Error(`Asset sort ${option} did not produce the expected visible row order: ${JSON.stringify(rows)}.`);
+}
+
+async function visibleTokenList(session, deadline) {
+  while (Date.now() <= deadline) {
+    const snapshot = await session.snapshot();
+    if (!sessionNode(snapshot, 'sort-alphabetical')
+      && sessionNode(snapshot, 'token-sort-button') && assetRows(snapshot).length >= 2) return;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  throw new Error('Asset token list was not visible after restoring the sort preference.\nNext: mm-harness call ui.screenshot --adapter mobile');
+}
+
+async function restoreSort(session, option, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const remaining = () => {
+    const ms = deadline - Date.now();
+    if (ms <= 0) throw new Error('Asset sort restoration timed out.\nNext: mm-harness call ui.screenshot --adapter mobile');
+    return ms;
+  };
+  if (await selectedSort(session, remaining()) !== option) {
+    await session.execute('ui.press', { test_id: option, timeout_ms: remaining(), settle: false });
+    await visibleTokenList(session, deadline);
+    if (await selectedSort(session, remaining()) !== option) {
+      throw new Error('Asset sort preference was not restored.\nNext: mm-harness call ui.screenshot --adapter mobile');
+    }
+  }
+  await session.execute('ui.press', { test_id: option, timeout_ms: remaining(), settle: false });
+  await visibleTokenList(session, deadline);
 }
 
 async function revealTokenList(session, timeoutMs) {
@@ -76,9 +139,13 @@ function sessionNode(snapshot, identifier) {
 runAdapter(async (input) => {
   const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
   const session = createNativeSession(input, 'Assets', `sort-${process.pid}`);
+  const errors = [];
+  let initialSort;
+  let result;
   try {
     await session.open();
     await revealTokenList(session, timeoutMs);
+    initialSort = await selectedSort(session, timeoutMs);
     const alphabetical = await choose(session, 'sort-alphabetical', timeoutMs);
     const declining = await choose(session, 'sort-declining-balance', timeoutMs);
     const failures = [];
@@ -91,14 +158,30 @@ runAdapter(async (input) => {
     if (failures.length > 0) {
       throw new Error(`Asset token sorting failed: ${failures.join('; ')}.`);
     }
-    return {
+    result = {
       action: input.action,
       alphabetical: alphabetical.map((row) => row.name),
       decliningFiat: declining.map((row) => row.fiat),
-      restoredSort: 'declining-balance',
+      initialSort: initialSort.slice('sort-'.length),
+      restoredSort: initialSort.slice('sort-'.length),
       proofPath: 'native-accessibility-token-sorting',
     };
-  } finally {
+  } catch (error) {
+    errors.push(error);
+  }
+  if (initialSort) {
+    try {
+      await restoreSort(session, initialSort, timeoutMs);
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  try {
     await closeNativeSession(session);
+  } catch (error) {
+    errors.push(error);
   }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, `Asset sorting failed: ${errors.map((error) => error.message).join('; ')}`);
+  return result;
 });

package/library/actions/mobile/deeplink/open.mjs

@@ -1,3 +1,4 @@
+// Open a validated external deeplink through the selected device's OS URL handler.
 import {
   externalDeeplinkTimeout,
   externalDeeplinkUrl,

package/library/actions/mobile/networks/add_custom.mjs

@@ -1,3 +1,4 @@
+// Add a missing custom network through native Settings and verify its saved row.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/networks/network-management.mjs

@@ -1,3 +1,4 @@
+// Navigate native Network Settings and search for network rows by chain ID and name.
 import { nativeLabel, nativeNode } from '../platform/native-session.mjs';
 
 const IDS = {

package/library/actions/mobile/networks/read_visible_state.mjs

@@ -1,3 +1,4 @@
+// Open Network Settings and locate a network, optionally rechecking it after a settling period.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/networks/remove_custom.mjs

@@ -1,3 +1,4 @@
+// Delete a custom network through native Settings and wait for its row to disappear.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/perps/assert_orders.mjs

@@ -1,3 +1,4 @@
+// Assert that selected Perps orders are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders } from './perps.mjs';
 

package/library/actions/mobile/perps/assert_positions.mjs

@@ -1,3 +1,4 @@
+// Assert that selected Perps positions are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions } from './perps.mjs';
 

package/library/actions/mobile/perps/capture_performance.mjs

@@ -1,3 +1,4 @@
+// Start or end a Perps performance log capture, writing artifacts and checking required events at end.
 import { runAdapter } from '../platform/bridge.mjs';
 import { capturePerpsPerformance } from './performance-capture.mjs';
 

package/library/actions/mobile/perps/close_orders.mjs

@@ -1,3 +1,4 @@
+// Cancel selected Perps orders through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders, closeOrders } from './perps.mjs';
 

package/library/actions/mobile/perps/close_positions.mjs

@@ -1,3 +1,4 @@
+// Close selected Perps positions through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions, closePositions } from './perps.mjs';
 

package/library/actions/mobile/perps/ensure_orders.mjs

@@ -1,3 +1,4 @@
+// Create a limit order when none matches, or cancel selected orders, then assert the requested state.
 import { runAdapter } from '../platform/bridge.mjs';
 import { ensureOrders } from './perps.mjs';
 

package/library/actions/mobile/perps/ensure_positions.mjs

@@ -1,3 +1,4 @@
+// Submit an order when no position matches, or close selected positions, then assert the requested state.
 import { runAdapter } from '../platform/bridge.mjs';
 import { ensurePositions } from './perps.mjs';
 

package/library/actions/mobile/perps/measure_homepage_visible.mjs

@@ -1,3 +1,4 @@
+// Unlock the wallet and measure the scroll transition until a requested homepage target becomes visible.
 import { runAdapter } from '../platform/bridge.mjs';
 import { measureHomepageVisible } from './perps.mjs';
 

package/library/actions/mobile/perps/performance-capture.mjs

@@ -1,3 +1,5 @@
+// Capture a bounded section of Perps console logs and write performance measurements and validation artifacts.
+// Persist the start offset and file identity to reject replaced or rewritten logs when the capture ends.
 import { createHash } from "node:crypto";
 import { mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";

package/library/actions/mobile/perps/perps.mjs

@@ -1,3 +1,5 @@
+// Implement Mobile Perps navigation, trading mutations, assertions, and setup or cleanup through the bridge.
+// Strategy getters used during cleanup can settle tracked collateral.
 import { pathToFileURL } from 'node:url';
 import {
   MOBILE_BRIDGE_RESULT_ERROR_CODES,
@@ -1771,7 +1773,7 @@ async function applyTutorialState(input, config) {
 
 export async function startState(input) {
   if (input.node?.account !== undefined && (typeof input.node.account !== 'string' || !input.node.account.trim())) {
-    throw new Error('Perps start state requires a non-empty named account when account is supplied.\nNext: mm-harness actions metamask.perps.start_state --adapter mobile --json');
+    throw new Error('Perps start state requires a non-empty account name or address when account is supplied.\nNext: mm-harness actions metamask.perps.start_state --adapter mobile --json');
   }
   const params = paramsForState(input);
   const config = applyTradingStatePolicy(
@@ -1831,7 +1833,9 @@ export async function startState(input) {
       node: {
         ...accountInput.node,
         action: 'metamask.wallet.select_account',
-        name: config.account.trim(),
+        ...(/^0x[0-9a-f]{40}$/iu.test(config.account.trim())
+          ? { address: config.account.trim() }
+          : { name: config.account.trim() }),
       },
     })
     : { skipped: true };

package/library/actions/mobile/perps/place_order.mjs

@@ -1,3 +1,4 @@
+// Submit a Perps order through the Mobile controller and assert a matching open position.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions, placeOrder } from './perps.mjs';
 runAdapter(async (input) => {

package/library/actions/mobile/perps/prepare_local_snapshot_endpoint.mjs

@@ -1,3 +1,5 @@
+// Apply and verify an adb reverse mapping for a local snapshot port on the selected Android device.
+// Skip the mapping when no Android serial is configured.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 

package/library/actions/mobile/perps/read-visible-state-loop.mjs

@@ -1,3 +1,5 @@
+// Poll native screen and accessibility observations until Perps state satisfies the requested checks.
+// Return normalized state or report the last assertion or observation failure at the deadline.
 import { observeNativeUi } from '../platform/observe-ui.mjs';
 import {
   normalizeVisiblePerpsState,

package/library/actions/mobile/perps/read_orders.mjs

@@ -1,3 +1,4 @@
+// Return selected open Perps orders with redacted fields and counts from the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { readOrders } from './perps.mjs';
 

package/library/actions/mobile/perps/read_positions.mjs

@@ -1,3 +1,4 @@
+// Return selected Perps positions with redacted fields and counts from the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { readPerpsPositions } from './perps.mjs';
 runAdapter(readPerpsPositions);

package/library/actions/mobile/perps/read_visible_state.mjs

@@ -1,3 +1,4 @@
+// Read Perps state from native accessibility observations, waiting for requested assertions to pass.
 import { runAdapter } from '../platform/bridge.mjs';
 import { readVisiblePerpsState } from './read-visible-state-loop.mjs';