@stakeplate/core 0.1.0

package/dist/index-BcTRfis9.d.ts

@@ -0,0 +1,276 @@
+import { m as Round } from "./protocol-C1KamF3t.js";
+import { t as NetworkManager } from "./network-pBW8CX1o.js";
+import { n as RootStore } from "./index-BBlN97RY.js";
+import { a as Ticker, t as HudPort } from "./hud-port-DNfotn4U.js";
+import { BootedHud } from "@open-slot-ui/pixi";
+import { Bus, BusGroup, Engine } from "@schmooky/zvuk";
+//#region src/engine/turbo.d.ts
+/** Delay multipliers per turbo level: off (1×) / turbo (0.4×) / super (0.12×). */
+declare const DEFAULT_TURBO_SPEEDS: number[];
+interface TurboState {
+  /** 0 = off, 1 = turbo, 2 = super — the HUD turbo cycler's index. */
+  readonly level: number;
+  /** The delay multiplier for the current level (`ctx.turbo.delay` already applies it). */
+  readonly speed: number;
+  /** True once the player slam-stopped this round (delays resolve instantly). */
+  readonly skipped: boolean;
+  /** A turbo- + slam-stop-aware delay for GAME animations. NOT for compliance waits. */
+  delay(ms: number): Promise<void>;
+}
+declare class TurboClock implements TurboState {
+  private readonly speeds;
+  private _level;
+  private _skipped;
+  private readonly pending;
+  constructor(speeds?: number[]);
+  get level(): number;
+  get speed(): number;
+  get skipped(): boolean;
+  /** Set the turbo level (clamped to the configured speeds). */
+  setLevel(index: number): void;
+  /** Slam-stop: resolve every in-flight delay + make the rest of the round instant. */
+  skip(): void;
+  /** Clear the slam-stop flag — the core calls this at the start of each spin. */
+  resetSkip(): void;
+  delay(ms: number): Promise<void>;
+}
+//#endregion
+//#region src/engine/round.d.ts
+/** Money facts of a settled round (all MAJOR units except `multiplier`, a ratio). */
+interface RoundInfo {
+  mode: string;
+  /** Base bet (before the mode's cost multiplier). */
+  bet: number;
+  /** Mode cost multiplier (× base bet) — the stake charged. */
+  cost: number;
+  /** The amount staked = bet × cost. */
+  stake: number;
+  /** Round multiplier relative to the BASE bet (totalWin / bet). */
+  multiplier: number;
+  /** Total win credited this round (derived: multiplier × bet). */
+  totalWin: number;
+  /** The server's AUTHORITATIVE win (`raw.payout`, major units); falls back to totalWin
+   *  when the round carries no explicit payout. Trust this over `totalWin` when they differ. */
+  payout: number;
+}
+/**
+ * A resolved round: money facts + the game's parsed model + the raw wire round. `E` is the
+ * game's book-event type — declared once on `createStakeGame`, so `raw` (and `interpretBook`)
+ * are TYPED rather than `unknown`.
+ */
+interface GameRound<T = unknown, E = unknown> extends RoundInfo {
+  /** The game's parsed model, from `interpretBook` — driven to the Present phase. */
+  data: T;
+  /** Whether the raw round still needs `/wallet/end-round` (the engine settles it). */
+  active: boolean;
+  /** Authoritative post-settlement balance (major units) — applied by the Settle phase. */
+  balance: number;
+  /** The raw, fully-typed wire round — the game's real server data. */
+  raw: Round<E>;
+}
+/** The game's ONE money-logic seam: parse the raw round's (typed) events into your model. Pure. */
+type InterpretBook<T, E = unknown> = (raw: Round<E>, info: RoundInfo) => T;
+/** Build the money facts from a raw wire round + the base bet + the mode cost. */
+declare function roundInfo<E = unknown>(raw: Round<E>, bet: number, cost: number): RoundInfo;
+//#endregion
+//#region src/game/config.d.ts
+interface ModeConfig {
+  /** Cost multiplier (× base bet). `base` is 1. */
+  cost: number;
+  /** A one-shot bought bonus — shown as a `Buy` card in the buy-feature modal (opened by the
+   *  bonus button). Buying it spins this mode once (through the jurisdiction confirm gate). */
+  buy?: boolean;
+  /** An activatable per-spin bet surcharge — shown as an `Activate` card (vs a one-tap `Buy`). */
+  boost?: boolean;
+  /** Display name for the feature card (defaults to the capitalized mode key). */
+  name?: string;
+  /** Card art (URL or data URI) for the feature card. A neutral gradient is used when absent. */
+  image?: string;
+}
+interface GameConfig {
+  title: string;
+  version?: string;
+  /** Fallback currency code; the session/`?currency=` wins. */
+  currency?: string;
+  /**
+   * Theoretical RTP percentage — DISPLAY ONLY (the RTP readout + rules). NOT authoritative:
+   * the server (`auth.config.rtp`) wins, and the certified math report is the source of
+   * truth. This is only a last-resort fallback; prefer never hand-typing it (drift risk).
+   */
+  rtp?: number;
+  /** Mode key → cost multiplier (a number) or a `ModeConfig`. `base` defaults to 1. */
+  modes?: Record<string, ModeConfig | number>;
+  /** Rules/info menu for the HUD (`@open-slot-ui` `MenuSpec`) — build it with `@stakeplate/core/rules` `buildRules`. */
+  rules?: unknown;
+  /** i18n messages per locale (`{ en: { key: text }, es: {…} }`) for the HUD + rules text. */
+  messages?: Record<string, Record<string, string>>;
+  /** SOCIAL/sweepstakes wording per locale — swapped in when social mode is on. Merge in
+   *  `buildRules().socialEn` so the core's disclaimer/guide are social-safe. */
+  socialMessages?: Record<string, Record<string, string>>;
+  /** Delay multipliers per turbo level (off / turbo / super). Default `[1, 0.4, 0.12]`. */
+  turboSpeeds?: number[];
+  /** Pause (ms) between autoplay/hold spins. Default 250. Scales with turbo. */
+  autoplayGapMs?: number;
+  /** Extra `@open-slot-ui` `UISpec` fields merged into the built spec (escape hatch). */
+  spec?: Record<string, unknown>;
+}
+/** The cost multiplier for a mode key (default 1 for `base` / unknown modes). */
+declare function modeCostOf(config: GameConfig, mode: string): number;
+//#endregion
+//#region src/engine/fsm.d.ts
+/** The minimal audio surface a game's phases call (satisfied by `@stakeplate/core/audio`). */
+interface AudioPort {
+  play(name: string, opts?: {
+    bus?: string;
+    volume?: number;
+  }): void;
+  music(name: string, opts?: {
+    fadeIn?: number;
+  }): void;
+  stopMusic(opts?: {
+    fade?: number;
+  }): void;
+}
+/** Handed to every phase. `round` is set by SpinPhase and read by Present/Settle. `E` is
+ *  the game's book-event type, so `interpretBook`/`round.raw` are typed. */
+interface PhaseContext<T = unknown, V = unknown, E = unknown> {
+  readonly config: GameConfig;
+  readonly stores: RootStore;
+  readonly network: NetworkManager;
+  readonly hud: HudPort;
+  readonly ticker: Ticker;
+  /** The game's mounted view (scene/presenter/stores) — whatever `mountView` returned. */
+  readonly view: V;
+  readonly audio: AudioPort | null;
+  /** Turbo speed + slam-stop (core-owned). Use `ctx.turbo.delay(ms)` for spin/anim timing. */
+  readonly turbo: TurboState;
+  readonly interpretBook: InterpretBook<T, E>;
+  readonly fsm: FSM<T, V, E>;
+  round: GameRound<T, E> | null;
+  /** Cost multiplier for a mode key (from `config.modes`, default 1). */
+  modeCost(mode: string): number;
+}
+interface Phase<T = unknown, V = unknown, E = unknown> {
+  readonly name: string;
+  enter(ctx: PhaseContext<T, V, E>): Promise<void> | void;
+  exit?(ctx: PhaseContext<T, V, E>): void;
+}
+declare class FSM<T = unknown, V = unknown, E = unknown> {
+  private ctx;
+  private readonly byName;
+  private _current;
+  /** Later phases with the same `name` win — so a game's Present overrides the default. */
+  constructor(phases: Phase<T, V, E>[]);
+  bind(ctx: PhaseContext<T, V, E>): void;
+  get current(): string;
+  has(name: string): boolean;
+  transition(name: string): Promise<void>;
+}
+//#endregion
+//#region src/audio/bind.d.ts
+/** The two volume groups the HUD's two sliders drive. */
+type MixerGroup = 'music' | 'effects';
+/**
+ * The minimal mixer surface the HUD binding needs. The HUD has exactly two sliders —
+ * **Music** and **Effects** — so the port is group-level, not per-bus. GameAudio satisfies
+ * it structurally.
+ */
+interface MixerLike {
+  /** Set a group's level (0..1) — applies to every bus in the group. */
+  setGroupLevel(group: MixerGroup, level: number): void;
+  /** Read a group's level (average across its buses). */
+  getGroupLevel(group: MixerGroup): number;
+  /** Mute/unmute everything (the Sound toggle). */
+  setMuted(muted: boolean): void;
+  /** Resume the AudioContext from a user gesture. Present on GameAudio. */
+  unlock?(): Promise<void> | void;
+}
+/**
+ * Bind the HUD sound controls to a mixer: the **Music slider → `music` group**, the
+ * **Effects slider → `effects` group** (both persisted to localStorage + restored), and the
+ * **Sound toggle → mute** everything. Returns a disposer.
+ */
+declare function bindMixerToHud(mixer: MixerLike, hud: BootedHud, opts?: {
+  storageKey?: string;
+}): () => void;
+//#endregion
+//#region src/audio/index.d.ts
+/** Buses in the MUSIC group (driven by the Music slider). */
+type MusicBus = 'music' | 'ambience';
+/** Buses in the EFFECTS group (driven by the Effects slider). */
+type SfxBus = 'reels' | 'symbols' | 'anticipation' | 'wins' | 'voiceover' | 'ui' | 'reverb';
+type BusName = MusicBus | SfxBus;
+interface GameAudioOptions {
+  /** Initial MUSIC-group level (music + ambience), 0..1. Default 0.8. */
+  music?: number;
+  /** Initial EFFECTS-group level (reels…reverb), 0..1. Default 1. */
+  effects?: number;
+  masterHeadroom?: number;
+  /** Duck the MUSIC group while THESE sfx buses are active (default `['wins']`; `null` = off). */
+  duckMusicFrom?: SfxBus | SfxBus[] | null;
+  duckAmount?: number;
+}
+/**
+ * A sound to load onto a bus, or a music track (intro/loop/outro → the `music` bus).
+ * For a PLAIN loop with no authored intro/outro, set `loopCrossfadeMs`: zvuk equal-power
+ * crossfades the loop boundary so a single file loops seamlessly (no click, no stinger/tail
+ * needed) — just the crossfade window in ms.
+ */
+type SoundEntry = {
+  name: string;
+  kind?: 'sound';
+  url: string | string[];
+  bus?: BusName;
+} | {
+  name: string;
+  kind: 'music';
+  loop: string | string[];
+  intro?: string | string[];
+  outro?: string | string[];
+  loopCrossfadeMs?: number;
+};
+/** The pre-wired game mixer. Satisfies {@link AudioPort} + {@link MixerLike}. */
+declare class GameAudio implements AudioPort, MixerLike {
+  readonly engine: Engine<BusName>;
+  private readonly musicGroup;
+  private readonly effectsGroup;
+  private readonly duckFrom;
+  private readonly duckAmount;
+  private unlocked;
+  private currentMusic;
+  constructor(opts?: GameAudioOptions);
+  /** Resume the AudioContext from a user gesture + arm ducking. Idempotent. */
+  unlock(): Promise<void>;
+  setGroupLevel(group: MixerGroup, level: number): void;
+  getGroupLevel(group: MixerGroup): number;
+  setMuted(muted: boolean): void;
+  /** A single bus (for per-sound routing, sends, FX inserts). */
+  bus(name: BusName): Bus;
+  /** A volume group handle (`'music'` or `'effects'`). */
+  group(name: MixerGroup): BusGroup;
+  /** Preload a manifest of sounds + music onto their buses. */
+  load(entries: SoundEntry[]): Promise<void>;
+  play(name: string, opts?: {
+    bus?: BusName;
+    volume?: number;
+  }): void;
+  music(name: string, opts?: {
+    fadeIn?: number;
+  }): void;
+  stopMusic(opts?: {
+    fade?: number;
+  }): void;
+}
+declare function createGameAudio(opts?: GameAudioOptions): GameAudio;
+/**
+ * Bind the HUD's sound controls to the audio groups (Music slider → music group, Effects →
+ * effects group, persisted; Sound toggle → mute). Returns a disposer. `createStakeGame` calls
+ * this for you (via {@link bindMixerToHud}) when you pass `audio`; use it directly only to opt
+ * out or wire a mixer the core didn't get.
+ */
+declare function bindAudioToHud(audio: GameAudio, hud: BootedHud, opts?: {
+  storageKey?: string;
+}): () => void;
+//#endregion
+export { DEFAULT_TURBO_SPEEDS as C, roundInfo as S, TurboState as T, ModeConfig as _, SfxBus as a, InterpretBook as b, createGameAudio as c, bindMixerToHud as d, AudioPort as f, GameConfig as g, PhaseContext as h, MusicBus as i, MixerGroup as l, Phase as m, GameAudio as n, SoundEntry as o, FSM as p, GameAudioOptions as r, bindAudioToHud as s, BusName as t, MixerLike as u, modeCostOf as v, TurboClock as w, RoundInfo as x, GameRound as y };
+//# sourceMappingURL=index-BcTRfis9.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { a as Balance, c as JurisdictionConfig, d as ReplayParams, f as RgsConfig, h as roundEvents, i as BOOK_AMOUNT_MULTIPLIER, l as PlayRequest, m as Round, n as AuthenticateRequest, o as EndRoundRequest, p as RgsError, r as AuthenticateResponse, s as EndRoundResponse, t as API_AMOUNT_MULTIPLIER, u as PlayResponse } from "./protocol-C1KamF3t.js";
+import { a as MockOptions, c as RuntimeConfig, i as MockNetworkManager, l as readRuntime, n as PlayArgs, o as ScriptedRound, r as createNetwork, s as ReplayLaunch, t as NetworkManager, u as urlParam } from "./network-pBW8CX1o.js";
+import { i as UiStore, n as RootStore, r as SessionStore, t as BalanceStore } from "./index-BBlN97RY.js";
+import { a as Ticker, i as RealTicker, n as ReplayInfo, r as InstantTicker, t as HudPort } from "./hud-port-DNfotn4U.js";
+import { C as DEFAULT_TURBO_SPEEDS, S as roundInfo, T as TurboState, _ as ModeConfig, b as InterpretBook, f as AudioPort, g as GameConfig, h as PhaseContext, m as Phase, o as SoundEntry, p as FSM, r as GameAudioOptions, v as modeCostOf, w as TurboClock, x as RoundInfo, y as GameRound } from "./index-BcTRfis9.js";
+import { StakeNetworkManager, StakeNetworkOptions } from "./rgs.js";
+import { BootedHud } from "@open-slot-ui/pixi";
+//#region src/engine/phases.d.ts
+/** Wait for the next spin (the HUD's `spinRequested` drives the transition to Spin). */
+declare class IdlePhase<T = unknown, V = unknown, E = unknown> implements Phase<T, V, E> {
+  readonly name = "idle";
+  enter(ctx: PhaseContext<T, V, E>): void;
+}
+/** Pick the mode, take the stake, ask the RGS, parse the round, hand off to Present. */
+declare class SpinPhase<T = unknown, V = unknown, E = unknown> implements Phase<T, V, E> {
+  readonly name = "spin";
+  enter(ctx: PhaseContext<T, V, E>): Promise<void>;
+}
+/** DEFAULT Present — nothing to animate. The game overrides `present` to play its scene. */
+declare class PresentPhase<T = unknown, V = unknown, E = unknown> implements Phase<T, V, E> {
+  readonly name = "present";
+  enter(ctx: PhaseContext<T, V, E>): Promise<void>;
+}
+/** Apply the authoritative balance + win, settle the round for the HUD, then Idle. */
+declare class SettlePhase<T = unknown, V = unknown, E = unknown> implements Phase<T, V, E> {
+  readonly name = "settle";
+  private roundStartedAt;
+  enter(ctx: PhaseContext<T, V, E>): Promise<void>;
+  /** Called by SpinPhase-adjacent boot wiring to timestamp the round start. */
+  markStart(now: number): void;
+}
+/** The default phase set (game phases are appended after → same-name overrides win). */
+declare function defaultPhases<T = unknown, V = unknown, E = unknown>(): Phase<T, V, E>[];
+//#endregion
+//#region src/game/createStakeGame.d.ts
+/**
+ * Declarative audio: hand the core your sounds and it lazily creates the `@schmooky/zvuk`
+ * mixer (master → music/sfx/ambience buses + ducking), preloads them, and auto-binds it to
+ * the HUD (sliders/mute + unlock). zvuk loads in its OWN async chunk — a game without sound
+ * pays nothing. (Advanced: pass a ready `GameAudio` instance instead, for custom buses/FX.)
+ */
+interface AudioSpec extends GameAudioOptions {
+  sounds: SoundEntry[];
+}
+/** Passed to `mountView` — everything the game's scene needs (not the round/fsm yet). */
+interface ViewContext {
+  config: GameConfig;
+  stores: RootStore;
+  hud: BootedHud;
+  ticker: Ticker;
+  audio: AudioPort | null;
+  /** Turbo speed + slam-stop (core-owned) — the scene may branch on `turbo.level`/`speed`. */
+  turbo: TurboState;
+}
+interface CreateStakeGameOptions<T = unknown, V = unknown, E = unknown> {
+  config: GameConfig;
+  /** The game's ONE money seam: typed RGS round (`Round<E>`) → your model. Pure. */
+  interpretBook: InterpretBook<T, E>;
+  /** Mount the game's pixi scene/presenter/stores; returns the view handed to phases. */
+  mountView: (host: HTMLElement, ctx: ViewContext) => V;
+  /** The game's Present phase (+ any overrides); Idle/Spin/Settle are provided. */
+  phases?: Phase<T, V, E>[];
+  /** Sounds (declarative — the core builds + wires the mixer) OR a ready `GameAudio`/AudioPort. */
+  audio?: AudioPort | AudioSpec | null;
+  /** Override the transport (tests / a supplied mock). */
+  network?: NetworkManager;
+  /** Override launch params (tests / embedding). */
+  runtime?: Partial<RuntimeConfig>;
+  /** Host for the pixi HUD canvas (default document.body). */
+  hudHost?: HTMLElement;
+  /** Host for the game scene (default = hudHost). */
+  sceneHost?: HTMLElement;
+  /** Passthrough to `mountHud` (spinSkin, icons, gsap, menu:false, hooks, …). */
+  hudOptions?: Record<string, unknown>;
+}
+/** A read-only snapshot of the running game — for the dev harness, tests and debugging. */
+interface GameSnapshot {
+  phase: string;
+  balance: number;
+  bet: number;
+  lastWin: number;
+  currency: string;
+  spinning: boolean;
+}
+interface StakeGame {
+  start(): Promise<void>;
+  dispose(): void;
+  /** Current phase + store values. The declarative harness asserts on this (no screenshots). */
+  inspect(): GameSnapshot;
+  /** Trigger a spin the same way the HUD spin button does — only from Idle. For harness/tests. */
+  requestSpin(): boolean;
+}
+declare function createStakeGame<T = unknown, V = unknown, E = unknown>(opts: CreateStakeGameOptions<T, V, E>): StakeGame;
+//#endregion
+export { API_AMOUNT_MULTIPLIER, AudioPort, AudioSpec, AuthenticateRequest, AuthenticateResponse, BOOK_AMOUNT_MULTIPLIER, Balance, BalanceStore, CreateStakeGameOptions, DEFAULT_TURBO_SPEEDS, EndRoundRequest, EndRoundResponse, FSM, GameConfig, GameRound, GameSnapshot, HudPort, IdlePhase, InstantTicker, InterpretBook, JurisdictionConfig, MockNetworkManager, MockOptions, ModeConfig, NetworkManager, Phase, PhaseContext, PlayArgs, PlayRequest, PlayResponse, PresentPhase, RealTicker, ReplayInfo, ReplayLaunch, ReplayParams, RgsConfig, RgsError, RootStore, Round, RoundInfo, RuntimeConfig, ScriptedRound, SessionStore, SettlePhase, SpinPhase, StakeGame, StakeNetworkManager, StakeNetworkOptions, Ticker, TurboClock, TurboState, UiStore, ViewContext, createNetwork, createStakeGame, defaultPhases, modeCostOf, readRuntime, roundEvents, roundInfo, urlParam };
+//# sourceMappingURL=index.d.ts.map