windows-development-sandbox 1.20.0 → 1.23.0

package/dist/guest/boot/runner.d.ts

@@ -0,0 +1,77 @@
+export interface BootTaskDef<Id extends string = string> {
+    readonly id: Id;
+    readonly stage: number;
+    readonly title: string;
+    readonly after: readonly Id[];
+    /** A failure stops the tasks that come after it and fails the boot (otherwise it is a warning). */
+    readonly critical: boolean;
+    /** Starts only after the gate (`run('background')`) and logs to the file only. */
+    readonly background?: boolean;
+    /** Runs alone (the hooks inherit the terminal). */
+    readonly exclusive?: boolean;
+}
+export type TaskRun = () => Promise<void> | void;
+export interface TaskOutcome {
+    readonly id: string;
+    readonly title: string;
+    readonly state: 'done' | 'failed' | 'skipped';
+    readonly ms: number;
+    readonly error?: string;
+}
+/** Where the boot stands, for the host's progress line. */
+export interface RunnerStatus {
+    readonly phase: 'booting' | 'provisioning';
+    /** The lowest stage that still has an unfinished foreground task. */
+    readonly step: number;
+    /** Titles of the tasks that run now. */
+    readonly running: readonly string[];
+    readonly message: string;
+}
+export interface RunnerOptions {
+    /** `quiet`: file only (background tasks). */
+    say(line: string, quiet?: boolean): void;
+    warn(line: string, quiet?: boolean): void;
+    /** Milliseconds. */
+    now(): number;
+    dryRun: boolean;
+    /** Tasks at once (default: 1 in a dry run, else 4). */
+    parallel?: number;
+    stages: number;
+    stageTitle(stage: number): string;
+    status?(status: RunnerStatus): void;
+    /** Runs a task's work so that its log lines carry the task (`prefix()` is empty while it runs alone). */
+    inContext?<T>(ctx: {
+        prefix: () => string;
+        quiet: boolean;
+    }, work: () => T): T;
+}
+export declare const seconds: (ms: number) => string;
+/** Dependencies must exist, ids be unique, the graph acyclic and no foreground task wait for a background one. */
+export declare function checkGraph(defs: readonly BootTaskDef[]): void;
+export declare class BootRunner<Id extends string> {
+    private readonly defs;
+    private readonly impl;
+    private readonly o;
+    private readonly byId;
+    private readonly state;
+    private readonly outcomes;
+    private readonly announced;
+    private readonly running;
+    constructor(defs: readonly BootTaskDef<Id>[], impl: Readonly<Record<Id, TaskRun>>, o: RunnerOptions);
+    /** Every outcome so far, in declaration order. */
+    results(): TaskOutcome[];
+    /**
+     * Runs the foreground tasks, or (after the gate) the background ones. Resolves with the outcomes of this run;
+     * rejects with the first critical error once the tasks that were running have finished.
+     */
+    run(which: 'foreground' | 'background'): Promise<TaskOutcome[]>;
+    private isFinished;
+    /** The task cannot have run properly: skipped, or failed with a critical failure. */
+    private isBlocked;
+    private skip;
+    private begin;
+    private finish;
+    private report;
+}
+/** "Boot ready in 31.8s. Slowest: Headroom 28.1s, Developer tools 7.0s. In the background: Visual Studio (...)". */
+export declare function bootSummary(totalMs: number, outcomes: readonly TaskOutcome[], background: readonly string[], logPath: string): string;

package/dist/guest/boot/runner.js

@@ -0,0 +1,215 @@
+// Runs the boot's tasks: each starts when the tasks it comes after are finished, a few at a time, in declaration order.
+// Pure (no runtime imports): the boot injects printing, the clock, the log context and the status.
+const PARALLEL = 4;
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+export const seconds = (ms) => (ms / 1000).toFixed(1) + 's';
+/** Dependencies must exist, ids be unique, the graph acyclic and no foreground task wait for a background one. */
+export function checkGraph(defs) {
+    const byId = new Map();
+    for (const d of defs) {
+        if (byId.has(d.id))
+            throw new Error('Boot task "' + d.id + '" is defined twice');
+        byId.set(d.id, d);
+    }
+    for (const d of defs)
+        for (const a of d.after) {
+            const dep = byId.get(a);
+            if (!dep)
+                throw new Error('Boot task "' + d.id + '" comes after "' + a + '", which does not exist');
+            if (dep.background && !d.background)
+                throw new Error('Boot task "' + d.id + '" waits for the background task "' + a + '"');
+        }
+    // Kahn: whatever cannot be taken off the front is in a cycle.
+    const left = new Map(defs.map((d) => [d.id, d.after.length]));
+    const queue = defs.filter((d) => d.after.length === 0).map((d) => d.id);
+    let taken = 0;
+    while (queue.length) {
+        const id = queue.shift();
+        taken++;
+        for (const d of defs)
+            if (d.after.includes(id)) {
+                left.set(d.id, left.get(d.id) - 1);
+                if (left.get(d.id) === 0)
+                    queue.push(d.id);
+            }
+    }
+    if (taken !== defs.length)
+        throw new Error('The boot tasks depend on each other in a circle');
+}
+export class BootRunner {
+    defs;
+    impl;
+    o;
+    byId = new Map();
+    state = new Map();
+    outcomes = new Map();
+    announced = new Set();
+    running = new Set();
+    constructor(defs, impl, o) {
+        this.defs = defs;
+        this.impl = impl;
+        this.o = o;
+        checkGraph(defs);
+        for (const d of defs) {
+            this.byId.set(d.id, d);
+            this.state.set(d.id, 'pending');
+        }
+    }
+    /** Every outcome so far, in declaration order. */
+    results() {
+        return this.defs.flatMap((d) => (this.outcomes.has(d.id) ? [this.outcomes.get(d.id)] : []));
+    }
+    /**
+     * Runs the foreground tasks, or (after the gate) the background ones. Resolves with the outcomes of this run;
+     * rejects with the first critical error once the tasks that were running have finished.
+     */
+    run(which) {
+        const todo = this.defs.filter((d) => Boolean(d.background) === (which === 'background'));
+        const quiet = which === 'background';
+        const parallel = this.o.parallel ?? (this.o.dryRun ? 1 : PARALLEL);
+        return new Promise((resolve, reject) => {
+            let firstCritical;
+            let failed = false;
+            const pending = () => todo.filter((d) => this.state.get(d.id) === 'pending');
+            const settle = () => {
+                if (this.running.size === 0 && pending().length === 0) {
+                    if (failed)
+                        reject(firstCritical);
+                    else
+                        resolve(todo.map((d) => this.outcomes.get(d.id)));
+                }
+            };
+            const start = (d) => {
+                this.state.set(d.id, 'running');
+                this.running.add(d.id);
+                const began = this.o.now();
+                if (!quiet)
+                    this.begin(d);
+                const prefix = () => (this.running.size > 1 && !d.exclusive ? d.title : '');
+                const work = async () => {
+                    await this.impl[d.id]();
+                };
+                const call = () => (this.o.inContext ? this.o.inContext({ prefix, quiet }, work) : work());
+                // A synchronous throw from a task is a failure too: the call starts inside a promise.
+                void Promise.resolve()
+                    .then(call)
+                    .then(() => this.finish(d, began, quiet, undefined), (e) => {
+                    this.finish(d, began, quiet, e);
+                    if (d.critical && firstCritical === undefined) {
+                        firstCritical = e;
+                        failed = true;
+                    }
+                })
+                    .finally(() => {
+                    this.running.delete(d.id);
+                    if (!quiet)
+                        this.report(d.stage);
+                    pump();
+                });
+            };
+            const pump = () => {
+                // Tasks that come after a failed critical (or skipped) task are skipped, and so is whatever comes after those.
+                for (let again = true; again;) {
+                    again = false;
+                    for (const d of pending()) {
+                        const bad = d.after.find((a) => this.isBlocked(a));
+                        if (bad) {
+                            this.skip(d, this.byId.get(bad).title + ' failed');
+                            again = true;
+                        }
+                    }
+                }
+                for (const d of pending()) {
+                    if (this.running.size >= parallel)
+                        break;
+                    if (!d.after.every((a) => this.isFinished(a)))
+                        continue;
+                    if (d.exclusive) {
+                        // Waits until nothing runs, and holds back everything declared after it.
+                        if (this.running.size === 0)
+                            start(d);
+                        break;
+                    }
+                    start(d);
+                }
+                settle();
+            };
+            pump();
+        });
+    }
+    isFinished(id) {
+        const s = this.state.get(id);
+        return s === 'done' || s === 'failed' || s === 'skipped';
+    }
+    /** The task cannot have run properly: skipped, or failed with a critical failure. */
+    isBlocked(id) {
+        const s = this.state.get(id);
+        return s === 'skipped' || (s === 'failed' && this.byId.get(id).critical);
+    }
+    skip(d, why) {
+        this.state.set(d.id, 'skipped');
+        this.outcomes.set(d.id, { id: d.id, title: d.title, state: 'skipped', ms: 0, error: why });
+        this.o.say('[' + d.stage + '/' + this.o.stages + '] ' + d.title + ': skipped (' + why + ')');
+    }
+    begin(d) {
+        if (!this.announced.has(d.stage)) {
+            this.announced.add(d.stage);
+            this.o.say('\n' + CYAN + '[' + d.stage + '/' + this.o.stages + '] ' + this.o.stageTitle(d.stage) + RESET);
+        }
+        this.o.say('[' + d.stage + '/' + this.o.stages + '] ' + d.title + ': started');
+        this.report(d.stage);
+    }
+    finish(d, began, quiet, error) {
+        const ms = this.o.now() - began;
+        const message = error === undefined ? undefined : error instanceof Error ? error.message : String(error);
+        this.state.set(d.id, message === undefined ? 'done' : 'failed');
+        this.outcomes.set(d.id, {
+            id: d.id,
+            title: d.title,
+            state: message === undefined ? 'done' : 'failed',
+            ms,
+            ...(message === undefined ? {} : { error: message }),
+        });
+        const tag = '[' + d.stage + '/' + this.o.stages + '] ' + d.title;
+        if (message === undefined) {
+            if (!quiet)
+                this.o.say(tag + ': done in ' + seconds(ms));
+        }
+        else if (d.critical) {
+            this.o.warn(tag + ': FAILED in ' + seconds(ms) + ': ' + message, quiet);
+        }
+        else {
+            this.o.warn(d.title + ' failed (continuing): ' + message, quiet);
+            if (!quiet)
+                this.o.say(tag + ': FAILED in ' + seconds(ms) + ': ' + message);
+        }
+    }
+    report(stageHint) {
+        if (!this.o.status)
+            return;
+        const open = this.defs.filter((d) => !d.background && !this.isFinished(d.id));
+        const step = open.length ? Math.min(...open.map((d) => d.stage)) : stageHint;
+        const stage1Open = open.some((d) => d.stage === 1);
+        const running = this.defs.filter((d) => this.running.has(d.id)).map((d) => d.title);
+        this.o.status({
+            phase: stage1Open ? 'booting' : 'provisioning',
+            step,
+            running,
+            message: '[' + step + '/' + this.o.stages + '] ' + this.o.stageTitle(step),
+        });
+    }
+}
+/** "Boot ready in 31.8s. Slowest: Headroom 28.1s, Developer tools 7.0s. In the background: Visual Studio (...)". */
+export function bootSummary(totalMs, outcomes, background, logPath) {
+    const slowest = [...outcomes]
+        .filter((o) => o.state !== 'skipped')
+        .sort((a, b) => b.ms - a.ms)
+        .slice(0, 3)
+        .map((o) => o.title + ' ' + seconds(o.ms));
+    return ('Boot ready in ' +
+        seconds(totalMs) +
+        '.' +
+        (slowest.length ? ' Slowest: ' + slowest.join(', ') + '.' : '') +
+        (background.length ? ' In the background: ' + background.join(', ') + ' (installing, see ' + logPath + ').' : ''));
+}

package/dist/guest/browser/cdp.d.ts

@@ -0,0 +1,71 @@
+import type { Duplex } from 'node:stream';
+/** The largest message accepted from the browser (its whole cookie jar can be big). */
+export declare const MAX_MESSAGE_BYTES: number;
+export declare const OPCODE: {
+    readonly continuation: 0;
+    readonly text: 1;
+    readonly binary: 2;
+    readonly close: 8;
+    readonly ping: 9;
+    readonly pong: 10;
+};
+/** Where a browser's DevTools listen: its port on 127.0.0.1 and the browser target's path. */
+export interface DevToolsEndpoint {
+    readonly port: number;
+    readonly path: string;
+}
+/** The DevToolsActivePort file's two lines (port, then /devtools/browser/<id>), or null when it is not that. */
+export declare function parseDevToolsActivePort(text: string): DevToolsEndpoint | null;
+/** One WebSocket frame. A client's frames are masked (`mask` given); a server's never are. */
+export declare function encodeFrame(opcode: number, payload: Buffer, mask?: Buffer | null): Buffer;
+export interface Frame {
+    readonly fin: boolean;
+    readonly opcode: number;
+    readonly payload: Buffer;
+}
+/**
+ * Cuts a byte stream into frames. Refuses (throws) reserved bits, unknown opcodes, a control frame that is long or
+ * split, a frame bigger than `maxBytes`, and masking the wrong way round (`masked`: what the other side must do).
+ */
+export declare class FrameReader {
+    private readonly maxBytes;
+    private readonly masked;
+    private buffer;
+    constructor(maxBytes?: number, masked?: boolean);
+    push(chunk: Buffer): Frame[];
+    private next;
+}
+/** The Sec-WebSocket-Accept a server must answer to `key` (RFC 6455). */
+export declare function acceptFor(key: string): string;
+/** Parses the server's handshake answer: the bytes after it, or throws when it is not a switch to WebSocket. */
+export declare function readHandshake(head: Buffer, key: string): {
+    rest: Buffer;
+} | null;
+/** One connection to a browser's DevTools: call() sends a command and resolves with its result. */
+export declare class CdpConnection {
+    private readonly socket;
+    private nextId;
+    private readonly pending;
+    private readonly reader;
+    private fragments;
+    private fragmentBytes;
+    private closed;
+    private constructor();
+    /** Connects to the endpoint on 127.0.0.1 (never another host). */
+    static open(endpoint: DevToolsEndpoint, timeoutMs?: number): Promise<CdpConnection>;
+    /** The handshake over a socket that is connecting or connected (the self-test gives a fake one). */
+    static over(socket: Duplex, endpoint: DevToolsEndpoint, timeoutMs?: number): Promise<CdpConnection>;
+    private listen;
+    private onBytes;
+    private onFrame;
+    private onMessage;
+    private send;
+    private shut;
+    /** Sends a command (to a page's session in flat mode when `sessionId` is given) and waits for its result. */
+    call<T = unknown>(method: string, params?: Readonly<Record<string, unknown>>, o?: {
+        readonly sessionId?: string;
+        readonly timeoutMs?: number;
+    }): Promise<T>;
+    /** Closes the connection (the browser keeps running). */
+    close(): void;
+}

package/dist/guest/browser/cdp.js

@@ -0,0 +1,306 @@
+// A small client of the Chrome DevTools Protocol (CDP) for a Chromium browser in this sandbox (Comet): the WebSocket
+// handshake and frames over a plain TCP socket to 127.0.0.1 (Node 22.0.0 has no stable WebSocket), JSON calls with
+// ids, nothing else. Everything the browser sends is bounded: the handshake's headers, each frame and each message.
+// The port comes from the profile's DevToolsActivePort file (the browser starts with --remote-debugging-port=0 or a
+// fixed port). No runtime imports: the self-test drives it over a fake socket.
+import crypto from 'node:crypto';
+import net from 'node:net';
+/** The largest message accepted from the browser (its whole cookie jar can be big). */
+export const MAX_MESSAGE_BYTES = 8 * 1024 * 1024;
+const MAX_HEADER_BYTES = 16 * 1024;
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const DEFAULT_TIMEOUT_MS = 10_000;
+export const OPCODE = { continuation: 0, text: 1, binary: 2, close: 8, ping: 9, pong: 10 };
+/** The DevToolsActivePort file's two lines (port, then /devtools/browser/<id>), or null when it is not that. */
+export function parseDevToolsActivePort(text) {
+    const [portLine = '', pathLine = ''] = text.slice(0, 512).split(/\r?\n/);
+    if (!/^\d{1,5}$/.test(portLine.trim()))
+        return null;
+    const port = Number(portLine.trim());
+    const target = pathLine.trim();
+    if (port < 1 || port > 65535 || !/^\/devtools\/browser\/[A-Za-z0-9-]{1,64}$/.test(target))
+        return null;
+    return { port, path: target };
+}
+/** One WebSocket frame. A client's frames are masked (`mask` given); a server's never are. */
+export function encodeFrame(opcode, payload, mask = crypto.randomBytes(4)) {
+    const len = payload.length;
+    const head = [0x80 | (opcode & 0x0f)];
+    const maskBit = mask ? 0x80 : 0;
+    if (len < 126)
+        head.push(maskBit | len);
+    else if (len < 65536)
+        head.push(maskBit | 126, (len >> 8) & 0xff, len & 0xff);
+    else {
+        head.push(maskBit | 127, 0, 0, 0, 0);
+        head.push((len >>> 24) & 0xff, (len >>> 16) & 0xff, (len >>> 8) & 0xff, len & 0xff);
+    }
+    if (!mask)
+        return Buffer.concat([Buffer.from(head), payload]);
+    const body = Buffer.alloc(len);
+    for (let i = 0; i < len; i++)
+        body[i] = payload[i] ^ mask[i & 3];
+    return Buffer.concat([Buffer.from(head), mask.subarray(0, 4), body]);
+}
+/**
+ * Cuts a byte stream into frames. Refuses (throws) reserved bits, unknown opcodes, a control frame that is long or
+ * split, a frame bigger than `maxBytes`, and masking the wrong way round (`masked`: what the other side must do).
+ */
+export class FrameReader {
+    maxBytes;
+    masked;
+    buffer = Buffer.alloc(0);
+    constructor(maxBytes = MAX_MESSAGE_BYTES, masked = false) {
+        this.maxBytes = maxBytes;
+        this.masked = masked;
+    }
+    push(chunk) {
+        this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;
+        const frames = [];
+        for (let frame = this.next(); frame; frame = this.next())
+            frames.push(frame);
+        return frames;
+    }
+    next() {
+        const b = this.buffer;
+        if (b.length < 2)
+            return null;
+        const fin = (b[0] & 0x80) !== 0;
+        if (b[0] & 0x70)
+            throw new Error('DevTools: a frame with reserved bits set');
+        const opcode = b[0] & 0x0f;
+        if (![0, 1, 2, 8, 9, 10].includes(opcode))
+            throw new Error('DevTools: an unknown frame type (' + opcode + ')');
+        const isMasked = (b[1] & 0x80) !== 0;
+        if (isMasked !== this.masked)
+            throw new Error('DevTools: a frame masked the wrong way');
+        let len = b[1] & 0x7f;
+        let at = 2;
+        if (len === 126) {
+            if (b.length < 4)
+                return null;
+            len = b.readUInt16BE(2);
+            at = 4;
+        }
+        else if (len === 127) {
+            if (b.length < 10)
+                return null;
+            if (b.readUInt32BE(2) !== 0)
+                throw new Error('DevTools: a frame bigger than ' + this.maxBytes + ' bytes');
+            len = b.readUInt32BE(6);
+            at = 10;
+        }
+        if (opcode >= 8 && (len > 125 || !fin))
+            throw new Error('DevTools: a control frame that is long or split');
+        if (len > this.maxBytes)
+            throw new Error('DevTools: a frame bigger than ' + this.maxBytes + ' bytes');
+        const maskAt = at;
+        if (isMasked)
+            at += 4;
+        if (b.length < at + len)
+            return null;
+        let payload = Buffer.from(b.subarray(at, at + len));
+        if (isMasked) {
+            const mask = b.subarray(maskAt, maskAt + 4);
+            payload = Buffer.from(payload.map((byte, i) => byte ^ mask[i & 3]));
+        }
+        this.buffer = b.subarray(at + len);
+        return { fin, opcode, payload };
+    }
+}
+/** The Sec-WebSocket-Accept a server must answer to `key` (RFC 6455). */
+export function acceptFor(key) {
+    return crypto
+        .createHash('sha1')
+        .update(key + WS_GUID)
+        .digest('base64');
+}
+/** Parses the server's handshake answer: the bytes after it, or throws when it is not a switch to WebSocket. */
+export function readHandshake(head, key) {
+    const end = head.indexOf('\r\n\r\n');
+    if (end < 0) {
+        if (head.length > MAX_HEADER_BYTES)
+            throw new Error('DevTools: the handshake answer is too long');
+        return null;
+    }
+    const lines = head.subarray(0, end).toString('latin1').split('\r\n');
+    if (!/^HTTP\/1\.1 101\b/.test(lines[0] ?? ''))
+        throw new Error('DevTools: refused the connection (' + (lines[0] ?? '') + ')');
+    const accept = lines
+        .slice(1)
+        .map((l) => /^sec-websocket-accept:\s*(\S+)\s*$/i.exec(l)?.[1])
+        .find((v) => v !== undefined);
+    if (accept !== acceptFor(key))
+        throw new Error('DevTools: the handshake answer does not match');
+    return { rest: head.subarray(end + 4) };
+}
+/** One connection to a browser's DevTools: call() sends a command and resolves with its result. */
+export class CdpConnection {
+    socket;
+    nextId = 1;
+    pending = new Map();
+    reader = new FrameReader();
+    fragments = [];
+    fragmentBytes = 0;
+    closed = false;
+    constructor(socket) {
+        this.socket = socket;
+    }
+    /** Connects to the endpoint on 127.0.0.1 (never another host). */
+    static open(endpoint, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const socket = net.connect({ host: '127.0.0.1', port: endpoint.port });
+        return CdpConnection.over(socket, endpoint, timeoutMs);
+    }
+    /** The handshake over a socket that is connecting or connected (the self-test gives a fake one). */
+    static over(socket, endpoint, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const key = crypto.randomBytes(16).toString('base64');
+        return new Promise((resolve, reject) => {
+            let head = Buffer.alloc(0);
+            const timer = setTimeout(() => fail(new Error('DevTools: no answer within ' + timeoutMs + ' ms')), timeoutMs);
+            const cleanup = () => {
+                clearTimeout(timer);
+                socket.off('data', onData);
+                socket.off('error', fail);
+                socket.off('close', onClose);
+            };
+            const fail = (e) => {
+                cleanup();
+                socket.destroy();
+                reject(e);
+            };
+            const onClose = () => fail(new Error('DevTools: the connection closed during the handshake'));
+            const onData = (chunk) => {
+                try {
+                    head = Buffer.concat([head, chunk]);
+                    const done = readHandshake(head, key);
+                    if (!done)
+                        return;
+                    cleanup();
+                    const connection = new CdpConnection(socket);
+                    connection.listen();
+                    if (done.rest.length)
+                        connection.onBytes(done.rest);
+                    resolve(connection);
+                }
+                catch (e) {
+                    fail(e instanceof Error ? e : new Error(String(e)));
+                }
+            };
+            socket.on('data', onData);
+            socket.on('error', fail);
+            socket.on('close', onClose);
+            socket.write('GET ' +
+                endpoint.path +
+                ' HTTP/1.1\r\nHost: 127.0.0.1:' +
+                endpoint.port +
+                '\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Key: ' +
+                key +
+                '\r\nSec-WebSocket-Version: 13\r\n\r\n');
+        });
+    }
+    listen() {
+        this.socket.on('data', (chunk) => this.onBytes(chunk));
+        this.socket.on('error', (e) => this.shut(e));
+        this.socket.on('close', () => this.shut(new Error('DevTools: the connection closed')));
+    }
+    onBytes(chunk) {
+        try {
+            for (const frame of this.reader.push(chunk))
+                this.onFrame(frame);
+        }
+        catch (e) {
+            this.shut(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    onFrame(frame) {
+        if (frame.opcode === OPCODE.ping) {
+            this.send(OPCODE.pong, frame.payload);
+            return;
+        }
+        if (frame.opcode === OPCODE.pong)
+            return;
+        if (frame.opcode === OPCODE.close) {
+            this.shut(new Error('DevTools: the browser closed the connection'));
+            return;
+        }
+        if (frame.opcode !== OPCODE.continuation && this.fragments.length)
+            throw new Error('DevTools: a new message before the last one ended');
+        if (frame.opcode === OPCODE.continuation && !this.fragments.length)
+            throw new Error('DevTools: a continuation without a message');
+        this.fragmentBytes += frame.payload.length;
+        if (this.fragmentBytes > MAX_MESSAGE_BYTES)
+            throw new Error('DevTools: a message bigger than ' + MAX_MESSAGE_BYTES);
+        this.fragments.push(frame.payload);
+        if (!frame.fin)
+            return;
+        const text = Buffer.concat(this.fragments).toString('utf8');
+        this.fragments = [];
+        this.fragmentBytes = 0;
+        this.onMessage(text);
+    }
+    onMessage(text) {
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return; // Not JSON: nothing waits for it.
+        }
+        if (typeof message !== 'object' || message === null)
+            return;
+        const m = message;
+        if (typeof m.id !== 'number')
+            return; // An event: not asked for.
+        const waiting = this.pending.get(m.id);
+        if (!waiting)
+            return;
+        this.pending.delete(m.id);
+        clearTimeout(waiting.timer);
+        if (m.error)
+            waiting.reject(new Error('DevTools: ' + String(m.error.message ?? 'the call failed').slice(0, 300)));
+        else
+            waiting.resolve(m.result ?? {});
+    }
+    send(opcode, payload) {
+        if (!this.closed)
+            this.socket.write(encodeFrame(opcode, payload));
+    }
+    shut(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(error);
+        }
+        this.pending.clear();
+        this.socket.destroy();
+    }
+    /** Sends a command (to a page's session in flat mode when `sessionId` is given) and waits for its result. */
+    call(method, params = {}, o = {}) {
+        if (this.closed)
+            return Promise.reject(new Error('DevTools: the connection is closed'));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error('DevTools: ' + method + ' did not answer'));
+            }, o.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            const body = { id, method, params, ...(o.sessionId ? { sessionId: o.sessionId } : {}) };
+            this.send(OPCODE.text, Buffer.from(JSON.stringify(body), 'utf8'));
+        });
+    }
+    /** Closes the connection (the browser keeps running). */
+    close() {
+        if (this.closed)
+            return;
+        try {
+            this.socket.write(encodeFrame(OPCODE.close, Buffer.alloc(0)));
+        }
+        catch {
+            // Already gone: nothing to tell the browser.
+        }
+        this.shut(new Error('DevTools: the connection is closed'));
+    }
+}