@umicat/phaser-sdk 1.0.0

package/dist/editor/EditorBridge.js

@@ -0,0 +1,2608 @@
+// 0.2.76 — no-op version bump to validate session-server's new
+// "chore: update @umicat/phaser-sdk to <version>" commit message in
+// the History panel. Refresh the browser after this lands and the
+// commit should show the version inline. Remove this comment in the
+// next functional patch.
+import Phaser from 'phaser';
+import { getEntityRegistry } from '../scene/EntityRegistry.js';
+import { applyAssetHitbox, applyTilesetAnimations, applyTilesetTileMetadata, applyTrackedHitArea, parseColor, resetTilesetAnimationsToRoot, spawnEntity } from '../scene/spawnEntity.js';
+import { applyAutotile, findTerrain, getAutotileKind, invalidateAutotileCells } from '../scene/autotile.js';
+import { resolveRenderScript } from '../scene/renderScripts.js';
+import { getManifest } from '../scene/SceneLoader.js';
+import { getRules, patchRule } from '../scene/Rules.js';
+import { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './EditorOverlayScene.js';
+import { getEditorState, setEditorActive, setSelection, getSelection, getEditorMode, setEditorMode, setDebugOverlayState, setTilemapToolState, } from './EditorState.js';
+import { applyHudPatch, createHudEntityInScene, deleteHudEntityFromScene, findHudRegistry, findHudSceneFile, UMICAT_HUD_SCENE_KEY, } from '../scene/HudRuntime.js';
+/**
+ * EditorBridge wires the host (home-ui) to the iframe's Phaser game during
+ * Edit mode. Manages:
+ *
+ * - Entering / exiting edit mode (pauses non-Boot scenes; launches the overlay)
+ * - Applying entity patches from the host (Inspector / Undo edits)
+ * - Tracking selection (host pushes; overlay reads)
+ * - Pan/zoom of the editor camera
+ * - Posting pickEntity + dragEnd back to the host
+ *
+ * Wired by `setupEditorModeListener` in EditorMode.ts.
+ */
+const BOOT_SCENE_KEYS = new Set(['BootScene', 'Boot']);
+const EDITOR_LISTENER_FLAG = '__unboxyEditorBridgeListener';
+export function setupEditorBridge(game) {
+    const flagged = game;
+    if (flagged[EDITOR_LISTENER_FLAG])
+        return;
+    flagged[EDITOR_LISTENER_FLAG] = true;
+    // Register the overlay scene class so it can be launched when needed.
+    // (Adding a class to game.scene.add() registers it without starting it.)
+    game.scene.add(EDITOR_OVERLAY_KEY, EditorOverlayScene, false);
+    window.addEventListener('message', (event) => {
+        const data = event.data;
+        if (!data || typeof data !== 'object' || typeof data.type !== 'string')
+            return;
+        if (!data.type.startsWith('umicat:editor:'))
+            return;
+        handleMessage(game, data);
+    });
+}
+function handleMessage(game, msg) {
+    switch (msg.type) {
+        case 'umicat:editor:enter':
+            enterEdit(game);
+            break;
+        case 'umicat:editor:exit':
+            exitEdit(game);
+            break;
+        case 'umicat:editor:getScene':
+            postSceneSnapshot(game);
+            break;
+        case 'umicat:editor:applyEdit':
+            void applyEdit(game, msg.entityId, msg.patch, msg.manifestAsset);
+            break;
+        case 'umicat:editor:setSelection':
+            setSelection(game, msg.entityIds[0] ?? null);
+            postSelectionRect(game);
+            break;
+        case 'umicat:editor:panZoom':
+            // applyEditorPanZoom now posts selectionRect itself, so no need
+            // to chain it here. RAF-coalesced anyway.
+            applyPanZoomToWorld(game, msg);
+            break;
+        case 'umicat:editor:createEntity':
+            void createEntity(game, msg.entity, msg.manifestAsset);
+            break;
+        case 'umicat:editor:deleteEntity':
+            deleteEntity(game, msg.entityId);
+            postSelectionRect(game);
+            break;
+        case 'umicat:editor:setEditMode':
+            // Slice 5 — World/HUD toggle. Mode change is purely state; the host
+            // already has both scene snapshots from enterEdit and just switches
+            // which one its UI renders. Selection may carry over between modes,
+            // but selectionRect re-posts so the ✨ button moves to the active
+            // mode's selected entity (or hides if none).
+            setEditorMode(game, msg.mode);
+            setSelection(game, null);
+            postSelectionRect(game);
+            // P1 infinite canvas — HUD scene visibility tied to mode: hidden
+            // in world edit (so it doesn't float wrong over pan/zoom view),
+            // shown in HUD edit (since that's the editing surface).
+            setHudVisibility(game, msg.mode === 'hud');
+            break;
+        case 'umicat:editor:assetUpdate':
+            // Slice 8 — Asset-level live update for hitbox / depthAnchor edits.
+            void handleAssetUpdate(game, msg.asset);
+            break;
+        case 'umicat:editor:setDebugOverlay':
+            // Slice 8 — "Show hitboxes" debug overlay toggle.
+            setDebugOverlay(game, { showHitboxes: msg.showHitboxes });
+            break;
+        case 'umicat:editor:editPrefab':
+            // Slice 11 Phase B.5 / editor P0.2 — prefab live-edit.
+            handleEditPrefab(game, msg.prefabId, msg.patch);
+            break;
+        case 'umicat:editor:patchRule':
+            // Slice 11 Phase B.5 / editor P0.3 — rule live-edit.
+            handlePatchRule(game, msg.path, msg.value);
+            break;
+        case 'umicat:editor:setTilemapTool':
+            // Slice 6 Phase B — tilemap painter active state push.
+            handleSetTilemapTool(game, msg);
+            break;
+        case 'umicat:editor:editTilemap':
+            // Slice 6 Phase B — host-driven tilemap mutation (agent writes,
+            // undo/redo replay, addLayer with new tileset). Live painter
+            // strokes go SDK→host via `tilemapEdited` instead — this path is
+            // for everything else. handleEditTilemap is async (awaits asset
+            // load when manifestAsset present); fire-and-forget the promise.
+            void handleEditTilemap(game, msg.entityId, msg.ops, msg.manifestAsset);
+            break;
+    }
+}
+// --- Enter / exit ---------------------------------------------------------
+function enterEdit(game) {
+    // Brute-force idempotent enter (2026-05-17): edit→play→edit was still
+    // breaking after the conditional-cleanup fix in 0.2.79 — the cleanup
+    // only ran when `state.active` was already true. But the bug also
+    // manifests when state is false but Phaser's scale.scaleMode /
+    // gameSize / camera viewports got out of sync due to the previous
+    // edit/play cycle. Solution: ALWAYS run uninstall + restore first,
+    // unconditionally — they're idempotent no-ops when there's no stale
+    // state, and they reset Phaser to a clean baseline when there IS
+    // stale state. Net cost: a few cheap getter/setter calls per enter.
+    uninstallVoidFill(game);
+    uninstallEditorCameras(game);
+    restoreCanvasAfterEditor(game);
+    setEditorActive(game, true);
+    pauseActiveNonEditor(game);
+    // P1 infinite canvas — expand the Phaser canvas to fill its container
+    // (host's iframe). Without this, the editor surface stays locked to
+    // the game's intrinsic aspect ratio (720×1280 portrait, etc.) with
+    // letterbox bars around it that the user can't pan into — defeats the
+    // "whole iframe = world map" mental model. Switches scale mode to
+    // RESIZE; canvas grows; editor cam viewport tracks the new canvas size.
+    // Game's logical world stays at its declared size; editor just has
+    // more "screen area" to show the world + void around it.
+    expandCanvasForEditor(game);
+    // P1 infinite canvas (correct architecture, 2026-05-17): editor view
+    // is a SEPARATE camera over the world, NOT the game's runtime camera.
+    // Matches Godot 2D editor's "editor viewport vs Camera2D" split.
+    installEditorCameras(game);
+    // Add the "editor void" grey fill into the world scene at very low
+    // depth so it renders BELOW entities (drag-to-place outside world
+    // bounds now shows the sprite instead of being covered by overlay
+    // grey). Runs after install so we know which world scene + which
+    // editor cam are active.
+    installVoidFill(game);
+    // Slice 6 Phase B — show tilemap grid sketches (hidden by default in
+    // Play mode). `setTilemapGridsVisible` walks every tilemap container
+    // in the registry and toggles its grid child. Called again on exitEdit
+    // with `false`.
+    setTilemapGridsVisible(game, true);
+    // Slice 6 Phase F — reset animated tiles to their root indices. Scenes
+    // are paused via `setActive(false)` in edit mode → animation UPDATE
+    // handlers don't fire → cells freeze on whatever frame was current.
+    // Reset so the editor shows the static authored frame (matches
+    // layer.data). exitEdit doesn't need a paired re-arm — the next UPDATE
+    // tick after scene resume re-runs `applyTilesetAnimations` cleanup-
+    // and-rebuild via the post-paint metadata re-application path.
+    resetAllTilesetAnimations(game);
+    // World edit mode hides HUD scene — HUD widgets are canvas-relative
+    // (anchor-positioned to edges) and would visually float wrong when the
+    // editor pans/zooms the world view. HUD edit mode shows it normally
+    // and treats HUD as the editing surface. Toggle in setEditorMode handler.
+    setHudVisibility(game, getEditorMode(game) === 'hud');
+    // Launch the overlay AFTER pausing world scenes so it sits on top in render
+    // order (Phaser renders scenes in the order they were started).
+    const overlayInit = buildOverlayInit(game);
+    if (!game.scene.isActive(EDITOR_OVERLAY_KEY)) {
+        game.scene.run(EDITOR_OVERLAY_KEY, overlayInit);
+    }
+    // Send the initial scene snapshot so home-ui can populate Hierarchy /
+    // Inspector without a separate getScene round-trip.
+    postSceneSnapshot(game);
+    // Race-window catch: when home-ui sends `enter` right after iframe load
+    // (which is exactly the auto-flush rebuild path), BootScene may still be
+    // in preload / GameScene may not have started, so the synchronous pause
+    // above had nothing to pause and the snapshot found no scene file in
+    // cache yet. Re-attempt for ~3 seconds. Each attempt is cheap and stops
+    // automatically once the user exits edit mode.
+    let attempts = 0;
+    const reattempt = () => {
+        if (!getEditorState(game).active)
+            return;
+        pauseActiveNonEditor(game);
+        if (!hasPostedSnapshot(game))
+            postSceneSnapshot(game);
+        attempts += 1;
+        if (attempts < 30)
+            setTimeout(reattempt, 100);
+    };
+    setTimeout(reattempt, 100);
+}
+function pauseActiveNonEditor(game) {
+    // P1 infinite canvas (2026-05-17) — use `setActive(false)` instead of
+    // `pause()` so scenes STOP updating (game logic frozen) but KEEP
+    // rendering. `pause()` halts both — which makes the editor camera blind
+    // to entity positions because the world scene's renderer is also paused.
+    // We need render to continue so editor cam pan/zoom can show the entities
+    // at correctly-transformed positions.
+    //
+    // Pair this with `physics.pause()` + `tweens.pauseAll()` + `time.paused`
+    // because setActive(false) on its own doesn't halt those — the Arcade
+    // body would keep stepping if untouched, entities animate during edit,
+    // etc.
+    for (const scene of game.scene.getScenes(true)) {
+        const key = scene.scene.key;
+        if (BOOT_SCENE_KEYS.has(key))
+            continue;
+        if (key === EDITOR_OVERLAY_KEY)
+            continue;
+        if (!scene.scene.isActive())
+            continue;
+        scene.scene.setActive(false);
+        if (scene.physics)
+            scene.physics.pause();
+        scene.tweens.pauseAll();
+        scene.time.paused = true;
+    }
+}
+/**
+ * Inverse of `pauseActiveNonEditor` — resumes update + physics + tweens +
+ * timers on every scene we paused. Called in `exitEdit`.
+ */
+function resumeActiveNonEditor(game) {
+    for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (BOOT_SCENE_KEYS.has(key))
+            continue;
+        if (key === EDITOR_OVERLAY_KEY)
+            continue;
+        if (scene.scene.isActive())
+            continue;
+        scene.scene.setActive(true);
+        if (scene.physics)
+            scene.physics.resume();
+        scene.tweens.resumeAll();
+        scene.time.paused = false;
+    }
+}
+function exitEdit(game) {
+    if (!getEditorState(game).active)
+        return;
+    setEditorActive(game, false);
+    setSelection(game, null);
+    // Allow next enter to re-post the snapshot (scene file may have changed).
+    delete game[SNAPSHOT_POSTED_FLAG];
+    if (game.scene.isActive(EDITOR_OVERLAY_KEY)) {
+        game.scene.stop(EDITOR_OVERLAY_KEY);
+    }
+    // P1 infinite canvas — tear down editor cameras + void fill + restore
+    // game cam visibility + restore canvas scale + restore HUD scene
+    // visibility BEFORE resuming scenes so the first resumed frame
+    // renders through the game's real cameras at the game's intended
+    // canvas size.
+    uninstallVoidFill(game);
+    setTilemapGridsVisible(game, false);
+    uninstallEditorCameras(game);
+    restoreCanvasAfterEditor(game);
+    setHudVisibility(game, true);
+    resumeActiveNonEditor(game);
+}
+/**
+ * Slice 6 Phase B — toggle the tilemap entities' grid sketch visibility.
+ * The grid is an editor-only visualization aid (helps users see tile
+ * boundaries on empty / sparsely-painted tilemaps); it bleeds into Play
+ * mode if not toggled off. Walks every tilemap container in the world
+ * scene's registry and finds the tagged grid Graphics child.
+ */
+function setTilemapGridsVisible(game, visible) {
+    const scene = findWorldScene(game);
+    if (!scene)
+        return;
+    const registry = getEntityRegistry(scene);
+    if (!registry)
+        return;
+    for (const go of registry.all()) {
+        if (go.getData('entityKind') !== 'tilemap')
+            continue;
+        const container = go;
+        for (const child of container.list) {
+            if (child.getData?.('unboxyTilemapGrid')) {
+                child.setVisible(visible);
+            }
+        }
+    }
+}
+/**
+ * Phase F — reset every animated tile to its root index across all
+ * tilemap entities in the active world scene. Called by `enterEdit` so
+ * the editor view always shows the authored (static) frame instead of
+ * whatever was currently visible when the user toggled into edit mode.
+ *
+ * Doesn't uninstall the per-frame UPDATE handler — scene pause prevents
+ * it from firing, and exitEdit lets it resume naturally on the next
+ * tick (cells re-swap from elapsed-time math).
+ */
+function resetAllTilesetAnimations(game) {
+    const scene = findWorldScene(game);
+    if (!scene)
+        return;
+    const registry = getEntityRegistry(scene);
+    if (!registry)
+        return;
+    for (const go of registry.all()) {
+        if (go.getData('entityKind') !== 'tilemap')
+            continue;
+        resetTilesetAnimationsToRoot(go);
+    }
+}
+function buildOverlayInit(game) {
+    const sceneFile = readActiveSceneFile(game);
+    // Fallback worldBounds for pure scene-as-code games (no scene file).
+    // Use the snapshot's intrinsic game dims so the white outline +
+    // selection math still work (outline at (0, 0, gameW, gameH)).
+    const snap = game[CANVAS_SCALE_SNAPSHOT_KEY];
+    const wbW = sceneFile?.world.width ?? snap?.gameWidth;
+    const wbH = sceneFile?.world.height ?? snap?.gameHeight;
+    return {
+        worldBounds: wbW != null && wbH != null
+            ? { x: 0, y: 0, width: wbW, height: wbH }
+            : undefined,
+        hitTest: (worldX, worldY) => hitTest(game, worldX, worldY),
+        hitTestAll: (worldX, worldY) => hitTestAll(game, worldX, worldY),
+        postPick: (entityId, modifiers, prefabId) => postToHost({
+            type: 'umicat:editor:pickEntity',
+            entityId,
+            modifiers,
+            prefabId,
+        }),
+        postDragEnd: (entityId, before, after) => postToHost({
+            type: 'umicat:editor:dragEnd',
+            entityId,
+            before,
+            after,
+        }),
+        postShortcut: (action) => postToHost({ type: 'umicat:editor:shortcut', action }),
+        // P1 infinite canvas — route in-canvas pan/zoom through the same
+        // function host-driven `umicat:editor:panZoom` uses, so cap + mirror
+        // logic stays in one place.
+        applyPanZoom: (msg) => applyPanZoomToWorld(game, msg),
+    };
+}
+// --- Snapshot -------------------------------------------------------------
+const SNAPSHOT_POSTED_FLAG = '__unboxyEditorSnapshotPostedFor';
+function postSceneSnapshot(game) {
+    const manifest = readActiveManifest(game);
+    const sceneFile = readActiveSceneFile(game);
+    if (sceneFile) {
+        postToHost({
+            type: 'umicat:editor:sceneLoaded',
+            sceneId: sceneFile.id,
+            mode: 'world',
+            sceneFile,
+            manifest,
+        });
+        game[SNAPSHOT_POSTED_FLAG] = sceneFile.id;
+    }
+    // Also post the HUD scene if attached + loaded. The host stashes both
+    // snapshots so the World/HUD toggle is purely a UI switch — no fresh
+    // SDK round-trip needed when the user flips it.
+    const hudFile = findHudSceneFile(game);
+    if (hudFile) {
+        postToHost({
+            type: 'umicat:editor:sceneLoaded',
+            sceneId: hudFile.id,
+            mode: 'hud',
+            sceneFile: hudFile,
+            manifest,
+        });
+    }
+    // P0.3 — also post the rules snapshot so the Rules panel can render
+    // without a separate fetch. Rules live on `scene.cache.json` (one tree
+    // per game, not per-scene), populated by `preloadRules` in BootScene.
+    // Empty `{}` is the valid "game has no rules.json" state.
+    postRulesSnapshot(game);
+    // P1 infinite canvas — initial camera state so host renders the zoom
+    // indicator at the right value from the moment Edit opens.
+    postCameraState(game);
+}
+/**
+ * Post the rules snapshot once, finding any non-Boot scene with a cached
+ * rules tree. The host stashes this as its baseline for the Rules form.
+ *
+ * P0.3 — `umicat:editor:rulesLoaded`. Tolerates a game with no rules at
+ * all (posts `{}`).
+ */
+function postRulesSnapshot(game) {
+    const scene = findWorldScene(game);
+    if (!scene)
+        return;
+    const rules = getRules(scene);
+    postToHost({ type: 'umicat:editor:rulesLoaded', rules });
+}
+// --- Selection rect (slice 4) ---------------------------------------------
+//
+// Emit the selected entity's DOM screen rect to the host so it can anchor
+// the ✨ button + popover next to the entity. Coalesce multiple calls
+// inside one RAF tick — Inspector spam (per-keystroke transform edits)
+// would otherwise spam the postMessage channel.
+const RECT_RAF_FLAG = '__unboxyEditorSelectionRectRafScheduled';
+function postSelectionRect(game) {
+    const bag = game;
+    if (bag[RECT_RAF_FLAG])
+        return;
+    bag[RECT_RAF_FLAG] = true;
+    // requestAnimationFrame runs after Phaser's render → bounds reflect the
+    // freshly-applied transform. Guarantees one emit per frame max.
+    if (typeof requestAnimationFrame === 'function') {
+        requestAnimationFrame(() => {
+            bag[RECT_RAF_FLAG] = false;
+            doPostSelectionRect(game);
+        });
+    }
+    else {
+        bag[RECT_RAF_FLAG] = false;
+        doPostSelectionRect(game);
+    }
+}
+function doPostSelectionRect(game) {
+    const id = getSelection(game);
+    if (!id) {
+        postToHost({ type: 'umicat:editor:selectionRect', entityId: null, rect: null });
+        return;
+    }
+    const registry = findRegistry(game);
+    const go = registry?.byId(id);
+    if (!go) {
+        postToHost({ type: 'umicat:editor:selectionRect', entityId: id, rect: null });
+        return;
+    }
+    const rect = computeScreenRect(game, go);
+    postToHost({ type: 'umicat:editor:selectionRect', entityId: id, rect });
+}
+/**
+ * Compute the entity's DOM screen rect — viewport pixels relative to the
+ * iframe's top-left. The host adds the iframe's bounding rect to translate
+ * into page coords.
+ *
+ * Path: world coords → camera transform → canvas pixels → iframe pixels.
+ * Phaser's Scale.FIT may letterbox/pillarbox the canvas inside the iframe,
+ * so we factor in the canvas's parent offset too.
+ */
+function computeScreenRect(game, go) {
+    // Pull entity-local bounds — same logic the editor uses for hit-test.
+    const hitW = go.getData('editorHitWidth');
+    const hitH = go.getData('editorHitHeight');
+    const positioned = go;
+    let entRect;
+    const liveBounds = readLiveTrackedBounds(go);
+    if (liveBounds) {
+        entRect = {
+            x: positioned.x + liveBounds.x,
+            y: positioned.y + liveBounds.y,
+            width: liveBounds.width,
+            height: liveBounds.height,
+        };
+    }
+    else if (typeof hitW === 'number' && typeof hitH === 'number') {
+        const offX = go.getData('editorHitOffsetX');
+        const offY = go.getData('editorHitOffsetY');
+        if (typeof offX === 'number' && typeof offY === 'number') {
+            entRect = {
+                x: positioned.x + offX,
+                y: positioned.y + offY,
+                width: hitW,
+                height: hitH,
+            };
+        }
+        else {
+            entRect = {
+                x: positioned.x - hitW / 2,
+                y: positioned.y - hitH / 2,
+                width: hitW,
+                height: hitH,
+            };
+        }
+    }
+    else {
+        const withBounds = go;
+        if (typeof withBounds.getBounds !== 'function')
+            return null;
+        const r = withBounds.getBounds();
+        entRect = { x: r.x, y: r.y, width: r.width, height: r.height };
+    }
+    // HUD mode — entity coords are already in canvas-pixel space (the HUD
+    // scene has identity camera). Skip the world→canvas camera transform.
+    let canvasX, canvasY, canvasW, canvasH;
+    if (getEditorMode(game) === 'hud') {
+        canvasX = entRect.x;
+        canvasY = entRect.y;
+        canvasW = entRect.width;
+        canvasH = entRect.height;
+    }
+    else {
+        // World mode — convert via the EDITOR camera (P1 infinite canvas).
+        // `cameras.main` is hidden during edit and its scroll/zoom never
+        // change while the user pans/zooms the editor — using it here pins
+        // the popover anchor to (0,0)/zoom=1 regardless of editor view,
+        // which is why the AI sparkle button only landed correctly at 100%
+        // / scroll(0,0). Editor cam IS what the user is looking through;
+        // its scroll/zoom track pan + pinch in real time, so popover
+        // follows the entity correctly. Falls back to cameras.main on the
+        // narrow boot-race window before editor cam is installed.
+        const cam = getEditorCamera(game) ?? (() => {
+            for (const scene of game.scene.getScenes(false)) {
+                const key = scene.scene.key;
+                if (BOOT_SCENE_KEYS.has(key))
+                    continue;
+                if (key === EDITOR_OVERLAY_KEY)
+                    continue;
+                if (key === UMICAT_HUD_SCENE_KEY)
+                    continue;
+                if (getEntityRegistry(scene))
+                    return scene.cameras.main;
+            }
+            return null;
+        })();
+        if (!cam)
+            return null;
+        // Include cam.x/cam.y — Phaser cam math is
+        //   canvas_pixel = (world - scroll) * zoom + viewport_offset
+        // The previous formula dropped `viewport_offset`, which is fine
+        // when setViewport(0, 0, ...) but breaks if any code path shifts
+        // the viewport. Defense-in-depth: read what's actually there.
+        canvasX = (entRect.x - cam.scrollX) * cam.zoom + cam.x;
+        canvasY = (entRect.y - cam.scrollY) * cam.zoom + cam.y;
+        canvasW = entRect.width * cam.zoom;
+        canvasH = entRect.height * cam.zoom;
+    }
+    // Convert logical canvas pixels → CSS pixels using the canvas's actual
+    // displayed size (avoids depending on which direction Phaser's displayScale
+    // goes — we just measure it). Canvas may be letterboxed/pillarboxed inside
+    // the iframe under Scale.FIT; getBoundingClientRect gives both the size
+    // and the offset.
+    const canvas = game.canvas;
+    if (!canvas || typeof canvas.getBoundingClientRect !== 'function')
+        return null;
+    const cssRect = canvas.getBoundingClientRect();
+    const logicalW = game.scale.width;
+    const logicalH = game.scale.height;
+    if (!logicalW || !logicalH)
+        return null;
+    const sx = cssRect.width / logicalW;
+    const sy = cssRect.height / logicalH;
+    return {
+        x: cssRect.left + canvasX * sx,
+        y: cssRect.top + canvasY * sy,
+        width: canvasW * sx,
+        height: canvasH * sy,
+    };
+}
+function readActiveManifest(game) {
+    for (const scene of game.scene.getScenes(false)) {
+        const cache = scene.cache.json;
+        const m = cache.entries?.entries?.['umicat:manifest'];
+        if (m)
+            return m;
+    }
+    return undefined;
+}
+function hasPostedSnapshot(game) {
+    return !!game[SNAPSHOT_POSTED_FLAG];
+}
+function readActiveSceneFile(game) {
+    // The active world scene cached its scene file in Phaser's JSON cache via
+    // SceneLoader. Pull it from there. We pick the first non-Boot scene we
+    // find with a JSON entry matching `umicat:scene:<id>`.
+    for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (BOOT_SCENE_KEYS.has(key))
+            continue;
+        if (key === EDITOR_OVERLAY_KEY)
+            continue;
+        // Scan cache for any 'umicat:scene:*' entry. There's typically one.
+        const cache = scene.cache.json;
+        const entries = cache.entries?.entries ?? {};
+        for (const cacheKey of Object.keys(entries)) {
+            if (cacheKey.startsWith('umicat:scene:')) {
+                const candidate = entries[cacheKey];
+                if (isWorldScene(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return null;
+}
+function isWorldScene(v) {
+    return !!v && typeof v === 'object' && v.type === 'world';
+}
+// --- Hit test -------------------------------------------------------------
+function hitTest(game, worldX, worldY) {
+    const registry = findRegistry(game);
+    if (!registry)
+        return null;
+    let topmost = null;
+    let topmostDepth = -Infinity;
+    for (const go of registry.all()) {
+        const r = entityHitRect(go);
+        if (!r)
+            continue;
+        if (worldX < r.x || worldX > r.x + r.width)
+            continue;
+        if (worldY < r.y || worldY > r.y + r.height)
+            continue;
+        const withDepth = go;
+        const depth = typeof withDepth.depth === 'number' ? withDepth.depth : 0;
+        if (depth >= topmostDepth) {
+            topmostDepth = depth;
+            topmost = go;
+        }
+    }
+    return topmost;
+}
+/**
+ * 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 function hitTestAll(game, worldX, worldY) {
+    const registry = findRegistry(game);
+    if (!registry)
+        return [];
+    const hits = [];
+    for (const go of registry.all()) {
+        const r = entityHitRect(go);
+        if (!r)
+            continue;
+        if (worldX < r.x || worldX > r.x + r.width)
+            continue;
+        if (worldY < r.y || worldY > r.y + r.height)
+            continue;
+        const withDepth = go;
+        const depth = typeof withDepth.depth === 'number' ? withDepth.depth : 0;
+        hits.push({ go, depth });
+    }
+    hits.sort((a, b) => b.depth - a.depth);
+    return hits.map((h) => h.go);
+}
+/**
+ * Compute a hit-test rectangle for a spawned entity in world coords.
+ *
+ * 1. If the entity has `editorHitWidth` / `editorHitHeight` set in data
+ *    (code-rendered entities — Graphics has no intrinsic bounds), use
+ *    those centered on the entity's x/y.
+ * 2. Otherwise fall back to Phaser's `getBounds()` (works for Sprite,
+ *    Rectangle, Arc, Container — anything with a Size component).
+ *
+ * Returns null if neither path yields a usable rect.
+ */
+function entityHitRect(go) {
+    // Live tracker query (0.2.97) — for code-rendered entities, the
+    // Graphics tracker's getter is stashed on data and reflects the
+    // LATEST draw extent (after every redraw the game tick triggered).
+    // Without this lookup, hit-test used stale data set once at spawn
+    // — fine for static visuals but wrong for procedural ones (snake
+    // growing, tilemap painting, dynamic UI). The getter is cheap
+    // (just reads 4 numbers), so calling it per hit-test is fine.
+    const positioned = go;
+    const liveBounds = readLiveTrackedBounds(go);
+    if (liveBounds) {
+        return {
+            x: positioned.x + liveBounds.x,
+            y: positioned.y + liveBounds.y,
+            width: liveBounds.width,
+            height: liveBounds.height,
+        };
+    }
+    const hitW = go.getData('editorHitWidth');
+    const hitH = go.getData('editorHitHeight');
+    if (typeof hitW === 'number' && typeof hitH === 'number') {
+        // editorHitOffsetX/Y (0.2.96) — relative top-left of the drawn
+        // area when offset is known (set by `applyTrackedHitArea` at
+        // spawn). Falls back to "centered on transform" for legacy
+        // entities (sprite/primitive/hud widgets that don't run through
+        // the tracker).
+        const offX = go.getData('editorHitOffsetX');
+        const offY = go.getData('editorHitOffsetY');
+        if (typeof offX === 'number' && typeof offY === 'number') {
+            return {
+                x: positioned.x + offX,
+                y: positioned.y + offY,
+                width: hitW,
+                height: hitH,
+            };
+        }
+        return {
+            x: positioned.x - hitW / 2,
+            y: positioned.y - hitH / 2,
+            width: hitW,
+            height: hitH,
+        };
+    }
+    const withBounds = go;
+    if (typeof withBounds.getBounds !== 'function')
+        return null;
+    const r = withBounds.getBounds();
+    if (r.width === 0 && r.height === 0)
+        return null;
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+}
+/**
+ * Read live bounds from the Graphics tracker getter stashed on the GO's
+ * data manager by `createCodeRendered` (0.2.96). Returns null when the
+ * entity isn't code-rendered (no getter stashed) or when nothing has
+ * been drawn since the last `clear()`. Used by hit-test + selection
+ * rect + popover anchor so they all see the most recent draw extent.
+ */
+function readLiveTrackedBounds(go) {
+    const getter = go.getData('__unboxyGraphicsBoundsGetter');
+    if (typeof getter !== 'function')
+        return null;
+    return getter();
+}
+/**
+ * Find the entity registry for the current editor mode. World mode picks the
+ * first non-Boot non-Editor scene with a registry; HUD mode picks the
+ * HUD scene's registry. Slice 5+.
+ */
+function findRegistry(game) {
+    if (getEditorMode(game) === 'hud')
+        return findHudRegistry(game);
+    for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (key === UMICAT_HUD_SCENE_KEY)
+            continue;
+        const reg = getEntityRegistry(scene);
+        if (reg)
+            return reg;
+    }
+    return undefined;
+}
+// --- applyEdit ------------------------------------------------------------
+async function applyEdit(game, entityId, patch, manifestAsset) {
+    // Lazy-load + manifest-upsert path. When the host's Inspector picks a Bg
+    // image asset that the iframe never preloaded (e.g. a per-game upload that
+    // was never dragged into the scene) OR an asset whose `kind` just flipped
+    // (e.g. region-atlas — slice 10 — flipping from 'image' to 'atlas'), the
+    // host pipelines the new manifest entry along with the patch so the
+    // resulting re-spawn sees a consistent runtime state. Without this, the
+    // re-spawn reads the stale cached manifest and falls back to the
+    // colored-rect placeholder.
+    if (manifestAsset) {
+        const targetScene = getEditorMode(game) === 'hud'
+            ? game.scene.getScene(UMICAT_HUD_SCENE_KEY)
+            : findWorldScene(game);
+        if (targetScene) {
+            try {
+                upsertCachedManifestAsset(targetScene, manifestAsset);
+                await ensureAssetLoaded(targetScene, manifestAsset);
+            }
+            catch (e) {
+                console.warn('[umicat/editor] applyEdit asset upsert/load failed:', e);
+                // Fall through — applyHudPatch will render its placeholder.
+            }
+        }
+    }
+    // HUD mode — patches modify anchor / HUD field values. World-style transform
+    // patches don't apply to HUD widgets, so we dispatch through a HUD-specific
+    // helper. SDK 0.3.0: render fields live at the patch root, so we forward
+    // them under `fields` (the HUD helper's contract).
+    if (getEditorMode(game) === 'hud') {
+        applyHudPatch(game, entityId, {
+            anchor: patch.anchor,
+            layer: patch.layer,
+            z: patch.z,
+            fields: extractRenderFields(patch),
+            role: patch.role,
+            properties: patch.properties,
+        });
+        if (getSelection(game) === entityId)
+            postSelectionRect(game);
+        return;
+    }
+    const registry = findRegistry(game);
+    if (!registry)
+        return;
+    const go = registry.byId(entityId);
+    if (!go)
+        return;
+    applyTransformPatch(go, patch.transform);
+    applyVisualPatch(go, patch);
+    applyCodeRenderedParamsPatch(game, go, patch.params);
+    if (patch.role !== undefined) {
+        if (patch.role === null)
+            go.setData('entityRole', undefined);
+        else
+            go.setData('entityRole', patch.role);
+    }
+    if (patch.properties !== undefined) {
+        go.setData('entityProperties', patch.properties);
+    }
+    // If this edit moved the selected entity, the host's ✨ button + popover
+    // anchor needs the new rect. Cheap RAF-coalesced.
+    if (getSelection(game) === entityId)
+        postSelectionRect(game);
+}
+// --- Slice 8: asset-level live update ------------------------------------
+/**
+ * Handle an `umicat:editor:assetUpdate` postMessage — used by the Hitbox
+ * Editor to push freshly-saved hitbox / depthAnchor metadata into the
+ * running iframe without a scene reload.
+ *
+ * Flow:
+ *   1. Upsert the asset into the iframe's cached manifest (so future spawns
+ *      see the new metadata).
+ *   2. Lazy-load texture if it isn't cached yet (defensive — Hitbox Editor
+ *      is typically opened on already-loaded assets, but the same code path
+ *      is reused if a user edits hitbox on an asset that was never in this
+ *      scene's manifest).
+ *   3. Walk the entity registry, find every sprite with `entityAssetId`
+ *      matching the updated asset's id, and re-apply `setOrigin` (from new
+ *      depthAnchor) + `applyAssetHitbox` (which is idempotent and re-installs
+ *      the per-frame listener cleanly).
+ *
+ * HUD-mode is a no-op — HUD widgets don't carry world hitboxes / depthAnchors.
+ * The Hitbox Editor is launched only on world-scene assets.
+ */
+async function handleAssetUpdate(game, asset) {
+    if (getEditorMode(game) === 'hud')
+        return;
+    const scene = findWorldScene(game);
+    if (!scene)
+        return;
+    try {
+        upsertCachedManifestAsset(scene, asset);
+        await ensureAssetLoaded(scene, asset);
+    }
+    catch (e) {
+        console.warn('[umicat/editor] assetUpdate upsert/load failed:', e);
+        return;
+    }
+    const registry = findRegistry(game);
+    if (!registry)
+        return;
+    for (const go of registry.all()) {
+        if (go.getData('entityAssetId') !== asset.id)
+            continue;
+        const sprite = go;
+        // Re-apply origin from new depthAnchor (no-op if anchor unset; spawn-time
+        // default origin of 0.5/0.5 stays). Cleared anchor reverts to center.
+        if (asset.depthAnchor) {
+            const frameW = sprite.width || 1;
+            const frameH = sprite.height || 1;
+            sprite.setOrigin?.(asset.depthAnchor.x / frameW, asset.depthAnchor.y / frameH);
+        }
+        else if (typeof sprite.setOrigin === 'function') {
+            sprite.setOrigin(0.5, 0.5);
+        }
+        // Re-apply hitbox. Idempotent — tears down the prior per-frame listener
+        // before installing the new one. Silent no-op when sprite has no body.
+        applyAssetHitbox(sprite, asset);
+    }
+    // Slice 6 Phase C — re-apply per-tile metadata + auto-collision on every
+    // tilemap layer whose layer.tilesetIds[0] matches this asset. Without
+    // this, a Tile Metadata Editor save only takes effect after a workspace
+    // rebuild / scene reload. Walks every tilemap entity, finds matching
+    // layers (via the GO's `entityKind === 'tilemap'` tag + the layer's
+    // `tilemapEntityId` data), then re-runs the same metadata wire that
+    // initial scene load uses.
+    for (const go of registry.all()) {
+        if (go.getData('entityKind') !== 'tilemap')
+            continue;
+        const container = go;
+        const layers = container.getData('tilemapLayers') ?? [];
+        for (const layer of layers) {
+            // Look up which tileset this layer was created against — stashed on
+            // the layer's data manager. Cheap match — `layer.tileset[0]` is the
+            // Phaser Tileset object, not the asset id, so we route through the
+            // host-stashed id.
+            const layerTilesetId = layer.getData('tilemapTilesetId');
+            if (!layerTilesetId || layerTilesetId !== asset.id)
+                continue;
+            const tilesetPhaser = layer.tileset[0];
+            if (!tilesetPhaser)
+                continue;
+            applyTilesetTileMetadata(tilesetPhaser, layer, asset);
+            // Slice 6 Phase D — autotile rule-map edits invalidate the cached
+            // vertex grid so the next paint reverse-derives against the new
+            // ruleMap. Without this, the AutotileEditorModal's save shows in
+            // the palette but new paint clicks still cascade against the
+            // pre-save ruleMap (vertex grid is keyed by terrain id but holds
+            // bits derived from old indices).
+            invalidateAutotileCells(layer);
+            // Slice 6 Phase F — re-arm tile animations against the new
+            // animations metadata. Tears down the previous UPDATE handler +
+            // re-scans cells; new animations defined via the Animation Editor
+            // start animating live without a scene reload.
+            applyTilesetAnimations(layer, asset);
+        }
+    }
+}
+// --- Slice 8: debug overlay toggle ---------------------------------------
+/**
+ * Forward the "Show hitboxes" toggle into the editor overlay scene. The
+ * overlay reads this flag each frame from the editor state attached to the
+ * Phaser game (see EditorState.setDebugOverlay).
+ */
+function setDebugOverlay(game, state) {
+    setDebugOverlayState(game, state);
+    // Mirror the toggle into Phaser's Arcade physics debug so the same
+    // "Show hitboxes" control works in BOTH modes:
+    //  - Edit mode: EditorOverlayScene reads `debugOverlay.showHitboxes`
+    //    each frame and draws authored hitbox metadata (slice 8 asset
+    //    hitboxes + slice 6 tile collision rects).
+    //  - Play mode: Phaser draws the actual Arcade body rects via the
+    //    world's debugGraphic. Useful for verifying that `body.setSize` /
+    //    `addTilemapCollider` / `setCollideWorldBounds` are wired
+    //    correctly at runtime.
+    // The two layers can show simultaneously when the user toggles ON
+    // during edit and then clicks Play — both layers visualize "what
+    // counts as solid", just from different sources (authored data vs.
+    // engine state). They don't conflict.
+    for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (key === EDITOR_OVERLAY_KEY)
+            continue;
+        if (key === UMICAT_HUD_SCENE_KEY)
+            continue;
+        if (key === 'BootScene' || key === 'Boot')
+            continue;
+        const world = scene
+            .physics?.world;
+        if (!world)
+            continue;
+        world.drawDebug = state.showHitboxes;
+        if (state.showHitboxes) {
+            // createDebugGraphic is idempotent-ish — Phaser stores it on
+            // world.debugGraphic; calling twice creates a second graphic.
+            // Guard so a re-fire doesn't stack.
+            if (!world.debugGraphic) {
+                world.createDebugGraphic();
+            }
+        }
+        else if (world.debugGraphic) {
+            world.debugGraphic.clear();
+        }
+    }
+}
+/**
+ * Re-render a code-rendered entity's visual when its params change.
+ * Slice 3.5 — Inspector params editor produces these patches.
+ *
+ * No-op for non-code-rendered entities (no renderScriptPath in data) so
+ * sprite/primitive patches that incidentally include `visual.params` (the
+ * type allows it) flow through harmlessly.
+ */
+function applyCodeRenderedParamsPatch(game, go, newParams) {
+    if (newParams === undefined)
+        return;
+    const scriptPath = go.getData('renderScriptPath');
+    if (!scriptPath)
+        return; // not a code-rendered entity
+    const render = resolveRenderScript(game, scriptPath);
+    if (!render)
+        return;
+    const g = go;
+    render(g, newParams);
+    // Re-read tracker bounds after re-render — params changes can grow
+    // or shrink the drawn area. Falls back to existing hit dims when
+    // tracker has no data (script didn't call any tracked methods).
+    const fallbackW = go.getData('editorHitWidth') ?? 64;
+    const fallbackH = go.getData('editorHitHeight') ?? 64;
+    applyTrackedHitArea(g, fallbackW, fallbackH);
+    go.setData('renderScriptParams', newParams);
+}
+function applyTransformPatch(go, t) {
+    if (!t)
+        return;
+    const target = go;
+    if (typeof t.x === 'number')
+        target.x = t.x;
+    if (typeof t.y === 'number')
+        target.y = t.y;
+    if (typeof t.rotation === 'number')
+        target.rotation = t.rotation;
+    if (typeof t.scaleX === 'number')
+        target.scaleX = t.scaleX;
+    if (typeof t.scaleY === 'number')
+        target.scaleY = t.scaleY;
+    if (typeof t.depth === 'number' && target.setDepth)
+        target.setDepth(t.depth);
+}
+/**
+ * Pull every "render field" off a flat `EditorEntityPatch` for forwarding
+ * to `applyHudPatch.fields`. Anything not on this allowlist (transform /
+ * anchor / layer / z / role / properties) flows through HUD's own slots.
+ */
+function extractRenderFields(patch) {
+    const fields = {};
+    const keys = [
+        'tint', 'alpha', 'flipX', 'flipY', 'frame',
+        'width', 'height', 'radius', 'fillColor', 'strokeColor', 'strokeWidth',
+        'params', 'source', 'fontFamily', 'fontSize', 'color', 'align',
+        'assetId', 'iconAssetId', 'backgroundAssetId', 'backgroundFrame', 'backgroundRegion',
+        'label', 'shape', 'pressedFillColor', 'textColor',
+        'value', 'max', 'backgroundColor', 'backgroundAlpha',
+        'borderColor', 'borderWidth', 'borderRadius',
+    ];
+    let any = false;
+    for (const k of keys) {
+        const v = patch[k];
+        if (v !== undefined) {
+            fields[k] = v;
+            any = true;
+        }
+    }
+    return any ? fields : undefined;
+}
+/**
+ * Apply the flat render fields from an `EditorEntityPatch` to a world
+ * entity's GameObject. SDK 0.3.0 — fields live at the patch root, not
+ * nested under `visual`.
+ */
+function applyVisualPatch(go, v) {
+    if (!v)
+        return;
+    const target = go;
+    if (v.tint !== undefined) {
+        if (v.tint === null)
+            target.clearTint?.();
+        else
+            target.setTint?.(parseColor(v.tint));
+    }
+    if (typeof v.alpha === 'number')
+        target.setAlpha?.(v.alpha);
+    if (typeof v.flipX === 'boolean')
+        target.setFlipX?.(v.flipX);
+    if (typeof v.flipY === 'boolean')
+        target.setFlipY?.(v.flipY);
+    if (v.frame !== undefined)
+        target.setFrame?.(v.frame);
+    if (typeof v.width === 'number' && typeof v.height === 'number') {
+        target.setSize?.(v.width, v.height);
+    }
+    if (typeof v.radius === 'number') {
+        // Phaser's Arc doesn't expose setRadius reliably; mutate + redraw.
+        if ('radius' in target)
+            target.radius = v.radius;
+    }
+    if (v.fillColor !== undefined) {
+        target.setFillStyle?.(parseColor(v.fillColor));
+    }
+    if (v.strokeColor !== undefined && typeof v.strokeWidth === 'number') {
+        if (v.strokeColor === null) {
+            // Phaser doesn't expose a clearStroke; setting width=0 + black is the
+            // closest approximation.
+            target.setStrokeStyle?.(0, 0);
+        }
+        else {
+            target.setStrokeStyle?.(v.strokeWidth, parseColor(v.strokeColor));
+        }
+    }
+}
+// --- Create / delete ------------------------------------------------------
+/**
+ * Spawn a new entity into the active world scene. Slice 3.
+ *
+ * If the entity references an asset whose texture isn't yet in the Phaser
+ * cache, we lazy-load it before spawn — same pattern as SceneLoader's
+ * preloadSceneAssets, but on a single asset and at edit time. Without this
+ * the host would have to coordinate a build before showing a dropped
+ * sprite, which defeats the point of drag-to-place.
+ */
+async function createEntity(game, entity, manifestAsset) {
+    // HUD mode dispatches to the HUD-runtime spawner (slice 5). The host
+    // sends HudEntity records (not WorldEntity), so we type-erase.
+    if (getEditorMode(game) === 'hud') {
+        // Lazy-load asset if the HUD widget needs one and it's not in cache yet.
+        const hud = game.scene.getScene(UMICAT_HUD_SCENE_KEY);
+        if (manifestAsset && hud && !hud.textures.exists(manifestAsset.textureKey)) {
+            await loadAssetIntoScene(hud, manifestAsset);
+        }
+        createHudEntityInScene(game, entity);
+        return;
+    }
+    const scene = findWorldScene(game);
+    if (!scene) {
+        console.warn('[umicat/editor] createEntity: no world scene to spawn into');
+        return;
+    }
+    const registry = getEntityRegistry(scene);
+    if (!registry) {
+        console.warn('[umicat/editor] createEntity: world scene has no entity registry');
+        return;
+    }
+    // Always upsert the manifestAsset into the scene's cached manifest so
+    // resolveAsset / re-spawns / subsequent layer adds find a consistent
+    // entry. Mirrors the addLayer + assetUpdate paths.
+    if (manifestAsset) {
+        upsertCachedManifestAsset(scene, manifestAsset);
+    }
+    // Collect every asset whose texture this entity needs lazy-loaded.
+    // - sprite: one asset (entity.assetId, or manifestAsset).
+    // - tilemap: one per layer's tileset.
+    // - other kinds (rect / circle / code-rendered / trigger): no asset.
+    const assetsToLoad = [];
+    const sceneRef = scene; // local non-nullable for closures below
+    function queueIfMissing(a) {
+        if (!a)
+            return;
+        if (sceneRef.textures.exists(a.textureKey))
+            return;
+        if (assetsToLoad.find((x) => x.id === a.id))
+            return;
+        assetsToLoad.push(a);
+    }
+    function resolveById(id) {
+        if (manifestAsset && manifestAsset.id === id)
+            return manifestAsset;
+        try {
+            const manifest = getManifest(sceneRef);
+            return manifest.assets.find((a) => a.id === id);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (entity.kind === 'sprite') {
+        let a = manifestAsset;
+        if (!a) {
+            const assetId = entity.assetId;
+            if (assetId)
+                a = resolveById(assetId);
+        }
+        queueIfMissing(a);
+    }
+    else if (entity.kind === 'tilemap') {
+        const tilemap = entity;
+        for (const layer of tilemap.layers ?? []) {
+            for (const tid of layer.tilesetIds ?? []) {
+                queueIfMissing(resolveById(tid));
+            }
+        }
+    }
+    for (const a of assetsToLoad) {
+        await loadAssetIntoScene(scene, a);
+    }
+    const ctx = {
+        scene,
+        registry,
+        resolveAsset: (id) => {
+            if (manifestAsset && manifestAsset.id === id)
+                return manifestAsset;
+            // Fallback: look up in the manifest cache. Covers re-drag of an
+            // already-in-manifest asset where the host omitted manifestAsset.
+            try {
+                const manifest = getManifest(scene);
+                const found = manifest.assets.find((a) => a.id === id);
+                if (found)
+                    return found;
+            }
+            catch {
+                /* fall through to throw */
+            }
+            throw new Error(`[umicat/editor] createEntity: asset '${id}' not found in manifest`);
+        },
+        resolveRenderScript: undefined,
+    };
+    try {
+        spawnEntity(ctx, entity);
+    }
+    catch (e) {
+        console.warn('[umicat/editor] spawnEntity failed:', e);
+    }
+    // Tilemap grids are created hidden (Play mode default); enterEdit walks
+    // existing tilemaps once and toggles them visible. New tilemaps dropped
+    // AFTER enterEdit miss that walk and stay invisible — an empty tilemap
+    // with hidden grid renders nothing, so the user sees nothing on the
+    // canvas + thinks the drop failed. Re-run the visibility walk after
+    // every editor-driven spawn so newly-dropped tilemaps show their bounds.
+    if (entity.kind === 'tilemap') {
+        setTilemapGridsVisible(game, true);
+    }
+}
+/**
+ * Merge an asset record into the scene's cached manifest (the one
+ * {@code getManifest(scene)} returns). Used by applyEdit's pipelined-asset
+ * path so subsequent re-spawns see the updated entry (kind / atlasPath /
+ * atlasFormat / ninePatch / etc.) without a full scene reload.
+ *
+ * <p>The manifest object lives in `scene.cache.json` and is shared by
+ * reference — mutating its `assets[]` is sufficient. We replace in place
+ * when an entry with the same id exists (so a stale {@code kind: 'image'}
+ * gets fully overwritten by a fresh {@code kind: 'atlas'} record).
+ */
+function upsertCachedManifestAsset(scene, asset) {
+    let manifest;
+    try {
+        manifest = getManifest(scene);
+    }
+    catch {
+        return; // manifest not in cache — nothing to merge against
+    }
+    if (!manifest.assets)
+        manifest.assets = [];
+    const idx = manifest.assets.findIndex((a) => a.id === asset.id);
+    if (idx >= 0)
+        manifest.assets[idx] = asset;
+    else
+        manifest.assets.push(asset);
+}
+/**
+ * Idempotent asset-loaded check: returns immediately if the texture is in
+ * the cache. For atlas-format assets, ALSO ensures the per-frame ninePatch
+ * sidecar JSON is loaded so the SDK's region-9-slice path can read it back.
+ */
+function ensureAssetLoaded(scene, asset) {
+    if (asset.kind === 'audio')
+        return Promise.resolve();
+    const needsTexture = !scene.textures.exists(asset.textureKey);
+    const sidecarKey = `umicat:atlas-ninepatch:${asset.textureKey}`;
+    const needsSidecar = asset.kind === 'atlas' &&
+        asset.atlasFormat === 'json' &&
+        !!asset.atlasPath &&
+        !scene.cache.json.exists(sidecarKey);
+    if (!needsTexture && !needsSidecar)
+        return Promise.resolve();
+    return loadAssetIntoScene(scene, asset);
+}
+/**
+ * Pick the URL to load asset bytes from. Drag-to-place uses the CDN
+ * URL directly because the asset bytes aren't yet in the workspace's
+ * `public/uploaded/` (they only get synced on SAVE by session-server's
+ * `syncWorkspaceAssetsFromManifest`). Without this, the iframe's
+ * lazy-load 404s for fresh drops, the texture never lands in
+ * `scene.textures`, and `add.sprite(...)` falls back to Phaser's empty
+ * `__DEFAULT` texture — visible only as the editor's selection rect
+ * outline with no sprite content inside. `loadUrl` is an off-record
+ * field set by `EditorBridge.createEntity`'s `manifestAsset` (home-ui
+ * passes `AssetSummary.url`); not part of the persisted manifest
+ * schema (which keeps `path: uploaded/<filename>` for build-time
+ * correctness — session-server syncs bytes there on save).
+ */
+function pickLoadUrl(asset) {
+    const loadUrl = asset.loadUrl;
+    return loadUrl || asset.path;
+}
+function loadAssetIntoScene(scene, asset) {
+    return new Promise((resolve, reject) => {
+        if (scene.textures.exists(asset.textureKey)) {
+            resolve();
+            return;
+        }
+        const onComplete = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (file) => {
+            if (file.key !== asset.textureKey)
+                return;
+            cleanup();
+            reject(new Error(`failed to load asset ${asset.id}: ${file.url}`));
+        };
+        const cleanup = () => {
+            scene.load.off(Phaser.Loader.Events.FILE_COMPLETE, perFileComplete);
+            scene.load.off(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+            scene.load.off(Phaser.Loader.Events.COMPLETE, onComplete);
+        };
+        const perFileComplete = (key) => {
+            if (key === asset.textureKey) {
+                cleanup();
+                resolve();
+            }
+        };
+        scene.load.on(Phaser.Loader.Events.FILE_COMPLETE, perFileComplete);
+        scene.load.on(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+        scene.load.on(Phaser.Loader.Events.COMPLETE, onComplete);
+        const loadFrom = pickLoadUrl(asset);
+        switch (asset.kind) {
+            case 'image':
+                scene.load.image(asset.textureKey, loadFrom);
+                break;
+            case 'spritesheet':
+                if (asset.spriteSheetConfig) {
+                    scene.load.spritesheet(asset.textureKey, loadFrom, asset.spriteSheetConfig);
+                }
+                else {
+                    scene.load.image(asset.textureKey, loadFrom);
+                }
+                break;
+            case 'atlas':
+                if (asset.atlasPath && asset.atlasFormat === 'xml') {
+                    scene.load.atlasXML(asset.textureKey, loadFrom, asset.atlasPath);
+                }
+                else if (asset.atlasPath) {
+                    scene.load.atlas(asset.textureKey, loadFrom, asset.atlasPath);
+                    // Also fetch the raw JSON into the side-cache for per-region
+                    // ninePatch lookups (slice 10). Phaser's atlas parser drops
+                    // unknown per-frame fields, so we keep the original JSON around.
+                    const sidecarKey = `umicat:atlas-ninepatch:${asset.textureKey}`;
+                    if (!scene.cache.json.exists(sidecarKey)) {
+                        scene.load.json(sidecarKey, asset.atlasPath);
+                    }
+                }
+                break;
+            case 'audio':
+                scene.load.audio(asset.textureKey, loadFrom);
+                break;
+            default:
+                cleanup();
+                reject(new Error(`unsupported asset kind for editor lazy-load: ${asset.kind}`));
+                return;
+        }
+        if (!scene.load.isLoading())
+            scene.load.start();
+    });
+}
+function deleteEntity(game, entityId) {
+    // HUD mode — dispatch to the HUD-scene helper, which destroys + unregisters
+    // + drops the entity from the cached scene file.
+    if (getEditorMode(game) === 'hud') {
+        deleteHudEntityFromScene(game, entityId);
+        if (getSelection(game) === entityId)
+            setSelection(game, null);
+        return;
+    }
+    const scene = findWorldScene(game);
+    if (!scene)
+        return;
+    const registry = getEntityRegistry(scene);
+    if (!registry)
+        return;
+    const go = registry.byId(entityId);
+    if (!go)
+        return;
+    // Slice 6 Phase B — tilemap entities have associated TilemapLayer
+    // GameObjects in scene ROOT (not Container children, due to the Phaser
+    // Container/TilemapLayer transform quirk). Destroying the Container
+    // alone orphans those layers — they stay visible in the canvas until
+    // the next scene reload. Walk the container's stashed layer refs and
+    // destroy each before destroying the container itself. Also destroys
+    // the sub-tile static body group (slice 6 Phase C follow-up) since
+    // those bodies are scene-root members too.
+    if (go.getData('entityKind') === 'tilemap') {
+        const container = go;
+        const layers = container.getData('tilemapLayers') ?? [];
+        for (const layer of layers) {
+            const subGroup = layer.getData('unboxySubTileStaticGroup');
+            if (subGroup) {
+                subGroup.clear(true, true);
+                subGroup.destroy(true);
+            }
+            layer.destroy();
+        }
+        container.setData('tilemapLayers', []);
+    }
+    go.destroy();
+    registry.unregister(entityId);
+    if (getSelection(game) === entityId)
+        setSelection(game, null);
+}
+function findWorldScene(game) {
+    // Prefer a scene with an EntityRegistry (scene-as-data game) — this
+    // is the canonical "world scene" with metadata the editor can fully
+    // interact with (Inspector, drag-to-place, prefab edits, etc.).
+    // But fall back to ANY non-Boot/HUD/Overlay scene for pure
+    // scene-as-code games. Without the fallback, the editor cam never
+    // installs for code-only games (Snake, breakout, etc.) and pan/zoom
+    // is silently broken — see game 3167e9ee (2026-05-17). Downstream
+    // callers that NEED a registry (createEntity, deleteEntity, prefab
+    // patches) check `getEntityRegistry(scene)` themselves and soft-fail
+    // when it's missing, so relaxing this fallback is safe.
+    let firstNonRegistry;
+    for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (BOOT_SCENE_KEYS.has(key))
+            continue;
+        if (key === UMICAT_HUD_SCENE_KEY)
+            continue;
+        if (key === EDITOR_OVERLAY_KEY)
+            continue;
+        if (getEntityRegistry(scene))
+            return scene;
+        if (!firstNonRegistry)
+            firstNonRegistry = scene;
+    }
+    return firstNonRegistry;
+}
+// --- Pan / zoom (P1 infinite canvas) -------------------------------------
+const ZOOM_MIN = 0.25;
+const ZOOM_MAX = 4;
+/**
+ * Cap zoom uniformly across host-driven + SDK-input-driven paths so the
+ * limits stay consistent everywhere.
+ */
+function clampZoom(z) {
+    return Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, z));
+}
+/**
+ * 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 function applyEditorPanZoom(game, msg) {
+    const editorCam = getEditorCamera(game);
+    const overlayScene = game.scene.getScene(EDITOR_OVERLAY_KEY);
+    const cams = [];
+    if (editorCam)
+        cams.push(editorCam);
+    if (overlayScene)
+        cams.push(overlayScene.cameras.main);
+    for (const cam of cams) {
+        if (msg.relative) {
+            if (typeof msg.scrollX === 'number')
+                cam.scrollX += msg.scrollX;
+            if (typeof msg.scrollY === 'number')
+                cam.scrollY += msg.scrollY;
+        }
+        else {
+            if (typeof msg.scrollX === 'number')
+                cam.scrollX = msg.scrollX;
+            if (typeof msg.scrollY === 'number')
+                cam.scrollY = msg.scrollY;
+        }
+        if (typeof msg.zoom === 'number') {
+            cam.setZoom(clampZoom(msg.zoom));
+        }
+    }
+    // Keep HUD scene's cam viewport tracking the camera-viewport rect
+    // on the editor canvas — pan/zoom moves the rect, HUD follows.
+    syncHudCameraToEditorCam(game);
+    postCameraState(game);
+    // Re-anchor the host's popover/sparkle button on every pan/zoom so
+    // it tracks the selected entity. Previously only the postMessage
+    // panZoom path posted the rect; the SDK-internal wheel/middle-drag
+    // path bypassed it and the popover lagged behind. Baking the call
+    // in here covers both paths uniformly. RAF-coalesced inside, so
+    // many wheel events per gesture still emit one rect per frame.
+    postSelectionRect(game);
+}
+/**
+ * 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 const applyPanZoomToWorld = 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 function postCameraState(game) {
+    const worldScene = findWorldScene(game);
+    if (!worldScene)
+        return;
+    const cam = getEditorCamera(game) ?? worldScene.cameras.main;
+    const canvasW = game.scale.width;
+    const canvasH = game.scale.height;
+    // Visible world rect = (scrollX, scrollY) → (scrollX + canvasW/zoom, ...).
+    // Convenience for the host so it doesn't have to re-derive zoom math.
+    const viewportWorld = {
+        x: cam.scrollX,
+        y: cam.scrollY,
+        width: canvasW / cam.zoom,
+        height: canvasH / cam.zoom,
+    };
+    postToHost({
+        type: 'umicat:editor:cameraState',
+        zoom: cam.zoom,
+        scrollX: cam.scrollX,
+        scrollY: cam.scrollY,
+        viewportWorld,
+    });
+}
+// --- Canvas expand / restore (P1 infinite canvas: whole iframe = editor) -
+const CANVAS_SCALE_SNAPSHOT_KEY = '__unboxyEditorScaleSnapshot';
+/**
+ * Switch Phaser to RESIZE scale mode so the canvas fills its parent (the
+ * iframe body). Pairs with a home-ui CSS rule that drops the iframe's
+ * aspect-ratio constraint in edit mode — together the iframe is the
+ * entire editor surface, matching the Figma/Godot mental model the user
+ * pushed back on 2026-05-17.
+ *
+ * The game's world coordinate system stays at its declared size (e.g.
+ * 720×1280) — `cameras.main` is invisible in edit mode and never reads
+ * the new canvas dims; only the editor camera (installed AFTER this
+ * call) uses the new size to set its viewport. On exit, scale mode is
+ * restored to the original (typically `FIT`) and the canvas snaps back
+ * to game intrinsic size.
+ *
+ * Idempotent: re-entering edit while a snapshot exists is a no-op (the
+ * race-window re-attempt loop in `enterEdit` calls back into the
+ * install chain every 100ms for ~3s).
+ */
+function expandCanvasForEditor(game) {
+    const bag = game;
+    // Idempotent expand (2026-05-17): if a stale snapshot exists from a
+    // prior cycle that didn't fully restore, restore first to a clean
+    // baseline, then take a fresh snapshot. Without this, second enter
+    // skipped the entire expand path on stale state.
+    if (bag[CANVAS_SCALE_SNAPSHOT_KEY]) {
+        restoreCanvasAfterEditor(game);
+    }
+    bag[CANVAS_SCALE_SNAPSHOT_KEY] = {
+        scaleMode: game.scale.scaleMode,
+        autoCenter: game.scale.autoCenter,
+        gameWidth: game.scale.gameSize.width,
+        gameHeight: game.scale.gameSize.height,
+    };
+    // Force html/body to fill the viewport with grey bg. Inline styles win
+    // over the template's `<style>` (which sets `body { display: flex;
+    // align-items: center; background: #000 }` — that flex-centers the
+    // canvas at its intrinsic size and shows a black background around
+    // it, exactly what the user pushed back on). Grey body bg also acts
+    // as the editor "void" — if any pixel inside the iframe isn't covered
+    // by the SDK overlay's outside-fill graphics (e.g. fast pan, low
+    // zoom + huge canvas), it falls through to grey instead of black.
+    if (typeof document !== 'undefined') {
+        const html = document.documentElement;
+        const body = document.body;
+        if (html) {
+            html.style.setProperty('width', '100%', 'important');
+            html.style.setProperty('height', '100%', 'important');
+            html.style.setProperty('margin', '0', 'important');
+            html.style.setProperty('padding', '0', 'important');
+            html.style.setProperty('overflow', 'hidden', 'important');
+        }
+        if (body) {
+            body.style.setProperty('width', '100%', 'important');
+            body.style.setProperty('height', '100%', 'important');
+            body.style.setProperty('margin', '0', 'important');
+            body.style.setProperty('padding', '0', 'important');
+            body.style.setProperty('display', 'block', 'important');
+            body.style.setProperty('background', '#2a2a2e', 'important');
+            body.style.setProperty('overflow', 'hidden', 'important');
+            // Force a layout flush so the body's new dims are committed before
+            // we read them via getBoundingClientRect below.
+            void body.offsetHeight;
+        }
+    }
+    // Switch to NONE (explicit canvas size) + NO_CENTER (no autoCenter
+    // margins) so we have full control. RESIZE alone was fighting both
+    // the template's body flex and the original `autoCenter: CENTER_BOTH`
+    // — net effect was the canvas would settle at game intrinsic size
+    // shifted/centered inside body, regardless of what scale.refresh()
+    // computed. NONE + setGameSize sidesteps all of that.
+    game.scale.autoCenter = Phaser.Scale.NO_CENTER;
+    game.scale.scaleMode = Phaser.Scale.NONE;
+    resizeCanvasToIframe(game);
+    // Re-measure on next frame too — React's iframe inline-style update
+    // and the iframe's internal layout might not be settled at the moment
+    // `enterEdit` fires. A second pass catches late layout. Reads the
+    // snapshot to confirm we're still in editor mode (user could have
+    // toggled out before the rAF tick).
+    if (typeof requestAnimationFrame !== 'undefined') {
+        requestAnimationFrame(() => {
+            if (!bag[CANVAS_SCALE_SNAPSHOT_KEY])
+                return;
+            resizeCanvasToIframe(game);
+        });
+    }
+}
+/**
+ * Read iframe viewport via `window.innerWidth/innerHeight` (most direct
+ * available measurement inside an iframe — equals the iframe ELEMENT's
+ * inner content area, settled by the browser regardless of body layout).
+ * Falls back to body rect when window dims are 0 (some sandboxes).
+ */
+function resizeCanvasToIframe(game) {
+    if (typeof window === 'undefined')
+        return;
+    // Use `window.innerWidth/Height` as the iframe viewport size, then
+    // FORCE the canvas's display CSS to exactly that in pixels via
+    // setProperty. This guarantees `cssRect.width === game.scale.width`
+    // regardless of what body styling, flex constraints, or CSS
+    // transforms might otherwise cause canvas's `width: 100%` to
+    // resolve to. Empirically, body's resolved width can be smaller
+    // than `window.innerWidth` due to template's `display: flex` /
+    // container queries / etc., even after we set `body.width: 100%`
+    // inline — when that happens `100%` on canvas = 100% of (shrunk)
+    // body, and we get the mismatch the user saw at 53% zoom (sparkle
+    // landed in top-left of the iframe instead of on the entity).
+    const w = window.innerWidth;
+    const h = window.innerHeight;
+    if (w <= 0 || h <= 0)
+        return;
+    game.scale.setGameSize(w, h);
+    game.scale.refresh();
+    if (game.canvas) {
+        // Explicit pixel display sizing — beats both `width: 100%`
+        // resolution AND any CSS-transform-induced scaling. Phaser's
+        // own `style.width` write happens in `refresh()` above, but
+        // without `!important` so any stylesheet rule with `!important`
+        // could win. We re-set with `!important` here.
+        game.canvas.style.setProperty('position', 'absolute', 'important');
+        game.canvas.style.setProperty('top', '0', 'important');
+        game.canvas.style.setProperty('left', '0', 'important');
+        game.canvas.style.setProperty('width', w + 'px', 'important');
+        game.canvas.style.setProperty('height', h + 'px', 'important');
+        game.canvas.style.setProperty('margin', '0', 'important');
+    }
+    // Sync editor + overlay camera viewports to the new canvas dims so
+    // pan/zoom + outside-fill render across the entire surface. The
+    // installEditorCameras call earlier in `enterEdit` may have set the
+    // viewport based on a stale first measurement; this rAF-deferred
+    // path catches the corrected size.
+    const editorCam = getEditorCamera(game);
+    if (editorCam && typeof editorCam.setViewport === 'function') {
+        editorCam.setViewport(0, 0, w, h);
+    }
+    const overlayScene = game.scene.getScene(EDITOR_OVERLAY_KEY);
+    // Overlay scene's `cameras.main` is undefined during the boot window
+    // between scene.run() and scene.create() — Phaser hasn't constructed
+    // the camera manager yet. Race-safe guard: only call setViewport if
+    // both cameras and cameras.main exist.
+    if (overlayScene && overlayScene.cameras && overlayScene.cameras.main) {
+        overlayScene.cameras.main.setViewport(0, 0, w, h);
+    }
+    // Re-sync HUD cam viewport to the camera-viewport rect on the new
+    // canvas dims (Phaser auto-resized HUD cam to the expanded canvas;
+    // we want it positioned inside the cam viewport rect instead).
+    syncHudCameraToEditorCam(game);
+}
+/**
+ * Inverse of `expandCanvasForEditor`. Restores the original scale mode
+ * and game size; Phaser resizes the canvas back to the game's intrinsic
+ * dimensions (with whatever FIT letterboxing the host CSS now allows).
+ */
+function restoreCanvasAfterEditor(game) {
+    const bag = game;
+    const snap = bag[CANVAS_SCALE_SNAPSHOT_KEY];
+    if (!snap)
+        return;
+    // Clear the inline html/body styles we added so Play mode reverts to
+    // the template's original styling (flex-centered canvas, black bg).
+    if (typeof document !== 'undefined') {
+        const html = document.documentElement;
+        const body = document.body;
+        if (html) {
+            ['width', 'height', 'margin', 'padding', 'overflow'].forEach((p) => html.style.removeProperty(p));
+        }
+        if (body) {
+            ['width', 'height', 'margin', 'padding', 'display', 'background', 'overflow'].forEach((p) => body.style.removeProperty(p));
+        }
+    }
+    // Clear the inline canvas styles we forced on enter. Phaser's
+    // scaleMode restore (FIT etc.) will re-write style.width/height to
+    // the appropriate values for its own layout.
+    if (game.canvas) {
+        ['position', 'top', 'left', 'width', 'height', 'margin'].forEach((p) => game.canvas.style.removeProperty(p));
+    }
+    game.scale.autoCenter = snap.autoCenter;
+    game.scale.scaleMode = snap.scaleMode;
+    game.scale.setGameSize(snap.gameWidth, snap.gameHeight);
+    game.scale.refresh();
+    delete bag[CANVAS_SCALE_SNAPSHOT_KEY];
+}
+// --- Editor camera install / uninstall (P1 infinite canvas) -------------
+const EDITOR_CAM_KEY = '__unboxyEditorCam';
+const GAME_CAM_HIDDEN_KEY = '__unboxyEditorGameCamWasVisible';
+const VOID_FILL_KEY = '__unboxyEditorVoidFill';
+// Editor "void" grey — matches what EditorOverlayScene used to draw via
+// `OUTSIDE_FILL_COLOR`. Moved into world scene Graphics at depth=-1e9 so
+// entities dropped outside world bounds render on top of the fill (was
+// behind it when drawn in overlay scene, hiding the sprite).
+const VOID_FILL_COLOR = 0x3a3a45;
+const VOID_FILL_ALPHA = 1;
+const VOID_FILL_DEPTH = -1e9;
+const VOID_FILL_EXTENT = 1000000;
+/**
+ * Install a SEPARATE editor camera on the world scene + hide the game's
+ * runtime camera so the editor view doesn't double-render. Initial state
+ * copied from cameras.main so the user opens edit mode looking at "what
+ * the player would see right now."
+ *
+ * Idempotent — calling twice is a no-op (the editor cam is keyed onto the
+ * game object). Editor cam reference is also exposed via `getEditorCamera`
+ * for `applyEditorPanZoom` + the overlay scene's mirror.
+ */
+function installEditorCameras(game) {
+    const worldScene = findWorldScene(game);
+    if (!worldScene)
+        return;
+    // Idempotent install (2026-05-17): if a stale editor cam reference
+    // exists (e.g. an exit cycle didn't fully clear it), remove it
+    // before installing a fresh one. The previous early-return left the
+    // game cam visible (since `gameCam.setVisible(false)` below was
+    // skipped), producing the "game renders top-left, no editor
+    // decorations" bug on second enter.
+    const existing = game[EDITOR_CAM_KEY];
+    if (existing) {
+        try {
+            worldScene.cameras.remove(existing);
+        }
+        catch { /* stale cam already gone */ }
+        delete game[EDITOR_CAM_KEY];
+    }
+    const gameCam = worldScene.cameras.main;
+    // Remember whether the game cam was visible so we can restore it exactly.
+    game[GAME_CAM_HIDDEN_KEY] = gameCam.visible;
+    gameCam.setVisible(false);
+    const canvasW = game.scale.width;
+    const canvasH = game.scale.height;
+    const editorCam = worldScene.cameras.add(0, 0, canvasW, canvasH);
+    // Editor cam's bg shows through to canvas behind it — we want the editor
+    // overlay's outside-fill graphics to be visible, so make the camera bg
+    // transparent.
+    editorCam.setBackgroundColor(0);
+    // Phase D fix — snap to integer pixels so tilemap NEAREST sampling
+    // doesn't catch transparent neighbor-tile pixels at subpixel offsets.
+    // See spawnEntity.ts renderLayerInto for the matching Play-mode setting.
+    editorCam.setRoundPixels(true);
+    // Initial editor view: match the game's display size in Play mode —
+    // i.e., fit the WHOLE world inside the canvas with NO margin. Play
+    // mode uses Phaser FIT scaling against an iframe that's sized to the
+    // game's AR, so the game renders at maximum size that fits the
+    // iframe. In edit mode the canvas is now wider/taller than the game
+    // (it fills the iframe regardless of AR), so we need to compute the
+    // same fit zoom ourselves: `min(canvasW/worldW, canvasH/worldH)`.
+    // The extra canvas area beyond the game becomes the editor void.
+    //
+    // History: 0.2.82 defaulted to zoom=1 which made the game look BIGGER
+    // than in Play mode (a 1280-tall world at zoom 1 clipped vertically
+    // in a 760-tall canvas) — user pushed back ("还不如你的53%"). The 53%
+    // came from 0.2.81's fit*0.9 logic; same intent, but the 0.9 margin
+    // made it visibly smaller than Play. Dropping the margin matches Play
+    // exactly — game looks the same as it did before clicking Edit.
+    const sceneFile = readActiveSceneFile(game);
+    const snap = game[CANVAS_SCALE_SNAPSHOT_KEY];
+    const worldW = sceneFile?.world.width ?? snap?.gameWidth ?? canvasW;
+    const worldH = sceneFile?.world.height ?? snap?.gameHeight ?? canvasH;
+    const editorZoom = Math.min(canvasW / worldW, canvasH / worldH);
+    editorCam.setZoom(editorZoom);
+    editorCam.scrollX = worldW / 2 - canvasW / (2 * editorZoom);
+    editorCam.scrollY = worldH / 2 - canvasH / (2 * editorZoom);
+    game[EDITOR_CAM_KEY] = editorCam;
+    // Sync HUD scene's camera to render INSIDE the camera viewport rect
+    // on the editor canvas (so HUD widgets visually track the camera
+    // viewport rect during pan/zoom — matching what the player will see
+    // at runtime).
+    syncHudCameraToEditorCam(game);
+}
+/**
+ * Tear down the editor camera + re-show the game's runtime camera. Inverse
+ * of {@link installEditorCameras}. Called from `exitEdit` BEFORE resuming
+ * scenes so the first resumed frame renders through cameras.main.
+ */
+function uninstallEditorCameras(game) {
+    const worldScene = findWorldScene(game);
+    const editorCam = game[EDITOR_CAM_KEY];
+    if (worldScene && editorCam) {
+        worldScene.cameras.remove(editorCam);
+    }
+    if (worldScene) {
+        const wasVisible = game[GAME_CAM_HIDDEN_KEY];
+        worldScene.cameras.main.setVisible(wasVisible !== false);
+    }
+    delete game[EDITOR_CAM_KEY];
+    delete game[GAME_CAM_HIDDEN_KEY];
+    // Restore HUD camera to identity (Play-mode behavior) so HUD widgets
+    // return to canvas-edge anchoring once Phaser resizes back to game
+    // intrinsic canvas dims.
+    restoreHudCamera(game);
+}
+/**
+ * Install a grey "void" fill in the world scene at very low depth so
+ * the area outside world bounds reads as editor surface (not the
+ * game's solid black canvas bg). Drawn as a single Graphics with four
+ * rects extending ±VOID_FILL_EXTENT (1e6) around world bounds; camera
+ * clips offscreen for free. Lives in the world scene (not overlay) at
+ * depth `-1e9` so entities at default depth render ON TOP of it —
+ * fixes the 2026-05-17 bug where dropped entities outside world bounds
+ * were visually covered by the overlay-scene grey fill.
+ */
+function installVoidFill(game) {
+    const worldScene = findWorldScene(game);
+    if (!worldScene)
+        return;
+    // Idempotent: tear down stale fill before installing fresh.
+    uninstallVoidFill(game);
+    // Prefer scene-file dims (scene-as-data games declare world bounds
+    // explicitly). Fall back to the snapshot's intrinsic game size for
+    // pure scene-as-code games (no scene file in cache) — see game
+    // 3167e9ee (Snake) which surfaced this 2026-05-17. Without the
+    // fallback the void fill never installed and the editor showed the
+    // game's solid bg color (black for Snake) instead of editor grey.
+    const sceneFile = readActiveSceneFile(game);
+    const snap = game[CANVAS_SCALE_SNAPSHOT_KEY];
+    const wbX = 0;
+    const wbY = 0;
+    const wbR = sceneFile?.world.width ?? snap?.gameWidth ?? game.scale.width;
+    const wbB = sceneFile?.world.height ?? snap?.gameHeight ?? game.scale.height;
+    const B = VOID_FILL_EXTENT;
+    const g = worldScene.add.graphics();
+    g.setDepth(VOID_FILL_DEPTH);
+    g.fillStyle(VOID_FILL_COLOR, VOID_FILL_ALPHA);
+    g.fillRect(-B, -B, 2 * B, B + wbY); // top strip
+    g.fillRect(-B, wbB, 2 * B, B - wbB); // bottom strip
+    g.fillRect(-B, wbY, B + wbX, wbB - wbY); // left strip
+    g.fillRect(wbR, wbY, B - wbR, wbB - wbY); // right strip
+    // Hide from the game cam (which is invisible anyway, but be explicit
+    // — if a future code path un-hides game cam during edit, the void
+    // fill shouldn't show through there).
+    g.setData('__unboxyVoidFill', true);
+    game[VOID_FILL_KEY] = g;
+}
+function uninstallVoidFill(game) {
+    const bag = game;
+    const g = bag[VOID_FILL_KEY];
+    if (g) {
+        try {
+            g.destroy();
+        }
+        catch { /* already gone */ }
+        delete bag[VOID_FILL_KEY];
+    }
+}
+/**
+ * Sync the HUD scene's main camera to render INSIDE the camera viewport
+ * rect on the editor canvas, scaled by the editor cam's zoom. Without
+ * this, HUD widgets stay anchored to the EXPANDED canvas corners — far
+ * from where the player will actually see them at runtime — and don't
+ * track when the user pans/zooms the editor view. With this, HUD
+ * widgets visually stick to the blue camera-viewport rect, matching
+ * what the player sees in Play mode.
+ *
+ * Pair with `resolveAnchor`'s snapshot-aware logic in HudRuntime — that
+ * makes HUD widgets compute positions in GAME-intrinsic coords; this
+ * function projects those coords onto the camera-viewport-rect area
+ * of the editor canvas.
+ *
+ * Idempotent. Called from `installEditorCameras` + `applyEditorPanZoom`
+ * + `resizeCanvasToIframe`'s rAF tick so HUD tracks all editor view
+ * mutations.
+ */
+function syncHudCameraToEditorCam(game) {
+    const hudScene = game.scene.getScene(UMICAT_HUD_SCENE_KEY);
+    if (!hudScene)
+        return;
+    const hudCam = hudScene.cameras.main;
+    if (!hudCam)
+        return;
+    const editorCam = getEditorCamera(game);
+    const worldScene = findWorldScene(game);
+    if (!editorCam || !worldScene)
+        return;
+    // Use FULL canvas viewport with a SCROLL offset (not a positioned
+    // viewport). The original approach (0.2.89) set HUD cam viewport to
+    // the camera-viewport rect's canvas position + size — visually
+    // equivalent for HUD widgets positioned inside the rect, but it
+    // caused two issues at zoom levels where the camera-viewport rect
+    // extends past the canvas edge:
+    //   1. Negative viewport coords (Phaser clips them weirdly)
+    //   2. Viewport-positioned clipping cut off widgets as the rect
+    //      moved during cursor-anchored zoom
+    // Scroll-based achieves the same widget placement without the
+    // clip artifacts (full canvas viewport → no clipping).
+    //
+    // Math: widget at HUD-intrinsic (X, Y) renders at
+    //   canvas X = viewport.x + (X - scroll.x) * zoom = (X - scroll.x) * zoom
+    // We want it to equal camRectCanvasX + X * zoom (where the camera-
+    // viewport rect renders on the editor canvas), so:
+    //   scroll.x = -camRectCanvasX / zoom = editorCam.scrollX - gameCam.scrollX
+    const gameCam = worldScene.cameras.main;
+    hudCam.setViewport(0, 0, game.scale.width, game.scale.height);
+    hudCam.setZoom(editorCam.zoom);
+    hudCam.setScroll(editorCam.scrollX - gameCam.scrollX, editorCam.scrollY - gameCam.scrollY);
+}
+/**
+ * Restore the HUD scene's main camera to its default identity (full
+ * canvas viewport at zoom 1, scroll 0) — the Play-mode state. Called
+ * from `uninstallEditorCameras` and `restoreCanvasAfterEditor`.
+ */
+function restoreHudCamera(game) {
+    const hudScene = game.scene.getScene(UMICAT_HUD_SCENE_KEY);
+    if (!hudScene)
+        return;
+    const hudCam = hudScene.cameras.main;
+    if (!hudCam)
+        return;
+    hudCam.setViewport(0, 0, game.scale.width, game.scale.height);
+    hudCam.setZoom(1);
+    hudCam.setScroll(0, 0);
+}
+/**
+ * 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 function getEditorCamera(game) {
+    return (game[EDITOR_CAM_KEY] ?? null);
+}
+/**
+ * Toggle HUD scene rendering. HUD widgets are canvas-relative (anchor-
+ * positioned to canvas edges), so in world edit mode — where the user is
+ * panning/zooming the world view — the HUD would float visually wrong
+ * (HUD widgets would stay glued to canvas corners regardless of editor
+ * pan). Hide HUD in world edit; show it in HUD edit (the editing surface).
+ *
+ * Phaser scene's `setVisible(false)` keeps the scene running but skips
+ * rendering. Cheap toggle.
+ */
+function setHudVisibility(game, visible) {
+    const hudScene = game.scene.getScene(UMICAT_HUD_SCENE_KEY);
+    if (!hudScene)
+        return;
+    hudScene.scene.setVisible(visible);
+}
+// --- Slice 11 Phase B.5: prefab live-edit --------------------------------
+/**
+ * Handle an `umicat:editor:editPrefab` postMessage — slice 11 B.5 / editor P0.2.
+ *
+ * Pipeline:
+ *   1. Locate the prefab in the cached manifest. Deep-merge the patch into
+ *      the record so subsequent `spawnPrefab` calls pick up the new values.
+ *   2. Walk every live instance via `EntityRegistry.byPrefabId(prefabId)`
+ *      (populated by `spawnPrefab` — instances tagged with `entityPrefabId`).
+ *   3. Re-apply visual + physics + property changes to each instance. Visual
+ *      reuses the same paths `applyEdit` uses for world entities so behavior
+ *      is consistent (Inspector edits on a world entity and on a prefab feel
+ *      identical to the user). Physics mutates the existing Arcade body
+ *      in place — no `physics.add.existing` recreate, no GameObject reuse
+ *      churn.
+ *
+ * No-op when the manifest isn't cached yet (edit fired during boot race) or
+ * the prefab id isn't declared (host should validate first, but we soft-fail).
+ */
+function handleEditPrefab(game, prefabId, patch) {
+    const manifest = readActiveManifest(game);
+    if (!manifest || !Array.isArray(manifest.prefabs)) {
+        console.warn(`[umicat/editor] editPrefab: no manifest cached, cannot apply patch for '${prefabId}'`);
+        return;
+    }
+    const idx = manifest.prefabs.findIndex((p) => p.id === prefabId);
+    if (idx < 0) {
+        console.warn(`[umicat/editor] editPrefab: no prefab with id '${prefabId}' in manifest`);
+        return;
+    }
+    // Merge patch into the cached record so subsequent spawns inherit it.
+    manifest.prefabs[idx] = mergePrefabRecord(manifest.prefabs[idx], patch);
+    // Walk live instances and re-apply each patched section. Lives in the
+    // world-scene registry (prefabs only spawn into world scenes — HUD has
+    // its own runtime).
+    const registry = findWorldScene(game) && getEntityRegistry(findWorldScene(game));
+    if (!registry)
+        return;
+    for (const go of registry.byPrefabId(prefabId)) {
+        applyPrefabPatchToInstance(game, go, patch);
+    }
+}
+function mergePrefabRecord(prev, patch) {
+    // SDK 0.3.0: render fields live at the patch root (assetId / tint / width /
+    // fillColor / params / etc.), same flat shape as the prefab record itself.
+    // Copy each render-field key that's present in the patch into the merged
+    // record. Non-render slots (physics / properties / role) stay in their
+    // own slots.
+    const merged = { ...prev };
+    const RENDER_KEYS = [
+        'assetId', 'frame', 'tint', 'alpha', 'flipX', 'flipY',
+        'width', 'height', 'radius', 'fillColor', 'strokeColor', 'strokeWidth',
+        'params',
+    ];
+    for (const k of RENDER_KEYS) {
+        const v = patch[k];
+        if (v === undefined)
+            continue;
+        if (k === 'params' && isPlainObject(merged.params) && isPlainObject(v)) {
+            merged.params = { ...merged.params, ...v };
+        }
+        else {
+            merged[k] = v;
+        }
+    }
+    if (patch.physics) {
+        merged.physics = { ...(prev.physics ?? {}), ...patch.physics };
+    }
+    if (patch.properties) {
+        merged.properties = { ...(prev.properties ?? {}), ...patch.properties };
+    }
+    if (patch.role !== undefined) {
+        if (patch.role === null)
+            delete merged.role;
+        else
+            merged.role = patch.role;
+    }
+    return merged;
+}
+/**
+ * Re-apply a prefab patch to a single live instance.
+ *
+ * Visual: same paths `applyEdit` uses for world entities — `applyVisualPatch`
+ * for sprite tint / alpha / size etc., `applyCodeRenderedParamsPatch` for
+ * render-script param re-render.
+ *
+ * Physics: mutate the existing Arcade body in place (size / offset /
+ * immovable / velocity / bounce). No recreation; no rendering change.
+ *
+ * Properties: merge into the GameObject's data-manager `entityProperties`
+ * slot so behavior code reading `go.getData('entityProperties').hp` sees
+ * the new value on next frame.
+ */
+function applyPrefabPatchToInstance(game, go, patch) {
+    // SDK 0.3.0: render fields live at the patch root. Apply them through the
+    // same paths `applyEdit` uses for world entities — `applyVisualPatch` for
+    // sprite tint / alpha / size / etc., `applyCodeRenderedParamsPatch` for
+    // render-script param re-render.
+    applyVisualPatch(go, patch);
+    applyCodeRenderedParamsPatch(game, go, patch.params);
+    if (patch.physics) {
+        applyPhysicsPatchToBody(go, patch.physics);
+    }
+    if (patch.properties) {
+        const prev = go.getData('entityProperties') ?? {};
+        go.setData('entityProperties', { ...prev, ...patch.properties });
+    }
+    if (patch.role !== undefined) {
+        go.setData('entityRole', patch.role ?? undefined);
+    }
+}
+/**
+ * Mutate an existing Arcade body with the patched physics fields.
+ *
+ * Distinct from `spawnEntity.ts`'s `applyEntityPhysics`: that one *creates*
+ * the body (calls `scene.physics.add.existing`) and computes defaults from
+ * the visual extent. This one only touches fields the patch carries — every
+ * other body property is left as-is. No body recreate, no origin shift
+ * (code-rendered origin shift only matters at body creation; size/offset
+ * patches respect the existing frame).
+ */
+function applyPhysicsPatchToBody(go, patch) {
+    const body = go.body;
+    if (!body)
+        return;
+    if (typeof patch.bodyW === 'number' || typeof patch.bodyH === 'number') {
+        body.setSize(typeof patch.bodyW === 'number' ? patch.bodyW : body.width, typeof patch.bodyH === 'number' ? patch.bodyH : body.height);
+    }
+    if (typeof patch.offsetX === 'number' || typeof patch.offsetY === 'number') {
+        body.setOffset(typeof patch.offsetX === 'number' ? patch.offsetX : body.offset.x, typeof patch.offsetY === 'number' ? patch.offsetY : body.offset.y);
+    }
+    if (typeof patch.immovable === 'boolean')
+        body.setImmovable(patch.immovable);
+    if (typeof patch.velocityX === 'number' || typeof patch.velocityY === 'number') {
+        body.setVelocity(typeof patch.velocityX === 'number' ? patch.velocityX : body.velocity.x, typeof patch.velocityY === 'number' ? patch.velocityY : body.velocity.y);
+    }
+    if (typeof patch.collideWorldBounds === 'boolean') {
+        body.setCollideWorldBounds(patch.collideWorldBounds);
+    }
+    if (typeof patch.bounceX === 'number' || typeof patch.bounceY === 'number') {
+        body.setBounce(typeof patch.bounceX === 'number' ? patch.bounceX : body.bounce.x, typeof patch.bounceY === 'number' ? patch.bounceY : body.bounce.y);
+    }
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// --- Slice 11 Phase B.5 / editor P0.3: rule live-edit --------------------
+/**
+ * Handle `umicat:editor:patchRule { path, value }` — slice 11 B.5 / P0.3.
+ *
+ * Delegates to `Rules.ts`'s `patchRule(scene, path, value)` which:
+ *  - Writes the path into the cached rules tree (subsequent `getRule`
+ *    calls return the new value).
+ *  - Fires every subscriber whose path matches or is an ancestor of the
+ *    patched path — game code that called `onRuleChange(this, 'balance.lives', cb)`
+ *    sees the new value on the next frame.
+ *
+ * Game code that read rules via `getRule` ONCE in `create()` won't see
+ * the change unless it subscribed; that's by design (most rules are
+ * configuration, not live-tunable). See SDK-GUIDE.md "Rules" chapter for
+ * the reactive subscription pattern.
+ *
+ * No-op when no world scene is loaded (edit fired during boot race).
+ */
+function handlePatchRule(game, path, value) {
+    const scene = findWorldScene(game);
+    if (!scene) {
+        console.warn(`[umicat/editor] patchRule: no world scene to patch '${path}' on`);
+        return;
+    }
+    patchRule(scene, path, value);
+}
+// --- Slice 6 Phase B — tilemap painter -----------------------------------
+function handleSetTilemapTool(game, msg) {
+    setTilemapToolState(game, {
+        tilemapEditingId: msg.tilemapEditingId,
+        activeLayerId: msg.activeLayerId,
+        tool: msg.tool,
+        activeTile: msg.activeTile,
+        activeTerrainId: msg.activeTerrainId ?? 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 async function handleEditTilemap(game, entityId, ops, manifestAsset) {
+    const scene = findWorldScene(game);
+    if (!scene) {
+        console.warn(`[umicat/editor] editTilemap: no world scene for '${entityId}'`);
+        return;
+    }
+    // Upsert + await asset load BEFORE any op runs. addLayer is the
+    // primary consumer of this; other ops (paint/erase/resize) don't
+    // need it but harmless to upsert idempotently.
+    if (manifestAsset) {
+        upsertCachedManifestAsset(scene, manifestAsset);
+        await ensureAssetLoaded(scene, manifestAsset);
+    }
+    const registry = getEntityRegistry(scene);
+    if (!registry)
+        return;
+    const container = registry.byId(entityId);
+    if (!container || !(container instanceof Phaser.GameObjects.Container)) {
+        console.warn(`[umicat/editor] editTilemap: entity '${entityId}' is not a tilemap container`);
+        return;
+    }
+    for (const op of ops) {
+        // Phase B.5 / B.6 layer-structure ops mutate the layer list / dims,
+        // not individual cell data. They take the container + scene, not a
+        // single TilemapLayer, because addLayer creates a NEW layer (no
+        // existing target), removeLayer destroys one, and resize rebuilds
+        // all layers atomically.
+        if (op.kind === 'addLayer' ||
+            op.kind === 'removeLayer' ||
+            op.kind === 'setLayerVisibility' ||
+            op.kind === 'setLayerName' ||
+            op.kind === 'resize') {
+            applyTilemapStructureOp(scene, container, op);
+            continue;
+        }
+        const layer = findTilemapLayerById(container, op.layerId);
+        if (!layer) {
+            console.warn(`[umicat/editor] editTilemap: layer '${op.layerId}' not found on tilemap '${entityId}'`);
+            continue;
+        }
+        // Resolve the layer's tileset asset once — autotilePaint needs it
+        // for the terrain lookup, sub-tile-body sync needs it after every op.
+        const layerTilesetId = layer.getData('tilemapTilesetId');
+        let layerAsset = null;
+        if (layerTilesetId) {
+            const manifest = getManifest(scene);
+            layerAsset = manifest?.assets.find((a) => a.id === layerTilesetId) ?? null;
+        }
+        applyTilemapOp(layer, op, layerAsset);
+        // Phase C follow-up — sub-tile collision rects. After any cell
+        // mutation, re-sync the layer's sub-tile static body group from the
+        // current `layer.data`. Cheap when the tileset has no collisionRect
+        // (single map scan + early return). Without this, painting a new tile
+        // with a collisionRect leaves the sub-rect body missing until next
+        // scene reload.
+        if (layerAsset) {
+            const tilesetPhaser = layer.tileset[0];
+            if (tilesetPhaser) {
+                applyTilesetTileMetadata(tilesetPhaser, layer, layerAsset);
+                // Phase F — re-arm tile animations after each paint op. A
+                // newly-painted root tile starts animating immediately.
+                applyTilesetAnimations(layer, layerAsset);
+            }
+        }
+    }
+}
+/**
+ * Layer-structure ops (add / remove / visibility) — slice 6 Phase B.5.
+ * Mutate the tilemap container's list of `TilemapLayer` children, not
+ * individual cells. Mirrors how `createTilemap` builds layers initially
+ * (in spawnEntity.ts) — same Container parent, same per-layer tagging,
+ * same centered (-w/2, -h/2) positioning.
+ */
+function applyTilemapStructureOp(scene, container, op) {
+    switch (op.kind) {
+        case 'addLayer': {
+            // Resolve tilemap entity dims (stashed by spawnEntity.tagGameObject
+            // on the container). Without these we can't size the new layer.
+            const tileSize = container.getData('tilemapTileSize');
+            const size = container.getData('tilemapSize');
+            if (!tileSize || !size) {
+                console.warn('[umicat/editor] addLayer: container missing tilemap dims');
+                return;
+            }
+            const tilesetId = op.layer.tilesetIds?.[0];
+            if (!tilesetId) {
+                console.warn(`[umicat/editor] addLayer '${op.layer.id}' has no tilesetIds`);
+                return;
+            }
+            const manifest = getManifest(scene);
+            const asset = manifest?.assets.find((a) => a.id === tilesetId);
+            if (!asset) {
+                console.warn(`[umicat/editor] addLayer: tileset '${tilesetId}' not in manifest`);
+                return;
+            }
+            if (!scene.textures.exists(asset.textureKey)) {
+                console.warn(`[umicat/editor] addLayer: tileset texture '${asset.textureKey}' not loaded; skipping`);
+                return;
+            }
+            const cellW = asset.tileset?.cellSize.width
+                ?? asset.spriteSheetConfig?.frameWidth
+                ?? asset.frameWidth
+                ?? tileSize.width;
+            const cellH = asset.tileset?.cellSize.height
+                ?? asset.spriteSheetConfig?.frameHeight
+                ?? asset.frameHeight
+                ?? tileSize.height;
+            // Build an empty grid of -1 (Phaser's "no tile" sentinel) so the
+            // new layer is immediately paintable. Same shape as Phase A's
+            // empty-layer materialization path in renderLayerInto.
+            const grid = [];
+            for (let y = 0; y < size.height; y++) {
+                grid.push(new Array(size.width).fill(-1));
+            }
+            let map;
+            try {
+                map = scene.make.tilemap({
+                    data: grid,
+                    tileWidth: cellW,
+                    tileHeight: cellH,
+                });
+            }
+            catch (e) {
+                console.warn(`[umicat/editor] addLayer: tilemap construction failed: ${String(e)}`);
+                return;
+            }
+            const tileset = map.addTilesetImage(tilesetId, asset.textureKey, cellW, cellH, asset.tileset?.margin ?? 0, asset.tileset?.spacing ?? 0);
+            if (!tileset) {
+                console.warn(`[umicat/editor] addLayer: addTilesetImage null for '${tilesetId}'`);
+                return;
+            }
+            const layerObj = map.createLayer(0, tileset, 0, 0);
+            if (!layerObj) {
+                console.warn(`[umicat/editor] addLayer: createLayer null for '${op.layer.id}'`);
+                return;
+            }
+            if (cellW !== tileSize.width || cellH !== tileSize.height) {
+                layerObj.setScale(tileSize.width / cellW, tileSize.height / cellH);
+            }
+            // Position in WORLD coords (NOT relative to container). See
+            // createTilemap for why TilemapLayers can't be Container children.
+            const pxW = size.width * tileSize.width;
+            const pxH = size.height * tileSize.height;
+            const left = -pxW / 2;
+            const top = -pxH / 2;
+            layerObj.x = container.x + left;
+            layerObj.y = container.y + top;
+            if (op.layer.visible === false)
+                layerObj.setVisible(false);
+            layerObj.setData('tilemapLayerId', op.layer.id);
+            // Stash tileset asset id so live `assetUpdate` (Tile Metadata
+            // Editor save) can find this layer + re-apply metadata.
+            layerObj.setData('tilemapTilesetId', tilesetId);
+            // Slice 6 Phase C — apply per-tile metadata + auto-collision AFTER
+            // positioning so sub-tile static bodies land at correct world
+            // coords. Calling before positioning would place bodies near world
+            // origin (the original bug visualized as collision bodies in the
+            // top-left of the canvas).
+            applyTilesetTileMetadata(tileset, layerObj, asset);
+            // Phase F — arm tile animations on this fresh layer.
+            applyTilesetAnimations(layerObj, asset);
+            // Parent-entity tag so the per-frame sync hook can find which
+            // container drives this layer's position.
+            const entityId = container.getData('entityId');
+            if (entityId)
+                layerObj.setData('tilemapEntityId', entityId);
+            layerObj.setData('tilemapLocalOffsetX', left);
+            layerObj.setData('tilemapLocalOffsetY', top);
+            // Append to the container's stashed layer refs array.
+            const layers = container.getData('tilemapLayers') ?? [];
+            layers.push(layerObj);
+            container.setData('tilemapLayers', layers);
+            break;
+        }
+        case 'removeLayer': {
+            const layer = findTilemapLayerById(container, op.layerId);
+            if (!layer)
+                return;
+            // Drop from the container's stashed layers + destroy. Layer is in
+            // scene root (not a container child), so container.remove() is wrong.
+            const layers = container.getData('tilemapLayers') ?? [];
+            const filtered = layers.filter((l) => l !== layer);
+            container.setData('tilemapLayers', filtered);
+            layer.destroy();
+            break;
+        }
+        case 'setLayerVisibility': {
+            const layer = findTilemapLayerById(container, op.layerId);
+            if (!layer)
+                return;
+            layer.setVisible(op.visible);
+            break;
+        }
+        case 'setLayerName': {
+            // Editor-only metadata — name has no runtime effect (SDK lookups
+            // are by id, never by name). Persisted to scene JSON via the host
+            // draft. No runtime mutation needed; explicit case so the dispatcher
+            // doesn't fall into the cell-op path.
+            break;
+        }
+        case 'resize': {
+            // Resize is destructive on shrink (cells outside new bounds are
+            // lost). Host UI guards with a confirm dialog when shrinking
+            // would discard painted cells — by the time the op reaches the
+            // SDK, the user has accepted the loss. We just need to rebuild
+            // every layer with the new dims, copying old cell data into the
+            // intersection of old × new bounds.
+            const tileSize = container.getData('tilemapTileSize');
+            if (!tileSize) {
+                console.warn('[umicat/editor] resize: container missing tilemapTileSize');
+                return;
+            }
+            const newW = op.width;
+            const newH = op.height;
+            if (newW <= 0 || newH <= 0)
+                return;
+            // Phase B.6.1 — handle-drag resizes shift the tilemap center to
+            // keep the opposite edge anchored. Apply BEFORE rebuilding layers
+            // so the new layers are positioned around the new center.
+            if (op.transformDelta) {
+                container.x += op.transformDelta.x;
+                container.y += op.transformDelta.y;
+                // Keep the entity-transform stash in sync so other systems (drag,
+                // selection rect, etc.) read the current pos.
+                const tx = container.getData('entityTransform');
+                if (tx) {
+                    tx.x += op.transformDelta.x;
+                    tx.y += op.transformDelta.y;
+                }
+            }
+            const oldLayers = container.getData('tilemapLayers') ?? [];
+            const snapshots = [];
+            for (const layer of oldLayers) {
+                const id = layer.getData('tilemapLayerId');
+                if (!id)
+                    continue;
+                const tileset = layer.tileset[0]; // single tileset per layer in v1
+                if (!tileset)
+                    continue;
+                const cells = [];
+                // Phaser's TilemapLayer exposes `layer.layer.data[y][x].index`.
+                const layerData = layer.layer.data;
+                for (let y = 0; y < layerData.length; y++) {
+                    const row = [];
+                    const sourceRow = layerData[y];
+                    for (let x = 0; x < sourceRow.length; x++) {
+                        const tile = sourceRow[x];
+                        row.push(tile && tile.index >= 0 ? tile.index : -1);
+                    }
+                    cells.push(row);
+                }
+                snapshots.push({
+                    id,
+                    visible: layer.visible,
+                    tilesetId: tileset.name,
+                    textureKey: tileset.image?.key ?? tileset.name,
+                    cellSize: { width: tileset.tileWidth, height: tileset.tileHeight },
+                    margin: tileset.tileMargin,
+                    spacing: tileset.tileSpacing,
+                    cells,
+                });
+                layer.destroy();
+            }
+            container.setData('tilemapLayers', []);
+            // Update size stash so subsequent ops (addLayer, etc.) see the new dims.
+            container.setData('tilemapSize', { width: newW, height: newH });
+            // Re-stamp the editor hit-test dims so clicks on the new (resized)
+            // bounds register on the entity. Without this, the container's
+            // hit-test rect stays at the original spawn dims — clicks in the
+            // new "outside-original-bounds" area would miss the entity, click
+            // fell through to empty canvas → selection clears → user thinks the
+            // tilemap "disappeared". Mirrors spawnEntity's sizeForHitTest stash
+            // which only runs at spawn time.
+            const newPxW = newW * tileSize.width;
+            const newPxH = newH * tileSize.height;
+            container.setData('editorHitWidth', newPxW);
+            container.setData('editorHitHeight', newPxH);
+            // Recreate layers with the new dims, copying clipped/padded data.
+            // Same algorithm as createTilemap's renderLayerInto, just sourcing
+            // the cell grid from the snapshot.
+            const pxW = newW * tileSize.width;
+            const pxH = newH * tileSize.height;
+            const left = -pxW / 2;
+            const top = -pxH / 2;
+            const newLayers = [];
+            for (const snap of snapshots) {
+                // Build new grid: copy intersect of (snap.cells, newW × newH).
+                const grid = [];
+                for (let y = 0; y < newH; y++) {
+                    const row = new Array(newW).fill(-1);
+                    const sourceRow = snap.cells[y];
+                    if (sourceRow) {
+                        for (let x = 0; x < Math.min(newW, sourceRow.length); x++) {
+                            row[x] = sourceRow[x];
+                        }
+                    }
+                    grid.push(row);
+                }
+                let map;
+                try {
+                    map = scene.make.tilemap({
+                        data: grid,
+                        tileWidth: snap.cellSize.width,
+                        tileHeight: snap.cellSize.height,
+                    });
+                }
+                catch (e) {
+                    console.warn(`[umicat/editor] resize: tilemap rebuild failed for layer '${snap.id}': ${String(e)}`);
+                    continue;
+                }
+                const ts = map.addTilesetImage(snap.tilesetId, snap.textureKey, snap.cellSize.width, snap.cellSize.height, snap.margin, snap.spacing);
+                if (!ts)
+                    continue;
+                const layerObj = map.createLayer(0, ts, 0, 0);
+                if (!layerObj)
+                    continue;
+                if (snap.cellSize.width !== tileSize.width || snap.cellSize.height !== tileSize.height) {
+                    layerObj.setScale(tileSize.width / snap.cellSize.width, tileSize.height / snap.cellSize.height);
+                }
+                layerObj.x = container.x + left;
+                layerObj.y = container.y + top;
+                if (!snap.visible)
+                    layerObj.setVisible(false);
+                layerObj.setData('tilemapLayerId', snap.id);
+                const entityId = container.getData('entityId');
+                if (entityId)
+                    layerObj.setData('tilemapEntityId', entityId);
+                layerObj.setData('tilemapLocalOffsetX', left);
+                layerObj.setData('tilemapLocalOffsetY', top);
+                newLayers.push(layerObj);
+            }
+            container.setData('tilemapLayers', newLayers);
+            // Redraw the background grid sketch inside the container. The
+            // grid sketch is the first non-null Graphics child of the container
+            // (added in createTilemap). We rebuild it in place to match new
+            // dims. Without this, the visual bounds would still show the
+            // pre-resize rectangle even though paintable cells are at the
+            // new dims — confusing for the user.
+            const cellsW = newW;
+            const cellsH = newH;
+            for (const child of container.list) {
+                if (child instanceof Phaser.GameObjects.Graphics) {
+                    child.clear();
+                    child.fillStyle(0xffffff, 0.04);
+                    child.fillRect(left, top, pxW, pxH);
+                    child.lineStyle(2, 0xaaaaaa, 0.45);
+                    child.strokeRect(left, top, pxW, pxH);
+                    if (tileSize.width >= 8 && cellsW * cellsH < 4000) {
+                        child.lineStyle(1, 0xaaaaaa, 0.1);
+                        for (let i = 1; i < cellsW; i++) {
+                            const x = left + i * tileSize.width;
+                            child.beginPath();
+                            child.moveTo(x, top);
+                            child.lineTo(x, top + pxH);
+                            child.strokePath();
+                        }
+                        for (let i = 1; i < cellsH; i++) {
+                            const y = top + i * tileSize.height;
+                            child.beginPath();
+                            child.moveTo(left, y);
+                            child.lineTo(left + pxW, y);
+                            child.strokePath();
+                        }
+                    }
+                    break; // only the grid sketch — there are no other Graphics children
+                }
+            }
+            break;
+        }
+    }
+}
+/**
+ * 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 function findTilemapLayerById(container, layerId) {
+    const layers = container.getData('tilemapLayers');
+    if (!layers)
+        return null;
+    for (const layer of layers) {
+        if (layer.getData('tilemapLayerId') === layerId)
+            return layer;
+    }
+    return 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 function applyTilemapOp(layer, op, asset) {
+    switch (op.kind) {
+        case 'paint':
+            for (const c of op.cells)
+                layer.putTileAt(c.index, c.x, c.y);
+            break;
+        case 'erase':
+            for (const c of op.cells)
+                layer.removeTileAt(c.x, c.y);
+            break;
+        case 'autotilePaint': {
+            const terrain = findTerrain(asset, op.terrainId);
+            if (!terrain) {
+                console.warn(`[umicat/editor] autotilePaint: tileset has no terrain '${op.terrainId}' (asset=${asset?.id ?? '<unknown>'})`);
+                return;
+            }
+            const mode = op.erase ? 'erase' : 'paint';
+            const kind = getAutotileKind(asset);
+            for (const c of op.cells)
+                applyAutotile(layer, c.x, c.y, terrain, mode, kind);
+            break;
+        }
+        case 'fillRect':
+            if (typeof op.index === 'number') {
+                layer.fill(op.index, op.x, op.y, op.w, op.h);
+            }
+            else {
+                // No index → erase-rect. Phaser's `fill` with -1 sets every cell
+                // in the region to "no tile", same effect as removeTileAt per cell.
+                layer.fill(-1, op.x, op.y, op.w, op.h);
+            }
+            break;
+        case 'bucketFill': {
+            // Phaser doesn't ship a flood-fill primitive — walk the layer ourselves
+            // from the seed cell, replacing matching cells 4-connected. Bounded by
+            // layer dims so degenerate input (huge layer all one tile) doesn't
+            // run unbounded.
+            const seed = layer.getTileAt(op.x, op.y, true);
+            const startIndex = seed ? seed.index : -1;
+            if (startIndex === op.index)
+                return; // already painted with target
+            const w = layer.tilemap.width;
+            const h = layer.tilemap.height;
+            const stack = [[op.x, op.y]];
+            let safety = 0;
+            while (stack.length > 0 && safety++ < w * h) {
+                const [cx, cy] = stack.pop();
+                if (cx < 0 || cy < 0 || cx >= w || cy >= h)
+                    continue;
+                const tile = layer.getTileAt(cx, cy, true);
+                const idx = tile ? tile.index : -1;
+                if (idx !== startIndex)
+                    continue;
+                layer.putTileAt(op.index, cx, cy);
+                stack.push([cx + 1, cy], [cx - 1, cy], [cx, cy + 1], [cx, cy - 1]);
+            }
+            break;
+        }
+    }
+}
+// --- postMessage helper ---------------------------------------------------
+function postToHost(msg) {
+    if (typeof window === 'undefined' || !window.parent)
+        return;
+    window.parent.postMessage(msg, '*');
+}