# 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.

## 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.