dsh-browser-plus 0.5.0 → 0.5.1

package/lib/browser-electron/page-chrome.js

@@ -89,6 +89,34 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         '#taskPanel .task-meta { color:#b8c5d6; }',
         '#taskPanel .task-latest { color:#acd0ff; }',
         '#taskPanel .task-error { color:#ffb1b1; }',
+        // ── 悬浮球：Agent 现在在做什么 ─────────────────────────────────────────────
+        // 宿主整层是 pointer-events:none，交互元素各自开回来 —— 漏了这一句球就只是画在那里：
+        // 拖不动、悬停也不出卡片（用户实测报「拖不动」就是它）。
+        '#orb { pointer-events:auto; position:fixed; right:18px; bottom:18px; width:44px; height:44px; z-index:2147483000; display:grid; place-items:center; box-sizing:border-box; border:1px solid rgba(255,255,255,.14); border-radius:50%; background:#292a2d; color:#e8eaed; cursor:pointer; box-shadow:0 1px 2px rgba(0,0,0,.5),0 8px 20px rgba(0,0,0,.34); opacity:.62; transition:opacity .18s ease,background .18s ease,border-color .18s ease; }',
+        '#orb:hover, #orb:focus-visible, #orb.dragging { opacity:1; background:#35363a; border-color:rgba(255,255,255,.24); }',
+        '#orb .orb-mark { width:21px; height:21px; opacity:.88; }',
+        '#orb .orb-ring { position:absolute; inset:-3px; border-radius:50%; border:2px solid transparent; border-top-color:#8ab4f8; border-right-color:#8ab4f8; opacity:0; transition:opacity .18s ease; animation:dshOrbSpin .85s linear infinite; }',
+        '#orb.working .orb-ring { opacity:1; }',
+        '@keyframes dshOrbSpin { to { transform:rotate(360deg); } }',
+        '#orb .orb-badge { position:absolute; right:-3px; bottom:-3px; box-sizing:border-box; min-width:17px; height:17px; padding:0 4px; border-radius:9px; background:#5f6368; color:#fff; font:600 10px/17px -apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif; text-align:center; box-shadow:0 0 0 2px #202124; }',
+        '#orb .orb-badge:empty { display:none; }',
+        '#orb.done .orb-badge { background:#34a853; }',
+        '#orb.failed .orb-badge { background:#d93025; }',
+        '#orb.waiting .orb-badge { background:#f9ab00; color:#202124; }',
+        '#orbCard { pointer-events:auto; position:fixed; right:18px; bottom:74px; width:308px; max-height:342px; z-index:2147483000; display:none; flex-direction:column; overflow:hidden; border:1px solid #3c4043; border-radius:10px; background:#292a2d; color:#e8eaed; box-shadow:0 8px 24px rgba(0,0,0,.5); font:12px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif; }',
+        '#orbCard.open { display:flex; }',
+        '#orbCard .orb-head { flex:none; display:flex; align-items:baseline; justify-content:space-between; gap:8px; padding:9px 12px; border-bottom:1px solid #3c4043; font-weight:500; }',
+        '#orbCard .orb-task { min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; color:#9aa0a6; font-weight:400; font-size:11px; }',
+        '#orbCard .orb-list { overflow:auto; padding:6px 0; }',
+        '#orbCard .orb-item { display:grid; grid-template-columns:16px minmax(0,1fr); column-gap:8px; align-items:start; padding:5px 12px; }',
+        '#orbCard .orb-mark { display:grid; place-items:center; width:16px; height:16px; color:#9aa0a6; font-size:11px; }',
+        '#orbCard .orb-item.in_progress .orb-mark { color:#8ab4f8; }',
+        '#orbCard .orb-item.completed .orb-mark { color:#81c995; }',
+        '#orbCard .orb-item.completed .orb-text { color:#9aa0a6; }',
+        '#orbCard .orb-text { min-width:0; overflow-wrap:anywhere; }',
+        '#orbCard .orb-spin { width:10px; height:10px; border:1.5px solid transparent; border-top-color:#8ab4f8; border-right-color:#8ab4f8; border-radius:50%; animation:dshOrbSpin .9s linear infinite; }',
+        '#orbCard .orb-foot { flex:none; padding:8px 12px; border-top:1px solid #3c4043; color:#8ab4f8; font-size:11px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }',
+        '#orbCard .orb-empty { padding:10px 12px; color:#9aa0a6; }',
         '#trail #trailList { flex:1; overflow-y:auto; padding:8px 12px; }',
         '#trail .activity-day { color:#accbff; font:11px/1.4 -apple-system,BlinkMacSystemFont,"SF Pro Display","Segoe UI",system-ui,sans-serif; text-align:center; margin:6px 0 5px; }',
         '#trail .activity-item { transition:background .12s ease; position:relative; display:grid; grid-template-columns:54px 16px minmax(0,1fr); column-gap:7px; align-items:start; padding:8px 0; }',
@@ -274,14 +302,13 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
     // and 'page' is the copy that stays in the page (the popups). Popups cannot live
     // in the frame: it is 84px tall and a menu would be clipped.
     const chromeCssText = toolbarCss + '\n#toolbarRevealZone,#toolbarHide{display:none!important}'
-        // #bookmarkBar 挂在 top:84px —— 在 84px 高的 frame 里它就是把文档撑高 34px，浏览器于是画一条
-        // 滚动条（真机截图里右边那条带箭头的）。书签栏由 page 那份画（它在那边被挪到 top:0）。
-        + (surface === 'frame' ? '\n#panel, .glass-panel, #mainMenu, #findBar, #toast, #bookmarkBar { display:none !important }' : '')
+        // #bookmarkBar 现在由 frame 那份画：帧视图会跟着开关长到 118px（84 + 34），
+        // 书签栏正好落在 84..118。页面视图从 118 开始 —— 所以页面**一点都不用让位**，
+        // 站点的 position:fixed 头部也就永远不会被压住（这正是这一改动要修的）。
+        + (surface === 'frame' ? '\n#panel, .glass-panel, #mainMenu, #findBar, #toast, #orb, #orbCard { display:none !important }' : '')
         + (surface === 'page'
-            ? '\n#tabstrip, #bar, #toolbarRevealZone, #toolbarHide { display:none !important }'
-                // The page's viewport now starts where the frame ends, so the bar sits at the
-                // very top of it and the popups hang just below the frame.
-                + '\n#bookmarkBar { top:0 !important }'
+            // 书签栏由 frame 那份画，页面这份连标签栏一起藏掉，弹层挂在帧下方。
+            ? '\n#tabstrip, #bar, #bookmarkBar, #toolbarRevealZone, #toolbarHide { display:none !important }'
                 + '\n#panel, .glass-panel, #mainMenu, #findBar { top:8px !important }'
             : '');
     const toolbarHtml = [
@@ -353,6 +380,11 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         '<div class="task-head"><span>浏览器任务</span><button id="taskClose" class="task-close" type="button" aria-label="关闭任务">×</button></div>',
         '<div id="taskList"></div>',
         '</div>',
+        // 悬浮球（右下角）：Agent 正在做什么。它不属于 menus —— 页面上的点击不该关掉它。
+        '<button id="orb" type="button" aria-label="Agent 任务"><span class="orb-ring"></span>'
+            + '<svg class="orb-mark" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3.25" y="4.75" width="17.5" height="14.5" rx="3.25"></rect><path d="M3.25 9.4h17.5"></path><circle cx="6.15" cy="7.05" r=".9" fill="currentColor" stroke="none"></circle><circle cx="8.75" cy="7.05" r=".9" fill="currentColor" stroke="none"></circle></svg>'
+            + '<span class="orb-badge"></span></button>',
+        '<div id="orbCard" role="menu" aria-label="Agent 任务"><div class="orb-head"><span>Agent 任务</span><span class="orb-task"></span></div><div class="orb-list"></div><div class="orb-foot"></div></div>',
     ].join('\n');
     return [
         '(() => {',
@@ -412,10 +444,9 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         "    // 根元素高度锁成视口高、padding 算在内部，滚动条就只由真实内容决定。",
         "    // 书签栏开着时顶栏会多 34px，下移量要跟着变（否则页面会被压住一截）。",
         "    let bookmarksVisible = false",
-        "    // page 表面上工具栏画在 frame 视图里，所以页面只需要给书签栏留位置（有就 34px）。",
-        "    const chromeInset = () => CHROME_SURFACE === 'page'",
-        "      ? (bookmarksVisible ? 34 : 0)",
-        "      : 84 + (bookmarksVisible ? 34 : 0)",
+        "    // page 表面上工具栏和书签栏都画在 frame 视图里，页面视图本身就从它们下面开始，",
+        "    // 所以页面一点也不用让位（以前要让 34px，position:fixed 的头部于是被压住）。",
+        "    const chromeInset = () => CHROME_SURFACE === 'page' ? 0 : 84 + (bookmarksVisible ? 34 : 0)",
         "    // 下移量。**过渡只在第二次应用之后才补上**：chrome 每次导航都会重新注入，第一次就带",
         "    // 过渡的话，每个页面加载（书签栏开着时 0 -> 34px）都会看到内容自己往下滑一下。",
         "    let insetApplied = false",
@@ -446,6 +477,200 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         "    const tasksBtn = root.getElementById('tasksBtn')",
         "    const taskPanel = root.getElementById('taskPanel')",
         "    const taskList = root.getElementById('taskList')",
+        "    const orb = root.getElementById('orb')",
+        "    const orbCard = root.getElementById('orbCard')",
+        "",
+        "    // ── 悬浮球 ──────────────────────────────────────────────────────────────",
+        "    // 两个数据源：任务摘要（status / latestAction）与定向的 task.todos 补丁",
+        "    // （Agent 的 todo 清单）。清单**不进摘要** —— 摘要会被注入每个访问过的页面的主世界。",
+        "    const taskTodosCache = new Map()",
+        "    const orbBadge = orb instanceof HTMLElement ? orb.querySelector('.orb-badge') : null",
+        "    const orbCardTask = orbCard instanceof HTMLElement ? orbCard.querySelector('.orb-task') : null",
+        "    const orbCardList = orbCard instanceof HTMLElement ? orbCard.querySelector('.orb-list') : null",
+        "    const orbCardFoot = orbCard instanceof HTMLElement ? orbCard.querySelector('.orb-foot') : null",
+        "    let orbCardTimer = null",
+        "    const orbTask = () => {",
+        "      const list = Array.isArray(window.__dshTasks) ? window.__dshTasks : []",
+        "      return list.find(task => task && task.key === chromeSelectedTaskKey) || list.find(task => task && task.active === true) || list[0]",
+        "    }",
+        "    let orbRenderSignature = null",
+        "    const renderOrb = () => {",
+        "      if (!(orb instanceof HTMLElement)) return",
+        "      const task = orbTask()",
+        "      const key = task && typeof task.key === 'string' ? task.key : ''",
+        "      const todos = key !== '' && Array.isArray(taskTodosCache.get(key)) ? taskTodosCache.get(key) : []",
+        "      const status = task && typeof task.status === 'string' ? task.status : 'idle'",
+        "      // 清单整表重建会把人的滚动位置弹回顶部、让转圈动画从头开始 —— 内容没变就整段跳过。",
+        "      const signature = key + '\u0001' + status + '\u0001' + (task && task.latestAction ? task.latestAction : '') + '\u0001' + todos.map(item => (item && item.status) + ':' + (item && item.content)).join('\u0002')",
+        "      if (signature === orbRenderSignature) return",
+        "      orbRenderSignature = signature",
+        "      const running = todos.some(item => item && item.status === 'in_progress')",
+        "      // 终态优先：Agent 的清单里通常有一条 in_progress，若让 running 盖过 failed/waiting-user，",
+        "      // 失败和「等你操作」就永远看不到（球一直转圈）。",
+        "      const settled = status === 'failed' || status === 'waiting-user'",
+        "      const working = status === 'running' || (running && !settled)",
+        "      const completed = todos.filter(item => item && item.status === 'completed').length",
+        "      // 清单被截断到上限时（与桥接 normalize 的 40 一致），最后那些可能没送进来 ——",
+        "      // 不能凭前 40 条就宣布「全部完成」。",
+        "      const capped = todos.length >= 40",
+        "      const allDone = todos.length > 0 && completed === todos.length && !capped",
+        "      orb.classList.toggle('working', working)",
+        "      orb.classList.toggle('done', !working && allDone)",
+        "      orb.classList.toggle('failed', !working && status === 'failed')",
+        "      orb.classList.toggle('waiting', !working && status === 'waiting-user')",
+        "      if (orbBadge) {",
+        "        // 角标只在有话要说时出现：进度、完成、失败、等你。空闲就是干净的一个球。",
+        "        if (working) orbBadge.textContent = todos.length > 0 ? String(completed) + '/' + String(todos.length) + (capped ? '+' : '') : ''",
+        "        else if (status === 'failed') orbBadge.textContent = '!'",
+        "        else if (status === 'waiting-user') orbBadge.textContent = '‖'",
+        "        else if (allDone) orbBadge.textContent = '✓'",
+        "        else orbBadge.textContent = ''",
+        "      }",
+        "      // 没有 label 时**不要**退回原始 key（session-6012f8c2-… 是内部键，给人看的东西）。",
+        "      if (orbCardTask) orbCardTask.textContent = task && typeof task.label === 'string' ? task.label : ''",
+        "      if (orbCardList) {",
+        "        orbCardList.textContent = ''",
+        "        if (todos.length === 0) {",
+        "          const empty = document.createElement('div')",
+        "          empty.className = 'orb-empty'",
+        "          empty.textContent = working ? '正在执行浏览器操作…' : '暂无任务清单'",
+        "          orbCardList.append(empty)",
+        "        } else {",
+        "          for (const item of todos) {",
+        "            const state = item && item.status === 'completed' ? 'completed' : item && item.status === 'in_progress' ? 'in_progress' : 'pending'",
+        "            const row = document.createElement('div')",
+        "            row.className = 'orb-item ' + state",
+        "            const mark = document.createElement('span')",
+        "            mark.className = 'orb-mark'",
+        "            if (state === 'in_progress') { const spin = document.createElement('span'); spin.className = 'orb-spin'; mark.append(spin) }",
+        "            else mark.textContent = state === 'completed' ? '✓' : '○'",
+        "            const text = document.createElement('span')",
+        "            text.className = 'orb-text'",
+        "            text.textContent = item && typeof item.content === 'string' ? item.content : ''",
+        "            row.append(mark, text)",
+        "            orbCardList.append(row)",
+        "          }",
+        "        }",
+        "      }",
+        "      if (orbCardFoot) {",
+        "        const latest = task && typeof task.latestAction === 'string' ? task.latestAction : ''",
+        "        orbCardFoot.textContent = working && latest !== '' ? '现在执行 · ' + latest : allDone ? '全部完成' : status === 'waiting-user' ? '等待你操作' : status === 'failed' ? '上次执行失败' : ''",
+        "        orbCardFoot.style.display = orbCardFoot.textContent === '' ? 'none' : ''",
+        "      }",
+        "      // 列表重建后卡片高度可能变了（缩略图补丁 5Hz 也会走到这里）—— 开着的话重新贴一次球，",
+        "      // 否则卡片长高会往下压住球（c1f6291 修的那个现象换了个触发路径）。",
+        "      try { if (orbCard instanceof HTMLElement && orbCard.classList.contains('open')) placeOrbCard() } catch { /* placeOrbCard 还没定义 */ }",
+        "    }",
+        "    // 悬浮球可拖动，位置交给宿主保存（chrome-prefs.json）—— 存在页面里会按源丢。",
+        "    let orbPos = null",
+        "    let orbDraggedAt = 0",
+        "    // 悬浮球**不随页面缩放变大变小**：它的大小是本地 px，宿主那层 zoom=1/缩放 正好抵消掉",
+        "    // （实测 100% 与 130% 下屏幕上都是 44px）。但坐标有两套 —— 事件与 rect 是页面 px，",
+        "    // style.left/top 是本地 px —— 混用就会拖动跳、夹取偏、卡片错位。",
+        "    const orbScale = () => { try { return typeof chromeScale === 'function' ? chromeScale() : 1 } catch { return 1 } }",
+        "    const clampOrbPos = (x, y) => {",
+        "      const s = orbScale()",
+        "      const maxX = Math.max(8, window.innerWidth * s - (orb instanceof HTMLElement ? orb.offsetWidth : 44) - 8)",
+        "      const maxY = Math.max(8, window.innerHeight * s - (orb instanceof HTMLElement ? orb.offsetHeight : 44) - 8)",
+        "      return { x: Math.min(Math.max(8, x), maxX), y: Math.min(Math.max(8, y), maxY) }",
+        "    }",
+        "    const applyOrbPos = () => {",
+        "      if (!(orb instanceof HTMLElement)) return",
+        "      if (orbPos === null) { orb.style.left = ''; orb.style.top = ''; orb.style.right = ''; orb.style.bottom = ''; return }",
+        "      // 存下来的坐标是在**当时那个窗口**里量出来的：窗口变小、换显示器、恢复最大化之后",
+        "      // 它可能已经在屏幕外 —— 那就再也拖不回来了（而且位置还会一直存在 chrome-prefs.json 里）。",
+        "      orbPos = clampOrbPos(orbPos.x, orbPos.y)",
+        "      orb.style.left = Math.round(orbPos.x) + 'px'",
+        "      orb.style.top = Math.round(orbPos.y) + 'px'",
+        "      orb.style.right = 'auto'",
+        "      orb.style.bottom = 'auto'",
+        "    }",
+        "    const emitOrbMove = (x, y) => {",
+        "      if (bindingToken === '') return",
+        "      try { const binding = window.__dshBrowserTaskAction; if (typeof binding === 'function') binding(JSON.stringify({ type: 'orb-move', x, y, token: bindingToken })) } catch { /* host unavailable */ }",
+        "    }",
+        "    let orbDrag = null",
+        "    if (orb instanceof HTMLElement) {",
+        "      orb.addEventListener('pointerdown', event => {",
+        "        if (event.button !== 0) return",
+        "        // moved 要比「按下时的起点」：拿 orb.offsetLeft 比的话，它是上一帧刚被 applyOrbPos 写进去的值，",
+        "        // 于是慢速拖动（每帧 <3px）永远不算拖动 —— 位置不落盘，松手还会误触 click。",
+        "        const s = orbScale()",
+        "        orbDrag = { startX: event.clientX, startY: event.clientY, localX: event.clientX * s, localY: event.clientY * s, dx: event.clientX * s - orb.offsetLeft, dy: event.clientY * s - orb.offsetTop, moved: false, pressed: false }",
+        "        orb.classList.add('dragging')",
+        "        // 不用 setPointerCapture：窗口级的 pointermove/pointerup 已经够了，而捕获会把后续的",
+        "        // click 重定向到球本身（标签拖动那条同款教训）。",
+        "      })",
+        "      window.addEventListener('pointermove', event => {",
+        "        // 在窗口外松手收不到 pointerup（pointercancel 也不保证）—— 不看 buttons 的话，",
+        "        // 鼠标一回到页面，球就会在没按任何键的情况下跟着光标跑。",
+        "        // 但**不能**见 0 就收尾：合成输入（离屏测试、CDP）的 pointermove 常常不带 buttons，",
+        "        // 那会把正常拖动也打断。所以只在「这次拖动曾经观察到按下」之后才认这个信号。",
+        "        if (orbDrag === null) return",
+        "        if (event.buttons !== 0) orbDrag.pressed = true",
+        "        else if (orbDrag.pressed) { endOrbDrag(); return }",
+        "        const s = orbScale()",
+        "        const spot = clampOrbPos(event.clientX * s - orbDrag.dx, event.clientY * s - orbDrag.dy)",
+        "        const x = spot.x",
+        "        const y = spot.y",
+        "        if (Math.abs(event.clientX * s - orbDrag.localX) > 3 || Math.abs(event.clientY * s - orbDrag.localY) > 3) orbDrag.moved = true",
+        "        orbPos = { x, y }",
+        "        applyOrbPos()",
+        "        if (orbDrag.moved && orbCard instanceof HTMLElement) orbCard.classList.remove('open')",
+        "      })",
+        "      const endOrbDrag = () => {",
+        "        if (orbDrag === null) return",
+        "        const moved = orbDrag.moved",
+        "        orbDrag = null",
+        "        orb.classList.remove('dragging')",
+        "        if (!moved) return",
+        "        orbDraggedAt = Date.now()",
+        "        if (orbPos !== null) emitOrbMove(orbPos.x, orbPos.y)",
+        "      }",
+        "      window.addEventListener('pointerup', endOrbDrag)",
+        "      window.addEventListener('pointercancel', endOrbDrag)",
+        "      // 在别的窗口/桌面上松手时，失焦是最可靠的信号（那时连 pointerup 都收不到）。",
+        "      window.addEventListener('blur', endOrbDrag)",
+        "      // 窗口一变形：已存的坐标要重新夹一次；卡片开着的话它也要跟着球重新定位。",
+        "      window.addEventListener('resize', () => { applyOrbPos(); if (orbCard instanceof HTMLElement && orbCard.classList.contains('open')) placeOrbCard() })",
+        "    }",
+        "    const placeOrbCard = () => {",
+        "      if (!(orb instanceof HTMLElement) || !(orbCard instanceof HTMLElement)) return",
+        "      const s = orbScale()",
+        "      const vw = window.innerWidth * s",
+        "      const vh = window.innerHeight * s",
+        "      // 视口比卡片还矮/还窄时（小窗口、分屏），先把卡片压到放得下再量 —— 否则它会",
+        "      // 被夹在 8..vh-8 之间，正好盖住贴底的球（review 报的 #10）。",
+        "      orbCard.style.maxHeight = Math.max(120, vh - 24) + 'px'",
+        "      orbCard.style.width = Math.max(160, Math.min(308, vw - 16)) + 'px'",
+        "      const box = orb.getBoundingClientRect()",
+        "      const width = orbCard.offsetWidth > 0 ? orbCard.offsetWidth : 308",
+        "      const height = orbCard.offsetHeight",
+        "      const left = Math.min(Math.max(8, box.left * s + (box.width * s) / 2 - width / 2), Math.max(8, window.innerWidth * s - width - 8))",
+        "      // 球拖到上方时，卡片再往上放就会被夹到视口顶、**盖住球自己** —— 上面放不下就翻到下面。",
+        "      const gap = 8",
+        "      const above = box.top * s - gap - height",
+        "      const top = above >= gap ? above : Math.min(box.bottom * s + gap, Math.max(gap, window.innerHeight * s - height - gap))",
+        "      orbCard.style.left = Math.round(left) + 'px'",
+        "      orbCard.style.top = Math.round(top) + 'px'",
+        "      orbCard.style.right = 'auto'",
+        "      orbCard.style.bottom = 'auto'",
+        "    }",
+        "    const openOrbCard = () => {",
+        "      if (orbCardTimer !== null) { clearTimeout(orbCardTimer); orbCardTimer = null }",
+        "      if (orbCard instanceof HTMLElement) { orbCard.classList.add('open'); placeOrbCard() }",
+        "    }",
+        "    const closeOrbCardSoon = () => {",
+        "      if (orbCardTimer !== null) clearTimeout(orbCardTimer)",
+        "      orbCardTimer = setTimeout(() => { if (orbCard instanceof HTMLElement) orbCard.classList.remove('open') }, 150)",
+        "    }",
+        "    if (orb instanceof HTMLElement && orbCard instanceof HTMLElement) {",
+        "      orb.addEventListener('pointerenter', openOrbCard)",
+        "      orb.addEventListener('pointerleave', closeOrbCardSoon)",
+        "      orbCard.addEventListener('pointerenter', openOrbCard)",
+        "      orbCard.addEventListener('pointerleave', closeOrbCardSoon)",
+        "      orb.addEventListener('click', () => { if (Date.now() - orbDraggedAt < 350) return; renderOrb(); if (orbCard.classList.contains('open')) orbCard.classList.remove('open'); else openOrbCard() })",
+        "    }",
         "    const taskControl = root.getElementById('taskControl')",
         "    const taskClose = root.getElementById('taskClose')",
         "    const trailList = root.getElementById('trailList')",
@@ -1181,7 +1406,7 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         "            row.append(thumb, title, meta, recent, failure)",
         "            // 复用之后闭包里的 key 会过期 —— 点的时候从 dataset 现读（第 46 轮的教训）。",
         "            row.addEventListener('click', () => {",
-        "              const key = row.dataset.dshTaskKey",
+        "              const key = row.dataset.dshKey",
         "              if (typeof key === 'string' && key !== '') emitTaskAction(key)",
         "            })",
         "            return row",
@@ -1209,14 +1434,15 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         "    window.__dshTaskRender = renderTasks",
         "    const patchTaskRow = task => {",
         "      if (!task || typeof task !== 'object' || typeof task.key !== 'string') return false",
-        "      const row = [...taskList.children].find(candidate => candidate instanceof HTMLElement && candidate.dataset.dshTaskKey === task.key)",
+        "      const row = [...taskList.children].find(candidate => candidate instanceof HTMLElement && candidate.dataset.dshKey === task.key)",
         "      if (!(row instanceof HTMLButtonElement)) return false",
         "      const version = String(Number.isFinite(task.thumbnailVersion) ? task.thumbnailVersion : 0)",
         "      if (row.dataset.dshThumbnailVersion !== version) return false",
         "      const status = ['idle', 'running', 'waiting-user', 'failed'].includes(task.status) ? task.status : 'idle'",
         "      const control = task.control === 'human' ? 'human' : 'agent'",
         "      row.className = 'task-row status-' + status + (task.active ? ' active' : '')",
-        "      row.disabled = false",
+        "      // 与整表渲染同一条规则：当前任务的行点不动（点了也只是切到自己）。",
+        "      row.disabled = task.active === true",
         "      const state = row.querySelector('[data-dsh-task-state]')",
         "      if (state instanceof HTMLElement) state.setAttribute('aria-label', statusText(status) + (task.active ? '，当前任务' : '，后台任务'))",
         "      const label = row.querySelector('[data-dsh-task-label]')",
@@ -1565,7 +1791,11 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         "        for (const key of [...taskThumbCache.keys()]) if (!liveKeys.has(key)) taskThumbCache.delete(key)",
         "        window.__dshTrail = Array.isArray(message.trail) ? message.trail : []",
         "        window.__dshWorkspacePanels = message.panels && typeof message.panels === 'object' ? message.panels : { tasks: false, trail: false }",
+        "        const saved = message.orbPosition",
+        "        orbPos = saved && typeof saved.x === 'number' && typeof saved.y === 'number' ? { x: saved.x, y: saved.y } : null",
+        "        applyOrbPos()",
         "        renderTasks()",
+        "        renderOrb()",
         "        renderTabs()",
         "        renderTrail()",
         "        applyWorkspacePanels()",
@@ -1599,6 +1829,10 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         "          if (typeof operation.dataUrl === 'string') taskThumbCache.set(operation.key, operation.dataUrl)",
         "          const task = tasks.find(candidate => candidate && candidate.key === operation.key)",
         "          if (task) { task.thumbnailVersion = operation.version; fullTaskRender = true }",
+        "        } else if (operation.op === 'task.todos' && typeof operation.key === 'string') {",
+        "          // Agent 的任务清单：定向补丁（不进摘要），悬浮球读它。",
+        "          taskTodosCache.set(operation.key, Array.isArray(operation.todos) ? operation.todos : [])",
+        "          renderOrb()",
         "        } else if (operation.op === 'trail.append' && operation.taskKey === chromeSelectedTaskKey && operation.entry) {",
         "          const trail = Array.isArray(window.__dshTrail) ? window.__dshTrail : []",
         "          window.__dshTrail = [...trail, operation.entry]",
@@ -1644,6 +1878,7 @@ export function buildPageChromeScript(bindingToken = '', surface = 'full') {
         "      window.__dshTasks = tasks",
         "      if (fullTaskRender) renderTasks()",
         "      else if (taskPatches.length > 0) { renderTaskControl(tasks); for (const task of taskPatches) { if (!patchTaskRow(task)) { renderTasks(); break } } }",
+        "      renderOrb()",
         "      if (trailReplaced) renderTrail()",
         "      else for (const entry of trailAppends) appendTrailEntry(entry)",
         "      // 换页也要重算星标：宿主给的标签 url 是**规范化过**的（没有结尾斜杠），而收藏里",

package/lib/browser-electron/provider.d.ts

@@ -6,7 +6,7 @@
  * shell that owns the `BrowserWindow`.
  * @module dsh-browser-plus/browser-electron
  */
-import type { BrowserChallenge, BrowserClearAuthRequest, BrowserClearAuthResult, BrowserContentRequest, BrowserContentResult, BrowserDragRequest, BrowserDragResult, BrowserPointerResult, BrowserPointerTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserHandoffState, BrowserHistoryEntry, BrowserOpenOptions, BrowserOpenRequest, BrowserPressKeyRequest, BrowserProvider, BrowserRefRequest, BrowserScrapeRequest, BrowserScrapeStatus, BrowserScrollIntoViewRequest, BrowserScrollRequest, BrowserScrollResult, BrowserSessionId, BrowserSnapshotResult, BrowserSpaceInfo, BrowserTab, BrowserTaskInfo, BrowserTaskUpdate, BrowserUploadFileRequest, BrowserUploadFileResult, BrowserWaitForRequest, BrowserWaitForResult, ExportedCookie } from '../browser/types.ts';
+import type { BrowserChallenge, BrowserClearAuthRequest, BrowserClearAuthResult, BrowserContentRequest, BrowserContentResult, BrowserDragRequest, BrowserDragResult, BrowserPointerResult, BrowserPointerTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserHandoffState, BrowserHistoryEntry, BrowserOpenOptions, BrowserOpenRequest, BrowserPressKeyRequest, BrowserProvider, BrowserRefRequest, BrowserScrapeRequest, BrowserScrapeStatus, BrowserScrollIntoViewRequest, BrowserScrollRequest, BrowserScrollResult, BrowserSessionId, BrowserSnapshotResult, BrowserSpaceInfo, BrowserTab, BrowserTaskInfo, BrowserTaskUpdate, BrowserUploadFileRequest, BrowserUploadFileResult, BrowserPdfRequest, BrowserPdfResult, BrowserHighlightRequest, BrowserHighlightResult, BrowserWaitForRequest, BrowserWaitForResult, BrowserTaskTodo, ExportedCookie } from '../browser/types.ts';
 /** Stable provider id registered with `ctx.browser`. */
 export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
 /**
@@ -110,6 +110,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>;
 }
 /**
  * A CDP-capable view handle. This is the subset of Electron's
@@ -159,6 +161,24 @@ 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>;
 }
 /**
  * How the host answers a JS dialog (alert/confirm/prompt).
@@ -252,6 +272,12 @@ export interface CdpEvaluateParams {
 }
 /** CDP method for a full-page screenshot capture. */
 export declare const CDP_PAGE_CAPTURE_SCREENSHOT = "Page.captureScreenshot";
+/** CDP method that renders the current document to PDF. */
+export declare const CDP_PAGE_PRINT_TO_PDF = "Page.printToPDF";
+/** CDP methods that draw the DevTools highlight box without touching the DOM. */
+export declare const CDP_OVERLAY_ENABLE = "Overlay.enable";
+export declare const CDP_OVERLAY_HIGHLIGHT_NODE = "Overlay.highlightNode";
+export declare const CDP_OVERLAY_HIDE_HIGHLIGHT = "Overlay.hideHighlight";
 /** CDP method for runtime evaluation (the execute path). */
 export declare const CDP_RUNTIME_EVALUATE = "Runtime.evaluate";
 /**
@@ -291,6 +317,14 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     /** Stable task-key index so callers can recover a session after tool-layer state loss. */
     private readonly sessionsByTask;
     private readonly taskStates;
+    /**
+     * 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;
     private readonly httpOnly;
     private readonly snapshotMaxElements;
     private readonly contentMaxChars;
@@ -438,7 +472,7 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * Bounds the total wait; a timeout surfaces as BROWSER_WAIT_TIMEOUT.
      */
     waitForElement(session: BrowserSessionId, request: BrowserWaitForRequest, signal?: AbortSignal): Promise<BrowserWaitForResult>;
-    /** Poll one tab until the selector matches. */
+    /** Poll one tab until the selector and/or text reaches the requested state. */
     private waitForElementTab;
     /** Type into the focused element. */
     type(session: BrowserSessionId, request: {
@@ -536,6 +570,13 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     /** Drop a batch's private tabs (and their views) once the batch is over. */
     private destroyScrapeTabs;
     /** 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.
+     */
+    highlight(session: BrowserSessionId, request: BrowserHighlightRequest, signal?: AbortSignal): Promise<BrowserHighlightResult>;
+    /** Print the active tab to a PDF file (Chrome's "Save as PDF"). */
+    pdf(session: BrowserSessionId, request: BrowserPdfRequest, signal?: AbortSignal): Promise<BrowserPdfResult>;
     screenshot(session: BrowserSessionId, request?: {
         readonly fullPage?: boolean;
         readonly savePath?: string;
@@ -619,6 +660,16 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     getTask(session: BrowserSessionId): Promise<BrowserTaskInfo>;
     /** Apply one visible task state update and mirror it to a supporting host. */
     updateTask(session: BrowserSessionId, update: BrowserTaskUpdate): Promise<BrowserTaskInfo>;
+    /**
+     * 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.
+     */
+    pushTaskTodos(taskKey: string, todos: readonly BrowserTaskTodo[]): Promise<void>;
     /** Hand control to the user or return it to Agent-driven actions. */
     setHandoff(session: BrowserSessionId, state: BrowserHandoffState): Promise<BrowserTaskInfo>;
     /** Append one operation to the session's history. */
@@ -633,6 +684,13 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * @param seq - the recorded entry's sequence number to replay.
      */
     replay(session: BrowserSessionId, seq: number): Promise<void>;
+    /**
+     * 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.
+     */
+    ensureWindowVisible(): Promise<void>;
     /** Close the session and destroy all its views. Idempotent. */
     close(session: BrowserSessionId): Promise<void>;
     /** Recover the live session associated with a stable task key. */