@autifyhq/aximo-cli 0.8.0 → 0.10.0

package/dist/mobile-control/appium-controller.test.js

@@ -11,24 +11,47 @@ function fakeTransport(options = {}) {
     const calls = [];
     const windowWidth = options.windowWidth ?? 400;
     const screenshotWidth = options.screenshotWidth ?? 400;
+    const findQueue = options.findElementRefs ? [...options.findElementRefs] : null;
+    let landscape = false;
     const transport = {
         async request(method, path, body) {
             calls.push({ method, path, body });
             if (method === "POST" && path === "/session") {
                 return { sessionId: "sess-1" };
             }
+            if (path.endsWith("/orientation")) {
+                landscape = body.orientation === "LANDSCAPE";
+                return {};
+            }
+            if (path.endsWith("/location")) {
+                if (options.locationError)
+                    throw new Error(options.locationError);
+                return {};
+            }
             if (path.endsWith("/screenshot")) {
                 return pngWithWidth(screenshotWidth);
             }
             if (path.endsWith("/window/rect")) {
-                return { width: windowWidth, height: windowWidth * 2, x: 0, y: 0 };
+                return landscape
+                    ? { width: windowWidth * 2, height: windowWidth, x: 0, y: 0 }
+                    : { width: windowWidth, height: windowWidth * 2, x: 0, y: 0 };
             }
             if (path.endsWith("/element/active")) {
+                if (options.activeElementError)
+                    throw new Error(options.activeElementError);
                 const ref = options.activeElement === undefined ? "active-el" : options.activeElement;
                 return ref ? { [ELEMENT_KEY]: ref } : null;
             }
+            if (method === "GET" && path.endsWith("/displayed")) {
+                const ref = path.split("/").at(-2) ?? "";
+                return options.displayed ? options.displayed(ref) : true;
+            }
             if (method === "POST" && path.endsWith("/element")) {
-                const ref = options.findElementRef === undefined ? "found-el" : options.findElementRef;
+                const ref = findQueue
+                    ? (findQueue.shift() ?? null)
+                    : options.findElementRef === undefined
+                        ? "found-el"
+                        : options.findElementRef;
                 return ref ? { [ELEMENT_KEY]: ref } : null;
             }
             return {};
@@ -66,6 +89,12 @@ function pointerActions(calls) {
     const groups = body["actions"];
     return groups[0]?.actions ?? [];
 }
+function lastPointerActions(calls) {
+    const actionCalls = calls.filter((c) => c.path.endsWith("/actions") && c.method === "POST");
+    const body = (actionCalls[actionCalls.length - 1]?.body ?? {});
+    const groups = body["actions"];
+    return groups[0]?.actions ?? [];
+}
 describe("AppiumController session capabilities", () => {
     it("sends Android UiAutomator2 caps", async () => {
         const { controller, calls } = makeController("android");
@@ -145,6 +174,75 @@ describe("AppiumController touch actions", () => {
         expect(downs).toHaveLength(2);
     });
 });
+describe("AppiumController pinch zoom", () => {
+    it("sends two synchronized touch pointers split around the scaled center", async () => {
+        const { controller, calls } = makeController("ios", { windowWidth: 400, screenshotWidth: 800 });
+        await controller.pinchZoom(200, 400, 2, 500);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/actions") && c.method === "POST");
+        const groups = body["actions"];
+        expect(groups).toHaveLength(2);
+        expect(groups.every((g) => g.type === "pointer" && g.parameters.pointerType === "touch")).toBe(true);
+        expect(groups[0]?.id).not.toBe(groups[1]?.id);
+        // Center scales 2x to (100, 200); start offset ±50, end offset ±100 (100 * scale / 2).
+        expect(groups[0]?.actions[0]).toMatchObject({ type: "pointerMove", x: 100, y: 150 });
+        expect(groups[0]?.actions[3]).toMatchObject({
+            type: "pointerMove",
+            x: 100,
+            y: 100,
+            duration: 500,
+        });
+        expect(groups[1]?.actions[0]).toMatchObject({ type: "pointerMove", x: 100, y: 250 });
+        expect(groups[1]?.actions[3]).toMatchObject({
+            type: "pointerMove",
+            x: 100,
+            y: 300,
+            duration: 500,
+        });
+        expect(calls.some((c) => c.method === "DELETE" && c.path.endsWith("/actions"))).toBe(true);
+    });
+    it("moves fingers toward the center when scale < 1 (zoom out)", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.pinchZoom(100, 300, 0.5, 600);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/actions") && c.method === "POST");
+        const groups = body["actions"];
+        expect(groups[0]?.actions[3]).toMatchObject({ x: 100, y: 275 });
+        expect(groups[1]?.actions[3]).toMatchObject({ x: 100, y: 325 });
+    });
+});
+describe("AppiumController rotation + location", () => {
+    it("rotateDevice posts the W3C orientation and refreshes coordinate scaling", async () => {
+        const { controller, calls } = makeController("ios", { windowWidth: 400, screenshotWidth: 800 });
+        await controller.tap(200, 100); // caches the 2x pixel->point scale
+        const result = await controller.rotateDevice("landscape");
+        expect(result.ok).toBe(true);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/orientation"));
+        expect(body["orientation"]).toBe("LANDSCAPE");
+        // Landscape rect is 800pt wide -> scale is 1 now; a stale cache would halve these.
+        await controller.tap(200, 100);
+        const move = lastPointerActions(calls)[0];
+        expect(move.x).toBe(200);
+        expect(move.y).toBe(100);
+    });
+    it("rotateDevice maps portrait to PORTRAIT", async () => {
+        const { controller, calls } = makeController("android");
+        const result = await controller.rotateDevice("portrait");
+        expect(result.ok).toBe(true);
+        expect(bodyOf(calls, (c) => c.path.endsWith("/orientation"))["orientation"]).toBe("PORTRAIT");
+    });
+    it("setLocation posts the W3C location body", async () => {
+        const { controller, calls } = makeController("android");
+        const result = await controller.setLocation(35.68, 139.69, 10);
+        expect(result.ok).toBe(true);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/location"));
+        expect(body["location"]).toEqual({ latitude: 35.68, longitude: 139.69, altitude: 10 });
+    });
+    it("setLocation returns the WebDriver failure as a structured error", async () => {
+        const { controller } = makeController("android", { locationError: "mock location denied" });
+        const result = await controller.setLocation(1, 2, 0);
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("mock location denied");
+    });
+});
 describe("AppiumController text + keys", () => {
     it("typeText on Android uses mobile: type", async () => {
         const { controller, calls } = makeController("android");
@@ -154,12 +252,41 @@ describe("AppiumController text + keys", () => {
         expect(exec.script).toBe("mobile: type");
         expect(exec.args[0]?.["text"]).toBe("hello");
     });
-    it("typeText on iOS sends keys to the active element", async () => {
-        const { controller, calls } = makeController("ios");
-        await controller.typeText("hi");
-        expect(calls.some((c) => c.path.endsWith("/element/active"))).toBe(true);
-        const send = bodyOf(calls, (c) => c.path.endsWith("/element/active-el/value"));
-        expect(send["text"]).toBe("hi");
+    it("typeText on Android types unsafe text into the focused element", async () => {
+        const { controller, calls } = makeController("android", { activeElement: "el-1" });
+        const result = await controller.typeText("パスワード$1!");
+        expect(result.ok).toBe(true);
+        expect(calls.some((c) => c.path.endsWith("/execute/sync"))).toBe(false);
+        const send = bodyOf(calls, (c) => c.path.endsWith("/element/el-1/value"));
+        expect(send["text"]).toBe("パスワード$1!");
+    });
+    it("typeText on Android returns a clear error for unsafe text with no focused element", async () => {
+        const { controller } = makeController("android", { activeElement: null });
+        const result = await controller.typeText("p@ss!word");
+        expect(result.ok).toBe(false);
+        expect(result.error).toBe("Cannot type special or non-ASCII characters: no input field is focused. Tap the field first.");
+    });
+    it("typeText on Android treats an active-element rejection as no focus", async () => {
+        const { controller } = makeController("android", { activeElementError: "no such element" });
+        const result = await controller.typeText("héllo");
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("no input field is focused");
+    });
+    it("typeText on iOS sends per-char key actions without resolving the active element", async () => {
+        const { controller, calls } = makeController("ios", { activeElement: null });
+        const result = await controller.typeText("hi");
+        expect(result.ok).toBe(true);
+        expect(calls.some((c) => c.path.endsWith("/element/active"))).toBe(false);
+        const body = bodyOf(calls, (c) => c.path.endsWith("/actions") && c.method === "POST");
+        const groups = body["actions"];
+        expect(groups[0]?.type).toBe("key");
+        expect(groups[0]?.actions).toEqual([
+            { type: "keyDown", value: "h" },
+            { type: "keyUp", value: "h" },
+            { type: "keyDown", value: "i" },
+            { type: "keyUp", value: "i" },
+        ]);
+        expect(calls.some((c) => c.method === "DELETE" && c.path.endsWith("/actions"))).toBe(true);
     });
     it("clearText clears the active element when present", async () => {
         const { controller, calls } = makeController("android", { activeElement: "el-9" });
@@ -220,6 +347,27 @@ describe("AppiumController findElement", () => {
         expect(result.ok).toBe(false);
         expect(result.error).toContain("not found");
     });
+    it("skips a non-displayed match and clicks the next strategy's visible one", async () => {
+        const { controller, calls } = makeController("android", {
+            findElementRefs: ["hidden-el", "vis-el"],
+            displayed: (ref) => ref === "vis-el",
+        });
+        const result = await controller.findElement("Sign in");
+        expect(result.ok).toBe(true);
+        expect(calls.some((c) => c.path.endsWith("/element/hidden-el/click"))).toBe(false);
+        expect(calls.some((c) => c.path.endsWith("/element/vis-el/click"))).toBe(true);
+        expect(calls.filter((c) => c.method === "POST" && c.path.endsWith("/element"))).toHaveLength(2);
+    });
+    it("treats a match that is never displayed as not found", async () => {
+        const { controller, calls } = makeController("ios", {
+            findElementRef: "hidden-el",
+            displayed: () => false,
+        });
+        const result = await controller.findElement("OK");
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("not found");
+        expect(calls.some((c) => c.path.includes("/click"))).toBe(false);
+    });
 });
 describe("AppiumController launch + lifecycle", () => {
     it("launchApp uses mobile: activateApp with appId on Android", async () => {
@@ -250,3 +398,105 @@ describe("AppiumController launch + lifecycle", () => {
         expect(calls.some((c) => c.method === "DELETE" && c.path === "/session/sess-1")).toBe(true);
     });
 });
+describe("AppiumController MJPEG capture", () => {
+    it("adds the mjpegServerPort capability and applies conservative settings", async () => {
+        const { transport, calls } = fakeTransport();
+        const controller = new AppiumController({
+            endpoint: "http://x",
+            platform: "android",
+            target: "udid-1",
+            mjpegServerPort: async () => 7777,
+            transport,
+        });
+        await controller.ensureReady();
+        const body = calls.find((c) => c.method === "POST" && c.path === "/session")?.body;
+        expect(body["capabilities"]?.alwaysMatch["appium:mjpegServerPort"]).toBe(7777);
+        const settings = calls.find((c) => c.path.endsWith("/appium/settings"));
+        expect(settings?.body).toEqual({
+            settings: {
+                mjpegServerFramerate: 10,
+                mjpegScalingFactor: 50,
+                mjpegServerScreenshotQuality: 40,
+            },
+        });
+        expect(controller.getMjpegPort()).toBe(7777);
+    });
+    it("omits the capability and settings call when no port is configured", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.screenshot();
+        const body = calls.find((c) => c.method === "POST" && c.path === "/session")?.body;
+        expect(body["capabilities"]?.alwaysMatch["appium:mjpegServerPort"]).toBeUndefined();
+        expect(calls.some((c) => c.path.endsWith("/appium/settings"))).toBe(false);
+        expect(controller.getMjpegPort()).toBeUndefined();
+    });
+});
+describe("AppiumController session recovery", () => {
+    function deadSessionTransport(failuresBeforeRecovery) {
+        const calls = [];
+        let sessions = 0;
+        let remainingFailures = failuresBeforeRecovery;
+        const transport = {
+            async request(method, path, body) {
+                calls.push({ method, path, body });
+                if (method === "POST" && path === "/session") {
+                    sessions += 1;
+                    return { sessionId: `sess-${sessions}` };
+                }
+                if (path.endsWith("/screenshot")) {
+                    if (remainingFailures > 0) {
+                        remainingFailures -= 1;
+                        throw new Error("WebDriver GET /screenshot failed: invalid session id");
+                    }
+                    return pngWithWidth(400);
+                }
+                return {};
+            },
+        };
+        return { transport, calls };
+    }
+    it("rebuilds the session once and retries when the cached session has died", async () => {
+        const { transport, calls } = deadSessionTransport(1);
+        const controller = new AppiumController({
+            endpoint: "http://x",
+            platform: "android",
+            target: "udid-1",
+            transport,
+        });
+        const shot = await controller.screenshot();
+        expect(Buffer.isBuffer(shot)).toBe(true);
+        expect(calls.filter((c) => c.method === "POST" && c.path === "/session")).toHaveLength(2);
+    });
+    it("surfaces the error when the rebuilt session is dead too", async () => {
+        const { transport, calls } = deadSessionTransport(2);
+        const controller = new AppiumController({
+            endpoint: "http://x",
+            platform: "android",
+            target: "udid-1",
+            transport,
+        });
+        await expect(controller.screenshot()).rejects.toThrow(/invalid session id/);
+        expect(calls.filter((c) => c.method === "POST" && c.path === "/session")).toHaveLength(2);
+    });
+    it("does not rebuild the session for ordinary command failures", async () => {
+        const calls = [];
+        const transport = {
+            async request(method, path, body) {
+                calls.push({ method, path, body });
+                if (method === "POST" && path === "/session")
+                    return { sessionId: "sess-1" };
+                if (path.endsWith("/screenshot")) {
+                    throw new Error("WebDriver GET /screenshot failed: unexpected server error");
+                }
+                return {};
+            },
+        };
+        const controller = new AppiumController({
+            endpoint: "http://x",
+            platform: "android",
+            target: "udid-1",
+            transport,
+        });
+        await expect(controller.screenshot()).rejects.toThrow(/unexpected server error/);
+        expect(calls.filter((c) => c.method === "POST" && c.path === "/session")).toHaveLength(1);
+    });
+});

package/dist/mobile-control/bundle-id-map.js

@@ -12,12 +12,15 @@ export function withBundleIdTranslation(controller, map) {
         doubleTap: (x, y) => controller.doubleTap(x, y),
         longPress: (x, y, durationMs) => controller.longPress(x, y, durationMs),
         swipe: (x1, y1, x2, y2, durationMs) => controller.swipe(x1, y1, x2, y2, durationMs),
+        pinchZoom: (x, y, scale, durationMs) => controller.pinchZoom(x, y, scale, durationMs),
         typeText: (text) => controller.typeText(text),
         pressKey: (key) => controller.pressKey(key),
         launchApp: (app) => controller.launchApp(map.get(app) ?? app),
         findElement: (text) => controller.findElement(text),
         clearText: () => controller.clearText(),
         hideKeyboard: () => controller.hideKeyboard(),
+        rotateDevice: (orientation) => controller.rotateDevice(orientation),
+        setLocation: (latitude, longitude, altitude) => controller.setLocation(latitude, longitude, altitude),
         close: () => controller.close(),
     };
     if (controller.getDeviceTime) {

package/dist/mobile-control/controller.d.ts

@@ -8,12 +8,15 @@ export interface MobileController {
     doubleTap(x: number, y: number): Promise<void>;
     longPress(x: number, y: number, durationMs: number): Promise<void>;
     swipe(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise<void>;
+    pinchZoom(x: number, y: number, scale: number, durationMs: number): Promise<void>;
     typeText(text: string): Promise<ActionResult>;
     pressKey(key: string): Promise<ActionResult>;
     launchApp(app: string): Promise<ActionResult>;
     findElement(text: string): Promise<ActionResult>;
     clearText(): Promise<ActionResult>;
     hideKeyboard(): Promise<ActionResult>;
+    rotateDevice(orientation: "portrait" | "landscape"): Promise<ActionResult>;
+    setLocation(latitude: number, longitude: number, altitude: number): Promise<ActionResult>;
     getDeviceTime?(): Promise<{
         datetime: string;
         timezone: string;

package/dist/mobile-control/frame-sender.d.ts

@@ -0,0 +1,34 @@
+import { type Socket } from "socket.io-client";
+export interface FrameSenderOptions {
+    wsUrl: string;
+    deviceToken: string;
+    /** Called when the gateway acks that no viewer is watching — capture should stop. */
+    onInactive: () => void;
+    log?: (message: string) => void;
+    /** Test seam: overrides the socket factory. */
+    connect?: (wsUrl: string, deviceToken: string) => Socket;
+}
+/**
+ * Pushes JPEG frames to the gateway over a DEDICATED socket.io connection
+ * (handshake `role: "frames"`) so frame bytes never share a TCP stream with
+ * command acks or engine.io pings — on a saturated uplink that head-of-line
+ * blocking delays tap acks by seconds and starves pings into a tunnel drop.
+ *
+ * Sending is ack-clocked with keep-latest replacement: one frame in flight,
+ * and whatever arrives while it is unacknowledged replaces the queued one.
+ * socket.io `volatile` cannot bound this — the websocket transport reports
+ * writable again on the next tick without consulting the real send buffer, so
+ * volatile frames still queue unboundedly on a slow link.
+ */
+export declare class FrameSender {
+    private readonly options;
+    private socket;
+    private pending;
+    private pumping;
+    private oversizedWarned;
+    constructor(options: FrameSenderOptions);
+    start(): void;
+    stop(): void;
+    push(frame: Buffer): void;
+    private pump;
+}

package/dist/mobile-control/frame-sender.js

@@ -0,0 +1,96 @@
+import { io } from "socket.io-client";
+const SOCKET_PATH = "/devices/tunnel";
+const ACK_TIMEOUT_MS = 10_000;
+// Frames at the pinned capture settings are ~30-80KB. Anything this large
+// means misapplied settings; sending it would monopolize a slow uplink.
+const MAX_FRAME_BYTES = 1024 * 1024;
+/**
+ * Pushes JPEG frames to the gateway over a DEDICATED socket.io connection
+ * (handshake `role: "frames"`) so frame bytes never share a TCP stream with
+ * command acks or engine.io pings — on a saturated uplink that head-of-line
+ * blocking delays tap acks by seconds and starves pings into a tunnel drop.
+ *
+ * Sending is ack-clocked with keep-latest replacement: one frame in flight,
+ * and whatever arrives while it is unacknowledged replaces the queued one.
+ * socket.io `volatile` cannot bound this — the websocket transport reports
+ * writable again on the next tick without consulting the real send buffer, so
+ * volatile frames still queue unboundedly on a slow link.
+ */
+export class FrameSender {
+    options;
+    socket = null;
+    pending = null;
+    pumping = false;
+    oversizedWarned = false;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.socket)
+            return;
+        const connect = this.options.connect ?? defaultConnect;
+        this.socket = connect(this.options.wsUrl, this.options.deviceToken);
+        this.socket.on("connect_error", (err) => {
+            this.options.log?.(`Frame connection error: ${err.message}`);
+        });
+        // A reconnect may have frames waiting from before the drop.
+        this.socket.on("connect", () => void this.pump());
+    }
+    stop() {
+        this.pending = null;
+        this.socket?.close();
+        this.socket = null;
+    }
+    push(frame) {
+        if (frame.length > MAX_FRAME_BYTES) {
+            if (!this.oversizedWarned) {
+                this.oversizedWarned = true;
+                this.options.log?.(`Dropping oversized MJPEG frame (${frame.length} bytes) — capture settings were likely not applied.`);
+            }
+            return;
+        }
+        this.pending = frame;
+        void this.pump();
+    }
+    async pump() {
+        if (this.pumping)
+            return;
+        this.pumping = true;
+        try {
+            while (this.pending) {
+                const socket = this.socket;
+                // Disconnected: leave the newest frame queued; the connect handler
+                // resumes the pump once the transport is back.
+                if (!socket?.connected)
+                    return;
+                const frame = this.pending;
+                this.pending = null;
+                try {
+                    const ack = (await socket.timeout(ACK_TIMEOUT_MS).emitWithAck("stream_frame", frame));
+                    if (ack?.active === false) {
+                        this.pending = null;
+                        this.options.onInactive();
+                        return;
+                    }
+                }
+                catch {
+                    // Ack timeout: the link is stalling. The frame is already stale —
+                    // drop it and let the next capture retry.
+                    return;
+                }
+            }
+        }
+        finally {
+            this.pumping = false;
+        }
+    }
+}
+function defaultConnect(wsUrl, deviceToken) {
+    return io(wsUrl, {
+        path: SOCKET_PATH,
+        transports: ["websocket"],
+        auth: { deviceToken, role: "frames" },
+        reconnectionAttempts: Infinity,
+        timeout: 10_000,
+    });
+}

package/dist/mobile-control/frame-sender.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/frame-sender.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from "vitest";
+import { FrameSender } from "./frame-sender.js";
+class FakeFramesSocket {
+    connected = true;
+    sent = [];
+    acks = [];
+    handlers = new Map();
+    on(event, handler) {
+        this.handlers.set(event, handler);
+        return this;
+    }
+    fire(event, ...args) {
+        this.handlers.get(event)?.(...args);
+    }
+    timeout(_ms) {
+        return {
+            emitWithAck: (_event, frame) => new Promise((resolve) => {
+                this.sent.push(frame);
+                this.acks.push(resolve);
+            }),
+        };
+    }
+    close() {
+        this.connected = false;
+    }
+}
+function tick() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function build(socket, onInactive = vi.fn()) {
+    const sender = new FrameSender({
+        wsUrl: "ws://gateway",
+        deviceToken: "token",
+        onInactive,
+        connect: () => socket,
+    });
+    sender.start();
+    return { sender, onInactive };
+}
+describe("FrameSender", () => {
+    it("ack-clocks with keep-latest: frames pushed mid-flight collapse to the newest", async () => {
+        const socket = new FakeFramesSocket();
+        const { sender } = build(socket);
+        sender.push(Buffer.from("f1"));
+        await tick();
+        sender.push(Buffer.from("f2"));
+        sender.push(Buffer.from("f3"));
+        await tick();
+        // f1 unacked: nothing else may be in flight.
+        expect(socket.sent.map(String)).toEqual(["f1"]);
+        socket.acks[0]?.({ active: true });
+        await tick();
+        // f2 was replaced by f3 while waiting.
+        expect(socket.sent.map(String)).toEqual(["f1", "f3"]);
+        socket.acks[1]?.({ active: true });
+        await tick();
+        expect(socket.sent).toHaveLength(2);
+    });
+    it("stops capture when the gateway acks that nobody is watching", async () => {
+        const socket = new FakeFramesSocket();
+        const { sender, onInactive } = build(socket);
+        sender.push(Buffer.from("frame"));
+        await tick();
+        socket.acks[0]?.({ active: false });
+        await tick();
+        expect(onInactive).toHaveBeenCalledTimes(1);
+    });
+    it("holds the newest frame while disconnected and resumes on connect", async () => {
+        const socket = new FakeFramesSocket();
+        socket.connected = false;
+        const { sender } = build(socket);
+        sender.push(Buffer.from("f1"));
+        sender.push(Buffer.from("f2"));
+        await tick();
+        expect(socket.sent).toHaveLength(0);
+        socket.connected = true;
+        socket.fire("connect");
+        await tick();
+        expect(socket.sent.map(String)).toEqual(["f2"]);
+    });
+    it("drops oversized frames instead of sending them", async () => {
+        const socket = new FakeFramesSocket();
+        const log = vi.fn();
+        const sender = new FrameSender({
+            wsUrl: "ws://gateway",
+            deviceToken: "token",
+            onInactive: vi.fn(),
+            log,
+            connect: () => socket,
+        });
+        sender.start();
+        sender.push(Buffer.alloc(2 * 1024 * 1024));
+        await tick();
+        expect(socket.sent).toHaveLength(0);
+        expect(log).toHaveBeenCalledOnce();
+    });
+    it("stop() clears the queue and closes the socket", async () => {
+        const socket = new FakeFramesSocket();
+        const { sender } = build(socket);
+        sender.push(Buffer.from("f1"));
+        await tick();
+        sender.stop();
+        expect(socket.connected).toBe(false);
+        socket.acks[0]?.({ active: true });
+        await tick();
+        expect(socket.sent).toHaveLength(1);
+    });
+});

package/dist/mobile-control/mjpeg-stream.d.ts

@@ -0,0 +1,43 @@
+import { type Socket as NetSocket } from "node:net";
+/**
+ * Incremental JPEG frame extractor for an MJPEG byte stream. Scans raw bytes
+ * for SOI/EOI markers instead of parsing multipart headers — the WDA and
+ * UiAutomator2 servers frame their streams differently, and marker scanning
+ * handles both and resyncs after corruption (HTTP headers and part boundaries
+ * fall out naturally because scanning starts at the first SOI).
+ */
+export declare class MjpegFrameParser {
+    private buffer;
+    push(chunk: Buffer): Buffer[];
+}
+export interface MjpegStreamClientOptions {
+    /** Bring the device session (and its forwarded MJPEG port) up; called before each connect. */
+    ensureReady: () => Promise<void>;
+    /** Local port the driver forwarded to the on-device MJPEG server. */
+    getPort: () => number | undefined;
+    onFrame: (jpeg: Buffer) => void;
+    log?: (message: string) => void;
+    /** Test seam: overrides the TCP connection factory. */
+    createConnection?: (port: number) => NetSocket;
+}
+/**
+ * Connects to the driver-forwarded MJPEG port and emits complete JPEG frames.
+ * Reconnects with capped backoff while started — an Appium session rebuild
+ * lands on a fresh port, which `getPort` reflects on the next attempt. All
+ * timers are cancellable so `stop()` never holds the process open.
+ */
+export declare class MjpegStreamClient {
+    private readonly options;
+    private active;
+    private socket;
+    private attempt;
+    private loop;
+    private wake;
+    constructor(options: MjpegStreamClientOptions);
+    isActive(): boolean;
+    start(): void;
+    stop(): Promise<void>;
+    private run;
+    private streamOnce;
+    private sleep;
+}