koneck 2.128.59 → 2.128.61

package/dist/browser.js

@@ -184,8 +184,10 @@ export function patienceFrom(value) {
 }
 /** Page text handed back, capped. A whole document is not an answer. */
 const MAX_TEXT = 12_000;
-/** Interactive elements listed. Beyond this a page is a haystack, not a form. */
+/** Interactive elements listed at once. Beyond this a page is a haystack; `from` pages through it. */
 const MAX_CONTROLS = 60;
+/** How many controls a page is searched for in all, so a long one can be paged. */
+const MAX_COLLECTED = 400;
 /**
  * The soonest a page is called settled.
  *
@@ -241,6 +243,101 @@ export function windowSize(configured) {
         return '1280,900';
     return `${Number(m[1])},${Number(m[2])}`;
 }
+/**
+ * Why an address will not be opened, or null when it may be.
+ *
+ * `open` took any scheme at all, in a browser started without its sandbox: file:// anywhere on the
+ * disk, javascript:, the browser's own chrome:// pages. The browser is for the web — the app being
+ * built, its docs, the sites it talks to — so http and https go anywhere, a file only inside the
+ * workspace, and schemes that are the browser's own or that run code are refused outright.
+ */
+export function refuseUrl(url, fileRoots) {
+    const scheme = (/^([a-z][a-z0-9+.-]*):/i.exec(url)?.[1] ?? '').toLowerCase();
+    if (scheme === 'http' || scheme === 'https' || url === 'about:blank')
+        return null;
+    if (scheme === 'file') {
+        let file;
+        try {
+            file = path.resolve(decodeURIComponent(new URL(url).pathname).replace(/^\/([a-z]:)/i, '$1'));
+        }
+        catch {
+            return `${url} is not a file address that can be read.`;
+        }
+        const inside = fileRoots.some(root => {
+            const rel = path.relative(path.resolve(root), file);
+            return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        });
+        return inside ? null
+            : `${url} is outside the workspace. The browser opens files only from inside it; serve the `
+                + `page, or copy it into the workspace, to look at it.`;
+    }
+    return `${scheme || 'That'}: addresses are not opened — the browser is for http and https pages, `
+        + `and files inside the workspace.`;
+}
+const NAMED_KEYS = {
+    enter: { code: 'Enter', key: 'Enter', windowsVirtualKeyCode: 13, text: '\r' },
+    tab: { code: 'Tab', key: 'Tab', windowsVirtualKeyCode: 9, text: '\t' },
+    escape: { code: 'Escape', key: 'Escape', windowsVirtualKeyCode: 27 },
+    backspace: { code: 'Backspace', key: 'Backspace', windowsVirtualKeyCode: 8 },
+    delete: { code: 'Delete', key: 'Delete', windowsVirtualKeyCode: 46 },
+    space: { code: 'Space', key: ' ', windowsVirtualKeyCode: 32, text: ' ' },
+    arrowdown: { code: 'ArrowDown', key: 'ArrowDown', windowsVirtualKeyCode: 40 },
+    arrowup: { code: 'ArrowUp', key: 'ArrowUp', windowsVirtualKeyCode: 38 },
+    arrowleft: { code: 'ArrowLeft', key: 'ArrowLeft', windowsVirtualKeyCode: 37 },
+    arrowright: { code: 'ArrowRight', key: 'ArrowRight', windowsVirtualKeyCode: 39 },
+    home: { code: 'Home', key: 'Home', windowsVirtualKeyCode: 36 },
+    end: { code: 'End', key: 'End', windowsVirtualKeyCode: 35 },
+    pageup: { code: 'PageUp', key: 'PageUp', windowsVirtualKeyCode: 33 },
+    pagedown: { code: 'PageDown', key: 'PageDown', windowsVirtualKeyCode: 34 },
+};
+const KEY_ALIASES = {
+    return: 'enter', esc: 'escape', del: 'delete', up: 'arrowup', down: 'arrowdown', left: 'arrowleft',
+    right: 'arrowright', pgup: 'pageup', pgdn: 'pagedown', ' ': 'space',
+};
+const MODIFIER_BITS = {
+    alt: 1, option: 1, control: 2, ctrl: 2, meta: 4, cmd: 4, command: 4, super: 4, shift: 8,
+};
+/**
+ * A key, or a chord like "Control+A" or "Shift+Tab", as the protocol wants it.
+ *
+ * Anything not in the table used to be pressed as Enter, silently — asked to press Delete, the page
+ * submitted a form. An unknown key is now refused and the known ones are named.
+ */
+export function parseKey(said) {
+    const raw = String(said ?? '').trim();
+    if (!raw)
+        return { spec: NAMED_KEYS['enter'], modifiers: 0 };
+    // "+" alone is the plus key; "Control++" is Control and plus.
+    const parts = raw === '+' ? ['+'] : raw.split(/\+(?!$)/);
+    let modifiers = 0;
+    for (const m of parts.slice(0, -1)) {
+        const bit = MODIFIER_BITS[m.trim().toLowerCase()];
+        if (!bit)
+            return { error: `"${m}" is not a modifier. Use Control, Shift, Alt or Meta, e.g. "Control+A".` };
+        modifiers |= bit;
+    }
+    const last = parts[parts.length - 1];
+    const lower = last.toLowerCase();
+    const fn = /^f([1-9]|1[0-2])$/.exec(lower);
+    let spec = NAMED_KEYS[KEY_ALIASES[lower] ?? lower];
+    if (!spec && fn)
+        spec = { code: last.toUpperCase(), key: last.toUpperCase(), windowsVirtualKeyCode: 111 + Number(fn[1]) };
+    if (!spec && [...last].length === 1) {
+        const ch = last;
+        const upper = ch.toUpperCase();
+        const code = /[a-z]/i.test(ch) ? 'Key' + upper : /[0-9]/.test(ch) ? 'Digit' + ch : '';
+        spec = { code, key: modifiers & 8 ? upper : ch, windowsVirtualKeyCode: upper.charCodeAt(0), text: modifiers & 8 ? upper : ch };
+    }
+    if (!spec) {
+        return { error: `"${last}" is not a key this browser knows. Keys: Enter, Tab, Escape, Backspace, `
+                + `Delete, Space, arrows, Home, End, PageUp, PageDown, F1–F12, any single character, and chords `
+                + `such as "Control+A" or "Shift+Tab".` };
+    }
+    // A command chord types nothing: Control+A selects all, it does not insert an "a".
+    if (modifiers & (2 | 4))
+        spec = { ...spec, text: undefined };
+    return { spec, modifiers };
+}
 export class Browser {
     child = null;
     socket = null;
@@ -262,6 +359,9 @@ export class Browser {
     patience = 'balanced';
     /** The window size from configuration, as WIDTHxHEIGHT. KONECK_BROWSER_WINDOW outranks it. */
     window;
+    onExit = null;
+    /** Folders a file:// address may be inside — the workspace. Empty means no file:// at all. */
+    fileRoots = [];
     get running() { return this.socket?.readyState === 1; }
     remember(problem) {
         // The same failing request on every render would otherwise fill this with one message.
@@ -271,6 +371,25 @@ export class Browser {
         while (this.problems.length > 25)
             this.problems.shift();
     }
+    /**
+     * Everything the page logged, and every request it made — not only what went wrong.
+     *
+     * Only errors and warnings were kept, and only the last 25, cleared when read. That answers "did
+     * something fail" and not "what did the page do": whether the save request was sent at all, what
+     * the API answered, the log line the developer put there to find out. Both are bounded, and they
+     * are kept for the model to ask for and the panel to show, apart from the problems above.
+     */
+    consoleLog = [];
+    requests = new Map();
+    finished = [];
+    /** The page's console, oldest first, `n` at most. */
+    consoleEntries(n = 50) {
+        return this.consoleLog.slice(-Math.max(1, n));
+    }
+    /** The page's requests, finished and still going, oldest first. */
+    networkEntries(n = 50) {
+        return [...this.finished, ...this.requests.values()].sort((a, b) => a.start - b.start).slice(-Math.max(1, n));
+    }
     /** Problems the page ran into, which nobody would otherwise see. */
     recentProblems() { return [...this.problems]; }
     clearProblems() { this.problems.length = 0; }
@@ -320,6 +439,18 @@ export class Browser {
         ];
         const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
         this.child = child;
+        /*
+         * Closed with KONECK, not left for the next one to find.
+         *
+         * Only an explicit close or the web server shutting down stopped it, so every terminal session
+         * that used the browser left a headless Chromium running until the next KONECK reaped it. 'exit'
+         * handlers must be synchronous, and a kill is.
+         */
+        this.onExit = () => { try {
+            child.kill('SIGKILL');
+        }
+        catch { /* already gone */ } };
+        process.once('exit', this.onExit);
         // Written down so a later run can tell a leak from a browser somebody is using.
         noteBrowser(child.pid, this.profile);
         // The port is chosen by the browser and announced on stderr; there is no other way to learn it.
@@ -408,6 +539,23 @@ export class Browser {
     navigating = false;
     noteEvent(message) {
         const method = message.method;
+        if (method === 'Page.screencastFrame') {
+            const p = message.params;
+            // Acknowledged at once: Chromium sends the next frame only after the last is acknowledged.
+            if (typeof p?.sessionId === 'number')
+                void this.call('Page.screencastFrameAck', { sessionId: p.sessionId });
+            if (p?.data) {
+                this.lastShot = 'data:image/jpeg;base64,' + p.data;
+                const meta = { width: Math.round(p.metadata?.deviceWidth ?? 0), height: Math.round(p.metadata?.deviceHeight ?? 0) };
+                for (const fn of this.frameListeners) {
+                    try {
+                        fn(this.lastShot, meta);
+                    }
+                    catch { /* one bad watcher is not everyone's problem */ }
+                }
+            }
+            return;
+        }
         if (method === 'Page.frameStartedLoading' || method === 'Page.navigatedWithinDocument') {
             this.navigating = true;
             return;
@@ -418,13 +566,43 @@ export class Browser {
         }
         if (method === 'Runtime.consoleAPICalled') {
             const p = message.params;
+            const text = (p?.args ?? []).map(a => String(a.description ?? a.value ?? '')).join(' ').trim();
+            if (text) {
+                this.consoleLog.push({ at: Date.now(), level: p?.type ?? 'log', text: text.slice(0, 500) });
+                while (this.consoleLog.length > 200)
+                    this.consoleLog.shift();
+            }
             if (p?.type !== 'error' && p?.type !== 'warning')
                 return;
-            const text = (p.args ?? []).map(a => String(a.description ?? a.value ?? '')).join(' ').trim();
             if (text)
                 this.remember(`console ${p.type}: ${text}`);
             return;
         }
+        if (method === 'Network.requestWillBeSent') {
+            const p = message.params;
+            if (!p?.requestId || !p.request?.url || p.request.url.startsWith('data:'))
+                return;
+            this.requests.set(p.requestId, {
+                method: p.request.method ?? 'GET', url: p.request.url.slice(0, 400), type: p.type ?? 'Other',
+                start: Date.now(),
+            });
+            return;
+        }
+        if (method === 'Network.loadingFinished' || method === 'Network.loadingFailed') {
+            const p = message.params;
+            const entry = p?.requestId ? this.requests.get(p.requestId) : undefined;
+            if (entry) {
+                this.requests.delete(p.requestId);
+                entry.ms = Date.now() - entry.start;
+                if (p.errorText)
+                    entry.error = p.errorText;
+                this.finished.push(entry);
+                while (this.finished.length > 200)
+                    this.finished.shift();
+            }
+            if (method === 'Network.loadingFinished')
+                return;
+        }
         if (method === 'Runtime.exceptionThrown') {
             const p = message.params;
             const text = p?.exceptionDetails?.exception?.description ?? p?.exceptionDetails?.text ?? '';
@@ -435,6 +613,9 @@ export class Browser {
         if (method === 'Network.responseReceived') {
             const p = message.params;
             const status = p?.response?.status ?? 0;
+            const entry = p?.requestId ? this.requests.get(p.requestId) : undefined;
+            if (entry)
+                entry.status = status;
             if (status >= 400)
                 this.remember(`HTTP ${status} from ${p?.response?.url ?? 'a request'}`);
             return;
@@ -494,7 +675,13 @@ export class Browser {
             if (!started.ok)
                 return started;
         }
-        const target = /^[a-z]+:\/\//i.test(url) ? url : 'http://' + url;
+        // A scheme is "name://", or one of the few that never take slashes; "example.com:8080" is a host.
+        const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url)
+            || /^(javascript|data|about|chrome|view-source|blob|mailto|vbscript|file):/i.test(url);
+        const target = hasScheme ? url : 'http://' + url;
+        const refused = refuseUrl(target, this.fileRoots);
+        if (refused)
+            return { ok: false, error: refused };
         const nav = await this.call('Page.navigate', { url: target });
         if (nav?.errorText)
             return { ok: false, error: `${target} — ${nav.errorText}` };
@@ -680,10 +867,68 @@ export class Browser {
     async signature() {
         return await this.evaluate('location.href + "|" + (document.body ? document.body.innerText.length : 0)') ?? '';
     }
-    async state() {
+    async state(from = 1) {
         const got = await this.evaluate(`(() => {
       const seen = new Set();
       const controls = [];
+      /*
+       * Numbers that stay with their element.
+       *
+       * They were positions in the list, recomputed on every read — so a page that changed between
+       * a read and a click (a banner appearing, a row added) moved every number after the change,
+       * and "click 7" pressed whatever was seventh now. Each element is given its number the first
+       * time it is seen and keeps it while it exists. Held in the page's memory, not written into
+       * its markup: the page being tested is not edited to test it. A navigation starts afresh.
+       */
+      const reg = window.__koneckRefs || (window.__koneckRefs = { next: 1, of: new WeakMap(), els: new Map() });
+      const refOf = (el) => {
+        let r = reg.of.get(el);
+        if (!r) { r = reg.next++; reg.of.set(el, r); reg.els.set(r, new WeakRef(el)); }
+        return r;
+      };
+      const implicitRole = (el) => {
+        const t = el.tagName.toLowerCase();
+        if (t === 'a') return 'link';
+        if (t === 'button') return 'button';
+        if (t === 'select') return 'combobox';
+        if (t === 'textarea') return 'textbox';
+        if (t === 'input') {
+          const ty = (el.getAttribute('type') || 'text').toLowerCase();
+          if (ty === 'checkbox' || ty === 'radio') return ty;
+          if (ty === 'submit' || ty === 'button' || ty === 'reset') return 'button';
+          if (ty === 'range') return 'slider';
+          if (ty === 'search') return 'searchbox';
+          return 'textbox';
+        }
+        return t;
+      };
+      const statesOf = (el) => {
+        const out = [];
+        const aria = (n) => el.getAttribute('aria-' + n);
+        if (el.disabled || aria('disabled') === 'true') out.push('disabled');
+        if (el.checked === true || aria('checked') === 'true') out.push('checked');
+        if (aria('expanded') === 'true') out.push('expanded');
+        else if (aria('expanded') === 'false') out.push('collapsed');
+        if (aria('selected') === 'true') out.push('selected');
+        if (aria('pressed') === 'true') out.push('pressed');
+        if (el.required || aria('required') === 'true') out.push('required');
+        if (aria('invalid') === 'true' || (el.validity && el.validity.valid === false && el.value)) out.push('invalid');
+        if (el.readOnly) out.push('read-only');
+        return out;
+      };
+      const valueOf = (el) => {
+        const t = el.tagName.toLowerCase();
+        // A password is never read back, not even to the model driving the page.
+        if (t === 'input' && (el.getAttribute('type') || '').toLowerCase() === 'password') return el.value ? '(filled)' : '';
+        if (t === 'select') { const o = el.options[el.selectedIndex]; return o ? (o.text || '').trim().slice(0, 40) : ''; }
+        if ((t === 'input' || t === 'textarea') && typeof el.value === 'string') {
+          const ty = (el.getAttribute('type') || 'text').toLowerCase();
+          if (ty === 'checkbox' || ty === 'radio' || ty === 'submit' || ty === 'button') return '';
+          return el.value.slice(0, 40);
+        }
+        return '';
+      };
+      let total = 0;
       /*
        * What the field is called on screen.
        *
@@ -759,10 +1004,19 @@ export class Browser {
         const sel = selectorFor(el);
         if (seen.has(sel)) continue;
         seen.add(sel);
+        total++;
+        // Paged: the ones before \`from\` are counted but not listed, so the numbers stay put.
+        if (total < ${from}) continue;
+        if (controls.length >= ${MAX_CONTROLS}) { if (total >= ${MAX_COLLECTED}) break; continue; }
+        const states = statesOf(el);
+        const value = valueOf(el);
         controls.push({
           // A number, because that is what a model reaches for when handed a numbered list — and
-          // it cannot be got subtly wrong the way a CSS path can.
-          ref: controls.length + 1,
+          // it cannot be got subtly wrong the way a CSS path can. It stays with the element.
+          ref: refOf(el),
+          role: el.getAttribute('role') || implicitRole(el),
+          ...(states.length ? { states } : {}),
+          ...(value ? { value } : {}),
           tag: el.tagName.toLowerCase(),
           label: label(el),
           selector: sel,
@@ -780,13 +1034,19 @@ export class Browser {
             w: Math.round(box.width), h: Math.round(box.height),
           },
         });
-        if (controls.length >= ${MAX_CONTROLS}) break;
       }
+      const headings = [...document.querySelectorAll('h1,h2,h3')]
+        .filter(h => { const b = h.getBoundingClientRect(); return b.width > 0 && b.height > 0; })
+        .slice(0, 20)
+        .map(h => h.tagName.toLowerCase() + ' ' + (h.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 80))
+        .filter(h => h.length > 3);
       return {
         url: location.href,
         title: document.title,
         text: (document.body ? document.body.innerText : '').trim().slice(0, ${MAX_TEXT}),
         controls,
+        total,
+        headings,
       };
     })()`);
         return got ?? { url: '', title: '', text: '', controls: [] };
@@ -811,9 +1071,9 @@ export class Browser {
      */
     target) {
         if (typeof target.ref === 'number') {
-            const state = await this.state();
-            const found = state.controls.find(c => c.ref === target.ref);
-            return found?.selector ?? null;
+            // The element that was given this number, wherever it is now — not whatever is at that
+            // position in a fresh list. See state().
+            return this.selectorOfRef(target.ref);
         }
         const said = target.text ?? target.label;
         if (said && said.trim()) {
@@ -876,6 +1136,24 @@ export class Browser {
       return parts.join(' > ') || null;
     })()`);
     }
+    /** A selector for the element holding a ref, built now, or null if it is gone. */
+    async selectorOfRef(ref) {
+        return this.evaluate(`(() => {
+      const reg = window.__koneckRefs;
+      const el = reg && reg.els.get(${Math.trunc(ref)}) && reg.els.get(${Math.trunc(ref)}).deref();
+      if (!el || !el.isConnected) return null;
+      if (el.id) return '#' + CSS.escape(el.id);
+      const parts = [];
+      for (let n = el; n && n.nodeType === 1 && n !== document.body; n = n.parentElement) {
+        if (n.id) { parts.unshift('#' + CSS.escape(n.id)); break; }
+        let i = 1, sib = n;
+        while ((sib = sib.previousElementSibling)) i++;
+        parts.unshift(n.tagName.toLowerCase() + ':nth-child(' + i + ')');
+      }
+      const path = parts.join(' > ');
+      return path ? ((parts[0][0] === '#') ? path : 'body > ' + path) : null;
+    })()`);
+    }
     /** What is on the page to act on, for an error message that helps rather than scolds. */
     async describeControls() {
         const state = await this.state();
@@ -1081,12 +1359,14 @@ export class Browser {
             const name = field.label ?? field.selector ?? (field.ref !== undefined ? `#${field.ref}` : '?');
             let selector = null;
             if (typeof field.ref === 'number') {
-                selector = state.controls.find(c => c.ref === field.ref)?.selector ?? null;
+                selector = await this.selectorOfRef(field.ref);
             }
             else if (field.label) {
                 const lower = field.label.toLowerCase();
                 selector = state.controls.find(c => c.label.toLowerCase() === lower)?.selector
-                    ?? state.controls.find(c => c.label.toLowerCase().includes(lower))?.selector ?? null;
+                    ?? state.controls.find(c => c.label.toLowerCase().includes(lower))?.selector
+                    // The same last look at the live page a click gets, which fill never had.
+                    ?? await this.findVisibleByText(field.label);
             }
             else if (field.selector) {
                 selector = field.selector;
@@ -1184,25 +1464,214 @@ export class Browser {
         return { ok: true };
     }
     async press(key) {
-        const known = {
-            Enter: { code: 'Enter', key: 'Enter', windowsVirtualKeyCode: 13, text: '\r' },
-            Tab: { code: 'Tab', key: 'Tab', windowsVirtualKeyCode: 9, text: '\t' },
-            Escape: { code: 'Escape', key: 'Escape', windowsVirtualKeyCode: 27 },
-            Backspace: { code: 'Backspace', key: 'Backspace', windowsVirtualKeyCode: 8 },
-            ArrowDown: { code: 'ArrowDown', key: 'ArrowDown', windowsVirtualKeyCode: 40 },
-            ArrowUp: { code: 'ArrowUp', key: 'ArrowUp', windowsVirtualKeyCode: 38 },
-            ArrowLeft: { code: 'ArrowLeft', key: 'ArrowLeft', windowsVirtualKeyCode: 37 },
-            ArrowRight: { code: 'ArrowRight', key: 'ArrowRight', windowsVirtualKeyCode: 39 },
-        };
-        const spec = known[key] ?? known['Enter'];
-        const down = spec.text !== undefined
-            ? { ...spec, unmodifiedText: spec.text }
-            : spec;
-        await this.call('Input.dispatchKeyEvent', { type: 'keyDown', ...down });
-        await this.call('Input.dispatchKeyEvent', { type: 'keyUp', ...spec });
+        const parsed = parseKey(key);
+        if ('error' in parsed)
+            return { ok: false, error: parsed.error };
+        /*
+         * The `text` field is what makes Enter submit a form.
+         *
+         * A key event without it produces keydown and keyup and no keypress, and a browser only runs
+         * default behaviour — submitting the form, inserting the newline — off the character. Measured:
+         * typing into a field and pressing Enter left the page exactly where it was, and the form never
+         * fired. Only keys that carry a character get one; Escape and the arrows must not, and neither
+         * does a chord with Control or Meta, which is a command rather than typing.
+         */
+        const { spec, modifiers } = parsed;
+        const down = spec.text !== undefined ? { ...spec, unmodifiedText: spec.text } : spec;
+        await this.call('Input.dispatchKeyEvent', { type: 'keyDown', modifiers, ...down });
+        await this.call('Input.dispatchKeyEvent', { type: 'keyUp', modifiers, ...spec, text: undefined });
         await this.settleAfterAction();
         return { ok: true };
     }
+    /**
+     * The element at a point on the page, as the panel's picker points at it.
+     *
+     * x and y are in the page's own viewport coordinates — the panel scales its picture back the same
+     * way a click does. Nothing on the page is touched: no click, no focus, no outline written into
+     * it. Null when the point is off the page.
+     */
+    async inspect(x, y) {
+        if (!this.running)
+            return null;
+        return this.evaluate(`(() => {
+      let el = document.elementFromPoint(${Math.round(x)}, ${Math.round(y)});
+      // The page itself is not an element anybody points at: nothing to name, nothing to find.
+      if (!el || el === document.documentElement || el === document.body) return null;
+      // A bare text span inside a button is not what anybody means by pointing at the button.
+      const lift = el.closest('button,a[href],label,input,select,textarea,[role=button],[role=link],[role=tab],[role=option],[role=menuitem]');
+      if (lift && lift.contains(el)) el = lift;
+      const reg = window.__koneckRefs || (window.__koneckRefs = { next: 1, of: new WeakMap(), els: new Map() });
+      let ref = reg.of.get(el);
+      if (!ref) { ref = reg.next++; reg.of.set(el, ref); reg.els.set(ref, new WeakRef(el)); }
+      const esc = (s) => CSS.escape(s);
+      const unique = (sel) => { try { return document.querySelectorAll(sel).length === 1; } catch (e) { return false; } };
+      const tag = el.tagName.toLowerCase();
+      const classes = [...el.classList].filter(c => c.length < 60).slice(0, 12);
+      const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || el.getAttribute('data-cy');
+      let selector = '';
+      if (el.id && unique('#' + esc(el.id))) selector = '#' + esc(el.id);
+      else if (testId && unique('[data-testid="' + testId + '"]')) selector = '[data-testid="' + testId + '"]';
+      else if (el.getAttribute('name') && unique(tag + '[name="' + el.getAttribute('name') + '"]')) selector = tag + '[name="' + el.getAttribute('name') + '"]';
+      if (!selector) {
+        const parts = [];
+        for (let n = el; n && n.nodeType === 1 && n !== document.body; n = n.parentElement) {
+          if (n.id) { parts.unshift('#' + esc(n.id)); break; }
+          let i = 1, sib = n;
+          while ((sib = sib.previousElementSibling)) i++;
+          parts.unshift(n.tagName.toLowerCase() + ':nth-child(' + i + ')');
+        }
+        selector = (parts[0] && parts[0][0] === '#' ? '' : 'body > ') + parts.join(' > ');
+      }
+      const attrs = {};
+      for (const a of ['name', 'type', 'href', 'src', 'alt', 'placeholder', 'aria-label', 'title', 'for', 'action', 'role', 'data-testid', 'data-test', 'data-cy']) {
+        const v = el.getAttribute(a);
+        if (v) attrs[a] = v.slice(0, 160);
+      }
+      const describe = (n) => n.tagName.toLowerCase() + (n.id ? '#' + n.id : '')
+        + [...n.classList].slice(0, 3).map(c => '.' + c).join('');
+      const path = [];
+      for (let n = el.parentElement; n && n !== document.body && path.length < 5; n = n.parentElement) path.unshift(describe(n));
+      const cs = getComputedStyle(el);
+      const styles = {};
+      for (const k of ['color', 'background-color', 'font-size', 'font-weight', 'font-family', 'line-height',
+                       'padding', 'margin', 'border', 'border-radius', 'display', 'gap', 'text-align']) {
+        const v = cs.getPropertyValue(k);
+        if (v && v !== 'normal' && v !== 'none' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[k] = v.slice(0, 80);
+      }
+      const b = el.getBoundingClientRect();
+      // The markup, with a password's value and any inline data URIs kept out of it.
+      let html = el.outerHTML.replace(/ value="[^"]*"/g, (m) => (el.type === 'password' ? '' : m)).replace(/data:[^"')]{80,}/g, 'data:…');
+      if (html.length > 700) {
+        const open = html.slice(0, html.indexOf('>') + 1);
+        html = open.slice(0, 500) + ' … </' + tag + '>';
+      }
+      return {
+        tag, ...(el.id ? { id: el.id } : {}), classes,
+        ...(el.getAttribute('role') ? { role: el.getAttribute('role') } : {}),
+        text: (el.innerText || el.value && el.type !== 'password' && el.value || '').replace(/\\s+/g, ' ').trim().slice(0, 200),
+        attrs, selector, path,
+        box: { x: Math.round(b.left), y: Math.round(b.top), w: Math.round(b.width), h: Math.round(b.height) },
+        styles, html, ref, url: location.href,
+      };
+    })()`);
+    }
+    /*
+     * The live picture.
+     *
+     * The panel showed a still taken after each action, so a page animating, loading or being typed
+     * into was a series of snapshots with nothing between them. Chromium can stream its compositor
+     * frames; they are passed on while anybody is watching and stopped when nobody is, because a
+     * screencast is not free on a four-core machine.
+     */
+    frameListeners = new Set();
+    casting = false;
+    /** Subscribes to live frames; returns the unsubscribe. The first subscriber starts the cast. */
+    watch(onFrame) {
+        this.frameListeners.add(onFrame);
+        if (!this.casting && this.running) {
+            this.casting = true;
+            void this.call('Page.startScreencast', { format: 'jpeg', quality: 60, everyNthFrame: 1 });
+        }
+        return () => {
+            this.frameListeners.delete(onFrame);
+            if (this.frameListeners.size === 0 && this.casting) {
+                this.casting = false;
+                void this.call('Page.stopScreencast', {});
+            }
+        };
+    }
+    /** How many are watching live — for the panel to say it is live, and for tests. */
+    get watchers() { return this.frameListeners.size; }
+    /** Reloads the page and waits for it, which the panel's refresh button never actually did. */
+    async reload() {
+        if (!this.running)
+            return { ok: false, error: 'no page is open' };
+        await this.call('Page.reload', { ignoreCache: false });
+        const how = await this.settle();
+        return how.settled ? { ok: true } : { ok: true, error: 'the page was still loading when it was read' };
+    }
+    /** Moves the pointer over something, for the menus and tooltips that only appear on hover. */
+    async hover(target) {
+        const selector = await this.resolve(target);
+        if (!selector)
+            return { ok: false, error: `could not find that on the page. What is here: ${await this.describeControls()}` };
+        const at = await this.centreOf(selector);
+        if (!at)
+            return { ok: false, error: `${selector} is not visible` };
+        await this.call('Input.dispatchMouseEvent', { type: 'mouseMoved', x: at.x, y: at.y });
+        await new Promise(r => setTimeout(r, 180)); // a hover menu animates in
+        await this.settleQuick();
+        return { ok: true };
+    }
+    /**
+     * Chooses an option by what it says: a native <select>, or a custom dropdown opened and picked.
+     *
+     * The model was left to work out which of the two it had — fill for a select, click then click
+     * for a component library's — and got it wrong often enough to be reported. This does both.
+     */
+    async choose(target, option) {
+        const selector = await this.resolve(target);
+        if (!selector)
+            return { ok: false, error: `could not find that on the page. What is here: ${await this.describeControls()}` };
+        const native = await this.selectNativeOption(selector, option);
+        if (native === 'set') {
+            await this.settleAfterAction();
+            return { ok: true };
+        }
+        if (native === 'nomatch') {
+            const options = await this.evaluate(`[...document.querySelector(${JSON.stringify(selector)}).options].map(o => o.text.trim()).slice(0, 30).join(', ')`);
+            return { ok: false, error: `no option "${option}". It has: ${options ?? '(none)'}` };
+        }
+        const opened = await this.click({ selector });
+        if (!opened.ok)
+            return opened;
+        await new Promise(r => setTimeout(r, 150));
+        const item = await this.findVisibleByText(option);
+        if (!item)
+            return { ok: false, error: `opened it, but no option "${option}" appeared. What is here: ${await this.describeControls()}` };
+        return this.click({ selector: item });
+    }
+    /** Ticks or unticks a checkbox, radio or switch — only clicking when it is not already so. */
+    async check(target, on = true) {
+        const selector = await this.resolve(target);
+        if (!selector)
+            return { ok: false, error: `could not find that on the page. What is here: ${await this.describeControls()}` };
+        const now = await this.evaluate(`(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return null;
+      if (typeof el.checked === 'boolean') return el.checked;
+      const a = el.getAttribute('aria-checked') || el.getAttribute('aria-pressed');
+      return a === null ? null : a === 'true';
+    })()`);
+        if (now === on)
+            return { ok: true, already: true };
+        return this.click({ selector });
+    }
+    /**
+     * Waits until some text or an element appears — or goes — rather than for a guessed time.
+     *
+     * A spinner, a toast, a row that arrives after a request: the model had no way to wait for any of
+     * them but to read again and again, each read a whole round trip.
+     */
+    async waitFor(what, timeoutMs = 10_000) {
+        const started = Date.now();
+        const limit = Math.max(200, Math.min(timeoutMs, 30_000));
+        const probe = what.selector
+            ? `(() => { const el = document.querySelector(${JSON.stringify(what.selector)});
+           if (!el) return false; const b = el.getBoundingClientRect(); return b.width > 0 && b.height > 0; })()`
+            : `(document.body ? document.body.innerText : '').toLowerCase().includes(${JSON.stringify((what.text ?? '').toLowerCase())})`;
+        for (;;) {
+            const seen = await this.evaluate(probe);
+            if (seen === !what.gone)
+                return { ok: true, ms: Date.now() - started };
+            if (Date.now() - started >= limit) {
+                const thing = what.selector ?? `"${what.text}"`;
+                return { ok: false, ms: Date.now() - started,
+                    error: `${thing} ${what.gone ? 'was still there' : 'did not appear'} after ${Math.round(limit / 100) / 10}s` };
+            }
+            await new Promise(r => setTimeout(r, 150));
+        }
+    }
     /**
      * Back, and forward.
      *
@@ -1281,6 +1750,8 @@ export class Browser {
         return this.lastShot;
     }
     async stop() {
+        // A stopped browser casts nothing; whoever was watching is left with the last frame.
+        this.casting = false;
         for (const { timer, resolve } of this.pending.values()) {
             clearTimeout(timer);
             resolve(null);
@@ -1293,6 +1764,10 @@ export class Browser {
         this.socket = null;
         const child = this.child;
         this.child = null;
+        if (this.onExit) {
+            process.off('exit', this.onExit);
+            this.onExit = null;
+        }
         if (child && child.exitCode === null) {
             try {
                 child.kill('SIGKILL');