@umicat/phaser-sdk 1.0.0

package/SDK-GUIDE.md

@@ -0,0 +1,1726 @@
+# @umicat/phaser-sdk — Agent Guide
+
+Reference for AI agents building games on the Umicat platform. Tracks the **installed SDK version** — always matches the code in `node_modules/@umicat/phaser-sdk`. Read this before calling any platform API.
+
+## What the SDK provides
+
+- `createUmicatGame(options)` — Phaser.Game factory with platform defaults (screenshot + recording wired up)
+- `UmicatScene` — optional base scene with `createButton`, `shakeCamera`, `flashCamera` helpers
+- `Umicat.init()` — platform services entry point
+- `umicat.saves` — **per-user** key-value store (only the owner sees/writes their data)
+- `umicat.gameData` — **per-game** key-value store (read by anyone; write requires auth)
+- `umicat.rooms` — **multiplayer rooms** (server-authoritative state sync, requires sign-in and host support)
+
+## `createUmicatGame` options
+
+| field | type | note |
+|-------|------|------|
+| `orientation` | `'portrait' \| 'landscape'` | mutually exclusive with `width`/`height`. Resolves to preset dims from `ORIENTATION_DIMENSIONS`. **Since 0.2.16.** |
+| `width` | `number` | required if `orientation` is omitted |
+| `height` | `number` | required if `orientation` is omitted |
+| `scenes` | `Phaser.Scene class[]` | required |
+| `backgroundColor` | `string` | defaults to `'#1a1a2e'` |
+| `pixelArt` | `boolean` | defaults to `false` |
+| `physics` | `Phaser.Types.Core.PhysicsConfig` | defaults to arcade physics, no gravity |
+| `plugins` | `Phaser.Types.Core.PluginObject` | forwarded as-is into the Phaser `GameConfig`. **Since 0.2.9.** Earlier versions silently dropped this field. |
+
+`orientation` and explicit `width`/`height` are a TypeScript union — pass one or the other, not both. The compiler rejects mixed usage.
+
+Any field not listed is ignored. If you need something else (e.g. `callbacks`, custom `render` options), use plain `new Phaser.Game(config)` instead of `createUmicatGame`.
+
+### Orientation presets
+
+```ts
+import { ORIENTATION_DIMENSIONS } from '@umicat/phaser-sdk';
+// { landscape: { width: 1280, height: 720 }, portrait: { width: 720, height: 1280 } }
+```
+
+The orientation a game uses is decided **once at game creation** and baked into the template's `src/config.ts`. There is no runtime API to flip orientation — switching mid-development would invalidate every screen layout.
+
+### Registering third-party Phaser plugins (e.g. rexUI)
+
+Pass them via the `plugins` option — do NOT try to register them inside a scene's `preload`:
+
+```ts
+import VirtualJoystickPlugin from 'phaser3-rex-plugins/plugins/virtualjoystick-plugin.js';
+
+createUmicatGame({
+  // ...
+  plugins: {
+    global: [
+      { key: 'rexVirtualJoystick', plugin: VirtualJoystickPlugin, start: true },
+    ],
+  },
+});
+```
+
+Then in a scene: `this.plugins.get('rexVirtualJoystick').add(this, { ... })`.
+
+## Platform services
+
+Initialize once at module load — resolves the host (home-ui, standalone, etc.) and returns a bound instance. Scenes read from the resulting promise.
+
+```ts
+// src/main.ts
+import { Umicat } from '@umicat/phaser-sdk';
+
+export const umicatReady = Umicat.init({ standaloneGameId: 'my-game' })
+  .catch(() => null);
+```
+
+`umicatReady` resolves to an `Umicat` instance, or `null` if init failed. Scenes should be resilient to `null` — they must still run for anonymous players.
+
+### Identity
+
+```ts
+const umicat = await umicatReady;
+if (umicat) {
+  umicat.user;            // { id, name, avatar? } | null — null = anonymous
+  umicat.isAuthenticated; // boolean
+  umicat.gameId;          // stable platform-issued game id
+  umicat.host;            // 'umicat-home-ui' | 'standalone' | 'discord' (future)
+}
+```
+
+### Save data — `umicat.saves`
+
+Per-user key-value store scoped to `(gameId, userId)`. Backed by the Umicat backend when authenticated, by localStorage when standalone/anonymous — **the API is identical either way**. Games should never branch on auth state for save logic.
+
+```ts
+// Read — returns null if the key doesn't exist
+const highScore = await umicat.saves.get<number>('highScore');
+
+// Write — returns the new version number
+await umicat.saves.set('highScore', 12340);
+
+// Optimistic concurrency — write only if stored version matches
+try {
+  await umicat.saves.set('progress', { level: 3 }, { ifVersion: 7 });
+} catch (err) {
+  // RpcError with code 'VERSION_MISMATCH' — someone else wrote first
+}
+
+// List keys (no values — cheap)
+const keys = await umicat.saves.list();
+
+// Delete
+await umicat.saves.delete('progress');
+```
+
+**Type parameter on `.get<T>()`** is only for TypeScript convenience — the SDK does not validate. Treat returned data as untrusted and defend against missing/malformed values.
+
+### Quotas (enforced at backend)
+
+| Limit | Value |
+|---|---|
+| Per value | 100 KB |
+| Per `(game, user)` total | 1 MB |
+| Max keys per `(game, user)` | 64 |
+| Key format | `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` |
+
+Exceeding a quota throws `RpcError` with code `QUOTA_EXCEEDED`. Don't catch silently — surface a clear error.
+
+### When to use saves
+
+**Persist (by convention, no need to ask):**
+- High scores, personal bests
+- Level / stage / chapter progression
+- Unlockables (characters, skins, abilities)
+- In-game currency, inventories
+- Cosmetic selection (chosen character, color)
+- User-configurable settings (volume, difficulty preference, control scheme)
+- Tutorial-seen / onboarding-completed flags
+
+**Do not persist (transient state):**
+- Current-run position, velocity, HP
+- Active enemies, projectiles, particles
+- Scene camera position
+- Animation frames, timers, cooldowns
+- UI focus, current menu
+
+**Rule of thumb:** if the user would be annoyed to lose it on refresh, persist. If they'd be confused to see it come back (e.g. "why is there an enemy here from my last game?"), don't.
+
+### Suggested key names
+
+Use stable, descriptive key names so data carries across SDK versions:
+
+| Concept | Key |
+|---|---|
+| Highest score ever | `highScore` |
+| Current progression | `progress` |
+| Unlocked items | `unlocks` |
+| Player settings | `settings` |
+| Cosmetic selection | `cosmetics` |
+| Onboarding flag | `onboardedAt` |
+
+### Error handling patterns
+
+```ts
+// Graceful degradation — save failures must never block gameplay
+try {
+  await umicat.saves.set('highScore', score);
+} catch (err) {
+  console.warn('[game] failed to save highScore', err);
+  // continue — game still works, just without persistence this turn
+}
+```
+
+```ts
+// Load at scene start — handle missing, malformed, and failure cases
+const saved = await umicat.saves.get<number>('highScore').catch(() => null);
+this.highScore = typeof saved === 'number' ? saved : 0;
+```
+
+### Game data — `umicat.gameData`
+
+Same API shape as `saves`, but **game-scope**: one value per key, shared by all players of the game. Use it for things the whole playerbase sees — scoreboards, shared inventories, tournament state, level-of-the-day.
+
+```ts
+// Read — public. Works for anonymous visitors.
+type Entry = { name: string; score: number; at: number };
+const board = await umicat.gameData.get<Entry[]>('leaderboard') ?? [];
+
+// Write — requires an authenticated user. Throws RpcError('UNAUTHENTICATED') otherwise.
+// Safe append: read + modify + write with ifVersion to avoid clobbering
+// concurrent writers (two players finishing at the same time).
+const { value: current, version } = await umicat.gameData
+  .get<Entry[]>('leaderboard')
+  .then((v) => ({ value: v ?? [], version: null as number | null }))  // null means "not yet written"
+
+async function submitScore(name: string, score: number) {
+  if (!umicat.isAuthenticated) return;             // skip for anonymous
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const raw = await umicat.gameData.get<Entry[]>('leaderboard');
+    const list = Array.isArray(raw) ? raw : [];
+    const next = [...list, { name, score, at: Date.now() }]
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 100);                              // cap to top 100 so we don't blow the 100 KB limit
+    try {
+      await umicat.gameData.set('leaderboard', next);
+      return;                                      // success
+    } catch (err: any) {
+      if (err?.code !== 'VERSION_MISMATCH') throw err;
+      // another writer landed first — re-read and retry
+    }
+  }
+}
+```
+
+### Saves vs. gameData — which one?
+
+| Need | Use | Why |
+|---|---|---|
+| My personal high score | `saves` | Only I write it, only I read it. Anonymous-friendly (localStorage fallback). |
+| Progress through levels | `saves` | Per-user private state. |
+| Character / loadout choice | `saves` | Per-user. |
+| Scoreboard visible to everyone | `gameData` | Multiple users write; anyone reads. |
+| Today's puzzle / daily challenge | `gameData` | Single global value read by all players. |
+| Shared tournament bracket | `gameData` | Shared mutable state across players. |
+| Player name in a chat log | `gameData` | But consider size caps — chat is noisy. |
+| Current frame's enemy positions | *neither* — transient, don't persist | Wastes quota and confuses state after refresh. |
+
+Rule of thumb: if two different players would write to the same key, it's `gameData`. If a write from player A should never be visible to player B, it's `saves`.
+
+### Concurrency + size (gameData specifics)
+
+- **List writes race.** If two players append to `leaderboard` simultaneously, one overwrites the other's work. Use `ifVersion` for read-modify-write. On `VERSION_MISMATCH`, re-read and retry.
+- **Truncate.** A single key caps at 100 KB — roughly 500-1000 compact JSON entries. Keep lists bounded (top N, drop older), or shard across keys.
+- **Reads are cheap and public.** No auth needed — even logged-out players see `gameData`. Don't put anything secret here.
+- **Trust is thin.** The backend stores what you write, verbatim. A player with devtools could submit any JSON. For casual games this is fine; for competitive stakes, a future typed leaderboards API with server-side validation is the right fix.
+
+### Multiplayer rooms — `umicat.rooms`
+
+Realtime rooms backed by umicat-realtime-service. The platform is **game-agnostic** — the server tracks who's in the room and relays data, but does not know what kind of game you're building. Two opaque primitives are your building blocks:
+
+1. **Delta-synced KV state** (`room.player.*`, `room.data.*`) — server-maintained maps. Values are JSON-serializable. Every client sees changes via `onStateChange`. State is preserved while the room exists; new joiners see the current snapshot.
+2. **Transient message relay** (`room.send` + `room.on`) — fire-and-forget. Payloads are stamped with `from: senderSessionId` and broadcast to every other client in the room. Not persisted.
+
+#### Join a room
+
+```ts
+// Join or create a room scoped to this game. The SDK fetches a short-lived
+// token from the host and forwards it; the iframe never handles credentials.
+const room = await umicat.rooms.joinOrCreate('lobby', {
+  displayName: umicat.user?.name ?? 'guest',
+});
+
+room.id;         // room identifier
+room.sessionId;  // this connection's session id within the room
+room.state;      // proxy of the server-authoritative schema
+```
+
+**Room type is always `'lobby'`.** This is the only room type the realtime server registers — there is no `'blokus'` / `'chess'` / `'mygame'` type. Passing any other name results in "no handler" and throws. To distinguish rooms (private matches, per-code lobbies, etc.) use the `roomCode` option, documented below.
+
+#### Matchmaking — one game can have many rooms
+
+By default (no `roomCode`), every player of the same game lands in **one shared room**. Fine for a single hangout or a "public lobby" — but not for games where users need to open *private* rooms (e.g. "play this match with my friend" / "create a room with code ABC123 and share it").
+
+Use the `roomCode` option to bucket players. Two clients with the same `(gameId, roomCode)` join the same room; different codes create independent rooms.
+
+```ts
+// --- Create a private room with a fresh code ---
+const code = Math.random().toString(36).slice(2, 8).toUpperCase();  // e.g. 'AB3X7Y'
+const hostRoom = await umicat.rooms.joinOrCreate('lobby', {
+  roomCode: code,
+  maxClients: 4,                       // cap to 4 players (server clamps to [1, 16])
+  displayName: umicat.user?.name ?? 'host',
+});
+
+// Show `code` in the UI; the host shares it with friends manually.
+
+// --- Friend joins the same room with the shared code ---
+const guestRoom = await umicat.rooms.joinOrCreate('lobby', {
+  roomCode: 'AB3X7Y',                  // whatever the host shared
+  displayName: umicat.user?.name ?? 'guest',
+});
+```
+
+**`roomCode` caveats:**
+- Not a password. Anyone who knows the code can join. Use it for unguessable rather than *secret*.
+- Defaults to empty string when omitted. Two clients that both omit `roomCode` share the same "default" room — useful for a single global lobby per game.
+- Changing `roomCode` between joins does NOT transfer state; it's a different room. Leave the old room (`room.leave()`) before joining a new one.
+
+**`maxClients` caveats:**
+- Only honored by the client who CREATES the room (the first one in). Later joiners see the creator's choice.
+- Server clamps to `[1, 16]`. Passing `maxClients: 1000` silently becomes 16.
+- When full, `joinOrCreate` throws. Handle that in your UI (e.g. "Room is full. Ask your friend to create a smaller room or try a different code.").
+
+**Quick match / public room pattern.** If you want a "click Play, get matched with someone" flow, omit `roomCode` — everyone lands in the same default room. Players are differentiated by their `sessionId`. Add your own ready / waiting logic in `room.data`.
+
+```ts
+// Public quick match — no roomCode, everyone shares one room per game
+const room = await umicat.rooms.joinOrCreate('lobby', {
+  maxClients: 2,
+  displayName: umicat.user?.name ?? 'guest',
+});
+```
+
+#### Browsing open rooms — `umicat.rooms.list()`
+
+A room code is enough for "my friend and I agreed on code ABC123 out of band", but not for "show me a list of open games and let me click one to join." For that, ask the server what rooms are currently open for your game:
+
+```ts
+interface RoomListEntry {
+  roomId: string;          // opaque — pass to joinById
+  roomCode: string;        // the code the host passed (empty for default rooms)
+  clients: number;         // current occupants
+  maxClients: number;      // cap the host set (server-clamped to [1, 16])
+  metadata?: unknown;      // whatever the host set via room.setMetadata (optional)
+  createdAt?: number;      // ms since epoch
+}
+
+const rooms = await umicat.rooms.list();
+rooms
+  .filter(r => r.clients < r.maxClients)  // hide full rooms
+  .forEach(renderLobbyCard);
+
+// On click:
+async function joinRoom(entry: RoomListEntry) {
+  const room = await umicat.rooms.joinById(entry.roomId, {
+    displayName: umicat.user?.name ?? 'guest',
+  });
+  // room state is populated after the first onStateChange — see
+  // "Connection lifecycle" below for the state-timing rule.
+}
+```
+
+**Scope.** `list()` only returns rooms for the caller's game. A player can't see rooms from other games (the server cross-checks the gameId claim on the token).
+
+**Filter.** Pass `{ roomCode: 'ABC' }` to narrow to one code without paging through the whole list — useful for "is the room with code ABC up yet?" polling.
+
+**Polling, not subscription.** There is no push-on-change API today. Poll on a timer (e.g. every 3-5 s) while the lobby is open, and refresh on the user's explicit click. Cancel the timer when the player leaves the lobby.
+
+```ts
+// Simple lobby browser refresh loop
+let stop = false;
+async function refreshLoop() {
+  while (!stop) {
+    try {
+      const rooms = await umicat.rooms.list();
+      renderLobby(rooms);
+    } catch (e) {
+      // Network hiccup or REALTIME_UNAVAILABLE — surface in UI, keep looping.
+    }
+    await new Promise(r => setTimeout(r, 3000));
+  }
+}
+refreshLoop();
+scene.events.once('shutdown', () => { stop = true; });
+```
+
+**Unlisted rooms.** Every room created via `joinOrCreate` / `create` is currently listable by players of the same game. There is no "private room" flag yet — if you need that, tell your users to share the code out of band and don't render a lobby browser.
+
+#### Delta-synced state — `room.player` and `room.data`
+
+Use this for anything that represents the *current world*: positions, hp, score, turn state, scoreboard, etc. The server delta-syncs diffs to every client.
+
+```ts
+// Per-player (only you can write your own entry)
+room.player.set('pos', { x: 120, y: 340 });
+room.player.set('hp', 80);
+room.player.delete('pos');
+
+// Read another player's data at any time
+const otherPos = room.player.get<{x:number; y:number}>(otherSessionId, 'pos');
+
+// Per-room (any client can write)
+room.data.set('currentTurn', playerSessionId);
+room.data.set('scoreboard', [{ sid: 's1', score: 12 }, ...]);
+const board = room.data.get<Entry[]>('scoreboard') ?? [];
+
+// React to any state change
+const offState = room.onStateChange(() => {
+  room.state.players.forEach((p, sid) => {
+    const pos = room.player.get<{x:number;y:number}>(sid, 'pos');
+    // ... re-render
+  });
+});
+```
+
+Values are JSON-stringified under the hood. Use for anything JSON-serializable.
+
+#### Transient events — `room.send` and `room.on`
+
+Use this for ephemeral actions: fires, hits, emotes, explosions. Not persisted. (For **chat**, prefer the dedicated `room.chat` helper below — it adds local echo, length capping, and a stamped sender name on top of this same primitive.)
+
+```ts
+// Sender
+room.send('fire', { x: 100, y: 200, angle: 1.5 });
+
+// Every other client (sender does NOT receive their own)
+const offFire = room.on('fire', (msg: { from: string; x: number; y: number; angle: number }) => {
+  spawnProjectile(msg.x, msg.y, msg.angle);
+});
+```
+
+#### Chat — `room.chat.send` and `room.chat.onMessage`
+
+A thin wrapper over the transient relay tuned for in-game chat. Use this instead of raw `room.send('chat', text)` — you get four things you'd otherwise re-implement in every game:
+
+1. **Local echo** — the sender's own message hits the same `onMessage` handler stream the moment it's sent, so your UI has one render path for both your messages and remote ones.
+2. **Stamped sender info** — every `ChatMessage` carries `kind`, `from` (sessionId), `displayName` (sender's human-readable name at send time), `text`, and `ts`. No need to look up the sender in `room.state.players`.
+3. **Trim + length cap** — text is `.trim()`ed, dropped if empty, and silently truncated to `MAX_CHAT_TEXT_LEN` (500) so a stray paste can't flood the relay.
+4. **Auto-emitted system messages** — when a remote player joins or leaves, the SDK dispatches a `kind: 'system.joined'` / `'system.left'` message into the same stream. No wire traffic; computed locally on each client from `room.state.players`. Skipped for the local player's own join.
+
+```ts
+import { MAX_CHAT_TEXT_LEN } from '@umicat/phaser-sdk';
+import type { ChatMessage } from '@umicat/phaser-sdk';
+
+const log: ChatMessage[] = [];
+
+const offChat = room.chat.onMessage((msg) => {
+  log.push(msg);
+  if (msg.kind === 'user') {
+    const who = msg.from === room.sessionId ? 'You' : (msg.displayName || 'Player');
+    appendChatLine(`${formatTime(msg.ts)} ${who}: ${msg.text}`);
+  } else {
+    // 'system.joined' or 'system.left' — render however you like.
+    // msg.text is already a sensible English fallback ("Alice joined").
+    appendSystemLine(`${formatTime(msg.ts)} — ${msg.text}`);
+  }
+});
+
+inputEl.maxLength = MAX_CHAT_TEXT_LEN;       // mirror the cap on the input box
+inputEl.addEventListener('keydown', async (e) => {
+  if (e.key !== 'Enter') return;
+  try {
+    await room.chat.send(inputEl.value);     // trim + cap + local echo + wire send
+    inputEl.value = '';                      // safe: echo already dispatched synchronously
+  } catch (err) {
+    // Local-side dispatch failed (e.g. connection dropped). Show a UI hint.
+    showChatError(err);
+  }
+});
+
+scene.events.once('shutdown', offChat);
+```
+
+`ChatMessage` discriminates by `kind`:
+
+```ts
+type ChatMessageKind = 'user' | 'system.joined' | 'system.left';
+interface ChatMessage {
+  kind: ChatMessageKind;
+  from: string;          // sessionId of the sender (or join/leave subject)
+  displayName: string;   // their displayName at the time
+  text: string;          // user-typed text, or English system fallback
+  ts: number;            // Date.now() when emitted
+}
+```
+
+Notes:
+- **No history.** A player who joins mid-room sees no prior `'user'` messages. If you need scrollback, write to `room.data.set('chatLog', [...])` yourself — the relay is fire-and-forget.
+- **System messages are local-only.** Each client computes them from `room.state.players` add/remove events. They are NOT broadcast over the wire, and never echo from the wire even if a different client tries to send one.
+- **`send` returns `Promise<void>`.** Resolves once dispatch is complete (echo + wire queued); rejects if the underlying connection blew up. It is **not** an ack — the relay itself is fire-and-forget; the Promise only catches local-side errors.
+- **Order by arrival.** `ts` is `Date.now()`, advisory only. Skew between clients is small in practice but don't sort by `ts` across senders.
+- **Trust model.** `text` and `displayName` come from the sender — no server-side validation. Same as every other transient relay payload.
+
+#### Server-tracked membership
+
+`room.state.players` is server-owned. Each entry exposes:
+- `userId` — Umicat identity (from the JWT)
+- `displayName` — set by the joining client
+- `joinedAt` — ms timestamp
+- `data` — the MapSchema<string> the player writes to via `room.player.set`
+
+Games never mutate these directly; read them from `room.state.players`.
+
+#### Connection lifecycle
+
+```ts
+room.onLeave((code) => console.log('disconnected', code));
+room.onError((code, message) => console.warn('room error', code, message));
+
+// Clean up on scene shutdown
+offState();
+offFire();
+await room.leave();
+```
+
+#### Picking the right primitive
+
+| Need | Use | Why |
+|---|---|---|
+| Smooth position sync of a player | `room.player.set('pos', {x,y})` at ~10-20 Hz + `onStateChange` | Delta-compressed, survives reconnect, server is source of truth. |
+| Per-frame local movement feel | client-side prediction + interpolate remotes from state | State arrives at ~20 Hz; lerp toward it. |
+| Scoreboard shared by all | `room.data.set('scoreboard', [...])` | One writer wins on conflict; use optimistic patterns or turn-based writes. |
+| Projectile spawn / hit effect | `room.send('fire', {...})` + `room.on('fire', ...)` | Ephemeral, not needed on reconnect. |
+| Chat message | `room.chat.send(text)` + `room.chat.onMessage(...)` | Helper over the relay: local echo, stamped sender, length cap. |
+| Current turn in a turn-based game | `room.data.set('turn', sid)` | Authoritative shared state. |
+
+Rules of thumb:
+- **If someone joining mid-game should see it, it's state** (`room.player.*` or `room.data.*`).
+- **If it's a one-shot action, it's a message** (`room.send` / `room.on`).
+- **Do not implement position sync via messages.** You will reinvent delta compression badly and spend more bandwidth. Use `room.player.set('pos', {x,y})`.
+- **Server is authoritative but permissive** — it doesn't validate what you put in `data`. Treat inbound values from other players as untrusted (don't eval, validate shape before reading).
+
+#### Making remote motion feel smooth
+
+State updates arrive at roughly 20 Hz (every ~50 ms). If you re-render remote entities by snapping directly to `room.player.get(sid, 'pos')` each frame, their movement will visibly step. Pick a smoothing technique that fits the game:
+
+**Interpolation** — good for continuous motion (platformer, shooter, racer). Keep a `target` on each remote sprite, update it from state, lerp toward it each frame.
+
+```ts
+// On state change, just update the target
+room.onStateChange(() => {
+  room.state.players.forEach((_p, sid) => {
+    if (sid === room.sessionId) return;
+    const pos = room.player.get<{x:number;y:number}>(sid, 'pos');
+    if (pos) remoteSprites.get(sid)!.target = pos;
+  });
+});
+
+// In your scene's update() loop
+remoteSprites.forEach((s) => {
+  s.sprite.x = Phaser.Math.Linear(s.sprite.x, s.target.x, 0.2);
+  s.sprite.y = Phaser.Math.Linear(s.sprite.y, s.target.y, 0.2);
+});
+```
+
+Pair this with **client-side prediction for the LOCAL player**: render your own sprite from a locally-predicted position (updated by input every frame) so input feels instant, not gated on the round trip. Publish the predicted position to state at ~10–20 Hz with `room.player.set('pos', predicted)`. You rarely need to reconcile in casual games; trust the local prediction.
+
+**Extrapolation** — good for projectiles and other predictable trajectories. Send `{ x, y, vx, vy, t }` once on spawn, let each client simulate locally with `x += vx * dt`. Only re-sync on events that change the trajectory (hit, bounce, destroy). Uses far less bandwidth than per-frame position sync.
+
+**Snap** — the right choice for:
+- Infrequent updates: score, hp, current turn, chat messages, lobby ready flags.
+- Turn-based games: pieces jumping to their next square shouldn't glide.
+- Discrete grids: same reason.
+
+Don't blindly apply interpolation to everything. It's wrong for a chess piece and wasteful on a hp bar.
+
+#### Availability
+
+- Requires sign-in. Anonymous players get `RpcError('UNAUTHENTICATED')`.
+- Requires a host with multiplayer enabled. Standalone games (no host) get `RpcError('REALTIME_UNAVAILABLE')` — guard with `if (umicat.host === 'umicat-home-ui')` if your game can run both hosted and standalone.
+
+#### Available room types
+
+- `lobby` — the generic room described above. Use for any multiplayer gameplay.
+
+**Rules of the road**
+- The server is the source of truth. Never trust `send()` payloads coming from other clients — the server validates.
+- Room state is *ephemeral*. When the last player leaves, it disposes. Persist anything you want to keep via `saves` or `gameData`.
+- Keep messages small. State syncs are delta-compressed; raw `send()` payloads are not.
+- Unsubscribe on scene shutdown. `onStateChange`, `on`, `onLeave`, `onError` all return an unsubscribe function — call them from `scene.events.once('shutdown', ...)`.
+- One Colyseus client is kept internally; repeated `joinOrCreate` calls reuse it and mint fresh tokens each connection.
+
+## Scene-as-data (visual editor foundation, since 0.2.17)
+
+Games that ship with `public/scenes/manifest.json` load layout from JSON instead of hardcoding `this.add.sprite(x, y, ...)` in scene classes. This split is what lets the visual editor edit a game without touching code.
+
+**File layout:**
+```
+src/scenes/
+  BootScene.ts            — preloads manifest, draws loading bar, starts GameScene
+  GameScene.ts            — generic loader: await loadWorldScene(this, sceneId)
+public/scenes/
+  manifest.json           — scenes list + asset table + initial scene id
+  world/<scene>.json      — one world scene per file (entities, camera, world dims)
+```
+
+**Manifest shape:**
+```json
+{
+  "schemaVersion": 1,
+  "id": "my-game", "title": "My Game", "version": "1.0.0",
+  "initialScene": "main",
+  "scenes":  [{ "id": "main", "type": "world", "file": "world/main.json", "hud": null }],
+  "huds":    [],
+  "assets":  [
+    { "id": "knight", "textureKey": "knight", "path": "uploaded/knight.png", "kind": "image" },
+    { "id": "tiles",  "textureKey": "tiles",  "path": "uploaded/tiles.png",
+      "kind": "spritesheet",
+      "spriteSheetConfig": { "frameWidth": 16, "frameHeight": 16 } }
+  ]
+}
+```
+
+The `assets[]` table is the single source of truth for asset loading in scene-as-data games. Replaces hand-rolled `BootScene.preload()` lines: `loadWorldScene` queues the right `this.load.*` call based on each asset's `kind` and config (lazy — only assets the active scene uses).
+
+**Entity shape (world scenes — flat schema, SDK 0.3.0):**
+```json
+{
+  "id": "player",
+  "kind": "sprite",
+  "role": "player",
+  "transform": { "x": 200, "y": 400, "rotation": 0, "scaleX": 1, "scaleY": 1 },
+  "assetId": "knight",
+  "properties": { "maxHp": 3, "speed": 200 }
+}
+```
+
+`kind` is the entity discriminator with seven variants: `sprite` / `rect` / `circle` / `code-rendered` / `group` / `tilemap` / `trigger`. Per-kind render fields live at the entity root (no nested `visual` sub-object):
+
+- `sprite` → `assetId`, optional `frame` / `tint` / `alpha` / `flipX` / `flipY`
+- `rect` → `width`, `height`, optional `fillColor` / `strokeColor` / `strokeWidth` / `alpha`
+- `circle` → `radius`, optional `fillColor` / `strokeColor` / `strokeWidth` / `alpha`
+- `code-rendered` → `script` (path to render script), optional `params` / `width` / `height`
+- `tilemap` → `tileSize`, `size`, `layers[]`
+- `trigger` → `shape`, optional `description` / `targets` / `behaviorScript`
+- `group` → `children[]`
+
+**Optional physics body (since 0.2.54).** Any renderable entity (`sprite` / `rect` / `circle` / `code-rendered`) may carry a `physics` block — the same shape prefabs use (see the Prefabs section's `physics` field reference). When present, `loadWorldScene` gives the entity an Arcade body, sized and offset per the block, so behavior code doesn't call `physics.add.existing` / `body.setSize` for it. A code-rendered platform, for example, can declare `"physics": { "bodyW": 200, "bodyH": 32, "immovable": true }` and be collidable the moment the scene loads.
+
+**World gravity from scene data (since 0.2.55).** A world scene's `world.physics.gravity` (`{ x?, y? }`) — or, as a manifest-wide default, `manifest.globals.physics.gravity` — is applied to the scene's Arcade physics world by `loadWorldScene`. Scene-level wins over the manifest global. Example: a platformer's `world/main.json` carries `"world": { "width": 5120, "height": 720, "physics": { "gravity": { "x": 0, "y": 700 } } }` and the player just falls — no `this.physics.world.gravity` line in `GameScene.ts`. (Before 0.2.55 these two fields were typed but inert; only `game.json`'s `GameConfig.physics.gravity`, wired through `createUmicatGame` in `main.ts`, took effect.)
+
+**API:**
+```ts
+import { preloadManifest, getManifest, loadWorldScene, getEntityRegistry } from '@umicat/phaser-sdk';
+
+class BootScene extends Phaser.Scene {
+  preload() { preloadManifest(this); /* + draw loading bar */ }
+  create() {
+    const manifest = getManifest(this);
+    this.scene.start('GameScene', { sceneId: manifest.initialScene });
+  }
+}
+
+class GameScene extends Phaser.Scene {
+  private sceneId!: string;
+  private player!: Phaser.Physics.Arcade.Sprite;
+  init(data: { sceneId: string }) { this.sceneId = data.sceneId; }
+  async create() {
+    await loadWorldScene(this, this.sceneId);  // spawns entities, applies camera
+    const registry = getEntityRegistry(this)!;
+    this.player = registry.byRole('player')[0] as Phaser.Physics.Arcade.Sprite;
+    // ...wire physics + input on `this.player`...
+  }
+  update() {
+    // Safe: loadWorldScene suspends update() during its await, so any
+    // class field assigned after `await loadWorldScene(...)` is defined
+    // by the first time update() ticks. No `if (!this.player) return;`
+    // guard needed.
+    this.player.setVelocityX(0);
+  }
+}
+```
+
+**Async create() safety (since 0.2.46).** Phaser does not await `create()`'s returned promise — without help, `update()` starts ticking before `await loadWorldScene(...)` resolves, and any class field assigned after the await is still `undefined` on frame 1. `loadWorldScene` (and `loadHudScene`) suspends the scene's update/physics/tween processing for the duration of its await via the exported `suspendSceneUpdates(scene)` helper, then resumes — so the pattern above is safe by construction. If you have **additional** awaits in `create()` after `loadWorldScene` returns, wrap them yourself:
+
+```ts
+async create() {
+  await loadWorldScene(this, this.sceneId);
+  const release = suspendSceneUpdates(this);
+  try {
+    await loadSomethingElse();
+    this.player = ...; // assigned here
+  } finally {
+    release();
+  }
+}
+```
+
+**Behavior conventions:**
+- Layout (positions, asset references, world dims, camera bounds) lives in scene JSON.
+- Behavior (physics setup, input handlers, update loop, tweens) lives in `GameScene.ts`.
+- Look entities up by `role` (`registry.byRole('player')`) — portable across scenes. By id (`registry.byId('boss-1')`) when you need a specific one.
+- Don't hand-write `this.load.image(...)` lines for game assets — declare them in `manifest.assets[]`.
+- Don't call `this.add.sprite(...)` for game entities in code — declare them in scene JSON.
+
+The `scene-data-architecture` agent skill has the full guidance. The `scene-data-migration` skill walks an existing scene-as-code game through the conversion.
+
+**Edit mode (host-driven):** when the host (home-ui) sends `{ type: 'umicat:setEditMode', enabled: true }` via `postMessage`, the SDK pauses every active non-Boot Phaser scene — entities stay rendered but `update`/physics/tweens stop. Sending `enabled: false` resumes. Used by the visual editor's read-only viewer in slice 1.
+
+## Prefabs — entity types for runtime spawning (slice 11 Phase B.1, since 0.2.47)
+
+Scene entities (above) cover *authored instances at design-time positions* — the player, a fixed boss, level decorations. They're the right pattern for layout-heavy games (top-down RPG, platformer, puzzle) where the user drags entities in the editor.
+
+For **runtime-spawned types** — Galaga enemies in a wave, bullets, drops, particle effects — declare them as **prefabs** in `manifest.prefabs[]` instead. A prefab is a self-contained TYPE record: visual + physics + properties. Code spawns instances via `spawnPrefab(scene, prefabId, x, y)`. The visual editor surfaces prefabs in a separate Hierarchy tab so the user can tweak HP / speed / color / hitbox without touching code — the editor's value extends to genres where layout editing isn't useful.
+
+### Manifest reference
+
+```json
+{
+  "schemaVersion": 1,
+  "scenes": [...],
+  "huds": [...],
+  "assets": [...],
+  "prefabs": [
+    {
+      "id": "enemy_grunt",
+      "kind": "code-rendered",
+      "role": "enemy",
+      "script": "src/visuals/enemy-grunt.ts",
+      "width": 40,
+      "height": 32,
+      "params": { "bodyColor": "#cc3344", "eyeColor": "#ffff66" },
+      "physics": {
+        "bodyW": 28,
+        "bodyH": 22,
+        "offsetX": 6,
+        "offsetY": 5,
+        "collideWorldBounds": false
+      },
+      "properties": {
+        "hp": 3,
+        "fireIntervalMs": 1800,
+        "scoreValue": 100
+      }
+    },
+    {
+      "id": "player_bullet",
+      "kind": "code-rendered",
+      "role": "bullet",
+      "script": "src/visuals/player-bullet.ts",
+      "width": 4,
+      "height": 14,
+      "physics": { "velocityY": -700 },
+      "properties": { "damage": 1 }
+    }
+  ]
+}
+```
+
+Prefabs use the same flat schema as scene entities (SDK 0.3.0). The four prefab kinds — `sprite` / `rect` / `circle` / `code-rendered` — each carry their render fields at the prefab root (no nested `visual` sub-object). The `physics` block carries the body sizing the SDK applies after `physics.add.existing`, so behavior code doesn't have to call `body.setSize` / `setOffset` manually. Since 0.2.54 the **same `physics` block also works on authored scene entities** (see the scene-as-data section) — prefabs and scene entities share one body-level path.
+
+**Field reference for `physics`:**
+- `bodyW` / `bodyH` — body dimensions. Default: the visual's drawn extent (sprite texture size, rect/circle dims, or code-rendered `width` / `height` — 64 if unset).
+- `offsetX` / `offsetY` — body offset, measured from the visual's top-left. Default: centers the body inside the visual. (For `code-rendered` entities the SDK shifts the body frame so the offset is measured from the top-left the same way it is for sprites/rect/circle — a Phaser `Graphics` has no Origin component, so the body math needs the shift. Fixed in 0.2.54; before that, code-rendered bodies landed at the bottom-right of the visual.)
+- `immovable`, `velocityX`, `velocityY`, `collideWorldBounds`, `bounceX`, `bounceY` — passed through to the Arcade body.
+
+### Code use
+
+```ts
+import { spawnPrefab } from '@umicat/phaser-sdk';
+
+// In GameScene.create() — replaces `this.physics.add.image(x, y, 'tex')`
+class GameScene extends Phaser.Scene {
+  async create() {
+    await loadWorldScene(this, this.sceneId);
+
+    // Spawn a 3×6 grid of enemies. Each is a registered EntityRegistry
+    // instance; behavior code can find them all via `registry.byRole('enemy')`.
+    for (let row = 0; row < 3; row++) {
+      for (let col = 0; col < 6; col++) {
+        const enemy = spawnPrefab(this, 'enemy_grunt', col * 90 + 90, row * 72 + 100);
+        this.enemies.add(enemy);
+      }
+    }
+
+    // Per-instance overrides for a unique boss.
+    // `fields` carries flat render-field overrides (assetId / params /
+    // fillColor / etc.), deep-merged onto the prefab record.
+    const boss = spawnPrefab(this, 'enemy_grunt', 360, 200, {
+      properties: { hp: 30, scoreValue: 5000 },
+      fields: { params: { bodyColor: '#ff0066' } },
+    });
+    this.enemies.add(boss);
+  }
+
+  fireBullet(x: number, y: number) {
+    const bullet = spawnPrefab(this, 'player_bullet', x, y);
+    this.playerBullets.add(bullet);
+  }
+}
+```
+
+### API
+
+| Function | Purpose |
+|---|---|
+| `spawnPrefab(scene, prefabId, x, y, overrides?, options?)` | Create + register a runtime instance. Returns the GameObject. |
+| `getPrefab(scene, prefabId)` | Read a prefab record from the manifest. Throws if missing. |
+| `listPrefabs(scene, role?)` | Enumerate prefabs, optionally filtered by role. |
+| `registry.byPrefabId(prefabId)` | List every live instance of a prefab. Used by editor live-edit + game-level operations ("kill all enemies"). |
+
+`SpawnPrefabOverrides` is a deep-partial of the prefab record:
+
+```ts
+interface SpawnPrefabOverrides {
+  role?: string;
+  visual?: DeepPartial<WorldVisual>;
+  physics?: DeepPartial<PrefabPhysics>;
+  properties?: Record<string, unknown>;
+  transform?: Partial<Omit<Transform, 'x' | 'y'>>;  // rotation, scale, depth
+}
+```
+
+Each spawn gets a runtime-generated id of the form `<prefabId>#<n>` starting at 1. Use it (`go.getData('entityId')`) to disambiguate instances of the same prefab. The instance auto-unregisters on `destroy()` so dead enemies don't bloat the registry.
+
+### When prefab vs scene entity
+
+| Scenario | Use |
+|---|---|
+| The thing is unique and stays at a fixed position the user might drag | scene entity in `world/*.json` |
+| The thing is one of many at runtime-decided positions (waves, drops, projectiles) | prefab + `spawnPrefab` |
+| The thing has a type the user might want to tweak (HP, speed, color, hitbox) without code | prefab |
+| The thing is purely procedural — a transient particle effect, a debug overlay | inline code (`this.add.sprite`), no registry needed |
+
+When in doubt: **anything you'd `this.physics.add.sprite` more than twice for the same type is a prefab.**
+
+### Anti-patterns
+
+- ❌ Putting a prefab's per-spawn position in the prefab record. Position comes from `spawnPrefab(x, y)`; the prefab is *type-level*.
+- ❌ Calling `body.setSize` / `setOffset` after `spawnPrefab`. The SDK applied them from the prefab's `physics` block. Re-applying breaks the editor's live-edit flow.
+- ❌ Hardcoding tunable values (HP, fire rate, score) at the spawn site as overrides. They belong in the prefab record so the editor can edit them; overrides are for per-instance variation (a boss with 10× HP).
+
+The `phaser-prefab-spawning` agent skill (Phase B.1) has the full guidance including a Galaga conversion walkthrough.
+
+## Game config — top-level settings as data (slice 11 Phase B.3, since 0.2.50)
+
+`public/game.json` is a small JSON file carrying the **canvas + physics defaults + controls hints** that today live as TS `const` exports in `src/config.ts`. Once extracted to data the visual editor's eventual "Game settings" panel (Phase B.5) lets the user tweak canvas size / orientation / gravity / controls without code edits.
+
+### File reference
+
+`public/game.json`:
+
+```json
+{
+  "orientation": "portrait",
+  "pixelArt": true,
+  "physics": {
+    "gravity": { "x": 0, "y": 980 }
+  },
+  "controls": {
+    "primary": "wasd",
+    "fire": "space"
+  }
+}
+```
+
+All fields are optional. Use `orientation` *or* `width`+`height`, not both. `controls` is a hint table — the SDK doesn't bind keys from it; behavior code reads what it needs.
+
+### Code use
+
+```ts
+// main.ts — requires top-level await (Vite default target supports it)
+import { createUmicatGame, loadGameConfig } from '@umicat/phaser-sdk';
+import { BootScene } from './scenes/BootScene';
+import { GameScene } from './scenes/GameScene';
+
+const cfg = await loadGameConfig();
+createUmicatGame({
+  orientation: cfg?.orientation ?? 'portrait',
+  pixelArt: cfg?.pixelArt ?? false,
+  physics: cfg?.physics ? { default: 'arcade', arcade: { gravity: cfg.physics.gravity, debug: cfg.physics.debug } } : undefined,
+  scenes: [BootScene, GameScene],
+});
+```
+
+`loadGameConfig` resolves to `null` on missing file — callers fall back to in-code defaults so games without `public/game.json` keep working.
+
+### API
+
+| Function | Purpose |
+|---|---|
+| `loadGameConfig(path?)` | Async fetch of `public/game.json` (or custom path). Returns `GameConfig | null`. |
+
+### When game.json vs rules.json
+
+| Value | Goes in |
+|---|---|
+| Canvas dimensions, orientation, `pixelArt` flag | `game.json` |
+| Default Arcade gravity at game level | `game.json` |
+| Tunable game balance (lives, fire cooldown, win threshold) | `rules.json` |
+| Per-entity-type properties (enemy HP, drop chance) | `prefab.properties` |
+
+`game.json` is for **boot-time settings** read once when constructing Phaser. `rules.json` is for **gameplay tunables** read by behavior code with fallbacks and reactive subscriptions.
+
+## Rules — tunable game parameters as data (slice 11 Phase B.2, since 0.2.48)
+
+`public/rules.json` is a free-form key-value tree where any value the user might want to tune lives — lives count, score thresholds, fire cooldowns, gravity, win conditions, controls. Replaces TS `const X = ...` declarations for these values. Behavior code reads via dot-notation paths; the visual editor's Rules mode (when it lands) lets the user tweak any field in a form.
+
+### File reference
+
+`public/rules.json`:
+
+```json
+{
+  "balance": {
+    "lives": 3,
+    "shootCooldownMs": 210,
+    "playerSpeed": 340,
+    "scoreThresholds": [1000, 2500, 5000, 10000]
+  },
+  "physics": {
+    "gravity": { "x": 0, "y": 980 }
+  },
+  "controls": {
+    "primary": "wasd",
+    "fire": "space"
+  },
+  "winCondition": {
+    "type": "score",
+    "target": 50000
+  }
+}
+```
+
+No required shape — group however makes sense (`balance`, `physics`, `controls`, `difficulty`, …). Optional `_meta_<key>` siblings carry editor-form hints (label, min, max, step, enum options); the editor's form-renderer uses them when present.
+
+### Code use
+
+```ts
+import { preloadRules, getRule, onRuleChange } from '@umicat/phaser-sdk';
+
+class BootScene extends Phaser.Scene {
+  preload() {
+    preloadManifest(this);
+    preloadRules(this);  // tolerant of missing file
+  }
+}
+
+class GameScene extends Phaser.Scene {
+  async create() {
+    await loadWorldScene(this, this.sceneId);
+
+    // One-time reads
+    this.lives = getRule(this, 'balance.lives', 3);
+    this.shootCooldown = getRule(this, 'balance.shootCooldownMs', 200);
+
+    // Reactive: react to live editor edits (e.g. user lowers shootCooldownMs
+    // while playing → next shot uses the new value)
+    const unsub = onRuleChange(this, 'balance.shootCooldownMs', (v) => {
+      this.shootCooldown = v as number;
+    });
+    this.events.once(Phaser.Scenes.Events.SHUTDOWN, unsub);
+  }
+}
+```
+
+### API
+
+| Function | Purpose |
+|---|---|
+| `preloadRules(scene)` | Queue load of `public/rules.json` in BootScene preload. Missing file is fine. |
+| `getRule(scene, path, fallback)` | Read a value by dot-path. Returns fallback when unset. |
+| `getRules(scene)` | Read the full tree (rare; usually for debug HUDs). |
+| `onRuleChange(scene, path, handler)` | Subscribe to live edits. Fires on the exact path AND any descendant. Returns an unsubscribe function. |
+| `patchRule(scene, path, value)` | Internal — called by `EditorBridge` on `umicat:editor:patchRule`. Direct use from game code is unusual. |
+
+### When rule vs prefab.properties
+
+| Scenario | Use |
+|---|---|
+| Value is per-instance of an entity type (this enemy's HP, that drop's chance) | `prefab.properties` |
+| Value is global to the game (starting lives, fire cooldown, gravity, win threshold) | `rules.<group>.<key>` |
+| Value is computed from gameplay state (current score, time elapsed) | code variable, not data |
+
+A rule of thumb: if changing the value affects ONE entity type, it's a prefab property. If it affects the whole game or many entity types, it's a rule.
+
+### Anti-patterns
+
+- ❌ **Putting algorithmic constants in rules** (e.g. `"physics.bulletSpeedFalloff": 0.7321`). Implementation detail. Stay in code.
+- ❌ **Putting per-instance prefab properties in rules** (e.g. `rules.enemy.grunt.hp`). Belongs in the prefab's `properties.hp`.
+- ❌ **Re-reading the same rule in a hot loop without subscribing.** `getRule` is cheap but not free. Cache the value in a class field; subscribe to changes if needed.
+- ❌ **Deep paths used in `getRule` and `onRuleChange` that don't match the data shape.** No schema validation — fallbacks fire silently. Test by reading the rule once at scene start with a sentinel fallback (e.g. `getRule(this, 'balance.lives', -1)`); if you ever read `-1`, the path is wrong.
+
+The `game-rules-extraction` agent skill teaches the agent to push tunables into `rules.json` automatically.
+
+## Waves — spawn schedules as data (slice 11 Phase B.4, since 0.2.49)
+
+A **wave schedule** is a time-ordered sequence of spawn instructions in `public/waves/<id>.json` that references prefab ids. Models Galaga formations, infinite-runner difficulty curves, survivor-game wave timing — anything where the game spawns entities by a script.
+
+The SDK provides `runWaveSchedule(scene, id, callbacks)` that drives the script and fires callbacks at each beat. Replaces hand-rolled wave loops (`time + interval` math, manual TimerEvent management, custom end conditions) in `GameScene.ts`.
+
+### File reference
+
+`public/waves/stage-1.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "stage-1",
+  "name": "Stage 1",
+  "waves": [
+    {
+      "id": "wave-1",
+      "spawns": [
+        {
+          "kind": "formation",
+          "prefabId": "enemy_grunt",
+          "formation": { "shape": "grid", "rows": 3, "cols": 6, "spacing": { "x": 90, "y": 72 }, "origin": { "x": 90, "y": 120 } },
+          "startMs": 0,
+          "intervalMs": 100
+        }
+      ],
+      "endCondition": "allDead"
+    },
+    {
+      "id": "wave-2",
+      "delayMs": 1500,
+      "spawns": [
+        {
+          "kind": "formation",
+          "prefabId": "enemy_bomber",
+          "formation": { "shape": "v-shape", "cols": 5, "spacing": { "x": 60, "y": 40 }, "origin": { "x": 360, "y": 100 } },
+          "startMs": 0,
+          "intervalMs": 180
+        }
+      ],
+      "endCondition": "allDead"
+    },
+    {
+      "id": "boss",
+      "delayMs": 2500,
+      "spawns": [
+        { "kind": "point", "prefabId": "enemy_boss", "x": 360, "y": 200, "atMs": 0 }
+      ],
+      "endCondition": "allDead"
+    }
+  ]
+}
+```
+
+**Spawn instruction kinds (v1):**
+- `point` — single spawn at `{ x, y }` at `atMs` (relative to wave start).
+- `formation` — multiple spawns expanded from a `FormationRecord` (`shape: 'grid' | 'line' | 'v-shape' | 'arc'`), each at `startMs + i * intervalMs`.
+
+**Wave end conditions:**
+- `"allDead"` (default) — wait until every spawned instance from this wave has destroyed.
+- `{ "type": "time", "ms": N }` — fixed duration from wave start.
+- `{ "type": "count", "killed": N }` — wait until N instances destroyed.
+
+`loop: true` at the top of the schedule restarts wave 0 after the last one ends — for endless modes.
+
+### Code use
+
+```ts
+import { runWaveSchedule, spawnPrefab } from '@umicat/phaser-sdk';
+
+class GameScene extends Phaser.Scene {
+  async create() {
+    await loadWorldScene(this, this.sceneId);
+    this.enemies = this.physics.add.group();
+    // ... wire colliders ...
+
+    runWaveSchedule(this, 'stage-1', {
+      onSpawn: ({ prefabId, x, y, overrides }) => {
+        const go = spawnPrefab(this, prefabId, x, y, overrides as Record<string, unknown>);
+        this.enemies.add(go);
+        return go;  // returned so the controller can track allDead
+      },
+      onWaveStart: (i, wave) => {
+        this.events.emit('hudWave', i + 1);
+      },
+      onWaveEnd: (i) => {
+        // play a "wave cleared" SFX, brief tween
+      },
+      onScheduleEnd: () => {
+        this.scene.start('VictoryScene');
+      }
+    });
+  }
+}
+```
+
+### API
+
+| Function / type | Purpose |
+|---|---|
+| `loadWaveSchedule(scene, id)` | Async fetch via Phaser loader. Cached. Resolves to `WaveScheduleRecord`. |
+| `runWaveSchedule(scene, id, callbacks)` | Start a schedule. Returns a `WaveController` immediately; loads + starts asynchronously. |
+| `WaveController.pause()` / `.resume()` | Suspend / resume timers (e.g. pause menu). |
+| `WaveController.skipTo(index)` | Jump to a wave (debug / cheat). |
+| `WaveController.stop()` | Halt the schedule + fire `onScheduleEnd`. |
+| `WaveController.currentWaveIndex()` / `.isComplete()` | Status queries. |
+
+**Always return the GameObject from `onSpawn`** when using `endCondition: 'allDead'` or `{ type: 'count' }` — the controller tracks `Phaser.GameObjects.Events.DESTROY` events on returned instances. Returning `void` short-circuits lifecycle tracking (acceptable for `{ type: 'time' }` end conditions where the schedule advances by clock, not kills).
+
+### When wave vs spawn-loop-in-code
+
+| Scenario | Use |
+|---|---|
+| Time-ordered formations, staged waves, boss-on-wave-N | `waves/*.json` + `runWaveSchedule` |
+| Conditional spawns ("spawn wave 4 only if player has ≥ 5000 score") | Code, with `WaveController.skipTo` for advancing |
+| Spawn-on-trigger (enemy spawns when player enters a region) | Code calling `spawnPrefab` directly — not a wave |
+| Single boss with no minions | A single-wave schedule, OR a direct `spawnPrefab` if no formation |
+| Procedural generation (rogue-like room population) | Code reads `prefabs[]` + an RNG; not a wave schedule |
+
+### Anti-patterns
+
+- ❌ **Manual `time + interval` loops with `scene.time.addEvent` for wave timing.** That's exactly what `runWaveSchedule` automates.
+- ❌ **Per-spawn hardcoded `(x, y)` in code when the agent could use a `formation: { shape: 'grid' }`** — the latter is editable in the waves timeline editor (Phase B.5).
+- ❌ **Spawning via `this.physics.add.sprite(...)` from inside `onSpawn`.** Use `spawnPrefab` so the entity goes through the prefab pipeline (physics, properties, registry tagging).
+- ❌ **Not returning the GameObject from `onSpawn`** when `endCondition: 'allDead'`. The wave never advances.
+
+The `phaser-wave-schedule` agent skill teaches the wave authoring pattern with worked examples (Galaga, runner difficulty curve).
+
+## HUD scenes (visual editor slice 5+, since 0.2.29)
+
+A HUD scene is a separate `Phaser.Scene` that runs in parallel with the active world scene and renders anchor-positioned UI on top of it. The visual editor's `HUD` mode edits these. Five widget kinds ship today: **text**, **image**, **icon-button**, **progress-bar**, **panel**.
+
+### Manifest reference
+
+```json
+{
+  "scenes": [
+    { "id": "main", "type": "world", "file": "world/main.json", "hud": "game-hud" }
+  ],
+  "huds": [
+    { "id": "game-hud", "file": "hud/game-hud.json" }
+  ]
+}
+```
+
+When `loadWorldScene(this, sceneId)` runs, it auto-launches the `UmicatHudScene` with the matching `hudId`. You don't call `loadHudScene` yourself — `loadWorldScene` does it for you. Multiple world scenes can reference the same HUD; editing `game-hud` updates every scene that points at it.
+
+### Scene file shape
+
+`public/scenes/hud/game-hud.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "game-hud",
+  "name": "Game HUD",
+  "type": "hud",
+  "design": {
+    "designAspectRatio": "16:9",
+    "safeArea": { "top": 16, "right": 16, "bottom": 16, "left": 16 }
+  },
+  "entities": [ /* HudEntity[] */ ]
+}
+```
+
+### Anchor + offset positioning (no transform)
+
+HUD entities use a **9-grid anchor + numeric offset** instead of world coords:
+
+```json
+{
+  "id": "score-text",
+  "kind": "text",
+  "anchor": { "side": "top-left", "offsetX": 16, "offsetY": 16 },
+  "layer": "base",
+  "source": { "mode": "static", "text": "Score: 0" }
+}
+```
+
+HUD entities use the same flat schema as world entities (SDK 0.3.0) — per-kind fields (`source` / `assetId` / `label` / `value` / etc.) live at the entity root, alongside `id` / `kind` / `anchor` / `layer` / `z`.
+
+`side` is one of `top-left | top | top-right | left | center | right | bottom-left | bottom | bottom-right`. The widget is anchored to that corner/edge of the canvas, then offset inward (or outward) by `offsetX/Y`. Resizing the canvas (orientation change, device rotation) re-resolves anchors automatically.
+
+`layer` is one of `base | overlay | modal` (default `base`) — controls render z-order; `modal` sits on top of `overlay` sits on top of `base`. `z` adds further ordering within a layer.
+
+### Widget reference
+
+#### `text`
+
+```json
+{
+  "kind": "text",
+  "anchor": { "side": "top-left", "offsetX": 16, "offsetY": 16 },
+  "source": { "mode": "static", "text": "Hello" },
+  "fontSize": 24, "color": "#ffffff", "align": "left"
+}
+```
+
+`source` is either `{ mode: "static", text }` for a literal string OR `{ mode: "dynamic", binding, prefix?, suffix?, fallback? }` for a value read live from Phaser's game registry (see "Dynamic bindings" below).
+
+#### `image`
+
+```json
+{
+  "kind": "image",
+  "anchor": { "side": "top-right", "offsetX": -16, "offsetY": 16 },
+  "assetId": "coin-icon",
+  "width": 32, "height": 32
+}
+```
+
+`assetId` resolves through `manifest.assets` exactly like world sprite entities. Optional `tint`, `alpha`, `frame` (atlas frame name or sprite-sheet index).
+
+#### `icon-button`
+
+```json
+{
+  "kind": "icon-button",
+  "anchor": { "side": "bottom-right", "offsetX": -32, "offsetY": -32 },
+  "layer": "overlay",
+  "label": "Pause",
+  "shape": "rounded-rect",
+  "width": 96, "height": 48,
+  "fillColor": "#3b82f6", "textColor": "#ffffff"
+}
+```
+
+Click handler is decoupled — the SDK emits a Phaser scene event `'hud:press'` with the entity id when the button is pressed. Subscribe in your gameplay code:
+
+```ts
+// In GameScene.ts (or any active scene)
+this.events.on('hud:press', (id: string) => {
+  if (id === 'pause-button') { this.scene.pause(); /* etc. */ }
+});
+```
+
+For now there's no built-in action binding (no `behavior: { type: 'pause-game' }` etc.) — you wire each button by its id explicitly. That's coming in a later slice.
+
+#### `progress-bar`
+
+```json
+{
+  "kind": "progress-bar",
+  "anchor": { "side": "top-left", "offsetX": 16, "offsetY": 50 },
+  "value": { "mode": "dynamic", "binding": "playerHp", "fallback": 0 },
+  "max":   { "mode": "dynamic", "binding": "playerMaxHp", "fallback": 100 },
+  "width": 200, "height": 16,
+  "fillColor": "#22c55e", "backgroundColor": "#0f172a",
+  "borderRadius": 4, "borderColor": "#ffffff", "borderWidth": 1
+}
+```
+
+`value` and `max` are independently bindable — either can be static (`{ mode: 'static', value: 100 }`) or dynamic. Bar fills from 0 → 1 as `value / max`. Subscribes to `changedata-<binding>` registry events and redraws on change.
+
+#### `panel`
+
+```json
+{
+  "kind": "panel",
+  "anchor": { "side": "center" },
+  "width": 320, "height": 200,
+  "backgroundColor": "#000000", "backgroundAlpha": 0.5,
+  "borderColor": "#ffffff", "borderWidth": 1, "borderRadius": 8
+}
+```
+
+A colored rectangle with optional border + rounded corners. Use as a visual frame behind groups of HUD widgets (no children layout in v1 — child widgets are sibling entities; you align them with anchor + offset).
+
+### Textured backgrounds for `icon-button` and `panel` (since 0.2.37)
+
+Both `icon-button` and `panel` accept an asset image as the background instead of the default colored fill. Three flavors, each stretchable with crisp corners via the SDK's built-in 9-slice renderer:
+
+**1. Single-image 9-slice** (since 0.2.37) — manifest asset is `kind: 'image'` with `ninePatch: { leftWidth, rightWidth, topHeight, bottomHeight }`. The whole texture slices into 9 regions; corners stay native, edges + middle stretch.
+
+```json
+{
+  "kind": "icon-button",
+  "label": "Start",
+  "width": 240, "height": 64,
+  "backgroundAssetId": "button-panel"
+}
+```
+
+**2. Per-frame on a uniform grid** (since 0.2.38) — manifest asset is `kind: 'spritesheet'` with `ninePatch: { perFrame: {...} }`. Used when every cell of a button-pack sheet is the same size and shares the same corner radius (typical itch.io packs). Pair with `backgroundFrame: <cell index>` to pick which cell.
+
+```json
+{
+  "kind": "icon-button",
+  "backgroundAssetId": "button-pack",
+  "backgroundFrame": 3
+}
+```
+
+**3. Region atlas** (since 0.2.42) — manifest asset is `kind: 'atlas'` + `atlasFormat: 'json'` + `atlasPath: '...'`. The atlas JSON file carries named frame rects, each optionally with its own inline `ninePatch`. Pair with `backgroundRegion: '<frame name>'` to pick the region. Mutually exclusive with `backgroundFrame` — when both are set, `backgroundRegion` wins.
+
+```json
+{
+  "kind": "icon-button",
+  "backgroundAssetId": "ui-buttons",
+  "backgroundRegion": "btn-primary-idle"
+}
+```
+
+Atlas JSON shape — Phaser-native JSON-Hash with an optional per-frame `ninePatch` field that Phaser's parser ignores but the SDK reads via a side-cache:
+
+```json
+{
+  "frames": {
+    "btn-primary-idle": {
+      "frame":      { "x": 7, "y": 9, "w": 18, "h": 30 },
+      "sourceSize": { "w": 18, "h": 30 },
+      "ninePatch":  { "leftWidth": 4, "rightWidth": 4, "topHeight": 4, "bottomHeight": 4 }
+    },
+    "btn-primary-pressed": {
+      "frame":      { "x": 39, "y": 9, "w": 18, "h": 30 },
+      "sourceSize": { "w": 18, "h": 30 }
+    }
+  },
+  "meta": { "image": "ui-buttons.png", "size": { "w": 128, "h": 96 }, "scale": "1" }
+}
+```
+
+The Region Editor in the home-ui (visual editor slice 10) writes this shape for you — drag-tag named regions on a single PNG, optionally toggle 9-slice per region, save. Regions without `ninePatch` render as plain stretched images of that region; regions with `ninePatch` render via the 9-slice path.
+
+### Dynamic bindings — driving the HUD from gameplay
+
+For values that change during play (score, HP, timer, lives), use **Phaser's game registry** as the bridge. The HUD widget references a `binding` key; gameplay code calls `this.registry.set(key, value)` and the HUD auto-refreshes.
+
+```ts
+// In GameScene.ts create():
+this.registry.set('score', 0);
+this.registry.set('playerHp', 100);
+this.registry.set('playerMaxHp', 100);
+
+// Wherever score changes:
+this.registry.set('score', this.score + 10);
+```
+
+The HUD widget's text / progress fill updates synchronously on the next frame — no manual `setText` / re-render call needed. Registry is `game.registry` under the hood, shared across all scenes.
+
+**Pick stable, lowercase keys**: `score`, `coins`, `playerHp`, `lives`, `currentLevel`, `xp`. The binding key goes into a `changedata-<key>` event name; spaces or special characters break it.
+
+**No declare ceremony**: just `set` the key. The HUD picks it up. The `umicat.gameData` module is for *persistent* shared values (across sessions); for in-game reactive HUD, registry is the right tool.
+
+### Editor mode (for visual-editor users only)
+
+The visual editor's `World/HUD` toggle pauses the active world scene and lets the user drag widgets / edit anchor + offset / live-tune visual fields. Edits flow back to `public/scenes/hud/<id>.json` on save (Cmd+S / Edit→Play / Publish). Auto-save during editing only persists JSON to disk — no rebuild — so the iframe doesn't reload mid-edit.
+
+For game code, the editor is invisible — you write HUD scene JSON the same way regardless of whether the user uses the editor.
+
+## Collision + Y-sort (visual editor slice 8, since 0.2.44)
+
+Two new fields on `AssetRecord` give per-asset collision shapes and footprint
+anchors for top-down draw-order sorting. The SDK consumes them automatically
+at sprite spawn time. `applyAssetHitbox` is also exported for behavior code
+that attaches a physics body after spawn.
+
+### `Asset.hitbox` — collision body shape
+
+Per-asset rect (in v1) in source-pixel coordinates relative to the
+asset's frame top-left. Two shapes:
+
+```ts
+// Single — one body across all frames (trees, walls, idle characters)
+hitbox: { kind: 'rect', x: 8, y: 24, w: 16, h: 8 }
+
+// Per-frame — combat sheets where attack frames need a wider hitbox
+hitbox: {
+  default: { kind: 'rect', x: 8, y: 24, w: 16, h: 8 },
+  frames: {
+    8:  { kind: 'rect', x: 0, y: 16, w: 32, h: 16 },
+    9:  { kind: 'rect', x: 0, y: 16, w: 32, h: 16 },
+    10: { kind: 'rect', x: 0, y: 16, w: 32, h: 16 },
+    11: { kind: 'rect', x: 0, y: 16, w: 32, h: 16 }
+  }
+}
+```
+
+`kind: 'rect'` is the only valid value in v1; `'circle'` is reserved for v2
+and the union widens as a pure addition. The `isPerFrameHitbox(hitbox)` type
+guard narrows the union.
+
+### `Asset.depthAnchor` — Y-sort footprint pixel
+
+```ts
+depthAnchor: { x: 16, y: 28 }   // pixel within frame 0 the SDK aligns sprite.y with
+```
+
+The SDK applies `sprite.setOrigin(x / frameW, y / frameH)` at spawn so the
+sprite's world `y` equals the world y of this pixel. Typical: feet for
+characters, trunk base for trees, foundation midpoint for buildings.
+
+### `applyAssetHitbox(sprite, asset)` — apply at runtime
+
+Called automatically by `createSprite` at scene boot. **Also callable** by
+behavior code after attaching a body later:
+
+```ts
+import { applyAssetHitbox } from '@umicat/phaser-sdk';
+
+const player = registry.getById('player');
+const asset = manifest.assets.find(a => a.id === player.getData('assetId'));
+
+scene.physics.add.existing(player);
+applyAssetHitbox(player, asset);   // reads asset.hitbox, applies to body
+```
+
+Semantics:
+
+- **No-op (silent)** when `asset.hitbox` is unset. Safe to call defensively.
+- **Dev-warn (NOT throw)** when called on a sprite without a physics body.
+  Most likely cause: call order — `scene.physics.add.existing(sprite)` must
+  come first.
+- **For per-frame hitboxes**: installs an `ANIMATION_UPDATE` listener that
+  swaps `body.setSize`/`setOffset` on every frame change during animation
+  playback. Idempotent — re-applying tears down the old listener first.
+
+**v1 caveat**: manual `sprite.setFrame(idx)` calls outside of animation
+playback do NOT swap the body. Combat sheets are animation-driven, so this
+rarely bites in practice.
+
+### Scene-level `ySort: true` — per-frame depth sort
+
+```json
+// public/scenes/world/main.json
+{
+  "schemaVersion": 1,
+  "id": "main",
+  "type": "world",
+  "ySort": true,
+  "entities": [ ... ]
+}
+```
+
+When set, `loadWorldScene` installs a per-frame update hook that walks the
+entity registry and assigns `sprite.depth = sprite.y` to every entity.
+**Per-game cost**: O(n) per frame; 200 entities at 60 FPS = 12,000
+`setDepth` calls/sec — well within Phaser's render budget.
+
+Two opt-out mechanisms (orthogonal, cover different intents):
+
+```ts
+// explicit constant depth → ySort skips the entity entirely
+{ "transform": { "x": 100, "y": 100, "depth": 1000 } }   // cloud always on top
+
+// behavior-managed depth → ySort doesn't touch the entity
+{ "transform": { "x": 100, "y": 100 }, "properties": { "skipYSort": true } }
+```
+
+### The conditional rule (when to call `applyAssetHitbox`)
+
+```ts
+const asset = manifest.assets.find(a => a.id === sprite.getData('assetId'));
+scene.physics.add.existing(sprite);
+
+if (asset?.hitbox) {
+  applyAssetHitbox(sprite, asset);          // metadata is source of truth
+} else {
+  sprite.body.setSize(30, 20);              // hardcode from gameplay intent
+  sprite.body.setOffset(5, 5);
+}
+```
+
+Both paths are correct depending on context:
+
+- **`applyAssetHitbox` path** — sprite uses an Asset that has `hitbox`
+  metadata. Pack import sets it via vision; users refine via the Hitbox
+  Editor. Hardcoding `setSize` afterward would override the user's
+  authored values.
+- **Hardcode path** — primitive sprites (`scene.add.rectangle`), AI-gen
+  images with no vision pass, chat-only games with no scene-as-data
+  manifest. There's nothing to apply; hardcoding is the right answer.
+
+The `asset-hitbox-physics` agent skill (in
+`plugins/unboxy-phaser/skills/asset-hitbox-physics/SKILL.md`) walks through
+this decision tree with worked examples.
+
+### Authoring metadata (the editor surface)
+
+Users author `hitbox` + `depthAnchor` in the home-ui's Hitbox Editor modal —
+launched from the Assets panel's per-card hover button (green hitbox icon).
+Supports both Same-for-all-frames and Per-frame overrides modes, with a
+frame strip + override-dot indicators for the per-frame case.
+
+Vision pre-fills the single-shape form at pack-import time for character /
+tree / building / rock / decoration subjects (narrow trunk for trees, foot
+footprint for characters, foundation for buildings).
+
+
+- Do **not** block scene creation on `umicatReady`. Games must cold-start immediately; hydrate when the promise resolves.
+- Do **not** save on every frame / every score tick. Debounce or only save on meaningful events (game over, level clear).
+- Do **not** store large binary blobs (images, audio) as save values — use a dedicated blob API when it ships.
+- Do **not** use `localStorage` directly for persistent data when `umicat.saves` is available — you'll lose cross-device sync when we ship provisional accounts.
+- Do **not** put secrets, private messages, or per-user data in `gameData` — it's public. That's `saves`.
+- Do **not** write to `gameData` on every score tick either — submit once at game-over or level-clear.
+
+## Tilemap per-tile metadata + collision (visual editor slice 6 Phase C, since 0.2.115)
+
+Each tile in a tileset can carry per-tile metadata (collision flag, damage,
+terrain tag, movement modifier, etc.). The SDK reads it from
+`asset.tileset.tiles` and:
+
+1. **Auto-wires solid-tile collision** at scene load via Phaser's native
+   `layer.setCollisionByProperty({ solid: true })`. Behavior code only
+   needs `scene.physics.add.collider(player, layer)` — every tile flagged
+   `solid: true` blocks the player.
+2. **Exposes per-tile metadata** via the new `getTilemapAt(scene, entityId, x, y)`
+   helper so game code can react to non-collision fields (damage, slope,
+   movement, ground type).
+
+### Authoring
+
+Users author metadata in the home-ui's Tile Metadata Editor — select a
+tile in the TilemapInspectorPanel's palette, then click the **⚙ Configure
+tile #N** button that appears below the palette. (Right-click also opens
+the modal as a power-user shortcut.) Eight fields per tile:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `solid` | boolean | Auto-armed via `setCollisionByProperty`. Standard collision. |
+| `oneWay` | boolean | Jump-through platform flag. v1 stores only; game code wires the check. |
+| `slope` | `'up-left'` \| `'up-right'` | Slope direction for diagonal walk-up. |
+| `damage` | number | HP/sec dealt when player stands on tile. Game code applies. |
+| `terrainTag` | string | Free-form (`grass`, `water`, `sand`) — used by Phase D autotile + behavior. |
+| `movement` | `'walk'` \| `'swim'` \| `'fly'` \| `'block'` | Character speed/passability modifier. |
+| `groundType` | string | Footstep-sound selection: `soft`, `stone`, `metal`. |
+| `customTag` | string | Game-specific (`checkpoint`, `spawn`, `exit`). |
+
+Only non-default fields are persisted — sparse map keyed by tile index.
+
+### Collision — zero-config
+
+If any painted tile has `solid: true`, the SDK auto-arms collision on the
+layer. Use the `addTilemapCollider` helper to wire it up — handles both
+the default cell-rect collision AND sub-tile collision rects (see next
+section) in one call:
+
+```ts
+import { addTilemapCollider } from '@umicat/phaser-sdk';
+
+create() {
+  // ... spawn player ...
+  addTilemapCollider(this, 'world', this.player);
+}
+```
+
+No `setCollisionByIndex` or `setCollision` boilerplate — the SDK calls
+`setCollisionByProperty({ solid: true })` automatically at scene load.
+
+### Sub-tile collision shape (Godot/Tiled-style polygon-on-tile)
+
+For tiles where only PART of the cell should block the player (e.g. a
+tile that's visually half wall + half floor, an L-shaped wall corner,
+fence posts, decorative overhangs), the Tile Metadata Editor's
+**Collision Shape** sub-panel lets the user draw **N axis-aligned
+rectangles** on the tile preview. The shape is **authored once per tile**
+— every painted instance of that tile across every level automatically
+gets the same collision shape, same as Godot's TileSet Physics editor.
+
+Data shape (`TileMetadata.collisionRects`):
+```ts
+Array<{ x: number, y: number, w: number, h: number }>  // each rect in source-pixel coords, relative to tile top-left
+```
+
+Multi-rect supports L / U / frame-shaped collision (e.g. a wall corner
+is two rects forming an L; a frame border is four). For non-axis-aligned
+shapes (slopes), Phaser Arcade has no native support — that would require
+switching to Matter physics which has different semantics and breaks the
+project's Arcade-based skill library.
+
+At runtime the SDK:
+1. Disables Phaser's native cell-rect collision for tiles with custom
+   `collisionRects` (so it doesn't double-collide).
+2. Creates one invisible `Phaser.GameObjects.Rectangle` with an Arcade
+   static body per rect at every painted instance of that tile, sized +
+   positioned in world coords.
+3. Bodies live in a `Phaser.Physics.Arcade.StaticGroup` stashed on the
+   layer's data manager (`unboxySubTileStaticGroup`). Rebuilt on each
+   painter op (paint / erase / fillRect / bucketFill) and on each
+   `assetUpdate` (live save from the Tile Metadata Editor).
+
+Behavior code doesn't need to know about any of this — `addTilemapCollider`
+wires up both the layer collider AND the sub-tile group at once. Cells
+without custom rects keep their default `solid` behavior; cells with a
+custom shape collide only on the sub-rects.
+
+**Implementation note**: Phaser's TilemapLayer + Arcade physics has no
+native sub-tile collision. This is a known limitation — the Phaser
+community workaround is exactly this static-body pattern. Matter physics
+has per-tile polygon support but requires switching the whole game to a
+different physics model, which has different semantics than Arcade and
+breaks every existing behavior pattern. We deliberately keep Arcade and
+materialize sub-rects as static bodies.
+
+### `getTilemapAt(scene, entityId, worldX, worldY, options?)`
+
+Read the painted tile at a world coord. Returns `null` when no tile is
+painted there (or coord is outside the layer); returns a `TilemapHit`
+otherwise:
+
+```ts
+interface TilemapHit {
+  layerId: string;          // which layer holds the tile
+  tileIndex: number;        // 0-based row-major index in the tileset image
+  metadata: TileMetadata;   // the eight-field object (empty when no metadata)
+  tileX: number;            // tile column within the layer
+  tileY: number;            // tile row within the layer
+}
+```
+
+```ts
+import { getTilemapAt } from '@umicat/phaser-sdk';
+
+update(_t: number, dt: number) {
+  const hit = getTilemapAt(this, 'world', this.player.x, this.player.y);
+  if (!hit) return;
+  // Damage tile (lava, spikes)
+  if (hit.metadata.damage) this.player.hp -= hit.metadata.damage * (dt / 1000);
+  // Movement modifier (water slows the player to 50%)
+  this.player.speed = hit.metadata.movement === 'swim' ? 0.5 : 1.0;
+  // Footstep sound by ground type
+  if (this.lastTile !== hit.tileIndex) {
+    this.lastTile = hit.tileIndex;
+    this.sound.play(`footstep-${hit.metadata.groundType ?? 'soft'}`);
+  }
+}
+```
+
+Layer scan order is top-down by default (highest `z` wins, matching the
+visual stack). Pass `options.layerId` to scope to one layer:
+
+```ts
+// Read the ground layer specifically (ignore decoration overlays)
+const hit = getTilemapAt(this, 'world', x, y, { layerId: 'floor' });
+```
+
+### Anti-patterns
+
+- Do **not** call `setCollisionByIndex` / `setCollision` yourself — the
+  SDK already arms `setCollisionByProperty({ solid: true })` after scene
+  load. Calling both can produce conflicting state where some painted
+  tiles are flagged but others aren't.
+- Do **not** read `layer.getTileAtWorldXY()` directly — it works but
+  loses the `metadata` object, the cross-layer top-down walk, and the
+  hidden-layer skip. Use `getTilemapAt`.
+- Do **not** rely on per-tile metadata for things that should be entity
+  properties — boss patrol points, NPC spawn positions, conversation
+  triggers. Those are entities (or triggers, slice 5), not tile flags.
+
+## Animated tiles (visual editor slice 6 Phase F, since 0.4.0)
+
+Painted cells whose source tile index equals an animation's `rootTileIndex`
+cycle through `frames[*].tileIndex` synchronously at runtime — water flow,
+lava bubble, torch flicker, glowing crystals. All matching cells animate
+together (Sprout Lands water lake-cells all flow in lockstep).
+
+### Schema (tileset metadata extension)
+
+```json
+{
+  "cellSize": { "width": 16, "height": 16 },
+  "cols": 4, "rows": 1,
+  "animations": [
+    {
+      "id": "water-flow",
+      "rootTileIndex": 0,
+      "frames": [
+        { "tileIndex": 0, "duration": 250 },
+        { "tileIndex": 1, "duration": 250 },
+        { "tileIndex": 2, "duration": 250 },
+        { "tileIndex": 3, "duration": 250 }
+      ]
+    }
+  ]
+}
+```
+
+- **`rootTileIndex`** — the tile users paint with. The painter palette shows
+  this tile with a 🎬 badge so users know which one to paint. Other frames
+  (1, 2, 3) are "internal" — the SDK swaps cells to them per-tick.
+- **`frames`** — cycle order. Convention: `frames[0].tileIndex === rootTileIndex`
+  so the static editor view (where animations don't run) matches frame 0.
+- **`duration`** — milliseconds per frame. Floor 16ms. Sprout Lands water
+  uses 250ms (4fps) across all 4 frames.
+
+### Runtime behavior
+
+`loadWorldScene` arms animations automatically — no code change needed in
+game scripts. Painted cells matching any `rootTileIndex` get swapped to the
+current frame every UPDATE tick. Cells painted with non-root indices stay
+static.
+
+### Edit mode vs Play mode
+
+In Edit mode the scene is paused (`setActive(false)`), so the animation
+UPDATE handler doesn't fire. `enterEdit` resets every animated cell to its
+root index so the editor always shows the authored ("data") frame, not
+whatever was visible at the moment of toggle. `exitEdit` resumes — next
+UPDATE tick swaps each cell to its current animation frame via elapsed-
+time math.
+
+### Save-path safety
+
+The iframe's per-frame `tile.index` mutation does NOT leak into the host's
+draft state. Home-ui keeps its own copy in `useEditorDraft`'s baseline +
+commands. Mid-animation Cmd+S saves root indices (the "data"), not the
+displayed frame.
+
+### Authoring UI
+
+Open the asset → `TilesetInspectorModal` → "Animations" section →
+"+ Add animation…" or "Edit animations…". The editor lets you pick a root
+tile + frames + uniform duration. For typical N-cell water/lava/torch
+spritesheets there's a one-click "Animate all" shortcut (sets root=0,
+frames=[0..N-1], duration=250ms).
+
+### When NOT to use
+
+- **Sprite animations** (player walk cycles, enemy attack frames) — those
+  are Phaser sprite animations, registered via `scene.anims.create()` from
+  `manifest.assets[].animations` (separate path, slice 7).
+- **One-shot tile state changes** (door opens, gate closes) — those are
+  `layer.putTileAt(x, y, newIndex)` from behavior code, not data-driven
+  cycling.
+- **Per-cell phase offset** (each water cell offset to look organic) — v2
+  per design 06 §8.9. v1 ships synchronized cycling only.
+
+## Changelog
+
+- **0.4.0** — visual editor slice 6 Phase F: **animated tiles** (2026-05-24). Closes the last open Slice 6 phase. New `TilesetAnimation` type + `TilesetMetadata.animations?: TilesetAnimation[]` schema (additive — minor bump). Painted cells with `tile.index === rootTileIndex` cycle through `frames[*].tileIndex` per-frame via a scene UPDATE listener installed by new `applyTilesetAnimations(layer, asset)` in `spawnEntity.ts`. All matching cells animate synchronously. Phaser 3 PARSES Tiled's `tile.animation` field into `tileset.tileData[id].animation` but its TilemapLayer renderer does NOT consume it (community `phaser-animated-tiles` plugin is bit-rotted on 3.80+); ~50-line custom impl avoids the dep. **Edit-mode behavior**: scenes pause via `setActive(false)` → handler dormant → cells reset to root via new `resetTilesetAnimationsToRoot(container)` so editor view always shows the authored frame. `exitEdit` resumes on next UPDATE tick. **Save-path safety**: per-frame `tile.index` mutation doesn't leak into the host's draft state. **Re-arm paths**: editor's `handleAssetUpdate` (Animation Editor save → live re-apply), `applyTilemapStructureOp addLayer` (new layer arm), every paint op's metadata re-application (newly-painted root tile starts animating immediately). Pairs with home-ui `TilesetAnimationsEditorModal` + "Animate all" quick-fill + 🎬 root-tile badge in the tilemap palette. SDK-GUIDE gains an "Animated tiles" chapter above the changelog covering schema, runtime, edit-mode behavior, when-not-to-use. Pack-import auto-detection of `water_0.png` / `water_1.png` filename sequences deferred to Phase F.2.
+- **0.2.121** — Phase C follow-up: **multi-rect sub-tile collision** (L / U / frame shapes). `TileMetadata.collisionRect` → `TileMetadata.collisionRects[]`. SDK `syncSubTileBodies` now creates N invisible static bodies per painted tile (one per rect). TileMetadataEditorModal's Collision Shape sub-panel rewritten as a multi-rect canvas: drag empty area = new rect (auto-selected), click existing rect = select it, drag selected = move, drag corner = resize, Delete key = remove selected, "Clear all" replaces "Clear". Selected rect = solid red border + corner handles; unselected rects = dashed translucent (clickable). Palette overlay draws N rects per cell. Backend POJO `TileMetadata.collisionRect` field replaced with `collisionRects: List<CollisionRect>`; parser validates each. Breaking change for in-flight test data but acceptable (one tester, no production data). Wall corners + complex collision shapes now expressible without splitting tiles.
+- **0.2.120** — fix: tilemap grid sketch (editor-only visualization showing tile boundaries on empty / sparsely-painted tilemaps) bled into Play mode. `createTilemap` now defaults the grid Graphics to `setVisible(false)` and tags it with `unboxyTilemapGrid` data flag. New `setTilemapGridsVisible(game, boolean)` helper walks every tilemap container's children, finds the tagged grid, and toggles. Called with `true` on `enterEdit` and `false` on `exitEdit`. Surfaced 2026-05-19 — in Play mode user saw the tilemap's grid lines overlaid on the actual tiles + extending past the world bounds.
+- **0.2.119** — fix: sub-tile collision bodies (0.2.116) landed at world origin instead of inside the tilemap's bounds — visible as static bodies stacked top-left of the canvas in `physics.world.createDebugGraphic()` while painted walls sat at the entity position. Root cause: `applyTilesetTileMetadata` was called inside `renderLayerInto` BEFORE the caller set `layerObj.x/y`, so `tile.getLeft()` returned layer-local coords (near 0,0) instead of world coords. `createTilemap` mirrors layer position from the container transform AFTER `renderLayerInto` returns, so painted tiles rendered correctly but sub-tile bodies were stranded. Fix: moved `applyTilesetTileMetadata` out of `renderLayerInto` to AFTER positioning in both `createTilemap` (initial spawn) and `applyTilemapStructureOp addLayer` (editor-time). `renderLayerInto` now does NOT call `applyTilesetTileMetadata` — comment notes the caller is responsible.
+- **0.2.118** — fix: deleting a tilemap entity in the editor left its TilemapLayers orphaned in scene root, still visible in the canvas until next save+reload. Same root cause as the 0.2.59-era "TilemapLayer can't be a Container child" architecture: layers live in scene root with a per-frame sync hook positioning them at `container.x + offset`. `deleteEntity` only destroyed the Container, so the orphaned layers had no parent to follow → frozen at their last sync position, visible until the next scene rebuild stripped them. Fix: `deleteEntity` now walks `container.getData('tilemapLayers')` and `.destroy()`s each layer before destroying the container. Also tears down the sub-tile static body group (`layer.getData('unboxySubTileStaticGroup')`) — those bodies are scene-root members too and would survive the container destroy.
+- **0.2.117** — fix: `createEntity` for tilemap entities didn't lazy-load tileset textures, leading to `tileset 'X' texture not loaded; skipping layer` warning + the painter falling back to drag-the-entity behavior right after CreateTilemapModal. The lazy-load gate was sprite-only (`entity.kind === 'sprite'`). Pre-existing bug, surfaced when the user deleted a tilemap and re-created one against a tileset that wasn't in the SDK's texture cache. Fix: generalize the lazy-load to walk `tilemap.layers[].tilesetIds[]`, resolve each via `manifestAsset` (preferred) or `getManifest(scene)`, and `loadAssetIntoScene` for any not in `scene.textures`. Also unconditionally `upsertCachedManifestAsset(scene, manifestAsset)` whenever the host passes one, mirroring the addLayer + assetUpdate paths so the manifest cache is consistent regardless of entity kind. Same fix pattern as 0.2.43's region-atlas live-edit gap. No new exports, no API changes.
+- **0.2.116** — visual editor slice 6 Phase C follow-up: **sub-tile collision rects** (Godot/Tiled-style polygon-on-tile, rect-only in v1). Solves the "tile is visually half wall + half floor — block only the wall half" case without splitting the asset. New `TileMetadata.collisionRect: { x, y, w, h }` (source-pixel coords relative to tile top-left). SDK runtime: `applyTilesetTileMetadata` now also calls new `syncSubTileBodies` — walks painted tiles with a `collisionRect`, disables Phaser's native cell-rect collision for them (`tile.setCollision(false, ...)`), and creates invisible `Phaser.GameObjects.Rectangle`s with Arcade static bodies sized to the sub-rect. Bodies live in a per-layer `StaticGroup` stashed on the layer's data manager (`unboxySubTileStaticGroup`). Rebuilt on every painter op (paint / erase / fillRect / bucketFill) — `handleEditTilemap` looks up the layer's tileset asset post-op and re-runs `applyTilesetTileMetadata`, which is cheap when no tile has a `collisionRect` (single map scan + early return). Also rebuilt on `assetUpdate` (Tile Metadata Editor save). **New SDK export `addTilemapCollider(scene, entityId, target, callback?)`** — single-call helper that wires both `physics.add.collider(target, layer)` AND `physics.add.collider(target, subTileGroup)` for every layer of a tilemap entity, so behavior code never has to know whether a tile has cell-rect or sub-rect collision. Returns the created `Collider[]` so callers can destroy on level transition. Pairs with home-ui's TileMetadataEditorModal which gains a "Collision shape" sub-panel — drag on a zoomed tile preview to define the rect, drag corner handles to resize, drag body to move, click-without-drag to clear; rect persists as `TileMetadata.collisionRect`. TilemapInspectorPanel's tile palette gains a red rect overlay on cells with a custom collision shape (additive to the existing metadata dot). Backend POJO + parser extended with new `CollisionRect` inner class (positive w/h, non-negative x/y validation). **Phaser community context**: Phaser's TilemapLayer + Arcade physics has no native sub-tile collision; the established community pattern is exactly this static-body workaround (Matter physics has per-tile polygon support but switching breaks every Arcade-based behavior pattern). We stay on Arcade and materialize per-painted-tile bodies. Pure forward-compat addition — existing tilesets without `collisionRect` keep their cell-rect-only behavior.
+- **0.2.115** — visual editor slice 6 Phase C: per-tile metadata + auto-collision + `getTilemapAt`. New `TilesetMetadata.tiles` field (sparse map keyed by tile index, eight-field per-tile metadata — solid / oneWay / slope / damage / terrainTag / movement / groundType / customTag). SDK consumer: new `applyTilesetTileMetadata(tileset, layer, asset)` is called automatically after `map.createLayer` in both initial spawn (`renderLayerInto` in spawnEntity.ts) AND editor-time `addLayer` (EditorBridge.applyTilemapStructureOp); it stamps `tileset.tileProperties` so newly-painted tiles inherit the lookup, walks already-painted tiles via `layer.forEachTile` to refresh `tile.properties`, and calls `layer.setCollisionByProperty({ solid: true })` so behavior code only needs `physics.add.collider(player, layer)` for free collision. Live edit: `handleAssetUpdate` (`umicat:editor:assetUpdate` message) now also walks every tilemap layer using the updated asset and re-applies metadata + collision wiring — Tile Metadata Editor save takes effect in the running iframe without a workspace rebuild / scene reload. New SDK export `getTilemapAt(scene, entityId, worldX, worldY, options?)` returns a `TilemapHit` (`{ layerId, tileIndex, metadata, tileX, tileY }`) or null; default layer scan is top-down (highest z wins, matches visual stack), `options.layerId` scopes to one layer. New exports: `applyTilesetTileMetadata`, `getTilemapAt`, types `TileMetadata`, `TilemapHit`. Asset record now carries `tileset.tiles?: { [tileIndex: number]: TileMetadata }`. Tilemap layer GO is tagged with `tilemapTilesetId` so the assetUpdate handler can find affected layers without a registry walk. Pairs with home-ui's TileMetadataEditorModal (right-click any tile in the TilemapInspectorPanel palette → modal with eight fields → PATCH `/games/{gameId}/assets/{assetId}/tileset` → updateAsset round-trip to iframe). No template PR needed — purely additive editor / runtime work. SDK-GUIDE gains a "Tilemap per-tile metadata + collision" chapter covering authoring, zero-config collision, `getTilemapAt` API + examples, and anti-patterns.
+- **0.2.55** — fix: gravity declared in scene data is now applied. `world.physics.gravity` (per world scene) and `manifest.globals.physics.gravity` (manifest-wide default) were typed-but-dead fields — `loadWorldScene` never read them, so a game that declared gravity in scene data ran at zero gravity (a platformer that "looks right but nothing falls"). `loadWorldScene` now applies them to `scene.physics.world.gravity`, scene-level winning over the manifest global, components applied individually (a partial `{ y }` leaves `x` intact). No schema change (both fields already existed in the `Manifest` / `WorldSceneConfig` types), no new exports. `game.json`'s `GameConfig.physics.gravity` is unchanged — it's a separate boot-time path wired through `createUmicatGame`. Behavior note: a game that *already* declared scene-data gravity now actually gets it — intended, since the field was inert before.
+- **0.2.54** — fix: code-rendered scene entities had no usable physics body, and the prefab physics path mis-anchored code-rendered bodies. Two parts: (1) **scene entities can now carry a `physics` block** (`sprite` / `primitive` / `code-rendered`, same `PrefabPhysics` shape prefabs use) — `spawnEntity` applies it via `physics.add.existing` + body size/offset/immovable/velocity/bounce. Before this, scene entities had no physics-application path at all, so a code-rendered platform got a 0×0 body and everything fell through it. (2) **code-rendered bodies are now correctly anchored.** A Phaser `Graphics` hardcodes `displayOrigin = (0,0)` (no Origin component) while render scripts draw centered on local (0,0); the Arcade body positions at `gameObject.x + offset.x`, so the prior default-offset body landed at the bottom-right of the visual ("player floats above the platform"). The fix shifts the *body frame* by `(-visualW/2, -visualH/2)` for code-rendered visuals — body-only, never touches the Graphics, so rendering is unaffected (this is the correct fix that 0.2.52's reverted `g.setOrigin` approach got wrong). Prefab and scene-entity physics now share one body-level path (`applyEntityPhysics` in `spawnEntity.ts`). Sprite / primitive physics behavior is unchanged. No new exports — `WorldEntityBase` gains an optional `physics` field; existing games are unaffected.
+- **0.2.45** — fix: `isPerFrameHitbox` type guard tightened to check `default != null` rather than `'default' in h`. Closes a wire-shape gap from slice 8 v1.1 — the backend now writes explicit null values on the alternate shape's fields when a Hitbox PATCH switches modes (Single ↔ Per-frame), because OpenSearch's `_update` API deep-merges nested objects and would otherwise leave stale per-frame fields after a Single-mode save. Without this guard fix, the SDK's `applyAssetHitbox` would have treated the explicit-null `default: null` as "per-frame mode" via the `'in'` check and crashed when calling `applyShape(body, null)`. Pure SDK change — no API additions; only the guard's branch condition.
+- **0.2.44** — visual editor slice 8: depth + asymmetric collision. New fields `AssetRecord.hitbox` (single rect or per-frame overrides) + `AssetRecord.depthAnchor` (footprint pixel for Y-sort). New scene flag `WorldScene.ySort: boolean` (per-frame `setDepth(y)` hook). New SDK export `applyAssetHitbox(sprite, asset)` — silent no-op without metadata, dev-warn on missing body, idempotent `ANIMATION_UPDATE` listener install for per-frame variants. New type guard `isPerFrameHitbox`. Two new editor protocol messages — `umicat:editor:assetUpdate { asset }` (broadcast hitbox/anchor edits to running iframe; re-applies to every spawned instance, no scene reload) + `umicat:editor:setDebugOverlay { showHitboxes }` (toggle the EditorOverlayScene's per-frame hitbox + anchor draw). See "Collision + Y-sort" chapter. Pairs with: backend `PATCH /games/{id}/assets/{aid}/hitbox`, vision detection in pack import (character/tree/building/rock/decoration subjects), Hitbox Editor modal in home-ui, `asset-hitbox-physics` agent skill teaching the conditional rule.
+- **0.2.33** — docs: HUD scenes chapter added to this guide (covers slice-5 widget kinds, anchor model, dynamic bindings via `scene.registry`, `hud:press` event). Existing workspaces pick this up via `npm update @umicat/phaser-sdk`.
+- **0.2.32** — fix: 9-grid anchor side change in the visual editor moved container-based widgets (icon-button, progress-bar, panel) far from the new corner. `applyHudPatch` now re-applies the origin shift that compensates for containers having no `setOrigin`.
+- **0.2.31** — fix: progress-bar and panel widgets drew their Graphics rect from `(0, 0)` instead of centered, so the visual was offset by `(w/2, h/2)` from the editor's selection rect. Both now draw centered.
+- **0.2.30** — added HUD `progress-bar` and `panel` widgets (visual editor slice 5.5). progress-bar supports independent static/dynamic `value` and `max` bindings; panel is a colored rectangle with optional border + rounded corners. New types: `HudProgressBarVisual`, `HudPanelVisual`, `HudNumberSource`. See "HUD scenes" chapter above.
+- **0.2.29** — added HUD scene runtime (visual editor slice 5). New module `src/scene/HudRuntime.ts` exporting `UmicatHudScene`, `loadHudScene`, `spawnHudEntity`, `resolveAnchor`. Three v1 widget kinds: `text` (static or dynamic), `image`, `icon-button`. Auto-launched by `loadWorldScene` when `manifest.scenes[].hud` is set. Dynamic bindings hook into Phaser's game registry. Editor protocol gains `umicat:editor:setEditMode { mode: 'world' \| 'hud' }`. See "HUD scenes" chapter above.
+- **0.2.28** — fix: `EditorBridge.computeScreenRect` was multiplying by `Phaser.Scale.ScaleManager.displayScale.x` which is `gameSize / canvasBoundsSize` (the inverse of what the variable name suggests), so coords ballooned out of the iframe. Now measures CSS-to-logical scale directly via `canvas.getBoundingClientRect()`.
+- **0.2.27** — added `EditorSelectionRectMessage` (visual editor slice 4 — inline AI popover). SDK posts `umicat:editor:selectionRect { entityId, rect }` on selection change / drag-end / pan-zoom; rect is in iframe-relative pixels. Used by home-ui to anchor a floating ✨ button next to the selected entity for entity-scoped AI prompts.
+- **0.2.26** — fix: tilemap entities couldn't be selected in the editor. `spawnEntity` for `tilemap` now sets explicit hit-test bounds (Phaser Graphics has no intrinsic size).
+- **0.2.25** — fix: Backspace / Delete in the editor didn't remove selected entities once focus was inside the iframe. The overlay scene now catches bare Backspace/Delete and posts `action: 'delete'` to the host.
+- **0.2.24** — fix: re-dragging an already-in-manifest asset spawned an unrendered entity. `createEntity` resolver now falls back to the cached `manifest.json` when the host omits `manifestAsset`.
+- **0.2.23** — fix: code-rendered entities couldn't be selected/dragged in the editor. `spawnEntity` now sets explicit Graphics size (Phaser Graphics returns 0×0 from `getBounds()` otherwise). Schema gains optional `visual.width` / `visual.height`.
+- **0.2.22** — render-script registry wired (visual editor slice 3.5). `createUmicatGame` accepts a new `renderScripts: Record<path, RenderScriptModule>` option; templates build it via `import.meta.glob('./visuals/*.ts', { eager: true })`. `loadWorldScene` falls back to that registry when no explicit `resolveRenderScript` is passed, so games don't have to plumb it through every scene call. Missing scripts no longer crash the scene boot — `spawnEntity` renders a clear orange-bordered "?" placeholder instead and tags the GameObject with `renderScriptMissing` for debug. `applyEdit` now handles `visual.params` patches on `code-rendered` entities by re-calling render with merged params (live editor preview as you tune in the Inspector). New exports: `RenderScriptModule`, `setRenderScriptRegistry`, `getRenderScriptRegistry`, `resolveRenderScript`. Pairs with the `phaser-render-script` agent skill which teaches the pure-function contract.
+- **0.2.21** — visual editor slice 3 (drag-to-place). Formalized trigger + tilemap entity data shapes (TriggerEntity now has `shape: rect|circle`, `description`, `targets[]`; TilemapEntity has `tileSize`, `size`, `layers[]`). spawnEntity renders both as placeholders (trigger = semi-transparent cyan rect/circle, tilemap = translucent grid sketch — full features ship in slices 5+6). New protocol: `umicat:editor:createEntity { entity, manifestAsset? }` (host-side drag-to-place spawns entity at world coord; lazy-loads asset texture if needed) + `umicat:editor:deleteEntity { entityId }` (Backspace + undo of create). `sceneLoaded` now also carries the manifest snapshot so home-ui can mutate the asset table when a new asset gets dropped on the canvas.
+- **0.2.20** — added editor shortcut forwarding (Cmd+Z/Y/S land in iframe when canvas focused; SDK posts back to host via `umicat:editor:shortcut`). Without this, native shortcuts didn't reach the host's keydown listener after the user clicked the canvas.
+- **0.2.19** — fix: editor `enter` arriving while BootScene is still preloading (the post-flush iframe-rebuild path) had nothing to pause, so the world scene resumed running freely once it started up. Now the bridge re-attempts the pause + scene snapshot for ~3 seconds after enter, catching the scene as it transitions from BootScene → GameScene. Snapshot is also re-posted once a scene file lands in cache. Surfaced when slice-2's auto-flush rebuilt the iframe and the user found the sprite started moving again post-save (2026-05-07).
+- **0.2.18** — added editor bridge (visual editor slice 2). Replaces the slice-1 `umicat:setEditMode` message with a full editor protocol: `umicat:editor:enter`/`:exit` (toggles edit mode + launches the overlay scene), `:applyEdit` (mutates a live entity from the host), `:setSelection` (host pushes selection), `:panZoom` (editor camera control), plus SDK→host `:sceneLoaded` (initial snapshot), `:pickEntity` (pointer-down selection), `:dragEnd` (entity dragged to new position). New module `src/editor/` with `EditorOverlayScene` (high-depth Phaser.Scene drawing selection rect + world bounds, capturing pointer events) and `EditorBridge` (postMessage handler + applyEdit logic). New exports: `setupEditorBridge`, `EditorOverlayScene`, `EDITOR_OVERLAY_KEY`, plus all editor protocol types. `setupEditorModeListener` is preserved as a thin wrapper that delegates to the bridge so existing `createUmicatGame` wiring continues to work. Pairs with home-ui's new Hierarchy + Inspector panels and `useEditorDraft` hook.
+- **0.2.17** — added scene-as-data foundation (visual editor slice 1). New exports: `loadWorldScene`, `preloadManifest`, `getManifest`, `preloadSceneAssets`, `spawnEntity`, `EntityRegistry`, `attachEntityRegistry`, `getEntityRegistry`, `setupEditorModeListener`, `isEditMode`, `parseColor`, `SCHEMA_VERSION`, plus all schema types (`Manifest`, `WorldScene`, `WorldEntity`, `Transform`, `AssetRecord`, etc.). New games that ship with `public/scenes/manifest.json` load entities + camera config from JSON; `GameScene.ts` becomes a generic loader that calls `await loadWorldScene(this, sceneId)`. `createUmicatGame` now also wires `setupEditorModeListener` so the host (home-ui) can pause active scenes via `postMessage({ type: 'umicat:setEditMode', enabled: boolean })`. Purely additive — existing scene-as-code games are unaffected. Migration to scene-as-data is opt-in via the `scene-data-migration` agent skill.
+- **0.2.16** — added orientation presets. `createUmicatGame` now accepts an `orientation: 'portrait' | 'landscape'` option as an alternative to explicit `width`/`height` (TS union — pass one or the other). New exports: `Orientation` type and `ORIENTATION_DIMENSIONS` map (`landscape: 1280×720`, `portrait: 720×1280`). Lets games declare orientation once and have a single source of truth for canvas dimensions.
+- **0.2.15** — fix: `ChatFacade.subscribeToPlayers` early-returned when `state.players` was `undefined` at construction time, which it always is on a fresh `joinOrCreate` (Colyseus delivers initial state as a separate message a few ms later). The early return meant `onStateChange` never subscribed and `system.joined` / `system.left` stayed silent in production despite the 0.2.14 callback-API fix. Now: always subscribe; treat the first state change as initial hydration (silent), subsequent changes do real diff. Three regression tests cover the deferred-hydration flow.
+- **0.2.14** — fix: `ChatFacade` `system.joined` / `system.left` events were silently no-op'ing in production. The lifecycle subscription used `state.players.onAdd` / `.onRemove` instance methods that Colyseus 0.16 removed in favour of `getStateCallbacks(room)`; the runtime check `typeof players.onAdd === 'function'` evaluated false, so neither system message fired. Now uses `room.onStateChange` + a known-names diff — robust to future Colyseus API changes. Tests updated to match. Patch-only; no API change for game code.
+- **0.2.13** — added `room.chat` helper for in-game chat. New API: `room.chat.send(text)` (returns `Promise<void>`) + `room.chat.onMessage(handler)`, plus exports `ChatMessage`, `ChatMessageKind`, and `MAX_CHAT_TEXT_LEN`. Wraps the existing `'chat'` wildcard relay with local echo (sender sees own message synchronously), stamped `displayName` on every payload, trim + 500-char silent truncate, and auto-emitted `kind: 'system.joined'` / `'system.left'` messages computed locally from `room.state.players` add/remove events (no wire traffic). Replaces the raw `room.send('chat', text)` pattern in the Multiplayer chapter — raw still works but loses local echo, length cap, and join/leave events.
+- **0.2.12** — added `umicat.rooms.list(options?)` — returns the open rooms for the caller's game right now, scoped server-side to the caller's gameId. Use this to build a lobby browser ("show me open rooms, click to join") without needing an out-of-band room code. SDK-GUIDE adds a "Browsing open rooms" section under Multiplayer covering the `RoomListEntry` shape, the poll-on-timer pattern, and the `{ roomCode }` filter for "is room X up yet?" probes.
+- **0.2.11** — added `roomCode` + `maxClients` to `JoinOptions`. SDK-GUIDE's Multiplayer chapter now documents matchmaking: room type is always `'lobby'`; use `roomCode` to bucket independent rooms per gameId (create-with-fresh-code, join-with-shared-code, quick-match with empty code). Fixes a real bug where agents were passing a gameId-derived string as the room type (e.g. `joinOrCreate('blokus-<code>', ...)`) and failing with "no handler" server-side.
+- **0.2.10** — docs: added a `createUmicatGame` options table (including the new `plugins` field) and a third-party Phaser plugin registration example. No code changes; version bumped so existing workspaces pick up the new guidance via `npm update @umicat/phaser-sdk`.
+- **0.2.9** — `createUmicatGame` now forwards the optional `plugins` field to Phaser's `GameConfig`. Previously the option was accepted at the call site but silently dropped — any `phaser3-rex-plugins` (or similar) registration never took effect, and `this.plugins.get(key)` returned undefined at runtime. Purely additive; no effect on games that don't pass `plugins`. Lets the `phaser-rex-touch` agent skill work end-to-end.
+- **0.2.8** — docs: added "Making remote motion feel smooth" section to the multiplayer chapter with concrete examples for interpolation (continuous motion), extrapolation (projectiles), and snap (discrete/turn-based/infrequent). No code changes — version bumped so existing workspaces pick up the new guidance via `npm update @umicat/phaser-sdk`.
+- **0.2.7** — fixed handshake race on slow-mounting hosts. `PostMessageTransport.connect` now retries `umicat:hello` every 200 ms until `umicat:init` arrives (previously one-shot → lost on Android/mobile where React mounted after the iframe first fired hello). Default handshake timeout bumped from 2 s → 5 s.
+- **0.2.6** — redesigned `umicat.rooms` around two generic primitives: delta-synced KV state (`room.player.set/get/delete`, `room.data.set/get/delete`) + transient relay (`room.send` / `room.on`). Server no longer bakes in game-specific fields like x/y/color/ready or a `move` handler — games define their own shapes via opaque JSON values, same contract as `gameData` / `saves`.
+- **0.2.5** — added `umicat.rooms` module (server-authoritative multiplayer rooms backed by Colyseus on umicat-realtime-service). Requires sign-in. Host must advertise `realtime` capability. Colyseus client loaded lazily — single-player games do not pay for the dependency.
+- **0.2.4** — added `umicat.gameData` module (game-scope key-value store for scoreboards, shared state)
+- **0.2.3** — anonymous users now use localStorage even inside a host (was throwing UNAUTHENTICATED when calling `saves` in home-ui without login)
+- **0.2.2** — added `SDK-GUIDE.md`
+- **0.2.1** — added `Umicat.init`, `umicat.user`, `umicat.saves`, Transport abstraction (PostMessage + LocalStorage backends)
+- **0.2.0** — added `UmicatScene`, recording support. Migrated to public npm.
+- **0.1.0** — initial release (CodeArtifact).