@deeeed/metamask-harness 0.44.3 → 0.45.1

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/commands/call.js

@@ -34,7 +34,6 @@ import {
   executeWithHealBounds,
   prepareHeal,
   persistRunEffects,
-  recoverRunInfra,
   resolveMetaMaskLibrarySources,
   preflightRecipe,
   runRecipe,
@@ -289,7 +288,7 @@ async function handleCall(argv) {
       skipMobileSourceFreshness: authoredMobileRestart || adapter === "mobile" && readMobileReleaseArtifactState(target) !== null
     });
     if (typeof prepared === "number") return prepared;
-    const { state, heal } = prepared;
+    const { state } = prepared;
     preflightedExecution = await preflightRecipe(
       adapter,
       recipe,
@@ -335,14 +334,8 @@ async function handleCall(argv) {
             state
           );
         },
-        adapter,
         target,
-        heal,
-        state,
-        () => recoverRunInfra(adapter, target, json, {
-          cdpPort: optionString(options, "cdpPort"),
-          watcherPort: optionString(options, "watcherPort") ?? optionString(options, "metroPort")
-        })
+        state
       );
     } catch (error) {
       await networkObservation?.finalize().catch(() => void 0);

package/dist/commands/run-engine.js

@@ -1358,44 +1358,6 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
   });
   return null;
 }
-const RUN_RECOVERY_CODE = {
-  mobile: "mobile.runtime_recovered",
-  extension: "extension.runtime_recovered",
-  core: "run.retried"
-};
-async function recoverRunInfra(adapter, target, json, runtimeOptions = {}) {
-  getAdapterSurface(adapter).resolveSlotPorts(target);
-  const previousCdpPort = process.env.CDP_PORT;
-  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
-  if (runtimeOptions.cdpPort) {
-    process.env.CDP_PORT = runtimeOptions.cdpPort;
-    process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
-  }
-  try {
-    if (adapter === "extension") {
-      const { releaseArtifactState } = await import("../adapters/extension/runtime-decision.js");
-      const artifact = releaseArtifactState(target);
-      if (artifact.status !== "none" && artifact.status !== "valid") {
-        return {
-          status: 1,
-          output: "Release artifact recovery cannot trust the recorded runtime identity.\nNext: rerun runtime-launch with the same artifact source."
-        };
-      }
-      const { launchExtension } = await import("./launch/extension.js");
-      return launchExtension(target, "quick", false);
-    }
-    if (adapter === "mobile") {
-      return {
-        status: 1,
-        output: "Automatic Mobile runtime recovery is disabled.\nNext: use an explicit app.lifecycle action when the recipe intends to relaunch the app."
-      };
-    }
-    return { status: 0, output: "headless run retry" };
-  } finally {
-    restoreEnv("CDP_PORT", previousCdpPort);
-    restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
-  }
-}
 function readRunFailureText(result) {
   try {
     const trace = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
@@ -1407,38 +1369,13 @@ function readRunFailureText(result) {
     return "";
   }
 }
-async function executeWithHealBounds(exec, adapter, target, heal, state, recover = () => recoverRunInfra(adapter, target, false), onRecovery = () => void 0) {
-  let result = await exec();
-  for (; ; ) {
-    if (result.status === "pass") return { result, violation: null };
-    const violation = checkHealBounds(
-      target,
-      readRunFailureText(result),
-      state
-    );
-    if (violation !== null) return { result, violation };
-    if (adapter === "mobile") return { result, violation: null };
-    if (heal === "off") return { result, violation: null };
-    const recoveryCode = RUN_RECOVERY_CODE[adapter];
-    state.attemptedRecoveries.push(recoveryCode);
-    onRecovery(recoveryCode);
-    const recovery = await recover();
-    if (recovery.status !== 0) {
-      return { result, violation: null };
-    }
-    if (adapter === "extension") {
-      state.mutations.push({
-        type: "runtime",
-        action: "reloaded",
-        reasonCode: recoveryCode
-      });
-    }
-    result = await exec();
-    if (result.status === "pass") {
-      state.recovered.push(recoveryCode);
-      return { result, violation: null };
-    }
-  }
+async function executeWithHealBounds(exec, target, state) {
+  const result = await exec();
+  if (result.status === "pass") return { result, violation: null };
+  return {
+    result,
+    violation: checkHealBounds(target, readRunFailureText(result), state)
+  };
 }
 function emitHealViolation(json, command, result, violation, state, adapter) {
   const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? 'create temp/recipe/runtime/wallet-fixture.json, or add "account": "<0x\u2026>" to the node block in the recipe' : violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
@@ -1499,7 +1436,6 @@ export {
   preflightRecipe,
   prepareHeal,
   prepareRuntimeIfNeeded,
-  recoverRunInfra,
   resolveMetaMaskLibrarySources,
   resolveRunRecipeArg,
   runOneNode,

package/dist/commands/run.js

@@ -22,7 +22,6 @@ import {
   preflightRecipe,
   prepareHeal,
   persistRunEffects,
-  recoverRunInfra,
   runRecipe,
   validateRunRecipeStatic
 } from "./run-engine.js";
@@ -304,7 +303,7 @@ async function handleRunInner({ positional, options }, stream) {
       });
       return prepared;
     }
-    const { state, heal } = prepared;
+    const { state } = prepared;
     preflightedExecution = await preflightRecipe(
       adapter,
       validated.recipeFile,
@@ -353,12 +352,8 @@ async function handleRunInner({ positional, options }, stream) {
             state
           );
         },
-        adapter,
         target,
-        heal,
-        state,
-        () => recoverRunInfra(adapter, target, machine, runtimeOptions),
-        (code) => stream.phase("recover", { code })
+        state
       );
     } catch (error) {
       await networkObservation?.finalize().catch(() => void 0);

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/CONTRIBUTING.md

@@ -108,6 +108,14 @@ Write evidence under `context.artifactsDir` and return relative artifact paths.
 `METAMASK_RECIPE_LIVE_ADAPTER_DIR` is the explicit task-local implementation
 root; configured libraries are the durable sharing mechanism.
 
+An ordinary action performs only its declared operation and observes the
+product's result. It must not restart or reload the app, reconnect providers or
+streams, clear caches, reset state, or retry a failed journey. Those operations
+can hide the product failure the recipe exists to catch. If lifecycle is the
+subject, expose it as an explicit recipe node with separate postconditions. If
+transport or lifecycle fails during another action, return the failure and keep
+the evidence. Do not repair and continue.
+
 Add a bundled action only when it is reusable, typed, stable, reduces inference
 or risk, and has a real postcondition. Otherwise use a team library or task-local
 recipe. Follow [Recipes](RECIPES.md) and [Security](SECURITY.md).