Skip to content

Commit c0b9c54

Browse files
authored
refactor(apple): promote tvOS to an explicit Apple-OS leaf (#976) (#992)
Name the tvOS Apple-OS leaf instead of branching on a `target === 'tv'` string smeared across the Apple interaction paths (Phase 3 d.2, part of #972). - Add `isTvOsDevice(device)` to kernel/device.ts — the sink, so core, the command-descriptor registry, and the platform code can all gate on one explicit, Apple-only predicate (the layering DAG forbids core importing platforms). Android TV shares `target: 'tv'` but is a distinct leaf, so the `platform === 'ios'` gate is load-bearing. - Extract the XCUIRemote focus-navigation command builder into a real `src/platforms/apple/os/tvos/` leaf (mirroring os/macos/), delivering the dedicated tvOS leaf ADR-0009 deferred. - Route the unambiguous tvOS gates (interactor back/home/scroll, iOS-touch synthesis, registry capability predicates) through `isTvOsDevice`. Do-not-flatten preserved: the tvOS focus-only interaction contract stays per-OS. back/home/scroll drive XCUIRemote focus; coordinate tap goes to the runner un-synthesized (rejected off the focused element); pinch/rotate/ transform stay UNSUPPORTED. This is a rename/extraction — behavior is byte-identical for tvOS devices. Intentionally left (noted inline): devices.ts `resolveAppleOs` (the canonical target→appleOs classification source), and the dispatch pinch/rotate/transform gates — those `target === 'tv'` checks also reject Android TV, so narrowing them to the Apple-only leaf would change Android-TV behavior. Tests: `isTvOsDevice` Apple-only gate (excludes Android TV); tvOS back/home focus navigation via remotePress menu/home + iOS keeps in-app back; tvOS rotate/transform reject UNSUPPORTED at dispatch (alongside existing pinch).
1 parent 643ed2c commit c0b9c54

9 files changed

Lines changed: 154 additions & 31 deletions

File tree

‎src/core/__tests__/dispatch-pinch.test.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,26 @@ test('dispatch pinch rejects tvOS before runner call', async () => {
2323
/pinch is not supported on tvOS/i.test(error.message),
2424
);
2525
});
26+
27+
// tvOS is focus-only: coordinate multi-touch gestures have no meaning off the focused
28+
// element, so rotate/transform reject up front (mirroring pinch above). This pins the
29+
// UNSUPPORTED coordinate-gesture half of the tvOS interaction contract.
30+
test('dispatch rotate-gesture rejects tvOS before runner call', async () => {
31+
await assert.rejects(
32+
() => dispatchCommand(TVOS_SIMULATOR, 'rotate-gesture', ['90']),
33+
(error: unknown) =>
34+
error instanceof AppError &&
35+
error.code === 'UNSUPPORTED_OPERATION' &&
36+
/rotate is not supported on tvOS/i.test(error.message),
37+
);
38+
});
39+
40+
test('dispatch transform-gesture rejects tvOS before runner call', async () => {
41+
await assert.rejects(
42+
() => dispatchCommand(TVOS_SIMULATOR, 'transform-gesture', ['1', '2', '3', '4', '1.5', '90']),
43+
(error: unknown) =>
44+
error instanceof AppError &&
45+
error.code === 'UNSUPPORTED_OPERATION' &&
46+
/transform is not supported on tvOS/i.test(error.message),
47+
);
48+
});

‎src/core/command-descriptor/registry.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import {
55
} from '../../command-catalog.ts';
66
import type { CommandCapability } from '../capabilities.ts';
77
import type { DaemonRequest } from '../../daemon/types.ts';
8-
import type { DeviceInfo } from '../../kernel/device.ts';
8+
import { isTvOsDevice, type DeviceInfo } from '../../kernel/device.ts';
99
import type { CommandDescriptor } from './types.ts';
1010

1111
// ---------------------------------------------------------------------------
@@ -42,16 +42,16 @@ const isNotMacOs = (device: DeviceInfo): boolean => device.platform !== 'macos';
4242
const isMacOsOrAppleSimulator = (device: DeviceInfo): boolean =>
4343
device.platform === 'macos' || device.kind === 'simulator';
4444
const isIosMobileSimulator = (device: DeviceInfo): boolean =>
45-
device.platform === 'ios' && device.kind === 'simulator' && device.target !== 'tv';
45+
device.platform === 'ios' && device.kind === 'simulator' && !isTvOsDevice(device);
4646
const supportsSynthesisGesture = (device: DeviceInfo): boolean =>
4747
device.platform === 'android' || isIosMobileSimulator(device);
4848
const supportsAndroidOrIosNonTv = (device: DeviceInfo): boolean =>
49-
device.platform === 'android' || (device.platform === 'ios' && device.target !== 'tv');
49+
device.platform === 'android' || (device.platform === 'ios' && !isTvOsDevice(device));
5050

5151
const synthesisGestureUnsupportedHint = (device: DeviceInfo): string | undefined => {
5252
if (device.platform === 'macos')
5353
return 'macOS automation has no multi-touch input — this gesture is supported on Android and the iOS simulator only.';
54-
if (device.platform === 'ios' && device.target === 'tv')
54+
if (isTvOsDevice(device))
5555
return 'tvOS has no touch input — this gesture is supported on Android and the iOS simulator only.';
5656
if (device.platform === 'ios' && device.kind === 'device')
5757
return 'Two-finger gesture synthesis is iOS-simulator only — not available on physical iOS devices.';

‎src/core/dispatch-interactions.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { AppError } from '../kernel/errors.ts';
2-
import type { DeviceInfo } from '../kernel/device.ts';
2+
import { isTvOsDevice, type DeviceInfo } from '../kernel/device.ts';
33
import { successText, withSuccessText } from '../utils/success-text.ts';
44
import { findMistargetedTypeRefToken } from '../utils/type-target-warning.ts';
55
import {
@@ -416,9 +416,10 @@ function buildPressSequenceSteps(
416416
series: PressSeriesOptions,
417417
): RunnerSequenceStep[] {
418418
const kind = series.doubleTap ? 'doubleTap' : series.holdMs > 0 ? 'longPress' : 'tap';
419-
// Mirror the individual `tap` command: on iOS non-tv, tap steps use synthesized HID taps
420-
// (synthesizedTapAt) rather than the drag-based XCUICoordinate tapAt, matching iosTapCommand.
421-
const synthesized = kind === 'tap' && device.platform === 'ios' && device.target !== 'tv';
419+
// Mirror the individual `tap` command: on touch-input iOS (not the tvOS leaf), tap steps
420+
// use synthesized HID taps (synthesizedTapAt) rather than the drag-based XCUICoordinate
421+
// tapAt, matching iosTapCommand.
422+
const synthesized = kind === 'tap' && device.platform === 'ios' && !isTvOsDevice(device);
422423
return Array.from({ length: series.count }, (_, index) => {
423424
const [dx, dy] = computeDeterministicJitter(index, series.jitterPx);
424425
const isLast = index === series.count - 1;
@@ -449,7 +450,7 @@ function buildSwipeSequenceSteps(params: {
449450
effectiveDurationMs: number;
450451
}): RunnerSequenceStep[] {
451452
const { device, x1, y1, x2, y2, count, pauseMs, pattern, effectiveDurationMs } = params;
452-
const synthesized = device.platform === 'ios' && device.target !== 'tv';
453+
const synthesized = device.platform === 'ios' && !isTvOsDevice(device);
453454
return Array.from({ length: count }, (_, index) => {
454455
const reverse = pattern === 'ping-pong' && index % 2 === 1;
455456
const isLast = index === count - 1;
@@ -863,6 +864,8 @@ export async function handlePinchCommand(
863864
positionals: string[],
864865
context: DispatchContext | undefined,
865866
): Promise<Record<string, unknown>> {
867+
// Cross-platform TV-target gate (also rejects Android TV, which shares target: 'tv');
868+
// NOT narrowed to the tvOS Apple-OS leaf (isTvOsDevice) so Android-TV behavior is unchanged.
866869
if (device.target === 'tv') {
867870
throw new AppError('UNSUPPORTED_OPERATION', 'gesture pinch is not supported on tvOS');
868871
}
@@ -887,6 +890,7 @@ export async function handleRotateGestureCommand(
887890
interactor: Interactor,
888891
positionals: string[],
889892
): Promise<Record<string, unknown>> {
893+
// Cross-platform TV-target gate (also rejects Android TV) — see handlePinchCommand.
890894
if (device.target === 'tv') {
891895
throw new AppError('UNSUPPORTED_OPERATION', 'gesture rotate is not supported on tvOS');
892896
}
@@ -914,6 +918,7 @@ export async function handleTransformGestureCommand(
914918
interactor: Interactor,
915919
positionals: string[],
916920
): Promise<Record<string, unknown>> {
921+
// Cross-platform TV-target gate (also rejects Android TV) — see handlePinchCommand.
917922
if (device.target === 'tv') {
918923
throw new AppError('UNSUPPORTED_OPERATION', 'gesture transform is not supported on tvOS');
919924
}

‎src/core/interactors/apple.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@ import {
88
writeIosClipboardText,
99
} from '../../platforms/apple/core/apps.ts';
1010
import {
11-
appleRemotePressCommand,
1211
iosRunnerOverrides,
1312
resolveAppleBackRunnerCommand,
1413
} from '../../platforms/ios/interactions.ts';
14+
import { appleRemotePressCommand } from '../../platforms/apple/os/tvos/remote.ts';
1515
import { runMacOsScreenshotAction } from '../../platforms/apple/os/macos/helper.ts';
1616
import { runIosRunnerCommand } from '../../platforms/apple/core/runner/runner-client.ts';
1717
import { withDiagnosticTimer } from '../../utils/diagnostics.ts';
18-
import type { DeviceInfo } from '../../kernel/device.ts';
18+
import { isTvOsDevice, type DeviceInfo } from '../../kernel/device.ts';
1919
import { AppError } from '../../kernel/errors.ts';
2020
import type { RawSnapshotNode } from '../../kernel/snapshot.ts';
2121
import type { Interactor, RunnerContext } from '../interactor-types.ts';
@@ -99,7 +99,8 @@ export function createAppleInteractor(
9999
};
100100
},
101101
back: async (mode) => {
102-
if (device.target === 'tv') {
102+
if (isTvOsDevice(device)) {
103+
// tvOS focus-only navigation: the Menu button pops focus, not a coordinate tap.
103104
await runIosRunnerCommand(
104105
device,
105106
appleRemotePressCommand('menu', runnerContext.appBundleId),
@@ -117,7 +118,8 @@ export function createAppleInteractor(
117118
);
118119
},
119120
home: async () => {
120-
if (device.target === 'tv') {
121+
if (isTvOsDevice(device)) {
122+
// tvOS focus-only navigation: the Home button drives the remote, not a tap.
121123
await runIosRunnerCommand(
122124
device,
123125
appleRemotePressCommand('home', runnerContext.appBundleId),

‎src/kernel/device.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,21 @@ export function isMobilePlatform(platform: Platform): boolean {
5050
return platform === 'ios' || platform === 'android';
5151
}
5252

53+
/**
54+
* The tvOS Apple-OS leaf predicate. tvOS is modeled as the `ios` platform with a
55+
* `tv` form-factor target (ADR-0009 defers the `Platform` collapse; discovery also
56+
* stores `appleOs: 'tvos'`). Naming the leaf keeps its focus-only interaction
57+
* contract — XCUIRemote focus navigation, and NO coordinate tap/gesture — gated by
58+
* one explicit predicate instead of a `target === 'tv'` string compare smeared
59+
* across the Apple interaction paths.
60+
*
61+
* Apple-only by design: Android TV also uses `target: 'tv'` but is a DISTINCT leaf,
62+
* so the `platform === 'ios'` gate is load-bearing (do not widen it to any TV target).
63+
*/
64+
export function isTvOsDevice(device: Pick<DeviceInfo, 'platform' | 'target'>): boolean {
65+
return device.platform === 'ios' && device.target === 'tv';
66+
}
67+
5368
export function isPlatform(value: unknown): value is Platform {
5469
// Leaf-platform membership derived from the canonical PLATFORMS tuple (excludes the
5570
// `apple` selector, which is not a concrete device platform).
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import type { RunnerCommand } from '../../core/runner/runner-contract.ts';
2+
3+
// The tvOS Apple-OS leaf (ADR-0009). tvOS has no touch input: it is driven by the
4+
// Siri Remote's focus engine, so back/home/scroll navigate focus via XCUIRemote
5+
// hardware-button presses rather than coordinate taps or drags. This focus-only
6+
// interaction contract is per-OS by design and must NOT be flattened into a uniform
7+
// Apple tap/gesture path (perfect-shape §7; ADR-0009). The `isTvOsDevice` gate
8+
// (kernel/device.ts) selects when this leaf's behavior applies.
9+
10+
export type AppleRemoteButton = NonNullable<RunnerCommand['remoteButton']>;
11+
12+
/**
13+
* Builds the XCUIRemote `remotePress` runner command for a tvOS navigation intent.
14+
* Scroll directions map straight onto the directional remote buttons; back maps to
15+
* `menu` and home to `home`. An optional `durationMs` becomes a button hold.
16+
*/
17+
export function appleRemotePressCommand(
18+
remoteButton: AppleRemoteButton,
19+
appBundleId?: string,
20+
durationMs?: number,
21+
): RunnerCommand {
22+
return {
23+
command: 'remotePress',
24+
remoteButton,
25+
...(durationMs !== undefined ? { durationMs } : {}),
26+
...(appBundleId !== undefined ? { appBundleId } : {}),
27+
};
28+
}

‎src/platforms/ios/interactions.ts‎

Lines changed: 6 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { DeviceInfo } from '../../kernel/device.ts';
1+
import { isTvOsDevice, type DeviceInfo } from '../../kernel/device.ts';
22
import { assertScrollGestureInput, type ScrollDirection } from '../../core/scroll-gesture.ts';
33
import { normalizeScrollDurationMs, SCROLL_DURATION_MAX_MS } from '../../core/scroll-command.ts';
44
import { runIosRunnerCommand } from '../apple/core/runner/runner-client.ts';
@@ -7,6 +7,7 @@ import {
77
parseRunnerSequenceResult,
88
} from '../apple/core/runner/runner-sequence.ts';
99
import type { RunnerCommand } from '../apple/core/runner/runner-contract.ts';
10+
import { appleRemotePressCommand } from '../apple/os/tvos/remote.ts';
1011
import { runMacosDesktopScroll } from '../apple/os/macos/desktop-scroll.ts';
1112
import {
1213
normalizeAppleScrollResult,
@@ -22,7 +23,6 @@ import type {
2223
} from '../../core/interactor-types.ts';
2324

2425
export type AppleBackRunnerCommand = 'backInApp' | 'backSystem';
25-
type AppleRemoteButton = NonNullable<RunnerCommand['remoteButton']>;
2626
type RunIosRunnerCommand = typeof runIosRunnerCommand;
2727
type RunnerOpts = RunnerCallOptions;
2828

@@ -267,7 +267,8 @@ function iosTapCommand(
267267
}
268268

269269
function shouldUseSynthesizedIosGesture(device: DeviceInfo): boolean {
270-
return device.platform === 'ios' && device.target !== 'tv';
270+
// Two-finger HID synthesis is for touch-input iOS only; the tvOS leaf has no touch.
271+
return device.platform === 'ios' && !isTvOsDevice(device);
271272
}
272273

273274
function iosDragCommand(
@@ -281,7 +282,7 @@ function iosDragCommand(
281282
options: IosDragCommandOptions,
282283
): RunnerCommand {
283284
const normalizedDurationMs =
284-
device.platform === 'ios' && device.target !== 'tv'
285+
device.platform === 'ios' && !isTvOsDevice(device)
285286
? iosGestureDurationMs(durationMs, options.defaultDurationMs)
286287
: (durationMs ?? options.legacyDefaultDurationMs);
287288
return {
@@ -305,19 +306,6 @@ function iosGestureDurationMs(durationMs: number | undefined, defaultDurationMs:
305306
);
306307
}
307308

308-
export function appleRemotePressCommand(
309-
remoteButton: AppleRemoteButton,
310-
appBundleId?: string,
311-
durationMs?: number,
312-
): Parameters<RunIosRunnerCommand>[1] {
313-
return {
314-
command: 'remotePress',
315-
remoteButton,
316-
...(durationMs !== undefined ? { durationMs } : {}),
317-
...(appBundleId !== undefined ? { appBundleId } : {}),
318-
};
319-
}
320-
321309
async function runAppleScroll(
322310
runRunnerCommand: RunIosRunnerCommand,
323311
device: DeviceInfo,
@@ -330,7 +318,7 @@ async function runAppleScroll(
330318
invalidMessage: `scroll durationMs must be a non-negative integer at most ${SCROLL_DURATION_MAX_MS}`,
331319
});
332320

333-
if (device.target === 'tv') {
321+
if (isTvOsDevice(device)) {
334322
const runnerResult = await runRunnerCommand(
335323
device,
336324
appleRemotePressCommand(direction, ctx.appBundleId, options?.durationMs),

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,32 @@ import { test } from 'vitest';
22
import assert from 'node:assert/strict';
33
import {
44
isPlatform,
5+
isTvOsDevice,
56
matchesPlatformSelector,
67
PLATFORMS,
78
resolveApplePlatformName,
89
resolveAppleSimulatorSetPathForSelector,
910
resolveDevice,
1011
} from '../../kernel/device.ts';
1112
import type { DeviceInfo } from '../../kernel/device.ts';
13+
import {
14+
ANDROID_TV_DEVICE,
15+
IOS_SIMULATOR,
16+
MACOS_DEVICE,
17+
TVOS_SIMULATOR,
18+
} from '../../__tests__/test-utils/device-fixtures.ts';
1219
import { AppError } from '../../kernel/errors.ts';
1320

21+
test('isTvOsDevice selects only the Apple tvOS leaf, not any TV target', () => {
22+
assert.equal(isTvOsDevice(TVOS_SIMULATOR), true);
23+
// Touch-input iOS and macOS are Apple, but are NOT the focus-only tvOS leaf.
24+
assert.equal(isTvOsDevice(IOS_SIMULATOR), false);
25+
assert.equal(isTvOsDevice(MACOS_DEVICE), false);
26+
// Android TV shares target: 'tv' but is a DISTINCT leaf — the platform gate excludes it,
27+
// so the tvOS focus-only contract is never applied to Android TV.
28+
assert.equal(isTvOsDevice(ANDROID_TV_DEVICE), false);
29+
});
30+
1431
test('matchesPlatformSelector resolves apple selector across Apple platforms', () => {
1532
assert.equal(matchesPlatformSelector('ios', 'apple'), true);
1633
assert.equal(matchesPlatformSelector('macos', 'apple'), true);

‎src/utils/__tests__/interactors.test.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,51 @@ test('tvOS scroll sends only a remotePress command (behavior unchanged)', async
130130
]);
131131
});
132132

133+
test('tvOS back navigates focus via the remote Menu button, not a coordinate tap', async () => {
134+
const commands: RunnerCommand[] = [];
135+
mockRunIosRunnerCommand.mockImplementation(async (_device, command) => {
136+
commands.push(command);
137+
return {};
138+
});
139+
const interactor = await getInteractor(tvOsSimulator, { appBundleId: 'com.example.app' });
140+
141+
await interactor.back();
142+
143+
// tvOS is focus-only: back pops focus via the Siri Remote Menu button (XCUIRemote).
144+
assert.deepEqual(commands, [
145+
{ command: 'remotePress', remoteButton: 'menu', appBundleId: 'com.example.app' },
146+
]);
147+
});
148+
149+
test('tvOS home navigates focus via the remote Home button', async () => {
150+
const commands: RunnerCommand[] = [];
151+
mockRunIosRunnerCommand.mockImplementation(async (_device, command) => {
152+
commands.push(command);
153+
return {};
154+
});
155+
const interactor = await getInteractor(tvOsSimulator, { appBundleId: 'com.example.app' });
156+
157+
await interactor.home();
158+
159+
assert.deepEqual(commands, [
160+
{ command: 'remotePress', remoteButton: 'home', appBundleId: 'com.example.app' },
161+
]);
162+
});
163+
164+
test('iOS back keeps the in-app navigation path, not the tvOS remote', async () => {
165+
const commands: RunnerCommand[] = [];
166+
mockRunIosRunnerCommand.mockImplementation(async (_device, command) => {
167+
commands.push(command);
168+
return {};
169+
});
170+
const interactor = await getInteractor(iosSimulator, { appBundleId: 'com.example.app' });
171+
172+
await interactor.back();
173+
174+
// The per-OS gate must not flatten: touch-input iOS never uses the XCUIRemote path.
175+
assert.deepEqual(commands, [{ command: 'backInApp', appBundleId: 'com.example.app' }]);
176+
});
177+
133178
test('ios scroll rejects non-positive amount before sending any runner command', async () => {
134179
mockRunIosRunnerCommand.mockImplementation(async () => ({}));
135180
const interactor = await getInteractor(iosSimulator, { appBundleId: 'com.example.app' });

0 commit comments

Comments
 (0)