@@ -137,22 +137,37 @@ extension RunnerTests {
137137 var isDistinguishable : Bool { ! identifier . isEmpty }
138138 }
139139
140- /// A text input found under a point, and the identity it carried when found. The element is an
141- /// index-bound query handle: an input inserted or reordered ahead of it later re-binds the handle
142- /// to that input, and the identity is what notices.
140+ /// A text input found under a point, the identity it carried when found, and the content vector of
141+ /// the command that found it. The element is an index-bound query handle: an input inserted or
142+ /// reordered ahead of it later re-binds the handle to that input, and the identity is what notices.
143143 struct TextInputAtPoint {
144144 let element : XCUIElement
145145 let identity : TextEntryInputIdentity
146+ let contentTranslation : TextEntryContentTranslation
147+ }
148+
149+ /// The vector that carries a snapshot-read frame to its place on the screen (#3899), read once per
150+ /// command by `liveContentTranslation`. Non-defaulted everywhere it travels: a vector nobody read
151+ /// must never read as full screen, because on a placed window that silently dispatches window-local
152+ /// points as screen points — the #3899 failure.
153+ enum TextEntryContentTranslation {
154+ /// The vector of a placed window: its content box's origin on the screen.
155+ case known ( CGSize )
156+ /// The app fills the screen, so a snapshot frame is already a screen frame.
157+ case none
158+ /// The window read could not answer, so the space of a snapshot frame is unknown. Consumers
159+ /// refuse it as a screen frame: `frameOnScreen` reads nil and nothing dispatches a point from it.
160+ case unknown
146161 }
147162
148163 struct TextEntryTarget {
149164 let element : XCUIElement ?
150165 let refreshPoint : CGPoint ?
151166 let prefersFocusedElement : Bool
152- /// The content vector of a placed window, read once for the command that built this target and
153- /// handed to every read it produces, which turns its snapshot frames into screen points (#3899).
154- /// Nil when the app fills the screen.
155- let contentTranslation : CGSize ?
167+ /// The content vector of the command that built this target, handed to every read it produces,
168+ /// which turns their snapshot frames into screen points (#3899). Non-defaulted: the route that
169+ /// reads no window carries `.unknown`, not a vector that would read as full screen.
170+ let contentTranslation : TextEntryContentTranslation
156171 let fromTapWitness : Bool
157172 /// The input the first resolved element was. Once bound, resolution refuses any other input.
158173 let boundIdentity : TextEntryInputIdentity ?
@@ -170,7 +185,7 @@ extension RunnerTests {
170185 element : XCUIElement ? ,
171186 refreshPoint : CGPoint ? ,
172187 prefersFocusedElement : Bool ,
173- contentTranslation : CGSize ? = nil ,
188+ contentTranslation : TextEntryContentTranslation ,
174189 fromTapWitness : Bool = false ,
175190 boundIdentity : TextEntryInputIdentity ? = nil ,
176191 inputAtRefreshPoint : TextInputAtPoint ? = nil ,
@@ -187,14 +202,14 @@ extension RunnerTests {
187202 }
188203
189204 /// The target moved to the input a resolution read: its element, a refresh point at its frame's
190- /// center on the screen, and its identity while the target is unbound. A read with no snapshot has
191- /// no frame here, so its center cannot come from the live `element.frame` — the read a post-focus
192- /// handle cannot answer without recording a failure (#3060) .
205+ /// center on the screen, and its identity while the target is unbound. A read that cannot name a
206+ /// screen box — no snapshot, or an unknown content space — keeps the target's current refresh
207+ /// point rather than a center it cannot trust .
193208 func withResolvedInput ( _ input : ResolvedTextEntryInput ? ) -> TextEntryTarget {
194209 guard let input else {
195210 return self
196211 }
197- let frame = input . snapshot == nil ? . zero : input . frameOnScreen
212+ let frame = input . frameOnScreen ?? . zero
198213 return TextEntryTarget (
199214 element : input . element ,
200215 refreshPoint : frame . isEmpty ? refreshPoint : CGPoint ( x : frame . midX , y : frame . midY ) ,
@@ -221,10 +236,10 @@ extension RunnerTests {
221236 let element : XCUIElement
222237 /// Nil when the element exists but could not be snapshotted.
223238 let snapshot : XCUIElementSnapshot ?
224- /// The vector of the command that made this read (#3899); nil when the app fills the screen .
225- let contentTranslation : CGSize ?
239+ /// The vector state of the command that made this read (#3899).
240+ let contentTranslation : TextEntryContentTranslation
226241
227- private init ( element : XCUIElement , snapshot : XCUIElementSnapshot ? , contentTranslation : CGSize ? ) {
242+ private init ( element : XCUIElement , snapshot : XCUIElementSnapshot ? , contentTranslation : TextEntryContentTranslation ) {
228243 self . element = element
229244 self . snapshot = snapshot
230245 self . contentTranslation = contentTranslation
@@ -233,7 +248,7 @@ extension RunnerTests {
233248 /// Reads a handle that may name an input the app has removed; nil when it names none or the read
234249 /// raised. The snapshot of a missing element throws only after XCTest waits about two seconds for
235250 /// a match, so existence is read first.
236- init ? ( reading element : XCUIElement , contentTranslation : CGSize ? = nil ) {
251+ init ? ( reading element : XCUIElement , contentTranslation : TextEntryContentTranslation ) {
237252 var exists = false
238253 var snapshot : XCUIElementSnapshot ?
239254 if let exception = RunnerObjCExceptionCatcher . catchException ( {
@@ -249,7 +264,7 @@ extension RunnerTests {
249264
250265 /// Reads a handle its query has just listed, inside the caller's exception containment, so the
251266 /// snapshot is read first and existence only when the snapshot fails; nil when it names no element.
252- init ? ( readingListed element : XCUIElement , contentTranslation : CGSize ? = nil ) {
267+ init ? ( readingListed element : XCUIElement , contentTranslation : TextEntryContentTranslation ) {
253268 let snapshot = try? element . snapshot ( )
254269 guard snapshot != nil || element . exists else { return nil }
255270 self . init ( element : element , snapshot : snapshot , contentTranslation : contentTranslation )
@@ -266,17 +281,25 @@ extension RunnerTests {
266281 return element
267282 }
268283
269- /// The input's box in screen space: the snapshot frame plus `contentTranslation`, or the live
270- /// frame when there is no snapshot — that property already reports a placed window's content in
271- /// screen space (#3899).
272- var frameOnScreen : CGRect {
284+ /// The input's box in screen space, or nil when this read cannot name one: no snapshot, or a
285+ /// window read that could not answer, so the snapshot frame's space is unknown. A nil here is the
286+ /// one signal every consumer uses to refuse a dispatched point: the live `element.frame` is a
287+ /// read a handle that stopped answering its query cannot make without recording a failure
288+ /// (#3060), and an unknown space must never be dispatched as a screen point (#3899). Callers
289+ /// that need a box for a route which dispatches nothing fall back to `element.frame`, which
290+ /// already reports a placed window's content in screen space.
291+ var frameOnScreen : CGRect ? {
273292 guard let snapshot else {
274- return element . frame
293+ return nil
275294 }
276- guard let contentTranslation else {
295+ switch contentTranslation {
296+ case . known ( let offset ) :
297+ return snapshot . frame . offsetBy ( dx : offset . width , dy : offset . height )
298+ case . none :
277299 return snapshot . frame
300+ case . unknown :
301+ return nil
278302 }
279- return snapshot . frame . offsetBy ( dx : contentTranslation . width , dy : contentTranslation . height )
280303 }
281304 }
282305
@@ -539,7 +562,7 @@ extension RunnerTests {
539562 return input
540563 }
541564 if let input = target . inputAtRefreshPoint ,
542- let read = textInputIfStillResolves ( input , contentTranslation : target . contentTranslation ) {
565+ let read = textInputIfStillResolves ( input ) {
543566 return read
544567 }
545568 if target . inputAtRefreshPoint == nil ,
@@ -658,12 +681,11 @@ extension RunnerTests {
658681 // zero-size one (how a departed handle reads), there is no point to dispatch — an edge-tap
659682 // from a frame the field moved after records a failure or navigates away, the shape
660683 // `clearTextInput`'s comment refuses — so degrade to the caller's point-free delete burst.
661- // A snapshotless read gets no point at all: `frameOnScreen`'s fallback is the live
662- // `element.frame` read this function exists to avoid (#3060).
663- guard input . snapshot ? . frame . isEmpty == false else {
684+ // A snapshotless read gets no point at all: `frameOnScreen` is nil without a snapshot, so the
685+ // live `element.frame` read this function exists to avoid is never reached (#3060).
686+ guard let frame = input . frameOnScreen , ! frame . isEmpty else {
664687 return
665688 }
666- let frame = input . frameOnScreen
667689 _ = tapAt (
668690 app : app ,
669691 x : frame . minX + max ( 2 , frame . width - 4 ) ,
0 commit comments