@umicat/phaser-sdk 1.0.0

package/dist/protocol.d.ts

@@ -0,0 +1,807 @@
+export declare const PROTOCOL_VERSION = 1;
+export interface UmicatUser {
+    id: string;
+    name: string;
+    avatar?: string;
+}
+export interface HelloMessage {
+    type: 'umicat:hello';
+    protocolVersion: number;
+    sdkVersion: string;
+}
+export interface RpcRequestMessage {
+    type: 'umicat:rpc';
+    id: string;
+    method: string;
+    params?: unknown;
+}
+export type SdkToHostMessage = HelloMessage | RpcRequestMessage;
+export interface InitMessage {
+    type: 'umicat:init';
+    protocolVersion: number;
+    gameId: string;
+    user: UmicatUser | null;
+    capabilities: string[];
+    /**
+     * WebSocket endpoint for umicat-realtime-service. Present only when the host
+     * has multiplayer configured (capabilities includes 'realtime'). SDK connects
+     * here after fetching a JWT via the 'realtime.getToken' RPC.
+     */
+    realtimeUrl?: string;
+}
+export interface RpcResultOk {
+    type: 'umicat:rpc.result';
+    id: string;
+    ok: true;
+    result: unknown;
+}
+export interface RpcErrorPayload {
+    code: string;
+    message: string;
+}
+export interface RpcResultError {
+    type: 'umicat:rpc.result';
+    id: string;
+    ok: false;
+    error: RpcErrorPayload;
+}
+export type HostToSdkMessage = InitMessage | RpcResultOk | RpcResultError;
+/**
+ * Patch shape applied to a live entity. Only the fields present are updated;
+ * `null` is the explicit clear (drops the field).
+ *
+ * **Flat schema** (SDK 0.3.0). Visual / render fields live at the patch root,
+ * the same place they live on the entity. Sprite tint goes in `tint`, not
+ * `visual.tint`. Same rule for every renderable field across every entity kind.
+ *
+ * The bridge applies only the slot relevant to the entity's kind — passing
+ * `width` on a sprite is a no-op, same as `tint` on a panel.
+ */
+export interface EditorEntityPatch {
+    transform?: Partial<{
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+        depth: number;
+    }>;
+    /**
+     * HUD-only (slice 5). Updates an entity's anchor side / offset. Only one
+     * of `transform` (world entities) or `anchor` (HUD entities) is set per
+     * patch; the SDK picks the right path based on the active mode.
+     */
+    anchor?: Partial<{
+        side: string;
+        offsetX: number;
+        offsetY: number;
+    }>;
+    /** HUD-only (slice 5). Render layer / z-order overrides. */
+    layer?: string;
+    z?: number;
+    /** Sprite / HUD-image tint + opacity controls. */
+    tint?: string | null;
+    alpha?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    /** Sprite / HUD-image frame index OR atlas frame name. */
+    frame?: string | number;
+    /** Primitive (rect / circle) + HUD widget dims. */
+    width?: number;
+    height?: number;
+    radius?: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    /**
+     * For `code-rendered` entities — the entire params object replaces
+     * `params`. SDK re-calls `render(g, params)` on receipt.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * HUD text widgets — replaces `source` wholesale. Static→dynamic switches
+     * and prefix/suffix edits all land here.
+     */
+    source?: Record<string, unknown>;
+    /** HUD text font / colour. */
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+    /** Sprite / HUD-image / HUD-icon-button asset references. */
+    assetId?: string;
+    iconAssetId?: string;
+    backgroundAssetId?: string | null;
+    backgroundFrame?: number;
+    backgroundRegion?: string;
+    /** HUD icon-button label + shape + colors. */
+    label?: string;
+    shape?: 'rounded-rect' | 'circle';
+    pressedFillColor?: string;
+    textColor?: string;
+    /** HUD progress-bar / panel — value + background. */
+    value?: Record<string, unknown>;
+    max?: Record<string, unknown>;
+    backgroundColor?: string;
+    backgroundAlpha?: number;
+    borderColor?: string | null;
+    borderWidth?: number;
+    borderRadius?: number;
+    role?: string | null;
+    properties?: Record<string, unknown>;
+}
+export interface EditorEnterMessage {
+    type: 'umicat:editor:enter';
+}
+export interface EditorExitMessage {
+    type: 'umicat:editor:exit';
+}
+export interface EditorGetSceneMessage {
+    /** Host requests a snapshot of what's currently loaded in the iframe. */
+    type: 'umicat:editor:getScene';
+}
+export interface EditorApplyEditMessage {
+    type: 'umicat:editor:applyEdit';
+    entityId: string;
+    patch: EditorEntityPatch;
+    /**
+     * Optional asset record to upsert into the iframe's manifest cache + lazy-
+     * load before the patch applies. Mirrors {@link EditorCreateEntityMessage}'s
+     * `manifestAsset` field. Used by the Inspector's Bg-image picker when the
+     * user picks an asset whose manifest entry needs flipping (e.g. region
+     * atlases — visual editor slice 10 — where the existing manifest entry
+     * was {@code kind: 'image'} but the asset is now atlas-format).
+     *
+     * <p>When present, the bridge:
+     *   1. Merges the asset into {@code scene.cache.json}'s manifest record
+     *   2. Lazy-loads the texture (and atlas-ninepatch sidecar JSON when
+     *      {@code kind: 'atlas' + atlasFormat: 'json'})
+     *   3. Applies the entity patch
+     */
+    manifestAsset?: unknown;
+}
+export interface EditorSetSelectionMessage {
+    type: 'umicat:editor:setSelection';
+    /** Empty array deselects. v1: max length 1 (multi-select is slice 2.5). */
+    entityIds: string[];
+}
+export interface EditorPanZoomMessage {
+    /** Editor camera control — separate from in-game camera. */
+    type: 'umicat:editor:panZoom';
+    scrollX?: number;
+    scrollY?: number;
+    /** Absolute zoom (1 = 100%). */
+    zoom?: number;
+    /** If true, deltas are added to current scroll. */
+    relative?: boolean;
+}
+/**
+ * Create a new entity in the active scene (slice 3 — drag-to-place).
+ * The SDK picks an asset record from `manifestAsset` (if present) so the
+ * texture can be lazy-loaded before spawn. Position can be supplied as
+ * world coords (preferred — host computed via 1:1 mapping in slice 3) or
+ * skipped if the entity already carries a transform.
+ */
+export interface EditorCreateEntityMessage {
+    type: 'umicat:editor:createEntity';
+    /** Full entity record. transform.x/y is authoritative. */
+    entity: unknown;
+    /** Asset record to add to runtime cache before spawn. Omit if assetId is already loaded. */
+    manifestAsset?: unknown;
+}
+export interface EditorDeleteEntityMessage {
+    type: 'umicat:editor:deleteEntity';
+    entityId: string;
+}
+/**
+ * Editor mode — slice 5. World mode edits the world scene; HUD mode edits
+ * the HUD scene attached to the active world. The host sends this when the
+ * user toggles the World/HUD switch in the editor canvas.
+ *
+ * The mode change does NOT clear selection at the SDK level; the host owns
+ * selection state per mode (separate selectedId for world / HUD drafts).
+ */
+export interface EditorSetEditModeMessage {
+    type: 'umicat:editor:setEditMode';
+    mode: 'world' | 'hud';
+}
+/**
+ * Asset-level live update (slice 8 — hitbox / depthAnchor editing).
+ *
+ * When the user edits an Asset's hitbox or depthAnchor in the Hitbox Editor
+ * modal, the change is at the asset level — not tied to a specific entity
+ * patch. The host sends this message; the bridge:
+ *   1. Upserts the asset into the iframe's cached manifest
+ *   2. Walks the entity registry, finds every sprite entity using this asset
+ *      (matched via `entityAssetId` data-manager stash), and re-applies
+ *      `setOrigin(depthAnchor)` + `applyAssetHitbox` to each
+ *
+ * Unlike `applyEdit`, this is NOT scoped to a single entity — one asset edit
+ * can affect dozens of in-scene sprites simultaneously.
+ */
+export interface EditorAssetUpdateMessage {
+    type: 'umicat:editor:assetUpdate';
+    /** Full AssetRecord — replaces the existing manifest entry. */
+    asset: unknown;
+}
+/**
+ * Patch applied to a prefab record (slice 11 Phase B.5 / editor P0.2).
+ *
+ * Mirrors the slice-2 entity patch shape but scoped to prefab fields. Only
+ * the fields present in the patch are updated; unset fields are unchanged.
+ *
+ * The bridge merges the patch into `manifest.prefabs[<id>]` in the cached
+ * manifest, then walks `EntityRegistry.byPrefabId(id)` and re-applies the
+ * visual / physics changes to every live instance. Subsequent `spawnPrefab`
+ * calls pick up the new values automatically.
+ *
+ * Property edits are stamped on `getData('entityProperties')` so behavior
+ * code reading `go.getData('entityProperties').hp` sees the new value
+ * immediately. Role edits update the entity-registry's role map.
+ */
+/**
+ * Patch to a prefab record. Flat schema (SDK 0.3.0) — render fields
+ * (assetId / tint / fillColor / width / params / etc.) live at the patch
+ * root, exactly like world-entity patches.
+ *
+ * The bridge deep-merges the patch into `manifest.prefabs[<id>]` then
+ * re-applies the same fields to every live instance returned by
+ * `EntityRegistry.byPrefabId(id)`. Subsequent `spawnPrefab` calls pick up
+ * the new values automatically.
+ */
+export interface EditorPrefabPatch {
+    /** Sprite. */
+    assetId?: string;
+    frame?: string | number;
+    tint?: string | null;
+    alpha?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    /** Primitive (rect / circle). */
+    width?: number;
+    height?: number;
+    radius?: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    /** Code-rendered — entire params object replaces existing. */
+    params?: Record<string, unknown>;
+    /** Patched physics fields — body size / offset / immovable / velocity / bounce. */
+    physics?: {
+        bodyW?: number;
+        bodyH?: number;
+        offsetX?: number;
+        offsetY?: number;
+        immovable?: boolean;
+        velocityX?: number;
+        velocityY?: number;
+        collideWorldBounds?: boolean;
+        bounceX?: number;
+        bounceY?: number;
+    };
+    /** Patched per-type properties — shallow-merged onto `prefab.properties`. */
+    properties?: Record<string, unknown>;
+    /** Patched role — `null` clears it from the prefab record. */
+    role?: string | null;
+}
+/**
+ * Patch a single rule (slice 11 Phase B.5 / editor P0.3 — 2026-05-16).
+ *
+ * Sent by the host when the Rules form commits a field change. Bridge
+ * delegates to `patchRule(scene, path, value)` in `Rules.ts`, which:
+ *  1. Writes the path-value pair into the cached rules tree.
+ *  2. Fires every subscriber whose path is the patched path OR an
+ *     ancestor of it (so a subscriber to `'balance'` sees an edit to
+ *     `'balance.lives'`).
+ *
+ * `path` is dot-notation (`'balance.lives'`, `'physics.gravity.y'`).
+ * `value` can be any JSON-serializable shape — primitive, array, or
+ * nested object. The host's draft layer mirrors this patch into its
+ * pending rules tree so the eventual flush writes the merged tree to
+ * `public/rules.json`.
+ */
+export interface EditorPatchRuleMessage {
+    type: 'umicat:editor:patchRule';
+    path: string;
+    value: unknown;
+}
+/**
+ * Snapshot of the cached rules tree posted by the SDK on enterEdit so
+ * the host's Rules panel can render the form without a separate fetch.
+ *
+ * Fires once per editor-enter, regardless of how many scenes are loaded
+ * (rules are game-level, not per-scene). Posts `{}` when the game has no
+ * `public/rules.json` or `preloadRules` was never called.
+ */
+export interface EditorRulesLoadedMessage {
+    type: 'umicat:editor:rulesLoaded';
+    rules: Record<string, unknown>;
+}
+/**
+ * Edit a prefab record (slice 11 Phase B.5 / editor P0.2 — 2026-05-16).
+ *
+ * Sent by the host when the Prefab Inspector commits a change. The bridge:
+ *   1. Deep-merges the patch into the cached `manifest.prefabs[<id>]`.
+ *   2. Walks `EntityRegistry.byPrefabId(id)` and re-applies the patched
+ *      visual fields (via the same paths `applyEdit` uses for world
+ *      entities — color/tint/alpha/code-rendered params/etc.) + physics
+ *      block (re-applies body size/offset/immovable/etc.) + property
+ *      stamps (via `setData('entityProperties', merged)`).
+ *
+ * Next `spawnPrefab` call picks up the new values automatically — no
+ * special path needed; the merged record is the new source of truth.
+ */
+export interface EditorEditPrefabMessage {
+    type: 'umicat:editor:editPrefab';
+    prefabId: string;
+    patch: EditorPrefabPatch;
+}
+/**
+ * Debug overlay toggle (slice 8 — "Show hitboxes" diagnostic).
+ *
+ * When the user toggles the scene-panel checkbox, the host sends this
+ * message. The overlay scene draws each sprite's hitbox rect (semi-
+ * transparent green) + depth-anchor crosshair (cyan ✚) for entities whose
+ * asset has those metadata fields set. Sprites without metadata get
+ * nothing drawn — chat-only Workflow A respect.
+ *
+ * Edit-mode only — complements Phaser's runtime `physics.world.createDebugGraphic`
+ * (which is the Play-mode tool), doesn't replace it.
+ */
+export interface EditorSetDebugOverlayMessage {
+    type: 'umicat:editor:setDebugOverlay';
+    showHitboxes: boolean;
+}
+/**
+ * Tilemap painter — active tool/tile/layer state (slice 6 Phase B).
+ *
+ * Host pushes this when the user selects a tilemap entity, switches paint
+ * tool (B/E/R/G/I), picks a different tile in the palette, or picks a
+ * different layer in the Hierarchy. SDK caches the values + uses them to
+ * drive paint behavior on canvas pointer events. `tilemapEditingId: null`
+ * deactivates paint mode (clearing both the cached state + ending any
+ * in-flight stroke).
+ *
+ * Why split state instead of per-pointer round-trip: pointer events fire
+ * many times per second; round-tripping each one through postMessage would
+ * add visible latency. SDK paints locally + posts ONE `tilemapEdited` per
+ * completed stroke for undo recording — same pattern as drag-to-move.
+ */
+export interface EditorSetTilemapToolMessage {
+    type: 'umicat:editor:setTilemapTool';
+    /**
+     * Tilemap entity being painted. Null clears paint mode (e.g. user
+     * selected a different entity kind, or explicitly exited tilemap mode).
+     */
+    tilemapEditingId: string | null;
+    /** Which layer (within the tilemap) the brush affects. Null when no layer chosen. */
+    activeLayerId: string | null;
+    /**
+     * Active paint tool. v1 surfaces brush + eraser (Phase B.3); rect/fill/picker
+     * (Phase B.4) land additively without protocol change.
+     */
+    tool: 'brush' | 'eraser' | 'rect' | 'fill' | 'picker';
+    /**
+     * Active tile index (0-based, row-major within the layer's tileset). Null
+     * means no tile picked yet — brush is no-op in that state. Eraser ignores
+     * this field.
+     */
+    activeTile: number | null;
+    /**
+     * Active Wang terrain id (slice 6 Phase D — design doc 06 §7). When
+     * non-null AND the active layer's tileset has matching autotile
+     * metadata, the brush/eraser paints with the terrain (cascade + ruleMap
+     * lookup) instead of stamping `activeTile` literally. Null = stamp-mode
+     * brush (existing Phase B behavior). Mutually meaningful with
+     * `activeTile`: stamp mode ignores terrainId; terrain mode ignores
+     * activeTile.
+     */
+    activeTerrainId?: string | null;
+}
+/**
+ * Explicit tilemap edit op pushed by the host (slice 6 Phase B).
+ *
+ * Used for: agent-authored writes ("paint a 5×5 grass patch"), undo/redo
+ * replay (host pushes the inverse op), and any future host-driven flow.
+ * Live painting via pointer events does NOT use this message — that path
+ * goes SDK→host (`tilemapEdited`) for undo recording.
+ */
+export interface EditorEditTilemapMessage {
+    type: 'umicat:editor:editTilemap';
+    entityId: string;
+    ops: TilemapEditOp[];
+    /**
+     * Optional manifest asset to upsert + load BEFORE the ops apply.
+     * Required when any op in this batch references an asset id that
+     * isn't yet in the iframe's cached manifest (typical case: addLayer
+     * with a freshly-picked tileset via Add Layer modal). Without this,
+     * the SDK handler hits a cache miss + skips the addLayer entirely
+     * → painter finds no layer → click falls through to drag.
+     *
+     * Pattern mirrors `EditorCreateEntityMessage.manifestAsset` (slice 3
+     * drag-to-place). The handler is async; upserts cache + awaits
+     * `ensureAssetLoaded` before invoking applyTilemapStructureOp.
+     *
+     * Typed `unknown` to avoid importing the AssetRecord type into
+     * protocol.ts (which has no runtime imports otherwise) — the SDK
+     * handler casts to AssetRecord.
+     */
+    manifestAsset?: unknown;
+}
+/**
+ * A single tilemap mutation. Cell coords are tile-grid coords (not pixels).
+ * paint/erase/fillRect/bucketFill mutate cell data within a layer (Phase B.3
+ * + B.4); addLayer/removeLayer/setLayerVisibility mutate the layer list
+ * itself (Phase B.5).
+ */
+export type TilemapEditOp = {
+    kind: 'paint';
+    layerId: string;
+    cells: Array<{
+        x: number;
+        y: number;
+        index: number;
+    }>;
+} | {
+    kind: 'erase';
+    layerId: string;
+    cells: Array<{
+        x: number;
+        y: number;
+    }>;
+} | {
+    kind: 'fillRect';
+    layerId: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** When omitted, fillRect acts as an erase-rect. */
+    index?: number;
+} | {
+    kind: 'bucketFill';
+    layerId: string;
+    x: number;
+    y: number;
+    index: number;
+} | {
+    /**
+     * Wang 4-bit autotile paint (slice 6 Phase D — design doc 06 §7).
+     *
+     * Each entry in `cells` is a USER-CLICKED cell; the SDK runs the
+     * cascade across that cell's 3×3 neighborhood, sets the 4 vertices,
+     * recomputes each affected cell's bitmask, and writes the
+     * corresponding tile index from `terrain.ruleMap`.
+     *
+     * The accompanying `tilemapEdited` message's `previousCells` array
+     * carries every cell whose tile changed (the click cells AND their
+     * cascade neighbors) — that's how the host records the inverse
+     * stroke for undo. Replaying the inverse re-issues an
+     * `autotilePaint` with the same `cells` and `erase` toggled, so
+     * the vertex grid stays in sync after undo.
+     */
+    kind: 'autotilePaint';
+    layerId: string;
+    /** Wang terrain id, references `tileset.autotile.terrains[].id`. */
+    terrainId: string;
+    cells: Array<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * When true the cells are UNPAINTED (4 vertices cleared, cascade
+     * recomputes). Omitted / false = paint.
+     */
+    erase?: boolean;
+    /**
+     * Cascade-resolved cells with their final tile indices (D.2.5.2 fix).
+     *
+     * Populated by the SDK when posting `tilemapEdited` so the host can
+     * persist the autotile result without re-running cascade logic
+     * (which needs ruleMap + asset context the host doesn't have).
+     * One entry per cell mutated by the click + its cascade neighbors
+     * (3×3 around each click, deduped). `index = null` means the cell
+     * became empty (no tile in ruleMap for the resulting bitmask).
+     *
+     * Agent-written `editTilemap` ops can omit this — the SDK's
+     * `applyTilemapOp` recomputes via `applyAutotile`. Only required
+     * when the host materializes the op into `layer.data` (save flush).
+     */
+    resolvedCells?: Array<{
+        x: number;
+        y: number;
+        index: number | null;
+    }>;
+} | {
+    /**
+     * Add a new layer to the tilemap (Phase B.5). The new layer is
+     * appended at the end of the layers array (renders on top of
+     * existing layers); explicit `z` in `layer` overrides this.
+     */
+    kind: 'addLayer';
+    layer: {
+        id: string;
+        name?: string;
+        tilesetIds?: string[];
+        z?: number;
+        visible?: boolean;
+    };
+} | {
+    /** Remove a layer from the tilemap. The layer's data is captured in `previousCells` so undo can restore. */
+    kind: 'removeLayer';
+    layerId: string;
+} | {
+    /** Toggle a layer's runtime visibility (and the editor-side checkbox). */
+    kind: 'setLayerVisibility';
+    layerId: string;
+    visible: boolean;
+} | {
+    /**
+     * Rename a layer. Editor-only metadata — name has no runtime
+     * effect (SDK doesn't use it; layers are looked up by `id`).
+     * Persisted to scene JSON so Inspector + Hierarchy + future
+     * tooling show the user-chosen name across sessions.
+     */
+    kind: 'setLayerName';
+    layerId: string;
+    name: string;
+} | {
+    /**
+     * Resize the tilemap (Phase B.6). Affects all layers atomically —
+     * each layer's data grid is clipped (shrink) or padded with -1
+     * (grow) to match the new dims. Tile cells at coords (x >= newW)
+     * or (y >= newH) are LOST on shrink — UI guards with a confirm
+     * when painted cells would be discarded.
+     *
+     * SDK runtime: destroys + recreates each TilemapLayer with the
+     * new dims (Phaser tilemap dims are immutable post-creation; the
+     * cleanest "resize" is a full layer rebuild). Background grid
+     * sketch is redrawn to match.
+     */
+    kind: 'resize';
+    width: number;
+    height: number;
+    /**
+     * Optional transform shift applied alongside resize (Phase B.6.1).
+     * Used by edge/corner handle drags to keep the opposite edge
+     * anchored. e.g. dragging the right edge to grow width: the LEFT
+     * edge must stay put → tilemap center.x shifts right by half the
+     * width delta → `transformDelta.x = delta/2`. Without this, the
+     * tilemap would grow symmetrically around center (Figma's symmetric
+     * resize via Alt-drag); we want one-edge-anchored as the default
+     * (matches Photoshop / Aseprite canvas resize).
+     *
+     * Number-input resize (B.6) sends no transformDelta → symmetric
+     * grow/shrink around center. Handle-drag resize (B.6.1) computes
+     * and sends transformDelta to anchor the opposite edge.
+     */
+    transformDelta?: {
+        x: number;
+        y: number;
+    };
+};
+export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage | EditorSetEditModeMessage | EditorAssetUpdateMessage | EditorSetDebugOverlayMessage | EditorEditPrefabMessage | EditorPatchRuleMessage | EditorSetTilemapToolMessage | EditorEditTilemapMessage;
+export interface EditorSceneLoadedMessage {
+    type: 'umicat:editor:sceneLoaded';
+    sceneId: string;
+    /**
+     * Discriminator (slice 5+). 'world' (default for back-compat) is the
+     * world scene; 'hud' is the HUD overlay scene. SDK posts one message per
+     * scene type when entering edit mode, so the host can populate both
+     * Hierarchy / Inspector drafts and switch between them via the
+     * World/HUD toggle without a fresh SDK round-trip.
+     */
+    mode?: 'world' | 'hud';
+    /** Snapshot of the scene file's current entities. */
+    sceneFile: unknown;
+    /**
+     * Snapshot of the manifest (asset table + scene list). Slice 3+ — home-ui
+     * needs this to mutate the manifest when drag-to-place adds a new asset.
+     */
+    manifest?: unknown;
+}
+export interface EditorSelectionPickedMessage {
+    /** Pointer-down on an entity in the canvas — host should update selection. */
+    type: 'umicat:editor:pickEntity';
+    entityId: string | null;
+    /**
+     * When the picked entity is a runtime-spawned prefab instance (tagged
+     * `entityPrefabId` by `spawnPrefab`), the source prefab id — slice 11 B.5
+     * / editor P0.2. Host uses this to route the click to the Prefab
+     * Inspector instead of the Entity Inspector. Editing one instance is
+     * editing the prefab type (= all instances), so the visible Inspector
+     * scope matches the change scope.
+     *
+     * Absent on authored scene entities (those have a real record in
+     * `sceneFile.entities[]` and edit per-instance).
+     */
+    prefabId?: string;
+    /** Modifier keys at pointer-down so host can decide single/toggle/range. */
+    modifiers: {
+        shift: boolean;
+        cmdOrCtrl: boolean;
+        alt: boolean;
+    };
+}
+export interface EditorDragEndMessage {
+    /** Pointer-up after dragging an entity. delta is total movement in world coords. */
+    type: 'umicat:editor:dragEnd';
+    entityId: string;
+    /** Position before drag started. */
+    before: {
+        x: number;
+        y: number;
+    };
+    /** Position at release. */
+    after: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Editor keyboard shortcut intercepted inside the iframe (user clicked the
+ * canvas, so focus is on the iframe and the host window doesn't see the
+ * native keydown). The SDK forwards a small allowlist back to the host.
+ */
+export interface EditorShortcutMessage {
+    type: 'umicat:editor:shortcut';
+    action: 'undo' | 'redo' | 'save' | 'delete';
+}
+/**
+ * The selected entity's DOM screen rect (slice 4 — popover anchoring).
+ *
+ * Emitted on selection change, drag-end, and pan/zoom — NOT per frame. The
+ * host uses this to anchor the floating ✨ button + InlineAIPopover next
+ * to the entity. Coords are relative to the iframe element (not the
+ * entity's world coords); the host adds the iframe's own bounding rect to
+ * land in viewport space. Sent with `null` when nothing is selected, so
+ * the host can hide the ✨ button.
+ *
+ * Slice 4 only handles single-select. Multi-select (slice 4.5) will pass
+ * the union bounding box.
+ */
+export interface EditorSelectionRectMessage {
+    type: 'umicat:editor:selectionRect';
+    entityId: string | null;
+    /** null when nothing is selected. */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
+/**
+ * Editor camera state (P1 infinite canvas — 2026-05-17).
+ *
+ * Posted by the SDK after every pan / zoom action — either host-driven
+ * (via `umicat:editor:panZoom`) or SDK-driven (mouse-wheel zoom in the
+ * canvas, middle-button drag, space+drag). The host uses it to render
+ * the zoom percentage indicator + "reset to 100%" button in the iframe
+ * toolbar, and to compute which entities are off-screen for the
+ * Hierarchy panel's dim-when-outside-viewport hint.
+ *
+ * `viewportWorld` is the world-coord rectangle currently visible inside
+ * the iframe — `scrollX / scrollY` plus the canvas dimensions divided
+ * by zoom. Convenient for the host so it doesn't have to know canvas
+ * size or zoom math.
+ *
+ * Fired only in world mode — HUD has an identity camera; pan/zoom is
+ * not meaningful there.
+ */
+export interface EditorCameraStateMessage {
+    type: 'umicat:editor:cameraState';
+    zoom: number;
+    scrollX: number;
+    scrollY: number;
+    viewportWorld: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Tilemap stroke completed (slice 6 Phase B — pointer-up after brush /
+ * eraser / rect / fill).
+ *
+ * Sent by the SDK after every painter stroke so the host can:
+ *   1. Push a command onto the undo stack (whole stroke = ONE undo step)
+ *   2. Mutate the cached scene draft so the next flush persists the change
+ *
+ * The SDK already applied the op locally before posting — so the iframe is
+ * already showing the painted cells. This message exists for undo +
+ * persistence, NOT live preview (mirrors how `dragEnd` works).
+ */
+export interface EditorTilemapEditedMessage {
+    type: 'umicat:editor:tilemapEdited';
+    entityId: string;
+    /** The forward op (replay on redo, reverse-derive on undo). */
+    op: TilemapEditOp;
+    /**
+     * Per-cell prior values that the op overwrote — host stores these to
+     * build the inverse op for undo. For paint/erase, indices match `op.cells`;
+     * for fillRect/bucketFill, this is a flat list of every cell the op
+     * changed (in row-major order from top-left of the affected region).
+     */
+    previousCells: Array<{
+        x: number;
+        y: number;
+        index: number | null;
+    }>;
+}
+/**
+ * Tile picked from the canvas (slice 6 Phase B.4 — Picker / eyedropper tool).
+ *
+ * Fires on pointerdown when the active tool is `picker`. The SDK reads the
+ * cell's current tile index and posts this message; the host's painter UI
+ * sets it as the active tile + auto-switches the tool back to brush (matches
+ * Photoshop / Aseprite eyedropper convention — pick once, paint next).
+ *
+ * `tileIndex: null` means the picked cell is empty.
+ */
+export interface EditorTilemapTilePickedMessage {
+    type: 'umicat:editor:tilemapTilePicked';
+    entityId: string;
+    layerId: string;
+    tileIndex: number | null;
+}
+export type EditorSdkToHostMessage = EditorSceneLoadedMessage | EditorSelectionPickedMessage | EditorDragEndMessage | EditorShortcutMessage | EditorSelectionRectMessage | EditorRulesLoadedMessage | EditorCameraStateMessage | EditorTilemapEditedMessage | EditorTilemapTilePickedMessage;
+export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list' | 'realtime.getToken';
+export interface SavesGetParams {
+    key: string;
+}
+export interface SavesGetResult {
+    value: unknown | null;
+    version: number | null;
+}
+export interface SavesSetParams {
+    key: string;
+    value: unknown;
+    ifVersion?: number;
+}
+export interface SavesSetResult {
+    version: number;
+}
+export interface SavesDeleteParams {
+    key: string;
+}
+export type SavesDeleteResult = {
+    deleted: boolean;
+};
+export interface SavesListResult {
+    keys: string[];
+}
+export interface GameDataGetParams {
+    key: string;
+}
+export interface GameDataGetResult {
+    value: unknown | null;
+    version: number | null;
+}
+export interface GameDataSetParams {
+    key: string;
+    value: unknown;
+    ifVersion?: number;
+}
+export interface GameDataSetResult {
+    version: number;
+}
+export interface GameDataDeleteParams {
+    key: string;
+}
+export type GameDataDeleteResult = {
+    deleted: boolean;
+};
+export interface GameDataListResult {
+    keys: string[];
+}
+export interface RealtimeGetTokenParams {
+    /** Opaque, forwarded to server-side auth (future use). */
+    purpose?: string;
+}
+export interface RealtimeGetTokenResult {
+    token: string;
+    /** Epoch millis when the token expires. */
+    expiresAt: number;
+}