@deeeed/metamask-harness 0.37.0 → 0.38.1

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

@@ -0,0 +1,31 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+import {
+  normalizeVisibleSwapBridgeState,
+  resolveVisibleSwapBridgeOptions,
+} from '../../shared/swap-bridge/visible-state.mjs';
+
+runAdapter(async (input) => {
+  const options = resolveVisibleSwapBridgeOptions(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 Swap state is unavailable${warning ? `: ${warning}` : '.'}`);
+  }
+  return {
+    action: input.action,
+    ...normalizeVisibleSwapBridgeState({
+      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/swap_bridge/select_assets.mjs

@@ -0,0 +1,94 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { resolveAssetSelectionOptions } from '../../shared/swap-bridge/transaction.mjs';
+import {
+  closeSwapNativeSession,
+  createSwapNativeSession,
+  nativeLabel,
+  nativeNode,
+} from './native-session.mjs';
+
+async function waitFor(session, identifier, timeoutMs) {
+  await session.execute('ui.wait_for', {
+    test_id: identifier,
+    expected: 'visible',
+    timeout_ms: timeoutMs,
+    settle: false,
+  });
+}
+
+function androidChainId(chain) {
+  const match = String(chain).match(/^eip155:(\d+)$/u);
+  return match ? `0x${Number(match[1]).toString(16)}` : String(chain);
+}
+
+async function selectAsset(session, role, asset, timeoutMs, pickerAlreadyOpen = false) {
+  const picker = role === 'source' ? 'source-token-area' : 'dest-token-area';
+  if (!pickerAlreadyOpen) await session.execute('ui.press', { test_id: picker, timeout_ms: timeoutMs });
+  await waitFor(session, 'bridge-token-search-input', timeoutMs);
+  await session.execute('ui.press', { text: 'All', timeout_ms: timeoutMs });
+  await session.execute('ui.set_input', {
+    test_id: 'bridge-token-search-input',
+    value: asset.query,
+    timeout_ms: timeoutMs,
+  });
+  const row = `asset-${androidChainId(asset.chain)}-${asset.symbol}`;
+  await session.execute('ui.key_press', { key: 'BACK', timeout_ms: timeoutMs });
+  await revealAssetRow(session, row, timeoutMs);
+  await session.execute('ui.press', { test_id: row, timeout_ms: timeoutMs });
+  await waitFor(session, picker, timeoutMs);
+  const selected = nativeLabel(nativeNode(await session.snapshot(), picker));
+  if (!selected.toUpperCase().includes(asset.symbol)) {
+    throw new Error(`Swap ${role} asset ${asset.symbol} was not selected; observed ${JSON.stringify(selected)}.`);
+  }
+  return { role, testId: row, symbol: asset.symbol, chain: asset.chain };
+}
+
+async function revealAssetRow(session, row, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    if (nativeNode(await session.snapshot(), row)) return;
+    await session.execute('ui.scroll', {
+      direction: 'down',
+      amount: 0.75,
+      timeout_ms: Math.max(1, deadline - Date.now()),
+      settle: false,
+    });
+  }
+  throw new Error(`Swap asset row ${row} was not visible in the all-network token list.`);
+}
+
+async function closeOpenPicker(session, timeoutMs) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const snapshot = await session.snapshot();
+    if (!nativeNode(snapshot, 'bridge-token-search-input')) return;
+    await session.execute('ui.key_press', { key: 'BACK', timeout_ms: timeoutMs });
+  }
+  if (nativeNode(await session.snapshot(), 'bridge-token-search-input')) {
+    throw new Error('Swap token picker remained open after dismissing its keyboard and sheet.');
+  }
+}
+
+runAdapter(async (input) => {
+  const options = resolveAssetSelectionOptions(input.node);
+  if (options.sourceAssetId || options.destinationAssetId) {
+    throw new Error('Mobile Swap selection cannot disambiguate asset IDs from native accessibility. Next: omit source_asset_id and destination_asset_id or run the Extension recipe.');
+  }
+  const session = createSwapNativeSession(input);
+  try {
+    await closeOpenPicker(session, options.timeoutMs);
+    await waitFor(session, 'source-token-area-input', options.timeoutMs);
+    const source = await selectAsset(session, 'source', {
+      chain: options.sourceChain,
+      symbol: options.sourceSymbol,
+      query: options.sourceQuery,
+    }, options.timeoutMs);
+    const destination = await selectAsset(session, 'destination', {
+      chain: options.destinationChain,
+      symbol: options.destinationSymbol,
+      query: options.destinationQuery,
+    }, options.timeoutMs);
+    return { action: input.action, source, destination, proofPath: 'native-accessibility-selection' };
+  } finally {
+    await closeSwapNativeSession(session);
+  }
+});

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

@@ -0,0 +1,73 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { resolveAmountOptions } from '../../shared/swap-bridge/transaction.mjs';
+import {
+  closeSwapNativeSession,
+  createSwapNativeSession,
+  nativeLabel,
+  nativeNode,
+} from './native-session.mjs';
+
+async function replaceNumericInput(session, amount, timeoutMs) {
+  await session.execute('ui.press', {
+    test_id: 'source-token-area-input',
+    timeout_ms: timeoutMs,
+    settle: false,
+  });
+  let current = nativeLabel(nativeNode(await session.snapshot(), 'source-token-area-input'));
+  for (let index = 0; index < Math.min(50, current.length + 2); index += 1) {
+    await session.execute('ui.press', {
+      test_id: 'keypad-delete-button',
+      timeout_ms: timeoutMs,
+      settle: false,
+    });
+  }
+  current = nativeLabel(nativeNode(await session.snapshot(), 'source-token-area-input'));
+  if (current !== '0' && current !== '') {
+    throw new Error(`Swap amount keypad could not clear the previous value ${JSON.stringify(current)}.`);
+  }
+  const keys = amount.startsWith('0.') && current === '0' ? amount.slice(1) : amount;
+  for (const key of keys) {
+    if (!/[0-9.]/u.test(key)) throw new Error(`Swap amount contains unsupported keypad character ${JSON.stringify(key)}.`);
+    await session.execute('ui.press', {
+      test_id: key === '.' ? 'keypad-key-dot' : `keypad-key-${key}`,
+      timeout_ms: timeoutMs,
+      settle: false,
+    });
+  }
+  await new Promise((resolve) => setTimeout(resolve, 300));
+}
+
+runAdapter(async (input) => {
+  const options = resolveAmountOptions(input.node);
+  const session = createSwapNativeSession(input);
+  try {
+    await replaceNumericInput(session, options.amount, options.timeoutMs);
+    const deadline = Date.now() + Math.max(1_000, options.timeoutMs - 10_000);
+    let observed;
+    do {
+      const snapshot = await session.snapshot();
+      const sourceAmount = nativeLabel(nativeNode(snapshot, 'source-token-area-input'));
+      const destinationAmount = nativeLabel(nativeNode(snapshot, 'dest-token-area-input'));
+      const cta = nativeNode(snapshot, 'bridge-confirm-button') ?? nativeNode(snapshot, 'bridge-confirm-button-keypad');
+      const noQuote = nativeNode(snapshot, 'bridge-no-quotes');
+      observed = {
+        sourceAmount,
+        destinationAmount,
+        cta: nativeLabel(cta) || null,
+        ctaEnabled: cta?.enabled !== false,
+        noQuote: Boolean(noQuote),
+      };
+      if (!options.waitForQuote || observed.noQuote || (Number(destinationAmount) > 0 && cta)) break;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    } while (Date.now() < deadline);
+    if (observed.sourceAmount !== options.amount) {
+      throw new Error(`Swap source amount mismatch: expected ${options.amount}, observed ${observed.sourceAmount}.`);
+    }
+    if (options.waitForQuote && !observed.noQuote && !(Number(observed.destinationAmount) > 0 && observed.cta)) {
+      throw new Error(`Swap quote did not resolve within ${options.timeoutMs}ms.`);
+    }
+    return { action: input.action, ...observed, proofPath: 'native-accessibility-amount' };
+  } finally {
+    await closeSwapNativeSession(session);
+  }
+});

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

@@ -1,5 +1,6 @@
 import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
 import { createAgentDeviceClient } from 'agent-device';
+import { nativeSessionName } from '../platform/native-session-name.mjs';
 
 const IDS = {
   wallet: ['wallet-safe-area', 'homepage-container'],
@@ -7,6 +8,10 @@ const IDS = {
   tradeTab: 'tab-bar-item-Trade',
   perpsEntry: 'homepage-balance-breakdown-row-perps',
   perpsTradeEntry: 'wallet-perps-action',
+  swapTradeEntry: 'wallet-actions-bottom-sheet-swap-button',
+  swapSourceInput: 'source-token-area-input',
+  swapSourceToken: 'source-token-area',
+  swapDestinationToken: 'dest-token-area',
   perpsHome: 'perps-home',
   perpsHomeBack: 'perps-home-back-button',
   tutorialSkip: 'perps-tutorial-skip-button',
@@ -27,8 +32,7 @@ export async function navigateOpaqueMobile(input, destination) {
     throw new Error('Opaque Mobile navigation requires one explicit Android device serial.');
   }
   const app = String(env.ANDROID_PACKAGE_ID ?? 'io.metamask');
-  const session = `mm-harness-navigation-${process.pid}-${String(input.context?.nodeId ?? 'navigate')}`
-    .replace(/[^A-Za-z0-9._-]/gu, '-');
+  const session = nativeSessionName(env, device, app);
   const client = createAgentDeviceClient({
     session,
     lockPolicy: 'reject',
@@ -84,6 +88,10 @@ export async function navigateOpaqueMobile(input, destination) {
     if (destination.page === 'home') {
       await navigateHome({ identifiers, press, wait, back });
       observedScreen = 'wallet-home';
+    } else if (destination.page === 'swap') {
+      observedScreen = await navigateSwap({ identifiers, press, wait, back });
+    } else if (destination.page === 'perps-market-list') {
+      observedScreen = await navigatePerpsMarketList({ identifiers, press, wait, back, timeoutMs: Number(input.node?.timeout_ms ?? 30_000) });
     } else {
       const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
       const initialIds = await identifiers();
@@ -116,10 +124,29 @@ export async function navigateOpaqueMobile(input, destination) {
       observedScreen,
     };
   } finally {
-    await closeNativeSession(transport, client, selection);
+    await closeNativeSession(client, selection);
   }
 }
 
+async function navigateSwap({ identifiers, press, wait, back }) {
+  let ids = await identifiers();
+  if (ids.has(IDS.swapSourceInput)) return IDS.swapSourceInput;
+  if (!ids.has(IDS.swapTradeEntry)) {
+    await navigateHome({ identifiers, press, wait, back });
+    await press(IDS.tradeTab);
+    await wait(IDS.swapTradeEntry);
+    ids = await identifiers();
+  }
+  if (!ids.has(IDS.swapTradeEntry)) {
+    throw new Error('Opaque Mobile navigation could not find the visible Swap entry.');
+  }
+  await press(IDS.swapTradeEntry);
+  await wait(IDS.swapSourceInput);
+  await wait(IDS.swapSourceToken);
+  await wait(IDS.swapDestinationToken);
+  return IDS.swapSourceInput;
+}
+
 async function selectMarket({ destination, identifiers, press, snapshot, timeoutMs }) {
   const market = String(destination.params.market.symbol).toUpperCase();
   await press(`perps-market-row-item-${market}`);
@@ -195,6 +222,20 @@ async function navigatePerps({ identifiers, press, wait, back, timeoutMs }) {
   return waitForPerpsDestination(identifiers, timeoutMs);
 }
 
+async function navigatePerpsMarketList({ identifiers, press, wait, back, timeoutMs }) {
+  let ids = await identifiers();
+  if (ids.has(IDS.marketList)) return IDS.marketList;
+  const observed = await navigatePerps({ identifiers, press, wait, back, timeoutMs });
+  ids = await identifiers();
+  if (ids.has(IDS.marketList)) return IDS.marketList;
+  if (ids.has(IDS.proMarketList)) {
+    await press(IDS.proMarketList);
+    await wait(IDS.marketList);
+    return IDS.marketList;
+  }
+  throw new Error(`Opaque Mobile navigation reached ${observed}, but no visible market-list control was available.`);
+}
+
 async function waitForPerpsDestination(identifiers, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() <= deadline) {
@@ -207,8 +248,7 @@ async function waitForPerpsDestination(identifiers, timeoutMs) {
   throw new Error('Opaque Mobile navigation did not reach a visible Perps destination.');
 }
 
-async function closeNativeSession(transport, client, selection) {
-  await transport.close();
+async function closeNativeSession(client, selection) {
   try {
     await client.sessions.close({ ...selection, responseLevel: 'digest' });
   } catch (error) {

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

@@ -4,6 +4,8 @@ import { navigateOpaqueMobile } from './native-navigation.mjs';
 const PAGE_ROUTES = {
   home: { route: 'WalletView', params: {} },
   perps: { route: 'PerpsMarketListView', params: {} },
+  'perps-market-list': { route: 'PerpsMarketListView', params: {} },
+  swap: { route: 'BridgeView', params: {} },
 };
 
 function text(value) {
@@ -19,7 +21,7 @@ function pageRoute(node) {
     if (!market) throw new Error('mobile ui.navigate page=perps-market requires market or symbol.');
     return { page, route: 'PerpsMarketDetails', params: { market: { symbol: market } } };
   }
-  throw new Error('mobile ui.navigate supported page intents: home, perps, perps-market.');
+  throw new Error('mobile ui.navigate supported page intents: home, perps, perps-market-list, perps-market, swap.');
 }
 
 runAdapter(async (input) => {

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

@@ -6,6 +6,7 @@ import {
   selectBridgeStatusEntry,
 } from '../platform/bridge.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
+import { isOpaqueMobileRuntime, unlockWalletThroughNativeUi } from './native-ui.mjs';
 
 async function fixturePassword(projectRoot) {
   const candidates = [
@@ -156,6 +157,22 @@ async function waitForStableUnlocked(input, initialStatus, stableMs = 750) {
 }
 
 export async function ensureUnlocked(input) {
+  if (isOpaqueMobileRuntime(input)) {
+    const timeoutMs = Number(input.node?.unlock_timeout_ms ?? 30_000);
+    const password = input.node?.password ?? await fixturePassword(input.context.projectRoot);
+    const proof = await unlockWalletThroughNativeUi(input, String(password), timeoutMs);
+    return {
+      action: input.action,
+      unlocked: true,
+      alreadyUnlocked: proof.alreadyReady,
+      account: proof.selectedAddress || proof.selectedAddressObserved
+        ? { address: proof.selectedAddress ?? proof.selectedAddressObserved }
+        : null,
+      redacted: true,
+      provider: proof.provider,
+      proofPath: proof.proofPath,
+    };
+  }
   const targetTimeoutMs = Number(input.node?.target_timeout_ms ?? 20000);
   const targetDeadline = Date.now() + targetTimeoutMs;
   const targetStatus = await waitForTargetStatus(input, targetTimeoutMs);

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

@@ -1,5 +1,6 @@
 import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
 import { createAgentDeviceClient } from 'agent-device';
+import { nativeSessionName } from '../platform/native-session-name.mjs';
 
 const TEST_IDS = {
   existingWallet: 'wallet-setup-screen-have-an-existing-wallet-button-id',
@@ -163,6 +164,25 @@ export async function readWalletThroughNativeUi(input) {
   }
 }
 
+export async function unlockWalletThroughNativeUi(input, password, timeoutMs) {
+  const native = nativeSession(input);
+  try {
+    const initial = await native.normalizeWalletSurface(timeoutMs);
+    if (initial.wallet) {
+      return await native.walletProof(undefined, true, timeoutMs);
+    }
+    if (!initial.visible.has(TEST_IDS.login)) {
+      throw new Error('Opaque Mobile wallet unlock could not find the visible login screen.');
+    }
+    await native.fill(TEST_IDS.loginPassword, password, timeoutMs);
+    await native.press(TEST_IDS.loginButton, timeoutMs);
+    await native.waitForWallet(timeoutMs);
+    return await native.walletProof(undefined, false, timeoutMs);
+  } finally {
+    await native.close();
+  }
+}
+
 export async function resetWalletThroughNativeUi(input) {
   const native = nativeSession(input);
   const timeoutMs = Number(input.node?.timeout_ms ?? 60_000);
@@ -198,8 +218,7 @@ function nativeSession(input) {
   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 session = nativeSessionName(env, device, app);
   const client = createAgentDeviceClient({
     session,
     lockPolicy: 'reject',

package/library/actions/shared/assets/visible-state.mjs

@@ -0,0 +1,176 @@
+function boundedInteger(value, fallback, minimum, maximum, name) {
+  const resolved = value == null ? fallback : Number(value);
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new Error(
+      `metamask.assets.read_visible_state ${name} must be an integer from ${minimum} to ${maximum}.`,
+    );
+  }
+  return resolved;
+}
+
+function stringList(value, name, maximum = 50) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`metamask.assets.read_visible_state ${name} must be an array.`);
+  }
+  const values = Array.from(new Set(value.map((entry) => String(entry).trim().toUpperCase()).filter(Boolean)));
+  if (values.length > maximum) {
+    throw new Error(`metamask.assets.read_visible_state ${name} accepts at most ${maximum} values.`);
+  }
+  return values;
+}
+
+export function resolveVisibleAssetsOptions(node = {}) {
+  return {
+    maxItems: boundedInteger(node.max_items, 100, 1, 200, 'max_items'),
+    minimumAssetCount: boundedInteger(node.minimum_asset_count, 0, 0, 200, 'minimum_asset_count'),
+    minimumPriceChangeCount: boundedInteger(
+      node.minimum_price_change_count,
+      0,
+      0,
+      200,
+      'minimum_price_change_count',
+    ),
+    minimumWithoutPriceChangeCount: boundedInteger(
+      node.minimum_without_price_change_count,
+      0,
+      0,
+      200,
+      'minimum_without_price_change_count',
+    ),
+    requireSymbols: stringList(node.require_symbols, 'require_symbols'),
+    requireFiat: node.require_fiat === true,
+    requirePriceChangeStyling: node.require_price_change_styling === true,
+  };
+}
+
+function text(value) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\s+/gu, ' ').trim();
+  return normalized ? normalized.slice(0, 500) : undefined;
+}
+
+function firstMatch(value, expression) {
+  return text(value)?.match(expression)?.[0];
+}
+
+function priceChangeFromLabel(value) {
+  const label = text(value);
+  if (!label) return undefined;
+  for (const match of label.matchAll(/[+-]?\d+(?:\.\d+)?%/gu)) {
+    const following = label.slice((match.index ?? 0) + match[0].length, (match.index ?? 0) + match[0].length + 8);
+    if (!/^\s*APY\b/iu.test(following)) return match[0];
+  }
+  return undefined;
+}
+
+function symbolFromAmount(value) {
+  return text(value)?.match(/\b([A-Za-z][A-Za-z0-9]{1,11})$/u)?.[1]?.toUpperCase();
+}
+
+function symbolFromTestId(value) {
+  const testId = text(value);
+  if (!testId?.startsWith('asset-')) return undefined;
+  return testId.slice('asset-'.length).trim().toUpperCase() || undefined;
+}
+
+function normalizeItem(source) {
+  const label = text(source?.label);
+  const amount = text(source?.amount) ?? text(label?.split(',').at(-1));
+  const fiat = text(source?.fiat) ?? firstMatch(label, /[$€£¥]\s?\d[\d,]*(?:\.\d{2})(?!\d)/u);
+  const priceChange = text(source?.priceChange) ?? priceChangeFromLabel(label);
+  const symbol = text(source?.symbol)?.toUpperCase() ?? symbolFromTestId(source?.testId) ?? symbolFromAmount(amount);
+  return {
+    testId: text(source?.testId) ?? null,
+    symbol: symbol ?? null,
+    name: text(source?.name) ?? text(label?.split(',')[0]) ?? symbol ?? null,
+    fiat: fiat ?? null,
+    amount: amount ?? null,
+    priceChange: priceChange ?? null,
+    priceChangeTone: text(source?.priceChangeTone)?.toLowerCase() ?? null,
+    ...(label ? { label } : {}),
+  };
+}
+
+export function normalizeVisibleAssetsState(raw, options, platform) {
+  const assets = (Array.isArray(raw.items) ? raw.items : [])
+    .slice(0, options.maxItems)
+    .map(normalizeItem)
+    .filter((item) => item.symbol || item.name);
+  const malformed = assets.filter((item) =>
+    /(?:\bNaN\b|\bundefined\b|\bnull\b)/u.test(
+      [item.label, item.fiat, item.amount, item.priceChange].filter(Boolean).join(' '),
+    )
+  );
+  const state = {
+    source: 'visible-ui',
+    platform,
+    surface: 'token-list',
+    ...(text(raw.route) ? { route: text(raw.route) } : {}),
+    ...(text(raw.title) ? { title: text(raw.title) } : {}),
+    assets,
+    observedSymbols: Array.from(new Set(assets.map((item) => item.symbol).filter(Boolean))),
+    features: {
+      'token-list': assets.length > 0,
+      fiat: assets.some((item) => item.fiat !== null),
+      'price-change': assets.some((item) => item.priceChange !== null),
+      'price-change-styling': assets.some((item) => item.priceChangeTone !== null),
+    },
+    malformedValueCount: malformed.length,
+    truncated: raw.truncated === true || (raw.items?.length ?? 0) > options.maxItems,
+  };
+  assertVisibleAssetsState(state, options);
+  return state;
+}
+
+function assertVisibleAssetsState(state, options) {
+  if (state.assets.length < options.minimumAssetCount) {
+    throw new Error(
+      `Expected at least ${options.minimumAssetCount} visible assets, but observed ${state.assets.length}.`,
+    );
+  }
+  const observed = new Set(state.observedSymbols);
+  const missing = options.requireSymbols.filter((symbol) => !observed.has(symbol));
+  if (missing.length > 0) {
+    throw new Error(`Missing required visible asset symbols: ${missing.join(', ')}.`);
+  }
+  if (options.requireFiat) {
+    const missingFiat = state.assets
+      .filter((item) => options.requireSymbols.length === 0 || options.requireSymbols.includes(item.symbol))
+      .filter((item) => item.fiat === null)
+      .map((item) => item.symbol ?? item.name);
+    if (missingFiat.length > 0) {
+      throw new Error(`Required visible assets lack formatted fiat values: ${missingFiat.join(', ')}.`);
+    }
+  }
+  const priceChangeCount = state.assets.filter((item) => item.priceChange !== null).length;
+  if (priceChangeCount < options.minimumPriceChangeCount) {
+    throw new Error(
+      `Expected price changes for at least ${options.minimumPriceChangeCount} visible assets, but observed ${priceChangeCount}.`,
+    );
+  }
+  const withoutPriceChangeCount = state.assets.length - priceChangeCount;
+  if (withoutPriceChangeCount < options.minimumWithoutPriceChangeCount) {
+    throw new Error(
+      `Expected at least ${options.minimumWithoutPriceChangeCount} clean assets without price-change data, but observed ${withoutPriceChangeCount}.`,
+    );
+  }
+  if (state.malformedValueCount > 0) {
+    throw new Error(`Visible asset values contain ${state.malformedValueCount} malformed entries.`);
+  }
+  if (options.requirePriceChangeStyling) {
+    const invalidStyles = state.assets
+      .filter((item) => item.priceChange !== null)
+      .filter((item) => {
+        const numeric = Number(item.priceChange.replace('%', ''));
+        if (!Number.isFinite(numeric)) return true;
+        if (numeric < 0) return item.priceChangeTone !== 'negative';
+        if (numeric > 0) return item.priceChangeTone !== 'positive';
+        return item.priceChangeTone !== 'neutral';
+      })
+      .map((item) => item.symbol ?? item.name);
+    if (invalidStyles.length > 0) {
+      throw new Error(`Visible price-change styling does not match its sign for: ${invalidStyles.join(', ')}.`);
+    }
+  }
+}

package/library/actions/shared/networks/visible-state.mjs

@@ -0,0 +1,70 @@
+import {
+  normalizeVisibleAssetsState,
+  resolveVisibleAssetsOptions,
+} from '../assets/visible-state.mjs';
+
+function boundedInteger(value, fallback, minimum, maximum, name) {
+  const resolved = value == null ? fallback : Number(value);
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new Error(
+      `metamask.networks.read_visible_state ${name} must be an integer from ${minimum} to ${maximum}.`,
+    );
+  }
+  return resolved;
+}
+
+function normalizedText(value) {
+  return typeof value === 'string' ? value.replace(/\s+/gu, ' ').trim() : '';
+}
+
+export function resolveVisibleNetworkOptions(node = {}) {
+  const network = normalizedText(node.network);
+  if (!network) throw new Error('metamask.networks.read_visible_state requires network.');
+  return {
+    network,
+    chainId: node.chain_id == null ? undefined : boundedInteger(node.chain_id, 0, 1, 2 ** 31 - 1, 'chain_id'),
+    settleMs: boundedInteger(node.settle_ms, 0, 0, 60_000, 'settle_ms'),
+    assets: resolveVisibleAssetsOptions(node),
+  };
+}
+
+export function normalizeVisibleNetworkState(beforeRaw, afterRaw, options, platform) {
+  const selectedNetwork = normalizedText(afterRaw.network ?? beforeRaw.network);
+  if (!selectedNetwork.toLowerCase().includes(options.network.toLowerCase())) {
+    throw new Error(
+      `Expected selected network ${options.network}, but observed ${selectedNetwork || 'none'}.`,
+    );
+  }
+  const forbiddenError = 'none of the cryptocurrencies are supported by price api';
+  const errors = [beforeRaw.errorText, afterRaw.errorText]
+    .map(normalizedText)
+    .filter((value) => value.toLowerCase().includes(forbiddenError));
+  if (errors.length > 0) {
+    throw new Error(`Selected network ${options.network} displayed a price API error.`);
+  }
+  const before = normalizeVisibleAssetsState(beforeRaw, options.assets, platform);
+  const after = normalizeVisibleAssetsState(afterRaw, options.assets, platform);
+  const afterBySymbol = new Map(after.assets.map((asset) => [asset.symbol, asset]));
+  const unstable = before.assets
+    .filter((asset) => options.assets.requireSymbols.length === 0 || options.assets.requireSymbols.includes(asset.symbol))
+    .filter((asset) => {
+      const current = afterBySymbol.get(asset.symbol);
+      return !current || current.amount !== asset.amount;
+    })
+    .map((asset) => asset.symbol ?? asset.name);
+  if (unstable.length > 0) {
+    throw new Error(`Network asset rows did not persist across the settle window: ${unstable.join(', ')}.`);
+  }
+  return {
+    source: 'visible-ui',
+    platform,
+    network: options.network,
+    ...(options.chainId ? { chainId: options.chainId } : {}),
+    selectedNetwork,
+    settleMs: options.settleMs,
+    stable: true,
+    before: before.assets,
+    after: after.assets,
+    priceApiError: false,
+  };
+}