@deeeed/metamask-harness 0.39.0 → 0.40.1

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.');
+}