@umicat/phaser-sdk 1.0.0

package/dist/scene/spawnEntity.js

@@ -0,0 +1,1326 @@
+import Phaser from 'phaser';
+import { isPerFrameHitbox, } from './types.js';
+import { getEntityRegistry } from './EntityRegistry.js';
+/**
+ * Spawn one entity into the scene and register it. Returns the created
+ * GameObject so callers (notably `spawnEntity` itself, recursing on a
+ * group's children) can attach it to a parent container.
+ */
+export function spawnEntity(ctx, entity) {
+    let go;
+    switch (entity.kind) {
+        case 'sprite':
+            go = createSprite(ctx, entity);
+            break;
+        case 'rect':
+            go = createRect(ctx, entity);
+            break;
+        case 'circle':
+            go = createCircle(ctx, entity);
+            break;
+        case 'group':
+            go = createGroup(ctx, entity);
+            break;
+        case 'code-rendered':
+            go = createCodeRendered(ctx, entity);
+            break;
+        case 'tilemap':
+            go = createTilemap(ctx, entity);
+            break;
+        case 'trigger':
+            go = createTriggerStub(ctx, entity);
+            break;
+        default: {
+            const exhaustive = entity;
+            throw new Error(`[umicat/scene] unknown entity kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    applyTransform(go, entity.transform);
+    tagGameObject(go, entity);
+    applyEntityPhysicsIfDeclared(ctx.scene, go, entity);
+    ctx.registry.register(entity.id, entity.role, go);
+    return go;
+}
+/**
+ * Apply a scene entity's optional `physics` block. Only renderable entity
+ * kinds (sprite / rect / circle / code-rendered) carry a body — they mirror
+ * `PrefabKind`. group / tilemap / trigger declare no body even though
+ * `physics` is on the shared `WorldEntityBase`. Routed through the same
+ * `applyEntityPhysics` the prefab path uses (via `prefabToEntity`), so
+ * authored entities and runtime instances get identical, correctly-anchored
+ * bodies.
+ */
+function applyEntityPhysicsIfDeclared(scene, go, entity) {
+    if (!entity.physics)
+        return;
+    if (entity.kind === 'sprite' ||
+        entity.kind === 'rect' ||
+        entity.kind === 'circle' ||
+        entity.kind === 'code-rendered') {
+        applyEntityPhysics(scene, go, entity, entity.physics);
+    }
+}
+/**
+ * Apply an Arcade physics body to a freshly spawned GameObject from a
+ * `PrefabPhysics` block. Shared by `spawnEntity` (authored scene entities)
+ * and `spawnPrefab` (runtime prefab instances, which route through
+ * `spawnEntity` via `prefabToEntity`) so both paths produce identical bodies.
+ *
+ * Body size defaults to the visual's drawn extent; offset defaults to
+ * centering the body inside that extent.
+ *
+ * Code-rendered visuals get an extra origin shift. A Phaser `Graphics` has
+ * `displayOrigin = (0, 0)` (it has no Origin component) while render scripts
+ * draw centered on local (0, 0). The Arcade body positions itself at
+ * `gameObject.x + offset.x` for a Graphics, so a default-offset body would
+ * land at the bottom-right of the visual — the "player floats above the
+ * platform" bug. Shifting the body frame by `(-visualW/2, -visualH/2)`
+ * measures offsets from the visual's top-left, matching sprite / primitive
+ * semantics (those have an Origin component that already accounts for the
+ * centering). This only touches the body, never the Graphics — so rendering
+ * is unaffected. (0.2.52 tried `g.setOrigin` on the Graphics instead, which
+ * shifted rendering and was reverted in 0.2.53; this is the body-only fix.)
+ */
+function applyEntityPhysics(scene, go, entity, physics) {
+    scene.physics.add.existing(go);
+    const body = go.body;
+    if (!body)
+        return; // shouldn't happen post `physics.add.existing` but guard
+    const visualW = renderableWidth(entity);
+    const visualH = renderableHeight(entity);
+    const bodyW = physics.bodyW ?? visualW;
+    const bodyH = physics.bodyH ?? visualH;
+    body.setSize(bodyW, bodyH);
+    // Code-rendered (Graphics) measures offsets from the visual's top-left —
+    // see the doc comment above. Sprite / primitive have an Origin component,
+    // so originShift stays 0 and behavior is identical to <= 0.2.53.
+    const isCodeRendered = entity.kind === 'code-rendered';
+    const originShiftX = isCodeRendered ? -visualW / 2 : 0;
+    const originShiftY = isCodeRendered ? -visualH / 2 : 0;
+    const defaultOffsetX = visualW > bodyW ? (visualW - bodyW) / 2 : 0;
+    const defaultOffsetY = visualH > bodyH ? (visualH - bodyH) / 2 : 0;
+    body.setOffset(originShiftX + (physics.offsetX ?? defaultOffsetX), originShiftY + (physics.offsetY ?? defaultOffsetY));
+    if (physics.immovable !== undefined)
+        body.setImmovable(physics.immovable);
+    if (physics.velocityX !== undefined || physics.velocityY !== undefined) {
+        body.setVelocity(physics.velocityX ?? body.velocity.x, physics.velocityY ?? body.velocity.y);
+    }
+    if (physics.collideWorldBounds)
+        body.setCollideWorldBounds(true);
+    if (physics.bounceX !== undefined || physics.bounceY !== undefined) {
+        body.setBounce(physics.bounceX ?? 0, physics.bounceY ?? 0);
+    }
+}
+/**
+ * Drawn width of a renderable entity, used as the default Arcade body width.
+ * Sprites return 0 so `body.setSize` falls back to the texture frame size.
+ */
+function renderableWidth(e) {
+    if (e.kind === 'sprite')
+        return 0; // body falls back to texture frame
+    if (e.kind === 'rect')
+        return e.width;
+    if (e.kind === 'circle')
+        return e.radius * 2;
+    if (e.kind === 'code-rendered')
+        return e.width ?? 64;
+    return 64;
+}
+/** Drawn height of a renderable entity — see `renderableWidth`. */
+function renderableHeight(e) {
+    if (e.kind === 'sprite')
+        return 0; // body falls back to texture frame
+    if (e.kind === 'rect')
+        return e.height;
+    if (e.kind === 'circle')
+        return e.radius * 2;
+    if (e.kind === 'code-rendered')
+        return e.height ?? 64;
+    return 64;
+}
+function createSprite(ctx, entity) {
+    // Schema guard — flat schema (SDK 0.3.0). Sprite entities require
+    // `assetId` at the top level. Empty / missing → render a magenta
+    // placeholder so the rest of the scene loads + the agent sees a clear
+    // console message rather than the whole scene boot crashing.
+    if (typeof entity.assetId !== 'string') {
+        console.warn(`[umicat/scene] sprite entity '${entity.id}' is missing 'assetId'. ` +
+            `Sprite entities require { kind: 'sprite', assetId: '<id>', transform: {...} }. ` +
+            `Got: ${JSON.stringify(entity, null, 2)}`);
+        return missingAssetPlaceholder(ctx, '<missing assetId>');
+    }
+    let asset;
+    try {
+        asset = ctx.resolveAsset(entity.assetId);
+    }
+    catch (e) {
+        // Soft-fail when the assetId isn't in the manifest. SceneLoader's
+        // preloadSceneAssets logged the warning; here we render a clear
+        // magenta-bordered "?" placeholder so the entity is still visible
+        // and selectable in the editor. Same pattern as createCodeRendered's
+        // missing-render-script path.
+        return missingAssetPlaceholder(ctx, entity.assetId);
+    }
+    // Phaser's add.sprite handles both plain images and atlas/spritesheet
+    // textures uniformly when given (key, frame). For plain images, frame
+    // is undefined and Phaser uses the default frame.
+    const sprite = ctx.scene.add.sprite(0, 0, asset.textureKey, entity.frame);
+    if (entity.tint)
+        sprite.setTint(parseColor(entity.tint));
+    if (typeof entity.alpha === 'number')
+        sprite.setAlpha(entity.alpha);
+    if (entity.flipX)
+        sprite.setFlipX(true);
+    if (entity.flipY)
+        sprite.setFlipY(true);
+    // Slice 8: depth anchor → setOrigin so sprite.y aligns with the asset's
+    // footprint pixel (feet, trunk base, etc.). Without this, ySort compares
+    // geometric centers — characters draw behind walls they're standing in
+    // front of. Phaser's sprite.width / .height reflect frame dims (not the
+    // whole spritesheet texture).
+    if (asset.depthAnchor) {
+        const frameW = sprite.width || 1;
+        const frameH = sprite.height || 1;
+        sprite.setOrigin(asset.depthAnchor.x / frameW, asset.depthAnchor.y / frameH);
+    }
+    // Slice 8: apply asset.hitbox to the physics body IF a body exists. We do
+    // NOT auto-add a body — the agent's physics skill / behavior code decides
+    // when to wire collision. This call is a no-op when asset.hitbox is unset
+    // (chat-only Workflow A path stays untouched).
+    applyAssetHitbox(sprite, asset);
+    return sprite;
+}
+/**
+ * Magenta "?" placeholder for an entity whose assetId isn't in the manifest.
+ * Drawn as a Graphics so the editor's hit-test (which uses getBounds) lands
+ * on the visible square. Mirrors createCodeRendered's missing-script path.
+ */
+function missingAssetPlaceholder(ctx, assetId) {
+    const w = 64;
+    const h = 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);
+    // Diagonal "no entry" lines + a "?" text so it's obvious from a glance.
+    g.lineBetween(-w / 2, -h / 2, w / 2, h / 2);
+    g.lineBetween(w / 2, -h / 2, -w / 2, h / 2);
+    // Phaser Graphics has no intrinsic size — sizeForHitTest sets bounds so
+    // the editor's hit-test (which uses getBounds) can find this entity.
+    sizeForHitTest(g, w, h);
+    g.setDataEnabled();
+    g.setData('unboxyMissingAssetId', assetId);
+    return g;
+}
+function createRect(ctx, e) {
+    if (typeof e.width !== 'number' || typeof e.height !== 'number') {
+        console.warn(`[umicat/scene] rect entity '${e.id}' is missing 'width' / 'height'. ` +
+            `Rect entities require { kind: 'rect', width: N, height: N, fillColor?: '#hex', transform: {...} }. ` +
+            `Got: ${JSON.stringify(e, null, 2)}`);
+        return ctx.scene.add.rectangle(0, 0, 64, 64, 0xff00ff);
+    }
+    const fill = e.fillColor ? parseColor(e.fillColor) : 0xffffff;
+    const rect = ctx.scene.add.rectangle(0, 0, e.width, e.height, fill);
+    if (e.strokeColor && e.strokeWidth) {
+        rect.setStrokeStyle(e.strokeWidth, parseColor(e.strokeColor));
+    }
+    if (typeof e.alpha === 'number')
+        rect.setAlpha(e.alpha);
+    return rect;
+}
+function createCircle(ctx, e) {
+    if (typeof e.radius !== 'number') {
+        console.warn(`[umicat/scene] circle entity '${e.id}' is missing 'radius'. ` +
+            `Circle entities require { kind: 'circle', radius: N, fillColor?: '#hex', transform: {...} }. ` +
+            `Got: ${JSON.stringify(e, null, 2)}`);
+        return ctx.scene.add.circle(0, 0, 32, 0xff00ff);
+    }
+    const fill = e.fillColor ? parseColor(e.fillColor) : 0xffffff;
+    const arc = ctx.scene.add.circle(0, 0, e.radius, fill);
+    if (e.strokeColor && e.strokeWidth) {
+        arc.setStrokeStyle(e.strokeWidth, parseColor(e.strokeColor));
+    }
+    if (typeof e.alpha === 'number')
+        arc.setAlpha(e.alpha);
+    return arc;
+}
+function createGroup(ctx, entity) {
+    const container = ctx.scene.add.container(0, 0);
+    for (const child of entity.children) {
+        if (child.kind === 'group') {
+            // v1 cap: groups can't nest. Surface a clear error rather than
+            // silently producing a half-attached hierarchy.
+            throw new Error(`[umicat/scene] group '${entity.id}' has a nested group child '${child.id}' — v1 supports one level of nesting only`);
+        }
+        const childGo = spawnEntity(ctx, child);
+        container.add(childGo);
+    }
+    return container;
+}
+function createCodeRendered(ctx, entity) {
+    // Schema guard — flat schema (SDK 0.3.0). Code-rendered entities require
+    // `script` at the top level. Without it, accessing `entity.script` is
+    // undefined and we can't resolve a renderer.
+    if (typeof entity.script !== 'string') {
+        console.warn(`[umicat/scene] code-rendered entity '${entity.id}' is missing 'script'. ` +
+            `Code-rendered entities require { kind: 'code-rendered', script: 'src/visuals/<name>.ts', transform: {...} }. ` +
+            `Got: ${JSON.stringify(entity, null, 2)}`);
+        return missingAssetPlaceholder(ctx, '<missing script>');
+    }
+    const w = entity.width ?? 64;
+    const h = entity.height ?? 64;
+    const render = ctx.resolveRenderScript?.(entity.script);
+    if (!render) {
+        // Render scripts have a registry, but a missing entry shouldn't crash
+        // the whole scene boot — the agent might be writing the script in a
+        // follow-up turn. Render a clear "?" placeholder so the user sees the
+        // entity exists but the visual is unresolved.
+        const ph = ctx.scene.add.graphics();
+        ph.fillStyle(0x666666, 0.4);
+        ph.fillRect(-w / 2, -h / 2, w, h);
+        ph.lineStyle(2, 0xff8800, 0.9);
+        ph.strokeRect(-w / 2, -h / 2, w, h);
+        sizeForHitTest(ph, w, h);
+        ph.setData('renderScriptMissing', entity.script);
+        return ph;
+    }
+    const g = ctx.scene.add.graphics();
+    // Install the auto-tracker (0.2.96) so the editor's hit area follows
+    // the script's actual drawn extent — not a stale `width/height` from
+    // the scene file. Critical for procedural visuals (snake, grids,
+    // tilemaps, dynamic UI) where the rendered area changes every frame.
+    const getBounds = installGraphicsTracker(g);
+    g.setData('__unboxyGraphicsBoundsGetter', getBounds);
+    const params = entity.params ?? {};
+    render(g, params);
+    applyTrackedHitArea(g, w, h);
+    // Stash data needed for live re-render from EditorBridge.applyEdit.
+    g.setData('renderScriptPath', entity.script);
+    g.setData('renderScriptParams', params);
+    return g;
+}
+/**
+ * Read the auto-tracker's recorded draw extent and set editor hit-area
+ * data on the GameObject. Falls back to declared `visual.width/height`
+ * (centered on transform) when nothing was tracked (script didn't call
+ * any tracked methods, or called them through unwrapped paths).
+ *
+ * Exported so EditorBridge can call it after a re-render too —
+ * applyCodeRenderedParamsPatch reads new params, calls render again,
+ * then this updates the hit area to the new draw extent.
+ */
+export function applyTrackedHitArea(g, fallbackW, fallbackH) {
+    const getter = g.getData('__unboxyGraphicsBoundsGetter');
+    const bounds = getter ? getter() : null;
+    if (bounds && bounds.width > 0 && bounds.height > 0) {
+        g.setData('editorHitWidth', bounds.width);
+        g.setData('editorHitHeight', bounds.height);
+        g.setData('editorHitOffsetX', bounds.x);
+        g.setData('editorHitOffsetY', bounds.y);
+    }
+    else {
+        g.setData('editorHitWidth', fallbackW);
+        g.setData('editorHitHeight', fallbackH);
+        g.setData('editorHitOffsetX', undefined);
+        g.setData('editorHitOffsetY', undefined);
+    }
+}
+/**
+ * Wrap a Phaser Graphics object's draw methods so they record min/max
+ * XY of every shape drawn through them. Returns a getter that yields
+ * the current bounds (or null if no draws since last `clear()`).
+ *
+ * Covers the methods agents commonly reach for in render scripts:
+ * fillRect, strokeRect, fillRoundedRect, strokeRoundedRect, fillCircle,
+ * strokeCircle, fillEllipse, strokeEllipse, fillTriangle, strokeTriangle,
+ * lineBetween, fillPoint, arc, moveTo, lineTo. `clear()` resets the
+ * tracker so each redraw cycle starts fresh. Less-common methods
+ * (fillPath/strokePath after manual moveTo/lineTo, fillRectShape, etc.)
+ * partially covered via moveTo/lineTo tracking; pure-shape variants
+ * fall back to `visual.width/height` — acceptable for v1.
+ */
+function installGraphicsTracker(g) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    const track = (x, y) => {
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    };
+    const trackRect = (x, y, w, h) => {
+        track(x, y);
+        track(x + w, y + h);
+    };
+    const trackRadius = (x, y, r) => {
+        track(x - r, y - r);
+        track(x + r, y + r);
+    };
+    const gAny = g;
+    const wrap = (name, pre) => {
+        const orig = gAny[name].bind(g);
+        gAny[name] = (...args) => {
+            pre(...args);
+            return orig(...args);
+        };
+    };
+    wrap('fillRect', (x, y, w, h) => trackRect(x, y, w, h));
+    wrap('strokeRect', (x, y, w, h) => trackRect(x, y, w, h));
+    wrap('fillRoundedRect', (x, y, w, h) => trackRect(x, y, w, h));
+    wrap('strokeRoundedRect', (x, y, w, h) => trackRect(x, y, w, h));
+    wrap('fillCircle', (x, y, r) => trackRadius(x, y, r));
+    wrap('strokeCircle', (x, y, r) => trackRadius(x, y, r));
+    wrap('fillEllipse', (x, y, w, h) => trackRect(x - w / 2, y - h / 2, w, h));
+    wrap('strokeEllipse', (x, y, w, h) => trackRect(x - w / 2, y - h / 2, w, h));
+    wrap('fillTriangle', (x1, y1, x2, y2, x3, y3) => {
+        track(x1, y1);
+        track(x2, y2);
+        track(x3, y3);
+    });
+    wrap('strokeTriangle', (x1, y1, x2, y2, x3, y3) => {
+        track(x1, y1);
+        track(x2, y2);
+        track(x3, y3);
+    });
+    wrap('lineBetween', (x1, y1, x2, y2) => {
+        track(x1, y1);
+        track(x2, y2);
+    });
+    wrap('moveTo', (x, y) => track(x, y));
+    wrap('lineTo', (x, y) => track(x, y));
+    wrap('fillPoint', (x, y, size) => {
+        const s = (typeof size === 'number' ? size : 1) / 2;
+        trackRect(x - s, y - s, s * 2, s * 2);
+    });
+    wrap('arc', (x, y, r) => trackRadius(x, y, r));
+    // `clear()` resets the tracker so each redraw cycle starts fresh.
+    const origClear = gAny['clear'].bind(g);
+    gAny['clear'] = () => {
+        minX = Infinity;
+        minY = Infinity;
+        maxX = -Infinity;
+        maxY = -Infinity;
+        return origClear();
+    };
+    return () => {
+        if (minX === Infinity)
+            return null;
+        return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+    };
+}
+/**
+ * Phaser Graphics doesn't track its drawn area — `getBounds()` returns
+ * a 0×0 rect because the Graphics class doesn't include the Size/Origin
+ * mixins by default. We:
+ *
+ *  1. Call `setSize(w, h)` so the GameObject has proper dimensions
+ *     for Phaser arcade physics to size + position bodies correctly.
+ *     Without this, `physics.add.existing(go)` creates a 0×0 body
+ *     anchored to the GO's transform position, and any subsequent
+ *     `body.setOffset(x, y)` is measured from sprite.x/sprite.y
+ *     rather than from a top-left corner — that mismatch between the
+ *     agent's mental model (Phaser docs: offset is from sprite
+ *     top-left) and Phaser's actual math (offset is from
+ *     `sprite.x - sprite.displayOriginX`) produces a "player floats
+ *     above the platform" bug because the body sits to the bottom-
+ *     right of the drawn visual.
+ *
+ *  2. Call `setOrigin(0.5, 0.5)` so the GO's transform position IS
+ *     its visual center — matching the render-script convention of
+ *     drawing around (0, 0). Combined with the explicit setSize above,
+ *     this makes `body.setOffset` behave per standard Phaser arcade
+ *     semantics (offset from GO top-left).
+ *
+ *  3. Stash the same dimensions on the data manager too, for the
+ *     editor's hit-test path (some legacy editor code reads from
+ *     `editorHitWidth`/`editorHitHeight` before falling back to
+ *     `getBounds()`).
+ *
+ * Surfaced 2026-05-14 on game 7f624e76 (platformer test): player
+ * floated ~20 px above platforms because the agent's reasonable
+ * `body.setSize(20, 40); body.setOffset(4, 4)` (which assumes
+ * Phaser docs' "offset from top-left" semantics) didn't behave
+ * that way without explicit setSize / setOrigin on the Graphics.
+ * Per 0.2.23 changelog this was supposed to be done; the actual
+ * setSize / setOrigin calls were dropped in a later refactor when
+ * this helper was extracted.
+ */
+function sizeForHitTest(g, width, height) {
+    // Reverted in 0.2.53 (2026-05-14): 0.2.52 added g.setSize + g.setOrigin
+    // here to make Phaser arcade body offsets behave per standard Phaser
+    // docs ("offset from top-left"). But Phaser's `setOrigin` ALSO shifts
+    // Graphics rendering — Phaser computes `displayOriginX = originX *
+    // width` and renders the Graphics commands offset by -displayOrigin.
+    // Render scripts draw around (0, 0) assuming that's the visual center;
+    // adding setOrigin(0.5, 0.5) made those drawings render at
+    // (transform.x - w/2, transform.y - h/2) instead — i.e., a 14×24 shift
+    // up-left for the canonical 28×48 humanoid. Every code-rendered entity
+    // in every existing game appeared in the wrong world position.
+    //
+    // The right long-term fix is documentation: code-rendered entities have
+    // Graphics with width=0/height=0/origin=(0,0), so Phaser arcade body
+    // offsets are interpreted from `sprite.x` / `sprite.y` directly (not
+    // from a top-left). Agents writing physics for code-rendered entities
+    // should compute body.setOffset accounting for this — see the prefab
+    // skill's body-offset cookbook.
+    //
+    // For now, restore the data-manager mirror that was the only thing
+    // this helper ever actually did before 0.2.52.
+    g.setData('editorHitWidth', width);
+    g.setData('editorHitHeight', height);
+}
+function applyTransform(go, t) {
+    // Most game objects implement Transform; Container does too. Cast through
+    // a permissive shape so this works for sprite/rect/circle/container alike.
+    const target = go;
+    target.x = t.x;
+    target.y = t.y;
+    if (typeof t.rotation === 'number')
+        target.rotation = t.rotation;
+    if (typeof t.scaleX === 'number')
+        target.scaleX = t.scaleX;
+    if (typeof t.scaleY === 'number')
+        target.scaleY = t.scaleY;
+    if (typeof t.depth === 'number' && target.setDepth)
+        target.setDepth(t.depth);
+}
+function tagGameObject(go, entity) {
+    go.setData('entityId', entity.id);
+    // Slice 6 Phase B: paint-mode detection reads entityKind off the GO without
+    // a registry round-trip. Tag every entity so the check is uniform — only
+    // tilemap consumers branch on it today, but other kinds (trigger, group)
+    // may need similar fast-path checks in future slices.
+    go.setData('entityKind', entity.kind);
+    if (entity.role)
+        go.setData('entityRole', entity.role);
+    if (entity.properties)
+        go.setData('entityProperties', entity.properties);
+    // Slice 8: ySort loop reads transform.depth to skip explicit-depth entities.
+    // Stash the transform on the GO's data manager to avoid a round-trip back
+    // to the scene file every frame.
+    go.setData('entityTransform', entity.transform);
+    // Slice 8: assetUpdate handler walks the registry to find all instances of
+    // an asset whose hitbox/anchor changed. Stash the assetId for sprite
+    // entities so the lookup is O(n) on the registry rather than a per-entity
+    // re-parse of the scene file.
+    if (entity.kind === 'sprite') {
+        go.setData('entityAssetId', entity.assetId);
+    }
+    // Slice 6 Phase B: tilemap-specific stash so the editor's tilemap
+    // handler can read cellSize / size / per-layer dims without re-parsing
+    // the scene file every paint op.
+    if (entity.kind === 'tilemap') {
+        go.setData('tilemapTileSize', entity.tileSize);
+        go.setData('tilemapSize', entity.size);
+    }
+}
+/**
+ * Trigger stub renderer — slice 3. Renders the trigger zone as a
+ * semi-transparent fill with cyan tint per design 03 §8.2 (in edit mode it
+ * is always visible; at play time the SDK will hide it once slice 5 wires
+ * the behavior layer).
+ */
+function createTriggerStub(ctx, entity) {
+    const TINT = 0x00bfff; // cyan-ish "neutral trigger" per design
+    const FILL_ALPHA = 0.25;
+    const STROKE_ALPHA = 0.7;
+    if (entity.shape.kind === 'rect') {
+        const r = ctx.scene.add.rectangle(0, 0, entity.shape.width, entity.shape.height, TINT, FILL_ALPHA);
+        r.setStrokeStyle(1.5, TINT, STROKE_ALPHA);
+        return r;
+    }
+    // circle
+    const c = ctx.scene.add.circle(0, 0, entity.shape.radius, TINT, FILL_ALPHA);
+    c.setStrokeStyle(1.5, TINT, STROKE_ALPHA);
+    return c;
+}
+/**
+ * Tilemap renderer — slice 6 Phase A (2026-05-18).
+ *
+ * Returns a `Container` parent holding (a) a grid-sketch Graphics drawn at
+ * low alpha as background so the tilemap's bounds remain visible even
+ * where layer data is empty, and (b) one Phaser `TilemapLayer` per
+ * authored layer (only when that layer has `data`). The container is
+ * positioned at the entity's `transform.x/y`; children are offset by
+ * `(-w/2, -h/2)` so the tilemap is centered on the entity origin —
+ * matches sprite / primitive / code-rendered convention.
+ *
+ * Soft-fail strategy mirrors the rest of the loader: a layer whose
+ * tileset isn't in the manifest or isn't loaded yet is skipped with a
+ * warn; the background grid still renders so the entity stays selectable.
+ * preloadSceneAssets already warned about missing assets — this is
+ * defense-in-depth.
+ *
+ * Phase B will add live-edit handlers (paint cell, add/remove layer,
+ * toggle visibility). Phase D will add Wang autotile resolution at
+ * paint time. Phase C wires per-tile collision via `setCollisionByProperty`
+ * once tileset metadata carries `tiles[<idx>].metadata.solid`.
+ */
+function createTilemap(ctx, entity) {
+    const tileW = entity.tileSize.width;
+    const tileH = entity.tileSize.height;
+    const cellsW = entity.size.width;
+    const cellsH = entity.size.height;
+    const pxW = cellsW * tileW;
+    const pxH = cellsH * tileH;
+    const left = -pxW / 2;
+    const top = -pxH / 2;
+    const container = ctx.scene.add.container(0, 0);
+    // Background grid sketch — drawn first so layer tiles render on top.
+    // Kept even when layers have data so empty cells show the grid; this
+    // also makes empty tilemaps (no painted data yet) visible + selectable.
+    // **Editor-only**: hidden by default; `enterEdit` walks tilemap entities
+    // and toggles visibility on. `exitEdit` toggles back off. Without this
+    // the grid bleeds through into Play mode where it has no purpose and
+    // visually conflicts with the actual painted tiles.
+    const grid = ctx.scene.add.graphics();
+    grid.fillStyle(0xffffff, 0.04);
+    grid.fillRect(left, top, pxW, pxH);
+    grid.lineStyle(2, 0xaaaaaa, 0.45);
+    grid.strokeRect(left, top, pxW, pxH);
+    if (tileW >= 8 && cellsW * cellsH < 4000) {
+        grid.lineStyle(1, 0xaaaaaa, 0.1);
+        for (let i = 1; i < cellsW; i++) {
+            const x = left + i * tileW;
+            grid.beginPath();
+            grid.moveTo(x, top);
+            grid.lineTo(x, top + pxH);
+            grid.strokePath();
+        }
+        for (let i = 1; i < cellsH; i++) {
+            const y = top + i * tileH;
+            grid.beginPath();
+            grid.moveTo(left, y);
+            grid.lineTo(left + pxW, y);
+            grid.strokePath();
+        }
+    }
+    grid.setData('unboxyTilemapGrid', true);
+    grid.setVisible(false);
+    container.add(grid);
+    // Create one Phaser TilemapLayer per authored layer.
+    //
+    // **Phaser quirk**: TilemapLayer does NOT inherit parent Container
+    // transforms at render time (the renderer treats `layer.x`/`layer.y` as
+    // world coords directly). If we made layers Container children, the cell
+    // grid would render at the wrong world position even though click→cell
+    // math worked. Symptom: paint clicks land in the editor void (near world
+    // origin) instead of inside the tilemap's bounds.
+    //
+    // Workaround: layers are scene-root siblings (NOT container children),
+    // positioned at WORLD coords matching the container's transform. The
+    // container holds only the grid sketch for visual bounds + hit-test.
+    // Layer refs are stashed on the container's data manager so the painter
+    // can find them by id. A per-frame sync hook (`installTilemapLayerSync`,
+    // installed by `loadWorldScene` when any tilemap entity exists) keeps
+    // layer positions in lockstep with the container's transform — so
+    // dragging the entity still visually moves the painted tiles.
+    const sortedLayers = [...entity.layers].sort((a, b) => (a.z ?? 0) - (b.z ?? 0));
+    const layerRefs = [];
+    for (const layer of sortedLayers) {
+        const layerObj = renderLayerInto(ctx, entity, layer, cellsW, cellsH, tileW, tileH);
+        if (!layerObj)
+            continue;
+        // Position in WORLD coords directly. The container's transform.x/y has
+        // already been applied to the container above; we mirror it to the
+        // layer so the layer renders at the same world position.
+        layerObj.x = entity.transform.x + left;
+        layerObj.y = entity.transform.y + top;
+        if (layer.visible === false)
+            layerObj.setVisible(false);
+        // Tag with layer id so the painter can locate by id (survives reorders).
+        layerObj.setData('tilemapLayerId', layer.id);
+        // Stamp the parent tilemap entity id so the sync hook can find which
+        // container each layer belongs to without a registry walk per frame.
+        layerObj.setData('tilemapEntityId', entity.id);
+        // Stash the layer's local-offset (left/top) so the sync hook can
+        // recompute world position from container.x/y + offset whenever the
+        // container moves. These are stable for a layer's lifetime.
+        layerObj.setData('tilemapLocalOffsetX', left);
+        layerObj.setData('tilemapLocalOffsetY', top);
+        // Slice 6 Phase C — per-tile metadata + auto-collision. Called here
+        // AFTER layer.x/y are set so `tile.getLeft()` returns correct world
+        // coords for sub-tile static body placement; calling this inside
+        // `renderLayerInto` would create bodies at world origin (visible as
+        // collision bodies stacked top-left of the canvas in earlier bug).
+        const tilesetForLayer = layerObj.tileset[0];
+        const tilesetIdForLayer = layer.tilesetIds?.[0];
+        if (tilesetForLayer && tilesetIdForLayer) {
+            try {
+                const layerAsset = ctx.resolveAsset(tilesetIdForLayer);
+                applyTilesetTileMetadata(tilesetForLayer, layerObj, layerAsset);
+                // Phase F — arm tile animations (water flow / lava bubble /
+                // torch flicker). Must run AFTER applyTilesetTileMetadata so
+                // the layer's tile.index field is fully populated when we scan
+                // for cells matching animation rootTileIndex.
+                applyTilesetAnimations(layerObj, layerAsset);
+            }
+            catch {
+                /* asset missing already warned by renderLayerInto */
+            }
+        }
+        layerRefs.push(layerObj);
+    }
+    // Stash layer refs on the container so the painter + structure-op handlers
+    // (addLayer / removeLayer / setLayerVisibility) can find them without a
+    // scene-wide walk. The container's `list` no longer holds them.
+    container.setData('tilemapLayers', layerRefs);
+    // Hit-test stash for the editor (Container reports 0×0 bounds otherwise).
+    sizeForHitTest(container, pxW, pxH);
+    return container;
+}
+/**
+ * Build one `TilemapLayer` for a single tilemap-entity layer. Returns
+ * `null` when the layer is unrenderable (no data, missing tileset, etc.)
+ * — caller skips and the background grid still indicates the bounds.
+ */
+function renderLayerInto(ctx, entity, layer, cellsW, cellsH, tileW, tileH) {
+    // Pick first tileset for Phase A (multi-tileset blending deferred).
+    const tilesetId = layer.tilesetIds?.[0];
+    if (!tilesetId) {
+        // Without a tileset there's nothing to paint with — skip even an empty
+        // layer. The grid sketch from the parent container still indicates
+        // bounds. Phase B's painter creates layers with a tileset attached;
+        // this branch only fires for hand-authored degenerate cases.
+        return null;
+    }
+    let asset;
+    try {
+        asset = ctx.resolveAsset(tilesetId);
+    }
+    catch {
+        // preloadSceneAssets already warned about this missing asset.
+        return null;
+    }
+    if (!ctx.scene.textures.exists(asset.textureKey)) {
+        // eslint-disable-next-line no-console
+        console.warn(`[umicat/scene] tilemap layer '${layer.id}' tileset '${tilesetId}' texture not loaded; skipping layer`);
+        return null;
+    }
+    // Cell size: prefer the asset's tileset metadata, then fall back to
+    // spritesheet's frame dims (if the user is using a spritesheet asset
+    // as a tileset), then fall back to the tilemap entity's tileSize.
+    // The Configure Tileset modal (Phase A.2) is what gets users to populate
+    // `asset.tileset.cellSize` deliberately — but for the SDK alone, these
+    // fallbacks let a hand-authored tilemap render against any image asset.
+    const cellSize = resolveTilesetCellSize(asset, tileW, tileH);
+    // Normalise data: Phaser's tilemap factory wants a rectangular 2D array
+    // of integers. Coerce missing rows / cells / non-numeric entries to -1
+    // (Phaser's "no tile" sentinel). Tile indices are 0-based in the source
+    // image (row-major), matching Phaser's native convention. An empty layer
+    // (no `data` field) materializes as an all-(-1) grid so the painter has
+    // something to mutate — Phase B's `putTileAt` calls then flip cells from
+    // -1 to real indices in place.
+    const grid = [];
+    const sourceData = layer.data ?? [];
+    for (let y = 0; y < cellsH; y++) {
+        const row = sourceData[y] ?? [];
+        const out = new Array(cellsW);
+        for (let x = 0; x < cellsW; x++) {
+            const v = row[x];
+            out[x] = typeof v === 'number' ? v : -1;
+        }
+        grid.push(out);
+    }
+    let map;
+    try {
+        map = ctx.scene.make.tilemap({
+            data: grid,
+            tileWidth: cellSize.width,
+            tileHeight: cellSize.height,
+        });
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.warn(`[umicat/scene] failed to construct tilemap for entity '${entity.id}' layer '${layer.id}': ${String(e)}`);
+        return null;
+    }
+    const tileset = map.addTilesetImage(tilesetId, asset.textureKey, cellSize.width, cellSize.height, asset.tileset?.margin ?? 0, asset.tileset?.spacing ?? 0);
+    if (!tileset) {
+        // eslint-disable-next-line no-console
+        console.warn(`[umicat/scene] addTilesetImage returned null for '${tilesetId}' on entity '${entity.id}' layer '${layer.id}'; skipping`);
+        return null;
+    }
+    const layerObj = map.createLayer(0, tileset, 0, 0);
+    if (!layerObj) {
+        // eslint-disable-next-line no-console
+        console.warn(`[umicat/scene] createLayer returned null for entity '${entity.id}' layer '${layer.id}'; skipping`);
+        return null;
+    }
+    // Slice 6 Phase D fix — prevent tile edge bleeding. Two-pronged:
+    //  (1) NEAREST filter on tileset texture — kills bilinear interpolation
+    //      that would sample neighbor-tile pixels at tile boundaries.
+    //  (2) `roundPixels = true` on the world camera — snaps the camera to
+    //      integer pixel positions so the GPU's NEAREST sampler can't pick
+    //      "between" pixels at tile edges due to subpixel camera offsets.
+    // Together they kill the thin dark hairlines visible at tile edges on
+    // typical (non-extruded) tilesets like Sprout Lands. Tilemaps are
+    // virtually always pixel art; applying these unconditionally is safe.
+    // Editor camera roundPixels is set separately in EditorBridge.
+    const tex = ctx.scene.textures.get(asset.textureKey);
+    if (tex)
+        tex.setFilter(Phaser.Textures.FilterMode.NEAREST);
+    ctx.scene.cameras.main.setRoundPixels(true);
+    // If render tileSize differs from source cellSize, scale the layer so
+    // each cell renders at the entity's declared tileSize. Skipping this
+    // would render at source pixels and visually mismatch the grid sketch.
+    if (cellSize.width !== tileW || cellSize.height !== tileH) {
+        layerObj.setScale(tileW / cellSize.width, tileH / cellSize.height);
+    }
+    // Slice 6 Phase C — stash the manifest asset id so live `assetUpdate`
+    // can find every layer affected by a Tile Metadata Editor save. The
+    // Phaser Tileset object's `name` IS the manifest id (set via
+    // addTilesetImage's first arg), but stashing on the layer is cheaper
+    // and avoids depending on Phaser internals.
+    layerObj.setData('tilemapTilesetId', tilesetId);
+    // Note: `applyTilesetTileMetadata` is intentionally NOT called here —
+    // the sub-tile body half (`syncSubTileBodies`) needs world coords,
+    // which `tile.getLeft()` only reports correctly AFTER the caller sets
+    // `layerObj.x/y`. Caller (createTilemap) invokes it post-positioning.
+    return layerObj;
+}
+/**
+ * Slice 6 Phase C — wire per-tile metadata onto a Phaser tileset + layer.
+ *
+ * Sources `asset.tileset.tiles` (sparse map keyed by tile index) and:
+ *   1. Replaces `tileset.tileProperties` so any FUTURE `putTileAt` call
+ *      auto-stamps the new tile's `properties` from the lookup. Phaser
+ *      reads `tileset.tileProperties[index]` at tile-creation time.
+ *   2. Walks existing tiles via `layer.forEachTile` and refreshes each
+ *      tile's `properties` — needed for tiles that were already painted
+ *      before this fn ran (initial scene load, or `assetUpdate` replay).
+ *   3. Calls `layer.setCollisionByProperty({ solid: true })` so any tile
+ *      whose `properties.solid === true` participates in Arcade collision.
+ *      Idempotent + safe to call when no tile is solid (no-op).
+ *
+ * Exported because `EditorBridge.applyTilemapStructureOp` (addLayer) and
+ * `EditorBridge.handleAssetUpdate` both need to re-arm collision wiring
+ * without going through the full scene load. SDK 0.2.115+.
+ */
+export function applyTilesetTileMetadata(tileset, layer, asset) {
+    applyTilesetTileMetadataInternal(layer.scene, tileset, layer, asset);
+}
+function applyTilesetTileMetadataInternal(scene, tileset, layer, asset) {
+    const tiles = asset.tileset?.tiles;
+    // Always REPLACE (not merge) so the live `assetUpdate` path correctly
+    // clears properties on tiles that no longer have metadata. Empty {} is
+    // the "no per-tile properties" state Phaser expects.
+    const tileProperties = {};
+    if (tiles) {
+        for (const key of Object.keys(tiles)) {
+            const idx = Number(key);
+            if (!Number.isFinite(idx))
+                continue;
+            const meta = tiles[idx];
+            if (!meta)
+                continue;
+            const props = {};
+            if (meta.solid != null)
+                props.solid = meta.solid;
+            if (meta.oneWay != null)
+                props.oneWay = meta.oneWay;
+            if (meta.slope != null)
+                props.slope = meta.slope;
+            if (meta.damage != null)
+                props.damage = meta.damage;
+            if (meta.terrainTag != null)
+                props.terrainTag = meta.terrainTag;
+            if (meta.movement != null)
+                props.movement = meta.movement;
+            if (meta.groundType != null)
+                props.groundType = meta.groundType;
+            if (meta.customTag != null)
+                props.customTag = meta.customTag;
+            if (Object.keys(props).length > 0) {
+                tileProperties[idx] = props;
+            }
+        }
+    }
+    // Mutate the tileset's lookup so newly-painted tiles inherit properties.
+    // Phaser's TS types declare `tileProperties` as readonly object[]; the
+    // runtime accepts a plain numeric-keyed Record. Cast through unknown to
+    // bypass the structural mismatch without disabling the wider TS surface.
+    tileset.tileProperties = tileProperties;
+    // Refresh ALREADY-painted tiles. Phaser copies properties from the
+    // tileset at tile-creation time; tiles painted BEFORE this call won't
+    // see the new properties unless we stamp them directly.
+    layer.forEachTile((tile) => {
+        // -1 / null tiles are skipped by Phaser internally; only real tiles
+        // reach the callback. Use the index as the lookup key.
+        const props = tileProperties[tile.index];
+        // Always replace tile.properties so removed-metadata also clears.
+        // Phaser's collide-by-property re-reads this on each call.
+        tile.properties = props ? { ...props } : {};
+    });
+    // Arm collision. `setCollisionByProperty` walks all tiles, checks each
+    // tile's `properties.solid === true`, and flips `tile.collides`. Safe to
+    // call when zero tiles are solid (just sets nothing). Phaser's collide-
+    // by-property is the standard pattern; behavior code only needs
+    // `scene.physics.add.collider(player, layer)` to get the collision.
+    layer.setCollisionByProperty({ solid: true });
+    // Slice 6 Phase C follow-up — sub-tile collision rects. Godot/Tiled-style
+    // per-tile shape, painted ONCE on the tile in the editor + materialized
+    // as invisible Arcade static bodies per painted instance at runtime.
+    // Phaser's TilemapLayer has no native sub-tile collision; static bodies
+    // are the standard escape hatch the Phaser community uses for this case.
+    syncSubTileBodies(scene, layer, asset);
+}
+// --- Animated tiles (slice 6 Phase F) -------------------------------------
+const ANIM_CLEANUP_KEY = 'unboxyTilesetAnimCleanup';
+const ANIM_RESET_KEY = 'unboxyTilesetAnimReset';
+/**
+ * Arm tile animations on this layer — Phase F (slice 6 — design doc 06 §8).
+ *
+ * Reads `asset.tileset.animations[]`, finds every painted cell whose source
+ * index matches an animation's `rootTileIndex`, installs a per-frame UPDATE
+ * listener that swaps each cell's `tile.index` to the current frame.
+ * All cells with the same root animate in lockstep (Sprout Lands water
+ * lake-cells flow together).
+ *
+ * Idempotent — re-calling tears down the prior listener and re-scans. Used
+ * by:
+ *  - `createTilemap` at scene boot (initial arm)
+ *  - `EditorBridge.handleAssetUpdate` (when Animation Editor saves)
+ *  - `EditorBridge.applyTilemapStructureOp addLayer` (new layer arm)
+ *  - any subsequent paint op (host's `handleEditTilemap` re-runs metadata)
+ *
+ * Edit-mode caveat: scenes are `setActive(false)` in edit mode → scene
+ * UPDATE doesn't fire → the swap handler stays dormant → animated cells
+ * stay on whatever frame they were on when edit was entered. To keep edit
+ * mode showing the static "data" view, `EditorBridge.enterEdit` calls
+ * `resetTilesetAnimationsToRoot` which walks all animated cells + sets
+ * them back to root. exitEdit → next UPDATE tick re-applies current frame.
+ *
+ * Save-path safety: the iframe's mutated `tile.index` per frame doesn't
+ * leak into the host's draft state (home-ui keeps its own copy in
+ * `useEditorDraft`'s baseline + commands). Mid-animation Cmd+S saves the
+ * root indices, not the displayed frame.
+ *
+ * Phaser API note: Phaser 3 parses Tiled's `tile.animation` field into
+ * `tileset.tileData[id].animation` but its TilemapLayer renderer does NOT
+ * consume it. The community `phaser-animated-tiles` plugin bridges that
+ * gap but has been bit-rotted since 3.80. This is a 50-line custom impl
+ * that does the swap directly — same algorithm, no external dep.
+ */
+export function applyTilesetAnimations(layer, asset) {
+    // Clear any prior animation arm on this layer (reset cells + uninstall).
+    const prevCleanup = layer.getData(ANIM_CLEANUP_KEY);
+    prevCleanup?.();
+    layer.setData(ANIM_CLEANUP_KEY, undefined);
+    const animations = asset.tileset?.animations ?? [];
+    if (animations.length === 0)
+        return;
+    // Index by rootTileIndex for O(1) match. Also collect every frame's
+    // tileIndex so re-application (cells already mid-animation) can map back
+    // to their root — needed because the previous cleanup happens BEFORE
+    // this scan, so cells are at root when we scan, but if some external
+    // path mutated indices we still want to catch them.
+    const animByRoot = new Map();
+    const frameToRoot = new Map();
+    for (const anim of animations) {
+        if (!anim.frames || anim.frames.length === 0)
+            continue;
+        animByRoot.set(anim.rootTileIndex, anim);
+        frameToRoot.set(anim.rootTileIndex, anim.rootTileIndex);
+        for (const f of anim.frames) {
+            if (!frameToRoot.has(f.tileIndex)) {
+                frameToRoot.set(f.tileIndex, anim.rootTileIndex);
+            }
+        }
+    }
+    if (animByRoot.size === 0)
+        return;
+    // Scan the layer once for cells that match a root (or any frame —
+    // defensive against cells left mid-frame from a prior arm). Store the
+    // Tile refs + which animation drives them — refs persist for the
+    // layer's lifetime (Phaser doesn't recreate Tile objects).
+    const cells = [];
+    layer.forEachTile((tile) => {
+        if (tile.index < 0)
+            return;
+        const rootIdx = frameToRoot.get(tile.index);
+        if (rootIdx === undefined)
+            return;
+        const anim = animByRoot.get(rootIdx);
+        if (!anim)
+            return;
+        cells.push({ tile, anim });
+    });
+    if (cells.length === 0)
+        return;
+    const scene = layer.scene;
+    const startTime = scene.time.now;
+    // Precompute total durations per animation — avoids re-summing each tick.
+    const totalDurByAnim = new Map();
+    for (const a of animByRoot.values()) {
+        totalDurByAnim.set(a, a.frames.reduce((sum, f) => sum + Math.max(16, f.duration), 0));
+    }
+    const handler = () => {
+        const now = scene.time.now;
+        for (const { tile, anim } of cells) {
+            const total = totalDurByAnim.get(anim);
+            if (!total)
+                continue;
+            const phase = (now - startTime) % total;
+            let acc = 0;
+            let frameTileIndex = anim.frames[0].tileIndex;
+            for (const f of anim.frames) {
+                acc += Math.max(16, f.duration);
+                if (phase < acc) {
+                    frameTileIndex = f.tileIndex;
+                    break;
+                }
+            }
+            if (tile.index !== frameTileIndex) {
+                tile.index = frameTileIndex;
+            }
+        }
+    };
+    scene.events.on(Phaser.Scenes.Events.UPDATE, handler);
+    // Two helpers stashed on layer.data:
+    //   - reset: walks cells + sets index back to root WITHOUT touching the
+    //     handler. Used by enterEdit to freeze the editor view on the
+    //     authored frame; the scene-pause means the handler doesn't fire,
+    //     and on exitEdit the next UPDATE tick will re-swap from elapsed
+    //     time → correct frame seamlessly.
+    //   - cleanup: full teardown — runs reset() AND uninstalls the UPDATE
+    //     handler. Used by re-application (assetUpdate / paint-op metadata
+    //     re-arm) and by scene SHUTDOWN.
+    const reset = () => {
+        for (const { tile, anim } of cells) {
+            if (tile.index !== anim.rootTileIndex) {
+                tile.index = anim.rootTileIndex;
+            }
+        }
+    };
+    const cleanup = () => {
+        scene.events.off(Phaser.Scenes.Events.UPDATE, handler);
+        reset();
+    };
+    layer.setData(ANIM_CLEANUP_KEY, cleanup);
+    layer.setData(ANIM_RESET_KEY, reset);
+    // Tear down on scene shutdown so cross-scene navigation doesn't leak the
+    // handler. Scene SHUTDOWN fires before scene START on the next visit.
+    scene.events.once(Phaser.Scenes.Events.SHUTDOWN, () => {
+        const c = layer.getData(ANIM_CLEANUP_KEY);
+        c?.();
+        layer.setData(ANIM_CLEANUP_KEY, undefined);
+        layer.setData(ANIM_RESET_KEY, undefined);
+    });
+}
+/**
+ * Reset every animated cell on a tilemap container to its root tile index.
+ * Called by `EditorBridge.enterEdit` so animated cells show the static
+ * authored frame in the editor, not whatever was currently visible at the
+ * moment the user toggled into edit mode. exitEdit doesn't need a paired
+ * call — the next UPDATE tick after scenes resume swaps each cell back to
+ * its current animation frame.
+ */
+export function resetTilesetAnimationsToRoot(container) {
+    const layers = container.getData('tilemapLayers') ?? [];
+    for (const layer of layers) {
+        const reset = layer.getData(ANIM_RESET_KEY);
+        // reset() ONLY touches tile indices — handler stays installed so
+        // exitEdit picks up where animation left off on next UPDATE tick.
+        reset?.();
+    }
+}
+const SUB_TILE_GROUP_KEY = 'unboxySubTileStaticGroup';
+/**
+ * Rebuild the per-layer `StaticGroup` of invisible sub-tile collision
+ * bodies (Phase C follow-up — sub-tile collision rects).
+ *
+ * Walks the layer's painted tiles, finds tiles whose tileset metadata
+ * carries a `collisionRect`, disables Phaser's native cell-rect collision
+ * for those tiles (`tile.setCollision(false, ...)`), and creates an
+ * invisible Rectangle GameObject with an Arcade static body sized to the
+ * sub-rect. Bodies live in a `Phaser.Physics.Arcade.StaticGroup` stashed
+ * on the layer's data manager so subsequent calls (e.g. painter ops, live
+ * `assetUpdate` replay) can wipe + rebuild cleanly.
+ *
+ * Cheap when no tile in the tileset has a `collisionRect` — single map
+ * scan + early return without touching layer tiles.
+ *
+ * Behavior code: use `addTilemapCollider(scene, entityId, target)` so
+ * both the layer's cell-collision AND the sub-tile group are wired up at
+ * once. Doing only `physics.add.collider(player, layer)` covers the
+ * cell-rect tiles but NOT the sub-rect bodies — a footgun without the
+ * helper.
+ */
+function syncSubTileBodies(scene, layer, asset) {
+    // Fast-path: no Arcade physics in this scene (e.g. a HUD-only scene)
+    // means no static bodies to create. Bail without touching anything.
+    if (!scene.physics?.add)
+        return;
+    // Get or create the group. Stashed on the layer's data manager so this
+    // function is the SOLE owner — no other code touches it.
+    let group = layer.getData(SUB_TILE_GROUP_KEY);
+    if (!group) {
+        group = scene.physics.add.staticGroup();
+        layer.setData(SUB_TILE_GROUP_KEY, group);
+    }
+    // Clear existing bodies. `clear(true, true)` destroys GOs + their bodies
+    // so we rebuild from a clean slate. Bounded — at most O(painted_cells).
+    group.clear(true, true);
+    // Build a fast index → collisionRects lookup. Most tiles in a tileset
+    // won't have sub-rects, so this is sparse.
+    const tiles = asset.tileset?.tiles;
+    if (!tiles)
+        return;
+    const subRectsByIdx = new Map();
+    for (const key of Object.keys(tiles)) {
+        const idx = Number(key);
+        if (!Number.isFinite(idx))
+            continue;
+        const meta = tiles[idx];
+        if (meta?.collisionRects && meta.collisionRects.length > 0) {
+            subRectsByIdx.set(idx, meta.collisionRects);
+        }
+    }
+    if (subRectsByIdx.size === 0)
+        return;
+    // Walk painted tiles. For each tile with one-or-more sub-rects: disable
+    // its native cell collision (so it doesn't double-collide) + spawn one
+    // invisible Rectangle with a static body per sub-rect. Position uses
+    // `tile.getLeft()/getTop()` which returns WORLD coords accounting for
+    // the layer's transform — correct when cellSize != tileSize and the
+    // layer is scaled. Multi-rect lets one tile carry L/U/frame collision.
+    layer.forEachTile((tile) => {
+        const rects = subRectsByIdx.get(tile.index);
+        if (!rects)
+            return;
+        // Turn OFF native cell collision so collider events fire only against
+        // the sub-rect bodies (avoids double-collision: cell + sub).
+        tile.setCollision(false, false, false, false, false);
+        const worldLeft = tile.getLeft();
+        const worldTop = tile.getTop();
+        const sx = layer.scaleX;
+        const sy = layer.scaleY;
+        for (const rect of rects) {
+            const cx = worldLeft + (rect.x + rect.w / 2) * sx;
+            const cy = worldTop + (rect.y + rect.h / 2) * sy;
+            const w = rect.w * sx;
+            const h = rect.h * sy;
+            const bodyGO = scene.add.rectangle(cx, cy, w, h);
+            bodyGO.setVisible(false);
+            scene.physics.add.existing(bodyGO, true /* static body */);
+            group.add(bodyGO);
+        }
+    });
+}
+/**
+ * Wire collision between `target` (a sprite, group, or anything with a
+ * physics body) and all collision surfaces of a tilemap entity — both
+ * the layer's native cell-rect collision AND any sub-tile static bodies
+ * authored via the Tile Metadata Editor's collision-shape mode.
+ *
+ * The one-call alternative to:
+ * ```ts
+ * scene.physics.add.collider(player, layer);
+ * scene.physics.add.collider(player, layer.getData('unboxySubTileStaticGroup'));
+ * ```
+ *
+ * Behavior code in a typical game:
+ * ```ts
+ * import { addTilemapCollider } from '@umicat/phaser-sdk';
+ * create() {
+ *   // ... spawn player ...
+ *   addTilemapCollider(this, 'world', this.player);
+ * }
+ * ```
+ *
+ * Returns the created Collider instances so callers can `.destroy()` them
+ * if needed (e.g. on level transition).
+ */
+export function addTilemapCollider(scene, entityId, target, callback) {
+    const out = [];
+    if (!scene.physics?.add)
+        return out;
+    const registry = getEntityRegistry(scene);
+    if (!registry)
+        return out;
+    const go = registry.byId(entityId);
+    if (!go)
+        return out;
+    if (go.getData('entityKind') !== 'tilemap')
+        return out;
+    const container = go;
+    const layers = container.getData('tilemapLayers') ?? [];
+    for (const layer of layers) {
+        out.push(scene.physics.add.collider(target, layer, callback));
+        const group = layer.getData(SUB_TILE_GROUP_KEY);
+        if (group) {
+            out.push(scene.physics.add.collider(target, group, callback));
+        }
+    }
+    return out;
+}
+function resolveTilesetCellSize(asset, fallbackW, fallbackH) {
+    if (asset.tileset?.cellSize)
+        return asset.tileset.cellSize;
+    // Spritesheet assets carry frame dims either nested in spriteSheetConfig
+    // or top-level — both shapes appear in real workspaces (see queueAssetLoad
+    // for the matching tolerance).
+    const cfgW = asset.spriteSheetConfig?.frameWidth ?? asset.frameWidth;
+    const cfgH = asset.spriteSheetConfig?.frameHeight ?? asset.frameHeight;
+    if (typeof cfgW === 'number' && typeof cfgH === 'number') {
+        return { width: cfgW, height: cfgH };
+    }
+    return { width: fallbackW, height: fallbackH };
+}
+/**
+ * Accepts `'#rrggbb'`, `'rrggbb'`, or `'0xrrggbb'` and returns a number
+ * suitable for Phaser's color APIs.
+ */
+export function parseColor(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('#'))
+        return parseInt(trimmed.slice(1), 16);
+    if (trimmed.startsWith('0x'))
+        return parseInt(trimmed.slice(2), 16);
+    return parseInt(trimmed, 16);
+}
+// --- Slice 8: hitbox application -----------------------------------------
+const HITBOX_LISTENER_KEY = 'unboxyHitboxListener';
+/**
+ * Apply the asset's `hitbox` metadata to a sprite's physics body.
+ *
+ * Called automatically at spawn from `createSprite`; ALSO callable by
+ * behavior code that attaches a body later (e.g. the agent's physics skill
+ * does `scene.physics.add.existing(sprite); applyAssetHitbox(sprite, asset);`).
+ *
+ * Semantics:
+ * - **No-op (silent)** when `asset.hitbox` is unset — that's the chat-only
+ *   path (primitives, AI-gen images without vision metadata). Workflow A
+ *   in design doc 09 §4.4 is unaffected.
+ * - **Dev-warn (NOT throw)** when called on a sprite without a physics body.
+ *   The most likely agent mistake is calling this BEFORE
+ *   `scene.physics.add.existing(sprite)`; the warning surfaces in the
+ *   iframe console for the agent's post-turn diagnostic loop.
+ * - **Per-frame variant** installs an `ANIMATION_UPDATE` listener that
+ *   swaps `body.setSize/setOffset` on every frame change during anim
+ *   playback. Listener is idempotent — calling `applyAssetHitbox` twice
+ *   on the same sprite tears down the prior listener before installing a
+ *   new one (handles asset hot-reload + Inspector live-edits).
+ *
+ * Caveat: per-frame swap fires on `Phaser.Animations.Events.ANIMATION_UPDATE`
+ * only, which means manual `sprite.setFrame(idx)` calls outside of animation
+ * playback do NOT swap the body. v1 accepts this — combat sheets are
+ * animation-driven. A `setFrame` wrapper is a v2 candidate.
+ */
+export function applyAssetHitbox(sprite, asset) {
+    if (!asset.hitbox)
+        return;
+    const body = sprite.body;
+    if (!body) {
+        // eslint-disable-next-line no-console
+        console.warn(`[umicat/scene] applyAssetHitbox called on a sprite with no physics ` +
+            `body (asset=${asset.id}). Call scene.physics.add.existing(sprite) ` +
+            `first, or this is a no-op.`);
+        return;
+    }
+    // Tear down any previously installed per-frame listener so re-applying is
+    // idempotent. The listener reference is stashed on the sprite's data
+    // manager because Phaser's emitter needs the exact function reference to
+    // remove it.
+    const prior = sprite.getData(HITBOX_LISTENER_KEY);
+    if (prior) {
+        sprite.off(Phaser.Animations.Events.ANIMATION_UPDATE, prior);
+        sprite.setData(HITBOX_LISTENER_KEY, undefined);
+    }
+    if (isPerFrameHitbox(asset.hitbox)) {
+        // Apply the default shape immediately — covers the current frame plus
+        // every frame not present in the overrides map.
+        applyShape(body, asset.hitbox.default);
+        const overrides = asset.hitbox.frames;
+        const defaultShape = asset.hitbox.default;
+        const listener = (_anim, frame) => {
+            applyShape(body, overrides[frame.index] ?? defaultShape);
+        };
+        sprite.setData(HITBOX_LISTENER_KEY, listener);
+        sprite.on(Phaser.Animations.Events.ANIMATION_UPDATE, listener);
+    }
+    else {
+        applyShape(body, asset.hitbox);
+    }
+}
+/**
+ * Internal helper that maps a HitboxRect to Phaser's body API. v1 handles
+ * `kind: 'rect'` only; v2 will widen the union to `HitboxRect | HitboxCircle`
+ * and branch on `shape.kind` — see design doc 09 §9.2.1.
+ */
+function applyShape(body, shape) {
+    body.setSize(shape.w, shape.h);
+    body.setOffset(shape.x, shape.y);
+}
+/**
+ * Look up the painted tile at a world coordinate inside a tilemap entity.
+ *
+ * Slice 6 Phase C (design doc 06 §5.2). Returns null when:
+ *   - the entity doesn't exist / isn't a tilemap;
+ *   - no layer in the tilemap has a painted (non-empty) tile at that
+ *     world coord;
+ *   - the world coord is outside every layer's bounds.
+ *
+ * Layer scan order (when `options.layerId` is omitted) is top-down — the
+ * layer with the highest `z` is queried first, matching the visual stack.
+ * Pass `options.layerId` to scope to one layer (e.g. for a "ground type"
+ * lookup on the floor layer specifically).
+ *
+ * Behavior-code use:
+ * ```ts
+ * const hit = getTilemapAt(this, 'world', player.x, player.y);
+ * if (hit?.metadata.damage) player.hp -= hit.metadata.damage * dt;
+ * if (hit?.metadata.movement === 'swim') player.speed *= 0.5;
+ * ```
+ *
+ * Per-frame perf: each layer query is a constant-time `worldToTileXY` +
+ * `getTileAt` Phaser call. Safe for `update()` loops at typical layer
+ * counts (1–4 layers per tilemap).
+ */
+export function getTilemapAt(scene, entityId, worldX, worldY, options) {
+    const registry = getEntityRegistry(scene);
+    if (!registry)
+        return null;
+    const go = registry.byId(entityId);
+    if (!go)
+        return null;
+    if (go.getData('entityKind') !== 'tilemap')
+        return null;
+    const container = go;
+    const layers = container.getData('tilemapLayers') ?? [];
+    if (layers.length === 0)
+        return null;
+    // Top-down walk so the visually-front layer wins. Stable sort by the
+    // layer's current depth (set by the per-frame sync hook + initial spawn
+    // → matches container.depth or layer.z). Cheap — typical N=1–4.
+    const candidates = options?.layerId
+        ? layers.filter((l) => l.getData('tilemapLayerId') === options.layerId)
+        : [...layers].sort((a, b) => b.depth - a.depth);
+    for (const layer of candidates) {
+        if (!layer.visible)
+            continue; // hidden layers participate in collision but not lookup; design 06 §5.2
+        const tileXY = layer.worldToTileXY(worldX, worldY, true);
+        if (!tileXY)
+            continue;
+        const tile = layer.getTileAt(tileXY.x, tileXY.y, false);
+        if (!tile || tile.index < 0)
+            continue;
+        const props = tile.properties ?? {};
+        return {
+            layerId: layer.getData('tilemapLayerId') ?? '',
+            tileIndex: tile.index,
+            metadata: { ...props },
+            tileX: tileXY.x,
+            tileY: tileXY.y,
+        };
+    }
+    return null;
+}