@energy8platform/platform-core 0.25.3 → 0.26.0

package/src/shell/GameShell.ts

@@ -11,7 +11,8 @@ import type {
   ShellState,
   ThemeConfig,
 } from './types';
-import { createInitialState } from './state';
+import { KeyboardController, type KeyboardHost } from './keyboard';
+import { createInitialState, nextTurbo, stepBet } from './state';
 import { buildThemeVars } from './theme';
 import { SHELL_CSS, SHELL_ROOT_ID } from './shell.css';
 import { renderBottomBar } from './components/BottomBar';
@@ -23,7 +24,7 @@ import { buildModal } from './components/Modal';
 import { buildReplayModal } from './components/ReplayModal';
 import { countUp } from './motion';
 import { formatCurrency } from './format';
-import { socialize } from './i18n';
+import { createI18n, type I18n } from './i18n';
 
 const REMOVE_FADE_MS = 300;
 
@@ -40,11 +41,20 @@ export class GameShell extends EventEmitter<ShellEvents> {
   private prevBalance = 0;
   private prevWin = 0;
   private moneyAnims: Array<() => void> = [];
-  private keysBound = false;
+  private kbd!: KeyboardController;
+  private i18n!: I18n;
+  /** onKey handler of the currently open modal/overlay, if any (set in showModal, cleared in closeModal). */
+  private modalOnKey: ((e: KeyboardEvent) => boolean) | undefined = undefined;
+  /** Shared sound on/off state — Settings speaker toggle and the Shift+M hotkey stay in sync. The
+   *  game listens to `settingChange({ key: 'sound' })` to (un)mute audio. */
+  soundOn = true;
+  /** Set by the open Settings modal so Shift+M live-updates its speaker icon; cleared on close. */
+  private soundRefresh: ((on: boolean) => void) | null = null;
 
   constructor(config: ShellConfig) {
     super();
     this.config = config;
+    this.i18n = createI18n({ language: config.language, isSocial: config.isSocial });
     this.state = createInitialState(config);
 
     this.styleEl = document.createElement('style');
@@ -63,12 +73,47 @@ export class GameShell extends EventEmitter<ShellEvents> {
     this.prevWin = this.state.win;
     this.observeLayout();
     if (typeof document !== 'undefined') {
-      document.addEventListener('keydown', this.handleKeyDown);
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
+      const shell = this;
+      const host: KeyboardHost = {
+        get state() { return shell.state; },
+        get hotkeysEnabled() { return shell.config.features.hotkeys !== false; },
+        get spacebarEnabled() { return shell.config.features.spacebar !== false; },
+        get turboLevels() { return shell.config.features.turbo; },
+        get autoplayEnabled() { return shell.config.features.autoplay != null; },
+        get buyBonusEnabled() { return shell.config.features.buyBonus !== false; },
+        hasOpenLayer: () => shell.modalHost.childElementCount > 0,
+        routeToLayer: (e) => shell.modalOnKey?.(e) ?? false,
+        spin: () => shell.emit('spin'),
+        stepBet: (dir) => {
+          const next = stepBet(shell.state, dir);
+          if (next === shell.state.bet) return;
+          shell.state.bet = next; shell.emit('betChange', next); shell.render();
+        },
+        toggleAutoplay: () => {
+          if (shell.state.autoplay.active) {
+            shell.state.autoplay = { active: false, remaining: 0 };
+            shell.emit('autoplayStop'); shell.render();
+          } else {
+            shell.openAutoplayPicker();
+          }
+        },
+        cycleTurbo: () => {
+          const next = nextTurbo(shell.state.turbo, shell.config.features.turbo);
+          shell.state.turbo = next; shell.emit('turboChange', next); shell.render();
+        },
+        openBuyBonus: () => shell.openBuyBonus(),
+        openInfo: () => shell.openInfo(),
+        openMenu: () => shell.openMenu(),
+        toggleMute: () => shell.setSound(!shell.soundOn),
+        closeLayer: () => shell.closeModal(),
+      };
+      this.kbd = new KeyboardController(host);
+      this.kbd.attach();
       // Stake serves the game in an iframe; on first paint focus is on the HOST page, so a `document`
       // keydown never fires and Space scrolls the parent. Pull window focus into the iframe on the
       // first pointer interaction so the spacebar shortcut works. Harmless on full-page Energy8.
       document.addEventListener('pointerdown', this.pullFocus, true);
-      this.keysBound = true;
     }
     this.render();
     // re-fit once the bundled webfont swaps in (text metrics change → row width changes)
@@ -113,10 +158,11 @@ export class GameShell extends EventEmitter<ShellEvents> {
     host.classList.remove('ge-fit');
     host.style.transform = '';
     host.style.transformOrigin = '';
-    // clear any per-zone height-scale from a prior pass
+    // clear any per-zone scale/zoom from a prior pass
     for (const el of host.querySelectorAll('.ge-zone, .ge-winpill')) {
       (el as HTMLElement).style.transform = '';
       (el as HTMLElement).style.transformOrigin = '';
+      (el as HTMLElement).style.removeProperty('zoom');
     }
     if (this.layout === 'mobile') {
       // Shrink the whole stack to fit narrow phones (mobile-s, or big balance/win/total-win
@@ -133,74 +179,59 @@ export class GameShell extends EventEmitter<ShellEvents> {
       }
       return;
     }
-    const availW = this.root.clientWidth - 12;
-    const availH = this.root.clientHeight * GameShell.BAR_MAX_FRACTION;
-    // 1) If the inline row overflows the width, lift the WIN pill onto its own line above the bar
-    //    (keeps the controls as large as possible — base's wide row + a big WIN pill hit this).
+    // ONE fit-scale, from the SCREEN SIZE, applied identically in EVERY mode — switching base⇄replay
+    // must not resize the bar. The factor is the frame WIDTH vs the bar's design width, never the
+    // current mode's content width.
+    //
+    // It's applied with `zoom` (not `transform`): zoom shrinks the LAYOUT, so the zones genuinely
+    // take less room and still sit edge-to-edge (menu hard-left, controls hard-right) even when base's
+    // wide row would overflow a merely-visually-scaled bar — so there is no per-mode centred cluster
+    // and no width/mode branching. A wide WIN pill is still lifted above the row first so it can't
+    // shove the controls off-screen. (Mobile, above, keeps its own stacked fit.)
     if (pill && bar.scrollWidth > bar.clientWidth + 1) { host.insertBefore(pill, bar); pill.classList.add('ge-up'); }
-    // 2) Still too WIDE (the control row itself doesn't fit) → shrink-to-content + uniform scale,
-    //    centred. Only base's wide row reaches here.
-    if (bar.scrollWidth > bar.clientWidth + 1) {
-      host.classList.add('ge-fit');
-      const naturalW = host.offsetWidth, naturalH = host.offsetHeight;
-      const s = Math.min(1, naturalW > 0 ? availW / naturalW : 1, naturalH > 0 ? availH / naturalH : 1);
-      if (s < 0.999) host.style.transform = `translateX(-50%) scale(${s.toFixed(4)})`;
-      else host.classList.remove('ge-fit');
-      return;
-    }
-    // 3) Fits the WIDTH but the stack (control row + any lifted WIN pill) is too TALL for a short
-    //    frame — replay/free-spins on Popout S. Shrink each piece toward its OWN edge so the bar
-    //    keeps its full-width space-between layout (menu hard-left, controls hard-right), just
-    //    lower — NOT packed into a centred cluster. Scale by frame HEIGHT only.
-    const naturalH = host.offsetHeight;
-    if (naturalH > availH && naturalH > 0) {
-      const s = (availH / naturalH).toFixed(4);
-      const scaleEdge = (el: Element | null, origin: string): void => {
-        if (!el) return;
-        (el as HTMLElement).style.transformOrigin = origin;
-        (el as HTMLElement).style.transform = `scale(${s})`;
-      };
-      scaleEdge(bar.querySelector('.ge-zone-left'), 'left bottom');
-      scaleEdge(bar.querySelector('.ge-zone-right'), 'right bottom');
-      scaleEdge(host.querySelector('.ge-winpill'), 'center bottom');
+    const zoomBar = (z: number): void => {
+      const v = z < 0.999 ? z.toFixed(4) : '';
+      for (const el of host.querySelectorAll('.ge-zone, .ge-winpill')) {
+        if (v) (el as HTMLElement).style.setProperty('zoom', v);
+        else (el as HTMLElement).style.removeProperty('zoom');
+      }
+    };
+    const s = Math.max(GameShell.BAR_MIN_SCALE, Math.min(1, this.root.clientWidth / GameShell.BAR_REF_WIDTH));
+    zoomBar(s);
+    // Safety: a pathologically long balance/win can still overflow the frame at the screen zoom —
+    // nudge the zoom down just enough that the far control (turbo) isn't clipped. Normal content
+    // never triggers this, so base and replay keep the SAME zoom (no size change on mode switch).
+    if (bar.scrollWidth > bar.clientWidth + 1 && bar.scrollWidth > 0) {
+      zoomBar(s * (bar.clientWidth / bar.scrollWidth));
     }
   }
 
-  /** Spacebar starts a spin — same path as the spin disc. Ignored when `features.spacebar` is
-   *  false, while a spin is running, while autoplay is active, outside base mode, when an
-   *  overlay/modal is open, or when an editable element is focused. `repeat` (held key) is
-   *  ignored so it can't spam. */
   /** Pull window focus into the iframe on first pointer interaction so `document` keydown (the
    *  spacebar shortcut) fires. No-op / harmless when already focused or full-page. */
   private pullFocus = (): void => { try { window.focus(); } catch { /* cross-origin / non-browser */ } };
 
-  private handleKeyDown = (e: KeyboardEvent): void => {
-    if (this.destroyed || e.code !== 'Space' || e.repeat) return;
-    if (this.config.features.spacebar === false) return; // shortcut disabled (e.g. jurisdiction)
-    const t = e.target as HTMLElement | null;
-    if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
-    // Space is ours now — swallow the browser default before any no-op bail. Otherwise the
-    // native "Space activates the focused button" still fires and re-clicks whichever shell
-    // <button> (menu/buy/auto) opened the overlay, tearing down + rebuilding the modal: a
-    // visible flicker. (Also stops the page from scrolling on Space.)
-    e.preventDefault();
-    if (this.modalHost.childElementCount > 0) return; // an overlay/modal is open
-    if (this.state.mode !== 'base' || this.state.busy || this.state.autoplay.active) return;
-    this.emit('spin');
-  };
-
   setLayout(layout: 'wide' | 'mobile'): void {
     if (layout === this.layout) return;
     this.layout = layout;
     this.render();
   }
 
-  /** Resolve a built-in shell string. English is the source; with `isSocial` it is run through
-   *  the social-casino word-swap. Game-supplied strings should NOT be passed through this. */
-  t(text: string): string { return this.config.isSocial ? socialize(text) : text; }
+  /** Resolve a built-in shell string through the i18n resolver (translation + optional socialize). */
+  t(text: string): string { return this.i18n.t(text); }
+
+  /** Toggle the social vocabulary at runtime (rebuilds resolver, re-renders bar). */
+  setSocial(isSocial: boolean): void {
+    this.config.isSocial = isSocial;
+    this.i18n = createI18n({ language: this.config.language, isSocial });
+    this.render();
+  }
 
-  /** Toggle the social vocabulary at runtime (re-renders the bar; reopen overlays to refresh them). */
-  setSocial(isSocial: boolean): void { this.config.isSocial = isSocial; this.render(); }
+  /** Swap the active language at runtime (rebuilds resolver, re-renders bar). */
+  setLanguage(lang: string): void {
+    this.config.language = lang;
+    this.i18n = createI18n({ language: lang, isSocial: this.config.isSocial });
+    this.render();
+  }
 
   /** Recolour the shell at runtime (e.g. switch dark/light scheme). */
   setTheme(theme: ThemeConfig): void {
@@ -241,7 +272,7 @@ export class GameShell extends EventEmitter<ShellEvents> {
     this.state.mode = mode;
     this.render();
   }
-  setBusy(busy: boolean): void { this.state.busy = busy; this.render(); }
+  setBusy(busy: boolean): void { this.state.busy = busy; this.render(); this.kbd?.notifyBusyChanged(busy); }
   setAutoplay(a: AutoplayOptions): void { this.state.autoplay = a; this.render(); }
   setTurbo(level: number): void { this.state.turbo = level; this.render(); }
   /** Currency-aware money formatter for WIN amounts (variable decimals: 0.0041 stays 0.0041, not
@@ -250,7 +281,7 @@ export class GameShell extends EventEmitter<ShellEvents> {
   setBuyBonusEnabled(enabled: boolean): void { this.state.buyBonusEnabled = enabled; this.render(); }
   setFreeSpins(fs: FreeSpinsState): void { this.state.freeSpins = fs; this.render(); }
 
-  private showModal(el: HTMLElement): void {
+  private showModal(el: HTMLElement, onKey?: (e: KeyboardEvent) => boolean): void {
     // The control that opened this overlay (menu/buy/auto) keeps DOM focus. Drop it, or a
     // stray Space/Enter would natively re-activate that <button> and rebuild the modal — a
     // visible flicker. Only relinquish focus we own (a shell control), never the host page's.
@@ -258,6 +289,7 @@ export class GameShell extends EventEmitter<ShellEvents> {
     if (active && this.root.contains(active)) active.blur();
     this.modalHost.innerHTML = '';
     this.modalHost.appendChild(el);
+    this.modalOnKey = onKey;
     this.fitModals();
   }
 
@@ -274,9 +306,12 @@ export class GameShell extends EventEmitter<ShellEvents> {
    *  modals from filling a small popout edge-to-edge (so even short pickers scale down there). */
   private static readonly MODAL_FIT = 0.86;
 
-  /** Max fraction of the frame HEIGHT the bottom bar may occupy before it fit-scales down. Keeps the
-   *  bar a consistent, small slice on short popouts in EVERY mode (base ≈ this already via width). */
-  private static readonly BAR_MAX_FRACTION = 0.27;
+  /** The bar's design width (px). When the frame is narrower, the bar fit-scales DOWN with the
+   *  screen — the SAME factor in every mode, so replay/free-spins shrink like base instead of
+   *  staying full-size on a popout. */
+  private static readonly BAR_REF_WIDTH = 840;
+  /** Lower bound on the bar fit-scale (guards a degenerate near-zero frame). */
+  private static readonly BAR_MIN_SCALE = 0.5;
 
   private fitSheet(root: HTMLElement): void {
     const card = root.querySelector('.ge-modal-card') as HTMLElement | null;
@@ -309,18 +344,28 @@ export class GameShell extends EventEmitter<ShellEvents> {
 
   openMenu(): void { this.emit('menuOpen'); this.openSettings(); }
   openSettings(): void { this.emit('settingsOpen'); this.showModal(openSettingsModal(this)); }
-  openInfo(): void { this.emit('infoOpen'); this.showModal(openGameInfoModal(this)); }
+  openInfo(): void { this.emit('infoOpen'); const { root, onKey } = openGameInfoModal(this); this.showModal(root, onKey); }
   openBuyBonus(): void {
     if (this.config.onBonusBuy) { this.config.onBonusBuy(); return; } // game handles it (own UI)
-    const overlay = openBuyBonusOverlay(this);
-    if (overlay) this.showModal(overlay);
+    const result = openBuyBonusOverlay(this);
+    if (result) this.showModal(result.root, result.onKey);
   }
   /** Open a generic, externally-driven modal (title + body + optional action buttons).
    *  Each action runs its `on` then closes; the ✕ shows when `availableClose` is true. */
-  openModal(opts: ModalOptions): void { this.showModal(buildModal(opts)); }
+  openModal(opts: ModalOptions): void { this.showModal(buildModal(opts), opts.onKey); }
   /** Programmatically dismiss whatever modal/overlay is currently shown (e.g. auto-close the
    *  reconnect overlay once the link is restored). No-op when nothing is open. */
-  closeModal(): void { this.modalHost.innerHTML = ''; }
+  closeModal(): void { this.modalOnKey = undefined; this.soundRefresh = null; this.modalHost.innerHTML = ''; }
+
+  /** Flip the shared sound state, notify the game (`settingChange({ key: 'sound' })`), and live-update
+   *  the Settings speaker icon if that modal is open. Used by both the Settings toggle and Shift+M. */
+  setSound(on: boolean): void {
+    this.soundOn = on;
+    this.emit('settingChange', { key: 'sound', value: on });
+    this.soundRefresh?.(on);
+  }
+  /** The Settings modal registers an icon-updater while open (cleared on close). */
+  setSoundRefresh(fn: ((on: boolean) => void) | null): void { this.soundRefresh = fn; }
   /** Open the non-dismissable replay summary modal (START REPLAY → onReplay → reopen). */
   openReplay(opts: ReplayModalOptions): void {
     if (this.destroyed) return;
@@ -328,19 +373,18 @@ export class GameShell extends EventEmitter<ShellEvents> {
   }
 
   /** Bet picker — list of available bets with an accent Confirm. */
-  openBetPicker(): void { this.showModal(openBetModal(this)); }
+  openBetPicker(): void { const { root, onKey } = openBetModal(this); this.showModal(root, onKey); }
   /** Autoplay picker — spin-count list; Confirm starts autoplay. */
-  openAutoplayPicker(): void { this.showModal(openAutoplayModal(this)); }
+  openAutoplayPicker(): void { const { root, onKey } = openAutoplayModal(this); this.showModal(root, onKey); }
 
   destroy(): Promise<void> {
     if (this.destroyed) return Promise.resolve();
     this.destroyed = true;
     this.ro?.disconnect();
     this.ro = null;
-    if (this.keysBound) {
-      document.removeEventListener('keydown', this.handleKeyDown);
+    if (typeof document !== 'undefined') {
+      this.kbd?.detach();
       document.removeEventListener('pointerdown', this.pullFocus, true);
-      this.keysBound = false;
     }
     this.cancelMoneyAnims();
     this.removeAllListeners();

package/src/shell/components/BuyBonus.ts

@@ -2,27 +2,172 @@ import type { GameShell } from '../GameShell';
 import type { BonusOption } from '../types';
 import { formatCurrency } from '../format';
 import { stepBet } from '../state';
+import { betDir } from '../keyboard';
 import { effectiveAccent, contrastText } from '../colors';
 import { createOverlay, createCardModal } from './primitives';
 import { icon, type IconName } from './icons';
 
-/** Buy-bonus overlay — a grid of art-forward cards, one per option. */
-export function openBuyBonusOverlay(shell: GameShell): HTMLElement | null {
+/** Mutable state shared between the overlay DOM and the onKey handler. */
+interface OverlayState {
+  /** Index into the affordable-card subset; -1 = none (no affordable cards). */
+  focusIndex: number;
+  /** The bonus whose confirm dialog is currently open, or undefined. */
+  confirmBonus: BonusOption | undefined;
+}
+
+/** Buy-bonus overlay — a grid of art-forward cards, one per option.
+ *  Returns the overlay element + a keyboard handler for the shell's `showModal`. */
+export function openBuyBonusOverlay(shell: GameShell): { root: HTMLElement; onKey: (e: KeyboardEvent) => boolean } | null {
   const bonuses = shell.config.features.buyBonus;
   if (bonuses === false || bonuses.length === 0) return null;
 
-  const { root, body } = createOverlay({ title: shell.t('Buy bonus'), onClose: () => root.remove() });
+  const st: OverlayState = { focusIndex: -1, confirmBonus: undefined };
+
+  const { root, body } = createOverlay({ title: shell.t('Buy bonus'), onClose: () => shell.closeModal() });
   root.dataset.ge = 'buybonus-overlay';
+
   // Re-render the grid whenever the bet changes so every card's price stays live.
-  const renderGrid = () => {
+  const renderGrid = (): void => {
     body.innerHTML = '';
     const grid = document.createElement('div'); grid.className = 'ge-bb-grid';
-    for (const bonus of bonuses) grid.appendChild(buildCard(shell, bonus, root));
+    const affordable: BonusOption[] = [];
+    for (const bonus of bonuses) {
+      const card = buildCard(shell, bonus, root, st);
+      grid.appendChild(card);
+      if (isAffordable(shell, bonus)) affordable.push(bonus);
+    }
     body.appendChild(grid);
+    // Initialize or restore focus index
+    if (affordable.length > 0) {
+      if (st.focusIndex < 0) st.focusIndex = 0;
+      else st.focusIndex = Math.min(st.focusIndex, affordable.length - 1);
+      applyFocusClass(root, bonuses, affordable, st.focusIndex);
+    } else {
+      st.focusIndex = -1;
+    }
   };
+
   renderGrid();
   root.appendChild(buildBetBar(shell, renderGrid)); // thin bottom footer, only as tall as the pill
-  return root;
+
+  /** Step the bet by `dir` and re-render the grid (live prices + affordability) when it changed.
+   *  Shared by the keyboard bet keys (the footer ± buttons keep their own copy). */
+  const stepBetBy = (dir: 1 | -1): void => {
+    const next = stepBet(shell.state, dir);
+    if (next === shell.state.bet) return;
+    shell.state.bet = next; shell.emit('betChange', next); shell.render();
+    renderGrid();
+  };
+
+  /** Keyboard handler for both browse and confirm phases. */
+  const onKey = (e: KeyboardEvent): boolean => {
+    const affordable = bonuses.filter((b) => isAffordable(shell, b));
+
+    // ── Confirm phase ──
+    if (st.confirmBonus) {
+      switch (e.code) {
+        case 'Enter':
+        case 'Space': {
+          const bonus = st.confirmBonus;
+          if (!isAffordable(shell, bonus)) return true;
+          if (bonus.type === 'feature') shell.activateFeature(bonus);
+          else shell.emit('buyBonusSelect', { id: bonus.id });
+          shell.closeModal();
+          return true;
+        }
+        case 'Escape':
+          // Remove the confirm dialog, return to browse
+          closeConfirm(root, st);
+          return true;
+        default:
+          return false;
+      }
+    }
+
+    // ── Browse phase ──
+    const last = affordable.length - 1;
+    const mobile = shell.layout === 'mobile';
+
+    // Bet stepping mirrors the bar's keys (Shift+↑/↓, Shift+=/-, Numpad ±). Checked BEFORE arrow
+    // navigation so a bare arrow still moves card focus while a Shift+arrow changes the bet.
+    const bet = betDir(e);
+    if (bet !== null) { stepBetBy(bet); return true; }
+
+    // Determine navigation direction from key code + layout (mobile uses vertical arrows)
+    const fwdKey = e.code === 'ArrowRight' || (mobile && e.code === 'ArrowDown');
+    const bwdKey = e.code === 'ArrowLeft' || (mobile && e.code === 'ArrowUp');
+
+    if (fwdKey) {
+      if (last < 0) return true;
+      if (st.focusIndex < last) {
+        st.focusIndex++;
+        applyFocusClass(root, bonuses, affordable, st.focusIndex);
+      }
+      return true;
+    }
+    if (bwdKey) {
+      if (last < 0) return true;
+      if (st.focusIndex > 0) {
+        st.focusIndex--;
+        applyFocusClass(root, bonuses, affordable, st.focusIndex);
+      }
+      return true;
+    }
+
+    switch (e.code) {
+      case 'Enter':
+      case 'Space':
+        if (last < 0 || st.focusIndex < 0) return true;
+        {
+          const bonus = affordable[st.focusIndex];
+          openConfirm(shell, bonus, root, st);
+        }
+        return true;
+      // Bare =/- also step the bet (the Shift+=/- and Numpad variants are handled by betDir above).
+      case 'Equal':
+        stepBetBy(1);
+        return true;
+      case 'Minus':
+        stepBetBy(-1);
+        return true;
+      case 'Escape':
+        shell.closeModal();
+        return true;
+      default:
+        return false;
+    }
+  };
+
+  return { root, onKey };
+}
+
+/** Apply a CSS keyboard-focus class to the currently focused affordable card. */
+function applyFocusClass(overlay: HTMLElement, bonuses: BonusOption[], affordable: BonusOption[], focusIndex: number): void {
+  for (const b of bonuses) {
+    const card = overlay.querySelector(`[data-ge="bonus-card-${b.id}"]`) as HTMLElement | null;
+    if (!card) continue;
+    card.classList.remove('ge-bonus-card--kbd-focus');
+  }
+  const focused = affordable[focusIndex];
+  if (!focused) return;
+  const card = overlay.querySelector(`[data-ge="bonus-card-${focused.id}"]`) as HTMLElement | null;
+  if (card) card.classList.add('ge-bonus-card--kbd-focus');
+}
+
+/** Open the confirm dialog for the given bonus and track it in overlay state. */
+function openConfirm(shell: GameShell, bonus: BonusOption, overlay: HTMLElement, st: OverlayState): void {
+  closeConfirm(overlay, st); // remove any existing confirm
+  st.confirmBonus = bonus;
+  overlay.appendChild(buildConfirm(shell, bonus, overlay, st));
+  shell.fitModals();
+}
+
+/** Remove the confirm dialog and clear the overlay state. */
+function closeConfirm(overlay: HTMLElement, st: OverlayState): void {
+  // The confirm dialog is a .ge-sheet with data-ge="bonus-confirm" appended directly to overlay.
+  const sheet = overlay.querySelector('[data-ge="bonus-confirm"]') as HTMLElement | null;
+  if (sheet) sheet.remove();
+  st.confirmBonus = undefined;
 }
 
 /** Bet control — a compact −/+ pill around the live stake, in a thin footer at the screen bottom.
@@ -63,7 +208,7 @@ function stepButton(ge: string, name: IconName): HTMLButtonElement {
 
 /** A grid card: title → thumbnail → description → volatility → price → full-bleed CTA.
  *  Clicking (when affordable) opens the confirmation modal. */
-function buildCard(shell: GameShell, bonus: BonusOption, overlay: HTMLElement): HTMLElement {
+function buildCard(shell: GameShell, bonus: BonusOption, overlay: HTMLElement, st: OverlayState): HTMLElement {
   const accent = effectiveAccent(bonus);
   const card = document.createElement('div');
   card.className = 'ge-bonus-card'; card.dataset.ge = `bonus-card-${bonus.id}`;
@@ -75,8 +220,7 @@ function buildCard(shell: GameShell, bonus: BonusOption, overlay: HTMLElement):
   // affordability at click time, so it's a safe no-op when the option can't be bought.
   const select = (): void => {
     if (!isAffordable(shell, bonus)) return;
-    overlay.appendChild(buildConfirm(shell, bonus, overlay));
-    shell.fitModals();
+    openConfirm(shell, bonus, overlay, st);
   };
 
   // Game-supplied card UI: the shell keeps the wrapper (grid sizing + accent vars) and runs the
@@ -123,9 +267,9 @@ function cardBody(shell: GameShell, bonus: BonusOption): HTMLElement {
 
 /** Confirmation modal — the shared card chrome (accent title heading, no ✕) with a bonus
  *  preview body and a full-bleed Cancel + action footer. */
-function buildConfirm(shell: GameShell, bonus: BonusOption, overlay: HTMLElement): HTMLElement {
+function buildConfirm(shell: GameShell, bonus: BonusOption, overlay: HTMLElement, st: OverlayState): HTMLElement {
   const accent = effectiveAccent(bonus);
-  const ui = createCardModal({ ge: 'bonus-confirm', title: bonus.title, accent, onClose: () => ui.root.remove() });
+  const ui = createCardModal({ ge: 'bonus-confirm', title: bonus.title, accent, onClose: () => { closeConfirm(overlay, st); } });
 
   const price = bonus.priceMultiplier * shell.state.bet;
   const preview = document.createElement('div'); preview.className = 'ge-confirm-preview';
@@ -140,7 +284,7 @@ function buildConfirm(shell: GameShell, bonus: BonusOption, overlay: HTMLElement
   const cancel = document.createElement('button');
   cancel.className = 'ge-modal-btn ge-modal-btn--ghost'; cancel.dataset.ge = 'bonus-confirm-cancel';
   cancel.textContent = shell.t('Cancel');
-  cancel.addEventListener('click', () => ui.root.remove());
+  cancel.addEventListener('click', () => closeConfirm(overlay, st));
   const buy = document.createElement('button');
   buy.className = 'ge-modal-btn ge-modal-btn--accent'; buy.dataset.ge = 'bonus-confirm-buy';
   buy.textContent = shell.t(actionLabel(bonus));
@@ -151,8 +295,7 @@ function buildConfirm(shell: GameShell, bonus: BonusOption, overlay: HTMLElement
     if (!isAffordable(shell, bonus)) return;
     if (bonus.type === 'feature') shell.activateFeature(bonus);
     else shell.emit('buyBonusSelect', { id: bonus.id });
-    ui.root.remove();
-    overlay.remove();
+    shell.closeModal();
   });
   actions.append(cancel, buy);
   ui.card.appendChild(actions);