@umicat/platform-sdk 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# @umicat/platform-sdk
+
+The engine-neutral half of the Umicat game SDK. Identity, cloud saves, shared
+game data, multiplayer rooms, runtime AI, voice input and scripted dialogue —
+none of which care how pixels get on screen.
+
+**Status: extracted and verified, not yet adopted.** `@umicat/phaser-sdk` still
+ships its own copies; the swap is proven safe by `scripts/verify-swap.mjs` but
+has not been applied, because applying it requires publishing this package to
+npm first. Nothing in production consumes this yet.
+
+## Why it exists
+
+`@umicat/phaser-sdk` is ~19.4k LOC, of which roughly four fifths is the scene
+system and the editor — genuinely Phaser-shaped. The rest was already written
+without touching Phaser, and it is the part every runtime needs: a 3D SDK, the
+iOS and Android clients, anything we build next.
+
+The one thing keeping it tangled was the composition root, which constructed a
+Phaser dialogue box. That is now injected, so `UmicatCore` is a platform with no
+opinion about rendering, and a runtime subclasses it to add what needs a canvas.
+
+See ADR-033 in `umicat-design`.
+
+```ts
+// A runtime wires the platform in, then adds its own engine-shaped modules.
+import { UmicatCore } from '@umicat/platform-sdk';
+
+class ThreeUmicat extends UmicatCore {
+  static async init(options = {}) {
+    return new ThreeUmicat(await UmicatCore.connect(MY_SDK_VERSION, options));
+  }
+}
+
+const umicat = await ThreeUmicat.init();
+await umicat.saves.set('progress', { level: 3 });
+const reply = await umicat.ai.complete('Greet the player by name');
+```
+
+## What is here, and what deliberately is not
+
+| in | out |
+|---|---|
+| `UmicatCore` — transports, handshake, identity | anything that draws |
+| `saves`, `gameData`, `rooms`, `ai`, `platform`, `voice` | the scene system, prefabs, HUD, tilemaps |
+| `DialogueModule` + `DialogueRunner`, renderer injected | `DialogueBox` (Phaser), screenshot/recording (take a `Phaser.Game`) |
+| the platform/RPC half of `protocol.ts` | the editor + tilemap message half |
+
+## Verifying a change
+
+```bash
+npm test                      # engine-neutrality contracts + dialogue behaviour
+node scripts/verify-swap.mjs  # proves @umicat/phaser-sdk still builds, exports
+                              # an identical API, and passes its whole suite
+```
+
+`verify-swap.mjs` copies both repos to a scratch dir, rewires the copy, and
+asserts the 105 exported names are unchanged and the Phaser SDK's 39 unit tests
+plus 3 browser tests still pass. **It never writes to either real repo.**
+
+## Two traps worth knowing
+
+**Deep imports, not the barrel.** The shims `apply-swap.mjs` writes point at
+`@umicat/platform-sdk/saves/SavesModule.js`, not at the package root. A barrel
+re-export would pull the whole index — and with it the realtime module — into
+every file that merely wanted `Transport`, silently changing the module graph of
+every game. Colyseus is lazily imported (`await import('colyseus.js')`), and a
+test asserts the package has **zero** static third-party imports so it stays
+that way.
+
+**Explicit `.js` in specifiers.** `moduleResolution: bundler` lets you write
+`@umicat/platform-sdk/dialogue/DialogueModule`, and tsc emits that string verbatim.
+Bundlers cope; a browser loading `dist/` raw — which the Phaser SDK's own
+browser tests do — gets a 404. Hence `.js` everywhere and both subpath patterns
+in `exports`.
+
+## Provenance
+
+Every module here was copied from `umicat-phaser-sdk/src` at v1.0.90 and, except
+where noted, is byte-identical. The changes were: `UmicatCore` (dialogue no
+longer constructed in the composition root), `DialogueModule` (renderer injected,
+generic over scene/theme), and `protocol.ts` (split at the editor boundary).

package/dist/ai/AiModule.d.ts

@@ -0,0 +1,62 @@
+import type { Transport } from '../core/Transport.js';
+import type { AiActParams, AiActResult, AiCompleteParams, AiCompleteResult, AiActionDef } from '../protocol.js';
+/**
+ * Runtime AI (ADR-017) — let the game call an in-game LLM at play time
+ * ("living NPCs" / AI opponents). The AI is a *virtual player*: it can only
+ * TALK (`say`) and CHOOSE an action (`do`) from the vocabulary the game
+ * declares — it never mutates game state, which stays the game's job.
+ *
+ * `act()` always RESOLVES with a structured {@link AiActResult} — never throws —
+ * so the game can branch in-fiction on `{ ok:false, reason }` (e.g. prompt an
+ * anonymous player to sign in on `SIGN_IN_REQUIRED`). The player is billed.
+ */
+export declare class AiModule {
+    private transport;
+    constructor(transport: Transport);
+    act(params: AiActParams): Promise<AiActResult>;
+    /**
+     * Generic ONE-SHOT completion — a raw prompt→text LLM call (ADR-028), the utility
+     * sibling of {@link act}. The game supplies the whole prompt and decides what the text
+     * is for (summarize / classify / name-generate / score / …); the platform stays
+     * task-neutral (auth + credits + safety rails + passthrough). No persona / actions /
+     * history — for in-character dialogue use `npc().say()` instead.
+     *
+     * Like {@link act}, it always RESOLVES with a structured result — never throws — so the
+     * game can branch on `{ ok:false, reason }` (e.g. skip today's summary on
+     * `INSUFFICIENT_CREDITS`). The player is billed.
+     */
+    complete(params: AiCompleteParams): Promise<AiCompleteResult>;
+    /** Higher-level helper: a persona-bound NPC that keeps its own conversation. */
+    npc(config: NpcConfig): Npc;
+}
+export interface NpcConfig {
+    /**
+     * Name of a playbook shipped at `public/playbooks/<name>.md` (ADR-018) — the
+     * NPC's persona + strategy as editable natural language, kept OUT of code.
+     * Preferred over the inline `role`/`goals`/`style` for any non-trivial
+     * character (you can tune behavior by editing the `.md`, no code change).
+     */
+    playbook?: string;
+    role?: string;
+    goals?: string[];
+    style?: string;
+    rules?: string[];
+    actions?: AiActionDef[];
+}
+/**
+ * A single NPC / opponent conversation. Maintains its own history so the game
+ * just calls `say(...)`; the persona + declared actions ride along every turn.
+ */
+export declare class Npc {
+    private ai;
+    private config;
+    private history;
+    constructor(ai: AiModule, config: NpcConfig);
+    say(playerLine: string, opts?: {
+        observation?: unknown;
+    }): Promise<AiActResult>;
+    /** Record a world event the NPC should be aware of next turn (no LLM call). */
+    note(text: string): void;
+    /** Forget the conversation (e.g. the player walked away and came back fresh). */
+    reset(): void;
+}

package/dist/ai/AiModule.js

@@ -0,0 +1,107 @@
+import { RpcError } from '../core/Transport.js';
+// LLM latency routinely exceeds the default 10s RPC timeout — give the host
+// (which does the Anthropic round-trip) headroom.
+const AI_RPC_TIMEOUT_MS = 60000;
+/**
+ * Runtime AI (ADR-017) — let the game call an in-game LLM at play time
+ * ("living NPCs" / AI opponents). The AI is a *virtual player*: it can only
+ * TALK (`say`) and CHOOSE an action (`do`) from the vocabulary the game
+ * declares — it never mutates game state, which stays the game's job.
+ *
+ * `act()` always RESOLVES with a structured {@link AiActResult} — never throws —
+ * so the game can branch in-fiction on `{ ok:false, reason }` (e.g. prompt an
+ * anonymous player to sign in on `SIGN_IN_REQUIRED`). The player is billed.
+ */
+export class AiModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async act(params) {
+        try {
+            // The host returns the structured outcome INSIDE the RPC result, so a
+            // host-level `{ ok:false, reason }` comes back here as-is. The catch below
+            // only fires for transport failures (timeout, no host, unknown method).
+            return await this.transport.call('ai.act', params, AI_RPC_TIMEOUT_MS);
+        }
+        catch (err) {
+            return { ok: false, reason: toReason(err) };
+        }
+    }
+    /**
+     * Generic ONE-SHOT completion — a raw prompt→text LLM call (ADR-028), the utility
+     * sibling of {@link act}. The game supplies the whole prompt and decides what the text
+     * is for (summarize / classify / name-generate / score / …); the platform stays
+     * task-neutral (auth + credits + safety rails + passthrough). No persona / actions /
+     * history — for in-character dialogue use `npc().say()` instead.
+     *
+     * Like {@link act}, it always RESOLVES with a structured result — never throws — so the
+     * game can branch on `{ ok:false, reason }` (e.g. skip today's summary on
+     * `INSUFFICIENT_CREDITS`). The player is billed.
+     */
+    async complete(params) {
+        try {
+            return await this.transport.call('ai.complete', params, AI_RPC_TIMEOUT_MS);
+        }
+        catch (err) {
+            return { ok: false, reason: toReason(err) };
+        }
+    }
+    /** Higher-level helper: a persona-bound NPC that keeps its own conversation. */
+    npc(config) {
+        return new Npc(this, config);
+    }
+}
+/**
+ * A single NPC / opponent conversation. Maintains its own history so the game
+ * just calls `say(...)`; the persona + declared actions ride along every turn.
+ */
+export class Npc {
+    constructor(ai, config) {
+        this.ai = ai;
+        this.config = config;
+        this.history = [];
+    }
+    async say(playerLine, opts) {
+        this.history.push({ from: 'player', text: playerLine });
+        const res = await this.ai.act({
+            playbook: this.config.playbook,
+            persona: {
+                role: this.config.role,
+                goals: this.config.goals,
+                style: this.config.style,
+                rules: this.config.rules,
+            },
+            actions: this.config.actions,
+            observation: opts?.observation,
+            history: this.history,
+        });
+        if (res.ok && res.say)
+            this.history.push({ from: 'npc', text: res.say });
+        return res;
+    }
+    /** Record a world event the NPC should be aware of next turn (no LLM call). */
+    note(text) {
+        this.history.push({ from: 'event', text });
+    }
+    /** Forget the conversation (e.g. the player walked away and came back fresh). */
+    reset() {
+        this.history = [];
+    }
+}
+/** Map a transport-level error code to a structured reason. Host-level failures
+ *  already arrive as `{ ok:false, reason }` and never reach this. */
+function toReason(err) {
+    const code = err instanceof RpcError ? err.code : '';
+    switch (code) {
+        case 'SIGN_IN_REQUIRED':
+        case 'UNAUTHENTICATED':
+            return 'SIGN_IN_REQUIRED';
+        case 'INSUFFICIENT_CREDITS':
+        case 'PAYMENT_REQUIRED':
+            return 'INSUFFICIENT_CREDITS';
+        case 'RATE_LIMITED':
+            return 'RATE_LIMITED';
+        default:
+            return 'UNAVAILABLE';
+    }
+}

package/dist/core/Transport.d.ts

@@ -0,0 +1,42 @@
+import type { UmicatUser } from '../protocol.js';
+/**
+ * Low-level transport for platform RPC calls. Swapped per host.
+ *
+ * Current implementations:
+ *   - PostMessageTransport: iframe hosted inside umicat-home-ui
+ *   - LocalStorageTransport: game running standalone (no host, no user)
+ *
+ * Future implementations (not shipped):
+ *   - DiscordTransport: game running as a Discord Activity
+ */
+export interface Transport {
+    readonly kind: TransportKind;
+    readonly user: UmicatUser | null;
+    readonly gameId: string;
+    /**
+     * Endpoint for umicat-realtime-service (WebSocket URL). Set by the host
+     * during handshake when multiplayer is enabled. Absent in standalone mode —
+     * `umicat.rooms.*` is unavailable in that case.
+     */
+    readonly realtimeUrl?: string;
+    /** The player's preferred language (BCP-47-ish, e.g. 'en', 'zh-CN'). The host
+     *  provides it at handshake; standalone falls back to the browser locale. */
+    readonly locale?: string;
+    /** Capabilities the host advertised at handshake (e.g. 'voice' when the native
+     *  app can run platform speech-to-text). Empty/undefined when standalone or on
+     *  a host that doesn't declare them. Lets modules feature-detect host-backed
+     *  primitives (see VoiceModule). */
+    readonly capabilities?: readonly string[];
+    /** Subscribe to a host-pushed event stream (e.g. 'umicat:voice' streaming
+     *  transcript + mic level). Returns an unsubscribe fn. Only hosts that push
+     *  events implement this; absent on standalone — callers must feature-detect. */
+    on?(event: string, handler: (payload: unknown) => void): () => void;
+    /** `timeoutMs` overrides the default RPC timeout — runtime-AI calls need
+     *  longer than the 10s default for LLM latency. */
+    call<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
+}
+export type TransportKind = 'umicat-home-ui' | 'standalone' | 'discord';
+export declare class RpcError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}

package/dist/core/Transport.js

@@ -0,0 +1,7 @@
+export class RpcError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'RpcError';
+    }
+}

package/dist/core/UmicatCore.d.ts

@@ -0,0 +1,80 @@
+import type { Transport, TransportKind } from './Transport.js';
+import { SavesModule } from '../saves/SavesModule.js';
+import { GameDataModule } from '../gamedata/GameDataModule.js';
+import { RealtimeModule } from '../realtime/RealtimeModule.js';
+import { AiModule } from '../ai/AiModule.js';
+import { PlatformModule } from '../platform/PlatformModule.js';
+import { VoiceModule } from '../voice/VoiceModule.js';
+import type { UmicatUser } from '../protocol.js';
+export interface UmicatInitOptions {
+    /** Handshake timeout in ms when running inside a host. Default 5000. */
+    handshakeTimeoutMs?: number;
+    /**
+     * Game ID used for the localStorage fallback. Ignored when connected to a
+     * host (the host provides the authoritative gameId). Default 'standalone'.
+     */
+    standaloneGameId?: string;
+}
+/**
+ * Umicat platform services bound to the current (game, user) — with no
+ * rendering engine anywhere in sight.
+ *
+ * The public API is host-agnostic: `connect()` detects the host (home-ui
+ * iframe, Discord Activity, or standalone) and picks the right transport.
+ * Games should not care which one is active.
+ *
+ * **Why this class exists separately from `@umicat/phaser-sdk`'s `Umicat`.**
+ * Identity, cloud saves, shared game data, multiplayer, runtime AI and voice
+ * are the same for every runtime we will ever ship. They were already written
+ * without touching Phaser; the only thing tying the composition root to a 2D
+ * engine was that it constructed a Phaser dialogue box. That is now the
+ * subclass's job, so a 3D runtime — or an engine we have not picked yet —
+ * inherits the platform whole instead of reimplementing it.
+ *
+ * Runtimes extend this and add their own engine-shaped modules:
+ * `@umicat/phaser-sdk`'s `Umicat` adds `dialogue` wired to `DialogueBox`.
+ */
+export declare class UmicatCore {
+    protected readonly transport: Transport;
+    readonly saves: SavesModule;
+    readonly gameData: GameDataModule;
+    readonly rooms: RealtimeModule;
+    /** Runtime AI — in-game LLM / living NPCs (ADR-017). */
+    readonly ai: AiModule;
+    /** Actions that belong to the surface, not the game — today: leaving it. */
+    readonly platform: PlatformModule;
+    /** Voice input (speech-to-text) with a live mic level for waveform UIs.
+     *  Browser recognition in a browser, native platform recognizer in the app. */
+    readonly voice: VoiceModule;
+    protected constructor(transport: Transport);
+    /** The current authenticated user, or `null` if anonymous / standalone. */
+    get user(): UmicatUser | null;
+    get isAuthenticated(): boolean;
+    /** Stable game identifier issued by the host. May be a placeholder when standalone. */
+    get gameId(): string;
+    /** The player's preferred language (e.g. 'en', 'zh-CN'). Use it to default the
+     *  game's UI + AI NPC language. See the game-i18n skill. */
+    get locale(): string;
+    /** Which transport the handshake selected. Useful for debugging. */
+    get host(): TransportKind;
+    /**
+     * Negotiate a transport. Runtimes call this from their own `init()` and pass
+     * the result to their constructor.
+     *
+     * Resolution order:
+     *   1. If embedded in a window that responds to the Umicat handshake → PostMessageTransport
+     *   2. Otherwise → LocalStorageTransport (anonymous, local-only saves)
+     *
+     * `sdkVersion` is reported to the host in the handshake. Each runtime passes
+     * its OWN published version — the core does not have a meaningful one to
+     * report, and the host uses it to reason about the game's capabilities.
+     */
+    static connect(sdkVersion: string, options?: UmicatInitOptions): Promise<Transport>;
+    /**
+     * Standalone entry point for runtimes that add no modules of their own.
+     * Named `start`, not `init`, deliberately: a subclass wants `init()` for its
+     * own richer return type, and TypeScript forbids a static override whose
+     * signature is incompatible with the base.
+     */
+    static start(sdkVersion: string, options?: UmicatInitOptions): Promise<UmicatCore>;
+}

package/dist/core/UmicatCore.js

@@ -0,0 +1,89 @@
+import { PostMessageTransport } from './transports/PostMessageTransport.js';
+import { LocalStorageTransport } from './transports/LocalStorageTransport.js';
+import { SavesModule } from '../saves/SavesModule.js';
+import { GameDataModule } from '../gamedata/GameDataModule.js';
+import { RealtimeModule } from '../realtime/RealtimeModule.js';
+import { AiModule } from '../ai/AiModule.js';
+import { PlatformModule } from '../platform/PlatformModule.js';
+import { VoiceModule } from '../voice/VoiceModule.js';
+/**
+ * Umicat platform services bound to the current (game, user) — with no
+ * rendering engine anywhere in sight.
+ *
+ * The public API is host-agnostic: `connect()` detects the host (home-ui
+ * iframe, Discord Activity, or standalone) and picks the right transport.
+ * Games should not care which one is active.
+ *
+ * **Why this class exists separately from `@umicat/phaser-sdk`'s `Umicat`.**
+ * Identity, cloud saves, shared game data, multiplayer, runtime AI and voice
+ * are the same for every runtime we will ever ship. They were already written
+ * without touching Phaser; the only thing tying the composition root to a 2D
+ * engine was that it constructed a Phaser dialogue box. That is now the
+ * subclass's job, so a 3D runtime — or an engine we have not picked yet —
+ * inherits the platform whole instead of reimplementing it.
+ *
+ * Runtimes extend this and add their own engine-shaped modules:
+ * `@umicat/phaser-sdk`'s `Umicat` adds `dialogue` wired to `DialogueBox`.
+ */
+export class UmicatCore {
+    constructor(transport) {
+        this.transport = transport;
+        // Saves are per-user. When the viewer is anonymous, route save calls to
+        // localStorage even if a host is attached — the backend requires auth,
+        // so forwarding would 401. Games see the same `umicat.saves` API either
+        // way and don't have to branch on auth state.
+        const savesTransport = transport.user === null
+            ? new LocalStorageTransport(transport.gameId || 'anonymous')
+            : transport;
+        this.saves = new SavesModule(savesTransport);
+        // gameData is game-scope: reads are public (anonymous OK), only writes
+        // need auth. The primary transport handles both; if it's a LocalStorage
+        // fallback (standalone mode) that also works — the module speaks the
+        // same RPC interface.
+        this.gameData = new GameDataModule(transport);
+        // Multiplayer requires a realtime endpoint from the host. When absent
+        // (standalone or a host without multiplayer), methods throw a clear
+        // REALTIME_UNAVAILABLE error rather than silently misbehaving.
+        this.rooms = new RealtimeModule(transport, transport.realtimeUrl);
+        this.ai = new AiModule(transport);
+        this.platform = new PlatformModule(transport);
+        this.voice = new VoiceModule(transport);
+    }
+    /** The current authenticated user, or `null` if anonymous / standalone. */
+    get user() { return this.transport.user; }
+    get isAuthenticated() { return this.transport.user !== null; }
+    /** Stable game identifier issued by the host. May be a placeholder when standalone. */
+    get gameId() { return this.transport.gameId; }
+    /** The player's preferred language (e.g. 'en', 'zh-CN'). Use it to default the
+     *  game's UI + AI NPC language. See the game-i18n skill. */
+    get locale() { return this.transport.locale ?? 'en'; }
+    /** Which transport the handshake selected. Useful for debugging. */
+    get host() { return this.transport.kind; }
+    /**
+     * Negotiate a transport. Runtimes call this from their own `init()` and pass
+     * the result to their constructor.
+     *
+     * Resolution order:
+     *   1. If embedded in a window that responds to the Umicat handshake → PostMessageTransport
+     *   2. Otherwise → LocalStorageTransport (anonymous, local-only saves)
+     *
+     * `sdkVersion` is reported to the host in the handshake. Each runtime passes
+     * its OWN published version — the core does not have a meaningful one to
+     * report, and the host uses it to reason about the game's capabilities.
+     */
+    static async connect(sdkVersion, options = {}) {
+        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5000;
+        const standaloneGameId = options.standaloneGameId ?? 'standalone';
+        const pm = await PostMessageTransport.connect(handshakeTimeoutMs, sdkVersion);
+        return pm ?? new LocalStorageTransport(standaloneGameId);
+    }
+    /**
+     * Standalone entry point for runtimes that add no modules of their own.
+     * Named `start`, not `init`, deliberately: a subclass wants `init()` for its
+     * own richer return type, and TypeScript forbids a static override whose
+     * signature is incompatible with the base.
+     */
+    static async start(sdkVersion, options = {}) {
+        return new UmicatCore(await UmicatCore.connect(sdkVersion, options));
+    }
+}

package/dist/core/cacheBust.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cache-bust fixed-path content fetches (manifest / scene / HUD / tilemap /
+ * atlas / rules / waves / game.json).
+ *
+ * These files live at STABLE urls (`scenes/world/main.json`, …) but their
+ * CONTENTS change every build / republish. The session-server serves them
+ * `no-cache` (revalidate), which is correct — BUT if any deploy path ever
+ * mistakenly served one `immutable` (a header bug), the browser caches it and
+ * NEVER revalidates, even on hard refresh. The stale copy then sticks: the game
+ * reloads after a Build / republish and the SDK re-fetches the scene, but the
+ * browser hands back the OLD bytes → "my edits reverted after Build", and a
+ * republished game shows players the previous version. This bit Catopia twice
+ * (world `main.json`, then `game-hud.json`).
+ *
+ * Fix: append a per-BUILD token to each such fetch. The token is the game's
+ * hashed bundle filename (`index-DAxxxx`), which Vite regenerates every build —
+ * so each build gets a FRESH url the browser has never cached (defeating any
+ * stale `immutable` entry), while the url stays IDENTICAL within a build (so the
+ * CDN still caches it — no per-request S3 hit). Content-hashed `assets/**` are
+ * untouched (already correctly `immutable`).
+ */
+/** The per-build cache token (memoized once per page load). */
+export declare function buildCacheToken(): string;
+/** Append the per-build cache-bust query param to a fetch path. */
+export declare function bustCache(path: string): string;

package/dist/core/cacheBust.js

@@ -0,0 +1,59 @@
+/**
+ * Cache-bust fixed-path content fetches (manifest / scene / HUD / tilemap /
+ * atlas / rules / waves / game.json).
+ *
+ * These files live at STABLE urls (`scenes/world/main.json`, …) but their
+ * CONTENTS change every build / republish. The session-server serves them
+ * `no-cache` (revalidate), which is correct — BUT if any deploy path ever
+ * mistakenly served one `immutable` (a header bug), the browser caches it and
+ * NEVER revalidates, even on hard refresh. The stale copy then sticks: the game
+ * reloads after a Build / republish and the SDK re-fetches the scene, but the
+ * browser hands back the OLD bytes → "my edits reverted after Build", and a
+ * republished game shows players the previous version. This bit Catopia twice
+ * (world `main.json`, then `game-hud.json`).
+ *
+ * Fix: append a per-BUILD token to each such fetch. The token is the game's
+ * hashed bundle filename (`index-DAxxxx`), which Vite regenerates every build —
+ * so each build gets a FRESH url the browser has never cached (defeating any
+ * stale `immutable` entry), while the url stays IDENTICAL within a build (so the
+ * CDN still caches it — no per-request S3 hit). Content-hashed `assets/**` are
+ * untouched (already correctly `immutable`).
+ */
+let cached = null;
+function computeToken() {
+    try {
+        if (typeof document !== 'undefined') {
+            // Vite emits one `<script type="module" src="/assets/index-<hash>.js">`.
+            // The hash changes per build → perfect per-build cache key.
+            const s = document.querySelector('script[type="module"][src]');
+            const src = s?.src;
+            if (src) {
+                const file = src.split('/').pop();
+                if (file)
+                    return file.replace(/\.[a-z0-9]+$/i, ''); // "index-DAxxxx"
+            }
+        }
+    }
+    catch {
+        /* fall through to the random fallback */
+    }
+    // No module script found (unusual host / test harness): a per-LOAD token —
+    // still never serves stale, at the cost of a re-fetch each load.
+    try {
+        return 'r' + Math.random().toString(36).slice(2, 10);
+    }
+    catch {
+        return 'v';
+    }
+}
+/** The per-build cache token (memoized once per page load). */
+export function buildCacheToken() {
+    if (cached === null)
+        cached = computeToken();
+    return cached;
+}
+/** Append the per-build cache-bust query param to a fetch path. */
+export function bustCache(path) {
+    const sep = path.includes('?') ? '&' : '?';
+    return `${path}${sep}v=${encodeURIComponent(buildCacheToken())}`;
+}

package/dist/core/transports/LocalStorageTransport.d.ts

@@ -0,0 +1,24 @@
+import type { Transport } from '../Transport.js';
+import type { UmicatUser } from '../../protocol.js';
+/**
+ * Fallback transport when the game runs without a host (e.g., opened directly
+ * outside umicat-home-ui) or when the viewer is anonymous. Data lives in
+ * localStorage, keyed by gameId. No network calls. Quotas mirror the backend.
+ */
+export declare class LocalStorageTransport implements Transport {
+    readonly gameId: string;
+    readonly kind: "standalone";
+    readonly user: UmicatUser | null;
+    readonly locale: string;
+    readonly capabilities: readonly string[];
+    constructor(gameId: string);
+    call<T = unknown>(method: string, params?: unknown): Promise<T>;
+    private savesPrefix;
+    private gameDataPrefix;
+    private read;
+    private write;
+    private kvGet;
+    private kvSet;
+    private kvDelete;
+    private kvList;
+}

package/dist/core/transports/LocalStorageTransport.js

@@ -0,0 +1,83 @@
+import { RpcError } from '../Transport.js';
+/**
+ * Fallback transport when the game runs without a host (e.g., opened directly
+ * outside umicat-home-ui) or when the viewer is anonymous. Data lives in
+ * localStorage, keyed by gameId. No network calls. Quotas mirror the backend.
+ */
+export class LocalStorageTransport {
+    constructor(gameId) {
+        this.gameId = gameId;
+        this.kind = 'standalone';
+        this.user = null;
+        // No host to tell us the player's language — best-effort from the browser.
+        this.locale = (typeof navigator !== 'undefined' && navigator.language) ? navigator.language : 'en';
+        // Standalone advertises no host capabilities — voice etc. fall back to the
+        // browser's own APIs (or are unsupported).
+        this.capabilities = [];
+    }
+    async call(method, params) {
+        switch (method) {
+            case 'saves.get': return this.kvGet(this.savesPrefix(), params);
+            case 'saves.set': return this.kvSet(this.savesPrefix(), params);
+            case 'saves.delete': return this.kvDelete(this.savesPrefix(), params);
+            case 'saves.list': return this.kvList(this.savesPrefix());
+            case 'gameData.get': return this.kvGet(this.gameDataPrefix(), params);
+            case 'gameData.set': return this.kvSet(this.gameDataPrefix(), params);
+            case 'gameData.delete': return this.kvDelete(this.gameDataPrefix(), params);
+            case 'gameData.list': return this.kvList(this.gameDataPrefix());
+            default: throw new RpcError('UNKNOWN_METHOD', `Unknown method: ${method}`);
+        }
+    }
+    savesPrefix() { return `umicat:saves:${this.gameId}:`; }
+    gameDataPrefix() { return `umicat:gameData:${this.gameId}:`; }
+    read(prefix, key) {
+        if (typeof localStorage === 'undefined')
+            return null;
+        const raw = localStorage.getItem(prefix + key);
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    write(prefix, key, rec) {
+        if (typeof localStorage === 'undefined')
+            throw new RpcError('UNAVAILABLE', 'localStorage unavailable');
+        localStorage.setItem(prefix + key, JSON.stringify(rec));
+    }
+    kvGet(prefix, { key }) {
+        const rec = this.read(prefix, key);
+        return rec ? { value: rec.value, version: rec.version } : { value: null, version: null };
+    }
+    kvSet(prefix, { key, value, ifVersion }) {
+        const existing = this.read(prefix, key);
+        if (ifVersion !== undefined && existing && existing.version !== ifVersion) {
+            throw new RpcError('VERSION_MISMATCH', `Expected version ${ifVersion} but stored is ${existing.version}`);
+        }
+        const next = { value, version: (existing?.version ?? 0) + 1 };
+        this.write(prefix, key, next);
+        return { version: next.version };
+    }
+    kvDelete(prefix, { key }) {
+        if (typeof localStorage === 'undefined')
+            return { deleted: false };
+        const full = prefix + key;
+        const existed = localStorage.getItem(full) !== null;
+        localStorage.removeItem(full);
+        return { deleted: existed };
+    }
+    kvList(prefix) {
+        if (typeof localStorage === 'undefined')
+            return { keys: [] };
+        const keys = [];
+        for (let i = 0; i < localStorage.length; i++) {
+            const k = localStorage.key(i);
+            if (k && k.startsWith(prefix))
+                keys.push(k.slice(prefix.length));
+        }
+        return { keys };
+    }
+}