@energy8platform/platform-core 0.25.4 → 0.26.1

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)
@@ -161,41 +206,32 @@ export class GameShell extends EventEmitter<ShellEvents> {
     }
   }
 
-  /** 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 (re-renders the bar; reopen overlays to refresh them). */
-  setSocial(isSocial: boolean): void { this.config.isSocial = isSocial; this.render(); }
+  /** 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();
+  }
+
+  /** 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 {
@@ -236,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
@@ -245,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.
@@ -253,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();
   }
 
@@ -307,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;
@@ -326,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,175 @@ 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));
+    // Card count drives the width-fit clamp in CSS (each card is 18em; N cards must fit the frame
+    // width), so the row scales to the available width instead of overflowing into an X-scroll.
+    grid.style.setProperty('--ge-bb-n', String(bonuses.length));
+    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 +211,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 +223,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 +270,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 +287,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 +298,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);

package/src/shell/components/GameInfo.ts

@@ -4,17 +4,32 @@ import { createOverlay, twoLine } from './primitives';
 import { icon } from './icons';
 import { PACKAGE_VERSION } from '../version';
 
+/** Default order key for the auto-injected hotkeys section: just after `controls` (-1). */
+const HOTKEYS_DEFAULT_ORDER = -0.5;
+
 const SVG_NS = 'http://www.w3.org/2000/svg';
 
-export function openGameInfoModal(shell: GameShell): HTMLElement {
-  const { root, body } = createOverlay({
+/** Result of openGameInfoModal — the overlay root element plus a keyboard handler. */
+export interface GameInfoModal {
+  root: HTMLElement;
+  onKey: (e: KeyboardEvent) => boolean;
+}
+
+export function openGameInfoModal(shell: GameShell): GameInfoModal {
+  const { root, body, scroll } = createOverlay({
     title: shell.t('Game info'),
     onClose: () => root.remove(),
     onBack: () => { root.remove(); shell.openSettings(); },
   });
   root.dataset.ge = 'info-modal';
 
-  const sections = shell.config.gameInfo.sections ?? [];
+  const rawSections = shell.config.gameInfo.sections ?? [];
+  // Auto-inject a hotkeys section unless the game already provides one or features.hotkeys === false.
+  const sectionsWithHotkeys: GameInfoSection[] = [...rawSections];
+  if (shell.config.features.hotkeys !== false && !rawSections.some((s) => s.type === 'hotkeys')) {
+    sectionsWithHotkeys.push({ type: 'hotkeys', order: HOTKEYS_DEFAULT_ORDER });
+  }
+  const sections = sectionsWithHotkeys;
   // Default placement: modes first, controls second, the rest in declaration order.
   // An explicit `order` overrides; ties keep declaration order (stable).
   const base = (s: GameInfoSection, i: number): number =>
@@ -25,7 +40,26 @@ export function openGameInfoModal(shell: GameShell): HTMLElement {
     .forEach(({ s }) => body.appendChild(renderSection(shell, s)));
 
   body.appendChild(versionFooter(shell));
-  return root;
+
+  const LINE = 60;
+  const PAGE = (): number => Math.floor(scroll.clientHeight * 0.9) || Math.floor(540 * 0.9);
+  const onKey = (e: KeyboardEvent): boolean => {
+    switch (e.code) {
+      case 'ArrowDown':  scroll.scrollTop += LINE;                             return true;
+      case 'ArrowUp':    scroll.scrollTop = Math.max(0, scroll.scrollTop - LINE); return true;
+      case 'PageDown':   scroll.scrollTop += PAGE();                           return true;
+      case 'PageUp':     scroll.scrollTop = Math.max(0, scroll.scrollTop - PAGE()); return true;
+      case 'Space':
+        if (e.shiftKey) { scroll.scrollTop = Math.max(0, scroll.scrollTop - PAGE()); }
+        else            { scroll.scrollTop += PAGE(); }
+        return true;
+      case 'Home':       scroll.scrollTop = 0;                                 return true;
+      case 'End':        scroll.scrollTop = scroll.scrollHeight - scroll.clientHeight; return true;
+      default:           return false;
+    }
+  };
+
+  return { root, onKey };
 }
 
 /** A muted version stamp pinned to the bottom of the game-info modal:
@@ -43,9 +77,11 @@ function renderSection(shell: GameShell, s: GameInfoSection): HTMLElement {
   switch (s.type) {
     case 'modes': return sectionModes(shell, s.modes, sec('info-modes', s.title, shell.t('Modes')));
     case 'controls': return sectionControls(shell, sec('info-controls', s.title, shell.t('Controls')));
+    case 'hotkeys': return sectionHotkeys(shell, sec('info-hotkeys', s.title, shell.t('Hotkeys')));
     case 'paytable': return sectionPaytable(s.rows, sec('info-paytable', s.title, shell.t('Paytable')));
     case 'wins': return sectionWins(s, sec('info-wins', s.title, shell.t(winFallbackTitle(s.kind))));
-    case 'custom': return sectionCustom(s, sec('info-custom', s.title, ''));
+    // Translate the heading (e.g. the host-built DISCLAIMER title); the body stays verbatim.
+    case 'custom': return sectionCustom(s, sec('info-custom', s.title != null ? shell.t(s.title) : undefined, ''));
   }
 }
 
@@ -123,6 +159,69 @@ function ctlBlock(shell: GameShell, label: string, rows: CtlRow[]): HTMLElement
   return block;
 }
 
+// ── hotkeys (keycap chips → localized action name) ────────────────────────────
+type HkRow = { chips: string[]; name: string; on: boolean };
+
+function sectionHotkeys(shell: GameShell, el: HTMLElement): HTMLElement {
+  const { features } = shell.config;
+
+  /** Render one or more key names as keycap chips joined by " / ". */
+  const chips = (...keys: string[]): string =>
+    keys.map((k) => `<span class="ge-gi-hk-chip">${k}</span>`).join('<span class="ge-gi-hk-sep"> / </span>');
+
+  const rows: HkRow[] = [
+    { chips: ['Space'],                        name: 'Spin',      on: true },
+    { chips: ['Shift', '↑', 'Shift', '='],     name: 'Raise bet', on: true },
+    { chips: ['Shift', '↓', 'Shift', '-'],     name: 'Lower bet', on: true },
+    { chips: ['Shift', 'A'],                   name: 'Autoplay',  on: features.autoplay != null },
+    { chips: ['Shift', 'T'],                   name: 'Turbo',     on: features.turbo > 0 },
+    { chips: ['Shift', 'B'],                   name: 'Buy bonus', on: features.buyBonus !== false },
+    { chips: ['Shift', 'I'],                   name: 'Game info', on: true },
+    { chips: ['Shift', 'S'],                   name: 'Menu',      on: true },
+    { chips: ['Shift', 'M'],                   name: 'Mute',      on: true },
+    { chips: ['←', '→'],                       name: 'Navigate',  on: true },
+    { chips: ['Enter'],                        name: 'Confirm',   on: true },
+    { chips: ['Esc'],                          name: 'Close',     on: true },
+  ];
+
+  const block = document.createElement('div');
+  block.className = 'ge-gi-hk-block';
+
+  for (const r of rows.filter((x) => x.on)) {
+    const row = document.createElement('div');
+    row.className = 'ge-gi-hk';
+
+    // Build the chips column
+    const chipsEl = document.createElement('div');
+    chipsEl.className = 'ge-gi-hk-chips';
+
+    if (r.name === 'Raise bet' || r.name === 'Lower bet') {
+      // Two combos separated by " / ": Shift+↑ / Shift+=  and  Shift+↓ / Shift+-
+      const [k1, k2, k3, k4] = r.chips;
+      chipsEl.innerHTML =
+        `<span class="ge-gi-hk-combo">${chips(k1, k2)}</span>` +
+        `<span class="ge-gi-hk-sep2"> / </span>` +
+        `<span class="ge-gi-hk-combo">${chips(k3, k4)}</span>`;
+    } else if (r.chips.length > 1) {
+      // Chord: Shift + X
+      chipsEl.innerHTML = `<span class="ge-gi-hk-combo">${chips(...r.chips)}</span>`;
+    } else {
+      chipsEl.innerHTML = chips(...r.chips);
+    }
+
+    const tx = document.createElement('div');
+    tx.className = 'ge-gi-hk-tx';
+    tx.textContent = shell.t(r.name);
+
+    row.appendChild(chipsEl);
+    row.appendChild(tx);
+    block.appendChild(row);
+  }
+
+  el.appendChild(block);
+  return el;
+}
+
 // ── paytable (cards — image on top, name, then win tiers "<count> x<mult>") ────
 function sectionPaytable(rows: PaytableRow[], el: HTMLElement): HTMLElement {
   const grid = document.createElement('div'); grid.className = 'ge-gi-pt-grid';

package/src/shell/components/Settings.ts

@@ -6,22 +6,21 @@ export function openSettingsModal(shell: GameShell): HTMLElement {
   const { root, body } = createOverlay({ title: shell.t('Settings'), onClose: () => root.remove() });
   root.dataset.ge = 'settings-modal';
 
-  // Sound on/off (starts on) — full-width row with a speaker icon button
+  // Sound on/off — backed by the shell's shared `soundOn` state so this toggle and the Shift+M
+  // hotkey stay in sync; `setSound` emits `settingChange({ key: 'sound' })` and refreshes the icon.
   const sound = (() => {
-    let on = true;
     const btn = document.createElement('button');
-    btn.className = 'ge-snd ge-active'; btn.dataset.ge = 'setting-sound';
-    btn.setAttribute('aria-label', 'Sound');
-    const paint = () => {
+    btn.className = 'ge-snd'; btn.dataset.ge = 'setting-sound';
+    btn.setAttribute('aria-label', shell.t('Sound'));
+    const paint = (on: boolean) => {
       btn.innerHTML = icon(on ? 'soundOn' : 'soundOff');
       btn.classList.toggle('ge-active', on);
       btn.setAttribute('aria-pressed', String(on));
     };
-    paint();
-    btn.addEventListener('click', () => {
-      on = !on; paint();
-      shell.emit('settingChange', { key: 'sound', value: on });
-    });
+    paint(shell.soundOn);
+    btn.addEventListener('click', () => shell.setSound(!shell.soundOn));
+    // Live-update the icon when sound changes from here OR via Shift+M (shell clears on close).
+    shell.setSoundRefresh(paint);
     const row = document.createElement('div'); row.className = 'ge-ov-row';
     row.innerHTML = `<span class="ge-grow">${shell.t('Sound')}</span>`; row.appendChild(btn);
     return row;