Replace absolute positioning with CSS Anchor Positioning and Popover APIs for annotation layer

[arniebradfo]

There is a huge issue with the selection of elements and screen resizing. The data flow is basically backwards. I can't make a PR for reasons, but here is an AI summary of a way it could be fixed:

---

Problem

The annotation overlay layer currently uses a mix of CSS anchor positioning and legacy absolute positioning (left/top with stored coordinates). This hybrid approach causes several issues:

1. Stale coordinates on resize/scroll: Annotations store x (viewport %) and y (px from document top) at creation time. These go stale when the page layout changes — window resize, dynamic content, responsive breakpoints, or container queries all break marker placement.

2. Backwards data flow: The system captures a snapshot of element geometry (bounding box, x/y) and stores it in the annotation, then uses those stored numbers to position overlays. This inverts the correct dependency — the DOM element is the source of truth for where it is, and the overlay should follow it, not replay a recording of where it was.

3. Dual code paths: There's a "modern" path using anchorId + positionAnchor and a "legacy" fallback using stored coordinates. Both paths must be maintained, tested, and reasoned about. The fallback silently activates when the anchor element is unmounted or not found, often producing incorrect placement with no visible error.

4. Manual position calculations: Tooltip positioning, popup placement, and outline rendering all contain hand-written viewport-edge clamping, vertical flip logic, and scroll-offset math. These are fragile, don't account for all edge cases (zoom, transforms, iframes), and duplicate logic the browser already provides.

5. Fixed/sticky element handling: Special-case logic detects position: fixed and position: sticky elements and adjusts coordinate storage and rendering accordingly. This is error-prone and incomplete.

Proposal

Replace the absolute positioning system entirely with CSS Anchor Positioning and the Popover API:

CSS Anchor Positioning (anchor-name / position-anchor / position-area)

• Each annotated element gets anchor-name: --ann-{id} (this part already works).
• Markers, outlines, and popups use position-anchor + position-area to declaratively follow their target element. The browser handles scroll, resize, layout shifts, and stacking context automatically.
• Remove all stored x/y coordinates and boundingBox from the annotation data model. An annotation should reference its element (via selector or anchor ID), not store a geometry snapshot.
• The position-area property replaces manual flip/clamp logic — use position-try-fallbacks for automatic repositioning when space is constrained.

Popover API (popover attribute)

• The annotation popup (comment input) should use the native popover attribute instead of a manually z-indexed absolute div. This provides:
  • Correct top-layer stacking (above all other content, no z-index wars)
  • Built-in light-dismiss behavior
  • Focus management
  • No manual backdrop/click-outside handling

Specific elements to convert

Element	Current approach	Proposed approach
Selection outline (box around annotated element)	Absolute div with stored bounding box coords	Anchored position: fixed div using position-anchor + inset-area to cover the target element
Marker (numbered badge)	positionAnchor (modern) or left/top (legacy)	position-anchor only, placed at top right of target via position-area
Popup (comment input)	positionAnchor (modern) or inline style (legacy)	popover attribute + position-anchor, placed with position-area and position-try-fallbacks for auto-flip
Tooltip (hover preview)	Manual JS calculation with flip/clamp	position-anchor + position-area: top with position-try-fallbacks: flip-block

Data model changes

• Remove x, y, boundingBox from the annotation type — these are view-layer concerns that don't belong in persisted data.
• Keep selector as the primary element reference (survives page reload).
• Keep anchorId as the runtime anchor name (set on the live DOM element when resolved).
• On page load, resolve selector → DOM element → stamp with anchor-name. If the element no longer exists, show a "stale annotation" indicator instead of placing a marker at wrong coordinates.

Benefits

• Zero manual position math — the browser handles all layout-relative positioning
• Resize/scroll correctness for free — anchored elements track their target automatically
• One code path instead of modern + legacy fallback
• Simpler data model — annotations store what they reference, not where it was
• Better stacking — Popover API top-layer eliminates z-index conflicts with the host app

Browser support

CSS Anchor Positioning is supported in Chrome 125+, Edge 125+, and Firefox 131+. Safari support is in progress. Since this is a developer tool (not end-user facing), targeting modern browsers is acceptable.

---

Good Luck

[jameslcowan]

I agree with the runtime direction here: the overlay should follow the live DOM, and the current mixed anchor/absolute path is doing too much bookkeeping.

One thing I would be careful about is removing x / y / boundingBox from the persisted annotation model entirely. I would stop using them for live placement, but I would keep capture-time geometry as optional metadata. It is still useful for stale-annotation diagnostics, screenshot/export context, and debugging cases where the selector resolves differently after the page changes.

So the split I would aim for is:

• selectors / runtime anchors are the source of truth for live positioning
• captured geometry is historical context, not layout input

That gets you the single render path without throwing away the only "where was this when it was created?" breadcrumb.