fix(annotation): read mark bounds in frame layout space, not the scaled client rect

Full-matrix runtime verification of #6361 surfaced a third coordinate
seam: in a fit-to-window scaled device frame (tablet/mobile preview in a
narrow window) the structured annotation bounds were read from
canvas.getBoundingClientRect(), which reports the on-screen size after
the ancestor transform: scale(). The composited screenshot paints marks
across the snapshot's artifact-local dimensions, so the PNG showed the
right region while the structured position sent to the agent was shrunk
by the fit scale — measured 0.42x: a mark on a 784px-wide band went out
as a 330px rect at the wrong offset.

Bounds now derive from the canvas layout box (offsetWidth/Height, the
same source the canvas is sized from and the anchor pass measures
against), with the client rect kept only as a fallback for environments
without layout metrics. Text-label bounds divide their client-space
offsets by the live scale for the same reason.

Verified against a live tools-dev runtime driving the real UI: box marks,
pen strokes at all four preview edges, sidebar collapsed/expanded, and a
0.42x-scaled tablet frame — the decoded screenshot's painted mark, the
structured bounds, and the pointer-targeted band now agree within 2px in
every case, at DPR 1 and 2.

Refs #6361

Author: linghaoSu

apps/web/src/components/PreviewDrawOverlay.tsx

@@ -956,9 +956,26 @@ export function PreviewDrawOverlay({
     bumpLayoutRevision();
   }, [active, redraw]);
 
+  // Bounds read for the annotation payload must be in the frame's *layout*
+  // space (offsetWidth/Height), matching the snapshot the marks are composited
+  // onto. In a scaled tablet/phone device frame getBoundingClientRect() returns
+  // the on-screen (transform-scaled) size, which shrank the structured bounds
+  // by the fit scale while the painted PNG stayed artifact-local (#6361).
+  function canvasLayoutSize(): { width: number; height: number } | null {
+    const cvs = canvasRef.current;
+    if (!cvs) return null;
+    // offsetWidth/Height are the untransformed layout size. Fall back to the
+    // client rect when layout metrics are unavailable (detached node, JSDOM) —
+    // in an unscaled frame the two agree.
+    const width = cvs.offsetWidth > 0 ? cvs.offsetWidth : cvs.getBoundingClientRect().width;
+    const height = cvs.offsetHeight > 0 ? cvs.offsetHeight : cvs.getBoundingClientRect().height;
+    if (width <= 0 || height <= 0) return null;
+    return { width, height };
+  }
+
   function normalizedRectToCanvasRect(box: NormalizedRect): Rect | null {
-    const rect = canvasRef.current?.getBoundingClientRect();
-    if (!rect || rect.width <= 0 || rect.height <= 0) return null;
+    const rect = canvasLayoutSize();
+    if (!rect) return null;
     return {
       x: box.x * rect.width,
       y: box.y * rect.height,
@@ -990,9 +1007,9 @@ export function PreviewDrawOverlay({
   }
 
   function strokeRect(stroke: Stroke | null | undefined): Rect | null {
-    const rect = canvasRef.current?.getBoundingClientRect();
+    const rect = canvasLayoutSize();
     const points = stroke?.points ?? [];
-    if (!rect || rect.width <= 0 || rect.height <= 0 || points.length === 0) return null;
+    if (!rect || points.length === 0) return null;
     const xs = points.map((point) => point.x * rect.width);
     const ys = points.map((point) => point.y * rect.height);
     const minX = Math.min(...xs);
@@ -1009,25 +1026,31 @@ export function PreviewDrawOverlay({
   }
 
   function textBounds(): { x: number; y: number; width: number; height: number } | null {
-    const rect = canvasRef.current?.getBoundingClientRect();
-    if (!rect || rect.width <= 0 || rect.height <= 0) return null;
+    const layout = canvasLayoutSize();
+    const client = canvasRef.current?.getBoundingClientRect();
+    if (!layout || !client || client.width <= 0 || client.height <= 0) return null;
+    // Client-space offsets shrink under a device-frame `transform: scale()`;
+    // divide by the live scale so label boxes land in layout space like every
+    // other bounds source (#6361).
+    const scaleX = client.width / layout.width;
+    const scaleY = client.height / layout.height;
     const rects: { left: number; top: number; right: number; bottom: number }[] = [];
     for (const mark of textMarksRef.current) {
       if (mark.text.trim().length === 0) continue;
       const el = textAreaRefs.current.get(mark.id);
       if (el) {
         const box = el.getBoundingClientRect();
         rects.push({
-          left: box.left - rect.left,
-          top: box.top - rect.top,
-          right: box.right - rect.left,
-          bottom: box.bottom - rect.top,
+          left: (box.left - client.left) / scaleX,
+          top: (box.top - client.top) / scaleY,
+          right: (box.right - client.left) / scaleX,
+          bottom: (box.bottom - client.top) / scaleY,
         });
       } else {
         // No live element (e.g. capture path measured after unmount): fall back
         // to the drop point so the label still contributes to the crop bounds.
-        const left = mark.x * rect.width;
-        const top = mark.y * rect.height;
+        const left = mark.x * layout.width;
+        const top = mark.y * layout.height;
         rects.push({ left, top, right: left + 1, bottom: top + 1 });
       }
     }

apps/web/tests/components/PreviewDrawOverlay.scaled-frame-bounds.test.tsx

@@ -0,0 +1,119 @@
+// @vitest-environment jsdom
+
+import { fireEvent, render, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PreviewDrawOverlay } from '../../src/components/PreviewDrawOverlay';
+
+// In a scaled tablet/phone device frame the overlay lives inside a
+// `transform: scale()` shell: getBoundingClientRect() reports the on-screen
+// (scaled) size while offsetWidth/Height keep the untransformed layout size.
+// The structured annotation bounds must be layout-space — the same space the
+// composited screenshot uses — or the agent receives a rect shrunk by the fit
+// scale while the painted mark stays artifact-local (#6361).
+describe('PreviewDrawOverlay scaled device frame bounds', () => {
+  function installImageCompositeMocks() {
+    const originalImage = globalThis.Image;
+    class MockImage {
+      onload: (() => void) | null = null;
+      onerror: (() => void) | null = null;
+      set src(_value: string) {
+        window.setTimeout(() => this.onload?.(), 0);
+      }
+    }
+    Object.defineProperty(globalThis, 'Image', {
+      configurable: true,
+      value: MockImage,
+      writable: true,
+    });
+    const getContext = vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockImplementation((() => ({
+      beginPath: vi.fn(),
+      clearRect: vi.fn(),
+      drawImage: vi.fn(),
+      fillRect: vi.fn(),
+      fillText: vi.fn(),
+      lineCap: 'round',
+      lineJoin: 'round',
+      lineTo: vi.fn(),
+      lineWidth: 1,
+      measureText: vi.fn(() => ({ width: 10 })),
+      moveTo: vi.fn(),
+      restore: vi.fn(),
+      save: vi.fn(),
+      scale: vi.fn(),
+      setLineDash: vi.fn(),
+      stroke: vi.fn(),
+      strokeRect: vi.fn(),
+      strokeStyle: '',
+      fillStyle: '',
+      font: '',
+    })) as unknown as typeof HTMLCanvasElement.prototype.getContext);
+    const toBlob = vi
+      .spyOn(HTMLCanvasElement.prototype, 'toBlob')
+      .mockImplementation((callback: BlobCallback) => callback(new Blob(['png'], { type: 'image/png' })));
+    return () => {
+      Object.defineProperty(globalThis, 'Image', {
+        configurable: true,
+        value: originalImage,
+        writable: true,
+      });
+      getContext.mockRestore();
+      toBlob.mockRestore();
+    };
+  }
+
+  it('sends layout-space bounds when the frame is fit-to-window scaled', async () => {
+    const restoreCompositeMocks = installImageCompositeMocks();
+    const annotation = vi.fn((event: Event) => {
+      const detail = (event as CustomEvent<{ ack?: (result: { ok: boolean }) => void }>).detail;
+      detail.ack?.({ ok: true });
+    });
+    window.addEventListener('opendesign:annotation', annotation);
+
+    try {
+      const { container, getByRole } = render(
+        <PreviewDrawOverlay
+          active
+          captureViewport
+          captureSnapshot={async () => ({ dataUrl: 'data:image/png;base64,cG5n', w: 820, h: 1180 })}
+        >
+          <div style={{ width: 320, height: 200 }} />
+        </PreviewDrawOverlay>,
+      );
+
+      const canvas = container.querySelector<HTMLCanvasElement>('canvas')!;
+      // Layout box: full 820×1180 device frame. On-screen rect: scaled to 42%.
+      Object.defineProperty(canvas, 'offsetWidth', { configurable: true, get: () => 820 });
+      Object.defineProperty(canvas, 'offsetHeight', { configurable: true, get: () => 1180 });
+      canvas.getBoundingClientRect = () =>
+        ({
+          x: 0, y: 0, left: 0, top: 0,
+          right: 820 * 0.42, bottom: 1180 * 0.42,
+          width: 820 * 0.42, height: 1180 * 0.42,
+          toJSON: () => ({}),
+        }) as DOMRect;
+
+      // Draw a box over the middle of the *on-screen* frame: client px are
+      // scaled, so the normalized fractions are what a real pointer produces.
+      fireEvent.pointerDown(canvas, { clientX: 0.42 * 100, clientY: 0.42 * 300, pointerId: 1 });
+      fireEvent.pointerMove(canvas, { clientX: 0.42 * 500, clientY: 0.42 * 400, pointerId: 1 });
+      fireEvent.pointerUp(canvas, { clientX: 0.42 * 500, clientY: 0.42 * 400, pointerId: 1 });
+
+      fireEvent.click(getByRole('button', { name: 'Send' }));
+
+      await waitFor(() => expect(annotation).toHaveBeenCalledTimes(1));
+      const detail = (annotation.mock.calls[0]?.[0] as CustomEvent).detail as {
+        bounds?: { x: number; y: number; width: number; height: number };
+      };
+      // Layout-space expectation: fractions × layout size (not × scaled rect).
+      expect(detail.bounds).toBeDefined();
+      expect(detail.bounds!.x).toBeCloseTo(100, 0);
+      expect(detail.bounds!.y).toBeCloseTo(300, 0);
+      expect(detail.bounds!.width).toBeCloseTo(400, 0);
+      expect(detail.bounds!.height).toBeCloseTo(100, 0);
+    } finally {
+      window.removeEventListener('opendesign:annotation', annotation);
+      restoreCompositeMocks();
+    }
+  });
+});