ar

AR / POI Overlay Components

The AR family renders points of interest over a live video or still image: markers that track detected objects, resolve their own overlaps, and expand into cards on interaction.

Every component here carries full class JSDoc, and Storybook autodocs surfaces it. This file covers what no single component's JSDoc can: how the pieces compose, and the traps that only show up across the family.

Layering

Five levels, outermost first. Each owns exactly one concern; pushing logic up or down the stack is the usual cause of bugs here.

<obc-poi-controller>          geometry: maps detection coordinates onto the media
  └─ media slot: <video> / <img>
  └─ <obc-poi-layer-stack>    selection across layers
       └─ <obc-poi-layer>     overlap resolution + layer height
            ├─ <obc-poi-data> a target
            └─ <obc-poi-group> a cluster of targets

• obc-poi-controller — the only component that knows about the media. It observes the slotted <video>/<img>, tracks natural vs rendered size, and applies fit (contain | cover) so marker coordinates land on the right pixels. It also filters detections by confidenceMin and classFilter, and drives frameIndex for frame-by-frame playback. Nothing below it should read media dimensions.
• obc-poi-layer-stack — coordinates selection across sibling layers via selection-mode, emitting layer-selection-changed.
• obc-poi-layer — resolves overlaps and reports its computed height. This is where most layout behaviour lives.
• obc-poi-group — one cluster: collapsed trigger ↔ expanded spread.
• obc-poi-data / -vessel / -aton — individual targets.

Overlap resolution: two strategies, not one

obc-poi-layer's overlapMode picks between two genuinely different algorithms, each with its own helper module. They do not share state, and a change to one does not affect the other:

Mode	Helper	Behaviour
grouping (default)	poi-layer/poi-layer-grouping-utils.ts	Builds overlap clusters and creates/removes auto-groups, preserving front / behind / pre-group states across the transition. Threshold set: enter, exit, pre, behind.
crossing	poi-layer/poi-layer-crossing-utils.ts	Leaves targets independent and continuously nudges their horizontal offsets so they stop crossing. Tracks previous positions, crossing order and last effective X per target.