@deeeed/metamask-harness 0.92.39 → 0.93.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 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/mobile/perps/perps.mjs

@@ -349,6 +349,17 @@ 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) {
@@ -428,6 +439,51 @@ 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 = '') {
+  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.`);
+  }
+}
+
 const TWAP_NOT_ADVERTISED = 'provider-does-not-advertise-twap';
 
 async function readStrategyOrders(input) {
@@ -831,6 +887,8 @@ function redactPosition(position) {
     size: position.size ?? position.szi ?? null,
     side: 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,
   };
 }
 
@@ -1527,6 +1585,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 closeImmediately = closeImmediatelyRequested(input.node);
   const runtime = await readPerpsRuntimeState(input);
   const network = orderNetwork({ declared: input.node?.network, liveIsTestnet: runtime?.isTestnet });
@@ -1539,6 +1598,7 @@ export async function placeOrder(input, { ensure = false } = {}) {
     orderType,
     closeImmediately,
     runCancelsLimit: !ensure,
+    marginMode,
     projectRoot: input.context?.projectRoot,
     selectedAddress: bound.address,
   });
@@ -1586,6 +1646,7 @@ export async function placeOrder(input, { ensure = false } = {}) {
       currentPrice,
       priceAtCalculation: currentPrice,
       maxSlippageBps,
+      ...(marginMode ? { marginMode } : {}),
     }
     : {
       symbol,
@@ -1597,7 +1658,9 @@ export async function placeOrder(input, { ensure = false } = {}) {
       currentPrice,
       priceAtCalculation: currentPrice,
       maxSlippageBps,
+      ...(marginMode ? { marginMode } : {}),
     };
+  if (marginMode && orderType === 'limit') await requireMarginModeLockReadable(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 +1680,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 +1711,21 @@ 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'}) is still 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;
+    } 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;
+    }
   } 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 +1894,17 @@ export async function ensurePositions(input) {
   requireExplicitSelection(input);
   const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
+    refuseMarginModeForAbsentState(input);
     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);
+    if (marginMode) requirePositionMarginMode(input, result.positions, marginMode);
+    return result;
   }
   throw new Error(`metamask.perps.ensure_positions received unsupported state: ${state}`);
 }
@@ -1836,6 +1914,7 @@ export async function ensureOrders(input) {
   requireExplicitSelection(input);
   const state = String(input.node.state).toLowerCase();
   if (state === 'none' || state === 'closed' || state === 'absent') {
+    refuseMarginModeForAbsentState(input);
     const close = await closeOrders(input);
     return { ...(await assertOrders(input, false)), close };
   }
@@ -1845,12 +1924,27 @@ 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);
+    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}`);
 }
 
 
+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 };

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

@@ -1,18 +1,26 @@
 // 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,
+  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)),
   );
   return {
     action: input.action,
-    ...locatorsFromObservation(requireVisibleObservation(observed)),
+    ...locatorsFromObservation(observation, { testIds }),
   };
 });

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,69 @@ 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, so a requested test ID is re-read until observed or the bound expires.
+export async function observeRequestedTestIds(observe, testIds, deadlineEpochMs) {
+  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 (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());
+}
+
+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;

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

@@ -1005,7 +1005,18 @@
       "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 observation was truncated and cannot prove absence. Use it to assert control state; locators lists only press targets."
+          },
+          "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)."
+          }
+        },
         "additionalProperties": false
       },
       "examples": [
@@ -2363,7 +2374,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 marginMode (isolated or cross) when the product exposes it.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2840,6 +2851,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 +3144,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 +3270,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, including for an order that already rested. Requires a build with getMarginModeLock."
+          },
           "state": {
             "type": "string",
             "enum": ["none", "absent", "closed", "open", "present"],

package/package.json

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