diff --git a/.scratch/embedded-browser/PRD.md b/.scratch/embedded-browser/PRD.md
index 5f7fecdc..7f56993e 100644
--- a/.scratch/embedded-browser/PRD.md
+++ b/.scratch/embedded-browser/PRD.md
@@ -51,6 +51,8 @@ PiGUI 目前对 dev server 零认知(project registry 只有 `{id, path, display
 
 ### 5. 元素标识与载荷形状(定义在 `packages/core`)
 
+> 修订提示(2026-10-10):本节「不新增结构化附件」「落到 composer 草稿」与 `formatBrowserAnnotationPrompt` 已被标注 v2 取代,见 `.scratch/browser-annotation-v2/PRD.md` 决策 4 与 ADR-0029「修订:标注 v2」。
+
 ```ts
 type BrowserAnnotationElement = {
   index: number;               // 标记序号,与截图上的数字一致
diff --git a/CONTEXT.md b/CONTEXT.md
index 5aafbc4c..975b5bd2 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -268,6 +268,10 @@ _Avoid_: Panel, tab, view, plugin, widget
 Pace 自带的 Surface：Changes、Files、Terminal、Browser。它们与将来扩展注册的 Surface 走同一套注册表与 Rail，只是 provider 为 `builtin`。Files 是只读的 checkout 目录树加文件预览（ADR-0035）。
 _Avoid_: Core panel, native panel, first-party plugin
 
+**Browser Comment**:
+用户在 Browser Surface 的标注模式里对页面一个元素或一块区域写下的评论，保存才成立（标注 v2，ADR-0029「修订：标注 v2」）。由主进程按 Session 持有——不属于 tab 或文档，带保存时的 URL、视口与局部截图；同 URL 的新文档会重新显示它的标记，找不到元素时标为 stale。它在 composer 附件抽屉里以 `#n` 芯片列出，随下一条消息作为评论块与截图发给 Pi，发送成功即被消费。
+_Avoid_: Annotation（仅指页上标记的实现层叫法）, marker, note, design comment
+
 **Session Projection**:
 Pace 自己保存的查询模型，用来支撑 Session 列表、Analyze、状态索引、成本聚合、checkout 生命周期、恢复入口和 UI 快速渲染。它是从 Pi Session State、Session Trajectory 和 Pace checkout 管理事件同步出来的投影，不是 Pi 会话内容的权威来源。渲染层每个 Session 只保留一份，由一个 module 拥有并作为唯一写者（ADR-0044）。
 _Avoid_: Runtime truth, independent chat state, source of record
diff --git a/apps/desktop/src/pages/design-components.tsx b/apps/desktop/src/pages/design-components.tsx
index 378d4ce8..dfdb4d03 100644
--- a/apps/desktop/src/pages/design-components.tsx
+++ b/apps/desktop/src/pages/design-components.tsx
@@ -2801,7 +2801,7 @@ function ComposerAttachmentDrawerGallery() {
             />
           </div>
         </Variant>
-        <Variant caption="with comment chips — one stale">
+        <Variant caption="with comment chips — one stale, one area">
           <div className="w-96">
             <ChatPromptInput
               drawer={
@@ -2814,6 +2814,7 @@ function ComposerAttachmentDrawerGallery() {
                       warning:
                         "No longer on the page — sent as it was when saved",
                     },
+                    { id: "c3", label: "#3 Area · Hero spacing is uneven" },
                   ]}
                   commentsLabel="Browser comments"
                   items={[
diff --git a/docs/adr/0029-embedded-browser-surface.md b/docs/adr/0029-embedded-browser-surface.md
index 7c72e0b1..8a18ede1 100644
--- a/docs/adr/0029-embedded-browser-surface.md
+++ b/docs/adr/0029-embedded-browser-surface.md
@@ -2,7 +2,7 @@
 
 - 状态：Accepted
 - 日期：2026-09-03
-- 来源：`.scratch/embedded-browser/PRD.md`（决策 1–6、Spike 结论、S2 / S3 实现约束）；PR #149（S0 + S1）、#153（S2）、#154（S3）；issue #86
+- 来源：`.scratch/embedded-browser/PRD.md`（决策 1–6、Spike 结论、S2 / S3 实现约束）；PR #149（S0 + S1）、#153（S2）、#154（S3）；issue #86；v2 修订：`.scratch/browser-annotation-v2/PRD.md`、PR #451 / #452 / #454 / #455（issue #446–#450）
 
 ## 背景
 
@@ -63,6 +63,30 @@ ADR-0013 把「内嵌浏览器 + DOM 标注」定为切换 Electron 外壳的承
 - `WebContentsView` 设 `backgroundColor` 为面板底色，避免 macOS `transparent + vibrancy` 被开洞；bounds 永不覆盖 40px 表头带。
 - 每个 tab 的导航独立递增 navigationId；截图握手绑定原页面，关闭或导航后返回的旧截图作废。渲染层在切 tab、切 Session 或关闭 tab 后丢弃仍在途的 Send to composer，避免把旧页面截图送进新上下文。
 
+## 修订：标注 v2（2026-10-10）
+
+本节取代上文「标注层」与「载荷回传」中被点名的 v1 内容（「只落草稿」、整视口截图握手、composer 注入路径等）；v1 原文保留为历史，不重写。
+
+- **推翻「只落草稿」**：评论以结构化附件进入 composer 附件抽屉「Browser comments」分组（Token chip：`#n 首行摘要`，区域评论为 `#n Area · 摘要`，stale 用黄色并带说明，移除即删除）；`To composer` 按钮、`browser_capture_annotation` 整视口截图握手、`injectIntoComposer` / `composer-injections` 注入路径均已移除。发送时 composer 在用户草稿后追加 core `formatBrowserComments` 产出的评论块（替代 `formatBrowserAnnotationPrompt`）；评论截图按评论顺序排在消息图片最后、用户自己附的图片在前，Pi 收到的仍是 `string + RuntimePromptImage[]`，Gateway / Pi 零改动。`send_prompt` / 排队 follow-up / 从队列 steer 三条路径天然覆盖——评论在入队时已烤进消息。提交成功后按构建时快照的 id 列表调 `browser_consume_comments`；发送期间新存的评论保留，失败则全部保留。
+- **评论仓归主进程、Session 级**：`browser-host.ts` 每 Session 持一个评论仓，仓内顺序即 `#n`（读时重算）；每条 `BrowserComment` = 标注字段 + `tabId` / `url` / `title` / `viewport` / `stale` / `hasImage` / `createdAt`。上限 200 条（`maxSessionComments`），超出拒收并发 `comment-rejected`。新评论保存时 overlay 整层隐藏两帧再上报，主进程随即 `capturePage` 裁局部截图：标记矩形外扩 48 CSS px、最小 320×200、先平移再夹进视口；图片不进状态广播，按 id 由 `browser_comment_images` 取。关闭 tab 只移除页上标记，评论仍在仓里；关窗/退出即丢，不落盘。命令：`browser_list_comments`、`browser_settle_comments`（等在途截图落定再读，发送用它）、`browser_comment_images`、`browser_delete_comment`、`browser_consume_comments`；`browser_clear_annotations` 只清当前 tab 的评论。事件：`comments-changed`（带 revision，旧答复丢弃）、`comment-rejected`、`submit-requested`。composer 订阅读取，不持有第二份副本。
+- **跨文档保留**：新文档 `ready` 与 `did-navigate-in-page`（SPA 路由切换）时，主进程下发 `sync-annotations`：本 tab 中 URL 键（origin + pathname + search，忽略 hash）相同的评论。overlay 用 selector 唯一解析元素，解析不到时用 MutationObserver 再等最多 5s，仍失败上报 `stale`；stale 评论仍可发送（文本与保存时的截图仍有效）。页上只显示当前 URL 的标记，其他页面的评论只在 composer 里。
+- **覆盖层交互**：点击即打开已聚焦的草稿编辑器（textarea），评论必填，保存才成为标注；点已保存的元素或徽章进入编辑（带 Delete），不产生重复；一次只有一个编辑器，有未保存内容时点别处编辑器抖动而不切走。目标收敛：跳过行内装饰节点、SVG 内部与小于 8×8 的元素，优先最近的交互控件；`↑` / `↓` 沿祖先链手动微调。悬停标签 `tag.firstClass · W×H`（有 source 时加 `file:line`）。已保存标注画细轮廓 + 外侧右上角编号徽章，相邻徽章重叠时错开。模式可感知：视口内侧 2px 主题色描边 + 顶部居中标签「Click or drag to annotate · Esc to exit」。颜色取渲染层语义 token，随 `set-design-mode` / `set-annotation-palette` 下发，overlay 用 `CSS.supports` 逐个校验、不合法的回落内置默认。工具条按钮名 `Annotate`。
+- **区域框选**：标注模式下按住拖动超过 4px 进入框选，松开打开编辑器；任一边小于 4px 视为误触；Esc / pointercancel / 窗口外松开取消并吞掉随后的 click；不拦截滚动。`BrowserAnnotationElement.area`（相对锚点边框盒左上角的偏移，CSS px）存在即区域评论，`rect` 为保存时区域的视口矩形；锚点取按下点祖先链上第一个完整包含矩形且非 SVG 内部的元素，兜底 `body`；区域不带 `text`、不占有锚点（点锚点仍新建元素评论，多个区域可共享锚点）；已保存区域画虚线轮廓。格式化无论有无截图都输出 `- area: W×H at (x, y)`。
+- **键位**：
+
+  | 位置 | 键 | 行为 |
+  |---|---|---|
+  | 编辑器内 | `Enter` | 保存并继续标注 |
+  | 编辑器内 | `Shift+Enter` | 换行 |
+  | 编辑器内 | `Cmd/Ctrl+Enter` | 保存并立即发送 composer |
+  | 编辑器内 | `Esc` | 取消编辑（拖动中则取消框选） |
+  | 标注模式、编辑器未开 | `Cmd/Ctrl+Enter` | 立即发送（有 pending 评论时） |
+  | 标注模式、编辑器未开 | `Esc` | 退出标注模式 |
+  | 标注模式、编辑器未开 | `↑` / `↓` | 悬停目标切到父元素 / 回到子元素 |
+  | 任意处 | `Cmd/Ctrl+Shift+A` | 切换标注模式（页内由 overlay 监听，Pace 窗口内由 Browser 面板监听） |
+
+  与 Codex 相反（Codex 的 Enter 直发），评论框的 Enter 是保存到待发区，不与 composer 的 Enter 发送冲突。页内 `Cmd/Ctrl+Enter` 路径：overlay 在 `annotation-saved` 之后发 `submit-requested`，主进程等本 Session 在途截图落定后经浏览器事件通知渲染层，composer 自行响应——Browser 面板关着也能发。
+
 ## 已知限制
 
 宿主：
@@ -93,6 +117,14 @@ ADR-0013 把「内嵌浏览器 + DOM 标注」定为切换 Electron 外壳的承
 - 页面标题用于 tab 提示；实例名保持稳定的 Browser 序号。
 - 注入只到达当前 Session 已挂载的 composer，不排队；注入文本作为 follow-up 草稿持久化，截图不持久化，重载后只剩文本。
 
+v2 修订后：
+
+- v1 的「无单条删除；清空后序号从 1 重开……页面文档替换或关闭 tab 才丢弃对应标注」、「握手 500ms 超时」「滚出视口的标记不在图上」「注入只到达已挂载 composer」各条已由 v2 取代。
+- selector 重定位依赖页面结构稳定：`nth-of-type` 链在列表重排后可能命中错误元素——stale 只能识别「找不到」，识别不了「找错」。
+- 评论多时图片数随之增长、占用上下文；本轮不设图片数上限（仓上限仍为 200 条）。
+- 评论不跨应用重启保留（与图片附件不落盘的策略一致）。
+- 区域的截图不画框，边界只在文本里（`- area:` 行）。
+
 ## 结果
 
 - ADR-0028「Terminal / File / Browser surface 仍受 ADR-0007 冻结」修订为：Terminal 由 PR #147 解冻、Browser 由本文解冻、File 仍冻结。
@@ -105,3 +137,5 @@ ADR-0013 把「内嵌浏览器 + DOM 标注」定为切换 Electron 外壳的承
 - 渲染层组件测试覆盖 surface 五态、URL 按 Project 记忆、design mode 工具条、Project tab 组迁移与恢复、跨 tab 状态隔离、过期截图丢弃及注入口。
 - Electron E2E 追加两 tab 的打开、切换、标注隔离、徽标、重载恢复与全部关闭空态。
 - Electron E2E（`e2e/smoke/browser-surface.spec.ts`）：bounds 跟随面板、弹层换快照、`ERR_ABORTED` 不算失败、严格 CSP 页上 design mode 可用且页面读不到覆盖层、标注 → Send → composer 草稿出现模板文本与 PNG 附件。
+- 标注 v2 Vitest 覆盖 overlay 交互与区域框选（jsdom）、主进程评论仓与消费竞态、core `formatBrowserComments` 模板、composer 抽屉与提交路径。
+- 标注 v2 Electron E2E（同 `browser-surface.spec.ts`）：严格 CSP 页经 Annotate 保存两条评论、重载文档后标记随评论仓恢复；composer 出现「Browser comments」芯片；页内 Cmd/Ctrl+Enter 发出，断言消息带评论块与两张按评论顺序的截图、发送后芯片与标记被消费。另有 tab 用例覆盖标记按 tab 隔离、切回恢复与芯片随 Session 出现。
diff --git a/docs/design/chat.md b/docs/design/chat.md
index bd5f9003..e65b95ac 100644
--- a/docs/design/chat.md
+++ b/docs/design/chat.md
@@ -100,7 +100,7 @@ Branch / Location chip 都截断在 16rem 以内，44rem 宽下长分支名不
 - `ChatQueuedMessage`：队列里的一条；`presence: "none" | "enter" | "exit"` 由 `usePresenceList` 给，不要自己传 `"enter"`。只有 `pending` 的整卡 `draggable`；拖动中 `isDragging`（45% 透明），目标位 `dropTarget: "before" | "after"`（顶/底边 accent 线，由指针落在卡片上半或下半决定）。`isWithdrawn` 显示 "Withdrawn"，`isSteered` 显示 "Steered"；两者都是终态，无动作、不可拖。重排 RPC 进行中卡片不可拖、drop 忽略。Pi follow-up mode 为 `all` 时整卡不可拖、drop 忽略。
 - `ModelSelectorControl`：选中项来自 projection；冷会话缺少目录时异步读取 `list_available_model_controls`，不启动 Agent，读取失败不阻塞历史或发送。Session 创建期间 projection 还没有自己的 controls，此时选中项回落到 draft 提交时写入的 `last model selection`，目录则复用本次 renderer 已读到的那份，选择器因此在 Draft → Live 交接中不会消失；创建期 `isDisabled`。真正切换模型会准备运行环境。`isDisabled` 在队列模式或提交等待期间为 true；`visibleModels` 空数组 = 全显。当前选中模型即使被隐藏也保留并标注。没有第二个模型选择器，失败卡里的 `modelControl` 插槽也用它。
 - `ComposerInsertMenu`：`catalogs` 是通用分组目录（`ComposerInsertCatalog[]`：`id` / `label` / `icon` / `searchLabel` / `emptyText` / `items`），一级菜单先是 Add files，再按传入顺序列出非空组（空组隐藏），点组打开 `CommandPalette` 按 label/description 搜索，选中经 `onPick(catalogId, itemId)` 回给调用方。菜单本身不携带任何领域概念——skills/prompts/extension commands 的分组和 token 插入由 `entities/prompt-command` 的 `insertCatalogs` / `commandToken` 组装，提交前的校验走 `validateCommandSubmit`（拦 Pi TUI 内置命令和排队模式下的 extension 命令）。`/` 补全的数据来自 `list_prompt_commands`（`usePromptCommands`：草稿按项目根静态解析，会话内走运行时 catalog）。
-- `ComposerAttachmentDrawer`：`items` 与 `comments` 都为空返回 null；图片走 Thumbnail，文本文件与 `comments`（结构化批注，如 Browser comments）各走一行 Token，stale 批注用 `warning` 上黄色（`color="yellow"` + `description`）。附件逻辑（大小上限、拒收文案、拼进 prompt，含 `appendix` 追加块）全在 `composer-attachment-logic.ts`，从 `composer-attachments/index.ts` 导入，不在页面里重算。
+- `ComposerAttachmentDrawer`：`items` 与 `comments` 都为空返回 null；图片走 Thumbnail，文本文件与 `comments`（结构化批注，如 Browser comments）各走一行 Token，stale 批注用 `warning` 上黄色（`color="yellow"` + `description`）。Browser comments 芯片标签为 `#n 摘要`，区域评论为 `#n Area · 摘要`。附件逻辑（大小上限、拒收文案、拼进 prompt，含 `appendix` 追加块）全在 `composer-attachment-logic.ts`，从 `composer-attachments/index.ts` 导入，不在页面里重算。
 
 `ComposerInsertCatalog` 可提供静态 `items` 或异步 `search(query)`。静态空组隐藏，异步组始终可见，打开后按输入检索。搜索框阻止点击冒泡，避免 portal 内点击被 Composer 的空白处点击逻辑抢走焦点。Design 页包含异步文件搜索示例。
 
diff --git a/docs/design/workspace.md b/docs/design/workspace.md
index 25cab897..23c95ab4 100644
--- a/docs/design/workspace.md
+++ b/docs/design/workspace.md
@@ -29,7 +29,7 @@
 
 ## BrowserSurface
 
-复合件：根只持 `state`，经 context 把状态交给子件。`state.kind` 为 `"narrow" | "unsupported" | "empty" | "live" | "error"`；`empty` 可用 `phase: "idle" | "initializing" | "opening" | "blank"`（无 phase 即 idle）。只有 `live` 渲染 viewport 占位（其 rect 驱动原生 `WebContentsView`）；`narrow` / `unsupported` 不画 chrome；零 tab 的 empty 显示 Astryx `EmptyState`。页面组合 `Tabs`（实例条）+ `Toolbar`（地址/导航/Annotate 标注模式）+ `Viewport`（占位、快照、notice、空态）。弹层出现时把 `snapshot` 传给 Viewport。
+复合件：根只持 `state`，经 context 把状态交给子件。`state.kind` 为 `"narrow" | "unsupported" | "empty" | "live" | "error"`；`empty` 可用 `phase: "idle" | "initializing" | "opening" | "blank"`（无 phase 即 idle）。只有 `live` 渲染 viewport 占位（其 rect 驱动原生 `WebContentsView`）；`narrow` / `unsupported` 不画 chrome；零 tab 的 empty 显示 Astryx `EmptyState`。页面组合 `Tabs`（实例条）+ `Toolbar`（地址/导航/Annotate 标注模式）+ `Viewport`（占位、快照、notice、空态）。弹层出现时把 `snapshot` 传给 Viewport。页内覆盖层支持点击元素写评论与拖动框选区域（超过 4px 生效）；覆盖层活在页面的 closed Shadow DOM 里，不是 `shared/ui` 组件。
 
 ```tsx
 <BrowserSurface state={state}>
diff --git a/docs/self-built-ui.md b/docs/self-built-ui.md
index f70a34fb..6eae8a77 100644
--- a/docs/self-built-ui.md
+++ b/docs/self-built-ui.md
@@ -40,7 +40,7 @@
 | composer-attachments | `shared/ui/composer-attachments/` | Composer「Add to prompt」菜单 + 附件抽屉(#98,2026-08-14 原型探索 Shelf 胜出):footer 左侧 Plus；一级仅 Add files / Use skill / Chat commands / Use plugin，技能与插件通过 Astryx CommandPalette 搜索，技能保留 SDK 说明，插件只规范展示名称、保留原插入标识；图片 Thumbnail、文本 Token;文本附件内联进 prompt,图片走 Gateway `images` 通道;抽屉还承载 Browser comments 芯片(stale 显示 warning),comments 作为 appendix 拼进 prompt 文本、截图排在附件图之后;决策记录 `.scratch/composer-attachments/PRD.md` |
 | session-dock | `shared/ui/session-dock/` | 会话页右栏的 surface 宿主(Rail 形态,2026-09-02 从 Dock/Rail/Ambient 三原型中选定,见 ADR-0028):面板本体 + 贴面板右缘的 44px 图标 rail,面板收起时 rail 随之消失。开合是成对运动(2026-09-06 修订):分栏 pane(`.pigui-session-dock-pane`,agent-workspace 里)在 `data-motion` 期间对 width 做 transition——这是全项目唯一刻意动画的布局属性,因为只有布局变化才能让分隔线和 Chat 列跟着 dock 边缘走;dock 本体只淡出淡入,不再自带 translate(否则位移叠加、内容比分隔线先跑掉);进 250ms / 出 180ms,拖拽调宽时无 transition,减动效关闭;Terminal/Browser 持有活的 pty / WebContentsView,关闭后不能一直挂着,所以退出动画结束后再卸 DOM。Rail 指针切换 surface 时内容区轻淡入,键盘切换不动画。静止态不写任何 `transform`/`will-change`:那会让 dock 或 surface 变成独立 stacking context,surface 第一行的 `z-index: 51` 就压不过 fixed 的 header chrome 拖拽区,标题带里的 tab 会点不到(2026-09-06 实测)。开合期间通过 `SessionDockMotionContext` 向 surface 广播「正在动画」,Browser 据此让原生视图让位。**宿主不写表头**(2026-09-05 ADR-0028 修订,[#184](https://github.com/BubblePtr/pace/issues/184)):rail 图标高亮已经命名了当前 surface、tooltip 里又是同一句,表头是第三遍,而且把每个 surface 自己的第一行挤成了第二条 40px 带;现在面板顶部那条 40px 带**就是 Surface 的第一行(状态 + 动作)**,`aside` 的可访问名改用 `aria-label`。rail 用 Astryx `ToggleButtonGroup`(vertical/single),宽度(默认 560 / 最小 340 / 上限 = 可分配宽度 - Chat 最小宽 400,2026-09-02 从原先的 58vw 改来,见 ADR-0028 修订)交给 agent-workspace 里既有的 Astryx `useResizable`;上限随分栏容器的 `ResizeObserver` 实时重算,窗口缩小到容不下时主动把 size clamp 回新上限;`surface-registry.ts` 只存元数据(id/title/icon/hint/multiInstance/flushContent——hint 只剩 rail tooltip 一个消费者,flush 的 surface 去掉内容内边距、自己管 inset),surface 内容由页面注入,注册表因此不依赖 Session 状态。已注册 Changes / Files / Terminal / Browser——Terminal 是首个 multiInstance surface(单 rail 图标 + 第一行实例条,ADR-0028);四者均 flush(第一行与内容贴面板缘);Files 已由 ADR-0035 解冻为只读 checkout 浏览器。Changes 的页面组合始终为 Diff / 大纲双栏，各自独立滚动且填满可用高度，文件标题在 Diff 列内吸顶，空态直接复用 Astryx `EmptyState`，与 Terminal / Browser 一致，不新增自建原语（#243）。rail 徽标(`badges`)由页面层的 `useSessionChanges` 供给 Changes 文件数(#141),与第一行的文件统计同源;Terminal 徽标是 `SessionTerminalPanel`(`widgets/session-dock/`)上报给页面的实例数;干净树、非 Git、加载中与读取失败都不显示数字 |
 | session-surface-bar | `shared/ui/session-dock/surface-bar.tsx` | Surface 第一行的两个共享原语(#184,ADR-0028 2026-09-05 修订)。`SessionSurfaceBar`:`h-10` 容器,与 Chat 标题同基线;`px-2` 是 flush surface 的统一内缩——这里打头的都是自带 ~8px 内边距的控件,图标因此落在与下方内容同一条 16px 列上;左槽状态、右槽动作(动作槽即使暂时空着也保留,Changes 将来的 checkout / commit / push 落在那里,ADR-0008)。`SessionSurfaceTabs`:多实例 surface 的实例条,每个 tab 自带关闭按钮、末尾一枚新建按钮、`exited` 态、`role=tablist`/`aria-selected`;Terminal 是首个消费者,Browser 多实例([#185](https://github.com/BubblePtr/pace/issues/185))复用同一个而不是再画一套。Astryx 都不等价:`Toolbar` 的高度来自 `--size-element-*` 加自身 block padding,钉不到 40px,而且它的 roving tabindex 会和实例条自己的方向键模型嵌套打架;`Tab` 渲染成单个 `<button>`,装不下每个 tab 自己的关闭按钮 |
-| browser-surface | `shared/ui/browser/` | Browser 多实例宿主的界面（#185，ADR-0029）：复合件，根只持 `state`，`.Tabs` / `.Toolbar` / `.Viewport` 分块；`isOpening` / `isInitializing` 并入 empty 的 `phase`。第一行复用 `SessionSurfaceBar` + `SessionSurfaceTabs`，支持新建、激活与关闭，右侧显示当前页标注数量；第二行放地址栏、历史导航和 Annotate 标注模式工具条，标注数量独立到第一行以保留地址输入空间。原生 `WebContentsView` 按 Session/tab 由主进程持有。Astryx 无法承载原生子视图，故保留自建 placeholder 与 bounds 同步；普通控件使用 Astryx，tab 条沿用 #184 的共享原语。只有 live 态渲染 viewport，narrow / unsupported / empty / error 均不显示原生视图；加载中独立提示，关闭全部 tab 返回 empty。弹层出现时捕获当前 tab 的静态快照再隐藏原生视图，切 tab 时丢弃旧快照；dock 开合动画期间同样让位——`WebContentsView` 跟不了 CSS transform，关闭时先截图再隐藏，重新展开从第一帧起显示上次缓存的快照（模块级 `lastStills`，按 session:tab 记），`transitionend` 后重新同步 bounds 并恢复显示。每个 tab 独立记地址、加载/错误、标注模式、标注与 notice 提示；Project 保存 URL 列表和激活项，兼容旧单 URL。标注评论由主进程按 Session 持有（browser annotation v2：保存即裁剪截图，导航/重载不清失），composer 抽屉以 Token 芯片列出，页内 Cmd/Ctrl+Enter 请求发送，发送成功后按快照 id 消费掉。工具条保持无弹层按钮，避免在冻结快照上标注；页内 closed Shadow DOM 覆盖层不属于 `shared/ui/`。零 tab 时隐藏实例条与页面工具条，复用 Astryx `EmptyState`，点击「Open browser」才恢复 Project 保存的 tab 或创建空白 tab；初始空态不清除项目记录，已有原生实例仍直接重新附着。Design 页展示多 tab、单 tab、零 tab、初始化、创建中、创建失败、空白 tab、加载、标注、发送、快照、错误和不可用状态。 |
+| browser-surface | `shared/ui/browser/` | Browser 多实例宿主的界面（#185，ADR-0029）：复合件，根只持 `state`，`.Tabs` / `.Toolbar` / `.Viewport` 分块；`isOpening` / `isInitializing` 并入 empty 的 `phase`。第一行复用 `SessionSurfaceBar` + `SessionSurfaceTabs`，支持新建、激活与关闭，右侧显示当前页标注数量；第二行放地址栏、历史导航和 Annotate 标注模式工具条，标注数量独立到第一行以保留地址输入空间。原生 `WebContentsView` 按 Session/tab 由主进程持有。Astryx 无法承载原生子视图，故保留自建 placeholder 与 bounds 同步；普通控件使用 Astryx，tab 条沿用 #184 的共享原语。只有 live 态渲染 viewport，narrow / unsupported / empty / error 均不显示原生视图；加载中独立提示，关闭全部 tab 返回 empty。弹层出现时捕获当前 tab 的静态快照再隐藏原生视图，切 tab 时丢弃旧快照；dock 开合动画期间同样让位——`WebContentsView` 跟不了 CSS transform，关闭时先截图再隐藏，重新展开从第一帧起显示上次缓存的快照（模块级 `lastStills`，按 session:tab 记），`transitionend` 后重新同步 bounds 并恢复显示。每个 tab 独立记地址、加载/错误、标注模式、标注与 notice 提示；Project 保存 URL 列表和激活项，兼容旧单 URL。标注评论由主进程按 Session 持有（browser annotation v2：保存即裁剪截图，导航/重载不清失），支持点击元素与区域框选（拖动超过 4px，锚定最小包含元素），composer 抽屉以 Token 芯片列出（区域为 `#n Area · …`），页内 Cmd/Ctrl+Enter 请求发送，发送成功后按快照 id 消费掉。工具条保持无弹层按钮，避免在冻结快照上标注；页内 closed Shadow DOM 覆盖层不属于 `shared/ui/`。零 tab 时隐藏实例条与页面工具条，复用 Astryx `EmptyState`，点击「Open browser」才恢复 Project 保存的 tab 或创建空白 tab；初始空态不清除项目记录，已有原生实例仍直接重新附着。Design 页展示多 tab、单 tab、零 tab、初始化、创建中、创建失败、空白 tab、加载、标注、发送、快照、错误和不可用状态。 |
 | terminal-view | `shared/ui/terminal/` | xterm.js 宿主原语,Astryx 无终端组件;Terminal + FitAddon 的生命周期(open / ResizeObserver fit / dispose)全收在组件内,对外只有 `write`/`focus` ref 句柄和 `onData`/`onResize` 回调,不含任何后端知识。右缘留白是 xterm 固有结构:FitAddon 为滚动条预留 `overviewRuler?.width || 14`px + 单元格取整余量(≤1 字符);xterm 6 的滚动条是 VS Code 式自绘元素(非原生 gutter),宽度同源 overviewRuler.width——组件内设为 8px(带 canvas 能力检测,jsdom 无 2d context 会硬崩),滑块颜色走 theme 的 `scrollbarSlider*Background`(token 经 color-mix 探针解析为 rgba,18/28/40% 三档,对齐 styles.css 的滚动条语言),闲置自动隐去。chrome 色(背景/前景/光标/选区)从 token 桥解析——桥是链式 var() 且 theme-neutral 的一级 token 在 `@scope` 内,documentElement 上读不到,故在主题作用域内挂探针元素读真实属性,整链(含 light-dark())解析为 rgb;背景取 `--surface` 与 dock 面板同色,OS 明暗切换经 matchMedia 重算主题。ANSI 16 色刻意保留惯例终端色——程序输出语义(diff 红、测试绿),不是 UI chrome——并按背景亮度在 VS Code 深/浅两套惯例色间选择。RPC 封装在 `entities/terminal/terminal-client.ts`;供 SessionDock 的 Terminal surface(`widgets/session-dock/session-terminal-panel.tsx`)使用。面板只查询已有 shell；零实例时页面层复用 Astryx `EmptyState`，点击「New terminal」才创建，创建中禁用按钮、失败可重试，关闭最后一个 shell 返回空态而不补建；不新增自建空态原语 |
 | icons.tsx / animated-icons.tsx / primitives.css / chat.css | `shared/ui/` | 图标与样式桥。Astryx 接受自定义 SVG，但没有所选的部件动画；`animated-icons.tsx` 适配 Hugeicons Animated 的 12 枚图形与 Lucide Animated 的饼图，统一 1.5 线宽与 SVG props。全部 14 个动画导出只在鼠标实际移入时播放一轮，整轮统一使用 `--pigui-icon-motion-duration`（固定 800ms，包含部件延迟，不随主题变化），点击不重播或按压缩放。用于 Sidebar / Header（含右上角 Dock 开关）与 Settings 的五个分类导航，Dock 内部栏位图标保持静态；Design 的 AnimatedIcons 展示全部尺寸和禁用 / 静态状态，规则见 `docs/design/animated-icons.md`。chat.css 把对话标题收成 conversation type scale(`#` 比正文大一档,更低层级不小于正文),大纲用 headingLevelStart=3 |
 
@@ -49,7 +49,7 @@
 | 方向 | Issue | 状态 |
 | --- | --- | --- |
 | Plugin surfaces 面板宿主(渲染侧) | [#85](https://github.com/BubblePtr/pace/issues/85) | 被 ADR-0018 协议阻塞 |
-| Embedded browser annotation 覆盖层/工具条 | [#86](https://github.com/BubblePtr/pace/issues/86) | S1 宿主与 surface、S2 标注层与 design mode 工具条、S3 载荷回传 composer([#151](https://github.com/BubblePtr/pace/issues/151))均已落地(见上表 browser-surface);覆盖层在页内 Shadow DOM,不是 `shared/ui/` 组件。S4 ADR-0029 已落地([#152](https://github.com/BubblePtr/pace/issues/152)) |
+| Embedded browser annotation 覆盖层/工具条 | [#86](https://github.com/BubblePtr/pace/issues/86) | S1 宿主与 surface、S2 标注层与 design mode 工具条、S3 载荷回传 composer([#151](https://github.com/BubblePtr/pace/issues/151))均已落地(见上表 browser-surface);覆盖层在页内 Shadow DOM,不是 `shared/ui/` 组件。S4 ADR-0029 已落地([#152](https://github.com/BubblePtr/pace/issues/152));v2(#446–#450):先编辑后保存、主进程 Session 级评论仓、composer 结构化附件、跨文档保留、区域框选,见 ADR-0029「修订:标注 v2」 |
 | 图表原语扩展(面积/日历热力/会话表) | [#87](https://github.com/BubblePtr/pace/issues/87) | 折线与星期×小时热力已随 Usage 重构落地；其余等需求驱动 |
 | Dynamic workflow visualization(图/DAG/时间线) | [#84](https://github.com/BubblePtr/pace/issues/84) | **future,远期**(2026-08-09 降级) |
 | 思维链样式可选项(Compact/Timeline) | [#81](https://github.com/BubblePtr/pace/issues/81) | **future,后置**(被 Appearance 设置页阻塞) |