dsh-builtin-browser 0.2.0 → 0.3.0

package/src/browser-electron/provider.ts

@@ -13,7 +13,7 @@ import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
 import { HistoryStore, type VisitedPage } from './history-store.js'
 import type { BrowserSettings } from './settings-store.js'
-import { paintCursor, type CursorAction } from './virtual-cursor.js'
+import { forgetCursor, paintCursor, type CursorAction } from './virtual-cursor.js'
 import type {
   BrowserA11yRequest,
   BrowserA11yResult,
@@ -185,6 +185,31 @@ export interface ElectronBrowserViewHost {
    * @param handler - called with the group (session) key; must not throw.
    */
   onViewClosed?(handler: (windowId: string) => void): void
+  /**
+   * Release the service's page(s) without ending the plugin's own lifetime.
+   *
+   * Only carriers that outlive a browser session need this. A self-hosted window
+   * dies with its view, but the desktop shell's sidebar keeps running no matter
+   * what the plugin does — so "release the browser when the session ends"
+   * (settings: ui.closeWithSession) has to be asked for explicitly there.
+   * @returns a promise that settles once the release was attempted.
+   */
+  releasePage?(): Promise<void>
+  /**
+   * Fold the carrier's presentation away while keeping the page alive.
+   *
+   * The desktop sidebar keeps running regardless of the plugin, so "do not take
+   * over the screen" (settings: ui.autoExpandOnce = false) can only be honoured by
+   * asking the shell to fold it. A self-hosted window has no such state and simply
+   * does not implement this.
+   * @returns a promise that settles once the fold was attempted.
+   */
+  collapse?(): Promise<void>
+  /**
+   * Release everything the carrier owns (a spawned browser, a socket, a child).
+   * Called when the plugin stops using it, never while it is still in service.
+   */
+  dispose?(): void
 }
 
 /**
@@ -670,6 +695,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
   private async settleDocument(handle: ElectronViewHandle, before: string, signal?: AbortSignal): Promise<void> {
     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
       // A probe failure is expected while the navigation commits (the context is
@@ -1180,21 +1210,39 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // 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)
@@ -1270,6 +1318,18 @@ export class ElectronBrowserProvider implements BrowserProvider {
       x = Number(out.x)
       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
     }
@@ -1298,7 +1358,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     // 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 => {
       void handle
         .sendCommand('Input.dispatchMouseEvent', {
@@ -1351,7 +1413,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       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')
+      if (cursorPoint !== undefined) this.showCursor(locateTab.handle, cursorPoint.x, cursorPoint.y, 'click', 'type', true)
     }
     const text = 'text' in request ? request.text : ''
     const timeoutMs = 30_000
@@ -2274,7 +2336,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * @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[] {
+  visited(options: { readonly limit?: number; readonly domain?: string; readonly query?: string; readonly session?: string } = {}): readonly VisitedPage[] {
     return this.historyStore?.list(options) ?? []
   }
 
@@ -2287,10 +2349,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * @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).
    */
-  private showCursor(handle: ElectronViewHandle, x: number, y: number, action: CursorAction): void {
+  private showCursor(handle: ElectronViewHandle, x: number, y: number, action: CursorAction, label?: string, force = false): void {
     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)
   }
 
   /**
@@ -2370,6 +2435,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (existing !== undefined) {
       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()
   }
@@ -2481,19 +2553,46 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
-  /** 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.
+   */
   private notifyUserActionError(action: BrowserUserAction, error: unknown): void {
-    const notify = (this.host as { notifyUserActionError?(windowId: string, message: string): void }).notifyUserActionError
     const message = `action ${action.type} failed: ${String(error)}`
-    if (typeof notify === 'function') {
-      notify(action.windowId, message)
-    } else {
-      process.stderr.write(`[dsh-browser] user action failed: ${message}\n`)
+    let reported = false
+    try {
+      const host = this.host as { notifyUserActionError?(windowId: string, message: string): void }
+      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
+      }
+    } 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. */
   private showActive(s: Session): void {
+    // §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)
   }
 

package/src/browser-electron/remote-host.ts

@@ -799,12 +799,27 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     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.
+   */
   private ready(): Promise<void> {
     // 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()
     const wrapped = started.catch(error => {

package/src/browser-electron/settings-store.ts

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
+import type { BrowserChannel } from './system-browser.js'
 
 /** Vision/operation strategy the provider prefers when the model can see. */
 export type VisionStrategy = 'auto' | 'nonVisual'
@@ -41,6 +42,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
@@ -53,6 +58,10 @@ export const DEFAULT_SETTINGS: BrowserSettings = {
   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 },
 }
 
@@ -71,6 +80,18 @@ function bool(value: unknown, fallback: boolean): boolean {
   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: unknown): BrowserChannel {
+  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: unknown, fallback: number): number {
   return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
@@ -96,6 +117,7 @@ export function resolveSettings(raw: unknown): BrowserSettings {
   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),
@@ -109,6 +131,7 @@ export function resolveSettings(raw: unknown): BrowserSettings {
       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) },
   }
 }
@@ -153,7 +176,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.
       this.cached = DEFAULT_SETTINGS

package/src/browser-electron/system-browser.ts

@@ -0,0 +1,318 @@
+/**
+ * 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 { readFileSync, rmSync } from 'node:fs'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+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
+}
+
+/**
+ * Where each Chromium product installs on Windows, plus the registry paths that
+ * survive a non-default install location. Only paths that exist are returned, so a
+ * caller can tell "not installed" from "installed elsewhere".
+ */
+const WINDOWS_LOCATIONS: Record<DetectedBrowser['kind'], string[]> = {
+  chrome: [
+    String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`,
+    String.raw`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+  ],
+  edge: [
+    String.raw`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
+    String.raw`C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+  ],
+  brave: [
+    String.raw`C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
+    String.raw`C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+  ],
+}
+
+/**
+ * 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 function detectBrowser(channel: BrowserChannel, env: NodeJS.ProcessEnv = process.env): DetectedBrowser | undefined {
+  if (channel === 'bundled') return undefined
+  const order: DetectedBrowser['kind'][] = channel === 'auto' ? ['chrome', 'edge', 'brave'] : [channel as DetectedBrowser['kind']]
+  for (const kind of order) {
+    const fromEnv = (kind === 'chrome' ? env.DSH_BROWSER_CHROME_PATH : kind === 'edge' ? env.DSH_BROWSER_EDGE_PATH : undefined)
+    if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv)) return { kind, path: fromEnv }
+    for (const candidate of WINDOWS_LOCATIONS[kind] ?? []) {
+      if (existsSync(candidate)) return { kind, path: candidate }
+    }
+  }
+  return undefined
+}
+
+/** One CDP connection to a browser-level WebSocket, with flattened sessions. */
+class CdpClient {
+  private nextId = 1
+  private readonly pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void }>()
+  private readonly ready: Promise<void>
+
+  /**
+   * @param url - the browser's `webSocketDebuggerUrl`.
+   */
+  constructor(private readonly url: string) {
+    // Node 22 provides WebSocket globally; no dependency is added for this.
+    const socket = new WebSocket(url)
+    this.socket = socket
+    this.ready = new Promise<void>((resolve, reject) => {
+      socket.addEventListener('open', () => resolve())
+      socket.addEventListener('error', () => reject(new Error('dsh-builtin-browser: could not reach the browser over CDP')))
+    })
+    socket.addEventListener('message', event => this.onMessage(String((event as MessageEvent).data)))
+    socket.addEventListener('close', () => this.fail(new Error('dsh-builtin-browser: the browser closed the CDP connection')))
+  }
+
+  private readonly socket: WebSocket
+
+  /** Resolve once the socket is open. */
+  async whenReady(): Promise<void> {
+    await this.ready
+  }
+
+  /**
+   * Send one CDP command, optionally on an attached session.
+   * @param method - the CDP method.
+   * @param params - its parameters.
+   * @param sessionId - the flattened session to target, when this is a page command.
+   * @returns the CDP result.
+   */
+  async send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<unknown> {
+    await this.ready
+    const id = this.nextId++
+    const message = { id, method, ...params !== undefined ? { params } : {}, ...sessionId !== undefined ? { sessionId } : {} }
+    return await new Promise<unknown>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      this.socket.send(JSON.stringify(message))
+      setTimeout(() => {
+        if (this.pending.delete(id)) reject(new Error(`dsh-builtin-browser: ${method} timed out`))
+      }, 30_000).unref?.()
+    })
+  }
+
+  /** Close the socket. */
+  close(): void {
+    try { this.socket.close() } catch { /* already closed */ }
+  }
+
+  /** Route one CDP message to its waiter. */
+  private onMessage(raw: string): void {
+    let message: { id?: number; result?: unknown; error?: { message?: string } }
+    try { message = JSON.parse(raw) } catch { return }
+    if (message.id === undefined) return
+    const entry = this.pending.get(message.id)
+    if (entry === undefined) return
+    this.pending.delete(message.id)
+    if (message.error !== undefined) entry.reject(new Error(`dsh-builtin-browser: CDP error: ${message.error.message ?? 'unknown'}`))
+    else entry.resolve(message.result)
+  }
+
+  /** Fail everything in flight. */
+  private fail(error: Error): void {
+    const pending = [...this.pending.values()]
+    this.pending.clear()
+    for (const entry of pending) entry.reject(error)
+  }
+}
+
+/** A system browser driven over CDP, presented as a browser view host. */
+export class SystemBrowserViewHost implements ElectronBrowserViewHost {
+  private readonly views = new Map<string, string>()
+  private disposed = false
+
+  /**
+   * @param child - the launched browser process.
+   * @param client - the CDP connection to it.
+   * @param kind - which product this is (for diagnostics).
+   * @param ephemeralDir - a throwaway profile to remove on release, when the user
+   *   has turned persistence off and no login state should outlive the session.
+   */
+  private constructor(
+    private readonly child: ChildProcess,
+    private readonly client: CdpClient,
+    readonly kind: DetectedBrowser['kind'],
+    private readonly ephemeralDir?: string,
+  ) {}
+
+  /**
+   * @param browser - the detected installation to launch.
+   * @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 when the browser is released, used
+   *   when persistence is switched off so no login state outlives the session.
+   * @returns the host, or undefined when the browser refuses to come up.
+   */
+  static async launch(browser: DetectedBrowser, profileDir: string, extraArgs: readonly string[] = [], ephemeralDir?: string): Promise<SystemBrowserViewHost | undefined> {
+    const args = [
+      '--remote-debugging-port=0',
+      `--user-data-dir=${profileDir}`,
+      // Behave like a fresh, unattended browser: no first-run UI, no default-browser
+      // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--disable-features=Translate,MediaRouter',
+      '--disable-session-crashed-bubble',
+      '--hide-crash-restore-bubble',
+      ...extraArgs,
+      'about:blank',
+    ]
+    const child = spawn(browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
+    const portFile = join(profileDir, 'DevToolsActivePort')
+    const deadline = Date.now() + 30_000
+    for (;;) {
+      if (Date.now() > deadline) { child.kill(); return undefined }
+      if (child.exitCode !== null) return undefined
+      if (existsSync(portFile)) {
+        try {
+          const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? ''
+          if (port !== '') {
+            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json() as { webSocketDebuggerUrl?: string }
+            if (typeof version.webSocketDebuggerUrl === 'string') {
+              const client = new CdpClient(version.webSocketDebuggerUrl)
+              await client.whenReady()
+              return new SystemBrowserViewHost(child, client, browser.kind, ephemeralDir)
+            }
+          }
+        } catch {
+          // The file can exist a moment before the port answers; poll again.
+        }
+      }
+      await new Promise(resolve => setTimeout(resolve, 250))
+    }
+  }
+
+  /** Whether this host can back views: the CDP connection is live. */
+  available(): boolean {
+    return !this.disposed
+  }
+
+  createView(): ElectronViewHandle {
+    const viewId = randomUUID()
+    return {
+      id: viewId,
+      sendCommand: async (method: string, params?: Record<string, unknown>) => {
+        const session = this.views.get(viewId) ?? await this.ensureSession(viewId)
+        const result = await this.client.send(method, params, session)
+        return (result ?? {}) as Record<string, unknown>
+      },
+    }
+  }
+
+  destroyView(handle: ElectronViewHandle): void {
+    const session = this.views.get(handle.id)
+    this.views.delete(handle.id)
+    if (session === undefined) return
+    // A session id is not a target id: closing the page needs the target the session
+    // was attached to, which is why they are tracked separately.
+    const targetId = this.sessions.get(session)
+    this.sessions.delete(session)
+    if (targetId !== undefined) {
+      // Best-effort: a page that is already gone is not an error.
+      void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined)
+    }
+  }
+
+  /** Nothing to show: the browser owns its own windows. */
+  showView(): void {}
+
+  /** Same as {@link showView}. */
+  async 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.
+   */
+  async focus(): Promise<void> {
+    try { this.child.kill('SIGCONT') } catch { /* not supported on Windows; harmless */ }
+  }
+
+  /** The browser reports its own window lifecycle. */
+  onUserAction(): void {}
+
+  /** The browser reports its own window lifecycle. */
+  onViewClosed(): void {}
+
+  /** Close the browser we launched. The user's own windows are a different process. */
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.views.clear()
+    this.sessions.clear()
+    this.client.close()
+    try { this.child.kill() } catch { /* already gone */ }
+    const ephemeral = this.ephemeralDir
+    if (ephemeral !== undefined) {
+      // The browser flushes its profile while shutting down, so deleting later avoids
+      // racing it. Leftovers are only a stray temp directory, never a live credential.
+      setTimeout(() => { try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ } }, 3_000).unref?.()
+    }
+  }
+
+  /** The flattened session for a view, creating its page on first use. */
+  private async ensureSession(viewId: string): Promise<string> {
+    const existing = this.views.get(viewId)
+    if (existing !== undefined) return existing
+    const created = await this.client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
+    const targetId = created?.targetId
+    if (typeof targetId !== 'string') throw new Error('dsh-builtin-browser: the browser did not create a page')
+    const attached = await this.client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
+    const sessionId = attached?.sessionId
+    if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
+    // The session id is what page commands ride; the target id is what closes it.
+    this.sessions.set(sessionId, targetId)
+    this.views.set(viewId, sessionId)
+    return sessionId
+  }
+
+  /** sessionId -> targetId, so a destroyed view can close the right page. */
+  private readonly sessions = new Map<string, string>()
+}