@deeeed/metamask-harness 0.37.0 → 0.38.0

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

@@ -12,8 +12,15 @@ const BACK_CONTROLS = [
   'perps-market-detail-back-button',
   'perps-activity-back-button',
   'perps-withdraw-back-button',
+  'wallet-initiated-header-back-button',
+  'transaction-details-back-button',
+  'asset__back',
+  'token-management-header-back-button',
+  'custom-token-import-back-button',
+  'networks-page-form-back-button',
+  'page-header-back-button',
   'back-button',
-].map(dataTestId);
+].map(dataTestId).concat('button[aria-label="Back"]');
 
 function text(value) {
   return typeof value === 'string' && value.length > 0 ? value : undefined;
@@ -22,13 +29,37 @@ function text(value) {
 function pageIntent(node) {
   const page = text(node?.page);
   if (!page) return undefined;
-  if (page === 'home' || page === 'perps') return { page };
+  if (page === 'back' || page === 'home' || page === 'perps' || page === 'swap') return { page };
+  if (page === 'perps-market-list' || page === 'perps-activity') return { page };
+  if (page === 'network') {
+    const network = text(node.network);
+    const chainId = Number(node.chain_id);
+    if (!network || !Number.isInteger(chainId) || chainId <= 0) {
+      throw new Error('extension ui.navigate page=network requires network and a positive integer chain_id.');
+    }
+    return { page, network, chainId, addIfMissing: node.add_if_missing !== false };
+  }
   if (page === 'perps-market') {
     const market = text(node.market) ?? text(node.symbol);
     if (!market) throw new Error('extension ui.navigate page=perps-market requires market or symbol.');
     return { page, market };
   }
-  throw new Error('extension ui.navigate supported page intents: home, perps, perps-market.');
+  throw new Error('extension ui.navigate supported page intents: back, home, network, perps, perps-market-list, perps-market, perps-activity, swap.');
+}
+
+async function goBack(page, timeoutMs) {
+  const before = await currentHref(page);
+  const history = await page.session.call('Page.getNavigationHistory');
+  const entry = history.entries?.[history.currentIndex - 1];
+  if (!entry) throw new Error('extension ui.navigate page=back has no previous browser history entry.');
+  await page.session.call('Page.navigateToHistoryEntry', { entryId: entry.id });
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const href = await currentHref(page);
+    if (href !== before) return { method: 'browser-history', href, previousHref: before };
+    await pauseForUi(page);
+  }
+  throw new Error(`extension ui.navigate page=back did not leave ${JSON.stringify(before)}.`);
 }
 
 async function hasVisibleSelector(page, selector) {
@@ -59,6 +90,12 @@ async function currentHref(page) {
   return page.evaluate('location.href');
 }
 
+function isHomeHref(href) {
+  const hash = href.includes('#') ? href.slice(href.indexOf('#')) : '';
+  const route = hash.split('?')[0];
+  return route === '' || route === '#' || route === '#/';
+}
+
 async function activateSemanticControl(page, selector) {
   return {
     activation: 'trusted-pointer',
@@ -68,6 +105,7 @@ async function activateSemanticControl(page, selector) {
 
 export async function openHome(page, timeoutMs) {
   const home = dataTestId('bottom-nav-home');
+  const drawerClose = dataTestId('drawer-close-button');
   const selectedHome = `${home}[aria-current="page"]`;
   const legacyHome = dataTestId('account-overview__asset-tab');
   const selectedLegacyHome = `${legacyHome}[aria-selected="true"]`;
@@ -76,13 +114,20 @@ export async function openHome(page, timeoutMs) {
   let pendingActivation;
 
   while (Date.now() < deadline) {
+    if (await hasVisibleSelector(page, drawerClose)) {
+      await activateSemanticControl(page, drawerClose);
+      steps.push(drawerClose);
+      await pauseForUi(page);
+      continue;
+    }
+    const href = await currentHref(page);
     if (
-      (await hasVisibleSelector(page, selectedHome)) ||
-      (await hasVisibleSelector(page, selectedLegacyHome))
+      isHomeHref(href) &&
+      ((await hasVisibleSelector(page, selectedHome)) ||
+        (await hasVisibleSelector(page, selectedLegacyHome)))
     ) {
-      return { method: 'visible-ui', href: await currentHref(page), steps };
+      return { method: 'visible-ui', href, steps };
     }
-    const href = await currentHref(page);
     if (pendingActivation && pendingActivation.href !== href) {
       pendingActivation = undefined;
       await pauseForUi(page);
@@ -130,12 +175,19 @@ export async function openPerpsHome(page, timeoutMs) {
   const bottomNav = dataTestId('bottom-nav-perps');
   const legacyTab = dataTestId('account-overview__perps-tab');
   const perpsHome = dataTestId('perps-home-page');
+  const tutorialSkip = dataTestId('perps-tutorial-skip-button');
   const steps = [];
   const deadline = Date.now() + timeoutMs;
   let pendingActivation;
   let perpsActivation;
 
   while (Date.now() < deadline) {
+    if (await hasVisibleSelector(page, tutorialSkip)) {
+      await activateSemanticControl(page, tutorialSkip);
+      steps.push(tutorialSkip);
+      await pauseForUi(page);
+      continue;
+    }
     if (await hasVisibleSelector(page, perpsHome)) {
       return {
         ...(perpsActivation ? { navigation: perpsActivation, selector: bottomNav } : {}),
@@ -207,8 +259,23 @@ export async function openPerpsHome(page, timeoutMs) {
 
 export async function openPerpsMarket(page, market, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
-  const home = await openPerpsHome(page, Math.max(1, deadline - Date.now()));
   const normalizedMarket = normalizeMarketSymbol(market.trim());
+  if (await hasVisibleSelector(page, dataTestId('market-list-view'))) {
+    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'), {
+      timeoutMs: Math.max(1, deadline - Date.now()),
+    });
+    return {
+      navigation,
+      method: 'visible-ui',
+      href: await currentHref(page),
+      selector: marketRow,
+      steps: [marketRow],
+    };
+  }
+  const home = await openPerpsHome(page, Math.max(1, deadline - Date.now()));
   const selectors = [
     dataTestId(`perps-watchlist-${normalizedMarket}`),
     dataTestId(`explore-markets-${normalizedMarket.replaceAll(':', '-')}`),
@@ -239,11 +306,178 @@ export async function openPerpsMarket(page, market, timeoutMs) {
   };
 }
 
+export async function openPerpsActivity(page, timeoutMs) {
+  if (await hasVisibleSelector(page, dataTestId('perps-activity-page'))) {
+    return { method: 'visible-ui', href: await currentHref(page), steps: [] };
+  }
+  const deadline = Date.now() + timeoutMs;
+  const home = await openPerpsHome(page, Math.max(1, deadline - Date.now()));
+  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'), {
+    timeoutMs: Math.max(1, deadline - Date.now()),
+  });
+  return {
+    navigation,
+    method: 'visible-ui',
+    href: await currentHref(page),
+    selector: activity,
+    steps: [...(home.steps ?? []), activity],
+  };
+}
+
+export async function openPerpsMarketList(page, timeoutMs) {
+  const marketList = dataTestId('market-list-view');
+  if (await hasVisibleSelector(page, marketList)) {
+    return { method: 'visible-ui', href: await currentHref(page), steps: [] };
+  }
+  const deadline = Date.now() + timeoutMs;
+  const detailListButton = dataTestId('perps-market-detail-market-list-button');
+  if (await hasVisibleSelector(page, detailListButton)) {
+    const navigation = await activateSemanticControl(page, detailListButton);
+    await page.waitForSelector(marketList, { timeoutMs: Math.max(1, deadline - Date.now()) });
+    return {
+      navigation,
+      method: 'visible-ui',
+      href: await currentHref(page),
+      selector: detailListButton,
+      steps: [detailListButton],
+    };
+  }
+  const home = await openPerpsHome(page, Math.max(1, deadline - Date.now()));
+  const explore = dataTestId('perps-explore-markets-row');
+  await page.waitForSelector(explore, { timeoutMs: Math.max(1, deadline - Date.now()) });
+  const navigation = await activateSemanticControl(page, explore);
+  await page.waitForSelector(marketList, { timeoutMs: Math.max(1, deadline - Date.now()) });
+  return {
+    navigation,
+    method: 'visible-ui',
+    href: await currentHref(page),
+    selector: explore,
+    steps: [...home.steps, explore],
+  };
+}
+
+export async function openNetwork(page, network, chainId, addIfMissing, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const hexChainId = `0x${chainId.toString(16)}`;
+  const installed = dataTestId(`home-network-filter-network-${hexChainId}`);
+  const custom = dataTestId(`home-network-filter-custom-${hexChainId}`);
+  const additional = dataTestId(`home-network-filter-additional-${hexChainId}`);
+  const manage = dataTestId('home-network-filter-manage-networks');
+  const sort = dataTestId('sort-by-networks');
+  const assets = dataTestId('account-overview__asset-tab');
+  const steps = [];
+  await openHome(page, Math.max(1, deadline - Date.now()));
+  if (!(await hasVisibleSelector(page, `${assets}[aria-selected="true"]`))) {
+    await activateSemanticControl(page, assets);
+    steps.push(assets);
+    if (!(await waitForFirstVisible(page, [`${assets}[aria-selected="true"]`], deadline))) {
+      throw new Error('Token assets did not become selected before network navigation.');
+    }
+  }
+  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) {
+    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}`);
+    if (!await hasVisibleSelector(page, listItem)) {
+      const popular = `${dataTestId(`popular-network-${hexChainId}`)} ${dataTestId('test-add-button')}`;
+      await page.waitForSelector(popular, { timeoutMs: Math.max(1, deadline - Date.now()) });
+      await activateSemanticControl(page, popular);
+      steps.push(popular);
+      await page.waitForSelector(listItem, { timeoutMs: Math.max(1, deadline - Date.now()) });
+    }
+    const back = dataTestId('page-header-back-button');
+    await activateSemanticControl(page, back);
+    steps.push(back);
+    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);
+    if (!choice) throw new Error(`Added network ${network} (${chainId}) did not appear in the wallet filter.`);
+    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 };
+    }
+    await pauseForUi(page);
+  }
+  throw new Error(`Network ${network} (${chainId}) did not become the selected wallet filter.`);
+}
+
+export async function openSwap(page, timeoutMs) {
+  const sourceAmount = dataTestId('from-amount');
+  const sourceToken = dataTestId('bridge-source-button');
+  const destinationToken = dataTestId('bridge-destination-button');
+  const bottomNav = dataTestId('bottom-nav-swaps');
+  const deadline = Date.now() + timeoutMs;
+  if (
+    await hasVisibleSelector(page, sourceAmount) &&
+    await hasVisibleSelector(page, sourceToken) &&
+    await hasVisibleSelector(page, destinationToken)
+  ) {
+    return { method: 'visible-ui', href: await currentHref(page), steps: [] };
+  }
+  const home = await openHome(page, Math.max(1, deadline - Date.now()));
+  let navigation;
+  let lastActivationAt = 0;
+  let observedHref = await currentHref(page);
+  while (Date.now() < deadline) {
+    if (
+      await hasVisibleSelector(page, sourceAmount) &&
+      await hasVisibleSelector(page, sourceToken) &&
+      await hasVisibleSelector(page, destinationToken)
+    ) break;
+    const href = await currentHref(page);
+    if (href !== observedHref) {
+      observedHref = href;
+      lastActivationAt = Date.now();
+    }
+    if (await hasVisibleSelector(page, bottomNav) && (!navigation || Date.now() - lastActivationAt >= 1000)) {
+      navigation = await activateSemanticControl(page, bottomNav);
+      lastActivationAt = Date.now();
+    }
+    await pauseForUi(page);
+  }
+  if (
+    !(await hasVisibleSelector(page, sourceAmount)) ||
+    !(await hasVisibleSelector(page, sourceToken)) ||
+    !(await hasVisibleSelector(page, destinationToken))
+  ) {
+    throw new Error('Swap inputs did not appear after visible Swap navigation.');
+  }
+  return {
+    navigation,
+    method: 'visible-ui',
+    href: await currentHref(page),
+    selector: bottomNav,
+    steps: [...home.steps, bottomNav],
+  };
+}
+
 export async function navigateExtensionUi(input) {
   return withExtensionPage(input, async (page) => {
   const intent = pageIntent(input.node);
   if (intent) {
     const timeoutMs = Number(input.node?.timeout_ms ?? 20000);
+    if (intent.page === 'back') {
+      const result = await goBack(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
     if (intent.page === 'home') {
       const result = await openHome(page, timeoutMs);
       return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
@@ -252,6 +486,28 @@ export async function navigateExtensionUi(input) {
       const result = await openPerpsHome(page, timeoutMs);
       return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
     }
+    if (intent.page === 'perps-market-list') {
+      const result = await openPerpsMarketList(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
+    if (intent.page === 'perps-activity') {
+      const result = await openPerpsActivity(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
+    if (intent.page === 'network') {
+      const result = await openNetwork(
+        page,
+        intent.network,
+        intent.chainId,
+        intent.addIfMissing,
+        timeoutMs,
+      );
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
+    if (intent.page === 'swap') {
+      const result = await openSwap(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
     const result = await openPerpsMarket(page, intent.market, timeoutMs);
     return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
   }

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

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixturePassword(projectRoot) {
@@ -32,11 +32,7 @@ runAdapter((input) => withExtensionPage(input, async (page) => {
 
   const password = input.node?.password ?? await fixturePassword(input.context.projectRoot);
   await page.setInput('input[type="password"]', String(password));
-  await page.evaluate(`(() => {
-    const button = document.querySelector('button[type="submit"]') || Array.from(document.querySelectorAll('button')).find((candidate) => /unlock/i.test(candidate.innerText || candidate.textContent || ''));
-    if (!button) throw new Error('Unlock button not found.');
-    button.click();
-  })()`);
+  await page.click(dataTestId('unlock-submit'));
   await page.waitForExpression(`!document.querySelector('input[type="password"]')`, { timeoutMs: Number(input.node?.timeout_ms ?? 15000) });
   return { action: input.action, unlocked: true, redacted: true, proofPath: 'extension-password-unlock' };
 }));

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

@@ -0,0 +1,35 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+const MENU = dataTestId('account-options-menu-button');
+const LOCK = dataTestId('global-menu-lock');
+const UNLOCK_PAGE = dataTestId('unlock-page');
+
+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;
+  })()`);
+}
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  if (!(await visible(page, LOCK))) await page.click(MENU);
+  const deadline = Date.now() + Number(input.node?.timeout_ms ?? 15_000);
+  while (!(await visible(page, LOCK))) {
+    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);
+  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))');
+  }
+  return {
+    action: input.action,
+    locked: true,
+    route: await page.evaluate('location.hash'),
+    proofPath: 'trusted-pointer-visible-ui',
+  };
+}));

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

@@ -1,5 +1,9 @@
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
-import { selectWalletAccountExpression } from './state.mjs';
+import {
+  listWalletAccountsExpression,
+  readWalletStateExpression,
+  selectWalletAccountExpression,
+} from './state.mjs';
 
 function normalize(value) {
   return String(value ?? '').toLowerCase();
@@ -12,10 +16,70 @@ runAdapter((input) => withExtensionPage(input, async (page) => {
   if (!requestedAddress && !requestedId && !requestedName) {
     throw new Error('metamask.wallet.select_account extension live adapter requires node.address, node.id, or node.name.');
   }
-  const selected = await page.evaluate(selectWalletAccountExpression({
-    address: requestedAddress,
-    id: requestedId,
-    name: requestedName,
-  }), { awaitPromise: true });
-  return { action: input.action, selected, proofPath: 'extension-account-selection' };
+  try {
+    const selected = await page.evaluate(selectWalletAccountExpression({
+      address: requestedAddress,
+      id: requestedId,
+      name: requestedName,
+    }), { awaitPromise: true });
+    return { action: input.action, selected, proofPath: 'extension-background-account-selection' };
+  } catch (error) {
+    if (!String(error?.message ?? error).includes('submitRequestToBackground is unavailable')) throw error;
+  }
+
+  let searchAddress = requestedAddress;
+  if (!searchAddress) {
+    const listed = await page.evaluate(listWalletAccountsExpression('all'), { awaitPromise: true });
+    const account = listed.accounts.find((entry) =>
+      (requestedId && entry.id === requestedId) ||
+      (requestedName && entry.name === requestedName));
+    searchAddress = normalize(account?.address);
+  }
+  if (!searchAddress) throw new Error('Requested account does not have a searchable EVM address.');
+
+  await page.navigateHash('#/account-list');
+  const searchSelector = 'input[data-testid="multichain-account-list-search"], [data-testid="multichain-account-list-search"] input';
+  await page.waitForSelector(searchSelector);
+  await page.setInput(searchSelector, searchAddress);
+
+  const rowDeadline = Date.now() + 15_000;
+  let row;
+  while (Date.now() <= rowDeadline) {
+    row = await page.evaluate(`(() => {
+      const rows = [...document.querySelectorAll('.multichain-account-cell[data-testid^="multichain-account-cell-"]')]
+        .filter((element) => {
+          const style = getComputedStyle(element);
+          const rect = element.getBoundingClientRect();
+          return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+        });
+      return {
+        count: rows.length,
+        testId: rows.length === 1 ? rows[0].getAttribute('data-testid') : null,
+        label: rows.length === 1 ? String(rows[0].innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 500) : null,
+      };
+    })()`);
+    if (row.count === 1 && row.testId) break;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  if (row?.count !== 1 || !row.testId) {
+    throw new Error(`Expected one visible account for the requested address, observed ${row?.count ?? 0}.`);
+  }
+  await page.click(`[data-testid=${JSON.stringify(row.testId)}]`);
+
+  const selectedDeadline = Date.now() + 15_000;
+  let selected;
+  while (Date.now() <= selectedDeadline) {
+    const state = await page.evaluate(readWalletStateExpression(), { awaitPromise: true });
+    selected = state.selectedAccount;
+    if (normalize(selected?.address) === searchAddress) {
+      return {
+        action: input.action,
+        selected,
+        visibleAccount: row,
+        proofPath: 'trusted-pointer-visible-ui',
+      };
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`Visible account selection did not select ${searchAddress}.`);
 }));

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

@@ -0,0 +1,37 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+import {
+  normalizeVisibleAssetsState,
+  resolveVisibleAssetsOptions,
+} from '../../shared/assets/visible-state.mjs';
+
+runAdapter(async (input) => {
+  const options = resolveVisibleAssetsOptions(input.node);
+  const observed = await observeNativeUi(
+    { refs: ['ui.screen', 'ui.visible'], node: input.node },
+    input.context,
+  );
+  const screen = observed.observations?.['ui.screen'];
+  const visible = observed.observations?.['ui.visible'];
+  if (!screen || !visible) {
+    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 ?? [])]
+    .filter((item) => String(item.test_id ?? '').startsWith('asset-'))
+    .map((item) => ({
+      testId: item.test_id,
+      label: item.label,
+      symbol: String(item.test_id).slice('asset-'.length),
+    }));
+  return {
+    action: input.action,
+    ...normalizeVisibleAssetsState({
+      route: screen.route,
+      title: screen.title,
+      items,
+      truncated: visible.truncated,
+    }, options, 'mobile'),
+    proofPath: 'native-accessibility',
+  };
+});

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

@@ -0,0 +1,31 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+import {
+  normalizeVisiblePerpsState,
+  resolveVisibleStateOptions,
+} from '../../shared/perps/visible-state.mjs';
+
+runAdapter(async (input) => {
+  const options = resolveVisibleStateOptions(input.node);
+  const observed = await observeNativeUi(
+    { refs: ['ui.screen', 'ui.visible'], node: input.node },
+    input.context,
+  );
+  const screen = observed.observations?.['ui.screen'];
+  const visible = observed.observations?.['ui.visible'];
+  if (!screen || !visible) {
+    const warning = observed.warnings?.map((entry) => entry.message).filter(Boolean).join('; ');
+    throw new Error(`Mobile visible Perps state is unavailable${warning ? `: ${warning}` : '.'}`);
+  }
+  return {
+    action: input.action,
+    ...normalizeVisiblePerpsState({
+      route: screen.route,
+      title: screen.title,
+      items: visible.items,
+      offscreenItems: visible.hidden_or_offscreen,
+      truncated: visible.truncated,
+    }, options, 'mobile'),
+    proofPath: 'native-accessibility',
+  };
+});

package/library/actions/mobile/platform/native-session-name.mjs

@@ -0,0 +1,5 @@
+export function nativeSessionName(env, device, app = 'io.metamask') {
+  const configured = String(env.METAMASK_RECIPE_MOBILE_SESSION ?? '').trim();
+  const source = configured || `mm-harness-${app}-${device}`;
+  return source.replace(/[^A-Za-z0-9._-]/gu, '-').slice(0, 120);
+}

package/library/actions/mobile/platform/observe-ui.mjs

@@ -3,6 +3,7 @@ import { promisify } from 'node:util';
 import { createAgentDeviceClient } from 'agent-device';
 
 import { bridgeCommand } from './bridge.mjs';
+import { nativeSessionName } from './native-session-name.mjs';
 import { mobileToolRecovery, resolveMobileToolPath } from './tool-paths.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -140,7 +141,8 @@ async function readAndroidHierarchy(node, env) {
 }
 
 async function readAndroidAgentDeviceHierarchy(serial, env) {
-  const session = `mm-harness-observe-${process.pid}-${Date.now()}`;
+  const app = text(env.ANDROID_PACKAGE_ID) ?? 'io.metamask';
+  const session = nativeSessionName(env, serial, app);
   const client = createAgentDeviceClient({
     session,
     lockPolicy: 'reject',
@@ -152,13 +154,13 @@ async function readAndroidAgentDeviceHierarchy(serial, env) {
       target: 'mobile',
       serial,
       session,
-      app: text(env.ANDROID_PACKAGE_ID) ?? 'io.metamask',
+      app,
       interactiveOnly: false,
       forceFull: true,
     });
     const hierarchy = flattenAgentDeviceHierarchy(
       snapshot.nodes,
-      text(env.ANDROID_PACKAGE_ID) ?? 'io.metamask',
+      app,
     );
     if (hierarchy.nodeCount === 0) {
       throw new Error('Agent Device returned an empty Android accessibility hierarchy.');

package/library/actions/mobile/swap_bridge/native-session.mjs

@@ -0,0 +1,45 @@
+import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
+import { createAgentDeviceClient } from 'agent-device';
+import { nativeSessionName } from '../platform/native-session-name.mjs';
+
+export function createSwapNativeSession(input) {
+  const env = { ...process.env, ...(input.context?.env ?? {}) };
+  const device = String(env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? '').trim();
+  if (!device) throw new Error('Opaque Mobile Swap actions require one explicit Android device serial.');
+  const app = String(env.ANDROID_PACKAGE_ID ?? 'io.metamask');
+  const session = nativeSessionName(env, device, app);
+  const client = createAgentDeviceClient({ session, lockPolicy: 'reject', lockPlatform: 'android' });
+  const selection = { platform: 'android', target: 'mobile', serial: device, session };
+  const transport = createAgentDeviceUiTransport({ platform: 'android', device, app, session, client });
+  const context = {
+    nodeId: String(input.context?.nodeId ?? 'action'),
+    projectRoot: input.context.projectRoot,
+    artifactsDir: input.context.artifactsDir,
+    env,
+  };
+  return {
+    client,
+    transport,
+    selection,
+    context,
+    app,
+    execute: (action, node) => transport.execute(action, node, context),
+    snapshot: () => client.capture.snapshot({ ...selection, app, interactiveOnly: false, forceFull: true }),
+  };
+}
+
+export async function closeSwapNativeSession(session) {
+  try {
+    await session.transport.close();
+  } catch (error) {
+    if (!/No active session|SESSION_NOT_FOUND/iu.test(String(error?.message ?? error))) throw error;
+  }
+}
+
+export function nativeNode(snapshot, identifier) {
+  return snapshot.nodes.find((node) => String(node.identifier ?? '') === identifier);
+}
+
+export function nativeLabel(node) {
+  return String(node?.label ?? node?.value ?? '').replace(/\s+/gu, ' ').trim();
+}