@energy8platform/game-engine 0.17.0 → 0.18.0

package/src/host/createSlotGame.ts

@@ -0,0 +1,423 @@
+// packages/game-engine/src/host/createSlotGame.ts
+import { GameApplication } from '../core';
+import { buildAppConfig } from './buildConfig';
+import { loadFonts, applyTextureDefaults, bootGuard } from './preboot';
+import { showFatalError, installGlobalErrorHandlers } from './fatalError';
+import type { CreateSlotGameOptions, SlotGameHandle } from './types';
+import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+import type { ShellMode } from '@energy8platform/platform-core/shell';
+
+/**
+ * One-call slot bootstrap: preboot → (optional Stake bridge) → GameApplication
+ * → register scene → start. Collapses the per-game main.ts boilerplate.
+ *
+ * Not unit-tested: GameApplication.init() drives Pixi, which hangs in headless
+ * environments. The pure helpers it sequences are unit-tested individually.
+ */
+export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResultBase>(
+  opts: CreateSlotGameOptions<T>,
+): Promise<SlotGameHandle> {
+  if (!bootGuard()) throw new Error('createSlotGame() called more than once');
+
+  if (opts.textureDefaults) applyTextureDefaults();
+  await loadFonts(opts.fonts);
+
+  // Declared up front so `fatal` can route errors through the shell's own modal once it exists.
+  let shell: SlotGameHandle['shell'] = null;
+
+  const fatal = (message: string) => {
+    if (opts.onFatalError) return opts.onFatalError(message);
+    // Once the shell is up, use ITS branded modal (consistent chrome, social vocabulary, fit
+    // scaling) rather than the bare DOM fallback. Errors thrown before the shell boots (asset
+    // load, SDK handshake) still get the standalone overlay.
+    if (shell) {
+      shell.openModal({
+        availableClose: false,
+        title: shell.t('Something went wrong'),
+        body: shell.t(message),
+        actions: [{ title: shell.t('Reload'), on: () => { try { location.reload(); } catch { /* non-browser */ } } }],
+      });
+      return;
+    }
+    showFatalError(opts.container ?? '#game', message);
+  };
+
+  // Global safety net: surface ANY uncaught error / unhandled rejection (e.g. an
+  // `Uncaught (in promise) SDKError` on spin) through the same fatal modal so games
+  // don't have to handle errors themselves. Honours the onFatalError override.
+  installGlobalErrorHandlers(opts.container ?? '#game', fatal);
+
+  let stakeBridge: SlotGameHandle['stakeBridge'] = null;
+  let isStakeNow = false;
+  if (opts.stake) {
+    const { isStakeLaunch } = await import('@energy8platform/stake-bridge/detect');
+    isStakeNow = isStakeLaunch(location.href);
+    if (isStakeNow) {
+      try {
+        const { StakeBridge } = await import('@energy8platform/stake-bridge');
+        stakeBridge = new StakeBridge({
+          devMode: true,
+          // In the dev harness the iframe is served over http and the dev-RGS
+          // lives at the same (http) origin; force the matching scheme so
+          // RGSClient can reach it. Prod (https) is unaffected.
+          protocol: location.protocol === 'http:' ? 'http' : 'https',
+          adapter: opts.stake.adapter,
+          modeMap: opts.model.modeMap,
+          gameId: opts.model.spec.id,
+          url: location.href,
+        });
+        await stakeBridge.ready();
+      } catch (err) {
+        fatal('Could not connect to the game server. Please reload.');
+        throw err;
+      }
+    }
+  }
+
+  const game = new GameApplication(buildAppConfig(opts, isStakeNow));
+
+  // Register EVERY scene up front so any of them can navigate to any other.
+  for (const { key, scene } of opts.scenes) game.scenes.register(key, scene);
+
+  // Navigation injected into the start data of every scene: a scene reads `goto`
+  // from its `onEnter(data)` and calls it to switch scenes (intro → game, etc.).
+  const goto = (key: string, data?: unknown) => {
+    void game.scenes.goto(key, { ...(data as object), goto });
+  };
+
+  // Pick the start scene from the ordered list + launch mode: a replay launch skips any leading
+  // `skipOnReplay` scene (the intro) and starts directly on the game scene.
+  const { resolveStartScene } = await import('./sceneStart');
+  const startScene = resolveStartScene(opts.scenes, !!stakeBridge?.isReplay, opts.startScene);
+
+  try {
+    await game.start(startScene, { ...(opts.startData as object), goto });
+  } catch (err) {
+    fatal('Could not start the game.');
+    throw err;
+  }
+
+  let currentBet = opts.model.spec.defaultBet ?? opts.model.spec.betLevels[0];
+
+  // Build slotPlay FIRST — bindGameScene() needs it to be in scope.
+  const { createSlotPlay, enrichRoundMeta } = await import('./slotPlay');
+
+  /** The current scene IFF it implements the SlotSceneController contract (duck-typed on
+   *  `present`). The host drives the play loop against whichever scene is current. */
+  const gameScene = () => {
+    const s = game.scenes.current?.scene as
+      | Partial<import('./sceneController').SlotSceneController<T>>
+      | undefined;
+    return typeof s?.present === 'function'
+      ? (s as import('./sceneController').SlotSceneController<T>)
+      : undefined;
+  };
+
+  const { runRound } = await import('./runRound');
+  const { createBalanceGate } = await import('./balanceGate');
+  const { createFreeSpinsCounter } = await import('./freeSpinsCounter');
+  const { resolvePlayError } = await import('./playError');
+
+  // slotPlay references shell via closure — define it after shell is assigned below.
+  // We use a late-binding wrapper so the closure captures the variable, not null.
+  const slotPlay = createSlotPlay<T>({
+    play: (p) => game.platformSession!.play(p),
+    normalize: opts.normalize,
+    // ACK the result AFTER the scene animates it (the scene calls host.ack()). On Stake this
+    // triggers /wallet/end-round so a winning round settles post-animation instead of staying
+    // open and blocking the next spin.
+    ack: (raw) => game.platformSession!.playAck(raw as import('@energy8platform/platform-core').PlayResultData),
+  });
+
+  if (opts.shell) {
+    const { createGameShell } = await import('@energy8platform/platform-core/shell');
+    const { buildShellConfig } = await import('./shellConfig');
+    const { resolveReplayBonusId } = await import('./replay');
+
+    const ps = game.platformSession;
+    const balance = (game.initData?.balance as number | undefined) ?? 0;
+    const isReplay = !!stakeBridge?.isReplay;
+    const mode: ShellMode = isReplay ? 'replay' : 'base';
+    // initData.config carries the Stake bridge's currency/social/disclaimer surface (GameConfigData);
+    // all are absent in non-stake/dev launches → graceful fallbacks downstream.
+    const initData = game.initData as {
+      config?: {
+        socialMode?: boolean;
+        disclaimerLines?: string[];
+        currency?: { code: string; symbol: string; decimals: number; symbolAfter?: boolean };
+        jurisdiction?: import('./shellConfig').JurisdictionRestrictions;
+        betLevels?: number[];
+        defaultBet?: number;
+        stake?: { defaultBetLevel?: number };
+      };
+      lang?: string;
+    } | null;
+    const config = initData?.config;
+    const { resolveCurrency } = await import('./shellConfig');
+    // SINGLE source of truth for the symbol: the Stake bridge already puts a full CurrencyMetaData
+    // (symbol + placement) on initData.config.currency. In the non-stake/devBridge path that meta
+    // is absent and we only have the spec's currency CODE — resolve it through the SAME table
+    // (stake-bridge's lookupCurrency) so e.g. 'EUR' renders as '€', not the literal text "EUR".
+    // stake-bridge ships with every scaffold; if it's somehow absent we degrade to the code.
+    let currencyMeta = config?.currency;
+    if (!currencyMeta?.symbol && opts.model.spec.currency) {
+      try {
+        const { lookupCurrency } = await import('@energy8platform/stake-bridge');
+        currencyMeta = lookupCurrency(opts.model.spec.currency);
+      } catch { /* stake-bridge not installed — resolveCurrency falls back to the code */ }
+    }
+    const runtime = {
+      balance,
+      currency: resolveCurrency(currencyMeta, opts.model.spec.currency),
+      language: initData?.lang,
+      mode,
+      social: config?.socialMode,
+      disclaimerLines: config?.disclaimerLines,
+      jurisdiction: config?.jurisdiction,
+      // Currency-specific ladder + per-currency default from /wallet/authenticate (Stake);
+      // absent on dev/devBridge → buildShellConfig falls back to the spec.
+      betLevels: config?.betLevels,
+      defaultBet: config?.stake?.defaultBetLevel ?? config?.defaultBet,
+    };
+    if (opts.dev) {
+      // Dev-only diagnostic. Logged as PLAIN STRINGS (not collapsed objects) so the values are
+      // readable in the console without expanding. If the shown symbol is a bare code ("EUR")
+      // instead of a glyph ("€"), paste this whole line.
+      const cc = config?.currency as { code?: string; symbol?: string } | undefined;
+      console.info(
+        `[e8] currency → bridge.code=${cc?.code ?? '∅'} bridge.symbol=${cc?.symbol ?? '∅'} ` +
+        `| spec=${opts.model.spec.currency ?? '∅'} ` +
+        `| RESOLVED.symbol=${runtime.currency?.symbol ?? '∅'} pos=${runtime.currency?.position ?? '∅'}`,
+      );
+    }
+    shell = createGameShell(buildShellConfig(opts.shell, opts.model, runtime));
+    // The gate tracks the live wallet (for the affordability guard) but only PAINTS the balance per
+    // the HUD-timing rule: the debit is buffered during play→present and shown at afterPresent; the
+    // async win credit (/wallet/end-round, after the final ack) paints when it lands. `balanceGate`
+    // is the single source for both the displayed balance and `ensureAffordable`.
+    const balanceGate = createBalanceGate((b) => shell!.setBalance(b), balance);
+    ps?.on('balanceUpdate', (d: { balance: number }) => { balanceGate.onBalance(d.balance); });
+
+    // Live turbo level (0..3) — read fresh on each ctx.turbo access so a mid-round toggle is honoured.
+    let currentTurbo = shell.state.turbo;
+    shell.on('turboChange', (level: number) => { currentTurbo = level; });
+
+    const roleOf = (action: string) => opts.model.spec.actions[action]?.role;
+    const makeContext = (action: string): import('./sceneController').RenderContext => ({
+      bet: currentBet,
+      action,
+      mode: opts.model.modeMap[action] ?? action.toUpperCase(),
+      formatAmount: (v) => shell!.formatWin(v),
+      get turbo() { return currentTurbo; },
+    });
+    // Play-error + connection handling. A play rejection is classified into a player-facing modal
+    // (ACTIVE_SESSION_EXISTS → Reload, etc.) instead of a misleading reconnect overlay; the reconnect
+    // overlay is suppressed while a play-error modal owns the screen.
+    let playErrorOpen = false;
+    let stopAutoplay: () => void = () => {}; // wired to the autoplay loop once it's created (below)
+    const showPlayError = (err: unknown): void => {
+      stopAutoplay(); // a play error halts an autoplay run (the .catch swallows, so stop explicitly)
+      const v = resolvePlayError(err);
+      playErrorOpen = true;
+      shell!.openModal({
+        availableClose: !v.reload,
+        title: shell!.t(v.title),
+        body: shell!.t(v.body),
+        actions: v.reload
+          ? [{ title: shell!.t('Reload'), on: () => { try { window.location.reload(); } catch { /* non-browser */ } } }]
+          : [{ title: shell!.t('OK'), on: () => { playErrorOpen = false; } }],
+      });
+    };
+    ps?.on('connectionStateChanged', (s: { status: string }) => {
+      if (s.status === 'restored') { if (!playErrorOpen) shell!.closeModal(); return; }
+      if (playErrorOpen) return; // a play-error modal owns the screen — don't mask it with "reconnecting"
+      shell!.openModal({
+        availableClose: false,
+        title: shell!.t('Reconnecting…'),
+        body: shell!.t('Lost connection to the game server. Trying to reconnect…'),
+      });
+    });
+
+    /** Drive a full round (trigger + drain) against the current scene. HUD readouts (win + balance)
+     *  update only AFTER each present(), per the HUD-timing requirement. */
+    const playRound = (action: string) => {
+      const scene = gameScene();
+      if (!scene) return;
+      // Per-round free-spins state: the shell enters FS mode on bonus-enter and shows current/total
+      // (growing on retriggers) + cumulative win per spin. `inBonus` gates the per-spin counter so
+      // the trigger segment (presented before onBonusEnter) doesn't count as a free spin.
+      let inBonus = false;
+      let prevWin = 0; // cumulative win up to the previous segment — the WIN readout shows the delta
+      const fsCounter = createFreeSpinsCounter();
+      shell!.setBusy(true); // block re-spin / spacebar while the round plays out
+      // RETURN the promise: the replay modal awaits onReplay() and only reopens once the round's
+      // animation has finished — returning void would reopen it instantly, over a running animation.
+      return runRound<T>(
+        {
+          // Suppress the debit paint from play() until this segment's afterPresent (HUD timing).
+          play: (a, b, rid) => { balanceGate.beginPlay(); return slotPlay.play(a, b, rid); },
+          ack: slotPlay.ack,
+          scene,
+          context: makeContext,
+          roleOf,
+          afterPresent: (r) => {
+            // WIN readout = THIS spin's win (cumulative delta); the cumulative total goes to the
+            // free-spins counter (totalWin) below, not the WIN readout.
+            shell!.setWin(r.totalWin - prevWin);
+            prevWin = r.totalWin;
+            balanceGate.afterPresent();
+            if (inBonus) shell!.setFreeSpins(fsCounter.spin(r.freeSpins?.awarded ?? 0, r.totalWin));
+          },
+          onBonusEnter: async (trigger, ctx) => {
+            inBonus = true;
+            shell!.setMode('freeSpins');
+            shell!.setFreeSpins(fsCounter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0));
+            await scene.onBonusEnter?.(trigger, ctx);
+          },
+          onBonusExit: async (last, ctx) => {
+            inBonus = false;
+            await scene.onBonusExit?.(last, ctx);
+            shell!.setMode('base');
+          },
+        },
+        action,
+      ).catch(showPlayError).finally(() => shell!.setBusy(false));
+    };
+
+    /**
+     * Drain a recovered open round to completion and settle it. Plays EVERY remaining segment from
+     * the bonus start (Continue animates each; Finish fast-forwards without animation), reaching the
+     * final ack so /wallet/end-round credits the win — fixing the old resume that presented one
+     * snapshot and never settled. The original trigger is gone on reload, so the FS counter here uses
+     * the bridge's session counts; FS mode is entered/exited around the drain.
+     */
+    const resumeDrain = async (
+      firstRaw: import('@energy8platform/platform-core').PlayResultData,
+      animate: boolean,
+    ): Promise<void> => {
+      const scene = gameScene();
+      if (!scene || !ps) return;
+      const ctx = makeContext((firstRaw as { action?: string }).action ?? 'spin');
+      const fsView = (raw: unknown, totalWin: number) => {
+        const s = (raw as { session?: { spinsPlayed?: number; spinsRemaining?: number } }).session;
+        if (!s) return null;
+        // The bridge session counts ALL segments incl. the trigger (segment 0); the free-spins
+        // counter is over FREE spins only, so drop the one trigger segment → 1/10, not 2/11.
+        const played = s.spinsPlayed ?? 0;
+        const current = Math.max(0, played - 1);
+        const total = Math.max(0, played + (s.spinsRemaining ?? 0) - 1);
+        return { current, total, totalWin };
+      };
+      let raw = firstRaw;
+      let r = enrichRoundMeta(opts.normalize(raw), raw);
+      let inBonus = false;
+      let prevWin = 0; // cumulative win up to the previous segment — WIN readout shows the delta
+      const applySegment = async (): Promise<void> => {
+        // A recovered open round with remaining segments is a bonus → show FS mode + counter.
+        if (!inBonus && !r.complete) { inBonus = true; shell!.setMode('freeSpins'); }
+        if (animate) await scene.present(r, ctx);
+        if (inBonus) { const v = fsView(raw, r.totalWin); if (v) shell!.setFreeSpins(v); }
+        shell!.setWin(r.totalWin - prevWin); // THIS spin's win, not the cumulative bonus total
+        prevWin = r.totalWin;
+        ps!.playAck(raw); // settles via /wallet/end-round on the FINAL segment
+      };
+      shell!.setBusy(true); // block input while the recovered round drains
+      try {
+        await applySegment();
+        while (!r.complete && r.nextActions && r.nextActions.length > 0) {
+          raw = (await ps.play({ action: r.nextActions[0], bet: ctx.bet, roundId: r.roundId })) as
+            import('@energy8platform/platform-core').PlayResultData;
+          r = enrichRoundMeta(opts.normalize(raw), raw);
+          await applySegment();
+        }
+        if (inBonus) shell!.setMode('base');
+      } finally {
+        shell!.setBusy(false);
+      }
+    };
+
+    if (mode === 'base') {
+      let activeFeature: string | null = null;
+      shell.on('featureActivate', ({ id }: { id: string }) => { activeFeature = id; });
+      shell.on('featureDeactivate', ({ id: _id }: { id: string }) => { activeFeature = null; });
+
+      const { stakeForAction } = await import('./shellConfig');
+      // Guard a play: if the stake exceeds the balance, show a shell modal and DON'T play.
+      const ensureAffordable = (action: string): boolean => {
+        if (stakeForAction(opts.model, action, currentBet) <= balanceGate.balance + 1e-9) return true;
+        shell!.openModal({
+          availableClose: true,
+          title: shell!.t('Insufficient balance'),
+          body: shell!.t('You don’t have enough balance for this bet. Lower your bet or top up.'),
+          actions: [{ title: shell!.t('OK') }],
+        });
+        return false;
+      };
+
+      shell.on('spin', () => {
+        const action = activeFeature ?? 'spin';
+        if (!ensureAffordable(action)) return;
+        void playRound(action);
+      });
+      shell.on('betChange', (bet: number) => { currentBet = bet; });
+      shell.on('buyBonusSelect', ({ id }: { id: string }) => {
+        if (!ensureAffordable(id)) return;
+        void playRound(id);
+      });
+
+      // Autoplay: the shell owns the picker/confirm/STOP/counter/lockout (all driven by state.autoplay);
+      // the host just runs the loop and pushes the per-spin remaining back via setAutoplay.
+      const { createAutoplayLoop } = await import('./autoplay');
+      const autoplay = createAutoplayLoop({
+        resolveAction: () => activeFeature ?? 'spin',
+        canAfford: (a) => ensureAffordable(a),
+        playRound: (a) => Promise.resolve(playRound(a)),
+        onState: (s) => shell!.setAutoplay(s),
+      });
+      stopAutoplay = () => autoplay.stop();
+      shell.on('autoplayStart', (o: { remaining?: number }) => autoplay.start(o?.remaining ?? 0));
+      shell.on('autoplayStop', () => autoplay.stop());
+
+      // Resume offer: when the game scene is (or becomes) current on a reload, ask the host whether
+      // a round is still open. If so, offer Continue (replay its animation, then settle) or Finish
+      // (settle now). Settlement is the same playAck path a normal spin uses. Runs at most once.
+      let resumeOffered = false;
+      const offerResume = async () => {
+        if (resumeOffered || !shell || !gameScene()) return;
+        resumeOffered = true;
+        let snap: import('@energy8platform/platform-core').PlayResultData | null = null;
+        try { snap = await ps?.getState() ?? null; } catch { snap = null; }
+        if (!snap) return;
+        shell.openModal({
+          availableClose: false,
+          title: shell.t('Unfinished round'),
+          body: shell.t('You have an unfinished round. Continue it or finish it now?'),
+          actions: [
+            // Continue: replay the round from the start with animation, then settle.
+            { title: shell.t('Continue'), on: () => { void resumeDrain(snap!, true); } },
+            // Finish: fast-forward the remaining segments (no animation) to settle the win now.
+            { title: shell.t('Finish'), on: () => { void resumeDrain(snap!, false); } },
+          ],
+        });
+      };
+      game.scenes.on('change', () => { void offerResume(); });
+      void offerResume();
+    } else {
+      const stakeMode = stakeBridge?.replayMode ?? 'BASE';
+      const bonusId = resolveReplayBonusId(opts.model, stakeMode);
+      // The replayed round's OWN bet + payout (fetched up front per Stake rules), not the spec's
+      // default bet — otherwise the replay modal always shows bet 1.
+      const replayBet = stakeBridge?.replayBet || currentBet;
+      currentBet = replayBet;
+      // onReplay only spins — the shell reopens the modal after it resolves; never call openReplay inside onReplay (double-open).
+      shell.openReplay({
+        bonusId,
+        bet: replayBet,
+        payoutMultiplier: stakeBridge?.replayPayoutMultiplier ?? 0,
+        onReplay: () => playRound(bonusId),
+      });
+    }
+  }
+
+  return { game, stakeBridge, shell };
+}

package/src/host/fatalError.ts

@@ -0,0 +1,104 @@
+// packages/game-engine/src/host/fatalError.ts
+
+/** Marker id so the modal is idempotent (first one wins; later calls replace its message). */
+const FATAL_ID = 'e8-fatal-error';
+
+/** Pure: extract a human-readable message from any thrown value / event reason. */
+export function fatalMessage(input: unknown): string {
+  if (input == null) return 'Something went wrong.';
+  if (typeof input === 'string') return input;
+  if (input instanceof Error) return input.message || input.name || 'Something went wrong.';
+  const anyIn = input as { message?: unknown; reason?: unknown };
+  if (typeof anyIn.message === 'string' && anyIn.message) return anyIn.message;
+  if (anyIn.reason != null) return fatalMessage(anyIn.reason);
+  try {
+    return String(input);
+  } catch {
+    return 'Something went wrong.';
+  }
+}
+
+/** Pure: build the modal overlay element (error text + a Reload button). */
+export function buildFatalErrorModal(message: string, onReload: () => void): HTMLElement {
+  const overlay = document.createElement('div');
+  overlay.id = FATAL_ID;
+  overlay.setAttribute('role', 'alertdialog');
+  overlay.style.cssText =
+    'position:fixed;inset:0;display:flex;align-items:center;justify-content:center;' +
+    'background:rgba(10,5,4,0.92);z-index:99999;font-family:system-ui,sans-serif;padding:24px';
+
+  const card = document.createElement('div');
+  card.style.cssText =
+    'max-width:420px;width:100%;background:#1a0f0a;border:1px solid #5a3a1e;border-radius:12px;' +
+    'padding:28px 24px;text-align:center;box-shadow:0 12px 40px rgba(0,0,0,0.6)';
+
+  const text = document.createElement('div');
+  text.className = 'e8-fatal-message';
+  text.style.cssText = 'color:#f0c98a;font:600 17px/1.4 system-ui,sans-serif;margin-bottom:22px';
+  text.textContent = message;
+
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = 'e8-fatal-reload';
+  button.textContent = 'Reload';
+  button.style.cssText =
+    'cursor:pointer;border:none;border-radius:8px;padding:12px 28px;font:600 15px system-ui,sans-serif;' +
+    'color:#1a0f0a;background:#f0c98a';
+  button.addEventListener('click', onReload);
+
+  card.appendChild(text);
+  card.appendChild(button);
+  overlay.appendChild(card);
+  return overlay;
+}
+
+/**
+ * Render a blocking fatal-error modal with a Reload button. Idempotent: if a modal is already
+ * shown, its message is replaced instead of stacking a second overlay.
+ */
+export function showFatalError(container: HTMLElement | string, message: string): void {
+  if (typeof document === 'undefined') return;
+  const host =
+    typeof container === 'string'
+      ? document.querySelector<HTMLElement>(container) ?? document.body
+      : container;
+
+  const existing = document.getElementById(FATAL_ID);
+  if (existing) {
+    const msg = existing.querySelector<HTMLElement>('.e8-fatal-message');
+    if (msg) msg.textContent = message;
+    return;
+  }
+
+  const overlay = buildFatalErrorModal(message, () => {
+    try {
+      location.reload();
+    } catch {
+      /* no-op in non-browser environments */
+    }
+  });
+  host.appendChild(overlay);
+}
+
+/**
+ * Install global handlers so ANY uncaught error or unhandled promise rejection surfaces the
+ * fatal modal (game devs don't have to handle errors themselves). `fatal` defaults to the
+ * built-in modal targeting `container`. Returns a disposer that removes the listeners.
+ */
+export function installGlobalErrorHandlers(
+  container: HTMLElement | string,
+  fatal: (message: string) => void = (m) => showFatalError(container, m),
+): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const onError = (e: ErrorEvent) => fatal(fatalMessage(e.error ?? e.message));
+  const onRejection = (e: PromiseRejectionEvent) => fatal(fatalMessage(e.reason));
+
+  window.addEventListener('error', onError);
+  window.addEventListener('unhandledrejection', onRejection);
+
+  return () => {
+    window.removeEventListener('error', onError);
+    window.removeEventListener('unhandledrejection', onRejection);
+  };
+}

package/src/host/freeSpinsCounter.ts

@@ -0,0 +1,44 @@
+/**
+ * Free-spins counter for the shell readout (current / total / totalWin), with RETRIGGER support.
+ *
+ * A bonus awards an initial pool of spins; a retrigger mid-bonus awards MORE. The full-event book
+ * already contains every segment (incl. retriggered spins), but the player-facing counter must grow
+ * dynamically: start at the awarded total, and each spin that awards extra bumps the total. The
+ * remaining spins the shell shows are `total - current`.
+ *
+ * Example (the canonical case): enter(10) → 0/10. After two spins → 2/10. The third spin retriggers
+ * +5 → 3/15 (i.e. 12 remaining). `awarded` per spin is the spins granted by THAT spin (0 normally,
+ * the retrigger amount on a retrigger). Pure + unit-testable; the host feeds it `result.freeSpins`.
+ */
+export interface FreeSpinsView {
+  /** Free spins played so far (1-based once spinning). */
+  current: number;
+  /** Total free spins awarded so far (initial + every retrigger). */
+  total: number;
+  /** Cumulative bonus win (the host passes the round's cumulative totalWin). */
+  totalWin: number;
+}
+
+export interface FreeSpinsCounter {
+  /** Bonus start: seed the total with the trigger's awarded spins. Resets current + totalWin. */
+  enter(awarded: number): FreeSpinsView;
+  /** One free spin presented: count it, fold in any retrigger `awarded`, carry the cumulative win. */
+  spin(awarded: number, totalWin: number): FreeSpinsView;
+}
+
+export function createFreeSpinsCounter(): FreeSpinsCounter {
+  let total = 0;
+  let current = 0;
+  return {
+    enter(awarded: number): FreeSpinsView {
+      total = awarded;
+      current = 0;
+      return { current, total, totalWin: 0 };
+    },
+    spin(awarded: number, totalWin: number): FreeSpinsView {
+      current += 1;
+      total += awarded; // a retrigger grows the pool
+      return { current, total, totalWin };
+    },
+  };
+}

package/src/host/index.ts

@@ -0,0 +1,18 @@
+// packages/game-engine/src/host/index.ts
+export { createSlotGame } from './createSlotGame';
+export type {
+  CreateSlotGameOptions,
+  SlotGameHandle,
+  StakeIntegration,
+  SceneRegistration,
+  SceneNavData,
+  SceneEntry,
+} from './types';
+export { buildShellConfig, stakeForAction } from './shellConfig';
+export type { SlotShellOptions } from './shellConfig';
+export { resolveReplayBonusId } from './replay';
+export { resolveStartScene } from './sceneStart';
+export type { SlotSceneController, RenderContext } from './sceneController';
+// Social-casino word-swap. The shell auto-socializes all gameInfo/buyBonus text in social mode;
+// authors only need this to socialize strings they render themselves (e.g. inside a custom DOM node).
+export { socialize } from '@energy8platform/platform-core/shell';

package/src/host/playError.ts

@@ -0,0 +1,64 @@
+/**
+ * Classify a play/settle error into a player-facing modal payload.
+ *
+ * The SDK rejects `play()` with an `SDKError` carrying a `.code` (e.g. `ACTIVE_SESSION_EXISTS`,
+ * `INSUFFICIENT_FUNDS`, `TIMEOUT`). The bridge ALSO emits a `connectionStateChanged: 'lost'` for
+ * some of these, which would otherwise surface a misleading "Reconnecting…" overlay while the real
+ * fix is "reload to resume". The host routes every play error through this classifier so the player
+ * sees the right message + action, and suppresses the connection overlay while a play-error modal
+ * is up.
+ *
+ * `reload: true` → the round must be recovered by reloading (an unfinished round blocks new plays);
+ * the modal offers a Reload button. Otherwise it's a dismissible OK.
+ */
+export interface PlayErrorView {
+  title: string;
+  body: string;
+  /** Offer a Reload action (the round can only be recovered by reloading). */
+  reload: boolean;
+}
+
+/** Pull a Stake/SDK error code off an unknown thrown value. */
+export function errorCode(err: unknown): string | undefined {
+  const code = (err as { code?: unknown })?.code;
+  return typeof code === 'string' ? code : undefined;
+}
+
+export function resolvePlayError(err: unknown): PlayErrorView {
+  const code = errorCode(err);
+  const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+  switch (code) {
+    case 'ACTIVE_SESSION_EXISTS':
+      return {
+        title: 'Round in progress',
+        body: 'You have an unfinished round. Reload to resume it.',
+        reload: true,
+      };
+    case 'NO_ACTIVE_SESSION':
+      return {
+        title: 'Round expired',
+        body: 'This round is no longer active. Reload to continue.',
+        reload: true,
+      };
+    case 'INSUFFICIENT_FUNDS':
+      return {
+        title: 'Insufficient balance',
+        body: 'You don’t have enough balance for this bet. Lower your bet or top up.',
+        reload: false,
+      };
+    case 'TIMEOUT':
+      return {
+        title: 'Connection timed out',
+        body: 'The game server did not respond in time. Please try again.',
+        reload: false,
+      };
+    default:
+      // Unknown code: surface the server message verbatim under a generic heading (never the
+      // connection overlay), so an operator can diagnose without a code change.
+      return {
+        title: 'Game error',
+        body: message || 'Something went wrong. Please reload the game.',
+        reload: true,
+      };
+  }
+}