@unboxy/phaser-sdk 0.2.28 → 0.2.30

package/dist/core/UnboxyGame.js

@@ -4,6 +4,7 @@ import { setupRecordingListener } from '../recording/RecordingManager.js';
 import { setupEditorModeListener } from '../scene/EditorMode.js';
 import { ORIENTATION_DIMENSIONS } from '../orientation.js';
 import { setRenderScriptRegistry, } from '../scene/renderScripts.js';
+import { UnboxyHudScene } from '../scene/HudRuntime.js';
 /**
  * Create an Unboxy-enhanced Phaser game instance.
  * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
@@ -30,7 +31,11 @@ export function createUnboxyGame(options) {
             arcade: { gravity: { x: 0, y: 0 }, debug: false },
         },
         ...(options.plugins ? { plugins: options.plugins } : {}),
-        scene: options.scenes,
+        // UnboxyHudScene is auto-registered alongside the game's scenes so
+        // `loadWorldScene` can launch it when the active world scene's manifest
+        // entry sets `hud: '<id>'`. Registered at the end so the user's scenes
+        // own the boot order.
+        scene: [...options.scenes, UnboxyHudScene],
     };
     const game = new Phaser.Game(config);
     // Built-in integrations

package/dist/editor/EditorBridge.js

@@ -4,7 +4,8 @@ import { parseColor, spawnEntity } from '../scene/spawnEntity.js';
 import { resolveRenderScript } from '../scene/renderScripts.js';
 import { getManifest } from '../scene/SceneLoader.js';
 import { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './EditorOverlayScene.js';
-import { getEditorState, setEditorActive, setSelection, getSelection, } from './EditorState.js';
+import { getEditorState, setEditorActive, setSelection, getSelection, getEditorMode, setEditorMode, } from './EditorState.js';
+import { applyHudPatch, createHudEntityInScene, deleteHudEntityFromScene, findHudRegistry, findHudSceneFile, UNBOXY_HUD_SCENE_KEY, } from '../scene/HudRuntime.js';
 /**
  * EditorBridge wires the host (home-ui) to the iframe's Phaser game during
  * Edit mode. Manages:
@@ -65,6 +66,16 @@ function handleMessage(game, msg) {
             deleteEntity(game, msg.entityId);
             postSelectionRect(game);
             break;
+        case 'unboxy:editor:setEditMode':
+            // Slice 5 — World/HUD toggle. Mode change is purely state; the host
+            // already has both scene snapshots from enterEdit and just switches
+            // which one its UI renders. Selection may carry over between modes,
+            // but selectionRect re-posts so the ✨ button moves to the active
+            // mode's selected entity (or hides if none).
+            setEditorMode(game, msg.mode);
+            setSelection(game, null);
+            postSelectionRect(game);
+            break;
     }
 }
 // --- Enter / exit ---------------------------------------------------------
@@ -156,16 +167,31 @@ function buildOverlayInit(game) {
 // --- Snapshot -------------------------------------------------------------
 const SNAPSHOT_POSTED_FLAG = '__unboxyEditorSnapshotPostedFor';
 function postSceneSnapshot(game) {
+    const manifest = readActiveManifest(game);
     const sceneFile = readActiveSceneFile(game);
-    if (!sceneFile)
-        return;
-    postToHost({
-        type: 'unboxy:editor:sceneLoaded',
-        sceneId: sceneFile.id,
-        sceneFile,
-        manifest: readActiveManifest(game),
-    });
-    game[SNAPSHOT_POSTED_FLAG] = sceneFile.id;
+    if (sceneFile) {
+        postToHost({
+            type: 'unboxy:editor:sceneLoaded',
+            sceneId: sceneFile.id,
+            mode: 'world',
+            sceneFile,
+            manifest,
+        });
+        game[SNAPSHOT_POSTED_FLAG] = 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
+    // SDK round-trip needed when the user flips it.
+    const hudFile = findHudSceneFile(game);
+    if (hudFile) {
+        postToHost({
+            type: 'unboxy:editor:sceneLoaded',
+            sceneId: hudFile.id,
+            mode: 'hud',
+            sceneFile: hudFile,
+            manifest,
+        });
+    }
 }
 // --- Selection rect (slice 4) ---------------------------------------------
 //
@@ -217,13 +243,13 @@ function doPostSelectionRect(game) {
  * so we factor in the canvas's parent offset too.
  */
 function computeScreenRect(game, go) {
-    // Pull world-coord bounds — same logic the editor uses for hit-test.
+    // Pull entity-local bounds — same logic the editor uses for hit-test.
     const hitW = go.getData('editorHitWidth');
     const hitH = go.getData('editorHitHeight');
     const positioned = go;
-    let worldRect;
+    let entRect;
     if (typeof hitW === 'number' && typeof hitH === 'number') {
-        worldRect = {
+        entRect = {
             x: positioned.x - hitW / 2,
             y: positioned.y - hitH / 2,
             width: hitW,
@@ -235,30 +261,40 @@ function computeScreenRect(game, go) {
         if (typeof withBounds.getBounds !== 'function')
             return null;
         const r = withBounds.getBounds();
-        worldRect = { x: r.x, y: r.y, width: r.width, height: r.height };
+        entRect = { x: r.x, y: r.y, width: r.width, height: r.height };
     }
-    // Find the world scene's camera — it carries scrollX/Y + zoom.
-    let cam = null;
-    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 (getEntityRegistry(scene)) {
-            cam = scene.cameras.main;
-            break;
+    // HUD mode — entity coords are already in canvas-pixel space (the HUD
+    // scene has identity camera). Skip the world→canvas camera transform.
+    let canvasX, canvasY, canvasW, canvasH;
+    if (getEditorMode(game) === 'hud') {
+        canvasX = entRect.x;
+        canvasY = entRect.y;
+        canvasW = entRect.width;
+        canvasH = entRect.height;
+    }
+    else {
+        // World mode — convert via the world scene's camera (scrollX/Y + zoom).
+        let cam = null;
+        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 (key === UNBOXY_HUD_SCENE_KEY)
+                continue;
+            if (getEntityRegistry(scene)) {
+                cam = scene.cameras.main;
+                break;
+            }
         }
+        if (!cam)
+            return null;
+        canvasX = (entRect.x - cam.scrollX) * cam.zoom;
+        canvasY = (entRect.y - cam.scrollY) * cam.zoom;
+        canvasW = entRect.width * cam.zoom;
+        canvasH = entRect.height * cam.zoom;
     }
-    if (!cam)
-        return null;
-    // World → canvas pixels (relative to canvas top-left, inside Phaser's
-    // logical canvas space — i.e. the game.config width/height, NOT the
-    // scaled visible pixels).
-    const canvasX = (worldRect.x - cam.scrollX) * cam.zoom;
-    const canvasY = (worldRect.y - cam.scrollY) * cam.zoom;
-    const canvasW = worldRect.width * cam.zoom;
-    const canvasH = worldRect.height * cam.zoom;
     // Convert logical canvas pixels → CSS pixels using the canvas's actual
     // displayed size (avoids depending on which direction Phaser's displayScale
     // goes — we just measure it). Canvas may be letterboxed/pillarboxed inside
@@ -374,8 +410,18 @@ function entityHitRect(go) {
         return null;
     return { x: r.x, y: r.y, width: r.width, height: r.height };
 }
+/**
+ * Find the entity registry for the current editor mode. World mode picks the
+ * first non-Boot non-Editor scene with a registry; HUD mode picks the
+ * HUD scene's registry. Slice 5+.
+ */
 function findRegistry(game) {
+    if (getEditorMode(game) === 'hud')
+        return findHudRegistry(game);
     for (const scene of game.scene.getScenes(false)) {
+        const key = scene.scene.key;
+        if (key === UNBOXY_HUD_SCENE_KEY)
+            continue;
         const reg = getEntityRegistry(scene);
         if (reg)
             return reg;
@@ -384,6 +430,15 @@ function findRegistry(game) {
 }
 // --- applyEdit ------------------------------------------------------------
 function applyEdit(game, entityId, patch) {
+    // HUD mode — patches modify anchor / HUD-visual fields. World-style
+    // transform / sprite-tint patches don't apply to HUD widgets, so we
+    // dispatch through a HUD-specific helper that knows the widget kinds.
+    if (getEditorMode(game) === 'hud') {
+        applyHudPatch(game, entityId, patch);
+        if (getSelection(game) === entityId)
+            postSelectionRect(game);
+        return;
+    }
     const registry = findRegistry(game);
     if (!registry)
         return;
@@ -496,6 +551,17 @@ function applyVisualPatch(go, v) {
  * sprite, which defeats the point of drag-to-place.
  */
 async function createEntity(game, entity, manifestAsset) {
+    // HUD mode dispatches to the HUD-runtime spawner (slice 5). The host
+    // sends HudEntity records (not WorldEntity), so we type-erase.
+    if (getEditorMode(game) === 'hud') {
+        // Lazy-load asset if the HUD widget needs one and it's not in cache yet.
+        const hud = game.scene.getScene(UNBOXY_HUD_SCENE_KEY);
+        if (manifestAsset && hud && !hud.textures.exists(manifestAsset.textureKey)) {
+            await loadAssetIntoScene(hud, manifestAsset);
+        }
+        createHudEntityInScene(game, entity);
+        return;
+    }
     const scene = findWorldScene(game);
     if (!scene) {
         console.warn('[unboxy/editor] createEntity: no world scene to spawn into');
@@ -622,6 +688,14 @@ function loadAssetIntoScene(scene, asset) {
     });
 }
 function deleteEntity(game, entityId) {
+    // HUD mode — dispatch to the HUD-scene helper, which destroys + unregisters
+    // + drops the entity from the cached scene file.
+    if (getEditorMode(game) === 'hud') {
+        deleteHudEntityFromScene(game, entityId);
+        if (getSelection(game) === entityId)
+            setSelection(game, null);
+        return;
+    }
     const scene = findWorldScene(game);
     if (!scene)
         return;
@@ -631,23 +705,18 @@ function deleteEntity(game, entityId) {
     const go = registry.byId(entityId);
     if (!go)
         return;
-    // Remove from registry by clearing + rebuilding the entries we care about.
-    // The slice-1 EntityRegistry doesn't expose a direct removeById; the
-    // simplest thing is to destroy the GameObject and let stale registry
-    // entries dangle until the next scene reload (post-flush). Slice 3.5
-    // can add an explicit `registry.unregister` if it becomes a problem.
     go.destroy();
-    // Drop selection if it pointed at this entity.
-    const sel = game;
-    const state = sel['__unboxyEditorState'];
-    if (state && state.selectedId === entityId)
-        state.selectedId = null;
+    registry.unregister(entityId);
+    if (getSelection(game) === entityId)
+        setSelection(game, null);
 }
 function findWorldScene(game) {
     for (const scene of game.scene.getScenes(false)) {
         const key = scene.scene.key;
         if (BOOT_SCENE_KEYS.has(key))
             continue;
+        if (key === UNBOXY_HUD_SCENE_KEY)
+            continue;
         if (key === EDITOR_OVERLAY_KEY)
             continue;
         if (getEntityRegistry(scene))

package/dist/editor/EditorOverlayScene.d.ts

@@ -61,6 +61,11 @@ export declare class EditorOverlayScene extends Phaser.Scene {
     init(data: EditorOverlayInitData): void;
     create(): void;
     private handleShortcut;
+    /**
+     * Pointer coords mode-aware. World mode uses world coords (camera-relative);
+     * HUD mode uses canvas-pixel coords (HUD scene has identity camera).
+     */
+    private pointerCoords;
     private handlePointerDown;
     private handlePointerMove;
     private handlePointerUp;
@@ -72,8 +77,8 @@ export declare class EditorOverlayScene extends Phaser.Scene {
      */
     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.
+     * Mode-aware registry lookup. World mode skips the HUD scene; HUD mode
+     * picks the HUD scene specifically.
      */
     private findEntityRegistry;
 }

package/dist/editor/EditorOverlayScene.js

@@ -1,6 +1,7 @@
 import Phaser from 'phaser';
 import { getEntityRegistry } from '../scene/EntityRegistry.js';
-import { getEditorState, startDrag, clearDrag, getDrag, getSelection, } from './EditorState.js';
+import { findHudEntity, findHudRegistry, UNBOXY_HUD_SCENE_KEY, } from '../scene/HudRuntime.js';
+import { getEditorState, startDrag, clearDrag, getDrag, getSelection, getEditorMode, } from './EditorState.js';
 /**
  * Editor overlay — slice 2.
  *
@@ -94,13 +95,21 @@ export class EditorOverlayScene extends Phaser.Scene {
             });
         }
     }
+    /**
+     * Pointer coords mode-aware. World mode uses world coords (camera-relative);
+     * HUD mode uses canvas-pixel coords (HUD scene has identity camera).
+     */
+    pointerCoords(pointer) {
+        if (getEditorMode(this.game) === 'hud')
+            return { x: pointer.x, y: pointer.y };
+        return { x: pointer.worldX, y: pointer.worldY };
+    }
     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 { x: px, y: py } = this.pointerCoords(pointer);
+        const hit = this.hitTest(px, py);
         const event = pointer.event;
         const modifiers = {
             shift: !!event?.shiftKey,
@@ -118,8 +127,21 @@ export class EditorOverlayScene extends Phaser.Scene {
         }
         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 });
+        // In HUD mode `startEntity` carries the entity's anchor offset (not the
+        // GameObject's canvas-pixel position) so dragEnd can report the new
+        // offset values directly.
+        if (getEditorMode(this.game) === 'hud') {
+            const ent = findHudEntity(this.game, entityId);
+            const startOffset = {
+                x: ent?.anchor.offsetX ?? 0,
+                y: ent?.anchor.offsetY ?? 0,
+            };
+            startDrag(this.game, entityId, { x: px, y: py }, startOffset);
+        }
+        else {
+            const target = hit;
+            startDrag(this.game, entityId, { x: px, y: py }, { x: target.x, y: target.y });
+        }
     }
     handlePointerMove(pointer) {
         const drag = getDrag(this.game);
@@ -131,22 +153,46 @@ export class EditorOverlayScene extends Phaser.Scene {
         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;
+        const { x: px, y: py } = this.pointerCoords(pointer);
+        const dx = px - drag.startWorld.x;
+        const dy = py - drag.startWorld.y;
+        if (getEditorMode(this.game) === 'hud') {
+            // HUD `startEntity` carries the offset, not the canvas-pixel start
+            // pos. We track per-frame delta on the GO so each pointermove just
+            // applies the incremental nudge — `go.x = startGoPos.x + dx` doesn't
+            // work because startGoPos isn't stored. The visual position the user
+            // sees is the canvas pos derived from the live anchor base + delta.
+            const lastDx = go.__lastDragDx ?? 0;
+            const lastDy = go.__lastDragDy ?? 0;
+            go.x += dx - lastDx;
+            go.y += dy - lastDy;
+            go.__lastDragDx = dx;
+            go.__lastDragDy = dy;
+        }
+        else {
+            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 { x: px, y: py } = this.pointerCoords(pointer);
+        const dx = px - drag.startWorld.x;
+        const dy = py - drag.startWorld.y;
         const before = drag.startEntity;
         const after = { x: drag.startEntity.x + dx, y: drag.startEntity.y + dy };
+        // Reset the per-drag delta accumulator on the GO if HUD mode left one.
+        if (getEditorMode(this.game) === 'hud') {
+            const reg = this.findEntityRegistry();
+            const go = reg?.byId(drag.entityId);
+            if (go) {
+                go.__lastDragDx = 0;
+                go.__lastDragDy = 0;
+            }
+        }
         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);
@@ -184,11 +230,16 @@ export class EditorOverlayScene extends Phaser.Scene {
         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.
+     * Mode-aware registry lookup. World mode skips the HUD scene; HUD mode
+     * picks the HUD scene specifically.
      */
     findEntityRegistry() {
+        if (getEditorMode(this.game) === 'hud')
+            return findHudRegistry(this.game);
         for (const scene of this.game.scene.getScenes(false)) {
+            const key = scene.scene.key;
+            if (key === UNBOXY_HUD_SCENE_KEY)
+                continue;
             const reg = getEntityRegistry(scene);
             if (reg)
                 return reg;

package/dist/editor/EditorState.d.ts

@@ -6,9 +6,16 @@
  * they reach game systems; this state carries the selection + drag-in-progress
  * info both sides read.
  */
+/**
+ * Editor mode — slice 5. World mode edits the active world scene; HUD mode
+ * edits the HUD scene attached to that world (manifest's `scenes[].hud`).
+ * Toggled by host via `unboxy:editor:setEditMode`.
+ */
+export type EditorMode = 'world' | 'hud';
 interface EditorStateShape {
     active: boolean;
     selectedId: string | null;
+    mode: EditorMode;
     /**
      * Drag-in-progress info. While set, the overlay scene mutates the entity's
      * x/y directly per pointermove without going through the host. On
@@ -35,6 +42,8 @@ interface EditorStateShape {
 type AnyObject = object;
 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 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

@@ -15,13 +15,19 @@ export function getEditorState(game) {
     const existing = b[KEY];
     if (existing)
         return existing;
-    const fresh = { active: false, selectedId: null, drag: null };
+    const fresh = { active: false, selectedId: null, mode: 'world', drag: null };
     b[KEY] = fresh;
     return fresh;
 }
 export function setEditorActive(game, active) {
     getEditorState(game).active = active;
 }
+export function getEditorMode(game) {
+    return getEditorState(game).mode;
+}
+export function setEditorMode(game, mode) {
+    getEditorState(game).mode = mode;
+}
 export function setSelection(game, id) {
     getEditorState(game).selectedId = id;
 }

package/dist/index.d.ts

@@ -26,7 +26,7 @@ export { setRenderScriptRegistry, getRenderScriptRegistry, resolveRenderScript,
 export type { RenderScriptModule } from './scene/renderScripts.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, EditorShortcutMessage, EditorCreateEntityMessage, EditorDeleteEntityMessage, EditorSelectionRectMessage, EditorSdkToHostMessage, } from './protocol.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, } 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, TriggerShape, WorldVisual, SpriteVisual, PrimitiveVisual, PrimitiveRectVisual, PrimitiveCircleVisual, CodeRenderedVisual, Transform, Anchor, AnchorSide, } 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, TriggerShape, WorldVisual, SpriteVisual, PrimitiveVisual, PrimitiveRectVisual, PrimitiveCircleVisual, CodeRenderedVisual, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudVisual, HudTextVisual, HudImageVisual, HudIconButtonVisual, HudProgressBarVisual, HudPanelVisual, HudTextSource, HudNumberSource, HudLayer, 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

@@ -61,13 +61,26 @@ export interface EditorEntityPatch {
         scaleY: number;
         depth: number;
     }>;
+    /**
+     * HUD-only (slice 5). Updates an entity's anchor side / offset. Only one
+     * of `transform` (world entities) or `anchor` (HUD entities) is set per
+     * patch; the SDK picks the right path based on the active mode.
+     */
+    anchor?: Partial<{
+        side: string;
+        offsetX: number;
+        offsetY: number;
+    }>;
+    /** HUD-only (slice 5). Render layer / z-order overrides. */
+    layer?: string;
+    z?: number;
     visual?: {
         tint?: string | null;
         alpha?: number;
         flipX?: boolean;
         flipY?: boolean;
         frame?: string | number;
-        /** For primitives. */
+        /** For primitives + HUD widgets. */
         width?: number;
         height?: number;
         radius?: number;
@@ -80,6 +93,25 @@ export interface EditorEntityPatch {
          * Slice 3.5.
          */
         params?: Record<string, unknown>;
+        /**
+         * HUD text widgets (slice 5). Replaces `visual.source` wholesale —
+         * static→dynamic switches and prefix/suffix edits land here. Static
+         * mode also accepts `text`; dynamic accepts `binding`/`prefix`/`suffix`/`fallback`.
+         */
+        source?: Record<string, unknown>;
+        /** HUD text font / colour. */
+        fontFamily?: string;
+        fontSize?: number;
+        color?: string;
+        align?: 'left' | 'center' | 'right';
+        /** HUD image / icon-button asset. */
+        assetId?: string;
+        iconAssetId?: string;
+        /** HUD icon-button. */
+        label?: string;
+        shape?: 'rounded-rect' | 'circle';
+        pressedFillColor?: string;
+        textColor?: string;
     };
     role?: string | null;
     properties?: Record<string, unknown>;
@@ -132,11 +164,31 @@ export interface EditorDeleteEntityMessage {
     type: 'unboxy:editor:deleteEntity';
     entityId: string;
 }
-export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage;
+/**
+ * Editor mode — slice 5. World mode edits the world scene; HUD mode edits
+ * the HUD scene attached to the active world. The host sends this when the
+ * user toggles the World/HUD switch in the editor canvas.
+ *
+ * The mode change does NOT clear selection at the SDK level; the host owns
+ * selection state per mode (separate selectedId for world / HUD drafts).
+ */
+export interface EditorSetEditModeMessage {
+    type: 'unboxy:editor:setEditMode';
+    mode: 'world' | 'hud';
+}
+export type EditorHostToSdkMessage = EditorEnterMessage | EditorExitMessage | EditorGetSceneMessage | EditorApplyEditMessage | EditorSetSelectionMessage | EditorPanZoomMessage | EditorCreateEntityMessage | EditorDeleteEntityMessage | EditorSetEditModeMessage;
 export interface EditorSceneLoadedMessage {
     type: 'unboxy:editor:sceneLoaded';
     sceneId: string;
-    /** Snapshot of the world scene file's current entities + camera. */
+    /**
+     * Discriminator (slice 5+). 'world' (default for back-compat) is the
+     * world scene; 'hud' is the HUD overlay scene. SDK posts one message per
+     * scene type when entering edit mode, so the host can populate both
+     * Hierarchy / Inspector drafts and switch between them via the
+     * World/HUD toggle without a fresh SDK round-trip.
+     */
+    mode?: 'world' | 'hud';
+    /** Snapshot of the scene file's current entities. */
     sceneFile: unknown;
     /**
      * Snapshot of the manifest (asset table + scene list). Slice 3+ — home-ui

package/dist/scene/EntityRegistry.d.ts

@@ -14,6 +14,9 @@ export declare class EntityRegistry {
     byId(id: string): Phaser.GameObjects.GameObject | undefined;
     byRole(role: string): Phaser.GameObjects.GameObject[];
     all(): Phaser.GameObjects.GameObject[];
+    /** Remove an entity from the registry. Does NOT destroy the GameObject —
+     *  callers (editor delete path) destroy first, then unregister. */
+    unregister(id: string): void;
     clear(): void;
 }
 export declare function attachEntityRegistry(scene: Phaser.Scene): EntityRegistry;

package/dist/scene/EntityRegistry.js

@@ -28,6 +28,22 @@ export class EntityRegistry {
     all() {
         return Array.from(this.byIdMap.values());
     }
+    /** Remove an entity from the registry. Does NOT destroy the GameObject —
+     *  callers (editor delete path) destroy first, then unregister. */
+    unregister(id) {
+        const go = this.byIdMap.get(id);
+        if (!go)
+            return;
+        this.byIdMap.delete(id);
+        for (const [role, list] of this.byRoleMap) {
+            const idx = list.indexOf(go);
+            if (idx >= 0) {
+                list.splice(idx, 1);
+                if (list.length === 0)
+                    this.byRoleMap.delete(role);
+            }
+        }
+    }
     clear() {
         this.byIdMap.clear();
         this.byRoleMap.clear();