@deeeed/metamask-harness 0.44.2 → 0.45.0

package/dist/adapters/performance/cdp-trace.js

@@ -5,8 +5,7 @@ import { withTimeout } from "../../async.js";
 import {
   summarizeJavaScriptTasks
 } from "./js-task-metrics.js";
-const FRAME_BUDGET_MS = 1e3 / 60;
-const MAX_TRACE_BYTES = 64 * 1024 * 1024;
+const MAX_TRACE_BYTES = 16 * 1024 * 1024;
 const MAX_TRACE_EVENTS = 25e4;
 const MOBILE_TRACE_CATEGORIES = [
   "blink.user_timing",
@@ -141,7 +140,7 @@ function parseTraceCapture(capture) {
   const trace = traceEvidence(
     { ...capture, events: scopedEvents },
     scope,
-    finite(marker?.pid) ? marker.pid : void 0
+    capture.platform === "extension" && finite(marker?.pid) ? marker.pid : void 0
   );
   if (!finite(marker?.ts) || capture.markerHostEpochMs === void 0 || capture.markerUncertaintyMs === void 0) {
     const reason = "CDP trace clock marker was unavailable.";
@@ -189,9 +188,15 @@ function parseTraceCapture(capture) {
       traceEventNames(scopedEvents),
       capture.markerUncertaintyMs
     ),
-    trace
+    trace,
+    rawTraceEvents: normalizeTraceTimestamps(scopedEvents, traceToEpochMs)
   };
 }
+function normalizeTraceTimestamps(events, traceToEpochMs) {
+  return events.map(
+    (event) => finite(event.ts) ? { ...event, ts: traceToEpochMs(event.ts) * 1e3 } : { ...event }
+  );
+}
 function traceEvidence(capture, scope, rendererProcessId) {
   const counts = /* @__PURE__ */ new Map();
   for (const event of capture.events) {
@@ -226,6 +231,7 @@ function nativeFrameSamples(events, platform, traceToEpochMs) {
     frames.push({ beginUs: begin.ts, endUs: event.ts });
   }
   frames.sort((first, second) => first.beginUs - second.beginUs);
+  const frameBudgetMs = estimateFrameBudgetMs(frames);
   if (platform === "ios") {
     const samples = [];
     for (let index = 1; index < frames.length; index += 1) {
@@ -235,9 +241,14 @@ function nativeFrameSamples(events, platform, traceToEpochMs) {
       const durationMs = (current.beginUs - previous.beginUs) / 1e3;
       if (durationMs <= 0) continue;
       samples.push({
+        cadenceInterval: true,
         completedAtEpochMs: traceToEpochMs(current.beginUs),
         durationMs,
-        janky: durationMs > FRAME_BUDGET_MS * 1.01
+        ...frameBudgetMs ? {
+          frameBudgetMs,
+          overBudget: durationMs > frameBudgetMs * 1.01
+        } : {},
+        startedAtEpochMs: traceToEpochMs(previous.beginUs)
       });
     }
     return samples;
@@ -247,10 +258,38 @@ function nativeFrameSamples(events, platform, traceToEpochMs) {
     return {
       completedAtEpochMs: traceToEpochMs(frame.endUs),
       durationMs,
-      janky: durationMs > FRAME_BUDGET_MS * 1.01
+      ...frameBudgetMs ? {
+        frameBudgetMs,
+        overBudget: durationMs > frameBudgetMs * 1.01
+      } : {},
+      startedAtEpochMs: traceToEpochMs(frame.beginUs)
     };
   }).filter((sample) => sample.durationMs > 0);
 }
+function estimateFrameBudgetMs(frames) {
+  const cadenceMs = [];
+  for (let index = 1; index < frames.length; index += 1) {
+    const previous = frames[index - 1];
+    const current = frames[index];
+    if (!previous || !current) continue;
+    const intervalMs = (current.beginUs - previous.beginUs) / 1e3;
+    if (intervalMs >= 3.5 && intervalMs <= 40) cadenceMs.push(intervalMs);
+  }
+  if (cadenceMs.length < 5) return void 0;
+  cadenceMs.sort((first, second) => first - second);
+  const observedBudgetMs = percentile(cadenceMs, 0.1);
+  const refreshRateHz = Math.round(1e3 / observedBudgetMs);
+  return refreshRateHz >= 24 && refreshRateHz <= 240 ? 1e3 / refreshRateHz : void 0;
+}
+function percentile(sorted, quantile) {
+  if (sorted.length === 1) return sorted[0] ?? 0;
+  const position = (sorted.length - 1) * quantile;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  const lowerValue = sorted[lower] ?? 0;
+  const upperValue = sorted[upper] ?? lowerValue;
+  return lowerValue + (upperValue - lowerValue) * (position - lower);
+}
 function javascriptTaskSamples(events, traceToEpochMs) {
   return events.filter(
     (event) => event.name === "RunTask" && event.ph === "X" && finite(event.ts) && finite(event.dur) && event.dur > 0
@@ -272,6 +311,7 @@ function frameSequence(event) {
 }
 function javascriptSourceResult(kind, samples, status, coverageGapReasons, observedEventNames, clockSyncUncertaintyMs) {
   return {
+    applicability: "applicable",
     status: samples.length > 0 ? status : "partial",
     kind,
     unavailableReasons: [],
@@ -287,18 +327,23 @@ function javascriptSourceResult(kind, samples, status, coverageGapReasons, obser
   };
 }
 function nativeUiSourceResult(kind, samples, status, coverageGapReasons, observedEventNames, clockSyncUncertaintyMs) {
+  const summary = summarizeFrames(samples);
+  const hasUnclassifiedCadenceGap = (summary.cadenceGapCount ?? 0) > 0;
   return {
-    status: samples.length > 0 ? status : "partial",
+    status: samples.length === 0 ? "partial" : hasUnclassifiedCadenceGap ? "partial" : status,
     kind,
     unavailableReasons: [],
     coverageGapReasons: [
       ...coverageGapReasons,
       ...samples.length > 0 ? [] : [
         `No ${kind} samples were recorded. Observed trace events: ${observedEventNames.join(", ") || "none"}.`
-      ]
+      ],
+      ...hasUnclassifiedCadenceGap ? [
+        "Unclassified native cadence gap prevents a complete FPS result."
+      ] : []
     ],
     samples,
-    summary: summarizeFrames(samples),
+    summary,
     clockSyncUncertaintyMs
   };
 }
@@ -312,6 +357,7 @@ function traceEventNames(events) {
 }
 function unavailableJavaScriptSource(kind, reason) {
   return {
+    applicability: "applicable",
     status: "unavailable",
     kind,
     unavailableReasons: [reason],

package/dist/adapters.js

@@ -955,7 +955,7 @@ async function executeNativeProviderAction(action, node, context, createTranspor
     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 = `mm-harness-${process.pid}-${context.nodeId}`.replace(/[^a-zA-Z0-9._-]/gu, "-");
+  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 {

package/dist/performance-observation.js

@@ -1,4 +1,6 @@
 import path from "node:path";
+import { promisify } from "node:util";
+import { gzip } from "node:zlib";
 import {
   createMobilePerformanceBackend
 } from "./adapters/mobile/performance-observer.js";
@@ -13,6 +15,7 @@ import {
 const sessions = /* @__PURE__ */ new Map();
 const DEFAULT_MAX_DURATION_MS = 5 * 60 * 1e3;
 const MAX_DURATION_MS = 60 * 60 * 1e3;
+const gzipAsync = promisify(gzip);
 function startRunPerformanceObservation(adapter, target, artifactsDir, env, ports = {}) {
   if (adapter === "core") return void 0;
   const key = path.resolve(artifactsDir);
@@ -31,8 +34,8 @@ function startRunPerformanceObservation(adapter, target, artifactsDir, env, port
   session.expirySweep = setInterval(() => {
     const now = Date.now();
     for (const window of session.windows.values()) {
-      if (!window.expiredResult && now - window.startedAtEpochMs >= window.maxDurationMs) {
-        window.expiredResult = endCapture(session, window);
+      if (!window.result && now - window.startedAtEpochMs >= window.maxDurationMs) {
+        void finishCaptureWindow(session, window);
       }
     }
   }, 100);
@@ -58,11 +61,17 @@ function startRunPerformanceObservation(adapter, target, artifactsDir, env, port
           };
           const jsonPath = `performance/${safeId(window.id)}-summary.json`;
           const htmlPath = `performance/${safeId(window.id)}.html`;
-          await writeArtifacts(session.artifactsDir, jsonPath, htmlPath, artifact);
+          const rawTracePath = await writeArtifacts(
+            session.artifactsDir,
+            jsonPath,
+            htmlPath,
+            artifact
+          );
           if (artifactManifestPath) {
             await indexPerformanceArtifacts(artifactManifestPath, [
               jsonPath,
-              htmlPath
+              htmlPath,
+              ...rawTracePath ? [rawTracePath] : []
             ]);
           }
         }
@@ -118,7 +127,12 @@ async function handleRunPerformanceAction(platform, action, node, context) {
   const htmlPath = String(
     node.html_path ?? `performance/${safeId(id)}.html`
   );
-  await writeArtifacts(session.artifactsDir, jsonPath, htmlPath, artifact);
+  const rawTracePath = await writeArtifacts(
+    session.artifactsDir,
+    jsonPath,
+    htmlPath,
+    artifact
+  );
   return {
     output: {
       action,
@@ -126,11 +140,13 @@ async function handleRunPerformanceAction(platform, action, node, context) {
       phase,
       status: artifact.status,
       artifactPath: jsonPath,
-      htmlPath
+      htmlPath,
+      ...rawTracePath ? { rawTracePath } : {}
     },
     artifacts: [
       { path: jsonPath, type: "metric", nodeId: context.nodeId },
-      { path: htmlPath, type: "report", nodeId: context.nodeId }
+      { path: htmlPath, type: "report", nodeId: context.nodeId },
+      ...rawTracePath ? [{ path: rawTracePath, type: "trace", nodeId: context.nodeId }] : []
     ]
   };
 }
@@ -159,24 +175,41 @@ async function endCapture(session, window) {
   );
 }
 function finishCaptureWindow(session, window) {
-  return window.expiredResult ?? endCapture(session, window);
+  if (!window.result) {
+    window.result = endCapture(session, window);
+    void window.result.catch(() => void 0);
+  }
+  return window.result;
 }
 function buildPerformanceArtifact(window, endedAtEpochMs, result, allEvents) {
+  const javascriptTasksApplicable = result.platform === "extension";
+  const javascript = javascriptTasksApplicable ? result.javascript : {
+    ...result.javascript,
+    applicability: "not_applicable",
+    status: "unavailable",
+    kind: "not-applicable-mobile-js-tasks",
+    unavailableReasons: [],
+    coverageGapReasons: [],
+    samples: [],
+    summary: {}
+  };
   const nodeEvents = allEvents.filter(
     (event) => event.epochMs >= window.startedAtEpochMs && event.epochMs <= endedAtEpochMs
   );
   const nodeIntervals = buildNodeIntervals(
     nodeEvents,
-    result.javascript,
+    javascript,
     result.nativeUi
   );
   const coverageGapReasons = [
-    ...result.javascript.unavailableReasons.map(
-      (reason) => `javascript unavailable: ${reason}`
-    ),
-    ...result.javascript.coverageGapReasons.map(
-      (reason) => `javascript: ${reason}`
-    ),
+    ...javascriptTasksApplicable ? [
+      ...javascript.unavailableReasons.map(
+        (reason) => `javascript unavailable: ${reason}`
+      ),
+      ...javascript.coverageGapReasons.map(
+        (reason) => `javascript: ${reason}`
+      )
+    ] : [],
     ...result.nativeUi.unavailableReasons.map(
       (reason) => `nativeUi unavailable: ${reason}`
     ),
@@ -188,19 +221,20 @@ function buildPerformanceArtifact(window, endedAtEpochMs, result, allEvents) {
   if (exceededMaxDuration) {
     coverageGapReasons.push("Performance capture exceeded max_duration_ms.");
   }
-  const status = exceededMaxDuration ? "partial" : result.javascript.status === "unavailable" && result.nativeUi.status === "unavailable" ? "unavailable" : result.javascript.status === "complete" && result.nativeUi.status === "complete" ? "complete" : "partial";
+  const status = exceededMaxDuration ? "partial" : javascriptTasksApplicable ? javascript.status === "unavailable" && result.nativeUi.status === "unavailable" ? "unavailable" : javascript.status === "complete" && result.nativeUi.status === "complete" ? "complete" : "partial" : result.nativeUi.status;
   const worst = worstInteraction(nodeIntervals);
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     id: window.id,
     status,
     platform: result.platform,
     startedAtEpochMs: window.startedAtEpochMs,
     endedAtEpochMs,
     durationMs: endedAtEpochMs - window.startedAtEpochMs,
-    javascript: { ...result.javascript, samples: [] },
+    javascript: { ...javascript, samples: [] },
     nativeUi: { ...result.nativeUi, samples: [] },
     trace: result.trace,
+    ...result.rawTraceEvents ? { rawTraceEvents: result.rawTraceEvents } : {},
     nodeEvents,
     nodeIntervals,
     ...worst ? { worstInteraction: worst } : {},
@@ -222,9 +256,12 @@ function buildNodeIntervals(events, javascript, nativeUi) {
       action: event.action,
       durationMs: event.epochMs - start.epochMs,
       endedAtEpochMs: event.epochMs,
-      javascript: summarizeJavaScriptTasks(
-        samplesWithin(javascript, start.epochMs, event.epochMs)
-      ),
+      javascript: javascript.applicability === "not_applicable" ? { applicability: "not_applicable" } : {
+        applicability: "applicable",
+        ...summarizeJavaScriptTasks(
+          samplesWithin(javascript, start.epochMs, event.epochMs)
+        )
+      },
       nativeUi: summarizeFrames(
         samplesWithin(nativeUi, start.epochMs, event.epochMs)
       ),
@@ -249,7 +286,10 @@ function worstInteraction(intervals) {
         source: "javascriptTask"
       },
       {
-        longestSampleMs: interval.nativeUi.longestFrameMs,
+        longestSampleMs: Math.max(
+          interval.nativeUi.longestFrameMs ?? 0,
+          interval.nativeUi.longestCadenceGapMs ?? 0
+        ) || void 0,
         source: "nativeUiFrame"
       }
     ];
@@ -274,7 +314,7 @@ async function assertPerformance(node, context) {
     node.artifact_path ?? `performance/${safeId(id)}-summary.json`
   );
   const artifact = await readArtifact(context.artifactsDir, artifactPath);
-  if (artifact.schemaVersion !== 1 || artifact.id !== id) {
+  if (artifact.schemaVersion !== 2 || artifact.id !== id) {
     throw new Error("app.performance_assert summary contract is invalid.");
   }
   const statuses = Array.isArray(node.required_status) ? node.required_status.map(String) : node.required_status ? [String(node.required_status)] : [];
@@ -320,10 +360,11 @@ async function assertPerformance(node, context) {
   };
 }
 async function writeArtifacts(artifactsDir, jsonPath, htmlPath, artifact) {
+  const { rawTraceEvents, ...summaryArtifact } = artifact;
   await writeContainedArtifact(
     artifactsDir,
     jsonPath,
-    `${JSON.stringify(artifact, null, 2)}
+    `${JSON.stringify(summaryArtifact, null, 2)}
 `,
     "Performance artifact"
   );
@@ -333,8 +374,70 @@ async function writeArtifacts(artifactsDir, jsonPath, htmlPath, artifact) {
     renderPerformanceHtml(artifact),
     "Performance artifact"
   );
+  if (!rawTraceEvents) return void 0;
+  const traceEvents = [
+    ...rawTraceEvents,
+    ...recipeNodeTraceEvents(artifact.nodeIntervals)
+  ];
+  const rawTracePath = chromeTracePath(jsonPath);
+  await writeContainedArtifact(
+    artifactsDir,
+    rawTracePath,
+    await gzipAsync(
+      `${JSON.stringify({
+        traceEvents,
+        displayTimeUnit: "ms",
+        metadata: {
+          source: "@deeeed/metamask-harness",
+          captureId: artifact.id,
+          platform: artifact.platform,
+          startedAtEpochMs: artifact.startedAtEpochMs,
+          endedAtEpochMs: artifact.endedAtEpochMs
+        }
+      })}
+`
+    ),
+    "Performance trace artifact"
+  );
+  return rawTracePath;
+}
+function recipeNodeTraceEvents(intervals) {
+  return [
+    {
+      name: "process_name",
+      ph: "M",
+      pid: 0,
+      tid: 0,
+      args: { name: "MetaMask Harness" }
+    },
+    {
+      name: "thread_name",
+      ph: "M",
+      pid: 0,
+      tid: 1,
+      args: { name: "Recipe nodes" }
+    },
+    ...intervals.map((interval) => ({
+      name: interval.action,
+      cat: "metamask.recipe.node",
+      ph: "X",
+      ts: interval.startedAtEpochMs * 1e3,
+      dur: interval.durationMs * 1e3,
+      pid: 0,
+      tid: 1,
+      args: {
+        nodeId: interval.nodeId,
+        outcome: interval.outcome
+      }
+    }))
+  ];
+}
+function chromeTracePath(jsonPath) {
+  return jsonPath.endsWith(".json") ? `${jsonPath.slice(0, -".json".length)}-trace.json.gz` : `${jsonPath}-trace.json.gz`;
 }
 function renderPerformanceHtml(artifact) {
+  const javascriptTasksApplicable = artifact.platform === "extension";
+  const iosCadence = artifact.platform === "ios";
   const maxNodeDurationMs = Math.max(
     1,
     ...artifact.nodeIntervals.map((interval) => interval.durationMs)
@@ -343,12 +446,20 @@ function renderPerformanceHtml(artifact) {
     const ui = interval.nativeUi;
     const js = interval.javascript;
     const width = Math.max(1, interval.durationMs / maxNodeDurationMs * 100);
-    return `<tr><td><strong>${escapeHtml(interval.nodeId)}</strong><div class="action">${escapeHtml(interval.action)}</div></td><td><div class="duration"><span style="width:${width.toFixed(1)}%"></span></div><small>${interval.durationMs} ms</small></td><td>${ui.frameCount}</td><td>${metric(ui.averageFps)}</td><td>${metric(ui.p95FrameMs)}</td><td>${metric(ui.jankyFramePercent)}</td><td>${js.taskCount}</td><td>${metric(js.longTaskCount)}</td><td>${metric(js.longestTaskMs)}</td></tr>`;
+    const javascriptCells = javascriptTasksApplicable ? `<td>${js.taskCount}</td><td>${metric(js.longTaskCount)}</td><td>${metric(js.longestTaskMs)}</td>` : "<td>N/A</td><td>N/A</td><td>N/A</td>";
+    return `<tr><td><strong>${escapeHtml(interval.nodeId)}</strong><div class="action">${escapeHtml(interval.action)}</div></td><td><div class="duration"><span style="width:${width.toFixed(1)}%"></span></div><small>${interval.durationMs} ms</small></td><td>${ui.frameCount}</td><td>${metric(ui.refreshRateHz, 2)}</td><td>${metric(ui.activeFps)}</td><td>${metric(ui.fpsIntervalCount)}</td><td>${metric(ui.p95FrameMs)}</td><td>${metric(ui.overBudgetFramePercent)}</td>${javascriptCells}</tr>`;
   }).join("");
-  const worst = artifact.worstInteraction ? `${escapeHtml(artifact.worstInteraction.nodeId)}: ${artifact.worstInteraction.longestSampleMs} ms (${artifact.worstInteraction.source})` : "No attributed UI frame or JS task samples";
-  const gaps = artifact.coverageGapReasons.length ? `<ul>${artifact.coverageGapReasons.map((reason) => `<li>${escapeHtml(reason)}</li>`).join("")}</ul>` : "<p>Both requested sources completed.</p>";
-  const sources = `<p><strong>JavaScript:</strong> ${escapeHtml(artifact.javascript.kind)} (${artifact.javascript.status})<br><strong>Native UI:</strong> ${escapeHtml(artifact.nativeUi.kind)} (${artifact.nativeUi.status})<br><strong>Trace events:</strong> ${artifact.trace.beginFrameCount} BeginFrame, ${artifact.trace.drawFrameCount} DrawFrame, ${artifact.trace.runTaskCount} RunTask, ${artifact.trace.profileChunkCount} ProfileChunk</p>`;
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>UI smoothness</title><style>:root{color-scheme:dark}*{box-sizing:border-box}body{font:15px system-ui,-apple-system,sans-serif;margin:0;background:#0b0d12;color:#f1f5f9}main{max-width:1180px;margin:auto;padding:32px}h1{font-size:28px;margin:0 0 6px}.lede,.action,small{color:#94a3b8}.cards{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px;margin:24px 0}.card,.coverage{padding:18px;border:1px solid #293244;border-radius:12px;background:#141821}.label{display:block;color:#94a3b8;font-size:12px;text-transform:uppercase;letter-spacing:.06em;margin-bottom:8px}.value{font-size:20px;font-weight:700}.partial{color:#fbbf24}.complete{color:#6ee7b7}.unavailable{color:#f87171}.coverage{margin-top:20px}.coverage h2{font-size:16px;margin:0 0 8px}.coverage ul,.coverage p{margin:8px 0 0;color:#cbd5e1}.coverage ul{padding-left:20px}table{width:100%;border-collapse:collapse;margin-top:24px;background:#141821;border:1px solid #293244;border-radius:12px;overflow:hidden}th,td{text-align:left;padding:12px;border-bottom:1px solid #293244;vertical-align:top}th{color:#93c5fd;font-size:12px;text-transform:uppercase;letter-spacing:.04em}.duration{height:8px;min-width:140px;background:#252c3a;border-radius:99px;overflow:hidden;margin:4px 0 5px}.duration span{display:block;height:100%;background:#7c3aed;border-radius:inherit}.legend{color:#94a3b8;font-size:13px;margin:10px 0 0}@media(max-width:760px){main{padding:20px}.cards{grid-template-columns:1fr}table{display:block;overflow-x:auto}}</style></head><body><main><h1>UI smoothness</h1><p class="lede">CDP trace evidence attributed to recipe-node boundaries. Compare matched runs on the same runtime and build.</p><section class="cards"><div class="card"><span class="label">Evidence status</span><span class="value ${artifact.status}">${artifact.status}</span></div><div class="card"><span class="label">Platform</span><span class="value">${artifact.platform}</span></div><div class="card"><span class="label">Worst observed sample</span><span class="value">${worst}</span></div></section><section class="coverage"><h2>Coverage</h2>${sources}${gaps}</section><table><thead><tr><th>Interaction</th><th>Node duration</th><th>UI frames</th><th>UI avg FPS</th><th>UI p95 frame</th><th>UI jank %</th><th>JS tasks</th><th>JS long tasks</th><th>Longest JS task</th></tr></thead><tbody>${rows}</tbody></table><p class="legend">UI FPS and jank come from native or Chromium frame events. JS tasks show main-thread blocking work and are not FPS. A long task is at least 50 ms. "\u2014" means the trace emitted no complete sample inside the interval.</p></main></body></html>
+  const worst = artifact.worstInteraction ? `${escapeHtml(artifact.worstInteraction.nodeId)}: ${artifact.worstInteraction.longestSampleMs} ms (${artifact.worstInteraction.source === "nativeUiFrame" && iosCadence ? "native UI cadence" : artifact.worstInteraction.source})` : javascriptTasksApplicable ? "No attributed UI frame or JS task samples" : "No attributed UI frame samples";
+  const gaps = artifact.coverageGapReasons.length ? `<ul>${artifact.coverageGapReasons.map((reason) => `<li>${escapeHtml(reason)}</li>`).join("")}</ul>` : javascriptTasksApplicable ? "<p>Both requested sources completed.</p>" : "<p>Native UI frame coverage completed.</p>";
+  const javascriptSource = javascriptTasksApplicable ? `${escapeHtml(artifact.javascript.kind)} (${artifact.javascript.status})` : "Not applicable on React Native Mobile";
+  const traceEvents = artifact.platform === "android" ? `${artifact.trace.beginFrameCount} synthesized BeginFrame, ${artifact.trace.drawFrameCount} synthesized DrawFrame from gfxinfo` : javascriptTasksApplicable ? `${artifact.trace.beginFrameCount} BeginFrame, ${artifact.trace.drawFrameCount} DrawFrame, ${artifact.trace.runTaskCount} RunTask` : `${artifact.trace.beginFrameCount} BeginFrame, ${artifact.trace.drawFrameCount} DrawFrame, ${artifact.trace.profileChunkCount} ProfileChunk`;
+  const refreshRate = artifact.nativeUi.summary.refreshRateHz === void 0 ? "N/A" : `${metric(artifact.nativeUi.summary.refreshRateHz, 2)} Hz`;
+  const clockUncertainty = artifact.nativeUi.clockSyncUncertaintyMs === void 0 ? "" : `<br><strong>Clock mapping uncertainty:</strong> ${metric(artifact.nativeUi.clockSyncUncertaintyMs, 2)} ms`;
+  const cadenceGaps = !iosCadence || artifact.nativeUi.summary.cadenceGapCount === void 0 ? "" : `<br><strong>Unclassified cadence gaps:</strong> ${artifact.nativeUi.summary.cadenceGapCount} (longest ${metric(artifact.nativeUi.summary.longestCadenceGapMs, 2)} ms)`;
+  const sources = `<p><strong>JavaScript tasks:</strong> ${javascriptSource}<br><strong>Native UI:</strong> ${escapeHtml(artifact.nativeUi.kind)} (${artifact.nativeUi.status})<br><strong>Detected refresh rate:</strong> ${refreshRate}${clockUncertainty}${cadenceGaps}<br><strong>Trace events:</strong> ${traceEvents}</p>`;
+  const legend = javascriptTasksApplicable ? "Active UI FPS uses Chromium renderer vsync intervals while frames are being produced. Idle gaps are excluded. Fewer than five usable intervals reports N/A. Over-budget frames compare frame time with the detected refresh period. JS tasks are blocking work, not FPS." : iosCadence ? "Active UI FPS and percentiles use continuous native CADisplayLink cadence intervals. An unclassified long gap forces partial coverage and N/A FPS. It remains visible as a gap and can be the worst observed sample, but is not classified as an over-budget frame. React Native Mobile does not emit Chromium RunTask events; Hermes ProfileChunk is separate CPU-profile evidence." : "Active UI FPS uses native vsync intervals while frames are being produced. Idle gaps are excluded. Fewer than five usable intervals reports N/A. Android over-budget frames miss FrameDeadline when available, with the detected refresh period used only as a fallback. React Native Mobile does not emit Chromium RunTask events; Hermes ProfileChunk is separate CPU-profile evidence.";
+  const p95Heading = iosCadence ? "UI p95 cadence" : "UI p95 frame";
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>UI smoothness</title><style>:root{color-scheme:dark}*{box-sizing:border-box}body{font:15px system-ui,-apple-system,sans-serif;margin:0;background:#0b0d12;color:#f1f5f9}main{max-width:1320px;margin:auto;padding:32px}h1{font-size:28px;margin:0 0 6px}.lede,.action,small{color:#94a3b8}.cards{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px;margin:24px 0}.card,.coverage{padding:18px;border:1px solid #293244;border-radius:12px;background:#141821}.label{display:block;color:#94a3b8;font-size:12px;text-transform:uppercase;letter-spacing:.06em;margin-bottom:8px}.value{font-size:20px;font-weight:700}.partial{color:#fbbf24}.complete{color:#6ee7b7}.unavailable{color:#f87171}.coverage{margin-top:20px}.coverage h2{font-size:16px;margin:0 0 8px}.coverage ul,.coverage p{margin:8px 0 0;color:#cbd5e1}.coverage ul{padding-left:20px}table{width:100%;border-collapse:collapse;margin-top:24px;background:#141821;border:1px solid #293244;border-radius:12px;overflow:hidden}th,td{text-align:left;padding:12px;border-bottom:1px solid #293244;vertical-align:top}th{color:#93c5fd;font-size:12px;text-transform:uppercase;letter-spacing:.04em}.duration{height:8px;min-width:140px;background:#252c3a;border-radius:99px;overflow:hidden;margin:4px 0 5px}.duration span{display:block;height:100%;background:#7c3aed;border-radius:inherit}.legend{color:#94a3b8;font-size:13px;margin:10px 0 0}@media(max-width:760px){main{padding:20px}.cards{grid-template-columns:1fr}table{display:block;overflow-x:auto}}</style></head><body><main><h1>UI smoothness</h1><p class="lede">Native UI evidence attributed to recipe-node boundaries. Node duration includes action and wait time; it is not FPS.</p><section class="cards"><div class="card"><span class="label">Evidence status</span><span class="value ${artifact.status}">${artifact.status}</span></div><div class="card"><span class="label">Platform</span><span class="value">${artifact.platform}</span></div><div class="card"><span class="label">Worst observed sample</span><span class="value">${worst}</span></div></section><section class="coverage"><h2>Coverage</h2>${sources}${gaps}</section><table><thead><tr><th>Interaction</th><th>Node duration</th><th>UI samples</th><th>Display Hz</th><th>Active UI FPS</th><th>FPS intervals</th><th>${p95Heading}</th><th>Over-budget %</th><th>JS tasks</th><th>JS long tasks</th><th>Longest JS task</th></tr></thead><tbody>${rows}</tbody></table><p class="legend">${legend}</p></main></body></html>
 `;
 }
 async function readArtifact(artifactsDir, artifactPath) {
@@ -364,7 +475,7 @@ async function indexPerformanceArtifacts(manifestPath, paths) {
     manifestPath,
     paths.map((artifactPath) => ({
       path: artifactPath,
-      type: artifactPath.endsWith(".html") ? "report" : "metric",
+      type: artifactPath.endsWith(".html") ? "report" : artifactPath.endsWith(".json.gz") ? "trace" : "metric",
       label: "UI smoothness observation",
       category: "diagnostic"
     }))
@@ -372,6 +483,7 @@ async function indexPerformanceArtifacts(manifestPath, paths) {
 }
 function unavailableCapture(session, window, reason) {
   const unavailableJavaScript = {
+    applicability: "applicable",
     status: "unavailable",
     kind: "unavailable",
     unavailableReasons: [reason.slice(0, 256)],
@@ -439,8 +551,9 @@ function boundedDuration(value) {
   }
   return duration;
 }
-function metric(value) {
-  return value === void 0 ? "\u2014" : String(value);
+function metric(value, digits) {
+  if (value === void 0) return "N/A";
+  return digits === void 0 ? String(value) : String(Number(value.toFixed(digits)));
 }
 function escapeHtml(value) {
   return value.replace(/[&<>"']/gu, (character) => {

package/docs/PERFORMANCE-CAPTURE.md

@@ -1,6 +1,6 @@
 # UI smoothness capture
 
-`app.performance_capture` attributes CDP trace samples to the exact Recipe Protocol v1 nodes that run inside an explicit window. Mobile and Extension use the same action contract.
+`app.performance_capture` attributes native frame samples to the exact Recipe Protocol v1 nodes that run inside an explicit window. Mobile and Extension use the same action contract.
 
 ```json
 {
@@ -13,21 +13,50 @@
 }
 ```
 
-End the same ID with `phase: "end"`. The action writes bounded JSON and a self-contained HTML report. `app.performance_assert` can require a status, minimum frame count, and specific node intervals.
+End the same ID with `phase: "end"`. The action writes a machine-readable schema-v2 summary, a self-contained HTML report, and a bounded gzip-compressed Chrome Trace Event file named `*-trace.json.gz`. Chrome DevTools and Perfetto can consume the trace format. `app.performance_assert` can require a status, minimum frame count, and specific node intervals.
+
+## How it works
+
+1. `app.performance_capture` with `phase: "start"` selects the platform source and starts a bounded capture window.
+2. The recipe runner records each node's start and end on the host clock while the interaction runs.
+3. `phase: "end"` maps native frame timestamps onto those node intervals and closes the source before building artifacts.
+4. The harness writes summary JSON for tools, self-contained HTML for people, and a gzip-compressed Chrome trace for DevTools or Perfetto.
+5. `app.performance_assert` checks source status, frame count, and required node attribution. Missing coverage fails or remains `N/A`; it never becomes zero.
+
+## Host prerequisites
+
+Run `mm-harness doctor --json` from the target checkout before performance work on a new machine.
+
+| Target | Required host tools | Notes |
+| --- | --- | --- |
+| Android | `adb` from Android Platform Tools | `gfxinfo framestats` is built into Android; there is no separate `gfxinfo` package to install. |
+| iOS Simulator | Xcode command-line tools (`xcrun`) | Native frames require a debug client with `unstable_frameRecordingEnabled: true`. Visible UI assertions and `ui.navigate page=perps-market mode=...` also require `idb`. |
+| Extension | Chrome or Chromium with an isolated CDP profile | The harness uses Chromium's Tracing domain. |
+| Trace viewing | Chrome DevTools or Perfetto | Optional for recipe execution; required only to inspect the raw `*-trace.json.gz` file visually. |
+
+`Flashlight`, Instruments, and an in-app FPS overlay are not harness dependencies. Keep the recipe HUD visible; it is separate from the performance source.
 
 ## Sources and status
 
-- Mobile uses React Native's `Tracing.start`, `Tracing.dataCollected`, and `Tracing.end` implementation. iOS frame timings come from its built-in `CADisplayLink` observer. Android frame timings come from `Window.FrameMetrics`. The app build must report `unstable_frameRecordingEnabled: true`; otherwise native UI coverage is partial or unavailable.
+- Android polls `adb shell dumpsys gfxinfo <package> framestats` from the host. It maps Android uptime to recipe timestamps, merges frame snapshots, and measures `FrameCompleted - IntendedVsync` against the device's refresh-rate budget. It does not need a Mobile patch.
+- iOS uses React Native's `Tracing.start`, `Tracing.dataCollected`, and `Tracing.end` implementation. Frame timings come from its native `CADisplayLink` observer. The debug app must report `unstable_frameRecordingEnabled: true`; otherwise native UI coverage is unavailable. Instruments `Animation Hitches` and `Core Animation FPS` do not support iOS Simulator.
+- React Native rejects iOS Tracing after more than one RN host has been registered during the app process lifetime. Its counter is cumulative: removing the old host does not decrement it. Unlocking does not create or remove a host; the MetaMask unlock path only unlocks the wallet and navigates. The observed second host came from reopening an already-running Expo dev-client process against Metro.
+- Establish the iOS measurement cohort explicitly: run `app.lifecycle` with `command: "restart"` outside every capture window, unlock the keyring after the process restart, prove the wallet reached Home, then start `app.performance_capture`. Unlocking does not register another host; restart → unlock → trace passed in one process. This terminates only the app process. It must not restart Metro or the simulator, and capture failure must never trigger it as automatic recovery.
 - Extension uses Chromium's implementation of the same CDP Tracing domain. Frame and JavaScript data count only after the harness proves they belong to the MetaMask renderer. Unresolved browser-wide events produce partial or unavailable coverage.
-- The harness records a CDP clock marker and maps trace timestamps onto recipe-node timestamps. It waits for `Tracing.tracingComplete` before writing evidence.
+- CDP sources record a clock marker and map trace timestamps onto recipe-node timestamps. They wait for `Tracing.tracingComplete` before writing evidence. Android uses the uptime value emitted by `gfxinfo`; the report exposes the measured clock-mapping uncertainty because it bounds node attribution.
 - The JSON report includes bounded trace evidence counts for `BeginFrame`, `DrawFrame`, `RunTask`, and `ProfileChunk`, plus data-loss and retention-overflow flags.
-- UI frames and JavaScript work remain separate sources. `RunTask` events produce JavaScript task summaries. Sampling `ProfileChunk` events prove profiler data exists but are not converted to task timing or FPS. JavaScript work is never labelled as UI or JS FPS.
+- UI frames and JavaScript work remain separate sources. Chromium `RunTask` events produce JavaScript task summaries on Extension. React Native Mobile does not emit `RunTask`, so Mobile reports those fields as not applicable and judges coverage from native UI frames. Sampling `ProfileChunk` events prove Hermes profiler data exists but are not converted to task timing or FPS.
+- Active UI FPS uses consecutive native vsync intervals only while frames are being produced. Fewer than five usable intervals or an unclassified long cadence gap reports `N/A`. Sampling jitter can never raise active FPS above the detected refresh rate.
+- The trace cadence determines the refresh rate and fallback per-frame budget. Android over-budget percentage uses `FrameDeadline` when present; frame percentiles use `FrameCompleted - IntendedVsync`. iOS percentiles describe continuous `CADisplayLink` cadence rather than render work duration. An unclassified long gap forces partial coverage and `N/A` FPS. It stays visible as a gap and can be the worst observed sample, but it is not classified as an over-budget frame.
 - `complete`, `partial`, and `unavailable` describe source coverage. Missing data is never converted to zero.
+- Raw trace timestamps use host epoch microseconds. Standard complete events on the `MetaMask Harness / Recipe nodes` track preserve the node boundaries used by the HTML and JSON reports.
 
 `app.performance_assert.minimum_frame_count` applies only to native UI or Chromium renderer frames. JavaScript task count cannot satisfy it.
 
+Node duration includes automation, native state checks, and wait time inside the node. It is not screen time-to-content. Use product lifecycle milestones for section visibility and data readiness.
+
 Capture is explicit only. Use the action for comparisons on the same runtime and build. Automatic capture remains disabled until its overhead passes a matched benchmark.
 
 ## Sentry promotion boundary
 
-This action does not send data to Sentry. A future product integration may promote only bounded aggregates after release-build overhead is independently accepted: source status, stable node/action name, frame count, p50/p95/p99, jank percentage, and longest frame. Do not send raw frame samples, recipe parameters, wallet/account identity, URLs, or artifact contents.
+This action does not send data to Sentry. A future product integration may promote only bounded aggregates after release-build overhead is independently accepted: source status, stable node/action name, frame count, p50/p95/p99, over-budget percentage, and longest frame. Do not send raw frame samples, recipe parameters, wallet/account identity, URLs, or artifact contents.

package/library/actions/mobile/perps/read-visible-state-loop.mjs

@@ -0,0 +1,73 @@
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+import {
+  normalizeVisiblePerpsState,
+  resolveVisibleStateOptions,
+} from '../../shared/perps/visible-state.mjs';
+
+export async function readVisiblePerpsState(
+  input,
+  observe = observeNativeUi,
+) {
+  const options = resolveVisibleStateOptions(input.node);
+  const deadline = Date.now() + Number(input.node?.timeout_ms ?? 30_000);
+  let observed;
+  let screen;
+  let visible;
+  let lastAssertionError;
+  let lastObservationError;
+  do {
+    try {
+      observed = await observe(
+        { refs: ['ui.screen', 'ui.visible'], node: input.node },
+        input.context,
+      );
+      lastObservationError = undefined;
+    } catch (error) {
+      if (
+        /requires the idb client|requires adb|Android SDK Platform Tools/iu.test(
+          String(error?.message ?? error),
+        )
+      ) {
+        throw error;
+      }
+      lastObservationError = error;
+      observed = undefined;
+    }
+    screen = observed?.observations?.['ui.screen'];
+    visible = observed?.observations?.['ui.visible'];
+    if (screen && visible) {
+      try {
+        return {
+          action: input.action,
+          ...normalizeVisiblePerpsState({
+            route: screen.route,
+            title: screen.title,
+            items: visible.items,
+            offscreenItems: visible.hidden_or_offscreen,
+            truncated: visible.truncated,
+          }, options, 'mobile'),
+          proofPath: 'native-accessibility',
+        };
+      } catch (error) {
+        lastAssertionError = error;
+      }
+    }
+    if (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  } while (Date.now() < deadline);
+  if (lastAssertionError) throw lastAssertionError;
+  const warning = observed?.warnings
+    ?.map((entry) => entry.message)
+    .filter(Boolean)
+    .join('; ');
+  const observationError = lastObservationError instanceof Error
+    ? lastObservationError.message
+    : lastObservationError === undefined
+      ? undefined
+      : String(lastObservationError);
+  const detail = warning ?? observationError;
+  throw new Error(
+    `Mobile visible Perps state is unavailable${detail ? `: ${detail}` : '.'}`,
+  );
+}