@quiesco/native 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,877 @@
1
+ import ExpoModulesCore
2
+ import UIKit
3
+ import WebKit
4
+
5
+ /**
6
+ * Real touch / text input inside the app process (requirements.md §6.3, docs/spikes/04-ios-touch.md).
7
+ * Uses private UIKit / IOKit API through QSTouchInjector: e2e builds only.
8
+ * Targets are addressed by React view tag (Fabric sets `UIView.tag`); positions are read from the view
9
+ * itself so native-driver animations count. Coordinates exchanged with JS are points in the window of
10
+ * the view, the same space as `getBoundingClientRect()` (no density conversion on iOS).
11
+ */
12
+ public class QuiescoNativeModule: Module {
13
+ static let doubleTapGapMs = 80
14
+ static let stepMs = 16
15
+
16
+ public func definition() -> ModuleDefinition {
17
+ Name("QuiescoNative")
18
+
19
+ OnCreate {
20
+ KeyboardMotion.shared.start()
21
+ DispatchQueue.main.async { NativeSettleMonitor.shared.start() }
22
+ Self.deliverLaunchUrl()
23
+ }
24
+
25
+ /**
26
+ * `app.device.setOrientation()` (Phase 6.6): rotate the app's window scene with a geometry request
27
+ * (simctl has no rotation command). Resolves with "" when requested, or iOS's error (e.g. the app
28
+ * does not support that orientation). The window's size changes right after; the host waits for it.
29
+ */
30
+ AsyncFunction("setOrientation") { (landscape: Bool, promise: Promise) in
31
+ guard let scene = UIApplication.shared.connectedScenes.compactMap({ $0 as? UIWindowScene }).first else {
32
+ promise.resolve("the app has no window scene")
33
+ return
34
+ }
35
+ scene.keyWindow?.rootViewController?.setNeedsUpdateOfSupportedInterfaceOrientations()
36
+ let mask: UIInterfaceOrientationMask = landscape ? .landscapeRight : .portrait
37
+ var settled = false
38
+ scene.requestGeometryUpdate(.iOS(interfaceOrientations: mask)) { error in
39
+ // Called only when the request fails.
40
+ guard !settled else { return }
41
+ settled = true
42
+ promise.resolve(error.localizedDescription)
43
+ }
44
+ // A successful request has no callback: report it on the next run loop turn.
45
+ DispatchQueue.main.async {
46
+ guard !settled else { return }
47
+ settled = true
48
+ promise.resolve("")
49
+ }
50
+ }.runOnQueue(.main)
51
+
52
+ /**
53
+ * `app.device.sendToBackground()` (Phase 6.5): leave for the home screen like the Home button, via
54
+ * the private `-[UIApplication suspend]` (e2e builds only). `simctl launch` brings the app back.
55
+ */
56
+ AsyncFunction("suspend") { () -> Bool in
57
+ let sel = NSSelectorFromString("suspend")
58
+ guard UIApplication.shared.responds(to: sel) else { return false }
59
+ UIApplication.shared.perform(sel)
60
+ return true
61
+ }.runOnQueue(.main)
62
+
63
+ /**
64
+ * `app.device.clipboard` (Phase 6.6). Written from inside the app: text another process put on the
65
+ * pasteboard (`simctl pbcopy`) makes iOS ask the user before the app may read it (spike 6.6), while
66
+ * the app reads what it wrote itself without asking. "" when the pasteboard holds no text.
67
+ */
68
+ AsyncFunction("getClipboard") { () -> String in
69
+ return UIPasteboard.general.string ?? ""
70
+ }.runOnQueue(.main)
71
+
72
+ AsyncFunction("setClipboard") { (text: String) in
73
+ UIPasteboard.general.string = text
74
+ }.runOnQueue(.main)
75
+
76
+ /**
77
+ * Synchronous (JS thread): whether native UI is still settling — a view controller transition in
78
+ * a window (navigation push / pop, Modal presentation) or the keyboard moving / just used. Sampled
79
+ * on the main thread every frame; read by the agent's `native` idle tracker.
80
+ */
81
+ Function("idleState") { () -> [String: Any] in
82
+ let s = NativeSettleMonitor.shared.snapshot()
83
+ return ["settling": !s.isEmpty, "reasons": s]
84
+ }
85
+
86
+ // docs/spikes/05: `xcrun simctl launch <udid> <bundle> -quiescoPort <p> -quiescoSession <id>`;
87
+ // "-key value" launch arguments land in UserDefaults' NSArgumentDomain.
88
+ // `quiescoArgs`: base64 of the test's launch arguments as JSON (Phase 6.5).
89
+ Function("getLaunchParams") { () -> [String: String?] in
90
+ let d = UserDefaults.standard
91
+ return ["port": d.string(forKey: "quiescoPort"), "session": d.string(forKey: "quiescoSession"), "args": d.string(forKey: "quiescoArgs")]
92
+ }
93
+
94
+ /** Where a view really is, and whether a touch at its center would reach it. */
95
+ /**
96
+ * Show / hide the scroll indicators of the UIScrollView of `tag` (Phase 6.9 full-page screenshots).
97
+ * Returns what they were: 1 shown, 0 hidden, -1 no scroll view.
98
+ */
99
+ AsyncFunction("setScrollIndicators") { (tag: Int, visible: Bool) -> Int in
100
+ guard let root = QSTouchInjector.view(withReactTag: tag) else { return -1 }
101
+ var queue: [UIView] = [root]
102
+ while !queue.isEmpty {
103
+ let v = queue.removeFirst()
104
+ if let sv = v as? UIScrollView {
105
+ let was = sv.showsVerticalScrollIndicator ? 1 : 0
106
+ sv.showsVerticalScrollIndicator = visible
107
+ sv.showsHorizontalScrollIndicator = visible
108
+ return was
109
+ }
110
+ queue.append(contentsOf: v.subviews)
111
+ }
112
+ return -1
113
+ }.runOnQueue(.main)
114
+
115
+ // ---- Phase 6.8 WebView (spike) ----
116
+
117
+ /** The WKWebView inside the React view `tag` (react-native-webview): its rect in the window and load state. */
118
+ AsyncFunction("webviewInfo") { (tag: Int) -> [String: Any] in
119
+ guard let web = Self.webView(tag), let window = web.window else { return ["found": false] }
120
+ let r = web.convert(web.bounds, to: window)
121
+ let inset = web.scrollView.adjustedContentInset
122
+ return [
123
+ "found": true, "x": r.minX, "y": r.minY, "width": r.width, "height": r.height,
124
+ "insetTop": inset.top, "insetLeft": inset.left, "zoom": web.scrollView.zoomScale,
125
+ "loading": web.isLoading, "progress": web.estimatedProgress,
126
+ "url": web.url?.absoluteString ?? "", "title": web.title ?? "",
127
+ ]
128
+ }.runOnQueue(.main)
129
+
130
+ /** Evaluate `script` (an expression) in the page's main frame; resolves with its value as a string (JSON by the caller). */
131
+ AsyncFunction("webviewEval") { (tag: Int, script: String, promise: Promise) in
132
+ guard let web = Self.webView(tag) else {
133
+ promise.reject("E_NO_VIEW", "no WebView in view \(tag)")
134
+ return
135
+ }
136
+ web.evaluateJavaScript(script) { result, error in
137
+ if let error = error {
138
+ promise.reject("E_SCRIPT", error.localizedDescription)
139
+ return
140
+ }
141
+ promise.resolve(result.map { "\($0)" } ?? "")
142
+ }
143
+ }.runOnQueue(.main)
144
+
145
+ /** Run `source` at document start of every later page load in this WebView (main frame). */
146
+ AsyncFunction("webviewAddStartScript") { (tag: Int, source: String) -> Bool in
147
+ guard let web = Self.webView(tag) else { return false }
148
+ web.configuration.userContentController.addUserScript(WKUserScript(source: source, injectionTime: .atDocumentStart, forMainFrameOnly: true))
149
+ return true
150
+ }.runOnQueue(.main)
151
+
152
+ AsyncFunction("locate") { (tag: Int) -> [String: Any] in
153
+ guard let view = QSTouchInjector.view(withReactTag: tag), view.window != nil else { return ["found": false] }
154
+ return Self.describe(view)
155
+ }.runOnQueue(.main)
156
+
157
+ /** Like `locate`'s reach fields, for a window point of `tag`'s window (taps at a point). */
158
+ AsyncFunction("hitAt") { (tag: Int, x: Double, y: Double) -> [String: Any] in
159
+ return Self.hit(tag: tag, x: x, y: y) ?? ["found": false]
160
+ }.runOnQueue(.main)
161
+
162
+ /** Tap the center of `tag` (or the point `x`,`y` of the key window when tag < 0). */
163
+ AsyncFunction("tap") { (tag: Int, x: Double, y: Double, holdMs: Int, count: Int, promise: Promise) in
164
+ if let missing = QSTouchInjector.missingPrivateAPI() {
165
+ promise.reject("E_UNSUPPORTED", Self.unsupported(missing))
166
+ return
167
+ }
168
+ guard let resolved = Self.target(tag: tag, x: x, y: y) else {
169
+ promise.reject("E_NO_VIEW", "view \(tag) not found")
170
+ return
171
+ }
172
+ let (window, point) = resolved
173
+ var handled = true
174
+ // Phase 4.5 experiment: the first touch after the keyboard appears is swallowed; prime with a
175
+ // cancelled touch (a cancelled touch never completes a tap, even if delivered).
176
+ func one(_ i: Int) {
177
+ handled = (QSTouchInjector.touchDown(at: point, in: window, tapCount: UInt(i + 1)) != nil) && handled
178
+ DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(holdMs)) {
179
+ handled = QSTouchInjector.touchUp() && handled
180
+ if i + 1 < count {
181
+ DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(Self.doubleTapGapMs)) { one(i + 1) }
182
+ } else {
183
+ promise.resolve(["x": point.x, "y": point.y, "handled": handled, "windowHasFocus": Self.reaches(window, point, tag)])
184
+ }
185
+ }
186
+ }
187
+ one(0)
188
+ }.runOnQueue(.main)
189
+
190
+ /** Drag from (fromX, fromY) to (toX, toY) in the window of `tag` over `durationMs`. */
191
+ AsyncFunction("swipe") { (tag: Int, fromX: Double, fromY: Double, toX: Double, toY: Double, durationMs: Int, promise: Promise) in
192
+ if let missing = QSTouchInjector.missingPrivateAPI() {
193
+ promise.reject("E_UNSUPPORTED", Self.unsupported(missing))
194
+ return
195
+ }
196
+ guard let window = (tag >= 0 ? QSTouchInjector.view(withReactTag: tag)?.window : nil) ?? QSTouchInjector.keyWindow() else {
197
+ promise.reject("E_NO_VIEW", "no window for view \(tag)")
198
+ return
199
+ }
200
+ let steps = max(4, durationMs / Self.stepMs)
201
+ let interval = max(1, durationMs / steps)
202
+ var handled = QSTouchInjector.touchDown(at: CGPoint(x: fromX, y: fromY), in: window, tapCount: 1) != nil
203
+ func step(_ i: Int) {
204
+ let t = Double(i) / Double(steps)
205
+ let p = CGPoint(x: fromX + (toX - fromX) * t, y: fromY + (toY - fromY) * t)
206
+ if i < steps {
207
+ handled = QSTouchInjector.touchMove(to: p) && handled
208
+ DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(interval)) { step(i + 1) }
209
+ } else {
210
+ handled = QSTouchInjector.touchMove(to: p) && handled
211
+ handled = QSTouchInjector.touchUp() && handled
212
+ promise.resolve(["handled": handled])
213
+ }
214
+ }
215
+ DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(interval)) { step(1) }
216
+ }.runOnQueue(.main)
217
+
218
+ /**
219
+ * One finger along a timed path in the window of `tag` (key window when tag < 0): `path` is flat
220
+ * [x, y, tMs, x, y, tMs, ...] with t from 0, increasing. Down at the first point, up at the last;
221
+ * moves are interpolated every `stepMs` between points that differ, none while the finger rests
222
+ * (a hold). Covers taps / long presses at a point, press-and-drag and swipes from a start point.
223
+ */
224
+ AsyncFunction("gesture") { (tag: Int, path: [Double], promise: Promise) in
225
+ if let missing = QSTouchInjector.missingPrivateAPI() {
226
+ promise.reject("E_UNSUPPORTED", Self.unsupported(missing))
227
+ return
228
+ }
229
+ guard path.count >= 6, path.count % 3 == 0 else {
230
+ promise.reject("E_BAD_ARGS", "path needs at least two [x, y, tMs] points")
231
+ return
232
+ }
233
+ guard let window = (tag >= 0 ? QSTouchInjector.view(withReactTag: tag)?.window : nil) ?? QSTouchInjector.keyWindow() else {
234
+ promise.reject("E_NO_VIEW", "no window for view \(tag)")
235
+ return
236
+ }
237
+ let points = stride(from: 0, to: path.count, by: 3).map { (CGPoint(x: path[$0], y: path[$0 + 1]), path[$0 + 2]) }
238
+ // Expand into timed events: (point, ms from start).
239
+ var events: [(CGPoint, Double)] = []
240
+ for i in 1..<points.count {
241
+ let (a, ta) = points[i - 1]
242
+ let (b, tb) = points[i]
243
+ let steps = a == b ? 1 : max(1, Int((tb - ta) / Double(Self.stepMs)))
244
+ for k in 1...steps {
245
+ let t = Double(k) / Double(steps)
246
+ events.append((CGPoint(x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t), ta + (tb - ta) * t))
247
+ }
248
+ }
249
+ let start = DispatchTime.now()
250
+ var handled = QSTouchInjector.touchDown(at: points[0].0, in: window, tapCount: 1) != nil
251
+ func fire(_ i: Int) {
252
+ let (p, _) = events[i]
253
+ if i == events.count - 1 {
254
+ handled = QSTouchInjector.touchMove(to: p) && handled
255
+ handled = QSTouchInjector.touchUp() && handled
256
+ promise.resolve(["handled": handled])
257
+ return
258
+ }
259
+ handled = QSTouchInjector.touchMove(to: p) && handled
260
+ DispatchQueue.main.asyncAfter(deadline: start + .milliseconds(Int(events[i + 1].1))) { fire(i + 1) }
261
+ }
262
+ DispatchQueue.main.asyncAfter(deadline: start + .milliseconds(Int(events[0].1))) { fire(0) }
263
+ }.runOnQueue(.main)
264
+
265
+ /**
266
+ * Several fingers along timed paths in the window of `tag` (key window when tag < 0). `frames` is flat:
267
+ * per frame [tMs, down0, x0, y0, down1, x1, y1, ...] for `fingerCount` fingers (down = 1 while the
268
+ * finger touches), t from 0 and increasing. A finger goes down in the first frame it is down, lifts
269
+ * in the first frame it is not; every finger is lifted after the last frame.
270
+ */
271
+ AsyncFunction("multiGesture") { (tag: Int, fingerCount: Int, frames: [Double], promise: Promise) in
272
+ if let missing = QSTouchInjector.missingPrivateAPI() {
273
+ promise.reject("E_UNSUPPORTED", Self.unsupported(missing))
274
+ return
275
+ }
276
+ let stride = 1 + 3 * fingerCount
277
+ guard fingerCount >= 1, frames.count >= stride, frames.count % stride == 0 else {
278
+ promise.reject("E_BAD_ARGS", "frames must be [t, down, x, y, ...] for \(fingerCount) fingers")
279
+ return
280
+ }
281
+ guard let window = (tag >= 0 ? QSTouchInjector.view(withReactTag: tag)?.window : nil) ?? QSTouchInjector.keyWindow() else {
282
+ promise.reject("E_NO_VIEW", "no window for view \(tag)")
283
+ return
284
+ }
285
+ let count = frames.count / stride
286
+ let start = DispatchTime.now()
287
+ func fire(_ f: Int) {
288
+ let base = f * stride
289
+ var points: [Any] = []
290
+ for i in 0..<fingerCount {
291
+ let o = base + 1 + 3 * i
292
+ points.append(frames[o] > 0.5 ? NSValue(cgPoint: CGPoint(x: frames[o + 1], y: frames[o + 2])) : NSNull())
293
+ }
294
+ QSTouchInjector.sendFingers(points, in: window)
295
+ if f + 1 < count {
296
+ DispatchQueue.main.asyncAfter(deadline: start + .milliseconds(Int(frames[(f + 1) * stride]))) { fire(f + 1) }
297
+ } else {
298
+ QSTouchInjector.liftAllFingers()
299
+ promise.resolve(["handled": true])
300
+ }
301
+ }
302
+ DispatchQueue.main.asyncAfter(deadline: start + .milliseconds(Int(frames[0]))) { fire(0) }
303
+ }.runOnQueue(.main)
304
+
305
+ /**
306
+ * A key of the software keyboard on the text field `tag`: `enter` (the return key: a single-line
307
+ * field asks its delegate `textFieldShouldReturn`, which is what UIKit does for the return key and
308
+ * where React Native submits; a multi-line field gets a newline through UIKeyInput, where RN applies
309
+ * its submit behavior) or `backspace` (UIKeyInput.deleteBackward, which RN reports to onKeyPress).
310
+ */
311
+ AsyncFunction("pressKey") { (tag: Int, key: String, promise: Promise) in
312
+ guard let view = QSTouchInjector.view(withReactTag: tag) else {
313
+ promise.reject("E_NO_VIEW", "view \(tag) not found")
314
+ return
315
+ }
316
+ guard let field = Self.findTextInput(view) else {
317
+ promise.reject("E_NOT_TEXT_INPUT", "view \(tag) is not a text field")
318
+ return
319
+ }
320
+ let focused = field.isFirstResponder || field.becomeFirstResponder()
321
+ switch key {
322
+ case "enter":
323
+ if let single = field as? UITextField {
324
+ _ = single.delegate?.textFieldShouldReturn?(single)
325
+ } else {
326
+ field.insertText("\n")
327
+ }
328
+ case "backspace":
329
+ field.deleteBackward()
330
+ default:
331
+ promise.reject("E_BAD_ARGS", "unknown key \(key)")
332
+ return
333
+ }
334
+ KeyboardMotion.shared.touch()
335
+ let current = field.textRange(from: field.beginningOfDocument, to: field.endOfDocument).flatMap { field.text(in: $0) } ?? ""
336
+ promise.resolve(["text": current, "focused": focused])
337
+ }.runOnQueue(.main)
338
+
339
+ /**
340
+ * Type into the text field `tag` through UIKeyInput (the path the software keyboard uses), so
341
+ * RN's delegate callbacks and onChangeText fire. `replace` clears the field first.
342
+ */
343
+ AsyncFunction("typeText") { (tag: Int, text: String, replace: Bool, promise: Promise) in
344
+ guard let view = QSTouchInjector.view(withReactTag: tag) else {
345
+ promise.reject("E_NO_VIEW", "view \(tag) not found")
346
+ return
347
+ }
348
+ guard let field = Self.findTextInput(view) else {
349
+ promise.reject("E_NOT_TEXT_INPUT", "view \(tag) is not a text field")
350
+ return
351
+ }
352
+ let focused = field.becomeFirstResponder()
353
+ if replace, let all = field.textRange(from: field.beginningOfDocument, to: field.endOfDocument), !all.isEmpty {
354
+ field.selectedTextRange = all
355
+ field.deleteBackward()
356
+ }
357
+ field.insertText(text)
358
+ KeyboardMotion.shared.touch()
359
+ let current = field.textRange(from: field.beginningOfDocument, to: field.endOfDocument).flatMap { field.text(in: $0) } ?? ""
360
+ promise.resolve(["text": current, "inputConnection": true, "focused": focused])
361
+ }.runOnQueue(.main)
362
+
363
+ /**
364
+ * Open a URL from inside the app. For the app's own scheme iOS routes it through the
365
+ * SceneDelegate to RN Linking without the confirmation alert `simctl openurl` shows
366
+ * (Phase 4.0 findings), so deep links behave as when a user follows one.
367
+ */
368
+ AsyncFunction("openUrl") { (url: String, promise: Promise) in
369
+ guard let u = URL(string: url), u.scheme != nil else {
370
+ promise.reject("E_BAD_URL", "invalid URL \(url)")
371
+ return
372
+ }
373
+ UIApplication.shared.open(u, options: [:]) { opened in promise.resolve(["opened": opened]) }
374
+ }.runOnQueue(.main)
375
+
376
+ /**
377
+ * Geometry of the UISlider in `tag`'s view: window x of the thumb center at the minimum and at the
378
+ * maximum value (UISlider insets its track by half a thumb), the thumb's current x and its y.
379
+ * UISlider only starts tracking on a touch near the thumb, so a drag must start at `thumbX`.
380
+ */
381
+ AsyncFunction("sliderInfo") { (tag: Int) -> [String: Any] in
382
+ guard let view = QSTouchInjector.view(withReactTag: tag), let window = view.window,
383
+ let slider = Self.find(UISlider.self, in: view) else { return ["found": false] }
384
+ let track = slider.trackRect(forBounds: slider.bounds)
385
+ func center(_ value: Float) -> CGPoint {
386
+ let r = slider.thumbRect(forBounds: slider.bounds, trackRect: track, value: value)
387
+ return slider.convert(CGPoint(x: r.midX, y: r.midY), to: window)
388
+ }
389
+ let lo = center(slider.minimumValue)
390
+ let hi = center(slider.maximumValue)
391
+ let cur = center(slider.value)
392
+ return [
393
+ "found": true, "minX": lo.x, "maxX": hi.x, "y": cur.y, "thumbX": cur.x,
394
+ "value": slider.value, "minimum": slider.minimumValue, "maximum": slider.maximumValue,
395
+ ]
396
+ }.runOnQueue(.main)
397
+
398
+ /**
399
+ * The wheels (UIPickerView, also the one inside a UIDatePicker in wheels style) in `tag`'s view: per
400
+ * component the selected row, row count, row height, the column's window rect and the selected row's
401
+ * title; for a UIDatePicker also its date (ms since epoch). `tree` lists the picker's view hierarchy
402
+ * (diagnostics: column views are private UIKit classes).
403
+ */
404
+ AsyncFunction("wheelInfo") { (tag: Int) -> [String: Any] in
405
+ guard let view = QSTouchInjector.view(withReactTag: tag), let window = view.window else { return ["found": false] }
406
+ guard let picker = Self.find(UIPickerView.self, in: view) else {
407
+ return ["found": false, "tree": Self.viewTree(view, depth: 0, maxDepth: 8)]
408
+ }
409
+ let columns = Self.columnViews(picker, in: window)
410
+ var components: [[String: Any]] = []
411
+ for c in 0..<picker.numberOfComponents {
412
+ let row = picker.selectedRow(inComponent: c)
413
+ var item: [String: Any] = [
414
+ "selectedRow": row,
415
+ "rows": picker.numberOfRows(inComponent: c),
416
+ "rowHeight": picker.rowSize(forComponent: c).height,
417
+ "title": Self.title(picker, row: row, component: c) ?? NSNull(),
418
+ ]
419
+ if c < columns.count {
420
+ let r = columns[c]
421
+ item["x"] = r.origin.x; item["y"] = r.origin.y; item["width"] = r.size.width; item["height"] = r.size.height
422
+ }
423
+ components.append(item)
424
+ }
425
+ let pr = picker.convert(picker.bounds, to: window)
426
+ // A wheel is moving while one of its scroll views is tracking a finger, dragging or decelerating
427
+ // (UIDatePicker.date and selectedRow update only once it stops).
428
+ var moving = false
429
+ var queue: [UIView] = [picker]
430
+ while let v = queue.popLast() {
431
+ if let sv = v as? UIScrollView, sv.isTracking || sv.isDragging || sv.isDecelerating || !(sv.layer.animationKeys() ?? []).isEmpty { moving = true; break }
432
+ queue.append(contentsOf: v.subviews)
433
+ }
434
+ var out: [String: Any] = [
435
+ "found": true, "components": components, "columnCount": columns.count, "moving": moving,
436
+ "x": pr.origin.x, "y": pr.origin.y, "width": pr.size.width, "height": pr.size.height,
437
+ "tree": Self.viewTree(picker, depth: 0, maxDepth: 6),
438
+ ]
439
+ if let dp = Self.ancestor(UIDatePicker.self, of: picker) {
440
+ out["date"] = dp.date.timeIntervalSince1970 * 1000
441
+ out["datePickerMode"] = dp.datePickerMode.rawValue
442
+ out["locale"] = (dp.locale ?? Locale.current).identifier
443
+ }
444
+ return out
445
+ }.runOnQueue(.main)
446
+
447
+ /**
448
+ * Perform the accessibility action `name` on `tag`'s view the way VoiceOver does: `increment` /
449
+ * `decrement` through UIAccessibilityAction (the adjustable swipe), `magicTap` / `escape` through
450
+ * their perform methods, any other through the view's accessibilityCustomActions (the VoiceOver
451
+ * "Actions" rotor) at `index` — React Native lists every declared action there, named by its label
452
+ * (`label`, or the name when it has none).
453
+ */
454
+ AsyncFunction("accessibilityAction") { (tag: Int, name: String, label: String, index: Int, _customIndex: Int, promise: Promise) in
455
+ guard let view = QSTouchInjector.view(withReactTag: tag) else {
456
+ promise.reject("E_NO_VIEW", "view \(tag) not found")
457
+ return
458
+ }
459
+ switch name {
460
+ case "increment":
461
+ view.accessibilityIncrement()
462
+ promise.resolve(["performed": true, "via": "accessibilityIncrement"])
463
+ case "decrement":
464
+ view.accessibilityDecrement()
465
+ promise.resolve(["performed": true, "via": "accessibilityDecrement"])
466
+ case "magicTap":
467
+ promise.resolve(["performed": view.accessibilityPerformMagicTap(), "via": "accessibilityPerformMagicTap"])
468
+ case "escape":
469
+ promise.resolve(["performed": view.accessibilityPerformEscape(), "via": "accessibilityPerformEscape"])
470
+ default:
471
+ let actions = view.accessibilityCustomActions ?? []
472
+ let byIndex = index >= 0 && index < actions.count && actions[index].name == label ? actions[index] : nil
473
+ guard let action = byIndex ?? actions.first(where: { $0.name == label }) else {
474
+ promise.reject("E_NO_ACTION", "view \(tag) has no accessibility custom action \"\(label)\" (has: \(actions.map { $0.name }))")
475
+ return
476
+ }
477
+ var performed = false
478
+ if let handler = action.actionHandler {
479
+ performed = handler(action)
480
+ } else if let target = action.target as? NSObject, target.responds(to: action.selector) {
481
+ _ = target.perform(action.selector, with: action)
482
+ performed = true
483
+ }
484
+ promise.resolve(["performed": performed, "via": "accessibilityCustomActions"])
485
+ }
486
+ }.runOnQueue(.main)
487
+ }
488
+
489
+ // MARK: - helpers (main thread)
490
+
491
+ /**
492
+ * `app.device.relaunch({ url })` (Phase 6.5): `-quiescoUrl <url>` at launch becomes the URL the app was
493
+ * opened with. The dev client takes `--initialUrl` as the bundle URL, and `simctl openurl` shows a
494
+ * confirmation alert and cannot pass launch arguments, so the link is handed to expo-linking's
495
+ * app-delegate subscriber (what expo-router reads on iOS: `getLinkingURL()`) before JS renders. Looked up
496
+ * at runtime: no build dependency on expo-linking. React Native's `Linking.getInitialURL()` reads launch
497
+ * options and does not see it (platforms.md).
498
+ */
499
+ static func deliverLaunchUrl() {
500
+ guard let raw = UserDefaults.standard.string(forKey: "quiescoUrl"), let url = URL(string: raw) else { return }
501
+ // App-delegate subscribers are @MainActor (creating one off the main thread traps); OnCreate runs on
502
+ // the module registry's thread, before the bundle runs. Async to main: in the Phase 6.5 spike it
503
+ // always landed before expo-router's first read (the main queue is free while JS starts).
504
+ DispatchQueue.main.async {
505
+ guard let cls = NSClassFromString("ExpoLinking.LinkingAppDelegateSubscriber") as? NSObject.Type,
506
+ let subscriber = cls.init() as? UIApplicationDelegate else {
507
+ NSLog("[quiesco] -quiescoUrl given but expo-linking's LinkingAppDelegateSubscriber was not found")
508
+ return
509
+ }
510
+ _ = subscriber.application?(UIApplication.shared, open: url, options: [:])
511
+ NSLog("[quiesco] launch URL delivered to expo-linking: \(raw)")
512
+ }
513
+ }
514
+
515
+ static func unsupported(_ missing: String) -> String {
516
+ let version = UIDevice.current.systemVersion
517
+ return "touch injection needs private UIKit API that iOS \(version) does not have (\(missing)); use actions.mode 'js'"
518
+ }
519
+
520
+ static func webView(_ tag: Int) -> WKWebView? {
521
+ guard let root = QSTouchInjector.view(withReactTag: tag) else { return nil }
522
+ var queue: [UIView] = [root]
523
+ while !queue.isEmpty {
524
+ let v = queue.removeFirst()
525
+ if let w = v as? WKWebView { return w }
526
+ queue.append(contentsOf: v.subviews)
527
+ }
528
+ return nil
529
+ }
530
+
531
+ static func target(tag: Int, x: Double, y: Double) -> (UIWindow, CGPoint)? {
532
+ if tag < 0 {
533
+ guard let w = QSTouchInjector.keyWindow() else { return nil }
534
+ return (w, CGPoint(x: x, y: y))
535
+ }
536
+ guard let view = QSTouchInjector.view(withReactTag: tag), let window = view.window else { return nil }
537
+ let r = view.convert(view.bounds, to: window)
538
+ return (window, CGPoint(x: r.midX, y: r.midY))
539
+ }
540
+
541
+ /** Whether the topmost view at `point` (across all windows) belongs to the view `tag`. */
542
+ static func reaches(_ window: UIWindow, _ point: CGPoint, _ tag: Int) -> Bool {
543
+ let top = topmostHit(window.convert(point, to: nil))
544
+ guard let target = tag >= 0 ? QSTouchInjector.view(withReactTag: tag) : nil else { return top?.window === window }
545
+ guard let hit = top else { return false }
546
+ return hit.isDescendant(of: target) || target.isDescendant(of: hit)
547
+ }
548
+
549
+ /** Hit test from the front-most window down, in screen coordinates. */
550
+ static func topmostHit(_ screenPoint: CGPoint) -> UIView? {
551
+ for w in QSTouchInjector.windows().reversed() {
552
+ let p = w.convert(screenPoint, from: nil)
553
+ if let hit = w.hitTest(p, with: nil) { return hit }
554
+ }
555
+ return nil
556
+ }
557
+
558
+ static func describe(_ view: UIView) -> [String: Any] {
559
+ let window = view.window!
560
+ let r = view.convert(view.bounds, to: window)
561
+ let center = CGPoint(x: r.midX, y: r.midY)
562
+ let top = topmostHit(window.convert(center, to: nil))
563
+ let reaches = top.map { $0.isDescendant(of: view) || view.isDescendant(of: $0) } ?? false
564
+ var shown = true
565
+ var v: UIView? = view
566
+ while let cur = v {
567
+ if cur.isHidden || cur.alpha <= 0.01 { shown = false; break }
568
+ v = cur.superview
569
+ }
570
+ let windows = QSTouchInjector.windows()
571
+ let transitioning = isTransitioning(window)
572
+ let animating = hasRunningAnimation(view)
573
+ let keyboardMoving = KeyboardMotion.shared.moving || KeyboardMotion.shared.recentlyActive
574
+ return [
575
+ // UIKit ignores touches during a view controller transition (e.g. a Modal fading in), and a
576
+ // Core Animation on the view or an ancestor changes what is on screen without a layout change.
577
+ // The software keyboard slides in / out in its own window, which can cover the view mid-way, and
578
+ // iOS drops touches right after keyboard activity (KeyboardMotion.quietSeconds).
579
+ "settling": transitioning || animating || keyboardMoving,
580
+ "keyboardMoving": keyboardMoving,
581
+ "animatingLayers": runningAnimations(view),
582
+ "transitioning": transitioning,
583
+ "animating": animating,
584
+ "found": true,
585
+ "x": r.origin.x, "y": r.origin.y, "width": r.size.width, "height": r.size.height,
586
+ "shown": shown,
587
+ // iOS: RN Modals are presented in the same window, so "focus" is decided by a real hit test at
588
+ // the center: false when another view (a Modal, an overlay, another window) would get the touch.
589
+ "windowHasFocus": reaches,
590
+ "windowIndex": windows.firstIndex(of: window) ?? -1,
591
+ "windowCount": windows.count,
592
+ "windowClass": String(describing: type(of: window)),
593
+ "hitClass": top.map { String(describing: type(of: $0)) } ?? "",
594
+ // Diagnostics for ELEMENT_OBSCURED: the hit view up to its window, and the presented controllers.
595
+ "hitChain": top.map(superviewChain) ?? [],
596
+ // React tags from the hit view up. Fabric does not mount every React child inside its React
597
+ // parent's native view (children of views that form no stacking context are mounted higher up),
598
+ // so "is the hit view a native descendant" is not enough: JS compares these tags with the
599
+ // element's React subtree.
600
+ "hitTags": top.map(tagChain) ?? [],
601
+ "presented": presentedChain(window),
602
+ ]
603
+ }
604
+
605
+ /** `tag` of the hit view and its superviews (React tags on Fabric component views; 0 for plain UIKit views). */
606
+ static func tagChain(_ view: UIView) -> [Int] {
607
+ var out: [Int] = []
608
+ var v: UIView? = view
609
+ while let cur = v, out.count < 40 {
610
+ out.append(cur.tag)
611
+ v = cur.superview
612
+ }
613
+ return out
614
+ }
615
+
616
+ /** Who would receive a touch at the window point (x, y) of `tag`'s window. */
617
+ static func hit(tag: Int, x: Double, y: Double) -> [String: Any]? {
618
+ guard let view = QSTouchInjector.view(withReactTag: tag), let window = view.window else { return nil }
619
+ let top = topmostHit(window.convert(CGPoint(x: x, y: y), to: nil))
620
+ let reaches = top.map { $0.isDescendant(of: view) || view.isDescendant(of: $0) } ?? false
621
+ return [
622
+ "windowHasFocus": reaches,
623
+ "hitClass": top.map { String(describing: type(of: $0)) } ?? "",
624
+ "hitChain": top.map(superviewChain) ?? [],
625
+ "hitTags": top.map(tagChain) ?? [],
626
+ ]
627
+ }
628
+
629
+ /** A view controller of this window is being presented / dismissed, or has a running transition. */
630
+ static func isTransitioning(_ window: UIWindow) -> Bool {
631
+ guard let root = window.rootViewController else { return false }
632
+ return isTransitioning(root, depth: 0)
633
+ }
634
+
635
+ /**
636
+ * The whole view controller tree: react-native-screens nests its UINavigationController several
637
+ * levels below the root, and UIKit refuses to present a Modal while a push / pop is running (the
638
+ * Modal then never appears), so a tap must wait for those transitions too.
639
+ */
640
+ static func isTransitioning(_ vc: UIViewController, depth: Int) -> Bool {
641
+ if depth > 32 { return false }
642
+ if vc.transitionCoordinator != nil || vc.isBeingPresented || vc.isBeingDismissed || vc.isMovingToParent || vc.isMovingFromParent {
643
+ return true
644
+ }
645
+ for child in vc.children where isTransitioning(child, depth: depth + 1) { return true }
646
+ if let presented = vc.presentedViewController, presented.presentingViewController === vc {
647
+ return isTransitioning(presented, depth: depth + 1)
648
+ }
649
+ return false
650
+ }
651
+
652
+ /** A Core Animation is attached to the view or one of its ancestors (fades, presentation slides). */
653
+ static func hasRunningAnimation(_ view: UIView) -> Bool {
654
+ var v: UIView? = view
655
+ while let cur = v {
656
+ if let keys = cur.layer.animationKeys(), !keys.isEmpty { return true }
657
+ v = cur.superview
658
+ }
659
+ return false
660
+ }
661
+
662
+ static func superviewChain(_ view: UIView) -> [String] {
663
+ var out: [String] = []
664
+ var v: UIView? = view
665
+ while let cur = v, out.count < 12 {
666
+ let f = cur.frame
667
+ out.append("\(String(describing: type(of: cur)))(\(Int(f.minX)),\(Int(f.minY)),\(Int(f.width))x\(Int(f.height)))")
668
+ v = cur.superview
669
+ }
670
+ return out
671
+ }
672
+
673
+ static func presentedChain(_ window: UIWindow) -> [String] {
674
+ var out: [String] = []
675
+ var vc = window.rootViewController
676
+ while let cur = vc, out.count < 8 {
677
+ out.append(String(describing: type(of: cur)))
678
+ vc = cur.presentedViewController
679
+ }
680
+ return out
681
+ }
682
+
683
+ /** Diagnostics: "<view class>: <animation keys>" for the view and its ancestors. */
684
+ static func runningAnimations(_ view: UIView) -> [String] {
685
+ var out: [String] = []
686
+ var v: UIView? = view
687
+ while let cur = v {
688
+ if let keys = cur.layer.animationKeys(), !keys.isEmpty {
689
+ out.append("\(String(describing: type(of: cur))): \(keys.joined(separator: ","))")
690
+ }
691
+ v = cur.superview
692
+ }
693
+ return out
694
+ }
695
+
696
+ /** The first view of class `T` in `view`'s subtree, breadth first (the view itself included). */
697
+ static func find<T: UIView>(_ type: T.Type, in view: UIView) -> T? {
698
+ var queue: [UIView] = [view]
699
+ var i = 0
700
+ while i < queue.count {
701
+ if let hit = queue[i] as? T { return hit }
702
+ queue.append(contentsOf: queue[i].subviews)
703
+ i += 1
704
+ }
705
+ return nil
706
+ }
707
+
708
+ static func ancestor<T: UIView>(_ type: T.Type, of view: UIView) -> T? {
709
+ var v: UIView? = view
710
+ while let cur = v {
711
+ if let hit = cur as? T { return hit }
712
+ v = cur.superview
713
+ }
714
+ return nil
715
+ }
716
+
717
+ /**
718
+ * Where each column of a picker takes touches, left to right in component order: window rects whose
719
+ * x range is found by hit testing along the selection band. The column views are private
720
+ * (`UIPickerColumnView`), all span the whole picker and are laid out with 3D transforms, so their
721
+ * frames do not tell where a column is (measured on iOS 27); a hit test does. `.zero` when a column
722
+ * takes no touch at any x.
723
+ */
724
+ static func columnViews(_ picker: UIPickerView, in window: UIWindow) -> [CGRect] {
725
+ var columns: [UIView] = []
726
+ func walk(_ v: UIView) {
727
+ for sub in v.subviews {
728
+ if String(describing: type(of: sub)).contains("PickerColumnView") { columns.append(sub) } else { walk(sub) }
729
+ }
730
+ }
731
+ walk(picker)
732
+ let pr = picker.convert(picker.bounds, to: window)
733
+ var lo = [CGFloat](repeating: .infinity, count: columns.count)
734
+ var hi = [CGFloat](repeating: -.infinity, count: columns.count)
735
+ var x = pr.minX + 1
736
+ while x < pr.maxX {
737
+ if let hit = window.hitTest(CGPoint(x: x, y: pr.midY), with: nil) {
738
+ var v: UIView? = hit
739
+ while let cur = v, cur !== picker {
740
+ if let i = columns.firstIndex(where: { $0 === cur }) {
741
+ lo[i] = min(lo[i], x)
742
+ hi[i] = max(hi[i], x)
743
+ break
744
+ }
745
+ v = cur.superview
746
+ }
747
+ }
748
+ x += 2
749
+ }
750
+ return columns.indices.map { i in
751
+ lo[i] <= hi[i] ? CGRect(x: lo[i], y: pr.minY, width: hi[i] - lo[i], height: pr.height) : .zero
752
+ }
753
+ }
754
+
755
+ /** Title of a row: the delegate's title, else the text of the labels in the row's view. */
756
+ static func title(_ picker: UIPickerView, row: Int, component: Int) -> String? {
757
+ if row < 0 { return nil }
758
+ if let d = picker.delegate {
759
+ if let t = d.pickerView?(picker, titleForRow: row, forComponent: component) { return t }
760
+ if let t = d.pickerView?(picker, attributedTitleForRow: row, forComponent: component) { return t.string }
761
+ }
762
+ guard let rowView = picker.view(forRow: row, forComponent: component) else { return nil }
763
+ var texts: [String] = []
764
+ func walk(_ v: UIView) {
765
+ if let l = v as? UILabel, let t = l.text, !t.isEmpty { texts.append(t) }
766
+ v.subviews.forEach(walk)
767
+ }
768
+ walk(rowView)
769
+ return texts.isEmpty ? nil : texts.joined(separator: " ")
770
+ }
771
+
772
+ static func viewTree(_ view: UIView, depth: Int, maxDepth: Int) -> [String] {
773
+ let f = view.frame
774
+ var out = ["\(String(repeating: " ", count: depth))\(String(describing: type(of: view)))(\(Int(f.minX)),\(Int(f.minY)),\(Int(f.width))x\(Int(f.height)))"]
775
+ if depth < maxDepth {
776
+ for sub in view.subviews.prefix(12) { out.append(contentsOf: viewTree(sub, depth: depth + 1, maxDepth: maxDepth)) }
777
+ }
778
+ return out
779
+ }
780
+
781
+ static func findTextInput(_ view: UIView) -> (UIView & UITextInput)? {
782
+ if let f = view as? UITextField { return f }
783
+ if let t = view as? UITextView { return t }
784
+ for sub in view.subviews {
785
+ if let f = findTextInput(sub) { return f }
786
+ }
787
+ return nil
788
+ }
789
+ }
790
+
791
+ /**
792
+ * Whether the software keyboard is sliding in or out: between UIKeyboardWill{Show,Hide} and the matching
793
+ * Did notification. Its window covers part of the screen while it moves; afterwards a hit test sees
794
+ * its final frame.
795
+ */
796
+ final class KeyboardMotion {
797
+ static let shared = KeyboardMotion()
798
+ private(set) var moving = false
799
+ /** Between UIKeyboardWillShow and UIKeyboardDidHide. */
800
+ private(set) var visible = false
801
+ /**
802
+ * iOS ignores touches outside the keyboard shortly after keyboard activity (typing, the keyboard
803
+ * appearing or changing): measured on iOS 27, a tap 0 ms after typing is dropped, 300 ms later it
804
+ * is delivered. Taps wait until the keyboard has been quiet for this long.
805
+ */
806
+ static let quietSeconds: CFTimeInterval = 0.4
807
+ private var lastActivity: CFTimeInterval = 0
808
+
809
+ /** Keyboard input happened (typeText) or the keyboard changed. */
810
+ func touch() {
811
+ lastActivity = CACurrentMediaTime()
812
+ }
813
+
814
+ /** Within the quiet period after keyboard activity, while the keyboard is shown. */
815
+ var recentlyActive: Bool {
816
+ visible && CACurrentMediaTime() - lastActivity < Self.quietSeconds
817
+ }
818
+ private var observers: [NSObjectProtocol] = []
819
+
820
+ func start() {
821
+ guard observers.isEmpty else { return }
822
+ let center = NotificationCenter.default
823
+ observers.append(center.addObserver(forName: UIResponder.keyboardWillShowNotification, object: nil, queue: .main) { [weak self] _ in
824
+ self?.moving = true
825
+ self?.visible = true
826
+ self?.touch()
827
+ })
828
+ observers.append(center.addObserver(forName: UIResponder.keyboardWillHideNotification, object: nil, queue: .main) { [weak self] _ in self?.moving = true; self?.touch() })
829
+ observers.append(center.addObserver(forName: UIResponder.keyboardDidShowNotification, object: nil, queue: .main) { [weak self] _ in self?.moving = false; self?.touch() })
830
+ // The keyboard also changes height while shown (e.g. a secure field switches the suggestion bar).
831
+ observers.append(center.addObserver(forName: UIResponder.keyboardWillChangeFrameNotification, object: nil, queue: .main) { [weak self] _ in self?.moving = true; self?.touch() })
832
+ observers.append(center.addObserver(forName: UIResponder.keyboardDidChangeFrameNotification, object: nil, queue: .main) { [weak self] _ in self?.moving = false; self?.touch() })
833
+ observers.append(center.addObserver(forName: UIResponder.keyboardDidHideNotification, object: nil, queue: .main) { [weak self] _ in
834
+ self?.moving = false
835
+ self?.visible = false
836
+ self?.touch()
837
+ })
838
+ }
839
+ }
840
+
841
+ /**
842
+ * Samples native settling state on the main thread every frame (CADisplayLink) and publishes it for
843
+ * synchronous reads from the JS thread. UIKit state must not be read off the main thread.
844
+ */
845
+ final class NativeSettleMonitor: NSObject {
846
+ static let shared = NativeSettleMonitor()
847
+ private var link: CADisplayLink?
848
+ private let lock = NSLock()
849
+ private var reasons: [String] = []
850
+
851
+ /** Main thread. */
852
+ func start() {
853
+ guard link == nil else { return }
854
+ let l = CADisplayLink(target: self, selector: #selector(tick))
855
+ l.add(to: .main, forMode: .common)
856
+ link = l
857
+ tick()
858
+ }
859
+
860
+ @objc private func tick() {
861
+ var r: [String] = []
862
+ for w in QSTouchInjector.windows() where QuiescoNativeModule.isTransitioning(w) {
863
+ r.append("view controller transition in \(String(describing: type(of: w)))")
864
+ }
865
+ if KeyboardMotion.shared.moving { r.append("keyboard moving") } else if KeyboardMotion.shared.recentlyActive { r.append("keyboard just used") }
866
+ lock.lock()
867
+ reasons = r
868
+ lock.unlock()
869
+ }
870
+
871
+ /** Any thread. Empty when settled. */
872
+ func snapshot() -> [String] {
873
+ lock.lock()
874
+ defer { lock.unlock() }
875
+ return reasons
876
+ }
877
+ }