simframe 0.5.0 → 0.6.0

package/README.md

@@ -20,9 +20,15 @@ one is obvious:
 3. **Nothing is remembered.** The same screen gets re-read and re-reasoned about
    every single time it appears.
 
-simframe attacks all three: a background loop keeps the newest frame warm, whole
-flows run in one call, and screens the agent has seen before are answered from
-memory.
+And there is a fourth that is pure waste: **an image is the most expensive way
+to ask what is on screen.** A screenshot costs ~1,600 tokens when it is handled
+as a native image block and 15,000–25,000 when it is not, and it does not tell
+you what is tappable or where — you have to measure that by eye.
+
+simframe attacks all four: a background loop keeps the newest frame warm, whole
+flows run in one call, screens the agent has seen before are answered from
+memory, and every answer is text with tap points in it. Nothing returns an
+image unless you ask for one.
 
 ## What changed, measured
 
@@ -35,6 +41,8 @@ Same four-tab navigation flow, on a real production app:
 | Finding a control | read tree (~570 ms) + reason | **~1 ms** from memory |
 | A 4-step flow, verified | 4+ model round trips | **1 call**, 3.6 s |
 | Same flow, 3rd run | no improvement — every run is the first | **3.7 s, 4/4 from memory, 4/4 verified** |
+| A 10-step flow | 10 turns, 10 images (~16,000 tokens at best) | **1 turn, 0 images, ~1,650 characters** |
+| Reading a screen | an image: ~1,600 tokens, no tap points | **~330 tokens** of text, with tap points |
 
 The four-tab tour, three times back to back from a cleared memory:
 
@@ -69,7 +77,8 @@ you have a simulator. Without them simframe falls back to the original
 ```
 ok   xcrun              xcrun version 72.
 ok   sips               available
-ok   input driver (idb) companion built Sep 1 2026
+ok   input driver      simframed: Indigo HID
+ok   accessibility tree simframed: AXPTranslator, host-side
 ok   on-device OCR      available
 ok   booted simulator   iPhone 17 Pro (iOS 26.5)
 ok   capture            frame #888 322x700 in 2ms (age 538ms)
@@ -103,33 +112,73 @@ have. **Observation needs nothing but Xcode.**
 | --- | --- | --- |
 | Watch the screen, wait, recall | nothing extra | — |
 | Read labels + coordinates from pixels | `swiftc` (Xcode CLT) | falls back to the accessibility tree alone |
-| Tap, type, swipe | nothing extra, or [`idb`](https://fbidb.io) as a fallback | simframe observes but cannot touch |
-| Accessibility tree | [`idb`](https://fbidb.io) | OCR alone still yields labels and coordinates |
+| Tap, type, swipe | nothing extra | simframe observes but cannot touch |
+| Accessibility tree | nothing extra | OCR alone still yields labels and coordinates |
 
 `simframe doctor` names which engine is carrying each capability, per device.
-**idb is now required only for the accessibility tree** — capture, input and text
-recognition all run in-process.
+**Nothing beyond Xcode is required.** Capture, input, text recognition and the
+accessibility tree all run in-process, in one daemon.
+
+[`idb`](https://fbidb.io) is still accepted as a fallback for input and for the
+tree, for a machine where the daemon cannot run — and `SIMFRAME_AX_DRIVER=idb`
+forces the tree back onto it, which is the escape hatch if an Xcode upgrade
+breaks the host-side path.
 
 ```bash
-# input, optional
+# optional fallback, not a requirement
 brew tap facebook/fb && brew install idb-companion && pipx install fb-idb
 ```
 
-Homebrew may ask you to trust the tap first; that is a deliberate prompt for a
-human, and the narrow form is `brew trust --formula facebook/fb/idb-companion`.
-
 ## The tools
 
+Read first, act in batches, and look at pixels only when the question is about
+pixels. Every tool description says so, because a tool surface that does not
+steer the model is a tool surface the model uses wrong.
+
 | Tool | What it does |
 | --- | --- |
-| `sim_look` | Newest frame as an image, no capture wait. |
-| `sim_state` | Text only: screen hash, what changed **since your last look**, region movement map. |
+| `sim_ui` | **Start here.** The screen as a numbered text map: region, type, label, state, tap point, source. A tenth the cost of a screenshot and strictly more useful. |
+| `sim_do` | **The main tool.** A whole flow in one call — tap, type, scroll, wait, assert — each step settling before the next and verified against what it did last time. |
+| `sim_state` | The cheapest question there is: has anything changed **since your last look**, and which regions moved. |
+| `sim_goto` | Walk to a screen simframe has been to before, planning the route through remembered transitions. |
+| `sim_flow_run` | Replay a flow that verified end to end. |
+| `sim_find` | Resolve an intent to one control, without acting on it. |
+| `sim_tap` · `sim_type_into` · `sim_scroll_to` · `sim_wait_for` · `sim_assert` | Single actions, for when you genuinely only have one step. Each is one `sim_do` step underneath. |
+| `sim_launch` · `sim_open_url` · `sim_permission` | Launch with arguments and environment; open a deep link; grant a privacy permission instead of tapping a system alert. |
 | `sim_wait` | Waits for the screen to change *and then* settle. |
-| `sim_do` | A whole flow in one call — tap, type, scroll, assert — each step settling before the next. |
-| `sim_ui` | The screen as labels + tap coordinates, from accessibility **and** OCR. |
-| `sim_recall` | Look backwards: a timeline of what happened, or the frame from N seconds ago. |
-| `sim_strip` | Recent frames tiled into one image. |
-| `sim_capture` / `sim_devices` | Manage capture loops; list simulators. |
+| `sim_look` | **The only tool that returns an image**, capped at 1024 px. For layout, colour, spacing — questions text cannot answer. |
+| `sim_recall` · `sim_strip` | Look backwards: a text timeline of what happened, or recent frames tiled into one image. |
+| `sim_capture` · `sim_devices` | Manage capture loops; list simulators. |
+
+### What the screen looks like as text
+
+```
+iPhone 17 Pro · 402x874pt · screen a1b2c3d4 "Inbox" (known, 3 known exits)
+last action: [2] tap — ok: matches the outcome seen 5x before
+nav-bar:
+  #1 button    24,64      Back
+  #2 text      201,64     Inbox
+content:
+  #3 cell      201,140    Weekly digest
+  #4 cell      201,196    Payment received
+tab-bar:
+  #5 text      62,835     Inbox
+  #6 text      201,835    Settings
+```
+
+Region first, because "Inbox" the title and "Inbox" the tab differ only by where
+they are. A tap point, because that is what an action needs. And a number, which
+is a selector: whatever this calls `#3`, the next call can tap as `#3` without
+describing it. A ref is valid only while that screen is showing — used on a
+different screen it refuses rather than tapping whatever now sits there.
+
+Three ways to name a control, anywhere one is named:
+
+| | |
+| --- | --- |
+| `#3` | the number the map gave it. Cheapest, unambiguous. |
+| `"Save"` · `the Assets tab` · `back` | resolved by intent — verbs, typos, synonyms, icon-only controls by their common name |
+| `@120,400` | raw point coordinates. Last resort: it cannot tell you it missed. |
 
 ## Baselines: the thing to understand
 
@@ -309,7 +358,8 @@ iPhone 17 Pro, iOS 26.5, Apple Silicon, default settings.
 | Tap (70 ms hold / 10 ms hold) | 76 ms / 13 ms |
 | Text recognition, in-process | **~174 ms** |
 | Text recognition, via PNG + helper (fallback) | ~555 ms |
-| Accessibility tree read (idb) | ~570 ms |
+| Accessibility tree read, in-process | **~45 ms** |
+| Accessibility tree read, via idb (fallback) | ~203 ms |
 | Screen map: first visit / remembered | ~305 ms / **~1 ms** |
 | CPU | 1.1 % idle · 3.1 % active |
 | Frame memory | ~60 s of screen, ~2.7 MB |
@@ -372,23 +422,48 @@ Run `simframe start --engine=simctl` to use the original loop instead.
 
 ## CLI
 
+The CLI is the low-token path, and it is a first-class one: `--json` is on every
+command, so nothing has to be parsed out of prose.
+
 ```bash
-simframe start                 # start the capture loop
-simframe mark                  # hash of the current frame, for --since
+simframe ui                    # the numbered screen map — start here
+simframe ui --json | jq '.elements[] | select(.type=="button") | .label'
+simframe do flow.json          # a whole flow, verified, then the end-state map
+simframe do flow.json --save=checkout   # save it if every step verified
+simframe flow run checkout     # replay it
+simframe tap "#3"              # or "Save", or "@120,400"
+simframe find "the save button"   # resolve an intent without acting
+simframe screens               # screens this device has learned
+simframe goto invoices         # walk to a known screen over known steps
 simframe state --since=$H      # what changed, as text
-simframe frame --out=now.png   # newest frame
+simframe mark                  # hash of the current frame, for --since
 simframe wait --since=$H       # change, then settle
-simframe ui                    # labels + tap points (ax and ocr)
-simframe recall                # what happened in the last minute
+simframe recall                # what happened in the last minute, as text
 simframe recall --ago=15000    # the frame from 15s ago
-simframe strip --count=6       # contact sheet
-simframe screens               # screens this device has learned
-simframe goto invoices         # walk to a known screen over known steps
-simframe flow save|run|list    # record a verified flow, replay it
-simframe doctor --json         machine-readable; --strict fails on any downgrade
-simframe status / stop [--force] / devices / doctor
+simframe frame --out=now.png   # newest frame, native resolution, to a file
+simframe strip --count=6       # contact sheet, for an animation
+simframe doctor --strict       # any degraded layer is a non-zero exit
+simframe start / status / stop [--force] / devices
 ```
 
+### The Claude Code skill
+
+[`skills/simframe/SKILL.md`](skills/simframe/SKILL.md) teaches the CLI path
+directly: the cheap-to-expensive order, the selector grammar, what each verdict
+means and what to do about it. It ships with the package, so an installed copy
+has it.
+
+```bash
+mkdir -p ~/.claude/skills
+ln -s "$(npm root -g)/simframe/skills/simframe" ~/.claude/skills/simframe
+```
+
+A skill and an MCP server are not redundant. The MCP server is discoverable —
+it appears in the tool list without anybody setting it up. The skill is cheaper:
+Claude reads 3–5 lines of CLI output instead of a tool result, and none of the
+MCP schema is in context until a tool is actually used. Ship both, use whichever
+the client makes easy.
+
 ## Degrading is allowed. Degrading quietly is not
 
 simframe is built to degrade rather than fail: no Swift toolchain still gives
@@ -411,8 +486,8 @@ So every downgrade now announces itself:
   is degraded and what that costs.
 - A dependency that is simply not installed is `--`, not `WARN`. The distinction
   is deliberate: `WARN` means this machine could be doing better and silently is
-  not, which is the failure worth shouting about. idb missing on a fresh machine
-  has not degraded from anything, and `--strict` ignores it.
+  not, which is the failure worth shouting about. An optional fallback missing on
+  a fresh machine has not degraded from anything, and `--strict` ignores it.
 - `--strict`, or `SIMFRAME_STRICT=1`, turns any downgrade into a non-zero exit.
   CI runs strict, so a release cannot ship in the state that shipped twice.
 
@@ -420,7 +495,7 @@ So every downgrade now announces itself:
 $ simframe doctor
 ok   capture engine        simframed
 WARN input driver          idb — the daemon's control socket is not up
---   accessibility tree    not installed: idb is not installed
+WARN accessibility tree    idb — the host-side translator did not load
 ```
 
 Two checks enforce it. A packaging check derives the required file list from the
@@ -457,35 +532,35 @@ said a word — the exact failure shape, found by the thing built to catch it.
 
 ## Roadmap
 
-- **The accessibility tree without idb.** `AXPTranslator` would remove the last
-  heavyweight install. Capture, input and geometry already come from the daemon;
-  the tree is all that is left.
-- **A compact state for the agent.** The element list, regions, what changed and
-  the last verdict, shaped so a model spends tokens on deciding rather than on
-  reading. This is where the token savings actually land.
-- **Region bands from where elements cluster**, rather than fractions of screen
-  height. A date banner sitting above the tab bar was classified as a tab label
-  and its text entered a screen's identity, which would have expired at
-  midnight. Fixed for that case by a width rule; the underlying cause remains.
-- **Reduce the input dependency.** idb is the one heavyweight requirement. Its
-  simulator input is a reimplementation of the Indigo HID transport rather than a
-  public API, so replacing it is real work, not a wrapper — but it is the last
-  thing standing between simframe and a zero-install tool.
+- **Android, as a second backend.** Everything above the platform boundary is
+  already platform-agnostic; nothing above it imports a simulator framework.
 - **Extend the confirm vocabulary beyond English.**
 
 ## Releasing
 
-`npm version` does not touch `server.json`, so bump both, then push the tag:
+`npm version` runs a `version` hook that rewrites `server.json` to match and
+stages it, so one command covers both files:
 
 ```bash
-npm version minor --no-git-tag-version
-$EDITOR server.json        # match "version" and packages[0].version
-git commit -am "Release vX.Y.Z" && git tag vX.Y.Z && git push && git push --tags
+npm version minor          # bumps package.json + server.json, commits, tags
+git push --follow-tags
 ```
 
+Before that hook existed, `server.json` had to be hand-edited between two
+commands, and the release that forgot failed at the workflow's own agreement
+check — which is the one thing that check is for.
+
 The `release` workflow verifies tag/`package.json`/`server.json` agree, validates
 `server.json` against the live registry, and publishes to npm and the MCP
-Registry. It needs `NPM_TOKEN`; the registry uses GitHub OIDC and needs no secret.
+Registry. It holds **no secrets** — both halves authenticate with the workflow's
+GitHub OIDC identity.
+
+That needs one setup step on npmjs.com, not in this repo: the package must have a
+Trusted Publisher pointing at this repository and `release.yml` (Package →
+Settings → Trusted Publisher → GitHub Actions). Without it npm has nothing to
+trust and fails with `ENEEDAUTH`. npm is ending token publishing in January 2027,
+and the tokens that work in CI need 2FA bypass, which npm's own UI warns against —
+so OIDC is the durable path, not merely the tidier one.
 
 ## License
 

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

@@ -0,0 +1,379 @@
+import CoreGraphics
+import Foundation
+
+/// One node of the simulator's live accessibility tree, read from the host.
+///
+/// Frames are in **points**, in the device's own top-left coordinate space —
+/// the same space input speaks, so a node's centre is a tap point with no
+/// conversion.
+public struct AXNode: Sendable {
+    public var role: String
+    public var subrole: String?
+    public var label: String?
+    public var value: String?
+    public var identifier: String?
+    public var enabled: Bool?
+    public var selected: Bool?
+    public var focused: Bool?
+    public var frame: CGRect
+    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) {
+        self.role = role
+        self.subrole = subrole
+        self.label = label
+        self.value = value
+        self.identifier = identifier
+        self.enabled = enabled
+        self.selected = selected
+        self.focused = focused
+        self.frame = frame
+        self.depth = depth
+    }
+}
+
+/// A tree, and whether it is all of one.
+///
+/// The walk has three ways to stop early and the bridge has a fourth, and every
+/// one of them produces something that looks exactly like a small screen. A
+/// partial tree is still useful — it is not, however, authoritative, and the
+/// layer above merges accessibility elements as the real hit targets and then
+/// writes them into screen memory. So the shortfall travels with the nodes.
+public struct AXTree: Sendable {
+    public let nodes: [AXNode]
+    /// Nil when the whole tree was read; otherwise why it was not.
+    public let truncated: String?
+
+    public init(nodes: [AXNode], truncated: String? = nil) {
+        self.nodes = nodes
+        self.truncated = truncated
+    }
+}
+
+public enum AccessibilityError: Error, CustomStringConvertible {
+    case unavailable(String)
+    case noFrontmostApplication
+
+    public var description: String {
+        switch self {
+        case .unavailable(let d): return "accessibility unavailable: \(d)"
+        case .noFrontmostApplication: return "no frontmost application on the device"
+        }
+    }
+}
+
+/// Reads the simulator's accessibility tree from the host, with nothing
+/// injected into the guest and no `NSView`.
+///
+/// The shape that works, established against the live runtime:
+///
+///   * `AXPTranslator.sharedInstance` on the host is the **macOS** translator.
+///     Its job is turning iOS accessibility data into mac platform elements,
+///     which is exactly what a host-side reader wants.
+///   * The bridge delegate is held **weakly**, so it must be retained here.
+///     A delegate nobody retains is deallocated at once and the translator
+///     answers nil, looking precisely like a broken private API.
+///   * The delegate token is not ours to invent: `SimDevice` publishes its own
+///     as `accessibilityPlatformTranslationToken`, and that is what routes a
+///     request to the right guest.
+///   * The element to read is **not** the translation object. Passing that to
+///     `processTranslatorRequest:` returns a response whose `resultData` is nil.
+///     `AXPMacPlatformElement.platformElementWithTranslationObject:` wraps it in
+///     something that answers ordinary `accessibilityAttributeValue:` calls,
+///     and the whole tree walks from there.
+///
+/// Every call must run off the main queue: the bridge blocks waiting on the
+/// device, and blocking main is a deadlock that presents as silence.
+public final class AccessibilityBridge {
+    private let device: NSObject
+    private let token: Any?
+    private let translator: NSObject
+    private let elementClass: NSObject.Type
+    /// The translator holds this weakly. Releasing it breaks every later read.
+    private let delegate: BridgeDelegate
+
+    /// A tree this deep is a runaway, not a screen.
+    private static let maxDepth = 40
+    /// Enough for any real screen; a cap so a cycle cannot hang the daemon.
+    private static let maxNodes = 4000
+
+    // MARK: - Construction
+
+    public init(device: NSObject, requestTimeout: TimeInterval = 5) throws {
+        guard let handle = dlopen(Self.frameworkPath, RTLD_NOW), handle != nil else {
+            throw AccessibilityError.unavailable(
+                "AccessibilityPlatformTranslation did not load: \(String(cString: dlerror()))")
+        }
+        guard let translatorClass = NSClassFromString("AXPTranslator") as? NSObject.Type,
+              let shared = translatorClass.perform(NSSelectorFromString("sharedInstance"))?
+                  .takeUnretainedValue() as? NSObject else {
+            throw AccessibilityError.unavailable("AXPTranslator.sharedInstance missing")
+        }
+        guard let elementClass = NSClassFromString("AXPMacPlatformElement") as? NSObject.Type,
+              elementClass.responds(to: NSSelectorFromString("platformElementWithTranslationObject:")) else {
+            throw AccessibilityError.unavailable("AXPMacPlatformElement missing")
+        }
+        guard shared.responds(to: NSSelectorFromString("frontmostApplicationWithDisplayId:bridgeDelegateToken:")) else {
+            throw AccessibilityError.unavailable("frontmostApplicationWithDisplayId: missing")
+        }
+        guard device.responds(to: NSSelectorFromString("sendAccessibilityRequestAsync:completionQueue:completionHandler:")) else {
+            throw AccessibilityError.unavailable("this SimDevice cannot carry accessibility requests")
+        }
+
+        self.device = device
+        self.translator = shared
+        self.elementClass = elementClass
+        self.delegate = BridgeDelegate(device: device, timeout: requestTimeout)
+        self.token = device.responds(to: NSSelectorFromString("accessibilityPlatformTranslationToken"))
+            ? device.value(forKey: "accessibilityPlatformTranslationToken")
+            : nil
+
+        shared.setValue(delegate, forKey: "bridgeTokenDelegate")
+        if shared.responds(to: NSSelectorFromString("setSupportsDelegateTokens:")) {
+            shared.setValue(true, forKey: "supportsDelegateTokens")
+        }
+        if shared.responds(to: NSSelectorFromString("setAccessibilityEnabled:")) {
+            shared.setValue(true, forKey: "accessibilityEnabled")
+        }
+    }
+
+    private static let frameworkPath =
+        "/System/Library/PrivateFrameworks/AccessibilityPlatformTranslation.framework/AccessibilityPlatformTranslation"
+
+    // MARK: - Reading
+
+    /// The frontmost application's tree, flattened depth-first.
+    ///
+    /// An app that is still launching genuinely has no tree yet — the read
+    /// returns the application node alone. That is reported as it is, rather
+    /// than retried into looking like a populated screen.
+    public func tree(budget: TimeInterval = 3) throws -> AXTree {
+        guard let app = frontmostApplication() else { throw AccessibilityError.noFrontmostApplication }
+        guard let root = elementClass
+            .perform(NSSelectorFromString("platformElementWithTranslationObject:"), with: app)?
+            .takeUnretainedValue() as? NSObject else {
+            throw AccessibilityError.unavailable("the frontmost application did not translate to an element")
+        }
+        delegate.resetTimeouts()
+        var out: [AXNode] = []
+        var cut: String?
+        let deadline = Date().addingTimeInterval(budget)
+        walk(root, depth: 0, into: &out, deadline: deadline, cut: &cut)
+        // A guest that missed the deadline answers `emptyResponse`, which makes
+        // the subtree below it look genuinely childless. Nothing in the nodes
+        // can show that, so the count has to.
+        let missed = delegate.timeouts
+        if cut == nil, missed > 0 {
+            cut = "\(missed) request(s) to the device timed out, so part of the tree is missing"
+        }
+        return AXTree(nodes: out, truncated: cut)
+    }
+
+    /// Read one attribute off the frontmost application.
+    ///
+    /// Constructing the bridge proves only that the classes and selectors are
+    /// there. The failure this whole path took two attempts to get past was a
+    /// bridge that constructed perfectly and then read nothing, so "available"
+    /// has to mean a value came back, not that the symbols exist.
+    public func probe() throws {
+        guard let app = frontmostApplication() else { throw AccessibilityError.noFrontmostApplication }
+        guard let root = elementClass
+            .perform(NSSelectorFromString("platformElementWithTranslationObject:"), with: app)?
+            .takeUnretainedValue() as? NSObject else {
+            throw AccessibilityError.unavailable("the frontmost application did not translate to an element")
+        }
+        guard attribute(root, "AXRole") is String else {
+            throw AccessibilityError.unavailable("the translator answered nil for the application's role")
+        }
+    }
+
+    /// The pid of the app currently frontmost, or nil when the bridge cannot say.
+    public func frontmostPid() -> Int32? {
+        guard let app = frontmostApplication() else { return nil }
+        return (app.value(forKey: "pid") as? NSNumber)?.int32Value
+    }
+
+    private func frontmostApplication() -> NSObject? {
+        let sel = NSSelectorFromString("frontmostApplicationWithDisplayId:bridgeDelegateToken:")
+        guard let imp = translator.method(for: sel) else { return nil }
+        typealias FrontFn = @convention(c) (AnyObject, Selector, UInt32, AnyObject?) -> AnyObject?
+        return unsafeBitCast(imp, to: FrontFn.self)(translator, sel, 0, token as AnyObject?) as? NSObject
+    }
+
+    private func walk(_ element: NSObject, depth: Int, into out: inout [AXNode],
+                      deadline: Date, cut: inout String?) {
+        if depth > Self.maxDepth {
+            cut = cut ?? "the tree is deeper than \(Self.maxDepth) levels"
+            return
+        }
+        if out.count >= Self.maxNodes {
+            cut = cut ?? "the tree has more than \(Self.maxNodes) nodes, which is a cycle rather than a screen"
+            return
+        }
+        if Date() > deadline {
+            cut = cut ?? "the read ran out of time"
+            return
+        }
+        out.append(node(from: element, depth: depth))
+        guard let children = attribute(element, "AXChildren") as? [NSObject] else { return }
+        for child in children {
+            walk(child, depth: depth + 1, into: &out, deadline: deadline, cut: &cut)
+        }
+    }
+
+    /// Everything scalar about a node, asked for in one go.
+    private static let batched = ["AXRole", "AXSubrole", "AXDescription", "AXValue",
+                                  "AXIdentifier", "AXEnabled", "AXSelected", "AXFocused"]
+
+    private func node(from element: NSObject, depth: Int) -> AXNode {
+        // One bridge round trip for eight attributes, not eight.
+        //
+        // Each `accessibilityAttributeValue:` is a synchronous hop into the
+        // guest, so a per-attribute walk costs eleven of them per node. That is
+        // 25 ms for fourteen nodes on this machine and invisible — and on a
+        // slow one it is the whole read. A CI runner took 28 s over it and
+        // returned nothing. `accessibilityMultipleAttributes:` answers the same
+        // eight in a single hop: 10 ms for the same fourteen nodes here, and
+        // one eighth of the round trips wherever a round trip is what costs.
+        let bag = multiple(element, Self.batched)
+        func value(_ name: String) -> Any? { bag?[name] ?? attribute(element, name) }
+
+        let role = value("AXRole") as? String ?? "AXUnknown"
+        // The label is the app's own name for the control. AXDescription is
+        // where UIKit puts an accessibility label that has no visible title,
+        // so it is the fallback rather than a separate field.
+        let label = string(element.responds(to: NSSelectorFromString("accessibilityLabel"))
+            ? element.value(forKey: "accessibilityLabel") : nil)
+            ?? string(value("AXDescription"))
+        return AXNode(
+            role: Self.shortRole(role),
+            subrole: Self.shortRole(value("AXSubrole") as? String),
+            label: label,
+            value: string(value("AXValue")),
+            identifier: string(value("AXIdentifier")),
+            enabled: (value("AXEnabled") as? NSNumber)?.boolValue,
+            selected: (value("AXSelected") as? NSNumber)?.boolValue,
+            focused: (value("AXFocused") as? NSNumber)?.boolValue,
+            frame: frame(of: element),
+            depth: depth)
+    }
+
+    /// Several attributes in one call, or nil if this element will not batch —
+    /// in which case the caller falls back to asking one at a time, because a
+    /// slower correct answer beats a missing one.
+    private func multiple(_ element: NSObject, _ names: [String]) -> [String: Any]? {
+        let sel = NSSelectorFromString("accessibilityMultipleAttributes:")
+        guard element.responds(to: sel) else { return nil }
+        let answer = element.perform(sel, with: names as NSArray)?.takeUnretainedValue()
+        guard let dictionary = answer as? [String: Any] else { return nil }
+        return dictionary
+    }
+
+    private func attribute(_ element: NSObject, _ name: String) -> Any? {
+        let sel = NSSelectorFromString("accessibilityAttributeValue:")
+        guard element.responds(to: sel) else { return nil }
+        return element.perform(sel, with: name as NSString)?.takeUnretainedValue()
+    }
+
+    private func frame(of element: NSObject) -> CGRect {
+        let sel = NSSelectorFromString("accessibilityFrame")
+        guard element.responds(to: sel), let imp = element.method(for: sel) else { return .zero }
+        typealias RectFn = @convention(c) (AnyObject, Selector) -> CGRect
+        return unsafeBitCast(imp, to: RectFn.self)(element, sel)
+    }
+
+    /// A value may be a string, a number, or something with no useful text.
+    private func string(_ value: Any?) -> String? {
+        switch value {
+        case let s as String:
+            let trimmed = s.trimmingCharacters(in: .whitespacesAndNewlines)
+            return trimmed.isEmpty ? nil : trimmed
+        case let n as NSNumber:
+            return n.stringValue
+        default:
+            return nil
+        }
+    }
+
+    /// `AXButton` is the mac vocabulary; the rest of simframe speaks `Button`.
+    private static func shortRole(_ role: String?) -> String? {
+        guard let role, !role.isEmpty else { return nil }
+        return role.hasPrefix("AX") ? String(role.dropFirst(2)) : role
+    }
+
+    private static func shortRole(_ role: String) -> String {
+        shortRole(Optional(role)) ?? role
+    }
+}
+
+/// Carries translator requests to the device and the answers back.
+///
+/// The translator asks for a block, calls it whenever it needs guest data, and
+/// expects the answer synchronously — so this bridges async to sync on a queue
+/// that is never main.
+private final class BridgeDelegate: NSObject {
+    private let device: NSObject
+    private let timeout: TimeInterval
+    private let queue = DispatchQueue(label: "simframe.accessibility.bridge")
+    private let counter = NSLock()
+    private var timedOut = 0
+
+    init(device: NSObject, timeout: TimeInterval) {
+        self.device = device
+        self.timeout = timeout
+    }
+
+    /// How many requests the device failed to answer since the last reset.
+    var timeouts: Int {
+        counter.lock(); defer { counter.unlock() }
+        return timedOut
+    }
+
+    func resetTimeouts() {
+        counter.lock(); defer { counter.unlock() }
+        timedOut = 0
+    }
+
+    fileprivate func recordTimeout() {
+        counter.lock(); defer { counter.unlock() }
+        timedOut += 1
+    }
+
+    @objc(accessibilityTranslationDelegateBridgeCallbackWithToken:)
+    func bridgeCallback(token: NSString?) -> Any? {
+        let device = self.device, queue = self.queue, timeout = self.timeout
+        let block: @convention(block) (Any?) -> Any? = { [self] request in
+            guard let request else { return nil }
+            let sel = NSSelectorFromString("sendAccessibilityRequestAsync:completionQueue:completionHandler:")
+            guard let imp = device.method(for: sel) else { return nil }
+            var answer: Any?
+            let waited = DispatchSemaphore(value: 0)
+            let handler: @convention(block) (Any?) -> Void = { response in
+                answer = response
+                waited.signal()
+            }
+            typealias SendFn = @convention(c) (AnyObject, Selector, AnyObject, AnyObject, AnyObject) -> Void
+            unsafeBitCast(imp, to: SendFn.self)(device, sel, request as AnyObject, queue, handler as AnyObject)
+            if waited.wait(timeout: .now() + timeout) == .timedOut {
+                self.recordTimeout()
+                // An empty response is what the translator expects when the
+                // guest does not answer. Returning nil crashes it.
+                return (NSClassFromString("AXPTranslatorResponse") as? NSObject.Type)?
+                    .perform(NSSelectorFromString("emptyResponse"))?.takeUnretainedValue()
+            }
+            return answer
+        }
+        return block
+    }
+
+    /// Frames arrive in the device's own point space, which is where they
+    /// belong: converting them to host screen coordinates would make them
+    /// useless for input.
+    @objc(accessibilityTranslationConvertPlatformFrameToSystem:withToken:)
+    func convertFrame(_ rect: CGRect, token: NSString?) -> CGRect { rect }
+
+    @objc(accessibilityTranslationRootParentWithToken:)
+    func rootParent(token: NSString?) -> Any? { nil }
+}