@deeeed/metamask-harness 0.26.5 → 0.28.0

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": [
@@ -3044,5 +3062,29 @@
         "additionalProperties": false
       }
     }
-  }
+  },
+  "observers": [
+    {
+      "ref": "ui.screen",
+      "default_for": [
+        "ui.navigate",
+        "ui.press",
+        "ui.screenshot",
+        "ui.scroll",
+        "ui.set_input",
+        "ui.wait_for"
+      ]
+    },
+    {
+      "ref": "ui.visible",
+      "default_for": [
+        "ui.navigate",
+        "ui.press",
+        "ui.screenshot",
+        "ui.scroll",
+        "ui.set_input",
+        "ui.wait_for"
+      ]
+    }
+  ]
 }

package/package.json

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