@umicat/phaser-sdk 1.0.0

package/dist/protocol.js

@@ -0,0 +1,3 @@
+// Shared postMessage protocol between the game SDK (iframe) and its host (umicat-home-ui).
+// Kept as a single file so host and SDK can be type-checked against the same contract.
+export const PROTOCOL_VERSION = 1;

package/dist/realtime/RealtimeModule.d.ts

@@ -0,0 +1,93 @@
+import type { Transport } from '../core/Transport.js';
+import { UmicatRoom } from './UmicatRoom.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;
+    /**
+     * Short code that distinguishes independent rooms for the same game.
+     * Empty / omitted means "the one shared room per game."
+     *
+     * Pass a non-empty value on `joinOrCreate` / `create` / `join` to bucket
+     * players into a private room. Two clients with the same `(gameId, roomCode)`
+     * land in the same room; different `roomCode` values create separate rooms.
+     * This is how you implement "Create Room" / "Join with code" UX — the
+     * server's `filterBy(["gameId", "roomCode"])` enforces the separation.
+     *
+     * Not a password: anyone who knows the code can join. Treat as an
+     * unguessability measure, not an access control.
+     */
+    roomCode?: string;
+    /**
+     * Cap on concurrent clients in the room the creator makes. Server clamps
+     * to [1, 16]. Defaults to 8 server-side. Only honored by the FIRST client
+     * (the creator) — later joiners see whatever the creator set.
+     */
+    maxClients?: number;
+}
+/**
+ * Multiplayer rooms backed by umicat-realtime-service (Colyseus under the hood).
+ *
+ * Availability: only when the host provided a `realtimeUrl` during the
+ * handshake (i.e. connected to umicat-home-ui with multiplayer enabled).
+ * Unavailable in standalone/anonymous mode — methods throw RpcError
+ * 'REALTIME_UNAVAILABLE'.
+ *
+ * Tokens are fetched per connection attempt via the `realtime.getToken`
+ * RPC — the iframe never holds a long-lived credential.
+ */
+export declare class RealtimeModule {
+    private readonly transport;
+    private readonly realtimeUrl;
+    private client;
+    constructor(transport: Transport, realtimeUrl: string | undefined);
+    /** `true` when a realtime endpoint was provided by the host. */
+    get available(): boolean;
+    joinOrCreate<State = unknown>(roomType: string, options?: JoinOptions): Promise<UmicatRoom<State>>;
+    create<State = unknown>(roomType: string, options?: JoinOptions): Promise<UmicatRoom<State>>;
+    join<State = unknown>(roomType: string, options?: JoinOptions): Promise<UmicatRoom<State>>;
+    joinById<State = unknown>(roomId: string, options?: JoinOptions): Promise<UmicatRoom<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 umicat.rooms.list();
+     * rooms
+     *   .filter(r => r.clients < r.maxClients)
+     *   .forEach(r => {
+     *     // render a button; on click: umicat.rooms.joinById(r.roomId)
+     *   });
+     * ```
+     */
+    list(options?: RoomListOptions): Promise<RoomListEntry[]>;
+    private connect;
+}

package/dist/realtime/RealtimeModule.js

@@ -0,0 +1,115 @@
+import { RpcError } from '../core/Transport.js';
+import { UmicatRoom } from './UmicatRoom.js';
+/**
+ * Multiplayer rooms backed by umicat-realtime-service (Colyseus under the hood).
+ *
+ * Availability: only when the host provided a `realtimeUrl` during the
+ * handshake (i.e. connected to umicat-home-ui with multiplayer enabled).
+ * Unavailable in standalone/anonymous mode — methods throw RpcError
+ * 'REALTIME_UNAVAILABLE'.
+ *
+ * Tokens are fetched per connection attempt via the `realtime.getToken`
+ * RPC — the iframe never holds a long-lived credential.
+ */
+export class RealtimeModule {
+    constructor(transport, realtimeUrl) {
+        this.transport = transport;
+        this.realtimeUrl = realtimeUrl;
+        this.client = null;
+    }
+    /** `true` when a realtime endpoint was provided by the host. */
+    get available() {
+        return typeof this.realtimeUrl === 'string' && this.realtimeUrl.length > 0;
+    }
+    async joinOrCreate(roomType, options = {}) {
+        return this.connect(roomType, options, 'joinOrCreate');
+    }
+    async create(roomType, options = {}) {
+        return this.connect(roomType, options, 'create');
+    }
+    async join(roomType, options = {}) {
+        return this.connect(roomType, options, 'join');
+    }
+    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 umicat.rooms.list();
+     * rooms
+     *   .filter(r => r.clients < r.maxClients)
+     *   .forEach(r => {
+     *     // render a button; on click: umicat.rooms.joinById(r.roomId)
+     *   });
+     * ```
+     */
+    async list(options = {}) {
+        if (!this.available) {
+            throw new RpcError('REALTIME_UNAVAILABLE', 'Multiplayer is not available for this host. Umicat.rooms.list requires running inside umicat-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. Umicat.rooms requires running inside umicat-home-ui with realtime enabled.');
+        }
+        if (!this.client) {
+            // Dynamic import so single-player games do not pull Colyseus into their
+            // bundle. Vite tree-shakes this path when `rooms` is never referenced.
+            const { Client } = await import('colyseus.js');
+            this.client = new Client(this.realtimeUrl);
+        }
+        const { token } = await this.transport.call('realtime.getToken', {});
+        // Inject gameId from the transport so the server-side gameId check sees
+        // a value consistent with the JWT — games never pass this directly.
+        const merged = { ...options, gameId: this.transport.gameId };
+        this.client.auth.token = token;
+        const room = await this.client[method](nameOrId, merged);
+        return new UmicatRoom(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/UmicatRoom.d.ts

@@ -0,0 +1,197 @@
+import type { Room } from 'colyseus.js';
+type Unsubscribe = () => void;
+/**
+ * Facade for per-player state — one entry per player, only the owner can write
+ * to their own entry. Delta-synced via Colyseus schema.
+ */
+export declare class PlayerDataFacade {
+    private readonly room;
+    constructor(room: Room<unknown>);
+    /** Write a JSON-serializable value to the caller's own player data. */
+    set(key: string, value: unknown): void;
+    /** Remove a key from the caller's own player data. */
+    delete(key: string): void;
+    /** Read a player's data value. Returns null if the player or key is absent. */
+    get<T = unknown>(sessionId: string, key: string): T | null;
+}
+/**
+ * Facade for room-scope shared state — one map per room, any client may write.
+ * Delta-synced via Colyseus schema. Use for shared game state like current
+ * turn, scoreboard, shared level-of-the-day, etc.
+ */
+export declare class RoomDataFacade {
+    private readonly room;
+    constructor(room: Room<unknown>);
+    /** Write a JSON-serializable value into the room's shared data map. */
+    set(key: string, value: unknown): void;
+    /** Remove a key from the room's shared data map. */
+    delete(key: string): void;
+    /** 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 umicat-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 umicat-design/features/multiplayer-chat.md §3.4.
+ */
+export declare class ChatFacade {
+    private readonly room;
+    private readonly handlers;
+    private remoteOff;
+    /** Sids known to this facade, mapped to the displayName they had at the
+     *  time we last observed them. Populated either at construction (if state
+     *  was already synced) or on the first `onStateChange` (initial hydration
+     *  — silent, no system messages). Subsequent state changes diff against
+     *  this map to emit `system.joined` / `system.left`. We track displayName
+     *  here because by the time a player is detected as "left" they're already
+     *  gone from `state.players` and we can't read it from there. */
+    private readonly knownNames;
+    /** Becomes true the first time we observe a usable `state.players` map.
+     *  The very first observation is treated as "initial state arrived" and
+     *  must NOT fire `system.joined` for the players already in the room when
+     *  the local user joined — only subsequent diffs are real lifecycle events. */
+    private hydrated;
+    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;
+    /**
+     * Hook `onStateChange` to detect joins / leaves and try an eager snapshot
+     * if `state.players` is already populated.
+     *
+     * **The onStateChange subscription must always be set up, even when
+     * `state.players` is `undefined` at construction.** Colyseus 0.16 (and
+     * earlier) deliver the initial state as a *separate* message that arrives
+     * a few ms after `client.joinOrCreate` resolves — so right when UmicatRoom
+     * is constructed, `room.state.players` is typically `undefined`. An earlier
+     * 0.2.14 implementation early-returned in that case and never subscribed,
+     * which meant the diff machinery never armed and BOTH `system.joined` /
+     * `system.left` silently dead-stopped in production (Blokus chat game,
+     * 2026-04-27).
+     *
+     * Eager snapshot if `state.players` is already there sets `hydrated=true`
+     * so the first state change does a real diff. Otherwise the first state
+     * change is treated as initial hydration: populate `knownNames` silently,
+     * skip system messages, set `hydrated=true`. Subsequent state changes do
+     * the real lifecycle diff.
+     *
+     * Why `onStateChange` and not `MapSchema.onAdd` / `.onRemove`: Colyseus
+     * 0.16 dropped those instance methods in favour of a separate
+     * `getStateCallbacks(room)` proxy API. Hooking `onStateChange` and diffing
+     * `players` keys ourselves works the same in any Colyseus version, keeps
+     * us decoupled from the realtime backend's callback shape, and adds < 1ms
+     * of work per state change for typical room sizes (max 16 players).
+     */
+    private subscribeToPlayers;
+    /** Populate `knownNames` from `state.players` if it's already available
+     *  and mark hydrated. Silent — never emits system messages. A successful
+     *  `forEach` (even iterating zero items) means the schema is synced and
+     *  this is "what the room looked like when we joined" — safe to hydrate. */
+    private tryEagerSnapshot;
+    /** Compare current `players` membership against `knownNames`. On the very
+     *  first invocation (post-construction) when `hydrated=false`, this is
+     *  the initial-hydration call: populate `knownNames` silently and bail.
+     *  Subsequent invocations diff against `knownNames` and emit
+     *  `system.joined` for new sids, `system.left` for vanished sids. */
+    private diffPlayers;
+    private dispatch;
+}
+/**
+ * Umicat-flavored wrapper around a Colyseus Room. Exposes only the surface
+ * documented in SDK-GUIDE.md so games are portable to a different realtime
+ * backend should we migrate away from Colyseus.
+ */
+export declare class UmicatRoom<State = unknown> {
+    private readonly room;
+    readonly player: PlayerDataFacade;
+    readonly data: RoomDataFacade;
+    readonly chat: ChatFacade;
+    constructor(room: Room<State>);
+    get id(): string;
+    get name(): string;
+    get sessionId(): string;
+    /**
+     * Current server-authoritative state. Proxied from Colyseus Schema — read
+     * values directly. Mutations do not propagate; only server-side handlers
+     * may change state.
+     */
+    get state(): State;
+    /** Send a transient message. Relayed to every other client in the room
+     *  with `from: sessionId` stamped onto the payload. Not persisted in state. */
+    send(type: string, payload?: unknown): void;
+    /** Register a handler for a server-sent message type. Returns unsubscribe. */
+    on(type: string, handler: (payload: unknown) => void): Unsubscribe;
+    /** Fires whenever the server-authoritative state changes. */
+    onStateChange(handler: (state: State) => void): Unsubscribe;
+    /**
+     * Fires when the connection closes (kick, server shutdown, network drop).
+     * `code` follows WebSocket close codes plus Colyseus-specific ones.
+     */
+    onLeave(handler: (code: number) => void): Unsubscribe;
+    /** Fires when the server reports an error for this room. */
+    onError(handler: (code: number, message?: string) => void): Unsubscribe;
+    /** Disconnect from the room. Resolves with the close code. */
+    leave(consented?: boolean): Promise<number>;
+}
+export {};