# 0001 — Twitch Video Overlay over Panel extension

- **Status:** Accepted
- **Date:** 2026-05-06

## Context and problem statement

Twitch offers three extension placements: Panel (fixed 318×496px below the video, always visible), Component (small attached affordance on the video that expands), and Video Overlay (full transparent layer over the stream, can be minimised to a configured slot).

Fog Expedition is an autonomous, tick-based ZPG that runs in parallel to a streamer's gameplay. The viewer experience needs to feel ambient and atmospheric — not a separate UI demanding attention, but a layer of fiction that complements the stream.

Which extension placement best supports this experience?

## Decision drivers

- **Aesthetic fit.** The "lantern in the fog" concept needs a small, persistent, atmospheric presence over the stream — not a docked widget below it.
- **Glanceability.** Viewers should be able to consume the latest log line in peripheral vision without taking focus from gameplay.
- **Streamer control.** Streamers need to position the overlay so it doesn't obscure their gameplay HUD.
- **Review feasibility.** All three pass Twitch review with reasonable design discipline; Video Overlay has stricter pixel-obstruction checks.
- **Ambient event surfacing.** Significant moments (injury, sacrifice) should briefly surface without forcing the viewer to open anything.

## Considered options

1. **Panel extension** — sits below the video, always visible.
2. **Component extension** — Twitch-managed icon attached to the video edge, expands to a card on click.
3. **Video Overlay extension** — custom-positioned element drawn over the stream, with a configured collapsed/minimised state.

## Decision outcome

**Chosen: Video Overlay extension.**

The minimised state is a custom "lantern + ticker" element (~290×56px) positioned at a streamer-configured corner. It shows the current survivor's state colour and the latest log line. Significant events ("ambient event" state) briefly surface a larger card before auto-dismissing. Click expands the lantern to a full survivor + log + action card (~320×440px) with a backdrop dim.

This is the only placement that supports the ambient-event surfacing pattern, and the only one that lets viewers consume the experience entirely in peripheral vision.

## Consequences

### Positive

- Aesthetic latitude — the lantern is custom-designed, not Twitch-chrome-constrained.
- Viewers see content without taking focus; the experience is genuinely ambient.
- Streamer config screen lets broadcasters position the overlay to avoid their HUD.

### Negative

- Stricter Twitch review: overlays must not obscure meaningful gameplay pixels, must include a streamer kill switch, and the visibility lifecycle (`onVisibilityChanged`) is more nuanced than a Panel.
- Higher design discipline required — bad overlays drive streamers to disable the extension across all viewers.
- Anonymous viewer experience must be designed explicitly (panel placement makes this trivial; overlay does not).

### Neutral

- The visibility lifecycle becomes an explicit concern. When the overlay is hidden, PubSub processing and polling must stop; when re-shown, state must be re-fetched. This shapes how the frontend store reconciles.