docs: add sticker visibility toggle spec, plan, and version bump
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
162
docs/external-downtream-stickers.md
Normal file
162
docs/external-downtream-stickers.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Sticker Layer Visibility Control
|
||||
|
||||
Integration guide for the Jackbox Game Picker to toggle sticker layer visibility on the vote-app overlay.
|
||||
|
||||
## Overview
|
||||
|
||||
The vote-app overlay shows stickers that voters purchase throughout a game session. By default, stickers are visible whenever a poll is displayed and hidden between polls. This API allows the Game Picker host to override that behavior — showing accumulated stickers between rounds (a "sticker wall showcase") or hiding them during a poll for a cleaner view.
|
||||
|
||||
## Modes
|
||||
|
||||
| Mode | Behavior |
|
||||
|--------|-------------------------------------------------|
|
||||
| `auto` | Default — stickers visible during polls, hidden between polls |
|
||||
| `show` | Force stickers visible regardless of poll state |
|
||||
| `hide` | Force stickers hidden regardless of poll state |
|
||||
|
||||
**Auto-reset:** When a new poll is generated, mode automatically resets to `auto`. The Game Picker receives a notification so its UI can update.
|
||||
|
||||
## WebSocket Integration (Primary)
|
||||
|
||||
### Sending: Set Mode
|
||||
|
||||
Send on the existing upstream WebSocket connection (`/api/sessions/live`):
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "stickers.setMode",
|
||||
"data": {
|
||||
"mode": "show"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Valid values for `mode`: `"auto"`, `"show"`, `"hide"`.
|
||||
|
||||
### Receiving: Mode Changed
|
||||
|
||||
The vote-app sends this whenever the mode changes (including auto-resets):
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "stickers.mode",
|
||||
"mode": "auto"
|
||||
}
|
||||
```
|
||||
|
||||
**When you'll receive this:**
|
||||
- After you send `stickers.setMode` (confirmation)
|
||||
- When a new poll starts (mode resets to `auto`)
|
||||
- When a session starts/ends (mode resets to `auto`)
|
||||
- When the debug panel changes the mode
|
||||
|
||||
**Use this to keep your UI in sync.** If you show a toggle button, update its state whenever you receive this message.
|
||||
|
||||
## HTTP API (Fallback)
|
||||
|
||||
### Set Mode
|
||||
|
||||
```
|
||||
PUT /api/stickers/visibility
|
||||
```
|
||||
|
||||
**Headers:**
|
||||
- `Content-Type: application/json`
|
||||
- `X-API-Key: <UPSTREAM_API_KEY>`
|
||||
|
||||
**Request body:**
|
||||
```json
|
||||
{ "mode": "show" }
|
||||
```
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{ "mode": "show", "previousMode": "auto" }
|
||||
```
|
||||
|
||||
**Error responses:**
|
||||
- `403` — Invalid or missing API key
|
||||
- `400` — Invalid mode value (not `auto`/`show`/`hide`)
|
||||
|
||||
### Get Current Mode
|
||||
|
||||
```
|
||||
GET /api/stickers/visibility
|
||||
```
|
||||
|
||||
No auth required.
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{ "mode": "auto" }
|
||||
```
|
||||
|
||||
Use this on startup to sync your UI state.
|
||||
|
||||
## Suggested UX
|
||||
|
||||
### Simple Toggle Button
|
||||
|
||||
A two-state toggle that alternates between `show` and `auto`:
|
||||
|
||||
```
|
||||
[Show Stickers] ← when mode is "auto" or "hide"
|
||||
[Hide Stickers] ← when mode is "show"
|
||||
```
|
||||
|
||||
When receiving `stickers.mode` with `"auto"`, reset the button to "Show Stickers" state.
|
||||
|
||||
### Three-State Control (Advanced)
|
||||
|
||||
If you prefer explicit control:
|
||||
|
||||
```
|
||||
( ) Auto — stickers follow poll visibility
|
||||
(•) Show — always visible
|
||||
( ) Hide — always hidden
|
||||
```
|
||||
|
||||
Highlight the current selection. Update when receiving `stickers.mode`.
|
||||
|
||||
### Handling Auto-Reset
|
||||
|
||||
When a poll starts, mode resets and you'll receive:
|
||||
```json
|
||||
{ "type": "stickers.mode", "mode": "auto" }
|
||||
```
|
||||
|
||||
Your UI should:
|
||||
1. Update the button/toggle state to reflect `auto`
|
||||
2. Optionally show a brief indicator ("Sticker mode reset")
|
||||
|
||||
## Example Flows
|
||||
|
||||
### Show stickers between games
|
||||
|
||||
1. Game ends, poll results shown, winner selected
|
||||
2. Host wants to show off sticker wall before next game
|
||||
3. Host clicks "Show Stickers" → sends `stickers.setMode` with `mode: "show"`
|
||||
4. Sticker layer becomes visible on the overlay
|
||||
5. Next poll starts → mode auto-resets to `auto`
|
||||
6. Game Picker receives `stickers.mode: "auto"` → updates button
|
||||
|
||||
### Hide stickers during a busy poll
|
||||
|
||||
1. Poll is active, stickers are distracting
|
||||
2. Host clicks "Hide Stickers" → sends `stickers.setMode` with `mode: "hide"`
|
||||
3. Sticker layer hides on the overlay
|
||||
4. Poll ends, new poll starts → mode auto-resets to `auto`
|
||||
5. Stickers show normally with the new poll
|
||||
|
||||
### Sync on reconnect
|
||||
|
||||
1. Game Picker reconnects to vote-app
|
||||
2. Call `GET /api/stickers/visibility` to get current mode
|
||||
3. Update UI to match
|
||||
|
||||
## Notes
|
||||
|
||||
- Stickers accumulate in the DOM regardless of visibility — toggling just shows/hides the layer
|
||||
- The sticker layer is at z-index 1, behind the poll overlay (z-index 9997)
|
||||
- Sticker data persists across server restarts (stored in SQLite)
|
||||
- Stickers are cleared on `session.started` and `session.ended` events
|
||||
Reference in New Issue
Block a user