@umicat/platform-sdk 0.1.0

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 {};

package/dist/realtime/UmicatRoom.js

@@ -0,0 +1,353 @@
+function parseOrNull(raw) {
+    if (raw == null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Facade for per-player state — one entry per player, only the owner can write
+ * to their own entry. Delta-synced via Colyseus schema.
+ */
+export class PlayerDataFacade {
+    constructor(room) {
+        this.room = room;
+    }
+    /** Write a JSON-serializable value to the caller's own player data. */
+    set(key, value) {
+        this.room.send('player.set', { key, value });
+    }
+    /** Remove a key from the caller's own player data. */
+    delete(key) {
+        this.room.send('player.delete', { key });
+    }
+    /** Read a player's data value. Returns null if the player or key is absent. */
+    get(sessionId, key) {
+        const state = this.room.state;
+        const player = state?.players?.get?.(sessionId);
+        return parseOrNull(player?.data?.get?.(key));
+    }
+}
+/**
+ * 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 class RoomDataFacade {
+    constructor(room) {
+        this.room = room;
+    }
+    /** Write a JSON-serializable value into the room's shared data map. */
+    set(key, value) {
+        this.room.send('room.set', { key, value });
+    }
+    /** Remove a key from the room's shared data map. */
+    delete(key) {
+        this.room.send('room.delete', { key });
+    }
+    /** Read a shared room value. Returns null if the key is absent. */
+    get(key) {
+        const state = this.room.state;
+        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 umicat-design/features/multiplayer-chat.md §3.4.
+ */
+export class ChatFacade {
+    constructor(room) {
+        this.room = room;
+        this.handlers = new Set();
+        this.remoteOff = null;
+        /** 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. */
+        this.knownNames = new Map();
+        /** 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. */
+        this.hydrated = false;
+        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);
+        };
+    }
+    /**
+     * 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).
+     */
+    subscribeToPlayers() {
+        // Always subscribe — regardless of whether `state.players` is populated yet.
+        this.room.onStateChange(() => this.diffPlayers());
+        // Best-effort eager snapshot. If state is already synced (rare — usually
+        // only in tests or on a reconnect to a hot room), this lets us mark
+        // hydrated immediately and treat the first state change as a real diff.
+        this.tryEagerSnapshot();
+    }
+    /** 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. */
+    tryEagerSnapshot() {
+        const players = this.room.state?.players;
+        if (!players || typeof players.forEach !== 'function')
+            return;
+        try {
+            players.forEach((p, sid) => {
+                const name = typeof p?.displayName === 'string' ? p.displayName : '';
+                this.knownNames.set(sid, name);
+            });
+            this.hydrated = true;
+        }
+        catch {
+            // State not iterable yet — leave it for the first onStateChange.
+        }
+    }
+    /** 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. */
+    diffPlayers() {
+        const state = this.room.state;
+        const players = state?.players;
+        if (!players || typeof players.forEach !== 'function')
+            return;
+        if (!this.hydrated) {
+            // Initial hydration — silently absorb whoever's in the room when we
+            // joined. Don't say "X joined" for everyone already there.
+            try {
+                players.forEach((p, sid) => {
+                    const name = typeof p?.displayName === 'string' ? p.displayName : '';
+                    this.knownNames.set(sid, name);
+                });
+            }
+            catch {
+                return;
+            }
+            this.hydrated = true;
+            return;
+        }
+        const nowSids = new Set();
+        try {
+            players.forEach((p, sid) => {
+                nowSids.add(sid);
+                const name = typeof p?.displayName === 'string' ? p.displayName : '';
+                if (this.knownNames.has(sid)) {
+                    // Refresh cached name in case Colyseus updated it post-join.
+                    this.knownNames.set(sid, name);
+                    return;
+                }
+                this.knownNames.set(sid, name);
+                if (sid === this.room.sessionId)
+                    return; // don't announce self-join
+                const who = name || 'A player';
+                this.dispatch({
+                    kind: 'system.joined',
+                    from: sid,
+                    displayName: name,
+                    text: `${who} joined`,
+                    ts: Date.now(),
+                });
+            });
+        }
+        catch {
+            return;
+        }
+        // Anyone in knownNames but not in nowSids has left.
+        for (const sid of [...this.knownNames.keys()]) {
+            if (nowSids.has(sid))
+                continue;
+            const name = this.knownNames.get(sid) ?? '';
+            this.knownNames.delete(sid);
+            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('[umicat.chat] handler threw', err);
+            }
+        }
+    }
+}
+/**
+ * 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 class UmicatRoom {
+    constructor(room) {
+        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; }
+    get sessionId() { return this.room.sessionId; }
+    /**
+     * Current server-authoritative state. Proxied from Colyseus Schema — read
+     * values directly. Mutations do not propagate; only server-side handlers
+     * may change state.
+     */
+    get state() { return this.room.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, payload) {
+        this.room.send(type, payload);
+    }
+    /** Register a handler for a server-sent message type. Returns unsubscribe. */
+    on(type, handler) {
+        return this.room.onMessage(type, handler);
+    }
+    /** Fires whenever the server-authoritative state changes. */
+    onStateChange(handler) {
+        const cb = () => handler(this.room.state);
+        this.room.onStateChange(cb);
+        return () => this.room.onStateChange.remove(cb);
+    }
+    /**
+     * Fires when the connection closes (kick, server shutdown, network drop).
+     * `code` follows WebSocket close codes plus Colyseus-specific ones.
+     */
+    onLeave(handler) {
+        const cb = (code) => handler(code);
+        this.room.onLeave(cb);
+        return () => this.room.onLeave.remove(cb);
+    }
+    /** Fires when the server reports an error for this room. */
+    onError(handler) {
+        const cb = (code, message) => handler(code, message);
+        this.room.onError(cb);
+        return () => this.room.onError.remove(cb);
+    }
+    /** Disconnect from the room. Resolves with the close code. */
+    async leave(consented = true) {
+        return this.room.leave(consented);
+    }
+}

package/dist/saves/SavesModule.d.ts

@@ -0,0 +1,23 @@
+import type { Transport } from '../core/Transport.js';
+/**
+ * Per-user key-value save data scoped to the current (game, user).
+ *
+ * When the viewer is authenticated, reads/writes go through the host to the
+ * Umicat backend. When anonymous or standalone, the same API is backed by
+ * localStorage — games do not branch on auth state.
+ *
+ * Size quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per (game, user)
+ *   - 64 keys per (game, user)
+ */
+export declare class SavesModule {
+    private transport;
+    constructor(transport: Transport);
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, options?: {
+        ifVersion?: number;
+    }): Promise<number>;
+    delete(key: string): Promise<boolean>;
+    list(): Promise<string[]>;
+}

package/dist/saves/SavesModule.js

@@ -0,0 +1,37 @@
+/**
+ * Per-user key-value save data scoped to the current (game, user).
+ *
+ * When the viewer is authenticated, reads/writes go through the host to the
+ * Umicat backend. When anonymous or standalone, the same API is backed by
+ * localStorage — games do not branch on auth state.
+ *
+ * Size quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per (game, user)
+ *   - 64 keys per (game, user)
+ */
+export class SavesModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async get(key) {
+        const res = await this.transport.call('saves.get', { key });
+        return (res?.value ?? null);
+    }
+    async set(key, value, options) {
+        const res = await this.transport.call('saves.set', {
+            key,
+            value,
+            ifVersion: options?.ifVersion,
+        });
+        return res.version;
+    }
+    async delete(key) {
+        const res = await this.transport.call('saves.delete', { key });
+        return res.deleted;
+    }
+    async list() {
+        const res = await this.transport.call('saves.list');
+        return res.keys;
+    }
+}

package/dist/voice/VoiceModule.d.ts

@@ -0,0 +1,44 @@
+import type { Transport } from '../core/Transport.js';
+/** BCP-47 language tag for recognition, e.g. 'en-US', 'zh-CN'. */
+export type VoiceLang = string;
+export interface VoiceCallbacks {
+    /** Interim transcript — updates live, may change. */
+    onPartial?: (text: string) => void;
+    /** The recognized text — fires once, on a clean stop (skipped on cancel/no speech). */
+    onFinal: (text: string) => void;
+    /** Recognition finished — always fires last, after onFinal or on cancel/error. */
+    onEnd: () => void;
+    /** Failure kind, e.g. 'not-allowed' | 'no-speech' | 'network' | 'unavailable'. */
+    onError?: (kind: string) => void;
+}
+export interface VoiceSession {
+    /** Current mic loudness, 0..1 (RMS) — poll each frame to drive a waveform. */
+    level(): number;
+    /** Finish + transcribe (→ onFinal if there was speech). */
+    stop(): void;
+    /** Abort with no transcript. */
+    cancel(): void;
+}
+/**
+ * Voice input — device/platform speech-to-text with a live mic level for
+ * waveform UIs. Access via `umicat.voice`. Never throws from `start()`; it
+ * resolves `null` when unsupported or the mic is denied.
+ */
+export declare class VoiceModule {
+    private transport;
+    constructor(transport: Transport);
+    /** Does this host declare the native voice capability (WebView bridge path)? */
+    private hasHostVoice;
+    /** True if voice input works here — either the native host bridge or the
+     *  browser's own SpeechRecognition + mic. Check before showing a mic button. */
+    supported(): boolean;
+    /**
+     * Start a voice session. Resolves to a {@link VoiceSession}, or `null` if
+     * unsupported / the mic was denied (callers fall back to typing).
+     */
+    start(lang: VoiceLang, cb: VoiceCallbacks): Promise<VoiceSession | null>;
+    /** Native path: drive the platform recognizer through the host bridge. */
+    private startHostVoice;
+}
+/** True if the BROWSER can do speech-to-text (its own recognition) AND give us the mic. */
+export declare function webVoiceSupported(): boolean;