@energy8platform/shell 0.5.0 → 0.6.1

package/dist/html.d.ts

@@ -21,6 +21,9 @@ declare class EventEmitter<TEvents extends {}> {
  *  `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';
@@ -282,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
@@ -309,6 +316,9 @@ interface ShellState {
     /** 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;
@@ -431,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;
 }
@@ -494,13 +511,14 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.5.0";
+    readonly engineVersion = "0.6.1";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
     private kbd?;
     private overlay;
     private soundRefresh;
+    private volumeRefresh;
     private prevBalance;
     private prevWin;
     private destroyed;
@@ -525,11 +543,22 @@ 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;
     setBalance(n: number): void;
-    setWin(n: number): void;
+    /** Set the WIN readout. Counts up/down from the previous value by default. Pass
+     *  `{ animate: false }` to SNAP instantly (renderBar cancels any in-flight count-up) — used by the
+     *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong. */
+    setWin(n: number, opts?: {
+        animate?: boolean;
+    }): void;
     setBet(n: number): void;
     setMode(mode: ShellMode): void;
     setBusy(busy: boolean): void;
@@ -564,7 +593,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.5.0";
+declare const PACKAGE_VERSION = "0.6.1";
 
 /** A shell: the renderer-agnostic controller plus the surface facade (safeArea/barHeight/setVisible)
  *  an embedding host reads. `createShell`, `createGameShell` and `createPixiShell` all return this. */
@@ -640,4 +669,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, 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, 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

@@ -65,8 +65,17 @@ function createInitialState(config) {
         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);
@@ -1437,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.5.0';
+const PACKAGE_VERSION = '0.6.1';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -1454,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',
@@ -1475,6 +1485,7 @@ class ShellController extends EventEmitter {
     kbd;
     overlay = null;
     soundRefresh = null;
+    volumeRefresh = null;
     prevBalance;
     prevWin;
     destroyed = false;
@@ -1658,6 +1669,7 @@ class ShellController extends EventEmitter {
             return;
         this.overlay = null;
         this.soundRefresh = null;
+        this.volumeRefresh = null;
         this.renderer.closeOverlay();
     }
     // ── sound ──────────────────────────────────────────────────────────────────
@@ -1670,6 +1682,22 @@ class ShellController extends EventEmitter {
     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;
@@ -1696,10 +1724,17 @@ class ShellController extends EventEmitter {
         this.prevBalance = n;
         this.money('balance', from, n);
     }
-    setWin(n) {
+    /** Set the WIN readout. Counts up/down from the previous value by default. Pass
+     *  `{ animate: false }` to SNAP instantly (renderBar cancels any in-flight count-up) — used by the
+     *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong. */
+    setWin(n, opts) {
         const from = this.prevWin;
         this.state.win = n;
         this.prevWin = n;
+        if (opts?.animate === false) {
+            this.renderer.renderBar(); // instant repaint from state; cancels running money anims
+            return;
+        }
         this.money('win', from, n);
     }
     setBet(n) {
@@ -2827,7 +2862,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';
@@ -2835,7 +2873,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');
@@ -2843,19 +2880,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';