@umicat/phaser-sdk 1.0.0

package/dist/core/Transport.d.ts

@@ -0,0 +1,28 @@
+import type { UmicatUser } from '../protocol.js';
+/**
+ * Low-level transport for platform RPC calls. Swapped per host.
+ *
+ * Current implementations:
+ *   - PostMessageTransport: iframe hosted inside umicat-home-ui
+ *   - LocalStorageTransport: game running standalone (no host, no user)
+ *
+ * Future implementations (not shipped):
+ *   - DiscordTransport: game running as a Discord Activity
+ */
+export interface Transport {
+    readonly kind: TransportKind;
+    readonly user: UmicatUser | null;
+    readonly gameId: string;
+    /**
+     * Endpoint for umicat-realtime-service (WebSocket URL). Set by the host
+     * during handshake when multiplayer is enabled. Absent in standalone mode —
+     * `umicat.rooms.*` is unavailable in that case.
+     */
+    readonly realtimeUrl?: string;
+    call<T = unknown>(method: string, params?: unknown): Promise<T>;
+}
+export type TransportKind = 'umicat-home-ui' | 'standalone' | 'discord';
+export declare class RpcError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}

package/dist/core/Transport.js

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

package/dist/core/Umicat.d.ts

@@ -0,0 +1,45 @@
+import type { TransportKind } from './Transport.js';
+import { SavesModule } from '../saves/SavesModule.js';
+import { GameDataModule } from '../gamedata/GameDataModule.js';
+import { RealtimeModule } from '../realtime/RealtimeModule.js';
+import type { UmicatUser } from '../protocol.js';
+export interface UmicatInitOptions {
+    /** Handshake timeout in ms when running inside a host. Default 5000. */
+    handshakeTimeoutMs?: number;
+    /**
+     * Game ID used for the localStorage fallback. Ignored when connected to a
+     * host (the host provides the authoritative gameId). Default 'standalone'.
+     */
+    standaloneGameId?: string;
+}
+/**
+ * Umicat platform services bound to the current (game, user).
+ *
+ * The public API is host-agnostic. Under the hood, `Umicat.init()` detects the
+ * host (home-ui iframe, Discord Activity, or standalone) and picks the right
+ * transport. Games should not care which one is active.
+ */
+export declare class Umicat {
+    private transport;
+    readonly saves: SavesModule;
+    readonly gameData: GameDataModule;
+    readonly rooms: RealtimeModule;
+    private constructor();
+    /** The current authenticated user, or `null` if anonymous / standalone. */
+    get user(): UmicatUser | null;
+    get isAuthenticated(): boolean;
+    /** Stable game identifier issued by the host. May be a placeholder when standalone. */
+    get gameId(): string;
+    /** Which transport Umicat.init() selected. Useful for debugging. */
+    get host(): TransportKind;
+    /**
+     * Initialize the SDK. Detects the host and negotiates identity.
+     *
+     * Resolution order:
+     *   1. If embedded in a window that responds to the Umicat handshake → PostMessageTransport
+     *   2. Otherwise → LocalStorageTransport (anonymous, local-only saves)
+     *
+     * Discord Activity support is designed for but not shipped in this version.
+     */
+    static init(options?: UmicatInitOptions): Promise<Umicat>;
+}

package/dist/core/Umicat.js

@@ -0,0 +1,60 @@
+import { PostMessageTransport } from './transports/PostMessageTransport.js';
+import { LocalStorageTransport } from './transports/LocalStorageTransport.js';
+import { SavesModule } from '../saves/SavesModule.js';
+import { GameDataModule } from '../gamedata/GameDataModule.js';
+import { RealtimeModule } from '../realtime/RealtimeModule.js';
+// Kept in sync with package.json on each publish.
+const SDK_VERSION = '0.2.8';
+/**
+ * Umicat platform services bound to the current (game, user).
+ *
+ * The public API is host-agnostic. Under the hood, `Umicat.init()` detects the
+ * host (home-ui iframe, Discord Activity, or standalone) and picks the right
+ * transport. Games should not care which one is active.
+ */
+export class Umicat {
+    constructor(transport) {
+        this.transport = transport;
+        // Saves are per-user. When the viewer is anonymous, route save calls to
+        // localStorage even if a host is attached — the backend requires auth,
+        // so forwarding would 401. Games see the same `umicat.saves` API either
+        // way and don't have to branch on auth state.
+        const savesTransport = transport.user === null
+            ? new LocalStorageTransport(transport.gameId || 'anonymous')
+            : transport;
+        this.saves = new SavesModule(savesTransport);
+        // gameData is game-scope: reads are public (anonymous OK), only writes
+        // need auth. The primary transport handles both; if it's a LocalStorage
+        // fallback (standalone mode) that also works — the module speaks the
+        // same RPC interface.
+        this.gameData = new GameDataModule(transport);
+        // Multiplayer requires a realtime endpoint from the host. When absent
+        // (standalone or a host without multiplayer), methods throw a clear
+        // REALTIME_UNAVAILABLE error rather than silently misbehaving.
+        this.rooms = new RealtimeModule(transport, transport.realtimeUrl);
+    }
+    /** The current authenticated user, or `null` if anonymous / standalone. */
+    get user() { return this.transport.user; }
+    get isAuthenticated() { return this.transport.user !== null; }
+    /** Stable game identifier issued by the host. May be a placeholder when standalone. */
+    get gameId() { return this.transport.gameId; }
+    /** Which transport Umicat.init() selected. Useful for debugging. */
+    get host() { return this.transport.kind; }
+    /**
+     * Initialize the SDK. Detects the host and negotiates identity.
+     *
+     * Resolution order:
+     *   1. If embedded in a window that responds to the Umicat handshake → PostMessageTransport
+     *   2. Otherwise → LocalStorageTransport (anonymous, local-only saves)
+     *
+     * Discord Activity support is designed for but not shipped in this version.
+     */
+    static async init(options = {}) {
+        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5000;
+        const standaloneGameId = options.standaloneGameId ?? 'standalone';
+        const pm = await PostMessageTransport.connect(handshakeTimeoutMs, SDK_VERSION);
+        if (pm)
+            return new Umicat(pm);
+        return new Umicat(new LocalStorageTransport(standaloneGameId));
+    }
+}

package/dist/core/UmicatGame.d.ts

@@ -0,0 +1,43 @@
+import Phaser from 'phaser';
+import { type Orientation } from '../orientation.js';
+import { RenderScriptModule } from '../scene/renderScripts.js';
+interface UmicatGameBaseOptions {
+    /** Phaser scene classes to register */
+    scenes: (new (...args: any[]) => Phaser.Scene)[];
+    /** Background color (default: '#1a1a2e') */
+    backgroundColor?: string;
+    /** Enable pixel art rendering (default: false) */
+    pixelArt?: boolean;
+    /** Custom physics config (default: arcade with no gravity) */
+    physics?: Phaser.Types.Core.PhysicsConfig;
+    /** Phaser plugin registrations (e.g. `phaser3-rex-plugins` virtual joystick) */
+    plugins?: Phaser.Types.Core.PluginObject;
+    /**
+     * Map of render-script paths → modules that export `render(g, params)`.
+     * Templates build this via `import.meta.glob('./visuals/*.ts', { eager: true })`.
+     * Used by `code-rendered` entities and consumed inside `loadWorldScene`.
+     * Optional — games without code-rendered visuals can omit it.
+     */
+    renderScripts?: Record<string, RenderScriptModule>;
+}
+/**
+ * Either pass `orientation` (preset dims from ORIENTATION_DIMENSIONS) OR
+ * explicit `width`/`height` — not both. The TS union enforces this at
+ * compile time so games can't drift out of the orientation presets by
+ * accident.
+ */
+export type UmicatGameOptions = (UmicatGameBaseOptions & {
+    orientation: Orientation;
+    width?: never;
+    height?: never;
+}) | (UmicatGameBaseOptions & {
+    width: number;
+    height: number;
+    orientation?: never;
+});
+/**
+ * Create an Umicat-enhanced Phaser game instance.
+ * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
+ */
+export declare function createUmicatGame(options: UmicatGameOptions): Phaser.Game;
+export {};

package/dist/core/UmicatGame.js

@@ -0,0 +1,64 @@
+import Phaser from 'phaser';
+import NinePatchPlugin from 'phaser3-rex-plugins/plugins/ninepatch-plugin.js';
+import { setupScreenshotListener } from '../screenshot/ScreenshotManager.js';
+import { setupRecordingListener } from '../recording/RecordingManager.js';
+import { setupEditorModeListener } from '../scene/EditorMode.js';
+import { ORIENTATION_DIMENSIONS } from '../orientation.js';
+import { setRenderScriptRegistry, } from '../scene/renderScripts.js';
+import { UmicatHudScene } from '../scene/HudRuntime.js';
+/**
+ * Create an Umicat-enhanced Phaser game instance.
+ * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
+ */
+export function createUmicatGame(options) {
+    const { width, height } = 'orientation' in options && options.orientation
+        ? ORIENTATION_DIMENSIONS[options.orientation]
+        : { width: options.width, height: options.height };
+    // Auto-register rex-plugins NinePatch so HUD widgets with 9-slice asset
+    // metadata (`Asset.ninePatch`) can scale without corner distortion. Plugin
+    // exposes `scene.add.rexNinePatch(...)` factory; HudRuntime calls it on
+    // demand. Merged with any user-supplied `plugins.global` so existing
+    // rexVirtualJoystick / rexUI registrations keep working.
+    const ninePatchEntry = {
+        key: 'rexNinePatchPlugin',
+        plugin: NinePatchPlugin,
+        start: true,
+    };
+    const plugins = {
+        ...(options.plugins ?? {}),
+        global: [ninePatchEntry, ...(options.plugins?.global ?? [])],
+    };
+    const config = {
+        type: Phaser.AUTO,
+        backgroundColor: options.backgroundColor ?? '#1a1a2e',
+        scale: {
+            mode: Phaser.Scale.FIT,
+            autoCenter: Phaser.Scale.CENTER_BOTH,
+            width,
+            height,
+        },
+        render: {
+            preserveDrawingBuffer: true,
+        },
+        pixelArt: options.pixelArt ?? false,
+        physics: options.physics ?? {
+            default: 'arcade',
+            arcade: { gravity: { x: 0, y: 0 }, debug: false },
+        },
+        plugins,
+        // UmicatHudScene is auto-registered alongside the game's scenes so
+        // `loadWorldScene` can launch it when the active world scene's manifest
+        // entry sets `hud: '<id>'`. Registered at the end so the user's scenes
+        // own the boot order.
+        scene: [...options.scenes, UmicatHudScene],
+    };
+    const game = new Phaser.Game(config);
+    // Built-in integrations
+    setupScreenshotListener(game);
+    setupRecordingListener(game);
+    setupEditorModeListener(game);
+    if (options.renderScripts) {
+        setRenderScriptRegistry(game, options.renderScripts);
+    }
+    return game;
+}

package/dist/core/UmicatScene.d.ts

@@ -0,0 +1,19 @@
+import Phaser from 'phaser';
+/**
+ * Base scene class with common Umicat utilities.
+ * Extend this instead of Phaser.Scene for built-in helpers.
+ */
+export declare class UmicatScene extends Phaser.Scene {
+    /**
+     * Create a simple text button with hover effects.
+     */
+    protected createButton(x: number, y: number, text: string, style?: Phaser.Types.GameObjects.Text.TextStyle, onClick?: () => void): Phaser.GameObjects.Text;
+    /**
+     * Shake the camera briefly (e.g., on damage).
+     */
+    protected shakeCamera(duration?: number, intensity?: number): void;
+    /**
+     * Flash the camera briefly (e.g., on hit).
+     */
+    protected flashCamera(duration?: number, r?: number, g?: number, b?: number): void;
+}

package/dist/core/UmicatScene.js

@@ -0,0 +1,38 @@
+import Phaser from 'phaser';
+/**
+ * Base scene class with common Umicat utilities.
+ * Extend this instead of Phaser.Scene for built-in helpers.
+ */
+export class UmicatScene extends Phaser.Scene {
+    /**
+     * Create a simple text button with hover effects.
+     */
+    createButton(x, y, text, style, onClick) {
+        const btn = this.add.text(x, y, text, {
+            fontSize: '20px',
+            color: '#ffffff',
+            backgroundColor: '#4662D8',
+            padding: { x: 16, y: 8 },
+            ...style,
+        })
+            .setOrigin(0.5)
+            .setInteractive({ useHandCursor: true });
+        btn.on('pointerover', () => btn.setAlpha(0.8));
+        btn.on('pointerout', () => btn.setAlpha(1));
+        if (onClick)
+            btn.on('pointerdown', onClick);
+        return btn;
+    }
+    /**
+     * Shake the camera briefly (e.g., on damage).
+     */
+    shakeCamera(duration = 100, intensity = 0.01) {
+        this.cameras.main.shake(duration, intensity);
+    }
+    /**
+     * Flash the camera briefly (e.g., on hit).
+     */
+    flashCamera(duration = 100, r = 255, g = 255, b = 255) {
+        this.cameras.main.flash(duration, r, g, b);
+    }
+}

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

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

package/dist/core/transports/LocalStorageTransport.js

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

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

@@ -0,0 +1,28 @@
+import type { Transport } from '../Transport.js';
+import { type UmicatUser } from '../../protocol.js';
+/**
+ * Connects to a parent window that implements the Umicat RPC host protocol.
+ * Used when the game is loaded inside umicat-home-ui.
+ */
+export declare class PostMessageTransport implements Transport {
+    private parent;
+    readonly kind: "umicat-home-ui";
+    user: UmicatUser | null;
+    gameId: string;
+    realtimeUrl?: string;
+    private pending;
+    private seq;
+    private constructor();
+    /**
+     * Perform the handshake. Resolves once parent has replied with `umicat:init`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
+     */
+    static connect(timeoutMs?: number, sdkVersion?: string, helloRetryMs?: number): Promise<PostMessageTransport | null>;
+    private installResultListener;
+    call<T = unknown>(method: string, params?: unknown): Promise<T>;
+}

package/dist/core/transports/PostMessageTransport.js

@@ -0,0 +1,105 @@
+import { RpcError } from '../Transport.js';
+import { PROTOCOL_VERSION, } from '../../protocol.js';
+/**
+ * Connects to a parent window that implements the Umicat RPC host protocol.
+ * Used when the game is loaded inside umicat-home-ui.
+ */
+export class PostMessageTransport {
+    constructor(parent) {
+        this.parent = parent;
+        this.kind = 'umicat-home-ui';
+        this.user = null;
+        this.gameId = '';
+        this.pending = new Map();
+        this.seq = 0;
+    }
+    /**
+     * Perform the handshake. Resolves once parent has replied with `umicat:init`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
+     */
+    static async connect(timeoutMs = 5000, sdkVersion = '0.0.0', helloRetryMs = 200) {
+        if (typeof window === 'undefined' || window.parent === window)
+            return null;
+        const transport = new PostMessageTransport(window.parent);
+        const hello = {
+            type: 'umicat:hello',
+            protocolVersion: PROTOCOL_VERSION,
+            sdkVersion,
+        };
+        const init = await new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                window.removeEventListener('message', onMessage);
+                clearInterval(helloInterval);
+                clearTimeout(timeoutHandle);
+                resolve(value);
+            };
+            const onMessage = (event) => {
+                if (event.source !== window.parent)
+                    return;
+                const data = event.data;
+                if (!data || data.type !== 'umicat:init')
+                    return;
+                finish(data);
+            };
+            window.addEventListener('message', onMessage);
+            // Fire the first hello immediately, then keep retrying until init
+            // arrives or timeout fires. Retries are cheap (a postMessage with a
+            // small payload); the parent's RPC host replies on first valid hello.
+            transport.parent.postMessage(hello, '*');
+            const helloInterval = setInterval(() => {
+                transport.parent.postMessage(hello, '*');
+            }, helloRetryMs);
+            const timeoutHandle = setTimeout(() => finish(null), timeoutMs);
+        });
+        if (!init)
+            return null;
+        if (init.protocolVersion !== PROTOCOL_VERSION) {
+            console.warn('[UmicatSDK] protocol version mismatch', init.protocolVersion, PROTOCOL_VERSION);
+        }
+        transport.user = init.user;
+        transport.gameId = init.gameId;
+        transport.realtimeUrl = init.realtimeUrl;
+        transport.installResultListener();
+        return transport;
+    }
+    installResultListener() {
+        window.addEventListener('message', (event) => {
+            if (event.source !== this.parent)
+                return;
+            const data = event.data;
+            if (!data || data.type !== 'umicat:rpc.result')
+                return;
+            const pending = this.pending.get(data.id);
+            if (!pending)
+                return;
+            this.pending.delete(data.id);
+            if (data.ok)
+                pending.resolve(data.result);
+            else
+                pending.reject(new RpcError(data.error.code, data.error.message));
+        });
+    }
+    call(method, params) {
+        const id = `${++this.seq}-${Date.now()}`;
+        const message = { type: 'umicat:rpc', id, method, params };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.parent.postMessage(message, '*');
+            setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new RpcError('TIMEOUT', `RPC ${method} timed out`));
+                }
+            }, 10000);
+        });
+    }
+}

package/dist/editor/EditorBridge.d.ts

@@ -0,0 +1,114 @@
+import Phaser from 'phaser';
+import { AssetRecord } from '../scene/types.js';
+import { TilemapEditOp } from '../protocol.js';
+export declare function setupEditorBridge(game: Phaser.Game): void;
+/**
+ * FB.9a — return ALL entities at the given world coords, sorted by depth
+ * DESC (topmost first). Used by EditorOverlayScene's Alt+click handler
+ * to cycle through overlapping entities. When no Alt held, the regular
+ * hitTest (returning just topmost) handles normal selection.
+ */
+export declare function hitTestAll(game: Phaser.Game, worldX: number, worldY: number): Phaser.GameObjects.GameObject[];
+/**
+ * Apply pan/zoom to the world scene's camera + mirror to the editor
+ * overlay scene's camera so the overlay graphics (selection rect, world-
+ * bounds rect, hitbox debug) draw in the right world position.
+ *
+ * Scoped to world + overlay only — HUD has an identity camera by design
+ * (widgets are anchor-positioned to canvas edges), so panning/zooming it
+ * would visually rip HUD widgets off their anchors.
+ *
+ * Exported for `EditorOverlayScene` so the in-canvas wheel + middle-click
+ * + space+drag handlers route through the same mutation function as the
+ * host-driven `umicat:editor:panZoom` message.
+ */
+/**
+ * Apply pan/zoom to the editor camera (NOT the game's runtime camera).
+ *
+ * P1 infinite canvas (2026-05-17). Mutates `editorCam` on the world scene
+ * + the overlay scene's mirror. `cameras.main` (the game's runtime cam)
+ * is never touched in edit mode — the game's intended camera position is
+ * preserved exactly as the game code left it, and surfaces in the editor
+ * as a dashed "Camera" rect (drawn by `EditorOverlayScene.update`). This
+ * matches Godot 2D editor's "editor viewport vs Camera2D" split.
+ *
+ * Exported for `EditorOverlayScene` so the in-canvas wheel + middle-click
+ * + space+drag handlers route through the same mutation function as the
+ * host-driven `umicat:editor:panZoom` message. Renamed from the misleading
+ * `applyPanZoomToWorld` (which sounded like "pan the world camera").
+ */
+export declare function applyEditorPanZoom(game: Phaser.Game, msg: {
+    scrollX?: number;
+    scrollY?: number;
+    zoom?: number;
+    relative?: boolean;
+}): void;
+/**
+ * Back-compat alias for callers (e.g. older host messages, internal call
+ * sites) referencing the old name. Keep until we're sure nothing still
+ * relies on it.
+ */
+export declare const applyPanZoomToWorld: typeof applyEditorPanZoom;
+/**
+ * Post the editor camera's current state to the host so it can render the
+ * zoom indicator + reset button, and decide which Hierarchy entries are
+ * off-screen. Falls back to the game's cameras.main when editorCam isn't
+ * installed yet (race during enterEdit).
+ */
+export declare function postCameraState(game: Phaser.Game): void;
+/**
+ * Read-only access to the editor camera. Null when edit mode hasn't been
+ * entered yet OR was just exited. Used by `applyEditorPanZoom`,
+ * `postCameraState`, and the overlay scene's mirror in `create`.
+ */
+export declare function getEditorCamera(game: Phaser.Game): Phaser.Cameras.Scene2D.Camera | null;
+/**
+ * Apply one or more tilemap edit ops to the live Phaser TilemapLayer(s).
+ *
+ * Called from two paths:
+ *   1. Host pushes `umicat:editor:editTilemap` (agent writes, undo/redo
+ *      replay) — see EditorBridge.handleMessage dispatch.
+ *   2. SDK's pointer-up handler (live painter stroke) — calls this directly
+ *      after composing the stroke's accumulated cells into one op, before
+ *      posting `umicat:editor:tilemapEdited` to the host.
+ *
+ * Mirror of handleEditPrefab's pattern: lookup container in registry → find
+ * matching layer child by `tilemapLayerId` data tag → apply Phaser tilemap
+ * mutation API. Soft-fails (warn + skip) on missing entity / missing layer
+ * / out-of-bounds cell so a stale op doesn't crash the runtime.
+ */
+/**
+ * Apply tilemap edit ops to live runtime. Public because the editor's
+ * own drag-resize commit (in EditorOverlayScene) needs to apply the op
+ * locally before posting `tilemapEdited` for host undo recording —
+ * same pattern as brush/rect/fill commits (apply local, post for undo).
+ * Skipping the local apply leaves SDK runtime + host draft out of sync
+ * (host knows the new size, SDK keeps rendering old size → bounds snap-
+ * back UX).
+ *
+ * Async because addLayer ops can reference a fresh tileset whose
+ * texture hasn't loaded yet. Caller supplies optional `manifestAsset`
+ * (same pattern as createEntity's drag-to-place) — handler upserts
+ * cache + AWAITS texture load before invoking applyTilemapStructureOp.
+ * Without the await, addLayer's `textures.exists()` check fails on
+ * the in-flight load → skips layer creation → painter can't find
+ * layer → click falls through to drag-the-entity.
+ */
+export declare function handleEditTilemap(game: Phaser.Game, entityId: string, ops: TilemapEditOp[], manifestAsset?: AssetRecord): Promise<void>;
+/**
+ * Find the TilemapLayer tagged with `layerId` belonging to the given tilemap
+ * container. Layers live in scene root (not as container children) because
+ * Phaser's TilemapLayer doesn't inherit parent Container transforms — see
+ * `createTilemap` for the rationale. The container's data manager stashes
+ * a `tilemapLayers` array of refs so we can find them without a scene walk.
+ */
+export declare function findTilemapLayerById(container: Phaser.GameObjects.Container, layerId: string): Phaser.Tilemaps.TilemapLayer | null;
+/**
+ * Apply a single op to a live TilemapLayer using Phaser's native mutation
+ * APIs. All ops are in-place — no full re-render needed. Out-of-bounds
+ * cells are tolerated by Phaser's `putTileAt` (no-op outside layer bounds).
+ *
+ * The optional `asset` arg is required for `autotilePaint` (the only op
+ * that needs to resolve a terrain's ruleMap); other ops ignore it.
+ */
+export declare function applyTilemapOp(layer: Phaser.Tilemaps.TilemapLayer, op: TilemapEditOp, asset?: AssetRecord | null): void;