@umicat/phaser-sdk 1.0.6 → 1.0.7

package/dist/editor/EditorBridge.js

@@ -11,7 +11,7 @@ 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 { getEditorState, setEditorActive, setSelection, getSelection, getEditorMode, setEditorMode, getActiveSceneId, setActiveSceneId, 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
@@ -126,7 +126,67 @@ function handleMessage(game, msg) {
             // load when manifestAsset present); fire-and-forget the promise.
             void handleEditTilemap(game, msg.entityId, msg.ops, msg.manifestAsset);
             break;
+        case 'umicat:editor:loadScene':
+            // Scene browser (design 01 §6.1) — switch to a different world scene.
+            handleLoadScene(game, msg.sceneId, msg.sceneFile, msg.manifest);
+            break;
+        case 'umicat:editor:updateManifest':
+            // Scene browser — non-switch structural op (create / rename / reorder
+            // / folders / set-initial) refreshed the manifest on disk; mirror it
+            // into the iframe's cache so it never goes stale.
+            handleUpdateManifest(game, msg.manifest);
+            break;
+    }
+}
+// --- Scene browser (design 01 §6.1) ----------------------------------------
+/**
+ * Replace the game-global JSON cache entry under `key` with `value`. The
+ * remove + add pair changes object identity, which is what makes
+ * SceneLoader's `getOrInitState` rebuild its assetsById index on the next
+ * `getManifest` call.
+ */
+function replaceJsonCacheEntry(game, key, value) {
+    if (game.cache.json.exists(key))
+        game.cache.json.remove(key);
+    game.cache.json.add(key, value);
+}
+function handleLoadScene(game, sceneId, sceneFile, manifest) {
+    if (manifest)
+        replaceJsonCacheEntry(game, 'umicat:manifest', manifest);
+    if (sceneFile)
+        replaceJsonCacheEntry(game, `umicat:scene:${sceneId}`, sceneFile);
+    setActiveSceneId(game, sceneId);
+    setSelection(game, null);
+    // Allow the post-restart enterEdit to post a fresh snapshot — that
+    // snapshot (a new `sceneLoaded`) is the host's switch ACK.
+    delete game[SNAPSHOT_POSTED_FLAG];
+    const scene = findWorldScene(game);
+    if (!scene) {
+        // Boot race — no world scene yet. The activeSceneId is set; when the
+        // scene boots it loads whatever the template's init data says, and the
+        // PRE_STEP hook completes editor install. Rare enough to warn.
+        // eslint-disable-next-line no-console
+        console.warn('[umicat/editor] loadScene: no world scene to restart yet');
+        return;
     }
+    // Tear down editor chrome BEFORE the restart. The restart destroys the
+    // scene's cameras, but the game-bag EDITOR_CAM_KEY ref would go stale
+    // (still truthy) — the PRE_STEP late-boot hook checks `!getEditorCamera`
+    // and would never re-run enterEdit. Uninstalling clears the key so the
+    // hook fires once the scene rebuilds, exactly like the boot-flag path.
+    uninstallVoidFill(game);
+    uninstallEditorCameras(game);
+    // Restart with the new sceneId. The template's GameScene.init({ sceneId })
+    // accepts this; loadWorldScene then reads the scene JSON we just cached.
+    // The PRE_STEP late-boot hook (1.0.6) re-runs the idempotent enterEdit
+    // once the scene rebuilds, re-installing editor chrome and posting the
+    // fresh sceneLoaded.
+    scene.scene.restart({ sceneId });
+}
+function handleUpdateManifest(game, manifest) {
+    if (!manifest)
+        return;
+    replaceJsonCacheEntry(game, 'umicat:manifest', manifest);
 }
 // --- Enter / exit ---------------------------------------------------------
 function enterEdit(game) {
@@ -423,6 +483,10 @@ function postSceneSnapshot(game) {
             manifest,
         });
         game[SNAPSHOT_POSTED_FLAG] = sceneFile.id;
+        // Scene browser — pin the active-scene tracker on the boot snapshot so
+        // readActiveSceneFile stays deterministic after later scene switches.
+        if (!getActiveSceneId(game))
+            setActiveSceneId(game, 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
@@ -631,9 +695,19 @@ function hasPostedSnapshot(game) {
     return !!game[SNAPSHOT_POSTED_FLAG];
 }
 function readActiveSceneFile(game) {
+    // Scene browser — once two scenes have been visited, the JSON cache holds
+    // multiple `umicat:scene:*` entries and the scan below becomes ambiguous.
+    // Prefer the exact entry for the tracked active scene when set.
+    const activeId = getActiveSceneId(game);
+    if (activeId) {
+        const exact = game.cache.json.get(`umicat:scene:${activeId}`);
+        if (isWorldScene(exact))
+            return exact;
+    }
     // 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>`.
+    // find with a JSON entry matching `umicat:scene:<id>`. (Boot path / old
+    // hosts — activeSceneId not yet set.)
     for (const scene of game.scene.getScenes(false)) {
         const key = scene.scene.key;
         if (BOOT_SCENE_KEYS.has(key))
@@ -1972,7 +2046,16 @@ function restoreHudCamera(game) {
  * `postCameraState`, and the overlay scene's mirror in `create`.
  */
 export function getEditorCamera(game) {
-    return (game[EDITOR_CAM_KEY] ?? null);
+    const cam = game[EDITOR_CAM_KEY] ?? null;
+    // Scene browser — a scene restart (loadScene switch) destroys the scene's
+    // cameras but leaves this game-bag ref dangling. Phaser's BaseCamera
+    // .destroy() nulls `cam.scene`; treat such a camera as absent and clear
+    // the stale key so the PRE_STEP late-boot hook can re-run enterEdit.
+    if (cam && !cam.scene) {
+        delete game[EDITOR_CAM_KEY];
+        return null;
+    }
+    return cam;
 }
 /**
  * Toggle HUD scene rendering. HUD widgets are canvas-relative (anchor-

package/dist/editor/EditorState.d.ts

@@ -62,6 +62,14 @@ interface EditorStateShape {
     active: boolean;
     selectedId: string | null;
     mode: EditorMode;
+    /**
+     * Scene browser (design 01 §6.1) — which world scene the editor is
+     * currently editing. Set by `umicat:editor:loadScene` and by the first
+     * scene snapshot. Once two scenes have been visited, the JSON cache holds
+     * multiple `umicat:scene:*` entries — this disambiguates which one
+     * `readActiveSceneFile` should return.
+     */
+    activeSceneId: 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
@@ -219,6 +227,8 @@ export declare function getEditorState(game: AnyObject): EditorStateShape;
 export declare function setEditorActive(game: AnyObject, active: boolean): void;
 export declare function getEditorMode(game: AnyObject): EditorMode;
 export declare function setEditorMode(game: AnyObject, mode: EditorMode): void;
+export declare function getActiveSceneId(game: AnyObject): string | null;
+export declare function setActiveSceneId(game: AnyObject, id: string | null): 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: {

package/dist/editor/EditorState.js

@@ -19,6 +19,7 @@ export function getEditorState(game) {
         active: false,
         selectedId: null,
         mode: 'world',
+        activeSceneId: null,
         drag: null,
         debugOverlay: { showHitboxes: false },
         tilemap: {
@@ -45,6 +46,12 @@ export function getEditorMode(game) {
 export function setEditorMode(game, mode) {
     getEditorState(game).mode = mode;
 }
+export function getActiveSceneId(game) {
+    return getEditorState(game).activeSceneId;
+}
+export function setActiveSceneId(game, id) {
+    getEditorState(game).activeSceneId = id;
+}
 export function setSelection(game, id) {
     getEditorState(game).selectedId = id;
 }

package/dist/index.d.ts

@@ -39,5 +39,5 @@ 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, EditorShortcutMessage, EditorCreateEntityMessage, EditorDeleteEntityMessage, EditorSetEditModeMessage, EditorSelectionRectMessage, EditorSdkToHostMessage, } from './protocol.js';
 export { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, } from './scene/types.js';
-export type { Manifest, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, RenderableEntity, SpriteEntity, RectEntity, CircleEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TilemapLayer, TilesetMetadata, TileMetadata, TilesetAutotile, TilesetAnimation, WangTerrain, TriggerEntity, TriggerShape, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, NinePatchPerFrame, HitboxRect, HitboxPerFrame, DepthAnchor, } from './scene/types.js';
+export type { Manifest, ManifestGroup, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, RenderableEntity, SpriteEntity, RectEntity, CircleEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TilemapLayer, TilesetMetadata, TileMetadata, TilesetAutotile, TilesetAnimation, WangTerrain, TriggerEntity, TriggerShape, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, NinePatchPerFrame, HitboxRect, HitboxPerFrame, DepthAnchor, } 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

@@ -580,7 +580,37 @@ export type TilemapEditOp = {
         y: number;
     };
 };
-export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage | EditorSetEditModeMessage | EditorAssetUpdateMessage | EditorSetDebugOverlayMessage | EditorEditPrefabMessage | EditorPatchRuleMessage | EditorSetTilemapToolMessage | EditorEditTilemapMessage;
+/**
+ * Switch the editor to a different world scene (scene browser — design 01
+ * §6.1). The iframe loads scene JSON from the deployed dist, NOT the
+ * workspace, so the host pushes the current on-disk truth here (fetched via
+ * the session-server's `request_workspace_file`) instead of letting the
+ * iframe fetch a stale copy.
+ *
+ * The bridge overwrites the Phaser JSON cache entries, then restarts the
+ * world scene with `{ sceneId }` init data. The restart destroys the editor
+ * camera; the PRE_STEP late-boot-completion hook (1.0.6) detects that and
+ * re-runs the idempotent `enterEdit`, which re-installs editor chrome and
+ * posts a fresh `sceneLoaded` — that snapshot is the host's switch ACK.
+ */
+export interface EditorLoadSceneMessage {
+    type: 'umicat:editor:loadScene';
+    sceneId: string;
+    /** Scene file content (workspace truth). When present, replaces the cached copy. */
+    sceneFile?: unknown;
+    /** Updated manifest (new scenes / groups / initialScene). Replaces cache entry. */
+    manifest?: unknown;
+}
+/**
+ * Replace the iframe's cached manifest without a scene switch — used after
+ * structural scene ops (create / rename / reorder / folders / set-initial)
+ * so the cached copy never goes stale relative to the workspace.
+ */
+export interface EditorUpdateManifestMessage {
+    type: 'umicat:editor:updateManifest';
+    manifest: unknown;
+}
+export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage | EditorSetEditModeMessage | EditorAssetUpdateMessage | EditorSetDebugOverlayMessage | EditorEditPrefabMessage | EditorPatchRuleMessage | EditorSetTilemapToolMessage | EditorEditTilemapMessage | EditorLoadSceneMessage | EditorUpdateManifestMessage;
 export interface EditorSceneLoadedMessage {
     type: 'umicat:editor:sceneLoaded';
     sceneId: string;

package/dist/scene/types.d.ts

@@ -11,12 +11,28 @@ export declare const SCHEMA_VERSION = 1;
 export type SceneType = 'world' | 'hud';
 export interface SceneRef {
     id: string;
+    /**
+     * Display name shown in the editor's scene browser (design 01 §6.1).
+     * Denormalized copy of the scene file's `name`; kept in sync by the
+     * editor's rename op. Optional — display falls back to `id`.
+     */
+    name?: string;
     type: SceneType;
     /** Path under `public/scenes/`, e.g. `"world/level-1-1.json"`. */
     file: string;
     /** Optional HUD scene id to overlay (world scenes only). Null = no HUD. */
     hud?: string | null;
 }
+/**
+ * Editor-only scene folder (scene browser — design 03 §3.1's "loose
+ * enhancement"). Groups scenes for display; the runtime ignores it.
+ * Scenes not in any group render below a separator in `scenes[]` order.
+ */
+export interface ManifestGroup {
+    id: string;
+    name: string;
+    sceneIds: string[];
+}
 export interface HudRef {
     id: string;
     /** Path under `public/scenes/`, e.g. `"hud/game-hud.json"`. */
@@ -526,6 +542,11 @@ export interface Manifest {
      * spawning) can omit this field.
      */
     prefabs?: PrefabRecord[];
+    /**
+     * Editor-only scene folders (scene browser). Optional + purely additive —
+     * runtime never reads it. See {@link ManifestGroup}.
+     */
+    groups?: ManifestGroup[];
     globals?: {
         physics?: {
             gravity?: {

package/package.json

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