From 4be3ea82d0007b589040c45ce9813503ded13ccc Mon Sep 17 00:00:00 2001
From: ravirajsinh45 <ravirajsinhdabhi86@gmail.com>
Date: Wed, 5 Aug 2026 16:40:18 +0530
Subject: [PATCH 1/4] fix(web): pin image annotations to the picture, not the
 letterboxed box
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drawings on images were authored and replayed against the full container
box rather than the picture inside it. `use-drawing` sized the Fabric
canvas from the parent container, stored that size as
`_canvasWidth`/`_canvasHeight`, and `AnnotationOverlay` rescaled by a
plain per-axis ratio on display. That rescale is only correct when the
display container has the same aspect ratio as the authoring one, so any
change of shape (sidebar collapsed vs expanded, a resized window, a
compare pane, a share link) both stretched the drawing and moved the
picture underneath it.

Measured in a browser: a 3:1 image annotated at 25% down the picture in
a 900x500 viewer, reopened at 400x700, put the mark at -29% — 54% of the
image height adrift and off the picture entirely. Through the new
constraint it lands at 25% exactly.

Video never had this bug; `VideoFrameConstraint` already fits the overlay
to the rendered video box. This is the image counterpart, but it cannot
be a copy. `<video>` is `w-full h-full object-contain`, so it fills its
container and the contain fit can be derived from the container. Images
are `max-w-full max-h-full`, and `max-*` only ever shrinks, so an image
smaller than its container renders at natural size rather than scaling
up. Deriving the box from the container upscales it in that case —
verified: a 100x200 image in an 800x400 box really occupies 100x200 at
(350,100), where container-derived math claims 200x400 at (300,0).

`renderedImageBox` therefore runs the contain fit inside the element's
own box and offsets by where that element sits, which is correct for
both patterns. It reads offset* rather than a client rect because this
renders inside react-zoom-pan-pinch's transform, where a client rect
would fold in the zoom matrix.

Applied to all four surfaces that show image annotations: the single
viewer (which also covers the folder share viewer, since that routes
through ImageViewer), both side-by-side compare panes, and the wipe
view. Wipe is not optional — once authoring moves to image space, a
viewer left in container space becomes newly wrong rather than merely
inconsistent.

`AnnotationOverlay` and `AnnotationCanvas` are unchanged: both size
themselves from their parent, so mounting them inside the constraint is
the whole mechanism.

Note for existing data: image annotations saved before this change were
only ever correct in the exact container they were drawn in, and are now
interpreted in image space, so they will shift.

Closes #185
---
 CHANGELOG.md                                  |   3 +
 .../__tests__/image-frame-constraint.test.tsx | 123 ++++++++++++++++++
 .../image-viewer-annotation-frame.test.tsx    |  98 ++++++++++++++
 .../__tests__/compare-overlay.test.tsx        |  63 ++++++++-
 .../compare/__tests__/wipe-viewer.test.tsx    |  92 ++++++++++++-
 .../review/compare/compare-overlay.tsx        |  23 +++-
 .../components/review/compare/wipe-viewer.tsx |  20 ++-
 .../review/image-frame-constraint.tsx         |  89 +++++++++++++
 apps/web/components/review/image-viewer.tsx   |  13 +-
 apps/web/lib/__tests__/media-frame.test.ts    |  80 ++++++++++++
 apps/web/lib/media-frame.ts                   |  75 +++++++++++
 11 files changed, 660 insertions(+), 19 deletions(-)
 create mode 100644 apps/web/components/review/__tests__/image-frame-constraint.test.tsx
 create mode 100644 apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx
 create mode 100644 apps/web/components/review/image-frame-constraint.tsx
 create mode 100644 apps/web/lib/__tests__/media-frame.test.ts
 create mode 100644 apps/web/lib/media-frame.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b9aa404..5df2b552 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- **Image annotations no longer drift when the viewer's aspect ratio changes** — drawings on images were authored and replayed against the full letterboxed container box rather than the picture inside it, so the same annotation pointed at a different part of the image depending on where it was viewed: sidebar collapsed vs expanded, a resized window, a compare pane, or a share link. A 3:1 image annotated in a 900x500 viewer and reopened in a 400x700 one put the mark 54% of the image height away from where it was drawn, far enough to land off the picture entirely. Images now get the same treatment video already had (`VideoFrameConstraint`), applied in the single viewer, both side-by-side compare panes, and the wipe view. (#185)
+
 ### Changed
 - **Pinned `starlette` and `botocore` so self-hosted Docker builds are reproducible** — both were floating transitives, so rebuilding the same commit on a different day could silently install different versions with no diff and no PR. FastAPI declares `starlette>=0.46.0` with no upper bound, meaning builds were free to cross a Starlette major (the ASGI layer under the SSE endpoint and the middleware stack); `botocore` is where S3 request signing lives, and unreviewed moves there have broken S3 compatibility before. Both are pinned to the versions already resolving, so no installed version changes.
 
diff --git a/apps/web/components/review/__tests__/image-frame-constraint.test.tsx b/apps/web/components/review/__tests__/image-frame-constraint.test.tsx
new file mode 100644
index 00000000..8ff835f2
--- /dev/null
+++ b/apps/web/components/review/__tests__/image-frame-constraint.test.tsx
@@ -0,0 +1,123 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import * as React from 'react'
+import { render, screen, fireEvent, act } from '@testing-library/react'
+import { ImageFrameConstraint } from '../image-frame-constraint'
+
+/**
+ * jsdom performs no layout, so offsetWidth/naturalWidth are always 0. These
+ * tests stub those DOM properties to describe a laid-out image and then assert
+ * on the style the component actually computes — the component's real effect
+ * runs, nothing about it is mocked.
+ */
+function layOut(
+  img: HTMLImageElement,
+  g: { natural: [number, number]; box: [number, number]; offset: [number, number] },
+) {
+  const props: Record<string, number> = {
+    naturalWidth: g.natural[0],
+    naturalHeight: g.natural[1],
+    offsetWidth: g.box[0],
+    offsetHeight: g.box[1],
+    offsetLeft: g.offset[0],
+    offsetTop: g.offset[1],
+  }
+  for (const [k, value] of Object.entries(props)) {
+    Object.defineProperty(img, k, { value, configurable: true })
+  }
+}
+
+function Harness({
+  geometry,
+}: {
+  geometry: { natural: [number, number]; box: [number, number]; offset: [number, number] }
+}) {
+  const imgRef = React.useRef<HTMLImageElement>(null)
+  // Lay the image out before the constraint's effect reads it.
+  React.useLayoutEffect(() => {
+    if (imgRef.current) layOut(imgRef.current, geometry)
+  }, [geometry])
+  return (
+    <div style={{ position: 'relative' }}>
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img ref={imgRef} alt="subject" />
+      <ImageFrameConstraint imgRef={imgRef}>
+        <div data-testid="child" />
+      </ImageFrameConstraint>
+    </div>
+  )
+}
+
+const wrapper = () => screen.getByTestId('child').parentElement as HTMLElement
+
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  })
+})
+
+describe('ImageFrameConstraint', () => {
+  it('positions the annotation layer over the picture, not the letterboxed container', () => {
+    // 100x200 image centred in an 800x400 box: max-* leaves it at natural size.
+    render(<Harness geometry={{ natural: [100, 200], box: [100, 200], offset: [350, 100] }} />)
+
+    expect(wrapper()).toHaveStyle({
+      position: 'absolute',
+      left: '350px',
+      top: '100px',
+      width: '100px',
+      height: '200px',
+    })
+  })
+
+  it('excludes the letterbox bands when the element itself fills the container', () => {
+    // The <video>-style case: element stretched to 800x400, picture is 200x400.
+    render(<Harness geometry={{ natural: [100, 200], box: [800, 400], offset: [0, 0] }} />)
+
+    expect(wrapper()).toHaveStyle({ left: '300px', top: '0px', width: '200px', height: '400px' })
+  })
+
+  it('recalculates once the image decodes and reports its intrinsic size', () => {
+    const { container } = render(
+      // naturalWidth 0 — not decoded yet, so the element box is all we know.
+      <Harness geometry={{ natural: [0, 0], box: [800, 400], offset: [0, 0] }} />,
+    )
+    expect(wrapper()).toHaveStyle({ width: '800px', height: '400px' })
+
+    const img = container.querySelector('img') as HTMLImageElement
+    layOut(img, { natural: [100, 200], box: [800, 400], offset: [0, 0] })
+    act(() => { fireEvent.load(img) })
+
+    expect(wrapper()).toHaveStyle({ left: '300px', width: '200px', height: '400px' })
+  })
+
+  it('renders its children inside the constrained box', () => {
+    render(<Harness geometry={{ natural: [100, 200], box: [100, 200], offset: [350, 100] }} />)
+    // AnnotationOverlay and AnnotationCanvas both size themselves from their
+    // parent, so being INSIDE this wrapper is what puts them in image space.
+    expect(wrapper()).toContainElement(screen.getByTestId('child'))
+  })
+
+  it('recomputes when the container resizes', () => {
+    const observers: Array<() => void> = []
+    vi.stubGlobal('ResizeObserver', class {
+      constructor(cb: () => void) { observers.push(cb) }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    })
+
+    const { container } = render(
+      <Harness geometry={{ natural: [100, 200], box: [800, 400], offset: [0, 0] }} />,
+    )
+    expect(wrapper()).toHaveStyle({ left: '300px', width: '200px' })
+
+    // Sidebar collapses: the pane gets wider, so the picture recentres.
+    const img = container.querySelector('img') as HTMLImageElement
+    layOut(img, { natural: [100, 200], box: [1000, 400], offset: [0, 0] })
+    act(() => { observers.forEach((cb) => cb()) })
+
+    expect(wrapper()).toHaveStyle({ left: '400px', width: '200px' })
+  })
+})
diff --git a/apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx b/apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx
new file mode 100644
index 00000000..e231f1a8
--- /dev/null
+++ b/apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx
@@ -0,0 +1,98 @@
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import { ImageViewer } from '../image-viewer'
+import { useReviewStore } from '@/stores/review-store'
+
+vi.mock('@/lib/api', () => ({
+  api: { get: vi.fn(async () => ({ url: '/asset.webp' })) },
+}))
+
+const asset = { id: 'a1', name: 'Demo', asset_type: 'image' } as never
+const version = { id: 'v1', version_number: 1, files: [] } as never
+
+/**
+ * Regression guard for #185. The annotation layer used to be mounted in a plain
+ * `absolute inset-0` div, i.e. the letterboxed CONTAINER box, so a drawing made
+ * in one container aspect ratio landed somewhere else in another. It must be
+ * mounted in the box the picture actually occupies.
+ *
+ * jsdom does no layout, so the <img> geometry is stubbed on the prototype
+ * before render — the component's own effect then reads it for real.
+ */
+const stubbed: Array<() => void> = []
+function stubGeometry(props: Record<string, number>) {
+  for (const [key, value] of Object.entries(props)) {
+    const proto = key.startsWith('natural') ? HTMLImageElement.prototype : HTMLElement.prototype
+    const original = Object.getOwnPropertyDescriptor(proto, key)
+    Object.defineProperty(proto, key, { value, configurable: true })
+    stubbed.push(() => {
+      if (original) Object.defineProperty(proto, key, original)
+      else delete (proto as unknown as Record<string, unknown>)[key]
+    })
+  }
+}
+
+beforeEach(() => {
+  useReviewStore.getState().reset()
+  vi.stubGlobal('ResizeObserver', class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  })
+})
+
+afterEach(() => {
+  stubbed.splice(0).forEach((restore) => restore())
+})
+
+describe('ImageViewer annotation frame', () => {
+  it('mounts the annotation layer over the picture, not the letterboxed container', async () => {
+    // A portrait image rendered at natural size inside a wider container:
+    // max-w-full/max-h-full leaves 350px of empty space either side.
+    stubGeometry({
+      naturalWidth: 100, naturalHeight: 200,
+      offsetWidth: 100, offsetHeight: 200, offsetLeft: 350, offsetTop: 100,
+    })
+
+    render(
+      <ImageViewer
+        asset={asset}
+        version={version}
+        annotationCanvas={<div data-testid="annotation-slot" />}
+      />,
+    )
+
+    const slot = await screen.findByTestId('annotation-slot')
+    await waitFor(() => {
+      expect(slot.parentElement).toHaveStyle({
+        position: 'absolute',
+        left: '350px',
+        top: '100px',
+        width: '100px',
+        height: '200px',
+      })
+    })
+  })
+
+  it('keeps the annotation layer a sibling of the image so it zooms and pans with it', async () => {
+    stubGeometry({
+      naturalWidth: 100, naturalHeight: 200,
+      offsetWidth: 100, offsetHeight: 200, offsetLeft: 350, offsetTop: 100,
+    })
+
+    const { container } = render(
+      <ImageViewer
+        asset={asset}
+        version={version}
+        annotationCanvas={<div data-testid="annotation-slot" />}
+      />,
+    )
+
+    const slot = await screen.findByTestId('annotation-slot')
+    const img = container.querySelector('img') as HTMLImageElement
+    // Same positioned ancestor as the <img>: the constraint's left/top are in
+    // that element's coordinate space, and the whole group sits inside the
+    // zoom/pan transform.
+    expect(slot.parentElement?.parentElement).toContainElement(img)
+  })
+})
diff --git a/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx b/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx
index 3e76f977..6c24d374 100644
--- a/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx
+++ b/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx
@@ -1,4 +1,4 @@
-import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { useReviewStore } from '@/stores/review-store'
 
@@ -86,6 +86,24 @@ function makeVersion(n: number, status = 'ready') {
   } as never
 }
 
+/**
+ * jsdom does no layout, so an <img> reports 0 for every geometry property.
+ * Describe a laid-out image on the prototypes; ImageFrameConstraint's own
+ * effect then reads it for real. Restored in afterEach.
+ */
+const geometryStubs: Array<() => void> = []
+function stubImageGeometry(props: Record<string, number>) {
+  for (const [key, value] of Object.entries(props)) {
+    const proto = key.startsWith('natural') ? HTMLImageElement.prototype : HTMLElement.prototype
+    const original = Object.getOwnPropertyDescriptor(proto, key)
+    Object.defineProperty(proto, key, { value, configurable: true })
+    geometryStubs.push(() => {
+      if (original) Object.defineProperty(proto, key, original)
+      else delete (proto as unknown as Record<string, unknown>)[key]
+    })
+  }
+}
+
 function makeComment(id: string, versionId: string, over: Record<string, unknown> = {}) {
   return {
     id, asset_id: 'a1', version_id: versionId, parent_id: null,
@@ -128,6 +146,10 @@ beforeEach(() => {
   })
 })
 
+afterEach(() => {
+  geometryStubs.splice(0).forEach((restore) => restore())
+})
+
 describe('CompareOverlay', () => {
   it('renders exactly the minimalist chrome: two selects, mode toggle (image), close', () => {
     render(
@@ -374,12 +396,45 @@ describe('CompareOverlay per-pane annotation display', () => {
     fireEvent.click(screen.getByText('Fix the color grade'))
 
     const overlay = screen.getByTestId('annotation-overlay')
-    // Same wrapper as pane B's <img> — drawings zoom/pan with the image.
-    expect(overlay.parentElement).toContainElement(screen.getByAltText('v3'))
-    expect(overlay.parentElement).not.toContainElement(screen.getByAltText('v1'))
+    // Inside pane B's image wrapper — drawings zoom/pan with that image, and
+    // pane A never renders it. Asserted from the <img> outwards so it stays
+    // precise regardless of the constraint layers in between.
+    expect(screen.getByAltText('v3').parentElement).toContainElement(overlay)
+    expect(screen.getByAltText('v1').parentElement).not.toContainElement(overlay)
     expect(useReviewStore.getState().activeAnnotation).toBeNull()
   })
 
+  it('image side-by-side: the annotation layer is pinned to the picture, not the letterboxed pane', () => {
+    searchParamsString = 'compare=v-1&mode=sbs'
+    streamUrl = '/img.webp'
+    // Portrait image rendered at natural size in a wider pane: max-w-full does
+    // not upscale, so 350px of empty pane sits either side of the picture.
+    stubImageGeometry({
+      naturalWidth: 100, naturalHeight: 200,
+      offsetWidth: 100, offsetHeight: 200, offsetLeft: 350, offsetTop: 100,
+    })
+    commentsByVersion['v-3'] = [
+      makeComment('c9', 'v-3', {
+        timecode_start: null,
+        annotation: { id: 'ann9', comment_id: 'c9', drawing_data: DRAWING },
+      }),
+    ]
+    render(
+      <CompareOverlay asset={asset} versions={[makeVersion(1), makeVersion(3)]} rightVersion={makeVersion(3)} onClose={vi.fn()} />,
+    )
+    fireEvent.click(screen.getByText('Fix the color grade'))
+
+    // #185: previously the overlay filled the whole pane, so the same drawing
+    // landed elsewhere in a pane of a different aspect ratio.
+    expect(screen.getByTestId('annotation-overlay').parentElement).toHaveStyle({
+      position: 'absolute',
+      left: '350px',
+      top: '100px',
+      width: '100px',
+      height: '200px',
+    })
+  })
+
   it('wipe: a v2 (right) marker is clipped to the RIGHT of the divider — no bleed onto v1', () => {
     streamUrl = '/img.webp'
     commentsByVersion['v-3'] = [
diff --git a/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx b/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx
index a7459d75..cfa877a8 100644
--- a/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx
+++ b/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx
@@ -1,8 +1,38 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
 import { fireEvent, render, screen, renderHook, act } from '@testing-library/react'
 import { WipeViewer } from '../wipe-viewer'
 import { useSharedTransform } from '../use-shared-transform'
 
+/**
+ * jsdom does no layout, so an <img> reports 0 for every geometry property.
+ * Describe a laid-out image on the prototypes; ImageFrameConstraint's own
+ * effect then reads it for real.
+ */
+const geometryStubs: Array<() => void> = []
+function stubImageGeometry(props: Record<string, number>) {
+  for (const [key, value] of Object.entries(props)) {
+    const proto = key.startsWith('natural') ? HTMLImageElement.prototype : HTMLElement.prototype
+    const original = Object.getOwnPropertyDescriptor(proto, key)
+    Object.defineProperty(proto, key, { value, configurable: true })
+    geometryStubs.push(() => {
+      if (original) Object.defineProperty(proto, key, original)
+      else delete (proto as unknown as Record<string, unknown>)[key]
+    })
+  }
+}
+
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  })
+})
+
+afterEach(() => {
+  geometryStubs.splice(0).forEach((restore) => restore())
+})
+
 function renderWipe() {
   const { result } = renderHook(() => useSharedTransform())
   render(
@@ -52,6 +82,66 @@ describe('WipeViewer', () => {
     }
   })
 
+  it('positions the overlay over the picture, not the letterboxed stage (#185)', () => {
+    // Drawings are authored in image-frame space (ImageFrameConstraint in the
+    // single viewer and the side-by-side panes). Wipe display has to use the
+    // SAME space or every annotation shown here is offset by the letterbox.
+    stubImageGeometry({
+      naturalWidth: 1200, naturalHeight: 400,
+      offsetWidth: 900, offsetHeight: 300, offsetLeft: 0, offsetTop: 100,
+    })
+    const { result } = renderHook(() => useSharedTransform())
+    render(
+      <WipeViewer
+        urlA="/a.webp" urlB="/b.webp" badgeA="v1" badgeB="v3"
+        transform={result.current}
+        overlay={<div data-testid="wipe-overlay" />}
+        overlaySide="b"
+      />,
+    )
+    expect(screen.getByTestId('wipe-overlay').parentElement).toHaveStyle({
+      position: 'absolute',
+      left: '0px',
+      top: '100px',
+      width: '900px',
+      height: '300px',
+    })
+  })
+
+  it('measures the overlay against the version that owns it', () => {
+    // Two versions of an asset can differ in aspect ratio, so the constraint
+    // has to follow overlaySide rather than always measuring the same image.
+    // Baseline geometry (both images): 3:1 letterboxed into a 900x500 stage.
+    stubImageGeometry({
+      naturalWidth: 1200, naturalHeight: 400,
+      offsetWidth: 900, offsetHeight: 300, offsetLeft: 0, offsetTop: 100,
+    })
+    const { result } = renderHook(() => useSharedTransform())
+    const wipe = (side: 'a' | 'b') => (
+      <WipeViewer
+        urlA="/a.webp" urlB="/b.webp" badgeA="v1" badgeB="v3"
+        transform={result.current}
+        overlay={<div data-testid="wipe-overlay" />}
+        overlaySide={side}
+      />
+    )
+    const { rerender } = render(wipe('a'))
+    expect(screen.getByTestId('wipe-overlay').parentElement)
+      .toHaveStyle({ top: '100px', height: '300px' })
+
+    // Give side B a taller shape than side A — only a constraint bound to B's
+    // <img> can report it.
+    for (const [key, value] of Object.entries({
+      naturalWidth: 900, naturalHeight: 600, offsetWidth: 900, offsetHeight: 600, offsetTop: 0,
+    })) {
+      Object.defineProperty(screen.getByAltText('v3'), key, { value, configurable: true })
+    }
+    rerender(wipe('b'))
+
+    expect(screen.getByTestId('wipe-overlay').parentElement)
+      .toHaveStyle({ top: '0px', height: '600px' })
+  })
+
   it('clips the overlay to the owning version’s half (A left of the divider, B right)', () => {
     const { result } = renderHook(() => useSharedTransform())
     const { rerender } = render(
diff --git a/apps/web/components/review/compare/compare-overlay.tsx b/apps/web/components/review/compare/compare-overlay.tsx
index 1b50f470..cfb1c1af 100644
--- a/apps/web/components/review/compare/compare-overlay.tsx
+++ b/apps/web/components/review/compare/compare-overlay.tsx
@@ -17,6 +17,7 @@ import { WipeViewer } from './wipe-viewer'
 import { AnnotationOverlay } from '@/components/review/annotation-overlay'
 import { AnnotationCanvas } from '@/components/review/annotation-canvas'
 import { VideoFrameConstraint } from '@/components/review/video-player'
+import { ImageFrameConstraint } from '@/components/review/image-frame-constraint'
 import { CommentPanel } from '@/components/review/comment-panel'
 import { CommentInput } from '@/components/review/comment-input'
 import type { AssetResponse, AssetVersion } from '@/types'
@@ -169,6 +170,10 @@ export function CompareOverlay({ asset, versions, rightVersion, onClose, canComm
   // saved drawing aligns with how it later renders. Available for video and
   // image side-by-side; image wipe stays display-only (one ambiguous stage).
   const canAuthor = isVideo || mode === 'sbs'
+  // Per-pane image refs — ImageFrameConstraint measures these so each side's
+  // annotations live in that image's frame, not the pane's letterboxed box.
+  const imgARef = React.useRef<HTMLImageElement>(null)
+  const imgBRef = React.useRef<HTMLImageElement>(null)
   const [drawingSide, setDrawingSide] = React.useState<'a' | 'b' | null>(null)
   const toggleDrawing = React.useCallback(
     (side: 'a' | 'b') => setDrawingSide((prev) => (prev === side ? null : side)),
@@ -540,9 +545,13 @@ export function CompareOverlay({ asset, versions, rightVersion, onClose, canComm
                   // available box as before.
                   <div className="relative flex h-full w-full items-center justify-center" style={transform.styleFor()}>
                     {/* eslint-disable-next-line @next/next/no-img-element */}
-                    <img src={urlA} alt={badgeA} className="max-h-full max-w-full object-contain" draggable={false} />
-                    <AnnotationOverlay key={`a-${focusedCommentId ?? 'none'}`} annotation={annotationA} />
-                    {drawingSide === 'a' && <AnnotationCanvas />}
+                    <img ref={imgARef} src={urlA} alt={badgeA} className="max-h-full max-w-full object-contain" draggable={false} />
+                    {/* Image-frame space, not pane space — the two panes letterbox
+                        differently whenever the versions differ in aspect ratio. */}
+                    <ImageFrameConstraint imgRef={imgARef}>
+                      <AnnotationOverlay key={`a-${focusedCommentId ?? 'none'}`} annotation={annotationA} />
+                      {drawingSide === 'a' && <AnnotationCanvas />}
+                    </ImageFrameConstraint>
                   </div>
                 )}
               </div>
@@ -552,9 +561,11 @@ export function CompareOverlay({ asset, versions, rightVersion, onClose, canComm
                 {urlB && (
                   <div className="relative flex h-full w-full items-center justify-center" style={transform.styleFor()}>
                     {/* eslint-disable-next-line @next/next/no-img-element */}
-                    <img src={urlB} alt={badgeB} className="max-h-full max-w-full object-contain" draggable={false} />
-                    <AnnotationOverlay key={`b-${focusedCommentId ?? 'none'}`} annotation={annotationB} />
-                    {drawingSide === 'b' && <AnnotationCanvas />}
+                    <img ref={imgBRef} src={urlB} alt={badgeB} className="max-h-full max-w-full object-contain" draggable={false} />
+                    <ImageFrameConstraint imgRef={imgBRef}>
+                      <AnnotationOverlay key={`b-${focusedCommentId ?? 'none'}`} annotation={annotationB} />
+                      {drawingSide === 'b' && <AnnotationCanvas />}
+                    </ImageFrameConstraint>
                   </div>
                 )}
               </div>
diff --git a/apps/web/components/review/compare/wipe-viewer.tsx b/apps/web/components/review/compare/wipe-viewer.tsx
index eb80ecde..0d42bc79 100644
--- a/apps/web/components/review/compare/wipe-viewer.tsx
+++ b/apps/web/components/review/compare/wipe-viewer.tsx
@@ -1,6 +1,7 @@
 'use client'
 
 import * as React from 'react'
+import { ImageFrameConstraint } from '@/components/review/image-frame-constraint'
 
 interface WipeViewerProps {
   urlA: string
@@ -31,6 +32,10 @@ interface WipeViewerProps {
 export function WipeViewer({ urlA, urlB, badgeA, badgeB, transform, overlay, overlaySide }: WipeViewerProps) {
   const [split, setSplit] = React.useState(50)
   const stageRef = React.useRef<HTMLDivElement>(null)
+  // Annotations are authored in image-frame space, so display has to measure the
+  // owning version's <img> — the two versions can letterbox differently.
+  const imgARef = React.useRef<HTMLImageElement>(null)
+  const imgBRef = React.useRef<HTMLImageElement>(null)
   const dividerCleanup = React.useRef<(() => void) | null>(null)
   React.useEffect(() => () => dividerCleanup.current?.(), [])
 
@@ -62,13 +67,13 @@ export function WipeViewer({ urlA, urlB, badgeA, badgeB, transform, overlay, ove
       {/* Side A (left of divider) */}
       <div className="absolute inset-0 flex items-center justify-center" style={transform.styleFor()}>
         {/* eslint-disable-next-line @next/next/no-img-element */}
-        <img src={urlA} alt={badgeA} className="max-h-full max-w-full object-contain" draggable={false} />
+        <img ref={imgARef} src={urlA} alt={badgeA} className="max-h-full max-w-full object-contain" draggable={false} />
       </div>
       {/* Side B on top, revealed right of the divider */}
       <div className="absolute inset-0" style={{ clipPath: `inset(0 0 0 ${split}%)` }}>
         <div className="absolute inset-0 flex items-center justify-center" style={transform.styleFor()}>
           {/* eslint-disable-next-line @next/next/no-img-element */}
-          <img src={urlB} alt={badgeB} className="max-h-full max-w-full object-contain" draggable={false} />
+          <img ref={imgBRef} src={urlB} alt={badgeB} className="max-h-full max-w-full object-contain" draggable={false} />
         </div>
       </div>
       {/* Overlay layer — above both images. The clip lives in SCREEN space
@@ -89,7 +94,16 @@ export function WipeViewer({ urlA, urlB, badgeA, badgeB, transform, overlay, ove
           }
         >
           <div className="absolute inset-0" style={transform.styleFor()}>
-            {overlay}
+            {/* Keyed by side so switching owner remounts the constraint against
+                that version's <img> instead of holding the previous one's box.
+                Both images share this layer's coordinate space (every layer here
+                is `absolute inset-0` of the stage), so the offsets line up. */}
+            <ImageFrameConstraint
+              key={overlaySide ?? 'a'}
+              imgRef={overlaySide === 'b' ? imgBRef : imgARef}
+            >
+              {overlay}
+            </ImageFrameConstraint>
           </div>
         </div>
       )}
diff --git a/apps/web/components/review/image-frame-constraint.tsx b/apps/web/components/review/image-frame-constraint.tsx
new file mode 100644
index 00000000..498cde70
--- /dev/null
+++ b/apps/web/components/review/image-frame-constraint.tsx
@@ -0,0 +1,89 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '@/lib/utils'
+import { renderedImageBox } from '@/lib/media-frame'
+
+/**
+ * Wraps children so they sit exactly over the visible picture, excluding the
+ * empty bands `object-contain` leaves around it.
+ *
+ * Annotations are AUTHORED inside this constraint (image-frame coordinates), so
+ * every viewer that renders them must mount the overlay in the same space —
+ * otherwise the same drawing lands somewhere else whenever the container's
+ * aspect ratio differs from the one it was drawn in. Mirrors
+ * `VideoFrameConstraint` in video-player.tsx, which does this for <video>.
+ *
+ * Both children that go in here size themselves from their parent
+ * (`AnnotationOverlay` reads offsetWidth/offsetHeight, `AnnotationCanvas` feeds
+ * the same into Fabric via useDrawing), so being inside this wrapper is the
+ * whole mechanism — neither needed changing.
+ *
+ * Uses offset* rather than getBoundingClientRect because this renders inside
+ * react-zoom-pan-pinch's TransformComponent: offset* are pre-transform layout
+ * values, while a client rect would fold the zoom/pan matrix in.
+ */
+export function ImageFrameConstraint({
+  imgRef,
+  className,
+  children,
+}: {
+  imgRef: React.RefObject<HTMLImageElement | null>
+  /** Merged onto the constrained box — callers use it for pointer-events. */
+  className?: string
+  children: React.ReactNode
+}) {
+  const [style, setStyle] = React.useState<React.CSSProperties>({ position: 'absolute', inset: 0 })
+
+  React.useEffect(() => {
+    const img = imgRef.current
+    if (!img) return
+
+    const calc = () => {
+      const box = renderedImageBox({
+        naturalWidth: img.naturalWidth,
+        naturalHeight: img.naturalHeight,
+        elementWidth: img.offsetWidth,
+        elementHeight: img.offsetHeight,
+        offsetLeft: img.offsetLeft,
+        offsetTop: img.offsetTop,
+      })
+
+      // Not laid out yet — fill the container so the overlay is never orphaned
+      // at 0x0, and recalculate on the next load/resize.
+      if (!box) {
+        setStyle({ position: 'absolute', inset: 0 })
+        return
+      }
+
+      setStyle({
+        position: 'absolute',
+        left: box.left,
+        top: box.top,
+        width: box.width,
+        height: box.height,
+      })
+    }
+
+    calc()
+    // A cached image can be complete before this effect runs, so calc() above
+    // is not redundant with the load listener.
+    img.addEventListener('load', calc)
+
+    // The <img> itself resizes whenever its container does, under both the
+    // max-* and the w-full/h-full patterns, so observing it covers both.
+    const ro = new ResizeObserver(calc)
+    ro.observe(img)
+
+    return () => {
+      img.removeEventListener('load', calc)
+      ro.disconnect()
+    }
+  }, [imgRef])
+
+  return (
+    <div style={style} className={cn('overflow-hidden', className)}>
+      {children}
+    </div>
+  )
+}
diff --git a/apps/web/components/review/image-viewer.tsx b/apps/web/components/review/image-viewer.tsx
index d6c26af9..6d9475f4 100644
--- a/apps/web/components/review/image-viewer.tsx
+++ b/apps/web/components/review/image-viewer.tsx
@@ -21,6 +21,7 @@ import { api } from '@/lib/api'
 import { Button } from '@/components/ui/button'
 import { useReviewStore } from '@/stores/review-store'
 import { useReview } from '@/components/review/review-provider'
+import { ImageFrameConstraint } from '@/components/review/image-frame-constraint'
 import type { Asset, AssetVersion, MediaFile } from '@/types'
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -101,14 +102,16 @@ function SingleImage({ url, alt, containerRef, onImageLoad, annotationOverlay, i
         className="max-w-full max-h-full object-contain select-none"
         draggable={false}
       />
-      {/* Annotation overlay — positioned on top of the image, moves with zoom/pan */}
+      {/* Annotation overlay — pinned to the picture itself (not the letterboxed
+          container box), so coordinates stay image-relative across containers of
+          different aspect ratio. Moves with zoom/pan by sitting in the transform. */}
       {annotationOverlay && (
-        <div
-          className="absolute inset-0"
-          style={{ pointerEvents: isDrawingMode ? 'auto' : 'none' }}
+        <ImageFrameConstraint
+          imgRef={imgRef}
+          className={isDrawingMode ? 'pointer-events-auto' : 'pointer-events-none'}
         >
           {annotationOverlay}
-        </div>
+        </ImageFrameConstraint>
       )}
     </div>
   )
diff --git a/apps/web/lib/__tests__/media-frame.test.ts b/apps/web/lib/__tests__/media-frame.test.ts
new file mode 100644
index 00000000..111d1f76
--- /dev/null
+++ b/apps/web/lib/__tests__/media-frame.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import { renderedImageBox } from '../media-frame'
+
+/**
+ * The three shapes below were measured in a real browser (Chrome, file:// probe)
+ * against the exact CSS the app ships, because the two <img> patterns in this
+ * codebase disagree about where the image actually lands:
+ *
+ *   image-viewer.tsx / compare panes:  max-w-full max-h-full object-contain
+ *   video-player.tsx <video>:          absolute inset-0 w-full h-full object-contain
+ *
+ * `max-*` only ever SHRINKS a replaced element, so an image smaller than its
+ * container renders at natural size — it is NOT scaled up to the contain box.
+ * Computing the contain box from the CONTAINER (what VideoFrameConstraint does,
+ * correctly, for <video>) gets that case wrong. Hence: contain math inside the
+ * element's own box, offset by where the element sits.
+ */
+
+const el = (
+  naturalWidth: number, naturalHeight: number,
+  elementWidth: number, elementHeight: number,
+  offsetLeft = 0, offsetTop = 0,
+) => ({ naturalWidth, naturalHeight, elementWidth, elementHeight, offsetLeft, offsetTop })
+
+describe('renderedImageBox — measured browser cases', () => {
+  it('image smaller than its container renders at natural size, centered (max-* does not upscale)', () => {
+    // 100x200 image, 800x400 container, max-w-full max-h-full
+    // browser: element box 100x200 at (350,100)
+    expect(renderedImageBox(el(100, 200, 100, 200, 350, 100)))
+      .toEqual({ left: 350, top: 100, width: 100, height: 200 })
+  })
+
+  it('image larger than its container is shrunk to the contain box', () => {
+    // 4000x1000 image, 800x400 container
+    // browser: element box 800x200 at (0,100)
+    expect(renderedImageBox(el(4000, 1000, 800, 200, 0, 100)))
+      .toEqual({ left: 0, top: 100, width: 800, height: 200 })
+  })
+
+  it('element that fills its container letterboxes internally (the <video> pattern)', () => {
+    // 100x200 image in an element stretched to 800x400 by w-full h-full
+    // browser: element box 800x400 at (0,0); the picture occupies 200x400 at (300,0)
+    expect(renderedImageBox(el(100, 200, 800, 400, 0, 0)))
+      .toEqual({ left: 300, top: 0, width: 200, height: 400 })
+  })
+})
+
+describe('renderedImageBox — letterbox direction', () => {
+  it('pads left/right when the image is taller than the element box', () => {
+    expect(renderedImageBox(el(1, 2, 400, 400)))
+      .toEqual({ left: 100, top: 0, width: 200, height: 400 })
+  })
+
+  it('pads top/bottom when the image is wider than the element box', () => {
+    expect(renderedImageBox(el(2, 1, 400, 400)))
+      .toEqual({ left: 0, top: 100, width: 400, height: 200 })
+  })
+
+  it('adds no padding when the aspect ratios already match', () => {
+    expect(renderedImageBox(el(1600, 900, 800, 450, 10, 20)))
+      .toEqual({ left: 10, top: 20, width: 800, height: 450 })
+  })
+
+  it('carries the element offset through in both axes', () => {
+    expect(renderedImageBox(el(1, 1, 400, 200, 30, 40)))
+      .toEqual({ left: 130, top: 40, width: 200, height: 200 })
+  })
+})
+
+describe('renderedImageBox — degenerate input', () => {
+  it('falls back to the element box before natural dimensions are known', () => {
+    // <img> not decoded yet: naturalWidth/Height are 0
+    expect(renderedImageBox(el(0, 0, 800, 400, 5, 6)))
+      .toEqual({ left: 5, top: 6, width: 800, height: 400 })
+  })
+
+  it('returns null when the element has not been laid out', () => {
+    expect(renderedImageBox(el(100, 200, 0, 0))).toBeNull()
+  })
+})
diff --git a/apps/web/lib/media-frame.ts b/apps/web/lib/media-frame.ts
new file mode 100644
index 00000000..a1c88809
--- /dev/null
+++ b/apps/web/lib/media-frame.ts
@@ -0,0 +1,75 @@
+/** Geometry of a laid-out <img>, as read off the DOM. */
+export interface ImageFrameMetrics {
+  /** Intrinsic size. Both 0 until the image has decoded. */
+  naturalWidth: number
+  naturalHeight: number
+  /** The element's own laid-out box (offsetWidth/offsetHeight). */
+  elementWidth: number
+  elementHeight: number
+  /** Where that box sits inside the nearest positioned ancestor. */
+  offsetLeft: number
+  offsetTop: number
+}
+
+export interface Box {
+  left: number
+  top: number
+  width: number
+  height: number
+}
+
+/**
+ * The box the picture actually occupies, in the coordinate space of the <img>'s
+ * offsetParent — i.e. excluding the empty bands `object-contain` leaves behind.
+ *
+ * Annotations must be authored and displayed in THIS box rather than the
+ * container's, or the same drawing lands somewhere else whenever the container's
+ * aspect ratio changes (sidebar collapsed vs expanded, window resize, compare
+ * panes, share view). See `renderedImageBox`'s callers.
+ *
+ * Deliberately measured from the ELEMENT's box, not the container's. The two
+ * <img> patterns in this codebase behave differently:
+ *
+ *   `max-w-full max-h-full`  the element already hugs the picture, since max-*
+ *                            only shrinks — an image smaller than its container
+ *                            renders at natural size and is NOT scaled up.
+ *   `w-full h-full`          the element fills the container and the picture
+ *                            letterboxes inside it (what <video> does).
+ *
+ * Running the contain fit inside the element's own box is correct for both.
+ * Deriving it from the container instead — which is what `VideoFrameConstraint`
+ * does, correctly, for a filling <video> — silently upscales the box for any
+ * image smaller than its container.
+ */
+export function renderedImageBox({
+  naturalWidth,
+  naturalHeight,
+  elementWidth,
+  elementHeight,
+  offsetLeft,
+  offsetTop,
+}: ImageFrameMetrics): Box | null {
+  // Not laid out yet — there is no box to report.
+  if (!elementWidth || !elementHeight) return null
+
+  // Not decoded yet: the element box is the best available answer, and the
+  // caller recalculates on load.
+  if (!naturalWidth || !naturalHeight) {
+    return { left: offsetLeft, top: offsetTop, width: elementWidth, height: elementHeight }
+  }
+
+  // Compare aspect ratios by cross-multiplying rather than dividing, so exact
+  // fits (a 16:9 image in a 16:9 box) stay exact instead of drifting a
+  // fraction of a pixel through an intermediate ratio.
+  const imageIsWider = naturalWidth * elementHeight > naturalHeight * elementWidth
+
+  const width = imageIsWider ? elementWidth : (elementHeight * naturalWidth) / naturalHeight
+  const height = imageIsWider ? (elementWidth * naturalHeight) / naturalWidth : elementHeight
+
+  return {
+    left: offsetLeft + (elementWidth - width) / 2,
+    top: offsetTop + (elementHeight - height) / 2,
+    width,
+    height,
+  }
+}

From e53fc9c7b9926e540467d5984b39276c953916cc Mon Sep 17 00:00:00 2001
From: ravirajsinh45 <ravirajsinhdabhi86@gmail.com>
Date: Thu, 13 Aug 2026 22:57:39 +0530
Subject: [PATCH 2/4] fix(web): recompute the image frame when the container
 only recentres

Review follow-ups on #185.

ResizeObserver watched the <img> alone. Under `max-w-full max-h-full` an
image smaller than its container renders at natural size, so a container
resize only RECENTRES it: offsetLeft/offsetTop move while the element's own
box is untouched, and ResizeObserver does not fire on a position-only
change. The overlay stayed pinned where the picture used to be, which is the
same drift #185 set out to fix, for the case where the picture never needs
shrinking. It now observes the container as well.

Also folds the contain fit into one helper. `renderedImageBox` and
`VideoFrameConstraint` computed the same centred, aspect-preserving box two
different ways (cross-multiplication vs division); both now call
`containBox`, leaving only the reference box different, which is the part
that genuinely must differ. Checked equivalent for integer video dimensions:
no branch flips, differences bounded at ~1e-13px. The video overlay also
fills its container instead of collapsing to 0x0 when measured before layout.

Tests 282 -> 293:
- A ResizeObserver stub that records its target, so a resize can be
  delivered to the container and not the picture. The existing resize test
  fired every callback regardless of target and passed either way.
- VideoFrameConstraint had no direct coverage (the compare and wipe suites
  stub ResizeObserver precisely to route around its math). Pinned before
  moving it, and mutation checked.
- A pane A geometry test for side-by-side compare. Only pane B had one, so
  stripping pane A's constraint left the suite green; this fails for both a
  removed constraint and a swapped ref.
- The jsdom geometry stub was copy-pasted into three suites, now one helper
  in test/geometry.ts.
---
 CHANGELOG.md                                  |  1 +
 .../__tests__/image-frame-constraint.test.tsx | 31 ++++++
 .../image-viewer-annotation-frame.test.tsx    | 15 +--
 .../__tests__/video-frame-constraint.test.tsx | 95 +++++++++++++++++++
 .../__tests__/compare-overlay.test.tsx        | 62 +++++++++---
 .../compare/__tests__/wipe-viewer.test.tsx    | 19 +---
 .../review/image-frame-constraint.tsx         |  9 +-
 apps/web/components/review/video-player.tsx   | 37 +++-----
 apps/web/lib/__tests__/media-frame.test.ts    | 25 ++++-
 apps/web/lib/media-frame.ts                   | 46 ++++++---
 apps/web/test/geometry.ts                     | 41 ++++++++
 11 files changed, 301 insertions(+), 80 deletions(-)
 create mode 100644 apps/web/components/review/__tests__/video-frame-constraint.test.tsx
 create mode 100644 apps/web/test/geometry.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5df2b552..e2c6273e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Image annotations no longer drift when the viewer's aspect ratio changes** — drawings on images were authored and replayed against the full letterboxed container box rather than the picture inside it, so the same annotation pointed at a different part of the image depending on where it was viewed: sidebar collapsed vs expanded, a resized window, a compare pane, or a share link. A 3:1 image annotated in a 900x500 viewer and reopened in a 400x700 one put the mark 54% of the image height away from where it was drawn, far enough to land off the picture entirely. Images now get the same treatment video already had (`VideoFrameConstraint`), applied in the single viewer, both side-by-side compare panes, and the wipe view. (#185)
 
 ### Changed
+- **Image and video overlays now share one contain-fit implementation** — the geometry that positions an annotation over the visible picture was written twice, once for `<img>` and once for `<video>`, with the two comparing aspect ratios differently. Both now call a single tested helper; only the reference box still differs, because `<video>` fills its container while an `<img>` under `max-*` does not. The video overlay also fills its container instead of collapsing to 0x0 when measured before layout.
 - **Pinned `starlette` and `botocore` so self-hosted Docker builds are reproducible** — both were floating transitives, so rebuilding the same commit on a different day could silently install different versions with no diff and no PR. FastAPI declares `starlette>=0.46.0` with no upper bound, meaning builds were free to cross a Starlette major (the ASGI layer under the SSE endpoint and the middleware stack); `botocore` is where S3 request signing lives, and unreviewed moves there have broken S3 compatibility before. Both are pinned to the versions already resolving, so no installed version changes.
 
 ### Fixed
diff --git a/apps/web/components/review/__tests__/image-frame-constraint.test.tsx b/apps/web/components/review/__tests__/image-frame-constraint.test.tsx
index 8ff835f2..51249343 100644
--- a/apps/web/components/review/__tests__/image-frame-constraint.test.tsx
+++ b/apps/web/components/review/__tests__/image-frame-constraint.test.tsx
@@ -120,4 +120,35 @@ describe('ImageFrameConstraint', () => {
 
     expect(wrapper()).toHaveStyle({ left: '400px', width: '200px' })
   })
+
+  it('recomputes when the container resizes but the picture only recentres', () => {
+    // Records what each observer was pointed at, so a resize can be delivered to
+    // one element and not another. That distinction is the whole point here: the
+    // test above fires every callback regardless of target, which passes whether
+    // the component watches the picture or its container.
+    const observed = new Map<Element, Array<() => void>>()
+    vi.stubGlobal('ResizeObserver', class {
+      cb: () => void
+      constructor(cb: () => void) { this.cb = cb }
+      observe(el: Element) { observed.set(el, [...(observed.get(el) ?? []), this.cb]) }
+      unobserve() {}
+      disconnect() {}
+    })
+
+    // A 100x200 picture at natural size in a wide pane: max-* only ever shrinks,
+    // so the element hugs the picture and the pane centres it.
+    const { container } = render(
+      <Harness geometry={{ natural: [100, 200], box: [100, 200], offset: [400, 100] }} />,
+    )
+    expect(wrapper()).toHaveStyle({ left: '400px', top: '100px' })
+
+    // Sidebar collapses: the pane widens, the picture stays 100x200 and only
+    // recentres. The <img>'s own box never changes, so an observer on the <img>
+    // alone never fires — only one on the container does.
+    const img = container.querySelector('img') as HTMLImageElement
+    layOut(img, { natural: [100, 200], box: [100, 200], offset: [600, 100] })
+    act(() => { observed.get(img.parentElement as Element)?.forEach((cb) => cb()) })
+
+    expect(wrapper()).toHaveStyle({ left: '600px', top: '100px' })
+  })
 })
diff --git a/apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx b/apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx
index e231f1a8..1b34c256 100644
--- a/apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx
+++ b/apps/web/components/review/__tests__/image-viewer-annotation-frame.test.tsx
@@ -1,4 +1,5 @@
 import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+import { stubGeometry, restoreGeometry } from '@/test/geometry'
 import { render, screen, waitFor } from '@testing-library/react'
 import { ImageViewer } from '../image-viewer'
 import { useReviewStore } from '@/stores/review-store'
@@ -19,18 +20,6 @@ const version = { id: 'v1', version_number: 1, files: [] } as never
  * jsdom does no layout, so the <img> geometry is stubbed on the prototype
  * before render — the component's own effect then reads it for real.
  */
-const stubbed: Array<() => void> = []
-function stubGeometry(props: Record<string, number>) {
-  for (const [key, value] of Object.entries(props)) {
-    const proto = key.startsWith('natural') ? HTMLImageElement.prototype : HTMLElement.prototype
-    const original = Object.getOwnPropertyDescriptor(proto, key)
-    Object.defineProperty(proto, key, { value, configurable: true })
-    stubbed.push(() => {
-      if (original) Object.defineProperty(proto, key, original)
-      else delete (proto as unknown as Record<string, unknown>)[key]
-    })
-  }
-}
 
 beforeEach(() => {
   useReviewStore.getState().reset()
@@ -42,7 +31,7 @@ beforeEach(() => {
 })
 
 afterEach(() => {
-  stubbed.splice(0).forEach((restore) => restore())
+  restoreGeometry()
 })
 
 describe('ImageViewer annotation frame', () => {
diff --git a/apps/web/components/review/__tests__/video-frame-constraint.test.tsx b/apps/web/components/review/__tests__/video-frame-constraint.test.tsx
new file mode 100644
index 00000000..d6a1d268
--- /dev/null
+++ b/apps/web/components/review/__tests__/video-frame-constraint.test.tsx
@@ -0,0 +1,95 @@
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+import { stubGeometry, restoreGeometry } from '@/test/geometry'
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { VideoFrameConstraint } from '../video-player'
+
+vi.mock('@/lib/api', () => ({ api: { get: vi.fn() } }))
+
+/**
+ * VideoFrameConstraint had no direct coverage: the compare and wipe suites stub
+ * ResizeObserver to a no-op precisely to route AROUND its layout math, so
+ * nothing pinned the box it computes. These tests pin it, which is what lets the
+ * fit itself move into the shared `containBox` helper without guessing.
+ *
+ * Unlike the <img> constraint, this one derives the fit from the CONTAINER,
+ * which is correct here: the <video> is `w-full h-full object-contain`, so it
+ * always fills its container and letterboxes internally.
+ */
+function Harness() {
+  const videoRef = React.useRef<HTMLVideoElement>(null)
+  return (
+    <div>
+      <video ref={videoRef} />
+      <VideoFrameConstraint videoRef={videoRef as React.RefObject<HTMLVideoElement>}>
+        <div data-testid="child" />
+      </VideoFrameConstraint>
+    </div>
+  )
+}
+
+const wrapper = () => screen.getByTestId('child').parentElement as HTMLElement
+
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  })
+})
+
+afterEach(() => {
+  restoreGeometry()
+})
+
+describe('VideoFrameConstraint', () => {
+  it('letterboxes top/bottom when the video is wider than its container', () => {
+    // 16:9 video in a square container: full width, bars above and below.
+    stubGeometry({ videoWidth: 1920, videoHeight: 1080, clientWidth: 800, clientHeight: 800 })
+    render(<Harness />)
+
+    expect(wrapper()).toHaveStyle({
+      position: 'absolute',
+      left: '0px',
+      top: '175px',
+      width: '800px',
+      height: '450px',
+    })
+  })
+
+  it('pillarboxes left/right when the video is taller than its container', () => {
+    stubGeometry({ videoWidth: 1080, videoHeight: 1920, clientWidth: 800, clientHeight: 800 })
+    render(<Harness />)
+
+    expect(wrapper()).toHaveStyle({
+      left: '175px',
+      top: '0px',
+      width: '450px',
+      height: '800px',
+    })
+  })
+
+  it('adds no bars when the video and container already share an aspect ratio', () => {
+    stubGeometry({ videoWidth: 1920, videoHeight: 1080, clientWidth: 1600, clientHeight: 900 })
+    render(<Harness />)
+
+    expect(wrapper()).toHaveStyle({ left: '0px', top: '0px', width: '1600px', height: '900px' })
+  })
+
+  it('fills the container until the video reports its dimensions', () => {
+    // videoWidth is 0 until loadedmetadata; the overlay must not collapse to 0x0.
+    stubGeometry({ videoWidth: 0, videoHeight: 0, clientWidth: 800, clientHeight: 800 })
+    render(<Harness />)
+
+    expect(wrapper()).toHaveStyle({ position: 'absolute', inset: '0px' })
+  })
+
+  it('fills the container when the container itself has not been laid out', () => {
+    // Dividing by a 0-height container yields a NaN aspect, which used to fall
+    // through to a 0x0 overlay. Fill instead and recompute on the next resize.
+    stubGeometry({ videoWidth: 1920, videoHeight: 1080, clientWidth: 0, clientHeight: 0 })
+    render(<Harness />)
+
+    expect(wrapper()).toHaveStyle({ position: 'absolute', inset: '0px' })
+  })
+})
diff --git a/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx b/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx
index 6c24d374..2c447e3e 100644
--- a/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx
+++ b/apps/web/components/review/compare/__tests__/compare-overlay.test.tsx
@@ -1,4 +1,5 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { stubGeometry, restoreGeometry } from '@/test/geometry'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { useReviewStore } from '@/stores/review-store'
 
@@ -91,18 +92,6 @@ function makeVersion(n: number, status = 'ready') {
  * Describe a laid-out image on the prototypes; ImageFrameConstraint's own
  * effect then reads it for real. Restored in afterEach.
  */
-const geometryStubs: Array<() => void> = []
-function stubImageGeometry(props: Record<string, number>) {
-  for (const [key, value] of Object.entries(props)) {
-    const proto = key.startsWith('natural') ? HTMLImageElement.prototype : HTMLElement.prototype
-    const original = Object.getOwnPropertyDescriptor(proto, key)
-    Object.defineProperty(proto, key, { value, configurable: true })
-    geometryStubs.push(() => {
-      if (original) Object.defineProperty(proto, key, original)
-      else delete (proto as unknown as Record<string, unknown>)[key]
-    })
-  }
-}
 
 function makeComment(id: string, versionId: string, over: Record<string, unknown> = {}) {
   return {
@@ -147,7 +136,7 @@ beforeEach(() => {
 })
 
 afterEach(() => {
-  geometryStubs.splice(0).forEach((restore) => restore())
+  restoreGeometry()
 })
 
 describe('CompareOverlay', () => {
@@ -409,7 +398,7 @@ describe('CompareOverlay per-pane annotation display', () => {
     streamUrl = '/img.webp'
     // Portrait image rendered at natural size in a wider pane: max-w-full does
     // not upscale, so 350px of empty pane sits either side of the picture.
-    stubImageGeometry({
+    stubGeometry({
       naturalWidth: 100, naturalHeight: 200,
       offsetWidth: 100, offsetHeight: 200, offsetLeft: 350, offsetTop: 100,
     })
@@ -435,6 +424,51 @@ describe('CompareOverlay per-pane annotation display', () => {
     })
   })
 
+  it('image side-by-side: pane A pins its overlay to pane A’s own picture', () => {
+    searchParamsString = 'compare=v-1&mode=sbs'
+    streamUrl = '/img.webp'
+    // Baseline both panes share.
+    stubGeometry({
+      naturalWidth: 100, naturalHeight: 200,
+      offsetWidth: 100, offsetHeight: 200, offsetLeft: 350, offsetTop: 100,
+    })
+    commentsByVersion['v-1'] = [
+      makeComment('c1', 'v-1', {
+        timecode_start: null,
+        annotation: { id: 'ann1', comment_id: 'c1', drawing_data: DRAWING },
+      }),
+    ]
+    render(
+      <CompareOverlay asset={asset} versions={[makeVersion(1), makeVersion(3)]} rightVersion={makeVersion(3)} onClose={vi.fn()} />,
+    )
+
+    // Give pane A's picture a landscape shape of its own — letterboxed top and
+    // bottom inside its element box, unlike the shared portrait baseline. The
+    // prototype stub alone cannot distinguish the panes, so without this an
+    // overlay wired to pane B's <img> would satisfy the assertion too.
+    for (const [key, value] of Object.entries({
+      naturalWidth: 400, naturalHeight: 100,
+      offsetWidth: 400, offsetHeight: 200, offsetLeft: 20, offsetTop: 250,
+    })) {
+      Object.defineProperty(screen.getByAltText('v1'), key, { value, configurable: true })
+    }
+    // The constraint measured the baseline at mount; decoding re-measures.
+    fireEvent.load(screen.getByAltText('v1'))
+
+    fireEvent.click(screen.getByLabelText('Toggle left comments'))
+    fireEvent.click(screen.getByText('Fix the color grade'))
+
+    // 4:1 picture inside a 400x200 element box: full width, 50px of band above
+    // and below, offset by where pane A's element sits.
+    expect(screen.getByTestId('annotation-overlay').parentElement).toHaveStyle({
+      position: 'absolute',
+      left: '20px',
+      top: '300px',
+      width: '400px',
+      height: '100px',
+    })
+  })
+
   it('wipe: a v2 (right) marker is clipped to the RIGHT of the divider — no bleed onto v1', () => {
     streamUrl = '/img.webp'
     commentsByVersion['v-3'] = [
diff --git a/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx b/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx
index cfa877a8..7ea77e5f 100644
--- a/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx
+++ b/apps/web/components/review/compare/__tests__/wipe-viewer.test.tsx
@@ -1,4 +1,5 @@
 import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+import { stubGeometry, restoreGeometry } from '@/test/geometry'
 import { fireEvent, render, screen, renderHook, act } from '@testing-library/react'
 import { WipeViewer } from '../wipe-viewer'
 import { useSharedTransform } from '../use-shared-transform'
@@ -8,18 +9,6 @@ import { useSharedTransform } from '../use-shared-transform'
  * Describe a laid-out image on the prototypes; ImageFrameConstraint's own
  * effect then reads it for real.
  */
-const geometryStubs: Array<() => void> = []
-function stubImageGeometry(props: Record<string, number>) {
-  for (const [key, value] of Object.entries(props)) {
-    const proto = key.startsWith('natural') ? HTMLImageElement.prototype : HTMLElement.prototype
-    const original = Object.getOwnPropertyDescriptor(proto, key)
-    Object.defineProperty(proto, key, { value, configurable: true })
-    geometryStubs.push(() => {
-      if (original) Object.defineProperty(proto, key, original)
-      else delete (proto as unknown as Record<string, unknown>)[key]
-    })
-  }
-}
 
 beforeEach(() => {
   vi.stubGlobal('ResizeObserver', class {
@@ -30,7 +19,7 @@ beforeEach(() => {
 })
 
 afterEach(() => {
-  geometryStubs.splice(0).forEach((restore) => restore())
+  restoreGeometry()
 })
 
 function renderWipe() {
@@ -86,7 +75,7 @@ describe('WipeViewer', () => {
     // Drawings are authored in image-frame space (ImageFrameConstraint in the
     // single viewer and the side-by-side panes). Wipe display has to use the
     // SAME space or every annotation shown here is offset by the letterbox.
-    stubImageGeometry({
+    stubGeometry({
       naturalWidth: 1200, naturalHeight: 400,
       offsetWidth: 900, offsetHeight: 300, offsetLeft: 0, offsetTop: 100,
     })
@@ -112,7 +101,7 @@ describe('WipeViewer', () => {
     // Two versions of an asset can differ in aspect ratio, so the constraint
     // has to follow overlaySide rather than always measuring the same image.
     // Baseline geometry (both images): 3:1 letterboxed into a 900x500 stage.
-    stubImageGeometry({
+    stubGeometry({
       naturalWidth: 1200, naturalHeight: 400,
       offsetWidth: 900, offsetHeight: 300, offsetLeft: 0, offsetTop: 100,
     })
diff --git a/apps/web/components/review/image-frame-constraint.tsx b/apps/web/components/review/image-frame-constraint.tsx
index 498cde70..bd89b626 100644
--- a/apps/web/components/review/image-frame-constraint.tsx
+++ b/apps/web/components/review/image-frame-constraint.tsx
@@ -70,10 +70,15 @@ export function ImageFrameConstraint({
     // is not redundant with the load listener.
     img.addEventListener('load', calc)
 
-    // The <img> itself resizes whenever its container does, under both the
-    // max-* and the w-full/h-full patterns, so observing it covers both.
+    // Watch both boxes. Under `w-full h-full` the <img> resizes with its
+    // container, but under `max-*` an image smaller than the container renders
+    // at natural size and a resize only RECENTRES it — offsetLeft/offsetTop
+    // move while the element's own box is untouched, and ResizeObserver does not
+    // fire on a position-only change. Observing the container catches that;
+    // observing the <img> catches a box change that leaves the container alone.
     const ro = new ResizeObserver(calc)
     ro.observe(img)
+    if (img.parentElement) ro.observe(img.parentElement)
 
     return () => {
       img.removeEventListener('load', calc)
diff --git a/apps/web/components/review/video-player.tsx b/apps/web/components/review/video-player.tsx
index b164c03a..fe823a71 100644
--- a/apps/web/components/review/video-player.tsx
+++ b/apps/web/components/review/video-player.tsx
@@ -13,6 +13,7 @@ import {
   Repeat,
 } from "lucide-react";
 import { cn, formatTime, formatTimecode, formatFrames } from "@/lib/utils";
+import { containBox } from "@/lib/media-frame";
 import { api } from "@/lib/api";
 import { useReviewStore, type TimeFormat } from "@/stores/review-store";
 import { useVideoPlayer } from "@/hooks/use-video-player";
@@ -68,37 +69,25 @@ export function VideoFrameConstraint({
       const vw = video.videoWidth;
       const vh = video.videoHeight;
 
-      if (!vw || !vh) {
-        // Video metadata not loaded yet — fill container
+      if (!vw || !vh || !cw || !ch) {
+        // Metadata not loaded, or the container not laid out yet — fill it, and
+        // recompute on the next loadedmetadata/resize.
         setStyle({ position: "absolute", inset: 0 });
         return;
       }
 
-      const containerAspect = cw / ch;
-      const videoAspect = vw / vh;
-
-      let renderW: number, renderH: number, offsetX: number, offsetY: number;
-
-      if (videoAspect > containerAspect) {
-        // Video wider than container — letterbox top/bottom
-        renderW = cw;
-        renderH = cw / videoAspect;
-        offsetX = 0;
-        offsetY = (ch - renderH) / 2;
-      } else {
-        // Video taller than container — letterbox left/right
-        renderH = ch;
-        renderW = ch * videoAspect;
-        offsetX = (cw - renderW) / 2;
-        offsetY = 0;
-      }
+      // Same contain fit the image constraint uses; only the reference box
+      // differs. <video> is w-full h-full object-contain, so it always fills the
+      // container and letterboxes inside it — hence fitting against the
+      // container is right here, where for <img> under max-* it would not be.
+      const box = containBox(vw, vh, cw, ch);
 
       setStyle({
         position: "absolute",
-        left: offsetX,
-        top: offsetY,
-        width: renderW,
-        height: renderH,
+        left: box.left,
+        top: box.top,
+        width: box.width,
+        height: box.height,
       });
     };
 
diff --git a/apps/web/lib/__tests__/media-frame.test.ts b/apps/web/lib/__tests__/media-frame.test.ts
index 111d1f76..74f0853a 100644
--- a/apps/web/lib/__tests__/media-frame.test.ts
+++ b/apps/web/lib/__tests__/media-frame.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { renderedImageBox } from '../media-frame'
+import { containBox, renderedImageBox } from '../media-frame'
 
 /**
  * The three shapes below were measured in a real browser (Chrome, file:// probe)
@@ -22,6 +22,29 @@ const el = (
   offsetLeft = 0, offsetTop = 0,
 ) => ({ naturalWidth, naturalHeight, elementWidth, elementHeight, offsetLeft, offsetTop })
 
+describe('containBox', () => {
+  it('pads top/bottom when the content is wider than the box', () => {
+    expect(containBox(2, 1, 400, 400)).toEqual({ left: 0, top: 100, width: 400, height: 200 })
+  })
+
+  it('pads left/right when the content is taller than the box', () => {
+    expect(containBox(1, 2, 400, 400)).toEqual({ left: 100, top: 0, width: 200, height: 400 })
+  })
+
+  it('adds no padding when the aspect ratios already match', () => {
+    expect(containBox(1600, 900, 800, 450)).toEqual({ left: 0, top: 0, width: 800, height: 450 })
+  })
+
+  it('keeps an exact fit exact instead of drifting through an intermediate ratio', () => {
+    // Cross-multiplying rather than dividing is what makes this land on the
+    // exact value: `boxHeight * contentAspect` computes 799.9999999999999 here.
+    expect(containBox(1600, 900, 800, 450).width).toBe(800)
+    // A 1080p video in an odd-sized pane — the same divide-first route yields
+    // 300.4444444444444, one ULP low.
+    expect(containBox(1920, 1080, 301, 169).width).toBe(300.44444444444446)
+  })
+})
+
 describe('renderedImageBox — measured browser cases', () => {
   it('image smaller than its container renders at natural size, centered (max-* does not upscale)', () => {
     // 100x200 image, 800x400 container, max-w-full max-h-full
diff --git a/apps/web/lib/media-frame.ts b/apps/web/lib/media-frame.ts
index a1c88809..bc9bd4bf 100644
--- a/apps/web/lib/media-frame.ts
+++ b/apps/web/lib/media-frame.ts
@@ -18,6 +18,36 @@ export interface Box {
   height: number
 }
 
+/**
+ * The centred, aspect-preserving sub-box `object-fit: contain` produces when
+ * fitting content into a box. `left`/`top` are relative to the box's own origin.
+ *
+ * Shared by the two constraint components so they cannot drift apart:
+ * `renderedImageBox` below fits the picture inside the <img>'s own box and then
+ * offsets by where that element sits, while `VideoFrameConstraint` fits the
+ * video inside its container. Only the reference box differs — the fit itself
+ * is one implementation.
+ *
+ * Compares aspect ratios by cross-multiplying rather than dividing, so an exact
+ * fit (a 16:9 frame in a 16:9 box) stays exact instead of drifting a fraction of
+ * a pixel through an intermediate ratio.
+ *
+ * Assumes all four dimensions are non-zero; callers guard degenerate input.
+ */
+export function containBox(
+  contentWidth: number,
+  contentHeight: number,
+  boxWidth: number,
+  boxHeight: number,
+): Box {
+  const contentIsWider = contentWidth * boxHeight > contentHeight * boxWidth
+
+  const width = contentIsWider ? boxWidth : (boxHeight * contentWidth) / contentHeight
+  const height = contentIsWider ? (boxWidth * contentHeight) / contentWidth : boxHeight
+
+  return { left: (boxWidth - width) / 2, top: (boxHeight - height) / 2, width, height }
+}
+
 /**
  * The box the picture actually occupies, in the coordinate space of the <img>'s
  * offsetParent — i.e. excluding the empty bands `object-contain` leaves behind.
@@ -58,18 +88,12 @@ export function renderedImageBox({
     return { left: offsetLeft, top: offsetTop, width: elementWidth, height: elementHeight }
   }
 
-  // Compare aspect ratios by cross-multiplying rather than dividing, so exact
-  // fits (a 16:9 image in a 16:9 box) stay exact instead of drifting a
-  // fraction of a pixel through an intermediate ratio.
-  const imageIsWider = naturalWidth * elementHeight > naturalHeight * elementWidth
-
-  const width = imageIsWider ? elementWidth : (elementHeight * naturalWidth) / naturalHeight
-  const height = imageIsWider ? (elementWidth * naturalHeight) / naturalWidth : elementHeight
+  const box = containBox(naturalWidth, naturalHeight, elementWidth, elementHeight)
 
   return {
-    left: offsetLeft + (elementWidth - width) / 2,
-    top: offsetTop + (elementHeight - height) / 2,
-    width,
-    height,
+    left: offsetLeft + box.left,
+    top: offsetTop + box.top,
+    width: box.width,
+    height: box.height,
   }
 }
diff --git a/apps/web/test/geometry.ts b/apps/web/test/geometry.ts
new file mode 100644
index 00000000..8a73a866
--- /dev/null
+++ b/apps/web/test/geometry.ts
@@ -0,0 +1,41 @@
+/**
+ * jsdom performs no layout, so every geometry property on an element reads 0 and
+ * a component that measures its own DOM has nothing to measure. These helpers
+ * describe a laid-out element on the relevant prototype, letting the component's
+ * real effect read real numbers, then put the originals back.
+ *
+ * Stubbing the prototype rather than an instance because the components under
+ * test create the elements internally. Where a test needs two elements to report
+ * DIFFERENT geometry, stub the shared baseline here and then override the
+ * specific node with Object.defineProperty — see wipe-viewer.test.tsx.
+ */
+const restores: Array<() => void> = []
+
+/** Geometry keys live on the media prototypes; layout keys on HTMLElement. */
+function prototypeFor(key: string): object {
+  if (key.startsWith('natural')) return HTMLImageElement.prototype
+  if (key.startsWith('video')) return HTMLVideoElement.prototype
+  return HTMLElement.prototype
+}
+
+/**
+ * Describes a laid-out element, e.g.
+ * `stubGeometry({ naturalWidth: 100, offsetWidth: 800 })`.
+ * Pair with `restoreGeometry()` in an afterEach.
+ */
+export function stubGeometry(props: Record<string, number>): void {
+  for (const [key, value] of Object.entries(props)) {
+    const proto = prototypeFor(key)
+    const original = Object.getOwnPropertyDescriptor(proto, key)
+    Object.defineProperty(proto, key, { value, configurable: true })
+    restores.push(() => {
+      if (original) Object.defineProperty(proto, key, original)
+      else delete (proto as unknown as Record<string, unknown>)[key]
+    })
+  }
+}
+
+/** Undoes every stubGeometry call made since the last restore. */
+export function restoreGeometry(): void {
+  restores.splice(0).forEach((restore) => restore())
+}

From cb38b64dbe85fe2156415c9c6d31c281a10eb9b7 Mon Sep 17 00:00:00 2001
From: ravirajsinh45 <ravirajsinhdabhi86@gmail.com>
Date: Sat, 15 Aug 2026 13:26:35 +0530
Subject: [PATCH 3/4] fix(web): keep pre-existing annotations in place, and fit
 video to its element
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Blind review of this PR found three things.

Every annotation saved before this change is silently reinterpreted. The
overlay sizes its Fabric canvas from its parent and rescales stored objects
by w/_canvasWidth, and this PR moves that parent from the letterboxed
container to the picture box, so stored CONTAINER dimensions were being
divided into PICTURE dimensions. A mark drawn 25% down a 3:1 image in a
900x500 viewer landed 35% down with a 40% vertical squash — in the very
viewport it was authored in, where the old code placed it exactly right.
Saved data is now replayed against the container it was authored for and
then shifted into the picture box, which reproduces its original position,
and new data records its coordinate space so nothing has to be inferred.
Video is unaffected: VideoFrameConstraint predates this, so unmarked video
annotations are already picture-space and are left alone.

The overlay measured its box exactly once. That was safe when its parent was
permanently `absolute inset-0`, but the constraint now starts as the whole
pane (an undecoded <img> reports no size) and shrinks to the picture on load,
so an annotation opened from a ?commentId= deep link was scaled against the
pane. It now re-measures on resize, as AnnotationCanvas already did.

The claim that <video> always fills its container is false: the compare panes
render `max-h-full max-w-full`, the same shrink-only case the <img> work
exists for, so a video smaller than its pane had its overlay upscaled and
every annotation misplaced. Both constraints now measure the element's own
box, which is correct for filling and shrink-only alike, so the helper is
genuinely shared rather than two rules with a caveat.
---
 CHANGELOG.md                                  |   4 +-
 .../annotation-overlay-frame.test.tsx         | 141 ++++++++++++++++++
 .../__tests__/video-frame-constraint.test.tsx |  75 ++++++++--
 .../components/review/annotation-overlay.tsx  |  44 +++++-
 .../review/image-frame-constraint.tsx         |  29 +++-
 .../components/review/media-frame-context.tsx |  34 +++++
 apps/web/components/review/video-player.tsx   |  39 ++---
 apps/web/hooks/use-drawing.ts                 |   4 +
 apps/web/lib/__tests__/media-frame.test.ts    |  26 ++--
 apps/web/lib/media-frame.ts                   |  26 ++--
 10 files changed, 352 insertions(+), 70 deletions(-)
 create mode 100644 apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx
 create mode 100644 apps/web/components/review/media-frame-context.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e2c6273e..ce8c53f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,10 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Fixed
-- **Image annotations no longer drift when the viewer's aspect ratio changes** — drawings on images were authored and replayed against the full letterboxed container box rather than the picture inside it, so the same annotation pointed at a different part of the image depending on where it was viewed: sidebar collapsed vs expanded, a resized window, a compare pane, or a share link. A 3:1 image annotated in a 900x500 viewer and reopened in a 400x700 one put the mark 54% of the image height away from where it was drawn, far enough to land off the picture entirely. Images now get the same treatment video already had (`VideoFrameConstraint`), applied in the single viewer, both side-by-side compare panes, and the wipe view. (#185)
+- **Image annotations no longer drift when the viewer's aspect ratio changes** — drawings on images were authored and replayed against the full letterboxed container box rather than the picture inside it, so the same annotation pointed at a different part of the image depending on where it was viewed: sidebar collapsed vs expanded, a resized window, a compare pane, or a share link. A 3:1 image annotated in a 900x500 viewer and reopened in a 400x700 one put the mark 54% of the image height away from where it was drawn, far enough to land off the picture entirely. Images now get the same treatment video already had (`VideoFrameConstraint`), applied in the single viewer, both side-by-side compare panes, and the wipe view. Annotations saved before this change are replayed against the box they were authored in, so they stay exactly where they were drawn; new ones record which space they use, so no future reader has to guess. (#185)
 
 ### Changed
-- **Image and video overlays now share one contain-fit implementation** — the geometry that positions an annotation over the visible picture was written twice, once for `<img>` and once for `<video>`, with the two comparing aspect ratios differently. Both now call a single tested helper; only the reference box still differs, because `<video>` fills its container while an `<img>` under `max-*` does not. The video overlay also fills its container instead of collapsing to 0x0 when measured before layout.
+- **Image and video overlays now share one contain-fit implementation** — the geometry that positions an annotation over the visible picture was written twice, once for `<img>` and once for `<video>`, with the two comparing aspect ratios differently. Both now call a single tested helper that measures the element's own box, which is correct whether the element fills its container (`w-full h-full`, the main video player) or only ever shrinks to hug the media (`max-*`, every image and the compare-pane videos). That last case was previously fitted against the container, which upscaled the box and misplaced annotations on any compare-pane video smaller than its pane. The overlay also spans the element instead of collapsing to 0x0 when measured before layout, and re-measures when its box changes, so an annotation opened from a deep link before the image has decoded is no longer scaled against the wrong box.
 - **Pinned `starlette` and `botocore` so self-hosted Docker builds are reproducible** — both were floating transitives, so rebuilding the same commit on a different day could silently install different versions with no diff and no PR. FastAPI declares `starlette>=0.46.0` with no upper bound, meaning builds were free to cross a Starlette major (the ASGI layer under the SSE endpoint and the middleware stack); `botocore` is where S3 request signing lives, and unreviewed moves there have broken S3 compatibility before. Both are pinned to the versions already resolving, so no installed version changes.
 
 ### Fixed
diff --git a/apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx b/apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx
new file mode 100644
index 00000000..4f4b6413
--- /dev/null
+++ b/apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx
@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
+import { stubGeometry, restoreGeometry } from '@/test/geometry'
+
+/**
+ * The frame fix moved image annotations from container space to picture space.
+ * Annotations saved before that carry container dimensions in
+ * `_canvasWidth`/`_canvasHeight`, so replaying them against the picture box
+ * silently squashes and shifts them. These pin both spaces.
+ */
+
+const loaded: Array<Record<string, unknown>> = []
+let objects: Array<Record<string, unknown>> = []
+let dimensions: Array<{ width: number; height: number }> = []
+
+vi.mock('fabric', () => ({
+  Canvas: class {
+    setDimensions(d: { width: number; height: number }) {
+      dimensions.push(d)
+    }
+    async loadFromJSON(json: Record<string, unknown>) {
+      loaded.push(json)
+    }
+    getObjects() {
+      return objects
+    }
+    renderAll() {}
+    dispose() {}
+  },
+}))
+
+import { AnnotationOverlay } from '../annotation-overlay'
+import { MediaFrameContext } from '../media-frame-context'
+
+/** A Fabric-ish object that records what the overlay sets on it. */
+function makeObject(left: number, top: number) {
+  return {
+    left,
+    top,
+    scaleX: 1,
+    scaleY: 1,
+    set(patch: Record<string, number>) {
+      Object.assign(this, patch)
+    },
+    setCoords() {},
+  } as unknown as Record<string, unknown>
+}
+
+// A 3000x1000 image in a 900x500 pane: the picture box is 900x300 at top 100.
+const CONTAINER = { width: 900, height: 500 }
+const PICTURE = { left: 0, top: 100, width: 900, height: 300 }
+
+async function renderOverlay(
+  annotation: Record<string, unknown>,
+  legacy: React.ContextType<typeof MediaFrameContext>,
+) {
+  const view = render(
+    <MediaFrameContext.Provider value={legacy}>
+      <AnnotationOverlay annotation={annotation} />
+    </MediaFrameContext.Provider>,
+  )
+  await vi.waitFor(() => expect(loaded.length).toBeGreaterThan(0))
+  return view
+}
+
+describe('AnnotationOverlay coordinate spaces', () => {
+  beforeEach(() => {
+    loaded.length = 0
+    objects = []
+    dimensions = []
+    // The overlay is mounted inside the picture box, so that is what it measures.
+    stubGeometry({ offsetWidth: PICTURE.width, offsetHeight: PICTURE.height })
+    vi.stubGlobal('ResizeObserver', class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    })
+  })
+  afterEach(() => {
+    restoreGeometry()
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('renders a legacy container-space annotation where it was originally drawn', async () => {
+    // Drawn 25% down the picture: container y=175 with the picture starting at 100.
+    const obj = makeObject(0, 175)
+    objects = [obj as never]
+
+    await renderOverlay(
+      { objects: [{}], _canvasWidth: 900, _canvasHeight: 500 },
+      { containerWidth: CONTAINER.width, containerHeight: CONTAINER.height, left: PICTURE.left, top: PICTURE.top },
+    )
+
+    // Same viewport it was authored in, so no rescale — only the shift into the
+    // picture box's own origin.
+    expect(obj.scaleX).toBe(1)
+    expect(obj.scaleY).toBe(1)
+    expect(obj.top).toBe(75)
+    expect(obj.left).toBe(0)
+  })
+
+  it('leaves a picture-space annotation alone when the box matches', async () => {
+    const obj = makeObject(0, 75)
+    objects = [obj as never]
+
+    await renderOverlay(
+      { objects: [{}], _canvasWidth: 900, _canvasHeight: 300, _frameSpace: 'media' },
+      { containerWidth: CONTAINER.width, containerHeight: CONTAINER.height, left: PICTURE.left, top: PICTURE.top },
+    )
+
+    expect(obj.top).toBe(75)
+    expect(obj.scaleY).toBe(1)
+  })
+
+  it('rescales a picture-space annotation authored in a differently sized picture box', async () => {
+    const obj = makeObject(0, 150)
+    objects = [obj as never]
+
+    // Authored in a 450x150 picture box, replayed in 900x300: everything doubles.
+    await renderOverlay(
+      { objects: [{}], _canvasWidth: 450, _canvasHeight: 150, _frameSpace: 'media' },
+      { containerWidth: CONTAINER.width, containerHeight: CONTAINER.height, left: PICTURE.left, top: PICTURE.top },
+    )
+
+    expect(obj.scaleY).toBe(2)
+    expect(obj.top).toBe(300)
+  })
+
+  it('treats unmarked data as picture-space when there is no legacy frame (video)', async () => {
+    // VideoFrameConstraint predates the fix, so video annotations were always
+    // authored in picture space and must not be shifted.
+    const obj = makeObject(0, 75)
+    objects = [obj as never]
+
+    await renderOverlay({ objects: [{}], _canvasWidth: 900, _canvasHeight: 300 }, null)
+
+    expect(obj.top).toBe(75)
+    expect(obj.scaleY).toBe(1)
+  })
+})
diff --git a/apps/web/components/review/__tests__/video-frame-constraint.test.tsx b/apps/web/components/review/__tests__/video-frame-constraint.test.tsx
index d6a1d268..4e98ebae 100644
--- a/apps/web/components/review/__tests__/video-frame-constraint.test.tsx
+++ b/apps/web/components/review/__tests__/video-frame-constraint.test.tsx
@@ -12,9 +12,11 @@ vi.mock('@/lib/api', () => ({ api: { get: vi.fn() } }))
  * nothing pinned the box it computes. These tests pin it, which is what lets the
  * fit itself move into the shared `containBox` helper without guessing.
  *
- * Unlike the <img> constraint, this one derives the fit from the CONTAINER,
- * which is correct here: the <video> is `w-full h-full object-contain`, so it
- * always fills its container and letterboxes internally.
+ * The main player's <video> is `absolute inset-0 w-full h-full object-contain`,
+ * so it fills its container and letterboxes internally. The compare panes use
+ * `max-h-full max-w-full` instead, where the element only ever SHRINKS and so
+ * hugs the picture — the same distinction the <img> constraint exists for.
+ * Measuring the element's own box is correct for both.
  */
 function Harness() {
   const videoRef = React.useRef<HTMLVideoElement>(null)
@@ -43,9 +45,23 @@ afterEach(() => {
 })
 
 describe('VideoFrameConstraint', () => {
+  /**
+   * The main player's <video> is `absolute inset-0 w-full h-full`, so its own
+   * box is exactly the container's and sits at its origin. These cases describe
+   * that player, so the element box tracks the container.
+   */
+  const fillingPlayer = (w: number, h: number) => ({
+    clientWidth: w,
+    clientHeight: h,
+    offsetWidth: w,
+    offsetHeight: h,
+    offsetLeft: 0,
+    offsetTop: 0,
+  })
+
   it('letterboxes top/bottom when the video is wider than its container', () => {
     // 16:9 video in a square container: full width, bars above and below.
-    stubGeometry({ videoWidth: 1920, videoHeight: 1080, clientWidth: 800, clientHeight: 800 })
+    stubGeometry({ videoWidth: 1920, videoHeight: 1080, ...fillingPlayer(800, 800) })
     render(<Harness />)
 
     expect(wrapper()).toHaveStyle({
@@ -58,7 +74,7 @@ describe('VideoFrameConstraint', () => {
   })
 
   it('pillarboxes left/right when the video is taller than its container', () => {
-    stubGeometry({ videoWidth: 1080, videoHeight: 1920, clientWidth: 800, clientHeight: 800 })
+    stubGeometry({ videoWidth: 1080, videoHeight: 1920, ...fillingPlayer(800, 800) })
     render(<Harness />)
 
     expect(wrapper()).toHaveStyle({
@@ -70,26 +86,59 @@ describe('VideoFrameConstraint', () => {
   })
 
   it('adds no bars when the video and container already share an aspect ratio', () => {
-    stubGeometry({ videoWidth: 1920, videoHeight: 1080, clientWidth: 1600, clientHeight: 900 })
+    stubGeometry({ videoWidth: 1920, videoHeight: 1080, ...fillingPlayer(1600, 900) })
     render(<Harness />)
 
     expect(wrapper()).toHaveStyle({ left: '0px', top: '0px', width: '1600px', height: '900px' })
   })
 
-  it('fills the container until the video reports its dimensions', () => {
-    // videoWidth is 0 until loadedmetadata; the overlay must not collapse to 0x0.
-    stubGeometry({ videoWidth: 0, videoHeight: 0, clientWidth: 800, clientHeight: 800 })
+  it('covers the whole element until the video reports its dimensions', () => {
+    // videoWidth is 0 until loadedmetadata, so there is no aspect to fit yet.
+    // The overlay must not collapse to 0x0 — it spans the element's box, which
+    // for the filling player is the container.
+    stubGeometry({ videoWidth: 0, videoHeight: 0, ...fillingPlayer(800, 800) })
     render(<Harness />)
 
-    expect(wrapper()).toHaveStyle({ position: 'absolute', inset: '0px' })
+    expect(wrapper()).toHaveStyle({
+      position: 'absolute',
+      left: '0px',
+      top: '0px',
+      width: '800px',
+      height: '800px',
+    })
   })
 
   it('fills the container when the container itself has not been laid out', () => {
-    // Dividing by a 0-height container yields a NaN aspect, which used to fall
-    // through to a 0x0 overlay. Fill instead and recompute on the next resize.
-    stubGeometry({ videoWidth: 1920, videoHeight: 1080, clientWidth: 0, clientHeight: 0 })
+    // A 0-sized element yields no box at all. Fill instead of collapsing to
+    // 0x0, and recompute on the next resize.
+    stubGeometry({ videoWidth: 1920, videoHeight: 1080, ...fillingPlayer(0, 0) })
     render(<Harness />)
 
     expect(wrapper()).toHaveStyle({ position: 'absolute', inset: '0px' })
   })
+
+  it('hugs the element box when the video is smaller than its pane (compare panes)', () => {
+    // compare-overlay renders <video className="max-h-full max-w-full">, so a
+    // 100x200 video in an 800x400 pane renders at natural size, centred — it is
+    // NOT upscaled to the 200x400 the container fit would produce.
+    stubGeometry({
+      videoWidth: 100,
+      videoHeight: 200,
+      clientWidth: 800,
+      clientHeight: 400,
+      offsetWidth: 100,
+      offsetHeight: 200,
+      offsetLeft: 350,
+      offsetTop: 100,
+    })
+    render(<Harness />)
+
+    expect(wrapper()).toHaveStyle({
+      position: 'absolute',
+      left: '350px',
+      top: '100px',
+      width: '100px',
+      height: '200px',
+    })
+  })
 })
diff --git a/apps/web/components/review/annotation-overlay.tsx b/apps/web/components/review/annotation-overlay.tsx
index aaad72a5..9462939b 100644
--- a/apps/web/components/review/annotation-overlay.tsx
+++ b/apps/web/components/review/annotation-overlay.tsx
@@ -2,6 +2,7 @@
 
 import React, { useEffect, useRef } from 'react'
 import { useReviewStore } from '@/stores/review-store'
+import { MediaFrameContext, MEDIA_FRAME_SPACE } from './media-frame-context'
 
 interface AnnotationOverlayProps {
   /**
@@ -20,6 +21,24 @@ export function AnnotationOverlay({ annotation }: AnnotationOverlayProps = {}) {
   const active = annotation !== undefined ? annotation : storeActiveAnnotation
   const containerRef = useRef<HTMLDivElement>(null)
   const canvasRef = useRef<HTMLCanvasElement>(null)
+  const legacyFrame = React.useContext(MediaFrameContext)
+
+  // The constrained box is not final on mount: an <img> that has not decoded
+  // reports no size, so the constraint starts as the whole pane and shrinks to
+  // the picture on load. Re-running on that change keeps a deep-linked
+  // annotation from being scaled against the pane. AnnotationCanvas already
+  // does this via its own ResizeObserver.
+  const [boxSize, setBoxSize] = React.useState<string>('')
+  useEffect(() => {
+    const el = containerRef.current
+    // Absent in SSR and in older browsers; the initial measurement still stands.
+    if (!el || typeof ResizeObserver === 'undefined') return
+    const ro = new ResizeObserver(() => {
+      setBoxSize(`${el.offsetWidth}x${el.offsetHeight}`)
+    })
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [active])
 
   useEffect(() => {
     if (!active || !canvasRef.current || !containerRef.current) return
@@ -62,16 +81,29 @@ export function AnnotationOverlay({ annotation }: AnnotationOverlayProps = {}) {
         // Fall back to data.width (never set by Fabric) then current size.
         const origWidth = (data._canvasWidth as number) || (data.width as number) || w
         const origHeight = (data._canvasHeight as number) || (data.height as number) || h
-        const scaleX = w / origWidth
-        const scaleY = h / origHeight
+
+        // Data saved before the frame fix measured the whole letterboxed
+        // container, not the picture. Replay it against the container it was
+        // authored for and then shift into this box's origin, which reproduces
+        // exactly where it used to render. `legacyFrame` is null on surfaces
+        // that always authored in media space (video), where unmarked data is
+        // already correct.
+        const isLegacy = data._frameSpace !== MEDIA_FRAME_SPACE && legacyFrame !== null
+        const refWidth = isLegacy ? legacyFrame.containerWidth : w
+        const refHeight = isLegacy ? legacyFrame.containerHeight : h
+        const shiftX = isLegacy ? legacyFrame.left : 0
+        const shiftY = isLegacy ? legacyFrame.top : 0
+
+        const scaleX = refWidth / origWidth
+        const scaleY = refHeight / origHeight
 
         await fabricCanvas.loadFromJSON(active)
 
-        if (scaleX !== 1 || scaleY !== 1) {
+        if (scaleX !== 1 || scaleY !== 1 || shiftX || shiftY) {
           fabricCanvas.getObjects().forEach((obj: any) => {
             obj.set({
-              left: (obj.left ?? 0) * scaleX,
-              top: (obj.top ?? 0) * scaleY,
+              left: (obj.left ?? 0) * scaleX - shiftX,
+              top: (obj.top ?? 0) * scaleY - shiftY,
               scaleX: (obj.scaleX ?? 1) * scaleX,
               scaleY: (obj.scaleY ?? 1) * scaleY,
             })
@@ -92,7 +124,7 @@ export function AnnotationOverlay({ annotation }: AnnotationOverlayProps = {}) {
         try { fabricCanvas.dispose() } catch { /* ignore */ }
       }
     }
-  }, [active])
+  }, [active, legacyFrame, boxSize])
 
   if (!active) return null
 
diff --git a/apps/web/components/review/image-frame-constraint.tsx b/apps/web/components/review/image-frame-constraint.tsx
index bd89b626..e9eb541b 100644
--- a/apps/web/components/review/image-frame-constraint.tsx
+++ b/apps/web/components/review/image-frame-constraint.tsx
@@ -2,7 +2,8 @@
 
 import * as React from 'react'
 import { cn } from '@/lib/utils'
-import { renderedImageBox } from '@/lib/media-frame'
+import { renderedMediaBox } from '@/lib/media-frame'
+import { MediaFrameContext, type LegacyAnnotationFrame } from './media-frame-context'
 
 /**
  * Wraps children so they sit exactly over the visible picture, excluding the
@@ -34,13 +35,15 @@ export function ImageFrameConstraint({
   children: React.ReactNode
 }) {
   const [style, setStyle] = React.useState<React.CSSProperties>({ position: 'absolute', inset: 0 })
+  // What annotations saved before the frame fix were measured against.
+  const [legacyFrame, setLegacyFrame] = React.useState<LegacyAnnotationFrame | null>(null)
 
   React.useEffect(() => {
     const img = imgRef.current
     if (!img) return
 
     const calc = () => {
-      const box = renderedImageBox({
+      const box = renderedMediaBox({
         naturalWidth: img.naturalWidth,
         naturalHeight: img.naturalHeight,
         elementWidth: img.offsetWidth,
@@ -53,9 +56,23 @@ export function ImageFrameConstraint({
       // at 0x0, and recalculate on the next load/resize.
       if (!box) {
         setStyle({ position: 'absolute', inset: 0 })
+        // Filling the container, so the two spaces coincide.
+        setLegacyFrame(null)
         return
       }
 
+      const container = img.parentElement
+      setLegacyFrame(
+        container
+          ? {
+              containerWidth: container.clientWidth,
+              containerHeight: container.clientHeight,
+              left: box.left,
+              top: box.top,
+            }
+          : null,
+      )
+
       setStyle({
         position: 'absolute',
         left: box.left,
@@ -87,8 +104,10 @@ export function ImageFrameConstraint({
   }, [imgRef])
 
   return (
-    <div style={style} className={cn('overflow-hidden', className)}>
-      {children}
-    </div>
+    <MediaFrameContext.Provider value={legacyFrame}>
+      <div style={style} className={cn('overflow-hidden', className)}>
+        {children}
+      </div>
+    </MediaFrameContext.Provider>
   )
 }
diff --git a/apps/web/components/review/media-frame-context.tsx b/apps/web/components/review/media-frame-context.tsx
new file mode 100644
index 00000000..434437dd
--- /dev/null
+++ b/apps/web/components/review/media-frame-context.tsx
@@ -0,0 +1,34 @@
+'use client'
+
+import * as React from 'react'
+
+/**
+ * Describes the box that annotations used to be authored against, for surfaces
+ * where that box changed.
+ *
+ * Image annotations were historically drawn and replayed against the whole
+ * letterboxed CONTAINER; they now use the picture box. Data saved before that
+ * change carries container dimensions in `_canvasWidth`/`_canvasHeight`, so
+ * replaying it against the picture box shifts and squashes it. `AnnotationOverlay`
+ * uses this to put such data back exactly where it used to render.
+ *
+ * `null` means "this surface always authored in media space" — which is true of
+ * `VideoFrameConstraint`, since it predates the change. Unmarked data there is
+ * already correct and must not be shifted.
+ */
+export interface LegacyAnnotationFrame {
+  /** The container box, i.e. what old `_canvasWidth`/`_canvasHeight` measured. */
+  containerWidth: number
+  containerHeight: number
+  /** Where the media box sits inside that container. */
+  left: number
+  top: number
+}
+
+export const MediaFrameContext = React.createContext<LegacyAnnotationFrame | null>(null)
+
+/**
+ * Marker written into new annotation JSON so it is self-describing rather than
+ * guessed at. Absence means the data predates the frame fix.
+ */
+export const MEDIA_FRAME_SPACE = 'media'
diff --git a/apps/web/components/review/video-player.tsx b/apps/web/components/review/video-player.tsx
index fe823a71..d9268eba 100644
--- a/apps/web/components/review/video-player.tsx
+++ b/apps/web/components/review/video-player.tsx
@@ -13,7 +13,7 @@ import {
   Repeat,
 } from "lucide-react";
 import { cn, formatTime, formatTimecode, formatFrames } from "@/lib/utils";
-import { containBox } from "@/lib/media-frame";
+import { renderedMediaBox } from "@/lib/media-frame";
 import { api } from "@/lib/api";
 import { useReviewStore, type TimeFormat } from "@/stores/review-store";
 import { useVideoPlayer } from "@/hooks/use-video-player";
@@ -61,27 +61,28 @@ export function VideoFrameConstraint({
     if (!video) return;
 
     const calc = () => {
-      const container = video.parentElement;
-      if (!container) return;
-
-      const cw = container.clientWidth;
-      const ch = container.clientHeight;
-      const vw = video.videoWidth;
-      const vh = video.videoHeight;
+      // Measured from the element's own box, exactly like the image constraint.
+      // The main player's <video> is `w-full h-full object-contain`, so its box
+      // IS the container and this reduces to fitting against the container. The
+      // compare panes use `max-h-full max-w-full`, where the element only ever
+      // shrinks and so already hugs the picture — deriving the fit from the
+      // container there would upscale the box and misplace every annotation.
+      const box = renderedMediaBox({
+        naturalWidth: video.videoWidth,
+        naturalHeight: video.videoHeight,
+        elementWidth: video.offsetWidth,
+        elementHeight: video.offsetHeight,
+        offsetLeft: video.offsetLeft,
+        offsetTop: video.offsetTop,
+      });
 
-      if (!vw || !vh || !cw || !ch) {
-        // Metadata not loaded, or the container not laid out yet — fill it, and
-        // recompute on the next loadedmetadata/resize.
+      if (!box) {
+        // Not laid out yet — fill the container and recompute on the next
+        // loadedmetadata/resize.
         setStyle({ position: "absolute", inset: 0 });
         return;
       }
 
-      // Same contain fit the image constraint uses; only the reference box
-      // differs. <video> is w-full h-full object-contain, so it always fills the
-      // container and letterboxes inside it — hence fitting against the
-      // container is right here, where for <img> under max-* it would not be.
-      const box = containBox(vw, vh, cw, ch);
-
       setStyle({
         position: "absolute",
         left: box.left,
@@ -95,7 +96,11 @@ export function VideoFrameConstraint({
     video.addEventListener("loadedmetadata", calc);
     video.addEventListener("resize", calc);
 
+    // Observe both: under `max-*` a container resize only RECENTRES the element,
+    // moving offsetLeft/offsetTop without changing its own box, and
+    // ResizeObserver does not fire on a position-only change.
     const ro = new ResizeObserver(calc);
+    ro.observe(video);
     if (video.parentElement) ro.observe(video.parentElement);
 
     return () => {
diff --git a/apps/web/hooks/use-drawing.ts b/apps/web/hooks/use-drawing.ts
index 6e74325e..b15e490c 100644
--- a/apps/web/hooks/use-drawing.ts
+++ b/apps/web/hooks/use-drawing.ts
@@ -324,6 +324,10 @@ export function useDrawing(): UseDrawingReturn {
     // when the container size differs from when the annotation was drawn.
     json._canvasWidth = sharedFabric.width
     json._canvasHeight = sharedFabric.height
+    // Marks these coordinates as media-space (the picture/video box) rather than
+    // the letterboxed container, so the overlay never has to guess. Data without
+    // it predates the frame fix and is replayed against the container.
+    json._frameSpace = 'media'
     return json
   }, [])
 
diff --git a/apps/web/lib/__tests__/media-frame.test.ts b/apps/web/lib/__tests__/media-frame.test.ts
index 74f0853a..c5153aff 100644
--- a/apps/web/lib/__tests__/media-frame.test.ts
+++ b/apps/web/lib/__tests__/media-frame.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { containBox, renderedImageBox } from '../media-frame'
+import { containBox, renderedMediaBox } from '../media-frame'
 
 /**
  * The three shapes below were measured in a real browser (Chrome, file:// probe)
@@ -45,59 +45,59 @@ describe('containBox', () => {
   })
 })
 
-describe('renderedImageBox — measured browser cases', () => {
+describe('renderedMediaBox — measured browser cases', () => {
   it('image smaller than its container renders at natural size, centered (max-* does not upscale)', () => {
     // 100x200 image, 800x400 container, max-w-full max-h-full
     // browser: element box 100x200 at (350,100)
-    expect(renderedImageBox(el(100, 200, 100, 200, 350, 100)))
+    expect(renderedMediaBox(el(100, 200, 100, 200, 350, 100)))
       .toEqual({ left: 350, top: 100, width: 100, height: 200 })
   })
 
   it('image larger than its container is shrunk to the contain box', () => {
     // 4000x1000 image, 800x400 container
     // browser: element box 800x200 at (0,100)
-    expect(renderedImageBox(el(4000, 1000, 800, 200, 0, 100)))
+    expect(renderedMediaBox(el(4000, 1000, 800, 200, 0, 100)))
       .toEqual({ left: 0, top: 100, width: 800, height: 200 })
   })
 
   it('element that fills its container letterboxes internally (the <video> pattern)', () => {
     // 100x200 image in an element stretched to 800x400 by w-full h-full
     // browser: element box 800x400 at (0,0); the picture occupies 200x400 at (300,0)
-    expect(renderedImageBox(el(100, 200, 800, 400, 0, 0)))
+    expect(renderedMediaBox(el(100, 200, 800, 400, 0, 0)))
       .toEqual({ left: 300, top: 0, width: 200, height: 400 })
   })
 })
 
-describe('renderedImageBox — letterbox direction', () => {
+describe('renderedMediaBox — letterbox direction', () => {
   it('pads left/right when the image is taller than the element box', () => {
-    expect(renderedImageBox(el(1, 2, 400, 400)))
+    expect(renderedMediaBox(el(1, 2, 400, 400)))
       .toEqual({ left: 100, top: 0, width: 200, height: 400 })
   })
 
   it('pads top/bottom when the image is wider than the element box', () => {
-    expect(renderedImageBox(el(2, 1, 400, 400)))
+    expect(renderedMediaBox(el(2, 1, 400, 400)))
       .toEqual({ left: 0, top: 100, width: 400, height: 200 })
   })
 
   it('adds no padding when the aspect ratios already match', () => {
-    expect(renderedImageBox(el(1600, 900, 800, 450, 10, 20)))
+    expect(renderedMediaBox(el(1600, 900, 800, 450, 10, 20)))
       .toEqual({ left: 10, top: 20, width: 800, height: 450 })
   })
 
   it('carries the element offset through in both axes', () => {
-    expect(renderedImageBox(el(1, 1, 400, 200, 30, 40)))
+    expect(renderedMediaBox(el(1, 1, 400, 200, 30, 40)))
       .toEqual({ left: 130, top: 40, width: 200, height: 200 })
   })
 })
 
-describe('renderedImageBox — degenerate input', () => {
+describe('renderedMediaBox — degenerate input', () => {
   it('falls back to the element box before natural dimensions are known', () => {
     // <img> not decoded yet: naturalWidth/Height are 0
-    expect(renderedImageBox(el(0, 0, 800, 400, 5, 6)))
+    expect(renderedMediaBox(el(0, 0, 800, 400, 5, 6)))
       .toEqual({ left: 5, top: 6, width: 800, height: 400 })
   })
 
   it('returns null when the element has not been laid out', () => {
-    expect(renderedImageBox(el(100, 200, 0, 0))).toBeNull()
+    expect(renderedMediaBox(el(100, 200, 0, 0))).toBeNull()
   })
 })
diff --git a/apps/web/lib/media-frame.ts b/apps/web/lib/media-frame.ts
index bc9bd4bf..3fac3d11 100644
--- a/apps/web/lib/media-frame.ts
+++ b/apps/web/lib/media-frame.ts
@@ -1,6 +1,6 @@
-/** Geometry of a laid-out <img>, as read off the DOM. */
-export interface ImageFrameMetrics {
-  /** Intrinsic size. Both 0 until the image has decoded. */
+/** Geometry of a laid-out replaced element (<img> or <video>), read off the DOM. */
+export interface MediaFrameMetrics {
+  /** Intrinsic size. Both 0 until the media has loaded. */
   naturalWidth: number
   naturalHeight: number
   /** The element's own laid-out box (offsetWidth/offsetHeight). */
@@ -23,10 +23,9 @@ export interface Box {
  * fitting content into a box. `left`/`top` are relative to the box's own origin.
  *
  * Shared by the two constraint components so they cannot drift apart:
- * `renderedImageBox` below fits the picture inside the <img>'s own box and then
- * offsets by where that element sits, while `VideoFrameConstraint` fits the
- * video inside its container. Only the reference box differs — the fit itself
- * is one implementation.
+ * `renderedMediaBox` below fits the content inside the element's own box and
+ * then offsets by where that element sits. Both constraints use it, so they
+ * cannot drift apart.
  *
  * Compares aspect ratios by cross-multiplying rather than dividing, so an exact
  * fit (a 16:9 frame in a 16:9 box) stays exact instead of drifting a fraction of
@@ -55,10 +54,10 @@ export function containBox(
  * Annotations must be authored and displayed in THIS box rather than the
  * container's, or the same drawing lands somewhere else whenever the container's
  * aspect ratio changes (sidebar collapsed vs expanded, window resize, compare
- * panes, share view). See `renderedImageBox`'s callers.
+ * panes, share view). See `renderedMediaBox`'s callers.
  *
  * Deliberately measured from the ELEMENT's box, not the container's. The two
- * <img> patterns in this codebase behave differently:
+ * patterns in this codebase behave differently:
  *
  *   `max-w-full max-h-full`  the element already hugs the picture, since max-*
  *                            only shrinks — an image smaller than its container
@@ -67,18 +66,17 @@ export function containBox(
  *                            letterboxes inside it (what <video> does).
  *
  * Running the contain fit inside the element's own box is correct for both.
- * Deriving it from the container instead — which is what `VideoFrameConstraint`
- * does, correctly, for a filling <video> — silently upscales the box for any
- * image smaller than its container.
+ * Deriving it from the container instead silently upscales the box for any
+ * media smaller than its container.
  */
-export function renderedImageBox({
+export function renderedMediaBox({
   naturalWidth,
   naturalHeight,
   elementWidth,
   elementHeight,
   offsetLeft,
   offsetTop,
-}: ImageFrameMetrics): Box | null {
+}: MediaFrameMetrics): Box | null {
   // Not laid out yet — there is no box to report.
   if (!elementWidth || !elementHeight) return null
 

From e2113779abd03bb65244de2ceb1f40e600f944f1 Mon Sep 17 00:00:00 2001
From: ravirajsinh45 <ravirajsinhdabhi86@gmail.com>
Date: Sat, 15 Aug 2026 14:21:32 +0530
Subject: [PATCH 4/4] fix(web): migrate pre-existing annotations into picture
 space

The first pass at legacy compatibility replayed old annotations against the
container they were authored in, reproducing their original placement
exactly. That was faithful but not useful: those coordinates were always
container-relative, so the mark still slid around as the viewer's aspect
ratio changed. Manual testing showed exactly that, a mark drifting off the
detail it was drawn on.

The stored dimensions plus the image's intrinsic size are enough to do
better. The picture box inside the authoring container is just the contain
fit of the natural size into the stored `_canvasWidth`/`_canvasHeight`, so an
old mark can be re-expressed relative to the picture and replayed at any
size. Two marks on a 1200x800 image saved in a 520x870 pane sit 32.0% and
30.8% down the picture; they now render at that same point whether the pane
is 1400x900, 900x500 or 600x1000, where before each pane put them somewhere
different.

This does move existing annotations relative to where they rendered before,
which the CHANGELOG now says plainly. The new position is the one they were
drawn at.

The context carries the intrinsic size rather than the container box, since
that is all the reconstruction needs, and it is null on surfaces that always
authored in media space so video data is left alone.
---
 CHANGELOG.md                                  |  2 +-
 .../annotation-overlay-frame.test.tsx         | 49 +++++++++++++------
 .../components/review/annotation-overlay.tsx  | 38 ++++++++------
 .../review/image-frame-constraint.tsx         | 16 ++----
 .../components/review/media-frame-context.tsx | 33 +++++++------
 5 files changed, 78 insertions(+), 60 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ce8c53f8..1a72d193 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Fixed
-- **Image annotations no longer drift when the viewer's aspect ratio changes** — drawings on images were authored and replayed against the full letterboxed container box rather than the picture inside it, so the same annotation pointed at a different part of the image depending on where it was viewed: sidebar collapsed vs expanded, a resized window, a compare pane, or a share link. A 3:1 image annotated in a 900x500 viewer and reopened in a 400x700 one put the mark 54% of the image height away from where it was drawn, far enough to land off the picture entirely. Images now get the same treatment video already had (`VideoFrameConstraint`), applied in the single viewer, both side-by-side compare panes, and the wipe view. Annotations saved before this change are replayed against the box they were authored in, so they stay exactly where they were drawn; new ones record which space they use, so no future reader has to guess. (#185)
+- **Image annotations no longer drift when the viewer's aspect ratio changes** — drawings on images were authored and replayed against the full letterboxed container box rather than the picture inside it, so the same annotation pointed at a different part of the image depending on where it was viewed: sidebar collapsed vs expanded, a resized window, a compare pane, or a share link. A 3:1 image annotated in a 900x500 viewer and reopened in a 400x700 one put the mark 54% of the image height away from where it was drawn, far enough to land off the picture entirely. Images now get the same treatment video already had (`VideoFrameConstraint`), applied in the single viewer, both side-by-side compare panes, and the wipe view. Annotations saved before this change are migrated on read rather than left behind: the picture box inside their original container is reconstructed from the image's intrinsic size, so an old mark is re-expressed relative to the picture and lands where it was actually drawn, at any viewer size. **This means existing image annotations can appear in a different place after upgrading than they did before** — the new position is the correct one, and it no longer moves when the viewer is resized. New annotations record which coordinate space they use, so no future reader has to guess. (#185)
 
 ### Changed
 - **Image and video overlays now share one contain-fit implementation** — the geometry that positions an annotation over the visible picture was written twice, once for `<img>` and once for `<video>`, with the two comparing aspect ratios differently. Both now call a single tested helper that measures the element's own box, which is correct whether the element fills its container (`w-full h-full`, the main video player) or only ever shrinks to hug the media (`max-*`, every image and the compare-pane videos). That last case was previously fitted against the container, which upscaled the box and misplaced annotations on any compare-pane video smaller than its pane. The overlay also spans the element instead of collapsing to 0x0 when measured before layout, and re-measures when its box changes, so an annotation opened from a deep link before the image has decoded is no longer scaled against the wrong box.
diff --git a/apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx b/apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx
index 4f4b6413..445c2cf9 100644
--- a/apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx
+++ b/apps/web/components/review/__tests__/annotation-overlay-frame.test.tsx
@@ -4,9 +4,11 @@ import { stubGeometry, restoreGeometry } from '@/test/geometry'
 
 /**
  * The frame fix moved image annotations from container space to picture space.
- * Annotations saved before that carry container dimensions in
- * `_canvasWidth`/`_canvasHeight`, so replaying them against the picture box
- * silently squashes and shifts them. These pin both spaces.
+ * Annotations saved before that carry CONTAINER dimensions in
+ * `_canvasWidth`/`_canvasHeight`, with the picture occupying only a band inside
+ * them. The overlay reconstructs that band from the image's intrinsic size and
+ * re-expresses the mark relative to the picture, so old drawings land where
+ * they were actually drawn at any viewer size. These pin both spaces.
  */
 
 const loaded: Array<Record<string, unknown>> = []
@@ -46,9 +48,11 @@ function makeObject(left: number, top: number) {
   } as unknown as Record<string, unknown>
 }
 
-// A 3000x1000 image in a 900x500 pane: the picture box is 900x300 at top 100.
-const CONTAINER = { width: 900, height: 500 }
-const PICTURE = { left: 0, top: 100, width: 900, height: 300 }
+// A 3000x1000 image authored in a 900x500 pane: the picture box was 900x300
+// at top 100, so a mark at container y=175 is 25% down the picture.
+const NATURAL = { naturalWidth: 3000, naturalHeight: 1000 }
+const AUTHORED = { canvasWidth: 900, canvasHeight: 500 }
+const PICTURE = { width: 900, height: 300 }
 
 async function renderOverlay(
   annotation: Record<string, unknown>,
@@ -82,31 +86,46 @@ describe('AnnotationOverlay coordinate spaces', () => {
     vi.restoreAllMocks()
   })
 
-  it('renders a legacy container-space annotation where it was originally drawn', async () => {
-    // Drawn 25% down the picture: container y=175 with the picture starting at 100.
+  it('places a legacy container-space mark where it was drawn on the picture', async () => {
+    // Container y=175, i.e. 25% down a picture box that ran y=100..400.
     const obj = makeObject(0, 175)
     objects = [obj as never]
 
     await renderOverlay(
-      { objects: [{}], _canvasWidth: 900, _canvasHeight: 500 },
-      { containerWidth: CONTAINER.width, containerHeight: CONTAINER.height, left: PICTURE.left, top: PICTURE.top },
+      { objects: [{}], _canvasWidth: AUTHORED.canvasWidth, _canvasHeight: AUTHORED.canvasHeight },
+      NATURAL,
     )
 
-    // Same viewport it was authored in, so no rescale — only the shift into the
-    // picture box's own origin.
+    // Replayed into a picture box the same size as the authored one.
     expect(obj.scaleX).toBe(1)
     expect(obj.scaleY).toBe(1)
-    expect(obj.top).toBe(75)
+    expect(obj.top).toBe(75) // 25% of 300
     expect(obj.left).toBe(0)
   })
 
+  it('keeps a legacy mark at the same point on the picture in a bigger viewer', async () => {
+    const obj = makeObject(0, 175)
+    objects = [obj as never]
+
+    // Same stored data, replayed in a picture box twice as large.
+    stubGeometry({ offsetWidth: 1800, offsetHeight: 600 })
+    await renderOverlay(
+      { objects: [{}], _canvasWidth: AUTHORED.canvasWidth, _canvasHeight: AUTHORED.canvasHeight },
+      NATURAL,
+    )
+
+    // Still 25% down the picture, now 25% of 600.
+    expect(obj.top).toBe(150)
+    expect(obj.scaleY).toBe(2)
+  })
+
   it('leaves a picture-space annotation alone when the box matches', async () => {
     const obj = makeObject(0, 75)
     objects = [obj as never]
 
     await renderOverlay(
       { objects: [{}], _canvasWidth: 900, _canvasHeight: 300, _frameSpace: 'media' },
-      { containerWidth: CONTAINER.width, containerHeight: CONTAINER.height, left: PICTURE.left, top: PICTURE.top },
+      NATURAL,
     )
 
     expect(obj.top).toBe(75)
@@ -120,7 +139,7 @@ describe('AnnotationOverlay coordinate spaces', () => {
     // Authored in a 450x150 picture box, replayed in 900x300: everything doubles.
     await renderOverlay(
       { objects: [{}], _canvasWidth: 450, _canvasHeight: 150, _frameSpace: 'media' },
-      { containerWidth: CONTAINER.width, containerHeight: CONTAINER.height, left: PICTURE.left, top: PICTURE.top },
+      NATURAL,
     )
 
     expect(obj.scaleY).toBe(2)
diff --git a/apps/web/components/review/annotation-overlay.tsx b/apps/web/components/review/annotation-overlay.tsx
index 9462939b..1524340d 100644
--- a/apps/web/components/review/annotation-overlay.tsx
+++ b/apps/web/components/review/annotation-overlay.tsx
@@ -3,6 +3,7 @@
 import React, { useEffect, useRef } from 'react'
 import { useReviewStore } from '@/stores/review-store'
 import { MediaFrameContext, MEDIA_FRAME_SPACE } from './media-frame-context'
+import { containBox } from '@/lib/media-frame'
 
 interface AnnotationOverlayProps {
   /**
@@ -83,27 +84,32 @@ export function AnnotationOverlay({ annotation }: AnnotationOverlayProps = {}) {
         const origHeight = (data._canvasHeight as number) || (data.height as number) || h
 
         // Data saved before the frame fix measured the whole letterboxed
-        // container, not the picture. Replay it against the container it was
-        // authored for and then shift into this box's origin, which reproduces
-        // exactly where it used to render. `legacyFrame` is null on surfaces
-        // that always authored in media space (video), where unmarked data is
-        // already correct.
-        const isLegacy = data._frameSpace !== MEDIA_FRAME_SPACE && legacyFrame !== null
-        const refWidth = isLegacy ? legacyFrame.containerWidth : w
-        const refHeight = isLegacy ? legacyFrame.containerHeight : h
-        const shiftX = isLegacy ? legacyFrame.left : 0
-        const shiftY = isLegacy ? legacyFrame.top : 0
-
-        const scaleX = refWidth / origWidth
-        const scaleY = refHeight / origHeight
+        // container, not the picture. Reconstruct where the picture sat inside
+        // that container (the contain fit of the media's intrinsic size into
+        // the stored dimensions) so the mark can be expressed relative to the
+        // picture and replayed correctly at any size. `legacyFrame` is null on
+        // surfaces that always authored in media space (video), where unmarked
+        // data is already correct.
+        const isLegacy =
+          data._frameSpace !== MEDIA_FRAME_SPACE &&
+          legacyFrame !== null &&
+          !!legacyFrame.naturalWidth &&
+          !!legacyFrame.naturalHeight
+
+        const authored = isLegacy
+          ? containBox(legacyFrame!.naturalWidth, legacyFrame!.naturalHeight, origWidth, origHeight)
+          : { left: 0, top: 0, width: origWidth, height: origHeight }
+
+        const scaleX = w / authored.width
+        const scaleY = h / authored.height
 
         await fabricCanvas.loadFromJSON(active)
 
-        if (scaleX !== 1 || scaleY !== 1 || shiftX || shiftY) {
+        if (scaleX !== 1 || scaleY !== 1 || authored.left || authored.top) {
           fabricCanvas.getObjects().forEach((obj: any) => {
             obj.set({
-              left: (obj.left ?? 0) * scaleX - shiftX,
-              top: (obj.top ?? 0) * scaleY - shiftY,
+              left: ((obj.left ?? 0) - authored.left) * scaleX,
+              top: ((obj.top ?? 0) - authored.top) * scaleY,
               scaleX: (obj.scaleX ?? 1) * scaleX,
               scaleY: (obj.scaleY ?? 1) * scaleY,
             })
diff --git a/apps/web/components/review/image-frame-constraint.tsx b/apps/web/components/review/image-frame-constraint.tsx
index e9eb541b..69d3485c 100644
--- a/apps/web/components/review/image-frame-constraint.tsx
+++ b/apps/web/components/review/image-frame-constraint.tsx
@@ -56,22 +56,14 @@ export function ImageFrameConstraint({
       // at 0x0, and recalculate on the next load/resize.
       if (!box) {
         setStyle({ position: 'absolute', inset: 0 })
-        // Filling the container, so the two spaces coincide.
+        // Nothing measured yet; recalculated on the next load/resize.
         setLegacyFrame(null)
         return
       }
 
-      const container = img.parentElement
-      setLegacyFrame(
-        container
-          ? {
-              containerWidth: container.clientWidth,
-              containerHeight: container.clientHeight,
-              left: box.left,
-              top: box.top,
-            }
-          : null,
-      )
+      // Enough for the overlay to reconstruct the picture box inside the
+      // container that pre-fix annotations were authored against.
+      setLegacyFrame({ naturalWidth: img.naturalWidth, naturalHeight: img.naturalHeight })
 
       setStyle({
         position: 'absolute',
diff --git a/apps/web/components/review/media-frame-context.tsx b/apps/web/components/review/media-frame-context.tsx
index 434437dd..25f7ebcc 100644
--- a/apps/web/components/review/media-frame-context.tsx
+++ b/apps/web/components/review/media-frame-context.tsx
@@ -3,26 +3,27 @@
 import * as React from 'react'
 
 /**
- * Describes the box that annotations used to be authored against, for surfaces
- * where that box changed.
+ * Marks a surface whose annotations used to be authored against the whole
+ * letterboxed container rather than the media inside it.
  *
- * Image annotations were historically drawn and replayed against the whole
- * letterboxed CONTAINER; they now use the picture box. Data saved before that
- * change carries container dimensions in `_canvasWidth`/`_canvasHeight`, so
- * replaying it against the picture box shifts and squashes it. `AnnotationOverlay`
- * uses this to put such data back exactly where it used to render.
+ * Image annotations were historically drawn and replayed against the container,
+ * so a mark saved in a 520x870 pane carries coordinates in that pane's space,
+ * with the picture occupying only a band inside it. Replaying those numbers
+ * directly against the picture box would misplace them.
  *
- * `null` means "this surface always authored in media space" — which is true of
- * `VideoFrameConstraint`, since it predates the change. Unmarked data there is
- * already correct and must not be shifted.
+ * Knowing the media's intrinsic size is enough to undo it: the picture box
+ * inside the authoring container is just the contain fit of that size into the
+ * stored `_canvasWidth`/`_canvasHeight`, which lets the mark be expressed
+ * relative to the picture and replayed correctly at any size.
+ *
+ * `null` means "this surface always authored in media space" — true of
+ * `VideoFrameConstraint`, which predates the change, so its unmarked data is
+ * already correct and must be left alone.
  */
 export interface LegacyAnnotationFrame {
-  /** The container box, i.e. what old `_canvasWidth`/`_canvasHeight` measured. */
-  containerWidth: number
-  containerHeight: number
-  /** Where the media box sits inside that container. */
-  left: number
-  top: number
+  /** Intrinsic media size, once known. Both 0 before the media has loaded. */
+  naturalWidth: number
+  naturalHeight: number
 }
 
 export const MediaFrameContext = React.createContext<LegacyAnnotationFrame | null>(null)