dsh-builtin-browser 0.4.9 → 0.4.11

package/src/browser-electron/provider.ts

@@ -51,6 +51,7 @@ import type {
   ExportedCookie,
 } from '../browser/types.js'
 import { BrowserError } from '../browser/types.js'
+import type { CarrierPage } from '../browser/types.js'
 
 /**
  * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
@@ -156,6 +157,35 @@ export interface ElectronBrowserViewHost {
    * @param label - human-readable session/task label, as in {@link showView}.
    */
   presentView?(handle: ElectronViewHandle, label?: string): Promise<void>
+  /**
+   * Optional: pages this carrier holds that the provider never created.
+   *
+   * A sidebar panel and an installed browser both own their own page creation. Clicking a link
+   * that opens a new page — or any `window.open` the page performs — produces a page the provider
+   * did not ask for and therefore never recorded. Those pages are real: they are what the human
+   * sees, they hold memory, and they persist until something closes them. Without this the tab
+   * model reports only what the provider itself made, so the extras are invisible to
+   * `dsh_browser_list_tabs` and unclosable through `dsh_browser_close_tab`, accumulating for the
+   * life of the browser.
+   *
+   * Views the host itself opened are NOT included. That exclusion belongs to the host, which is the
+   * only side that can make it: a provider tab is identified by the provider's own id and a carrier
+   * page by the carrier's, so a caller comparing the two matches nothing and reports every page
+   * twice. Measured on the sidebar carrier: three clicks produced three webview guests while
+   * `dsh_browser_list_tabs` reported one tab; on the installed-browser carrier the window held four
+   * pages and the tool reported one.
+   * @returns every page the carrier holds that this host did not open.
+   */
+  listPages?(): Promise<readonly CarrierPage[]>
+  /**
+   * Optional: close one page reported by {@link listPages}.
+   *
+   * The pair exists because listing a page the caller cannot close is worse than not listing it:
+   * `dsh_browser_list_tabs` would report pages that `dsh_browser_close_tab` answers "not open in
+   * this session" about, which reads as a contradiction rather than a boundary.
+   * @param id - the carrier's own page id, as {@link listPages} reported it.
+   */
+  closePage?(id: string): Promise<void>
   /**
    * Optional cheap usability probe (no network): whether the host can back
    * views at all right now. The self-hosted host checks for a usable Electron
@@ -413,6 +443,15 @@ export interface CdpNavigateParams {
  * 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.
+ *
+ * `buttons` is a BITMASK of what is held down at the moment of the event, and it is not the same
+ * field as `button` — `button` says which one this event is about, `buttons` says which ones are
+ * down. Chromium needs both to recognise a synthesized press as a real button press: with
+ * `buttons` omitted (0), the event still reaches the page and a `click` listener still fires, but
+ * the element's DEFAULT ACTION does not run. Measured on the sidebar carrier: a click on an
+ * anchor sent `mousedown`/`mouseup`/`click` to the page with `isTrusted: true` and
+ * `defaultPrevented: false`, and the browser did not follow the link — including for an anchor
+ * injected by the test itself, so the page was not responsible.
  */
 export interface CdpMouseParams {
   readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased'
@@ -420,6 +459,8 @@ export interface CdpMouseParams {
   readonly y: number
   readonly button?: 'left'
   readonly clickCount?: number
+  /** Buttons held during the event: 1 = primary down. A move carries 0. */
+  readonly buttons?: number
 }
 
 /** CDP method/params for `Input.insertText`. */
@@ -771,6 +812,27 @@ export class ElectronBrowserProvider implements BrowserProvider {
         active: i === s.activeIndex,
       })
     }
+    // Pages the CARRIER holds that this provider never created.
+    //
+    // A sidebar panel and an installed browser both open pages on their own: a click on a link
+    // that targets a new page, or any `window.open`, produces a page nothing tells us about.
+    // Reporting only our own tabs made those invisible to this tool and unclosable through
+    // `dsh_browser_close_tab`, so they accumulated for the life of the browser. Measured on the
+    // sidebar carrier: three clicks produced three webview guests while this listed one tab.
+    //
+    // `listPages` already excludes the pages it opened the view for — that filtering cannot happen
+    // here, because a tab is known by this provider's own id and a carrier page by the carrier's,
+    // and the two never match. A first version compared them anyway and listed every page twice.
+    //
+    // They are appended under a `page:` prefix so a caller can tell the two kinds apart — the
+    // prefix is also what `closeTab` uses to decide whether to close a view or a carrier page.
+    const pages = await this.host.listPages?.().catch(() => undefined) ?? []
+    for (const page of pages) {
+      // A page with no URL is a blank one the carrier opened for itself. Listing it would invite a
+      // caller to act on nothing, and the blank normalisation already closes those.
+      if (page.url === '' || page.url === 'about:blank') continue
+      result.push({ id: `page:${page.id}`, url: page.url, active: false })
+    }
     return result
   }
 
@@ -784,6 +846,19 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /** Close one tab; closing the active tab activates the next. */
   closeTab(session: BrowserSessionId, tabId: string): Promise<void> {
+    // A page the carrier owns rather than a view we created. It was reported by `listTabs` under
+    // this prefix, so closing it here is what keeps the two tools consistent — a page that can be
+    // listed must be closable, or the listing reads as a contradiction.
+    if (tabId.startsWith('page:')) {
+      const id = tabId.slice('page:'.length)
+      if (this.host.closePage === undefined) {
+        return Promise.reject(new BrowserError(
+          'browser: this carrier does not expose the pages it opens on its own, so that page cannot be closed',
+          'BROWSER_TAB_NOT_FOUND',
+        ))
+      }
+      return this.host.closePage(id)
+    }
     const found = this.locateTab(session, tabId)
     const s = found.s
     const index = found.index
@@ -1747,7 +1822,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // landed because the first had quietly established the target. Move the
     // pointer first so a click is self-contained.
     try {
-      await send({ type: 'mouseMoved', x, y } satisfies CdpMouseParams, 'move')
+      await send({ type: 'mouseMoved', x, y, buttons: 0 } satisfies CdpMouseParams, 'move')
     } catch (error) {
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
@@ -1767,12 +1842,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
           x,
           y,
           button: 'left',
+          buttons: 0,
           clickCount: 1,
         } satisfies CdpMouseParams)
         .catch(() => {})
     }
     try {
-      await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press')
+      await send({ type: 'mousePressed', x, y, button: 'left', buttons: 1, 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.
@@ -1780,7 +1856,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
     try {
-      await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release')
+      await send({ type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1 }, 'release')
     } catch (error) {
       // The press already landed; retry the release so the button is not
       // left pressed before surfacing the failure.

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

@@ -82,6 +82,7 @@ const defaultLauncher: BrowserLauncher = (path, args) =>
 import { spawn, type ChildProcess } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
+import type { CarrierPage } from '../browser/types.js'
 
 /** Which browser the user asked for. */
 export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto' | 'sidebar'
@@ -187,6 +188,19 @@ const INSTALL_LOCATIONS: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.P
  * @param env - the environment to resolve against.
  * @returns the path with %NAME% references replaced, or the entry unchanged when unknown.
  */
+/**
+ * Whether a browser's self-reported product name is one this carrier could have launched.
+ *
+ * `edg`, not `edge`: Edge reports itself as `Edg/155.0.4283.45`, both over HTTP and over the
+ * protocol. Testing for the full word rejected a live Edge that had just been started, so the
+ * call failed with the hand-off error this check was added to prevent — while the browser was
+ * running the whole time, answering on its own port.
+ * @param product - the product string a browser reports about itself.
+ */
+function isBrowserProduct(product: unknown): boolean {
+  return typeof product === 'string' && /chrome|chromium|edg/i.test(product)
+}
+
 /**
  * Whether a target URL is one of the blanks a browser opens by itself.
  *
@@ -619,13 +633,13 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       if (typeof version.webSocketDebuggerUrl !== 'string') return undefined
       // The port number alone proves nothing — it can be reused once the browser that owned it
       // exits. The endpoint's own answer is the evidence, and it has to name a browser.
-      if (typeof version.Browser !== 'string' || !/chrome|chromium|edge/i.test(version.Browser)) return undefined
+      if (!isBrowserProduct(version.Browser)) return undefined
       const client = new CdpClient(version.webSocketDebuggerUrl)
       await client.whenReady()
       // Asked through the protocol too, so a websocket that merely accepts connections is not
       // mistaken for a browser that answers.
       const info = await client.send('Browser.getVersion', {}) as { product?: string }
-      if (typeof info?.product !== 'string' || !/chrome|chromium|edge/i.test(info.product)) {
+      if (!isBrowserProduct(info?.product)) {
         client.close()
         return undefined
       }
@@ -707,11 +721,37 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     // The port file is deliberately NOT deleted here, and that is a reversal.
     //
     // It used to be removed so the launch loop below could not read a previous browser's port. But
-    // the loop already refuses any file older than the spawn (`freshPort` compares mtimes), so the
-    // deletion never protected it — while it DID destroy the only record of a browser that may
-    // still be running for this profile. That record is what `adoptRunningBrowser` needs when the
-    // launch comes back as a hand-off: the browser was alive the whole time, and without the file
-    // there is no way to find it again.
+    // the loop judges freshness against a snapshot taken below, so the deletion never protected it
+    // — while it DID destroy the only record of a browser that may still be running for this
+    // profile. That record is what `adoptRunningBrowser` needs when the launch comes back as a
+    // hand-off: the browser was alive the whole time, and without the file there is no way to find
+    // it again.
+    const portFile = join(this.profileDir, 'DevToolsActivePort')
+    /**
+     * What the port file was like BEFORE this launch, so "fresh" is judged against a snapshot
+     * rather than against a clock.
+     *
+     * The test used to be `mtimeMs < spawnedAt` — a filesystem timestamp compared to `Date.now()`.
+     * Those are different clocks with different resolutions, and CI is where it showed: a file the
+     * fake browser had just written was rejected as stale, so the loop waited out its full 30s
+     * against a browser that was already listening, because the file's mtime had rounded down
+     * below the spawn time. That is not a test-only problem: on any filesystem whose mtime
+     * resolution is coarser than a millisecond, the plugin would fail to see the browser it had
+     * just launched, and report a CDP timeout for a browser that was up the whole time.
+     *
+     * `undefined` means there was no file, so any file that appears afterwards is fresh. When one
+     * existed, a later mtime OR different contents makes the new one fresh. Byte-identical contents
+     * with an unchanged mtime is the PREVIOUS browser's port, and adopting it is what this whole
+     * check exists to prevent: it may name a port that now belongs to something else entirely.
+     */
+    const portFileBefore = ((): { mtimeMs: number; contents: string } | undefined => {
+      try {
+        return { mtimeMs: statSync(portFile).mtimeMs, contents: readFileSync(portFile, 'utf8') }
+      } catch {
+        return undefined
+      }
+    })()
+    // Kept for the failure message and for the exit listener's diagnostics; no longer a judgement.
     const spawnedAt = Date.now()
     let child: ReturnType<typeof spawn>
     try {
@@ -745,20 +785,26 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       // Clearing these is what makes the restart usable rather than merely alive.
       this.forgetBrowserState()
     })
-    const portFile = join(this.profileDir, 'DevToolsActivePort')
     /**
      * The port this launch wrote, or undefined while it has not written one yet.
      *
-     * A file left by the PREVIOUS browser is not evidence about this one. Its contents
-     * name a port that may now belong to something else entirely — another Chromium, a
-     * node --inspect — and connecting there publishes a client this host does not own and
-     * dispose() can never kill. Only a file written after the spawn counts.
+     * A file left by the PREVIOUS browser is not evidence about this one. Its contents name a port
+     * that may now belong to something else entirely — another Chromium, a `node --inspect` — and
+     * connecting there publishes a client this host does not own and dispose() can never kill.
+     * Only a file that CHANGED across this launch counts, which is what `portFileBefore` records.
      */
     const freshPort = (): number | undefined => {
       try {
         if (!existsSync(portFile)) return undefined
-        if (statSync(portFile).mtimeMs < spawnedAt) return undefined
-        const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '')
+        const after = statSync(portFile)
+        const contents = readFileSync(portFile, 'utf8')
+        // Unchanged since before the launch: this is the previous browser's file, whatever its
+        // mtime says. Comparing against the snapshot rather than the spawn time is what keeps this
+        // correct on a filesystem whose timestamps are coarser than the clock behind spawnedAt.
+        if (portFileBefore !== undefined
+          && after.mtimeMs <= portFileBefore.mtimeMs
+          && contents === portFileBefore.contents) return undefined
+        const value = Number(contents.split('\n')[0]?.trim() ?? '')
         return Number.isInteger(value) && value > 0 ? value : undefined
       } catch {
         return undefined
@@ -867,6 +913,69 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     return !this.disposed
   }
 
+  /**
+   * Every page the browser currently holds, including ones this plugin did not create.
+   *
+   * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+   * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+   * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+   * window: four pages present while `dsh_browser_list_tabs` reported one.
+   *
+   * Discovery is already on at connection time (see the blank-page normalisation), so
+   * `Target.getTargets` also lists pages that existed before this client connected.
+   * @returns the browser's pages, or an empty list when it cannot answer.
+   */
+  /**
+   * Every page the browser holds that THIS HOST did not open.
+   *
+   * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+   * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+   * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+   * window: four pages present while `dsh_browser_list_tabs` reported one.
+   *
+   * Pages this host opened are EXCLUDED here rather than deduplicated by the caller, because the
+   * caller cannot do it: the provider knows a tab by its own id, the carrier knows a page by its
+   * CDP target id, and the two never match. The first version returned everything and relied on the
+   * caller to filter, which reported the same page twice.
+   *
+   * Discovery is already on at connection time (see the blank-page normalisation), so
+   * `Target.getTargets` also lists pages that existed before this client connected.
+   * @returns the browser's pages that are not ours, or an empty list when it cannot answer.
+   */
+  async listPages(): Promise<readonly CarrierPage[]> {
+    try {
+      const client = await this.ensureClient()
+      const listed = await client.send('Target.getTargets', {}) as {
+        targetInfos?: Array<{ targetId?: string; type?: string; url?: string; title?: string }>
+      }
+      const ours = new Set(this.sessions.values())
+      return (listed?.targetInfos ?? [])
+        .filter(entry => entry.type === 'page' && typeof entry.targetId === 'string')
+        .filter(entry => !ours.has(entry.targetId as string))
+        .map(entry => ({
+          id: entry.targetId as string,
+          url: typeof entry.url === 'string' ? entry.url : '',
+          ...typeof entry.title === 'string' && entry.title !== '' ? { title: entry.title } : {},
+        }))
+    } catch {
+      // A listing must not fail harder than driving does; the next command reports a real problem.
+      return []
+    }
+  }
+
+  /**
+   * Close one page by the target id {@link listPages} reported.
+   *
+   * `Target.closeTarget` is the browser's own close, so it works for pages this plugin never
+   * created. The page may already be gone if the human closed it in the meantime — the caller
+   * asked for it to be closed and it is, so that is not an error.
+   * @param id - the CDP target id.
+   */
+  async closePage(id: string): Promise<void> {
+    const client = await this.ensureClient()
+    await client.send('Target.closeTarget', { targetId: id }).catch(() => undefined)
+  }
+
   createView(): ElectronViewHandle {
     const viewId = randomUUID()
     return {