simframe 0.12.1 → 0.13.0

package/src/cli.js

@@ -278,6 +278,10 @@ async function main() {
   if (flags.sensor) options.sensor = String(flags.sensor);
   if (flags.planner) options.planner = String(flags.planner);
   if (flags.supervisor) options.supervisor = String(flags.supervisor);
+  // Stated rather than defaulted, which is the same rule the settle budgets
+  // follow. The default is sized on a developer's machine; a loaded build farm
+  // is a different machine and should say so rather than be guessed at.
+  if (flags.readyTimeoutMs) options.readyTimeoutMs = num(flags.readyTimeoutMs);
 
   switch (command) {
     case undefined:
@@ -463,6 +467,77 @@ async function main() {
     }
 
     case 'frame': {
+      // `--fresh` captures independently of the daemon, and then says whether
+      // the two agree.
+      //
+      // This is the arbiter three field reports had to leave simframe to get.
+      // When `sim_look` served a three-hour-stale image labelled `130ms old`,
+      // the thing that finally settled it was `xcrun simctl io … screenshot` —
+      // run by hand, outside the tool, because nothing inside offered an
+      // independent read. Worse, the obvious candidate lies: `--engine` decides
+      // how to *start* a daemon, so passing `--engine=screenshot` to a read
+      // command returns the running daemon's cached frame. A tester compared
+      // the two, got byte-identical files with the same frame number, and
+      // reasonably concluded "the fallback engine is not an escape hatch".
+      //
+      // One command now answers the question the escape hatch was for: capture
+      // the screen twice by two different paths and report whether they agree.
+      if (flags.fresh) {
+        const dev = await resolveDevice(device);
+        const out = flags.out || path.join(process.cwd(), 'simframe.png');
+        await screenshot(dev.udid, out);
+        const png = fs.readFileSync(out);
+        // The daemon's own newest frame, for comparison. Absent is fine and
+        // interesting in itself: an independent capture that works while the
+        // daemon has none is exactly the wedge.
+        let cached = null;
+        try {
+          cached = await api.getFrame(device, { detail: flags.detail ?? 'normal', options });
+        } catch { /* no daemon, or it has nothing — reported below */ }
+        // Compared by *content*, never by bytes. The direct capture is a
+        // full-resolution PNG and the daemon's is downscaled, so a byte
+        // comparison says "different" every time — which is a confident wrong
+        // answer about the one question this command exists to settle. Both
+        // are decoded and reduced to the same region signature the change
+        // detector already uses, and `signatureDiff` is the same measure that
+        // decides whether a screen moved.
+        let diff = null;
+        if (cached) {
+          try {
+            const a = analyze.regionSignature(decodePng(png));
+            const b = analyze.regionSignature(decodePng(cached.png));
+            diff = analyze.signatureDiff(a, b);
+          } catch { /* an undecodable frame is reported as "could not compare" */ }
+        }
+        // The threshold the daemon itself calls a change. Below it the two
+        // paths are looking at the same screen.
+        const same = diff == null ? null : diff <= analyze.PATHS_AGREE;
+        emit(
+          flags,
+          {
+            file: out,
+            fresh: true,
+            bytes: png.length,
+            daemonSeq: cached?.state?.seq ?? null,
+            daemonAgeMs: cached?.ageMs ?? null,
+            agrees: same,
+            difference: diff == null ? null : Number(diff.toFixed(4)),
+          },
+          [
+            `${out} — captured directly from the device, ${png.length} bytes`,
+            cached
+              ? `the daemon's newest frame is #${cached.state.seq}, ${cached.ageMs}ms old`
+                + (same == null
+                  ? ' — could not be compared (one of the two would not decode)'
+                  : same
+                    ? ` — the two paths agree (difference ${diff.toFixed(4)}, under the ${analyze.PATHS_AGREE} two paths may differ by)`
+                    : ` — they DISAGREE (difference ${diff.toFixed(4)}). Two capture paths see different screens;`
+                      + ' this file is the one that bypassed the daemon. `simframe revive` re-attaches capture.')
+              : 'the daemon has no frame to compare against, while a direct capture worked',
+          ],
+        );
+        return;
+      }
       const res = await api.getFrame(device, { detail: flags.detail ?? 'normal', options });
       const out = flags.out || path.join(process.cwd(), 'simframe.png');
       fs.writeFileSync(out, res.png);
@@ -487,7 +562,9 @@ async function main() {
       } else {
         const s = res.state;
         const out = [];
-        if (!res.live.ok) out.push(`WARNING: ${res.live.note}`);
+        // Any note, not only a failing one: a dead surface reports `ok` with
+        // something important to say. See `liveness`.
+        if (res.live.note) out.push(`WARNING: ${res.live.note}`);
         // A cause, rather than five silent no-ops. Every tap on a stale
         // session is dispatched successfully and moves nothing.
         if (res.input?.stale) out.push(`input: stale — ${res.input.reason}`);
@@ -542,20 +619,36 @@ async function main() {
           changedBeforeWait: Boolean(res.changedBeforeWait),
           noVisibleChange: Boolean(res.noVisibleChange),
           stalled: Boolean(res.stalled),
+          // Where it was still moving, when it never stopped — item 123.
+          //
+          // `waitFor` has computed this since it learned to, and this payload
+          // is hand-built, so the field existed and no caller could see it. I
+          // read a null here and nearly concluded the tracking was broken; it
+          // was the reporting.
+          motion: res.motion ?? null,
+          animating: res.animating ?? null,
           hash: res.state?.hash,
           seq: res.state?.seq,
         },
         () => {
           if (res.satisfied) {
             return `${res.mode === 'change' ? 'changed' : 'settled'} after ${res.waitedMs}ms — frame #${res.state.seq}` +
-              (res.changedBeforeWait ? ' (change had already happened before the call)' : '');
+              (res.changedBeforeWait ? ' (change had already happened before the call)' : '') +
+              (res.animating
+                ? `\nbut a ${res.animating.width}x${res.animating.height} region is still animating`
+                  + ' — the stillness signal is a mean and cannot see it'
+                : '');
           }
           if (res.noVisibleChange) {
             return `no visible change after ${res.waitedMs}ms — screen stable, nothing moved (the action may have had no visible effect)`;
           }
           if (res.stalled) return `capture stalled after ${res.waitedMs}ms — ${res.live.note}`;
           return `timed out after ${res.waitedMs}ms — no ${res.mode === 'change' ? 'change' : 'settle'}` +
-            (res.sawChange ? '' : '; if the change happened before this call, pass `--since` from `simframe mark`');
+            (res.sawChange ? '' : '; if the change happened before this call, pass `--since` from `simframe mark`') +
+            (res.motion
+              ? `\nthe movement is ${res.motion.where}`
+                + `${res.motion.localised ? ` (${res.motion.share}% of it)` : ''}:\n${res.motion.map}`
+              : '');
         },
       );
       process.exitCode = res.satisfied ? 0 : 1;
@@ -734,12 +827,25 @@ async function main() {
           `"${target}" matches more than one screen:`,
           ...(res.candidates ?? []).map((c) => `  ${c.name}  (${c.hash.slice(0, 8)})`),
         ],
+        // Both of these walked, so the steps they took are the useful part and
+        // are printed exactly as a flow prints them.
+        'route-halted': () => [
+          ...(res.results ?? []).map(stepLine),
+          `stopped after ${res.ranSteps} of ${res.steps?.length} step(s) on the way to ${res.screen}`,
+        ],
+        'arrived-elsewhere': () => [
+          ...(res.results ?? []).map(stepLine),
+          `ended at ${res.arrived}, wanted ${res.screen} — every step ran, so an edge the graph`
+            + ' remembers no longer leads where it says. Re-walk it and the graph will relearn.',
+        ],
       };
       if (!res.ok && res.reason) {
         emit(flags, res, refusal[res.reason] ?? `${res.reason}: cannot reach "${res.to ?? target}" from here`);
         process.exitCode = 1;
         return;
       }
+      // Everything that is not ok now carries a reason and was handled above,
+      // so this is the arrival path only.
       emit(
         flags,
         res,
@@ -747,9 +853,7 @@ async function main() {
           ? `already on ${res.screen}`
           : [
               ...(res.results ?? []).map(stepLine),
-              res.ok
-                ? `arrived at ${res.screen} in ${res.ranSteps} step(s)`
-                : `ended at ${res.arrived}, wanted ${res.screen}`,
+              `arrived at ${res.screen} in ${res.ranSteps} step(s)`,
             ],
       );
       process.exitCode = res.ok ? 0 : 1;
@@ -841,11 +945,15 @@ async function main() {
         /* capture not running: fall through and report the send alone */
       }
       const t0 = Date.now();
+      // Item 120, the single-shot half: a coordinate that changed nothing owes
+      // an answer about what it landed on.
+      let aim = null;
       switch (command) {
         case 'tapAt': {
           if (positional.length < 2 || nums.slice(0, 2).some(Number.isNaN)) {
             throw new Error('usage: simframe tapAt <x> <y>');
           }
+          aim = { point: { x: nums[0], y: nums[1] }, what: 'the tap point' };
           await input.tapPoint(dev.udid, nums[0], nums[1], flags.durationMs ? { durationMs: num(flags.durationMs) } : {});
           break;
         }
@@ -853,6 +961,7 @@ async function main() {
           if (positional.length < 4 || nums.slice(0, 4).some(Number.isNaN)) {
             throw new Error('usage: simframe swipe <x1> <y1> <x2> <y2>');
           }
+          aim = { point: { x: nums[0], y: nums[1] }, what: 'the swipe start point' };
           await input.swipe(dev.udid, { x: nums[0], y: nums[1] }, { x: nums[2], y: nums[3] }, { durationMs: num(flags.durationMs, 300) });
           break;
         }
@@ -886,14 +995,22 @@ async function main() {
       // Deliberately not an accusation. Pressing home while already on the
       // springboard legitimately changes nothing, and a warning that cries wolf
       // is how a real one gets ignored.
+      // The map for the screen as it was before the send. Free when the screen
+      // has been perceived once — and silent when it has not, because "we did
+      // not look" must not be printed as "there is nothing there".
+      const hit = changed === false && aim
+        ? api.screenmap.describePoint(api.screenmap.recall(dev.udid, before), aim.point, { what: aim.what })
+        : null;
       const note = changed === false
-        ? ' — the screen did not change. That is expected if the press had nothing to do here;'
+        ? ' — the screen did not change'
+          + (hit ? `, and ${hit}` : '')
+          + '. That is expected if the press had nothing to do here;'
           + ' if you expected a change, input may not be reaching the device —'
           + ' `simframe stop --force && simframe start` rebuilds the session.'
         : '';
       emit(
         flags,
-        { ok: true, command, ms, driver: driver.name, screenChanged: changed },
+        { ok: true, command, ms, driver: driver.name, screenChanged: changed, hit: hit ?? undefined },
         `${command} in ${ms}ms via ${driver.name}${changed === true ? ' — screen changed' : ''}${note}`,
       );
       return;
@@ -1078,13 +1195,31 @@ async function main() {
 
     case 'supervisions': {
       const dev = await resolveDevice(flags.device);
-      const records = metrics.readSupervisions(dev.udid, { limit: flags.last ? num(flags.last) : undefined });
+      // `--session` works here now, and did not before.
+      //
+      // Reported twice from the field: two different session ids returned
+      // byte-identical output while `escalations --session` filtered correctly.
+      // A flag that exists on one command and is silently inert on its sibling
+      // is worse than an absent one — this command's own footer warns that the
+      // counts pool multiple agents and then offered no way to unpool them.
+      const session = flags.session === true
+        ? metrics.sessionId()
+        : (flags.session ? String(flags.session) : null);
+      const all = metrics.readSupervisions(dev.udid, { limit: flags.last ? num(flags.last) : undefined });
+      const records = session ? all.filter((r) => r?.session_id === session) : all;
       const b = metrics.supervisionBreakdown(records);
       if (flags.out) store.writeAtomic(String(flags.out), `${JSON.stringify({ ...b, records }, null, 2)}\n`);
       emit(flags, { ...b, records: flags.verbose ? records : undefined }, [
         `${b.total} supervisor ruling${b.total === 1 ? '' : 's'} on ${dev.name}`,
-        b.total ? '' : 'Nothing has been judged on this device yet. The supervisor is off unless'
-          + ' SIMFRAME_SUPERVISOR=apple, and a ruling is only recorded when a step actually fails.',
+        // "Nothing here" and "nothing matched your filter" are different
+        // answers, and the first one told a reader the supervisor had never
+        // run on a device holding 111 rulings.
+        b.total
+          ? null
+          : (all.length
+            ? `no ruling in this log belongs to session ${session} — the device has ${all.length}.`
+            : 'Nothing has been judged on this device yet. The supervisor is off unless'
+              + ' SIMFRAME_SUPERVISOR=apple, and a ruling is only recorded when a step actually fails.'),
         ...Object.entries(b.decision_to_outcome)
           .sort((a, c) => c[1] - a[1])
           .map(([k, n]) => `  ${k.padEnd(28)} ${String(n).padStart(4)}`),
@@ -1100,8 +1235,12 @@ async function main() {
               ? ` — ${b.p95_unknown} ruling(s) are on edges with no p95, so they cannot take part in 101's comparison`
               : '')
           : null,
+        session && all.length !== records.length
+          ? `filtered to session ${session}: ${records.length} of ${all.length} ruling(s)`
+          : null,
         b.sessions.length > 1
           ? `WARNING ${b.sessions.length} sessions are pooled here; two agents on one device write one file`
+            + ' — narrow with --session (this process) or --session=<id>'
           : null,
       ].filter((l) => l !== null).join('\n'));
       break;
@@ -1120,10 +1259,29 @@ async function main() {
         ...metrics.REASONS
           .filter((r) => b.by_reason[r])
           .sort((a, c) => b.by_reason[c] - b.by_reason[a])
-          .map((r) => `  ${r.padEnd(20)} ${String(b.by_reason[r]).padStart(4)}   `
-            + (metrics.BUILT_FACULTIES.has(metrics.FACULTY[r])
+          .map((r) => {
+            const n = b.by_reason[r];
+            const read = b.classified_by_reason?.[r] ?? 0;
+            // A faculty is only named for the part of a reason that was read
+            // off the failure. The rest is a count of things nothing could
+            // classify, and naming a phase against it is advice with nothing
+            // behind it — which is how this report came to tell a tester that
+            // their unlabeled-control problem was a timing problem.
+            const assumed = b.assumed_by_reason?.[r] ?? 0;
+            const named = metrics.BUILT_FACULTIES.has(metrics.FACULTY[r])
               ? `not removed by: ${metrics.FACULTY[r]} [built]`
-              : `would be removed by: ${metrics.FACULTY[r]}`)),
+              : `would be removed by: ${metrics.FACULTY[r]}`;
+            let verdict;
+            if (read > 0) {
+              verdict = named + (read < n ? ` (on the ${read} of ${n} whose reason was read)` : '');
+            } else if (assumed > 0) {
+              verdict = 'reason assumed, not read — no faculty can be named from these';
+            } else {
+              // Neither read nor assumed: the log predates the distinction.
+              verdict = `${named} — but these records predate the check, so treat it as untested`;
+            }
+            return `  ${r.padEnd(20)} ${String(n).padStart(4)}   ${verdict}`;
+          }),
         b.total ? '' : null,
         b.total ? `avoidable ${b.avoidable}/${b.total} (${b.avoidable_escalation_rate})` : null,
         // Said out loud rather than left for someone to discover: the rate is
@@ -1497,9 +1655,38 @@ async function doctor({ json = false, strict = false, device, options = {} } = {
       // machine could be doing better and silently is not; a driver someone
       // selected on purpose is neither silent nor a surprise.
       const axState = !ax.available ? 'optional' : ax.name === 'simframed' || ax.chosen ? 'ok' : 'warn';
-      add(`accessibility tree (${d.name})`, axState,
-        ax.available ? `${ax.name}: ${ax.version}` : `unavailable: ${ax.reason}`,
+      // Prove a round trip, not a presence — the same correction this file
+      // already made for the supervisor, never carried across to here.
+      //
+      // A CI run read the screen eighteen times and every single reading came
+      // back `ocr` with no `ax` at all, while this check said `ok` because a
+      // driver was configured. It is configured; it answers with nothing. Six
+      // minutes later the fingerprint step failed with a distribution mystery,
+      // and the layer that had actually died was named nowhere. Asking the tree
+      // for the current screen costs one read (~50ms) and turns that into a
+      // first-minute failure with the right sentence on it.
+      let axCount = null;
+      if (ax.available) {
+        try {
+          axCount = (await input.describeAll(d.udid)).length;
+        } catch {
+          axCount = 0;
+        }
+      }
+      add(`accessibility tree (${d.name})`,
+        // `warn`, not `fail`: a genuinely empty screen exists — a springboard
+        // mid-boot, a black frame — and a hard error on one would cry wolf.
+        // The count is exported so a caller that knows the screen is not empty
+        // can assert on it, which is what CI does.
+        ax.available && axCount === 0 ? 'warn' : axState,
+        ax.available
+          ? `${ax.name}: ${ax.version}`
+            + (axCount === 0
+              ? ' — but it returned NO elements for the current screen, so every read is OCR alone'
+              : axCount != null ? `; ${axCount} element(s) on the current screen` : '')
+          : `unavailable: ${ax.reason}`,
         { key: 'ax.driver', value: ax.name });
+      if (axCount != null) add(null, null, null, { key: 'ax.elements', value: axCount });
     }
     if (probed.length) {
       const t0 = Date.now();
@@ -1526,6 +1713,13 @@ async function doctor({ json = false, strict = false, device, options = {} } = {
       for (const d of probed) {
         const live = api.liveness(d.udid, (await api.getState(d.udid)).state);
         if (live.stalled) add(`capture health (${d.name})`, 'fail', live.note, { key: 'capture.stalled', value: true });
+        // A `warn` rather than a `fail`, because a genuinely inert screen is
+        // possible and this is a contradiction between two numbers rather than
+        // a proven fault. It is still the loudest thing `doctor` can say about
+        // the failure that made a tester report a false application state.
+        else if (live.suspectSurface) {
+          add(`capture surface (${d.name})`, 'warn', live.note, { key: 'capture.suspectSurface', value: true });
+        }
       }
     }
   } catch (err) {
@@ -1566,11 +1760,14 @@ async function doctor({ json = false, strict = false, device, options = {} } = {
       warnings: warned.length,
       optional: optional.length,
       ...flat,
-      checks: checks.map(({ name, level, detail }) => ({ name, level, detail })),
+      checks: checks.filter((c) => c.name).map(({ name, level, detail }) => ({ name, level, detail })),
     }, null, 2));
   } else {
     const mark = { ok: 'ok  ', warn: 'WARN', fail: 'FAIL', optional: '--  ' };
-    for (const c of checks) console.log(`${mark[c.level]} ${c.name.padEnd(24)} ${c.detail}`);
+    // A nameless entry is data for `--json` and not a line for a reader — the
+    // element count belongs beside the layer it describes, not on a row of its
+    // own.
+    for (const c of checks) if (c.name) console.log(`${mark[c.level]} ${c.name.padEnd(24)} ${c.detail}`);
     if (warned.length) {
       console.log(`\n${warned.length} layer(s) degraded. simframe still works, but not at full speed or coverage:`);
       for (const c of warned) console.log(`  - ${c.name}: ${c.detail}`);

package/src/fingerprint.js

@@ -72,8 +72,17 @@ import * as regions from './regions.js';
  *     graph merged them. Both bounds are absolute now. Screens that were
  *     missed at 7 hash differently at 8, and unlike a stale hash that matches
  *     nothing, these matched the *wrong* thing.
+ *
+ * 9 — nothing in this file changed. The element list it is given did: item 122
+ *     stopped dropping accessibility nodes that have no name, so a screen with
+ *     an icon-only control now carries a token for it that it did not carry
+ *     before. That is a better identity — a nav bar with an overflow menu and
+ *     one without are not the same screen — and it is still a different hash
+ *     for the same screen, which is what this number exists to declare. The
+ *     lesson worth keeping is that the rules version is not a version of *this
+ *     file*; it is a version of the token set, and the token set has an input.
  */
-export const TOKEN_RULES_VERSION = 8;
+export const TOKEN_RULES_VERSION = 9;
 
 /** Frames are quantised to this, so sub-pixel drift and a nudged row do not matter. */
 export const GRID = 24;