@umicat/phaser-sdk 1.0.6 → 1.0.8

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, PrefabRefEntity, 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/SceneLoader.js

@@ -78,7 +78,7 @@ export function preloadSceneAssets(scene, sceneFile, manifest) {
     if (sceneFile.type !== 'world')
         return; // HUD slice will add its own walker
     const state = getOrInitState(scene, manifest);
-    const ids = collectAssetIds(sceneFile.entities);
+    const ids = collectAssetIds(sceneFile.entities, manifest);
     for (const id of ids) {
         if (state.requestedAssetIds.has(id))
             continue;
@@ -98,7 +98,7 @@ export function preloadSceneAssets(scene, sceneFile, manifest) {
         state.requestedAssetIds.add(id);
     }
 }
-function collectAssetIds(entities) {
+function collectAssetIds(entities, manifest) {
     const ids = new Set();
     function walk(e) {
         if (e.kind === 'sprite') {
@@ -119,6 +119,14 @@ function collectAssetIds(entities) {
                     ids.add(id);
             }
         }
+        else if (e.kind === 'prefab-ref') {
+            // Authored prefab instance — preload whatever the prefab's visual
+            // references (sprite prefabs carry an assetId at the record root).
+            const prefab = manifest?.prefabs?.find((p) => p.id === e.prefabId);
+            const assetId = prefab?.assetId;
+            if (typeof assetId === 'string')
+                ids.add(assetId);
+        }
         // rect / circle / code-rendered / trigger don't reference assets.
     }
     for (const e of entities)

package/dist/scene/spawnEntity.js

@@ -30,6 +30,14 @@ export function spawnEntity(ctx, entity) {
         case 'trigger':
             go = createTriggerStub(ctx, entity);
             break;
+        case 'prefab-ref':
+            // Authored prefab INSTANCE (editor "Convert to Type" / drag-from-Types,
+            // 2026-06-12). Resolve the prefab record, build a synthetic entity at
+            // this instance's transform, and recurse — the inner call creates the
+            // GameObject, applies the prefab's physics, tags, and registers under
+            // THIS entity's id. We then re-tag kind + prefabId below.
+            go = createPrefabRefInstance(ctx, entity);
+            break;
         default: {
             const exhaustive = entity;
             throw new Error(`[umicat/scene] unknown entity kind: ${JSON.stringify(exhaustive)}`);
@@ -38,9 +46,71 @@ export function spawnEntity(ctx, entity) {
     applyTransform(go, entity.transform);
     tagGameObject(go, entity);
     applyEntityPhysicsIfDeclared(ctx.scene, go, entity);
+    if (entity.kind === 'prefab-ref') {
+        // Tag for editor live-edit: `umicat:editor:editPrefab` walks instances
+        // via this data key, and canvas clicks route to the Prefab inspector
+        // (editing one instance = editing the type). Registry re-registers with
+        // the prefabId so byPrefabId() finds authored instances too.
+        go.setData('entityPrefabId', entity.prefabId);
+        ctx.registry.unregister(entity.id);
+        ctx.registry.register(entity.id, entity.role ?? prefabRoleOf(ctx.scene, entity.prefabId), go, entity.prefabId);
+        return go;
+    }
     ctx.registry.register(entity.id, entity.role, go);
     return go;
 }
+/**
+ * Read a prefab record straight from the cached manifest. Deliberately NOT
+ * importing SceneLoader's getManifest — that module imports this one, and
+ * keeping the read inline avoids the import cycle.
+ */
+function lookupPrefab(scene, prefabId) {
+    const manifest = scene.cache.json.get('umicat:manifest');
+    const prefab = manifest?.prefabs?.find((p) => p.id === prefabId);
+    return prefab ?? null;
+}
+function prefabRoleOf(scene, prefabId) {
+    const prefab = lookupPrefab(scene, prefabId);
+    return prefab?.role ?? undefined;
+}
+function createPrefabRefInstance(ctx, entity) {
+    const prefab = lookupPrefab(ctx.scene, entity.prefabId);
+    if (!prefab) {
+        console.warn(`[umicat/scene] prefab-ref '${entity.id}' references prefab '${entity.prefabId}' but the manifest has no such prefab; rendering placeholder`);
+        return createMissingPlaceholder(ctx.scene, `prefab: ${entity.prefabId}?`);
+    }
+    // Synthetic entity = prefab fields + this instance's id/transform. Instance
+    // role/properties override the prefab's when set (per-instance variance
+    // without breaking the type link).
+    const synthetic = {
+        ...prefab,
+        id: entity.id,
+        transform: entity.transform,
+        ...(entity.role !== undefined ? { role: entity.role } : {}),
+        ...(entity.properties !== undefined
+            ? { properties: { ...(prefab.properties ?? {}), ...entity.properties } }
+            : {}),
+    };
+    if (synthetic.kind === 'prefab-ref') {
+        // A prefab record can never be kind prefab-ref, but guard against a
+        // hand-edited manifest producing infinite recursion.
+        console.warn(`[umicat/scene] prefab '${entity.prefabId}' has invalid kind 'prefab-ref'`);
+        return createMissingPlaceholder(ctx.scene, `prefab: ${entity.prefabId}?`);
+    }
+    return spawnEntity(ctx, synthetic);
+}
+/** Magenta-bordered "?" placeholder — same soft-fail pattern as missing assets. */
+function createMissingPlaceholder(scene, label) {
+    const g = scene.add.graphics();
+    g.lineStyle(2, 0xff00ff, 1);
+    g.strokeRect(-32, -32, 64, 64);
+    g.lineBetween(-32, -32, 32, 32);
+    g.lineBetween(-32, 32, 32, -32);
+    g.setData('editorHitWidth', 64);
+    g.setData('editorHitHeight', 64);
+    void label;
+    return g;
+}
 /**
  * Apply a scene entity's optional `physics` block. Only renderable entity
  * kinds (sprite / rect / circle / code-rendered) carry a body — they mirror

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?: {
@@ -732,7 +753,7 @@ export interface Anchor {
     offsetX?: number;
     offsetY?: number;
 }
-export type WorldEntityKind = 'sprite' | 'rect' | 'circle' | 'code-rendered' | 'group' | 'tilemap' | 'trigger';
+export type WorldEntityKind = 'sprite' | 'rect' | 'circle' | 'code-rendered' | 'group' | 'tilemap' | 'trigger' | 'prefab-ref';
 export interface WorldEntityBase {
     id: string;
     /** Optional semantic tag. Behavior code keys off this. */
@@ -892,7 +913,23 @@ export interface TriggerEntity extends WorldEntityBase {
     /** Optional preset name (open-door / damage-zone / scene-transition / spawner / heal). */
     preset?: string;
 }
-export type NonGroupWorldEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity;
+/**
+ * Authored INSTANCE of a prefab — the Figma component/instance model
+ * brought to scene data (editor "Convert to Type" + drag-from-Types,
+ * 2026-06-12). The scene stores only "which type + where"; every render /
+ * physics / properties field comes from the prefab record at spawn time,
+ * so editing the prefab updates every placed instance across all scenes.
+ *
+ * Unlike `spawnPrefab` runtime instances (`<prefabId>#<n>` ids, created by
+ * behavior code), prefab-refs are scene-file entities: they appear in the
+ * editor Hierarchy, are draggable (transform lives here), and persist.
+ * `role` defaults to the prefab's role; an explicit role here overrides.
+ */
+export interface PrefabRefEntity extends WorldEntityBase {
+    kind: 'prefab-ref';
+    prefabId: string;
+}
+export type NonGroupWorldEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity | PrefabRefEntity;
 export type WorldEntity = NonGroupWorldEntity | GroupEntity;
 /**
  * Renderable entity kinds — those that produce a single GameObject with

package/package.json

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