@deeeed/metamask-harness 0.47.4 → 0.49.0

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

@@ -1,12 +1,11 @@
+// Converge selected testnet orders to open or absent state, then assert the result.
+// Reuse an existing matching order instead of placing another.
+
 import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
 import { assertOrders } from './assert_orders.mjs';
 import { closeOrders } from './close_orders.mjs';
 import { placeOrder } from './place_order.mjs';
 
-// core Higher-level wrapper that reads selected open orders, converges them to the
-// requested `state` (open/none) by canceling or placing, then asserts the final
-// order state. Mirrors ensure_positions.mjs.
-
 export async function ensureOrders(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.ensure_orders requires state=open or state=none.');
   requireExplicitSelection(input);

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

@@ -1,12 +1,11 @@
+// Converge selected testnet positions to open or absent state, then assert the result.
+// Open a position only when the selected state requires one.
+
 import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
 import { assertPositions } from './assert_positions.mjs';
 import { closePositions } from './close_positions.mjs';
 import { placeOrder } from './place_order.mjs';
 
-// core Higher-level wrapper that reads selected positions, converges them to the
-// requested `state` (open/none) by placing or closing, then asserts the final
-// state. Mirrors the extension ensure_positions semantics.
-
 export async function ensurePositions(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.ensure_positions requires state=open or state=none.');
   requireExplicitSelection(input);
@@ -26,7 +25,7 @@ export async function ensurePositions(input) {
       userAddress: accountAddress,
     });
     let order = null;
-    if (selectedItems(input, positions).length === 0) {
+    if (selectedItems(input, positions, 'position').length === 0) {
       order = await placeOrder(input);
     }
     const assertion = await assertPositions(input, true);

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

@@ -1,3 +1,6 @@
+// Submit and verify testnet market, limit or trigger orders through the headless controller.
+// Supports declared rejection cases and attached protection parameters.
+
 import {
   configuredSymbols,
   controllerRejection,
@@ -12,24 +15,14 @@ import {
   selectedItems,
 } from './_controller.mjs';
 
-// core Place a real Perps order on HyperLiquid testnet by driving the headless
-// PerpsController.placeOrder() through the full signing/provider path (Slice 2).
-// Mirrors the extension adapter's input vocabulary and notional→size math:
-//   size = (usdAmount * leverage) / currentPrice
-// The HyperLiquidProvider recalculates size from usdAmount internally; we still
-// pass a derived size for the controller's own validation, plus currentPrice/
-// priceAtCalculation so the provider's slippage guard has a fresh anchor.
-//
 // LIMIT orders (orderType=limit) place a RESTING order on the book instead of
 // filling: the provider sends tif=Gtc and uses the provided `price` verbatim
 // (calculateOrderPriceAndSize / buildOrdersArray in core's orderCalculations.ts).
 // The limit price is derived from the live mid by `offset_pct` (e.g. -30 places a
-// BUY 30% below mid that will NOT fill), or supplied absolutely via `limit_price`.
+// BUY 30% below mid), or supplied absolutely via `limit_price`.
 // For a limit order we size from the LIMIT price (not mid) and omit usdAmount so
-// the controller uses our explicit size verbatim — that guarantees the
-// on-exchange notional (size * limitPrice) clears HyperLiquid's ~$10 minimum even
-// though the limit sits far from mid. After placing we verify the resting open
-// order exists (not a filled position).
+// the controller receives an explicit size; venue quantity normalization still
+// applies. After placing we verify the resting open order exists, not a filled position.
 //
 // TRIGGER placements (order_type=stop_market | stop_limit | take_profit_market |
 // take_profit_limit) rest off-book until `trigger_price` is reached, then execute
@@ -567,7 +560,7 @@ export async function placeOrder(input) {
       userAddress: accountAddress,
     });
   }
-  const matchingPositions = selectedItems(input, positions);
+  const matchingPositions = selectedItems(input, positions, 'position');
 
   if (restsOnBook && matchingOrders.length === 0) {
     throw new Error(

package/library/actions/core/perps/read_account.mjs

@@ -1,3 +1,5 @@
+// Read the selected account's Perps balance and margin data through standalone controller APIs.
+
 import {
   getCoreController,
   isDirectRun,

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

@@ -1,3 +1,5 @@
+// Read standalone Perps orders and return redacted selected data with total/matching counts.
+
 import {
   getCoreController,
   isDirectRun,

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

@@ -1,3 +1,5 @@
+// Read standalone Perps positions and return redacted selected data with total/matching counts.
+
 import {
   getCoreController,
   isDirectRun,
@@ -12,7 +14,7 @@ export async function readPositions(input) {
     standalone: true,
     userAddress: accountAddress,
   });
-  const matching = selectedItems(input, positions);
+  const matching = selectedItems(input, positions, 'position');
   return {
     action: input.action,
     source: 'perps-controller-standalone',

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

@@ -1,3 +1,6 @@
+// Summarize public Perps market data, account state or both for a headless proof.
+// Retain data-source and account identity metadata alongside redacted results.
+
 import {
   getCoreController,
   isDirectRun,

package/library/actions/core/perps/start_state.mjs

@@ -1,21 +1,10 @@
+// Prepare selected testnet baselines before proof, handling positions before orders.
+// Omitted domains are skipped; this headless action performs no UI navigation.
+
 import { isDirectRun, resolveNetwork, runAdapter } from './_controller.mjs';
 import { ensureOrders } from './ensure_orders.mjs';
 import { ensurePositions } from './ensure_positions.mjs';
 
-// core Headless composite that converges the POSITION and ORDER baselines for the
-// selected market(s) on HyperLiquid testnet before the proof window. Mirrors the
-// extension perps-domain-dispatcher start_state semantics but SKIPS every
-// navigation/page/HUD step — headless core has no UI surface.
-//
-// Params (extension schema, testnet-default): profile, market(s)/symbol(s),
-// positions{state,...}, orders{state,...}, network. The UI-only `page`/`hud`
-// fields are accepted by the schema but intentionally ignored here.
-//
-// A baseline block converges to its `state` by composing the ensure_* helpers; a
-// block set to `false` (or omitted) skips that domain. Position convergence runs
-// first (closing a position also clears its TP/SL orders), then order
-// convergence, so the final order baseline is authoritative.
-
 const BASELINE_KEYS = [
   'market',
   'symbol',

package/library/actions/core/perps/teardown_state.mjs

@@ -1,21 +1,10 @@
+// Restore selected testnet baselines, canceling orders before closing positions.
+// Omitted domains default to empty; explicit false skips a domain.
+
 import { isDirectRun, resolveNetwork, runAdapter } from './_controller.mjs';
 import { ensureOrders } from './ensure_orders.mjs';
 import { ensurePositions } from './ensure_positions.mjs';
 
-// core Headless composite that restores the POSITION and ORDER baselines for the
-// selected market(s) on HyperLiquid testnet after the proof window. Mirrors the
-// extension perps-domain-dispatcher teardown_state semantics but SKIPS every
-// navigation/page/HUD step — headless core has no UI surface.
-//
-// Params (extension schema, testnet-default): profile, market(s)/symbol(s),
-// positions{state,...}, orders{state,...}, network. The UI-only `page`/`hud`
-// fields are accepted by the schema but intentionally ignored here.
-//
-// Teardown defaults BOTH domains to state=none (leave the shared dev account
-// FLAT) when a baseline block is omitted; pass a block explicitly to override, or
-// `false` to skip a domain. Orders are canceled FIRST, then positions are closed,
-// so resting orders never re-arm against a position mid-teardown.
-
 const BASELINE_KEYS = [
   'market',
   'symbol',

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

@@ -1,3 +1,6 @@
+// Manage full or partial TP/SL for a selected testnet position and verify the resulting triggers.
+// Fractional sizes use live venue quantity precision.
+
 import {
   configuredSymbols,
   controllerRejection,
@@ -10,14 +13,6 @@ import {
   selectedItems,
 } from './_controller.mjs';
 
-// core Set or replace the TP/SL attached to an existing Perps POSITION by driving
-// the headless PerpsController.updatePositionTPSL() through the full
-// signing/provider path. This is the position-bound half of the advanced-order
-// contract (TAT-3511): it covers both whole-position TP/SL and PARTIAL
-// (quantity-scoped) TP/SL, which the provider must express as standalone
-// reduce-only trigger orders because a position-bound TP/SL always closes the
-// whole position.
-//
 // Params use the controller's own provider-agnostic names: take_profit_price /
 // take_profit_size / stop_loss_price / stop_loss_size (camelCase aliases
 // accepted). Omitting a price removes that side; omitting a size covers the
@@ -129,9 +124,6 @@ export async function updatePositionTpsl(input) {
   // Prices and sizes are resolved from live mid and the actual position, so a
   // recipe never has to name a number that only holds for one market at one
   // moment. An absolute value still wins when the caller gives one.
-  // Both derivations below need the market, and each used to fetch it
-  // separately. getMarketDataWithPrices reads every market, so doing it twice in
-  // one adapter is what pushed this past the node timeout.
   let market;
   const readMarket = async () => {
     if (market === undefined) {
@@ -181,11 +173,16 @@ export async function updatePositionTpsl(input) {
 
   if (takeProfitFraction !== undefined || stopLossFraction !== undefined) {
     const absolutePositionSize = Math.abs(Number(position.size ?? position.szi ?? 0));
-    // Round to the market's own size precision before submitting. The venue
-    // rounds anyway, and the read-back below matches on size — so an unrounded
-    // fraction asks for a size that can never come back, and the poll spins
-    // until it times out.
-    const szDecimals = Number((await readMarket())?.szDecimals);
+    // MarketInfo carries quantity precision; formatted market prices do not.
+    const markets = await controller.getMarkets({ symbols: [symbol] });
+    const szDecimals = markets.find(
+      (item) => item.name.toUpperCase() === symbol.toUpperCase(),
+    )?.szDecimals;
+    if (!Number.isInteger(szDecimals) || szDecimals < 0) {
+      throw new Error(
+        `core updatePositionTPSL found no valid size precision for ${symbol}.\nNext: run mm-harness verify --adapter core`,
+      );
+    }
     const fromFraction = (raw, name) => {
       const fraction = Number(raw);
       if (!Number.isFinite(fraction) || fraction <= 0 || fraction > 1) {
@@ -194,9 +191,6 @@ export async function updatePositionTpsl(input) {
         );
       }
       const exact = absolutePositionSize * fraction;
-      if (!Number.isFinite(szDecimals)) {
-        return String(exact);
-      }
       const rounded = Number(exact.toFixed(szDecimals));
       if (rounded <= 0) {
         throw new Error(

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

@@ -1,3 +1,6 @@
+// Derive public account identities from the checkout's wallet fixture and apply scope selection.
+// Credential values are not included in the returned account list.
+
 import { readFile, writeFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';

package/library/actions/extension/analytics/consent.mjs

@@ -1,3 +1,5 @@
+// Builds controller requests to set and verify analytics consent.
+// The fallback reloads the page with a temporary Chrome bridge and removes it afterward.
 export function consentControllerExpression({
   bridgeSymbol,
   participate,

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

@@ -1,3 +1,5 @@
+// Sets MetaMetrics and marketing consent through background controllers and checks settled state.
+// Reloads with a temporary Chrome bridge when the debug request bridge is unavailable.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { consentParams } from '../../shared/analytics/consent.mjs';
 import {

package/library/actions/extension/assets/home-token-identity.mjs

@@ -0,0 +1,31 @@
+// Opens a Home token to verify its ERC-20 identity from the details route, then returns Home.
+import { openHome } from '../ui/navigate.mjs';
+
+export async function verifyHomeIdentity(page, token, assetId, timeoutMs) {
+  try {
+    await page.clickPoint(token.point.x, token.point.y);
+    const deadline = Date.now() + timeoutMs;
+    let route;
+    while (Date.now() < deadline) {
+      const value = String(await page.evaluate('location.hash'));
+      if (value.startsWith('#/asset/')) {
+        route = value;
+        break;
+      }
+      await page.evaluate('new Promise((resolve) => setTimeout(resolve, 150))');
+    }
+    if (!route) throw new Error('The selected Home token did not expose an asset-details route.');
+    const [, , chainId, address] = route.split('/');
+    if (!/^0x[0-9a-f]+$/iu.test(chainId ?? '') || !/^0x[0-9a-f]{40}$/iu.test(address ?? '')) {
+      throw new Error('The selected Home route does not expose an ERC-20 identity.');
+    }
+    const observed = `eip155:${BigInt(chainId).toString()}/erc20:${address.toLowerCase()}`;
+    if (observed !== assetId) {
+      throw new Error(`Home asset identity ${observed} does not match ${assetId}.\nNext: select a network filter with an unambiguous matching token before continuing.`);
+    }
+    return { assetId, route, verified: true };
+  } finally {
+    await openHome(page, timeoutMs);
+    delete token.point;
+  }
+}

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

@@ -1,10 +1,15 @@
+// Imports an ERC-20 through token management and checks its Home row.
+// Reusing a visible token requires a matching details-route identity and an unchanged account.
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { readWalletStateExpression } from '../wallet/state.mjs';
+import { verifyHomeIdentity } from './home-token-identity.mjs';
 
 const OPTIONS = dataTestId('asset-list-control-bar-action-button');
 const MANAGE = dataTestId('manageTokens__button');
 const ADD = dataTestId('token-management-add-custom-token-button');
 const PAGE = dataTestId('custom-token-import-page');
 const NETWORK = dataTestId('network-selector');
+const NETWORK_PICKER = dataTestId('custom-token-import-network-selector');
 const ADDRESS = dataTestId('custom-token-import-address-input');
 const SYMBOL = dataTestId('custom-token-import-symbol-input');
 const DECIMALS = dataTestId('custom-token-import-decimal-input');
@@ -33,96 +38,69 @@ async function waitFor(page, predicate, message, timeoutMs) {
   throw new Error(message);
 }
 
-async function visibleButton(page, label) {
-  const marker = `mm-harness-${Date.now()}-${Math.random().toString(16).slice(2)}`;
-  const found = await page.evaluate(`(() => {
-    const label = ${JSON.stringify(label)};
-    const marker = ${JSON.stringify(marker)};
-    for (const element of document.querySelectorAll('button')) {
-      const text = String(element.innerText || element.textContent || '').replace(/\\s+/gu, ' ').trim();
-      const style = getComputedStyle(element);
-      const rect = element.getBoundingClientRect();
-      if (text === label && style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0) {
-        element.setAttribute('data-mm-harness-target', marker);
-        return true;
-      }
-    }
-    return false;
-  })()`);
-  if (!found) throw new Error(`Visible button ${JSON.stringify(label)} was not found.`);
-  return `[data-mm-harness-target="${marker}"]`;
-}
-
-async function networkOption(page, network, chainId) {
+async function networkOption(page, chainId) {
   return page.evaluate(`(() => {
-    const network = ${JSON.stringify(network.toLowerCase())};
+    const picker = document.querySelector(${JSON.stringify(NETWORK_PICKER)});
+    if (!picker) return null;
     const chainIds = new Set(${JSON.stringify([
       String(chainId),
       `0x${chainId.toString(16)}`,
       `eip155:${chainId}`,
     ].map((value) => value.toLowerCase()))});
-    for (const element of document.querySelectorAll('[data-testid^="network-list-item-"]')) {
+    for (const element of picker.querySelectorAll('[data-testid^="network-list-item-"]')) {
       const testId = String(element.getAttribute('data-testid') || '');
       const suffix = testId.slice('network-list-item-'.length).toLowerCase();
+      if (!chainIds.has(suffix)) continue;
+      element.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+      const rect = element.getBoundingClientRect();
+      const hit = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+      if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })
+        || rect.width <= 0 || rect.height <= 0 || !hit || !element.contains(hit)) continue;
       const label = String(element.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 500);
-      if (chainIds.has(suffix) || label.toLowerCase().includes(network)) return { testId, label };
+      return { testId, label };
     }
     return null;
   })()`);
 }
 
-async function homeToken(page, symbol) {
+async function homeToken(page, symbol, verifyIdentity = false) {
   return page.evaluate(`(() => {
     const symbol = ${JSON.stringify(symbol.toLowerCase())};
+    const verifyIdentity = ${JSON.stringify(verifyIdentity)};
+    const matches = [];
     for (const row of document.querySelectorAll('[data-testid="multichain-token-list-button"]')) {
       const name = String(row.querySelector('[data-testid="multichain-token-list-item-token-name"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
       const amount = String(row.querySelector('[data-testid="multichain-token-list-item-value"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
       const observed = amount.match(/\\b([A-Za-z][A-Za-z0-9]{1,11})$/u)?.[1] || '';
-      if (observed.toLowerCase() === symbol) return { name, symbol: observed.toUpperCase(), amount };
+      const style = getComputedStyle(row);
+      const rect = row.getBoundingClientRect();
+      if (observed.toLowerCase() !== symbol || style.display === 'none' || style.visibility === 'hidden'
+        || rect.width <= 0 || rect.height <= 0) continue;
+      matches.push({ row, name, symbol: observed.toUpperCase(), amount });
     }
-    return null;
+    if (matches.length > 1) throw new Error('Visible token symbol matches multiple rows; identity is ambiguous.\\nNext: narrow the product network filter before importing.');
+    if (!matches.length) return null;
+    const { row, ...token } = matches[0];
+    if (verifyIdentity) {
+      row.scrollIntoView({ block: 'center', inline: 'nearest' });
+      const rect = row.getBoundingClientRect();
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      const hit = document.elementFromPoint(x, y);
+      if (!hit || !row.contains(hit)) throw new Error('The matching Home token is covered; identity cannot be verified.\\nNext: uncover the token row before importing.');
+      token.point = { x, y };
+    }
+    return token;
   })()`);
 }
 
-async function importedTokenIdentity(page, chainId, address, expectedSymbol) {
-  return page.evaluate(`(async () => {
-    const hooks = globalThis.stateHooks || {};
-    const root = (await hooks.getCleanAppState?.()) || hooks.store?.getState?.() || {};
-    const state = root.metamask || root;
-    const allTokens = state.allTokens;
-    const selectedAddress = String(state.selectedAddress || '').toLowerCase();
-    if (!allTokens || typeof allTokens !== 'object' || !selectedAddress) {
-      return { available: false, token: null };
-    }
-    const expectedChainId = ${JSON.stringify(chainId)};
-    const chainEntry = Object.entries(allTokens).find(([key]) => {
-      const normalized = String(key).toLowerCase();
-      const value = normalized.startsWith('eip155:')
-        ? Number(normalized.slice('eip155:'.length))
-        : normalized.startsWith('0x')
-          ? Number.parseInt(normalized.slice(2), 16)
-          : Number(normalized);
-      return value === expectedChainId;
-    });
-    const accountEntry = chainEntry && Object.entries(chainEntry[1] || {})
-      .find(([account]) => String(account).toLowerCase() === selectedAddress);
-    const tokens = Array.isArray(accountEntry?.[1]) ? accountEntry[1] : [];
-    const expectedAddress = ${JSON.stringify(address.toLowerCase())};
-    const expectedSymbol = ${JSON.stringify(expectedSymbol)};
-    const token = tokens.find((entry) => {
-      const tokenAddress = String(entry?.address || entry?.contractAddress || '').toLowerCase();
-      return tokenAddress === expectedAddress && String(entry?.symbol || '').toUpperCase() === expectedSymbol;
-    });
-    return {
-      available: true,
-      token: token ? {
-        address: String(token.address || token.contractAddress),
-        symbol: String(token.symbol),
-        decimals: token.decimals == null ? null : String(token.decimals),
-        chainId: chainEntry?.[0] || null,
-      } : null,
-    };
-  })()`, { awaitPromise: true });
+async function selectedEvmAccount(page) {
+  const { selectedAccount } = await page.evaluate(readWalletStateExpression(), { awaitPromise: true });
+  if (!selectedAccount?.id || !['eip155:eoa', 'eip155:erc4337'].includes(selectedAccount.type)
+    || !/^0x[0-9a-f]{40}$/iu.test(selectedAccount.address ?? '')) {
+    throw new Error('The selected EVM account is unavailable; existing token identity cannot be verified.\nNext: select the intended EVM account before importing.');
+  }
+  return { id: selectedAccount.id, address: selectedAccount.address.toLowerCase(), type: selectedAccount.type };
 }
 
 runAdapter(async (input) => withExtensionPage(input, async (page) => {
@@ -136,39 +114,44 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
     throw new Error('metamask.assets.import_custom_token requires network, positive chain_id, ERC-20 address, and expected_symbol.');
   }
 
-  const existingToken = await homeToken(page, expectedSymbol);
-  const existingIdentity = existingToken
-    ? await importedTokenIdentity(page, chainId, address, expectedSymbol)
-    : null;
-  if (existingToken && existingIdentity?.token) {
+  const account = await selectedEvmAccount(page);
+  const existingToken = await homeToken(page, expectedSymbol, true);
+  if (existingToken) {
+    const existingIdentity = await verifyHomeIdentity(
+      page, existingToken, `eip155:${chainId}/erc20:${address.toLowerCase()}`, timeoutMs,
+    );
+    const afterAccount = await selectedEvmAccount(page);
+    if (JSON.stringify(afterAccount) !== JSON.stringify(account)) {
+      throw new Error('The selected EVM account changed while checking the existing token.\nNext: keep the intended account selected for the full import check.');
+    }
     return {
       action: input.action,
       network,
       chainId,
       address,
       alreadyImported: true,
+      changed: false,
       token: existingToken,
-      identity: existingIdentity.token,
+      identity: { ...existingIdentity, account, address, symbol: expectedSymbol, decimals: null, chainId: `0x${chainId.toString(16)}` },
       proofPath: 'trusted-pointer-visible-ui',
     };
   }
 
   if (!(await visible(page, MANAGE))) await page.click(OPTIONS);
   await waitFor(page, () => visible(page, MANAGE), 'Manage tokens did not become visible.', timeoutMs);
-  await page.click(await visibleButton(page, 'Manage tokens'));
+  await page.click(MANAGE);
   await waitFor(page, () => visible(page, ADD), 'Add a custom token did not become visible.', timeoutMs);
-  await page.click(await visibleButton(page, 'Add a custom token'));
+  await page.click(ADD);
   await waitFor(page, () => visible(page, PAGE), 'Custom token import did not open.', timeoutMs);
   await page.click(NETWORK);
   const selectedNetwork = await waitFor(
     page,
-    () => networkOption(page, network, chainId),
+    () => networkOption(page, chainId),
     `${network} (${chainId}) was not available in the custom token network selector.`,
     timeoutMs,
   );
-  await page.click(dataTestId(selectedNetwork.testId));
-  await waitFor(page, () => visible(page, ADDRESS), 'Custom token address input did not become visible.', timeoutMs);
-  await page.evaluate('new Promise((resolve) => setTimeout(resolve, 2000))');
+  await page.click(`${NETWORK_PICKER} ${dataTestId(selectedNetwork.testId)}`);
+  await waitFor(page, async () => !(await visible(page, NETWORK_PICKER)) && await visible(page, ADDRESS), 'Custom token network selection did not return to the address form.', timeoutMs);
   await page.setInput(ADDRESS, address);
 
   let metadataSource = 'network';
@@ -183,7 +166,7 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
       return state.symbol && state.enabled ? state : null;
     }, 'Custom token metadata did not resolve to an enabled import.', Math.min(timeoutMs, 15_000));
   } catch (error) {
-    if (expectedDecimals === null) throw error;
+    if (expectedDecimals === null || !(await visible(page, SYMBOL)) || !(await visible(page, DECIMALS))) throw error;
     metadataSource = 'manual';
     await page.setInput(SYMBOL, expectedSymbol);
     await page.setInput(DECIMALS, expectedDecimals);
@@ -216,6 +199,7 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
 
   return {
     action: input.action,
+    changed: true,
     network: selectedNetwork.label || network,
     chainId,
     address,

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

@@ -1,3 +1,4 @@
+// Opens asset details from a uniquely visible token symbol and waits for the asset route.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 runAdapter(async (input) => withExtensionPage(input, async (page) => {
@@ -6,19 +7,30 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
   if (!/^[A-Z0-9._-]{2,20}$/u.test(symbol)) {
     throw new Error('metamask.assets.open_details requires a valid token symbol.');
   }
-  const selector = await page.evaluate(`(() => {
+  const match = await page.evaluate(`(() => {
     const symbol = ${JSON.stringify(symbol)};
-    for (const [index, row] of [...document.querySelectorAll('[data-testid="multichain-token-list-button"]')].entries()) {
+    const selectors = [];
+    for (const row of document.querySelectorAll('[data-testid="multichain-token-list-button"]')) {
+      const style = getComputedStyle(row);
+      const rect = row.getBoundingClientRect();
+      if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0
+        || rect.bottom <= 0 || rect.right <= 0 || rect.top >= innerHeight || rect.left >= innerWidth) continue;
       const amount = String(row.querySelector('[data-testid="multichain-token-list-item-value"]')?.innerText || '').trim();
       const observed = amount.match(/\\b([A-Za-z][A-Za-z0-9._-]{1,19})$/u)?.[1]?.toUpperCase();
       if (observed !== symbol) continue;
-      row.setAttribute('data-mm-harness-asset-index', String(index));
-      return '[data-mm-harness-asset-index="' + index + '"]';
+      const parts = [];
+      for (let element = row; element; element = element.parentElement) {
+        const index = element.parentElement
+          ? [...element.parentElement.children].indexOf(element) + 1 : 1;
+        parts.unshift(element.localName + ':nth-child(' + index + ')');
+      }
+      selectors.push(parts.join(' > '));
     }
-    return null;
+    return { count: selectors.length, selector: selectors.length === 1 ? selectors[0] : null };
   })()`);
-  if (!selector) throw new Error(`Visible asset ${symbol} was not found.`);
-  await page.click(selector);
+  if (!match.count) throw new Error(`Visible asset ${symbol} was not found.`);
+  if (match.count !== 1) throw new Error(`Visible asset ${symbol} matches ${match.count} rows; selection is ambiguous.\nNext: use a uniquely visible token symbol or narrow the product network filter before retrying.`);
+  await page.click(match.selector);
   const deadline = Date.now() + timeoutMs;
   while (Date.now() <= deadline) {
     if (String(await page.evaluate('location.hash')).startsWith('#/asset/')) {

package/library/actions/extension/assets/prepare_send.mjs

@@ -1,3 +1,4 @@
+// Fills a token send with a recipient and explicit or Max amount, stopping at enabled Continue.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import { selectors, tokenRow, visible, waitFor } from './send.mjs';