@energy8platform/platform-core 0.25.3 → 0.26.0

package/dist/index.d.ts

@@ -439,6 +439,48 @@ declare class PlatformSession extends EventEmitter<PlatformSessionEvents> {
  */
 declare function createPlatformSession(config?: PlatformSessionConfig): Promise<PlatformSession>;
 
+/**
+ * A live binding between the CSS preloader's lifecycle API
+ * (`setCSSPreloaderProgress` / `waitCSSPreloaderTap`) and the variant's own
+ * DOM. Returned by {@link PreloaderVariant.mount}; `null` when the variant has
+ * no progress target (e.g. a custom-HTML override), which makes the lifecycle
+ * inert.
+ */
+interface PreloaderVariantHandle {
+    /** Drive the progress indicator. `p` is already clamped to [0, 1]. */
+    setProgress(p: number, showPercentage: boolean): void;
+    /** Swap the waiting indicator to the tap-to-start cue. */
+    showTapText(text: string): void;
+}
+/**
+ * A selectable visual identity for the CSS preloader. Encapsulates the markup,
+ * its scoped CSS (animations + logo styling), and how progress/tap are driven —
+ * everything `CSSPreloader.ts` does NOT own (it keeps overlay/background/fade
+ * infrastructure and the shared tap-listener machinery).
+ */
+interface PreloaderVariant {
+    /** Inner HTML for the overlay (including the variant's own content wrapper). */
+    buildContentHTML(config?: LoadingScreenConfig): string;
+    /** Variant-specific CSS appended after the shared base styles. */
+    css: string;
+    /**
+     * Bind to the freshly-mounted overlay and return a handle, or `null` if the
+     * variant's progress target is absent (lifecycle then becomes inert).
+     */
+    mount(overlay: HTMLElement, config?: LoadingScreenConfig): PreloaderVariantHandle | null;
+}
+
+/**
+ * Registry of selectable preloader variants. Add a new variant by writing a
+ * file in this folder and adding one entry here — `PreloaderVariantName` and
+ * `LoadingScreenConfig.preloaderVariant` widen automatically.
+ */
+declare const VARIANTS: {
+    readonly energy8: PreloaderVariant;
+    readonly voidmoon: PreloaderVariant;
+};
+type PreloaderVariantName = keyof typeof VARIANTS;
+
 interface AssetEntry {
     alias: string;
     src: string | string[];
@@ -453,6 +495,12 @@ interface AssetManifest {
     bundles: AssetBundle[];
 }
 interface LoadingScreenConfig {
+    /**
+     * Which visual identity the CSS preloader renders. Defaults to `'energy8'`;
+     * an unknown value falls back to the default. Ignored when `cssPreloaderHTML`
+     * is set (custom HTML bypasses the variant).
+     */
+    preloaderVariant?: PreloaderVariantName;
     /** Background color (hex number or CSS string) */
     backgroundColor?: number | string;
     /** Background gradient (CSS string applied to the CSS preloader) */
@@ -660,6 +708,10 @@ type GameInfoSection = {
     type: 'controls';
     title?: string;
     order?: number;
+} | {
+    type: 'hotkeys';
+    title?: string;
+    order?: number;
 } | {
     type: 'paytable';
     title?: string;
@@ -684,6 +736,9 @@ interface AutoplayConfig {
 }
 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;
@@ -731,6 +786,10 @@ interface ModalOptions {
     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;
@@ -816,7 +875,15 @@ declare class GameShell extends EventEmitter<ShellEvents> {
     private prevBalance;
     private prevWin;
     private moneyAnims;
-    private keysBound;
+    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;
@@ -827,20 +894,16 @@ declare class GameShell extends EventEmitter<ShellEvents> {
      * 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 when `features.spacebar` is
-     *  false, 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. */
     /** 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;
-    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. */
+    /** Resolve a built-in shell string through the i18n resolver (translation + optional socialize). */
     t(text: string): string;
-    /** Toggle the social vocabulary at runtime (re-renders the bar; reopen overlays to refresh them). */
+    /** 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;
@@ -866,9 +929,12 @@ declare class GameShell extends EventEmitter<ShellEvents> {
     /** 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;
-    /** Max fraction of the frame HEIGHT the bottom bar may occupy before it fit-scales down. Keeps the
-     *  bar a consistent, small slice on short popouts in EVERY mode (base ≈ this already via width). */
-    private static readonly BAR_MAX_FRACTION;
+    /** 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. */
@@ -885,6 +951,11 @@ declare class GameShell extends EventEmitter<ShellEvents> {
     /** 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. */