BGS Docs

Viewer API

For TypeScript types, validation, and reusable integration helpers, see the protocol library.

BGS loads your viewer in an iframe and calls window[name].launch(selector) to get its event emitter. registerViewer creates this entry point for you. You supply the UI and handlers for the events below.

For bundle hosting, see Adding a game.

Use plain data for event payloads. The iframe bridge uses postMessage; functions, DOM nodes, and reactive proxies cannot be cloned. Although structured cloning can copy Map and Set, BGS payloads should use JSON-compatible objects and arrays. For a Svelte 5 $state value, send $state.snapshot(value).

Viewer registration

registerViewer

import { registerViewer } from "@boardgamers/protocol/viewer";

registerViewer<State, Move>(name, mount, {
	stateSchema,
	moveSchema,
	onInvalid: ({ event, message }) => console.warn(event, message),
});

The optional third argument validates game-specific payloads. name must be an unused JavaScript global identifier, such as tictactoe; configure that name in BGS. The library registers the global itself. If your bundler requires an IIFE name (Vite's build.lib.name), use a different one, such as tictactoeBundle.

mount({ target, move, openPlayer, ... }) runs on each launch. It receives the selected DOM container and the commands below. Return onState and whichever optional callbacks your UI needs. No emitter is exposed to the mount callback.

Create components and chat controllers inside mount so each launch gets fresh instances. Mounting is synchronous; onState and onLog may await rendering. Failures in onState, onUpdate, or onLog call onError (or log the error); later callbacks can still run.

The return value of registerViewer is only needed for local tests or explicit cleanup:

Method Behavior
launch(selector) Replace the previous UI and return the transport emitter. BGS calls this; a local host can too.
diagnostics(capabilities?) Report the current instance's handler coverage. Before launch or after disposal, no handlers are installed.
destroy() Dispose the instance; safe to repeat. The registration remains available for another launch.

The library sends ready after the first successful state render. By default it requests full state on state:updated and gamelog; onUpdate and onLog respectively replace those defaults. On disposal it removes listeners, cancels timers, destroys chat, calls your destroy hook, and empties the mount container. See the short example or complete tic-tac-toe viewer.

Commands

Destructure these from the mount callback's argument. They are also methods on the object returned by createViewer.

Command Purpose
move(payload) Submit your game's typed move, such as move({ x: 1, y: 2 }).
openPlayer(index) Open the profile for a zero-based player seat.
hoverPlayer(index, anchor) / leavePlayer() Show or dismiss the host player card.
openBoardgame() Open the current boardgame page.
updatePreference(name, value) Save a preference; values are strings, booleans, or null.
fetchState() Request the full state. Updates trigger this by default.
fetchLog({ start, end? }) Request a log range, inclusive of both endpoints.
addLog(lines) / replaceLog(lines) Append or replace string entries in BGS's journal.
setReplayInfo({ start, current, end }) Update BGS's replay controls.
undo() Take back the player's last move (solo games, including engine-managed opponents, 0.10.0).

Commands return false for invalid payloads or after disposal. true means the payload passed local validation, not that BGS accepted the action. The engine still validates moves. Use ChatController for chat sends and read reports; readiness is handled internally.

Callbacks

Return these from mount, or pass them as options to createViewer:

Callback Purpose
onState(state) Required. Render the game state; may return a promise.
onUpdate() Request an update, replacing the default fetchState().
onPlayer({ index }) Store the viewer's seat; undefined means spectator.
onPreferences(preferences) Apply game preferences, including shared sound and color-blind settings.
onAvatars(urls) Apply player avatars in seat order.
onTheme({ dark }) Apply theme changes.
onLog({ start, end?, data }) Apply a log slice; may return a promise. Replaces the default state fetch.
onReplayStart() / onReplayTo(index) / onReplayEnd() Implement replay, and call setReplayInfo as the position changes.
onUndoAvailable(available) Show or hide your undo control (solo games, including engine-managed opponents, 0.10.0).
onError(error) Handle a failed state, update, or log callback.

Only onState is required to construct the helper. Interactive games should also handle onPlayer; the core coverage check flags missing player handling. Omit unused callbacks instead of adding empty ones. Return a chat controller to connect chat, and destroy() to unmount your framework.

createViewer and ViewerEmitter

createViewer({ onState, onPlayer?, chat?, ... }) supplies the same commands, callbacks, validation, state refreshes, and readiness handling without registering a global or managing DOM. It returns the commands plus diagnostics, destroy, and an emitter for connecting BGS or a local test host.

Use new ViewerEmitter<State, Move>(validation?) only when you need to own the transport and lifecycle yourself. Incremental logs work with the helpers above. It provides typed, validated events without automatic handlers. on and once return cleanup functions. destroy permanently disconnects it; later events return false. attachChat(emitter, chat) installs chat handlers and returns cleanup that also destroys the controller.

Incremental logs

BGS sends an initial state, update notifications, and log slices (including the result of your own move). Return onUpdate and onLog to apply slices instead of fetching the full state after each change. The same callbacks work with registerViewer and createViewer.

This example expects state.log and logSlice to contain arrays of strings:

import { registerViewer } from "@boardgamers/protocol/viewer";

type LogState = { log: string[] };

registerViewer<LogState, never>("logDemo", ({ target, fetchLog }) => {
	let entries: string[] = [];
	const render = () => {
		target.textContent = entries.join("\n");
	};

	return {
		onState(state) {
			entries = [...state.log];
			render();
		},
		onUpdate() {
			fetchLog({ start: entries.length });
		},
		onLog({ start, data }) {
			if (!Array.isArray(data) || !data.every((entry) => typeof entry === "string")) {
				throw new Error("Invalid log slice");
			}
			if (start > entries.length) {
				fetchLog({ start: entries.length });
				return;
			}
			entries.splice(start, data.length, ...data);
			render();
		},
	};
});

onState, onUpdate, and onLog run in arrival order, awaiting each callback. Issue requests from onUpdate and handle their replies in onLog; do not wait inside one callback for a later queued callback to run.

The viewer owns the cursor because logSlice can return any structure. Merge by start to handle overlapping slices, and request missing entries when there is a gap. If you also need fresh private state or other data absent from the log, call fetchState() explicitly. Without onUpdate or onLog, that event keeps its default full-state refresh.

Event validation

The emitter checks event payloads before delivery. Unknown event names return false; invalid known events call onInvalid (or console.warn) and return false. The library validates game-specific state and moves only when you supply stateSchema and moveSchema. Each validator implements parse(value: unknown).

Custom adapters can use validateEvent(name, payload) or downlinkSchemas and uplinkSchemas from @boardgamers/protocol. validateEvent returns parsed data or throws. These describe emitter payloads, not the bridge's raw window messages. The game engine remains responsible for authorization-sensitive game rules.

Handler coverage

Use registration.diagnostics() after launch, or viewer.diagnostics() with createViewer. For a custom emitter, use inspectViewer(emitter, capabilities?).

Group Checked handlers
Core state, state:updated, player
Chat chat:messages, chat:appended, chat:updated, chat:deleted, chat:state, chat:disabled, chat:result
Replay replay:start, replay:to, replay:end
Recommended preferences, avatars

Theme handling appears separately under optional; a single-theme viewer need not implement it.

Each group has completed, total, percent, and missing fields. compatible means all checked required groups are complete. A connected chat controller enables the chat checks; any replay callback enables all three replay checks. Pass an explicit array, such as ["chat", "replay"], to choose the capabilities to check. inspectViewer checks only core unless capabilities are supplied.

Only installed handlers count, including those implemented by the library. An omitted callback does not install a placeholder listener. Coverage measures wiring, not UI behavior or rule correctness; optional features need no empty handlers.

This section describes the underlying BGS events for custom adapters. With registerViewer or createViewer, use the callbacks above; chat events are connected through ChatController. These events flow from BGS to the viewer:

emitter.on("state", (state) => {
	// Render the new state
});

state

emitter.on("state", (state: GameData) => {
	// ...
});

Receive game data filtered by stripSecret for this player or spectator.

Replace the previous viewer state with this snapshot.

state:updated

emitter.on("state:updated", () => {
	// ...
});

Notification that new state is available.

You can request the full state by emitting fetchState or request the new log elements by emitting fetchLog.

gamelog

emitter.on("gamelog", (logData: { start: number; end?: number; data: unknown }) => {
	//...
});

Receive log data.

data is the return value of the backend's logSlice.

preferences

emitter.on("preferences", (preferences: Record<string, unknown>) => {
	//...
});

Get the user's UI preferences for this game, including the shared sound and colorBlind booleans.

preferences.analysis === true identifies the all-seat manual sandbox. Keep legal move controls, explicit pass controls and the journal; hide live chat, planning / premove controls and account-level automation. Do not send auto-pass, premoves or bot choices on preference updates, seat changes, reads or navigation. Mandatory engine rule effects still apply. The host owns history navigation and seat selection. Clearly label simulated hidden information and deliberate sandbox overrides as hypothetical, never actual source values. In Power Grid, every seat starts with a hypothetical 999 budget, with normal costs and affordability checks—not unlimited money or a claim about real cash. Control-only cycles (including undo/redo and wait/resume) must not append unbounded logs or snapshot chains; real moves and explicit passes may extend normal history. See the analysis hooks.

preferences.chatNotifications tells the viewer whether to show floating unread-chat reminders. Hide those reminders when it is false: a BGS rail or floating shortcut already provides them. BGS sends true when neither shortcut is visible. Keep the embedded chat accessible either way. Treat a missing value as true; this is a live layout hint, not a saved user preference.

preferences.bgs (typed as PlayerAppearance in protocol 0.8.1) carries public appearance in seat order:

{
  players: [{ pro: true }, { pro: false }],
  supporterBadge: { url: "https://boardgamers.space/assets/supporter.svg", label: "Supporter" },
  playerColors: ["#4595d1", "#e68b32"]
}

For seats with pro: true, display the host's supporterBadge.url beside the player's avatar or name, with supporterBadge.label as its accessible label. Do not embed badge artwork in viewers; hide it when the seat flag or badge is absent. playerColors contains the final cosmetic colours resolved centrally by BGS for every seat; viewers must use this array without resolving conflicts again. An empty array restores the game's defaults. The host preserves unaffected seats and only replaces colours that are identical or almost identical; choosing a similar colour name alone does not cause reassignment. Apply updates without mutating engine state or move identities. Keep faction colours and accessibility palettes authoritative. The host derives this data from membership; ignore persisted game preferences under the reserved bgs key. Older hosts can omit it.

Games with player-chosen cosmetic colours can instead use preferences.preferredPlayerColors:

{
	preferredPlayerColors: ["#da73aa", null];
}

This separate, BGS-owned field contains only actual custom preferences, normalized to six-digit hex in seat order. null means keep that player's game colour. Unlike bgs.playerColors, it is not a complete, conflict-resolved palette. Apply custom preferences to the game's chosen palette, preserving unaffected seats. Resolve identical or almost identical colours with the viewing player's custom preference first, then seat order (spectators use seat order); use a distinct fallback for conflicts. BGS uses squared RGB distance below 24² as its collision threshold. Keep accessibility palettes authoritative and update displayed colours without changing game state. The host overwrites persisted values for this field. It can be absent on older hosts; do not assume that every entry in the legacy bgs.playerColors array is a custom preference.

For example, a game may expose a preference for flat building graphics.

devMode

On top of the game's own preferences, the platform injects a devMode: true key when the user has developer settings enabled on their device. When developer settings are off, the key is entirely absent — check preferences.devMode === true.

player

emitter.on("player", (playerInfo: { index?: number }) => {
	// ...
});

Receive the connected player's zero-based seat index. For spectators, index is undefined; start with no selected seat until this event arrives.

Sound (in-game audio)

If your game has a sound entry in its preferences, the site reserves that key: preferences.sound in the preferences message is the user's global, site-wide in-game sound setting, re-sent live whenever it changes. Your viewer must honor it: mute when it is false. Games without a sound preference get no sound control on the site.

A viewer-side sound toggle emits update:preference {name: "sound", value} as usual; the site routes it to the global setting (broadcast back to all the user's games). There is no per-game override.

Color-blind support

preferences.colorBlind is a reserved, site-wide boolean, false by default. Users can change it in Account → Game preferences or any supporting game's preferences. Logged-in users keep the setting across games and devices; anonymous visitors keep it in their browser. The global value overrides any old per-game value. Existing enabled settings from Gaia Project, Fuji and Primordial Soup are carried over to the account.

Declare support in your game info so BGS displays the shared control:

{ "name": "colorBlind", "label": "Color-blind mode", "type": "checkbox", "default": false }

Apply preferences.colorBlind === true whenever onPreferences runs, including updates while the viewer is open. Each game chooses appropriate visual aids: distinctive borders, symbols or color labels. It must not change game rules. Analysis viewers receive the same setting.

A viewer's own toggle calls ctx.updatePreference("colorBlind", enabled) (or emits update:preference with { name: "colorBlind", value: enabled }). BGS saves it globally and sends the new preferences back. Do not save a separate per-game override or emit an update while applying an incoming preference. Standalone previews may use their own local fallback.

Interface language

preferences.locale is the current BGS interface language (a BCP-47 tag such as nl, fr, pt-BR or zh-TW). BGS sends it to normal games, replays and analyses, and updates it when the player changes language. It is presentation context, not a saved per-game preference. Apply it to controls, tooltips and game explanations; keep player names, chat messages, move identifiers and game state unchanged. Fall back to English for an unsupported locale.

Tutorials receive the same locale in launchTutorial(selector, { chapter, locale, ... }).

avatars

emitter.on("avatars", (avatars: string[]) => {
	// ...
});

Receive the avatars of each player, in order.

replay:start

emitter.on("replay:start", () => {
	// ...
});

Start replay mode. Only for compatible viewers.

When entering replay mode, you should emit the replay:info event with the necessary info.

replay:to

emitter.on("replay:to", (logIndex: number) => {
	// ...
});

Replay up to that point in the log.

replay:end

emitter.on("replay:end", () => {
	//...
});

Leave replay mode

undo:available

emitter.on("undo:available", (available: boolean) => {
	//...
});

Sent for solo games, including single-seat games with built-in opponents: true while they can take back their last saved move. BGS replays the engine to the position before it, so the engine must implement replay(data, { to }). Show your undo control while it is true and emit undo from it. BGS then sends the earlier position through state. A platform sidebar control is also available. This rewinds the saved move and any automatic opponent responses. It permanently records platformRewoundAt outside engine data for future leaderboard eligibility. Ordinary engine-level corrections remain normal moves and do not set this marker; engines must prevent those corrections from revealing new information or rewinding opponents' responses.

theme

emitter.on("theme", ({ dark }: { dark: boolean }) => {
	// ...
});

Receive the site's current color theme. It is sent when the game is ready and every time the theme changes afterwards, including when the OS theme flips while the user's setting is "system".

The theme also arrives as a raw postMessage ({ type: "theme", dark: boolean }) before any viewer script runs — that's how the wrapper page toggles its own dark class without waiting for launch. The emitter event is the preferred API; only fall back to a window message listener if you must apply the theme before launch returns.

Theme support is optional. If your viewer switches themes, apply changes live without reloading the iframe.

See Dark mode.

chat:messages

emitter.on("chat:messages", (messages: ViewerChatMessage[]) => {
	// ...
});

Only sent to viewers that declare the chat capability (viewer.chat: true in the game metadata — see Chat). Hands the viewer the full recent chat history as a replace: render this list wholesale. It is sent on mount and re-sent on every iframe remount (e.g. when the user toggles the alternate UI), so always treat it as the complete current history, not an append.

ViewerChatMessage contains a plain-text fallback and structured rich segments:

type ViewerChatMessage = {
	_id?: string; // message id, for reconciling chat:updated / chat:deleted
	author?: string; // author display name; absent on system messages
	authorId?: string; // author's stable user id — match players/colors on THIS, never on the name
	playerIndex?: number; // author's seat index, set when the author is a player in this game
	createdAt?: string; // ISO date — when the message was posted
	text: string; // plain-text fallback
	segments: (
		| { kind: "text"; text: string }
		| { kind: "link"; text: string; url: string }
		| { kind: "mention"; name: string; id: string }
	)[];
	type: "text" | "system";
	editedAt?: string; // ISO date, set when the message was edited
	editText?: string; // original input, preserving quoted mentions
	editableUntil?: string; // ISO deadline; supplied only for your own eligible messages
};

Use playerIndex to apply board seat colors and authorId for stable identity. System messages may omit both. The library also accepts messages without segments; render text as the fallback.

chat:appended

emitter.on("chat:appended", (messages: ViewerChatMessage[]) => {
	// ...
});

New messages to append to the list. The sender's own message arrives back through this event too (the platform rebroadcasts every accepted post), so don't add an optimistic echo on send.

chat:updated

emitter.on("chat:updated", (messages: ViewerChatMessage[]) => {
	// ...
});

Edited messages. Replace each in place by _id (ignore updates for messages you don't have).

chat:deleted

emitter.on("chat:deleted", (ids: string[]) => {
	// ...
});

Moderation deletes. Drop these message ids from the list.

chat:disabled

emitter.on("chat:disabled", (disabled: boolean) => {
	// ...
});

The room-wide chat kill switch (moderation). When true, gate your chat input — the api rejects posts to a disabled room regardless, this is only so you can show the chat as read-only. Note it's only re-pushed when the flag changes (or on mount), not streamed continuously.

chat:state

emitter.on(
	"chat:state",
	(state: { canSend: boolean; reason?: string; mentions: { id: string; name: string; playerIndex?: number }[] }) => {
		// ...
	},
);

The viewer's write-permission state, pushed on mount and whenever it changes (login, kill switch). Use it to hide/disable your composer — the api stays the authority on writes (a refused chat:send still gets its chat:result either way), this only reflects what the api would accept. reason is a machine-stable code, present when canSend is false: "not-logged-in" | "not-confirmed" | "chat-disabled" | "not-a-player" | "no-game". Localize its display on your side.

canEdit?: boolean advertises editing support. Optional editLabels contains the localized edit, save and cancel strings. Edit controls also require the message's editableUntil to be in the future; BGS rechecks permissions on every save.

readState?: { userId: string; lastReadAt: number } | null supplies the signed-in reader's saved position as a Unix-millisecond timestamp. Protocol 0.6.1 uses it to restore unread badges after a reload. It can arrive before or after chat history. null clears account-specific tracking on logout; omitting it preserves the controller's current tracking.

chat:translation

The result of chat:translate: { messageId, requestId, target, ok, text?, segments?, language? }. language is the detected source language; und means uncertain and mul means mixed. Keep the original message unchanged. ChatController handles results, discards responses for edited/deleted messages or an old target language, and offers retry on failure.

BGS advertises availability via chat:state.translationTarget and sends translated UI labels in chat:state.translationLabels. Absence of a target means translation is unavailable. Detection is a hint: manual translation remains available regardless of the detected language.

chat:result

emitter.on("chat:result", (result: { requestId: string; ok: boolean; error?: string }) => {
	// ...
});

The acknowledgement for a chat:send or chat:edit carrying a requestId — one result per request, by requestId. ok: true: the message was accepted (it arrives via chat:appended like any other; edited messages arrive through chat:updated). ok: false: the post was refused (error is the api's message — not logged in, rate-limited, chat disabled, validation) — keep the draft and show what happened.

The commands above send these events for you. The raw examples below are for ViewerEmitter integrations. These events flow from the viewer to BGS:

emitter.emit("fetchState");

ready

emitter.emit("ready");

The game has rendered and can be shown to the player. The app keeps the iframe hidden (with a loading spinner) until it receives this, then reveals it.

Emit ready only after the first state has been received and rendered — not on mount. The app sends the initial state in response to the shim's gameReady, so by the time your viewer has state, the app's message listener is guaranteed to be attached; a ready fired on mount (before any state) can race ahead of that listener on a hard refresh and be dropped, leaving the spinner up forever.

Emit it on a macrotask (e.g. in a setTimeout(0) after applying the first state), not inside requestAnimationFrame: the app keeps the iframe hidden until ready, and in a hidden/backgrounded iframe requestAnimationFrame may never fire — so the game would never signal ready and stay hidden forever.

move

emitter.emit("move", { x: 1, y: 2 });

Send a move to the backend.

move is passed as is to the backend's move exported method: the emitted payload is relayed verbatim as the backend move's move field. Emit the raw move object:

// ✅ the engine receives move.action === "take"
emitter.emit("move", { action: "take", gems: ["ruby", "onyx"] });

// ❌ double-wrapped: the engine receives move.move.action
emitter.emit("move", { move: { action: "take", gems: ["ruby", "onyx"] } });

player:clicked

emitter.emit("player:clicked", { index: 0 });

Signals that a player's name was clicked, so that the application can go to the player's profile.

Optional: emit it when the player clicks a participant name or avatar.

fetchState

emitter.emit("fetchState");

Requests the current game state passed to us, in full.

The application will fetch the current game state, and pass it to the viewer with a state event.

fetchLog

emitter.emit("fetchLog", { start: 0, end: 9 });

Requests the log between start and end included.

The application will fetch the data and will pass it to the viewer with a gamelog event.

addLog

emitter.emit("addLog", ["Player 1 built a factory."]);

Transmits new log elements to the application, to be displayed in the sidebar.

replaceLog

emitter.emit("replaceLog", ["Game started."]);

Erases current log and transmits new log elements to the application, to be displayed in the sidebar.

replay:info

emitter.emit("replay:info", { start: 0, current: 3, end: 9 });

Emit it when replay starts and whenever the replay position changes.

Used for the replay controls in the sidebar.

undo

emitter.emit("undo");

Take back the player's last move, while undo:available is true.

update:preference

Update a preference from your viewer. Values can be strings, booleans, or null.

emitter.emit("update:preference", { name: "flatBuildings", value: true });

The preference is stored per game and re-sent in the preferences message. Two names are reserved: sound and colorBlind write the user's global settings instead — see Sound and Color-blind support. Both take boolean values.

chat:send

emitter.emit("chat:send", { text: "Hello @Alice", requestId: "message-1" });

Send plain text to the game's chat. Include a unique requestId to receive chat:result and show errors; ChatController does this automatically. After acceptance, the message arrives through chat:appended, including for the sender. Avoid adding a local echo. BGS enforces posting permissions, rate limits, and the room's disabled state.

chat:edit

emitter.emit("chat:edit", {
	messageId: "650000000000000000000001",
	text: 'Corrected message @"Full Name"',
	requestId: "edit-1",
});

Edit your own text message in this room within 15 minutes of posting. Start from message.editText (falling back to message.text), never from a displayed translation. BGS enforces ownership, the time window and room write permissions. Listen for chat:result; preserve the editor on failure. The accepted change arrives through chat:updated, which also invalidates cached translations. No local echo is needed. ChatController manages this flow for you.

chat:translate

emitter.emit("chat:translate", {
	messageId: "650000000000000000000001",
	requestId: "translation-1",
	target: "fr",
});

Use the target supplied by BGS in chat:state. The platform resolves the message from the current room, checks access and limits, then returns chat:translation. Viewers never receive model credentials and cannot submit arbitrary text for translation. mountChat includes these controls from protocol 0.4.0; custom UIs call chat.toggleTranslation(messageId) to translate or toggle the original.

chat:read

emitter.emit("chat:read", { messageId: "650000000000000000000001" });

Report the latest message the user actually saw, using its _id. BGS marks the room read through that message and clears corresponding mention notifications. Send only after checking chat visibility and browser-tab visibility. Invalid or unknown IDs are ignored.

Chat

Tick Chat in the admin options for each viewer that renders chat. BGS uses its own chat in the lobby; once the game starts, chat is also available in that viewer. The Chat button remains available in both the compact rail and expanded sidebar, including on mobile and for alternate viewers. It opens the same conversation, with shared unread state. Games cannot hide this button.

A custom integration handles chat:messages, chat:appended, chat:updated, chat:deleted, chat:state, chat:disabled, and chat:result. ChatController and registerViewer wire these handlers for you.

Render rich segments as text, links, and mentions. Never inject messages as HTML or re-linkify the plain fallback; BGS supplies links according to the author's permissions. Use the roster in chat:state for mention suggestions. Send mentions as @username or @"Full Name"; BGS resolves recipients and excludes self-notifications.

There are no viewer uplinks for editing messages or adding reactions. Viewers receive edit and deletion notifications so their displayed history stays current.

ChatController reference

ChatController from @boardgamers/protocol/chat manages the events above. Return it as chat from your registration callback, pass it to createViewer, or use attachChat(emitter, chat) with a custom emitter. See the panel and custom UI examples.

Method Purpose
subscribe(listener) Immediately supplies the current snapshot, then each update; returns an unsubscribe function.
setDraft(text) / submit() Update the draft / send it if permitted, nonempty, and no request is pending.
setOpen(open) Track panel visibility; does not mark messages read.
markRead(messageId) Clear local unread IDs through this message and report it to BGS. Call only after checking visibility.
suggestions(query) Filter the latest mention roster, excluding your seat.
destroy() Remove subscriptions and cancel timers. viewer.destroy() calls this for its attached controller.

Treat snapshot as read-only. Its fields are:

Fields Meaning
messages, unreadIds Current messages and IDs of locally unread messages. chat.unread returns the count.
enabled, open Chat has been supplied by BGS / the UI panel is open.
canSend, disabled, reason Write permission, room kill switch, and a permission code to localize.
draft, pending, error Composer text, pending request ID (empty when idle), and send error.
mentions, playerIndex Mention roster and the viewer's seat, if any.

Translation (0.4.0+): toggleTranslation(messageId) requests a translation or toggles back to the original. translationTarget and translationLabels describe availability and localized controls. translations[messageId] contains pending/error/shown state, translated text and segments. The original messages array is unchanged. Edits, deletions and target-language changes invalidate the relevant translations.

Editing (0.5.0+): canEdit(message) checks host permission and the edit deadline. startEditing(messageId) loads its original input; editLast() selects the latest eligible message. Both return whether editing started. snapshot.editingId identifies the active editor. cancelEditing() restores the previous draft, while submit() saves the edit. Pending edits lock the input and cancellation until an acknowledgement or timeout; failures preserve the draft. chat.editLabels returns host-localized labels or English defaults. The shared composer handles ↑ on an empty input and Escape.

History and unread: with a saved readState, initial and replacement history count messages newer than the saved position, excluding your own messages and system events. Without one, history starts as a read baseline and replacements retain known unread IDs still present. Duplicate IDs, edits and deletions are reconciled in place. Neither receiving history nor opening a hidden panel marks messages read; read reports require visibility.

Read reports: mountChat and bindChatViewport handle scrolling and visibility checks, including clipping by the embedding page; iframe focus is not required. With your own implementation, check visibility before calling markRead. markRead accepts an ID present in history, batches reports for 500 ms, and never moves the reported watermark backwards during the controller's lifetime.

Send results: submit() trims text and assigns a request ID. A matching chat:result settles the request; success clears the submitted draft only if it has not since changed. Refusals and timeouts preserve it. Stale acknowledgements cannot settle a newer send. Accepted messages arrive through chat:appended.

Override timing when constructing the controller, for example in tests:

import { ChatController } from "@boardgamers/protocol/chat";

const chat = new ChatController({
	readDelayMs: 500,
	sendTimeoutMs: 20_000,
});

Optional chat UI

Import these helpers from @boardgamers/protocol/chat/dom. All bindings expose destroy() for unmounting; the controller remains owned by the viewer.

Helper Purpose
mountChat(container, options) Mount a complete panel. Returns element, open(), refresh() and destroy().
bindChatComposer(input, options) Bind draft, permissions, keyboard and mention handling to a text input. Returns choose(index) and destroy().
bindChatViewport(list, options) Follow messages and report visible reads. Returns open(), refresh(), bounds() and destroy().

All require options.chat. Composer options require onSuggestions, receiving { candidates, selected }; maxSuggestions defaults to 6. Mark message rows with data-message-id and pass their wrapper as contents to the viewport binding.

Date dividers use local calendar days. Override labels.date(date) to change their text, or use chatDateSeparators(messages, locales?) from /chat in your own UI. It returns { dateTime, label } at the first dated message and each day change, and undefined elsewhere.

Panel options include openPlayer, renderAuthor, labels, styles, viewport and onVisibilityChange. Viewport bindings accept contents, isVisible, viewport and onVisibilityChange. viewport() returns any of top, right, bottom, left in CSS pixels within the game window; it can narrow the browser's visible area to exclude overlays. refresh() rechecks layout after external changes.

The panel's open() reveals chat and scrolls its document to it. The lower-level viewport's open() only positions its message list. Neither scrolls the parent BGS page. Your UI must select its chat tab before calling open().

See examples and styling.

Dark mode

Dark-mode support is entirely optional. A single, readable theme is fine; there is no general recommendation to maintain both light and dark versions.

The site supports a light/dark theme, switchable by the user or following the OS ("system"). The wrapper page does two things for dark mode:

If you choose to follow the site theme, read ?dark=1 (or the wrapper's <html class="dark">) for the first paint, then use onTheme for live changes. Style your components accordingly; a viewer with a single theme can ignore this.

settings / update:setting

The host sends settings with the current player's per-game engine settings, or null when unavailable. Use createViewer({ onSettings(settings) { … }, onState(state) { … } }) to receive updates and viewer.updateSetting("autoCharge", "3") to request a change. The host validates the declared setting, merges it with the player's other settings, saves through the gameplay settings API, and sends back the canonical settings. Sidebar changes use the same settings. These are game settings, separate from presentation preferences sent through update:preference. Only active-game players can edit them.

Player hover cards and boardgame navigation

player:hovered

emitter.emit("player:hovered", {
	index: 0,
	anchor: { x: 100, y: 40, width: 120, height: 24 },
});
emitter.emit("player:hovered", null); // pointer leave / focus loss

The anchor is the player-name element's bounding rectangle in iframe-viewport CSS pixels. Emit on hover or keyboard focus; send null when leaving. BGS resolves the seat to an account, delays opening briefly, and allows the pointer to move onto the card. Invalid coordinates, unknown seats and bots are ignored. The same protocol works in game and analysis viewers.

boardgame:clicked

emitter.emit("boardgame:clicked");

Navigates to the current game's boardgame page. No name, URL or game ID is accepted: the host supplies the destination. The SDK equivalents are hoverPlayer(index, anchor), leavePlayer(), and openBoardgame().

Board thumbnail capture

thumbnail:render (BGS → viewer)

{ width: 1200, height: 630 }

Asks an opted-in viewer to prepare a still image of its current public board. With createViewer or registerViewer, implement onThumbnail(size) and return the board element after layout and image loading finish. The SDK waits for pending state renders and sends the result automatically. Return null to decline.

thumbnail:ready (viewer → BGS)

emitter.emit("thumbnail:ready", {
	supported: true,
	bounds: { x: 20, y: 30, width: 900, height: 600 },
});
// Or:
emitter.emit("thumbnail:ready", { supported: false });

Bounds use iframe-viewport CSS pixels, have positive dimensions, and must fit inside the capture iframe (1200 × 900). This event does not upload an image or arbitrary URL. The platform crops and scales the rendered board into the game share image, using the normal background if capture fails. Enable it with viewer.thumbnail: true only after implementing the callback. See the thumbnail lifecycle and example.

Publishing a viewer with multiple files

Keep language files, code chunks, images, fonts and WASM next to the entry point instead of inlining them into one large JavaScript file. Use relative URLs so the whole build can live in its own immutable directory.

In the admin viewer editor, choose Upload folder, select the build directory and pick the entry point. Extra JavaScript files are hosted as chunks; they are not automatically executed as dependencies. Save after the upload completes.

For scripted releases, scripts/publish-viewer.mjs uploads a directory, verifies every public file and saves the previous viewer for rollback. It prints a dry run unless --apply is given; --activate switches the configured viewer only after all files pass verification.

node scripts/publish-viewer.mjs --game powergrid --version 13 \
  --dir ./release --entry powergrid-viewer.umd.min.js --style powergrid-viewer.css \
  --token /path/to/admin-token --record /tmp/powergrid-release.json --apply --activate

The upload API preserves relative paths with a shared bundle identifier. JavaScript, CSS, JSON, SVG, sourcemaps and WASM are gzip-compressed when smaller; browsers receive the original contents through Content-Encoding: gzip. Already-compressed media stay unchanged. Use a new bundle identifier when any file changes. The script skips sourcemaps by default; add --source-maps only if you want them publicly accessible.

Upload the complete viewer build, including any language JSON, JS chunks, images, fonts and WASM it references. Use a clean release folder: leave out engines, preview apps, test fixtures and private data. Replacing only the main JS file will break relative asset URLs. Each release needs its own bundle directory, and the viewer URL should change only after every file is uploaded.

Send ordinary file bytes to the upload API—do not gzip them yourself or upload .gz URLs. BGS chooses compression and sets the HTTP headers. The optional viewer.scriptBytes is the uncompressed entry size, used by the download progress bar; the admin uploader and release script set it for you. --alternate updates the alternate viewer while preserving the main one.

If a browser cannot reach our asset storage, BGS retries viewer scripts and stylesheets through its own server. Relative chunks keep working on that route; use relative URLs within your build, rather than hardcoding the storage host.

Cleaning up old uploads

Run apps/api/scripts/cleanup-viewer-assets.ts on the API host. It reads every game version, including private and archived versions, and the viewer snapshots saved with analyses. A reference to any file protects its whole bundle directory, including language chunks, images and WASM. Engines, avatars and boardgame artwork outside viewer bundles are excluded.

cd apps/api
export previewDbUrl=mongodb://10.90.0.3:27017/admin
NODE_ENV=production node scripts/cleanup-viewer-assets.ts \
  --extra-mongo-env previewDbUrl \
  --state /home/bgs/viewer-cleanup/state.json \
  --report /home/bgs/viewer-cleanup/report.json

This is a dry run: it writes a local report and retention state, but changes nothing in Mongo or S3. Include every Mongo server whose previews use this bucket; --extra-mongo-env can be repeated and scans all non-system databases, including preview templates. An unavailable reference source aborts the run. --keep-url can pin additional rollback builds; --public-base adds a custom public URL alias for the same bucket.

A bundle becomes eligible only when its newest file is at least seven days old and it has been observed unused for seven days. Reuse, changed files or changed reference-source settings restart the grace period. Keep the same state file between runs; losing it delays cleanup rather than making files eligible immediately.

Analyses already store their viewer and game version. New analyses also record viewerPinnedAt, and authorized reads record lastViewedAt without changing the list's edit-activity order. During cleanup, analyses with no creation, edit, view or viewer change in 30 days can switch to the viewer configured for their exact same game version. The engine, positions and other analysis data stay unchanged. The report saves the previous viewer for rollback. Recent activity cancels the update. Extra preview databases are read-only reference sources.

Review the report, then repeat the command with --apply to refresh eligible analyses and delete eligible bundles. Old analysis viewers stay protected for that run; their seven-day unused grace period starts on a later scan. --min-age-days and --analysis-idle-days can lengthen the retention periods. Reference checks and object fingerprints are repeated before deletion, and each object deletion uses its ETag as a condition.

Pause publishing, rollbacks and preview restores while applying cleanup: the scans are not a transaction across Mongo and S3. The script installs no schedule. Keep reports outside /tmp if you want a durable deletion log and viewer rollback history.

Move acknowledgements

With protocol 0.7, onMoveResult receives { move, ok, error? } after the host submits a move. move is the original payload, so a viewer can match its sequence number. A rejection clears a pending action immediately; request a fresh state before retrying. A successful acknowledgement is not a state snapshot: continue rendering the normal state/log updates.

Open the platform chat

Emit chat:open with no payload to open the platform's standard game chat. The SDK command is ctx.openChat(). Check preferences.platformChat === true before using it; hosts without this capability need the viewer’s existing chat UI. This works on desktop and mobile, including when the viewer declares its own chat control. It does not send a message or mark unseen messages read; the platform chat retains its normal read and permission handling. A viewer using only this shortcut does not need to render a chat panel or attach a ChatController.