@energy8platform/platform-core 0.24.5 → 0.25.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SessionData, GameConfigData, PlayParams, PlayResultData, BalanceData, CasinoGameSDK, InitData } from '@energy8platform/game-sdk';
+import { SessionData, GameConfigData, PlayParams, PlayResultData, BalanceData, ConnectionStatePayload, CasinoGameSDK, InitData } from '@energy8platform/game-sdk';
 export { AnywhereWinData, BalanceData, GameConfigData, InitData, PaylineData, PlayParams, PlayResultData, SessionData, SymbolData, WinLineData } from '@energy8platform/game-sdk';
 
 interface GameDefinition {
@@ -76,6 +76,14 @@ interface LuaEngineConfig {
     logger?: (level: string, msg: string) => void;
     /** Skip marshalling data fields (matrix, wins, etc.) for faster simulation */
     simulationMode?: boolean;
+    /**
+     * Allow `requires_session` actions (e.g. `free_spin`) to run even with no active session.
+     * Default false (server-faithful). The dev harness sets this true: when a bonus is bought
+     * through the BOOKS path the LuaEngine never created a session, yet the scaffold then replays
+     * `free_spin` (which has no books) via the Lua fallback — without this it would throw
+     * "Action free_spin requires an active session".
+     */
+    allowSessionlessActions?: boolean;
 }
 interface LuaPlayResult {
     totalWin: number;
@@ -354,6 +362,9 @@ interface PlatformSessionEvents {
     balanceUpdate: BalanceData;
     /** SDK or transport error */
     error: Error;
+    /** Host link state changed (forwarded from the SDK): 'connecting' | 'lost' | 'restored'.
+     *  The host renders a reconnect overlay on lost/connecting and dismisses it on restored. */
+    connectionStateChanged: ConnectionStatePayload;
 }
 /**
  * Lifecycle wrapper around CasinoGameSDK + (optional) DevBridge.
@@ -401,6 +412,20 @@ declare class PlatformSession extends EventEmitter<PlatformSessionEvents> {
      * Throws if the session was constructed with `sdk: false`.
      */
     play(params: PlayParams): Promise<PlayResultData>;
+    /**
+     * Acknowledge a finished PLAY_RESULT (call AFTER the game has animated it).
+     *
+     * The host uses this to know the client is ready for the next action and, on
+     * Stake, to settle the round (`/wallet/end-round`) only once the win
+     * animation has played. No-op when constructed with `sdk: false`.
+     */
+    playAck(result: PlayResultData): void;
+    /**
+     * Query the host for an in-flight round (e.g. after a page reload). Resolves with the last
+     * result snapshot when a round is still open, or `null`. Used to offer a "resume / finish"
+     * choice on boot. Resolves `null` when constructed with `sdk: false`.
+     */
+    getState(): Promise<PlayResultData | null>;
     /** Tear down the SDK, DevBridge, and clear listeners. */
     destroy(): void;
 }
@@ -712,6 +737,9 @@ interface ShellConfig {
     theme?: ThemeConfig;
     gameInfo: GameInfoContent;
     language: string;
+    /** Game version shown in the game-info footer (e.g. '1.2.0'). Defaults to '1.0.0'. The footer
+     *  stamp is `${version}.${engineVersionWithoutDots}` — e.g. game 1.0.0 on engine 0.24.6 → '1.0.0.0246'. */
+    version?: string;
     /** When true, all built-in shell text is shown in the social-casino vocabulary (derived from
      *  English via word-swap rules), regardless of `language`. Game-supplied content is untouched. */
     isSocial?: boolean;
@@ -722,6 +750,10 @@ interface ShellConfig {
     balance: number;
     win: number;
     mode: ShellMode;
+    /** Mark this shell as a read-only historical-round replay. A replay never shows the player's
+     *  balance (there's no live wallet), even while its free-spins phase runs in `freeSpins` mode.
+     *  Defaults to `mode === 'replay'`; set explicitly when a replay starts in another mode. */
+    replay?: boolean;
     features: ShellFeatures;
     /** Override the BUY BONUS bar button's action: when set, tapping it calls this instead of
      *  opening the built-in buy-bonus overlay (e.g. the game shows its own bonus UI). The button
@@ -730,6 +762,10 @@ interface ShellConfig {
 }
 interface ShellState {
     mode: ShellMode;
+    /** Sticky replay marker — true for a historical-round replay, regardless of the current
+     *  `mode`. Set once (from config or when `mode` becomes 'replay') and never cleared, since a
+     *  shell instance is either a live game or a replay viewer for its whole lifetime. */
+    replay: boolean;
     balance: number;
     win: number;
     bet: number;
@@ -795,6 +831,9 @@ declare class GameShell extends EventEmitter<ShellEvents> {
      *  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;
     private handleKeyDown;
     setLayout(layout: 'wide' | 'mobile'): void;
     /** Resolve a built-in shell string. English is the source; with `isSocial` it is run through
@@ -813,6 +852,9 @@ declare class GameShell extends EventEmitter<ShellEvents> {
     setBusy(busy: boolean): void;
     setAutoplay(a: AutoplayOptions): void;
     setTurbo(level: number): void;
+    /** Currency-aware money formatter for WIN amounts (variable decimals: 0.0041 stays 0.0041, not
+     *  0.00). The host hands this to a scene so games format money without knowing the currency. */
+    formatWin(value: number): string;
     setBuyBonusEnabled(enabled: boolean): void;
     setFreeSpins(fs: FreeSpinsState): void;
     private showModal;
@@ -837,6 +879,9 @@ declare class GameShell extends EventEmitter<ShellEvents> {
     /** 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;
+    /** 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;
     /** Open the non-dismissable replay summary modal (START REPLAY → onReplay → reopen). */
     openReplay(opts: ReplayModalOptions): void;
     /** Bet picker — list of available bets with an accent Confirm. */
@@ -889,6 +934,12 @@ interface NativeSimulationConfig {
     rng?: NativeRNGKind;
     /** Replay mode: requires `rng: 'provably-fair'` (or default). */
     replay?: NativeReplayParams;
+    /**
+     * Path to write per-round JSONL book dump. When set, the binary writes one
+     * JSON object per line (one per round) to this file, enabling post-run
+     * analysis of the full round log.
+     */
+    dump?: string;
     /** Progress callback */
     onProgress?: (completed: number, total: number) => void;
 }

package/dist/index.esm.js

@@ -608,6 +608,26 @@ class PlatformSession extends EventEmitter {
         }
         return this.sdk.play(params);
     }
+    /**
+     * Acknowledge a finished PLAY_RESULT (call AFTER the game has animated it).
+     *
+     * The host uses this to know the client is ready for the next action and, on
+     * Stake, to settle the round (`/wallet/end-round`) only once the win
+     * animation has played. No-op when constructed with `sdk: false`.
+     */
+    playAck(result) {
+        this.sdk?.playAck(result);
+    }
+    /**
+     * Query the host for an in-flight round (e.g. after a page reload). Resolves with the last
+     * result snapshot when a round is still open, or `null`. Used to offer a "resume / finish"
+     * choice on boot. Resolves `null` when constructed with `sdk: false`.
+     */
+    async getState() {
+        if (!this.sdk)
+            return null;
+        return this.sdk.getState();
+    }
     /** Tear down the SDK, DevBridge, and clear listeners. */
     destroy() {
         this.sdk?.destroy();
@@ -647,6 +667,9 @@ async function createPlatformSession(config = {}) {
         sdk.on('balanceUpdate', (data) => {
             session.emit('balanceUpdate', data);
         });
+        sdk.on('connectionStateChanged', (state) => {
+            session.emit('connectionStateChanged', state);
+        });
     }
     return session;
 }
@@ -953,6 +976,7 @@ function removeCSSPreloader(_container) {
 function createInitialState(config) {
     return {
         mode: config.mode,
+        replay: config.replay ?? config.mode === 'replay',
         balance: config.balance,
         win: config.win,
         bet: config.currentBet ?? config.defaultBet,
@@ -1215,6 +1239,8 @@ const SHELL_CSS = SHELL_FONT_CSS + `
 #${SHELL_ROOT_ID} .ge-gi-sec h3 { color:var(--shell-plaque-label); font-size:11px; letter-spacing:.14em;
   text-transform:uppercase; margin:0 0 12px; }
 #${SHELL_ROOT_ID} .ge-gi-sec p { color:rgba(255,255,255,.88); font-size:15px; line-height:1.6; margin:0; }
+#${SHELL_ROOT_ID} .ge-gi-version { text-align:center; color:var(--shell-muted); font-size:11px;
+  letter-spacing:.08em; opacity:.7; margin:4px 0 2px; }
 
 /* controls — two blocks (gameplay / menu & info), icon/name/description per control */
 #${SHELL_ROOT_ID} .ge-gi-ctl-block + .ge-gi-ctl-block { margin-top:16px; padding-top:4px; border-top:1px solid var(--shell-plaque-line); }
@@ -1652,8 +1678,9 @@ function renderBottomBar(shell) {
     // 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.
-    const balance = state.mode === 'replay'
+    // 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', shell.t('Balance'), fmt(state.balance));
     // With a feature active (e.g. Ante) the BET readout shows the effective stake, tinted with
@@ -1923,6 +1950,10 @@ function openSettingsModal(shell) {
     return root;
 }
 
+// AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
+/** The @energy8platform/platform-core package version, stamped at build time. */
+const PACKAGE_VERSION = '0.25.0';
+
 const SVG_NS = 'http://www.w3.org/2000/svg';
 function openGameInfoModal(shell) {
     const { root, body } = createOverlay({
@@ -1939,8 +1970,19 @@ function openGameInfoModal(shell) {
         .map((s, i) => ({ s, i, k: base(s, i) }))
         .sort((a, b) => a.k - b.k || a.i - b.i)
         .forEach(({ s }) => body.appendChild(renderSection(shell, s)));
+    body.appendChild(versionFooter(shell));
     return root;
 }
+/** A muted version stamp pinned to the bottom of the game-info modal:
+ *  `${config.version ?? '1.0.0'}.${engine version without dots}` (e.g. '1.0.0.0246'). */
+function versionFooter(shell) {
+    const gameVersion = shell.config.version ?? '1.0.0';
+    const el = document.createElement('div');
+    el.dataset.ge = 'info-version';
+    el.className = 'ge-gi-version';
+    el.textContent = `${gameVersion}.${PACKAGE_VERSION.replaceAll('.', '')}`;
+    return el;
+}
 function renderSection(shell, s) {
     switch (s.type) {
         case 'modes': return sectionModes(shell, s.modes, sec('info-modes', s.title, shell.t('Modes')));
@@ -2734,6 +2776,10 @@ class GameShell extends EventEmitter {
         this.observeLayout();
         if (typeof document !== 'undefined') {
             document.addEventListener('keydown', this.handleKeyDown);
+            // 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();
@@ -2819,6 +2865,12 @@ class GameShell extends EventEmitter {
      *  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. */
+    pullFocus = () => { try {
+        window.focus();
+    }
+    catch { /* cross-origin / non-browser */ } };
     handleKeyDown = (e) => {
         if (this.destroyed || e.code !== 'Space' || e.repeat)
             return;
@@ -2883,10 +2935,18 @@ class GameShell extends EventEmitter {
     setBalance(n) { this.state.balance = n; this.render(); }
     setWin(n) { this.state.win = n; this.render(); }
     setBet(n) { this.state.bet = n; this.render(); }
-    setMode(mode) { this.state.mode = mode; this.render(); }
+    setMode(mode) {
+        if (mode === 'replay')
+            this.state.replay = true; // sticky: a replay stays a replay across modes
+        this.state.mode = mode;
+        this.render();
+    }
     setBusy(busy) { this.state.busy = busy; this.render(); }
     setAutoplay(a) { this.state.autoplay = a; this.render(); }
     setTurbo(level) { this.state.turbo = level; this.render(); }
+    /** Currency-aware money formatter for WIN amounts (variable decimals: 0.0041 stays 0.0041, not
+     *  0.00). The host hands this to a scene so games format money without knowing the currency. */
+    formatWin(value) { return formatCurrency(value, this.config.currency, true); }
     setBuyBonusEnabled(enabled) { this.state.buyBonusEnabled = enabled; this.render(); }
     setFreeSpins(fs) { this.state.freeSpins = fs; this.render(); }
     showModal(el) {
@@ -2957,6 +3017,9 @@ class GameShell extends EventEmitter {
     /** 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) { this.showModal(buildModal(opts)); }
+    /** 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() { this.modalHost.innerHTML = ''; }
     /** Open the non-dismissable replay summary modal (START REPLAY → onReplay → reopen). */
     openReplay(opts) {
         if (this.destroyed)
@@ -2975,6 +3038,7 @@ class GameShell extends EventEmitter {
         this.ro = null;
         if (this.keysBound) {
             document.removeEventListener('keydown', this.handleKeyDown);
+            document.removeEventListener('pointerdown', this.pullFocus, true);
             this.keysBound = false;
         }
         this.cancelMoneyAnims();