# KoalaSync Shared Constants

This directory is the source of truth for protocol constants and shared browser/server data.

## Where You Are

- `constants.js`: protocol version, app version, official URLs/token, event names, control modes, capabilities, and timing constants.
- `blacklist.js`: domains hidden by the popup's clutter filter.
- `names.js`: generated username parts and helper used by the extension.
- `extension/shared/`: generated mirror created by `npm run build:extension`; do not edit that mirror directly.

## Syncing with the Extension

> [!IMPORTANT]
> After modifying any file in this directory, run `npm run build:extension` from the repository root.

Browser extensions cannot import files outside their own root directory, so the build script copies shared files into `extension/shared/` and injects selected constants into `content.js`.

## Security & Versioning Constants

- `PROTOCOL_VERSION`: exact protocol version required during `join_room`.
- `APP_VERSION`: extension/app version, injected from release tags by CI.
- `OFFICIAL_SERVER_URL`: default public relay endpoint.
- `OFFICIAL_LANDING_PAGE_URL`: public website and invitation bridge origin.
- `OFFICIAL_SERVER_TOKEN`: public client token used to reject non-KoalaSync Socket.IO clients. It is not a secret; see `docs/KNOWN_LIMITATIONS.md`.
- `SUPPORT_URL` and `GITHUB_URL`: public project links used by the extension UI.

## Control Modes & Capabilities

- `CONTROL_MODES.EVERYONE`: default room mode; any peer may control playback.
- `CONTROL_MODES.HOST_ONLY`: only the host and promoted controllers may move playback.
- `CAPABILITIES.HOST_CONTROL`: relay supports host-only room authority.
- `CAPABILITIES.CO_HOST`: relay supports promoted controller peers.

Clients should enable capability-gated UI only when the relay advertises the matching flag in `room_data.capabilities`.

## Protocol Events

For the complete event list, read the `EVENTS` object in [`constants.js`](constants.js). Current event groups:

| Event | Direction | Purpose |
|:---|:---|:---|
| `JOIN_ROOM` | Client -> Server | Join or create a room with credentials and protocol version |
| `LEAVE_ROOM` | Client -> Server | Leave the current room |
| `ROOM_DATA` | Server -> Client | Initial room snapshot, peers, host state, capabilities |
| `ERROR` | Server -> Client | Connection, auth, capacity, or protocol error |
| `SET_CONTROL_MODE` | Client -> Server | Host switches between `everyone` and `host-only` |
| `CONTROL_MODE` | Server -> Client | Host/control-mode/controller snapshot changed |
| `SET_PEER_ROLE` | Client -> Server | Host promotes or demotes a co-host/controller |
| `PLAY` / `PAUSE` / `SEEK` | Bidirectional relay | Media control commands |
| `PEER_STATUS` | Bidirectional relay | Heartbeat and current media state |
| `FORCE_SYNC_PREPARE` | Bidirectional relay | Phase 1: pause and seek peers to a target time |
| `FORCE_SYNC_ACK` | Bidirectional relay | Phase 1 confirmation that a peer is ready |
| `FORCE_SYNC_EXECUTE` | Bidirectional relay | Phase 2: resume playback together |
| `EVENT_ACK` | Server -> Client | Delivery confirmation for UI feedback |
| `EPISODE_LOBBY` | Bidirectional relay | Episode transition lobby started |
| `EPISODE_READY` | Bidirectional relay | Peer has loaded the episode and is ready |
| `EPISODE_LOBBY_CANCEL` | Bidirectional relay | Active episode lobby cancelled |
| `GET_ROOMS` / `ROOM_LIST` | Client <-> Server | Room discovery with server-side cooldown |
| `PING` / `PONG` | Client <-> Server/Peer | Server RTT and peer latency checks |

## Timing Constants

- `HEARTBEAT_INTERVAL`: content heartbeat interval in milliseconds.
- `FORCE_SYNC_TIMEOUT`: max wait for force-sync ACKs.
- `EPISODE_LOBBY_TIMEOUT`: max wait for episode-lobby readiness.

## Do Not Break

- Do not rename events without updating `docs/PROTOCOL.md`, `server/index.js`, `extension/background.js`, and the build-injected `content.js` path.
- Do not edit `extension/shared/` directly.
- Keep new server-gated features behind `CAPABILITIES` so old clients and old relays degrade cleanly.
- Run `npm run build:extension` and `npm run verify` after protocol changes.
