@deeeed/metamask-harness 0.27.0 → 0.29.0

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

@@ -1,26 +1,8 @@
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { readWalletStateExpression } from './state.mjs';
 
 runAdapter((input) => withExtensionPage(input, async (page) => {
-  const state = await page.evaluate(`(() => {
-    const passwordInput = Boolean(document.querySelector('input[type="password"]'));
-    const hooks = globalThis.stateHooks;
-    const store = hooks && hooks.store;
-    const root = store && typeof store.getState === 'function' ? store.getState() : {};
-    const metamask = root.metamask || {};
-    const internal = metamask.internalAccounts || {};
-    const accounts = internal.accounts || {};
-    const selectedId = internal.selectedAccount || null;
-    const selected = selectedId && accounts[selectedId] ? accounts[selectedId] : null;
-    return {
-      href: String(globalThis.location && globalThis.location.href || ''),
-      passwordInput,
-      completedOnboarding: Boolean(metamask.completedOnboarding),
-      selectedAccount: selected ? {
-        id: selectedId,
-        address: selected.address || null,
-      } : null,
-    };
-  })()`);
+  const state = await page.evaluate(readWalletStateExpression(), { awaitPromise: true });
   const seededProfilePresent = Boolean(state?.passwordInput || (state?.completedOnboarding && state?.selectedAccount?.address));
   if (!seededProfilePresent) {
     throw new Error(`Extension fixture profile is not ready; expected a locked password screen or completed onboarding with a selected account, got ${JSON.stringify(state)}`);

package/library/actions/extension/wallet/state.mjs

@@ -0,0 +1,111 @@
+const walletStatePreamble = `
+    const readWalletState = async () => {
+      const hooks = globalThis.stateHooks || {};
+      let root = null;
+      if (typeof hooks.getCleanAppState === 'function') {
+        root = await hooks.getCleanAppState();
+      }
+      if ((!root || typeof root !== 'object') && typeof hooks.store?.getState === 'function') {
+        root = hooks.store.getState();
+      }
+      if (!root || typeof root !== 'object') {
+        throw new Error('stateHooks.getCleanAppState and stateHooks.store.getState are unavailable.');
+      }
+      const metamask = root.metamask || root;
+      return {
+        hooks,
+        metamask,
+        internal: metamask.internalAccounts || {},
+      };
+    };
+`;
+
+export function readWalletStateExpression() {
+  return `(async () => {
+    ${walletStatePreamble}
+    const { metamask, internal } = await readWalletState();
+    const accounts = internal.accounts || {};
+    const selectedId = internal.selectedAccount || null;
+    const selected = selectedId && accounts[selectedId] ? accounts[selectedId] : null;
+    const metadata = selected?.metadata || {};
+    return {
+      href: String(globalThis.location?.href || ''),
+      passwordInput: Boolean(globalThis.document?.querySelector?.('input[type="password"]')),
+      selectedAccount: selected ? {
+        id: selectedId,
+        address: selected.address || null,
+        name: metadata.name || null,
+        type: selected.type || null,
+      } : null,
+      completedOnboarding: Boolean(metamask.completedOnboarding),
+      selectedNetworkClientId: metamask.selectedNetworkClientId || null,
+    };
+  })()`;
+}
+
+export function listWalletAccountsExpression(scope) {
+  return `(async () => {
+    ${walletStatePreamble}
+    const { internal } = await readWalletState();
+    const selectedId = internal.selectedAccount || null;
+    const scope = ${JSON.stringify(scope)};
+    const accounts = Object.entries(internal.accounts || {})
+      .map(([id, account]) => ({
+        id,
+        address: account?.address || null,
+        name: account?.metadata?.name || null,
+        type: account?.type || null,
+        selected: id === selectedId,
+      }))
+      .filter((account) => {
+        if (scope === 'selected') return account.selected;
+        if (scope === 'all') return true;
+        if (scope === 'evm') return /^0x[0-9a-f]{40}$/iu.test(account.address || '');
+        return account.selected || Boolean(String(account.name || '').trim());
+      });
+    return { accounts };
+  })()`;
+}
+
+export function selectWalletAccountExpression(criteria, timeoutMs = 5000) {
+  return `(async () => {
+    ${walletStatePreamble}
+    const before = await readWalletState();
+    const accounts = before.internal.accounts || {};
+    const requestedAddress = ${JSON.stringify(criteria.address)};
+    const requestedId = ${JSON.stringify(criteria.id)};
+    const requestedName = ${JSON.stringify(criteria.name)};
+    const match = Object.entries(accounts).find(([id, account]) => {
+      const metadata = account?.metadata || {};
+      return (requestedId && id === requestedId) ||
+        (requestedAddress && String(account?.address || '').toLowerCase() === requestedAddress) ||
+        (requestedName && metadata.name === requestedName);
+    });
+    if (!match) throw new Error('Requested account was not found in internalAccounts.');
+    if (typeof before.hooks.submitRequestToBackground !== 'function') {
+      throw new Error('stateHooks.submitRequestToBackground is unavailable.');
+    }
+    const [id] = match;
+    await before.hooks.submitRequestToBackground('setSelectedInternalAccount', [id]);
+    const deadline = Date.now() + ${Number(timeoutMs)};
+    let observedId = before.internal.selectedAccount || null;
+    while (Date.now() <= deadline) {
+      const after = await readWalletState();
+      observedId = after.internal.selectedAccount || null;
+      if (observedId === id) {
+        const selected = after.internal.accounts?.[observedId];
+        return {
+          id: observedId,
+          address: selected?.address || null,
+          name: selected?.metadata?.name || null,
+          type: selected?.type || null,
+        };
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(
+      'Expected selected account ' + id + ', got ' + String(observedId) +
+      ' after ${Number(timeoutMs)}ms.',
+    );
+  })()`;
+}

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

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
+import { bridgeCommand } from './bridge.mjs';
 import { mobileToolRecovery, resolveMobileToolPath } from './tool-paths.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -8,6 +9,7 @@ const VISIBLE_LIMIT = 50;
 const HIDDEN_LIMIT = 50;
 
 export async function observeNativeUi(payload, context) {
+  await hideAccessibilityMaskingHud(payload, context);
   const refs = Array.isArray(payload?.refs)
     ? payload.refs.filter((ref) => typeof ref === 'string')
     : [];
@@ -38,6 +40,25 @@ export async function observeNativeUi(payload, context) {
   }
 }
 
+async function hideAccessibilityMaskingHud(payload, context) {
+  try {
+    await bridgeCommand(
+      {
+        action: 'ui.observe',
+        node: {
+          ...record(payload),
+          bridge_timeout_ms: 2_000,
+          cdp_timeout_ms: 2_000,
+        },
+        context,
+      },
+      ['hide-step'],
+    );
+  } catch {
+    // Native observation remains warning-only when the separate iOS HUD window is unavailable.
+  }
+}
+
 async function readNativeHierarchy(payload, context) {
   const node = record(payload?.node);
   const env = {

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

@@ -0,0 +1,17 @@
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+import { runAdapter } from '../platform/bridge.mjs';
+import {
+  locatorsFromObservation,
+  requireVisibleObservation,
+} from '../../shared/ui/locators.mjs';
+
+runAdapter(async (input) => {
+  const observed = await observeNativeUi(
+    { refs: ['ui.visible'], node: input.node },
+    input.context,
+  );
+  return {
+    action: input.action,
+    ...locatorsFromObservation(requireVisibleObservation(observed)),
+  };
+});

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

@@ -0,0 +1,160 @@
+const LOCATOR_LIMIT = 20;
+const INTERACTIVE_ROLE_PARTS = [
+  'button',
+  'textfield',
+  'edittext',
+  'searchfield',
+  'textarea',
+  'checkbox',
+  'radiobutton',
+  'switch',
+  'togglebutton',
+  'slider',
+  'seekbar',
+  'picker',
+  'spinner',
+  'link',
+  'tab',
+  'menuitem',
+  'cell',
+];
+
+export function locatorsFromObservation(observation) {
+  const value = record(observation);
+  const items = Array.isArray(value.items) ? value.items.map(record) : [];
+  const ranked = items
+    .filter(isInteractive)
+    .map(locatorFor)
+    .filter((locator) => locator.suggestions.length > 0)
+    .sort((left, right) => {
+      const leftBest = left.suggestions[0];
+      const rightBest = right.suggestions[0];
+      return (
+        confidenceRank(leftBest?.confidence) - confidenceRank(rightBest?.confidence) ||
+        strategyRank(leftBest?.strategy) - strategyRank(rightBest?.strategy)
+      );
+    });
+  const locators = ranked.slice(0, LOCATOR_LIMIT);
+  return {
+    provider: text(value.provider) ?? 'unknown',
+    observed: items.length,
+    count: locators.length,
+    truncated: value.truncated === true || ranked.length > locators.length,
+    locators,
+  };
+}
+
+export function requireVisibleObservation(result) {
+  const value = record(result);
+  const observations = record(value.observations);
+  const visible = observations['ui.visible'];
+  if (visible && typeof visible === 'object' && !Array.isArray(visible)) {
+    return visible;
+  }
+  const warning = Array.isArray(value.warnings)
+    ? value.warnings.map((entry) => text(record(entry).message)).find(Boolean)
+    : undefined;
+  throw new Error(
+    `ui.locators could not read the current ui.visible observation${warning ? `: ${warning}` : '.'}`,
+  );
+}
+
+function isInteractive(item) {
+  const role = text(item.role)?.toLowerCase() ?? '';
+  return (
+    Boolean(text(item.selector)) ||
+    INTERACTIVE_ROLE_PARTS.some((part) => role.includes(part)) ||
+    (item.enabled !== false && Boolean(text(item.test_id)))
+  );
+}
+
+function locatorFor(item) {
+  const testId = text(item.test_id);
+  const label = text(item.label);
+  const selector = text(item.selector);
+  const role = text(item.role);
+  const suggestions = [];
+  if (testId) {
+    suggestions.push({
+      strategy: 'test_id',
+      value: testId,
+      confidence: 'high',
+      params: { test_id: testId },
+    });
+  }
+  if (label && supportsTextTarget(role)) {
+    suggestions.push({
+      strategy: 'label',
+      value: label,
+      confidence: testId ? 'medium' : 'high',
+      params: { text: label },
+    });
+  }
+  if (selector && !selectorRepresentsTestId(selector, testId)) {
+    suggestions.push({
+      strategy: 'selector',
+      value: selector,
+      confidence: stableSelector(selector) ? 'high' : 'low',
+      params: { selector },
+    });
+  }
+  suggestions.sort((left, right) => (
+    confidenceRank(left.confidence) - confidenceRank(right.confidence) ||
+    strategyRank(left.strategy) - strategyRank(right.strategy)
+  ));
+  return {
+    description: describe(item),
+    role,
+    enabled: item.enabled !== false,
+    bounds: bounds(item.bounds),
+    suggestions,
+  };
+}
+
+function supportsTextTarget(role) {
+  const normalized = role?.toLowerCase() ?? '';
+  return ['button', 'link', 'tab', 'menuitem', 'cell'].some((part) =>
+    normalized.includes(part));
+}
+
+function describe(item) {
+  const parts = [text(item.role) ?? 'element'];
+  if (text(item.label)) parts.push(`label=${JSON.stringify(text(item.label))}`);
+  if (text(item.test_id)) parts.push(`test_id=${JSON.stringify(text(item.test_id))}`);
+  return parts.join(' ');
+}
+
+function bounds(value) {
+  const candidate = record(value);
+  const keys = ['x', 'y', 'width', 'height'];
+  if (!keys.every((key) => Number.isFinite(candidate[key]))) return undefined;
+  return Object.fromEntries(keys.map((key) => [key, candidate[key]]));
+}
+
+function selectorRepresentsTestId(selector, testId) {
+  return Boolean(testId && selector.includes('data-test') && selector.includes(testId));
+}
+
+function stableSelector(selector) {
+  return /^\[(?:id|data-test(?:id|-id))=/u.test(selector);
+}
+
+function confidenceRank(value) {
+  if (value === 'high') return 0;
+  if (value === 'medium') return 1;
+  return 2;
+}
+
+function strategyRank(value) {
+  if (value === 'test_id') return 0;
+  if (value === 'selector') return 1;
+  return 2;
+}
+
+function text(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}

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

@@ -716,6 +716,24 @@
         }
       ]
     },
+    "ui.locators": {
+      "description": "List ranked, copy-pasteable ui.press targets from the current ui.visible observation. Prefer high-confidence test IDs when updating durable recipe source after exploratory interaction.",
+      "execution_capabilities": [
+        "host-read-export"
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "ui.locators",
+          "intent": "Find stable targets for durable recipe authoring.",
+          "next": "done"
+        }
+      ]
+    },
     "ui.screenshot": {
       "description": "Capture registered visual evidence through capture-helper, bounded Chrome-native capture, or an explicitly labeled computed-style DOM raster fallback. Always read the resulting PNG; artifact metadata records the provider.",
       "examples": [

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

@@ -734,6 +734,24 @@
         }
       ]
     },
+    "ui.locators": {
+      "description": "List ranked, copy-pasteable ui.press targets from the current ui.visible observation. Prefer high-confidence test IDs when updating durable recipe source after exploratory interaction.",
+      "execution_capabilities": [
+        "host-read-export"
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "ui.locators",
+          "intent": "Find stable targets for durable recipe authoring.",
+          "next": "done"
+        }
+      ]
+    },
     "ui.screenshot": {
       "description": "Capture registered PNG evidence with xcrun simctl on iOS or adb screencap on Android. Artifact metadata records the native provider, command mode, and selected device; invalid or empty PNG output fails before registration.",
       "examples": [

package/library/recipes/runner/action-validation.extension.recipe.json

@@ -7,7 +7,7 @@
     "nodes": {
       "prepare-files": {
         "action": "command",
-        "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION extension\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"extension\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'extension log E2E_ACTION_VALIDATION\\n' > temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION extension",
+        "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION extension\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"extension\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'extension log E2E_ACTION_VALIDATION\\n' >> temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION extension",
         "next": "assert-command-exit",
         "intent": "Prepare runner.action-validation probe files"
       },

package/library/recipes/runner/action-validation.mobile.recipe.json

@@ -7,7 +7,7 @@
     "nodes": {
       "prepare-files": {
         "action": "command",
-        "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION mobile\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"mobile\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'mobile log E2E_ACTION_VALIDATION\\n' > temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION mobile",
+        "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION mobile\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"mobile\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'mobile log E2E_ACTION_VALIDATION\\n' >> temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION mobile",
         "next": "assert-command-exit",
         "intent": "Prepare runner.action-validation probe files"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -13,16 +13,17 @@
     "test:unit": "vitest run --config scripts/vitest.config.mjs",
     "test:coverage": "vitest run --coverage --config scripts/vitest.config.mjs",
     "qa:human": "node scripts/validate-human-outcomes.mjs",
+    "site:contrast": "node scripts/site-contrast.mjs",
     "self-test": "bin/mm-harness self-test",
     "manifest:mobile": "bin/mm-harness actions --raw --adapter mobile --json",
     "manifest:extension": "bin/mm-harness actions --raw --adapter extension --json",
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "^0.4.0",
+    "@farmslot/agent-runtime": "^0.5.0",
     "@farmslot/handoff": "^0.3.1",
-    "@farmslot/protocol": "^0.14.0",
-    "@farmslot/recipe-harness": "^0.10.4",
+    "@farmslot/protocol": "^0.15.0",
+    "@farmslot/recipe-harness": "^0.11.0",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",
     "esbuild": "0.28.1",
@@ -61,8 +62,10 @@
     "dist",
     "adapters",
     "library",
+    "site",
     "scripts/completions.sh",
     "scripts/install-completions.sh",
+    "scripts/site-contrast.mjs",
     "scripts/validate-human-outcomes.mjs",
     "!scripts/README.md",
     "docs",