simframe 0.1.0 → 0.4.1

package/src/daemon.js

@@ -2,22 +2,40 @@
 // newest frame permanently warm on disk so a reader never waits on simctl.
 import fs from 'node:fs';
 import path from 'node:path';
-import { decodePng } from './png.js';
-import { frameHash, regionSignature, signatureDiff, regionDeltas } from './analyze.js';
+import { decodePng, encodePng, scaleBitmap } from './png.js';
+import {
+  frameHash,
+  layoutHash,
+  regionSignature,
+  signatureDiff,
+  regionDeltas,
+  signatureToHex,
+} from './analyze.js';
 import * as store from './store.js';
 import { isBootedSync, resize, screenshot } from './simctl.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.
-export const STATE_VERSION = 2;
+export const STATE_VERSION = 5;
 
 export const DEFAULTS = {
   fps: 4,
   idleFps: 1.5,
   idleAfterMs: 2500,
   maxDim: 700,
-  ringSize: 24,
-  fullKeep: 3,
+  // Frame memory: every frame for the last few seconds, thinned to roughly
+  // 2fps further back. Fine detail where transitions live, cheap recall beyond.
+  retainMs: 60_000,
+  fineMs: 6_000,
+  keyframeMs: 450,
+  // Frames older than fineMs are re-encoded at half size: still legible enough
+  // to tell which screen was showing, at roughly a quarter of the bytes.
+  recallScale: 0.5,
+  maxRingBytes: 12 << 20,
+  ringSize: 400,
+  historySize: 400,
+  historyMs: 90_000,
+  fullKeep: 8,
   changeThreshold: 0.004,
   idleExitMs: 15 * 60_000,
 };
@@ -53,6 +71,11 @@ export async function runDaemon(device, options = {}) {
 
   let seq = 0;
   let prevSignature = null;
+  /** Recent frames, so a caller can diff against whatever it last saw rather
+   *  than only against the frame that happened to precede this one. */
+  let history = [];
+  /** seq + timestamp for every frame still on disk, so retention can be thinned by age. */
+  let ringIndex = [];
   let lastChangeAt = Date.now();
   let consecutiveErrors = 0;
   let lastBootCheck = Date.now();
@@ -102,6 +125,7 @@ export async function runDaemon(device, options = {}) {
 
       const bmp = decodePng(fs.readFileSync(ringFile));
       const signature = regionSignature(bmp);
+      const prevWasNull = prevSignature === null;
       const diff = signatureDiff(signature, prevSignature);
       const deltas = regionDeltas(signature, prevSignature);
       const changed = diff > opts.changeThreshold;
@@ -112,6 +136,18 @@ export async function runDaemon(device, options = {}) {
       prevSignature = signature;
       consecutiveErrors = 0;
 
+      const hash = frameHash(bmp);
+      const layout = layoutHash(bmp);
+      history.push({
+        seq,
+        at: now,
+        hash,
+        sig: signatureToHex(signature),
+        diff: prevWasNull ? 0 : Number(diff.toFixed(5)),
+      });
+      const historyCutoff = now - opts.historyMs;
+      history = history.filter((h) => h.at >= historyCutoff).slice(-opts.historySize);
+
       fs.copyFileSync(ringFile, path.join(p.dir, 'latest.png.tmp'));
       fs.renameSync(path.join(p.dir, 'latest.png.tmp'), path.join(p.dir, 'latest.png'));
 
@@ -123,17 +159,34 @@ export async function runDaemon(device, options = {}) {
           captureMs: now - tickStart,
           width: bmp.width,
           height: bmp.height,
-          hash: frameHash(bmp),
-          diff: Number(diff.toFixed(5)),
-          changed,
+          hash,
+          layoutHash: layout,
+          diff: prevWasNull ? null : Number(diff.toFixed(5)),
+          changed: prevWasNull ? false : changed,
+          firstFrame: prevWasNull,
           stableForMs: now - lastChangeAt,
-          regions: deltas.map((d) => Number(d.toFixed(4))),
+          regions: prevWasNull ? deltas.map(() => 0) : deltas.map((d) => Number(d.toFixed(4))),
+          // Absolute instant of the last detected change: lets a caller reason
+          // about baselines older than the history window.
+          lastChangeAt,
+          history,
+          ring: ringIndex,
           fullFile,
           ringFile,
           device,
         }),
       );
 
+      ringIndex.push({ seq, at: now });
+      ringIndex = thinRing(ringIndex, now, opts, (dropped) => {
+        try {
+          fs.unlinkSync(path.join(p.ring, `${dropped}.png`));
+        } catch {
+          /* already gone */
+        }
+      });
+      shrinkAgedFrames(p.ring, ringIndex, now, opts, log);
+      enforceByteBudget(p.ring, ringIndex, opts);
       store.pruneDir(p.ring, opts.ringSize);
       store.pruneDir(p.full, opts.fullKeep);
     } catch (err) {
@@ -168,3 +221,80 @@ export async function runDaemon(device, options = {}) {
   }
   return outcome;
 }
+
+/**
+ * Decide which buffered frames to keep. Everything inside `fineMs` survives, so
+ * a transition can be replayed frame by frame; beyond that only one frame per
+ * `keyframeMs` is kept, out to `retainMs`. Calls `drop` for each discarded seq
+ * and returns the retained index.
+ */
+export function thinRing(index, now, opts, drop = () => {}) {
+  const kept = [];
+  let lastKeptAt = null;
+  for (let i = index.length - 1; i >= 0; i--) {
+    const frame = index[i];
+    const age = now - frame.at;
+    if (age > opts.retainMs) {
+      drop(frame.seq);
+      continue;
+    }
+    if (age <= opts.fineMs || lastKeptAt === null || lastKeptAt - frame.at >= opts.keyframeMs) {
+      kept.push(frame);
+      lastKeptAt = frame.at;
+    } else {
+      drop(frame.seq);
+    }
+  }
+  return kept.reverse();
+}
+
+/**
+ * Re-encode frames that have aged out of the fine window at a smaller size.
+ * Done in-process with the bundled PNG codec, so recall stays cheap on disk
+ * without adding a dependency or another process spawn per frame.
+ */
+function shrinkAgedFrames(dir, index, now, opts, log) {
+  for (const frame of index) {
+    if (frame.small || now - frame.at <= opts.fineMs) continue;
+    const file = path.join(dir, `${frame.seq}.png`);
+    try {
+      const bmp = decodePng(fs.readFileSync(file));
+      const small = scaleBitmap(
+        bmp,
+        Math.max(1, Math.round(bmp.width * opts.recallScale)),
+        Math.max(1, Math.round(bmp.height * opts.recallScale)),
+      );
+      store.writeAtomic(file, encodePng(small));
+      frame.small = true;
+    } catch (err) {
+      // A frame we cannot shrink is still a frame we can serve.
+      frame.small = true;
+      log?.(`shrink failed for #${frame.seq}: ${err.message}`);
+    }
+  }
+}
+
+/** Last-resort cap so a long session cannot grow the buffer without bound. */
+function enforceByteBudget(dir, index, opts) {
+  let total = 0;
+  const sizes = index.map((frame) => {
+    let size = 0;
+    try {
+      size = fs.statSync(path.join(dir, `${frame.seq}.png`)).size;
+    } catch {
+      /* counted as zero */
+    }
+    total += size;
+    return size;
+  });
+  for (let i = 0; i < index.length && total > opts.maxRingBytes; i++) {
+    try {
+      fs.unlinkSync(path.join(dir, `${index[i].seq}.png`));
+      total -= sizes[i];
+      index[i].dropped = true;
+    } catch {
+      /* already gone */
+    }
+  }
+  for (let i = index.length - 1; i >= 0; i--) if (index[i].dropped) index.splice(i, 1);
+}

package/src/index.js

@@ -5,8 +5,16 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEFAULTS, STATE_VERSION } from './daemon.js';
 import { decodePng, encodePng, scaleBitmap } from './png.js';
-import { REGION_COLS, regionMap } from './analyze.js';
-import { resolveDevice, resize } from './simctl.js';
+import {
+  REGION_COLS,
+  hexToSignature,
+  regionDeltas,
+  regionMap,
+  signatureDiff,
+} from './analyze.js';
+import * as input from './input.js';
+import * as screenmap from './screenmap.js';
+import { resolveDevice, resize, screenshot } from './simctl.js';
 import * as store from './store.js';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -21,6 +29,39 @@ export function resolveMaxDim(detail) {
   return DETAIL_LEVELS.normal;
 }
 
+/**
+ * A full-resolution frame to read text from. The capture loop prunes these
+ * aggressively, so by the time a caller wants one it is often already gone —
+ * in which case take a fresh shot rather than silently skipping OCR.
+ */
+async function fullFrameFor(udid, state) {
+  if (state.fullFile && fs.existsSync(state.fullFile)) return state.fullFile;
+  const p = store.paths(udid);
+  const file = path.join(p.dir, 'ocr-source.png');
+  await screenshot(udid, file, { mask: 'ignored' });
+  return file;
+}
+
+/**
+ * Points-per-pixel and screen size for this device. idb reports both exactly;
+ * without it, fall back to the captured frame's aspect and a 3x guess, which is
+ * only used for OCR coordinates that nothing can tap anyway.
+ */
+async function deviceGeometry(udid, state) {
+  try {
+    const geo = await input.screenInfo(udid);
+    if (geo.pointWidth && geo.pointHeight) return geo;
+  } catch {
+    /* idb absent: fall through */
+  }
+  const density = 3;
+  return {
+    density,
+    pointWidth: Math.round((state.width * (state.nativeScale ?? 1)) / 1) || 402,
+    pointHeight: Math.round((state.height * (state.nativeScale ?? 1)) / 1) || 874,
+  };
+}
+
 export function daemonStatus(udid) {
   const meta = store.readJson(store.paths(udid).meta);
   const pid = meta?.pid ?? null;
@@ -120,9 +161,100 @@ function readLogTail(file, lines = 6) {
   return safeRead(file).trim().split('\n').slice(-lines).join('\n');
 }
 
-export function stopDaemon(udid) {
+/** A frame this old means the capture loop is wedged, not that the screen is calm. */
+export const STALE_FRAME_MS = 2500;
+
+/** Below this a "change" is a clock digit or a caret, not a new screen. */
+export const MINOR_CHANGE = 0.004;
+export const MAJOR_CHANGE = 0.03;
+
+export function changeLevel(diff) {
+  if (diff > MAJOR_CHANGE) return 'major';
+  if (diff > MINOR_CHANGE) return 'minor';
+  return 'none';
+}
+
+export function liveness(udid, state) {
+  const ageMs = Date.now() - state.capturedAt;
+  const { running } = daemonStatus(udid);
+  if (!running) {
+    return { ok: false, ageMs, note: 'the capture loop has died; the frame you are looking at is the last one it wrote' };
+  }
+  if (ageMs > STALE_FRAME_MS) {
+    return { ok: false, ageMs, note: `capture loop is stalled: newest frame is ${ageMs}ms old` };
+  }
+  return { ok: true, ageMs, note: null };
+}
+
+/**
+ * Find the frame a caller is diffing against. `since` may be a frame hash, a
+ * sequence number, or a millisecond timestamp. Baselines older than the history
+ * window fall back to a coarse answer derived from lastChangeAt, which is still
+ * correct about *whether* anything changed.
+ */
+export function resolveBaseline(state, since) {
+  if (since == null) return null;
+  const history = state.history || [];
+  const key = String(since);
+  let entry = null;
+  for (let i = history.length - 1; i >= 0; i--) {
+    const h = history[i];
+    if (h.hash === key || String(h.seq) === key) {
+      entry = h;
+      break;
+    }
+  }
+  if (entry) return { kind: 'history', entry };
+
+  const at = Number(since);
+  if (Number.isFinite(at) && at > 1e12) {
+    return { kind: 'coarse', at, changed: (state.lastChangeAt ?? 0) > at };
+  }
+  return { kind: 'unmatched', requested: key };
+}
+
+function compareToBaseline(state, baseline) {
+  if (!baseline) return null;
+  if (baseline.kind === 'history') {
+    const from = hexToSignature(baseline.entry.sig);
+    const to = hexToSignature(
+      (state.history || []).find((h) => h.seq === state.seq)?.sig || '',
+    );
+    if (!to.length) return { kind: 'unmatched', requested: String(baseline.entry.seq) };
+    const diff = signatureDiff(to, from);
+    const deltas = regionDeltas(to, from);
+    return {
+      kind: 'history',
+      matched: true,
+      seq: baseline.entry.seq,
+      hash: baseline.entry.hash,
+      at: baseline.entry.at,
+      ageMs: Date.now() - baseline.entry.at,
+      changed: diff > MINOR_CHANGE,
+      level: changeLevel(diff),
+      diff: Number(diff.toFixed(5)),
+      regions: deltas.map((d) => Number(d.toFixed(4))),
+      map: regionMap(deltas, REGION_COLS),
+    };
+  }
+  if (baseline.kind === 'coarse') {
+    return {
+      kind: 'coarse',
+      matched: false,
+      at: baseline.at,
+      ageMs: Date.now() - baseline.at,
+      changed: baseline.changed,
+      note: 'baseline is older than the buffered history; only whether-it-changed is known',
+    };
+  }
+  return { kind: 'unmatched', matched: false, requested: baseline.requested };
+}
+
+export function stopDaemon(udid, { force = false } = {}) {
   const { pid, running } = daemonStatus(udid);
   if (!running) return false;
+  // Another client may be mid-session on this device; do not yank it away.
+  if (!force && store.heartbeatAge(udid) < 60_000) return 'in-use';
   try {
     process.kill(pid, 'SIGTERM');
     return true;
@@ -171,13 +303,15 @@ function pngSize(png) {
   return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
 }
 
-export async function getState(deviceQuery, { options } = {}) {
+export async function getState(deviceQuery, { since, options } = {}) {
   const { device, state } = await ensureDaemon(deviceQuery, options);
   return {
     device,
     state,
     ageMs: Date.now() - state.capturedAt,
     map: regionMap(state.regions || [], REGION_COLS),
+    since: compareToBaseline(state, resolveBaseline(state, since)),
+    live: liveness(device.udid, state),
   };
 }
 
@@ -185,29 +319,86 @@ export async function getState(deviceQuery, { options } = {}) {
  * Wait for the screen to settle (`mode: 'stable'`) or to move away from what it
  * shows right now (`mode: 'change'`). Removes the screenshot-retry loop.
  */
+/**
+ * Wait for the screen to do something.
+ *
+ *   change  the screen differs from `since` (or from now, if no baseline)
+ *   stable  the screen holds still for `stableMs`, observed within this call
+ *   settle  change first, then stable — what you want after a tap or a launch
+ *
+ * Pass `since` (a hash captured BEFORE the action) whenever you can: a baseline
+ * sampled after the fact is the single most common way to wait for a change
+ * that has already happened.
+ */
 export async function waitFor(
   deviceQuery,
-  { mode = 'stable', stableMs = 600, timeoutMs = 8000, baselineHash, options } = {},
+  { mode = 'settle', since, stableMs = 600, timeoutMs = 8000, reactionMs = 2500, baselineHash, options } = {},
 ) {
   const { device, state: first } = await ensureDaemon(deviceQuery, options);
   const p = store.paths(device.udid);
-  const baseline = baselineHash || first.hash;
-  const deadline = Date.now() + timeoutMs;
+  const requested = since ?? baselineHash;
+  const resolved = resolveBaseline(first, requested);
+  const baselineHashValue =
+    resolved?.kind === 'history' ? resolved.entry.hash : (requested ?? first.hash);
+  const baselineResolved = resolved?.kind === 'history' || requested == null;
+
+  const startedAt = Date.now();
+  const deadline = startedAt + timeoutMs;
+  const startSeq = first.seq;
   let last = first;
+  let sawChange = mode === 'stable' || first.hash !== baselineHashValue;
+  const changedAtStart = sawChange && mode !== 'stable';
+
+  const done = (satisfied, extra = {}) => ({
+    device,
+    state: last,
+    satisfied,
+    mode,
+    sawChange,
+    changedBeforeWait: changedAtStart,
+    baselineHash: baselineHashValue,
+    baselineResolved,
+    waitedMs: Date.now() - startedAt,
+    live: liveness(device.udid, last),
+    ...extra,
+  });
 
   while (Date.now() < deadline) {
     const state = store.readJson(p.state);
     if (state) {
       last = state;
+      // A wedged capture loop must not look like a calm screen.
+      const live = liveness(device.udid, state);
+      if (!live.ok) return done(false, { stalled: true });
+
+      if (!sawChange && state.hash !== baselineHashValue) sawChange = true;
+
+      // Some controls barely move the screen at all — a radio dot, a checkbox,
+      // a button changing state. Waiting the full timeout for a change that
+      // will never be visible turns a 100ms action into a 12s one, so give up
+      // early and say so, rather than silently burning the clock.
+      if (!sawChange && Date.now() - startedAt > reactionMs && state.stableForMs >= stableMs) {
+        return done(false, { noVisibleChange: true });
+      }
+
       if (mode === 'change') {
-        if (state.hash !== baseline) return { device, state, satisfied: true, mode, waitedMs: timeoutMs - (deadline - Date.now()) };
-      } else if (state.stableForMs >= stableMs) {
-        return { device, state, satisfied: true, mode, waitedMs: timeoutMs - (deadline - Date.now()) };
+        if (sawChange) return done(true);
+      } else {
+        // "settle" requires a change first, so accumulated stillness from before
+        // the caller acted can never satisfy it; once the change is seen,
+        // stableForMs is measured from that change. Plain "stable" has no such
+        // requirement — an already-still screen genuinely is stable.
+        // At least one frame must arrive during the call, so the answer is
+        // never derived purely from what was already on disk.
+        const freshFrames = state.seq - startSeq;
+        if (sawChange && freshFrames >= 1 && state.stableForMs >= stableMs) {
+          return done(true);
+        }
       }
     }
     await sleep(60);
   }
-  return { device, state: last, satisfied: false, mode, waitedMs: timeoutMs };
+  return done(false, { timedOut: true });
 }
 
 /**
@@ -224,13 +415,24 @@ export async function getStrip(deviceQuery, { count = 5, spanMs, thumbMaxDim = 2
     .filter((e) => Number.isFinite(e.seq))
     .sort((a, b) => a.seq - b.seq);
 
-  entries = entries.map((e) => ({ ...e, mtimeMs: safeMtime(e.file) })).filter((e) => e.mtimeMs);
+  const stamps = new Map(((await ensureDaemon(deviceQuery, options)).state.ring || []).map((f) => [f.seq, f.at]));
+  entries = entries
+    .map((e) => ({ ...e, mtimeMs: stamps.get(e.seq) ?? safeMtime(e.file) }))
+    .filter((e) => e.mtimeMs);
+  const want = Math.max(1, count);
   if (spanMs) {
+    // "Show me the last 40 seconds" means frames spread ACROSS that window, not
+    // the newest few frames that happen to fall inside it.
     const cutoff = Date.now() - spanMs;
     const within = entries.filter((e) => e.mtimeMs >= cutoff);
-    if (within.length) entries = within;
+    if (within.length) {
+      entries = within.length <= want ? within : spreadEvenly(within, want);
+    } else {
+      entries = entries.slice(-want);
+    }
+  } else {
+    entries = entries.slice(-want);
   }
-  entries = entries.slice(-Math.max(1, count));
   if (!entries.length) throw new Error('no frames buffered yet');
 
   const frames = entries.map((e) => decodePng(fs.readFileSync(e.file)));
@@ -260,6 +462,17 @@ export async function getStrip(deviceQuery, { count = 5, spanMs, thumbMaxDim = 2
   };
 }
 
+/** Pick `count` items spaced as evenly as possible across a list, keeping the ends. */
+export function spreadEvenly(items, count) {
+  if (count >= items.length) return items;
+  if (count === 1) return [items[items.length - 1]];
+  const out = [];
+  for (let i = 0; i < count; i++) {
+    out.push(items[Math.round((i * (items.length - 1)) / (count - 1))]);
+  }
+  return out;
+}
+
 function safeMtime(file) {
   try {
     return fs.statSync(file).mtimeMs;
@@ -268,4 +481,158 @@ function safeMtime(file) {
   }
 }
 
-export { DEFAULTS, store };
+/**
+ * What happened on screen over the last `spanMs`, derived from the buffered
+ * frame signatures. This is the "memory" view: not every frame, but the events
+ * worth knowing about, each with when it started, how long it took and how much
+ * of the screen it moved.
+ */
+export async function getTimeline(deviceQuery, { spanMs = 60_000, options } = {}) {
+  const { device, state } = await ensureDaemon(deviceQuery, options);
+  const now = Date.now();
+  const hist = (state.history || []).filter((h) => h.at >= now - spanMs);
+  const events = [];
+  let current = null;
+
+  hist.forEach((h, i) => {
+    if ((h.diff ?? 0) > MINOR_CHANGE) {
+      if (!current) {
+        const before = hist[i - 1] || h;
+        current = { startAt: before.at, fromSig: before.sig, endAt: h.at, frames: 1, peak: h.diff };
+      } else {
+        current.endAt = h.at;
+        current.frames += 1;
+        current.peak = Math.max(current.peak, h.diff);
+      }
+      current.toSig = h.sig;
+    } else if (current) {
+      current.endAt = h.at;
+      current.toSig = h.sig;
+      events.push(current);
+      current = null;
+    }
+  });
+  if (current) events.push(current);
+
+  const shaped = events.map((e) => {
+    const from = hexToSignature(e.fromSig || '');
+    const to = hexToSignature(e.toSig || '');
+    const magnitude = from.length && to.length ? signatureDiff(to, from) : e.peak;
+    const deltas = from.length && to.length ? regionDeltas(to, from) : [];
+    return {
+      startedMsAgo: now - e.startAt,
+      endedMsAgo: now - e.endAt,
+      durationMs: Math.max(0, e.endAt - e.startAt),
+      magnitude: Number(magnitude.toFixed(4)),
+      level: changeLevel(magnitude),
+      frames: e.frames,
+      map: deltas.length ? regionMap(deltas, REGION_COLS) : null,
+    };
+  });
+
+  return {
+    device,
+    state,
+    spanMs,
+    coveredMs: hist.length ? now - hist[0].at : 0,
+    frames: hist.length,
+    buffered: (state.ring || []).length,
+    events: shaped,
+    idleForMs: state.stableForMs,
+    live: liveness(device.udid, state),
+  };
+}
+
+/** The buffered frame closest to a moment in the past. */
+export async function getFrameAt(deviceQuery, { msAgo = 0, options } = {}) {
+  const { device, state } = await ensureDaemon(deviceQuery, options);
+  const ring = state.ring || [];
+  if (!ring.length) throw new Error('no frames buffered yet');
+  const target = Date.now() - msAgo;
+  let best = ring[0];
+  for (const frame of ring) {
+    if (Math.abs(frame.at - target) < Math.abs(best.at - target)) best = frame;
+  }
+  const file = path.join(store.paths(device.udid).ring, `${best.seq}.png`);
+  if (!fs.existsSync(file)) throw new Error(`frame #${best.seq} is no longer buffered`);
+  const png = fs.readFileSync(file);
+  return {
+    device,
+    state,
+    png,
+    seq: best.seq,
+    at: best.at,
+    actualMsAgo: Date.now() - best.at,
+    requestedMsAgo: msAgo,
+    width: png.readUInt32BE(16),
+    height: png.readUInt32BE(20),
+    oldestMsAgo: Date.now() - ring[0].at,
+  };
+}
+
+/**
+ * Find where to tap for a label on the screen showing right now.
+ *
+ * Familiar screens answer from memory: no accessibility read, no OCR, no image.
+ * A screen seen for the first time pays once to build its map, and every later
+ * visit is a file read.
+ */
+export async function locate(deviceQuery, query, { index, refresh = false, useAx = true, useOcr = true, options } = {}) {
+  const { device, state } = await ensureDaemon(deviceQuery, options);
+  const udid = device.udid;
+  let entry = null;
+  let from = 'memory';
+  let distance = 0;
+
+  if (!refresh) {
+    const near = screenmap.recallNearest(udid, state.layoutHash);
+    if (near) {
+      entry = near.entry;
+      distance = near.distance;
+    }
+  }
+
+  if (!entry) {
+    const geo = await deviceGeometry(udid, state);
+    entry = await screenmap.build(udid, {
+      hash: state.hash,
+      layoutHash: state.layoutHash,
+      fullFrame: await fullFrameFor(udid, state),
+      density: geo.density,
+      screen: { width: geo.pointWidth, height: geo.pointHeight },
+      useAx,
+      useOcr,
+    });
+    from = 'built';
+  }
+
+  const candidates = screenmap.rank(entry, query);
+  if (candidates.length > 1 && index == null) {
+    const top = candidates[0];
+    const second = candidates[1];
+    const decisive = screenmap.isInteractive(top) && !screenmap.isInteractive(second);
+    if (!decisive) {
+      const list = candidates
+        .slice(0, 6)
+        .map((t, i) => `[${i}] "${t.label}" (${t.x},${t.y}) ${t.type}/${t.source}`)
+        .join(', ');
+      throw new Error(
+        `"${query}" matches ${candidates.length} things on this screen — pass index to choose: ${list}`,
+      );
+    }
+  }
+  const target = index != null ? candidates[index] : candidates[0];
+  if (!target) {
+    const sample = entry.targets
+      .filter((t) => t.label)
+      .slice(0, 12)
+      .map((t) => t.label)
+      .join(', ');
+    throw new Error(
+      `"${query}" is not on this screen. Visible: ${sample || '(nothing readable)'}`,
+    );
+  }
+  return { device, state, entry, target, from, distance, screens: screenmap.stats(udid).screens };
+}
+
+export { DEFAULTS, screenmap, store };