11import Foundation
22import CoreGraphics
33
4- // Where a piece of geometry lives, and how it gets where the caller means it.
5- //
6- // DISPATCH: synthesized events skip XCTest's orientation handling, so a point planned in an app's
7- // interface space has to be rotated into the device's native (portrait-up) space before it is
8- // performed. Without that, a landscape tap lands somewhere else.
9- //
10- // CAPTURE: iOS hosts some system surfaces in that native space even while the app is rotated, so
11- // their whole subtree arrives quarter-turned. Measured on iPhone 17 Pro (iOS 26.2) with the system
12- // keyboard up in landscape: the app viewport is 874 x 402, `UIRemoteKeyboardWindow` reports its own
13- // box as 402 x 874, a key arrives 45 x 72 at x 154, and the key plane as 202 x 724 — a strip down
14- // the left edge — while the screenshot draws a 724 x 204 band docked at y 198, which is exactly
15- // what the live `app.keyboards` query measures. Rules that read the reported numbers refused app
16- // content the keyboard was nowhere near and let a tap through into a key (#2612, #2589).
17- //
18- // Both directions live in ONE table on purpose: capture rotates back with the exact inverse of what
19- // dispatch rotates forward, so a performed tap and a reported rect can never disagree about which
20- // pixel is which. The round-trip test in the package suite is that proof, not a comment asking for
21- // care. This file is pure geometry, which is why it lives here rather than in the XCTest bundle:
22- // nothing in it needs a simulator to run.
4+ // Rotation between an app's interface space and the device's native (portrait-up) space, shared by
5+ // synthesized dispatch (forward) and capture (inverse). Rationale and measurements: ADR 0004
6+ // "the coordinate space of a captured subtree" and contracts/fixtures/window-coordinate-space.json.
237
24- /// The UIInterfaceOrientation raw values the rotation table switches on. XCTest exposes the app's
25- /// interface orientation as an integer, and 0 (unknown) deliberately rotates nothing.
268public enum RunnerInterfaceOrientation {
279 public static let unknown = 0
2810 public static let portrait = 1
@@ -31,9 +13,7 @@ public enum RunnerInterfaceOrientation {
3113 public static let landscapeLeft = 4
3214}
3315
34- /// The quarter-turn between an app's interface space and the device's native (portrait-up) space.
3516public enum CoordinateSpaceRotation {
36- /// An interface-space point, in the native space synthesized events are performed in.
3717 public static func native (
3818 point : CGPoint ,
3919 in frame : CGRect ,
@@ -50,12 +30,11 @@ public enum CoordinateSpaceRotation {
5030 return CGPoint ( x : localY , y : width - localX )
5131 case RunnerInterfaceOrientation . portraitUpsideDown :
5232 return CGPoint ( x : width - localX , y : height - localY )
53- default : // portrait, or an orientation the platform did not name
33+ default :
5434 return CGPoint ( x : localX , y : localY )
5535 }
5636 }
5737
58- /// An interface-space translation vector, in the same native space as `native(point:)`.
5938 public static func native ( vector : CGVector , interfaceOrientation : Int ) -> CGVector {
6039 switch interfaceOrientation {
6140 case RunnerInterfaceOrientation . landscapeRight :
@@ -64,12 +43,11 @@ public enum CoordinateSpaceRotation {
6443 return CGVector ( dx : vector . dy , dy : - vector . dx )
6544 case RunnerInterfaceOrientation . portraitUpsideDown :
6645 return CGVector ( dx : - vector . dx , dy : - vector . dy )
67- default : // portrait, or an orientation the platform did not name
46+ default :
6847 return vector
6948 }
7049 }
7150
72- /// The inverse of `native(point:)`: a native-space point, in the app's interface space.
7351 public static func oriented (
7452 point : CGPoint ,
7553 in frame : CGRect ,
@@ -89,16 +67,13 @@ public enum CoordinateSpaceRotation {
8967 case RunnerInterfaceOrientation . portraitUpsideDown :
9068 localX = width - Double ( point . x )
9169 localY = height - Double ( point . y )
92- default : // portrait, or an orientation the platform did not name
70+ default :
9371 localX = Double ( point . x )
9472 localY = Double ( point . y )
9573 }
9674 return CGPoint ( x : localX + Double ( frame . minX ) , y : localY + Double ( frame . minY ) )
9775 }
9876
99- /// The inverse of `native(point:)` for a rect. A quarter turn swaps the axes, so opposite corners
100- /// of the reported rect become opposite corners of the result; ordering them keeps the origin
101- /// top-left, which is what every consumer of a published rect reads.
10277 public static func oriented (
10378 rect : CGRect ,
10479 in frame : CGRect ,
@@ -123,34 +98,12 @@ public enum CoordinateSpaceRotation {
12398 }
12499}
125100
126- /// The space one captured subtree reports its rects in.
127- ///
128- /// RULE: the capture publishes every rect in the app's orientation space. A surface host declares the
129- /// space of its own subtree — its box is either the app's box, or the app's box turned through a
130- /// quarter, which is how a surface hosted in the device's native space announces itself — and anything
131- /// below it inherits that space. Nothing is declared, and every rect stays exactly as the platform
132- /// reported it, when the app frame is unusable, when the interface orientation names no quarter turn
133- /// (portrait, or an orientation the platform did not name), or when the app frame is square. Geometry
134- /// the capture cannot place is not a claim about where it is, and consumers already fail open on it the
135- /// way they do on any missing platform fact — but the capture says so: `unplacedSurfaceHostCount`
136- /// counts the hosts a published tree still carries turned, so the daemon can warn instead of
137- /// publishing two spaces silently.
138- ///
139- /// A half turn is a different claim: an upside-down app's own box is already the native box, so no
140- /// reported window distinguishes the two spaces and nothing is turned back. That is the same limit the
141- /// box-only rule accepts for a square app frame, and it is why the consumer rules in
142- /// `tap-keyboard-occlusion.ts` stay rather than becoming an assertion here.
143101public enum SnapshotGeometrySpace : Equatable {
144- /** The app's own orientation space: the one every consumer of a published tree reads. */
145102 case appOrientation
146- /** The device's native (portrait-up) space, with the way back to the app's space attached. */
147103 case deviceNative ( appFrame : CGRect , interfaceOrientation : Int )
148104
149- /// How far a window's side lengths may miss the app's swapped side lengths and still be that
150- /// quarter turn. Measured captures match to the point; this absorbs float representation only.
151105 public static let quarterTurnTolerance : Double = 1
152106
153- /// The reported rect, in the space the capture publishes.
154107 public func orientedFrame ( of reportedFrame : CGRect ) -> CGRect {
155108 switch self {
156109 case . appOrientation :
@@ -164,14 +117,6 @@ public enum SnapshotGeometrySpace: Equatable {
164117 }
165118 }
166119
167- /// The space one node's subtree reports in.
168- ///
169- /// Only a surface host may declare a space: the window itself, or the surface the window hands its
170- /// content to. XCTest reports `UIRemoteKeyboardWindow` with the app's own box and its child with
171- /// the turned one, so the window alone is not where the turn shows up, while a deep node claiming a
172- /// turned box is content whose reported bounds happen to be large and is left in the inherited
173- /// space. A host that reports anything other than a turned box declares the app's space for its
174- /// subtree, which is how a tree with no rotated surface stays exactly as reported.
175120 public static func space (
176121 reportedBySurfaceHost isSurfaceHost : Bool ,
177122 reportedFrame : CGRect ,
@@ -185,65 +130,15 @@ public enum SnapshotGeometrySpace: Equatable {
185130 return . deviceNative ( appFrame : appFrame , interfaceOrientation : interfaceOrientation )
186131 }
187132
188- /// Whether this orientation is a turn the reported box can be measured against. Portrait and an
189- /// unnamed orientation leave the device's native space upright, so nothing under them is turned.
190133 public static func namesQuarterTurn ( _ interfaceOrientation : Int ) -> Bool {
191134 interfaceOrientation == RunnerInterfaceOrientation . landscapeLeft
192135 || interfaceOrientation == RunnerInterfaceOrientation . landscapeRight
193136 }
194137
195- /// Whether this node, or the window above it, is where a hosted surface's box appears.
196138 public static func isSurfaceHost ( isWindow : Bool , parentIsWindow : Bool ) -> Bool {
197139 isWindow || parentIsWindow
198140 }
199141
200- /// The element type names under which a producer publishes the app's windows: the app's own
201- /// window, `UITextEffectsWindow`, `UIRemoteKeyboardWindow`. XCTest models each as its own element
202- /// typed `.application` or `.window`, and every producer names them this way in a published tree.
203- public static func isWindowType ( _ type : String ) -> Bool {
204- type == " Application " || type == " Window "
205- }
206-
207- /// Surface hosts a published tree still carries in the device's native space.
208- ///
209- /// A capture that could name the app's interface orientation turned every such host back, so its
210- /// published tree holds none. One that could not — the orientation read failed, or the tier had
211- /// only the bridge's own root box to anchor on — publishes the host as the platform reported it,
212- /// and this is where that shows: a host whose box is the viewport quarter-turned. The count is a
213- /// disclosure, not a repair; it rides the quality verdict so the daemon can say which captures hold
214- /// two spaces instead of letting rects under those hosts read as addresses (#2612).
215- public static func unplacedSurfaceHostCount ( in nodes : [ RawAXNode ] , viewport : CGRect ) -> Int {
216- guard isPlottable ( viewport ) else { return 0 }
217- // `parentIndex` is a position into this array: every producer appends nodes in traversal order
218- // with `index == nodes.count` and sets a child's `parentIndex` to the parent's index, so
219- // `nodes[parentIndex]` is that parent. A turned host is one surface even when both its window
220- // and the surface directly under it report the turned box, so a turned node whose parent is
221- // itself turned is folded into that parent rather than counted a second time.
222- func turnedFrame ( _ node : RawAXNode ) -> Bool {
223- let parentIsWindow = node . parentIndex . map { index in
224- nodes . indices . contains ( index ) && isWindowType ( nodes [ index ] . type )
225- } ?? false
226- guard isSurfaceHost ( isWindow : isWindowType ( node . type ) , parentIsWindow : parentIsWindow )
227- else { return false }
228- return isQuarterTurned (
229- CGRect ( x : node . rect . x , y : node . rect . y , width : node . rect . width , height : node . rect . height ) ,
230- relativeTo : viewport
231- )
232- }
233- var count = 0
234- for node in nodes {
235- guard turnedFrame ( node ) else { continue }
236- let parentTurned = node . parentIndex . map { index in
237- nodes . indices . contains ( index ) && turnedFrame ( nodes [ index ] )
238- } ?? false
239- if ! parentTurned { count += 1 }
240- }
241- return count
242- }
243-
244- /// A window that reports the app's two side lengths on the other axes is hosted in the device's
245- /// native space. A square app frame cannot be told from its own quarter turn, so it is left alone
246- /// rather than guessed at.
247142 private static func isQuarterTurned ( _ frame : CGRect , relativeTo appFrame : CGRect ) -> Bool {
248143 guard isPlottable ( frame ) , isPlottable ( appFrame ) ,
249144 abs ( appFrame . width - appFrame . height ) > quarterTurnTolerance
0 commit comments