simframe 0.6.1 → 0.7.0

package/src/cli.js

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { runDaemon, DEFAULTS } from './daemon.js';
-import { bootedDevices, listDevices, resolveDevice } from './simctl.js';
+import { bootedDevices, capabilitiesFor, listDevices, PLATFORMS, resolveDevice, toolchainChecks } from './platform/index.js';
 import * as actions from './actions.js';
 import * as api from './index.js';
 import * as input from './input.js';
@@ -51,8 +51,8 @@ Options
   --json                 machine-readable output — on every command
   --out=<file>           output path for frame/strip/recall
   --detail=low|normal|high|full   or --detail=<max pixels>
-  --engine=simframed|simctl   capture engine (default simframed)
-  --fps=<n>              capture rate while the screen is moving (simctl engine only)
+  --engine=simframed|screenshot  capture engine (default: the fastest the device has)
+  --fps=<n>              capture rate while the screen is moving (screenshot engine only)
   --count=<n>            frames in a strip (default 5)
   --since=<hash|seq>     compare against this frame (see: simframe mark)
   --mode=settle|change|stable   what wait waits for (default settle)
@@ -177,18 +177,21 @@ async function main() {
     case 'start': {
       const { device: dev, state, started } = await api.ensureDaemon(device, options);
       const engineModule = await import('./engine.js');
-      const running = engineModule.runningEngine(dev.udid) ?? 'simctl';
+      const best = capabilitiesFor(dev.udid).captureEngines[0];
+      const running = engineModule.runningEngine(dev.udid) ?? best;
       console.log(
         `${started ? 'started' : 'already running'} — ${dev.name} (${dev.runtime}) ` +
           `engine=${running} frame #${state.seq} ${state.width}x${state.height}`,
       );
       // Say which engine, and if it is the slow one, say why. A downgrade that
-      // prints nothing is how this shipped broken twice.
-      if (running !== 'simframed') {
+      // prints nothing is how this shipped broken twice. But it is only a
+      // downgrade if this platform has something better: the screenshot loop is
+      // the whole of Android's capture, not a fallback from anything.
+      if (running !== best) {
         const why = api.fallbackReason(dev.udid);
         console.log(
-          `WARN engine=simctl — roughly 30x slower per frame. ` +
-            (why ? `simframed unavailable: ${why}` : 'reason unrecorded; run simframe doctor'),
+          `WARN engine=${running} — roughly 30x slower per frame than ${best}. ` +
+            (why ? `${best} unavailable: ${why}` : 'reason unrecorded; run simframe doctor'),
         );
         if (Boolean(flags.strict) || process.env.SIMFRAME_STRICT === '1') {
           console.error('--strict: refusing to run on a degraded engine');
@@ -697,7 +700,7 @@ async function main() {
       if (flags.json) {
         console.log(JSON.stringify(shown, null, 2));
       } else if (!shown.length) {
-        console.log('no booted simulators (pass --all to list every device)');
+        console.log('no booted devices (pass --all to list every device)');
       } else {
         for (const d of shown) console.log(`${d.state === 'Booted' ? '●' : '○'} ${d.name}  ${d.runtime}  ${d.udid}`);
       }
@@ -748,11 +751,10 @@ async function doctor({ json = false, strict = false, device } = {}) {
 
   add('node', 'ok', process.version);
   const { execFileSync } = await import('node:child_process');
-  try {
-    add('xcrun', 'ok', execFileSync('xcrun', ['--version'], { encoding: 'utf8' }).trim().split('\n')[0]);
-  } catch (err) {
-    add('xcrun', 'fail', err.message);
-  }
+  // The active backend names its own prerequisites — doctor renders them and
+  // does not know what they are. On iOS that is xcrun; on Android it will be
+  // adb, and this line will not change.
+  for (const check of toolchainChecks()) add(check.name, check.level, check.detail);
   try {
     execFileSync('sips', ['--version'], { encoding: 'utf8', stdio: 'pipe' });
     add('sips', 'ok', 'available');
@@ -798,11 +800,21 @@ async function doctor({ json = false, strict = false, device } = {}) {
       const wanted = await resolveDevice(device);
       booted = booted.filter((d) => d.udid === wanted.udid);
     }
-    add('booted simulator', booted.length ? 'ok' : 'warn',
+    // `deviceNoun` earns its place here: one platform's devices are called by
+    // its own word, and a mixed set by the neutral one. An emulator reported as
+    // a "booted simulator" is the same small lie as an emulator reported as
+    // having an idb input driver.
+    const nouns = [...new Set(booted.map((d) => capabilitiesFor(d.udid) && PLATFORMS[d.platform].deviceNoun))];
+    add(`booted ${nouns.length === 1 ? nouns[0] : 'device'}`, booted.length ? 'ok' : 'warn',
       booted.map((d) => `${d.name} (${d.runtime})`).join(', ') || 'none');
     for (const d of booted) {
       const input = await import('./input.js');
       const control = await import('./control.js');
+      // What this device's platform can do at all. Without asking, doctor
+      // described an Android emulator in iOS terms — "input driver: idb" about
+      // a tool that has never spoken to one.
+      const caps = capabilitiesFor(d.udid);
+      const bestEngine = caps.captureEngines[0];
       // Start the engine before asking which engine is in use. Reading it first
       // reports `simctl` on any machine where nothing happens to be running
       // yet — a warning about a downgrade that has not occurred, and one that
@@ -813,27 +825,43 @@ async function doctor({ json = false, strict = false, device } = {}) {
       // ensureDaemon waits for a frame; the control socket comes up a moment
       // later. Asking immediately reports `idb` for a device whose own input
       // path is seconds from ready — a race that would read as CI flake.
-      for (let i = 0; i < 40 && !control.available(d.udid); i += 1) {
+      for (let i = 0; i < 40 && caps.input.supported && !control.available(d.udid); i += 1) {
         await new Promise((r) => setTimeout(r, 50));
       }
-      const driver = await input.driverFor(d.udid, { refresh: true });
+      const driver = caps.input.supported ? await input.driverFor(d.udid, { refresh: true }) : null;
       // Which engine is actually capturing, from the daemon's own record.
       // `control.available` answers a different question — whether the input
       // socket is up — and using it here reported simctl on a machine that was
       // capturing with simframed perfectly well.
-      const captureEngine = engineModule.runningEngine(d.udid) ?? 'simctl';
+      const captureEngine = engineModule.runningEngine(d.udid) ?? bestEngine;
       const daemon = captureEngine === 'simframed';
-      const why = captureEngine === 'simctl' ? api.fallbackReason(d.udid) : null;
-      add(`capture engine (${d.name})`, captureEngine === 'simframed' ? 'ok' : 'warn',
-        captureEngine === 'simframed'
-          ? 'simframed'
-          : `simctl — roughly 30x slower per frame${why ? `; simframed unavailable: ${why}` : '. Run simframe start to see why'}`,
+      const why = captureEngine === bestEngine ? null : api.fallbackReason(d.udid);
+      add(`capture engine (${d.name})`, captureEngine === bestEngine ? 'ok' : 'warn',
+        captureEngine === bestEngine
+          ? captureEngine
+          : `${captureEngine} — roughly 30x slower per frame than ${bestEngine}${why ? `; ${bestEngine} unavailable: ${why}` : '. Run simframe start to see why'}`,
         { key: 'capture.engine', value: captureEngine });
-      add(`input driver (${d.name})`, driver.available ? (driver.name === 'simframed' ? 'ok' : 'warn') : 'warn',
-        driver.available ? `${driver.name}: ${driver.version}` : driver.reason,
-        { key: 'input.driver', value: driver.available ? driver.name : null });
+      // A layer this platform does not have yet is `optional`, the level that
+      // means "documented as absent" rather than "this machine is degraded".
+      if (!caps.input.supported) {
+        add(`input driver (${d.name})`, 'optional', caps.input.note, { key: 'input.driver', value: null });
+      } else {
+        // `warn` means this machine could be doing better and silently is not —
+        // which is true of idb on a simulator and false of the platform's own
+        // driver. The console is not a downgrade on Android; it is the only
+        // input path there is, and grading it a downgrade made `--strict` fail
+        // on a device that was working perfectly.
+        const best = driver.name === 'simframed' || driver.name === caps.input.via;
+        add(`input driver (${d.name})`, driver.available ? (best ? 'ok' : 'warn') : 'warn',
+          driver.available ? `${driver.name}: ${driver.version}` : driver.reason,
+          { key: 'input.driver', value: driver.available ? driver.name : null });
+      }
       add(`text recognition (${d.name})`, 'ok',
         daemon ? 'simframed (in-process, off the framebuffer)' : 'sips + helper binary');
+      if (!caps.ax.supported) {
+        add(`accessibility tree (${d.name})`, 'optional', caps.ax.note, { key: 'ax.driver', value: null });
+        continue;
+      }
       const ax = await input.axDriverFor(d.udid);
       // idb here is a downgrade unless it was asked for. `warn` means this
       // machine could be doing better and silently is not; a driver someone
@@ -849,6 +877,14 @@ async function doctor({ json = false, strict = false, device } = {}) {
       add('capture', 'ok',
         `frame #${res.state.seq} ${res.width}x${res.height} in ${Date.now() - t0}ms (age ${res.ageMs}ms)`,
         { key: 'capture.frames', value: res.state.seq });
+      // A wedged device produces the same nothing as a quiet one, so doctor has
+      // to ask the capture loop rather than look at the frames. `fail`, not
+      // `warn`: nothing here is degraded-but-working, and the cure is a device
+      // restart that simframe deliberately does not perform.
+      for (const d of booted) {
+        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 });
+      }
     }
   } catch (err) {
     add('capture', 'fail', err.message);

package/src/daemon.js

@@ -12,7 +12,7 @@ import {
   signatureToHex,
 } from './analyze.js';
 import * as store from './store.js';
-import { isBootedSync, resize, screenshot } from './simctl.js';
+import { isBootedSync, resize, screenshot } from './platform/index.js';
 
 // Bump whenever the shape of state.json changes, so an upgraded client retires
 // a capture loop left running by an older install instead of misreading it.
@@ -25,6 +25,18 @@ import { isBootedSync, resize, screenshot } from './simctl.js';
 // through a flow. A unit test asserts these two constants match.
 export const STATE_VERSION = 6;
 
+/**
+ * How many failed captures in a row mean this loop is wedged rather than
+ * unlucky.
+ *
+ * Four, against the ten that make it give up: far enough in that a single
+ * hiccup does not raise an alarm, early enough that a reader learns about it
+ * while the loop is still trying. The Swift daemon reaches the same conclusion
+ * differently — it counts re-resolves of the display port, because there a
+ * successful re-resolve resets the failure count and hides the loop.
+ */
+export const STALLED_AFTER_ERRORS = 4;
+
 export const DEFAULTS = {
   fps: 4,
   idleFps: 1.5,
@@ -85,6 +97,7 @@ export async function runDaemon(device, options = {}) {
   let ringIndex = [];
   let lastChangeAt = Date.now();
   let consecutiveErrors = 0;
+  let stalledSince = null;
   let lastBootCheck = Date.now();
   let running = true;
   const stop = () => {
@@ -141,6 +154,10 @@ export async function runDaemon(device, options = {}) {
 
       seq = nextSeq;
       prevSignature = signature;
+      if (consecutiveErrors >= STALLED_AFTER_ERRORS) {
+        log('capture recovered on its own');
+        store.writeCaptureHealth(udid, null);
+      }
       consecutiveErrors = 0;
 
       const hash = frameHash(bmp);
@@ -199,7 +216,25 @@ export async function runDaemon(device, options = {}) {
     } catch (err) {
       consecutiveErrors++;
       log(`capture error (${consecutiveErrors}): ${err.message}`);
+      // Say that capture is wedged rather than merely slow, and do nothing
+      // about it: the cure is a device restart, and that is the user's to make.
+      // Published rather than only logged, because a reader of `state` sees the
+      // last healthy frame with nothing in it to say the device stopped
+      // answering — the same frames a merely idle screen produces.
+      if (consecutiveErrors >= STALLED_AFTER_ERRORS) {
+        stalledSince ??= Date.now();
+        store.writeCaptureHealth(udid, {
+          stalled: true,
+          since: stalledSince,
+          at: Date.now(),
+          consecutiveFailures: consecutiveErrors,
+          reattaches: 0,
+          reason: err.message,
+        });
+      }
       if (consecutiveErrors >= 10) {
+        // Left published on purpose. The file is how a reader learns why this
+        // loop is not running any more.
         log('exit: too many consecutive capture errors');
         break;
       }

package/src/engine.js

@@ -1,10 +1,16 @@
 // Chooses and starts the capture engine.
 //
 // Two exist: `simframed`, a Swift daemon that reads the framebuffer directly,
-// and `simctl`, the original loop that shells out for each screenshot. The
-// daemon is the default because it is roughly thirty times faster, but the old
-// loop stays reachable — a machine without a Swift toolchain, or an Xcode
-// version where a private symbol has moved, still needs to work.
+// and `screenshot`, the loop that asks the platform boundary for one frame at a
+// time. The daemon is the default on iOS because it is roughly thirty times
+// faster, but the loop stays reachable — a machine without a Swift toolchain,
+// or an Xcode version where a private symbol has moved, still needs to work.
+//
+// The loop used to be called `simctl`, after the tool it shelled out to. It no
+// longer shells out to anything in particular: on Android the same loop reaches
+// the emulator console and captures a frame in ~41 ms, which is not `simctl` by
+// any reading. `simctl` stays accepted as an alias, because it is in shipped
+// meta.json files, in documentation and in people's shell history.
 import { execFile, spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -17,7 +23,14 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE = path.join(HERE, '..', 'native', 'simframed');
 const BINARY = path.join(PACKAGE, '.build', 'release', 'simframed');
 
-export const ENGINES = ['simframed', 'simctl'];
+export const ENGINES = ['simframed', 'screenshot'];
+
+/** `simctl` was this engine's name until it ran on a second platform. */
+const ENGINE_ALIASES = { simctl: 'screenshot' };
+
+export function normalizeEngine(name) {
+  return ENGINE_ALIASES[name] ?? name;
+}
 
 export function binaryPath() {
   return BINARY;
@@ -95,5 +108,5 @@ export function spawnDaemon(udid, { maxDim, minIntervalMs, idleExitMs } = {}) {
 export function runningEngine(udid) {
   const meta = store.readJson(path.join(store.deviceDir(udid), 'meta.json'));
   if (!meta || !store.isProcessAlive(meta.pid)) return null;
-  return meta.options?.engine === 'simframed' ? 'simframed' : 'simctl';
+  return meta.options?.engine === 'simframed' ? 'simframed' : 'screenshot';
 }

package/src/fingerprint.js

@@ -11,6 +11,22 @@
 import crypto from 'node:crypto';
 import * as regions from './regions.js';
 
+/**
+ * Bumped whenever the token rules change, and read by `graph.FINGERPRINT_VERSION`
+ * and `screenmap.MAP_VERSION` so stored hashes are discarded rather than
+ * compared against hashes computed by different rules. An old hash is a
+ * perfectly well-formed hash that never matches anything, which is the quietest
+ * kind of wrong.
+ *
+ * 2 — elements with no visible footprint, and containers holding two or more
+ *     others, no longer enter identity: only one sensor can see either.
+ * 3 — a chrome label must be a name: at least two letters, and not a URL. A
+ *     browser's address bar put "== example.com" into a screen's identity, so
+ *     a different page read as a different screen, and OCR's ":" and "+" read
+ *     off icons were identities of their own.
+ */
+export const TOKEN_RULES_VERSION = 3;
+
 /** Frames are quantised to this, so sub-pixel drift and a nudged row do not matter. */
 export const GRID = 24;
 
@@ -85,12 +101,36 @@ const MONTHS = /\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\b/i;
 const WEEKDAYS = /\b(mon|tue|wed|thu|fri|sat|sun)[a-z]*day?\b/i;
 const DATE_LIKE = /\d{1,4}[/.-]\d{1,2}([/.-]\d{1,4})?|\b\d{1,2}:\d{2}\b/;
 
+/**
+ * A URL is the most volatile thing a nav bar can hold.
+ *
+ * Measured on Android, where a browser's address bar is chrome by every
+ * structural test there is: the screen's identity contained `"== example.com"`,
+ * so the same browser on a different page was a different screen, and every
+ * route through it broke on navigation. The `==` is OCR reading the lock icon.
+ *
+ * Matched after stripping the punctuation OCR decorates it with, and only when
+ * the whole label is the address — a sentence that happens to mention a domain
+ * is still a sentence.
+ */
+const URL_LIKE = /^(https?:\/\/|www\.)|^[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)*\.[a-z]{2,}(\/\S*)?$/i;
+
+/** How many letters a name has to have. One is a glyph, not a name. */
+const NAME_MIN_LETTERS = 2;
+
 export function isVolatileLabel(label) {
   const text = String(label ?? '').trim();
   if (!text) return true;
   if (MONTHS.test(text) || WEEKDAYS.test(text) || DATE_LIKE.test(text)) return true;
+  // Strip what OCR hangs off an icon before asking whether the rest is an
+  // address: the observed label was `== example.com`.
+  const bare = text.replace(/^[^\p{L}\p{N}]+/u, '').replace(/[^\p{L}\p{N}/]+$/u, '');
+  if (URL_LIKE.test(bare)) return true;
   const letters = (text.match(/\p{L}/gu) ?? []).length;
   const digits = (text.match(/\p{N}/gu) ?? []).length;
+  // A label with no word in it is not a name for anything. OCR reads `:`, `+`,
+  // `...` and `—` off icons, and each of those became an identity of its own.
+  if (letters < NAME_MIN_LETTERS) return true;
   // Mostly digits: a count, a price, a phone number, an ID. "1020" and
   // "+1 (111) 111-1111" are both this; "Assets" is not.
   return digits > 0 && digits >= letters;
@@ -108,13 +148,31 @@ export function tokens(targets, screen) {
   const keyboardTop = regions.detectKeyboardTop(targets, screen);
   const groups = new Map();
 
+  // Identity is what the screen *is*, not which sensor happened to see it, so
+  // two things that only one sensor can produce must not enter it: an element
+  // with no visible footprint, and a container that exists to hold others.
+  // Pixels cannot see either, and the accessibility tree reports both.
+  const encloses = (frame) => targets.filter((o) => {
+    const f = o.frame;
+    if (!f || f === frame) return false;
+    const cx = f.x + (f.width ?? 0) / 2;
+    const cy = f.y + (f.height ?? 0) / 2;
+    return cx > frame.x && cx < frame.x + (frame.width ?? 0)
+      && cy > frame.y && cy < frame.y + (frame.height ?? 0);
+  }).length;
+
   for (const t of targets) {
     const frame = t.frame ?? { x: t.x, y: t.y, width: 0, height: 0 };
     // Off-screen elements are not part of what this screen looks like.
     if (frame.y + (frame.height ?? 0) <= 0 || frame.y >= screen.height) continue;
+    // Nor is anything with no footprint to be seen.
+    if (!(frame.width > 0) || !(frame.height > 0)) continue;
     const region = t.region ?? regions.regionFor(frame, screen, { keyboardTop });
     if (region === 'status-bar') continue;
     if (keyboardTop != null && frame.y >= keyboardTop) continue;
+    // A thing that holds two or more other things is scenery, and only the
+    // tree can see it. Its children are already in the fingerprint.
+    if (/group|other|generic/i.test(String(t.type ?? '')) && encloses(frame) >= 2) continue;
 
     const role = roleOf(t);
     // Group by what a thing IS and how big it is, not where it is. Repeated

package/src/graph.js

@@ -7,11 +7,28 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { hashDistance } from './analyze.js';
+import { informative } from './refs.js';
 import * as fingerprint from './fingerprint.js';
 import * as matching from './matching.js';
 import * as store from './store.js';
 
-const GRAPH_VERSION = 2;
+const GRAPH_VERSION = 3;
+
+/**
+ * Which fingerprint produced the hashes in these files.
+ *
+ * Separate from `GRAPH_VERSION` because it answers a different question: not
+ * "is this file shaped the way I expect" but "were these hashes computed by the
+ * same rules I am about to compare them with". A stored graph whose hashes came
+ * from an older fingerprint is not stale, it is *incomparable* — and the failure
+ * is silent, because an old hash is a perfectly well-formed hash that simply
+ * never matches anything.
+ *
+ * On a mismatch the graph is discarded and rebuilt, never translated. A rebuild
+ * costs a few hundred milliseconds per screen and happens once. A mis-merged
+ * graph costs a wrong tap, and costs it for as long as the file survives.
+ */
+export const FINGERPRINT_VERSION = fingerprint.TOKEN_RULES_VERSION;
 /**
  * Screens are matched by structural hash, exactly, and then by how alike their
  * token sets are — which tolerates one optional element appearing (a badge, a
@@ -38,6 +55,14 @@ const GRAPH_VERSION = 2;
  * Most revisits match on a hash outright and never reach this at all.
  */
 export const SIMILARITY_THRESHOLD = 0.36;
+
+/**
+ * How many of the 288 layout bits may differ and still be the same arrangement
+ * of light. The same number `screenmap` recalls maps by, and for the same
+ * reason: measured, a revisit is usually identical and different screens sit at
+ * 74 and above, so 20 is well inside the gap.
+ */
+export const SAME_SCREEN_LAYOUT_BITS = 20;
 /**
  * A screen with three async sections has a few settled structures, not endless
  * ones. Capping this keeps a genuinely wrong merge bounded: if a node starts
@@ -105,11 +130,28 @@ function fingerprintsOf(node) {
 function load(udid, screen) {
   const key = typeof screen === 'string' ? { hash: screen, tokens: [] } : screen;
   const entry = store.readJson(path.join(graphDir(udid), `${key.hash}.json`));
-  if (entry?.version === GRAPH_VERSION) return entry;
+  if (entry?.version === GRAPH_VERSION && entry?.fingerprintVersion === FINGERPRINT_VERSION) return entry;
   // The hash may be a variant of a node filed under a different name.
   const byVariant = allNodes(udid).find((n) => (n.variants ?? []).some((v) => v.hash === key.hash));
   if (byVariant) return byVariant;
-  return { version: GRAPH_VERSION, hash: key.hash, tokens: key.tokens ?? [], variants: [], edges: [] };
+  return {
+    version: GRAPH_VERSION,
+    fingerprintVersion: FINGERPRINT_VERSION,
+    hash: key.hash,
+    tokens: key.tokens ?? [],
+    // What the pixels looked like here. Kept because it is the evidence that
+    // two structurally different readings are the same screen — see `record`.
+    layoutHash: key.layoutHash ?? null,
+    variants: [],
+    edges: [],
+  };
+}
+
+/** Keep the pixel baseline current for a screen we are standing on. */
+function noteLayout(node, reading) {
+  const now = typeof reading === 'string' ? null : reading?.layoutHash;
+  if (now && informative(now)) node.layoutHash = now;
+  return node;
 }
 
 function save(udid, node) {
@@ -124,7 +166,7 @@ export function allNodes(udid) {
       .readdirSync(graphDir(udid))
       .filter((f) => f.endsWith('.json'))
       .map((f) => store.readJson(path.join(graphDir(udid), f)))
-      .filter((n) => n?.version === GRAPH_VERSION);
+      .filter((n) => n?.version === GRAPH_VERSION && n?.fingerprintVersion === FINGERPRINT_VERSION);
   } catch {
     return [];
   }
@@ -243,6 +285,10 @@ export function record(udid, { from, action, to, kind }) {
   // arrive as — that is what variants are for, and rewriting it here would let
   // a node drift screen by screen into something it never was.
   if (!node.tokens?.length && fromKey.tokens?.length) node.tokens = fromKey.tokens;
+  // The pixel baseline, on the other hand, *should* track: it is the evidence
+  // for "same arrangement of light as last time I stood here", and a stale one
+  // answers a question about a screen as it was weeks ago.
+  noteLayout(node, fromKey);
   const to_ = toHash;
   const signature = actionSignature(action);
   const existing = node.edges.find((e) => e.action === signature);
@@ -272,9 +318,28 @@ export function record(udid, { from, action, to, kind }) {
       // So the reading has to positively look like the target before it is
       // called a face of it. Unclaimed is a necessary condition, not a
       // sufficient one.
-      const looksLikeTarget = resembles(target, reading);
+      // Two kinds of positive evidence that this reading is a face of the
+      // target, and either will do. What will not do is "nothing else claims
+      // it", which is an absence of evidence and used to be the whole test.
+      //
+      //  * It looks like the target — the tokens overlap enough to be the same
+      //    screen by the same measure used everywhere else.
+      //  * It *looks like* the target on screen. The pixels are within the
+      //    same-screen band of what was seen here before, and we arrived
+      //    through an edge that has led here. Identity belongs to the graph as
+      //    much as to the hash: the transition is evidence the fingerprint
+      //    cannot supply, and it is exactly the evidence needed when one
+      //    perception layer answered this time and not last time.
+      //
+      // That second route is what carries a screen whose structure genuinely
+      // differs between reads. Measured on four device-native screens, the
+      // accessibility tree and OCR agree on only 0.33–0.47 of a screen's
+      // tokens and never on its hash, and coarsening the vocabulary barely
+      // moved it — so this is not a residual case, it is the common one.
+      const looksLikeTarget = resembles(target, reading) || pixelsAgree(target, reading);
       if (unclaimed && looksLikeTarget && target.hash !== to_ && reading.tokens?.length) {
         addVariant(target, reading);
+        noteLayout(target, reading);
         save(udid, target);
         existing.count += 1;
         existing.lastSeen = Date.now();
@@ -306,6 +371,25 @@ export function record(udid, { from, action, to, kind }) {
 }
 
 /** What this action did last time, if we have ever seen it here. */
+/**
+ * Do the pixels say this is the same screen we have stood on here before?
+ *
+ * The layout hash is a poor answer to "which screen is this" on its own — that
+ * is why identity is structural — but it is a good answer to "is this the same
+ * arrangement of light", and combined with having arrived through a known edge
+ * it is the evidence that two structurally different readings are one screen.
+ *
+ * Guarded by `informative`, because a dark or uniform screen hashes to almost
+ * nothing and two of those are within any tolerance of each other while being
+ * evidence of nothing at all.
+ */
+function pixelsAgree(node, reading) {
+  const before = node?.layoutHash;
+  const now = reading?.layoutHash;
+  if (!before || !now || !informative(before) || !informative(now)) return false;
+  return hashDistance(before, now) <= SAME_SCREEN_LAYOUT_BITS;
+}
+
 /**
  * Does this reading look like a face of this screen, rather than a different
  * screen we happen not to have stored yet?