@fortemate/vega-vvd-driver 0.1.0

package/dist/mcp.js

@@ -0,0 +1,273 @@
+// An MCP server over stdio, so that an AI coding agent can drive the VVD and
+// see what it did: press remote keys, look at the screen, wait for it to
+// change, record a video and check the TV safe area.
+//
+// A model chooses the arguments, so they are bounded: how many keys a call
+// presses, how long it waits or records, and which files it may write. A call
+// that the client cancels stops.
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { enableGrpc } from "./console.js";
+import { Device } from "./device.js";
+import { findEmulators } from "./discovery.js";
+import { parseKeys } from "./keys.js";
+import { record } from "./record.js";
+import { checkSafeArea, formatColour, parseColour } from "./safearea.js";
+import { VERSION } from "./version.js";
+// Presses per call: 100 at the default gap take about 54 seconds.
+export const MAX_PRESSES = 100;
+const text = (value) => ({
+    content: [{ type: 'text', text: value }],
+});
+const failure = (error) => ({
+    isError: true,
+    content: [{ type: 'text', text: error.message ?? String(error) }],
+});
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// A path a model may record to: a local file with a video extension, and not
+// one that exists unless it asks to replace it. Relative paths resolve against
+// the server's working directory.
+export const videoPath = (file, overwrite = false) => {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(file))
+        throw new Error('file must be a local path, not a URL');
+    const path = resolve(file);
+    if (!/\.(mp4|mov|mkv)$/i.test(path))
+        throw new Error('file must end in .mp4, .mov or .mkv');
+    if (!overwrite && existsSync(path))
+        throw new Error(`${path} exists; set overwrite to replace it`);
+    return path;
+};
+export const createServer = (options = {}) => {
+    const server = new McpServer({ name: 'vega-vvd-driver', version: VERSION });
+    const find = { pid: options.pid, directories: options.directories };
+    // One connection, kept while the same emulator serves the same endpoint; a
+    // restarted VVD, or gRPC turned on again, gets a new one.
+    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)
+            return device;
+        device?.close();
+        device = undefined; // a failed connect below must not leave it cached
+        device = Device.connect({
+            ...find,
+            protoDirectory: options.protoDirectory,
+        });
+        return device;
+    };
+    const screen = async (d, signal) => {
+        const frame = await d.screenshot('png', { signal });
+        return {
+            type: 'image',
+            data: frame.data.toString('base64'),
+            mimeType: 'image/png',
+        };
+    };
+    server.registerTool('list_devices', {
+        title: 'List running Vega Virtual Devices',
+        description: 'Lists the running Vega Virtual Devices whose gRPC endpoint is on. An empty list usually means gRPC is off: call enable_grpc.',
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const devices = findEmulators({ directories: options.directories }).map(({ pid, grpcPort, consolePort, avdName }) => ({
+            pid,
+            grpcPort,
+            consolePort,
+            avdName,
+        }));
+        return text(JSON.stringify(devices, null, 2));
+    });
+    server.registerTool('enable_grpc', {
+        title: 'Turn on the emulator gRPC endpoint',
+        description: 'Turns on the gRPC endpoint of a running Vega Virtual Device through its emulator console. It is off after every start of the device, and nothing else here works until it is on.',
+        inputSchema: {
+            grpc_port: z
+                .number()
+                .int()
+                .min(1024)
+                .max(65535)
+                .optional()
+                .describe('Default 8554'),
+            console_port: z
+                .number()
+                .int()
+                .min(5554)
+                .max(5682)
+                .multipleOf(2)
+                .optional()
+                .describe('The emulator console, an even port; default 5554'),
+        },
+    }, async ({ grpc_port, console_port }) => {
+        try {
+            await enableGrpc(grpc_port ?? 8554, { port: console_port });
+            const found = () => findEmulators({ directories: options.directories }).length;
+            for (let i = 0; i < 20 && found() === 0; i++)
+                await sleep(250);
+            return text(found()
+                ? `gRPC is on at port ${grpc_port ?? 8554}.`
+                : 'The console accepted the command, but no discovery file appeared yet.');
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool('press_keys', {
+        title: 'Press remote keys',
+        description: `Presses TV remote keys in order: up, down, left, right, ok, back, menu, playpause, rewind, fastforward, a KEY_* name or an evdev code. Append *N to repeat (down*3), :down or :up to hold or release. At most ${MAX_PRESSES} presses per call. Home cannot be pressed on the Virtual Device. Set screenshot_after to see the result.`,
+        inputSchema: {
+            keys: z
+                .array(z.string().min(1).max(40))
+                .min(1)
+                .max(50)
+                .describe('For example ["down", "down", "ok"]'),
+            gap_ms: z
+                .number()
+                .int()
+                .min(0)
+                .max(10000)
+                .optional()
+                .describe('Pause after each key, default 450'),
+            screenshot_after: z
+                .boolean()
+                .optional()
+                .describe('Return a screenshot once the keys are pressed'),
+        },
+    }, async ({ keys, gap_ms, screenshot_after }, { signal }) => {
+        try {
+            const steps = parseKeys(keys); // a typo fails before any device is touched
+            if (steps.length > MAX_PRESSES)
+                throw new Error(`${steps.length} presses asked for; at most ${MAX_PRESSES} per call`);
+            const d = connected();
+            await d.press(steps, { gapMs: gap_ms, signal });
+            const done = text(`Pressed ${keys.join(' ')}.`);
+            if (screenshot_after)
+                done.content.push(await screen(d, signal));
+            return done;
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool('screenshot', {
+        title: 'Take a screenshot',
+        description: 'Returns the current screen of the Vega Virtual Device as a PNG image (1920x1080).',
+        annotations: { readOnlyHint: true },
+    }, async ({ signal }) => {
+        try {
+            return { content: [await screen(connected(), signal)] };
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool('wait_for_change', {
+        title: 'Wait until the screen changes',
+        description: 'Waits until the screen differs from how it looked when the call began, for example after starting an app or while the app is thinking. Returns whether it changed, with a screenshot.',
+        inputSchema: {
+            timeout_ms: z
+                .number()
+                .int()
+                .min(100)
+                .max(120000)
+                .optional()
+                .describe('Default 5000'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ timeout_ms }, { signal }) => {
+        try {
+            const d = connected();
+            const changed = await d.waitForChange({
+                timeoutMs: timeout_ms,
+                signal,
+            });
+            const result = text(changed
+                ? 'The screen changed.'
+                : 'The screen did not change before the timeout.');
+            result.content.push(await screen(d, signal));
+            return result;
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool('record_video', {
+        title: 'Record a video with sound',
+        description: 'Records the screen and the sound of the Vega Virtual Device to a video file, at 1080p. Needs ffmpeg on the PATH. Blocks for the whole duration; cancelling the call stops the recording.',
+        inputSchema: {
+            file: z
+                .string()
+                .min(1)
+                .max(1024)
+                .describe("A local .mp4, .mov or .mkv path, absolute or relative to the server's working directory"),
+            seconds: z.number().min(1).max(600),
+            fps: z.number().int().min(1).max(60).optional().describe('Default 30'),
+            audio: z.boolean().optional().describe('Default true'),
+            overwrite: z
+                .boolean()
+                .optional()
+                .describe('Replace an existing file; default false'),
+        },
+    }, async ({ file, seconds, fps, audio, overwrite }, { signal }) => {
+        try {
+            const path = videoPath(file, overwrite);
+            const result = await record(connected(), {
+                file: path,
+                seconds,
+                fps,
+                audio,
+                signal,
+            });
+            return text(`Recorded ${result.file}: ${result.frames} frames, ${result.audioSeconds.toFixed(1)} s of audio.`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool('check_safe_area', {
+        title: 'Check the TV safe area',
+        description: 'Counts the pixels in the outer margin of the screen (5% of each edge by default) that differ from the background. Fire TV guidance keeps content out of that margin, which a television may crop.',
+        inputSchema: {
+            background: z
+                .string()
+                .max(7)
+                .optional()
+                .describe('#rrggbb; the most common margin colour by default'),
+            margin: z
+                .number()
+                .min(0.01)
+                .max(0.25)
+                .optional()
+                .describe('Fraction of each edge, default 0.05'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ background, margin }, { signal }) => {
+        try {
+            const frame = await connected().screenshot('rgb', { signal });
+            const report = checkSafeArea(frame.data, frame.width, frame.height, {
+                background: background ? parseColour(background) : undefined,
+                margin,
+            });
+            return text(`${report.clear ? 'Clear' : 'Not clear'}: left ${report.left}, right ${report.right}, top ${report.top}, bottom ${report.bottom} pixels differ from ${formatColour(report.background)}.`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    // Let go of the device when the client goes away.
+    server.server.onclose = () => {
+        device?.close();
+        device = undefined;
+    };
+    return server;
+};
+export const serveStdio = async (options = {}) => {
+    await createServer(options).connect(new StdioServerTransport());
+};

package/dist/png.d.ts

@@ -0,0 +1 @@
+export declare const encodePng: (width: number, height: number, rgb: Buffer) => Buffer;

package/dist/png.js

@@ -0,0 +1,49 @@
+// A minimal PNG encoder for RGB888 frames, so that frames can be saved
+// without an image library: one IHDR chunk, the rows deflated with no filter,
+// and IEND.
+import { deflateSync } from 'node:zlib';
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+const crc32 = (bytes) => {
+    let crc = 0xffffffff;
+    for (const byte of bytes)
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+};
+const chunk = (type, data) => {
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(body));
+    return Buffer.concat([length, body, crc]);
+};
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export const encodePng = (width, height, rgb) => {
+    const stride = width * 3;
+    if (rgb.length < stride * height)
+        throw new Error(`expected ${width}x${height} RGB data, got ${rgb.length} bytes`);
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8; // bits per channel
+    header[9] = 2; // colour type: RGB
+    // compression, filter and interlace methods stay 0
+    const raw = Buffer.alloc((stride + 1) * height);
+    for (let y = 0; y < height; y++)
+        rgb.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+    return Buffer.concat([
+        SIGNATURE,
+        chunk('IHDR', header),
+        chunk('IDAT', deflateSync(raw, { level: 6 })),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+};

package/dist/record.d.ts

@@ -0,0 +1,19 @@
+import { type AudioPacket, type Device } from './device.ts';
+export type RecordOptions = {
+    file: string;
+    seconds: number;
+    fps?: number;
+    audio?: boolean;
+    onStart?: () => void | Promise<void>;
+    signal?: AbortSignal;
+};
+export type RecordResult = {
+    file: string;
+    frames: number;
+    screenshots: number;
+    audioSeconds: number;
+};
+export declare const assembleAudio: (packets: readonly AudioPacket[], startUs: number, seconds: number) => Buffer;
+export declare const audioWithin: (packets: readonly AudioPacket[], startUs: number, seconds: number) => number;
+export declare const hasFfmpeg: () => Promise<boolean>;
+export declare const record: (device: Device, options: RecordOptions) => Promise<RecordResult>;

package/dist/record.js

@@ -0,0 +1,254 @@
+// Recording the VVD's screen, with its sound, to a video file. Needs ffmpeg on
+// the PATH.
+//
+// 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.
+//
+// However a recording ends, it cleans up after itself: ffmpeg is stopped, the
+// audio stream is cancelled and the working directory is removed.
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { accessSync, constants, mkdtempSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CALL_TIMEOUT_MS } from "./device.js";
+// Settles when the process has ended: resolves on exit code 0, and otherwise
+// rejects with the end of what it wrote to stderr.
+const ended = (child, name) => new Promise((resolve, reject) => {
+    let stderr = '';
+    child.stderr.on('data', (chunk) => (stderr += chunk.toString()));
+    child.on('error', reject);
+    child.on('close', (code, signal) => code === 0
+        ? resolve()
+        : reject(new Error(`${name} exited with ${code ?? signal}: ${stderr.trim().slice(-500)}`)));
+});
+const run = (command, args, signal) => ended(spawn(command, args, { stdio: ['ignore', 'ignore', 'pipe'], signal }), command);
+// Waits for a promise, or rejects as soon as the signal fires.
+const abortable = (promise, signal) => {
+    if (!signal)
+        return promise;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+};
+const SAMPLE_RATE = 44100;
+const FRAME_BYTES = 4; // 16-bit stereo
+// Lays audio packets on a timeline that starts at `startUs` and lasts
+// `seconds`, as 16-bit stereo PCM: silence where nothing arrived, and a packet
+// that starts earlier than the audio before it overwrites the overlap. Packets
+// captured before the start are cut; the result is exactly as long as asked.
+export const assembleAudio = (packets, startUs, seconds) => {
+    const track = Buffer.alloc(Math.round(seconds * SAMPLE_RATE) * FRAME_BYTES);
+    for (const packet of packets) {
+        const frames = Math.floor(packet.pcm.length / FRAME_BYTES);
+        let offset = Math.round(((packet.timestampUs - startUs) / 1e6) * SAMPLE_RATE);
+        let from = 0;
+        if (offset < 0) {
+            from = -offset;
+            offset = 0;
+        }
+        if (from >= frames || offset * FRAME_BYTES >= track.length)
+            continue;
+        packet.pcm.copy(track, offset * FRAME_BYTES, from * FRAME_BYTES, frames * FRAME_BYTES);
+    }
+    return track;
+};
+// How many seconds of the window from `startUs` the packets cover.
+export const audioWithin = (packets, startUs, seconds) => {
+    const endUs = startUs + seconds * 1e6;
+    let covered = 0;
+    for (const packet of packets) {
+        const lengthUs = (Math.floor(packet.pcm.length / FRAME_BYTES) / SAMPLE_RATE) * 1e6;
+        const from = Math.max(packet.timestampUs, startUs);
+        const to = Math.min(packet.timestampUs + lengthUs, endUs);
+        if (to > from)
+            covered += to - from;
+    }
+    return covered / 1e6;
+};
+export const hasFfmpeg = () => run('ffmpeg', ['-version']).then(() => true, () => false);
+// The output as an absolute path, in a directory that can be written: checked
+// before anything is recorded, not after.
+const outputPath = (file) => {
+    const path = resolve(file);
+    try {
+        accessSync(dirname(path), constants.W_OK);
+    }
+    catch {
+        throw new Error(`cannot write to ${dirname(path)}`);
+    }
+    return path;
+};
+export const record = async (device, options) => {
+    const { signal } = options;
+    const output = outputPath(options.file);
+    // "file:" keeps ffmpeg from reading a name such as "http://…" as a URL.
+    const target = `file:${output}`;
+    if (!(await hasFfmpeg()))
+        throw new Error('recording needs ffmpeg on the PATH (for example: brew install ffmpeg)');
+    const fps = options.fps ?? 30;
+    const withAudio = options.audio ?? true;
+    const work = mkdtempSync(join(tmpdir(), 'vvd-record-'));
+    let encoder;
+    let encoded;
+    let stopAudio;
+    try {
+        const first = await device.screenshot('rgb', { signal });
+        const video = join(work, 'video.mp4');
+        encoder = spawn('ffmpeg', [
+            ['-loglevel', 'error', '-y'],
+            [
+                '-f',
+                'rawvideo',
+                '-pix_fmt',
+                'rgb24',
+                '-s',
+                `${first.width}x${first.height}`,
+                '-r',
+                String(fps),
+            ],
+            ['-i', 'pipe:0'],
+            [
+                '-c:v',
+                'libx264',
+                '-preset',
+                'veryfast',
+                '-crf',
+                '18',
+                '-pix_fmt',
+                'yuv420p',
+            ],
+            [video],
+        ].flat(), { stdio: ['pipe', 'ignore', 'pipe'] });
+        const stdin = encoder.stdin;
+        encoded = ended(encoder, 'ffmpeg');
+        // Awaited below. Until then, an early exit must not crash the process.
+        encoded.catch(() => { });
+        // A broken pipe means ffmpeg has gone, and `encoded` says why.
+        stdin.on('error', () => { });
+        let finishing = false;
+        // Rejects when ffmpeg stops before it has been asked to.
+        const died = encoded.then(() => {
+            if (!finishing)
+                throw new Error('ffmpeg stopped before the recording ended');
+        });
+        died.catch(() => { });
+        const write = async (chunk) => {
+            if (stdin.write(chunk))
+                return;
+            try {
+                await Promise.race([once(stdin, 'drain', { signal }), died]);
+            }
+            catch (error) {
+                // A broken pipe: ffmpeg's own exit, if it comes soon, says more.
+                if (!signal?.aborted)
+                    await Promise.race([died, sleep(1000)]);
+                throw error;
+            }
+        };
+        stopAudio = withAudio ? device.listen() : undefined;
+        const startMs = Date.now();
+        const endMs = startMs + options.seconds * 1000;
+        let latest = first.data;
+        let written = 1;
+        let screenshots = 1;
+        await write(latest);
+        // Writes the latest frame until the video has caught up with the clock.
+        const catchUp = async (untilMs) => {
+            const due = Math.floor(((untilMs - startMs) / 1000) * fps);
+            while (written < due) {
+                written += 1;
+                await write(latest);
+            }
+        };
+        // The caller's actions run alongside the recording, not before it.
+        let startFailure;
+        const started = (async () => options.onStart?.())();
+        started.catch((error) => (startFailure = { error }));
+        while (Date.now() < endMs) {
+            signal?.throwIfAborted();
+            if (startFailure)
+                throw startFailure.error;
+            const frame = await device
+                .screenshot('rgb', {
+                signal,
+                deadline: Math.min(Date.now() + CALL_TIMEOUT_MS, endMs + 1000),
+            })
+                .catch((error) => {
+                // A screenshot that runs out of time after the end ends the loop.
+                if (error.name === 'TimeoutError' && Date.now() >= endMs)
+                    return undefined;
+                throw error;
+            });
+            if (!frame)
+                break;
+            screenshots += 1;
+            if (frame.width === first.width && frame.height === first.height)
+                latest = frame.data;
+            await catchUp(Math.min(Date.now(), endMs));
+        }
+        await catchUp(endMs);
+        const packets = stopAudio?.() ?? [];
+        stopAudio = undefined;
+        finishing = true;
+        stdin.end();
+        await abortable(encoded, signal);
+        await abortable(started, signal);
+        if (!withAudio) {
+            await run('ffmpeg', [
+                ['-loglevel', 'error', '-y', '-i', video],
+                ['-c', 'copy', '-movflags', '+faststart', target],
+            ].flat(), signal);
+            return { file: output, frames: written, screenshots, audioSeconds: 0 };
+        }
+        const raw = join(work, 'audio.raw');
+        writeFileSync(raw, assembleAudio(packets, startMs * 1000, options.seconds));
+        await run('ffmpeg', [
+            ['-loglevel', 'error', '-y', '-i', video],
+            ['-f', 's16le', '-ar', String(SAMPLE_RATE), '-ac', '2', '-i', raw],
+            [
+                '-c:v',
+                'copy',
+                '-c:a',
+                'aac',
+                '-b:a',
+                '192k',
+                '-t',
+                String(options.seconds),
+                '-movflags',
+                '+faststart',
+            ],
+            [target],
+        ].flat(), signal);
+        return {
+            file: output,
+            frames: written,
+            screenshots,
+            audioSeconds: audioWithin(packets, startMs * 1000, options.seconds),
+        };
+    }
+    finally {
+        stopAudio?.();
+        if (encoder && encoder.exitCode === null && encoder.signalCode === null) {
+            encoder.stdin.destroy();
+            encoder.kill('SIGKILL');
+        }
+        await encoded?.catch(() => { });
+        rmSync(work, { recursive: true, force: true });
+    }
+};

package/dist/safearea.d.ts

@@ -0,0 +1,17 @@
+export type Rgb = readonly [number, number, number];
+export type SafeAreaReport = {
+    background: Rgb;
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    clear: boolean;
+};
+export type SafeAreaOptions = {
+    background?: Rgb;
+    margin?: number;
+    tolerance?: number;
+};
+export declare const parseColour: (text: string) => Rgb;
+export declare const formatColour: ([r, g, b]: Rgb) => string;
+export declare const checkSafeArea: (rgb: Buffer, width: number, height: number, options?: SafeAreaOptions) => SafeAreaReport;

package/dist/safearea.js

@@ -0,0 +1,70 @@
+// Checking a screen against the television's safe area. Amazon's Fire TV
+// guidance keeps content out of the outer 5% of each edge, which a television
+// may crop (overscan). This counts, per edge, the pixels in that margin that
+// are not the background.
+export const parseColour = (text) => {
+    const match = /^#?([0-9a-f]{6})$/i.exec(text.trim());
+    if (!match)
+        throw new Error(`cannot read colour "${text}": use #rrggbb`);
+    const value = Number.parseInt(match[1], 16);
+    return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+};
+export const formatColour = ([r, g, b]) => `#${[r, g, b].map((channel) => channel.toString(16).padStart(2, '0')).join('')}`;
+const bands = (width, height, margin) => {
+    const across = Math.round(width * margin);
+    const down = Math.round(height * margin);
+    return {
+        left: { x: 0, y: 0, width: across, height },
+        right: { x: width - across, y: 0, width: across, height },
+        top: { x: 0, y: 0, width, height: down },
+        bottom: { x: 0, y: height - down, width, height: down },
+    };
+};
+const mostCommon = (rgb, width, all) => {
+    const counts = new Map();
+    for (const band of all)
+        for (let y = band.y; y < band.y + band.height; y += 2)
+            for (let x = band.x; x < band.x + band.width; x += 2) {
+                const at = (y * width + x) * 3;
+                const key = (rgb[at] << 16) | (rgb[at + 1] << 8) | rgb[at + 2];
+                counts.set(key, (counts.get(key) ?? 0) + 1);
+            }
+    let best = 0;
+    let bestCount = -1;
+    for (const [key, count] of counts)
+        if (count > bestCount)
+            [best, bestCount] = [key, count];
+    return [(best >> 16) & 255, (best >> 8) & 255, best & 255];
+};
+// `rgb` is RGB888 rows, top to bottom, as Device.screenshot('rgb') returns.
+export const checkSafeArea = (rgb, width, height, options = {}) => {
+    if (rgb.length < width * height * 3)
+        throw new Error(`expected ${width}x${height} RGB data, got ${rgb.length} bytes`);
+    const edges = bands(width, height, options.margin ?? 0.05);
+    const background = options.background ?? mostCommon(rgb, width, Object.values(edges));
+    const tolerance = options.tolerance ?? 6;
+    const count = (band) => {
+        let outside = 0;
+        for (let y = band.y; y < band.y + band.height; y++)
+            for (let x = band.x; x < band.x + band.width; x++) {
+                const at = (y * width + x) * 3;
+                if (Math.abs(rgb[at] - background[0]) > tolerance ||
+                    Math.abs(rgb[at + 1] - background[1]) > tolerance ||
+                    Math.abs(rgb[at + 2] - background[2]) > tolerance)
+                    outside += 1;
+            }
+        return outside;
+    };
+    const left = count(edges.left);
+    const right = count(edges.right);
+    const top = count(edges.top);
+    const bottom = count(edges.bottom);
+    return {
+        background,
+        left,
+        right,
+        top,
+        bottom,
+        clear: left + right + top + bottom === 0,
+    };
+};