dsh-builtin-browser 0.1.22 → 0.2.0

package/lib/browser-electron/provider.d.ts

@@ -6,6 +6,8 @@
  * shell that owns the `BrowserWindow`.
  * @module dsh-browser/browser-electron
  */
+import { type VisitedPage } from './history-store.js';
+import type { BrowserSettings } from './settings-store.js';
 import type { BrowserA11yRequest, BrowserA11yResult, BrowserChallenge, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserHistoryEntry, BrowserOpenRequest, BrowserProvider, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, ExportedCookie } from '../browser/types.js';
 /** Stable provider id registered with `ctx.browser`. */
 export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
@@ -78,6 +80,13 @@ export interface ElectronBrowserViewHost {
      * @param handler - called for every user action; must not throw.
      */
     onUserAction?(handler: (action: BrowserUserAction) => void): void;
+    /**
+     * Optional: receive notice that the human closed a browser window. Closing the
+     * interface ends the session it showed — the next call opens a clean one —
+     * while browsing history and login state survive on disk.
+     * @param handler - called with the group (session) key; must not throw.
+     */
+    onViewClosed?(handler: (windowId: string) => void): void;
 }
 /**
  * A user-initiated browser action from the host's own UI (toolbar). The
@@ -126,11 +135,39 @@ export interface ElectronViewHandle {
      * @returns the CDP `result` object.
      */
     sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Give the backing view web focus so keyboard input reaches its page.
+     * Optional: an adapter that cannot focus a view omits it, and the provider
+     * then behaves exactly as before.
+     */
+    focus?(): Promise<void>;
 }
 /** Provider config: navigation admission defaults and snapshot caps. */
 export interface ElectronBrowserProviderConfig {
     /** Allow navigation only to HTTP(S) URLs; reject anything else. Default true. */
     readonly httpOnly?: boolean;
+    /**
+     * Persistent browsing history (visited pages), independent of session
+     * lifetime. `enabled: false` keeps the browser working but records nothing;
+     * the retained limits ride along so a user's choice from the settings panel
+     * reaches the store without a second configuration path.
+     */
+    readonly history?: {
+        readonly enabled?: boolean;
+        readonly maxEntries?: number;
+        readonly maxAgeDays?: number;
+        /**
+         * Explicit history file path. Default: beside the browser profile
+         * (`$DSH_HOME/dsh-builtin-browser-host/history.jsonl`).
+         */
+        readonly file?: string;
+    };
+    /**
+     * Live settings source (the settings panel's document). When present it wins
+     * over the static `history` config, so a switch flipped in the UI takes effect
+     * without restarting DSH.
+     */
+    readonly settings?: () => BrowserSettings;
     /** Maximum snapshot elements before truncation. Default 60. */
     readonly snapshotMaxElements?: number;
     /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
@@ -151,14 +188,16 @@ export interface CdpNavigateParams {
     readonly url: string;
 }
 /**
- * CDP method/params for `Input.dispatchMouseEvent` (a click press+release pair).
+ * CDP method/params for `Input.dispatchMouseEvent`: a pointer move, or one half
+ * of a click's press+release pair. `button`/`clickCount` belong to the press and
+ * release halves; a move carries only the position.
  */
 export interface CdpMouseParams {
-    readonly type: 'mousePressed' | 'mouseReleased';
+    readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased';
     readonly x: number;
     readonly y: number;
-    readonly button: 'left';
-    readonly clickCount: number;
+    readonly button?: 'left';
+    readonly clickCount?: number;
 }
 /** CDP method/params for `Input.insertText`. */
 export interface CdpInsertTextParams {
@@ -200,6 +239,13 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private readonly snapshotMaxElements;
     private readonly contentMaxChars;
     private readonly downloadDir;
+    /**
+     * Persistent browsing history, or `undefined` when the user turned it off.
+     * Sessions come and go; this record outlives all of them.
+     */
+    private readonly historyStore;
+    /** Live settings source; absent when nothing owns a settings document. */
+    private readonly settingsSource;
     constructor(host: ElectronBrowserViewHost, config?: ElectronBrowserProviderConfig);
     /**
      * Usable when the host says it can back views (the self-hosted host probes
@@ -278,6 +324,17 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * rather than reporting a success the page never saw.
      */
     private present;
+    /**
+     * Give the view web focus before synthesizing keyboard input.
+     *
+     * A renderer only delivers key events to the view that holds web focus. A
+     * view that was created but never clicked holds none — and `Input` events
+     * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+     * session vanished inside the renderer while the command still answered
+     * success. Hosts that cannot focus a view (a test double, a different shell
+     * adapter) simply have no `focus`, and nothing changes for them.
+     */
+    private focusView;
     /** Execute JS in the active tab's page context. */
     execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult>;
     /**
@@ -342,6 +399,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * (polling until it appears or the budget runs out) and then runs `body`
      * with `el` in scope. Shared by the target-based tools: click/type (②),
      * setValue/check/select/clear/getValue (③), and the scrape item wait.
+     * A selector that fails to PARSE is reported immediately instead of being
+     * polled until the budget expires — see the comment in `match`.
      */
     private buildTargetScript;
     /**
@@ -426,6 +485,34 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private record;
     /** Return the session's chronological operation log (newest last). */
     history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /**
+     * Record one page visit in the persistent browsing history. Fire-and-forget by
+     * design: a visit must never delay or fail the navigation that produced it,
+     * and the title is only worth reading once the document has settled.
+     * @param s - the session that drove the visit.
+     * @param handle - the view whose document just loaded.
+     */
+    private recordVisit;
+    /**
+     * List persisted visits, newest first — what `browser_visited` reads back.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the matching visits, or an empty list when history is disabled.
+     */
+    visited(options?: {
+        readonly limit?: number;
+        readonly domain?: string;
+    }): readonly VisitedPage[];
+    /**
+     * Show the synthetic pointer on a view, unless the user switched it off. The
+     * cursor is the "the agent has taken over this tab" signal, so it is painted
+     * for every operation that has a landing point — including DOM-level ones that
+     * move no real pointer.
+     * @param handle - the view to paint into.
+     * @param x - viewport x in CSS pixels.
+     * @param y - viewport y in CSS pixels.
+     * @param action - click pulses a ripple; move only relocates.
+     */
+    private showCursor;
     /**
      * Replay one recorded operation by sequence number. Navigate/click/type are
      * re-issued against the current page; execute re-runs its script. The
@@ -444,6 +531,20 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private newTab;
     /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
     private tabByViewId;
+    /**
+     * Whether a session is still live. The human closing a window ends its session
+     * (see {@link handleViewClosed}), so callers that cache ids must ask first.
+     * @param session - the session id to test.
+     */
+    exists(session: BrowserSessionId): boolean;
+    /**
+     * The human closed a browser window: the session that window showed is over.
+     * Ending it here is what makes the next call a clean start rather than a
+     * resurrection of an invisible window. Browsing history and login state live
+     * on disk, so nothing the human cares about is lost with it.
+     * @param windowId - the group key the host reported, which is the session id.
+     */
+    private handleViewClosed;
     /**
      * Route a user-initiated action from the host's UI into the session model.
      * Fire-and-forget by design: a user action failing (e.g. an unreachable

package/lib/browser-electron/provider.js

@@ -10,6 +10,8 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { HistoryStore } from './history-store.js';
+import { paintCursor } from './virtual-cursor.js';
 import { BrowserError } from '../browser/types.js';
 /**
  * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
@@ -135,6 +137,13 @@ export class ElectronBrowserProvider {
     snapshotMaxElements;
     contentMaxChars;
     downloadDir;
+    /**
+     * Persistent browsing history, or `undefined` when the user turned it off.
+     * Sessions come and go; this record outlives all of them.
+     */
+    historyStore;
+    /** Live settings source; absent when nothing owns a settings document. */
+    settingsSource;
     constructor(host, config = {}) {
         this.host = host;
         this.httpOnly = config.httpOnly ?? true;
@@ -146,9 +155,21 @@ export class ElectronBrowserProvider {
         // sandbox does not have to arbitrate. The localized name is probed so a
         // Chinese desktop (`~/下载`) works without configuring `downloadDir`.
         this.downloadDir = config.downloadDir ?? defaultDownloadDir();
+        this.settingsSource = config.settings;
+        // Browsing history follows the browser profile's persistence rules (close
+        // the interface, lose nothing), and can be switched off from settings.
+        this.historyStore = config.history?.enabled === false
+            ? undefined
+            : new HistoryStore(config.history?.file, {
+                ...config.history?.maxEntries !== undefined ? { maxEntries: config.history.maxEntries } : {},
+                ...config.history?.maxAgeDays !== undefined ? { maxAgeDays: config.history.maxAgeDays } : {},
+            });
         // Route toolbar (host UI) actions into the session model: the human and
         // the agent then always drive the same tabs, history, and navigation.
         this.host.onUserAction?.(action => { void this.handleUserAction(action); });
+        // A window the human closed ends the session it showed: the next call opens a
+        // clean one instead of driving a page nobody can see.
+        this.host.onViewClosed?.(windowId => { void this.handleViewClosed(windowId); });
     }
     /**
      * Usable when the host says it can back views (the self-hosted host probes
@@ -313,6 +334,7 @@ export class ElectronBrowserProvider {
             // NEXT observation sees, not whether this action happened).
             this.record(s, 'navigate', { url }, true);
             await this.settleDocument(handle, before, signal);
+            this.recordVisit(s, handle);
             this.showActive(s);
         }
         catch (error) {
@@ -419,6 +441,27 @@ export class ElectronBrowserProvider {
             throw new BrowserError(`browser: the page view is not presented, so synthesized input would be silently dropped (${String(error)})`, 'BROWSER_VIEW_NOT_PRESENTED', { cause: error });
         }
     }
+    /**
+     * Give the view web focus before synthesizing keyboard input.
+     *
+     * A renderer only delivers key events to the view that holds web focus. A
+     * view that was created but never clicked holds none — and `Input` events
+     * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+     * session vanished inside the renderer while the command still answered
+     * success. Hosts that cannot focus a view (a test double, a different shell
+     * adapter) simply have no `focus`, and nothing changes for them.
+     */
+    async focusView(handle) {
+        if (handle.focus === undefined)
+            return;
+        try {
+            await handle.focus();
+        }
+        catch {
+            // Best-effort: a view that refuses focus must not fail the caller's key
+            // press; the dispatch below reports a real channel failure itself.
+        }
+    }
     /** Execute JS in the active tab's page context. */
     async execute(session, request, signal) {
         const s = this.session(session);
@@ -915,24 +958,51 @@ export class ElectronBrowserProvider {
         // Input.* is only delivered to a view with a current display surface; the
         // barrier also re-presents after a navigation replaced the renderer.
         await this.present(s, signal);
-        const press = (type) => handle.sendCommand('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 });
         const timeoutMs = 30_000;
+        const send = (params, label) => withTimeout(handle.sendCommand('Input.dispatchMouseEvent', params), timeoutMs, signal, `browser: click ${label} timed out after ${timeoutMs}ms`);
+        // Chromium routes a synthesized `mousePressed` to the widget's *current*
+        // hover target rather than hit-testing the coordinates, and a real pointer
+        // click is always preceded by movement. A view that has never received a
+        // mouse event has no hover target yet, so the press of the FIRST click on a
+        // fresh tab went nowhere while CDP still answered success; the second click
+        // landed because the first had quietly established the target. Move the
+        // pointer first so a click is self-contained.
         try {
-            await withTimeout(press('mousePressed'), timeoutMs, signal, `browser: click press timed out after ${timeoutMs}ms`);
+            await send({ type: 'mouseMoved', x, y }, 'move');
+        }
+        catch (error) {
+            throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
+        }
+        // Paint before the press so the ripple is already on screen when the click
+        // lands — the cursor exists to show the human WHERE the agent acts.
+        this.showCursor(handle, x, y, 'click');
+        const release = () => {
+            void handle
+                .sendCommand('Input.dispatchMouseEvent', {
+                type: 'mouseReleased',
+                x,
+                y,
+                button: 'left',
+                clickCount: 1,
+            })
+                .catch(() => { });
+        };
+        try {
+            await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press');
         }
         catch (error) {
             // The press may still land late; release best-effort so the button is
             // never left in a stuck pressed state.
-            void press('mouseReleased').catch(() => { });
+            release();
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
         }
         try {
-            await withTimeout(press('mouseReleased'), timeoutMs, signal, `browser: click release timed out after ${timeoutMs}ms`);
+            await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release');
         }
         catch (error) {
             // The press already landed; retry the release so the button is not
             // left pressed before surfacing the failure.
-            void press('mouseReleased').catch(() => { });
+            release();
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
         }
         this.record(s, 'click', 'target' in request ? { target: request.target } : { x, y }, true);
@@ -952,7 +1022,11 @@ export class ElectronBrowserProvider {
         el.focus()
         return { ok: true }
       `);
-            await this.runTargetScript(this.activeTab(s), script, locateMs, signal, 'BROWSER_TYPE_FAILED', 'browser: type');
+            const locateTab = this.activeTab(s);
+            const out = await this.runTargetScript(locateTab, script, locateMs, signal, 'BROWSER_TYPE_FAILED', 'browser: type');
+            const cursorPoint = scriptPoint(out);
+            if (cursorPoint !== undefined)
+                this.showCursor(locateTab.handle, cursorPoint.x, cursorPoint.y, 'click');
         }
         const text = 'text' in request ? request.text : '';
         const timeoutMs = 30_000;
@@ -1022,6 +1096,7 @@ export class ElectronBrowserProvider {
         await withTimeout(handle.sendCommand('Page.navigateToHistoryEntry', { entryId: entry.id }), timeoutMs, signal, `browser: history navigation timed out after ${timeoutMs}ms`, () => { void handle.sendCommand('Page.stopLoading').catch(() => { }); });
         this.record(s, direction === -1 ? 'back' : 'forward', {}, true);
         await this.settleDocument(handle, before, signal);
+        this.recordVisit(s, handle);
         this.showActive(s);
     }
     /** Go back in the active tab's history. */
@@ -1046,6 +1121,7 @@ export class ElectronBrowserProvider {
         () => { void handle.sendCommand('Page.stopLoading').catch(() => { }); });
         this.record(s, 'reload', {}, true);
         await this.settleDocument(handle, before, signal);
+        this.recordVisit(s, handle);
         this.showActive(s);
     }
     /** Press one named key (Enter/Tab/arrows/…) via CDP key events. */
@@ -1061,6 +1137,7 @@ export class ElectronBrowserProvider {
         const timeoutMs = 15_000;
         // Input.dispatchKeyEvent is subject to the same display-surface rule.
         await this.present(s, signal);
+        await this.focusView(handle);
         const release = () => handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params });
         try {
             await withTimeout(handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyDown', ...params }), timeoutMs, signal, `browser: key press timed out after ${timeoutMs}ms`);
@@ -1231,10 +1308,16 @@ export class ElectronBrowserProvider {
      * (polling until it appears or the budget runs out) and then runs `body`
      * with `el` in scope. Shared by the target-based tools: click/type (②),
      * setValue/check/select/clear/getValue (③), and the scrape item wait.
+     * A selector that fails to PARSE is reported immediately instead of being
+     * polled until the budget expires — see the comment in `match`.
      */
     buildTargetScript(spec, timeoutMs, body) {
+        // `by` defaults to css in-page; report the strategy that WAS used, or a
+        // miss says only `{"value":"Learn more"}` and the caller cannot tell that a
+        // plain label was queried as a CSS selector.
+        const resolvedSpec = { ...spec, by: spec.by ?? 'css' };
         return `(async () => {
-      const spec = ${JSON.stringify(spec)}
+      const spec = ${JSON.stringify(resolvedSpec)}
       const timeoutMs = ${String(timeoutMs)}
       const sleep = ms => new Promise(r => setTimeout(r, ms))
       const isVisible = el => el instanceof HTMLElement && (el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0)
@@ -1246,7 +1329,13 @@ export class ElectronBrowserProvider {
         const index = typeof spec.index === 'number' ? spec.index : 0
         let els = []
         if (by === 'css') {
-          try { els = Array.from(document.querySelectorAll(value)) } catch { return null }
+          // A selector that does not PARSE can never match on a later poll, so
+          // it must not look like a miss: the old "return null" kept the caller
+          // polling until the whole budget was gone, and "element not found
+          // after 10s" reads like a slow page while the real cause is a
+          // malformed selector (a label or plain text passed where one belongs).
+          try { els = Array.from(document.querySelectorAll(value)) }
+          catch (error) { throw new Error('invalid CSS selector ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else if (by === 'xpath') {
           try {
             const snap = document.evaluate(value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
@@ -1254,7 +1343,7 @@ export class ElectronBrowserProvider {
               const n = snap.snapshotItem(i)
               if (n instanceof Element) els.push(n)
             }
-          } catch { return null }
+          } catch (error) { throw new Error('invalid XPath ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else {
           const all = Array.from(document.querySelectorAll('body *'))
           const exact = all.filter(el => isVisible(el) && ownText(el) === value)
@@ -1268,12 +1357,24 @@ export class ElectronBrowserProvider {
       const deadline = Date.now() + timeoutMs
       let el = null
       for (;;) {
-        el = match()
+        // Only a parse error escapes the poll: see the comment in match() above.
+        try { el = match() } catch (error) { return { ok: false, error: String((error && error.message) || error) } }
         if (el !== null) break
-        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) }
+        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) + ' (looked for ' + timeoutMs + 'ms)' }
         await sleep(100)
       }
+      const __result = await (async () => {
       ${body}
+      })()
+      // Report the operated element's viewport center next to the script's own
+      // verdict: the synthetic cursor (and any future feedback) needs the point,
+      // and no individual body should have to compute it a second time. Kept
+      // under a distinct key so a body that already returns x/y keeps them.
+      const __rect = el.getBoundingClientRect()
+      return {
+        ...(typeof __result === 'object' && __result !== null ? __result : { ok: true }),
+        __point: { x: Math.round(__rect.x + __rect.width / 2), y: Math.round(__rect.y + __rect.height / 2) },
+      }
     })()`;
     }
     /**
@@ -1282,7 +1383,12 @@ export class ElectronBrowserProvider {
      * evaluation failure or an in-page `{ ok: false, error }` verdict.
      */
     async runTargetScript(tab, script, timeoutMs, signal, errorCode, errorLabel) {
-        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `${errorLabel} timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        // The script polls for its whole `timeoutMs` and only then answers, so an
+        // outer budget of the same size fires at the same instant and wins: the
+        // caller saw `click timed out after 10000ms` while the page had already
+        // decided WHY (selector not found / malformed). Give the answer a chance to
+        // get back before the generic timeout replaces it.
+        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs + TARGET_SCRIPT_GRACE_MS, signal, `${errorLabel} timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
         if (!result.ok)
             throw new BrowserError(`${errorLabel} failed: ${result.exception}`, errorCode);
         const value = result.value;
@@ -1333,6 +1439,9 @@ export class ElectronBrowserProvider {
     `;
         const script = this.buildTargetScript(request.target, timeoutMs, body);
         const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_SET_VALUE_FAILED', 'browser: setValue');
+        const cursorPoint = scriptPoint(out);
+        if (cursorPoint !== undefined)
+            this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click');
         this.record(s, 'setValue', { target: request.target, value: String(request.value) }, true, { result: out.method });
         return { method: out.method, value: out.value };
     }
@@ -1358,6 +1467,9 @@ export class ElectronBrowserProvider {
     `;
         const script = this.buildTargetScript(request.target, timeoutMs, body);
         const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CHECK_FAILED', 'browser: check');
+        const cursorPoint = scriptPoint(out);
+        if (cursorPoint !== undefined)
+            this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click');
         this.record(s, 'check', { target: request.target, checked: want }, true);
         return { checked: out.checked === true };
     }
@@ -1389,6 +1501,9 @@ export class ElectronBrowserProvider {
     `;
         const script = this.buildTargetScript(request.target, timeoutMs, body);
         const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_SELECT_FAILED', 'browser: select');
+        const cursorPoint = scriptPoint(out);
+        if (cursorPoint !== undefined)
+            this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click');
         this.record(s, 'select', { target: request.target, optionValue: request.optionValue ?? null, optionText: request.optionText ?? null, optionIndex: request.optionIndex ?? null }, true);
         return { value: out.value, text: out.text };
     }
@@ -1421,7 +1536,10 @@ export class ElectronBrowserProvider {
       return { ok: true }
     `;
         const script = this.buildTargetScript(request.target, timeoutMs, body);
-        await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CLEAR_FAILED', 'browser: clear');
+        const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CLEAR_FAILED', 'browser: clear');
+        const cursorPoint = scriptPoint(out);
+        if (cursorPoint !== undefined)
+            this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click');
         this.record(s, 'clear', { target: request.target }, true);
         return { cleared: true };
     }
@@ -1474,7 +1592,9 @@ export class ElectronBrowserProvider {
       const deadline = Date.now() + timeoutMs
       let items = []
       for (;;) {
-        try { items = Array.from(document.querySelectorAll(itemSel)) } catch (e) { return { ok: false, error: String(e) } }
+        // Immediate, like match() above: an unparseable selector can never match.
+        try { items = Array.from(document.querySelectorAll(itemSel)) }
+        catch (error) { return { ok: false, error: 'invalid CSS selector ' + JSON.stringify(itemSel) + ' (' + String((error && error.message) || error) + ')' } }
         if (items.length > 0) break
         if (Date.now() >= deadline) return { ok: false, error: 'no elements matched: ' + itemSel }
         await sleep(100)
@@ -1709,6 +1829,62 @@ export class ElectronBrowserProvider {
     async history(session) {
         return this.session(session).history;
     }
+    /**
+     * Record one page visit in the persistent browsing history. Fire-and-forget by
+     * design: a visit must never delay or fail the navigation that produced it,
+     * and the title is only worth reading once the document has settled.
+     * @param s - the session that drove the visit.
+     * @param handle - the view whose document just loaded.
+     */
+    recordVisit(s, handle) {
+        const store = this.historyStore;
+        if (store === undefined)
+            return;
+        // The settings panel can switch recording off at runtime; the static config
+        // only supplies the startup default.
+        if (this.settingsSource !== undefined && !this.settingsSource().history.enabled)
+            return;
+        void handleSendEvaluate(handle, 'location.href + "\\u0000" + (document.title || "")')
+            .then(result => {
+            if (!result.ok || typeof result.value !== 'string')
+                return;
+            const [url = '', title = ''] = result.value.split('\u0000');
+            // Internal documents are not visits: an untouched browser is not history.
+            if (url === '' || url.startsWith('about:') || url.startsWith('devtools:'))
+                return;
+            store.append({
+                at: Date.now(),
+                url,
+                ...title.trim() !== '' ? { title: title.trim() } : {},
+                ...s.label !== undefined ? { session: s.label } : {},
+            });
+            store.prune();
+        })
+            .catch(() => { });
+    }
+    /**
+     * List persisted visits, newest first — what `browser_visited` reads back.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the matching visits, or an empty list when history is disabled.
+     */
+    visited(options = {}) {
+        return this.historyStore?.list(options) ?? [];
+    }
+    /**
+     * Show the synthetic pointer on a view, unless the user switched it off. The
+     * cursor is the "the agent has taken over this tab" signal, so it is painted
+     * for every operation that has a landing point — including DOM-level ones that
+     * move no real pointer.
+     * @param handle - the view to paint into.
+     * @param x - viewport x in CSS pixels.
+     * @param y - viewport y in CSS pixels.
+     * @param action - click pulses a ripple; move only relocates.
+     */
+    showCursor(handle, x, y, action) {
+        if (this.settingsSource !== undefined && !this.settingsSource().ui.virtualCursor)
+            return;
+        paintCursor(handle, x, y, action, (target, expression) => handleSendEvaluate(target, expression));
+    }
     /**
      * Replay one recorded operation by sequence number. Navigate/click/type are
      * re-issued against the current page; execute re-runs its script. The
@@ -1822,6 +1998,29 @@ export class ElectronBrowserProvider {
     tabByViewId(s, viewId) {
         return s.tabs.find(tab => tab.handle.id === viewId);
     }
+    /**
+     * Whether a session is still live. The human closing a window ends its session
+     * (see {@link handleViewClosed}), so callers that cache ids must ask first.
+     * @param session - the session id to test.
+     */
+    exists(session) {
+        return this.sessions.has(session);
+    }
+    /**
+     * The human closed a browser window: the session that window showed is over.
+     * Ending it here is what makes the next call a clean start rather than a
+     * resurrection of an invisible window. Browsing history and login state live
+     * on disk, so nothing the human cares about is lost with it.
+     * @param windowId - the group key the host reported, which is the session id.
+     */
+    async handleViewClosed(windowId) {
+        if (typeof windowId !== 'string' || windowId === '')
+            return;
+        const s = this.sessions.get(windowId);
+        if (s === undefined)
+            return;
+        await this.close(s.id).catch(() => { });
+    }
     /**
      * Route a user-initiated action from the host's UI into the session model.
      * Fire-and-forget by design: a user action failing (e.g. an unreachable
@@ -1913,6 +2112,12 @@ const SETTLE_TIMEOUT_MS = 5_000;
 const SETTLE_GRACE_MS = 150;
 /** Poll interval for the document-settle loop. */
 const SETTLE_POLL_MS = 25;
+/**
+ * Extra time the transport gets over an in-page locate script's own budget: the
+ * script polls for `timeoutMs` and answers only afterwards, so the outer wait
+ * must outlast it or its generic timeout hides the in-page reason.
+ */
+const TARGET_SCRIPT_GRACE_MS = 2_000;
 /** `tab:<uuid>` ↔ `<uuid>`: ids accept either form (see locateTab). */
 function stripTabPrefix(id) {
     return id.startsWith('tab:') ? id.slice(4) : id;
@@ -2007,6 +2212,13 @@ function terminatePage(handle) {
  * @param expression - the JS expression.
  * @param signal - optional abort signal; a fired signal rejects the call.
  */
+/** Viewport point a target script reported, when it reported one. */
+function scriptPoint(out) {
+    const point = out?.__point;
+    const x = Number(point?.x);
+    const y = Number(point?.y);
+    return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : undefined;
+}
 async function handleSendEvaluate(handle, expression, signal) {
     signal?.throwIfAborted();
     const result = await handle.sendCommand(CDP_RUNTIME_EVALUATE, {