@energy8platform/shell 0.4.1 → 0.5.0

package/dist/html.d.ts

@@ -16,7 +16,11 @@ 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';
 interface CurrencyConfig {
     symbol: string;
     position: 'left' | 'right';
@@ -205,6 +209,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;
@@ -283,6 +300,12 @@ 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;
@@ -471,7 +494,7 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.4.1";
+    readonly engineVersion = "0.5.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
@@ -514,6 +537,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 +564,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.5.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 +640,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, WinSection };

package/dist/html.esm.js

@@ -63,6 +63,7 @@ function createInitialState(config) {
         turbo: 0,
         buyBonusEnabled: true,
         freeSpins: { current: 0, total: 0, totalWin: 0 },
+        bonus: null,
         activeFeature: null,
     };
 }
@@ -1436,7 +1437,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.5.0';
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 function resolveConfig(config) {
@@ -1497,9 +1498,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 +1573,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,27 +1606,52 @@ 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)
@@ -1623,7 +1667,9 @@ class ShellController extends EventEmitter {
         this.soundRefresh?.(on);
         this.renderer.refreshSoundIcon?.(on);
     }
-    setSoundRefresh(fn) { this.soundRefresh = fn; }
+    setSoundRefresh(fn) {
+        this.soundRefresh = fn;
+    }
     // ── features ─────────────────────────────────────────────────────────────────
     activateFeature(bonus) {
         this.state.activeFeature = bonus;
@@ -1644,21 +1690,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 +2486,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 +2505,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 +2534,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 +2595,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 +2621,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 +2636,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 +2666,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;
 }