dsh-builtin-browser 0.2.0 → 0.3.1

package/lib/browser-electron/provider.js

@@ -11,7 +11,7 @@ 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 { forgetCursor, paintCursor } from './virtual-cursor.js';
 import { BrowserError } from '../browser/types.js';
 /**
  * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
@@ -393,6 +393,11 @@ export class ElectronBrowserProvider {
     async settleDocument(handle, before, signal) {
         const started = Date.now();
         const deadline = started + SETTLE_TIMEOUT_MS;
+        // The document is being replaced, so the synthetic pointer drawn into the old one
+        // is gone. Dropping the remembered position is what lets it be painted again:
+        // without this, a paint at coincidentally identical coordinates would be skipped
+        // and the pointer would never come back after a navigation.
+        forgetCursor(handle);
         for (;;) {
             if (signal?.aborted === true)
                 return;
@@ -870,21 +875,39 @@ export class ElectronBrowserProvider {
       // iframes stay opaque — the browser forbids reading them).
       let content = ''
       if (fmt === 'txt') {
-        const parts = []
-        const textWalk = (node) => {
-          if (node.nodeType === Node.TEXT_NODE) { const t = (node.textContent || '').trim(); if (t) parts.push(t); return }
-          if (node.nodeType !== Node.ELEMENT_NODE) return
-          const tag = node.tagName.toLowerCase()
-          if (tag === 'script' || tag === 'style' || tag === 'noscript') return
-          if (tag === 'iframe') {
-            try { const d = node.contentDocument; if (d && d.body) for (const c of d.body.childNodes) textWalk(c) } catch { /* cross-origin */ }
-            return
+        // Prefer the browser's own rendered text.
+        //
+        // Walking text nodes and joining them is not equivalent: pages that wrap
+        // every character in its own element — one-character spans for a
+        // per-character animation, which is common — produce one text node per
+        // letter, and joining those with spaces turns every word into a column of
+        // letters. The rendered text reassembles them the way a reader sees them,
+        // and it also honours visibility, so hidden text does not leak out.
+        // (No backticks in this comment: it lives inside a template literal.)
+        const rendered = typeof root.innerText === 'string' ? root.innerText : ''
+        if (rendered.trim() !== '') {
+          content = rendered
+        } else {
+          // Fallback for nodes without layout (a detached root, or a fragment):
+          // collect text directly, still piercing shadow roots and same-origin
+          // iframes, and join without inventing separators beyond what the markup
+          // already implies.
+          const parts = []
+          const textWalk = (node) => {
+            if (node.nodeType === Node.TEXT_NODE) { const t = (node.textContent || '').trim(); if (t) parts.push(t); return }
+            if (node.nodeType !== Node.ELEMENT_NODE) return
+            const tag = node.tagName.toLowerCase()
+            if (tag === 'script' || tag === 'style' || tag === 'noscript') return
+            if (tag === 'iframe') {
+              try { const d = node.contentDocument; if (d && d.body) for (const c of d.body.childNodes) textWalk(c) } catch { /* cross-origin */ }
+              return
+            }
+            if (node.shadowRoot) for (const c of node.shadowRoot.childNodes) textWalk(c)
+            for (const child of node.childNodes) textWalk(child)
           }
-          if (node.shadowRoot) for (const c of node.shadowRoot.childNodes) textWalk(c)
-          for (const child of node.childNodes) textWalk(child)
+          textWalk(root)
+          content = parts.join(' ')
         }
-        textWalk(root)
-        content = parts.join(' ')
       }
       else if (fmt === 'html') content = root.outerHTML || ''
       else if (fmt === 'json') content = JSON.stringify(root)
@@ -952,6 +975,15 @@ export class ElectronBrowserProvider {
             y = Number(out.y);
         }
         else {
+            // A coordinate only exists because somebody read a picture. Under the
+            // non-visual strategy the plugin must not accept one: a model that cannot
+            // see cannot have produced it, so the coordinates are either copied from an
+            // earlier vision pass or invented, and honouring them turns a silent
+            // mis-click into a mystery. Refusing here, with a message that says what to
+            // do instead, converts that into a usable instruction.
+            if (this.settingsSource !== undefined && this.settingsSource().vision.strategy === 'nonVisual') {
+                throw new BrowserError('browser: the configured non-visual strategy refuses coordinate clicks — pass a semantic target instead, e.g. target { by: "text", value: "Sign in" }, which locates the element from the DOM and clicks its centre', 'BROWSER_NON_VISUAL_COORDINATES');
+            }
             x = request.x;
             y = request.y;
         }
@@ -975,7 +1007,9 @@ export class ElectronBrowserProvider {
         }
         // 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');
+        // Name the operation in the overlay: the pointer is the "agent is driving this
+        // tab" signal, so the bubble is what lets a human follow along without the log.
+        this.showCursor(handle, x, y, 'click', 'click', true);
         const release = () => {
             void handle
                 .sendCommand('Input.dispatchMouseEvent', {
@@ -1026,7 +1060,7 @@ export class ElectronBrowserProvider {
             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');
+                this.showCursor(locateTab.handle, cursorPoint.x, cursorPoint.y, 'click', 'type', true);
         }
         const text = 'text' in request ? request.text : '';
         const timeoutMs = 30_000;
@@ -1879,11 +1913,14 @@ export class ElectronBrowserProvider {
      * @param x - viewport x in CSS pixels.
      * @param y - viewport y in CSS pixels.
      * @param action - click pulses a ripple; move only relocates.
+     * @param label - short description of the operation, shown beside the pointer.
+     * @param force - paint even when the pointer is already there (a click ripple must
+     *   always play; a bare move need not repeat).
      */
-    showCursor(handle, x, y, action) {
+    showCursor(handle, x, y, action, label, force = false) {
         if (this.settingsSource !== undefined && !this.settingsSource().ui.virtualCursor)
             return;
-        paintCursor(handle, x, y, action, (target, expression) => handleSendEvaluate(target, expression));
+        paintCursor(handle, x, y, action, (target, expression) => handleSendEvaluate(target, expression), label, force);
     }
     /**
      * Replay one recorded operation by sequence number. Navigate/click/type are
@@ -1967,6 +2004,13 @@ export class ElectronBrowserProvider {
             this.sessions.delete(session);
             for (const tab of existing.tabs)
                 this.host.destroyView(tab.handle);
+            // Releasing the browser at session end is a setting, not fixed behaviour
+            // (requirements §3). A self-hosted carrier already tore its window down with
+            // the views above; the desktop's sidebar does not, so it is asked explicitly
+            // — and its cookies plus the browsing history outlive the page either way.
+            if (this.settingsSource !== undefined && this.settingsSource().ui.closeWithSession) {
+                void this.host.releasePage?.().catch(() => undefined);
+            }
         }
         return Promise.resolve();
     }
@@ -2076,19 +2120,47 @@ export class ElectronBrowserProvider {
             this.notifyUserActionError(action, error);
         }
     }
-    /** Report a failed user action to the host UI (toolbar), when supported. */
+    /**
+     * Report a failed user action to the host UI (toolbar), when supported.
+     *
+     * Two properties matter here, because this runs inside the catch of an async
+     * handler (issue #16):
+     *  - the receiver must be preserved. Reading the method off the host and calling
+     *    it unbound runs the host's implementation with `this === undefined`, so its
+     *    very first statement (`void this.ready()`) throws, the throw escapes the
+     *    async catch as an unhandled rejection, and the whole DSH host exits;
+     *  - this method must be incapable of throwing. Reporting a failed action is
+     *    diagnostics: it can never be allowed to become the failure.
+     */
     notifyUserActionError(action, error) {
-        const notify = this.host.notifyUserActionError;
         const message = `action ${action.type} failed: ${String(error)}`;
-        if (typeof notify === 'function') {
-            notify(action.windowId, message);
+        let reported = false;
+        try {
+            const host = this.host;
+            const notify = host.notifyUserActionError;
+            if (typeof notify === 'function') {
+                // Called on its owner: an unbound call here kills the host process.
+                notify.call(host, action.windowId, message);
+                reported = true;
+            }
         }
-        else {
-            process.stderr.write(`[dsh-browser] user action failed: ${message}\n`);
+        catch (notifyError) {
+            // Contained on purpose; the log line below still carries the original cause.
+            process.stderr.write(`[dsh-browser] host notify failed: ${String(notifyError)}\n`);
         }
+        if (!reported)
+            process.stderr.write(`[dsh-browser] user action failed: ${message}\n`);
     }
     /** Ask the host to show the active tab's view, carrying the session label. */
     showActive(s) {
+        // §3: whether the agent's page takes over the screen is the user's choice, not
+        // a fixed behaviour. With auto-expand off the page still exists and is still
+        // driven — it is simply folded away, so the agent works without claiming the
+        // sidebar. Carriers that own no presentation (self-hosted) ignore the call.
+        if (this.settingsSource !== undefined && !this.settingsSource().ui.autoExpandOnce) {
+            void this.host.collapse?.().catch(() => undefined);
+            return;
+        }
         this.host.showView?.(this.activeTab(s).handle, s.label);
     }
     /** Read the current URL of a view through CDP. */

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

@@ -145,7 +145,15 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
      * 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). */
+    /**
+     * Ensure the child is up and ready (lazy on first use; restarts after a crash).
+     *
+     * Never throws synchronously. Callers are fire-and-forget
+     * (`void this.ready().then(…).catch(…)`), and a synchronous throw escapes their
+     * `.catch` entirely — the shape that let a failed toolbar report take the whole
+     * DSH host down (issue #16). A disposed host is reported as a rejected promise
+     * instead, which those callers already handle.
+     */
     private ready;
     private start;
     /** The child died: tear down so the next use starts a fresh child. */

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

@@ -765,13 +765,27 @@ export class RemoteElectronViewHost {
         }
         return this.electronAvailable;
     }
-    /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
+    /**
+     * Ensure the child is up and ready (lazy on first use; restarts after a crash).
+     *
+     * Never throws synchronously. Callers are fire-and-forget
+     * (`void this.ready().then(…).catch(…)`), and a synchronous throw escapes their
+     * `.catch` entirely — the shape that let a failed toolbar report take the whole
+     * DSH host down (issue #16). A disposed host is reported as a rejected promise
+     * instead, which those callers already handle.
+     */
     ready() {
         // Fail fast on a disposed host: a recovery path can re-enter ready() after
         // dispose() cleared its state, and starting fresh here would spawn a child
         // nobody will ever kill.
-        if (this.disposed)
-            throw new HostGoneError('browser host disposed');
+        if (this.disposed) {
+            const gone = Promise.reject(new HostGoneError('browser host disposed'));
+            // Keep the rejection observable to callers while marking it handled here:
+            // a fire-and-forget caller that forgot to attach a handler must not turn
+            // this into an unhandled rejection either.
+            gone.catch(() => undefined);
+            return gone;
+        }
         if (this.readyPromise !== undefined)
             return this.readyPromise;
         const started = this.start();

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

@@ -8,6 +8,7 @@
  * defaults" rather than an error.
  * @module dsh-browser/browser-electron/settings-store
  */
+import type { BrowserChannel } from './system-browser.js';
 /** Vision/operation strategy the provider prefers when the model can see. */
 export type VisionStrategy = 'auto' | 'nonVisual';
 /** The full settings document, with every field resolved. */
@@ -35,6 +36,10 @@ export interface BrowserSettings {
     readonly vision: {
         readonly strategy: VisionStrategy;
     };
+    /** Which browser binary carries the agent's pages. */
+    readonly browser: {
+        readonly channel: BrowserChannel;
+    };
     /** Whether the agent may read cookies / export login state. */
     readonly credentials: {
         readonly allowRead: boolean;

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

@@ -17,6 +17,10 @@ export const DEFAULT_SETTINGS = {
     cookies: { persist: true },
     ui: { autoExpandOnce: true, closeWithSession: false, virtualCursor: true },
     vision: { strategy: 'auto' },
+    // Bundled by default: it needs nothing installed, and on the desktop the carrier
+    // is the sidebar anyway. Choosing a system browser is an explicit opt-in because
+    // it starts a real Chrome/Edge with its own profile.
+    browser: { channel: 'bundled' },
     credentials: { allowRead: true },
 };
 /**
@@ -32,6 +36,17 @@ export function settingsPath() {
 function bool(value, fallback) {
     return typeof value === 'boolean' ? value : fallback;
 }
+/**
+ * Coerce the browser channel, keeping the default when it is not one of the
+ * known choices. A hand-edited typo must not silently select a different browser.
+ * @param value - the raw value from the settings document.
+ * @returns a valid channel.
+ */
+function resolveChannel(value) {
+    return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled'
+        ? value
+        : DEFAULT_SETTINGS.browser.channel;
+}
 /** 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;
@@ -55,6 +70,7 @@ export function resolveSettings(raw) {
     const ui = section(source, 'ui');
     const vision = section(source, 'vision');
     const credentials = section(source, 'credentials');
+    const browser = section(source, 'browser');
     return {
         history: {
             enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
@@ -68,6 +84,7 @@ export function resolveSettings(raw) {
             virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
         },
         vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+        browser: { channel: resolveChannel(browser.channel) },
         credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
     };
 }
@@ -113,7 +130,13 @@ export class SettingsStore {
         if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs)
             return this.cached;
         try {
-            this.cached = text === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(text));
+            // A leading BOM is what ordinary Windows editors (Notepad, PowerShell's
+            // `Set-Content -Encoding utf8`) leave behind, and `JSON.parse` rejects it.
+            // Without this strip, hand-editing the settings file silently discarded every
+            // value in it: the document looked correct, and the plugin quietly ran on
+            // defaults — including switches the user had just turned off.
+            const body = text?.replace(/^\uFEFF/, '');
+            this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body));
         }
         catch {
             // Malformed JSON: behave as defaults rather than fail startup.

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

@@ -0,0 +1,132 @@
+/**
+ * Drive the browser the user already has (Chrome / Edge / any Chromium) instead of
+ * the Electron we ship — the same approach Codex Browser Use takes.
+ *
+ * WHY
+ * The bundled Electron is a private copy with its own profile, so it can never see
+ * the logins the user already has in Chrome, and on a managed machine the user may
+ * simply prefer their own browser. Launching their browser with a *separate*
+ * `--user-data-dir` gives us a real Chromium we can drive over CDP without touching
+ * their everyday profile, bookmarks or windows: nothing of theirs is opened, locked
+ * or modified, and closing us never closes them.
+ *
+ * HOW
+ * Chromium exposes CDP on `--remote-debugging-port=0`, and writes the port it chose
+ * into `<profile>/DevToolsActivePort`. That file is the discovery mechanism — no
+ * port guessing, no collisions. From there everything is CDP over one WebSocket:
+ * `Target.createTarget` makes a page, `Target.attachToTarget` (flattened) gives a
+ * session for it, and the plugin's commands ride that session. Node 22 ships a global
+ * `WebSocket`, so this needs no dependency at all.
+ *
+ * WHAT IT IMPLEMENTS
+ * The same `ElectronBrowserViewHost` seam as the self-hosted and sidebar hosts, so
+ * the provider, the tools, history, the cursor and teardown rules are unchanged —
+ * only the carrier differs.
+ * @module dsh-browser/browser-electron/system-browser
+ */
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
+/** Which browser the user asked for. */
+export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto';
+/** A resolved browser installation. */
+export interface DetectedBrowser {
+    /** Which product this is. */
+    readonly kind: 'chrome' | 'edge' | 'brave';
+    /** Absolute path to the executable. */
+    readonly path: string;
+}
+/**
+ * Find an installed Chromium browser.
+ *
+ * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
+ * is to be the browser a user actually chose rather than one Windows shipped.
+ * @param channel - the configured choice; `bundled` never resolves to a system browser.
+ * @param env - environment lookup, injected so tests need no real machine.
+ * @returns the detected browser, or undefined when the choice is unavailable.
+ */
+export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.ProcessEnv): DetectedBrowser | undefined;
+/** A system browser driven over CDP, presented as a browser view host. */
+export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
+    private readonly browser;
+    private readonly profileDir;
+    private readonly extraArgs;
+    private readonly ephemeralDir?;
+    private readonly views;
+    private disposed;
+    /**
+     * The browser is started on FIRST USE, never on construction.
+     *
+     * A plugin that launches Chrome the moment its host loads is a plugin that takes
+     * over the machine before anyone asked it to: simply starting DSH would spawn a
+     * browser window. Registration must therefore be inert, and the process is only
+     * spawned when a view is actually needed.
+     */
+    private client;
+    private child;
+    private starting;
+    /**
+     * @param browser - the detected installation to launch on first use.
+     * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
+     * @param extraArgs - additional Chromium switches.
+     * @param ephemeralDir - a directory to delete on release, when the user has turned
+     *   persistence off so no login state outlives the session.
+     */
+    constructor(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string | undefined);
+    /** Which product this host would drive (for diagnostics). */
+    get kind(): DetectedBrowser['kind'];
+    /** Whether the browser has actually been started yet (diagnostics and tests). */
+    get started(): boolean;
+    /**
+     * The CDP client, starting the browser on first use.
+     * @returns the connected client.
+     */
+    private ensureClient;
+    /**
+     * Launch the browser with a private profile and connect over CDP.
+     *
+     * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+     * reliable way to learn the port: a fixed port collides with whatever else the
+     * machine is running, and parsing stderr is fragile across versions.
+     * @returns the connected client.
+     */
+    private start;
+    /**
+     * Whether this host can back views.
+     *
+     * True while the host is usable — including before the browser has been started,
+     * since the first command is what starts it. Reporting "unavailable" here would
+     * make the plugin fall back for no reason.
+     */
+    available(): boolean;
+    createView(): ElectronViewHandle;
+    destroyView(handle: ElectronViewHandle): void;
+    /** Nothing to show: the browser owns its own windows. */
+    showView(): void;
+    /** Same as {@link showView}. */
+    presentView(): Promise<void>;
+    /** The browser owns window grouping. */
+    groupView(): void;
+    /**
+     * Bring the browser's window forward.
+     *
+     * The browser is a separate application, so there is no view to raise; focusing
+     * the process is the closest honest equivalent, and failing to do so (a minimized
+     * window, a locked session) is never worth an error.
+     */
+    focus(): Promise<void>;
+    /** The browser reports its own window lifecycle. */
+    onUserAction(): void;
+    /** The browser reports its own window lifecycle. */
+    onViewClosed(): void;
+    /**
+     * Close the browser we launched, if we ever launched one.
+     *
+     * The user's own windows belong to a different process and are never touched. A
+     * host whose browser was never started (the common case when nobody used the
+     * browser) simply tears down its bookkeeping.
+     */
+    dispose(): void;
+    /** The flattened session for a view, creating its page on first use. */
+    private ensureSession;
+    /** sessionId -> targetId, so a destroyed view can close the right page. */
+    private readonly sessions;
+}