simframe 0.14.1 → 0.14.3

package/native/simframed/Sources/PrivateAPI/AccessibilityBridge.swift

@@ -16,11 +16,20 @@ public struct AXNode: Sendable {
     public var selected: Bool?
     public var focused: Bool?
     public var frame: CGRect
+    /// Where the control actuates, when the app says so.
+    ///
+    /// Not the same as the centre of `frame`, and a switch is the proof: UIKit
+    /// publishes a row-wide frame for it, so the geometric centre is the label
+    /// and iOS does not actuate a switch from there. Measured — tapping the
+    /// centre flipped it 0 of 3 times and the control itself 3 of 3. UIKit has
+    /// `accessibilityActivationPoint` for exactly this question, and nil means
+    /// the app did not answer it, never a guess of ours.
+    public var activationPoint: CGPoint?
     public var depth: Int
 
     public init(role: String, subrole: String? = nil, label: String? = nil, value: String? = nil,
                 identifier: String? = nil, enabled: Bool? = nil, selected: Bool? = nil,
-                focused: Bool? = nil, frame: CGRect, depth: Int) {
+                focused: Bool? = nil, frame: CGRect, activationPoint: CGPoint? = nil, depth: Int) {
         self.role = role
         self.subrole = subrole
         self.label = label
@@ -30,6 +39,7 @@ public struct AXNode: Sendable {
         self.selected = selected
         self.focused = focused
         self.frame = frame
+        self.activationPoint = activationPoint
         self.depth = depth
     }
 }
@@ -251,7 +261,8 @@ public final class AccessibilityBridge {
 
     /// Everything scalar about a node, asked for in one go.
     private static let batched = ["AXRole", "AXSubrole", "AXDescription", "AXValue",
-                                  "AXIdentifier", "AXEnabled", "AXSelected", "AXFocused"]
+                                  "AXIdentifier", "AXEnabled", "AXSelected", "AXFocused",
+                                  "AXActivationPoint"]
 
     private func node(from element: NSObject, depth: Int) -> AXNode {
         // One bridge round trip for eight attributes, not eight.
@@ -283,6 +294,7 @@ public final class AccessibilityBridge {
             selected: (value("AXSelected") as? NSNumber)?.boolValue,
             focused: (value("AXFocused") as? NSNumber)?.boolValue,
             frame: frame(of: element),
+            activationPoint: point(value("AXActivationPoint")) ?? activationPoint(of: element),
             depth: depth)
     }
 
@@ -310,6 +322,41 @@ public final class AccessibilityBridge {
         return unsafeBitCast(imp, to: RectFn.self)(element, sel)
     }
 
+    /// The activation point as the attribute bag reports it.
+    ///
+    /// Defensive about the shape because this is a private bridge and the
+    /// answer arrives as whatever the translator chose: an NSValue wrapping a
+    /// CGPoint on one path, a stringified `{x, y}` on another. Anything it does
+    /// not recognise is nil, which costs nothing — the caller falls back to the
+    /// frame centre, which is what it did before this attribute was asked for.
+    private func point(_ value: Any?) -> CGPoint? {
+        switch value {
+        case let v as NSValue:
+            // `pointValue`, not `cgPointValue`: this daemon is a macOS binary
+            // driving a guest, and the iOS-only accessor does not exist here.
+            // NSPoint and CGPoint are the same type on 64-bit.
+            let p = v.pointValue
+            return p.x.isFinite && p.y.isFinite ? p : nil
+        case let s as String:
+            let parts = s.trimmingCharacters(in: CharacterSet(charactersIn: "{} "))
+                .split(separator: ",")
+                .compactMap { Double($0.trimmingCharacters(in: .whitespaces)) }
+            guard parts.count == 2 else { return nil }
+            return CGPoint(x: parts[0], y: parts[1])
+        default:
+            return nil
+        }
+    }
+
+    /// The direct selector, for elements that answer it but do not batch it.
+    private func activationPoint(of element: NSObject) -> CGPoint? {
+        let sel = NSSelectorFromString("accessibilityActivationPoint")
+        guard element.responds(to: sel), let imp = element.method(for: sel) else { return nil }
+        typealias PointFn = @convention(c) (AnyObject, Selector) -> CGPoint
+        let p = unsafeBitCast(imp, to: PointFn.self)(element, sel)
+        return p.x.isFinite && p.y.isFinite ? p : nil
+    }
+
     /// A value may be a string, a number, or something with no useful text.
     private func string(_ value: Any?) -> String? {
         switch value {

package/native/simframed/Sources/SimframeCore/Element.swift

@@ -60,10 +60,20 @@ public struct Element: Sendable {
     public var state: ElementState
     public var source: ElementSource
     public var confidence: Double
+    /// Where the control actuates, when the app publishes it.
+    ///
+    /// Deliberately NOT folded into `center`. `center` is the element's place,
+    /// and two readings of one control are matched by how close their places
+    /// are — 12pt apart, per `SAME_CONTROL_POINTS` above the boundary. A switch
+    /// actuates at the far end of a row-wide frame, so making `center` mean
+    /// "where to tap" would move the tree's reading ~145pt away from OCR's and
+    /// stop the two collapsing into one control. Aiming and identity are
+    /// different questions; this is the answer to the first one only.
+    public var activationPoint: CGPoint?
 
     public init(id: Int, frame: CGRect, role: String, label: String? = nil, value: String? = nil,
                 identifier: String? = nil, state: ElementState = ElementState(),
-                source: ElementSource, confidence: Double = 1) {
+                source: ElementSource, confidence: Double = 1, activationPoint: CGPoint? = nil) {
         self.id = id
         self.frame = frame
         self.role = role
@@ -73,6 +83,7 @@ public struct Element: Sendable {
         self.state = state
         self.source = source
         self.confidence = confidence
+        self.activationPoint = activationPoint
     }
 
     public var center: CGPoint { CGPoint(x: frame.midX, y: frame.midY) }
@@ -89,6 +100,11 @@ public struct Element: Sendable {
         if let label { out["label"] = label }
         if let value { out["value"] = value }
         if let identifier { out["identifier"] = identifier }
+        // Only when the app answered. Absent means "no opinion", and the layer
+        // above then aims at the centre exactly as it always has.
+        if let activationPoint {
+            out["activationPoint"] = ["x": Int(activationPoint.x.rounded()), "y": Int(activationPoint.y.rounded())]
+        }
         let state = state.json
         if !state.isEmpty { out["state"] = state }
         return out
@@ -112,7 +128,8 @@ public extension Element {
             state: ElementState(enabled: node.enabled, selected: node.selected,
                                 checked: nil, focused: node.focused),
             source: .accessibility,
-            confidence: 1)
+            confidence: 1,
+            activationPoint: node.activationPoint)
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/analyse-escalations.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Of the `verification_failed` escalations, how many happened on a
+ * `(screen, action)` the graph had already seen behave consistently?
+ * EXPERIMENTS §17. The answer was 3% and 0%, which is why this is kept: it is
+ * the measurement that stopped a phase being spent on remembering edge
+ * outcomes.
+ *
+ * Two thirds of those escalations are `no-visible-change`, and 83-100% of them
+ * are on a screen or an action the graph has never seen — memory cannot answer
+ * a question about a place it has never been.
+ *
+ * The graph is read as it is NOW, so an edge matched here may have been learned
+ * after the escalation. That makes the "addressable" figure an upper bound, and
+ * it is already near zero.
+ *
+ * Aggregate by design, and stricter than it looks: `detail` is app content, so
+ * verdicts are classified against a CLOSED vocabulary and the raw string is
+ * never printed. The first version of this printed the prefix and put a
+ * client's screen labels and a customer email into a terminal.
+ *
+ * Usage: node scripts/analyse-escalations.mjs <udid-prefix> [<udid-prefix>...] */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const root = process.env.SIMFRAME_HOME || path.join(os.homedir(), '.simframe');
+
+for (const dev of process.argv.slice(2)) {
+  const dir = fs.readdirSync(root).find((d) => d.startsWith(dev));
+  if (!dir) continue;
+  const base = path.join(root, dir);
+  const gdir = path.join(base, 'graph');
+  if (!fs.existsSync(gdir)) continue;
+
+  const nodes = fs.readdirSync(gdir).filter((f) => f.endsWith('.json'))
+    .map((f) => { try { return JSON.parse(fs.readFileSync(path.join(gdir, f), 'utf8')); } catch { return null; } })
+    .filter(Boolean);
+  const byHash = new Map();
+  for (const n of nodes) { byHash.set(n.hash, n); for (const v of n.variants ?? []) if (!byHash.has(v.hash)) byHash.set(v.hash, n); }
+
+  const esc = [];
+  const p = path.join(base, 'escalations.jsonl');
+  if (!fs.existsSync(p)) continue;
+  for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+    const t = line.trim(); if (!t) continue;
+    try { esc.push(JSON.parse(t)); } catch {}
+  }
+  const vf = esc.filter((e) => e.reason === 'verification_failed');
+
+  const bucket = { noScreen: 0, noEdge: 0, seenOnce: 0, consistent: 0, nondet: 0 };
+  const verdicts = new Map();
+  for (const e of vf) {
+    // Classify against a CLOSED vocabulary and never emit the raw text. The
+    // first version split on ':' and printed the prefix, which put a client's
+    // screen labels and an email address into a terminal. `detail` is app
+    // content; only its shape is ours to report.
+    const d = String(e.detail ?? '').toLowerCase();
+    const v = d.includes('no-visible-change') || d.includes('did not change') ? 'no-visible-change'
+      : d.includes('unexpected-screen') ? 'unexpected-screen'
+      : d.includes('did not settle') ? 'settle-timeout'
+      : d.includes('waited') ? 'wait-timeout'
+      : d.includes('matches') && d.includes('things') ? 'ambiguous'
+      : d.includes('numbered on a different') ? 'stale-ref'
+      : d.includes('disabled') ? 'disabled-control'
+      : d ? 'other' : '(none)';
+    verdicts.set(v, (verdicts.get(v) ?? 0) + 1);
+    const node = byHash.get(e.screen_fingerprint ?? '');
+    if (!node) { bucket.noScreen++; continue; }
+    const want = String(e.intent ?? '').toLowerCase();
+    const hit = (node.edges ?? []).find((x) => {
+      const sig = String(x.action ?? '').toLowerCase();
+      return want && (sig.endsWith(`:${want}`) || sig.includes(want));
+    });
+    if (!hit) { bucket.noEdge++; continue; }
+    if ((hit.changedOutcomes ?? 0) > 0) bucket.nondet++;
+    else if ((hit.count ?? 0) > 1) bucket.consistent++;
+    else bucket.seenOnce++;
+  }
+  const pct = (n) => (vf.length ? Math.round((100 * n) / vf.length) : 0);
+  console.log(`--- ${dev} ---`);
+  console.log(`  verification_failed: ${vf.length}`);
+  console.log(`  screen not in graph at all:            ${bucket.noScreen} (${pct(bucket.noScreen)}%)`);
+  console.log(`  screen known, this action never seen:  ${bucket.noEdge} (${pct(bucket.noEdge)}%)`);
+  console.log(`  edge seen exactly once:                ${bucket.seenOnce} (${pct(bucket.seenOnce)}%)`);
+  console.log(`  edge NONDETERMINISTIC (rightly asked): ${bucket.nondet} (${pct(bucket.nondet)}%)`);
+  console.log(`  edge repeated and CONSISTENT:          ${bucket.consistent} (${pct(bucket.consistent)}%)  <- addressable`);
+  console.log(`  verdict words: ${[...verdicts].sort((a,b)=>b[1]-a[1]).slice(0,6).map(([k,n])=>`${k}=${n}`).join(', ')}`);
+}

package/scripts/analyse-routes.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Would routing by measured time differ from routing by hop count, and by how
+ * much? EXPERIMENTS §16, kept runnable because the answer was "barely" and that
+ * is the kind of result that gets re-litigated by someone's intuition.
+ *
+ * `route()` in graph.js is a plain BFS over hop count, while `record()` has
+ * been storing a settle sample on nearly every edge all along (97% and 85% of
+ * edges on the two real-app graphs measured). This compares the two.
+ *
+ * Measured: the fastest route differs from the fewest-hops route on 9%, 0% and
+ * 7% of reachable pairs, saving a median of 1853ms, — and 615ms. Real, unused,
+ * and pointed at the wrong prize — it saves seconds, not round trips, and round
+ * trips are what the human-parity series exists to reduce.
+ *
+ * Output is aggregate by design: this reads a real device's memory of real
+ * third-party apps, so it prints counts and never a label, a screen or an app
+ * name. Same standing rule as scripts/phase17-corpus.mjs.
+ *
+ * Usage: node scripts/analyse-routes.mjs <udid-prefix> [<udid-prefix>...] */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const root = process.env.SIMFRAME_HOME || path.join(os.homedir(), '.simframe');
+const median = (a) => { const s=[...a].sort((x,y)=>x-y); return s.length? (s.length%2? s[(s.length-1)/2] : (s[s.length/2-1]+s[s.length/2])/2) : null; };
+
+for (const dev of process.argv.slice(2)) {
+  const dir = fs.readdirSync(root).find((d) => d.startsWith(dev));
+  if (!dir) continue;
+  const gdir = path.join(root, dir, 'graph');
+  if (!fs.existsSync(gdir)) continue;
+  const nodes = fs.readdirSync(gdir).filter(f=>f.endsWith('.json'))
+    .map(f => { try { return JSON.parse(fs.readFileSync(path.join(gdir,f),'utf8')); } catch { return null; } })
+    .filter(Boolean);
+
+  const byHash = new Map();
+  for (const n of nodes) { byHash.set(n.hash, n); for (const v of n.variants ?? []) if(!byHash.has(v.hash)) byHash.set(v.hash, n); }
+  const canonical = (h) => byHash.get(h)?.hash ?? h;
+
+  // Edge costs: the median settle actually measured on that edge.
+  const all = [];
+  for (const n of nodes) for (const e of n.edges ?? []) { const m = median(e.settles ?? []); if (m!=null) all.push(m); }
+  const fallback = median(all) ?? 500;
+  const cost = (e) => median(e.settles ?? []) ?? fallback;
+
+  // BFS exactly as graph.js does it: first path found, insertion order.
+  const bfs = (start, goal) => {
+    const seen = new Set([start]); const q = [{h:start, p:[]}];
+    while (q.length) { const {h,p} = q.shift();
+      if (p.length >= 12) continue;
+      for (const e of byHash.get(h)?.edges ?? []) {
+        const to = canonical(e.to); const next=[...p,e];
+        if (to === goal) return next;
+        if (seen.has(to)) continue; seen.add(to); q.push({h:to,p:next});
+      } }
+    return null;
+  };
+  // Dijkstra on measured time.
+  const fastest = (start, goal) => {
+    const dist = new Map([[start,0]]); const prev = new Map(); const done = new Set();
+    while (true) {
+      let cur=null, best=Infinity;
+      for (const [h,d] of dist) if (!done.has(h) && d<best) { best=d; cur=h; }
+      if (cur==null) break;
+      if (cur===goal) break;
+      done.add(cur);
+      for (const e of byHash.get(cur)?.edges ?? []) {
+        const to = canonical(e.to); const nd = best + cost(e);
+        if (nd < (dist.get(to) ?? Infinity)) { dist.set(to,nd); prev.set(to,[cur,e]); }
+      } }
+    if (!dist.has(goal)) return null;
+    const out=[]; let at=goal;
+    while (prev.has(at)) { const [from,e]=prev.get(at); out.unshift(e); at=from; }
+    return out;
+  };
+
+  const canon = [...new Set(nodes.map(n=>n.hash))];
+  let pairs=0, differ=0, saved=[], hopsUp=0;
+  for (const s of canon) for (const g of canon) {
+    if (s===g) continue;
+    const b = bfs(s,g); if (!b) continue;
+    const f = fastest(s,g); if (!f) continue;
+    pairs++;
+    const cb = b.reduce((t,e)=>t+cost(e),0), cf = f.reduce((t,e)=>t+cost(e),0);
+    if (cf < cb - 1) { differ++; saved.push(cb-cf); if (f.length > b.length) hopsUp++; }
+  }
+  saved.sort((a,b)=>a-b);
+  console.log(`--- ${dev} ---`);
+  console.log(`  reachable pairs: ${pairs}`);
+  console.log(`  where the fastest route differs from the fewest-hops route: ${differ} (${pairs?Math.round(100*differ/pairs):0}%)`);
+  if (saved.length) {
+    console.log(`  time saved per such route — median ${Math.round(median(saved))}ms, max ${Math.round(saved[saved.length-1])}ms`);
+    console.log(`  ...of those, routes that take MORE hops to be faster: ${hopsUp}`);
+  }
+}

package/scripts/check-published.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Does the version on npm contain the code you think it does?
+ *
+ * **DEFERRED 149.** `0.14.1` was tagged at one commit and a change landed
+ * immediately after it, so `npm install simframe@0.14.1` shipped the previous
+ * `centerOf()`. An external tester was asked to evaluate that change, diffed
+ * the package against the checkout themselves, and wrote: *"I came within one
+ * command of filing this report against the wrong binary."*
+ *
+ * Nothing in the pipeline compared what was tagged against what was being asked
+ * for, and the release workflow cannot: it checks that the tag, `package.json`
+ * and `server.json` agree, which they did. The gap is between the tag and
+ * whatever arrived afterwards.
+ *
+ * So this is the check to run **before handing someone a version to test**, and
+ * before cutting the next one. It fetches the published tarball and compares
+ * every shipped source file against the working tree.
+ *
+ * It deliberately compares against the WORKING TREE rather than a tag: the
+ * question being asked is "is what I am about to ask someone to install the code
+ * I am looking at", and a tag cannot answer that.
+ *
+ * Usage:
+ *   node scripts/check-published.mjs            # the version in package.json
+ *   node scripts/check-published.mjs 0.14.1     # any published version
+ *   node scripts/check-published.mjs --latest   # whatever npm serves as latest
+ *
+ * Exit 0 when every shipped file matches, 1 when any differs, 2 when the
+ * version is not published or npm could not be reached — which is a different
+ * answer and must not read as "it matches".
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const md5 = (buf) => createHash('md5').update(buf).digest('hex');
+const here = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+
+const arg = process.argv.slice(2).find((a) => !a.startsWith('-'));
+const wantLatest = process.argv.includes('--latest');
+const local = JSON.parse(fs.readFileSync(path.join(here, 'package.json'), 'utf8'));
+
+let version = arg ?? local.version;
+if (wantLatest) {
+  try {
+    version = execFileSync('npm', ['view', local.name, 'version'], { encoding: 'utf8' }).trim();
+  } catch (err) {
+    console.error(`could not ask npm for the latest ${local.name}: ${err.message}`);
+    process.exit(2);
+  }
+}
+
+console.log(`comparing ${local.name}@${version} on npm against this working tree`);
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'simframe-published-'));
+let tarball;
+try {
+  tarball = execFileSync('npm', ['pack', `${local.name}@${version}`, '--silent', '--pack-destination', tmp], {
+    encoding: 'utf8',
+  }).trim().split('\n').pop();
+} catch (err) {
+  // Not published, unpublished, or no network. None of those is a match.
+  console.error(`could not fetch ${local.name}@${version} from npm.`);
+  console.error('That is not the same answer as "it differs" — nothing was compared.');
+  console.error(String(err.stderr || err.message).trim().split('\n').slice(-3).join('\n'));
+  process.exit(2);
+}
+
+execFileSync('tar', ['-xzf', path.join(tmp, tarball), '-C', tmp]);
+const root = path.join(tmp, 'package');
+
+/** Every file the package ships, relative to the package root. */
+const shipped = [];
+const walk = (dir) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walk(full);
+    else shipped.push(path.relative(root, full));
+  }
+};
+walk(root);
+
+// Only compare what this repo is the source of. `package.json` is rewritten by
+// npm on publish (it adds `_id`, `dist`, and normalises fields), so byte
+// equality there is not the question and would be a permanent false alarm.
+const comparable = shipped.filter((f) => /^(src|scripts|native)\//.test(f) && !f.includes('/.build/'));
+
+const same = [];
+const differ = [];
+const missing = [];
+for (const rel of comparable) {
+  const mine = path.join(here, rel);
+  if (!fs.existsSync(mine)) { missing.push(rel); continue; }
+  if (md5(fs.readFileSync(mine)) === md5(fs.readFileSync(path.join(root, rel)))) same.push(rel);
+  else differ.push(rel);
+}
+
+const publishedVersion = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+console.log(`  published version: ${publishedVersion}`);
+console.log(`  files compared:    ${comparable.length}`);
+console.log(`  identical:         ${same.length}`);
+
+if (missing.length) {
+  console.log(`  shipped but absent here: ${missing.length}`);
+  for (const f of missing) console.log(`    ${f}`);
+}
+
+if (!differ.length && !missing.length) {
+  console.log(`\nok — ${local.name}@${version} is the code in this tree`);
+  process.exit(0);
+}
+
+console.error(`\nFAIL ${differ.length} shipped file(s) differ from this tree:`);
+for (const f of differ) console.error(`    ${f}`);
+console.error('\nIf you are about to ask someone to test a change, they would be testing');
+console.error('the published bytes above, not what you are reading. Publish first, or point');
+console.error('them at the checkout and say so.');
+process.exit(1);

package/scripts/ci-device-guard.mjs

@@ -31,6 +31,24 @@ const DEVICE_STATE = [
   [/Timeout waiting for screen surfaces|display surface is not answering|display surface could not be read/i, 'the display surface is wedged'],
   [/no frames buffered|capture is wedged/i, 'capture stopped'],
   [/the second app never launched|could not be dispatched/i, 'an app would not launch'],
+  // A launched app that never comes to the front, seen as the tour waiting for
+  // one of its landmarks on a screen that is showing a clock and nothing else.
+  //
+  // Measured on a runner: `ok launch — launched com.apple.Preferences
+  // (relaunched)` followed by `waited 8000ms for General: "General" is not on
+  // this screen. Visible: 10:50, .?o (the screen has not moved for 6181ms)`.
+  // Two labels, one of them a clock, on a still screen — the device is not
+  // presenting the app, and the guard called that a check failing on its
+  // merits and declined to revive.
+  //
+  // Deliberately narrow. It requires the wait to have failed AND the screen to
+  // have been still AND almost nothing readable: a tour that genuinely asks for
+  // the wrong label has a screen full of other labels, and must keep failing
+  // rather than being retried into a pass.
+  [
+    /never arrived[\s\S]*?Visible:[^\n]{0,24}\(the screen has not moved for \d+ms/i,
+    'a launched app never came to the front (the screen shows a clock and nothing else)',
+  ],
 ];
 
 const udid = process.argv[2];

package/scripts/classify-stray.mjs

@@ -0,0 +1,63 @@
+/**
+ * Why does a fingerprint reading not resemble its own screen?
+ *
+ * Its own module, with no side effects, for one reason: this logic has failed
+ * at RUNTIME twice — once reaching for a variable local to another function,
+ * once on declaration order — while being correct both times. `eval-fingerprint.mjs`
+ * runs the whole eval on import, so nothing could test it there, and the only
+ * thing that ever exercised it was a hosted runner at the end of a
+ * fifteen-minute job, in the middle of a report. That is the most expensive
+ * place in this project to find a typo.
+ *
+ * Three causes, and they have different remedies — which is the whole reason to
+ * tell them apart rather than print one sentence about all three:
+ *
+ * - **collided** — neither reading carries a chrome label, so both are
+ *   structure with no name and the fingerprint has nothing left to separate two
+ *   list screens. That is this harness's own subject, and a real finding.
+ * - **wrongScreen** — the tokens are identical to another screen AND this
+ *   screen reads differently in its other rounds, so it is demonstrably
+ *   distinguishable and the tour was simply somewhere else. A tap that missed.
+ * - **underRead** — the reading stayed under the token floor and the screen
+ *   cannot tell itself apart in any round, so we never looked long enough. Ours
+ *   to fix, and nothing about the tour or the fingerprint.
+ *
+ * The middle case is the correction that prompted this. Sparseness alone used
+ * to claim `underRead`, and a wrong turn onto a screen that *legitimately*
+ * reads sparse — the Settings root, at 4 tokens on a runner — is flagged sparse
+ * too. So a genuine tour failure was reported as our instrument's fault, and
+ * the harness's original and correct message had been silenced by an
+ * "improvement".
+ */
+import * as fingerprint from '../src/fingerprint.js';
+
+/**
+ * @param {object} o
+ * @param {object} o.reading           the stray
+ * @param {object|null} o.match        the other screen's reading it most resembles
+ * @param {number} o.bestOther         how much it resembles that one, 0..1
+ * @param {object[]} o.siblings        every reading of the stray's own screen
+ * @param {boolean} o.wasSparse        did it stay under the token floor after retries
+ * @param {string[]} [o.named]         chrome-labelled tokens in the stray
+ * @param {string[]} [o.matchNamed]    chrome-labelled tokens in the match
+ */
+export function classifyStray({
+  reading, match, bestOther, siblings, wasSparse, named = [], matchNamed = [],
+}) {
+  // Does any other round of this same screen read differently from the screen
+  // we collided with? If so this screen CAN be told apart, and a round that
+  // matched the other one exactly was somewhere else.
+  const distinguishable = (siblings ?? [])
+    .some((o) => o !== reading && fingerprint.similarity(o.tokens, match?.tokens ?? []) < 0.99);
+  const identical = bestOther >= 0.99;
+  // Checked first and exclusively: a reading with no names at all cannot be
+  // said to have gone anywhere, because there is nothing in it that would have
+  // named a destination.
+  const collided = identical && named.length === 0 && matchNamed.length === 0;
+  return {
+    collided,
+    wrongScreen: !collided && identical && distinguishable,
+    underRead: !collided && Boolean(wasSparse) && !distinguishable,
+    distinguishable,
+  };
+}