portholejs 0.1.1 → 0.2.1

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
@@ -11,10 +12,13 @@ import { startMcpServer } from "./mcp/server.js";
 import { VERSION } from "./index.js";
 import { resolveTarget } from "./target-resolution.js";
 import { defaultScreenshotPath, fetchSessionScreenshot, getSessionJson, postSessionJson, sendSessionInput, writeScreenshot, } from "./control-client.js";
-import { readState } from "./state.js";
+import { readState, removeSession } from "./state.js";
 import { runCliAction } from "./cli-errors.js";
 import { runDoctor } from "./doctor.js";
 import { ensurePortFree } from "./port-check.js";
+import { scrollGesture } from "./gesture.js";
+import { comparePngScreens, parseDiffRegion } from "./screen-diff.js";
+import { recordSession } from "./recording.js";
 const program = new Command();
 if (Number(process.versions.node.split(".")[0] ?? "0") < 20) {
     console.error("porthole: Node.js 20 or newer is required.");
@@ -75,7 +79,7 @@ program
     });
 });
 program
-    .command("start [avd]", { isDefault: true })
+    .command("start [avds...]", { isDefault: true })
     .description("Boot/attach emulator and serve preview")
     .option("-p, --port <port>", "HTTP port", "3200")
     .option("-d, --device <serial>", "Target device serial")
@@ -92,7 +96,7 @@ program
     .option("--max-fps <fps>", "Maximum stream FPS", "30")
     .option("--bitrate <bps>", "Stream bitrate in bits per second")
     .option("-q, --quiet", "Quiet/JSON mode")
-    .action(async (avd, opts) => {
+    .action(async (avds, opts) => {
     // Check the port before prompting, booting, or detaching — a busy port
     // otherwise surfaces as a boot wasted on a doomed session or as an
     // opaque detach timeout.
@@ -102,73 +106,47 @@ program
         process.exit(1);
     }
     if (opts.detach && process.env["PORTHOLE_DETACHED_CHILD"] !== "1") {
-        await startDetached(avd, opts);
+        await startDetached(avds ?? [], opts);
         return;
     }
     const sdk = findAndroidSdk();
-    let devices = await listDevices();
-    let selectedAvd = avd;
-    if (!selectedAvd && !opts.device && !opts.quiet) {
-        selectedAvd = await promptForAvd(devices);
-    }
-    const resolution = resolveTarget(devices, selectedAvd, opts.device);
-    let target;
-    let bootedByUs = false;
-    if (resolution.action === "error") {
-        console.error(resolution.message);
-        process.exit(1);
-    }
-    if (resolution.action === "boot") {
-        if (!opts.quiet)
-            console.log(`Booting ${resolution.avdName}...`);
-        const serial = await bootDevice({
-            sdk,
-            avdName: resolution.avdName,
-            emulatorArgs: emulatorArgs(opts),
-        });
-        devices = await listDevices();
-        target = devices.find((d) => d.serial === serial);
-        bootedByUs = true;
+    const devices = await listDevices();
+    let selectedAvds = avds ?? [];
+    if (selectedAvds.length === 0 && !opts.device && !opts.quiet) {
+        const selectedAvd = await promptForAvd(devices);
+        selectedAvds = selectedAvd ? [selectedAvd] : [];
     }
-    else {
-        target = resolution.device;
-    }
-    if (target?.state === "offline") {
-        if (!opts.quiet)
-            console.log(`Reconnecting ${target.serial}...`);
-        await reconnectOfflineDevices(sdk, target.serial ?? undefined);
-        devices = await listDevices();
-        const reconnected = devices.find((device) => (target?.serial && device.serial === target.serial) ||
-            device.name === target?.name);
-        if (reconnected) {
-            target = reconnected;
-        }
+    let targets;
+    try {
+        targets = await resolveSessionTargets(devices, selectedAvds, opts, sdk);
     }
-    if (!target || !target.serial || target.state !== "running") {
-        console.error("No target device.");
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
         process.exit(1);
     }
     const session = new Session({
-        device: target,
+        devices: targets,
         port: parseInt(opts.port, 10),
         host: opts.host,
         maxSize: Number(opts.maxSize),
         maxFps: Number(opts.maxFps),
         bitrate: opts.bitrate ? Number(opts.bitrate) : undefined,
-        bootedByUs,
         detached: process.env["PORTHOLE_DETACHED_CHILD"] === "1",
         forceMjpeg: opts.mjpeg ?? false,
     });
     try {
         const { url } = await session.start();
         if (!opts.quiet) {
-            console.log(`Attached to ${target.name} [${target.profile}] (${target.serial})`);
+            for (const target of targets) {
+                console.log(`Attached to ${target.device.name} [${target.device.profile}] (${target.device.serial})`);
+            }
             console.log(`Preview: ${url}`);
             if (opts.mjpeg)
                 console.log("Video mode: MJPEG screenshot polling");
         }
         else {
-            process.stdout.write(JSON.stringify({ device: target, url }) + "\n");
+            process.stdout.write(JSON.stringify({ devices: targets.map((target) => target.device), url }) +
+                "\n");
         }
         if (opts.preview && process.env["PORTHOLE_DETACHED_CHILD"] !== "1") {
             openBrowser(url);
@@ -182,15 +160,19 @@ program
         else {
             console.error(`Failed to start: ${message}`);
         }
-        if (bootedByUs && !opts.keepAlive && target.serial) {
-            await shutdownDevice(sdk, target.serial);
+        for (const target of targets) {
+            if (target.bootedByUs && !opts.keepAlive && target.device.serial) {
+                await shutdownDevice(sdk, target.device.serial);
+            }
         }
         process.exit(1);
     }
     const stopForSignal = async () => {
         await session.stop();
-        if (bootedByUs && !opts.keepAlive && target.serial) {
-            await shutdownDevice(sdk, target.serial);
+        for (const target of targets) {
+            if (target.bootedByUs && !opts.keepAlive && target.device.serial) {
+                await shutdownDevice(sdk, target.device.serial);
+            }
         }
         process.exit(0);
     };
@@ -206,6 +188,7 @@ program
     const devices = await listDevices();
     const state = await readState();
     const targetSerials = new Set();
+    const matchedSessions = state.sessions.filter((session) => !avd || session.avdName === avd);
     for (const d of devices) {
         if (d.state === "running" &&
             d.serial &&
@@ -213,10 +196,14 @@ program
             targetSerials.add(d.serial);
         }
     }
-    for (const session of state.sessions) {
-        if (!avd || session.avdName === avd) {
-            targetSerials.add(session.serial);
-            if (session.detached && session.pid !== process.pid) {
+    for (const session of matchedSessions) {
+        targetSerials.add(session.serial);
+        if (session.detached && session.pid !== process.pid) {
+            const siblingOnSharedServer = avd !== undefined &&
+                state.sessions.some((other) => other.pid === session.pid &&
+                    other.port === session.port &&
+                    other.serial !== session.serial);
+            if (!siblingOnSharedServer) {
                 try {
                     process.kill(session.pid, "SIGTERM");
                 }
@@ -224,6 +211,9 @@ program
                     // process already gone
                 }
             }
+            else {
+                await removeSession({ serial: session.serial });
+            }
         }
     }
     if (targetSerials.size === 0) {
@@ -251,6 +241,7 @@ program
     .command("tap <x> <y>")
     .description("Touch at normalized 0..1 coordinates")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((x, y, opts) => {
     void runCliAction(opts, async () => {
@@ -259,15 +250,93 @@ program
         if (isNaN(nx) || isNaN(ny) || nx < 0 || nx > 1 || ny < 0 || ny > 1) {
             throw new Error("Coordinates must be numbers in 0..1");
         }
-        await sendSessionInput({ kind: "touch", phase: "down", x: nx, y: ny }, { port: parseOptionalPort(opts.port) });
-        const session = await sendSessionInput({ kind: "touch", phase: "up", x: nx, y: ny }, { port: parseOptionalPort(opts.port) });
+        await sendSessionInput({ kind: "touch", phase: "down", x: nx, y: ny }, sessionControlOpts(opts));
+        const session = await sendSessionInput({ kind: "touch", phase: "up", x: nx, y: ny }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, session, event: "tap" }, `Tapped ${nx},${ny}`);
     });
 });
+program
+    .command("swipe <x1> <y1> <x2> <y2>")
+    .description("Swipe between normalized 0..1 phone coordinates")
+    .option("--duration <ms>", "Gesture duration in milliseconds")
+    .option("--steps <count>", "Number of move events")
+    .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
+    .option("-q, --quiet", "JSON output")
+    .action((x1, y1, x2, y2, opts) => {
+    void runCliAction(opts, async () => {
+        const event = {
+            kind: "gesture",
+            type: "swipe",
+            x1: parseNormalized(x1, "x1"),
+            y1: parseNormalized(y1, "y1"),
+            x2: parseNormalized(x2, "x2"),
+            y2: parseNormalized(y2, "y2"),
+            ...(opts.duration === undefined
+                ? {}
+                : { durationMs: parsePositiveNumber(opts.duration, "duration") }),
+            ...(opts.steps === undefined
+                ? {}
+                : { steps: parsePositiveInteger(opts.steps, "steps") }),
+        };
+        const session = await sendSessionInput(event, {
+            port: parseOptionalPort(opts.port),
+        });
+        printResult(opts.quiet, { ok: true, session, event }, "Swiped");
+    });
+});
+program
+    .command("longpress <x> <y>")
+    .alias("long-press")
+    .description("Long-press normalized 0..1 phone coordinates")
+    .option("--duration <ms>", "Hold duration in milliseconds")
+    .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
+    .option("-q, --quiet", "JSON output")
+    .action((x, y, opts) => {
+    void runCliAction(opts, async () => {
+        const event = {
+            kind: "gesture",
+            type: "longpress",
+            x1: parseNormalized(x, "x"),
+            y1: parseNormalized(y, "y"),
+            ...(opts.duration === undefined
+                ? {}
+                : { durationMs: parsePositiveNumber(opts.duration, "duration") }),
+        };
+        const session = await sendSessionInput(event, {
+            port: parseOptionalPort(opts.port),
+        });
+        printResult(opts.quiet, { ok: true, session, event }, "Long-pressed");
+    });
+});
+program
+    .command("scroll <direction>")
+    .description("Scroll a phone screen: up, down, left, or right")
+    .option("--amount <value>", "Normalized scroll amount", "0.5")
+    .option("--duration <ms>", "Gesture duration in milliseconds")
+    .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
+    .option("-q, --quiet", "JSON output")
+    .action((direction, opts) => {
+    void runCliAction(opts, async () => {
+        if (!isScrollDirection(direction)) {
+            throw new Error("Scroll direction must be up, down, left, or right");
+        }
+        const event = scrollGesture(direction, parseNormalized(opts.amount, "amount"), opts.duration === undefined
+            ? undefined
+            : parsePositiveNumber(opts.duration, "duration"));
+        const session = await sendSessionInput(event, {
+            port: parseOptionalPort(opts.port),
+        });
+        printResult(opts.quiet, { ok: true, session, direction, event }, `Scrolled ${direction}`);
+    });
+});
 program
     .command("key <keycode>")
     .description("Send a single Android keyevent")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((keycode, opts) => {
     void runCliAction(opts, async () => {
@@ -275,8 +344,8 @@ program
         if (isNaN(code)) {
             throw new Error("Keycode must be a number");
         }
-        await sendSessionInput({ kind: "key", phase: "down", keycode: code }, { port: parseOptionalPort(opts.port) });
-        const session = await sendSessionInput({ kind: "key", phase: "up", keycode: code }, { port: parseOptionalPort(opts.port) });
+        await sendSessionInput({ kind: "key", phase: "down", keycode: code }, sessionControlOpts(opts));
+        const session = await sendSessionInput({ kind: "key", phase: "up", keycode: code }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, session, keycode: code }, `Key ${code} sent`);
     });
 });
@@ -284,13 +353,14 @@ program
     .command("remote <button>")
     .description("D-pad / media remote button")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((button, opts) => {
     void runCliAction(opts, async () => {
         if (!(button in REMOTE_BUTTON_TO_KEYCODE)) {
             throw new Error(`Unknown button: ${button}. Valid: ${Object.keys(REMOTE_BUTTON_TO_KEYCODE).join(", ")}`);
         }
-        const session = await sendSessionInput({ kind: "remote", button: button }, { port: parseOptionalPort(opts.port) });
+        const session = await sendSessionInput({ kind: "remote", button: button }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, session, button }, `Remote: ${button}`);
     });
 });
@@ -298,10 +368,11 @@ program
     .command("text <string>")
     .description("Type text")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((text, opts) => {
     void runCliAction(opts, async () => {
-        const session = await sendSessionInput({ kind: "text", text }, { port: parseOptionalPort(opts.port) });
+        const session = await sendSessionInput({ kind: "text", text }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, session, text }, `Typed "${text}"`);
     });
 });
@@ -309,26 +380,77 @@ program
     .command("screenshot")
     .description("Take a PNG screenshot from a running session")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-o, --output <file>", "Output path")
     .option("-q, --quiet", "JSON output")
     .action((opts) => {
     void runCliAction(opts, async () => {
-        const { session, png } = await fetchSessionScreenshot({
-            port: parseOptionalPort(opts.port),
-        });
+        const { session, png } = await fetchSessionScreenshot(sessionControlOpts(opts));
         const output = opts.output ?? defaultScreenshotPath(session.serial);
         await writeScreenshot(output, png);
         printResult(opts.quiet, { ok: true, path: output, session }, output);
     });
 });
+program
+    .command("assert-screen <baseline>")
+    .description("Compare the current screenshot against a PNG baseline")
+    .option("--threshold <ratio>", "Maximum mismatch ratio", "0.02")
+    .option("--diff <file>", "Write a PNG diff image")
+    .option("--region <x,y,w,h>", "Compare a pixel region")
+    .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
+    .option("-q, --quiet", "JSON output")
+    .action((baseline, opts) => {
+    void runCliAction(opts, async () => {
+        const { session, png } = await fetchSessionScreenshot({
+            port: parseOptionalPort(opts.port),
+        });
+        const result = comparePngScreens(await readFile(baseline), png, {
+            thresholdRatio: parseRatio(opts.threshold, "threshold"),
+            region: opts.region === undefined ? undefined : parseDiffRegion(opts.region),
+        });
+        if (opts.diff && result.diffPng) {
+            await writeFile(opts.diff, result.diffPng);
+        }
+        const payload = {
+            ok: result.ok,
+            mismatchRatio: result.mismatchRatio,
+            diffPath: opts.diff,
+            session,
+        };
+        printResult(opts.quiet, payload, result.ok
+            ? `Screen matched (${formatRatio(result.mismatchRatio)})`
+            : `Screen differed (${formatRatio(result.mismatchRatio)})`);
+        if (!result.ok)
+            process.exitCode = 1;
+    });
+});
+program
+    .command("record <output>")
+    .description("Record the current H.264 stream to an MP4 file")
+    .option("--duration <duration>", "Recording duration, e.g. 30s or 1500ms (bare = ms)")
+    .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
+    .option("-q, --quiet", "JSON output")
+    .action((output, opts) => {
+    void runCliAction(opts, async () => {
+        const result = await recordSession({
+            output,
+            durationMs: opts.duration === undefined ? undefined : parseDurationMs(opts.duration),
+            ...sessionControlOpts(opts),
+        });
+        printResult(opts.quiet, result, `Recorded ${result.path}`);
+    });
+});
 program
     .command("rotate <orientation>")
     .description("Rotate a phone session: portrait, landscape, left, or right")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((orientation, opts) => {
     void runCliAction(opts, async () => {
-        const result = await postSessionJson("/api/rotate", { orientation }, { port: parseOptionalPort(opts.port) });
+        const result = await postSessionJson("/api/rotate", { orientation }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, ...result }, `Rotated ${orientation}`);
     });
 });
@@ -336,10 +458,11 @@ program
     .command("emu <args...>")
     .description("Pass arguments to adb emu for the active session")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((args, opts) => {
     void runCliAction(opts, async () => {
-        const result = await postSessionJson("/api/emu", { args }, { port: parseOptionalPort(opts.port) });
+        const result = await postSessionJson("/api/emu", { args }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, ...result }, "Emulator command sent");
     });
 });
@@ -347,19 +470,37 @@ program
     .command("focused")
     .description("Print the currently focused UI node")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((opts) => {
     void runCliAction(opts, async () => {
-        const result = await getSessionJson("/api/focused", {
-            port: parseOptionalPort(opts.port),
-        });
+        const result = await getSessionJson("/api/focused", sessionControlOpts(opts));
         printResult(opts.quiet, result, JSON.stringify(result.response, null, 2));
     });
 });
+program
+    .command("focus-on <text>")
+    .description("Move TV D-pad focus to matching text")
+    .option("--select", "Press select after focusing")
+    .option("--max-steps <count>", "Maximum D-pad steps", "15")
+    .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
+    .option("-q, --quiet", "JSON output")
+    .action((text, opts) => {
+    void runCliAction(opts, async () => {
+        const result = await postSessionJson("/api/focus_on", {
+            text,
+            select: opts.select === true,
+            maxSteps: parsePositiveInteger(opts.maxSteps, "max-steps"),
+        }, sessionControlOpts(opts));
+        printResult(opts.quiet, result, `Focused ${text}`);
+    });
+});
 program
     .command("dump-ui")
     .description("Dump the Android accessibility hierarchy")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("--filter <text>", "Filter by text/resource id/content description")
     .option("-q, --quiet", "JSON output")
     .action((opts) => {
@@ -368,7 +509,7 @@ program
             ? `?${new URLSearchParams({ filter: opts.filter }).toString()}`
             : "";
         const result = await getSessionJson(`/api/ui${query}`, {
-            port: parseOptionalPort(opts.port),
+            ...sessionControlOpts(opts),
         });
         printResult(opts.quiet, result, JSON.stringify(result.response, null, 2));
     });
@@ -377,11 +518,12 @@ program
     .command("wait-for <text>")
     .description("Wait until text appears in the UI hierarchy")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("--timeout <ms>", "Timeout in milliseconds", "10000")
     .option("-q, --quiet", "JSON output")
     .action((text, opts) => {
     void runCliAction(opts, async () => {
-        const result = await postSessionJson("/api/wait_for", { text, timeoutMs: Number(opts.timeout) }, { port: parseOptionalPort(opts.port) });
+        const result = await postSessionJson("/api/wait_for", { text, timeoutMs: Number(opts.timeout) }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, ...result }, `Found "${text}"`);
     });
 });
@@ -389,10 +531,11 @@ program
     .command("open-url <url>")
     .description("Open an Android deep link or URL")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((url, opts) => {
     void runCliAction(opts, async () => {
-        const result = await postSessionJson("/api/open_url", { url }, { port: parseOptionalPort(opts.port) });
+        const result = await postSessionJson("/api/open_url", { url }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, ...result }, `Opened ${url}`);
     });
 });
@@ -400,10 +543,11 @@ program
     .command("stop-app <package>")
     .description("Force-stop an app package")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((packageName, opts) => {
     void runCliAction(opts, async () => {
-        const result = await postSessionJson("/api/stop_app", { packageName }, { port: parseOptionalPort(opts.port) });
+        const result = await postSessionJson("/api/stop_app", { packageName }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, ...result }, `Stopped ${packageName}`);
     });
 });
@@ -411,10 +555,11 @@ program
     .command("clear-app <package>")
     .description("Clear an app package's data")
     .option("-p, --port <port>", "Session port")
+    .option("-d, --device <serial>", "Target device serial")
     .option("-q, --quiet", "JSON output")
     .action((packageName, opts) => {
     void runCliAction(opts, async () => {
-        const result = await postSessionJson("/api/clear_app", { packageName }, { port: parseOptionalPort(opts.port) });
+        const result = await postSessionJson("/api/clear_app", { packageName }, sessionControlOpts(opts));
         printResult(opts.quiet, { ok: true, ...result }, `Cleared ${packageName}`);
     });
 });
@@ -425,11 +570,88 @@ program
     await startMcpServer();
 });
 program.parse();
-async function startDetached(avd, opts) {
+async function resolveSessionTargets(initialDevices, avds, opts, sdk) {
+    let devices = initialDevices;
+    const serials = parseSerialList(opts.device);
+    if (serials.length > 0) {
+        const targets = [];
+        for (const serial of serials) {
+            let target = devices.find((device) => device.serial === serial);
+            if (target?.state === "offline") {
+                if (!opts.quiet)
+                    console.log(`Reconnecting ${target.serial}...`);
+                await reconnectOfflineDevices(sdk, target.serial ?? undefined);
+                devices = await listDevices();
+                target = devices.find((device) => device.serial === serial);
+            }
+            if (!target || !target.serial || target.state !== "running") {
+                throw new Error(`No running target device for serial ${serial}.`);
+            }
+            targets.push({ device: target, bootedByUs: false });
+        }
+        return targets;
+    }
+    const requested = avds.length > 0 ? avds : [undefined];
+    const targets = [];
+    for (const avd of requested) {
+        const resolution = resolveTarget(devices, avd, undefined);
+        let target;
+        let bootedByUs = false;
+        if (resolution.action === "error") {
+            throw new Error(resolution.message);
+        }
+        if (resolution.action === "boot") {
+            if (!opts.quiet)
+                console.log(`Booting ${resolution.avdName}...`);
+            const serial = await bootDevice({
+                sdk,
+                avdName: resolution.avdName,
+                emulatorArgs: emulatorArgs(opts),
+            });
+            devices = await listDevices();
+            target = devices.find((device) => device.serial === serial);
+            bootedByUs = true;
+        }
+        else {
+            target = resolution.device;
+        }
+        if (target?.state === "offline") {
+            if (!opts.quiet)
+                console.log(`Reconnecting ${target.serial}...`);
+            await reconnectOfflineDevices(sdk, target.serial ?? undefined);
+            devices = await listDevices();
+            const reconnected = devices.find((device) => (target?.serial && device.serial === target.serial) ||
+                device.name === target?.name);
+            if (reconnected)
+                target = reconnected;
+        }
+        if (!target || !target.serial || target.state !== "running") {
+            throw new Error("No target device.");
+        }
+        if (!targets.some((entry) => entry.device.serial === target?.serial)) {
+            targets.push({ device: target, bootedByUs });
+        }
+    }
+    return targets;
+}
+function parseSerialList(value) {
+    return value
+        ? value
+            .split(",")
+            .map((serial) => serial.trim())
+            .filter(Boolean)
+        : [];
+}
+function sessionControlOpts(opts) {
+    return {
+        port: parseOptionalPort(opts.port),
+        device: opts.device,
+    };
+}
+async function startDetached(avds, opts) {
     const cliPath = fileURLToPath(import.meta.url);
     const args = [cliPath, "start"];
-    if (avd)
-        args.push(avd);
+    args.push(...avds);
     args.push("--port", opts.port, "--host", opts.host, "--no-preview");
     if (opts.device)
         args.push("--device", opts.device);
@@ -456,24 +678,25 @@ async function startDetached(avd, opts) {
     child.unref();
     const port = parsePort(opts.port);
     const deadline = Date.now() + 120_000;
-    let session;
+    let sessions = [];
+    const expectedSessions = Math.max(1, avds.length, parseSerialList(opts.device).length);
     while (Date.now() < deadline) {
         const state = await readState();
-        session = state.sessions.find((record) => record.port === port && record.pid === child.pid);
-        if (session)
+        sessions = state.sessions.filter((record) => record.port === port && record.pid === child.pid);
+        if (sessions.length >= expectedSessions)
             break;
         await new Promise((resolve) => setTimeout(resolve, 500));
     }
-    if (!session) {
+    if (sessions.length === 0) {
         console.error("Detached server did not become ready before the timeout.");
         process.exit(1);
     }
     if (opts.quiet) {
-        process.stdout.write(JSON.stringify(session) + "\n");
+        process.stdout.write(JSON.stringify(sessions.length === 1 ? sessions[0] : { sessions }) + "\n");
     }
     else {
-        console.log(`Detached Porthole server pid=${session.pid}`);
-        console.log(`Preview: ${session.url}`);
+        console.log(`Detached Porthole server pid=${sessions[0]?.pid}`);
+        console.log(`Preview: ${sessions[0]?.url}`);
     }
 }
 function emulatorArgs(opts) {
@@ -531,6 +754,51 @@ function parsePort(port) {
     }
     return parsed;
 }
+function parseNormalized(value, label) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        throw new Error(`${label} must be a number in 0..1`);
+    }
+    return parsed;
+}
+function parsePositiveNumber(value, label) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${label} must be a positive number`);
+    }
+    return parsed;
+}
+function parsePositiveInteger(value, label) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+    return parsed;
+}
+function parseRatio(value, label) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        throw new Error(`${label} must be a number in 0..1`);
+    }
+    return parsed;
+}
+function parseDurationMs(value) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s)?$/.exec(value);
+    if (!match)
+        throw new Error("duration must look like 1500ms, 30s, or 1500 (ms)");
+    const amount = Number(match[1]);
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new Error("duration must be a positive number");
+    }
+    // Bare numbers are milliseconds, matching every other --duration flag.
+    return Math.round(amount * (match[2] === "s" ? 1000 : 1));
+}
+function isScrollDirection(value) {
+    return value === "up" || value === "down" || value === "left" || value === "right";
+}
+function formatRatio(value) {
+    return `${(value * 100).toFixed(2)}% mismatch`;
+}
 function printResult(quiet, json, text) {
     if (quiet) {
         process.stdout.write(JSON.stringify(json) + "\n");