@unboxy/phaser-sdk 0.2.28 → 0.2.29

package/dist/scene/HudRuntime.js

@@ -0,0 +1,717 @@
+import Phaser from 'phaser';
+import { SCHEMA_VERSION, } from './types.js';
+import { attachEntityRegistry, getEntityRegistry, } from './EntityRegistry.js';
+import { parseColor } from './spawnEntity.js';
+import { getManifest, SCENES_BASE } from './SceneLoader.js';
+/**
+ * HUD runtime — slice 5.
+ *
+ * `UnboxyHudScene` is a Phaser scene class that runs in parallel with the
+ * world scene, draws anchor-positioned widgets above the gameplay, and
+ * subscribes dynamic-text widgets to the game registry so they live-update
+ * when the agent's behavior code calls `this.registry.set(key, value)`.
+ *
+ * Agent contract (taught by the `hud-dynamic-binding` skill):
+ *   - Use `scene.registry.set(key, value)` to drive HUD bindings. The HUD
+ *     scene picks up the change via `registry.events.on('changedata-<key>')`.
+ *   - The HUD widget JSON references the key via `visual.source.binding`.
+ */
+export const UNBOXY_HUD_SCENE_KEY = 'UnboxyHud';
+/**
+ * Default safe area when the HUD scene file omits one. Matches design 04 §2.1.
+ */
+const DEFAULT_SAFE_AREA = { top: 16, right: 16, bottom: 16, left: 16 };
+/**
+ * Resolve a HUD anchor + offset against the current canvas size to a
+ * concrete pixel position. Called per widget on (a) initial spawn and (b)
+ * scale resize so widgets re-anchor when the viewport changes.
+ */
+export function resolveAnchor(scene, anchor, safeArea = DEFAULT_SAFE_AREA) {
+    const w = scene.scale.width;
+    const h = scene.scale.height;
+    let baseX = 0;
+    let baseY = 0;
+    switch (anchor.side) {
+        case 'top-left':
+            baseX = safeArea.left;
+            baseY = safeArea.top;
+            break;
+        case 'top':
+            baseX = w / 2;
+            baseY = safeArea.top;
+            break;
+        case 'top-right':
+            baseX = w - safeArea.right;
+            baseY = safeArea.top;
+            break;
+        case 'left':
+            baseX = safeArea.left;
+            baseY = h / 2;
+            break;
+        case 'center':
+            baseX = w / 2;
+            baseY = h / 2;
+            break;
+        case 'right':
+            baseX = w - safeArea.right;
+            baseY = h / 2;
+            break;
+        case 'bottom-left':
+            baseX = safeArea.left;
+            baseY = h - safeArea.bottom;
+            break;
+        case 'bottom':
+            baseX = w / 2;
+            baseY = h - safeArea.bottom;
+            break;
+        case 'bottom-right':
+            baseX = w - safeArea.right;
+            baseY = h - safeArea.bottom;
+            break;
+    }
+    return {
+        x: baseX + (anchor.offsetX ?? 0),
+        y: baseY + (anchor.offsetY ?? 0),
+    };
+}
+const LAYER_DEPTH = {
+    base: 100,
+    overlay: 200,
+    modal: 300,
+};
+/**
+ * Spawn a HUD widget into the scene. The returned GameObject is recorded in
+ * the entity registry so the editor + behavior code can find it by id.
+ */
+export function spawnHudEntity(ctx, entity) {
+    const pos = resolveAnchor(ctx.scene, entity.anchor, ctx.safeArea);
+    let go;
+    switch (entity.kind) {
+        case 'text':
+            go = createText(ctx, entity, pos);
+            break;
+        case 'image':
+            go = createImage(ctx, entity, pos);
+            break;
+        case 'icon-button':
+            go = createIconButton(ctx, entity, pos);
+            break;
+        default: {
+            const exhaustive = entity;
+            throw new Error(`[unboxy/hud] unknown HUD entity kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    go.setData('entityId', entity.id);
+    // Z-order. Layer first (base < overlay < modal), then explicit z within layer.
+    const layerDepth = LAYER_DEPTH[entity.layer ?? 'base'];
+    const z = typeof entity.z === 'number' ? entity.z : 0;
+    go.setDepth?.(layerDepth + z);
+    if (entity.visible === false) {
+        go.setVisible?.(false);
+    }
+    ctx.registry.register(entity.id, entity.role, go);
+    return go;
+}
+function createText(ctx, entity, pos) {
+    const initialText = formatText(entity.visual.source, ctx.scene);
+    const text = ctx.scene.add.text(pos.x, pos.y, initialText, {
+        fontFamily: entity.visual.fontFamily ?? 'sans-serif',
+        fontSize: `${entity.visual.fontSize ?? 18}px`,
+        color: entity.visual.color ?? '#ffffff',
+        align: entity.visual.align ?? 'left',
+    });
+    // Anchor origin matches the anchor side so position lands correctly under
+    // the resolved coordinate (e.g. top-right anchored text grows leftward).
+    applyOriginFromAnchor(text, entity.anchor.side);
+    // Wire dynamic binding subscription if needed. Stored on the GameObject so
+    // the editor's applyEdit (changing source) can rewire it.
+    const cleanup = subscribeText(text, entity.visual.source, ctx.scene);
+    text.setData('hudCleanup', cleanup);
+    text.once(Phaser.GameObjects.Events.DESTROY, () => {
+        const fn = text.getData('hudCleanup');
+        fn?.();
+    });
+    return text;
+}
+function createImage(ctx, entity, pos) {
+    const asset = ctx.resolveAsset(entity.visual.assetId);
+    const image = entity.visual.frame !== undefined
+        ? ctx.scene.add.image(pos.x, pos.y, asset.textureKey, entity.visual.frame)
+        : ctx.scene.add.image(pos.x, pos.y, asset.textureKey);
+    if (typeof entity.visual.width === 'number' && typeof entity.visual.height === 'number') {
+        image.setDisplaySize(entity.visual.width, entity.visual.height);
+    }
+    if (entity.visual.tint)
+        image.setTint(parseColor(entity.visual.tint));
+    if (typeof entity.visual.alpha === 'number')
+        image.setAlpha(entity.visual.alpha);
+    applyOriginFromAnchor(image, entity.anchor.side);
+    return image;
+}
+function createIconButton(ctx, entity, pos) {
+    const v = entity.visual;
+    const w = v.width ?? 96;
+    const h = v.height ?? 48;
+    const fillColor = parseColor(v.fillColor ?? '#3b82f6');
+    const strokeColor = v.strokeColor === null ? null : parseColor(v.strokeColor ?? '#1e40af');
+    const strokeW = v.strokeWidth ?? 0;
+    // Container at anchor pos. Children drawn with their own origins.
+    const container = ctx.scene.add.container(pos.x, pos.y);
+    const bg = v.shape === 'circle'
+        ? ctx.scene.add.circle(0, 0, Math.max(w, h) / 2, fillColor)
+        : (() => {
+            const r = ctx.scene.add.rectangle(0, 0, w, h, fillColor);
+            r.setOrigin(0.5, 0.5);
+            return r;
+        })();
+    if (strokeColor !== null && strokeW > 0) {
+        if (v.shape === 'circle') {
+            bg.setStrokeStyle(strokeW, strokeColor);
+        }
+        else {
+            bg.setStrokeStyle(strokeW, strokeColor);
+        }
+    }
+    container.add(bg);
+    if (v.iconAssetId) {
+        try {
+            const asset = ctx.resolveAsset(v.iconAssetId);
+            const icon = ctx.scene.add.image(0, 0, asset.textureKey);
+            const iconSize = Math.min(w, h) * 0.6;
+            icon.setDisplaySize(iconSize, iconSize);
+            container.add(icon);
+        }
+        catch {
+            // Asset missing — fall through to label or nothing.
+        }
+    }
+    if (v.label) {
+        const label = ctx.scene.add.text(0, 0, v.label, {
+            fontFamily: 'sans-serif',
+            fontSize: `${v.fontSize ?? 16}px`,
+            color: v.textColor ?? '#ffffff',
+        });
+        label.setOrigin(0.5, 0.5);
+        container.add(label);
+    }
+    // Container has no intrinsic size — set hit area + size for the editor.
+    container.setSize(w, h);
+    // Anchor origin: containers don't have setOrigin, but offset children
+    // already centered at 0,0 means the container's "visual center" is its
+    // position. Apply the anchor-equivalent offset on the container's x/y.
+    applyContainerOriginShift(container, entity.anchor.side, w, h);
+    // Click → emit `hud:press` on the scene events bus. Agent's behavior
+    // code subscribes by entity id (or role) to wire its onPress action.
+    // The editor mode ignores this — input is captured by the EditorOverlay.
+    bg.setInteractive({ useHandCursor: true });
+    bg.on(Phaser.Input.Events.POINTER_DOWN, () => {
+        if (v.pressedFillColor) {
+            bg.setFillStyle?.(parseColor(v.pressedFillColor));
+        }
+    });
+    bg.on(Phaser.Input.Events.POINTER_UP, () => {
+        if (v.pressedFillColor) {
+            bg.setFillStyle?.(fillColor);
+        }
+        ctx.scene.events.emit('hud:press', entity.id, entity);
+    });
+    bg.on(Phaser.Input.Events.POINTER_OUT, () => {
+        if (v.pressedFillColor) {
+            bg.setFillStyle?.(fillColor);
+        }
+    });
+    // Provide editor hit-test bounds on the container (Phaser containers don't
+    // give getBounds the way game objects do) — same convention as
+    // code-rendered visuals (see SDK 0.2.23).
+    container.setData('editorHitWidth', w);
+    container.setData('editorHitHeight', h);
+    return container;
+}
+/**
+ * Map a 9-grid anchor side to a Phaser origin pair so the rendered widget
+ * is positioned correctly relative to the resolved anchor coordinate.
+ *
+ * Example: side='top-right' → origin (1, 0) so the widget's top-right
+ * corner lands ON the anchor coordinate (which itself is offset inward
+ * from the canvas's actual top-right corner by the safe-area inset).
+ */
+function applyOriginFromAnchor(go, side) {
+    const map = {
+        'top-left': [0, 0],
+        'top': [0.5, 0],
+        'top-right': [1, 0],
+        'left': [0, 0.5],
+        'center': [0.5, 0.5],
+        'right': [1, 0.5],
+        'bottom-left': [0, 1],
+        'bottom': [0.5, 1],
+        'bottom-right': [1, 1],
+    };
+    const [ox, oy] = map[side];
+    go.setOrigin(ox, oy);
+}
+/**
+ * Containers don't support setOrigin; instead nudge their position by half
+ * of (origin × size) so they end up positioned consistently with widgets
+ * that DO have setOrigin. Called once at spawn.
+ */
+function applyContainerOriginShift(container, side, w, h) {
+    const map = {
+        'top-left': [0, 0],
+        'top': [0.5, 0],
+        'top-right': [1, 0],
+        'left': [0, 0.5],
+        'center': [0.5, 0.5],
+        'right': [1, 0.5],
+        'bottom-left': [0, 1],
+        'bottom': [0.5, 1],
+        'bottom-right': [1, 1],
+    };
+    const [ox, oy] = map[side];
+    // Container's children are drawn relative to (0,0) inside the container,
+    // and we drew bg at (0,0) (its setOrigin is 0.5/0.5). To shift the
+    // container so the desired anchor corner lands at the resolved coord:
+    container.x += (0.5 - ox) * w;
+    container.y += (0.5 - oy) * h;
+}
+/**
+ * Compute the rendered string for a text source. Static returns the literal;
+ * dynamic reads the current registry value, applies prefix/suffix.
+ */
+function formatText(source, scene) {
+    if (source.mode === 'static')
+        return source.text;
+    const value = scene.game.registry.get(source.binding);
+    const display = value === undefined || value === null ? (source.fallback ?? '') : String(value);
+    return `${source.prefix ?? ''}${display}${source.suffix ?? ''}`;
+}
+/**
+ * Subscribe a Phaser.Text to the registry key named by a dynamic source.
+ * Returns a cleanup function that detaches the listener.
+ */
+function subscribeText(text, source, scene) {
+    if (source.mode !== 'dynamic')
+        return () => undefined;
+    const key = source.binding;
+    const handler = () => {
+        if (!text.scene)
+            return;
+        text.setText(formatText(source, scene));
+    };
+    scene.game.registry.events.on(`changedata-${key}`, handler);
+    return () => scene.game.registry.events.off(`changedata-${key}`, handler);
+}
+// --- Loader ----------------------------------------------------------------
+/**
+ * Walk a HudScene's entities and queue Phaser loads for any image / icon
+ * assets it references. Idempotent — relies on `manifestState.requestedAssetIds`
+ * if SceneLoader's preload helpers have already touched this scene.
+ */
+export function preloadHudAssets(scene, hudScene, manifest) {
+    const ids = collectHudAssetIds(hudScene.entities);
+    for (const id of ids) {
+        const asset = manifest.assets?.find((a) => a.id === id);
+        if (!asset) {
+            throw new Error(`[unboxy/hud] HUD scene '${hudScene.id}' references assetId '${id}' but the manifest has no such asset`);
+        }
+        if (scene.textures.exists(asset.textureKey))
+            continue;
+        if (asset.kind === 'image') {
+            scene.load.image(asset.textureKey, asset.path);
+        }
+        else if (asset.kind === 'spritesheet') {
+            if (asset.spriteSheetConfig) {
+                scene.load.spritesheet(asset.textureKey, asset.path, asset.spriteSheetConfig);
+            }
+        }
+        else if (asset.kind === 'atlas') {
+            if (asset.atlasPath && asset.atlasFormat === 'xml') {
+                scene.load.atlasXML(asset.textureKey, asset.path, asset.atlasPath);
+            }
+            else if (asset.atlasPath && asset.atlasFormat === 'json') {
+                scene.load.atlas(asset.textureKey, asset.path, asset.atlasPath);
+            }
+        }
+    }
+}
+function collectHudAssetIds(entities) {
+    const ids = new Set();
+    for (const e of entities) {
+        if (e.kind === 'image')
+            ids.add(e.visual.assetId);
+        else if (e.kind === 'icon-button' && e.visual.iconAssetId)
+            ids.add(e.visual.iconAssetId);
+    }
+    return Array.from(ids);
+}
+/**
+ * Load and spawn a HUD scene into the given Phaser scene. Symmetric to
+ * `loadWorldScene`. Returns the parsed scene file + entity registry.
+ *
+ * Pattern (in `UnboxyHudScene.create`):
+ *   const result = await loadHudScene(this, hudId);
+ *   // widgets live; agent's behavior code can subscribe to events via
+ *   // `this.events.on('hud:press', id => ...)`.
+ */
+export async function loadHudScene(scene, hudId) {
+    const manifest = getManifest(scene);
+    const ref = manifest.huds?.find((h) => h.id === hudId);
+    if (!ref)
+        throw new Error(`[unboxy/hud] manifest has no hud with id '${hudId}'`);
+    const hudScene = await loadHudJson(scene, hudId, ref.file);
+    if (hudScene.schemaVersion !== SCHEMA_VERSION) {
+        throw new Error(`[unboxy/hud] HUD scene '${hudId}' schemaVersion ${hudScene.schemaVersion} but SDK expects ${SCHEMA_VERSION}`);
+    }
+    if (hudScene.type !== 'hud') {
+        throw new Error(`[unboxy/hud] HUD scene '${hudId}' has type=${hudScene.type} in file body`);
+    }
+    preloadHudAssets(scene, hudScene, manifest);
+    await runLoader(scene);
+    const registry = attachEntityRegistry(scene);
+    const safeArea = hudScene.design?.safeArea ?? DEFAULT_SAFE_AREA;
+    const ctx = {
+        scene,
+        registry,
+        safeArea,
+        resolveAsset: (id) => {
+            const a = manifest.assets?.find((x) => x.id === id);
+            if (!a)
+                throw new Error(`[unboxy/hud] manifest has no asset with id '${id}'`);
+            return a;
+        },
+    };
+    for (const entity of hudScene.entities)
+        spawnHudEntity(ctx, entity);
+    // Re-anchor on canvas resize. Fired by Phaser's scale manager.
+    const onResize = () => reanchorAll(scene, hudScene, safeArea);
+    scene.scale.on(Phaser.Scale.Events.RESIZE, onResize);
+    scene.events.once(Phaser.Scenes.Events.SHUTDOWN, () => {
+        scene.scale.off(Phaser.Scale.Events.RESIZE, onResize);
+    });
+    return { hudScene, registry };
+}
+function reanchorAll(scene, hudScene, safeArea) {
+    const reg = getEntityRegistry(scene);
+    if (!reg)
+        return;
+    for (const entity of hudScene.entities) {
+        const go = reg.byId(entity.id);
+        if (!go)
+            continue;
+        const pos = resolveAnchor(scene, entity.anchor, safeArea);
+        go.x = pos.x;
+        go.y = pos.y;
+    }
+}
+async function loadHudJson(scene, hudId, file) {
+    const cacheKey = `unboxy:hud:${hudId}`;
+    if (scene.cache.json.exists(cacheKey)) {
+        return scene.cache.json.get(cacheKey);
+    }
+    scene.load.json(cacheKey, `${SCENES_BASE}${file}`);
+    await runLoader(scene);
+    return scene.cache.json.get(cacheKey);
+}
+function runLoader(scene) {
+    return new Promise((resolve, reject) => {
+        if (!scene.load.isLoading() && scene.load.list.size === 0) {
+            queueMicrotask(resolve);
+            return;
+        }
+        scene.load.once(Phaser.Loader.Events.COMPLETE, () => resolve());
+        scene.load.once(Phaser.Loader.Events.FILE_LOAD_ERROR, (file) => {
+            reject(new Error(`[unboxy/hud] loader failed: ${file.key} (${file.url})`));
+        });
+        scene.load.start();
+    });
+}
+// --- Editor bridge helpers (slice 5) --------------------------------------
+//
+// These are called by EditorBridge.ts when the editor is in HUD mode. They
+// keep the bridge file small (no HUD-specific surface there beyond a mode
+// dispatch) and let HUD logic live alongside the runtime that originally
+// spawned the entities.
+/** Find the HUD scene's entity registry, if a HUD scene is currently active. */
+export function findHudRegistry(game) {
+    const hud = game.scene.getScene(UNBOXY_HUD_SCENE_KEY);
+    if (!hud)
+        return undefined;
+    return getEntityRegistry(hud);
+}
+/** Find the HUD scene file from the JSON cache, if loaded. */
+export function findHudSceneFile(game) {
+    const hud = game.scene.getScene(UNBOXY_HUD_SCENE_KEY);
+    if (!hud)
+        return undefined;
+    const cache = hud.cache.json;
+    const entries = cache.entries?.entries ?? {};
+    for (const [k, v] of Object.entries(entries)) {
+        if (k.startsWith('unboxy:hud:'))
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Look up a HUD entity record from the cached scene file. Used by the bridge
+ * during drag (to read anchor side / current offset) and applyEdit (to
+ * resolve the new anchor when side changes).
+ */
+export function findHudEntity(game, entityId) {
+    const hud = findHudSceneFile(game);
+    if (!hud)
+        return undefined;
+    return hud.entities.find((e) => e.id === entityId);
+}
+/**
+ * Compute the canvas-pixel base position for an entity's anchor side
+ * (without offset). Used on drag-end to derive the new offset from the
+ * GameObject's final position.
+ */
+export function getHudAnchorBase(game, entity) {
+    const hud = game.scene.getScene(UNBOXY_HUD_SCENE_KEY);
+    if (!hud)
+        return { x: 0, y: 0 };
+    const sceneFile = findHudSceneFile(game);
+    const safeArea = sceneFile?.design?.safeArea ?? DEFAULT_SAFE_AREA;
+    return resolveAnchor(hud, { side: entity.anchor.side, offsetX: 0, offsetY: 0 }, safeArea);
+}
+/**
+ * Apply an editor patch to a live HUD widget. Mirrors the spawn function's
+ * logic but operates on the existing GameObject — anchor changes
+ * re-resolve position; text source changes rewire the registry subscription;
+ * visual style changes setText / setColor / etc. directly.
+ *
+ * Returns true if a known field was patched, false if nothing applied.
+ */
+export function applyHudPatch(game, entityId, patch) {
+    const hud = game.scene.getScene(UNBOXY_HUD_SCENE_KEY);
+    if (!hud)
+        return false;
+    const reg = getEntityRegistry(hud);
+    if (!reg)
+        return false;
+    const go = reg.byId(entityId);
+    if (!go)
+        return false;
+    const entity = findHudEntity(game, entityId);
+    if (!entity)
+        return false;
+    const sceneFile = findHudSceneFile(game);
+    const safeArea = sceneFile?.design?.safeArea ?? DEFAULT_SAFE_AREA;
+    // Anchor side / offset → re-resolve position. Mutates `entity` so further
+    // applyEdit calls see the latest values (the host owns persistence; the
+    // bridge cache is here for runtime correctness during the editing session).
+    if (patch.anchor) {
+        if (typeof patch.anchor.side === 'string') {
+            entity.anchor.side = patch.anchor.side;
+        }
+        if (typeof patch.anchor.offsetX === 'number')
+            entity.anchor.offsetX = patch.anchor.offsetX;
+        if (typeof patch.anchor.offsetY === 'number')
+            entity.anchor.offsetY = patch.anchor.offsetY;
+        const pos = resolveAnchor(hud, entity.anchor, safeArea);
+        go.x = pos.x;
+        go.y = pos.y;
+        // Text + image origins were set per anchor.side at spawn — re-apply on
+        // side change so e.g. switching top-left → top-right re-pivots the
+        // origin and the widget grows in the correct direction.
+        if (typeof patch.anchor.side === 'string') {
+            const sideMap = {
+                'top-left': [0, 0],
+                'top': [0.5, 0],
+                'top-right': [1, 0],
+                'left': [0, 0.5],
+                'center': [0.5, 0.5],
+                'right': [1, 0.5],
+                'bottom-left': [0, 1],
+                'bottom': [0.5, 1],
+                'bottom-right': [1, 1],
+            };
+            const o = sideMap[patch.anchor.side];
+            if (o) {
+                const setOrigin = go.setOrigin;
+                setOrigin?.call(go, o[0], o[1]);
+            }
+        }
+    }
+    if (typeof patch.layer === 'string') {
+        entity.layer = patch.layer;
+        const layerDepth = LAYER_DEPTH[entity.layer ?? 'base'];
+        const z = typeof entity.z === 'number' ? entity.z : 0;
+        go.setDepth?.(layerDepth + z);
+    }
+    if (typeof patch.z === 'number') {
+        entity.z = patch.z;
+        const layerDepth = LAYER_DEPTH[entity.layer ?? 'base'];
+        go.setDepth?.(layerDepth + patch.z);
+    }
+    // Per-kind visual patches.
+    if (patch.visual && entity.kind === 'text') {
+        const v = entity.visual;
+        const p = patch.visual;
+        const text = go;
+        if (typeof p.fontFamily === 'string')
+            v.fontFamily = p.fontFamily;
+        if (typeof p.fontSize === 'number')
+            v.fontSize = p.fontSize;
+        if (typeof p.color === 'string')
+            v.color = p.color;
+        if (typeof p.align === 'string')
+            v.align = p.align;
+        if (p.source && typeof p.source === 'object') {
+            // Wholesale replacement of `source`. Re-subscribe registry binding.
+            v.source = p.source;
+            const oldCleanup = text.getData('hudCleanup');
+            oldCleanup?.();
+            const cleanup = subscribeText(text, v.source, hud);
+            text.setData('hudCleanup', cleanup);
+        }
+        text.setStyle({
+            fontFamily: v.fontFamily ?? 'sans-serif',
+            fontSize: `${v.fontSize ?? 18}px`,
+            color: v.color ?? '#ffffff',
+            align: v.align ?? 'left',
+        });
+        text.setText(formatText(v.source, hud));
+    }
+    if (patch.visual && entity.kind === 'image') {
+        const v = entity.visual;
+        const p = patch.visual;
+        const image = go;
+        if (typeof p.tint === 'string') {
+            v.tint = p.tint;
+            image.setTint(parseColor(v.tint));
+        }
+        else if (p.tint === null) {
+            v.tint = undefined;
+            image.clearTint();
+        }
+        if (typeof p.alpha === 'number') {
+            v.alpha = p.alpha;
+            image.setAlpha(p.alpha);
+        }
+        if (typeof p.width === 'number' && typeof p.height === 'number') {
+            v.width = p.width;
+            v.height = p.height;
+            image.setDisplaySize(p.width, p.height);
+        }
+    }
+    if (patch.visual && entity.kind === 'icon-button') {
+        // Icon-button is a Container — visual patches require a small refresh.
+        // For v1 we just patch the entity record + label/colour fields cheaply;
+        // wholesale re-spawn lands in slice 5.5 if we add live re-styling.
+        const v = entity.visual;
+        const p = patch.visual;
+        if (typeof p.label === 'string')
+            v.label = p.label;
+        if (typeof p.fillColor === 'string')
+            v.fillColor = p.fillColor;
+        if (typeof p.iconAssetId === 'string')
+            v.iconAssetId = p.iconAssetId;
+        // Patches that change the rendered visual deeply (label, colour, icon)
+        // re-render by destroying + re-spawning the container in place.
+        const reg2 = reg;
+        const safeArea2 = safeArea;
+        const oldDepth = go.depth;
+        go.destroy();
+        reg2.unregister(entityId);
+        const ctx = {
+            scene: hud,
+            registry: reg2,
+            safeArea: safeArea2,
+            resolveAsset: (id) => {
+                const m = getManifest(hud);
+                const a = m.assets?.find((x) => x.id === id);
+                if (!a)
+                    throw new Error(`[unboxy/hud] manifest has no asset with id '${id}'`);
+                return a;
+            },
+        };
+        const fresh = spawnHudEntity(ctx, entity);
+        if (typeof oldDepth === 'number') {
+            fresh.setDepth?.(oldDepth);
+        }
+    }
+    if (patch.role !== undefined) {
+        if (patch.role === null)
+            entity.role = undefined;
+        else
+            entity.role = patch.role;
+    }
+    if (patch.properties)
+        entity.properties = { ...(entity.properties ?? {}), ...patch.properties };
+    return true;
+}
+/** Spawn a fresh HUD entity into the active HUD scene. Used by editor's create-entity path. */
+export function createHudEntityInScene(game, entity) {
+    const hud = game.scene.getScene(UNBOXY_HUD_SCENE_KEY);
+    if (!hud)
+        return false;
+    const reg = getEntityRegistry(hud) ?? attachEntityRegistry(hud);
+    const sceneFile = findHudSceneFile(game);
+    const safeArea = sceneFile?.design?.safeArea ?? DEFAULT_SAFE_AREA;
+    // Mutate the cached scene file so subsequent enter-edit snapshots include
+    // the new entity. Persistence is the host's job.
+    if (sceneFile)
+        sceneFile.entities.push(entity);
+    const ctx = {
+        scene: hud,
+        registry: reg,
+        safeArea,
+        resolveAsset: (id) => {
+            const m = getManifest(hud);
+            const a = m.assets?.find((x) => x.id === id);
+            if (!a)
+                throw new Error(`[unboxy/hud] manifest has no asset with id '${id}'`);
+            return a;
+        },
+    };
+    spawnHudEntity(ctx, entity);
+    return true;
+}
+/** Destroy a HUD entity. */
+export function deleteHudEntityFromScene(game, entityId) {
+    const hud = game.scene.getScene(UNBOXY_HUD_SCENE_KEY);
+    if (!hud)
+        return false;
+    const reg = getEntityRegistry(hud);
+    if (!reg)
+        return false;
+    const go = reg.byId(entityId);
+    if (!go)
+        return false;
+    go.destroy();
+    reg.unregister(entityId);
+    const sceneFile = findHudSceneFile(game);
+    if (sceneFile) {
+        const idx = sceneFile.entities.findIndex((e) => e.id === entityId);
+        if (idx >= 0)
+            sceneFile.entities.splice(idx, 1);
+    }
+    return true;
+}
+// --- Phaser scene class ----------------------------------------------------
+/**
+ * Per-game HUD scene. Auto-launched by `createUnboxyGame` when the world
+ * scene's manifest entry sets `hud: '<id>'`. Renders above the world via
+ * Phaser's scene rendering order; takes input independently.
+ */
+export class UnboxyHudScene extends Phaser.Scene {
+    constructor() {
+        super({ key: UNBOXY_HUD_SCENE_KEY });
+        this.hudId = null;
+    }
+    init(data) {
+        this.hudId = data.hudId ?? null;
+    }
+    async create() {
+        if (!this.hudId)
+            return;
+        try {
+            await loadHudScene(this, this.hudId);
+        }
+        catch (e) {
+            console.warn('[unboxy/hud] loadHudScene failed:', e);
+        }
+    }
+}