diff --git a/.scratch/browser-annotation-v2/PRD.md b/.scratch/browser-annotation-v2/PRD.md
new file mode 100644
index 00000000..9f51f02a
--- /dev/null
+++ b/.scratch/browser-annotation-v2/PRD.md
@@ -0,0 +1,117 @@
+# Browser Annotation v2：对齐 Codex 的标注体验
+
+> 前身：`.scratch/embedded-browser/PRD.md`（v1，S2 / S3）与 `docs/adr/0029-embedded-browser-surface.md`。
+> 调研对象：Codex / ChatGPT 桌面端内置浏览器的 Annotation mode（官方文档 `developers.openai.com/codex/app/browser`、Annotations Extensibility 文档、openai/codex#22719 等 issue）。
+> 用户拍板（2026-10-10）：**标注以结构化附件进入 composer（推翻 v1「只落草稿、不新增结构化附件」）；评论框里 Enter 默认「保存并继续攒」。**
+> 落地：切片开成 GitHub Issues 后在本文「切片」段回链。
+
+## 问题
+
+v1 的标注能用，但每一步都比 Codex 多一次操作、少一份反馈：
+
+1. 点元素只落一个序号，要再点序号才能写评论；不写评论也算一条标注（`(no comment)`），同一元素可重复标。
+2. 评论框是 220px 单行 `input`，没有保存 / 取消 / 删除，失焦即提交；只能「全部清空」，不能删单条。
+3. 命中的是 `composedPath()[0]`（最深节点），常选中 `span` / `svg path`；没有办法选父元素；高亮框没有任何标签。
+4. 已标注元素只在左上角留一枚徽章，没有轮廓；嵌套元素的徽章叠在同一角；评论框贴边时不翻转。
+5. 覆盖层颜色硬编码（`#6d28d9`、白底），与 Pace 主题、暗色模式脱节；进入模式后页面上看不出「正在标注」。
+6. `To composer` 把一整段 markdown 追加进草稿 + 一张整视口截图：草稿里混着模板文本；视口外的标注拍不到；发出后标注仍留在页上，再点一次就重复发送。
+7. 每个新文档（整页刷新、HMR 失败回退刷新）主进程直接清空标注，评论全丢。
+
+Codex 的对应体验：点选即打开评论编辑器、保存后作为下一条消息的附加上下文、可拖拽框选区域、编辑 / 删除已有评论、标注不再混进用户自己写的文本。
+
+## 决策
+
+### 1. 标注生命周期：先编辑，保存才算数
+
+```
+hover ──click──▶ editing ──Save / Enter──▶ saved（pending）──消息发出──▶ consumed（从页面和 composer 移除）
+                    │                         │
+                    └──Cancel / Esc──▶ 丢弃     └──Delete──▶ 移除
+```
+
+- 点击元素**立即**在元素旁打开编辑器并聚焦；此时还不是标注，取消即无痕。
+- **评论必填**：空评论时 Save 禁用、Enter 无效。v1「没评论的标注也是标注」的取舍作废：先编辑后保存的流程里，空评论只是误点。
+- 点击已保存的元素或它的徽章 → 打开该条的编辑器（编辑态多一个 Delete），**不再新增重复标注**。
+- 一次只开一个编辑器；编辑器开着时点别的元素 = 先按 Cancel 语义丢弃未保存内容，再开新的（未保存且有内容时编辑器抖动一下提示，不切走；Codex 同款）。
+
+### 2. 键位
+
+| 键 | 编辑器内 | 标注模式、编辑器未开 |
+|---|---|---|
+| `Enter` | 保存，留在标注模式继续攒 | — |
+| `Shift+Enter` | 换行 | — |
+| `Cmd/Ctrl+Enter` | 保存并**立即发送** composer（见决策 4） | 立即发送 composer（有 pending 评论时） |
+| `Esc` | 取消编辑 | 退出标注模式 |
+| `↑` / `↓` | — | 悬停目标切到父元素 / 回到子元素 |
+| `Cmd/Ctrl+Shift+A` | — | 切换标注模式（页面内由 overlay 监听，Pace 窗口内由 Browser 面板监听） |
+
+Codex 默认是 Enter 直发、`Cmd+Enter` 攒（#22719 下大量反对）；Pace 反过来，与 composer 自身「Enter 发送」不冲突，因为评论框的「发送」是保存到待发区。
+
+### 3. 覆盖层交互
+
+- **目标收敛**：从最深节点向上，跳过行内装饰节点（`span`/`b`/`i`/`em`/`strong`/`svg` 子节点/小于 8×8 的元素），停在最近的「有意义目标」：交互控件（`a`/`button`/`input`/`select`/`textarea`/`label`/`[role=button]`）、媒体（`img`/`svg`/`video`/`canvas`）、带 `id` 或 `data-testid` 的元素、或块级文本容器。`↑`/`↓` 在这条祖先链上手动移动。
+- **悬停标签**：高亮框上方一枚小标签 `tag.firstClass · W×H`，有 `source` 时追加 `file:line`。
+- **已保存标注**：保留细轮廓 + 徽章；徽章贴在轮廓**外侧**右上角，与已有徽章重叠时依次错开。编辑器默认在元素下方，空间不足翻到上方，水平方向夹进视口。
+- **模式可感知**：视口内侧 2px 主题色描边 + 顶部居中一枚「Annotating · Esc to exit」标签（均在 closed shadow root 内，`pointer-events: none`）。
+- **主题**：渲染层在开启标注模式时从计算后的语义 token（`--primary`、`--primary-foreground`、`--background`、`--foreground`、`--border`、`--muted-foreground`）读出颜色值，随 `set-design-mode` 命令下发；overlay 用 `CSS.supports("color", v)` 逐个校验，不合法回落内置默认值。不在页内加载任何 Pace 样式表。
+- **工具条**：`Design` 改名 `Annotate`（ToggleButton，仍是准星图标）；`Clear marks` 只清当前 tab 的评论；**移除 `To composer`**（被决策 4 取代）；右侧计数改为 `N comments`。
+- 编辑器仍在页内 closed Shadow DOM 里，用 textarea + 原生按钮实现。「透明子 `WebContentsView` 承载 React 编辑器」不在本轮（见范围外）。
+
+### 4. 结构化附件：Browser Comment 进 composer
+
+- **单一事实来源在主进程**：Session 级评论仓（不是 tab 级），每条：`{ id, tabId, url, title, viewport, element(selector/tag/text/rect/source), comment, kind: "element" | "area", stale, createdAt }` + 一张局部截图。关闭 tab 只移除页上标记，评论仍在仓里；窗口关闭/应用退出即丢（与图片附件不落盘的策略一致）。
+- **composer 拉取，不复制**：`FullChatComposer` 订阅本 Session 的评论仓（新增只读命令 + 事件），在附件抽屉里渲染为独立分组「Browser comments」，每条一个条目：缩略图 + `#n 评论摘要`（单行截断）+ 移除。移除 = 调主进程删除，页上标记同步消失；页上删除，composer 条目同步消失。没有第二份副本，因此不存在同步漂移。
+- **编号**：`#n` 是发送前 Session 内 pending 列表的顺序号，增删后重排；页上徽章同步显示同一编号。局部截图**不含任何覆盖层元素**（截取前整层隐藏），所以重排编号不会让截图与文本对不上。
+- **发送**：composer 的 `submitDraft` 在用户草稿之后追加 core 格式化的评论块，图片按评论顺序附在 `images` 里；Pi 收到的仍是 `string + RuntimePromptImage[]`，Gateway / Pi 侧零改动。`send_prompt` / `queue_follow_up` / 从队列 steer 三条路径天然覆盖（评论在入队时已烤进消息）。
+- **消费**：提交成功后按**构建时快照的 id 列表**调 `browser_consume_annotations`；提交期间新存的评论不受影响。提交失败则全部保留。
+- **Cmd/Ctrl+Enter 直发**：页面 → 主进程 `submit-requested` → 渲染层事件 → composer 执行与点击发送相同的 `submitDraft`（新增 `requestComposerSubmit(sessionId)`，与 `injectIntoComposer` 同范式，返回是否有 composer 接住；没接住时 Browser 面板一行提示，评论保留）。
+- **局部截图**：保存时由 overlay 隐藏整层、等两帧，再通知主进程；主进程 `capturePage(rect)`，rect = 元素矩形外扩 48 CSS px、最小 320×200、夹进视口，按 CSS 像素降采样（沿用 `downsampleToCssWidth`）。状态事件只带 `hasImage`，图片走单独的只读命令按 id 取（缩略图与发送时用），不在每次状态广播里搬 data URL。
+- **格式化**：core 新增 `formatBrowserComments(groups)` 替换 `formatBrowserAnnotationPrompt`：按 URL 分组，每条 `#n` + selector/tag + 评论 + text/source；无截图的条目附 rect；`stale` 条目注明「元素已不在当前页面，截图为保存时所见」。模板由测试锁定。
+
+### 5. 跨文档保留与重新定位
+
+- 新文档 `ready` 时，主进程不再清空，而是下发 `restore-annotations`：当前 tab 中 URL 与新文档相同（比较 origin + pathname + search，忽略 hash）的评论。`did-navigate-in-page`（SPA 路由切换）同样重发。
+- overlay 用 selector 唯一解析元素；解析不到时用 MutationObserver 继续尝试最多 5s（等 SPA 渲染），仍失败则上报 `stale`。stale 评论在 composer 条目上显示警示，仍可发送（文本 + 保存时的截图仍有效）。
+- 页上只显示与当前 URL 匹配的评论标记；其他页面的评论只在 composer 里。
+
+### 6. 区域框选
+
+- 标注模式下按住拖动超过 4px 即进入框选，松开打开编辑器；`kind: "area"`，记录视口矩形，`selector` 取完整包含该矩形的最小元素作为锚点，并记录相对锚点的偏移，供决策 5 重新定位。
+- 单击仍是元素选择；框选不吞页面滚动。
+
+## 切片
+
+依赖顺序：S1 → S2 → S3；S4 依赖 S1；S5 收尾。
+
+1. **S1 覆盖层交互重写**（#446；`electron/browser-annotation-overlay.ts`、`browser-annotation.ts`、`browser-surface.tsx`）：决策 1、2（除 `Cmd+Enter` 发送）、3。标注获得稳定 `id`（overlay 侧 `crypto.randomUUID()`，主进程按字符串 ≤64 校验）；协议仍发全量列表，v1 的 `To composer` 本切片暂时保留可用。
+2. **S2 主进程评论仓**（#447；`browser-host.ts`、`main.ts`、`browser-protocol.ts`、preload）：决策 4 的仓 / 局部截图 / 读、删、消费命令与事件，决策 5 的跨文档保留与 stale。
+3. **S3 composer 结构化附件**（#448；`full-chat-composer.tsx`、`shared/ui/composer-attachments/`、`entities/session/composer-injections.ts`、`packages/core/src/browser-annotation.ts`、`session-browser-panel.tsx`）：决策 4 的抽屉分组、发送与消费、`Cmd+Enter` 直发、`formatBrowserComments`；移除 `To composer` 与旧注入路径。
+4. **S4 区域框选**（#449）：决策 6。
+5. **S5 文档收尾**（#450）：ADR-0029 追加修订节（推翻「只落草稿」、评论仓归主进程、跨文档保留）；`CONTEXT.md` 加 **Browser Comment** 词条；`/design` 页更新 `BrowserSurface` 工具条与附件抽屉新分组；`docs/self-built-ui.md`、`docs/design/` 对应条目。
+
+## 验收标准
+
+- [ ] 点击元素即出现已聚焦的编辑器；Esc 取消后页面无残留；空评论不可保存；同一元素再点进入编辑而非新增。
+- [ ] Enter 保存并留在标注模式；Shift+Enter 换行；Cmd/Ctrl+Enter 保存并以当前草稿 + 全部 pending 评论发出一条消息。
+- [ ] 保存后 composer 抽屉「Browser comments」立刻出现对应条目（缩略图 + `#n` + 摘要）；任一端删除，另一端同步消失。
+- [ ] 发出的消息：用户草稿在前，评论块在后，图片按 `#n` 顺序；发送成功后页面与 composer 中这些评论消失，发送期间新存的评论保留；发送失败全部保留。
+- [ ] 运行中 composer 处于队列模式时，评论随入队消息一起烤入并被消费。
+- [ ] 整页刷新后同 URL 的评论标记回到原元素；元素消失的标为 stale 且仍可发送。
+- [ ] 暗色主题下覆盖层使用 Pace 语义色；标注模式有可见描边与提示标签。
+- [ ] 视口外（已滚走）的评论截图仍是保存时的局部图。
+- [ ] Vitest：overlay 交互（jsdom）、主进程评论仓与消费的竞态、core 格式化模板、composer 抽屉与提交路径；Electron E2E：标注 → 保存两条 → Cmd+Enter → 断言发出的 prompt 与图片数。
+- [ ] `bun run typecheck` / `lint` / `test` / `build` 全绿。
+
+## 范围外
+
+- Codex 的 **Adjust** 样式微调（字体 / 间距 / 颜色实时预览并随评论发送）。
+- 页面侧扩展协议（类似 `oai-annotatable` / `oai-annotation-metadata` 的 `data-pace-*` 属性）；与 #159（reactName / source）一并后续评估。
+- 文字范围标注、跨源 iframe 内元素（仍等 CDP）。
+- 用透明子 `WebContentsView` 以 React + Astryx 渲染编辑器。
+- 评论持久化到磁盘、跨应用重启保留。
+- Browser 面板内的评论列表（composer 抽屉已承担列表职能）。
+
+## 风险
+
+- 评论多时图片数随之增长，占用上下文；本轮不设上限，以真实使用反馈再定。
+- 选择器重新定位依赖页面结构稳定；`nth-of-type` 链在列表重排后可能命中错误元素——stale 判定只能识别「找不到」，识别不了「找错」。
diff --git a/apps/desktop/electron/browser-annotation-overlay.test.ts b/apps/desktop/electron/browser-annotation-overlay.test.ts
index 91418921..51ecb9a0 100644
--- a/apps/desktop/electron/browser-annotation-overlay.test.ts
+++ b/apps/desktop/electron/browser-annotation-overlay.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type {
   BrowserAnnotationElement,
+  BrowserAnnotationPalette,
   BrowserAnnotationViewport,
 } from "@/shared/browser-protocol";
 import {
@@ -12,8 +13,8 @@ import {
 /**
  * The overlay lives in a closed shadow root, which is exactly what makes it
  * unreachable from the page — and from a test. Capturing the roots as they are
- * attached is the only way to drive the comment bubble the way a user does;
- * everything else is asserted through the callbacks the preload subscribes to.
+ * attached is the only way to drive the editor the way a user does; everything
+ * else is asserted through the callbacks the preload subscribes to.
  */
 const shadowRoots: ShadowRoot[] = [];
 let overlay: BrowserAnnotationOverlay | null = null;
@@ -54,26 +55,105 @@ function clickPageElement(element: Element) {
   );
 }
 
-function pressKey(target: EventTarget, key: string) {
+function hoverPageElement(element: Element) {
+  element.dispatchEvent(
+    new MouseEvent("pointermove", {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+    }),
+  );
+}
+
+function pressKey(target: EventTarget, key: string, init: KeyboardEventInit = {}) {
   target.dispatchEvent(
-    new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true, composed: true }),
+    new KeyboardEvent("keydown", {
+      key,
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      ...init,
+    }),
   );
 }
 
-function rectAt(x: number, y: number) {
+function rectAt(x: number, y: number, width = 40, height = 20) {
   return {
     x,
     y,
-    width: 40,
-    height: 20,
+    width,
+    height,
     left: x,
     top: y,
-    right: x + 40,
-    bottom: y + 20,
+    right: x + width,
+    bottom: y + height,
     toJSON: () => ({}),
   } as DOMRect;
 }
 
+/**
+ * jsdom measures nothing, and target resolution skips elements under 8px —
+ * every click target needs a rect or the climb lands on `<body>`.
+ */
+function place(element: Element, x = 40, y = 40) {
+  vi.spyOn(element, "getBoundingClientRect").mockReturnValue(rectAt(x, y));
+  return element;
+}
+
+function clip(element: Element, x: number, y: number, width: number, height: number) {
+  vi.spyOn(element, "getBoundingClientRect").mockReturnValue(
+    rectAt(x, y, width, height),
+  );
+  Object.defineProperties(element, {
+    clientLeft: { configurable: true, value: 0 },
+    clientTop: { configurable: true, value: 0 },
+    clientWidth: { configurable: true, value: width },
+    clientHeight: { configurable: true, value: height },
+  });
+  return element;
+}
+
+function editor(h: ReturnType<typeof harness>) {
+  return h
+    .shadow()
+    .querySelector<HTMLElement>('[data-slot="annotation-editor"]')!;
+}
+
+function editorInput(h: ReturnType<typeof harness>) {
+  return h
+    .shadow()
+    .querySelector<HTMLTextAreaElement>('[data-slot="annotation-editor-input"]')!;
+}
+
+function editorButton(h: ReturnType<typeof harness>, slot: string) {
+  return h
+    .shadow()
+    .querySelector<HTMLButtonElement>(`[data-slot="annotation-editor-${slot}"]`)!;
+}
+
+function editorVisible(h: ReturnType<typeof harness>) {
+  return editor(h).style.display !== "none";
+}
+
+function typeDraft(h: ReturnType<typeof harness>, text: string) {
+  const input = editorInput(h);
+  input.value = text;
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+/** Click, type, Enter — the full path from pointer to saved annotation. */
+function annotate(h: ReturnType<typeof harness>, element: Element, text: string) {
+  clickPageElement(element);
+  typeDraft(h, text);
+  pressKey(editorInput(h), "Enter");
+}
+
+function badges(h: ReturnType<typeof harness>) {
+  return Array.from(
+    h.shadow().querySelectorAll<HTMLElement>('[data-slot="annotation-badge"]'),
+  );
+}
+
 /** jsdom runs rAF on a timer; two frames is enough for a scheduled sync. */
 function nextFrames() {
   return new Promise<void>((resolve) => {
@@ -81,6 +161,15 @@ function nextFrames() {
   });
 }
 
+const fullPalette: BrowserAnnotationPalette = {
+  accent: "rgb(1, 2, 3)",
+  accentForeground: "rgb(4, 5, 6)",
+  surface: "rgb(7, 8, 9)",
+  foreground: "rgb(10, 11, 12)",
+  border: "rgb(13, 14, 15)",
+  muted: "rgb(16, 17, 18)",
+};
+
 beforeEach(() => {
   const attachShadow = Element.prototype.attachShadow;
 
@@ -94,133 +183,611 @@ beforeEach(() => {
     shadowRoots.push(root);
     return root;
   });
-  document.body.innerHTML = '<main><button id="cta">Go</button><p id="copy">c</p></main>';
+  document.body.innerHTML =
+    '<main><button id="cta">Go</button><p id="copy">c</p></main>';
 });
 
 afterEach(() => {
   overlay?.dispose();
   overlay = null;
   vi.restoreAllMocks();
+  vi.unstubAllGlobals();
 });
 
 describe("annotation overlay", () => {
-  it("marks an element only while design mode is on, and keeps the click from the page", () => {
-    const { overlay, annotationChanges, latest } = harness();
+  it("opens a focused editor on click and reports nothing until it is saved", () => {
+    const h = harness();
+    const button = place(document.getElementById("cta")!);
     const pageClicks = vi.fn();
-    const button = document.getElementById("cta")!;
 
     button.addEventListener("click", pageClicks);
-
     clickPageElement(button);
 
-    expect(annotationChanges).toHaveLength(0);
     expect(pageClicks).toHaveBeenCalledTimes(1);
+    expect(h.annotationChanges).toHaveLength(0);
 
-    overlay.setDesignMode(true);
+    h.overlay.setDesignMode(true);
     clickPageElement(button);
 
     // The page must not act on a click the user meant as "mark this".
     expect(pageClicks).toHaveBeenCalledTimes(1);
-    expect(latest()).toHaveLength(1);
-    expect(latest()[0]).toMatchObject({ index: 1, selector: "#cta", tag: "button" });
+    expect(editorVisible(h)).toBe(true);
+    expect(h.shadow().activeElement).toBe(editorInput(h));
+
+    // A draft is not an annotation yet: main hears nothing while it is typed.
+    typeDraft(h, "Too small to hit");
+    expect(h.annotationChanges).toHaveLength(0);
+    // Main clamps comments at the same ceiling when it rebuilds them.
+    expect(editorInput(h).maxLength).toBe(500);
   });
 
-  it("numbers markers in the order they were clicked", () => {
-    const { overlay, latest } = harness();
+  it("cannot save an empty comment — Save is disabled and Enter does nothing", () => {
+    const h = harness();
 
-    overlay.setDesignMode(true);
-    clickPageElement(document.getElementById("cta")!);
-    clickPageElement(document.getElementById("copy")!);
+    h.overlay.setDesignMode(true);
+    clickPageElement(place(document.getElementById("cta")!));
+
+    const save = editorButton(h, "save");
 
-    expect(latest().map((annotation) => [annotation.index, annotation.selector])).toEqual([
-      [1, "#cta"],
-      [2, "#copy"],
-    ]);
+    expect(save.disabled).toBe(true);
+
+    pressKey(editorInput(h), "Enter");
+    typeDraft(h, "   ");
+    pressKey(editorInput(h), "Enter");
+
+    expect(editorVisible(h)).toBe(true);
+    expect(h.annotationChanges).toHaveLength(0);
   });
 
-  it("leaves design mode on Escape and keeps the marks that were made", () => {
-    const { overlay, designModeChanges, latest } = harness();
+  it("saves on Enter and stays in annotation mode", () => {
+    const h = harness();
 
-    overlay.setDesignMode(true);
-    clickPageElement(document.getElementById("cta")!);
+    h.overlay.setDesignMode(true);
+    annotate(h, place(document.getElementById("cta")!), "Too small to hit");
 
-    window.dispatchEvent(
-      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
-    );
+    expect(h.latest()).toHaveLength(1);
+    expect(h.latest()[0]).toMatchObject({
+      index: 1,
+      selector: "#cta",
+      tag: "button",
+      comment: "Too small to hit",
+    });
+    expect(typeof h.latest()[0]!.id).toBe("string");
+    expect(h.designModeChanges).toEqual([]);
+    expect(editorVisible(h)).toBe(false);
+    expect(badges(h)[0]?.textContent).toBe("1");
+  });
 
-    expect(designModeChanges).toEqual([false]);
+  it("keeps Shift+Enter as a newline instead of saving", () => {
+    const h = harness();
+    const event = new KeyboardEvent("keydown", {
+      key: "Enter",
+      shiftKey: true,
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+    });
 
-    // Marks outlive design mode — they are what the screenshot has to show.
-    clickPageElement(document.getElementById("copy")!);
-    expect(latest()).toHaveLength(1);
+    h.overlay.setDesignMode(true);
+    clickPageElement(place(document.getElementById("cta")!));
+    typeDraft(h, "line one");
+    editorInput(h).dispatchEvent(event);
+
+    expect(event.defaultPrevented).toBe(false);
+    expect(editorVisible(h)).toBe(true);
+    expect(h.annotationChanges).toHaveLength(0);
   });
 
-  it("reports the page's own viewport alongside the marks", () => {
-    const { overlay, viewports } = harness();
+  it("cancels the editor on first Escape and leaves the mode on the second", () => {
+    const h = harness();
 
-    for (const [property, value] of Object.entries({
-      innerWidth: 684,
-      innerHeight: 820,
-      devicePixelRatio: 2,
-    })) {
-      Object.defineProperty(window, property, { configurable: true, value });
-    }
+    h.overlay.setDesignMode(true);
+    clickPageElement(place(document.getElementById("cta")!));
+    typeDraft(h, "half-typed");
+    pressKey(editorInput(h), "Escape");
 
-    overlay.setDesignMode(true);
-    clickPageElement(document.getElementById("cta")!);
+    expect(editorVisible(h)).toBe(false);
+    expect(h.designModeChanges).toEqual([]);
+    expect(h.annotationChanges).toHaveLength(0);
+
+    pressKey(window, "Escape");
+
+    expect(h.designModeChanges).toEqual([false]);
+  });
+
+  it("reverts an existing annotation's text when its edit is cancelled", () => {
+    const h = harness();
+    const button = place(document.getElementById("cta")!);
+
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "saved text");
+    clickPageElement(button);
+
+    expect(editorInput(h).value).toBe("saved text");
+
+    typeDraft(h, "changed mind");
+    editorButton(h, "cancel").click();
+
+    expect(editorVisible(h)).toBe(false);
+    expect(h.latest()[0]!.comment).toBe("saved text");
+    expect(h.latest()).toHaveLength(1);
+  });
+
+  it("opens the annotation's own editor when its element or badge is re-clicked", () => {
+    const h = harness();
+    const button = place(document.getElementById("cta")!);
+
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "first note");
+    clickPageElement(button);
 
-    // The marks are measured in the page's viewport, not the panel's rect —
-    // and the panel can be resized between marking and sending.
-    expect(viewports[viewports.length - 1]).toEqual({
-      width: 684,
-      height: 820,
-      dpr: 2,
+    // Editing, not duplicating: the Delete button only exists for a saved mark.
+    expect(editorInput(h).value).toBe("first note");
+    expect(editorButton(h, "delete").style.display).not.toBe("none");
+    expect(h.latest()).toHaveLength(1);
+
+    pressKey(editorInput(h), "Escape");
+    badges(h)[0]!.click();
+
+    expect(editorInput(h).value).toBe("first note");
+    expect(h.latest()).toHaveLength(1);
+  });
+
+  it("deletes a mark and renumbers the rest contiguously", () => {
+    const h = harness();
+    const cta = place(document.getElementById("cta")!, 40, 40);
+    const copy = place(document.getElementById("copy")!, 40, 300);
+
+    h.overlay.setDesignMode(true);
+    annotate(h, cta, "first");
+    annotate(h, copy, "second");
+    clickPageElement(cta);
+    editorButton(h, "delete").click();
+
+    expect(h.latest()).toHaveLength(1);
+    expect(h.latest()[0]).toMatchObject({ index: 1, selector: "#copy", comment: "second" });
+    expect(badges(h).map((badge) => badge.textContent)).toEqual(["1"]);
+  });
+
+  it("keeps a dirty draft when another element is clicked, shaking instead of switching", () => {
+    const h = harness();
+    const cta = place(document.getElementById("cta")!, 40, 40);
+    const copy = place(document.getElementById("copy")!, 40, 300);
+
+    h.overlay.setDesignMode(true);
+    clickPageElement(cta);
+    typeDraft(h, "not finished");
+    clickPageElement(copy);
+
+    // The draft the user was typing survives — a click is not a discard.
+    expect(editorVisible(h)).toBe(true);
+    expect(editorInput(h).value).toBe("not finished");
+    expect(h.annotationChanges).toHaveLength(0);
+  });
+
+  it("discards an untouched draft when another element is clicked", () => {
+    const h = harness();
+    const cta = place(document.getElementById("cta")!, 40, 40);
+    const copy = place(document.getElementById("copy")!, 40, 300);
+
+    h.overlay.setDesignMode(true);
+    clickPageElement(cta);
+    clickPageElement(copy);
+
+    // The new target owns the editor: it hangs below the second element.
+    expect(editorVisible(h)).toBe(true);
+    expect(editorInput(h).value).toBe("");
+    expect(editor(h).style.top).toBe(`${300 + 20 + 8}px`);
+  });
+
+  it("flips the editor above an element near the viewport's bottom edge", () => {
+    const h = harness();
+
+    Object.defineProperty(window, "innerHeight", { configurable: true, value: 200 });
+    h.overlay.setDesignMode(true);
+    clickPageElement(place(document.getElementById("cta")!, 40, 170));
+
+    // jsdom's editor measures 0px tall, so above sits at top − 8.
+    expect(editor(h).style.top).toBe(`${170 - 8}px`);
+  });
+
+  it("lets ↑ climb to the parent and ↓ return, and annotates the adjusted target", () => {
+    const h = harness();
+    const wrap = place(document.querySelector("main")!, 8, 8);
+    const button = place(document.getElementById("cta")!, 40, 40);
+
+    h.overlay.setDesignMode(true);
+    hoverPageElement(button);
+    pressKey(window, "ArrowUp");
+    pressKey(window, "ArrowDown");
+    pressKey(window, "ArrowUp");
+    clickPageElement(button);
+    typeDraft(h, "the whole row");
+    pressKey(editorInput(h), "Enter");
+
+    expect(h.latest()[0]).toMatchObject({ index: 1, tag: "main" });
+    expect(button.parentElement).toBe(wrap);
+  });
+
+  it("ignores Enter and Escape while an IME composition is active", () => {
+    const h = harness();
+
+    h.overlay.setDesignMode(true);
+    clickPageElement(place(document.getElementById("cta")!));
+    typeDraft(h, "half-typed");
+
+    // Enter inside a composition confirms a candidate — saving half a phrase
+    // is the bug this guard exists for. keyCode 229 is Chromium's composition
+    // marker on platforms that do not set isComposing.
+    pressKey(editorInput(h), "Enter", { isComposing: true });
+    expect(editorVisible(h)).toBe(true);
+    expect(h.annotationChanges).toHaveLength(0);
+
+    pressKey(editorInput(h), "Enter", { keyCode: 229 });
+    expect(editorVisible(h)).toBe(true);
+    expect(h.annotationChanges).toHaveLength(0);
+
+    pressKey(editorInput(h), "Escape", { isComposing: true });
+    expect(editorVisible(h)).toBe(true);
+    expect(h.designModeChanges).toEqual([]);
+
+    // Once the composition commits, the same keys work again.
+    pressKey(editorInput(h), "Enter");
+    expect(h.latest()[0]!.comment).toBe("half-typed");
+  });
+
+  it("toggles annotation mode on Cmd/Ctrl+Shift+A and reports it", () => {
+    const h = harness();
+
+    pressKey(window, "a", { code: "KeyA", shiftKey: true, metaKey: true });
+
+    expect(h.designModeChanges).toEqual([true]);
+
+    pressKey(window, "a", { code: "KeyA", shiftKey: true, ctrlKey: true });
+
+    expect(h.designModeChanges).toEqual([true, false]);
+    // A bare Cmd+A is the page's own shortcut and must not toggle.
+    pressKey(window, "a", { code: "KeyA", metaKey: true });
+    expect(h.designModeChanges).toEqual([true, false]);
+  });
+
+  it("falls back per colour when the page cannot parse a palette value", () => {
+    const h = harness();
+
+    // jsdom's CSS has no `supports`, which the overlay treats as "unsupported"
+    // — stub the whole global, keeping `escape` for the selector builder.
+    vi.stubGlobal("CSS", {
+      escape: CSS.escape,
+      supports: (_property: string, value: string) => value === "rgb(4, 5, 6)",
     });
+
+    h.overlay.setDesignMode(true, fullPalette);
+    annotate(h, place(document.getElementById("cta")!), "hi");
+
+    const badge = badges(h)[0]!;
+
+    // The bad accent falls back alone; a good accentForeground still lands.
+    // jsdom normalises colours to rgb(), so the default reads back expanded.
+    expect(badge.style.backgroundColor).toBe("rgb(109, 40, 217)");
+    expect(badge.style.color).toBe("rgb(4, 5, 6)");
+  });
+
+  it("updates the palette without enabling annotation mode", () => {
+    const h = harness();
+    const button = place(document.getElementById("cta")!);
+
+    vi.stubGlobal("CSS", {
+      escape: CSS.escape,
+      supports: (_property: string, value: string) => value.startsWith("rgb("),
+    });
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "palette");
+    h.overlay.setDesignMode(false);
+
+    h.overlay.setAnnotationPalette(fullPalette);
+
+    expect(badges(h)[0]!.style.backgroundColor).toBe("rgb(1, 2, 3)");
+    expect(
+      h.shadow().querySelector<HTMLElement>('[data-slot="annotation-frame"]')!
+        .style.display,
+    ).toBe("none");
+    expect(
+      h.shadow().querySelector<HTMLElement>('[data-slot="annotation-markers"]')!
+        .style.pointerEvents,
+    ).toBe("none");
+    expect(h.designModeChanges).toEqual([]);
+  });
+
+  it("shows the mode frame and pill only while annotating", () => {
+    const h = harness();
+    const frame = () =>
+      h.shadow().querySelector<HTMLElement>('[data-slot="annotation-frame"]')!;
+    const pill = () =>
+      h.shadow().querySelector<HTMLElement>('[data-slot="annotation-pill"]')!;
+
+    h.overlay.setDesignMode(true);
+
+    expect(frame().style.display).toBe("block");
+    expect(pill().textContent).toContain("Esc to exit");
+
+    h.overlay.setDesignMode(false);
+
+    expect(frame().style.display).toBe("none");
+    expect(pill().style.display).toBe("none");
   });
 
-  it("settles the overlay before a capture and acks what the page then holds", () => {
-    const { overlay, shadow, captures } = harness();
+  it("labels the hover box with the tag, first class, size and source", () => {
+    const h = harness();
     const button = document.getElementById("cta")!;
 
+    button.classList.add("primary-cta", "ignored");
+    button.setAttribute("data-source", "src/cta.tsx:9");
+    place(button, 40, 40);
+
+    h.overlay.setDesignMode(true);
+    hoverPageElement(button);
+
+    const label = h
+      .shadow()
+      .querySelector<HTMLElement>('[data-slot="annotation-highlight-label"]')!;
+
+    expect(label.hidden).toBe(false);
+    expect(label.textContent).toBe("button.primary-cta · 40×20 · src/cta.tsx:9");
+  });
+
+  it("saves a non-empty draft on prepareCapture and hides all chrome but the marks", () => {
+    const h = harness();
+    const button = place(document.getElementById("cta")!);
+
     Object.defineProperty(window, "innerWidth", { configurable: true, value: 900 });
 
-    overlay.setDesignMode(true);
-    button.dispatchEvent(
-      new MouseEvent("pointermove", { bubbles: true, cancelable: true, composed: true }),
-    );
+    h.overlay.setDesignMode(true);
+    hoverPageElement(button);
     clickPageElement(button);
-    clickPageElement(shadow().querySelector('[data-slot="annotation-badge"]')!);
+    typeDraft(h, "typed as the shot was asked for");
+
+    h.overlay.prepareCapture();
+
+    // The draft the user was still typing has to reach the payload — a Send
+    // driven from the toolbar never blurs the textarea.
+    expect(h.captures).toHaveLength(1);
+    expect(h.captures[0]).toEqual({
+      annotations: [
+        expect.objectContaining({ index: 1, comment: "typed as the shot was asked for" }),
+      ],
+      viewport: { width: 900, height: window.innerHeight, dpr: window.devicePixelRatio },
+    });
+
+    const shadow = h.shadow();
+
+    for (const slot of [
+      "annotation-editor",
+      "annotation-highlight",
+      "annotation-highlight-label",
+      "annotation-frame",
+      "annotation-pill",
+    ]) {
+      const element = shadow.querySelector<HTMLElement>(`[data-slot="${slot}"]`)!;
+      expect(element.hidden === true || element.style.display === "none").toBe(true);
+    }
 
-    const comment = shadow().querySelector<HTMLInputElement>(
-      '[data-slot="annotation-comment"]',
+    // Marks stay in the shot: the numbered rows in the prompt point at them.
+    expect(badges(h)[0]!.style.display).not.toBe("none");
+    expect(
+      shadow.querySelector<HTMLElement>('[data-slot="annotation-outline"]')!.style
+        .display,
+    ).not.toBe("none");
+
+    // The shot is done: the mode chrome comes back, still annotating.
+    h.overlay.finishCapture();
+    expect(
+      shadow.querySelector<HTMLElement>('[data-slot="annotation-frame"]')!.style.display,
+    ).toBe("block");
+  });
+
+  it("discards an empty draft on prepareCapture instead of inventing a mark", () => {
+    const h = harness();
+
+    h.overlay.setDesignMode(true);
+    clickPageElement(place(document.getElementById("cta")!));
+    h.overlay.prepareCapture();
+
+    expect(h.captures[0]?.annotations).toEqual([]);
+    expect(h.annotationChanges).toHaveLength(0);
+  });
+
+  it("hides fully offscreen marks and refreshes their positions synchronously for capture", () => {
+    const h = harness();
+    const button = place(document.getElementById("cta")!, -60, -60);
+
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "offscreen");
+
+    const outline = h.shadow().querySelector<HTMLElement>(
+      '[data-slot="annotation-outline"]',
     )!;
-    const highlight = shadow().querySelector<HTMLElement>(
-      '[data-slot="annotation-highlight"]',
+    const badge = badges(h)[0]!;
+
+    expect(outline.style.display).toBe("none");
+    expect(badge.style.display).toBe("none");
+
+    vi.mocked(button.getBoundingClientRect).mockReturnValue(rectAt(80, 90));
+    h.overlay.prepareCapture();
+
+    expect(outline.style.display).toBe("block");
+    expect(outline.style.left).toBe("80px");
+    expect(outline.style.top).toBe("90px");
+    expect(badge.style.display).toBe("flex");
+    expect(h.captures[0]?.annotations).toHaveLength(1);
+  });
+
+  it("keeps the badge usable when its target is smaller than the badge", () => {
+    const h = harness();
+    const button = document.getElementById("cta")!;
+
+    vi.spyOn(button, "getBoundingClientRect").mockReturnValue(
+      rectAt(40, 40, 16, 16),
+    );
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "small target");
+
+    const outline = h.shadow().querySelector<HTMLElement>(
+      '[data-slot="annotation-outline"]',
     )!;
+    const badge = badges(h)[0]!;
+
+    expect(outline.style.width).toBe("16px");
+    expect(outline.style.height).toBe("16px");
+    expect(badge.style.display).toBe("flex");
+    expect(badge.style.left).toBe("46px");
+    expect(badge.style.top).toBe("30px");
+  });
 
-    comment.value = "Too small to hit";
+  it("keeps the badge visible when only a sliver of its target intersects the viewport", () => {
+    const h = harness();
+    const button = document.getElementById("cta")!;
 
-    overlay.prepareCapture();
+    vi.spyOn(button, "getBoundingClientRect").mockReturnValue(
+      rectAt(-18, 40, 20, 20),
+    );
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "partially visible");
 
-    // Nothing of the overlay's own chrome may reach the screenshot, and the
-    // comment being typed has to reach the payload — a keyboard-driven Send
-    // never blurs the input, so committing on the way out is the only chance.
-    expect(comment.hidden).toBe(true);
-    expect(highlight.hidden).toBe(true);
-    expect(captures[captures.length - 1]).toEqual({
-      annotations: [expect.objectContaining({ index: 1, comment: "Too small to hit" })],
-      // Measured now: the panel may have been dragged since the mark was made.
-      viewport: { width: 900, height: window.innerHeight, dpr: window.devicePixelRatio },
+    const outline = h.shadow().querySelector<HTMLElement>(
+      '[data-slot="annotation-outline"]',
+    )!;
+    const badge = badges(h)[0]!;
+
+    expect(outline.style.left).toBe("0px");
+    expect(outline.style.width).toBe("2px");
+    expect(badge.style.display).toBe("flex");
+    expect(badge.style.left).toBe("8px");
+  });
+
+  it("clips marks and badge placement to nested scrolling ancestors", () => {
+    const h = harness();
+    const outer = document.createElement("section");
+    const inner = document.createElement("section");
+    const button = document.createElement("button");
+
+    outer.style.overflowX = "auto";
+    outer.style.overflowY = "auto";
+    inner.style.overflowX = "hidden";
+    inner.style.overflowY = "hidden";
+    outer.append(inner);
+    inner.append(button);
+    document.querySelector("main")!.append(outer);
+    clip(outer, 40, 40, 120, 120);
+    clip(inner, 60, 60, 60, 60);
+    clip(button, 20, 20, 120, 120);
+
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "nested");
+
+    const outline = h.shadow().querySelector<HTMLElement>(
+      '[data-slot="annotation-outline"]',
+    )!;
+    const badge = badges(h)[0]!;
+
+    expect(outline.style.left).toBe("60px");
+    expect(outline.style.top).toBe("60px");
+    expect(outline.style.width).toBe("60px");
+    expect(outline.style.height).toBe("60px");
+    expect(Number.parseFloat(badge.style.left)).toBeGreaterThanOrEqual(60);
+    expect(Number.parseFloat(badge.style.left) + 20).toBeLessThanOrEqual(120);
+    expect(Number.parseFloat(badge.style.top)).toBeGreaterThanOrEqual(60);
+    expect(Number.parseFloat(badge.style.top) + 20).toBeLessThanOrEqual(120);
+    expect(badge.style.left).toBe("100px");
+    expect(badge.style.top).toBe("60px");
+
+    vi.mocked(button.getBoundingClientRect).mockReturnValue(
+      rectAt(130, 130, 20, 20),
+    );
+    h.overlay.prepareCapture();
+
+    expect(outline.style.display).toBe("none");
+    expect(badge.style.display).toBe("none");
+  });
+
+  it("rebinds a uniquely selected DOM replacement and keeps its stable annotation id", () => {
+    const h = harness();
+    const original = place(document.getElementById("cta")!, 40, 40);
+    h.overlay.setDesignMode(true);
+    annotate(h, original, "Original comment");
+    const originalId = h.latest()[0]!.id;
+    clickPageElement(original);
+    expect(editorVisible(h)).toBe(true);
+
+    original.remove();
+    const replacement = document.createElement("button");
+    replacement.id = "cta";
+    replacement.textContent = "Replacement";
+    place(replacement, 120, 130);
+    document.querySelector("main")!.append(replacement);
+
+    clickPageElement(replacement);
+
+    expect(editorInput(h).value).toBe("Original comment");
+    expect(editor(h).style.left).toBe("120px");
+    typeDraft(h, "Updated comment");
+    pressKey(editorInput(h), "Enter");
+
+    expect(h.latest()).toHaveLength(1);
+    expect(h.latest()[0]).toMatchObject({
+      id: originalId,
+      index: 1,
+      selector: "#cta",
+      rect: { x: 120, y: 130 },
+      comment: "Updated comment",
     });
   });
 
+  it("does not rebind a disconnected annotation to an ambiguous selector", () => {
+    const h = harness();
+    const original = place(document.getElementById("cta")!);
+    h.overlay.setDesignMode(true);
+    annotate(h, original, "Original comment");
+    original.remove();
+
+    const first = document.createElement("button");
+    const second = document.createElement("button");
+    first.id = "cta";
+    second.id = "cta";
+    place(first, 80, 80);
+    place(second, 120, 120);
+    document.querySelector("main")!.append(first, second);
+
+    clickPageElement(first);
+
+    expect(editorVisible(h)).toBe(true);
+    expect(editorInput(h).value).toBe("");
+    expect(editorButton(h, "delete").style.display).toBe("none");
+    expect(h.latest()).toHaveLength(1);
+    expect(h.latest()[0]?.comment).toBe("Original comment");
+  });
+
+  it("reclaims the shared badge corner immediately after deleting an earlier mark", () => {
+    const h = harness();
+    const button = place(document.getElementById("cta")!, 40, 40);
+    const paragraph = place(document.getElementById("copy")!, 40, 40);
+
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "first");
+    annotate(h, paragraph, "second");
+    const survivingBadge = badges(h)[1]!;
+    expect(survivingBadge.style.left).toBe("46px");
+
+    clickPageElement(button);
+    editorButton(h, "delete").click();
+
+    expect(survivingBadge.textContent).toBe("1");
+    expect(survivingBadge.style.left).toBe("70px");
+    expect(h.latest()).toHaveLength(1);
+  });
+
   it("drops the hover highlight when the pointer leaves the page", () => {
-    const { overlay, shadow } = harness();
-    const button = document.getElementById("cta")!;
-    const hover = (target: Element) =>
-      target.dispatchEvent(
-        new MouseEvent("pointermove", { bubbles: true, cancelable: true, composed: true }),
-      );
+    const h = harness();
+    const button = place(document.getElementById("cta")!);
     const leave = (target: Element, relatedTarget: Element | null) =>
       target.dispatchEvent(
         new MouseEvent("mouseout", {
@@ -231,12 +798,12 @@ describe("annotation overlay", () => {
         }),
       );
 
-    overlay.setDesignMode(true);
-    hover(button);
+    h.overlay.setDesignMode(true);
+    hoverPageElement(button);
 
-    const highlight = shadow().querySelector<HTMLElement>(
-      '[data-slot="annotation-highlight"]',
-    )!;
+    const highlight = h
+      .shadow()
+      .querySelector<HTMLElement>('[data-slot="annotation-highlight"]')!;
 
     expect(highlight.hidden).toBe(false);
 
@@ -253,71 +820,17 @@ describe("annotation overlay", () => {
   });
 
   it("ignores clicks that land on its own overlay", () => {
-    const { overlay, annotationChanges } = harness();
-
-    overlay.setDesignMode(true);
-
-    const host = document.querySelector(annotationOverlayHostTag)!;
-
-    clickPageElement(host);
-
-    expect(annotationChanges).toHaveLength(0);
-  });
-
-  it("sends a comment once it is committed, not on every keystroke", () => {
-    const { overlay, shadow, annotationChanges, latest } = harness();
-
-    overlay.setDesignMode(true);
-    clickPageElement(document.getElementById("cta")!);
+    const h = harness();
 
-    const badge = shadow().querySelector<HTMLElement>('[data-slot="annotation-badge"]')!;
-    const comment = shadow().querySelector<HTMLInputElement>(
-      '[data-slot="annotation-comment"]',
-    )!;
-
-    expect(badge.textContent).toBe("1");
-    expect(comment.hidden).toBe(true);
-
-    clickPageElement(badge);
-    expect(comment.hidden).toBe(false);
-
-    const changesBeforeTyping = annotationChanges.length;
-
-    comment.value = "This button is too small";
-    comment.dispatchEvent(new Event("input", { bubbles: true }));
-
-    // Typing must not cost an IPC round trip per character.
-    expect(annotationChanges).toHaveLength(changesBeforeTyping);
-
-    // Enter closes the bubble. The overlay's own keydown handler runs in the
-    // capture phase at the window, so it is the only one that can see this.
-    pressKey(comment, "Enter");
+    h.overlay.setDesignMode(true);
+    clickPageElement(document.querySelector(annotationOverlayHostTag)!);
 
-    expect(comment.hidden).toBe(true);
-    expect(latest()[0]!.comment).toBe("This button is too small");
-  });
-
-  it("closes an open bubble on Escape before it stops marking, keeping the text", () => {
-    const { overlay, shadow, designModeChanges, latest } = harness();
-
-    overlay.setDesignMode(true);
-    clickPageElement(document.getElementById("cta")!);
-    clickPageElement(shadow().querySelector('[data-slot="annotation-badge"]')!);
-
-    const comment = shadow().querySelector<HTMLInputElement>(
-      '[data-slot="annotation-comment"]',
-    )!;
-
-    comment.value = "Too small";
-    pressKey(comment, "Escape");
-
-    expect(comment.hidden).toBe(true);
-    expect(designModeChanges).toEqual([]);
-    expect(latest()[0]!.comment).toBe("Too small");
+    expect(shadowRoots[0]!.querySelector('[data-slot="annotation-editor"]')).toBeNull();
+    expect(h.annotationChanges).toHaveLength(0);
   });
 
   it("marks the element inside the page's own shadow root, not its host", () => {
-    const { overlay, latest } = harness();
+    const h = harness();
     const widget = document.createElement("div");
 
     widget.id = "widget";
@@ -326,85 +839,141 @@ describe("annotation overlay", () => {
     const inner = document.createElement("a");
 
     inner.textContent = "Inner link";
+    inner.href = "https://example.com";
     widget.attachShadow({ mode: "open" }).append(inner);
+    place(inner, 60, 60);
 
-    overlay.setDesignMode(true);
+    h.overlay.setDesignMode(true);
     clickPageElement(inner);
+    typeDraft(h, "shadow");
+    pressKey(editorInput(h), "Enter");
 
     // `event.target` is retargeted to the host at the window; the composed
     // path still names what the user actually pointed at.
-    expect(latest()[0]).toMatchObject({ tag: "a", text: "Inner link" });
+    expect(h.latest()[0]).toMatchObject({ tag: "a", text: "Inner link" });
   });
 
-  it("keeps a marker on its element as the page scrolls", async () => {
-    const { overlay, shadow } = harness();
+  it("keeps a mark on its element as the page scrolls", async () => {
+    const h = harness();
     const button = document.getElementById("cta")!;
     const measure = vi.spyOn(button, "getBoundingClientRect");
 
+    Object.defineProperty(window, "innerHeight", { configurable: true, value: 768 });
     measure.mockReturnValue(rectAt(12, 200));
-    overlay.setDesignMode(true);
-    clickPageElement(button);
+    h.overlay.setDesignMode(true);
+    annotate(h, button, "scroll test");
 
-    const marker = shadow().querySelector<HTMLElement>('[data-slot="annotation-marker"]')!;
+    const outline = h
+      .shadow()
+      .querySelector<HTMLElement>('[data-slot="annotation-outline"]')!;
 
-    expect(marker.style.top).toBe("200px");
+    expect(outline.style.top).toBe("200px");
 
     measure.mockReturnValue(rectAt(12, 40));
     window.dispatchEvent(new Event("scroll"));
     await nextFrames();
 
-    // A marker pinned to where the element was would sit over the wrong thing
-    // in the page and on S3's screenshot.
-    expect(marker.style.top).toBe("40px");
+    // A mark pinned to where the element was would sit over the wrong thing
+    // in the page and on the screenshot.
+    expect(outline.style.top).toBe("40px");
 
-    // An element a re-render took away has no position to sit at; the marker
+    // An element a re-render took away has no position to sit at; the mark
     // must not fall back to the top-left corner of the viewport.
     button.remove();
     window.dispatchEvent(new Event("scroll"));
     await nextFrames();
 
-    expect(marker.style.display).toBe("none");
+    expect(outline.style.display).toBe("none");
+    expect(badges(h)[0]!.style.display).toBe("none");
   });
 
-  it("arms its markers when the overlay is built after design mode was on", () => {
-    const { overlay, shadow } = harness();
-    const root = document.documentElement;
+  it("moves the open editor with its element on scroll", async () => {
+    const h = harness();
     const button = document.getElementById("cta")!;
+    const measure = vi.spyOn(button, "getBoundingClientRect");
+
+    measure.mockReturnValue(rectAt(40, 40));
+    // Tests that reshape the viewport leak it (defineProperty survives
+    // restoreAllMocks), so this one states its own height.
+    Object.defineProperty(window, "innerHeight", {
+      configurable: true,
+      value: 600,
+    });
+    h.overlay.setDesignMode(true);
+    clickPageElement(button);
+
+    expect(editor(h).style.top).toBe(`${40 + 20 + 8}px`);
+
+    measure.mockReturnValue(rectAt(40, 200));
+    window.dispatchEvent(new Event("scroll"));
+    await nextFrames();
+
+    // Scrolling is not blocked while a comment is being typed, so an editor
+    // that stayed behind would be writing about the wrong element.
+    expect(editor(h).style.top).toBe(`${200 + 20 + 8}px`);
+  });
+
+  it("moves the hover highlight and its label with the element on scroll", async () => {
+    const h = harness();
+    const button = document.getElementById("cta")!;
+    const measure = vi.spyOn(button, "getBoundingClientRect");
+
+    measure.mockReturnValue(rectAt(40, 40));
+    h.overlay.setDesignMode(true);
+    hoverPageElement(button);
+
+    const highlight = h
+      .shadow()
+      .querySelector<HTMLElement>('[data-slot="annotation-highlight"]')!;
+
+    expect(highlight.style.top).toBe("40px");
+
+    measure.mockReturnValue(rectAt(40, 120));
+    window.dispatchEvent(new Event("scroll"));
+    await nextFrames();
+
+    expect(highlight.style.top).toBe("120px");
+  });
+
+  it("arms its marks when the overlay is built after design mode was on", () => {
+    const h = harness();
+    const root = document.documentElement;
+    const button = place(document.getElementById("cta")!);
 
     // A preload runs before the document has a root element to hang the
     // overlay on, and main re-applies design mode the moment it reports in.
     root.remove();
-    overlay.setDesignMode(true);
+    h.overlay.setDesignMode(true);
     document.append(root);
 
     clickPageElement(button);
 
     expect(
-      shadow().querySelector<HTMLElement>('[data-slot="annotation-markers"]')!.style
+      h.shadow().querySelector<HTMLElement>('[data-slot="annotation-markers"]')!.style
         .pointerEvents,
     ).toBe("auto");
   });
 
   it("clears every mark on demand", () => {
-    const { overlay, latest, shadow } = harness();
+    const h = harness();
 
-    overlay.setDesignMode(true);
-    clickPageElement(document.getElementById("cta")!);
-    overlay.clearAnnotations();
+    h.overlay.setDesignMode(true);
+    annotate(h, place(document.getElementById("cta")!), "gone");
+    h.overlay.clearAnnotations();
 
-    expect(latest()).toEqual([]);
-    expect(shadow().querySelector('[data-slot="annotation-badge"]')).toBeNull();
+    expect(h.latest()).toEqual([]);
+    expect(badges(h)).toHaveLength(0);
   });
 
   it("takes its overlay and its listeners with it when disposed", () => {
-    const { overlay, annotationChanges } = harness();
+    const h = harness();
 
-    overlay.setDesignMode(true);
-    overlay.dispose();
+    h.overlay.setDesignMode(true);
+    h.overlay.dispose();
 
     expect(document.querySelector(annotationOverlayHostTag)).toBeNull();
 
     clickPageElement(document.getElementById("cta")!);
-    expect(annotationChanges).toHaveLength(0);
+    expect(h.annotationChanges).toHaveLength(0);
   });
 });
diff --git a/apps/desktop/electron/browser-annotation-overlay.ts b/apps/desktop/electron/browser-annotation-overlay.ts
index cd4b3122..b13049a1 100644
--- a/apps/desktop/electron/browser-annotation-overlay.ts
+++ b/apps/desktop/electron/browser-annotation-overlay.ts
@@ -1,17 +1,30 @@
-import { describeAnnotatedElement } from "./browser-annotation";
+import {
+  describeAnnotatedElement,
+  maxCommentLength,
+  readSource,
+  resolveAnnotationTarget,
+} from "./browser-annotation";
 import type {
   BrowserAnnotationElement,
+  BrowserAnnotationPalette,
   BrowserAnnotationViewport,
 } from "@/shared/browser-protocol";
 
 /**
- * The design-mode overlay, as it runs inside the embedded page's isolated
+ * The annotation-mode overlay, as it runs inside the embedded page's isolated
  * world: a host element under `<html>` with a **closed** shadow root holding
- * the hover highlight, the numbered markers and their comment bubbles.
+ * the hover highlight, the mode chrome (frame + pill), the saved marks
+ * (outline + numbered badge) and the comment editor.
  *
  * Electron-free on purpose — the preload only wires it to IPC — so every
  * interaction rule below is testable in jsdom.
  *
+ * Lifecycle (decision 1 of `.scratch/browser-annotation-v2/PRD.md`): a click
+ * opens a focused *draft* editor — not yet an annotation, and main hears
+ * nothing until Save/Enter commits it. Cancel/Esc discards without a trace.
+ * Clicking a saved element or its badge re-opens that annotation's editor
+ * (with Delete); an empty comment can never be saved.
+ *
  * Two properties of the host page drive the implementation:
  *
  * - **It is hostile.** The shadow root is closed, so page script can see the
@@ -25,26 +38,54 @@ import type {
 
 export const annotationOverlayHostTag = "pigui-annotation-overlay";
 
-type MarkerEntry = {
+type AnnotationEntry = {
   annotation: BrowserAnnotationElement;
-  /** Kept so the marker can be re-measured; the rect it reported cannot. */
+  /** Kept so outline and badge can be re-measured; the rect it reported cannot. */
+  element: Element;
+  outline: HTMLElement;
+  badge: HTMLButtonElement;
+};
+
+/** The one open editor: what it annotates, and what it started with. */
+type EditorState = {
   element: Element;
-  marker: HTMLElement;
-  comment: HTMLInputElement;
+  annotationId: string | null;
+  savedText: string;
 };
 
 export type BrowserAnnotationOverlay = {
-  setDesignMode(enabled: boolean): void;
+  setDesignMode(enabled: boolean, palette?: BrowserAnnotationPalette): void;
+  setAnnotationPalette(palette: BrowserAnnotationPalette): void;
   clearAnnotations(): void;
   /**
    * Put the overlay out of shot and say what it holds, so main can photograph
-   * the page without the overlay's own chrome on it.
+   * the page without the overlay's own chrome on it. A draft worth keeping is
+   * saved first: asking for the shot is intent to send.
    */
   prepareCapture(): void;
+  /** The shot is done — the mode chrome `prepareCapture` hid comes back. */
+  finishCapture(): void;
   dispose(): void;
 };
 
-const accent = "#6d28d9";
+type OverlayColors = {
+  accent: string;
+  accentForeground: string;
+  surface: string;
+  foreground: string;
+  border: string;
+  muted: string;
+};
+
+const defaultColors: OverlayColors = {
+  accent: "#6d28d9",
+  accentForeground: "#ffffff",
+  surface: "#ffffff",
+  foreground: "#111827",
+  border: "#e5e7eb",
+  muted: "#6b7280",
+};
+
 const overlayFont =
   '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif';
 /**
@@ -60,6 +101,12 @@ const pointerEvents = [
   "contextmenu",
 ];
 
+const editorWidthPx = 280;
+
+function clampValue(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), Math.max(min, max));
+}
+
 function applyStyles(element: HTMLElement, styles: Record<string, string>) {
   for (const [property, value] of Object.entries(styles)) {
     // Important throughout: the host element sits in the page's own tree, so
@@ -68,6 +115,35 @@ function applyStyles(element: HTMLElement, styles: Record<string, string>) {
   }
 }
 
+/** A palette colour is honoured only if this page's CSS engine can parse it. */
+function supportsColor(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    typeof CSS !== "undefined" &&
+    typeof CSS.supports === "function" &&
+    CSS.supports("color", value)
+  );
+}
+
+/**
+ * The renderer's palette, field by field against the defaults: a token the
+ * page cannot parse falls back alone, so one bad colour never costs the rest.
+ */
+function resolveOverlayPalette(palette: BrowserAnnotationPalette): OverlayColors {
+  return {
+    accent: supportsColor(palette.accent) ? palette.accent : defaultColors.accent,
+    accentForeground: supportsColor(palette.accentForeground)
+      ? palette.accentForeground
+      : defaultColors.accentForeground,
+    surface: supportsColor(palette.surface) ? palette.surface : defaultColors.surface,
+    foreground: supportsColor(palette.foreground)
+      ? palette.foreground
+      : defaultColors.foreground,
+    border: supportsColor(palette.border) ? palette.border : defaultColors.border,
+    muted: supportsColor(palette.muted) ? palette.muted : defaultColors.muted,
+  };
+}
+
 export function createAnnotationOverlay(options: {
   document: Document;
   onAnnotationsChange: (
@@ -86,15 +162,133 @@ export function createAnnotationOverlay(options: {
   // cannot swallow the events design mode needs.
   const listenerTarget: EventTarget = doc.defaultView ?? doc;
   const annotations: BrowserAnnotationElement[] = [];
-  const markers = new Map<number, MarkerEntry>();
+  const entries = new Map<string, AnnotationEntry>();
 
+  let colors: OverlayColors = { ...defaultColors };
   let designMode = false;
   let host: HTMLElement | null = null;
+  let shadowRoot: ShadowRoot | null = null;
   let highlight: HTMLElement | null = null;
+  let highlightLabel: HTMLElement | null = null;
   let markerLayer: HTMLElement | null = null;
-  let openComment: number | null = null;
+  let frame: HTMLElement | null = null;
+  let pill: HTMLElement | null = null;
+  let editorBox: HTMLElement | null = null;
+  let editorText: HTMLTextAreaElement | null = null;
+  let saveButton: HTMLButtonElement | null = null;
+  let deleteButton: HTMLButtonElement | null = null;
+  let editor: EditorState | null = null;
+  /** The resolved target of the last pointermove — the base ↑ climbs from. */
+  let resolvedTarget: Element | null = null;
+  /** What is actually framed now: the resolved target, or an ancestor ↑ chose. */
+  let hoverTarget: Element | null = null;
   let markerSyncFrame = 0;
 
+  function applyDesignMode(enabled: boolean) {
+    designMode = enabled;
+
+    if (enabled) {
+      ensureHost();
+      setModeAffordanceVisible(true);
+    } else {
+      hideHighlight();
+      closeEditor();
+      resolvedTarget = null;
+      hoverTarget = null;
+      setModeAffordanceVisible(false);
+    }
+
+    // Marks only take pointer events while marking; once annotation mode is
+    // off the page has to be fully usable again with the marks still on it.
+    if (markerLayer) {
+      applyStyles(markerLayer, { "pointer-events": enabled ? "auto" : "none" });
+    }
+  }
+
+  function setModeAffordanceVisible(visible: boolean) {
+    if (frame) {
+      applyStyles(frame, { display: visible ? "block" : "none" });
+    }
+    if (pill) {
+      applyStyles(pill, { display: visible ? "block" : "none" });
+    }
+  }
+
+  // -- Colour-dependent styles, reapplied whenever a new palette lands.
+
+  function styleHighlight() {
+    applyStyles(highlight!, {
+      border: `2px solid ${colors.accent}`,
+      background: `color-mix(in srgb, ${colors.accent} 12%, transparent)`,
+    });
+  }
+
+  function styleHighlightLabel() {
+    applyStyles(highlightLabel!, {
+      background: colors.foreground,
+      color: colors.surface,
+    });
+  }
+
+  function styleFrame() {
+    applyStyles(frame!, {
+      "box-shadow": `inset 0 0 0 2px ${colors.accent}`,
+    });
+  }
+
+  function stylePill() {
+    applyStyles(pill!, {
+      background: colors.surface,
+      color: colors.foreground,
+      border: `1px solid ${colors.border}`,
+    });
+  }
+
+  function styleOutline(outline: HTMLElement) {
+    applyStyles(outline, { border: `1.5px solid ${colors.accent}` });
+  }
+
+  function styleBadge(badge: HTMLButtonElement) {
+    applyStyles(badge, {
+      background: colors.accent,
+      color: colors.accentForeground,
+    });
+  }
+
+  function styleEditor() {
+    applyStyles(editorBox!, {
+      background: colors.surface,
+      border: `1px solid ${colors.border}`,
+    });
+    applyStyles(editorText!, {
+      background: colors.surface,
+      color: colors.foreground,
+      border: `1px solid ${colors.border}`,
+    });
+    applyStyles(saveButton!, {
+      background: colors.accent,
+      color: colors.accentForeground,
+    });
+    applyStyles(deleteButton!, { color: colors.muted });
+  }
+
+  function restyle() {
+    if (highlight) styleHighlight();
+    if (highlightLabel) styleHighlightLabel();
+    if (frame) styleFrame();
+    if (pill) stylePill();
+    if (editorBox) styleEditor();
+    for (const entry of entries.values()) {
+      styleOutline(entry.outline);
+      styleBadge(entry.badge);
+    }
+  }
+
+  function applyAnnotationPalette(palette: BrowserAnnotationPalette) {
+    colors = resolveOverlayPalette(palette);
+    restyle();
+  }
+
   function ensureHost() {
     if (host) {
       return host;
@@ -122,6 +316,38 @@ export function createAnnotationOverlay(options: {
     });
 
     const root = host.attachShadow({ mode: "closed" });
+    shadowRoot = root;
+
+    // The frame and pill are how the user knows the page is being annotated
+    // at all — they only exist while the mode is on, and never take events.
+    frame = doc.createElement("div");
+    frame.dataset.slot = "annotation-frame";
+    applyStyles(frame, {
+      position: "fixed",
+      inset: "0",
+      display: designMode ? "block" : "none",
+      "pointer-events": "none",
+    });
+    styleFrame();
+
+    pill = doc.createElement("div");
+    pill.dataset.slot = "annotation-pill";
+    pill.textContent = "Annotating · Esc to exit";
+    applyStyles(pill, {
+      position: "fixed",
+      top: "10px",
+      left: "50%",
+      transform: "translateX(-50%)",
+      margin: "0",
+      padding: "4px 12px",
+      "border-radius": "999px",
+      display: designMode ? "block" : "none",
+      font: `600 11px/16px ${overlayFont}`,
+      "white-space": "nowrap",
+      "box-shadow": "0 1px 3px rgba(0, 0, 0, 0.35)",
+      "pointer-events": "none",
+    });
+    stylePill();
 
     highlight = doc.createElement("div");
     highlight.dataset.slot = "annotation-highlight";
@@ -129,11 +355,26 @@ export function createAnnotationOverlay(options: {
     applyStyles(highlight, {
       position: "fixed",
       "box-sizing": "border-box",
-      border: `2px solid ${accent}`,
       "border-radius": "2px",
-      background: "rgba(109, 40, 217, 0.12)",
       "pointer-events": "none",
     });
+    styleHighlight();
+
+    // The element under the pointer, named: `tag.firstClass · W×H`, with the
+    // dev-server source location when one was stamped.
+    highlightLabel = doc.createElement("div");
+    highlightLabel.dataset.slot = "annotation-highlight-label";
+    highlightLabel.hidden = true;
+    applyStyles(highlightLabel, {
+      position: "fixed",
+      margin: "0",
+      padding: "1px 6px",
+      "border-radius": "3px",
+      font: `500 10px/14px ${overlayFont}`,
+      "white-space": "nowrap",
+      "pointer-events": "none",
+    });
+    styleHighlightLabel();
 
     markerLayer = doc.createElement("div");
     markerLayer.dataset.slot = "annotation-markers";
@@ -141,13 +382,13 @@ export function createAnnotationOverlay(options: {
       position: "absolute",
       top: "0",
       left: "0",
-      // Design mode can be turned on before the document has a root element to
-      // hang this on, so the layer arms itself from the current state rather
+      // Annotation mode can be turned on before the document has a root element
+      // to hang this on, so the layer arms itself from the current state rather
       // than waiting for the next toggle.
       "pointer-events": designMode ? "auto" : "none",
     });
 
-    root.append(highlight, markerLayer);
+    root.append(frame, highlight, highlightLabel, markerLayer, pill);
     parent.append(host);
 
     return host;
@@ -175,26 +416,54 @@ export function createAnnotationOverlay(options: {
     );
   }
 
-  /** The element the user is pointing at, or null when it is our own overlay. */
-  function pageTarget(event: Event) {
-    // `event.target` is retargeted to the shadow host at the window, which for
-    // a page's own (open) shadow DOM would name the wrapper instead of what
-    // the user pointed at. The composed path names the real element — and
-    // stops at our host for our own closed root, which is how clicks on a
-    // badge or a bubble are still told apart from clicks on the page.
+  /**
+   * True when the event began inside our own closed shadow tree — or above
+   * the page entirely (window/document), which is where synthetic key events
+   * land. `composedPath()` stops at the host for a closed root where the spec
+   * is honoured, but Chromium has historically exposed the internals too, so
+   * the root itself is what decides, not the first path entry's name.
+   */
+  function isOverlayEvent(event: Event) {
     const [target] = event.composedPath();
 
-    return target instanceof Element && target !== host ? target : null;
+    return (
+      !(target instanceof Element) ||
+      target === host ||
+      (shadowRoot !== null && target.getRootNode() === shadowRoot)
+    );
   }
 
+  /** The element the user is pointing at, or null when it is our own overlay. */
+  function pageTarget(event: Event) {
+    return isOverlayEvent(event) ? null : (event.composedPath()[0] as Element);
+  }
+
+  // -- Hover highlight ----------------------------------------------------
+
   function hideHighlight() {
     if (highlight) {
       highlight.hidden = true;
     }
+    if (highlightLabel) {
+      highlightLabel.hidden = true;
+    }
+  }
+
+  function describeHoverTarget(element: Element) {
+    const rect = element.getBoundingClientRect();
+    const tag = element.tagName.toLowerCase();
+    const firstClass = element.classList.item(0);
+    const size = `${Math.round(rect.width)}×${Math.round(rect.height)}`;
+    const source = readSource(element);
+
+    return (
+      `${tag}${firstClass ? `.${firstClass.slice(0, 24)}` : ""} · ${size}` +
+      (source ? ` · ${source.file}:${source.line}` : "")
+    );
   }
 
   function showHighlight(element: Element) {
-    if (!ensureHost() || !highlight) {
+    if (!ensureHost() || !highlight || !highlightLabel) {
       return;
     }
 
@@ -207,98 +476,295 @@ export function createAnnotationOverlay(options: {
       height: `${rect.height}px`,
     });
     highlight.hidden = false;
+
+    highlightLabel.textContent = describeHoverTarget(element);
+
+    // Above the box by default; when there is no room up there the label goes
+    // below rather than under the toolbar.
+    const labelRect = highlightLabel.getBoundingClientRect();
+    const labelHeight = labelRect.height || highlightLabel.offsetHeight;
+    const labelWidth = labelRect.width || highlightLabel.offsetWidth;
+    const viewport = readViewport();
+    const top =
+      rect.top - labelHeight - 4 >= 4 ? rect.top - labelHeight - 4 : rect.bottom + 4;
+
+    applyStyles(highlightLabel, {
+      left: `${clampValue(rect.left, 4, Math.max(4, viewport.width - labelWidth - 4))}px`,
+      top: `${top}px`,
+    });
+    highlightLabel.hidden = false;
   }
 
+  // -- Saved marks: outline + badge ---------------------------------------
+
   /**
-   * A comment reaches main when the bubble is committed — Enter, a blur, or the
-   * bubble closing — never per keystroke: every notification is a full IPC
-   * round trip carrying the whole list.
+   * Marks are fixed to the viewport and re-measured, not pinned to where the
+   * element was when it was marked: a scroll — of the window or of any nested
+   * container — or a reflow would otherwise leave the badge sitting over
+   * something else, in the page and on the screenshot alike.
    */
-  function commitComment(entry: MarkerEntry) {
-    const value = entry.comment.value;
-
-    if (value === (entry.annotation.comment ?? "")) {
+  function positionEntries() {
+    if (!markerLayer) {
       return;
     }
 
-    if (value) {
-      entry.annotation.comment = value;
-    } else {
-      delete entry.annotation.comment;
+    const viewport = readViewport();
+    const reconciled = reconcileEntries();
+    const placed: { x: number; y: number; width: number; height: number }[] = [];
+
+    // Annotation order is creation order, so the earlier badge always wins
+    // the corner and the later one steps aside.
+    for (const annotation of annotations) {
+      const entry = entries.get(annotation.id);
+
+      if (!entry) {
+        continue;
+      }
+
+      const elementRects = visibleElementRect(entry.element, viewport);
+
+      if (!elementRects) {
+        applyStyles(entry.outline, { display: "none" });
+        applyStyles(entry.badge, { display: "none" });
+        continue;
+      }
+      const { visible, clipping } = elementRects;
+
+      applyStyles(entry.outline, {
+        display: "block",
+        left: `${visible.left}px`,
+        top: `${visible.top}px`,
+        width: `${visible.right - visible.left}px`,
+        height: `${visible.bottom - visible.top}px`,
+      });
+
+      const badgeWidth = entry.badge.offsetWidth || 20;
+      const badgeHeight = entry.badge.offsetHeight || 20;
+      const clippedX = clipping.left > 0 || clipping.right < viewport.width;
+      const clippedY = clipping.top > 0 || clipping.bottom < viewport.height;
+      const minimumX = clippedX ? clipping.left : 8;
+      const minimumY = clippedY ? clipping.top : 8;
+      const maximumX = clippedX
+        ? clipping.right - badgeWidth
+        : viewport.width - badgeWidth - 8;
+      const maximumY = clippedY
+        ? clipping.bottom - badgeHeight
+        : viewport.height - badgeHeight - 8;
+      if (maximumX < minimumX || maximumY < minimumY) {
+        applyStyles(entry.badge, { display: "none" });
+        continue;
+      }
+
+      // Centre the badge on the visible top-right corner, then keep it within
+      // the viewport or scroll-container clipping bounds.
+      let badgeX = clampValue(
+        visible.right - badgeWidth / 2,
+        minimumX,
+        maximumX,
+      );
+      const badgeY = clampValue(
+        visible.top - badgeHeight / 2,
+        minimumY,
+        maximumY,
+      );
+
+      // …and shifted left while it would sit on an earlier badge (nested
+      // elements share the corner).
+      while (
+        placed.some(
+          (other) =>
+            badgeX < other.x + other.width &&
+            other.x < badgeX + badgeWidth &&
+            badgeY < other.y + other.height &&
+            other.y < badgeY + badgeHeight,
+        )
+      ) {
+        if (badgeX - badgeWidth - 4 < minimumX) {
+          break;
+        }
+        badgeX -= badgeWidth + 4;
+      }
+
+      placed.push({ x: badgeX, y: badgeY, width: badgeWidth, height: badgeHeight });
+      applyStyles(entry.badge, {
+        display: "flex",
+        left: `${badgeX}px`,
+        top: `${badgeY}px`,
+      });
+    }
+
+    if (reconciled) {
+      notify();
     }
-    notify();
   }
 
-  function setCommentOpen(index: number | null) {
-    const open = openComment === null ? null : markers.get(openComment);
+  function visibleElementRect(
+    element: Element,
+    viewport: BrowserAnnotationViewport,
+  ) {
+    if (!element.isConnected || element.ownerDocument !== doc) {
+      return null;
+    }
 
-    if (open) {
-      commitComment(open);
+    const rect = element.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) {
+      return null;
+    }
+
+    let clipLeft = 0;
+    let clipTop = 0;
+    let clipRight = viewport.width;
+    let clipBottom = viewport.height;
+    const view = doc.defaultView;
+
+    for (
+      let ancestor = element.parentElement;
+      ancestor && clipLeft < clipRight && clipTop < clipBottom;
+      ancestor = ancestor.parentElement
+    ) {
+      if (!view) {
+        break;
+      }
+
+      const style = view.getComputedStyle(ancestor);
+      const ancestorRect = ancestor.getBoundingClientRect();
+      const overflowX = style.overflowX || style.overflow;
+      const overflowY = style.overflowY || style.overflow;
+
+      if (["hidden", "clip", "auto", "scroll"].includes(overflowX)) {
+        clipLeft = Math.max(clipLeft, ancestorRect.left + ancestor.clientLeft);
+        clipRight = Math.min(
+          clipRight,
+          ancestorRect.left + ancestor.clientLeft + ancestor.clientWidth,
+        );
+      }
+      if (["hidden", "clip", "auto", "scroll"].includes(overflowY)) {
+        clipTop = Math.max(clipTop, ancestorRect.top + ancestor.clientTop);
+        clipBottom = Math.min(
+          clipBottom,
+          ancestorRect.top + ancestor.clientTop + ancestor.clientHeight,
+        );
+      }
     }
 
-    openComment = index;
-    for (const [markerIndex, entry] of markers) {
-      entry.comment.hidden = markerIndex !== index;
+    const left = Math.max(rect.left, clipLeft);
+    const top = Math.max(rect.top, clipTop);
+    const right = Math.min(rect.right, clipRight);
+    const bottom = Math.min(rect.bottom, clipBottom);
+
+    return left < right && top < bottom
+      ? {
+          visible: { left, top, right, bottom },
+          clipping: {
+            left: clipLeft,
+            top: clipTop,
+            right: clipRight,
+            bottom: clipBottom,
+          },
+        }
+      : null;
+  }
+
+  function reconcileEntries() {
+    const owned = new Set<Element>();
+    let changed = false;
+
+    for (const entry of entries.values()) {
+      if (entry.element.isConnected && entry.element.ownerDocument === doc) {
+        owned.add(entry.element);
+      }
     }
-    if (index !== null) {
-      markers.get(index)?.comment.focus();
+
+    for (const annotation of annotations) {
+      const entry = entries.get(annotation.id);
+
+      if (!entry || (entry.element.isConnected && entry.element.ownerDocument === doc)) {
+        continue;
+      }
+
+      let matches: NodeListOf<Element>;
+      try {
+        matches = doc.querySelectorAll(entry.annotation.selector);
+      } catch {
+        continue;
+      }
+
+      if (matches.length !== 1 || owned.has(matches[0]!)) {
+        continue;
+      }
+
+      const replacement = matches[0]!;
+      const refreshed = describeAnnotatedElement(
+        replacement,
+        entry.annotation.index,
+        entry.annotation.id,
+      );
+      if (entry.annotation.comment) {
+        refreshed.comment = entry.annotation.comment;
+      }
+      const annotationIndex = annotations.indexOf(entry.annotation);
+
+      if (annotationIndex !== -1) {
+        annotations[annotationIndex] = refreshed;
+      }
+      entry.annotation = refreshed;
+      entry.element = replacement;
+      if (editor?.annotationId === refreshed.id) {
+        editor.element = replacement;
+      }
+      owned.add(replacement);
+      changed = true;
     }
+
+    return changed;
   }
 
   /**
-   * Markers are fixed to the viewport and re-measured, not pinned to where the
-   * element was when it was marked: a scroll — of the window or of any nested
-   * container — or a reflow would otherwise leave the number sitting over
-   * something else, in the page and on S3's screenshot alike.
+   * Anything anchored to an element re-measures in one frame: the marks, the
+   * open editor, and the hover box. Scrolling is not blocked while an editor
+   * is open, so it is not only the badges that would otherwise be left behind.
    */
-  function positionMarker(entry: MarkerEntry) {
-    // `hidden` cannot win against the important display below, and an element
-    // a re-render took away measures as 0,0 — which would park the number in
-    // the corner of the viewport rather than take it off screen.
-    if (!entry.element.isConnected) {
-      applyStyles(entry.marker, { display: "none" });
-      return;
+  function syncOverlayPositions() {
+    positionEntries();
+    if (editor) {
+      positionEditor(editor.element);
+    }
+    if (highlight && !highlight.hidden && hoverTarget) {
+      showHighlight(hoverTarget);
     }
-
-    const rect = entry.element.getBoundingClientRect();
-
-    applyStyles(entry.marker, {
-      display: "flex",
-      left: `${rect.x}px`,
-      top: `${rect.y}px`,
-    });
   }
 
   function scheduleMarkerSync() {
     const view = doc.defaultView;
+    const hoverVisible = highlight !== null && !highlight.hidden;
 
-    if (!view || markerSyncFrame || markers.size === 0) {
+    if (!view || markerSyncFrame || (entries.size === 0 && !editor && !hoverVisible)) {
       return;
     }
 
     markerSyncFrame = view.requestAnimationFrame(() => {
       markerSyncFrame = 0;
-      for (const entry of markers.values()) {
-        positionMarker(entry);
-      }
+      syncOverlayPositions();
     });
   }
 
-  function renderMarker(annotation: BrowserAnnotationElement, element: Element) {
+  function renderEntry(annotation: BrowserAnnotationElement, element: Element) {
     if (!ensureHost() || !markerLayer) {
       return;
     }
 
-    const marker = doc.createElement("div");
+    const outline = doc.createElement("div");
 
-    marker.dataset.slot = "annotation-marker";
-    // Placement and display both come from positionMarker below, which is the
-    // only thing that knows whether the element is still on the page.
-    applyStyles(marker, {
+    outline.dataset.slot = "annotation-outline";
+    // Position and display both come from positionEntries, which is the only
+    // thing that knows whether the element is still on the page.
+    applyStyles(outline, {
       position: "fixed",
-      "align-items": "flex-start",
-      gap: "4px",
+      "box-sizing": "border-box",
+      "border-radius": "2px",
+      "pointer-events": "none",
     });
+    styleOutline(outline);
 
     const badge = doc.createElement("button");
 
@@ -306,7 +772,7 @@ export function createAnnotationOverlay(options: {
     badge.dataset.slot = "annotation-badge";
     badge.textContent = String(annotation.index);
     applyStyles(badge, {
-      display: "flex",
+      position: "fixed",
       "align-items": "center",
       "justify-content": "center",
       "min-width": "20px",
@@ -315,72 +781,320 @@ export function createAnnotationOverlay(options: {
       padding: "0 5px",
       border: "0",
       "border-radius": "10px",
-      background: accent,
-      color: "#ffffff",
       font: `600 11px/20px ${overlayFont}`,
       cursor: "pointer",
       "box-shadow": "0 1px 3px rgba(0, 0, 0, 0.35)",
     });
+    styleBadge(badge);
     badge.addEventListener("click", () => {
-      setCommentOpen(openComment === annotation.index ? null : annotation.index);
+      const entry = entries.get(annotation.id);
+
+      if (entry) {
+        requestEditor(entry.element, entry);
+      }
     });
 
-    const comment = doc.createElement("input");
+    entries.set(annotation.id, { annotation, element, outline, badge });
+    markerLayer.append(outline, badge);
+    positionEntries();
+  }
+
+  function entryForElement(element: Element) {
+    positionEntries();
+    if (editor) {
+      positionEditor(editor.element);
+    }
+    for (const entry of entries.values()) {
+      if (entry.element === element) {
+        return entry;
+      }
+    }
+    return null;
+  }
 
-    comment.dataset.slot = "annotation-comment";
-    comment.type = "text";
-    comment.placeholder = "What is wrong here?";
-    comment.hidden = true;
-    applyStyles(comment, {
-      width: "220px",
+  /** Badges follow the list order: delete renumbers 1..N with no gaps. */
+  function renumber() {
+    annotations.forEach((annotation, position) => {
+      annotation.index = position + 1;
+      const entry = entries.get(annotation.id);
+
+      if (entry) {
+        entry.badge.textContent = String(annotation.index);
+      }
+    });
+  }
+
+  function deleteEntry(entry: AnnotationEntry) {
+    annotations.splice(annotations.indexOf(entry.annotation), 1);
+    entries.delete(entry.annotation.id);
+    entry.outline.remove();
+    entry.badge.remove();
+    renumber();
+    positionEntries();
+    notify();
+  }
+
+  // -- The comment editor --------------------------------------------------
+
+  function ensureEditor() {
+    if (editorBox || !ensureHost() || !markerLayer) {
+      return;
+    }
+
+    editorBox = doc.createElement("div");
+    editorBox.dataset.slot = "annotation-editor";
+    applyStyles(editorBox, {
+      position: "fixed",
+      display: "none",
+      "flex-direction": "column",
+      gap: "8px",
+      "box-sizing": "border-box",
+      width: `${editorWidthPx}px`,
+      padding: "10px",
+      "border-radius": "8px",
+      "box-shadow": "0 4px 16px rgba(0, 0, 0, 0.3)",
+    });
+
+    editorText = doc.createElement("textarea");
+    editorText.dataset.slot = "annotation-editor-input";
+    editorText.rows = 3;
+    // Same ceiling main applies when it rebuilds the comment on the way in.
+    editorText.maxLength = maxCommentLength;
+    editorText.placeholder = "What is wrong here?";
+    applyStyles(editorText, {
+      "box-sizing": "border-box",
+      width: "100%",
       margin: "0",
-      padding: "3px 6px",
-      border: `1px solid ${accent}`,
+      padding: "6px 8px",
       "border-radius": "4px",
-      background: "#ffffff",
-      color: "#111827",
-      font: `400 12px/16px ${overlayFont}`,
-      "box-shadow": "0 1px 3px rgba(0, 0, 0, 0.35)",
+      font: `400 13px/18px ${overlayFont}`,
+      resize: "none",
+    });
+    editorText.addEventListener("input", syncSaveEnabled);
+
+    const row = doc.createElement("div");
+    applyStyles(row, {
+      display: "flex",
+      "justify-content": "flex-end",
+      gap: "6px",
+    });
+
+    deleteButton = doc.createElement("button");
+    deleteButton.type = "button";
+    deleteButton.dataset.slot = "annotation-editor-delete";
+    deleteButton.textContent = "Delete";
+    applyStyles(deleteButton, {
+      display: "none",
+      "margin-right": "auto",
+      padding: "4px 8px",
+      border: "0",
+      "border-radius": "4px",
+      background: "transparent",
+      font: `500 12px/16px ${overlayFont}`,
+      cursor: "pointer",
+    });
+    deleteButton.addEventListener("click", () => {
+      const id = editor?.annotationId;
+      const entry = id ? entries.get(id) : undefined;
+
+      closeEditor();
+      if (entry) {
+        deleteEntry(entry);
+      }
+    });
+
+    const cancelButton = doc.createElement("button");
+    cancelButton.type = "button";
+    cancelButton.dataset.slot = "annotation-editor-cancel";
+    cancelButton.textContent = "Cancel";
+    applyStyles(cancelButton, {
+      padding: "4px 8px",
+      border: "0",
+      "border-radius": "4px",
+      background: "transparent",
+      font: `500 12px/16px ${overlayFont}`,
+      cursor: "pointer",
     });
+    cancelButton.addEventListener("click", () => closeEditor());
+
+    saveButton = doc.createElement("button");
+    saveButton.type = "button";
+    saveButton.dataset.slot = "annotation-editor-save";
+    saveButton.textContent = "Save";
+    applyStyles(saveButton, {
+      padding: "4px 10px",
+      border: "0",
+      "border-radius": "4px",
+      font: `600 12px/16px ${overlayFont}`,
+      cursor: "pointer",
+    });
+    saveButton.addEventListener("click", () => saveEditor());
 
-    const entry: MarkerEntry = { annotation, element, marker, comment };
+    row.append(deleteButton, cancelButton, saveButton);
+    editorBox.append(editorText, row);
+    markerLayer.append(editorBox);
+    styleEditor();
+  }
 
-    // A blur is a commit; Enter and Escape go through the overlay's own
-    // keydown handler, which is the only one that sees them.
-    comment.addEventListener("change", () => commitComment(entry));
-    comment.addEventListener("blur", () => commitComment(entry));
+  function syncSaveEnabled() {
+    if (!editorText || !saveButton) {
+      return;
+    }
 
-    marker.append(badge, comment);
-    markerLayer.append(marker);
-    markers.set(annotation.index, entry);
-    positionMarker(entry);
+    // A comment is required: an empty mark was a misclick, not an annotation.
+    const empty = editorText.value.trim() === "";
+    saveButton.disabled = empty;
+    applyStyles(saveButton, { opacity: empty ? "0.5" : "1" });
   }
 
-  function addAnnotation(element: Element) {
-    const annotation = describeAnnotatedElement(element, annotations.length + 1);
+  /**
+   * Below the element by default; if it would run off the viewport bottom it
+   * goes above, and if neither fits it clamps inside what room there is.
+   */
+  function positionEditor(element: Element) {
+    if (!editorBox) {
+      return;
+    }
 
-    annotations.push(annotation);
-    renderMarker(annotation, element);
-    notify();
+    const rect = element.getBoundingClientRect();
+    const viewport = readViewport();
+    const elementRects = visibleElementRect(element, viewport);
+    const anchor = elementRects?.visible ?? rect;
+    const height =
+      editorBox.getBoundingClientRect().height || editorBox.offsetHeight;
+
+    let top = anchor.bottom + 8;
+
+    if (top + height > viewport.height - 8) {
+      top = anchor.top - 8 - height;
+    }
+
+    applyStyles(editorBox, {
+      left: `${clampValue(anchor.left, 8, Math.max(8, viewport.width - editorWidthPx - 8))}px`,
+      top: `${clampValue(top, 8, Math.max(8, viewport.height - height - 8))}px`,
+    });
   }
 
-  function applyDesignMode(enabled: boolean) {
-    designMode = enabled;
+  function openEditor(element: Element, entry?: AnnotationEntry) {
+    ensureEditor();
 
-    if (enabled) {
-      ensureHost();
+    if (!editorBox || !editorText || !deleteButton) {
+      return;
+    }
+
+    editor = {
+      element,
+      annotationId: entry?.annotation.id ?? null,
+      savedText: entry?.annotation.comment ?? "",
+    };
+    editorText.value = editor.savedText;
+    applyStyles(deleteButton, { display: entry ? "block" : "none" });
+    syncSaveEnabled();
+    // Shown before it is measured: a display:none box has no height, so the
+    // flip-above check would always think there is room below.
+    applyStyles(editorBox, { display: "flex" });
+    positionEditor(element);
+    editorText.focus();
+    editorText.setSelectionRange(editorText.value.length, editorText.value.length);
+  }
+
+  /** Close without committing: a draft is discarded, an edit reverts. */
+  function closeEditor() {
+    editor = null;
+
+    if (editorBox) {
+      applyStyles(editorBox, { display: "none" });
+    }
+  }
+
+  /**
+   * Commit the draft. A click on another target while a changed non-empty
+   * draft is open does not switch — it shakes instead, so typed text is
+   * never silently lost.
+   */
+  function saveEditor() {
+    if (!editor || !editorText) {
+      return;
+    }
+
+    const comment = editorText.value.trim();
+
+    if (!comment) {
+      return;
+    }
+
+    const existing = editor.annotationId
+      ? entries.get(editor.annotationId)
+      : undefined;
+
+    if (existing) {
+      existing.annotation.comment = comment;
     } else {
-      hideHighlight();
-      setCommentOpen(null);
+      const annotation = describeAnnotatedElement(
+        editor.element,
+        annotations.length + 1,
+        crypto.randomUUID(),
+      );
+      annotation.comment = comment;
+      annotations.push(annotation);
+      renderEntry(annotation, editor.element);
     }
 
-    // Markers only take pointer events while marking; once design mode is off
-    // the page has to be fully usable again with the marks still on screen.
-    if (markerLayer) {
-      applyStyles(markerLayer, { "pointer-events": enabled ? "auto" : "none" });
+    closeEditor();
+    notify();
+  }
+
+  function shakeEditor() {
+    const reduceMotion =
+      doc.defaultView
+        ?.matchMedia?.("(prefers-reduced-motion: reduce)")
+        .matches === true;
+
+    if (reduceMotion || typeof editorBox?.animate !== "function") {
+      return;
     }
+
+    editorBox.animate(
+      [
+        { transform: "translateX(0)" },
+        { transform: "translateX(-5px)" },
+        { transform: "translateX(5px)" },
+        { transform: "translateX(-3px)" },
+        { transform: "translateX(0)" },
+      ],
+      { duration: 200 },
+    );
   }
 
+  /**
+   * Every request to open an editor — a page click or a badge. One editor at
+   * a time: a dirty unsaved draft holds its ground (with a shake); anything
+   * else is discarded in favour of the new target.
+   */
+  function requestEditor(element: Element, entry?: AnnotationEntry) {
+    if (editor && editorText) {
+      const sameTarget = entry
+        ? editor.annotationId === entry.annotation.id
+        : editor.element === element;
+
+      if (sameTarget) {
+        editorText.focus();
+        return;
+      }
+
+      if (editorText.value.trim() && editorText.value !== editor.savedText) {
+        shakeEditor();
+        return;
+      }
+
+      closeEditor();
+    }
+
+    openEditor(element, entry);
+  }
+
+  // -- Event handlers ------------------------------------------------------
+
   function handlePointerMove(event: Event) {
     if (!designMode) {
       return;
@@ -388,25 +1102,29 @@ export function createAnnotationOverlay(options: {
 
     const target = pageTarget(event);
 
-    if (target) {
-      showHighlight(target);
-    } else {
+    if (!target) {
       hideHighlight();
+      resolvedTarget = null;
+      hoverTarget = null;
+      return;
     }
+
+    // Moving the pointer re-anchors: whatever ↑ did is a per-hover adjustment,
+    // not a persistent selection.
+    resolvedTarget = resolveAnnotationTarget(target);
+    hoverTarget = resolvedTarget;
+    showHighlight(hoverTarget);
   }
 
   /**
    * The pointer left the document — `relatedTarget` is null only then, which
    * is what tells this apart from moving between two elements in the page.
-   *
-   * Purely what the user sees: the highlight follows the pointer, so it has to
-   * stop framing an element once the pointer is off the page and over the
-   * toolbar. Keeping it out of the screenshot is `prepareCapture`'s job, which
-   * covers the keyboard route this cannot.
    */
   function handlePointerOut(event: Event) {
     if (designMode && !(event as MouseEvent).relatedTarget) {
       hideHighlight();
+      resolvedTarget = null;
+      hoverTarget = null;
     }
   }
 
@@ -417,7 +1135,7 @@ export function createAnnotationOverlay(options: {
 
     const target = pageTarget(event);
 
-    // Our own badges and bubbles have to keep working, so their events are
+    // Our own badges and editor have to keep working, so their events are
     // left entirely alone.
     if (!target) {
       return;
@@ -427,42 +1145,130 @@ export function createAnnotationOverlay(options: {
     event.stopPropagation();
     event.stopImmediatePropagation();
 
-    if (event.type === "click") {
-      addAnnotation(target);
+    if (event.type !== "click") {
+      return;
     }
+
+    // A click annotates the current target — the one ↑ may have moved to an
+    // ancestor — while a click somewhere unhovered resolves fresh.
+    const resolved = resolveAnnotationTarget(target);
+    const targetElement =
+      resolved === resolvedTarget && hoverTarget ? hoverTarget : resolved;
+
+    resolvedTarget = resolved;
+    hoverTarget = targetElement;
+    requestEditor(targetElement, entryForElement(targetElement) ?? undefined);
+  }
+
+  /** ↑ walks toward the root (never to `<html>`), ↓ back toward the pointer. */
+  function moveHover(direction: -1 | 1) {
+    if (!hoverTarget) {
+      return;
+    }
+
+    if (direction < 0) {
+      const parent = hoverTarget.parentElement;
+
+      if (parent && parent !== doc.documentElement) {
+        hoverTarget = parent;
+        showHighlight(hoverTarget);
+      }
+      return;
+    }
+
+    if (
+      !resolvedTarget ||
+      resolvedTarget === hoverTarget ||
+      !hoverTarget.contains(resolvedTarget)
+    ) {
+      return;
+    }
+
+    let step = resolvedTarget;
+
+    while (step.parentElement && step.parentElement !== hoverTarget) {
+      step = step.parentElement;
+    }
+
+    hoverTarget = step;
+    showHighlight(hoverTarget);
+  }
+
+  function toggleDesignMode() {
+    applyDesignMode(!designMode);
+    options.onDesignModeChange(designMode);
   }
 
   function handleKeyDown(event: Event) {
-    const { key } = event as KeyboardEvent;
-    const fromOverlay = !pageTarget(event);
+    const keyboard = event as KeyboardEvent;
+
+    // Cmd/Ctrl+Shift+A toggles annotation mode from anywhere — including an
+    // open editor, whose draft goes away with the mode it lives in.
+    if (
+      keyboard.code === "KeyA" &&
+      keyboard.shiftKey &&
+      (keyboard.metaKey || keyboard.ctrlKey)
+    ) {
+      event.preventDefault();
+      event.stopPropagation();
+      toggleDesignMode();
+      return;
+    }
+
+    const own = isOverlayEvent(event);
 
     // Typing a comment must not trigger the page's own keyboard shortcuts —
-    // which also means the bubble's own listeners never see the keys, so Enter
-    // is answered here rather than on the input.
-    if (fromOverlay) {
+    // which also means the editor's own listeners never see the keys, so
+    // Enter and Escape are answered here rather than on the textarea.
+    if (own) {
       event.stopPropagation();
+    }
 
-      if (key === "Enter" && openComment !== null) {
-        event.preventDefault();
-        setCommentOpen(null);
-        return;
-      }
+    if (!designMode) {
+      return;
     }
 
-    if (!designMode || key !== "Escape") {
+    // An IME composition owns its keys: Enter confirms a candidate and Escape
+    // cancels the composition — neither may save or close the editor. 229 is
+    // what Chromium reports for keyCode during a composition.
+    if (keyboard.isComposing || keyboard.keyCode === 229) {
       return;
     }
 
-    event.preventDefault();
-    event.stopPropagation();
+    if (keyboard.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+
+      // Two-stage: an open editor is cancelled first (draft discarded, saved
+      // text reverted); the next Escape leaves annotation mode entirely.
+      if (editor) {
+        closeEditor();
+        return;
+      }
+
+      applyDesignMode(false);
+      options.onDesignModeChange(false);
+      return;
+    }
 
-    if (openComment !== null) {
-      setCommentOpen(null);
+    if (own && editor && keyboard.key === "Enter" && !keyboard.shiftKey) {
+      // A bare Enter saves and keeps marking; Shift+Enter stays a newline
+      // because its default action is left alone.
+      event.preventDefault();
+      saveEditor();
       return;
     }
 
-    applyDesignMode(false);
-    options.onDesignModeChange(false);
+    if (
+      !editor &&
+      hoverTarget &&
+      (keyboard.key === "ArrowUp" || keyboard.key === "ArrowDown")
+    ) {
+      // Without this the arrow keys would scroll the page being marked.
+      event.preventDefault();
+      event.stopPropagation();
+      moveHover(keyboard.key === "ArrowUp" ? -1 : 1);
+    }
   }
 
   for (const type of pointerEvents) {
@@ -480,20 +1286,35 @@ export function createAnnotationOverlay(options: {
   listenerTarget.addEventListener("resize", scheduleMarkerSync, true);
 
   return {
-    setDesignMode(enabled) {
+    setAnnotationPalette(palette) {
+      applyAnnotationPalette(palette);
+    },
+
+    setDesignMode(enabled, palette) {
+      if (palette) {
+        applyAnnotationPalette(palette);
+      }
       // No notification back: this is main answering its own command, and an
       // echo would fight the renderer's own state.
       applyDesignMode(enabled);
     },
 
     prepareCapture() {
-      // Closing the bubble commits it: a Send driven from the keyboard never
-      // blurs the input, so this is the only moment the comment the user just
-      // typed can still reach the payload. It also takes the input and the
-      // hover box out of the frame — both are overlay chrome, and neither
-      // belongs in a screenshot of the user's page.
-      setCommentOpen(null);
+      // An open editor settles before the shot: a draft with text is saved —
+      // asking to send is intent to keep it — an empty one is a misclick.
+      if (editor) {
+        if (editorText?.value.trim()) {
+          saveEditor();
+        } else {
+          closeEditor();
+        }
+      }
+      syncOverlayPositions();
+      // Editor, hover box and mode chrome are overlay chrome — none of them
+      // belong in a screenshot of the user's page. The marks stay: they are
+      // what the numbered rows in the prompt point at.
       hideHighlight();
+      setModeAffordanceVisible(false);
       // Measured now rather than when the mark was made: the panel can have
       // been dragged wider since, and the shot is being taken at this size.
       options.onCaptureReady(
@@ -502,15 +1323,22 @@ export function createAnnotationOverlay(options: {
       );
     },
 
+    finishCapture() {
+      if (designMode) {
+        setModeAffordanceVisible(true);
+      }
+    },
+
     clearAnnotations() {
       // No commit on the way out: clearing throws the marks away, comments and
       // all, so there is nothing left to report but the empty list.
-      openComment = null;
+      closeEditor();
       annotations.length = 0;
-      for (const { marker } of markers.values()) {
-        marker.remove();
+      for (const entry of entries.values()) {
+        entry.outline.remove();
+        entry.badge.remove();
       }
-      markers.clear();
+      entries.clear();
       notify();
     },
 
@@ -525,9 +1353,20 @@ export function createAnnotationOverlay(options: {
       listenerTarget.removeEventListener("resize", scheduleMarkerSync, true);
       host?.remove();
       host = null;
+      shadowRoot = null;
       highlight = null;
+      highlightLabel = null;
       markerLayer = null;
-      markers.clear();
+      frame = null;
+      pill = null;
+      editorBox = null;
+      editorText = null;
+      saveButton = null;
+      deleteButton = null;
+      editor = null;
+      resolvedTarget = null;
+      hoverTarget = null;
+      entries.clear();
       annotations.length = 0;
     },
   };
diff --git a/apps/desktop/electron/browser-annotation-preload.ts b/apps/desktop/electron/browser-annotation-preload.ts
index 7ebc82e0..93324e5c 100644
--- a/apps/desktop/electron/browser-annotation-preload.ts
+++ b/apps/desktop/electron/browser-annotation-preload.ts
@@ -49,7 +49,10 @@ ipcRenderer.on(
   (_event, command: BrowserAnnotationCommand) => {
     switch (command?.type) {
       case "set-design-mode":
-        overlay.setDesignMode(command.enabled === true);
+        overlay.setDesignMode(command.enabled === true, command.palette);
+        break;
+      case "set-annotation-palette":
+        overlay.setAnnotationPalette(command.palette);
         break;
       case "clear-annotations":
         overlay.clearAnnotations();
@@ -57,6 +60,9 @@ ipcRenderer.on(
       case "prepare-capture":
         overlay.prepareCapture();
         break;
+      case "capture-done":
+        overlay.finishCapture();
+        break;
     }
   },
 );
diff --git a/apps/desktop/electron/browser-annotation.test.ts b/apps/desktop/electron/browser-annotation.test.ts
index 79888dfd..c09309d1 100644
--- a/apps/desktop/electron/browser-annotation.test.ts
+++ b/apps/desktop/electron/browser-annotation.test.ts
@@ -1,8 +1,10 @@
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   acceptBrowserAnnotationMessage,
   buildElementSelector,
   describeAnnotatedElement,
+  readAnnotationPalette,
+  resolveAnnotationTarget,
 } from "./browser-annotation";
 
 function mount(html: string) {
@@ -107,7 +109,7 @@ describe("describeAnnotatedElement", () => {
     mount('<main><button id="cta">Go</button></main>');
 
     const element = document.getElementById("cta")!;
-    const annotation = describeAnnotatedElement(element, 3);
+    const annotation = describeAnnotatedElement(element, 3, "d1");
 
     expect(annotation.index).toBe(3);
     expect(annotation.tag).toBe("button");
@@ -118,7 +120,7 @@ describe("describeAnnotatedElement", () => {
   it("collapses whitespace and truncates long text", () => {
     mount(`<p id="copy">${"word ".repeat(60)}</p>`);
 
-    const annotation = describeAnnotatedElement(document.getElementById("copy")!, 1);
+    const annotation = describeAnnotatedElement(document.getElementById("copy")!, 1, "d1");
 
     expect(annotation.text!.length).toBeLessThanOrEqual(120);
     expect(annotation.text!.endsWith("…")).toBe(true);
@@ -128,10 +130,10 @@ describe("describeAnnotatedElement", () => {
   it("keeps short text verbatim and omits it when there is none", () => {
     mount('<p id="copy">  Hello\n  world  </p><img id="pic" alt="" />');
 
-    expect(describeAnnotatedElement(document.getElementById("copy")!, 1).text).toBe(
+    expect(describeAnnotatedElement(document.getElementById("copy")!, 1, "d1").text).toBe(
       "Hello world",
     );
-    expect(describeAnnotatedElement(document.getElementById("pic")!, 2)).not.toHaveProperty(
+    expect(describeAnnotatedElement(document.getElementById("pic")!, 2, "d2")).not.toHaveProperty(
       "text",
     );
   });
@@ -139,7 +141,7 @@ describe("describeAnnotatedElement", () => {
   it("reads a source location from data-source", () => {
     mount('<b id="tagged" data-source="src/pages/app.tsx:12:5">x</b>');
 
-    expect(describeAnnotatedElement(document.getElementById("tagged")!, 1).source).toEqual({
+    expect(describeAnnotatedElement(document.getElementById("tagged")!, 1, "d1").source).toEqual({
       file: "src/pages/app.tsx",
       line: 12,
       column: 5,
@@ -151,7 +153,7 @@ describe("describeAnnotatedElement", () => {
       '<b id="tagged" data-inspector-relative-path="src/app.tsx" data-inspector-line="7">x</b>',
     );
 
-    expect(describeAnnotatedElement(document.getElementById("tagged")!, 1).source).toEqual({
+    expect(describeAnnotatedElement(document.getElementById("tagged")!, 1, "d1").source).toEqual({
       file: "src/app.tsx",
       line: 7,
     });
@@ -160,7 +162,7 @@ describe("describeAnnotatedElement", () => {
   it("omits the source when no data attribute carries one", () => {
     mount('<b id="plain" data-source="not-a-location">x</b>');
 
-    expect(describeAnnotatedElement(document.getElementById("plain")!, 1)).not.toHaveProperty(
+    expect(describeAnnotatedElement(document.getElementById("plain")!, 1, "d1")).not.toHaveProperty(
       "source",
     );
   });
@@ -169,7 +171,7 @@ describe("describeAnnotatedElement", () => {
     mount('<b id="plain">x</b>');
 
     expect(
-      Object.keys(describeAnnotatedElement(document.getElementById("plain")!, 1)),
+      Object.keys(describeAnnotatedElement(document.getElementById("plain")!, 1, "d1")),
     ).not.toContain("reactName");
   });
 });
@@ -177,6 +179,7 @@ describe("describeAnnotatedElement", () => {
 describe("acceptBrowserAnnotationMessage", () => {
   const trustedSender = { id: "view" };
   const annotation = {
+    id: "ann-1",
     index: 1,
     selector: "#cta",
     tag: "button",
@@ -246,6 +249,30 @@ describe("acceptBrowserAnnotationMessage", () => {
     });
   });
 
+  it("drops annotations whose id is not a minted short string", () => {
+    const accepted = acceptBrowserAnnotationMessage({
+      sender: trustedSender,
+      trustedSender,
+      message: {
+        type: "annotations",
+        viewport,
+        annotations: [
+          annotation,
+          { ...annotation, id: 42 },
+          { ...annotation, id: "has spaces/in it" },
+          { ...annotation, id: "x".repeat(65) },
+          { ...annotation, id: "" },
+        ],
+      },
+    });
+    const kept = (accepted as { annotations: Array<{ id: string }> }).annotations;
+
+    // Only the well-formed mark survives; the index field alone is not an
+    // identity a page can be trusted with.
+    expect(kept).toHaveLength(1);
+    expect(kept[0]!.id).toBe("ann-1");
+  });
+
   it("folds newlines out of every field that reaches the prompt", () => {
     const accepted = acceptBrowserAnnotationMessage({
       sender: trustedSender,
@@ -335,3 +362,112 @@ describe("acceptBrowserAnnotationMessage", () => {
     ).toEqual({ type: "design-mode", enabled: false });
   });
 });
+
+describe("resolveAnnotationTarget", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  /** jsdom measures nothing; give an element a size so it is not decorative. */
+  function size(element: Element, width = 40, height = 20) {
+    vi.spyOn(element, "getBoundingClientRect").mockReturnValue({
+      x: 0,
+      y: 0,
+      width,
+      height,
+      left: 0,
+      top: 0,
+      right: width,
+      bottom: height,
+      toJSON: () => ({}),
+    } as DOMRect);
+    return element;
+  }
+
+  it("climbs out of inline decorations to the element the user meant", () => {
+    mount('<p id="copy">Some <span id="word">nested <b id="bold">text</b></span></p>');
+    const copy = size(document.getElementById("copy")!);
+
+    expect(resolveAnnotationTarget(size(document.getElementById("bold")!))).toBe(
+      copy,
+    );
+    expect(resolveAnnotationTarget(size(document.getElementById("word")!))).toBe(
+      copy,
+    );
+  });
+
+  it("names the svg, not a path inside it", () => {
+    mount(
+      '<button id="icon"><svg viewBox="0 0 10 10"><path id="stroke" d="M0 0h10"/></svg></button>',
+    );
+
+    const path = document.getElementById("stroke")!;
+    size(document.getElementById("icon")!);
+
+    // The climb reaches the <svg>, and the interactive step then prefers the
+    // button — marking an icon is marking the control it draws.
+    expect(resolveAnnotationTarget(path)).toBe(document.getElementById("icon"));
+  });
+
+  it("climbs past elements too small to have been aimed at", () => {
+    mount('<div id="row"><i id="hairline"></i></div>');
+    const row = size(document.getElementById("row")!);
+
+    expect(resolveAnnotationTarget(document.getElementById("hairline")!)).toBe(row);
+  });
+
+  it("prefers the nearest interactive ancestor even for a sizeable target", () => {
+    mount('<button id="cta"><span id="label">Go</span></button>');
+
+    const label = document.getElementById("label")!;
+    size(document.getElementById("cta")!);
+
+    // span is decorative regardless, but the assertion is on the outcome:
+    // the click meant the button.
+    expect(resolveAnnotationTarget(label)).toBe(document.getElementById("cta"));
+  });
+
+  it("honours ARIA roles as interactive targets", () => {
+    mount('<div id="chip" role="button"><em id="inner">x</em></div>');
+    const chip = size(document.getElementById("chip")!);
+
+    expect(resolveAnnotationTarget(document.getElementById("inner")!)).toBe(chip);
+  });
+
+  it("stops at body rather than climbing to the document element", () => {
+    mount('<span id="orphan">x</span>');
+
+    expect(resolveAnnotationTarget(document.getElementById("orphan")!)).toBe(
+      document.body,
+    );
+  });
+});
+
+describe("readAnnotationPalette", () => {
+  const palette = {
+    accent: "#0064E0",
+    accentForeground: "#fff",
+    surface: "#1f1f22",
+    foreground: "rgb(1, 2, 3)",
+    border: "rgba(0, 0, 0, 0.1)",
+    muted: "oklch(0.7 0.1 200)",
+  };
+
+  it("accepts a full palette of short strings verbatim", () => {
+    expect(readAnnotationPalette(palette)).toEqual(palette);
+  });
+
+  it("drops the whole palette when a field is missing, not a string, or too long", () => {
+    for (const bad of [
+      null,
+      "dark",
+      { ...palette, accent: 42 },
+      { ...palette, muted: "x".repeat(65) },
+      { accent: "#fff" },
+    ]) {
+      // A partial or malformed palette must not reach the page: the overlay
+      // would then mix renderer colours with defaults unpredictably.
+      expect(readAnnotationPalette(bad)).toBeUndefined();
+    }
+  });
+});
diff --git a/apps/desktop/electron/browser-annotation.ts b/apps/desktop/electron/browser-annotation.ts
index 6c31cde9..a644cc17 100644
--- a/apps/desktop/electron/browser-annotation.ts
+++ b/apps/desktop/electron/browser-annotation.ts
@@ -1,5 +1,6 @@
 import type {
   BrowserAnnotationElement,
+  BrowserAnnotationPalette,
   BrowserAnnotationViewport,
 } from "@/shared/browser-protocol";
 
@@ -39,17 +40,45 @@ export type BrowserAnnotationMessage =
   | ({ type: "capture-ready" } & AnnotationsPayload);
 
 export type BrowserAnnotationCommand =
-  | { type: "set-design-mode"; enabled: boolean }
+  | {
+      type: "set-design-mode";
+      enabled: boolean;
+      /** The renderer's theme tokens; the overlay validates each colour itself. */
+      palette?: BrowserAnnotationPalette;
+    }
+  | {
+      type: "set-annotation-palette";
+      palette: BrowserAnnotationPalette;
+    }
   | { type: "clear-annotations" }
-  | { type: "prepare-capture" };
+  | { type: "prepare-capture" }
+  /**
+   * The screenshot is taken (or abandoned): the overlay may put its mode
+   * chrome — the frame and pill `prepare-capture` hid — back on screen.
+   */
+  | { type: "capture-done" };
 
 const maxTextLength = 120;
-const maxCommentLength = 500;
+/**
+ * The page-side editor caps its textarea at this too — export it so the one
+ * limit lives in one place. (This module is already in the preload bundle.)
+ */
+export const maxCommentLength = 500;
 const maxTagLength = 40;
 const maxSelectorLength = 1_000;
 const maxAnnotations = 200;
 /** `file:line` or `file:line:column`, with a file part that is not empty. */
 const sourcePattern = /^(.+?):(\d+)(?::(\d+))?$/;
+/** What the overlay mints with `crypto.randomUUID()` — short and url-safe. */
+const annotationIdPattern = /^[A-Za-z0-9-]{1,64}$/;
+const paletteFields = [
+  "accent",
+  "accentForeground",
+  "surface",
+  "foreground",
+  "border",
+  "muted",
+] as const;
 
 /**
  * One line, then at most `max` characters of it.
@@ -137,12 +166,60 @@ function readText(element: Element) {
   return text ? clampText(text, maxTextLength) : undefined;
 }
 
+/**
+ * Tags that decorate text rather than carry it — pointing at one means the
+ * user aimed at what wraps it.
+ */
+const decorativeTags = new Set(["span", "b", "i", "em", "strong", "small"]);
+
+/**
+ * Controls a click means even when it lands on a child: marking a button's
+ * label is marking the button.
+ */
+const interactiveTargetSelector =
+  'a,button,label,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[role="checkbox"]';
+
+/**
+ * What a click on the deepest composed node actually meant. The path names
+ * leaf nodes — a `span`, an SVG `path`, a 1px decorator — so the target
+ * climbs while the element is decorative (decorative tag, an SVG interior,
+ * or too small to have been aimed at), stopping at `document.body`, then
+ * prefers the nearest enclosing interactive control.
+ */
+export function resolveAnnotationTarget(deepest: Element): Element {
+  const body = deepest.ownerDocument.body;
+  let current = deepest;
+
+  while (current !== body) {
+    const tag = current.tagName.toLowerCase();
+    const rect = current.getBoundingClientRect();
+    // `ownerSVGElement` is non-null only inside an SVG — and only on
+    // SVGElements at all, which is why this is not a plain property read.
+    const insideSvg =
+      current instanceof SVGElement && current.ownerSVGElement !== null;
+    const decorative =
+      decorativeTags.has(tag) ||
+      insideSvg ||
+      rect.width < 8 ||
+      rect.height < 8;
+    const parent = current.parentElement;
+
+    if (!decorative || !parent) {
+      break;
+    }
+
+    current = parent;
+  }
+
+  return current.closest(interactiveTargetSelector) ?? current;
+}
+
 /**
  * Best-effort source location, read only from `data-*` attributes: either a
  * combined `data-source="file:line:column"` or the separate attributes the
  * React inspector plugins stamp. Anything else is left out rather than guessed.
  */
-function readSource(element: Element) {
+export function readSource(element: Element) {
   const combined = sourcePattern.exec(element.getAttribute("data-source")?.trim() ?? "");
 
   if (combined) {
@@ -172,12 +249,14 @@ function readSource(element: Element) {
 export function describeAnnotatedElement(
   element: Element,
   index: number,
+  id: string,
 ): BrowserAnnotationElement {
   const rect = element.getBoundingClientRect();
   const text = readText(element);
   const source = readSource(element);
 
   return {
+    id,
     index,
     selector: buildElementSelector(element),
     tag: element.tagName.toLowerCase(),
@@ -252,14 +331,14 @@ function readAnnotation(value: unknown): BrowserAnnotationElement | null {
     return null;
   }
 
-  const { index, selector, tag, text, rect, source, comment } = value as Record<
-    string,
-    unknown
-  >;
+  const { id, index, selector, tag, text, rect, source, comment } =
+    value as Record<string, unknown>;
   const indexNumber = finiteNumber(index);
   const rectangle = readRect(rect);
 
   if (
+    typeof id !== "string" ||
+    !annotationIdPattern.test(id) ||
     indexNumber === null ||
     typeof selector !== "string" ||
     typeof tag !== "string" ||
@@ -271,6 +350,7 @@ function readAnnotation(value: unknown): BrowserAnnotationElement | null {
   const location = readSourceValue(source);
 
   return {
+    id,
     index: Math.trunc(indexNumber),
     selector: clampText(selector, maxSelectorLength),
     tag: clampText(tag, maxTagLength),
@@ -303,6 +383,34 @@ function readAnnotationsPayload(
   };
 }
 
+/**
+ * The renderer sends its computed theme tokens with a design-mode or
+ * palette-only command. Main validates the shape; the overlay parses colours
+ * with `CSS.supports` in the page's CSS engine.
+ */
+export function readAnnotationPalette(
+  value: unknown,
+): BrowserAnnotationPalette | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const record = value as Record<string, unknown>;
+  const palette = {} as Record<(typeof paletteFields)[number], string>;
+
+  for (const field of paletteFields) {
+    const colour = record[field];
+
+    if (typeof colour !== "string" || colour.length > 64) {
+      return undefined;
+    }
+
+    palette[field] = colour;
+  }
+
+  return palette;
+}
+
 /**
  * The gate on the annotation channel: the message has to come from the
  * embedded view's own webContents, and it has to be one of the shapes
diff --git a/apps/desktop/electron/browser-host.test.ts b/apps/desktop/electron/browser-host.test.ts
index a48088cf..b9132d54 100644
--- a/apps/desktop/electron/browser-host.test.ts
+++ b/apps/desktop/electron/browser-host.test.ts
@@ -52,12 +52,20 @@ function createFakeView() {
     goBack() {
       calls.push("goBack");
     },
-    setDesignMode(enabled) {
-      calls.push(`setDesignMode(${enabled})`);
+    setDesignMode(enabled, palette) {
+      calls.push(`setDesignMode(${enabled}${palette ? ",palette" : ""})`);
+      calls.push(`palette(${palette ? JSON.stringify(palette) : ""})`);
+    },
+    setAnnotationPalette(palette) {
+      calls.push("setAnnotationPalette");
+      calls.push(`palette(${JSON.stringify(palette)})`);
     },
     prepareCapture() {
       calls.push("prepareCapture");
     },
+    finishCapture() {
+      calls.push("finishCapture");
+    },
     clearAnnotations() {
       calls.push("clearAnnotations");
     },
@@ -178,6 +186,7 @@ describe("browser host commands", () => {
   const marked = {
     annotations: [
       {
+        id: "m1",
         index: 1,
         selector: "#cta",
         tag: "button",
@@ -457,10 +466,12 @@ describe("browser host commands", () => {
       url: "http://localhost:5173/",
     });
     // Order is the whole point: shooting first would print the open comment
-    // bubble and a stale hover box onto what Pi reads.
-    expect(views[0]!.calls.slice(-2)).toEqual([
+    // bubble and a stale hover box onto what Pi reads — and the page is told
+    // when the shot is over so its annotation chrome can come back.
+    expect(views[0]!.calls.slice(-3)).toEqual([
       "prepareCapture",
       "capture(684)",
+      "finishCapture",
     ]);
   });
 
@@ -484,6 +495,8 @@ describe("browser host commands", () => {
         viewport: marked.viewport,
       });
       expect(views[0]!.calls).toContain("capture()");
+      // Even the bail-out tells the page the shot is over.
+      expect(views[0]!.calls).toContain("finishCapture");
     } finally {
       vi.useRealTimers();
     }
@@ -506,6 +519,69 @@ describe("browser host commands", () => {
     expect(views[0]!.calls).toContain("clearAnnotations");
   });
 
+  it("stores a valid palette for ready replays and forwards it to the view", async () => {
+    const { host, views } = createHostHarness();
+    const palette = {
+      accent: "#0064E0",
+      accentForeground: "#ffffff",
+      surface: "#1f1f22",
+      foreground: "#dfe2e5",
+      border: "#494d53",
+      muted: "#aaafb5",
+    };
+
+    await host.invoke("browser_navigate", { url: "http://localhost:5173/" });
+    await host.invoke("browser_set_design_mode", { enabled: true, palette });
+
+    expect(views[0]!.calls).toContain(
+      `palette(${JSON.stringify(palette)})`,
+    );
+    // Fresh documents get it back when their overlay reports in.
+    expect(host.annotationPalette()).toEqual(palette);
+  });
+
+  it("validates palette-only updates without changing design mode", async () => {
+    const { host, views } = createHostHarness();
+    const palette = {
+      accent: "#0064E0",
+      accentForeground: "#ffffff",
+      surface: "#1f1f22",
+      foreground: "#dfe2e5",
+      border: "#494d53",
+      muted: "#aaafb5",
+    };
+
+    await host.invoke("browser_navigate", { url: "http://localhost:5173/" });
+    await host.invoke("browser_set_annotation_palette", { palette });
+
+    expect(host.annotationPalette()).toEqual(palette);
+    expect(host.isDesignModeEnabled()).toBe(false);
+    expect(views[0]!.calls).toContain("setAnnotationPalette");
+    expect(views[0]!.calls).not.toContain("setDesignMode(false)");
+
+    const callCount = views[0]!.calls.length;
+    await host.invoke("browser_set_annotation_palette", {
+      palette: { ...palette, surface: 42 },
+    });
+
+    expect(host.annotationPalette()).toEqual(palette);
+    expect(views[0]!.calls).toHaveLength(callCount);
+    expect(host.isDesignModeEnabled()).toBe(false);
+  });
+
+  it("ignores a malformed palette wholesale instead of forwarding part of it", async () => {
+    const { host, views } = createHostHarness();
+
+    await host.invoke("browser_navigate", { url: "http://localhost:5173/" });
+    await host.invoke("browser_set_design_mode", {
+      enabled: true,
+      palette: { accent: "#0064E0", surface: 42 },
+    });
+
+    expect(host.annotationPalette()).toBeUndefined();
+    expect(views[0]!.calls).toContain("palette()");
+  });
+
   it("records design mode the page left on its own without commanding it back", async () => {
     const { host, views } = createHostHarness();
 
@@ -534,6 +610,7 @@ describe("browser host commands", () => {
       "browser_set_bounds",
       "browser_set_visible",
       "browser_set_design_mode",
+      "browser_set_annotation_palette",
       "browser_clear_annotations",
       "browser_open_external",
     ]) {
@@ -698,7 +775,10 @@ describe("Browser multi-instance host", () => {
     await host.invoke("browser_set_design_mode", { ...first, enabled: true });
     host
       .tab(first)
-      .recordAnnotations([{ index: 1, selector: "#a", tag: "p", rect }], null);
+      .recordAnnotations(
+        [{ id: "a1", index: 1, selector: "#a", tag: "p", rect }],
+        null,
+      );
     const capture = host.invoke("browser_capture_annotation", first);
     await host.invoke("browser_open", second);
     await host.invoke("browser_navigate", { ...second, url: "localhost:4000" });
diff --git a/apps/desktop/electron/browser-host.ts b/apps/desktop/electron/browser-host.ts
index 7c43b606..9c36ad3d 100644
--- a/apps/desktop/electron/browser-host.ts
+++ b/apps/desktop/electron/browser-host.ts
@@ -6,11 +6,13 @@ import type {
   BrowserTabState,
   BrowserTabTarget,
   BrowserAnnotationElement,
+  BrowserAnnotationPalette,
   BrowserAnnotationViewport,
   BrowserViewRect,
   BrowserViewSnapshot,
   BrowserViewState,
 } from "@/shared/browser-protocol";
+import { readAnnotationPalette } from "./browser-annotation";
 
 /**
  * Policy and lifecycle for the embedded browser surface, with every Electron
@@ -58,6 +60,7 @@ const browserCommands = new Set([
   "browser_set_bounds",
   "browser_set_visible",
   "browser_set_design_mode",
+  "browser_set_annotation_palette",
   "browser_clear_annotations",
   "browser_open_external",
 ]);
@@ -220,10 +223,14 @@ export type BrowserHostView = {
   goBack(): void;
   goForward(): void;
   /** Design mode lives in the page's isolated world; this is the command. */
-  setDesignMode(enabled: boolean): void;
+  setDesignMode(enabled: boolean, palette?: BrowserAnnotationPalette): void;
+  /** Updates the annotation colours without changing mode. */
+  setAnnotationPalette(palette: BrowserAnnotationPalette): void;
   clearAnnotations(): void;
   /** Asks the overlay to put itself out of shot and report what it holds. */
   prepareCapture(): void;
+  /** The shot is done — the overlay may put its mode chrome back. */
+  finishCapture(): void;
   reload(): void;
   destroy(): void;
   readState(): BrowserViewSnapshot;
@@ -268,6 +275,11 @@ type BrowserTabHost = {
   isDesignModeEnabled(): boolean;
   /** Design mode the page left by itself (Escape), so main stops re-applying it. */
   recordDesignMode(enabled: boolean): void;
+  /**
+   * The last valid palette, replayed to each fresh document so the overlay
+   * keeps Pace's colours.
+   */
+  annotationPalette(): BrowserAnnotationPalette | undefined;
   /**
    * What the page reports as the user marks. Kept so a capture can go ahead
    * with the last known marks when the page does not answer the prepare.
@@ -330,6 +342,7 @@ export function createBrowserTabHost(
   let title = "";
   let loading = false;
   let designMode = false;
+  let palette: BrowserAnnotationPalette | undefined;
   let marks: Omit<BrowserAnnotationCapture, "image" | "url"> = {
     annotations: [],
     viewport: null,
@@ -451,25 +464,31 @@ export function createBrowserTabHost(
     const capturedNavigation = navigationId;
     const settled = await awaitCaptureAck(capturedView);
 
-    // Closing or navigating a tab invalidates the page this handshake began on.
-    if (view !== capturedView || navigationId !== capturedNavigation) {
-      return null;
-    }
-    const image = await capturedView.capture(bounds?.width);
-    if (view !== capturedView || navigationId !== capturedNavigation)
-      return null;
+    try {
+      // Closing or navigating a tab invalidates the page this handshake began on.
+      if (view !== capturedView || navigationId !== capturedNavigation) {
+        return null;
+      }
+      const image = await capturedView.capture(bounds?.width);
+      if (view !== capturedView || navigationId !== capturedNavigation)
+        return null;
 
-    return {
-      // Downsampled to the panel's own CSS width: `capturePage` answers in
-      // device pixels, so on a 2x display a wide panel is a PNG approaching
-      // the 8 MiB an image attachment may weigh, for pixels the model cannot
-      // use. The overlay still (`browser_capture`) keeps them, because it is
-      // displayed at the placeholder's size.
-      image,
-      annotations: settled.annotations,
-      viewport: settled.viewport,
-      url: view.readState().url,
-    };
+      return {
+        // Downsampled to the panel's own CSS width: `capturePage` answers in
+        // device pixels, so on a 2x display a wide panel is a PNG approaching
+        // the 8 MiB an image attachment may weigh, for pixels the model cannot
+        // use. The overlay still (`browser_capture`) keeps them, because it is
+        // displayed at the placeholder's size.
+        image,
+        annotations: settled.annotations,
+        viewport: settled.viewport,
+        url: view.readState().url,
+      };
+    } finally {
+      // However the shot ended — taken, abandoned, never answered — the page
+      // gets told so its annotation-mode chrome can come back.
+      capturedView.finishCapture();
+    }
   }
 
   function setBounds(rect: BrowserViewRect) {
@@ -538,12 +557,28 @@ export function createBrowserTabHost(
           visibilityRequested = args?.visible === true;
           applyVisibility();
           return readState();
-        case "browser_set_design_mode":
-          // Deliberately not `ensureView()`: turning Design on over the empty
-          // state has nothing to mark up, and creating a view would paint one.
+        case "browser_set_design_mode": {
+          // Deliberately not `ensureView()`: turning annotation mode on over
+          // the empty state has nothing to mark up, and creating a view would
+          // paint one.
           designMode = args?.enabled === true;
-          view?.setDesignMode(designMode);
+          // An absent or malformed palette keeps the last one — the renderer
+          // only sends tokens when it turns the mode on.
+          const nextPalette = readAnnotationPalette(args?.palette);
+          if (nextPalette) {
+            palette = nextPalette;
+          }
+          view?.setDesignMode(designMode, nextPalette);
           return null;
+        }
+        case "browser_set_annotation_palette": {
+          const nextPalette = readAnnotationPalette(args?.palette);
+          if (nextPalette) {
+            palette = nextPalette;
+            view?.setAnnotationPalette(nextPalette);
+          }
+          return null;
+        }
         case "browser_clear_annotations":
           marks = { annotations: [], viewport: null };
           view?.clearAnnotations();
@@ -589,6 +624,10 @@ export function createBrowserTabHost(
       designMode = enabled;
     },
 
+    annotationPalette() {
+      return palette;
+    },
+
     recordAnnotations(annotations, viewport) {
       marks = { annotations, viewport };
     },
diff --git a/apps/desktop/electron/main.ts b/apps/desktop/electron/main.ts
index d00f68bb..e3df3cf2 100644
--- a/apps/desktop/electron/main.ts
+++ b/apps/desktop/electron/main.ts
@@ -19,7 +19,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { autoUpdater } from "electron-updater";
 import type { BackendRpcEvent, BackendRpcResponse } from "@pace/backend";
-import { browserEventChannel, type BrowserEvent, type BrowserTabTarget } from "@/shared/browser-protocol";
+import { browserEventChannel, type BrowserAnnotationPalette, type BrowserEvent, type BrowserTabTarget } from "@/shared/browser-protocol";
 import { updateEventChannel } from "@/shared/update-protocol";
 import {
   acceptBrowserAnnotationMessage,
@@ -543,12 +543,23 @@ function createBrowserView(target: BrowserTabTarget) {
       ),
     goBack: () => webContents.navigationHistory.goBack(),
     goForward: () => webContents.navigationHistory.goForward(),
-    setDesignMode: (enabled: boolean) =>
-      sendAnnotationCommand(webContents, { type: "set-design-mode", enabled }),
+    setDesignMode: (enabled: boolean, palette?: BrowserAnnotationPalette) =>
+      sendAnnotationCommand(webContents, {
+        type: "set-design-mode",
+        enabled,
+        ...(palette ? { palette } : {}),
+      }),
+    setAnnotationPalette: (palette: BrowserAnnotationPalette) =>
+      sendAnnotationCommand(webContents, {
+        type: "set-annotation-palette",
+        palette,
+      }),
     clearAnnotations: () =>
       sendAnnotationCommand(webContents, { type: "clear-annotations" }),
     prepareCapture: () =>
       sendAnnotationCommand(webContents, { type: "prepare-capture" }),
+    finishCapture: () =>
+      sendAnnotationCommand(webContents, { type: "capture-done" }),
     reload: () => webContents.reload(),
     destroy: () => {
       browserAnnotationSenders.delete(webContents);
@@ -616,16 +627,20 @@ ipcMain.on(browserAnnotationChannel, (event, payload: unknown) => {
   const host = getBrowserHost().tab(target);
 
   switch (message.type) {
-    case "ready":
+    case "ready": {
       // A new document carries a new overlay: no marks on it, and design mode
-      // has to be put back if the user never left it.
+      // — with the tab's last palette — has to be put back if the user never
+      // left it.
+      const palette = host.annotationPalette();
       sendAnnotationCommand(event.sender, {
         type: "set-design-mode",
         enabled: host.isDesignModeEnabled(),
+        ...(palette ? { palette } : {}),
       });
       host.recordAnnotations([], null);
       getBrowserHost().notify(target);
       break;
+    }
     case "annotations":
       // Kept on the host as well as forwarded: a capture whose prepare goes
       // unanswered falls back to the last marks that arrived here.
diff --git a/apps/desktop/src/entities/browser/browser-client.ts b/apps/desktop/src/entities/browser/browser-client.ts
index f42ec03c..f5c74856 100644
--- a/apps/desktop/src/entities/browser/browser-client.ts
+++ b/apps/desktop/src/entities/browser/browser-client.ts
@@ -1,6 +1,7 @@
 import { invoke, onBrowserEvent } from "@/shared/runtime";
 import type {
   BrowserAnnotationCapture,
+  BrowserAnnotationPalette,
   BrowserEvent,
   BrowserSessionState,
   BrowserTabState,
@@ -58,10 +59,21 @@ export function setBrowserVisible(target: BrowserTabTarget, visible: boolean) {
 export function setBrowserDesignMode(
   target: BrowserTabTarget,
   enabled: boolean,
+  palette?: BrowserAnnotationPalette,
 ) {
   return invoke<BrowserTabState | null>("browser_set_design_mode", {
     ...target,
     enabled,
+    ...(palette ? { palette } : {}),
+  });
+}
+export function setBrowserAnnotationPalette(
+  target: BrowserTabTarget,
+  palette: BrowserAnnotationPalette,
+) {
+  return invoke<BrowserTabState | null>("browser_set_annotation_palette", {
+    ...target,
+    palette,
   });
 }
 export function clearBrowserAnnotations(target: BrowserTabTarget) {
diff --git a/apps/desktop/src/pages/design-components.test.tsx b/apps/desktop/src/pages/design-components.test.tsx
index 754fac52..826829d1 100644
--- a/apps/desktop/src/pages/design-components.test.tsx
+++ b/apps/desktop/src/pages/design-components.test.tsx
@@ -324,18 +324,18 @@ describe("Design components layer", () => {
     expect(within(section).getByTestId("browser-snapshot")).toBeInTheDocument();
     expect(within(section).getByText(/widen the window/i)).toBeInTheDocument();
     expect(within(section).getByText("No page loaded")).toBeInTheDocument();
-    // Design mode is a toolbar state of this surface, so the gallery has to
-    // carry it too — pressed toggle and the count of what is marked.
+    // Annotation mode is a toolbar state of this surface, so the gallery has
+    // to carry it too — pressed toggle and the count of what is marked.
     expect(within(section).getAllByTestId("browser-annotation-count")[0]).toHaveTextContent(
-      "2",
+      "2 comments",
     );
     expect(
       within(section)
-        .getAllByRole("button", { name: "Design" })
+        .getAllByRole("button", { name: "Annotate" })
         .some((button) => button.getAttribute("aria-pressed") === "true"),
     ).toBe(true);
 
-    // Send to composer is the point of design mode, and it has two states
+    // Send to composer is the point of annotation mode, and it has two states
     // worth showing: nothing marked yet, and something to send.
     const send = within(section).getAllByRole("button", { name: "Send to composer" });
 
diff --git a/apps/desktop/src/pages/design-components.tsx b/apps/desktop/src/pages/design-components.tsx
index 365fdd9d..3c5f3057 100644
--- a/apps/desktop/src/pages/design-components.tsx
+++ b/apps/desktop/src/pages/design-components.tsx
@@ -499,7 +499,7 @@ function BrowserSurfaceGallery() {
             />
           </div>
         </Variant>
-        <Variant caption="design mode on, two elements marked — the marks live in the page's own overlay, and Send to composer drops them plus a screenshot into the chat draft">
+        <Variant caption="annotate mode on, two comments — the marks live in the page's own overlay, and To composer drops them plus a screenshot into the chat draft">
           <div className="h-56 w-[30rem] overflow-hidden rounded-md border border-separator px-2">
             <GalleryBrowserSurface
               address="http://localhost:5173/"
diff --git a/apps/desktop/src/shared/browser-protocol.ts b/apps/desktop/src/shared/browser-protocol.ts
index f6bf24c3..92b14ac4 100644
--- a/apps/desktop/src/shared/browser-protocol.ts
+++ b/apps/desktop/src/shared/browser-protocol.ts
@@ -44,6 +44,21 @@ export type BrowserViewState = BrowserViewSnapshot & {
  */
 export type { BrowserAnnotationElement, BrowserAnnotationViewport };
 
+/**
+ * The renderer's theme tokens, resolved to computed colour values and carried
+ * to the page's overlay with `set-design-mode`. The overlay accepts each
+ * colour only if `CSS.supports("color", v)` parses it, falling back per field
+ * to its built-in defaults, so nothing here needs to be a legal colour.
+ */
+export type BrowserAnnotationPalette = {
+  accent: string;
+  accentForeground: string;
+  surface: string;
+  foreground: string;
+  border: string;
+  muted: string;
+};
+
 /**
  * What `browser_capture_annotation` answers with: the screenshot and the marks
  * it was taken against, which the page settled and re-measured for this shot.
diff --git a/apps/desktop/src/shared/ui/browser/browser-surface.test.tsx b/apps/desktop/src/shared/ui/browser/browser-surface.test.tsx
index e8815caa..1383c4aa 100644
--- a/apps/desktop/src/shared/ui/browser/browser-surface.test.tsx
+++ b/apps/desktop/src/shared/ui/browser/browser-surface.test.tsx
@@ -229,7 +229,7 @@ describe("BrowserSurface", () => {
 
     renderSurface({ onDesignModeChange });
 
-    await user.click(screen.getByRole("button", { name: "Design" }));
+    await user.click(screen.getByRole("button", { name: "Annotate" }));
 
     expect(onDesignModeChange).toHaveBeenCalledWith(true, expect.anything());
   });
@@ -247,7 +247,7 @@ describe("BrowserSurface", () => {
     view.rerender(<ComposedBrowserSurface {...props} annotationCount={2} isDesignMode />);
 
     expect(screen.getByTestId("browser-annotation-count")).toHaveTextContent(
-      "2",
+      "2 comments",
     );
     await user.click(screen.getByRole("button", { name: "Clear marks" }));
 
@@ -277,7 +277,7 @@ describe("BrowserSurface", () => {
       isDesignMode: true,
     });
 
-    const design = screen.getByRole("button", { name: "Design" });
+    const design = screen.getByRole("button", { name: "Annotate" });
 
     expect(design).toBeDisabled();
     // Nothing is marked where there is no page, so a pressed-but-disabled
diff --git a/apps/desktop/src/shared/ui/browser/browser-surface.tsx b/apps/desktop/src/shared/ui/browser/browser-surface.tsx
index f2bd9b76..859a8a2b 100644
--- a/apps/desktop/src/shared/ui/browser/browser-surface.tsx
+++ b/apps/desktop/src/shared/ui/browser/browser-surface.tsx
@@ -135,7 +135,7 @@ function BrowserSurfaceTabs({
             className="shrink-0 text-xs tabular-nums text-muted"
             data-testid="browser-annotation-count"
           >
-            {annotationCount} marked
+            {annotationCount === 1 ? "1 comment" : `${annotationCount} comments`}
           </span>
         ) : null
       }
@@ -224,7 +224,7 @@ function BrowserSurfaceToolbar({
             // never reads as pressed there — a pressed, disabled control
             // claims a state the user cannot leave.
             isPressed={isLive && isDesignMode}
-            label="Design"
+            label="Annotate"
             size="sm"
             onPressedChange={onDesignModeChange}
           />
diff --git a/apps/desktop/src/widgets/session-dock/session-browser-panel.test.tsx b/apps/desktop/src/widgets/session-dock/session-browser-panel.test.tsx
index 404f8cfc..337d1e71 100644
--- a/apps/desktop/src/widgets/session-dock/session-browser-panel.test.tsx
+++ b/apps/desktop/src/widgets/session-dock/session-browser-panel.test.tsx
@@ -19,6 +19,7 @@ import { SessionBrowserPanel } from "./session-browser-panel";
 
 const marks = [
   {
+    id: "m1",
     index: 1,
     selector: "#cta",
     tag: "button",
@@ -60,8 +61,10 @@ function installPreload(
         goBack() {},
         goForward() {},
         setDesignMode() {},
+        setAnnotationPalette() {},
         clearAnnotations() {},
         prepareCapture() {},
+        finishCapture() {},
         reload() {},
         destroy() {},
         readState: () => ({ url, canGoBack: false, canGoForward: false }),
@@ -272,7 +275,7 @@ describe("SessionBrowserPanel multi-instance", () => {
       "aria-busy",
       "true",
     );
-    await user.click(screen.getByRole("button", { name: "Design" }));
+    await user.click(screen.getByRole("button", { name: "Annotate" }));
     preload.mark(first);
     await user.click(screen.getByRole("button", { name: "New browser tab" }));
     expect(screen.queryByTestId("browser-annotation-count")).toBeNull();
@@ -289,9 +292,9 @@ describe("SessionBrowserPanel multi-instance", () => {
     });
     expect(
       await screen.findByTestId("browser-annotation-count"),
-    ).toHaveTextContent("1 marked");
+    ).toHaveTextContent("1 comment");
     await waitFor(() =>
-      expect(screen.getByRole("button", { name: "Design" })).toHaveAttribute(
+      expect(screen.getByRole("button", { name: "Annotate" })).toHaveAttribute(
         "aria-pressed",
         "true",
       ),
@@ -301,7 +304,7 @@ describe("SessionBrowserPanel multi-instance", () => {
       preload.host.notify(first);
     });
     await waitFor(() =>
-      expect(screen.getByRole("button", { name: "Design" })).toHaveAttribute(
+      expect(screen.getByRole("button", { name: "Annotate" })).toHaveAttribute(
         "aria-pressed",
         "false",
       ),
@@ -325,7 +328,7 @@ describe("SessionBrowserPanel multi-instance", () => {
     await act(async () => release());
     expect(
       await screen.findByTestId("browser-annotation-count"),
-    ).toHaveTextContent("1 marked");
+    ).toHaveTextContent("1 comment");
   });
 
   it("hides on unmount, preserves marks on reattach, and never commands from a narrow Sheet", async () => {
@@ -342,7 +345,7 @@ describe("SessionBrowserPanel multi-instance", () => {
     await restored();
     expect(
       await screen.findByTestId("browser-annotation-count"),
-    ).toHaveTextContent("1 marked");
+    ).toHaveTextContent("1 comment");
     next.unmount();
     preload.invocations.length = 0;
     const narrow = render(
@@ -542,4 +545,103 @@ describe("SessionBrowserPanel multi-instance", () => {
     await act(async () => release());
     expect(screen.queryByTestId("browser-snapshot")).toBeNull();
   });
+
+  it("sends the panel's semantic tokens as the overlay palette when annotating starts", async () => {
+    const preload = installPreload();
+    const user = userEvent.setup();
+    mount();
+    await restored();
+
+    await user.click(screen.getByRole("button", { name: "Annotate" }));
+
+    const toggle = preload.invocations.find(
+      (item) => item.command === "browser_set_design_mode" && item.args?.enabled === true,
+    );
+
+    // The overlay lives in a page that cannot read Pace's stylesheets, so the
+    // colours travel as computed values. jsdom resolves none of the tokens —
+    // empty strings are still strings, and the page-side check decides which
+    // of them can actually parse.
+    expect(toggle?.args?.palette).toEqual({
+      accent: expect.any(String),
+      accentForeground: expect.any(String),
+      surface: expect.any(String),
+      foreground: expect.any(String),
+      border: expect.any(String),
+      muted: expect.any(String),
+    });
+  });
+
+  it("sends a palette-only update for page-origin activation without echoing mode", async () => {
+    const preload = installPreload();
+    mount();
+    await restored();
+    const target = await preload.target();
+
+    act(() => {
+      preload.host.tab({ sessionId: "s", tabId: target.tabId }).recordDesignMode(true);
+      preload.host.notify({ sessionId: "s", tabId: target.tabId });
+    });
+
+    await waitFor(() =>
+      expect(
+        preload.invocations.filter(
+          (item) => item.command === "browser_set_annotation_palette",
+        ),
+      ).toHaveLength(1),
+    );
+    expect(
+      preload.invocations.some(
+        (item) => item.command === "browser_set_design_mode",
+      ),
+    ).toBe(false);
+  });
+
+  it("toggles annotation mode on Cmd/Ctrl+Shift+A while a live tab is active", async () => {
+    const preload = installPreload();
+    mount();
+    await restored();
+
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        code: "KeyA",
+        key: "a",
+        metaKey: true,
+        shiftKey: true,
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+
+    await waitFor(() =>
+      expect(
+        preload.invocations.some(
+          (item) =>
+            item.command === "browser_set_design_mode" &&
+            item.args?.enabled === true,
+        ),
+      ).toBe(true),
+    );
+
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        code: "KeyA",
+        key: "a",
+        ctrlKey: true,
+        shiftKey: true,
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+
+    await waitFor(() =>
+      expect(
+        preload.invocations.some(
+          (item) =>
+            item.command === "browser_set_design_mode" &&
+            item.args?.enabled === false,
+        ),
+      ).toBe(true),
+    );
+  });
 });
diff --git a/apps/desktop/src/widgets/session-dock/session-browser-panel.tsx b/apps/desktop/src/widgets/session-dock/session-browser-panel.tsx
index 1d94bd11..daa5464d 100644
--- a/apps/desktop/src/widgets/session-dock/session-browser-panel.tsx
+++ b/apps/desktop/src/widgets/session-dock/session-browser-panel.tsx
@@ -14,6 +14,7 @@ import {
   openBrowserTab,
   openBrowserUrlExternally,
   reloadBrowser,
+  setBrowserAnnotationPalette,
   setBrowserBounds,
   setBrowserDesignMode,
   setBrowserVisible,
@@ -22,6 +23,7 @@ import {
 import { injectIntoComposer } from "@/entities/session/composer-injections";
 import { isElectronRuntime } from "@/shared/runtime";
 import type {
+  BrowserAnnotationPalette,
   BrowserSessionState,
   BrowserTabState,
   BrowserViewRect,
@@ -84,6 +86,8 @@ function BrowserSessionContent({
   // Every context change invalidates pending captures, even if the user switches back.
   const contextVersion = useRef(0);
   const viewportRef = useRef<HTMLDivElement>(null);
+  /** The panel's own root — the element its semantic tokens are read from. */
+  const surfaceRef = useRef<HTMLDivElement>(null);
   const instancesCallback = useRef(onInstancesChange);
   instancesCallback.current = onInstancesChange;
   const available = isElectronRuntime() && docked;
@@ -169,6 +173,44 @@ function BrowserSessionContent({
     () => (tabId ? { sessionId, tabId } : null),
     [sessionId, tabId],
   );
+
+  /**
+   * The overlay paints in a page that shares nothing with Pace's stylesheets,
+   * so the computed semantic tokens travel with the command and the page
+   * checks each colour itself.
+   */
+  const readAnnotationPalette = useCallback(():
+    | BrowserAnnotationPalette
+    | undefined => {
+    const element = surfaceRef.current;
+    if (!element) return undefined;
+    const styles = getComputedStyle(element);
+    const token = (name: string) => styles.getPropertyValue(name).trim();
+    return {
+      accent: token("--primary"),
+      accentForeground: token("--color-on-accent"),
+      surface: token("--surface"),
+      foreground: token("--foreground"),
+      border: token("--border"),
+      muted: token("--muted"),
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!available || !tabId || !active?.designMode) return;
+    const palette = readAnnotationPalette();
+    if (!palette) return;
+    void setBrowserAnnotationPalette({ sessionId, tabId }, palette).catch((error) => {
+      if (alive.current) setActionError(errorMessage(error));
+    });
+  }, [
+    active?.designMode,
+    available,
+    readAnnotationPalette,
+    sessionId,
+    tabId,
+  ]);
+
   const tabCount = group?.tabs.length ?? 0;
   const state: BrowserSurfaceState = !docked
     ? { kind: "narrow" }
@@ -277,6 +319,37 @@ function BrowserSessionContent({
       if (alive.current) setActionError(errorMessage(error));
     });
   };
+  const changeDesignMode = (tab: BrowserTabState, enabled: boolean) => {
+    runPageCommand(() =>
+      setBrowserDesignMode(
+        { sessionId, tabId: tab.tabId },
+        enabled,
+        // The palette only matters when the overlay comes up; main keeps the
+        // last one it saw for everything else.
+        enabled ? readAnnotationPalette() : undefined,
+      ),
+    );
+  };
+
+  // The in-page overlay listens for the same shortcut — this side covers the
+  // Pace window having focus while a browser tab is live.
+  useEffect(() => {
+    if (!available || state.kind !== "live" || !tabId) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (
+        event.code !== "KeyA" ||
+        !event.shiftKey ||
+        (!event.metaKey && !event.ctrlKey)
+      )
+        return;
+      const tab = groupRef.current?.tabs.find((item) => item.tabId === tabId);
+      if (!tab) return;
+      event.preventDefault();
+      changeDesignMode(tab, !tab.designMode);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [available, state.kind, tabId]);
   const submitAddress = async (url: string) => {
     if (!available || !url.trim()) return;
     const version = ++contextVersion.current;
@@ -370,7 +443,7 @@ function BrowserSessionContent({
       runPageCommand(() => reloadBrowser({ sessionId, tabId: active.tabId }));
   };
   return (
-    <BrowserSurface state={state}>
+    <BrowserSurface ref={surfaceRef} state={state}>
       <BrowserSurface.Tabs
         tabs={tabs}
         activeTabId={tabId}
@@ -406,10 +479,7 @@ function BrowserSessionContent({
             );
         }}
         onDesignModeChange={(enabled) => {
-          if (active)
-            runPageCommand(() =>
-              setBrowserDesignMode({ sessionId, tabId: active.tabId }, enabled),
-            );
+          if (active) changeDesignMode(active, enabled);
         }}
         onForward={() => {
           if (active)
diff --git a/docs/design/workspace.md b/docs/design/workspace.md
index b07739bc..77f01dc3 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`（地址/导航/design mode）+ `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。
 
 ```tsx
 <BrowserSurface state={state}>
diff --git a/docs/self-built-ui.md b/docs/self-built-ui.md
index 80e86342..a32647f5 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` 通道;决策记录 `.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`，支持新建、激活与关闭，右侧显示当前页标注数量；第二行放地址栏、历史导航和 design mode 工具条，标注数量独立到第一行以保留地址输入空间。原生 `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 独立记地址、加载/错误、design mode、标注与发送提示；Project 保存 URL 列表和激活项，兼容旧单 URL。`Send to composer` 握手取得同页截图与标注，降采样后只注入当前 Session 草稿；切 tab / Session 后到达的结果丢弃。工具条保持无弹层按钮，避免在冻结快照上标注；页内 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 独立记地址、加载/错误、标注模式、标注与发送提示；Project 保存 URL 列表和激活项，兼容旧单 URL。`Send to composer` 握手取得同页截图与标注，降采样后只注入当前 Session 草稿；切 tab / Session 后到达的结果丢弃。工具条保持无弹层按钮，避免在冻结快照上标注；页内 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 |
 
diff --git a/e2e/smoke/browser-surface.spec.ts b/e2e/smoke/browser-surface.spec.ts
index 49b3eff2..6cc981c2 100644
--- a/e2e/smoke/browser-surface.spec.ts
+++ b/e2e/smoke/browser-surface.spec.ts
@@ -119,6 +119,27 @@ async function readBrowserViewWidth(app: ElectronApplication) {
   return widths.at(-1) ?? 0;
 }
 
+/**
+ * The comment editor lives in the isolated world's closed shadow root —
+ * unreachable for `evaluate` — so the comment goes in as real input on the
+ * focused textarea (`insertText`), and Enter is a real key press the
+ * overlay's window-capture handler sees.
+ */
+async function typeAndSaveComment(app: ElectronApplication, text: string) {
+  await app.evaluate(({ BrowserWindow }, value) => {
+    const views = (BrowserWindow.getAllWindows()[0]?.contentView.children ?? [])
+      .filter(
+        (child): child is Electron.WebContentsView => "webContents" in child,
+      )
+      .filter((child) => child.webContents.getURL() !== "");
+    const view = views.at(-1);
+
+    view?.webContents.insertText(value);
+    view?.webContents.sendInputEvent({ type: "keyDown", keyCode: "Enter" });
+    view?.webContents.sendInputEvent({ type: "keyUp", keyCode: "Enter" });
+  }, text);
+}
+
 /** Opens the dock on the Browser surface, with no page loaded yet. */
 async function openBrowserSurface(testApp: PaceTestApplication) {
   const { window } = testApp;
@@ -262,7 +283,7 @@ test("Browser surface loads a page, follows the panel, and keeps popups in place
   }
 });
 
-test("Design mode marks a strict-CSP page, keeps the overlay to itself, and sends the marks to the composer", async () => {
+test("Annotate mode marks a strict-CSP page, keeps the overlay to itself, and sends the marks to the composer", async () => {
   const { server, origin } = await startPreviewServer();
   const testApp = await launchPace({
     seedSession: true,
@@ -285,7 +306,7 @@ test("Design mode marks a strict-CSP page, keeps the overlay to itself, and send
     // Page content can load before the renderer has synchronized native view bounds and visibility.
     await expect.poll(() => readBrowserViewVisible(testApp.app)).toBe(true);
 
-    await aside.getByRole("button", { name: "Design" }).click();
+    await aside.getByRole("button", { name: "Annotate" }).click();
 
     // The toolbar is plain buttons on purpose: a layer would trip the overlay
     // detection and the user would end up marking a frozen screenshot.
@@ -304,10 +325,14 @@ test("Design mode marks a strict-CSP page, keeps the overlay to itself, and send
 
     // Synthesized input cannot reach a native child view, so the page marks
     // itself; the isolated world's listener still sees the click (S0 spike).
+    // A click opens the draft editor — nothing is a mark until it is saved.
     await embedded.evaluate(() => document.getElementById("cta")!.click());
+    await expect(aside.getByTestId("browser-annotation-count")).toHaveCount(0);
+
+    await typeAndSaveComment(testApp.app, "Needs a bigger hit area");
 
     await expect(aside.getByTestId("browser-annotation-count")).toHaveText(
-      "1 marked",
+      "1 comment",
     );
 
     // Everything the overlay draws stays behind a closed shadow root: the page
@@ -336,10 +361,9 @@ test("Design mode marks a strict-CSP page, keeps the overlay to itself, and send
 
     const composer = window.getByTestId("full-chat-composer");
 
-    // No comment was typed — the bubble lives in the closed shadow root, out of
-    // reach of any driver — so this also covers the uncommented row.
+    // The comment typed into the shadow-root editor is on the row Pi reads.
     await expect(composer.getByRole("combobox", { name: "Prompt" })).toHaveText(
-      /#1 `#cta` \(button\) — \(no comment\)/,
+      /#1 `#cta` \(button\) — Needs a bigger hit area/,
     );
     await expect(
       composer.getByAltText("browser-annotations.png"),
@@ -356,10 +380,9 @@ test("Design mode marks a strict-CSP page, keeps the overlay to itself, and send
       ),
     );
 
-    await expect(aside.getByRole("button", { name: "Design" })).toHaveAttribute(
-      "aria-pressed",
-      "false",
-    );
+    await expect(
+      aside.getByRole("button", { name: "Annotate" }),
+    ).toHaveAttribute("aria-pressed", "false");
 
     await aside.getByRole("button", { name: "Clear marks" }).click();
     await expect(aside.getByTestId("browser-annotation-count")).toHaveCount(0);
@@ -397,7 +420,7 @@ test("Browser tabs isolate views and marks, restore the Project group, and close
     await window.keyboard.press("Enter");
     const first = await firstPage;
     await expect(first.locator("#cta")).toHaveText("Mark me");
-    await aside.getByRole("button", { name: "Design", exact: true }).click();
+    await aside.getByRole("button", { name: "Annotate", exact: true }).click();
     await expect
       .poll(() =>
         first.evaluate(() =>
@@ -406,8 +429,9 @@ test("Browser tabs isolate views and marks, restore the Project group, and close
       )
       .toBe(true);
     await first.evaluate(() => document.getElementById("cta")!.click());
+    await typeAndSaveComment(testApp.app, "Pinned to tab one");
     await expect(aside.getByTestId("browser-annotation-count")).toHaveText(
-      "1 marked",
+      "1 comment",
     );
 
     await aside.getByRole("button", { name: "New browser tab" }).click();
@@ -433,12 +457,12 @@ test("Browser tabs isolate views and marks, restore the Project group, and close
       .toEqual([false, true]);
     await expect(aside.getByTestId("browser-annotation-count")).toHaveCount(0);
     await expect(
-      aside.getByRole("button", { name: "Design", exact: true }),
+      aside.getByRole("button", { name: "Annotate", exact: true }),
     ).toHaveAttribute("aria-pressed", "false");
 
     await aside.getByRole("tab", { name: "Browser 1" }).click();
     await expect(aside.getByTestId("browser-annotation-count")).toHaveText(
-      "1 marked",
+      "1 comment",
     );
     await expect
       .poll(async () =>
@@ -484,11 +508,11 @@ test("Browser tabs isolate views and marks, restore the Project group, and close
     const addressBounds = (await aside
       .getByRole("textbox", { name: "Address" })
       .boundingBox())!;
-    const designBounds = (await aside
-      .getByRole("button", { name: "Design", exact: true })
+    const annotateBounds = (await aside
+      .getByRole("button", { name: "Annotate", exact: true })
       .boundingBox())!;
     expect(addressBounds.x + addressBounds.width).toBeLessThanOrEqual(
-      designBounds.x,
+      annotateBounds.x,
     );
 
     // A reload remounts the renderer while main keeps the Session's pages.
diff --git a/packages/core/src/browser-annotation.test.ts b/packages/core/src/browser-annotation.test.ts
index eae0f5f2..ff1c126e 100644
--- a/packages/core/src/browser-annotation.test.ts
+++ b/packages/core/src/browser-annotation.test.ts
@@ -16,7 +16,8 @@ describe("formatBrowserAnnotationPrompt", () => {
         screenshot: true,
         elements: [
           {
-            index: 1,
+            id: "e1",
+          index: 1,
             selector: "#cta",
             tag: "button",
             text: "Get started",
@@ -51,12 +52,14 @@ describe("formatBrowserAnnotationPrompt", () => {
         screenshot: true,
         elements: [
           {
-            index: 1,
+            id: "e1",
+          index: 1,
             selector: "main > p:nth-of-type(2)",
             tag: "p",
             rect: { x: 0, y: 0, width: 10, height: 10 },
           },
           {
+            id: "e2",
             index: 2,
             selector: "[data-testid=\"row\"]",
             tag: "li",
@@ -91,7 +94,8 @@ describe("formatBrowserAnnotationPrompt", () => {
         screenshot: false,
         elements: [
           {
-            index: 1,
+            id: "e1",
+          index: 1,
             selector: "#cta",
             tag: "button",
             text: "Get started",
@@ -123,6 +127,7 @@ describe("formatBrowserAnnotationPrompt", () => {
       screenshot: true,
       elements: [
         {
+          id: "e1",
           index: 1,
           selector: "#cta",
           tag: "button",
diff --git a/packages/core/src/browser-annotation.ts b/packages/core/src/browser-annotation.ts
index d62bb918..e1744e5f 100644
--- a/packages/core/src/browser-annotation.ts
+++ b/packages/core/src/browser-annotation.ts
@@ -24,6 +24,11 @@ export type BrowserAnnotationViewport = {
  * read from whatever `data-*` attributes the dev server stamped.
  */
 export type BrowserAnnotationElement = {
+  /**
+   * Stable identity for the annotation's lifetime, minted by the overlay
+   * (`crypto.randomUUID()`). `index` renumbers on delete; `id` never changes.
+   */
+  id: string;
   /** 1-based; the number the marker shows in the page and on the screenshot. */
   index: number;
   selector: string;