@unboxy/phaser-sdk 0.2.16 → 0.2.18

package/SDK-GUIDE.md

@@ -544,6 +544,88 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 - Unsubscribe on scene shutdown. `onStateChange`, `on`, `onLeave`, `onError` all return an unsubscribe function — call them from `scene.events.once('shutdown', ...)`.
 - One Colyseus client is kept internally; repeated `joinOrCreate` calls reuse it and mint fresh tokens each connection.
 
+## Scene-as-data (visual editor foundation, since 0.2.17)
+
+Games that ship with `public/scenes/manifest.json` load layout from JSON instead of hardcoding `this.add.sprite(x, y, ...)` in scene classes. This split is what lets the visual editor edit a game without touching code.
+
+**File layout:**
+```
+src/scenes/
+  BootScene.ts            — preloads manifest, draws loading bar, starts GameScene
+  GameScene.ts            — generic loader: await loadWorldScene(this, sceneId)
+public/scenes/
+  manifest.json           — scenes list + asset table + initial scene id
+  world/<scene>.json      — one world scene per file (entities, camera, world dims)
+```
+
+**Manifest shape:**
+```json
+{
+  "schemaVersion": 1,
+  "id": "my-game", "title": "My Game", "version": "1.0.0",
+  "initialScene": "main",
+  "scenes":  [{ "id": "main", "type": "world", "file": "world/main.json", "hud": null }],
+  "huds":    [],
+  "assets":  [
+    { "id": "knight", "textureKey": "knight", "path": "uploaded/knight.png", "kind": "image" },
+    { "id": "tiles",  "textureKey": "tiles",  "path": "uploaded/tiles.png",
+      "kind": "spritesheet",
+      "spriteSheetConfig": { "frameWidth": 16, "frameHeight": 16 } }
+  ]
+}
+```
+
+The `assets[]` table is the single source of truth for asset loading in scene-as-data games. Replaces hand-rolled `BootScene.preload()` lines: `loadWorldScene` queues the right `this.load.*` call based on each asset's `kind` and config (lazy — only assets the active scene uses).
+
+**Entity shape (world scenes):**
+```json
+{
+  "id": "player",
+  "kind": "sprite",
+  "role": "player",
+  "transform": { "x": 200, "y": 400, "rotation": 0, "scaleX": 1, "scaleY": 1 },
+  "visual": { "kind": "sprite", "assetId": "knight" },
+  "properties": { "maxHp": 3, "speed": 200 }
+}
+```
+
+`kind` is the entity-kind discriminator (`sprite` / `primitive` / `group` / `code-rendered` / `tilemap` / `trigger` — last three not in v1). `visual.kind` is the visual variant (`sprite` / `rect` / `circle` / `code-rendered`). They are separate fields with separate enums.
+
+**API:**
+```ts
+import { preloadManifest, getManifest, loadWorldScene, getEntityRegistry } from '@unboxy/phaser-sdk';
+
+class BootScene extends Phaser.Scene {
+  preload() { preloadManifest(this); /* + draw loading bar */ }
+  create() {
+    const manifest = getManifest(this);
+    this.scene.start('GameScene', { sceneId: manifest.initialScene });
+  }
+}
+
+class GameScene extends Phaser.Scene {
+  private sceneId!: string;
+  init(data: { sceneId: string }) { this.sceneId = data.sceneId; }
+  async create() {
+    await loadWorldScene(this, this.sceneId);  // spawns entities, applies camera
+    const registry = getEntityRegistry(this)!;
+    const player = registry.byRole('player')[0] as Phaser.GameObjects.Sprite;
+    // ...wire physics + input on `player`...
+  }
+}
+```
+
+**Behavior conventions:**
+- Layout (positions, asset references, world dims, camera bounds) lives in scene JSON.
+- Behavior (physics setup, input handlers, update loop, tweens) lives in `GameScene.ts`.
+- Look entities up by `role` (`registry.byRole('player')`) — portable across scenes. By id (`registry.byId('boss-1')`) when you need a specific one.
+- Don't hand-write `this.load.image(...)` lines for game assets — declare them in `manifest.assets[]`.
+- Don't call `this.add.sprite(...)` for game entities in code — declare them in scene JSON.
+
+The `scene-data-architecture` agent skill has the full guidance. The `scene-data-migration` skill walks an existing scene-as-code game through the conversion.
+
+**Edit mode (host-driven):** when the host (home-ui) sends `{ type: 'unboxy:setEditMode', enabled: true }` via `postMessage`, the SDK pauses every active non-Boot Phaser scene — entities stay rendered but `update`/physics/tweens stop. Sending `enabled: false` resumes. Used by the visual editor's read-only viewer in slice 1.
+
 ## Anti-patterns (don't do these)
 
 - Do **not** call `Unboxy.init()` inside a scene. Initialize at module load in `main.ts` and export the promise.
@@ -556,6 +638,8 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **0.2.18** — added editor bridge (visual editor slice 2). Replaces the slice-1 `unboxy:setEditMode` message with a full editor protocol: `unboxy:editor:enter`/`:exit` (toggles edit mode + launches the overlay scene), `:applyEdit` (mutates a live entity from the host), `:setSelection` (host pushes selection), `:panZoom` (editor camera control), plus SDK→host `:sceneLoaded` (initial snapshot), `:pickEntity` (pointer-down selection), `:dragEnd` (entity dragged to new position). New module `src/editor/` with `EditorOverlayScene` (high-depth Phaser.Scene drawing selection rect + world bounds, capturing pointer events) and `EditorBridge` (postMessage handler + applyEdit logic). New exports: `setupEditorBridge`, `EditorOverlayScene`, `EDITOR_OVERLAY_KEY`, plus all editor protocol types. `setupEditorModeListener` is preserved as a thin wrapper that delegates to the bridge so existing `createUnboxyGame` wiring continues to work. Pairs with home-ui's new Hierarchy + Inspector panels and `useEditorDraft` hook.
+- **0.2.17** — added scene-as-data foundation (visual editor slice 1). New exports: `loadWorldScene`, `preloadManifest`, `getManifest`, `preloadSceneAssets`, `spawnEntity`, `EntityRegistry`, `attachEntityRegistry`, `getEntityRegistry`, `setupEditorModeListener`, `isEditMode`, `parseColor`, `SCHEMA_VERSION`, plus all schema types (`Manifest`, `WorldScene`, `WorldEntity`, `Transform`, `AssetRecord`, etc.). New games that ship with `public/scenes/manifest.json` load entities + camera config from JSON; `GameScene.ts` becomes a generic loader that calls `await loadWorldScene(this, sceneId)`. `createUnboxyGame` now also wires `setupEditorModeListener` so the host (home-ui) can pause active scenes via `postMessage({ type: 'unboxy:setEditMode', enabled: boolean })`. Purely additive — existing scene-as-code games are unaffected. Migration to scene-as-data is opt-in via the `scene-data-migration` agent skill.
 - **0.2.16** — added orientation presets. `createUnboxyGame` now accepts an `orientation: 'portrait' | 'landscape'` option as an alternative to explicit `width`/`height` (TS union — pass one or the other). New exports: `Orientation` type and `ORIENTATION_DIMENSIONS` map (`landscape: 1280×720`, `portrait: 720×1280`). Lets games declare orientation once and have a single source of truth for canvas dimensions.
 - **0.2.15** — fix: `ChatFacade.subscribeToPlayers` early-returned when `state.players` was `undefined` at construction time, which it always is on a fresh `joinOrCreate` (Colyseus delivers initial state as a separate message a few ms later). The early return meant `onStateChange` never subscribed and `system.joined` / `system.left` stayed silent in production despite the 0.2.14 callback-API fix. Now: always subscribe; treat the first state change as initial hydration (silent), subsequent changes do real diff. Three regression tests cover the deferred-hydration flow.
 - **0.2.14** — fix: `ChatFacade` `system.joined` / `system.left` events were silently no-op'ing in production. The lifecycle subscription used `state.players.onAdd` / `.onRemove` instance methods that Colyseus 0.16 removed in favour of `getStateCallbacks(room)`; the runtime check `typeof players.onAdd === 'function'` evaluated false, so neither system message fired. Now uses `room.onStateChange` + a known-names diff — robust to future Colyseus API changes. Tests updated to match. Patch-only; no API change for game code.

package/dist/core/UnboxyGame.js

@@ -1,6 +1,7 @@
 import Phaser from 'phaser';
 import { setupScreenshotListener } from '../screenshot/ScreenshotManager.js';
 import { setupRecordingListener } from '../recording/RecordingManager.js';
+import { setupEditorModeListener } from '../scene/EditorMode.js';
 import { ORIENTATION_DIMENSIONS } from '../orientation.js';
 /**
  * Create an Unboxy-enhanced Phaser game instance.
@@ -34,5 +35,6 @@ export function createUnboxyGame(options) {
     // Built-in integrations
     setupScreenshotListener(game);
     setupRecordingListener(game);
+    setupEditorModeListener(game);
     return game;
 }

package/dist/editor/EditorBridge.d.ts

@@ -0,0 +1,2 @@
+import Phaser from 'phaser';
+export declare function setupEditorBridge(game: Phaser.Game): void;

package/dist/editor/EditorBridge.js

@@ -0,0 +1,295 @@
+import { getEntityRegistry } from '../scene/EntityRegistry.js';
+import { parseColor } from '../scene/spawnEntity.js';
+import { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './EditorOverlayScene.js';
+import { getEditorState, setEditorActive, setSelection, } from './EditorState.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('unboxy:editor:'))
+            return;
+        handleMessage(game, data);
+    });
+}
+function handleMessage(game, msg) {
+    switch (msg.type) {
+        case 'unboxy:editor:enter':
+            enterEdit(game);
+            break;
+        case 'unboxy:editor:exit':
+            exitEdit(game);
+            break;
+        case 'unboxy:editor:getScene':
+            postSceneSnapshot(game);
+            break;
+        case 'unboxy:editor:applyEdit':
+            applyEdit(game, msg.entityId, msg.patch);
+            break;
+        case 'unboxy:editor:setSelection':
+            setSelection(game, msg.entityIds[0] ?? null);
+            break;
+        case 'unboxy:editor:panZoom':
+            applyPanZoom(game, msg);
+            break;
+    }
+}
+// --- Enter / exit ---------------------------------------------------------
+function enterEdit(game) {
+    if (getEditorState(game).active)
+        return;
+    setEditorActive(game, true);
+    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())
+            scene.scene.pause();
+    }
+    // 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);
+    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);
+}
+function exitEdit(game) {
+    if (!getEditorState(game).active)
+        return;
+    setEditorActive(game, false);
+    setSelection(game, null);
+    if (game.scene.isActive(EDITOR_OVERLAY_KEY)) {
+        game.scene.stop(EDITOR_OVERLAY_KEY);
+    }
+    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.isPaused())
+            scene.scene.resume();
+    }
+}
+function buildOverlayInit(game) {
+    const sceneFile = readActiveSceneFile(game);
+    return {
+        worldBounds: sceneFile
+            ? { x: 0, y: 0, width: sceneFile.world.width, height: sceneFile.world.height }
+            : undefined,
+        hitTest: (worldX, worldY) => hitTest(game, worldX, worldY),
+        postPick: (entityId, modifiers) => postToHost({
+            type: 'unboxy:editor:pickEntity',
+            entityId,
+            modifiers,
+        }),
+        postDragEnd: (entityId, before, after) => postToHost({
+            type: 'unboxy:editor:dragEnd',
+            entityId,
+            before,
+            after,
+        }),
+    };
+}
+// --- Snapshot -------------------------------------------------------------
+function postSceneSnapshot(game) {
+    const sceneFile = readActiveSceneFile(game);
+    if (!sceneFile)
+        return;
+    postToHost({
+        type: 'unboxy:editor:sceneLoaded',
+        sceneId: sceneFile.id,
+        sceneFile,
+    });
+}
+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 `unboxy: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 'unboxy: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('unboxy: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 withBounds = go;
+        if (typeof withBounds.getBounds !== 'function')
+            continue;
+        const r = withBounds.getBounds();
+        if (worldX < r.x || worldX > r.x + r.width)
+            continue;
+        if (worldY < r.y || worldY > r.y + r.height)
+            continue;
+        const depth = typeof withBounds.depth === 'number' ? withBounds.depth : 0;
+        if (depth >= topmostDepth) {
+            topmostDepth = depth;
+            topmost = go;
+        }
+    }
+    return topmost;
+}
+function findRegistry(game) {
+    for (const scene of game.scene.getScenes(false)) {
+        const reg = getEntityRegistry(scene);
+        if (reg)
+            return reg;
+    }
+    return undefined;
+}
+// --- applyEdit ------------------------------------------------------------
+function applyEdit(game, entityId, patch) {
+    const registry = findRegistry(game);
+    if (!registry)
+        return;
+    const go = registry.byId(entityId);
+    if (!go)
+        return;
+    applyTransformPatch(go, patch.transform);
+    applyVisualPatch(go, patch.visual);
+    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);
+    }
+}
+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);
+}
+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));
+        }
+    }
+}
+// --- Pan / zoom -----------------------------------------------------------
+function applyPanZoom(game, msg) {
+    // Apply to BOTH the world scene's camera (so the entity rendering moves)
+    // and the overlay scene's camera (so handles draw at the right place).
+    for (const scene of game.scene.getScenes(false)) {
+        if (BOOT_SCENE_KEYS.has(scene.scene.key))
+            continue;
+        const cam = scene.cameras.main;
+        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') {
+            const z = Math.max(0.25, Math.min(2, msg.zoom));
+            cam.setZoom(z);
+        }
+    }
+}
+// --- postMessage helper ---------------------------------------------------
+function postToHost(msg) {
+    if (typeof window === 'undefined' || !window.parent)
+        return;
+    window.parent.postMessage(msg, '*');
+}

package/dist/editor/EditorOverlayScene.d.ts

@@ -0,0 +1,72 @@
+import Phaser from 'phaser';
+/**
+ * Editor overlay — slice 2.
+ *
+ * Runs ABOVE the world/HUD scenes. Its job:
+ *
+ * 1. Render selection rectangle around the currently selected entity
+ * 2. Render world bounds rectangle (visual cue for "edge of the game world")
+ * 3. Capture pointer events:
+ *    - pointerdown on an entity → posts pickEntity to host
+ *    - drag → mutates the entity's x/y in real time (visual only)
+ *    - pointerup → posts dragEnd with before/after to host
+ *
+ * The overlay scene is launched by EditorBridge when entering Edit mode,
+ * stopped on exit. It holds no persistent state of its own — selection +
+ * drag info live in the shared EditorState attached to the Phaser game.
+ */
+export declare const EDITOR_OVERLAY_KEY = "__UnboxyEditorOverlay";
+interface EditorOverlayInitData {
+    /** World bounds rect to draw (slice 2 draws but doesn't allow editing). */
+    worldBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Callback to resolve the entity at a given world point. Provided by the
+     * EditorBridge so the overlay doesn't have to know about the EntityRegistry.
+     * Returns the topmost (highest depth) entity at that point or null.
+     */
+    hitTest: (worldX: number, worldY: number) => Phaser.GameObjects.GameObject | null;
+    /** postMessage helpers (so the scene can send pickEntity / dragEnd). */
+    postPick: (entityId: string | null, modifiers: {
+        shift: boolean;
+        cmdOrCtrl: boolean;
+        alt: boolean;
+    }) => void;
+    postDragEnd: (entityId: string, before: {
+        x: number;
+        y: number;
+    }, after: {
+        x: number;
+        y: number;
+    }) => void;
+}
+export declare class EditorOverlayScene extends Phaser.Scene {
+    private graphics;
+    private worldBounds?;
+    private hitTest;
+    private postPick;
+    private postDragEnd;
+    constructor();
+    init(data: EditorOverlayInitData): void;
+    create(): void;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    update(): void;
+    /**
+     * Find the world scene's main camera so the overlay can mirror it.
+     * In edit mode, the world scene is paused but its camera state is what
+     * the overlay's pointer math should use.
+     */
+    private findWorldSceneCamera;
+    /**
+     * The EntityRegistry lives on the world scene. Pull it from there so we
+     * don't have to plumb registry references through the bridge.
+     */
+    private findEntityRegistry;
+}
+export {};

package/dist/editor/EditorOverlayScene.js

@@ -0,0 +1,158 @@
+import Phaser from 'phaser';
+import { getEntityRegistry } from '../scene/EntityRegistry.js';
+import { getEditorState, startDrag, clearDrag, getDrag, getSelection, } from './EditorState.js';
+/**
+ * Editor overlay — slice 2.
+ *
+ * Runs ABOVE the world/HUD scenes. Its job:
+ *
+ * 1. Render selection rectangle around the currently selected entity
+ * 2. Render world bounds rectangle (visual cue for "edge of the game world")
+ * 3. Capture pointer events:
+ *    - pointerdown on an entity → posts pickEntity to host
+ *    - drag → mutates the entity's x/y in real time (visual only)
+ *    - pointerup → posts dragEnd with before/after to host
+ *
+ * The overlay scene is launched by EditorBridge when entering Edit mode,
+ * stopped on exit. It holds no persistent state of its own — selection +
+ * drag info live in the shared EditorState attached to the Phaser game.
+ */
+export const EDITOR_OVERLAY_KEY = '__UnboxyEditorOverlay';
+const SELECTION_COLOR = 0x4662d8;
+const SELECTION_ALPHA = 1;
+const SELECTION_LINE_WIDTH = 2;
+const WORLD_BOUNDS_COLOR = 0x888888;
+const WORLD_BOUNDS_ALPHA = 0.5;
+export class EditorOverlayScene extends Phaser.Scene {
+    constructor() {
+        super({ key: EDITOR_OVERLAY_KEY });
+    }
+    init(data) {
+        this.worldBounds = data.worldBounds;
+        this.hitTest = data.hitTest;
+        this.postPick = data.postPick;
+        this.postDragEnd = data.postDragEnd;
+    }
+    create() {
+        this.graphics = this.add.graphics();
+        // Mirror the world scene's camera so editor overlay draws in world coords.
+        // The host (home-ui) will pan/zoom this camera via panZoom postMessages.
+        const worldCam = this.findWorldSceneCamera();
+        if (worldCam) {
+            this.cameras.main.setScroll(worldCam.scrollX, worldCam.scrollY);
+            this.cameras.main.setZoom(worldCam.zoom);
+        }
+        this.input.on('pointerdown', this.handlePointerDown, this);
+        this.input.on('pointermove', this.handlePointerMove, this);
+        this.input.on('pointerup', this.handlePointerUp, this);
+    }
+    handlePointerDown(pointer) {
+        const state = getEditorState(this.game);
+        if (!state.active)
+            return;
+        const wx = pointer.worldX;
+        const wy = pointer.worldY;
+        const hit = this.hitTest(wx, wy);
+        const event = pointer.event;
+        const modifiers = {
+            shift: !!event?.shiftKey,
+            cmdOrCtrl: !!(event?.metaKey || event?.ctrlKey),
+            alt: !!event?.altKey,
+        };
+        if (!hit) {
+            this.postPick(null, modifiers);
+            return;
+        }
+        const entityId = hit.getData('entityId');
+        if (!entityId) {
+            this.postPick(null, modifiers);
+            return;
+        }
+        this.postPick(entityId, modifiers);
+        // Begin drag immediately on pointerdown (drag threshold can be added later).
+        const target = hit;
+        startDrag(this.game, entityId, { x: wx, y: wy }, { x: target.x, y: target.y });
+    }
+    handlePointerMove(pointer) {
+        const drag = getDrag(this.game);
+        if (!drag)
+            return;
+        const registry = this.findEntityRegistry();
+        if (!registry)
+            return;
+        const go = registry.byId(drag.entityId);
+        if (!go)
+            return;
+        const dx = pointer.worldX - drag.startWorld.x;
+        const dy = pointer.worldY - drag.startWorld.y;
+        go.x = drag.startEntity.x + dx;
+        go.y = drag.startEntity.y + dy;
+    }
+    handlePointerUp(pointer) {
+        const drag = getDrag(this.game);
+        if (!drag)
+            return;
+        const dx = pointer.worldX - drag.startWorld.x;
+        const dy = pointer.worldY - drag.startWorld.y;
+        const before = drag.startEntity;
+        const after = { x: drag.startEntity.x + dx, y: drag.startEntity.y + dy };
+        clearDrag(this.game);
+        // Suppress dragEnd for trivial "click without movement" — the host already
+        // got pickEntity for those.
+        if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5)
+            return;
+        this.postDragEnd(drag.entityId, before, after);
+    }
+    update() {
+        this.graphics.clear();
+        if (this.worldBounds) {
+            this.graphics.lineStyle(2, WORLD_BOUNDS_COLOR, WORLD_BOUNDS_ALPHA);
+            this.graphics.strokeRect(this.worldBounds.x, this.worldBounds.y, this.worldBounds.width, this.worldBounds.height);
+        }
+        const selectedId = getSelection(this.game);
+        if (selectedId) {
+            const registry = this.findEntityRegistry();
+            const go = registry?.byId(selectedId);
+            if (go) {
+                const bounds = computeBounds(go);
+                if (bounds) {
+                    this.graphics.lineStyle(SELECTION_LINE_WIDTH, SELECTION_COLOR, SELECTION_ALPHA);
+                    this.graphics.strokeRect(bounds.x, bounds.y, bounds.width, bounds.height);
+                }
+            }
+        }
+    }
+    /**
+     * Find the world scene's main camera so the overlay can mirror it.
+     * In edit mode, the world scene is paused but its camera state is what
+     * the overlay's pointer math should use.
+     */
+    findWorldSceneCamera() {
+        for (const scene of this.game.scene.getScenes(false)) {
+            if (scene.scene.key === 'GameScene') {
+                return scene.cameras.main;
+            }
+        }
+        return null;
+    }
+    /**
+     * The EntityRegistry lives on the world scene. Pull it from there so we
+     * don't have to plumb registry references through the bridge.
+     */
+    findEntityRegistry() {
+        for (const scene of this.game.scene.getScenes(false)) {
+            const reg = getEntityRegistry(scene);
+            if (reg)
+                return reg;
+        }
+        return undefined;
+    }
+}
+function computeBounds(go) {
+    // Most game objects implement getBounds; Container does too.
+    const withBounds = go;
+    if (typeof withBounds.getBounds !== 'function')
+        return null;
+    const r = withBounds.getBounds();
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+}