@energy8platform/platform-core 0.26.1 → 0.28.0

package/dist/shell.d.ts

@@ -1,433 +0,0 @@
-type ShellMode = 'base' | 'freeSpins' | 'replay';
-interface CurrencyConfig {
-    symbol: string;
-    position: 'left' | 'right';
-    /** Maximum fraction digits (default 2). Win / total-win readouts are rounded to this precision;
-     *  balance / bet / prices stay fixed at `minDecimals`. */
-    maxDecimals?: number;
-    /** Minimum fraction digits (defaults to `maxDecimals`). For win / total-win, 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). Everything else is shown at exactly this many. */
-    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;
-    /** Override the card UI. Return the card's inner content; the shell keeps the grid wrapper,
-     *  accent vars and live re-pricing, and runs the normal buy flow when you call `ctx.select()`. */
-    custom?: (ctx: BonusCardContext) => HTMLElement;
-}
-/** Context passed to a `BonusOption.custom` renderer. Render the card however you like and wire
- *  your own control to `select()` — the buy/confirm flow stays internal to the shell. */
-interface BonusCardContext {
-    bonus: BonusOption;
-    /** Current bet. */
-    bet: number;
-    /** Card price = `bonus.priceMultiplier × bet`. */
-    price: number;
-    /** `price` formatted in the shell currency. */
-    priceText: string;
-    /** True when the option can't be bought right now (unaffordable / busy / buy-bonus disabled);
-     *  reflect it in your UI. `select()` is a no-op while disabled. */
-    disabled: boolean;
-    /** Card accent (per-option override or the type default); also set as the `--card-acc` CSS var. */
-    accent: string;
-    /** Proceed through the shell's normal flow: opens the confirm modal, then emits `buyBonusSelect`
-     *  / activates the feature. No-op while `disabled`. */
-    select: () => void;
-}
-interface ThemeConfig {
-    /** Palette scheme: 'dark' (default) for dark games, 'light' for light backgrounds. */
-    scheme?: 'dark' | 'light';
-    /** Brand accent — active states, the SPIN hover glow, and the BUY BONUS button.
-     *  (Per-bonus card accents are set on each `BonusOption.accentColor`.) */
-    accent?: 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];
-/** A named winning shape: an arbitrary set of grid cells (not one-per-column like a payline),
- *  shown as a grid illustration with its name and optional description. */
-interface ShapeDef {
-    /** The lit cells, in any pattern. */
-    cells: CellRef[];
-    name: string;
-    description?: string;
-}
-/** 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[];
-} | {
-    kind: 'shapes';
-    shapes: ShapeDef[];
-});
-/** 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: 'hotkeys';
-    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[];
-}
-/** Autoplay limits. Presence of this object (vs `null`) is what enables autoplay. */
-interface AutoplayConfig {
-    /** Maximum selectable spin count in the autoplay picker. Caps the built-in presets and
-     *  drops the unlimited (∞) choice; if it isn't already a preset it becomes the top choice.
-     *  Omit for the default presets (including ∞). */
-    maxCount?: number;
-}
-interface ShellFeatures {
-    turbo: 0 | 1 | 2 | 3;
-    /** Master keyboard-shortcut switch. Defaults to `true`; set `false` to disable ALL hotkeys
-     *  (overrides `spacebar` and any future hotkey). */
-    hotkeys?: boolean;
-    /** Spacebar starts a spin in base mode. Defaults to `true`; set `false` to disable the
-     *  keyboard shortcut (e.g. jurisdictions that forbid quick-spin keys). */
-    spacebar?: boolean;
-    /** Autoplay: `null` (or omitted) disables it; an object enables it (optionally with limits). */
-    autoplay?: AutoplayConfig | null;
-    buyBonus: BonusOption[] | false;
-}
-interface AutoplayOptions {
-    active: boolean;
-    remaining: number;
-}
-interface FreeSpinsState {
-    /** Spin index for the `current / total` counter. Set to `null` (or omit) to instead show just
-     *  `total` as a single number — drive a countdown by decrementing `total` each spin. */
-    current?: number | null;
-    total: number;
-    totalWin: 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;
-    /** Optional keyboard handler — called by the shell keyboard controller while this modal is
-     *  open. Return true to consume the key (prevents bar actions + Escape close); false to let
-     *  the controller handle it (Escape → closeModal). */
-    onKey?: (e: KeyboardEvent) => boolean;
-}
-interface ShellConfig {
-    mount: HTMLElement;
-    theme?: ThemeConfig;
-    gameInfo: GameInfoContent;
-    language: string;
-    /** Game version shown in the game-info footer (e.g. '1.2.0'). Defaults to '1.0.0'. The footer
-     *  stamp is `${version}.${engineVersionWithoutDots}` — e.g. game 1.0.0 on engine 0.24.6 → '1.0.0.0246'. */
-    version?: 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;
-    /** Mark this shell as a read-only historical-round replay. A replay never shows the player's
-     *  balance (there's no live wallet), even while its free-spins phase runs in `freeSpins` mode.
-     *  Defaults to `mode === 'replay'`; set explicitly when a replay starts in another mode. */
-    replay?: boolean;
-    features: ShellFeatures;
-    /** Override the BUY BONUS bar button's action: when set, tapping it calls this instead of
-     *  opening the built-in buy-bonus overlay (e.g. the game shows its own bonus UI). The button
-     *  is shown whenever this OR `features.buyBonus` is set. */
-    onBonusBuy?: () => void;
-}
-interface ShellState {
-    mode: ShellMode;
-    /** Sticky replay marker — true for a historical-round replay, regardless of the current
-     *  `mode`. Set once (from config or when `mode` becomes 'replay') and never cleared, since a
-     *  shell instance is either a live game or a replay viewer for its whole lifetime. */
-    replay: boolean;
-    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;
-    };
-}
-
-/**
- * Minimal typed event emitter — internal utility for platform-core.
- *
- * Supports `void` event types — events that carry no data can be emitted
- * without arguments: `emitter.emit('eventName')`.
- *
- * Mirrors the EventEmitter shipped from game-engine's core, copied here
- * so platform-core has no upward dependency on game-engine.
- */
-declare class EventEmitter<TEvents extends {}> {
-    private listeners;
-    on<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
-    once<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
-    off<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
-    emit<K extends keyof TEvents>(...args: TEvents[K] extends void ? [event: K] : [event: K, data: TEvents[K]]): void;
-    removeAllListeners(event?: keyof TEvents): this;
-}
-
-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 kbd;
-    private i18n;
-    /** onKey handler of the currently open modal/overlay, if any (set in showModal, cleared in closeModal). */
-    private modalOnKey;
-    /** Shared sound on/off state — Settings speaker toggle and the Shift+M hotkey stay in sync. The
-     *  game listens to `settingChange({ key: 'sound' })` to (un)mute audio. */
-    soundOn: boolean;
-    /** Set by the open Settings modal so Shift+M live-updates its speaker icon; cleared on close. */
-    private soundRefresh;
-    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;
-    /** Pull window focus into the iframe on first pointer interaction so `document` keydown (the
-     *  spacebar shortcut) fires. No-op / harmless when already focused or full-page. */
-    private pullFocus;
-    setLayout(layout: 'wide' | 'mobile'): void;
-    /** Resolve a built-in shell string through the i18n resolver (translation + optional socialize). */
-    t(text: string): string;
-    /** Toggle the social vocabulary at runtime (rebuilds resolver, re-renders bar). */
-    setSocial(isSocial: boolean): void;
-    /** Swap the active language at runtime (rebuilds resolver, re-renders bar). */
-    setLanguage(lang: string): 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;
-    /** Currency-aware money formatter for WIN amounts (variable decimals: 0.0041 stays 0.0041, not
-     *  0.00). The host hands this to a scene so games format money without knowing the currency. */
-    formatWin(value: number): string;
-    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;
-    /** The bar's design width (px). When the frame is narrower, the bar fit-scales DOWN with the
-     *  screen — the SAME factor in every mode, so replay/free-spins shrink like base instead of
-     *  staying full-size on a popout. */
-    private static readonly BAR_REF_WIDTH;
-    /** Lower bound on the bar fit-scale (guards a degenerate near-zero frame). */
-    private static readonly BAR_MIN_SCALE;
-    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;
-    /** Programmatically dismiss whatever modal/overlay is currently shown (e.g. auto-close the
-     *  reconnect overlay once the link is restored). No-op when nothing is open. */
-    closeModal(): void;
-    /** Flip the shared sound state, notify the game (`settingChange({ key: 'sound' })`), and live-update
-     *  the Settings speaker icon if that modal is open. Used by both the Settings toggle and Shift+M. */
-    setSound(on: boolean): void;
-    /** The Settings modal registers an icon-updater while open (cleared on close). */
-    setSoundRefresh(fn: ((on: boolean) => void) | null): 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>;
-}
-
-/** Rewrite restricted gambling terms in `text` to social-safe phrasing, preserving case. */
-declare function socialize(text: string): string;
-type Lang = 'de' | 'en' | 'es' | 'fi' | 'fr' | 'hi' | 'id' | 'ja' | 'ko' | 'pl' | 'pt' | 'ru' | 'tr' | 'vi' | 'zh' | 'da';
-declare function normalizeLang(code: string | null | undefined): Lang;
-interface I18nOptions {
-    language: string;
-    isSocial?: boolean;
-    messages?: Partial<Record<Lang, Record<string, string>>>;
-}
-interface I18n {
-    readonly lang: Lang;
-    t(src: string): string;
-}
-declare function createI18n(opts: I18nOptions): I18n;
-
-declare function createGameShell(config: ShellConfig): GameShell;
-declare function removeGameShell(): Promise<void>;
-
-export { GameShell, createGameShell, createI18n, normalizeLang, removeGameShell, socialize };
-export type { AutoplayConfig, AutoplayOptions, BonusCardContext, BonusOption, CellRef, CurrencyConfig, FreeSpinsState, GameInfoContent, GameInfoSection, GameMode, I18n, I18nOptions, Lang, ModalAction, ModalOptions, PaylineDef, PaytableRow, ReplayModalOptions, ShapeDef, ShellConfig, ShellEvents, ShellFeatures, ShellMode, ShellState, ThemeConfig, WinSection };