@deeeed/metamask-harness 0.47.4 → 0.49.0

package/library/actions/mobile/networks/remove_custom.mjs

@@ -1,3 +1,4 @@
+// Delete a custom network through native Settings and wait for its row to disappear.
 import { runAdapter } from '../platform/bridge.mjs';
 import {
   closeNativeSession,
@@ -32,6 +33,8 @@ runAdapter(async (input) => {
       (snapshot) => {
         const container = nativeNode(snapshot, 'network-details-view-container');
         if (!container) return null;
+        const remove = nativeNode(snapshot, 'network-details-view-remove-network-button');
+        if (remove?.enabled === true && remove.visibleToUser !== false && remove.hittable === true) return remove;
         const labeled = snapshot.nodes.find((node) =>
           node.hittable === true && /delete|remove|trash/iu.test(nativeLabel(node))
         );
@@ -84,8 +87,10 @@ runAdapter(async (input) => {
       (snapshot) => nativeNode(snapshot, 'networks-settings-container'),
       'Mobile Networks settings did not reopen after deletion.',
     );
-    if (await findNetwork(session, network, chainId, timeoutMs)) {
-      throw new Error(`${network} (${chainId}) remained after deletion.`);
+    const removalDeadline = Date.now() + timeoutMs;
+    while (await findNetwork(session, network, chainId, Math.max(1, removalDeadline - Date.now()))) {
+      if (Date.now() >= removalDeadline) throw new Error(`${network} (${chainId}) remained after deletion.`);
+      await new Promise((resolve) => setTimeout(resolve, 250));
     }
     return {
       action: input.action,

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

@@ -1,3 +1,4 @@
+// Assert that selected Perps orders are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Assert that selected Perps positions are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Start or end a Perps performance log capture, writing artifacts and checking required events at end.
 import { runAdapter } from '../platform/bridge.mjs';
 import { capturePerpsPerformance } from './performance-capture.mjs';
 

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

@@ -1,3 +1,4 @@
+// Cancel selected Perps orders through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders, closeOrders } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Close selected Perps positions through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions, closePositions } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Create a limit order when none matches, or cancel selected orders, then assert the requested state.
 import { runAdapter } from '../platform/bridge.mjs';
 import { ensureOrders } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Submit an order when no position matches, or close selected positions, then assert the requested state.
 import { runAdapter } from '../platform/bridge.mjs';
 import { ensurePositions } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Unlock the wallet and measure the scroll transition until a requested homepage target becomes visible.
 import { runAdapter } from '../platform/bridge.mjs';
 import { measureHomepageVisible } from './perps.mjs';
 

package/library/actions/mobile/perps/performance-capture.mjs

@@ -1,3 +1,5 @@
+// Capture a bounded section of Perps console logs and write performance measurements and validation artifacts.
+// Persist the start offset and file identity to reject replaced or rewritten logs when the capture ends.
 import { createHash } from "node:crypto";
 import { mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";

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

@@ -1,3 +1,5 @@
+// Implement Mobile Perps navigation, trading mutations, assertions, and setup or cleanup through the bridge.
+// Strategy getters used during cleanup can settle tracked collateral.
 import { pathToFileURL } from 'node:url';
 import {
   MOBILE_BRIDGE_RESULT_ERROR_CODES,
@@ -1770,6 +1772,9 @@ async function applyTutorialState(input, config) {
 
 
 export async function startState(input) {
+  if (input.node?.account !== undefined && (typeof input.node.account !== 'string' || !input.node.account.trim())) {
+    throw new Error('Perps start state requires a non-empty account name or address when account is supplied.\nNext: mm-harness actions metamask.perps.start_state --adapter mobile --json');
+  }
   const params = paramsForState(input);
   const config = applyTradingStatePolicy(
     mergeStateConfig(profileDefaults(params.profile), params),
@@ -1828,7 +1833,9 @@ export async function startState(input) {
       node: {
         ...accountInput.node,
         action: 'metamask.wallet.select_account',
-        name: config.account.trim(),
+        ...(/^0x[0-9a-f]{40}$/iu.test(config.account.trim())
+          ? { address: config.account.trim() }
+          : { name: config.account.trim() }),
       },
     })
     : { skipped: true };

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

@@ -1,3 +1,4 @@
+// Submit a Perps order through the Mobile controller and assert a matching open position.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions, placeOrder } from './perps.mjs';
 runAdapter(async (input) => {

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

@@ -1,3 +1,5 @@
+// Apply and verify an adb reverse mapping for a local snapshot port on the selected Android device.
+// Skip the mapping when no Android serial is configured.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 

package/library/actions/mobile/perps/read-visible-state-loop.mjs

@@ -1,3 +1,5 @@
+// Poll native screen and accessibility observations until Perps state satisfies the requested checks.
+// Return normalized state or report the last assertion or observation failure at the deadline.
 import { observeNativeUi } from '../platform/observe-ui.mjs';
 import {
   normalizeVisiblePerpsState,
@@ -47,6 +49,7 @@ export async function readVisiblePerpsState(
             truncated: visible.truncated,
           }, options, 'mobile'),
           proofPath: 'native-accessibility',
+          observationProvider: visible.provider,
         };
       } catch (error) {
         lastAssertionError = error;

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

@@ -1,3 +1,4 @@
+// Return selected open Perps orders with redacted fields and counts from the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { readOrders } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Return selected Perps positions with redacted fields and counts from the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { readPerpsPositions } from './perps.mjs';
 runAdapter(readPerpsPositions);

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

@@ -1,3 +1,4 @@
+// Read Perps state from native accessibility observations, waiting for requested assertions to pass.
 import { runAdapter } from '../platform/bridge.mjs';
 import { readVisiblePerpsState } from './read-visible-state-loop.mjs';
 

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,
@@ -11,7 +13,14 @@ const FAVORITE_IDS = [
   'perps-pro-market-header-favorite-button',
 ];
 
-function favoriteControl(snapshot) {
+function favoriteControl(snapshot, market) {
+  const subtitle = nativeLabel(
+    nativeNode(snapshot, 'perps-market-header-subtitle')
+    ?? nativeNode(snapshot, 'perps-pro-market-header-subtitle'),
+  ).toUpperCase();
+  if (!subtitle.startsWith(`${market}-`)) {
+    throw new Error(`Visible Perps market ${JSON.stringify(subtitle)} does not match ${market}.`);
+  }
   for (const testId of FAVORITE_IDS) {
     const node = nativeNode(snapshot, testId);
     if (/(?:add to|remove from) watchlist/iu.test(nativeLabel(node))) {
@@ -39,18 +48,11 @@ runAdapter(async (input) => {
   if (typeof desired !== 'boolean') {
     throw new Error('metamask.perps.set_market_favorite requires favorite=true or false.');
   }
-  let session = createNativeSession(input, 'Perps', `favorite-${process.pid}`);
+  const session = createNativeSession(input, 'Perps', `favorite-${process.pid}`);
   try {
     await session.open();
     let snapshot = await session.snapshot();
-    const subtitle = nativeLabel(
-      nativeNode(snapshot, 'perps-market-header-subtitle')
-      ?? nativeNode(snapshot, 'perps-pro-market-header-subtitle'),
-    ).toUpperCase();
-    if (!subtitle.startsWith(`${market}-`)) {
-      throw new Error(`Visible Perps market ${JSON.stringify(subtitle)} does not match ${market}.`);
-    }
-    let control = favoriteControl(snapshot);
+    let control = favoriteControl(snapshot, market);
     const controlDeadline = Date.now() + timeoutMs;
     let lastControls = [];
     while (Date.now() <= controlDeadline && !control) {
@@ -60,37 +62,33 @@ runAdapter(async (input) => {
         .filter((node) => /(?:favorite|mode-toggle|market-header)/iu.test(String(node.identifier ?? '')))
         .map((node) => ({ id: String(node.identifier ?? ''), label: nativeLabel(node) }))
         .slice(0, 20);
-      control = favoriteControl(snapshot);
+      control = favoriteControl(snapshot, market);
     }
     if (!control) {
       throw new Error(`Perps favorite control is not visible in Lite or Pro mode; observed ${JSON.stringify(lastControls)}.`);
     }
     const before = favoriteState(control);
+    if (requireUnchanged && before !== desired) {
+      throw new Error(`Perps favorite state for ${market} did not persist across navigation; no change was made.`);
+    }
     if (before !== desired) {
       await session.execute('ui.press', {
         test_id: control.testId,
         timeout_ms: timeoutMs,
         settle: false,
       });
-      await closeNativeSession(session);
-      await new Promise((resolve) => setTimeout(resolve, 500));
-      session = createNativeSession(input, 'Perps', `favorite-proof-${process.pid}`);
-      await session.open();
     }
     const deadline = Date.now() + timeoutMs;
     let after = before;
     while (Date.now() <= deadline) {
       snapshot = await session.snapshot();
-      control = favoriteControl(snapshot);
+      control = favoriteControl(snapshot, market);
       if (control) after = favoriteState(control);
       if (after === desired) break;
       await new Promise((resolve) => setTimeout(resolve, 200));
     }
     if (after !== desired) throw new Error(`Perps favorite state did not become ${desired}.`);
     const changed = before !== after;
-    if (requireUnchanged && changed) {
-      throw new Error(`Perps favorite state for ${market} did not persist across navigation.`);
-    }
     return {
       action: input.action,
       market,

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,6 +1,11 @@
+// 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';
 
+import { resolveMobileTarget } from './bridge.mjs';
+import { hideAccessibilityMaskingHud } from './observe-ui.mjs';
+
 import {
   nativeAgentDeviceStateDir,
   nativeSessionName,
@@ -8,17 +13,27 @@ import {
 
 export function createNativeSession(input, domain, sessionSuffix = '') {
   const env = { ...process.env, ...(input.context?.env ?? {}) };
-  const device = String(env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? '').trim();
-  if (!device) throw new Error(`Mobile ${domain} native actions require one explicit Android device serial.`);
-  const app = String(env.ANDROID_PACKAGE_ID ?? 'io.metamask');
+  const target = resolveMobileTarget(input);
+  const platform = target.requestedPlatform || (target.adbSerial ? 'android' : 'ios');
+  const device = String(platform === 'android'
+    ? target.adbSerial ?? ''
+    : input.node?.sim_udid ?? env.SIM_UDID ?? target.iosSimulator ?? '').trim();
+  if (!device) throw new Error(`Mobile ${domain} native actions require one explicit ${platform} device. Next: pass --device <device>.`);
+  const app = String(platform === 'android'
+    ? env.ANDROID_PACKAGE_ID ?? 'io.metamask'
+    : env.IOS_BUNDLE_ID ?? 'io.metamask.MetaMask');
   const baseSession = nativeSessionName(env, device, app);
   const session = sessionSuffix
     ? `${baseSession}-${String(sessionSuffix).replace(/[^A-Za-z0-9._-]/gu, '-')}`.slice(0, 120)
     : baseSession;
   const stateDir = nativeAgentDeviceStateDir(env, input.context.projectRoot, device);
-  const client = createAgentDeviceClient({ session, stateDir, lockPolicy: 'reject', lockPlatform: 'android' });
-  const selection = { platform: 'android', target: 'mobile', serial: device, session };
-  const transport = createAgentDeviceUiTransport({ platform: 'android', device, app, session, stateDir, client });
+  const client = createAgentDeviceClient({ session, stateDir, lockPolicy: 'reject', lockPlatform: platform });
+  const selection = {
+    platform, target: 'mobile', session,
+    ...(platform === 'android' ? { serial: device }
+      : /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(device) ? { udid: device } : { device }),
+  };
+  const transport = createAgentDeviceUiTransport({ platform, device, app, session, stateDir, client });
   const context = {
     nodeId: String(input.context?.nodeId ?? 'action'),
     projectRoot: input.context.projectRoot,
@@ -31,23 +46,19 @@ export function createNativeSession(input, domain, sessionSuffix = '') {
     selection,
     context,
     app,
-    open: () => client.apps.open({ ...selection, app, noRecord: true }),
+    open: async () => {
+      if (platform === 'ios' && env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME !== '1') {
+        await hideAccessibilityMaskingHud({ node: input.node }, input.context);
+      }
+      await transport.open();
+    },
     execute: (action, node) => transport.execute(action, node, context),
     snapshot: () => client.capture.snapshot({ ...selection, app, interactiveOnly: false, forceFull: true }),
   };
 }
 
 export async function closeNativeSession(session) {
-  try {
-    await session.transport.close();
-  } catch (error) {
-    if (!/No active session|SESSION_NOT_FOUND/iu.test(String(error?.message ?? error))) throw error;
-  }
-  try {
-    await session.client.sessions.close();
-  } catch (error) {
-    if (!/No active session|SESSION_NOT_FOUND/iu.test(String(error?.message ?? error))) throw error;
-  }
+  await session.transport.close();
 }
 
 export function nativeNode(snapshot, identifier) {

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';
@@ -45,7 +47,7 @@ export async function observeNativeUi(payload, context) {
   }
 }
 
-async function hideAccessibilityMaskingHud(payload, context) {
+export async function hideAccessibilityMaskingHud(payload, context) {
   try {
     await bridgeCommand(
       {
@@ -429,7 +431,7 @@ function parseAndroidHierarchy(output) {
       isActionableRole(role) ||
       attributes.clickable === 'true' ||
       attributes['long-clickable'] === 'true';
-    if (isActionable) {
+    if (isActionable || item.test_id) {
       if (isVisible) {
         visible.push(item);
       } else {

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,
@@ -12,7 +14,7 @@ import {
 const PAGE_ROUTES = {
   home: { route: 'WalletView', params: {} },
   perps: { route: 'PerpsMarketListView', params: {} },
-  'perps-market-list': { route: 'PerpsMarketListView', params: {} },
+  'perps-market-list': { route: 'PerpsTrendingView', params: {} },
   swap: { route: 'BridgeView', params: {} },
 };
 

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,