@deeeed/metamask-harness 0.33.3 → 0.34.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.34.0 - 2026-08-07
+
+### Fixed
+
+- Record Mobile Android recipe runs with the selected device's native `screenrecord` capability when `--record-video=full-run` is requested.
+- Record iOS Simulator recipe runs with `simctl recordVideo`, avoiding hidden/offscreen Simulator-window captures that produce empty videos.
+- Keep pinned Android commands on their requested device while its Hermes target re-registers with Metro after a runtime rotation.
+- Make Mobile account selection wait for the selected account state without disconnecting or reinitializing the Perps controller, preventing duplicate account-change reconnections and transient Perps errors.
+- Resolve shutdown iOS simulators to their canonical bridge-visible name while preserving the requested UDID for native launch.
+- Keep lifecycle performance recipes free from HUD bridge timeouts while the app is backgrounded or its runtime target is rotating.
+- Make Android coordinate swipes and scroll-into-view use the selected device consistently, including the native fallback path.
+
+### Added
+
+- Add manifest-declared Mobile `app.lifecycle` and `app.network` actions with device targeting, runtime readiness, and Android offline/online recovery.
+- Add reusable Perps Homepage performance capture with lifecycle, delivery-source, visible-content, and socket-pipeline validation.
+- Bundle the device-proven Android/iOS Perps Homepage short-resume, reconnect, cold-cache, cold-no-cache, and Android network-recovery recipes with explicit cleanup and full-run evidence commands.
+- Add wallet setup/account-selection readiness checks and source-freshness recovery evidence for Mobile recipe runs.
+
 ## 0.33.3 - 2026-08-05
 
 ### Changed

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -305,6 +305,7 @@ const COMMANDS = {
     let testId;
     let offset = 300;
     let animated = false;
+    let intoView = false;
     for (let i = 0; i < args.length; i++) {
       if (args[i] === '--test-id' && i + 1 < args.length) {
         testId = args[++i];
@@ -312,11 +313,13 @@ const COMMANDS = {
         offset = Number(args[++i]);
       } else if (args[i] === '--animated') {
         animated = true;
+      } else if (args[i] === '--into-view') {
+        intoView = true;
       } else if (args[i] === '--no-animated') {
         animated = false;
       }
     }
-    const optsJson = JSON.stringify({ testId, offset, animated });
+    const optsJson = JSON.stringify({ testId, offset, animated, intoView });
     // Try __AGENTIC__ bridge first, fall back to inline fiber walking
     const expr = `(function() {
       if (globalThis.__AGENTIC__?.scrollView) return globalThis.__AGENTIC__.scrollView(${optsJson});
@@ -340,6 +343,19 @@ const COMMANDS = {
         }
         return false;
       }
+      function tryScrollNear(anchor) {
+        if (!opts.intoView && tryScroll(anchor, false)) return true;
+        var current = anchor ? anchor.return : null;
+        while (current) {
+          var sn = current.stateNode;
+          if (sn) {
+            if (typeof sn.scrollTo === 'function') { sn.scrollTo({ y: opts.offset, animated: opts.animated }); return true; }
+            if (typeof sn.scrollToOffset === 'function') { sn.scrollToOffset({ offset: opts.offset, animated: opts.animated }); return true; }
+          }
+          current = current.return;
+        }
+        return opts.intoView ? tryScroll(anchor, false) : false;
+      }
       function findTestId(fiber) {
         if (!fiber) return null;
         var props = fiber.memoizedProps;
@@ -354,7 +370,7 @@ const COMMANDS = {
           if (scrolled) return;
           if (opts.testId) {
             var anchor = findTestId(r.current);
-            if (anchor) scrolled = tryScroll(anchor, false);
+            if (anchor) scrolled = tryScrollNear(anchor);
           } else {
             scrolled = tryScroll(r.current);
           }

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -30,17 +30,23 @@ function fetchJSONOnce(url) {
   });
 }
 
-async function fetchJSON(url) {
+async function fetchJSON(url, acceptResponse) {
   let lastError;
+  let lastResponse;
   for (let attempt = 1; attempt <= FETCH_RETRIES; attempt++) {
     try {
-      return await fetchJSONOnce(url);
+      const response = await fetchJSONOnce(url);
+      lastError = undefined;
+      lastResponse = response;
+      if (!acceptResponse || await acceptResponse(response)) return response;
     } catch (error) {
       lastError = error;
-      if (attempt === FETCH_RETRIES) break;
-      await new Promise((resolve) => setTimeout(resolve, attempt * 1000));
     }
+    if (attempt === FETCH_RETRIES) break;
+    await new Promise((resolve) => setTimeout(resolve, attempt * 1000));
   }
+  if (lastError !== undefined) throw lastError;
+  if (lastResponse !== undefined) return lastResponse;
   throw lastError;
 }
 
@@ -103,6 +109,19 @@ function rankRuntimeCandidates(targets) {
   return candidates;
 }
 
+function targetDeviceIdentity(target) {
+  try {
+    const device = new URL(target.webSocketDebuggerUrl).searchParams.get('device');
+    if (device) return device;
+  } catch {
+    // Fall back to Metro's display identity when the debugger URL is malformed.
+  }
+  // Without Metro's device id there is no safe way to collapse same-name pages
+  // into one physical device. Keep each debugger target distinct and fail closed
+  // on ambiguity instead of silently choosing between devices.
+  return target.webSocketDebuggerUrl || target.deviceName || '';
+}
+
 /**
  * Discover the Hermes CDP WebSocket URL from Metro's /json/list endpoint.
  *
@@ -114,9 +133,34 @@ function rankRuntimeCandidates(targets) {
  */
 async function discoverTarget(port) {
   const listUrl = `http://localhost:${port}/json/list`;
+  const androidTargetName = loadAndroidTargetDeviceName();
+  const androidDevice = loadAndroidDevice();
+  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
+  const androidPinned = Boolean(androidTargetName || androidDevice);
+  const simName = loadSimulatorName();
+  const matchesAndroidPin = (target) => androidTargetName
+    ? target.deviceName !== simName &&
+      (target.deviceName === androidTargetName ||
+        (target.deviceName != null && target.deviceName.startsWith(androidTargetName)))
+    : target.deviceName === androidDevice;
+  let acceptedPinnedCandidate;
   let targets;
   try {
-    targets = await fetchJSON(listUrl);
+    targets = await fetchJSON(
+      listUrl,
+      androidPinned
+        ? async (response) => {
+          const pinnedCandidates = rankRuntimeCandidates(response).filter(matchesAndroidPin);
+          for (const candidate of pinnedCandidates) {
+            if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+              acceptedPinnedCandidate = candidate;
+              return true;
+            }
+          }
+          return false;
+        }
+        : undefined,
+    );
   } catch (e) {
     throw coded(
       new Error(`Cannot reach Metro at ${listUrl}. Is Metro running?\n  ${e.message}`),
@@ -137,17 +181,11 @@ async function discoverTarget(port) {
   //     from the adb serial via `adb -s <serial> shell getprop ro.product.model`.
   //     Example: "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36".
   //   ANDROID_DEVICE — exact user-specified Metro deviceName.
-  const androidTargetName = loadAndroidTargetDeviceName();
-  const androidDevice = loadAndroidDevice();
-  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
-  const androidPinned = Boolean(androidTargetName || androidDevice);
-
   // Filter by simulator name if IOS_SIMULATOR is set — but never when an android
   // pin is present: dual-platform slots carry an ambient IOS_SIMULATOR in their
   // context, and letting it win here sends a pinned android action to the iOS
   // target. No-match keeps the full candidate set (ambient sim configs tolerate a
   // sim that is not currently attached).
-  const simName = loadSimulatorName();
   if (simName && !androidPinned && candidates.length > 1) {
     const deviceFiltered = candidates.filter(
       (t) => t.deviceName === simName,
@@ -163,7 +201,7 @@ async function discoverTarget(port) {
   // remained; the pin was ignored and the recipe drove the simulator). When a
   // device is pinned, we MUST NOT silently fall back to another target; an
   // unmatchable pin fails fast with diagnostics.
-  if (androidPinned && candidates.length > 0) {
+  if (androidPinned) {
     let androidFiltered = [];
 
     if (androidTargetName) {
@@ -171,20 +209,19 @@ async function discoverTarget(port) {
       // /json/list has no explicit platform field, so scope the ANDROID pin by
       // excluding the one iOS identity we do know (the pinned simulator name) —
       // a simulator named to shadow a model string must not satisfy an android pin.
-      androidFiltered = candidates.filter(
-        (t) => t.deviceName !== simName &&
-               (t.deviceName === androidTargetName ||
-                (t.deviceName != null && t.deviceName.startsWith(androidTargetName))),
-      );
-      if (androidFiltered.length > 1) {
+      androidFiltered = candidates.filter(matchesAndroidPin);
+      const matchingDeviceIdentities = [...new Set(
+        androidFiltered.map(targetDeviceIdentity),
+      )];
+      if (matchingDeviceIdentities.length > 1) {
         // Two same-model devices produce identical Metro model prefixes — the pin
-        // is genuinely ambiguous; picking one silently is exactly the bug this
-        // path exists to prevent.
+        // is genuinely ambiguous. Native + JS pages share the same Metro device
+        // identity and must remain available for probing.
         const ambiguousList = androidFiltered
-          .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
+          .map((target) => `  deviceName=${JSON.stringify(target.deviceName || '')} ws=${target.webSocketDebuggerUrl || ''}`)
           .join('\n');
         throw coded(new Error(
-          `Pinned Android device is ambiguous: model '${androidTargetName}' matches ${androidFiltered.length} Metro targets.\n` +
+          `Pinned Android device is ambiguous: model '${androidTargetName}' matches ${matchingDeviceIdentities.length} Metro devices.\n` +
           `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
           `  Matching Metro targets:\n${ambiguousList}\n` +
           `  Set ANDROID_DEVICE to the exact Metro deviceName to disambiguate.`,
@@ -206,7 +243,7 @@ async function discoverTarget(port) {
       candidates = androidFiltered;
     } else if (androidDevice) {
       // Exact Metro deviceName match when the user set ANDROID_DEVICE directly.
-      androidFiltered = candidates.filter((t) => t.deviceName === androidDevice);
+      androidFiltered = candidates.filter(matchesAndroidPin);
       if (androidFiltered.length === 0) {
         // Pinned by exact Metro name but no candidate matched — fail fast.
         const candidateList = targets
@@ -233,6 +270,17 @@ async function discoverTarget(port) {
     );
   }
 
+  if (acceptedPinnedCandidate) {
+    for (const candidate of candidates) {
+      if (candidate.webSocketDebuggerUrl === acceptedPinnedCandidate.webSocketDebuggerUrl) {
+        return {
+          wsUrl: acceptedPinnedCandidate.webSocketDebuggerUrl,
+          deviceName: acceptedPinnedCandidate.deviceName || '',
+        };
+      }
+    }
+  }
+
   // Sort by page number descending (JS runtime has higher page number than C++
   // native). rankRuntimeCandidates output arrives pre-sorted; this re-sort is
   // load-bearing only when the raw targets.filter() fallback above repopulated
@@ -251,6 +299,18 @@ async function discoverTarget(port) {
     }
   }
 
+  if (androidPinned) {
+    const candidateList = candidates
+      .map((target) => `  deviceName=${JSON.stringify(target.deviceName || '')} ws=${target.webSocketDebuggerUrl || ''}`)
+      .join('\n');
+    throw coded(new Error(
+      `Pinned Android device has no responding __AGENTIC__ JS runtime after ${FETCH_RETRIES} discovery attempt(s).\n` +
+      `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
+      `  Matching non-agentic targets:\n${candidateList}\n` +
+      `  The native C++ page is not a valid recipe target; wait for Android Hermes to re-register or relaunch the Android app.`,
+    ), BRIDGE_ERROR_CODES.NO_TARGET);
+  }
+
   // Fallback: return highest page number (most likely the JS runtime)
   return { wsUrl: candidates[0].webSocketDebuggerUrl, deviceName: candidates[0].deviceName || '' };
 }

package/dist/adapters/mobile/prepare.js

@@ -60,6 +60,20 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   const iosAccessibilityChanged = platform === "ios" && report.decision !== "unknown" && enableIosAccessibility(json);
+  if (report.decision === "ready" && clearMetro) {
+    const launch = await dispatchActionSequence(
+      withAppRestart(
+        launchActions(path.resolve(target), true),
+        restartApp || iosAccessibilityChanged
+      ),
+      target,
+      platform,
+      json,
+      preflightMode,
+      opts.watcherPort
+    );
+    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch;
+  }
   if (report.decision === "ready") {
     if (restartApp || iosAccessibilityChanged) {
       const launch2 = await dispatchActionSequence(

package/dist/adapters/mobile/video-recorder.js

@@ -0,0 +1,282 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  ANDROID_RECORDING_TARGET_PREFIX,
+  IOS_SIMULATOR_RECORDING_TARGET_PREFIX
+} from "../../recording-target.js";
+const RECORDING_START_TIMEOUT_MS = 5e3;
+const RECORDING_STOP_TIMEOUT_MS = 1e4;
+const RECORDING_TIME_LIMIT_SECONDS = 180;
+function createAndroidVideoRecorder(serial) {
+  return {
+    name: "adb-screenrecord",
+    platform: "android",
+    doctor: async () => doctorAndroidRecorder(serial),
+    start: (request) => startAndroidRecording(serial, request)
+  };
+}
+function createIosSimulatorVideoRecorder(simulator) {
+  return {
+    name: "simctl-recordVideo",
+    platform: "ios",
+    doctor: async () => doctorIosSimulatorRecorder(simulator),
+    start: (request) => startIosSimulatorRecording(simulator, request)
+  };
+}
+function doctorIosSimulatorRecorder(simulator) {
+  const state = runSimctl(["getenv", simulator, "SIMULATOR_UDID"]);
+  if (state.status !== 0 || !state.stdout.trim()) {
+    return {
+      ok: false,
+      code: "ios_simulator_unavailable",
+      message: `iOS simulator ${simulator} is not booted: ${commandFailure(state)}`,
+      suggestedFix: `Boot ${simulator} and run xcrun simctl getenv ${simulator} SIMULATOR_UDID.`
+    };
+  }
+  return {
+    ok: true,
+    code: "ok",
+    message: `iOS simulator recording is ready on ${simulator}.`
+  };
+}
+async function startIosSimulatorRecording(simulator, request) {
+  const targetSimulator = iosTargetSimulator(request);
+  if (targetSimulator !== simulator) {
+    throw new Error(
+      `iOS recording target ${targetSimulator ?? "<missing>"} does not match selected simulator ${simulator}.`
+    );
+  }
+  fs.mkdirSync(path.dirname(request.outputPath), { recursive: true });
+  const child = spawn(
+    "xcrun",
+    [
+      "simctl",
+      "io",
+      simulator,
+      "recordVideo",
+      "--codec=h264",
+      "--force",
+      request.outputPath
+    ],
+    { stdio: ["ignore", "pipe", "pipe"] }
+  );
+  const output = [];
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => output.push(String(chunk)));
+  child.stderr?.on("data", (chunk) => output.push(String(chunk)));
+  await waitForIosRecordingStart(child, output);
+  let stopped = false;
+  return {
+    async stop() {
+      if (stopped) {
+        throw new Error(
+          `iOS simulator recording on ${simulator} was already stopped.`
+        );
+      }
+      stopped = true;
+      child.kill("SIGINT");
+      await waitForChildExit(
+        child,
+        RECORDING_STOP_TIMEOUT_MS,
+        "iOS simulator recordVideo"
+      );
+      const recorded = fs.statSync(request.outputPath);
+      if (!recorded.isFile() || recorded.size <= 0) {
+        throw new Error(
+          `iOS simulator recording output is empty: ${request.outputPath}`
+        );
+      }
+      return {
+        recorder: {
+          name: "simctl-recordVideo",
+          platform: "ios",
+          target: { selector: "simulator", value: simulator }
+        }
+      };
+    }
+  };
+}
+function doctorAndroidRecorder(serial) {
+  const state = runAdb(serial, ["get-state"]);
+  if (state.status !== 0 || state.stdout.trim() !== "device") {
+    return {
+      ok: false,
+      code: "android_device_unavailable",
+      message: `Android device ${serial} is not ready: ${commandFailure(state)}`,
+      suggestedFix: `Run adb -s ${serial} get-state and reconnect or unlock the device.`
+    };
+  }
+  const screenrecord = runAdb(serial, ["shell", "screenrecord", "--help"]);
+  if (screenrecord.status !== 0) {
+    return {
+      ok: false,
+      code: "android_screenrecord_unavailable",
+      message: `Android screenrecord is unavailable on ${serial}: ${commandFailure(screenrecord)}`,
+      suggestedFix: `Run adb -s ${serial} shell screenrecord --help.`
+    };
+  }
+  return {
+    ok: true,
+    code: "ok",
+    message: `Android screen recording is ready on ${serial}.`
+  };
+}
+async function startAndroidRecording(serial, request) {
+  const targetSerial = androidTargetSerial(request);
+  if (targetSerial !== serial) {
+    throw new Error(
+      `Android recording target ${targetSerial ?? "<missing>"} does not match selected device ${serial}.`
+    );
+  }
+  const existingPid = screenrecordPid(serial);
+  if (existingPid) {
+    throw new Error(
+      `Android screenrecord is already running on ${serial} (pid ${existingPid}). Stop that recording before retrying.`
+    );
+  }
+  const remotePath = `/sdcard/Download/mm-harness-recipe-${Date.now()}-${process.pid}.mp4`;
+  const child = spawn(
+    "adb",
+    [
+      "-s",
+      serial,
+      "shell",
+      "screenrecord",
+      "--time-limit",
+      String(RECORDING_TIME_LIMIT_SECONDS),
+      remotePath
+    ],
+    { stdio: ["ignore", "pipe", "pipe"] }
+  );
+  const stderr = [];
+  child.stderr?.setEncoding("utf8");
+  child.stderr?.on("data", (chunk) => stderr.push(String(chunk)));
+  child.stdout?.resume();
+  const recorderPid = await waitForScreenrecordStart(serial, child, stderr);
+  let stopped = false;
+  return {
+    async stop() {
+      if (stopped) {
+        throw new Error(`Android screen recording on ${serial} was already stopped.`);
+      }
+      stopped = true;
+      try {
+        stopRemoteScreenrecord(serial, recorderPid);
+        await waitForChildExit(
+          child,
+          RECORDING_STOP_TIMEOUT_MS,
+          "Android screenrecord"
+        );
+        fs.mkdirSync(path.dirname(request.outputPath), { recursive: true });
+        const pull = runAdb(serial, ["pull", remotePath, request.outputPath]);
+        if (pull.status !== 0) {
+          throw new Error(
+            `Could not pull Android recording from ${serial}: ${commandFailure(pull)}`
+          );
+        }
+        const output = fs.statSync(request.outputPath);
+        if (!output.isFile() || output.size <= 0) {
+          throw new Error(`Android recording output is empty: ${request.outputPath}`);
+        }
+        return {
+          recorder: {
+            name: "adb-screenrecord",
+            platform: "android",
+            target: { selector: "adb-serial", value: serial }
+          }
+        };
+      } finally {
+        runAdb(serial, ["shell", "rm", "-f", remotePath]);
+      }
+    }
+  };
+}
+function androidTargetSerial(request) {
+  if (request.target.kind !== "window-id") return void 0;
+  if (!request.target.windowId.startsWith(ANDROID_RECORDING_TARGET_PREFIX)) return void 0;
+  return request.target.windowId.slice(ANDROID_RECORDING_TARGET_PREFIX.length) || void 0;
+}
+async function waitForScreenrecordStart(serial, child, stderr) {
+  const deadline = Date.now() + RECORDING_START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(
+        `Android screenrecord exited before capture started (exit ${child.exitCode}): ${stderr.join("").trim() || "no recorder output"}`
+      );
+    }
+    const pid = screenrecordPid(serial);
+    if (pid) return pid;
+    await sleep(100);
+  }
+  child.kill("SIGTERM");
+  throw new Error(
+    `Android screenrecord did not start on ${serial} within ${RECORDING_START_TIMEOUT_MS}ms.`
+  );
+}
+function stopRemoteScreenrecord(serial, pid) {
+  const stop = runAdb(serial, ["shell", "kill", "-2", pid]);
+  if (stop.status !== 0 && screenrecordPid(serial) === pid) {
+    throw new Error(`Could not stop Android screenrecord pid ${pid}: ${commandFailure(stop)}`);
+  }
+}
+async function waitForChildExit(child, timeoutMs, recorderName) {
+  if (child.exitCode !== null) return;
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`${recorderName} did not stop within ${timeoutMs}ms.`));
+    }, timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+}
+async function waitForIosRecordingStart(child, output) {
+  const deadline = Date.now() + RECORDING_START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(
+        `iOS simulator recordVideo exited before capture started (exit ${child.exitCode}): ${output.join("").trim() || "no recorder output"}`
+      );
+    }
+    if (output.join("").includes("Recording started")) return;
+    await sleep(100);
+  }
+  if (child.exitCode === null) return;
+  throw new Error(
+    `iOS simulator recordVideo did not start within ${RECORDING_START_TIMEOUT_MS}ms.`
+  );
+}
+function iosTargetSimulator(request) {
+  if (request.target.kind !== "window-id") return void 0;
+  if (!request.target.windowId.startsWith(
+    IOS_SIMULATOR_RECORDING_TARGET_PREFIX
+  )) {
+    return void 0;
+  }
+  return request.target.windowId.slice(IOS_SIMULATOR_RECORDING_TARGET_PREFIX.length) || void 0;
+}
+function screenrecordPid(serial) {
+  const result = runAdb(serial, ["shell", "pidof", "screenrecord"]);
+  if (result.status !== 0) return void 0;
+  return result.stdout.trim().split(/\s+/u).find(Boolean);
+}
+function runAdb(serial, args) {
+  return spawnSync("adb", ["-s", serial, ...args], { encoding: "utf8" });
+}
+function runSimctl(args) {
+  return spawnSync("xcrun", ["simctl", ...args], { encoding: "utf8" });
+}
+function commandFailure(result) {
+  return result.stderr.trim() || result.stdout.trim() || `exit ${result.status ?? "unknown"}`;
+}
+function sleep(durationMs) {
+  return new Promise((resolve) => setTimeout(resolve, durationMs));
+}
+export {
+  createAndroidVideoRecorder,
+  createIosSimulatorVideoRecorder
+};