@deeeed/metamask-harness 0.35.0 → 0.37.0

package/library/actions/mobile/wallet/native-ui.mjs

@@ -0,0 +1,493 @@
+import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
+import { createAgentDeviceClient } from 'agent-device';
+
+const TEST_IDS = {
+  existingWallet: 'wallet-setup-screen-have-an-existing-wallet-button-id',
+  importSeed: 'onboarding-sheet-import-seed-button-id',
+  srp: 'phrase-input-id',
+  continue: 'import-from-seed-screen-continue-button-id',
+  password: 'create-password-first-input-field',
+  confirmPassword: 'create-password-second-input-field',
+  passwordTerms: 'password-understand-box',
+  createPassword: 'submit-button',
+  metricsCheckbox: 'optin-metrics-metrics-checkbox',
+  metricsContinue: 'optin-metrics-continue-button-id',
+  interestSkip: 'onboarding-interest-skip-button',
+  interestContinue: 'onboarding-interest-continue-button',
+  successDone: 'onboarding-success-done-button',
+  notificationYes: 'push-notification-new-user-sheet-button-yes',
+  notificationNotNow: 'push-notification-new-user-sheet-button-not-now',
+  walletTourSkip: 'wallet-home-onboarding-steps-skip',
+  wallet: 'wallet-screen',
+  walletSafeArea: 'wallet-safe-area',
+  walletHomepage: 'homepage-container',
+  walletScroll: 'wallet-scroll-view',
+  walletAddress: 'wallet-account-copy-button',
+  addressListBack: 'address-list-go-back',
+  walletTab: 'tab-bar-item-Wallet',
+  perpsHome: 'perps-home',
+  perpsHomeBack: 'perps-home-back-button',
+  perpsMarket: 'perps-market-details-view',
+  perpsMarketBack: 'perps-market-header-back-button',
+  hamburger: 'navbar-hamburger-menu-button',
+  lock: 'lock-menu-item',
+  confirmLock: 'android:id/button1',
+  login: 'login',
+  loginPassword: 'login-password-input',
+  loginButton: 'log-in-button',
+  forgotPassword: 'reset-wallet-button',
+  resetWallet: 'forgot-password-modal-reset-wallet-button',
+  confirmReset: 'forgot-password-modal-yes-reset-wallet-button',
+};
+
+const WALLET_SCREEN_IDS = [
+  TEST_IDS.wallet,
+  TEST_IDS.walletSafeArea,
+  TEST_IDS.walletHomepage,
+  TEST_IDS.walletScroll,
+];
+
+const POST_PASSWORD_TEST_IDS = [
+  TEST_IDS.metricsContinue,
+  TEST_IDS.interestSkip,
+  TEST_IDS.successDone,
+  TEST_IDS.notificationNotNow,
+  TEST_IDS.walletTourSkip,
+  ...WALLET_SCREEN_IDS,
+];
+
+const BIOMETRIC_PROMPT_ID = 'com.android.systemui:id/biometric_prompt_constraint_layout';
+const PERMISSION_CONTROLLER_PACKAGES = new Set([
+  'com.android.permissioncontroller',
+  'com.google.android.permissioncontroller',
+]);
+
+function isMetaMaskBiometricPrompt(nodes) {
+  const systemUiNodes = nodes.filter((node) => node.bundleId === 'com.android.systemui');
+  return systemUiNodes.some((node) => node.identifier === BIOMETRIC_PROMPT_ID) &&
+    systemUiNodes.some((node) =>
+      /metamask/iu.test(String(node.label ?? node.value ?? ''))
+    );
+}
+
+function isPostPasswordScreen(nodes) {
+  return nodes.some((node) => POST_PASSWORD_TEST_IDS.includes(String(node.identifier ?? '')));
+}
+
+function isMetaMaskNotificationPermissionPrompt(nodes) {
+  const permissionNodes = nodes.filter((node) => PERMISSION_CONTROLLER_PACKAGES.has(node.bundleId));
+  return permissionNodes.some((node) => /metamask/iu.test(String(node.label ?? node.value ?? ''))) &&
+    permissionNodes.some((node) => /notification/iu.test(String(node.label ?? node.value ?? node.identifier ?? '')));
+}
+
+function isWalletScreen(nodes) {
+  return nodes.some((node) => WALLET_SCREEN_IDS.includes(String(node.identifier ?? '')));
+}
+
+function hasBlockingSystemUi(nodes) {
+  return nodes.some((node) =>
+    (node.bundleId === 'com.android.systemui' || PERMISSION_CONTROLLER_PACKAGES.has(node.bundleId)) &&
+    /(?:dialog|prompt|permission)/iu.test(String(node.identifier ?? ''))
+  );
+}
+
+export function isOpaqueMobileRuntime(input) {
+  return input.context?.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === '1' ||
+    process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === '1';
+}
+
+export async function importWalletThroughNativeUi(input, credentials, options) {
+  const native = nativeSession(input);
+  try {
+    const initial = await native.normalizeWalletSurface(options.timeoutMs);
+    if (initial.wallet) {
+      if (options.requireFresh) {
+        throw new Error('metamask.wallet.import method=ui requires a fresh Mobile onboarding state.');
+      }
+      return await native.walletProof(credentials.expectedAddress, true, options.timeoutMs);
+    }
+    if (initial.visible.has(TEST_IDS.login)) {
+      if (options.requireFresh) {
+        throw new Error('metamask.wallet.import method=ui requires a fresh Mobile onboarding state.');
+      }
+      await native.fill(TEST_IDS.loginPassword, credentials.password, options.timeoutMs);
+      await native.press(TEST_IDS.loginButton, options.timeoutMs);
+      await native.waitForWallet(options.timeoutMs);
+      return await native.walletProof(credentials.expectedAddress, true, options.timeoutMs);
+    }
+    const resumedAfterPassword = initial.postPassword;
+    if (!resumedAfterPassword) {
+      await native.press(TEST_IDS.existingWallet, options.timeoutMs);
+      if (!await native.exists(TEST_IDS.srp, 3000)) {
+        await native.press(TEST_IDS.importSeed, options.timeoutMs);
+      }
+      await fillRecoveryPhrase(native, credentials.mnemonic, options.timeoutMs);
+      await native.press(TEST_IDS.continue, options.timeoutMs);
+      await native.fill(TEST_IDS.password, credentials.password, options.timeoutMs);
+      await native.fill(TEST_IDS.confirmPassword, credentials.password, options.timeoutMs);
+      await native.dismissKeyboard();
+      await native.press(TEST_IDS.passwordTerms, options.timeoutMs);
+      await native.press(TEST_IDS.createPassword, options.timeoutMs);
+    }
+    const onboarding = await native.completeOnboarding(options);
+    return {
+      ...await native.walletProof(credentials.expectedAddress, false, options.timeoutMs),
+      ...onboarding,
+    };
+  } finally {
+    await native.close();
+  }
+}
+
+async function fillRecoveryPhrase(native, mnemonic, timeoutMs) {
+  const words = mnemonic.trim().split(/\s+/u);
+  await native.fill(TEST_IDS.srp, words[0], timeoutMs);
+  for (const [index, word] of words.slice(1).entries()) {
+    await native.type(' ');
+    await native.wait(`${TEST_IDS.srp}_${index + 1}`, timeoutMs);
+    await native.type(word);
+  }
+  await native.verifyRecoveryPhrase(words);
+  await native.dismissKeyboard();
+}
+
+export async function readWalletThroughNativeUi(input) {
+  const native = nativeSession(input);
+  try {
+    const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
+    await native.normalizeWalletSurface(timeoutMs);
+    await native.waitForWallet(timeoutMs);
+    return await native.walletProof(undefined, true, timeoutMs);
+  } finally {
+    await native.close();
+  }
+}
+
+export async function resetWalletThroughNativeUi(input) {
+  const native = nativeSession(input);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 60_000);
+  try {
+    if (await native.exists(TEST_IDS.existingWallet, 1000)) {
+      return { alreadyFresh: true, provider: 'android-native-accessibility' };
+    }
+    if (await native.exists(TEST_IDS.confirmLock, 1000)) {
+      await native.press(TEST_IDS.confirmLock, timeoutMs);
+    } else {
+      const state = await native.normalizeWalletSurface(timeoutMs);
+      if (state.wallet) {
+        await native.press(TEST_IDS.hamburger, timeoutMs);
+        await native.press(TEST_IDS.lock, timeoutMs);
+        if (await native.exists(TEST_IDS.confirmLock, 3000)) {
+          await native.press(TEST_IDS.confirmLock, timeoutMs);
+        }
+      }
+    }
+    await native.wait(TEST_IDS.login, timeoutMs);
+    await native.press(TEST_IDS.forgotPassword, timeoutMs);
+    await native.press(TEST_IDS.resetWallet, timeoutMs);
+    await native.press(TEST_IDS.confirmReset, timeoutMs);
+    await native.wait(TEST_IDS.existingWallet, timeoutMs);
+    return { alreadyFresh: false, provider: 'android-native-accessibility' };
+  } finally {
+    await native.close();
+  }
+}
+
+function nativeSession(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 UI execution requires one explicit Android device serial.');
+  const app = String(env.ANDROID_PACKAGE_ID ?? 'io.metamask');
+  const session = `mm-harness-wallet-${process.pid}-${String(input.context?.nodeId ?? 'node')}`
+    .replace(/[^A-Za-z0-9._-]/gu, '-');
+  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 ?? 'wallet'),
+    projectRoot: input.context.projectRoot,
+    artifactsDir: input.context.artifactsDir,
+    env,
+  };
+  const execute = (action, node) => transport.execute(action, node, context);
+  return {
+    press: (testId, timeoutMs) => execute('ui.press', { test_id: testId, timeout_ms: timeoutMs }),
+    fill: (testId, value, timeoutMs) => execute('ui.set_input', {
+      test_id: testId,
+      value,
+      timeout_ms: timeoutMs,
+      settle: false,
+    }),
+    type: (value) => client.interactions.type({
+      ...selection,
+      text: value,
+      delayMs: 50,
+      responseLevel: 'digest',
+    }),
+    async verifyRecoveryPhrase(words) {
+      const snapshot = await client.capture.snapshot({
+        ...selection,
+        interactiveOnly: false,
+        forceFull: true,
+      });
+      const actual = new Map(snapshot.nodes
+        .filter((node) => /^phrase-input-id_\d+$/u.test(String(node.identifier ?? '')))
+        .map((node) => [
+          Number(String(node.identifier).split('_').at(-1)),
+          String(node.value ?? node.label ?? ''),
+        ]));
+      const mismatches = words.flatMap((word, index) =>
+        actual.get(index) === word ? [] : [index + 1]
+      );
+      if (actual.size !== words.length || mismatches.length > 0) {
+        throw new Error(
+          `Mobile recovery phrase entry did not match ${words.length} expected fields; mismatched field numbers: ${mismatches.join(', ') || 'unknown'}.`,
+        );
+      }
+    },
+    dismissKeyboard: () => client.command.keyboard({
+      ...selection,
+      action: 'dismiss',
+      responseLevel: 'digest',
+    }),
+    async isPostPasswordScreen() {
+      return (await this.screenState()).postPassword;
+    },
+    async screenState() {
+      const snapshot = await client.capture.snapshot({
+        ...selection,
+        interactiveOnly: false,
+        forceFull: true,
+      });
+      return {
+        nodes: snapshot.nodes,
+        visible: new Set(snapshot.nodes.map((node) => String(node.identifier ?? ''))),
+        wallet: isWalletScreen(snapshot.nodes),
+        postPassword: isPostPasswordScreen(snapshot.nodes) || isMetaMaskBiometricPrompt(snapshot.nodes),
+      };
+    },
+    async normalizeWalletSurface(timeoutMs) {
+      const deadline = Date.now() + timeoutMs;
+      for (let attempt = 0; attempt < 5 && Date.now() <= deadline; attempt += 1) {
+        const state = await this.screenState();
+        if (
+          state.wallet ||
+          state.postPassword ||
+          state.visible.has(TEST_IDS.existingWallet) ||
+          state.visible.has(TEST_IDS.login)
+        ) {
+          return state;
+        }
+        if (state.visible.has(TEST_IDS.perpsMarketBack)) {
+          await this.press(TEST_IDS.perpsMarketBack, timeoutMs);
+        } else if (state.visible.has(TEST_IDS.perpsHomeBack)) {
+          await this.press(TEST_IDS.perpsHomeBack, timeoutMs);
+        } else if (state.visible.has(TEST_IDS.walletTab)) {
+          await this.press(TEST_IDS.walletTab, timeoutMs);
+        } else if (state.visible.has(TEST_IDS.addressListBack)) {
+          await this.press(TEST_IDS.addressListBack, timeoutMs);
+        } else {
+          await client.command.back({
+            ...selection,
+            mode: 'system',
+            responseLevel: 'digest',
+          });
+        }
+      }
+      throw new Error('Mobile wallet action could not reach wallet home, login, or onboarding.');
+    },
+    async completeOnboarding(options) {
+      const deadline = Date.now() + options.timeoutMs;
+      let biometricPromptDismissed = false;
+      let notificationPromptHandled = false;
+      let notificationsEnabled = false;
+      let walletTourSkipped = false;
+      let interestsHandled = false;
+      let awaitingNotificationPermission = false;
+      while (Date.now() <= deadline) {
+        const snapshot = await client.capture.snapshot({
+          ...selection,
+          interactiveOnly: false,
+          forceFull: true,
+        });
+        if (isMetaMaskBiometricPrompt(snapshot.nodes)) {
+          if (options.biometricsEnabled) {
+            throw new Error('Mobile biometrics=true requires manual device authentication and is not supported by an unattended recipe.');
+          }
+          await client.command.back({
+            ...selection,
+            mode: 'system',
+            responseLevel: 'digest',
+          });
+          biometricPromptDismissed = true;
+          continue;
+        }
+        if (isMetaMaskNotificationPermissionPrompt(snapshot.nodes) && awaitingNotificationPermission) {
+          await client.command.alert({
+            ...selection,
+            action: 'accept',
+            timeoutMs: 5000,
+            responseLevel: 'digest',
+          });
+          awaitingNotificationPermission = false;
+          notificationsEnabled = true;
+          continue;
+        }
+        if (hasBlockingSystemUi(snapshot.nodes)) {
+          throw new Error('Unexpected Android system UI blocked Mobile wallet creation; refusing to dismiss it as biometric authentication.');
+        }
+        const visible = new Set(snapshot.nodes.map((node) => String(node.identifier ?? '')));
+        if (visible.has(TEST_IDS.metricsContinue)) {
+          if (!options.metametricsEnabled) {
+            await this.press(TEST_IDS.metricsCheckbox, options.timeoutMs);
+          }
+          await this.press(TEST_IDS.metricsContinue, options.timeoutMs);
+          continue;
+        }
+        if (visible.has(TEST_IDS.interestSkip)) {
+          interestsHandled = true;
+          if (options.interests.length > 0) {
+            for (const interest of options.interests) {
+              await this.press(`onboarding-interest-option-${interest}`, options.timeoutMs);
+            }
+            await this.press(TEST_IDS.interestContinue, options.timeoutMs);
+          } else {
+            await this.press(TEST_IDS.interestSkip, options.timeoutMs);
+          }
+          continue;
+        }
+        if (visible.has(TEST_IDS.successDone)) {
+          if (options.interests.length > 0 && !interestsHandled) {
+            throw new Error('Mobile onboarding interests were requested, but the questionnaire is not enabled for this build.');
+          }
+          await this.press(TEST_IDS.successDone, options.timeoutMs);
+          continue;
+        }
+        if (visible.has(TEST_IDS.notificationNotNow)) {
+          await this.press(
+            options.notificationsEnabled ? TEST_IDS.notificationYes : TEST_IDS.notificationNotNow,
+            options.timeoutMs,
+          );
+          notificationPromptHandled = true;
+          awaitingNotificationPermission = options.notificationsEnabled;
+          continue;
+        }
+        if (visible.has(TEST_IDS.walletTourSkip)) {
+          if (options.skipWalletTour) {
+            await this.press(TEST_IDS.walletTourSkip, options.timeoutMs);
+            walletTourSkipped = true;
+            continue;
+          }
+          throw new Error('Mobile wallet-home tour remains visible because skip_wallet_tour=false; wallet readiness cannot be proven.');
+        }
+        if (WALLET_SCREEN_IDS.some((testId) => visible.has(testId))) {
+          if (options.interests.length > 0 && !interestsHandled) {
+            throw new Error('Mobile onboarding interests were requested, but the questionnaire is not enabled for this build.');
+          }
+          return {
+            biometricsEnabled: options.biometricsEnabled,
+            biometricPromptDismissed,
+            notificationsEnabled,
+            notificationPromptHandled,
+            walletTourSkipped,
+          };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      throw new Error('Mobile onboarding did not reach a usable wallet before the import timeout.');
+    },
+    wait: (testId, timeoutMs) => execute('ui.wait_for', {
+      test_id: testId,
+      expected: 'visible',
+      timeout_ms: timeoutMs,
+      settle: false,
+    }),
+    async waitForWallet(timeoutMs) {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() <= deadline) {
+        if ((await this.screenState()).wallet) return;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      throw new Error('Mobile wallet home did not become visible before the readiness timeout.');
+    },
+    async exists(testId, timeoutMs) {
+      try {
+        await execute('ui.wait_for', {
+          test_id: testId,
+          expected: 'visible',
+          timeout_ms: timeoutMs,
+          settle: false,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async walletProof(expectedAddress, alreadyReady, timeoutMs) {
+      const observed = await transport.observe?.(['ui.screen', 'ui.visible']);
+      let rawText = JSON.stringify(observed ?? '').toLowerCase();
+      const text = rawText.replace(/[^a-z0-9]/gu, '');
+      const address = expectedAddress?.toLowerCase().replace(/[^a-z0-9]/gu, '');
+      let addressVisible = address
+        ? text.includes(address) || (text.includes(address.slice(0, 7)) && text.includes(address.slice(-5)))
+        : /0x[a-f0-9]{5,40}(?:…|\.\.\.)?[a-f0-9]{0,8}/u.test(rawText);
+      const deadline = Date.now() + Math.min(timeoutMs, 30_000);
+      while (!addressVisible && Date.now() <= deadline) {
+        let openedAddressList = false;
+        try {
+          await this.press(TEST_IDS.walletAddress, 15_000);
+          openedAddressList = true;
+          const addressState = await this.screenState();
+          rawText = JSON.stringify(addressState.nodes.map((node) => [node.label, node.value])).toLowerCase();
+          const normalized = rawText.replace(/[^a-z0-9]/gu, '');
+          addressVisible = address
+            ? normalized.includes(address) ||
+              (normalized.includes(address.slice(0, 7)) && normalized.includes(address.slice(-5)))
+            : /0x[a-f0-9]{5,40}(?:…|\.\.\.)?[a-f0-9]{0,8}/u.test(rawText);
+        } finally {
+          if (openedAddressList) {
+            if (await this.exists(TEST_IDS.addressListBack, 2000)) {
+              await this.press(TEST_IDS.addressListBack, 15_000);
+            } else {
+              await client.command.back({
+                ...selection,
+                mode: 'system',
+                responseLevel: 'digest',
+              });
+            }
+          }
+        }
+        if (!addressVisible) await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      const observedAddress = rawText.match(/0x[a-f0-9]{5,40}(?:…|\.\.\.)?[a-f0-9]{0,8}/u)?.[0] ?? null;
+      return {
+        alreadyReady,
+        selectedAddress: addressVisible && expectedAddress ? expectedAddress : null,
+        selectedAddressObserved: observedAddress,
+        ...(expectedAddress ? { selectedAddressExpected: expectedAddress } : {}),
+        addressVisible,
+        walletVisible: true,
+        provider: 'android-native-accessibility',
+        redacted: true,
+        proofPath: 'mobile-visible-onboarding-import-native',
+      };
+    },
+    async close() {
+      try {
+        await client.sessions.close({ session, shutdown: false });
+      } catch (error) {
+        if (!/No active session|SESSION_NOT_FOUND/iu.test(String(error?.message ?? error))) throw error;
+      }
+    },
+  };
+}

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

@@ -1,9 +1,25 @@
 import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
+import { isOpaqueMobileRuntime, readWalletThroughNativeUi } from './native-ui.mjs';
 
 // selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
 const selectedStatus = selectBridgeStatusEntry;
 
 runAdapter(async (input) => {
+  if (isOpaqueMobileRuntime(input)) {
+    const proof = await readWalletThroughNativeUi(input);
+    if (!proof.addressVisible) {
+      throw new Error('Mobile wallet home is visible, but the selected account address is not observable through native accessibility.');
+    }
+    return {
+      action: input.action,
+      source: proof.provider,
+      account: { address: proof.selectedAddress, displayAddress: proof.selectedAddressObserved },
+      route: { name: 'WalletView', observedBy: 'wallet-screen' },
+      platform: 'android',
+      redacted: true,
+      proofPath: 'native-wallet-status',
+    };
+  }
   const status = selectedStatus(await bridgeCommand(input, ['status']), input);
   const output = {
     action: input.action,

package/library/actions/mobile/wallet/reset-helper.mjs

@@ -0,0 +1,99 @@
+import {
+  bridgeCommand,
+  selectBridgeStatusEntry,
+} from '../platform/bridge.mjs';
+
+const TEST_IDS = {
+  existingWallet: 'wallet-setup-screen-have-an-existing-wallet-button-id',
+  forgotPassword: 'reset-wallet-button',
+  resetWallet: 'forgot-password-modal-reset-wallet-button',
+  confirmReset: 'forgot-password-modal-yes-reset-wallet-button',
+};
+
+function selectedEntry(status, input) {
+  return selectBridgeStatusEntry(status, input) ?? {};
+}
+
+function walletState(status, input) {
+  const entry = selectedEntry(status, input);
+  return {
+    address: String(entry?.account?.address ?? '').toLowerCase(),
+    route: String(entry?.route?.name ?? ''),
+  };
+}
+
+async function isFreshWallet(status, input) {
+  const state = walletState(status, input);
+  if (state.route !== 'Onboarding') return false;
+  return bridgeCommand(input, ['eval', `(() => {
+    const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    const rootsFor = hook?.getFiberRoots;
+    if (!hook?.renderers || typeof rootsFor !== 'function') return false;
+    const walk = (fiber) => {
+      if (!fiber) return false;
+      if (fiber.memoizedProps?.testID === ${JSON.stringify(TEST_IDS.existingWallet)}) return true;
+      return walk(fiber.child) || walk(fiber.sibling);
+    };
+    for (const [id] of hook.renderers) {
+      for (const root of rootsFor(id) ?? []) {
+        if (walk(root.current)) return true;
+      }
+    }
+    return false;
+  })()`]);
+}
+
+async function waitForCommand(input, args, timeoutMs, label) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() <= deadline) {
+    try {
+      const result = await bridgeCommand(input, args);
+      if (result?.ok !== false) return result;
+      lastError = result?.error;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`${label} was not available before the wallet reset timeout: ${String(lastError?.message ?? lastError ?? 'unknown')}`);
+}
+
+async function waitForFreshWallet(input, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let observed;
+  while (Date.now() <= deadline) {
+    observed = await bridgeCommand(input, ['status-selected']);
+    if (await isFreshWallet(observed, input)) return observed;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  const state = walletState(observed, input);
+  throw new Error(`Mobile wallet reset did not reach fresh onboarding; route=${state.route || 'unknown'} account=${state.address || 'none'}.`);
+}
+
+export async function resetMobileWalletThroughUi(input) {
+  const timeoutMs = Number(input.node?.timeout_ms ?? 60000);
+  const before = await bridgeCommand(input, ['status-selected']);
+  if (await isFreshWallet(before, input)) {
+    return {
+      alreadyFresh: true,
+      route: walletState(before, input).route,
+      redacted: true,
+      proofPath: 'mobile-visible-wallet-reset',
+    };
+  }
+
+  if (walletState(before, input).route !== 'Login') {
+    await bridgeCommand(input, ['navigate', 'Login']);
+  }
+  await waitForCommand(input, ['press-test-id', TEST_IDS.forgotPassword], timeoutMs, TEST_IDS.forgotPassword);
+  await waitForCommand(input, ['press-test-id', TEST_IDS.resetWallet], timeoutMs, TEST_IDS.resetWallet);
+  await waitForCommand(input, ['press-test-id', TEST_IDS.confirmReset], timeoutMs, TEST_IDS.confirmReset);
+  const after = await waitForFreshWallet(input, timeoutMs);
+  return {
+    alreadyFresh: false,
+    route: walletState(after, input).route,
+    redacted: true,
+    proofPath: 'mobile-visible-wallet-reset',
+  };
+}

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

@@ -0,0 +1,20 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { resetMobileWalletThroughUi } from './reset-helper.mjs';
+import { isOpaqueMobileRuntime, resetWalletThroughNativeUi } from './native-ui.mjs';
+
+runAdapter(async (input) => {
+  if (isOpaqueMobileRuntime(input)) {
+    const result = await resetWalletThroughNativeUi(input);
+    return {
+      action: input.action,
+      ...result,
+      route: 'Onboarding',
+      redacted: true,
+      proofPath: 'mobile-visible-wallet-reset-native',
+    };
+  }
+  return {
+    action: input.action,
+    ...(await resetMobileWalletThroughUi(input)),
+  };
+});

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

@@ -30,6 +30,7 @@ export function locatorsFromObservation(observation) {
       const leftBest = left.suggestions[0];
       const rightBest = right.suggestions[0];
       return (
+        locatorPriority(left) - locatorPriority(right) ||
         confidenceRank(leftBest?.confidence) - confidenceRank(rightBest?.confidence) ||
         strategyRank(leftBest?.strategy) - strategyRank(rightBest?.strategy)
       );
@@ -44,6 +45,12 @@ export function locatorsFromObservation(observation) {
   };
 }
 
+function locatorPriority(locator) {
+  const role = text(locator.role)?.toLowerCase() ?? '';
+  if (INTERACTIVE_ROLE_PARTS.some((part) => role.includes(part))) return 0;
+  return locator.description.includes('label=') ? 1 : 2;
+}
+
 export function requireVisibleObservation(result) {
   const value = record(result);
   const observations = record(value.observations);