fix(comment): keep pins glued to their element across iframe scroll

Root cause: overlay.ts captured getBoundingClientRect() once at click time
and sent viewport-relative coords to the parent. The PinOverlay sits outside
the iframe and has no way to observe iframe-internal scroll, so the pin
stayed at the old viewport coordinates while the selected element moved
with the scrolled content.

Fix: iframe becomes the source of truth for rect.
  - New WATCH_SELECTORS message (parent→iframe) registers the selectors
    the parent cares about for the current design/snapshot.
  - New ELEMENT_RECTS message (iframe→parent) broadcasts current rects
    on scroll/resize, rAF-coalesced so bursts collapse into one post.
  - Parent stores a liveRects map keyed by selector; PinOverlay and the
    CommentBubble prefer it over the stored rect when present.
  - Freshly-pinned elements auto-add themselves to the iframe's watch
    list so scroll tracking works before the parent round-trip lands.

DB schema untouched — stored rect is still the initial value before the
iframe broadcasts its first update. liveRects is cleared on design switch.

Test coverage: overlay rAF coalescing, scroll re-broadcast, selector
resolution fallbacks, ELEMENT_RECTS handler validation, store merge/clear
semantics, PinOverlay rendering with live rect override.

Author: hqhq1025

apps/desktop/src/renderer/src/components/PreviewPane.test.ts

@@ -48,6 +48,7 @@ describe('handlePreviewMessage trust boundary', () => {
     return {
       onElementSelected: vi.fn(),
       onIframeError: vi.fn(),
+      onElementRects: vi.fn(),
     };
   }
 
@@ -112,6 +113,42 @@ describe('handlePreviewMessage trust boundary', () => {
     expect(errorOutcome).toEqual({ status: 'handled', type: 'IFRAME_ERROR' });
     expect(handlers.onIframeError).toHaveBeenCalledOnce();
   });
+
+  it('accepts well-formed ELEMENT_RECTS payloads and forwards entries', () => {
+    const handlers = makeHandlers();
+    const outcome = handlePreviewMessage(
+      {
+        __codesign: true,
+        type: 'ELEMENT_RECTS',
+        entries: [
+          { selector: '#a', rect: { top: 10, left: 20, width: 30, height: 40 } },
+          { selector: '[data-codesign-id="x"]', rect: { top: 1, left: 2, width: 3, height: 4 } },
+        ],
+      },
+      handlers,
+    );
+    expect(outcome).toEqual({ status: 'handled', type: 'ELEMENT_RECTS' });
+    expect(handlers.onElementRects).toHaveBeenCalledOnce();
+    const payload = handlers.onElementRects.mock.calls[0]?.[0] as {
+      entries: Array<{ selector: string }>;
+    };
+    expect(payload.entries).toHaveLength(2);
+    expect(payload.entries[0]?.selector).toBe('#a');
+  });
+
+  it('rejects ELEMENT_RECTS with a malformed rect entry', () => {
+    const handlers = makeHandlers();
+    const outcome = handlePreviewMessage(
+      {
+        __codesign: true,
+        type: 'ELEMENT_RECTS',
+        entries: [{ selector: '#bad', rect: { top: 'NaN' } }],
+      },
+      handlers,
+    );
+    expect(outcome.status).toBe('rejected');
+    expect(handlers.onElementRects).not.toHaveBeenCalled();
+  });
 });
 
 describe('postModeToPreviewWindow', () => {

apps/desktop/src/renderer/src/components/PreviewPane.tsx

@@ -1,8 +1,10 @@
 import { useT } from '@open-codesign/i18n';
 import {
+  type ElementRectsMessage,
   type IframeErrorMessage,
   type OverlayMessage,
   buildSrcdoc,
+  isElementRectsMessage,
   isIframeErrorMessage,
   isOverlayMessage,
 } from '@open-codesign/runtime';
@@ -69,11 +71,12 @@ export function scaleRectForZoom(
   };
 }
 
-export type AllowedPreviewMessageType = 'ELEMENT_SELECTED' | 'IFRAME_ERROR';
+export type AllowedPreviewMessageType = 'ELEMENT_SELECTED' | 'IFRAME_ERROR' | 'ELEMENT_RECTS';
 
 export interface PreviewMessageHandlers {
   onElementSelected: (msg: OverlayMessage) => void;
   onIframeError: (msg: IframeErrorMessage) => void;
+  onElementRects: (msg: ElementRectsMessage) => void;
 }
 
 export type PreviewMessageOutcome =
@@ -105,6 +108,12 @@ export function handlePreviewMessage(
         return { status: 'handled', type: 'IFRAME_ERROR' };
       }
       return { status: 'rejected', reason: 'shape', type: envelope.type };
+    case 'ELEMENT_RECTS':
+      if (isElementRectsMessage(data)) {
+        handlers.onElementRects(data);
+        return { status: 'handled', type: 'ELEMENT_RECTS' };
+      }
+      return { status: 'rejected', reason: 'shape', type: envelope.type };
     default:
       return { status: 'rejected', reason: 'unknown-type', type: envelope.type };
   }
@@ -276,6 +285,9 @@ export function PreviewPane({ onPickStarter }: PreviewPaneProps) {
   const openCommentBubble = useCodesignStore((s) => s.openCommentBubble);
   const closeCommentBubble = useCodesignStore((s) => s.closeCommentBubble);
   const addComment = useCodesignStore((s) => s.addComment);
+  const applyLiveRects = useCodesignStore((s) => s.applyLiveRects);
+  const clearLiveRects = useCodesignStore((s) => s.clearLiveRects);
+  const liveRects = useCodesignStore((s) => s.liveRects);
 
   // Active iframe ref consumed by TweakPanel (postMessage target) and by the
   // window.message guard. We re-point this whenever the active design changes
@@ -304,7 +316,35 @@ export function PreviewPane({ onPickStarter }: PreviewPaneProps) {
     if (el) {
       postModeToPreviewWindow(el.contentWindow, interactionMode, pushIframeError);
     }
-  }, [currentDesignId, interactionMode, pushIframeError]);
+    // New iframe / new design → liveRects from the old one are stale.
+    clearLiveRects();
+  }, [currentDesignId, interactionMode, pushIframeError, clearLiveRects]);
+
+  // Tell the sandbox which selectors to track. The sandbox re-measures each
+  // on scroll/resize and broadcasts ELEMENT_RECTS; we merge into liveRects.
+  // Selectors: all comments on the current snapshot + the active bubble's
+  // selector (usually the freshly-pinned one, included for the moment
+  // between click and save).
+  // biome-ignore lint/correctness/useExhaustiveDependencies: currentDesignId is intentional — iframeRef.current is a ref so biome can't see that it changes with the active design. When the design switches we MUST resend WATCH_SELECTORS to the newly-active iframe; the currentDesignId dependency is what triggers that re-run.
+  useEffect(() => {
+    const win = iframeRef.current?.contentWindow;
+    if (!win) return;
+    const selectors = new Set<string>();
+    if (currentSnapshotId) {
+      for (const c of comments) {
+        if (c.snapshotId === currentSnapshotId) selectors.add(c.selector);
+      }
+    }
+    if (commentBubble) selectors.add(commentBubble.selector);
+    try {
+      win.postMessage(
+        { __codesign: true, type: 'WATCH_SELECTORS', selectors: Array.from(selectors) },
+        '*',
+      );
+    } catch {
+      /* sandbox gone — retry happens next render */
+    }
+  }, [comments, currentSnapshotId, commentBubble, currentDesignId]);
 
   useEffect(() => {
     function onMessage(event: MessageEvent): void {
@@ -334,6 +374,9 @@ export function PreviewPane({ onPickStarter }: PreviewPaneProps) {
         },
         onIframeError: (msg) =>
           pushIframeError(formatIframeError(msg.kind, msg.message, msg.source, msg.lineno)),
+        onElementRects: (msg) => {
+          applyLiveRects(msg.entries);
+        },
       });
 
       if (outcome.status === 'rejected' && outcome.reason === 'unknown-type') {
@@ -343,7 +386,7 @@ export function PreviewPane({ onPickStarter }: PreviewPaneProps) {
 
     window.addEventListener('message', onMessage);
     return () => window.removeEventListener('message', onMessage);
-  }, [pushIframeError, selectCanvasElement, openCommentBubble, previewZoom]);
+  }, [pushIframeError, selectCanvasElement, openCommentBubble, previewZoom, applyLiveRects]);
 
   // Pool entries: active design first (using the freshest in-memory
   // previewHtml), then any other recently-visited designs that still have a
@@ -379,21 +422,23 @@ export function PreviewPane({ onPickStarter }: PreviewPaneProps) {
     <PinOverlay
       comments={snapshotComments}
       zoom={previewZoom}
-      onPinClick={(c) =>
+      liveRects={liveRects}
+      onPinClick={(c) => {
+        const live = liveRects[c.selector] ?? c.rect;
         openCommentBubble({
           selector: c.selector,
           tag: c.tag,
           outerHTML: c.outerHTML,
           rect: {
-            top: c.rect.top * (previewZoom / 100),
-            left: c.rect.left * (previewZoom / 100),
-            width: c.rect.width * (previewZoom / 100),
-            height: c.rect.height * (previewZoom / 100),
+            top: live.top * (previewZoom / 100),
+            left: live.left * (previewZoom / 100),
+            width: live.width * (previewZoom / 100),
+            height: live.height * (previewZoom / 100),
           },
           existingCommentId: c.id,
           initialText: c.text,
-        })
-      }
+        });
+      }}
     />
   );
 
@@ -481,54 +526,67 @@ export function PreviewPane({ onPickStarter }: PreviewPaneProps) {
           {body}
           {previewHtml ? <TweakPanel iframeRef={iframeRef} /> : null}
         </div>
-        {commentBubble && interactionMode === 'comment' ? (
-          <CommentBubble
-            key={commentBubble.selector}
-            selector={commentBubble.selector}
-            tag={commentBubble.tag}
-            outerHTML={commentBubble.outerHTML}
-            rect={commentBubble.rect}
-            {...(commentBubble.initialText !== undefined
-              ? { initialText: commentBubble.initialText }
-              : {})}
-            onClose={() => {
-              const win = iframeRef.current?.contentWindow;
-              if (win) {
-                try {
-                  win.postMessage({ __codesign: true, type: 'CLEAR_PIN' }, '*');
-                } catch {
-                  /* noop */
-                }
-              }
-              closeCommentBubble();
-            }}
-            onSendToClaude={async (text: string) => {
-              await addComment({
-                kind: 'edit',
-                selector: commentBubble.selector,
-                tag: commentBubble.tag,
-                outerHTML: commentBubble.outerHTML,
-                rect: commentBubble.rect,
-                text,
-                scope: 'element',
-                ...(commentBubble.parentOuterHTML
-                  ? { parentOuterHTML: commentBubble.parentOuterHTML }
-                  : {}),
-              });
-              const win = iframeRef.current?.contentWindow;
-              if (win) {
-                try {
-                  win.postMessage({ __codesign: true, type: 'CLEAR_PIN' }, '*');
-                } catch {
-                  /* noop */
-                }
-              }
-              closeCommentBubble();
-              // Stage only — user clicks the "Apply" button on the chip bar
-              // to send all accumulated edits in one go.
-            }}
-          />
-        ) : null}
+        {commentBubble && interactionMode === 'comment'
+          ? (() => {
+              const liveForBubble = liveRects[commentBubble.selector];
+              const scaled = liveForBubble
+                ? {
+                    top: liveForBubble.top * (previewZoom / 100),
+                    left: liveForBubble.left * (previewZoom / 100),
+                    width: liveForBubble.width * (previewZoom / 100),
+                    height: liveForBubble.height * (previewZoom / 100),
+                  }
+                : commentBubble.rect;
+              return (
+                <CommentBubble
+                  key={commentBubble.selector}
+                  selector={commentBubble.selector}
+                  tag={commentBubble.tag}
+                  outerHTML={commentBubble.outerHTML}
+                  rect={scaled}
+                  {...(commentBubble.initialText !== undefined
+                    ? { initialText: commentBubble.initialText }
+                    : {})}
+                  onClose={() => {
+                    const win = iframeRef.current?.contentWindow;
+                    if (win) {
+                      try {
+                        win.postMessage({ __codesign: true, type: 'CLEAR_PIN' }, '*');
+                      } catch {
+                        /* noop */
+                      }
+                    }
+                    closeCommentBubble();
+                  }}
+                  onSendToClaude={async (text: string) => {
+                    await addComment({
+                      kind: 'edit',
+                      selector: commentBubble.selector,
+                      tag: commentBubble.tag,
+                      outerHTML: commentBubble.outerHTML,
+                      rect: commentBubble.rect,
+                      text,
+                      scope: 'element',
+                      ...(commentBubble.parentOuterHTML
+                        ? { parentOuterHTML: commentBubble.parentOuterHTML }
+                        : {}),
+                    });
+                    const win = iframeRef.current?.contentWindow;
+                    if (win) {
+                      try {
+                        win.postMessage({ __codesign: true, type: 'CLEAR_PIN' }, '*');
+                      } catch {
+                        /* noop */
+                      }
+                    }
+                    closeCommentBubble();
+                    // Stage only — user clicks the "Apply" button on the chip bar
+                    // to send all accumulated edits in one go.
+                  }}
+                />
+              );
+            })()
+          : null}
       </div>
     </div>
   );

apps/desktop/src/renderer/src/components/comment/PinOverlay.test.tsx

@@ -1,6 +1,6 @@
 import type { CommentRow } from '@open-codesign/shared';
 import { describe, expect, it } from 'vitest';
-import { pinStyle, variantFor } from './PinOverlay';
+import { pinStyle, pinStyleFromRect, variantFor } from './PinOverlay';
 
 function comment(overrides: Partial<CommentRow> = {}): CommentRow {
   return {
@@ -50,4 +50,12 @@ describe('pinStyle', () => {
     // scale = 0.5; top = 100*0.5 - 10 = 40; left = 50*0.5 + 80*0.5 - 10 = 55
     expect(pos).toEqual({ top: '40px', left: '55px' });
   });
+
+  it('pinStyleFromRect uses the supplied rect instead of the stored one', () => {
+    // This is the path PinOverlay takes when liveRects has an entry for the
+    // comment's selector: the badge stays glued to the element's current
+    // position in the iframe viewport, even after the user scrolls.
+    const live = pinStyleFromRect({ top: 10, left: 5, width: 80, height: 40 }, 100);
+    expect(live).toEqual({ top: '0px', left: '75px' });
+  });
 });

apps/desktop/src/renderer/src/components/comment/PinOverlay.tsx

@@ -1,5 +1,5 @@
 import { useT } from '@open-codesign/i18n';
-import type { CommentRow } from '@open-codesign/shared';
+import type { CommentRect, CommentRow } from '@open-codesign/shared';
 
 export interface PinOverlayProps {
   /** Comments filtered to the currently-viewed snapshot. */
@@ -8,6 +8,10 @@ export interface PinOverlayProps {
   zoom: number;
   /** Called when a pin is clicked; opens the CommentBubble anchored at its rect. */
   onPinClick: (comment: CommentRow) => void;
+  /** Live, iframe-viewport-relative rects by selector. When present for a
+   *  comment's selector, it overrides the stored rect — this is how pins
+   *  stay glued to their element across iframe scroll/resize. Unscaled. */
+  liveRects?: Record<string, CommentRect>;
 }
 
 export interface PinVariant {
@@ -47,24 +51,29 @@ export function variantFor(comment: CommentRow): PinVariant {
   };
 }
 
-export function pinStyle(comment: CommentRow, zoom: number): { top: string; left: string } {
+export function pinStyleFromRect(rect: CommentRect, zoom: number): { top: string; left: string } {
   const scale = zoom / 100;
   // Position pin at the outer top-right corner: half-overlapping the corner
   // so it reads as a "badge" attached to the element rather than floating
   // randomly. Pin is 20px, so offset by -10 = half outside.
-  const top = comment.rect.top * scale - 10;
-  const left = comment.rect.left * scale + comment.rect.width * scale - 10;
+  const top = rect.top * scale - 10;
+  const left = rect.left * scale + rect.width * scale - 10;
   return { top: `${top}px`, left: `${left}px` };
 }
 
-export function PinOverlay({ comments, zoom, onPinClick }: PinOverlayProps) {
+export function pinStyle(comment: CommentRow, zoom: number): { top: string; left: string } {
+  return pinStyleFromRect(comment.rect, zoom);
+}
+
+export function PinOverlay({ comments, zoom, onPinClick, liveRects }: PinOverlayProps) {
   const t = useT();
   if (comments.length === 0) return null;
   return (
     <div className="pointer-events-none absolute inset-0 z-[5]">
       {comments.map((comment, index) => {
         const v = variantFor(comment);
-        const pos = pinStyle(comment, zoom);
+        const rect = liveRects?.[comment.selector] ?? comment.rect;
+        const pos = pinStyleFromRect(rect, zoom);
         const label =
           comment.kind === 'note'
             ? t('pinOverlay.note', { n: index + 1 })