KoalaSync/shared/README.md

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. 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.