@deeeed/metamask-harness 0.34.2 → 0.34.4

package/library/actions/extension/performance/_navigation-memory.mjs

@@ -0,0 +1,372 @@
+const DEFAULT_SCREEN_TIMEOUT_MS = 15_000;
+const DEFAULT_SETTLE_MS = 1_500;
+const DEFAULT_GC_SETTLE_MS = 300;
+const DEFAULT_ACTION_TIMEOUT_MS = 400_000;
+const DEFAULT_ROUND_DURATION_MS = 10_000;
+
+function finiteNumber(value, fallback, label) {
+  const parsed = value ?? fallback;
+  if (!Number.isFinite(parsed)) throw new Error(`${label} must be a finite number.`);
+  return parsed;
+}
+
+function positiveInteger(value, fallback, label, minimum = 1) {
+  const parsed = finiteNumber(value, fallback, label);
+  if (!Number.isInteger(parsed) || parsed < minimum) {
+    throw new Error(`${label} must be an integer >= ${minimum}.`);
+  }
+  return parsed;
+}
+
+function requiredText(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} is required.`);
+  }
+  return value.trim();
+}
+
+function optionalHash(value, fallback) {
+  const hash = typeof value === 'string' && value.trim() ? value.trim() : fallback;
+  return hash.startsWith('#') ? hash : `#${hash}`;
+}
+
+export function leastSquaresSlope(values) {
+  if (!Array.isArray(values) || values.length < 2 || values.some((value) => !Number.isFinite(value))) {
+    throw new Error('leastSquaresSlope requires at least two finite samples.');
+  }
+  const meanX = (values.length - 1) / 2;
+  const meanY = values.reduce((sum, value) => sum + value, 0) / values.length;
+  let numerator = 0;
+  let denominator = 0;
+  for (let index = 0; index < values.length; index += 1) {
+    numerator += (index - meanX) * (values[index] - meanY);
+    denominator += (index - meanX) ** 2;
+  }
+  return numerator / denominator;
+}
+
+export function assessNavigationSlope(slopes, bounds) {
+  return {
+    nodes: slopes.nodes <= bounds.maxNodesPerCycle,
+    listeners: slopes.listeners <= bounds.maxListenersPerCycle,
+  };
+}
+
+export function countDetachedNodes(snapshot) {
+  const fields = snapshot?.snapshot?.meta?.node_fields;
+  const nodes = snapshot?.nodes;
+  if (!Array.isArray(fields) || !Array.isArray(nodes)) {
+    throw new Error('Heap snapshot is missing node metadata.');
+  }
+  const detachedIndex = fields.indexOf('detachedness');
+  if (detachedIndex < 0) throw new Error('Heap snapshot has no detachedness field.');
+  let count = 0;
+  for (let index = 0; index < nodes.length; index += fields.length) {
+    if (nodes[index + detachedIndex] === 2) count += 1;
+  }
+  return count;
+}
+
+export function navigationMemoryOptions(node, countField = 'cycles', defaultCount = 8) {
+  const screenHash = optionalHash(node.screen_hash ?? node.screenHash, '');
+  if (screenHash === '#') throw new Error('screen_hash is required.');
+  const screenTestId = requiredText(node.screen_test_id ?? node.screenTestId, 'screen_test_id');
+  return {
+    screenHash,
+    screenTestId,
+    returnHash: optionalHash(node.return_hash ?? node.returnHash, '#/'),
+    count: positiveInteger(node[countField], defaultCount, countField, 2),
+    settleMs: positiveInteger(node.settle_ms ?? node.settleMs, DEFAULT_SETTLE_MS, 'settle_ms', 0),
+    gcSettleMs: positiveInteger(node.gc_settle_ms ?? node.gcSettleMs, DEFAULT_GC_SETTLE_MS, 'gc_settle_ms', 0),
+    screenTimeoutMs: positiveInteger(
+      node.screen_timeout_ms ?? node.screenTimeoutMs,
+      DEFAULT_SCREEN_TIMEOUT_MS,
+      'screen_timeout_ms',
+    ),
+    timeoutMs: positiveInteger(node.timeout_ms ?? node.timeoutMs, DEFAULT_ACTION_TIMEOUT_MS, 'timeout_ms'),
+    roundDurationMs: positiveInteger(
+      node.round_duration_ms ?? node.roundDurationMs,
+      DEFAULT_ROUND_DURATION_MS,
+      'round_duration_ms',
+    ),
+  };
+}
+
+function deadlineIn(timeoutMs) {
+  return Date.now() + timeoutMs;
+}
+
+function remaining(deadline, label) {
+  const value = deadline - Date.now();
+  if (value <= 0) throw new Error(`${label} timed out.`);
+  return value;
+}
+
+async function boundedSleep(ms, deadline, label) {
+  if (ms === 0) return;
+  const available = remaining(deadline, label);
+  if (ms > available) throw new Error(`${label} timed out.`);
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function navigateAndSettle(page, hash, testId, options, deadline, label) {
+  await page.navigateHash(hash, Math.min(options.screenTimeoutMs, remaining(deadline, label)));
+  if (testId) {
+    await page.waitForSelector(`[data-testid=${JSON.stringify(testId)}]`, {
+      timeoutMs: Math.min(options.screenTimeoutMs, remaining(deadline, label)),
+    });
+  }
+  await boundedSleep(options.settleMs, deadline, label);
+}
+
+export async function forceGarbageCollection(session, settleMs, deadline) {
+  for (let pass = 0; pass < 2; pass += 1) {
+    await session.call('HeapProfiler.collectGarbage', {}, {
+      timeoutMs: remaining(deadline, 'Forced garbage collection'),
+    });
+    await boundedSleep(settleMs, deadline, 'Forced garbage collection');
+  }
+}
+
+async function readPerformanceMetrics(session, deadline) {
+  const result = await session.call('Performance.getMetrics', {}, {
+    timeoutMs: remaining(deadline, 'Performance metric sampling'),
+  });
+  const metrics = Object.fromEntries((result?.metrics ?? []).map(({ name, value }) => [name, value]));
+  for (const name of ['Nodes', 'JSEventListeners', 'JSHeapUsedSize']) {
+    if (!Number.isFinite(metrics[name])) throw new Error(`CDP metric ${name} is unavailable.`);
+  }
+  return metrics;
+}
+
+async function enableMemoryDomains(session, deadline, includePerformance) {
+  if (includePerformance) {
+    await session.call('Performance.enable', {}, {
+      timeoutMs: remaining(deadline, 'Performance domain setup'),
+    });
+  }
+  await session.call('HeapProfiler.enable', {}, {
+    timeoutMs: remaining(deadline, 'Heap profiler setup'),
+  });
+}
+
+async function samplePostGcMetrics(page, options, deadline, index, navigate, roundDurationMs) {
+  const startedAt = Date.now();
+  if (navigate) {
+    await navigateAndSettle(page, options.returnHash, null, options, deadline, `Navigation cycle ${index}`);
+    await navigateAndSettle(
+      page,
+      options.screenHash,
+      options.screenTestId,
+      options,
+      deadline,
+      `Navigation cycle ${index}`,
+    );
+  }
+  if (roundDurationMs !== undefined) {
+    const waitMs = roundDurationMs - (Date.now() - startedAt);
+    if (waitMs < 0) {
+      throw new Error(
+        `${navigate ? 'Navigation' : 'Idle'} round ${index} exceeded round_duration_ms=${roundDurationMs}.`,
+      );
+    }
+    await boundedSleep(waitMs, deadline, `${navigate ? 'Navigation' : 'Idle'} sample ${index}`);
+  }
+  await forceGarbageCollection(page.session, options.gcSettleMs, deadline);
+  const metrics = await readPerformanceMetrics(page.session, deadline);
+  return {
+    index,
+    nodes: metrics.Nodes,
+    listeners: metrics.JSEventListeners,
+    heapBytes: metrics.JSHeapUsedSize,
+  };
+}
+
+function sampleSlopes(samples) {
+  return {
+    nodes: leastSquaresSlope(samples.map(({ nodes }) => nodes)),
+    listeners: leastSquaresSlope(samples.map(({ listeners }) => listeners)),
+    heapBytes: leastSquaresSlope(samples.map(({ heapBytes }) => heapBytes)),
+  };
+}
+
+export async function measureNavigationSlope(page, options, bounds) {
+  const deadline = deadlineIn(options.timeoutMs);
+  await enableMemoryDomains(page.session, deadline, true);
+  await navigateAndSettle(
+    page,
+    options.screenHash,
+    options.screenTestId,
+    options,
+    deadline,
+    'Initial screen navigation',
+  );
+  const samples = [];
+  for (let cycle = 1; cycle <= options.count; cycle += 1) {
+    samples.push(await samplePostGcMetrics(page, options, deadline, cycle, true));
+  }
+  const slopes = sampleSlopes(samples);
+  const passed = assessNavigationSlope(slopes, bounds);
+  const result = {
+    measurement: 'post-gc-navigation-slope',
+    screen: { hash: options.screenHash, testId: options.screenTestId },
+    cycles: options.count,
+    samples,
+    slopes,
+    bounds,
+    passed,
+  };
+  if (!passed.nodes || !passed.listeners) {
+    throw new Error(
+      `Navigation memory bounds exceeded: nodes ${slopes.nodes.toFixed(2)}/${bounds.maxNodesPerCycle} per cycle; listeners ${slopes.listeners.toFixed(2)}/${bounds.maxListenersPerCycle} per cycle.`,
+    );
+  }
+  return result;
+}
+
+async function takeHeapSnapshot(session, gcSettleMs, deadline) {
+  const chunks = [];
+  const unsubscribe = session.on('HeapProfiler.addHeapSnapshotChunk', (params) => {
+    if (typeof params?.chunk === 'string') chunks.push(params.chunk);
+  });
+  try {
+    await forceGarbageCollection(session, gcSettleMs, deadline);
+    await session.call(
+      'HeapProfiler.takeHeapSnapshot',
+      { reportProgress: false, captureNumericValue: false },
+      { timeoutMs: remaining(deadline, 'Heap snapshot') },
+    );
+  } finally {
+    unsubscribe();
+  }
+  if (chunks.length === 0) throw new Error('Heap snapshot produced no chunks.');
+  return JSON.parse(chunks.join(''));
+}
+
+export async function measureDetachedDom(page, options, maxDetachedGrowth) {
+  const deadline = deadlineIn(options.timeoutMs);
+  await enableMemoryDomains(page.session, deadline, false);
+  await navigateAndSettle(
+    page,
+    options.screenHash,
+    options.screenTestId,
+    options,
+    deadline,
+    'Initial screen navigation',
+  );
+  const before = countDetachedNodes(
+    await takeHeapSnapshot(page.session, options.gcSettleMs, deadline),
+  );
+  for (let cycle = 1; cycle <= options.count; cycle += 1) {
+    await navigateAndSettle(page, options.returnHash, null, options, deadline, `Navigation cycle ${cycle}`);
+    await navigateAndSettle(
+      page,
+      options.screenHash,
+      options.screenTestId,
+      options,
+      deadline,
+      `Navigation cycle ${cycle}`,
+    );
+  }
+  const after = countDetachedNodes(
+    await takeHeapSnapshot(page.session, options.gcSettleMs, deadline),
+  );
+  const result = {
+    measurement: 'post-gc-detached-dom',
+    screen: { hash: options.screenHash, testId: options.screenTestId },
+    cycles: options.count,
+    before,
+    after,
+    growth: after - before,
+    bound: { maxDetachedGrowth },
+    passed: after - before <= maxDetachedGrowth,
+  };
+  if (!result.passed) {
+    throw new Error(
+      `Detached DOM bound exceeded: growth ${result.growth}/${maxDetachedGrowth} nodes.`,
+    );
+  }
+  return result;
+}
+
+async function measureArm(page, options, deadline, navigate) {
+  await navigateAndSettle(
+    page,
+    options.screenHash,
+    options.screenTestId,
+    options,
+    deadline,
+    `${navigate ? 'Navigation' : 'Idle'} arm setup`,
+  );
+  const samples = [];
+  for (let round = 1; round <= options.count; round += 1) {
+    samples.push(
+      await samplePostGcMetrics(
+        page,
+        options,
+        deadline,
+        round,
+        navigate,
+        options.roundDurationMs,
+      ),
+    );
+  }
+  return { samples, slopes: sampleSlopes(samples) };
+}
+
+export async function compareIdleNavigation(page, options, maxAttributableListenersPerCycle) {
+  const deadline = deadlineIn(options.timeoutMs);
+  await enableMemoryDomains(page.session, deadline, true);
+  const idle = await measureArm(page, options, deadline, false);
+  const navigation = await measureArm(page, options, deadline, true);
+  const idleListenersPerCycle = Math.max(0, idle.slopes.listeners);
+  const attributableListenersPerCycle = navigation.slopes.listeners - idleListenersPerCycle;
+  const result = {
+    measurement: 'post-gc-idle-control',
+    screen: { hash: options.screenHash, testId: options.screenTestId },
+    rounds: options.count,
+    idle,
+    navigation,
+    idleListenersPerCycle,
+    attributableListenersPerCycle,
+    bound: { maxAttributableListenersPerCycle },
+    passed: attributableListenersPerCycle <= maxAttributableListenersPerCycle,
+  };
+  if (!result.passed) {
+    throw new Error(
+      `Idle-control bound exceeded: attributable listeners ${attributableListenersPerCycle.toFixed(2)}/${maxAttributableListenersPerCycle} per cycle (navigation ${navigation.slopes.listeners.toFixed(2)}, idle ${idleListenersPerCycle.toFixed(2)}).`,
+    );
+  }
+  return result;
+}
+
+export function navigationSlopeBounds(node) {
+  return {
+    maxNodesPerCycle: finiteNumber(
+      node.max_nodes_per_cycle ?? node.maxNodesPerCycle,
+      2,
+      'max_nodes_per_cycle',
+    ),
+    maxListenersPerCycle: finiteNumber(
+      node.max_listeners_per_cycle ?? node.maxListenersPerCycle,
+      4,
+      'max_listeners_per_cycle',
+    ),
+  };
+}
+
+export function detachedDomBound(node) {
+  return finiteNumber(
+    node.max_detached_growth ?? node.maxDetachedGrowth,
+    50,
+    'max_detached_growth',
+  );
+}
+
+export function idleControlBound(node) {
+  return finiteNumber(
+    node.max_attributable_listeners_per_cycle ?? node.maxAttributableListenersPerCycle,
+    2,
+    'max_attributable_listeners_per_cycle',
+  );
+}

package/library/actions/extension/performance/compare_idle_navigation_memory.mjs

@@ -0,0 +1,18 @@
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  compareIdleNavigation,
+  idleControlBound,
+  navigationMemoryOptions,
+} from './_navigation-memory.mjs';
+
+runAdapter((input) =>
+  withExtensionPage(input, async (page) => ({
+    action: input.action,
+    status: 'pass',
+    ...(await compareIdleNavigation(
+      page,
+      navigationMemoryOptions(input.node, 'rounds', 8),
+      idleControlBound(input.node),
+    )),
+  })),
+);

package/library/actions/extension/performance/measure_detached_dom.mjs

@@ -0,0 +1,18 @@
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  detachedDomBound,
+  measureDetachedDom,
+  navigationMemoryOptions,
+} from './_navigation-memory.mjs';
+
+runAdapter((input) =>
+  withExtensionPage(input, async (page) => ({
+    action: input.action,
+    status: 'pass',
+    ...(await measureDetachedDom(
+      page,
+      navigationMemoryOptions(input.node, 'cycles', 5),
+      detachedDomBound(input.node),
+    )),
+  })),
+);

package/library/actions/extension/performance/measure_navigation_memory.mjs

@@ -0,0 +1,18 @@
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  measureNavigationSlope,
+  navigationMemoryOptions,
+  navigationSlopeBounds,
+} from './_navigation-memory.mjs';
+
+runAdapter((input) =>
+  withExtensionPage(input, async (page) => ({
+    action: input.action,
+    status: 'pass',
+    ...(await measureNavigationSlope(
+      page,
+      navigationMemoryOptions(input.node),
+      navigationSlopeBounds(input.node),
+    )),
+  })),
+);

package/library/actions/mobile/app/network-control.mjs

@@ -42,6 +42,12 @@ async function defaultRun(file, args) {
   return execFileAsync(file, args, { timeout: 15_000, encoding: 'utf8' });
 }
 
+function isAppFocused(output, appId) {
+  return String(output ?? '')
+    .split('\n')
+    .some((line) => line.includes('mCurrentFocus=') && line.includes(appId));
+}
+
 export async function setMobileNetworkState(input, deps = {}) {
   const state = String(input.node?.state ?? '').toLowerCase();
   if (state !== 'offline' && state !== 'online') {
@@ -87,19 +93,26 @@ export async function setMobileNetworkState(input, deps = {}) {
       `app.network requested ${state}, but Android airplane_mode_on was ${JSON.stringify(observed)} instead of ${expected}.`,
     );
   }
-
-
-  await run(adb, [
+  const focusBefore = await run(adb, [
     '-s',
     serial,
     'shell',
-    'monkey',
-    '-p',
-    appId,
-    '-c',
-    'android.intent.category.LAUNCHER',
-    '1',
+    'dumpsys',
+    'window',
   ]);
+  if (!isAppFocused(focusBefore.stdout, appId)) {
+    await run(adb, [
+      '-s',
+      serial,
+      'shell',
+      'monkey',
+      '-p',
+      appId,
+      '-c',
+      'android.intent.category.LAUNCHER',
+      '1',
+    ]);
+  }
 
   const fallbackSettleMs = state === 'offline' ? 3000 : 10000;
   const settleMs = Number(input.node?.settle_ms ?? fallbackSettleMs);
@@ -113,10 +126,9 @@ export async function setMobileNetworkState(input, deps = {}) {
     serial,
     'shell',
     'dumpsys',
-    'activity',
-    'activities',
+    'window',
   ]);
-  if (!String(foreground.stdout ?? '').includes(appId)) {
+  if (!isAppFocused(foreground.stdout, appId)) {
     throw new Error(
       `app.network changed Android networking but ${appId} was not foregrounded afterward.`,
     );

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

@@ -728,6 +728,61 @@
       ],
       "execution_capabilities": []
     },
+    "metamask.perps.read_snapshot": {
+      "description": "Read global market and account snapshots through the public PerpsController API used by wallet clients.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "enum": [
+              "markets",
+              "account",
+              "all"
+            ],
+            "default": "all",
+            "description": "Select the public controller snapshot calls to execute."
+          },
+          "account": {
+            "type": "string",
+            "description": "Wallet fixture account name or EVM address; defaults to dev1."
+          },
+          "account_name": {
+            "type": "string",
+            "description": "Alias for a wallet fixture account name."
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "default": "testnet"
+          },
+          "terminal_market_data_url": {
+            "type": "string",
+            "description": "Optional full URL for the legacy Terminal market-data endpoint."
+          },
+          "terminal_global_snapshot_url": {
+            "type": "string",
+            "description": "Optional full URL for the Terminal schema-v2 global snapshot endpoint."
+          },
+          "timeout_ms": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.perps.read_snapshot",
+          "scope": "all",
+          "intent": "Read coherent Perps snapshots through the public controller API",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
     "metamask.perps.place_order": {
       "description": "core Place a real Perps order on HyperLiquid testnet by driving the headless perps controller placeOrder() through the full signing/provider path. Supports market (default), resting limit orders (order_type=limit with price/offset_pct), and resting trigger placements (stop_market | stop_limit | take_profit_market | take_profit_limit with trigger_price/trigger_offset_pct), plus reduce_only and attached/partial TP/SL (take_profit_price/take_profit_size, stop_loss_price/stop_loss_size, tpsl_linkage). Venue is selected with network (testnet default; mainnet signs with REAL funds and also requires CORE_PERPS_ALLOW_MAINNET_WRITES=1). Plain limit orders accept time_in_force GTC | ALO (post-only).",
       "schema": {

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

@@ -1221,6 +1221,106 @@
       ],
       "execution_capabilities": []
     },
+    "metamask.performance.measure_navigation_memory": {
+      "description": "Measure retained DOM nodes and listeners across repeated Extension navigation after forced garbage collection, using least-squares slopes and separate declared bounds.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "screen_hash": { "type": "string" },
+          "screen_test_id": { "type": "string" },
+          "return_hash": { "type": "string", "default": "#/" },
+          "cycles": { "type": "integer", "minimum": 2, "default": 8 },
+          "max_nodes_per_cycle": { "type": "number", "default": 2 },
+          "max_listeners_per_cycle": { "type": "number", "default": 4 },
+          "settle_ms": { "type": "integer", "minimum": 0, "default": 1500 },
+          "gc_settle_ms": { "type": "integer", "minimum": 0, "default": 300 },
+          "screen_timeout_ms": { "type": "integer", "minimum": 1, "default": 15000 },
+          "timeout_ms": { "type": "integer", "minimum": 1, "default": 400000 }
+        },
+        "required": ["screen_hash", "screen_test_id"],
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.performance.measure_navigation_memory",
+          "screen_hash": "#/settings",
+          "screen_test_id": "settings-tab-bar-grouped",
+          "return_hash": "#/",
+          "cycles": 8,
+          "max_nodes_per_cycle": 2,
+          "max_listeners_per_cycle": 4,
+          "intent": "Measure post-GC retained-memory slopes across repeated navigation.",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
+    "metamask.performance.measure_detached_dom": {
+      "description": "Compare retained detached-DOM counts before and after repeated Extension navigation, with forced garbage collection before each heap snapshot.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "screen_hash": { "type": "string" },
+          "screen_test_id": { "type": "string" },
+          "return_hash": { "type": "string", "default": "#/" },
+          "cycles": { "type": "integer", "minimum": 2, "default": 5 },
+          "max_detached_growth": { "type": "number", "default": 50 },
+          "settle_ms": { "type": "integer", "minimum": 0, "default": 1500 },
+          "gc_settle_ms": { "type": "integer", "minimum": 0, "default": 300 },
+          "screen_timeout_ms": { "type": "integer", "minimum": 1, "default": 15000 },
+          "timeout_ms": { "type": "integer", "minimum": 1, "default": 400000 }
+        },
+        "required": ["screen_hash", "screen_test_id"],
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.performance.measure_detached_dom",
+          "screen_hash": "#/settings",
+          "screen_test_id": "settings-tab-bar-grouped",
+          "return_hash": "#/",
+          "cycles": 5,
+          "max_detached_growth": 50,
+          "intent": "Measure detached DOM retained after navigation and forced garbage collection.",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
+    "metamask.performance.compare_idle_navigation_memory": {
+      "description": "Compare equal-duration idle and navigating Extension arms to isolate navigation-attributable listener growth after forced garbage collection.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "screen_hash": { "type": "string" },
+          "screen_test_id": { "type": "string" },
+          "return_hash": { "type": "string", "default": "#/" },
+          "rounds": { "type": "integer", "minimum": 2, "default": 8 },
+          "round_duration_ms": { "type": "integer", "minimum": 1, "default": 10000 },
+          "max_attributable_listeners_per_cycle": { "type": "number", "default": 2 },
+          "settle_ms": { "type": "integer", "minimum": 0, "default": 1500 },
+          "gc_settle_ms": { "type": "integer", "minimum": 0, "default": 300 },
+          "screen_timeout_ms": { "type": "integer", "minimum": 1, "default": 15000 },
+          "timeout_ms": { "type": "integer", "minimum": 1, "default": 400000 }
+        },
+        "required": ["screen_hash", "screen_test_id"],
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.performance.compare_idle_navigation_memory",
+          "screen_hash": "#/settings",
+          "screen_test_id": "settings-tab-bar-grouped",
+          "return_hash": "#/",
+          "rounds": 8,
+          "round_duration_ms": 10000,
+          "max_attributable_listeners_per_cycle": 2,
+          "intent": "Separate navigation-attributable listener growth from equal-duration idle growth.",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
     "metamask.perps.read_positions": {
       "description": "extension Read live Perps positions; without a selector, return all live positions.",
       "schema": {

package/library/recipes/core/perps/snapshot.recipe.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "MetaMask core Perps snapshots",
+  "description": "Reads global market and account snapshots through the public PerpsController API used by wallet clients. Configure CORE_PERPS_TERMINAL_GLOBAL_SNAPSHOT_URL to exercise a Terminal schema-v2 endpoint.",
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": {
+        "action": "app.status",
+        "next": "read_snapshot",
+        "intent": "Resolve the Core checkout and report headless compatibility"
+      },
+      "read_snapshot": {
+        "action": "metamask.perps.read_snapshot",
+        "scope": "all",
+        "next": "done",
+        "intent": "Read coherent market and account snapshots through public controller methods"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}