Skip to content

Commit 70f6faa

Browse files
committed
refactor(ios): cut the screen-space comments and the duplicated frame offset (#3899)
The vector on the target replaces the offset arithmetic in textEntryRefreshPoint, which read the snapshot frame and added the vector itself. One owner now: ResolvedTextEntryInput.frameOnScreen. The comments that restated the capture's rule at every call site are cut to the constraint the code cannot show. SnapshotCoordinateSpace.swift ships in the npm package without comment stripping, so its prose lives in ADR 0004 and the golden table instead; the same rule text is removed from the TypeScript decoder's foot note.
1 parent b4ec027 commit 70f6faa

10 files changed

Lines changed: 74 additions & 135 deletions

File tree

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -155,8 +155,7 @@ extension RunnerTests {
155155
)
156156
let textInput: XCUIElement?
157157
if !xCTestTextInputProbeSkipped {
158-
// The lookup compares the point, which is a screen point, with candidate frames; on a
159-
// placed window the snapshot frames need the content vector (#3899).
158+
// The lookup compares candidate frames with this screen point (#3899).
160159
textInput = coordinateTapTextInputAt(
161160
app: activeApp,
162161
x: x,

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -352,8 +352,7 @@ extension RunnerTests {
352352

353353
func readTextAt(app: XCUIApplication, x: Double, y: Double) -> String? {
354354
let point = CGPoint(x: x, y: y)
355-
// The point is a screen point; candidate snapshot frames of a placed window need the content
356-
// vector to be compared with it (#3899).
355+
// The lookup compares candidate frames with this screen point (#3899).
357356
let textInputCandidates = textInputCandidatesAt(
358357
app: app,
359358
point: point,
@@ -623,15 +622,14 @@ extension RunnerTests {
623622
#if !os(tvOS)
624623
private func interactionCoordinate(app: XCUIApplication, x: Double, y: Double) -> XCUICoordinate {
625624
#if os(iOS)
626-
// A caller's point is a screen point: coordinate taps, double taps, long presses, and drags
627-
// anchor at the application's origin, not the resolved window, so the point is dispatched as
628-
// given. That holds because `app.coordinate(withNormalizedOffset: .zero)` sits at the origin of
629-
// the space `app.frame` names, and for a windowed app the measured `app.frame` starts at the
630-
// screen's origin. The first qualifying window is not always the one under the finger — a
625+
// A caller's point is a screen point: these gestures anchor at the app's origin, not the
626+
// resolved window, so it is dispatched as given. The anchor sits at the origin of the space
627+
// `app.frame` names, and for a windowed app the measured `app.frame` starts at the screen's
628+
// origin (#3899). The first qualifying window is not always the one under the finger — a
631629
// SpringBoard `alert accept` can live in an alert window while the wallpaper or status-bar
632630
// window qualifies first, so a window-relative anchor misses the button. Reference frames and
633631
// the synthesized display ID still resolve through `resolveRunnerWindow`, so a foldable tap
634-
// keeps its panel and stays on its display (#3899, ADR 0025).
632+
// keeps its panel and stays on its display (ADR 0025).
635633
let origin = app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
636634
return origin.withOffset(CGVector(dx: x, dy: y))
637635
#else

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift‎

Lines changed: 18 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -149,10 +149,9 @@ extension RunnerTests {
149149
let element: XCUIElement?
150150
let refreshPoint: CGPoint?
151151
let prefersFocusedElement: Bool
152-
/// The live snapshot-frame vector for the reading session, read once when this target was built
153-
/// (#3899). Every snapshot frame the target's reads produce is compared with screen points, so
154-
/// every such read carries this vector (`ResolvedTextEntryInput.frameOnScreen`). Nil on a device
155-
/// whose app fills the screen, where a snapshot frame is already a screen frame.
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.
156155
let contentTranslation: CGSize?
157156
let fromTapWitness: Bool
158157
/// The input the first resolved element was. Once bound, resolution refuses any other input.
@@ -187,25 +186,18 @@ extension RunnerTests {
187186
self.postFocusRead = postFocusRead
188187
}
189188

190-
/// The target moved to the input a resolution read: its element and identity, and — when the
191-
/// read carries a snapshot — a refresh point at that frame's center on the screen (`frameOnScreen`
192-
/// plus this target's content vector, #3899). A read with no snapshot keeps the old refresh
193-
/// point: its center would come from the live `element.frame`, the read a post-focus handle
194-
/// cannot answer without recording a failure (#3060).
189+
/// 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).
195193
func withResolvedInput(_ input: ResolvedTextEntryInput?) -> TextEntryTarget {
196194
guard let input else {
197195
return self
198196
}
199-
let nextRefreshPoint: CGPoint?
200-
if let snapshot = input.snapshot {
201-
let frame = input.frameOnScreen
202-
nextRefreshPoint = frame.isEmpty ? refreshPoint : CGPoint(x: frame.midX, y: frame.midY)
203-
} else {
204-
nextRefreshPoint = refreshPoint
205-
}
197+
let frame = input.snapshot == nil ? .zero : input.frameOnScreen
206198
return TextEntryTarget(
207199
element: input.element,
208-
refreshPoint: nextRefreshPoint,
200+
refreshPoint: frame.isEmpty ? refreshPoint : CGPoint(x: frame.midX, y: frame.midY),
209201
prefersFocusedElement: prefersFocusedElement,
210202
contentTranslation: contentTranslation,
211203
fromTapWitness: fromTapWitness,
@@ -222,18 +214,14 @@ extension RunnerTests {
222214
/// removed input or a focused Flutter password field (#3060), records an XCTest failure that ends
223215
/// the runner session, the snapshot only throws.
224216
///
225-
/// This type owns the probe-side space of #3899 (ADR 0004). `XCUIElementSnapshot.frame` reports a
226-
/// placed window's content in the window's own space, while every point this read feeds — a refresh
227-
/// point, a focus tap, a probe match, a readiness retap — is a screen point. So the read carries
228-
/// the content vector it was taken under, and `frameOnScreen` is the only frame consumers use: a
229-
/// snapshot frame plus the vector, or the live frame when there is no snapshot. Raw frames
230-
/// (`snapshot.frame`) are compared only with each other.
217+
/// This type owns the probe-side space of #3899 (ADR 0004): a snapshot frame names a placed
218+
/// window's content space while every point this read feeds is a screen point, so consumers take
219+
/// `frameOnScreen` and compare raw frames only with each other.
231220
struct ResolvedTextEntryInput {
232221
let element: XCUIElement
233222
/// Nil when the element exists but could not be snapshotted.
234223
let snapshot: XCUIElementSnapshot?
235-
/// The live snapshot-frame vector read once for the command that made this read (#3899). Nil
236-
/// when the app fills the screen, where a snapshot frame is already a screen frame.
224+
/// The vector of the command that made this read (#3899); nil when the app fills the screen.
237225
let contentTranslation: CGSize?
238226

239227
private init(element: XCUIElement, snapshot: XCUIElementSnapshot?, contentTranslation: CGSize?) {
@@ -278,9 +266,9 @@ extension RunnerTests {
278266
return element
279267
}
280268

281-
/// The input's box in screen space: the snapshot frame carried by `contentTranslation` to its
282-
/// place on the screen, or the live frame when there is no snapshot — the live
283-
/// `XCUIElement.frame` already reports a placed window's content in screen space (#3899).
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).
284272
var frameOnScreen: CGRect {
285273
guard let snapshot else {
286274
return element.frame
@@ -296,8 +284,6 @@ extension RunnerTests {
296284
/// `dispatch` runs, and resolves the target again after that, so a bound target refuses an input
297285
/// that took its place. Each resolution moves the target to the input it read. Every post and every
298286
/// pause between reads goes through `dispatch`; the pause a typing plan takes itself follows a post.
299-
/// The reader hands the target's content vector to every read it resolves, so one vector rules the
300-
/// command (#3899).
301287
struct TextEntryReader {
302288
private(set) var target: TextEntryTarget
303289
private var lastRead: ResolvedTextEntryInput?
@@ -672,10 +658,8 @@ extension RunnerTests {
672658
// zero-size one (how a departed handle reads), there is no point to dispatch — an edge-tap
673659
// from a frame the field moved after records a failure or navigates away, the shape
674660
// `clearTextInput`'s comment refuses — so degrade to the caller's point-free delete burst.
675-
// The read's snapshot frame names the window's own content space on a placed window, so the
676-
// point enters `tapAt` through `frameOnScreen`, which carries the read's content vector (#3899).
677-
// A read with no snapshot gets no point at all: `frameOnScreen`'s fallback is the live
678-
// `element.frame` read this function exists to avoid.
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).
679663
guard input.snapshot?.frame.isEmpty == false else {
680664
return
681665
}

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryFocus.swift‎

Lines changed: 10 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,7 @@ extension RunnerTests {
7979
// The tapped input's own read comes before the keyboard. While a software keyboard is
8080
// presented, the keyboard query blocks and then finds none. An input that reports keyboard
8181
// focus is stronger evidence than the keyboard's arrival, which shows only that some input
82-
// took focus. The read carries the focus step's content vector (#3899): the hand-on read
83-
// becomes the entry's first read, and its frames must enter screen space.
82+
// took focus.
8483
let read = target.flatMap { ResolvedTextEntryInput(reading: $0, contentTranslation: contentTranslation) }
8584
if let read, let snapshot = read.snapshot, snapshotHasKeyboardFocus(snapshot) {
8685
return TextEntryStabilization(element: read.element, evidence: .inputReportsKeyboardFocus(read), polls: polls)
@@ -132,18 +131,15 @@ extension RunnerTests {
132131
return TextEntryTarget(element: focused, refreshPoint: nil, prefersFocusedElement: true)
133132
}
134133

135-
// The one content-vector read for this command (#3899): every target this focus step builds
136-
// carries it, every read those targets produce converts through it, and the retap and reader
137-
// downstream reuse it. On a device whose app fills the screen it is nil and every frame stays
138-
// exactly as read.
134+
// The one content-vector read for this command (#3899): every target built here carries it and
135+
// every read those targets produce converts through it.
139136
let contentTranslation = liveContentTranslation(app: app)
140137
let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
141138
let input = textInputAt(app: app, x: x, y: y, contentTranslation: contentTranslation)
142139
let target = input?.element
143140
let requestedPoint = CGPoint(x: x, y: y)
144-
// The focus tap goes to the input's own center, and the input's frame arrives from a snapshot,
145-
// which reports a placed window's content in the window's own space while `tapAt` dispatches a
146-
// screen point (#3899). An input read live (no snapshot) already names screen space.
141+
// The tap goes to the input's own center, and `tapAt` dispatches a screen point, so the point
142+
// comes from `frameOnScreen` (#3899).
147143
let inputCenter = input.map { $0.frameOnScreen }.flatMap {
148144
$0.isEmpty ? nil : CGPoint(x: $0.midX, y: $0.midY)
149145
}
@@ -205,8 +201,6 @@ extension RunnerTests {
205201
contentTranslation: CGSize?
206202
) -> TextEntryTarget {
207203
guard let element else {
208-
// No element: the target keeps its refresh point, and the reads a later resolve makes through
209-
// that point carry this command's vector (#3899).
210204
return TextEntryTarget(
211205
element: nil,
212206
refreshPoint: requestedPoint,
@@ -249,22 +243,19 @@ extension RunnerTests {
249243
/// the target gets NO refresh point rather than the pre-focus one: this route's first resolve is
250244
/// not yet bound to an identity, and a field that went unqueryable on focus may have moved the
251245
/// layout so the old point names a different input, so fail closed with a typed reason instead of
252-
/// typing into that other field. The frame is the read's snapshot frame plus its content vector
253-
/// (#3899) — never the live `element.frame` fallback `frameOnScreen` uses for a snapshotless read.
246+
/// typing into that other field. The frame is `read`'s snapshot frame plus its content vector,
247+
/// never the live `element.frame` (#3899, #3060).
254248
private func textEntryRefreshPoint(
255249
read: ResolvedTextEntryInput?,
256250
fallbackTo requestedPoint: CGPoint
257251
) -> CGPoint? {
258-
guard let snapshot = read?.snapshot else {
252+
guard let read, read.snapshot != nil else {
259253
return nil
260254
}
261-
guard !snapshot.frame.isEmpty else {
255+
let frame = read.frameOnScreen
256+
guard !frame.isEmpty else {
262257
return requestedPoint
263258
}
264-
let frame = snapshot.frame.offsetBy(
265-
dx: read?.contentTranslation?.width ?? 0,
266-
dy: read?.contentTranslation?.height ?? 0
267-
)
268259
return CGPoint(x: frame.midX, y: frame.midY)
269260
}
270261
}

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntryReadiness.swift‎

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -86,19 +86,15 @@ extension RunnerTests {
8686
/// wait rather than reused, because focusing a field moves the layout: the repeat aims at where the
8787
/// field is then, which is the moment the read it replaced ran at.
8888
///
89-
/// The read enters `retapAt` as a `ResolvedTextEntryInput`, so the repeat taps
90-
/// `frameOnScreen` — the snapshot frame plus the content vector of a placed window (#3899). The base
91-
/// read carries no vector; the re-read carries the live one, read only on this branch, so a tap that
92-
/// confirms focus dispatches no window lookup.
89+
/// The re-read carries the live content vector, so the repeat taps a screen point (#3899). It is
90+
/// read only on this branch: a tap that confirms focus dispatches no window lookup.
9391
func waitForTextEntryReadinessAfterTap(app: XCUIApplication, element: XCUIElement) {
9492
#if os(iOS)
9593
if waitForTextEntryFocus(app: app, element: element, timeout: TextEntryTiming.readinessTimeout) {
9694
return
9795
}
98-
// The re-read enters as a `ResolvedTextEntryInput` carrying the content vector of a placed
99-
// window (#3899), read only on this branch, so a tap that confirms focus dispatches no window
100-
// lookup. The window read is contained like the probe lookups: a transient window that records
101-
// an XCTest issue costs the vector, not the command.
96+
// Contained like the probe lookups: a transient window that records an XCTest issue costs the
97+
// vector, not the command.
10298
let settled: ResolvedTextEntryInput?
10399
switch containingTextInputProbeIssues(fallback: nil as ResolvedTextEntryInput?, { _ in
104100
ResolvedTextEntryInput(reading: element, contentTranslation: liveContentTranslation(app: app))
@@ -116,9 +112,8 @@ extension RunnerTests {
116112
}
117113

118114
/// The readiness retap, split out so the unit lane can drive it and assert where the point lands.
119-
/// `tapAt` takes a screen point, so the point is `frameOnScreen`'s center. A read with no snapshot
120-
/// taps nothing: `frameOnScreen`'s fallback is the live `element.frame` read — the one that records
121-
/// an XCTest failure on a handle that stopped answering its query (#3060).
115+
/// A read with no snapshot taps nothing: its `frameOnScreen` is the live `element.frame`, the read
116+
/// a handle that stopped answering its query cannot make without recording a failure (#3060).
122117
func retapAt(read: ResolvedTextEntryInput, app: XCUIApplication, element: XCUIElement) {
123118
guard read.snapshot != nil else {
124119
return
@@ -159,8 +154,7 @@ extension RunnerTests {
159154
/// fallback at all.
160155
func keyboardFocusConfirmed(app: XCUIApplication, element: XCUIElement) -> Bool {
161156
#if os(iOS)
162-
// The read needs no content vector: this corroborates identity and position raw-frame against
163-
// raw-frame, and never turns a frame into a dispatched point (#3899's rule).
157+
// No content vector: this corroborates raw frame against raw frame and dispatches no point.
164158
return ResolvedTextEntryInput(reading: element).map { keyboardFocusConfirmed(app: app, read: $0) } ?? false
165159
#else
166160
return false

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextInputProbe.swift‎

Lines changed: 11 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ extension RunnerTests {
2424
y: Double,
2525
contentTranslation: CGSize?
2626
) -> ResolvedTextEntryInput? {
27-
textInputCandidatesAt(app: app, point: CGPoint(x: x, y: y), contentTranslation: contentTranslation).first
27+
let point = CGPoint(x: x, y: y)
28+
return textInputCandidatesAt(app: app, point: point, contentTranslation: contentTranslation).first
2829
}
2930

3031
func textInputCandidatesAt(
@@ -134,8 +135,7 @@ extension RunnerTests {
134135
}
135136

136137
/// Runs an optional probe whose XCTest issues are contained instead of recorded: an issue makes
137-
/// the probe unavailable rather than failing the command and invalidating the runner. Visible to
138-
/// the readiness retap, whose window re-read needs the same containment (#3899).
138+
/// the probe unavailable rather than failing the command and invalidating the runner.
139139
func containingTextInputProbeIssues<T>(
140140
fallback: T,
141141
_ probe: (_ shouldStop: () -> Bool) -> T
@@ -215,20 +215,15 @@ extension RunnerTests {
215215
}
216216

217217
/// The vector that carries this session's snapshot-read app-content frames to their place on the
218-
/// screen, or nil when the app fills the screen (#3899). Read once at the start of each command
219-
/// that dispatches points derived from snapshot frames — the focus step, the coordinate fill route,
220-
/// the readiness retap, a coordinate text read — and carried on the types the command builds from
221-
/// it (`TextEntryTarget.contentTranslation`, `ResolvedTextEntryInput.contentTranslation`). No read
222-
/// inside a loop re-reads it: the whole-app queries below cost about 90 ms each on heavy React
223-
/// Native screens, and a per-read re-query would undo the fill-read work of #3881, #3906 and #3909.
218+
/// screen, or nil when the app fills the screen (#3899). Each command that dispatches points from
219+
/// snapshot frames reads it once, at its own start, and hands it down; a read inside a typing loop
220+
/// never calls this, because the two live box reads below cost about 90 ms each on a heavy React
221+
/// Native screen.
224222
///
225-
/// The live `XCUIElement.frame` property already reports a placed window's content in screen space,
226-
/// but `XCUIElementSnapshot.frame` reports it in the window's own content space, so the same probe
227-
/// sees two spaces on an iPad Windowed Apps window. The signature and the vector are the capture's
228-
/// rule (`SnapshotContentTranslation`, ADR 0004) read from the two live boxes that name it: the
229-
/// application's `frame` is a `(0,0)`-anchored copy of the box the resolved window reports at its
230-
/// place on the screen. Any other pair of boxes declares no vector, so full-screen, iPhone, and
231-
/// each foldable panel keep their frames exactly as read.
223+
/// The signature and the vector are the capture's rule (`SnapshotContentTranslation`, ADR 0004)
224+
/// read from the two live boxes that name it: the application's `frame` is a `(0,0)`-anchored copy
225+
/// of the box the resolved window reports at its place on the screen. Any other pair of boxes
226+
/// declares no vector, so full-screen, iPhone, and each foldable panel keep frames as read.
232227
func liveContentTranslation(app: XCUIApplication) -> CGSize? {
233228
// The window read is contained like the probe lookups it replaces: a transient window that
234229
// records an XCTest issue costs the vector, not the runner session.

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TypeExecution.swift‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,7 @@ extension RunnerTests {
2727
hasY: command.y != nil,
2828
xCTestChannelPenalized: xCTestChannelPenalized
2929
), let x = command.x, let y = command.y {
30-
// The one content-vector read for this command (#3899): the target built here carries it, and
31-
// every read that target produces converts through it, as the focus route's targets do.
30+
// The one content-vector read for this command (#3899); the target built here carries it.
3231
let contentTranslation = liveContentTranslation(app: activeApp)
3332
// Resolved before the tap: the focus it causes can move the field away from this point.
3433
// A replacement with no input at the point has nothing to bind to: its clear and its typed

0 commit comments

Comments
 (0)