@energy8platform/shell 0.2.0

package/src/core/motion.ts

@@ -0,0 +1,10 @@
+/** True when the user (or environment) prefers no motion. Missing matchMedia (jsdom/SSR) is
+ *  treated as reduced so animations never block. */
+export function prefersReducedMotion(): boolean {
+  const mm = (globalThis as { matchMedia?: (q: string) => { matches: boolean } }).matchMedia;
+  if (typeof mm !== 'function') return true;
+  return mm('(prefers-reduced-motion: reduce)').matches;
+}
+
+export const easeOutCubic = (p: number): number => 1 - Math.pow(1 - p, 3);
+export const easeInOutQuad = (p: number): number => (p < 0.5 ? 2 * p * p : 1 - Math.pow(-2 * p + 2, 2) / 2);

package/src/core/renderer.ts

@@ -0,0 +1,121 @@
+import type { EventEmitter } from './EventEmitter';
+import type { ShellTokens } from './theme';
+import type {
+  ResolvedShellConfig, ShellState, ShellEvents, BonusOption,
+  ModalOptions, ReplayModalOptions,
+} from './types';
+
+export type ShellLayoutMode = 'wide' | 'mobile';
+
+/** The view side the controller drives. A renderer holds its own mount target (DOM element /
+ *  Pixi app) and translates state → pixels; it never owns logic. */
+export interface ShellRenderer {
+  /** Bind to the brain. Called once during createShell, before the first renderBar. */
+  mount(host: ShellHost): void;
+  /** (Re)build the bottom bar from host.state. MUST cancel any in-flight money count-up first. */
+  renderBar(): void;
+  /** Switch bar layout. The controller derives wide|mobile from host.notifyResize. */
+  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;
+  /** 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;
+
+  // ── optional surface facade ──────────────────────────────────────────────
+  // A renderer that draws a bottom bar exposes these so an embedding host can reserve space for it
+  // and toggle the whole shell. createShell() forwards them onto the returned shell (with inert
+  // defaults when a renderer omits them), so every renderer — built-in or custom — is host-drivable.
+  /** Insets a scene should avoid (only the bottom bar is reserved; the rest is full-bleed). */
+  readonly safeArea?: SafeArea;
+  /** Height of the bottom control bar in px (0 before first layout / when there's no bar). */
+  readonly barHeight?: number;
+  /** Show/hide the whole shell (bar + overlays). */
+  setVisible?(visible: boolean): void;
+}
+
+/** Bottom-bar inset a host reserves for scene content. */
+export interface SafeArea {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** The surface facade createShell() guarantees on the returned shell, delegating to the renderer
+ *  (inert defaults when the renderer omits a member). Hosts embedding a shell read these. */
+export interface ShellSurface {
+  readonly safeArea: SafeArea;
+  readonly barHeight: number;
+  setVisible(visible: boolean): void;
+}
+
+/** What the renderer (and its components) read from the brain. */
+export interface ShellHost {
+  readonly state: ShellState;
+  readonly config: ResolvedShellConfig;
+  readonly tokens: ShellTokens;
+  readonly layout: ShellLayoutMode;
+  readonly soundOn: boolean;
+  /** Resolve a built-in string (translation + optional socialize). */
+  t(text: string): string;
+  /** Currency-aware money formatting (win=true ⇒ variable decimals). */
+  formatCurrency(n: number, win?: boolean): string;
+  /** Typed event emit — same signature as the shells. */
+  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). */
+  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;
+  /** Logic-bearing actions invoked by renderer controls. */
+  readonly actions: ShellActions;
+}
+
+/** Every state-changing thing a control can do. Each runs logic in the controller, emits the
+ *  matching event, and triggers a re-render. Renderers MUST route input through these. */
+export interface ShellActions {
+  spin(): void;
+  stepBet(dir: 1 | -1): void;
+  setBet(n: number): void;
+  cycleTurbo(): void;
+  toggleAutoplay(): void;
+  startAutoplay(remaining: number): void;
+  stopAutoplay(): void;
+  openMenu(): void;
+  openSettings(): void;
+  openInfo(): void;
+  openBuyBonus(): void;
+  openBetPicker(): void;
+  openAutoplayPicker(): void;
+  selectBuyBonus(id: string): void;
+  activateFeature(b: BonusOption): void;
+  deactivateFeature(): void;
+  setSound(on: boolean): void;
+  closeOverlay(): void;
+}
+
+export interface OverlayHandle {
+  /** Overlay-specific keys (e.g. arrows in a picker). Return true to consume. */
+  onKey?(e: KeyboardEvent): boolean;
+  /** Programmatically close this overlay. */
+  close(): void;
+}
+
+export type OverlayRequest =
+  | { kind: 'settings' }
+  | { kind: 'gameInfo' }
+  | { kind: 'buyBonus' }
+  | { kind: 'betPicker' }
+  | { kind: 'autoplayPicker' }
+  | { kind: 'replay'; opts: ReplayModalOptions }
+  | { kind: 'modal'; opts: ModalOptions };

package/src/core/state.ts

@@ -0,0 +1,31 @@
+import type { ShellConfig, ShellState } from './types';
+
+export function createInitialState(config: ShellConfig): ShellState {
+  return {
+    mode: config.mode,
+    replay: config.replay ?? config.mode === 'replay',
+    balance: config.balance,
+    win: config.win,
+    bet: config.currentBet ?? config.defaultBet,
+    availableBets: [...config.availableBets],
+    busy: false,
+    autoplay: { active: false, remaining: 0 },
+    turbo: 0,
+    buyBonusEnabled: true,
+    freeSpins: { current: 0, total: 0, totalWin: 0 },
+    activeFeature: null,
+  };
+}
+
+/** Step bet up/down within availableBets, clamped at the ends. */
+export function stepBet(state: ShellState, direction: 1 | -1): number {
+  const idx = state.availableBets.indexOf(state.bet);
+  const next = Math.max(0, Math.min(state.availableBets.length - 1, idx + direction));
+  return state.availableBets[next];
+}
+
+/** Cycle turbo level 0..maxLevels (wraps back to 0). */
+export function nextTurbo(current: number, maxLevels: number): number {
+  if (maxLevels <= 0) return 0;
+  return current >= maxLevels ? 0 : current + 1;
+}

package/src/core/theme.ts

@@ -0,0 +1,81 @@
+import type { ThemeConfig } from './types';
+import { BRAND_ACCENT } from './colors';
+
+// Ported 1:1 from platform-core/src/shell/theme.ts. The DOM shell emits these as CSS custom
+// properties; the Pixi shell resolves them to plain colour strings (Pixi's Color accepts hex
+// AND rgba()/rgb() strings) so every surface paints with the exact same value.
+
+export const DEFAULT_ACCENT = BRAND_ACCENT; // brand purple — BUY BONUS + active states (single source: colors.ts)
+
+const PALETTE = {
+  dark: {
+    fg: '#f3f5fa', muted: '#9aa3b6', icon: '#c7cedb', iconActive: '#ffffff',
+    surface: '#0c111c', hairline: 'rgba(255,255,255,.07)',
+    veil: 'rgba(255,255,255,.05)', veilStrong: 'rgba(255,255,255,.1)', track: 'rgba(255,255,255,.16)',
+    soft: '#dfe4ee', spin: '#f4f6fb', spinFg: '#141a28',
+  },
+  light: {
+    fg: '#15202e', muted: '#5a6678', icon: '#3c4658', iconActive: '#0b1220',
+    surface: '#eef1f7', hairline: 'rgba(15,23,42,.12)',
+    veil: 'rgba(15,23,42,.05)', veilStrong: 'rgba(15,23,42,.09)', track: 'rgba(15,23,42,.22)',
+    soft: '#3a4453', spin: '#1c2434', spinFg: '#f3f6fb',
+  },
+} as const;
+
+/** Resolved colour tokens for the shell — scheme palette + the scheme-independent
+ *  "plaque" language shared by the control bar and overlays, plus the game-overridable accent. */
+export interface ShellTokens {
+  fg: string;
+  muted: string;
+  icon: string;
+  iconActive: string;
+  surface: string;
+  hairline: string;
+  veil: string;
+  veilStrong: string;
+  track: string;
+  soft: string;
+  spin: string;
+  spinFg: string;
+  // Plaque tokens (always dark, white-on-dark) — identical in both schemes so the bar +
+  // overlays stay visually identical regardless of the dark/light scheme.
+  plaqueDark: string;
+  plaqueGlass: string;
+  plaqueGlassHover: string;
+  plaqueSolid: string;
+  plaqueLine: string;
+  plaqueLabel: string;
+  // The continuous desktop control-bar surface + the white-disc buttons that sit on it.
+  bar: string;
+  btn: string;
+  btnInk: string;
+  accent: string;
+  // Fixed chrome colours used inline by the CSS (frosted backdrop tint, ways win/lose ticks).
+  backdrop: string;
+  white: string;
+  winOk: string;
+  winNo: string;
+}
+
+export const SCHEMES = ['dark', 'light'] as const;
+
+export function resolveTheme(theme: ThemeConfig = {}): ShellTokens {
+  const p = PALETTE[theme.scheme === 'light' ? 'light' : 'dark'];
+  return {
+    ...p,
+    plaqueDark: 'rgba(6,9,15,.86)',
+    plaqueGlass: 'rgba(30,36,48,.70)',
+    plaqueGlassHover: 'rgba(40,48,64,.86)',
+    plaqueSolid: '#1a2030',
+    plaqueLine: 'rgba(255,255,255,.22)',
+    plaqueLabel: 'rgba(255,255,255,.6)',
+    bar: 'rgba(6,9,15,.86)',
+    btn: '#f4f6fb',
+    btnInk: '#0b0e16',
+    accent: theme.accent ?? DEFAULT_ACCENT,
+    backdrop: 'rgba(12,17,28,.5)',
+    white: '#ffffff',
+    winOk: '#4ade80',
+    winNo: '#f87171',
+  };
+}

package/src/core/types.ts

@@ -0,0 +1,269 @@
+export type ShellMode = 'base' | 'freeSpins' | 'replay';
+
+export 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 };
+}
+
+export 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()`.
+   *  Core uses `unknown`; each renderer re-exports a typed alias (ui/html → HTMLElement,
+   *  ui/pixi → Container). */
+  custom?: (ctx: BonusCardContext) => unknown;
+}
+
+/** 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. */
+export 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;
+}
+
+export 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>". */
+export 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. */
+export 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. */
+export 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. */
+export 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`. */
+export 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). */
+export 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. */
+export 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?: unknown; html?: string };
+
+export interface GameInfoContent {
+  sections?: GameInfoSection[];
+}
+
+/** Autoplay limits. Presence of this object (vs `null`) is what enables autoplay. */
+export 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;
+}
+
+export 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;
+}
+
+export interface AutoplayOptions {
+  active: boolean;
+  remaining: number;
+}
+
+export 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. */
+export 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. */
+export 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. */
+export 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;
+}
+
+export interface ShellConfig {
+  // NOTE: `mount: HTMLElement` is intentionally omitted — mount target is a renderer concern.
+  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;
+}
+
+/** ShellConfig after the controller applies defaults (version, isSocial, replay, theme). No mount. */
+export type ResolvedShellConfig = Required<Pick<ShellConfig,
+  'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>>
+  & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy'>;
+
+export 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;
+}
+
+export 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 };
+}

package/src/core/version.ts

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
+/** The @energy8platform/shell package version, stamped into the game-info footer. */
+export const PACKAGE_VERSION = '0.2.0';