simframe 0.4.2 → 0.6.0-rc.1

package/src/screenmap.js

@@ -8,11 +8,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { hashDistance } from './analyze.js';
+import * as control from './control.js';
+import * as fingerprint from './fingerprint.js';
 import * as input from './input.js';
 import * as ocr from './ocr.js';
+import * as regions from './regions.js';
 import * as store from './store.js';
 
-const MAP_VERSION = 2; // layout hash crop changed; old maps no longer comparable
+const MAP_VERSION = 6; // dates, prices and phone numbers no longer contribute labels
 
 function mapDir(udid) {
   return path.join(store.deviceDir(udid), 'screens');
@@ -20,11 +23,18 @@ function mapDir(udid) {
 
 /**
  * How many of the 288 layout bits may differ and still count as the same screen.
- * Measured on a real app: revisiting a screen (with different list rows and a
- * different clock) moved 0-3 bits; different screens were 77-96 apart. 12 sits
- * well clear of both.
+ *
+ * Re-measured across four visits to each of five screens: a revisit is usually
+ * identical (median 0) but the tail reaches 62 when list content has changed,
+ * while different screens sit at 74 and above. That margin is much narrower
+ * than the first calibration suggested, and it is the reason this number stays
+ * conservative rather than being raised to cover the tail.
+ *
+ * The consequence is deliberate: a heavily changed screen is rebuilt rather
+ * than recognised. A rebuild costs ~300ms; a false match taps the wrong
+ * control. See docs/DEFERRED.md on fingerprinting structure instead of pixels.
  */
-export const DEFAULT_TOLERANCE = 12;
+export const DEFAULT_TOLERANCE = 20;
 
 export function recall(udid, hash) {
   if (!hash) return null;
@@ -104,16 +114,47 @@ export async function build(udid, {
   density = 3,
   useAx = true,
   useOcr = true,
+  persist = true,
   screen,
 } = {}) {
   const targets = [];
   const sources = [];
-  // Kick OCR off before reading the tree: they are independent, and the OCR
-  // pass is pure computation on a file that already exists.
-  const ocrPromise =
-    useOcr && fullFrame && fs.existsSync(fullFrame)
+  // Why a layer is missing, kept rather than swallowed.
+  //
+  // A partial map used to be indistinguishable from a whole one: `sources` said
+  // ["ax"] and nothing said why OCR was not there. On CI this produced a map
+  // with zero elements reported as a successful read, and the only way to find
+  // out what had happened was to guess. Before the tree came in-process the
+  // same failure was loud, because with no idb the ax layer failed too and an
+  // empty `sources` rethrew — so making a layer work turned a loud failure into
+  // a quiet one.
+  const degraded = [];
+  // One round trip for both, because the daemon runs the tree read and the
+  // recognition pass concurrently against the same instant of the screen. Asked
+  // separately they would queue: the control socket serves one request at a
+  // time, so a second call pays the first one's latency before it starts.
+  //
+  // The daemon reads text straight off the framebuffer. The fallback encodes a
+  // PNG, writes it, spawns a helper and decodes it again — measured at 555ms
+  // against 174ms — so it is only used when no daemon is listening.
+  const viaDaemon = (useOcr || useAx) && control.available(udid);
+  const axViaDaemon = useAx && process.env.SIMFRAME_AX_DRIVER !== 'idb';
+  const daemonPromise = viaDaemon
+    ? control.request(udid, { action: 'ui', ax: axViaDaemon, ocr: useOcr }).catch((err) => err)
+    : null;
+  const ocrPromise = !useOcr || viaDaemon
+    ? null
+    : fullFrame && fs.existsSync(fullFrame)
       ? ocr.readText(fullFrame, { density }).catch((err) => err)
       : null;
+  const daemonAnswer = daemonPromise ? await daemonPromise : null;
+  // Keep the failure rather than flattening it to null. A daemon that was
+  // listening and then did not answer is a loud failure, and the version of
+  // this that dropped it returned an empty map with no error — which `persist`
+  // then wrote into screen memory, so a later warm visit read the emptiness
+  // back instead of perceiving the screen again.
+  const daemonError = daemonAnswer instanceof Error ? daemonAnswer : null;
+  const daemonScreen = daemonError ? null : daemonAnswer?.screen ?? null;
   // With no geometry, treat every element as a potential control rather than
   // guessing a screen size and mis-classifying containers.
   const screenArea = screen?.width && screen?.height ? screen.width * screen.height : Infinity;
@@ -125,7 +166,12 @@ export async function build(udid, {
 
   if (useAx) {
     try {
-      const nodes = await input.describeAll(udid);
+      // The tree is already in hand when the daemon answered; describeAll would
+      // only ask for it a second time.
+      const nodes = daemonScreen?.sources?.includes('ax')
+        ? daemonScreen.elements.filter((e) => e.source?.includes('ax')).map(input.elementToNode)
+        : await input.describeAll(udid);
+
       sources.push('ax');
       for (const n of nodes) {
         if (!n.frame || !n.label || isContainer(n)) continue;
@@ -139,15 +185,40 @@ export async function build(udid, {
           source: 'ax',
         });
       }
-    } catch {
+    } catch (err) {
       /* no idb, or the tree read failed; OCR alone is still useful */
+      degraded.push(`accessibility: ${err.message}`);
     }
   }
 
-  if (ocrPromise) {
+  // Neither layer was even attempted: nothing below can report the failure, so
+  // it has to be reported here rather than returned as an empty screen.
+  if (daemonError && !useOcr) throw daemonError;
+
+  if (ocrPromise || (useOcr && viaDaemon)) {
     try {
-      const words = await ocrPromise;
-      if (words instanceof Error) throw words;
+      const result = ocrPromise ? await ocrPromise : (daemonError ?? daemonScreen);
+      if (result instanceof Error) throw result;
+      if (!result) throw new Error('the daemon did not answer');
+      // A daemon that answered without reading text is not an OCR source, and
+      // saying it was would claim the screen had been read when it had not.
+      if (viaDaemon && !result.sources?.includes('ocr')) throw new Error(result.ocrError ?? 'no text was read');
+      // The daemon answers in points; readText answers in points too, having
+      // divided by density. Normalise the daemon's element shape to match.
+      const words = viaDaemon
+        ? (result.elements ?? [])
+            .filter((e) => e.source?.includes('ocr') && e.label?.trim())
+            .map((e) => ({
+              text: e.label,
+              confidence: e.confidence,
+              x: e.frame.x,
+              y: e.frame.y,
+              width: e.frame.width,
+              height: e.frame.height,
+              centerX: e.center.x,
+              centerY: e.center.y,
+            }))
+        : result;
       sources.push('ocr');
       for (const w of words) {
         if (!w.text.trim()) continue;
@@ -183,18 +254,44 @@ export async function build(udid, {
         });
       }
     } catch (err) {
+      degraded.push(`text recognition: ${err.message}`);
       if (!sources.length) throw err;
     }
   }
 
-  return remember(udid, {
-    version: MAP_VERSION,
-    hash,
-    layoutHash,
-    at: Date.now(),
-    sources,
-    targets,
-  });
+  return finish();
+
+  function finish() {
+    // Region priors are geometry, so they cost nothing and disambiguate a great
+    // deal: "Assets" the nav title and "Assets" the tab differ only by where
+    // they are.
+    if (screen?.width && screen?.height) regions.annotate(targets, screen);
+    // Two hashes, two jobs. The pixel layout hash indexes this entry, because
+    // it can be computed from a frame alone and so can find a map without
+    // building one. The structural hash identifies the screen, because content
+    // is pixels and a list with new rows is not a new screen.
+    const structure = screen?.width && screen?.height
+      ? fingerprint.fingerprint(targets, screen)
+      : { hash: null, tokens: [], keyboard: false };
+    const entry = {
+      version: MAP_VERSION,
+      hash,
+      layoutHash,
+      structuralHash: structure.hash,
+      structuralTokens: structure.tokens,
+      keyboard: structure.keyboard,
+      at: Date.now(),
+      sources,
+      targets,
+    };
+    // A truncated tree is nodes without authority; the daemon says so and the
+    // map has to carry it, because this is what gets written into memory.
+    if (daemonScreen?.axTruncated) degraded.push(`accessibility tree cut short: ${daemonScreen.axTruncated}`);
+    if (degraded.length) entry.degraded = degraded;
+    // Only a map of a settled screen is worth keeping; remembering a transition
+    // fills the store with layouts that will never be seen again.
+    return persist ? remember(udid, entry) : entry;
+  }
 }
 
 const norm = (s) => String(s ?? '').toLowerCase().trim();

package/src/simctl.js

@@ -96,9 +96,17 @@ export function isBootedSync(udid) {
 }
 
 export async function screenshot(udid, outFile, { mask = 'ignored' } = {}) {
-  await run('xcrun', ['simctl', 'io', udid, 'screenshot', '--type=png', `--mask=${mask}`, outFile], {
-    timeout: 10_000,
-  });
+  try {
+    await run('xcrun', ['simctl', 'io', udid, 'screenshot', '--type=png', `--mask=${mask}`, outFile], {
+      timeout: 10_000,
+    });
+  } catch (err) {
+    // Same reason as launchApp: execFile's message is "Command failed: <the
+    // whole command>" and simctl's actual complaint is in stderr. A CI failure
+    // here reported the command and nothing about why it did not work.
+    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
+    throw new Error(detail ? `simctl screenshot failed: ${detail}` : `simctl screenshot failed: ${err.message}`);
+  }
 }
 
 /** Resample with sips, which ships with macOS, so simframe needs no image deps. */
@@ -106,8 +114,38 @@ export async function resize(inFile, outFile, maxDim) {
   await run('sips', ['-Z', String(maxDim), inFile, '--out', outFile], { timeout: 10_000 });
 }
 
-export async function launchApp(udid, bundleId) {
-  await run('xcrun', ['simctl', 'launch', udid, bundleId], { timeout: 20_000 });
+/**
+ * Launch, optionally with arguments and environment.
+ *
+ * simctl passes launch arguments after the bundle id and environment through
+ * `SIMCTL_CHILD_`-prefixed variables of its own process — which is why env has
+ * to be set on the child rather than passed as flags.
+ */
+export async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst = false } = {}) {
+  if (terminateFirst) {
+    // A launch against an already-running app is a no-op that reports success,
+    // which is how a flow "relaunched" an app and tested the screen it was
+    // already on.
+    try {
+      await terminateApp(udid, bundleId);
+    } catch {
+      /* not running; that is the state we wanted */
+    }
+  }
+  const childEnv = { ...process.env };
+  for (const [k, v] of Object.entries(env)) childEnv[`SIMCTL_CHILD_${k}`] = String(v);
+  try {
+    await run('xcrun', ['simctl', 'launch', udid, bundleId, ...args.map(String)], {
+      timeout: 20_000,
+      env: childEnv,
+    });
+  } catch (err) {
+    // execFile's message is just "Command failed: ..." with simctl's actual
+    // complaint left in stderr. A CI run failed here and said nothing about
+    // why, which is the same sin as a silent fallback.
+    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
+    throw new Error(detail ? `could not launch ${bundleId}: ${detail}` : `could not launch ${bundleId}: ${err.message}`);
+  }
 }
 
 export async function terminateApp(udid, bundleId) {
@@ -118,6 +156,37 @@ export async function openUrl(udid, url) {
   await run('xcrun', ['simctl', 'openurl', udid, url], { timeout: 20_000 });
 }
 
+export const PERMISSION_SERVICES = [
+  'all', 'calendar', 'contacts-limited', 'contacts', 'location', 'location-always',
+  'photos-add', 'photos', 'media-library', 'microphone', 'motion', 'reminders', 'siri',
+];
+
+/**
+ * Grant, revoke or reset a privacy permission.
+ *
+ * The point of doing this from a test harness is that the alternative is
+ * tapping a system alert, and a system alert is not part of the app under test:
+ * its buttons move between iOS versions and its appearance is a race.
+ */
+export async function setPermission(udid, action, service, bundleId) {
+  const verb = String(action).toLowerCase();
+  if (!['grant', 'revoke', 'reset'].includes(verb)) {
+    throw new Error(`permission action must be grant, revoke or reset (got "${action}")`);
+  }
+  if (!PERMISSION_SERVICES.includes(service)) {
+    throw new Error(`unknown permission "${service}" — one of: ${PERMISSION_SERVICES.join(', ')}`);
+  }
+  const args = ['simctl', 'privacy', udid, verb, service];
+  if (bundleId) args.push(bundleId);
+  try {
+    await run('xcrun', args, { timeout: 20_000 });
+  } catch (err) {
+    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
+    throw new Error(`could not ${verb} ${service}: ${detail || err.message}`);
+  }
+  return `${verb === 'reset' ? 'reset' : verb + 'ed'} ${service}${bundleId ? ` for ${bundleId}` : ''}`;
+}
+
 /** Put text on the device pasteboard — far faster than typing a long string. */
 export async function setPasteboard(udid, value) {
   const child = execFile('xcrun', ['simctl', 'pbcopy', udid], { timeout: 10_000 });

package/src/store.js

@@ -5,6 +5,14 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+/**
+ * A directory under ROOT is a device only if it is named like a UDID.
+ *
+ * `simframe status` listed five phantom `? ` rows once, which were test
+ * fixtures. Anything that is not a UDID is not a device, whoever wrote it.
+ */
+export const isUdid = (name) => /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i.test(name);
+
 export const ROOT = process.env.SIMFRAME_HOME || path.join(os.homedir(), '.simframe');
 
 export function deviceDir(udid) {

package/src/view.js

@@ -0,0 +1,342 @@
+// What Claude sees.
+//
+// Every action used to answer with an image. An image costs 1,600 tokens when
+// Claude Code handles it natively and 15,000–25,000 when it does not, and it
+// answers the one question the tool already knew: what is on the screen and
+// what can be tapped. This module answers that in text, with a number in front
+// of every element so the next call can name one without describing it.
+//
+// The format is deliberately dense. Region first, because "Assets" the nav
+// title and "Assets" the tab differ only by where they are; a tap point,
+// because that is what an action needs; and the source, because an element the
+// app published and one OCR read off the pixels deserve different amounts of
+// trust.
+import * as api from './index.js';
+import * as graph from './graph.js';
+import { writeRefs } from './refs.js';
+
+/** Reading order. Chrome frames the screen, so it reads first and last. */
+const REGION_ORDER = ['nav-bar', 'content', 'tab-bar', 'keyboard', 'status-bar'];
+
+/**
+ * The status bar says the time and the battery level. It is on every screen,
+ * it is never what anybody wants to tap, and it costs a row every time.
+ */
+const HIDDEN_REGIONS = new Set(['status-bar']);
+
+/** A keyboard is 30-odd keys nobody refers to by name. One line says it. */
+const COLLAPSE_REGIONS = new Set(['keyboard']);
+
+/** Past this many rows the map stops being cheaper than looking. */
+export const DEFAULT_LIMIT = 60;
+
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+/** Types that are hit targets rather than description. */
+const INTERACTIVE = /button|field|cell|link|switch|slider|tab|menu|segment|checkbox/i;
+
+/** A label past this length is a paragraph, and no selector needs a paragraph. */
+const MAX_LABEL = 64;
+
+/** Anything covering more of the screen than this is scenery, not a control. */
+const CONTAINER_AREA_FRACTION = 0.35;
+
+const area = (f) => (f ? Math.max(1, f.width) * Math.max(1, f.height) : 0);
+
+const centerInside = (t, f) =>
+  Boolean(f) && t.x >= f.x && t.x <= f.x + f.width && t.y >= f.y && t.y <= f.y + f.height;
+
+/**
+ * Fold read text into the control it is printed on.
+ *
+ * The screen map keeps an accessibility element and the text OCR read off it as
+ * separate targets, deliberately: identity is computed from that list and
+ * throwing away a target would change what a screen is. But as something to
+ * show a model it is nearly twice as long as it needs to be — "TRACK TIME" the
+ * button and "TRACK TIME" the pixels are one thing to tap.
+ *
+ * So the folding happens here, in the presentation, and the fingerprint never
+ * sees it. The rule is containment plus interactivity: text sitting inside a
+ * button belongs to that button. Size is not part of it — that check exists in
+ * screenmap.build to stop a tab bar swallowing its five tabs, and a tab bar is
+ * not interactive.
+ */
+/**
+ * How many pieces of text one control may absorb.
+ *
+ * A control's visible text is a fragment or three: a title, a count, a unit. A
+ * container swallows five, and a tab bar that absorbed its own tabs would leave
+ * nothing to tap. This is what separates the two, because size does not: a
+ * dashboard tile and a tab bar are the same few thousand square points.
+ */
+const MAX_ABSORBED = 3;
+
+/** Could this be the thing the text is printed on? */
+function isHost(t) {
+  if (!t.frame) return false;
+  if (INTERACTIVE.test(t.type || '')) return true;
+  // An accessibility element the app gave a label to is a unit the app itself
+  // considers one thing — a dashboard tile reading "WOs past ETA, 1910" is one
+  // tap target whose parts OCR happens to read separately.
+  return t.source === 'ax' && Boolean(t.label);
+}
+
+/**
+ * Fold read text into the control it is printed on.
+ *
+ * The screen map keeps an accessibility element and the text OCR read off it as
+ * separate targets, deliberately: identity is computed from that list and
+ * dropping a target would change what a screen is. But as something to show a
+ * model it is nearly twice as long as it needs to be — "TRACK TIME" the button
+ * and "TRACK TIME" the pixels are one thing to tap.
+ *
+ * So the folding happens here, in the presentation, and the fingerprint never
+ * sees it.
+ */
+function foldText(targets) {
+  const hosts = targets.filter(isHost);
+  // Who would absorb what, before absorbing anything: a host that turns out to
+  // be a container must not have already eaten two of its children.
+  const claims = new Map(hosts.map((h) => [h, []]));
+  for (const t of targets) {
+    if (isHost(t)) continue;
+    const host = hosts
+      .filter((h) => centerInside(t, h.frame))
+      .sort((a, b) => area(a.frame) - area(b.frame))[0];
+    if (host) claims.get(host).push(t);
+  }
+
+  const absorbed = new Set();
+  for (const [host, texts] of claims) {
+    if (!texts.length || texts.length > MAX_ABSORBED) continue;
+    for (const t of texts) {
+      absorbed.add(t);
+      const text = String(t.label ?? '').trim();
+      if (text && !saysTheSame(host, text)) host.aliases = [...(host.aliases ?? []), text];
+    }
+  }
+  return targets.filter((t) => !absorbed.has(t));
+}
+
+/** Comparison that ignores what OCR adds: a stray bullet, a mangled glyph. */
+const alnum = (s_) => String(s_ ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
+
+function saysTheSame(host, text) {
+  const t = alnum(text);
+  if (!t) return true;
+  return [host.label, ...(host.aliases ?? [])]
+    .filter(Boolean)
+    .some((known) => alnum(known).includes(t));
+}
+
+/**
+ * Drop the scenery.
+ *
+ * A group that encloses several other elements is the thing they are arranged
+ * in, not a thing anybody means to tap — and it is exactly what "tap the tab
+ * bar" would resolve to if it were listed.
+ */
+function dropContainers(targets, screen) {
+  const screenArea = screen?.width && screen?.height ? screen.width * screen.height : Infinity;
+  return targets.filter((t) => {
+    if (!t.frame) return true;
+    if (INTERACTIVE.test(t.type || '')) return true;
+    if (area(t.frame) > screenArea * CONTAINER_AREA_FRACTION) return false;
+    const encloses = targets.filter((o) => o !== t && centerInside(o, t.frame)).length;
+    return encloses < 2;
+  });
+}
+
+/**
+ * Text with no letters or digits in it is OCR reading the furniture: a divider,
+ * an ellipsis menu, a chevron it decided was a period. Nothing can be tapped by
+ * that name, so listing it is pure cost.
+ */
+const isNoise = (t) => t.source === 'ocr' && !alnum(t.label);
+
+const trim = (text) => {
+  const one = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return one.length > MAX_LABEL ? `${one.slice(0, MAX_LABEL - 1)}…` : one;
+};
+
+/** Rank and number what is on screen. */
+export function rowsFor(entry, { screen, filter, interactive, all = false, limit = DEFAULT_LIMIT } = {}) {
+  let kept = (entry?.targets ?? []).map((t) => ({ ...t })).filter((t) => {
+    if (!isNum(t.x) || !isNum(t.y)) return false;
+    // Off-screen elements are real in the tree and untappable in fact.
+    if (screen?.height && (t.y < 0 || t.y > screen.height)) return false;
+    if (!all && HIDDEN_REGIONS.has(t.region)) return false;
+    if (!all && isNoise(t)) return false;
+    return true;
+  });
+
+  if (!all) {
+    kept = foldText(kept);
+    kept = dropContainers(kept, screen);
+  }
+
+  if (filter) {
+    const q = String(filter).toLowerCase();
+    kept = kept.filter((t) =>
+      [t.label, ...(t.aliases ?? [])].filter(Boolean).join(' ').toLowerCase().includes(q));
+  }
+  if (interactive) kept = kept.filter((t) => INTERACTIVE.test(t.type || ''));
+
+  const order = (t) => {
+    const i = REGION_ORDER.indexOf(t.region ?? 'content');
+    return i === -1 ? REGION_ORDER.indexOf('content') : i;
+  };
+  kept.sort((a, b) => order(a) - order(b) || a.y - b.y || a.x - b.x);
+
+  const rows = [];
+  const collapsed = new Map();
+  for (const t of kept) {
+    const region = t.region ?? 'content';
+    if (COLLAPSE_REGIONS.has(region)) {
+      collapsed.set(region, (collapsed.get(region) ?? 0) + 1);
+      continue;
+    }
+    rows.push({ ...t, region, ref: rows.length + 1 });
+  }
+  return { rows: rows.slice(0, limit), truncated: Math.max(0, rows.length - limit), collapsed };
+}
+
+function renderRow(r) {
+  const name = [
+    trim(r.label) || (r.source === 'ax' ? '(unlabelled)' : '(no text)'),
+    aliasNote(r),
+  ].filter(Boolean).join(' ');
+  const state = [
+    r.enabled === false ? 'disabled' : null,
+    r.selected ? 'selected' : null,
+  ].filter(Boolean).join(',');
+  return [
+    `#${r.ref}`.padStart(4),
+    shortType(r.type).padEnd(9),
+    `${r.x},${r.y}`.padEnd(9),
+    state ? `${state} ` : '',
+    name,
+  ].join(' ');
+}
+
+/**
+ * Only aliases that say something the label does not.
+ *
+ * The screen map records OCR's reading of an element it already had a label
+ * for, which is useful when they disagree and pure cost when they agree —
+ * "WELCOME ~ WELCOME" was a third of some rows.
+ */
+function aliasNote(r) {
+  const extra = (r.aliases ?? [])
+    .filter((a) => {
+      const t = alnum(a);
+      return t && !alnum(r.label).includes(t);
+    })
+    .slice(0, 2);
+  return extra.length ? `~ ${trim(extra.join(' '))}` : null;
+}
+
+/**
+ * Element types, in as few characters as carry the meaning. iOS calls things
+ * `GenericElement` and `StaticText`; nothing is lost by calling them `element`
+ * and `text`, and a column of them costs a third as much.
+ */
+const TYPE_NAMES = [
+  [/textfield|textview|searchfield|field/i, 'field'],
+  [/button/i, 'button'],
+  [/statictext|^text$/i, 'text'],
+  [/cell|row/i, 'cell'],
+  [/^link$/i, 'link'],
+  [/switch|toggle/i, 'switch'],
+  [/tab/i, 'tab'],
+  [/image|icon/i, 'image'],
+  [/generic|other|group|^any$/i, 'element'],
+];
+
+function shortType(type) {
+  const t = String(type ?? '').trim();
+  if (!t) return '?';
+  for (const [pattern, name] of TYPE_NAMES) if (pattern.test(t)) return name;
+  return t.slice(0, 9).toLowerCase();
+}
+
+/**
+ * The whole map as text.
+ *
+ * One read of the screen produces the identity, the elements and the verdict,
+ * so this is the same cost as the `screenIdentity` call an action already makes
+ * to verify itself.
+ */
+export async function screenMap(deviceQuery, {
+  options,
+  filter,
+  interactive,
+  all = false,
+  limit = DEFAULT_LIMIT,
+  refresh = false,
+  identity: given,
+} = {}) {
+  // `refresh` rebuilds this screen's map; it does not wipe the device's memory.
+  // Forgetting everything to re-read one screen would throw away every other
+  // screen's muscle memory to answer a question about this one.
+  const identity = given ?? await api.screenIdentity(deviceQuery, { options, confirmNovel: false, fresh: refresh });
+  const { device } = await api.ensureDaemon(deviceQuery, options);
+  const udid = device.udid;
+  const entry = identity.entry;
+  const screen = identity.points;
+
+  const { rows, truncated, collapsed } = rowsFor(entry, { screen, filter, interactive, all, limit });
+  writeRefs(udid, { structuralHash: identity.hash, layoutHash: identity.layoutHash, rows });
+
+  const found = identity.hash ? graph.nearestScreen(udid, identity) : null;
+  const node = found?.node ?? null;
+  const name = node ? graph.describe(node) : null;
+  // Not a visit count — nothing stores one. The number of edges out of this
+  // screen is what the agent can actually use: it says how much of this screen
+  // the graph can navigate from without being told.
+  const exits = node ? node.edges.length : null;
+
+  return {
+    device,
+    identity,
+    rows,
+    truncated,
+    collapsed,
+    screen,
+    name,
+    exits,
+    text: render({ device, identity, rows, truncated, collapsed, screen, name, exits }),
+  };
+}
+
+export function render({ device, identity, rows, truncated, collapsed, screen, name, exits, verdictLine, ambiguities }) {
+  const head = [
+    device?.name,
+    screen?.width ? `${screen.width}x${screen.height}pt` : null,
+    identity?.hash
+      ? `screen ${identity.hash.slice(0, 8)}${name ? ` "${name}"` : ''}` +
+        (exits == null ? ' (new to simframe)' : ` (known, ${exits} known exit${exits === 1 ? '' : 's'})`)
+      : 'screen unidentified',
+    identity?.keyboard ? 'keyboard up' : null,
+    identity?.settled === false ? 'STILL MOVING' : null,
+  ].filter(Boolean).join(' · ');
+
+  const lines = [head];
+  if (verdictLine) lines.push(verdictLine);
+
+  let region = null;
+  for (const r of rows) {
+    if (r.region !== region) {
+      region = r.region;
+      lines.push(`${region}:`);
+    }
+    lines.push(renderRow(r));
+  }
+  for (const [name_, count] of collapsed ?? []) lines.push(`${name_}: ${count} keys (tap by label or type directly)`);
+  if (!rows.length) lines.push('no elements read on this screen — try sim_look, or the app may still be drawing');
+  if (truncated) lines.push(`... ${truncated} more; pass filter to narrow`);
+  if (ambiguities?.length) {
+    for (const a of ambiguities) lines.push(`ambiguous "${a.query}": ${a.options.join(', ')}`);
+  }
+  return lines.join('\n');
+}