@deeeed/metamask-harness 0.10.0 → 0.11.0

package/dist/runner.js

@@ -1,8 +1,9 @@
 import { execSync } from "node:child_process";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
+import { resolveMetaMaskMobileLifecycleTarget } from "./app-lifecycle.js";
 import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
 import { createMetaMaskRecordingTargetProvider } from "./recording-target.js";
-import { importRecipeHarness, importRecipeHarnessRuntimeCdp, importRecipeHarnessRuntimeReactNativeBridge, runnerDir } from "./paths.js";
+import { importRecipeHarness, importRecipeHarnessAppLifecycle, importRecipeHarnessRuntimeCdp, importRecipeHarnessRuntimeReactNativeBridge, runnerDir } from "./paths.js";
 async function createMetaMaskMobileRunner(options = {}) {
   return createMetaMaskRunner(
     "mobile",
@@ -23,13 +24,14 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   } = await importRecipeHarness();
   const { createCdpWebUiTransport } = await importRecipeHarnessRuntimeCdp();
   const { createReactNativeBridgeUiTransport } = await importRecipeHarnessRuntimeReactNativeBridge();
+  const { createAppLifecycleAdapters } = await importRecipeHarnessAppLifecycle();
   const actions = [
     ...actionManifest.supported_official_actions,
     ...(actionManifest.custom_actions ?? []).map((entry) => entry.name)
   ];
   const declaredActions = new Set(actions);
   const core = createStandardCoreAdapters({ actions });
-  const projectOwnedOfficialActions = /* @__PURE__ */ new Set(["app.status"]);
+  const projectOwnedOfficialActions = /* @__PURE__ */ new Set(["app.status", "app.lifecycle"]);
   const ui = createStandardUiAdapters({
     actions: actions.filter((action) => !projectOwnedOfficialActions.has(action)),
     transport: createMetaMaskUiTransport(adapter, {
@@ -38,14 +40,18 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     })
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
+  const lifecycle = adapter === "mobile" ? createAppLifecycleAdapters({
+    actions,
+    targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
+  }) : [];
   const custom = createMetaMaskAdapters(adapter).filter(
-    (entry) => declaredActions.has(entry.action) && !existing.has(entry.action)
+    (entry) => declaredActions.has(entry.action) && !existing.has(entry.action) && !lifecycle.some((lifecycleEntry) => lifecycleEntry.action === entry.action)
   );
   const autoHudDisabled = process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false";
   const logger = options.quietStdout ? new console.Console(process.stderr) : console;
   return createRecipeRunner({
     actionManifest,
-    adapters: [...core, ...ui, ...custom],
+    adapters: [...core, ...ui, ...lifecycle, ...custom],
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter)

package/docs/CLI-SPEC.md

@@ -439,7 +439,7 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ## `--device <id>` — first-class mobile device targeting (REAL)
 
-`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. Pass the **adb serial** for Android (from `adb devices`) or the **UDID / simulator name** for iOS. The harness resolves the adb serial to the Metro CDP target identity internally — users never need to know or set `ANDROID_DEVICE='Pixel 6 - 16 - API 36'`.
+`--device` is the uniform mobile device selector on `run`, `call`, `doctor`, and `fixtures`. Pass the **adb serial** for Android (from `adb devices`) or the **UDID / simulator name** for iOS. The harness resolves the adb serial to the Metro CDP target identity internally — users never need to know or set `ANDROID_DEVICE='Pixel 6 - 16 - API 36'`.
 
 **Internal Android identity mapping**: `ADB_SERIAL` / `ANDROID_SERIAL` carry the raw adb serial. The bridge resolves the device model via `adb -s <serial> shell getprop ro.product.model` and propagates it as `ANDROID_TARGET_DEVICE_NAME`. Target-discovery uses `ANDROID_TARGET_DEVICE_NAME` for Metro `deviceName` prefix matching (e.g. `"Pixel 6"` matches `"Pixel 6 - 16 - API 36"`). When the pinned model cannot be matched to any Metro `/json/list` candidate and multiple candidates exist, the bridge fails fast with a diagnostic listing every candidate's `deviceName` — it never silently selects the wrong device. iOS UDID/simulator name → `IOS_SIMULATOR` (unchanged).
 
@@ -447,6 +447,7 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 |---|---|---|
 | `run` / `call` | resolve id → set serial/simulator env; proceed | **ambiguity gate:** >1 connected mobile device (across both android and ios, counting only targetable ones: android state `device`, iOS state `Booted`) → fail fast (exit 2), listing connected devices and `--device <id>` hints. Exactly one targetable (or zero — existing engine errors speak) → unchanged behavior. |
 | `doctor` | resolve id → set env | no gate — doctor is diagnostic and **reports** the device list (`devices[]`) instead. |
+| `fixtures` | resolve id → set serial/simulator env before sync/set and recovery relaunch | no gate — preserves existing single-device and ambient slot behavior. |
 
 `--device` on the **extension/core** adapter is a teaching usage error (those adapters have no device to target). `run --plan` is static (touches no device) and is exempt from the gate.
 

package/docs/recipe-libraries.md

@@ -230,6 +230,16 @@ mm-harness run my-perps-performance \
   --library mydev=~/my-recipes \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts
 
+# Canonical start-state variants — same installed app, no rebuild.
+mm-harness run app-lifecycle-android-smoke \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/lifecycle-smoke
+mm-harness run perps-performance-warm-start \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/warm
+mm-harness run perps-performance-background-resume \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/background
+mm-harness run perps-performance-cold-start \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/cold
+
 # Per-node durations to diff across runs (trace.json is an array of entries, or
 # { metadata, entries: [...] }; each entry carries nodeId + durationMs):
 node -e 'const t=require("./artifacts/trace.json"); \
@@ -239,6 +249,15 @@ node -e 'const t=require("./artifacts/trace.json"); \
 A miss with `--library` names the sources that were searched, so you can tell at a
 glance whether a typo or a missing library entry caused the failure.
 
+Run `app-lifecycle-android-smoke` first when validating a new Android slot; it
+isolates lifecycle control from wallet setup and Perps navigation. The start-state
+variants use the standard outer `app.lifecycle` action. Every
+variant begins with `app.status` so `trace.json` records an idempotent start
+marker before lifecycle setup and Perps timing nodes. Android background resume
+sends HOME, then relaunches through the Expo dev-client deep link. Cold start
+force-stops the installed package, then launches the same build through the deep
+link.
+
 ### The measured-flow pattern
 
 Five rules keep timings meaningful and diffable:

package/library/actions/mobile/platform/bridge.mjs

@@ -71,10 +71,14 @@ export async function bridgeEnv(input) {
   const watcherPort = target.watcherPort;
   const simulator = target.iosSimulator;
   const androidDevice = target.androidDevice;
+  const androidTargetDeviceName = target.androidTargetDeviceName;
   const adbSerial = target.adbSerial;
   if (watcherPort !== undefined && watcherPort !== null && String(watcherPort) !== '') env.WATCHER_PORT = String(watcherPort);
   if (simulator !== undefined && simulator !== null && String(simulator) !== '') env.IOS_SIMULATOR = String(simulator);
   if (androidDevice !== undefined && androidDevice !== null && String(androidDevice) !== '') env.ANDROID_DEVICE = String(androidDevice);
+  if (androidTargetDeviceName !== undefined && androidTargetDeviceName !== null && String(androidTargetDeviceName) !== '') {
+    env.ANDROID_TARGET_DEVICE_NAME = String(androidTargetDeviceName);
+  }
   if (adbSerial !== undefined && adbSerial !== null && String(adbSerial) !== '') {
     env.ADB_SERIAL = String(adbSerial);
     env.ANDROID_SERIAL = String(adbSerial);
@@ -92,6 +96,8 @@ export async function bridgeEnv(input) {
     if (model) {
       env.ANDROID_TARGET_DEVICE_NAME = model;
     }
+  }
+  if (serialStr) {
     // ANDROID_DEVICE === ADB_SERIAL is the explicit --device android pin shape
     // (device-target.ts / launch --device). Slots hosting BOTH platforms carry an
     // ambient IOS_SIMULATOR in their context env, which spreads over process.env
@@ -113,8 +119,14 @@ function resolveMobileTarget(input) {
   const watcherPort = input.node?.watcher_port ?? input.node?.metro_port ?? input.node?.cdp_port ?? contextEnv.WATCHER_PORT ?? contextEnv.CDP_PORT ?? contextEnv.RECIPE_CDP_PORT ?? process.env.WATCHER_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
   const iosSimulator = input.node?.simulator ?? input.node?.ios_simulator ?? contextEnv.IOS_SIMULATOR ?? process.env.IOS_SIMULATOR;
   const androidDevice = input.node?.android_device ?? contextEnv.ANDROID_DEVICE ?? process.env.ANDROID_DEVICE;
+  const androidTargetDeviceName = input.node?.android_target_device_name ?? input.node?.androidTargetDeviceName ?? contextEnv.ANDROID_TARGET_DEVICE_NAME ?? process.env.ANDROID_TARGET_DEVICE_NAME;
   const adbSerial = input.node?.adb_serial ?? contextEnv.ADB_SERIAL ?? contextEnv.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL ?? androidDevice;
-  return { watcherPort, iosSimulator, androidDevice, adbSerial };
+  return { watcherPort, iosSimulator, androidDevice, androidTargetDeviceName, adbSerial };
+}
+
+function androidDeviceNameMatches(deviceName, targetName) {
+  if (!targetName) return false;
+  return deviceName === targetName || deviceName.startsWith(`${targetName} -`);
 }
 
 // Select THIS action's entry from a multi-target bridge `status` reply (the bridge
@@ -124,21 +136,31 @@ function resolveMobileTarget(input) {
 // against Metro deviceNames (which are model descriptors, never serials), so a
 // pinned android run selected the iOS entry on dual-platform slots.
 export function selectBridgeStatusEntry(status, input) {
-  if (!Array.isArray(status)) {
-    return status && typeof status === 'object' ? status : null;
-  }
-  const entries = status.filter((entry) => entry && typeof entry === 'object');
+  const entries = Array.isArray(status)
+    ? status.filter((entry) => entry && typeof entry === 'object')
+    : (status && typeof status === 'object' ? [status] : []);
   if (entries.length === 0) return null;
   const target = resolveMobileTarget(input);
   const adbSerial = target.adbSerial != null ? String(target.adbSerial) : '';
   const androidDevice = target.androidDevice != null ? String(target.androidDevice) : '';
+  const androidTargetDeviceName = target.androidTargetDeviceName != null ? String(target.androidTargetDeviceName) : '';
   const iosSimulator = target.iosSimulator != null ? String(target.iosSimulator) : '';
 
   // Explicit android pin shape (--device <serial> sets ANDROID_DEVICE === ADB_SERIAL).
   // Checked BEFORE the simulator identity: dual-platform slots inject an ambient
   // IOS_SIMULATOR that must not capture a pinned android action.
-  if (adbSerial && androidDevice === adbSerial) {
+  if (adbSerial && (androidTargetDeviceName || androidDevice === adbSerial || !androidDevice)) {
     const android = entries.filter((entry) => entry.platform === 'android');
+    if (androidTargetDeviceName) {
+      const matchesAndroidTargetNameEntry = (entry) => {
+        const deviceName = String(entry.deviceName ?? '');
+        return androidDeviceNameMatches(deviceName, androidTargetDeviceName);
+      };
+      const byName = android.filter(matchesAndroidTargetNameEntry);
+      if (byName.length === 1) return byName[0];
+      const byModelName = entries.filter(matchesAndroidTargetNameEntry);
+      if (byModelName.length === 1) return byModelName[0];
+    }
     if (android.length === 1) return android[0];
     if (android.length > 1) {
       // Two android targets can't be told apart by serial here (Metro deviceNames
@@ -160,7 +182,7 @@ export function selectBridgeStatusEntry(status, input) {
   }
   if (androidDevice) {
     const byName = entries.find(
-      (entry) => entry.deviceName === androidDevice || String(entry.deviceName ?? '').startsWith(androidDevice),
+      (entry) => androidDeviceNameMatches(String(entry.deviceName ?? ''), androidDevice),
     );
     if (byName) return byName;
   }

package/library/actions/mobile/wallet/ensure_unlocked.mjs

@@ -41,30 +41,87 @@ async function status(input) {
   return bridgeCommand(input, ['status']);
 }
 
+async function waitForTargetStatus(input, timeoutMs = 20000) {
+  const deadline = Date.now() + timeoutMs;
+  let last = null;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      last = await status(input);
+      const selected = selectedStatus(last, input);
+      if (selected?.agenticPresent === true) return last;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  throw new Error(
+    `Timed out waiting for pinned Mobile agentic bridge target; last status was ${JSON.stringify(last)}; last error was ${String(lastError?.message ?? lastError)}`,
+  );
+}
+
 async function waitForUnlocked(input, timeoutMs = 15000) {
   const deadline = Date.now() + timeoutMs;
   let last = null;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      last = await status(input);
+      if (selectedAccount(last, input) && routeName(last, input) !== 'Login') return last;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`Timed out waiting for Mobile wallet unlock; last status was ${JSON.stringify(last)}; last error was ${String(lastError?.message ?? lastError)}`);
+}
+
+function isUnlockedStatus(status, input) {
+  return Boolean(selectedAccount(status, input)) && routeName(status, input) !== 'Login';
+}
+
+async function waitForStableUnlocked(input, initialStatus, stableMs = 750) {
+  if (!isUnlockedStatus(initialStatus, input)) return null;
+  const deadline = Date.now() + stableMs;
+  let last = initialStatus;
+  let transientDrops = 0;
   while (Date.now() < deadline) {
-    last = await status(input);
-    if (selectedAccount(last, input) && routeName(last, input) !== 'Login') return last;
     await new Promise((resolve) => setTimeout(resolve, 250));
+    try {
+      last = await status(input);
+      if (!isUnlockedStatus(last, input)) {
+        if (routeName(last, input) === 'Login') return null;
+        transientDrops += 1;
+        if (transientDrops > 2) return null;
+        continue;
+      }
+      transientDrops = 0;
+    } catch {
+      // Recovery is correct: a bridge error during the stability window is the
+      // same signal as an unlocked-state drop — count it toward the transient
+      // threshold; exceeding it returns null so the caller runs the real
+      // password unlock instead of reporting a false alreadyUnlocked.
+      transientDrops += 1;
+      if (transientDrops > 2) return null;
+    }
   }
-  throw new Error(`Timed out waiting for Mobile wallet unlock; last status was ${JSON.stringify(last)}`);
+  return last;
 }
 
 runAdapter(async (input) => {
-  const before = await status(input);
+  const before = await waitForTargetStatus(input, Number(input.node?.target_timeout_ms ?? 20000));
   if (!selectedAccount(before, input) && routeName(before, input) !== 'Login') {
     throw new Error(
       `No wallet onboarded on this device (route ${routeName(before, input) || 'unknown'}, empty wallet status) — unlock has nothing to unlock.\n  Next: mm-harness fixtures set   # applies the fixture wallet, then re-run: mm-harness call ensure_unlocked`,
     );
   }
-  if (selectedAccount(before, input) && routeName(before, input) !== 'Login') {
+  const stableBefore = await waitForStableUnlocked(input, before, Number(input.node?.stable_unlocked_ms ?? 750));
+  if (stableBefore) {
     return {
       action: input.action,
       unlocked: true,
       alreadyUnlocked: true,
-      account: selectedAccount(before, input),
+      account: selectedAccount(stableBefore, input),
       redacted: true,
       proofPath: 'agentic-wallet-status',
     };
@@ -74,11 +131,12 @@ runAdapter(async (input) => {
   try {
     const result = await bridgeCommand(input, ['unlock', String(password)]);
     const after = await waitForUnlocked(input, Number(input.node?.unlock_timeout_ms ?? 15000));
+    const stableAfter = await waitForStableUnlocked(input, after, Number(input.node?.stable_unlocked_ms ?? 750)) ?? after;
     return {
       action: input.action,
       unlocked: Boolean(result?.ok ?? result?.unlocked ?? true),
-      account: selectedAccount(after, input),
-      route: selectedStatus(after, input)?.route ?? null,
+      account: selectedAccount(stableAfter, input),
+      route: selectedStatus(stableAfter, input)?.route ?? null,
       redacted: true,
       proofPath: 'agentic-wallet-unlock',
     };

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

@@ -19,6 +19,7 @@
     "ui.scroll",
     "ui.wait_for",
     "ui.screenshot",
+    "app.lifecycle",
     "app.status",
     "app.hud",
     "cdp.target"
@@ -213,6 +214,19 @@
         }
       ]
     },
+    "app.lifecycle": {
+      "description": "Drive outer mobile app lifecycle for deterministic performance start states without rebuilding: foreground/launch, background, terminate, or restart the installed app.",
+      "examples": [
+        {
+          "node": {
+            "action": "app.lifecycle",
+            "command": "background",
+            "settle_ms": 1000,
+            "intent": "Send the selected Android device to the launcher before a warm-resume measurement"
+          }
+        }
+      ]
+    },
     "assert_file": {
       "description": "Assert that a project file exists and optionally contains text.",
       "examples": [
@@ -1999,6 +2013,10 @@
       "action": "ui.screenshot",
       "implementation": "@farmslot/recipe-harness/runtime/react-native-bridge"
     },
+    {
+      "action": "app.lifecycle",
+      "implementation": "@farmslot/recipe-harness/adapters/app-lifecycle"
+    },
     {
       "action": "app.status",
       "implementation": "@metamask/recipe-runner/platform-status"

package/library/recipes/app-lifecycle-android-smoke.mobile.recipe.json

@@ -0,0 +1,87 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Android lifecycle smoke",
+  "description": "Isolated on-device proof for the standard outer app.lifecycle action on Android. Setup cold-relaunches the installed app through the Expo dev-client deep link without rebuilding and proves the React Native bridge is reachable. The main workflow then backgrounds the installed app, foregrounds it again, proves the bridge is reachable after resume, and captures a screenshot.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after setup relaunch",
+    "detail": "Read-only start-state marker after setup has made the Android bridge reachable."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "terminate-before",
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "terminate",
+          "settle_ms": 3000,
+          "intent": "Terminate the installed Android app before lifecycle smoke",
+          "detail": "Force-stops stale foreground instances that may have no React Native debug target."
+        },
+        {
+          "id": "launch-before",
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "launch",
+          "settle_ms": 15000,
+          "intent": "Launch the installed Android app through the Expo dev-client deep link from a cold process",
+          "detail": "Uses the selected adb serial, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "bridge-before",
+          "action": "cdp.target",
+          "require_reachable": true,
+          "intent": "Confirm the mobile React Native debug bridge is reachable after setup relaunch",
+          "detail": "This proves setup can recover a missing Android bridge target before the background-resume proof."
+        }
+      ],
+      "entry": "background-app",
+      "nodes": {
+        "background-app": {
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "background",
+          "settle_ms": 1000,
+          "intent": "Put the selected Android device on the launcher",
+          "detail": "Uses adb HOME through the shared Farmslot lifecycle adapter.",
+          "flow": "lifecycle",
+          "next": "foreground-app"
+        },
+        "foreground-app": {
+          "action": "app.lifecycle",
+          "platform": "android",
+          "command": "foreground",
+          "settle_ms": 15000,
+          "intent": "Foreground the installed Android app through the Expo dev-client deep link",
+          "detail": "Uses the selected adb serial, Metro port, and installed package; it does not rebuild.",
+          "flow": "lifecycle",
+          "next": "bridge-after"
+        },
+        "bridge-after": {
+          "action": "cdp.target",
+          "require_reachable": true,
+          "intent": "Confirm the mobile React Native debug bridge recovered after foregrounding",
+          "detail": "This is the capability gate before running Perps recipes that depend on CDP/bridge control.",
+          "flow": "lifecycle",
+          "next": "screenshot-after"
+        },
+        "screenshot-after": {
+          "action": "ui.screenshot",
+          "path": "screenshots/app-lifecycle-android-smoke.png",
+          "intent": "Capture the app after Android lifecycle foreground",
+          "detail": "Visual proof that the selected device is displaying the relaunched app.",
+          "flow": "evidence",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the isolated Android lifecycle smoke",
+          "detail": "If this passes, lifecycle is proven independently of wallet and Perps actions.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps-performance-background-resume.mobile.recipe.json

@@ -0,0 +1,72 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps performance flow - background resume",
+  "description": "Measured Perps flow from a deterministic background-resume start state. Setup sends the installed app to the background, foregrounds it through the Expo dev-client deep link without rebuilding, and unlocks if needed. startState records the stable status. The measured workflow is only Perps list -> state -> BTC detail.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after background-resume setup",
+    "detail": "Read-only start-state marker after lifecycle and wallet setup have completed."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "background-app",
+          "action": "app.lifecycle",
+          "command": "background",
+          "settle_ms": 3000,
+          "intent": "Put the installed app in the background before measuring resume",
+          "detail": "On Android this sends HOME to the selected device. On iOS simulator this foregrounds Settings through the shared outer adapter."
+        },
+        {
+          "id": "foreground-app",
+          "action": "app.lifecycle",
+          "command": "foreground",
+          "settle_ms": 15000,
+          "intent": "Foreground the installed app through the Expo dev-client deep link",
+          "detail": "Uses the selected device, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "ensure-unlocked",
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Unlock the wallet before timing the Perps journey",
+          "detail": "Unlock only if the app is currently locked so the first measured node starts from a stable, signed-in state."
+        }
+      ],
+      "entry": "open-perps-list",
+      "nodes": {
+        "open-perps-list": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "intent": "Open the Perps market list screen",
+          "detail": "Navigate to the Perps markets list via the stable page alias; its node duration measures market-list render time.",
+          "flow": "perps",
+          "next": "read-positions"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "intent": "Read the live Perps positions shown on the market list",
+          "detail": "Read live Perps positions through the controller; its node duration measures how long live account state takes to resolve.",
+          "flow": "perps",
+          "next": "open-market-detail"
+        },
+        "open-market-detail": {
+          "action": "ui.navigate",
+          "page": "perps-market",
+          "market": "BTC",
+          "intent": "Open the BTC Perps market detail screen",
+          "detail": "Navigate to the BTC market detail via the stable page alias; its node duration measures market-detail render time.",
+          "flow": "perps",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the background-resume Perps performance flow",
+          "detail": "Terminal node; trace.json holds setup plus measured Perps node durations.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps-performance-cold-start.mobile.recipe.json

@@ -0,0 +1,72 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps performance flow - cold process start",
+  "description": "Measured Perps flow from a deterministic cold-process start state. Setup force-stops/terminates the installed app, relaunches it through the Expo dev-client deep link without rebuilding, and unlocks if needed. startState records the stable status. The measured workflow is only Perps list -> state -> BTC detail.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after cold-start setup",
+    "detail": "Read-only start-state marker after lifecycle and wallet setup have completed."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "terminate-app",
+          "action": "app.lifecycle",
+          "command": "terminate",
+          "settle_ms": 3000,
+          "intent": "Terminate the installed app process before measuring cold start",
+          "detail": "Uses adb force-stop on Android or simctl terminate on iOS simulator; it does not uninstall or rebuild."
+        },
+        {
+          "id": "launch-app",
+          "action": "app.lifecycle",
+          "command": "launch",
+          "settle_ms": 15000,
+          "intent": "Launch the installed app through the Expo dev-client deep link",
+          "detail": "Uses the selected device, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "ensure-unlocked",
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Unlock the wallet before timing the Perps journey",
+          "detail": "Unlock only if the app is currently locked so the first measured node starts from a stable, signed-in state."
+        }
+      ],
+      "entry": "open-perps-list",
+      "nodes": {
+        "open-perps-list": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "intent": "Open the Perps market list screen",
+          "detail": "Navigate to the Perps markets list via the stable page alias; its node duration measures market-list render time.",
+          "flow": "perps",
+          "next": "read-positions"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "intent": "Read the live Perps positions shown on the market list",
+          "detail": "Read live Perps positions through the controller; its node duration measures how long live account state takes to resolve.",
+          "flow": "perps",
+          "next": "open-market-detail"
+        },
+        "open-market-detail": {
+          "action": "ui.navigate",
+          "page": "perps-market",
+          "market": "BTC",
+          "intent": "Open the BTC Perps market detail screen",
+          "detail": "Navigate to the BTC market detail via the stable page alias; its node duration measures market-detail render time.",
+          "flow": "perps",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the cold-start Perps performance flow",
+          "detail": "Terminal node; trace.json holds setup plus measured Perps node durations.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps-performance-warm-start.mobile.recipe.json

@@ -0,0 +1,64 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps performance flow - warm foreground start",
+  "description": "Measured Perps flow from a deterministic warm-foreground start state. Setup foregrounds the already installed app through the Expo dev-client deep link without rebuilding and unlocks if needed. startState records the stable status. The measured workflow is only Perps list -> state -> BTC detail.",
+  "startState": {
+    "action": "app.status",
+    "intent": "Record the stable run start status after warm foreground setup",
+    "detail": "Read-only start-state marker after lifecycle and wallet setup have completed."
+  },
+  "validate": {
+    "workflow": {
+      "setup": [
+        {
+          "id": "foreground-app",
+          "action": "app.lifecycle",
+          "command": "foreground",
+          "settle_ms": 10000,
+          "intent": "Foreground the installed app through the Expo dev-client deep link",
+          "detail": "Uses the selected device, Metro port, and installed package; it does not rebuild."
+        },
+        {
+          "id": "ensure-unlocked",
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Unlock the wallet before timing the Perps journey",
+          "detail": "Unlock only if the app is currently locked so the first measured node starts from a stable, signed-in state."
+        }
+      ],
+      "entry": "open-perps-list",
+      "nodes": {
+        "open-perps-list": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "intent": "Open the Perps market list screen",
+          "detail": "Navigate to the Perps markets list via the stable page alias; its node duration measures market-list render time.",
+          "flow": "perps",
+          "next": "read-positions"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "intent": "Read the live Perps positions shown on the market list",
+          "detail": "Read live Perps positions through the controller; its node duration measures how long live account state takes to resolve.",
+          "flow": "perps",
+          "next": "open-market-detail"
+        },
+        "open-market-detail": {
+          "action": "ui.navigate",
+          "page": "perps-market",
+          "market": "BTC",
+          "intent": "Open the BTC Perps market detail screen",
+          "detail": "Navigate to the BTC market detail via the stable page alias; its node duration measures market-detail render time.",
+          "flow": "perps",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the warm-start Perps performance flow",
+          "detail": "Terminal node; trace.json holds setup plus measured Perps node durations.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}