@deeeed/metamask-harness 0.36.0 → 0.38.0

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,
+  };
+}

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

@@ -0,0 +1,354 @@
+const SURFACES = new Set([
+  'auto',
+  'home',
+  'market-list',
+  'market-details',
+  'order-entry',
+  'activity',
+  'funds',
+]);
+const FEATURES = new Set([
+  'activity',
+  'balance',
+  'chart',
+  'long-short',
+  'market-list',
+  'order-entry',
+  'price',
+  'price-change',
+  'stats',
+]);
+
+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.perps.read_visible_state ${name} must be an integer from ${minimum} to ${maximum}.`,
+    );
+  }
+  return resolved;
+}
+
+function stringList(value, name, maximum = 100) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`metamask.perps.read_visible_state ${name} must be an array.`);
+  }
+  const values = Array.from(new Set(value.map((entry) => String(entry).trim()).filter(Boolean)));
+  if (values.length > maximum) {
+    throw new Error(`metamask.perps.read_visible_state ${name} accepts at most ${maximum} values.`);
+  }
+  return values;
+}
+
+export function resolveVisibleStateOptions(node = {}) {
+  const surface = String(node.surface ?? 'auto').toLowerCase();
+  if (!SURFACES.has(surface)) {
+    throw new Error(
+      `metamask.perps.read_visible_state received unsupported surface ${JSON.stringify(surface)}.`,
+    );
+  }
+  const market = node.market == null ? undefined : String(node.market).trim().toUpperCase();
+  if (node.market != null && !market) {
+    throw new Error('metamask.perps.read_visible_state market must not be empty.');
+  }
+  return {
+    surface,
+    market,
+    includeOffscreen: node.include_offscreen !== false,
+    maxItems: boundedInteger(node.max_items, 100, 1, 200, 'max_items'),
+    minimumMarketCount: boundedInteger(
+      node.minimum_market_count,
+      0,
+      0,
+      200,
+      'minimum_market_count',
+    ),
+    maximumMarketCount: boundedInteger(
+      node.maximum_market_count,
+      200,
+      0,
+      200,
+      'maximum_market_count',
+    ),
+    requireTestIds: stringList(node.require_test_ids, 'require_test_ids'),
+    forbidTestIds: stringList(node.forbid_test_ids, 'forbid_test_ids'),
+    direction: node.direction == null ? undefined : String(node.direction).trim().toLowerCase(),
+    orderType: node.order_type == null ? undefined : String(node.order_type).trim().toLowerCase(),
+    amount: node.amount == null ? undefined : String(node.amount),
+    percent: node.percent == null ? undefined : String(node.percent),
+    leverage: node.leverage == null ? undefined : String(node.leverage),
+    autoClose: node.auto_close == null ? undefined : Boolean(node.auto_close),
+    submitEnabled: node.submit_enabled == null ? undefined : Boolean(node.submit_enabled),
+    requireValidationText: stringList(node.require_validation_text, 'require_validation_text', 20),
+    minimumPositionCount: boundedInteger(node.minimum_position_count, 0, 0, 200, 'minimum_position_count'),
+    maximumPositionCount: boundedInteger(node.maximum_position_count, 200, 0, 200, 'maximum_position_count'),
+    minimumOrderCount: boundedInteger(node.minimum_order_count, 0, 0, 200, 'minimum_order_count'),
+    maximumOrderCount: boundedInteger(node.maximum_order_count, 200, 0, 200, 'maximum_order_count'),
+    minimumActivityCount: boundedInteger(node.minimum_activity_count, 0, 0, 200, 'minimum_activity_count'),
+    requireNoHorizontalOverflow: node.require_no_horizontal_overflow === true,
+    requireFeatures: stringList(node.require_features, 'require_features').map((feature) => {
+      if (!FEATURES.has(feature)) {
+        throw new Error(
+          `metamask.perps.read_visible_state received unsupported feature ${JSON.stringify(feature)}.`,
+        );
+      }
+      return feature;
+    }),
+  };
+}
+
+function text(value) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\s+/gu, ' ').trim();
+  return normalized ? normalized.slice(0, 500) : undefined;
+}
+
+function equalNumericText(actual, expected) {
+  const left = String(actual ?? '').trim();
+  const right = String(expected ?? '').trim();
+  if (!left || !right) return left === right;
+  const leftNumber = Number(left);
+  const rightNumber = Number(right);
+  return Number.isFinite(leftNumber) && Number.isFinite(rightNumber)
+    ? leftNumber === rightNumber
+    : left === right;
+}
+
+function normalizedItem(source) {
+  const testId = text(source?.testId ?? source?.test_id ?? source?.identifier);
+  if (!testId) return undefined;
+  return {
+    testId,
+    ...(text(source?.label ?? source?.value) ? { label: text(source?.label ?? source?.value) } : {}),
+    ...(text(source?.role ?? source?.type) ? { role: text(source?.role ?? source?.type) } : {}),
+    enabled: source?.enabled !== false,
+    visible: source?.visible !== false,
+  };
+}
+
+function marketFromTestId(testId) {
+  if (testId.startsWith('market-row-ticker-')) return undefined;
+  for (const prefix of ['perps-watchlist-', 'explore-markets-', 'perps-market-row-item-', 'market-row-']) {
+    if (!testId.startsWith(prefix)) continue;
+    const raw = testId.slice(prefix.length);
+    if ((prefix === 'explore-markets-' || prefix === 'market-row-') && raw.startsWith('xyz-')) {
+      return `XYZ:${raw.slice(4).toUpperCase()}`;
+    }
+    return raw.toUpperCase();
+  }
+  return undefined;
+}
+
+function classifySurface(route, testIds) {
+  const joined = [...testIds].join('\n');
+  if (/\/perps\/trade\//u.test(route)) {
+    return 'order-entry';
+  }
+  if (/\/perps\/market\//u.test(route)) {
+    return 'market-details';
+  }
+  if (/perps-(?:order-entry|order-view|trade)/u.test(joined)) return 'order-entry';
+  if (/perps-(?:market-detail|market-details|pro-market)/u.test(joined)) return 'market-details';
+  if (/market-list-view|perps-market-list/u.test(joined)) return 'market-list';
+  if (/perps-(?:activity|transactions)/u.test(joined)) return 'activity';
+  if (/perps-(?:deposit|withdraw|add-funds)/u.test(joined)) return 'funds';
+  if (/perps-home/u.test(joined) || /perps-home|tab=perps/u.test(route)) return 'home';
+  return 'unknown';
+}
+
+function selected(items, predicate, maximum) {
+  return items.filter(predicate).slice(0, maximum);
+}
+
+function compactEntries(items, maximum) {
+  return selected(items, () => true, maximum).map((item) => ({
+    testId: item.testId,
+    ...(item.label ? { label: item.label } : {}),
+    enabled: item.enabled,
+    visible: item.visible,
+  }));
+}
+
+function visibleFeatures(items) {
+  const ids = new Set(items.map((item) => item.testId));
+  const has = (pattern) => [...ids].some((testId) => pattern.test(testId));
+  const long = has(/(?:long-cta-button|direction-long)$/u);
+  const short = has(/(?:short-cta-button|direction-short)$/u);
+  return {
+    activity: has(/^(?:transaction-card-|perps-(?:recent-activity|activity))/u),
+    balance: has(/^perps-balance-dropdown/u),
+    chart: has(/perps-(?:candlestick-chart|market-detail-chart|pro-market-chart)/u),
+    'long-short': long && short,
+    'market-list': has(/^(?:market-list-view|perps-market-list|perps-watchlist-|explore-markets-|market-row-)/u),
+    'order-entry': has(/perps-(?:order-entry|pro-order-form)/u),
+    price: has(/perps-(?:market-detail-price|pro-market-price)$/u),
+    'price-change': has(/perps-(?:market-detail-change|pro-market-price-change)$/u),
+    stats: has(/perps-(?:stats-section|market-detail-oracle-price|pro-market-stats)/u),
+  };
+}
+
+export function normalizeVisiblePerpsState(raw, options, platform) {
+  const items = [...(raw.items ?? []), ...(options.includeOffscreen ? raw.offscreenItems ?? [] : [])]
+    .map(normalizedItem)
+    .filter(Boolean);
+  const unique = Array.from(new Map(items.map((item) => [item.testId, item])).values());
+  const testIds = new Set(unique.map((item) => item.testId));
+  const route = text(raw.route) ?? '';
+  const surface = classifySurface(route, testIds);
+  const marketItems = selected(
+    unique,
+    (item) => Boolean(marketFromTestId(item.testId)),
+    options.maxItems,
+  ).map((item) => ({
+    market: marketFromTestId(item.testId),
+    testId: item.testId,
+    ...(item.label ? { label: item.label } : {}),
+    visible: item.visible,
+  }));
+  const state = {
+    source: 'visible-ui',
+    platform,
+    surface,
+    ...(route ? { route } : {}),
+    ...(text(raw.title) ? { title: text(raw.title) } : {}),
+    balance: compactEntries(
+      selected(unique, (item) => item.testId.startsWith('perps-balance-dropdown'), 1),
+      1,
+    )[0] ?? null,
+    markets: marketItems,
+    positions: compactEntries(
+      selected(unique, (item) => /^(?:position-card-|perps-position-row-|perps-position-size-value$|perps-pro-market-position-row-)/u.test(item.testId), options.maxItems),
+      options.maxItems,
+    ),
+    orders: compactEntries(
+      selected(unique, (item) => /^(?:order-card-|perps-order-row-)/u.test(item.testId), options.maxItems),
+      options.maxItems,
+    ),
+    activity: compactEntries(
+      selected(unique, (item) => /^(?:transaction-card-|perps-activity-row-)/u.test(item.testId), options.maxItems),
+      options.maxItems,
+    ),
+    orderEntry: raw.orderEntry && typeof raw.orderEntry === 'object' ? {
+      symbol: text(raw.orderEntry.symbol) ?? null,
+      direction: text(raw.orderEntry.direction) ?? null,
+      orderType: text(raw.orderEntry.orderType) ?? null,
+      amount: raw.orderEntry.amount == null ? null : String(raw.orderEntry.amount),
+      percent: raw.orderEntry.percent == null ? null : String(raw.orderEntry.percent),
+      leverage: raw.orderEntry.leverage == null ? null : String(raw.orderEntry.leverage),
+      autoClose: raw.orderEntry.autoClose === true,
+      takeProfitPrice: raw.orderEntry.takeProfitPrice == null ? null : String(raw.orderEntry.takeProfitPrice),
+      stopLossPrice: raw.orderEntry.stopLossPrice == null ? null : String(raw.orderEntry.stopLossPrice),
+      submit: raw.orderEntry.submit && typeof raw.orderEntry.submit === 'object' ? {
+        label: text(raw.orderEntry.submit.label) ?? null,
+        enabled: raw.orderEntry.submit.enabled !== false,
+      } : null,
+      limitPrice: raw.orderEntry.limitPrice == null ? null : String(raw.orderEntry.limitPrice),
+      validation: Array.isArray(raw.orderEntry.validation)
+        ? raw.orderEntry.validation.map(text).filter(Boolean).slice(0, 20)
+        : [],
+    } : null,
+    features: visibleFeatures(unique),
+    controls: compactEntries(
+      selected(
+        unique,
+        (item) => item.testId.startsWith('perps-') && !marketFromTestId(item.testId),
+        options.maxItems,
+      ),
+      options.maxItems,
+    ),
+    observedTestIds: Array.from(testIds).slice(0, options.maxItems),
+    truncated: raw.truncated === true || unique.length > options.maxItems,
+    layout: raw.layout && typeof raw.layout === 'object' ? {
+      viewportWidth: Number(raw.layout.viewportWidth ?? 0),
+      viewportHeight: Number(raw.layout.viewportHeight ?? 0),
+      contentWidth: Number(raw.layout.contentWidth ?? 0),
+      horizontalOverflow: raw.layout.horizontalOverflow === true,
+      clippedTestIds: Array.isArray(raw.layout.clippedTestIds)
+        ? raw.layout.clippedTestIds.map(text).filter(Boolean).slice(0, 100)
+        : [],
+    } : null,
+  };
+  assertVisibleState(state, options);
+  return state;
+}
+
+function assertVisibleState(state, options) {
+  if (options.requireNoHorizontalOverflow && (
+    !state.layout || state.layout.horizontalOverflow || state.layout.clippedTestIds.length > 0
+  )) {
+    throw new Error(`Visible Perps layout overflows horizontally: ${JSON.stringify(state.layout)}.`);
+  }
+  if (options.surface !== 'auto' && state.surface !== options.surface) {
+    throw new Error(
+      `Expected visible Perps surface ${options.surface}, but observed ${state.surface}.`,
+    );
+  }
+  if (state.markets.length < options.minimumMarketCount) {
+    throw new Error(
+      `Expected at least ${options.minimumMarketCount} visible Perps markets, but observed ${state.markets.length}.`,
+    );
+  }
+  if (state.markets.length > options.maximumMarketCount) {
+    throw new Error(
+      `Expected at most ${options.maximumMarketCount} visible Perps markets, but observed ${state.markets.length}.`,
+    );
+  }
+  if (state.positions.length < options.minimumPositionCount || state.positions.length > options.maximumPositionCount) {
+    throw new Error(`Expected ${options.minimumPositionCount}-${options.maximumPositionCount} visible Perps positions, but observed ${state.positions.length}.`);
+  }
+  if (state.orders.length < options.minimumOrderCount || state.orders.length > options.maximumOrderCount) {
+    throw new Error(`Expected ${options.minimumOrderCount}-${options.maximumOrderCount} visible Perps orders, but observed ${state.orders.length}.`);
+  }
+  if (state.activity.length < options.minimumActivityCount) {
+    throw new Error(`Expected at least ${options.minimumActivityCount} visible Perps activity entries, but observed ${state.activity.length}.`);
+  }
+  const observed = new Set(state.observedTestIds);
+  const missing = options.requireTestIds.filter((testId) => !observed.has(testId));
+  if (missing.length > 0) {
+    throw new Error(`Missing required visible Perps test IDs: ${missing.join(', ')}.`);
+  }
+  const forbidden = options.forbidTestIds.filter((testId) => observed.has(testId));
+  if (forbidden.length > 0) {
+    throw new Error(`Forbidden visible Perps test IDs were observed: ${forbidden.join(', ')}.`);
+  }
+  const missingFeatures = options.requireFeatures.filter((feature) => state.features[feature] !== true);
+  if (missingFeatures.length > 0) {
+    throw new Error(`Missing required visible Perps features: ${missingFeatures.join(', ')}.`);
+  }
+  if (options.market) {
+    const requested = options.market.replace(/^XYZ-/u, 'XYZ:');
+    const matched = state.markets.some((entry) => entry.market === requested) ||
+      [...state.controls, ...state.positions, ...state.orders, ...state.activity]
+        .some((entry) => String(entry.label ?? entry.testId).toUpperCase().includes(requested));
+    if (!matched) {
+      throw new Error(`Expected visible Perps market ${requested}, but it was not observed.`);
+    }
+  }
+  if (options.direction && state.orderEntry?.direction !== options.direction) {
+    throw new Error(`Expected Perps order direction ${options.direction}, but observed ${state.orderEntry?.direction ?? 'none'}.`);
+  }
+  if (options.orderType && state.orderEntry?.orderType !== options.orderType) {
+    throw new Error(`Expected Perps order type ${options.orderType}, but observed ${state.orderEntry?.orderType ?? 'none'}.`);
+  }
+  if (options.amount !== undefined && !equalNumericText(state.orderEntry?.amount, options.amount)) {
+    throw new Error(`Expected Perps order amount ${options.amount}, but observed ${state.orderEntry?.amount ?? 'none'}.`);
+  }
+  if (options.percent !== undefined && !equalNumericText(state.orderEntry?.percent, options.percent)) {
+    throw new Error(`Expected Perps order percent ${options.percent}, but observed ${state.orderEntry?.percent ?? 'none'}.`);
+  }
+  if (options.leverage !== undefined && !equalNumericText(state.orderEntry?.leverage, options.leverage)) {
+    throw new Error(`Expected Perps leverage ${options.leverage}, but observed ${state.orderEntry?.leverage ?? 'none'}.`);
+  }
+  if (options.autoClose !== undefined && state.orderEntry?.autoClose !== options.autoClose) {
+    throw new Error(`Expected Perps auto-close ${options.autoClose}, but observed ${state.orderEntry?.autoClose ?? 'none'}.`);
+  }
+  if (options.submitEnabled !== undefined && state.orderEntry?.submit?.enabled !== options.submitEnabled) {
+    throw new Error(`Expected Perps submit enabled ${options.submitEnabled}, but observed ${state.orderEntry?.submit?.enabled ?? 'none'}.`);
+  }
+  const validationText = state.orderEntry?.validation?.join(' ') ?? '';
+  const missingValidation = options.requireValidationText.filter((entry) => !validationText.includes(entry));
+  if (missingValidation.length > 0) {
+    throw new Error(`Missing required Perps validation text: ${missingValidation.join(', ')}.`);
+  }
+}

package/library/actions/shared/swap-bridge/transaction.mjs

@@ -0,0 +1,54 @@
+function requiredText(value, name) {
+  const resolved = String(value ?? '').trim();
+  if (!resolved) throw new Error(`metamask.swap_bridge ${name} is required.`);
+  return resolved;
+}
+
+function timeout(value) {
+  const resolved = Number(value ?? 60_000);
+  if (!Number.isInteger(resolved) || resolved < 1_000 || resolved > 180_000) {
+    throw new Error('metamask.swap_bridge timeout_ms must be an integer from 1000 to 180000.');
+  }
+  return resolved;
+}
+
+function plainDecimal(value) {
+  const text = String(value).trim();
+  const match = /^([+-]?)(\d+)(?:\.(\d*))?[eE]([+-]?\d+)$/u.exec(text);
+  if (!match) return text;
+  const [, sign, integer, fraction = '', exponentText] = match;
+  const digits = `${integer}${fraction}`;
+  const decimalIndex = integer.length + Number(exponentText);
+  if (decimalIndex <= 0) return `${sign}0.${'0'.repeat(-decimalIndex)}${digits}`;
+  if (decimalIndex >= digits.length) return `${sign}${digits}${'0'.repeat(decimalIndex - digits.length)}`;
+  return `${sign}${digits.slice(0, decimalIndex)}.${digits.slice(decimalIndex)}`;
+}
+
+export function resolveAssetSelectionOptions(node = {}) {
+  const sourceSymbol = requiredText(node.source_symbol, 'source_symbol').toUpperCase();
+  const destinationSymbol = requiredText(node.destination_symbol, 'destination_symbol').toUpperCase();
+  return {
+    sourceSymbol,
+    destinationSymbol,
+    sourceChain: requiredText(node.source_chain, 'source_chain'),
+    destinationChain: requiredText(node.destination_chain, 'destination_chain'),
+    sourceQuery: String(node.source_query ?? sourceSymbol).trim(),
+    destinationQuery: String(node.destination_query ?? destinationSymbol).trim(),
+    sourceAssetId: String(node.source_asset_id ?? '').trim() || undefined,
+    destinationAssetId: String(node.destination_asset_id ?? '').trim() || undefined,
+    timeoutMs: timeout(node.timeout_ms),
+  };
+}
+
+export function resolveAmountOptions(node = {}) {
+  const amount = plainDecimal(requiredText(node.amount, 'amount'));
+  const numeric = Number(amount);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    throw new Error('metamask.swap_bridge amount must be a positive number.');
+  }
+  return {
+    amount,
+    waitForQuote: node.wait_for_quote !== false,
+    timeoutMs: timeout(node.timeout_ms),
+  };
+}