dsh-browser-plus 0.5.0 → 0.5.1

package/src/browser-electron/provider.ts

@@ -47,8 +47,13 @@ import type {
   BrowserTaskUpdate,
   BrowserUploadFileRequest,
   BrowserUploadFileResult,
+  BrowserPdfRequest,
+  BrowserPdfResult,
+  BrowserHighlightRequest,
+  BrowserHighlightResult,
   BrowserWaitForRequest,
   BrowserWaitForResult,
+  BrowserTaskTodo,
   ExportedCookie,
 } from '../browser/types.ts'
 import { BrowserError } from '../browser/types.ts'
@@ -188,6 +193,8 @@ export interface ElectronBrowserViewHost {
   getTask?(key: string): Promise<BrowserTaskInfo | undefined>
   /** Apply a task status/control update to the visible workspace. */
   updateTask?(key: string, update: BrowserTaskUpdate): Promise<BrowserTaskInfo | undefined>
+  /** Mirror one task's Agent todo list into the visible workspace (floating orb). */
+  setTaskTodos?(key: string, todos: readonly BrowserTaskTodo[]): Promise<void>
 }
 
 /**
@@ -231,10 +238,28 @@ export interface ElectronViewHandle {
    * tokenless copy as a fallback.
    */
   reinstallChrome?(): Promise<void>
+  /**
+   * Print this view to a PDF and return it base64-encoded. Optional: a host
+   * with no native print path omits it, and the provider falls back to CDP.
+   *
+   * Electron's debugger does NOT implement CDP `Page.printToPDF` (it answers
+   * "'Page.printToPDF' wasn't found"), so the PDF path has to go through the
+   * host's own `webContents.printToPDF`.
+   * @param options - Electron PrintToPDFOptions (pageSize in microns).
+   */
+  printToPdf?(options: Record<string, unknown>): Promise<{ readonly base64: string }>
+  /**
+   * Raise this view's window (show + restore + focus). Optional: a host that
+   * owns no window omits it. Distinct from the provider's own show/switch
+   * path, which deliberately leaves a human-selected visible task alone.
+   */
+  focusWindow?(): Promise<void>
 }
 
 /** Internal selector and fingerprint captured for one snapshot element. */
 interface SnapshotTarget {
+  /** iframe index when the target lives inside a frame. */
+  readonly frame?: number
   readonly path: string
   readonly fingerprint: string
 }
@@ -377,6 +402,12 @@ export interface CdpEvaluateParams {
 
 /** CDP method for a full-page screenshot capture. */
 export const CDP_PAGE_CAPTURE_SCREENSHOT = 'Page.captureScreenshot'
+/** CDP method that renders the current document to PDF. */
+export const CDP_PAGE_PRINT_TO_PDF = 'Page.printToPDF'
+/** CDP methods that draw the DevTools highlight box without touching the DOM. */
+export const CDP_OVERLAY_ENABLE = 'Overlay.enable'
+export const CDP_OVERLAY_HIGHLIGHT_NODE = 'Overlay.highlightNode'
+export const CDP_OVERLAY_HIDE_HIGHLIGHT = 'Overlay.hideHighlight'
 /** CDP method for runtime evaluation (the execute path). */
 export const CDP_RUNTIME_EVALUATE = 'Runtime.evaluate'
 
@@ -530,7 +561,6 @@ export const CDP_PAGE_RELOAD = 'Page.reload'
 export const CDP_PAGE_STOP_LOADING = 'Page.stopLoading'
 
 /** Cap on content returned by a snapshot fetch to keep the wire bounded. */
-const SNAPSHOT_LABEL_MAX = 120
 
 /** An input dispatch must not outlive this: a blocked renderer never acknowledges. */
 const INPUT_DISPATCH_TIMEOUT_MS = 15_000
@@ -686,6 +716,14 @@ export class ElectronBrowserProvider implements BrowserProvider {
   /** Stable task-key index so callers can recover a session after tool-layer state loss. */
   private readonly sessionsByTask = new Map<string, BrowserSessionId>()
   private readonly taskStates = new Map<string, LocalTaskState>()
+  /**
+   * The Agent's todo list per task, kept here as well as in the host.
+   *
+   * The host's copy is in memory and dies with the host process, and the bridge
+   * only pushes on a todo change — so without this cache a host restart left the
+   * floating orb with no plan until the Agent happened to write its list again.
+   */
+  private readonly taskTodos = new Map<string, readonly BrowserTaskTodo[]>()
   private readonly httpOnly: boolean
   private readonly snapshotMaxElements: number
   private readonly contentMaxChars: number
@@ -802,12 +840,24 @@ export class ElectronBrowserProvider implements BrowserProvider {
         const labelable = active as { label?(label: string): Promise<void> } | undefined
         if (typeof labelable?.label === 'function') await labelable.label(taskLabel).catch(() => undefined)
       }
+      // 宿主重启后它内存里那份计划是空的，而这是**已存在会话**唯一会走到的入口
+      // （ensureWindowVisible 也补推一次）—— 不推的话球上会一直空着。
+      const cached = this.taskTodos.get(taskKey)
+      if (cached !== undefined && typeof this.host.setTaskTodos === 'function') {
+        void this.host.setTaskTodos(taskKey, cached).catch(() => undefined)
+      }
       return existing.id
     }
     const handle = this.host.createView(taskKey, taskLabel === '' ? undefined : taskLabel)
     const id = `browser:${randomUUID()}`
     this.sessions.set(id, { id, taskKey, taskLabel, tabs: [this.createTab(handle)], activeIndex: 0, history: [], nextSeq: 1 })
     this.sessionsByTask.set(taskKey, id)
+    // A fresh view means a host that may never have seen this task's plan (a host
+    // restart drops the host's copy), so replay what the Agent last wrote.
+    const cachedTodos = this.taskTodos.get(taskKey)
+    if (cachedTodos !== undefined && typeof this.host.setTaskTodos === 'function') {
+      void this.host.setTaskTodos(taskKey, cachedTodos).catch(() => undefined)
+    }
     if (!this.taskStates.has(taskKey)) {
       this.taskStates.set(taskKey, { status: 'idle', control: 'agent', updatedAt: Date.now() })
     }
@@ -1133,7 +1183,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
         if (text) return tag + ':has-text("' + text.replace(/"/g, '\\\\"') + '")'
         return tag
       }
-      const pathOf = (el) => {
+      const pathOf = (el, doc) => {
         if (el.id) return '#' + CSS.escape(el.id)
         const parts = []
         let node = el
@@ -1145,7 +1195,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
             if (siblings.length > 1) part += ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')'
           }
           parts.unshift(part)
-          if (node === document.body) break
+          if (node === doc.body) break
           node = parent
         }
         return parts.join(' > ')
@@ -1160,42 +1210,65 @@ export class ElectronBrowserProvider implements BrowserProvider {
       ].join('\u001f')
       const url = location.href
       const title = document.title || undefined
-      const els = [...document.querySelectorAll('input, textarea, select, button, a[href], [role="button"], [role="searchbox"], [contenteditable="true"]')]
       const out = []
       let capped = false
-      for (const el of els) {
-        if (el.closest('[data-dsh-browser-chrome]')) continue
-        const r = el.getBoundingClientRect()
-        const cs = getComputedStyle(el)
-        if (r.width < 4 || r.height < 4 || cs.visibility === 'hidden' || cs.display === 'none') continue
-        const kind = el.tagName === 'INPUT' ? (el.type === 'checkbox' ? 'checkbox' : (el.type === 'submit' || el.type === 'button' ? 'button' : 'input'))
-          : el.tagName === 'TEXTAREA' ? 'textarea'
-          : el.tagName === 'SELECT' ? 'select'
-          : el.tagName === 'BUTTON' ? 'button'
-          : el.tagName === 'A' ? 'link' : 'other'
-        const label = (el.getAttribute('aria-label') || el.placeholder || el.textContent || el.value || el.name || el.id || '').toString().replace(/\\s+/g, ' ').trim().slice(0, ${String(SNAPSHOT_LABEL_MAX)})
-        if (!label && kind !== 'link') continue
-        // 过滤放在计上限**之前**：默认上限是 60，先截断就永远搜不到后面的元素。
-        if (query !== '' && (kind + ' ' + label).toLowerCase().indexOf(query) === -1) continue
-        if (out.length >= cap) { capped = true; break }
-        out.push({
-          ref: out.length + 1,
-          kind,
-          label,
-          selector: el.id ? '#' + CSS.escape(el.id) : (el.name ? '[name=' + JSON.stringify(el.name) + ']' : ''),
-          loc: locatorOf(el),
-          path: pathOf(el),
-          fingerprint: fingerprintOf(el),
-          x: Math.round(r.x + r.width / 2),
-          y: Math.round(r.y + r.height / 2),
-        })
+      // 同一套判定，用在顶层文档和每个同源子框架上；dx/dy 把框架内的坐标换算成页面坐标。
+      const collect = (doc, frameIndex, dx, dy) => {
+        const els = [...doc.querySelectorAll('input, textarea, select, button, a[href], [role="button"], [role="searchbox"], [role="link"], [contenteditable="true"]')]
+        for (const el of els) {
+          if (el.closest('[data-dsh-browser-chrome]')) continue
+          const r = el.getBoundingClientRect()
+          const cs = getComputedStyle(el)
+          if (r.width < 4 || r.height < 4 || cs.visibility === 'hidden' || cs.display === 'none') continue
+          const kind = el.tagName === 'INPUT' ? (el.type === 'checkbox' ? 'checkbox' : (el.type === 'submit' || el.type === 'button' ? 'button' : 'text'))
+            : el.tagName === 'TEXTAREA' ? 'textarea'
+            : el.tagName === 'SELECT' ? 'select'
+            : el.tagName === 'BUTTON' ? 'button'
+            : el.tagName === 'A' ? 'link' : 'other'
+          const label = (el.getAttribute('aria-label') || el.placeholder || el.textContent || el.value || el.name || el.id || '').replace(/\s+/g, ' ').trim().slice(0, 120)
+          if (!label && kind !== 'link') continue
+          // 过滤放在计上限**之前**：默认上限是 60，先截断就永远搜不到后面的元素。
+          if (query !== '' && (kind + ' ' + label).toLowerCase().indexOf(query) === -1) continue
+          if (out.length >= cap) { capped = true; return }
+          out.push({
+            ref: out.length + 1,
+            kind,
+            label,
+            ...(frameIndex === undefined ? {} : { frame: frameIndex }),
+            selector: el.id ? '#' + CSS.escape(el.id) : (el.name ? '[name=' + JSON.stringify(el.name) + ']' : ''),
+            loc: locatorOf(el),
+            path: pathOf(el, doc),
+            fingerprint: fingerprintOf(el),
+            x: Math.round(r.x + r.width / 2 + dx),
+            y: Math.round(r.y + r.height / 2 + dy),
+          })
+        }
+      }
+      collect(document, undefined, 0, 0)
+      // 子框架：同源的走进去（元素带 frame 序号、坐标加上框架自己的矩形）；
+      // 跨源的 contentDocument 读不到，就只记一条 readable:false —— 不假装能读。
+      const frames = []
+      const frameEls = [...document.querySelectorAll('iframe')]
+      for (let i = 0; i < frameEls.length; i++) {
+        const frame = frameEls[i]
+        const src = frame.getAttribute('src') || ''
+        let inner = null
+        try { inner = frame.contentDocument } catch (error) { inner = null }
+        if (inner === null) {
+          frames.push({ index: i, url: src, readable: false })
+          continue
+        }
+        const fr = frame.getBoundingClientRect()
+        frames.push({ index: i, url: inner.location.href || src, readable: true })
+        if (out.length >= cap) { capped = true; continue }
+        collect(inner, i, fr.left, fr.top)
       }
       const challenge = ${CHALLENGE_DETECT_EXPRESSION}
       const chromeHost = document.getElementById('__dsh_browser_chrome_host__')
       const userControlling = chromeHost?.getAttribute('data-dsh-user-active') === '1'
       // Only an early break means truncation: exactly cap candidates is a
       // complete inventory, not a truncated one.
-      return { url, title, elements: out, truncated: capped, challenge, userControlling }
+      return { url, title, elements: out, truncated: capped, frames, challenge, userControlling }
     })()`
     // Same hang guard as execute: a renderer that has not committed after
     // navigate would otherwise block snapshot forever.
@@ -1235,7 +1308,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const snapshotId = `snapshot:${randomUUID()}`
     const targets = new Map<number, SnapshotTarget>()
     for (const element of value.elements) {
-      targets.set(element.ref, { path: element.path, fingerprint: element.fingerprint })
+      targets.set(element.ref, {
+        path: element.path,
+        fingerprint: element.fingerprint,
+        ...element.frame !== undefined ? { frame: element.frame } : {},
+      })
     }
     tab.snapshots.set(snapshotId, { tabId: tab.id, url: value.url, epoch: tab.navigationEpoch, targets })
     while (tab.snapshots.size > 10) {
@@ -1248,6 +1325,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       url: value.url,
       ...value.title !== undefined ? { title: value.title } : {},
       elements: value.elements.map(({ path: _path, fingerprint: _fingerprint, ...element }) => element),
+      ...value.frames !== undefined ? { frames: value.frames } : {},
       truncated: value.truncated,
       ...value.challenge !== undefined ? { challenge: value.challenge } : {},
       ...value.userControlling !== undefined ? { userControlling: value.userControlling } : {},
@@ -1528,27 +1606,55 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return this.waitForElementTab(s, this.activeTab(s), request, signal)
   }
 
-  /** Poll one tab until the selector matches. */
+  /** Poll one tab until the selector and/or text reaches the requested state. */
   private async waitForElementTab(s: Session, tab: Tab, request: BrowserWaitForRequest, signal?: AbortSignal): Promise<BrowserWaitForResult> {
     const { handle } = tab
     signal?.throwIfAborted()
     const timeoutMs = request.timeoutMs ?? 15_000
-    const visible = request.visible !== false
-    const selector = request.selector
+    const selector = request.selector ?? ''
+    const wanted = request.text
+    const state: 'visible' | 'attached' | 'hidden' | 'detached' = request.state ?? (request.visible === false ? 'attached' : 'visible')
+    if (selector === '' && wanted === undefined) {
+      throw new BrowserError('browser: waitForElement needs a selector, some text, or both', 'BROWSER_WAIT_INVALID')
+    }
+    if (selector === '' && (state === 'hidden' || state === 'detached')) {
+      throw new BrowserError(`browser: state "${state}" needs a selector to watch disappear`, 'BROWSER_WAIT_INVALID')
+    }
     const script = `(() => {
+      const selector = ${JSON.stringify(selector)}
+      const wanted = ${JSON.stringify(wanted ?? null)}
+      const state = ${JSON.stringify(state)}
       let el = null
-      try { el = document.querySelector(${JSON.stringify(selector)}) } catch (e) { return { error: String(e) } }
-      if (!el) return null
-      if (${visible}) {
-        const r = el.getBoundingClientRect()
-        const cs = getComputedStyle(el)
-        if (r.width < 4 || r.height < 4 || cs.visibility === 'hidden' || cs.display === 'none') return null
+      if (selector !== '') {
+        try { el = document.querySelector(selector) } catch (e) { return { error: String(e) } }
       }
+      const visibleNow = node => {
+        if (node === null) return false
+        const r = node.getBoundingClientRect()
+        if (r.width < 4 || r.height < 4) return false
+        const cs = getComputedStyle(node)
+        return cs.visibility !== 'hidden' && cs.display !== 'none'
+      }
+      const textOf = node => (node === null ? '' : (node.textContent || '')).replace(/\\s+/g, ' ').trim()
+      const attached = el !== null
+      const visible = visibleNow(el)
+      let met
+      if (selector === '') {
+        // 只等文字时没有元素可量：文字在不在，本身就是那个状态。
+        // （以前这里仍按 visibleNow(null) === false 判定，于是默认的 visible 永远不成立。）
+        const present = textOf(document.body).includes(wanted)
+        met = state === 'hidden' || state === 'detached' ? !present : present
+      } else {
+        met = state === 'attached' ? attached : state === 'visible' ? visible : state === 'hidden' ? !visible : state === 'detached' ? !attached : false
+        if (met && wanted !== null) met = textOf(el).includes(wanted)
+      }
+      if (!met) return null
       return {
         found: true,
-        selector: ${JSON.stringify(selector)},
-        tag: el.tagName.toLowerCase(),
-        text: (el.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 200),
+        state,
+        selector,
+        tag: attached ? el.tagName.toLowerCase() : '',
+        text: (wanted !== null && !attached ? wanted : textOf(selector === '' ? document.body : el)).slice(0, 200),
       }
     })()`
     const deadline = Date.now() + timeoutMs
@@ -1561,8 +1667,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
       } else {
         const value = result.value as { found?: boolean; tag?: string; text?: string; error?: string } | null
         if (value?.found === true && typeof value.tag === 'string') {
-          this.record(s, 'waitForElement', { selector, timeoutMs, visible }, true, { result: value.tag })
-          return { found: true, selector, tag: value.tag, text: value.text ?? '' }
+          this.record(s, 'waitForElement', { selector, text: wanted, state, timeoutMs }, true, { result: value.tag ?? '' })
+          return { found: true, state, selector, tag: value.tag, text: value.text ?? '' }
         }
         if (value?.error !== undefined) {
           // A malformed selector can never start matching, so fail now instead of
@@ -1572,7 +1678,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
       }
       await new Promise(resolve => setTimeout(resolve, Math.min(250, Math.max(deadline - Date.now(), 1))))
     }
-    throw new BrowserError(`browser: element "${selector}" did not appear within ${timeoutMs}ms${lastError !== undefined ? ` (${lastError})` : ''}`, 'BROWSER_WAIT_TIMEOUT')
+    const what = selector === '' ? `text ${JSON.stringify(wanted)}` : `"${selector}"`
+    throw new BrowserError(`browser: ${what} did not reach state "${state}" within ${timeoutMs}ms${lastError !== undefined ? ` (${lastError})` : ''}`, 'BROWSER_WAIT_TIMEOUT')
   }
 
   /** Type into the focused element. */
@@ -2085,6 +2192,111 @@ export class ElectronBrowserProvider implements BrowserProvider {
   }
 
   /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
+  /**
+   * Draw the DevTools highlight box over the first match of a selector, or clear it.
+   * Uses CDP Overlay, so the page DOM is never touched.
+   */
+  async highlight(
+    session: BrowserSessionId,
+    request: BrowserHighlightRequest,
+    signal?: AbortSignal,
+  ): Promise<BrowserHighlightResult> {
+    const s = this.session(session)
+    const { handle } = this.activeTab(s)
+    signal?.throwIfAborted()
+    if (request.clear === true) {
+      this.ignoreHostFailure(handle.sendCommand(CDP_OVERLAY_HIDE_HIGHLIGHT, {}))
+      return { matched: false, cleared: true }
+    }
+    const selector = request.selector ?? ''
+    if (selector === '') {
+      throw new BrowserError('browser: highlight needs a selector, or clear: true', 'BROWSER_HIGHLIGHT_INVALID')
+    }
+    const doc = await handle.sendCommand('DOM.getDocument', {})
+    const rootId = (doc as { root?: { nodeId?: number } }).root?.nodeId
+    if (typeof rootId !== 'number') {
+      throw new BrowserError('browser: could not read the document root', 'BROWSER_HIGHLIGHT_FAILED')
+    }
+    const found = await handle.sendCommand('DOM.querySelector', { nodeId: rootId, selector })
+    const nodeId = (found as { nodeId?: number }).nodeId ?? 0
+    if (nodeId === 0) return { matched: false, cleared: false }
+    let box: { x: number; y: number; width: number; height: number } | undefined
+    try {
+      const model = await handle.sendCommand('DOM.getBoxModel', { nodeId })
+      const quad = (model as { model?: { content?: number[] } }).model?.content
+      if (Array.isArray(quad) && quad.length >= 8) {
+        const xs = [quad[0], quad[2], quad[4], quad[6]]
+        const ys = [quad[1], quad[3], quad[5], quad[7]]
+        const x = Math.min(...xs)
+        const y = Math.min(...ys)
+        box = { x, y, width: Math.max(...xs) - x, height: Math.max(...ys) - y }
+      }
+    } catch { /* a zero-size element has no box model; the box is still highlighted */ }
+    await handle.sendCommand(CDP_OVERLAY_ENABLE, {})
+    await handle.sendCommand(CDP_OVERLAY_HIGHLIGHT_NODE, {
+      nodeId,
+      highlightConfig: {
+        showInfo: true,
+        contentColor: { r: 77, g: 107, b: 254, a: 0.28 },
+        borderColor: { r: 77, g: 107, b: 254, a: 0.9 },
+      },
+    })
+    this.record(s, 'highlight', { selector }, true, { result: `node ${nodeId}` })
+    return { matched: true, cleared: false, nodeId, ...box !== undefined ? { box } : {} }
+  }
+
+
+  /** Print the active tab to a PDF file (Chrome's "Save as PDF"). */
+  async pdf(
+    session: BrowserSessionId,
+    request: BrowserPdfRequest,
+    signal?: AbortSignal,
+  ): Promise<BrowserPdfResult> {
+    const s = this.session(session)
+    const { handle } = this.activeTab(s)
+    signal?.throwIfAborted()
+    // Resolve first: a bad path must fail before we spend time printing.
+    const target = resolveWritePath(request.savePath, this.writeRoots)
+    // Electron's debugger does not implement CDP `Page.printToPDF`, so a host
+    // that can print natively does it and hands back base64. Paper size arrives
+    // in inches; Electron wants microns.
+    const timeoutMs = 60_000
+    const printOnce = async (): Promise<string> => {
+      if (handle.printToPdf !== undefined) {
+        const options: Record<string, unknown> = {
+          // Backgrounds off by default would print dark pages as white paper.
+          printBackground: request.printBackground !== false,
+          landscape: request.landscape === true,
+        }
+        if (request.paperWidth !== undefined || request.paperHeight !== undefined) {
+          options.pageSize = {
+            width: Math.round((request.paperWidth ?? 8.5) * 25_400),
+            height: Math.round((request.paperHeight ?? 11) * 25_400),
+          }
+        }
+        const printed = await handle.printToPdf(options)
+        return printed.base64
+      }
+      const params: Record<string, unknown> = {
+        printBackground: request.printBackground !== false,
+        landscape: request.landscape === true,
+      }
+      if (request.paperWidth !== undefined) params.paperWidth = request.paperWidth
+      if (request.paperHeight !== undefined) params.paperHeight = request.paperHeight
+      const result = await handle.sendCommand(CDP_PAGE_PRINT_TO_PDF, params)
+      return typeof result.data === 'string' ? result.data : ''
+    }
+    const data = await withTimeout(printOnce(), timeoutMs, signal, `browser: pdf timed out after ${timeoutMs}ms`)
+    if (data === '') {
+      throw new BrowserError('browser: printToPDF returned no data', 'BROWSER_PDF_FAILED')
+    }
+    const bytes = Buffer.from(data, 'base64')
+    writeFileSync(target, bytes)
+    this.record(s, 'pdf', { savePath: request.savePath, landscape: request.landscape === true }, true, { result: `${bytes.length} bytes` })
+    return { path: request.savePath, bytes: bytes.length }
+  }
+
+
   async screenshot(
     session: BrowserSessionId,
     request?: { readonly fullPage?: boolean; readonly savePath?: string },
@@ -2372,6 +2584,25 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return this.localTaskInfo(s)
   }
 
+  /**
+   * Mirror one task's Agent todo list into the host so the floating orb can
+   * render it. The list is the DSH session projection for that task's session;
+   * only this side can read it, and only the host can reach the chrome.
+   *
+   * Unknown task keys are still stored: an Agent usually writes its plan before
+   * it opens a page, and the orb should show that plan the moment the task has a
+   * view rather than wait for the next write.
+   */
+  async pushTaskTodos(taskKey: string, todos: readonly BrowserTaskTodo[]): Promise<void> {
+    this.taskTodos.set(taskKey, todos)
+    if (typeof this.host.setTaskTodos !== 'function') return
+    // 只在「这个任务真的开过浏览器」时才转发：宿主 RPC 的第一步是 ready()，
+    // 而 ready() 会 spawn 一个 Electron 子进程 —— 一个和浏览器无关的 todo_write
+    // 不该把几百 MB 的宿主拉起来。缓存照存，open() 会给新会话补推。
+    if (!this.sessionsByTask.has(taskKey)) return
+    await this.host.setTaskTodos(taskKey, todos).catch(() => undefined)
+  }
+
   /** Hand control to the user or return it to Agent-driven actions. */
   async setHandoff(session: BrowserSessionId, state: BrowserHandoffState): Promise<BrowserTaskInfo> {
     return this.updateTask(session, state === 'waiting-user'
@@ -2474,6 +2705,35 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
+  /**
+   * Put the shared window on screen and raise it. With no session yet this
+   * opens the default one, which spawns the host and creates the first view —
+   * that is what makes the window appear. With a session already open the
+   * window exists, so it only has to be raised.
+   */
+  async ensureWindowVisible(): Promise<void> {
+    // With no session yet this opens the default one. Its handle is lazy —
+    // `createView` only records a deferred view — so the raise below is ALSO
+    // what spawns the host and puts the window on screen. Returning right after
+    // `open()` would leave the window to appear whenever some later call
+    // happened to materialize the view.
+    if (this.sessions.size === 0) await this.open()
+    for (const s of this.sessions.values()) {
+      const tab = s.tabs[s.activeIndex] ?? s.tabs[0]
+      if (tab === undefined) continue
+      if (tab.handle.focusWindow !== undefined) await tab.handle.focusWindow()
+      break
+    }
+    // 「把窗口带出来」也是「有人要看了」——顺手把手里存的计划补推一遍。
+    // 宿主重启会丢掉它内存里那份，而桥接只在清单**变化**时推；没有这一步，
+    // 重启后球上会一直空着，直到 Agent 再写一次 todo（review 报的 M1）。
+    for (const [taskKey, todos] of this.taskTodos) {
+      if (!this.sessionsByTask.has(taskKey)) continue
+      if (typeof this.host.setTaskTodos !== 'function') break
+      await this.host.setTaskTodos(taskKey, todos).catch(() => undefined)
+    }
+  }
+
   /** Close the session and destroy all its views. Idempotent. */
   close(session: BrowserSessionId): Promise<void> {
     const existing = this.sessions.get(session)
@@ -2487,6 +2747,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
       }
       if (replacement === undefined) {
         this.taskStates.delete(existing.taskKey)
+        // 这张表和 taskStates 一样是「每个任务一条」，关掉最后一个会话就该回收。
+        this.taskTodos.delete(existing.taskKey)
       }
     }
     return Promise.resolve()
@@ -2588,8 +2850,24 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     const script = `(() => {
       if (location.href !== ${JSON.stringify(record.url)}) return { stale: 'url changed' }
+      // 框架里的元素：先进入对应的同源 iframe，坐标再加上框架自己的矩形。
+      const frameIndex = ${JSON.stringify(target.frame ?? null)}
+      let scope = document
+      let dx = 0
+      let dy = 0
+      if (frameIndex !== null) {
+        const frame = document.querySelectorAll('iframe')[frameIndex]
+        if (!frame) return { stale: 'frame missing' }
+        let inner = null
+        try { inner = frame.contentDocument } catch { inner = null }
+        if (inner === null) return { stale: 'frame is cross-origin' }
+        scope = inner
+        const fr = frame.getBoundingClientRect()
+        dx = fr.left
+        dy = fr.top
+      }
       let el
-      try { el = document.querySelector(${JSON.stringify(target.path)}) } catch { return { stale: 'selector invalid' } }
+      try { el = scope.querySelector(${JSON.stringify(target.path)}) } catch { return { stale: 'selector invalid' } }
       if (!el || el.closest('[data-dsh-browser-chrome]')) return { stale: 'element missing' }
       const fingerprint = [
         el.tagName,
@@ -2606,8 +2884,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
       if (rect.width < 4 || rect.height < 4 || style.visibility === 'hidden' || style.display === 'none') return { stale: 'element hidden' }
       const root = document.documentElement
       return {
-        x: Math.round(rect.x + rect.width / 2),
-        y: Math.round(rect.y + rect.height / 2),
+        x: Math.round(rect.x + rect.width / 2 + dx),
+        y: Math.round(rect.y + rect.height / 2 + dy),
         scrollX: window.scrollX,
         scrollY: window.scrollY,
         maxX: Math.max(0, root.scrollWidth - window.innerWidth),

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

@@ -24,7 +24,7 @@ import { createServer, type Server, type Socket } from 'node:net'
 import { fileURLToPath } from 'node:url'
 import type { ChromeHostEvent, ElectronBrowserViewHost, ElectronViewHandle } from './provider.ts'
 import { BrowserError } from '../browser/types.ts'
-import type { BrowserTaskInfo, BrowserTaskUpdate, ExportedCookie } from '../browser/types.ts'
+import type { BrowserTaskInfo, BrowserTaskTodo, BrowserTaskUpdate, ExportedCookie } from '../browser/types.ts'
 
 /** How long to wait for the child to signal readiness before failing. */
 const READY_TIMEOUT_MS = 20_000
@@ -294,7 +294,8 @@ class ElectronChildClient {
     delete env.NODE_OPTIONS
     // The chrome's world is the child's choice, so it travels as an argument.
     const childArgs = [
-      ...this.chromeWorld === 'isolated' ? ['--chrome-world', 'isolated'] : [],
+      // 缺省也按 isolated 走：主世界会把 Agent 的计划暴露给页面脚本。
+      ...this.chromeWorld === 'main' ? [] : ['--chrome-world', 'isolated'],
       ...this.fingerprintArgs,
     ]
     this.child = spawn(electron, [hostMainPath, '--rpc-port', String(port), ...childArgs], {
@@ -481,6 +482,31 @@ class RemoteView implements ElectronViewHandle {
     return this.client.call<{ base64: string; width: number; height: number }>('capture', { viewId: this.id }, RPC_TRANSFER_TIMEOUT_MS)
   }
 
+  /**
+   * Print the view to a PDF in the child process. Electron's debugger has no
+   * `Page.printToPDF`, so this is the only working print path; the bytes cross
+   * the RPC socket base64-encoded.
+   */
+  printToPdf(options: Record<string, unknown>): Promise<{ base64: string }> {
+    return this.client.call<{ base64: string }>('printToPdf', { viewId: this.id, options }, RPC_TRANSFER_TIMEOUT_MS)
+  }
+
+  /**
+   * Run a snippet in the world the *page's* injected chrome lives in.
+   *
+   * In isolated mode (the default) the chrome's globals are not reachable from
+   * the page's own world, and creating a world with the same name from here
+   * yields a different, empty context — the host has to resolve its own.
+   */
+  chromeWorldEval(expression: string): Promise<{ result?: { value?: unknown } }> {
+    return this.client.call<{ result?: { value?: unknown } }>('chromeWorldEval', { viewId: this.id, expression }, RPC_QUERY_TIMEOUT_MS)
+  }
+
+  /** Raise the child's window (show + restore + focus). */
+  focusWindow(): Promise<void> {
+    return this.client.call<Record<string, never>>('focusWindow', { viewId: this.id }, RPC_COMMAND_TIMEOUT_MS).then(() => undefined)
+  }
+
   /** Export the session's cookies (login state). */
   flushAuth(): Promise<ExportedCookie[]> {
     return this.client.call<{ cookies: ExportedCookie[] }>('flushAuth', { viewId: this.id }, RPC_COMMAND_TIMEOUT_MS).then(r => r.cookies)
@@ -819,6 +845,14 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     return result.task ?? undefined
   }
 
+  /** Mirror one task's Agent todo list into the self-hosted workspace. */
+  async setTaskTodos(key: string, todos: readonly BrowserTaskTodo[]): Promise<void> {
+    await this.ready()
+    const client = this.client
+    if (client === undefined) throw new Error('browser host unavailable')
+    await client.call<Record<string, never>>('setTaskTodos', { key, todos }, RPC_QUERY_TIMEOUT_MS)
+  }
+
   /** Shut the child and the RPC server down. */
   dispose(): void {
     this.disposed = true
@@ -933,6 +967,19 @@ export class DeferredRemoteView implements ElectronViewHandle {
     return this.withView(view => view.sendCommand(method, params), settle, method)
   }
 
+  async printToPdf(options: Record<string, unknown>): Promise<{ base64: string }> {
+    return this.withView(view => view.printToPdf(options))
+  }
+
+  /** Evaluate in the injected chrome's own world (see the view-level method). */
+  async chromeWorldEval(expression: string): Promise<{ result?: { value?: unknown } }> {
+    return this.withView(view => view.chromeWorldEval(expression))
+  }
+
+  async focusWindow(): Promise<void> {
+    return this.withView(view => view.focusWindow())
+  }
+
   async download(url: string, savePath: string): Promise<void> {
     return this.withView(view => view.download(url, savePath))
   }