65af268b86
- Added Zod as a dependency in package.json. - Updated pnpm-lock.yaml to include Zod. - Refactored API interfaces: exported new modules for perk, survivor, mission, and encounter. - Removed obsolete api-interfaces.ts file. - Enhanced tests for new schemas in api-interfaces.spec.ts, covering various validation scenarios.
3.2 KiB
Executable File
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
- Panel extension — sits below the video, always visible.
- Component extension — Twitch-managed icon attached to the video edge, expands to a card on click.
- 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.