simframe 0.10.0 → 0.11.0

package/src/index.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEFAULTS, STATE_VERSION } from './daemon.js';
 import * as engine from './engine.js';
+import * as regions from './regions.js';
 import { decodePng, encodePng, scaleBitmap } from './png.js';
 import {
   REGION_COLS,
@@ -536,9 +537,31 @@ export async function getFrame(deviceQuery, { detail = 'normal', options } = {})
   let scaledOnRead = false;
   if (maxDim === 0) {
     file = state.fullFile;
-  } else if (maxDim > nativeMax + 8 && fs.existsSync(state.fullFile)) {
+  } else if (maxDim > nativeMax + 8) {
+    // Asking for more detail than the ring frame holds, so it has to come from
+    // a full-resolution frame. The `fs.existsSync(state.fullFile)` this used to
+    // require is exactly the condition that fails routinely — retention thins
+    // full frames aggressively, and `state.fullFile` names one that is often
+    // already gone. When it did, this fell straight through to `latest.png` and
+    // returned a 322x700 image while still calling itself detail "high".
+    //
+    // That was not a small inaccuracy. Every single `sim_look` header in a
+    // two-agent field round read `322x700` on a 402x874pt device, so "high
+    // (1024px, readable small text)" was interpolating a sub-1x source the
+    // whole time. `fullFrameFor` has always known how to find or take a full
+    // frame — state named full/9660.png while the directory held eight frames
+    // at 1206x2622 — and this path simply never asked it.
+    //
+    // What this does *not* explain, though it is tempting: the OCR corruption
+    // in that round's log (`saaiad@example.com`, `suomit order`). OCR has
+    // always gone through `fullFrameFor`, and the daemon's own text recognition
+    // reads the live surface at native resolution, so neither was ever looking
+    // at the small frame. Those errors are a desktop-width page rendering its
+    // labels at a few pixels tall. Fixing what the caller *sees* does not fix
+    // what OCR reads, and saying so here keeps the next reader from assuming it did.
+    const source = await fullFrameFor(device.udid, state);
     const out = path.join(p.dir, `read-${maxDim}.png`);
-    await resize(state.fullFile, out, maxDim);
+    await resize(source, out, maxDim);
     file = out;
     scaledOnRead = true;
   } else if (maxDim < nativeMax - 8) {
@@ -550,17 +573,50 @@ export async function getFrame(deviceQuery, { detail = 'normal', options } = {})
 
   const png = fs.readFileSync(file);
   const bmp = pngSize(png);
+  // The age must describe the *bytes*, not the state that dates them.
+  //
+  // These are two different files. `state.json` is written when a frame is
+  // recorded; the image is a separate write. A freshly started daemon publishes
+  // fresh state while `latest.png` is still the previous session's — which is
+  // when a caller's first look of a session happens. Reported, and it is the
+  // worst failure this tool can have: a header reading `frame #714 · 84ms old ·
+  // still for 17173ms` above an image whose status-bar clock said 6:11 when the
+  // real time was 11:10. `sim_ui` was right in the same session because the
+  // accessibility tree is read live and in-process; only the image comes from a
+  // file, so only the image can be hours stale while the header says otherwise.
+  //
+  // Taking the *larger* of the two ages cannot overstate freshness. It can
+  // overstate staleness by however long the two writes are apart, which is 6ms
+  // measured on a healthy daemon — the right direction to be wrong in.
+  let fileAgeMs = null;
+  try { fileAgeMs = Date.now() - fs.statSync(file).mtimeMs; } catch { /* stat is advisory */ }
+  const stateAgeMs = Date.now() - state.capturedAt;
+  const ageMs = Number.isFinite(fileAgeMs) ? Math.max(stateAgeMs, fileAgeMs) : stateAgeMs;
   return {
     device,
     state,
     png,
     width: bmp.width,
     height: bmp.height,
-    ageMs: Date.now() - state.capturedAt,
+    ageMs,
+    // Said out loud when the image is materially older than the state, because
+    // "this picture is not of the screen the rest of this response describes" is
+    // not something a caller can work out for themselves.
+    frameBehindMs: Number.isFinite(fileAgeMs) && fileAgeMs - stateAgeMs > FRAME_BEHIND_MS
+      ? Math.round(fileAgeMs - stateAgeMs)
+      : null,
     scaledOnRead,
   };
 }
 
+/**
+ * How far the image may lag the state before it is worth saying so.
+ *
+ * Measured on a healthy daemon, the two writes land 6ms apart. A second is far
+ * outside that and far inside the hours-stale case this exists to catch.
+ */
+const FRAME_BEHIND_MS = 1000;
+
 function pngSize(png) {
   return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
 }
@@ -1068,10 +1124,76 @@ export async function readScreenWith(deviceQuery, { useAx = true, useOcr = true,
   return { device, entry, points: { width: geo.pointWidth, height: geo.pointHeight } };
 }
 
-export async function locate(
+/**
+ * A target that answers the query but sits outside the viewport.
+ *
+ * The off-screen filter above is right — an element in the tree below the fold
+ * is untappable in fact — but "not on this screen" was the wrong way to say so.
+ * Reported: a `waitFor` spent its full 15s timeout and stopped the flow while
+ * the control sat one scroll down. Waiting cannot fix that and scrolling can.
+ */
+export function offScreenMatch(targets, query, points) {
+  // Both axes: a horizontal row puts elements past the right edge, and checking
+  // only `y` reported them as visible.
+  const off = (targets ?? []).filter((t) => t.label && regions.offViewport(t, points));
+  if (!off.length) return null;
+  const hit = matching.resolve(off, query);
+  if (hit.status === 'ok') return hit.target;
+  // Ambiguous off-screen is still an answer to "why is it not here".
+  return hit.status === 'ambiguous' && hit.alternatives?.length ? hit.alternatives[0] : null;
+}
+
+/**
+ * Which sensors a read asks for by default.
+ *
+ * `full` is the default and what CLAUDE.md fixes: accessibility and OCR fused
+ * into one element list. `ax-first` asks for the tree alone — 85 ms against
+ * 142 ms warm — and pays for OCR only when the cheap read could not answer the
+ * question.
+ *
+ * The escalation is the whole point, and it is what makes this safe to try. A
+ * mode that just dropped OCR would lose every OCR-only element, which is
+ * precisely how the map cut lost discovery: nothing became untappable, but the
+ * agent could no longer see what was there. Here a resolve failure — the one
+ * signal that says "the cheap sensor was not enough" — triggers a full read
+ * before anyone is told the target is absent. Wrong guesses cost a second read;
+ * they cannot cost a wrong answer.
+ */
+export function sensorMode(options) {
+  // Per call first, then the environment. The environment is fixed when a
+  // process starts, and an MCP server is one long-lived process — so a tester
+  // asked to compare two sensor modes in one session could not do it, which is
+  // exactly what happened: round 6's A was run and B and C could not be. Their
+  // own suggestion was three server entries with three env blocks, and it is
+  // the worse fix: three servers on one device means three writers, against the
+  // one-writer-per-device rule, and it makes an A/B a configuration change
+  // rather than an argument.
+  const asked = options?.sensor;
+  const raw = String(asked ?? process.env.SIMFRAME_SENSOR ?? '').trim().toLowerCase();
+  return raw === 'ax-first' || raw === 'axfirst' ? 'ax-first' : 'full';
+}
+
+export async function locate(deviceQuery, query, opts = {}) {
+  if (sensorMode(opts.options) !== 'ax-first' || opts.useOcr === false || opts.escalated) {
+    return locateWith(deviceQuery, query, opts);
+  }
+  const options = opts;
+  try {
+    return await locateWith(deviceQuery, query, { ...options, useOcr: false, escalated: true });
+  } catch (err) {
+    // Only a perception failure earns the expensive retry. A refused selector or
+    // an ambiguity between two things the tree *did* see is not going to be
+    // settled by reading more text.
+    const why = metrics.escalationOf(err);
+    if (why?.reason !== 'unknown_screen' && why?.reason !== 'ambiguous_intent') throw err;
+    return locateWith(deviceQuery, query, { ...options, useOcr: true, refresh: true, escalated: true });
+  }
+}
+
+async function locateWith(
   deviceQuery,
   query,
-  { index, refresh = false, useAx = true, useOcr = true, settleMs = MEMORY_SETTLE_MS, options } = {},
+  { index, refresh = false, useAx = true, useOcr = true, settleMs = MEMORY_SETTLE_MS, options, escalated } = {},
 ) {
   const { device, state: firstState } = await ensureDaemon(deviceQuery, options);
   const udid = device.udid;
@@ -1094,11 +1216,47 @@ export async function locate(
     // be checked against structural identity without paying for a perception
     // pass — which is the whole reason a ref exists.
     const near = screenmap.recallNearest(udid, firstState.layoutHash);
-    const hit = refs.resolveRef(udid, selector.ref, {
-      layoutHash: firstState.layoutHash,
-      structuralHash: near?.entry?.structuralHash ?? null,
-      screenKnown: Boolean(near),
-    });
+    let hit;
+    try {
+      hit = resolveRefHere();
+    } catch (err) {
+      // A stale ref carries the label it was numbered against, so it need not
+      // cost the rest of the batch. Reported: `#19 was numbered on a different
+      // screen (61b835b7 → 6f34c006)` because dashboard cards finished loading
+      // and shifted the layout — the same screen, a new hash — and that one
+      // refusal aborted the three remaining steps.
+      //
+      // It re-resolves by label rather than by coordinate, and it *says so*.
+      // The number is not honoured; the caller's own words are, which is what
+      // they would have written instead. Resolving the old coordinates would be
+      // the dangerous version of this, and is not what happens.
+      // Only layout drift is recoverable. `identity` means the numbers were
+      // drawn somewhere else, and the label they stood for appearing here is
+      // coincidence rather than evidence — measured: `#1` numbered "Reminders"
+      // in Reminders re-resolved in Contacts onto the status-bar back-to-app
+      // breadcrumb "• Reminders", and reported ok.
+      if (!err.staleRef || !err.staleLabel || err.staleKind !== 'drift') throw err;
+      let again;
+      try {
+        again = await locateWith(deviceQuery, err.staleLabel, {
+          index, refresh: true, useAx, useOcr, settleMs, options, escalated,
+        });
+      } catch (second) {
+        // The number was not honoured and the label it stood for is not here
+        // either. That is still a refusal to tap stale coordinates, but by the
+        // time it surfaces it looks like an ordinary "not on this screen" and a
+        // caller cannot tell the two apart. Carrying the marker across says
+        // which question was actually asked.
+        second.staleRef = true;
+        second.staleLabel = err.staleLabel;
+        throw second;
+      }
+      return {
+        ...again,
+        from: 'ref-relabelled',
+        relabelled: { ref: selector.ref, label: err.staleLabel, why: err.message },
+      };
+    }
     return {
       device,
       state: firstState,
@@ -1107,6 +1265,23 @@ export async function locate(
       distance: 0,
       settled: true,
     };
+
+    function resolveRefHere() {
+      return refs.resolveRef(udid, selector.ref, {
+      layoutHash: firstState.layoutHash,
+      structuralHash: near?.entry?.structuralHash ?? null,
+      // How far that recall reached. `recallNearest` is deliberately tolerant —
+      // a list with new rows is still the same screen — so at any distance
+      // above zero it is a *guess* about which screen this is, and a guess must
+      // not be the sole grounds for refusing a ref. Reported from the field: a
+      // refusal reading `#5 was numbered on a different screen
+      // (0f7b9e3e → 48e5c92d)` where both calls' headers printed the identical
+      // screen, because the map named the screen from a tolerant recall while
+      // refs treated that same recall as exact.
+        structuralDistance: near?.distance ?? null,
+        screenKnown: Boolean(near),
+      });
+    }
   }
   if (selector.exact) query = selector.label;
   // Key memory off a settled frame, never off whichever frame happened to be
@@ -1167,7 +1342,7 @@ export async function locate(
         // ambiguous_intent when the screen was one we thought we knew. A
         // waiting caller needs the difference: more time cannot make a thing
         // unique, and it can make an absent thing arrive.
-        { candidates: outcome.alternatives, ambiguous: true },
+        { candidates: outcome.alternatives, ambiguous: true, intent: query },
       );
     }
     if (outcome.status === 'ok') {
@@ -1181,8 +1356,25 @@ export async function locate(
     // here undoes every guard above — it has no off-screen filter and no
     // coverage weighting, and it is what returned a scrolled-away list row for
     // "back". "Not found" is the correct answer.
-    const visible = entry.targets.filter((t) => t.label && t.y >= 0 && t.y <= points.height);
+    const visible = entry.targets.filter((t) => t.label && !regions.offViewport(t, points));
     const sample = visible.slice(0, 12).map((t) => t.label.slice(0, 24)).join(', ');
+    // "Not on this screen" and "not in view" are different answers, and giving
+    // the first for the second cost a reported 15 seconds: a `waitFor REVIEW`
+    // burned its whole timeout while REVIEW sat one scroll below the fold, and
+    // then stopped the flow. Waiting cannot bring a thing into view, and
+    // scrolling can — so the difference is the whole of what to do next.
+    const offScreen = offScreenMatch(entry.targets, query, points);
+    if (offScreen) {
+      throw metrics.tag(
+        new Error(
+          `"${query}" is in the tree but not in view — it is at y=${Math.round(offScreen.y)}`
+          + ` on a ${Math.round(points.height)}pt screen. Scroll to it (sim_scroll_to) rather than waiting;`
+          + ' waiting cannot bring it into view.',
+        ),
+        from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',
+        { candidates: visible.slice(0, 8), intent: query },
+      );
+    }
     // Which escalation this is depends on whether the screen was recognised.
     // Screen memory had nothing for it (`from` is one of the built values) and
     // the target is missing: that is not knowing the screen. On a screen
@@ -1190,7 +1382,7 @@ export async function locate(
     throw metrics.tag(
       new Error(`"${query}" is not on this screen. Visible: ${sample || '(nothing readable)'}`),
       from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',
-      { candidates: visible.slice(0, 8) },
+      { candidates: visible.slice(0, 8), intent: query },
     );
   }
 
@@ -1202,7 +1394,7 @@ export async function locate(
     throw metrics.tag(
       new Error(`"${query}" is not on this screen. Visible: ${sample || '(nothing readable)'}`),
       from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',
-      { candidates: visible.slice(0, 8) },
+      { candidates: visible.slice(0, 8), intent: query },
     );
   }
   return { device, state: current, entry, target, from, distance, settled, screens: screenmap.stats(udid).screens };
@@ -1315,6 +1507,11 @@ export async function screenIdentity(deviceQuery, { options, confirmNovel = true
       keyboard: Boolean(entry.keyboard),
       layoutHash: current.layoutHash,
       settled,
+      // Settled and incomplete are different states and used to render
+      // identically. A screen awaiting a network call is perfectly still; a
+      // person sees a spinner and knows to wait. The classifier already says
+      // so, and nothing above this line was asking.
+      loading: current.transition?.kind === 'loading',
       // Carried out so callers that want the elements as well as the identity
       // do not pay for a second perception pass to get them. The compact
       // screen map needs both, and reading twice was the whole cost of it.

package/src/input.js

@@ -429,14 +429,77 @@ export async function typeKeys(udid, value) {
   await idb(['ui', 'text', '--udid', udid, String(value)]);
 }
 
-export async function pressKey(udid, keycode) {
+/**
+ * Keyboard keys, by name.
+ *
+ * A peer was blocked outright for want of Return: half of mobile search fields
+ * submit on the keyboard return key, `button` covers only the hardware buttons,
+ * and `key` wanted a raw HID usage code that nobody should have to know. Typing
+ * "\n" as text is not a substitute — text goes through whatever keyboard layout
+ * iOS has active, and measured, it turned "Coke Display" into "Coke In Display".
+ *
+ * These are HID keyboard usage codes, which name a key *position* and are never
+ * translated by a layout. That property is the whole reason this path exists on
+ * a device whose own doctor warns that two extra layouts are installed.
+ */
+export const KEYS = {
+  return: 40, enter: 40, escape: 41, esc: 41, backspace: 42, delete: 42,
+  tab: 43, space: 44, up: 82, down: 81, left: 80, right: 79,
+  a: 4,
+};
+
+/** Modifier usage codes, held while another key is pressed. */
+export const MODIFIERS = { control: 224, shift: 225, alt: 226, option: 226, command: 227, cmd: 227, gui: 227 };
+
+/** The usage code for a name, a number, or null when it is neither. */
+export function keyUsage(key) {
+  if (Number.isFinite(Number(key))) return Number(key);
+  const name = String(key ?? '').trim().toLowerCase();
+  return Object.hasOwn(KEYS, name) ? KEYS[name] : null;
+}
+
+export async function pressKey(udid, keycode, { modifiers = [] } = {}) {
   await ensureFreshSession(udid);
+  const usage = keyUsage(keycode);
+  const held = modifiers
+    .map((m) => (Number.isFinite(Number(m)) ? Number(m) : MODIFIERS[String(m).trim().toLowerCase()]))
+    .filter((m) => Number.isFinite(m));
+  if (usage == null) {
+    throw new Error(`unknown key ${JSON.stringify(String(keycode))} — known names: ${Object.keys(KEYS).join(', ')}`
+      + ', or a HID usage code');
+  }
   const own = inputDriverFor(udid);
   if (own) {
-    await own.key(udid, keycode);
+    await own.key(udid, usage, held);
+    return;
+  }
+  // The daemon owns the keyboard usage path on iOS. It was implemented in the
+  // HID layer and never exposed as a verb, so this fell through to idb — which
+  // is absent on a machine using the daemon, and so there was no way to press a
+  // keyboard key at all.
+  if (control.available(udid)) {
+    await control.key(udid, usage, held);
     return;
   }
-  await idb(['ui', 'key', '--udid', udid, String(keycode)]);
+  if (held.length) throw new Error('modifier keys need the daemon; idb cannot hold one');
+  await idb(['ui', 'key', '--udid', udid, String(usage)]);
+}
+
+/**
+ * Empty the focused field.
+ *
+ * Command-A then Delete, over HID. There is no clear primitive anywhere —
+ * XCUITest, Appium and idb all lack one, and re-typing appends — so this is the
+ * standard answer rather than a trick of ours. It is layout-independent for the
+ * reason that matters on a device with Farsi and Armenian keyboards installed:
+ * a modifier and Delete are key *positions*, and so is the `a` in Command-A, so
+ * none of the three is translated by the active layout.
+ *
+ * It clears whatever has focus, which is why every caller focuses first.
+ */
+export async function clearField(udid) {
+  await pressKey(udid, 'a', { modifiers: ['command'] });
+  await pressKey(udid, 'delete');
 }
 
 /**

package/src/localhelper.js

@@ -0,0 +1,155 @@
+/**
+ * A warm, line-oriented local helper process.
+ *
+ * Extracted rather than duplicated, because writing this twice would mean
+ * risking the same two bugs twice — and both were subtle enough to look like
+ * something else entirely.
+ *
+ * A timed-out request left its waiter in the queue, so every later answer went
+ * to the wrong asker and the run simply never finished; it read as the model
+ * being slow. And unreferencing the child's stdout unreferenced the pipe every
+ * request waits on, so the process exited silently in the middle of an await
+ * and printed nothing at all, returning 0.
+ *
+ * The helper is kept warm because the first answer in a process pays model load
+ * — measured at ~880ms against ~560ms for every answer after it.
+ */
+import { spawn, execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/**
+ * Compile a Swift source once and reuse the binary.
+ *
+ * `swiftc`, not `xcrun swiftc`: nothing above the platform boundary may name a
+ * platform tool, and the boundary test catches it. A compiler is not a device
+ * tool, which is the precedent `src/ocr.js` set.
+ */
+export function compiler({ source, binary, what }) {
+  let building = null;
+  return async function ensureBinary() {
+    if (building) return building;
+    building = (async () => {
+      try {
+        const src = fs.statSync(source).mtimeMs;
+        const bin = fs.existsSync(binary) ? fs.statSync(binary).mtimeMs : 0;
+        if (bin > src) return { available: true, binary };
+      } catch {
+        return { available: false, reason: `the ${what} source is missing from this install` };
+      }
+      try {
+        fs.mkdirSync(path.dirname(binary), { recursive: true });
+        await run('swiftc', ['-O', source, '-o', binary], { timeout: 180_000 });
+        return { available: true, binary };
+      } catch (err) {
+        building = null; // let a later call retry once a toolchain is present
+        return {
+          available: false,
+          reason: err.code === 'ENOENT'
+            ? `swiftc is not installed, so the ${what} cannot be built (install Xcode command line tools)`
+            : `could not build the ${what}: ${String(err.message).split('\n')[0]}`,
+        };
+      }
+    })();
+    return building;
+  };
+}
+
+/**
+ * Open a helper and speak JSON lines to it.
+ *
+ * @returns {{ask: (o: object, ms: number) => Promise<object|null>, close: () => void, ok: boolean, reason?: string}}
+ */
+export function lineServer({ ensureBinary, what }) {
+  let session = null;
+
+  async function open() {
+    if (session) return session;
+    const built = await ensureBinary();
+    if (!built.available) return { ok: false, reason: built.reason };
+    session = await new Promise((resolve) => {
+      const child = spawn(built.binary, [], { stdio: ['pipe', 'pipe', 'ignore'] });
+      // Deliberately NOT unref'd — see the note at the top of this file.
+      let buffer = '';
+      const waiters = [];
+      let settled = false;
+      const fail = (reason) => {
+        if (!settled) { settled = true; resolve({ ok: false, reason }); }
+        while (waiters.length) waiters.shift()(null);
+      };
+      child.on('error', (err) => fail(`the ${what} would not start: ${err.message}`));
+      child.on('exit', () => { session = null; fail(`the ${what} exited`); });
+      child.stdout.on('data', (chunk) => {
+        buffer += chunk;
+        let i = buffer.indexOf('\n');
+        while (i >= 0) {
+          const line = buffer.slice(0, i).trim();
+          buffer = buffer.slice(i + 1);
+          i = buffer.indexOf('\n');
+          if (!line) continue;
+          let msg;
+          try { msg = JSON.parse(line); } catch { continue; }
+          if (!settled) {
+            settled = true;
+            if (msg.ready) resolve({ ok: true, child, waiters });
+            else resolve({ ok: false, reason: msg.unavailable ?? `the ${what} did not become ready` });
+            continue;
+          }
+          const next = waiters.shift();
+          if (next) next(msg);
+        }
+      });
+    });
+    return session;
+  }
+
+  return {
+    async ask(question, timeoutMs = 3000) {
+      let live;
+      try {
+        live = await open();
+      } catch {
+        return null;
+      }
+      if (!live?.ok) return null;
+      return new Promise((resolve) => {
+        // A timed-out waiter is retired, not merely resolved. Leaving it queued
+        // sent the next answer to it instead of to the next asker, and every
+        // call after that was off by one.
+        let done = false;
+        const waiter = (msg) => {
+          if (done) return;
+          done = true;
+          clearTimeout(timer);
+          resolve(msg);
+        };
+        const timer = setTimeout(() => {
+          if (done) return;
+          done = true;
+          const i = live.waiters.indexOf(waiter);
+          if (i >= 0) live.waiters.splice(i, 1);
+          resolve(null);
+        }, timeoutMs);
+        live.waiters.push(waiter);
+        try {
+          live.child.stdin.write(`${JSON.stringify(question)}\n`);
+        } catch {
+          clearTimeout(timer);
+          done = true;
+          resolve(null);
+        }
+      });
+    },
+    async status() {
+      const live = await open();
+      return live?.ok ? { ok: true } : { ok: false, reason: live?.reason ?? 'unavailable' };
+    },
+    close() {
+      try { session?.child?.kill(); } catch { /* already gone */ }
+      session = null;
+    },
+  };
+}

package/src/matching.js

@@ -337,9 +337,67 @@ function sameControl(a, b) {
   // and a map built before that still resolves.
   if (isAxTarget(a) && !isAxTarget(b) && sameElementSeenTwice(a, b)) return true;
   if (isAxTarget(b) && !isAxTarget(a) && sameElementSeenTwice(b, a)) return true;
+  // And a caption sitting on the control it names. Containment above requires
+  // the container to be a recognised hit target, and a React Native composite
+  // is a generic element — so a form row published its caption and its select
+  // with the same label, 152 points apart, and nothing merged them. They are
+  // one control seen twice, not two candidates: answering `ambiguous` here
+  // costs a round trip to choose between a thing and its own name.
+  if (isCaptionFor(a, b) || isCaptionFor(b, a)) return true;
   return false;
 }
 
+/** Does `caption` merely name `control`, overlapping it, with the same label? */
+function isCaptionFor(caption, control) {
+  if (!namesOnly(caption) || namesOnly(control)) return false;
+  if (norm(caption.label) !== norm(control.label)) return false;
+  return overlaps(caption.frame, control.frame);
+}
+
+/** Any shared area at all — a caption's box often clears its control's by a point or two. */
+function overlaps(a, b) {
+  if (!a || !b) return false;
+  return a.x < b.x + b.width && b.x < a.x + a.width
+    && a.y < b.y + b.height && b.y < a.y + a.height;
+}
+
+/**
+ * Roles that only ever *name* a control, never are one.
+ *
+ * The tree publishes a caption and the control it captions with the same label,
+ * and a React Native composite (a `native-base` Select, say) surfaces as a
+ * generic element that `INTERACTIVE_ROLE` does not recognise. So `tap "Problem"`
+ * resolved to the caption at (49,486) and did nothing, while the select sat at
+ * (201,496) — reported as half of the single largest cost in a real-app run,
+ * because it means neither selector can be trusted.
+ *
+ * `collapseSamePlace` already prefers a hit target over the text printed on it,
+ * but only once `sameControl` has decided they are the same place. These two
+ * were 152 points apart with a generic role, so nothing merged them.
+ */
+const NAMING_ONLY_ROLE = /^(statictext|text|label|heading|image)$/i;
+
+const namesOnly = (t) => NAMING_ONLY_ROLE.test(t?.type ?? '');
+
+/**
+ * A caption never wins over a control that answers the same name.
+ *
+ * Applied only when the two are close enough in score to be answering the same
+ * question — a heading is still reachable when nothing else matches, which is
+ * why this promotes rather than filters. Anything further apart than
+ * `CAPTION_MARGIN` is a different match, not the same match seen twice.
+ */
+export const CAPTION_MARGIN = 0.2;
+
+export function preferTheControl(ranked) {
+  if (!ranked.length || !namesOnly(ranked[0].target)) return ranked;
+  const lead = ranked[0].score;
+  const i = ranked.findIndex((c, idx) => idx > 0 && !namesOnly(c.target) && lead - c.score <= CAPTION_MARGIN);
+  if (i < 0) return ranked;
+  const promoted = { ...ranked[i], reasons: [...ranked[i].reasons, 'the control, not the caption naming it'] };
+  return [promoted, ...ranked.filter((_, idx) => idx !== i)];
+}
+
 function collapseSamePlace(ranked) {
   const kept = [];
   for (const c of ranked) {
@@ -351,6 +409,11 @@ function collapseSamePlace(ranked) {
     // Prefer the real hit target: an accessibility element over OCR's reading of
     // it, and an interactive role over a caption sitting inside it.
     const better = (candidate, incumbent) => {
+      // A caption loses to what it names before anything else is considered:
+      // a `StaticText` is never the tap target when the control it labels is
+      // right there, whatever either one's source.
+      if (namesOnly(incumbent.target) && !namesOnly(candidate.target)) return true;
+      if (namesOnly(candidate.target) && !namesOnly(incumbent.target)) return false;
       if (isAxTarget(candidate.target) && !isAxTarget(incumbent.target)) return true;
       if (!isAxTarget(candidate.target) && isAxTarget(incumbent.target)) return false;
       return INTERACTIVE_ROLE.test(candidate.target.type ?? '')
@@ -368,7 +431,7 @@ function collapseSamePlace(ranked) {
  * @returns {{status: 'ok'|'ambiguous'|'none', target?, score?, reasons?, alternatives?}}
  */
 export function resolve(targets, intent, options = {}) {
-  const ranked = collapseSamePlace(rank(targets, intent, options).filter((c) => c.score >= MINIMUM_SCORE));
+  const ranked = preferTheControl(collapseSamePlace(rank(targets, intent, options).filter((c) => c.score >= MINIMUM_SCORE)));
   if (!ranked.length) return { status: 'none', alternatives: [] };
   const [best, second] = ranked;
   if (second && best.score - second.score < AMBIGUITY_MARGIN) {