# @hiyve/react-annotations

Live annotation overlay for Hiyve video tiles. Drop a transparent canvas on top of a screen-share (or any video) and let participants draw on it; strokes replicate to every peer in real time.

## Installation

```bash
npm install @hiyve/react-annotations @hiyve/react @hiyve/core @hiyve/utilities @mui/material
```

## Quick start

```tsx
import { useState, useRef } from 'react';
import {
  AnnotationCanvas,
  AnnotationToolbar,
  useAnnotationSync,
} from '@hiyve/react-annotations';

function ScreenShareTile({ videoRef, shareId, localUserId, isOwner, isSharer }) {
  const [tool, setTool] = useState({ color: '#ff3366', width: 0.004 });
  const sync = useAnnotationSync({ shareId, localUserId, isOwner, isSharer });

  return (
    <>
      <AnnotationCanvas
        videoRef={videoRef}
        shareId={shareId}
        localUserId={localUserId}
        isOwner={isOwner}
        isSharer={isSharer}
        tool={tool}
        sync={sync}
      />
      <AnnotationToolbar
        tool={tool}
        onToolChange={setTool}
        onClearMine={sync.clearMine}
        onClearAll={sync.clearAll}
        canClearAll={sync.canClearAll}
      />
    </>
  );
}
```

## Features

- **Transparent SVG overlay** that mounts over a `<video>` element and tracks its content rect (handles `objectFit: contain` letterbox / pillarbox math).
- **Aspect-ratio-invariant strokes**: each stroke records the source aspect ratio at authoring time, so it stays anchored to the source content even when peers' tile sizes differ or the source resolution changes mid-share.
- **Real-time sync** over the WebRTC data channel — works on every browser, no relay required.
- **Late-joiner snapshot**: peers who join after drawing started receive the current stroke set automatically.
- **Permissions**: configurable per-action — anyone can draw and clear-mine by default; sharer + room owner can clear-all.
- **Pointer Events** uniformly: mouse, touch, pen.

## Requirements

- Mounted under `HiyveProvider` from `@hiyve/react`.
- React 18+.
- A `<video>` element ref to overlay (typically the screen-share tile's video).

## Public API

| Export | Kind | Purpose |
|---|---|---|
| `AnnotationCanvas` | component | The transparent SVG overlay |
| `AnnotationToolbar` | component | Pen + colour swatches + width + clear |
| `useAnnotationSync` | hook | Stroke state + transport |
| `useVideoContentRect` | hook | Live content rect of a `<video>` under `objectFit: contain` |
| `useScreenSharingParticipants` | hook | Filter `useParticipants()` to screen sharers |
| `Stroke`, `Point`, `AnnotationPermission`, ... | types | Public type surface |
| `DEFAULT_COLORS`, `DEFAULT_TOOL`, ... | defaults | Sensible starting values + merge functions |

See the per-component README sections below for full prop tables.

## Customization

Both `AnnotationCanvas` and `AnnotationToolbar` accept `labels`, `colors`, and `styles` overrides — same merge-function pattern used elsewhere in the SDK.