simframe 0.8.0 → 0.10.0

package/src/actions.js

@@ -6,6 +6,8 @@ import * as api from './index.js';
 import * as graph from './graph.js';
 import * as input from './input.js';
 import * as intent from './intent.js';
+import * as metrics from './metrics.js';
+import * as screenmap from './screenmap.js';
 import { launchApp, openUrl, setPermission, terminateApp } from './platform/index.js';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -25,11 +27,22 @@ const MAX_PAUSE_MS = 5000;
  * falls out at `reaction` instead. That bounds the cost of the honest case
  * rather than the broken one.
  */
+/**
+ * The stillness window stays fixed, and that is a decision rather than an
+ * oversight. Learning a stillness window is the half of Phase 11 that was
+ * reverted for cause: a wait that ends early never observes the pauses that
+ * come later, so the estimator ratchets itself down and the graph learns
+ * transitions that never happened. See docs/BENCHMARKS.md, Phase 11.
+ */
 const FOCUS_STABLE_MS = 250;
 /**
- * Long enough for a slow capture loop to produce a frame or two. The screenshot
- * engine idles at 1.5 fps — 667 ms between frames — so anything under that is a
- * verdict reached before there was anything to look at.
+ * The cold defaults, unchanged, for a field this screen has not been measured
+ * focusing. `graph.focusPlan` takes over once it has been, and may only make
+ * the wait longer.
+ *
+ * 900 ms is long enough for a slow capture loop to produce a frame or two. The
+ * screenshot engine idles at 1.5 fps — 667 ms between frames — so anything
+ * under that is a verdict reached before there was anything to look at.
  */
 const FOCUS_REACTION_MS = 900;
 const FOCUS_TIMEOUT_MS = 3000;
@@ -112,6 +125,12 @@ export async function runScript(
     // Rebuild the HID session and retry once when a hardware button provably
     // did nothing. Off only for a caller deliberately testing that path.
     recoverInput = true,
+    // What this run is called and how few steps it could take, for the flow
+    // record. A bare `sim_do` has neither and says so with nulls rather than
+    // inventing a name — an unnamed run still gets timed, it just cannot be
+    // compared against a human baseline.
+    flowName = null,
+    minSteps = null,
     options,
   } = {},
 ) {
@@ -119,6 +138,24 @@ export async function runScript(
   const { device } = await api.ensureDaemon(deviceQuery, options);
   const udid = device.udid;
   const startedAt = Date.now();
+  // Measurement only. Nothing below reads these, and a failure to write one
+  // can never change what a step does — see `note`.
+  const flowId = metrics.newFlowId();
+  const escalations = [];
+  const verdicts = [];
+  // Named noteEscalation, not note: the step loop below declares its own
+  // `note` string for the no-visible-change suffix, which shadowed this and
+  // turned every escalating verdict into a failed step reading "note is not a
+  // function". The try/catch inside here could not help — the throw was at the
+  // call site, one scope out. Instrumentation that can fail a flow is worse
+  // than no instrumentation.
+  const noteEscalation = (record) => {
+    try {
+      escalations.push(metrics.recordEscalation(udid, { flowId, flowName, ...record }));
+    } catch {
+      /* instrumentation must not be able to fail a flow it is only watching */
+    }
+  };
 
   const needsInput = steps.some((s) => ACTION_STEPS.has(normalizeStep(s).action));
   if (needsInput) {
@@ -145,10 +182,35 @@ export async function runScript(
   // moves nothing and is not a failure, so an unbounded retry would rebuild the
   // session and press again on every such step for no reason.
   let inputRecovered = false;
+  /**
+   * The previous step's transition, still to be measured.
+   *
+   * Its pause profile cannot be read while the step is running — that is the
+   * biased measurement that corrupted the graph — so it is read one step later,
+   * off a frame history whose end nothing about the wait decided. See
+   * `api.longestQuietGap`.
+   */
+  let pendingGap = null;
+  const measurePendingGap = async () => {
+    if (!pendingGap) return;
+    const { from, step: prevStep, actionAt } = pendingGap;
+    pendingGap = null;
+    try {
+      const history = (await api.getState(deviceQuery, { options })).state.history ?? [];
+      const trueGapMs = api.longestQuietGap(history, actionAt);
+      if (trueGapMs != null) graph.noteTrueGap(udid, from, prevStep, trueGapMs);
+    } catch {
+      /* a statistic nothing acts on must never be able to fail a flow */
+    }
+  };
 
   for (const [i, raw] of steps.entries()) {
     const step = normalizeStep(raw);
     const stepStart = Date.now();
+    // Before anything else, and before this step disturbs the screen: the
+    // previous transition is definitely over by now, so its true pause profile
+    // is readable.
+    await measurePendingGap();
     // The baseline for "did the screen react" must predate the action itself.
     const beforeState = (await api.getState(deviceQuery, { options })).state;
     const before = beforeState.hash;
@@ -164,14 +226,72 @@ export async function runScript(
     // What this action did last time it was taken here, if ever.
     const prediction = verify && beforeScreen?.hash ? graph.predict(udid, beforeScreen, step) : null;
     try {
-      let detail = await runStep(deviceQuery, udid, step, { screen, options, frames });
+      // How long this transition has cost before, on this screen, for this
+      // action. A cold edge gets the old fixed default and says so; a measured
+      // one gets p95 plus a margin. Research §7.
+      //
+      // Read before the step, not after, because one of the waits it informs
+      // happens *inside* the step: a `type into` taps the field and waits for
+      // focus before it types, and that wait used to be three constants.
+      const learned = verify && beforeScreen?.hash ? graph.timingFor(udid, beforeScreen, step) : null;
+      const focus = {
+        plan: graph.focusPlan(learned, {
+          reactionMs: FOCUS_REACTION_MS,
+          timeoutMs: FOCUS_TIMEOUT_MS,
+          stillnessMs: FOCUS_STABLE_MS,
+          keyboardUp: Boolean(beforeScreen?.keyboard),
+        }),
+        observedMs: null,
+      };
+      let detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
+      // How long this screen must hold still before it counts as settled.
+      //
+      // 500 ms was a constant paid by every step of every flow, and it is the
+      // reducible half of a settle: the rest is the transition genuinely
+      // taking time. An edge whose transition has never paused mid-flight
+      // needs 150 ms of quiet, not 500. Capped at the caller's own value, so
+      // this can only ever shorten a wait.
+      // NOT YET USED TO DECIDE ANYTHING, and the reason is worth the space.
+      //
+      // `graph.stillnessFor` computes a shorter window from the longest pause
+      // ever observed inside this transition, and measured live it made the
+      // Settings flow 8.0 s instead of 11.5 s — and wrong. Eight runs in a row
+      // failed at step 2 with the screen still showing Settings root, because
+      // step 1's settle returned mid-push, `screenIdentity` then read the
+      // screen we had not left yet, and the graph learned root -> root as a
+      // verified edge and started predicting it.
+      //
+      // The flaw is in the estimator, not the idea: the gap statistic is
+      // gathered only from what a wait itself observed, so a wait that ends
+      // early never sees the pauses that come later, the gaps look like zero,
+      // the window ratchets down, and the next wait ends earlier still. A
+      // self-reinforcing bias with a wrong graph at the end of it.
+      //
+      // The unbiased estimator is available and is a separate piece of work:
+      // the frame history holds every frame's timestamp and diff, so the true
+      // motion profile of a transition can be computed *after* it is over
+      // rather than from inside the wait that cut it short. Until then the
+      // gaps are recorded and not acted on — measuring is safe, and this is
+      // Phase 11's own rule that a learned number may only ever shorten a
+      // wait, applied to itself.
+      const stillness = step.stableMs ?? stableMs;
+      const stillnessPlan = learned ? graph.stillnessFor(learned, stillness) : { cold: true };
+      // A settle is not satisfied until the screen has held still for
+      // `stillness`, so a budget below that can never be met — and the learned
+      // p95 is measured from waits that include the stillness window, which
+      // makes it self-consistent but not self-evidently so. A tab switch with
+      // a p95 of 90ms would get a 240ms budget and then time out at 240ms
+      // waiting for 500ms of quiet, turning every fast edge into a failure.
+      const floorMs = stillness + 250;
+      const budgetMs = step.timeoutMs
+        ?? (learned && !learned.cold ? Math.max(learned.timeoutMs, floorMs) : timeoutMs);
       const settleFor = async () => {
         if (!autoSettle || !ACTION_STEPS.has(step.action)) return null;
         const w = await api.waitFor(deviceQuery, {
           mode: 'settle',
           since: before,
-          stableMs: step.stableMs ?? stableMs,
-          timeoutMs: step.timeoutMs ?? timeoutMs,
+          stableMs: stillness,
+          timeoutMs: budgetMs,
           options,
         });
         return {
@@ -180,9 +300,64 @@ export async function runScript(
           sawChange: w.sawChange,
           stalled: Boolean(w.stalled),
           noVisibleChange: Boolean(w.noVisibleChange),
+          // What this wait was allowed, and where the number came from. A
+          // timeout nobody can explain is how a fixed sleep comes back as a
+          // constant with a comment.
+          budgetMs,
+          stillnessMs: stillness,
+          quietGapMs: w.quietGapMs,
+          // The baseline had already finished moving when the wait began, so it
+          // was re-taken from the live screen. Surfaced because it means the
+          // step before this one had not finished when this one started.
+          staleBaseline: Boolean(w.staleBaseline),
+          // Something moved in one region only — a switch, a radio dot, a
+          // segment highlight. Worth saying, because it is the difference
+          // between "the action did nothing" and "the action did something the
+          // whole-screen mean cannot see".
+          smallChange: Boolean(w.smallChange),
+          timing: learned
+            ? {
+              p50: learned.p50,
+              p95: learned.p95,
+              samples: learned.samples,
+              cold: learned.cold,
+              gapP95: learned.gapP95,
+              gapSamples: learned.gapSamples,
+              // What it *would* have been, for the eval that has to happen
+              // before this is trusted with a wait.
+              stillnessWouldBe: stillnessPlan.stillnessMs ?? null,
+            }
+            : null,
         };
       };
       let settled = await settleFor();
+      // A screen that is still working earns more time; a screen doing nothing
+      // visible has already answered. Research §7: keep waiting past p95 only
+      // while the transition classifier says something is loading, and never
+      // past Nielsen's 10 s — at which point it escalates with the timing
+      // attached rather than waiting longer.
+      if (settled && !settled.ok && !settled.noVisibleChange && learned && !learned.cold) {
+        const kind = (await api.getState(deviceQuery, { options })).state.transition?.kind;
+        const verdict = graph.slowerThanUsual({
+          elapsedMs: settled.waitedMs, p95: learned.p95, settled: false, kind,
+        });
+        if (verdict.keepWaiting) {
+          const remaining = graph.HARD_CAP_MS - settled.waitedMs;
+          const more = await api.waitFor(deviceQuery, {
+            mode: 'settle', since: before, stableMs: stillness, timeoutMs: remaining, options,
+          });
+          settled = {
+            ...settled,
+            ok: more.satisfied,
+            waitedMs: settled.waitedMs + more.waitedMs,
+            sawChange: settled.sawChange || more.sawChange,
+            quietGapMs: Math.max(settled.quietGapMs ?? 0, more.quietGapMs ?? 0),
+            slowerThanUsual: verdict.note,
+          };
+        } else if (verdict.slower) {
+          settled = { ...settled, slowerThanUsual: verdict.note };
+        }
+      }
 
       // A hardware button that moved nothing did not arrive.
       //
@@ -226,14 +401,66 @@ export async function runScript(
         // for. Requiring both meant a screen that settled slowly recorded
         // nothing at all.
         endScreen = afterScreen;
-        if (afterScreen.confirmed && afterScreen.hash) {
-          graph.record(udid, { from: beforeScreen, action: step, to: afterScreen, kind });
+        // An action with no observed effect teaches the graph nothing, and
+        // recording it teaches something false.
+        //
+        // This is the second half of the same bug. A settle that returned on a
+        // stale baseline reported `ok` for a tap that moved nothing, and the
+        // recorder asked only whether the *reading* was confirmed — so
+        // `root -> root` went in as a verified edge and started being
+        // predicted. Re-baselining stops the settle lying; this stops the
+        // graph learning from a step that has no evidence behind it either way.
+        //
+        // It does cost a real case for now: a control that genuinely returns to
+        // the same screen — a toggle — is invisible to the change detector at
+        // eight times below its threshold, so it reads as no-visible-change and
+        // its edge is no longer recorded. That is the right trade while the
+        // detector cannot see it, and it comes back on its own once it can.
+        const noEvidence = Boolean(settled?.noVisibleChange);
+        if (afterScreen.confirmed && afterScreen.hash && !noEvidence) {
+          // The observed cost of this transition, which is what makes the next
+          // one adaptive. Only from a settle that was actually satisfied: a
+          // timeout is not a measurement of how long the screen takes, it is a
+          // measurement of how long we were prepared to wait.
+          graph.record(udid, {
+            from: beforeScreen, action: step, to: afterScreen, kind,
+            settleMs: settled?.ok ? settled.waitedMs : undefined,
+            // The pause statistic is worth having from any settle that saw the
+            // screen move, satisfied or not: a transition that paused for
+            // 400ms and then timed out is exactly the case a 150ms stillness
+            // window would have got wrong.
+            quietGapMs: settled?.sawChange ? settled.quietGapMs : undefined,
+            // The focus wait's own distribution, kept apart from the step's.
+            // Only set when a field was tapped and visibly took focus.
+            focusMs: focus.observedMs ?? undefined,
+          });
+          pendingGap = { from: beforeScreen, step, actionAt: stepStart };
+          carriedScreen = afterScreen;
+        } else if (afterScreen.confirmed && afterScreen.hash) {
+          // Where we are is still known; only what got us here is not worth
+          // remembering. Carrying it saves the next step a perception pass.
           carriedScreen = afterScreen;
         }
       }
 
       const wrongTurn = wrongTurnFrom(verification);
-      const note = settled?.noVisibleChange ? ' [no visible change]' : '';
+      // `[no visible change]` after a launch is ambiguous between two very
+      // different things, and a real session read it the wrong way twice:
+      // "the app was already in front, so nothing needed to move" and "the app
+      // did not come forward". Measured on this Xcode, `simctl launch` *does*
+      // front an already-running app, so the first reading is the likely one —
+      // but likely is not the same as said, and the step is the only place that
+      // can say it.
+      const launchNote = step.action === 'launch' && settled?.noVisibleChange
+        ? ' [the screen did not change, so this app was already in front — or it did not come forward]'
+        : '';
+      const note = launchNote
+        + (settled?.smallChange ? ' [a small change, in one region only]' : '')
+        + (settled?.noVisibleChange ? ' [no visible change]' : '')
+        + (settled?.staleBaseline ? ' [baseline had already settled; re-taken from the live screen]' : '')
+        + (settled?.blackFrames
+          ? ` [${settled.blackFrames} black frame(s) waited through${settled.blackMs ? `, still black after ${settled.blackMs}ms` : ''}]`
+          : '');
       results.push({
         index: i,
         action: step.action,
@@ -244,6 +471,25 @@ export async function runScript(
         settled,
       });
       const halt = haltDecision({ verification, stopOnUnexpected, continueOnError });
+      if (verification?.verdict) verdicts.push(verification.verdict);
+      if (metrics.ESCALATING_VERDICTS.has(verification?.verdict)) {
+        noteEscalation({
+          stepIndex: i,
+          fingerprint: beforeScreen?.hash ?? null,
+          reason: 'verification_failed',
+          candidates: [],
+          // A halted run is a decision simframe made and stopped on; a step
+          // that moved nothing carries on and leaves the judgement to whoever
+          // reads the result.
+          outcome: halt.halt ? 'failed' : 'escalated_to_model',
+          wallMs: Date.now() - stepStart,
+          detail: `${verification.verdict}: ${verification.detail}`
+            + (settled?.slowerThanUsual ? ` [${settled.slowerThanUsual}]` : '')
+            + (settled?.timing && !settled.timing.cold
+              ? ` [waited ${settled.waitedMs}ms of a ${settled.budgetMs}ms budget; p95 ${settled.timing.p95}ms]`
+              : ''),
+        });
+      }
       if (halt.halt) {
         results[results.length - 1].ok = false;
         results[results.length - 1].error = halt.error;
@@ -252,20 +498,56 @@ export async function runScript(
       }
     } catch (err) {
       results.push({ index: i, action: step.action, ok: false, ms: Date.now() - stepStart, error: err.message });
+      const why = metrics.reasonForStepError(step, err);
+      noteEscalation({
+        stepIndex: i,
+        fingerprint: beforeScreen?.hash ?? metrics.fingerprintNow(udid, screenmap),
+        reason: why.reason,
+        candidates: why.candidates,
+        tried: why.tried,
+        outcome: 'failed',
+        wallMs: Date.now() - stepStart,
+        detail: err.message,
+      });
       failed = true;
       if (!continueOnError) break;
     }
   }
 
+  // The last step has no next step to measure it, and its transition is over by
+  // the time the loop exits.
+  await measurePendingGap();
+
+  const wallMs = Date.now() - startedAt;
+  try {
+    metrics.recordFlow(udid, metrics.flowRecordFrom({
+      flowId,
+      flowName,
+      udid,
+      startedAt,
+      wallMs,
+      stepsTaken: results.length,
+      totalSteps: steps.length,
+      minSteps,
+      imagesSent: frames.length,
+      escalations,
+      verdicts,
+      completed: !failed && results.length === steps.length,
+    }));
+  } catch {
+    /* as above: a flow that ran is not a flow that failed because of a log */
+  }
+
   return {
     device,
     // Returned so a run that verified end to end can be handed straight to
     // navigate.saveFlow without the caller reassembling what it just ran.
     steps,
+    flowId,
     endScreen,
     results,
     ok: !failed,
-    totalMs: Date.now() - startedAt,
+    totalMs: wallMs,
     ranSteps: results.length,
     totalSteps: steps.length,
     frames,
@@ -284,18 +566,31 @@ export async function runScript(
  */
 async function focusField(deviceQuery, udid, step, ctx) {
   const found = await api.locate(deviceQuery, step.into, { index: step.index, refresh: step.refresh });
+  // What this field has cost to focus before, on this screen. Cold, or with no
+  // verification running, that is exactly the three constants above; measured,
+  // it can only be longer. `graph.focusPlan` carries the reason it is either.
+  const plan = ctx.focus?.plan ?? {
+    reactionMs: FOCUS_REACTION_MS, timeoutMs: FOCUS_TIMEOUT_MS, cold: true, from: 'no timing in hand',
+  };
+  const tappedAt = Date.now();
   await input.tapPoint(udid, found.target.x, found.target.y);
   const focused = await api.waitFor(deviceQuery, {
     mode: 'settle',
     stableMs: FOCUS_STABLE_MS,
-    reactionMs: FOCUS_REACTION_MS,
-    timeoutMs: FOCUS_TIMEOUT_MS,
+    reactionMs: plan.reactionMs,
+    timeoutMs: plan.timeoutMs,
     options: ctx.options,
   });
+  // Only a wait that was satisfied is a measurement of how long focus takes. A
+  // reaction window that ran out measures how long we were prepared to watch a
+  // screen that did not move, and banking that would teach the edge the cost of
+  // its own impatience — the estimator mistake learned stillness made.
+  if (ctx.focus && focused.satisfied) ctx.focus.observedMs = Date.now() - tappedAt;
   return {
     found,
     where: `"${found.target.label}" at ${found.target.x},${found.target.y}`,
     quiet: focused.satisfied ? '' : ' [the field did not visibly take focus]',
+    waited: focused.satisfied && !plan.cold ? ` [focus in ${focused.waitedMs}ms, ${plan.from}]` : '',
   };
 }
 
@@ -327,7 +622,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
       if (step.into) {
         const field = await focusField(deviceQuery, udid, step, ctx);
         await input.typeText(udid, step.text ?? step.value);
-        return `typed into ${field.where}${field.quiet}`;
+        return `typed into ${field.where}${field.quiet}${field.waited}`;
       }
       await input.typeText(udid, step.text ?? step.value);
       return 'typed text';
@@ -340,7 +635,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
       if (step.into) {
         const field = await focusField(deviceQuery, udid, step, ctx);
         await input.pasteText(udid, step.text ?? step.value);
-        return `pasted into ${field.where}${field.quiet}`;
+        return `pasted into ${field.where}${field.quiet}${field.waited}`;
       }
       await input.pasteText(udid, step.text ?? step.value);
       return 'pasted into the focused field';
@@ -420,6 +715,14 @@ async function runStep(deviceQuery, udid, step, ctx) {
           return `"${node.label ?? target}" appeared`;
         } catch (err) {
           lastError = err.message;
+          // Same rule as `waitFor`, and `matchElement` says it in its own
+          // words: a query that matched several elements has found them all
+          // already.
+          if (/matched \d+ elements/.test(err.message)) {
+            throw new Error(
+              `${err.message}\n  (not waiting: it is already on screen, and waiting cannot make it unique)`,
+            );
+          }
         }
         await sleep(250);
       }
@@ -472,6 +775,22 @@ async function runStep(deviceQuery, udid, step, ctx) {
           return `"${found.target.label}" appeared at ${found.target.x},${found.target.y}`;
         } catch (err) {
           lastError = err.message;
+          // Waiting cannot make a thing unique.
+          //
+          // Reported from a real session: a wait on an ambiguous string spent
+          // the full 30 s and then listed four matches, all four of which were
+          // on the very first frame. The disambiguation is good and it arrived
+          // twenty-nine seconds after everything it needed. `ambiguous` means
+          // the target is *present*, several times over — which is precisely
+          // the case where more time changes nothing.
+          //
+          // Distinguished by the tag at the throw site rather than by reading
+          // the message, because "not on this screen" tags the same reason.
+          if (metrics.escalationOf(err)?.ambiguous) {
+            throw new Error(
+              `${err.message}\n  (not waiting: it is already on screen, and waiting cannot make it unique)`,
+            );
+          }
         }
         if (Date.now() >= limit) break;
         await sleep(POLL_MS);

package/src/analyze.js

@@ -35,6 +35,42 @@ export function signatureDiff(a, b) {
   return sum / a.length / 255;
 }
 
+/**
+ * A change small enough that the whole-screen mean cannot see it.
+ *
+ * `changed` in both daemons is `signatureDiff > 0.004`, a mean over a 4x8 grid
+ * of gray means. Measured on this device, an iOS switch flipping:
+ *
+ *   mean diff        0.001348   — a third of the threshold, so: not a change
+ *   max cell delta   0.043137   — one cell of thirty-two, in row 1
+ *
+ * So the entire class of small binary controls — switches, radio dots,
+ * checkboxes, segment highlights — changes nothing as far as the daemon is
+ * concerned, and a step that flips one reports `no-visible-change`, which is a
+ * verdict that escalates.
+ *
+ * The threshold sits in a measured gap rather than being chosen. Eighty seconds
+ * of a *static* screen gave a largest per-cell delta of 0.003922, in row 0,
+ * which is the status-bar clock ticking over — the only thing moving. So the
+ * separation is 0.0039 against 0.0431, eleven times, and 0.012 is three times
+ * the noise and three and a half times under the signal. No row is excluded:
+ * the clock does not reach the threshold, which is a better reason to ignore it
+ * than a structural exclusion that would also blind the nav bar.
+ *
+ * What this deliberately does **not** do is feed stillness. `stableForMs` stays
+ * on the mean, because a blinking text caret is a small localised change and a
+ * screen with a cursor in it would otherwise never settle. The two signals are
+ * independent by design: this one answers "did the action do anything", and the
+ * mean answers "has the screen finished moving".
+ */
+export const CELL_CHANGE = 0.012;
+
+/** The largest single-region change between two signatures, 0-1. */
+export function maxCellDelta(a, b) {
+  const deltas = regionDeltas(a, b);
+  return deltas.length ? Math.max(...deltas) : 0;
+}
+
 /** Per-region change fractions, so callers can tell a toast from a screen push. */
 export function regionDeltas(a, b) {
   if (!a || !b || a.length !== b.length) return a ? a.map(() => 1) : [];
@@ -69,6 +105,40 @@ export function signatureToHex(sig) {
   return sig.map((v) => v.toString(16).padStart(2, '0')).join('');
 }
 
+/**
+ * Is this frame black — not dark, black?
+ *
+ * The capture wedge (docs/BENCHMARKS.md) leaves `simctl io screenshot`
+ * succeeding and returning 0 non-black pixels of 3,162,132, and simframe's own
+ * frames go the same way: the display pipeline stops rendering while
+ * everything about the capture path keeps reporting success. It self-recovers
+ * most times and a device restart cures the rest, so the useful thing is to
+ * notice early — before a settle spends its whole budget deciding a black
+ * screen is a calm one.
+ *
+ * The signature is already computed for every frame, so this costs 32 integer
+ * comparisons and no decode. A real screen does not come close: measured on
+ * this device's Settings root, the 32 bytes ran 191–245.
+ *
+ * The threshold is a level, not a fraction, and it is on the *maximum*: one
+ * cell with anything in it is enough to say the display is rendering. That
+ * matters because a dark-mode screen, a video, or a splash on black are all
+ * legitimately near-zero in most cells and this must not call them faults.
+ *
+ * And it says "the frames are black", never "the simulator is wedged". A
+ * screen can be black because the app drew black. What makes it a wedge is
+ * that it stays black while input is being delivered, and only the caller
+ * knows that.
+ */
+export const BLACK_LEVEL = 8;
+
+export function isBlackFrame(sig, { level = BLACK_LEVEL } = {}) {
+  const bytes = typeof sig === 'string' ? hexToSignature(sig) : sig;
+  if (!bytes?.length) return false;
+  for (const b of bytes) if (b > level) return false;
+  return true;
+}
+
 export function hexToSignature(hex) {
   const out = [];
   for (let i = 0; i < hex.length; i += 2) out.push(parseInt(hex.slice(i, i + 2), 16));