@tapflowio/ios-agent 0.29.0 → 0.31.0

package/dist/FoldableInput.d.ts

@@ -0,0 +1,58 @@
+import { type InputChannel } from './InputChannel.js';
+import type { GuestHelper } from './GuestHelper.js';
+/**
+ * A gesture that starts within this fraction of any screen edge carries `FromEdgeTip`, which is what makes
+ * SpringBoard treat a swipe as a system gesture (home, app switcher). Measured on the Duo's cover: a home
+ * flick works from 7% of the bottom edge and not from 12%, because the system checks the start point
+ * itself — so the flag on a touch it does not consider an edge changes nothing, and a tap that carries it
+ * stays a tap. The threshold can therefore be generous. It is the same for all four edges, which also makes
+ * it independent of how the panel's UI is rotated inside its buffer.
+ */
+export declare const EDGE_FRACTION = 0.08;
+export interface FoldableInputDeps {
+    /** The device's guest helper, owned by IOSAgent outside `DeviceState`, or null if there is none. */
+    guest: () => GuestHelper | null;
+    /** The display UUID of the panel the device is showing, or null when it is not known yet. */
+    litScreen: () => string | null;
+    minContactMs?: number;
+}
+/**
+ * `InputChannel` for a device with more than one integrated panel, through `guest-helper` inside the
+ * simulator. Coordinates arrive normalized to the lit panel's framebuffer — the same space TouchHelper
+ * gets — and go to that panel's virtual touchscreen as they are: measured on the unfolded panel, whose UI
+ * is turned inside a portrait buffer, buffer coordinates land where they point.
+ */
+export declare class FoldableInput implements InputChannel {
+    private readonly deps;
+    private gesture;
+    private touchStartedAt;
+    private stopped;
+    private heldEnd;
+    constructor(deps: FoldableInputDeps);
+    start(): void;
+    stop(): void;
+    inputState(): 'ready' | 'starting' | 'unavailable';
+    ownsGesture(): boolean;
+    touchStart(x: number, y: number): boolean;
+    touchMove(x: number, y: number): boolean;
+    touchEnd(): boolean;
+    /** TouchHelper's minimum contact, for the same reason (a client sends down and up back to back). */
+    touchEndAfterMinContact(): Promise<boolean>;
+    pinchStart(x1: number, y1: number, x2: number, y2: number): boolean;
+    pinchMove(x1: number, y1: number, x2: number, y2: number): boolean;
+    pinchEnd(): boolean;
+    sendKey(usage: number, modifiers?: number): boolean;
+    pressButton(usagePage: number, usage: number): boolean;
+    pressButtonDown(usagePage: number, usage: number): boolean;
+    pressButtonUp(usagePage: number, usage: number): boolean;
+    pressLegacyButton(code: number): boolean;
+    /** The panel a new gesture goes to, fixed for the gesture: a fold mid-drag finishes the drag where it began. */
+    private open;
+    /**
+     * A key or button, acked on the write like TouchHelper's: the helper plays it and answers later, and
+     * waiting on that would change what an ack means. A refusal it reports afterwards is logged.
+     */
+    private fire;
+    private releaseHeldEnd;
+}
+//# sourceMappingURL=FoldableInput.d.ts.map

package/dist/FoldableInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoldableInput.d.ts","sourceRoot":"","sources":["../src/FoldableInput.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAInD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,OAAO,CAAA;AAiBjC,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,KAAK,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;IAC/B,6FAA6F;IAC7F,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,YAAY;IAMpC,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAA0F;gBAE5E,IAAI,EAAE,iBAAiB;IAEpD,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI;IAMZ,UAAU,IAAI,OAAO,GAAG,UAAU,GAAG,aAAa;IAQlD,WAAW,IAAI,OAAO;IAItB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAOzC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAOxC,QAAQ,IAAI,OAAO;IAOnB,oGAAoG;IACpG,uBAAuB,IAAI,OAAO,CAAC,OAAO,CAAC;IAa3C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAOnE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAOlE,QAAQ,IAAI,OAAO;IAQnB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAI,GAAG,OAAO;IAO9C,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAItD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAI1D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAIxD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKxC,gHAAgH;IAChH,OAAO,CAAC,IAAI;IASZ;;;OAGG;IACH,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,cAAc;CAOvB"}

package/dist/FoldableInput.js

@@ -0,0 +1,166 @@
+import { createLogger } from '@tapflowio/agent-core';
+import { MIN_CONTACT_MS } from './InputChannel.js';
+const logger = createLogger('ios-agent:foldable-input');
+/**
+ * A gesture that starts within this fraction of any screen edge carries `FromEdgeTip`, which is what makes
+ * SpringBoard treat a swipe as a system gesture (home, app switcher). Measured on the Duo's cover: a home
+ * flick works from 7% of the bottom edge and not from 12%, because the system checks the start point
+ * itself — so the flag on a touch it does not consider an edge changes nothing, and a tap that carries it
+ * stays a tap. The threshold can therefore be generous. It is the same for all four edges, which also makes
+ * it independent of how the panel's UI is rotated inside its buffer.
+ */
+export const EDGE_FRACTION = 0.08;
+// The keyboard page's modifier usages, in the order the HID modifier bitmap numbers them.
+const MODIFIER_USAGES = [0xe0, 0xe1, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7]; // LCtrl LShift LAlt LMeta RCtrl RShift RAlt RMeta
+const KEYBOARD_PAGE = 0x07;
+const KEY_HOLD_MS = 100; // a keyboard key: the same as a tap's contact, which iOS reads as a press
+const BUTTON_HOLD_MS = 250; // a hardware button: DeviceHub holds its buttons a quarter second
+// Measured on the Duo: consumer-page Menu goes home, AC Home (0x223) does nothing.
+const HOME = [0x0c, 0x40];
+const POWER = [0x0c, 0x30];
+/**
+ * `InputChannel` for a device with more than one integrated panel, through `guest-helper` inside the
+ * simulator. Coordinates arrive normalized to the lit panel's framebuffer — the same space TouchHelper
+ * gets — and go to that panel's virtual touchscreen as they are: measured on the unfolded panel, whose UI
+ * is turned inside a portrait buffer, buffer coordinates land where they point.
+ */
+export class FoldableInput {
+    deps;
+    gesture = null;
+    touchStartedAt = 0;
+    stopped = false;
+    heldEnd = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    start() {
+        this.stopped = false;
+    }
+    stop() {
+        this.releaseHeldEnd(false);
+        this.stopped = true;
+        this.gesture = null;
+    }
+    inputState() {
+        if (this.stopped)
+            return 'unavailable';
+        const state = this.deps.guest()?.inputState() ?? 'unavailable';
+        // Ready to write, but not yet told which panel is lit (the first devicectl reading after a boot or an
+        // agent restart): a caller should wait a moment, which is what `starting` tells it.
+        return state === 'ready' && this.deps.litScreen() === null ? 'starting' : state;
+    }
+    ownsGesture() {
+        return this.gesture !== null && (this.deps.guest()?.ownsGesture() ?? false);
+    }
+    touchStart(x, y) {
+        if (this.heldEnd)
+            this.releaseHeldEnd(this.touchEnd());
+        const opened = this.open([x, y], nearEdge(x, y));
+        this.touchStartedAt = Date.now();
+        return opened !== null && this.deps.guest().touch(opened.screen, 'd', x, y, opened.edge);
+    }
+    touchMove(x, y) {
+        const g = this.gesture;
+        if (!g)
+            return false;
+        g.points = [x, y];
+        return this.deps.guest()?.touch(g.screen, 'm', x, y, g.edge) ?? false;
+    }
+    touchEnd() {
+        const g = this.gesture;
+        if (!g)
+            return false;
+        this.gesture = null;
+        return this.deps.guest()?.touch(g.screen, 'u', g.points[0], g.points[1], g.edge) ?? false;
+    }
+    /** TouchHelper's minimum contact, for the same reason (a client sends down and up back to back). */
+    touchEndAfterMinContact() {
+        const wait = this.touchStartedAt + (this.deps.minContactMs ?? MIN_CONTACT_MS) - Date.now();
+        if (wait <= 0 || this.stopped)
+            return Promise.resolve(this.touchEnd());
+        if (this.heldEnd)
+            this.releaseHeldEnd(this.touchEnd());
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.heldEnd = null;
+                resolve(this.touchEnd());
+            }, wait);
+            this.heldEnd = { timer, resolve };
+        });
+    }
+    pinchStart(x1, y1, x2, y2) {
+        if (this.heldEnd)
+            this.releaseHeldEnd(this.touchEnd());
+        // The pinch command carries no edge flag: a two-finger touch is not a system swipe.
+        const opened = this.open([x1, y1, x2, y2], false);
+        return opened !== null && this.deps.guest().pinch(opened.screen, 'd', x1, y1, x2, y2);
+    }
+    pinchMove(x1, y1, x2, y2) {
+        const g = this.gesture;
+        if (!g)
+            return false;
+        g.points = [x1, y1, x2, y2];
+        return this.deps.guest()?.pinch(g.screen, 'm', x1, y1, x2, y2) ?? false;
+    }
+    pinchEnd() {
+        const g = this.gesture;
+        if (!g)
+            return false;
+        this.gesture = null;
+        const [x1, y1, x2, y2] = g.points;
+        return this.deps.guest()?.pinch(g.screen, 'u', x1, y1, x2, y2) ?? false;
+    }
+    sendKey(usage, modifiers = 0) {
+        const mods = MODIFIER_USAGES
+            .filter((_, bit) => modifiers & (1 << bit))
+            .map((u) => [KEYBOARD_PAGE, u]);
+        return this.fire((g) => g.key(KEYBOARD_PAGE, usage, KEY_HOLD_MS, mods), 'key');
+    }
+    pressButton(usagePage, usage) {
+        return this.fire((g) => g.key(usagePage, usage, BUTTON_HOLD_MS), 'button');
+    }
+    pressButtonDown(usagePage, usage) {
+        return this.fire((g) => g.keyDown(usagePage, usage), 'button down');
+    }
+    pressButtonUp(usagePage, usage) {
+        return this.fire((g) => g.keyUp(usagePage, usage), 'button up');
+    }
+    pressLegacyButton(code) {
+        const [page, usage] = code === 0 ? HOME : POWER;
+        return this.fire((g) => g.key(page, usage, BUTTON_HOLD_MS), code === 0 ? 'home' : 'lock');
+    }
+    /** The panel a new gesture goes to, fixed for the gesture: a fold mid-drag finishes the drag where it began. */
+    open(points, edge) {
+        this.gesture = null;
+        const guest = this.deps.guest();
+        const screen = this.deps.litScreen();
+        if (this.stopped || !guest || guest.inputState() !== 'ready' || !screen)
+            return null;
+        this.gesture = { screen, edge, points };
+        return this.gesture;
+    }
+    /**
+     * A key or button, acked on the write like TouchHelper's: the helper plays it and answers later, and
+     * waiting on that would change what an ack means. A refusal it reports afterwards is logged.
+     */
+    fire(send, what) {
+        const guest = this.deps.guest();
+        if (this.stopped || !guest || guest.inputState() !== 'ready')
+            return false;
+        void send(guest).then((ok) => { if (!ok)
+            logger.warn(`guest-helper did not take the ${what}`); });
+        return true;
+    }
+    releaseHeldEnd(sent) {
+        const held = this.heldEnd;
+        if (!held)
+            return;
+        this.heldEnd = null;
+        clearTimeout(held.timer);
+        held.resolve(sent);
+    }
+}
+function nearEdge(x, y) {
+    return Math.min(x, 1 - x, y, 1 - y) < EDGE_FRACTION;
+}
+//# sourceMappingURL=FoldableInput.js.map

package/dist/FoldableInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoldableInput.js","sourceRoot":"","sources":["../src/FoldableInput.ts"],"names":[],"mappings":"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"}

package/dist/GuestHelper.d.ts

@@ -0,0 +1,109 @@
+import { type ChildProcess } from 'child_process';
+export declare const GUEST_HELPER_BINARY: string;
+export type TouchPhase = 'd' | 'm' | 'u';
+/** DeviceHub's own orientation labels. On the unfolded panel `landscape-left` shows the UI upright and
+ *  `pud` shows it landscape with its bottom at the buffer's left edge (measured) — they are not the
+ *  public names' meaning, which is why nothing outside the agent should pick one. */
+export type GuestOrientation = 'portrait' | 'pud' | 'landscape-left' | 'landscape-right';
+/** The process-level operations, injectable for tests — the same seam `XCUITreeReader` uses. */
+export interface GuestHelperNative {
+    spawn(udid: string, args: string[]): ChildProcess;
+    /** Guest helpers for this udid still running from an earlier agent or an earlier spawn. */
+    findOrphans(udid: string): Promise<number[]>;
+    killPid(pid: number, signal: NodeJS.Signals): void;
+    /**
+     * Why a multi-panel device cannot be used on this Mac before anything is booted, or null if it can: the
+     * helper binary is missing, or there is no devicectl to say which panel is lit. Asked at connect, so such a
+     * device is left out of the list rather than offered and refused after a 3 GB boot.
+     */
+    unavailableReason(): Promise<string | null>;
+}
+export declare const defaultGuestHelperNative: GuestHelperNative;
+export interface GuestHelperOptions {
+    /** Called when the helper stops serving this device: for good (the runtime refused it — `fatal` — or it
+     *  could not be exec'd), or until the respawn window clears. The owner hides posture. */
+    onUnavailable?: (reason: string) => void;
+    /** Called when a helper is ready again after `onUnavailable` — the owner shows posture again. */
+    onAvailable?: () => void;
+}
+/**
+ * The host side of `guest-helper`: one per multi-panel device, resident for the device's life.
+ *
+ * Its lifecycle follows TouchHelper's rules — readiness gates writes, a gesture belongs to the process
+ * that took its opening frame, deaths are replaced eagerly within a rolling budget — with three
+ * differences the guest process forces:
+ *  - the process the agent spawns is `simctl spawn`, not the helper; the helper's own pid arrives on
+ *    stdout and is killed separately, because the two do not die together;
+ *  - earlier helpers for the same device are found with `pgrep` and killed before every spawn;
+ *  - `fatal` is final: it means the runtime refused the private API, and spawning again would only
+ *    hear the same answer.
+ *
+ * **Running out of the respawn budget is not final**, which is TouchHelper's rule too ("it self-clears,
+ * so a session that briefly could not start a helper is not left without input until the device is
+ * rebooted"). A first version made it final, and a Mac short of memory turned one slow minute into a
+ * device with no input for the rest of its boot. The helper waits for the window to clear and launches
+ * again, answering `starting` meanwhile.
+ */
+export declare class GuestHelper {
+    private readonly udid;
+    private readonly touchscreens;
+    private readonly native;
+    private readonly options;
+    private proc;
+    private guestPid;
+    private gestureProc;
+    private ready;
+    private stopped;
+    private unavailable;
+    private fatalReason;
+    private spawns;
+    private pending;
+    private readyTimer;
+    private readyWaiters;
+    private generation;
+    private cooldown;
+    private outage;
+    private launching;
+    /**
+     * `touchscreens` is asked on every launch, not once: display UUIDs change on every boot, and a respawn
+     * after the device rebooted under the agent must register the new ones.
+     */
+    constructor(udid: string, touchscreens: () => Promise<string[]>, native?: GuestHelperNative, options?: GuestHelperOptions);
+    start(): Promise<void>;
+    stop(): void;
+    inputState(): 'ready' | 'starting' | 'unavailable';
+    /** Resolves true once the helper is ready, false if it becomes unavailable or is stopped first. */
+    whenReady(): Promise<boolean>;
+    /** Why the helper cannot serve — for good, or for now — or null. */
+    unavailableReason(): string | null;
+    ownsGesture(): boolean;
+    /** One finger on the panel whose display UUID is `screen`. Acked on the write, like Indigo: the helper
+     *  answers a touch only when it fails, and a drag is too many lines a second to wait on. */
+    touch(screen: string, phase: TouchPhase, x: number, y: number, edge: boolean): boolean;
+    pinch(screen: string, phase: TouchPhase, x1: number, y1: number, x2: number, y2: number): boolean;
+    hinge(fromDeg: number, toDeg: number, durationMs: number): Promise<boolean>;
+    orient(value: GuestOrientation): Promise<boolean>;
+    key(usagePage: number, usage: number, holdMs: number, modifiers?: Array<[number, number]>): Promise<boolean>;
+    /** Half of a held press — a long-press lasts as long as the tester holds it, like TouchHelper's
+     *  `pressButtonDown`/`Up`. */
+    keyDown(usagePage: number, usage: number): Promise<boolean>;
+    keyUp(usagePage: number, usage: number): Promise<boolean>;
+    private gestureFrame;
+    private command;
+    private write;
+    private launch;
+    private onLine;
+    private handleDeath;
+    /** Out of service until the respawn window has room again, then launch. */
+    private retryLater;
+    private noteOutage;
+    /** For good: the runtime refused the helper, or it could not be exec'd at all. */
+    private becomeUnavailable;
+    private armReadyDeadline;
+    private clearReadyDeadline;
+    private failPending;
+    private settleReadyWaiters;
+    /** `simctl spawn` was started detached, so it leads its own process group. */
+    private signalProcess;
+}
+//# sourceMappingURL=GuestHelper.d.ts.map

package/dist/GuestHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuestHelper.d.ts","sourceRoot":"","sources":["../src/GuestHelper.ts"],"names":[],"mappings":"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"}