@unboxy/phaser-sdk 0.2.11 → 0.2.13

package/SDK-GUIDE.md

@@ -283,6 +283,61 @@ const room = await unboxy.rooms.joinOrCreate('lobby', {
 });
 ```
 
+#### Browsing open rooms — `unboxy.rooms.list()`
+
+A room code is enough for "my friend and I agreed on code ABC123 out of band", but not for "show me a list of open games and let me click one to join." For that, ask the server what rooms are currently open for your game:
+
+```ts
+interface RoomListEntry {
+  roomId: string;          // opaque — pass to joinById
+  roomCode: string;        // the code the host passed (empty for default rooms)
+  clients: number;         // current occupants
+  maxClients: number;      // cap the host set (server-clamped to [1, 16])
+  metadata?: unknown;      // whatever the host set via room.setMetadata (optional)
+  createdAt?: number;      // ms since epoch
+}
+
+const rooms = await unboxy.rooms.list();
+rooms
+  .filter(r => r.clients < r.maxClients)  // hide full rooms
+  .forEach(renderLobbyCard);
+
+// On click:
+async function joinRoom(entry: RoomListEntry) {
+  const room = await unboxy.rooms.joinById(entry.roomId, {
+    displayName: unboxy.user?.name ?? 'guest',
+  });
+  // room state is populated after the first onStateChange — see
+  // "Connection lifecycle" below for the state-timing rule.
+}
+```
+
+**Scope.** `list()` only returns rooms for the caller's game. A player can't see rooms from other games (the server cross-checks the gameId claim on the token).
+
+**Filter.** Pass `{ roomCode: 'ABC' }` to narrow to one code without paging through the whole list — useful for "is the room with code ABC up yet?" polling.
+
+**Polling, not subscription.** There is no push-on-change API today. Poll on a timer (e.g. every 3-5 s) while the lobby is open, and refresh on the user's explicit click. Cancel the timer when the player leaves the lobby.
+
+```ts
+// Simple lobby browser refresh loop
+let stop = false;
+async function refreshLoop() {
+  while (!stop) {
+    try {
+      const rooms = await unboxy.rooms.list();
+      renderLobby(rooms);
+    } catch (e) {
+      // Network hiccup or REALTIME_UNAVAILABLE — surface in UI, keep looping.
+    }
+    await new Promise(r => setTimeout(r, 3000));
+  }
+}
+refreshLoop();
+scene.events.once('shutdown', () => { stop = true; });
+```
+
+**Unlisted rooms.** Every room created via `joinOrCreate` / `create` is currently listable by players of the same game. There is no "private room" flag yet — if you need that, tell your users to share the code out of band and don't render a lobby browser.
+
 #### Delta-synced state — `room.player` and `room.data`
 
 Use this for anything that represents the *current world*: positions, hp, score, turn state, scoreboard, etc. The server delta-syncs diffs to every client.
@@ -314,7 +369,7 @@ Values are JSON-stringified under the hood. Use for anything JSON-serializable.
 
 #### Transient events — `room.send` and `room.on`
 
-Use this for ephemeral actions: fires, hits, emotes, explosions, chat. Not persisted.
+Use this for ephemeral actions: fires, hits, emotes, explosions. Not persisted. (For **chat**, prefer the dedicated `room.chat` helper below — it adds local echo, length capping, and a stamped sender name on top of this same primitive.)
 
 ```ts
 // Sender
@@ -326,6 +381,68 @@ const offFire = room.on('fire', (msg: { from: string; x: number; y: number; angl
 });
 ```
 
+#### Chat — `room.chat.send` and `room.chat.onMessage`
+
+A thin wrapper over the transient relay tuned for in-game chat. Use this instead of raw `room.send('chat', text)` — you get four things you'd otherwise re-implement in every game:
+
+1. **Local echo** — the sender's own message hits the same `onMessage` handler stream the moment it's sent, so your UI has one render path for both your messages and remote ones.
+2. **Stamped sender info** — every `ChatMessage` carries `kind`, `from` (sessionId), `displayName` (sender's human-readable name at send time), `text`, and `ts`. No need to look up the sender in `room.state.players`.
+3. **Trim + length cap** — text is `.trim()`ed, dropped if empty, and silently truncated to `MAX_CHAT_TEXT_LEN` (500) so a stray paste can't flood the relay.
+4. **Auto-emitted system messages** — when a remote player joins or leaves, the SDK dispatches a `kind: 'system.joined'` / `'system.left'` message into the same stream. No wire traffic; computed locally on each client from `room.state.players`. Skipped for the local player's own join.
+
+```ts
+import { MAX_CHAT_TEXT_LEN } from '@unboxy/phaser-sdk';
+import type { ChatMessage } from '@unboxy/phaser-sdk';
+
+const log: ChatMessage[] = [];
+
+const offChat = room.chat.onMessage((msg) => {
+  log.push(msg);
+  if (msg.kind === 'user') {
+    const who = msg.from === room.sessionId ? 'You' : (msg.displayName || 'Player');
+    appendChatLine(`${formatTime(msg.ts)} ${who}: ${msg.text}`);
+  } else {
+    // 'system.joined' or 'system.left' — render however you like.
+    // msg.text is already a sensible English fallback ("Alice joined").
+    appendSystemLine(`${formatTime(msg.ts)} — ${msg.text}`);
+  }
+});
+
+inputEl.maxLength = MAX_CHAT_TEXT_LEN;       // mirror the cap on the input box
+inputEl.addEventListener('keydown', async (e) => {
+  if (e.key !== 'Enter') return;
+  try {
+    await room.chat.send(inputEl.value);     // trim + cap + local echo + wire send
+    inputEl.value = '';                      // safe: echo already dispatched synchronously
+  } catch (err) {
+    // Local-side dispatch failed (e.g. connection dropped). Show a UI hint.
+    showChatError(err);
+  }
+});
+
+scene.events.once('shutdown', offChat);
+```
+
+`ChatMessage` discriminates by `kind`:
+
+```ts
+type ChatMessageKind = 'user' | 'system.joined' | 'system.left';
+interface ChatMessage {
+  kind: ChatMessageKind;
+  from: string;          // sessionId of the sender (or join/leave subject)
+  displayName: string;   // their displayName at the time
+  text: string;          // user-typed text, or English system fallback
+  ts: number;            // Date.now() when emitted
+}
+```
+
+Notes:
+- **No history.** A player who joins mid-room sees no prior `'user'` messages. If you need scrollback, write to `room.data.set('chatLog', [...])` yourself — the relay is fire-and-forget.
+- **System messages are local-only.** Each client computes them from `room.state.players` add/remove events. They are NOT broadcast over the wire, and never echo from the wire even if a different client tries to send one.
+- **`send` returns `Promise<void>`.** Resolves once dispatch is complete (echo + wire queued); rejects if the underlying connection blew up. It is **not** an ack — the relay itself is fire-and-forget; the Promise only catches local-side errors.
+- **Order by arrival.** `ts` is `Date.now()`, advisory only. Skew between clients is small in practice but don't sort by `ts` across senders.
+- **Trust model.** `text` and `displayName` come from the sender — no server-side validation. Same as every other transient relay payload.
+
 #### Server-tracked membership
 
 `room.state.players` is server-owned. Each entry exposes:
@@ -356,7 +473,7 @@ await room.leave();
 | Per-frame local movement feel | client-side prediction + interpolate remotes from state | State arrives at ~20 Hz; lerp toward it. |
 | Scoreboard shared by all | `room.data.set('scoreboard', [...])` | One writer wins on conflict; use optimistic patterns or turn-based writes. |
 | Projectile spawn / hit effect | `room.send('fire', {...})` + `room.on('fire', ...)` | Ephemeral, not needed on reconnect. |
-| Chat message | `room.send('chat', text)` + `room.on('chat', ...)` | Same — ephemeral relay. |
+| Chat message | `room.chat.send(text)` + `room.chat.onMessage(...)` | Helper over the relay: local echo, stamped sender, length cap. |
 | Current turn in a turn-based game | `room.data.set('turn', sid)` | Authoritative shared state. |
 
 Rules of thumb:
@@ -427,6 +544,9 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **0.2.13** — added `room.chat` helper for in-game chat. New API: `room.chat.send(text)` (returns `Promise<void>`) + `room.chat.onMessage(handler)`, plus exports `ChatMessage`, `ChatMessageKind`, and `MAX_CHAT_TEXT_LEN`. Wraps the existing `'chat'` wildcard relay with local echo (sender sees own message synchronously), stamped `displayName` on every payload, trim + 500-char silent truncate, and auto-emitted `kind: 'system.joined'` / `'system.left'` messages computed locally from `room.state.players` add/remove events (no wire traffic). Replaces the raw `room.send('chat', text)` pattern in the Multiplayer chapter — raw still works but loses local echo, length cap, and join/leave events.
+- **0.2.12** — added `unboxy.rooms.list(options?)` — returns the open rooms for the caller's game right now, scoped server-side to the caller's gameId. Use this to build a lobby browser ("show me open rooms, click to join") without needing an out-of-band room code. SDK-GUIDE adds a "Browsing open rooms" section under Multiplayer covering the `RoomListEntry` shape, the poll-on-timer pattern, and the `{ roomCode }` filter for "is room X up yet?" probes.
+- **0.2.11** — added `roomCode` + `maxClients` to `JoinOptions`. SDK-GUIDE's Multiplayer chapter now documents matchmaking: room type is always `'lobby'`; use `roomCode` to bucket independent rooms per gameId (create-with-fresh-code, join-with-shared-code, quick-match with empty code). Fixes a real bug where agents were passing a gameId-derived string as the room type (e.g. `joinOrCreate('blokus-<code>', ...)`) and failing with "no handler" server-side.
 - **0.2.10** — docs: added a `createUnboxyGame` options table (including the new `plugins` field) and a third-party Phaser plugin registration example. No code changes; version bumped so existing workspaces pick up the new guidance via `npm update @unboxy/phaser-sdk`.
 - **0.2.9** — `createUnboxyGame` now forwards the optional `plugins` field to Phaser's `GameConfig`. Previously the option was accepted at the call site but silently dropped — any `phaser3-rex-plugins` (or similar) registration never took effect, and `this.plugins.get(key)` returned undefined at runtime. Purely additive; no effect on games that don't pass `plugins`. Lets the `phaser-rex-touch` agent skill work end-to-end.
 - **0.2.8** — docs: added "Making remote motion feel smooth" section to the multiplayer chapter with concrete examples for interpolation (continuous motion), extrapolation (projectiles), and snap (discrete/turn-based/infrequent). No code changes — version bumped so existing workspaces pick up the new guidance via `npm update @unboxy/phaser-sdk`.

package/dist/index.d.ts

@@ -8,8 +8,9 @@ export type { UnboxyInitOptions } from './core/Unboxy.js';
 export { SavesModule } from './saves/SavesModule.js';
 export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RealtimeModule } from './realtime/RealtimeModule.js';
-export type { JoinOptions } from './realtime/RealtimeModule.js';
-export { UnboxyRoom, PlayerDataFacade, RoomDataFacade } from './realtime/UnboxyRoom.js';
+export type { JoinOptions, RoomListEntry, RoomListOptions } from './realtime/RealtimeModule.js';
+export { UnboxyRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UnboxyRoom.js';
+export type { ChatMessage, ChatMessageKind } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';
 export type { UnboxyUser } from './protocol.js';

package/dist/index.js

@@ -10,6 +10,6 @@ export { Unboxy } from './core/Unboxy.js';
 export { SavesModule } from './saves/SavesModule.js';
 export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RealtimeModule } from './realtime/RealtimeModule.js';
-export { UnboxyRoom, PlayerDataFacade, RoomDataFacade } from './realtime/UnboxyRoom.js';
+export { UnboxyRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/realtime/RealtimeModule.d.ts

@@ -1,5 +1,28 @@
 import type { Transport } from '../core/Transport.js';
 import { UnboxyRoom } from './UnboxyRoom.js';
+export interface RoomListEntry {
+    /** Opaque Colyseus room id — pass to `joinById` to connect. */
+    roomId: string;
+    /** Short code the host passed on create (empty string for default rooms). */
+    roomCode: string;
+    /** Current number of connected clients. */
+    clients: number;
+    /** Max clients the host set (server-clamped to [1, 16]). */
+    maxClients: number;
+    /** Whatever the host attached via `room.setMetadata(...)`. Unvalidated. */
+    metadata?: unknown;
+    /** Server-side creation time (ms since epoch). */
+    createdAt?: number;
+}
+export interface RoomListOptions {
+    /**
+     * Filter to rooms with this exact roomCode. Useful for "is a room with code
+     * X up yet?" polling without enumerating the whole list.
+     */
+    roomCode?: string;
+    /** Max entries to return. Server caps to 100 regardless. */
+    limit?: number;
+}
 export interface JoinOptions extends Record<string, unknown> {
     /** Optional display name passed to the server-side room on join. */
     displayName?: string;
@@ -46,5 +69,25 @@ export declare class RealtimeModule {
     create<State = unknown>(roomType: string, options?: JoinOptions): Promise<UnboxyRoom<State>>;
     join<State = unknown>(roomType: string, options?: JoinOptions): Promise<UnboxyRoom<State>>;
     joinById<State = unknown>(roomId: string, options?: JoinOptions): Promise<UnboxyRoom<State>>;
+    /**
+     * List the open rooms for the caller's game, as seen by the realtime
+     * service right now. Results are scoped server-side to the caller's
+     * gameId — you can't enumerate rooms from a different game.
+     *
+     * Use this to build a lobby browser ("show me open rooms, click to join").
+     * Poll on a timer or on a user's "Refresh" click; the API is request/
+     * response, not a live subscription.
+     *
+     * Example:
+     * ```ts
+     * const rooms = await unboxy.rooms.list();
+     * rooms
+     *   .filter(r => r.clients < r.maxClients)
+     *   .forEach(r => {
+     *     // render a button; on click: unboxy.rooms.joinById(r.roomId)
+     *   });
+     * ```
+     */
+    list(options?: RoomListOptions): Promise<RoomListEntry[]>;
     private connect;
 }

package/dist/realtime/RealtimeModule.js

@@ -33,6 +33,56 @@ export class RealtimeModule {
     async joinById(roomId, options = {}) {
         return this.connect(roomId, options, 'joinById');
     }
+    /**
+     * List the open rooms for the caller's game, as seen by the realtime
+     * service right now. Results are scoped server-side to the caller's
+     * gameId — you can't enumerate rooms from a different game.
+     *
+     * Use this to build a lobby browser ("show me open rooms, click to join").
+     * Poll on a timer or on a user's "Refresh" click; the API is request/
+     * response, not a live subscription.
+     *
+     * Example:
+     * ```ts
+     * const rooms = await unboxy.rooms.list();
+     * rooms
+     *   .filter(r => r.clients < r.maxClients)
+     *   .forEach(r => {
+     *     // render a button; on click: unboxy.rooms.joinById(r.roomId)
+     *   });
+     * ```
+     */
+    async list(options = {}) {
+        if (!this.available) {
+            throw new RpcError('REALTIME_UNAVAILABLE', 'Multiplayer is not available for this host. Unboxy.rooms.list requires running inside unboxy-home-ui with realtime enabled.');
+        }
+        const { token } = await this.transport.call('realtime.getToken', {});
+        const url = new URL(toHttpBase(this.realtimeUrl) + '/rooms');
+        url.searchParams.set('gameId', this.transport.gameId);
+        if (typeof options.roomCode === 'string')
+            url.searchParams.set('roomCode', options.roomCode);
+        if (typeof options.limit === 'number' && Number.isFinite(options.limit)) {
+            url.searchParams.set('limit', String(Math.floor(options.limit)));
+        }
+        const res = await fetch(url.toString(), {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            let detail = '';
+            try {
+                const body = await res.json();
+                if (body && typeof body.error === 'string')
+                    detail = `: ${body.error}`;
+            }
+            catch { }
+            throw new RpcError('ROOMS_LIST_FAILED', `/rooms returned ${res.status}${detail}`);
+        }
+        const body = await res.json();
+        if (!body || !Array.isArray(body.rooms)) {
+            throw new RpcError('ROOMS_LIST_FAILED', '/rooms response missing rooms[]');
+        }
+        return body.rooms;
+    }
     async connect(nameOrId, options, method) {
         if (!this.available) {
             throw new RpcError('REALTIME_UNAVAILABLE', 'Multiplayer is not available for this host. Unboxy.rooms requires running inside unboxy-home-ui with realtime enabled.');
@@ -52,3 +102,14 @@ export class RealtimeModule {
         return new UnboxyRoom(room);
     }
 }
+// Convert the realtime WebSocket base (wss://ws.unboxy.com/rt or ws://…) to
+// the matching HTTP base used for the /rooms REST endpoint. Colyseus's HTTP
+// routes (/matchmake, /rooms, /health) ride the same nginx vhost + path
+// prefix as the WebSocket, so this is just a scheme swap.
+function toHttpBase(wsUrl) {
+    if (wsUrl.startsWith('wss://'))
+        return 'https://' + wsUrl.slice('wss://'.length);
+    if (wsUrl.startsWith('ws://'))
+        return 'http://' + wsUrl.slice('ws://'.length);
+    return wsUrl;
+}

package/dist/realtime/UnboxyRoom.d.ts

@@ -29,6 +29,94 @@ export declare class RoomDataFacade {
     /** Read a shared room value. Returns null if the key is absent. */
     get<T = unknown>(key: string): T | null;
 }
+/** Maximum text length accepted by `ChatFacade.send`. Longer input is silently
+ *  truncated. Games should mirror this on their input box's `maxLength`. */
+export declare const MAX_CHAT_TEXT_LEN = 500;
+/**
+ * Discriminator for `ChatMessage`:
+ *  - `'user'` — a real player message sent via `ChatFacade.send`.
+ *  - `'system.joined'` — auto-emitted locally when a remote player enters the room.
+ *  - `'system.left'` — auto-emitted locally when a player leaves the room.
+ *
+ * System messages are computed locally on each client from `room.state.players`
+ * add/remove events; they never go over the wire. The first joiner does not
+ * see "X joined" for players already in the room when they themselves arrived
+ * (initial hydration is suppressed).
+ */
+export type ChatMessageKind = 'user' | 'system.joined' | 'system.left';
+/** Canonical chat-message shape delivered to `ChatFacade.onMessage` handlers.
+ *  See unboxy-design/features/multiplayer-chat.md §3 for the rationale on
+ *  each field. */
+export interface ChatMessage {
+    /** What kind of message this is — see `ChatMessageKind`. Default `'user'`. */
+    kind: ChatMessageKind;
+    /** For user messages: sender's session id (equals `room.sessionId` on the
+     *  sender's local-echoed copy). For system messages: the joined/left player's
+     *  session id. */
+    from: string;
+    /** Sender's (or subject's) display name at the time of the message. Empty if
+     *  the Player entry carried no displayName. */
+    displayName: string;
+    /** For user messages: the trimmed, length-capped text. For system messages:
+     *  a sensible English fallback (e.g. `"Alice joined"`). Games doing their own
+     *  i18n should switch on `kind` and ignore this. */
+    text: string;
+    /** Sender-side `Date.now()` for user messages, local `Date.now()` for system
+     *  messages. Advisory: order chat by arrival, not by ts. */
+    ts: number;
+}
+/**
+ * Convenience layer over the transient relay for in-game chat. Wraps
+ * `room.send('chat', ...)` / `room.on('chat', ...)` with three things every
+ * game would otherwise re-implement inconsistently:
+ *  - Local echo so the sender's own message hits the same handler stream
+ *    immediately (synchronous, before the network call).
+ *  - A canonical `ChatMessage` payload shape every chat in every game shares.
+ *  - Outbound `text.trim()` + length-cap to MAX_CHAT_TEXT_LEN, so a stray
+ *    paste cannot flood the relay.
+ *
+ * `displayName` is read from the sender's Player entry at send time and
+ * stamped onto the payload so receivers don't have to chase room.state to
+ * resolve a sessionId. See unboxy-design/features/multiplayer-chat.md §3.4.
+ */
+export declare class ChatFacade {
+    private readonly room;
+    private readonly handlers;
+    private remoteOff;
+    /** Sids that were already in `state.players` when this facade was constructed
+     *  — we suppress "joined" system messages for them so the joiner doesn't see
+     *  a flood of "X joined" for everyone already in the room. */
+    private readonly seen;
+    constructor(room: Room<unknown>);
+    /**
+     * Send a chat line. Empty-after-trim input is dropped silently. Text longer
+     * than MAX_CHAT_TEXT_LEN is silently truncated. Local echo fires
+     * synchronously before the wire send, so the input box can be cleared on
+     * the same tick.
+     *
+     * Returns a Promise that resolves once dispatch is complete (local echo +
+     * wire send queued). Rejects if the underlying `room.send` throws (e.g.
+     * the connection has dropped). Note: resolution does NOT confirm remote
+     * delivery — the underlying transient relay is fire-and-forget. Use this
+     * for catching local-side errors; do not treat it as an ack.
+     */
+    send(text: string): Promise<void>;
+    /**
+     * Subscribe to chat messages — both remote and local-echoed (your own), plus
+     * auto-emitted `'system.joined'` / `'system.left'` events. Returns an
+     * unsubscribe function. Call it on scene shutdown.
+     */
+    onMessage(handler: (msg: ChatMessage) => void): Unsubscribe;
+    /**
+     * Snapshot the current player list and subscribe to add/remove for system
+     * messages. By the time `client.joinOrCreate` resolves (and UnboxyRoom is
+     * constructed), Colyseus has delivered the initial state — so the snapshot
+     * here covers everyone already in the room, and we skip emission for them.
+     * Adds and removes after this point are real events.
+     */
+    private subscribeToPlayers;
+    private dispatch;
+}
 /**
  * Unboxy-flavored wrapper around a Colyseus Room. Exposes only the surface
  * documented in SDK-GUIDE.md so games are portable to a different realtime
@@ -38,6 +126,7 @@ export declare class UnboxyRoom<State = unknown> {
     private readonly room;
     readonly player: PlayerDataFacade;
     readonly data: RoomDataFacade;
+    readonly chat: ChatFacade;
     constructor(room: Room<State>);
     get id(): string;
     get name(): string;

package/dist/realtime/UnboxyRoom.js

@@ -54,6 +54,176 @@ export class RoomDataFacade {
         return parseOrNull(state?.data?.get?.(key));
     }
 }
+/** Maximum text length accepted by `ChatFacade.send`. Longer input is silently
+ *  truncated. Games should mirror this on their input box's `maxLength`. */
+export const MAX_CHAT_TEXT_LEN = 500;
+/**
+ * Convenience layer over the transient relay for in-game chat. Wraps
+ * `room.send('chat', ...)` / `room.on('chat', ...)` with three things every
+ * game would otherwise re-implement inconsistently:
+ *  - Local echo so the sender's own message hits the same handler stream
+ *    immediately (synchronous, before the network call).
+ *  - A canonical `ChatMessage` payload shape every chat in every game shares.
+ *  - Outbound `text.trim()` + length-cap to MAX_CHAT_TEXT_LEN, so a stray
+ *    paste cannot flood the relay.
+ *
+ * `displayName` is read from the sender's Player entry at send time and
+ * stamped onto the payload so receivers don't have to chase room.state to
+ * resolve a sessionId. See unboxy-design/features/multiplayer-chat.md §3.4.
+ */
+export class ChatFacade {
+    constructor(room) {
+        this.room = room;
+        this.handlers = new Set();
+        this.remoteOff = null;
+        /** Sids that were already in `state.players` when this facade was constructed
+         *  — we suppress "joined" system messages for them so the joiner doesn't see
+         *  a flood of "X joined" for everyone already in the room. */
+        this.seen = new Set();
+        this.subscribeToPlayers();
+    }
+    /**
+     * Send a chat line. Empty-after-trim input is dropped silently. Text longer
+     * than MAX_CHAT_TEXT_LEN is silently truncated. Local echo fires
+     * synchronously before the wire send, so the input box can be cleared on
+     * the same tick.
+     *
+     * Returns a Promise that resolves once dispatch is complete (local echo +
+     * wire send queued). Rejects if the underlying `room.send` throws (e.g.
+     * the connection has dropped). Note: resolution does NOT confirm remote
+     * delivery — the underlying transient relay is fire-and-forget. Use this
+     * for catching local-side errors; do not treat it as an ack.
+     */
+    send(text) {
+        if (typeof text !== 'string')
+            return Promise.resolve();
+        const trimmed = text.trim();
+        if (trimmed.length === 0)
+            return Promise.resolve();
+        const capped = trimmed.length > MAX_CHAT_TEXT_LEN ? trimmed.slice(0, MAX_CHAT_TEXT_LEN) : trimmed;
+        const state = this.room.state;
+        const me = state?.players?.get?.(this.room.sessionId);
+        const displayName = typeof me?.displayName === 'string' ? me.displayName : '';
+        const msg = {
+            kind: 'user',
+            from: this.room.sessionId,
+            displayName,
+            text: capped,
+            ts: Date.now(),
+        };
+        // Local echo first, synchronously, so callers can clear input on the same
+        // tick the message lands in their chat log.
+        this.dispatch(msg);
+        // Wire send. The server's wildcard relay rebroadcasts to every other
+        // client (`except: senderClient`) with `from: client.sessionId` stamped.
+        try {
+            this.room.send('chat', { kind: 'user', text: capped, ts: msg.ts, displayName });
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        return Promise.resolve();
+    }
+    /**
+     * Subscribe to chat messages — both remote and local-echoed (your own), plus
+     * auto-emitted `'system.joined'` / `'system.left'` events. Returns an
+     * unsubscribe function. Call it on scene shutdown.
+     */
+    onMessage(handler) {
+        this.handlers.add(handler);
+        if (!this.remoteOff) {
+            const cb = (raw) => {
+                const p = (raw && typeof raw === 'object' ? raw : {});
+                if (typeof p.text !== 'string')
+                    return; // defensive: drop legacy raw-string sends
+                // System messages are always computed locally — clamp wire kind to 'user'.
+                const msg = {
+                    kind: 'user',
+                    from: typeof p.from === 'string' ? p.from : '',
+                    displayName: typeof p.displayName === 'string' ? p.displayName : '',
+                    text: p.text,
+                    ts: typeof p.ts === 'number' ? p.ts : Date.now(),
+                };
+                // Server uses `except: senderClient`, so a remote 'chat' is never the
+                // sender's own — no de-dupe with local echo needed.
+                this.dispatch(msg);
+            };
+            this.remoteOff = this.room.onMessage('chat', cb);
+        }
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    /**
+     * Snapshot the current player list and subscribe to add/remove for system
+     * messages. By the time `client.joinOrCreate` resolves (and UnboxyRoom is
+     * constructed), Colyseus has delivered the initial state — so the snapshot
+     * here covers everyone already in the room, and we skip emission for them.
+     * Adds and removes after this point are real events.
+     */
+    subscribeToPlayers() {
+        const players = this.room.state?.players;
+        if (!players)
+            return;
+        if (typeof players.forEach === 'function') {
+            try {
+                players.forEach((_p, sid) => { this.seen.add(sid); });
+            }
+            catch {
+                // forEach can throw on an unsynced state; the seen set stays empty,
+                // which means we'll emit "joined" for the initial hydration. That's
+                // a degraded but non-broken behavior — the chat log gets an extra
+                // line per existing player. Log once for visibility.
+                console.warn('[unboxy.chat] could not snapshot players on subscribe');
+            }
+        }
+        if (typeof players.onAdd === 'function') {
+            players.onAdd((player, sid) => {
+                if (this.seen.has(sid))
+                    return;
+                this.seen.add(sid);
+                // Don't announce yourself joining your own room.
+                if (sid === this.room.sessionId)
+                    return;
+                const name = typeof player?.displayName === 'string' ? player.displayName : '';
+                const who = name || 'A player';
+                this.dispatch({
+                    kind: 'system.joined',
+                    from: sid,
+                    displayName: name,
+                    text: `${who} joined`,
+                    ts: Date.now(),
+                });
+            });
+        }
+        if (typeof players.onRemove === 'function') {
+            players.onRemove((player, sid) => {
+                if (!this.seen.has(sid))
+                    return;
+                this.seen.delete(sid);
+                const name = typeof player?.displayName === 'string' ? player.displayName : '';
+                const who = name || 'A player';
+                this.dispatch({
+                    kind: 'system.left',
+                    from: sid,
+                    displayName: name,
+                    text: `${who} left`,
+                    ts: Date.now(),
+                });
+            });
+        }
+    }
+    dispatch(msg) {
+        for (const h of this.handlers) {
+            try {
+                h(msg);
+            }
+            catch (err) {
+                console.error('[unboxy.chat] handler threw', err);
+            }
+        }
+    }
+}
 /**
  * Unboxy-flavored wrapper around a Colyseus Room. Exposes only the surface
  * documented in SDK-GUIDE.md so games are portable to a different realtime
@@ -64,6 +234,7 @@ export class UnboxyRoom {
         this.room = room;
         this.player = new PlayerDataFacade(room);
         this.data = new RoomDataFacade(room);
+        this.chat = new ChatFacade(room);
     }
     get id() { return this.room.roomId; }
     get name() { return this.room.name; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test scripts/test-chat-facade.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {