Skip to content

Commit dec7c9b

Browse files
committed
fix(apple): refuse a foldable capture when CoreDevice names no panel
ADR 0025 decides that only CoreDevice facts identify a panel: the sole lit panel, otherwise the `primary` panel, and never array position. When no panel reported `primary` and power did not decide one lit panel, the inventory captured the first lit or first integrated panel in list order. That inventory now names no panel, and capture-target resolution refuses with COMMAND_FAILED, reason `capture-panel-unidentified`, and a hint. The sole-lit-panel path and the primary-panel path are unchanged. The foldable help topic states the refusal. Evidence: the audit at bd4fd68 (display-inventory.ts:261); re-verified on 4c1c786. Part of #3744.
1 parent 3fdd3ae commit dec7c9b

3 files changed

Lines changed: 99 additions & 12 deletions

File tree

‎packages/platform-apple/src/core/__tests__/display-inventory.test.ts‎

Lines changed: 67 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -266,15 +266,26 @@ describe('buildInventory', () => {
266266
}
267267
});
268268

269-
test('names a capture even when no panel reports primary', () => {
269+
test('names the sole lit panel when no panel reports primary', () => {
270270
const inventory = buildInventory([
271-
{ ...outerPanel, primary: false },
271+
{ ...outerPanel, power: 'dark', primary: false },
272272
{ ...innerPanel, power: 'lit', primary: false },
273273
]);
274274
assert.equal(inventory.multiScreen, true);
275275
assert.equal(inventory.ambiguous, true);
276-
// A capture is still named: never the implicit black-producing default.
277-
assert.ok(inventory.activeDisplay);
276+
assert.equal(inventory.activeDisplay?.name, 'LCD-1');
277+
});
278+
279+
test('names no panel when neither primary nor power identifies one', () => {
280+
for (const power of ['lit', 'dark', 'unknown'] as const) {
281+
const inventory = buildInventory([
282+
{ ...outerPanel, power, primary: false },
283+
{ ...innerPanel, power, primary: false },
284+
]);
285+
assert.equal(inventory.multiScreen, true);
286+
assert.equal(inventory.ambiguous, true);
287+
assert.equal(inventory.activeDisplay, undefined, power);
288+
}
278289
});
279290

280291
test('keeps choosing the lit panel when a third panel is present', () => {
@@ -476,6 +487,58 @@ describe('resolveAppleCaptureTarget', () => {
476487
assert.equal(target.displayRotation, undefined);
477488
});
478489

490+
/** The closed-Duo payload with each panel's `primary` flag and backlight replaced. */
491+
function duoReporting(panels: Record<number, { primary: boolean; backlightState: string }>) {
492+
return JSON.stringify({
493+
result: {
494+
displays: IPHONE_DUO_CLOSED.result.displays.map((entry) => ({
495+
...entry,
496+
...panels[entry.displayId],
497+
})),
498+
},
499+
});
500+
}
501+
502+
test('names the primary panel when panel power is ambiguous', async () => {
503+
mockReadHostTextFile.mockResolvedValue(
504+
duoReporting({
505+
1: { primary: true, backlightState: 'activeOn' },
506+
3: { primary: false, backlightState: 'activeOn' },
507+
}),
508+
);
509+
assert.equal((await resolveAppleCaptureTarget(IOS_TEST_SIMULATOR)).display?.name, 'LCD');
510+
});
511+
512+
test('names the sole lit panel when no panel reports primary', async () => {
513+
mockReadHostTextFile.mockResolvedValue(
514+
duoReporting({
515+
1: { primary: false, backlightState: 'off' },
516+
3: { primary: false, backlightState: 'activeOn' },
517+
}),
518+
);
519+
assert.equal((await resolveAppleCaptureTarget(IOS_TEST_SIMULATOR)).display?.name, 'LCD-1');
520+
});
521+
522+
test('refuses instead of picking a panel by list order when no fact identifies one', async () => {
523+
for (const backlightState of ['activeOn', 'off', 'futureState']) {
524+
mockReadHostTextFile.mockResolvedValue(
525+
duoReporting({
526+
1: { primary: false, backlightState },
527+
3: { primary: false, backlightState },
528+
}),
529+
);
530+
await assert.rejects(
531+
resolveAppleCaptureTarget(IOS_TEST_SIMULATOR),
532+
(error: unknown) =>
533+
error instanceof AppError &&
534+
error.code === 'COMMAND_FAILED' &&
535+
error.details?.reason === 'capture-panel-unidentified' &&
536+
typeof error.details?.hint === 'string',
537+
backlightState,
538+
);
539+
}
540+
});
541+
479542
test('reports nothing when CoreDevice cannot be asked', async () => {
480543
mockRunXcrun.mockResolvedValueOnce({
481544
exitCode: 1,

‎packages/platform-apple/src/core/display-inventory.ts‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import type { DeviceRotation } from '@agent-device/contracts/device';
22
import type { DeviceInfo } from '@agent-device/kernel/device';
3+
import { AppError } from '@agent-device/kernel/errors';
34
import { isCommandTimeoutError } from '@agent-device/host-kit/command';
45
import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
56

@@ -45,6 +46,11 @@ export type AppleDisplayInventory = {
4546
* single-screen behavior and never route through a display selector.
4647
*/
4748
multiScreen: boolean;
49+
/**
50+
* The panel a multi-panel capture names. Absent on a multi-panel device when
51+
* neither panel power nor CoreDevice `primary` identifies a panel: list order is
52+
* not identity, so the capture refuses instead.
53+
*/
4854
activeDisplay?: AppleDeviceDisplay;
4955
/**
5056
* True on a multi-panel device whose lit panel could not be decided, so the
@@ -258,7 +264,7 @@ export function buildInventory(displays: AppleDeviceDisplay[]): AppleDisplayInve
258264
// choice is the highest screen ID, which is exactly how a foldable capture comes
259265
// back all black and exits 0. When panel power is ambiguous the primary panel is
260266
// named explicitly and the ambiguity is reported, not hidden.
261-
const captureDisplay = decided ? litPanels[0]! : (primaryPanel ?? litPanels[0] ?? panels[0]!);
267+
const captureDisplay = decided ? litPanels[0]! : primaryPanel;
262268
const ambiguous = !decided || primaryPanel === undefined;
263269
if (ambiguous) {
264270
emitDiagnostic({
@@ -267,20 +273,27 @@ export function buildInventory(displays: AppleDeviceDisplay[]): AppleDisplayInve
267273
data: {
268274
reason: primaryPanel === undefined ? 'no-primary-panel' : 'lit-panel-count',
269275
litPanelCount: litPanels.length,
270-
capturedDisplay: captureDisplay.name,
271-
hint: 'Panel power did not identify exactly one lit panel, so the capture names the primary panel without claiming to know which panel the device is showing. Read the device pose from the app under test with UIHinge.status.',
276+
...(captureDisplay
277+
? {
278+
capturedDisplay: captureDisplay.name,
279+
hint: 'Panel power did not identify exactly one lit panel, so the capture names the primary panel without claiming to know which panel the device is showing. Read the device pose from the app under test with UIHinge.status.',
280+
}
281+
: { hint: UNIDENTIFIED_PANEL_HINT }),
272282
},
273283
});
274284
}
275285
return {
276286
displays: panels,
277287
multiScreen: true,
278-
activeDisplay: captureDisplay,
288+
...(captureDisplay ? { activeDisplay: captureDisplay } : {}),
279289
ambiguous,
280290
unresolved: false,
281291
};
282292
}
283293

294+
const UNIDENTIFIED_PANEL_HINT =
295+
'CoreDevice reported no primary panel and panel power did not identify exactly one lit panel. Run `xcrun devicectl device info displays --device <udid>`, then retry after one panel reports a lit backlightState.';
296+
284297
/**
285298
* Sanity-checks the panel geometry against a foldable's shape.
286299
*
@@ -315,8 +328,9 @@ function warnWhenPrimaryPanelIsNotTheSmallest(panels: AppleDeviceDisplay[]): voi
315328
* `simctl io screenshot` without `--display` silently picks the highest screen
316329
* ID, which on a closed foldable is the *dark* inner panel: the capture succeeds
317330
* and comes back black. A multi-panel device therefore always names a display
318-
* explicitly — even when panel power is ambiguous — and only a genuinely
319-
* single-panel device (or an unreadable toolchain) keeps the historic argv.
331+
* explicitly — even when panel power is ambiguous — or refuses when CoreDevice
332+
* identifies no panel. Only a genuinely single-panel device (or an unreadable
333+
* toolchain) keeps the historic argv.
320334
*/
321335
export async function resolveAppleCaptureDisplay(
322336
device: DeviceInfo,
@@ -336,7 +350,17 @@ export async function resolveAppleCaptureTarget(
336350
const inventory = await queryAppleDisplayInventory(device, options);
337351
if (inventory.unresolved) return {};
338352
if (inventory.multiScreen) {
339-
return inventory.activeDisplay ? { display: inventory.activeDisplay } : {};
353+
if (inventory.activeDisplay) return { display: inventory.activeDisplay };
354+
throw new AppError(
355+
'COMMAND_FAILED',
356+
`CoreDevice did not identify which panel of ${device.name} to capture`,
357+
{
358+
deviceId: device.id,
359+
reason: 'capture-panel-unidentified',
360+
litPanelCount: inventory.displays.filter((display) => display.power === 'lit').length,
361+
hint: UNIDENTIFIED_PANEL_HINT,
362+
},
363+
);
340364
}
341365
// Only a built-in panel is the screen simctl captures; an attached display says nothing about it.
342366
const panel = inventory.displays.find((entry) => entry.integrated);

‎src/commands/system/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,7 @@ export const foldableHelpTopic = {
278278
A foldable Apple device (iPhone Duo) carries two integrated panels, which Apple calls the outer display and the inner display. Only one is lit at a time, and which one is lit is the device pose.
279279
280280
Screens are handled for you:
281-
Each iOS simulator capture resolves the CoreDevice display table, captures the lit panel explicitly, and normalizes density with that panel's own point scale. Do not add a screen flag to the normal loop; there is none, because the lit panel is always the only capturable one: the dark panel yields an all-black PNG.
281+
Each iOS simulator capture resolves the CoreDevice display table, captures the lit panel explicitly, and normalizes density with that panel's own point scale. Do not add a screen flag to the normal loop; there is none, because the lit panel is always the only capturable one: the dark panel yields an all-black PNG. When panel power names no single lit panel, the capture names CoreDevice's primary panel; with no primary panel either, it fails with COMMAND_FAILED and reason capture-panel-unidentified rather than pick a panel by list order.
282282
The two panels are different sizes (iPhone Duo: 466x678 points closed on the outer panel, 669x951 open on the inner). A pose change therefore invalidates every ref and coordinate. Re-snapshot after any pose change and never carry coordinates or refs across one.
283283
Check which panel is lit before trusting a geometry claim: agent-device screenshot reports its point size, and 466x678 versus 669x951 says which panel you captured.
284284

0 commit comments

Comments
 (0)