dsh-builtin-browser 0.1.22 → 0.2.0

package/lib/browser-electron/remote-host.d.ts

@@ -99,29 +99,50 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly spawnExecutable?;
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    private readonly probe;
     private client;
     private server;
     private pendingSocket;
     private readonly views;
     private readyPromise;
     private disposed;
-    /** Cached probe result so `available()` stays cheap after the first call. */
+    /** Last probe result. A success is kept for the host's lifetime; a failure
+     *  is retried after `PROBE_RETRY_MS` (see `available()`). */
     private electronAvailable;
+    /** Earliest time the next probe may run after a negative one. */
+    private nextProbeAt;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     private readonly groups;
     /** The provider's user-action handler; routes toolbar actions into sessions. */
     private userActionHandler;
+    /**
+     * The provider's handler for a window the human closed. Closing the interface
+     * ends the session it showed: history and login state stay on disk, so the
+     * next open starts clean instead of resuming a window nobody can see.
+     */
+    private viewClosedHandler;
     constructor(hostMainPath: string, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
-    spawnExecutable?: string | undefined);
+    spawnExecutable?: string | undefined, 
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    probe?: () => void);
     /**
      * Cheap usability probe: can we find an Electron binary to spawn? The scan
-     * is filesystem-only (no network), per the seam's contract, and the result
-     * is cached for the host's lifetime — a missing binary surfaces as
-     * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-     * confusing spawn failure on first use.
+     * is filesystem-only (no network), per the seam's contract, so a missing
+     * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+     * instead of a confusing spawn failure on first use.
+     *
+     * A success is cached for the host's lifetime. A failure is NOT: an install
+     * (`npm i electron`, or the postinstall that fetches the binary) can land
+     * long after DSH started, and provider selection happens once per process —
+     * caching "no" permanently reported "no usable browser provider is
+     * registered" until DSH restarted, with no way back short of that. Retrying
+     * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available(): boolean;
     /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
@@ -152,6 +173,8 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     groupView(handle: ElectronViewHandle, windowId: string, label?: string): void;
     /** Register the provider's handler for user-initiated toolbar actions. */
     onUserAction(handler: (action: BrowserUserAction) => void): void;
+    /** Register the provider's handler for windows the human closed. */
+    onViewClosed(handler: (windowId: string) => void): void;
     /** Surface a failed user action to the child's toolbar (address bar etc.). */
     notifyUserActionError(windowId: string, message: string): void;
     destroyView(handle: ElectronViewHandle): void;

package/lib/browser-electron/remote-host.js

@@ -374,6 +374,7 @@ class ElectronChildClient {
     token;
     onExit;
     onUserAction;
+    onViewClosed;
     executable;
     child;
     pending = new Map();
@@ -392,6 +393,12 @@ class ElectronChildClient {
     awaitingHello = true;
     helloTimer;
     constructor(hostMainPath, port, token, onExit, onUserAction, 
+    /**
+     * Called when the human closes a browser window. The session it showed is
+     * over: the provider releases it, while history and login state stay on disk
+     * so the next open is a clean session rather than a resurrected one.
+     */
+    onViewClosed, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     executable) {
@@ -400,9 +407,18 @@ class ElectronChildClient {
         this.token = token;
         this.onExit = onExit;
         this.onUserAction = onUserAction;
+        this.onViewClosed = onViewClosed;
         this.executable = executable;
         const electron = this.executable ?? resolveElectronPath();
+        // Record what is about to be spawned — with existence checks — BEFORE the
+        // attempt. When Electron cannot load the app entry it exits 1 with EMPTY
+        // stderr, and that signature is otherwise indistinguishable from a missing
+        // binary: writing both paths (and whether they exist) in advance is what
+        // turns the next occurrence into a named cause instead of a guess.
         process.stderr.write(`[dsh-browser host] spawning electron: ${electron}\n`);
+        appendHostLog(`${hostStamp()} spawning: electron=${electron} (exists=${String(existsSync(electron))})`
+            + ` hostMain=${this.hostMainPath} (exists=${String(existsSync(this.hostMainPath))})`
+            + ` port=${String(this.port)}\n`);
         // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
         // Node, breaking require('electron'); NODE_OPTIONS can inject flags that
         // break the child. Rebuild the env without either.
@@ -439,15 +455,26 @@ class ElectronChildClient {
         // A failed spawn (bad/corrupt binary) emits 'error' — without a listener
         // that would crash the whole DSH process.
         this.child.on('error', error => {
-            const line = `spawn error: ${String(error)}`;
+            const line = `${hostStamp()} spawn error: ${String(error)} electron=${electron} hostMain=${this.hostMainPath}`;
             process.stderr.write(`[dsh-browser host] ${line}\n`);
             appendHostLog(`${line}\n`);
             this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`));
         });
         this.child.on('exit', (code, signal) => {
             // The exit code/signal is the other half of a crash report; without it a
-            // restart loop is indistinguishable from a clean stop.
-            const line = `browser host exited (code=${String(code)} signal=${String(signal)})`;
+            // restart loop is indistinguishable from a clean stop. The timestamp, pid
+            // and both paths are what turn a bare `code=1` into a diagnosis: Electron
+            // exits 1 with empty stderr precisely when it cannot load the app entry,
+            // so the dated `exists=` line written at spawn is the other half.
+            const entryExists = existsSync(this.hostMainPath);
+            const line = `${hostStamp()} browser host exited (code=${String(code)} signal=${String(signal)})`
+                + ` pid=${String(this.child?.pid)} electron=${electron} hostMain=${this.hostMainPath}`
+                + ` entryExists=${String(entryExists)}`
+                // Comparing this with the `exists=` recorded at spawn is the whole
+                // diagnosis: present at spawn and absent now means the installation was
+                // replaced underneath a running host, which is exactly how Electron ends
+                // up unable to load the app entry and exits 1 with empty stderr.
+                + (entryExists ? '' : ' [entry script missing at exit]');
             appendHostLog(`${line}\n`);
             this.fail(new Error(`dsh-builtin-browser: ${line}`));
         });
@@ -537,6 +564,14 @@ class ElectronChildClient {
                 this.onUserAction?.(msg.action);
                 continue;
             }
+            if (msg.op === 'viewClosed') {
+                // Fire-and-forget notification from the child's own UI: the human closed
+                // the window, so the interface that session showed is gone. The provider
+                // decides what that ends — browsing history and login state survive on
+                // disk, only the session itself does not.
+                this.onViewClosed?.(typeof msg.windowId === 'string' ? msg.windowId : '');
+                continue;
+            }
             if (this.awaitingHello) {
                 // The FIRST line must be the child's hello carrying the spawn token.
                 // Anything else (or a wrong token) means a spoofed connection: drop
@@ -624,6 +659,10 @@ class RemoteView {
             params: params ?? {},
         });
     }
+    /** Give this view web focus in the child, so keyboard input reaches the page. */
+    focus() {
+        return this.client.call('focus', { viewId: this.id });
+    }
     /** Ask the child to download a URL to a local file (keeps cookies/login). */
     async download(url, savePath) {
         // The child writes the file itself (temp + rename); only a small
@@ -644,6 +683,14 @@ class RemoteView {
         return this.client.call('restoreAuth', { viewId: this.id, cookies }).then(r => r.restored);
     }
 }
+/**
+ * How long a FAILED Electron-binary probe is remembered before the binary
+ * search runs again (`available()`). A success is kept for the host's lifetime.
+ */
+const PROBE_RETRY_MS = (() => {
+    const raw = Number(process.env.DSH_BROWSER_PROBE_RETRY_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : 30000;
+})();
 /**
  * Self-hosted view host: spawns the plugin's Electron child on first use and
  * keeps it alive until dispose(). Fallback when no desktop shell provides
@@ -652,46 +699,69 @@ class RemoteView {
 export class RemoteElectronViewHost {
     hostMainPath;
     spawnExecutable;
+    probe;
     client;
     server;
     pendingSocket;
     views = new Map();
     readyPromise;
     disposed = false;
-    /** Cached probe result so `available()` stays cheap after the first call. */
+    /** Last probe result. A success is kept for the host's lifetime; a failure
+     *  is retried after `PROBE_RETRY_MS` (see `available()`). */
     electronAvailable;
+    /** Earliest time the next probe may run after a negative one. */
+    nextProbeAt = 0;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     groups = new Map();
     /** The provider's user-action handler; routes toolbar actions into sessions. */
     userActionHandler;
+    /**
+     * The provider's handler for a window the human closed. Closing the interface
+     * ends the session it showed: history and login state stay on disk, so the
+     * next open starts clean instead of resuming a window nobody can see.
+     */
+    viewClosedHandler;
     constructor(hostMainPath, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
-    spawnExecutable) {
+    spawnExecutable, 
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    probe = resolveElectronPath) {
         this.hostMainPath = hostMainPath;
         this.spawnExecutable = spawnExecutable;
+        this.probe = probe;
     }
     /**
      * Cheap usability probe: can we find an Electron binary to spawn? The scan
-     * is filesystem-only (no network), per the seam's contract, and the result
-     * is cached for the host's lifetime — a missing binary surfaces as
-     * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-     * confusing spawn failure on first use.
+     * is filesystem-only (no network), per the seam's contract, so a missing
+     * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+     * instead of a confusing spawn failure on first use.
+     *
+     * A success is cached for the host's lifetime. A failure is NOT: an install
+     * (`npm i electron`, or the postinstall that fetches the binary) can land
+     * long after DSH started, and provider selection happens once per process —
+     * caching "no" permanently reported "no usable browser provider is
+     * registered" until DSH restarted, with no way back short of that. Retrying
+     * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available() {
-        if (this.electronAvailable === undefined) {
-            try {
-                resolveElectronPath();
-                this.electronAvailable = true;
-            }
-            catch (error) {
-                this.electronAvailable = false;
-                // The provider will be reported unavailable, so the detailed
-                // resolution error (install-electron / ELECTRON_PATH guidance) would
-                // otherwise never reach the user — surface it on stderr.
-                process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
-            }
+        if (this.electronAvailable === true)
+            return true;
+        if (Date.now() < this.nextProbeAt)
+            return false;
+        this.nextProbeAt = Date.now() + PROBE_RETRY_MS;
+        try {
+            this.probe();
+            this.electronAvailable = true;
+        }
+        catch (error) {
+            this.electronAvailable = false;
+            // The provider will be reported unavailable, so the detailed
+            // resolution error (install-electron / ELECTRON_PATH guidance) would
+            // otherwise never reach the user — surface it on stderr.
+            process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
         }
         return this.electronAvailable;
     }
@@ -758,7 +828,7 @@ export class RemoteElectronViewHost {
         // Random per-spawn token: the child must prove knowledge of it (via
         // stdin hello) before any command is written to the socket.
         const token = randomBytes(24).toString('hex');
-        this.client = new ElectronChildClient(this.hostMainPath, port, token, () => this.onChildExit(), action => this.userActionHandler?.(action), this.spawnExecutable);
+        this.client = new ElectronChildClient(this.hostMainPath, port, token, () => this.onChildExit(), action => this.userActionHandler?.(action), windowId => this.viewClosedHandler?.(windowId), this.spawnExecutable);
         if (this.pendingSocket !== undefined) {
             this.client.attach(this.pendingSocket);
             this.pendingSocket = undefined;
@@ -887,6 +957,10 @@ export class RemoteElectronViewHost {
     onUserAction(handler) {
         this.userActionHandler = handler;
     }
+    /** Register the provider's handler for windows the human closed. */
+    onViewClosed(handler) {
+        this.viewClosedHandler = handler;
+    }
     /** Surface a failed user action to the child's toolbar (address bar etc.). */
     notifyUserActionError(windowId, message) {
         void this.ready()
@@ -978,6 +1052,9 @@ class DeferredRemoteView {
     async capture(opts) {
         return this.withRecovery(view => view.capture(opts));
     }
+    async focus() {
+        return this.withRecovery(view => view.focus());
+    }
     async flushAuth() {
         return this.withRecovery(view => view.flushAuth());
     }
@@ -996,6 +1073,15 @@ class DeferredRemoteView {
  * gets large (a crash loop writes quickly).
  */
 const HOST_LOG_MAX_BYTES = 2 * 1024 * 1024;
+/**
+ * ISO timestamp prefix for host-log lines. This log is the only place a spawn
+ * failure is recorded, and an undated line cannot be lined up with anything else
+ * that happened on the machine — a plugin update replacing the entry script, for
+ * instance — which is precisely the question this log gets asked.
+ */
+function hostStamp() {
+    return new Date().toISOString();
+}
 function appendHostLog(text) {
     const home = process.env.DSH_HOME;
     if (home === undefined || home === '')
@@ -1004,8 +1090,12 @@ function appendHostLog(text) {
         const dir = join(home, 'logs');
         const file = join(dir, 'dsh-builtin-browser-host.log');
         try {
-            if (statSync(file).size > HOST_LOG_MAX_BYTES)
-                writeFileSync(file, '');
+            if (statSync(file).size > HOST_LOG_MAX_BYTES) {
+                // Discard the old bytes but leave a dated marker: truncating to empty
+                // makes a rotation look like "nothing ever happened", which is how the
+                // history of a crash loop gets silently swallowed.
+                writeFileSync(file, `${hostStamp()} log rotated: previous content exceeded ${String(HOST_LOG_MAX_BYTES)} bytes and was discarded\n`);
+            }
         }
         catch { /* first write, or unreadable: just append */ }
         mkdirSync(dir, { recursive: true });

package/lib/browser-electron/settings-store.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Plugin-owned settings document — the switches the browser settings panel
+ * exposes, stored next to the browsing history so both follow the same rules:
+ * they survive the browser process and DSH restarts.
+ *
+ * Every field is optional on disk and falls back to a default, so a hand-edited
+ * or older file never breaks startup; an unreadable file is treated as "all
+ * defaults" rather than an error.
+ * @module dsh-browser/browser-electron/settings-store
+ */
+/** Vision/operation strategy the provider prefers when the model can see. */
+export type VisionStrategy = 'auto' | 'nonVisual';
+/** The full settings document, with every field resolved. */
+export interface BrowserSettings {
+    /** Persistent browsing history (visited pages). */
+    readonly history: {
+        readonly enabled: boolean;
+        readonly maxEntries: number;
+        readonly maxAgeDays: number;
+    };
+    /** Login-state retention: cookies and the browser profile. */
+    readonly cookies: {
+        readonly persist: boolean;
+    };
+    /** Presentation behaviour. */
+    readonly ui: {
+        /** Auto-expand the side panel once per task, then leave the user alone. */
+        readonly autoExpandOnce: boolean;
+        /** Release the browser when its session ends, instead of waiting for a close. */
+        readonly closeWithSession: boolean;
+        /** Show the synthetic cursor/click feedback while the agent operates. */
+        readonly virtualCursor: boolean;
+    };
+    /** Visual vs non-visual operation strategy. */
+    readonly vision: {
+        readonly strategy: VisionStrategy;
+    };
+    /** Whether the agent may read cookies / export login state. */
+    readonly credentials: {
+        readonly allowRead: boolean;
+    };
+}
+/** Defaults for every switch: the documented out-of-the-box behaviour. */
+export declare const DEFAULT_SETTINGS: BrowserSettings;
+/**
+ * Absolute path of the settings file, beside the browser profile and the
+ * browsing history.
+ * @returns the settings file path.
+ */
+export declare function settingsPath(): string;
+/**
+ * Resolve a raw settings document (already parsed, shape unknown) into the full
+ * document, field by field. Unknown keys are dropped: the file is not a place to
+ * smuggle configuration.
+ * @param raw - the parsed file contents.
+ * @returns the resolved settings.
+ */
+export declare function resolveSettings(raw: unknown): BrowserSettings;
+/**
+ * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
+ * edit from another process (or the settings panel writing through a second
+ * code path) is picked up without a restart; writes are atomic enough for a
+ * single-writer plugin and never throw at the caller.
+ */
+export declare class SettingsStore {
+    private readonly file;
+    private cached;
+    /** Last observed mtime, used to invalidate the cache on external edits. */
+    private cachedMtimeMs;
+    /**
+     * @param file - settings file path (defaults beside the browser profile).
+     */
+    constructor(file?: string);
+    /** Path this store reads and writes. */
+    path(): string;
+    /**
+     * Current settings, re-read when the file changed on disk.
+     * @returns the resolved settings document.
+     */
+    get(): BrowserSettings;
+    /**
+     * Merge a partial patch into the stored document and persist it.
+     * @param patch - the fields to change (unknown keys are ignored).
+     * @returns the settings after the merge.
+     */
+    update(patch: unknown): BrowserSettings;
+}

package/lib/browser-electron/settings-store.js

@@ -0,0 +1,160 @@
+/**
+ * Plugin-owned settings document — the switches the browser settings panel
+ * exposes, stored next to the browsing history so both follow the same rules:
+ * they survive the browser process and DSH restarts.
+ *
+ * Every field is optional on disk and falls back to a default, so a hand-edited
+ * or older file never breaks startup; an unreadable file is treated as "all
+ * defaults" rather than an error.
+ * @module dsh-browser/browser-electron/settings-store
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Defaults for every switch: the documented out-of-the-box behaviour. */
+export const DEFAULT_SETTINGS = {
+    history: { enabled: true, maxEntries: 5_000, maxAgeDays: 90 },
+    cookies: { persist: true },
+    ui: { autoExpandOnce: true, closeWithSession: false, virtualCursor: true },
+    vision: { strategy: 'auto' },
+    credentials: { allowRead: true },
+};
+/**
+ * Absolute path of the settings file, beside the browser profile and the
+ * browsing history.
+ * @returns the settings file path.
+ */
+export function settingsPath() {
+    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'dsh-builtin-browser-host', 'settings.json');
+}
+/** Coerce one boolean field, keeping the default when absent or mistyped. */
+function bool(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+/** Coerce one positive-integer field, keeping the default when invalid. */
+function count(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+/** Read one nested section of an unknown document, or an empty object. */
+function section(source, key) {
+    const value = source[key];
+    return typeof value === 'object' && value !== null ? value : {};
+}
+/**
+ * Resolve a raw settings document (already parsed, shape unknown) into the full
+ * document, field by field. Unknown keys are dropped: the file is not a place to
+ * smuggle configuration.
+ * @param raw - the parsed file contents.
+ * @returns the resolved settings.
+ */
+export function resolveSettings(raw) {
+    const source = typeof raw === 'object' && raw !== null ? raw : {};
+    const history = section(source, 'history');
+    const cookies = section(source, 'cookies');
+    const ui = section(source, 'ui');
+    const vision = section(source, 'vision');
+    const credentials = section(source, 'credentials');
+    return {
+        history: {
+            enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
+            maxEntries: count(history.maxEntries, DEFAULT_SETTINGS.history.maxEntries),
+            maxAgeDays: count(history.maxAgeDays, DEFAULT_SETTINGS.history.maxAgeDays),
+        },
+        cookies: { persist: bool(cookies.persist, DEFAULT_SETTINGS.cookies.persist) },
+        ui: {
+            autoExpandOnce: bool(ui.autoExpandOnce, DEFAULT_SETTINGS.ui.autoExpandOnce),
+            closeWithSession: bool(ui.closeWithSession, DEFAULT_SETTINGS.ui.closeWithSession),
+            virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
+        },
+        vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+        credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+    };
+}
+/**
+ * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
+ * edit from another process (or the settings panel writing through a second
+ * code path) is picked up without a restart; writes are atomic enough for a
+ * single-writer plugin and never throw at the caller.
+ */
+export class SettingsStore {
+    file;
+    cached;
+    /** Last observed mtime, used to invalidate the cache on external edits. */
+    cachedMtimeMs = -1;
+    /**
+     * @param file - settings file path (defaults beside the browser profile).
+     */
+    constructor(file = settingsPath()) {
+        this.file = file;
+    }
+    /** Path this store reads and writes. */
+    path() {
+        return this.file;
+    }
+    /**
+     * Current settings, re-read when the file changed on disk.
+     * @returns the resolved settings document.
+     */
+    get() {
+        let mtimeMs = -1;
+        let text;
+        try {
+            if (existsSync(this.file)) {
+                mtimeMs = statSync(this.file).mtimeMs;
+                text = readFileSync(this.file, 'utf8');
+            }
+        }
+        catch {
+            // Unreadable file: fall through to defaults below.
+            mtimeMs = -1;
+            text = undefined;
+        }
+        if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs)
+            return this.cached;
+        try {
+            this.cached = text === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(text));
+        }
+        catch {
+            // Malformed JSON: behave as defaults rather than fail startup.
+            this.cached = DEFAULT_SETTINGS;
+        }
+        this.cachedMtimeMs = mtimeMs;
+        return this.cached;
+    }
+    /**
+     * Merge a partial patch into the stored document and persist it.
+     * @param patch - the fields to change (unknown keys are ignored).
+     * @returns the settings after the merge.
+     */
+    update(patch) {
+        const current = this.get();
+        const merged = resolveSettings(deepMerge(current, patch));
+        try {
+            mkdirSync(dirname(this.file), { recursive: true });
+            writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`);
+        }
+        catch {
+            // Keep the merged value in memory even when the write fails.
+        }
+        this.cached = merged;
+        this.cachedMtimeMs = Date.now();
+        return merged;
+    }
+}
+/** One-level-deep merge over the settings sections (patch wins). */
+function deepMerge(base, patch) {
+    if (typeof patch !== 'object' || patch === null)
+        return base;
+    const result = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        const existing = result[key];
+        if (typeof value === 'object' && value !== null && typeof existing === 'object' && existing !== null) {
+            result[key] = { ...existing, ...value };
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/lib/browser-electron/virtual-cursor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Synthetic pointer feedback for a human watching the tab: an overlay drawn
+ * INSIDE the page, never the real system pointer. Its presence is the "the agent
+ * has taken over this tab" signal, so it also covers DOM-level operations that
+ * move no pointer at all.
+ *
+ * Implementation notes that matter:
+ * - The overlay is `position: fixed` and positioned from viewport coordinates,
+ *   which is exactly what the element locator already computes and what
+ *   `Input.dispatchMouseEvent` consumes.
+ * - All styling is inline and the ripple uses the Web Animations API: a
+ *   `<style>` element would be subject to the page's `style-src` CSP, an
+ *   injected script is not. Injected page feedback must never be silently
+ *   dropped by a strict CSP.
+ * - Every call is best-effort: feedback is never allowed to fail an operation.
+ * @module dsh-browser/browser-electron/virtual-cursor
+ */
+/** What the pointer is doing at the reported point. */
+export type CursorAction = 'move' | 'click';
+/**
+ * The in-page expression that materializes or moves the overlay. Idempotent: the
+ * first call creates the nodes, later calls only move them (and pulse).
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - whether to pulse a click ripple at the point.
+ * @returns a self-contained expression that evaluates to `true`.
+ */
+export declare function cursorScript(x: number, y: number, action: CursorAction): string;
+/**
+ * Draw (or move) the pointer overlay on one view's page.
+ *
+ * Fire-and-forget: a page that is mid-navigation, cross-origin-blocked, or
+ * otherwise unable to answer must not turn a successful operation into a
+ * failure, and the navigation that just committed may still be replacing the
+ * document this call would have painted into.
+ * @param handle - the view to paint into.
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - whether to pulse a click ripple.
+ * @param evaluate - the provider's evaluate bridge (keeps the CDP coupling in one place).
+ */
+export declare function paintCursor<TView>(handle: TView, x: number, y: number, action: CursorAction, evaluate: (handle: TView, expression: string) => Promise<unknown>): void;