@unboxy/phaser-sdk 0.2.18 → 0.2.20

package/SDK-GUIDE.md

@@ -638,6 +638,7 @@ The `scene-data-architecture` agent skill has the full guidance. The `scene-data
 
 ## Changelog
 
+- **0.2.19** — fix: editor `enter` arriving while BootScene is still preloading (the post-flush iframe-rebuild path) had nothing to pause, so the world scene resumed running freely once it started up. Now the bridge re-attempts the pause + scene snapshot for ~3 seconds after enter, catching the scene as it transitions from BootScene → GameScene. Snapshot is also re-posted once a scene file lands in cache. Surfaced when slice-2's auto-flush rebuilt the iframe and the user found the sprite started moving again post-save (2026-05-07).
 - **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.

package/dist/editor/EditorBridge.js

@@ -60,6 +60,36 @@ function enterEdit(game) {
     if (getEditorState(game).active)
         return;
     setEditorActive(game, true);
+    pauseActiveNonEditor(game);
+    // 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) {
     for (const scene of game.scene.getScenes(true)) {
         const key = scene.scene.key;
         if (BOOT_SCENE_KEYS.has(key))
@@ -69,19 +99,14 @@ function enterEdit(game) {
         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);
+    // 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);
     }
@@ -113,9 +138,11 @@ function buildOverlayInit(game) {
             before,
             after,
         }),
+        postShortcut: (action) => postToHost({ type: 'unboxy:editor:shortcut', action }),
     };
 }
 // --- Snapshot -------------------------------------------------------------
+const SNAPSHOT_POSTED_FLAG = '__unboxyEditorSnapshotPostedFor';
 function postSceneSnapshot(game) {
     const sceneFile = readActiveSceneFile(game);
     if (!sceneFile)
@@ -125,6 +152,10 @@ function postSceneSnapshot(game) {
         sceneId: sceneFile.id,
         sceneFile,
     });
+    game[SNAPSHOT_POSTED_FLAG] = sceneFile.id;
+}
+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

package/dist/editor/EditorOverlayScene.d.ts

@@ -43,6 +43,12 @@ interface EditorOverlayInitData {
         x: number;
         y: number;
     }) => void;
+    /**
+     * Forward an editor keyboard shortcut to the host. Set when the iframe has
+     * focus (which is always after the user clicks the canvas to select);
+     * native Cmd+Z otherwise can't reach the host.
+     */
+    postShortcut: (action: 'undo' | 'redo' | 'save') => void;
 }
 export declare class EditorOverlayScene extends Phaser.Scene {
     private graphics;
@@ -50,9 +56,11 @@ export declare class EditorOverlayScene extends Phaser.Scene {
     private hitTest;
     private postPick;
     private postDragEnd;
+    private postShortcut;
     constructor();
     init(data: EditorOverlayInitData): void;
     create(): void;
+    private handleShortcut;
     private handlePointerDown;
     private handlePointerMove;
     private handlePointerUp;

package/dist/editor/EditorOverlayScene.js

@@ -26,12 +26,40 @@ const WORLD_BOUNDS_ALPHA = 0.5;
 export class EditorOverlayScene extends Phaser.Scene {
     constructor() {
         super({ key: EDITOR_OVERLAY_KEY });
+        this.handleShortcut = (e) => {
+            if (!(e.metaKey || e.ctrlKey))
+                return;
+            // Don't swallow keys when the user is typing in a real form control —
+            // shouldn't happen inside the iframe, but be defensive.
+            const target = e.target;
+            if (target) {
+                const tag = target.tagName;
+                if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT')
+                    return;
+                if (target.isContentEditable)
+                    return;
+            }
+            const k = e.key.toLowerCase();
+            if (k === 'z') {
+                e.preventDefault();
+                this.postShortcut(e.shiftKey ? 'redo' : 'undo');
+            }
+            else if (k === 'y') {
+                e.preventDefault();
+                this.postShortcut('redo');
+            }
+            else if (k === 's') {
+                e.preventDefault();
+                this.postShortcut('save');
+            }
+        };
     }
     init(data) {
         this.worldBounds = data.worldBounds;
         this.hitTest = data.hitTest;
         this.postPick = data.postPick;
         this.postDragEnd = data.postDragEnd;
+        this.postShortcut = data.postShortcut;
     }
     create() {
         this.graphics = this.add.graphics();
@@ -45,6 +73,19 @@ export class EditorOverlayScene extends Phaser.Scene {
         this.input.on('pointerdown', this.handlePointerDown, this);
         this.input.on('pointermove', this.handlePointerMove, this);
         this.input.on('pointerup', this.handlePointerUp, this);
+        // Forward editor shortcuts back to the host. The user clicks the canvas
+        // to select an entity, which moves focus into the iframe — after that,
+        // native Cmd+Z lands here, not on the host's window. We catch it before
+        // Phaser's keyboard plugin gets it (DOM phase is fine because Phaser
+        // listens via its own KeyboardManager), preventDefault'ing browser
+        // back-nav-on-Cmd+Left etc. is unnecessary; we only intercept the few
+        // editor keys we care about.
+        if (typeof document !== 'undefined') {
+            document.addEventListener('keydown', this.handleShortcut, true);
+            this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => {
+                document.removeEventListener('keydown', this.handleShortcut, true);
+            });
+        }
     }
     handlePointerDown(pointer) {
         const state = getEditorState(this.game);

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export { EntityRegistry, attachEntityRegistry, getEntityRegistry, } from './scen
 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 type { EditorEntityPatch, EditorEnterMessage, EditorExitMessage, EditorGetSceneMessage, EditorApplyEditMessage, EditorSetSelectionMessage, EditorPanZoomMessage, EditorHostToSdkMessage, EditorSceneLoadedMessage, EditorSelectionPickedMessage, EditorDragEndMessage, EditorShortcutMessage, 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/protocol.d.ts

@@ -141,7 +141,16 @@ export interface EditorDragEndMessage {
         y: number;
     };
 }
-export type EditorSdkToHostMessage = EditorSceneLoadedMessage | EditorSelectionPickedMessage | EditorDragEndMessage;
+/**
+ * Editor keyboard shortcut intercepted inside the iframe (user clicked the
+ * canvas, so focus is on the iframe and the host window doesn't see the
+ * native keydown). The SDK forwards a small allowlist back to the host.
+ */
+export interface EditorShortcutMessage {
+    type: 'unboxy:editor:shortcut';
+    action: 'undo' | 'redo' | 'save';
+}
+export type EditorSdkToHostMessage = EditorSceneLoadedMessage | EditorSelectionPickedMessage | EditorDragEndMessage | EditorShortcutMessage;
 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/package.json

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