@energy8platform/shell 0.2.0

package/src/core/format.ts

@@ -0,0 +1,39 @@
+import type { CurrencyConfig } from './types';
+
+/** The shared money formatter for every shell readout (balance, win, total win, bet, prices).
+ *
+ *  `maxDecimals` is the MAXIMUM fraction digits (default 2); `minDecimals` (defaults to
+ *  `maxDecimals`) is the MINIMUM. By default the value is shown at exactly `minDecimals` places.
+ *  With `variableDecimals` — used only for win / total-win — it is rounded to `maxDecimals`, then
+ *  trailing zeros are trimmed down to (but never past) `minDecimals`, so small wins keep their
+ *  significant digits. Balance / bet / prices stay fixed at `minDecimals`.
+ *
+ *  Example with `maxDecimals: 4, minDecimals: 2`:
+ *    fixed    → 0.0673 → 0,07     0.3 → 0,30
+ *    variable → 0.0673 → 0,0673   0.067 → 0,067   0.3 → 0,30   0 → 0,00
+ */
+export function formatCurrency(value: number, currency: CurrencyConfig, variableDecimals = false): string {
+  const maxDecimals = currency.maxDecimals ?? 2;
+  const minDecimals = Math.max(0, Math.min(maxDecimals, currency.minDecimals ?? maxDecimals));
+  const thousands = currency.separator?.thousands ?? '.';
+  const decimal = currency.separator?.decimal ?? ',';
+  const safe = Number.isFinite(value) ? value : 0;
+
+  // fixed callers round at minDecimals; variable callers round at maxDecimals then trim back down.
+  const places = variableDecimals ? maxDecimals : minDecimals;
+  const fixed = safe.toFixed(places);
+  const [intPart, rawFrac = ''] = fixed.split('.');
+  // trim trailing zeros, but keep at least `minDecimals` fraction digits
+  let fracPart = rawFrac;
+  if (fracPart.length > minDecimals) {
+    fracPart = fracPart.replace(/0+$/, '');
+    if (fracPart.length < minDecimals) fracPart = fracPart.padEnd(minDecimals, '0');
+  }
+
+  const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, thousands);
+  const number = fracPart.length ? `${grouped}${decimal}${fracPart}` : grouped;
+
+  return currency.position === 'left'
+    ? `${currency.symbol}${number}`
+    : `${number} ${currency.symbol}`;
+}

package/src/core/i18n.ts

@@ -0,0 +1,96 @@
+import { LOCALES } from './locales';
+
+// Social-casino language. English is the source (and, for now, the only) language; `socialize`
+// rewrites the restricted gambling vocabulary into social-safe phrasing while preserving case.
+//
+// Ordering matters: the longest / most specific phrases are listed first so they win over their
+// constituent words (e.g. "buy bonus" before "buy", "pay out" before "pay"). The JS alternation
+// tries entries left-to-right at each position, so a phrase earlier in this list takes priority.
+//
+// Conflicting duplicates in the source table are resolved to a single replacement here
+// (betting→playing, total bet→total play, paid out→won, pays out→win).
+const RULES: ReadonlyArray<readonly [string, string]> = [
+  ['be awarded to player’s accounts', 'appear in player’s accounts'],
+  ["be awarded to player's accounts", "appear in player's accounts"],
+  ['place your bets', 'come and play / join in the game'],
+  ['at the cost of', 'for'],
+  ['cost of', 'can be played for'],
+  ['win feature', 'play feature'],
+  ['total bet', 'total play'],
+  ['buy bonus', 'get bonus'],
+  ['bonus buy', 'bonus / feature'],
+  ['pay out', 'win / won'],
+  ['paid out', 'won'],
+  ['pays out', 'win'],
+  ['payout', 'win'], // single word; "pay out" (spaced) is handled above
+  ['paytable', 'win table'],
+  ['paylines', 'winlines'],
+  ['payline', 'winline'],
+  ['bet/s', 'play/s'],
+  ['betting', 'playing'],
+  ['rebet', 'respin'],
+  ['stake', 'play amount'],
+  ['payer', 'winner'],
+  ['bets', 'plays'],
+  ['pays', 'wins'],
+  ['paid', 'won'],
+  ['bought', 'instantly triggered'],
+  ['purchase', 'play'],
+  ['price', 'play'],
+  ['cost', 'play'], // standalone; the "cost of" / "at the cost of" phrases above win first
+  ['deposit', 'get coins'],
+  ['withdraw', 'redeem'],
+  ['currency', 'token'],
+  ['gamble', 'play'],
+  ['wager', 'play'],
+  ['credit', 'balance'],
+  ['money', 'coins'],
+  ['cash', 'coins'],
+  ['fund', 'balance'],
+  ['bet', 'play'],
+  ['pay', 'win'],
+  ['buy', 'play'],
+];
+
+const MAP = new Map(RULES.map(([k, v]) => [k.toLowerCase(), v] as const));
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+// Letter-bounded so we only swap whole words/phrases (e.g. "pay" inside "Autoplay" is left alone).
+const PATTERN = new RegExp(`(?<![A-Za-z])(?:${RULES.map(([k]) => escapeRe(k)).join('|')})(?![A-Za-z])`, 'gi');
+
+/** Carry the matched text's capitalisation onto the replacement: ALL CAPS → upper, Capitalised
+ *  (first letter) → capitalise the replacement's first letter, otherwise lower-case as written. */
+function applyCase(match: string, repl: string): string {
+  const letters = match.replace(/[^A-Za-z]/g, '');
+  if (letters && letters === letters.toUpperCase()) return repl.toUpperCase();
+  if (/^[^A-Za-z]*[A-Z]/.test(match)) return repl.charAt(0).toUpperCase() + repl.slice(1);
+  return repl;
+}
+
+/** Rewrite restricted gambling terms in `text` to social-safe phrasing, preserving case. */
+export function socialize(text: string): string {
+  return text.replace(PATTERN, (m) => {
+    const repl = MAP.get(m.toLowerCase());
+    return repl == null ? m : applyCase(m, repl);
+  });
+}
+
+export type Lang = 'de'|'en'|'es'|'fi'|'fr'|'hi'|'id'|'ja'|'ko'|'pl'|'pt'|'ru'|'tr'|'vi'|'zh'|'da';
+export const LANGS: readonly Lang[] = ['de','en','es','fi','fr','hi','id','ja','ko','pl','pt','ru','tr','vi','zh','da'];
+const LANG_SET = new Set<string>(LANGS);
+
+export function normalizeLang(code: string | null | undefined): Lang {
+  const base = (code ?? '').toLowerCase().split(/[-_]/)[0];
+  return (LANG_SET.has(base) ? base : 'en') as Lang;
+}
+
+export interface I18nOptions { language: string; isSocial?: boolean; messages?: Partial<Record<Lang, Record<string, string>>>; }
+export interface I18n { readonly lang: Lang; t(src: string): string; }
+
+export function createI18n(opts: I18nOptions): I18n {
+  const lang = normalizeLang(opts.language);
+  const t = (src: string): string => {
+    if (lang === 'en') return opts.isSocial ? socialize(src) : src;
+    return opts.messages?.[lang]?.[src] ?? LOCALES[lang]?.[src] ?? src;
+  };
+  return { lang, t };
+}

package/src/core/index.ts

@@ -0,0 +1,35 @@
+import { ShellController, type CreateShellOptions } from './ShellController';
+import type { ShellSurface, SafeArea } from './renderer';
+
+/** A shell: the renderer-agnostic controller plus the surface facade (safeArea/barHeight/setVisible)
+ *  an embedding host reads. `createShell`, `createGameShell` and `createPixiShell` all return this. */
+export type Shell = ShellController & ShellSurface;
+
+const NO_INSET: SafeArea = { top: 0, right: 0, bottom: 0, left: 0 };
+
+/** Create a shell with an explicit renderer instance (custom or a built-in HtmlRenderer/PixiRenderer).
+ *  Built-in renderers also have the createGameShell/createPixiShell sugar in /html and /pixi.
+ *
+ *  The returned controller is augmented with the `ShellSurface` facade, delegating to the renderer's
+ *  optional surface members (inert defaults when it has none) — so any renderer, custom included, is
+ *  drivable by an embedding host (e.g. game-engine's createSlotGame) without Pixi-specific glue. */
+export function createShell(opts: CreateShellOptions): Shell {
+  const controller = new ShellController(opts);
+  const r = opts.renderer;
+  Object.defineProperties(controller, {
+    safeArea: { get: () => r.safeArea ?? NO_INSET, enumerable: true, configurable: true },
+    barHeight: { get: () => r.barHeight ?? 0, enumerable: true, configurable: true },
+    setVisible: { value: (v: boolean) => r.setVisible?.(v), enumerable: true, configurable: true },
+  });
+  return controller as Shell;
+}
+
+export { ShellController, resolveConfig } from './ShellController';
+export type { CreateShellOptions } from './ShellController';
+export * from './renderer';
+export * from './types';
+export { resolveTheme, SCHEMES, DEFAULT_ACCENT } from './theme';
+export type { ShellTokens } from './theme';
+export { createI18n, socialize, normalizeLang } from './i18n';
+export type { Lang, I18n, I18nOptions } from './i18n';
+export { PACKAGE_VERSION } from './version';

package/src/core/keyboard.ts

@@ -0,0 +1,229 @@
+import type { ShellState } from './types';
+
+export interface KeyboardHost {
+  readonly state: ShellState;
+  readonly hotkeysEnabled: boolean;   // features.hotkeys !== false
+  readonly spacebarEnabled: boolean;  // features.spacebar !== false
+  readonly turboLevels: number;       // features.turbo
+  readonly autoplayEnabled: boolean;  // features.autoplay != null
+  readonly buyBonusEnabled: boolean;  // features.buyBonus !== false
+  hasOpenLayer(): boolean;
+  routeToLayer(e: KeyboardEvent): boolean; // give the key to the top layer's onKey; true if consumed
+  spin(): void;
+  stepBet(dir: 1 | -1): void;
+  toggleAutoplay(): void;
+  cycleTurbo(): void;
+  openBuyBonus(): void;
+  openInfo(): void;
+  openMenu(): void;
+  toggleMute(): void;
+  closeLayer(): void;
+}
+
+// Bet key detection: bet-up needs Shift for arrow/equal, NumpadAdd is bare; same logic for down.
+// Exported so overlays with their own bet stepper (Buy bonus) honour the SAME keys as the bar.
+export function betDir(e: KeyboardEvent): 1 | -1 | null {
+  if (e.code === 'ArrowUp'   && e.shiftKey) return 1;
+  if (e.code === 'Equal'     && e.shiftKey) return 1;
+  if (e.code === 'NumpadAdd')               return 1;
+  if (e.code === 'ArrowDown' && e.shiftKey) return -1;
+  if (e.code === 'Minus'     && e.shiftKey) return -1;
+  if (e.code === 'NumpadSubtract')          return -1;
+  return null;
+}
+
+export class KeyboardController {
+  private host: KeyboardHost;
+  private doc: Document;
+  private spaceHeld = false;
+  private holdTimer: ReturnType<typeof setTimeout> | null = null;
+  // Bet hold-repeat state
+  private betHeldCode: string | null = null;
+  private betTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(host: KeyboardHost, doc?: Document) {
+    this.host = host;
+    this.doc = doc ?? (typeof document !== 'undefined' ? document : (null as unknown as Document));
+  }
+
+  private isSpinAllowed(): boolean {
+    const h = this.host;
+    const s = h.state;
+    return (
+      h.spacebarEnabled &&
+      h.hotkeysEnabled &&
+      !h.hasOpenLayer() &&
+      s.mode === 'base' &&
+      !s.autoplay.active
+    );
+  }
+
+  private isBetAllowed(): boolean {
+    const h = this.host;
+    const s = h.state;
+    return (
+      h.hotkeysEnabled &&
+      !h.hasOpenLayer() &&
+      s.mode === 'base' &&
+      !s.busy
+    );
+  }
+
+  private clearBetTimer(): void {
+    if (this.betTimer !== null) {
+      clearTimeout(this.betTimer);
+      this.betTimer = null;
+    }
+  }
+
+  private startBetRepeat(dir: 1 | -1, elapsed: number): void {
+    // elapsed is ms already spent holding; use it to accelerate toward 45ms floor.
+    // Start at 90ms, decrease ~1ms per 10ms held after the first repeat, floor at 45ms.
+    const interval = Math.max(45, 90 - Math.floor(elapsed / 10));
+    this.betTimer = setTimeout(() => {
+      this.betTimer = null;
+      if (this.betHeldCode !== null && this.isBetAllowed()) {
+        this.host.stepBet(dir);
+        this.startBetRepeat(dir, elapsed + interval);
+      }
+    }, interval);
+  }
+
+  private onKeyDown = (e: KeyboardEvent): void => {
+    const target = e.target as HTMLElement | null;
+    // Editable element guard — never intercept keyboard input
+    if (target && (target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName))) return;
+
+    // For Space: claim preventDefault early (before layer/mode/busy bail) so the browser's
+    // native "Space activates focused button" can't re-fire a shell control and flicker a modal.
+    if (e.code === 'Space' && !e.repeat) {
+      if (!this.host.spacebarEnabled || !this.host.hotkeysEnabled) return;
+      e.preventDefault();
+      if (this.host.hasOpenLayer()) {
+        this.host.routeToLayer(e);
+        return;
+      }
+      const s = this.host.state;
+      if (s.mode !== 'base' || s.busy || s.autoplay.active) return;
+      this.spaceHeld = true;
+      this.host.spin();
+      return;
+    }
+
+    // Bet step keys (Shift+arrows, Shift+=/-, NumpadAdd/Subtract) — non-repeat only
+    if (!e.repeat) {
+      const dir = betDir(e);
+      if (dir !== null && this.isBetAllowed()) {
+        this.betHeldCode = e.code;
+        this.host.stepBet(dir);
+        // First repeat after 350ms initial delay
+        this.clearBetTimer();
+        const capturedDir = dir;
+        this.betTimer = setTimeout(() => {
+          this.betTimer = null;
+          if (this.betHeldCode !== null && this.isBetAllowed()) {
+            this.host.stepBet(capturedDir);
+            this.startBetRepeat(capturedDir, 350);
+          }
+        }, 350);
+        return;
+      }
+    }
+
+    // Non-Space keys: give the open layer first refusal. If it consumes the key, done; Escape closes
+    // it. Anything the layer does NOT consume falls through to the chrome hotkeys below — so the
+    // Settings/Info pages still honour Shift+I (Game info), Shift+M (sound), Shift+S, etc.
+    if (this.host.hasOpenLayer()) {
+      const consumed = this.host.routeToLayer(e);
+      if (consumed) return;
+      if (e.code === 'Escape') { this.host.closeLayer(); return; }
+      // not consumed → fall through to the Shift+letter chrome hotkeys
+    }
+
+    // Shift+letter bar hotkeys — fire when no layer is open, OR when an open layer left the key
+    // unconsumed (see fall-through above); gated on hotkeys being enabled.
+    if (!e.repeat && e.shiftKey && this.host.hotkeysEnabled) {
+      const h = this.host;
+      const s = h.state;
+      switch (e.code) {
+        case 'KeyA':
+          if (h.autoplayEnabled && !s.replay) { h.toggleAutoplay(); return; }
+          break;
+        case 'KeyT':
+          if (h.turboLevels > 0 && !s.replay) { h.cycleTurbo(); return; }
+          break;
+        case 'KeyB':
+          if (h.buyBonusEnabled && s.mode === 'base' && !s.replay) { h.openBuyBonus(); return; }
+          break;
+        case 'KeyI':
+          h.openInfo(); return;
+        case 'KeyS':
+          h.openMenu(); return;
+        case 'KeyM':
+          h.toggleMute(); return;
+      }
+    }
+  };
+
+  private onKeyUp = (e: KeyboardEvent): void => {
+    if (e.code === 'Space') {
+      this.spaceHeld = false;
+      this.clearHoldTimer();
+    }
+    // Stop bet repeat on key release
+    if (e.code === this.betHeldCode) {
+      this.betHeldCode = null;
+      this.clearBetTimer();
+    }
+  };
+
+  private onBlur = (): void => {
+    // Window blur — stop bet repeat AND hold-to-spin (same as releasing both keys)
+    this.betHeldCode = null;
+    this.clearBetTimer();
+    this.spaceHeld = false;
+    this.clearHoldTimer();
+  };
+
+  private clearHoldTimer(): void {
+    if (this.holdTimer !== null) {
+      clearTimeout(this.holdTimer);
+      this.holdTimer = null;
+    }
+  }
+
+  attach(): void {
+    this.doc.addEventListener('keydown', this.onKeyDown);
+    this.doc.addEventListener('keyup', this.onKeyUp);
+    // Use window if available for blur events
+    if (typeof window !== 'undefined') {
+      window.addEventListener('blur', this.onBlur);
+    }
+  }
+
+  detach(): void {
+    this.doc.removeEventListener('keydown', this.onKeyDown);
+    this.doc.removeEventListener('keyup', this.onKeyUp);
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('blur', this.onBlur);
+    }
+    this.spaceHeld = false;
+    this.clearHoldTimer();
+    this.betHeldCode = null;
+    this.clearBetTimer();
+  }
+
+  notifyBusyChanged(busy: boolean): void {
+    if (busy) return;
+    if (!this.spaceHeld) return;
+    if (!this.isSpinAllowed()) return;
+    // Schedule the next spin after the 120 ms floor (gap between completion and next spin).
+    this.clearHoldTimer();
+    this.holdTimer = setTimeout(() => {
+      this.holdTimer = null;
+      if (this.spaceHeld && this.isSpinAllowed()) {
+        this.host.spin();
+      }
+    }, 120);
+  }
+}