@deeeed/metamask-harness 0.42.0 → 0.43.0

package/dist/network-observation.js

@@ -1,12 +1,17 @@
-import fs from "node:fs";
 import path from "node:path";
 import brokerModule from "../adapters/mobile/bridge-runtime/lib/cdp-broker.cjs";
+import configModule from "../adapters/mobile/bridge-runtime/lib/config.cjs";
 import {
   createExtensionNetworkObserver
 } from "./adapters/extension/network-observer.js";
+import {
+  indexArtifactManifest,
+  writeContainedArtifact
+} from "./artifact-files.js";
 const AUTO_CAPTURE_ID = "run-network";
 const AUTO_ARTIFACT_PATH = "network/run-summary.json";
 const { brokerSocketPath, createBrokerClient } = brokerModule;
+const { resolvePort } = configModule;
 const sessions = /* @__PURE__ */ new Map();
 async function startRunNetworkObservation(adapter, target, artifactsDir, env, ports = {}) {
   if (adapter === "core") return void 0;
@@ -54,9 +59,9 @@ async function startRunNetworkObservation(adapter, target, artifactsDir, env, po
       try {
         if (runtimeEnv.MM_HARNESS_AUTO_NETWORK_CAPTURE !== "0") {
           const summary = await automaticSummary(session);
-          writeSummary(key, AUTO_ARTIFACT_PATH, summary);
+          await writeSummary(key, AUTO_ARTIFACT_PATH, summary);
           if (artifactManifestPath) {
-            indexArtifact(
+            await indexArtifact(
               artifactManifestPath,
               AUTO_ARTIFACT_PATH,
               "Automatic network observation"
@@ -106,7 +111,7 @@ async function handleRunNetworkAction(platform, action, node, context) {
     node.artifact_path ?? `network/${id}-summary.json`
   );
   const summary = await session.backend.end(id);
-  writeSummary(context.artifactsDir, artifactPath, summary);
+  await writeSummary(context.artifactsDir, artifactPath, summary);
   return {
     output: {
       action,
@@ -123,13 +128,7 @@ async function handleRunNetworkAction(platform, action, node, context) {
   };
 }
 async function createMobileNetworkBackend(target, env) {
-  const runtimeDir = env.RECIPE_RUNTIME_DIR ? path.resolve(target, env.RECIPE_RUNTIME_DIR) : path.join(target, "temp", "recipe", "runtime");
-  const socketPath = brokerSocketPath(runtimeDir);
-  const discoveryClient = await createBrokerClient(socketPath, "", 1e4);
-  const targets = await discoveryClient.control("list-targets", {}, 1e4);
-  discoveryClient.close();
-  const deviceId = selectMobileBrokerTarget(targets, env);
-  const client = await createBrokerClient(socketPath, deviceId, 1e4);
+  const { client } = await connectMobileBroker(target, env);
   return {
     start(params) {
       return client.control("capture-start", params, 1e4);
@@ -142,14 +141,30 @@ async function createMobileNetworkBackend(target, env) {
     }
   };
 }
+async function connectMobileBroker(target, env) {
+  const runtimeDir = env.RECIPE_RUNTIME_DIR ? path.resolve(target, env.RECIPE_RUNTIME_DIR) : path.join(target, "temp", "recipe", "runtime");
+  const socketPath = brokerSocketPath(
+    runtimeDir,
+    resolvePort(env, target)
+  );
+  const discoveryClient = await createBrokerClient(socketPath, "", 1e4);
+  let targets;
+  try {
+    targets = await discoveryClient.control(
+      "resolve-targets",
+      { nameIncludes: mobileTargetPin(env) },
+      1e4
+    );
+  } finally {
+    discoveryClient.close();
+  }
+  const deviceId = selectMobileBrokerTarget(targets, env);
+  const client = await createBrokerClient(socketPath, deviceId, 1e4);
+  return { client, deviceId };
+}
 function selectMobileBrokerTarget(value, env) {
   const targets = Array.isArray(value) ? value.map(asRecord).filter((target) => target.deviceId) : [];
-  const platform = String(
-    env.MM_HARNESS_EXPLICIT_PLATFORM ?? env.RECIPE_HARNESS_PLATFORM ?? ""
-  ).toLowerCase();
-  const pin = String(
-    platform === "android" ? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? "" : platform === "ios" ? env.IOS_SIMULATOR ?? "" : env.IOS_SIMULATOR ?? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? ""
-  ).trim();
+  const pin = mobileTargetPin(env);
   const candidates = pin ? targets.filter(
     (target) => String(target.name ?? "").toLowerCase().includes(pin.toLowerCase())
   ) : targets;
@@ -160,6 +175,14 @@ function selectMobileBrokerTarget(value, env) {
   }
   return String(candidates[0].deviceId);
 }
+function mobileTargetPin(env) {
+  const platform = String(
+    env.MM_HARNESS_EXPLICIT_PLATFORM ?? env.RECIPE_HARNESS_PLATFORM ?? ""
+  ).toLowerCase();
+  return String(
+    platform === "android" ? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? "" : platform === "ios" ? env.IOS_SIMULATOR ?? "" : env.IOS_SIMULATOR ?? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? ""
+  ).trim();
+}
 async function automaticSummary(session) {
   let summary;
   if (session.autoStarted && session.backend) {
@@ -216,38 +239,26 @@ function captureParams(id, node) {
     maxDurationMs: node.max_duration_ms
   };
 }
-function writeSummary(artifactsDir, relativePath, summary) {
-  const destination = resolveArtifact(artifactsDir, relativePath);
-  fs.mkdirSync(path.dirname(destination), { recursive: true });
-  fs.writeFileSync(destination, `${JSON.stringify(summary, null, 2)}
-`);
-}
-function resolveArtifact(artifactsDir, relativePath) {
-  const root = path.resolve(artifactsDir);
-  const resolved = path.resolve(root, relativePath);
-  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
-    throw new Error("Network artifact_path escapes artifactsDir.");
-  }
-  return resolved;
-}
-function indexArtifact(artifactManifestPath, relativePath, label) {
-  const manifest = asRecord(
-    JSON.parse(fs.readFileSync(artifactManifestPath, "utf8"))
+async function writeSummary(artifactsDir, relativePath, summary) {
+  await writeContainedArtifact(
+    artifactsDir,
+    relativePath,
+    `${JSON.stringify(summary, null, 2)}
+`,
+    "Network artifact"
   );
-  const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts.filter(
-    (artifact) => asRecord(artifact).path !== relativePath
-  ) : [];
-  artifacts.push({
-    path: relativePath,
-    type: "report",
-    label,
-    category: "diagnostic"
-  });
-  manifest.artifacts = artifacts;
-  fs.writeFileSync(
+}
+async function indexArtifact(artifactManifestPath, relativePath, label) {
+  await indexArtifactManifest(
     artifactManifestPath,
-    `${JSON.stringify(manifest, null, 2)}
-`
+    [
+      {
+        path: relativePath,
+        type: "report",
+        label,
+        category: "diagnostic"
+      }
+    ]
   );
 }
 function extensionCdpPort(env) {
@@ -266,6 +277,7 @@ function asRecord(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
 export {
+  connectMobileBroker,
   handleRunNetworkAction,
   startRunNetworkObservation
 };

package/dist/performance-observation.js

@@ -0,0 +1,465 @@
+import path from "node:path";
+import {
+  createMobilePerformanceBackend
+} from "./adapters/mobile/performance-observer.js";
+import { createExtensionPerformanceBackend } from "./adapters/extension/performance-observer.js";
+import { summarizeFrames } from "./adapters/mobile/frame-metrics.js";
+import { summarizeJavaScriptTasks } from "./adapters/performance/js-task-metrics.js";
+import {
+  indexArtifactManifest,
+  readContainedJsonArtifact,
+  writeContainedArtifact
+} from "./artifact-files.js";
+const sessions = /* @__PURE__ */ new Map();
+const DEFAULT_MAX_DURATION_MS = 5 * 60 * 1e3;
+const MAX_DURATION_MS = 60 * 60 * 1e3;
+function startRunPerformanceObservation(adapter, target, artifactsDir, env, ports = {}) {
+  if (adapter === "core") return void 0;
+  const key = path.resolve(artifactsDir);
+  const session = {
+    adapter,
+    artifactsDir: key,
+    env: {
+      ...env,
+      ...ports.watcherPort ? { WATCHER_PORT: ports.watcherPort } : {}
+    },
+    nodeEvents: [],
+    ports,
+    target,
+    windows: /* @__PURE__ */ new Map()
+  };
+  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);
+      }
+    }
+  }, 100);
+  sessions.set(key, session);
+  return {
+    onActionEvent(event) {
+      session.nodeEvents.push({ ...event, epochMs: Date.now() });
+    },
+    async finalize(artifactManifestPath) {
+      if (session.expirySweep) clearInterval(session.expirySweep);
+      try {
+        for (const window of [...session.windows.values()]) {
+          const result = await finishCaptureWindow(session, window).catch(
+            (error) => unavailableCapture(session, window, errorMessage(error))
+          );
+          const artifact = {
+            ...result,
+            status: "partial",
+            coverageGapReasons: [
+              ...result.coverageGapReasons,
+              "Recipe run ended before app.performance_capture phase=end."
+            ]
+          };
+          const jsonPath = `performance/${safeId(window.id)}-summary.json`;
+          const htmlPath = `performance/${safeId(window.id)}.html`;
+          await writeArtifacts(session.artifactsDir, jsonPath, htmlPath, artifact);
+          if (artifactManifestPath) {
+            await indexPerformanceArtifacts(artifactManifestPath, [
+              jsonPath,
+              htmlPath
+            ]);
+          }
+        }
+      } finally {
+        session.windows.clear();
+        await session.backend?.close();
+        sessions.delete(key);
+      }
+    }
+  };
+}
+async function handleRunPerformanceAction(platform, action, node, context) {
+  if (platform === "core") return null;
+  if (action === "app.performance_assert") {
+    return { output: await assertPerformance(node, context) };
+  }
+  if (action !== "app.performance_capture") return null;
+  const session = sessions.get(path.resolve(context.artifactsDir));
+  if (!session) {
+    throw new Error("UI performance observation session was not started.");
+  }
+  const phase = String(node.phase ?? "").toLowerCase();
+  const id = String(node.id ?? "").trim();
+  if (!["start", "end"].includes(phase) || !id) {
+    throw new Error(
+      "app.performance_capture requires phase=start|end and a non-empty id."
+    );
+  }
+  if (phase === "start") {
+    if (session.windows.has(id)) {
+      await finishCaptureWindow(session, session.windows.get(id)).catch(
+        () => void 0
+      );
+      session.windows.delete(id);
+    }
+    const backend = await performanceBackend(session);
+    await backend.start(id);
+    const maxDurationMs = boundedDuration(node.max_duration_ms);
+    session.windows.set(id, {
+      id,
+      maxDurationMs,
+      startedAtEpochMs: Date.now()
+    });
+    return { output: { action, id, phase, status: "started" } };
+  }
+  const window = session.windows.get(id);
+  if (!window) throw new Error(`Performance capture is not active: ${id}`);
+  const artifact = await finishCaptureWindow(session, window);
+  session.windows.delete(id);
+  const jsonPath = String(
+    node.artifact_path ?? `performance/${safeId(id)}-summary.json`
+  );
+  const htmlPath = String(
+    node.html_path ?? `performance/${safeId(id)}.html`
+  );
+  await writeArtifacts(session.artifactsDir, jsonPath, htmlPath, artifact);
+  return {
+    output: {
+      action,
+      id,
+      phase,
+      status: artifact.status,
+      artifactPath: jsonPath,
+      htmlPath
+    },
+    artifacts: [
+      { path: jsonPath, type: "metric", nodeId: context.nodeId },
+      { path: htmlPath, type: "report", nodeId: context.nodeId }
+    ]
+  };
+}
+async function performanceBackend(session) {
+  if (session.backend) return session.backend;
+  if (session.backendError) throw new Error(session.backendError);
+  try {
+    session.backend = session.adapter === "mobile" ? await createMobilePerformanceBackend(session.target, session.env) : await createExtensionPerformanceBackend(
+      extensionCdpPort(session),
+      session.target
+    );
+    return session.backend;
+  } catch (error) {
+    session.backendError = errorMessage(error);
+    throw error;
+  }
+}
+async function endCapture(session, window) {
+  const sourceResult = await (await performanceBackend(session)).end(window.id);
+  const endedAtEpochMs = Date.now();
+  return buildPerformanceArtifact(
+    window,
+    endedAtEpochMs,
+    sourceResult,
+    session.nodeEvents
+  );
+}
+function finishCaptureWindow(session, window) {
+  return window.expiredResult ?? endCapture(session, window);
+}
+function buildPerformanceArtifact(window, endedAtEpochMs, result, allEvents) {
+  const nodeEvents = allEvents.filter(
+    (event) => event.epochMs >= window.startedAtEpochMs && event.epochMs <= endedAtEpochMs
+  );
+  const nodeIntervals = buildNodeIntervals(
+    nodeEvents,
+    result.javascript,
+    result.nativeUi
+  );
+  const coverageGapReasons = [
+    ...result.javascript.unavailableReasons.map(
+      (reason) => `javascript unavailable: ${reason}`
+    ),
+    ...result.javascript.coverageGapReasons.map(
+      (reason) => `javascript: ${reason}`
+    ),
+    ...result.nativeUi.unavailableReasons.map(
+      (reason) => `nativeUi unavailable: ${reason}`
+    ),
+    ...result.nativeUi.coverageGapReasons.map(
+      (reason) => `nativeUi: ${reason}`
+    )
+  ];
+  const exceededMaxDuration = endedAtEpochMs - window.startedAtEpochMs >= window.maxDurationMs;
+  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 worst = worstInteraction(nodeIntervals);
+  return {
+    schemaVersion: 1,
+    id: window.id,
+    status,
+    platform: result.platform,
+    startedAtEpochMs: window.startedAtEpochMs,
+    endedAtEpochMs,
+    durationMs: endedAtEpochMs - window.startedAtEpochMs,
+    javascript: { ...result.javascript, samples: [] },
+    nativeUi: { ...result.nativeUi, samples: [] },
+    trace: result.trace,
+    nodeEvents,
+    nodeIntervals,
+    ...worst ? { worstInteraction: worst } : {},
+    coverageGapReasons
+  };
+}
+function buildNodeIntervals(events, javascript, nativeUi) {
+  const active = /* @__PURE__ */ new Map();
+  const intervals = [];
+  for (const event of events) {
+    if (event.status === "running") {
+      active.set(event.nodeId, event);
+      continue;
+    }
+    const start = active.get(event.nodeId);
+    if (!start) continue;
+    active.delete(event.nodeId);
+    intervals.push({
+      action: event.action,
+      durationMs: event.epochMs - start.epochMs,
+      endedAtEpochMs: event.epochMs,
+      javascript: summarizeJavaScriptTasks(
+        samplesWithin(javascript, start.epochMs, event.epochMs)
+      ),
+      nativeUi: summarizeFrames(
+        samplesWithin(nativeUi, start.epochMs, event.epochMs)
+      ),
+      nodeId: event.nodeId,
+      outcome: event.status,
+      startedAtEpochMs: start.epochMs
+    });
+  }
+  return intervals;
+}
+function samplesWithin(source, startEpochMs, endEpochMs) {
+  return source.samples.filter(
+    (sample) => sample.completedAtEpochMs - sample.durationMs >= startEpochMs && sample.completedAtEpochMs <= endEpochMs
+  );
+}
+function worstInteraction(intervals) {
+  let worst;
+  for (const interval of intervals) {
+    const candidates = [
+      {
+        longestSampleMs: interval.javascript.longestTaskMs,
+        source: "javascriptTask"
+      },
+      {
+        longestSampleMs: interval.nativeUi.longestFrameMs,
+        source: "nativeUiFrame"
+      }
+    ];
+    for (const candidate of candidates) {
+      const { longestSampleMs } = candidate;
+      if (longestSampleMs !== void 0 && (!worst || longestSampleMs > worst.longestSampleMs)) {
+        worst = {
+          action: interval.action,
+          longestSampleMs,
+          nodeId: interval.nodeId,
+          source: candidate.source
+        };
+      }
+    }
+  }
+  return worst;
+}
+async function assertPerformance(node, context) {
+  const id = String(node.id ?? "").trim();
+  if (!id) throw new Error("app.performance_assert requires id.");
+  const artifactPath = String(
+    node.artifact_path ?? `performance/${safeId(id)}-summary.json`
+  );
+  const artifact = await readArtifact(context.artifactsDir, artifactPath);
+  if (artifact.schemaVersion !== 1 || 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)] : [];
+  if (statuses.length > 0 && !statuses.includes(artifact.status)) {
+    throw new Error(
+      `app.performance_assert expected ${statuses.join("|")}, got ${artifact.status}.`
+    );
+  }
+  const requiredNodeIds = Array.isArray(node.required_node_ids) ? node.required_node_ids.map(String) : [];
+  const observedNodeIds = new Set(
+    Array.isArray(artifact.nodeIntervals) ? artifact.nodeIntervals.map((interval) => String(interval.nodeId)) : []
+  );
+  const missingNodeIds = requiredNodeIds.filter(
+    (nodeId) => !observedNodeIds.has(nodeId)
+  );
+  if (missingNodeIds.length > 0) {
+    throw new Error(
+      `app.performance_assert missing node interval(s): ${missingNodeIds.join(", ")}.`
+    );
+  }
+  const minimumFrameCount = Number(node.minimum_frame_count ?? 0);
+  if (!Number.isInteger(minimumFrameCount) || minimumFrameCount < 0) {
+    throw new Error(
+      "app.performance_assert minimum_frame_count must be a non-negative integer."
+    );
+  }
+  const nativeFrames = Number(artifact.nativeUi?.summary?.frameCount ?? 0);
+  if (nativeFrames < minimumFrameCount) {
+    throw new Error(
+      `app.performance_assert expected at least ${minimumFrameCount} frame(s).`
+    );
+  }
+  if (node.require_native_ui_when_supported === true && artifact.nativeUi?.status !== "complete") {
+    throw new Error(
+      "app.performance_assert requires complete native UI data."
+    );
+  }
+  return {
+    action: "app.performance_assert",
+    artifactPath,
+    id,
+    status: artifact.status
+  };
+}
+async function writeArtifacts(artifactsDir, jsonPath, htmlPath, artifact) {
+  await writeContainedArtifact(
+    artifactsDir,
+    jsonPath,
+    `${JSON.stringify(artifact, null, 2)}
+`,
+    "Performance artifact"
+  );
+  await writeContainedArtifact(
+    artifactsDir,
+    htmlPath,
+    renderPerformanceHtml(artifact),
+    "Performance artifact"
+  );
+}
+function renderPerformanceHtml(artifact) {
+  const maxNodeDurationMs = Math.max(
+    1,
+    ...artifact.nodeIntervals.map((interval) => interval.durationMs)
+  );
+  const rows = artifact.nodeIntervals.map((interval) => {
+    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>`;
+  }).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>
+`;
+}
+async function readArtifact(artifactsDir, artifactPath) {
+  return readContainedJsonArtifact(
+    artifactsDir,
+    artifactPath,
+    5 * 1024 * 1024,
+    "Performance artifact"
+  );
+}
+async function indexPerformanceArtifacts(manifestPath, paths) {
+  await indexArtifactManifest(
+    manifestPath,
+    paths.map((artifactPath) => ({
+      path: artifactPath,
+      type: artifactPath.endsWith(".html") ? "report" : "metric",
+      label: "UI smoothness observation",
+      category: "diagnostic"
+    }))
+  );
+}
+function unavailableCapture(session, window, reason) {
+  const unavailableJavaScript = {
+    status: "unavailable",
+    kind: "unavailable",
+    unavailableReasons: [reason.slice(0, 256)],
+    coverageGapReasons: [],
+    samples: [],
+    summary: { taskCount: 0 }
+  };
+  const unavailableNativeUi = {
+    status: "unavailable",
+    kind: "unavailable",
+    unavailableReasons: [reason.slice(0, 256)],
+    coverageGapReasons: [],
+    samples: [],
+    summary: { frameCount: 0 }
+  };
+  return buildPerformanceArtifact(
+    window,
+    Date.now(),
+    {
+      platform: resolveSessionPlatform(session),
+      javascript: unavailableJavaScript,
+      nativeUi: unavailableNativeUi,
+      trace: {
+        beginFrameCount: 0,
+        dataLossOccurred: false,
+        drawFrameCount: 0,
+        overflow: false,
+        profileChunkCount: 0,
+        runTaskCount: 0,
+        scope: "unresolved",
+        totalEventCount: 0
+      }
+    },
+    session.nodeEvents
+  );
+}
+function resolveSessionPlatform(session) {
+  if (session.adapter === "extension") return "extension";
+  const explicit = String(
+    session.env.MM_HARNESS_EXPLICIT_PLATFORM ?? session.env.RECIPE_HARNESS_PLATFORM ?? ""
+  ).toLowerCase();
+  if (explicit === "android" || explicit === "ios") return explicit;
+  return session.env.ADB_SERIAL || session.env.ANDROID_SERIAL || session.env.ANDROID_DEVICE ? "android" : "ios";
+}
+function extensionCdpPort(session) {
+  const port = Number(
+    session.ports.cdpPort ?? session.env.CDP_PORT ?? session.env.RECIPE_CDP_PORT
+  );
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error("Extension performance observation requires CDP_PORT.");
+  }
+  return port;
+}
+function safeId(value) {
+  const result = value.replace(/[^a-zA-Z0-9_-]/gu, "-").slice(0, 80);
+  if (!result) throw new Error("Performance capture id is invalid.");
+  return result;
+}
+function boundedDuration(value) {
+  const duration = Number(value ?? DEFAULT_MAX_DURATION_MS);
+  if (!Number.isInteger(duration) || duration < 1 || duration > MAX_DURATION_MS) {
+    throw new Error(
+      `app.performance_capture max_duration_ms must be an integer from 1 to ${MAX_DURATION_MS}.`
+    );
+  }
+  return duration;
+}
+function metric(value) {
+  return value === void 0 ? "\u2014" : String(value);
+}
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/gu, (character) => {
+    const entities = {
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;"
+    };
+    return entities[character] ?? character;
+  });
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  buildPerformanceArtifact,
+  handleRunPerformanceAction,
+  renderPerformanceHtml,
+  startRunPerformanceObservation
+};

package/docs/PERFORMANCE-CAPTURE.md

@@ -0,0 +1,33 @@
+# 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.
+
+```json
+{
+  "action": "app.performance_capture",
+  "phase": "start",
+  "id": "market-scroll",
+  "max_duration_ms": 60000,
+  "intent": "Start UI smoothness capture",
+  "next": "scroll"
+}
+```
+
+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.
+
+## 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.
+- 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.
+- 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.
+- `complete`, `partial`, and `unavailable` describe source coverage. Missing data is never converted to zero.
+
+`app.performance_assert.minimum_frame_count` applies only to native UI or Chromium renderer frames. JavaScript task count cannot satisfy it.
+
+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.

package/docs/RECIPES.md

@@ -269,6 +269,13 @@ events. The result distinguishes complete, partial, and unavailable evidence
 so a target rotation cannot be misreported as zero requests. See
 [Recipe-scoped network capture](NETWORK-CAPTURE.md).
 
+## Capture UI smoothness
+
+Use explicit `app.performance_capture` start/end nodes to correlate Mobile or
+Extension CDP trace samples with recipe-node boundaries.
+`app.performance_assert` checks the resulting evidence contract. Capture is
+not automatic; see [UI smoothness capture](PERFORMANCE-CAPTURE.md).
+
 ## Share a library
 
 ```text