# Companion native overlay

Lumi Companion includes a Windows-native monitor overlay under **Plugins → Lumi
Overlay**. It is independent of Lumi's OBS browser-source overlays: it uses
Avalonia controls in a transparent, topmost, click-through window and never
loads HTML or provider credentials.

## Data and authorization

The server endpoint is `/plugins/lumi_overlay/live`. It authenticates the same
paired device credential as Companion and requires `overlay.read.v1`. New
pairings receive the capability. Existing active devices receive it through a
one-time migration; a later capability removal is not silently undone.

Lumi reuses its normalized Twitch, YouTube, and Discord chat/event streams.
Selections are filtered on the server, messages are sanitized and bounded, and
a connection receives live items only—no history is replayed after startup or
reconnect. Missing provider scopes disable only their affected event types and
are reported in feed status.

The native renderer uses the same normalized badge, emote, and Discord media
payloads as Lumi's OBS browser overlay. HTTPS artwork is downloaded with strict
size, dimension, frame-count, and decoded-pixel limits. Animated GIF/WebP
emotes and images retain their bounded frame timing; unsupported video-only
embeds use their supplied preview image when available.

## Window behavior

The selected monitor, layout, styling, sources, event types, visibility mode,
animation lifecycle, and hotkeys are stored atomically under the current
Windows user's Companion data directory. A missing monitor temporarily falls
back to the primary screen without changing the saved monitor.

The overlay reapplies click-through, non-activating, tool-window and topmost
styles after display, power, and Windows session changes. It calls
`SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE)` and reports the result in the
settings page. This is best-effort Windows protection: OBS and other capture
software can use capture paths that do not honor display affinity.

`When live` is activated only by a selected Twitch or YouTube source. Discord
does not activate it. Sample preview and the visibility override temporarily
take precedence, then restore the saved mode.

## Verification

From PowerShell:

```powershell
companion/scripts/verify-lumi-overlay.ps1
```

The regular `npm run verify:all` suite also exercises the server protocol,
filtering, no-backlog behavior, queue bounds, capability migration, and
revocation behavior.