@umicat/phaser-sdk 1.0.0

package/dist/scene/HudRuntime.js

@@ -0,0 +1,1224 @@
+import Phaser from 'phaser';
+import { SCHEMA_VERSION, isPerFrameNinePatch, } from './types.js';
+import { attachEntityRegistry, getEntityRegistry, } from './EntityRegistry.js';
+import { parseColor } from './spawnEntity.js';
+import { applyPixelArtFilters, getAtlasFrameNinePatch, getManifest, SCENES_BASE, suspendSceneUpdates, } from './SceneLoader.js';
+/**
+ * HUD runtime — slice 5.
+ *
+ * `UmicatHudScene` 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>')`.
+ *   - HUD text widgets reference the registry key via `source.binding` (flat,
+ *     at the widget root — SDK 0.3.0).
+ */
+export const UMICAT_HUD_SCENE_KEY = 'UmicatHud';
+/**
+ * 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) {
+    // In edit mode the canvas is EXPANDED to fill the iframe, so
+    // `scene.scale.width/height` is the expanded dim — NOT the game's
+    // intrinsic viewport. HUD widgets should anchor to the GAME'S
+    // intrinsic dims (the camera viewport rect) so that "top-right" =
+    // top-right of where the player will actually see the HUD at
+    // runtime. EditorBridge stores the intrinsic dims as a snapshot
+    // when expanding the canvas; we read them back here. Outside edit
+    // mode (no snapshot), `scene.scale.width/height` IS the game dims.
+    const snap = scene.game['__unboxyEditorScaleSnapshot'];
+    const w = snap?.gameWidth ?? scene.scale.width;
+    const h = snap?.gameHeight ?? 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,
+};
+/**
+ * Render an image (or one cell of a uniform-grid spritesheet) at (x, y) sized
+ * to (width, height). When the asset carries `ninePatch` metadata, uses
+ * `phaser3-rex-plugins`' NinePatch (corners fixed, edges + center stretch);
+ * otherwise falls back to a regular Image scaled with `setDisplaySize`.
+ *
+ * Two ninePatch shapes accepted:
+ *   - Single image (slice 7.5): `asset.ninePatch` is a `NinePatchConfig`. The
+ *     whole texture slices into 9 regions.
+ *   - Per-frame on a uniform-grid sheet (slice 7.6): `asset.ninePatch` is
+ *     `{ perFrame: NinePatchConfig }`. The shared cuts apply to whichever
+ *     frame the caller picks via `frame`. Common case: itch.io button packs
+ *     where every cell is a different button color/state with the same
+ *     corner radius.
+ *
+ * Caller owns origin/anchor — both Image and NinePatch (which extends
+ * RenderTexture) expose `setOrigin`. Returns the created GameObject already
+ * added to the scene's display list.
+ */
+function createImageOrNinePatch(scene, x, y, width, height, asset, frame) {
+    // Region-atlas path (slice 10) — when the asset is an atlas-format texture
+    // AND the caller picks a frame by string name, per-region ninePatch
+    // metadata may live in the atlas JSON. Phaser drops unknown per-frame
+    // fields on parse, so we read from the side-cache stashed at preload.
+    if (asset.kind === 'atlas' && asset.atlasFormat === 'json' && typeof frame === 'string') {
+        const cuts = getAtlasFrameNinePatch(scene, asset.textureKey, frame);
+        if (cuts) {
+            return createCustomNinePatch(scene, x, y, width, height, asset, cuts, frame);
+        }
+        // Atlas frame without 9-slice metadata → plain stretched Image of that
+        // region. Falls through to the generic fallback below.
+    }
+    if (asset.ninePatch) {
+        const np = asset.ninePatch;
+        const cuts = isPerFrameNinePatch(np) ? np.perFrame : np;
+        return createCustomNinePatch(scene, x, y, width, height, asset, cuts, frame);
+    }
+    // Fallback: plain Image. Frame (number index or string atlas-name) threaded
+    // through for spritesheet / atlas assets so per-cell rendering still works
+    // without 9-slice.
+    const image = frame !== undefined
+        ? scene.add.image(x, y, asset.textureKey, frame)
+        : scene.add.image(x, y, asset.textureKey);
+    image.setDisplaySize(width, height);
+    return image;
+}
+/**
+ * 9-slice renderer built directly on Phaser primitives. We tried
+ * `phaser3-rex-plugins`' NinePatch first (slice 7.5/7.6) but ran into a
+ * RenderTexture sizing bug in Phaser 3.60+ that's hard to work around
+ * without monkey-patching: rex's constructor calls `super(scene)` with no
+ * dims (defaulting the DynamicTexture to 32×32), then `setSize(w, h)` —
+ * which in Phaser 3.60+ only sets display dimensions, not the underlying
+ * texture. The 9-slice gets drawn into the small default canvas and
+ * displayed stretched. Reproducing this without rex is faster than the
+ * monkey-patch dance.
+ *
+ * <p>Algorithm: split the source texture into 9 sub-frames via
+ * `texture.add()` (idempotent — Phaser ignores re-adds), spawn one Phaser
+ * Image per sub-frame, position + stretch them inside a Container. Corners
+ * keep their native dimensions; edges stretch in one axis; the middle
+ * stretches in both. Returns the container, sized to the target dims with
+ * an explicit hit area so `setInteractive` works as expected on the
+ * icon-button widget.
+ *
+ * <p>Source layout: `(sx, sy)` is the source-image origin within the
+ * texture; for plain Images it's (0,0). For per-frame on a uniform-grid
+ * sheet, `frame` selects which cell — the corresponding frame's `cutX/Y`
+ * gives the origin.
+ */
+function createCustomNinePatch(scene, x, y, width, height, asset, cuts, frame) {
+    const texKey = asset.textureKey;
+    const texture = scene.textures.get(texKey);
+    // Per-frame variant: look up the specified cell's source rect (number for
+    // uniform-grid sheets, atlas-name string for region atlases). Single image
+    // uses the texture's `__BASE` frame covering the whole image.
+    const baseFrame = frame !== undefined
+        ? texture.get(frame)
+        : texture.get('__BASE');
+    const sx = baseFrame.cutX;
+    const sy = baseFrame.cutY;
+    const sw = baseFrame.width;
+    const sh = baseFrame.height;
+    const L = cuts.leftWidth;
+    const R = cuts.rightWidth;
+    const T = cuts.topHeight;
+    const B = cuts.bottomHeight;
+    // Source middle widths/heights (the part that stretches).
+    const midSrcW = Math.max(0, sw - L - R);
+    const midSrcH = Math.max(0, sh - T - B);
+    // Target middle widths/heights — what remains after the four corners are
+    // placed at their fixed sizes. When the widget is sized smaller than
+    // L+R / T+B, the corners overlap; rare but handled by clamping to 0
+    // rather than producing negative-size sprites.
+    const midDstW = Math.max(0, width - L - R);
+    const midDstH = Math.max(0, height - T - B);
+    const container = scene.add.container(x, y);
+    // Register a sub-frame on the source texture (idempotent) and add a
+    // Phaser Image rendering that frame at the target position + size.
+    // Position is relative to container's origin; Image origin (0, 0) makes
+    // (dx, dy) the top-left of the sub-region.
+    const frameSuffix = frame !== undefined ? `__f${frame}` : '';
+    const addSubFrame = (suffix, fx, fy, fw, fh, dx, dy, dw, dh) => {
+        if (fw <= 0 || fh <= 0 || dw <= 0 || dh <= 0)
+            return;
+        const subKey = `${texKey}${frameSuffix}_${suffix}`;
+        if (!texture.has(subKey)) {
+            texture.add(subKey, 0, sx + fx, sy + fy, fw, fh);
+        }
+        const img = scene.add.image(dx, dy, texKey, subKey);
+        img.setOrigin(0, 0);
+        img.setDisplaySize(dw, dh);
+        container.add(img);
+    };
+    // Layout offsets — container's local origin is at its center, so the
+    // 9-slice patch spans (-width/2, -height/2) to (width/2, height/2).
+    const x0 = -width / 2;
+    const y0 = -height / 2;
+    const xL = x0 + L;
+    const xR = x0 + width - R;
+    const yT = y0 + T;
+    const yB = y0 + height - B;
+    // Source frame offsets within the base frame.
+    const fxL = 0;
+    const fxM = L;
+    const fxR = sw - R;
+    const fyT = 0;
+    const fyM = T;
+    const fyB = sh - B;
+    // Top row
+    addSubFrame('tl', fxL, fyT, L, T, x0, y0, L, T);
+    addSubFrame('tm', fxM, fyT, midSrcW, T, xL, y0, midDstW, T);
+    addSubFrame('tr', fxR, fyT, R, T, xR, y0, R, T);
+    // Middle row
+    addSubFrame('ml', fxL, fyM, L, midSrcH, x0, yT, L, midDstH);
+    addSubFrame('mm', fxM, fyM, midSrcW, midSrcH, xL, yT, midDstW, midDstH);
+    addSubFrame('mr', fxR, fyM, R, midSrcH, xR, yT, R, midDstH);
+    // Bottom row
+    addSubFrame('bl', fxL, fyB, L, B, x0, yB, L, B);
+    addSubFrame('bm', fxM, fyB, midSrcW, B, xL, yB, midDstW, B);
+    addSubFrame('br', fxR, fyB, R, B, xR, yB, R, B);
+    // Explicit hit area so setInteractive works (Phaser containers have no
+    // intrinsic bounds; the icon-button widget calls setInteractive on this).
+    container.setSize(width, height);
+    return container;
+}
+/**
+ * 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;
+        case 'progress-bar':
+            go = createProgressBar(ctx, entity, pos);
+            break;
+        case 'panel':
+            go = createPanel(ctx, entity, pos);
+            break;
+        default: {
+            const exhaustive = entity;
+            throw new Error(`[umicat/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.source, ctx.scene);
+    const text = ctx.scene.add.text(pos.x, pos.y, initialText, {
+        fontFamily: entity.fontFamily ?? 'sans-serif',
+        fontSize: `${entity.fontSize ?? 18}px`,
+        color: entity.color ?? '#ffffff',
+        align: entity.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.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) {
+    let asset;
+    try {
+        asset = ctx.resolveAsset(entity.assetId);
+    }
+    catch {
+        // Soft-fail when the assetId isn't in the manifest. Mirrors the world
+        // scene's createSprite missing-asset path. Wraps a Graphics in a
+        // Container so the editor's bounds-based hit-test has a sized target.
+        const w = entity.width ?? 64;
+        const h = entity.height ?? 64;
+        const g = ctx.scene.add.graphics();
+        g.fillStyle(0x4d2244, 0.4);
+        g.fillRect(-w / 2, -h / 2, w, h);
+        g.lineStyle(2, 0xff00ff, 0.9);
+        g.strokeRect(-w / 2, -h / 2, w, h);
+        g.lineBetween(-w / 2, -h / 2, w / 2, h / 2);
+        g.lineBetween(w / 2, -h / 2, -w / 2, h / 2);
+        const container = ctx.scene.add.container(pos.x, pos.y, [g]);
+        container.setSize(w, h);
+        return container;
+    }
+    // 9-slice path. When the asset has `ninePatch` metadata, the SDK renders
+    // via our custom Container-based NinePatch (corners fixed; edges + center
+    // stretch). Missing width/height falls back to the texture's native source
+    // dims so existing image-without-dims data still works.
+    if (asset.ninePatch) {
+        const tex = ctx.scene.textures.get(asset.textureKey);
+        const src = tex?.getSourceImage();
+        const w = entity.width ?? src?.width ?? 64;
+        const h = entity.height ?? src?.height ?? 64;
+        const np = createImageOrNinePatch(ctx.scene, pos.x, pos.y, w, h, asset);
+        if (typeof entity.alpha === 'number') {
+            np.setAlpha?.(entity.alpha);
+        }
+        // The custom NinePatch is a Container with children centered around
+        // (0, 0). Use the same origin-shift trick the container widgets use so
+        // the anchor side resolves correctly. Tint isn't supported on
+        // Container; image widgets needing tint should bypass ninePatch.
+        if (np instanceof Phaser.GameObjects.Container) {
+            applyContainerOriginShift(np, entity.anchor.side, w, h);
+        }
+        else {
+            applyOriginFromAnchor(np, entity.anchor.side);
+        }
+        return np;
+    }
+    const image = entity.frame !== undefined
+        ? ctx.scene.add.image(pos.x, pos.y, asset.textureKey, entity.frame)
+        : ctx.scene.add.image(pos.x, pos.y, asset.textureKey);
+    if (typeof entity.width === 'number' && typeof entity.height === 'number') {
+        image.setDisplaySize(entity.width, entity.height);
+    }
+    if (entity.tint)
+        image.setTint(parseColor(entity.tint));
+    if (typeof entity.alpha === 'number')
+        image.setAlpha(entity.alpha);
+    applyOriginFromAnchor(image, entity.anchor.side);
+    return image;
+}
+/**
+ * Build the v0 colored-rect background for an icon-button (rectangle or
+ * circle). Used when `backgroundAssetId` is unset OR the referenced asset
+ * couldn't be resolved.
+ */
+function makeColoredRectBg(scene, v, w, h, fillColor, strokeColor, strokeW) {
+    const bg = v.shape === 'circle'
+        ? scene.add.circle(0, 0, Math.max(w, h) / 2, fillColor)
+        : (() => {
+            const r = 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);
+        }
+    }
+    return bg;
+}
+function createIconButton(ctx, entity, pos) {
+    const v = entity;
+    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);
+    // Background source (textured vs. colored-rect). When `backgroundAssetId`
+    // is set we render the asset image (NinePatch when the asset has 9-slice
+    // metadata; stretched Image otherwise); colored-rect bg is the v0 fallback.
+    // The interactive surface is always the `bg` GameObject — POINTER_DOWN/UP
+    // events fire on whichever variant is active.
+    let bg;
+    let texturedBg = false;
+    if (v.backgroundAssetId) {
+        try {
+            const bgAsset = ctx.resolveAsset(v.backgroundAssetId);
+            // Region-atlas name (string) wins when both are set; uniform-grid index
+            // (number) is the fallback for slice 7.6 button packs.
+            const bgFrame = v.backgroundRegion ?? v.backgroundFrame;
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, bgFrame);
+            np.setOrigin?.(0.5, 0.5);
+            bg = np;
+            texturedBg = true;
+        }
+        catch {
+            // Background asset missing — fall through to colored-rect.
+            bg = makeColoredRectBg(ctx.scene, v, w, h, fillColor, strokeColor, strokeW);
+        }
+    }
+    else {
+        bg = makeColoredRectBg(ctx.scene, v, w, h, fillColor, strokeColor, strokeW);
+    }
+    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 });
+    // pressedFillColor only applies to the colored-rect bg (Rectangle/Arc have
+    // setFillStyle). Textured backgrounds render the asset's pixels directly —
+    // pressed-state visual feedback for those is v2.
+    const supportsFillSwap = !texturedBg && !!v.pressedFillColor;
+    bg.on(Phaser.Input.Events.POINTER_DOWN, () => {
+        if (supportsFillSwap) {
+            bg.setFillStyle?.(parseColor(v.pressedFillColor));
+        }
+    });
+    bg.on(Phaser.Input.Events.POINTER_UP, () => {
+        if (supportsFillSwap) {
+            bg.setFillStyle?.(fillColor);
+        }
+        ctx.scene.events.emit('hud:press', entity.id, entity);
+    });
+    bg.on(Phaser.Input.Events.POINTER_OUT, () => {
+        if (supportsFillSwap) {
+            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;
+}
+/**
+ * Progress bar — Graphics-rendered (no Phaser primitive matches "fill that
+ * shrinks/grows from one edge"). Subscribes to value + max bindings if
+ * either is dynamic; redraws whenever a relevant registry key changes.
+ */
+function createProgressBar(ctx, entity, pos) {
+    const v = entity;
+    const w = v.width ?? 200;
+    const h = v.height ?? 16;
+    const container = ctx.scene.add.container(pos.x, pos.y);
+    // Background + fill drawn into a Graphics so width-stretching doesn't
+    // distort corners (no setDisplaySize stretching, no extra dependencies).
+    const g = ctx.scene.add.graphics();
+    container.add(g);
+    const draw = (frac) => {
+        const f = Math.max(0, Math.min(1, frac));
+        g.clear();
+        const radius = v.borderRadius ?? 0;
+        // Centered draw: the container is positioned by applyContainerOriginShift
+        // so child visuals at (0,0) sit at the resolved anchor; drawing the rect
+        // from (-w/2, -h/2) keeps the visual aligned with the editor's
+        // editorHit{Width,Height} bounds (which are computed center-based).
+        const x0 = -w / 2;
+        const y0 = -h / 2;
+        // Background.
+        if (v.backgroundColor) {
+            g.fillStyle(parseColor(v.backgroundColor), 1);
+            if (radius > 0)
+                g.fillRoundedRect(x0, y0, w, h, radius);
+            else
+                g.fillRect(x0, y0, w, h);
+        }
+        // Fill.
+        const fillColor = v.fillColor ?? '#22c55e';
+        g.fillStyle(parseColor(fillColor), 1);
+        const fillW = w * f;
+        if (fillW > 0) {
+            if (radius > 0)
+                g.fillRoundedRect(x0, y0, fillW, h, Math.min(radius, fillW / 2));
+            else
+                g.fillRect(x0, y0, fillW, h);
+        }
+        // Border.
+        if (v.borderColor && (v.borderWidth ?? 0) > 0) {
+            g.lineStyle(v.borderWidth ?? 1, parseColor(v.borderColor), 1);
+            if (radius > 0)
+                g.strokeRoundedRect(x0, y0, w, h, radius);
+            else
+                g.strokeRect(x0, y0, w, h);
+        }
+    };
+    const computeFrac = () => {
+        const value = readNumberSource(v.value, ctx.scene);
+        const max = readNumberSource(v.max, ctx.scene);
+        if (max <= 0)
+            return 0;
+        return value / max;
+    };
+    draw(computeFrac());
+    // Subscribe to dynamic bindings. Either value or max can be dynamic;
+    // each pushes a redraw on registry change.
+    const cleanups = [];
+    if (v.value.mode === 'dynamic') {
+        const key = `changedata-${v.value.binding}`;
+        const handler = () => draw(computeFrac());
+        ctx.scene.game.registry.events.on(key, handler);
+        cleanups.push(() => ctx.scene.game.registry.events.off(key, handler));
+    }
+    if (v.max.mode === 'dynamic') {
+        const key = `changedata-${v.max.binding}`;
+        const handler = () => draw(computeFrac());
+        ctx.scene.game.registry.events.on(key, handler);
+        cleanups.push(() => ctx.scene.game.registry.events.off(key, handler));
+    }
+    // setSize so the editor's bounds-based hit-test works on the container.
+    container.setSize(w, h);
+    container.setData('editorHitWidth', w);
+    container.setData('editorHitHeight', h);
+    applyContainerOriginShift(container, entity.anchor.side, w, h);
+    // Persist redraw + cleanup on the GameObject for applyHudPatch to reach.
+    container.setData('hudRedraw', () => draw(computeFrac()));
+    container.setData('hudCleanup', () => cleanups.forEach((fn) => fn()));
+    container.once(Phaser.GameObjects.Events.DESTROY, () => {
+        const fn = container.getData('hudCleanup');
+        fn?.();
+    });
+    return container;
+}
+/**
+ * Panel — a colored rectangle with optional border + rounded corners. Used
+ * as a visual frame behind other HUD widgets (no children layout in v1;
+ * children live alongside the panel as separate entities).
+ */
+function createPanel(ctx, entity, pos) {
+    const v = entity;
+    const w = v.width ?? 200;
+    const h = v.height ?? 100;
+    const container = ctx.scene.add.container(pos.x, pos.y);
+    // Textured-background path: when `backgroundAssetId` is set we render the
+    // asset image (NinePatch when it carries 9-slice metadata; stretched Image
+    // otherwise). The colored Graphics path below is the fallback when the
+    // asset is missing or no background asset is configured.
+    let bgRendered = false;
+    if (v.backgroundAssetId) {
+        try {
+            const bgAsset = ctx.resolveAsset(v.backgroundAssetId);
+            const bgFrame = v.backgroundRegion ?? v.backgroundFrame;
+            const np = createImageOrNinePatch(ctx.scene, 0, 0, w, h, bgAsset, bgFrame);
+            np.setOrigin?.(0.5, 0.5);
+            container.add(np);
+            bgRendered = true;
+        }
+        catch {
+            // Background asset missing — fall through to Graphics rect.
+        }
+    }
+    if (!bgRendered) {
+        const g = ctx.scene.add.graphics();
+        container.add(g);
+        const draw = () => {
+            g.clear();
+            const radius = v.borderRadius ?? 0;
+            // Centered draw — see createProgressBar for the rationale.
+            const x0 = -w / 2;
+            const y0 = -h / 2;
+            if (v.backgroundColor) {
+                g.fillStyle(parseColor(v.backgroundColor), v.backgroundAlpha ?? 1);
+                if (radius > 0)
+                    g.fillRoundedRect(x0, y0, w, h, radius);
+                else
+                    g.fillRect(x0, y0, w, h);
+            }
+            if (v.borderColor && (v.borderWidth ?? 0) > 0) {
+                g.lineStyle(v.borderWidth ?? 1, parseColor(v.borderColor), 1);
+                if (radius > 0)
+                    g.strokeRoundedRect(x0, y0, w, h, radius);
+                else
+                    g.strokeRect(x0, y0, w, h);
+            }
+        };
+        draw();
+        container.setData('hudRedraw', draw);
+    }
+    container.setSize(w, h);
+    container.setData('editorHitWidth', w);
+    container.setData('editorHitHeight', h);
+    applyContainerOriginShift(container, entity.anchor.side, w, h);
+    return container;
+}
+/** Read a numeric source (static or dynamic from registry). */
+function readNumberSource(source, scene) {
+    if (source.mode === 'static')
+        return source.value;
+    const raw = scene.game.registry.get(source.binding);
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return raw;
+    return source.fallback ?? 0;
+}
+/**
+ * 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);
+}
+/**
+ * Compute the per-side origin-shift offset for a container widget. Containers
+ * don't support setOrigin, so we shift the container's position so its
+ * (centred) child visuals appear at the right place relative to the
+ * resolved anchor coord. Used both at spawn and during applyHudPatch when
+ * the anchor side changes.
+ */
+/** Default container widths/heights — must mirror the spawners' fallbacks. */
+function defaultContainerWidth(entity) {
+    if (entity.kind === 'icon-button')
+        return entity.width ?? 96;
+    if (entity.kind === 'progress-bar')
+        return entity.width ?? 200;
+    if (entity.kind === 'panel')
+        return entity.width ?? 200;
+    return 0;
+}
+function defaultContainerHeight(entity) {
+    if (entity.kind === 'icon-button')
+        return entity.height ?? 48;
+    if (entity.kind === 'progress-bar')
+        return entity.height ?? 16;
+    if (entity.kind === 'panel')
+        return entity.height ?? 100;
+    return 0;
+}
+function originShiftFor(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];
+    return { x: (0.5 - ox) * w, y: (0.5 - oy) * h };
+}
+function applyContainerOriginShift(container, side, w, h) {
+    const s = originShiftFor(side, w, h);
+    container.x += s.x;
+    container.y += s.y;
+}
+/**
+ * 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) {
+            // Soft-fail: warn + continue. createImage / createIconButton render
+            // a placeholder when the asset is unresolvable. Mirrors the world
+            // scene's preloadSceneAssets soft-fail (SceneLoader.ts).
+            // eslint-disable-next-line no-console
+            console.warn(`[umicat/hud] HUD scene '${hudScene.id}' references assetId '${id}' but the manifest has no such asset; widget will render as a placeholder`);
+            continue;
+        }
+        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);
+                // Also fetch the raw JSON into the side-cache so per-frame
+                // `ninePatch` metadata (which Phaser drops on parse) is readable at
+                // spawn time via `getAtlasFrameNinePatch`. See SceneLoader.ts.
+                const sidecarKey = `umicat:atlas-ninepatch:${asset.textureKey}`;
+                if (!scene.cache.json.exists(sidecarKey)) {
+                    scene.load.json(sidecarKey, asset.atlasPath);
+                }
+            }
+        }
+    }
+}
+function collectHudAssetIds(entities) {
+    const ids = new Set();
+    for (const e of entities) {
+        if (e.kind === 'image') {
+            ids.add(e.assetId);
+        }
+        else if (e.kind === 'icon-button') {
+            if (e.iconAssetId)
+                ids.add(e.iconAssetId);
+            if (e.backgroundAssetId)
+                ids.add(e.backgroundAssetId);
+        }
+        else if (e.kind === 'panel' && e.backgroundAssetId) {
+            ids.add(e.backgroundAssetId);
+        }
+    }
+    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 `UmicatHudScene.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 release = suspendSceneUpdates(scene);
+    try {
+        return await loadHudSceneImpl(scene, hudId);
+    }
+    finally {
+        release();
+    }
+}
+async function loadHudSceneImpl(scene, hudId) {
+    const manifest = getManifest(scene);
+    const ref = manifest.huds?.find((h) => h.id === hudId);
+    if (!ref)
+        throw new Error(`[umicat/hud] manifest has no hud with id '${hudId}'`);
+    const hudScene = await loadHudJson(scene, hudId, ref.file);
+    if (hudScene.schemaVersion !== SCHEMA_VERSION) {
+        throw new Error(`[umicat/hud] HUD scene '${hudId}' schemaVersion ${hudScene.schemaVersion} but SDK expects ${SCHEMA_VERSION}`);
+    }
+    if (hudScene.type !== 'hud') {
+        throw new Error(`[umicat/hud] HUD scene '${hudId}' has type=${hudScene.type} in file body`);
+    }
+    preloadHudAssets(scene, hudScene, manifest);
+    await runLoader(scene);
+    // Mirrors loadWorldScene: NEAREST filter on every `pixelArt: true` asset.
+    // HUD scene runs in its own Phaser scene with its own texture references
+    // (textures are game-global so this is mostly idempotent with the world
+    // pass, but the HUD might load image assets the world doesn't reference).
+    applyPixelArtFilters(scene, manifest);
+    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(`[umicat/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;
+        // Re-apply origin shift for container-based widgets — initial
+        // spawn does this via `applyContainerOriginShift`, but the
+        // resize path was setting `go.x = pos.x` without the shift,
+        // leaving the container at the raw anchor pos and visually
+        // misaligning its children (drawn centered on container) by
+        // (w/2, h/2). Visible as the editor's selection rect being
+        // slightly off the widget's bg (the rect uses
+        // editorHitWidth/Height centered on the post-shift container.x,
+        // while the bg renders centered on the now-not-shifted
+        // container.x → mismatch). Text widgets (no Container) weren't
+        // affected, which matches the user's observation.
+        const hitW = go.getData?.('editorHitWidth');
+        const hitH = go.getData?.('editorHitHeight');
+        if (typeof hitW === 'number' && typeof hitH === 'number') {
+            const shift = originShiftFor(entity.anchor.side, hitW, hitH);
+            go.x += shift.x;
+            go.y += shift.y;
+        }
+    }
+}
+async function loadHudJson(scene, hudId, file) {
+    const cacheKey = `umicat: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(`[umicat/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(UMICAT_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(UMICAT_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('umicat: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(UMICAT_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(UMICAT_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);
+        // Container-based widgets (icon-button, progress-bar, panel) have no
+        // setOrigin — they were shifted at spawn by `applyContainerOriginShift`
+        // so their centred child visuals appear at the right place. The same
+        // shift must be re-applied on every anchor change, otherwise the
+        // container ends up centred on the raw anchor coord and the visual is
+        // off by ±(w/2, h/2). Text + image have setOrigin so we use that path.
+        const isContainer = entity.kind === 'icon-button' || entity.kind === 'progress-bar' || entity.kind === 'panel';
+        if (isContainer) {
+            const sized = entity;
+            const w = sized.width ?? defaultContainerWidth(entity);
+            const h = sized.height ?? defaultContainerHeight(entity);
+            const shift = originShiftFor(entity.anchor.side, w, h);
+            go.x = pos.x + shift.x;
+            go.y = pos.y + shift.y;
+        }
+        else {
+            go.x = pos.x;
+            go.y = pos.y;
+            // Re-pivot the origin for setOrigin-based widgets (text, image).
+            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 render-field patches. Field names match the flat entity root.
+    const fields = patch.fields;
+    if (fields && entity.kind === 'text') {
+        const v = entity;
+        const text = go;
+        if (typeof fields.fontFamily === 'string')
+            v.fontFamily = fields.fontFamily;
+        if (typeof fields.fontSize === 'number')
+            v.fontSize = fields.fontSize;
+        if (typeof fields.color === 'string')
+            v.color = fields.color;
+        if (typeof fields.align === 'string')
+            v.align = fields.align;
+        if (fields.source && typeof fields.source === 'object') {
+            // Wholesale replacement of `source`. Re-subscribe registry binding.
+            v.source = fields.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 (fields && entity.kind === 'image') {
+        const v = entity;
+        // 9-slice live objects are RenderTextures, not Images — setDisplaySize /
+        // setTint don't behave the same. Mirror the panel/icon-button approach:
+        // mutate the entity record + re-spawn in place.
+        const manifest = getManifest(hud);
+        const asset = manifest.assets?.find((a) => a.id === v.assetId);
+        if (asset?.ninePatch) {
+            for (const [k, val] of Object.entries(fields)) {
+                if (val !== undefined)
+                    v[k] = val;
+            }
+            respawnHudWidget(hud, reg, safeArea, entity, go, entityId);
+        }
+        else {
+            const image = go;
+            if (typeof fields.tint === 'string') {
+                v.tint = fields.tint;
+                image.setTint(parseColor(v.tint));
+            }
+            else if (fields.tint === null) {
+                v.tint = undefined;
+                image.clearTint();
+            }
+            if (typeof fields.alpha === 'number') {
+                v.alpha = fields.alpha;
+                image.setAlpha(fields.alpha);
+            }
+            if (typeof fields.width === 'number' && typeof fields.height === 'number') {
+                v.width = fields.width;
+                v.height = fields.height;
+                image.setDisplaySize(fields.width, fields.height);
+            }
+        }
+    }
+    if (fields && (entity.kind === 'progress-bar' || entity.kind === 'panel' || entity.kind === 'icon-button')) {
+        // All three are containers — flatten the patch onto the entity record
+        // then re-spawn in place. Same pattern across the three kinds.
+        const target = entity;
+        for (const [k, val] of Object.entries(fields)) {
+            if (val === null)
+                delete target[k];
+            else if (val !== undefined)
+                target[k] = val;
+        }
+        respawnHudWidget(hud, reg, safeArea, entity, go, entityId);
+    }
+    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(UMICAT_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(`[umicat/hud] manifest has no asset with id '${id}'`);
+            return a;
+        },
+    };
+    spawnHudEntity(ctx, entity);
+    return true;
+}
+/**
+ * Re-spawn a HUD widget in place after a field mutation. Shared by
+ * applyHudPatch for image-with-9-slice / progress-bar / panel / icon-button
+ * — kinds whose live re-render is too field-conditional to do incrementally.
+ */
+function respawnHudWidget(hud, reg, safeArea, entity, go, entityId) {
+    const oldDepth = go.depth;
+    go.destroy();
+    reg.unregister(entityId);
+    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(`[umicat/hud] manifest has no asset with id '${id}'`);
+            return a;
+        },
+    };
+    const fresh = spawnHudEntity(ctx, entity);
+    if (typeof oldDepth === 'number') {
+        fresh.setDepth?.(oldDepth);
+    }
+}
+/** Destroy a HUD entity. */
+export function deleteHudEntityFromScene(game, entityId) {
+    const hud = game.scene.getScene(UMICAT_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 `createUmicatGame` 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 UmicatHudScene extends Phaser.Scene {
+    constructor() {
+        super({ key: UMICAT_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('[umicat/hud] loadHudScene failed:', e);
+        }
+    }
+}