@unboxy/phaser-sdk 0.2.17 → 0.2.18

package/SDK-GUIDE.md

@@ -638,6 +638,7 @@ The `scene-data-architecture` agent skill has the full guidance. The `scene-data
 
 ## 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.

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 };
+}

package/dist/editor/EditorState.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-game editor state, shared between EditorBridge (postMessage handler)
+ * and EditorOverlayScene (canvas renderer + pointer source).
+ *
+ * Design 03 §13.5: in Edit mode the editor overlay captures clicks before
+ * they reach game systems; this state carries the selection + drag-in-progress
+ * info both sides read.
+ */
+interface EditorStateShape {
+    active: boolean;
+    selectedId: string | null;
+    /**
+     * Drag-in-progress info. While set, the overlay scene mutates the entity's
+     * x/y directly per pointermove without going through the host. On
+     * pointerup it posts dragEnd with before/after, and the host pushes a
+     * single command. This is the "SDK holds short-lived visual state" path
+     * from the slice-2 design discussion.
+     */
+    drag: {
+        entityId: string;
+        startWorld: {
+            x: number;
+            y: number;
+        };
+        startEntity: {
+            x: number;
+            y: number;
+        };
+    } | null;
+}
+/**
+ * Accept any object — we only use a single internal symbol-style key, so
+ * there's no risk of collision with Phaser's own props.
+ */
+type AnyObject = object;
+export declare function getEditorState(game: AnyObject): EditorStateShape;
+export declare function setEditorActive(game: AnyObject, active: boolean): void;
+export declare function setSelection(game: AnyObject, id: string | null): void;
+export declare function getSelection(game: AnyObject): string | null;
+export declare function startDrag(game: AnyObject, entityId: string, startWorld: {
+    x: number;
+    y: number;
+}, startEntity: {
+    x: number;
+    y: number;
+}): void;
+export declare function clearDrag(game: AnyObject): void;
+export declare function getDrag(game: AnyObject): EditorStateShape['drag'];
+export {};

package/dist/editor/EditorState.js

@@ -0,0 +1,39 @@
+/**
+ * Per-game editor state, shared between EditorBridge (postMessage handler)
+ * and EditorOverlayScene (canvas renderer + pointer source).
+ *
+ * Design 03 §13.5: in Edit mode the editor overlay captures clicks before
+ * they reach game systems; this state carries the selection + drag-in-progress
+ * info both sides read.
+ */
+const KEY = '__unboxyEditorState';
+function bag(game) {
+    return game;
+}
+export function getEditorState(game) {
+    const b = bag(game);
+    const existing = b[KEY];
+    if (existing)
+        return existing;
+    const fresh = { active: false, selectedId: null, drag: null };
+    b[KEY] = fresh;
+    return fresh;
+}
+export function setEditorActive(game, active) {
+    getEditorState(game).active = active;
+}
+export function setSelection(game, id) {
+    getEditorState(game).selectedId = id;
+}
+export function getSelection(game) {
+    return getEditorState(game).selectedId;
+}
+export function startDrag(game, entityId, startWorld, startEntity) {
+    getEditorState(game).drag = { entityId, startWorld, startEntity };
+}
+export function clearDrag(game) {
+    getEditorState(game).drag = null;
+}
+export function getDrag(game) {
+    return getEditorState(game).drag;
+}

package/dist/index.d.ts

@@ -22,6 +22,9 @@ export { spawnEntity, parseColor } from './scene/spawnEntity.js';
 export type { SpawnContext, AssetResolver, RenderScriptResolver, } from './scene/spawnEntity.js';
 export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
 export { setupEditorModeListener, isEditMode } from './scene/EditorMode.js';
+export { setupEditorBridge } from './editor/EditorBridge.js';
+export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
+export type { EditorEntityPatch, EditorEnterMessage, EditorExitMessage, EditorGetSceneMessage, EditorApplyEditMessage, EditorSetSelectionMessage, EditorPanZoomMessage, EditorHostToSdkMessage, EditorSceneLoadedMessage, EditorSelectionPickedMessage, EditorDragEndMessage, EditorSdkToHostMessage, } from './protocol.js';
 export { SCHEMA_VERSION, } from './scene/types.js';
 export type { Manifest, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, SpriteEntity, PrimitiveEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TriggerEntity, WorldVisual, SpriteVisual, PrimitiveVisual, PrimitiveRectVisual, PrimitiveCircleVisual, CodeRenderedVisual, Transform, Anchor, AnchorSide, } from './scene/types.js';
 export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, type RealtimeGetTokenParams, type RealtimeGetTokenResult, } from './protocol.js';

package/dist/index.js

@@ -18,5 +18,7 @@ export { loadWorldScene, preloadManifest, preloadSceneAssets, getManifest, SCENE
 export { spawnEntity, parseColor } from './scene/spawnEntity.js';
 export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scene/EntityRegistry.js';
 export { setupEditorModeListener, isEditMode } from './scene/EditorMode.js';
+export { setupEditorBridge } from './editor/EditorBridge.js';
+export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
 export { SCHEMA_VERSION, } from './scene/types.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/protocol.d.ts

@@ -46,6 +46,102 @@ export interface RpcResultError {
     error: RpcErrorPayload;
 }
 export type HostToSdkMessage = InitMessage | RpcResultOk | RpcResultError;
+/**
+ * Patch shape applied to a live entity. Only the fields present are updated;
+ * `null` is the explicit clear (drops the field). The patch mirrors the slice
+ * of the entity schema the editor edits in slice 2 — transform + simple
+ * visual fields. Properties / behavior wiring extend this in later slices.
+ */
+export interface EditorEntityPatch {
+    transform?: Partial<{
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+        depth: number;
+    }>;
+    visual?: {
+        tint?: string | null;
+        alpha?: number;
+        flipX?: boolean;
+        flipY?: boolean;
+        frame?: string | number;
+        /** For primitives. */
+        width?: number;
+        height?: number;
+        radius?: number;
+        fillColor?: string;
+        strokeColor?: string | null;
+        strokeWidth?: number;
+    };
+    role?: string | null;
+    properties?: Record<string, unknown>;
+}
+export interface EditorEnterMessage {
+    type: 'unboxy:editor:enter';
+}
+export interface EditorExitMessage {
+    type: 'unboxy:editor:exit';
+}
+export interface EditorGetSceneMessage {
+    /** Host requests a snapshot of what's currently loaded in the iframe. */
+    type: 'unboxy:editor:getScene';
+}
+export interface EditorApplyEditMessage {
+    type: 'unboxy:editor:applyEdit';
+    entityId: string;
+    patch: EditorEntityPatch;
+}
+export interface EditorSetSelectionMessage {
+    type: 'unboxy:editor:setSelection';
+    /** Empty array deselects. v1: max length 1 (multi-select is slice 2.5). */
+    entityIds: string[];
+}
+export interface EditorPanZoomMessage {
+    /** Editor camera control — separate from in-game camera. */
+    type: 'unboxy:editor:panZoom';
+    scrollX?: number;
+    scrollY?: number;
+    /** Absolute zoom (1 = 100%). */
+    zoom?: number;
+    /** If true, deltas are added to current scroll. */
+    relative?: boolean;
+}
+export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage;
+export interface EditorSceneLoadedMessage {
+    type: 'unboxy:editor:sceneLoaded';
+    sceneId: string;
+    /** Snapshot of the world scene file's current entities + camera. */
+    sceneFile: unknown;
+}
+export interface EditorSelectionPickedMessage {
+    /** Pointer-down on an entity in the canvas — host should update selection. */
+    type: 'unboxy:editor:pickEntity';
+    entityId: string | null;
+    /** Modifier keys at pointer-down so host can decide single/toggle/range. */
+    modifiers: {
+        shift: boolean;
+        cmdOrCtrl: boolean;
+        alt: boolean;
+    };
+}
+export interface EditorDragEndMessage {
+    /** Pointer-up after dragging an entity. delta is total movement in world coords. */
+    type: 'unboxy:editor:dragEnd';
+    entityId: string;
+    /** Position before drag started. */
+    before: {
+        x: number;
+        y: number;
+    };
+    /** Position at release. */
+    after: {
+        x: number;
+        y: number;
+    };
+}
+export type EditorSdkToHostMessage = EditorSceneLoadedMessage | EditorSelectionPickedMessage | EditorDragEndMessage;
 export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list' | 'realtime.getToken';
 export interface SavesGetParams {
     key: string;

package/dist/scene/EditorMode.d.ts

@@ -1,3 +1,17 @@
 import Phaser from 'phaser';
+/**
+ * Slice-1 entry point that became a thin wrapper over the slice-2 editor
+ * bridge. The bridge owns the full edit-mode lifecycle (pause world scenes,
+ * launch overlay, handle pointer events, route postMessage commands).
+ *
+ * Wire shape (host → SDK):
+ *   { type: 'unboxy:editor:enter' }   - enter edit mode
+ *   { type: 'unboxy:editor:exit'  }   - exit edit mode
+ *   ...plus the rest of the editor protocol — see protocol.ts
+ *
+ * The slice-1 `unboxy:setEditMode` message is no longer accepted; home-ui
+ * has been updated to send the editor:enter / editor:exit pair as part of
+ * the slice-2 work.
+ */
 export declare function setupEditorModeListener(game: Phaser.Game): void;
 export declare function isEditMode(game: Phaser.Game): boolean;

package/dist/scene/EditorMode.js

@@ -1,57 +1,22 @@
+import { setupEditorBridge } from '../editor/EditorBridge.js';
+import { getEditorState } from '../editor/EditorState.js';
 /**
- * Edit mode = pause every active world/HUD scene so the canvas freezes
- * but stays rendered. The visual editor uses this for slice 1's
- * read-only viewer; later slices add overlay/gizmo layers on top.
+ * Slice-1 entry point that became a thin wrapper over the slice-2 editor
+ * bridge. The bridge owns the full edit-mode lifecycle (pause world scenes,
+ * launch overlay, handle pointer events, route postMessage commands).
  *
- * Wire shape (host → SDK only — no reply expected):
- *   { type: 'unboxy:setEditMode', enabled: boolean }
+ * Wire shape (host → SDK):
+ *   { type: 'unboxy:editor:enter' }   - enter edit mode
+ *   { type: 'unboxy:editor:exit'  }   - exit edit mode
+ *   ...plus the rest of the editor protocol — see protocol.ts
  *
- * Boot scenes are skipped — pausing them stalls the loader.
+ * The slice-1 `unboxy:setEditMode` message is no longer accepted; home-ui
+ * has been updated to send the editor:enter / editor:exit pair as part of
+ * the slice-2 work.
  */
-const BOOT_SCENE_KEYS = new Set(['BootScene', 'Boot']);
-const EDIT_MODE_FLAG = '__unboxyEditMode';
 export function setupEditorModeListener(game) {
-    window.addEventListener('message', (event) => {
-        const data = event.data;
-        if (!data || typeof data !== 'object')
-            return;
-        if (data.type !== 'unboxy:setEditMode')
-            return;
-        const enabled = !!data.enabled;
-        if (enabled)
-            enterEditMode(game);
-        else
-            exitEditMode(game);
-    });
+    setupEditorBridge(game);
 }
 export function isEditMode(game) {
-    return !!game[EDIT_MODE_FLAG];
-}
-function enterEditMode(game) {
-    const flagged = game;
-    if (flagged[EDIT_MODE_FLAG])
-        return;
-    flagged[EDIT_MODE_FLAG] = true;
-    for (const scene of game.scene.getScenes(true)) {
-        const key = scene.scene.key;
-        if (BOOT_SCENE_KEYS.has(key))
-            continue;
-        // Phaser's pause() stops update + physics + tweens but leaves the
-        // scene rendered — exactly what the read-only viewer wants.
-        if (scene.scene.isActive())
-            scene.scene.pause();
-    }
-}
-function exitEditMode(game) {
-    const flagged = game;
-    if (!flagged[EDIT_MODE_FLAG])
-        return;
-    flagged[EDIT_MODE_FLAG] = false;
-    for (const scene of game.scene.getScenes(false)) {
-        const key = scene.scene.key;
-        if (BOOT_SCENE_KEYS.has(key))
-            continue;
-        if (scene.scene.isPaused())
-            scene.scene.resume();
-    }
+    return getEditorState(game).active;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",