@energy8platform/platform-core 0.24.5 → 0.25.0

package/src/lua/LuaEngine.ts

@@ -36,6 +36,7 @@ export class LuaEngine {
   private gameDefinition: GameDefinition;
   private variables: Record<string, number> = {};
   private simulationMode: boolean;
+  private allowSessionlessActions: boolean;
   /** Reusable state objects to avoid per-iteration allocation */
   private _stateVars: Record<string, number> = {};
   private _stateParams: Record<string, unknown> = {};
@@ -43,6 +44,7 @@ export class LuaEngine {
   constructor(config: LuaEngineConfig) {
     this.gameDefinition = config.gameDefinition;
     this.simulationMode = config.simulationMode ?? false;
+    this.allowSessionlessActions = config.allowSessionlessActions ?? false;
 
     const rng = config.seed !== undefined
       ? createSeededRng(config.seed)
@@ -93,10 +95,11 @@ export class LuaEngine {
   execute(params: PlayParams): LuaPlayResult {
     const { action: actionName, params: clientParams } = params;
 
-    // 1. Resolve action
+    // 1. Resolve action. In the harness, `allowSessionlessActions` lets a standalone free_spin
+    //    (replayed after a books-path bonus buy that never created an engine session) run anyway.
     const action = this.actionRouter.resolveAction(
       actionName,
-      this.sessionManager.isActive,
+      this.sessionManager.isActive || this.allowSessionlessActions,
     );
 
     // 2. Determine bet — server uses session bet for session actions

package/src/lua/types.ts

@@ -88,6 +88,14 @@ export 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;
 }
 
 export interface LuaPlayResult {

package/src/shell/GameShell.ts

@@ -64,6 +64,10 @@ export class GameShell extends EventEmitter<ShellEvents> {
     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();
@@ -139,6 +143,10 @@ export 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 = (): void => { try { window.focus(); } catch { /* cross-origin / non-browser */ } };
+
   private handleKeyDown = (e: KeyboardEvent): void => {
     if (this.destroyed || e.code !== 'Space' || e.repeat) return;
     if (this.config.features.spacebar === false) return; // shortcut disabled (e.g. jurisdiction)
@@ -201,10 +209,17 @@ export class GameShell extends EventEmitter<ShellEvents> {
   setBalance(n: number): void { this.state.balance = n; this.render(); }
   setWin(n: number): void { this.state.win = n; this.render(); }
   setBet(n: number): void { this.state.bet = n; this.render(); }
-  setMode(mode: ShellMode): void { this.state.mode = mode; this.render(); }
+  setMode(mode: ShellMode): void {
+    if (mode === 'replay') this.state.replay = true; // sticky: a replay stays a replay across modes
+    this.state.mode = mode;
+    this.render();
+  }
   setBusy(busy: boolean): void { this.state.busy = busy; this.render(); }
   setAutoplay(a: AutoplayOptions): void { this.state.autoplay = a; this.render(); }
   setTurbo(level: number): void { 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: number): string { return formatCurrency(value, this.config.currency, true); }
   setBuyBonusEnabled(enabled: boolean): void { this.state.buyBonusEnabled = enabled; this.render(); }
   setFreeSpins(fs: FreeSpinsState): void { this.state.freeSpins = fs; this.render(); }
 
@@ -272,6 +287,9 @@ export 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 { 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(): void { this.modalHost.innerHTML = ''; }
   /** Open the non-dismissable replay summary modal (START REPLAY → onReplay → reopen). */
   openReplay(opts: ReplayModalOptions): void {
     if (this.destroyed) return;
@@ -288,7 +306,11 @@ export class GameShell extends EventEmitter<ShellEvents> {
     this.destroyed = true;
     this.ro?.disconnect();
     this.ro = null;
-    if (this.keysBound) { document.removeEventListener('keydown', this.handleKeyDown); this.keysBound = false; }
+    if (this.keysBound) {
+      document.removeEventListener('keydown', this.handleKeyDown);
+      document.removeEventListener('pointerdown', this.pullFocus, true);
+      this.keysBound = false;
+    }
     this.cancelMoneyAnims();
     this.removeAllListeners();
     this.root.classList.add('ge-shell-hidden');

package/src/shell/components/BottomBar.ts

@@ -52,8 +52,9 @@ export function renderBottomBar(shell: GameShell): HTMLElement {
   // 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

package/src/shell/components/GameInfo.ts

@@ -2,6 +2,7 @@ import type { GameShell } from '../GameShell';
 import type { CellRef, GameInfoSection, GameMode, PaytableRow, PaylineDef, ShapeDef, WinSection } from '../types';
 import { createOverlay, twoLine } from './primitives';
 import { icon } from './icons';
+import { PACKAGE_VERSION } from '../version';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
 
@@ -23,9 +24,21 @@ export function openGameInfoModal(shell: GameShell): HTMLElement {
     .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: GameShell): HTMLElement {
+  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: GameShell, s: GameInfoSection): HTMLElement {
   switch (s.type) {
     case 'modes': return sectionModes(shell, s.modes, sec('info-modes', s.title, shell.t('Modes')));

package/src/shell/index.ts

@@ -18,3 +18,4 @@ export function removeGameShell(): Promise<void> {
 }
 
 export { GameShell };
+export { socialize } from './i18n';

package/src/shell/shell.css.ts

@@ -148,6 +148,8 @@ export 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); }

package/src/shell/state.ts

@@ -3,6 +3,7 @@ import type { ShellConfig, ShellState } from './types';
 export function createInitialState(config: ShellConfig): ShellState {
   return {
     mode: config.mode,
+    replay: config.replay ?? config.mode === 'replay',
     balance: config.balance,
     win: config.win,
     bet: config.currentBet ?? config.defaultBet,

package/src/shell/types.ts

@@ -194,6 +194,9 @@ export 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;
@@ -204,6 +207,10 @@ export 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
@@ -213,6 +220,10 @@ export interface ShellConfig {
 
 export 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;

package/src/shell/version.ts

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
+/** The @energy8platform/platform-core package version, stamped at build time. */
+export const PACKAGE_VERSION = '0.25.0';

package/src/simulation/NativeSimulationRunner.ts

@@ -52,6 +52,12 @@ export 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;
 }
@@ -137,6 +143,43 @@ interface GoSimulationOutput {
   };
 }
 
+// ─── Pure arg builder ────────────────────────────────────
+
+export interface NativeArgsInput {
+  configPath: string;
+  iterations: number;
+  bet: number;
+  action?: string;
+  params?: unknown;
+  rng?: string;
+  seed?: string;
+  dump?: string;
+  replay?: { serverSeed: string; clientSeed: string; nonceStart: number };
+}
+
+/**
+ * Build the CLI args array for the native simulation binary.
+ * Pure function — no I/O, easily testable.
+ */
+export function buildNativeArgs(a: NativeArgsInput): string[] {
+  const args = ['-config', a.configPath, '-iterations', String(a.iterations), '-bet', String(a.bet), '-format', 'json'];
+  if (a.action) args.push('-action', a.action);
+  if (a.params !== undefined && a.params !== null && (typeof a.params !== 'object' || Object.keys(a.params as object).length > 0)) {
+    args.push('-params', JSON.stringify(a.params));
+  }
+  if (a.rng) args.push('-rng', a.rng);
+  if (a.seed) args.push('-seed', a.seed);
+  if (a.dump) args.push('-dump', a.dump);
+  if (a.replay) {
+    args.push(
+      '-replay-server-seed', a.replay.serverSeed,
+      '-replay-client-seed', a.replay.clientSeed,
+      '-replay-nonce-start', String(a.replay.nonceStart),
+    );
+  }
+  return args;
+}
+
 // ─── Runner ─────────────────────────────────────────────
 
 export class NativeSimulationRunner {
@@ -147,7 +190,7 @@ export class NativeSimulationRunner {
   }
 
   async run(): Promise<NativeSimulationResult> {
-    const { binaryPath, script, gameDefinition, iterations, bet, action, params, seed, rng, replay } = this.config;
+    const { binaryPath, script, gameDefinition, iterations, bet, action, params, seed, rng, replay, dump } = this.config;
 
     if (replay && rng && rng !== 'provably-fair') {
       throw new Error(`Replay mode requires rng="provably-fair" (got rng="${rng}")`);
@@ -166,31 +209,7 @@ export class NativeSimulationRunner {
       ]);
 
       // Build CLI args
-      const args = [
-        '-config', configPath,
-        '-iterations', String(iterations),
-        '-bet', String(bet),
-        '-format', 'json',
-      ];
-      if (action) {
-        args.push('-action', action);
-      }
-      if (params && Object.keys(params).length > 0) {
-        args.push('-params', JSON.stringify(params));
-      }
-      if (rng) {
-        args.push('-rng', rng);
-      }
-      if (seed) {
-        args.push('-seed', seed);
-      }
-      if (replay) {
-        args.push(
-          '-replay-server-seed', replay.serverSeed,
-          '-replay-client-seed', replay.clientSeed,
-          '-replay-nonce-start', String(replay.nonceStart),
-        );
-      }
+      const args = buildNativeArgs({ configPath, iterations, bet, action, params, rng, seed, dump, replay });
 
       // Execute binary
       const output = await this.exec(binaryPath, args);
@@ -359,6 +378,23 @@ export function findNativeBinary(baseDir?: string): string | null {
   return null;
 }
 
+/**
+ * Return the native binary path or throw a clear, install-guiding error.
+ * The math pipeline is go-native only — NO JS fallback.
+ *
+ * @param finder - injectable finder for testability; defaults to findNativeBinary.
+ */
+export function requireNativeBinary(finder: () => string | null = findNativeBinary): string {
+  const bin = finder();
+  if (!bin) {
+    throw new Error(
+      'native simulation binary not found — run `npm install` (platform-core fetches it via install-simulate). ' +
+      'The math pipeline is go-native only (no JS fallback).',
+    );
+  }
+  return bin;
+}
+
 function isExecutable(path: string): boolean {
   try {
     accessSync(path, fsConstants.X_OK);

package/src/simulation/index.ts

@@ -10,6 +10,8 @@ export {
   NativeSimulationRunner,
   findNativeBinary,
   formatNativeResult,
+  buildNativeArgs,
+  requireNativeBinary,
 } from './NativeSimulationRunner';
 export type {
   NativeSimulationConfig,
@@ -18,6 +20,7 @@ export type {
   NativeReplayParams,
   StageStats,
   DistributionBucket,
+  NativeArgsInput,
 } from './NativeSimulationRunner';
 
 export { ParallelSimulationRunner } from './ParallelSimulationRunner';

package/src/slot-result/coerce.ts

@@ -0,0 +1,11 @@
+/** Lua empty tables decode as {} — turn a possibly-{} value into a real array. */
+export function asArray<T = unknown>(value: unknown): T[] {
+  return Array.isArray(value) ? (value as T[]) : [];
+}
+
+/** Apply asArray() to the named fields of a record (Lua {} → []). Optional helper for a game's normalizer. */
+export function coerceLuaArrays<T extends Record<string, unknown>>(obj: T, fields: string[]): T {
+  const out: Record<string, unknown> = { ...obj };
+  for (const f of fields) out[f] = asArray(out[f]);
+  return out as T;
+}

package/src/slot-result/index.ts

@@ -0,0 +1,2 @@
+export type { SlotSpinResultBase, SlotResultNormalizer } from './types';
+export { asArray, coerceLuaArrays } from './coerce';

package/src/slot-result/types.ts

@@ -0,0 +1,19 @@
+/** Minimal, renderer-agnostic base every normalized slot result satisfies. */
+export interface SlotSpinResultBase {
+  /** Currency win amount for this play (PlatformSession.play() already applied the bet). */
+  totalWin: number;
+  freeSpins?: { awarded?: number; total?: number; remaining?: number };
+  // ── Round-continuation metadata (Stake segment-drain) ──────────────────
+  // A round may be split into several SEGMENTS (e.g. a base trigger + every free spin of one
+  // bonus). The host fills these from the raw play result so a scene can drain the remaining
+  // segments by replaying the SAME round; the game's normalizer never sets them.
+  /** Round id to pass back to `play(action, bet, roundId)` for the next segment of THIS round. */
+  roundId?: string;
+  /** Actions valid for the next segment; `nextActions[0]` is what to play to advance the round. */
+  nextActions?: string[];
+  /** True once the round has no further segments to drain (single spin, or final bonus spin). */
+  complete?: boolean;
+}
+
+/** A game declares one of these; the host invokes it on every play. Generic over the game's result type. */
+export type SlotResultNormalizer<T extends SlotSpinResultBase> = (raw: unknown) => T;