dsh-web-annotator 0.0.0-stage → 0.2.0-alpha.12

package/docs/harness-browser-annotation.patch

@@ -0,0 +1,1909 @@
+diff --git a/docs/subsystems/sidebar-right.md b/docs/subsystems/sidebar-right.md
+index 6315827..b61b1db 100644
+--- a/docs/subsystems/sidebar-right.md
++++ b/docs/subsystems/sidebar-right.md
+@@ -2,6 +2,8 @@
+ 
+ English | [中文](sidebar-right.zh.md)
+ 
++Browser declares additional toolbar and annotation-list child slots with data and bounded page-picker callbacks; their owner props and carrier restrictions are defined in the [Browser package reference](../../packages/client/ui-sidebar-browser/README.md#annotation-extension-points).
++
+ The right Sidebar is the Web Client's per-Session docking surface: a column of panes and tabs beside the conversation in which addressed content — a workspace file, a directory tree, the product's own pages — opens, splits, floats, and closes. [`dsh-client-ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.md) owns the surface, the tab-type registry, and the navigation service; [`dsh-client-ui-dockkit`](../../packages/client/ui-dockkit/README.md) is its internal layout engine; [`dsh-client-resources`](../../packages/client/resources/README.md) turns addresses into live values for any component; [`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) provides both the Host workspace service and the Client `file` resource provider.
+ 
+ This page is the reference for the subsystem's contracts: addresses, tab-type registration, the navigation service, the extension slots and their owner props, the resource model, the Workspace Files service, the shipped types, and what is deliberately not built. How the layout engine, the frame, and the surface fit together is in the [Agent Note](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md); slot mechanics are in the [Slots reference](slots.md).
+diff --git a/docs/subsystems/sidebar-right.zh.md b/docs/subsystems/sidebar-right.zh.md
+index 1df6007..1588a87 100644
+--- a/docs/subsystems/sidebar-right.zh.md
++++ b/docs/subsystems/sidebar-right.zh.md
+@@ -2,6 +2,8 @@
+ 
+ [English](sidebar-right.md) | 中文
+ 
++Browser 另行声明工具栏和批注列表子插槽，提供数据与受限的页面 picker 回调；owner props 和载体限制见 [Browser 包参考](../../packages/client/ui-sidebar-browser/README.zh.md#批注扩展点)。
++
+ 右侧 Sidebar 是 Web Client 里每个会话一份的停靠面：会话区旁的一列 pane 与 tab，按地址寻址的内容——工作区文件、目录树、产品自带页面——在这里打开、分栏、浮出、关闭。[`dsh-client-ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.zh.md) 拥有这个面、tab 类型注册表与导航服务；[`dsh-client-ui-dockkit`](../../packages/client/ui-dockkit/README.zh.md) 是它内部的布局引擎；[`dsh-client-resources`](../../packages/client/resources/README.zh.md) 把地址变成任何组件都能读的活数据；[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md) 同时提供 Host 工作区文件服务与 Client `file` 资源提供者。
+ 
+ 本页是该子系统契约的参考：地址、tab 类型注册、导航服务、扩展 slot 与其 owner props、资源模型、Workspace Files 服务、内置类型，以及明确不做的事。布局引擎、frame 与停靠面如何拼在一起见 [Agent Note](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)；slot 机制见 [Slots 参考](slots.zh.md)。
+diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md
+index f09b12c..6031abf 100644
+--- a/packages/client/ui-chat/README.md
++++ b/packages/client/ui-chat/README.md
+@@ -182,3 +182,5 @@ None.
+ </details>
+ 
+ **Runtime invariant:** No companion is published. Conversation and Slot registration enforce Chat target consistency.
++
++The optional `conversation.message.user-text` chain presents recognized user text inside the existing bubble, including local echoes and steering. A contribution receives only the joined text; all-decline preserves reference-aware ordinary rendering. It does not change the persisted message, model request, image attachments or message actions.
+diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md
+index 599c4cb..b7f4765 100644
+--- a/packages/client/ui-chat/README.zh.md
++++ b/packages/client/ui-chat/README.zh.md
+@@ -182,3 +182,5 @@ Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点，并且
+ </details>
+ 
+ **运行时不变式：** 不发布伴生入口。Conversation 与 slot 注册已经强制 Chat target 一致。
++
++可选的 `conversation.message.user-text` chain 在原有消息气泡中呈现已识别的用户正文，也覆盖本地回显与 steering。插件只收到拼接后的文本；全部拒绝时保留普通正文与引用呈现。它不改变持久化消息、模型请求、图片附件或消息操作。
+diff --git a/packages/client/ui-chat/src/client/apply.ts b/packages/client/ui-chat/src/client/apply.ts
+index e580772..94c73d0 100644
+--- a/packages/client/ui-chat/src/client/apply.ts
++++ b/packages/client/ui-chat/src/client/apply.ts
+@@ -185,6 +185,7 @@ export function apply(ctx: Context): void {
+       children: {
+         'conversation.chat.node': { kind: 'keyed', scope: 'session', inject: CHAT_NODE_INJECT },
+         'conversation.message.images': { kind: 'single', scope: 'session' },
++        'conversation.message.user-text': { kind: 'chain', scope: 'session' },
+       },
+       store: chatStore,
+       inject: (sessionId: SessionId): ChatViewInjected => {
+diff --git a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
+index f2269da..8e65d7c 100644
+--- a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
++++ b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
+@@ -45,7 +45,7 @@ function turnOf(node: ChatNode | undefined): number | undefined {
+ export const ChatNodeSeat = memo(function ChatNodeSeat({
+   nodeKey, groupPart, useChatNode, useChatNodeProcess, usePresentation,
+   cwd, openFile, openSkill, inspectCall, forkAt,
+-  loadImage, renderMessageImages, fileMentions, useStore, actions, renderSlot, t,
++  loadImage, renderMessageImages, renderUserText, fileMentions, useStore, actions, renderSlot, t,
+ }: ChatNodeSeatProps) {
+   const node = useChatNode(nodeKey)
+   const routedNode = node as ChatNode | undefined
+@@ -131,11 +131,12 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({
+       forkAt,
+       loadImage,
+       renderMessageImages,
++      renderUserText,
+       fileMentions,
+       turnProcess,
+     }, [
+     node, groupPart, cwd, openFile, openSkill, inspectCall, forkAt,
+-    loadImage, renderMessageImages, fileMentions, turnProcess,
++    loadImage, renderMessageImages, renderUserText, fileMentions, turnProcess,
+   ])
+   if (routedNode === undefined || owner === null) return null
+   // Runtime dispatch owns the correlation: every Node's discriminant is the
+diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
+index 460f98b..cf485d5 100644
+--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
++++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
+@@ -10,7 +10,7 @@ import type { PendingSubmission } from '@deepseek-ai/dsh-api-session-controller/
+ import {
+   Button, IconChevronDownOutlineRegular, MarkdownDelegateProvider, Modal,
+ } from '@deepseek-ai/dsh-client-ui-primitives'
+-import type { ChatViewSlotProps, OpenFileOptions } from '../contract/slots.ts'
++import type { ChatNodeOwnerProps, ChatViewSlotProps, OpenFileOptions } from '../contract/slots.ts'
+ import type { ChatSnapshot } from '../contract/snapshot.ts'
+ import { PendingSteeringBubble, PendingSubmissionBubble } from './MessageItem.tsx'
+ import { ChatNodeSeat } from './ChatNodeSeat.tsx'
+@@ -77,10 +77,10 @@ const ChatNodeList = memo(function ChatNodeList({ entries, useChatGroup, pending
+   })
+   const pendingRows = pendingInputs.map(item => 'requestId' in item ? (
+     <PendingSubmissionBubble key={item.requestId} submission={item}
+-      renderMessageImages={seatProps.renderMessageImages} t={seatProps.t} />
++        renderMessageImages={seatProps.renderMessageImages} renderUserText={seatProps.renderUserText} t={seatProps.t} />
+   ) : (
+     <PendingSteeringBubble key={item.id} content={item.content}
+-      renderMessageImages={seatProps.renderMessageImages} t={seatProps.t} />
++        renderMessageImages={seatProps.renderMessageImages} renderUserText={seatProps.renderUserText} t={seatProps.t} />
+   ))
+   const tail = entries.at(-1)
+   const node = tail?.kind === 'node' ? seatProps.nodeStore.get(tail.key) : undefined
+@@ -99,7 +99,7 @@ const ChatNodeList = memo(function ChatNodeList({ entries, useChatGroup, pending
+  * ordered business Node crosses the keyed renderer seat.
+  */
+ export function ChatView({
+-  useSession, useChat, useChatNode, useChatNodeProcess, useChatGroup, useConversation, useSessions, useStore, actions, renderSlot,
++    useSession, useChat, useChatNode, useChatNodeProcess, useChatGroup, useConversation, useSessions, useStore, actions, renderSlot, renderSlotChain,
+   sessionId, openFile, openSkill, openExternalLink, loadOlder, loadThrough, loadImage, inspectCall, chatScroll, forkAt, fileMentions,
+   usePresentation, useProjection, t,
+ }: ChatViewSlotProps) {
+@@ -210,6 +210,10 @@ export function ChatView({
+     owner => renderSlot('conversation.message.images', { ...owner, loadImage }),
+     [loadImage, renderSlot],
+   )
++  const renderUserText = useCallback<ChatNodeOwnerProps['renderUserText']>(
++    (text, fallback) => renderSlotChain('conversation.message.user-text', { text }, { fallback }),
++    [renderSlotChain],
++  )
+ 
+   const firstKey = order[0]
+   const firstSeq = firstKey === undefined ? null : nodeStore.get(firstKey)?.anchorSeq ?? null
+@@ -272,6 +276,7 @@ export function ChatView({
+                 forkAt={forkAt}
+                 loadImage={loadImage}
+                 renderMessageImages={renderMessageImages}
++                  renderUserText={renderUserText}
+                 fileMentions={fileMentions}
+                 renderSlot={renderSlot}
+                 t={t}
+diff --git a/packages/client/ui-chat/src/client/chat/MessageItem.tsx b/packages/client/ui-chat/src/client/chat/MessageItem.tsx
+index 9005150..22094af 100644
+--- a/packages/client/ui-chat/src/client/chat/MessageItem.tsx
++++ b/packages/client/ui-chat/src/client/chat/MessageItem.tsx
+@@ -160,11 +160,12 @@ function TurnMaxTokensItem({ t }: {
+ 
+ /** Right-aligned bubble shared by user and steering rows. */
+ function UserStyleBubble({
+-  content, renderMessageImages, actions, pending = false, echo = false, referenceLabels = [], skillNames = [],
++  content, renderMessageImages, renderUserText, actions, pending = false, echo = false, referenceLabels = [], skillNames = [],
+   previewAttachments, references, t,
+ }: {
+   content: readonly unknown[]
+   renderMessageImages: ChatNodeOwnerProps['renderMessageImages']
++  renderUserText: ChatNodeOwnerProps['renderUserText']
+   /** Optional IconActions (or similar) below the bubble; receives the joined text. */
+   actions?: (text: string) => ReactNode
+   /** Whether this is the Host-authoritative pre-admission steering projection. */
+@@ -219,7 +220,7 @@ function UserStyleBubble({
+           </div>
+         )}
+         {showBubble && <div className={css.bubble}>
+-          {projectUserText(text, referenceLabels, skillNames, 'skill', references)}
++          {renderUserText(text, projectUserText(text, referenceLabels, skillNames, 'skill', references))}
+           {rest.map((block, i) => <JsonBlock key={i} label={t('message.extraBlock')} payload={block} truncatedLabel={truncated} />)}
+         </div>}
+         {referenceLabels.length > 0 && (
+@@ -239,15 +240,17 @@ function UserStyleBubble({
+  * @param props - Pending message content and conversation translator.
+  * @returns the pending steering bubble.
+  */
+-export function PendingSteeringBubble({ content, renderMessageImages, t }: {
++export function PendingSteeringBubble({ content, renderMessageImages, renderUserText, t }: {
+   content: readonly unknown[]
+   renderMessageImages: ChatNodeOwnerProps['renderMessageImages']
++  renderUserText: ChatNodeOwnerProps['renderUserText']
+   t: ChatViewSlotProps['t']
+ }): ReactNode {
+   return (
+     <UserStyleBubble
+       content={content}
+       renderMessageImages={renderMessageImages}
++      renderUserText={renderUserText}
+       pending
+       t={t}
+       actions={text => (
+@@ -270,9 +273,10 @@ export function PendingSteeringBubble({ content, renderMessageImages, t }: {
+  * @param props - the session snapshot's pending submission and render seats.
+  * @returns the echoed user bubble.
+  */
+-export function PendingSubmissionBubble({ submission, renderMessageImages, t }: {
++export function PendingSubmissionBubble({ submission, renderMessageImages, renderUserText, t }: {
+   submission: PendingSubmission
+   renderMessageImages: ChatNodeOwnerProps['renderMessageImages']
++  renderUserText: ChatNodeOwnerProps['renderUserText']
+   t: ChatViewSlotProps['t']
+ }): ReactNode {
+   const content = useMemo(
+@@ -300,6 +304,7 @@ export function PendingSubmissionBubble({ submission, renderMessageImages, t }:
+       content={content}
+       previewAttachments={previewAttachments}
+       renderMessageImages={renderMessageImages}
++      renderUserText={renderUserText}
+       pending={submission.placement === 'steering'}
+       echo
+       t={t}
+@@ -318,7 +323,7 @@ export function PendingSubmissionBubble({ submission, renderMessageImages, t }:
+ 
+ /** User and admitted-steering keyed Chat renderer. */
+ export const UserMessageNodeView = memo(function UserMessageNodeView({
+-  node, renderMessageImages, openFile, openSkill, t,
++  node, renderMessageImages, renderUserText, openFile, openSkill, t,
+ }: ChatNodeViewProps<'user' | 'steering'>) {
+   const data = node.data
+   return (
+@@ -326,6 +331,7 @@ export const UserMessageNodeView = memo(function UserMessageNodeView({
+       content={data.content}
+       references={{ openFile, openSkill }}
+       renderMessageImages={renderMessageImages}
++      renderUserText={renderUserText}
+       {...data.referenceLabels === undefined ? {} : { referenceLabels: data.referenceLabels }}
+       {...data.skillNames === undefined ? {} : { skillNames: data.skillNames }}
+       t={t}
+diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts
+index 5c7a8e3..c661e01 100644
+--- a/packages/client/ui-chat/src/client/contract/slots.ts
++++ b/packages/client/ui-chat/src/client/contract/slots.ts
+@@ -1,4 +1,5 @@
+ /** Chat-owned Slot declarations and composed component props. */
++import type { ReactNode } from 'react'
+ import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
+ import type { SessionId, SessionSeq } from '@deepseek-ai/dsh-session/types'
+ import type {
+@@ -158,6 +159,8 @@ export interface ChatNodeInjected {
+ 
+ /** Stable owner currency delivered to a keyed Chat renderer. */
+ export interface ChatNodeOwnerProps {
++  /** Offer one user text to the feature chain while preserving the default presentation. */
++  renderUserText: (text: string, fallback: ReactNode) => ReactNode
+   /** Renderer-owned Node portion selected by the grouping Definition. */
+   groupPart?: string
+   cwd?: string | undefined
+@@ -262,7 +265,7 @@ export interface ChatViewInjected {
+ /** Full Chat view props. */
+ export type ChatViewSlotProps =
+   PropsRuntime<'conversation.view'>
+-  & PropsRenderSlots<'conversation.chat.node' | 'conversation.message.images'>
++  & PropsRenderSlots<'conversation.chat.node' | 'conversation.message.images' | 'conversation.message.user-text'>
+   & PropsStore<ChatStore>
+   & InjectFace<ChatViewInjected>
+   & PropsLocale<'chat'>
+@@ -282,6 +285,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
+   }
+ 
+   interface SlotMap {
++    /** Feature-owned presentation of recognized user text; all-decline keeps the normal bubble. */
++    'conversation.message.user-text': { kind: 'chain'; scope: 'session'; owner: { readonly text: string } }
+     /**
+      * Final Chat node renderer, keyed by `ChatNodeKind`. The component receives
+      * the typed node, shared Chat actions, and Turn-data hook. Reusing a key
+diff --git a/packages/client/ui-layout/README.md b/packages/client/ui-layout/README.md
+index e32e926..bbeeb71 100644
+--- a/packages/client/ui-layout/README.md
++++ b/packages/client/ui-layout/README.md
+@@ -31,6 +31,8 @@ The root slot composes the sidebar, main content, and right column. The sidebar
+ 
+ Global panels occupy the root-scoped `main` keyed slot; `conversation` is the reserved key for the Conversation. `ctx.layout.selectPanel(id)` selects a registered panel, and `null` selects the Conversation without changing the current Session. No global panel is registered by the shipped composition.
+ 
++While the right panel is fullscreen, the covered main column is invisible and inert but remains mounted and measured. This prevents glass themes from painting or focusing the chat above the panel; restoring the panel preserves the same composer and draft.
++
+ <a id="window-chrome-seat"></a>
+ ### Window-chrome seat
+ 
+diff --git a/packages/client/ui-layout/README.zh.md b/packages/client/ui-layout/README.zh.md
+index 83b29e5..9ab9b41 100644
+--- a/packages/client/ui-layout/README.zh.md
++++ b/packages/client/ui-layout/README.zh.md
+@@ -31,6 +31,8 @@ kind: "package-reference"
+ 
+ 全局面板占据 root 作用域的 `main` keyed slot；`conversation` 是为会话界面保留的 key。`ctx.layout.selectPanel(id)` 选中已注册面板，`null` 则选中会话界面，但不改变当前会话。默认组合不注册任何全局面板。
+ 
++右侧面板全屏时，后方主栏不可见且设为 inert，但保持挂载和尺寸。玻璃主题因此不会让聊天界面绘制在面板上方或误获焦点；退出全屏恢复同一输入框与草稿。
++
+ <a id="window-chrome-seat"></a>
+ ### 窗口 chrome 座
+ 
+diff --git a/packages/client/ui-layout/src/client/AppFrame.module.css b/packages/client/ui-layout/src/client/AppFrame.module.css
+index 56494a9..c707f8e 100644
+--- a/packages/client/ui-layout/src/client/AppFrame.module.css
++++ b/packages/client/ui-layout/src/client/AppFrame.module.css
+@@ -74,6 +74,14 @@
+   overflow: hidden;
+ }
+ 
++/* Keep the covered main tree mounted and measured, but out of paint and focus.
++   A glass theme can create a stacking context on the right panel, trapping its
++   dock layer below main content. Fullscreen owns the visible center regardless
++   of that theme; restoring it preserves the same composer and draft. */
++.frame[data-rightbar-fullscreen] .centerCol {
++  visibility: hidden;
++}
++
+ /* macOS desktop: the frame goes transparent so window vibrancy reaches the
+    sidebar column, which keeps only a translucent tint; the centre paints the
+    base background itself to stay opaque. The sidebar/centre separator moves
+diff --git a/packages/client/ui-layout/src/client/AppFrame.tsx b/packages/client/ui-layout/src/client/AppFrame.tsx
+index 841f9f7..1f6ba88 100644
+--- a/packages/client/ui-layout/src/client/AppFrame.tsx
++++ b/packages/client/ui-layout/src/client/AppFrame.tsx
+@@ -32,8 +32,9 @@ export type AppFrameProps =
+   & PropsLocale<'common'>
+ 
+ /** Center column grid item (session-body building block). */
+-function CenterColumn(props: { children?: ReactNode }) {
+-  return <div className={css.centerCol}>{props.children}</div>
++function CenterColumn(props: { children?: ReactNode; covered: boolean }) {
++  return <div className={css.centerCol} aria-hidden={props.covered || undefined}
++    {...(props.covered ? { inert: '' } : {})}>{props.children}</div>
+ }
+ 
+ /** Subscribe to the main key without subscribing the column frame to each panel id. */
+@@ -281,7 +282,7 @@ export function AppFrame({
+         {sidebar}
+       </div>
+       <>
+-        <CenterColumn>{main}</CenterColumn>
++        <CenterColumn covered={layoutInfo.rightbarFullscreen}>{main}</CenterColumn>
+         <RightbarColumn>
+           {renderSlot('rightbar', { width: normal.rightbar, viewportWidth: viewport, canShow: normal.rightbar > 0 })}
+         </RightbarColumn>
+diff --git a/packages/client/ui-sidebar-browser/README.md b/packages/client/ui-sidebar-browser/README.md
+index b15844e..592d2f2 100644
+--- a/packages/client/ui-sidebar-browser/README.md
++++ b/packages/client/ui-sidebar-browser/README.md
+@@ -46,6 +46,14 @@ The `browser.new` command opens a separate Browser page in the focused dock pane
+ 
+ The toolbar provides Back, Forward, Reload, Go, and Open in system browser. Web also offers a per-tab sandbox toggle; disabling it is temporary and displays an amber warning with neutral text. Desktop shows the observed page title. After a restart, Browser shows the saved title and URL; Restore or Reload opens that address only when requested.
+ 
++### Annotation extension points
++
++Browser declares session-scoped list slots `sidebar.right.tab.browser.toolbar` and `sidebar.right.tab.browser.annotations`. Toolbar contributions appear immediately before Reload. Owner props carry the tab ID, known URL, loading state and bounded `annotate(options)` / `cancelAnnotation()` callbacks; they never expose DOM, guest identifiers or an evaluator. Contributions own localized controls, retained annotation queues and any explicit Session submission.
++
++The picker supports element clicks, whitespace points and exact drag rectangles. Holding Space temporarily restores page interaction; spaces in the editor remain text input. Escape, navigation, physical unmount, cancellation and disposal release the picker. Results contain a comment/question intent, note, page identity, viewport, document and viewport rectangles, and bounded DOM candidates; candidates never replace a region's rectangle.
++
++Web requires a cooperating page bridge using the `dsh-browser-annotation-v1` MessageChannel request. The provider enforces the known HTTP(S) origin and page URL and rejects absent bridges or invalid results. Desktop executes only the fixed compiled picker inside its approved webview, validates its JSON result and exposes no Node or Electron capability. The local Desktop annotation implementation requires native product validation before release; these operations do not attach screenshots.
++
+ -----
+ 
+ <a id="understand-the-implementation"></a>
+diff --git a/packages/client/ui-sidebar-browser/README.zh.md b/packages/client/ui-sidebar-browser/README.zh.md
+index d09d327..df24c5c 100644
+--- a/packages/client/ui-sidebar-browser/README.zh.md
++++ b/packages/client/ui-sidebar-browser/README.zh.md
+@@ -46,6 +46,14 @@ Client 插件可以调用 `ctx.sidebarRight.openTab('browser', { params: { url }
+ 
+ 工具栏提供后退、前进、刷新、前往和在系统浏览器中打开。Web 还提供逐 tab sandbox 开关；关闭它是临时选择，并会显示灰字、琥珀色底的警告。Desktop 显示观察到的页面标题。重启后，Browser 展示保存的标题和 URL；只有点击恢复或刷新才打开该地址。
+ 
++### 批注扩展点
++
++Browser 声明会话作用域的 list 插槽 `sidebar.right.tab.browser.toolbar` 和 `sidebar.right.tab.browser.annotations`。工具栏贡献紧挨“刷新”左侧显示。Owner props 包含 tab ID、已知 URL、加载状态，以及受限的 `annotate(options)` / `cancelAnnotation()` 回调，不暴露 DOM、guest 标识或求值器。贡献方负责本地化控件、保留的批注队列与用户明确触发的会话提交。
++
++Picker 支持点击元素、空白位置以及精确拖动矩形。按住空格临时恢复网页交互，编辑器中的空格仍用于文本输入。Escape、导航、物理卸载、取消与销毁都会释放 picker。结果包含评论 / 提问意图、文字、页面身份、视口、文档 / 视口矩形与有界 DOM 候选；候选不会替代区域的真实矩形。
++
++Web 需要配合 `dsh-browser-annotation-v1` MessageChannel 请求的页面连接。提供方限制已知 HTTP(S) origin 与完整页面 URL，拒绝缺少连接或无效结果的页面。Desktop 只在已批准的 webview 中执行固定的编译后 picker，校验 JSON 结果，不提供 Node 或 Electron 能力。当前本地 Desktop 批注实现发布前仍需原生产品验证；这些操作不附截图。
++
+ -----
+ 
+ <a id="understand-the-implementation"></a>
+diff --git a/packages/client/ui-sidebar-browser/src/client/annotation/iframe-annotation.ts b/packages/client/ui-sidebar-browser/src/client/annotation/iframe-annotation.ts
+new file mode 100644
+index 0000000..867e819
+--- /dev/null
++++ b/packages/client/ui-sidebar-browser/src/client/annotation/iframe-annotation.ts
+@@ -0,0 +1,74 @@
++/** Bounded annotation requests to a bridge-enabled iframe owned by Browser. */
++import type { BrowserAnnotationOptions } from './page-inspector.ts';
++import { isAnnotationResult, type AnnotationResult } from './protocol.ts';
++
++/** Request one picker without exposing the iframe or an evaluator to plugins.
++ * @param frame - provider-owned iframe.
++ * @param url - controller-known HTTP(S) page.
++ * @param options - picker copy and theme.
++ * @param signal - operation lifetime.
++ * @returns saved evidence or cancellation; rejects when the page has no bridge.
++ */
++export function annotateIframe(
++  frame: HTMLIFrameElement,
++  url: string,
++  options: BrowserAnnotationOptions,
++  signal: AbortSignal,
++): Promise<AnnotationResult> {
++  if (signal.aborted) return Promise.resolve({ cancelled: true });
++  return new Promise((resolve, reject) => {
++    const channel = new MessageChannel();
++    let ended = false;
++    let ready = false;
++    const handshake = setTimeout(() => {
++      if (!ready) finish(undefined, new Error('annotation-unavailable'));
++    }, 3000);
++    function finish(value?: AnnotationResult, error?: Error) {
++      if (ended) return;
++      ended = true;
++      channel.port1.postMessage({ type: 'cancel' });
++      channel.port1.close();
++      channel.port2.close();
++      clearTimeout(handshake);
++      signal.removeEventListener('abort', cancel);
++      frame.removeEventListener('load', cancel);
++      if (error) reject(error);
++      else resolve(value || { cancelled: true });
++    }
++    function cancel() {
++      finish({ cancelled: true });
++    }
++    signal.addEventListener('abort', cancel, { once: true });
++    frame.addEventListener('load', cancel, { once: true });
++    channel.port1.onmessage = (event) => {
++      if (event.data?.ready === true && !ready) {
++        ready = true;
++        clearTimeout(handshake);
++        return;
++      }
++      if (!isAnnotationResult(event.data)) {
++        finish(undefined, new Error('annotation-invalid'));
++        return;
++      }
++      if (!('cancelled' in event.data) && event.data.url !== url) {
++        finish(undefined, new Error('annotation-page-changed'));
++        return;
++      }
++      finish(event.data);
++    };
++    try {
++      if (!frame.contentWindow) {
++        finish(undefined, new Error('annotation-unavailable'));
++        return;
++      }
++      frame.contentWindow.postMessage(
++        { channel: 'dsh-browser-annotation-v1', type: 'start', options },
++        new URL(url).origin,
++        [channel.port2],
++      );
++      frame.focus();
++    } catch (error) {
++      finish(undefined, error instanceof Error ? error : new Error('annotation-unavailable'));
++    }
++  });
++}
+diff --git a/packages/client/ui-sidebar-browser/src/client/annotation/page-inspector.ts b/packages/client/ui-sidebar-browser/src/client/annotation/page-inspector.ts
+new file mode 100644
+index 0000000..9d57afa
+--- /dev/null
++++ b/packages/client/ui-sidebar-browser/src/client/annotation/page-inspector.ts
+@@ -0,0 +1,915 @@
++/** Data returned by one explicit, in-page annotation gesture. */
++export interface BrowserAnnotation {
++  /** Provider-captured viewport with the saved area marked; never part of DOM evidence. */
++  readonly screenshot?: BrowserAnnotationImage;
++  /** Requested CSS values for the precisely selected element. */
++  readonly styleChanges?: Record<string, { before: string; after: string }>;
++  readonly intent: 'comment' | 'question';
++  readonly note: string;
++  readonly url: string;
++  readonly title: string;
++  readonly viewport: { width: number; height: number };
++  readonly selection: {
++    kind: 'element' | 'region' | 'point';
++    /** CSS pixels in the document, never substituted with a parent element. */
++    rect: { x: number; y: number; width: number; height: number };
++    viewportRect: { x: number; y: number; width: number; height: number };
++    scroll: { x: number; y: number };
++    candidates: BrowserAnnotationElement[];
++  };
++}
++
++/** Bounded JPEG capture supplied by Browser, not by a visited page. */
++export interface BrowserAnnotationImage {
++  readonly mediaType: 'image/jpeg';
++  readonly data: string;
++  readonly width: number;
++  readonly height: number;
++}
++
++/** Bounded DOM evidence; candidates do not redefine a point or region. */
++export interface BrowserAnnotationElement {
++  selector: string;
++  shadowHosts: string[];
++  matchCount: number;
++  tag: string;
++  text: string;
++  rect: { x: number; y: number; width: number; height: number };
++  styles: Record<string, string>;
++  source?: string;
++}
++
++/** Copy and theme supplied by the owning Harness plugin, never by the page. */
++export interface BrowserAnnotationOptions {
++  readonly intent: 'comment' | 'question';
++  readonly dark: boolean;
++  readonly copy: {
++    select: string;
++    comment: string;
++    question: string;
++    placeholder: string;
++    settings: string;
++    save: string;
++    cancel: string;
++    parent: string;
++    child: string;
++    targetGone: string;
++    empty: string;
++    region: string;
++    point: string;
++    interact: string;
++    color: string;
++    background: string;
++    opacity: string;
++    font: string;
++    fontSize: string;
++    fontWeight: string;
++    spacing: string;
++    elementOnly: string;
++    invalidStyle: string;
++    applyStyles: string;
++    styleHint: string;
++  };
++}
++
++declare global {
++  interface Window {
++    __DSH_PAGE_ANNOTATION_CANCEL__?: () => void;
++  }
++}
++
++/**
++ * Run a bounded picker inside the inspected document. This function is self-contained
++ * so Desktop can execute its compiled body in an approved guest, without a preload.
++ * @param options - localized copy, initial intent, and host theme.
++ * @returns the saved annotation, or a cancellation when no annotation was saved.
++ */
++export function annotatePage(
++  options: BrowserAnnotationOptions,
++): Promise<BrowserAnnotation | { cancelled: true }> {
++  window.__DSH_PAGE_ANNOTATION_CANCEL__?.();
++  const doc = document;
++  const originalUrl = location.href;
++  const originalFocus = doc.activeElement;
++  const root = doc.createElement('div');
++  root.setAttribute('data-dsh-page-annotation', '');
++  root.style.cssText = 'position:fixed;inset:0;z-index:2147483647;pointer-events:none;';
++  const shadow = root.attachShadow({ mode: 'open' });
++  const style = doc.createElement('style');
++  style.textContent = `
++    :host{all:initial;color-scheme:${options.dark ? 'dark' : 'light'}}
++    *{box-sizing:border-box}
++    .outline{position:fixed;pointer-events:none;border:2px solid #2979ff;border-radius:5px;background:#2979ff0c}
++    .hint{position:fixed;top:12px;left:50%;transform:translateX(-50%);padding:8px 12px;border-radius:8px;background:#181a20;color:#fff;font:13px/20px system-ui;max-width:calc(100vw - 24px);pointer-events:none}
++    .editor,.options{position:fixed;pointer-events:auto;border:0;background:${options.dark ? '#292a2d' : '#fff'};color:${options.dark ? '#ededee' : '#303338'};box-shadow:0 0 0 .5px ${options.dark ? '#55565b' : '#dcdfe3'},0 2px 8px #00000014;font:14px/22px system-ui}
++    .editor{border-radius:26px;corner-shape:round;padding:7px 8px;width:min(384px,calc(100vw - 24px));overflow:hidden;max-height:calc(100vh - 24px);display:flex;flex-direction:column}
++    .editor.expanded{width:min(420px,calc(100vw - 24px));border-radius:24px;padding:0}
++    .expanded>.row{padding:12px 14px;flex:none}
++    .expanded>.row>.save{display:none}
++    .expanded textarea{max-height:min(66px,20vh)}
++    .editor:focus-within{box-shadow:0 0 0 .5px ${options.dark ? '#85868b' : '#bfc4cc'},0 2px 8px #00000014}
++    .row{display:flex;align-items:center;gap:10px}
++    button,select,textarea{font:inherit;color:inherit}
++    button{border:0;border-radius:8px;padding:6px 8px;background:transparent;cursor:pointer;flex:none}
++    button:disabled{opacity:.4;cursor:default}
++    button:hover:not(:disabled){background:${options.dark ? '#3b3c40' : '#f0f1f3'}}
++    button:focus-visible,select:focus-visible{outline:2px solid #2979ff;outline-offset:2px}
++    .options-toggle,.save{display:flex;align-items:center;justify-content:center;padding:0;width:30px;height:30px;border-radius:50%;corner-shape:round}
++    .options-toggle{color:${options.dark ? '#bdc0c5' : '#737880'}}
++    .save,.save:disabled{background:${options.dark ? '#797c82' : '#a2a5a9'};color:#fff;opacity:1}
++    .save:not(:disabled){background:${options.dark ? '#d2d3d6' : '#777c83'};color:${options.dark ? '#242529' : '#fff'}}
++    .save:hover:not(:disabled){background:${options.dark ? '#eeeff1' : '#60656d'}}
++    textarea{display:block;flex:1;width:100%;min-width:0;height:22px;max-height:110px;resize:none;border:0;background:transparent;padding:0;margin:0;outline:0;line-height:22px;overflow-y:auto}
++    textarea::placeholder{color:${options.dark ? '#aaaeb5' : '#888e96'};opacity:1}
++    .options{position:static;box-shadow:none;flex:1;min-height:0;overflow:auto;font-size:14px;line-height:22px;scrollbar-width:thin}
++    .target-row{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:7px 20px;background:${options.dark ? '#35363a' : '#f4f4f4'}}
++    .target{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:${options.dark ? '#c9ccd1' : '#656b73'}}
++    .target-controls{display:flex;gap:2px;flex:none}
++    .target-controls button{font-size:13px;padding:0;width:24px;height:24px}
++    .properties{padding:12px 20px;display:grid;gap:10px}
++    .property{display:grid;grid-template-columns:minmax(90px,1fr) minmax(0,180px);align-items:center;gap:12px;color:${options.dark ? '#c9ccd1' : '#6e747b'}}
++    .field{display:flex;align-items:center;gap:9px;border:.5px solid ${options.dark ? '#57595f' : '#dedfe2'};border-radius:13px;padding:7px 10px;min-width:0}
++    .field input{font:13px/20px ui-monospace,monospace;background:transparent;color:inherit;border:0;outline:0;width:100%;min-width:0}
++    .field:focus-within{border-color:${options.dark ? '#a2a5ac' : '#a5a9b1'}}
++    .swatch{width:22px;height:22px;border-radius:7px;flex:none;box-shadow:inset 0 0 0 .5px #8886}
++    .intent{display:flex;align-items:center;justify-content:space-between;padding:0 20px 12px;gap:8px;font-size:13px;color:${options.dark ? '#c9ccd1' : '#6e747b'}}
++    select{font:inherit;border:.5px solid ${options.dark ? '#57595f' : '#dedfe2'};background:transparent;border-radius:10px;padding:5px 8px;max-width:160px}
++    .footer{border-top:.5px solid ${options.dark ? '#44464b' : '#eee'};display:flex;align-items:center;justify-content:space-between;padding:10px 12px;flex:none}
++    .footer>.cancel{border:.5px solid ${options.dark ? '#55565b' : '#e5e6e9'};border-radius:20px;padding:6px 12px;font-size:13px}
++    .style-hint{font-size:12px;line-height:18px;margin:3px 0;color:${options.dark ? '#adb1b8' : '#8a9097'}}
++    .error{color:${options.dark ? '#ffb0a9' : '#b82920'};font-size:12px;padding:3px 40px 1px}
++    .hidden{display:none!important}
++  `;
++  const outline = doc.createElement('div');
++  outline.className = 'outline hidden';
++  const hint = doc.createElement('div');
++  hint.className = 'hint';
++  hint.textContent = options.copy.select;
++  const editor = doc.createElement('form');
++  editor.className = 'editor hidden';
++  editor.setAttribute('aria-label', options.copy.placeholder);
++  const row = doc.createElement('div');
++  row.className = 'row';
++  // The injected picker reuses the shared SlidersTwoOutline and CheckOutline artwork.
++  function icon(parts: readonly (readonly [string, Record<string, string>])[]) {
++    const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg');
++    for (const [name, value] of Object.entries({
++      width: '18',
++      height: '18',
++      viewBox: '0 0 16 16',
++      fill: 'none',
++      stroke: 'currentColor',
++      'stroke-width': '1.3',
++      'stroke-linecap': 'round',
++      'stroke-linejoin': 'round',
++      'aria-hidden': 'true',
++    }))
++      svg.setAttribute(name, value);
++    for (const [tag, attributes] of parts) {
++      const node = doc.createElementNS('http://www.w3.org/2000/svg', tag);
++      for (const [name, value] of Object.entries(attributes)) node.setAttribute(name, value);
++      svg.append(node);
++    }
++    return svg;
++  }
++  const settings = doc.createElement('button');
++  settings.type = 'button';
++  settings.className = 'options-toggle';
++  settings.title = options.copy.settings;
++  settings.setAttribute('aria-label', options.copy.settings);
++  settings.setAttribute('aria-expanded', 'false');
++  settings.setAttribute('aria-haspopup', 'dialog');
++  settings.append(
++    icon([
++      ['path', { d: 'M2.3 5h5.85M12.05 5h1.65' }],
++      ['circle', { cx: '9.95', cy: '5', r: '1.45' }],
++      ['path', { d: 'M2.3 11h1.65M7.85 11h5.85' }],
++      ['circle', { cx: '5.75', cy: '11', r: '1.45' }],
++    ]),
++  );
++  const optionsPanel = doc.createElement('section');
++  optionsPanel.className = 'options hidden';
++  optionsPanel.setAttribute('role', 'dialog');
++  optionsPanel.setAttribute('aria-label', options.copy.settings);
++  const intentRow = doc.createElement('div');
++  intentRow.className = 'intent';
++  const intentLabel = doc.createElement('span');
++  intentLabel.textContent = options.copy.comment + ' / ' + options.copy.question;
++  const intent = doc.createElement('select');
++  intent.setAttribute('aria-label', options.copy.comment + ' / ' + options.copy.question);
++  for (const [value, label] of [
++    ['comment', options.copy.comment],
++    ['question', options.copy.question],
++  ]) {
++    const option = doc.createElement('option');
++    option.value = value!;
++    option.textContent = label!;
++    intent.append(option);
++  }
++  intent.value = options.intent;
++  const input = doc.createElement('textarea');
++  input.placeholder = options.copy.placeholder;
++  input.setAttribute('aria-label', options.copy.placeholder);
++  input.maxLength = 1000;
++  const save = doc.createElement('button');
++  save.type = 'submit';
++  save.className = 'save';
++  save.disabled = true;
++  save.append(
++    icon([
++      [
++        'path',
++        { d: 'M2.25 8.5L5.49732 11.7473C5.90519 12.1552 6.57263 12.1344 6.95426 11.7018L13.75 4' },
++      ],
++    ]),
++  );
++  save.title = options.copy.save;
++  save.setAttribute('aria-label', options.copy.save);
++  row.append(settings, input, save);
++  const targetLabel = doc.createElement('span');
++  targetLabel.className = 'target';
++  const controls = doc.createElement('div');
++  controls.className = 'controls';
++  function control(label: string, glyph: string) {
++    const button = doc.createElement('button');
++    button.type = 'button';
++    button.title = label;
++    button.setAttribute('aria-label', label);
++    button.textContent = glyph + '  ' + label;
++    controls.append(button);
++    return button;
++  }
++  const parent = control(options.copy.parent, '↑');
++  const child = control(options.copy.child, '↓');
++  const cancel = control(options.copy.cancel, '×');
++  const error = doc.createElement('div');
++  error.className = 'error hidden';
++  error.setAttribute('role', 'alert');
++  intentRow.append(intentLabel, intent);
++  const targetRow = doc.createElement('div');
++  targetRow.className = 'target-row';
++  controls.className = 'target-controls';
++  cancel.remove();
++  parent.textContent = '↑';
++  child.textContent = '↓';
++  targetRow.append(targetLabel, controls);
++  const properties = doc.createElement('div');
++  properties.className = 'properties';
++  const styleHint = doc.createElement('p');
++  styleHint.className = 'style-hint';
++  const fields = new Map<
++    string,
++    { input: HTMLInputElement; before: string; swatch?: HTMLElement }
++  >();
++  for (const [property, label] of [
++    ['color', options.copy.color],
++    ['background-color', options.copy.background],
++    ['opacity', options.copy.opacity],
++    ['font-family', options.copy.font],
++    ['font-size', options.copy.fontSize],
++    ['font-weight', options.copy.fontWeight],
++    ['gap', options.copy.spacing],
++  ]) {
++    const item = doc.createElement('label');
++    item.className = 'property';
++    const labelText = doc.createElement('span');
++    labelText.textContent = label!;
++    const field = doc.createElement('div');
++    field.className = 'field';
++    const value = doc.createElement('input');
++    value.setAttribute('aria-label', label!);
++    value.dataset.property = property;
++    value.maxLength = 1000;
++    let swatch: HTMLElement | undefined;
++    if (property === 'color' || property === 'background-color') {
++      swatch = doc.createElement('span');
++      swatch.className = 'swatch';
++      swatch.setAttribute('aria-hidden', 'true');
++      field.append(swatch);
++    }
++    field.append(value);
++    item.append(labelText, field);
++    properties.append(item);
++    fields.set(property!, { input: value, before: '', ...(swatch ? { swatch } : {}) });
++  }
++  properties.append(styleHint);
++  const footer = doc.createElement('div');
++  footer.className = 'footer hidden';
++  cancel.className = 'cancel';
++  cancel.textContent = options.copy.cancel;
++  const expandedSave = save.cloneNode(true) as HTMLButtonElement;
++  footer.append(cancel, expandedSave);
++  optionsPanel.append(targetRow, properties, intentRow);
++  editor.append(row, optionsPanel, error, footer);
++  shadow.append(style, outline, hint, editor);
++  const surface = doc.createElement('div');
++  surface.style.cssText =
++    'position:fixed;inset:0;pointer-events:auto;cursor:crosshair;touch-action:none';
++  shadow.prepend(surface);
++  doc.documentElement.append(root);
++
++  let target: Element | null = null;
++  let hovered: Element | null = null;
++  let selection: {
++    kind: 'element' | 'region' | 'point';
++    rect: { x: number; y: number; width: number; height: number };
++  } | null = null;
++  let gesture: {
++    id: number;
++    x: number;
++    y: number;
++    clientX: number;
++    clientY: number;
++    dragging: boolean;
++  } | null = null;
++  let suspended = false;
++  let suppressClick = false;
++  const descendants: Element[] = [];
++  let animation = 0;
++  let ended = false;
++  let settle!: (value: BrowserAnnotation | { cancelled: true }) => void;
++  const result = new Promise<BrowserAnnotation | { cancelled: true }>((resolve) => {
++    settle = resolve;
++  });
++  const lifecycle = new AbortController();
++  function changes(): Record<string, { before: string; after: string }> {
++    if (selection?.kind !== 'element') return {};
++    return Object.fromEntries(
++      [...fields].flatMap(([key, field]) => {
++        let after = field.input.value.trim();
++        if ((key === 'font-size' || key === 'gap') && /^\d+(\.\d+)?$/.test(after)) after += 'px';
++        return after === field.before ? [] : [[key, { before: field.before, after }]];
++      }),
++    );
++  }
++  function refreshProperties(element: Element | null) {
++    const computed = element ? getComputedStyle(element) : null;
++    for (const [key, field] of fields) {
++      field.before = computed?.getPropertyValue(key) || '';
++      field.input.value = field.before;
++      field.input.disabled = !element;
++      if (field.swatch) field.swatch.style.background = field.before;
++    }
++    properties.classList.toggle('area', !element);
++    for (const field of fields.values())
++      field.input.closest('.property')?.classList.toggle('hidden', !element);
++    styleHint.textContent = element ? options.copy.styleHint : options.copy.elementOnly;
++  }
++  for (const [key, field] of fields) {
++    field.input.addEventListener(
++      'input',
++      () => {
++        if (field.swatch && CSS.supports(key, field.input.value))
++          field.swatch.style.background = field.input.value;
++        intent.value = 'comment';
++        error.classList.add('hidden');
++        draw();
++      },
++      { signal: lifecycle.signal },
++    );
++    field.input.addEventListener(
++      'keydown',
++      (event) => {
++        if (event.key === 'Enter' && !event.isComposing && event.keyCode !== 229) {
++          event.preventDefault();
++          event.stopPropagation();
++          submit(event);
++        }
++      },
++      { signal: lifecycle.signal },
++    );
++  }
++  const observer = new ResizeObserver(draw);
++
++  function finish(value: BrowserAnnotation | { cancelled: true }) {
++    if (ended) return;
++    ended = true;
++    lifecycle.abort();
++    cancelAnimationFrame(animation);
++    observer.disconnect();
++    root.remove();
++    if (window.__DSH_PAGE_ANNOTATION_CANCEL__ === dismiss)
++      delete window.__DSH_PAGE_ANNOTATION_CANCEL__;
++    if (originalFocus instanceof HTMLElement && originalFocus.isConnected)
++      originalFocus.focus({ preventScroll: true });
++    settle(value);
++  }
++  function dismiss() {
++    finish({ cancelled: true });
++  }
++  window.__DSH_PAGE_ANNOTATION_CANCEL__ = dismiss;
++  function showError(message: string) {
++    error.textContent = message;
++    error.classList.remove('hidden');
++  }
++  function valid(element: Element | null): element is Element {
++    return (
++      !!element &&
++      element !== doc.body &&
++      element !== doc.documentElement &&
++      !element.closest('[data-dsh-page-annotation]')
++    );
++  }
++  function hit(x: number, y: number): Element | null {
++    surface.style.pointerEvents = 'none';
++    editor.style.pointerEvents = 'none';
++    let node = doc.elementFromPoint(x, y);
++    while (node?.shadowRoot) {
++      const inner = node.shadowRoot.elementFromPoint(x, y);
++      if (!inner || inner === node) break;
++      node = inner;
++    }
++    surface.style.pointerEvents = suspended ? 'none' : 'auto';
++    editor.style.pointerEvents = 'auto';
++    return valid(node) ? node : null;
++  }
++  function rectInDocument(element: Element) {
++    const rect = element.getBoundingClientRect();
++    return { x: rect.x + scrollX, y: rect.y + scrollY, width: rect.width, height: rect.height };
++  }
++  function gestureRect(x: number, y: number) {
++    return {
++      x: Math.min(gesture!.x, x),
++      y: Math.min(gesture!.y, y),
++      width: Math.max(1, Math.abs(x - gesture!.x)),
++      height: Math.max(1, Math.abs(y - gesture!.y)),
++    };
++  }
++  function selector(element: Element): string {
++    const scope = element.getRootNode() as Document | ShadowRoot;
++    if (element.id) {
++      const id = '#' + CSS.escape(element.id);
++      if (scope.querySelectorAll(id).length === 1) return id;
++    }
++    const pieces: string[] = [];
++    let node: Element | null = element;
++    while (node) {
++      let part = node.localName;
++      const peers = node.parentElement
++        ? Array.from(node.parentElement.children).filter((x) => x.localName === node!.localName)
++        : [];
++      if (peers.length > 1) part += `:nth-of-type(${peers.indexOf(node) + 1})`;
++      pieces.unshift(part);
++      const path = pieces.join(' > ');
++      if (scope.querySelectorAll(path).length === 1 && scope.querySelector(path) === element)
++        return path;
++      node = node.parentElement;
++    }
++    return pieces.join(' > ');
++  }
++  function locator(element: Element) {
++    const shadowHosts: string[] = [];
++    let scope = element.getRootNode();
++    while (scope instanceof ShadowRoot) {
++      shadowHosts.unshift(selector(scope.host));
++      scope = scope.host.getRootNode();
++    }
++    return {
++      selector: selector(element),
++      shadowHosts,
++      matchCount: (element.getRootNode() as Document | ShadowRoot).querySelectorAll(
++        selector(element),
++      ).length,
++    };
++  }
++  function draw() {
++    if (ended) return;
++    if (location.href !== originalUrl) {
++      dismiss();
++      return;
++    }
++    if (suspended) return;
++    const node = target || hovered;
++    if (selection?.kind === 'element' && !target?.isConnected) {
++      outline.classList.add('hidden');
++      showError(options.copy.targetGone);
++      save.disabled = expandedSave.disabled = true;
++      return;
++    }
++    save.disabled = expandedSave.disabled =
++      !selection || (!input.value.trim() && !Object.keys(changes()).length);
++    const documentRect =
++      selection?.kind === 'element' && target
++        ? rectInDocument(target)
++        : selection?.rect || (node?.isConnected ? rectInDocument(node) : null);
++    if (!documentRect) {
++      outline.classList.add('hidden');
++      return;
++    }
++    const rect = {
++      left: documentRect.x - scrollX,
++      top: documentRect.y - scrollY,
++      width: documentRect.width,
++      height: documentRect.height,
++      bottom: documentRect.y - scrollY + documentRect.height,
++    };
++    outline.classList.remove('hidden');
++    Object.assign(outline.style, {
++      left: `${rect.left - (selection?.kind === 'point' ? 5 : 0)}px`,
++      top: `${rect.top - (selection?.kind === 'point' ? 5 : 0)}px`,
++      width: `${selection?.kind === 'point' ? 10 : rect.width}px`,
++      height: `${selection?.kind === 'point' ? 10 : rect.height}px`,
++      borderStyle: selection?.kind === 'region' ? 'dashed' : 'solid',
++    });
++    if (editor.classList.contains('hidden')) return;
++    const width = editor.getBoundingClientRect().width;
++    const height = editor.getBoundingClientRect().height;
++    const left = Math.max(12, Math.min(rect.left, innerWidth - width - 12));
++    const below = rect.bottom + 8;
++    const above = rect.top - height - 8;
++    const top = Math.max(
++      12,
++      Math.min(
++        below + height <= innerHeight - 12 ? below : above >= 12 ? above : rect.top + 8,
++        innerHeight - height - 12,
++      ),
++    );
++    Object.assign(editor.style, { left: `${left}px`, top: `${top}px` });
++  }
++  function setOptions(open: boolean, restoreFocus = false) {
++    optionsPanel.classList.toggle('hidden', !open);
++    editor.classList.toggle('expanded', open);
++    footer.classList.toggle('hidden', !open);
++    settings.setAttribute('aria-expanded', String(open));
++    draw();
++    if (open) settings.focus({ preventScroll: true });
++    else if (restoreFocus) settings.focus({ preventScroll: true });
++  }
++  settings.addEventListener(
++    'click',
++    () => {
++      setOptions(optionsPanel.classList.contains('hidden'));
++    },
++    { signal: lifecycle.signal },
++  );
++  intent.addEventListener(
++    'change',
++    () => {
++      setOptions(false);
++      input.focus({ preventScroll: true });
++    },
++    { signal: lifecycle.signal },
++  );
++  input.addEventListener(
++    'input',
++    () => {
++      input.style.height = '22px';
++      input.style.height = `${Math.min(110, input.scrollHeight)}px`;
++      error.classList.add('hidden');
++      draw();
++    },
++    { signal: lifecycle.signal },
++  );
++  function track() {
++    draw();
++    if (!ended) animation = requestAnimationFrame(track);
++  }
++  function choose(element: Element) {
++    if (!valid(element)) return;
++    observer.disconnect();
++    target = element;
++    selection = { kind: 'element', rect: rectInDocument(element) };
++    observer.observe(element);
++    hint.classList.add('hidden');
++    editor.classList.remove('hidden');
++    error.classList.add('hidden');
++    const where = locator(element);
++    targetLabel.textContent = `<${element.localName}>`;
++    targetLabel.title = [...where.shadowHosts, where.selector].join(' › ');
++    refreshProperties(element);
++    parent.disabled =
++      !valid(element.parentElement) && !(element.getRootNode() instanceof ShadowRoot);
++    child.disabled = descendants.length === 0;
++    draw();
++    if (!animation) animation = requestAnimationFrame(track);
++    input.focus({ preventScroll: true });
++  }
++  function chooseArea(
++    kind: 'region' | 'point',
++    rect: { x: number; y: number; width: number; height: number },
++  ) {
++    observer.disconnect();
++    target = null;
++    selection = { kind, rect };
++    hint.classList.add('hidden');
++    editor.classList.remove('hidden');
++    error.classList.add('hidden');
++    targetLabel.textContent =
++      kind === 'region'
++        ? `${options.copy.region} · ${Math.round(rect.width)} × ${Math.round(rect.height)}`
++        : options.copy.point;
++    parent.disabled = child.disabled = true;
++    targetLabel.title = '';
++    refreshProperties(null);
++    draw();
++    if (!animation) animation = requestAnimationFrame(track);
++    input.focus({ preventScroll: true });
++  }
++  function isOverlay(event: Event) {
++    return event.composedPath().includes(root);
++  }
++  window.addEventListener(
++    'pointermove',
++    (event) => {
++      if (suspended || !editor.classList.contains('hidden')) return;
++      if (gesture && gesture.id === event.pointerId) {
++        gesture.dragging ||=
++          Math.hypot(event.clientX - gesture.clientX, event.clientY - gesture.clientY) >= 5;
++        if (gesture.dragging) {
++          selection = {
++            kind: 'region',
++            rect: gestureRect(event.clientX + scrollX, event.clientY + scrollY),
++          };
++          draw();
++          return;
++        }
++      }
++      const node = hit(event.clientX, event.clientY);
++      hovered = event.shiftKey && valid(node?.parentElement || null) ? node!.parentElement : node;
++      draw();
++    },
++    { capture: true, signal: lifecycle.signal },
++  );
++  window.addEventListener(
++    'pointerdown',
++    (event) => {
++      if (suspended) {
++        suppressClick = false;
++        return;
++      }
++      if (isOverlay(event) && !event.composedPath().includes(surface)) return;
++      setOptions(false);
++      event.preventDefault();
++      event.stopImmediatePropagation();
++      suppressClick = true;
++      if (event.button !== 0 || !editor.classList.contains('hidden')) return;
++      gesture = {
++        id: event.pointerId,
++        x: event.clientX + scrollX,
++        y: event.clientY + scrollY,
++        clientX: event.clientX,
++        clientY: event.clientY,
++        dragging: false,
++      };
++      surface.setPointerCapture(event.pointerId);
++    },
++    { capture: true, signal: lifecycle.signal },
++  );
++  window.addEventListener(
++    'pointerup',
++    (event) => {
++      if (!gesture || gesture.id !== event.pointerId || suspended) return;
++      event.preventDefault();
++      event.stopImmediatePropagation();
++      const current = gesture;
++      const area = gestureRect(event.clientX + scrollX, event.clientY + scrollY);
++      gesture = null;
++      if (surface.hasPointerCapture(event.pointerId))
++        surface.releasePointerCapture(event.pointerId);
++      if (
++        current.dragging ||
++        Math.hypot(event.clientX - current.clientX, event.clientY - current.clientY) >= 5
++      )
++        chooseArea('region', area);
++      else {
++        const node = hit(event.clientX, event.clientY);
++        descendants.length = 0;
++        if (node) choose(event.shiftKey && valid(node.parentElement) ? node.parentElement : node);
++        else
++          chooseArea('point', {
++            x: event.clientX + scrollX,
++            y: event.clientY + scrollY,
++            width: 0,
++            height: 0,
++          });
++      }
++    },
++    { capture: true, signal: lifecycle.signal },
++  );
++  function abortGesture() {
++    if (!gesture) return;
++    if (surface.hasPointerCapture(gesture.id)) surface.releasePointerCapture(gesture.id);
++    gesture = null;
++    if (editor.classList.contains('hidden')) selection = null;
++    draw();
++  }
++  window.addEventListener('pointercancel', abortGesture, {
++    capture: true,
++    signal: lifecycle.signal,
++  });
++  window.addEventListener(
++    'click',
++    (event) => {
++      if (isOverlay(event) && !event.composedPath().includes(surface)) return;
++      if (suspended && !suppressClick) return;
++      event.preventDefault();
++      event.stopImmediatePropagation();
++      suppressClick = false;
++    },
++    { capture: true, signal: lifecycle.signal },
++  );
++  function resume() {
++    if (!suspended) return;
++    suspended = false;
++    surface.style.pointerEvents = 'auto';
++    hint.textContent = options.copy.select;
++    if (selection) {
++      editor.classList.remove('hidden');
++      hint.classList.add('hidden');
++    } else hint.classList.remove('hidden');
++    draw();
++  }
++  window.addEventListener(
++    'keydown',
++    (event) => {
++      if (event.isComposing || event.keyCode === 229) return;
++      if (event.key === 'Escape') {
++        event.preventDefault();
++        event.stopImmediatePropagation();
++        if (optionsPanel.classList.contains('hidden')) dismiss();
++        else setOptions(false, true);
++        return;
++      }
++      // The comment editor owns spaces. The page receives normal keys while suspended.
++      if (isOverlay(event) && !event.composedPath().includes(surface)) return;
++      if (event.code === 'Space' && !event.altKey && !event.ctrlKey && !event.metaKey) {
++        event.preventDefault();
++        event.stopImmediatePropagation();
++        abortGesture();
++        suspended = true;
++        setOptions(false);
++        surface.style.pointerEvents = 'none';
++        outline.classList.add('hidden');
++        editor.classList.add('hidden');
++        hint.classList.remove('hidden');
++        hint.textContent = options.copy.interact;
++      } else if (!suspended && !isOverlay(event)) {
++        event.preventDefault();
++        event.stopImmediatePropagation();
++      }
++    },
++    { capture: true, signal: lifecycle.signal },
++  );
++  window.addEventListener(
++    'keyup',
++    (event) => {
++      if (event.code === 'Space' && suspended) {
++        event.preventDefault();
++        event.stopImmediatePropagation();
++        resume();
++      }
++    },
++    { capture: true, signal: lifecycle.signal },
++  );
++  window.addEventListener(
++    'blur',
++    () => {
++      abortGesture();
++      resume();
++    },
++    { signal: lifecycle.signal },
++  );
++  doc.addEventListener(
++    'visibilitychange',
++    () => {
++      if (doc.hidden) {
++        abortGesture();
++        resume();
++      }
++    },
++    { signal: lifecycle.signal },
++  );
++  window.addEventListener('pagehide', dismiss, { once: true, signal: lifecycle.signal });
++  parent.addEventListener(
++    'click',
++    () => {
++      if (!target) return;
++      const scope = target.getRootNode();
++      const node = target.parentElement || (scope instanceof ShadowRoot ? scope.host : null);
++      if (valid(node)) {
++        setOptions(false);
++        descendants.push(target);
++        choose(node);
++      }
++    },
++    { signal: lifecycle.signal },
++  );
++  child.addEventListener(
++    'click',
++    () => {
++      const node = descendants.pop();
++      if (node?.isConnected) {
++        setOptions(false);
++        choose(node);
++      }
++    },
++    { signal: lifecycle.signal },
++  );
++  cancel.addEventListener('click', dismiss, { signal: lifecycle.signal });
++  function evidence(element: Element): BrowserAnnotationElement {
++    const where = locator(element);
++    const computed = getComputedStyle(element);
++    const styles: Record<string, string> = {};
++    for (const name of [
++      'display',
++      'position',
++      'font-size',
++      'font-family',
++      'color',
++      'background-color',
++      'padding',
++      'margin',
++      'gap',
++      'opacity',
++      'font-weight',
++    ])
++      styles[name] = computed.getPropertyValue(name).slice(0, 1000);
++    const source = element
++      .closest('[data-web-annotator-source]')
++      ?.getAttribute('data-web-annotator-source')
++      ?.slice(0, 1000);
++    return {
++      ...where,
++      tag: element.localName,
++      text: (element instanceof HTMLElement ? element.innerText : element.textContent || '')
++        .replace(/\s+/g, ' ')
++        .trim()
++        .slice(0, 400),
++      rect: rectInDocument(element),
++      styles,
++      ...(source ? { source } : {}),
++    };
++  }
++  function candidates(rect: { x: number; y: number; width: number; height: number }) {
++    const found = new Set<Element>();
++    // Bounded samples also reach open Shadow DOM and avoid scanning the whole page.
++    for (let row = 0; row < 5; row++)
++      for (let col = 0; col < 5; col++) {
++        const node = hit(
++          rect.x - scrollX + (rect.width * (col + 0.5)) / 5,
++          rect.y - scrollY + (rect.height * (row + 0.5)) / 5,
++        );
++        if (node) found.add(node);
++      }
++    return [...found].slice(0, 12).map(evidence);
++  }
++  function submit(event: Event) {
++    event.preventDefault();
++    if (
++      !selection ||
++      (selection.kind === 'element' && !target?.isConnected) ||
++      location.href !== originalUrl
++    ) {
++      showError(options.copy.targetGone);
++      return;
++    }
++    const styleChanges = changes();
++    for (const [property, { after }] of Object.entries(styleChanges)) {
++      if (
++        !CSS.supports(property, after) ||
++        (property === 'opacity' && !(Number(after) >= 0 && Number(after) <= 1))
++      ) {
++        showError(options.copy.invalidStyle);
++        setOptions(true);
++        fields.get(property)?.input.focus();
++        return;
++      }
++    }
++    if (!input.value.trim() && !Object.keys(styleChanges).length) {
++      showError(options.copy.empty);
++      input.focus();
++      return;
++    }
++    const rect = selection.kind === 'element' ? rectInDocument(target!) : selection.rect;
++    const items = selection.kind === 'element' ? [evidence(target!)] : candidates(rect);
++    finish({
++      intent: intent.value === 'question' ? 'question' : 'comment',
++      note: input.value.trim() || options.copy.applyStyles,
++      ...(Object.keys(styleChanges).length ? { styleChanges } : {}),
++      url: originalUrl,
++      title: doc.title.slice(0, 300),
++      viewport: { width: innerWidth, height: innerHeight },
++      selection: {
++        kind: selection.kind,
++        rect,
++        viewportRect: { ...rect, x: rect.x - scrollX, y: rect.y - scrollY },
++        scroll: { x: scrollX, y: scrollY },
++        candidates: items,
++      },
++    });
++  }
++  editor.addEventListener('submit', submit, { signal: lifecycle.signal });
++  input.addEventListener(
++    'keydown',
++    (event) => {
++      if (event.key === 'Enter' && !event.shiftKey && !event.isComposing && event.keyCode !== 229) {
++        event.preventDefault();
++        event.stopPropagation();
++        submit(event);
++      }
++    },
++    { signal: lifecycle.signal },
++  );
++  animation = requestAnimationFrame(track);
++  return result;
++}
+diff --git a/packages/client/ui-sidebar-browser/src/client/annotation/protocol.ts b/packages/client/ui-sidebar-browser/src/client/annotation/protocol.ts
+new file mode 100644
+index 0000000..2861153
+--- /dev/null
++++ b/packages/client/ui-sidebar-browser/src/client/annotation/protocol.ts
+@@ -0,0 +1,169 @@
++/** Validation for page and guest process results, not same-process slot props. */
++import type { BrowserAnnotation, BrowserAnnotationOptions } from './page-inspector.ts';
++
++/** Result of one annotation operation. */
++export type AnnotationResult = BrowserAnnotation | { cancelled: true };
++
++function object(value: unknown): value is Record<string, unknown> {
++  return !!value && typeof value === 'object' && !Array.isArray(value);
++}
++function string(value: unknown, limit: number): value is string {
++  return typeof value === 'string' && value.length <= limit;
++}
++function number(value: unknown): value is number {
++  return typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= 1e7;
++}
++function rect(value: unknown): boolean {
++  return (
++    object(value) &&
++    number(value.x) &&
++    number(value.y) &&
++    number(value.width) &&
++    number(value.height) &&
++    value.width >= 0 &&
++    value.height >= 0
++  );
++}
++/** Validate bounded JSON evidence received from a visited document.
++ * @param value - process or MessagePort result.
++ * @returns whether the result can be retained and rendered.
++ */
++export function isAnnotationResult(value: unknown): value is AnnotationResult {
++  if (!object(value)) return false;
++  if (value.cancelled === true) return Object.keys(value).length === 1;
++  if (
++    (value.intent !== 'comment' && value.intent !== 'question') ||
++    !string(value.note, 1000) ||
++    !value.note.trim() ||
++    !string(value.url, 8192) ||
++    !string(value.title, 300)
++  )
++    return false;
++  if (
++    value.styleChanges !== undefined &&
++    (!object(value.styleChanges) ||
++      Object.keys(value.styleChanges).length > 10 ||
++      !Object.entries(value.styleChanges).every(
++        ([key, change]) =>
++          [
++            'color',
++            'background-color',
++            'opacity',
++            'font-family',
++            'font-size',
++            'font-weight',
++            'padding',
++            'margin',
++            'gap',
++          ].includes(key) &&
++          object(change) &&
++          string(change.before, 1000) &&
++          string(change.after, 1000),
++      ))
++  )
++    return false;
++  if (
++    value.screenshot !== undefined &&
++    (!object(value.screenshot) ||
++      value.screenshot.mediaType !== 'image/jpeg' ||
++      !string(value.screenshot.data, 4000000) ||
++      !/^[A-Za-z0-9+/]+={0,2}$/.test(value.screenshot.data) ||
++      !number(value.screenshot.width) ||
++      !number(value.screenshot.height) ||
++      value.screenshot.width <= 0 ||
++      value.screenshot.width > 1600 ||
++      value.screenshot.height <= 0 ||
++      value.screenshot.height > 1600)
++  )
++    return false;
++  try {
++    if (!['http:', 'https:'].includes(new URL(value.url).protocol)) return false;
++  } catch {
++    return false;
++  }
++  if (
++    !object(value.viewport) ||
++    !number(value.viewport.width) ||
++    !number(value.viewport.height) ||
++    value.viewport.width <= 0 ||
++    value.viewport.height <= 0
++  )
++    return false;
++  const selection = value.selection;
++  if (
++    !object(selection) ||
++    !['element', 'region', 'point'].includes(String(selection.kind)) ||
++    !rect(selection.rect) ||
++    !rect(selection.viewportRect) ||
++    !object(selection.scroll) ||
++    !number(selection.scroll.x) ||
++    !number(selection.scroll.y) ||
++    !Array.isArray(selection.candidates) ||
++    selection.candidates.length > 12
++  )
++    return false;
++  if (selection.kind === 'element' && selection.candidates.length !== 1) return false;
++  for (const item of selection.candidates) {
++    if (
++      !object(item) ||
++      !string(item.selector, 8192) ||
++      !Array.isArray(item.shadowHosts) ||
++      item.shadowHosts.length > 32 ||
++      !item.shadowHosts.every((x) => string(x, 8192)) ||
++      item.matchCount !== 1 ||
++      !string(item.tag, 200) ||
++      !string(item.text, 400) ||
++      !rect(item.rect) ||
++      !object(item.styles) ||
++      Object.keys(item.styles).length > 16 ||
++      !Object.entries(item.styles).every(([key, val]) => string(key, 100) && string(val, 1000)) ||
++      (item.source !== undefined && !string(item.source, 1000))
++    )
++      return false;
++  }
++  try {
++    return JSON.stringify({ ...value, screenshot: undefined }).length <= 64000;
++  } catch {
++    return false;
++  }
++}
++
++/** Validate picker configuration crossing the iframe bridge.
++ * @param value - parent message options.
++ * @returns whether all localized fields are bounded strings.
++ */
++export function isAnnotationOptions(value: unknown): value is BrowserAnnotationOptions {
++  return (
++    object(value) &&
++    (value.intent === 'comment' || value.intent === 'question') &&
++    typeof value.dark === 'boolean' &&
++    object(value.copy) &&
++    [
++      'select',
++      'comment',
++      'question',
++      'placeholder',
++      'settings',
++      'save',
++      'cancel',
++      'parent',
++      'child',
++      'targetGone',
++      'empty',
++      'region',
++      'point',
++      'interact',
++      'color',
++      'background',
++      'opacity',
++      'font',
++      'fontSize',
++      'fontWeight',
++      'spacing',
++      'elementOnly',
++      'invalidStyle',
++      'applyStyles',
++      'styleHint',
++    ].every((key) => string(value.copy && object(value.copy) ? value.copy[key] : null, 500))
++  );
++}
+diff --git a/packages/client/ui-sidebar-browser/src/client/annotation/screenshot.ts b/packages/client/ui-sidebar-browser/src/client/annotation/screenshot.ts
+new file mode 100644
+index 0000000..f8bf8b6
+--- /dev/null
++++ b/packages/client/ui-sidebar-browser/src/client/annotation/screenshot.ts
+@@ -0,0 +1,49 @@
++/** Render a provider-captured viewport with its exact saved selection. */
++import type { BrowserAnnotation, BrowserAnnotationImage } from './page-inspector.ts';
++
++/** Mark the saved rectangle on actual captured pixels and normalize to a bounded JPEG.
++ * @param dataUrl - Browser capture of the inspected viewport, after picker cleanup.
++ * @param annotation - saved viewport coordinates.
++ * @returns image bytes ready for the official Session image attachment path.
++ */
++export async function markScreenshot(
++  dataUrl: string,
++  annotation: BrowserAnnotation,
++): Promise<BrowserAnnotationImage> {
++  const picture = new Image();
++  picture.src = dataUrl;
++  await picture.decode();
++  if (!picture.naturalWidth || !picture.naturalHeight) throw new Error('annotation-image-failed');
++  const scale = Math.min(1, 1600 / Math.max(picture.naturalWidth, picture.naturalHeight));
++  const canvas = document.createElement('canvas');
++  canvas.width = Math.round(picture.naturalWidth * scale);
++  canvas.height = Math.round(picture.naturalHeight * scale);
++  const context = canvas.getContext('2d');
++  if (!context) throw new Error('annotation-image-failed');
++  context.drawImage(picture, 0, 0, canvas.width, canvas.height);
++  const sx = canvas.width / annotation.viewport.width;
++  const sy = canvas.height / annotation.viewport.height;
++  const area = annotation.selection.viewportRect;
++  context.strokeStyle = '#1683ff';
++  context.fillStyle = '#1683ff';
++  context.lineWidth = 2;
++  const x = area.x * sx,
++    y = area.y * sy;
++  if (annotation.selection.kind === 'point') {
++    if (x < 0 || y < 0 || x > canvas.width || y > canvas.height)
++      throw new Error('annotation-image-failed');
++    context.beginPath();
++    context.arc(x, y, 7, 0, Math.PI * 2);
++    context.stroke();
++  } else {
++    const left = Math.max(1, x),
++      top = Math.max(1, y);
++    const right = Math.min(canvas.width - 1, x + area.width * sx);
++    const bottom = Math.min(canvas.height - 1, y + area.height * sy);
++    if (right <= left || bottom <= top) throw new Error('annotation-image-failed');
++    context.strokeRect(left, top, right - left, bottom - top);
++  }
++  const data = canvas.toDataURL('image/jpeg', 0.8).split(',')[1]!;
++  if (data.length > 4000000) throw new Error('annotation-image-failed');
++  return { mediaType: 'image/jpeg', data, width: canvas.width, height: canvas.height };
++}
+diff --git a/packages/client/ui-sidebar-browser/src/client/annotation/slots.ts b/packages/client/ui-sidebar-browser/src/client/annotation/slots.ts
+new file mode 100644
+index 0000000..18856f0
+--- /dev/null
++++ b/packages/client/ui-sidebar-browser/src/client/annotation/slots.ts
+@@ -0,0 +1,24 @@
++/** Browser-owned extension positions expose data and bounded picker callbacks. */
++import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
++import type { BrowserAnnotationOptions } from './page-inspector.ts'
++import type { AnnotationResult } from './protocol.ts'
++
++/** Owner data for toolbar additions and the annotation queue. */
++export interface BrowserAnnotationOwner {
++  readonly tabId: TabId
++  readonly url: string | undefined
++  readonly loading: boolean
++  /** @param options - localized picker configuration. @returns saved evidence or cancellation. */
++  readonly annotate: (options: BrowserAnnotationOptions) => Promise<AnnotationResult>
++  /** Cancel only the active picker for this tab. */
++  readonly cancelAnnotation: () => void
++}
++
++declare module '@deepseek-ai/dsh-client-ui-slots' {
++  interface SlotMap {
++    /** Additional Browser toolbar controls; consumers never receive a DOM handle. */
++    'sidebar.right.tab.browser.toolbar': { kind: 'list'; scope: 'session'; owner: BrowserAnnotationOwner }
++    /** Retained annotation review below the existing Browser viewport. */
++    'sidebar.right.tab.browser.annotations': { kind: 'list'; scope: 'session'; owner: BrowserAnnotationOwner }
++  }
++}
+diff --git a/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts b/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts
+index 45d17bb..1dcf3fa 100644
+--- a/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts
++++ b/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts
+@@ -7,6 +7,8 @@ import type { BrowserPage, BrowserPageFactory } from './BrowserPage.ts'
+ import { currentBrowserTarget, type BrowserTabState } from './BrowserPersistence.ts'
+ import type { BrowserStore } from './store.ts'
+ import { parseBrowserAddress, type BrowserAddressFailure, type BrowserTarget } from './url.ts'
++import type { BrowserAnnotationOptions } from '../annotation/page-inspector.ts'
++import type { AnnotationResult } from '../annotation/protocol.ts'
+ 
+ /** Live tab state; navigation comes from its provider and draft validation stays local. */
+ export interface BrowserControllerState {
+@@ -38,6 +40,7 @@ export class BrowserController implements HostObservable<BrowserControllerState>
+   private started = false
+   private disposed = false
+   private disposal: Promise<void> | undefined
++  private annotation: AbortController | undefined
+   private readonly abort = (): void => { void this.dispose() }
+ 
+   /** @param options - identity, persistence, page factory and source-tab navigation. */
+@@ -84,9 +87,28 @@ export class BrowserController implements HostObservable<BrowserControllerState>
+    */
+   mount(viewportId: string): () => void {
+     this.publishSaved()
+-    return this.page.presentation.mount(viewportId)
++    const unmount = this.page.presentation.mount(viewportId)
++    return () => { this.cancelAnnotation(); unmount() }
+   }
+ 
++  /** @param options - localized picker configuration. @returns saved evidence or cancellation. */
++  async annotate(options: BrowserAnnotationOptions): Promise<AnnotationResult> {
++    this.cancelAnnotation()
++    const frame = this.page.frame.getSnapshot()
++    if (this.disposed || frame.loading || frame.address === 'unknown' || frame.target === undefined || this.page.presentation.annotate === undefined) throw new Error('annotation-unavailable')
++    const lifetime = new AbortController()
++    this.annotation = lifetime
++    try {
++      const result = await this.page.presentation.annotate(frame.target.url, options, lifetime.signal)
++      return lifetime.signal.aborted ? { cancelled: true } : result
++    } finally {
++      if (this.annotation === lifetime) this.annotation = undefined
++    }
++  }
++
++  /** Cancel the current tab's picker. */
++  cancelAnnotation(): void { this.annotation?.abort(); this.annotation = undefined }
++
+   /**
+    * Consume initial navigation once; a saved checkpoint alone never starts a page.
+    * @param initialUrl - explicit typed-open address, or absence.
+@@ -146,6 +168,7 @@ export class BrowserController implements HostObservable<BrowserControllerState>
+   dispose(): Promise<void> {
+     if (this.disposal !== undefined) return this.disposal
+     this.disposed = true
++    this.cancelAnnotation()
+     this.options.signal.removeEventListener('abort', this.abort)
+     this.unsubscribe()
+     this.disposal = this.page.frame.dispose()
+@@ -162,6 +185,7 @@ export class BrowserController implements HostObservable<BrowserControllerState>
+ 
+   private command(run: () => void): void {
+     if (this.disposed) return
++    this.cancelAnnotation()
+     const current = this.store.getSnapshot()
+     this.store.set({ ...current, addressFailure: undefined, addressRevision: current.addressRevision + 1 })
+     run()
+@@ -181,6 +205,10 @@ export interface BrowserMountRequest {
+ 
+ /** Plain Slot callbacks and a framework-bound state source, not a desktop protocol. */
+ export interface BrowserInjected {
++  /** @param tabId - tab occurrence. @param options - picker configuration. @returns saved evidence or cancellation. */
++  annotate(tabId: TabId, options: BrowserAnnotationOptions): Promise<AnnotationResult>
++  /** @param tabId - tab whose picker is active. */
++  cancelAnnotation(tabId: TabId): void
+   readonly keyedHooks: {
+     readonly browserState: (key: string) => HostObservable<BrowserControllerState> | undefined
+   }
+@@ -221,6 +249,8 @@ export function createBrowserControllers(actions: BoundActions<BrowserStore>, cr
+   }>()
+   const controller = (id: TabId): BrowserController | undefined => controllers.get(id)?.controller
+   return {
++    annotate: (id, options) => controller(id)?.annotate(options) ?? Promise.reject(new Error('annotation-unavailable')),
++    cancelAnnotation: id => { controller(id)?.cancelAnnotation() },
+     keyedHooks: { browserState: key => controller(key as TabId) },
+     mount(request) {
+       const { tabId, signal } = request
+diff --git a/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebviewPresentation.ts b/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebviewPresentation.ts
+index 5d3ff43..de1a20b 100644
+--- a/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebviewPresentation.ts
++++ b/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebviewPresentation.ts
+@@ -2,9 +2,14 @@
+ import type { DesktopBrowserReservation } from '../../types.ts'
+ import type { BrowserPresentation } from '../view/BrowserPresentation.ts'
+ import css from '../view/Browser.module.css'
++import { annotatePage, type BrowserAnnotationOptions } from '../annotation/page-inspector.ts'
++import { isAnnotationResult, type AnnotationResult } from '../annotation/protocol.ts'
++import { markScreenshot } from '../annotation/screenshot.ts'
+ 
+ /** The Electron tag API used by its navigation provider. */
+ export interface WebviewElement extends HTMLElement {
++  capturePage(): Promise<{ toDataURL(): string }>
++  executeJavaScript(code: string): Promise<unknown>
+   loadURL(url: string): Promise<void>
+   getURL(): string
+   getTitle(): string
+@@ -30,6 +35,49 @@ export class ElectronWebviewPresentation implements BrowserPresentation {
+ 
+   constructor(private readonly events: ElectronPresentationEvents) {}
+ 
++  /** @param url - controller-known page. @param options - picker configuration. @param signal - lifetime. @returns bounded guest evidence. */
++  async annotate(url: string, options: BrowserAnnotationOptions, signal: AbortSignal): Promise<AnnotationResult> {
++    const element = this.element
++    if (signal.aborted) return { cancelled: true }
++    if (element === undefined || element.getURL() !== url) throw new Error('annotation-unavailable')
++    const cancel = (): void => {
++      void element.executeJavaScript('window.__DSH_PAGE_ANNOTATION_CANCEL__?.()').catch(() => {
++        // A destroyed or navigated guest has already removed the picker.
++      })
++    }
++    signal.addEventListener('abort', cancel, { once: true })
++    const navigation = (): void => { cancel() }
++    element.addEventListener('did-start-navigation', navigation)
++    try {
++      element.focus()
++      const result = await element.executeJavaScript(`(${annotatePage.toString()})(${JSON.stringify(options)})`)
++      if (signal.aborted || this.element !== element) return { cancelled: true }
++      if (!isAnnotationResult(result)) throw new Error('annotation-invalid')
++      if (!('cancelled' in result) && (result.url !== url || element.getURL() !== url)) throw new Error('annotation-page-changed')
++      if (!('cancelled' in result)) {
++        try {
++          const image = await element.capturePage()
++          const screenshot = await markScreenshot(image.toDataURL(), result)
++          if (signal.aborted || this.element !== element) return { cancelled: true }
++          if (element.getURL() !== url || element.isLoading()) throw new Error('annotation-page-changed')
++          const view = await element.executeJavaScript('({width:innerWidth,height:innerHeight,x:scrollX,y:scrollY})')
++          if (typeof view !== 'object' || view === null || !('width' in view) || !('height' in view) || !('x' in view) || !('y' in view) ||
++              view.width !== result.viewport.width || view.height !== result.viewport.height || view.x !== result.selection.scroll.x || view.y !== result.selection.scroll.y) return result
++          return { ...result, screenshot }
++        } catch (error) {
++          if (signal.aborted || this.element !== element) return { cancelled: true }
++          if (element.getURL() !== url || element.isLoading()) throw new Error('annotation-page-changed')
++          // A capture failure must retain the saved annotation for detail-only submission.
++          return result
++        }
++      }
++      return result
++    } finally {
++      signal.removeEventListener('abort', cancel)
++      element.removeEventListener('did-start-navigation', navigation)
++    }
++  }
++
+   /** @param viewportId - committed content container. @returns ends attachment and releases its guest. */
+   mount(viewportId: string): () => void {
+     const host = document.getElementById(viewportId)
+diff --git a/packages/client/ui-sidebar-browser/src/client/index.ts b/packages/client/ui-sidebar-browser/src/client/index.ts
+index d44226e..c0f9218 100644
+--- a/packages/client/ui-sidebar-browser/src/client/index.ts
++++ b/packages/client/ui-sidebar-browser/src/client/index.ts
+@@ -18,8 +18,12 @@ import type { BrowserPageFactory } from './browser/BrowserPage.ts'
+ import { BROWSER_ID, browserDefinition } from './definition.tsx'
+ import { en, zh } from './locales.ts'
+ import { createBrowserStore } from './browser/store.ts'
++import type {} from './annotation/slots.ts'
+ 
+ export type { BrowserBodyProps } from './view/BrowserBody.tsx'
++export type { BrowserAnnotationOwner } from './annotation/slots.ts'
++export type { BrowserAnnotation, BrowserAnnotationOptions, BrowserAnnotationElement } from './annotation/page-inspector.ts'
++export type { AnnotationResult } from './annotation/protocol.ts'
+ export type { BrowserControllerState, BrowserInjected, BrowserMountRequest } from './browser/BrowserController.ts'
+ export type { BrowserFrame, BrowserFrameState, BrowserLoadError, BrowserSandboxControl } from './browser/BrowserFrame.ts'
+ export type { BrowserPage, BrowserPageFactory, BrowserPageOptions } from './browser/BrowserPage.ts'
+@@ -81,6 +85,10 @@ export function apply(ctx: Context): void {
+     }, 'ui-sidebar-browser.frames')
+     scope.effect(() => scope.slots.inject('sidebar.right.pane.tab', () => scope.slots.register({
+       name: 'sidebar.right.pane.tab', key: BROWSER_ID, locale: namespace, store,
++      children: {
++        'sidebar.right.tab.browser.toolbar': { kind: 'list', scope: 'session' },
++        'sidebar.right.tab.browser.annotations': { kind: 'list', scope: 'session' },
++      },
+       inject: (sessionId, actions) => {
+         const existing = controllers.get(sessionId)
+         if (existing !== undefined) {
+diff --git a/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx b/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx
+index f819dba..b4fc5f6 100644
+--- a/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx
++++ b/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx
+@@ -1,5 +1,5 @@
+ /** Common browser chrome; a presentation adapter attaches the page inside its content container. */
+-import { useEffect, useId, useLayoutEffect, useRef, useState } from 'react'
++import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from 'react'
+ import type { FormEvent, ReactNode } from 'react'
+ import {
+   Button,
+@@ -11,7 +11,8 @@ import {
+   SHIELD_OUTLINE_PATH,
+   ICON_REGULAR_STROKE,
+ } from '@deepseek-ai/dsh-client-ui-primitives'
+-import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
++import type { InjectFace, PropsLocale, PropsRuntime, PropsStore, PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
++import type { BrowserAnnotationOwner } from '../annotation/slots.ts'
+ import type { BrowserInjected } from '../browser/BrowserController.ts'
+ import { emptyBrowserFrame } from '../browser/BrowserFrame.ts'
+ import { currentBrowserTarget } from '../browser/BrowserPersistence.ts'
+@@ -36,6 +37,7 @@ export type BrowserBodyProps = PropsRuntime<'sidebar.right.pane.tab'>
+   & PropsStore<BrowserStore>
+   & PropsLocale<'sidebarBrowser'>
+   & InjectFace<BrowserInjected>
++  & PropsRenderSlots<'sidebar.right.tab.browser.toolbar' | 'sidebar.right.tab.browser.annotations'>
+ 
+ function useBrowserDraft(url: string | undefined, revision: number): readonly [string, (value: string) => void] {
+   const [edit, setEdit] = useState<{ readonly revision: number; readonly value: string }>()
+@@ -75,12 +77,18 @@ export function BrowserBody(props: BrowserBodyProps): ReactNode {
+   const failure = state?.addressFailure
+   const error = frame.error
+   const submit = (event: FormEvent): void => { event.preventDefault(); loadUrl(tab.id, draft) }
++  const annotationOwner: BrowserAnnotationOwner = useMemo(() => ({
++    tabId: tab.id, url: unknown ? undefined : frame.target?.url, loading: frame.loading || mountEpoch === 0,
++    annotate: options => props.annotate(tab.id, options),
++    cancelAnnotation: () => { props.cancelAnnotation(tab.id) },
++  }), [tab.id, unknown, frame.target?.url, frame.loading, mountEpoch, props.annotate, props.cancelAnnotation])
+ 
+   return (
+     <div className={css.root}>
+       <form className={css.toolbar} onSubmit={submit}>
+         <button type="button" className={css.tool} aria-label={t('back')} title={t('back')} disabled={!frame.canGoBack} onClick={() => { goBack(tab.id) }}><IconChevronLeftOutlineRegular /></button>
+         <button type="button" className={css.tool} aria-label={t('forward')} title={t('forward')} disabled={!frame.canGoForward} onClick={() => { goForward(tab.id) }}><IconChevronRightOutlineRegular /></button>
++        {props.renderSlot('sidebar.right.tab.browser.toolbar', annotationOwner)}
+         <Tooltip label={t('reload')} shortcutKeys={tab.refreshShortcut?.keys} side="bottom" delayMs={500}>
+           <button type="button" className={css.tool} aria-label={t('reload')} aria-keyshortcuts={tab.refreshShortcut?.aria} disabled={target === undefined || mountEpoch === 0} onClick={() => { reload(tab.id) }}><IconRefreshOutlineRegular /></button>
+         </Tooltip>
+@@ -127,6 +135,7 @@ export function BrowserBody(props: BrowserBodyProps): ReactNode {
+           <div className={css.start}>{t(target === undefined ? 'start' : 'loading')}</div>
+         </div>}
+       </div>
++      {props.renderSlot('sidebar.right.tab.browser.annotations', annotationOwner)}
+       {unknown && <p className={css.limit}>{t('address.unknown')}</p>}
+     </div>
+   )
+diff --git a/packages/client/ui-sidebar-browser/src/client/view/BrowserPresentation.ts b/packages/client/ui-sidebar-browser/src/client/view/BrowserPresentation.ts
+index dadf0dc..0b47111 100644
+--- a/packages/client/ui-sidebar-browser/src/client/view/BrowserPresentation.ts
++++ b/packages/client/ui-sidebar-browser/src/client/view/BrowserPresentation.ts
+@@ -1,5 +1,9 @@
+ /** The presentation face is separate from page navigation and terminal disposal. */
++import type { BrowserAnnotationOptions } from '../annotation/page-inspector.ts'
++import type { AnnotationResult } from '../annotation/protocol.ts'
+ export interface BrowserPresentation {
++  /** @param url - observed page. @param options - picker copy. @param signal - operation lifetime. @returns bounded evidence or cancellation. */
++  annotate?(url: string, options: BrowserAnnotationOptions, signal: AbortSignal): Promise<AnnotationResult>
+   /**
+    * Attach the page inside a committed content container.
+    * @param viewportId - content element id; its DOM ancestors must remain connected for page retention.
+diff --git a/packages/client/ui-sidebar-browser/src/client/view/IframePresentation.ts b/packages/client/ui-sidebar-browser/src/client/view/IframePresentation.ts
+index fc064f5..595677d 100644
+--- a/packages/client/ui-sidebar-browser/src/client/view/IframePresentation.ts
++++ b/packages/client/ui-sidebar-browser/src/client/view/IframePresentation.ts
+@@ -2,6 +2,9 @@
+ import type { BrowserTarget } from '../browser/url.ts'
+ import type { BrowserPresentation } from './BrowserPresentation.ts'
+ import css from './Browser.module.css'
++import { annotateIframe } from '../annotation/iframe-annotation.ts'
++import type { BrowserAnnotationOptions } from '../annotation/page-inspector.ts'
++import type { AnnotationResult } from '../annotation/protocol.ts'
+ 
+ /** Fixed iframe policy; top navigation and downloads are not granted directly. */
+ export const WEB_BROWSER_SANDBOX = 'allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox'
+@@ -29,6 +32,12 @@ export class IframePresentation implements BrowserPresentation {
+   /** @param events - provider-owned load and remount callbacks. */
+   constructor(private readonly events: IframePresentationEvents) {}
+ 
++  /** @param url - controller-known URL. @param options - picker copy. @param signal - lifetime. @returns saved annotation or cancellation. */
++  annotate(url: string, options: BrowserAnnotationOptions, signal: AbortSignal): Promise<AnnotationResult> {
++    if (this.element === undefined) return Promise.reject(new Error('annotation-unavailable'))
++    return annotateIframe(this.element, url, options, signal)
++  }
++
+   /** @param viewportId - mounted placeholder. @returns removes only the iframe presentation. */
+   mount(viewportId: string): () => void {
+     const host = document.getElementById(viewportId)