@deeeed/metamask-harness 0.93.0 → 0.94.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## 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

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();
@@ -349,17 +361,6 @@ function resolveOrderType(input) {
   return value;
 }
 
-// Omitted keeps the venue default: the open position's mode, else isolated.
-function resolveMarginMode(input) {
-  const raw = input.node?.margin_mode ?? input.node?.marginMode;
-  if (raw == null || raw === '') return undefined;
-  const value = String(raw).toLowerCase();
-  if (value !== 'isolated' && value !== 'cross') {
-    throw new Error(`${input.action} received unsupported margin_mode: ${value}.`);
-  }
-  return value;
-}
-
 function resolveLimitPrice(input, isBuy, currentPrice) {
   const explicit = input.node?.limit_price ?? input.node?.limitPrice ?? input.node?.price;
   if (explicit != null && String(explicit).length > 0) {
@@ -458,30 +459,7 @@ async function readMarginModeLock(input, symbol) {
 }
 
 async function requireOrderMarginMode(input, symbol, marginMode, leftOver = '') {
-  const lock = await readMarginModeLock(input, symbol);
-  if (lock?.status !== 'locked' || lock.marginMode !== marginMode) {
-    throw new Error(`${input.action} requested margin_mode=${marginMode} for ${symbol}, but the venue reports ${JSON.stringify(lock)}.${leftOver}`);
-  }
-  return lock;
-}
-
-// A resting order is only provable through the venue lock, so refuse before
-// dispatch when this build or provider cannot answer it.
-async function requireMarginModeLockReadable(input, symbol) {
-  const lock = await readMarginModeLock(input, symbol);
-  if (lock?.status !== 'locked' && lock?.status !== 'unlocked') {
-    throw new Error(`${input.action} cannot verify margin_mode for ${symbol} before placing a resting order: the venue lock reports ${JSON.stringify(lock)}.`);
-  }
-}
-
-function requirePositionMarginMode(input, positions, marginMode) {
-  if (positions.length === 0) {
-    throw new Error(`${input.action} requested margin_mode=${marginMode}, but no matching position was observed to prove it.`);
-  }
-  const mismatched = positions.filter((position) => position.marginMode !== marginMode);
-  if (mismatched.length > 0) {
-    throw new Error(`${input.action} requested margin_mode=${marginMode}, but ${mismatched.map((p) => `${p.symbol} is ${p.marginMode}`).join(', ')}; the venue cannot change an open position's mode, so converge with state=none first.`);
-  }
+  return requireLockMarginMode(input.action, symbol, await readMarginModeLock(input, symbol), marginMode, leftOver);
 }
 
 const TWAP_NOT_ADVERTISED = 'provider-does-not-advertise-twap';
@@ -885,10 +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,
-    // Same source as the mainnet house-limit check, normalized to isolated|cross.
-    marginMode: String(position.leverage?.type ?? position.marginType ?? '').toLowerCase() || null,
+    marginMode: marginModeOf(position),
   };
 }
 
@@ -1585,7 +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);
+  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 });
@@ -1660,7 +1637,7 @@ export async function placeOrder(input, { ensure = false } = {}) {
       maxSlippageBps,
       ...(marginMode ? { marginMode } : {}),
     };
-  if (marginMode && orderType === 'limit') await requireMarginModeLockReadable(input, symbol);
+  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.');
   }
@@ -1712,13 +1689,16 @@ export async function placeOrder(input, { ensure = false } = {}) {
       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'}) is still resting; ${ledgerId ? "the run's teardown cancels it" : 'cancel it with ensure_orders state=none'}.`;
+      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 = marginModeLock.marginMode;
+      observedMarginMode = String(marginModeLock.marginMode).toLowerCase();
     } else if (marginMode) {
-      const opened = (await readBoundPositions(input, bound)).filter((position) => symbolForItem(position) === symbol);
-      requirePositionMarginMode(input, opened.map(redactPosition), marginMode);
-      observedMarginMode = redactPosition(opened[0]).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);
@@ -1894,7 +1874,7 @@ export async function ensurePositions(input) {
   requireExplicitSelection(input);
   const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
-    refuseMarginModeForAbsentState(input);
+    refuseMarginModeForAbsentState(input.node, input.action);
     const close = await closePositions(input);
     return { ...(await assertPositions(input, false)), close };
   }
@@ -1902,8 +1882,8 @@ export async function ensurePositions(input) {
     const existing = await readPositions(input);
     if (selectedItems(input, existing).length === 0) await placeOrder(input, { ensure: true });
     const result = await assertPositions(input, true);
-    const marginMode = resolveMarginMode(input);
-    if (marginMode) requirePositionMarginMode(input, result.positions, marginMode);
+    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}`);
@@ -1914,7 +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);
+    refuseMarginModeForAbsentState(input.node, input.action);
     const close = await closeOrders(input);
     return { ...(await assertOrders(input, false)), close };
   }
@@ -1925,7 +1905,7 @@ export async function ensureOrders(input) {
       order = await placeOrder({ ...input, node: { ...input.node, order_type: 'limit' } }, { ensure: true });
     }
     const result = await assertOrders(input, true);
-    const marginMode = resolveMarginMode(input);
+    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))];
@@ -1939,12 +1919,6 @@ export async function ensureOrders(input) {
 }
 
 
-function refuseMarginModeForAbsentState(input) {
-  if (resolveMarginMode(input)) {
-    throw new Error(`${input.action} margin_mode applies only to state=open; drop it for state=none.`);
-  }
-}
-
 function paramsForState(input) {
   const nested = input.node?.params && typeof input.node.params === 'object' ? input.node.params : {};
   return { ...nested, ...input.node };
@@ -2122,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

@@ -4,6 +4,7 @@ import { earliestDeadline, runAdapter } from '../platform/bridge.mjs';
 import {
   locatorsFromObservation,
   observeRequestedTestIds,
+  requestedEnabledStates,
   requestedTestIds,
   requestedTimeoutMs,
   requireVisibleObservation,
@@ -18,6 +19,7 @@ runAdapter(async (input) => {
     )),
     testIds,
     earliestDeadline(input, Date.now() + requestedTimeoutMs(input.node)),
+    requestedEnabledStates(input.node, testIds),
   );
   return {
     action: input.action,

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/ui/locators.mjs

@@ -77,15 +77,20 @@ function visibleStateByTestId(items, testIds, truncated) {
 }
 
 // The native accessibility tree can lag the React tree while a sheet animates
-// in, so a requested test ID is re-read until observed or the bound expires.
-export async function observeRequestedTestIds(observe, testIds, deadlineEpochMs) {
+// 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) return observation;
-    const items = Array.isArray(observation?.items) ? observation.items : [];
-    const seen = new Set(items.map((item) => text(record(item).test_id)));
-    if (testIds.every((testId) => seen.has(testId))) return observation;
+    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));
   }
@@ -100,6 +105,24 @@ export function requestedTestIds(node) {
   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;
@@ -189,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

@@ -1009,12 +1009,16 @@
           "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 observation was truncated and cannot prove absence. Use it to assert control state; locators lists only press targets."
+            "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 or this many milliseconds pass (default 5000)."
+            "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
@@ -2374,7 +2378,7 @@
       "execution_capabilities": ["app-mutation"]
     },
     "metamask.perps.read_positions": {
-      "description": "mobile Read live Perps positions; without a selector, return all live positions. Each position reports marginMode (isolated or cross) when the product exposes it.",
+      "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": {
@@ -3273,7 +3277,7 @@
           "margin_mode": {
             "type": "string",
             "enum": ["isolated", "cross"],
-            "description": "Collateral mode for a created resting order. Also proves the venue lock binds this mode, including for an order that already rested. Requires a build with getMarginModeLock."
+            "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",
@@ -3582,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"]
           },
@@ -3642,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"
               },
@@ -3730,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.93.0",
+  "version": "0.94.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"