@energy8platform/shell 0.4.1 → 0.6.0

package/dist/html.d.ts

@@ -16,7 +16,14 @@ declare class EventEmitter<TEvents extends {}> {
     removeAllListeners(event?: keyof TEvents): this;
 }
 
-type ShellMode = 'base' | 'freeSpins' | 'replay';
+/** `freeSpins` and `bonus` are the SAME bar layout (host-driven hero + Total Win); `freeSpins` is
+ *  kept as a back-compat alias for the common case (its readout is derived current/total), while
+ *  `bonus` pairs with `setBonus()` to show a game-supplied label + value (adventure, hold-and-spin,
+ *  respins — anything that isn't a plain free-spins counter). */
+type ShellMode = 'base' | 'bonus' | 'freeSpins' | 'replay';
+/** The three independent volume sliders shown in the Settings overlay. */
+type VolumeKey = 'master' | 'music' | 'sfx';
+type VolumeLevels = Record<VolumeKey, number>;
 interface CurrencyConfig {
     symbol: string;
     position: 'left' | 'right';
@@ -205,6 +212,19 @@ interface FreeSpinsState {
     total: number;
     totalWin: number;
 }
+/** A game-supplied bonus readout for the bar hero, set via `setBonus()`. Generalizes the
+ *  free-spins counter: the shell renders `label` (localized via the shell translator, so a game
+ *  i18n entry for it is honoured) + `value` (a pre-formatted string, shown verbatim — "2 / 10",
+ *  "3", "×5", "7 coins") + the Total Win accumulator. The shell stays free of any per-game bonus
+ *  concept — the label/value semantics live in the game/host. */
+interface BonusReadout {
+    /** Bar label, e.g. 'Free spins' | 'Adventure' | 'Hold & Spin'. Run through the shell translator. */
+    label: string;
+    /** Pre-formatted counter value shown verbatim (NOT translated). */
+    value: string;
+    /** Cumulative bonus win for the Total Win readout. */
+    totalWin: number;
+}
 /** One footer button of a generic modal. Clicking it runs `on` (if any), then closes the modal. */
 interface ModalAction {
     title: string;
@@ -265,9 +285,13 @@ interface ShellConfig {
      *  opening the built-in buy-bonus overlay (e.g. the game shows its own bonus UI). The button
      *  is shown whenever this OR `features.buyBonus` is set. */
     onBonusBuy?: () => void;
+    /** Initial Settings-overlay volume slider positions (each 0..1, defaults to 1 = 100%). The shell
+     *  keeps them stateful across opens; read/update at runtime via `shell.getVolume()` /
+     *  `shell.setVolume()`, and listen to `settingChange` ({ key: 'master'|'music'|'sfx' }) to apply. */
+    volumes?: Partial<VolumeLevels>;
 }
 /** ShellConfig after the controller applies defaults (version, isSocial, replay, theme). No mount. */
-type ResolvedShellConfig = Required<Pick<ShellConfig, 'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>> & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy'>;
+type ResolvedShellConfig = Required<Pick<ShellConfig, 'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>> & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes'>;
 interface ShellState {
     mode: ShellMode;
     /** Sticky replay marker — true for a historical-round replay, regardless of the current
@@ -283,9 +307,18 @@ interface ShellState {
     turbo: number;
     buyBonusEnabled: boolean;
     freeSpins: FreeSpinsState;
+    /** Game-supplied bonus label + value override (from `setBonus()`). When null the bar derives the
+     *  readout from `freeSpins` (label 'Free spins', value current/total) — the back-compat default. */
+    bonus: {
+        label: string;
+        value: string;
+    } | null;
     /** The currently activated `feature` option (e.g. Ante), or null. Drives the
      *  effective-bet readout tint and the BUY BONUS → DISABLE toggle on the bar. */
     activeFeature: BonusOption | null;
+    /** Volume slider positions (0..1) surfaced in the Settings overlay. Stateful across opens so a
+     *  reopened overlay reflects the last-set positions instead of resetting to 100%. */
+    volumes: VolumeLevels;
 }
 interface ShellEvents {
     spin: void;
@@ -408,6 +441,13 @@ interface ShellHost {
     setSound(on: boolean): void;
     /** An open Settings overlay registers an icon updater here (null clears it on close). */
     setSoundRefresh(fn: ((on: boolean) => void) | null): void;
+    /** Current volume slider position (0..1) for master/music/sfx. */
+    getVolume(key: VolumeKey): number;
+    /** Set a volume slider (0..1): clamps, stores, emits `settingChange`, and live-updates an open
+     *  Settings overlay. Called by the slider control on drag AND by game code as the public API. */
+    setVolume(key: VolumeKey, value: number): void;
+    /** An open Settings overlay registers a slider updater here (null clears it on close). */
+    setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void;
     /** Logic-bearing actions invoked by renderer controls. */
     readonly actions: ShellActions;
 }
@@ -471,13 +511,14 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.4.1";
+    readonly engineVersion = "0.6.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
     private kbd?;
     private overlay;
     private soundRefresh;
+    private volumeRefresh;
     private prevBalance;
     private prevWin;
     private destroyed;
@@ -502,6 +543,12 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     closeModal(): void;
     setSound(on: boolean): void;
     setSoundRefresh(fn: ((on: boolean) => void) | null): void;
+    getVolume(key: VolumeKey): number;
+    /** Set a volume slider (0..1). Shared by the slider control (drag) and game code (public API):
+     *  clamps, stores so a reopened Settings overlay reflects it, emits `settingChange`, and
+     *  live-updates the slider if the overlay is currently open. */
+    setVolume(key: VolumeKey, value: number): void;
+    setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void;
     activateFeature(bonus: BonusOption): void;
     deactivateFeature(): void;
     private money;
@@ -514,6 +561,10 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     setTurbo(level: number): void;
     setBuyBonusEnabled(enabled: boolean): void;
     setFreeSpins(fs: FreeSpinsState): void;
+    /** Generic bonus readout (adventure / hold-and-spin / respins). Sets a game-supplied label+value
+     *  override for the bar hero and folds `totalWin` into the shared accumulator. Pairs with
+     *  `setMode('bonus')`. `setFreeSpins()` clears the override back to the derived current/total. */
+    setBonus(b: BonusReadout): void;
     setTheme(theme: ThemeConfig): void;
     setLanguage(lang: string): void;
     setSocial(isSocial: boolean): void;
@@ -537,7 +588,7 @@ interface I18n {
 declare function createI18n(opts: I18nOptions): I18n;
 
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-declare const PACKAGE_VERSION = "0.4.1";
+declare const PACKAGE_VERSION = "0.6.0";
 
 /** A shell: the renderer-agnostic controller plus the surface facade (safeArea/barHeight/setVisible)
  *  an embedding host reads. `createShell`, `createGameShell` and `createPixiShell` all return this. */
@@ -613,4 +664,4 @@ declare function createGameShell(config: HtmlShellConfig): ShellController;
 declare function removeGameShell(): Promise<void>;
 
 export { DEFAULT_ACCENT, ShellController as GameShell, HtmlRenderer, PACKAGE_VERSION, SCHEMES, ShellController, createGameShell, createI18n, createShell, normalizeLang, removeGameShell, resolveConfig, resolveTheme, socialize };
-export type { AutoplayConfig, AutoplayOptions, BonusCardContext, BonusOption, CellRef, CreateShellOptions, CurrencyConfig, FreeSpinsState, GameInfoContent, GameInfoSection, GameMode, HtmlShellConfig, I18n, I18nOptions, Lang, ModalAction, ModalOptions, OverlayHandle, OverlayRequest, PaylineDef, PaytableRow, ReplayModalOptions, ResolvedShellConfig, SafeArea, ShapeDef, Shell, ShellActions, HtmlShellConfig as ShellConfig, ShellEvents, ShellFeatures, ShellHost, ShellLayoutMode, ShellMode, ShellRenderer, ShellState, ShellSurface, ShellTokens, ThemeConfig, WinSection };
+export type { AutoplayConfig, AutoplayOptions, BonusCardContext, BonusOption, BonusReadout, CellRef, CreateShellOptions, CurrencyConfig, FreeSpinsState, GameInfoContent, GameInfoSection, GameMode, HtmlShellConfig, I18n, I18nOptions, Lang, ModalAction, ModalOptions, OverlayHandle, OverlayRequest, PaylineDef, PaytableRow, ReplayModalOptions, ResolvedShellConfig, SafeArea, ShapeDef, Shell, ShellActions, HtmlShellConfig as ShellConfig, ShellEvents, ShellFeatures, ShellHost, ShellLayoutMode, ShellMode, ShellRenderer, ShellState, ShellSurface, ShellTokens, ThemeConfig, VolumeKey, VolumeLevels, WinSection };

package/dist/html.esm.js

@@ -63,9 +63,19 @@ function createInitialState(config) {
         turbo: 0,
         buyBonusEnabled: true,
         freeSpins: { current: 0, total: 0, totalWin: 0 },
+        bonus: null,
         activeFeature: null,
+        volumes: {
+            master: clampVolume(config.volumes?.master),
+            music: clampVolume(config.volumes?.music),
+            sfx: clampVolume(config.volumes?.sfx),
+        },
     };
 }
+/** Clamp a configured volume to 0..1, defaulting to full (1) when unset/invalid. */
+function clampVolume(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 1;
+}
 /** Step bet up/down within availableBets, clamped at the ends. */
 function stepBet(state, direction) {
     const idx = state.availableBets.indexOf(state.bet);
@@ -1436,7 +1446,7 @@ class KeyboardController {
 
 // AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-const PACKAGE_VERSION = '0.4.1';
+const PACKAGE_VERSION = '0.6.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -1453,6 +1463,7 @@ function resolveConfig(config) {
         features: config.features,
         theme: config.theme,
         onBonusBuy: config.onBonusBuy,
+        volumes: config.volumes,
         version: config.version ?? '1.0.0',
         isSocial: config.isSocial ?? false,
         replay: config.replay ?? config.mode === 'replay',
@@ -1474,6 +1485,7 @@ class ShellController extends EventEmitter {
     kbd;
     overlay = null;
     soundRefresh = null;
+    volumeRefresh = null;
     prevBalance;
     prevWin;
     destroyed = false;
@@ -1497,9 +1509,15 @@ class ShellController extends EventEmitter {
         this.renderer.renderBar();
     }
     // ── ShellHost ──────────────────────────────────────────────────────────────
-    t(text) { return this.i18n.t(text); }
-    formatCurrency(n, win = false) { return formatCurrency(n, this.config.currency, win); }
-    formatWin(value) { return this.formatCurrency(value, true); }
+    t(text) {
+        return this.i18n.t(text);
+    }
+    formatCurrency(n, win = false) {
+        return formatCurrency(n, this.config.currency, win);
+    }
+    formatWin(value) {
+        return this.formatCurrency(value, true);
+    }
     notifyResize(w, h) {
         const layout = w !== 0 && h > w ? 'mobile' : 'wide';
         if (layout !== this.layout) {
@@ -1566,12 +1584,24 @@ class ShellController extends EventEmitter {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const self = this;
         const host = {
-            get state() { return self.state; },
-            get hotkeysEnabled() { return self.config.features.hotkeys !== false; },
-            get spacebarEnabled() { return self.config.features.spacebar !== false; },
-            get turboLevels() { return self.config.features.turbo; },
-            get autoplayEnabled() { return self.config.features.autoplay != null; },
-            get buyBonusEnabled() { return self.config.features.buyBonus !== false; },
+            get state() {
+                return self.state;
+            },
+            get hotkeysEnabled() {
+                return self.config.features.hotkeys !== false;
+            },
+            get spacebarEnabled() {
+                return self.config.features.spacebar !== false;
+            },
+            get turboLevels() {
+                return self.config.features.turbo;
+            },
+            get autoplayEnabled() {
+                return self.config.features.autoplay != null;
+            },
+            get buyBonusEnabled() {
+                return self.config.features.buyBonus !== false;
+            },
             hasOpenLayer: () => self.overlay !== null,
             routeToLayer: (e) => self.overlay?.onKey?.(e) ?? false,
             spin: () => self.actions.spin(),
@@ -1587,33 +1617,59 @@ class ShellController extends EventEmitter {
         this.kbd = new KeyboardController(host);
         this.kbd.attach();
     }
-    pullFocus = () => { try {
-        globalThis.focus?.();
-    }
-    catch { /* cross-origin */ } };
+    pullFocus = () => {
+        try {
+            globalThis.focus?.();
+        }
+        catch {
+            /* cross-origin */
+        }
+    };
     // ── overlay flow ─────────────────────────────────────────────────────────────
     show(req) {
         this.closeModal();
         this.overlay = this.renderer.openOverlay(req) ?? null;
     }
-    openMenu() { this.emit('menuOpen'); this.openSettings(); }
-    openSettings() { this.emit('settingsOpen'); this.show({ kind: 'settings' }); }
-    openInfo() { this.emit('infoOpen'); this.show({ kind: 'gameInfo' }); }
-    openBuyBonus() { if (this.config.onBonusBuy) {
-        this.config.onBonusBuy();
-        return;
-    } this.show({ kind: 'buyBonus' }); }
-    openBetPicker() { this.show({ kind: 'betPicker' }); }
-    openAutoplayPicker() { this.show({ kind: 'autoplayPicker' }); }
-    openReplay(opts) { if (this.destroyed)
-        return; this.show({ kind: 'replay', opts }); }
-    openModal(opts) { this.show({ kind: 'modal', opts }); }
+    openMenu() {
+        this.emit('menuOpen');
+        this.openSettings();
+    }
+    openSettings() {
+        this.emit('settingsOpen');
+        this.show({ kind: 'settings' });
+    }
+    openInfo() {
+        this.emit('infoOpen');
+        this.show({ kind: 'gameInfo' });
+    }
+    openBuyBonus() {
+        if (this.config.onBonusBuy) {
+            this.config.onBonusBuy();
+            return;
+        }
+        this.show({ kind: 'buyBonus' });
+    }
+    openBetPicker() {
+        this.show({ kind: 'betPicker' });
+    }
+    openAutoplayPicker() {
+        this.show({ kind: 'autoplayPicker' });
+    }
+    openReplay(opts) {
+        if (this.destroyed)
+            return;
+        this.show({ kind: 'replay', opts });
+    }
+    openModal(opts) {
+        this.show({ kind: 'modal', opts });
+    }
     /** Programmatically dismiss whatever overlay/modal is open. No-op when nothing is shown. */
     closeModal() {
         if (!this.overlay)
             return;
         this.overlay = null;
         this.soundRefresh = null;
+        this.volumeRefresh = null;
         this.renderer.closeOverlay();
     }
     // ── sound ──────────────────────────────────────────────────────────────────
@@ -1623,7 +1679,25 @@ class ShellController extends EventEmitter {
         this.soundRefresh?.(on);
         this.renderer.refreshSoundIcon?.(on);
     }
-    setSoundRefresh(fn) { this.soundRefresh = fn; }
+    setSoundRefresh(fn) {
+        this.soundRefresh = fn;
+    }
+    // ── volume ─────────────────────────────────────────────────────────────────
+    getVolume(key) {
+        return this.state.volumes[key];
+    }
+    /** Set a volume slider (0..1). Shared by the slider control (drag) and game code (public API):
+     *  clamps, stores so a reopened Settings overlay reflects it, emits `settingChange`, and
+     *  live-updates the slider if the overlay is currently open. */
+    setVolume(key, value) {
+        const v = Math.max(0, Math.min(1, value));
+        this.state.volumes[key] = v;
+        this.emit('settingChange', { key, value: v });
+        this.volumeRefresh?.(key, v);
+    }
+    setVolumeRefresh(fn) {
+        this.volumeRefresh = fn;
+    }
     // ── features ─────────────────────────────────────────────────────────────────
     activateFeature(bonus) {
         this.state.activeFeature = bonus;
@@ -1644,21 +1718,81 @@ class ShellController extends EventEmitter {
         if (to !== from)
             this.renderer.animateMoney(field, from, to);
     }
-    setBalance(n) { const from = this.prevBalance; this.state.balance = n; this.prevBalance = n; this.money('balance', from, n); }
-    setWin(n) { const from = this.prevWin; this.state.win = n; this.prevWin = n; this.money('win', from, n); }
-    setBet(n) { this.state.bet = n; this.renderer.renderBar(); }
-    setMode(mode) { if (mode === 'replay')
-        this.state.replay = true; this.state.mode = mode; this.renderer.renderBar(); }
-    setBusy(busy) { this.state.busy = busy; this.renderer.renderBar(); this.kbd?.notifyBusyChanged(busy); }
-    setAutoplay(a) { this.state.autoplay = a; this.renderer.renderBar(); }
-    setTurbo(level) { this.state.turbo = level; this.renderer.renderBar(); }
-    setBuyBonusEnabled(enabled) { this.state.buyBonusEnabled = enabled; this.renderer.renderBar(); }
-    setFreeSpins(fs) { this.state.freeSpins = fs; this.renderer.renderBar(); }
-    setTheme(theme) { this.config.theme = theme; this.tokens = resolveTheme(theme); this.renderer.applyTheme(this.tokens); this.renderer.renderBar(); }
-    setLanguage(lang) { this.config.language = lang; this.i18n = createI18n({ language: lang, isSocial: this.config.isSocial }); this.renderer.renderBar(); }
-    setSocial(isSocial) { this.config.isSocial = isSocial; this.i18n = createI18n({ language: this.config.language, isSocial }); this.renderer.renderBar(); }
-    setLayout(layout) { if (layout === this.layout)
-        return; this.layout = layout; this.renderer.setLayout(layout); this.renderer.renderBar(); }
+    setBalance(n) {
+        const from = this.prevBalance;
+        this.state.balance = n;
+        this.prevBalance = n;
+        this.money('balance', from, n);
+    }
+    setWin(n) {
+        const from = this.prevWin;
+        this.state.win = n;
+        this.prevWin = n;
+        this.money('win', from, n);
+    }
+    setBet(n) {
+        this.state.bet = n;
+        this.renderer.renderBar();
+    }
+    setMode(mode) {
+        if (mode === 'replay')
+            this.state.replay = true;
+        this.state.mode = mode;
+        this.renderer.renderBar();
+    }
+    setBusy(busy) {
+        this.state.busy = busy;
+        this.renderer.renderBar();
+        this.kbd?.notifyBusyChanged(busy);
+    }
+    setAutoplay(a) {
+        this.state.autoplay = a;
+        this.renderer.renderBar();
+    }
+    setTurbo(level) {
+        this.state.turbo = level;
+        this.renderer.renderBar();
+    }
+    setBuyBonusEnabled(enabled) {
+        this.state.buyBonusEnabled = enabled;
+        this.renderer.renderBar();
+    }
+    setFreeSpins(fs) {
+        this.state.freeSpins = fs;
+        this.state.bonus = null;
+        this.renderer.renderBar();
+    }
+    /** Generic bonus readout (adventure / hold-and-spin / respins). Sets a game-supplied label+value
+     *  override for the bar hero and folds `totalWin` into the shared accumulator. Pairs with
+     *  `setMode('bonus')`. `setFreeSpins()` clears the override back to the derived current/total. */
+    setBonus(b) {
+        this.state.bonus = { label: b.label, value: b.value };
+        this.state.freeSpins = { ...this.state.freeSpins, totalWin: b.totalWin };
+        this.renderer.renderBar();
+    }
+    setTheme(theme) {
+        this.config.theme = theme;
+        this.tokens = resolveTheme(theme);
+        this.renderer.applyTheme(this.tokens);
+        this.renderer.renderBar();
+    }
+    setLanguage(lang) {
+        this.config.language = lang;
+        this.i18n = createI18n({ language: lang, isSocial: this.config.isSocial });
+        this.renderer.renderBar();
+    }
+    setSocial(isSocial) {
+        this.config.isSocial = isSocial;
+        this.i18n = createI18n({ language: this.config.language, isSocial });
+        this.renderer.renderBar();
+    }
+    setLayout(layout) {
+        if (layout === this.layout)
+            return;
+        this.layout = layout;
+        this.renderer.setLayout(layout);
+        this.renderer.renderBar();
+    }
     destroy() {
         if (this.destroyed)
             return Promise.resolve();
@@ -2380,8 +2514,10 @@ function iconBtn(ge, name, onClick, active = false) {
     b.className = `ge-iconbtn${active ? ' ge-active' : ''}`;
     b.dataset.ge = ge;
     b.innerHTML = icon(name);
-    b.addEventListener('click', () => { if (!b.disabled)
-        onClick(); });
+    b.addEventListener('click', () => {
+        if (!b.disabled)
+            onClick();
+    });
     return b;
 }
 function renderBottomBar(host) {
@@ -2397,15 +2533,13 @@ function renderBottomBar(host) {
     // All three modes share the base plaque layout. FS/replay hide the controls that don't apply
     // and add Free Spins + Total Win blocks on the left; the per-spin WIN uses the base pill.
     const isBase = state.mode === 'base';
-    const isFS = state.mode === 'freeSpins';
+    const isFS = state.mode === 'freeSpins' || state.mode === 'bonus';
     // FS always shows the spins counter + accumulated Total Win (even €0); a replay shows them
     // only when it's a free-spins replay (freeSpins.total > 0).
     const showFsBlocks = isFS || (state.mode === 'replay' && state.freeSpins.total > 0);
     // Replay is a read-only historical round — there's no real balance to show, so hide it. Keyed on
     // the sticky `replay` flag (not `mode`) so it stays hidden through a replay's free-spins phase.
-    const balance = state.replay
-        ? null
-        : readout('balance', host.t('Balance'), fmt(state.balance));
+    const balance = state.replay ? null : readout('balance', host.t('Balance'), fmt(state.balance));
     // With a feature active (e.g. Ante) the BET readout shows the effective stake, tinted with
     // the feature accent; the base state.bet is unchanged and returns once the feature is off.
     const feature = state.activeFeature;
@@ -2428,21 +2562,25 @@ function renderBottomBar(host) {
         betDown = iconBtn('bet-down', 'minus', () => host.actions.stepBet(-1));
         betUp = iconBtn('bet-up', 'plus', () => host.actions.stepBet(1));
         betValue.classList.add('ge-betbtn'); // tap the stake → bet picker
-        betValue.addEventListener('click', () => { if (!betLocked(host))
-            host.actions.openBetPicker(); });
+        betValue.addEventListener('click', () => {
+            if (!betLocked(host))
+                host.actions.openBetPicker();
+        });
         spin = spinButton(host);
         auto = config.features.autoplay ? autoButton(host) : null;
-        buy = (config.features.buyBonus !== false || config.onBonusBuy) ? buyBtn(host) : null;
+        buy = config.features.buyBonus !== false || config.onBonusBuy ? buyBtn(host) : null;
     }
     const winEl = state.win > 0 ? readout('win', host.t('Win'), fmtWin(state.win)) : null;
     // FS/replay left blocks: spins counter + accumulated Total Win (shown even at €0).
     // current = number → "current / total"; current = null/undefined → just the (game-driven) total.
     const fs = state.freeSpins;
-    const fsText = fs.current == null ? `${fs.total}` : `${fs.current} / ${fs.total}`;
+    const fsText = state.bonus?.value ?? (fs.current == null ? `${fs.total}` : `${fs.current} / ${fs.total}`);
     // In FS the spins counter takes the SPIN slot as a rectangular hero plaque (same white/black-ring
     // style as the SPIN disc); Total Win stays an inline readout.
-    const fsHero = showFsBlocks ? fsHeroPlaque(host, fsText) : null;
-    const fsTotalWin = showFsBlocks ? readout('fs-totalwin', host.t('Total win'), fmtWin(fs.totalWin)) : null;
+    const fsHero = showFsBlocks ? fsHeroPlaque(host, fsText, state.bonus?.label) : null;
+    const fsTotalWin = showFsBlocks
+        ? readout('fs-totalwin', host.t('Total win'), fmtWin(fs.totalWin))
+        : null;
     // The hero in the centre/spin position: SPIN in base, the FS counter in free spins, nothing else.
     const hero = isBase ? spin : fsHero;
     if (mobile) {
@@ -2485,13 +2623,13 @@ function renderBottomBar(host) {
 }
 /** Free-spins hero plaque — takes the SPIN slot in FS: same white disc/black-ring language as SPIN,
  *  but a rounded RECTANGLE showing the spins counter ("3 / 10"). */
-function fsHeroPlaque(host, text) {
+function fsHeroPlaque(host, text, label) {
     const el = document.createElement('div');
     el.className = 'ge-fs-hero';
     el.dataset.ge = 'fs-counter';
     const lbl = document.createElement('span');
     lbl.className = 'ge-fs-lbl';
-    lbl.textContent = host.t('Free spins');
+    lbl.textContent = host.t(label ?? 'Free spins');
     const num = document.createElement('span');
     num.className = 'ge-fs-num';
     num.textContent = text;
@@ -2511,7 +2649,9 @@ function plaque(cls, children) {
     d.append(...children);
     return d;
 }
-function compact(items) { return items.filter((x) => x !== null); }
+function compact(items) {
+    return items.filter((x) => x !== null);
+}
 function buyBtn(host) {
     const buy = document.createElement('button');
     buy.className = 'ge-shell-buybonus';
@@ -2524,15 +2664,19 @@ function buyBtn(host) {
         buy.innerHTML = `<span>${host.t('DISABLE')}</span>`;
         buy.style.background = accent;
         buy.style.color = contrastText(accent);
-        buy.addEventListener('click', () => { if (!buy.disabled)
-            host.actions.deactivateFeature(); });
+        buy.addEventListener('click', () => {
+            if (!buy.disabled)
+                host.actions.deactivateFeature();
+        });
     }
     else {
         // Ticket icon (no text); keep the label for screen readers.
         buy.setAttribute('aria-label', host.t('BUY BONUS'));
         buy.innerHTML = `<span class="ge-bb-tk">${icon('ticket')}</span>`;
-        buy.addEventListener('click', () => { if (!buy.disabled)
-            host.actions.openBuyBonus(); });
+        buy.addEventListener('click', () => {
+            if (!buy.disabled)
+                host.actions.openBuyBonus();
+        });
     }
     return buy;
 }
@@ -2550,15 +2694,19 @@ function spinButton(host) {
         const rem = state.autoplay.remaining;
         const label = Number.isFinite(rem) ? String(rem) : '∞';
         sp.innerHTML = `<span class="ge-spin-stop">${icon('stop')}</span><span class="ge-spin-count">${label}</span>`;
-        sp.addEventListener('click', () => { if (!sp.disabled)
-            host.actions.stopAutoplay(); });
+        sp.addEventListener('click', () => {
+            if (!sp.disabled)
+                host.actions.stopAutoplay();
+        });
     }
     else {
         sp.innerHTML = icon('spin');
         if (state.busy)
             sp.classList.add('ge-spinning');
-        sp.addEventListener('click', () => { if (!sp.disabled)
-            host.actions.spin(); });
+        sp.addEventListener('click', () => {
+            if (!sp.disabled)
+                host.actions.spin();
+        });
     }
     return sp;
 }
@@ -2707,7 +2855,10 @@ function openSettingsModal(host) {
         return row;
     })();
     body.appendChild(sound);
-    // Volume sliders — full-width column rows with a live value readout
+    // Volume sliders — full-width column rows with a live value readout. Positions are read from the
+    // shell's stored volumes (not hardcoded to 100%), so reopening the overlay reflects the last set
+    // value, and `host.setVolume()` from game code updates them live via the registered refreshers.
+    const updaters = {};
     const slider = (key, label) => {
         const row = document.createElement('div');
         row.className = 'ge-ov-row ge-col';
@@ -2715,7 +2866,6 @@ function openSettingsModal(host) {
         head.className = 'ge-row-head';
         const val = document.createElement('span');
         val.className = 'ge-val';
-        val.textContent = '100%';
         head.innerHTML = `<span>${label}</span>`;
         head.appendChild(val);
         const input = document.createElement('input');
@@ -2723,19 +2873,23 @@ function openSettingsModal(host) {
         input.min = '0';
         input.max = '1';
         input.step = '0.05';
-        input.value = '1';
         input.className = 'ge-slider';
         input.dataset.ge = `setting-${key}`;
+        const paint = (v) => { input.value = String(v); val.textContent = `${Math.round(v * 100)}%`; };
+        paint(host.getVolume(key));
         input.addEventListener('input', () => {
             val.textContent = `${Math.round(Number(input.value) * 100)}%`;
-            host.emit('settingChange', { key, value: Number(input.value) });
+            host.setVolume(key, Number(input.value));
         });
+        updaters[key] = paint;
         row.append(head, input);
         return row;
     };
     body.appendChild(slider('master', host.t('Master volume')));
     body.appendChild(slider('music', host.t('Music')));
     body.appendChild(slider('sfx', host.t('SFX')));
+    // Live-update sliders when volume changes via host.setVolume (shell clears on close).
+    host.setVolumeRefresh((key, v) => updaters[key]?.(v));
     // Game info — full-width row button that opens its own overlay
     const gameInfo = document.createElement('button');
     gameInfo.className = 'ge-ov-row';