@deeeed/metamask-harness 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.28.0 - 2026-07-31
+
+### Added
+
+- Add `actions --matrix` and adapter-aware action refusals that name missing capabilities and list the adapters that satisfy them.
+- Add `ui.locators` for ranked, copy-pasteable recipe targets derived from the current Extension or Mobile `ui.visible` observation.
+
 ## 0.27.0 - 2026-07-31
 
 ### Changed

package/dist/adapters.js

@@ -305,17 +305,6 @@ async function handleMobileStatus(payload, context) {
   return bridgeCommand(mobileUiInput(context, "status", payload), ["status"]);
 }
 async function handleMobileObserveUi(payload, context) {
-  try {
-    await bridgeCommand(
-      mobileUiInput(context, "observe", {
-        ...payload,
-        bridge_timeout_ms: 2e3,
-        cdp_timeout_ms: 2e3
-      }),
-      ["hide-step"]
-    );
-  } catch {
-  }
   return observeNativeUi(payload, context);
 }
 async function handleMobileNavigate(payload, context) {

package/dist/cli-commands.js

@@ -15,7 +15,7 @@ const SPEC = {
     { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
-    { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--categories", "--category", "--action", "--library"] },
+    { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--matrix", "--categories", "--category", "--action", "--library"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { name: "execution-template", desc: "Discover and materialize shared agent checklists", args: ["list", "materialize", "lint", "new"], flags: ["--dir", "--domain-dir", "--project-worker", "--project-name", "--package-templates", "--package-id", "--flow", "--run-mode", "--platform", "--domain", "--id", "--provenance", "--include-shadowed", "--no-include-shadowed", "--title", "--force", "--json"] },

package/dist/command-contract.js

@@ -117,6 +117,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
   actions: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
       "--action": value(),
+      "--matrix": bool(),
       "--categories": bool(),
       "--category": value(),
       "--action-manifest": value(),

package/dist/commands/call.js

@@ -6,7 +6,14 @@ import { importRecipeProtocol } from "../paths.js";
 import { conciseFailureForHuman, recipeRunning } from "../heal-bounds.js";
 import { color } from "../cli-color.js";
 import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
-import { actionExampleCommand, describeManifestActions, fuzzyResolveActions } from "./manifest.js";
+import {
+  actionLibraryContextArgs,
+  actionExampleCommand,
+  describeManifestActions,
+  fuzzyResolveActions,
+  resolveActionCapabilityMatrix,
+  resolveActionCapabilityRefusal
+} from "./manifest.js";
 import {
   parseArgs,
   isRecord,
@@ -112,6 +119,36 @@ async function handleCall(argv) {
   const names = getRecipeActionManifestActionNames(manifest);
   const resolution = resolveActionName(shortName, names);
   if (resolution.status === "unknown") {
+    const refusal = actionManifestOverride ? void 0 : resolveActionCapabilityRefusal(
+      shortName,
+      adapter,
+      await resolveActionCapabilityMatrix(librarySources)
+    );
+    if (refusal) {
+      const satisfying = refusal.satisfyingAdapters.join(", ");
+      const message2 = `missing action capability "${refusal.capability}" for the ${adapter} adapter.`;
+      const userAction2 = `Satisfying adapters for "${refusal.capability}": ${satisfying}. Inspect: mm-harness actions --matrix --action ${shellQuote(refusal.capability)}${actionLibraryContextArgs(librarySources)} --json`;
+      const error = {
+        code: "ACTION_CAPABILITY_UNAVAILABLE",
+        message: message2,
+        capability: refusal.capability,
+        satisfyingAdapters: refusal.satisfyingAdapters,
+        userAction: userAction2
+      };
+      if (json) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "call",
+          adapter,
+          action: shortName,
+          error
+        }, null, 2));
+      } else {
+        console.error(`\u2717 call: ${message2}
+  Next: ${userAction2}`);
+      }
+      return EXIT.usage;
+    }
     const message = `unknown action "${shortName}" for the ${adapter} adapter.`;
     const userAction = `mm-harness actions --adapter ${adapter} --json`;
     if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));

package/dist/commands/manifest.js

@@ -18,22 +18,33 @@ import {
 import { metaMaskActionExecutionCapabilities } from "../recipe-security.js";
 import { closest } from "../command-contract.js";
 const OFFICIAL_ACTIONS = new Set(OFFICIAL_RECIPE_ACTIONS);
+const ACTION_MATRIX_ADAPTERS = ["mobile", "extension", "core"];
+function actionLibraryContextArgs(librarySources) {
+  return (librarySources ?? []).filter((source) => source.name !== "metamask").map((source) => {
+    const entry = source.name ? `${source.name}=${source.root}` : source.root;
+    return ` --library ${shellQuoteArg(entry)}`;
+  }).join("");
+}
 async function handleActions({ options, positional }) {
-  const { adapter, target } = resolveAdapter(options);
   const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+  const json = optionFlag(options, "json");
+  const action = optionString(options, "action");
+  const query = positional[0]?.trim();
+  const category = optionString(options, "category")?.toLowerCase();
+  if (optionFlag(options, "matrix")) {
+    return handleActionMatrix(options, { json, action, query, category, librarySources });
+  }
+  const { adapter, target } = resolveAdapter(options);
+  const actionManifestOverride = optionString(options, "actionManifest");
   const { manifest, actionSources } = await resolveActionManifest(
     adapter,
-    optionString(options, "actionManifest"),
+    actionManifestOverride,
     librarySources
   );
   if (optionFlag(options, "raw")) {
     console.log(JSON.stringify(manifest, null, 2));
     return EXIT.ok;
   }
-  const json = optionFlag(options, "json");
-  const action = optionString(options, "action");
-  const query = positional[0]?.trim();
-  const category = optionString(options, "category")?.toLowerCase();
   const categoriesOnly = optionFlag(options, "categories");
   const all = describeManifestActions(manifest, actionSources);
   const categories = summarizeActionCategories(all);
@@ -67,6 +78,36 @@ async function handleActions({ options, positional }) {
   }
   const actions = action ? fuzzyResolveActions(categoryActions, action) : query ? searchActions(categoryActions, query) : categoryActions;
   if (action && actions.length === 0) {
+    const refusal = actionManifestOverride ? void 0 : resolveActionCapabilityRefusal(
+      action,
+      adapter,
+      await resolveActionCapabilityMatrix(librarySources)
+    );
+    if (refusal) {
+      const satisfying = refusal.satisfyingAdapters.join(", ");
+      const message2 = `missing action capability "${refusal.capability}" for the ${adapter} adapter.`;
+      const userAction2 = `Satisfying adapters for "${refusal.capability}": ${satisfying}. Inspect: mm-harness actions --matrix --action ${shellQuoteArg(refusal.capability)}${actionLibraryContextArgs(librarySources)} --json`;
+      if (json) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "actions",
+          adapter,
+          action,
+          category,
+          error: {
+            code: "ACTION_CAPABILITY_UNAVAILABLE",
+            message: message2,
+            capability: refusal.capability,
+            satisfyingAdapters: refusal.satisfyingAdapters,
+            userAction: userAction2
+          }
+        }, null, 2));
+      } else {
+        console.error(`\u2717 mm-harness actions: ${message2}
+  Next: ${userAction2}`);
+      }
+      return EXIT.usage;
+    }
     const message = `no action matches "${action}" for the ${adapter} adapter.`;
     const userAction = `mm-harness actions --adapter ${adapter}`;
     if (json) {
@@ -126,6 +167,154 @@ ${color("label", "Related:", { stream: process.stdout })} ${relatedActions.join(
   }
   return 0;
 }
+async function resolveActionCapabilityMatrix(librarySources) {
+  const catalogs = await Promise.all(
+    ACTION_MATRIX_ADAPTERS.map(async (adapter) => {
+      const { manifest, actionSources } = await resolveActionManifest(
+        adapter,
+        void 0,
+        librarySources
+      );
+      return { adapter, actions: describeManifestActions(manifest, actionSources) };
+    })
+  );
+  const actions = /* @__PURE__ */ new Map();
+  for (const catalog of catalogs) {
+    for (const action of catalog.actions) {
+      const entry = actions.get(action.name) ?? { entries: [], adapters: /* @__PURE__ */ new Set() };
+      entry.entries.push(action);
+      entry.adapters.add(catalog.adapter);
+      actions.set(action.name, entry);
+    }
+  }
+  return [...actions.entries()].map(([name, entry]) => {
+    const representative = entry.entries[0];
+    const satisfyingAdapters = ACTION_MATRIX_ADAPTERS.filter(
+      (adapter) => entry.adapters.has(adapter)
+    );
+    return {
+      name,
+      category: representative.category,
+      description: entry.entries.map((action) => action.description).find(Boolean) ?? "",
+      fields: [...new Set(entry.entries.flatMap((action) => action.fields))].sort(),
+      support: Object.fromEntries(
+        ACTION_MATRIX_ADAPTERS.map((adapter) => [
+          adapter,
+          entry.adapters.has(adapter) ? "available" : "unavailable"
+        ])
+      ),
+      satisfyingAdapters
+    };
+  }).sort((left, right) => left.name.localeCompare(right.name));
+}
+function resolveActionCapabilityRefusal(action, adapter, matrix) {
+  const matches = fuzzyResolveActions(matrix, action);
+  if (matches.length !== 1 || matches[0].satisfyingAdapters.includes(adapter)) {
+    return void 0;
+  }
+  return {
+    capability: matches[0].name,
+    satisfyingAdapters: matches[0].satisfyingAdapters
+  };
+}
+function missingActionCapabilities(adapter, actionNames, matrix) {
+  return [...new Set(actionNames)].flatMap((action) => {
+    const row = matrix.find((entry) => entry.name === action);
+    if (!row || row.satisfyingAdapters.includes(adapter)) return [];
+    return [{ capability: row.name, satisfyingAdapters: row.satisfyingAdapters }];
+  });
+}
+function handleActionMatrixError(json, code, message, userAction, details = {}) {
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "actions",
+      view: "matrix",
+      ...details,
+      error: { code, message, userAction }
+    }, null, 2));
+  } else {
+    console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+  }
+  return EXIT.usage;
+}
+async function handleActionMatrix(options, input) {
+  const inspectCommand = `mm-harness actions --matrix${actionLibraryContextArgs(input.librarySources)} --json`;
+  const conflicts = [
+    optionFlag(options, "raw") ? "--raw" : void 0,
+    optionFlag(options, "categories") ? "--categories" : void 0,
+    optionString(options, "adapter") ? "--adapter" : void 0,
+    optionString(options, "platform") ? "--platform" : void 0,
+    optionString(options, "actionManifest") ? "--action-manifest" : void 0
+  ].filter((value) => Boolean(value));
+  if (conflicts.length > 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_MATRIX_CONFLICT",
+      `--matrix cannot be combined with ${conflicts.join(", ")}.`,
+      inspectCommand
+    );
+  }
+  const matrix = await resolveActionCapabilityMatrix(input.librarySources);
+  const categories = summarizeActionCategories(matrix);
+  const categoryActions = input.category ? matrix.filter((entry) => entry.category === input.category) : matrix;
+  if (input.category && categoryActions.length === 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_CATEGORY_UNKNOWN",
+      `no action category matches "${input.category}" across the adapter matrix.`,
+      inspectCommand,
+      { category: input.category, availableCategories: categories }
+    );
+  }
+  const actions = input.action ? fuzzyResolveActions(categoryActions, input.action) : input.query ? searchActions(categoryActions, input.query) : categoryActions;
+  if (input.action && actions.length === 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_UNKNOWN",
+      `no action capability matches "${input.action}" across Mobile, Extension, or Core.`,
+      inspectCommand,
+      { action: input.action, category: input.category }
+    );
+  }
+  if (input.query && actions.length === 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_SEARCH_EMPTY",
+      `no action capability matches search "${input.query}" across Mobile, Extension, or Core.`,
+      inspectCommand,
+      { query: input.query, category: input.category }
+    );
+  }
+  if (input.json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "actions",
+      view: "matrix",
+      adapters: ACTION_MATRIX_ADAPTERS,
+      ...input.query ? { query: input.query } : {},
+      ...input.category ? { category: input.category } : {},
+      actions
+    }, null, 2));
+  } else {
+    console.log(renderHumanActionMatrix(actions));
+  }
+  return EXIT.ok;
+}
+function renderHumanActionMatrix(actions) {
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const width = Math.max("action capability".length, ...actions.map((action) => action.name.length));
+  const cell = (status, width2) => status === "available" ? out("accent", "yes".padEnd(width2)) : out("dim", "\u2014".padEnd(width2));
+  return [
+    out("bold", "action capability matrix"),
+    out("comment", "Inspect one: mm-harness actions --matrix --action <name> --json"),
+    `${"action capability".padEnd(width)}  mobile  extension  core`,
+    ...actions.map(
+      (action) => `${action.name.padEnd(width)}  ${cell(action.support.mobile, 6)}  ${cell(action.support.extension, 9)}  ${cell(action.support.core, 4)}`
+    )
+  ].join("\n");
+}
 function fuzzyResolveActions(entries, query) {
   const exactFull = entries.filter((e) => e.name === query);
   if (exactFull.length > 0) return exactFull;
@@ -393,13 +582,19 @@ function levenshtein(left, right) {
   return prior[right.length] ?? right.length;
 }
 export {
+  ACTION_MATRIX_ADAPTERS,
   actionExampleCommand,
+  actionLibraryContextArgs,
   describeManifestActions,
   findRelatedActions,
   fuzzyResolveActions,
   handleActions,
+  missingActionCapabilities,
   renderHumanActionCatalog,
   renderHumanActionExample,
+  renderHumanActionMatrix,
+  resolveActionCapabilityMatrix,
+  resolveActionCapabilityRefusal,
   searchActions,
   summarizeActionCategories,
   summarizeDescribedAction

package/dist/commands/parse-args.js

@@ -29,6 +29,7 @@ function parseArgs(argv, command) {
     "list",
     "describe",
     "raw",
+    "matrix",
     "categories",
     "fix",
     "force",

package/dist/commands/run.js

@@ -35,6 +35,30 @@ import { JsonStreamWriter } from "../json-stream.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 import { recipeTrustFailure } from "../recipe-security.js";
 import { recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
+import {
+  actionLibraryContextArgs,
+  missingActionCapabilities,
+  resolveActionCapabilityMatrix
+} from "./manifest.js";
+async function validationCapabilityRefusals(adapter, findings, librarySources) {
+  const actionNames = findings.flatMap((finding) => {
+    if (finding.code !== "recipe.action_not_declared_by_manifest") return [];
+    const match = /^Recipe action ([^ ]+) is not declared by the runner action manifest[.]?$/u.exec(finding.message);
+    return match?.[1] ? [match[1]] : [];
+  });
+  if (actionNames.length === 0) return [];
+  return missingActionCapabilities(
+    adapter,
+    actionNames,
+    await resolveActionCapabilityMatrix(librarySources)
+  );
+}
+function capabilityValidationUserAction(adapter, refusals, libraryContextArgs) {
+  const capabilities = refusals.map(
+    (refusal) => `"${refusal.capability}" [${refusal.satisfyingAdapters.join(", ")}]`
+  ).join("; ");
+  return `Missing action capabilities for ${adapter}, with satisfying adapters: ${capabilities}. Inspect: mm-harness actions --matrix${libraryContextArgs} --json; then rerun from a checkout matching a satisfying adapter, splitting the recipe if no single adapter satisfies every capability`;
+}
 async function handleRun(parsed) {
   const stream = new JsonStreamWriter("run", optionFlag(parsed.options, "jsonStream"));
   const restoreStdout = stream.isolateStdout();
@@ -165,7 +189,21 @@ async function handleRunInner({ positional, options }, stream) {
     );
   }
   if (validated.errorCount > 0) {
-    return emitRunValidationError(jsonOutput, stream, adapter, validated.recipeFile, validated.findings, validated.errorCount);
+    const capabilityRefusals = optionString(options, "actionManifest") ? [] : await validationCapabilityRefusals(
+      adapter,
+      validated.findings,
+      validated.librarySources
+    );
+    return emitRunValidationError(
+      jsonOutput,
+      stream,
+      adapter,
+      validated.recipeFile,
+      validated.findings,
+      validated.errorCount,
+      capabilityRefusals,
+      actionLibraryContextArgs(validated.librarySources)
+    );
   }
   const depsBlock = adapter === "core" && await recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
   if (depsBlock) {
@@ -447,8 +485,23 @@ async function handleRunPlan(recipeArg, params, options, stream) {
       userAction
     );
   }
-  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid, effectiveParams } = validated;
+  const {
+    recipe,
+    recipeFile,
+    findings,
+    errorCount,
+    manifestOk,
+    schemaValid,
+    effectiveParams,
+    librarySources
+  } = validated;
   const status = errorCount === 0 ? "pass" : "fail";
+  const capabilityRefusals = status === "fail" && !optionString(options, "actionManifest") ? await validationCapabilityRefusals(adapter, findings, librarySources) : [];
+  const failureUserAction = capabilityRefusals.length > 0 ? capabilityValidationUserAction(
+    adapter,
+    capabilityRefusals,
+    actionLibraryContextArgs(librarySources)
+  ) : runPlanProbe(adapter, recipeFile);
   const nodeCount = countRecipeNodes(recipe);
   const artifactsDir = optionString(options, "artifactsDir");
   const plan = [
@@ -514,7 +567,8 @@ async function handleRunPlan(recipeArg, params, options, stream) {
     payload.error = {
       code: "RECIPE_VALIDATION_FAILED",
       message: `recipe validation found ${errorCount} error(s)`,
-      userAction: runPlanProbe(adapter, recipeFile)
+      ...capabilityRefusals.length > 0 ? { missingCapabilities: capabilityRefusals } : {},
+      userAction: failureUserAction
     };
   }
   if (stream.enabled) {
@@ -534,7 +588,7 @@ async function handleRunPlan(recipeArg, params, options, stream) {
         console.log(`  ${finding.severity === "error" ? "\u2717" : "\u26A0"} ${finding.code} ${finding.path} \u2014 ${finding.message}`);
       }
     }
-    if (status === "fail") console.error(`  Next: ${runPlanProbe(adapter, recipeFile)}`);
+    if (status === "fail") console.error(`  Next: ${failureUserAction}`);
   }
   return status === "pass" ? EXIT.ok : EXIT.validation;
 }
@@ -582,10 +636,17 @@ function emitRunUsageError(json, stream, adapter, recipeFile, code, message, use
   }
   return EXIT.usage;
 }
-function emitRunValidationError(json, stream, adapter, recipeFile, findings, errorCount) {
+function emitRunValidationError(json, stream, adapter, recipeFile, findings, errorCount, capabilityRefusals, libraryContextArgs) {
   const message = `recipe validation found ${errorCount} error(s)`;
-  const userAction = runPlanProbe(adapter, recipeFile);
-  stream.error({ code: "RECIPE_VALIDATION_FAILED", message, userAction, findings });
+  const userAction = capabilityRefusals.length > 0 ? capabilityValidationUserAction(adapter, capabilityRefusals, libraryContextArgs) : runPlanProbe(adapter, recipeFile);
+  const capabilityDetails = capabilityRefusals.length > 0 ? { missingCapabilities: capabilityRefusals } : {};
+  stream.error({
+    code: "RECIPE_VALIDATION_FAILED",
+    message,
+    userAction,
+    findings,
+    ...capabilityDetails
+  });
   if (json) {
     console.log(
       JSON.stringify(
@@ -599,7 +660,12 @@ function emitRunValidationError(json, stream, adapter, recipeFile, findings, err
           mutations: [],
           recipe: recipeFile,
           findings,
-          error: { code: "RECIPE_VALIDATION_FAILED", message, userAction }
+          error: {
+            code: "RECIPE_VALIDATION_FAILED",
+            message,
+            userAction,
+            ...capabilityDetails
+          }
         },
         null,
         2

package/dist/mm-harness-cli.js

@@ -121,6 +121,7 @@ Materialize:
 
   query                              Search names, categories, fields, and descriptions (typo-tolerant)
   --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
+  --matrix                           Compare action availability across Mobile, Extension, and Core
   --categories                       List compact action categories and counts
   --category <name>                  List only one category (for example ui, wallet, or perps)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
@@ -130,6 +131,7 @@ Materialize:
 
 Example:
   mm-harness actions --adapter mobile
+  mm-harness actions --matrix --json
   mm-harness actions positions --adapter mobile
   mm-harness actions --adapter mobile --categories --json
   mm-harness actions --adapter mobile --category ui --json

package/dist/recipe-security.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, readFile, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.locators",
   "metamask.wallet.fixture_status",
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state",

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

@@ -0,0 +1,13 @@
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  locatorsFromObservation,
+  requireVisibleObservation,
+} from '../../shared/ui/locators.mjs';
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const observed = await page.observe(['ui.visible']);
+  return {
+    action: input.action,
+    ...locatorsFromObservation(requireVisibleObservation(observed)),
+  };
+}));

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/package.json

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