@umicat/platform-sdk 0.1.0

package/dist/gamedata/GameDataModule.js

@@ -0,0 +1,59 @@
+/**
+ * Game-scope key-value store shared by all players of a game.
+ *
+ * Unlike `umicat.saves` (per-user), `gameData` lives at the game level — one
+ * value per key, visible to everyone. Reads are public (anonymous players
+ * see the same data). Writes require an authenticated user; calling
+ * `set()` or `delete()` when `umicat.user === null` throws an `RpcError`
+ * with code `UNAUTHENTICATED`.
+ *
+ * Typical uses: scoreboards, shared inventories, tournament state, level
+ * of the day. Values are opaque JSON — primitive, object, or collection.
+ *
+ * Trust model (see SDK-GUIDE.md for details):
+ *   - The backend does not enforce invariants INSIDE a value. If you store
+ *     a list and append your entry, you own the read-modify-write loop —
+ *     including not mutating other players' entries, truncating to cap
+ *     the list size, and retrying on 409 conflicts.
+ *   - Use `ifVersion` to avoid lost updates when concurrent writes race.
+ *
+ * Quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per game
+ *   - 64 keys per game
+ */
+export class GameDataModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Read the value under `key`. Returns `null` if unset. Public — works for anonymous viewers. */
+    async get(key) {
+        const res = await this.transport.call('gameData.get', { key });
+        return (res?.value ?? null);
+    }
+    /**
+     * Write `value` under `key`. Requires an authenticated user.
+     * @param options.ifVersion — only succeed if the stored version matches; otherwise throws
+     *   an RpcError with code `VERSION_MISMATCH`. Use this to implement safe read-modify-write
+     *   loops for list values (scoreboards, shared lists).
+     * @returns the new version number.
+     */
+    async set(key, value, options) {
+        const res = await this.transport.call('gameData.set', {
+            key,
+            value,
+            ifVersion: options?.ifVersion,
+        });
+        return res.version;
+    }
+    /** Delete the value at `key`. Requires an authenticated user. */
+    async delete(key) {
+        const res = await this.transport.call('gameData.delete', { key });
+        return res.deleted;
+    }
+    /** List all keys that have a value set for this game. Public. */
+    async list() {
+        const res = await this.transport.call('gameData.list');
+        return res.keys;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { UmicatCore } from './core/UmicatCore.js';
+export type { UmicatInitOptions } from './core/UmicatCore.js';
+export { RpcError } from './core/Transport.js';
+export type { Transport, TransportKind } from './core/Transport.js';
+export { PostMessageTransport } from './core/transports/PostMessageTransport.js';
+export { LocalStorageTransport } from './core/transports/LocalStorageTransport.js';
+export { bustCache } from './core/cacheBust.js';
+export { SavesModule } from './saves/SavesModule.js';
+export { GameDataModule } from './gamedata/GameDataModule.js';
+export { RealtimeModule } from './realtime/RealtimeModule.js';
+export { UmicatRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UmicatRoom.js';
+export type { ChatMessage, ChatMessageKind } from './realtime/UmicatRoom.js';
+export type { JoinOptions, RoomListEntry, RoomListOptions } from './realtime/RealtimeModule.js';
+export { AiModule, Npc } from './ai/AiModule.js';
+export type { NpcConfig } from './ai/AiModule.js';
+export { PlatformModule } from './platform/PlatformModule.js';
+export { VoiceModule, webVoiceSupported } from './voice/VoiceModule.js';
+export type { VoiceCallbacks, VoiceSession, VoiceLang } from './voice/VoiceModule.js';
+export { DialogueModule } from './dialogue/DialogueModule.js';
+export type { DialoguePlayOptions, DialogueRenderer } from './dialogue/DialogueModule.js';
+export { DialogueRunner, resolveLangText } from './dialogue/runner.js';
+export type { DialogueScript, DialogueNode, DialogueNodeType, DialogueHost, LangText, DialogueLineNode, DialogueChoiceNode, DialogueChoiceOption, DialogueSetNode, DialogueIfNode, DialogueEndNode, } from './dialogue/runner.js';
+export * from './protocol.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+// @umicat/platform-sdk — the engine-neutral half of the Umicat game SDK.
+//
+// Everything here works the same whether the game is drawn by Phaser, by
+// three.js, or by something we have not chosen yet. Anything that needs to
+// know how pixels get on screen belongs in a runtime package, not here.
+export { UmicatCore } from './core/UmicatCore.js';
+export { RpcError } from './core/Transport.js';
+export { PostMessageTransport } from './core/transports/PostMessageTransport.js';
+export { LocalStorageTransport } from './core/transports/LocalStorageTransport.js';
+export { bustCache } from './core/cacheBust.js';
+export { SavesModule } from './saves/SavesModule.js';
+export { GameDataModule } from './gamedata/GameDataModule.js';
+export { RealtimeModule } from './realtime/RealtimeModule.js';
+export { UmicatRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UmicatRoom.js';
+export { AiModule, Npc } from './ai/AiModule.js';
+export { PlatformModule } from './platform/PlatformModule.js';
+export { VoiceModule, webVoiceSupported } from './voice/VoiceModule.js';
+export { DialogueModule } from './dialogue/DialogueModule.js';
+export { DialogueRunner, resolveLangText } from './dialogue/runner.js';
+export * from './protocol.js';

package/dist/platform/PlatformModule.d.ts

@@ -0,0 +1,47 @@
+import type { Transport } from '../core/Transport.js';
+/**
+ * Actions that belong to the surface the game is running on, rather than to
+ * the game itself.
+ *
+ * Today that is one thing: leaving the game and going back to Umicat.
+ *
+ * ## Why the game owns the exit UI
+ *
+ * On a phone a game fills the screen edge to edge — there is no letterbox for
+ * the platform to hide chrome in, the way a desktop browser has. Anything the
+ * host draws sits on top of art it knows nothing about. Every game's art is
+ * different, so there is no corner that is safe for all of them.
+ *
+ * The host therefore draws nothing during normal play, and the game puts
+ * "Exit" where players already look for it: its own pause or settings menu.
+ * That is also where players expect it — games do not normally keep a quit
+ * button parked on the play field.
+ *
+ * ```ts
+ * exitButton.on('pointerup', () => umicat.platform.exit());
+ * ```
+ *
+ * The host keeps one escape hatch that does not depend on the game working at
+ * all (a two-finger long press, plus a real exit control on the crash and
+ * load-failure screens), because a game that dies before its menu exists must
+ * not be able to trap a player.
+ */
+export declare class PlatformModule {
+    private transport;
+    constructor(transport: Transport);
+    /**
+     * True when a host is attached and can act on `exit()`. False when the game
+     * is running standalone (opened directly, no Umicat around it) — hide your
+     * exit control in that case rather than offering one that does nothing.
+     */
+    get canExit(): boolean;
+    /**
+     * Leave the game and return to Umicat.
+     *
+     * Resolves once the host has accepted the request; the game is usually torn
+     * down immediately after, so do not rely on code that follows. Save first.
+     *
+     * No-op when running standalone — there is nothing to return to.
+     */
+    exit(): Promise<void>;
+}

package/dist/platform/PlatformModule.js

@@ -0,0 +1,63 @@
+import { RpcError } from '../core/Transport.js';
+/**
+ * Actions that belong to the surface the game is running on, rather than to
+ * the game itself.
+ *
+ * Today that is one thing: leaving the game and going back to Umicat.
+ *
+ * ## Why the game owns the exit UI
+ *
+ * On a phone a game fills the screen edge to edge — there is no letterbox for
+ * the platform to hide chrome in, the way a desktop browser has. Anything the
+ * host draws sits on top of art it knows nothing about. Every game's art is
+ * different, so there is no corner that is safe for all of them.
+ *
+ * The host therefore draws nothing during normal play, and the game puts
+ * "Exit" where players already look for it: its own pause or settings menu.
+ * That is also where players expect it — games do not normally keep a quit
+ * button parked on the play field.
+ *
+ * ```ts
+ * exitButton.on('pointerup', () => umicat.platform.exit());
+ * ```
+ *
+ * The host keeps one escape hatch that does not depend on the game working at
+ * all (a two-finger long press, plus a real exit control on the crash and
+ * load-failure screens), because a game that dies before its menu exists must
+ * not be able to trap a player.
+ */
+export class PlatformModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * True when a host is attached and can act on `exit()`. False when the game
+     * is running standalone (opened directly, no Umicat around it) — hide your
+     * exit control in that case rather than offering one that does nothing.
+     */
+    get canExit() {
+        return this.transport.kind !== 'standalone';
+    }
+    /**
+     * Leave the game and return to Umicat.
+     *
+     * Resolves once the host has accepted the request; the game is usually torn
+     * down immediately after, so do not rely on code that follows. Save first.
+     *
+     * No-op when running standalone — there is nothing to return to.
+     */
+    async exit() {
+        if (!this.canExit)
+            return;
+        try {
+            await this.transport.call('platform.exit');
+        }
+        catch (error) {
+            // An older host will not know the method. That is not the game's problem
+            // and should not surface as an unhandled rejection mid-play.
+            if (error instanceof RpcError && error.code === 'UNKNOWN_METHOD')
+                return;
+            throw error;
+        }
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Wire protocol between a game and its Umicat host.
+ *
+ * Extracted from `@umicat/phaser-sdk`'s `protocol.ts`, which carries BOTH this
+ * platform/RPC contract and the 2D editor + tilemap message set. Only the
+ * platform half is engine-neutral, so only that half lives here; the editor
+ * half stays with the Phaser SDK that implements it.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export interface UmicatUser {
+    id: string;
+    name: string;
+    avatar?: string;
+}
+export interface HelloMessage {
+    type: 'umicat:hello';
+    protocolVersion: number;
+    sdkVersion: string;
+}
+export interface RpcRequestMessage {
+    type: 'umicat:rpc';
+    id: string;
+    method: string;
+    params?: unknown;
+}
+export type SdkToHostMessage = HelloMessage | RpcRequestMessage;
+export interface InitMessage {
+    type: 'umicat:init';
+    protocolVersion: number;
+    gameId: string;
+    user: UmicatUser | null;
+    capabilities: string[];
+    /**
+     * WebSocket endpoint for umicat-realtime-service. Present only when the host
+     * has multiplayer configured (capabilities includes 'realtime'). SDK connects
+     * here after fetching a JWT via the 'realtime.getToken' RPC.
+     */
+    realtimeUrl?: string;
+    /**
+     * The player's preferred language (the host's UI locale, e.g. 'en', 'zh-CN',
+     * 'ja'). Lets a game default its UI + AI NPC language to the player's without
+     * asking. Absent in standalone mode → SDK falls back to the browser locale.
+     */
+    locale?: string;
+}
+export interface RpcResultOk {
+    type: 'umicat:rpc.result';
+    id: string;
+    ok: true;
+    result: unknown;
+}
+export interface RpcErrorPayload {
+    code: string;
+    message: string;
+}
+export interface RpcResultError {
+    type: 'umicat:rpc.result';
+    id: string;
+    ok: false;
+    error: RpcErrorPayload;
+}
+export interface VoiceEventMessage {
+    type: 'umicat:voice';
+    /**
+     * 'partial' — live (may change) transcript · 'final' — the recognized text ·
+     * 'level' — current mic loudness 0..1 (drive a waveform) · 'end' — session
+     * finished (fires once, after any final) · 'error' — recognition failed.
+     */
+    event: 'partial' | 'final' | 'level' | 'end' | 'error';
+    /** partial / final transcript text. */
+    text?: string;
+    /** 'level' loudness, 0..1. */
+    level?: number;
+    /** 'error' kind, e.g. 'not-allowed' | 'no-speech' | 'unavailable'. */
+    code?: string;
+}
+/** Params for the `voice.start` RPC. */
+export interface VoiceStartParams {
+    /** BCP-47 language tag for recognition, e.g. 'en-US', 'zh-CN'. */
+    lang: string;
+}
+export type HostToSdkMessage = InitMessage | RpcResultOk | RpcResultError | VoiceEventMessage;
+/**
+ * Patch shape applied to a live entity. Only the fields present are updated;
+ * `null` is the explicit clear (drops the field).
+ *
+ * **Flat schema** (SDK 0.3.0). Visual / render fields live at the patch root,
+ * the same place they live on the entity. Sprite tint goes in `tint`, not
+ * `visual.tint`. Same rule for every renderable field across every entity kind.
+ *
+ * The bridge applies only the slot relevant to the entity's kind — passing
+ * `width` on a sprite is a no-op, same as `tint` on a panel.
+ */
+export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list' | 'realtime.getToken' | 'ai.act' | 'ai.complete';
+export interface SavesGetParams {
+    key: string;
+}
+export interface SavesGetResult {
+    value: unknown | null;
+    version: number | null;
+}
+export interface SavesSetParams {
+    key: string;
+    value: unknown;
+    ifVersion?: number;
+}
+export interface SavesSetResult {
+    version: number;
+}
+export interface SavesDeleteParams {
+    key: string;
+}
+export type SavesDeleteResult = {
+    deleted: boolean;
+};
+export interface SavesListResult {
+    keys: string[];
+}
+export interface GameDataGetParams {
+    key: string;
+}
+export interface GameDataGetResult {
+    value: unknown | null;
+    version: number | null;
+}
+export interface GameDataSetParams {
+    key: string;
+    value: unknown;
+    ifVersion?: number;
+}
+export interface GameDataSetResult {
+    version: number;
+}
+export interface GameDataDeleteParams {
+    key: string;
+}
+export type GameDataDeleteResult = {
+    deleted: boolean;
+};
+export interface GameDataListResult {
+    keys: string[];
+}
+/** Why an ai.act could not run. The game branches on these in-fiction. */
+export type AiReason = 'SIGN_IN_REQUIRED' | 'INSUFFICIENT_CREDITS' | 'RATE_LIMITED' | 'UNAVAILABLE';
+export interface AiPersona {
+    role?: string;
+    goals?: string[];
+    style?: string;
+    rules?: string[];
+}
+/** Shorthand arg spec — `{ field: "string" | "number" | "integer" | "boolean" }`. */
+export interface AiActionDef {
+    name: string;
+    description?: string;
+    args?: Record<string, string>;
+}
+export interface AiHistoryMsg {
+    from: 'player' | 'npc' | 'event';
+    text?: string;
+    data?: unknown;
+}
+export interface AiActOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+export interface AiActParams {
+    /**
+     * Name of a playbook shipped with the game at `public/playbooks/<name>.md`
+     * (ADR-018) — a natural-language behavior pack (persona + strategy) the platform
+     * loads and injects. Pass just the NAME; the host resolves it under the game's
+     * own id (tamper-resistant). Supplies the character behavior; can be combined
+     * with `persona` (the playbook leads, `persona` augments).
+     */
+    playbook?: string;
+    persona?: AiPersona;
+    /** Arbitrary game-defined JSON of what the AI perceives this turn. */
+    observation?: unknown;
+    actions?: AiActionDef[];
+    history?: AiHistoryMsg[];
+    options?: AiActOptions;
+}
+/** A player-level intent the AI chose — the game must validate + execute it. */
+export interface AiActionCall {
+    name: string;
+    args: unknown;
+}
+export interface AiUsage {
+    credits: number;
+    balanceCredits: number;
+    limitReached: boolean;
+    model: string;
+}
+export interface AiActSuccess {
+    ok: true;
+    /** Dialogue — display only, no state effect. */
+    say?: string;
+    /** Chosen player-level intents — the game validates + executes each. */
+    do?: AiActionCall[];
+    usage?: AiUsage;
+}
+export interface AiActFailure {
+    ok: false;
+    reason: AiReason;
+}
+export type AiActResult = AiActSuccess | AiActFailure;
+export interface AiCompleteParams {
+    /** The prompt to complete. Required. Untrusted to the platform — the safety rails win. */
+    prompt: string;
+    /** Optional extra system framing; the platform PREPENDS its own safety preamble (can't be stripped). */
+    system?: string;
+    /** Max response tokens (backend clamps + applies a small default — this is a utility call, not a chat). */
+    maxTokens?: number;
+    /** Sampling temperature (backend clamps). */
+    temperature?: number;
+    /** Model id (backend allow-lists + defaults to a cheap model). */
+    model?: string;
+}
+export interface AiCompleteSuccess {
+    ok: true;
+    /** The model's text output. */
+    text: string;
+    usage?: AiUsage;
+}
+export interface AiCompleteFailure {
+    ok: false;
+    reason: AiReason;
+}
+export type AiCompleteResult = AiCompleteSuccess | AiCompleteFailure;
+export interface RealtimeGetTokenParams {
+    /** Opaque, forwarded to server-side auth (future use). */
+    purpose?: string;
+}
+export interface RealtimeGetTokenResult {
+    token: string;
+    /** Epoch millis when the token expires. */
+    expiresAt: number;
+}

package/dist/protocol.js

@@ -0,0 +1,11 @@
+/**
+ * Wire protocol between a game and its Umicat host.
+ *
+ * Extracted from `@umicat/phaser-sdk`'s `protocol.ts`, which carries BOTH this
+ * platform/RPC contract and the 2D editor + tilemap message set. Only the
+ * platform half is engine-neutral, so only that half lives here; the editor
+ * half stays with the Phaser SDK that implements it.
+ */
+// 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;
+}