@umicat/phaser-sdk 1.0.5 → 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) {
@@ -233,6 +293,17 @@ function installPauseEnforcement(game) {
         if (!getEditorState(game).active)
             return;
         pauseActiveNonEditor(game);
+        // Late-boot completion (1.0.6). The boot-flag path (`umicatEdit=1`)
+        // runs enterEdit BEFORE any scene exists — the scene-dependent
+        // installs (editor cameras, canvas expand, void fill, overlay launch)
+        // all no-op'd, leaving an editor that is paused and snapshotted but
+        // can't pan/zoom or pick. Once the world scene appears, re-run the
+        // full idempotent enterEdit to install them. The editor-camera check
+        // makes this fire at most once per enter: after a successful install
+        // it's permanently truthy (cheap per-frame no-op otherwise).
+        if (!getEditorCamera(game) && findWorldScene(game)) {
+            enterEdit(game);
+        }
     };
     game.events.on(Phaser.Core.Events.PRE_STEP, handler);
     bag[PAUSE_ENFORCER_FLAG] = handler;
@@ -412,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
@@ -620,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))
@@ -1961,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/EditorOverlayScene.d.ts

@@ -304,20 +304,6 @@ export declare class EditorOverlayScene extends Phaser.Scene {
      * replays the `before` patch through the normal applyEdit path.
      */
     private commitEntityResize;
-    /**
-     * Render the CORNER resize handles around the selected rect entity —
-     * Figma convention (2026-06-11): no edge-midpoint squares. On a small
-     * entity 8 handles visually swallowed the rect (a 3×3 grid of squares
-     * with the entity peeking through the middle). Edges stay fully
-     * resizable — the entire selection edge is a hit target and the cursor
-     * flips to ns/ew-resize on hover, which is affordance enough. No bounds
-     * outline (the blue selection rect already draws it) and no ghost rect
-     * (the live GO resizes in place during the drag).
-     *
-     * Visual is 10px; the hit target stays 14px (see hitTestResizeHandlesAt)
-     * — bigger-than-visible click zones are standard.
-     */
-    private drawEntityResizeOverlay;
     update(): void;
     /**
      * Render the 8 resize handles (when paint mode is active) and the

package/dist/editor/EditorOverlayScene.js

@@ -1691,36 +1691,12 @@ export class EditorOverlayScene extends Phaser.Scene {
         // The selection rect changed size — refresh the host's anchor rect.
         postSelectionRect(this.game);
     }
-    /**
-     * Render the CORNER resize handles around the selected rect entity —
-     * Figma convention (2026-06-11): no edge-midpoint squares. On a small
-     * entity 8 handles visually swallowed the rect (a 3×3 grid of squares
-     * with the entity peeking through the middle). Edges stay fully
-     * resizable — the entire selection edge is a hit target and the cursor
-     * flips to ns/ew-resize on hover, which is affordance enough. No bounds
-     * outline (the blue selection rect already draws it) and no ghost rect
-     * (the live GO resizes in place during the drag).
-     *
-     * Visual is 10px; the hit target stays 14px (see hitTestResizeHandlesAt)
-     * — bigger-than-visible click zones are standard.
-     */
-    drawEntityResizeOverlay() {
-        const info = this.entityResizeHandlePositions();
-        if (!info)
-            return;
-        const cam = this.findActiveEditorCamera();
-        const zoom = cam?.zoom ?? 1;
-        const handleSize = 10 / zoom; // 10px on screen regardless of zoom
-        const half = handleSize / 2;
-        for (const h of info.handles) {
-            if (h.id !== 'nw' && h.id !== 'ne' && h.id !== 'sw' && h.id !== 'se')
-                continue;
-            this.graphics.fillStyle(0xffffff, 1);
-            this.graphics.fillRect(h.x - half, h.y - half, handleSize, handleSize);
-            this.graphics.fillStyle(SELECTION_COLOR, 1);
-            this.graphics.fillRect(h.x - half + 1.5 / zoom, h.y - half + 1.5 / zoom, handleSize - 3 / zoom, handleSize - 3 / zoom);
-        }
-    }
+    // Rect entities draw NO handle squares at all (2026-06-11, user decision
+    // after comparing with Figma) — the blue selection outline is the whole
+    // visual. Resizability is communicated by the hover cursor: ns/ew-resize
+    // along the edges, nwse/nesw-resize in the corner zones. Hit targets are
+    // unchanged (entityResizeHandlePositions + hitTestResizeHandlesAt still
+    // serve all 8 zones for the pointer logic).
     update() {
         this.graphics.clear();
         // Slice 6 Phase B (fix): sync tilemap layer world positions to their
@@ -1844,9 +1820,9 @@ export class EditorOverlayScene extends Phaser.Scene {
         // host Inspector). Ghost rect preview shows the new bounds during
         // an active resize drag.
         this.drawTilemapResizeOverlay();
-        // Rect-entity resize handles — render whenever a rect entity is
-        // selected (2026-06-10).
-        this.drawEntityResizeOverlay();
+        // (Rect-entity resize handles draw nothing — resize affordance is the
+        // hover cursor on the selection edges/corners. See the note above
+        // entityResizeHandlePositions' draw section, 2026-06-11.)
         // Snap-to-align guide lines — render while a drag is snapped (2026-06-11).
         this.drawSnapGuides();
     }

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.5",
+  "version": "1.0.7",
   "description": "Umicat Phaser 3 SDK — game infrastructure for the Umicat platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",