@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/browser-view.js

@@ -0,0 +1,1487 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { observePage, observationResult } from './browser-observation.js';
+export const VIEW_TAB_LIMIT = 6;
+export const VIEW_SESSION_LIMIT = 4;
+export const VIEW_IDLE_CLOSE_MS = 10 * 60 * 1000;
+/** The pacing window between emitted frames: one per display refresh, with the coalescer holding the newest. */
+export const VIEW_FRAME_MIN_INTERVAL_MS = 16;
+export const VIEW_GOTO_TIMEOUT_MS = 30_000;
+/** The viewport Mobile mode simulates, in CSS pixels: an iPhone-class layout. */
+export const VIEW_MOBILE_VIEWPORT = { width: 390, height: 844 };
+/** The JPEG quality stream frames use; agent screenshots keep their own setting. */
+export const VIEW_STREAM_QUALITY = 75;
+/**
+ * The mobile Chrome UA Mobile mode presents. A Chromium engine claiming to be
+ * iOS Safari confuses sites that branch on it, so the UA names the platform the
+ * page actually renders with.
+ */
+export const VIEW_MOBILE_USER_AGENT = 'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Mobile Safari/537.36';
+const VIEW_URL_LIMIT = 2048;
+// A copy is answered as one JSON string over the same pipe as everything else,
+// so the largest plausible selection is bounded rather than trusted.
+const VIEW_CLIPBOARD_LIMIT = 1_000_000;
+/**
+ * The top document's selection, and whether focus is inside a child frame.
+ *
+ * `document.activeElement` is the iframe element itself, never the field inside
+ * it, and the top document's own selection is empty while a frame holds focus —
+ * so a selection made in a frame is invisible here and the caller has to ask the
+ * frames. It is an expression rather than a function: this file compiles without
+ * the DOM library, and Playwright evaluates a string inside the page as-is.
+ */
+const SELECTION_STATE = `(() => {
+  const active = document.activeElement;
+  const inFrame = !!active && (active.tagName === 'IFRAME' || active.tagName === 'FRAME');
+  // A selection outlives the focus that made it, so text alone does not say which
+  // document the user is in; the focused document is the one that owns the caret.
+  const focused = document.hasFocus();
+  if (inFrame) return { inFrame: true, focused, text: '' };
+  if (active && typeof active.value === 'string' && typeof active.selectionStart === 'number'
+    && typeof active.selectionEnd === 'number' && active.selectionEnd > active.selectionStart) {
+    return { inFrame: false, focused, text: active.value.slice(active.selectionStart, active.selectionEnd) };
+  }
+  return { inFrame: false, focused, text: window.getSelection ? String(window.getSelection() || '') : '' };
+})()`;
+/**
+ * The cursor style in effect at a point in the page.
+ *
+ * The pane shows a streamed image, so the page's pointer never appears on its
+ * own: the panel asks for the style under the pointer and draws that shape
+ * itself. Same-origin frames are entered by mapping the point into each one.
+ */
+const CURSOR_AT = `((point) => {
+  let doc = document;
+  let x = point.x;
+  let y = point.y;
+  for (let depth = 0; depth < 8; depth += 1) {
+    let element;
+    try { element = doc.elementFromPoint(x, y); } catch { return 'default'; }
+    if (!element) return 'default';
+    if (element.tagName === 'IFRAME' || element.tagName === 'FRAME') {
+      let inner = null;
+      try { inner = element.contentDocument; } catch { inner = null; }
+      if (inner) {
+        const rect = element.getBoundingClientRect();
+        x -= rect.left;
+        y -= rect.top;
+        doc = inner;
+        continue;
+      }
+    }
+    try { return getComputedStyle(element).cursor || 'default'; } catch { return 'default'; }
+  }
+  return 'default';
+})`;
+/** The dependency panel browsing needs: an HTTP(S) page an isolated browser can open. */ export function browserViewUrl(value) {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new Error('Use an HTTP(S) URL without embedded credentials');
+    if (url.href.length > VIEW_URL_LIMIT)
+        throw new Error('URL exceeds the 2048-character limit');
+    return url.href;
+}
+export function clampViewport(width, height) {
+    const value = (input, min, max, fallback) => Number.isSafeInteger(input) ? Math.max(min, Math.min(max, input)) : fallback;
+    return { width: value(width, 280, 1600, 900), height: value(height, 240, 2200, 700) };
+}
+/**
+ * JPEG dimensions straight from the SOF markers, without decoding pixels.
+ *
+ * Screencast frames carry no size fields; the panel sends input in image pixels
+ * and the engine must translate to page CSS pixels, so the real image size is
+ * load-bearing, not decorative.
+ */
+export function jpegSize(bytes) {
+    if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return undefined;
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+        if (bytes[offset] !== 0xff) {
+            offset++;
+            continue;
+        }
+        const marker = bytes[offset + 1];
+        // Fill bytes before a marker, and the stand-alone markers that carry no length.
+        if (marker === 0xff || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+            offset += 2;
+            continue;
+        }
+        const length = (bytes[offset + 2] << 8) | bytes[offset + 3];
+        // Baseline and progressive DCT carry the frame size; every other segment is skipped whole.
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+            if (length < 7 || offset + 9 > bytes.length)
+                return undefined;
+            return { height: (bytes[offset + 5] << 8) | bytes[offset + 6], width: (bytes[offset + 7] << 8) | bytes[offset + 8] };
+        }
+        if (length < 2)
+            return undefined;
+        offset += 2 + length;
+    }
+    return undefined;
+}
+/** Windows virtual-key codes for the named keys a panel keypress can produce. */
+const KEY_CODE = {
+    Enter: 13, Backspace: 8, Tab: 9, Escape: 27, Delete: 46, Insert: 45,
+    ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40, Home: 36, End: 35, PageUp: 33, PageDown: 34,
+    F1: 112, F2: 113, F3: 114, F4: 115, F5: 116, F6: 117, F7: 118, F8: 119, F9: 120, F10: 121, F11: 122, F12: 123,
+};
+const CODE_KEY = {
+    Comma: 188, Period: 190, Slash: 191, Semicolon: 186, Quote: 222, BracketLeft: 219, BracketRight: 221,
+    Backslash: 220, Minus: 189, Equal: 187, Backquote: 192, NumpadEnter: 13, NumpadAdd: 107, NumpadSubtract: 109,
+    NumpadMultiply: 106, NumpadDivide: 111, NumpadDecimal: 110,
+};
+/**
+ * One panel key event as the CDP input domain needs it.
+ *
+ * A key is always a keyboard event, with the character a key-down inserts in
+ * `text`: an ordinary letter is inserted that way, and Enter carries Chromium's
+ * carriage return so a textarea or a content-editable field gets its newline.
+ * Keeping the gesture as a key event is what lets the page run its own keydown
+ * handling — Space activating a focused button, a page's printable-key shortcut —
+ * which text insertion alone would never trigger. A Ctrl, Alt or Meta held over a
+ * key drops the text (Ctrl+C must be a key event, never the character "c"), with
+ * one exception: AltGr is reported as Ctrl+Alt, and the character it produced —
+ * "@" on a German layout, "€" on many others — must survive.
+ */
+export function keyDescriptor(key, code, modifiers = 0) {
+    const named = KEY_CODE[key]
+        ?? (code?.startsWith('Key') && code.length === 4 ? code.charCodeAt(3) : undefined)
+        ?? (code?.startsWith('Digit') && code.length === 6 ? 48 + Number(code.slice(5)) : undefined)
+        ?? (code !== undefined ? CODE_KEY[code] : undefined);
+    const printable = key.length === 1;
+    if (!printable && named === undefined)
+        throw new Error(`Unsupported key: ${key}`);
+    const ctrl = (modifiers & MODIFIER_BITS.ctrl) !== 0;
+    const alt = (modifiers & MODIFIER_BITS.alt) !== 0;
+    // An Option gesture on macOS that produces a character changes the key itself to
+    // that character (Option+2 is '™' on a US layout), while an Alt shortcut leaves
+    // the letter or digit it names untouched: a non-ASCII single character with Alt
+    // held is text to insert, not a shortcut, or the page would see the key and
+    // insert nothing.
+    const altCharacter = alt && !ctrl && printable && (key.codePointAt(0) ?? 0) > 0x7f;
+    // AltGr arrives as Ctrl+Alt together; a shortcut has exactly one of them (or Meta).
+    const shortcut = !altCharacter && ((modifiers & MODIFIER_BITS.meta) !== 0 || (ctrl !== alt && (ctrl || alt)));
+    const keyCode = named ?? key.toUpperCase().charCodeAt(0);
+    const text = shortcut ? undefined : printable ? key : key === 'Enter' ? '\r' : undefined;
+    return {
+        key: printable && shortcut ? key.toLowerCase() : key,
+        code: code ?? '',
+        windowsVirtualKeyCode: keyCode,
+        nativeKeyCodes: [keyCode],
+        ...(text === undefined ? {} : { text }),
+    };
+}
+export const MODIFIER_BITS = { alt: 1, ctrl: 2, meta: 4, shift: 8 };
+export function modifierMask(modifiers) {
+    if (modifiers === undefined)
+        return 0;
+    if (!Array.isArray(modifiers) || modifiers.some(item => typeof item !== 'string' || !(item in MODIFIER_BITS)))
+        throw new Error('modifiers must be a list of alt, ctrl, meta, shift');
+    return modifiers.reduce((mask, name) => mask | MODIFIER_BITS[name], 0);
+}
+/**
+ * The native editing commands a macOS page performs for a key-down.
+ *
+ * On macOS, gestures like Cmd+A, Cmd+Z, or Option+Arrow are not synthesized from
+ * key events: Chromium runs the named command instead, and nothing happens when
+ * none is sent — the panel suppresses the local default, so the page would be
+ * left without either. These are the mappings Playwright itself derives for the
+ * same CDP call (its macEditingCommands table), limited to the gestures a pane
+ * can forward.
+ */
+export function macEditingCommands(key, modifiers) {
+    const meta = (modifiers & MODIFIER_BITS.meta) !== 0;
+    const alt = (modifiers & MODIFIER_BITS.alt) !== 0;
+    const shift = (modifiers & MODIFIER_BITS.shift) !== 0;
+    if (meta && !alt) {
+        switch (key) {
+            case 'a': return ['selectAll'];
+            case 'z': return [shift ? 'redo' : 'undo'];
+            case 'c': return ['copy'];
+            case 'x': return ['cut'];
+            case 'v': return ['paste'];
+            case 'Backspace': return ['deleteToBeginningOfLine'];
+            case 'ArrowLeft': return [shift ? 'moveToBeginningOfLineAndModifySelection' : 'moveToBeginningOfLine'];
+            case 'ArrowRight': return [shift ? 'moveToEndOfLineAndModifySelection' : 'moveToEndOfLine'];
+            default: return [];
+        }
+    }
+    if (alt && !meta) {
+        switch (key) {
+            case 'Backspace': return ['deleteWordBackward'];
+            case 'Delete': return ['deleteWordForward'];
+            case 'ArrowLeft': return [shift ? 'moveWordLeftAndModifySelection' : 'moveWordLeft'];
+            case 'ArrowRight': return [shift ? 'moveWordRightAndModifySelection' : 'moveWordRight'];
+            default: return [];
+        }
+    }
+    return [];
+}
+/**
+ * The launch options for the panel browser. Playwright mutes Chromium by default
+ * (`--mute-audio`), which silences every page the user browses in the panel; the
+ * screencast carries pixels only, so the page's own audio output on the engine's
+ * machine is the only sound the panel has.
+ */
+export function viewLaunchOptions(channel, executablePath) {
+    return {
+        headless: true,
+        ...(channel === 'chromium' ? { executablePath } : { channel }),
+        ignoreDefaultArgs: ['--mute-audio'],
+        timeout: 20_000,
+    };
+}
+/** Whether a frame arriving at `now` may be emitted, given the last emitted frame time. */
+export function frameGate(now, lastEmittedAt, minIntervalMs) {
+    return lastEmittedAt === undefined || now - lastEmittedAt >= minIntervalMs;
+}
+/**
+ * The file whose existence proves a channel is installed. The bundled Chromium's
+ * path comes from playwright-core itself; system channels have per-platform
+ * locations. The probe reads the filesystem and never launches anything.
+ */
+export function channelCandidate(channel, platform, chromiumExecutable) {
+    if (channel === 'chromium') {
+        try {
+            return chromiumExecutable();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const programFiles = [process.env['ProgramFiles'], process.env['ProgramFiles(x86)']].filter((value) => !!value);
+    if (platform === 'win32') {
+        if (channel === 'msedge')
+            return programFiles.map(root => join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe')).find(existsSync);
+        return programFiles.map(root => join(root, 'Google', 'Chrome', 'Application', 'chrome.exe')).find(existsSync);
+    }
+    if (platform === 'darwin') {
+        return channel === 'msedge' ? '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge' : '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+    }
+    return channel === 'msedge'
+        ? ['/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable'].find(existsSync)
+        : ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable'].find(existsSync);
+}
+/**
+ * One engine's panel browsers: a browser per session, a page per tab, and a CDP
+ * screencast relay per active tab. Everything is keyed by the saved session id —
+ * exactly the identity the desktop's browser pane already owns.
+ */
+export class BrowserViewManager {
+    emit;
+    launchBrowser;
+    sessions = new Map();
+    /**
+     * The pane's standing stream request per session, kept before a browser exists.
+     *
+     * A panel mounts and asks for frames before its first tab is opened, so the
+     * request has to outlive the absence of a session: the open that follows
+     * adopts this along with its viewport, and a later re-open after an idle reap
+     * resumes streaming without another round trip.
+     */
+    desired = new Map();
+    /** Launches in flight per session, so concurrent opens share one browser. */
+    launching = new Map();
+    runtime = { state: 'checking' };
+    runtimeProbe;
+    installTask;
+    /**
+     * The running installer, held here rather than in the closure that started it:
+     * shutdown has to terminate the download and settle the request waiting on it,
+     * or the child outlives the engine that is being closed.
+     */
+    installer;
+    /**
+     * Sessions released while their first launch was still in flight. The launch
+     * that arrives afterwards closes its browser instead of registering one the
+     * deleted session can never reach, or else it would hold a slot for good.
+     */
+    released = new Set();
+    closed = false;
+    constructor(emit, launchBrowser) {
+        this.emit = emit;
+        this.launchBrowser = launchBrowser;
+    }
+    publishRuntime(status) {
+        this.runtime = status;
+        this.emit('browser.runtime', { ...status });
+    }
+    /**
+     * Probe the same executables `launch` will use, without launching anything;
+     * the answer is cached.
+     */
+    runtimeStatus(force = false) {
+        if (!force && this.runtime.state !== 'checking')
+            return Promise.resolve(this.runtime);
+        this.runtimeProbe ??= (async () => {
+            const { chromium } = await import('playwright-core');
+            const failures = [];
+            for (const channel of ['chromium', 'msedge', 'chrome']) {
+                if (this.closed)
+                    break;
+                try {
+                    const candidate = channelCandidate(channel, process.platform, () => chromium.executablePath());
+                    if (candidate && existsSync(candidate)) {
+                        const status = { state: 'ready', channel };
+                        this.publishRuntime(status);
+                        return status;
+                    }
+                }
+                catch (error) {
+                    failures.push(error instanceof Error ? error.message : String(error));
+                }
+            }
+            const status = { state: 'missing', detail: failures.join('; ').slice(0, 500) || undefined };
+            this.publishRuntime(status);
+            return status;
+        })().finally(() => { this.runtimeProbe = undefined; });
+        return this.runtimeProbe;
+    }
+    /**
+     * Download the bundled Chromium through playwright-core's own installer.
+     *
+     * A machine with Edge or Chrome installed never reaches this: the probe is
+     * satisfied by the system browser and the download is skipped.
+     */
+    install() {
+        if (this.installTask)
+            return this.installTask;
+        // Nothing to install into a manager that is already gone.
+        if (this.closed)
+            return Promise.resolve({ state: 'failed', detail: 'Application is shutting down' });
+        const run = async () => new Promise(resolve => {
+            let detail = '';
+            let settled = false;
+            let child;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.installer = undefined;
+                resolve(value);
+            };
+            // A stalled download must not wedge the runtime in 'installing' forever:
+            // the installer is stopped and the state reported as failed.
+            const timer = setTimeout(() => {
+                child?.kill();
+                const failed = { state: 'failed', detail: detail || 'Browser runtime install timed out' };
+                this.publishRuntime(failed);
+                finish(failed);
+            }, 20 * 60 * 1000);
+            try {
+                const entry = fileURLToPath(import.meta.resolve('playwright-core'));
+                child = spawn(process.execPath, [join(dirname(entry), 'cli.js'), 'install', 'chromium', '--no-progress'], {
+                    stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.publishRuntime({ state: 'failed', detail: message });
+                finish({ state: 'failed', detail: message });
+                return;
+            }
+            this.installer = { child, timer, finish };
+            const note = (chunk) => {
+                detail = chunk.toString('utf8').split('\n').filter(line => line.trim()).pop()?.slice(0, 300) ?? detail;
+            };
+            child.stdout?.on('data', note);
+            child.stderr?.on('data', note);
+            child.on('error', error => {
+                this.publishRuntime({ state: 'failed', detail: error.message });
+                finish({ state: 'failed', detail: error.message });
+            });
+            child.on('close', code => {
+                if (settled)
+                    return;
+                if (code === 0) {
+                    void this.runtimeStatus(true).then(status => {
+                        this.publishRuntime(status);
+                        finish(status);
+                    });
+                }
+                else {
+                    const failed = { state: 'failed', detail: detail || `Installer exited with code ${code}` };
+                    this.publishRuntime(failed);
+                    finish(failed);
+                }
+            });
+        });
+        this.installTask = run().finally(() => { this.installTask = undefined; });
+        return this.installTask;
+    }
+    async launch() {
+        // Tests supply a fake browser; production launches the real one below.
+        if (this.launchBrowser)
+            return await this.launchBrowser();
+        const { chromium } = await import('playwright-core');
+        const failures = [];
+        // The probe's candidates in the probe's order. The bundled Chromium is launched
+        // by the very executable the probe checked: a default headless launch selects
+        // Playwright's separate headless shell, which an install made with `--no-shell`
+        // does not have, so probing the full binary and launching the shell would report
+        // a ready runtime for a browser that cannot start.
+        for (const channel of ['chromium', 'msedge', 'chrome']) {
+            if (this.closed)
+                throw new Error('Application is shutting down');
+            const candidate = channelCandidate(channel, process.platform, () => chromium.executablePath());
+            if (!candidate || !existsSync(candidate))
+                continue;
+            try {
+                return await chromium.launch(viewLaunchOptions(channel, candidate));
+            }
+            catch (error) {
+                failures.push((error instanceof Error ? error.message : String(error)).split('\n')[0]);
+            }
+        }
+        throw new Error(`Browser runtime is not usable: ${failures.join('; ').slice(0, 1000)}`);
+    }
+    summary(session) {
+        return {
+            tabs: [...session.tabs.values()].map(tab => ({ id: tab.id, url: tab.url, title: tab.title, loading: tab.loading })),
+            ...(session.activeTabId ? { activeTabId: session.activeTabId } : {}),
+        };
+    }
+    publishTabs(sessionId, session) {
+        // A browser being torn down is no longer the session's: a replacement may
+        // already hold the id, and the old generation's late events must not speak
+        // for it.
+        if (session.closing || this.sessions.get(sessionId) !== session)
+            return;
+        this.emit('browser.view', { kind: 'tabs', sessionId, ...this.summary(session) });
+    }
+    scheduleIdleClose(sessionId, session) {
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        // A session someone is watching (streaming) is never idle-reaped; only an
+        // abandoned open browser is, so a forgotten panel cannot pin memory forever.
+        session.idleTimer = setTimeout(() => {
+            session.idleTimer = undefined;
+            // A tab still being created is work in progress, not idleness.
+            if (!session.streaming && session.pendingTabs === 0)
+                void this.closeSession(sessionId, 'idle', session);
+        }, VIEW_IDLE_CLOSE_MS);
+        session.idleTimer.unref?.();
+    }
+    async stopScreencast(tab) {
+        tab.streaming = false;
+        if (tab.pendingTimer) {
+            clearTimeout(tab.pendingTimer);
+            tab.pendingTimer = undefined;
+        }
+        tab.pendingFrame = undefined;
+        try {
+            await tab.cdp?.send('Page.stopScreencast');
+        }
+        catch { /* The page is already gone. */ }
+    }
+    /**
+     * Show one tab: the pane's current size, then its stream.
+     *
+     * Every path that makes a tab the visible one goes through here — an explicit
+     * activation, an open that completed while it still owned the selection, and
+     * the fallback chosen when the active tab closes — because a pane resized
+     * while the tab was inactive only sized the active page, and a page laid out
+     * at a stale size puts every translated click in the wrong place.
+     */
+    async showTab(session, tab) {
+        if (session.activeTabId !== tab.id)
+            return;
+        await this.queueViewportMode(session, tab);
+        // Two activations can overlap: the later one owns the pane by the time this
+        // page finishes resizing, and a stream started for the earlier tab would be
+        // a stream nobody sees — while its `streaming` flag would keep the next
+        // selection of that tab from ever starting one.
+        if (session.activeTabId !== tab.id)
+            return;
+        await this.startScreencast(session, tab);
+    }
+    /**
+     * Put one page into the session's viewport mode.
+     *
+     * Desktop sizes the page to the pane. Mobile is full emulation: the fixed
+     * phone's device metrics — `mobile: true` is what makes the meta viewport
+     * respected, with a phone's pixel density — a mobile Chrome user agent, and
+     * touch events, so the sites the pane shows answer with their mobile layouts
+     * and hover-dependent UIs behave like they do on a phone. Leaving Mobile
+     * clears the metrics and resets the user agent with an empty override —
+     * Chromium answers that with the page's own browser UA (verified live), so
+     * nothing about the page before the switch needs remembering. A switch
+     * changes the page's size, so the caller restarts the screencast for the new
+     * capture scale.
+     *
+     * Calls for one tab are serialized by `queueViewportMode`: each applies
+     * whatever the session's mode is at its turn, so a rapid toggle cannot leave
+     * a page emulated under a session that has already moved on.
+     */
+    async applyViewportMode(session, tab) {
+        const mobile = session.mode === 'mobile';
+        try {
+            if (mobile) {
+                // Full device metrics, not just dimensions. Playwright's own
+                // setViewportSize would re-issue the override with `mobile: false`, so
+                // while Mobile is on, this override is the page's only sizing
+                // authority (verified live: the metrics override yields exactly
+                // 390×844 screencast frames at a phone's pixel density).
+                await tab.cdp.send('Emulation.setDeviceMetricsOverride', {
+                    width: VIEW_MOBILE_VIEWPORT.width, height: VIEW_MOBILE_VIEWPORT.height, deviceScaleFactor: 3, mobile: true,
+                });
+            }
+            else {
+                if (tab.emulated)
+                    await tab.cdp.send('Emulation.clearDeviceMetricsOverride');
+                await tab.page.setViewportSize(session.viewport).catch(() => { });
+            }
+            if (mobile === Boolean(tab.emulated))
+                return;
+            tab.emulated = mobile;
+            await tab.cdp.send('Emulation.setUserAgentOverride', mobile
+                ? { userAgent: VIEW_MOBILE_USER_AGENT }
+                // An empty user agent resets the page to its own browser's UA.
+                : { userAgent: '' });
+            await tab.cdp.send('Emulation.setTouchEmulationEnabled', { enabled: mobile, ...(mobile ? { maxTouchPoints: 5 } : {}) });
+        }
+        catch { /* The page is gone; the next activation retries. */ }
+    }
+    /** The per-tab serialization `applyViewportMode` relies on; see its note. */
+    queueViewportMode(session, tab) {
+        const tail = (tab.modeTask ?? Promise.resolve()).catch(() => { });
+        tab.modeTask = tail.then(() => this.applyViewportMode(session, tab));
+        return tab.modeTask;
+    }
+    emitFrame(sessionId, session, tab, payload) {
+        // Frames still in flight from a replaced browser belong to nobody.
+        if (session.closing || this.sessions.get(sessionId) !== session)
+            return;
+        const size = jpegSize(Buffer.from(payload.data, 'base64'));
+        if (!size)
+            return;
+        tab.lastEmitAt = Date.now();
+        tab.seq += 1;
+        tab.imageWidth = size.width;
+        tab.imageHeight = size.height;
+        this.emit('browser.view', {
+            kind: 'frame', sessionId, tabId: tab.id, seq: tab.seq, image: payload.data,
+            imageWidth: size.width, imageHeight: size.height,
+            viewportWidth: session.viewport.width, viewportHeight: session.viewport.height,
+        });
+    }
+    async startScreencast(session, tab) {
+        if (!session.streaming || tab.streaming)
+            return;
+        tab.streaming = true;
+        tab.lastEmitAt = undefined;
+        try {
+            await tab.cdp.send('Page.startScreencast', {
+                format: 'jpeg', quality: session.quality,
+                // The viewport clamp's maxima, fixed rather than sized to the current
+                // viewport: no legal resize exceeds them, so frames are never scaled
+                // down by the caps and a resize only ever needs the restart for the new
+                // capture scale, not new caps.
+                maxWidth: 1600, maxHeight: 2200,
+                everyNthFrame: 1,
+            });
+        }
+        catch {
+            tab.streaming = false;
+        }
+    }
+    wireTab(sessionId, session, page, cdp) {
+        const tab = {
+            id: randomUUID(), page, cdp, url: '', title: '', loading: false,
+            streaming: false, seq: 0, lastEmitAt: undefined, imageWidth: session.viewport.width, imageHeight: session.viewport.height,
+        };
+        const publish = () => this.publishTabs(sessionId, session);
+        // A fragment link or a `pushState` route change commits without loading a
+        // document: `framenavigated` fires, `domcontentloaded` does not. Tracking the
+        // document request is what tells the two apart, so the commit of a new
+        // document clears the previous one's title and marks the tab loading while a
+        // same-document commit only moves the address.
+        let documentRequest;
+        page.on('request', (request) => {
+            try {
+                if (request?.isNavigationRequest?.() === true && request.frame?.() === page.mainFrame())
+                    documentRequest = request;
+            }
+            catch { /* A request with no frame is not the document's own. */ }
+        });
+        page.on('requestfailed', (request) => { if (request === documentRequest)
+            documentRequest = undefined; });
+        page.on('framenavigated', (frame) => {
+            if (frame !== page.mainFrame())
+                return;
+            tab.url = String(frame.url()).slice(0, VIEW_URL_LIMIT);
+            const newDocument = documentRequest !== undefined;
+            documentRequest = undefined;
+            if (newDocument) {
+                tab.loading = true;
+                tab.title = '';
+            }
+            publish();
+        });
+        page.on('domcontentloaded', () => {
+            tab.loading = false;
+            void page.title().then((title) => {
+                if (typeof title === 'string') {
+                    tab.title = title.slice(0, 300);
+                    publish();
+                }
+            }, () => { });
+            publish();
+        });
+        page.on('close', () => {
+            session.tabs.delete(tab.id);
+            if (session.activeTabId === tab.id) {
+                session.activeTabId = [...session.tabs.keys()][0];
+                const next = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+                if (next)
+                    void this.showTab(session, next);
+            }
+            // A tab whose page is still being created is a live session too: closing
+            // the browser here would take it away from the open that is waiting on it.
+            if (session.tabs.size === 0 && session.pendingTabs === 0)
+                void this.closeSession(sessionId, undefined, session);
+            else
+                publish();
+        });
+        page.on('crash', () => { void page.close().catch(() => { }); });
+        // A `target="_blank"` link or `window.open()` opens a page of its own; without
+        // this the destination loads in a browser nobody can see. A popup becomes a
+        // tab of the session (the cap applies to it like any other open), and it
+        // takes the pane so the user follows the link they clicked.
+        page.on('popup', (popup) => { void this.adoptPage(sessionId, session, popup); });
+        cdp.on('Page.screencastFrame', async (payload) => {
+            // Acknowledge first, always: the stream has a small outstanding-frame
+            // window, and an unacknowledged frame stalls it even when this frame is
+            // held back by the pacing window or its tab is no longer active.
+            try {
+                await cdp.send('Page.screencastFrameAck', { sessionId: payload.sessionId });
+            }
+            catch { /* Gone. */ }
+            if (!tab.streaming || session.activeTabId !== tab.id || session.closing)
+                return;
+            const now = Date.now();
+            if (frameGate(now, tab.lastEmitAt, VIEW_FRAME_MIN_INTERVAL_MS)) {
+                if (tab.pendingTimer) {
+                    clearTimeout(tab.pendingTimer);
+                    tab.pendingTimer = undefined;
+                }
+                tab.pendingFrame = undefined;
+                this.emitFrame(sessionId, session, tab, payload);
+                return;
+            }
+            // Inside the pacing window: keep only the newest image and deliver it
+            // when the window opens. Dropping it outright would leave the panel on an
+            // older frame forever when the page's last update lands here.
+            tab.pendingFrame = payload;
+            if (tab.pendingTimer)
+                return;
+            const wait = Math.max(0, VIEW_FRAME_MIN_INTERVAL_MS - (now - (tab.lastEmitAt ?? now)));
+            tab.pendingTimer = setTimeout(() => {
+                tab.pendingTimer = undefined;
+                const pending = tab.pendingFrame;
+                tab.pendingFrame = undefined;
+                if (!pending || !tab.streaming || session.activeTabId !== tab.id || session.closing)
+                    return;
+                this.emitFrame(sessionId, session, tab, pending);
+            }, wait);
+            tab.pendingTimer.unref?.();
+        });
+        session.tabs.set(tab.id, tab);
+        return tab;
+    }
+    /**
+     * A frame straight from the page, for a stream that is already running.
+     *
+     * A pane that reattaches (a renderer reload) has no image of its own, and a
+     * static page produces no new screencast frames, so the screencast's own
+     * stream cannot supply one. A screenshot is bounded and always reflects the
+     * page as it is now.
+     */
+    async captureFrame(sessionId, session, tab) {
+        try {
+            const shot = await tab.cdp?.send('Page.captureScreenshot', { format: 'jpeg', quality: session.quality });
+            if (typeof shot?.data !== 'string')
+                return;
+            if (!tab.streaming || session.activeTabId !== tab.id || session.closing)
+                return;
+            this.emitFrame(sessionId, session, tab, { data: shot.data, sessionId: 'capture' });
+        }
+        catch { /* The page may be mid-navigation; the stream supplies the next frame. */ }
+    }
+    /**
+     * A page the browser opened on its own, adopted as a tab of the session.
+     *
+     * The page is already live, so it only needs a CDP session and its pane
+     * geometry. Past the tab cap the popup is closed rather than left running as an
+     * invisible page: the cap states one bound for everything the browser holds.
+     */
+    async adoptPage(sessionId, session, page) {
+        if (session.closing) {
+            await Promise.resolve().then(() => page.close()).catch(() => { });
+            return;
+        }
+        if (session.tabs.size + session.pendingTabs >= VIEW_TAB_LIMIT) {
+            await Promise.resolve().then(() => page.close()).catch(() => { });
+            return;
+        }
+        session.pendingTabs += 1;
+        try {
+            const cdp = await page.context().newCDPSession(page);
+            const previous = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+            if (previous)
+                await this.stopScreencast(previous);
+            // Adoption yields before it takes the pane, so a tab activated meanwhile is
+            // streaming by now; assigning the popup would discard its frames while its
+            // `streaming` flag stayed on, and reselecting it would request neither a new
+            // screencast nor a screenshot. Stop the tab that actually holds the pane, as
+            // an open does; the loop is bounded by a stream really running, because a
+            // stop with nothing to do cannot have yielded.
+            let selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+            while (selected && selected.streaming) {
+                await this.stopScreencast(selected);
+                selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+            }
+            if (session.closing) {
+                await page.close().catch(() => { });
+                return;
+            }
+            const tab = this.wireTab(sessionId, session, page, cdp);
+            await this.queueViewportMode(session, tab);
+            // The mode application yields, so a tab the user activated meanwhile can
+            // be streaming: it stops before the popup takes the pane, or it would
+            // stream on with nobody watching — the same reason the loop above ran.
+            selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+            while (selected && selected.streaming) {
+                await this.stopScreencast(selected);
+                selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+            }
+            if (session.closing) {
+                await page.close().catch(() => { });
+                return;
+            }
+            session.activeTabId = tab.id;
+            // The popup has usually navigated before it reached us, so its landing URL
+            // is read from the page rather than waiting for an event that already fired.
+            tab.url = String(page.url?.() ?? '').slice(0, VIEW_URL_LIMIT);
+            void page.title?.().then((title) => {
+                if (typeof title === 'string' && title) {
+                    tab.title = title.slice(0, 300);
+                    this.publishTabs(sessionId, session);
+                }
+            }, () => { });
+            await this.startScreencast(session, tab);
+            this.publishTabs(sessionId, session);
+        }
+        catch {
+            await Promise.resolve().then(() => page.close()).catch(() => { });
+        }
+        finally {
+            session.pendingTabs -= 1;
+        }
+    }
+    async ensureSession(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing) {
+            this.scheduleIdleClose(sessionId, existing);
+            return existing;
+        }
+        // A second open can arrive while the first is still launching (Enter pressed
+        // twice). It joins that launch instead of starting a second browser whose
+        // session record would overwrite the first and leave it unreachable.
+        const inflight = this.launching.get(sessionId);
+        if (inflight)
+            return await inflight;
+        if (this.sessions.size + this.launching.size >= VIEW_SESSION_LIMIT)
+            throw new Error('Too many open panel browsers; close one first');
+        if (this.closed)
+            throw new Error('Application is shutting down');
+        const starting = (async () => {
+            const browser = await this.launch();
+            // Shutdown may have finished while the launch was in flight: the browser
+            // that arrived late belongs to nobody, so it is closed here rather than
+            // inserted into a manager that has already visited its sessions.
+            if (this.closed) {
+                await Promise.resolve().then(() => browser.close()).catch(() => { });
+                throw new Error('Application is shutting down');
+            }
+            // A release that landed while this launch was in flight has already closed
+            // whatever it found; the browser this launch just produced belongs to the
+            // session that no longer exists, so it goes the same way.
+            if (this.released.delete(sessionId)) {
+                await Promise.resolve().then(() => browser.close()).catch(() => { });
+                throw new Error('That session was deleted.');
+            }
+            const desired = this.desired.get(sessionId);
+            const session = {
+                browser, tabs: new Map(), activeTabId: undefined, pendingTabs: 0,
+                viewport: desired?.viewport ?? clampViewport(undefined, undefined),
+                mode: desired?.mode ?? 'desktop',
+                streaming: desired !== undefined, quality: desired?.quality ?? VIEW_STREAM_QUALITY, idleTimer: undefined,
+            };
+            this.sessions.set(sessionId, session);
+            this.scheduleIdleClose(sessionId, session);
+            return session;
+        })();
+        this.launching.set(sessionId, starting);
+        try {
+            return await starting;
+        }
+        finally {
+            this.launching.delete(sessionId);
+        }
+    }
+    /**
+     * The session's browser context, created once.
+     *
+     * One context per session is what makes the tabs one browser: cookies, local
+     * storage and cache are shared across the session's pages, and sessions stay
+     * isolated from each other.
+     */
+    async contextFor(session) {
+        if (session.context)
+            return session.context;
+        session.contextTask ??= Promise.resolve()
+            .then(() => session.browser.newContext({ viewport: { ...session.viewport }, acceptDownloads: false }))
+            .then((context) => { session.context = context; return context; });
+        return await session.contextTask;
+    }
+    async openTab(sessionId, url, signal) {
+        const target = browserViewUrl(url);
+        const session = await this.ensureSession(sessionId);
+        // The launch is the longest wait here, and the one a stop usually arrives
+        // during: a cancelled call returns before creating a page at all.
+        signal?.throwIfAborted();
+        if (session.closing)
+            throw new Error('Browser is closing; retry shortly');
+        // Capacity is reserved before the first await. Stopping the previous
+        // screencast and creating the page both yield, so a burst of overlapping
+        // opens would otherwise all pass a plain `tabs.size` check and exceed the
+        // cap with pages nobody intended to keep.
+        if (session.tabs.size + session.pendingTabs >= VIEW_TAB_LIMIT)
+            throw new Error('Close a tab before opening another (maximum 6)');
+        session.pendingTabs += 1;
+        let reserved = true;
+        const release = () => {
+            if (!reserved)
+                return;
+            reserved = false;
+            session.pendingTabs -= 1;
+        };
+        const previous = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+        try {
+            if (previous)
+                await this.stopScreencast(previous);
+            const context = await this.contextFor(session);
+            const page = await context.newPage();
+            const cdp = await page.context().newCDPSession(page);
+            const tab = this.wireTab(sessionId, session, page, cdp);
+            // The context was created at the viewport of the first open; a tab opened
+            // after the pane was resized has to match the pane it will be shown in, or
+            // its layout and every translated click would use the old size. The mode's
+            // emulation rides along on the same call.
+            await this.queueViewportMode(session, tab);
+            // The reservation has become a real tab; the cap now counts it directly.
+            release();
+            // The pane follows the newest open. The selection may have moved while this
+            // page was being created, so it is re-read and stopped until it is this
+            // tab's: a stream left running for a tab nobody sees discards its frames
+            // while keeping `streaming` true, and selecting that tab again would then
+            // start nothing. The loop is bounded by the tab actually streaming — a stop
+            // with nothing to do cannot have yielded to another activation, so the
+            // assignment that follows is atomic.
+            let selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+            while (selected && selected.id !== tab.id && selected.streaming) {
+                await this.stopScreencast(selected);
+                // An activation can land during that await; stop whatever the selection
+                // has become before this tab takes it.
+                selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+            }
+            // Creating the page stops the previous screencast, and both yield: a run
+            // stopped while its tab was being made must not select it or load the URL
+            // afterwards, so only the unfinished tab is closed here — the rest of the
+            // shared browser the user is watching stays exactly as it is.
+            if (signal?.aborted) {
+                await this.discardTab(sessionId, session, tab, previous);
+                // The pane never left the tab it was on, but this open had already stopped that tab's
+                // stream: without restarting it the panel would sit frozen on a tab that still accepts
+                // input. `discardTab` restores the stream only for a tab that held the pane, which this
+                // one never did.
+                const survivor = session.activeTabId === undefined ? undefined : session.tabs.get(session.activeTabId);
+                if (survivor && !survivor.streaming)
+                    await this.showTab(session, survivor);
+                signal.throwIfAborted();
+            }
+            session.activeTabId = tab.id;
+            // The pane's target changes here, before the navigation it waits for: an
+            // input request naming no tab of its own would otherwise land on a page the
+            // panel is not showing yet, and the strip would still name the old one.
+            this.publishTabs(sessionId, session);
+            try {
+                await page.goto(target, { waitUntil: 'domcontentloaded', timeout: VIEW_GOTO_TIMEOUT_MS });
+            }
+            catch (error) {
+                // A page that failed its first navigation is not a tab worth keeping: an
+                // address-bar retry would otherwise stack error pages behind it.
+                await this.discardTab(sessionId, session, tab, previous);
+                throw error;
+            }
+            // The URL the tab shows is the one the page actually landed on
+            // (`framenavigated` records redirects); the requested target may differ.
+            // A slow open that finished after a later one took the selection must not
+            // start a stream for a tab nobody is looking at: its frames would be
+            // discarded while `streaming` stayed true, and activating it later would
+            // find the stream already "running" and never ask for a fresh frame.
+            if (session.activeTabId === tab.id)
+                await this.showTab(session, tab);
+            this.publishTabs(sessionId, session);
+            // The pane follows an open, whoever drove it: an agent's first tab is the
+            // moment the panel should be on screen, and expanding an open pane is a
+            // no-op, so the user's own opens can simply ride the same event. A session
+            // being torn down is nobody's pane to open.
+            if (!session.closing)
+                this.emit('browser.panel.opened', { sessionId });
+            return { tabId: tab.id };
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Remove one tab an open created and did not finish.
+     *
+     * The page itself is closed too — a discarded page still runs and still counts
+     * against the browser, and the tab cap only counts pages it holds. Only the
+     * unfinished tab goes: the rest of the shared browser, which the user may be
+     * watching, is left as it is.
+     */
+    async discardTab(sessionId, session, tab, previous) {
+        session.tabs.delete(tab.id);
+        // Only the tab that is still selected may hand the pane back: an overlapping
+        // open that succeeded meanwhile owns it, and clearing its selection would
+        // leave a visible tab that input cannot address. The tab that owned the pane
+        // before this open may itself have been closed while the open was in flight,
+        // so a survivor is chosen instead.
+        if (session.activeTabId === tab.id) {
+            const fallback = previous && session.tabs.has(previous.id) ? previous : [...session.tabs.values()][0];
+            session.activeTabId = fallback?.id;
+            if (fallback)
+                void this.showTab(session, fallback);
+        }
+        await tab.cdp?.detach().catch(() => { });
+        await tab.page.close().catch(() => { });
+        // Another open may still be creating its page: the session is not empty.
+        if (session.tabs.size === 0 && session.pendingTabs === 0)
+            void this.closeSession(sessionId, undefined, session);
+    }
+    activeOrNamed(session, tabId) {
+        // An explicit id names one tab: falling back to the selection would let a
+        // repeated close of a tab that is already gone destroy an unrelated one.
+        if (tabId !== undefined) {
+            const named = session.tabs.get(tabId);
+            if (!named)
+                throw new Error(`No browser tab is open for this session with id ${tabId}`);
+            return named;
+        }
+        const tab = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+        if (!tab)
+            throw new Error('No browser tab is open for this session');
+        return tab;
+    }
+    async navigate(sessionId, url, tabId) {
+        const target = browserViewUrl(url);
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error('No browser tab is open for this session');
+        const tab = this.activeOrNamed(session, tabId);
+        this.scheduleIdleClose(sessionId, session);
+        await tab.page.goto(target, { waitUntil: 'domcontentloaded', timeout: VIEW_GOTO_TIMEOUT_MS });
+        // `framenavigated` owns the tab's URL (it records where redirects landed);
+        // overwriting it here would describe an address the page is not showing.
+        this.publishTabs(sessionId, session);
+        // A navigation is new content in the pane: the same pop-up an open gets.
+        if (!session.closing)
+            this.emit('browser.panel.opened', { sessionId });
+    }
+    async activateTab(sessionId, tabId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || !session.tabs.has(tabId))
+            throw new Error('Unknown browser tab for this session');
+        const previous = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+        if (previous && previous.id !== tabId)
+            await this.stopScreencast(previous);
+        // Another activation can have taken the pane while this one waited for that
+        // stop: whatever holds the selection now gives up its stream too, or its flag
+        // would keep its next selection from ever starting one. Bounded by a stream
+        // really running, as everywhere else that waits on a stop.
+        let holding = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+        while (holding && holding.streaming && holding.id !== tabId) {
+            await this.stopScreencast(holding);
+            holding = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+        }
+        // The stop yields, so the tab being activated can have closed in that window.
+        // Naming it anyway would strand the pane on an id nothing can address, with
+        // the survivor's stream stopped and every implicit request refused.
+        if (!session.tabs.has(tabId)) {
+            const survivor = previous && session.tabs.has(previous.id) ? previous : [...session.tabs.values()][0];
+            session.activeTabId = survivor?.id;
+            if (survivor)
+                await this.showTab(session, survivor);
+            this.publishTabs(sessionId, session);
+            return;
+        }
+        session.activeTabId = tabId;
+        const tab = session.tabs.get(tabId);
+        // A pane resized while this tab was inactive only sized the active page. The
+        // page is brought to the session's current viewport before it streams, so
+        // input translation and the displayed frame agree on the page's size.
+        await this.showTab(session, tab);
+        this.scheduleIdleClose(sessionId, session);
+        this.publishTabs(sessionId, session);
+    }
+    async closeTab(sessionId, tabId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        const tab = this.activeOrNamed(session, tabId);
+        await this.stopScreencast(tab);
+        await tab.page.close().catch(() => { });
+    }
+    /**
+     * Panel geometry: the page viewport and the streamed frame target follow the
+     * pane, or Mobile mode's fixed phone viewport with its emulation.
+     *
+     * The request is remembered even when the session has no browser yet: a panel
+     * mounts and asks for frames before its first tab is opened, and the open
+     * adopts the remembered request. Disabling forgets it, so a collapsed panel
+     * that is later reopened makes a fresh, explicitly desired request.
+     */
+    async configureStream(sessionId, options) {
+        if (!options.enabled) {
+            this.desired.delete(sessionId);
+            const session = this.sessions.get(sessionId);
+            if (!session)
+                return;
+            session.streaming = false;
+            for (const tab of session.tabs.values()) {
+                // A newer enable took the pane back while this disable was stopping tabs:
+                // its stream stands, and the stops still owed belong to it, not this one.
+                if (session.streaming)
+                    return;
+                await this.stopScreencast(tab);
+            }
+            this.scheduleIdleClose(sessionId, session);
+            return;
+        }
+        const mode = options.mode === 'mobile' ? 'mobile' : 'desktop';
+        const viewport = mode === 'mobile' ? { ...VIEW_MOBILE_VIEWPORT } : clampViewport(options.viewportWidth, options.viewportHeight);
+        const quality = Number.isSafeInteger(options.quality) ? Math.max(30, Math.min(90, options.quality)) : VIEW_STREAM_QUALITY;
+        this.desired.set(sessionId, { viewport, quality, mode });
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        session.streaming = true;
+        const modeChanged = mode !== session.mode;
+        const resized = viewport.width !== session.viewport.width || viewport.height !== session.viewport.height;
+        session.mode = mode;
+        session.viewport = viewport;
+        session.quality = quality;
+        this.scheduleIdleClose(sessionId, session);
+        const active = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+        if (!active)
+            return;
+        if (resized || modeChanged) {
+            // A mode switch is more than a resize: the page is put into or taken out
+            // of the phone's emulation.
+            await this.queueViewportMode(session, active);
+            // Applying yields, so the selection can have moved by the time it lands:
+            // the tab that lost the pane stops streaming, and the pane's new owner
+            // gets the fresh geometry through the guarded path.
+            if (session.activeTabId !== active.id) {
+                await this.stopScreencast(active);
+                const selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+                if (selected)
+                    await this.showTab(session, selected);
+                return;
+            }
+            // The screencast bakes its capture scale in at start: a page resized under
+            // a running stream delivers frames scaled to the old size (verified live —
+            // a 560×800 page after a 390-wide capture arrives 390×557), so the stream
+            // restarts to pick up the new geometry. The pane holds its last painted
+            // frame through the gap, so the UI never blanks while it happens.
+            await this.stopScreencast(active);
+            // The stop yields, so the selection can have moved by the time it lands:
+            // restarting this tab would stream one nobody sees while leaving its flag
+            // on, and the pane's new owner would wait for frames that never come.
+            if (session.activeTabId !== active.id) {
+                const selected = session.activeTabId ? session.tabs.get(session.activeTabId) : undefined;
+                if (selected)
+                    await this.showTab(session, selected);
+                return;
+            }
+        }
+        const reattached = active.streaming;
+        await this.startScreencast(session, active);
+        // A stream that was already running sends nothing more for a page that is
+        // not repainting, so a pane that returned (renderer reload) would have no
+        // image; asking for one now makes the resumed panel show the page as it is.
+        if (reattached)
+            await this.captureFrame(sessionId, session, active);
+    }
+    /**
+     * Panel input, translated from image pixels to page CSS pixels and forwarded
+     * as CDP input events. The panel never holds a CDP connection of its own.
+     */
+    async input(sessionId, payload) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error('No browser tab is open for this session');
+        const tab = this.activeOrNamed(session, typeof payload.tabId === 'string' ? payload.tabId : undefined);
+        this.scheduleIdleClose(sessionId, session);
+        const modifiers = modifierMask(payload.modifiers);
+        const scale = {
+            x: tab.imageWidth / Math.max(1, session.viewport.width),
+            y: tab.imageHeight / Math.max(1, session.viewport.height),
+        };
+        const point = () => {
+            const x = Number(payload.x);
+            const y = Number(payload.y);
+            if (!Number.isSafeInteger(x) || !Number.isSafeInteger(y) || x < 0 || y < 0 || x > tab.imageWidth || y > tab.imageHeight) {
+                throw new Error(`Pointer coordinates must be image pixels within 0..${tab.imageWidth}, 0..${tab.imageHeight}`);
+            }
+            return { x: Math.round(x / scale.x), y: Math.round(y / scale.y) };
+        };
+        const button = (value) => value === 'middle' || value === 'right' ? value : 'left';
+        const type = payload.type;
+        if (type === 'move') {
+            const at = point();
+            // A held button during a drag: the mask is what makes the page treat the
+            // movement as dragging rather than hovering.
+            const pressed = payload.pressed === true;
+            const name = pressed ? button(payload.button) : 'none';
+            const buttons = pressed ? (name === 'right' ? 2 : name === 'middle' ? 4 : 1) : 0;
+            await tab.cdp.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: at.x, y: at.y, button: name, buttons, modifiers });
+        }
+        else if (type === 'down' || type === 'up') {
+            const at = point();
+            await tab.cdp.send('Input.dispatchMouseEvent', {
+                type: type === 'down' ? 'mousePressed' : 'mouseReleased', x: at.x, y: at.y,
+                button: button(payload.button), clickCount: 1, modifiers,
+            });
+        }
+        else if (type === 'click') {
+            const at = point();
+            const count = Number.isSafeInteger(payload.count) && payload.count >= 1 && payload.count <= 3 ? payload.count : 1;
+            const name = button(payload.button);
+            await tab.cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: at.x, y: at.y, button: name, clickCount: count, modifiers });
+            await tab.cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: at.x, y: at.y, button: name, clickCount: count, modifiers });
+        }
+        else if (type === 'wheel') {
+            const at = point();
+            const deltaX = Number(payload.deltaX);
+            const deltaY = Number(payload.deltaY);
+            if (!Number.isFinite(deltaX) || !Number.isFinite(deltaY) || Math.abs(deltaX) > 3500 || Math.abs(deltaY) > 3500)
+                throw new Error('wheel deltas must be numbers within ±3500');
+            await tab.cdp.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: at.x, y: at.y, deltaX: Math.round(deltaX), deltaY: Math.round(deltaY), button: 'none', modifiers });
+        }
+        else if (type === 'key') {
+            const down = payload.down === true;
+            const descriptor = keyDescriptor(String(payload.key ?? ''), typeof payload.code === 'string' ? payload.code : undefined, modifiers);
+            // The character a key inserts belongs to the key-down; a key-up carries
+            // none, so the page does not see the text twice.
+            const text = down ? descriptor.text : undefined;
+            // A macOS browser performs its editing gestures as named commands on the
+            // key-down, not from the key event itself; see `macEditingCommands`.
+            const commands = process.platform === 'darwin' && down ? macEditingCommands(descriptor.key, modifiers) : [];
+            await tab.cdp.send('Input.dispatchKeyEvent', {
+                type: down ? (text === undefined ? 'rawKeyDown' : 'keyDown') : 'keyUp',
+                key: descriptor.key, code: descriptor.code,
+                windowsVirtualKeyCode: descriptor.windowsVirtualKeyCode, nativeKeyCodes: descriptor.nativeKeyCodes, modifiers,
+                ...(text === undefined ? {} : { text, unmodifiedText: text }),
+                ...(commands.length ? { commands } : {}),
+            });
+        }
+        else if (type === 'text') {
+            const text = payload.text;
+            if (typeof text !== 'string' || !text.length || text.length > 2000)
+                throw new Error('text must be a string of at most 2000 characters');
+            await tab.cdp.send('Input.insertText', { text });
+        }
+        else {
+            throw new Error('Unsupported browser input type');
+        }
+    }
+    /**
+     * The cursor shape the page would show at a pane point, in image pixels.
+     *
+     * The pane draws frames and forwards input, so the page's own pointer is never
+     * visible: a link must still read as a link. The answer is the page's computed
+     * `cursor` at that point, bounded and lower-cased for the panel to draw.
+     */
+    async cursorAt(sessionId, x, y, tabId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return 'default';
+        const tab = this.activeOrNamed(session, tabId);
+        this.scheduleIdleClose(sessionId, session);
+        const px = Number(x);
+        const py = Number(y);
+        // A point outside the frame the pane is showing names nothing in the page.
+        if (!Number.isSafeInteger(px) || !Number.isSafeInteger(py) || px < 0 || py < 0 || px > tab.imageWidth || py > tab.imageHeight)
+            return 'default';
+        const scaleX = tab.imageWidth / Math.max(1, session.viewport.width);
+        const scaleY = tab.imageHeight / Math.max(1, session.viewport.height);
+        const cursor = await tab.page.evaluate(`${CURSOR_AT}({ x: ${Math.round(px / scaleX)}, y: ${Math.round(py / scaleY)} })`)
+            .catch(() => 'default');
+        return typeof cursor === 'string' && /^[a-z-]{1,40}$/.test(cursor) ? cursor : 'default';
+    }
+    /**
+     * The text a copy or cut would take from the page, for the viewer's clipboard.
+     *
+     * Copy and cut travel to the page as key events, so the text they produce stays
+     * in the browser that owns the page. The viewer reads it back here and writes
+     * it to its own clipboard, which is what makes a copy on a paired machine land
+     * on the machine the user is sitting at. The viewer reads before it forwards
+     * the key: a cut collapses the selection it just removed.
+     */
+    async selectionText(sessionId, tabId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return '';
+        const tab = this.activeOrNamed(session, tabId);
+        this.scheduleIdleClose(sessionId, session);
+        const text = await this.selectionInPage(tab.page);
+        // A selection past the bound is refused rather than truncated: the viewer
+        // writes what it read and then forwards the key, and a cut removes the whole
+        // selection from the page — a prefix on the clipboard would lose the rest.
+        if (typeof text !== 'string')
+            return '';
+        if (text.length > VIEW_CLIPBOARD_LIMIT)
+            throw new Error(`The selection is too large to copy (${text.length} characters)`);
+        return text;
+    }
+    /**
+     * The focused document's selection, including one made inside a frame.
+     *
+     * The top document is asked first, and it says when focus is inside a frame:
+     * there the iframe element is the active element and the top selection is
+     * empty, so each frame is asked in turn. Playwright evaluates inside a
+     * cross-origin frame as well, because the evaluation runs over CDP rather than
+     * through the page's own script context.
+     */
+    async selectionInPage(page) {
+        const top = await page.evaluate(SELECTION_STATE).catch(() => undefined);
+        if (typeof top?.text === 'string' && top.text)
+            return top.text;
+        // The top document answered "no selection and focus is mine": no frame holds it.
+        if (top?.inFrame === false)
+            return '';
+        let frames = [];
+        try {
+            const main = page.mainFrame();
+            frames = page.frames().filter((frame) => frame !== main);
+        }
+        catch {
+            return '';
+        }
+        // A frame keeps its selection after focus moves elsewhere, so an unfocused
+        // frame's text is not the user's. Only the focused document's selection is
+        // the answer, even an empty one; a focused frame whose own active element is
+        // another iframe is a step on the way to a deeper frame, not the caret itself.
+        let fallback = '';
+        let focusedAnswered = false;
+        for (const frame of frames) {
+            const state = await frame.evaluate(SELECTION_STATE).catch(() => undefined);
+            const text = typeof state?.text === 'string' ? state.text : '';
+            if (state?.focused === true) {
+                if (state?.inFrame === false)
+                    return text;
+                focusedAnswered = true;
+                continue;
+            }
+            if (!fallback && text)
+                fallback = text;
+        }
+        // The focus is deeper than the frames readable here: their stale text is not it.
+        return focusedAnswered ? '' : fallback;
+    }
+    /**
+     * Agent operations on the session's panel browser.
+     *
+     * The panel browser belongs to the user as much as to the agent: an operation
+     * that fails, stalls or is cancelled ends only that call — never the browser —
+     * and tab-affecting operations publish tabs so the pane follows along.
+     */
+    async boundedAgentOperation(signal, pending, timeoutMessage) {
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); };
+            const fail = (error) => { if (settled)
+                return; settled = true; cleanup(); reject(error); };
+            const abort = () => fail(signal.reason);
+            const timer = setTimeout(() => fail(new Error(timeoutMessage)), 10_000);
+            signal.addEventListener('abort', abort, { once: true });
+            if (signal.aborted)
+                abort();
+            pending.then(value => { if (!settled) {
+                settled = true;
+                cleanup();
+                resolve(value);
+            } }, fail);
+        });
+    }
+    agentTarget(sessionId, tabId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.closing)
+            throw new Error('No browser tab is open for this session; open one first');
+        this.scheduleIdleClose(sessionId, session);
+        return { session, tab: this.activeOrNamed(session, tabId) };
+    }
+    /** The session's tabs as the agent sees them; a panel with no browser yet is simply empty. */
+    agentTabs(sessionId) {
+        return this.sessionSummaries()[sessionId] ?? { tabs: [] };
+    }
+    /** Step a tab through its history or reload it, for the agent and the panel's toolbar alike. */
+    async go(sessionId, kind, tabId) {
+        const { session, tab } = this.agentTarget(sessionId, tabId);
+        if (kind === 'back')
+            await tab.page.goBack({ waitUntil: 'domcontentloaded', timeout: VIEW_GOTO_TIMEOUT_MS });
+        else if (kind === 'forward')
+            await tab.page.goForward({ waitUntil: 'domcontentloaded', timeout: VIEW_GOTO_TIMEOUT_MS });
+        else
+            await tab.page.reload({ waitUntil: 'domcontentloaded', timeout: VIEW_GOTO_TIMEOUT_MS });
+        this.publishTabs(sessionId, session);
+    }
+    async agentSnapshot(sessionId, tabId, signal) {
+        const { tab } = this.agentTarget(sessionId, tabId);
+        const observation = tab.page.evaluate(observePage, { sessionId, tabId: tab.id, errors: [] });
+        const output = await this.boundedAgentOperation(signal, observation, 'Browser snapshot exceeded the 10-second observation timeout.');
+        return observationResult(output, { sessionId, tabId: tab.id });
+    }
+    async agentClick(sessionId, options, signal) {
+        const { tab } = this.agentTarget(sessionId, options.tabId);
+        await this.boundedAgentOperation(signal, tab.page.locator(options.selector).click({ button: options.button, timeout: 10_000, signal }), `Browser click exceeded the 10-second timeout; re-snapshot and retry.`);
+    }
+    async agentFill(sessionId, options, signal) {
+        const { tab } = this.agentTarget(sessionId, options.tabId);
+        await this.boundedAgentOperation(signal, tab.page.locator(options.selector).fill(options.value, { timeout: 10_000, signal }), 'Browser fill exceeded the 10-second timeout; re-snapshot and retry.');
+    }
+    async agentPress(sessionId, options, signal) {
+        const { tab } = this.agentTarget(sessionId, options.tabId);
+        // The keypress belongs to this call alone: a focus that resolves after the call
+        // was cancelled or timed out must not dispatch into the shared browser, where it
+        // could submit a form nobody is driving anymore.
+        let callerGone = false;
+        const sequence = (async () => {
+            if (options.selector)
+                await tab.page.locator(options.selector).focus({ timeout: 10_000, signal });
+            if (callerGone || signal.aborted)
+                return;
+            await tab.page.keyboard.press(options.key);
+        })();
+        try {
+            await this.boundedAgentOperation(signal, sequence, `Browser press of ${options.key} exceeded the 10-second timeout.`);
+        }
+        finally {
+            callerGone = true;
+        }
+    }
+    async agentScroll(sessionId, options, signal) {
+        const { tab } = this.agentTarget(sessionId, options.tabId);
+        await this.boundedAgentOperation(signal, tab.page.mouse.wheel(0, options.deltaY), 'Browser scroll exceeded the 10-second timeout.');
+    }
+    async agentWait(sessionId, options, signal) {
+        const { tab } = this.agentTarget(sessionId, options.tabId);
+        await this.boundedAgentOperation(signal, tab.page.locator(options.selector).waitFor({ state: 'visible', timeout: 10_000, signal }), `Browser wait for ${options.selector} exceeded the 10-second timeout.`);
+    }
+    async agentScreenshot(sessionId, tabId, signal) {
+        const { session, tab } = this.agentTarget(sessionId, tabId);
+        const capture = tab.page.screenshot({ type: 'jpeg', quality: 60, timeout: 10_000 });
+        const data = await this.boundedAgentOperation(signal, capture, 'Browser screenshot exceeded the 10-second timeout.');
+        return { tabId: tab.id, data, width: session.viewport.width, height: session.viewport.height };
+    }
+    async closeSession(sessionId, reason, expected) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.closing)
+            return;
+        // A teardown that started for an older generation must not close the
+        // replacement that took its id in the meantime.
+        if (expected !== undefined && session !== expected)
+            return;
+        session.closing = (async () => {
+            this.sessions.delete(sessionId);
+            if (session.idleTimer)
+                clearTimeout(session.idleTimer);
+            await Promise.all([...session.tabs.values()].map(tab => this.stopScreencast(tab)));
+            // Playwright transport shutdown is not reliably awaitable; own the
+            // rejection and let the browser close land whenever it lands.
+            await Promise.resolve().then(() => session.browser.close()).catch(() => { });
+            // A new browser may already hold this session id; its pane has content of
+            // its own, so the old generation stays silent.
+            if (this.sessions.has(sessionId))
+                return;
+            this.emit('browser.view', { kind: 'gone', sessionId, ...(reason ? { reason } : {}) });
+        })();
+        await session.closing;
+    }
+    sessionSummaries() {
+        const result = {};
+        for (const [sessionId, session] of this.sessions)
+            result[sessionId] = this.summary(session);
+        return result;
+    }
+    /**
+     * Release one session's panel browser now.
+     *
+     * A deleted session will never stream again, so waiting for its idle timeout
+     * would keep a whole browser, and one of the four session slots, alive for ten
+     * minutes for a pane nobody can open.
+     */
+    async release(sessionId, reason) {
+        // Marked before the close, so a launch finishing in between still sees the
+        // release; the marker is dropped once no launch can still be holding it.
+        this.released.add(sessionId);
+        try {
+            await this.closeSession(sessionId, reason);
+        }
+        finally {
+            if (!this.launching.has(sessionId))
+                this.released.delete(sessionId);
+        }
+    }
+    /** Engine shutdown: no panel browser outlives the process. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // A download in progress belongs to this engine: its child is terminated and
+        // the request waiting on it is answered, rather than left to the process
+        // exit and its twenty-minute timer.
+        if (this.installer) {
+            const { child, finish } = this.installer;
+            try {
+                child.kill();
+            }
+            catch { /* Already gone. */ }
+            const stopped = { state: 'failed', detail: 'Application is shutting down' };
+            this.publishRuntime(stopped);
+            finish(stopped);
+        }
+        // A launch already in flight is awaited before the last sweep: it inserts its
+        // session while this loop is running, and a browser nobody then visits would
+        // outlive the engine. The wait is bounded because a launch may never settle.
+        const pending = [...this.launching.values()];
+        if (pending.length) {
+            await Promise.race([
+                Promise.allSettled(pending),
+                new Promise(resolve => { const timer = setTimeout(resolve, 5_000); timer.unref?.(); }),
+            ]);
+        }
+        await Promise.all([...this.sessions.keys()].map(sessionId => this.closeSession(sessionId)));
+        // A launch that landed after the bound closed itself in `ensureSession`.
+    }
+}