@deeeed/metamask-harness 0.92.39 → 0.94.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 0.94.0 - 2026-10-22
+
+### Added
+
+- Core `metamask.perps.place_order`, `ensure_positions` and `ensure_orders` take `margin_mode` (`isolated` or `cross`) with the same contract as Mobile: the controller order carries it, and the action proves the opened position's mode or, for a resting order, the venue lock (`getMarginModeLock`). It refuses a resting order before dispatch when the lock can't be read, and refuses anything but isolated on mainnet. `ensure_orders` proves reused orders per market and lists them in `marginModeLocks`; `margin_mode` applies only to `state=open`.
+- Mobile and Core `metamask.perps.start_state` pass `margin_mode` through their `positions` and `orders` objects to the `ensure_*` step that creates the state.
+- Mobile and Core positions report `side` from their signed size, and Core positions also report `marginMode`, like Mobile.
+- On Android, an unlabeled test-ID container (for example a list row whose copy sits on child text views) reports its visible descendants' text as `descendant_text` (up to 500 characters), and `ui.locators` `byTestId` includes it in `description`.
+- Mobile `ui.locators` takes `expect_enabled`, a map of requested test IDs to `true` or `false`, and re-reads until they reach that state or `timeout_ms` passes. The Pro margin chooser keeps Cross disabled until its venue lock read answers, so a single read can see a transient state. The last read is returned either way.
+
+### Changed
+
+- The margin-mode request parsing and venue proofs live in one shared module (`library/actions/shared/perps/margin-mode.mjs`) used by Mobile and Core.
+- Extension order actions don't take `margin_mode`: the Extension product has no Cross margin control to drive yet.
+
+### Fixed
+
+- Mobile `place_order` with `margin_mode` retries the account-guarded position read on a transient client error instead of failing right after a fill. An account or network change is still never retried. A failed lock check now says the order may still be resting, since the order may have filled or been rejected. The lock mode is compared case-insensitively, and the returned top-level `marginMode` is lowercase like position reads; the `marginModeLock` objects keep the venue's value.
+- Mobile `ui.locators` `test_ids` returns after one read when given no finite deadline instead of polling forever, and its description says to prove presence from `byTestId`.
+- Mobile `ensure_orders` `margin_mode` documents `marginModeLocks`, one lock per selected market.
+- Mobile Perps reads (positions, open orders, margin lock) retry a bridge read the app left unanswered (`CDP_TIMEOUT`, a busy JS thread) until their deadline, as they already did for `CLIENT_NOT_INITIALIZED`. A lost target or closed socket, as after a reload, still fails. Before, one busy moment right after a signed order failed `assert_positions` although the position opened.
+- Mobile `start_state` with `page=false` keeps the current route even when `market` or `symbol` scopes the trading state. Before, it navigated to a `false` target before cleaning, so a cleanup could fail on navigation and leave the position open.
+
+## 0.93.0 - 2026-10-21
+
+### Added
+
+- Mobile `metamask.perps.place_order`, `ensure_positions` and `ensure_orders` take `margin_mode` (`isolated` or `cross`). The order carries it to `PerpsController.placeOrder`. The action then proves the venue holds that mode: the opened position's mode for a market order, or `getMarginModeLock` for a resting order. It fails when they differ or when no position appears. A resting order is refused before dispatch when the venue lock cannot be read, and a failed lock check names the order left resting. `ensure_orders` proves each reused order on its own market. `ensure_positions` refuses to reuse an open position in another mode, since the venue cannot change it while open. `margin_mode` applies only to `state=open`. The mainnet house limits refuse any mode but `isolated`. Omitted keeps the venue default (the open position's mode, else isolated). Extension and Core order actions do not take `margin_mode` yet.
+- Mobile `metamask.perps.read_positions` (and every position the Perps actions report) includes `marginMode`, so recipes can assert a position's collateral mode as state.
+- Mobile `ui.locators` takes `test_ids` and returns `byTestId` (each element's role, enabled state, `null` when unreported, and description), `missingTestIds` and `unobservedTestIds`. A recipe can assert a control's state by test ID instead of scanning the ranked list. It covers disabled and non-interactive elements, which the ranked list drops as press targets. With `test_ids` it re-reads the accessibility tree until each ID is present or `timeout_ms` (default 5000, capped by the action deadline) passes, because the native tree can trail the React tree while a sheet animates in. A truncated observation reports its gaps as `unobservedTestIds`, since it cannot prove absence. The Extension observation keeps only interactive elements, so Extension `ui.locators` does not take `test_ids`.
+
 ## 0.92.39 - 2026-10-20
 
 ### Added

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

@@ -7,6 +7,7 @@ import { pathToFileURL } from 'node:url';
 
 import { walletFixturePath } from '../../harness-exports.mjs';
 import { normalizeSide, sideForItem } from '../../shared/perps/item-side.mjs';
+import { marginModeOf } from '../../shared/perps/margin-mode.mjs';
 import { readFixtureAccounts } from '../../shared/wallet/fixture-accounts.mjs';
 import { createRewardsClient, rewardsApiUrl } from './_rewards.mjs';
 
@@ -655,8 +656,9 @@ export function redactPosition(position) {
   return {
     coin: position.coin ?? position.symbol ?? null,
     size: position.size ?? position.szi ?? null,
-    side: position.side ?? null,
+    side: sideForItem(position, 'position') || normalizeSide(position.side) || null,
     entryPrice: position.entryPrice ?? position.entryPx ?? null,
+    marginMode: marginModeOf(position),
   };
 }
 

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

@@ -1,10 +1,11 @@
 // Converge selected testnet orders to open or absent state, then assert the result.
 // Reuse an existing matching order instead of placing another.
 
-import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
+import { getCoreController, getCoreControllerWithSigner, isDirectRun, requireExplicitSelection, runAdapter, selectedItems } from './_controller.mjs';
 import { assertOrders } from './assert_orders.mjs';
 import { closeOrders } from './close_orders.mjs';
 import { placeOrder } from './place_order.mjs';
+import { refuseMarginModeForAbsentState, requireLockMarginMode, resolveMarginMode } from '../../shared/perps/margin-mode.mjs';
 
 export async function ensureOrders(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.ensure_orders requires state=open or state=none.');
@@ -12,6 +13,7 @@ export async function ensureOrders(input) {
   const state = String(input.node.state).toLowerCase();
 
   if (state === 'none' || state === 'closed' || state === 'absent') {
+    refuseMarginModeForAbsentState(input.node, input.action);
     const close = await closeOrders(input);
     const assertion = await assertOrders(input, false);
     return { ...assertion, ensured: 'none', close };
@@ -28,11 +30,25 @@ export async function ensureOrders(input) {
       userAddress: accountAddress,
     });
     let order = null;
-    if (selectedItems(input, orders).length === 0) {
+    const reused = selectedItems(input, orders);
+    if (reused.length === 0) {
       order = await placeOrder({ ...input, node: { ...input.node, order_type: 'limit' } });
     }
     const assertion = await assertOrders(input, true);
-    return { ...assertion, ensured: 'open', order };
+    const marginMode = resolveMarginMode(input.node, input.action);
+    if (!marginMode) return { ...assertion, ensured: 'open', order };
+    // A placed order was already proved inside placeOrder; reused orders are proved per market.
+    const locks = {};
+    if (order) {
+      locks[order.market] = order.marginModeLock;
+    } else {
+      // The lock is read for the controller's own account, which only the signer setup binds.
+      const { controller: signed } = await getCoreControllerWithSigner(input);
+      for (const symbol of [...new Set(reused.map((item) => item.coin ?? item.symbol))]) {
+        locks[symbol] = requireLockMarginMode(input.action, symbol, await signed.getMarginModeLock({ symbol }), marginMode);
+      }
+    }
+    return { ...assertion, ensured: 'open', order, marginModeLock: Object.values(locks)[0], marginModeLocks: locks };
   }
 
   throw new Error(`metamask.perps.ensure_orders received unsupported state: ${state}`);

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

@@ -5,6 +5,7 @@ import { getCoreController, isDirectRun, requireExplicitSelection, runAdapter, s
 import { assertPositions } from './assert_positions.mjs';
 import { closePositions } from './close_positions.mjs';
 import { placeOrder } from './place_order.mjs';
+import { refuseMarginModeForAbsentState, requirePositionMarginMode, resolveMarginMode } from '../../shared/perps/margin-mode.mjs';
 
 export async function ensurePositions(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.ensure_positions requires state=open or state=none.');
@@ -12,6 +13,7 @@ export async function ensurePositions(input) {
   const state = String(input.node.state).toLowerCase();
 
   if (state === 'none' || state === 'closed' || state === 'absent') {
+    refuseMarginModeForAbsentState(input.node, input.action);
     const close = await closePositions(input);
     const assertion = await assertPositions(input, false);
     return { ...assertion, ensured: 'none', close };
@@ -25,7 +27,11 @@ export async function ensurePositions(input) {
       userAddress: accountAddress,
     });
     let order = null;
-    if (selectedItems(input, positions, 'position').length === 0) {
+    const existing = selectedItems(input, positions, 'position');
+    const marginMode = resolveMarginMode(input.node, input.action);
+    // The venue cannot change an open position's mode, so a reused one must already hold it.
+    if (existing.length > 0 && marginMode) requirePositionMarginMode(input.action, existing, marginMode);
+    if (existing.length === 0) {
       order = await placeOrder(input);
     }
     const assertion = await assertPositions(input, true);

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

@@ -16,6 +16,12 @@ import {
   symbolForItem,
 } from './_controller.mjs';
 import { waitForPositionsAbsent } from './close_positions.mjs';
+import {
+  requireLockMarginMode,
+  requireLockReadable,
+  requirePositionMarginMode,
+  resolveMarginMode,
+} from '../../shared/perps/margin-mode.mjs';
 import {
   assertFlatBeforeRoundTrip,
   assertHouseLimitPosition,
@@ -376,6 +382,7 @@ export async function placeOrder(input) {
   }
   const isBuy = side === 'long';
   const orderType = resolveOrderType(input);
+  const marginMode = resolveMarginMode(input.node, input.action);
   const leverage = Number(optionalParam(input.node ?? {}, 'leverage') ?? 3);
   const maxSlippageBps = Number(
     optionalParam(
@@ -437,6 +444,7 @@ export async function placeOrder(input) {
     leverage,
     orderType,
     closeImmediately,
+    marginMode,
     projectRoot: input.context?.projectRoot,
     selectedAddress: signerAddress,
   });
@@ -489,6 +497,7 @@ export async function placeOrder(input) {
   const strayTimeInForce =
     orderType === 'limit' ? undefined : requestedTimeInForce;
   const forwardedFields = {
+    ...(marginMode ? { marginMode } : {}),
     ...(strayTriggerPrice === undefined
       ? {}
       : { triggerPrice: strayTriggerPrice }),
@@ -566,6 +575,11 @@ export async function placeOrder(input) {
   // close_immediately started from a flat market (checked above), so a position
   // in it after a failed placement is this order's: close it rather than leave it open.
   const restsOnBook = orderType === 'limit' || isTriggerOrderType(orderType);
+  if (marginMode && restsOnBook) {
+    requireLockReadable(input.action, symbol, await controller.getMarginModeLock({ symbol }));
+  }
+  let marginModeLock;
+  let observedMarginMode;
   const placeAndVerify = async () => {
     const result = await controller.placeOrder(orderParams);
     if (!result || result.success !== true) {
@@ -614,6 +628,13 @@ export async function placeOrder(input) {
         `core placeOrder (market) for ${symbol} reported success but no matching position is visible (orderId=${result.orderId ?? 'null'}).`,
       );
     }
+    if (marginMode && restsOnBook) {
+      const resting = ` The ${symbol} order it placed (${result.orderId ?? 'unknown id'}) may still be resting; cancel it with ensure_orders state=none.`;
+      marginModeLock = requireLockMarginMode(input.action, symbol, await controller.getMarginModeLock({ symbol }), marginMode, resting);
+      observedMarginMode = String(marginModeLock.marginMode).toLowerCase();
+    } else if (marginMode) {
+      observedMarginMode = requirePositionMarginMode(input.action, matchingPositions, marginMode);
+    }
     return { result, matchingOrders, matchingPositions };
   };
   let placed;
@@ -649,6 +670,8 @@ export async function placeOrder(input) {
     orderType,
     notional: usdAmount,
     leverage,
+    ...(observedMarginMode ? { marginMode: observedMarginMode } : {}),
+    ...(marginModeLock ? { marginModeLock } : {}),
     timeInForce,
     size: orderParams.size,
     currentPrice,

package/library/actions/mobile/perps/perps.mjs

@@ -1,8 +1,17 @@
 // Implement Mobile Perps navigation, trading mutations, assertions, and setup or cleanup through the bridge.
 // Strategy getters used during cleanup can settle tracked collateral.
-import { sideForItem } from '../../shared/perps/item-side.mjs';
+import { normalizeSide, sideForItem } from '../../shared/perps/item-side.mjs';
+import {
+  marginModeOf,
+  refuseMarginModeForAbsentState,
+  requireLockMarginMode,
+  requireLockReadable,
+  requirePositionMarginMode,
+  resolveMarginMode,
+} from '../../shared/perps/margin-mode.mjs';
 import { pathToFileURL } from 'node:url';
 import {
+  MOBILE_BRIDGE_ERROR_CODES,
   MOBILE_BRIDGE_RESULT_ERROR_CODES,
   bridgeCommand,
   createSetupBudget,
@@ -251,8 +260,10 @@ export async function ensureMode(input) {
   throw new Error(`Perps did not reach ${requestedMode} mode before timeout.`);
 }
 
-// Retries the client-not-initialized race until the deadline, and a 429 with
-// the shared rate-limit backoff.
+// Retries the client-not-initialized race and a CDP_TIMEOUT (the app's JS
+// thread busy, e.g. signing on a dev build) until the deadline, and a 429 with
+// the shared rate-limit backoff. Only reads are wrapped, so a retry cannot
+// repeat a write. A lost target or closed socket (a reload) still throws.
 export async function retryPerpsClientRead(
   read,
   {
@@ -274,7 +285,8 @@ export async function retryPerpsClientRead(
     try {
       return await withRateLimitRetry(call, read, { deadline, sleep: wait, random });
     } catch (error) {
-      if (!/CLIENT_NOT_INITIALIZED/u.test(String(error?.message ?? error))) {
+      if (!/CLIENT_NOT_INITIALIZED/u.test(String(error?.message ?? error))
+          && error?.code !== MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT) {
         throw error;
       }
       const remainingMs = deadline - Date.now();
@@ -428,6 +440,28 @@ async function readOpenOrders(input) {
   );
 }
 
+// The mode the venue binds to a market through its resting orders or TWAPs;
+// open orders themselves do not report it.
+async function readMarginModeLock(input, symbol) {
+  return retryPerpsClientRead(
+    () => evalAsync(
+      input,
+      `(function(){
+        var controller = Engine && Engine.context && Engine.context.PerpsController;
+        if (!controller || typeof controller.getMarginModeLock !== 'function') {
+          throw new Error('Engine.context.PerpsController.getMarginModeLock is unavailable; this build cannot verify margin_mode.');
+        }
+        return controller.getMarginModeLock(${sourceLiteral({ symbol })}).then(function(r){ return JSON.stringify(r); });
+      })()`,
+    ),
+    { deadlineEpochMs: inheritedDeadline(input), call: 'PerpsController.getMarginModeLock' },
+  );
+}
+
+async function requireOrderMarginMode(input, symbol, marginMode, leftOver = '') {
+  return requireLockMarginMode(input.action, symbol, await readMarginModeLock(input, symbol), marginMode, leftOver);
+}
+
 const TWAP_NOT_ADVERTISED = 'provider-does-not-advertise-twap';
 
 async function readStrategyOrders(input) {
@@ -829,8 +863,9 @@ function redactPosition(position) {
   return {
     symbol: position.symbol ?? position.coin ?? null,
     size: position.size ?? position.szi ?? null,
-    side: position.side ?? null,
+    side: sideForItem(position, 'position') || normalizeSide(position.side) || null,
     entryPrice: position.entryPrice ?? position.entryPx ?? null,
+    marginMode: marginModeOf(position),
   };
 }
 
@@ -1527,6 +1562,7 @@ export async function placeOrder(input, { ensure = false } = {}) {
   const maxSlippageBps = Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300);
   const isBuy = orderSideIsBuy(side);
   const orderType = resolveOrderType(input);
+  const marginMode = resolveMarginMode(input.node, input.action);
   const closeImmediately = closeImmediatelyRequested(input.node);
   const runtime = await readPerpsRuntimeState(input);
   const network = orderNetwork({ declared: input.node?.network, liveIsTestnet: runtime?.isTestnet });
@@ -1539,6 +1575,7 @@ export async function placeOrder(input, { ensure = false } = {}) {
     orderType,
     closeImmediately,
     runCancelsLimit: !ensure,
+    marginMode,
     projectRoot: input.context?.projectRoot,
     selectedAddress: bound.address,
   });
@@ -1586,6 +1623,7 @@ export async function placeOrder(input, { ensure = false } = {}) {
       currentPrice,
       priceAtCalculation: currentPrice,
       maxSlippageBps,
+      ...(marginMode ? { marginMode } : {}),
     }
     : {
       symbol,
@@ -1597,7 +1635,9 @@ export async function placeOrder(input, { ensure = false } = {}) {
       currentPrice,
       priceAtCalculation: currentPrice,
       maxSlippageBps,
+      ...(marginMode ? { marginMode } : {}),
     };
+  if (marginMode && orderType === 'limit') requireLockReadable(input.action, symbol, await readMarginModeLock(input, symbol));
   if (await tradingContextChanged(input, bound)) {
     throw new Error('Perps order not dispatched: the selected account or network changed after the order rule allowed it.');
   }
@@ -1617,6 +1657,8 @@ export async function placeOrder(input, { ensure = false } = {}) {
     })
     : null;
   let result;
+  let marginModeLock;
+  let observedMarginMode;
   try {
     result = await evalAsync(input, `(function(){ ${boundContextGuard(bound)}
       return Engine.context.PerpsController.placeOrder(${sourceLiteral(orderParams)}).then(function(r){return JSON.stringify(r)}); })()`);
@@ -1646,12 +1688,24 @@ export async function placeOrder(input, { ensure = false } = {}) {
     } else {
       await waitForPositionPresent(input, symbol, Number(input.node?.timeout_ms ?? 30000));
     }
+    if (marginMode && orderType === 'limit') {
+      const resting = ` The ${symbol} order it placed (${result?.orderId ?? 'unknown id'}) may still be resting; ${ledgerId ? "the run's teardown cancels it" : 'cancel it with ensure_orders state=none'}.`;
+      marginModeLock = await requireOrderMarginMode(input, symbol, marginMode, resting);
+      observedMarginMode = String(marginModeLock.marginMode).toLowerCase();
+    } else if (marginMode) {
+      const positions = await retryPerpsClientRead(
+        () => readBoundPositions(input, bound),
+        { deadlineEpochMs: inheritedDeadline(input), call: 'PerpsController.getPositions' },
+      );
+      const opened = positions.filter((position) => symbolForItem(position) === symbol);
+      observedMarginMode = requirePositionMarginMode(input.action, opened, marginMode);
+    }
   } catch (error) {
     if (ledgerId && error?.knownNotDispatched) await dropMainnetOrder(input.context.projectRoot, ledgerId);
     if (!closeImmediately || error?.knownNotDispatched) throw error;
     throw await closeAfterFailedPlacement(input, symbol, error, bound);
   }
-  const placed = { action: input.action, market: symbol, side, orderType, amount, size, leverage, limitPrice, submitted: true, result, network, policy: policy.lane, ...(policy.autoCancel ? { autoCancel: policy.autoCancel } : {}), ...(houseNotional ? { houseNotional } : {}), proofPath: 'mobile-perps-controller-place-order' };
+  const placed = { action: input.action, market: symbol, side, orderType, amount, size, leverage, ...(observedMarginMode ? { marginMode: observedMarginMode } : {}), ...(marginModeLock ? { marginModeLock } : {}), limitPrice, submitted: true, result, network, policy: policy.lane, ...(policy.autoCancel ? { autoCancel: policy.autoCancel } : {}), ...(houseNotional ? { houseNotional } : {}), proofPath: 'mobile-perps-controller-place-order' };
   if (!closeImmediately) return placed;
   return { ...placed, roundTrip: await closeOpenedPosition(input, symbol, bound) };
 }
@@ -1820,13 +1874,17 @@ export async function ensurePositions(input) {
   requireExplicitSelection(input);
   const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
+    refuseMarginModeForAbsentState(input.node, input.action);
     const close = await closePositions(input);
     return { ...(await assertPositions(input, false)), close };
   }
   if (state === 'open' || state === 'present') {
     const existing = await readPositions(input);
     if (selectedItems(input, existing).length === 0) await placeOrder(input, { ensure: true });
-    return assertPositions(input, true);
+    const result = await assertPositions(input, true);
+    const marginMode = resolveMarginMode(input.node, input.action);
+    if (marginMode) requirePositionMarginMode(input.action, result.positions, marginMode);
+    return result;
   }
   throw new Error(`metamask.perps.ensure_positions received unsupported state: ${state}`);
 }
@@ -1836,6 +1894,7 @@ export async function ensureOrders(input) {
   requireExplicitSelection(input);
   const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
+    refuseMarginModeForAbsentState(input.node, input.action);
     const close = await closeOrders(input);
     return { ...(await assertOrders(input, false)), close };
   }
@@ -1845,7 +1904,16 @@ export async function ensureOrders(input) {
     if (selectedItems(input, current).length === 0) {
       order = await placeOrder({ ...input, node: { ...input.node, order_type: 'limit' } }, { ensure: true });
     }
-    return { ...(await assertOrders(input, true)), order };
+    const result = await assertOrders(input, true);
+    const marginMode = resolveMarginMode(input.node, input.action);
+    if (!marginMode) return { ...result, order };
+    // A placed order was already proved inside placeOrder; reused orders are proved per market.
+    const symbols = order ? [marketSymbol(input)] : [...new Set(result.orders.map((item) => item.symbol))];
+    const locks = {};
+    for (const symbol of symbols) {
+      locks[symbol] = order ? order.marginModeLock : await requireOrderMarginMode(input, symbol, marginMode);
+    }
+    return { ...result, order, marginModeLock: locks[symbols[0]], marginModeLocks: locks };
   }
   throw new Error(`metamask.perps.ensure_orders received unsupported state: ${state}`);
 }
@@ -2028,8 +2096,10 @@ async function applyStrategiesState(input, config) {
   return closeStrategyOrders(childInput(input, node));
 }
 
-async function applyStateNavigation(input, config) {
-  if (!config.page && !config.market && !config.symbol) return { skipped: true };
+// page=false preserves the current route even when market/symbol scopes the
+// cleanup, so a teardown cannot fail on navigation before it cleans.
+export async function applyStateNavigation(input, config) {
+  if (config.page === false || (!config.page && !config.market && !config.symbol)) return { skipped: true };
   const target = config.page ?? defaultNavigationTarget(config);
   return navigatePerps(childInput(input, { target, market: config.market, symbol: config.symbol }));
 }

package/library/actions/mobile/platform/observe-ui.mjs

@@ -503,18 +503,26 @@ function flattenIosHierarchy(value, textTestIds = [], hudIntent) {
   return { visible, hidden, nodeCount, screenName };
 }
 
-function parseAndroidHierarchy(output, hudIntent) {
+// Unlabeled test-ID containers (a Pressable around TextViews) also report the
+// visible text of their descendants as descendant_text, capped so a container
+// such as a scroll view does not carry the whole screen.
+const DESCENDANT_TEXT_LIMIT = 500;
+
+export function parseAndroidHierarchy(output, hudIntent) {
   const xmlStart = Math.max(output.indexOf('<?xml'), output.indexOf('<hierarchy'));
   const xml = xmlStart >= 0 ? output.slice(xmlStart) : output;
   const visible = [];
   const hidden = [];
   const ancestorVisibility = [];
+  const openItems = [];
   let nodeCount = 0;
   let screenName;
   for (const match of xml.matchAll(/<\/?node\b[^>]*>/gu)) {
     const tag = match[0];
     if (tag.startsWith('</')) {
       ancestorVisibility.pop();
+      const closed = openItems.pop();
+      if (closed?.texts.length) closed.item.descendant_text = closed.texts.join(' ').slice(0, DESCENDANT_TEXT_LIMIT);
       continue;
     }
     const attributes = {};
@@ -528,6 +536,7 @@ function parseAndroidHierarchy(output, hudIntent) {
     const label = text(attributes['content-desc']) ??
       (isEditable ? undefined : text(attributes.text));
     if (!screenName && label && !isEditable) screenName = label;
+    const ownText = isEditable ? undefined : text(attributes.text) ?? text(attributes['content-desc']);
     const item = compactItem({
       role,
       label,
@@ -540,6 +549,9 @@ function parseAndroidHierarchy(output, hudIntent) {
     const isVisible =
       ancestorVisibility.every(Boolean) &&
       attributes['visible-to-user'] !== 'false';
+    if (ownText && isVisible) {
+      for (const open of openItems) if (open) open.texts.push(ownText);
+    }
     const isActionable =
       isActionableRole(role) ||
       attributes.clickable === 'true' ||
@@ -551,7 +563,10 @@ function parseAndroidHierarchy(output, hudIntent) {
         hidden.push({ ...item, reason: 'hidden' });
       }
     }
-    if (!tag.endsWith('/>')) ancestorVisibility.push(isVisible);
+    if (!tag.endsWith('/>')) {
+      ancestorVisibility.push(isVisible);
+      openItems.push(item.test_id && !item.label ? { item, texts: [] } : null);
+    }
   }
   return { visible, hidden, nodeCount, screenName };
 }

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

@@ -1,18 +1,28 @@
 // Turn visible Mobile accessibility observations into UI locator candidates.
 import { observeNativeUi } from '../platform/observe-ui.mjs';
-import { runAdapter } from '../platform/bridge.mjs';
+import { earliestDeadline, runAdapter } from '../platform/bridge.mjs';
 import {
   locatorsFromObservation,
+  observeRequestedTestIds,
+  requestedEnabledStates,
+  requestedTestIds,
+  requestedTimeoutMs,
   requireVisibleObservation,
 } from '../../shared/ui/locators.mjs';
 
 runAdapter(async (input) => {
-  const observed = await observeNativeUi(
-    { refs: ['ui.visible'], node: input.node },
-    input.context,
+  const testIds = requestedTestIds(input.node);
+  const observation = await observeRequestedTestIds(
+    async () => requireVisibleObservation(await observeNativeUi(
+      { refs: ['ui.visible'], node: input.node },
+      input.context,
+    )),
+    testIds,
+    earliestDeadline(input, Date.now() + requestedTimeoutMs(input.node)),
+    requestedEnabledStates(input.node, testIds),
   );
   return {
     action: input.action,
-    ...locatorsFromObservation(requireVisibleObservation(observed)),
+    ...locatorsFromObservation(observation, { testIds }),
   };
 });

package/library/actions/shared/perps/margin-mode.mjs

@@ -0,0 +1,53 @@
+// Margin-mode requests and venue proofs shared by the Mobile and Core Perps order actions.
+
+export const MARGIN_MODES = Object.freeze(['isolated', 'cross']);
+
+// Omitted keeps the venue default: the open position's mode, else isolated.
+export function resolveMarginMode(node, action) {
+  const raw = node?.margin_mode ?? node?.marginMode;
+  if (raw == null || raw === '') return undefined;
+  const value = String(raw).toLowerCase();
+  if (!MARGIN_MODES.includes(value)) {
+    throw new Error(`${action} received unsupported margin_mode: ${value}.`);
+  }
+  return value;
+}
+
+// Same source as the mainnet house-limit check, normalized to isolated|cross.
+// Accepts a raw controller position or one already redacted with marginMode.
+export function marginModeOf(position) {
+  return String(position?.marginMode ?? position?.leverage?.type ?? position?.marginType ?? '').toLowerCase() || null;
+}
+
+export function refuseMarginModeForAbsentState(node, action) {
+  if (resolveMarginMode(node, action)) {
+    throw new Error(`${action} margin_mode applies only to state=open; drop it for state=none.`);
+  }
+}
+
+export function requirePositionMarginMode(action, positions, marginMode) {
+  if (positions.length === 0) {
+    throw new Error(`${action} requested margin_mode=${marginMode}, but no matching position was observed to prove it.`);
+  }
+  const mismatched = positions.filter((position) => marginModeOf(position) !== marginMode);
+  if (mismatched.length > 0) {
+    const found = mismatched.map((position) => `${position.symbol ?? position.coin} is ${marginModeOf(position)}`).join(', ');
+    throw new Error(`${action} requested margin_mode=${marginMode}, but ${found}; the venue cannot change an open position's mode, so converge with state=none first.`);
+  }
+  return marginModeOf(positions[0]);
+}
+
+// A resting order is only provable through the venue lock, so refuse before
+// dispatch when the build or provider cannot answer it.
+export function requireLockReadable(action, symbol, lock) {
+  if (lock?.status !== 'locked' && lock?.status !== 'unlocked') {
+    throw new Error(`${action} cannot verify margin_mode for ${symbol} before placing a resting order: the venue lock reports ${JSON.stringify(lock)}.`);
+  }
+}
+
+export function requireLockMarginMode(action, symbol, lock, marginMode, leftOver = '') {
+  if (lock?.status !== 'locked' || String(lock.marginMode).toLowerCase() !== marginMode) {
+    throw new Error(`${action} requested margin_mode=${marginMode} for ${symbol}, but the venue reports ${JSON.stringify(lock)}.${leftOver}`);
+  }
+  return lock;
+}

package/library/actions/shared/perps/order-policy.mjs

@@ -62,10 +62,11 @@ export function closeImmediatelyRequested(node) {
  * @param {boolean} order.fixtureAccount - The selected account is a synced fixture account.
  * @param {string|null} [order.accountName] - Its fixture name.
  * @param {boolean} [order.runCancelsLimit] - The caller records a limit order for the run's forced cancel.
+ * @param {'isolated'|'cross'} [order.marginMode] - Explicit collateral mode; mainnet allows only isolated.
  * @returns {{ lane: 'testnet' } | { lane: 'mainnet-house-limits', notionalBaseUnits: string, autoCancel?: 'end-of-run' }}
  */
 export function decidePerpsOrder({
-  network, amount, leverage, orderType = 'market', closeImmediately, fixtureAccount, accountName = null, runCancelsLimit = false,
+  network, amount, leverage, orderType = 'market', closeImmediately, fixtureAccount, accountName = null, runCancelsLimit = false, marginMode,
 }) {
   if (closeImmediately && orderType !== 'market') {
     throw new Error('close_immediately needs a market order: a resting limit order is not a position the action can close.');
@@ -80,6 +81,7 @@ export function decidePerpsOrder({
   if (amountBaseUnits <= 0n) broken.push('the amount is not positive');
   if (!fixtureAccount) broken.push('the selected account is not one of the synced test accounts');
   if (leverageValue !== MAINNET_HOUSE_LIMITS.leverage) broken.push(`leverage is ${leverage}, not 1`);
+  if (marginMode !== undefined && marginMode !== 'isolated') broken.push(`margin_mode is ${marginMode}, not isolated`);
   if (notionalBaseUnits > MAINNET_HOUSE_LIMITS.maxNotionalBaseUnits) {
     broken.push(`notional ${formatUsd(notionalBaseUnits)} is above $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}`);
   }

package/library/actions/shared/ui/locators.mjs

@@ -21,7 +21,7 @@ const INTERACTIVE_ROLE_PARTS = [
   'cell',
 ];
 
-export function locatorsFromObservation(observation) {
+export function locatorsFromObservation(observation, { testIds = [] } = {}) {
   const value = record(observation);
   const items = Array.isArray(value.items) ? value.items.map(record) : [];
   const ranked = items
@@ -44,9 +44,92 @@ export function locatorsFromObservation(observation) {
     count: locators.length,
     truncated: value.truncated === true || ranked.length > locators.length,
     locators,
+    ...(testIds.length > 0 ? visibleStateByTestId(items, testIds, value.truncated === true) : {}),
   };
 }
 
+// State lookup for requested test IDs over every visible item, including
+// disabled or non-interactive ones that are not press targets.
+// A truncated observation cannot prove absence, so its gaps are reported as
+// unobservedTestIds rather than missingTestIds.
+function visibleStateByTestId(items, testIds, truncated) {
+  const byTestId = Object.create(null);
+  const absent = [];
+  for (const testId of testIds) {
+    const matches = items.filter((item) => text(item.test_id) === testId);
+    if (matches.length === 0) {
+      absent.push(testId);
+      continue;
+    }
+    const item = matches[0];
+    byTestId[testId] = {
+      matches: matches.length,
+      role: text(item.role),
+      enabled: typeof item.enabled === 'boolean' ? item.enabled : null,
+      ...(typeof item.selected === 'boolean' ? { selected: item.selected } : {}),
+      description: describe(item),
+      bounds: bounds(item.bounds),
+    };
+  }
+  return truncated
+    ? { byTestId, missingTestIds: [], unobservedTestIds: absent }
+    : { byTestId, missingTestIds: absent, unobservedTestIds: [] };
+}
+
+// The native accessibility tree can lag the React tree while a sheet animates
+// in, and a control can stay disabled until its data loads, so requested test
+// IDs are re-read until observed (and in their expected enabled state) or the
+// bound expires. The caller asserts on whatever the last read saw.
+export async function observeRequestedTestIds(observe, testIds, deadlineEpochMs, expectEnabled = {}) {
+  const pollMs = 250;
+  while (true) {
+    const observation = await observe();
+    if (testIds.length === 0 || !Number.isFinite(deadlineEpochMs)) return observation;
+    const items = (Array.isArray(observation?.items) ? observation.items : []).map(record);
+    const settled = testIds.every((testId) => {
+      const item = items.find((candidate) => text(candidate.test_id) === testId);
+      return item && (!(testId in expectEnabled) || item.enabled === expectEnabled[testId]);
+    });
+    if (settled) return observation;
+    if (Date.now() + pollMs >= deadlineEpochMs) return observation;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+export function requestedTestIds(node) {
+  const value = node?.test_ids;
+  if (value == null) return [];
+  if (!Array.isArray(value) || !value.every((id) => typeof id === 'string' && id.trim())) {
+    throw new Error('ui.locators test_ids must be an array of non-empty test ID strings.');
+  }
+  return value.map((id) => id.trim());
+}
+
+// Booleans may arrive as rendered template strings ("true"/"false").
+export function requestedEnabledStates(node, testIds) {
+  const value = node?.expect_enabled;
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('ui.locators expect_enabled must map requested test IDs to true or false.');
+  }
+  const states = Object.create(null);
+  for (const [testId, raw] of Object.entries(value)) {
+    const enabled = raw === true || raw === 'true' ? true : raw === false || raw === 'false' ? false : null;
+    if (!testIds.includes(testId) || enabled === null) {
+      throw new Error(`ui.locators expect_enabled must map requested test IDs to true or false; got ${testId}: ${JSON.stringify(raw)}.`);
+    }
+    states[testId] = enabled;
+  }
+  return states;
+}
+
+export function requestedTimeoutMs(node) {
+  const value = node?.timeout_ms;
+  if (value == null) return 5000;
+  if (!Number.isFinite(value) || value < 0) throw new Error('ui.locators timeout_ms must be a non-negative number.');
+  return value;
+}
+
 function locatorPriority(locator) {
   const role = text(locator.role)?.toLowerCase() ?? '';
   if (INTERACTIVE_ROLE_PARTS.some((part) => role.includes(part))) return 0;
@@ -129,6 +212,7 @@ function supportsTextTarget(role) {
 function describe(item) {
   const parts = [text(item.role) ?? 'element'];
   if (text(item.label)) parts.push(`label=${JSON.stringify(text(item.label))}`);
+  if (text(item.descendant_text)) parts.push(`text=${JSON.stringify(text(item.descendant_text))}`);
   if (text(item.test_id)) parts.push(`test_id=${JSON.stringify(text(item.test_id))}`);
   return parts.join(' ');
 }

package/library/manifests/core.action-manifest.json

@@ -572,7 +572,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.read_positions": {
-      "description": "core Read live Perps positions directly from the Perps controller; without a selector, return all live positions.",
+      "description": "core Read live Perps positions directly from the Perps controller; without a selector, return all live positions. Each position reports side (from its signed size) and marginMode (isolated or cross) when the controller exposes it.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1098,6 +1098,11 @@
             "type": "number",
             "default": 3
           },
+          "margin_mode": {
+            "type": "string",
+            "enum": ["isolated", "cross"],
+            "description": "Collateral mode for this order (Hyperliquid). The action proves the opened position or, for a resting order, the venue lock carries it and fails otherwise. Mainnet refuses anything but isolated. Omitted keeps the venue default: the open position mode, else isolated."
+          },
           "close_immediately": {
             "type": "boolean",
             "description": "Close the opened position again inside this action and prove the market flat (market orders only; the market must start flat). Required on mainnet, with leverage 1 and notional at most $15 from a fixture account."
@@ -1701,6 +1706,11 @@
             ],
             "description": "USD notional alias."
           },
+          "margin_mode": {
+            "type": "string",
+            "enum": ["isolated", "cross"],
+            "description": "Collateral mode for a created position. A reused open position must already hold it, since the venue cannot change it while open. Applies only to state=open."
+          },
           "leverage": {
             "type": "number"
           },
@@ -2188,6 +2198,11 @@
             "type": "number",
             "description": "Leverage used only when creating a missing open order."
           },
+          "margin_mode": {
+            "type": "string",
+            "enum": ["isolated", "cross"],
+            "description": "Collateral mode for a created resting order. Also proves the venue lock binds this mode on every selected market, including orders that already rested; the result lists each lock in marginModeLocks. Applies only to state=open."
+          },
           "state": {
             "type": "string",
             "enum": [
@@ -2347,6 +2362,11 @@
               "leverage": {
                 "type": "number"
               },
+              "margin_mode": {
+                "type": "string",
+                "enum": ["isolated", "cross"],
+                "description": "Collateral mode passed to the ensure_* step that creates this state (isolated or cross); see metamask.perps.ensure_positions / ensure_orders."
+              },
               "order_type": {
                 "type": "string"
               },
@@ -2458,6 +2478,11 @@
               "leverage": {
                 "type": "number"
               },
+              "margin_mode": {
+                "type": "string",
+                "enum": ["isolated", "cross"],
+                "description": "Collateral mode passed to the ensure_* step that creates this state (isolated or cross); see metamask.perps.ensure_positions / ensure_orders."
+              },
               "order_type": {
                 "type": "string"
               },

package/library/manifests/mobile.action-manifest.json

@@ -1005,7 +1005,22 @@
       "execution_capabilities": ["host-read-export"],
       "schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "test_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Also report byTestId: the role, enabled state and description of each visible element with these test IDs, including disabled and non-interactive ones (enabled is null when unreported). Absent IDs are listed in missingTestIds, or in unobservedTestIds when the accessibility observation itself was truncated (not the 20-entry ranked list) and cannot prove absence. Prove presence from byTestId, not from an empty missingTestIds. Use it to assert control state; locators lists only press targets."
+          },
+          "expect_enabled": {
+            "type": "object",
+            "description": "Map of requested test IDs to the enabled state (true or false) to wait for, for controls that stay disabled until their data loads. The last read is returned either way; assert on byTestId."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "minimum": 0,
+            "description": "With test_ids, re-read the observation until every requested test ID is present (and matches expect_enabled) or this many milliseconds pass (default 5000)."
+          }
+        },
         "additionalProperties": false
       },
       "examples": [
@@ -2363,7 +2378,7 @@
       "execution_capabilities": ["app-mutation"]
     },
     "metamask.perps.read_positions": {
-      "description": "mobile Read live Perps positions; without a selector, return all live positions.",
+      "description": "mobile Read live Perps positions; without a selector, return all live positions. Each position reports side (from its signed size) and marginMode (isolated or cross) when the product exposes it.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2840,6 +2855,11 @@
             "enum": ["market", "limit"],
             "default": "market"
           },
+          "margin_mode": {
+            "type": "string",
+            "enum": ["isolated", "cross"],
+            "description": "Collateral mode for this order (Hyperliquid; limit orders need a build with getMarginModeLock). The action proves the opened position or the venue lock carries it and fails otherwise. Omitted keeps the venue default: the open position mode, else isolated."
+          },
           "limit_price": {
             "type": ["string", "number"],
             "description": "Limit price; omit it to offset from the current market price by offset_pct."
@@ -3128,6 +3148,11 @@
             "type": ["string", "number"],
             "description": "Alias for amount."
           },
+          "margin_mode": {
+            "type": "string",
+            "enum": ["isolated", "cross"],
+            "description": "Collateral mode for a created position. Also proves every selected open position carries it; an existing position in another mode fails, since the venue cannot change it while open."
+          },
           "state": {
             "type": "string",
             "enum": ["none", "absent", "closed", "open", "present"],
@@ -3249,6 +3274,11 @@
             "default": 3,
             "description": "Testnet leverage used only when creating a missing open order."
           },
+          "margin_mode": {
+            "type": "string",
+            "enum": ["isolated", "cross"],
+            "description": "Collateral mode for a created resting order. Also proves the venue lock binds this mode on every selected market, including orders that already rested; the result lists each lock in marginModeLocks, and marginModeLock is the first market's. Requires a build with getMarginModeLock."
+          },
           "state": {
             "type": "string",
             "enum": ["none", "absent", "closed", "open", "present"],
@@ -3556,7 +3586,7 @@
             }
           },
           "page": {
-            "description": "Initial Perps page target; omit it to use the profile or market default, or set false without market/symbol to preserve the current route.",
+            "description": "Initial Perps page target; omit it to use the profile or market default, or set false to preserve the current route (market/symbol then only scope the trading state). Without navigation, Perps must already have been opened in this app session.",
             "type": ["string", "boolean"],
             "enum": [false, "home", "perps", "perps_home", "market", "market_details"]
           },
@@ -3616,6 +3646,11 @@
               "leverage": {
                 "type": "number"
               },
+              "margin_mode": {
+                "type": "string",
+                "enum": ["isolated", "cross"],
+                "description": "Collateral mode passed to the ensure_* step that creates this state (isolated or cross); see metamask.perps.ensure_positions / ensure_orders."
+              },
               "order_type": {
                 "type": "string"
               },
@@ -3704,6 +3739,11 @@
               "leverage": {
                 "type": "number"
               },
+              "margin_mode": {
+                "type": "string",
+                "enum": ["isolated", "cross"],
+                "description": "Collateral mode passed to the ensure_* step that creates this state (isolated or cross); see metamask.perps.ensure_positions / ensure_orders."
+              },
               "order_type": {
                 "type": "string"
               },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.92.39",
+  "version": "0.94.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"