@energy8platform/game-engine 0.17.0 → 0.18.0

package/src/host/preboot.ts

@@ -0,0 +1,25 @@
+import { TextureSource } from 'pixi.js';
+
+/** Preload web fonts so Pixi text rasterizes with the right glyphs. Never throws. */
+export async function loadFonts(specs?: string[]): Promise<void> {
+  if (!specs || specs.length === 0) return;
+  try {
+    await Promise.all(specs.map((s) => document.fonts.load(s)));
+    await document.fonts.ready;
+  } catch {
+    /* font CDN unreachable → fall back to system fonts */
+  }
+}
+
+/** Smoother default downscaling for art-heavy slots. Pixel-art games omit this. */
+export function applyTextureDefaults(): void {
+  TextureSource.defaultOptions.autoGenerateMipmaps = true;
+}
+
+/** Idempotent double-boot guard. Returns true the first time, false thereafter. */
+export function bootGuard(flag = '__e8SlotBooted__'): boolean {
+  const w = window as unknown as Record<string, boolean>;
+  if (w[flag]) return false;
+  w[flag] = true;
+  return true;
+}

package/src/host/replay.ts

@@ -0,0 +1,9 @@
+import type { GameModel } from '@energy8platform/platform-core/game-spec';
+
+/** Reverse the model's modeMap (Stake bet mode → SDK action key) for replay labelling/cost. */
+export function resolveReplayBonusId(model: GameModel, stakeMode: string): string {
+  for (const [action, mode] of Object.entries(model.modeMap)) {
+    if (mode === stakeMode) return action;
+  }
+  return stakeMode;
+}

package/src/host/runRound.ts

@@ -0,0 +1,63 @@
+import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+import type { RenderContext, SlotSceneController } from './sceneController';
+
+/** Injected dependencies for one round. All host-agnostic + unit-testable. */
+export interface RunRoundDeps<T extends SlotSpinResultBase> {
+  /** play → normalize → enrich (roundId/nextActions/complete). From createSlotPlay. */
+  play(action: string, bet: number, roundId?: string): Promise<T>;
+  /** Settle the most recent result (post-animation). From createSlotPlay. */
+  ack(): void;
+  /** The scene to render into (resolved by the caller at call time — it can change between rounds). */
+  scene: Pick<SlotSceneController<T>, 'present'>;
+  /** Build the per-round render context for the trigger action. */
+  context(action: string): RenderContext;
+  /** Role of an action from the spec ('base'|'buy'|'feature'|'free'); drives bonus detection. */
+  roleOf(action: string): string | undefined;
+  /** Fires after each segment is presented + acked. The host updates HUD readouts (win/balance)
+   *  here so they change WITH the animation, never eagerly when the play result arrives. */
+  afterPresent?(result: T): void;
+  /** Fires EXACTLY before the first free spin of a bonus. The host drives the shell free-spins mode
+   *  + counter and delegates to the scene's onBonusEnter. `trigger` is the round's trigger result. */
+  onBonusEnter?(trigger: T, ctx: RenderContext): Promise<void>;
+  /** Fires after the last free spin of a bonus. The host exits the shell free-spins mode + delegates
+   *  to the scene's onBonusExit. `last` is the final free-spin result (cumulative totalWin). */
+  onBonusExit?(last: T, ctx: RenderContext): Promise<void>;
+}
+
+/**
+ * Drive ONE round end-to-end: play the trigger, present it, ack; then drain the remaining segments
+ * (a bonus's free spins) by replaying nextActions[0] with the SAME roundId until the round reports
+ * `complete`. Fires `onBonusEnter` EXACTLY before the first free-role segment and `onBonusExit`
+ * after the last. A plain spin with no bonus is already `complete`, so the while-loop is a no-op.
+ *
+ * `ctx.bet` is captured once (bet can't change mid-round); `ctx.turbo` is a live getter so a
+ * mid-round toggle is honoured on the next segment.
+ */
+export async function runRound<T extends SlotSpinResultBase>(
+  deps: RunRoundDeps<T>,
+  action: string,
+): Promise<void> {
+  const ctx = deps.context(action);
+  let r = await deps.play(action, ctx.bet);
+  await deps.scene.present(r, ctx);
+  deps.ack();
+  deps.afterPresent?.(r); // HUD readouts update AFTER the animation, not before
+
+  let inBonus = false;
+  while (!r.complete && r.nextActions && r.nextActions.length > 0) {
+    const next = r.nextActions[0];
+    if (!inBonus && deps.roleOf(next) === 'free') {
+      inBonus = true;
+      await deps.onBonusEnter?.(r, ctx);
+    }
+    // Snapshot the TRIGGER context per segment: { ... } freezes the live `turbo` getter into a data
+    // property (so a mid-round toggle is reflected on the NEXT segment), while action/mode/bet stay
+    // the round's (the trigger's) identity — a scene must see the same bonus identity all round.
+    const segCtx = { ...deps.context(action) } as RenderContext;
+    r = await deps.play(next, ctx.bet, r.roundId);
+    await deps.scene.present(r, segCtx);
+    deps.ack();
+    deps.afterPresent?.(r);
+  }
+  if (inBonus) await deps.onBonusExit?.(r, ctx);
+}

package/src/host/sceneController.ts

@@ -0,0 +1,31 @@
+import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+
+/** Everything a scene needs to render one result. The host builds it once per round. */
+export interface RenderContext {
+  /** Bet for this round (major units). Stable for the whole round (a bonus is one round). */
+  bet: number;
+  /** Trigger action in the game's own vocabulary (gameSpec.actions keys): 'spin' | 'ante' |
+   *  'buy_bonus' | … Stable for the whole round. */
+  action: string;
+  /** Stake bet-mode of the round (model.spec.modeMap[action]): 'BASE' | 'ANTE' | 'BONUS' | …
+   *  Canonical per-round identifier of WHICH bonus/feature this is. Stable for the whole round. */
+  mode: string;
+  /** Currency-aware money formatter. win/totalWin get variable decimals (0.0041 stays 0.0041). */
+  formatAmount(value: number): string;
+  /** LIVE turbo level (0 = off, 1..3 = escalating speed), matching the shell's state.turbo. Read at
+   *  the moment of access (getter) so a mid-round toggle is reflected. */
+  readonly turbo: number;
+}
+
+/** The contract a slot scene implements. The HOST owns the play→present→ack→drain loop and calls
+ *  these; the scene only renders. The game never sees play/ack/roundId. */
+export interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResultBase> {
+  /** Render ONE segment (a spin, or one free spin). All pacing/pauses/overlays live here
+   *  (await your own animations). The host calls this once per segment. */
+  present(result: T, ctx: RenderContext): Promise<void>;
+  /** Optional. Fires EXACTLY before the first free spin of a bonus (intro; spin counts in
+   *  trigger.freeSpins). */
+  onBonusEnter?(trigger: T, ctx: RenderContext): Promise<void>;
+  /** Optional. Fires after the last free spin of a bonus (summary; last.totalWin = bonus total). */
+  onBonusExit?(last: T, ctx: RenderContext): Promise<void>;
+}

package/src/host/sceneStart.ts

@@ -0,0 +1,25 @@
+import type { SceneRegistration } from './types';
+
+/**
+ * Pick the scene to START with, given the registered scenes (in order) and the launch mode.
+ *
+ * Rules:
+ *  - On a replay launch, scenes flagged `skipOnReplay` are NOT eligible to start (they stay
+ *    registered for `goto`, they just aren't auto-started) — so a leading intro is skipped and
+ *    the game scene starts directly.
+ *  - An explicit `startScene` wins, but only if that scene is itself eligible; otherwise the first
+ *    eligible scene wins.
+ *  - Falls back to the first scene unconditionally if nothing is eligible (degenerate config).
+ */
+export function resolveStartScene(
+  scenes: SceneRegistration[],
+  isReplay: boolean,
+  explicitStart?: string,
+): string {
+  const eligible = scenes.filter((s) => !(isReplay && s.skipOnReplay));
+  if (explicitStart) {
+    const ok = eligible.find((s) => s.key === explicitStart);
+    if (ok) return ok.key;
+  }
+  return eligible[0]?.key ?? scenes[0]?.key;
+}

package/src/host/shellConfig.ts

@@ -0,0 +1,379 @@
+// packages/game-engine/src/host/shellConfig.ts
+import { socialize } from '@energy8platform/platform-core/shell';
+import type {
+  ShellConfig, ShellMode, CurrencyConfig, GameInfoContent, GameInfoSection, PaytableRow,
+  BonusOption, ShellFeatures, GameMode,
+} from '@energy8platform/platform-core/shell';
+import type { GameModel } from '@energy8platform/platform-core/game-spec';
+import type { WinTier } from '../slot';
+
+export interface SlotShellOptions {
+  mount?: HTMLElement;
+  /** Override the derived currency (normally taken from initData). */
+  currency?: CurrencyConfig;
+  /** Author-supplied info sections, MERGED over the host-derived set by section identity (an author
+   *  section REPLACES the derived one of the same `type`/`kind`; a new `type` is appended; derived
+   *  sections without an override are kept).
+   *
+   *  Pass a plain `GameInfoContent`, OR a function `(t) => GameInfoContent` where `t` is the
+   *  social-aware translator (it rewrites restricted gambling words when in social mode, and is the
+   *  identity otherwise) — wrap player-facing copy in `t(...)` so it socializes. Either way the
+   *  merged result is also run through `socialize` in social mode as a safety net, so forbidden
+   *  words never leak even if `t()` was forgotten. */
+  gameInfo?: GameInfoContent | ((t: (text: string) => string) => GameInfoContent);
+  /** Override the derived buy/ante options. In social mode the card copy is socialized too. */
+  buyBonus?: BonusOption[];
+  tiers?: WinTier[];
+  features?: Partial<ShellFeatures>;
+}
+
+/** The currency metadata surfaced on `initData.config.currency` (game-sdk `CurrencyMetaData`).
+ *  Built by the Stake bridge via `lookupCurrency(code)` from the authoritative `CURRENCY_META`
+ *  table — the single source of truth for symbol/decimals/placement. */
+export interface CurrencyMeta {
+  code: string;
+  symbol: string;
+  decimals: number;
+  symbolAfter?: boolean;
+}
+
+/** Runtime context from the SDK handshake (initData) + the resolved mode. */
+export interface ShellRuntime {
+  balance: number;
+  /** Resolved shell currency, derived from `initData.config.currency` (the SAME meta the Stake
+   *  bridge builds). Pass a full `CurrencyConfig` — see `resolveCurrency`. */
+  currency?: CurrencyConfig;
+  language?: string;
+  mode: ShellMode;
+  /** Social-casino mode from initData (`config.socialMode`); swaps shell vocabulary. */
+  social?: boolean;
+  /** Stake-required disclaimer lines from initData (`config.disclaimerLines`); when
+   *  absent (non-stake/dev) no disclaimer section is rendered. */
+  disclaimerLines?: string[];
+  /** Jurisdiction flags from initData (`config.jurisdiction`). Restrict shell features — applied
+   *  OVER the author's features so a jurisdiction restriction always wins. */
+  jurisdiction?: JurisdictionRestrictions;
+  /** Bet ladder from `/wallet/authenticate` (`initData.config.betLevels`, major units). Stake ladders
+   *  are CURRENCY-SPECIFIC (us_/non_us_/social_), so this overrides the spec's static `betLevels` on a
+   *  Stake launch; falls back to the spec on dev/devBridge. */
+  betLevels?: number[];
+  /** Per-currency default bet from `/wallet/authenticate` (the bridge surfaces it as
+   *  `config.stake.defaultBetLevel`). Stake requires the selector to start here on every entry. */
+  defaultBet?: number;
+}
+
+/** The subset of Stake's jurisdiction flags the shell can enforce via `ShellFeatures`. */
+export interface JurisdictionRestrictions {
+  /** No turbo at all → `features.turbo = 0`. */
+  disabledTurbo?: boolean;
+  /** Basic turbo allowed, but no super-turbo → cap `features.turbo` at 1. */
+  disabledSuperTurbo?: boolean;
+  /** No spacebar quick-spin → `features.spacebar = false`. */
+  disabledSpacebar?: boolean;
+  /** No autoplay → `features.autoplay = null`. */
+  disabledAutoplay?: boolean;
+  /** No buy-feature → `features.buyBonus = false`. */
+  disabledBuyFeature?: boolean;
+}
+
+/**
+ * Apply jurisdiction restrictions over the resolved shell features, in place. A restriction ALWAYS
+ * wins over the author's intent (a forbidden control must stay off even if the game enabled it).
+ */
+export function applyJurisdiction(features: ShellFeatures, j?: JurisdictionRestrictions): void {
+  if (!j) return;
+  if (j.disabledTurbo) features.turbo = 0;
+  else if (j.disabledSuperTurbo && features.turbo > 1) features.turbo = 1;
+  if (j.disabledSpacebar) features.spacebar = false;
+  if (j.disabledAutoplay) features.autoplay = null;
+  if (j.disabledBuyFeature) features.buyBonus = false;
+}
+
+/**
+ * Resolve the shell `CurrencyConfig` from the SAME data the Stake bridge uses — the
+ * `CurrencyMetaData` it puts on `initData.config.currency` (symbol + placement from
+ * `symbolAfter`). No second symbol table lives here.
+ *
+ * Fallback chain (dev/devBridge with no Stake meta): `initData.config.currency`
+ * → the spec's currency `code` (neutral `{ symbol: code, position: 'left' }`)
+ * → `{ symbol: '€', position: 'left' }`.
+ */
+/** Extra precision for WIN / TOTAL-WIN readouts so small-bet wins (e.g. 0.0041 on a 0.01 bet) are
+ *  not rounded away to 0.00. Balance / bet stay at the currency's own decimals (`minDecimals`). */
+const WIN_MAX_DECIMALS = 4;
+
+/** Attach decimals: `minDecimals` (balance/bet/prices, fixed) = the currency's decimals; `maxDecimals`
+ *  (win/total-win, variable, trailing zeros trimmed) = up to WIN_MAX_DECIMALS — but only when the
+ *  currency actually has fraction digits (a 0-decimal currency like JPY keeps wins integer). */
+function withDecimals(base: { symbol: string; position: 'left' | 'right' }, decimals: number): CurrencyConfig {
+  return {
+    ...base,
+    minDecimals: decimals,
+    maxDecimals: decimals > 0 ? Math.max(decimals, WIN_MAX_DECIMALS) : 0,
+  };
+}
+
+export function resolveCurrency(meta?: CurrencyMeta | null, specCurrency?: string): CurrencyConfig {
+  const hasMeta = !!(meta && meta.symbol);
+  // Single expression, no early-return branches (the bundler was treeshaking the meta branch away).
+  const symbol = hasMeta ? meta!.symbol : (specCurrency || '€');
+  const position: 'left' | 'right' = hasMeta && meta!.symbolAfter ? 'right' : 'left';
+  const decimals = hasMeta && typeof meta!.decimals === 'number' ? meta!.decimals : 2;
+  return withDecimals({ symbol, position }, decimals);
+}
+
+/** Total stake for an action = bet × the action's cost multiplier (1 for a base spin; e.g. 100 for
+ *  a buy bonus). The host uses this to block a play the balance can't cover. */
+export function stakeForAction(model: GameModel, action: string, bet: number): number {
+  const cost = (model.spec.actions?.[action]?.cost ?? 1) as number;
+  return cost * bet;
+}
+
+/** Derive shell buy cards + ante toggles from the spec's buy/feature actions (SSOT). */
+export function toBonusOptions(model: GameModel): BonusOption[] {
+  const out: BonusOption[] = [];
+  for (const [key, action] of Object.entries(model.spec.actions)) {
+    const role = action.role ?? 'base';
+    if (role !== 'buy' && role !== 'feature') continue;
+    out.push({
+      id: key,
+      type: role === 'buy' ? 'bonus' : 'feature',
+      title: action.title ?? key.replace(/_/g, ' ').toUpperCase(),
+      description: action.description ?? '',
+      priceMultiplier: action.cost ?? (role === 'buy' ? 100 : 1),
+    });
+  }
+  return out;
+}
+
+/** Build a paytable section from the model's derived paytable view (multipliers per symbol count). */
+function paytableSection(model: GameModel): GameInfoSection | null {
+  const symbols = model.paytable?.symbols ?? [];
+  const rows: PaytableRow[] = [];
+  for (const s of symbols) {
+    const wins = Object.entries(s.pay ?? {})
+      .map(([count, multiplier]) => ({ count: String(count), multiplier: Number(multiplier) }))
+      .filter((w) => Number.isFinite(w.multiplier) && w.multiplier > 0)
+      .sort((a, b) => Number(a.count) - Number(b.count));
+    if (!wins.length) continue;
+    rows.push({ symbol: { text: s.name ?? s.id }, wins });
+  }
+  if (!rows.length) return null;
+  return { type: 'paytable', title: 'PAYTABLE', rows };
+}
+
+/** Build a "wins" illustration section sized to the grid; `kind` follows the spec mechanic hint. */
+function winsSection(model: GameModel): GameInfoSection {
+  const { cols, rows } = model.spec.grid;
+  const grid = { cols, rows };
+  switch (model.spec.mechanic) {
+    case 'cluster':
+      return { type: 'wins', kind: 'cluster', minCount: 5, grid } as GameInfoSection;
+    case 'ways':
+      return { type: 'wins', kind: 'ways', grid } as GameInfoSection;
+    default:
+      return { type: 'wins', kind: 'anywhere', minCount: 3, grid } as GameInfoSection;
+  }
+}
+
+/** Title of the legal disclaimer section — used to build it and to exempt it from socialization. */
+const DISCLAIMER_TITLE = 'DISCLAIMER';
+
+/** A disclaimer section from initData's disclaimer lines; null when none supplied. */
+function disclaimerSection(lines?: string[]): GameInfoSection | null {
+  const clean = (lines ?? []).map((l) => l.trim()).filter(Boolean);
+  if (!clean.length) return null;
+  const html = clean.map((l) => `<p>${l}</p>`).join('');
+  return { type: 'custom', title: DISCLAIMER_TITLE, html };
+}
+
+/** The legal disclaimer must be shown verbatim — this identifies it so socialization skips it. */
+function isDisclaimerSection(s: GameInfoSection): boolean {
+  return s.type === 'custom' && (s as { title?: string }).title === DISCLAIMER_TITLE;
+}
+
+/** Move the legal disclaimer to the very END of the section list — it must always render last,
+ *  regardless of where an author merge or an extra section would otherwise place it. */
+function orderDisclaimerLast(sections: GameInfoSection[]): GameInfoSection[] {
+  const disclaimer = sections.filter(isDisclaimerSection);
+  if (!disclaimer.length) return sections;
+  return [...sections.filter((s) => !isDisclaimerSection(s)), ...disclaimer];
+}
+
+/**
+ * Pure: derive a maximal default GameInfoContent from the model + runtime so every game
+ * gets a real info panel for free (paytable, win illustration, controls, and the Stake
+ * disclaimer when present). Author-supplied `opts.gameInfo` is MERGED over this set by
+ * section identity (see `mergeGameInfo`), not wholesale-replaced.
+ */
+export function defaultGameInfo(model: GameModel, runtime: ShellRuntime): GameInfoContent {
+  const sections: GameInfoSection[] = [];
+  sections.push(winsSection(model));
+  const pay = paytableSection(model);
+  if (pay) sections.push(pay);
+  const modes = modesSection(model);
+  if (modes) sections.push(modes);
+  sections.push({ type: 'controls' });
+  const disclaimer = disclaimerSection(runtime.disclaimerLines);
+  if (disclaimer) sections.push(disclaimer);
+  return { sections };
+}
+
+/** Per-mode info table (BASE / ANTE / each buy tier) derived from the spec's modes — the SAME SSOT
+ *  (`model.mathModes` + `spec.actions`) that drives the buy cards and the math pipeline. Stake
+ *  compliance requires Cost / RTP / Max Win per mode; deriving it here means the author declares a
+ *  mode once (in game.spec) and the info table can't drift. `free` actions are excluded (mathModes
+ *  already drops them — free spins are part of a bonus, not a purchasable mode). */
+function modesSection(model: GameModel): GameInfoSection | null {
+  const modes = model.mathModes ?? [];
+  if (!modes.length) return null;
+  const rows: GameMode[] = modes.map((m) => {
+    const action = model.spec.actions[m.action];
+    const isBase = (action?.role ?? 'base') === 'base' || m.mode === 'BASE';
+    const row: GameMode = {
+      title: action?.title ?? (isBase ? 'Base game' : m.mode.replace(/_/g, ' ')),
+      maxWin: `${m.maxWin.toLocaleString('en-US')}×`,
+    };
+    // Cost is a bet-multiplier; a base spin (1×) reads as no premium, so only show it for buys/features.
+    if (m.costMultiplier && m.costMultiplier !== 1) row.price = `${m.costMultiplier}×`;
+    if (typeof m.rtp === 'number') row.rtp = Math.round(m.rtp * 1000) / 10; // 0.965 → 96.5 (%)
+    if (action?.description) row.description = action.description;
+    return row;
+  });
+  return { type: 'modes', title: 'MODES', modes: rows };
+}
+
+/** Identity key for merge. `wins` is keyed by `kind` (different mechanics coexist). `custom` has
+ *  no structural discriminant and several can coexist (MAX WIN, DISCLAIMER, …) so it is keyed by
+ *  its `title` (an author `custom` with a matching title replaces that derived block; a new title
+ *  is added). Every other type is a singleton keyed by `type`. */
+function sectionKey(s: GameInfoSection): string {
+  if (s.type === 'wins') return `wins:${s.kind}`;
+  if (s.type === 'custom') return `custom:${s.title ?? ''}`;
+  return s.type;
+}
+
+/**
+ * Merge author `gameInfo` over the host-derived set by section identity: an author section
+ * REPLACES the derived section of the same identity (same `type`, or same `wins` `kind`); a new
+ * identity is APPENDED (after the derived ones, in author order); derived sections without an
+ * author override are KEPT. `override` undefined → the pure derived set.
+ */
+export function mergeGameInfo(derived: GameInfoContent, override?: GameInfoContent): GameInfoContent {
+  if (!override) return derived;
+  const authorByKey = new Map<string, GameInfoSection>();
+  for (const s of override.sections ?? []) authorByKey.set(sectionKey(s), s);
+
+  const out: GameInfoSection[] = [];
+  const used = new Set<string>();
+  // Keep derived order; swap in the author's version where identities collide.
+  for (const s of derived.sections ?? []) {
+    const k = sectionKey(s);
+    const replacement = authorByKey.get(k);
+    if (replacement) { out.push(replacement); used.add(k); }
+    else out.push(s);
+  }
+  // Append author sections whose identity wasn't in the derived set, in author order.
+  for (const s of override.sections ?? []) {
+    const k = sectionKey(s);
+    if (!used.has(k)) { out.push(s); used.add(k); }
+  }
+  return { sections: out };
+}
+
+/** Run a section's player-facing text through `socialize`. Applied to the full MERGED set
+ *  (host-derived + author) in social mode. Covers section titles, custom HTML, and PAYTABLE row
+ *  symbol labels — the paytable's symbol text comes straight from the gameSpec's `symbols[].name`,
+ *  so a forbidden word in a spec symbol name is rewritten here too. A `node`-based custom section is
+ *  returned untouched — its DOM is author-owned and not introspected. */
+function socializeSection(s: GameInfoSection): GameInfoSection {
+  const next = { ...s } as GameInfoSection;
+  if ('title' in next && typeof next.title === 'string') {
+    (next as { title?: string }).title = socialize(next.title);
+  }
+  if (next.type === 'custom' && typeof next.html === 'string') {
+    (next as { html?: string }).html = socialize(next.html);
+  }
+  if (next.type === 'paytable' && Array.isArray((next as { rows?: PaytableRow[] }).rows)) {
+    (next as { rows: PaytableRow[] }).rows = (next as { rows: PaytableRow[] }).rows.map((r) =>
+      typeof r.symbol?.text === 'string'
+        ? { ...r, symbol: { ...r.symbol, text: socialize(r.symbol.text) } }
+        : r,
+    );
+  }
+  if (next.type === 'modes' && Array.isArray((next as { modes?: GameMode[] }).modes)) {
+    (next as { modes: GameMode[] }).modes = (next as { modes: GameMode[] }).modes.map((m) => ({
+      ...m,
+      title: socialize(m.title),
+      ...(m.description ? { description: socialize(m.description) } : {}),
+    }));
+  }
+  return next;
+}
+
+/** Socialize buy-bonus card copy (title/description) when in social mode; a no-op otherwise.
+ *  Applied to the final option set (author override or spec-derived) so forbidden words in author
+ *  card copy are rewritten too. */
+function socializeBonusOptions(options: BonusOption[], isSocial: boolean): BonusOption[] {
+  if (!isSocial) return options;
+  return options.map((o) => ({ ...o, title: socialize(o.title), description: socialize(o.description) }));
+}
+
+/** Pure: assemble a ShellConfig from the model + runtime context (currency/balance/language/mode). */
+export function buildShellConfig(opts: SlotShellOptions, model: GameModel, runtime: ShellRuntime): ShellConfig {
+  // Prefer the currency-specific ladder from /wallet/authenticate; fall back to the spec (dev/devBridge).
+  const betLevels = runtime.betLevels?.length ? runtime.betLevels : model.spec.betLevels;
+  // Stake requires the default to come from authenticate on every entry; spec default is the dev fallback.
+  const defaultBet = runtime.defaultBet ?? model.spec.defaultBet ?? betLevels[0];
+  // runtime.currency is the resolved CurrencyConfig (derived from initData.config.currency by the
+  // host); opts.currency still wins. Fall back to the spec code, then a neutral euro.
+  const currency =
+    opts.currency ?? runtime.currency ?? resolveCurrency(null, model.spec.currency);
+  const isSocial = runtime.social ?? false;
+  // Merge author sections over the host-derived defaults, THEN socialize the WHOLE merged set in
+  // social mode — so restricted gambling vocabulary is rewritten in BOTH the built-in copy AND any
+  // author-supplied text (title + custom HTML). A game can no longer surface a forbidden word in
+  // social mode just because the author wrote it in their own info section. (Custom sections built
+  // from a raw DOM `node` can't be rewritten automatically — author owns the node and can call the
+  // exported `socialize` from '@energy8platform/game-engine/host' on their own strings.)
+  // Author gameInfo may be a plain object or a `(t) => content` factory. `t` socializes when in
+  // social mode (identity otherwise) so authors can wrap copy explicitly; the full merged set is
+  // still socialized below as a safety net.
+  const t = isSocial ? socialize : (text: string) => text;
+  const authored = typeof opts.gameInfo === 'function' ? opts.gameInfo(t) : opts.gameInfo;
+  let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime), authored);
+  // The DISCLAIMER is required legal copy and must be shown VERBATIM — never socialized (its
+  // wording is mandated, and word-swaps like "bet → play" would corrupt the legal text).
+  if (isSocial) {
+    gameInfo = {
+      sections: (gameInfo.sections ?? []).map((s) => (isDisclaimerSection(s) ? s : socializeSection(s))),
+    };
+  }
+  // The legal DISCLAIMER always renders LAST — author-merged or extra sections never push below it.
+  gameInfo = { sections: orderDisclaimerLast(gameInfo.sections ?? []) };
+  // Buy-bonus cards: socialize the FINAL options (author override or spec-derived) in social mode.
+  const buyBonus = socializeBonusOptions(opts.buyBonus ?? toBonusOptions(model), isSocial);
+  // Features: defaults, then author overrides, THEN jurisdiction restrictions (a restriction wins).
+  const features: ShellFeatures = {
+    turbo: 0,
+    spacebar: true,
+    autoplay: {},
+    buyBonus,
+    ...(opts.features ?? {}),
+  } as ShellFeatures;
+  applyJurisdiction(features, runtime.jurisdiction);
+  return {
+    mount: opts.mount ?? (typeof document !== 'undefined' ? document.body : (undefined as never)),
+    language: runtime.language ?? 'en',
+    isSocial,
+    currency,
+    gameInfo,
+    availableBets: [...betLevels],
+    defaultBet,
+    currentBet: defaultBet,
+    balance: runtime.balance,
+    win: 0,
+    mode: runtime.mode,
+    features,
+  };
+}

package/src/host/slotPlay.ts

@@ -0,0 +1,62 @@
+import type { SlotSpinResultBase, SlotResultNormalizer } from '@energy8platform/platform-core/slot-result';
+
+export interface SlotPlayDeps<T extends SlotSpinResultBase> {
+  play(params: { action: string; bet: number; roundId?: string }): Promise<unknown>;
+  normalize: SlotResultNormalizer<T>;
+  onWin?: (totalWin: number) => void;
+  /** Host hook to acknowledge a finished result (PlatformSession.playAck). Called by `ack()`
+   *  with the raw host result of the most recent play. On Stake this is what settles the round
+   *  (`/wallet/end-round`) AFTER the win animation — so the scene must call `ack()` once it has
+   *  finished presenting each result. */
+  ack?: (raw: unknown) => void;
+}
+
+/** A bound play/ack pair the host uses to drive the play loop (createSlotGame → runRound). */
+export interface SlotPlay<T extends SlotSpinResultBase> {
+  /** play → normalize → onWin(totalWin) → return T. Pass `roundId` to advance an in-flight round
+   *  (drain the next segment of a multi-segment bonus) instead of starting a new one. */
+  play(action: string, bet: number, roundId?: string): Promise<T>;
+  /** Acknowledge the most recent result (call AFTER its animation). Settles the round on Stake. */
+  ack(): void;
+}
+
+/**
+ * Enrich a normalized result with round-continuation metadata (roundId / nextActions / complete)
+ * read from the raw play result, so a caller can drain the remaining segments of a multi-segment
+ * round by replaying the SAME roundId. The game's normalizer stays focused on render data. Shared by
+ * `createSlotPlay` (normal play) and the host's resume path (draining a recovered open round).
+ */
+export function enrichRoundMeta<T extends SlotSpinResultBase>(result: T, raw: unknown): T {
+  const meta = (raw ?? {}) as {
+    roundId?: string;
+    nextActions?: string[];
+    session?: { completed?: boolean } | null;
+  };
+  result.roundId = meta.roundId;
+  result.nextActions = meta.nextActions;
+  // A round is complete when there is no open session, or the session reports completed. The host
+  // sets a session on every segment, so this is `session.completed` in practice.
+  result.complete = !meta.session || meta.session.completed === true;
+  return result;
+}
+
+/** Build the host play/ack pair. Host-agnostic wiring; unit-testable. The returned `play` stashes
+ *  the raw host result so the matching `ack()` can forward it to `deps.ack` (PlatformSession.playAck)
+ *  once the scene has finished animating. Plays are sequential (awaited), so a single stash is safe. */
+export function createSlotPlay<T extends SlotSpinResultBase>(
+  deps: SlotPlayDeps<T>,
+): SlotPlay<T> {
+  let lastRaw: unknown = null;
+  return {
+    play: async (action, bet, roundId) => {
+      const raw = await deps.play({ action, bet, roundId });
+      lastRaw = raw;
+      const result = enrichRoundMeta(deps.normalize(raw), raw);
+      deps.onWin?.(result.totalWin);
+      return result;
+    },
+    ack: () => {
+      if (lastRaw != null) deps.ack?.(lastRaw);
+    },
+  };
+}