From 67e4020dbc80da859416954da466ae61e212e84b Mon Sep 17 00:00:00 2001
From: Brian Fertig <brianfertig@hotmail.com>
Date: Sat, 4 Jul 2026 22:16:02 -0600
Subject: [PATCH] feat: add adventure battle modal and phase wheel UI

Introduce a step-by-step adventure battle modal that replaces the old
fixed-delay fx when heroes walk through a dungeon. The modal shows the
hero queue and dungeon layout, then plays hero-by-hero, room-by-room
with battle animations, a play-by-play log, and Continue-gated progression.

Key changes:
- Adventure battle modal with hero/dungeon rows, battle zone, log panel,
  and Continue button; handles room hits, trap kills, boss wounds, and
  hero deaths with animations
- Split adventure walk events correctly across mid-walk decision pauses
  using pre-mutation dungeon/hero snapshots captured in applyDecision()
- New phase wheel UI (Round Start / Build / Bait / Adventure / Round End)
  with spinning animation and icons, driven by new phase events
- Replace heroToken circles with miniHeroCard portraits at entrance gates,
  with shrink animation from town to gate size during heroWalks
- Support proxy dragging from hover previews and deep-dive modal
- Add renderInto() to Portrait.js for static portrait copies in the modal
---
 src/games/dungeonboss/DungeonBossGame.js  | 1228 ++++++++++++++++++++-
 src/games/dungeonboss/DungeonBossLogic.js |    3 +
 src/ui/Portrait.js                        |   45 +-
 3 files changed, 1227 insertions(+), 49 deletions(-)

diff --git a/src/games/dungeonboss/DungeonBossGame.js b/src/games/dungeonboss/DungeonBossGame.js
index f60b740..c42f53a 100644
--- a/src/games/dungeonboss/DungeonBossGame.js
+++ b/src/games/dungeonboss/DungeonBossGame.js
@@ -43,6 +43,12 @@ const DEPTH = { board: 10, town: 20, hand: 40, fx: 60, ui: 80, overlay: 90, hove
 // Canonical card shapes (w/h) — every rendered instance of a card type keeps
 // this aspect ratio, whatever box a call site hands it (see fitCardBox).
 const CARD_ASPECT = { room: 280 / 390, spell: 260 / 360, hero: 280 / 390, boss: 300 / 430 };
+// Mini hero-card sizes for entrance/gate queues (see miniHeroCard) and the
+// full town-card width heroes shrink from when they walk to a gate (see the
+// 'heroWalks' case in eventFx).
+const TOWN_HERO_W = 106;
+const OPP_ENTRANCE_W = 46, OPP_ENTRANCE_PITCH = 30;
+const HUMAN_ENTRANCE_W = 64, HUMAN_ENTRANCE_PITCH = 38;
 // Width a drawn card grows to while paused, face down then flipped, in the
 // center of the screen mid-draw-animation, before shrinking into the hand.
 const DRAW_FULL_W = { room: 340, spell: 300 };
@@ -50,6 +56,34 @@ const DRAW_FULL_W = { room: 340, spell: 300 };
 // match renderDeckPiles()'s room/spell rows.
 const DECK_PILE_POS = { room: { x: 60, y: 520, w: 46, h: 64 }, spell: { x: 60, y: 600, w: 46, h: 64 } };
 
+// ── adventure battle modal: layout constants ────────────────────────────────
+// Event types the modal owns end-to-end once a walk starts (see
+// splitAdventureWalk). NOT exclusively adventure-walk events elsewhere in the
+// engine (endRound()'s own trap collapse also emits roomDestroyed; spells
+// also emit heroHurt) — membership here is necessary but not sufficient, see
+// splitAdventureWalk's midHero guard.
+const ADV_WALK_TYPES = new Set([
+  'heroEnters', 'heroTeleported', 'heroHurt', 'roomHits', 'heroDies', 'bossWounded', 'roomDestroyed', 'eliminated',
+]);
+const ADV_HERO_ROW = { x0: 40, x1: 860, y: 200, maxW: 120 };
+const ADV_ROOM_ROW = { x0: 900, x1: 1880, y: 200, maxW: 150 };
+const ADV_STAGE_HERO = { x: 380, y: 680 };
+const ADV_STAGE_ROOM = { x: 760, y: 680 };
+// Card widths in the battle stage match the hover-zoom preview size those
+// same card renderers use elsewhere (makeHeroCard/makeRoomCard's own
+// `previewW`) — keep these two pairs in sync if either one ever changes.
+const ADV_STAGE_HERO_W = 314;
+const ADV_STAGE_ROOM_W = 344;
+const ADV_LOG_PANEL = { x0: 1180, y0: 420, w: 700, h: 480, lineH: 50 };
+const ADV_CONTINUE_POS = { x: 1530, y: 990 };
+const ADV_FRAME_MARGIN = 18;
+// Labeled section boxes drawn around the hero row, dungeon+boss row, and
+// battle stage — comfortably outside the content each area actually lays
+// out (see the ADV_HERO_ROW/ADV_ROOM_ROW/ADV_STAGE_* constants above).
+const ADV_HERO_SECTION = { x0: 24, y0: 92, x1: 876, y1: 306 };
+const ADV_ROOM_SECTION = { x0: 892, y0: 92, x1: 1896, y1: 306 };
+const ADV_STAGE_SECTION = { x0: 24, y0: 396, x1: 1140, y1: 1024 };
+
 // Deep-dive card inspector: per-card-type table of gameplay-relevant "zones"
 // to annotate with a box + leader line + tooltip once a hovered card has
 // been centered on screen (see openDeepDive/revealZones/showZoneCallout).
@@ -234,6 +268,9 @@ export default class DungeonBossGame extends Phaser.Scene {
     this._dealing = false;          // true while the initial-deal animation plays
     this.deepDiveTimer = null;      // second "keep hovering" timer, mirrors hoverTimer
     this._deepDive = null;          // { modal, cardHolder, zoneTimers, zoneNodes, returnX, returnY, w, h, deepDiveInfo } while open
+    this._hoverSuppressCont = null; // card container currently mid-drag — its own hover popup stays disabled until dropped
+    this._advBattle = null;         // adventure battle modal session state (see openAdventureModal) while open
+    this._advDungeonSnapshot = null; // per-seat pre-mutation dungeon snapshot, refreshed every applyDecision (see there)
   }
 
   create() {
@@ -284,7 +321,11 @@ export default class DungeonBossGame extends Phaser.Scene {
     this.deckText = this.add.text(20, 360, '', {
       fontFamily: '"Julius Sans One"', fontSize: '16px', color: '#9e9080', lineSpacing: 6,
     }).setDepth(DEPTH.ui);
-    this.promptText = this.add.text(GAME_WIDTH / 2, 830, '', {
+    // y=865 sits below the human dungeon room slots (humanSlotRect bottom
+    // edge ≈836.5, w=196/CARD_ASPECT.room) and above the hand row (room/
+    // spell card top edges ≈897 at hand y=985) — see also addActionButton,
+    // which now sits under the boss card instead of near this text.
+    this.promptText = this.add.text(GAME_WIDTH / 2, 865, '', {
       fontFamily: 'Righteous', fontSize: '24px', color: C.goldHex,
       backgroundColor: '#120e16dd', padding: { x: 16, y: 6 },
     }).setOrigin(0.5).setDepth(DEPTH.ui);
@@ -293,7 +334,145 @@ export default class DungeonBossGame extends Phaser.Scene {
     const panels = this.oppPanelCenters();
     this._oppPortraits = this.opponents.map((opp, i) =>
       createOpponentPortrait(this, opp, panels[i].x - 265, panels[i].y - 88, 36, DEPTH.ui));
-    createPlayerPortrait(this, 180, 870, 40, DEPTH.ui, 'DungeonBossGame');
+    this._playerPortrait = createPlayerPortrait(this, 180, 870, 40, DEPTH.ui, 'DungeonBossGame');
+
+    // Round-phase wheel — above the boss card, in the gap under the opponent
+    // panels (whose bottom edge sits at y=330 for all player counts; the boss
+    // card's top edge is at y=582).
+    this.phaseWheel = this.makePhaseWheel(1740, 456, 76);
+  }
+
+  // A 5-wedge ring (Round Start/Build/Bait/Adventure/Round End) that spins so
+  // the active wedge locks under a fixed top pointer — same mechanic as
+  // Dominion's phase dial (src/games/dominion/DominionGame.js:makePhaseDial),
+  // minus the per-seat active/pulse logic: Dungeon Boss phases apply to the
+  // whole table each round, so the wheel is always fully visible.
+  makePhaseWheel(x, y, outerR) {
+    const scene = this;
+    const PHASE = { roundStart: 0, build: 1, bait: 2, adventure: 3, roundEnd: 4 };
+    const colors = [0xf2ead8, C.gold, 0x8c5a2b, 0x6b8c3a, C.bossEdge];
+    const TWO_PI_5 = (Math.PI * 2) / 5;
+    const HALF = Math.PI / 5;
+    const TOP = -Math.PI / 2;
+
+    const container = this.add.container(x, y).setDepth(DEPTH.ui);
+    const ring = this.add.container(0, 0);
+    container.add(ring);
+
+    const a0 = [], a1 = [], mid = [];
+    for (let i = 0; i < 5; i++) {
+      const c = TOP + i * TWO_PI_5;
+      a0[i] = c - HALF; a1[i] = c + HALF; mid[i] = c;
+    }
+
+    const wedges = [];
+    for (let i = 0; i < 5; i++) {
+      const w = this.add.graphics();
+      ring.add(w);
+      wedges.push(w);
+    }
+    const paintWedges = (activeIdx) => {
+      for (let i = 0; i < 5; i++) {
+        const w = wedges[i];
+        const on = i === activeIdx;
+        w.clear();
+        w.fillStyle(colors[i], on ? 0.95 : 0.26);
+        w.beginPath(); w.moveTo(0, 0); w.arc(0, 0, outerR, a0[i], a1[i], false); w.closePath(); w.fillPath();
+        w.lineStyle(on ? Math.max(2, outerR * 0.05) : 1.5, on ? colors[i] : 0x9e9080, on ? 1 : 0.55);
+        w.beginPath(); w.moveTo(0, 0); w.arc(0, 0, outerR, a0[i], a1[i], false); w.closePath(); w.strokePath();
+      }
+    };
+
+    const ic = outerR * 0.2;
+    const midR = outerR * 0.66;
+    const drawHourglass = (g) => {
+      g.fillStyle(0x2a2118, 1);
+      g.fillTriangle(-ic, -ic, ic, -ic, 0, 0);
+      g.fillTriangle(-ic, ic, ic, ic, 0, 0);
+      g.lineStyle(Math.max(1, 0.16 * ic), 0xf2ead8, 1);
+      g.strokeTriangle(-ic, -ic, ic, -ic, 0, 0);
+      g.strokeTriangle(-ic, ic, ic, ic, 0, 0);
+    };
+    const drawHammer = (g) => {
+      g.fillStyle(0x2a2118, 1);
+      g.fillRect(-0.16 * ic, -0.2 * ic, 0.32 * ic, 1.2 * ic);
+      g.fillStyle(0x2a2118, 1);
+      g.fillRoundedRect(-ic, -1.15 * ic, 2 * ic, 0.7 * ic, 2);
+    };
+    const drawFootprint = (g) => {
+      g.fillStyle(0x2a2118, 1);
+      g.fillEllipse(0, 0.25 * ic, 0.7 * ic, 1 * ic);
+      g.fillCircle(-0.35 * ic, -0.75 * ic, 0.18 * ic);
+      g.fillCircle(0, -0.85 * ic, 0.2 * ic);
+      g.fillCircle(0.4 * ic, -0.75 * ic, 0.18 * ic);
+    };
+    const drawBoot = (g) => {
+      g.fillStyle(0x2a2118, 1);
+      g.fillRoundedRect(-0.5 * ic, -1.1 * ic, ic, 1.3 * ic, 3);
+      g.fillTriangle(-0.5 * ic, 0.2 * ic, 0.9 * ic, 0.2 * ic, 0.9 * ic, 0.7 * ic);
+      g.fillRect(-0.5 * ic, 0.2 * ic, 1.4 * ic, 0.5 * ic);
+    };
+    const drawMoon = (g) => {
+      g.fillStyle(0xf2ead8, 1);
+      g.fillCircle(0, 0, ic);
+      g.fillStyle(0x8c1f28, 1);
+      g.fillCircle(0.45 * ic, -0.15 * ic, 0.85 * ic);
+    };
+    const drawers = [drawHourglass, drawHammer, drawFootprint, drawBoot, drawMoon];
+    const icons = [];
+    for (let i = 0; i < 5; i++) {
+      const g = this.add.graphics();
+      drawers[i](g);
+      g.setPosition(Math.cos(mid[i]) * midR, Math.sin(mid[i]) * midR);
+      ring.add(g);
+      icons.push(g);
+    }
+
+    const hub = this.add.graphics();
+    hub.fillStyle(0x141008, 0.88); hub.fillCircle(0, 0, outerR * 0.4);
+    hub.lineStyle(Math.max(1.5, outerR * 0.03), 0x9e9080, 0.7); hub.strokeCircle(0, 0, outerR * 0.4);
+    container.add(hub);
+
+    const pointer = this.add.graphics();
+    const pw = outerR * 0.16, ph = outerR * 0.3, ty = -outerR;
+    pointer.fillStyle(C.gold, 1);
+    pointer.fillTriangle(-pw, ty - ph, pw, ty - ph, 0, ty + ph * 0.5);
+    pointer.lineStyle(1.5, 0x2a2118, 0.6);
+    pointer.strokeTriangle(-pw, ty - ph, pw, ty - ph, 0, ty + ph * 0.5);
+    container.add(pointer);
+
+    const names = ['Round Start', 'Build', 'Bait', 'Adventure', 'Round End'];
+    const nameHex = ['#f2ead8', C.goldHex, '#c98a52', '#9fce6a', '#e0656e'];
+    const labelSize = Math.max(12, Math.round(outerR * 0.3));
+    const label = this.add.text(0, -(outerR + labelSize), '', {
+      fontFamily: 'Righteous', fontSize: `${labelSize}px`, color: nameHex[0],
+    }).setOrigin(0.5);
+    label.setShadow(0, 2, '#000000', 4, false, true);
+    container.add(label);
+    const applyLabel = (idx) => { label.setText(names[idx]); label.setColor(nameHex[idx]); };
+
+    let phaseIdx = 0;
+    let rotTween = null;
+    paintWedges(phaseIdx);
+    applyLabel(phaseIdx);
+
+    return {
+      container,
+      setPhase(name) {
+        const idx = PHASE[name] ?? 0;
+        if (idx === phaseIdx) return;
+        phaseIdx = idx;
+        paintWedges(idx);
+        applyLabel(idx);
+        rotTween?.remove();
+        rotTween = scene.tweens.add({
+          targets: ring, rotation: -idx * TWO_PI_5, duration: 500, ease: 'Cubic.Out',
+          onUpdate: () => { icons.forEach((g) => { g.rotation = -ring.rotation; }); },
+          onComplete: () => { icons.forEach((g) => { g.rotation = -ring.rotation; }); },
+        });
+      },
+      destroy() { rotTween?.remove(); container.destroy(true); },
+    };
   }
 
   oppPanelCenters() {
@@ -597,9 +776,12 @@ export default class DungeonBossGame extends Phaser.Scene {
     // hp heart + soul value
     const hy = h / 2 - 16;
     this.drawHeartIcon(cont, -w / 2 + 21, hy + 1, 24);
-    cont.add(this.add.text(-w / 2 + 21, hy + 1, `${hero.hp}`, {
+    // Stashed on the container so the adventure battle modal can drive a
+    // live numeric tween on it during an HP-drain animation.
+    cont.hpText = this.add.text(-w / 2 + 21, hy + 1, `${hero.hp}`, {
       fontFamily: 'Righteous', fontSize: '13px', color: '#fff',
-    }).setOrigin(0.5));
+    }).setOrigin(0.5);
+    cont.add(cont.hpText);
     const souls = heroSouls(def);
     this.drawSoulIcon(cont, w / 2 - 18, hy + 2, 9);
     cont.add(this.add.text(w / 2 - 18, hy + 2, `${souls}`, {
@@ -831,16 +1013,20 @@ export default class DungeonBossGame extends Phaser.Scene {
           if (this.busy) return;
           if (!moved) {
             // Actual dragging just began — drop the hover-zoom preview (or
-            // its pending timer) so it doesn't sit over the drop zone.
+            // its pending timer) so it doesn't sit over the drop zone, and
+            // keep it from reopening on this card while it's under the
+            // pointer for the rest of the drag (see attachHover).
             if (this.hoverTimer) { this.hoverTimer.remove(); this.hoverTimer = null; }
             if (this.deepDiveTimer) { this.deepDiveTimer.remove(); this.deepDiveTimer = null; }
             this.hideHover();
+            this._hoverSuppressCont = cont;
           }
           moved = true;
           cont.x = dragX; cont.y = dragY;
         });
         cont.on('dragend', () => {
           if (this.busy) return;
+          if (this._hoverSuppressCont === cont) this._hoverSuppressCont = null;
           if (!moved) { opts.onClick && opts.onClick(); return; }
           if (opts.onDrop) opts.onDrop(cont.x, cont.y);
         });
@@ -852,7 +1038,7 @@ export default class DungeonBossGame extends Phaser.Scene {
         }
         cont.on('pointerdown', () => { if (!this.busy) opts.onClick(); });
       }
-      if (wantHoverPreview) this.attachHover(cont, opts._hoverBuild, opts._deepDiveInfo);
+      if (wantHoverPreview) this.attachHover(cont, opts._hoverBuild, opts._deepDiveInfo, opts);
     }
     (opts.parent || this.boardLayer).add(cont);
   }
@@ -860,16 +1046,30 @@ export default class DungeonBossGame extends Phaser.Scene {
   // ── Hover-to-zoom card preview ───────────────────────────────────────────────
   buildHoverPopup() {
     this.hoverPopup = this.add.container(-9999, -9999).setDepth(DEPTH.hover).setVisible(false);
+    this._hoverDragCtx = null; // { cont, opts } of the real card, set only while it's draggable
+    // A draggable source card's popup can be grabbed directly — pressing and
+    // holding it hands off into the same manual drag path a native card drag
+    // uses (see beginProxyDrag).
+    this.hoverPopup.on('pointerdown', () => {
+      if (this.busy || !this._hoverDragCtx) return;
+      this.beginProxyDrag(this._hoverDragCtx);
+    });
   }
 
-  attachHover(hitObj, buildFn, deepDiveInfo) {
+  attachHover(hitObj, buildFn, deepDiveInfo, opts) {
     hitObj.on('pointerover', () => {
+      // A card being dragged (natively, or handed off from its own popup/
+      // deep-dive) gets repositioned under the pointer, which otherwise
+      // reads as a fresh "pointer entered this object" and would reopen the
+      // popup mid-drag — suppressed until it's dropped (see beginProxyDrag
+      // and finishCard's draggable branch).
+      if (this._hoverSuppressCont === hitObj) return;
       if (this.hoverTimer) this.hoverTimer.remove();
       if (this.deepDiveTimer) { this.deepDiveTimer.remove(); this.deepDiveTimer = null; }
       this.hoverTimer = this.time.delayedCall(500, () => {
-        this.showHover(buildFn);
+        this.showHover(buildFn, hitObj, opts);
         if (deepDiveInfo && DEEPDIVE_ZONES[deepDiveInfo.kind]) {
-          this.deepDiveTimer = this.time.delayedCall(1000, () => this.openDeepDive(deepDiveInfo));
+          this.deepDiveTimer = this.time.delayedCall(1000, () => this.openDeepDive(deepDiveInfo, hitObj, opts));
         }
       });
     });
@@ -880,7 +1080,7 @@ export default class DungeonBossGame extends Phaser.Scene {
     });
   }
 
-  showHover(buildFn) {
+  showHover(buildFn, sourceCont, opts) {
     this.hoverPopup.removeAll(true);
     const { w, h } = buildFn(this.hoverPopup);
     const shadow = this.add.graphics();
@@ -891,6 +1091,22 @@ export default class DungeonBossGame extends Phaser.Scene {
     this.hoverPopup.setData('h', h);
     this.hoverVisible = true;
     this.hoverPopup.setVisible(true);
+    // If the card being previewed is a draggable source card, the popup
+    // itself becomes grabbable — refresh its hit area to match this card's
+    // size (it's a reused container, so a stale hit area from a previous,
+    // differently-sized card would otherwise linger). Ordinary previews stay
+    // non-interactive, same as before, so clicks still pass through to
+    // whatever's underneath rather than being swallowed for no reason.
+    this._hoverDragCtx = (opts && opts.draggable) ? { cont: sourceCont, opts } : null;
+    if (this._hoverDragCtx) {
+      this.hoverPopup.setInteractive({
+        hitArea: new Phaser.Geom.Rectangle(-w / 2, -h / 2, w, h),
+        hitAreaCallback: Phaser.Geom.Rectangle.Contains,
+        useHandCursor: true,
+      });
+    } else if (this.hoverPopup.input) {
+      this.hoverPopup.disableInteractive();
+    }
     // Opponent portraits use a real DOM <video>, which always renders above
     // canvas content no matter its Phaser depth — hide/pause them so they
     // can't sit on top of the popup.
@@ -909,10 +1125,45 @@ export default class DungeonBossGame extends Phaser.Scene {
 
   hideHover() {
     this.hoverVisible = false;
+    this._hoverDragCtx = null;
     this.hoverPopup.setVisible(false).setPosition(-9999, -9999);
     this._oppPortraits?.forEach((p) => p.setVideoVisible(true));
   }
 
+  // Manually drives a drag for the REAL card (`ctx.cont`) starting from a
+  // pointerdown that landed on a stand-in (the hover popup or the deep-dive
+  // zone) instead of the card itself — Phaser's native drag plugin only
+  // tracks objects pressed directly, so this reimplements the same
+  // press-hold-move-release lifecycle finishCard's draggable branch uses,
+  // by hand, via scene-level pointer events.
+  beginProxyDrag(ctx) {
+    const { cont, opts } = ctx;
+    let moved = false;
+    let active = true;
+    const onMove = (p) => {
+      if (!active || !cont.scene) return;
+      if (!moved) {
+        moved = true;
+        // Hand off from whichever stand-in is showing to the real card.
+        this.hideHover();
+        this.forceCloseDeepDive();
+        this._hoverSuppressCont = cont;
+        if (opts.onDragStart) opts.onDragStart();
+        (opts.parent || this.boardLayer).bringToTop(cont);
+      }
+      cont.x = p.x; cont.y = p.y;
+    };
+    const onUp = () => {
+      active = false;
+      this.input.off('pointermove', onMove);
+      this.input.off('pointerup', onUp);
+      if (this._hoverSuppressCont === cont) this._hoverSuppressCont = null;
+      if (moved && cont.scene && opts.onDrop) opts.onDrop(cont.x, cont.y);
+    };
+    this.input.on('pointermove', onMove);
+    this.input.on('pointerup', onUp);
+  }
+
   // ── layout helpers ──────────────────────────────────────────────────────────
   humanSlotRect(idx) {
     // Boss at the right; slot 0 sits beside it, entrance grows leftward.
@@ -1033,12 +1284,16 @@ export default class DungeonBossGame extends Phaser.Scene {
       }
       // pending secret build
       if (p.pendingBuild) this.makeCardBack(x + 128 - p.dungeon.length * pitch, y + 62, mw * 0.8, mh * 0.9, this.boardLayer);
-      // entrance heroes
+      // entrance heroes — mini cards, fanned with a slight overlap
       p.entrance.forEach((hero, hi) => {
-        const hx = x - pw / 2 + 26 + hi * 20;
-        const t = this.heroToken(hero, hx, y + 62);
-        this.boardLayer.add(t);
-        this._heroTokens.set(hero.uid, { x: hx, y: y + 62 });
+        const hx = x - pw / 2 + 30 + hi * OPP_ENTRANCE_PITCH;
+        const hy = y + 62;
+        this.miniHeroCard(hx, hy, hero, OPP_ENTRANCE_W, {
+          parent: this.boardLayer, hover: false,
+          highlight: this.isHeroTarget(hero.uid),
+          onClick: () => this.onHeroClicked(hero.uid),
+        });
+        this._heroTokens.set(hero.uid, { x: hx, y: hy });
       });
     }
   }
@@ -1053,7 +1308,7 @@ export default class DungeonBossGame extends Phaser.Scene {
     gs.town.forEach((hero, i) => {
       const { x, y } = this.townPos(i, n);
       this._heroTokens.set(hero.uid, { x, y });
-      this.makeHeroCard(x, y, hero, 106, 148, {
+      this.makeHeroCard(x, y, hero, TOWN_HERO_W, TOWN_HERO_W / CARD_ASPECT.hero, {
         parent: this.townLayer,
         highlight: this.isHeroTarget(hero.uid),
         onClick: () => this.onHeroClicked(hero.uid),
@@ -1137,9 +1392,12 @@ export default class DungeonBossGame extends Phaser.Scene {
     // queued heroes at entrance
     const entR = this.humanSlotRect(Math.max(p.dungeon.length, 1) - 0.35);
     p.entrance.forEach((hero, hi) => {
-      const hx = entR.x - 130 - hi * 24;
-      const t = this.heroToken(hero, hx, 640);
-      this.boardLayer.add(t);
+      const hx = entR.x - 130 - hi * HUMAN_ENTRANCE_PITCH;
+      this.miniHeroCard(hx, 640, hero, HUMAN_ENTRANCE_W, {
+        parent: this.boardLayer, hover: false,
+        highlight: this.isHeroTarget(hero.uid),
+        onClick: () => this.onHeroClicked(hero.uid),
+      });
       this._heroTokens.set(hero.uid, { x: hx, y: 640 });
     });
     // pending build indicator
@@ -1149,24 +1407,47 @@ export default class DungeonBossGame extends Phaser.Scene {
     }
   }
 
-  heroToken(hero, x, y) {
+  // Small "hero at the gate" card: just the portrait framed in the hero's
+  // class colour (gold if epic) with HP as a number underneath — used for
+  // every entrance/gate hero queue. Replaces the old plain numbered circle
+  // so a glance at a gate still shows which hero it is. Still gets the
+  // standard hover-to-zoom preview (see attachHover) unless suppressed.
+  miniHeroCard(x, y, hero, w, opts = {}) {
+    const h = w / CARD_ASPECT.hero;
     const def = heroDef(hero);
     const info = CLASS_INFO[def.cls] || { color: 0x888888 };
     const cont = this.add.container(x, y);
     const g = this.add.graphics();
-    g.fillStyle(0x10141c, 1); g.fillCircle(0, 0, 17);
-    g.lineStyle(def.epic ? 3 : 2, def.epic ? C.gold : info.color, 1); g.strokeCircle(0, 0, 17);
+    g.fillStyle(C.cardBg, 1); g.fillRoundedRect(-w / 2, -h / 2, w, h, 4);
+    g.lineStyle(def.epic ? 3 : 2, def.epic ? C.gold : info.color, 1);
+    g.strokeRoundedRect(-w / 2, -h / 2, w, h, 4);
     cont.add(g);
-    cont.add(this.add.text(0, -1, `${hero.hp}`, { fontFamily: 'Righteous', fontSize: '15px', color: '#f2ead8' }).setOrigin(0.5));
-    cont.setSize(36, 36);
-    cont.setInteractive({ useHandCursor: true });
-    cont.on('pointerdown', () => { if (!this.busy) this.onHeroClicked(hero.uid); });
-    if (this.isHeroTarget(hero.uid)) {
-      const hl = this.add.graphics();
-      hl.lineStyle(3, C.gold, 1); hl.strokeCircle(0, 0, 22);
-      cont.add(hl);
-      this.tweens.add({ targets: hl, alpha: 0.3, duration: 420, yoyo: true, repeat: -1 });
+    const art = this.artFor('hero', hero.id);
+    if (art) {
+      const img = this.add.image(0, -2, art.key, art.frame);
+      img.setScale(Math.min((w - 6) / Math.max(img.width, 1), (h - 6) / Math.max(img.height, 1)));
+      cont.add(img);
+    } else {
+      const glyph = def.fool ? '🃏' : def.cls === 'fighter' ? '🛡' : def.cls === 'mage' ? '🔮' : def.cls === 'thief' ? '🗝' : '📿';
+      cont.add(this.add.text(0, -2, glyph, { fontSize: `${Math.round(h * 0.5)}px` }).setOrigin(0.5).setAlpha(0.85));
     }
+    const by = h / 2 + 12;
+    const bb = this.add.graphics();
+    bb.fillStyle(0x10141c, 1); bb.fillCircle(0, by, 11);
+    bb.lineStyle(1.5, def.epic ? C.gold : info.color, 1); bb.strokeCircle(0, by, 11);
+    cont.add(bb);
+    cont.add(this.add.text(0, by, `${hero.hp}`, {
+      fontFamily: 'Righteous', fontSize: '13px', color: '#f2ead8',
+    }).setOrigin(0.5));
+    if (!opts.noHoverPreview) {
+      const previewW = 314;
+      opts._deepDiveInfo = { kind: 'hero', hero, previewW };
+      opts._hoverBuild = (parent) => {
+        this.makeHeroCard(0, 0, hero, previewW, previewW / CARD_ASPECT.hero, { isHoverPreview: true, parent });
+        return { w: previewW, h: previewW / CARD_ASPECT.hero };
+      };
+    }
+    this.finishCard(cont, w, h + 26, opts);
     return cont;
   }
 
@@ -1413,6 +1694,24 @@ export default class DungeonBossGame extends Phaser.Scene {
   }
 
   applyDecision(d, choice) {
+    // Snapshot every seat's dungeon BEFORE the mutator runs. The adventure
+    // battle modal needs to know what a seat's dungeon looked like at the
+    // start of a walk, but by the time playEvents() sees the resulting
+    // events, the mutator (and any AI/engine cascade it triggers) has
+    // already run to completion — a trap kill may have already spliced a
+    // room out of gs.players[seat].dungeon, shifting every later index.
+    // Reading live state at that point would silently show the wrong (or a
+    // missing) room. This is cheap (≤MAX_ROOMS rooms × player count).
+    this._advDungeonSnapshot = this.gs.players.map((p) => p.dungeon.map((s) => ({
+      room: { id: s.room.id, uid: s.room.uid }, deactivated: s.deactivated, armed: s.armed,
+    })));
+    // Same problem, different spot: runBait() removes every baited hero from
+    // gs.town before emitting heroWalks, all within this SAME mutator call —
+    // so by the time playEvents()'s own renderAll() runs and heroWalks' fx
+    // reads this._heroTokens for a "from" (town) position, that hero is
+    // already gone from gs.town and renderTown() never gave it an entry.
+    // Snapshot the current (pre-mutation, still-accurate) town positions now.
+    this._preBaitHeroTokens = new Map(this._heroTokens);
     try {
       switch (d.kind) {
         case 'setupDiscard': actSetupDiscard(this.gs, d.seat, choice); break;
@@ -1485,7 +1784,7 @@ export default class DungeonBossGame extends Phaser.Scene {
         this.mode = { type: 'target', decision: d, candidates: d.candidates };
         this.setPrompt(this.targetPrompt(d));
         if (d.optional) this.addActionButton('Skip', () => this.applyDecision(d, null));
-        if (this.needsModalTargets(d)) this.showTargetModal(d);
+        if (this.needsModalTargets(d)) this.showPickModal(d.candidates, (ref) => this.applyDecision(d, ref));
         break;
       }
       case 'roomDraw': {
@@ -1718,17 +2017,24 @@ export default class DungeonBossGame extends Phaser.Scene {
       const pick = () => { this.closeModal(); onPick(ref); };
       const card = this.renderCandidate(ref, x, y, cw, ch, root, pick);
       if (!card) {
+        // Button self-registers on the scene root rather than becoming a
+        // child of `root` (see openDeepDive's identical root.add(closeBtn)
+        // for the established fix) — reparent it so closeModal()'s
+        // root.destroy() actually removes it instead of leaving a stray,
+        // still-clickable button behind once a pick is made.
         const b = new Button(this, x, y, this.candidateLabel(ref), pick, { width: cw, fontSize: 16 });
         b.setDepth(DEPTH.overlay + 1);
+        root.add(b);
       }
     });
     const cancel = this.mode.decision?.optional;
-    new Button(this, GAME_WIDTH / 2, GAME_HEIGHT / 2 + (rows / 2) * (ch + 16) + 60,
+    const cancelBtn = new Button(this, GAME_WIDTH / 2, GAME_HEIGHT / 2 + (rows / 2) * (ch + 16) + 60,
       cancel ? 'Skip' : 'Cancel', () => {
         this.closeModal();
         if (cancel) this.applyDecision(this.mode.decision, null);
         else this.enterHumanMode(this.mode.decision);
       }, { width: 150, fontSize: 18, variant: 'ghost' }).setDepth(DEPTH.overlay + 1);
+    root.add(cancelBtn);
   }
 
   renderCandidate(ref, x, y, cw, ch, root, onPick) {
@@ -1797,8 +2103,14 @@ export default class DungeonBossGame extends Phaser.Scene {
     });
     buttons.push({ label: 'Let it resolve', resp: null });
     buttons.forEach((b, i) => {
-      new Button(this, cx, cy + 4 + i * 54, b.label, () => { this.closeModal(); this.applyDecision(d, b.resp); },
+      // Button self-registers on the scene root rather than becoming a
+      // child of `root` (see openDeepDive's root.add(closeBtn) for the
+      // established fix) — reparent it so closeModal()'s root.destroy()
+      // actually removes it instead of leaving a stray, still-clickable
+      // button behind once a choice is made.
+      const btn = new Button(this, cx, cy + 4 + i * 54, b.label, () => { this.closeModal(); this.applyDecision(d, b.resp); },
         { width: 380, fontSize: 19, variant: b.resp ? undefined : 'ghost' }).setDepth(DEPTH.overlay + 1);
+      root.add(btn);
     });
   }
 
@@ -1825,7 +2137,7 @@ export default class DungeonBossGame extends Phaser.Scene {
   // Deliberately doesn't reuse modalRoot()/this._modal/closeModal() — this
   // modal needs a bespoke close *animation* and must never close on an
   // incidental click, only via the Close button.
-  openDeepDive(deepDiveInfo) {
+  openDeepDive(deepDiveInfo, hitObj, opts) {
     if (this._modal || this._deepDive || this.busy) return;
     const returnX = this.hoverPopup.x, returnY = this.hoverPopup.y;
     this.hideHover();
@@ -1853,10 +2165,16 @@ export default class DungeonBossGame extends Phaser.Scene {
     } else if (kind === 'hero') {
       this.makeHeroCard(0, 0, hero, previewW, previewH, { isHoverPreview: true, parent: cardHolder });
     }
-    // Sits on top of the card (added after it), same size, no handler of its
-    // own — just there to win topOnly hit-testing over `dim` so clicks that
-    // land on the card don't close the modal.
-    cardHolder.add(this.add.zone(0, 0, previewW, previewH).setInteractive());
+    // Sits on top of the card (added after it), same size — wins topOnly
+    // hit-testing over `dim` so clicks on the card don't close the modal.
+    // If the card being viewed is a draggable source card, pressing and
+    // holding it here hands off into the same manual drag path the hover
+    // popup uses (see beginProxyDrag): the modal closes immediately and the
+    // real card appears under the pointer.
+    const dragCtx = opts && opts.draggable ? { cont: hitObj, opts } : null;
+    const zone = this.add.zone(0, 0, previewW, previewH).setInteractive({ useHandCursor: !!dragCtx });
+    if (dragCtx) zone.on('pointerdown', () => this.beginProxyDrag(dragCtx));
+    cardHolder.add(zone);
 
     const closeBtn = new Button(this, GAME_WIDTH / 2, GAME_HEIGHT / 2 + previewH / 2 + 70, 'Close',
       () => this.closeDeepDive(), { width: 160, fontSize: 20 });
@@ -1951,13 +2269,792 @@ export default class DungeonBossGame extends Phaser.Scene {
     });
   }
 
+  // Instant teardown (no fly-back animation) — used when a drag is handed
+  // off out of the deep-dive card, since the player is already mid-gesture
+  // and shouldn't have to wait on a competing tween.
+  forceCloseDeepDive() {
+    if (!this._deepDive) return;
+    const { modal, cardHolder, zoneTimers } = this._deepDive;
+    zoneTimers.forEach((t) => t.remove());
+    this.tweens.killTweensOf(cardHolder);
+    modal.destroy();
+    this._deepDive = null;
+  }
+
+  // ── adventure battle modal ───────────────────────────────────────────────────
+  // A full-screen, step-by-step replacement for the old fixed-delay adventure
+  // fx: when a seat's queued heroes start walking, this pops a modal (self-
+  // contained state on this._advBattle, modeled on _deepDive rather than the
+  // generic modalRoot()/_modal — it must survive many Continue clicks and a
+  // possible mid-session hide/show without the "any click closes it" default)
+  // showing that seat's whole hero queue up top-left and its dungeon (rooms
+  // -> boss) up top-right, then steps hero-by-hero, room-by-room through the
+  // walk: each room's card + the active hero's card animate down to a battle
+  // stage, the hit resolves with an animation + a play-by-play log line, and
+  // a Continue button (shown only once the animation finishes) advances.
+  //
+  // CRITICAL CORRECTNESS NOTE: by the time playEvents() sees these events,
+  // the engine has already fully mutated gs to completion (or the next
+  // decision-pause) — gs is never an in-progress snapshot. So this code never
+  // reads the live hero queue (p.entrance — already drained) or the live room
+  // list (p.dungeon — may have had a room spliced out by a trap kill, shifting
+  // every later index) to build its initial layout. Instead: the hero roster
+  // comes purely from heroEnters events (each carries {seat,uid,id}; starting
+  // HP is always heroDef(id).hp since only stepAdventure ever mutates hp, and
+  // only after heroEnters fires), and the room track comes from
+  // this._advDungeonSnapshot[seat], captured pre-mutation in applyDecision().
+  // A parallel `liveOrder` array (stable "display key" per snapshotted room,
+  // in current live order) plus a self-tracked `currentLiveIdx` pointer
+  // (mirroring the engine's own w.roomIdx countdown) resolve every
+  // roomHits/roomDestroyed/ramp-heroHurt event to the correct card even after
+  // an earlier trap kill this same session shifted every subsequent index —
+  // and surface rooms the engine's event stream is silent about entirely
+  // (0-net-damage or deactivated rooms never emit anything) as a quick 'pass'
+  // beat, so the hero never appears to silently teleport past one.
+
+  // Splits `events` into `{ before, walk, rest }`: `before` is whatever
+  // precedes the walk (e.g. the windowPass event(s) that close the pre-
+  // adventure advStart window — confirmed via a direct engine trace that the
+  // seat closing that window's own windowPass shares the SAME event batch as
+  // the heroEnters it unblocks, so the walk is NOT reliably the first event
+  // in the array), `walk` is the contiguous adventure-walk run this modal
+  // owns end-to-end, and `rest` is whatever follows (typically the next
+  // seat's adventureStart, or the round/game tail). Pure scan, no side
+  // effects. roomDestroyed/heroHurt/eliminated are NOT exclusively
+  // adventure-walk events elsewhere (endRound()'s own trap collapse also
+  // emits roomDestroyed; spells also emit heroHurt) — the midHero guard
+  // (true strictly between a heroEnters and that hero's terminal event) is
+  // what keeps this correct once inside the walk.
+  splitAdventureWalk(events) {
+    const before = [];
+    const walk = [];
+    let seat = this._advBattle ? this._advBattle.seat : null;
+    let inWalk = false;
+    let midHero = false;
+    let i = 0;
+    for (; i < events.length; i++) {
+      const e = events[i];
+      if (!inWalk) {
+        if (e.type === 'heroEnters' && (seat == null || e.seat === seat)) {
+          seat = e.seat;
+          inWalk = true;
+          walk.push(e); midHero = true;
+        } else {
+          before.push(e);
+        }
+        continue;
+      }
+      if (e.type === 'heroEnters') {
+        if (e.seat !== seat) break;
+        walk.push(e); midHero = true; continue;
+      }
+      if (e.seat !== seat || !ADV_WALK_TYPES.has(e.type)) break;
+      if (!midHero && e.type !== 'bossWounded' && e.type !== 'eliminated') break;
+      walk.push(e);
+      if (e.type === 'heroDies' || e.type === 'bossWounded') midHero = false;
+    }
+    return { before, walk, rest: events.slice(i) };
+  }
+
+  // Hands a walk sub-run off to the modal, opening it on the first call for
+  // this seat and just re-showing + feeding it more events on later calls
+  // (the only way a session spans more than one call: a mid-walk decision
+  // like an onHeroDieHere room effect needing a real target choice — see
+  // onAdventureQueueDrained). `rest` is whatever follows this seat's walk in
+  // the original batch (typically the next seat's adventureStart, or the
+  // round/game tail) and is handed back to the normal pipeline once this
+  // session closes.
+  runAdventureWalk(events, rest) {
+    // On a brand-new session, let the player see the full hero/dungeon
+    // layout at rest first — the very first battle only starts once they
+    // click Continue, rather than immediately marching into the first room.
+    const freshlyOpened = !this._advBattle;
+    if (freshlyOpened) {
+      this.openAdventureModal(events[0].seat, events);
+    } else {
+      this._advBattle.root.setVisible(true);
+      this._advBattle.attackedPortrait.forEach((o) => o.setVisible?.(true));
+      this.setAdventureVideosVisible(false);
+      this.syncHeroRow(events);
+    }
+    const ab = this._advBattle;
+    ab.events.push(...events);
+    ab.onSessionDrained = () => this.closeAdventureModal(() => { this.busy = false; this.playEvents(rest); });
+    if (freshlyOpened) ab.continueBtn.setVisible(true);
+    else this.advanceAdventureStep();
+  }
+
+  openAdventureModal(seat, firstBatch) {
+    this.setAdventureVideosVisible(false);
+    const root = this.add.container(0, 0).setDepth(DEPTH.overlay);
+    // Dark plum backdrop (matches the game's own scene background, C.bgTop)
+    // rather than plain black, framed by an inset gold border so the modal
+    // reads as its own "window" over the darkened board.
+    const dim = this.add.rectangle(GAME_WIDTH / 2, GAME_HEIGHT / 2, GAME_WIDTH, GAME_HEIGHT, C.bgTop, 0.93).setInteractive();
+    root.add(dim);
+    const frame = this.add.graphics();
+    const m = ADV_FRAME_MARGIN;
+    frame.lineStyle(4, C.gold, 0.9);
+    frame.strokeRoundedRect(m, m, GAME_WIDTH - m * 2, GAME_HEIGHT - m * 2, 14);
+    frame.lineStyle(1.5, C.gold, 0.45);
+    frame.strokeRoundedRect(m + 8, m + 8, GAME_WIDTH - (m + 8) * 2, GAME_HEIGHT - (m + 8) * 2, 10);
+    root.add(frame);
+    this._advBattle = {
+      root, dim, seat,
+      heroCards: new Map(), heroOrder: [], heroMeta: new Map(), heroHp: new Map(),
+      roomCards: new Map(), bossCard: null, liveOrder: [], attackedPortrait: [],
+      stage: null, logLines: [], continueBtn: null,
+      events: [], cursor: 0, currentLiveIdx: null, activeHeroUid: null,
+      lastStep: null, onSessionDrained: null,
+    };
+    this.buildAdventureRoomRow(seat);
+    this.syncHeroRow(firstBatch);
+    const ab = this._advBattle;
+    this.buildAdventureAttackedPortrait(seat);
+    this.drawAdventureSectionFrame(ADV_HERO_SECTION, 'Heroes');
+    this.drawAdventureSectionFrame(ADV_ROOM_SECTION, this.advDungeonLabel(seat));
+    this.drawAdventureSectionFrame(ADV_STAGE_SECTION, 'Battle Zone');
+    ab.stage = this.add.container(0, 0);
+    root.add(ab.stage);
+    // "Prepare for Dungeon Crawl!" — only ever shown here, at the very start
+    // of a fresh session, before the first Continue click. It's a child of
+    // ab.stage, so playAdventureStep's own stage.removeAll(true) (its first
+    // action once the first real step plays) clears it away for free.
+    const prepText = this.add.text(
+      (ADV_STAGE_SECTION.x0 + ADV_STAGE_SECTION.x1) / 2, (ADV_STAGE_SECTION.y0 + ADV_STAGE_SECTION.y1) / 2,
+      'Prepare for Dungeon Crawl!', {
+        fontFamily: 'Righteous', fontSize: '52px', color: '#f5d76e', align: 'center',
+        stroke: '#120e16', strokeThickness: 6,
+        wordWrap: { width: ADV_STAGE_SECTION.x1 - ADV_STAGE_SECTION.x0 - 60 },
+      },
+    ).setOrigin(0.5).setAlpha(0);
+    ab.stage.add(prepText);
+    this.tweens.add({ targets: prepText, alpha: 1, duration: 320, ease: 'Cubic.easeOut' });
+    this.buildLogPanel();
+    ab.continueBtn = new Button(this, ADV_CONTINUE_POS.x, ADV_CONTINUE_POS.y, 'Continue',
+      () => this.onAdventureContinue(), { width: 220, fontSize: 22 }).setDepth(DEPTH.overlay + 1);
+    ab.continueBtn.setVisible(false);
+    root.setAlpha(0);
+    this.tweens.add({ targets: root, alpha: 1, duration: 220 });
+  }
+
+  // Adds any hero from `events` not already in the row (every heroEnters the
+  // first time; only genuinely new ones on a later, resumed batch), sized by
+  // the pitch formula for the CURRENT total queue length — mirrors the
+  // existing townPos pitch pattern. Existing cards are left at their original
+  // slot/size on a later batch rather than reflowed, a deliberate simplification
+  // since that only matters for the rare mid-session-decision resume case.
+  syncHeroRow(events) {
+    const ab = this._advBattle;
+    const newUids = [];
+    for (const e of events) {
+      if (e.type === 'heroEnters' && !ab.heroMeta.has(e.uid)) {
+        const def = heroDef({ id: e.id });
+        ab.heroMeta.set(e.uid, { id: e.id, def });
+        ab.heroHp.set(e.uid, def.hp);
+        ab.heroOrder.push(e.uid);
+        newUids.push(e.uid);
+      }
+    }
+    if (!newUids.length) return;
+    const n = Math.max(1, ab.heroOrder.length);
+    const { x0, x1, y, maxW } = ADV_HERO_ROW;
+    const pitch = Math.min(maxW + 14, (x1 - x0) / n);
+    const w = Math.max(46, Math.min(maxW, pitch - 14));
+    const h = w / CARD_ASPECT.hero;
+    newUids.forEach((uid) => {
+      const i = ab.heroOrder.indexOf(uid);
+      const x = x0 + pitch / 2 + i * pitch;
+      const meta = ab.heroMeta.get(uid);
+      const cont = this.makeHeroCard(x, y, { uid, id: meta.id, hp: meta.def.hp }, w, h,
+        { parent: ab.root, hover: false, noHoverPreview: true });
+      ab.heroCards.set(uid, { cont, x, y, w, h, id: meta.id, def: meta.def });
+    });
+  }
+
+  // Room track, gate -> boss (left -> right): dungeon slot index length-1 is
+  // gate-side (walked first), index 0 is boss-adjacent (see the engine
+  // comment "entrance = dungeon.length-1" on roomDamage). Keyed by a stable
+  // displayKey = the room's ORIGINAL snapshot index, paired with a `liveOrder`
+  // array (displayKeys in current live-index order) that a trap kill splices
+  // from during play, exactly mirroring the engine's own p.dungeon.splice —
+  // this is what keeps later roomHits/heroHurt events resolving to the right
+  // card even after an earlier trap kill shifted every subsequent live index.
+  buildAdventureRoomRow(seat) {
+    const ab = this._advBattle;
+    const snap = (this._advDungeonSnapshot && this._advDungeonSnapshot[seat]) || [];
+    const { x0, x1, y, maxW } = ADV_ROOM_ROW;
+    const n = snap.length + 1; // rooms + boss
+    const pitch = Math.min(maxW + 14, (x1 - x0) / n);
+    const w = Math.max(50, Math.min(maxW, pitch - 14));
+    const h = w / CARD_ASPECT.room;
+    ab.liveOrder = snap.map((_, i) => i);
+    const ordered = snap.map((s, i) => ({ s, displayKey: i })).reverse();
+    ordered.forEach(({ s, displayKey }, pos) => {
+      const x = x0 + pitch / 2 + pos * pitch;
+      const cont = this.makeRoomCard(x, y, s.room, w, h, {
+        parent: ab.root, showText: false, hover: false, noHoverPreview: true,
+      });
+      if (s.armed) this.tagArmedBadge(cont, w, h);
+      ab.roomCards.set(displayKey, { cont, x, y, w, h, defId: s.room.id, destroyed: false });
+    });
+    const bx = x0 + pitch / 2 + snap.length * pitch;
+    const bh = w / CARD_ASPECT.boss;
+    const bossCont = this.makeBossCard(bx, y, this.gs.players[seat].boss.id, w, bh, {
+      parent: ab.root, showText: false, hover: false, noHoverPreview: true,
+    });
+    ab.bossCard = { cont: bossCont, x: bx, y, w, h: bh };
+  }
+
+  // A static profile picture — never the animated <video> the board
+  // portraits use, per request — for whichever seat's dungeon this session
+  // is attacking, sitting just to the right of their boss card. Reuses the
+  // same board-portrait picture (avatar/initial for the human, sprite-sheet
+  // frame for an opponent) via Portrait.js's renderInto(); these are plain
+  // scene-root objects (not children of ab.root), so closeAdventureModal
+  // destroys them explicitly alongside it.
+  buildAdventureAttackedPortrait(seat) {
+    const ab = this._advBattle;
+    const boss = ab.bossCard;
+    if (!boss) { ab.attackedPortrait = []; return; }
+    const portrait = seat === this.humanSeat ? this._playerPortrait : this._oppPortraits?.[seat - 1];
+    const radius = 34;
+    const x = boss.x + boss.w / 2 + radius + 14;
+    const y = boss.y;
+    ab.attackedPortrait = portrait ? portrait.renderInto(x, y, radius, DEPTH.overlay + 1) : [];
+  }
+
+  tagArmedBadge(cont, w, h) {
+    cont.add(this.add.text(w / 2 - 14, -h / 2 + 14, '⚠', { fontSize: '18px', color: '#c9962a' }).setOrigin(0.5));
+  }
+
+  advDungeonLabel(seat) {
+    return seat === this.humanSeat ? 'Your Dungeon' : `${this.seatName(seat)}'s Dungeon`;
+  }
+
+  // A subtle labeled box (gold-on-dark, tab-style title straddling the top
+  // edge) grouping one region of the modal — purely visual organization, no
+  // interactivity.
+  drawAdventureSectionFrame(box, label) {
+    const ab = this._advBattle;
+    const g = this.add.graphics();
+    g.lineStyle(2, C.gold, 0.55);
+    g.strokeRoundedRect(box.x0, box.y0, box.x1 - box.x0, box.y1 - box.y0, 8);
+    ab.root.add(g);
+    ab.root.add(this.add.text(box.x0 + 18, box.y0, label, {
+      fontFamily: 'Righteous', fontSize: '17px', color: C.goldHex,
+      backgroundColor: '#120e16', padding: { x: 10, y: 3 },
+    }).setOrigin(0, 0.5));
+  }
+
+  buildLogPanel() {
+    const ab = this._advBattle;
+    const { x0, y0, w, h } = ADV_LOG_PANEL;
+    const bg = this.add.graphics();
+    bg.fillStyle(C.parchment, 0.96); bg.fillRoundedRect(x0, y0, w, h, 8);
+    bg.lineStyle(2, 0x4a3a5c, 0.6); bg.strokeRoundedRect(x0, y0, w, h, 8);
+    ab.root.add(bg);
+  }
+
+  appendLogLine(text, color = C.ink) {
+    const ab = this._advBattle;
+    const { x0, y0, w, h, lineH } = ADV_LOG_PANEL;
+    const maxLines = Math.floor(h / lineH) - 1;
+    if (ab.logLines.length >= maxLines) ab.logLines.shift().destroy();
+    const t = this.add.text(x0 + 16, 0, text, {
+      fontFamily: '"Julius Sans One"', fontSize: '28px', color, wordWrap: { width: w - 32 },
+    });
+    ab.logLines.push(t);
+    ab.root.add(t);
+    let y = y0 + h - 20;
+    for (let i = ab.logLines.length - 1; i >= 0; i--) {
+      ab.logLines[i].setY(y - ab.logLines[i].height);
+      y -= ab.logLines[i].height + 6;
+    }
+    t.setAlpha(0);
+    this.tweens.add({ targets: t, alpha: 1, duration: 180 });
+  }
+
+  // ── step sequencing ─────────────────────────────────────────────────────────
+  // Pulls raw events from ab.events/ab.cursor and groups them into one
+  // Continue-gated "step." The modal walks its OWN currentLiveIdx pointer
+  // from liveOrder.length-1 down to -1 per hero, mirroring the engine's
+  // w.roomIdx, and matches it against the next unconsumed event — this is
+  // what surfaces a silent 0-damage/deactivated room (no event at all) as a
+  // 'pass' step that a pure event-type scan would miss entirely.
+  nextAdventureStep() {
+    const ab = this._advBattle;
+    let bounceAmount = null;
+    for (;;) {
+      if (ab.cursor >= ab.events.length) return null;
+      const e = ab.events[ab.cursor];
+
+      if (e.type === 'heroEnters') {
+        ab.cursor++;
+        ab.activeHeroUid = e.uid;
+        ab.currentLiveIdx = ab.liveOrder.length - 1;
+        const step = { kind: 'enter', uid: e.uid };
+        if (ab.events[ab.cursor]?.type === 'heroTeleported') {
+          ab.cursor++;
+          step.teleported = true;
+          ab.currentLiveIdx = ab.liveOrder.length - 1;
+        }
+        return step;
+      }
+
+      if (e.type === 'bossWounded') {
+        ab.cursor++;
+        const step = { kind: 'bossWound', uid: e.uid, seat: e.seat, wounds: e.wounds, total: e.total };
+        if (ab.events[ab.cursor]?.type === 'eliminated') { ab.cursor++; step.eliminated = true; }
+        ab.activeHeroUid = null; ab.currentLiveIdx = null;
+        return step;
+      }
+
+      if (ab.currentLiveIdx == null || ab.currentLiveIdx < 0) { ab.cursor++; continue; } // defensive
+
+      const roomIdx = ab.currentLiveIdx;
+      const uid = ab.activeHeroUid;
+
+      // Minotaur's Maze: a one-off re-hit of the room just left, folded as a
+      // narrative prefix onto whatever happens in the current room next.
+      if (e.type === 'roomHits' && e.bounce && e.slotIdx === roomIdx + 1) {
+        ab.cursor++;
+        bounceAmount = e.amount;
+        continue;
+      }
+      if (e.type === 'roomDestroyed' && e.slotIdx === roomIdx) {
+        ab.cursor++;
+        const displayKey = ab.liveOrder.splice(roomIdx, 1)[0];
+        const step = { kind: 'trapKill', uid, displayKey, bounceAmount };
+        if (ab.events[ab.cursor]?.type === 'heroDies') { step.heroDies = ab.events[ab.cursor]; ab.cursor++; }
+        ab.activeHeroUid = null; ab.currentLiveIdx = null;
+        return step;
+      }
+      if (e.type === 'heroHurt') {
+        ab.cursor++;
+        const displayKey = ab.liveOrder[roomIdx];
+        const step = { kind: 'roomHit', uid, displayKey, rampAmount: e.amount, amount: 0, bounceAmount };
+        if (ab.events[ab.cursor]?.type === 'roomHits' && ab.events[ab.cursor].slotIdx === roomIdx) {
+          step.amount = ab.events[ab.cursor].amount; step.bounce = !!ab.events[ab.cursor].bounce; ab.cursor++;
+        }
+        if (ab.events[ab.cursor]?.type === 'heroDies') { step.heroDies = ab.events[ab.cursor]; ab.cursor++; }
+        if (step.heroDies) { ab.activeHeroUid = null; ab.currentLiveIdx = null; } else ab.currentLiveIdx--;
+        return step;
+      }
+      if (e.type === 'roomHits' && e.slotIdx === roomIdx) {
+        ab.cursor++;
+        const displayKey = ab.liveOrder[roomIdx];
+        const step = { kind: 'roomHit', uid, displayKey, amount: e.amount, bounceAmount };
+        if (ab.events[ab.cursor]?.type === 'heroDies') { step.heroDies = ab.events[ab.cursor]; ab.cursor++; }
+        if (step.heroDies) { ab.activeHeroUid = null; ab.currentLiveIdx = null; } else ab.currentLiveIdx--;
+        return step;
+      }
+      // No event matches this room index — a silent 0-dmg or deactivated pass.
+      const displayKey = ab.liveOrder[roomIdx];
+      ab.currentLiveIdx--;
+      return { kind: 'pass', uid, displayKey, bounceAmount };
+    }
+  }
+
+  advanceAdventureStep() {
+    const ab = this._advBattle;
+    ab.continueBtn.setVisible(false);
+    const step = this.nextAdventureStep();
+    if (!step) { this.onAdventureQueueDrained(); return; }
+    ab.lastStep = step;
+    this.playAdventureStep(step, () => {
+      if (step.kind === 'enter' || step.kind === 'pass') { this.advanceAdventureStep(); return; }
+      ab.continueBtn.setVisible(true);
+    });
+  }
+
+  onAdventureContinue() {
+    const ab = this._advBattle;
+    ab.continueBtn.setVisible(false);
+    this.settleAdventureStepIntoTopRows(ab.lastStep, () => this.advanceAdventureStep());
+  }
+
+  // Return-to-top / dim / advance, per the spec: a survived room hit sends
+  // both cards back up then dims the room just passed; a trap kill sends
+  // just the room back up as a destroyed placeholder (the hero already faded
+  // away in playTrapKillStep); bossWound and pass need no further settling
+  // (already fully resolved inline in their own play functions).
+  settleAdventureStepIntoTopRows(step, onDone) {
+    if (!step) { onDone(); return; } // the opening Continue click — nothing has played yet to settle
+    switch (step.kind) {
+      case 'roomHit': {
+        // The hero (if it died here) is already gone from the stage by now
+        // (removeHeroCard ran inside playRoomHitStep) — only the room needs
+        // to travel back, either way.
+        const uid = step.heroDies ? null : step.uid;
+        this.returnHome(uid, step.displayKey, () => { this.dimRoomCard(step.displayKey); onDone(); });
+        break;
+      }
+      case 'trapKill':
+        this.returnHome(null, step.displayKey, () => { this.markRoomDestroyed(step.displayKey); onDone(); });
+        break;
+      default:
+        onDone();
+        break;
+    }
+  }
+
+  // When the step queue empties: if the engine is now waiting on a real
+  // decision for THIS seat (e.g. an onHeroDieHere room effect's target
+  // choice), hide (not destroy) the modal and let the existing decision UI
+  // (showPickModal etc.) run its course via the normal pump()/applyDecision
+  // cycle — the next batch of events resumes this same session (see
+  // runAdventureWalk). Otherwise the seat's whole queue is done.
+  onAdventureQueueDrained() {
+    const ab = this._advBattle;
+    const d = pendingDecision(this.gs);
+    if (d && d.seat === ab.seat && ['target', 'discard', 'roomDraw'].includes(d.kind)) {
+      ab.root.setVisible(false);
+      ab.continueBtn.setVisible(false);
+      ab.attackedPortrait.forEach((o) => o.setVisible?.(false)); // scene-root objects, not children of ab.root
+      this.setAdventureVideosVisible(true); // the decision UI (showPickModal etc.) is a normal board overlay, fine to show these under
+      this.busy = false;
+      this.pump();
+      return;
+    }
+    ab.onSessionDrained();
+  }
+
+  closeAdventureModal(onDone) {
+    const ab = this._advBattle;
+    ab.continueBtn.setVisible(false);
+    this.tweens.add({
+      // ab.continueBtn and ab.attackedPortrait are scene-root objects (see
+      // their own comments), not children of ab.root, so they need to fade
+      // and be destroyed alongside it explicitly rather than for free.
+      targets: [ab.root, ...ab.attackedPortrait], alpha: 0, duration: 240, ease: 'Cubic.easeIn',
+      onComplete: () => {
+        ab.continueBtn.destroy();
+        ab.attackedPortrait.forEach((o) => o.destroy());
+        ab.root.destroy();
+        this._advBattle = null;
+        this.setAdventureVideosVisible(true);
+        this.renderAll();
+        onDone?.();
+      },
+    });
+  }
+
+  // Opponent portraits use a real DOM <video>, which always renders above
+  // canvas content regardless of Phaser depth (see hoverPopup's identical
+  // treatment) — hide/pause them whenever the adventure modal is the topmost
+  // thing on screen so they can't float over it.
+  setAdventureVideosVisible(visible) {
+    this._oppPortraits?.forEach((p) => p.setVideoVisible(visible));
+  }
+
+  // ── shared move helpers ──────────────────────────────────────────────────────
+  moveToStage(uid, displayKey, opts, onDone) {
+    const ab = this._advBattle;
+    const heroRec = uid != null ? ab.heroCards.get(uid) : null;
+    const roomRec = displayKey != null ? ab.roomCards.get(displayKey) : null;
+    const duration = opts.duration || 300;
+    let pending = 0;
+    const done = () => { if (--pending <= 0) onDone(); };
+    if (heroRec) {
+      pending++;
+      // Scale relative to this card's OWN built width (varies with hero-row
+      // pitch/count) so it lands at the exact hover-preview width, not just
+      // a fixed multiplier of whatever size it happened to be built at.
+      const scale = ADV_STAGE_HERO_W / heroRec.w;
+      this.tweens.add({ targets: heroRec.cont, x: ADV_STAGE_HERO.x, y: ADV_STAGE_HERO.y, scale, duration, ease: 'Cubic.easeOut', onComplete: done });
+    }
+    if (roomRec && !roomRec.destroyed) {
+      pending++;
+      const scale = ADV_STAGE_ROOM_W / roomRec.w;
+      this.tweens.add({ targets: roomRec.cont, x: ADV_STAGE_ROOM.x, y: ADV_STAGE_ROOM.y, scale, duration, ease: 'Cubic.easeOut', onComplete: done });
+    }
+    if (!pending) onDone();
+  }
+
+  returnHome(uid, displayKey, onDone) {
+    const ab = this._advBattle;
+    const heroRec = uid != null ? ab.heroCards.get(uid) : null;
+    const roomRec = displayKey != null ? ab.roomCards.get(displayKey) : null;
+    let pending = 0;
+    const done = () => { if (--pending <= 0) onDone(); };
+    if (heroRec) {
+      pending++;
+      this.tweens.add({ targets: heroRec.cont, x: heroRec.x, y: heroRec.y, scale: 1, duration: 260, ease: 'Cubic.easeIn', onComplete: done });
+    }
+    if (roomRec && !roomRec.destroyed) {
+      pending++;
+      this.tweens.add({ targets: roomRec.cont, x: roomRec.x, y: roomRec.y, scale: 1, duration: 260, ease: 'Cubic.easeIn', onComplete: done });
+    }
+    if (!pending) onDone();
+  }
+
+  // Large "-{amount}" overlaid on the hero's card in the stage, rising and
+  // fading over 1.5s — placed in absolute stage coordinates (not as a child
+  // of the hero card's own container) so its size stays fixed/predictable
+  // regardless of how much that container is currently scaled up (which
+  // varies with hero-row crowding, from ~2.6x up to ~6.8x).
+  popHeroDamageNumber(amount) {
+    const ab = this._advBattle;
+    const t = this.add.text(ADV_STAGE_HERO.x, ADV_STAGE_HERO.y, `-${amount}`, {
+      fontFamily: 'Righteous', fontSize: '72px', color: '#ff2222', stroke: '#000000', strokeThickness: 8,
+    }).setOrigin(0.5);
+    ab.stage.add(t);
+    this.tweens.add({ targets: t, y: t.y - 140, alpha: 0, duration: 1500, ease: 'Cubic.easeOut', onComplete: () => t.destroy() });
+  }
+
+  dimRoomCard(displayKey) {
+    const rc = this._advBattle.roomCards.get(displayKey);
+    if (rc && !rc.destroyed) rc.cont.setAlpha(0.35);
+  }
+
+  markRoomDestroyed(displayKey) {
+    const rc = this._advBattle.roomCards.get(displayKey);
+    if (!rc || rc.destroyed) return;
+    rc.destroyed = true;
+    rc.cont.setAlpha(1);
+    rc.cont.removeAll(true);
+    const g = this.add.graphics();
+    g.fillStyle(0x241a2e, 0.9); g.fillRoundedRect(-rc.w / 2, -rc.h / 2, rc.w, rc.h, 6);
+    g.lineStyle(2, 0x6b5a4a, 0.8); g.strokeRoundedRect(-rc.w / 2, -rc.h / 2, rc.w, rc.h, 6);
+    rc.cont.add(g);
+    rc.cont.add(this.add.text(0, 0, '💥', { fontSize: `${Math.round(rc.h * 0.4)}px` }).setOrigin(0.5).setAlpha(0.7));
+  }
+
+  // Soul-rises removal beat for a hero that died this session (trap kill or
+  // cumulative room damage) — echoes the live board's heroDies soul-flight fx.
+  removeHeroCard(uid, onDone) {
+    const ab = this._advBattle;
+    const rec = ab.heroCards.get(uid);
+    if (!rec) { onDone(); return; }
+    const soul = this.add.circle(rec.cont.x, rec.cont.y, 10, 0xf5d76e, 0.9);
+    ab.stage.add(soul);
+    this.tweens.add({ targets: soul, y: soul.y - 90, alpha: 0, duration: 500, ease: 'Cubic.easeOut', onComplete: () => soul.destroy() });
+    this.tweens.add({
+      targets: rec.cont, alpha: 0, scale: 0.7, duration: 380, ease: 'Cubic.easeIn',
+      onComplete: () => {
+        rec.cont.destroy();
+        ab.heroCards.delete(uid);
+        const idx = ab.heroOrder.indexOf(uid);
+        if (idx >= 0) ab.heroOrder.splice(idx, 1);
+        onDone();
+      },
+    });
+  }
+
+  advHeroCurrentHp(uid) { return this._advBattle.heroHp.get(uid) ?? 0; }
+  advSetHeroCurrentHp(uid, v) { this._advBattle.heroHp.set(uid, v); }
+  advHeroName(uid) {
+    const meta = this._advBattle.heroMeta.get(uid);
+    return meta ? meta.def.name : 'The hero';
+  }
+  advRoomName(displayKey) {
+    const rc = this._advBattle.roomCards.get(displayKey);
+    return rc ? (ROOMS[rc.defId]?.name || 'the room') : 'the room';
+  }
+
+  // ── battle-step animations ──────────────────────────────────────────────────
+  playAdventureStep(step, onDone) {
+    const ab = this._advBattle;
+    ab.stage.removeAll(true);
+    const ctx = this.adventureStepCtx(step);
+    this.appendLogLine(this.adventureLogLine(step, ctx), this.adventureLogColor(step));
+    switch (step.kind) {
+      case 'enter': this.playEnterStep(step, onDone); return;
+      case 'pass': this.playPassStep(step, onDone); return;
+      case 'roomHit': this.playRoomHitStep(step, onDone); return;
+      case 'trapKill': this.playTrapKillStep(step, onDone); return;
+      case 'bossWound': this.playBossWoundStep(step, onDone); return;
+      default: onDone(); return;
+    }
+  }
+
+  adventureStepCtx(step) {
+    const ab = this._advBattle;
+    const heroName = step.uid != null ? this.advHeroName(step.uid) : 'The hero';
+    const roomName = step.displayKey != null ? this.advRoomName(step.displayKey) : '';
+    const seatName = this.seatName(ab.seat);
+    let boosted = false;
+    if (step.kind === 'roomHit' && step.displayKey != null) {
+      const rc = ab.roomCards.get(step.displayKey);
+      const def = rc && ROOMS[rc.defId];
+      boosted = !!(def && step.amount > def.dmg);
+    }
+    return { heroName, roomName, seatName, boosted };
+  }
+
+  adventureLogLine(step, ctx) {
+    switch (step.kind) {
+      case 'enter':
+        return `${ctx.heroName} enters the dungeon${step.teleported ? ' again (teleported!)' : ''}...`;
+      case 'pass':
+        return `${ctx.heroName} slips past ${ctx.roomName} unscathed.`;
+      case 'roomHit': {
+        const total = (step.rampAmount || 0) + (step.amount || 0) + (step.bounceAmount || 0);
+        const boosted = ctx.boosted ? ' (boosted!)' : '';
+        const bounce = step.bounceAmount ? ' — bounced back into the previous room!' : '';
+        let line = `${ctx.roomName} hits ${ctx.heroName} for ${total}${boosted}${bounce}`;
+        if (step.heroDies) line += ` — ${ctx.heroName} falls! (+${step.heroDies.souls} soul${step.heroDies.souls > 1 ? 's' : ''})`;
+        return line;
+      }
+      case 'trapKill': {
+        const souls = step.heroDies?.souls ?? 1;
+        return `${ctx.roomName} triggers — it collapses, destroying itself and killing ${ctx.heroName} instantly! (+${souls} soul${souls > 1 ? 's' : ''})`;
+      }
+      case 'bossWound':
+        return `${ctx.heroName} reaches the boss chamber! ${ctx.seatName}'s boss takes ${step.wounds} wound${step.wounds > 1 ? 's' : ''} (${step.total}/5)`
+          + (step.eliminated ? ` — ${ctx.seatName} is slain!` : '');
+      default:
+        return '';
+    }
+  }
+
+  adventureLogColor(step) {
+    if (step.kind === 'roomHit' || step.kind === 'trapKill') return '#8c1f28';
+    if (step.kind === 'bossWound' && step.eliminated) return '#8c1f28';
+    return C.ink;
+  }
+
+  playEnterStep(step, onDone) {
+    const ab = this._advBattle;
+    const rec = ab.heroCards.get(step.uid);
+    this.resetRoomDimming(); // fresh hero, fresh run — every room but a truly destroyed one is fair game again
+    if (!rec) { onDone(); return; }
+    const hl = this.add.graphics();
+    hl.lineStyle(3, C.gold, 1);
+    hl.strokeRoundedRect(rec.x - rec.w / 2 - 5, rec.y - rec.h / 2 - 5, rec.w + 10, rec.h + 10, 8);
+    ab.root.add(hl);
+    this.tweens.add({ targets: hl, alpha: 0, duration: 500, ease: 'Cubic.easeOut', onComplete: () => { hl.destroy(); onDone(); } });
+  }
+
+  // Rooms only get dimmed to mark "already passed through THIS hero's run" —
+  // a room a prior hero cleared is fully live again for the next one, so
+  // undo that dimming whenever a fresh hero starts (a room actually
+  // destroyed by a trap stays a rubble placeholder for the whole session).
+  resetRoomDimming() {
+    const ab = this._advBattle;
+    ab.roomCards.forEach((rc) => {
+      if (!rc.destroyed && rc.cont.alpha < 1) {
+        this.tweens.add({ targets: rc.cont, alpha: 1, duration: 260, ease: 'Cubic.easeOut' });
+      }
+    });
+  }
+
+  playPassStep(step, onDone) {
+    this.moveToStage(step.uid, step.displayKey, { duration: 200 }, () => {
+      this.time.delayedCall(140, () => {
+        this.returnHome(step.uid, step.displayKey, () => { this.dimRoomCard(step.displayKey); onDone(); });
+      });
+    });
+  }
+
+  playRoomHitStep(step, onDone) {
+    const ab = this._advBattle;
+    const uid = step.uid;
+    const heroRec = ab.heroCards.get(uid);
+    const roomRec = ab.roomCards.get(step.displayKey);
+    const def = roomRec && ROOMS[roomRec.defId];
+    const trap = def && def.type === 'trap';
+
+    this.moveToStage(uid, step.displayKey, {}, () => {
+      const midX = (ADV_STAGE_HERO.x + ADV_STAGE_ROOM.x) / 2, midY = (ADV_STAGE_HERO.y + ADV_STAGE_ROOM.y) / 2;
+      if (roomRec) this.tweens.add({ targets: roomRec.cont, x: roomRec.cont.x - 30, duration: 130, ease: 'Back.easeOut', yoyo: true });
+      this.popText(midX, midY, '⚔', trap ? '#c9962a' : '#ff6b5e', 34);
+      this.time.delayedCall(260, () => {
+        this.shakeAt(ADV_STAGE_HERO.x, ADV_STAGE_HERO.y);
+        const totalAmount = (step.rampAmount || 0) + (step.amount || 0) + (step.bounceAmount || 0);
+        this.popHeroDamageNumber(totalAmount);
+        if (def && step.amount > def.dmg) this.popText(ADV_STAGE_HERO.x + 46, ADV_STAGE_HERO.y - 74, '⚡ boosted!', '#f5d76e', 16);
+        const startHp = this.advHeroCurrentHp(uid);
+        const newHp = Math.max(0, startHp - totalAmount);
+        this.advSetHeroCurrentHp(uid, newHp);
+        if (heroRec?.cont.hpText) {
+          const hpObj = { v: startHp };
+          this.tweens.add({
+            targets: hpObj, v: newHp, duration: 440, ease: 'Cubic.easeIn',
+            onUpdate: () => heroRec.cont.hpText.setText(`${Math.round(hpObj.v)}`),
+          });
+        }
+        if (step.heroDies) this.time.delayedCall(480, () => this.removeHeroCard(uid, onDone));
+        else this.time.delayedCall(480, onDone);
+      });
+    });
+  }
+
+  playTrapKillStep(step, onDone) {
+    const ab = this._advBattle;
+    const uid = step.uid;
+    const roomRec = ab.roomCards.get(step.displayKey);
+    this.moveToStage(uid, step.displayKey, {}, () => {
+      if (roomRec) this.tweens.add({ targets: roomRec.cont, scaleY: 0.1, duration: 180, ease: 'Cubic.easeIn' });
+      this.popText(ADV_STAGE_ROOM.x, ADV_STAGE_ROOM.y, '💥', '#ffffff', 40);
+      this.shakeAt(ADV_STAGE_ROOM.x, ADV_STAGE_ROOM.y);
+      this.time.delayedCall(60, () => this.shakeAt(ADV_STAGE_HERO.x, ADV_STAGE_HERO.y));
+      const heroRec = ab.heroCards.get(uid);
+      if (heroRec) {
+        // Size to the card's CURRENT on-stage scale, not its small built
+        // dimensions, so the flash actually covers the (now much bigger,
+        // hover-preview-sized) card.
+        const s = heroRec.cont.scaleX || 1;
+        const flash = this.add.rectangle(heroRec.cont.x, heroRec.cont.y, heroRec.w * s, heroRec.h * s, 0xff0000, 0.5);
+        ab.stage.add(flash);
+        this.tweens.add({ targets: flash, alpha: 0, duration: 260, onComplete: () => flash.destroy() });
+      }
+      this.time.delayedCall(300, () => this.removeHeroCard(uid, onDone));
+    });
+  }
+
+  playBossWoundStep(step, onDone) {
+    const ab = this._advBattle;
+    const uid = step.uid;
+    const heroRec = ab.heroCards.get(uid);
+    const boss = ab.bossCard;
+    if (!heroRec || !boss) { onDone(); return; }
+    this.tweens.add({
+      targets: heroRec.cont, x: boss.x - boss.w / 2 - 10, y: boss.y, scale: 1.1,
+      duration: 260, ease: 'Back.easeIn',
+      onComplete: () => {
+        this.shakeAt(boss.x, boss.y);
+        this.popText(boss.x, boss.y - boss.h / 2 - 10, `☠ wound${step.wounds > 1 ? ' ×2' : ''}`, '#ff5348', 26);
+        const flash = this.add.rectangle(boss.x, boss.y, boss.w, boss.h, 0xc0392b, 0.4);
+        ab.root.add(flash);
+        this.tweens.add({ targets: flash, alpha: 0, duration: 380, onComplete: () => flash.destroy() });
+        this.tweens.add({
+          targets: heroRec.cont, alpha: 0, duration: 300, delay: 150, ease: 'Cubic.easeIn',
+          onComplete: () => {
+            heroRec.cont.destroy();
+            ab.heroCards.delete(uid);
+            const idx = ab.heroOrder.indexOf(uid);
+            if (idx >= 0) ab.heroOrder.splice(idx, 1);
+            if (step.eliminated) this.showAdventureEliminatedBanner(this.seatName(ab.seat), onDone);
+            else onDone();
+          },
+        });
+      },
+    });
+  }
+
+  showAdventureEliminatedBanner(name, onDone) {
+    const ab = this._advBattle;
+    const dark = this.add.rectangle(GAME_WIDTH / 2, GAME_HEIGHT / 2, GAME_WIDTH, GAME_HEIGHT, 0x000000, 0.35);
+    ab.root.add(dark);
+    const banner = this.add.text(GAME_WIDTH / 2, 120, `${name} has been slain!`, {
+      fontFamily: 'Righteous', fontSize: '34px', color: '#f2ead8',
+      backgroundColor: '#120e16ee', padding: { x: 28, y: 14 },
+    }).setOrigin(0.5).setAlpha(0);
+    ab.root.add(banner);
+    this.tweens.add({ targets: banner, alpha: 1, duration: 240, ease: 'Back.easeOut', onComplete: () => this.time.delayedCall(900, onDone) });
+  }
+
   // ── prompt + action buttons ─────────────────────────────────────────────────
   setPrompt(txt) { this.promptText.setText(txt || ''); }
   addActionButton(label, cb) {
     this._actionButtons = this._actionButtons || [];
     const i = this._actionButtons.length;
-    const b = new Button(this, GAME_WIDTH / 2 + 470 + (i % 2) * 160, 830 + Math.floor(i / 2) * 48, label, cb,
-      { width: 150, fontSize: 18 });
+    // Stacked in a single column under the human boss card (center x=1740,
+    // bottom edge ≈820.4 — see makeBossCard(1740, 700, ..., 168, 236) — plus
+    // a little padding), rather than beside the prompt text.
+    const b = new Button(this, 1740, 890 + i * 52, label, cb, { width: 160, fontSize: 18 });
     b.setDepth(DEPTH.ui);
     this._actionButtons.push(b);
   }
@@ -1977,10 +3074,17 @@ export default class DungeonBossGame extends Phaser.Scene {
     this._humanDrawBatch = { room: 0, spell: 0 };
     this._humanDrawSeen = { room: 0, spell: 0 };
     for (const e of events) if (e.type === 'draw' && e.seat === this.humanSeat) this._humanDrawBatch[e.card]++;
-    const queue = events.filter((e) => this.eventDelay(e) > 0 || this.eventFx(e, true));
+    // `before` (e.g. the windowPass event(s) that close the pre-adventure
+    // advStart window — confirmed via engine trace to share the SAME batch
+    // as the heroEnters it unblocks) plays through the normal fixed-delay
+    // pipeline first; once it drains, `walk` (if any) hands off to the
+    // adventure battle modal instead of falling through to pump().
+    const { before, walk, rest } = this.splitAdventureWalk(events);
+    const queue = before.filter((e) => this.eventDelay(e) > 0 || this.eventFx(e, true));
     const step = () => {
       const e = queue.shift();
       if (!e) {
+        if (walk.length) { this.renderAll(); this.runAdventureWalk(walk, rest); return; }
         this.busy = false;
         this.renderAll();
         this.pump();
@@ -1999,7 +3103,7 @@ export default class DungeonBossGame extends Phaser.Scene {
       case 'flip': return 260;
       case 'roomBuilt': return 240;
       case 'heroRevealed': return 140;
-      case 'heroWalks': return 320;
+      case 'heroWalks': return 1500;
       case 'heroEnters': return 200;
       case 'roomHits': return 340;
       case 'heroDies': return 480;
@@ -2009,6 +3113,10 @@ export default class DungeonBossGame extends Phaser.Scene {
       case 'spellCast': return 820;
       case 'spellCountered': return 700;
       case 'roundStart': return 600;
+      case 'roundEnd': return 400;
+      case 'phaseBuild': return 10;
+      case 'phaseBait': return 10;
+      case 'phaseAdventure': return 10;
       case 'heroResurrected': return 400;
       case 'roomDestroyed': return 320;
       case 'roomFrozen': return 300;
@@ -2049,13 +3157,26 @@ export default class DungeonBossGame extends Phaser.Scene {
         break;
       }
       case 'heroWalks': {
-        const from = this._heroTokens.get(e.uid);
+        // Use the pre-mutation snapshot (see applyDecision) — by now
+        // renderAll() has already redrawn the town without this hero (bait
+        // already moved it into an entrance), so the live _heroTokens has no
+        // entry for it any more.
+        const from = this._preBaitHeroTokens?.get(e.uid) || this._heroTokens.get(e.uid);
         const hero = this.findHero(e.uid) || { uid: e.uid, id: e.id, hp: 0 };
         if (from) {
-          const tok = this.heroToken(hero, from.x, from.y);
-          this.fxLayer.add(tok);
+          // Built at full town-card width, then tweened down (via scale) to
+          // the destination gate's mini-card width as it flies, so the hero
+          // visibly shrinks into its resting entrance size.
+          const entW = e.seat === this.humanSeat ? HUMAN_ENTRANCE_W : OPP_ENTRANCE_W;
+          const tok = this.miniHeroCard(from.x, from.y, hero, TOWN_HERO_W, {
+            parent: this.fxLayer, noHoverPreview: true,
+          });
           const to = this.entranceApprox(e.seat);
-          this.tweens.add({ targets: tok, x: to.x, y: to.y, duration: 300, ease: 'Cubic.easeIn', onComplete: () => tok.destroy() });
+          const scale = entW / TOWN_HERO_W;
+          this.tweens.add({
+            targets: tok, x: to.x, y: to.y, scaleX: scale, scaleY: scale,
+            duration: 1500, ease: 'Cubic.easeInOut', onComplete: () => tok.destroy(),
+          });
         }
         break;
       }
@@ -2109,6 +3230,19 @@ export default class DungeonBossGame extends Phaser.Scene {
       case 'roundStart':
         this.showBanner(`— Round ${e.round} —`);
         this.sfx(SFX.CARD_DEAL);
+        this.phaseWheel.setPhase('roundStart');
+        break;
+      case 'roundEnd':
+        this.phaseWheel.setPhase('roundEnd');
+        break;
+      case 'phaseBuild':
+        this.phaseWheel.setPhase('build');
+        break;
+      case 'phaseBait':
+        this.phaseWheel.setPhase('bait');
+        break;
+      case 'phaseAdventure':
+        this.phaseWheel.setPhase('adventure');
         break;
       case 'heroResurrected':
         this.popText(GAME_WIDTH / 2, 500, 'A hero rises from the grave!', '#9be89b');
diff --git a/src/games/dungeonboss/DungeonBossLogic.js b/src/games/dungeonboss/DungeonBossLogic.js
index c41e147..2d8d6af 100644
--- a/src/games/dungeonboss/DungeonBossLogic.js
+++ b/src/games/dungeonboss/DungeonBossLogic.js
@@ -1035,6 +1035,7 @@ export function baitTargets(state) {
 }
 
 function runBait(state) {
+  emit(state, { type: 'phaseBait' });
   const targets = baitTargets(state);
   const staying = [];
   for (const hero of state.town) {
@@ -1048,6 +1049,7 @@ function runBait(state) {
 
 // ── Adventure ───────────────────────────────────────────────────────────────
 function startAdventure(state) {
+  emit(state, { type: 'phaseAdventure' });
   state.phase = 'adventure';
   state.adv = { orderIdx: -1, walking: null, windowOpened: false };
   nextAdventureSeat(state);
@@ -1311,6 +1313,7 @@ function advance(state) {
       case 'roundStart':
         state.window = { id: 'buildStart', passes: [], casts: 0 };
         state.phase = 'windowBuildStart';
+        emit(state, { type: 'phaseBuild' });
         continue;
       case 'windowBuildStart':
         // window handled above; when closed phase becomes 'build'
diff --git a/src/ui/Portrait.js b/src/ui/Portrait.js
index 73c5fa0..11b7ec9 100644
--- a/src/ui/Portrait.js
+++ b/src/ui/Portrait.js
@@ -280,7 +280,25 @@ export function createOpponentPortrait(scene, opponent, worldX, worldY, radius,
     });
   }
 
-  return { playEmotion, hide, show, stopVideo, fadeToEliminated, destroy, setVideoVisible };
+  // Draws a fresh, independent static copy of this opponent's picture (the
+  // same sprite-sheet frame the video sits in front of — never the <video>
+  // itself, which always renders above canvas content regardless of depth)
+  // at an arbitrary spot. Caller owns the returned GameObjects' lifecycle.
+  function renderInto(x, y, radius, depth) {
+    const objs = [drawBacking(scene, x, y, radius, depth)];
+    if (scene.textures.exists('opponents')) {
+      const maskG = scene.make.graphics({ x: 0, y: 0, add: false });
+      maskG.fillStyle(0xffffff);
+      maskG.fillCircle(x, y, radius);
+      objs.push(scene.add.image(x, y, 'opponents', opponent?.spriteIndex ?? 0)
+        .setDisplaySize(radius * 2, radius * 2)
+        .setMask(maskG.createGeometryMask())
+        .setDepth(depth + 1));
+    }
+    return objs;
+  }
+
+  return { playEmotion, hide, show, stopVideo, fadeToEliminated, destroy, setVideoVisible, renderInto };
 }
 
 // ── Player portrait (profile avatar with letter fallback) ─────────────────────
@@ -299,6 +317,7 @@ export function createPlayerPortrait(scene, worldX, worldY, radius, depth, scene
 
   const allObjs = [backingG, placeholder];
   let destroyed = false;
+  let avatarKey = null; // set once the avatar texture is loaded, for renderInto()
 
   // Async avatar load
   (async () => {
@@ -327,6 +346,7 @@ export function createPlayerPortrait(scene, worldX, worldY, radius, depth, scene
         .setMask(maskG.createGeometryMask())
         .setDepth(depth + 1);
       allObjs.push(avatarImg);
+      avatarKey = key;
     } catch { /* placeholder remains */ }
   })();
 
@@ -348,5 +368,26 @@ export function createPlayerPortrait(scene, worldX, worldY, radius, depth, scene
     allObjs.length = 0;
   }
 
-  return { hide, show, stopVideo, fadeToEliminated, destroy, setVideoVisible };
+  // Draws a fresh, independent static copy of the player's picture (the
+  // loaded avatar if ready, else the same letter fallback) at an arbitrary
+  // spot. Caller owns the returned GameObjects' lifecycle.
+  function renderInto(x, y, radius, depth) {
+    const objs = [drawBacking(scene, x, y, radius, depth)];
+    if (avatarKey && scene.textures.exists(avatarKey)) {
+      const maskG = scene.make.graphics({ x: 0, y: 0, add: false });
+      maskG.fillStyle(0xffffff);
+      maskG.fillCircle(x, y, radius);
+      objs.push(scene.add.image(x, y, avatarKey)
+        .setDisplaySize(radius * 2, radius * 2)
+        .setMask(maskG.createGeometryMask())
+        .setDepth(depth + 1));
+    } else {
+      objs.push(scene.add.text(x, y, initial, {
+        fontFamily: '"Julius Sans One"', fontSize: `${Math.round(radius * 0.9)}px`, color: COLORS.accentHex,
+      }).setOrigin(0.5).setDepth(depth + 1));
+    }
+    return objs;
+  }
+
+  return { hide, show, stopVideo, fadeToEliminated, destroy, setVideoVisible, renderInto };
 }