@stakeplate/core 0.1.0 → 0.2.0

package/README.md

@@ -61,7 +61,18 @@ config.socialMessages = { en: built.socialEn }; // auto-derived social wording
 - `@stakeplate/core/rgs` — wire protocol, launch-param runtime, `NetworkManager` +
   Stake/mock adapters, `createNetwork`.
 - `@stakeplate/core/audio` — zvuk bus graph (music/effects groups) + HUD slider/mute binding.
+  Loaded one-shots are RMS-normalized by default (consistent levels, no per-file gains) and
+  each effects bus is voice-capped so stacked cues don't machine-gun. `play(name, { volume,
+  pitch })` takes jitter (`{ base, jitter }`) so repeated cues vary. `bindInputSounds(audio,
+  hud, map)` (or an `AudioSpec.inputSounds` map) plays a cue on spin/bet/autoplay/turbo/skip.
+  Encode raw clips to shippable web assets (webm/opus + mp3 codec ladder, all metadata
+  stripped) with `scripts/encode-audio.sh OUTDIR raw/*.wav`, then load the pair with
+  `{ url: ['clip.webm', 'clip.mp3'] }`.
 - `@stakeplate/core/rules` — `buildRules` compliant menu + `toSocial`/`findRestricted` + dict.
+- Boot loader — pass `loader: { title, backgroundImage, logo, accent, … }` to `createStakeGame`
+  for a configurable loading screen (pulsing logo/spinner + progress bar over your backdrop)
+  that shows before anything heavy loads and pops away when ready. `manual: true` +
+  `ctx.loader.done()` to hold it until your scene's art is in. `createLoader()` is also standalone.
 - `@stakeplate/core/stores` — the MobX stores (balance, ui) for composing game state.
 - `@stakeplate/core/testing` — the mock RGS, scriptable network, instant ticker.
 - (soon) `/scene`, `/i18n`.

package/dist/audio.d.ts

@@ -1,2 +1,2 @@
-import { a as SfxBus, c as createGameAudio, d as bindMixerToHud, i as MusicBus, l as MixerGroup, n as GameAudio, o as SoundEntry, r as GameAudioOptions, s as bindAudioToHud, t as BusName, u as MixerLike } from "./index-BcTRfis9.js";
-export { BusName, GameAudio, GameAudioOptions, type MixerGroup, type MixerLike, MusicBus, SfxBus, SoundEntry, bindAudioToHud, bindMixerToHud, createGameAudio };
+import { a as SfxBus, c as createGameAudio, d as bindInputSounds, f as MixerGroup, i as MusicBus, l as InputSoundMap, m as bindMixerToHud, n as GameAudio, o as SoundEntry, p as MixerLike, r as GameAudioOptions, s as bindAudioToHud, t as BusName, u as InputSoundOptions } from "./index-DsA8mDpk.js";
+export { BusName, GameAudio, GameAudioOptions, type InputSoundMap, type InputSoundOptions, type MixerGroup, type MixerLike, MusicBus, SfxBus, SoundEntry, bindAudioToHud, bindInputSounds, bindMixerToHud, createGameAudio };

package/dist/audio.js

@@ -1,4 +1,4 @@
-import { t as bindMixerToHud } from "./bind-BBRxizWR.js";
+import { n as bindMixerToHud, t as bindInputSounds } from "./inputs-X3Tc_HTV.js";
 import { Ducker, createEngine } from "@schmooky/zvuk";
 //#region src/audio/index.ts
 const MUSIC_BUSES = ["music", "ambience"];
@@ -18,14 +18,23 @@ var GameAudio = class {
 	effectsGroup;
 	duckFrom;
 	duckAmount;
+	normalizeDefault;
 	unlocked = false;
 	currentMusic = null;
 	constructor(opts = {}) {
 		const musicLevel = opts.music ?? .8;
 		const fxLevel = opts.effects ?? 1;
+		const conc = opts.sfxConcurrency === void 0 ? {
+			max: 8,
+			steal: "oldest"
+		} : opts.sfxConcurrency;
+		this.normalizeDefault = opts.normalize ?? true;
 		const buses = {};
 		for (const b of MUSIC_BUSES) buses[b] = { level: musicLevel };
-		for (const b of SFX_BUSES) buses[b] = { level: fxLevel };
+		for (const b of SFX_BUSES) buses[b] = {
+			level: fxLevel,
+			...conc ? { concurrency: conc } : {}
+		};
 		this.engine = createEngine({
 			buses,
 			master: {
@@ -77,12 +86,18 @@ var GameAudio = class {
 			loop: e.loop,
 			...e.intro ? { intro: e.intro } : {},
 			...e.outro ? { outro: e.outro } : {}
-		}, e.loopCrossfadeMs != null ? { loopCrossfade: e.loopCrossfadeMs / 1e3 } : void 0) : this.engine.loadSound(e.name, e.url, { bus: e.bus ?? "ui" })));
+		}, e.loopCrossfadeMs != null ? { loopCrossfade: e.loopCrossfadeMs / 1e3 } : void 0) : this.engine.loadSound(e.name, e.url, {
+			bus: e.bus ?? "ui",
+			normalize: e.normalize ?? this.normalizeDefault
+		})));
 	}
+	/** Fire a one-shot. `volume`/`pitch` accept a `VoiceJitter` (`{ base, jitter }`) so
+	*  repeated cues — contacts, ticks — vary per voice instead of sounding cloned. */
 	play(name, opts) {
 		this.engine.sound(name).play({
 			...opts?.bus ? { bus: opts.bus } : {},
-			...opts?.volume != null ? { volume: opts.volume } : {}
+			...opts?.volume != null ? { volume: opts.volume } : {},
+			...opts?.pitch != null ? { pitch: opts.pitch } : {}
 		});
 	}
 	music(name, opts) {
@@ -107,6 +122,6 @@ function bindAudioToHud(audio, hud, opts = {}) {
 	return bindMixerToHud(audio, hud, opts);
 }
 //#endregion
-export { GameAudio, bindAudioToHud, bindMixerToHud, createGameAudio };
+export { GameAudio, bindAudioToHud, bindInputSounds, bindMixerToHud, createGameAudio };
 
 //# sourceMappingURL=audio.js.map

package/dist/audio.js.map

@@ -1 +1 @@
-{"version":3,"file":"audio.js","names":[],"sources":["../src/audio/index.ts"],"sourcesContent":["// @stakeplate/core/audio — a thin PRE-WIRING over @schmooky/zvuk. The core stands up the\n// standard slot bus graph (nine buses in TWO groups) + master, binds the two groups to the\n// HUD's Music/Effects sliders (persisted) and mutes on the Sound toggle, and ducks music\n// while chosen sfx play. The game just declares sounds and calls `audio.play('win','wins')`.\n//\n//   master\n//   ├── MUSIC group  (Music slider) → music · ambience\n//   └── EFFECTS group (Effects slider) → reels · symbols · anticipation · wins ·\n//                                        voiceover · ui · reverb\n//\n// Groups are zvuk BusGroups (a logical handle: a slider sets every member's level). Keep the\n// per-sound mix in the sound volumes; the sliders scale the whole group.\n\nimport { createEngine, Ducker, type Engine, type Bus, type BusConfig, type BusGroup } from '@schmooky/zvuk';\nimport type { BootedHud } from '@open-slot-ui/pixi';\nimport type { AudioPort } from '../engine/fsm';\nimport { bindMixerToHud, type MixerLike, type MixerGroup } from './bind';\n\nexport { bindMixerToHud, type MixerLike, type MixerGroup } from './bind';\n\n/** Buses in the MUSIC group (driven by the Music slider). */\nexport type MusicBus = 'music' | 'ambience';\n/** Buses in the EFFECTS group (driven by the Effects slider). */\nexport type SfxBus = 'reels' | 'symbols' | 'anticipation' | 'wins' | 'voiceover' | 'ui' | 'reverb';\nexport type BusName = MusicBus | SfxBus;\n\nconst MUSIC_BUSES: MusicBus[] = ['music', 'ambience'];\nconst SFX_BUSES: SfxBus[] = ['reels', 'symbols', 'anticipation', 'wins', 'voiceover', 'ui', 'reverb'];\n\nexport interface GameAudioOptions {\n  /** Initial MUSIC-group level (music + ambience), 0..1. Default 0.8. */\n  music?: number;\n  /** Initial EFFECTS-group level (reels…reverb), 0..1. Default 1. */\n  effects?: number;\n  masterHeadroom?: number;\n  /** Duck the MUSIC group while THESE sfx buses are active (default `['wins']`; `null` = off). */\n  duckMusicFrom?: SfxBus | SfxBus[] | null;\n  duckAmount?: number;\n}\n\n/**\n * A sound to load onto a bus, or a music track (intro/loop/outro → the `music` bus).\n * For a PLAIN loop with no authored intro/outro, set `loopCrossfadeMs`: zvuk equal-power\n * crossfades the loop boundary so a single file loops seamlessly (no click, no stinger/tail\n * needed) — just the crossfade window in ms.\n */\nexport type SoundEntry =\n  | { name: string; kind?: 'sound'; url: string | string[]; bus?: BusName }\n  | { name: string; kind: 'music'; loop: string | string[]; intro?: string | string[]; outro?: string | string[]; loopCrossfadeMs?: number };\n\n/** The pre-wired game mixer. Satisfies {@link AudioPort} + {@link MixerLike}. */\nexport class GameAudio implements AudioPort, MixerLike {\n  readonly engine: Engine<BusName>;\n  private readonly musicGroup: BusGroup;\n  private readonly effectsGroup: BusGroup;\n  private readonly duckFrom: SfxBus[];\n  private readonly duckAmount: number;\n  private unlocked = false;\n  private currentMusic: { stop(opts?: { fade?: number }): void } | null = null;\n\n  constructor(opts: GameAudioOptions = {}) {\n    const musicLevel = opts.music ?? 0.8;\n    const fxLevel = opts.effects ?? 1;\n    const buses = {} as Record<BusName, BusConfig>;\n    for (const b of MUSIC_BUSES) buses[b] = { level: musicLevel };\n    for (const b of SFX_BUSES) buses[b] = { level: fxLevel };\n    this.engine = createEngine<BusName>({\n      buses,\n      master: { headroom: opts.masterHeadroom ?? -3, limiter: { threshold: -1 } },\n    });\n    this.musicGroup = this.engine.busGroup('music', MUSIC_BUSES.map((b) => this.engine.bus(b)));\n    this.effectsGroup = this.engine.busGroup('effects', SFX_BUSES.map((b) => this.engine.bus(b)));\n    const df = opts.duckMusicFrom === undefined ? (['wins'] as SfxBus[]) : opts.duckMusicFrom;\n    this.duckFrom = df == null ? [] : Array.isArray(df) ? df : [df];\n    this.duckAmount = opts.duckAmount ?? 0.5;\n  }\n\n  /** Resume the AudioContext from a user gesture + arm ducking. Idempotent. */\n  async unlock(): Promise<void> {\n    if (this.unlocked) return;\n    await this.engine.unlock();\n    this.unlocked = true;\n    // Duck music + ambience while each chosen sfx bus is active.\n    for (const src of this.duckFrom) {\n      for (const target of MUSIC_BUSES) {\n        const ducker = new Ducker(this.engine.context, this.engine.bus(src), { amount: this.duckAmount, attack: 0.05, release: 0.3 });\n        this.engine.bus(target).addFx(ducker);\n      }\n    }\n  }\n\n  // ── MixerLike (the HUD sliders + mute drive these) ────────────────────────────\n  setGroupLevel(group: MixerGroup, level: number): void {\n    (group === 'music' ? this.musicGroup : this.effectsGroup).level = level;\n  }\n  getGroupLevel(group: MixerGroup): number {\n    return (group === 'music' ? this.musicGroup : this.effectsGroup).level;\n  }\n  setMuted(muted: boolean): void {\n    this.musicGroup.muted = muted;\n    this.effectsGroup.muted = muted;\n  }\n\n  /** A single bus (for per-sound routing, sends, FX inserts). */\n  bus(name: BusName): Bus {\n    return this.engine.bus(name);\n  }\n  /** A volume group handle (`'music'` or `'effects'`). */\n  group(name: MixerGroup): BusGroup {\n    return name === 'music' ? this.musicGroup : this.effectsGroup;\n  }\n\n  /** Preload a manifest of sounds + music onto their buses. */\n  async load(entries: SoundEntry[]): Promise<void> {\n    await Promise.all(\n      entries.map((e) =>\n        'kind' in e && e.kind === 'music'\n          ? this.engine.loadMusic(\n              e.name,\n              { loop: e.loop, ...(e.intro ? { intro: e.intro } : {}), ...(e.outro ? { outro: e.outro } : {}) },\n              e.loopCrossfadeMs != null ? { loopCrossfade: e.loopCrossfadeMs / 1000 } : undefined,\n            )\n          : this.engine.loadSound(e.name, e.url, { bus: e.bus ?? 'ui' }),\n      ),\n    );\n  }\n\n  play(name: string, opts?: { bus?: BusName; volume?: number }): void {\n    this.engine.sound(name).play({ ...(opts?.bus ? { bus: opts.bus } : {}), ...(opts?.volume != null ? { volume: opts.volume } : {}) });\n  }\n\n  music(name: string, opts?: { fadeIn?: number }): void {\n    this.currentMusic?.stop({ fade: 0.3 });\n    this.currentMusic = this.engine.music(name).play({ fadeIn: opts?.fadeIn ?? 0.4 });\n  }\n\n  stopMusic(opts?: { fade?: number }): void {\n    this.currentMusic?.stop({ fade: opts?.fade ?? 0.3 });\n    this.currentMusic = null;\n  }\n}\n\nexport function createGameAudio(opts?: GameAudioOptions): GameAudio {\n  return new GameAudio(opts);\n}\n\n/**\n * Bind the HUD's sound controls to the audio groups (Music slider → music group, Effects →\n * effects group, persisted; Sound toggle → mute). Returns a disposer. `createStakeGame` calls\n * this for you (via {@link bindMixerToHud}) when you pass `audio`; use it directly only to opt\n * out or wire a mixer the core didn't get.\n */\nexport function bindAudioToHud(audio: GameAudio, hud: BootedHud, opts: { storageKey?: string } = {}): () => void {\n  return bindMixerToHud(audio, hud, opts);\n}\n"],"mappings":"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"}
+{"version":3,"file":"audio.js","names":[],"sources":["../src/audio/index.ts"],"sourcesContent":["// @stakeplate/core/audio — a thin PRE-WIRING over @schmooky/zvuk. The core stands up the\n// standard slot bus graph (nine buses in TWO groups) + master, binds the two groups to the\n// HUD's Music/Effects sliders (persisted) and mutes on the Sound toggle, and ducks music\n// while chosen sfx play. The game just declares sounds and calls `audio.play('win','wins')`.\n//\n//   master\n//   ├── MUSIC group  (Music slider) → music · ambience\n//   └── EFFECTS group (Effects slider) → reels · symbols · anticipation · wins ·\n//                                        voiceover · ui · reverb\n//\n// Groups are zvuk BusGroups (a logical handle: a slider sets every member's level). Keep the\n// per-sound mix in the sound volumes; the sliders scale the whole group.\n\nimport { createEngine, Ducker, type Engine, type Bus, type BusConfig, type BusGroup, type VoiceJitter, type ConcurrencyConfig, type LoudnessOptions } from '@schmooky/zvuk';\nimport type { BootedHud } from '@open-slot-ui/pixi';\nimport type { AudioPort } from '../engine/fsm';\nimport { bindMixerToHud, type MixerLike, type MixerGroup } from './bind';\n\nexport { bindMixerToHud, type MixerLike, type MixerGroup } from './bind';\nexport { bindInputSounds, type InputSoundMap, type InputSoundOptions } from './inputs';\n\n/** Buses in the MUSIC group (driven by the Music slider). */\nexport type MusicBus = 'music' | 'ambience';\n/** Buses in the EFFECTS group (driven by the Effects slider). */\nexport type SfxBus = 'reels' | 'symbols' | 'anticipation' | 'wins' | 'voiceover' | 'ui' | 'reverb';\nexport type BusName = MusicBus | SfxBus;\n\nconst MUSIC_BUSES: MusicBus[] = ['music', 'ambience'];\nconst SFX_BUSES: SfxBus[] = ['reels', 'symbols', 'anticipation', 'wins', 'voiceover', 'ui', 'reverb'];\n\nexport interface GameAudioOptions {\n  /** Initial MUSIC-group level (music + ambience), 0..1. Default 0.8. */\n  music?: number;\n  /** Initial EFFECTS-group level (reels…reverb), 0..1. Default 1. */\n  effects?: number;\n  masterHeadroom?: number;\n  /** Duck the MUSIC group while THESE sfx buses are active (default `['wins']`; `null` = off). */\n  duckMusicFrom?: SfxBus | SfxBus[] | null;\n  duckAmount?: number;\n  /**\n   * RMS loudness normalization applied to every loaded one-shot so the whole manifest sits\n   * at a consistent level (no hand-tuned per-file gains). A per-entry `normalize` overrides\n   * this. Default `true`. Pass a `LoudnessOptions` object to tune the target, or `false` off.\n   */\n  normalize?: boolean | LoudnessOptions;\n  /**\n   * Voice cap applied to EACH effects bus so stacked one-shots (a multi-pay cascade, rapid\n   * contacts) don't machine-gun — steals the oldest voice when the cap is hit. Default\n   * `{ max: 8, steal: 'oldest' }`. Pass `null` to leave the effects buses uncapped.\n   */\n  sfxConcurrency?: ConcurrencyConfig | null;\n}\n\n/**\n * A sound to load onto a bus, or a music track (intro/loop/outro → the `music` bus).\n * For a PLAIN loop with no authored intro/outro, set `loopCrossfadeMs`: zvuk equal-power\n * crossfades the loop boundary so a single file loops seamlessly (no click, no stinger/tail\n * needed) — just the crossfade window in ms.\n */\nexport type SoundEntry =\n  | { name: string; kind?: 'sound'; url: string | string[]; bus?: BusName; normalize?: boolean | LoudnessOptions }\n  | { name: string; kind: 'music'; loop: string | string[]; intro?: string | string[]; outro?: string | string[]; loopCrossfadeMs?: number };\n\n/** The pre-wired game mixer. Satisfies {@link AudioPort} + {@link MixerLike}. */\nexport class GameAudio implements AudioPort, MixerLike {\n  readonly engine: Engine<BusName>;\n  private readonly musicGroup: BusGroup;\n  private readonly effectsGroup: BusGroup;\n  private readonly duckFrom: SfxBus[];\n  private readonly duckAmount: number;\n  private readonly normalizeDefault: boolean | LoudnessOptions;\n  private unlocked = false;\n  private currentMusic: { stop(opts?: { fade?: number }): void } | null = null;\n\n  constructor(opts: GameAudioOptions = {}) {\n    const musicLevel = opts.music ?? 0.8;\n    const fxLevel = opts.effects ?? 1;\n    // Cap each effects bus so stacked one-shots don't machine-gun (opt out with `null`).\n    const conc = opts.sfxConcurrency === undefined ? ({ max: 8, steal: 'oldest' } as ConcurrencyConfig) : opts.sfxConcurrency;\n    this.normalizeDefault = opts.normalize ?? true;\n    const buses = {} as Record<BusName, BusConfig>;\n    for (const b of MUSIC_BUSES) buses[b] = { level: musicLevel };\n    for (const b of SFX_BUSES) buses[b] = { level: fxLevel, ...(conc ? { concurrency: conc } : {}) };\n    this.engine = createEngine<BusName>({\n      buses,\n      master: { headroom: opts.masterHeadroom ?? -3, limiter: { threshold: -1 } },\n    });\n    this.musicGroup = this.engine.busGroup('music', MUSIC_BUSES.map((b) => this.engine.bus(b)));\n    this.effectsGroup = this.engine.busGroup('effects', SFX_BUSES.map((b) => this.engine.bus(b)));\n    const df = opts.duckMusicFrom === undefined ? (['wins'] as SfxBus[]) : opts.duckMusicFrom;\n    this.duckFrom = df == null ? [] : Array.isArray(df) ? df : [df];\n    this.duckAmount = opts.duckAmount ?? 0.5;\n  }\n\n  /** Resume the AudioContext from a user gesture + arm ducking. Idempotent. */\n  async unlock(): Promise<void> {\n    if (this.unlocked) return;\n    await this.engine.unlock();\n    this.unlocked = true;\n    // Duck music + ambience while each chosen sfx bus is active.\n    for (const src of this.duckFrom) {\n      for (const target of MUSIC_BUSES) {\n        const ducker = new Ducker(this.engine.context, this.engine.bus(src), { amount: this.duckAmount, attack: 0.05, release: 0.3 });\n        this.engine.bus(target).addFx(ducker);\n      }\n    }\n  }\n\n  // ── MixerLike (the HUD sliders + mute drive these) ────────────────────────────\n  setGroupLevel(group: MixerGroup, level: number): void {\n    (group === 'music' ? this.musicGroup : this.effectsGroup).level = level;\n  }\n  getGroupLevel(group: MixerGroup): number {\n    return (group === 'music' ? this.musicGroup : this.effectsGroup).level;\n  }\n  setMuted(muted: boolean): void {\n    this.musicGroup.muted = muted;\n    this.effectsGroup.muted = muted;\n  }\n\n  /** A single bus (for per-sound routing, sends, FX inserts). */\n  bus(name: BusName): Bus {\n    return this.engine.bus(name);\n  }\n  /** A volume group handle (`'music'` or `'effects'`). */\n  group(name: MixerGroup): BusGroup {\n    return name === 'music' ? this.musicGroup : this.effectsGroup;\n  }\n\n  /** Preload a manifest of sounds + music onto their buses. */\n  async load(entries: SoundEntry[]): Promise<void> {\n    await Promise.all(\n      entries.map((e) =>\n        'kind' in e && e.kind === 'music'\n          ? this.engine.loadMusic(\n              e.name,\n              { loop: e.loop, ...(e.intro ? { intro: e.intro } : {}), ...(e.outro ? { outro: e.outro } : {}) },\n              e.loopCrossfadeMs != null ? { loopCrossfade: e.loopCrossfadeMs / 1000 } : undefined,\n            )\n          : this.engine.loadSound(e.name, e.url, { bus: e.bus ?? 'ui', normalize: e.normalize ?? this.normalizeDefault }),\n      ),\n    );\n  }\n\n  /** Fire a one-shot. `volume`/`pitch` accept a `VoiceJitter` (`{ base, jitter }`) so\n   *  repeated cues — contacts, ticks — vary per voice instead of sounding cloned. */\n  play(name: string, opts?: { bus?: BusName; volume?: number | VoiceJitter; pitch?: number | VoiceJitter }): void {\n    this.engine.sound(name).play({\n      ...(opts?.bus ? { bus: opts.bus } : {}),\n      ...(opts?.volume != null ? { volume: opts.volume } : {}),\n      ...(opts?.pitch != null ? { pitch: opts.pitch } : {}),\n    });\n  }\n\n  music(name: string, opts?: { fadeIn?: number }): void {\n    this.currentMusic?.stop({ fade: 0.3 });\n    this.currentMusic = this.engine.music(name).play({ fadeIn: opts?.fadeIn ?? 0.4 });\n  }\n\n  stopMusic(opts?: { fade?: number }): void {\n    this.currentMusic?.stop({ fade: opts?.fade ?? 0.3 });\n    this.currentMusic = null;\n  }\n}\n\nexport function createGameAudio(opts?: GameAudioOptions): GameAudio {\n  return new GameAudio(opts);\n}\n\n/**\n * Bind the HUD's sound controls to the audio groups (Music slider → music group, Effects →\n * effects group, persisted; Sound toggle → mute). Returns a disposer. `createStakeGame` calls\n * this for you (via {@link bindMixerToHud}) when you pass `audio`; use it directly only to opt\n * out or wire a mixer the core didn't get.\n */\nexport function bindAudioToHud(audio: GameAudio, hud: BootedHud, opts: { storageKey?: string } = {}): () => void {\n  return bindMixerToHud(audio, hud, opts);\n}\n"],"mappings":";;;AA2BA,MAAM,cAA0B,CAAC,SAAS,UAAU;AACpD,MAAM,YAAsB;CAAC;CAAS;CAAW;CAAgB;CAAQ;CAAa;CAAM;AAAQ;;AAoCpG,IAAa,YAAb,MAAuD;CACrD;CACA;CACA;CACA;CACA;CACA;CACA,WAAmB;CACnB,eAAwE;CAExE,YAAY,OAAyB,CAAC,GAAG;EACvC,MAAM,aAAa,KAAK,SAAS;EACjC,MAAM,UAAU,KAAK,WAAW;EAEhC,MAAM,OAAO,KAAK,mBAAmB,KAAA,IAAa;GAAE,KAAK;GAAG,OAAO;EAAS,IAA0B,KAAK;EAC3G,KAAK,mBAAmB,KAAK,aAAa;EAC1C,MAAM,QAAQ,CAAC;EACf,KAAK,MAAM,KAAK,aAAa,MAAM,KAAK,EAAE,OAAO,WAAW;EAC5D,KAAK,MAAM,KAAK,WAAW,MAAM,KAAK;GAAE,OAAO;GAAS,GAAI,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;EAAG;EAC/F,KAAK,SAAS,aAAsB;GAClC;GACA,QAAQ;IAAE,UAAU,KAAK,kBAAkB;IAAI,SAAS,EAAE,WAAW,GAAG;GAAE;EAC5E,CAAC;EACD,KAAK,aAAa,KAAK,OAAO,SAAS,SAAS,YAAY,KAAK,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC;EAC1F,KAAK,eAAe,KAAK,OAAO,SAAS,WAAW,UAAU,KAAK,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC;EAC5F,MAAM,KAAK,KAAK,kBAAkB,KAAA,IAAa,CAAC,MAAM,IAAiB,KAAK;EAC5E,KAAK,WAAW,MAAM,OAAO,CAAC,IAAI,MAAM,QAAQ,EAAE,IAAI,KAAK,CAAC,EAAE;EAC9D,KAAK,aAAa,KAAK,cAAc;CACvC;;CAGA,MAAM,SAAwB;EAC5B,IAAI,KAAK,UAAU;EACnB,MAAM,KAAK,OAAO,OAAO;EACzB,KAAK,WAAW;EAEhB,KAAK,MAAM,OAAO,KAAK,UACrB,KAAK,MAAM,UAAU,aAAa;GAChC,MAAM,SAAS,IAAI,OAAO,KAAK,OAAO,SAAS,KAAK,OAAO,IAAI,GAAG,GAAG;IAAE,QAAQ,KAAK;IAAY,QAAQ;IAAM,SAAS;GAAI,CAAC;GAC5H,KAAK,OAAO,IAAI,MAAM,CAAC,CAAC,MAAM,MAAM;EACtC;CAEJ;CAGA,cAAc,OAAmB,OAAqB;EACpD,CAAC,UAAU,UAAU,KAAK,aAAa,KAAK,aAAA,CAAc,QAAQ;CACpE;CACA,cAAc,OAA2B;EACvC,QAAQ,UAAU,UAAU,KAAK,aAAa,KAAK,aAAA,CAAc;CACnE;CACA,SAAS,OAAsB;EAC7B,KAAK,WAAW,QAAQ;EACxB,KAAK,aAAa,QAAQ;CAC5B;;CAGA,IAAI,MAAoB;EACtB,OAAO,KAAK,OAAO,IAAI,IAAI;CAC7B;;CAEA,MAAM,MAA4B;EAChC,OAAO,SAAS,UAAU,KAAK,aAAa,KAAK;CACnD;;CAGA,MAAM,KAAK,SAAsC;EAC/C,MAAM,QAAQ,IACZ,QAAQ,KAAK,MACX,UAAU,KAAK,EAAE,SAAS,UACtB,KAAK,OAAO,UACV,EAAE,MACF;GAAE,MAAM,EAAE;GAAM,GAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;GAAI,GAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;EAAG,GAC/F,EAAE,mBAAmB,OAAO,EAAE,eAAe,EAAE,kBAAkB,IAAK,IAAI,KAAA,CAC5E,IACA,KAAK,OAAO,UAAU,EAAE,MAAM,EAAE,KAAK;GAAE,KAAK,EAAE,OAAO;GAAM,WAAW,EAAE,aAAa,KAAK;EAAiB,CAAC,CAClH,CACF;CACF;;;CAIA,KAAK,MAAc,MAA6F;EAC9G,KAAK,OAAO,MAAM,IAAI,CAAC,CAAC,KAAK;GAC3B,GAAI,MAAM,MAAM,EAAE,KAAK,KAAK,IAAI,IAAI,CAAC;GACrC,GAAI,MAAM,UAAU,OAAO,EAAE,QAAQ,KAAK,OAAO,IAAI,CAAC;GACtD,GAAI,MAAM,SAAS,OAAO,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;EACrD,CAAC;CACH;CAEA,MAAM,MAAc,MAAkC;EACpD,KAAK,cAAc,KAAK,EAAE,MAAM,GAAI,CAAC;EACrC,KAAK,eAAe,KAAK,OAAO,MAAM,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,MAAM,UAAU,GAAI,CAAC;CAClF;CAEA,UAAU,MAAgC;EACxC,KAAK,cAAc,KAAK,EAAE,MAAM,MAAM,QAAQ,GAAI,CAAC;EACnD,KAAK,eAAe;CACtB;AACF;AAEA,SAAgB,gBAAgB,MAAoC;CAClE,OAAO,IAAI,UAAU,IAAI;AAC3B;;;;;;;AAQA,SAAgB,eAAe,OAAkB,KAAgB,OAAgC,CAAC,GAAe;CAC/G,OAAO,eAAe,OAAO,KAAK,IAAI;AACxC"}

package/dist/{index-BcTRfis9.d.ts → index-DsA8mDpk.d.ts}

@@ -3,31 +3,42 @@ 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";
+import { Bus, BusGroup, ConcurrencyConfig, Engine, LoudnessOptions, VoiceJitter } 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). */
+  /** The EFFECTIVE delay multiplier right now — the turbo level, floored by the autoplay
+   *  speed while autoplay is running (`ctx.turbo.delay` already applies it). */
   readonly speed: number;
+  /** True while autoplay/hold is running — game animations are shortened even at turbo off. */
+  readonly autoplay: boolean;
   /** 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. */
+  /** A turbo- + autoplay- + slam-stop-aware delay for GAME animations. NOT for compliance waits. */
   delay(ms: number): Promise<void>;
 }
 declare class TurboClock implements TurboState {
   private readonly speeds;
+  /** Delay multiplier applied while autoplay/hold runs (the floor for `speed`). Defaults to
+   *  the turbo (level-1) speed, so autoplay plays at least at turbo pace even at turbo off. */
+  private readonly autoplaySpeed;
   private _level;
+  private _autoplay;
   private _skipped;
   private readonly pending;
-  constructor(speeds?: number[]);
+  constructor(speeds?: number[], autoplaySpeed?: number);
   get level(): number;
   get speed(): number;
+  get autoplay(): boolean;
   get skipped(): boolean;
   /** Set the turbo level (clamped to the configured speeds). */
   setLevel(index: number): void;
+  /** Mark autoplay/hold as running so `delay()` shortens game animations. The core sets
+   *  this on autoplayStarted/holdSpinStarted and clears it when they stop. */
+  setAutoplay(active: boolean): 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. */
@@ -118,11 +129,25 @@ interface GameConfig {
 declare function modeCostOf(config: GameConfig, mode: string): number;
 //#endregion
 //#region src/engine/fsm.d.ts
+/** A fixed value or a per-voice random spread (`{ base, jitter }`) — structurally matches
+ *  zvuk's `VoiceJitter` without importing it, so the engine stays zvuk-free. */
+type AudioValue = number | {
+  base?: number;
+  jitter?: number;
+};
+/** The minimal boot-loader surface a game's phases touch (satisfied by the core's
+ *  `GameLoader`) — kept structural so the engine needn't import the loader module. */
+interface LoaderPort {
+  setProgress(p: number): void;
+  done(): Promise<void>;
+}
 /** The minimal audio surface a game's phases call (satisfied by `@stakeplate/core/audio`). */
 interface AudioPort {
+  /** Fire a one-shot. `volume`/`pitch` accept jitter so repeated cues vary per voice. */
   play(name: string, opts?: {
     bus?: string;
-    volume?: number;
+    volume?: AudioValue;
+    pitch?: AudioValue;
   }): void;
   music(name: string, opts?: {
     fadeIn?: number;
@@ -144,6 +169,8 @@ interface PhaseContext<T = unknown, V = unknown, E = unknown> {
   readonly audio: AudioPort | null;
   /** Turbo speed + slam-stop (core-owned). Use `ctx.turbo.delay(ms)` for spin/anim timing. */
   readonly turbo: TurboState;
+  /** The boot loader, if one was configured (else `null`) — drive progress / `done()`. */
+  readonly loader: LoaderPort | null;
   readonly interpretBook: InterpretBook<T, E>;
   readonly fsm: FSM<T, V, E>;
   round: GameRound<T, E> | null;
@@ -194,6 +221,32 @@ declare function bindMixerToHud(mixer: MixerLike, hud: BootedHud, opts?: {
   storageKey?: string;
 }): () => void;
 //#endregion
+//#region src/audio/inputs.d.ts
+/** Cue name per HUD input event. Any omitted → that input stays silent. */
+interface InputSoundMap {
+  /** Spin button press (and each autoplay/hold re-spin fires `spinRequested`). */
+  spin?: string;
+  /** Bet +/- (the bet stepper's `valueChanged`). */
+  bet?: string;
+  /** Autoplay engaged (count picked). */
+  autoplay?: string;
+  /** Turbo cycler toggled. */
+  turbo?: string;
+  /** Any switch toggled (turbo/sound/…) — a generic UI click. */
+  toggle?: string;
+  /** Slam-stop (tap-to-skip the spin). */
+  skip?: string;
+}
+interface InputSoundOptions {
+  /** Bus to route the cues to (default `'ui'`). */
+  bus?: string;
+}
+/**
+ * Wire the HUD input events to sounds. Returns a disposer. Safe to call with a partial map —
+ * only the mapped inputs subscribe.
+ */
+declare function bindInputSounds(audio: AudioPort, hud: BootedHud, map: InputSoundMap, opts?: InputSoundOptions): () => void;
+//#endregion
 //#region src/audio/index.d.ts
 /** Buses in the MUSIC group (driven by the Music slider). */
 type MusicBus = 'music' | 'ambience';
@@ -209,6 +262,18 @@ interface GameAudioOptions {
   /** Duck the MUSIC group while THESE sfx buses are active (default `['wins']`; `null` = off). */
   duckMusicFrom?: SfxBus | SfxBus[] | null;
   duckAmount?: number;
+  /**
+   * RMS loudness normalization applied to every loaded one-shot so the whole manifest sits
+   * at a consistent level (no hand-tuned per-file gains). A per-entry `normalize` overrides
+   * this. Default `true`. Pass a `LoudnessOptions` object to tune the target, or `false` off.
+   */
+  normalize?: boolean | LoudnessOptions;
+  /**
+   * Voice cap applied to EACH effects bus so stacked one-shots (a multi-pay cascade, rapid
+   * contacts) don't machine-gun — steals the oldest voice when the cap is hit. Default
+   * `{ max: 8, steal: 'oldest' }`. Pass `null` to leave the effects buses uncapped.
+   */
+  sfxConcurrency?: ConcurrencyConfig | null;
 }
 /**
  * A sound to load onto a bus, or a music track (intro/loop/outro → the `music` bus).
@@ -221,6 +286,7 @@ type SoundEntry = {
   kind?: 'sound';
   url: string | string[];
   bus?: BusName;
+  normalize?: boolean | LoudnessOptions;
 } | {
   name: string;
   kind: 'music';
@@ -236,6 +302,7 @@ declare class GameAudio implements AudioPort, MixerLike {
   private readonly effectsGroup;
   private readonly duckFrom;
   private readonly duckAmount;
+  private readonly normalizeDefault;
   private unlocked;
   private currentMusic;
   constructor(opts?: GameAudioOptions);
@@ -250,9 +317,12 @@ declare class GameAudio implements AudioPort, MixerLike {
   group(name: MixerGroup): BusGroup;
   /** Preload a manifest of sounds + music onto their buses. */
   load(entries: SoundEntry[]): Promise<void>;
+  /** Fire a one-shot. `volume`/`pitch` accept a `VoiceJitter` (`{ base, jitter }`) so
+   *  repeated cues — contacts, ticks — vary per voice instead of sounding cloned. */
   play(name: string, opts?: {
     bus?: BusName;
-    volume?: number;
+    volume?: number | VoiceJitter;
+    pitch?: number | VoiceJitter;
   }): void;
   music(name: string, opts?: {
     fadeIn?: number;
@@ -272,5 +342,5 @@ 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
+export { TurboState as A, modeCostOf as C, roundInfo as D, RoundInfo as E, DEFAULT_TURBO_SPEEDS as O, ModeConfig as S, InterpretBook as T, FSM as _, SfxBus as a, PhaseContext as b, createGameAudio as c, bindInputSounds as d, MixerGroup as f, AudioValue as g, AudioPort as h, MusicBus as i, TurboClock as k, InputSoundMap as l, bindMixerToHud as m, GameAudio as n, SoundEntry as o, MixerLike as p, GameAudioOptions as r, bindAudioToHud as s, BusName as t, InputSoundOptions as u, LoaderPort as v, GameRound as w, GameConfig as x, Phase as y };
+//# sourceMappingURL=index-DsA8mDpk.d.ts.map

package/dist/index.d.ts

@@ -2,9 +2,10 @@ import { a as Balance, c as JurisdictionConfig, d as ReplayParams, f as RgsConfi
 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 { A as TurboState, C as modeCostOf, D as roundInfo, E as RoundInfo, O as DEFAULT_TURBO_SPEEDS, S as ModeConfig, T as InterpretBook, _ as FSM, b as PhaseContext, g as AudioValue, h as AudioPort, k as TurboClock, l as InputSoundMap, o as SoundEntry, r as GameAudioOptions, v as LoaderPort, w as GameRound, x as GameConfig, y as Phase } from "./index-DsA8mDpk.js";
 import { StakeNetworkManager, StakeNetworkOptions } from "./rgs.js";
 import { BootedHud } from "@open-slot-ui/pixi";
+import { CurrencySpec } from "@open-slot-ui/core";
 //#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> {
@@ -32,6 +33,92 @@ declare class SettlePhase<T = unknown, V = unknown, E = unknown> implements Phas
 /** 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/engine/beat.d.ts
+interface BeatOptions {
+  /** Pause before the announcement shows — lets the reveal settle. Default 0. */
+  leadMs?: number;
+  /** How long the announcement holds alone on screen. */
+  holdMs: number;
+  /** Pause after hiding, before play resumes. Default 0. */
+  trailMs?: number;
+  /** Reveal the announcement (banner/sfx). Called after the lead pause. */
+  show: () => void;
+  /** Hide it. Called after the hold, before the trailing pause. Optional (some banners
+   *  self-dismiss). */
+  hide?: () => void;
+  /**
+   * Timing source. `'real'` (default) is a fixed, unskippable beat via the ticker — an
+   * announcement is a deliberate moment that a slam-stop shouldn't blow past. `'turbo'`
+   * makes the pauses turbo-/autoplay-/slam-stop-aware (shorter under turbo, skippable).
+   */
+  timing?: 'real' | 'turbo';
+}
+/** Timing surface the beat needs — a `PhaseContext` satisfies it (`ctx.ticker`/`ctx.turbo`). */
+interface BeatClock {
+  ticker: Ticker;
+  turbo: TurboState;
+}
+/**
+ * Run a blocking announcement beat: lead → show → hold → hide → trail. Awaitable, so a
+ * Present phase just `await blockingBeat(ctx, { … })` and the round pauses for the whole
+ * thing. Returns when the beat (including the trailing pause) is over.
+ */
+declare function blockingBeat(ctx: BeatClock, opts: BeatOptions): Promise<void>;
+//#endregion
+//#region src/loader/index.d.ts
+/** One feature card on the intro splash — an image with a short (may be multi-line) caption. */
+interface FeatureItem {
+  /** Image URL / data-URI. Rendered at a uniform height so mismatched art still lines up. */
+  image: string;
+  /** Short caption under the image. `\n` for line breaks. */
+  text: string;
+}
+interface LoaderConfig {
+  /** Big title under the logo (LOADING phase only). Defaults to the game title. */
+  title?: string;
+  /** Small line under the title (LOADING phase). */
+  subtitle?: string;
+  /** URL/data-URI of the logo. Pulses while loading; glides to the top for the features
+   *  splash. Omit for a CSS ring spinner (and no move-up). */
+  logo?: string;
+  /** Solid colour behind everything. Default `#0b0d12`. */
+  background?: string;
+  /** Optional cover image (ideally the game's own backdrop, for a seamless reveal). */
+  backgroundImage?: string;
+  /** Blur the cover image. Default `true`. */
+  blur?: boolean;
+  /** Accent colour — progress fill + title glow + caption text. Default `#d99000`. */
+  accent?: string;
+  /** Minimum time the LOADING phase stays up, so the bar always fills. Default `1200`ms. */
+  minDurationMs?: number;
+  /** Stacking order. Default a very high value so it sits over the game. */
+  zIndex?: number;
+  /**
+   * If `true`, the core shows the loader + advances progress but does NOT auto-advance past
+   * LOADING — the game calls `ctx.loader.done()` itself (e.g. after its scene finishes loading
+   * art). Default `false`. (The FEATURES splash always waits for the player regardless.)
+   */
+  manual?: boolean;
+  /** 2–3 feature cards → show a FEATURES splash after loading. Omit for a plain loader. */
+  features?: FeatureItem[];
+  /** The dismiss prompt under the feature cards. Default `PRESS TO CONTINUE`. */
+  continueText?: string;
+}
+interface GameLoader {
+  /** The overlay element (already in the document). */
+  readonly el: HTMLElement;
+  /** Drive the progress bar. Clamped to the range it has already reached (never goes back). */
+  setProgress(p: number): void;
+  /** Advance out of LOADING: fill to 100%, honour `minDurationMs`, then either show the
+   *  FEATURES splash (waiting for the player to continue) or — with no features — pop away.
+   *  Resolves once the overlay is fully gone. Idempotent (first call wins). */
+  done(): Promise<void>;
+  /** Remove immediately without any outro (used on a boot error). */
+  remove(): void;
+}
+/** Create + mount the boot overlay. Safe to call before anything else in boot. */
+declare function createLoader(config?: LoaderConfig): GameLoader;
+//#endregion
 //#region src/game/createStakeGame.d.ts
 /**
  * Declarative audio: hand the core your sounds and it lazily creates the `@schmooky/zvuk`
@@ -41,6 +128,9 @@ declare function defaultPhases<T = unknown, V = unknown, E = unknown>(): Phase<T
  */
 interface AudioSpec extends GameAudioOptions {
   sounds: SoundEntry[];
+  /** Optional: play a cue on HUD input events (spin/bet/autoplay/turbo/toggle/skip). The
+   *  core auto-binds these after the HUD mounts — the named sounds must be in `sounds`. */
+  inputSounds?: InputSoundMap;
 }
 /** Passed to `mountView` — everything the game's scene needs (not the round/fsm yet). */
 interface ViewContext {
@@ -51,6 +141,10 @@ interface ViewContext {
   audio: AudioPort | null;
   /** Turbo speed + slam-stop (core-owned) — the scene may branch on `turbo.level`/`speed`. */
   turbo: TurboState;
+  /** The boot loader (if `loader` was configured) — drive `setProgress` while your scene
+   *  loads art, and (with `loader.manual`) call `done()` when the scene is ready. `null`
+   *  when no loader is used. */
+  loader: GameLoader | null;
 }
 interface CreateStakeGameOptions<T = unknown, V = unknown, E = unknown> {
   config: GameConfig;
@@ -72,6 +166,14 @@ interface CreateStakeGameOptions<T = unknown, V = unknown, E = unknown> {
   sceneHost?: HTMLElement;
   /** Passthrough to `mountHud` (spinSkin, icons, gsap, menu:false, hooks, …). */
   hudOptions?: Record<string, unknown>;
+  /**
+   * A configurable boot loader — shows the instant boot starts, advances across the boot
+   * milestones, then fills + pops away when the game is ready. Pass a {@link LoaderConfig}
+   * to enable it (title defaults to `config.title`); omit or `false` to render none (the
+   * game keeps its own HTML loader). With `manual: true`, call `ctx.loader.done()` yourself
+   * (e.g. after the scene's art finishes loading).
+   */
+  loader?: LoaderConfig | false;
 }
 /** A read-only snapshot of the running game — for the dev harness, tests and debugging. */
 interface GameSnapshot {
@@ -92,5 +194,20 @@ interface StakeGame {
 }
 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 };
+//#region src/currency/index.d.ts
+/** Three-decimal fiat missing from the @open-slot-ui currency table — the Gulf/Arab
+ *  dinars & rials (the lib already covers KWD/BHD/JOD). `symbol` follows the lib's short
+ *  latinised convention for the region (KWD→"KD", …). */
+declare const EXTRA_DECIMALS: Readonly<Record<string, {
+  decimals: number;
+  symbol: string;
+}>>;
+/**
+ * `resolveCurrency`, but with the missing 3-decimal dinars/rials patched in. Use this
+ * everywhere a currency code becomes a `CurrencySpec` so precision is correct for every
+ * code — `createStakeGame` routes all of its resolution through here.
+ */
+declare function currencyFor(code: string): CurrencySpec;
+//#endregion
+export { API_AMOUNT_MULTIPLIER, AudioPort, AudioSpec, AudioValue, AuthenticateRequest, AuthenticateResponse, BOOK_AMOUNT_MULTIPLIER, Balance, BalanceStore, BeatClock, BeatOptions, CreateStakeGameOptions, DEFAULT_TURBO_SPEEDS, EXTRA_DECIMALS, EndRoundRequest, EndRoundResponse, FSM, FeatureItem, GameConfig, GameLoader, GameRound, GameSnapshot, HudPort, IdlePhase, InstantTicker, InterpretBook, JurisdictionConfig, LoaderConfig, LoaderPort, 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, blockingBeat, createLoader, createNetwork, createStakeGame, currencyFor, defaultPhases, modeCostOf, readRuntime, roundEvents, roundInfo, urlParam };
 //# sourceMappingURL=index.d.ts.map