You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7c2b93a
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/adr/0025-foldable-apple-panels.md
+81-81Lines changed: 81 additions & 81 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -256,19 +256,19 @@ afterwards.
256
256
257
257
## Which XCTest capture surface sees the lit panel
258
258
259
-
#2727 measured every `XCUIScreenshotProviding` surface a runner can reach against the
260
-
`simctl io screenshot --display=<panel>` capture of the panel CoreDevice reports lit, on iPhone Duo
261
-
(iOS 27.1, Xcode 27.1 beta) closed at hinge 0° and open at 180°, with a 130° session on different
262
-
app content as the corroboration run and iPhone 17 (iOS 27.0) as the single-panel control. Poses came
263
-
from the hinge read-back, not from the pose that was requested — the amendment above is why that is
264
-
the only defensible source: the first two inner-panel sessions were booked as open and both read back
265
-
130°, so they are recorded here as corroboration and the settled 180° session carries the table. A different app screen was shown per session, so neither
266
-
panel could be mistaken for the other by content, and the app was left untouched between the oracle
267
-
and the runner capture, so a luma gap is a source difference rather than a content one. Mean luma
268
-
comes from a 48x48 resample; panel identity comes from CoreDevice's `displayId` and pixel agreement
269
-
from comparing decoded pixels, so no claim here rests on luma. Captured dimensions are PNG header
270
-
dimensions, which is the panel's native geometry — the capture's own orientation presents some of
271
-
them turned.
259
+
#2727 measured every `XCUIScreenshotProviding` surface a runner can reach against the `simctl io
260
+
screenshot --display=<panel>` capture of the panel CoreDevice reports lit, on iPhone Duo (iOS 27.1,
261
+
Xcode 27.1 beta) closed at hinge 0° and open at 180°, with a 130° session on different app content
262
+
as the corroboration run and iPhone 17 (iOS 27.0) as the single-panel control. Poses came from the
263
+
hinge read-back, not from the pose that was requested — the amendment above is why that is the only
264
+
defensible source: the first two inner-panel sessions were booked as open and both read back 130°,
265
+
so they are recorded here as corroboration and the settled 180° session carries the table. A
266
+
different app screen was shown per session, so neither panel could be mistaken for the other by
267
+
content, and the app was left untouched between the oracle and the runner capture, so a luma gap is
268
+
a source difference rather than a content one. Mean luma comes from a 48x48 resample; panel
269
+
identity comes from CoreDevice's `displayId` and pixel agreement from comparing decoded pixels, so
270
+
no claim here rests on luma. Captured dimensions are PNG header dimensions, which is the panel's
271
+
native geometry — the capture's own orientation presents some of them turned.
@@ -289,40 +289,40 @@ returns one element rather than a panel.
289
289
290
290
Four facts the capture path cannot read off the image:
291
291
292
-
-**Identity, and how little of it is declared.**`XCUIScreen.h` declares `screens` and`mainScreen`
293
-
alone, and documents `mainScreen` as "the primary screen of the device", so naming the outer panel
294
-
in every pose is the documented behavior and not a malfunction. `displayID`,`scale`, and `bounds`
295
-
answered KVC on every screen measured while `frame` and `name` raised`NSUnknownKeyException`, but
296
-
none of those keys appears in any XCTest header in this toolchain: the identity read is as
297
-
undocumented as the one #2724 already relies on for gesture routing, and#2728 inherits that
298
-
breakage risk whichever way it goes. It should reuse #2724's resolved-display read rather than open a
299
-
third route to the same private key. The ordering #2724 recorded held here: `app.screen` and an
300
-
unresolved window reported `displayID``1` while the app was visibly on panel `3`, and the resolved
301
-
window reported `3`. `XCUIScreen` carries no panel-power fact and no`displayWithID:` lookup, so a
302
-
panel is chosen by filtering `XCUIScreen.screens` and`backlightState` stays CoreDevice's.
303
-
-**Geometry.** The capture carries the panel's own scale (measured `3`, equal to that panel's
304
-
CoreDevice `pointScale`) in the panel's *native* geometry rather than the interface orientation: on
305
-
the `rot90` inner panel the PNG is `2006x2852` with the landscape content rotated inside it and the
306
-
`UIImage` carrying capture orientation raw value `3`, whose display size transposes the panel,
307
-
where `simctl` exports the same panel `2853x2007` upright. The runner's production encoder and
308
-
`XCUIScreenshot`'s produce 0 differing pixels for one capture from `358,402` and `328,181` encoded
309
-
bytes, so the turn belongs to the capture and not to an encoder. Rotating is not enough to compare
310
-
the two: the runner's canvas is `2006x2852` and `simctl`'s `2853x2007`, a pixel apart on each axis,
311
-
so #2729's normalization owes a rotation and a crop.
312
-
-**Overlays.** A screen capture and a window capture are both display captures — the second cropped
313
-
to the window — so the software keyboard, a SpringBoard-hosted permission alert, and the status bar
314
-
all appear in either. It cuts the other way as well: that alert's own window resolved to
315
-
`displayID``3`, the dark panel in the closed pose, and capturing it yielded a black`668x950` crop
316
-
indistinguishable from any capture of a dark panel. Whether a system window on the*lit* panel
317
-
captures was not measured, so a system surface is verified on the app's panel, not through its
318
-
window.
319
-
-**Unresolved window.** Asking an element that does not exist for screenshot data raises
320
-
`Element Window (First Match) cannot request screenshot data because it does not exist` instead of
321
-
capturing anything, but that is the element route only: `XCUIAutomation` also contains `Could not
322
-
resolve displayID for snapshot %@; falling back to main display (id %lld)`, so an internal
323
-
snapshot-to-display resolution failure can reach the main display silently. A helper therefore
324
-
resolves the window itself and reports its own typed reason, and does not treat that message text as
325
-
the contract. Defaulting to `XCUIScreen.main` on that path would be this ADR's original bug, renamed.
292
+
-**Identity, and how little of it is declared.**`XCUIScreen.h` declares `screens` and
293
+
`mainScreen`alone, and documents `mainScreen` as "the primary screen of the device", so naming
294
+
the outer panel in every pose is the documented behavior and not a malfunction. `displayID`,
295
+
`scale`, and `bounds`answered KVC on every screen measured while `frame` and `name` raised
296
+
`NSUnknownKeyException`, but none of those keys appears in any XCTest header in this toolchain:
297
+
the identity read is as undocumented as the one #2724 already relies on for gesture routing, and
298
+
#2728 inherits that breakage risk whichever way it goes. It should reuse #2724's resolved-display
299
+
read rather than open a third route to the same private key. The ordering #2724 recorded held
300
+
here: `app.screen` and an unresolved window reported `displayID``1` while the app was visibly on
301
+
panel `3`, and the resolved window reported `3`. `XCUIScreen` carries no panel-power fact and no
302
+
`displayWithID:` lookup, so a panel is chosen by filtering `XCUIScreen.screens` and
303
+
`backlightState` stays CoreDevice's. - **Geometry.** The capture carries the panel's own scale
304
+
(measured `3`, equal to that panel's CoreDevice `pointScale`) in the panel's *native* geometry
305
+
rather than the interface orientation: on the `rot90` inner panel the PNG is `2006x2852` with the
306
+
landscape content rotated inside it and the `UIImage` carrying capture orientation raw value `3`,
307
+
whose display size transposes the panel, where `simctl` exports the same panel `2853x2007`
308
+
upright. The runner's production encoder and `XCUIScreenshot`'s produce 0 differing pixels for
309
+
one capture from `358,402` and `328,181` encoded bytes, so the turn belongs to the capture and
310
+
not to an encoder. Rotating is not enough to compare the two: the runner's canvas is `2006x2852`
311
+
and `simctl`'s `2853x2007`, a pixel apart on each axis, so #2729's normalization owes a rotation
312
+
and a crop. - **Overlays.** A screen capture and a window capture are both display captures — the
313
+
second cropped to the window — so the software keyboard, a SpringBoard-hosted permission alert,
314
+
and the status bar all appear in either. It cuts the other way as well: that alert's own window
315
+
resolved to `displayID``3`, the dark panel in the closed pose, and capturing it yielded a black
316
+
`668x950` crop indistinguishable from any capture of a dark panel. Whether a system window on the
317
+
*lit* panel captures was not measured, so a system surface is verified on the app's panel, not
318
+
through its window. - **Unresolved window.** Asking an element that does not exist for screenshot
319
+
data raises `Element Window (First Match) cannot request screenshot data because it does not
320
+
exist` instead of capturing anything, but that is the element route only: `XCUIAutomation` also
321
+
contains `Could not resolve displayID for snapshot %@; falling back to main display (id %lld)`,
322
+
so an internal snapshot-to-display resolution failure can reach the main display silently. A
323
+
helper therefore resolves the window itself and reports its own typed reason, and does not treat
324
+
that message text as the contract. Defaulting to `XCUIScreen.main` on that path would be this
325
+
ADR's original bug, renamed.
326
326
327
327
On the single-panel control every surface agreed: one screen, `1206x2622`, `rot0`, upright crops, no
328
328
rotation to repair. A window-resolved source changes nothing there except that its identity becomes
@@ -332,45 +332,45 @@ explicit.
332
332
333
333
-**Runner capture migration.**`XCUIScreen.main` is six call expressions in four files, and the
334
334
iOS-reachable ones capture a dark panel once an unfolded Duo moves the app to the inner one: the
335
-
`screenshot` command's non-macOS branch in `RunnerTests+CommandExecution.swift`; its two
336
-
`#if os(macOS)` siblings are `XCUIScreen.main` captures too and only the branch between them
337
-
captures the app's own root, so the desktop's behavior stays unmeasured here and the desktop also
338
-
reaches the screen through Screen Capture Kit in `AgentDeviceMacOSHelper`. Then `captureRunnerFrame`
339
-
in `RunnerTests+Lifecycle.swift`, which feeds both the recorder and the keyboard stability
335
+
`screenshot` command's non-macOS branch in `RunnerTests+CommandExecution.swift`; its two `#if
336
+
os(macOS)` siblings are `XCUIScreen.main` captures too and only the branch between them captures
337
+
the app's own root, so the desktop's behavior stays unmeasured here and the desktop also reaches
338
+
the screen through Screen Capture Kit in `AgentDeviceMacOSHelper`. Then `captureRunnerFrame` in
339
+
`RunnerTests+Lifecycle.swift`, which feeds both the recorder and the keyboard stability
340
340
fingerprint in `RunnerTests+Keyboard.swift`; the in-app-back visual-state probe in
341
341
`RunnerTests+Navigation.swift`; and the synthesized-gesture reference frame in
342
342
`RunnerTests+Interaction.swift`, which only the unmerged #2724 replaces. All of them call the
343
-
expression the measurement above ran, so they follow by construction and not by measurement, and two
344
-
fail less visibly than a black screenshot: identical black samples satisfy
343
+
expression the measurement above ran, so they follow by construction and not by measurement, and
344
+
two fail less visibly than a black screenshot: identical black samples satisfy
345
345
`runnerScreenshotStabilitySettled` on its first interval whatever the keyboard is doing, and an
346
-
unchanged black pair logs `AGENT_DEVICE_RUNNER_IN_APP_BACK_FALLBACK_NO_STATE_CHANGE` and reports a
347
-
back navigation that worked as one that failed. Host-side, `screenshot.ts` passes no scale precisely
348
-
because the runner captures `XCUIScreen.main`, `display-inventory.test.ts` asserts that, and
349
-
`commands.md` tells users the physical capture is built from`XCUIScreen.main.screenshot()` frames,
350
-
so all three move with the runner; #2727's comment carries the line-numbered inventory. CoreDevice still names the
351
-
panel, since `XCUIScreen` has no panel-power fact to trade on. Physical devices compile the same
352
-
source and no physical foldable was measured, so that path stays unverified.
353
-
-**Quarter-turn detection.** Both Duo panels report`currentOrientation: rot90`, and no available
354
-
path rotates a foldable, so the orientation half of the inventory is carried but never exercised
355
-
against a changed value.
356
-
-**Pose control on a second Device Hub instance.**`fold` drives the first `DeviceHub` process in
357
-
the process table. Two Xcodes each running a Device Hub is not a state this was verified in.
358
-
-**A hinge that settles slowly.** Four reads is twenty seconds of streams, and a Duo that needs
359
-
longer to come to rest inside `half-open` is now refused where the superseded rule would have
360
-
reported a pose. Every Duo run observed for this change settled inside the budget; no simulator
361
-
that needs longer was seen, so the budget stays as it is rather than growing on a hypothesis.
346
+
unchanged black pair logs `AGENT_DEVICE_RUNNER_IN_APP_BACK_FALLBACK_NO_STATE_CHANGE` and reports
347
+
a back navigation that worked as one that failed. Host-side, `screenshot.ts` passes no scale
348
+
precisely because the runner captures `XCUIScreen.main`, `display-inventory.test.ts` asserts
349
+
that, and `commands.md` tells users the physical capture is built from
350
+
`XCUIScreen.main.screenshot()` frames, so all three move with the runner; #2727's comment carries
351
+
the line-numbered inventory. CoreDevice still names the panel, since `XCUIScreen` has no
352
+
panel-power fact to trade on. Physical devices compile the same source and no physical foldable
353
+
was measured, so that path stays unverified. - **Quarter-turn detection.** Both Duo panels report
354
+
`currentOrientation: rot90`, and no available path rotates a foldable, so the orientation half of
355
+
the inventory is carried but never exercised against a changed value. - **Pose control on a
356
+
second Device Hub instance.**`fold` drives the first `DeviceHub` process in the process table.
357
+
Two Xcodes each running a Device Hub is not a state this was verified in. - **A hinge that
358
+
settles slowly.** Four reads is twenty seconds of streams, and a Duo that needs longer to come to
359
+
rest inside `half-open` is now refused where the superseded rule would have reported a pose.
360
+
Every Duo run observed for this change settled inside the budget; no simulator that needs longer
361
+
was seen, so the budget stays as it is rather than growing on a hypothesis.
362
362
363
363
-**Pose control when two simulators share a name.**`fold` picks the device by the sidebar row's
364
364
`AXIdentifier`, but `selectDevice` in `DeviceHubPose.swift` confirms the switch through
365
-
`windowShows(deviceName:)`, which reads the window title, and it skips the selection altogether when
366
-
no row was found and that title already matches — and two simulators named `iPhone Duo` are both
367
-
titled `iPhone Duo – iOS 27.1`. Observed while pressing the poses for the captures above, and
368
-
consistent with that path, a `fold open` aimed at one Duo pressed the pose control of the other,
369
-
which unfolded while the intended device stayed closed; the `apple_fold_pose_pressed` diagnostic
370
-
reports `selected` and nothing gates the press on it. The hinge read-back is what stopped the
371
-
command reporting a pose it had not achieved, yet the untargeted device had already moved. Selecting that device's row before pressing routed every later pose correctly, so the row is
372
-
the only device identity Device Hub offers and an unconfirmed selection leaves the press aimed at
373
-
whatever it happens to display.
374
-
-**Physical foldables.** Device Hub poses simulators only; the leaf fact refuses a physical device,
375
-
and the hinge stream on one was not exercised.
365
+
`windowShows(deviceName:)`, which reads the window title, and it skips the selection altogether
366
+
when no row was found and that title already matches — and two simulators named `iPhone Duo` are
367
+
both titled `iPhone Duo – iOS 27.1`. Observed while pressing the poses for the captures above,
368
+
and consistent with that path, a `fold open` aimed at one Duo pressed the pose control of the
369
+
other, which unfolded while the intended device stayed closed; the `apple_fold_pose_pressed`
370
+
diagnostic reports `selected` and nothing gates the press on it. The hinge read-back is what
371
+
stopped the command reporting a pose it had not achieved, yet the untargeted device had already
372
+
moved. Selecting that device's row before pressing routed every later pose correctly, so the row
373
+
is the only device identity Device Hub offers and an unconfirmed selection leaves the press aimed
374
+
at whatever it happens to display. - **Physical foldables.** Device Hub poses simulators only;
375
+
the leaf fact refuses a physical device, and the hinge stream on one was not exercised.
0 commit comments