simframe 0.12.2 → 0.14.0

package/src/cli.js

@@ -12,6 +12,7 @@ import * as baseline from './baseline.js';
 import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
 import { decodePng } from './png.js';
+import * as storage from './storage.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
@@ -33,6 +34,7 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe tap     <selector>        tap #3, "Save", or @120,400
   simframe do      <script.json>     run a scripted flow (see below)
   simframe screens [device]          list screens this device has learned
+  simframe storage [bundle-id]       what the app saved (works on a shut-down device)
   simframe goto    <screen>          walk to a known screen through known steps
   simframe flow    save <name> <script.json>   run a flow and save it if every step verifies
   simframe flow    run  <name>       replay a saved flow
@@ -467,6 +469,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);
@@ -491,7 +564,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}`);
@@ -546,20 +621,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;
@@ -712,7 +803,7 @@ async function main() {
         },
         [
           ...res.results.map(stepLine),
-          `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps in ${res.totalMs}ms`,
+          actions.flowSummary(res),
           saved && (saved.ok ? `saved flow "${saved.name}" — ${saved.steps} steps` : `not saved: ${saved.reason}`),
           map && `\n${map}`,
         ],
@@ -771,6 +862,25 @@ async function main() {
       return;
     }
 
+    case 'storage': {
+      // A file read, like `screens`, and deliberately not a daemon call. The
+      // whole value of this command is that it answers on a device that is not
+      // running — measured: simctl itself cannot, on this Xcode. Routing it
+      // through the daemon would throw that away for no gain.
+      const device = await resolveDevice(flags.device);
+      const [bundleId] = positional;
+      if (!bundleId) {
+        const list = await storage.apps(device.udid);
+        const match = flags.match ? String(flags.match).toLowerCase() : null;
+        const shown = match ? list.filter((a) => a.bundleId.toLowerCase().includes(match)) : list;
+        emit(flags, shown, storage.formatApps(shown));
+        return;
+      }
+      const result = await storage.read(device.udid, bundleId);
+      emit(flags, result, storage.format(result));
+      return;
+    }
+
     case 'screens': {
       // Reading what this device has learned is a file read. It used to go
       // through ensureDaemon, so a device whose capture had stopped could not
@@ -831,7 +941,7 @@ async function main() {
         }
         emit(flags, res, [
           ...(res.results ?? []).map(stepLine),
-          `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps`,
+          actions.flowSummary(res, { withTime: false }),
         ]);
         process.exitCode = res.ok ? 0 : 1;
         return;
@@ -1106,13 +1216,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)}`),
@@ -1128,8 +1256,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;
@@ -1148,10 +1280,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
@@ -1525,9 +1676,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();
@@ -1554,6 +1734,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) {
@@ -1594,11 +1781,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;

package/src/graph.js

@@ -396,7 +396,18 @@ export function describe(node) {
   if (tabs.length) return tabs.slice(0, 3).join(' / ');
   const anyChrome = labels(/:(nav-bar|tab-bar):/);
   if (anyChrome.length) return anyChrome.slice(0, 3).join(' ');
-  return node.hash.slice(0, 8);
+  // No name. Say so, rather than handing back a hash dressed as one.
+  //
+  // This fell back to `node.hash.slice(0, 8)`, and the map prints the name in
+  // quotes after the identity hash — so an unnamed screen read
+  // `screen 299dd147 "a9505378"`: two hashes, one of them looking like a title,
+  // beside the `screen 089bec77 "time sheets"` a named screen produces.
+  // Reported from the field, with the right fix attached: omit the quoted part
+  // rather than echo a second hash.
+  //
+  // Callers that need *something* to print in a list supply their own fallback,
+  // which is a decision about presentation and belongs at the point of display.
+  return null;
 }
 
 /** Find a known screen by what a human would call it. */
@@ -404,7 +415,9 @@ export function findScreen(udid, query) {
   const wanted = String(query ?? '').trim();
   if (!wanted) return null;
   const scored = allNodes(udid)
-    .map((node) => ({ node, name: describe(node) }))
+    // The short hash stays searchable: `goto 089bec77` worked before `describe`
+    // stopped inventing names and must keep working.
+    .map((node) => ({ node, name: describe(node) ?? node.hash.slice(0, 8) }))
     .map((c) => ({ ...c, score: matching.nameScore(c.name, wanted) }))
     .filter((c) => c.score > 0)
     .sort((a, b) => b.score - a.score);