@buoy-gg/bug-links 0.0.0-stage → 7.0.81

package/ios/BuoyFrames.swift

@@ -0,0 +1,640 @@
+// Bug Links pictures and video on iOS (research/bug-links-2026-10/media/SPEC.md).
+//
+// The way to take a frame won a race on a real iPhone (SPEC section 6, v23):
+// UIGraphicsImageRenderer at 1x in its default format, drawHierarchy without
+// waiting for a screen update, started right after a display tick. Boxes,
+// color and JPEG happen on a background queue.
+//
+// Safety, from the 2026-10-26 compatibility review:
+// - a frame is read three times (a tick before, right before, right after) and
+//   every place a part was gets a box (H13);
+// - any doubt drops the frame and keeps a reason (H2, C5);
+// - every job carries a run token, so a late job can't touch a newer run;
+// - nothing here blocks the main thread waiting on another thread.
+import UIKit
+import UIKit.UIGestureRecognizerSubclass
+import ImageIO
+import UniformTypeIdentifiers
+
+@available(iOSApplicationExtension, unavailable)
+@objc(BuoyFrames)
+final class BuoyFrames: NSObject {
+  @objc static func requiresMainQueueSetup() -> Bool { false }
+
+  private let engine = BuoyFrameEngine.shared
+
+  @objc(configure:)
+  func configure(_ options: NSDictionary) {
+    DispatchQueue.main.async { self.engine.configure(options) }
+  }
+
+  @objc(status:reject:)
+  func status(_ resolve: @escaping (Any?) -> Void, reject: @escaping (String?, String?, Error?) -> Void) {
+    DispatchQueue.main.async { resolve(self.engine.status()) }
+  }
+
+  @objc(takeMedia:reject:)
+  func takeMedia(_ resolve: @escaping (Any?) -> Void, reject: @escaping (String?, String?, Error?) -> Void) {
+    DispatchQueue.main.async { self.engine.takeMedia { resolve($0) } }
+  }
+
+  @objc(captureLast:reject:)
+  func captureLast(_ resolve: @escaping (Any?) -> Void, reject: @escaping (String?, String?, Error?) -> Void) {
+    DispatchQueue.main.async { self.engine.captureLast { resolve($0) } }
+  }
+
+  @objc func resume() {
+    DispatchQueue.main.async { self.engine.resume() }
+  }
+
+  @objc(startVideo:)
+  func startVideo(_ always: Bool) {
+    DispatchQueue.main.async { self.engine.startVideo(always: always) }
+  }
+
+  @objc func stopVideo() {
+    DispatchQueue.main.async { self.engine.stopVideo() }
+  }
+
+  @objc func mark() {
+    DispatchQueue.main.async { self.engine.mark() }
+  }
+
+  @objc func clear() {
+    DispatchQueue.main.async { self.engine.clear() }
+  }
+
+  /// Test hook for the mask zoo: take one frame now and give back its boxes and JPEG.
+  @objc(probe:reject:)
+  func probe(_ resolve: @escaping (Any?) -> Void, reject: @escaping (String?, String?, Error?) -> Void) {
+    DispatchQueue.main.async { self.engine.probe { resolve($0) } }
+  }
+
+  @objc func invalidate() {
+    DispatchQueue.main.async { self.engine.stopAll() }
+  }
+}
+
+struct BuoyFrame {
+  let t: Double      // ms since 1970 (the case's touch clock)
+  let kind: String   // "last" | "tap" | "video"
+  let w: Int
+  let h: Int
+  let jpeg: Data
+  let boxes: Int
+  let moved: Bool
+}
+
+@available(iOSApplicationExtension, unavailable)
+final class BuoyFrameEngine: NSObject, UIGestureRecognizerDelegate {
+  static let shared = BuoyFrameEngine()
+
+  // Settings (S1, M1)
+  private var pictures = true
+  private var customer = false
+  private var masks = BuoyMaskSettings()
+  private var videoFps = 2.0
+  private var enabled = false
+
+  // Rings (F2, F3, F4). Main thread only.
+  private var taps: [BuoyFrame] = []
+  private var video: [BuoyFrame] = []
+  private var last: BuoyFrame?
+  private var marks: [Double] = []
+  private var dropped: [String: Int] = [:]
+  private var frozen = false
+  // F8: the time of the last frame taken when Buoy's button was touched, and
+  // whether the touch going on now started on Buoy (no tap frame for it).
+  private var buttonLastT: Double?
+  private var downOnBuoy = false
+
+  // One job at a time. `run` goes up on every stop, so late jobs are ignored.
+  private var run = 0
+  private var busy = false
+  private var slowInRow = 0
+  private var stoppedReason: String?
+
+  // Video (F3, F3a)
+  private var videoOn = false
+  private var videoAlways = false
+  private var videoUntil: CFTimeInterval = 0
+  private var nextVideoDue: CFTimeInterval = 0
+  private var videoLink: CADisplayLink?
+
+  // Taps (F2)
+  private var watchers: [BuoyTapWatcher] = []
+  private var visibleObserver: NSObjectProtocol?
+  private var tapTimer: Timer?
+
+  private let queue = DispatchQueue(label: "gg.buoy.frames", qos: .utility)
+  private static let maxLongSide: CGFloat = 1280
+  private static let maxVideoBytes = 6 * 1024 * 1024
+
+  // MARK: settings
+
+  func configure(_ o: NSDictionary) {
+    let wasCustomer = customer
+    let old = masks
+    pictures = (o["pictures"] as? Bool) ?? true
+    customer = (o["mode"] as? String) == "customer"
+    masks.text = (o["maskAllText"] as? Bool) ?? true
+    masks.images = (o["maskAllImages"] as? Bool) ?? true
+    masks.inputs = (o["maskAllInputs"] as? Bool) ?? true
+    // A hiding setting that turned on (or customer mode): frames already taken hid less, so they go.
+    // Here, not only in JS: this engine outlives a JS reload, and new JS brings new settings.
+    if (!old.text && masks.text) || (!old.images && masks.images) || (!old.inputs && masks.inputs) || (customer && !wasCustomer) { clear() }
+    if let fps = o["videoFps"] as? Double, fps > 0 { videoFps = min(fps, 10) }
+    enabled = true
+    attachWatcher()
+    let v = o["video"] as? String
+    if v == "always" && !customer { startVideo(always: true) } else if videoAlways { stopVideo() }
+  }
+
+  func status() -> [String: Any] {
+    ["available": true, "enabled": enabled, "mode": customer ? "customer" : "internal", "stopped": stoppedReason ?? NSNull()]
+  }
+
+  // MARK: taps
+
+  private func attachWatcher() {
+    // Every app window gets a watcher, so taps in an app's own extra window
+    // (an .alert-level one) get pictures too. Windows that show later are
+    // picked up when they become visible.
+    for w in Self.appWindows().all where !watchers.contains(where: { $0.view === w }) {
+      let g = BuoyTapWatcher(target: nil, action: nil)
+      g.cancelsTouchesInView = false
+      g.delaysTouchesBegan = false
+      g.delaysTouchesEnded = false
+      g.delegate = self
+      g.onBegan = { [weak self] view in self?.touchBegan(on: view) }
+      g.onEnded = { [weak self] in self?.tapped() }
+      w.addGestureRecognizer(g)
+      watchers.append(g)
+    }
+    watchers.removeAll { $0.view == nil }
+    if visibleObserver == nil {
+      visibleObserver = NotificationCenter.default.addObserver(forName: UIWindow.didBecomeVisibleNotification, object: nil, queue: .main) { [weak self] _ in
+        guard let self, self.enabled else { return }
+        self.attachWatcher()
+      }
+    }
+  }
+
+
+  func gestureRecognizer(_ g: UIGestureRecognizer, shouldRecognizeSimultaneouslyWith other: UIGestureRecognizer) -> Bool { true }
+
+  /// A touch on Buoy's floating button: take the last frame now, before the dial draws (F8).
+  private func touchBegan(on view: UIView?) {
+    downOnBuoy = false
+    guard var v = view else { return }
+    while true {
+      if BuoyWalker.nativeID(v) == BuoyWalker.buoyRootID {
+        downOnBuoy = true
+        if enabled, !frozen, !busy {
+          take(kind: "last", attempts: 1) { [weak self] ok in
+            if ok { self?.buttonLastT = self?.last?.t }
+          }
+        }
+        return
+      }
+      guard let s = v.superview else { return }
+      v = s
+    }
+  }
+
+  private func tapped() {
+    // A tap on Buoy's own button would show Buoy's toast or dial, not the app.
+    if downOnBuoy { downOnBuoy = false; return }
+    guard enabled, pictures, !customer, !frozen, stoppedReason == nil else { return }
+    tapTimer?.invalidate()
+    // F2: about 300 ms after the tap, so the screen has time to change.
+    tapTimer = Timer.scheduledTimer(withTimeInterval: 0.3, repeats: false) { [weak self] _ in
+      self?.take(kind: "tap", attempts: 1)
+    }
+  }
+
+  // MARK: video
+
+  func startVideo(always: Bool) {
+    guard enabled, !customer else { return }
+    videoOn = true
+    videoAlways = always
+    if !always { video.removeAll(); marks.removeAll() }
+    videoUntil = always ? .infinity : CACurrentMediaTime() + 60 // F3: 60 s at most
+    nextVideoDue = CACurrentMediaTime()
+    if videoLink == nil {
+      let l = CADisplayLink(target: BuoyLinkProxy(self), selector: #selector(BuoyLinkProxy.tick))
+      l.add(to: .main, forMode: .common)
+      videoLink = l
+    }
+  }
+
+  func stopVideo() {
+    videoOn = false
+    videoAlways = false
+    videoLink?.invalidate()
+    videoLink = nil
+  }
+
+  func mark() { if videoOn { marks.append(Date().timeIntervalSince1970 * 1000) } }
+
+  fileprivate func videoTick() {
+    let now = CACurrentMediaTime()
+    if now > videoUntil { stopVideo(); return }
+    guard videoOn, !frozen, stoppedReason == nil, now >= nextVideoDue else { return }
+    // Set the next slot from now, so a long pause never makes a backlog.
+    nextVideoDue = now + 1 / videoFps
+    if !busy { take(kind: "video", attempts: 1) }
+  }
+
+  // MARK: the case
+
+  /// F8: the last frame. Buoy is usually open by now, so this keeps the frame
+  /// taken when Buoy's button was touched, unless a fresh one can be taken.
+  func captureLast(_ done: @escaping ([String: Any]) -> Void) {
+    // Buoy's toast is up by now, so the frame from the button touch is the
+    // better last frame while it is new.
+    if let b = buttonLastT, last?.t == b, Date().timeIntervalSince1970 * 1000 - b < 10_000 {
+      done(["ok": true, "reason": NSNull()])
+      return
+    }
+    take(kind: "last", attempts: customer ? 6 : 1) { [weak self] ok in
+      done(["ok": ok, "reason": ok ? NSNull() : (self?.lastReason ?? "no frame")])
+    }
+  }
+
+  private var lastReason: String?
+
+  // Debug builds run this code with no optimizing, several times slower, so
+  // they get more time before a frame is dropped.
+  #if DEBUG
+  private static let walkBudgetMs: Double = 160
+  #else
+  private static let walkBudgetMs: Double = 40
+  #endif
+
+  func takeMedia(_ done: @escaping ([String: Any]) -> Void) {
+    frozen = true // F8: no late job adds a frame now
+    var frames: [[String: Any]] = []
+    func add(_ f: BuoyFrame) {
+      frames.append(["t": f.t, "kind": f.kind, "w": f.w, "h": f.h, "boxes": f.boxes, "moved": f.moved,
+                     "jpeg": f.jpeg.base64EncodedString()])
+    }
+    // Keep only what can fit in a case before making base64 (C2).
+    var bytes = 0
+    let budget = 4 * 1024 * 1024
+    // C2's order: the last frame, taps (newest first), video near a "Bug here"
+    // mark (closest first), then the rest of the video spread over the clip.
+    var out: [BuoyFrame] = []
+    if let l = last { out.append(l) }
+    out += taps.reversed()
+    let gap = { (f: BuoyFrame) -> Double in self.marks.map { abs($0 - f.t) }.min() ?? .greatestFiniteMagnitude }
+    let near = video.indices.filter { gap(video[$0]) <= 3000 }.sorted { gap(video[$0]) < gap(video[$1]) }
+    out += near.map { video[$0] }
+    let nearSet = Set(near)
+    // The rest in spread order, so a size cut keeps frames from the whole clip.
+    let rest = video.indices.filter { !nearSet.contains($0) }
+    out += BuoyFrameEngine.spreadOrder(rest.count).map { video[rest[$0]] }
+    var kept: [BuoyFrame] = []
+    var cut = 0
+    for f in out {
+      if kept.count >= 150 || bytes + f.jpeg.count > budget { cut += 1; continue }
+      kept.append(f)
+      bytes += f.jpeg.count
+    }
+    kept.sort { $0.t < $1.t }
+    kept.forEach(add)
+    done([
+      "frames": frames,
+      "marks": marks,
+      "dropped": cut + dropped.values.reduce(0, +),
+      "reasons": dropped,
+      "stopped": stoppedReason ?? NSNull(),
+      "lastAgeMs": last.map { Date().timeIntervalSince1970 * 1000 - $0.t } ?? NSNull(),
+      "settings": ["maskAllText": masks.text, "maskAllImages": masks.images, "maskAllInputs": masks.inputs],
+    ])
+  }
+
+  /// 0..<n in an order where every start of the list spans the range (ends, middle, quarters…).
+  static func spreadOrder(_ n: Int) -> [Int] {
+    guard n > 0 else { return [] }
+    var used = [Bool](repeating: false, count: n)
+    var out: [Int] = []
+    func add(_ i: Int) { if !used[i] { used[i] = true; out.append(i) } }
+    add(0); add(n - 1)
+    var parts = 2
+    while out.count < n {
+      var k = 1
+      while k < parts { add(Int((Double(n - 1) * Double(k) / Double(parts)).rounded())); k += 2 }
+      if parts > n * 2 { for i in 0..<n { add(i) } }
+      parts *= 2
+    }
+    return out
+  }
+
+  func resume() { frozen = false }
+
+  func clear() {
+    // A frame still being made belongs to the old settings: a new run token drops it.
+    run += 1
+    busy = false
+    tapTimer?.invalidate(); tapTimer = nil
+    taps.removeAll(); video.removeAll(); last = nil; marks.removeAll(); dropped.removeAll()
+    frozen = false
+  }
+
+  func stopAll() {
+    run += 1
+    stopVideo()
+    tapTimer?.invalidate(); tapTimer = nil
+    for w in watchers { w.view?.removeGestureRecognizer(w) }
+    watchers.removeAll()
+    if let o = visibleObserver { NotificationCenter.default.removeObserver(o); visibleObserver = nil }
+    busy = false
+    enabled = false
+  }
+
+  // MARK: one frame
+
+  private func drop(_ reason: String) {
+    dropped[reason, default: 0] += 1
+    lastReason = reason
+  }
+
+  /// Takes one frame over two display ticks: read the boxes on the first, then
+  /// read, draw and read again on the second (H13).
+  private func take(kind: String, attempts: Int, done: ((Bool) -> Void)? = nil) {
+    guard enabled else { done?(false); return }
+    // Customer mode keeps the last frame only (M1); a tap queued before the switch adds nothing.
+    if kind == "tap" && (customer || !pictures) { done?(false); return }
+    attachWatcher()
+    guard !busy else { drop("busy"); done?(false); return }
+    guard UIApplication.shared.applicationState == .active else { drop("app in background"); done?(false); return } // F7
+    busy = true
+    let token = run
+    let before = Self.walkNow(masks: masks)
+    BuoyNextTick.after { [weak self] in
+      guard let self, token == self.run else { done?(false); return }
+      self.shoot(kind: kind, before: before, token: token) { ok, retry in
+        if !ok && retry && attempts > 1 {
+          // Customer mode: wait for the screen to hold still.
+          DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+            guard token == self.run else { done?(false); return }
+            self.take(kind: kind, attempts: attempts - 1, done: done)
+          }
+        } else {
+          done?(ok)
+        }
+      }
+    }
+  }
+
+  private static func walkNow(masks: BuoyMaskSettings) -> (BuoyWalk, CGRect, [UIWindow])? {
+    let found = appWindows()
+    guard !found.all.isEmpty else { return nil }
+    let frame = found.frame
+    return (BuoyWalker.walk(found.all, in: frame, settings: masks, budgetMs: Self.walkBudgetMs), frame, found.all)
+  }
+
+  private func shoot(kind: String, before: (BuoyWalk, CGRect, [UIWindow])?, token: Int, done: @escaping (Bool, Bool) -> Void) {
+    let t0 = CACurrentMediaTime()
+    func fail(_ reason: String, retry: Bool = false) { busy = false; drop(reason); done(false, retry) }
+    guard UIApplication.shared.applicationState == .active else { return fail("app in background") }
+    guard let before, let now = Self.walkNow(masks: masks) else { return fail("no app window") }
+    let (walkA, frameA, windowsA) = before
+    let (walkB, frame, windows) = now
+    // H2: any change to the windows between reads means we can't trust the boxes.
+    guard frame == frameA, windows.map({ ObjectIdentifier($0) }) == windowsA.map({ ObjectIdentifier($0) }) else { return fail("the window changed") }
+    if let f = walkA.failed ?? walkB.failed { return fail(f) }
+    if walkA.buoyOpen || walkB.buoyOpen { return fail("a Buoy screen was open") } // F5
+    guard frame.width >= 1, frame.height >= 1 else { return fail("no app window") }
+
+    // Draw at 1x in the renderer's default format: the fast path (SPEC section 6).
+    let scale = min(1, Self.maxLongSide / max(frame.width, frame.height))
+    let fmt = UIGraphicsImageRendererFormat()
+    fmt.scale = scale
+    fmt.opaque = true
+    var drew = true
+    let image = UIGraphicsImageRenderer(size: frame.size, format: fmt).image { _ in
+      for w in windows {
+        let r = w.frame.offsetBy(dx: -frame.minX, dy: -frame.minY)
+        if !w.drawHierarchy(in: r, afterScreenUpdates: false) { drew = false }
+      }
+    }
+    guard drew, let shot = image.cgImage else { return fail("iOS couldn't draw the screen") }
+
+    let walkC = BuoyWalker.walk(windows, in: frame, settings: masks, budgetMs: Self.walkBudgetMs)
+    if let f = walkC.failed { return fail(f) }
+    if walkC.buoyOpen { return fail("a Buoy screen was open") }
+
+    // H13: every place each part was, a tick ago, now and after the draw.
+    var boxes: [ObjectIdentifier: CGRect] = walkA.parts
+    var moved = false
+    for walk in [walkB.parts, walkC.parts] {
+      for (id, r) in walk {
+        if let old = boxes[id] {
+          if old != r { moved = true }
+          boxes[id] = old.union(r)
+        } else {
+          boxes[id] = r
+          moved = true
+        }
+      }
+    }
+    if walkA.parts.keys.contains(where: { walkC.parts[$0] == nil }) { moved = true }
+    if moved && customer { return fail("the screen was moving", retry: true) }
+
+    let mainMs = (CACurrentMediaTime() - t0) * 1000
+    noteSpeed(mainMs, kind: kind)
+
+    let rects = Self.merge(Array(boxes.values))
+    let size = frame.size
+    let wall = Date().timeIntervalSince1970 * 1000
+    queue.async { [weak self] in
+      let jpeg = autoreleasepool { Self.boxAndEncode(shot, size: size, scale: scale, rects: rects) }
+      DispatchQueue.main.async {
+        // A newer run (clear, stop): still answer, so a waiting report never hangs.
+        guard let self, token == self.run else { done(false, false); return }
+        self.busy = false
+        guard let jpeg else { self.drop("couldn't make the picture"); done(false, false); return }
+        let f = BuoyFrame(t: wall, kind: kind, w: Int(size.width.rounded()), h: Int(size.height.rounded()),
+                          jpeg: jpeg, boxes: rects.count, moved: moved)
+        self.keep(f)
+        done(true, false)
+      }
+    }
+  }
+
+  private func keep(_ f: BuoyFrame) {
+    // F8: once the case is being made, only its own last frame can land.
+    if frozen && f.kind != "last" { return }
+    switch f.kind {
+    case "last": last = f
+    case "tap":
+      taps.append(f)
+      if taps.count > 10 { taps.removeFirst(taps.count - 10) } // F2
+    default:
+      video.append(f)
+      let keepFor: Double = videoAlways ? 30_000 : 60_000 // F3, F3a
+      let cutoff = f.t - keepFor
+      video.removeAll { $0.t < cutoff }
+      var total = video.reduce(0) { $0 + $1.jpeg.count }
+      while total > Self.maxVideoBytes, !video.isEmpty { total -= video.removeFirst().jpeg.count } // F4
+    }
+  }
+
+  /// F6 and M1: slow phones take fewer frames, then stop.
+  private func noteSpeed(_ ms: Double, kind: String) {
+    if kind == "last" { return }
+    if ms > 250 {
+      stoppedReason = "pictures stopped: this phone took \(Int(ms)) ms for one"
+      stopVideo()
+    } else if ms > 100 {
+      slowInRow += 1
+      if slowInRow >= 2 { videoFps = max(0.5, videoFps / 2); slowInRow = 0 }
+    } else {
+      slowInRow = 0
+    }
+  }
+
+  /// Drops boxes that sit fully inside another one.
+  static func merge(_ rects: [CGRect]) -> [CGRect] {
+    let sorted = rects.sorted { $0.width * $0.height > $1.width * $1.height }
+    var out: [CGRect] = []
+    for r in sorted where !out.contains(where: { $0.contains(r) }) { out.append(r) }
+    return out
+  }
+
+  static func boxAndEncode(_ shot: CGImage, size: CGSize, scale: CGFloat, rects: [CGRect]) -> Data? {
+    let w = Int((size.width * scale).rounded()), h = Int((size.height * scale).rounded())
+    guard w > 0, h > 0, w * h <= 4_000_000,
+          let space = CGColorSpace(name: CGColorSpace.sRGB),
+          let ctx = CGContext(data: nil, width: w, height: h, bitsPerComponent: 8, bytesPerRow: 0,
+                              space: space, bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue)
+    else { return nil }
+    ctx.interpolationQuality = .medium
+    ctx.draw(shot, in: CGRect(x: 0, y: 0, width: w, height: h))
+    ctx.setFillColor(red: 0x1F / 255, green: 0x1F / 255, blue: 0x1F / 255, alpha: 1) // H3
+    for r in rects {
+      let s = CGRect(x: r.minX * scale, y: r.minY * scale, width: r.width * scale, height: r.height * scale).integral
+      ctx.fill(CGRect(x: s.minX, y: CGFloat(h) - s.maxY, width: s.width, height: s.height))
+    }
+    guard let out = ctx.makeImage() else { return nil }
+    let data = NSMutableData()
+    guard let dest = CGImageDestinationCreateWithData(data, UTType.jpeg.identifier as CFString, 1, nil) else { return nil }
+    CGImageDestinationAddImage(dest, out, [kCGImageDestinationLossyCompressionQuality: 0.6] as CFDictionary)
+    guard CGImageDestinationFinalize(dest) else { return nil }
+    return data as Data
+  }
+
+  /// The app's windows in the scene in front: the main one, plus others the
+  /// app shows (alerts, toasts), low to high. Never the keyboard.
+  static func appWindows() -> (main: UIWindow?, all: [UIWindow], frame: CGRect) {
+    let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
+    let scene = scenes.first { $0.activationState == .foregroundActive && $0.windows.contains { $0.isKeyWindow } }
+      ?? scenes.first { $0.activationState == .foregroundActive }
+    var windows = scene?.windows ?? []
+    if windows.isEmpty { windows = UIApplication.shared.windows }
+    // Every app window that shows, at any level (an app can put its own window
+    // at .alert), but not the keyboard or the system's own windows.
+    let shown = windows.filter { w in
+      let name = NSStringFromClass(type(of: w))
+      return !w.isHidden && w.alpha > 0
+        && !name.contains("Keyboard") && !name.contains("TextEffects") && !name.contains("StatusBar")
+        && !name.hasPrefix("_UI") && !name.contains("RemoteKeyboard")
+    }.sorted { $0.windowLevel.rawValue < $1.windowLevel.rawValue }
+    let main = shown.first { $0.isKeyWindow && $0.windowLevel == .normal } ?? shown.first { $0.windowLevel == .normal } ?? shown.first
+    let frame = scene?.coordinateSpace.bounds ?? main?.bounds ?? .zero
+    return (main, shown, frame)
+  }
+
+  // MARK: test hook
+
+  /// The testID for a boxed view: its own, or the nearest parent's when the box
+  /// covers most of that parent (RN puts testID on a wrapper, like an image's).
+  static func probeID(_ v: UIView, _ box: CGRect) -> String {
+    if let id = v.accessibilityIdentifier, !id.isEmpty { return id }
+    let mine = v.convert(v.bounds, to: nil)
+    var p = v.superview
+    while let parent = p {
+      if let id = parent.accessibilityIdentifier, !id.isEmpty {
+        let theirs = parent.convert(parent.bounds, to: nil)
+        return mine.width * mine.height >= theirs.width * theirs.height * 0.8 ? id : ""
+      }
+      p = parent.superview
+    }
+    return ""
+  }
+
+  func probe(_ done: @escaping ([String: Any]) -> Void) {
+    let found = Self.appWindows()
+    let walk = BuoyWalker.walk(found.all, in: found.frame, settings: masks, budgetMs: 200)
+    var parts: [[String: Any]] = []
+    for w in found.all {
+      var stack: [UIView] = [w]
+      while let v = stack.popLast() {
+        if let r = walk.parts[ObjectIdentifier(v)] {
+          var part: [String: Any] = ["testID": Self.probeID(v, r), "cls": NSStringFromClass(type(of: v)), "x": r.minX, "y": r.minY, "w": r.width, "h": r.height]
+          parts.append(part)
+        }
+        stack += v.subviews
+      }
+    }
+    let wasFrozen = frozen
+    frozen = false
+    take(kind: "last", attempts: 1) { [weak self] ok in
+      guard let self else { return }
+      self.frozen = wasFrozen
+      done(["ok": ok, "reason": ok ? NSNull() : (self.lastReason ?? NSNull()), "parts": parts,
+            "failed": walk.failed ?? NSNull(), "buoyOpen": walk.buoyOpen,
+            "jpeg": ok ? (self.last?.jpeg.base64EncodedString() ?? NSNull()) : NSNull(),
+            "w": found.frame.width, "h": found.frame.height])
+    }
+  }
+}
+
+/// Watches touches without taking them: it never recognizes, so the app's own
+/// gestures and RN's touch handling see every touch as before.
+final class BuoyTapWatcher: UIGestureRecognizer {
+  var onBegan: ((UIView?) -> Void)?
+  var onEnded: (() -> Void)?
+  override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent) {
+    onBegan?(touches.first?.view)
+  }
+  override func touchesEnded(_ touches: Set<UITouch>, with event: UIEvent) {
+    onEnded?()
+    state = .failed // never recognizes; failing resets it for the next touch
+  }
+  override func touchesCancelled(_ touches: Set<UITouch>, with event: UIEvent) { state = .failed }
+  override func canPrevent(_ g: UIGestureRecognizer) -> Bool { false }
+  override func canBePrevented(by g: UIGestureRecognizer) -> Bool { false }
+}
+
+/// Runs a block once, on the next display tick.
+final class BuoyNextTick: NSObject {
+  private var link: CADisplayLink?
+  private var block: (() -> Void)?
+  private static var live = Set<BuoyNextTick>()
+  static func after(_ block: @escaping () -> Void) {
+    let n = BuoyNextTick()
+    n.block = block
+    let l = CADisplayLink(target: n, selector: #selector(fire))
+    n.link = l
+    live.insert(n)
+    l.add(to: .main, forMode: .common)
+  }
+  @objc private func fire() {
+    link?.invalidate(); link = nil
+    Self.live.remove(self)
+    let b = block; block = nil
+    b?()
+  }
+}
+
+/// CADisplayLink keeps its target alive; this keeps the engine out of that loop.
+@available(iOSApplicationExtension, unavailable)
+final class BuoyLinkProxy: NSObject {
+  weak var engine: BuoyFrameEngine?
+  init(_ e: BuoyFrameEngine) { engine = e }
+  @objc func tick() { engine?.videoTick() }
+}