diff --git a/packages/serve-sim/Sources/SimNative/HIDInjector.swift b/packages/serve-sim/Sources/SimNative/HIDInjector.swift index f69e47460..360b9ee9b 100644 --- a/packages/serve-sim/Sources/SimNative/HIDInjector.swift +++ b/packages/serve-sim/Sources/SimNative/HIDInjector.swift @@ -489,14 +489,18 @@ actor HIDInjector { case "home": // Xcode 26+ silently drops the Indigo HID home-button press, so the // press is delivered but never reaches SpringBoard. Relaunching - // SpringBoard foregrounds the home screen reliably on every Xcode - // version (it's what the buttonFunc-missing fallback always used), - // and is functionally identical to a single home press, so use it - // unconditionally rather than depending on whether the HID symbol - // resolved. + // SpringBoard leaves a foreground app on every Xcode version (it's + // what the buttonFunc-missing fallback always used). It is a no-op + // when SpringBoard is already frontmost (App Library, folders, + // inner home pages); NativeHid routes those to flick_home. await launchSpringBoard(deviceUDID: deviceUDID) return true + case "flick_home": + // Short home-indicator flick. Long swipe_home (yEnd 0.35) can open + // the app switcher when already on the first home page. + return sendSwipeHome(yEnd: 0.70) + case "swipe_home": return sendSwipeHome() @@ -661,10 +665,13 @@ actor HIDInjector { /// Synthesize a swipe-up-from-bottom gesture (Face ID "go home" gesture). /// Uses IndigoHIDEdge.bottom to flag touches as system edge gestures, /// which iOS interprets as the home indicator swipe. - private func sendSwipeHome() -> Bool { + /// + /// Default `yEnd` 0.35 is a long swipe (legacy `swipe_home`). A shorter + /// flick (`yEnd` 0.70) leaves apps, dismisses App Library and folders, and + /// returns to page 1, without opening the app switcher on page 1. + private func sendSwipeHome(yEnd: Double = 0.35) -> Bool { let xPos = 0.5 let yStart = 0.95 - let yEnd = 0.35 let steps = 10 let stepDelay: TimeInterval = 0.016 // ~16ms per step let edge = Self.edgeBottom diff --git a/packages/serve-sim/src/__tests__/host-rpc-home.test.ts b/packages/serve-sim/src/__tests__/host-rpc-home.test.ts new file mode 100644 index 000000000..4e317b199 --- /dev/null +++ b/packages/serve-sim/src/__tests__/host-rpc-home.test.ts @@ -0,0 +1,124 @@ +import { describe, expect, test } from "bun:test"; +import { + createHostRpcHandler, + DEFAULT_PRESS_HOME_TIMEOUT_MS, + type RunResult, +} from "../host-rpc"; + +const UDID = "11111111-2222-3333-4444-555555555555"; + +function handler(opts: { + known?: boolean; + pressHome?: (udid: string, signal?: AbortSignal) => Promise; + pressHomeTimeoutMs?: number; +} = {}) { + const calls: Array<[string, string[]]> = []; + const events: string[] = []; + const rpc = createHostRpcHandler({ + serveSimBin: "serve-sim", + isKnownDevice: async () => opts.known ?? true, + pressHome: opts.pressHome, + pressHomeTimeoutMs: opts.pressHomeTimeoutMs, + onCommandResult: (command) => events.push(command), + run: async (file, args): Promise => { + calls.push([file, args]); + return { stdout: args.includes("launch") ? "com.apple.springboard: 1\n" : "", stderr: "", exitCode: 0 }; + }, + }); + return { rpc, calls, events }; +} + +describe("home", () => { + test("uses the native pressHome path and does not shell out to simctl", async () => { + const pressed: string[] = []; + const { rpc, calls, events } = handler({ + pressHome: async (udid) => { + pressed.push(udid); + return true; + }, + }); + expect(await rpc({ method: "home", params: { udid: UDID } })).toEqual({ + stdout: "", + stderr: "", + exitCode: 0, + }); + expect(pressed).toEqual([UDID]); + expect(calls).toEqual([]); + expect(events).toEqual([`serve-sim button home -d ${UDID}`]); + }); + + test("falls back to simctl launch when pressHome returns false", async () => { + const { rpc, calls } = handler({ pressHome: async () => false }); + expect(await rpc({ method: "home", params: { udid: UDID } })).toMatchObject({ exitCode: 0 }); + expect(calls).toEqual([["xcrun", ["simctl", "launch", UDID, "com.apple.springboard"]]]); + }); + + test("falls back to simctl launch when pressHome throws", async () => { + const { rpc, calls } = handler({ + pressHome: async () => { + throw new Error("no session"); + }, + }); + expect(await rpc({ method: "home", params: { udid: UDID } })).toMatchObject({ exitCode: 0 }); + expect(calls).toEqual([["xcrun", ["simctl", "launch", UDID, "com.apple.springboard"]]]); + }); + + test("falls back to simctl launch when pressHome exceeds the timeout", async () => { + const { rpc, calls } = handler({ + pressHomeTimeoutMs: 30, + pressHome: () => new Promise(() => {}), + }); + const t0 = performance.now(); + expect(await rpc({ method: "home", params: { udid: UDID } })).toMatchObject({ exitCode: 0 }); + expect(performance.now() - t0).toBeLessThan(400); + expect(calls).toEqual([["xcrun", ["simctl", "launch", UDID, "com.apple.springboard"]]]); + }); + + test("aborts a timed-out pressHome so a late native press cannot still fire", async () => { + let seen: AbortSignal | undefined; + const { rpc, calls } = handler({ + pressHomeTimeoutMs: 30, + pressHome: (_udid: string, signal?: AbortSignal) => { + seen = signal; + return new Promise(() => {}); + }, + }); + expect(await rpc({ method: "home", params: { udid: UDID } })).toMatchObject({ exitCode: 0 }); + expect(seen?.aborted).toBe(true); + expect(calls).toEqual([["xcrun", ["simctl", "launch", UDID, "com.apple.springboard"]]]); + }); + + test("without pressHome, launches SpringBoard via simctl (legacy path)", async () => { + const { rpc, calls } = handler(); + expect(await rpc({ method: "home", params: { udid: UDID } })).toMatchObject({ exitCode: 0 }); + expect(calls).toEqual([["xcrun", ["simctl", "launch", UDID, "com.apple.springboard"]]]); + }); + + test("watch home still uses the Simulator.app menu, not pressHome or simctl", async () => { + let pressed = 0; + const { rpc, calls } = handler({ + pressHome: async () => { + pressed += 1; + return true; + }, + }); + const result = await rpc({ method: "home", params: { udid: UDID, watch: true } }); + expect(result.exitCode).toBe(0); + expect(calls[0]?.[0]).toBe("osascript"); + expect(calls[0]?.[1].join(" ")).toContain('menu item "Home"'); + expect(pressed).toBe(0); + }); + + test("rejects a device that isn't booted", async () => { + const { rpc, calls } = handler({ known: false, pressHome: async () => true }); + await expect(rpc({ method: "home", params: { udid: UDID } })).rejects.toThrow( + "unknown or not booted device", + ); + expect(calls).toEqual([]); + }); + + test("DEFAULT_PRESS_HOME_TIMEOUT_MS is a short bound, not the 10s/30s launcher waits", () => { + expect(DEFAULT_PRESS_HOME_TIMEOUT_MS).toBe(2_000); + expect(DEFAULT_PRESS_HOME_TIMEOUT_MS).toBeLessThan(10_000); + }); +}); diff --git a/packages/serve-sim/src/__tests__/native-hid-home.test.ts b/packages/serve-sim/src/__tests__/native-hid-home.test.ts new file mode 100644 index 000000000..18face03c --- /dev/null +++ b/packages/serve-sim/src/__tests__/native-hid-home.test.ts @@ -0,0 +1,304 @@ +import { describe, expect, test } from "bun:test"; +import { existsSync } from "fs"; +import { + HOME_FRONTMOST_PROBE_TIMEOUT_MS, + NativeHid, + SPRINGBOARD_BUNDLE_ID, + homeButtonForFrontmost, + homeButtonSessionRoute, + type NativeHidDeps, +} from "../native"; +import { deviceSupportsHomeIndicatorFlick } from "../devicekit-chrome"; + +const faceIdPortrait = { + bundleId: SPRINGBOARD_BUNDLE_ID, + supportsHomeIndicator: true, + orientation: "portrait", + inputShadowed: false, +} as const; + +function hidWith(options: { + buttons?: string[]; + axFrontmost?: (udid: string) => Promise; + getOrientation?: () => string | undefined; + supportsHomeIndicator?: () => boolean; + isInputShadowed?: () => boolean; + isFoldable?: () => Promise; +}) { + const buttons: string[] = options.buttons ?? []; + class FakeSimHID { + constructor(_udid: string, _duoHelper: string) {} + isFoldable = options.isFoldable ?? (async () => { throw new Error("not a duo"); }); + setDuoHelper = async () => {}; + button = async (name: string) => { buttons.push(name); return true; }; + touch = async () => {}; + } + const hid = new NativeHid("UDID", { + SimHID: FakeSimHID as unknown as NativeHidDeps["SimHID"], + bundledDuoHelper: () => "/tmp/serve-sim-duo-hid-test", + axFrontmost: options.axFrontmost, + getOrientation: options.getOrientation, + supportsHomeIndicator: options.supportsHomeIndicator, + isInputShadowed: options.isInputShadowed, + }); + return { hid, buttons }; +} + +describe("homeButtonForFrontmost", () => { + test("leaves a foreground app via the SpringBoard launch path", () => { + expect(homeButtonForFrontmost({ ...faceIdPortrait, bundleId: "com.apple.Preferences" })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, bundleId: "com.apple.mobilesafari" })).toBe("home"); + }); + + test("uses a short home-indicator flick only on a Face ID device in portrait with SpringBoard frontmost", () => { + expect(homeButtonForFrontmost(faceIdPortrait)).toBe("flick_home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, orientation: "portrait_upside_down" })).toBe("flick_home"); + }); + + test("keeps the launch path when chrome, orientation, or Device Hub shadow is unknown or unsafe", () => { + expect(homeButtonForFrontmost({ ...faceIdPortrait, bundleId: null })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, bundleId: undefined })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, bundleId: "" })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, supportsHomeIndicator: false })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, supportsHomeIndicator: undefined })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, orientation: "landscape_left" })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, orientation: null })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, orientation: undefined })).toBe("home"); + expect(homeButtonForFrontmost({ ...faceIdPortrait, inputShadowed: true })).toBe("home"); + }); +}); + +describe("deviceSupportsHomeIndicatorFlick", () => { + test("treats missing chrome as unknown and does not flick", () => { + expect( + deviceSupportsHomeIndicatorFlick({ + name: "unknown box", + deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.Does-Not-Exist", + }), + ).toBe(false); + }); + + test("is true for Face ID chrome and false for a physical Home button", () => { + if (!existsSync("/Library/Developer/DeviceKit/Chrome/phone.devicechrome")) return; + expect( + deviceSupportsHomeIndicatorFlick({ + name: "iPhone 17 Pro", + deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro", + }), + ).toBe(true); + expect( + deviceSupportsHomeIndicatorFlick({ + name: "iPhone SE (3rd generation)", + deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.iPhone-SE-3rd-generation", + }), + ).toBe(false); + expect( + deviceSupportsHomeIndicatorFlick({ + name: "iPad Pro (9.7-inch)", + deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.iPad-Pro--9-7-inch-", + }), + ).toBe(false); + }); +}); + +describe("homeButtonSessionRoute", () => { + test("a fresh session does not flick: orientation unset, shadow unknown, chrome unconfirmed", () => { + expect( + homeButtonForFrontmost({ + bundleId: SPRINGBOARD_BUNDLE_ID, + ...homeButtonSessionRoute({}), + }), + ).toBe("home"); + }); + + test("flicks only after orientation, shadow, and chrome are all confirmed safe", () => { + expect( + homeButtonForFrontmost({ + bundleId: SPRINGBOARD_BUNDLE_ID, + ...homeButtonSessionRoute({ + knownOrientation: "portrait", + deviceHubShadowed: false, + homeIndicatorFlickSupported: true, + }), + }), + ).toBe("flick_home"); + expect( + homeButtonForFrontmost({ + bundleId: SPRINGBOARD_BUNDLE_ID, + ...homeButtonSessionRoute({ + knownOrientation: "portrait", + deviceHubShadowed: undefined, + homeIndicatorFlickSupported: true, + }), + }), + ).toBe("home"); + expect( + homeButtonForFrontmost({ + bundleId: SPRINGBOARD_BUNDLE_ID, + ...homeButtonSessionRoute({ + knownOrientation: undefined, + deviceHubShadowed: false, + homeIndicatorFlickSupported: true, + }), + }), + ).toBe("home"); + expect( + homeButtonForFrontmost({ + bundleId: SPRINGBOARD_BUNDLE_ID, + ...homeButtonSessionRoute({ + knownOrientation: "portrait", + deviceHubShadowed: false, + homeIndicatorFlickSupported: false, + }), + }), + ).toBe("home"); + }); +}); + +describe("NativeHid.button home routing", () => { + test("sends flick_home when SpringBoard is frontmost on a Face ID device in portrait", async () => { + const { hid, buttons } = hidWith({ + axFrontmost: async () => JSON.stringify({ bundleId: SPRINGBOARD_BUNDLE_ID }), + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + isInputShadowed: () => false, + }); + expect(await hid.button("home")).toBe(true); + expect(buttons).toEqual(["flick_home"]); + }); + + test("sends the launch path for a foreground app and does not wait for HID settle", async () => { + // isFoldable resolving true/false starts the 1.5s guest-HID settle. + // Launch must not wait for it; a hang here would also trip host-rpc's 2s race. + const { hid, buttons } = hidWith({ + isFoldable: async () => false, + axFrontmost: async () => JSON.stringify({ bundleId: "com.apple.Preferences" }), + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + }); + const started = Date.now(); + expect(await hid.button("home")).toBe(true); + expect(Date.now() - started).toBeLessThan(400); + expect(buttons).toEqual(["home"]); + }); + + test("falls back to launch when the frontmost probe rejects, returns malformed JSON, or times out", async () => { + const { hid: rejected, buttons: rejectedButtons } = hidWith({ + axFrontmost: async () => { throw new Error("ax down"); }, + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + }); + expect(await rejected.button("home")).toBe(true); + expect(rejectedButtons).toEqual(["home"]); + + const { hid: malformed, buttons: malformedButtons } = hidWith({ + axFrontmost: async () => "not-json", + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + }); + expect(await malformed.button("home")).toBe(true); + expect(malformedButtons).toEqual(["home"]); + + const { hid: timedOut, buttons: timedOutButtons } = hidWith({ + axFrontmost: () => new Promise(() => {}), + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + }); + const started = Date.now(); + expect(await timedOut.button("home")).toBe(true); + const elapsed = Date.now() - started; + expect(elapsed).toBeGreaterThanOrEqual(HOME_FRONTMOST_PROBE_TIMEOUT_MS - 20); + expect(elapsed).toBeLessThan(HOME_FRONTMOST_PROBE_TIMEOUT_MS + 250); + expect(timedOutButtons).toEqual(["home"]); + }); + + test("does not probe frontmost for a non-home button", async () => { + let probed = 0; + const { hid, buttons } = hidWith({ + axFrontmost: async () => { probed += 1; return JSON.stringify({ bundleId: SPRINGBOARD_BUNDLE_ID }); }, + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + }); + expect(await hid.button("power")).toBe(true); + expect(probed).toBe(0); + expect(buttons).toEqual(["power"]); + }); + + test("keeps the launch path in landscape, without a home indicator, or when Device Hub is shadowing input", async () => { + for (const deps of [ + { getOrientation: () => "landscape_left", supportsHomeIndicator: () => true, isInputShadowed: () => false }, + { getOrientation: () => "portrait", supportsHomeIndicator: () => false, isInputShadowed: () => false }, + { getOrientation: () => "portrait", supportsHomeIndicator: () => true, isInputShadowed: () => true }, + ]) { + const { hid, buttons } = hidWith({ + axFrontmost: async () => JSON.stringify({ bundleId: SPRINGBOARD_BUNDLE_ID }), + ...deps, + }); + expect(await hid.button("home")).toBe(true); + expect(buttons).toEqual(["home"]); + } + }); + + test("does not probe frontmost when a sync gate already rules out a flick", async () => { + let probed = 0; + const probe = async () => { + probed += 1; + return JSON.stringify({ bundleId: SPRINGBOARD_BUNDLE_ID }); + }; + for (const deps of [ + { getOrientation: () => undefined, supportsHomeIndicator: () => true, isInputShadowed: () => false }, + { getOrientation: () => "portrait", supportsHomeIndicator: () => false, isInputShadowed: () => false }, + { getOrientation: () => "portrait", supportsHomeIndicator: () => true, isInputShadowed: () => true }, + ]) { + probed = 0; + const { hid, buttons } = hidWith({ axFrontmost: probe, ...deps }); + expect(await hid.button("home")).toBe(true); + expect(probed).toBe(0); + expect(buttons).toEqual(["home"]); + } + }); + + test("the flick path still waits for HID settle", async () => { + const { hid, buttons } = hidWith({ + isFoldable: async () => false, + axFrontmost: async () => JSON.stringify({ bundleId: SPRINGBOARD_BUNDLE_ID }), + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + isInputShadowed: () => false, + }); + const started = Date.now(); + expect(await hid.button("home")).toBe(true); + expect(Date.now() - started).toBeGreaterThanOrEqual(1400); + expect(buttons).toEqual(["flick_home"]); + }); + + test("re-reads flick gates after the frontmost probe", async () => { + let orientation = "portrait"; + const { hid, buttons } = hidWith({ + axFrontmost: async () => { + orientation = "landscape_left"; + return JSON.stringify({ bundleId: SPRINGBOARD_BUNDLE_ID }); + }, + getOrientation: () => orientation, + supportsHomeIndicator: () => true, + isInputShadowed: () => false, + }); + expect(await hid.button("home")).toBe(true); + expect(buttons).toEqual(["home"]); + }); + + test("does not dispatch a late home after the request is aborted", async () => { + const controller = new AbortController(); + const { hid, buttons } = hidWith({ + axFrontmost: async () => { + controller.abort(); + return JSON.stringify({ bundleId: SPRINGBOARD_BUNDLE_ID }); + }, + getOrientation: () => "portrait", + supportsHomeIndicator: () => true, + isInputShadowed: () => false, + }); + expect(await hid.button("home", controller.signal)).toBe(false); + expect(buttons).toEqual([]); + }); +}); diff --git a/packages/serve-sim/src/client/simulator/SimulatorToolbar.tsx b/packages/serve-sim/src/client/simulator/SimulatorToolbar.tsx index 5b618ab90..a6a616556 100644 --- a/packages/serve-sim/src/client/simulator/SimulatorToolbar.tsx +++ b/packages/serve-sim/src/client/simulator/SimulatorToolbar.tsx @@ -365,14 +365,13 @@ const ToolbarButton = forwardRef(function // Raises the watch window, sets Simulator as frontmost, then clicks the menu // item — this is the only mechanism that actually returns a watchOS simulator // to the watch face. -// Pick the host command that returns a device to its home screen. -// -// The HID home-button press (`serve-sim button home`) is silently dropped by -// Xcode 26+, which delivers the Indigo event but never routes it to -// SpringBoard. Relaunching SpringBoard foregrounds the home screen reliably on -// every Xcode version and is functionally identical to a single home press, so -// it's the default whenever a udid is known. Watch simulators ignore both, so -// they fall back to driving Simulator.app's Device > Home menu item. +// Last-resort shell command for a Home click that wasn't intercepted. +// The product toolbar preventDefault()s and sends host-rpc `home`, which +// uses SpringBoardLauncher (and a short home-indicator flick when +// SpringBoard is already frontmost on a Face ID device in portrait). +// This fallback still relaunches SpringBoard via simctl when a udid is +// known. Watch simulators ignore both, so they drive Simulator.app's +// Device > Home menu item. export function homeButtonCommand( deviceType: DeviceType, deviceUdid?: string | null, diff --git a/packages/serve-sim/src/device-session.ts b/packages/serve-sim/src/device-session.ts index 43cdd7bd7..56d603b8e 100644 --- a/packages/serve-sim/src/device-session.ts +++ b/packages/serve-sim/src/device-session.ts @@ -31,8 +31,11 @@ import { axDescribeAsync, axFrontmostAsync, duoHidHelperPath, + homeButtonSessionRoute, type MjpegFrame, } from "./native"; +import { deviceSupportsHomeIndicatorFlick } from "./devicekit-chrome"; +import { simulatorDeviceInfo } from "./device"; import { createReadStream } from "fs"; import type { Readable } from "stream"; import { mkdir, rm, stat } from "fs/promises"; @@ -371,6 +374,13 @@ export class DeviceSession { private width = 0; private height = 0; private orientation = "portrait"; + /** Guest UI orientation from a confirmed 0x07 or the Duo monitor. Unset + * until then — a default of "portrait" must not authorize a flick. */ + private knownOrientation?: string; + /** True only after chrome says Face ID and the device is not foldable. */ + private homeIndicatorFlickSupported?: boolean; + private homeIndicatorWarmAttempts = 0; + private static readonly HOME_INDICATOR_WARM_MAX_ATTEMPTS = 3; private latestJpegBuffer: Buffer | null = null; private latestJpegLength = 0; @@ -416,7 +426,12 @@ export class DeviceSession { constructor(public readonly udid: string, private readonly dependencies?: DeviceSessionDependencies) { this.usesInjectedHid = dependencies?.hid != null; - this.hid = dependencies?.hid ?? new NativeHid(udid); + this.hid = dependencies?.hid ?? new NativeHid(udid, { + getOrientation: () => this.homeButtonRoute().orientation ?? undefined, + isInputShadowed: () => this.homeButtonRoute().inputShadowed === true, + supportsHomeIndicator: () => this.homeButtonRoute().supportsHomeIndicator === true, + }); + if (!this.usesInjectedHid) void this.warmHomeIndicatorSupport(); this.capture = dependencies?.capture ?? new NativeCapture(udid); this.duo = new DuoPreview({ createRenderer: (onFailure) => dependencies?.createDuoRenderer @@ -431,6 +446,18 @@ export class DeviceSession { }); } + /** + * Home button: the same path as `serve-sim button home`. Leaves a + * foreground app via SpringBoardLauncher (#192 direct launch, #208 + * timeout, then the launcher's simctl fallback). When SpringBoard is + * already frontmost (App Library, folders, inner pages), uses a short + * home-indicator flick because the launch is a no-op there. + */ + async pressHome(signal?: AbortSignal): Promise { + if (this.homeIndicatorFlickSupported == null) void this.warmHomeIndicatorSupport(); + return (await this.hid.button("home", signal)) !== false; + } + /** * Begin capture and track the screen size. Idempotent. * @@ -461,6 +488,7 @@ export class DeviceSession { this.phase = "running"; // Do not await: a wedged notifyutil must not delay the first stream frame. void this.refreshDeviceHubInput(); + void this.warmHomeIndicatorSupport(); const bufferDefault = this.dependencies?.rollingBuffer !== undefined ? this.dependencies.rollingBuffer : parseRollingBufferEnv(); @@ -559,7 +587,10 @@ export class DeviceSession { this.followedCover = panel === "cover"; } const orientation = state.orientations[panel]; - if (orientation) this.orientation = orientation; + if (orientation) { + this.orientation = orientation; + this.knownOrientation = orientation; + } this.duo.setPanel(panel); this.broadcastConfig(); this.duo.requestFrame(); @@ -1396,7 +1427,10 @@ export class DeviceSession { } // SpringBoardLauncher home still reaches the guest when Device Hub // has disconnected legacy mouse/keyboard HID, so it is recorded even - // while other buttons are refused. + // while other buttons are refused. When SpringBoard is frontmost, + // NativeHid stays on the launch path if input is shadowed (a flick + // would be dropped) rather than acknowledging a touch that was not + // delivered. if (m.button !== "home" && await this.legacyInputShadowed()) return shadowedInputResult(this.udid); this.recordHidEvent(tag, m); return this.hid.button(m.button); @@ -1423,6 +1457,10 @@ export class DeviceSession { const value = ORIENTATION_BY_NAME[m.orientation]; if (value != null && await this.hid.orientation(value)) { this.recordHidEvent(tag, m); + // Confirm orientation even when it matches the default "portrait" + // so a fresh session can flick. Do not overwrite a Duo monitor + // reading with view state. + if (this.duo.hinge == null) this.knownOrientation = m.orientation; if (m.orientation !== this.orientation || m.orientation !== this.duo.viewOrientationName) { // Duo physical orientation and the active panel's UI orientation // differ (the inner panel's natural axis is rotated). Let the @@ -1798,6 +1836,38 @@ export class DeviceSession { return readDeviceHubInputShadowed; } + private homeButtonRoute() { + return homeButtonSessionRoute({ + knownOrientation: this.knownOrientation, + deviceHubShadowed: this.deviceHubShadowed, + homeIndicatorFlickSupported: this.homeIndicatorFlickSupported, + }); + } + + /** Resolve chrome and foldable off the Home hot path. A transient lookup + * failure leaves the flag unset so a later warm can retry, up to a bound. */ + private async warmHomeIndicatorSupport(): Promise { + if (this.homeIndicatorFlickSupported != null || this.usesInjectedHid) return; + if (this.homeIndicatorWarmAttempts >= DeviceSession.HOME_INDICATOR_WARM_MAX_ATTEMPTS) { + this.homeIndicatorFlickSupported = false; + return; + } + this.homeIndicatorWarmAttempts += 1; + try { + if (await this.hid.isFoldable?.()) { + this.homeIndicatorFlickSupported = false; + return; + } + const info = await simulatorDeviceInfo(this.udid); + if (this.isStopped()) return; + this.homeIndicatorFlickSupported = info != null && deviceSupportsHomeIndicatorFlick(info); + } catch { + if (this.homeIndicatorWarmAttempts >= DeviceSession.HOME_INDICATOR_WARM_MAX_ATTEMPTS) { + this.homeIndicatorFlickSupported = false; + } + } + } + /** Single-flight probe. Callers that already have a reading must not await this. */ private refreshDeviceHubInput(): Promise { if (this.deviceHubProbe) return this.deviceHubProbe; diff --git a/packages/serve-sim/src/device.ts b/packages/serve-sim/src/device.ts index 27ff46f40..a2ce8b1b4 100644 --- a/packages/serve-sim/src/device.ts +++ b/packages/serve-sim/src/device.ts @@ -1,6 +1,9 @@ -import { execFileSync } from "child_process"; +import { execFile, execFileSync } from "child_process"; +import { promisify } from "util"; import { simctlArguments } from "./simctl"; +const execFileAsync = promisify(execFile); + /** * UDID of a booted simulator, or null if none is booted. Prefers an iOS device * — a machine may also have a booted watchOS/tvOS sim, which `serve-sim`'s @@ -59,3 +62,57 @@ export function resolveDevice(nameOrUDID: string): string { console.error(`Could not resolve device: ${nameOrUDID}`); process.exit(1); } + +export type SimulatorDeviceInfo = { + udid: string; + name: string; + deviceTypeIdentifier?: string; +}; + +let simulatorDeviceInfoCache: Map | undefined; +let simulatorDeviceInfoInflight: Promise | undefined> | undefined; + +function parseSimulatorDeviceInfo(output: string): Map { + const data = JSON.parse(output) as { + devices: Record>; + }; + const cache = new Map(); + for (const devices of Object.values(data.devices)) { + for (const device of devices) { + cache.set(device.udid.toUpperCase(), { + udid: device.udid, + name: device.name, + deviceTypeIdentifier: device.deviceTypeIdentifier, + }); + } + } + return cache; +} + +async function refreshSimulatorDeviceInfo(): Promise | undefined> { + if (simulatorDeviceInfoInflight) return simulatorDeviceInfoInflight; + simulatorDeviceInfoInflight = (async () => { + try { + const { stdout } = await execFileAsync("xcrun", simctlArguments(["list", "devices", "-j"]), { encoding: "utf-8" }); + simulatorDeviceInfoCache = parseSimulatorDeviceInfo(stdout); + return simulatorDeviceInfoCache; + } catch { + simulatorDeviceInfoCache = undefined; + return undefined; + } finally { + simulatorDeviceInfoInflight = undefined; + } + })(); + return simulatorDeviceInfoInflight; +} + +/** Name and device type for `udid` from `simctl list`. Refreshes on a miss so a + * device created after the first lookup can still resolve. */ +export async function simulatorDeviceInfo(udid: string): Promise { + const key = udid.toUpperCase(); + const hit = simulatorDeviceInfoCache?.get(key); + if (hit) return hit; + const cache = await refreshSimulatorDeviceInfo(); + if (!cache) throw new Error("simctl list devices failed"); + return cache.get(key) ?? null; +} diff --git a/packages/serve-sim/src/devicekit-chrome.ts b/packages/serve-sim/src/devicekit-chrome.ts index c27e1352d..025c8bd87 100644 --- a/packages/serve-sim/src/devicekit-chrome.ts +++ b/packages/serve-sim/src/devicekit-chrome.ts @@ -87,6 +87,8 @@ export type DeviceKitChromeDescriptor = { slice: DeviceKitChromeSlice | null; corner: Size | null; buttons: DeviceKitChromeButton[]; + /** Raw chrome.json input names, including buttons dropped for a missing PDF. */ + inputNames?: string[]; }; export type DeviceKitChromeButton = { @@ -216,6 +218,19 @@ export function resolveDeviceDisplays(device: { return resolved; } +/** Face ID / home-indicator devices have chrome with no physical Home button. + * Missing chrome is treated as unknown: do not send a bottom-edge flick + * (on a home-button device that opens Control Center). Uses raw input names + * so a missing Home-button PDF cannot fail open to a flick. */ +export function deviceSupportsHomeIndicatorFlick(device: { + name: string; + deviceTypeIdentifier?: string; +}): boolean { + const chrome = resolveDeviceKitChrome(device); + if (!chrome) return false; + return !(chrome.inputNames ?? []).includes("home") && !chrome.buttons.some((button) => button.name === "home"); +} + export function resolveDeviceKitChrome(device: { name: string; deviceTypeIdentifier?: string; @@ -498,6 +513,7 @@ function resolveChromeDescriptor( slice: chrome.slice, corner, buttons, + inputNames: chrome.buttons.map((button) => button.name), }; } diff --git a/packages/serve-sim/src/host-rpc.ts b/packages/serve-sim/src/host-rpc.ts index a6dfb579c..071c2c767 100644 --- a/packages/serve-sim/src/host-rpc.ts +++ b/packages/serve-sim/src/host-rpc.ts @@ -51,6 +51,47 @@ export interface HostRpcOptions { * Required for `installApp` and for staging `serve-sim-install-*` uploads. */ allowExec?: boolean; + /** + * Preferred Home path: the in-process HID / SpringBoardLauncher used by + * `serve-sim button home`. When it returns false, throws, or exceeds + * `pressHomeTimeoutMs`, `home` falls back to `simctl launch springboard`. + */ + pressHome?: (udid: string, signal?: AbortSignal) => Promise; + /** Bound on `pressHome`. Default `DEFAULT_PRESS_HOME_TIMEOUT_MS`. */ + pressHomeTimeoutMs?: number; +} + +/** Cap on the native Home path so a stuck launch cannot hang the toolbar. */ +export const DEFAULT_PRESS_HOME_TIMEOUT_MS = 2_000; + +async function racePressHome( + pressHome: (udid: string, signal?: AbortSignal) => Promise, + udid: string, + timeoutMs: number, +): Promise { + const controller = new AbortController(); + try { + return await new Promise((resolve) => { + const timer = setTimeout(() => { + controller.abort(); + resolve(false); + }, timeoutMs); + timer.unref?.(); + pressHome(udid, controller.signal).then( + (ok) => { + clearTimeout(timer); + resolve(ok === true); + }, + () => { + clearTimeout(timer); + resolve(false); + }, + ); + }); + } catch { + controller.abort(); + return false; + } } export type HostRpcHandler = (payload: unknown) => Promise>; @@ -249,6 +290,22 @@ export function createHostRpcHandler(opts: HostRpcOptions): HostRpcHandler { const watch = p.watch === true; await requireDevice(udid); if (watch) return { ...(await run("osascript", WATCH_HOME_SCRIPT.flatMap((line) => ["-e", line]))) }; + if (opts.pressHome) { + const delivered = await racePressHome( + opts.pressHome, + udid, + opts.pressHomeTimeoutMs ?? DEFAULT_PRESS_HOME_TIMEOUT_MS, + ); + if (delivered) { + const result: RunResult = { stdout: "", stderr: "", exitCode: 0 }; + try { + opts.onCommandResult?.(`serve-sim button home -d ${udid}`, result); + } catch { + // Diagnostic side-channel only. + } + return { ...result }; + } + } return { ...(await run("xcrun", simctlArguments(["launch", udid, "com.apple.springboard"]))) }; }, diff --git a/packages/serve-sim/src/middleware.ts b/packages/serve-sim/src/middleware.ts index 447686b29..e088b9f33 100644 --- a/packages/serve-sim/src/middleware.ts +++ b/packages/serve-sim/src/middleware.ts @@ -1641,6 +1641,14 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware { allowExec, isKnownDevice: options?.isKnownDevice ?? (async (udid) => (await getBootedUdids())?.has(udid) ?? false), onCommandResult: (command, result) => recordCommandEvent(command, result), + // Prefer the in-process HID / SpringBoardLauncher path (same as + // `serve-sim button home`). Create the device session if the preview + // has not opened one yet — otherwise the first toolbar Home falls back + // to `simctl launch springboard`. If the press fails or times out, + // host-rpc still falls back to simctl. + pressHome: async (udid, signal) => { + return getDeviceSession(udid).pressHome(signal); + }, }); // Unicode text → guest pasteboard via CoreDevice, verified by readback. diff --git a/packages/serve-sim/src/native.ts b/packages/serve-sim/src/native.ts index 922de9954..7923c696a 100644 --- a/packages/serve-sim/src/native.ts +++ b/packages/serve-sim/src/native.ts @@ -249,9 +249,73 @@ export interface NativeHidDeps { bundledDuoHelper?: () => string; /** The launchable helper; may run `codesign`, so it is only called for a Duo. */ duoHelper?: () => string; + /** Frontmost-app probe; defaults to `axFrontmostAsync`. */ + axFrontmost?: (udid: string) => Promise; + /** Guest UI orientation name (`portrait`, `landscape_left`, …). */ + getOrientation?: () => string | undefined; + /** True only for Face ID / home-indicator devices with known chrome. */ + supportsHomeIndicator?: () => boolean; + /** Last known Device Hub legacy-input shadow flag. */ + isInputShadowed?: () => boolean; +} + +export const SPRINGBOARD_BUNDLE_ID = "com.apple.springboard"; + +/** Bound on the frontmost probe that chooses launch vs flick. */ +export const HOME_FRONTMOST_PROBE_TIMEOUT_MS = 400; + +const PORTRAIT_ORIENTATIONS = new Set(["portrait", "portrait_upside_down"]); + +export type HomeButtonRoute = { + bundleId?: string | null; + supportsHomeIndicator?: boolean; + orientation?: string | null; + inputShadowed?: boolean; +}; + +/** + * `hid.button("home")` launches SpringBoard to leave a foreground app (the + * Indigo HID home press is dropped on Xcode 26+). That launch is a no-op when + * SpringBoard is already frontmost, so App Library, folders, and inner home + * pages on Face ID devices in portrait use a short home-indicator flick + * instead of `swipe_home` (a long swipe can open the app switcher on page 1). + * Home-button devices, landscape, Device Hub shadow, and an unknown + * frontmost/orientation all stay on the launch path: a bottom-edge swipe on + * those surfaces can open Control Center or miss the home indicator. + */ +export function homeButtonForFrontmost(route: HomeButtonRoute): "home" | "flick_home" { + if (route.bundleId !== SPRINGBOARD_BUNDLE_ID) return "home"; + if (route.inputShadowed) return "home"; + if (route.supportsHomeIndicator !== true) return "home"; + if (route.orientation == null || !PORTRAIT_ORIENTATIONS.has(route.orientation)) return "home"; + return "flick_home"; +} + +/** Session fields as NativeHid should see them. Unknown orientation, an + * unsettled Device Hub probe (`undefined`), or an unconfirmed chrome/ + * foldable flag must not flick. */ +export function homeButtonSessionRoute(state: { + knownOrientation?: string; + deviceHubShadowed?: boolean; + homeIndicatorFlickSupported?: boolean; +}): Pick { + return { + supportsHomeIndicator: state.homeIndicatorFlickSupported === true, + orientation: state.knownOrientation, + inputShadowed: state.deviceHubShadowed !== false, + }; +} + +function canFlickHomeBeforeFrontmostProbe(route: Pick): boolean { + return homeButtonForFrontmost({ ...route, bundleId: SPRINGBOARD_BUNDLE_ID }) === "flick_home"; } export class NativeHid { + private readonly udid: string; + private readonly axFrontmost: (udid: string) => Promise; + private readonly getOrientation: () => string | undefined; + private readonly supportsHomeIndicator: () => boolean; + private readonly isInputShadowed: () => boolean; private readonly handle: SimHIDHandle; private readonly keys: KeySequencer; /** @@ -269,6 +333,11 @@ export class NativeHid { private duoHelperSettled = false; constructor(udid: string, deps: NativeHidDeps = {}) { + this.udid = udid; + this.axFrontmost = deps.axFrontmost ?? axFrontmostAsync; + this.getOrientation = deps.getOrientation ?? (() => undefined); + this.supportsHomeIndicator = deps.supportsHomeIndicator ?? (() => false); + this.isInputShadowed = deps.isInputShadowed ?? (() => false); const bundled = (deps.bundledDuoHelper ?? bundledDuoHidHelperPath)(); this.handle = new (deps.SimHID ?? load().SimHID)(udid, bundled); this.keys = new KeySequencer(this.handle); @@ -328,8 +397,55 @@ export class NativeHid { return this.delivered("multiTouch", () => this.settled(() => this.handle.multiTouch(type, x1, y1, x2, y2, w, h))); } - button(button: string): Promise { - return this.delivered("button", () => this.settled(this.viaDuoHelper(() => this.handle.button(button)))); + async button(button: string, signal?: AbortSignal): Promise { + if (button !== "home") { + return this.delivered("button", () => this.settled(this.viaDuoHelper(() => this.handle.button(button)))); + } + const name = await this.homeButtonName(); + if (signal?.aborted) return false; + const send = this.viaDuoHelper(() => this.handle.button(name)); + const guarded = () => { + if (signal?.aborted) return Promise.resolve(false); + return send(); + }; + // SpringBoardLauncher does not use the HID client, so a cold session + // must not wait out GUEST_HID_SETTLE_MS and then trip the host-rpc + // timeout (which would also fire a late flick after simctl fallback). + if (name === "home") return this.delivered("button", guarded); + return this.delivered("button", () => this.settled(guarded)); + } + + private async homeButtonName(): Promise<"home" | "flick_home"> { + const gates = { + supportsHomeIndicator: this.supportsHomeIndicator(), + orientation: this.getOrientation(), + inputShadowed: this.isInputShadowed(), + }; + // Sync gates already rule out a flick: skip the AX probe (up to 400 ms) + // on home-button devices, landscape, unknown orientation, and shadow. + if (!canFlickHomeBeforeFrontmostProbe(gates)) return "home"; + let bundleId: string | null = null; + try { + const raw = await new Promise((resolve, reject) => { + const timer = setTimeout(() => reject(new Error("axFrontmost timeout")), HOME_FRONTMOST_PROBE_TIMEOUT_MS); + timer.unref?.(); + this.axFrontmost(this.udid).then( + (value) => { clearTimeout(timer); resolve(value); }, + (error) => { clearTimeout(timer); reject(error); }, + ); + }); + bundleId = (JSON.parse(raw) as { bundleId?: string }).bundleId ?? null; + } catch { + return "home"; + } + // Re-read gates after the probe: a rotation to landscape while we waited + // must not use the pre-probe portrait snapshot to send flick_home. + return homeButtonForFrontmost({ + bundleId, + supportsHomeIndicator: this.supportsHomeIndicator(), + orientation: this.getOrientation(), + inputShadowed: this.isInputShadowed(), + }); } buttonHid(page: number, usage: number, phase: ButtonPhase = "press"): Promise {