# 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