From 35f2f0f4a5eb2227b52d24af3e0a4f5e7f1a619f Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 17:14:07 -0800 Subject: [PATCH 1/5] fix(hid): route toolbar Home through SpringBoardLauncher host-rpc `home` used an unbounded `simctl launch springboard`, which is a no-op when SpringBoard is already frontmost (App Library, folders, inner pages). Prefer DeviceSession.pressHome() with a 2s timeout, then simctl as fallback. Leaving an app still uses SpringBoardLauncher (Xcode 26 drops the Indigo HID home press). When SpringBoard is already frontmost, send a short home-indicator flick instead of launch or the long swipe_home (which can open the app switcher on page 1). Create the device session if the preview has not opened one, so the first toolbar Home is native too. --- .../Sources/SimNative/HIDInjector.swift | 21 ++-- .../src/__tests__/host-rpc-home.test.ts | 110 ++++++++++++++++++ .../src/__tests__/native-hid-home.test.ts | 19 +++ packages/serve-sim/src/device-session.ts | 11 ++ packages/serve-sim/src/host-rpc.ts | 51 ++++++++ packages/serve-sim/src/middleware.ts | 8 ++ packages/serve-sim/src/native.ts | 33 +++++- 7 files changed, 244 insertions(+), 9 deletions(-) create mode 100644 packages/serve-sim/src/__tests__/host-rpc-home.test.ts create mode 100644 packages/serve-sim/src/__tests__/native-hid-home.test.ts 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..9f020ac07 --- /dev/null +++ b/packages/serve-sim/src/__tests__/host-rpc-home.test.ts @@ -0,0 +1,110 @@ +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) => 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("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..d98e3ed35 --- /dev/null +++ b/packages/serve-sim/src/__tests__/native-hid-home.test.ts @@ -0,0 +1,19 @@ +import { describe, expect, test } from "bun:test"; +import { homeButtonForFrontmost, SPRINGBOARD_BUNDLE_ID } from "../native"; + +describe("homeButtonForFrontmost", () => { + test("leaves a foreground app via the SpringBoard launch path", () => { + expect(homeButtonForFrontmost("com.apple.Preferences")).toBe("home"); + expect(homeButtonForFrontmost("com.apple.mobilesafari")).toBe("home"); + }); + + test("uses a short home-indicator flick when SpringBoard is already frontmost", () => { + expect(homeButtonForFrontmost(SPRINGBOARD_BUNDLE_ID)).toBe("flick_home"); + }); + + test("falls back to the launch path when frontmost is unknown", () => { + expect(homeButtonForFrontmost(null)).toBe("home"); + expect(homeButtonForFrontmost(undefined)).toBe("home"); + expect(homeButtonForFrontmost("")).toBe("home"); + }); +}); diff --git a/packages/serve-sim/src/device-session.ts b/packages/serve-sim/src/device-session.ts index 43cdd7bd7..003e068cd 100644 --- a/packages/serve-sim/src/device-session.ts +++ b/packages/serve-sim/src/device-session.ts @@ -431,6 +431,17 @@ 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(): Promise { + return (await this.hid.button("home")) !== false; + } + /** * Begin capture and track the screen size. Idempotent. * diff --git a/packages/serve-sim/src/host-rpc.ts b/packages/serve-sim/src/host-rpc.ts index a6dfb579c..3da19e112 100644 --- a/packages/serve-sim/src/host-rpc.ts +++ b/packages/serve-sim/src/host-rpc.ts @@ -51,6 +51,41 @@ 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) => 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) => Promise, + udid: string, + timeoutMs: number, +): Promise { + try { + return await new Promise((resolve) => { + const timer = setTimeout(() => resolve(false), timeoutMs); + pressHome(udid).then( + (ok) => { + clearTimeout(timer); + resolve(ok === true); + }, + () => { + clearTimeout(timer); + resolve(false); + }, + ); + }); + } catch { + return false; + } } export type HostRpcHandler = (payload: unknown) => Promise>; @@ -249,6 +284,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..66c5b11c3 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) => { + return getDeviceSession(udid).pressHome(); + }, }); // 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..ccd467bad 100644 --- a/packages/serve-sim/src/native.ts +++ b/packages/serve-sim/src/native.ts @@ -249,9 +249,26 @@ 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; +} + +export const SPRINGBOARD_BUNDLE_ID = "com.apple.springboard"; + +/** + * `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 use a short home-indicator flick instead of `swipe_home` (a long + * swipe can open the app switcher on page 1). + */ +export function homeButtonForFrontmost(bundleId: string | null | undefined): "home" | "flick_home" { + return bundleId === SPRINGBOARD_BUNDLE_ID ? "flick_home" : "home"; } export class NativeHid { + private readonly udid: string; + private readonly axFrontmost: (udid: string) => Promise; private readonly handle: SimHIDHandle; private readonly keys: KeySequencer; /** @@ -269,6 +286,8 @@ export class NativeHid { private duoHelperSettled = false; constructor(udid: string, deps: NativeHidDeps = {}) { + this.udid = udid; + this.axFrontmost = deps.axFrontmost ?? axFrontmostAsync; const bundled = (deps.bundledDuoHelper ?? bundledDuoHidHelperPath)(); this.handle = new (deps.SimHID ?? load().SimHID)(udid, bundled); this.keys = new KeySequencer(this.handle); @@ -328,8 +347,18 @@ 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): Promise { + const name = button === "home" ? await this.homeButtonName() : button; + return this.delivered("button", () => this.settled(this.viaDuoHelper(() => this.handle.button(name)))); + } + + private async homeButtonName(): Promise<"home" | "flick_home"> { + try { + const info = JSON.parse(await this.axFrontmost(this.udid)) as { bundleId?: string }; + return homeButtonForFrontmost(info.bundleId); + } catch { + return "home"; + } } buttonHid(page: number, usage: number, phase: ButtonPhase = "press"): Promise { From 2e1fb420d96dded57faad6a5b68782890f48fe73 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 17:24:52 -0800 Subject: [PATCH 2/5] fix(hid): gate home-indicator flick to Face ID portrait Only send flick_home when SpringBoard is frontmost on a device without a physical Home button, in portrait, and not under Device Hub shadow. Cap the frontmost probe and skip HID settle on the launch path so a cold session does not also fire simctl. --- .../src/__tests__/native-hid-home.test.ts | 182 +++++++++++++++++- .../src/client/simulator/SimulatorToolbar.tsx | 15 +- packages/serve-sim/src/device-session.ts | 16 +- packages/serve-sim/src/device.ts | 35 ++++ packages/serve-sim/src/devicekit-chrome.ts | 12 ++ packages/serve-sim/src/native.ts | 69 ++++++- 6 files changed, 302 insertions(+), 27 deletions(-) diff --git a/packages/serve-sim/src/__tests__/native-hid-home.test.ts b/packages/serve-sim/src/__tests__/native-hid-home.test.ts index d98e3ed35..b4b5054e8 100644 --- a/packages/serve-sim/src/__tests__/native-hid-home.test.ts +++ b/packages/serve-sim/src/__tests__/native-hid-home.test.ts @@ -1,19 +1,183 @@ import { describe, expect, test } from "bun:test"; -import { homeButtonForFrontmost, SPRINGBOARD_BUNDLE_ID } from "../native"; +import { existsSync } from "fs"; +import { + HOME_FRONTMOST_PROBE_TIMEOUT_MS, + NativeHid, + SPRINGBOARD_BUNDLE_ID, + homeButtonForFrontmost, + 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("com.apple.Preferences")).toBe("home"); - expect(homeButtonForFrontmost("com.apple.mobilesafari")).toBe("home"); + 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("is true for Face ID chrome and false for a physical Home button or missing chrome", () => { + 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); + expect( + deviceSupportsHomeIndicatorFlick({ + name: "unknown box", + deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.Does-Not-Exist", + }), + ).toBe(false); + }); +}); + +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("uses a short home-indicator flick when SpringBoard is already frontmost", () => { - expect(homeButtonForFrontmost(SPRINGBOARD_BUNDLE_ID)).toBe("flick_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("falls back to the launch path when frontmost is unknown", () => { - expect(homeButtonForFrontmost(null)).toBe("home"); - expect(homeButtonForFrontmost(undefined)).toBe("home"); - expect(homeButtonForFrontmost("")).toBe("home"); + 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"]); + } }); }); 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 003e068cd..771537cb1 100644 --- a/packages/serve-sim/src/device-session.ts +++ b/packages/serve-sim/src/device-session.ts @@ -33,6 +33,8 @@ import { duoHidHelperPath, 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"; @@ -416,7 +418,14 @@ 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.orientation, + isInputShadowed: () => this.deviceHubShadowed === true, + supportsHomeIndicator: () => { + const info = simulatorDeviceInfo(udid); + return info != null && deviceSupportsHomeIndicatorFlick(info); + }, + }); this.capture = dependencies?.capture ?? new NativeCapture(udid); this.duo = new DuoPreview({ createRenderer: (onFailure) => dependencies?.createDuoRenderer @@ -1407,7 +1416,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); diff --git a/packages/serve-sim/src/device.ts b/packages/serve-sim/src/device.ts index 27ff46f40..ba59f8ae6 100644 --- a/packages/serve-sim/src/device.ts +++ b/packages/serve-sim/src/device.ts @@ -59,3 +59,38 @@ 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; + +/** Name and device type for `udid` from `simctl list`, cached for the process. */ +export function simulatorDeviceInfo(udid: string): SimulatorDeviceInfo | null { + if (!simulatorDeviceInfoCache) { + simulatorDeviceInfoCache = new Map(); + try { + const output = execFileSync("xcrun", simctlArguments(["list", "devices", "-j"]), { encoding: "utf-8" }); + const data = JSON.parse(output) as { + devices: Record>; + }; + for (const devices of Object.values(data.devices)) { + for (const device of devices) { + simulatorDeviceInfoCache.set(device.udid.toUpperCase(), { + udid: device.udid, + name: device.name, + deviceTypeIdentifier: device.deviceTypeIdentifier, + }); + } + } + } catch { + // Leave the cache empty so a later call can retry after simctl recovers. + simulatorDeviceInfoCache = undefined; + return null; + } + } + return simulatorDeviceInfoCache.get(udid.toUpperCase()) ?? null; +} diff --git a/packages/serve-sim/src/devicekit-chrome.ts b/packages/serve-sim/src/devicekit-chrome.ts index c27e1352d..be3596ba7 100644 --- a/packages/serve-sim/src/devicekit-chrome.ts +++ b/packages/serve-sim/src/devicekit-chrome.ts @@ -216,6 +216,18 @@ 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). */ +export function deviceSupportsHomeIndicatorFlick(device: { + name: string; + deviceTypeIdentifier?: string; +}): boolean { + const chrome = resolveDeviceKitChrome(device); + if (!chrome) return false; + return !chrome.buttons.some((button) => button.name === "home"); +} + export function resolveDeviceKitChrome(device: { name: string; deviceTypeIdentifier?: string; diff --git a/packages/serve-sim/src/native.ts b/packages/serve-sim/src/native.ts index ccd467bad..735522591 100644 --- a/packages/serve-sim/src/native.ts +++ b/packages/serve-sim/src/native.ts @@ -251,24 +251,52 @@ export interface NativeHidDeps { 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 use a short home-indicator flick instead of `swipe_home` (a long - * swipe can open the app switcher on page 1). + * 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(bundleId: string | null | undefined): "home" | "flick_home" { - return bundleId === SPRINGBOARD_BUNDLE_ID ? "flick_home" : "home"; +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"; } 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; /** @@ -288,6 +316,9 @@ export class NativeHid { 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); @@ -348,17 +379,39 @@ export class NativeHid { } async button(button: string): Promise { - const name = button === "home" ? await this.homeButtonName() : button; - return this.delivered("button", () => this.settled(this.viaDuoHelper(() => this.handle.button(name)))); + if (button !== "home") { + return this.delivered("button", () => this.settled(this.viaDuoHelper(() => this.handle.button(button)))); + } + const name = await this.homeButtonName(); + const send = this.viaDuoHelper(() => this.handle.button(name)); + // 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", send); + return this.delivered("button", () => this.settled(send)); } private async homeButtonName(): Promise<"home" | "flick_home"> { + let bundleId: string | null = null; try { - const info = JSON.parse(await this.axFrontmost(this.udid)) as { bundleId?: string }; - return homeButtonForFrontmost(info.bundleId); + 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"; } + return homeButtonForFrontmost({ + bundleId, + supportsHomeIndicator: this.supportsHomeIndicator(), + orientation: this.getOrientation(), + inputShadowed: this.isInputShadowed(), + }); } buttonHid(page: number, usage: number, phase: ButtonPhase = "press"): Promise { From c77c0db4864a47ea1d9ecc2ec8506b0b16495f4d Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 17:30:58 -0800 Subject: [PATCH 3/5] fix(hid): do not flick Home until orientation is known A fresh session no longer treats the default "portrait" as confirmed. Unknown Device Hub shadow and foldable devices stay on the launch path. Chrome and foldable support is warmed off the Home hot path. --- .../src/__tests__/native-hid-home.test.ts | 101 +++++++++++++++++- packages/serve-sim/src/device-session.ts | 42 ++++++-- packages/serve-sim/src/device.ts | 65 +++++++---- packages/serve-sim/src/devicekit-chrome.ts | 8 +- packages/serve-sim/src/native.ts | 34 ++++-- 5 files changed, 207 insertions(+), 43 deletions(-) diff --git a/packages/serve-sim/src/__tests__/native-hid-home.test.ts b/packages/serve-sim/src/__tests__/native-hid-home.test.ts index b4b5054e8..51b2b51ec 100644 --- a/packages/serve-sim/src/__tests__/native-hid-home.test.ts +++ b/packages/serve-sim/src/__tests__/native-hid-home.test.ts @@ -5,6 +5,7 @@ import { NativeHid, SPRINGBOARD_BUNDLE_ID, homeButtonForFrontmost, + homeButtonSessionRoute, type NativeHidDeps, } from "../native"; import { deviceSupportsHomeIndicatorFlick } from "../devicekit-chrome"; @@ -68,7 +69,16 @@ describe("homeButtonForFrontmost", () => { }); describe("deviceSupportsHomeIndicatorFlick", () => { - test("is true for Face ID chrome and false for a physical Home button or missing chrome", () => { + 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({ @@ -88,12 +98,60 @@ describe("deviceSupportsHomeIndicatorFlick", () => { 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( - deviceSupportsHomeIndicatorFlick({ - name: "unknown box", - deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.Does-Not-Exist", + homeButtonForFrontmost({ + bundleId: SPRINGBOARD_BUNDLE_ID, + ...homeButtonSessionRoute({}), }), - ).toBe(false); + ).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"); }); }); @@ -180,4 +238,37 @@ describe("NativeHid.button home routing", () => { 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"]); + }); }); diff --git a/packages/serve-sim/src/device-session.ts b/packages/serve-sim/src/device-session.ts index 771537cb1..f1b541b86 100644 --- a/packages/serve-sim/src/device-session.ts +++ b/packages/serve-sim/src/device-session.ts @@ -373,6 +373,11 @@ 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 latestJpegBuffer: Buffer | null = null; private latestJpegLength = 0; @@ -419,13 +424,11 @@ export class DeviceSession { constructor(public readonly udid: string, private readonly dependencies?: DeviceSessionDependencies) { this.usesInjectedHid = dependencies?.hid != null; this.hid = dependencies?.hid ?? new NativeHid(udid, { - getOrientation: () => this.orientation, - isInputShadowed: () => this.deviceHubShadowed === true, - supportsHomeIndicator: () => { - const info = simulatorDeviceInfo(udid); - return info != null && deviceSupportsHomeIndicatorFlick(info); - }, + getOrientation: () => this.knownOrientation, + isInputShadowed: () => this.deviceHubShadowed !== false, + supportsHomeIndicator: () => this.homeIndicatorFlickSupported === true, }); + if (!this.usesInjectedHid) void this.warmHomeIndicatorSupport(); this.capture = dependencies?.capture ?? new NativeCapture(udid); this.duo = new DuoPreview({ createRenderer: (onFailure) => dependencies?.createDuoRenderer @@ -481,6 +484,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(); @@ -579,7 +583,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(); @@ -1450,7 +1457,10 @@ export class DeviceSession { // Duo physical orientation and the active panel's UI orientation // differ (the inner panel's natural axis is rotated). Let the // monitor report the guest UI; never overwrite it with view state. - if (this.duo.hinge == null) this.orientation = m.orientation; + if (this.duo.hinge == null) { + this.orientation = m.orientation; + this.knownOrientation = m.orientation; + } this.duo.animateRotation(m.orientation); this.duoMonitor?.refreshOrientation(); this.broadcastConfig(); @@ -1822,6 +1832,22 @@ export class DeviceSession { } /** Single-flight probe. Callers that already have a reading must not await this. */ + /** Resolve chrome and foldable off the Home hot path. Unknown stays false. */ + private async warmHomeIndicatorSupport(): Promise { + if (this.homeIndicatorFlickSupported != null || this.usesInjectedHid) return; + 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 { + this.homeIndicatorFlickSupported = false; + } + } + private refreshDeviceHubInput(): Promise { if (this.deviceHubProbe) return this.deviceHubProbe; const read = this.deviceHubInputReader(); diff --git a/packages/serve-sim/src/device.ts b/packages/serve-sim/src/device.ts index ba59f8ae6..905a5eca8 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 @@ -67,30 +70,48 @@ export type SimulatorDeviceInfo = { }; 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; +} -/** Name and device type for `udid` from `simctl list`, cached for the process. */ -export function simulatorDeviceInfo(udid: string): SimulatorDeviceInfo | null { - if (!simulatorDeviceInfoCache) { - simulatorDeviceInfoCache = new Map(); +async function refreshSimulatorDeviceInfo(): Promise | undefined> { + if (simulatorDeviceInfoInflight) return simulatorDeviceInfoInflight; + simulatorDeviceInfoInflight = (async () => { try { - const output = execFileSync("xcrun", simctlArguments(["list", "devices", "-j"]), { encoding: "utf-8" }); - const data = JSON.parse(output) as { - devices: Record>; - }; - for (const devices of Object.values(data.devices)) { - for (const device of devices) { - simulatorDeviceInfoCache.set(device.udid.toUpperCase(), { - udid: device.udid, - name: device.name, - deviceTypeIdentifier: device.deviceTypeIdentifier, - }); - } - } + const { stdout } = await execFileAsync("xcrun", simctlArguments(["list", "devices", "-j"]), { encoding: "utf-8" }); + simulatorDeviceInfoCache = parseSimulatorDeviceInfo(stdout); + return simulatorDeviceInfoCache; } catch { - // Leave the cache empty so a later call can retry after simctl recovers. simulatorDeviceInfoCache = undefined; - return null; + return undefined; + } finally { + simulatorDeviceInfoInflight = undefined; } - } - return simulatorDeviceInfoCache.get(udid.toUpperCase()) ?? null; + })(); + 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(); + return cache?.get(key) ?? null; } diff --git a/packages/serve-sim/src/devicekit-chrome.ts b/packages/serve-sim/src/devicekit-chrome.ts index be3596ba7..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 = { @@ -218,14 +220,15 @@ export function resolveDeviceDisplays(device: { /** 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). */ + * (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.buttons.some((button) => button.name === "home"); + return !(chrome.inputNames ?? []).includes("home") && !chrome.buttons.some((button) => button.name === "home"); } export function resolveDeviceKitChrome(device: { @@ -510,6 +513,7 @@ function resolveChromeDescriptor( slice: chrome.slice, corner, buttons, + inputNames: chrome.buttons.map((button) => button.name), }; } diff --git a/packages/serve-sim/src/native.ts b/packages/serve-sim/src/native.ts index 735522591..e5fe9a486 100644 --- a/packages/serve-sim/src/native.ts +++ b/packages/serve-sim/src/native.ts @@ -291,6 +291,25 @@ export function homeButtonForFrontmost(route: HomeButtonRoute): "home" | "flick_ 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; @@ -392,6 +411,14 @@ export class NativeHid { } 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) => { @@ -406,12 +433,7 @@ export class NativeHid { } catch { return "home"; } - return homeButtonForFrontmost({ - bundleId, - supportsHomeIndicator: this.supportsHomeIndicator(), - orientation: this.getOrientation(), - inputShadowed: this.isInputShadowed(), - }); + return homeButtonForFrontmost({ bundleId, ...gates }); } buttonHid(page: number, usage: number, phase: ButtonPhase = "press"): Promise { From dd823d6bb1d26d7dab1d2505bd7d0af17fa66708 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 17:36:27 -0800 Subject: [PATCH 4/5] fix(hid): confirm portrait from the first 0x07 on a fresh session A confirming portrait must not be dropped just because the session default already said "portrait"; otherwise Home never flicks until the device is rotated away and back. Wire NativeHid through homeButtonSessionRoute so that mapping stays in one place. --- packages/serve-sim/src/device-session.ts | 26 ++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/packages/serve-sim/src/device-session.ts b/packages/serve-sim/src/device-session.ts index f1b541b86..69047add3 100644 --- a/packages/serve-sim/src/device-session.ts +++ b/packages/serve-sim/src/device-session.ts @@ -31,6 +31,7 @@ import { axDescribeAsync, axFrontmostAsync, duoHidHelperPath, + homeButtonSessionRoute, type MjpegFrame, } from "./native"; import { deviceSupportsHomeIndicatorFlick } from "./devicekit-chrome"; @@ -424,9 +425,9 @@ export class DeviceSession { constructor(public readonly udid: string, private readonly dependencies?: DeviceSessionDependencies) { this.usesInjectedHid = dependencies?.hid != null; this.hid = dependencies?.hid ?? new NativeHid(udid, { - getOrientation: () => this.knownOrientation, - isInputShadowed: () => this.deviceHubShadowed !== false, - supportsHomeIndicator: () => this.homeIndicatorFlickSupported === true, + 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); @@ -1453,14 +1454,15 @@ 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 // monitor report the guest UI; never overwrite it with view state. - if (this.duo.hinge == null) { - this.orientation = m.orientation; - this.knownOrientation = m.orientation; - } + if (this.duo.hinge == null) this.orientation = m.orientation; this.duo.animateRotation(m.orientation); this.duoMonitor?.refreshOrientation(); this.broadcastConfig(); @@ -1831,7 +1833,14 @@ export class DeviceSession { return readDeviceHubInputShadowed; } - /** Single-flight probe. Callers that already have a reading must not await this. */ + private homeButtonRoute() { + return homeButtonSessionRoute({ + knownOrientation: this.knownOrientation, + deviceHubShadowed: this.deviceHubShadowed, + homeIndicatorFlickSupported: this.homeIndicatorFlickSupported, + }); + } + /** Resolve chrome and foldable off the Home hot path. Unknown stays false. */ private async warmHomeIndicatorSupport(): Promise { if (this.homeIndicatorFlickSupported != null || this.usesInjectedHid) return; @@ -1848,6 +1857,7 @@ export class DeviceSession { } } + /** Single-flight probe. Callers that already have a reading must not await this. */ private refreshDeviceHubInput(): Promise { if (this.deviceHubProbe) return this.deviceHubProbe; const read = this.deviceHubInputReader(); From c175c8323e77019b717d45c21812c56acb14a354 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 17:46:43 -0800 Subject: [PATCH 5/5] fix(hid): cancel a timed-out Home and retry chrome lookup Abort pressHome when the host-rpc timeout wins so a late flick cannot close an app after simctl fallback. Re-read flick gates after the frontmost probe, and treat a transient simctl failure as retryable instead of disabling the flick for the session. --- .../src/__tests__/host-rpc-home.test.ts | 16 +++++++++- .../src/__tests__/native-hid-home.test.ts | 30 +++++++++++++++++++ packages/serve-sim/src/device-session.ts | 19 +++++++++--- packages/serve-sim/src/device.ts | 3 +- packages/serve-sim/src/host-rpc.ts | 14 ++++++--- packages/serve-sim/src/middleware.ts | 4 +-- packages/serve-sim/src/native.ts | 20 ++++++++++--- 7 files changed, 90 insertions(+), 16 deletions(-) diff --git a/packages/serve-sim/src/__tests__/host-rpc-home.test.ts b/packages/serve-sim/src/__tests__/host-rpc-home.test.ts index 9f020ac07..4e317b199 100644 --- a/packages/serve-sim/src/__tests__/host-rpc-home.test.ts +++ b/packages/serve-sim/src/__tests__/host-rpc-home.test.ts @@ -9,7 +9,7 @@ const UDID = "11111111-2222-3333-4444-555555555555"; function handler(opts: { known?: boolean; - pressHome?: (udid: string) => Promise; + pressHome?: (udid: string, signal?: AbortSignal) => Promise; pressHomeTimeoutMs?: number; } = {}) { const calls: Array<[string, string[]]> = []; @@ -74,6 +74,20 @@ describe("home", () => { 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 }); diff --git a/packages/serve-sim/src/__tests__/native-hid-home.test.ts b/packages/serve-sim/src/__tests__/native-hid-home.test.ts index 51b2b51ec..18face03c 100644 --- a/packages/serve-sim/src/__tests__/native-hid-home.test.ts +++ b/packages/serve-sim/src/__tests__/native-hid-home.test.ts @@ -271,4 +271,34 @@ describe("NativeHid.button home routing", () => { 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/device-session.ts b/packages/serve-sim/src/device-session.ts index 69047add3..56d603b8e 100644 --- a/packages/serve-sim/src/device-session.ts +++ b/packages/serve-sim/src/device-session.ts @@ -379,6 +379,8 @@ export class DeviceSession { 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; @@ -451,8 +453,9 @@ export class DeviceSession { * already frontmost (App Library, folders, inner pages), uses a short * home-indicator flick because the launch is a no-op there. */ - async pressHome(): Promise { - return (await this.hid.button("home")) !== false; + async pressHome(signal?: AbortSignal): Promise { + if (this.homeIndicatorFlickSupported == null) void this.warmHomeIndicatorSupport(); + return (await this.hid.button("home", signal)) !== false; } /** @@ -1841,9 +1844,15 @@ export class DeviceSession { }); } - /** Resolve chrome and foldable off the Home hot path. Unknown stays false. */ + /** 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; @@ -1853,7 +1862,9 @@ export class DeviceSession { if (this.isStopped()) return; this.homeIndicatorFlickSupported = info != null && deviceSupportsHomeIndicatorFlick(info); } catch { - this.homeIndicatorFlickSupported = false; + if (this.homeIndicatorWarmAttempts >= DeviceSession.HOME_INDICATOR_WARM_MAX_ATTEMPTS) { + this.homeIndicatorFlickSupported = false; + } } } diff --git a/packages/serve-sim/src/device.ts b/packages/serve-sim/src/device.ts index 905a5eca8..a2ce8b1b4 100644 --- a/packages/serve-sim/src/device.ts +++ b/packages/serve-sim/src/device.ts @@ -113,5 +113,6 @@ export async function simulatorDeviceInfo(udid: string): Promise Promise; + pressHome?: (udid: string, signal?: AbortSignal) => Promise; /** Bound on `pressHome`. Default `DEFAULT_PRESS_HOME_TIMEOUT_MS`. */ pressHomeTimeoutMs?: number; } @@ -65,14 +65,19 @@ export interface HostRpcOptions { export const DEFAULT_PRESS_HOME_TIMEOUT_MS = 2_000; async function racePressHome( - pressHome: (udid: string) => Promise, + pressHome: (udid: string, signal?: AbortSignal) => Promise, udid: string, timeoutMs: number, ): Promise { + const controller = new AbortController(); try { return await new Promise((resolve) => { - const timer = setTimeout(() => resolve(false), timeoutMs); - pressHome(udid).then( + const timer = setTimeout(() => { + controller.abort(); + resolve(false); + }, timeoutMs); + timer.unref?.(); + pressHome(udid, controller.signal).then( (ok) => { clearTimeout(timer); resolve(ok === true); @@ -84,6 +89,7 @@ async function racePressHome( ); }); } catch { + controller.abort(); return false; } } diff --git a/packages/serve-sim/src/middleware.ts b/packages/serve-sim/src/middleware.ts index 66c5b11c3..e088b9f33 100644 --- a/packages/serve-sim/src/middleware.ts +++ b/packages/serve-sim/src/middleware.ts @@ -1646,8 +1646,8 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware { // 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) => { - return getDeviceSession(udid).pressHome(); + pressHome: async (udid, signal) => { + return getDeviceSession(udid).pressHome(signal); }, }); diff --git a/packages/serve-sim/src/native.ts b/packages/serve-sim/src/native.ts index e5fe9a486..7923c696a 100644 --- a/packages/serve-sim/src/native.ts +++ b/packages/serve-sim/src/native.ts @@ -397,17 +397,22 @@ export class NativeHid { return this.delivered("multiTouch", () => this.settled(() => this.handle.multiTouch(type, x1, y1, x2, y2, w, h))); } - async button(button: string): Promise { + 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", send); - return this.delivered("button", () => this.settled(send)); + if (name === "home") return this.delivered("button", guarded); + return this.delivered("button", () => this.settled(guarded)); } private async homeButtonName(): Promise<"home" | "flick_home"> { @@ -433,7 +438,14 @@ export class NativeHid { } catch { return "home"; } - return homeButtonForFrontmost({ bundleId, ...gates }); + // 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 {