@xingular/harness 1.0.0 → 1.1.1

package/dist/sdk/annotations/bridge.js

@@ -0,0 +1,264 @@
+// The page bridge (PROP-0018): page notes in a web view that has no DevTools port, such as a Tauri
+// window on macOS. The developer loads one script into their app while developing it; the script
+// carries the page helper and pulls operations from this loopback server, answering each with the
+// helper's JSON. Only 127.0.0.1 listens, every request carries the bridge token, and everything a
+// window answers is untrusted page data.
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { readJson, writeJson } from "../core/fs.js";
+import { PAGE_SCRIPT } from "./pageScript.js";
+const POLL_MS = 20_000;
+const GONE_MS = 45_000;
+const CALL_MS = 10_000;
+const MAX_BODY = 1_000_000;
+const MAX_WINDOWS = 32;
+const bounded = (value, size) => (typeof value === 'string' ? Array.from(value).slice(0, size).join('') : '');
+/** The script a window loads: the page helper plus a loop that pulls operations from the bridge. */
+export function bridgeScript(base, token) {
+    const helper = PAGE_SCRIPT.replace('__ARGS__', () => '__op');
+    return `(() => {
+  if (window.__harnessPageNotesBridge) return
+  window.__harnessPageNotesBridge = true
+  const base = ${JSON.stringify(base)}
+  const token = ${JSON.stringify(token)}
+  const call = (__op) => ${helper}
+  let windowId = null
+  const post = (path, body) => fetch(base + path, { method: 'POST', headers: { 'content-type': 'text/plain' }, body: JSON.stringify({ token, ...body }) })
+    .then(response => response.ok ? response.json() : Promise.reject(new Error(String(response.status))))
+  const pause = ms => new Promise(resolve => setTimeout(resolve, ms))
+  const loop = async () => {
+    for (;;) {
+      try {
+        if (!windowId) windowId = (await post('/register', { url: location.href, title: document.title })).windowId
+        const query = '?token=' + encodeURIComponent(token) + '&window=' + encodeURIComponent(windowId) + '&url=' + encodeURIComponent(location.href.slice(0, 2000)) + '&title=' + encodeURIComponent(document.title.slice(0, 200))
+        const response = await fetch(base + '/poll' + query)
+        if (response.status === 410) { windowId = null; continue }
+        if (response.status !== 200) { if (response.status !== 204) await pause(2000); continue }
+        const { id, operation } = await response.json()
+        let reply
+        try { reply = call(operation) } catch (error) { reply = JSON.stringify({ ok: false, error: String(error && error.message || error) }) }
+        await post('/reply', { window: windowId, id, reply })
+      } catch {
+        await pause(2000)
+      }
+    }
+  }
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', loop, { once: true })
+  else loop()
+})()
+`;
+}
+export class NotesBridge {
+    options;
+    server = null;
+    starting = null;
+    info = null;
+    windows = new Map();
+    nextWindow = 1;
+    nextCall = 1;
+    constructor(options) {
+        this.options = options;
+    }
+    settingsFile() {
+        return join(this.options.stateDir, 'notes-bridge.json');
+    }
+    /** Starts the bridge (once) on the port and token kept from last time, so the app's snippet stays valid. */
+    start() {
+        if (this.info)
+            return Promise.resolve(this.info);
+        this.starting ??= this.listen().finally(() => { this.starting = null; });
+        return this.starting;
+    }
+    async listen() {
+        const settingsFile = this.settingsFile();
+        if (existsSync(settingsFile))
+            chmodSync(settingsFile, 0o600);
+        const saved = existsSync(settingsFile) ? readJson(settingsFile) : null;
+        const token = typeof saved?.token === 'string' && /^[a-f0-9]{48}$/.test(saved.token) ? saved.token : randomBytes(24).toString('hex');
+        const wanted = this.options.port ?? (Number.isSafeInteger(saved?.port) ? saved.port : 0);
+        const server = createServer((request, response) => void this.handle(request, response, token));
+        const port = await new Promise((resolve, reject) => {
+            const attempt = (port, retry) => {
+                server.once('error', (error) => {
+                    if (retry && error.code === 'EADDRINUSE')
+                        attempt(0, false);
+                    else
+                        reject(error);
+                });
+                server.listen(port, '127.0.0.1', () => resolve(server.address().port));
+            };
+            attempt(wanted, wanted !== 0);
+        });
+        this.server = server;
+        writeJson(settingsFile, { port, token });
+        chmodSync(settingsFile, 0o600);
+        const base = `http://127.0.0.1:${port}`;
+        const scriptUrl = `${base}/page-notes.js?token=${token}`;
+        this.info = {
+            port,
+            token,
+            scriptUrl,
+            snippet: `<script src="${scriptUrl}"></script>`
+        };
+        return this.info;
+    }
+    list() {
+        this.sweep();
+        return [...this.windows.values()].map(({ id, url, title, lastSeen }) => ({ id, url, title, lastSeen }));
+    }
+    /** Sends one helper operation to a window and waits for its JSON reply. */
+    call(windowId, operation) {
+        this.sweep();
+        const live = this.windows.get(windowId);
+        if (!live)
+            return Promise.reject(new Error('That app window is no longer connected.'));
+        return new Promise((resolve, reject) => {
+            const id = String(this.nextCall++);
+            const pending = {
+                id, operation, resolve, reject,
+                timer: setTimeout(() => {
+                    live.sent.delete(id);
+                    live.queue = live.queue.filter((entry) => entry !== pending);
+                    reject(new Error('The app window did not answer.'));
+                }, CALL_MS)
+            };
+            live.queue.push(pending);
+            this.flush(live);
+        });
+    }
+    flush(live) {
+        if (!live.waiter || !live.queue.length)
+            return;
+        const pending = live.queue.shift();
+        live.sent.set(pending.id, pending);
+        const waiter = live.waiter;
+        live.waiter = null;
+        if (live.waiterTimer)
+            clearTimeout(live.waiterTimer);
+        live.waiterTimer = null;
+        this.json(waiter, 200, { id: pending.id, operation: pending.operation });
+    }
+    sweep() {
+        const now = Date.now();
+        for (const live of this.windows.values()) {
+            if (now - live.lastSeen <= GONE_MS || live.waiter)
+                continue;
+            this.windows.delete(live.id);
+            for (const pending of [...live.queue, ...live.sent.values()]) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error('That app window is no longer connected.'));
+            }
+        }
+    }
+    json(response, status, body) {
+        response.writeHead(status, { 'content-type': 'application/json', 'access-control-allow-origin': '*', 'cache-control': 'no-store' });
+        response.end(body === undefined ? undefined : JSON.stringify(body));
+    }
+    async body(request) {
+        let size = 0;
+        const chunks = [];
+        for await (const chunk of request) {
+            size += chunk.length;
+            if (size > MAX_BODY)
+                return null;
+            chunks.push(chunk);
+        }
+        try {
+            const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            return value && typeof value === 'object' ? value : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async handle(request, response, token) {
+        try {
+            const port = this.server?.address()?.port;
+            // Refuse other host names, so a web page cannot reach the bridge by DNS rebinding.
+            if (request.headers.host !== `127.0.0.1:${port}` && request.headers.host !== `localhost:${port}`)
+                return this.json(response, 421);
+            const url = new URL(request.url ?? '/', `http://127.0.0.1:${port}`);
+            if (request.method === 'OPTIONS')
+                return this.json(response, 204);
+            if (request.method === 'GET' && url.pathname === '/page-notes.js') {
+                if (url.searchParams.get('token') !== token)
+                    return this.json(response, 403);
+                response.writeHead(200, { 'content-type': 'application/javascript; charset=utf-8', 'access-control-allow-origin': '*', 'cache-control': 'no-store' });
+                response.end(bridgeScript(`http://127.0.0.1:${port}`, token));
+                return;
+            }
+            if (request.method === 'GET' && url.pathname === '/poll') {
+                if (url.searchParams.get('token') !== token)
+                    return this.json(response, 403);
+                const live = this.windows.get(url.searchParams.get('window') ?? '');
+                if (!live)
+                    return this.json(response, 410);
+                live.lastSeen = Date.now();
+                live.url = bounded(url.searchParams.get('url'), 2000) || live.url;
+                live.title = bounded(url.searchParams.get('title'), 200);
+                if (live.waiter)
+                    this.json(live.waiter, 204);
+                live.waiter = response;
+                live.waiterTimer = setTimeout(() => {
+                    if (live.waiter !== response)
+                        return;
+                    live.waiter = null;
+                    this.json(response, 204);
+                }, POLL_MS);
+                response.on('close', () => { if (live.waiter === response)
+                    live.waiter = null; });
+                this.flush(live);
+                return;
+            }
+            if (request.method === 'POST' && (url.pathname === '/register' || url.pathname === '/reply')) {
+                const body = await this.body(request);
+                if (!body || body.token !== token)
+                    return this.json(response, 403);
+                if (url.pathname === '/register') {
+                    this.sweep();
+                    if (this.windows.size >= MAX_WINDOWS)
+                        return this.json(response, 429);
+                    const id = `a${this.nextWindow++}`;
+                    this.windows.set(id, { id, url: bounded(body.url, 2000), title: bounded(body.title, 200), lastSeen: Date.now(), queue: [], sent: new Map(), waiter: null, waiterTimer: null });
+                    return this.json(response, 200, { windowId: id });
+                }
+                const live = this.windows.get(typeof body.window === 'string' ? body.window : '');
+                const pending = live?.sent.get(typeof body.id === 'string' ? body.id : '');
+                if (!live || !pending)
+                    return this.json(response, 410);
+                live.sent.delete(pending.id);
+                clearTimeout(pending.timer);
+                pending.resolve(body.reply);
+                return this.json(response, 200, {});
+            }
+            this.json(response, 404);
+        }
+        catch {
+            if (!response.headersSent)
+                this.json(response, 500);
+        }
+    }
+    async close() {
+        for (const live of this.windows.values()) {
+            if (live.waiter)
+                this.json(live.waiter, 204);
+            if (live.waiterTimer)
+                clearTimeout(live.waiterTimer);
+            for (const pending of [...live.queue, ...live.sent.values()]) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error('The page bridge closed.'));
+            }
+        }
+        this.windows.clear();
+        const server = this.server;
+        this.server = null;
+        this.info = null;
+        if (server) {
+            const closed = new Promise((resolve) => server.close(() => resolve()));
+            server.closeAllConnections();
+            await closed;
+        }
+    }
+}

package/dist/sdk/annotations/capture.d.ts

@@ -0,0 +1,116 @@
+import type { Browser } from 'playwright-core';
+import { NetworkPolicy } from "../browser/network.js";
+import { type Launcher } from "../browser/session.js";
+import { NotesBridge, type BridgeInfo } from "./bridge.js";
+import { type NoteApp, type NoteTarget } from "./store.js";
+export interface CaptureEnvelope {
+    url: string;
+    title: string;
+    documentId: string;
+    target: NoteTarget;
+}
+export type CaptureTargetSpec = {
+    kind: 'web';
+} | {
+    kind: 'cdp';
+    endpoint: string;
+    name?: string | null;
+} | {
+    kind: 'bridge';
+    name?: string | null;
+};
+export interface CaptureWindow {
+    id: string;
+    url: string;
+    title: string;
+    current: boolean;
+}
+/** One comment the person submitted in the inspector's popover. */
+export interface InspectResult extends CaptureEnvelope {
+    body: string;
+    action: 'save' | 'queue' | 'send';
+}
+export interface InspectState {
+    /** False once the person or the page ended it. */
+    active: boolean;
+    url: string;
+    title: string;
+    documentId: string;
+    result: InspectResult | null;
+    /** Whether the result came from a script world the page cannot reach. */
+    trusted: boolean;
+    /** The app the window belongs to, for the note's source. */
+    app: NoteApp | null;
+}
+/** Opens a DevTools connection to a running app; tests replace it. */
+export type AppConnector = (endpoint: string) => Promise<Browser>;
+export interface AnnotationCaptureOptions {
+    stateDir: string;
+    launch?: Launcher;
+    network?: NetworkPolicy;
+    connect?: AppConnector;
+    bridge?: NotesBridge;
+}
+export declare class AnnotationCapture {
+    private readonly options;
+    private readonly targets;
+    private readonly inspecting;
+    private readonly network;
+    readonly bridge: NotesBridge;
+    constructor(options: AnnotationCaptureOptions);
+    private web;
+    private target;
+    private replace;
+    private call;
+    /** What `key` captures in now. */
+    describe(key: string): {
+        kind: CaptureTargetSpec['kind'];
+        app: NoteApp | null;
+        inspecting: boolean;
+    };
+    /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
+    attach(key: string, spec: CaptureTargetSpec): Promise<{
+        kind: CaptureTargetSpec['kind'];
+        app: NoteApp | null;
+        windows: CaptureWindow[];
+        bridge?: BridgeInfo;
+    }>;
+    windows(key: string): Promise<CaptureWindow[]>;
+    /** Switches to another window or tab of the target; an inspector there starts again. */
+    selectWindow(key: string, id: string): Promise<void>;
+    /** Shows the capture window, at `url` when given. Captures in the browser again if an app was attached. */
+    open(key: string, url?: string | null): Promise<{
+        url: string;
+        title: string;
+    }>;
+    identity(key: string): Promise<{
+        url: string;
+        title: string;
+        documentId: string;
+    }>;
+    /** Starts listening for the person's selection or click. Returns the id `capture` takes. */
+    begin(key: string, kind: 'text' | 'element'): Promise<{
+        captureId: string;
+    }>;
+    /** What the person selected, or null when nothing is selected yet. */
+    capture(key: string, captureId: string): Promise<CaptureEnvelope | null>;
+    cancel(key: string, captureId?: string): Promise<void>;
+    /** Turns on the inspector in the current window: hover outlines, a click opens the comment popover. */
+    inspect(key: string): Promise<{
+        captureId: string;
+    }>;
+    stopInspect(key: string): Promise<void>;
+    /**
+     * The next comment the person submitted, if any. A new document (a reload, a link) loses the
+     * inspector; it is turned on again there, so the person can keep going.
+     */
+    next(key: string): Promise<InspectState>;
+    toast(key: string, text: string): Promise<void>;
+    /** Opens the note's page when another one is showing, then scrolls to and marks its target. */
+    reveal(key: string, url: string, target: NoteTarget): Promise<{
+        state: 'matched' | 'ambiguous' | 'unresolved';
+        reason?: string;
+    }>;
+    release(key: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/sdk/annotations/capture.js

@@ -0,0 +1,308 @@
+// The terminal's capture surface for page notes (PROP-0017, PROP-0018). A front end captures in
+// one target at a time:
+// - `web`: a visible browser window the person browses in, separate from the agent's browser;
+// - `cdp`: the windows of a desktop app started with a DevTools port (an Electron app, say);
+// - `bridge`: app windows that loaded the page bridge script (a macOS web view has no DevTools port).
+// The person selects text, clicks an element, or inspects with the popover; the front end pulls
+// what they did through the page helper.
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { readBrowserConfig } from "../browser/config.js";
+import { NetworkPolicy } from "../browser/network.js";
+import { BrowserSession, fileName, launchBrowser } from "../browser/session.js";
+import { NotesBridge } from "./bridge.js";
+import { evaluateIsolated } from "./isolated.js";
+import { pageCall, pageReply } from "./pageScript.js";
+import { validateUrl } from "./store.js";
+const IDLE_MS = 60 * 60_000;
+const LOOPBACK = /^(?:https?|wss?):\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/;
+const connectApp = async (endpoint) => {
+    const { chromium } = await import('playwright-core');
+    return chromium.connectOverCDP(endpoint);
+};
+/** An app's own windows over its DevTools port. Nothing is routed or opened, and the app is never closed. */
+class CdpTarget {
+    browser;
+    app;
+    kind = 'cdp';
+    ids = new WeakMap();
+    nextId = 1;
+    current = null;
+    constructor(browser, app) {
+        this.browser = browser;
+        this.app = app;
+    }
+    pages() {
+        return this.browser.contexts().flatMap((context) => context.pages()).filter((page) => !/^(?:devtools|chrome-extension):/.test(page.url()));
+    }
+    id(page) {
+        let id = this.ids.get(page);
+        if (!id) {
+            id = `w${this.nextId++}`;
+            this.ids.set(page, id);
+        }
+        return id;
+    }
+    page() {
+        const pages = this.pages();
+        if (this.current && pages.includes(this.current))
+            return this.current;
+        this.current = pages[0] ?? null;
+        if (!this.current)
+            throw new Error('The app has no open window.');
+        return this.current;
+    }
+    async evaluate(operation) {
+        return evaluateIsolated(this.page(), pageCall(operation));
+    }
+    async windows() {
+        const current = this.pages().length ? this.page() : null;
+        return Promise.all(this.pages().map(async (page) => ({ id: this.id(page), url: page.url(), title: await page.title().catch(() => ''), current: page === current })));
+    }
+    select(id) {
+        const page = this.pages().find((candidate) => this.ids.get(candidate) === id);
+        if (!page)
+            throw new Error(`There is no app window ${id}.`);
+        this.current = page;
+        void page.bringToFront().catch(() => undefined);
+    }
+    async close() {
+        // Disconnects; an app we attached to keeps running.
+        await this.browser.close().catch(() => undefined);
+    }
+}
+/** Windows that loaded the page bridge script. Every answer is page data the page could forge. */
+class BridgeTarget {
+    bridge;
+    app;
+    kind = 'bridge';
+    current = null;
+    constructor(bridge, app) {
+        this.bridge = bridge;
+        this.app = app;
+    }
+    window() {
+        const windows = this.bridge.list();
+        if (this.current && windows.some((window) => window.id === this.current))
+            return this.current;
+        this.current = windows.sort((left, right) => right.lastSeen - left.lastSeen)[0]?.id ?? null;
+        if (!this.current)
+            throw new Error('No app window has connected to the page bridge yet. Load the bridge script in the app and reload it.');
+        return this.current;
+    }
+    async evaluate(operation) {
+        return { reply: await this.bridge.call(this.window(), operation), trusted: false };
+    }
+    async windows() {
+        const current = this.bridge.list().length ? this.window() : null;
+        return this.bridge.list().map((window) => ({ id: window.id, url: window.url, title: window.title, current: window.id === current }));
+    }
+    select(id) {
+        if (!this.bridge.list().some((window) => window.id === id))
+            throw new Error(`There is no app window ${id}.`);
+        this.current = id;
+    }
+    async close() { }
+}
+/** The visible browser window, with the helper in an isolated world. */
+class WebTarget {
+    session;
+    kind = 'web';
+    app = null;
+    constructor(session) {
+        this.session = session;
+    }
+    evaluate(operation) {
+        return this.session.run(async () => evaluateIsolated((await this.session.tab()).page, pageCall(operation)));
+    }
+    async windows() {
+        if (!this.session.started)
+            return [];
+        return Promise.all(this.session.list().map(async (tab) => ({ id: tab.id, url: tab.url, title: await (await this.session.tab(tab.id)).page.title().catch(() => ''), current: tab.current })));
+    }
+    select(id) {
+        void this.session.select(id).page.bringToFront().catch(() => undefined);
+    }
+    close() {
+        return this.session.close();
+    }
+}
+export class AnnotationCapture {
+    options;
+    targets = new Map();
+    inspecting = new Map();
+    network;
+    bridge;
+    constructor(options) {
+        this.options = options;
+        this.network = options.network ?? new NetworkPolicy(() => readBrowserConfig(options.stateDir));
+        this.bridge = options.bridge ?? new NotesBridge({ stateDir: options.stateDir });
+    }
+    web(key) {
+        const existing = this.targets.get(key);
+        if (existing instanceof WebTarget)
+            return existing;
+        const session = new BrowserSession({
+            key: `notes-${key}`,
+            profileDir: join(this.options.stateDir, 'browser', 'profiles', 'person'),
+            downloadsDir: join(this.options.stateDir, 'browser', 'downloads', fileName(`notes-${key}`)),
+            // Always a window the person can see and select in.
+            config: () => ({ ...readBrowserConfig(this.options.stateDir), headed: true }),
+            network: this.network,
+            launch: this.options.launch ?? launchBrowser,
+            idleMs: IDLE_MS,
+            onIdle: () => void this.release(key)
+        });
+        const target = new WebTarget(session);
+        this.targets.set(key, target);
+        return target;
+    }
+    target(key) {
+        return this.targets.get(key) ?? this.web(key);
+    }
+    async replace(key, target) {
+        const old = this.targets.get(key);
+        this.targets.set(key, target);
+        this.inspecting.delete(key);
+        if (old && old !== target)
+            await old.close().catch(() => undefined);
+    }
+    async call(key, operation) {
+        return pageReply((await this.target(key).evaluate(operation)).reply);
+    }
+    /** What `key` captures in now. */
+    describe(key) {
+        const target = this.targets.get(key);
+        return { kind: target?.kind ?? 'web', app: target?.app ?? null, inspecting: this.inspecting.has(key) };
+    }
+    /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
+    async attach(key, spec) {
+        if (spec.kind === 'web') {
+            if (this.targets.get(key)?.kind !== 'web')
+                await this.replace(key, this.web(key));
+            return { kind: 'web', app: null, windows: await this.target(key).windows() };
+        }
+        if (spec.kind === 'cdp') {
+            if (typeof spec.endpoint !== 'string' || !LOOPBACK.test(spec.endpoint))
+                throw new Error('An app\'s DevTools address must be on this computer, such as http://127.0.0.1:9229.');
+            const browser = await (this.options.connect ?? connectApp)(spec.endpoint);
+            const name = spec.name?.trim() || `App at ${new URL(spec.endpoint).host}`;
+            const target = new CdpTarget(browser, { kind: 'cdp', name: name.slice(0, 200) });
+            await this.replace(key, target);
+            return { kind: 'cdp', app: target.app, windows: await target.windows() };
+        }
+        if (spec.kind === 'bridge') {
+            const bridge = await this.bridge.start();
+            const target = new BridgeTarget(this.bridge, { kind: 'bridge', name: (spec.name?.trim() || 'App window').slice(0, 200) });
+            await this.replace(key, target);
+            return { kind: 'bridge', app: target.app, windows: await target.windows(), bridge };
+        }
+        throw new Error('A capture target is web, cdp or bridge.');
+    }
+    windows(key) {
+        return this.target(key).windows();
+    }
+    /** Switches to another window or tab of the target; an inspector there starts again. */
+    async selectWindow(key, id) {
+        const inspecting = this.inspecting.has(key);
+        if (inspecting)
+            await this.stopInspect(key).catch(() => undefined);
+        this.target(key).select(id);
+        if (inspecting)
+            await this.inspect(key);
+    }
+    /** Shows the capture window, at `url` when given. Captures in the browser again if an app was attached. */
+    async open(key, url) {
+        if (this.targets.get(key) && this.targets.get(key).kind !== 'web')
+            await this.replace(key, this.web(key));
+        const { session } = this.web(key);
+        return session.run(async () => {
+            const tab = await session.tab();
+            if (url) {
+                const address = validateUrl(url);
+                const refusal = await this.network.refusal(address);
+                if (refusal)
+                    throw new Error(refusal);
+                await tab.page.goto(address, { waitUntil: 'domcontentloaded' });
+            }
+            await tab.page.bringToFront().catch(() => undefined);
+            return { url: tab.page.url(), title: await tab.page.title().catch(() => '') };
+        });
+    }
+    identity(key) {
+        return this.call(key, { operation: 'identity' });
+    }
+    /** Starts listening for the person's selection or click. Returns the id `capture` takes. */
+    async begin(key, kind) {
+        this.inspecting.delete(key);
+        const captureId = randomUUID();
+        await this.call(key, { operation: 'begin', kind, captureId });
+        return { captureId };
+    }
+    /** What the person selected, or null when nothing is selected yet. */
+    capture(key, captureId) {
+        return this.call(key, { operation: 'capture', captureId });
+    }
+    async cancel(key, captureId) {
+        if (!this.targets.has(key))
+            return;
+        await this.call(key, { operation: 'cancel', ...(captureId ? { captureId } : {}) });
+    }
+    /** Turns on the inspector in the current window: hover outlines, a click opens the comment popover. */
+    async inspect(key) {
+        const captureId = randomUUID();
+        await this.call(key, { operation: 'begin', kind: 'inspect', captureId });
+        const identity = await this.identity(key).catch(() => null);
+        this.inspecting.set(key, { captureId, documentId: identity?.documentId ?? null });
+        return { captureId };
+    }
+    async stopInspect(key) {
+        const state = this.inspecting.get(key);
+        this.inspecting.delete(key);
+        if (state && this.targets.has(key))
+            await this.call(key, { operation: 'cancel', captureId: state.captureId }).catch(() => undefined);
+    }
+    /**
+     * The next comment the person submitted, if any. A new document (a reload, a link) loses the
+     * inspector; it is turned on again there, so the person can keep going.
+     */
+    async next(key) {
+        const target = this.target(key);
+        const state = this.inspecting.get(key);
+        if (!state)
+            throw new Error('The inspector is off.');
+        const { reply, trusted } = await target.evaluate({ operation: 'next', captureId: state.captureId });
+        const value = pageReply(reply);
+        if (!value.active && this.inspecting.get(key) === state && value.documentId !== state.documentId) {
+            await target.evaluate({ operation: 'begin', kind: 'inspect', captureId: state.captureId });
+            state.documentId = value.documentId;
+            return { ...value, active: true, result: null, trusted, app: target.app };
+        }
+        if (!value.active)
+            this.inspecting.delete(key);
+        return { ...value, trusted, app: target.app };
+    }
+    async toast(key, text) {
+        await this.call(key, { operation: 'toast', text: text.slice(0, 200) });
+    }
+    /** Opens the note's page when another one is showing, then scrolls to and marks its target. */
+    async reveal(key, url, target) {
+        const current = this.targets.get(key);
+        if (!current || current.kind === 'web') {
+            const shown = current?.session.started ? await this.identity(key).catch(() => null) : null;
+            if (shown?.url !== url)
+                await this.open(key, url);
+        }
+        return this.call(key, { operation: 'reveal', target });
+    }
+    async release(key) {
+        const target = this.targets.get(key);
+        this.targets.delete(key);
+        this.inspecting.delete(key);
+        await target?.close();
+    }
+    async close() {
+        await Promise.all([...this.targets.keys()].map((key) => this.release(key)));
+        await this.bridge.close();
+    }
+}