@deeeed/metamask-harness 0.47.4 → 0.49.0

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 {
@@ -8,6 +10,7 @@ import {
 } from '../platform/cdp.mjs';
 
 const BACK_CONTROLS = [
+  'custom-token-import-close-button',
   'perps-order-entry-back-button',
   'perps-market-detail-back-button',
   'perps-activity-back-button',
@@ -23,6 +26,18 @@ const BACK_CONTROLS = [
 ].map(dataTestId).concat('button[aria-label="Back"]');
 const UI_POLL_MS = 200;
 const PERPS_HOME_SETTLE_MS = 1000;
+const PERPS_MARKET_LIST = [
+  'market-list-view',
+  'parent-selector-perps-market-list',
+].map(dataTestId).join(',');
+const PERPS_MARKET_DETAIL = [
+  'perps-market-detail-page',
+  'parent-selector-perps-market-detail',
+].map(dataTestId).join(',');
+const PERPS_ACTIVITY = [
+  'perps-activity-page',
+  'parent-selector-perps-activity',
+].map(dataTestId).join(',');
 
 function text(value) {
   return typeof value === 'string' && value.length > 0 ? value : undefined;
@@ -68,6 +83,7 @@ async function hasVisibleSelector(page, selector) {
   return page.evaluate(`(() => {
     const element = document.querySelector(${JSON.stringify(selector)});
     if (!element) return false;
+    if (element.closest('dialog')?.open === false) return false;
     const style = getComputedStyle(element);
     const rect = element.getBoundingClientRect();
     return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
@@ -116,6 +132,13 @@ export async function openHome(page, timeoutMs) {
   let pendingActivation;
 
   while (Date.now() < deadline) {
+    const importNetworkClose = '[data-testid="custom-token-import-network-selector"] button[aria-label="Close"]';
+    if (await hasVisibleSelector(page, importNetworkClose)) {
+      await activateSemanticControl(page, importNetworkClose);
+      steps.push(importNetworkClose);
+      await pauseForUi(page);
+      continue;
+    }
     if (await hasVisibleSelector(page, drawerClose)) {
       await activateSemanticControl(page, drawerClose);
       steps.push(drawerClose);
@@ -274,11 +297,11 @@ export async function openPerpsHome(page, timeoutMs) {
 export async function openPerpsMarket(page, market, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   const normalizedMarket = normalizeMarketSymbol(market.trim());
-  if (await hasVisibleSelector(page, dataTestId('market-list-view'))) {
+  if (await hasVisibleSelector(page, PERPS_MARKET_LIST)) {
     const marketRow = dataTestId(`market-row-${normalizedMarket.replace(':', '-')}`);
     await page.waitForSelector(marketRow, { timeoutMs: Math.max(1, deadline - Date.now()) });
     const navigation = await activateSemanticControl(page, marketRow);
-    await page.waitForSelector(dataTestId('perps-market-detail-page'), {
+    await page.waitForSelector(PERPS_MARKET_DETAIL, {
       timeoutMs: Math.max(1, deadline - Date.now()),
     });
     return {
@@ -308,7 +331,7 @@ export async function openPerpsMarket(page, market, timeoutMs) {
     );
   }
   const navigation = await activateSemanticControl(page, marketControl);
-  await page.waitForSelector(dataTestId('perps-market-detail-page'), {
+  await page.waitForSelector(PERPS_MARKET_DETAIL, {
     timeoutMs: Math.max(1, deadline - Date.now()),
   });
   return {
@@ -321,7 +344,7 @@ export async function openPerpsMarket(page, market, timeoutMs) {
 }
 
 export async function openPerpsActivity(page, timeoutMs) {
-  if (await hasVisibleSelector(page, dataTestId('perps-activity-page'))) {
+  if (await hasVisibleSelector(page, PERPS_ACTIVITY)) {
     return { method: 'visible-ui', href: await currentHref(page), steps: [] };
   }
   const deadline = Date.now() + timeoutMs;
@@ -329,7 +352,7 @@ export async function openPerpsActivity(page, timeoutMs) {
   const activity = dataTestId('perps-recent-activity-see-all');
   await page.waitForSelector(activity, { timeoutMs: Math.max(1, deadline - Date.now()) });
   const navigation = await activateSemanticControl(page, activity);
-  await page.waitForSelector(dataTestId('perps-activity-page'), {
+  await page.waitForSelector(PERPS_ACTIVITY, {
     timeoutMs: Math.max(1, deadline - Date.now()),
   });
   return {
@@ -342,7 +365,7 @@ export async function openPerpsActivity(page, timeoutMs) {
 }
 
 export async function openPerpsMarketList(page, timeoutMs) {
-  const marketList = dataTestId('market-list-view');
+  const marketList = PERPS_MARKET_LIST;
   if (await hasVisibleSelector(page, marketList)) {
     return { method: 'visible-ui', href: await currentHref(page), steps: [] };
   }
@@ -417,17 +440,37 @@ export async function openNetwork(page, network, chainId, addIfMissing, timeoutM
       throw new Error('Token assets did not become selected before network navigation.');
     }
   }
-  await activateSemanticControl(page, sort);
-  steps.push(sort);
+  if (!(await hasVisibleSelector(page, dataTestId('home-network-filter-all-default')))) {
+    await activateSemanticControl(page, sort);
+    steps.push(sort);
+  }
   let choice = await waitForFirstVisible(page, [installed, custom, additional, manage], deadline);
   if (!choice) throw new Error(`Network filter did not show ${network} (${chainId}) before timeout.`);
-  if (choice !== manage) {
+  if (!addIfMissing && (choice === additional || choice === manage)) {
+    throw new Error(`Network ${network} (${chainId}) is not added to the wallet.`);
+  }
+  let added = false;
+  if (choice === additional) {
+    await page.scroll({ selector: additional, intoView: true });
+    await page.waitFor({ selector: additional, expected: 'visible', timeoutMs: Math.max(1, deadline - Date.now()) });
+    await activateSemanticControl(page, additional);
+    steps.push(additional);
+    await page.waitFor({ selector: additional, expected: 'hidden', timeoutMs: Math.max(1, deadline - Date.now()) });
+    await activateSemanticControl(page, sort);
+    steps.push(sort);
+    choice = await waitForFirstVisible(page, [installed, custom], deadline);
+    if (!choice) throw new Error(`Added network ${network} (${chainId}) did not appear in the wallet filter.`);
+    await page.scroll({ selector: choice, intoView: true });
+    await page.waitFor({ selector: choice, expected: 'visible', timeoutMs: Math.max(1, deadline - Date.now()) });
+    await activateSemanticControl(page, choice);
+    steps.push(choice);
+    added = true;
+  } else if (choice !== manage) {
+    await page.scroll({ selector: choice, intoView: true });
+    await page.waitFor({ selector: choice, expected: 'visible', timeoutMs: Math.max(1, deadline - Date.now()) });
     await activateSemanticControl(page, choice);
     steps.push(choice);
   } else {
-    if (!addIfMissing) {
-      throw new Error(`Network ${network} (${chainId}) is not added to the wallet.`);
-    }
     await activateSemanticControl(page, manage);
     steps.push(manage);
     const listItem = dataTestId(`network-list-item-eip155:${chainId}`);
@@ -437,6 +480,7 @@ export async function openNetwork(page, network, chainId, addIfMissing, timeoutM
       await activateSemanticControl(page, popular);
       steps.push(popular);
       await page.waitForSelector(listItem, { timeoutMs: Math.max(1, deadline - Date.now()) });
+      added = true;
     }
     const back = dataTestId('page-header-back-button');
     await activateSemanticControl(page, back);
@@ -444,15 +488,17 @@ export async function openNetwork(page, network, chainId, addIfMissing, timeoutM
     await page.waitForSelector(sort, { timeoutMs: Math.max(1, deadline - Date.now()) });
     await activateSemanticControl(page, sort);
     steps.push(sort);
-    choice = await waitForFirstVisible(page, [installed, custom, additional], deadline);
+    choice = await waitForFirstVisible(page, [installed, custom], deadline);
     if (!choice) throw new Error(`Added network ${network} (${chainId}) did not appear in the wallet filter.`);
+    await page.scroll({ selector: choice, intoView: true });
+    await page.waitFor({ selector: choice, expected: 'visible', timeoutMs: Math.max(1, deadline - Date.now()) });
     await activateSemanticControl(page, choice);
     steps.push(choice);
   }
   while (Date.now() < deadline) {
     const label = await page.evaluate(`String(document.querySelector(${JSON.stringify(sort)})?.innerText || '')`);
     if (label.toLowerCase().includes(network.toLowerCase())) {
-      return { method: 'visible-ui', href: await currentHref(page), network, chainId, steps };
+      return { method: 'visible-ui', href: await currentHref(page), network, chainId, added, steps };
     }
     await pauseForUi(page);
   }

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');
@@ -21,6 +23,7 @@ async function clickUncovered(page, selector, deadline) {
     point = await page.evaluate(`(() => {
       const element = document.querySelector(${JSON.stringify(selector)});
       if (!element) return null;
+      element.scrollIntoView({ block: 'center', inline: 'center' });
       const style = getComputedStyle(element);
       const rect = element.getBoundingClientRect();
       if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0) return null;
@@ -74,7 +77,7 @@ export async function lockWallet(page, timeoutMs = 15_000) {
     if (Date.now() >= deadline) throw new Error('Wallet lock control did not become visible.');
     await page.evaluate('new Promise((resolve) => setTimeout(resolve, 100))');
   }
-  await page.click(LOCK);
+  await clickUncovered(page, LOCK, deadline);
   while (!(await visible(page, UNLOCK_PAGE))) {
     if (Date.now() >= deadline) throw new Error('Wallet did not reach the unlock page after locking.');
     await page.evaluate('new Promise((resolve) => setTimeout(resolve, 100))');

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,
@@ -168,6 +170,7 @@ runAdapter(async (input) => {
     const token = await findTokenRow(session, expectedSymbol, timeoutMs);
     return {
       action: input.action,
+      changed: true,
       network,
       chainId,
       address,

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 {
@@ -17,7 +18,7 @@ runAdapter(async (input) => {
     const warning = observed.warnings?.map((entry) => entry.message).filter(Boolean).join('; ');
     throw new Error(`Mobile visible Assets state is unavailable${warning ? `: ${warning}` : '.'}`);
   }
-  const items = [...(visible.items ?? []), ...(visible.hidden_or_offscreen ?? [])]
+  const items = (visible.items ?? [])
     .filter((item) => String(item.test_id ?? '').startsWith('asset-'))
     .map((item) => ({
       testId: item.test_id,
@@ -32,6 +33,8 @@ runAdapter(async (input) => {
       items,
       truncated: visible.truncated,
     }, options, 'mobile'),
+    observationProvider: visible.provider ?? screen.provider,
+    deviceId: screen.deviceId,
     proofPath: 'native-accessibility',
   };
 });

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,
@@ -25,25 +27,24 @@ function descendants(snapshot, root) {
 
 function searchedToken(snapshot, query) {
   const normalized = query.toUpperCase();
-  const rows = snapshot.nodes.filter((node) => node.identifier === 'searched-token-result');
+  const rows = snapshot.nodes.filter((node) => node.identifier === 'searched-token-result' && node.visibleToUser !== false);
+  const matches = [];
   for (const row of rows) {
     const children = descendants(snapshot, row);
-    const label = children.map(nativeLabel).find((value) => {
+    const label = [nativeLabel(row), ...children.map(nativeLabel)].find((value) => {
       const parts = value.split(',').map((part) => part.trim().toUpperCase());
       return parts.includes(normalized);
     });
     if (label) {
-      return {
+      matches.push({
         row,
         label,
         imported: row.enabled === false && children.some((node) => /CheckBox$/u.test(String(node.type))),
-      };
+      });
     }
   }
-  const imported = rows.find((row) =>
-    row.enabled === false && descendants(snapshot, row).some((node) => /CheckBox$/u.test(String(node.type)))
-  );
-  return imported ? { row: imported, label: query, imported: true } : null;
+  if (matches.length > 1) throw new Error(`Mobile token search matched ${matches.length} rows for ${query}; token identity is ambiguous.\nNext: mm-harness actions --action metamask.assets.set_token_visibility --json`);
+  return matches[0] ?? null;
 }
 
 function visibleNode(snapshot, identifier) {
@@ -201,7 +202,9 @@ async function findVisibleAsset(session, query, timeoutMs) {
     )).snapshot;
   }
   for (let attempt = 0; attempt < 8; attempt += 1) {
-    if (nativeNode(snapshot, `asset-${query.toUpperCase()}`)) return true;
+    const matches = snapshot.nodes.filter(node => node.identifier === `asset-${query.toUpperCase()}` && node.visibleToUser !== false);
+    if (matches.length > 1) throw new Error(`Mobile token list matched ${matches.length} rows for ${query}; removal is ambiguous.\nNext: mm-harness actions --action metamask.assets.set_token_visibility --json`);
+    if (matches.length === 1) return true;
     await session.execute('ui.scroll', { direction: 'down', timeout_ms: timeoutMs, settle: false });
     snapshot = await session.snapshot();
   }
@@ -271,6 +274,9 @@ async function disableToken(session, query, requireUnchanged, requireChange, tim
 }
 
 runAdapter(async (input) => {
+  if (String(input.node?.asset_id ?? '').trim()) {
+    throw new Error('Exact asset-ID corroboration is not supported on Mobile.\nNext: mm-harness actions --adapter mobile --action metamask.assets.set_token_visibility --json');
+  }
   const query = String(input.node?.query ?? '').trim();
   const timeoutMs = Number(input.node?.timeout_ms ?? 45_000);
   const requested = input.node?.visible;

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 = {
@@ -26,6 +27,10 @@ export async function waitForSnapshot(session, timeoutMs, predicate, message) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() <= deadline) {
     const snapshot = await session.snapshot();
+    const labels = snapshot.nodes.map(nativeLabel);
+    if (labels.includes('Reload') && labels.includes('Go home') && labels.includes('Tools button')) {
+      throw new Error('Mobile network navigation opened the Expo developer menu instead of the requested control.\nNext: mm-harness call ui.key_press key=BACK --adapter mobile');
+    }
     const value = predicate(snapshot);
     if (value) return { snapshot, value };
     await new Promise((resolve) => setTimeout(resolve, 200));
@@ -42,23 +47,26 @@ async function systemBack(session) {
 }
 
 export async function openNetworkManager(session, timeoutMs) {
-  for (let attempt = 0; attempt < 8; attempt += 1) {
-    const snapshot = await session.snapshot();
-    if (visibleNode(snapshot, IDS.manager)) return snapshot;
-    if (visibleNode(snapshot, IDS.details)) {
-      await systemBack(session);
-      continue;
-    }
-    if (visibleNode(snapshot, IDS.menu)) {
-      await session.execute('ui.press', { test_id: IDS.menu, timeout_ms: timeoutMs, settle: false });
-      continue;
-    }
-    if (IDS.wallet.some((identifier) => nativeNode(snapshot, identifier))) {
-      await session.execute('ui.press', { test_id: IDS.hamburger, timeout_ms: timeoutMs, settle: false });
-      continue;
-    }
+  const snapshot = await session.snapshot();
+  if (visibleNode(snapshot, IDS.manager)) return snapshot;
+  if (visibleNode(snapshot, IDS.details)) {
     await systemBack(session);
+    return (await waitForSnapshot(
+      session, timeoutMs, (current) => visibleNode(current, IDS.manager),
+      'Mobile Networks settings did not return from network details.',
+    )).snapshot;
+  }
+  if (!visibleNode(snapshot, IDS.menu)) {
+    if (!IDS.wallet.some((identifier) => nativeNode(snapshot, identifier))) {
+      throw new Error('Mobile network navigation requires Home, the account menu, or network settings.');
+    }
+    await session.execute('ui.press', { test_id: IDS.hamburger, timeout_ms: timeoutMs, settle: false });
+    await waitForSnapshot(
+      session, timeoutMs, (current) => visibleNode(current, IDS.menu),
+      'The Mobile account menu did not expose the Networks control after opening.',
+    );
   }
+  await session.execute('ui.press', { test_id: IDS.menu, timeout_ms: timeoutMs, settle: false });
   return (await waitForSnapshot(
     session,
     timeoutMs,

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,