@energy8platform/shell 0.6.5 → 0.7.0

package/dist/html.d.ts

@@ -16,13 +16,117 @@ declare class EventEmitter<TEvents extends {}> {
     removeAllListeners(event?: keyof TEvents): this;
 }
 
+declare const ICON_NAMES: readonly ["spin", "turbo1", "autoplay", "stop", "menu", "minus", "plus", "gift", "info", "soundOn", "soundOff", "close", "back", "chevronRight", "ticket", "turbo2", "turboOff", "chevronUp", "chevronDown"];
+type IconName = (typeof ICON_NAMES)[number];
+
+/** Built-in presets: the id alone is enough — the shell knows the label, icon and behaviour. */
+type MenuPresetId = 'sound' | 'music' | 'sfx' | 'gameInfo';
+declare function isPresetId(id: string): id is MenuPresetId;
+interface MenuItemBase {
+    id: string;
+    /** Overrides the preset/default label. Run through the shell translator. */
+    label?: string;
+    icon?: IconName;
+    disabled?: boolean;
+}
+type MenuPresetItem = {
+    id: MenuPresetId;
+} & Omit<MenuItemBase, 'id'>;
+type MenuToggleItem = {
+    type: 'toggle';
+    value?: boolean;
+    onChange?(v: boolean): void;
+} & MenuItemBase;
+type MenuRangeItem = {
+    type: 'range';
+    min?: number;
+    max?: number;
+    step?: number;
+    value?: number;
+    /** Right-hand readout. Defaults to percent for a 0..1 range, else the raw number. */
+    format?(v: number): string;
+    onChange?(v: number): void;
+} & MenuItemBase;
+type MenuButtonItem = {
+    type: 'button';
+    chevron?: boolean;
+    onSelect?(): void;
+} & MenuItemBase;
+type MenuSeparatorItem = {
+    type: 'separator';
+};
+type MenuItem = MenuPresetItem | MenuToggleItem | MenuRangeItem | MenuButtonItem | MenuSeparatorItem;
+/** The rows shown when `ShellConfig.menu` is omitted — today's Settings content, minus master. */
+declare const DEFAULT_MENU: MenuItem[];
+/** What `resolveMenu` reads. `ShellController` satisfies it; tests can supply a small literal. */
+interface MenuHost {
+    readonly menu: MenuItem[];
+    t(text: string): string;
+    getMenuValue(id: string): boolean | number | undefined;
+    setMenuValue(id: string, value: boolean | number): void;
+    readonly actions: {
+        openInfo(): void;
+    };
+}
+/** A row, ready to draw: no preset knowledge left, no config shapes, just kind + accessors. */
+type MenuRow = {
+    kind: 'separator';
+} | {
+    kind: 'toggle';
+    id: string;
+    label: string;
+    disabled: boolean;
+    /** Glyph for the current value (the sound preset swaps speaker on/off). */
+    icon(value: boolean): IconName | undefined;
+    get(): boolean;
+    set(value: boolean): void;
+} | {
+    kind: 'range';
+    id: string;
+    label: string;
+    icon?: IconName;
+    disabled: boolean;
+    min: number;
+    max: number;
+    step: number;
+    get(): number;
+    set(value: number): void;
+    format(value: number): string;
+} | {
+    kind: 'button';
+    id: string;
+    label: string;
+    icon?: IconName;
+    disabled: boolean;
+    chevron: boolean;
+    select(): void;
+};
+/** Range bounds with defaults: 0..1 like a volume slider, step = a twentieth of the span. */
+declare function rangeBounds(item: {
+    min?: number;
+    max?: number;
+    step?: number;
+}): {
+    min: number;
+    max: number;
+    step: number;
+};
+/** Initial values for CUSTOM items (presets keep their own homes). Values already in `prev` win, so
+ *  a later `setMenu()` with the same ids does not reset what the player has changed. */
+declare function seedMenuValues(items: MenuItem[], prev?: Record<string, boolean | number>): Record<string, boolean | number>;
+/** Expand the configured list into render-ready rows. A config mistake — an unknown preset id, an
+ *  unrecognized custom `type`, or an invalid range span — is dropped with one warning rather than
+ *  silently misbehaving: a typo must be visible, not silently invisible. A custom id that collides
+ *  with a reserved preset id also warns, but keeps its row (see `custom()`). */
+declare function resolveMenu(host: MenuHost): MenuRow[];
+
 /** `freeSpins` and `bonus` are the SAME bar layout (host-driven hero + Total Win); `freeSpins` is
  *  kept as a back-compat alias for the common case (its readout is derived current/total), while
  *  `bonus` pairs with `setBonus()` to show a game-supplied label + value (adventure, hold-and-spin,
  *  respins — anything that isn't a plain free-spins counter). */
 type ShellMode = 'base' | 'bonus' | 'freeSpins' | 'replay';
-/** The three independent volume sliders shown in the Settings overlay. */
-type VolumeKey = 'master' | 'music' | 'sfx';
+/** The two independent volume sliders shown in the bar menu. */
+type VolumeKey = 'music' | 'sfx';
 type VolumeLevels = Record<VolumeKey, number>;
 interface CurrencyConfig {
     symbol: string;
@@ -287,11 +391,13 @@ interface ShellConfig {
     onBonusBuy?: () => void;
     /** Initial Settings-overlay volume slider positions (each 0..1, defaults to 1 = 100%). The shell
      *  keeps them stateful across opens; read/update at runtime via `shell.getVolume()` /
-     *  `shell.setVolume()`, and listen to `settingChange` ({ key: 'master'|'music'|'sfx' }) to apply. */
+     *  `shell.setVolume()`, and listen to `settingChange` ({ key: 'music'|'sfx' }) to apply. */
     volumes?: Partial<VolumeLevels>;
+    /** Bar-menu items, in order. Omit for the default list (sound, music, sfx, ─, game info). */
+    menu?: MenuItem[];
 }
 /** ShellConfig after the controller applies defaults (version, isSocial, replay, theme). No mount. */
-type ResolvedShellConfig = Required<Pick<ShellConfig, 'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>> & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes'>;
+type ResolvedShellConfig = Required<Pick<ShellConfig, 'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>> & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes' | 'menu'>;
 interface ShellState {
     mode: ShellMode;
     /** Sticky replay marker — true for a historical-round replay, regardless of the current
@@ -316,9 +422,11 @@ interface ShellState {
     /** 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;
-    /** Volume slider positions (0..1) surfaced in the Settings overlay. Stateful across opens so a
-     *  reopened overlay reflects the last-set positions instead of resetting to 100%. */
+    /** Volume slider positions (0..1) for the two sliders in the menu. */
     volumes: VolumeLevels;
+    /** Values of CUSTOM menu items, keyed by id. Seeded from the item list; preset values live in
+     *  their own homes (`soundOn`, `volumes`) and are reached through `getMenuValue`. */
+    menu: Record<string, boolean | number>;
 }
 interface ShellEvents {
     spin: void;
@@ -390,15 +498,15 @@ interface ShellRenderer {
     setLayout(layout: ShellLayoutMode): void;
     /** Apply colour tokens (CSS vars in DOM / repaint in Pixi). */
     applyTheme(tokens: ShellTokens): void;
-    /** Count a money readout from→to on the freshly-rendered bar (DOM rAF / Pixi ticker). */
-    animateMoney(field: 'balance' | 'win', from: number, to: number): void;
+    /** Count a money readout from→to on the freshly-rendered bar (DOM rAF / Pixi ticker).
+     *  `durationMs` overrides the renderer's default count-up length — a cascade/tumble scene
+     *  reporting a win per step needs each count-up to fit inside its step. */
+    animateMoney(field: 'balance' | 'win', from: number, to: number, durationMs?: number): void;
     /** Build + show an overlay from a controller-supplied model; return a handle for key routing
      *  and programmatic close. Returns void when nothing was shown. */
     openOverlay(req: OverlayRequest): OverlayHandle | void;
     /** Tear down any open overlay. */
     closeOverlay(): void;
-    /** If the open overlay registered a sound-icon refresher, the controller calls this to refresh it. */
-    refreshSoundIcon?(on: boolean): void;
     /** Fade out + remove all nodes; resolve when gone. */
     destroy(): Promise<void> | void;
     /** Insets a scene should avoid (only the bottom bar is reserved; the rest is full-bleed). */
@@ -437,17 +545,21 @@ interface ShellHost {
     emit: EventEmitter<ShellEvents>['emit'];
     /** Renderer reports its surface size; the controller recomputes layout + re-renders. */
     notifyResize(w: number, h: number): void;
-    /** Flip shared sound state (emits settingChange + refreshes an open Settings icon). */
+    /** Flip shared sound state (emits settingChange + refreshes an open menu's sound icon). */
     setSound(on: boolean): void;
-    /** An open Settings overlay registers an icon updater here (null clears it on close). */
-    setSoundRefresh(fn: ((on: boolean) => void) | null): void;
-    /** Current volume slider position (0..1) for master/music/sfx. */
+    /** Current volume slider position (0..1) for music/sfx. */
     getVolume(key: VolumeKey): number;
     /** Set a volume slider (0..1): clamps, stores, emits `settingChange`, and live-updates an open
-     *  Settings overlay. Called by the slider control on drag AND by game code as the public API. */
+     *  menu. Called by the slider control on drag AND by game code as the public API. */
     setVolume(key: VolumeKey, value: number): void;
-    /** An open Settings overlay registers a slider updater here (null clears it on close). */
-    setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void;
+    /** The configured menu items (see core/menu.ts). */
+    readonly menu: MenuItem[];
+    /** Current value of a menu item — presets included (sound → soundOn, music/sfx → volumes). */
+    getMenuValue(id: string): boolean | number | undefined;
+    /** Set a menu value: clamps ranges, stores, emits `settingChange`, refreshes an open menu. */
+    setMenuValue(id: string, value: boolean | number): void;
+    /** An open menu registers a row updater here (null clears it on close). */
+    setMenuRefresh(fn: ((id: string, value: boolean | number) => void) | null): void;
     /** Logic-bearing actions invoked by renderer controls. */
     readonly actions: ShellActions;
     /** Re-show the replay summary modal through the controller (keeps its OverlayHandle in sync).
@@ -485,7 +597,7 @@ interface OverlayHandle {
     close(): void;
 }
 type OverlayRequest = {
-    kind: 'settings';
+    kind: 'menu';
 } | {
     kind: 'gameInfo';
 } | {
@@ -516,14 +628,15 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.6.5";
+    readonly engineVersion = "0.7.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
     private kbd?;
     private overlay;
-    private soundRefresh;
-    private volumeRefresh;
+    private menuItems;
+    private menuRefresh;
+    private overlayKind;
     private prevBalance;
     private prevWin;
     private destroyed;
@@ -536,7 +649,9 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     private attachKeyboard;
     private pullFocus;
     private show;
+    /** Open the bar menu. Called again while it is open, it closes it — the burger toggles. */
     openMenu(): void;
+    /** @deprecated The Settings overlay is gone — this opens the bar menu. */
     openSettings(): void;
     openInfo(): void;
     openBuyBonus(): void;
@@ -547,22 +662,32 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     /** Programmatically dismiss whatever overlay/modal is open. No-op when nothing is shown. */
     closeModal(): void;
     setSound(on: boolean): void;
-    setSoundRefresh(fn: ((on: boolean) => void) | null): void;
     getVolume(key: VolumeKey): number;
     /** Set a volume slider (0..1). Shared by the slider control (drag) and game code (public API):
-     *  clamps, stores so a reopened Settings overlay reflects it, emits `settingChange`, and
-     *  live-updates the slider if the overlay is currently open. */
+     *  clamps, stores so a reopened menu popover reflects it, emits `settingChange`, and
+     *  live-updates the slider if the menu is currently open. */
     setVolume(key: VolumeKey, value: number): void;
-    setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void;
+    get menu(): MenuItem[];
+    /** Replace the item list. Values of ids already in state are kept; new ids are seeded. */
+    setMenu(items: MenuItem[]): void;
+    getMenuValue(id: string): boolean | number | undefined;
+    /** Set a menu value. Presets route to their own homes so there is never a second copy. */
+    setMenuValue(id: string, value: boolean | number): void;
+    setMenuRefresh(fn: ((id: string, value: boolean | number) => void) | null): void;
+    /** Clamp to the declared bounds of a custom `range` item (a non-range id passes through). */
+    private clampRange;
     activateFeature(bonus: BonusOption): void;
     deactivateFeature(): void;
     private money;
     setBalance(n: number): void;
     /** Set the WIN readout. Counts up/down from the previous value by default. Pass
      *  `{ animate: false }` to SNAP instantly (renderBar cancels any in-flight count-up) — used by the
-     *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong. */
+     *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong.
+     *  `{ durationMs }` shortens/lengthens the count-up (default 450ms) — a scene reporting a win per
+     *  cascade step passes its step length so each count-up finishes before the next step lands. */
     setWin(n: number, opts?: {
         animate?: boolean;
+        durationMs?: number;
     }): void;
     setBet(n: number): void;
     setMode(mode: ShellMode): void;
@@ -582,6 +707,56 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     destroy(): Promise<void>;
 }
 
+/** Geometry for the bar-menu popover. Pure math over rectangles so the DOM and Pixi renderers
+ *  place it identically — the renderers only supply measured sizes and apply the result. */
+interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface Surface {
+    w: number;
+    h: number;
+}
+interface PopoverPlacement {
+    /** Top-left of the popover card, in surface coordinates. */
+    x: number;
+    y: number;
+    /** True space on the chosen side, in surface coordinates; may be less than minH on a very short surface. The row list scrolls inside it. */
+    maxH: number;
+    /** Arrow centre, relative to the card's left edge. `-1` when there is no anchor to point at. */
+    arrowX: number;
+    /** True when the card opens below the anchor (arrow flips to the top edge). */
+    below: boolean;
+}
+declare const POPOVER: {
+    /** Keep-out from the surface edges. */
+    readonly margin: 8;
+    /** Space between the anchor and the card. */
+    readonly gap: 8;
+    /** Minimum distance from the arrow tip to either rounded corner. */
+    readonly arrowInset: 14;
+    /** A card shorter than this does not fit — flip to the other side instead. */
+    readonly minH: 120;
+    readonly minW: 220;
+    readonly maxW: 320;
+};
+/** Card width: content width clamped to [minW, maxW] and never wider than the surface. */
+declare function popoverWidth(surfaceW: number, contentW: number): number;
+/** Place the card above the `anchor` (below if it does not fit), left-aligned to it and clamped
+ *  inside the surface. `anchor === null` (no bar / hidden shell) centres it, arrow off.
+ *
+ *  `anchor` drives PLACEMENT (x, y, maxH, below) — normally the bar's whole plaque ("plate"), so the
+ *  card sits flush with the bar as a whole rather than with whichever control opened it. `pointer` is
+ *  the (optional) rect the ARROW points at — normally the burger button, which can sit anywhere
+ *  inside the plate. Defaults to `anchor` when omitted, so every caller that only ever had one rect
+ *  (i.e. every caller before `pointer` existed) keeps behaving exactly as it did before. */
+declare function placePopover(anchor: Rect | null, surface: Surface, size: {
+    w: number;
+    h: number;
+}, pointer?: Rect | null): PopoverPlacement;
+
 /** 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';
@@ -598,7 +773,7 @@ interface I18n {
 declare function createI18n(opts: I18nOptions): I18n;
 
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-declare const PACKAGE_VERSION = "0.6.5";
+declare const PACKAGE_VERSION = "0.7.0";
 
 /** A shell: the renderer-agnostic controller plus the surface facade (safeArea/barHeight/setVisible)
  *  an embedding host reads. `createShell`, `createGameShell` and `createPixiShell` all return this. */
@@ -624,7 +799,11 @@ declare class HtmlRenderer implements ShellRenderer {
     private ro;
     private moneyAnims;
     private modalOnKey;
+    private popoverPosition;
     private destroyed;
+    /** The scale factor last applied to the bar by applyFitScale() — exposed so the menu popover can
+     *  match it exactly (see getBarScale) rather than re-derive its own, possibly-disagreeing, value. */
+    private barScale;
     /** MutationObserver for buy-bonus confirm fit — fires fitModals() when nodes are added
      *  inside the modalHost (e.g. the confirm dialog appended after the grid is open). */
     private mutObs;
@@ -636,13 +815,16 @@ declare class HtmlRenderer implements ShellRenderer {
     applyTheme(tokens: ShellTokens): void;
     renderBar(): void;
     setLayout(): void;
-    animateMoney(field: 'balance' | 'win', from: number, to: number): void;
+    animateMoney(field: 'balance' | 'win', from: number, to: number, durationMs?: number): void;
     openOverlay(req: OverlayRequest): OverlayHandle | void;
     closeOverlay(): void;
-    refreshSoundIcon?(_on: boolean): void;
     destroy(): Promise<void>;
     /** Trigger a bar fit-scale pass (used by tests that stub geometry after the initial render). */
     fitBar(): void;
+    /** The scale factor applyFitScale() last applied to the bar — the menu popover multiplies its own
+     *  card by this SAME number so its typography/padding/row-heights carry the same visual weight
+     *  relationship the bar has, instead of ignoring the viewport like a fixed-px card would. */
+    getBarScale(): number;
     private cancelMoneyAnims;
     private buildOverlay;
     private showModal;
@@ -671,5 +853,5 @@ declare function createGameShell(config: HtmlShellConfig): ShellController;
 /** Tear down the active shell (no argument — singleton). Resolves immediately when nothing is active. */
 declare function removeGameShell(): Promise<void>;
 
-export { DEFAULT_ACCENT, ShellController as GameShell, HtmlRenderer, PACKAGE_VERSION, SCHEMES, ShellController, createGameShell, createI18n, createShell, normalizeLang, removeGameShell, resolveConfig, resolveTheme, socialize };
-export type { AutoplayConfig, AutoplayOptions, BonusCardContext, BonusOption, BonusReadout, CellRef, CreateShellOptions, CurrencyConfig, FreeSpinsState, GameInfoContent, GameInfoSection, GameMode, HtmlShellConfig, I18n, I18nOptions, Lang, ModalAction, ModalOptions, OverlayHandle, OverlayRequest, PaylineDef, PaytableRow, ReplayModalOptions, ResolvedShellConfig, SafeArea, ShapeDef, Shell, ShellActions, HtmlShellConfig as ShellConfig, ShellEvents, ShellFeatures, ShellHost, ShellLayoutMode, ShellMode, ShellRenderer, ShellState, ShellSurface, ShellTokens, ThemeConfig, VolumeKey, VolumeLevels, WinSection };
+export { DEFAULT_ACCENT, DEFAULT_MENU, ShellController as GameShell, HtmlRenderer, PACKAGE_VERSION, POPOVER, SCHEMES, ShellController, createGameShell, createI18n, createShell, isPresetId, normalizeLang, placePopover, popoverWidth, rangeBounds, removeGameShell, resolveConfig, resolveMenu, resolveTheme, seedMenuValues, socialize };
+export type { AutoplayConfig, AutoplayOptions, BonusCardContext, BonusOption, BonusReadout, CellRef, CreateShellOptions, CurrencyConfig, FreeSpinsState, GameInfoContent, GameInfoSection, GameMode, HtmlShellConfig, I18n, I18nOptions, Lang, MenuHost, MenuItem, MenuPresetId, MenuRow, ModalAction, ModalOptions, OverlayHandle, OverlayRequest, PaylineDef, PaytableRow, PopoverPlacement, Rect as PopoverRect, ReplayModalOptions, ResolvedShellConfig, SafeArea, ShapeDef, Shell, ShellActions, HtmlShellConfig as ShellConfig, ShellEvents, ShellFeatures, ShellHost, ShellLayoutMode, ShellMode, ShellRenderer, ShellState, ShellSurface, ShellTokens, ThemeConfig, VolumeKey, VolumeLevels, WinSection };