@deeeed/metamask-harness 0.48.0 → 0.49.0

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

@@ -1,3 +1,4 @@
+// Enter a query in the native Perps market search and wait for visible market rows.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

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

@@ -1,3 +1,5 @@
+// Set a visible market's watchlist state through native controls and verify the result.
+// With require_unchanged, fail on a mismatched state without toggling the control.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/platform/bridge.mjs

@@ -1,3 +1,5 @@
+// Run Mobile actions and device-targeted bridge commands with deadlines and classified errors.
+// Provide runtime evaluation, verified navigation, external deeplink launch, and screenshot capture.
 import { randomUUID } from 'node:crypto';
 import { constants as fsConstants, existsSync } from 'node:fs';
 import { mkdir, mkdtemp, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
@@ -666,8 +668,16 @@ async function waitForNextRouteProbe(deadline) {
 
 export async function navigate(input, route, params = {}, expectedRoute) {
   const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15000);
-  const requestedRoute = String(expectedRoute ?? route);
-  const requestedParams = requestedRoute === String(route) ? params : undefined;
+  let requestedRoute = String(expectedRoute ?? route);
+  let requestedParams = requestedRoute === String(route) ? params : undefined;
+  const nestedTarget = expectedRoute == null && typeof params?.screen === 'string';
+  if (nestedTarget) {
+    // React Navigation reports the active leaf, not its enclosing navigator.
+    while (typeof requestedParams?.screen === 'string') {
+      requestedRoute = requestedParams.screen;
+      requestedParams = requestedParams.params ?? {};
+    }
+  }
   const transitionCodes = [];
   let lastTransitionError = null;
   let navigateAttempts = 0;
@@ -754,13 +764,15 @@ export async function navigate(input, route, params = {}, expectedRoute) {
         input,
         ['navigate', route, JSON.stringify(params)],
       );
-      const verifiedRoute = String(
+      const verifiedRoute = nestedTarget ? requestedRoute : String(
         expectedRoute ??
           (navigation && typeof navigation === 'object' && navigation.navigated
             ? navigation.navigated
             : route),
       );
-      const verifiedParams = verifiedRoute === String(route) ? params : undefined;
+      const verifiedParams = nestedTarget
+        ? requestedParams
+        : verifiedRoute === String(route) ? params : undefined;
       const currentRoute = await waitForRoute(
         input,
         verifiedRoute,

package/library/actions/mobile/platform/native-session-name.mjs

@@ -1,3 +1,4 @@
+// Derive native session names and device-specific state directories, honoring configured overrides.
 import path from 'node:path';
 
 export function nativeSessionName(env, device, app = 'io.metamask') {

package/library/actions/mobile/platform/native-session.mjs

@@ -1,3 +1,5 @@
+// Create device-targeted native UI sessions for actions and accessibility snapshots.
+// Opening an instrumented iOS session hides the accessibility-masking HUD.
 import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
 import { createAgentDeviceClient } from 'agent-device';
 

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

@@ -1,3 +1,5 @@
+// Read and normalize native accessibility hierarchies into screen and visible-item observations.
+// Attempt to hide the masking HUD first and return observation failures as warnings.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createAgentDeviceClient } from 'agent-device';

package/library/actions/mobile/platform/tool-paths.mjs

@@ -1,3 +1,4 @@
+// Locate executable adb and idb clients, cache their paths, and export tool-path environment overrides.
 import { constants as fsConstants, accessSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';

package/library/actions/mobile/swap_bridge/native-session.mjs

@@ -1,3 +1,4 @@
+// Bind shared native UI session helpers to Swap actions.
 import {
   closeNativeSession,
   createNativeSession,

package/library/actions/mobile/swap_bridge/read_visible_state.mjs

@@ -1,3 +1,4 @@
+// Normalize Mobile accessibility observations into visible Swap and Bridge quote state.
 import { runAdapter } from '../platform/bridge.mjs';
 import { observeNativeUi } from '../platform/observe-ui.mjs';
 import {

package/library/actions/mobile/swap_bridge/select_assets.mjs

@@ -1,3 +1,5 @@
+// Select source and destination assets through native token pickers and verify their symbols.
+// Exact asset-ID selection is unsupported.
 import { runAdapter } from '../platform/bridge.mjs';
 import { resolveAssetSelectionOptions } from '../../shared/swap-bridge/transaction.mjs';
 import {

package/library/actions/mobile/swap_bridge/set_amount.mjs

@@ -1,3 +1,4 @@
+// Replace the Swap source amount through its keypad and optionally wait for a quote or no-quote state.
 import { runAdapter } from '../platform/bridge.mjs';
 import { resolveAmountOptions } from '../../shared/swap-bridge/transaction.mjs';
 import {

package/library/actions/mobile/swap_bridge/set_max_amount.mjs

@@ -1,3 +1,4 @@
+// Press Swap Max, verify a positive source amount, and optionally wait for the quote result.
 import { runAdapter } from '../platform/bridge.mjs';
 import { resolveAmountOptions } from '../../shared/swap-bridge/transaction.mjs';
 import {

package/library/actions/mobile/swap_bridge/set_slippage.mjs

@@ -1,3 +1,4 @@
+// Apply custom Swap slippage through native controls and verify the refreshed quote displays it.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

package/library/actions/mobile/swap_bridge/submit_transaction.mjs

@@ -1,3 +1,5 @@
+// Submit a live Swap or Bridge with confirm_live, including any price-impact confirmation.
+// Require a stable matching quote, a completion status, and a visible Activity entry.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,

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

@@ -1,3 +1,4 @@
+// Turn visible Mobile accessibility observations into UI locator candidates.
 import { observeNativeUi } from '../platform/observe-ui.mjs';
 import { runAdapter } from '../platform/bridge.mjs';
 import {

package/library/actions/mobile/ui/native-navigation.mjs

@@ -1,3 +1,5 @@
+// Navigate Android Home, Swap, and Perps through native controls and verify visible destinations.
+// Switch Perps Lite or Pro mode through visible controls on Android and iOS.
 import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
 import { createAgentDeviceClient } from 'agent-device';
 import {

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

@@ -1,3 +1,5 @@
+// Resolve page intents or raw routes into Mobile navigation, using native controls in opaque mode.
+// Verify requested Perps market mode through visible controls.
 import {
   navigate,
   resolveMobileTarget,

package/library/actions/mobile/wallet/ensure_unlocked.mjs

@@ -1,3 +1,5 @@
+// Unlock an existing wallet with a supplied or fixture password through the bridge or native UI.
+// Verify wallet readiness and, for bridge sessions, a stable unlocked controller state.
 import { readFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import {

package/library/actions/mobile/wallet/home.mjs

@@ -1,3 +1,4 @@
+// Open wallet home through WalletView, with a verified HomeNav fallback for older navigators.
 import { bridgeCommand, navigate, waitForRoute } from '../platform/bridge.mjs';
 
 /**

package/library/actions/mobile/wallet/import.mjs

@@ -1,3 +1,5 @@
+// Import a recovery phrase through onboarding or unlock an existing profile, then verify the expected account.
+// Fresh imports also handle consent, interests, and supported onboarding prompts.
 import { createHash } from 'node:crypto';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';

package/library/actions/mobile/wallet/list_accounts.mjs

@@ -1,3 +1,4 @@
+// List controller accounts with selection markers, filtered by selected, named, EVM, or all accounts.
 import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
 
 runAdapter(async (input) => {

package/library/actions/mobile/wallet/lock.mjs

@@ -1,3 +1,4 @@
+// Lock the wallet through Android native UI and verify the login screen, or accept an already locked wallet.
 import { runAdapter } from '../platform/bridge.mjs';
 import { lockWalletThroughNativeUi } from './native-ui.mjs';
 

package/library/actions/mobile/wallet/native-ui.mjs

@@ -1,3 +1,5 @@
+// Drive Android wallet onboarding, lock, unlock, and reset through native accessibility.
+// Wallet observations can navigate home and open the address list to verify the selected account.
 import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
 import { createAgentDeviceClient } from 'agent-device';
 import {

package/library/actions/mobile/wallet/read_state.mjs

@@ -1,3 +1,5 @@
+// Report the selected account and route from bridge status or native accessibility.
+// Native reads navigate to wallet home and may open the address list to observe the account.
 import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 import { isOpaqueMobileRuntime, readWalletThroughNativeUi } from './native-ui.mjs';
 

package/library/actions/mobile/wallet/reset-helper.mjs

@@ -1,3 +1,4 @@
+// Reset the wallet through bridge-driven login UI and wait for the fresh onboarding control.
 import {
   bridgeCommand,
   selectBridgeStatusEntry,

package/library/actions/mobile/wallet/reset.mjs

@@ -1,3 +1,4 @@
+// Reset the wallet through visible UI and verify fresh onboarding using the bridge or native accessibility.
 import { runAdapter } from '../platform/bridge.mjs';
 import { resetMobileWalletThroughUi } from './reset-helper.mjs';
 import { isOpaqueMobileRuntime, resetWalletThroughNativeUi } from './native-ui.mjs';

package/library/actions/mobile/wallet/select_account.mjs

@@ -1,3 +1,5 @@
+// Select a wallet account by address, ID, or name and verify the resulting selection.
+// Observe ambiguous bridge write failures until the deadline without repeating the switch.
 import { pathToFileURL } from 'node:url';
 import {
   bridgeCommand,

package/library/actions/mobile/wallet/setup.mjs

@@ -1,3 +1,5 @@
+// Validate the wallet fixture, run the Mobile setup script, and verify a selected account.
+// Unlock with the fixture password when setup leaves no selected account observable.
 import { readFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';

package/library/actions/shared/analytics/assert_events.mjs

@@ -1,3 +1,6 @@
+// Assert captured event counts and property values within the requested flow window.
+// Observe the settling interval before deciding whether duplicate emissions occurred.
+
 import { runAdapter } from './_adapter.mjs';
 import { readCollected } from './collector.mjs';
 

package/library/actions/shared/analytics/consent.mjs

@@ -1,3 +1,6 @@
+// Normalize analytics consent inputs and reject marketing consent without participation.
+// This helper validates options; platform actions perform the settings changes.
+
 export function consentParams(node) {
   const optional = (value, fallback) =>
     value === undefined || value === null || value === '' ? fallback : value;

package/library/actions/shared/analytics/read_events.mjs

@@ -1,3 +1,5 @@
+// Read checkout-local collected analytics events, optionally filtered by cursor and event name.
+
 import { runAdapter } from './_adapter.mjs';
 import { readCollected } from './collector.mjs';
 

package/library/actions/shared/analytics/start_capture.mjs

@@ -1,3 +1,6 @@
+// Start or reuse the local analytics collector and return a cursor for this flow.
+// Client routing and consent must be configured separately.
+
 import { runAdapter } from './_adapter.mjs';
 import { startCollector } from './collector.mjs';
 

package/library/actions/shared/app/network-artifact.mjs

@@ -1,3 +1,5 @@
+// Resolve a network-evidence path without allowing it to escape the run's artifact directory.
+
 import path from 'node:path';
 
 export function resolveNetworkArtifact(artifactsDir, relativePath) {

package/library/actions/shared/app/network-assert.mjs

@@ -1,3 +1,5 @@
+// Validate a captured network summary and assert requested status and request-count bounds.
+
 import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
 

package/library/actions/shared/assets/visible-state.mjs

@@ -1,3 +1,5 @@
+// Normalize platform asset observations and enforce symbol, count and display requirements.
+
 function boundedInteger(value, fallback, minimum, maximum, name) {
   const resolved = value == null ? fallback : Number(value);
   if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {

package/library/actions/shared/deeplink/url.mjs

@@ -1,3 +1,6 @@
+// Validate external HTTPS deeplink inputs and their bounded timeout.
+// Signature authorization belongs to the receiving product, not this URL-shape check.
+
 export function externalDeeplinkUrl(node) {
   const raw = node?.url;
   if (typeof raw !== 'string' || raw.trim().length === 0) {

package/library/actions/shared/networks/visible-state.mjs

@@ -1,3 +1,5 @@
+// Normalize network observations and compare asset state across the requested observation window.
+
 import {
   normalizeVisibleAssetsState,
   resolveVisibleAssetsOptions,

package/library/actions/shared/perps/visible-state.mjs

@@ -1,3 +1,5 @@
+// Normalize platform Perps observations and enforce the requested screen, content and count claims.
+
 const SURFACES = new Set([
   'auto',
   'home',

package/library/actions/shared/swap-bridge/transaction.mjs

@@ -1,3 +1,6 @@
+// Validate cross-platform swap asset selections and positive amounts, including decimal normalization.
+// Platform actions perform the actual form changes and submission.
+
 function requiredText(value, name) {
   const resolved = String(value ?? '').trim();
   if (!resolved) throw new Error(`metamask.swap_bridge ${name} is required.`);

package/library/actions/shared/swap-bridge/visible-state.mjs

@@ -1,3 +1,5 @@
+// Normalize observed swap controls and enforce token, quote, settings and slippage requirements.
+
 function text(value) {
   if (typeof value !== 'string') return undefined;
   const normalized = value.replace(/\s+/gu, ' ').trim();

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

@@ -1,3 +1,5 @@
+// Rank locator suggestions from observed interactive elements and enforce observation visibility.
+
 const LOCATOR_LIMIT = 20;
 const INTERACTIVE_ROLE_PARTS = [
   'button',

package/library/actions/shared/wallet/import-source.mjs

@@ -1,3 +1,6 @@
+// Resolve wallet-import credentials from explicit environment or fixture sources.
+// Validate method/source combinations before platform onboarding runs.
+
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 

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

@@ -1161,6 +1161,21 @@
       "schema": {
         "type": "object",
         "properties": {
+          "expected_positions": {
+            "type": "array",
+            "maxItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["coin", "size", "entryPrice"],
+              "properties": {
+                "coin": { "type": "string" },
+                "size": { "type": ["string", "number"] },
+                "entryPrice": { "type": ["string", "number"] }
+              },
+              "additionalProperties": true
+            },
+            "description": "Optional seed receipt guard. Require the selected live market, signed size and entry price to match before dispatch; close at most that quantity in its reducing direction. Empty requires no selected position. Identical netted replacements cannot be distinguished."
+          },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."
@@ -1569,6 +1584,11 @@
       "schema": {
         "type": "object",
         "properties": {
+          "expected_order_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Optional exact receipt set. Refuse a changed selected order set before dispatch and cancel only these IDs. Empty requires no selected open orders."
+          },
           "account": {
             "type": "string",
             "description": "Wallet fixture account name used for signing; defaults to dev1."

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

@@ -593,7 +593,7 @@
               "string",
               "number"
             ],
-            "description": "Text or a typed numeric recipe parameter; numbers are entered as their decimal text."
+            "description": "Text or a typed numeric recipe parameter; numbers are entered as their decimal text. Use an empty string to clear the field."
           },
           "text": {
             "type": "string"
@@ -4191,7 +4191,7 @@
           "from_current_form": {
             "type": "boolean",
             "default": false,
-            "description": "Submit the already configured visible form once without navigation, field edits, or controller placement. Requires an empty position/order baseline, verified provider/network, matching market/direction/amount/leverage, and trusted funding. Preserves the current protection settings and observes the product's resulting route."
+            "description": "Submit the already configured visible form once without navigation, field edits, or controller placement. Requires an empty position/order baseline, verified provider/network, matching market/direction/amount/leverage, and trusted funding. Prepared limit sizing currently requires 1x leverage. Preserves the current protection settings and observes the product's resulting route."
           },
           "market": {
             "type": "string",

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

@@ -1814,7 +1814,7 @@
       "execution_capabilities": ["host-read-export"]
     },
     "metamask.assets.verify_sorting": {
-      "description": "Select alphabetical and declining-fiat token sorting and assert the visible native row order.",
+      "description": "Verify native name order under MetaMask's SES collation and declining-fiat order, then restore the original sort preference.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3299,7 +3299,7 @@
       "execution_capabilities": ["app-mutation"]
     },
     "metamask.perps.ensure_mode": {
-      "description": "Ensure the viewport-visible Perps market-detail root is Lite or Pro. The action presses the active mode control at most once and fails closed if that press opens another chooser or does not converge directly.",
+      "description": "Ensure the viewport-visible Perps market-detail root is Lite or Pro. Press the active mode control at most once and select the requested first-entry choice if shown; fail if the requested detail root does not appear before the deadline.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3341,7 +3341,7 @@
           },
           "account": {
             "type": "string",
-            "description": "Optional exact account name. Omit it to keep the currently selected account."
+            "description": "Optional exact account name or EVM address. Prefer an address when the current product does not expose account names. Omit it to keep the currently selected account."
           },
           "provider": {
             "type": "string",

package/library/recipes/mobile/app/{lifecycle.android-smoke.recipe.json → lifecycle-smoke.recipe.json}

@@ -1,11 +1,16 @@
 {
   "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
-  "title": "MetaMask Mobile Android lifecycle smoke",
-  "description": "Cold-launch the installed Android dev client, verify its bridge, unlock the fixture-backed wallet, then prove same-process background/foreground recovery and capture the final app state. Requires a source-dev runtime; does not rebuild or reset wallet data.",
+  "title": "MetaMask Mobile lifecycle smoke",
+  "description": "Cold-launch the installed dev client on the selected Android device or iOS simulator, verify its bridge, unlock the fixture-backed wallet, then prove same-process background/foreground recovery and capture the final app state. Requires a source-dev runtime; does not rebuild or reset wallet data.",
   "paramsSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {
+      "capture_path": {
+        "type": "string",
+        "default": "screenshots/app-lifecycle-smoke.png",
+        "description": "Use a distinct path when composing repeated lifecycle checks."
+      },
       "runtime_ready_timeout_ms": {
         "type": "integer",
         "minimum": 1000,
@@ -19,20 +24,18 @@
     "nodes": {
       "background-app": {
         "action": "app.lifecycle",
-        "platform": "android",
         "command": "background",
         "settle_ms": 1000,
         "require_process_continuity": true,
-        "intent": "Put the selected Android device on the launcher",
+        "intent": "Background the selected app without terminating its process",
         "next": "foreground-app"
       },
       "foreground-app": {
         "action": "app.lifecycle",
-        "platform": "android",
         "command": "foreground",
         "runtime_ready_timeout_ms": "{{params.runtime_ready_timeout_ms}}",
         "require_process_continuity": true,
-        "intent": "Resume the installed Android app in the same process and await its selected bridge",
+        "intent": "Resume the selected app in the same process and await its bridge",
         "next": "bridge-after"
       },
       "bridge-after": {
@@ -43,7 +46,7 @@
       },
       "screenshot-after": {
         "action": "ui.screenshot",
-        "path": "screenshots/app.lifecycle.android-smoke.png",
+        "path": "{{params.capture_path}}",
         "intent": "Record the foreground app state as evidence",
         "next": "end"
       },
@@ -69,18 +72,16 @@
       },
       "launch-before": {
         "action": "app.lifecycle",
-        "platform": "android",
         "command": "launch",
         "runtime_ready_timeout_ms": "{{params.runtime_ready_timeout_ms}}",
-        "intent": "Launch the installed Android app through the Expo dev-client deep link from a cold process",
+        "intent": "Launch the selected app through the Expo dev-client deep link from a cold process",
         "next": "bridge-before"
       },
       "terminate-before": {
         "action": "app.lifecycle",
-        "platform": "android",
         "command": "terminate",
         "settle_ms": 3000,
-        "intent": "Terminate the installed Android app before lifecycle smoke",
+        "intent": "Terminate the selected app before lifecycle smoke",
         "next": "launch-before"
       }
     }

package/package.json

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