@deeeed/metamask-harness 0.74.0 → 0.76.0

package/dist/adapters.js

@@ -1,36 +1,14 @@
 import http from "node:http";
 import { createHash } from "node:crypto";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { compatibilityMode, fixtureSummary, repoShape } from "./doctor.js";
 import {
   runLiveAdapterScript
 } from "./live-adapter-contract.js";
-import { withExtensionPage } from "../library/actions/extension/platform/cdp.mjs";
-import { bridgeCommand, evalAsync, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
-import { observeNativeUi } from "../library/actions/mobile/platform/observe-ui.mjs";
-import { nativeAgentDeviceStateDir } from "../library/actions/mobile/platform/native-session-name.mjs";
-import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 import { resolveWalletImportCredentials, validateWalletImportOptions } from "../library/actions/shared/wallet/import-source.mjs";
+import { isRecord, traceText } from "./action-values.js";
+import { getAdapterSurface } from "./adapters/surface.js";
 import { handleRunNetworkAction } from "./network-observation.js";
 import { handleRunPerformanceAction } from "./performance-observation.js";
-const execFileAsync = promisify(execFile);
-const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
-  "ui.press",
-  "ui.key_press",
-  "ui.set_input",
-  "ui.scroll",
-  "ui.swipe",
-  "ui.pan",
-  "ui.drag",
-  "ui.long_press",
-  "ui.wait_for",
-  "ui.screenshot",
-  "ui.capture_surface"
-]);
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 function simpleAdapter(action, executor) {
   return {
     action,
@@ -93,9 +71,6 @@ const LIVE_ONLY_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.teardown_state",
   "metamask.perps.capture_performance"
 ]);
-const CORE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
-  "metamask.perps.read_account"
-]);
 const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
   "metamask.wallet.import",
@@ -118,10 +93,10 @@ const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set([
   "app.performance_assert"
 ]);
 function requiresLiveAdapter(platform, action) {
-  return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_FEATURE_FLAG_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
+  return LIVE_ONLY_ACTIONS.has(action) || Boolean(getAdapterSurface(platform).actions.liveOnly?.includes(action)) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_FEATURE_FLAG_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
 }
 function liveRuntimeConfigured(platform, node) {
-  if (platform === "mobile" || platform === "core" || platform === "terminal") return true;
+  if (!getAdapterSurface(platform).actions.liveNeedsCdpPort) return true;
   return Boolean(node.cdp_port ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT);
 }
 async function runLiveFirst(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
@@ -204,35 +179,6 @@ async function semanticResult(platform, action, node, context, forceLive = false
     }
   };
 }
-function isRecord(value) {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-function optionalScalarText(value, label) {
-  if (value === void 0 || value === null) return void 0;
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  throw new Error(`${label} must be a string, number, or boolean.`);
-}
-function scalarText(value, label, fallback) {
-  return optionalScalarText(value, label) ?? fallback;
-}
-function firstScalarText(record, keys, label, fallback) {
-  for (const key of keys) {
-    const value = optionalScalarText(record[key], `${label}.${key}`);
-    if (value !== void 0) return value;
-  }
-  if (fallback !== void 0) return fallback;
-  throw new Error(`${label} requires one of: ${keys.join(", ")}.`);
-}
-function traceText(value) {
-  if (value === void 0 || value === null) return "";
-  if (value instanceof Error) return value.message;
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  return JSON.stringify(value);
-}
 function probeHttpJson(url, timeoutMs = 1e3) {
   return new Promise((resolve) => {
     const request = http.get(url, { timeout: timeoutMs }, (response) => {
@@ -280,67 +226,35 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
   ];
   const bundledActions = [
     ...walletActions,
-    ...platform !== "core" ? [
-      "app.network_capture",
-      "app.network_assert",
-      "app.performance_capture",
-      "app.performance_assert"
-    ] : [],
     "metamask.assets.read_visible_state",
     "metamask.assets.open_details",
     "metamask.assets.read_details",
     "metamask.assets.verify_sorting",
     "metamask.assets.set_token_visibility",
     "metamask.assets.import_custom_token",
-    ...platform === "extension" ? [
-      "metamask.assets.prepare_send",
-      "metamask.assets.review_send",
-      "metamask.assets.set_custom_gas",
-      "metamask.assets.select_network_scope"
-    ] : [],
     "metamask.wallet.lock",
     "metamask.networks.read_visible_state",
     "metamask.networks.add_custom",
-    ...platform === "extension" ? ["metamask.networks.add_chainlist"] : [],
     "metamask.networks.remove_custom",
     "metamask.perps.read_visible_state",
     "metamask.perps.search_markets",
     "metamask.perps.set_market_favorite",
-    ...platform === "extension" ? ["metamask.perps.compare_provider_market"] : [],
-    ...platform === "extension" ? ["metamask.perps.read_eligibility"] : [],
-    ...platform === "extension" ? [
-      "metamask.perps.open_position_action",
-      "metamask.perps.edit_margin",
-      "metamask.perps.update_position_tpsl",
-      "metamask.perps.assert_visible_consistency"
-    ] : [],
     "metamask.swap_bridge.read_visible_state",
     "metamask.swap_bridge.select_assets",
     "metamask.swap_bridge.set_amount",
     "metamask.swap_bridge.set_max_amount",
     "metamask.swap_bridge.set_slippage",
-    ...platform === "mobile" ? ["metamask.swap_bridge.submit_transaction"] : [],
-    ...platform === "extension" ? ["metamask.settings.set_basic_functionality"] : [],
     "metamask.perps.read_positions",
     "metamask.perps.ensure_positions",
     "metamask.perps.assert_positions",
     "metamask.perps.place_order",
-    ...platform === "mobile" || platform === "core" ? ["metamask.perps.close_positions"] : [],
     "metamask.perps.read_orders",
     "metamask.perps.close_orders",
     "metamask.perps.ensure_orders",
     "metamask.perps.assert_orders",
-    ...platform === "mobile" || platform === "core" ? ["metamask.perps.start_state"] : [],
     "metamask.perps.teardown_state",
     "metamask.perps.capture_performance",
-    ...platform === "extension" || platform === "core" ? ["metamask.perps.read_snapshot"] : [],
-    ...platform === "mobile" ? [
-      "metamask.perps.clear_performance_caches",
-      "metamask.perps.measure_homepage_visible",
-      "metamask.perps.prepare_local_snapshot_endpoint"
-    ] : [],
-    // read_account is core-only: only the headless core adapter implements it.
-    ...platform === "core" ? ["metamask.perps.read_account"] : []
+    ...getAdapterSurface(platform).actions.semantic
   ];
   const bundled = new Set(bundledActions);
   const actions = [.../* @__PURE__ */ new Set([...bundledActions, ...declaredCustomActions])];
@@ -358,734 +272,41 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
     )
   );
 }
-function uiInputFor(context, input) {
-  return {
-    action: input.action,
-    node: input.node,
-    context: {
-      nodeId: context.nodeId,
-      projectRoot: context.projectRoot,
-      artifactsDir: context.artifactsDir,
-      env: context.env
-    }
-  };
-}
-function mobileProbeOutput(status, input, projectRoot) {
-  const entries = Array.isArray(status) ? status : [status];
-  const selected = selectBridgeStatusEntry(status, input) ?? null;
-  const route = isRecord(selected) && isRecord(selected.route) ? selected.route : null;
-  return {
-    reachable: isRecord(selected) && selected.agenticPresent === true && Boolean(route),
-    bridge: mobileBridgePath(projectRoot),
-    targetCount: entries.filter((entry) => isRecord(entry)).length,
-    deviceName: isRecord(selected) && typeof selected.deviceName === "string" ? selected.deviceName : null,
-    routeName: route && typeof route.name === "string" ? route.name : null,
-    accountPresent: isRecord(selected) && isRecord(selected.account)
-  };
-}
-function mobileBridgePath(_projectRoot) {
-  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || "runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs";
-}
-function resolveMobileWaitTarget(payload) {
-  const testId = optionalScalarText(
-    payload.test_id ?? payload.testID,
-    "Mobile ui.wait_for.test_id"
-  );
-  const expectedText = optionalScalarText(payload.text, "ui.wait_for.text");
-  if (!testId && !expectedText) {
-    throw new Error(
-      "Mobile ui.wait_for requires one of: test_id, testID, text."
-    );
-  }
-  const expected = scalarText(
-    payload.expected,
-    "ui.wait_for.expected",
-    "present"
-  ).toLowerCase();
-  const textMatch = scalarText(
-    payload.text_match ?? payload.textMatch,
-    "ui.wait_for.text_match",
-    "contains"
-  ).toLowerCase();
-  if (!["contains", "exact"].includes(textMatch)) {
-    throw new Error("ui.wait_for.text_match must be contains or exact.");
-  }
-  if (!testId && textMatch === "exact") {
-    throw new Error(
-      "Mobile text-only ui.wait_for supports text_match=contains; exact matching also requires test_id/testID."
-    );
-  }
-  return {
-    testId,
-    expectedText,
-    expected,
-    textMatch,
-    visibility: expected === "visible" || expected === "hidden" ? "viewport" : "tree"
-  };
-}
-const RETRYABLE_MOBILE_WAIT_CODES = /* @__PURE__ */ new Set([
-  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
-  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
-  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
-  MOBILE_BRIDGE_ERROR_CODES.METRO_UNREACHABLE
-]);
-function isRetryableMobileWaitError(error) {
-  return Boolean(
-    isRecord(error) && typeof error.code === "string" && RETRYABLE_MOBILE_WAIT_CODES.has(error.code)
-  );
-}
-async function waitForMobileTarget(input, payload) {
-  const timeoutMs = Number(payload.timeout_ms ?? payload.timeoutMs ?? 1e4);
-  const deadline = Date.now() + timeoutMs;
-  const { testId, expectedText, expected, textMatch, visibility } = resolveMobileWaitTarget(payload);
-  const query = {
-    ...testId ? { testId } : {},
-    ...expectedText && textMatch === "contains" ? { textContains: expectedText } : {},
-    visibility
-  };
-  const queryExpression = `(function(){
-    const api = globalThis.__AGENTIC__;
-    if (!api || typeof api.queryUiTarget !== 'function') {
-      return Promise.resolve(JSON.stringify({ unsupported: true }));
-    }
-    return api.queryUiTarget(${JSON.stringify(query)}).then(function(result){
-      return JSON.stringify(result);
-    });
-  })()`;
-  const textExpression = testId ? `(function(){
-        const api = globalThis.__AGENTIC__;
-        if (!api?.getTextByTestId) return null;
-        return api.getTextByTestId(${JSON.stringify(testId)});
-      })()` : null;
-  let lastResult = null;
-  let lastText = null;
-  let lastBridgeError = null;
-  const expectsAbsent = expected === "absent" || expected === "hidden" || expected === "not_present";
-  while (Date.now() <= deadline) {
-    const remainingMs = Math.max(1, deadline - Date.now());
-    const probeTimeoutMs = Math.min(5e3, remainingMs);
-    const probeInput = {
-      ...input,
-      node: {
-        ...input.node,
-        bridge_timeout_ms: probeTimeoutMs,
-        cdp_timeout_ms: probeTimeoutMs
-      }
-    };
-    let result;
-    try {
-      result = await evalAsync(probeInput, queryExpression);
-    } catch (error) {
-      if (!isRetryableMobileWaitError(error)) throw error;
-      lastBridgeError = error;
-      await sleep(250);
-      continue;
-    }
-    if (!isRecord(result) || result.unsupported === true) {
-      throw new Error(
-        "Mobile ui.wait_for requires the current __AGENTIC__.queryUiTarget bridge for text-only or viewport-visible assertions."
-      );
-    }
-    lastResult = result;
-    const present = result.present === true;
-    const visible = result.visible === true;
-    let textMatched = !expectedText || textMatch === "contains";
-    if (expectedText && textMatch === "exact" && textExpression) {
-      try {
-        lastText = await evalSync(probeInput, textExpression);
-      } catch (error) {
-        if (!isRetryableMobileWaitError(error)) throw error;
-        lastBridgeError = error;
-        await sleep(250);
-        continue;
-      }
-      textMatched = traceText(lastText) === expectedText;
-    }
-    const matched = expected === "visible" ? visible && textMatched : expected === "hidden" ? !visible : expectsAbsent ? !present : present && textMatched;
-    if (matched) {
-      return {
-        matched: true,
-        ...testId ? { testId } : {},
-        ...expectedText ? { text: expectedText, textMatch } : {},
-        expected,
-        present,
-        visible,
-        visibility,
-        ...isRecord(result.rect) ? { rect: result.rect } : {}
-      };
-    }
-    await sleep(250);
-  }
-  const target = [
-    testId ? `testID ${JSON.stringify(testId)}` : "",
-    expectedText ? `text ${textMatch} ${JSON.stringify(expectedText)}` : ""
-  ].filter(Boolean).join(" with ");
-  const exactReason = textMatch === "exact" ? `; last text=${JSON.stringify(lastText)}` : "";
-  const bridgeReason = lastBridgeError ? `; last bridge error=${traceText(lastBridgeError)}` : "";
-  throw new Error(
-    `Timed out waiting for mobile ${target} to be ${expected}; last result=${JSON.stringify(lastResult)}${exactReason}${bridgeReason}.`
-  );
-}
-const MOBILE_BRIDGE_HANDLERS = {
-  screenshot: handleMobileScreenshot,
-  status: handleMobileStatus,
-  navigate: handleMobileNavigate,
-  press: handleMobilePress,
-  keyPress: handleMobileKeyPress,
-  setInput: handleMobileSetInput,
-  scroll: handleMobileScroll,
-  waitFor: handleMobileWaitFor,
-  hud: handleMobileHud,
-  observeUi: handleMobileObserveUi
-};
-function createMetaMaskMobileBridge() {
-  return {
-    async send(command, context) {
-      const handler = MOBILE_BRIDGE_HANDLERS[command.command];
-      if (!handler) {
-        throw new Error(`React Native bridge command ${command.command} is not implemented by the MetaMask runner transport.`);
-      }
-      return handler(command.payload, context);
-    }
-  };
-}
-function mobileUiInput(context, command, payload) {
-  return uiInputFor(context, { action: `ui.${command}`, node: payload });
-}
-async function handleMobileScreenshot(payload, context) {
-  const input = mobileUiInput(context, "screenshot", payload);
-  const relPath = scalarText(payload.path, "ui.screenshot.path", `screenshots/${context.nodeId}.png`);
-  const artifact = await simulatorScreenshot(input, relPath);
-  context.registerArtifact(artifact);
-  return { captured: true, path: artifact.path, artifact };
-}
-async function handleMobileStatus(payload, context) {
-  return bridgeCommand(mobileUiInput(context, "status", payload), ["status"]);
-}
-async function handleMobileObserveUi(payload, context) {
-  return observeNativeUi(payload, context);
-}
-async function handleMobileNavigate(payload, context) {
-  const live = await runLiveAdapterScript({
-    platform: "mobile",
-    action: "ui.navigate",
-    node: payload,
-    context
-  });
-  if (!live) throw new Error("ui.navigate requires library/actions/mobile/ui/navigate.mjs.");
-  return isRecord(live.result) ? { ...live.result, liveAdapter: live.script } : live.result;
-}
-async function handleMobilePress(payload, context) {
-  const identifiers = ["test_id", "testID", "selector"].map((field) => optionalScalarText(payload[field], `ui.press.${field}`)).filter((value) => value !== void 0);
-  const text = optionalScalarText(payload.text, "ui.press.text");
-  if (identifiers.length + Number(text !== void 0) !== 1) {
-    throw new Error("ui.press requires exactly one of: test_id, testID, selector, text.");
-  }
-  const target = text ?? identifiers[0];
-  if (target.trim() === "") throw new Error("ui.press target must be non-empty.");
-  const longPress = payload.long_press === true;
-  if (longPress && text !== void 0) {
-    throw new Error("ui.press long_press=true requires test_id, testID, or selector targeting.");
-  }
-  const input = mobileUiInput(context, "press", payload);
-  if (text !== void 0) return bridgeCommand(input, ["press-text", target]);
-  return bridgeCommand(input, [longPress ? "long-press-test-id" : "press-test-id", target]);
-}
-async function handleMobileKeyPress(payload, context) {
-  const key = scalarText(payload.key, "ui.key_press.key", "Enter");
-  const input = mobileUiInput(context, "key_press", payload);
-  return bridgeCommand(input, ["key-press", key]);
-}
-async function handleMobileSetInput(payload, context) {
-  const input = mobileUiInput(context, "set_input", payload);
-  const testId = firstScalarText(payload, ["test_id", "testID"], "ui.set_input");
-  const value = scalarText(payload.value ?? payload.text, "ui.set_input.value", "");
-  const result = await bridgeCommand(input, ["set-input", testId, value]);
-  if (isRecord(result) && result.ok === false) {
-    throw new Error(`ui.set_input failed for mobile testID ${testId}: ${traceText(result.error ?? result)}`);
-  }
-  return isRecord(result) ? result : { result, testId, value };
-}
-async function handleMobileScroll(payload, context) {
-  const input = mobileUiInput(context, "scroll", payload);
-  const testId = optionalScalarText(payload.test_id ?? payload.testID, "ui.scroll.test_id");
-  const offset = scalarText(payload.offset ?? payload.delta_y ?? payload.deltaY, "ui.scroll.offset", "600");
-  const intoView = payload.scroll_into_view === true || payload.into_view === true;
-  const measureFromTestId = optionalScalarText(
-    payload.measure_from_test_id ?? payload.measureFromTestId,
-    "ui.scroll.measure_from_test_id"
-  );
-  const measureTargetTestId = optionalScalarText(
-    payload.measure_target_test_id ?? payload.measureTargetTestId,
-    "ui.scroll.measure_target_test_id"
-  );
-  const measureTargetText = optionalScalarText(
-    payload.measure_target_text ?? payload.measureTargetText,
-    "ui.scroll.measure_target_text"
-  );
-  const measureTargetCount = Number(Boolean(measureTargetTestId)) + Number(Boolean(measureTargetText));
-  const measureRequiredPresentTestId = optionalScalarText(
-    payload.measure_required_present_test_id ?? payload.measureRequiredPresentTestId,
-    "ui.scroll.measure_required_present_test_id"
-  );
-  if (Boolean(measureFromTestId) !== (measureTargetCount === 1)) {
-    throw new Error(
-      "ui.scroll visible-transition measurement requires measure_from_test_id and exactly one of measure_target_test_id or measure_target_text."
-    );
-  }
-  if (measureFromTestId && measureTargetCount === 1) {
-    if (intoView) {
-      throw new Error(
-        "ui.scroll visible-transition measurement uses an explicit offset and does not support scroll_into_view."
-      );
-    }
-    return measureMobileScrollTransition(input, {
-      animated: payload.animated === true,
-      fromTestId: measureFromTestId,
-      offset: Number(offset),
-      ...measureTargetTestId ? { targetTestId: measureTargetTestId } : {},
-      ...measureTargetText ? { targetText: measureTargetText } : {},
-      ...measureRequiredPresentTestId ? { requiredPresentTestId: measureRequiredPresentTestId } : {},
-      timeoutMs: Math.max(
-        1,
-        Number(payload.timeout_ms ?? payload.timeoutMs ?? 3e4)
-      ),
-      ...testId ? { scrollTestId: testId } : {}
-    });
-  }
-  if (testId && intoView) {
-    const before = await queryMobileViewportTarget(input, testId);
-    if (before.visible === true) {
-      return {
-        ok: true,
-        testId,
-        intoView: true,
-        alreadyVisible: true,
-        rect: before.rect
-      };
-    }
-  }
-  const args = testId ? [
-    "scroll-view",
-    "--test-id",
-    testId,
-    "--offset",
-    offset,
-    ...intoView ? ["--into-view"] : [],
-    animatedFlag(payload)
-  ] : ["scroll-view", "--offset", offset, animatedFlag(payload)];
-  const timeoutMs = Math.max(0, Number(payload.timeout_ms ?? payload.timeoutMs ?? 5e3));
-  const deadline = Date.now() + timeoutMs;
-  let result;
-  while (true) {
-    try {
-      result = await bridgeCommand(input, args);
-      break;
-    } catch (error) {
-      if (!testId || Date.now() >= deadline) throw error;
-      await sleep(100);
-    }
-  }
-  if (testId && intoView) {
-    const after = await waitForMobileViewportTarget(
-      input,
-      testId,
-      timeoutMs
-    );
-    if (after.visible !== true) {
-      throw new Error(
-        `ui.scroll did not bring mobile testID ${JSON.stringify(testId)} into the viewport; last result=${JSON.stringify(after)}.`
-      );
-    }
-  }
-  return {
-    ...isRecord(result) ? result : { result },
-    intoView
-  };
-}
-async function measureMobileScrollTransition(input, options) {
-  const result = await bridgeCommand(
-    {
-      ...input,
-      node: {
-        ...input.node,
-        bridge_timeout_ms: options.timeoutMs + 5e3,
-        cdp_timeout_ms: options.timeoutMs + 5e3
-      }
-    },
-    ["measure-scroll-transition", JSON.stringify(options)]
-  );
-  if (!isRecord(result) || result.unsupported === true) {
-    throw new Error(
-      "ui.scroll visible-transition measurement requires queryUiTarget and scrollView on the current mobile bridge."
-    );
-  }
-  if (result.ok !== true) {
-    throw new Error(
-      `ui.scroll visible-transition measurement failed: ${traceText(result.error ?? result)}.`
-    );
-  }
-  return {
-    ...result,
-    measureFromTestId: options.fromTestId,
-    ...options.targetTestId ? { measureTargetTestId: options.targetTestId } : {},
-    ...options.targetText ? { measureTargetText: options.targetText } : {},
-    ...options.requiredPresentTestId ? { measureRequiredPresentTestId: options.requiredPresentTestId } : {}
-  };
-}
-async function queryMobileViewportTarget(input, testId) {
-  const expression = `(function(){
-    const api = globalThis.__AGENTIC__;
-    if (!api || typeof api.queryUiTarget !== 'function') {
-      return Promise.resolve(JSON.stringify({ unsupported: true }));
-    }
-    return api.queryUiTarget(${JSON.stringify({ testId, visibility: "viewport" })}).then(function(result){
-      return JSON.stringify(result);
-    });
-  })()`;
-  const result = await evalAsync(input, expression);
-  if (!isRecord(result) || result.unsupported === true) {
-    throw new Error(
-      "Mobile ui.scroll scroll_into_view requires the current __AGENTIC__.queryUiTarget bridge."
-    );
-  }
-  return result;
-}
-async function waitForMobileViewportTarget(input, testId, timeoutMs) {
-  const deadline = Date.now() + Math.max(0, Math.min(timeoutMs, 5e3));
-  let result = await queryMobileViewportTarget(input, testId);
-  while (result.visible !== true && Date.now() < deadline) {
-    await sleep(100);
-    result = await queryMobileViewportTarget(input, testId);
-  }
-  return result;
-}
-async function handleMobileWaitFor(payload, context) {
-  return waitForMobileTarget(mobileUiInput(context, "waitFor", payload), payload);
-}
-async function handleMobileHud(payload, context) {
-  const automaticProgress = typeof payload.action_name === "string" || context.nodeId === "recipe-complete" && isRecord(payload.progress) && payload.progress.complete === true;
-  const captureProgress = payload.action_name === "ui.screenshot" || payload.action_name === "ui.capture_surface";
-  const input = mobileUiInput(
-    context,
-    "hud",
-    automaticProgress ? {
-      ...payload,
-      bridge_timeout_ms: captureProgress ? 1e4 : 2e3,
-      cdp_timeout_ms: captureProgress ? 1e4 : 2e3
-    } : payload
-  );
-  if (payload.clear === true) {
-    try {
-      return await bridgeCommand(input, ["hide-step"]);
-    } catch (error) {
-      return mobileHudSkippedOrThrow(error);
-    }
-  }
-  const hud = mobileHudPayload(payload, context);
-  try {
-    const result = await bridgeCommand(input, [
-      automaticProgress && !captureProgress ? "show-step-json-deferred" : "show-step-json",
-      JSON.stringify(hud.step)
-    ]);
-    return { hud: true, nodeId: hud.nodeId, status: hud.status, result };
-  } catch (error) {
-    return mobileHudSkippedOrThrow(error, { nodeId: hud.nodeId, status: hud.status });
-  }
-}
-async function hideMobileHudOnTeardown(projectRoot, env = {}) {
-  if (env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") return;
-  if (process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false") return;
-  const input = {
-    node: { bridge_timeout_ms: 8e3, cdp_timeout_ms: 5e3 },
-    context: { nodeId: "teardown", projectRoot, artifactsDir: projectRoot, env }
-  };
-  try {
-    await bridgeCommand(input, ["hide-step-deferred"]);
-  } catch {
-  }
-}
-function mobileHudSkippedOrThrow(error, extra = {}) {
-  const reason = traceText(error);
-  const code = isRecord(error) && typeof error.code === "string" ? error.code : void 0;
-  if (isMobileHudLifecycleSkip(reason, code)) {
-    process.stderr.write(`app.hud skipped (bridge target down or transitioning): ${reason}
-`);
-    return {
-      hud: false,
-      skipped: true,
-      warning: "app.hud skipped because the mobile bridge target is down during lifecycle transition.",
-      ...extra,
-      reason
-    };
-  }
-  throw new Error(`app.hud bridge command failed outside a lifecycle/no-target transition: ${reason}`);
-}
-const HUD_LIFECYCLE_SKIP_CODES = /* @__PURE__ */ new Set([
-  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
-  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
-  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
-  MOBILE_BRIDGE_ERROR_CODES.METRO_UNREACHABLE
-]);
-function isMobileHudLifecycleSkip(reason, code) {
-  if (code && HUD_LIFECYCLE_SKIP_CODES.has(code)) return true;
-  const haystack = reason.toLowerCase();
-  return [
-    "no responding bridge target",
-    "pinned android device",
-    "bridge probe failed",
-    "econnrefused",
-    "timed out",
-    "no react native bridge target",
-    // Metro down mid-run: HUD cannot paint, so skip rather than abort (the real
-    // action fails on its own). Matches the METRO_UNREACHABLE code branch above.
-    "cannot reach metro",
-    // Dev-client foreground/reload kills the Hermes page mid-flight: pending
-    // CDP calls surface as a message timeout or a closed socket.
-    "cdp message timeout",
-    "websocket closed"
-  ].some((needle) => haystack.includes(needle));
-}
-function animatedFlag(payload) {
-  return payload.animated === true ? "--animated" : "--no-animated";
-}
-function mobileHudPayload(payload, context) {
-  const nodeId = scalarText(payload.node_id ?? payload.nodeId, "app.hud.node_id", context.nodeId);
-  const status = scalarText(payload.status, "app.hud.status", "running");
-  const text = optionalScalarText(payload.intent ?? payload.text ?? payload.detail, "app.hud.intent");
-  if (!text || !text.trim()) {
-    throw new Error("app.hud requires intent/text/detail; automatic recipe progress should provide node intent.");
-  }
-  const detail = scalarText(payload.detail, "app.hud.detail", "");
-  const error = scalarText(payload.error, "app.hud.error", "");
-  const progress = mobileHudProgress(payload.progress);
-  const display = isRecord(payload.display) ? payload.display : {};
-  const showDebug = display.showDebug === true;
-  const showDetail = display.showDetail === true;
-  const proofTarget = payload.proofTarget ?? payload.proof_target;
-  const displayId = [mobileHudStatusLabel(status), progress.text].filter(Boolean).join(" ");
-  return {
-    nodeId,
-    status,
-    step: {
-      id: displayId || nodeId,
-      nodeId,
-      status,
-      intent: text,
-      progress: progress.value,
-      detail: showDetail && detail !== text ? detail : void 0,
-      error: error || void 0,
-      debug: showDebug ? {
-        nodeId,
-        proofTarget
-      } : void 0
-    }
-  };
-}
-function mobileHudProgress(progress) {
-  if (!isRecord(progress)) return { text: "" };
-  if (typeof progress.current !== "number" || typeof progress.total !== "number") return { text: "" };
-  return {
-    text: `${progress.current}/${progress.total}`,
-    value: { current: progress.current, total: progress.total }
-  };
-}
-function mobileHudStatusLabel(status) {
-  if (status === "fail") return "fail";
-  if (status === "pass") return "pass";
-  return "run";
-}
 function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters, { hudPolicy = "auto" } = {}) {
-  if (platform === "core") {
+  const ui = getAdapterSurface(platform).actions.ui;
+  if (!ui) {
     return {
       async execute(action) {
         throw new Error(
-          `core adapter is headless and cannot execute UI action ${action}. Next: mm-harness actions --matrix`
+          `${platform} adapter is headless and cannot execute UI action ${action}. Next: mm-harness actions --matrix`
         );
       }
     };
   }
-  const base = platform === "mobile" ? harness.createReactNativeBridgeUiTransport({ bridge: createMetaMaskMobileBridge() }) : platform === "terminal" ? harness.createCdpWebUiTransport({
-    async withPage(input, callback) {
-      const { withTerminalPage } = await import("../library/actions/terminal/platform/page.mjs");
-      return withTerminalPage(
-        {
-          action: input.action,
-          node: input.node,
-          context: {
-            nodeId: input.context.nodeId,
-            projectRoot: input.context.projectRoot,
-            artifactsDir: input.context.artifactsDir
-          }
-        },
-        callback
-      );
-    }
-  }) : harness.createCdpWebUiTransport({
-    async withPage(input, callback) {
-      return withExtensionPage(
-        {
-          action: input.action,
-          node: input.node,
-          context: {
-            nodeId: input.context.nodeId,
-            projectRoot: input.context.projectRoot,
-            artifactsDir: input.context.artifactsDir
-          }
-        },
-        callback
+  const { base, execute } = ui(harness, { hudPolicy });
+  async function standard(action, node, context) {
+    if (action === "ui.navigate") {
+      const live = await runLiveFirst(
+        platform,
+        action,
+        node,
+        context,
+        false,
+        preparedLiveAdapters
       );
+      if (live) return live.output;
+      throw new Error(`ui.navigate requires library/actions/${platform}/ui/navigate.mjs.`);
     }
-  });
+    return base.execute(action, action === "ui.wait_for" ? normalizeUiWaitNode(node) : node, context);
+  }
   return {
     ...base.observe ? { observe: base.observe.bind(base) } : {},
     async execute(action, node, context) {
-      if (platform === "terminal" && action === "app.hud") {
-        const { showTerminalHud } = await import("../library/actions/terminal/platform/hud.mjs");
-        return showTerminalHud(
-          { action, node, context: { nodeId: context.nodeId, projectRoot: context.projectRoot } },
-          { hudPolicy }
-        );
-      }
-      if (action === "ui.navigate") {
-        const live = await runLiveFirst(
-          platform,
-          action,
-          node,
-          context,
-          false,
-          preparedLiveAdapters
-        );
-        if (live) return live.output;
-        throw new Error(`ui.navigate requires library/actions/${platform}/ui/navigate.mjs.`);
-      }
-      if (platform === "mobile" && NATIVE_PROVIDER_UI_ACTIONS.has(action) && (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || ["ui.swipe", "ui.pan", "ui.drag", "ui.long_press", "ui.capture_surface"].includes(action))) {
-        return executeNativeProviderAction(action, node, context, harness.createNativeUiTransport);
-      }
-      return base.execute(action, action === "ui.wait_for" ? normalizeUiWaitNode(node) : node, context);
-    }
-  };
-}
-async function executeNativeProviderAction(action, node, context, createTransport) {
-  if (!createTransport) {
-    throw new Error(
-      `${action} requires the MetaMask native UI provider. Next: npm install -g @deeeed/metamask-harness@latest`
-    );
-  }
-  const platform = mobileNativePlatform(context.env);
-  const device = platform === "android" ? context.env.ADB_SERIAL ?? context.env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL : context.env.SIM_UDID ?? context.env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? process.env.IOS_SIMULATOR;
-  if (!device) {
-    throw new Error(
-      `${action} requires one selected ${platform} device. Next: mm-harness status --adapter mobile --all-devices --json`
-    );
-  }
-  if (platform === "android" && action === "ui.swipe" && isCoordinateTarget(node.target)) {
-    return executeAndroidCoordinateSwipe(node, String(device));
-  }
-  const app = platform === "android" ? context.env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask" : context.env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask";
-  const session = (platform === "ios" ? `mm-harness-${process.pid}-${device}` : `mm-harness-${process.pid}-${context.nodeId}`).replace(/[^a-zA-Z0-9._-]/gu, "-");
-  const stateDir = nativeAgentDeviceStateDir(context.env ?? {}, context.projectRoot, String(device));
-  let transport;
-  try {
-    transport = await createTransport({ platform, device, app, session, stateDir });
-  } catch (error) {
-    throw new Error(
-      `${action} could not start the MetaMask native UI provider. Next: npm install -g @deeeed/metamask-harness@latest`,
-      { cause: error }
-    );
-  }
-  let executionError;
-  let output;
-  try {
-    output = await transport.execute(action, node, context);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    executionError = /^Native recipe actions require the optional agent-device provider:/u.test(message) ? new Error(
-      `${action} could not start the MetaMask native UI provider. Next: npm install -g @deeeed/metamask-harness@latest`,
-      { cause: error }
-    ) : error;
-  }
-  let closeError;
-  try {
-    await transport.close?.();
-  } catch (error) {
-    closeError = error;
-  }
-  if (executionError && closeError) {
-    const message = executionError instanceof Error ? executionError.message : String(executionError);
-    throw new AggregateError([executionError, closeError], message);
-  }
-  if (executionError) throw executionError;
-  if (closeError) throw closeError;
-  return output;
-}
-function isCoordinateTarget(value) {
-  return isRecord(value) && typeof value.x === "number" && Number.isFinite(value.x) && typeof value.y === "number" && Number.isFinite(value.y);
-}
-async function executeAndroidCoordinateSwipe(node, device) {
-  const target = node.target;
-  const direction = String(node.direction ?? "").toLowerCase();
-  if (!["up", "down", "left", "right"].includes(direction)) {
-    throw new Error("ui.swipe.direction must be up, down, left, or right.");
-  }
-  const distance = Number(node.distance ?? 300);
-  const durationMs = Number(node.duration_ms ?? 300);
-  if (!Number.isFinite(distance) || distance <= 0) {
-    throw new Error("ui.swipe.distance must be a positive number.");
-  }
-  if (!Number.isFinite(durationMs) || durationMs <= 0) {
-    throw new Error("ui.swipe.duration_ms must be a positive number.");
-  }
-  const start = { x: Math.round(target.x), y: Math.round(target.y) };
-  const end = {
-    x: Math.round(start.x + (direction === "left" ? -distance : direction === "right" ? distance : 0)),
-    y: Math.round(start.y + (direction === "up" ? -distance : direction === "down" ? distance : 0))
-  };
-  const adbPath = resolveMobileToolPath("adb", { required: true });
-  try {
-    await execFileAsync(
-      adbPath,
-      [
-        "-s",
-        device,
-        "shell",
-        "input",
-        "swipe",
-        String(start.x),
-        String(start.y),
-        String(end.x),
-        String(end.y),
-        String(Math.round(durationMs))
-      ],
-      { encoding: "utf8", timeout: Math.round(durationMs) + 1e4 }
-    );
-  } catch (error) {
-    throw new Error(
-      `Android ui.swipe failed on ${device}: ${error instanceof Error ? error.message : String(error)}`
-    );
-  }
-  const settleMs = node.settle === false ? 0 : 300;
-  if (settleMs > 0) await sleep(settleMs);
-  return {
-    action: "ui.swipe",
-    resolvedStart: start,
-    resolvedEnd: end,
-    backend: "adb-input-swipe",
-    segments: 1,
-    settlement: {
-      method: "bounded-post-gesture",
-      waitedMs: settleMs,
-      lifecycleNeutral: true
+      if (execute) return execute(action, node, context, () => standard(action, node, context));
+      return standard(action, node, context);
     }
   };
 }
-function mobileNativePlatform(env) {
-  if (env.PLATFORM === "android" || env.PLATFORM === "ios") return env.PLATFORM;
-  if (env.ADB_SERIAL || env.ANDROID_SERIAL) return "android";
-  if (env.SIM_UDID || env.IOS_SIMULATOR) return "ios";
-  if (process.env.PLATFORM === "android" || process.env.PLATFORM === "ios") return process.env.PLATFORM;
-  return process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
-}
 function normalizeUiWaitNode(node) {
   if (node.expected !== void 0 || typeof node.visible !== "boolean") return node;
   return { ...node, expected: node.visible ? "visible" : "absent" };
@@ -1106,17 +327,13 @@ function createMetaMaskAdapters(adapter, declaredCustomActions = [], preparedLiv
       const metroPort = node.metro_port ?? node.watcher_port ?? process.env.WATCHER_PORT ?? null;
       const timeoutMs = Number(node.probe_timeout_ms ?? node.cdp_timeout_ms ?? node.timeout_ms ?? process.env.CDP_TIMEOUT ?? 1e4);
       const required = node.require_reachable === true || node.required === true;
-      if (platform === "mobile" && required) {
-        const uiInput = { action: "cdp.target", nodeId: context.nodeId, node };
-        const status = await bridgeCommand(uiInputFor(context, uiInput), ["status"]);
-        const probe2 = mobileProbeOutput(status, uiInput, context.projectRoot);
-        if (!probe2.reachable) {
-          throw new Error("cdp.target required a reachable mobile React Native bridge, but bridge status did not expose a selected app route.");
-        }
+      const target = getAdapterSurface(platform).actions.cdpTarget;
+      if (required && target.requiredProbe) {
+        const probe2 = await target.requiredProbe(node, context);
         return {
           output: {
             platform,
-            transport: "react-native-debug-bridge",
+            transport: target.transport,
             cdpPort,
             metroPort,
             timeoutMs,
@@ -1124,8 +341,8 @@ function createMetaMaskAdapters(adapter, declaredCustomActions = [], preparedLiv
           }
         };
       }
-      const targetPort = platform === "mobile" ? metroPort ?? cdpPort : cdpPort;
-      const url = targetProbeUrl(platform, targetPort);
+      const targetPort = target.watcherPortFirst ? metroPort ?? cdpPort : cdpPort;
+      const url = targetPort ? `http://127.0.0.1:${traceText(targetPort)}/${target.probePath}` : null;
       const probe = url ? await probeHttpJson(url, timeoutMs) : { reachable: null, statusCode: null, error: "no port declared" };
       if (required && !probe.reachable) {
         throw new Error(`cdp.target required a reachable ${platform} runtime at ${url ?? "<no port>"}: ${traceText(probe.error) || "not reachable"}`);
@@ -1133,7 +350,7 @@ function createMetaMaskAdapters(adapter, declaredCustomActions = [], preparedLiv
       return {
         output: {
           platform,
-          transport: platform === "mobile" ? "react-native-debug-bridge" : platform === "terminal" ? "chrome-cdp" : "chrome-extension-cdp",
+          transport: target.transport,
           cdpPort,
           metroPort,
           probeUrl: url,
@@ -1146,17 +363,8 @@ function createMetaMaskAdapters(adapter, declaredCustomActions = [], preparedLiv
   ];
   return adapters;
 }
-function targetProbeUrl(platform, targetPort) {
-  if (!targetPort) return null;
-  const pathSuffix = platform === "mobile" ? "json/list" : "json/version";
-  return `http://127.0.0.1:${traceText(targetPort)}/${pathSuffix}`;
-}
 export {
   createMetaMaskAdapters,
   createMetaMaskUiTransport,
-  hideMobileHudOnTeardown,
-  isMobileHudLifecycleSkip,
-  isRetryableMobileWaitError,
-  normalizeUiWaitNode,
-  resolveMobileWaitTarget
+  normalizeUiWaitNode
 };