@deeeed/metamask-harness 0.41.1 → 0.43.0

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/NETWORK-CAPTURE.md

@@ -0,0 +1,98 @@
+# Recipe-scoped network capture
+
+`app.network_capture` records HTTP requests between two Recipe Protocol v1 nodes without product instrumentation. Mobile uses its shared Hermes CDP broker; Extension uses one browser-level CDP observer across the extension page, service worker, and offscreen targets.
+
+```json
+{
+  "action": "app.network_capture",
+  "phase": "start",
+  "id": "perps-home",
+  "url_includes": ["api.hyperliquid.xyz/info"],
+  "methods": ["POST"],
+  "body_json_fields": ["type", "req.coin", "dex"],
+  "next": "exercise-flow"
+}
+```
+
+```json
+{
+  "action": "app.network_capture",
+  "phase": "end",
+  "id": "perps-home",
+  "artifact_path": "network/perps-home.json",
+  "next": "assert-network"
+}
+```
+
+```json
+{
+  "action": "app.network_assert",
+  "id": "perps-home",
+  "artifact_path": "network/perps-home.json",
+  "required_status": "complete",
+  "next": "done"
+}
+```
+
+The end node writes and indexes a JSON summary containing request totals, counts by method/host/retained body type, relative timestamps, reconnects, and dropped events.
+
+## Automatic run evidence
+
+Every live Mobile or Extension recipe run also writes `network/run-summary.json`. The automatic artifact is metadata-only and records:
+
+- method, host, sanitized path, elapsed time, and the safe top-level request `type` when present;
+- `running`, `passed`, and `failed` node-boundary events on the same elapsed-time axis;
+- completeness, reconnect, drop, and coverage-gap status.
+
+This makes requests between node boundaries inspectable without adding capture nodes to every recipe. Set `MM_HARNESS_AUTO_NETWORK_CAPTURE=0` only for observer-overhead comparisons or a runtime that intentionally forbids network inspection. Explicit `app.network_capture` windows remain the source for focused filters, assertions, and additional allowlisted body fields.
+
+## Status semantics
+
+- `complete`: the debugger target stayed attached and every retained event fit inside the configured cap.
+- `partial`: the target rotated/disconnected, the window exceeded `max_duration_ms`, events exceeded a retention bound, or a requested body field could not be inspected safely. Never interpret zero requests from a partial capture as proof of absence.
+- `unavailable`: the selected runtime rejected Network capture or no observer-owned target became available.
+
+Use `required_status`, `required_min_requests`, `required_max_requests`,
+`required_types`, and `forbidden_types` on a separate `app.network_assert`
+node. The end node is therefore recorded and its JSON artifact indexed before
+an assertion can fail. Absence assertions (`required_max_requests` and
+`forbidden_types`) require `required_status: "complete"`; partial or unavailable
+coverage cannot prove absence. Type assertions also require `type` in the start
+node's `body_json_fields`, so an unobserved discriminator cannot prove presence
+or absence.
+
+## Redaction
+
+- Query strings, request headers, response bodies, cookies, and authorization are never stored.
+- Request bodies are omitted unless `body_json_fields` explicitly allowlists bounded, non-sensitive primitive fields.
+- Field names containing address, account, user, token, secret, password, key, cookie, or authorization are rejected.
+- Each capture is capped at 4 MiB in addition to `max_requests`, which defaults
+  to 1,000 and is capped at 10,000.
+- `max_duration_ms` defaults to five minutes and is capped at one hour; at
+  most 16 windows may be active for one device.
+- The local broker socket is mode `0600`.
+
+## Runtime design
+
+Mobile uses one per-slot broker for console events, bridge commands, HUD actions, and Network events. The broker reconnects when Hermes rotates and marks active captures partial because events emitted while no target exists cannot be proven complete.
+
+Extension uses the browser CDP target to attach to every target owned by the loaded MetaMask extension. Target creation or removal re-enables Network collection and marks active captures partial when continuity cannot be proven.
+
+| Adapter | Automatic run artifact | Explicit window/assert | Raw interactive view |
+| --- | --- | --- | --- |
+| Mobile | Supported | Supported | React Native DevTools |
+| Extension | Supported | Supported | Chrome DevTools |
+| Core | Not applicable | Not declared | Not applicable |
+
+## Recipe v1 observation-window convention
+
+Observation capabilities use one lifecycle:
+
+1. start a bounded observer;
+2. execute ordinary recipe nodes;
+3. end the observer and index its artifact;
+4. assert the indexed artifact separately.
+
+Every observer reports `complete`, `partial`, or `unavailable`; a partial or unavailable window cannot prove absence. A future Mobile FPS/jank observer should reuse this lifecycle and node-boundary timeline, but no FPS action is advertised until its device overhead and metrics are validated.
+
+Local validation of the shared request processor measured about 1.6 microseconds of median CPU per retained request. Five real observer lifecycle samples measured 19.9 ms median on Mobile and 9.4 ms median on Extension; observed maxima were 117 ms and 192 ms. These are harness-overhead measurements, not product-network or UI latency claims.

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

@@ -259,6 +259,23 @@ when repeated direct access has a stable cross-task contract.
 The protocol is authoritative:
 <https://farmslot.io/docs/reference/recipe-protocol-v1>.
 
+## Capture network requests
+
+Use `app.network_capture` start/end nodes to record redacted HTTP requests made
+inside one Mobile or Extension recipe window, then a separate
+`app.network_assert` node when the recipe needs self-checking evidence. Every
+live recipe also indexes a bounded metadata-only run summary with node-boundary
+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

package/library/actions/mobile/app/network_assert.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+
+import { assertNetwork } from '../../shared/app/network-assert.mjs';
+import { runAdapter } from '../platform/bridge.mjs';
+
+export { assertNetwork };
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runAdapter(assertNetwork);
+}