Skip to content

Commit 7c2b93a

Browse files
committed
docs(adr): wrap the capture section to the file's line budget
The added paragraphs ran past the hundred-column wrap the rest of the file keeps. Text is unchanged; every token matches the previous commit.
1 parent 45e2984 commit 7c2b93a

1 file changed

Lines changed: 81 additions & 81 deletions

File tree

‎docs/adr/0025-foldable-apple-panels.md‎

Lines changed: 81 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -256,19 +256,19 @@ afterwards.
256256

257257
## Which XCTest capture surface sees the lit panel
258258

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.
272272

273273
| Capture surface | Outer panel lit (closed) | Inner panel lit (open, 180°) | Verdict |
274274
| --- | --- | --- | --- |
@@ -289,40 +289,40 @@ returns one element rather than a panel.
289289

290290
Four facts the capture path cannot read off the image:
291291

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.
326326

327327
On the single-panel control every surface agreed: one screen, `1206x2622`, `rot0`, upright crops, no
328328
rotation to repair. A window-resolved source changes nothing there except that its identity becomes
@@ -332,45 +332,45 @@ explicit.
332332

333333
- **Runner capture migration.** `XCUIScreen.main` is six call expressions in four files, and the
334334
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
340340
fingerprint in `RunnerTests+Keyboard.swift`; the in-app-back visual-state probe in
341341
`RunnerTests+Navigation.swift`; and the synthesized-gesture reference frame in
342342
`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
345345
`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.
362362

363363
- **Pose control when two simulators share a name.** `fold` picks the device by the sidebar row's
364364
`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.
376376

0 commit comments

Comments
 (0)