@energy8platform/game-engine 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",
@@ -94,7 +94,7 @@
   },
   "dependencies": {
     "@energy8platform/platform-core": ">=0.33.0",
-    "@energy8platform/shell": ">=0.8.0"
+    "@energy8platform/shell": ">=0.9.0"
   },
   "peerDependencies": {
     "@energy8platform/game-sdk": "^2.9.0",

package/src/host/autoplay.ts

@@ -5,6 +5,11 @@
  * drains fully before the next auto-spin), updating the shell's autoplay readout each spin and
  * halting on Stop, on an unaffordable spin, or on a play error.
  *
+ * Two ways a run ends, and they differ in what the player is left looking at: `stop()` clears the
+ * counter (the player pressed STOP, or the budget ran out — the run is over), while `halt()` keeps
+ * it (a lost connection cut the run short; the spins are still owed, and the shell shows them so
+ * the player can resume).
+ *
  * Sequential by construction: it awaits each round (incl. its bonus drain) before the next, so
  * there is never more than one round in flight. Pure over injected deps — unit-testable.
  */
@@ -20,10 +25,18 @@ export interface AutoplayDeps {
 }
 
 export interface Autoplay {
-  /** Begin an autoplay run of `count` rounds (no-op if already running or count ≤ 0). */
+  /** Begin an autoplay run of `count` rounds (no-op if already running or count ≤ 0). Also how a
+   *  halted run RESUMES: the shell sends the preserved count back (`start(remaining)`). */
   start(count: number): void;
-  /** Stop the run; the in-flight round (if any) finishes, then the loop exits. */
+  /** Stop the run and clear the counter — the player pressed STOP, or the budget ran out. */
   stop(): void;
+  /**
+   * Halt the run but KEEP the counter: the run was cut short by something that isn't the player and
+   * isn't the budget — a lost connection, a failed round. The player then sees how many spins were
+   * left and can resume them (`start(remaining)`), which is what a certification lab means by
+   * "autoplay stops, and after reconnection the counter is displayed correctly".
+   */
+  halt(): void;
   readonly active: boolean;
   readonly remaining: number;
 }
@@ -40,6 +53,12 @@ export function createAutoplayLoop(deps: AutoplayDeps): Autoplay {
     deps.onState({ active: false, remaining: 0 });
   };
 
+  const halt = (): void => {
+    if (!active) return; // nothing running — nothing to preserve
+    active = false;
+    deps.onState({ active: false, remaining });
+  };
+
   async function loop(): Promise<void> {
     if (running) return;
     running = true;
@@ -53,7 +72,9 @@ export function createAutoplayLoop(deps: AutoplayDeps): Autoplay {
         try {
           await deps.playRound(action);
         } catch {
-          stop(); // a play error already surfaced its own modal — just halt the run
+          // The round failed (the host surfaces its own message, if any is due). Halt rather than
+          // stop: a connection blip must not eat the spins the player still has coming.
+          halt();
           return;
         }
       }
@@ -72,6 +93,7 @@ export function createAutoplayLoop(deps: AutoplayDeps): Autoplay {
       void loop();
     },
     stop,
+    halt,
     get active() { return active; },
     get remaining() { return remaining; },
   };

package/src/host/connectionRecovery.ts

@@ -0,0 +1,113 @@
+// packages/game-engine/src/host/connectionRecovery.ts
+
+/**
+ * What the game does while the link to the platform is down, and when it comes back.
+ *
+ * The rules come from a certification remark: *"if connection is lost during autoplay, autoplay
+ * stops, and after reconnection the counter is displayed correctly"*. What the game used to do
+ * instead was worse in both halves — the in-flight play rejected, the host classified that
+ * rejection as an ordinary round failure and put up a "reload the page" screen (visible only in
+ * autoplay, because only autoplay always has a play in flight), and the autoplay counter was
+ * cleared to zero on the way. Reconnecting healed the link but nothing took the screen back down.
+ *
+ * So, per transition:
+ *  - **lost** — halt autoplay (the counter survives, see `autoplay.halt()`) and put up the
+ *    reconnect overlay. Repeated `lost` (one per failed reconnect attempt) doesn't restack it.
+ *  - **lost + `ConnectionGone`** — the bridge gave up retrying. That is terminal and honest about
+ *    it: a Reload modal, not a "Reconnecting…" that will never resolve.
+ *  - **restored** — take the overlay down and finish what the drop interrupted: if the platform
+ *    still holds an open round, play it out silently to settlement. No modal asks the player to
+ *    confirm this — it is their own round, they already paid for it, and an extra screen here is
+ *    the very thing the remark objected to.
+ *
+ * A `restored` that never followed a `lost` does nothing at all: it must not close a modal that
+ * belongs to someone else.
+ *
+ * Pure over injected deps — unit-testable, which `createSlotGame` itself is not.
+ */
+
+import type { PlayResultData } from '@energy8platform/platform-core';
+
+export interface ConnectionState {
+  status: 'lost' | 'restored' | 'connecting';
+  code?: string;
+  message?: string;
+}
+
+export interface ConnectionRecoveryDeps {
+  /** Stop an autoplay run WITHOUT clearing its counter (`Autoplay.halt`). */
+  haltAutoplay(): void;
+  /** Put up the blocking "Reconnecting…" overlay. */
+  showReconnecting(): void;
+  /** Put up the terminal "the connection is gone — reload" modal. */
+  showGone(): void;
+  /** Take down whatever the loss put up. */
+  dismiss(): void;
+  /** The platform's snapshot of an unfinished round, or `null` when there is nothing to finish. */
+  getState(): Promise<PlayResultData | null>;
+  /** Play a recovered round out to settlement (the host's `resumeDrain`). */
+  drain(snapshot: PlayResultData): Promise<void>;
+  /** Report a recovery that itself failed (the host routes it to its play-error modal). */
+  onError(err: unknown): void;
+  /**
+   * True while a modal the player must act on owns the screen. The overlay must not mask it, and
+   * a restored link must not close it — but the round underneath is still finished.
+   */
+  isBlocked?(): boolean;
+}
+
+export interface ConnectionRecovery {
+  /** Feed one `connectionStateChanged` payload. Awaitable: `restored` finishes the open round. */
+  onState(state: ConnectionState): Promise<void>;
+}
+
+/** The bridge has stopped retrying — see `ArtubeClient`'s exhausted reconnect loop. */
+const GONE = 'ConnectionGone';
+
+export function createConnectionRecovery(deps: ConnectionRecoveryDeps): ConnectionRecovery {
+  let linkLost = false;
+
+  const blocked = (): boolean => deps.isBlocked?.() ?? false;
+
+  async function recover(): Promise<void> {
+    let snapshot: PlayResultData | null = null;
+    try {
+      snapshot = await deps.getState();
+    } catch {
+      // The platform couldn't tell us. Nothing to finish, and nothing worth a screen: the player
+      // is back in the game, and the next play resolves the open round (or refuses it, loudly).
+      return;
+    }
+    if (!snapshot) return;
+    try {
+      await deps.drain(snapshot);
+    } catch (err) {
+      deps.onError(err);
+    }
+  }
+
+  return {
+    async onState(state: ConnectionState): Promise<void> {
+      if (state.status === 'connecting') return; // in transit — the screen stays as it is
+
+      if (state.status === 'lost') {
+        // Halt first: it is what the remark asks for, and it holds even when a modal already owns
+        // the screen and the overlay below is skipped.
+        deps.haltAutoplay();
+        if (state.code === GONE) {
+          if (!blocked()) deps.showGone();
+          return;
+        }
+        if (linkLost) return; // already announced — reconnect attempts don't restack the overlay
+        linkLost = true;
+        if (!blocked()) deps.showReconnecting();
+        return;
+      }
+
+      if (!linkLost) return; // nothing of ours is on screen; nothing of ours to recover
+      linkLost = false;
+      if (!blocked()) deps.dismiss();
+      await recover();
+    },
+  };
+}

package/src/host/createSlotGame.ts

@@ -9,6 +9,7 @@ import { releaseExternalOverlay } from '@energy8platform/platform-core/loading';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 import type { ShellMode } from '@energy8platform/shell/pixi';
 import type { SceneApi, SlotSceneController, RenderContext } from './sceneController';
+import type { ConnectionState } from './connectionRecovery';
 import type { FreeSpinsView } from './freeSpinsCounter';
 
 /**
@@ -282,6 +283,9 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
        *  per session; demo sessions are 'FUN'); Stake sends full meta on `config.currency` instead. */
       currency?: string;
       lang?: string;
+      /** The client the platform launched us on. Both bridges read it off the launch URL
+       *  (Stake's `device=`, Artube's `device=`); absent on dev/devBridge launches. */
+      device?: string;
     } | null;
     const config = initData?.config;
     // A reload mid-round is just another entry: authenticate answers with BOTH the currency's
@@ -324,6 +328,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       social: config?.socialMode,
       disclaimerLines: config?.disclaimerLines,
       jurisdiction: config?.jurisdiction,
+      // Decides whether the shell offers a keyboard at all — see buildShellConfig.
+      device: initData?.device,
       // Currency-specific ladder + per-currency default from /wallet/authenticate (Stake) or the
       // backend's `allowed_bets` (Artube); absent on dev/devBridge → buildShellConfig falls back to
       // the spec.
@@ -490,32 +496,39 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         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.
+    // Play-error + connection handling. A play rejection is classified (playError.ts): a failed
+    // ROUND gets a player-facing modal (ACTIVE_SESSION_EXISTS → Reload, etc.), a failed LINK gets
+    // none — the reconnect overlay owns that screen (connectionRecovery.ts). Either way the failure
+    // halts an autoplay run WITHOUT clearing its counter. The overlay stays 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)
+    let haltAutoplay: () => void = () => {}; // ditto — stops the run but KEEPS its counter
+    const reload = () => {
+      try {
+        window.location.reload();
+      } catch {
+        /* non-browser */
+      }
+    };
     const showPlayError = (err: unknown): void => {
-      stopAutoplay(); // a play error halts an autoplay run (the .catch swallows, so stop explicitly)
       const v = resolvePlayError(err);
+      // Halt, don't stop: the spins the player still has coming outlive the failure, so the bar can
+      // show them (and offer to resume). The .catch in playRound swallows the rejection, so the
+      // autoplay loop can't see it — this is what ends the run.
+      haltAutoplay();
+      // A failed LINK is not a failed round. The bridge is already reconnecting and the connection
+      // overlay owns the screen; a modal here is exactly the "reload the page" screen that showed
+      // up on every network blip — and only in autoplay, since only autoplay always has a play in
+      // flight when the socket dies.
+      if (v.connection) return;
       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('Reload'), on: reload }]
           : [
               {
                 title: shell!.t('OK'),
@@ -526,18 +539,35 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
             ],
       });
     };
-    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…'),
-      });
+    // Connection loss/return. Assigned below, once `resumeDrain` exists: a restored link finishes
+    // the round the drop interrupted, and it must not reach the drain before it is defined.
+    let recoverRound: (
+      snapshot: import('@energy8platform/platform-core').PlayResultData,
+    ) => Promise<void> = async () => {};
+    const { createConnectionRecovery } = await import('./connectionRecovery');
+    const connection = createConnectionRecovery({
+      haltAutoplay: () => haltAutoplay(),
+      showReconnecting: () =>
+        shell!.openModal({
+          availableClose: false,
+          title: shell!.t('Reconnecting…'),
+          body: shell!.t('Lost connection to the game server. Trying to reconnect…'),
+        }),
+      // The bridge stopped retrying: say so instead of leaving "Reconnecting…" up for good.
+      showGone: () =>
+        shell!.openModal({
+          availableClose: false,
+          title: shell!.t('Connection lost'),
+          body: shell!.t('Could not reconnect to the game server. Please reload the game.'),
+          actions: [{ title: shell!.t('Reload'), on: reload }],
+        }),
+      dismiss: () => shell!.closeModal(),
+      getState: async () => (await ps?.getState()) ?? null,
+      drain: (snapshot) => recoverRound(snapshot),
+      onError: showPlayError,
+      isBlocked: () => playErrorOpen,
     });
+    ps?.on('connectionStateChanged', (s: ConnectionState) => void connection.onState(s));
 
     // Skip state: `currentSegmentAbort` is the controller for the segment presently animating;
     // `presenting` is true for the whole play→drain window (gates the double-tap detector so taps
@@ -740,82 +770,27 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         });
     };
 
-    /**
-     * 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;
-      // A recovered drain isn't skippable (no live skip gesture wired to it), so it gets a stable,
-      // never-aborted signal to satisfy onSpin's RenderContext. ctx carries the round identity (built
-      // once from the trigger action) — recovery drains a single flat bonus using the bridge session
-      // counts; the full per-level nesting is a LIVE-play concern (playRound).
-      const ctx: RenderContext = {
-        ...makeContext((firstRaw as { action?: string }).action ?? 'spin'),
-        signal: new AbortController().signal,
-      };
-      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 bonus mode + counter.
-        if (!inBonus && !r.complete) {
-          inBonus = true;
-          shell!.setMode(bonusShellMode);
-        }
-        shell!.setWin(0, { animate: false }); // clear WIN before this segment animates (see playRound)
-        if (animate) winReporter.open(); // a fast-forward drain doesn't present → no reports expected
-        if (animate) await scene.onSpin(r, ctx);
-        if (inBonus) {
-          const v = fsView(raw, r.totalWin);
-          if (v) applyBonusReadout(r, v, ctx.mode);
-        }
-        winReporter.close();
-        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');
-          // Same as playRound: on return to base the WIN readout must show the round's cumulative
-          // total (r is the final drained segment), not the last segment's per-spin delta.
-          shell!.setWin(r.totalWin);
-        }
-      } finally {
-        winReporter.close(); // also closes the window when a drained segment threw
-        shell!.setBusy(false);
-      }
-    };
+    // Drain a recovered open round (reload / dropped connection) to settlement — see resumeDrain.ts.
+    // `scene` folds in the old `!ps` guard: with no session there is nothing to play or ack.
+    const { createResumeDrain } = await import('./resumeDrain');
+    const resumeDrain = createResumeDrain<T>({
+      scene: () => (ps ? gameScene() : undefined),
+      play: (req) => ps!.play(req),
+      ack: (raw) => ps!.playAck(raw),
+      normalize: opts.normalize,
+      context: makeContext,
+      setWin: (amount, o) => shell!.setWin(amount, o),
+      setMode: (m) => shell!.setMode(m),
+      setBusy: (b) => shell!.setBusy(b),
+      winReporter,
+      applyBonusReadout,
+      bonusMode: bonusShellMode,
+    });
+    // A round interrupted by a dropped connection is finished the same way a round interrupted by a
+    // reload is — animated, through to settlement — except nothing asks the player first: it is
+    // their own round, and an extra confirmation screen is what the reconnect flow is meant to
+    // avoid. (The reload path keeps its Continue/Finish offer: there, the player has been away.)
+    recoverRound = (snapshot) => resumeDrain(snapshot, true);
 
     if (mode === 'base') {
       let activeFeature: string | null = null;
@@ -843,6 +818,9 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       shell.on('spin', () => {
         const action = activeFeature ?? 'spin';
         if (!ensureAffordable(action)) return;
+        // Spinning by hand retires whatever a halted run left on the counter — the player moved on.
+        // (No-op unless a run was halted: `stop()` returns early when there is nothing to clear.)
+        stopAutoplay();
         void playRound(action);
       });
       shell.on('betChange', (bet: number) => {
@@ -851,6 +829,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       });
       shell.on('buyBonusSelect', ({ id }: { id: string }) => {
         if (!ensureAffordable(id)) return;
+        stopAutoplay(); // as with a manual spin: a bought bonus retires a halted run's counter
         void playRound(id);
       });
 
@@ -867,6 +846,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         },
       });
       stopAutoplay = () => autoplay.stop();
+      haltAutoplay = () => autoplay.halt();
       shell.on('autoplayStart', (o: { remaining?: number }) => autoplay.start(o?.remaining ?? 0));
       shell.on('autoplayStop', () => autoplay.stop());
 

package/src/host/playError.ts

@@ -16,8 +16,23 @@ export interface PlayErrorView {
   body: string;
   /** Offer a Reload action (the round can only be recovered by reloading). */
   reload: boolean;
+  /**
+   * The LINK failed, not the round: the bridge is already reconnecting, and the connection overlay
+   * (driven by `connectionStateChanged`) owns the screen. Such a failure gets NO modal of its own —
+   * a "reload the page" screen over a blip the bridge heals by itself is exactly the wrong answer,
+   * and it was the one the player used to get, because every autoplay round is a play in flight.
+   */
+  connection?: boolean;
 }
 
+/**
+ * Codes that mean "the connection died", per bridge:
+ *  - `ConnectionLost` / `ConnectionFailed` — Artube's WS client (a pending play on a dropped
+ *    socket, or a play attempted while the socket is down);
+ *  - `ERR_NET` — Stake's RGS client, after its retries are exhausted on a network-level failure.
+ */
+const CONNECTION_CODES = new Set(['ConnectionLost', 'ConnectionFailed', 'ERR_NET']);
+
 /** 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;
@@ -27,6 +42,14 @@ export function errorCode(err: unknown): string | undefined {
 export function resolvePlayError(err: unknown): PlayErrorView {
   const code = errorCode(err);
   const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+  if (code && CONNECTION_CODES.has(code)) {
+    return {
+      title: 'Connection lost',
+      body: 'Lost connection to the game server. Trying to reconnect…',
+      reload: false,
+      connection: true,
+    };
+  }
   switch (code) {
     case 'ACTIVE_SESSION_EXISTS':
       return {

package/src/host/resumeDrain.ts

@@ -0,0 +1,156 @@
+// packages/game-engine/src/host/resumeDrain.ts
+
+/**
+ * Play a recovered open round to completion and settle it.
+ *
+ * A round that was interrupted — the page reloaded, the socket dropped — is still open on the
+ * platform, and the player is owed both its remaining segments and the money at the end of them.
+ * This drains it: every remaining segment from where the snapshot left off (Continue animates each,
+ * Finish fast-forwards without animation), through to the final ack so the wallet credits the win.
+ *
+ * The original trigger is gone on a reload, so the free-spins counter here is rebuilt from the
+ * bridge's session counts rather than from the trigger's award — see `resumeBonusView`. Bonus mode
+ * is entered and exited around the drain, and the counter is painted the moment the bar enters it:
+ * a bonus bar with nothing in its counter reads as `0 / 0`, which is what a certification lab means
+ * by "the counter is reset while the previous FS round is active".
+ *
+ * Pure over injected deps — unit-testable, which `createSlotGame` itself is not.
+ */
+
+import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+import type { PlayResultData } from '@energy8platform/platform-core';
+import type { ShellMode } from '@energy8platform/shell/pixi';
+import type { RenderContext, SlotSceneController } from './sceneController';
+import type { FreeSpinsView } from './freeSpinsCounter';
+import { enrichRoundMeta } from './slotPlay';
+
+export interface ResumeDrainDeps<T extends SlotSpinResultBase> {
+  /** The scene to draw the recovered segments on; `undefined` aborts the drain. */
+  scene(): SlotSceneController<T> | undefined;
+  /** Play the next segment of the open round (PlatformSession.play). */
+  play(req: { action: string; bet: number; roundId?: string }): Promise<PlayResultData>;
+  /** Acknowledge a presented segment (PlatformSession.playAck) — settles on the final one. */
+  ack(raw: PlayResultData): void;
+  normalize(raw: unknown): T;
+  /** The signal-less RenderContext for an action (the host's `makeContext`). */
+  context(action: string): Omit<RenderContext, 'signal'>;
+  setWin(amount: number, opts?: { animate?: boolean }): void;
+  setMode(mode: ShellMode): void;
+  setBusy(busy: boolean): void;
+  /** The progressive-WIN window (open while a segment may report per-step wins). */
+  winReporter: { open(): void; close(): void };
+  /** Paint the bonus readout — the free-spins counter, or the game's own. */
+  applyBonusReadout(result: T, view: FreeSpinsView, mode: string): void;
+  /** The shell mode a bonus enters: 'bonus' when the game customises the readout, else 'freeSpins'. */
+  bonusMode: ShellMode;
+}
+
+/** The session counts a bridge attaches to every segment of an open round. */
+interface ResumeSession {
+  spinsPlayed?: number;
+  spinsRemaining?: number;
+}
+
+/**
+ * Rebuild the free-spins counter from a resumed segment's session counts.
+ *
+ * The bridge session counts ALL segments including the trigger (segment 0); the free-spins counter
+ * is over FREE spins only, so one trigger segment is dropped → `1 / 10`, not `2 / 11`. `null` when
+ * the snapshot carries no session at all — there is nothing to count, and painting zeroes would be
+ * a claim, not a reading.
+ */
+export function resumeBonusView(raw: unknown, totalWin: number): FreeSpinsView | null {
+  const s = (raw as { session?: ResumeSession | null } | null)?.session;
+  if (!s) return null;
+  const played = s.spinsPlayed ?? 0;
+  return {
+    current: Math.max(0, played - 1),
+    total: Math.max(0, played + (s.spinsRemaining ?? 0) - 1),
+    totalWin,
+  };
+}
+
+/**
+ * Fold a segment's own free-spins counts over the session-derived view.
+ *
+ * Same precedence live play uses (`overrideView` in createSlotGame): when the book states the count
+ * outright, it is the authority — the session's segment arithmetic is only a reconstruction, and it
+ * assumes a shape (exactly one trigger segment ahead of the free spins) that not every game has.
+ */
+export function overrideWithBook(
+  view: FreeSpinsView | null,
+  fs: SlotSpinResultBase['freeSpins'],
+): FreeSpinsView | null {
+  if (!fs || (fs.total == null && fs.remaining == null)) return view;
+  const base = view ?? { current: 0, total: 0, totalWin: 0 };
+  const total = fs.total ?? base.total;
+  const current = fs.remaining != null ? Math.max(0, total - fs.remaining) : base.current;
+  return { current, total, totalWin: base.totalWin };
+}
+
+export function createResumeDrain<T extends SlotSpinResultBase>(
+  deps: ResumeDrainDeps<T>,
+): (firstRaw: PlayResultData, animate: boolean) => Promise<void> {
+  return async function drain(firstRaw: PlayResultData, animate: boolean): Promise<void> {
+    const scene = deps.scene();
+    if (!scene) return;
+    // A recovered drain isn't skippable (no live skip gesture wired to it), so it gets a stable,
+    // never-aborted signal to satisfy onSpin's RenderContext. ctx carries the round identity (built
+    // once from the trigger action) — recovery drains a single flat bonus using the bridge session
+    // counts; the full per-level nesting is a LIVE-play concern (playRound).
+    const ctx: RenderContext = {
+      ...deps.context((firstRaw as { action?: string }).action ?? 'spin'),
+      signal: new AbortController().signal,
+    };
+    let raw: PlayResultData = firstRaw;
+    let r = enrichRoundMeta(deps.normalize(raw), raw);
+    let inBonus = false;
+    let prevWin = 0; // cumulative win up to the previous segment — WIN readout shows the delta
+
+    /** Push the current segment's counts to the bar (book counts win over the session's). */
+    const paintCounter = (): void => {
+      const view = overrideWithBook(resumeBonusView(raw, r.totalWin), r.freeSpins);
+      if (view) deps.applyBonusReadout(r, view, ctx.mode);
+    };
+
+    const applySegment = async (): Promise<void> => {
+      // A recovered open round with remaining segments is a bonus → show bonus mode + counter.
+      if (!inBonus && !r.complete) {
+        inBonus = true;
+        deps.setMode(deps.bonusMode);
+        // BEFORE the segment animates, not after. The bar has just switched to its bonus face, and
+        // its counter still holds the zeroes it was born with; leaving it that way means the player
+        // watches a whole free spin play out under `0 / 0` and only then sees where the round
+        // actually stands. The snapshot already carries the counts — paint them.
+        paintCounter();
+      }
+      deps.setWin(0, { animate: false }); // clear WIN before this segment animates (see playRound)
+      if (animate) deps.winReporter.open(); // a fast-forward drain doesn't present → no reports expected
+      if (animate) await scene.onSpin(r, ctx);
+      if (inBonus) paintCounter();
+      deps.winReporter.close();
+      deps.setWin(r.totalWin - prevWin); // THIS spin's win, not the cumulative bonus total
+      prevWin = r.totalWin;
+      deps.ack(raw); // settles via /wallet/end-round on the FINAL segment
+    };
+
+    deps.setBusy(true); // block input while the recovered round drains
+    try {
+      await applySegment();
+      while (!r.complete && r.nextActions && r.nextActions.length > 0) {
+        raw = await deps.play({ action: r.nextActions[0], bet: ctx.bet, roundId: r.roundId });
+        r = enrichRoundMeta(deps.normalize(raw), raw);
+        await applySegment();
+      }
+      if (inBonus) {
+        deps.setMode('base');
+        // Same as playRound: on return to base the WIN readout must show the round's cumulative
+        // total (r is the final drained segment), not the last segment's per-spin delta.
+        deps.setWin(r.totalWin);
+      }
+    } finally {
+      deps.winReporter.close(); // also closes the window when a drained segment threw
+      deps.setBusy(false);
+    }
+  };
+}