Skip to content

Commit f6ec1d7

Browse files
committed
refactor: read Apple capability closures from a per-AppleOS table (#978)
Introduce a per-`AppleOS` capability data table (`src/core/platform-plugin/apple-os-capabilities.ts`) — the capability-axis sibling of `RUNNER_PLATFORM_PROFILES` and the Swift `#if os()` guards — and have the Apple capability closures read `device.appleOs` through it, collapsing the scattered `target !== 'tv'` / `platform !== 'macos'` / `isTvOsDevice` predicates into one lookup (`resolveDeviceAppleOs` + `appleOsCapabilities`). Discipline (perfect-shape §7 / ADR-0009 step d.5): relocate the OS-axis predicates into data, never change behavior. Only the AppleOS-shaped facts moved to the table; the DEVICE-shaped nuance (simulator vs physical device — e.g. two-finger synthesis is iOS-simulator-only, and the physical-iOS hint) stays in the reading closure, and non-Apple branches keep their verbatim verdicts (`appleOsCapabilities` returns `undefined` off the Apple family). Parity gate: a new table-equivalence test (`apple-os-capability-table-parity.test.ts`) pins the table-driven closures byte-for-byte against an INDEPENDENT verbatim copy of the original predicates across the full {command × sample-device} matrix, and the existing capability-plugin-routing-parity test is extended with appleOs-bearing iPadOS/visionOS fixtures so the stored-`appleOs` read path is covered (iOS/iPadOS/tvOS/macOS/visionOS). Deferred (behavior-change risk / out of scope): the `isTvOsDevice` interaction leaves (dispatch-interactions, interactors/apple, platforms/ios) are irreducible per-device gesture/focus synthesis, not capability admission; per-gesture table granularity (pinch/rotate/transform) is left as one `multiTouchSynthesis` field since all three are uniform today.
1 parent 6e8e45f commit f6ec1d7

6 files changed

Lines changed: 453 additions & 35 deletions

File tree

‎src/__tests__/test-utils/device-fixtures.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,3 +65,26 @@ export const TVOS_SIMULATOR: DeviceInfo = {
6565
kind: 'simulator',
6666
target: 'tv',
6767
};
68+
69+
// iPadOS / visionOS carry the explicit `appleOs` discriminant discovery stores, so
70+
// the per-AppleOS capability table's stored-`appleOs` read path is exercised (not just
71+
// the target-based inference the iPhone/tvOS/macOS fixtures cover). Both are modeled as
72+
// the touch iOS engine (`platform: 'ios'`, mobile target) and are capability-identical
73+
// to iOS today.
74+
export const IPADOS_SIMULATOR: DeviceInfo = {
75+
platform: 'ios',
76+
id: 'ipad-sim-1',
77+
name: 'iPad Pro 11-inch',
78+
kind: 'simulator',
79+
appleOs: 'ipados',
80+
booted: true,
81+
};
82+
83+
export const VISIONOS_SIMULATOR: DeviceInfo = {
84+
platform: 'ios',
85+
id: 'vision-sim-1',
86+
name: 'Apple Vision Pro',
87+
kind: 'simulator',
88+
appleOs: 'visionos',
89+
booted: true,
90+
};

‎src/__tests__/test-utils/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,11 @@ export {
33
ANDROID_TV_DEVICE,
44
IOS_DEVICE,
55
IOS_SIMULATOR,
6+
IPADOS_SIMULATOR,
67
LINUX_DEVICE,
78
MACOS_DEVICE,
89
TVOS_SIMULATOR,
10+
VISIONOS_SIMULATOR,
911
WEB_DESKTOP_DEVICE,
1012
} from './device-fixtures.ts';
1113

‎src/core/__tests__/capability-plugin-routing-parity.test.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,11 @@ import {
1212
ANDROID_TV_DEVICE,
1313
IOS_DEVICE,
1414
IOS_SIMULATOR,
15+
IPADOS_SIMULATOR,
1516
LINUX_DEVICE,
1617
MACOS_DEVICE,
1718
TVOS_SIMULATOR,
19+
VISIONOS_SIMULATOR,
1820
WEB_DESKTOP_DEVICE,
1921
} from '../../__tests__/test-utils/index.ts';
2022
import {
@@ -81,6 +83,11 @@ const SAMPLE_DEVICES: DeviceInfo[] = [
8183
ANDROID_TV_DEVICE,
8284
IOS_DEVICE,
8385
IOS_SIMULATOR,
86+
// The appleOs-bearing iPadOS/visionOS shapes exercise the per-AppleOS table's
87+
// stored-`appleOs` read path (step d.5); the target-based oracle below still agrees
88+
// because both are modeled as the mobile iOS engine and are capability-identical.
89+
IPADOS_SIMULATOR,
90+
VISIONOS_SIMULATOR,
8491
LINUX_DEVICE,
8592
MACOS_DEVICE,
8693
TVOS_SIMULATOR,
Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { isAudioProbeSupportedDevice } from '../../../kernel/audio-probe-support.ts';
4+
import {
5+
DEVICE_TARGETS,
6+
PLATFORMS,
7+
type AppleOS,
8+
type DeviceInfo,
9+
type DeviceKind,
10+
type DeviceTarget,
11+
} from '../../../kernel/device.ts';
12+
import {
13+
ANDROID_EMULATOR,
14+
ANDROID_TV_DEVICE,
15+
IOS_DEVICE,
16+
IOS_SIMULATOR,
17+
IPADOS_SIMULATOR,
18+
LINUX_DEVICE,
19+
MACOS_DEVICE,
20+
TVOS_SIMULATOR,
21+
VISIONOS_SIMULATOR,
22+
WEB_DESKTOP_DEVICE,
23+
} from '../../../__tests__/test-utils/index.ts';
24+
import { APPLE_OS_CAPABILITIES, resolveDeviceAppleOs } from '../apple-os-capabilities.ts';
25+
import { getPlugin } from '../plugin.ts';
26+
import { registerBuiltinPlatformPlugins } from '../register-builtins.ts';
27+
28+
// Phase 3 step d.5 table-equivalence gate. The AppleOS-axis predicates
29+
// (`target !== 'tv'` / `platform !== 'macos'` / `isTvOsDevice`) that used to be
30+
// open-coded in the Apple capability closures now READ the per-`AppleOS` data table
31+
// (`apple-os-capabilities.ts`). This test pins that the swap is byte-for-byte
32+
// behaviorless: the closures now living on the Apple plugin return an identical
33+
// boolean / identical hint STRING to an INDEPENDENT verbatim copy of the ORIGINAL
34+
// predicates, across the full {command x sample-device} matrix — real discovery shapes
35+
// for iOS/iPadOS/tvOS/macOS/visionOS plus the exhaustive synthetic cross-product.
36+
37+
registerBuiltinPlatformPlugins();
38+
39+
// ---------------------------------------------------------------------------
40+
// Independent VERBATIM copies of the ORIGINAL command-facet predicates (before the
41+
// table read), kept BYTE-FOR-BYTE by hand so this oracle stays INDEPENDENT of the
42+
// table it pins (mirrors the copy in capability-plugin-routing-parity.test.ts).
43+
// ---------------------------------------------------------------------------
44+
const isNotMacOs = (device: DeviceInfo): boolean => device.platform !== 'macos';
45+
const isMacOsOrAppleSimulator = (device: DeviceInfo): boolean =>
46+
device.platform === 'macos' || device.kind === 'simulator';
47+
const isIosMobileSimulator = (device: DeviceInfo): boolean =>
48+
device.platform === 'ios' && device.kind === 'simulator' && device.target !== 'tv';
49+
const supportsSynthesisGesture = (device: DeviceInfo): boolean =>
50+
device.platform === 'android' || isIosMobileSimulator(device);
51+
const supportsAndroidOrIosNonTv = (device: DeviceInfo): boolean =>
52+
device.platform === 'android' || (device.platform === 'ios' && device.target !== 'tv');
53+
const synthesisGestureUnsupportedHint = (device: DeviceInfo): string | undefined => {
54+
if (device.platform === 'macos')
55+
return 'macOS automation has no multi-touch input — this gesture is supported on Android and the iOS simulator only.';
56+
if (device.platform === 'ios' && device.target === 'tv')
57+
return 'tvOS has no touch input — this gesture is supported on Android and the iOS simulator only.';
58+
if (device.platform === 'ios' && device.kind === 'device')
59+
return 'Two-finger gesture synthesis is iOS-simulator only — not available on physical iOS devices.';
60+
return undefined;
61+
};
62+
63+
const SUPPORTS_REF: Record<string, (device: DeviceInfo) => boolean> = {
64+
boot: isNotMacOs,
65+
install: isNotMacOs,
66+
reinstall: isNotMacOs,
67+
'install-from-source': isNotMacOs,
68+
push: isNotMacOs,
69+
home: isNotMacOs,
70+
'app-switcher': isNotMacOs,
71+
clipboard: (device) =>
72+
device.platform === 'android' ||
73+
device.platform === 'linux' ||
74+
device.platform === 'macos' ||
75+
device.kind === 'simulator',
76+
keyboard: supportsAndroidOrIosNonTv,
77+
rotate: supportsAndroidOrIosNonTv,
78+
alert: (device) => device.platform === 'android' || isMacOsOrAppleSimulator(device),
79+
settings: (device) =>
80+
device.platform === 'android' || device.platform === 'macos' || device.kind === 'simulator',
81+
// `audio` is NOT part of the AppleOS-table relocation — it stays the standalone
82+
// `isAudioProbeSupportedDevice` predicate. Included here only so the key-set
83+
// assertion stays strict (catches a dropped command) and confirms the rebase
84+
// did not alter it.
85+
audio: isAudioProbeSupportedDevice,
86+
pinch: supportsSynthesisGesture,
87+
'rotate-gesture': supportsSynthesisGesture,
88+
'transform-gesture': supportsSynthesisGesture,
89+
};
90+
const HINT_REF: Record<string, (device: DeviceInfo) => string | undefined> = {
91+
pinch: synthesisGestureUnsupportedHint,
92+
'rotate-gesture': synthesisGestureUnsupportedHint,
93+
'transform-gesture': synthesisGestureUnsupportedHint,
94+
};
95+
96+
// ---------------------------------------------------------------------------
97+
// The sample-device matrix: the real discovery fixtures (incl. the appleOs-bearing
98+
// iPadOS/visionOS shapes, so the table's stored-`appleOs` read path is exercised) plus
99+
// per-kind clones of every Apple fixture (so the physical-device paths run per OS) plus
100+
// the exhaustive synthetic cross-product (the target-inference read path).
101+
// ---------------------------------------------------------------------------
102+
const APPLE_FIXTURES: DeviceInfo[] = [
103+
IOS_SIMULATOR,
104+
IOS_DEVICE,
105+
IPADOS_SIMULATOR,
106+
VISIONOS_SIMULATOR,
107+
TVOS_SIMULATOR,
108+
MACOS_DEVICE,
109+
];
110+
111+
function withKinds(device: DeviceInfo): DeviceInfo[] {
112+
const kinds: DeviceKind[] = ['simulator', 'device'];
113+
return kinds.map((kind) => ({ ...device, kind, id: `${device.id}-${kind}` }));
114+
}
115+
116+
const DEVICE_KINDS_ALL: DeviceKind[] = ['simulator', 'emulator', 'device'];
117+
const DEVICE_TARGETS_ALL: (DeviceTarget | undefined)[] = [undefined, ...DEVICE_TARGETS];
118+
119+
function buildSyntheticMatrix(): DeviceInfo[] {
120+
const devices: DeviceInfo[] = [];
121+
for (const platform of PLATFORMS) {
122+
for (const kind of DEVICE_KINDS_ALL) {
123+
for (const target of DEVICE_TARGETS_ALL) {
124+
devices.push({
125+
platform,
126+
id: `${platform}-${kind}-${target ?? 'none'}`,
127+
name: `${platform} ${kind} ${target ?? 'none'}`,
128+
kind,
129+
...(target ? { target } : {}),
130+
booted: true,
131+
});
132+
}
133+
}
134+
}
135+
return devices;
136+
}
137+
138+
const SAMPLE_DEVICES: DeviceInfo[] = [
139+
ANDROID_EMULATOR,
140+
ANDROID_TV_DEVICE,
141+
LINUX_DEVICE,
142+
WEB_DESKTOP_DEVICE,
143+
...APPLE_FIXTURES,
144+
...APPLE_FIXTURES.flatMap(withKinds),
145+
...buildSyntheticMatrix(),
146+
];
147+
148+
test('the per-AppleOS table row keys are exhaustive and iOS/iPadOS/visionOS share one row', () => {
149+
const rows: AppleOS[] = ['ios', 'ipados', 'tvos', 'watchos', 'visionos', 'macos'];
150+
for (const os of rows) {
151+
assert.ok(APPLE_OS_CAPABILITIES[os], `capability row present for ${os}`);
152+
}
153+
// The iOS family is capability-identical today; sharing ONE frozen row is the
154+
// invariant that makes a stored `appleOs: 'ipados' | 'visionos'` read exactly what
155+
// the legacy target-inference produced for an unlabeled iOS record.
156+
assert.equal(APPLE_OS_CAPABILITIES.ios, APPLE_OS_CAPABILITIES.ipados);
157+
assert.equal(APPLE_OS_CAPABILITIES.ios, APPLE_OS_CAPABILITIES.visionos);
158+
});
159+
160+
test('resolveDeviceAppleOs prefers the stored discriminant, else infers from target', () => {
161+
// Stored `appleOs` wins.
162+
assert.equal(resolveDeviceAppleOs(IPADOS_SIMULATOR), 'ipados');
163+
assert.equal(resolveDeviceAppleOs(VISIONOS_SIMULATOR), 'visionos');
164+
// Inference fallback for the fixtures that predate `appleOs`.
165+
assert.equal(resolveDeviceAppleOs(IOS_SIMULATOR), 'ios');
166+
assert.equal(resolveDeviceAppleOs(IOS_DEVICE), 'ios');
167+
assert.equal(resolveDeviceAppleOs(TVOS_SIMULATOR), 'tvos');
168+
assert.equal(resolveDeviceAppleOs(MACOS_DEVICE), 'macos');
169+
});
170+
171+
test('table-driven Apple supports() closures are byte-for-byte the verbatim originals', () => {
172+
const appleSupports = getPlugin('ios').capability.supportsByDefault;
173+
assert.ok(appleSupports, 'the Apple plugin carries supportsByDefault');
174+
// Every command that had an original predicate must still carry one, keyed the same.
175+
assert.deepEqual(Object.keys(appleSupports).sort(), Object.keys(SUPPORTS_REF).sort());
176+
for (const [command, reference] of Object.entries(SUPPORTS_REF)) {
177+
const relocated: ((device: DeviceInfo) => boolean) | undefined = appleSupports[command];
178+
assert.ok(relocated, `${command} supports closure present on the Apple plugin`);
179+
for (const device of SAMPLE_DEVICES) {
180+
assert.equal(
181+
relocated(device),
182+
reference(device),
183+
`${command} supports on ${device.id} (appleOs=${device.appleOs ?? 'inferred'})`,
184+
);
185+
}
186+
}
187+
});
188+
189+
test('table-driven Apple unsupportedHint() closures are byte-for-byte the verbatim originals', () => {
190+
const appleHints = getPlugin('ios').capability.unsupportedHintByDefault;
191+
assert.ok(appleHints, 'the Apple plugin carries unsupportedHintByDefault');
192+
assert.deepEqual(Object.keys(appleHints).sort(), Object.keys(HINT_REF).sort());
193+
for (const [command, reference] of Object.entries(HINT_REF)) {
194+
const relocated: ((device: DeviceInfo) => string | undefined) | undefined = appleHints[command];
195+
assert.ok(relocated, `${command} hint closure present on the Apple plugin`);
196+
for (const device of SAMPLE_DEVICES) {
197+
assert.equal(
198+
relocated(device),
199+
reference(device),
200+
`${command} hint on ${device.id} (appleOs=${device.appleOs ?? 'inferred'})`,
201+
);
202+
}
203+
}
204+
});

0 commit comments

Comments
 (0)