@energy8platform/platform-core 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -131,6 +131,41 @@ interface SimulationRawAccumulators {
     hits: number;
 }
 
+/**
+ * A detected replay launch — the host wants to re-play a historical round
+ * instead of placing live bets. `mode`/`roundId` are forwarded verbatim to
+ * {@link ReplayConfig.resolve}.
+ */
+interface ReplayLaunch {
+    /** Game mode the round was recorded in (e.g. "BASE", "BONUS"). */
+    mode?: string;
+    /** Identifier of the recorded round to replay. */
+    roundId?: string;
+}
+/**
+ * Opt-in replay support for the DevBridge mock host.
+ *
+ * In production the casino backend serves a recorded round; in dev the
+ * DevBridge IS the host. Provide a `resolve` callback that returns the
+ * recorded rounds — DevBridge stays agnostic about where they come from
+ * (fetch, static fixtures, localStorage, …). When a replay launch is
+ * detected, the bridge flips `config.replayMode = true` and feeds the
+ * recorded `PlayResultData[]` back on each play request, without touching
+ * the wallet.
+ */
+interface ReplayConfig {
+    /**
+     * Resolve the recorded rounds for a replay launch. Receives the `mode`
+     * and `roundId` from {@link detect}. May be async (e.g. a fetch).
+     */
+    resolve: (mode: string | undefined, roundId: string | undefined) => PlayResultData[] | Promise<PlayResultData[]>;
+    /**
+     * Decide whether this launch is a replay and extract its params.
+     * Defaults to reading `?replay=1&mode=…&event=…` from the browser URL.
+     * Return `null` for a normal (non-replay) launch.
+     */
+    detect?: () => ReplayLaunch | null;
+}
 interface DevBridgeConfig {
     /** Mock initial balance */
     balance?: number;
@@ -154,6 +189,12 @@ interface DevBridgeConfig {
     gameDefinition?: GameDefinition;
     /** RNG seed for deterministic Lua execution */
     luaSeed?: number;
+    /**
+     * Opt-in historical-round replay. When the detector reports a replay
+     * launch, the bridge serves recorded rounds instead of running Lua/onPlay.
+     * See {@link ReplayConfig}.
+     */
+    replay?: ReplayConfig;
 }
 /**
  * Mock host bridge for local development.
@@ -195,7 +236,15 @@ declare class DevBridge {
     private _sessionExpiresAt;
     /** Pre-parsed session TTL from gameDefinition.session_ttl. */
     private _sessionTtlMs;
+    /** Detected replay launch, or null when not replaying. */
+    private _replayLaunch;
+    /** Recorded rounds for the active replay (resolved lazily once). */
+    private _replayResults;
+    /** Cursor into the recorded rounds; wraps to 0 on "Play Again". */
+    private _replayCursor;
     constructor(config?: DevBridgeConfig);
+    /** True when this bridge was launched as a historical-round replay. */
+    get isReplay(): boolean;
     /** Current mock balance */
     get balance(): number;
     /** Start listening for SDK messages */
@@ -207,6 +256,20 @@ declare class DevBridge {
     /** Destroy the dev bridge */
     destroy(): void;
     private handleGameReady;
+    /**
+     * Replay INIT: flip `config.replayMode = true` and take balance/currency
+     * from the recorded results (the wallet is never touched in replay).
+     */
+    private handleReplayGameReady;
+    /** Resolve (and cache) the recorded rounds for the active replay launch. */
+    private resolveReplayResults;
+    /**
+     * Replay PLAY_REQUEST: serve the recorded round at the cursor and advance.
+     * No wallet movement, no bet/session validation. The first spin past the
+     * end resets the cursor to 0 ("Play Again"). An empty record list behaves
+     * like an exhausted live session.
+     */
+    private handleReplayPlay;
     private handlePlayRequest;
     /** Send a PLAY_ERROR correlated to the original PLAY_REQUEST id. */
     private sendError;
@@ -326,6 +389,13 @@ declare class PlatformSession extends EventEmitter<PlatformSessionEvents> {
     get balance(): number;
     /** Current currency from the SDK ('USD' fallback). */
     get currency(): string;
+    /**
+     * `true` when launched as a historical-round replay (the host set
+     * `config.replayMode`). Games read this to hide balance/bet/autoplay UI
+     * and surface a "Play / Play Again" CTA only. Falls back to the handshake
+     * config when no SDK is present.
+     */
+    get isReplay(): boolean;
     /**
      * Send a play request through the SDK and resolve with the host result.
      * Throws if the session was constructed with `sdk: false`.
@@ -427,6 +497,306 @@ interface LogoSVGOptions {
  */
 declare function buildLogoSVG(opts: LogoSVGOptions): string;
 
+type ShellMode = 'base' | 'freeSpins' | 'replay';
+interface CurrencyConfig {
+    symbol: string;
+    position: 'left' | 'right';
+    /** Maximum fraction digits (default 2). The value is rounded to this precision. */
+    decimals?: number;
+    /** Minimum fraction digits (defaults to `decimals`). Trailing zeros are trimmed down to
+     *  this many places, so small wins keep their significant digits (e.g. 0.0673) while round
+     *  amounts stay compact (e.g. 0.30). */
+    minDecimals?: number;
+    separator?: {
+        thousands?: string;
+        decimal?: string;
+    };
+}
+interface BonusOption {
+    id: string;
+    /** 'bonus' buys into a bonus round, 'feature' toggles a base-game modifier (e.g. Ante).
+     *  Drives the card/button label and accent. Defaults to 'bonus'. */
+    type?: 'feature' | 'bonus';
+    title: string;
+    description: string;
+    /** Transparent art image shown at the top of the card (no background plate). */
+    thumbnail?: string;
+    volatility?: 1 | 2 | 3 | 4 | 5;
+    /** Card price = priceMultiplier × current bet, rendered in the shell currency. */
+    priceMultiplier: number;
+    /** Per-option accent override. Falls back to the type default (bonus → purple, feature → gold). */
+    accentColor?: string;
+}
+interface ThemeConfig {
+    /** Palette scheme: 'dark' (default) for dark games, 'light' for light backgrounds. */
+    scheme?: 'dark' | 'light';
+    accent?: string;
+    buyBonusColor?: string;
+}
+/** One paytable entry: a symbol (text/image) and its win tiers, rendered "<count> x<multiplier>". */
+interface PaytableRow {
+    symbol: {
+        text?: string;
+        image?: string;
+    };
+    wins: Array<{
+        count?: string;
+        multiplier: number;
+    }>;
+}
+/** One payline over a cols×rows grid: the row index (0 = top) the line takes in each column. */
+interface PaylineDef {
+    /** length must equal grid.cols; each value in 0..rows-1 */
+    pattern: number[];
+    label?: string;
+}
+/** A single grid cell, 0-based, row 0 = top. */
+type CellRef = [col: number, row: number];
+/** How a game pays — drives the GameInfo win-section illustration. One section = one kind.
+ *  `example`/`winExample`/`loseExample` are optional; omit them for an auto-drawn illustration
+ *  sized to `grid`. */
+type WinSection = {
+    type: 'wins';
+    title?: string;
+    order?: number;
+    grid: {
+        cols: number;
+        rows: number;
+    };
+    /** Optional prose shown alongside the illustration. */
+    description?: string;
+} & ({
+    kind: 'classic';
+    lines: Array<number[] | PaylineDef>;
+} | {
+    kind: 'cluster';
+    minCount: number;
+    example?: CellRef[];
+} | {
+    kind: 'anywhere';
+    minCount: number;
+    example?: CellRef[];
+} | {
+    kind: 'ways';
+    winExample?: CellRef[];
+    loseExample?: CellRef[];
+});
+/** A playable mode / bonus-buy option, shown for comparison (informational only). */
+interface GameMode {
+    title: string;
+    price?: string;
+    rtp?: number;
+    maxWin?: string;
+    description?: string;
+}
+/** A preset game-info section. `order` overrides placement; by default `modes` comes
+ *  first, `controls` second, and the rest follow in declaration order. */
+type GameInfoSection = {
+    type: 'modes';
+    title?: string;
+    order?: number;
+    modes: GameMode[];
+} | {
+    type: 'controls';
+    title?: string;
+    order?: number;
+} | {
+    type: 'paytable';
+    title?: string;
+    order?: number;
+    rows: PaytableRow[];
+} | WinSection | {
+    type: 'custom';
+    title?: string;
+    order?: number;
+    node?: HTMLElement;
+    html?: string;
+};
+interface GameInfoContent {
+    sections?: GameInfoSection[];
+}
+interface ShellFeatures {
+    turbo: 0 | 1 | 2 | 3;
+    autoplay: boolean;
+    buyBonus: BonusOption[] | false;
+}
+interface AutoplayOptions {
+    active: boolean;
+    remaining: number;
+}
+interface FreeSpinsState {
+    current: number;
+    total: number;
+    totalWin: number;
+    lastWin: number;
+}
+/** One footer button of a generic modal. Clicking it runs `on` (if any), then closes the modal. */
+interface ModalAction {
+    title: string;
+    /** Button fill colour (any CSS colour). Omit for a neutral/secondary button. */
+    color?: string;
+    on?: () => void;
+}
+/** Options for `shell.openReplay()` — a non-dismissable replay summary modal.
+ *  `bonusId` is matched against `features.buyBonus` to label the mode and read the cost
+ *  multiplier. There is no ✕ and the backdrop never closes it; the only action is START
+ *  REPLAY, which closes the modal, runs `onReplay`, then reopens it. */
+interface ReplayModalOptions {
+    bonusId: string;
+    /** Base bet the replay was recorded at. */
+    bet: number;
+    payoutMultiplier: number;
+    /** Runs after the modal closes; the modal reopens once it resolves (immediately for sync). */
+    onReplay: () => void | Promise<void>;
+}
+/** Options for `shell.openModal()` — a generic, externally-triggered card modal. */
+interface ModalOptions {
+    /** Show the ✕ in the overlay's top-right corner. */
+    availableClose: boolean;
+    title: string;
+    body: string;
+    /** Footer buttons; each closes the modal (after running its `on`). */
+    actions?: ModalAction[];
+    /** Backdrop blur in px (defaults to the shell's standard blur). */
+    blurLevel?: number;
+}
+interface ShellConfig {
+    mount: HTMLElement;
+    theme?: ThemeConfig;
+    gameInfo: GameInfoContent;
+    language: string;
+    /** When true, all built-in shell text is shown in the social-casino vocabulary (derived from
+     *  English via word-swap rules), regardless of `language`. Game-supplied content is untouched. */
+    isSocial?: boolean;
+    currency: CurrencyConfig;
+    availableBets: number[];
+    defaultBet: number;
+    currentBet: number | null;
+    balance: number;
+    win: number;
+    mode: ShellMode;
+    features: ShellFeatures;
+}
+interface ShellState {
+    mode: ShellMode;
+    balance: number;
+    win: number;
+    bet: number;
+    availableBets: number[];
+    busy: boolean;
+    autoplay: AutoplayOptions;
+    turbo: number;
+    buyBonusEnabled: boolean;
+    freeSpins: FreeSpinsState;
+    /** The currently activated `feature` option (e.g. Ante), or null. Drives the
+     *  effective-bet readout tint and the BUY BONUS → DISABLE toggle on the bar. */
+    activeFeature: BonusOption | null;
+}
+interface ShellEvents {
+    spin: void;
+    betChange: number;
+    autoplayStart: AutoplayOptions;
+    autoplayStop: void;
+    turboChange: number;
+    buyBonusSelect: {
+        id: string;
+    };
+    featureActivate: {
+        id: string;
+    };
+    featureDeactivate: {
+        id: string;
+    };
+    menuOpen: void;
+    settingsOpen: void;
+    infoOpen: void;
+    settingChange: {
+        key: string;
+        value: unknown;
+    };
+}
+
+declare class GameShell extends EventEmitter<ShellEvents> {
+    readonly config: ShellConfig;
+    state: ShellState;
+    private root;
+    private styleEl;
+    private barHost;
+    private modalHost;
+    private destroyed;
+    layout: 'wide' | 'mobile';
+    private ro;
+    private prevBalance;
+    private prevWin;
+    private moneyAnims;
+    private keysBound;
+    constructor(config: ShellConfig);
+    render(): void;
+    private cancelMoneyAnims;
+    /** Keep the WIN pill inline between the groups; float it above when it won't fit. */
+    /**
+     * Landscape bar fills the width when it fits. When it overflows, the WIN pill is
+     * lifted above the bar (unscaled, so it stays readable) and the remaining row is
+     * centred and scaled down to fit — keeping the controls as large as possible.
+     */
+    private applyFitScale;
+    /** Spacebar starts a spin — same path as the spin disc. Ignored while a spin is running,
+     *  while autoplay is active, outside base mode, when an overlay/modal is open, or when an
+     *  editable element is focused. `repeat` (held key) is ignored so it can't spam. */
+    private handleKeyDown;
+    setLayout(layout: 'wide' | 'mobile'): void;
+    /** Resolve a built-in shell string. English is the source; with `isSocial` it is run through
+     *  the social-casino word-swap. Game-supplied strings should NOT be passed through this. */
+    t(text: string): string;
+    /** Toggle the social vocabulary at runtime (re-renders the bar; reopen overlays to refresh them). */
+    setSocial(isSocial: boolean): void;
+    /** Recolour the shell at runtime (e.g. switch dark/light scheme). */
+    setTheme(theme: ThemeConfig): void;
+    private observeLayout;
+    private animateMoney;
+    setBalance(n: number): void;
+    setWin(n: number): void;
+    setBet(n: number): void;
+    setMode(mode: ShellMode): void;
+    setBusy(busy: boolean): void;
+    setAutoplay(a: AutoplayOptions): void;
+    setTurbo(level: number): void;
+    setBuyBonusEnabled(enabled: boolean): void;
+    setFreeSpins(fs: FreeSpinsState): void;
+    private showModal;
+    /** Uniformly scale every open centred card modal (`.ge-sheet`) down so it fits a short/narrow
+     *  popout — the same idea as the bar's fit-scale. Covers the pickers, generic + replay modals,
+     *  AND the buy-bonus confirm (which is hosted inside the overlay, not directly in modalHost).
+     *  Full-screen overlays handle their own responsiveness (scroll + vh-clamp). */
+    fitModals(): void;
+    /** Fraction of the frame a card modal may occupy; the rest is breathing-room margin. Keeps
+     *  modals from filling a small popout edge-to-edge (so even short pickers scale down there). */
+    private static readonly MODAL_FIT;
+    private fitSheet;
+    /** Activate a `feature` option (e.g. Ante): the bar shows the effective bet, tinted with
+     *  the feature accent, and BUY BONUS becomes DISABLE. */
+    activateFeature(bonus: BonusOption): void;
+    /** Clear the active feature — reverts the bet readout and the BUY BONUS button. */
+    deactivateFeature(): void;
+    openMenu(): void;
+    openSettings(): void;
+    openInfo(): void;
+    openBuyBonus(): void;
+    /** Open a generic, externally-driven modal (title + body + optional action buttons).
+     *  Each action runs its `on` then closes; the ✕ shows when `availableClose` is true. */
+    openModal(opts: ModalOptions): void;
+    /** Open the non-dismissable replay summary modal (START REPLAY → onReplay → reopen). */
+    openReplay(opts: ReplayModalOptions): void;
+    /** Bet picker — list of available bets with an accent Confirm. */
+    openBetPicker(): void;
+    /** Autoplay picker — spin-count list; Confirm starts autoplay. */
+    openAutoplayPicker(): void;
+    destroy(): Promise<void>;
+}
+
+declare function createGameShell(config: ShellConfig): GameShell;
+declare function removeGameShell(): Promise<void>;
+
 type NativeRNGKind = 'provably-fair' | 'fast';
 /**
  * Replay mode parameters. Forces single-worker deterministic execution over a
@@ -508,5 +878,5 @@ interface NativeSimulationResult extends SimulationResult {
     replay?: NativeReplayParams;
 }
 
-export { DevBridge, EventEmitter, LOADER_BAR_MAX_WIDTH, PlatformSession, buildLogoSVG, createCSSPreloader, createPlatformSession, removeCSSPreloader, setCSSPreloaderProgress, waitCSSPreloaderTap };
-export type { ActionDefinition, AssetBundle, AssetEntry, AssetManifest, BetLevelsConfig, DevBridgeConfig, DistributionBucket, GameDefinition, LoadingScreenConfig, LuaEngineConfig, LuaPlayResult, MaxWinConfig, NativeSimulationConfig, NativeSimulationResult, PersistentStateConfig, PlatformSessionConfig, PlatformSessionEvents, SDKOptions, SessionConfig, SimulationConfig, SimulationRawAccumulators, SimulationResult, StageStats, TransitionRule };
+export { DevBridge, EventEmitter, GameShell, LOADER_BAR_MAX_WIDTH, PlatformSession, buildLogoSVG, createCSSPreloader, createGameShell, createPlatformSession, removeCSSPreloader, removeGameShell, setCSSPreloaderProgress, waitCSSPreloaderTap };
+export type { ActionDefinition, AssetBundle, AssetEntry, AssetManifest, AutoplayOptions, BetLevelsConfig, BonusOption, CurrencyConfig, DevBridgeConfig, DistributionBucket, FreeSpinsState, GameDefinition, GameInfoContent, LoadingScreenConfig, LuaEngineConfig, LuaPlayResult, MaxWinConfig, NativeSimulationConfig, NativeSimulationResult, PersistentStateConfig, PlatformSessionConfig, PlatformSessionEvents, ReplayConfig, ReplayLaunch, SDKOptions, SessionConfig, ShellConfig, ShellEvents, ShellFeatures, ShellMode, ShellState, SimulationConfig, SimulationRawAccumulators, SimulationResult, StageStats, ThemeConfig, TransitionRule };