@fortemate/vega-vvd-driver 0.1.0 → 0.2.0

package/README.md

@@ -59,7 +59,7 @@ vvd record demo.mp4 --seconds 20
 | `vvd press <key…> [--gap 450]`                             | Presses remote keys in order: `up down left right ok back menu playpause rewind fastforward`, a `KEY_*` name or an evdev code. `down*3` repeats, `ok:down` and `ok:up` hold and release |
 | `vvd screenshot [file]`                                    | Saves the screen as a PNG                                                                                                                                                               |
 | `vvd record <file> [--seconds 10] [--fps 30] [--no-audio]` | Records the screen with sound to an MP4. Needs ffmpeg                                                                                                                                   |
-| `vvd frames <dir> [--seconds 3]`                           | Saves every distinct frame as a PNG, named by the emulator's time                                                                                                                       |
+| `vvd frames <dir> [--seconds 3] [--max-frames 200]`        | Saves every distinct frame as a PNG, named by the emulator's time. The frames wait in memory until the capture ends: 6 MB each at the VVD's 1920x1080, and 2 GB at most                 |
 | `vvd wait-change [--timeout 5000]`                         | Exits 0 once the screen changes, 1 on timeout                                                                                                                                           |
 | `vvd safe-area [--background #rrggbb] [--margin 0.05]`     | Counts what sits in the outer 5% of each edge. Exits 0 when clear                                                                                                                       |
 | `vvd mcp`                                                  | Runs the MCP server on stdio                                                                                                                                                            |
@@ -110,7 +110,7 @@ device.close();
 
 ## Recipes
 
-**Check an animation.** Start `vvd frames ./frames --seconds 3`, then trigger the animation. Each distinct frame lands as a PNG named by the emulator's own clock. On the VVD, a 220 ms move slide in Dice Chess came through as 10 to 11 frames.
+**Check an animation.** Start `vvd frames ./frames --seconds 3`, then trigger the animation. Each distinct frame lands as a PNG named by the emulator's own clock. The frames wait in memory while the capture runs, about 6 MB each at 1080p, and are written when it ends, because encoding one takes 20 to 200 ms and the screen would go unwatched meanwhile. The capture stops at 200 frames, about 1.2 GB, unless `--max-frames` says otherwise, and in any case before the frames held pass 2 GB, 321 frames at 1080p; the frames it has are written either way. On the VVD on 28 September 2026, with SDK 0.24.12112, the 220 ms pawn slide of Dice Chess's first tutorial move came through with the pawn in flight in 4 to 6 frames, 23 to 55 ms apart. A screenshot takes longer while the screen changes, and that sets the pace.
 
 **Record a demo.** Script the presses, record while they run, and cut the best takes afterwards. Recording works without the device's window.
 
@@ -129,7 +129,7 @@ Measured on the VVD with Vega SDK 0.24.12112 on macOS:
 - **Keys.** The emulator's gRPC `sendKey`, with Linux evdev codes, reaches apps: it is the path the VVD's own on-screen remote uses. OK is `KEY_KPENTER`, and apps receive it as `kpenter`, not the `select` the remote's documentation names. `KEY_SELECT` and `KEY_OK` never arrive, because the emulator's virtual keyboard does not declare them. Back is `KEY_BACK`; `KEY_ESC` does not reach an app as Back.
 - **Dead ends.** The emulator console's `event send`, QEMU's `send-key` and `inputd-cli` on the device all report success and never reach an app.
 - **Home cannot be sent.** `KEY_HOMEPAGE` (172), `KEY_F1` and 170, the code Amazon's Appium documentation gives for Home, all leave the app on screen. To get back to the launcher, run `vega device launch-app -d VirtualDevice -a com.amazon.keplerlauncherapp.main`.
-- **Screenshots.** `getScreenshot` returns 1920x1080. A running process polls it at about 90 screenshots a second; `vvd screenshot` takes about half a second, most of it starting up. The emulator's `streamScreenshot` has delivered only its first frame while the screen kept changing, so the driver polls instead.
+- **Screenshots.** `getScreenshot` returns 1920x1080. A running process polls it in RGB at about 57 screenshots a second of a still screen, 17 ms each, and at 16 to 43 a second while the screen changes, 23 to 61 ms each (measured on 28 September 2026). `vvd screenshot` takes about half a second, most of it starting up. The emulator's `streamScreenshot` has delivered only its first frame while the screen kept changing, so the driver polls instead.
 - **Audio.** `streamAudio` sends nothing while the device is silent. `record` rebuilds the track on the video's clock from each packet's capture time and fills the gaps with silence, so a sound effect stays in sync.
 - **gRPC.** The endpoint is off after every start of the VVD, and the discovery file that the driver reads appears only once `grpc <port>` has been sent to the console. `vvd enable-grpc` does that.
 

package/dist/bin.js

@@ -2,12 +2,14 @@
 // The executable behind `vvd`. Kept apart from cli.ts so that the tests can
 // import the command line without running it.
 import { main } from "./cli.js";
-main(process.argv.slice(2)).then((code) => {
+try {
+    const code = await main(process.argv.slice(2));
     // -1: a long-running command (the MCP server) that exits on its own.
     if (code >= 0)
         process.exitCode = code;
-}, (error) => {
+}
+catch (error) {
     // 2, so that scripts can tell an error from wait-change's "no change".
     console.error(`vvd: ${error.message ?? String(error)}`);
     process.exitCode = 2;
-});
+}

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+import { Device } from './device.ts';
 export declare const USAGE: string;
 export type Parsed = {
     command: string | undefined;
@@ -8,6 +9,7 @@ export type Parsed = {
         'console-port'?: string;
         gap?: string;
         seconds?: string;
+        'max-frames'?: string;
         fps?: string;
         'no-audio'?: boolean;
         timeout?: string;
@@ -23,4 +25,15 @@ export declare const numberOption: (value: string | undefined, name: string, fal
     max?: number | undefined;
     integer?: boolean | undefined;
 }) => number;
+export declare const MAX_FRAMES = 200;
+export declare const MAX_BYTES = 2000000000;
+export declare const saveFrames: (device: Device, dir: string, options: {
+    durationMs: number;
+    maxFrames?: number;
+    maxBytes?: number;
+    encode?: (width: number, height: number, rgb: Buffer) => Buffer;
+}) => Promise<{
+    count: number;
+    stopped: "max-frames" | "memory" | undefined;
+}>;
 export declare const main: (argv: readonly string[]) => Promise<number>;

package/dist/cli.js

@@ -30,8 +30,11 @@ Commands:
       --seconds <n>          default 10
       --fps <n>              default 30
       --no-audio             video only
-  frames <dir>               save every distinct frame as a PNG, to check animations
+  frames <dir>               save every distinct frame as a PNG, to check animations;
+                             frames wait in memory until the capture ends, 6 MB each
+                             at 1080p, and it stops before they pass 2 GB
       --seconds <n>          default 3
+      --max-frames <n>       stop after this many frames, default 200
   wait-change                exit 0 once the screen changes, 1 on a timeout
       --timeout <ms>         default 5000
   safe-area                  check the outer 5% of the screen against the background;
@@ -59,6 +62,7 @@ export const parseCli = (argv) => {
             'console-port': { type: 'string' },
             gap: { type: 'string' },
             seconds: { type: 'string' },
+            'max-frames': { type: 'string' },
             fps: { type: 'string' },
             'no-audio': { type: 'boolean' },
             timeout: { type: 'string' },
@@ -84,6 +88,170 @@ export const numberOption = (value, name, fallback, { min = 0, max = Number.MAX_
     return parsed;
 };
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
+// How many frames `vvd frames` holds by default: about 1.2 GB at 1080p.
+export const MAX_FRAMES = 200;
+// The most memory the held frames may take, whatever --max-frames says and
+// whatever the screen's size: 321 frames at 1080p.
+export const MAX_BYTES = 2_000_000_000;
+// Captures every distinct frame for `durationMs`, then writes each to `dir`
+// as frame-<ms>ms.png, the milliseconds on the emulator's clock from the
+// first frame. The frames wait in memory until the capture is over: encoding
+// one at 1080p takes 20 to 200 ms, and the next screenshot would wait for it.
+// The capture stops after `maxFrames`, or before the frames held would pass
+// `maxBytes`; the frames it has are written either way.
+export const saveFrames = async (device, dir, options) => {
+    const { durationMs, maxFrames = MAX_FRAMES, maxBytes = MAX_BYTES, encode = encodePng, } = options;
+    const held = [];
+    let bytes = 0;
+    // Fires at the first frame that does not fit, which is not kept: frames can
+    // differ in size, so each one is checked as it comes.
+    const full = new AbortController();
+    try {
+        await device.frames(durationMs, (frame) => {
+            if (bytes + frame.data.length > maxBytes) {
+                full.abort();
+                return;
+            }
+            held.push(frame);
+            bytes += frame.data.length;
+        }, { maxFrames, signal: full.signal });
+    }
+    catch (error) {
+        if (!full.signal.aborted)
+            throw error;
+    }
+    const first = held[0]?.timestampUs ?? 0;
+    for (const frame of held) {
+        const ms = Math.round((frame.timestampUs - first) / 1000);
+        writeFileSync(join(dir, `frame-${String(ms).padStart(6, '0')}ms.png`), encode(frame.width, frame.height, frame.data));
+    }
+    let stopped;
+    if (full.signal.aborted)
+        stopped = 'memory';
+    else if (held.length >= maxFrames)
+        stopped = 'max-frames';
+    return { count: held.length, stopped };
+};
+// Connects to the device, runs `body` with it, and lets go of the device
+// however `body` ends.
+const withDevice = async (pid, body) => {
+    const device = Device.connect({ pid });
+    try {
+        return await body(device);
+    }
+    finally {
+        device.close();
+    }
+};
+// The commands by name, each returning its exit status. Options are checked
+// before a device is looked for.
+const COMMANDS = {
+    devices({ pid }) {
+        const devices = findEmulators({ pid });
+        if (devices.length === 0) {
+            console.log('No running Vega Virtual Device with gRPC on. Start one, then run: vvd enable-grpc');
+            return 1;
+        }
+        for (const d of devices)
+            console.log(`pid ${d.pid}  grpc ${d.grpcPort}  console ${d.consolePort ?? '-'}  ${d.avdName ?? ''}`.trimEnd());
+        return 0;
+    },
+    async 'enable-grpc'({ values, pid }) {
+        if (pid !== undefined)
+            throw new Error('enable-grpc talks to an emulator console, not to a pid: use --console-port');
+        const port = numberOption(values.port, 'port', 8554, {
+            min: 1024,
+            max: 65535,
+        });
+        const consolePort = numberOption(values['console-port'], 'console-port', 5554, { min: 5554, max: 5682 });
+        await enableGrpc(port, { port: consolePort });
+        console.log(`gRPC is on at port ${port}.`);
+        return 0;
+    },
+    async press({ positionals, values, pid }) {
+        if (positionals.length === 0)
+            throw new Error('press needs at least one key, for example: vvd press down ok');
+        const steps = parseKeys(positionals); // fails before connecting on a typo
+        const gapMs = numberOption(values.gap, 'gap', 450, { max: 60000 });
+        await withDevice(pid, (device) => device.press(steps, { gapMs }));
+        return 0;
+    },
+    async screenshot({ positionals, pid }) {
+        const file = positionals[0] ?? `vvd-${stamp()}.png`;
+        const frame = await withDevice(pid, (device) => device.screenshot('png'));
+        writeFileSync(file, frame.data);
+        console.log(file);
+        return 0;
+    },
+    async record({ positionals, values, pid }) {
+        const file = positionals[0];
+        if (!file)
+            throw new Error('record needs a file, for example: vvd record demo.mp4 --seconds 20');
+        const options = {
+            file,
+            seconds: numberOption(values.seconds, 'seconds', 10, {
+                min: 1,
+                max: 3600,
+                integer: false,
+            }),
+            fps: numberOption(values.fps, 'fps', 30, { min: 1, max: 60 }),
+            audio: !values['no-audio'],
+        };
+        const result = await withDevice(pid, (device) => record(device, options));
+        console.log(`${result.file}: ${result.frames} frames, ${result.audioSeconds.toFixed(1)} s of audio`);
+        return 0;
+    },
+    async frames({ positionals, values, pid }) {
+        const dir = positionals[0];
+        if (!dir)
+            throw new Error('frames needs a directory, for example: vvd frames ./frames --seconds 3');
+        const seconds = numberOption(values.seconds, 'seconds', 3, {
+            min: 0.1,
+            max: 600,
+            integer: false,
+        });
+        const maxFrames = numberOption(values['max-frames'], 'max-frames', MAX_FRAMES, { min: 1, max: 10_000 });
+        mkdirSync(dir, { recursive: true });
+        const { count, stopped } = await withDevice(pid, (device) => saveFrames(device, dir, { durationMs: seconds * 1000, maxFrames }));
+        const why = {
+            'max-frames': `stopped at --max-frames ${maxFrames}`,
+            memory: `stopped at ${MAX_BYTES / 1e9} GB of frames in memory`,
+        };
+        console.log(stopped
+            ? `${count} distinct frames in ${dir}: ${why[stopped]} before the ${seconds} s were up`
+            : `${count} distinct frames in ${dir}`);
+        return 0;
+    },
+    async 'wait-change'({ values, pid }) {
+        const timeoutMs = numberOption(values.timeout, 'timeout', 5000, {
+            min: 1,
+            max: 3_600_000,
+        });
+        const changed = await withDevice(pid, (device) => device.waitForChange({ timeoutMs }));
+        console.log(changed ? 'changed' : 'no change');
+        return changed ? 0 : 1;
+    },
+    async 'safe-area'({ values, pid }) {
+        const options = {
+            background: values.background
+                ? parseColour(values.background)
+                : undefined,
+            margin: numberOption(values.margin, 'margin', 0.05, {
+                min: 0.01,
+                max: 0.25,
+                integer: false,
+            }),
+        };
+        const frame = await withDevice(pid, (device) => device.screenshot('rgb'));
+        const report = checkSafeArea(frame.data, frame.width, frame.height, options);
+        console.log(`${report.clear ? 'clear' : 'NOT clear'}: left=${report.left} right=${report.right} top=${report.top} bottom=${report.bottom} (background ${formatColour(report.background)})`);
+        return report.clear ? 0 : 1;
+    },
+    async mcp({ pid }) {
+        await serveStdio({ pid });
+        return -1; // keeps running until the client disconnects
+    },
+};
 export const main = async (argv) => {
     const { command, positionals, values } = parseCli(argv);
     if (values.version) {
@@ -97,146 +265,8 @@ export const main = async (argv) => {
     const pid = values.pid === undefined
         ? undefined
         : numberOption(values.pid, 'pid', 0, { min: 1 });
-    const connect = () => Device.connect({ pid });
-    switch (command) {
-        case 'devices': {
-            const devices = findEmulators({ pid });
-            if (devices.length === 0) {
-                console.log('No running Vega Virtual Device with gRPC on. Start one, then run: vvd enable-grpc');
-                return 1;
-            }
-            for (const d of devices)
-                console.log(`pid ${d.pid}  grpc ${d.grpcPort}  console ${d.consolePort ?? '-'}  ${d.avdName ?? ''}`.trimEnd());
-            return 0;
-        }
-        case 'enable-grpc': {
-            if (pid !== undefined)
-                throw new Error('enable-grpc talks to an emulator console, not to a pid: use --console-port');
-            const port = numberOption(values.port, 'port', 8554, {
-                min: 1024,
-                max: 65535,
-            });
-            const consolePort = numberOption(values['console-port'], 'console-port', 5554, { min: 5554, max: 5682 });
-            await enableGrpc(port, { port: consolePort });
-            console.log(`gRPC is on at port ${port}.`);
-            return 0;
-        }
-        case 'press': {
-            if (positionals.length === 0)
-                throw new Error('press needs at least one key, for example: vvd press down ok');
-            const steps = parseKeys(positionals); // fails before connecting on a typo
-            const device = connect();
-            try {
-                await device.press(steps, {
-                    gapMs: numberOption(values.gap, 'gap', 450, { max: 60000 }),
-                });
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'screenshot': {
-            const file = positionals[0] ?? `vvd-${stamp()}.png`;
-            const device = connect();
-            try {
-                const frame = await device.screenshot('png');
-                writeFileSync(file, frame.data);
-                console.log(file);
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'record': {
-            const file = positionals[0];
-            if (!file)
-                throw new Error('record needs a file, for example: vvd record demo.mp4 --seconds 20');
-            const device = connect();
-            try {
-                const result = await record(device, {
-                    file,
-                    seconds: numberOption(values.seconds, 'seconds', 10, {
-                        min: 1,
-                        max: 3600,
-                        integer: false,
-                    }),
-                    fps: numberOption(values.fps, 'fps', 30, { min: 1, max: 60 }),
-                    audio: !values['no-audio'],
-                });
-                console.log(`${result.file}: ${result.frames} frames, ${result.audioSeconds.toFixed(1)} s of audio`);
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'frames': {
-            const dir = positionals[0];
-            if (!dir)
-                throw new Error('frames needs a directory, for example: vvd frames ./frames --seconds 3');
-            mkdirSync(dir, { recursive: true });
-            const device = connect();
-            try {
-                let first;
-                const count = await device.frames(numberOption(values.seconds, 'seconds', 3, {
-                    min: 0.1,
-                    max: 600,
-                    integer: false,
-                }) * 1000, (frame) => {
-                    first ??= frame.timestampUs;
-                    const ms = Math.round((frame.timestampUs - first) / 1000);
-                    writeFileSync(join(dir, `frame-${String(ms).padStart(6, '0')}ms.png`), encodePng(frame.width, frame.height, frame.data));
-                });
-                console.log(`${count} distinct frames in ${dir}`);
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'wait-change': {
-            const device = connect();
-            try {
-                const changed = await device.waitForChange({
-                    timeoutMs: numberOption(values.timeout, 'timeout', 5000, {
-                        min: 1,
-                        max: 3_600_000,
-                    }),
-                });
-                console.log(changed ? 'changed' : 'no change');
-                return changed ? 0 : 1;
-            }
-            finally {
-                device.close();
-            }
-        }
-        case 'safe-area': {
-            const device = connect();
-            try {
-                const frame = await device.screenshot('rgb');
-                const report = checkSafeArea(frame.data, frame.width, frame.height, {
-                    background: values.background
-                        ? parseColour(values.background)
-                        : undefined,
-                    margin: numberOption(values.margin, 'margin', 0.05, {
-                        min: 0.01,
-                        max: 0.25,
-                        integer: false,
-                    }),
-                });
-                console.log(`${report.clear ? 'clear' : 'NOT clear'}: left=${report.left} right=${report.right} top=${report.top} bottom=${report.bottom} (background ${formatColour(report.background)})`);
-                return report.clear ? 0 : 1;
-            }
-            finally {
-                device.close();
-            }
-        }
-        case 'mcp':
-            await serveStdio({ pid });
-            return -1; // keeps running until the client disconnects
-        default:
-            throw new Error(`unknown command "${command}". Run vvd --help.`);
-    }
+    // Own names only, so that "constructor" and the like are not commands.
+    if (!Object.hasOwn(COMMANDS, command))
+        throw new Error(`unknown command "${command}". Run vvd --help.`);
+    return COMMANDS[command]({ positionals, values, pid });
 };

package/dist/device.d.ts

@@ -42,6 +42,7 @@ export declare class Device {
     }): Promise<boolean>;
     frames(durationMs: number, onFrame: (frame: Frame) => void | Promise<void>, options?: {
         intervalMs?: number;
+        maxFrames?: number;
         signal?: AbortSignal;
     }): Promise<number>;
     listen(): () => AudioPacket[];

package/dist/device.js

@@ -154,10 +154,21 @@ export class Device {
         }
         return false;
     }
-    // Calls `onFrame` with every distinct frame for `durationMs`. Useful to
-    // check an animation: a 220 ms slide comes through as about ten frames.
+    // Calls `onFrame` with every distinct frame for `durationMs`, or until
+    // `maxFrames` of them have come; `maxFrames` is a whole number from 1, and
+    // anything else is refused before the first screenshot. Useful to check an
+    // animation: on the VVD a screenshot takes 23 to 61 ms while the screen
+    // changes, and a 220 ms slide comes through as 4 to 6 frames.
+    //
+    // The next screenshot waits for `onFrame`, so keep it quick: encoding a
+    // 1080p PNG takes 20 to 200 ms, and frames that come meanwhile are missed.
+    // Hold the frames and save them once the capture is over, as `vvd frames`
+    // does; `maxFrames` bounds the memory, about 6 MB a frame at 1080p.
     async frames(durationMs, onFrame, options = {}) {
-        const { signal } = options;
+        const { signal, maxFrames = Infinity } = options;
+        const whole = Number.isInteger(maxFrames) && maxFrames >= 1;
+        if (!whole && maxFrames !== Infinity)
+            throw new RangeError(`maxFrames must be a whole number from 1, not ${maxFrames}`);
         const endMs = Date.now() + durationMs;
         let previous;
         let count = 0;
@@ -169,6 +180,8 @@ export class Device {
                 previous = frame.data;
                 count += 1;
                 await onFrame(frame);
+                if (count >= maxFrames)
+                    break;
             }
             if (options.intervalMs)
                 await sleep(options.intervalMs, undefined, { signal });

package/dist/discovery.js

@@ -58,41 +58,43 @@ const toPort = (value) => {
     const port = Number(value);
     return Number.isInteger(port) && port > 0 ? port : undefined;
 };
+// The emulator a discovery file describes, or undefined when the file names
+// no gRPC port.
+const readEmulator = (file, pid) => {
+    const fields = parseDiscovery(readFileSync(file, 'utf8'));
+    const grpcPort = toPort(fields.get('grpc.port'));
+    if (grpcPort === undefined)
+        return undefined;
+    return Object.defineProperty({
+        pid,
+        file,
+        grpcPort,
+        consolePort: toPort(fields.get('port.serial')),
+        avdName: fields.get('avd.name') || undefined,
+    }, 'grpcToken', { value: fields.get('grpc.token') || undefined, enumerable: false });
+};
 // The running emulators with gRPC on, newest first. Stale files left by an
 // emulator that has exited are skipped.
 export const findEmulators = (options = {}) => {
     const alive = options.alive ?? isAlive;
+    const wanted = (pid) => (options.pid === undefined || pid === options.pid) && alive(pid);
     const found = [];
     for (const directory of options.directories ?? runningDirectories()) {
         if (!existsSync(directory))
             continue;
         for (const name of readdirSync(directory)) {
-            const match = /^pid_(\d+)\.ini$/.exec(name);
-            if (!match)
-                continue;
-            const pid = Number(match[1]);
-            if (options.pid !== undefined && pid !== options.pid)
-                continue;
-            if (!alive(pid))
+            // NaN for a name that is no discovery file.
+            const pid = Number(/^pid_(\d+)\.ini$/.exec(name)?.[1]);
+            if (Number.isNaN(pid) || !wanted(pid))
                 continue;
             const file = join(directory, name);
-            const fields = parseDiscovery(readFileSync(file, 'utf8'));
-            const grpcPort = toPort(fields.get('grpc.port'));
-            if (grpcPort === undefined)
-                continue;
-            const emulator = Object.defineProperty({
-                pid,
-                file,
-                grpcPort,
-                consolePort: toPort(fields.get('port.serial')),
-                avdName: fields.get('avd.name') || undefined,
-            }, 'grpcToken', { value: fields.get('grpc.token') || undefined, enumerable: false });
-            found.push({ emulator, modified: statSync(file).mtimeMs });
+            const emulator = readEmulator(file, pid);
+            if (emulator)
+                found.push({ emulator, modified: statSync(file).mtimeMs });
         }
     }
-    return found
-        .sort((a, b) => b.modified - a.modified)
-        .map(({ emulator }) => emulator);
+    found.sort((a, b) => b.modified - a.modified);
+    return found.map(({ emulator }) => emulator);
 };
 export class NoDeviceError extends Error {
     constructor() {

package/dist/mcp.js

@@ -40,6 +40,8 @@ export const videoPath = (file, overwrite = false) => {
         throw new Error(`${path} exists; set overwrite to replace it`);
     return path;
 };
+// The same emulator, serving the same endpoint with the same token.
+const sameEndpoint = (a, b) => a.pid === b.pid && a.grpcPort === b.grpcPort && a.grpcToken === b.grpcToken;
 export const createServer = (options = {}) => {
     const server = new McpServer({ name: 'vega-vvd-driver', version: VERSION });
     const find = { pid: options.pid, directories: options.directories };
@@ -48,13 +50,7 @@ export const createServer = (options = {}) => {
     let device;
     const connected = () => {
         const [newest] = findEmulators(find);
-        const current = device?.emulator;
-        if (device &&
-            current &&
-            newest &&
-            current.pid === newest.pid &&
-            current.grpcPort === newest.grpcPort &&
-            current.grpcToken === newest.grpcToken)
+        if (device && newest && sameEndpoint(device.emulator, newest))
             return device;
         device?.close();
         device = undefined; // a failed connect below must not leave it cached

package/dist/record.js

@@ -4,10 +4,11 @@
 // Frames are polled with getScreenshot and written to ffmpeg at a fixed frame
 // rate, repeating the latest frame when the screen is still. The emulator's
 // streamScreenshot was tried first and can stop delivering frames while the
-// screen keeps changing; polling keeps up at about 90 screenshots a second at
-// 1080p. The audio comes from streamAudio. The emulator sends nothing while
-// the device is silent, so the track is rebuilt on the video's clock from each
-// packet's capture time, with silence in the gaps.
+// screen keeps changing. Polling does not stop: on the VVD a 1080p screenshot
+// takes about 17 ms, or 23 to 61 ms while the screen changes. The audio comes
+// from streamAudio. The emulator sends nothing while the device is silent, so
+// the track is rebuilt on the video's clock from each packet's capture time,
+// with silence in the gaps.
 //
 // However a recording ends, it cleans up after itself: ffmpeg is stopped, the
 // audio stream is cancelled and the working directory is removed.
@@ -244,7 +245,7 @@ export const record = async (device, options) => {
     }
     finally {
         stopAudio?.();
-        if (encoder && encoder.exitCode === null && encoder.signalCode === null) {
+        if (encoder?.exitCode === null && encoder.signalCode === null) {
             encoder.stdin.destroy();
             encoder.kill('SIGKILL');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fortemate/vega-vvd-driver",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Unofficial driver for the Vega Virtual Device: remote keys, screenshots and video with sound, from scripts and AI agents. CLI, Node library and MCP server.",
   "keywords": [
     "vega",
@@ -46,6 +46,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "node --test test/*.test.ts",
+    "coverage": "node -e \"require('node:fs').mkdirSync('coverage', { recursive: true })\" && node --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info test/*.test.ts",
     "test:device": "VVD_INTEGRATION=1 node --test test/device.test.ts",
     "prepare": "npm run build"
   },