@energy8platform/platform-core 0.16.1 → 0.17.0

package/src/dev-bridge/DevBridge.ts

@@ -8,7 +8,56 @@ import {
   type PlayResultAckPayload,
   type PlayParams,
 } from '@energy8platform/game-sdk';
-import type { GameDefinition } from '../lua';
+import type { GameDefinition, BetLevelsConfig } from '../lua/types';
+
+/** Default session TTL when GameDefinition.session_ttl is omitted (24h). */
+const DEFAULT_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Parse a Go-style duration string ("24h", "5ms", "30s", "10m") into
+ * milliseconds. Mirrors GameDefinition.SessionTTLDuration on the server.
+ */
+function parseSessionTtl(ttl: string | undefined): number {
+  if (!ttl) return DEFAULT_SESSION_TTL_MS;
+  const m = ttl.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)$/);
+  if (!m) return DEFAULT_SESSION_TTL_MS;
+  const n = parseFloat(m[1]);
+  switch (m[2]) {
+    case 'ms': return n;
+    case 's':  return n * 1000;
+    case 'm':  return n * 60 * 1000;
+    case 'h':  return n * 60 * 60 * 1000;
+    default:   return DEFAULT_SESSION_TTL_MS;
+  }
+}
+
+/**
+ * Validate a bet against the game's bet_levels config — mirrors the server's
+ * validateBet. Levels-list takes priority over min/max range.
+ */
+function isBetAllowed(bet: number, levels: number[] | BetLevelsConfig | undefined): boolean {
+  if (!levels) return true;
+  if (Array.isArray(levels)) {
+    return levels.includes(bet);
+  }
+  if (levels.levels && levels.levels.length > 0) {
+    return levels.levels.includes(bet);
+  }
+  if (levels.min !== undefined && bet < levels.min) return false;
+  if (levels.max !== undefined && bet > levels.max) return false;
+  return true;
+}
+
+/**
+ * Generate a server-style UUID for a fresh round. Falls back to a counter
+ * suffix if `crypto.randomUUID` isn't available (very old runtimes).
+ */
+function generateRoundId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (c && typeof c.randomUUID === 'function') return c.randomUUID();
+  // Minimal fallback — not crypto-strong, but keeps the wire shape sane.
+  return 'dev-' + Math.random().toString(16).slice(2) + '-' + Date.now().toString(16);
+}
 
 export interface DevBridgeConfig {
   /** Mock initial balance */
@@ -84,11 +133,20 @@ export class DevBridge {
   private _roundCounter = 0;
   private _bridge: Bridge | null = null;
   private _useLuaServer: boolean;
+  /** Last PlayResult sent — mirrors what `GET /games/{id}/session` returns. */
+  private _lastPlayResult: PlayResultData | null = null;
+  /** Active session round id; non-null while a session is in progress. */
+  private _activeRoundId: string | null = null;
+  /** Wall-clock expiry timestamp for the active session. */
+  private _sessionExpiresAt: number | null = null;
+  /** Pre-parsed session TTL from gameDefinition.session_ttl. */
+  private _sessionTtlMs: number;
 
   constructor(config: DevBridgeConfig = {}) {
     this._config = { ...DEFAULT_CONFIG, ...config };
     this._balance = this._config.balance;
     this._useLuaServer = !!(this._config.luaScript && this._config.gameDefinition);
+    this._sessionTtlMs = parseSessionTtl(this._config.gameDefinition?.session_ttl);
   }
 
   /** Current mock balance */
@@ -175,27 +233,95 @@ export class DevBridge {
     payload: PlayParams,
     id?: string,
   ): void {
-    const { action, bet, roundId, params } = payload;
+    const { action, bet, params } = payload;
     this._roundCounter++;
 
     if (this._useLuaServer) {
+      const def = this._config.gameDefinition!;
+      // Mirror the server's INVALID_INPUT short-circuit: an unknown action
+      // is rejected before any wallet movement, with no PLAY_RESULT.
+      const actionDef = def.actions?.[action];
+      if (!actionDef) {
+        this.sendError(id, 'INVALID_INPUT', `unknown action "${action}"`);
+        return;
+      }
+
+      // Bet validation — server returns 400 INVALID_AMOUNT before the
+      // engine. We mirror that so games can't silently accept bad bets.
+      if (!isBetAllowed(bet, def.bet_levels)) {
+        this.sendError(id, 'INVALID_AMOUNT', `bet ${bet} is not in allowed bet_levels`);
+        return;
+      }
+
+      // Session-state guards (server: 409 ACTIVE_SESSION_EXISTS / 404 NoActiveSession / 410 ExpiredSession).
+      const sessionExpired =
+        this._activeRoundId !== null &&
+        this._sessionExpiresAt !== null &&
+        Date.now() > this._sessionExpiresAt;
+
+      if (actionDef.requires_session) {
+        if (sessionExpired) {
+          this.clearSessionState();
+          this.sendError(id, 'SESSION_EXPIRED', 'game session has expired');
+          return;
+        }
+        if (this._activeRoundId === null) {
+          this.sendError(id, 'NO_ACTIVE_SESSION', `action "${action}" requires an active session`);
+          return;
+        }
+      } else {
+        // Non-session action over an active (non-expired) session — server's
+        // acquireSession would fail with ACTIVE_SESSION_EXISTS.
+        if (this._activeRoundId !== null && !sessionExpired) {
+          this.sendError(id, 'ACTIVE_SESSION_EXISTS', 'an active game session already exists');
+          return;
+        }
+        if (sessionExpired) {
+          // Drop stale session state so a fresh non-session action can proceed.
+          this.clearSessionState();
+        }
+      }
+
       // Compute the debit amount for this action — mirrors the platform's
       // server-side rules so Buy Bonus / Ante Bet actions debit the right
       // multiple of bet instead of just the base bet.
       const debit = this.computeDebit(action, bet, params);
+
+      // Server returns 402 INSUFFICIENT_FUNDS before the wallet is touched
+      // and never reaches the engine. DevBridge must do the same so the
+      // SDK's play() rejects with the right SDKError code.
+      if (debit > this._balance) {
+        this.sendError(
+          id,
+          'INSUFFICIENT_FUNDS',
+          `insufficient funds (need ${debit}, have ${this._balance})`,
+        );
+        return;
+      }
+
       this._balance -= debit;
 
-      this.executeLuaOnServer({ action, bet, roundId, params })
+      // Round id rules mirror server's playRound:
+      //   non-session  → fresh UUID, client-supplied id is ignored
+      //   session-based → reuse the active session's round id
+      const serverRoundId = actionDef.requires_session
+        ? this._activeRoundId!
+        : generateRoundId();
+
+      this.executeLuaOnServer({ action, bet, roundId: serverRoundId, params })
         .then((result) => {
+          this._lastPlayResult = result;
+          this.updateSessionState(result);
           this._bridge?.send('PLAY_RESULT', result, id);
         })
         .catch((err) => {
           console.error('[DevBridge] Lua server error:', err);
           this._balance += debit;
-          this._bridge?.send('PLAY_RESULT', this.buildFallbackResult(action, bet, roundId), id);
+          this.sendError(id, 'ENGINE_ERROR', err?.message ?? 'lua execution failed');
         });
     } else {
       // Fallback to onPlay callback
+      const { roundId } = payload;
       const customResult = this._config.onPlay({ action, bet, roundId, params });
       const totalWin = customResult.totalWin ?? (Math.random() > 0.6 ? bet * (1 + Math.random() * 10) : 0);
 
@@ -215,81 +341,66 @@ export class DevBridge {
         gameId: this._config.gameConfig?.id ?? 'dev-game',
       };
 
+      this._lastPlayResult = result;
       this.delayedSend('PLAY_RESULT', result, id);
     }
   }
 
+  /** Send a PLAY_ERROR correlated to the original PLAY_REQUEST id. */
+  private sendError(id: string | undefined, code: string, message: string): void {
+    this._bridge?.send('PLAY_ERROR', { code, message }, id);
+  }
+
+  /**
+   * Refresh tracked session state from the latest PlayResult.
+   *  - new/ongoing session → remember roundId + (re)set expiry
+   *  - completed/no session → clear tracking
+   */
+  private updateSessionState(result: PlayResultData): void {
+    const session = result.session;
+    if (session && !session.completed) {
+      if (this._activeRoundId === null) {
+        this._activeRoundId = result.roundId;
+        this._sessionExpiresAt = Date.now() + this._sessionTtlMs;
+      }
+    } else {
+      this.clearSessionState();
+    }
+  }
+
+  /** Drop active-session tracking (called on completion or expiry sweep). */
+  private clearSessionState(): void {
+    this._activeRoundId = null;
+    this._sessionExpiresAt = null;
+  }
+
   /**
    * Compute the wallet debit for a play request, mirroring the platform's
-   * server-side rules:
-   *   - debit: 'bet'             → bet
-   *   - debit: 'buy_bonus_cost'  → bet × buy_bonus.modes[mode].cost_multiplier
-   *   - debit: 'ante_bet_cost'   → bet × ante_bet.cost_multiplier
-   *   - debit: 'none'            → 0  (session continuations, e.g. free spins)
-   *
-   * Without a gameDefinition (or when the action is unknown), falls back to
-   * `bet` and warns. This is the dev-mode behavior the previous
-   * implementation always used for every action — kept here as a safe
-   * default so existing setups don't silently change semantics.
+   * v5 ActionDefinition.DebitAmount:
+   *   - debit: 'bet'           → bet × (cost_multiplier || 1)
+   *   - debit: 'none'/missing  → 0
+   *   - any other value        → 0 (legacy v4 modes like 'buy_bonus_cost'
+   *                                are no longer recognized; surfacing as 0
+   *                                forces config breakage to the surface)
    *
-   * Note: in the platform protocol the client sends the *base* bet only
-   * (`PlayParams.bet`); the cost multiplier lives in the GameDefinition.
-   * Session continuations (free_spin, feature_spin) must be invoked with
-   * `bet: 0` — LuaEngine pulls the active session's bet from the persisted
-   * session state.
+   * The action carries its own cost (cost_multiplier + opaque feature_data).
+   * No top-level buy_bonus/ante_bet blocks. No params.ante_bet flag — ante
+   * is just a separate action with its own cost_multiplier.
    */
   private computeDebit(
     action: string,
     bet: number,
-    params: Record<string, unknown> | undefined,
+    _params: Record<string, unknown> | undefined,
   ): number {
-    const def = this._config.gameDefinition;
-    const actionDef = def?.actions?.[action];
-
-    if (!def || !actionDef) {
-      if (this._config.debug) {
-        console.warn(`[DevBridge] Unknown action "${action}" — debiting base bet as fallback.`);
-      }
-      return bet;
+    const actionDef = this._config.gameDefinition?.actions?.[action];
+    if (!actionDef || actionDef.debit !== 'bet') {
+      return 0;
     }
-
-    switch (actionDef.debit) {
-      case 'none':
-        return 0;
-      case 'buy_bonus_cost': {
-        const modeName = actionDef.buy_bonus_mode;
-        const mode = modeName ? def.buy_bonus?.modes?.[modeName] : undefined;
-        if (!mode) {
-          console.warn(
-            `[DevBridge] Action "${action}" has debit: "buy_bonus_cost" but no matching buy_bonus mode (${modeName ?? '<unset>'}). Falling back to base bet.`,
-          );
-          return bet;
-        }
-        return bet * mode.cost_multiplier;
-      }
-      case 'ante_bet_cost': {
-        const multiplier = def.ante_bet?.cost_multiplier;
-        if (typeof multiplier !== 'number') {
-          console.warn(
-            `[DevBridge] Action "${action}" has debit: "ante_bet_cost" but no ante_bet.cost_multiplier defined. Falling back to base bet.`,
-          );
-          return bet;
-        }
-        return bet * multiplier;
-      }
-      case 'bet':
-      default: {
-        // The platform also debits ante_bet pricing on regular `bet` actions
-        // when the client signals it via params.ante_bet. Mirror that here.
-        if (params && (params as Record<string, unknown>)['ante_bet'] === true) {
-          const multiplier = def.ante_bet?.cost_multiplier;
-          if (typeof multiplier === 'number') {
-            return bet * multiplier;
-          }
-        }
-        return bet;
-      }
+    const mult = actionDef.cost_multiplier;
+    if (typeof mult === 'number' && mult > 0 && mult !== 1) {
+      return bet * mult;
     }
+    return bet;
   }
 
   private async executeLuaOnServer(params: PlayParams): Promise<PlayResultData> {
@@ -322,22 +433,9 @@ export class DevBridge {
       data: luaResult.data,
       nextActions: luaResult.nextActions,
       session: luaResult.session,
-      creditPending: !shouldCredit,
-      bonusFreeSpin: null,
-      currency: this._config.currency,
-      gameId: this._config.gameConfig?.id ?? 'dev-game',
-    };
-  }
-
-  private buildFallbackResult(action: string, bet: number, roundId?: string): PlayResultData {
-    return {
-      roundId: roundId ?? `dev-round-${this._roundCounter}`,
-      action,
-      balanceAfter: this._balance,
-      totalWin: 0,
-      data: { error: 'Lua execution failed' },
-      nextActions: ['spin'],
-      session: null,
+      // creditPending=true on the wire means "wallet credit failed, queued
+      // for retry" — not "credit deferred until session completes". DevBridge
+      // never simulates credit failures, so this is always false.
       creditPending: false,
       bonusFreeSpin: null,
       currency: this._config.currency,
@@ -356,7 +454,14 @@ export class DevBridge {
   }
 
   private handleGetState(id?: string): void {
-    this.delayedSend('STATE_RESPONSE', { session: this._config.session ?? null }, id);
+    // Mirror the platform's GET /games/{id}/session: the response wraps the
+    // last PlayResult-shaped snapshot, which the SDK reads back as
+    // `payload.session.session` (SessionData) and `payload.session.balanceAfter`.
+    // Only surface it while a session is active and not yet completed —
+    // matches GameUseCase.GetActiveSession.
+    const last = this._lastPlayResult;
+    const session = last && last.session && !last.session.completed ? last : null;
+    this.delayedSend('STATE_RESPONSE', { session }, id);
   }
 
   private handleOpenDeposit(): void {

package/src/index.ts

@@ -72,9 +72,6 @@ export type {
   LuaEngineConfig,
   LuaPlayResult,
   MaxWinConfig,
-  BuyBonusConfig,
-  BuyBonusMode,
-  AnteBetConfig,
   PersistentStateConfig,
   BetLevelsConfig,
   SimulationConfig,

package/src/lua/LuaEngine.ts

@@ -1,5 +1,5 @@
 import type { PlayParams, SessionData } from '@energy8platform/game-sdk';
-import type { LuaEngineConfig, LuaPlayResult, GameDefinition } from './types';
+import type { LuaEngineConfig, LuaPlayResult, GameDefinition, ActionDefinition } from './types';
 import { LuaEngineAPI, createSeededRng, luaToJS, pushJSValue, cachedToLuastring } from './LuaEngineAPI';
 import { ActionRouter } from './ActionRouter';
 import { SessionManager } from './SessionManager';
@@ -153,25 +153,16 @@ export class LuaEngine {
     const gameDataParams = this.persistentState.getGameDataParams();
     Object.assign(stateParams, gameDataParams);
 
-    // Handle buy bonus
-    if (action.buy_bonus_mode && this.gameDefinition.buy_bonus) {
-      const mode = this.gameDefinition.buy_bonus.modes[action.buy_bonus_mode];
-      if (mode) {
-        stateParams.buy_bonus = true;
-        stateParams.buy_bonus_mode = action.buy_bonus_mode;
-        if (mode.scatter_distribution) {
-          stateParams.forced_scatter_count = this.pickFromDistribution(mode.scatter_distribution);
-        }
-      }
-    }
-
-    // Handle ante bet
-    if (clientParams?.ante_bet && this.gameDefinition.ante_bet) {
-      stateParams.ante_bet = true;
+    // v5: forced scatter rolls come from the action's own feature_data.
+    // Output of the roll stays in state.params (it's random per-call), while
+    // the static config flows through state.action_config.feature_data.
+    const scatterDist = readScatterDistribution(action.feature_data);
+    if (scatterDist) {
+      stateParams.forced_scatter_count = this.pickFromDistribution(scatterDist);
     }
 
     // 5. Execute Lua (server: executor.Execute(stage, state))
-    const luaResult = this.callLuaExecute(action.stage, actionName, stateParams, stateVars);
+    const luaResult = this.callLuaExecute(action.stage, actionName, stateParams, stateVars, action);
 
     // 6. Process result (server: ApplyLuaResult)
     const totalWinMultiplier = typeof luaResult.total_win === 'number' ? luaResult.total_win : 0;
@@ -193,6 +184,12 @@ export class LuaEngine {
       }
     }
 
+    // Apply MapState parity — server's state_mapper.go injects these
+    // variable-derived keys into the client data so scripts don't have to
+    // surface them manually. Lua-provided values take precedence (server
+    // also overwrites variable-derived keys with state.Data on merge).
+    this.applyMapStateInjection(stateVars, data);
+
     // 7. Handle _persist_* and _persist_game_* keys
     this.sessionManager.storePersistData(data);
     this.persistentState.storeGameData(data);
@@ -214,7 +211,8 @@ export class LuaEngine {
     }
 
     // 8. Evaluate transitions (server uses state.Variables which is stateVars)
-    const { rule, nextActions } = this.actionRouter.evaluateTransitions(action, stateVars);
+    const { rule } = this.actionRouter.evaluateTransitions(action, stateVars);
+    let nextActions = rule.next_actions;
 
     // 9. Determine credit behavior (server: creditNow logic)
     let creditDeferred = action.credit === 'defer' || rule.credit_override === 'defer';
@@ -227,9 +225,15 @@ export class LuaEngine {
     // Calculate max win cap for session
     const maxWinCap = this.calculateMaxWinCap(bet);
 
+    // Snapshot the round data for history (matches server's MapStateForHistory:
+    // strip _persist_* keys, but those are already removed below before
+    // returning — at this point in the flow they may still be in `data`,
+    // so we filter inline).
+    const roundData = stripPersistKeys(data);
+
     if (rule.creates_session && !this.sessionManager.isActive) {
       // CREATE SESSION — initial spin counted (server: createSession includes spinWin)
-      session = this.sessionManager.createSession(rule, stateVars, bet, spinWin, maxWinCap);
+      session = this.sessionManager.createSession(rule, stateVars, bet, spinWin, maxWinCap, roundData);
       creditDeferred = true;
       resultTotalWin = spinWin;
 
@@ -239,16 +243,23 @@ export class LuaEngine {
       }
     } else if (this.sessionManager.isActive) {
       // UPDATE SESSION — accumulate win, check completion
-      session = this.sessionManager.updateSession(rule, stateVars, spinWin);
+      session = this.sessionManager.updateSession(rule, stateVars, spinWin, roundData);
 
       if (session?.completed) {
-        // SESSION COMPLETED — server returns session.TotalWin as result.TotalWin
+        // SESSION COMPLETED — server returns session.TotalWin as result.TotalWin,
+        // and pulls next_actions from the explicit completion transition
+        // (findCompletionNextActions) rather than the matched 'continue' rule.
         const completed = this.sessionManager.completeSession();
         session = completed.session;
         resultTotalWin = completed.totalWin;
         sessionCompleted = true;
         creditDeferred = false;
 
+        const completionNext = findCompletionNextActions(action);
+        if (completionNext) {
+          nextActions = completionNext;
+        }
+
         // Clean up session-scoped variables
         for (const varName of completed.sessionVarNames) {
           delete this.variables[varName];
@@ -315,11 +326,12 @@ export class LuaEngine {
     action: string,
     params: Record<string, unknown>,
     variables: Record<string, number>,
+    actionDef: ActionDefinition,
   ): Record<string, unknown> {
     lua.lua_getglobal(this.L, cachedToLuastring('execute'));
 
-    // Build state table: {stage, action, params, variables}
-    lua.lua_createtable(this.L, 0, 4);
+    // Build state table: {stage, action, action_config, params, variables}
+    lua.lua_createtable(this.L, 0, 5);
 
     // state.stage
     lua.lua_pushstring(this.L, cachedToLuastring(stage));
@@ -329,6 +341,18 @@ export class LuaEngine {
     lua.lua_pushstring(this.L, cachedToLuastring(action));
     lua.lua_setfield(this.L, -2, cachedToLuastring('action'));
 
+    // state.action_config — v5: { cost_multiplier, feature_data }.
+    // Server's lua_runtime.go substitutes 1.0 when cost_multiplier is unset
+    // so scripts never see 0; mirror that default.
+    const mult = typeof actionDef.cost_multiplier === 'number' && actionDef.cost_multiplier > 0
+      ? actionDef.cost_multiplier
+      : 1;
+    pushJSValue(this.L, {
+      cost_multiplier: mult,
+      feature_data: actionDef.feature_data ?? {},
+    });
+    lua.lua_setfield(this.L, -2, cachedToLuastring('action_config'));
+
     // state.params
     pushJSValue(this.L, params);
     lua.lua_setfield(this.L, -2, cachedToLuastring('params'));
@@ -386,6 +410,35 @@ export class LuaEngine {
     return result as Record<string, unknown>;
   }
 
+  /**
+   * Mirror server's state_mapper.go MapState — surface variable-derived
+   * fields so scripts that don't manually echo them in the result table
+   * still produce a server-shaped data map. Lua keys win on conflict.
+   */
+  private applyMapStateInjection(
+    vars: Record<string, number>,
+    data: Record<string, unknown>,
+  ): void {
+    const m = vars.multiplier;
+    if (typeof m === 'number' && m > 1 && data.multiplier === undefined) {
+      data.multiplier = m;
+    }
+
+    const gm = vars.global_multiplier;
+    if (typeof gm === 'number' && gm > 1 && data.global_multiplier === undefined) {
+      data.global_multiplier = gm;
+    }
+
+    const fs = vars.free_spins_remaining;
+    if (typeof fs === 'number' && fs > 0 && data.free_spins_total === undefined) {
+      data.free_spins_total = Math.trunc(fs);
+    }
+
+    if (vars.max_win_reached === 1 && data.max_win_reached === undefined) {
+      data.max_win_reached = true;
+    }
+  }
+
   private calculateMaxWinCap(bet: number): number | undefined {
     const mw = this.gameDefinition.max_win;
     if (!mw) return undefined;
@@ -410,3 +463,55 @@ export class LuaEngine {
     return parseInt(entries[entries.length - 1][0], 10);
   }
 }
+
+// ─── Module helpers ─────────────────────────────────────
+
+/**
+ * Pull a `scatter_distribution` map out of an action's feature_data, if any.
+ * Returns null when missing or wrong-shaped — caller falls through with no
+ * forced_scatter_count injection (matches server behavior).
+ */
+function readScatterDistribution(
+  featureData: Record<string, unknown> | undefined,
+): Record<string, number> | null {
+  if (!featureData) return null;
+  const dist = featureData['scatter_distribution'];
+  if (!dist || typeof dist !== 'object') return null;
+  const out: Record<string, number> = {};
+  for (const [k, v] of Object.entries(dist as Record<string, unknown>)) {
+    if (typeof v === 'number') out[k] = v;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * Strip _persist_* and _persist_game_* keys from a data map — matches
+ * server's MapStateForHistory used when recording session round history.
+ */
+function stripPersistKeys(data: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const k of Object.keys(data)) {
+    if (k.startsWith('_persist_') || k.startsWith('_persist_game_')) continue;
+    out[k] = data[k];
+  }
+  return out;
+}
+
+/**
+ * Mirror server's findCompletionNextActions: when a session naturally
+ * completes, the matched 'continue' rule's next_actions are NOT what
+ * the client should see — the explicit complete_session transition wins,
+ * with a fallback to the 'always' transition.
+ */
+function findCompletionNextActions(action: ActionDefinition): string[] | null {
+  let alwaysFallback: string[] | null = null;
+  for (const t of action.transitions) {
+    if (t.complete_session && t.next_actions && t.next_actions.length > 0) {
+      return t.next_actions;
+    }
+    if (t.condition.trim() === 'always' && t.next_actions && t.next_actions.length > 0 && alwaysFallback === null) {
+      alwaysFallback = t.next_actions;
+    }
+  }
+  return alwaysFallback;
+}

package/src/lua/SessionManager.ts

@@ -1,6 +1,13 @@
 import type { SessionData } from '@energy8platform/game-sdk';
 import type { TransitionRule } from './types';
 
+/** Per-round history entry — wire shape mirrors server SessionInfo.History. */
+export interface SessionRound {
+  spinIndex: number;
+  win: number;
+  data: Record<string, unknown>;
+}
+
 interface SessionState {
   spinsRemaining: number;
   spinsPlayed: number;
@@ -13,6 +20,7 @@ interface SessionState {
   persistentVarNames: string[];
   persistentVars: Record<string, number>;
   persistentData: Record<string, unknown>;
+  history: SessionRound[];
 }
 
 const MAX_SESSION_SPINS = 200;
@@ -56,7 +64,8 @@ export class SessionManager {
 
   /**
    * Create a new session from a transition rule.
-   * Server behavior: initial spin is already counted (spinsPlayed=1, totalWin includes spinWin).
+   * Server behavior: initial spin is already counted (spinsPlayed=1, totalWin includes spinWin),
+   * and history[0] holds the trigger spin's data.
    */
   createSession(
     rule: TransitionRule,
@@ -64,6 +73,7 @@ export class SessionManager {
     bet: number,
     spinWin: number,
     maxWinCap: number | undefined,
+    triggerData: Record<string, unknown>,
   ): SessionData {
     let spinsRemaining = -1;
     let spinsVarName: string | undefined;
@@ -90,6 +100,7 @@ export class SessionManager {
       persistentVarNames,
       persistentVars,
       persistentData: {},
+      history: [{ spinIndex: 0, win: spinWin, data: triggerData }],
     };
 
     return this.toSessionData();
@@ -104,9 +115,18 @@ export class SessionManager {
     rule: TransitionRule,
     variables: Record<string, number>,
     spinWin: number,
+    roundData: Record<string, unknown>,
   ): SessionData {
     if (!this.session) throw new Error('No active session');
 
+    // Append history with PRE-increment spin index (matches server's
+    // updateSession: append round, THEN increment SpinsPlayed).
+    this.session.history.push({
+      spinIndex: this.session.spinsPlayed,
+      win: spinWin,
+      data: roundData,
+    });
+
     // Accumulate win and count spin
     this.session.totalWin += spinWin;
     this.session.spinsPlayed++;
@@ -222,6 +242,8 @@ export class SessionManager {
       completed: this.session.completed,
       maxWinReached: this.session.maxWinReached,
       betAmount: this.session.bet,
+      // Snapshot the array so downstream mutation can't corrupt internal state.
+      history: [...this.session.history],
     };
   }
 }