dsh-builtin-browser 0.1.22 → 0.2.0

package/src/browser-electron/provider.ts

@@ -11,6 +11,9 @@ import { randomUUID } from 'node:crypto'
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
+import { HistoryStore, type VisitedPage } from './history-store.js'
+import type { BrowserSettings } from './settings-store.js'
+import { paintCursor, type CursorAction } from './virtual-cursor.js'
 import type {
   BrowserA11yRequest,
   BrowserA11yResult,
@@ -175,6 +178,13 @@ export interface ElectronBrowserViewHost {
    * @param handler - called for every user action; must not throw.
    */
   onUserAction?(handler: (action: BrowserUserAction) => void): void
+  /**
+   * Optional: receive notice that the human closed a browser window. Closing the
+   * interface ends the session it showed — the next call opens a clean one —
+   * while browsing history and login state survive on disk.
+   * @param handler - called with the group (session) key; must not throw.
+   */
+  onViewClosed?(handler: (windowId: string) => void): void
 }
 
 /**
@@ -207,6 +217,12 @@ export interface ElectronViewHandle {
    * @returns the CDP `result` object.
    */
   sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>
+  /**
+   * Give the backing view web focus so keyboard input reaches its page.
+   * Optional: an adapter that cannot focus a view omits it, and the provider
+   * then behaves exactly as before.
+   */
+  focus?(): Promise<void>
 }
 
 /** One tab inside a session: its view plus a stable id. */
@@ -232,6 +248,28 @@ interface Session {
 export interface ElectronBrowserProviderConfig {
   /** Allow navigation only to HTTP(S) URLs; reject anything else. Default true. */
   readonly httpOnly?: boolean
+  /**
+   * Persistent browsing history (visited pages), independent of session
+   * lifetime. `enabled: false` keeps the browser working but records nothing;
+   * the retained limits ride along so a user's choice from the settings panel
+   * reaches the store without a second configuration path.
+   */
+  readonly history?: {
+    readonly enabled?: boolean
+    readonly maxEntries?: number
+    readonly maxAgeDays?: number
+    /**
+     * Explicit history file path. Default: beside the browser profile
+     * (`$DSH_HOME/dsh-builtin-browser-host/history.jsonl`).
+     */
+    readonly file?: string
+  }
+  /**
+   * Live settings source (the settings panel's document). When present it wins
+   * over the static `history` config, so a switch flipped in the UI takes effect
+   * without restarting DSH.
+   */
+  readonly settings?: () => BrowserSettings
   /** Maximum snapshot elements before truncation. Default 60. */
   readonly snapshotMaxElements?: number
   /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
@@ -254,14 +292,16 @@ export interface CdpNavigateParams {
 }
 
 /**
- * CDP method/params for `Input.dispatchMouseEvent` (a click press+release pair).
+ * CDP method/params for `Input.dispatchMouseEvent`: a pointer move, or one half
+ * of a click's press+release pair. `button`/`clickCount` belong to the press and
+ * release halves; a move carries only the position.
  */
 export interface CdpMouseParams {
-  readonly type: 'mousePressed' | 'mouseReleased'
+  readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased'
   readonly x: number
   readonly y: number
-  readonly button: 'left'
-  readonly clickCount: number
+  readonly button?: 'left'
+  readonly clickCount?: number
 }
 
 /** CDP method/params for `Input.insertText`. */
@@ -357,6 +397,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
   private readonly snapshotMaxElements: number
   private readonly contentMaxChars: number
   private readonly downloadDir: string | undefined
+  /**
+   * Persistent browsing history, or `undefined` when the user turned it off.
+   * Sessions come and go; this record outlives all of them.
+   */
+  private readonly historyStore: HistoryStore | undefined
+  /** Live settings source; absent when nothing owns a settings document. */
+  private readonly settingsSource: (() => BrowserSettings) | undefined
 
   constructor(
     private readonly host: ElectronBrowserViewHost,
@@ -371,9 +418,21 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // sandbox does not have to arbitrate. The localized name is probed so a
     // Chinese desktop (`~/下载`) works without configuring `downloadDir`.
     this.downloadDir = config.downloadDir ?? defaultDownloadDir()
+    this.settingsSource = config.settings
+    // Browsing history follows the browser profile's persistence rules (close
+    // the interface, lose nothing), and can be switched off from settings.
+    this.historyStore = config.history?.enabled === false
+      ? undefined
+      : new HistoryStore(config.history?.file, {
+        ...config.history?.maxEntries !== undefined ? { maxEntries: config.history.maxEntries } : {},
+        ...config.history?.maxAgeDays !== undefined ? { maxAgeDays: config.history.maxAgeDays } : {},
+      })
     // Route toolbar (host UI) actions into the session model: the human and
     // the agent then always drive the same tabs, history, and navigation.
     this.host.onUserAction?.(action => { void this.handleUserAction(action) })
+    // A window the human closed ends the session it showed: the next call opens a
+    // clean one instead of driving a page nobody can see.
+    this.host.onViewClosed?.(windowId => { void this.handleViewClosed(windowId) })
   }
 
   /**
@@ -548,6 +607,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // NEXT observation sees, not whether this action happened).
       this.record(s, 'navigate', { url }, true)
       await this.settleDocument(handle, before, signal)
+      this.recordVisit(s, handle)
       this.showActive(s)
     } catch (error) {
       if (!(error instanceof BrowserError && (error as { code?: string }).code === 'BROWSER_NAVIGATION_BLOCKED')) {
@@ -664,6 +724,26 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
+  /**
+   * Give the view web focus before synthesizing keyboard input.
+   *
+   * A renderer only delivers key events to the view that holds web focus. A
+   * view that was created but never clicked holds none — and `Input` events
+   * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+   * session vanished inside the renderer while the command still answered
+   * success. Hosts that cannot focus a view (a test double, a different shell
+   * adapter) simply have no `focus`, and nothing changes for them.
+   */
+  private async focusView(handle: ElectronViewHandle): Promise<void> {
+    if (handle.focus === undefined) return
+    try {
+      await handle.focus()
+    } catch {
+      // Best-effort: a view that refuses focus must not fail the caller's key
+      // press; the dispatch below reports a real channel failure itself.
+    }
+  }
+
   /** Execute JS in the active tab's page context. */
   async execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult> {
     const s = this.session(session)
@@ -1196,23 +1276,54 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // Input.* is only delivered to a view with a current display surface; the
     // barrier also re-presents after a navigation replaced the renderer.
     await this.present(s, signal)
-    const press = (type: 'mousePressed' | 'mouseReleased'): Promise<Record<string, unknown>> =>
-      handle.sendCommand('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 } satisfies CdpMouseParams)
     const timeoutMs = 30_000
+    const send = (params: Record<string, unknown>, label: string): Promise<unknown> =>
+      withTimeout(
+        handle.sendCommand('Input.dispatchMouseEvent', params),
+        timeoutMs,
+        signal,
+        `browser: click ${label} timed out after ${timeoutMs}ms`,
+      )
+    // Chromium routes a synthesized `mousePressed` to the widget's *current*
+    // hover target rather than hit-testing the coordinates, and a real pointer
+    // click is always preceded by movement. A view that has never received a
+    // mouse event has no hover target yet, so the press of the FIRST click on a
+    // fresh tab went nowhere while CDP still answered success; the second click
+    // landed because the first had quietly established the target. Move the
+    // pointer first so a click is self-contained.
     try {
-      await withTimeout(press('mousePressed'), timeoutMs, signal, `browser: click press timed out after ${timeoutMs}ms`)
+      await send({ type: 'mouseMoved', x, y } satisfies CdpMouseParams, 'move')
+    } catch (error) {
+      throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
+    }
+    // Paint before the press so the ripple is already on screen when the click
+    // lands — the cursor exists to show the human WHERE the agent acts.
+    this.showCursor(handle, x, y, 'click')
+    const release = (): void => {
+      void handle
+        .sendCommand('Input.dispatchMouseEvent', {
+          type: 'mouseReleased',
+          x,
+          y,
+          button: 'left',
+          clickCount: 1,
+        } satisfies CdpMouseParams)
+        .catch(() => {})
+    }
+    try {
+      await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press')
     } catch (error) {
       // The press may still land late; release best-effort so the button is
       // never left in a stuck pressed state.
-      void press('mouseReleased').catch(() => {})
+      release()
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
     try {
-      await withTimeout(press('mouseReleased'), timeoutMs, signal, `browser: click release timed out after ${timeoutMs}ms`)
+      await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release')
     } catch (error) {
       // The press already landed; retry the release so the button is not
       // left pressed before surfacing the failure.
-      void press('mouseReleased').catch(() => {})
+      release()
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
     this.record(s, 'click', 'target' in request ? { target: request.target } : { x, y }, true)
@@ -1237,7 +1348,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
         el.focus()
         return { ok: true }
       `)
-      await this.runTargetScript(this.activeTab(s), script, locateMs, signal, 'BROWSER_TYPE_FAILED', 'browser: type')
+      const locateTab = this.activeTab(s)
+      const out = await this.runTargetScript(locateTab, script, locateMs, signal, 'BROWSER_TYPE_FAILED', 'browser: type')
+      const cursorPoint = scriptPoint(out)
+      if (cursorPoint !== undefined) this.showCursor(locateTab.handle, cursorPoint.x, cursorPoint.y, 'click')
     }
     const text = 'text' in request ? request.text : ''
     const timeoutMs = 30_000
@@ -1327,6 +1441,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     )
     this.record(s, direction === -1 ? 'back' : 'forward', {}, true)
     await this.settleDocument(handle, before, signal)
+    this.recordVisit(s, handle)
     this.showActive(s)
   }
 
@@ -1359,6 +1474,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     )
     this.record(s, 'reload', {}, true)
     await this.settleDocument(handle, before, signal)
+    this.recordVisit(s, handle)
     this.showActive(s)
   }
 
@@ -1375,6 +1491,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const timeoutMs = 15_000
     // Input.dispatchKeyEvent is subject to the same display-surface rule.
     await this.present(s, signal)
+    await this.focusView(handle)
     const release = (): Promise<Record<string, unknown>> =>
       handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params })
     try {
@@ -1552,10 +1669,16 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * (polling until it appears or the budget runs out) and then runs `body`
    * with `el` in scope. Shared by the target-based tools: click/type (②),
    * setValue/check/select/clear/getValue (③), and the scrape item wait.
+   * A selector that fails to PARSE is reported immediately instead of being
+   * polled until the budget expires — see the comment in `match`.
    */
   private buildTargetScript(spec: BrowserElementTarget, timeoutMs: number, body: string): string {
+    // `by` defaults to css in-page; report the strategy that WAS used, or a
+    // miss says only `{"value":"Learn more"}` and the caller cannot tell that a
+    // plain label was queried as a CSS selector.
+    const resolvedSpec = { ...spec, by: spec.by ?? 'css' }
     return `(async () => {
-      const spec = ${JSON.stringify(spec)}
+      const spec = ${JSON.stringify(resolvedSpec)}
       const timeoutMs = ${String(timeoutMs)}
       const sleep = ms => new Promise(r => setTimeout(r, ms))
       const isVisible = el => el instanceof HTMLElement && (el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0)
@@ -1567,7 +1690,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
         const index = typeof spec.index === 'number' ? spec.index : 0
         let els = []
         if (by === 'css') {
-          try { els = Array.from(document.querySelectorAll(value)) } catch { return null }
+          // A selector that does not PARSE can never match on a later poll, so
+          // it must not look like a miss: the old "return null" kept the caller
+          // polling until the whole budget was gone, and "element not found
+          // after 10s" reads like a slow page while the real cause is a
+          // malformed selector (a label or plain text passed where one belongs).
+          try { els = Array.from(document.querySelectorAll(value)) }
+          catch (error) { throw new Error('invalid CSS selector ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else if (by === 'xpath') {
           try {
             const snap = document.evaluate(value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
@@ -1575,7 +1704,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
               const n = snap.snapshotItem(i)
               if (n instanceof Element) els.push(n)
             }
-          } catch { return null }
+          } catch (error) { throw new Error('invalid XPath ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else {
           const all = Array.from(document.querySelectorAll('body *'))
           const exact = all.filter(el => isVisible(el) && ownText(el) === value)
@@ -1589,12 +1718,24 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const deadline = Date.now() + timeoutMs
       let el = null
       for (;;) {
-        el = match()
+        // Only a parse error escapes the poll: see the comment in match() above.
+        try { el = match() } catch (error) { return { ok: false, error: String((error && error.message) || error) } }
         if (el !== null) break
-        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) }
+        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) + ' (looked for ' + timeoutMs + 'ms)' }
         await sleep(100)
       }
+      const __result = await (async () => {
       ${body}
+      })()
+      // Report the operated element's viewport center next to the script's own
+      // verdict: the synthetic cursor (and any future feedback) needs the point,
+      // and no individual body should have to compute it a second time. Kept
+      // under a distinct key so a body that already returns x/y keeps them.
+      const __rect = el.getBoundingClientRect()
+      return {
+        ...(typeof __result === 'object' && __result !== null ? __result : { ok: true }),
+        __point: { x: Math.round(__rect.x + __rect.width / 2), y: Math.round(__rect.y + __rect.height / 2) },
+      }
     })()`
   }
 
@@ -1611,9 +1752,14 @@ export class ElectronBrowserProvider implements BrowserProvider {
     errorCode: string,
     errorLabel: string,
   ): Promise<Record<string, unknown>> {
+    // The script polls for its whole `timeoutMs` and only then answers, so an
+    // outer budget of the same size fires at the same instant and wins: the
+    // caller saw `click timed out after 10000ms` while the page had already
+    // decided WHY (selector not found / malformed). Give the answer a chance to
+    // get back before the generic timeout replaces it.
     const result = await withTimeout(
       handleSendEvaluate(tab.handle, script),
-      timeoutMs,
+      timeoutMs + TARGET_SCRIPT_GRACE_MS,
       signal,
       `${errorLabel} timed out after ${timeoutMs}ms`,
       () => terminatePage(tab.handle),
@@ -1667,6 +1813,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
     const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_SET_VALUE_FAILED', 'browser: setValue')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'setValue', { target: request.target, value: String(request.value) }, true, { result: out.method as string })
     return { method: out.method as string, value: out.value as string }
   }
@@ -1693,6 +1841,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
     const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CHECK_FAILED', 'browser: check')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'check', { target: request.target, checked: want }, true)
     return { checked: out.checked === true }
   }
@@ -1725,6 +1875,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
     const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_SELECT_FAILED', 'browser: select')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'select', { target: request.target, optionValue: request.optionValue ?? null, optionText: request.optionText ?? null, optionIndex: request.optionIndex ?? null }, true)
     return { value: out.value as string, text: out.text as string }
   }
@@ -1758,7 +1910,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       return { ok: true }
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
-    await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CLEAR_FAILED', 'browser: clear')
+    const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CLEAR_FAILED', 'browser: clear')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'clear', { target: request.target }, true)
     return { cleared: true }
   }
@@ -1813,7 +1967,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const deadline = Date.now() + timeoutMs
       let items = []
       for (;;) {
-        try { items = Array.from(document.querySelectorAll(itemSel)) } catch (e) { return { ok: false, error: String(e) } }
+        // Immediate, like match() above: an unparseable selector can never match.
+        try { items = Array.from(document.querySelectorAll(itemSel)) }
+        catch (error) { return { ok: false, error: 'invalid CSS selector ' + JSON.stringify(itemSel) + ' (' + String((error && error.message) || error) + ')' } }
         if (items.length > 0) break
         if (Date.now() >= deadline) return { ok: false, error: 'no elements matched: ' + itemSel }
         await sleep(100)
@@ -2083,6 +2239,60 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return this.session(session).history
   }
 
+  /**
+   * Record one page visit in the persistent browsing history. Fire-and-forget by
+   * design: a visit must never delay or fail the navigation that produced it,
+   * and the title is only worth reading once the document has settled.
+   * @param s - the session that drove the visit.
+   * @param handle - the view whose document just loaded.
+   */
+  private recordVisit(s: Session, handle: ElectronViewHandle): void {
+    const store = this.historyStore
+    if (store === undefined) return
+    // The settings panel can switch recording off at runtime; the static config
+    // only supplies the startup default.
+    if (this.settingsSource !== undefined && !this.settingsSource().history.enabled) return
+    void handleSendEvaluate(handle, 'location.href + "\\u0000" + (document.title || "")')
+      .then(result => {
+        if (!result.ok || typeof result.value !== 'string') return
+        const [url = '', title = ''] = result.value.split('\u0000')
+        // Internal documents are not visits: an untouched browser is not history.
+        if (url === '' || url.startsWith('about:') || url.startsWith('devtools:')) return
+        store.append({
+          at: Date.now(),
+          url,
+          ...title.trim() !== '' ? { title: title.trim() } : {},
+          ...s.label !== undefined ? { session: s.label } : {},
+        })
+        store.prune()
+      })
+      .catch(() => { /* best-effort: history is never worth surfacing an error */ })
+  }
+
+  /**
+   * List persisted visits, newest first — what `browser_visited` reads back.
+   * @param options - result cap and an optional hostname filter.
+   * @returns the matching visits, or an empty list when history is disabled.
+   */
+  visited(options: { readonly limit?: number; readonly domain?: string } = {}): readonly VisitedPage[] {
+    return this.historyStore?.list(options) ?? []
+  }
+
+  /**
+   * Show the synthetic pointer on a view, unless the user switched it off. The
+   * cursor is the "the agent has taken over this tab" signal, so it is painted
+   * for every operation that has a landing point — including DOM-level ones that
+   * move no real pointer.
+   * @param handle - the view to paint into.
+   * @param x - viewport x in CSS pixels.
+   * @param y - viewport y in CSS pixels.
+   * @param action - click pulses a ripple; move only relocates.
+   */
+  private showCursor(handle: ElectronViewHandle, x: number, y: number, action: CursorAction): void {
+    if (this.settingsSource !== undefined && !this.settingsSource().ui.virtualCursor) return
+    paintCursor(handle, x, y, action, (target, expression) => handleSendEvaluate(target, expression))
+  }
+
   /**
    * Replay one recorded operation by sequence number. Navigate/click/type are
    * re-issued against the current page; execute re-runs its script. The
@@ -2195,6 +2405,29 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return s.tabs.find(tab => tab.handle.id === viewId)
   }
 
+  /**
+   * Whether a session is still live. The human closing a window ends its session
+   * (see {@link handleViewClosed}), so callers that cache ids must ask first.
+   * @param session - the session id to test.
+   */
+  exists(session: BrowserSessionId): boolean {
+    return this.sessions.has(session)
+  }
+
+  /**
+   * The human closed a browser window: the session that window showed is over.
+   * Ending it here is what makes the next call a clean start rather than a
+   * resurrection of an invisible window. Browsing history and login state live
+   * on disk, so nothing the human cares about is lost with it.
+   * @param windowId - the group key the host reported, which is the session id.
+   */
+  private async handleViewClosed(windowId: string): Promise<void> {
+    if (typeof windowId !== 'string' || windowId === '') return
+    const s = this.sessions.get(windowId as BrowserSessionId)
+    if (s === undefined) return
+    await this.close(s.id).catch(() => { /* the window is already gone */ })
+  }
+
   /**
    * Route a user-initiated action from the host's UI into the session model.
    * Fire-and-forget by design: a user action failing (e.g. an unreachable
@@ -2295,6 +2528,13 @@ const SETTLE_GRACE_MS = 150
 /** Poll interval for the document-settle loop. */
 const SETTLE_POLL_MS = 25
 
+/**
+ * Extra time the transport gets over an in-page locate script's own budget: the
+ * script polls for `timeoutMs` and answers only afterwards, so the outer wait
+ * must outlast it or its generic timeout hides the in-page reason.
+ */
+const TARGET_SCRIPT_GRACE_MS = 2_000
+
 /** `tab:<uuid>` ↔ `<uuid>`: ids accept either form (see locateTab). */
 function stripTabPrefix(id: string): string {
   return id.startsWith('tab:') ? id.slice(4) : id
@@ -2393,6 +2633,14 @@ function terminatePage(handle: ElectronViewHandle): void {
  * @param expression - the JS expression.
  * @param signal - optional abort signal; a fired signal rejects the call.
  */
+/** Viewport point a target script reported, when it reported one. */
+function scriptPoint(out: Record<string, unknown> | undefined): { x: number; y: number } | undefined {
+  const point = out?.__point as { x?: unknown; y?: unknown } | undefined
+  const x = Number(point?.x)
+  const y = Number(point?.y)
+  return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : undefined
+}
+
 async function handleSendEvaluate(
   handle: ElectronViewHandle,
   expression: string,