@energy8platform/platform-core 0.25.3 → 0.26.0

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;

package/src/shell/components/pickers.ts

@@ -15,46 +15,101 @@ interface SheetOpts {
   columns: number | { wide: number; mobile: number };
   confirmLabel: string;
   onConfirm: (id: string) => void;
+  /** Called to dismiss the picker (should invoke shell.closeModal()). */
+  onClose: () => void;
+}
+
+/** Result of buildSheet — the root DOM element plus a keyboard handler. */
+interface Sheet {
+  root: HTMLElement;
+  /** Route keydown events here. Returns true if the event was consumed. */
+  onKey: (e: KeyboardEvent) => boolean;
 }
 
 /** A centred picker (chips grid + accent Confirm) on the shared card modal. */
-function buildSheet(opts: SheetOpts): HTMLElement {
-  const ui = createCardModal({ ge: opts.ge, title: opts.title, onClose: () => ui.root.remove() });
+function buildSheet(opts: SheetOpts): Sheet {
+  const ui = createCardModal({ ge: opts.ge, title: opts.title, onClose: () => opts.onClose() });
 
   const grid = document.createElement('div'); grid.className = 'ge-sheet-grid';
   const cols = typeof opts.columns === 'number' ? { wide: opts.columns, mobile: opts.columns } : opts.columns;
   grid.style.setProperty('--cols', String(cols.wide));
   grid.style.setProperty('--cols-m', String(cols.mobile));
   let selected = opts.selected;
+  let focusIndex = opts.choices.findIndex((c) => c.id === selected);
+  if (focusIndex < 0) focusIndex = 0;
   const chips: HTMLButtonElement[] = [];
-  for (const c of opts.choices) {
+
+  /** Update chip visuals to reflect the current selected/focused index. */
+  function setHighlight(newIndex: number): void {
+    focusIndex = newIndex;
+    selected = opts.choices[focusIndex].id;
+    for (let i = 0; i < chips.length; i++) {
+      chips[i].classList.toggle('ge-on', i === focusIndex);
+    }
+  }
+
+  for (let i = 0; i < opts.choices.length; i++) {
+    const c = opts.choices[i];
     const chip = document.createElement('button');
-    chip.className = 'ge-chip' + (c.id === selected ? ' ge-on' : '');
+    chip.className = 'ge-chip' + (i === focusIndex ? ' ge-on' : '');
     chip.dataset.id = c.id; chip.textContent = c.label;
+    const idx = i; // capture for closure
     chip.addEventListener('click', () => {
-      selected = c.id;
-      for (const x of chips) x.classList.toggle('ge-on', x.dataset.id === selected);
+      setHighlight(idx);
     });
     chips.push(chip); grid.appendChild(chip);
   }
   ui.body.appendChild(grid);
 
+  function doConfirm(): void {
+    opts.onConfirm(selected);
+    opts.onClose();
+  }
+
   // Single full-bleed Confirm; dismissal is the ✕ (top-right). No Cancel button.
   const confirm = document.createElement('button');
   confirm.className = 'ge-modal-btn ge-modal-btn--accent'; confirm.dataset.ge = 'sheet-confirm';
   confirm.textContent = opts.confirmLabel;
-  confirm.addEventListener('click', () => { opts.onConfirm(selected); ui.root.remove(); });
+  confirm.addEventListener('click', doConfirm);
   ui.card.appendChild(confirm);
 
-  return ui.root;
+  function onKey(e: KeyboardEvent): boolean {
+    const last = opts.choices.length - 1;
+    switch (e.code) {
+      case 'ArrowRight':
+      case 'ArrowDown':
+      case 'Equal':         // + on most keyboards
+      case 'NumpadAdd':
+        if (focusIndex < last) setHighlight(focusIndex + 1);
+        return true;
+      case 'ArrowLeft':
+      case 'ArrowUp':
+      case 'Minus':
+      case 'NumpadSubtract':
+        if (focusIndex > 0) setHighlight(focusIndex - 1);
+        return true;
+      case 'Enter':
+      case 'Space':
+        doConfirm();
+        return true;
+      case 'Escape':
+        opts.onClose();
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  return { root: ui.root, onKey };
 }
 
 /** Bet picker — all available bets as chips (6 per row, 3 on mobile), accent Confirm applies it. */
-export function openBetModal(shell: GameShell): HTMLElement {
+export function openBetModal(shell: GameShell): { root: HTMLElement; onKey: (e: KeyboardEvent) => boolean } {
   return buildSheet({
     ge: 'bet-modal', title: shell.t('Bet'), columns: { wide: 6, mobile: 3 }, confirmLabel: shell.t('Confirm'),
     choices: shell.state.availableBets.map((b) => ({ id: String(b), label: formatCurrency(b, shell.config.currency) })),
     selected: String(shell.state.bet),
+    onClose: () => shell.closeModal(),
     onConfirm: (id) => {
       const v = Number(id);
       if (v !== shell.state.bet) { shell.state.bet = v; shell.emit('betChange', v); }
@@ -76,13 +131,14 @@ function autoplayCounts(maxCount?: number): number[] {
 }
 
 /** Autoplay picker — spin counts (incl. ∞ unless a maxCount caps them); Confirm starts autoplay. */
-export function openAutoplayModal(shell: GameShell): HTMLElement {
+export function openAutoplayModal(shell: GameShell): { root: HTMLElement; onKey: (e: KeyboardEvent) => boolean } {
   const maxCount = shell.config.features.autoplay?.maxCount;
   const counts = autoplayCounts(maxCount);
   return buildSheet({
     ge: 'autoplay-modal', title: shell.t('Autoplay'), columns: 3, confirmLabel: shell.t('Start'),
     choices: counts.map((n) => ({ id: String(n), label: Number.isFinite(n) ? String(n) : '∞' })),
     selected: String(shell.state.autoplay.remaining || counts[0]),
+    onClose: () => shell.closeModal(),
     onConfirm: (id) => {
       let remaining = Number(id); // "Infinity" → Infinity
       if (maxCount != null) remaining = Math.min(remaining, maxCount); // defensive cap

package/src/shell/components/primitives.ts

@@ -52,8 +52,9 @@ export interface OverlayOpts {
   onBack?: () => void;
 }
 
-/** Full-screen overlay. Returns { root, body }; append content to body. */
-export function createOverlay(opts: OverlayOpts): { root: HTMLDivElement; body: HTMLDivElement } {
+/** Full-screen overlay. Returns { root, body, scroll }; append content to body.
+ *  The `scroll` element is the scrollable container (overflow-y: auto). */
+export function createOverlay(opts: OverlayOpts): { root: HTMLDivElement; body: HTMLDivElement; scroll: HTMLDivElement } {
   const root = document.createElement('div');
   root.className = 'ge-shell-overlay';
   const head = document.createElement('div');
@@ -80,5 +81,5 @@ export function createOverlay(opts: OverlayOpts): { root: HTMLDivElement; body:
   const body = document.createElement('div'); body.className = 'ge-ov-body';
   scroll.appendChild(body);
   root.append(head, scroll);
-  return { root, body };
+  return { root, body, scroll };
 }

package/src/shell/i18n.ts

@@ -1,3 +1,5 @@
+import { LOCALES } from './locales';
+
 // Social-casino language. English is the source (and, for now, the only) language; `socialize`
 // rewrites the restricted gambling vocabulary into social-safe phrasing while preserving case.
 //
@@ -71,3 +73,24 @@ export function socialize(text: string): string {
     return repl == null ? m : applyCase(m, repl);
   });
 }
+
+export type Lang = 'de'|'en'|'es'|'fi'|'fr'|'hi'|'id'|'ja'|'ko'|'pl'|'pt'|'ru'|'tr'|'vi'|'zh'|'da';
+export const LANGS: readonly Lang[] = ['de','en','es','fi','fr','hi','id','ja','ko','pl','pt','ru','tr','vi','zh','da'];
+const LANG_SET = new Set<string>(LANGS);
+
+export function normalizeLang(code: string | null | undefined): Lang {
+  const base = (code ?? '').toLowerCase().split(/[-_]/)[0];
+  return (LANG_SET.has(base) ? base : 'en') as Lang;
+}
+
+export interface I18nOptions { language: string; isSocial?: boolean; messages?: Partial<Record<Lang, Record<string, string>>>; }
+export interface I18n { readonly lang: Lang; t(src: string): string; }
+
+export function createI18n(opts: I18nOptions): I18n {
+  const lang = normalizeLang(opts.language);
+  const t = (src: string): string => {
+    if (lang === 'en') return opts.isSocial ? socialize(src) : src;
+    return opts.messages?.[lang]?.[src] ?? LOCALES[lang]?.[src] ?? src;
+  };
+  return { lang, t };
+}

package/src/shell/index.ts

@@ -18,4 +18,5 @@ export function removeGameShell(): Promise<void> {
 }
 
 export { GameShell };
-export { socialize } from './i18n';
+export { socialize, createI18n, normalizeLang } from './i18n';
+export type { Lang, I18n, I18nOptions } from './i18n';

package/src/shell/keyboard.ts

@@ -0,0 +1,229 @@
+import type { ShellState } from './types';
+
+export interface KeyboardHost {
+  readonly state: ShellState;
+  readonly hotkeysEnabled: boolean;   // features.hotkeys !== false
+  readonly spacebarEnabled: boolean;  // features.spacebar !== false
+  readonly turboLevels: number;       // features.turbo
+  readonly autoplayEnabled: boolean;  // features.autoplay != null
+  readonly buyBonusEnabled: boolean;  // features.buyBonus !== false
+  hasOpenLayer(): boolean;
+  routeToLayer(e: KeyboardEvent): boolean; // give the key to the top layer's onKey; true if consumed
+  spin(): void;
+  stepBet(dir: 1 | -1): void;
+  toggleAutoplay(): void;
+  cycleTurbo(): void;
+  openBuyBonus(): void;
+  openInfo(): void;
+  openMenu(): void;
+  toggleMute(): void;
+  closeLayer(): void;
+}
+
+// Bet key detection: bet-up needs Shift for arrow/equal, NumpadAdd is bare; same logic for down.
+// Exported so overlays with their own bet stepper (Buy bonus) honour the SAME keys as the bar.
+export function betDir(e: KeyboardEvent): 1 | -1 | null {
+  if (e.code === 'ArrowUp'   && e.shiftKey) return 1;
+  if (e.code === 'Equal'     && e.shiftKey) return 1;
+  if (e.code === 'NumpadAdd')               return 1;
+  if (e.code === 'ArrowDown' && e.shiftKey) return -1;
+  if (e.code === 'Minus'     && e.shiftKey) return -1;
+  if (e.code === 'NumpadSubtract')          return -1;
+  return null;
+}
+
+export class KeyboardController {
+  private host: KeyboardHost;
+  private doc: Document;
+  private spaceHeld = false;
+  private holdTimer: ReturnType<typeof setTimeout> | null = null;
+  // Bet hold-repeat state
+  private betHeldCode: string | null = null;
+  private betTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(host: KeyboardHost, doc?: Document) {
+    this.host = host;
+    this.doc = doc ?? (typeof document !== 'undefined' ? document : (null as unknown as Document));
+  }
+
+  private isSpinAllowed(): boolean {
+    const h = this.host;
+    const s = h.state;
+    return (
+      h.spacebarEnabled &&
+      h.hotkeysEnabled &&
+      !h.hasOpenLayer() &&
+      s.mode === 'base' &&
+      !s.autoplay.active
+    );
+  }
+
+  private isBetAllowed(): boolean {
+    const h = this.host;
+    const s = h.state;
+    return (
+      h.hotkeysEnabled &&
+      !h.hasOpenLayer() &&
+      s.mode === 'base' &&
+      !s.busy
+    );
+  }
+
+  private clearBetTimer(): void {
+    if (this.betTimer !== null) {
+      clearTimeout(this.betTimer);
+      this.betTimer = null;
+    }
+  }
+
+  private startBetRepeat(dir: 1 | -1, elapsed: number): void {
+    // elapsed is ms already spent holding; use it to accelerate toward 45ms floor.
+    // Start at 90ms, decrease ~1ms per 10ms held after the first repeat, floor at 45ms.
+    const interval = Math.max(45, 90 - Math.floor(elapsed / 10));
+    this.betTimer = setTimeout(() => {
+      this.betTimer = null;
+      if (this.betHeldCode !== null && this.isBetAllowed()) {
+        this.host.stepBet(dir);
+        this.startBetRepeat(dir, elapsed + interval);
+      }
+    }, interval);
+  }
+
+  private onKeyDown = (e: KeyboardEvent): void => {
+    const target = e.target as HTMLElement | null;
+    // Editable element guard — never intercept keyboard input
+    if (target && (target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName))) return;
+
+    // For Space: claim preventDefault early (before layer/mode/busy bail) so the browser's
+    // native "Space activates focused button" can't re-fire a shell control and flicker a modal.
+    if (e.code === 'Space' && !e.repeat) {
+      if (!this.host.spacebarEnabled || !this.host.hotkeysEnabled) return;
+      e.preventDefault();
+      if (this.host.hasOpenLayer()) {
+        this.host.routeToLayer(e);
+        return;
+      }
+      const s = this.host.state;
+      if (s.mode !== 'base' || s.busy || s.autoplay.active) return;
+      this.spaceHeld = true;
+      this.host.spin();
+      return;
+    }
+
+    // Bet step keys (Shift+arrows, Shift+=/-, NumpadAdd/Subtract) — non-repeat only
+    if (!e.repeat) {
+      const dir = betDir(e);
+      if (dir !== null && this.isBetAllowed()) {
+        this.betHeldCode = e.code;
+        this.host.stepBet(dir);
+        // First repeat after 350ms initial delay
+        this.clearBetTimer();
+        const capturedDir = dir;
+        this.betTimer = setTimeout(() => {
+          this.betTimer = null;
+          if (this.betHeldCode !== null && this.isBetAllowed()) {
+            this.host.stepBet(capturedDir);
+            this.startBetRepeat(capturedDir, 350);
+          }
+        }, 350);
+        return;
+      }
+    }
+
+    // Non-Space keys: give the open layer first refusal. If it consumes the key, done; Escape closes
+    // it. Anything the layer does NOT consume falls through to the chrome hotkeys below — so the
+    // Settings/Info pages still honour Shift+I (Game info), Shift+M (sound), Shift+S, etc.
+    if (this.host.hasOpenLayer()) {
+      const consumed = this.host.routeToLayer(e);
+      if (consumed) return;
+      if (e.code === 'Escape') { this.host.closeLayer(); return; }
+      // not consumed → fall through to the Shift+letter chrome hotkeys
+    }
+
+    // Shift+letter bar hotkeys — fire when no layer is open, OR when an open layer left the key
+    // unconsumed (see fall-through above); gated on hotkeys being enabled.
+    if (!e.repeat && e.shiftKey && this.host.hotkeysEnabled) {
+      const h = this.host;
+      const s = h.state;
+      switch (e.code) {
+        case 'KeyA':
+          if (h.autoplayEnabled && !s.replay) { h.toggleAutoplay(); return; }
+          break;
+        case 'KeyT':
+          if (h.turboLevels > 0 && !s.replay) { h.cycleTurbo(); return; }
+          break;
+        case 'KeyB':
+          if (h.buyBonusEnabled && s.mode === 'base' && !s.replay) { h.openBuyBonus(); return; }
+          break;
+        case 'KeyI':
+          h.openInfo(); return;
+        case 'KeyS':
+          h.openMenu(); return;
+        case 'KeyM':
+          h.toggleMute(); return;
+      }
+    }
+  };
+
+  private onKeyUp = (e: KeyboardEvent): void => {
+    if (e.code === 'Space') {
+      this.spaceHeld = false;
+      this.clearHoldTimer();
+    }
+    // Stop bet repeat on key release
+    if (e.code === this.betHeldCode) {
+      this.betHeldCode = null;
+      this.clearBetTimer();
+    }
+  };
+
+  private onBlur = (): void => {
+    // Window blur — stop bet repeat AND hold-to-spin (same as releasing both keys)
+    this.betHeldCode = null;
+    this.clearBetTimer();
+    this.spaceHeld = false;
+    this.clearHoldTimer();
+  };
+
+  private clearHoldTimer(): void {
+    if (this.holdTimer !== null) {
+      clearTimeout(this.holdTimer);
+      this.holdTimer = null;
+    }
+  }
+
+  attach(): void {
+    this.doc.addEventListener('keydown', this.onKeyDown);
+    this.doc.addEventListener('keyup', this.onKeyUp);
+    // Use window if available for blur events
+    if (typeof window !== 'undefined') {
+      window.addEventListener('blur', this.onBlur);
+    }
+  }
+
+  detach(): void {
+    this.doc.removeEventListener('keydown', this.onKeyDown);
+    this.doc.removeEventListener('keyup', this.onKeyUp);
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('blur', this.onBlur);
+    }
+    this.spaceHeld = false;
+    this.clearHoldTimer();
+    this.betHeldCode = null;
+    this.clearBetTimer();
+  }
+
+  notifyBusyChanged(busy: boolean): void {
+    if (busy) return;
+    if (!this.spaceHeld) return;
+    if (!this.isSpinAllowed()) return;
+    // Schedule the next spin after the 120 ms floor (gap between completion and next spin).
+    this.clearHoldTimer();
+    this.holdTimer = setTimeout(() => {
+      this.holdTimer = null;
+      if (this.spaceHeld && this.isSpinAllowed()) {
+        this.host.spin();
+      }
+    }, 120);
+  }
+}