@deeeed/metamask-harness 0.38.1 → 0.40.0

package/library/actions/extension/perps/select_market_filter.mjs

@@ -1,3 +1,5 @@
+import { pathToFileURL } from 'node:url';
+
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import {
   normalizeVisiblePerpsState,
@@ -16,7 +18,23 @@ const FILTERS = new Map([
   ['new', 'new'],
 ]);
 
-runAdapter(async (input) => withExtensionPage(input, async (page) => {
+async function visibleLabel(page, selector) {
+  return page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return { visible: false, label: '' };
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return {
+      visible: style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0,
+      label: String(element.getAttribute('aria-label') || element.innerText || element.getAttribute('value') || '')
+        .replace(/\\s+/gu, ' ')
+        .trim()
+        .slice(0, 500),
+    };
+  })()`);
+}
+
+export async function selectMarketFilter(page, input, pollOptions = {}) {
   const filter = String(input.node?.filter ?? '').trim().toLowerCase();
   const option = FILTERS.get(filter);
   if (!option) {
@@ -29,15 +47,35 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
     minimum_market_count: input.node?.minimum_market_count ?? 1,
     maximum_market_count: input.node?.maximum_market_count ?? 200,
   });
+  const timeoutMs = pollOptions.timeoutMs ?? input.node?.timeout_ms ?? 10_000;
+  const pollIntervalMs = pollOptions.pollIntervalMs ?? 100;
   await page.click(dataTestId('filter-select-button'));
   const optionSelector = dataTestId(`filter-select-option-${option}`);
   try {
-    await page.waitForSelector(optionSelector, { timeoutMs: 2_000 });
+    await page.waitForSelector(optionSelector, { timeoutMs: Math.min(timeoutMs, 2_000) });
   } catch {
     throw new Error(`Perps market filter ${JSON.stringify(filter)} is not available in this release.`);
   }
+  const optionState = await visibleLabel(page, optionSelector);
+  if (!optionState.visible || !optionState.label) {
+    throw new Error(`Perps market filter ${JSON.stringify(filter)} is not visibly available in this release.`);
+  }
   await page.click(optionSelector);
-  await new Promise((resolve) => setTimeout(resolve, 300));
+  const selectedSelector = dataTestId('filter-select-button');
+  const deadline = Date.now() + timeoutMs;
+  let selectedState;
+  while (true) {
+    selectedState = await visibleLabel(page, selectedSelector);
+    if (selectedState.visible && selectedState.label === optionState.label) break;
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Perps market filter ${JSON.stringify(filter)} did not select within ${timeoutMs}ms: ` +
+        `expected label ${JSON.stringify(optionState.label)}, observed ${JSON.stringify(selectedState.label)} ` +
+        `(visible=${selectedState.visible === true}).`,
+      );
+    }
+    await page.evaluate(`new Promise((resolve) => setTimeout(resolve, ${JSON.stringify(pollIntervalMs)}))`);
+  }
   const raw = await page.evaluate(`(() => {
     const maximum = ${JSON.stringify(options.maxItems)};
     const items = [];
@@ -66,7 +104,13 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
   return {
     action: input.action,
     filter,
+    option,
+    selectedLabel: selectedState.label,
     ...normalizeVisiblePerpsState(raw, options, 'extension'),
     proofPath: 'trusted-pointer-visible-ui',
   };
-}));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runAdapter((input) => withExtensionPage(input, (page) => selectMarketFilter(page, input)));
+}

package/library/actions/extension/perps/set_market_favorite.mjs

@@ -9,6 +9,7 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
     throw new Error('metamask.perps.set_market_favorite requires favorite=true or false.');
   }
   const desired = input.node.favorite;
+  const requireUnchanged = input.node?.require_unchanged === true;
   const selector = dataTestId('perps-market-detail-favorite-button');
   const readState = () => page.evaluate(`(() => {
     const market = ${JSON.stringify(market)};
@@ -35,11 +36,15 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
   if (after.favorite !== desired) {
     throw new Error(`Perps favorite state did not become ${desired}.`);
   }
+  const changed = before.favorite !== after.favorite;
+  if (requireUnchanged && changed) {
+    throw new Error(`Perps favorite state for ${market} did not persist across navigation.`);
+  }
   return {
     action: input.action,
     market,
     requestedFavorite: desired,
-    changed: before.favorite !== after.favorite,
+    changed,
     before,
     after,
     proofPath: 'trusted-pointer-visible-ui',

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

@@ -1,49 +1,131 @@
-import { dataTestId, marketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  assertTrustedExternalMutationTarget,
+  externalMutationNotDispatched,
+  readExternalMutationReceipt,
+  runGuardedExternalMutation,
+  trustedExternalMutationIdentity,
+  withExternalMutationRecovery,
+} from './mutation-receipt.mjs';
+import { requireCurrentVisibleFundingBalance, requirePerpsTradingContext } from './perps.mjs';
+import {
+  normalizePositionSizeIdentity,
+  parsePositionDetail,
+  parseUsdBaseUnits,
+  positionIdentityMatches,
+} from './visible-mutation-identity.mjs';
 
-function displayedPrice(value) {
-  const match = String(value).replace(/,/gu, '').match(/-?\d+(?:\.\d+)?/u);
-  return match ? Number(match[0]) : null;
+function marketSymbol(value) {
+  const market = String(value ?? '').trim().toUpperCase();
+  if (!/^[A-Z0-9:_-]{2,20}$/u.test(market)) {
+    throw new Error('metamask.perps.update_position_tpsl requires market=<symbol>.');
+  }
+  return market;
 }
 
-function matchesRequestedPrice(displayed, requested) {
-  const observed = displayedPrice(displayed);
-  const expected = Number(requested);
-  return observed !== null && Number.isFinite(observed)
-    && Math.abs(observed - expected) <= Math.max(0.005, Math.abs(expected) * 1e-10);
+function price(value, label) {
+  const text = String(value ?? '');
+  if (!/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(text)) {
+    throw new Error(`metamask.perps.update_position_tpsl requires a positive ${label}.`);
+  }
+  return text;
 }
 
-runAdapter(async (input) => withExtensionPage(input, async (page) => {
-  const market = marketSymbol(input);
-  const takeProfit = input.node?.take_profit_price;
-  const stopLoss = input.node?.stop_loss_price;
-  if (!market) throw new Error('metamask.perps.update_position_tpsl requires market=<symbol>.');
-  if (takeProfit == null && stopLoss == null) {
-    throw new Error('metamask.perps.update_position_tpsl requires take_profit_price and/or stop_loss_price.');
+async function readPosition(page, market) {
+  await page.navigateHash(`#/perps/market/${encodeURIComponent(market)}`);
+  await page.waitForSelector(dataTestId('perps-position-size-value'), { timeoutMs: 20_000 });
+  const raw = await page.evaluate(`(() => {
+    const read = (testId) => String(document.querySelector('[data-testid="' + testId + '"]')?.innerText || '')
+      .replace(/\\s+/gu, ' ')
+      .trim()
+      .slice(0, 500);
+    return {
+      route: String(location.hash),
+      pair: read('perps-market-detail-pair'),
+      direction: read('perps-position-leverage'),
+      size: read('perps-position-size-value'),
+      margin: read('perps-position-margin-value'),
+      liquidation: read('perps-position-liquidation-value'),
+      takeProfit: read('perps-auto-close-tp-value'),
+      stopLoss: read('perps-auto-close-sl-value'),
+    };
+  })()`);
+  const parsed = parsePositionDetail(raw);
+  if (!parsed || !raw.route.includes('/perps/market/') || !raw.pair.toUpperCase().startsWith(`${market}-`)) {
+    throw new Error('Visible Perps position identity is unavailable or does not match the requested market.');
   }
-  for (const [name, value] of [['take_profit_price', takeProfit], ['stop_loss_price', stopLoss]]) {
-    if (value != null && (!Number.isFinite(Number(value)) || Number(value) <= 0)) {
-      throw new Error(`metamask.perps.update_position_tpsl received invalid ${name}.`);
+  return { ...raw, ...parsed };
+}
+
+function exactPrices(state, takeProfit, stopLoss) {
+  return parseUsdBaseUnits(state.takeProfit) === parseUsdBaseUnits(takeProfit)
+    && parseUsdBaseUnits(state.stopLoss) === parseUsdBaseUnits(stopLoss);
+}
+
+async function waitForExactPrices(page, identity, facts, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let stable = null;
+  let stableSince = 0;
+  let after;
+  while (Date.now() <= deadline) {
+    after = await readPosition(page, identity.market);
+    const exact = exactPrices(after, facts.takeProfitPrice, facts.stopLossPrice)
+      && after.size === facts.positionBefore.size
+      && after.direction === facts.positionBefore.direction
+      && positionIdentityMatches(after, {
+        market: identity.market,
+        side: identity.side,
+        leverage: identity.leverage,
+        matchMargin: false,
+      });
+    if (exact) {
+      const key = JSON.stringify(after);
+      if (key !== stable) {
+        stable = key;
+        stableSince = Date.now();
+      } else if (Date.now() - stableSince >= 1_000) return after;
+    } else {
+      stable = null;
     }
+    await new Promise((resolve) => setTimeout(resolve, 250));
   }
-  if (input.node?.confirm_live !== true) {
-    throw new Error('metamask.perps.update_position_tpsl requires confirm_live=true for live submission.');
-  }
+  throw new Error(`exact TP/SL postcondition was not visible: ${JSON.stringify(after)}.`);
+}
 
-  await page.navigateHash(`#/perps/market/${encodeURIComponent(market)}`);
-  await page.waitForSelector(dataTestId('perps-auto-close-row'), { timeoutMs: 20_000 });
-  const before = await page.evaluate(`(() => ({
-    takeProfit: String(document.querySelector('[data-testid="perps-auto-close-tp-value"]')?.textContent || '').trim(),
-    stopLoss: String(document.querySelector('[data-testid="perps-auto-close-sl-value"]')?.textContent || '').trim(),
-  }))()`);
+async function observePersistedPrices(page, identity, facts, timeoutMs) {
+  const immediate = await waitForExactPrices(page, identity, facts, timeoutMs);
+  await page.session.call('Page.reload', { ignoreCache: true });
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  await page.waitForSelector(dataTestId('perps-position-size-value'), { timeoutMs: 20_000 });
+  const persisted = await waitForExactPrices(page, identity, facts, timeoutMs);
+  return {
+    success: true,
+    positionBefore: facts.positionBefore,
+    prefill: facts.prefill,
+    request: {
+      takeProfitPrice: facts.takeProfitPrice,
+      stopLossPrice: facts.stopLossPrice,
+    },
+    immediate,
+    persistedAfterReload: persisted,
+  };
+}
+
+async function prepareTpslModal(page, before, takeProfit, stopLoss) {
   await page.click(dataTestId('perps-auto-close-row'));
   await page.waitForSelector(dataTestId('perps-update-tpsl-modal'), { timeoutMs: 10_000 });
-  if (takeProfit != null) {
-    await page.setInput('input[data-testid="perps-update-tpsl-tp-price-input"], [data-testid="perps-update-tpsl-tp-price-input"] input', String(takeProfit));
-  }
-  if (stopLoss != null) {
-    await page.setInput('input[data-testid="perps-update-tpsl-sl-price-input"], [data-testid="perps-update-tpsl-sl-price-input"] input', String(stopLoss));
+  const prefill = await page.evaluate(`(() => ({
+    takeProfit: document.querySelector('input[data-testid="perps-update-tpsl-tp-price-input"], [data-testid="perps-update-tpsl-tp-price-input"] input')?.value ?? null,
+    stopLoss: document.querySelector('input[data-testid="perps-update-tpsl-sl-price-input"], [data-testid="perps-update-tpsl-sl-price-input"] input')?.value ?? null,
+  }))()`);
+  const beforeTakeProfit = parseUsdBaseUnits(before.takeProfit);
+  const beforeStopLoss = parseUsdBaseUnits(before.stopLoss);
+  if ((beforeTakeProfit != null && parseUsdBaseUnits(prefill.takeProfit) !== beforeTakeProfit)
+    || (beforeStopLoss != null && parseUsdBaseUnits(prefill.stopLoss) !== beforeStopLoss)) {
+    throw new Error('TP/SL modal did not prefill the existing visible values.');
   }
-
+  await page.setInput('input[data-testid="perps-update-tpsl-tp-price-input"], [data-testid="perps-update-tpsl-tp-price-input"] input', takeProfit);
+  await page.setInput('input[data-testid="perps-update-tpsl-sl-price-input"], [data-testid="perps-update-tpsl-sl-price-input"] input', stopLoss);
   const readyDeadline = Date.now() + 10_000;
   let ready;
   while (Date.now() <= readyDeadline) {
@@ -54,53 +136,153 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
         takeProfit: value('perps-update-tpsl-tp-price-input'),
         stopLoss: value('perps-update-tpsl-sl-price-input'),
         submitEnabled: Boolean(submit && !submit.disabled && submit.getAttribute('aria-disabled') !== 'true'),
-        entry: String(document.querySelector('[data-testid="perps-update-tpsl-entry-price-value"]')?.textContent || '').trim(),
-        current: String(document.querySelector('[data-testid="perps-update-tpsl-current-price-value"]')?.textContent || '').trim(),
-        liquidation: String(document.querySelector('[data-testid="perps-update-tpsl-liquidation-price-value"]')?.textContent || '').trim(),
-        errors: [...document.querySelectorAll('[role="alert"]')]
-          .map((element) => String(element.innerText || '').replace(/\\s+/gu, ' ').trim())
-          .filter(Boolean)
-          .slice(0, 20),
       };
     })()`);
-    const retained = (takeProfit == null || Number(ready.takeProfit) === Number(takeProfit)) &&
-      (stopLoss == null || Number(ready.stopLoss) === Number(stopLoss));
-    if (retained && ready.submitEnabled) break;
+    if (Number(ready.takeProfit) === Number(takeProfit)
+      && Number(ready.stopLoss) === Number(stopLoss) && ready.submitEnabled) break;
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
-  if (!ready?.submitEnabled || ready.errors.length > 0) {
+  if (!ready?.submitEnabled || Number(ready.takeProfit) !== Number(takeProfit)
+    || Number(ready.stopLoss) !== Number(stopLoss)) {
     throw new Error(`Perps TP/SL update is not ready: ${JSON.stringify(ready)}.`);
   }
-  await page.click(dataTestId('perps-update-tpsl-modal-submit'));
+  return { prefill, ready };
+}
 
-  const resultDeadline = Date.now() + Number(input.node?.timeout_ms ?? 30_000);
-  const reconciled = (state) =>
-    (takeProfit == null || matchesRequestedPrice(state.takeProfit, takeProfit)) &&
-    (stopLoss == null || matchesRequestedPrice(state.stopLoss, stopLoss));
-  let after;
-  while (Date.now() <= resultDeadline) {
-    after = await page.evaluate(`(() => ({
-      modalVisible: Boolean(document.querySelector('[data-testid="perps-update-tpsl-modal"]')),
-      takeProfit: String(document.querySelector('[data-testid="perps-auto-close-tp-value"]')?.textContent || '').trim(),
-      stopLoss: String(document.querySelector('[data-testid="perps-auto-close-sl-value"]')?.textContent || '').trim(),
-      errors: [...document.querySelectorAll('[role="alert"]')]
-        .map((element) => String(element.innerText || '').replace(/\\s+/gu, ' ').trim())
-        .filter(Boolean)
-        .slice(0, 20),
-    }))()`);
-    if (!after.modalVisible && reconciled(after)) break;
-    if (after.errors.length > 0) throw new Error(`Perps TP/SL update failed: ${after.errors.join(' | ')}`);
-    await new Promise((resolve) => setTimeout(resolve, 200));
+export async function updatePositionTpsl(input) {
+  return withExtensionPage(input, async (page) => {
+  const market = marketSymbol(input.node?.market);
+  const takeProfit = price(input.node?.take_profit_price, 'take_profit_price');
+  const stopLoss = price(input.node?.stop_loss_price, 'stop_loss_price');
+  const fundingSide = String(input.node?.funding_side ?? '').trim().toLowerCase();
+  const fundingAmount = String(input.node?.funding_amount ?? '');
+  const fundingAmountBaseUnits = parseUsdBaseUnits(fundingAmount);
+  const fundingPositionSize = normalizePositionSizeIdentity(input.node?.funding_position_size);
+  const leverage = Number(input.node?.leverage);
+  if (!/^(?:long|short)$/u.test(fundingSide)
+    || !/^[1-9][0-9]{0,29}$/u.test(String(fundingAmountBaseUnits ?? ''))
+    || fundingPositionSize == null
+    || !Number.isInteger(leverage) || leverage < 1 || leverage > 100) {
+    throw new Error('metamask.perps.update_position_tpsl received invalid funded position inputs.');
   }
-  if (!after || after.modalVisible || !reconciled(after)) {
-    throw new Error(`Perps TP/SL did not reconcile after submission: ${JSON.stringify({ before, after })}.`);
+  if (input.node?.confirm_live !== true) {
+    throw new Error('metamask.perps.update_position_tpsl requires confirm_live=true for live submission.');
   }
+  const identity = trustedExternalMutationIdentity(input, page, {
+    operation: 'perps-tpsl-update',
+    provider: input.node?.provider,
+    network: input.node?.network,
+    market,
+    side: fundingSide,
+    amount: fundingAmount,
+    leverage,
+    orderType: 'tpsl',
+    positionMode: 'modify',
+    takeProfitPrice: takeProfit,
+    stopLossPrice: stopLoss,
+    positionAmountBaseUnits: fundingAmountBaseUnits,
+    positionSize: fundingPositionSize,
+    roundingToleranceBaseUnits: '0',
+  });
+  const existingReceipt = await readExternalMutationReceipt(input, identity);
+  if (existingReceipt) {
+    return withExternalMutationRecovery(existingReceipt, async () => {
+      const mutation = await runGuardedExternalMutation({
+        input,
+        identity,
+        dispatch: async () => { throw new Error('resumed TP/SL mutation must not dispatch'); },
+        observe: async ({ receipt }) => observePersistedPrices(
+          page,
+          identity,
+          receipt.facts,
+          Number(input.node?.timeout_ms ?? 45_000),
+        ),
+      });
+      return {
+        action: input.action,
+        market,
+        receipt: mutation.receipt,
+        resumed: true,
+        outcome: mutation.observation,
+        proofPath: 'trusted-pointer-visible-ui',
+      };
+    });
+  }
+
+  const timeoutMs = Number(input.node?.timeout_ms ?? 45_000);
+  const fundingBalance = await requireCurrentVisibleFundingBalance(input, page, timeoutMs);
+  const tradingContext = await requirePerpsTradingContext(input, page);
+  const before = await readPosition(page, market);
+  if (!positionIdentityMatches(before, { market, side: fundingSide, leverage, matchMargin: false })
+    || normalizePositionSizeIdentity(before.size) !== fundingPositionSize) {
+    throw new Error('Visible Perps position does not match the funded market/side/leverage/size identity.');
+  }
+  const { prefill, ready } = await prepareTpslModal(page, before, takeProfit, stopLoss);
+  const facts = {
+    positionBefore: before,
+    prefill,
+    takeProfitPrice: takeProfit,
+    stopLossPrice: stopLoss,
+    fundingBalance,
+    tradingContext,
+  };
+  const mutation = await runGuardedExternalMutation({
+    input,
+    identity,
+    publicationFacts: facts,
+    dispatch: async () => {
+      let dispatchTarget;
+      try {
+        await requireCurrentVisibleFundingBalance(input, page, timeoutMs, fundingBalance.observedBaseUnits);
+        await requirePerpsTradingContext(input, page);
+        assertTrustedExternalMutationTarget(input, page, identity);
+        const current = await readPosition(page, market);
+        if (current.size !== before.size || current.direction !== before.direction
+          || normalizePositionSizeIdentity(current.size) !== fundingPositionSize
+          || !positionIdentityMatches(current, { market, side: fundingSide, leverage, matchMargin: false })) {
+          throw new Error('Visible Perps position changed before TP/SL dispatch.');
+        }
+        await prepareTpslModal(page, current, takeProfit, stopLoss);
+        dispatchTarget = await page.evaluate(`(() => {
+          const element = document.querySelector('[data-testid="perps-update-tpsl-modal-submit"]');
+          if (!element || element.disabled || element.getAttribute('aria-disabled') === 'true') {
+            throw new Error('Visible Perps TP/SL submit control is unavailable.');
+          }
+          const rect = element.getBoundingClientRect();
+          return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+        })()`);
+        assertTrustedExternalMutationTarget(input, page, identity);
+      } catch (error) {
+        throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
+      }
+      await page.session.call('Input.dispatchMouseEvent', {
+        type: 'mousePressed', x: dispatchTarget.x, y: dispatchTarget.y,
+        button: 'left', buttons: 1, clickCount: 1,
+      });
+      await page.session.call('Input.dispatchMouseEvent', {
+        type: 'mouseReleased', x: dispatchTarget.x, y: dispatchTarget.y,
+        button: 'left', buttons: 0, clickCount: 1,
+      });
+    },
+    observe: async ({ receipt }) => observePersistedPrices(
+      page,
+      identity,
+      receipt.facts,
+      Number(input.node?.timeout_ms ?? 45_000),
+    ),
+  });
   return {
     action: input.action,
     market,
     before,
+    prefill,
     ready,
-    after,
-    proofPath: 'visible-product-controls',
+    receipt: mutation.receipt,
+    resumed: mutation.resumed,
+    outcome: mutation.observation,
+    proofPath: 'trusted-pointer-visible-ui',
   };
-}));
+  });
+}
+
+runAdapter(updatePositionTpsl);

package/library/actions/extension/perps/visible-mutation-identity.mjs

@@ -0,0 +1,164 @@
+const INTEGER = /^(0|[1-9][0-9]{0,29})$/u;
+
+export function parseUsdBaseUnits(value) {
+  const normalized = String(value ?? '').replace(/[,$\s]/gu, '');
+  const match = /^([+-]?)(\d+)(?:\.(\d{1,6}))?$/u.exec(normalized);
+  if (!match) return null;
+  const magnitude = BigInt(`${match[2]}${String(match[3] ?? '').padEnd(6, '0')}`);
+  return `${match[1] === '-' ? -magnitude : magnitude}`;
+}
+
+export function parsePositiveBaseUnits(value, label = 'base units') {
+  const text = String(value ?? '');
+  if (!INTEGER.test(text) || text === '0') throw new Error(`${label} must be a positive integer string.`);
+  return text;
+}
+
+export function absoluteDelta(left, right) {
+  const delta = BigInt(left) - BigInt(right);
+  return `${delta < 0n ? -delta : delta}`;
+}
+
+export function withinBaseUnitTolerance(actual, expected, tolerance) {
+  if (![actual, expected, tolerance].every((value) => /^-?\d+$/u.test(String(value)))) return false;
+  return BigInt(absoluteDelta(actual, expected)) <= BigInt(tolerance);
+}
+
+export function normalizedNumericInputMatches(observed, requested) {
+  const value = String(observed ?? '');
+  const expected = String(requested ?? '');
+  return /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/u.test(value)
+    && /^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(expected)
+    && Number(value) === Number(expected);
+}
+
+export function normalizePositionSizeIdentity(value) {
+  const match = /^([0-9][0-9,]*)(?:\.([0-9]+))?\s+([A-Z0-9:_-]{2,20})$/u.exec(
+    String(value ?? '').trim().toUpperCase(),
+  );
+  if (!match) return null;
+  const whole = match[1].replace(/,/gu, '').replace(/^0+(?=\d)/u, '');
+  const fraction = String(match[2] ?? '').replace(/0+$/u, '');
+  if (!/[1-9]/u.test(`${whole}${fraction}`)) return null;
+  return `${whole}${fraction ? `.${fraction}` : ''} ${match[3]}`;
+}
+
+export function positionIdentityMatches(observed, expected) {
+  const identityMatches = Boolean(observed)
+    && String(observed.market).toUpperCase() === String(expected.market).toUpperCase()
+    && String(observed.side).toLowerCase() === String(expected.side).toLowerCase()
+    && Number(observed.leverage) === Number(expected.leverage);
+  if (!identityMatches) return false;
+  if (expected.matchMargin === false) {
+    const size = /^([0-9][0-9,]*)(?:\.([0-9]+))?(?:\s|$)/u.exec(String(observed.size ?? '').trim());
+    return /^\d+$/u.test(String(observed.marginBaseUnits))
+      && BigInt(observed.marginBaseUnits) > 0n
+      && Boolean(size && /[1-9]/u.test(`${size[1]}${size[2] ?? ''}`));
+  }
+  return withinBaseUnitTolerance(
+      observed.marginBaseUnits,
+      expected.amountBaseUnits,
+      expected.roundingToleranceBaseUnits,
+  );
+}
+
+export function orderIdentityMatches(observed, expected) {
+  return Boolean(observed)
+    && String(observed.market).toUpperCase() === String(expected.market).toUpperCase()
+    && String(observed.side).toLowerCase() === String(expected.side).toLowerCase()
+    && String(observed.orderType).toLowerCase() === String(expected.orderType).toLowerCase()
+    && withinBaseUnitTolerance(
+      observed.notionalBaseUnits,
+      expected.notionalBaseUnits,
+      expected.roundingToleranceBaseUnits,
+    )
+    && withinBaseUnitTolerance(
+      observed.limitPriceBaseUnits,
+      expected.limitPriceBaseUnits,
+      expected.roundingToleranceBaseUnits,
+    );
+}
+
+export function parsePositionDetail(raw) {
+  const pair = String(raw?.pair ?? '').trim().toUpperCase();
+  const direction = /\b(long|short)\s+(\d+(?:\.\d+)?)x\b/iu.exec(String(raw?.direction ?? ''));
+  const marginBaseUnits = parseUsdBaseUnits(raw?.margin);
+  if (!pair || !direction || marginBaseUnits == null) return null;
+  return {
+    market: pair.split(/[-/\s]/u)[0],
+    side: direction[1].toLowerCase(),
+    leverage: Number(direction[2]),
+    marginBaseUnits,
+    size: String(raw?.size ?? '').trim().slice(0, 128),
+  };
+}
+
+export function parseOrderCard(raw, market) {
+  const text = String(raw?.text ?? '').replace(/\s+/gu, ' ').trim();
+  const label = /\b(market|limit)\s+(long|short)\b/iu.exec(text);
+  const price = [...text.matchAll(/\$\s*([0-9][0-9,]*(?:\.[0-9]{1,6})?)/gu)].at(-1)?.[0];
+  const size = /([0-9]+(?:\.[0-9]+)?)\s+([A-Z0-9:_-]{2,20})\b/u.exec(text);
+  const limitPriceBaseUnits = parseUsdBaseUnits(price);
+  if (!label || !size || limitPriceBaseUnits == null) return null;
+  const notional = Number(size[1]) * Number(limitPriceBaseUnits) / 1_000_000;
+  if (!Number.isFinite(notional) || notional <= 0) return null;
+  return {
+    id: String(raw?.id ?? ''),
+    market: String(market ?? size[2]).toUpperCase(),
+    side: label[2].toLowerCase(),
+    orderType: label[1].toLowerCase(),
+    size: size[1],
+    limitPriceBaseUnits,
+    notionalBaseUnits: `${Math.round(notional * 1_000_000)}`,
+  };
+}
+
+export async function waitForStableGlobalPerpsHome(page, options = {}) {
+  const timeoutMs = Number(options.timeoutMs ?? 20_000);
+  const stableMs = Number(options.stableMs ?? 1_000);
+  const requireZero = options.requireZero !== false;
+  const deadline = Date.now() + timeoutMs;
+  let stableSince = null;
+  let last = null;
+  while (Date.now() <= deadline) {
+    last = await page.evaluate(`(() => {
+      const visible = (element) => {
+        if (!element) return false;
+        const rect = element.getBoundingClientRect();
+        const style = getComputedStyle(element);
+        return rect.width > 0 && rect.height > 0 && style.display !== 'none' && style.visibility !== 'hidden';
+      };
+      const visibleCount = (selector) => [...document.querySelectorAll(selector)].filter(visible).length;
+      const balance = document.querySelector('[data-testid="perps-balance-dropdown-balance"]');
+      return {
+        route: String(location.hash),
+        viewVisible: visible(document.querySelector('[data-testid="perps-view"]')),
+        loading: visibleCount('[data-testid$="-skeleton"], [data-testid*="loading"]') > 0,
+        marketCount: visibleCount('[data-testid="perps-explore-markets-row"]'),
+        positionCount: visibleCount('[data-testid^="position-card-"]:not([data-testid^="position-card-roe-"])'),
+        orderCount: visibleCount('[data-testid^="order-card-"]'),
+        balance: visible(balance) ? String(balance.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 200) : null,
+      };
+    })()`);
+    const loaded = last.route.includes('/perps-home') && last.viewVisible && !last.loading
+      && last.marketCount > 0 && typeof last.balance === 'string' && last.balance.length > 0;
+    const clean = last.positionCount === 0 && last.orderCount === 0;
+    if (loaded && (!requireZero || clean)) {
+      stableSince ??= Date.now();
+      if (Date.now() - stableSince >= stableMs) {
+        const balanceBaseUnits = parseUsdBaseUnits(
+          String(last.balance).match(/\$\s*[0-9][0-9,]*(?:\.[0-9]{1,6})?/u)?.[0],
+        );
+        if (balanceBaseUnits == null) throw new Error('Visible Perps balance could not be parsed.');
+        return { ...last, balanceBaseUnits };
+      }
+    } else {
+      stableSince = null;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  if (requireZero && last && (last.positionCount !== 0 || last.orderCount !== 0)) {
+    throw new Error('Loaded Perps Home must have globally zero positions and orders before external mutation or cleanup.');
+  }
+  throw new Error('Loaded skeleton-free Perps Home did not become stable before timeout.');
+}