From b4fe6055bb0a001c0104e8df900b612c14190915 Mon Sep 17 00:00:00 2001
From: drown0315 <drown0315@gmail.com>
Date: Thu, 9 Jul 2026 11:40:32 +0800
Subject: [PATCH 1/6] chore: mark agent session command issue complete

---
 issues/0.0.3-selection-chat.md | 35 ++++++++++++++++++----------------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/issues/0.0.3-selection-chat.md b/issues/0.0.3-selection-chat.md
index 825d174..b415ba0 100644
--- a/issues/0.0.3-selection-chat.md
+++ b/issues/0.0.3-selection-chat.md
@@ -363,22 +363,25 @@ The standard CLI command loop should support a combined command shape like `agen
 
 ## Acceptance criteria
 
-- [ ] The standard agent loop is poll, process, reply, poll again.
-- [ ] A command can write an agent reply and continue polling in one flow.
-- [ ] A command can write a system error message.
-- [ ] Command-level errors produce `system` messages, not `agent` messages.
-- [ ] Normal agent explanations of failed work use `agent` messages.
-- [ ] Agent replies are correlated with the user message ID they answer.
-- [ ] Agent error messages can be correlated with the user message where applicable.
-- [ ] Reply write failure prevents continued polling and returns an error.
-- [ ] Error write failure prevents continued polling and returns an error.
-- [ ] Agent reply success followed by poll continuation failure keeps the reply and moves Agent Status to `Waiting for agent`.
-- [ ] Poller output includes the current message payload.
-- [ ] Poller output includes next-step guidance for the agent.
-- [ ] The CLI command is the formal Agent Session Command contract.
-- [ ] HTTP agent endpoints are treated as the underlying transport for the command.
-- [ ] The command terminology is not exposed in the product UI.
-- [ ] Manual review confirms the command shape works naturally in the launching agent session.
+- [x] The standard agent loop is poll, process, reply, poll again.
+- [x] A command can write an agent reply and continue polling in one flow.
+- [x] A command can write a system error message.
+- [x] Command-level errors produce `system` messages, not `agent` messages.
+- [x] Normal agent explanations of failed work use `agent` messages.
+- [x] Agent replies are correlated with the user message ID they answer.
+- [x] Agent error messages can be correlated with the user message where applicable.
+- [x] Reply write failure prevents continued polling and returns an error.
+- [x] Error write failure prevents continued polling and returns an error.
+- [x] Agent reply success followed by poll continuation failure keeps the reply and moves Agent Status to `Waiting for agent`.
+- [x] Poller output includes the current message payload.
+- [x] Poller output includes next-step guidance for the agent.
+- [x] The CLI command is the formal Agent Session Command contract.
+- [x] HTTP agent endpoints are treated as the underlying transport for the command.
+- [x] The command terminology is not exposed in the product UI.
+- [x] Manual review confirms the command shape works naturally in the launching agent session.
+
+Completed via `issues/0.0.3-agent-session-command.md`, which split this
+contract work into six completed Agent Session Command slices.
 
 ## Blocked by
 

From 86a19f6e133d81b7e23e2d1599172197cc3b113e Mon Sep 17 00:00:00 2001
From: drown0315 <drown0315@gmail.com>
Date: Thu, 9 Jul 2026 12:31:54 +0800
Subject: [PATCH 2/6] fix: harden selection chat boundaries

---
 apps/bridge/test/chat/chat_ingress_test.dart  | 36 +++++++++
 apps/web/src/app/AskUiWorkbench.tsx           |  1 +
 apps/web/src/chat/chatComposerState.test.ts   | 64 ++++++++++++++-
 apps/web/src/chat/chatComposerState.ts        | 16 ++++
 apps/web/src/chat/chatSessionState.test.ts    | 77 +++++++++++++++++++
 apps/web/src/components/chat/ChatComposer.tsx |  6 +-
 apps/web/src/components/chat/ChatPanel.tsx    |  3 +
 .../components/chat/SelectedWidgetSection.tsx | 11 ++-
 .../components/chat/chatPanelContent.test.ts  | 17 ++++
 .../chat/useSelectionCommentPanelFlow.ts      |  4 +
 .../live-app-surface/DeviceShell.tsx          | 37 +++++++--
 .../deviceControlProtocol.test.ts             | 25 ++++++
 .../live-app-surface/deviceControlProtocol.ts | 10 +++
 .../selectionCommentValidation.test.ts        | 25 ++++++
 .../selectionCommentValidation.ts             | 26 +++++++
 issues/0.0.3-selection-chat.md                | 46 +++++------
 16 files changed, 369 insertions(+), 35 deletions(-)

diff --git a/apps/bridge/test/chat/chat_ingress_test.dart b/apps/bridge/test/chat/chat_ingress_test.dart
index 7d8c209..b6d8d4e 100644
--- a/apps/bridge/test/chat/chat_ingress_test.dart
+++ b/apps/bridge/test/chat/chat_ingress_test.dart
@@ -206,6 +206,42 @@ void main() {
           (unowned as RejectedChatIngressMessage).error, 'invalid_chat_parts');
       expect(owned, isA<AcceptedChatIngressMessage>());
     });
+
+    test('does not restore snapshot ownership in a restarted Bridge Session',
+        () {
+      const snapshotPath = '/tmp/ask-ui/session-1/snapshots/comment.png';
+      existingSnapshotPaths.add(snapshotPath);
+      session.manageLocalPath('/tmp/ask-ui/session-1');
+      final originalSessionResult = ingress.parseMessage(
+        {
+          'parts': [
+            selectionCommentPart(snapshotPath),
+          ],
+        },
+        session,
+      );
+      final restartedSession = BridgeSession(
+        id: 'session-1',
+        vmServiceUri: session.vmServiceUri,
+        projectRoot: session.projectRoot,
+        deviceId: session.deviceId,
+      );
+
+      final restartedSessionResult = ingress.parseMessage(
+        {
+          'parts': [
+            selectionCommentPart(snapshotPath),
+          ],
+        },
+        restartedSession,
+      );
+
+      expect(originalSessionResult, isA<AcceptedChatIngressMessage>());
+      expect(
+        (restartedSessionResult as RejectedChatIngressMessage).error,
+        'invalid_chat_parts',
+      );
+    });
   });
 }
 
diff --git a/apps/web/src/app/AskUiWorkbench.tsx b/apps/web/src/app/AskUiWorkbench.tsx
index d9c7b45..4b63ec5 100644
--- a/apps/web/src/app/AskUiWorkbench.tsx
+++ b/apps/web/src/app/AskUiWorkbench.tsx
@@ -88,6 +88,7 @@ export function AskUiWorkbench() {
           activeSelectionCommentId={selectionComments.activeSelectionCommentId}
           attachmentTokens={selectionComments.attachmentTokens}
           chatSessionState={chatSession}
+          isReadOnly={isReadOnly}
           isSelectWidgetActive={actions.topBarActionState.isSelectWidgetActive}
           onAttachmentTokenClick={selectionComments.handleAttachmentTokenClick}
           onSelectionCommentStateChange={
diff --git a/apps/web/src/chat/chatComposerState.test.ts b/apps/web/src/chat/chatComposerState.test.ts
index 391161f..b3f6581 100644
--- a/apps/web/src/chat/chatComposerState.test.ts
+++ b/apps/web/src/chat/chatComposerState.test.ts
@@ -4,10 +4,14 @@ import test from 'node:test';
 import {
   CHAT_COMPOSER_TEXT_LIMIT,
   getChatComposerState,
+  getChatComposerTextareaInputPolicy,
   getComposerTextAfterSendResult,
   shouldSubmitChatComposerKey,
 } from './chatComposerState.ts';
-import { getInitialChatSessionState } from './chatSessionState.ts';
+import {
+  getInitialChatSessionState,
+  reduceChatSessionDisconnected,
+} from './chatSessionState.ts';
 
 test('enables Chat send only while the Agent is ready with text or attachments', () => {
   const state = getInitialChatSessionState({
@@ -59,6 +63,58 @@ test('disables Chat send when Agent Status is not ready', () => {
   });
 });
 
+test('disables Chat send after session events disconnect', () => {
+  const state = reduceChatSessionDisconnected(
+    getInitialChatSessionState({
+      status: 'ok',
+      agentStatus: 'agent_ready',
+      readOnly: false,
+      messages: [],
+    }),
+  );
+
+  assert.deepEqual(getChatComposerState(state, 'Make it primary.'), {
+    canSend: false,
+    disabledReason: 'Agent Status is Waiting for agent.',
+    isTooLong: false,
+  });
+});
+
+test('enables prepared composer text after Agent ready recovery without clearing it', () => {
+  const disconnected = reduceChatSessionDisconnected(
+    getInitialChatSessionState({
+      status: 'ok',
+      agentStatus: 'agent_working',
+      readOnly: false,
+      messages: [],
+    }),
+  );
+  const preparedText = 'Make it primary.';
+
+  assert.deepEqual(getChatComposerState(disconnected, preparedText), {
+    canSend: false,
+    disabledReason: 'Agent Status is Waiting for agent.',
+    isTooLong: false,
+  });
+
+  const recovered = getInitialChatSessionState({
+    status: 'ok',
+    agentStatus: 'agent_ready',
+    readOnly: false,
+    messages: [],
+  });
+
+  assert.deepEqual(getChatComposerState(recovered, preparedText), {
+    canSend: true,
+    disabledReason: null,
+    isTooLong: false,
+  });
+  assert.equal(
+    getComposerTextAfterSendResult(preparedText, false),
+    preparedText,
+  );
+});
+
 test('limits typed composer text to 4000 characters', () => {
   const state = getInitialChatSessionState({
     status: 'ok',
@@ -74,6 +130,12 @@ test('limits typed composer text to 4000 characters', () => {
   });
 });
 
+test('lets typed composer text exceed the limit so inline validation can explain it', () => {
+  assert.deepEqual(getChatComposerTextareaInputPolicy(), {
+    maxLength: undefined,
+  });
+});
+
 test('Enter submits the Chat composer while Shift+Enter inserts a newline', () => {
   assert.equal(shouldSubmitChatComposerKey('Enter', false), true);
   assert.equal(shouldSubmitChatComposerKey('Enter', true), false);
diff --git a/apps/web/src/chat/chatComposerState.ts b/apps/web/src/chat/chatComposerState.ts
index 5947856..d0f24b7 100644
--- a/apps/web/src/chat/chatComposerState.ts
+++ b/apps/web/src/chat/chatComposerState.ts
@@ -11,6 +11,10 @@ export type ChatComposerState = {
   isTooLong: boolean;
 };
 
+export type ChatComposerTextareaInputPolicy = {
+  maxLength: number | undefined;
+};
+
 /**
  * Derive Chat composer sendability from Chat session state and attachments.
  *
@@ -83,6 +87,18 @@ export function getChatComposerState(
   };
 }
 
+/**
+ * Return DOM input constraints for the Chat composer textarea.
+ *
+ * The composer intentionally does not set `maxLength`: over-limit text must
+ * remain in local state so inline validation can explain why Send is disabled.
+ */
+export function getChatComposerTextareaInputPolicy(): ChatComposerTextareaInputPolicy {
+  return {
+    maxLength: undefined,
+  };
+}
+
 /**
  * Return whether a textarea key press should submit Chat.
  *
diff --git a/apps/web/src/chat/chatSessionState.test.ts b/apps/web/src/chat/chatSessionState.test.ts
index b0c0c4a..19745fa 100644
--- a/apps/web/src/chat/chatSessionState.test.ts
+++ b/apps/web/src/chat/chatSessionState.test.ts
@@ -80,6 +80,44 @@ test('applies Chat History and Agent Status bridge events', () => {
   ]);
 });
 
+test('keeps read-only Chat sessions observable while applying bridge events', () => {
+  const initial = getInitialChatSessionState({
+    status: 'ok',
+    agentStatus: 'waiting_for_agent',
+    readOnly: true,
+    messages: [],
+  });
+
+  const nextState = reduceChatSessionBridgeEvent(initial, {
+    type: 'chat_snapshot',
+    sessionId: 'session-1',
+    payload: {
+      agentStatus: 'agent_ready',
+      messages: [
+        {
+          id: 'message-1',
+          role: 'agent',
+          text: 'Ready.',
+        },
+      ],
+    },
+  });
+
+  assert.deepEqual(nextState, {
+    status: 'ready',
+    agentStatus: 'agent_ready',
+    readOnly: true,
+    connectionWarning: null,
+    messages: [
+      {
+        id: 'message-1',
+        role: 'agent',
+        text: 'Ready.',
+      },
+    ],
+  });
+});
+
 test('replays queued bridge events after loading the initial Chat snapshot', () => {
   assert.deepEqual(
     getInitialChatSessionStateWithQueuedEvents(
@@ -151,6 +189,45 @@ test('maps session event disconnect to Waiting for agent with a warning', () =>
   });
 });
 
+test('clears the session event disconnect warning when bridge events resume', () => {
+  const disconnected = reduceChatSessionDisconnected(
+    getInitialChatSessionState({
+      status: 'ok',
+      agentStatus: 'agent_working',
+      readOnly: false,
+      messages: [
+        {
+          id: 'message-1',
+          role: 'user',
+          text: 'Make it primary.',
+        },
+      ],
+    }),
+  );
+
+  const reconnected = reduceChatSessionBridgeEvent(disconnected, {
+    type: 'agent_status_changed',
+    sessionId: 'session-1',
+    payload: {
+      agentStatus: 'agent_ready',
+    },
+  });
+
+  assert.deepEqual(reconnected, {
+    status: 'ready',
+    agentStatus: 'agent_ready',
+    readOnly: false,
+    connectionWarning: null,
+    messages: [
+      {
+        id: 'message-1',
+        role: 'user',
+        text: 'Make it primary.',
+      },
+    ],
+  });
+});
+
 test('adds a temporary Agent working placeholder to visible Chat History', () => {
   const state = getInitialChatSessionState({
     status: 'ok',
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index 57c27a2..053149f 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -1,4 +1,4 @@
-import { CHAT_COMPOSER_TEXT_LIMIT } from '../../chat/chatComposerState';
+import { getChatComposerTextareaInputPolicy } from '../../chat/chatComposerState';
 import type { ChatSessionState } from '../../chat/chatSessionState';
 import type { SelectionCommentAttachmentToken } from '../../selection-comments/selectionCommentState';
 import type { useChatComposerFlow } from './useChatComposerFlow';
@@ -20,6 +20,8 @@ export function ChatComposer({
   placeholder: string;
   sessionId: string | null;
 }) {
+  const inputPolicy = getChatComposerTextareaInputPolicy();
+
   return (
     <form
       className="chat-composer"
@@ -48,7 +50,7 @@ export function ChatComposer({
         aria-label="Message"
         className="chat-composer-input"
         disabled={chatSessionState.status === 'ready' && chatSessionState.readOnly}
-        maxLength={CHAT_COMPOSER_TEXT_LIMIT}
+        maxLength={inputPolicy.maxLength}
         onChange={(event) => {
           composer.handleComposerTextChange(event.target.value);
         }}
diff --git a/apps/web/src/components/chat/ChatPanel.tsx b/apps/web/src/components/chat/ChatPanel.tsx
index f6cd1c9..bbbc01e 100644
--- a/apps/web/src/components/chat/ChatPanel.tsx
+++ b/apps/web/src/components/chat/ChatPanel.tsx
@@ -24,6 +24,7 @@ export function ChatPanel({
   activeSelectionCommentId,
   attachmentTokens,
   chatSessionState,
+  isReadOnly,
   isSelectWidgetActive,
   onAttachmentTokenClick,
   onSelectionCommentStateChange,
@@ -36,6 +37,7 @@ export function ChatPanel({
   activeSelectionCommentId: string | null;
   attachmentTokens: SelectionCommentAttachmentToken[];
   chatSessionState: ChatSessionState;
+  isReadOnly: boolean;
   isSelectWidgetActive: boolean;
   onAttachmentTokenClick: (token: SelectionCommentAttachmentToken) => void;
   onSelectionCommentStateChange: Dispatch<SetStateAction<SelectionCommentState>>;
@@ -49,6 +51,7 @@ export function ChatPanel({
   const selectionComments = useSelectionCommentPanelFlow({
     activeSelectionCommentId,
     attachmentTokens,
+    isReadOnly,
     isSelectWidgetActive,
     onSelectionCommentStateChange,
     selectedWidget,
diff --git a/apps/web/src/components/chat/SelectedWidgetSection.tsx b/apps/web/src/components/chat/SelectedWidgetSection.tsx
index 487ad0b..55ff43c 100644
--- a/apps/web/src/components/chat/SelectedWidgetSection.tsx
+++ b/apps/web/src/components/chat/SelectedWidgetSection.tsx
@@ -1,4 +1,4 @@
-import { SELECTION_COMMENT_TEXT_LIMIT } from '../../selection-comments/selectionCommentState';
+import { getSelectionCommentTextareaInputPolicy } from '../../selection-comments/selectionCommentState';
 import type { useSelectionCommentPanelFlow } from './useSelectionCommentPanelFlow';
 
 type SelectionCommentPanelFlow = ReturnType<
@@ -15,6 +15,7 @@ export function SelectedWidgetSection({
   title: string;
 }) {
   const panelTarget = selectionComments.panelTarget;
+  const inputPolicy = getSelectionCommentTextareaInputPolicy();
 
   return (
     <section className="selected-widget-card" aria-labelledby="selected-widget-title">
@@ -61,7 +62,8 @@ export function SelectedWidgetSection({
                   <textarea
                     aria-label={`Selection Comment ${comment.number}`}
                     className="selection-comment-edit"
-                    maxLength={SELECTION_COMMENT_TEXT_LIMIT}
+                    disabled={selectionComments.isReadOnly}
+                    maxLength={inputPolicy.maxLength}
                     onChange={(event) => {
                       selectionComments.handleSelectionCommentTextChange(
                         comment.id,
@@ -74,6 +76,7 @@ export function SelectedWidgetSection({
                   <button
                     aria-label={`Delete Selection Comment ${comment.number}`}
                     className="selection-comment-delete"
+                    disabled={selectionComments.isReadOnly}
                     onClick={() =>
                       selectionComments.handleDeleteSelectionComment(comment.id)
                     }
@@ -90,8 +93,8 @@ export function SelectedWidgetSection({
             <textarea
               aria-label="Selection Comment"
               className="selection-comment-input"
-              disabled={panelTarget === null}
-              maxLength={SELECTION_COMMENT_TEXT_LIMIT}
+              disabled={panelTarget === null || selectionComments.isReadOnly}
+              maxLength={inputPolicy.maxLength}
               onChange={(event) => {
                 selectionComments.handleSelectionCommentDraftChange(
                   event.currentTarget.value,
diff --git a/apps/web/src/components/chat/chatPanelContent.test.ts b/apps/web/src/components/chat/chatPanelContent.test.ts
index 21cd359..f15ddef 100644
--- a/apps/web/src/components/chat/chatPanelContent.test.ts
+++ b/apps/web/src/components/chat/chatPanelContent.test.ts
@@ -23,3 +23,20 @@ test('defines the Chat shell sections and initial Agent Status language', () =>
     composerDisabledReason: 'Agent Status is Waiting for agent.',
   });
 });
+
+test('keeps non-MVP Chat History controls out of the Chat panel contract', () => {
+  const serializedContent = JSON.stringify({
+    sections: CHAT_PANEL_SECTIONS,
+    initial: getInitialChatPanelState(),
+  }).toLowerCase();
+
+  for (const unsupportedControl of [
+    'search',
+    'clear',
+    'export',
+    'end session',
+    'resend',
+  ]) {
+    assert.equal(serializedContent.includes(unsupportedControl), false);
+  }
+});
diff --git a/apps/web/src/components/chat/useSelectionCommentPanelFlow.ts b/apps/web/src/components/chat/useSelectionCommentPanelFlow.ts
index 41c18af..a581168 100644
--- a/apps/web/src/components/chat/useSelectionCommentPanelFlow.ts
+++ b/apps/web/src/components/chat/useSelectionCommentPanelFlow.ts
@@ -31,6 +31,7 @@ import { captureSelectionCommentSnapshot } from '../../services/askUiBridgeClien
 type UseSelectionCommentPanelFlowOptions = {
   activeSelectionCommentId: string | null;
   attachmentTokens: SelectionCommentAttachmentToken[];
+  isReadOnly: boolean;
   isSelectWidgetActive: boolean;
   onSelectionCommentStateChange: Dispatch<SetStateAction<SelectionCommentState>>;
   selectedWidget: SelectedWidgetTarget | null;
@@ -42,6 +43,7 @@ type UseSelectionCommentPanelFlowOptions = {
 export function useSelectionCommentPanelFlow({
   activeSelectionCommentId,
   attachmentTokens,
+  isReadOnly,
   isSelectWidgetActive,
   onSelectionCommentStateChange,
   selectedWidget,
@@ -78,6 +80,7 @@ export function useSelectionCommentPanelFlow({
     panelTarget,
   );
   const selectionCommentInputState = getSelectionCommentInputState({
+    isReadOnly,
     isSelectWidgetActive,
     selectedWidget: panelTarget,
     widgetTreeStatus,
@@ -195,6 +198,7 @@ export function useSelectionCommentPanelFlow({
     getSelectionCommentDraftsByWidgetIdForSend,
     getSelectionCommentsForSend,
     panelTarget,
+    isReadOnly,
     selectedWidgetComments,
     selectionCommentInputState,
     selectionCommentText,
diff --git a/apps/web/src/components/live-app-surface/DeviceShell.tsx b/apps/web/src/components/live-app-surface/DeviceShell.tsx
index 160bb68..d96192c 100644
--- a/apps/web/src/components/live-app-surface/DeviceShell.tsx
+++ b/apps/web/src/components/live-app-surface/DeviceShell.tsx
@@ -4,6 +4,7 @@ import type { LiveAppSurfaceState } from '../../live-app-surface/liveAppSurfaceS
 import {
   buildSystemKeyMessage,
   buildTouchMessage,
+  shouldSendDeviceControlMessage,
   type DeviceControlMessage,
   type DeviceSystemKey,
 } from '../../live-app-surface/deviceControlProtocol';
@@ -142,7 +143,13 @@ export function DeviceShell({
     action: 'down' | 'move' | 'up' | 'cancel',
     event: PointerEvent<HTMLDivElement>,
   ) => {
-    if (isInputDisabled || !fit || !metadata.controlReady) {
+    if (
+      !shouldSendDeviceControlMessage({
+        isInputDisabled,
+        controlReady: metadata.controlReady,
+      }) ||
+      !fit
+    ) {
       return;
     }
 
@@ -218,7 +225,12 @@ export function DeviceShell({
   };
 
   const sendSystemKey = (key: DeviceSystemKey) => {
-    if (isInputDisabled) {
+    if (
+      !shouldSendDeviceControlMessage({
+        isInputDisabled,
+        controlReady: metadata.controlReady,
+      })
+    ) {
       return;
     }
 
@@ -262,7 +274,12 @@ export function DeviceShell({
       <div className="surface-controls">
         <button
           aria-label="Back"
-          disabled={isInputDisabled || !metadata.controlReady}
+          disabled={
+            !shouldSendDeviceControlMessage({
+              isInputDisabled,
+              controlReady: metadata.controlReady,
+            })
+          }
           onClick={() => sendSystemKey('back')}
           title="Back"
           type="button"
@@ -271,7 +288,12 @@ export function DeviceShell({
         </button>
         <button
           aria-label="Home"
-          disabled={isInputDisabled || !metadata.controlReady}
+          disabled={
+            !shouldSendDeviceControlMessage({
+              isInputDisabled,
+              controlReady: metadata.controlReady,
+            })
+          }
           onClick={() => sendSystemKey('home')}
           title="Home"
           type="button"
@@ -280,7 +302,12 @@ export function DeviceShell({
         </button>
         <button
           aria-label="Recents"
-          disabled={isInputDisabled || !metadata.controlReady}
+          disabled={
+            !shouldSendDeviceControlMessage({
+              isInputDisabled,
+              controlReady: metadata.controlReady,
+            })
+          }
           onClick={() => sendSystemKey('recents')}
           title="Recents"
           type="button"
diff --git a/apps/web/src/live-app-surface/deviceControlProtocol.test.ts b/apps/web/src/live-app-surface/deviceControlProtocol.test.ts
index 960d845..306a6fd 100644
--- a/apps/web/src/live-app-surface/deviceControlProtocol.test.ts
+++ b/apps/web/src/live-app-surface/deviceControlProtocol.test.ts
@@ -6,6 +6,7 @@ import {
   buildTouchMessage,
   deviceSystemKeys,
   deviceTouchActions,
+  shouldSendDeviceControlMessage,
 } from './deviceControlProtocol.ts';
 
 test('builds touch messages with centralized action values', () => {
@@ -53,3 +54,27 @@ test('builds system key messages with centralized key values', () => {
     key: 'recents',
   });
 });
+
+test('blocks Device control messages in read-only browser tabs', () => {
+  assert.equal(
+    shouldSendDeviceControlMessage({
+      isInputDisabled: true,
+      controlReady: true,
+    }),
+    false,
+  );
+  assert.equal(
+    shouldSendDeviceControlMessage({
+      isInputDisabled: false,
+      controlReady: false,
+    }),
+    false,
+  );
+  assert.equal(
+    shouldSendDeviceControlMessage({
+      isInputDisabled: false,
+      controlReady: true,
+    }),
+    true,
+  );
+});
diff --git a/apps/web/src/live-app-surface/deviceControlProtocol.ts b/apps/web/src/live-app-surface/deviceControlProtocol.ts
index c58ceea..56cead4 100644
--- a/apps/web/src/live-app-surface/deviceControlProtocol.ts
+++ b/apps/web/src/live-app-surface/deviceControlProtocol.ts
@@ -23,6 +23,16 @@ export type DeviceControlMessage = DeviceTouchMessage | DeviceSystemKeyMessage;
 
 const maxPointerId = 0xffffffff;
 
+export function shouldSendDeviceControlMessage({
+  isInputDisabled,
+  controlReady,
+}: {
+  isInputDisabled: boolean;
+  controlReady: boolean;
+}): boolean {
+  return !isInputDisabled && controlReady;
+}
+
 /**
  * Build the JSON touch control message sent over the Device WebSocket.
  *
diff --git a/apps/web/src/selection-comments/selectionCommentValidation.test.ts b/apps/web/src/selection-comments/selectionCommentValidation.test.ts
index 952687c..f10c716 100644
--- a/apps/web/src/selection-comments/selectionCommentValidation.test.ts
+++ b/apps/web/src/selection-comments/selectionCommentValidation.test.ts
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import {
+  getSelectionCommentTextareaInputPolicy,
   getSelectionCommentInputState,
   SELECTION_COMMENT_BATCH_LIMIT,
   SELECTION_COMMENT_TEXT_LIMIT,
@@ -55,6 +56,24 @@ test('enables Add comment only with Select Widget mode and reliable selected wid
   );
 });
 
+test('disables Selection Comment authoring in read-only browser tabs', () => {
+  assert.deepEqual(
+    getSelectionCommentInputState({
+      isReadOnly: true,
+      isSelectWidgetActive: true,
+      selectedWidget: target,
+      widgetTreeStatus: 'loaded',
+      text: 'Make this primary.',
+      batchSize: 0,
+    }),
+    {
+      canAdd: false,
+      disabledReason: 'Read-only browser tabs cannot edit Selection Comments.',
+      isTooLong: false,
+    },
+  );
+});
+
 test('validates Selection Comment text, batch limit, and Widget Tree failure', () => {
   assert.deepEqual(
     getSelectionCommentInputState({
@@ -108,3 +127,9 @@ test('validates Selection Comment text, batch limit, and Widget Tree failure', (
     'Widget Tree is unavailable.',
   );
 });
+
+test('lets Selection Comment text exceed the limit so inline validation can explain it', () => {
+  assert.deepEqual(getSelectionCommentTextareaInputPolicy(), {
+    maxLength: undefined,
+  });
+});
diff --git a/apps/web/src/selection-comments/selectionCommentValidation.ts b/apps/web/src/selection-comments/selectionCommentValidation.ts
index 0634845..3b55733 100644
--- a/apps/web/src/selection-comments/selectionCommentValidation.ts
+++ b/apps/web/src/selection-comments/selectionCommentValidation.ts
@@ -5,13 +5,19 @@ import {
   type SelectionCommentInputState,
 } from './selectionCommentTypes.ts';
 
+export type SelectionCommentTextareaInputPolicy = {
+  maxLength: number | undefined;
+};
+
 export function getSelectionCommentInputState({
+  isReadOnly = false,
   isSelectWidgetActive,
   selectedWidget,
   widgetTreeStatus,
   text,
   batchSize,
 }: {
+  isReadOnly?: boolean;
   isSelectWidgetActive: boolean;
   selectedWidget: SelectedWidgetTarget | null;
   widgetTreeStatus: 'loading' | 'loaded' | 'error';
@@ -20,6 +26,14 @@ export function getSelectionCommentInputState({
 }): SelectionCommentInputState {
   const isTooLong = text.length > SELECTION_COMMENT_TEXT_LIMIT;
 
+  if (isReadOnly) {
+    return {
+      canAdd: false,
+      disabledReason: 'Read-only browser tabs cannot edit Selection Comments.',
+      isTooLong,
+    };
+  }
+
   if (!isSelectWidgetActive) {
     return {
       canAdd: false,
@@ -78,3 +92,15 @@ export function getSelectionCommentInputState({
     isTooLong,
   };
 }
+
+/**
+ * Return DOM input constraints for Selection Comment textareas.
+ *
+ * The UI keeps over-limit text editable so the existing inline validation can
+ * explain why Add comment is disabled.
+ */
+export function getSelectionCommentTextareaInputPolicy(): SelectionCommentTextareaInputPolicy {
+  return {
+    maxLength: undefined,
+  };
+}
diff --git a/issues/0.0.3-selection-chat.md b/issues/0.0.3-selection-chat.md
index b415ba0..833ab4e 100644
--- a/issues/0.0.3-selection-chat.md
+++ b/issues/0.0.3-selection-chat.md
@@ -400,29 +400,29 @@ This slice closes the remaining edge cases after the main Chat loop is working:
 
 ## Acceptance criteria
 
-- [ ] One Chat message is limited to 20 Selection Comments.
-- [ ] Selection Comment text is limited to 1000 characters.
-- [ ] Typed composer text is limited to 4000 characters.
-- [ ] Over-limit states show inline validation.
-- [ ] Chat History is stored in Bridge Session memory.
-- [ ] Chat History is not restored after bridge backend restart.
-- [ ] Snapshot files are not restored after bridge backend restart.
-- [ ] Bridge restart is treated as session end for Chat.
-- [ ] A second browser tab is read-only.
-- [ ] Read-only tabs receive Chat History and Agent Status updates.
-- [ ] Read-only tabs cannot edit composer content.
-- [ ] Read-only tabs cannot send.
-- [ ] Read-only tabs cannot control the Live App Surface.
-- [ ] Session events/SSE disconnect disables Send and shows a connection warning.
-- [ ] Session events/SSE reconnect preserves local unsent state and does not auto-send.
-- [ ] Agent Status changes do not clear typed text, staged comments, tokens, markers, or drafts.
-- [ ] `Agent ready` recovery enables Send but does not auto-send prepared content.
-- [ ] No Chat History search UI is added.
-- [ ] No Chat History clear UI is added.
-- [ ] No Chat History export UI is added.
-- [ ] No End Session control is added inside Chat.
-- [ ] No Resend control is added for delivered messages.
-- [ ] Tests cover the hardening behaviors above at module or rendered-state boundaries.
+- [x] One Chat message is limited to 20 Selection Comments.
+- [x] Selection Comment text is limited to 1000 characters.
+- [x] Typed composer text is limited to 4000 characters.
+- [x] Over-limit states show inline validation.
+- [x] Chat History is stored in Bridge Session memory.
+- [x] Chat History is not restored after bridge backend restart.
+- [x] Snapshot files are not restored after bridge backend restart.
+- [x] Bridge restart is treated as session end for Chat.
+- [x] A second browser tab is read-only.
+- [x] Read-only tabs receive Chat History and Agent Status updates.
+- [x] Read-only tabs cannot edit composer content.
+- [x] Read-only tabs cannot send.
+- [x] Read-only tabs cannot control the Live App Surface.
+- [x] Session events/SSE disconnect disables Send and shows a connection warning.
+- [x] Session events/SSE reconnect preserves local unsent state and does not auto-send.
+- [x] Agent Status changes do not clear typed text, staged comments, tokens, markers, or drafts.
+- [x] `Agent ready` recovery enables Send but does not auto-send prepared content.
+- [x] No Chat History search UI is added.
+- [x] No Chat History clear UI is added.
+- [x] No Chat History export UI is added.
+- [x] No End Session control is added inside Chat.
+- [x] No Resend control is added for delivered messages.
+- [x] Tests cover the hardening behaviors above at module or rendered-state boundaries.
 
 ## Blocked by
 

From 00ceb1ce29bde528e6d8bf30bb1df5092dbe48af Mon Sep 17 00:00:00 2001
From: drown0315 <drown0315@gmail.com>
Date: Thu, 9 Jul 2026 16:51:55 +0800
Subject: [PATCH 3/6] feat: add ask ui runtime package

---
 packages/ask_ui_runtime/README.md             | 29 ++++++
 .../ask_ui_runtime/lib/ask_ui_runtime.dart    |  1 +
 .../lib/src/ask_ui_runtime.dart               | 92 +++++++++++++++++++
 packages/ask_ui_runtime/pubspec.yaml          | 16 ++++
 .../test/widget_bounds_extension_test.dart    | 47 ++++++++++
 5 files changed, 185 insertions(+)
 create mode 100644 packages/ask_ui_runtime/README.md
 create mode 100644 packages/ask_ui_runtime/lib/ask_ui_runtime.dart
 create mode 100644 packages/ask_ui_runtime/lib/src/ask_ui_runtime.dart
 create mode 100644 packages/ask_ui_runtime/pubspec.yaml
 create mode 100644 packages/ask_ui_runtime/test/widget_bounds_extension_test.dart

diff --git a/packages/ask_ui_runtime/README.md b/packages/ask_ui_runtime/README.md
new file mode 100644
index 0000000..7cdc610
--- /dev/null
+++ b/packages/ask_ui_runtime/README.md
@@ -0,0 +1,29 @@
+# ask_ui_runtime
+
+Debug runtime service extensions for Ask UI Flutter app integration.
+
+## Usage
+
+Add the package to your Flutter app:
+
+```yaml
+dependencies:
+  ask_ui_runtime:
+    path: /path/to/ask_ui/packages/ask_ui_runtime
+```
+
+Register the runtime before `runApp`:
+
+```dart
+import 'package:ask_ui_runtime/ask_ui_runtime.dart';
+
+void main() {
+  registerAskUiRuntime();
+  runApp(const MyApp());
+}
+```
+
+`registerAskUiRuntime` currently registers `ext.ask_ui.widgetBounds`, which Ask
+UI Bridge uses to query real `RenderBox.localToGlobal` bounds for Flutter
+Inspector widget ids. Registration is debug-only and is removed from release
+builds by Dart assertions.
diff --git a/packages/ask_ui_runtime/lib/ask_ui_runtime.dart b/packages/ask_ui_runtime/lib/ask_ui_runtime.dart
new file mode 100644
index 0000000..6f53b2c
--- /dev/null
+++ b/packages/ask_ui_runtime/lib/ask_ui_runtime.dart
@@ -0,0 +1 @@
+export 'src/ask_ui_runtime.dart';
diff --git a/packages/ask_ui_runtime/lib/src/ask_ui_runtime.dart b/packages/ask_ui_runtime/lib/src/ask_ui_runtime.dart
new file mode 100644
index 0000000..3293763
--- /dev/null
+++ b/packages/ask_ui_runtime/lib/src/ask_ui_runtime.dart
@@ -0,0 +1,92 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:developer' as developer;
+
+import 'package:flutter/widgets.dart';
+
+const _widgetBoundsExtensionName = 'ext.ask_ui.widgetBounds';
+
+bool _didRegisterAskUiRuntime = false;
+
+/// Registers Ask UI debug runtime service extensions for the current app.
+///
+/// Call this before `runApp` in a Flutter debug build:
+///
+/// ```dart
+/// void main() {
+///   registerAskUiRuntime();
+///   runApp(const MyApp());
+/// }
+/// ```
+///
+/// The registration is wrapped in `assert`, so it is tree-shaken from release
+/// builds and has no production behavior.
+void registerAskUiRuntime() {
+  assert(() {
+    if (_didRegisterAskUiRuntime) {
+      return true;
+    }
+    _didRegisterAskUiRuntime = true;
+    developer.registerExtension(
+      _widgetBoundsExtensionName,
+      _handleWidgetBoundsExtension,
+    );
+    return true;
+  }());
+}
+
+Future<developer.ServiceExtensionResponse> _handleWidgetBoundsExtension(
+  String method,
+  Map<String, String> parameters,
+) async {
+  final id = parameters['id'];
+  final groupName = parameters['groupName'];
+  final inspector = WidgetInspectorService.instance as dynamic;
+  final object = inspector.toObject(id, groupName);
+
+  return _jsonResult(widgetBoundsResultForInspectorObject(object));
+}
+
+developer.ServiceExtensionResponse _jsonResult(Map<String, Object?> result) {
+  return developer.ServiceExtensionResponse.result(jsonEncode(result));
+}
+
+/// Converts a Flutter Inspector object into Ask UI widget bounds JSON.
+///
+/// This is public only for package tests. App code should call
+/// [registerAskUiRuntime] instead.
+Map<String, Object?> widgetBoundsResultForInspectorObject(Object? object) {
+  if (object is! Element) {
+    return {
+      'found': false,
+      'reason': 'not_element',
+    };
+  }
+
+  final renderObject = object.renderObject;
+  if (renderObject is! RenderBox || !renderObject.hasSize) {
+    return {
+      'found': false,
+      'reason': 'not_render_box',
+    };
+  }
+
+  final topLeft = renderObject.localToGlobal(Offset.zero);
+  final view = View.maybeOf(object);
+  final physicalSize = view?.physicalSize;
+
+  return {
+    'found': true,
+    'x': topLeft.dx,
+    'y': topLeft.dy,
+    'width': renderObject.size.width,
+    'height': renderObject.size.height,
+    'coordinateSpace': 'flutterLogical',
+    'devicePixelRatio': view?.devicePixelRatio ?? 1.0,
+    if (physicalSize != null)
+      'physicalSize': {
+        'width': physicalSize.width,
+        'height': physicalSize.height,
+      },
+  };
+}
diff --git a/packages/ask_ui_runtime/pubspec.yaml b/packages/ask_ui_runtime/pubspec.yaml
new file mode 100644
index 0000000..253fe42
--- /dev/null
+++ b/packages/ask_ui_runtime/pubspec.yaml
@@ -0,0 +1,16 @@
+name: ask_ui_runtime
+description: Debug runtime service extensions for Ask UI Flutter app integration.
+version: 0.1.0
+publish_to: none
+
+environment:
+  sdk: '>=3.4.0 <4.0.0'
+  flutter: '>=3.22.0'
+
+dependencies:
+  flutter:
+    sdk: flutter
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
diff --git a/packages/ask_ui_runtime/test/widget_bounds_extension_test.dart b/packages/ask_ui_runtime/test/widget_bounds_extension_test.dart
new file mode 100644
index 0000000..cf22e78
--- /dev/null
+++ b/packages/ask_ui_runtime/test/widget_bounds_extension_test.dart
@@ -0,0 +1,47 @@
+import 'package:ask_ui_runtime/src/ask_ui_runtime.dart';
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('reports not_element when Inspector id does not resolve to an Element',
+      () {
+    expect(widgetBoundsResultForInspectorObject(null), {
+      'found': false,
+      'reason': 'not_element',
+    });
+  });
+
+  testWidgets('returns RenderBox global bounds in Flutter logical pixels',
+      (tester) async {
+    final key = GlobalKey();
+
+    await tester.pumpWidget(
+      Directionality(
+        textDirection: TextDirection.ltr,
+        child: Stack(
+          children: [
+            Positioned(
+              left: 12,
+              top: 24,
+              width: 80,
+              height: 40,
+              child: SizedBox(key: key),
+            ),
+          ],
+        ),
+      ),
+    );
+
+    final element = key.currentContext as Element;
+    final result = widgetBoundsResultForInspectorObject(element);
+
+    expect(result['found'], isTrue);
+    expect(result['x'], 12.0);
+    expect(result['y'], 24.0);
+    expect(result['width'], 80.0);
+    expect(result['height'], 40.0);
+    expect(result['coordinateSpace'], 'flutterLogical');
+    expect(result['devicePixelRatio'], tester.view.devicePixelRatio);
+  });
+
+}

From a56b49a0e74d76a0c70790a075989d6049fb32cf Mon Sep 17 00:00:00 2001
From: drown0315 <drown0315@gmail.com>
Date: Thu, 9 Jul 2026 16:55:06 +0800
Subject: [PATCH 4/6] feat: fetch widget bounds from ask ui runtime

---
 .../inspector/flutter_inspector_client.dart   | 136 ++++++++++++
 .../lib/widget_tree/widget_tree_snapshot.dart |  33 ++-
 .../test/flutter_inspector_client_test.dart   | 194 +++++++++++++++++-
 .../test/widget_tree_snapshot_test.dart       |  32 +++
 4 files changed, 393 insertions(+), 2 deletions(-)

diff --git a/apps/bridge/lib/inspector/flutter_inspector_client.dart b/apps/bridge/lib/inspector/flutter_inspector_client.dart
index 4ddb872..25ed2ec 100644
--- a/apps/bridge/lib/inspector/flutter_inspector_client.dart
+++ b/apps/bridge/lib/inspector/flutter_inspector_client.dart
@@ -125,9 +125,16 @@ class VmServiceFlutterInspectorClient implements FlutterInspectorClient {
         );
       }
 
+      final boundsById = await _fetchWidgetBoundsById(
+        vmService,
+        isolateId: isolateId,
+        diagnosticsNode: result,
+      );
+
       return WidgetTreeNode.fromFlutterDiagnostics(
         result,
         projectRoot: session.projectRoot,
+        boundsById: boundsById,
       );
     } finally {
       await vmService.dispose();
@@ -303,6 +310,123 @@ class VmServiceFlutterInspectorClient implements FlutterInspectorClient {
   }
 }
 
+Future<Map<String, WidgetBounds>> _fetchWidgetBoundsById(
+  FlutterInspectorVmService vmService, {
+  required String isolateId,
+  required Map<String, Object?> diagnosticsNode,
+}) async {
+  final boundsById = <String, WidgetBounds>{};
+
+  for (final widgetId in _widgetIdsInDiagnostics(diagnosticsNode)) {
+    final WidgetBounds? bounds;
+    try {
+      bounds = await _fetchWidgetBounds(
+        vmService,
+        isolateId: isolateId,
+        widgetId: widgetId,
+      );
+    } on _WidgetBoundsExtensionUnavailable {
+      break;
+    }
+    if (bounds == null) {
+      continue;
+    }
+    boundsById[widgetId] = bounds;
+  }
+
+  return boundsById;
+}
+
+Iterable<String> _widgetIdsInDiagnostics(
+  Map<String, Object?> diagnosticsNode,
+) sync* {
+  final id = diagnosticsNode['valueId']?.toString().trim();
+  if (id != null && id.isNotEmpty) {
+    yield id;
+  }
+
+  final rawChildren = diagnosticsNode['children'];
+  if (rawChildren is! List) {
+    return;
+  }
+
+  for (final child in rawChildren.whereType<Map<String, Object?>>()) {
+    yield* _widgetIdsInDiagnostics(child);
+  }
+}
+
+Future<WidgetBounds?> _fetchWidgetBounds(
+  FlutterInspectorVmService vmService, {
+  required String isolateId,
+  required String widgetId,
+}) async {
+  final response = await _callWidgetBoundsExtension(
+    vmService,
+    isolateId: isolateId,
+    widgetId: widgetId,
+  );
+  if (response == null) {
+    return null;
+  }
+
+  final result = _decodeInspectorResult(response);
+  if (result is! Map<String, Object?>) {
+    return null;
+  }
+
+  return _widgetBoundsFromAppSideResult(result);
+}
+
+Future<Map<String, Object?>?> _callWidgetBoundsExtension(
+  FlutterInspectorVmService vmService, {
+  required String isolateId,
+  required String widgetId,
+}) async {
+  try {
+    return await vmService.callServiceExtension(
+      'ext.ask_ui.widgetBounds',
+      isolateId: isolateId,
+      args: {
+        'id': widgetId,
+        'groupName': 'ask_ui_widget_tree',
+      },
+    );
+  } on FlutterInspectorServiceUnavailableException {
+    throw const _WidgetBoundsExtensionUnavailable();
+  } on RPCError catch (error) {
+    if (error.code == RPCErrorKind.kMethodNotFound.code) {
+      throw const _WidgetBoundsExtensionUnavailable();
+    }
+    rethrow;
+  }
+}
+
+WidgetBounds? _widgetBoundsFromAppSideResult(Map<String, Object?> result) {
+  final x = _doubleFrom(result['x']);
+  final y = _doubleFrom(result['y']);
+  final width = _doubleFrom(result['width']);
+  final height = _doubleFrom(result['height']);
+  final devicePixelRatio = _doubleFrom(result['devicePixelRatio']) ?? 1;
+
+  if (x == null || y == null || width == null || height == null) {
+    return null;
+  }
+  if (width <= 0 || height <= 0 || devicePixelRatio <= 0) {
+    return null;
+  }
+
+  return WidgetBounds(
+    x: x * devicePixelRatio,
+    y: y * devicePixelRatio,
+    width: width * devicePixelRatio,
+    height: height * devicePixelRatio,
+  );
+}
+
+class _WidgetBoundsExtensionUnavailable implements Exception {
+  const _WidgetBoundsExtensionUnavailable();
+}
+
 Object? _decodeInspectorResult(Map<String, Object?> response) {
   final result = response['result'] ?? response['object'] ?? response['value'];
 
@@ -313,6 +437,18 @@ Object? _decodeInspectorResult(Map<String, Object?> response) {
   return result ?? response;
 }
 
+double? _doubleFrom(Object? value) {
+  if (value is num) {
+    return value.toDouble();
+  }
+
+  final stringValue = value?.toString().trim();
+  if (stringValue == null || stringValue.isEmpty) {
+    return null;
+  }
+  return double.tryParse(stringValue);
+}
+
 class FlutterInspectorException implements Exception {
   const FlutterInspectorException(this.message);
 
diff --git a/apps/bridge/lib/widget_tree/widget_tree_snapshot.dart b/apps/bridge/lib/widget_tree/widget_tree_snapshot.dart
index 3b9b5cc..7473e97 100644
--- a/apps/bridge/lib/widget_tree/widget_tree_snapshot.dart
+++ b/apps/bridge/lib/widget_tree/widget_tree_snapshot.dart
@@ -14,6 +14,7 @@ class WidgetTreeNode {
     required this.id,
     required this.label,
     required this.children,
+    this.bounds,
     this.sourceLocation,
     this.visibleText,
     this.semanticInfo,
@@ -42,8 +43,10 @@ class WidgetTreeNode {
   factory WidgetTreeNode.fromFlutterDiagnostics(
     Map<String, Object?> diagnosticsNode, {
     String? projectRoot,
+    Map<String, WidgetBounds> boundsById = const {},
   }) {
     final rawChildren = diagnosticsNode['children'];
+    final id = diagnosticsNode['valueId']?.toString() ?? '';
     final children = rawChildren is List
         ? rawChildren
             .whereType<Map<String, Object?>>()
@@ -51,6 +54,7 @@ class WidgetTreeNode {
               (child) => WidgetTreeNode.fromFlutterDiagnostics(
                 child,
                 projectRoot: projectRoot,
+                boundsById: boundsById,
               ),
             )
             .toList()
@@ -58,7 +62,7 @@ class WidgetTreeNode {
     final description = diagnosticsNode['description']?.toString() ?? '';
 
     return WidgetTreeNode(
-      id: diagnosticsNode['valueId']?.toString() ?? '',
+      id: id,
       label: description,
       sourceLocation: _sourceLocationFromDiagnostics(
         diagnosticsNode,
@@ -70,12 +74,14 @@ class WidgetTreeNode {
         'semanticLabel',
         'semanticDescription',
       ]),
+      bounds: boundsById[id],
       children: children,
     );
   }
 
   final String id;
   final String label;
+  final WidgetBounds? bounds;
   final String? sourceLocation;
   final String? visibleText;
   final String? semanticInfo;
@@ -85,6 +91,7 @@ class WidgetTreeNode {
     return {
       'id': id,
       'label': label,
+      if (bounds != null) 'bounds': bounds!.toJson(),
       if (sourceLocation != null) 'sourceLocation': sourceLocation,
       if (visibleText != null) 'visibleText': visibleText,
       if (semanticInfo != null) 'semanticInfo': semanticInfo,
@@ -93,6 +100,30 @@ class WidgetTreeNode {
   }
 }
 
+/// Visual rectangle for a Flutter widget in device-screen coordinates.
+class WidgetBounds {
+  const WidgetBounds({
+    required this.x,
+    required this.y,
+    required this.width,
+    required this.height,
+  });
+
+  final double x;
+  final double y;
+  final double width;
+  final double height;
+
+  Map<String, Object?> toJson() {
+    return {
+      'x': x,
+      'y': y,
+      'width': width,
+      'height': height,
+    };
+  }
+}
+
 String? _sourceLocationFromDiagnostics(
   Map<String, Object?> diagnosticsNode, {
   required String? projectRoot,
diff --git a/apps/bridge/test/flutter_inspector_client_test.dart b/apps/bridge/test/flutter_inspector_client_test.dart
index 395e060..6538a0f 100644
--- a/apps/bridge/test/flutter_inspector_client_test.dart
+++ b/apps/bridge/test/flutter_inspector_client_test.dart
@@ -68,6 +68,14 @@ void main() {
             'fullDetails': 'true',
           },
         ),
+        const FlutterInspectorVmServiceCall(
+          method: 'ext.ask_ui.widgetBounds',
+          isolateId: 'isolates/main',
+          args: {
+            'id': 'inspector-1',
+            'groupName': 'ask_ui_widget_tree',
+          },
+        ),
       ]);
     });
 
@@ -96,6 +104,165 @@ void main() {
       });
     });
 
+    test('enriches widget tree nodes with app-side widget bounds', () async {
+      final vmService = RecordingFlutterInspectorVmService(
+        {
+          'result': {
+            'valueId': 'inspector-1',
+            'description': 'MaterialApp',
+            'children': [
+              {
+                'valueId': 'inspector-2',
+                'description': 'FilledButton',
+              },
+            ],
+          },
+        },
+        serviceExtensionResponses: {
+          'ext.ask_ui.widgetBounds': [
+            {
+              'result': {
+                'x': 4,
+                'y': 8,
+                'width': 120,
+                'height': 48,
+                'devicePixelRatio': 2.5,
+              },
+            },
+            {
+              'result':
+                  '{"x":24,"y":36,"width":80,"height":20,"devicePixelRatio":2.5}',
+            },
+          ],
+        },
+      );
+      final client = VmServiceFlutterInspectorClient(
+        vmServiceFactory: RecordingFlutterInspectorVmServiceFactory(vmService),
+      );
+
+      final root = await client.fetchRootWidgetTree(
+        BridgeSession(
+          id: 'session-1',
+          vmServiceUri: 'ws://127.0.0.1:12345/ws',
+          projectRoot: '/Users/example/app',
+          deviceId: '19271FDF6007TY',
+        ),
+      );
+
+      expect(root.toJson(), {
+        'id': 'inspector-1',
+        'label': 'MaterialApp',
+        'bounds': {
+          'x': 10.0,
+          'y': 20.0,
+          'width': 300.0,
+          'height': 120.0,
+        },
+        'children': [
+          {
+            'id': 'inspector-2',
+            'label': 'FilledButton',
+            'bounds': {
+              'x': 60.0,
+              'y': 90.0,
+              'width': 200.0,
+              'height': 50.0,
+            },
+            'children': <Object?>[],
+          },
+        ],
+      });
+      expect(vmService.calls, [
+        const FlutterInspectorVmServiceCall(
+          method: 'ext.flutter.inspector.setPubRootDirectories',
+          isolateId: 'isolates/main',
+          args: {'arg0': '/Users/example/app'},
+        ),
+        const FlutterInspectorVmServiceCall(
+          method: 'ext.flutter.inspector.getRootWidgetTree',
+          isolateId: 'isolates/main',
+          args: {
+            'groupName': 'ask_ui_widget_tree',
+            'isSummaryTree': 'true',
+            'withPreviews': 'true',
+            'fullDetails': 'true',
+          },
+        ),
+        const FlutterInspectorVmServiceCall(
+          method: 'ext.ask_ui.widgetBounds',
+          isolateId: 'isolates/main',
+          args: {
+            'id': 'inspector-1',
+            'groupName': 'ask_ui_widget_tree',
+          },
+        ),
+        const FlutterInspectorVmServiceCall(
+          method: 'ext.ask_ui.widgetBounds',
+          isolateId: 'isolates/main',
+          args: {
+            'id': 'inspector-2',
+            'groupName': 'ask_ui_widget_tree',
+          },
+        ),
+      ]);
+    });
+
+    test('keeps widget tree available when app-side bounds extension is absent',
+        () async {
+      final vmService = RecordingFlutterInspectorVmService({
+        'result': {
+          'valueId': 'inspector-1',
+          'description': 'MaterialApp',
+          'children': [
+            {
+              'valueId': 'inspector-2',
+              'description': 'Scaffold',
+            },
+          ],
+        },
+      }, unavailableServiceExtensions: {
+        'ext.ask_ui.widgetBounds'
+      });
+      final client = VmServiceFlutterInspectorClient(
+        vmServiceFactory: RecordingFlutterInspectorVmServiceFactory(vmService),
+      );
+
+      final root = await client.fetchRootWidgetTree(
+        BridgeSession(
+          id: 'session-1',
+          vmServiceUri: 'ws://127.0.0.1:12345/ws',
+          projectRoot: '/Users/example/app',
+          deviceId: '19271FDF6007TY',
+        ),
+      );
+
+      expect(root.toJson(), {
+        'id': 'inspector-1',
+        'label': 'MaterialApp',
+        'children': [
+          {
+            'id': 'inspector-2',
+            'label': 'Scaffold',
+            'children': <Object?>[],
+          },
+        ],
+      });
+      expect(
+        vmService.calls
+            .where((call) => call.method == 'ext.ask_ui.widgetBounds'),
+        [
+          const FlutterInspectorVmServiceCall(
+            method: 'ext.ask_ui.widgetBounds',
+            isolateId: 'isolates/main',
+            args: {
+              'id': 'inspector-1',
+              'groupName': 'ask_ui_widget_tree',
+            },
+          ),
+        ],
+      );
+    });
+
     test('sets Flutter Inspector select widget mode through inspector.show',
         () async {
       final vmService = RecordingFlutterInspectorVmService({'result': null});
@@ -239,9 +406,20 @@ class RecordingFlutterInspectorVmServiceFactory
 }
 
 class RecordingFlutterInspectorVmService implements FlutterInspectorVmService {
-  RecordingFlutterInspectorVmService(this.widgetTreeResponse);
+  RecordingFlutterInspectorVmService(
+    this.widgetTreeResponse, {
+    Map<String, List<Map<String, Object?>>> serviceExtensionResponses =
+        const {},
+    Set<String> unavailableServiceExtensions = const {},
+  })  : _serviceExtensionResponses = {
+          for (final entry in serviceExtensionResponses.entries)
+            entry.key: List<Map<String, Object?>>.of(entry.value),
+        },
+        _unavailableServiceExtensions = unavailableServiceExtensions;
 
   final Map<String, Object?> widgetTreeResponse;
+  final Map<String, List<Map<String, Object?>>> _serviceExtensionResponses;
+  final Set<String> _unavailableServiceExtensions;
   final calls = <FlutterInspectorVmServiceCall>[];
   final serviceExtensionStateListeners =
       <void Function(FlutterServiceExtensionStateChange change)>[];
@@ -269,6 +447,20 @@ class RecordingFlutterInspectorVmService implements FlutterInspectorVmService {
     if (method == 'ext.flutter.inspector.getRootWidgetTree') {
       return widgetTreeResponse;
     }
+    if (_unavailableServiceExtensions.contains(method)) {
+      throw const FlutterInspectorServiceUnavailableException(
+        'Service extension is not registered.',
+      );
+    }
+    final responses = _serviceExtensionResponses[method];
+    if (responses != null && responses.isNotEmpty) {
+      return responses.removeAt(0);
+    }
+    if (method == 'ext.ask_ui.widgetBounds') {
+      throw const FlutterInspectorServiceUnavailableException(
+        'Service extension is not registered.',
+      );
+    }
 
     return {'result': null};
   }
diff --git a/apps/bridge/test/widget_tree_snapshot_test.dart b/apps/bridge/test/widget_tree_snapshot_test.dart
index 65ddd33..93eaf24 100644
--- a/apps/bridge/test/widget_tree_snapshot_test.dart
+++ b/apps/bridge/test/widget_tree_snapshot_test.dart
@@ -78,5 +78,37 @@ void main() {
         },
       );
     });
+
+    test('normalizes app-side visual bounds by widget id', () {
+      final root = WidgetTreeNode.fromFlutterDiagnostics(
+        {
+          'valueId': 'inspector-1',
+          'description': 'Text',
+        },
+        boundsById: const {
+          'inspector-1': WidgetBounds(
+            x: 10.5,
+            y: 20,
+            width: 100,
+            height: 40,
+          ),
+        },
+      );
+
+      expect(
+        root.toJson(),
+        {
+          'id': 'inspector-1',
+          'label': 'Text',
+          'bounds': {
+            'x': 10.5,
+            'y': 20.0,
+            'width': 100.0,
+            'height': 40.0,
+          },
+          'children': <Object?>[],
+        },
+      );
+    });
   });
 }

From c62a20fcb177d5bbb50c98cdb64095ce13ed7430 Mon Sep 17 00:00:00 2001
From: drown0315 <drown0315@gmail.com>
Date: Thu, 9 Jul 2026 16:56:52 +0800
Subject: [PATCH 5/6] fix: place selection markers within widget bounds

---
 .../src/app/useWorkbenchSelectionComments.ts  | 13 +++-
 .../live-app-surface/DeviceShell.css          | 21 +++++
 .../live-app-surface/DeviceShell.tsx          | 54 +++++++++++++
 .../live-app-surface/LiveAppSurface.css       | 24 ------
 .../live-app-surface/LiveAppSurface.tsx       | 17 +---
 .../deviceViewGeometry.test.ts                | 57 ++++++++++++++
 .../live-app-surface/deviceViewGeometry.ts    | 68 ++++++++++++++++
 .../selectedWidgetTarget.test.ts              | 62 +++++++++++++++
 .../selectedWidgetTarget.ts                   | 41 +++++++++-
 .../selectionCommentAttachments.test.ts       | 77 ++++++++++++++++++-
 .../selectionCommentAttachments.ts            | 27 ++++---
 .../selectionCommentTypes.ts                  |  9 ++-
 apps/web/src/services/bridgeTypes.ts          |  6 ++
 apps/web/src/types/bridgeSession.ts           |  8 ++
 14 files changed, 429 insertions(+), 55 deletions(-)

diff --git a/apps/web/src/app/useWorkbenchSelectionComments.ts b/apps/web/src/app/useWorkbenchSelectionComments.ts
index 18e35cf..904b845 100644
--- a/apps/web/src/app/useWorkbenchSelectionComments.ts
+++ b/apps/web/src/app/useWorkbenchSelectionComments.ts
@@ -1,6 +1,7 @@
 import { useCallback, useMemo, useState } from 'react';
 import {
   getInitialSelectionCommentState,
+  getLocatableWidgetBoundsById,
   getLocatableWidgetIds,
   getSelectedWidgetTarget,
   getSelectionCommentAttachmentTokens,
@@ -45,6 +46,14 @@ export function useWorkbenchSelectionComments({
     return getLocatableWidgetIds(widgetTreeState.root);
   }, [widgetTreeState]);
 
+  const locatableWidgetBoundsById = useMemo(() => {
+    if (widgetTreeState.status !== 'loaded') {
+      return new Map();
+    }
+
+    return getLocatableWidgetBoundsById(widgetTreeState.root);
+  }, [widgetTreeState]);
+
   const attachmentTokens = useMemo(
     () =>
       getSelectionCommentAttachmentTokens(
@@ -58,10 +67,10 @@ export function useWorkbenchSelectionComments({
     () =>
       getSelectionCommentOverlayMarkers({
         isSelectWidgetActive,
-        locatableWidgetIds,
+        locatableWidgetBoundsById,
         state: selectionCommentState,
       }),
-    [isSelectWidgetActive, locatableWidgetIds, selectionCommentState],
+    [isSelectWidgetActive, locatableWidgetBoundsById, selectionCommentState],
   );
 
   const handleSelectedWidgetIdChange = useCallback((widgetId: string | null) => {
diff --git a/apps/web/src/components/live-app-surface/DeviceShell.css b/apps/web/src/components/live-app-surface/DeviceShell.css
index e62e699..1884252 100644
--- a/apps/web/src/components/live-app-surface/DeviceShell.css
+++ b/apps/web/src/components/live-app-surface/DeviceShell.css
@@ -59,6 +59,27 @@
   height: 100%;
 }
 
+.selection-marker-layer {
+  position: absolute;
+  inset: 0;
+  z-index: 3;
+  pointer-events: none;
+}
+
+.selection-marker {
+  position: absolute;
+  display: grid;
+  place-items: center;
+  border: 2px solid #ffffff;
+  border-radius: 999px;
+  background: var(--vue-green);
+  box-shadow: 0 8px 18px rgba(15, 23, 42, 0.22);
+  color: #ffffff;
+  font-size: 12px;
+  font-weight: 900;
+  line-height: 1;
+}
+
 .surface-controls {
   display: flex;
   align-items: center;
diff --git a/apps/web/src/components/live-app-surface/DeviceShell.tsx b/apps/web/src/components/live-app-surface/DeviceShell.tsx
index d96192c..c31e8d0 100644
--- a/apps/web/src/components/live-app-surface/DeviceShell.tsx
+++ b/apps/web/src/components/live-app-surface/DeviceShell.tsx
@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { PointerEvent } from 'react';
 import type { LiveAppSurfaceState } from '../../live-app-surface/liveAppSurfaceState';
+import type { SelectionCommentOverlayMarker } from '../../selection-comments/selectionCommentState';
 import {
   buildSystemKeyMessage,
   buildTouchMessage,
@@ -10,6 +11,7 @@ import {
 } from '../../live-app-surface/deviceControlProtocol';
 import {
   calculateDeviceViewFit,
+  getSelectionMarkerPlacement,
   mapPointToDeviceCoordinates,
   type DeviceViewFit,
 } from '../../live-app-surface/deviceViewGeometry';
@@ -30,8 +32,12 @@ type DeviceShellProps = {
     LiveAppSurfaceState,
     { status: 'waitingForVideo' | 'renderingVideo' }
   >;
+  overlayMarkers?: SelectionCommentOverlayMarker[];
 };
 
+const SELECTION_MARKER_SIZE = 26;
+const SELECTION_MARKER_PADDING = 4;
+
 /**
  * Renders the interactive Device View and Android Surface Controls.
  *
@@ -43,6 +49,7 @@ export function DeviceShell({
   isInputDisabled,
   onDeviceControlMessage,
   onDeviceVideoRendererChange,
+  overlayMarkers = [],
   surfaceState,
 }: DeviceShellProps) {
   const areaRef = useRef<HTMLDivElement | null>(null);
@@ -262,6 +269,30 @@ export function DeviceShell({
               className="device-view-canvas"
               ref={setCanvasElement}
             />
+            {overlayMarkers.length > 0 ? (
+              <div
+                aria-label="Selection Comment markers"
+                className="selection-marker-layer"
+              >
+                {getRenderableSelectionMarkers(overlayMarkers, fit).map(
+                  ({ marker, placement }) => (
+                    <div
+                      className="selection-marker"
+                      key={marker.id}
+                      style={{
+                        height: `${SELECTION_MARKER_SIZE}px`,
+                        left: `${placement.left}px`,
+                        top: `${placement.top}px`,
+                        width: `${SELECTION_MARKER_SIZE}px`,
+                      }}
+                      title={marker.widgetLabel}
+                    >
+                      {marker.number}
+                    </div>
+                  ),
+                )}
+              </div>
+            ) : null}
             {surfaceState.status === 'waitingForVideo' ? (
               <>
                 <div className="device-view-status">Waiting for video</div>
@@ -318,3 +349,26 @@ export function DeviceShell({
     </div>
   );
 }
+
+function getRenderableSelectionMarkers(
+  overlayMarkers: SelectionCommentOverlayMarker[],
+  fit: DeviceViewFit,
+) {
+  const markerCountsByWidgetId = new Map<string, number>();
+
+  return overlayMarkers.map((marker) => {
+    const markerIndexForWidget = markerCountsByWidgetId.get(marker.widgetId) ?? 0;
+    markerCountsByWidgetId.set(marker.widgetId, markerIndexForWidget + 1);
+
+    return {
+      marker,
+      placement: getSelectionMarkerPlacement({
+        bounds: marker.bounds,
+        fit,
+        markerIndexForWidget,
+        markerSize: SELECTION_MARKER_SIZE,
+        padding: SELECTION_MARKER_PADDING,
+      }),
+    };
+  });
+}
diff --git a/apps/web/src/components/live-app-surface/LiveAppSurface.css b/apps/web/src/components/live-app-surface/LiveAppSurface.css
index 655ab71..20a865a 100644
--- a/apps/web/src/components/live-app-surface/LiveAppSurface.css
+++ b/apps/web/src/components/live-app-surface/LiveAppSurface.css
@@ -221,27 +221,3 @@
   height: min(100%, 820px);
   min-height: 0;
 }
-
-.selection-marker-layer {
-  position: absolute;
-  inset: 10px 10px auto auto;
-  z-index: 3;
-  display: grid;
-  gap: 7px;
-  pointer-events: none;
-}
-
-.selection-marker {
-  display: grid;
-  place-items: center;
-  width: 26px;
-  height: 26px;
-  border: 2px solid #ffffff;
-  border-radius: 999px;
-  background: var(--vue-green);
-  box-shadow: 0 8px 18px rgba(15, 23, 42, 0.22);
-  color: #ffffff;
-  font-size: 12px;
-  font-weight: 900;
-  line-height: 1;
-}
diff --git a/apps/web/src/components/live-app-surface/LiveAppSurface.tsx b/apps/web/src/components/live-app-surface/LiveAppSurface.tsx
index 8b06e42..79fdcd8 100644
--- a/apps/web/src/components/live-app-surface/LiveAppSurface.tsx
+++ b/apps/web/src/components/live-app-surface/LiveAppSurface.tsx
@@ -45,24 +45,9 @@ export function LiveAppSurface({
             isInputDisabled={isInputDisabled}
             onDeviceControlMessage={onDeviceControlMessage}
             onDeviceVideoRendererChange={onDeviceVideoRendererChange}
+            overlayMarkers={overlayMarkers}
             surfaceState={surfaceState}
           />
-          {overlayMarkers.length > 0 ? (
-            <div
-              className="selection-marker-layer"
-              aria-label="Selection Comment markers"
-            >
-              {overlayMarkers.map((marker) => (
-                <div
-                  className="selection-marker"
-                  key={marker.id}
-                  title={marker.widgetLabel}
-                >
-                  {marker.number}
-                </div>
-              ))}
-            </div>
-          ) : null}
         </div>
       ) : surfaceState.status === 'waitingForVideo' ? (
         <div className="live-app-surface-waiting-stack">
diff --git a/apps/web/src/live-app-surface/deviceViewGeometry.test.ts b/apps/web/src/live-app-surface/deviceViewGeometry.test.ts
index b67e4a6..d5ac622 100644
--- a/apps/web/src/live-app-surface/deviceViewGeometry.test.ts
+++ b/apps/web/src/live-app-surface/deviceViewGeometry.test.ts
@@ -3,6 +3,7 @@ import test from 'node:test';
 
 import {
   calculateDeviceViewFit,
+  getSelectionMarkerPlacement,
   mapPointToDeviceCoordinates,
 } from './deviceViewGeometry.ts';
 
@@ -42,3 +43,59 @@ test('maps view points into metadata coordinates and rejects letterbox hits', ()
     y: 2400,
   });
 });
+
+test('places selection markers inside widget bounds in the rendered Device View frame', () => {
+  const fit = calculateDeviceViewFit({
+    screenWidth: 1080,
+    screenHeight: 2400,
+    maxWidth: 540,
+    maxHeight: 540,
+  });
+
+  assert.deepEqual(
+    getSelectionMarkerPlacement({
+      bounds: {
+        x: 100,
+        y: 400,
+        width: 600,
+        height: 120,
+      },
+      fit,
+      markerIndexForWidget: 0,
+      markerSize: 26,
+      padding: 4,
+    }),
+    {
+      left: 128,
+      top: 91,
+    },
+  );
+});
+
+test('clamps selection markers inside small widget bounds', () => {
+  const fit = calculateDeviceViewFit({
+    screenWidth: 100,
+    screenHeight: 100,
+    maxWidth: 100,
+    maxHeight: 100,
+  });
+
+  assert.deepEqual(
+    getSelectionMarkerPlacement({
+      bounds: {
+        x: 8,
+        y: 12,
+        width: 12,
+        height: 10,
+      },
+      fit,
+      markerIndexForWidget: 0,
+      markerSize: 26,
+      padding: 4,
+    }),
+    {
+      left: 1,
+      top: 4,
+    },
+  );
+});
diff --git a/apps/web/src/live-app-surface/deviceViewGeometry.ts b/apps/web/src/live-app-surface/deviceViewGeometry.ts
index e4ea6cc..00be4a0 100644
--- a/apps/web/src/live-app-surface/deviceViewGeometry.ts
+++ b/apps/web/src/live-app-surface/deviceViewGeometry.ts
@@ -24,6 +24,26 @@ export type DeviceCoordinates = {
   y: number;
 };
 
+export type DeviceBounds = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type SelectionMarkerPlacementInput = {
+  bounds: DeviceBounds;
+  fit: DeviceViewFit;
+  markerIndexForWidget: number;
+  markerSize: number;
+  padding: number;
+};
+
+export type SelectionMarkerPlacement = {
+  left: number;
+  top: number;
+};
+
 /**
  * Fit bridge-reported device metadata inside the available UI area.
  *
@@ -74,3 +94,51 @@ export function mapPointToDeviceCoordinates({
     y: localY / fit.scale,
   };
 }
+
+export function getSelectionMarkerPlacement({
+  bounds,
+  fit,
+  markerIndexForWidget,
+  markerSize,
+  padding,
+}: SelectionMarkerPlacementInput): SelectionMarkerPlacement {
+  const rect = {
+    left: bounds.x * fit.scale,
+    top: bounds.y * fit.scale,
+    width: bounds.width * fit.scale,
+    height: bounds.height * fit.scale,
+  };
+  const rectRight = rect.left + rect.width;
+  const rectBottom = rect.top + rect.height;
+  const markerOffset = markerIndexForWidget * (markerSize + padding);
+
+  const preferredLeft = rectRight - markerSize - padding - markerOffset;
+  const preferredTop = rect.top + padding;
+  const centeredLeft = rect.left + (rect.width - markerSize) / 2;
+  const centeredTop = rect.top + (rect.height - markerSize) / 2;
+
+  return {
+    left: Math.round(
+      clamp(
+        rect.width >= markerSize + padding * 2 ? preferredLeft : centeredLeft,
+        rect.left,
+        rectRight - markerSize,
+      ),
+    ),
+    top: Math.round(
+      clamp(
+        rect.height >= markerSize + padding * 2 ? preferredTop : centeredTop,
+        rect.top,
+        rectBottom - markerSize,
+      ),
+    ),
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  if (min > max) {
+    return (min + max) / 2;
+  }
+
+  return Math.min(Math.max(value, min), max);
+}
diff --git a/apps/web/src/selection-comments/selectedWidgetTarget.test.ts b/apps/web/src/selection-comments/selectedWidgetTarget.test.ts
index 8499e0b..a075054 100644
--- a/apps/web/src/selection-comments/selectedWidgetTarget.test.ts
+++ b/apps/web/src/selection-comments/selectedWidgetTarget.test.ts
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import {
+  getLocatableWidgetBoundsById,
   getLocatableWidgetIds,
   getSelectedWidgetTarget,
 } from './selectionCommentState.ts';
@@ -62,6 +63,67 @@ test('collects locatable widget ids from the current Widget Tree', () => {
   );
 });
 
+test('collects only valid widget bounds from the current Widget Tree', () => {
+  const root = {
+    id: 'root',
+    label: 'MaterialApp',
+    bounds: {
+      x: 0,
+      y: 0,
+      width: 300,
+      height: 600,
+    },
+    children: [
+      {
+        id: 'button',
+        label: 'PrimaryButton',
+        bounds: {
+          x: 20,
+          y: 40,
+          width: 120,
+          height: 44,
+        },
+        children: [],
+      },
+      {
+        id: 'stale',
+        label: 'StaleWidget',
+        bounds: {
+          x: 10,
+          y: 10,
+          width: 0,
+          height: 20,
+        },
+        children: [],
+      },
+    ],
+  } satisfies WidgetTreeNode;
+
+  assert.deepEqual(
+    getLocatableWidgetBoundsById(root),
+    new Map([
+      [
+        'root',
+        {
+          x: 0,
+          y: 0,
+          width: 300,
+          height: 600,
+        },
+      ],
+      [
+        'button',
+        {
+          x: 20,
+          y: 40,
+          width: 120,
+          height: 44,
+        },
+      ],
+    ]),
+  );
+});
+
 test('normalizes optional widget context fields before rendering', () => {
   const root = {
     id: 'root',
diff --git a/apps/web/src/selection-comments/selectedWidgetTarget.ts b/apps/web/src/selection-comments/selectedWidgetTarget.ts
index 0dca040..bd505be 100644
--- a/apps/web/src/selection-comments/selectedWidgetTarget.ts
+++ b/apps/web/src/selection-comments/selectedWidgetTarget.ts
@@ -1,4 +1,4 @@
-import type { WidgetTreeNode } from '../types/bridgeSession.ts';
+import type { WidgetBounds, WidgetTreeNode } from '../types/bridgeSession.ts';
 import type { SelectedWidgetTarget } from './selectionCommentTypes.ts';
 
 export function getSelectedWidgetTarget(
@@ -32,6 +32,16 @@ export function getLocatableWidgetIds(root: WidgetTreeNode): Set<string> {
   return locatableWidgetIds;
 }
 
+export function getLocatableWidgetBoundsById(
+  root: WidgetTreeNode,
+): Map<string, WidgetBounds> {
+  const boundsById = new Map<string, WidgetBounds>();
+
+  collectLocatableWidgetBounds(root, boundsById);
+
+  return boundsById;
+}
+
 function collectLocatableWidgetIds(
   node: WidgetTreeNode,
   locatableWidgetIds: Set<string>,
@@ -45,6 +55,35 @@ function collectLocatableWidgetIds(
   }
 }
 
+function collectLocatableWidgetBounds(
+  node: WidgetTreeNode,
+  boundsById: Map<string, WidgetBounds>,
+) {
+  if (isValidWidgetBounds(node.bounds)) {
+    boundsById.set(node.id, node.bounds);
+  }
+
+  const children = Array.isArray(node.children) ? node.children : [];
+
+  for (const child of children) {
+    collectLocatableWidgetBounds(child, boundsById);
+  }
+}
+
+function isValidWidgetBounds(
+  bounds: WidgetTreeNode['bounds'],
+): bounds is WidgetBounds {
+  return (
+    bounds !== undefined &&
+    Number.isFinite(bounds.x) &&
+    Number.isFinite(bounds.y) &&
+    Number.isFinite(bounds.width) &&
+    Number.isFinite(bounds.height) &&
+    bounds.width > 0 &&
+    bounds.height > 0
+  );
+}
+
 function stringifyWidgetContextValue(value: unknown): string | undefined {
   if (value === null || value === undefined) {
     return undefined;
diff --git a/apps/web/src/selection-comments/selectionCommentAttachments.test.ts b/apps/web/src/selection-comments/selectionCommentAttachments.test.ts
index 5f4a724..938a86f 100644
--- a/apps/web/src/selection-comments/selectionCommentAttachments.test.ts
+++ b/apps/web/src/selection-comments/selectionCommentAttachments.test.ts
@@ -77,7 +77,17 @@ test('keeps unavailable Attachment Tokens sendable while hiding stale overlay ma
   assert.deepEqual(
     getSelectionCommentOverlayMarkers({
       isSelectWidgetActive: true,
-      locatableWidgetIds: new Set(['widget-1']),
+      locatableWidgetBoundsById: new Map([
+        [
+          'widget-1',
+          {
+            x: 10,
+            y: 20,
+            width: 100,
+            height: 40,
+          },
+        ],
+      ]),
       state,
     }),
     [
@@ -86,6 +96,59 @@ test('keeps unavailable Attachment Tokens sendable while hiding stale overlay ma
         number: 1,
         widgetId: 'widget-1',
         widgetLabel: 'PrimaryButton',
+        bounds: {
+          x: 10,
+          y: 20,
+          width: 100,
+          height: 40,
+        },
+      },
+    ],
+  );
+});
+
+test('includes widget bounds on overlay markers and hides markers without bounds', () => {
+  const otherTarget: SelectedWidgetTarget = {
+    id: 'widget-2',
+    displayLabel: 'SecondaryButton',
+  };
+  let state: SelectionCommentState = {
+    comments: [],
+    draftsByWidgetId: {},
+    nextCommentId: 1,
+  };
+
+  state = addSelectionComment(state, target, 'Place this on the button');
+  state = addSelectionComment(state, otherTarget, 'No bounds');
+
+  assert.deepEqual(
+    getSelectionCommentOverlayMarkers({
+      isSelectWidgetActive: true,
+      locatableWidgetBoundsById: new Map([
+        [
+          'widget-1',
+          {
+            x: 10,
+            y: 20,
+            width: 100,
+            height: 40,
+          },
+        ],
+      ]),
+      state,
+    }),
+    [
+      {
+        id: 'selection-comment-1',
+        number: 1,
+        widgetId: 'widget-1',
+        widgetLabel: 'PrimaryButton',
+        bounds: {
+          x: 10,
+          y: 20,
+          width: 100,
+          height: 40,
+        },
       },
     ],
   );
@@ -103,7 +166,17 @@ test('hides overlay markers while Select Widget mode is off without clearing sta
   assert.deepEqual(
     getSelectionCommentOverlayMarkers({
       isSelectWidgetActive: false,
-      locatableWidgetIds: new Set(['widget-1']),
+      locatableWidgetBoundsById: new Map([
+        [
+          'widget-1',
+          {
+            x: 10,
+            y: 20,
+            width: 100,
+            height: 40,
+          },
+        ],
+      ]),
       state,
     }),
     [],
diff --git a/apps/web/src/selection-comments/selectionCommentAttachments.ts b/apps/web/src/selection-comments/selectionCommentAttachments.ts
index 90159f8..02f81d7 100644
--- a/apps/web/src/selection-comments/selectionCommentAttachments.ts
+++ b/apps/web/src/selection-comments/selectionCommentAttachments.ts
@@ -3,6 +3,7 @@ import type {
   SelectionCommentOverlayMarker,
   SelectionCommentState,
 } from './selectionCommentTypes.ts';
+import type { WidgetBounds } from '../types/bridgeSession.ts';
 
 export function getSelectionCommentAttachmentTokens(
   state: SelectionCommentState,
@@ -19,11 +20,11 @@ export function getSelectionCommentAttachmentTokens(
 
 export function getSelectionCommentOverlayMarkers({
   isSelectWidgetActive,
-  locatableWidgetIds,
+  locatableWidgetBoundsById,
   state,
 }: {
   isSelectWidgetActive: boolean;
-  locatableWidgetIds: ReadonlySet<string>;
+  locatableWidgetBoundsById: ReadonlyMap<string, WidgetBounds>;
   state: SelectionCommentState;
 }): SelectionCommentOverlayMarker[] {
   if (!isSelectWidgetActive) {
@@ -31,11 +32,19 @@ export function getSelectionCommentOverlayMarkers({
   }
 
   return state.comments
-    .map((comment, index) => ({
-      id: comment.id,
-      number: index + 1,
-      widgetId: comment.widgetId,
-      widgetLabel: comment.widgetLabel,
-    }))
-    .filter((marker) => locatableWidgetIds.has(marker.widgetId));
+    .map((comment, index) => {
+      const bounds = locatableWidgetBoundsById.get(comment.widgetId);
+      if (bounds === undefined) {
+        return null;
+      }
+
+      return {
+        id: comment.id,
+        number: index + 1,
+        widgetId: comment.widgetId,
+        widgetLabel: comment.widgetLabel,
+        bounds,
+      };
+    })
+    .filter((marker) => marker !== null);
 }
diff --git a/apps/web/src/selection-comments/selectionCommentTypes.ts b/apps/web/src/selection-comments/selectionCommentTypes.ts
index 63c4186..994bc3b 100644
--- a/apps/web/src/selection-comments/selectionCommentTypes.ts
+++ b/apps/web/src/selection-comments/selectionCommentTypes.ts
@@ -1,3 +1,5 @@
+import type { WidgetBounds } from '../types/bridgeSession.ts';
+
 export const SELECTION_COMMENT_TEXT_LIMIT = 1000;
 export const SELECTION_COMMENT_BATCH_LIMIT = 20;
 
@@ -150,7 +152,9 @@ export type SelectionCommentAttachmentToken = {
  * Numbered marker shown on the Live App Surface for a locatable comment.
  *
  * Markers are derived from staged comments while Select Widget mode is active.
- * They do not store geometry because placement belongs to the Live App Surface.
+ * They include current widget bounds so the Live App Surface can place the
+ * marker inside the selected widget highlight without persisting coordinates in
+ * the Selection Comment payload.
  *
  * Example:
  * A marker with number `2` and widget label `PrimaryButton` is shown only while
@@ -169,6 +173,9 @@ export type SelectionCommentOverlayMarker = {
 
   /** Widget label available for marker accessibility or debugging. */
   widgetLabel: string;
+
+  /** Current widget rectangle in device-screen coordinates. */
+  bounds: WidgetBounds;
 };
 
 /**
diff --git a/apps/web/src/services/bridgeTypes.ts b/apps/web/src/services/bridgeTypes.ts
index 2dad92c..f26a5cb 100644
--- a/apps/web/src/services/bridgeTypes.ts
+++ b/apps/web/src/services/bridgeTypes.ts
@@ -17,6 +17,12 @@ export type CreateBridgeSessionResponse = {
 export type WidgetTreeNodeResponse = {
   id: string;
   label: string;
+  bounds?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
   sourceLocation?: string;
   visibleText?: string;
   semanticInfo?: string;
diff --git a/apps/web/src/types/bridgeSession.ts b/apps/web/src/types/bridgeSession.ts
index 507a498..4d82317 100644
--- a/apps/web/src/types/bridgeSession.ts
+++ b/apps/web/src/types/bridgeSession.ts
@@ -1,6 +1,14 @@
+export type WidgetBounds = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
 export type WidgetTreeNode = {
   id: string;
   label: string;
+  bounds?: WidgetBounds;
   sourceLocation?: string;
   visibleText?: string;
   semanticInfo?: string;

From 5feded7de8b249c02115715b9daa9d93a633f107 Mon Sep 17 00:00:00 2001
From: drown0315 <drown0315@gmail.com>
Date: Thu, 9 Jul 2026 17:10:38 +0800
Subject: [PATCH 6/6] chore: document ask ui runtime bounds extension

---
 .../ask-ui-widget-bounds-extension.md         | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs_internal/ask-ui-widget-bounds-extension.md

diff --git a/docs_internal/ask-ui-widget-bounds-extension.md b/docs_internal/ask-ui-widget-bounds-extension.md
new file mode 100644
index 0000000..81f656e
--- /dev/null
+++ b/docs_internal/ask-ui-widget-bounds-extension.md
@@ -0,0 +1,57 @@
+# Ask UI Runtime Widget Bounds Extension
+
+Ask UI widget marker placement needs real Flutter render bounds, not Flutter
+Inspector tree JSON. Inspector JSON exposes widget ids and sizes in some layout
+views, but it does not expose each widget's global screen origin.
+
+Flutter apps should install `ask_ui_runtime` and register it before `runApp`.
+The runtime registers debug-only VM Service extensions used by the local Ask UI
+Bridge.
+
+## Install
+
+For local development, add a path dependency to the target Flutter app:
+
+```yaml
+dependencies:
+  ask_ui_runtime:
+    path: /path/to/ask_ui/packages/ask_ui_runtime
+```
+
+## Register
+
+```dart
+import 'package:ask_ui_runtime/ask_ui_runtime.dart';
+
+void main() {
+  registerAskUiRuntime();
+  runApp(const SmokeApp());
+}
+```
+
+`registerAskUiRuntime()` is wrapped in Dart assertions, so it registers only in
+debug builds and is tree-shaken from release builds.
+
+## Bridge Contract
+
+Bridge calls:
+
+```text
+ext.ask_ui.widgetBounds
+  id: inspector-11
+  groupName: ask_ui_widget_tree
+```
+
+The extension returns Flutter logical pixels plus `devicePixelRatio`. Bridge
+converts the rectangle to device-screen pixels before sending it to the web app.
+
+## Probe Command
+
+```bash
+cd apps/bridge
+dart run tool/inspect_widget_bounds.dart \
+  --vm-service-uri 'ws://127.0.0.1:52051/rIfSxeErFAs=/ws' \
+  --project-root '/Users/drown/flutter_project/flutter_pilot/examples/smoke_app' \
+  --group-name ask_ui_widget_tree \
+  --widget-id inspector-11
+```