Skip to content

Commit 8db5091

Browse files
fix(ios): guard Duo picker mapping and report panel read failures
1 parent 94cf7fd commit 8db5091

8 files changed

Lines changed: 77 additions & 19 deletions

File tree

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -372,20 +372,21 @@ Rejected alternatives:
372372

373373
`XCUIDevice.orientation` has no effect on an iPhone Duo simulator, and the runner readback repeats the requested value.
374374
`devicectl device orientation set` reports success and has no effect on a simulator that `simctl boot` started.
375-
`orientation` therefore rotates a multi-panel simulator through the guest device-state control: the HID event that Device Hub's orientation menu sends (`orientation-picker-control`, type `enum`).
375+
`orientation` therefore rotates a multi-panel iPhone Duo simulator through the guest device-state control: the HID event that Device Hub's orientation menu sends (`orientation-picker-control`, type `enum`).
376376
The picker accepts `pud` for upside-down dispatch, which the inner panel needs to show landscape-left.
377377
The user target `portrait-upside-down` remains refused with `unsupported-foldable-orientation`.
378378
Routing uses the `fold` admission and the set-based panel-count source. A resolved panel count is a hardware fact, so the daemon probes each simulator once.
379379
A supplied helper is a reuse handle; only an explicit guest-source request changes the default-set source.
380380
Thus, classifying a single-panel default-set simulator does not prepare the fold helper.
381381

382-
Verification was updated on 2026-11-12 under [#4440](https://github.com/callstack/agent-device/pull/4440).
382+
The picker mapping requires the discovered model to be iPhone Duo; other multi-panel models are refused.
383383
In both simulator sets, the helper reads the guest panel table and dispatches the fixed picker value for the established lit panel.
384384
The table maps the outer panel at zero offset and the inner panel at +90 degrees.
385385
Only a fresh `currentOrientation` from an established lit panel confirms the requested visible orientation.
386386
An incomplete table, unknown-power sibling, or multiple lit panels cannot confirm or dispatch.
387387
A repeated visible target dispatches nothing; delayed reads wait without resending to the same panel.
388388
A target that never appears is refused with `orientation-unverified` in either set.
389+
An unreadable guest table reports `orientation-panel-table-unavailable` and points to the inventory diagnostic.
389390

390391
Rejected alternatives:
391392

‎docs/agents/device-foldable.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Foldable Apple verification
22

3-
Read ADR 0025 before capture changes.
3+
Before capture changes, read ADR 0025.
44
For default-set capture, run `xcrun devicectl device info displays --device <udid>`.
55
For scoped capture or rotation, run `xcrun simctl --set <set> spawn <udid> ~/.agent-device/fold-helper/<key>/fold-helper panels`.
66
For default-set rotation, omit `--set <set>`.

‎packages/platform-apple/src/foldable/orientation.test.ts‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,12 @@ beforeEach(() => {
3333
let simulatorCount = 0;
3434
function simulator(overrides: Partial<DeviceInfo> = {}): DeviceInfo {
3535
simulatorCount += 1;
36-
return { ...IOS_SIMULATOR, id: `${IOS_SIMULATOR.id}-${simulatorCount}`, ...overrides };
36+
return {
37+
...IOS_SIMULATOR,
38+
model: 'iPhone Duo',
39+
id: `${IOS_SIMULATOR.id}-${simulatorCount}`,
40+
...overrides,
41+
};
3742
}
3843

3944
const SINGLE_PANEL_DISPLAYS = IPHONE_17_SINGLE_PANEL.result.displays;
@@ -125,7 +130,10 @@ test('a cold default Duo helper failure cannot fall back to runner success', asy
125130
);
126131
await expect(rotateDuo(sim, 'landscape-left')).resolves.toMatchObject({
127132
code: 'COMMAND_FAILED',
128-
details: { reason: 'orientation-unverified' },
133+
details: {
134+
reason: 'orientation-panel-table-unavailable',
135+
hint: expect.stringContaining('apple_display_inventory_unresolved'),
136+
},
129137
});
130138
expect(sim.classificationReads).toHaveLength(1);
131139
expect(mockRunner).not.toHaveBeenCalled();
@@ -136,6 +144,7 @@ test('a physical device keeps the runner rotation without a CoreDevice probe', a
136144
const sim = fakeSimulator(IOS_DEVICE, []);
137145
await expect(sim.rotate('landscape-left')).resolves.toEqual({ orientation: 'landscape-left' });
138146
expect(sim.unexpectedTools).toEqual([]);
147+
expect(sim.classificationReads).toEqual([]);
139148
expect(mockRunner).toHaveBeenCalledTimes(1);
140149
});
141150

@@ -652,3 +661,20 @@ test('a rotation is not routed by a pending panel-table retry', async () => {
652661
expect(sim.rotations()).toEqual(['landscape-left']);
653662
expect(mockRunner).not.toHaveBeenCalled();
654663
});
664+
665+
test.each(['iPad Pro', 'Another Foldable', undefined])(
666+
'an unverified multi-panel model %s cannot use the Duo picker mapping',
667+
async (model) => {
668+
const sim = fakeDuo(simulator({ model, name: 'iPhone Duo' }), {
669+
lit: 'outer',
670+
picker: 'portrait',
671+
});
672+
await expect(sim.rotate('landscape-left')).rejects.toMatchObject({
673+
code: 'UNSUPPORTED_OPERATION',
674+
details: { reason: 'unsupported-foldable-model' },
675+
});
676+
expect(ensureFoldHelperBinary).not.toHaveBeenCalled();
677+
expect(sim.rotations()).toEqual([]);
678+
expect(mockRunner).not.toHaveBeenCalled();
679+
},
680+
);

‎packages/platform-apple/src/foldable/orientation.ts‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,13 @@ export async function setAppleFoldableOrientation(
125125
options: { signal?: AbortSignal } = {},
126126
): Promise<{ orientation: DeviceRotation }> {
127127
const { signal } = options;
128+
if (device.model !== 'iPhone Duo') {
129+
throw new AppError('UNSUPPORTED_OPERATION', 'Guest rotation requires an iPhone Duo model', {
130+
deviceId: device.id,
131+
reason: 'unsupported-foldable-model',
132+
hint: 'The guest orientation picker mapping is verified only for iPhone Duo. Use a simulator whose discovered model is iPhone Duo.',
133+
});
134+
}
128135
if (rotation === 'portrait-upside-down') {
129136
throw new AppError('UNSUPPORTED_OPERATION', `${device.name} cannot rotate to ${rotation}`, {
130137
deviceId: device.id,
@@ -208,16 +215,17 @@ async function readLitPanel(
208215
helper: FoldHelper,
209216
signal: AbortSignal | undefined,
210217
): Promise<LitPanel | undefined> {
211-
let inventory: AppleDisplayInventory;
212-
try {
213-
inventory = await queryAppleDisplayInventory(device, {
214-
signal,
215-
source: 'guest',
216-
foldHelper: helper,
218+
const inventory = await queryAppleDisplayInventory(device, {
219+
signal,
220+
source: 'guest',
221+
foldHelper: helper,
222+
});
223+
if (inventory.unresolved) {
224+
throw new AppError('COMMAND_FAILED', 'The guest panel table could not be read', {
225+
deviceId: device.id,
226+
reason: 'orientation-panel-table-unavailable',
227+
hint: 'The fold helper could not provide a usable display table. Check the apple_display_inventory_unresolved diagnostic for the helper or display-table failure, then retry.',
217228
});
218-
} catch (error) {
219-
if (signal?.aborted) throw error;
220-
return undefined;
221229
}
222230
const panel = establishedLitPanel(inventory);
223231
if (!panel) return undefined;

‎packages/platform-apple/src/foldable/pose.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,10 @@ test('sends the simulator HID pose and reports the pose the guest hinge read bac
107107
screen: { display: 'LCD-1', coordinateSpace: 'native-panel', widthPt: 669, heightPt: 951 },
108108
});
109109

110+
expect(mockInventory.mock.calls.map(([, options]) => options.source)).toEqual([
111+
undefined,
112+
'guest',
113+
]);
110114
expect(mockSend).toHaveBeenCalledWith('open', undefined);
111115
expect(mockHinge).toHaveBeenCalledTimes(2);
112116
// Reads are spaced so two samples of a moving hinge cannot land together; the first is not delayed.

‎packages/platform-apple/src/foldable/pose.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ const FOLDABLE_REQUIRED_HINT =
2626
'fold sets the hinge angle of a foldable simulator such as iPhone Duo; this simulator reports one integrated panel, so it has no hinge to pose.';
2727

2828
const INVENTORY_REQUIRED_HINT =
29-
"fold needs the simulator's integrated displays to identify a foldable: the fold helper reads their panel table in either simulator set. The apple_display_inventory_unresolved diagnostic names why the read failed.";
29+
"fold needs the simulator's integrated displays to identify a foldable: the default set uses CoreDevice and a scoped set uses the fold helper. The apple_display_inventory_unresolved diagnostic names why the read failed.";
3030

3131
const DISPATCHED_UNVERIFIED_HINT =
3232
'The pose request was sent and the device may have followed it, but the first hinge-angle read returned no sample, so fold cannot confirm it. Take a screenshot or snapshot to see which panel is lit; hingeReadFailure names why the read failed.';
@@ -49,7 +49,6 @@ export async function setAppleFoldPose(
4949
const helper = createFoldHelper(device);
5050
const inventory = await queryAppleDisplayInventory(device, {
5151
signal: options.signal,
52-
source: 'guest',
5352
foldHelper: helper,
5453
});
5554
requireFoldableInventory(device, inventory);

‎test/integration/provider-scenarios/ios-fold.test.ts‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,11 @@ test('timed fold keyframes reach simulator HID through the public client and dae
8484
const ok = { stdout: '', stderr: '', exitCode: 0 };
8585
let angle = 0;
8686
const tool = createRecordingAppleToolProvider({
87+
devicectl: async (args) => {
88+
assert.deepEqual(args.slice(0, 3), ['device', 'info', 'displays']);
89+
fs.writeFileSync(args.at(-1)!, JSON.stringify({ result: JSON.parse(guestPanelReading()) }));
90+
return ok;
91+
},
8792
simctl: async (args, options) => {
8893
if (args[0] === 'list') {
8994
return {
@@ -142,6 +147,7 @@ test('timed fold keyframes reach simulator HID through the public client and dae
142147
});
143148
assert.equal(result.pose, 'half-open');
144149
assert.equal(result.hingeAngleDegrees, 100);
150+
assert.equal(result.screen?.display, 'LCD-1');
145151
const replayed = await daemon.client().command.fold({
146152
platform: 'ios',
147153
udid: PROVIDER_SCENARIO_IOS_SIMULATOR.id,
@@ -209,6 +215,12 @@ function createFoldLedgerAppleToolProvider(params: {
209215
// Built on the shared recording provider so any call this route does not script (macosHelper,
210216
// macosHost, plist, or an unexpected runCommand) throws instead of being silently answered.
211217
const recording = createRecordingAppleToolProvider({
218+
devicectl: async (args, options) => {
219+
await record('devicectl', args, options);
220+
assert.deepEqual(args.slice(0, 3), ['device', 'info', 'displays']);
221+
fs.writeFileSync(args.at(-1)!, JSON.stringify({ result: JSON.parse(guestPanelReading()) }));
222+
return ok;
223+
},
212224
simctl: async (args, options) => {
213225
if (args[0] === 'list') {
214226
if (params.isTracking()) await record('simctl', args, options);
@@ -344,13 +356,21 @@ function assertFoldLedgerPhaseCoverage(ledger: readonly FoldLedgerCall[]): void
344356
const isDisplayInventory = (call: FoldLedgerCall) =>
345357
call.tool === 'simctl' && call.args[0] === 'spawn' && call.args[3] === 'panels';
346358

359+
assert.equal(
360+
ledger.filter(
361+
(call) =>
362+
call.tool === 'devicectl' && call.args.slice(0, 3).join(' ') === 'device info displays',
363+
).length,
364+
1,
365+
'ledger must record the set-source foldable classification',
366+
);
347367
assert.ok(ledger.some(isBuild), 'ledger is missing the helper-build phase');
348368
assert.ok(ledger.some(isSpawn), 'ledger is missing the HID-dispatch (simctl spawn) phase');
349369
assert.ok(ledger.some(isHingeRead), 'ledger is missing the hinge-settle-read phase');
350370
assert.equal(
351371
ledger.filter(isDisplayInventory).length,
352-
2,
353-
'ledger must record both the foldable-check and the lit-panel guest inventory reads',
372+
1,
373+
'ledger must record the lit-panel guest inventory read',
354374
);
355375
}
356376

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ Back, orientation, and hardware buttons:
125125
- `back` uses app-owned back navigation: visible in-app back UI on Apple targets, and the back keyevent on Android. `--in-app` names this default explicitly.
126126
- On iOS, a single-screen iPhone or an iPad whose app provably fills its screen, `back` can use a top-leading tap when the app tree is unreadable. It compares the screen before and after the tap. If the screen cannot be captured, the command reports an unknown outcome; inspect the screen before you retry.
127127
- `back --system` sends system back input: the Android back keyevent, the iOS back gesture, or the tvOS Siri Remote Menu button. macOS has no system back, so it reports unavailable.
128-
- `orientation portrait|portrait-upside-down|landscape-left|landscape-right` works on iOS and Android mobile targets only. On ADB-backed Android it turns auto-rotate off, and the lock persists after the session ends until something turns it back on. A foldable iPhone simulator (iPhone Duo) refuses `portrait-upside-down`. In both default and scoped simulator sets it rotates through the fold helper and succeeds only when the lit panel shows the requested orientation; if it never does, or the simulator never reports a single lit panel, the command fails with `orientation-unverified`.
128+
- `orientation portrait|portrait-upside-down|landscape-left|landscape-right` works on iOS and Android mobile targets only. On ADB-backed Android it turns auto-rotate off, and the lock persists after the session ends until something turns it back on. In both default and scoped simulator sets, an iPhone Duo classified with more than one integrated panel refuses `portrait-upside-down` and rotates through the fold helper. It succeeds only when the lit panel shows the requested orientation; if it never does, or the simulator never reports a single lit panel, the command fails with `orientation-unverified`. An unreadable guest table reports `orientation-panel-table-unavailable`. Other multi-panel simulator models are refused. A simulator classified with one panel, or whose first classification read is unresolved, uses the standard runner rotation.
129129
- `orientation auto` hands rotation back to the sensor on ADB-backed Android, local or Limrun (`accelerometer_rotation=1`, `user_rotation` untouched), and reports `orientation: "auto"`. It does not wait for the display to rotate, because there is no target rotation: the sensor decides, and an emulator usually settles on portrait. Every other backend refuses `auto` with `UNSUPPORTED_OPERATION`.
130130
- `action-button` presses the iPhone or iPad Action Button once. It takes no arguments, no hold duration, and no `--settle`, and it doesn't activate the session app or drive Camera Control. Other platforms refuse it, and a model without the button (an iPhone SE, most iPad simulators) fails with `UNSUPPORTED_OPERATION`.
131131
- `action-button` reports that the press was dispatched, not what it triggered. Simulators run no Shortcuts or App Intents, so verify the outcome on a physical iPhone. Expect a press to take about five seconds on a Simulator.

0 commit comments

Comments
 (0)