dsh-browser-plus 0.5.0 → 0.5.1

package/lib/browser-electron/provider.js

@@ -44,6 +44,12 @@ const AGENT_INPUT_SUPPRESSION_MS = 900;
 export const ELECTRON_BROWSER_PROVIDER_ID = 'electron';
 /** 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';
 /**
@@ -196,7 +202,6 @@ export const CDP_PAGE_NAVIGATE_TO_HISTORY_ENTRY = 'Page.navigateToHistoryEntry';
 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;
 /**
@@ -327,6 +332,14 @@ export class ElectronBrowserProvider {
     /** Stable task-key index so callers can recover a session after tool-layer state loss. */
     sessionsByTask = new Map();
     taskStates = new Map();
+    /**
+     * 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.
+     */
+    taskTodos = new Map();
     httpOnly;
     snapshotMaxElements;
     contentMaxChars;
@@ -449,12 +462,24 @@ export class ElectronBrowserProvider {
                 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() });
         }
@@ -756,7 +781,7 @@ export class ElectronBrowserProvider {
         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
@@ -768,7 +793,7 @@ export class ElectronBrowserProvider {
             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(' > ')
@@ -783,42 +808,65 @@ export class ElectronBrowserProvider {
       ].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.
@@ -851,7 +899,11 @@ export class ElectronBrowserProvider {
         const snapshotId = `snapshot:${randomUUID()}`;
         const targets = new Map();
         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) {
@@ -865,6 +917,7 @@ export class ElectronBrowserProvider {
             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 } : {},
@@ -1126,27 +1179,55 @@ export class ElectronBrowserProvider {
         const s = this.session(session);
         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. */
     async waitForElementTab(s, tab, request, signal) {
         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 = 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;
@@ -1160,8 +1241,8 @@ export class ElectronBrowserProvider {
             else {
                 const value = result.value;
                 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
@@ -1171,7 +1252,8 @@ export class ElectronBrowserProvider {
             }
             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. */
     async type(session, request, signal) {
@@ -1664,6 +1746,103 @@ export class ElectronBrowserProvider {
         this.showActive(s);
     }
     /** 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, request, signal) {
+        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.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.nodeId ?? 0;
+        if (nodeId === 0)
+            return { matched: false, cleared: false };
+        let box;
+        try {
+            const model = await handle.sendCommand('DOM.getBoxModel', { nodeId });
+            const quad = model.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, request, signal) {
+        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 () => {
+            if (handle.printToPdf !== undefined) {
+                const options = {
+                    // 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 = {
+                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, request, signal) {
         const s = this.session(session);
         const { handle } = this.activeTab(s);
@@ -1932,6 +2111,26 @@ export class ElectronBrowserProvider {
         }
         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, todos) {
+        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, state) {
         return this.updateTask(session, state === 'waiting-user'
@@ -2030,6 +2229,39 @@ export class ElectronBrowserProvider {
                 throw new BrowserError(`browser: history seq ${seq} action "${entry.action}" is not replayable`, 'BROWSER_HISTORY_NOT_REPLAYABLE');
         }
     }
+    /**
+     * 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() {
+        // 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) {
         const existing = this.sessions.get(session);
@@ -2046,6 +2278,8 @@ export class ElectronBrowserProvider {
             }
             if (replacement === undefined) {
                 this.taskStates.delete(existing.taskKey);
+                // 这张表和 taskStates 一样是「每个任务一条」，关掉最后一个会话就该回收。
+                this.taskTodos.delete(existing.taskKey);
             }
         }
         return Promise.resolve();
@@ -2123,8 +2357,24 @@ export class ElectronBrowserProvider {
         }
         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,
@@ -2141,8 +2391,8 @@ export class ElectronBrowserProvider {
       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/lib/browser-electron/remote-host.d.ts

@@ -16,7 +16,7 @@
  * @module dsh-browser-plus/browser-electron/remote-host
  */
 import type { ChromeHostEvent, ElectronBrowserViewHost, ElectronViewHandle } from './provider.ts';
-import type { BrowserTaskInfo, BrowserTaskUpdate } from '../browser/types.ts';
+import type { BrowserTaskInfo, BrowserTaskTodo, BrowserTaskUpdate } from '../browser/types.ts';
 /**
  * Whether a usable Electron binary can be located right now. Cheap and local:
  * it only probes package metadata and the filesystem (no spawn, no network).
@@ -136,6 +136,8 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     getTask(key: string): Promise<BrowserTaskInfo | undefined>;
     /** Update one task summary in the self-hosted visible workspace. */
     updateTask(key: string, task: BrowserTaskUpdate): Promise<BrowserTaskInfo | undefined>;
+    /** Mirror one task's Agent todo list into the self-hosted workspace. */
+    setTaskTodos(key: string, todos: readonly BrowserTaskTodo[]): Promise<void>;
     /** Shut the child and the RPC server down. */
     dispose(): void;
 }

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

@@ -274,7 +274,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], {
@@ -475,6 +476,28 @@ class RemoteView {
     capture() {
         return this.client.call('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) {
+        return this.client.call('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) {
+        return this.client.call('chromeWorldEval', { viewId: this.id, expression }, RPC_QUERY_TIMEOUT_MS);
+    }
+    /** Raise the child's window (show + restore + focus). */
+    focusWindow() {
+        return this.client.call('focusWindow', { viewId: this.id }, RPC_COMMAND_TIMEOUT_MS).then(() => undefined);
+    }
     /** Export the session's cookies (login state). */
     flushAuth() {
         return this.client.call('flushAuth', { viewId: this.id }, RPC_COMMAND_TIMEOUT_MS).then(r => r.cookies);
@@ -793,6 +816,14 @@ export class RemoteElectronViewHost {
         const result = await client.call('updateTask', { key, task }, RPC_QUERY_TIMEOUT_MS);
         return result.task ?? undefined;
     }
+    /** Mirror one task's Agent todo list into the self-hosted workspace. */
+    async setTaskTodos(key, todos) {
+        await this.ready();
+        const client = this.client;
+        if (client === undefined)
+            throw new Error('browser host unavailable');
+        await client.call('setTaskTodos', { key, todos }, RPC_QUERY_TIMEOUT_MS);
+    }
     /** Shut the child and the RPC server down. */
     dispose() {
         this.disposed = true;
@@ -894,6 +925,16 @@ export class DeferredRemoteView {
         await settle?.();
         return this.withView(view => view.sendCommand(method, params), settle, method);
     }
+    async printToPdf(options) {
+        return this.withView(view => view.printToPdf(options));
+    }
+    /** Evaluate in the injected chrome's own world (see the view-level method). */
+    async chromeWorldEval(expression) {
+        return this.withView(view => view.chromeWorldEval(expression));
+    }
+    async focusWindow() {
+        return this.withView(view => view.focusWindow());
+    }
     async download(url, savePath) {
         return this.withView(view => view.download(url, savePath));
     }