@energy8platform/game-engine 0.16.0 → 0.18.0

package/dist/host.d.ts

@@ -0,0 +1,915 @@
+import { Container, ApplicationOptions, Application, Texture } from 'pixi.js';
+import { GameModel } from '@energy8platform/platform-core/game-spec';
+import { LoadingScreenConfig, AssetManifest, PlatformSession } from '@energy8platform/platform-core';
+import * as _energy8platform_platform_core_shell from '@energy8platform/platform-core/shell';
+import { CurrencyConfig, GameInfoContent, BonusOption, ShellFeatures, ShellMode, ShellConfig, GameShell } from '@energy8platform/platform-core/shell';
+export { socialize } from '@energy8platform/platform-core/shell';
+import { BookAdapter, AdapterModule, StakeBridge } from '@energy8platform/stake-bridge';
+import { CasinoGameSDK, InitData, GameConfigData, SessionData } from '@energy8platform/game-sdk';
+import { SlotSpinResultBase, SlotResultNormalizer } from '@energy8platform/platform-core/slot-result';
+
+declare enum ScaleMode {
+    /** Fit inside container, maintain aspect ratio (letterbox/pillarbox) */
+    FIT = "FIT",
+    /** Fill container, maintain aspect ratio (crop edges) */
+    FILL = "FILL",
+    /** Stretch to fill (distorts) */
+    STRETCH = "STRETCH"
+}
+declare enum Orientation {
+    LANDSCAPE = "landscape",
+    PORTRAIT = "portrait",
+    ANY = "any"
+}
+
+interface AudioConfig {
+    /** Default volumes per category (0..1) */
+    music?: number;
+    sfx?: number;
+    ui?: number;
+    ambient?: number;
+    /** Persist mute state in localStorage */
+    persist?: boolean;
+    /** LocalStorage key prefix */
+    storageKey?: string;
+}
+interface GameApplicationConfig {
+    /** Container element or CSS selector to mount canvas into */
+    container?: HTMLElement | string;
+    /** Reference design width (fallback: GameConfigData.viewport.width or 1920) */
+    designWidth?: number;
+    /** Reference design height (fallback: GameConfigData.viewport.height or 1080) */
+    designHeight?: number;
+    /** How to scale the game to fit the container */
+    scaleMode?: ScaleMode;
+    /** Preferred orientation */
+    orientation?: Orientation;
+    /** Loading screen configuration */
+    loading?: LoadingScreenConfig;
+    /** Asset manifest — what to load */
+    manifest?: AssetManifest;
+    /** Audio configuration */
+    audio?: AudioConfig;
+    /** SDK options. Set to false to disable SDK (offline/development mode) */
+    sdk?: {
+        parentOrigin?: string;
+        timeout?: number;
+        debug?: boolean;
+        /** Use in-memory channel instead of postMessage (no iframe required) */
+        devMode?: boolean;
+    } | false;
+    /** PixiJS Application options (pass-through) */
+    pixi?: Partial<ApplicationOptions>;
+    /** Enable debug overlay (FPS, draw calls) */
+    debug?: boolean;
+    /** When set, GameApplication mounts the branded game shell after the SDK handshake. */
+    shell?: _energy8platform_platform_core_shell.ShellConfig | false;
+}
+interface SceneConstructor {
+    new (): IScene;
+    [key: string]: any;
+}
+interface IScene {
+    /** Root display container for this scene */
+    readonly container: Container;
+    /** @internal GameApplication reference — set by SceneManager */
+    __engineApp?: any;
+    /** Called when the scene is entered */
+    onEnter?(data?: unknown): Promise<void> | void;
+    /** Called when the scene is exited */
+    onExit?(): Promise<void> | void;
+    /** Called every frame */
+    onUpdate?(dt: number): void;
+    /** Called when viewport resizes */
+    onResize?(width: number, height: number): void;
+    /** Called when the scene is destroyed */
+    onDestroy?(): void;
+}
+declare enum TransitionType {
+    NONE = "none",
+    FADE = "fade",
+    SLIDE_LEFT = "slide-left",
+    SLIDE_RIGHT = "slide-right"
+}
+interface TransitionConfig {
+    type: TransitionType;
+    duration?: number;
+    easing?: (t: number) => number;
+}
+interface GameEngineEvents {
+    /** Fired when engine initialization is complete */
+    initialized: void;
+    /** Fired when all assets are loaded */
+    loaded: void;
+    /** Fired when the engine starts running */
+    started: void;
+    /** Fired on viewport resize */
+    resize: {
+        width: number;
+        height: number;
+    };
+    /** Fired on orientation change */
+    orientationChange: Orientation;
+    /** Fired on scene change */
+    sceneChange: {
+        from: string | null;
+        to: string;
+    };
+    /** Fired when player balance changes (forwarded from SDK) */
+    balanceUpdate: {
+        balance: number;
+    };
+    /** Fired on error */
+    error: Error;
+    /** Fired when engine is destroyed */
+    destroyed: void;
+}
+
+/**
+ * Minimal typed event emitter.
+ * Used internally by GameApplication, SceneManager, AudioManager, etc.
+ *
+ * Supports `void` event types — events that carry no data can be emitted
+ * without arguments: `emitter.emit('eventName')`.
+ */
+declare class EventEmitter<TEvents extends {}> {
+    private listeners;
+    on<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
+    once<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
+    off<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
+    emit<K extends keyof TEvents>(...args: TEvents[K] extends void ? [event: K] : [event: K, data: TEvents[K]]): void;
+    removeAllListeners(event?: keyof TEvents): this;
+}
+
+interface SceneEntry$1 {
+    scene: IScene;
+    key: string;
+}
+interface SceneManagerEvents {
+    change: {
+        from: string | null;
+        to: string;
+    };
+}
+/**
+ * Manages the scene stack and transitions between scenes.
+ *
+ * @example
+ * ```ts
+ * const scenes = new SceneManager(app.stage);
+ * scenes.register('loading', LoadingScene);
+ * scenes.register('game', GameScene);
+ * await scenes.goto('loading');
+ * ```
+ */
+declare class SceneManager extends EventEmitter<SceneManagerEvents> {
+    private static MAX_TRANSITION_DEPTH;
+    /** Root container that scenes are added to */
+    root: Container;
+    private registry;
+    private stack;
+    private _transitionDepth;
+    /** Current viewport dimensions — set by ViewportManager */
+    private _width;
+    private _height;
+    /** @internal GameApplication reference — passed to scenes */
+    private _app;
+    constructor(root?: Container);
+    /** @internal Set the root container (called by GameApplication after PixiJS init) */
+    setRoot(root: Container): void;
+    /** @internal Set the app reference (called by GameApplication) */
+    setApp(app: any): void;
+    /** Register a scene class by key */
+    register(key: string, ctor: SceneConstructor): this;
+    /** Get the current (topmost) scene entry */
+    get current(): SceneEntry$1 | null;
+    /** Get the current scene key */
+    get currentKey(): string | null;
+    /** Whether a scene transition is in progress */
+    get isTransitioning(): boolean;
+    /**
+     * Navigate to a scene, replacing the entire stack.
+     */
+    goto(key: string, data?: unknown, transition?: TransitionConfig): Promise<void>;
+    /**
+     * Push a scene onto the stack (the previous scene stays underneath).
+     * Useful for overlays, modals, pause screens.
+     */
+    push(key: string, data?: unknown, transition?: TransitionConfig): Promise<void>;
+    /**
+     * Pop the top scene from the stack.
+     */
+    pop(transition?: TransitionConfig): Promise<void>;
+    /**
+     * Replace the top scene with a new one.
+     */
+    replace(key: string, data?: unknown, transition?: TransitionConfig): Promise<void>;
+    /**
+     * Called every frame by GameApplication.
+     */
+    update(dt: number): void;
+    /**
+     * Called on viewport resize.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Destroy all scenes and clear the manager.
+     */
+    destroy(): void;
+    private createScene;
+    private pushInternal;
+    private popInternal;
+    private transitionIn;
+    private transitionOut;
+}
+
+/**
+ * Manages game asset loading with progress tracking, bundle support, and
+ * automatic base path resolution from SDK's assetsUrl.
+ *
+ * Wraps PixiJS Assets API with a typed, game-oriented interface.
+ *
+ * @example
+ * ```ts
+ * const assets = new AssetManager('https://cdn.example.com/game/', manifest);
+ * await assets.init();
+ * await assets.loadBundle('preload', (p) => console.log(p));
+ * const texture = assets.get<Texture>('hero');
+ * ```
+ */
+declare class AssetManager {
+    private _initialized;
+    private _basePath;
+    private _manifest;
+    private _loadedBundles;
+    constructor(basePath?: string, manifest?: AssetManifest);
+    /** Whether the asset system has been initialized */
+    get initialized(): boolean;
+    /** Base path for all assets (usually from SDK's assetsUrl) */
+    get basePath(): string;
+    /** Set of loaded bundle names */
+    get loadedBundles(): ReadonlySet<string>;
+    /**
+     * Initialize the asset system.
+     * Must be called before loading any assets.
+     */
+    init(): Promise<void>;
+    /**
+     * Load a single bundle by name.
+     *
+     * @param name - Bundle name (must exist in the manifest)
+     * @param onProgress - Progress callback (0..1)
+     * @returns Loaded assets map
+     */
+    loadBundle(name: string, onProgress?: (progress: number) => void): Promise<Record<string, unknown>>;
+    /**
+     * Load multiple bundles simultaneously.
+     * Progress is aggregated across all bundles.
+     *
+     * @param names - Bundle names
+     * @param onProgress - Progress callback (0..1)
+     */
+    loadBundles(names: string[], onProgress?: (progress: number) => void): Promise<Record<string, unknown>>;
+    /**
+     * Load individual assets by URL or alias.
+     *
+     * @param urls - Asset URLs or aliases
+     * @param onProgress - Progress callback (0..1)
+     */
+    load<T = unknown>(urls: string | string[], onProgress?: (progress: number) => void): Promise<T>;
+    /**
+     * Get a loaded asset synchronously from cache.
+     *
+     * @param alias - Asset alias
+     * @throws if not loaded
+     */
+    get<T = unknown>(alias: string): T;
+    /**
+     * Unload a bundle to free memory.
+     */
+    unloadBundle(name: string): Promise<void>;
+    /**
+     * Start background loading a bundle (low-priority preload).
+     * Useful for loading bonus round assets while player is in base game.
+     */
+    backgroundLoad(name: string): Promise<void>;
+    /**
+     * Get all bundle names from the manifest.
+     */
+    getBundleNames(): string[];
+    /**
+     * Check if a bundle is loaded.
+     */
+    isBundleLoaded(name: string): boolean;
+    private ensureInitialized;
+}
+
+type AudioCategoryName = 'music' | 'sfx' | 'ui' | 'ambient';
+/**
+ * Manages all game audio: music, SFX, UI sounds, ambient.
+ *
+ * Optional dependency on @pixi/sound — if not installed, AudioManager
+ * operates as a silent no-op (graceful degradation).
+ *
+ * Features:
+ * - Per-category volume control (music, sfx, ui, ambient)
+ * - Music crossfade and looping
+ * - Mobile audio unlock on first interaction
+ * - Mute state persistence in localStorage
+ * - Global mute/unmute
+ *
+ * @example
+ * ```ts
+ * const audio = new AudioManager({ music: 0.5, sfx: 0.8 });
+ * await audio.init();
+ * audio.playMusic('bg-music');
+ * audio.play('spin-click', 'sfx');
+ * ```
+ */
+declare class AudioManager {
+    private _soundModule;
+    private _initialized;
+    private _globalMuted;
+    private _persist;
+    private _storageKey;
+    private _categories;
+    private _currentMusic;
+    private _unlocked;
+    private _unlockHandler;
+    constructor(config?: AudioConfig);
+    /** Whether the audio system is initialized */
+    get initialized(): boolean;
+    /** Whether audio is globally muted */
+    get muted(): boolean;
+    /**
+     * Initialize the audio system.
+     * Dynamically imports @pixi/sound to keep it optional.
+     */
+    init(): Promise<void>;
+    /**
+     * Play a sound effect.
+     *
+     * @param alias - Sound alias (must be loaded via AssetManager)
+     * @param category - Audio category (default: 'sfx')
+     * @param options - Additional play options
+     */
+    play(alias: string, category?: AudioCategoryName, options?: {
+        volume?: number;
+        loop?: boolean;
+        speed?: number;
+    }): void;
+    /**
+     * Play background music with optional crossfade.
+     *
+     * @param alias - Music alias
+     * @param fadeDuration - Crossfade duration in ms (default: 500)
+     */
+    playMusic(alias: string, fadeDuration?: number): void;
+    /**
+     * Stop current music.
+     */
+    stopMusic(): void;
+    /**
+     * Stop all sounds.
+     */
+    stopAll(): void;
+    /**
+     * Set volume for a category.
+     */
+    setVolume(category: AudioCategoryName, volume: number): void;
+    /**
+     * Get volume for a category.
+     */
+    getVolume(category: AudioCategoryName): number;
+    /**
+     * Mute a specific category.
+     */
+    muteCategory(category: AudioCategoryName): void;
+    /**
+     * Unmute a specific category.
+     */
+    unmuteCategory(category: AudioCategoryName): void;
+    /**
+     * Toggle mute for a category.
+     */
+    toggleCategory(category: AudioCategoryName): boolean;
+    /**
+     * Mute all audio globally.
+     */
+    muteAll(): void;
+    /**
+     * Unmute all audio globally.
+     */
+    unmuteAll(): void;
+    /**
+     * Toggle global mute.
+     */
+    toggleMute(): boolean;
+    /**
+     * Duck music volume (e.g., during big win presentation).
+     *
+     * @param factor - Volume multiplier (0..1), e.g. 0.3 = 30% of normal
+     */
+    duckMusic(factor: number): void;
+    /**
+     * Restore music to normal volume after ducking.
+     */
+    unduckMusic(): void;
+    /**
+     * Destroy the audio manager and free resources.
+     */
+    destroy(): void;
+    /**
+     * Smoothly fade a sound's volume from `fromVol` to `toVol` over `durationMs`.
+     */
+    private fadeVolume;
+    private applyVolumes;
+    private setupMobileUnlock;
+    private removeMobileUnlock;
+    private saveState;
+    private restoreState;
+}
+
+interface InputEvents {
+    tap: {
+        x: number;
+        y: number;
+    };
+    press: {
+        x: number;
+        y: number;
+    };
+    release: {
+        x: number;
+        y: number;
+    };
+    move: {
+        x: number;
+        y: number;
+    };
+    swipe: {
+        direction: 'up' | 'down' | 'left' | 'right';
+        velocity: number;
+    };
+    keydown: {
+        key: string;
+        code: string;
+    };
+    keyup: {
+        key: string;
+        code: string;
+    };
+}
+/**
+ * Unified input manager for touch, mouse, and keyboard.
+ *
+ * Features:
+ * - Unified pointer events (works with touch + mouse)
+ * - Swipe gesture detection
+ * - Keyboard input with isKeyDown state
+ * - Input locking (block input during animations)
+ *
+ * @example
+ * ```ts
+ * const input = new InputManager(app.canvas);
+ *
+ * input.on('tap', ({ x, y }) => console.log('Tapped at', x, y));
+ * input.on('swipe', ({ direction }) => console.log('Swiped', direction));
+ * input.on('keydown', ({ key }) => {
+ *   if (key === ' ') spin();
+ * });
+ *
+ * // Block input during animations
+ * input.lock();
+ * await playAnimation();
+ * input.unlock();
+ * ```
+ */
+declare class InputManager extends EventEmitter<InputEvents> {
+    private _canvas;
+    private _locked;
+    private _keysDown;
+    private _destroyed;
+    private _viewportScale;
+    private _viewportOffsetX;
+    private _viewportOffsetY;
+    private _pointerStart;
+    private _swipeThreshold;
+    private _swipeMaxTime;
+    constructor(canvas: HTMLCanvasElement);
+    /** Whether input is currently locked */
+    get locked(): boolean;
+    /** Lock all input (e.g., during animations) */
+    lock(): void;
+    /** Unlock input */
+    unlock(): void;
+    /** Check if a key is currently pressed */
+    isKeyDown(key: string): boolean;
+    /**
+     * Update the viewport transform used for DOM→world coordinate mapping.
+     * Called automatically by GameApplication when ViewportManager emits resize.
+     */
+    setViewportTransform(scale: number, offsetX: number, offsetY: number): void;
+    /**
+     * Convert a DOM canvas position to game-world coordinates,
+     * accounting for viewport scaling and offset.
+     */
+    getWorldPosition(canvasX: number, canvasY: number): {
+        x: number;
+        y: number;
+    };
+    /** Destroy the input manager */
+    destroy(): void;
+    private setupPointerEvents;
+    private onPointerDown;
+    private onPointerUp;
+    private onPointerMove;
+    private getCanvasPosition;
+    private setupKeyboardEvents;
+    private onKeyDown;
+    private onKeyUp;
+}
+
+interface ViewportConfig {
+    designWidth: number;
+    designHeight: number;
+    scaleMode: ScaleMode;
+    orientation: Orientation;
+}
+interface ViewportEvents {
+    resize: {
+        width: number;
+        height: number;
+        scale: number;
+    };
+    orientationChange: Orientation;
+}
+/**
+ * Manages responsive scaling of the game canvas to fit its container.
+ *
+ * Supports three scale modes:
+ * - **FIT** — letterbox/pillarbox to maintain aspect ratio (industry standard)
+ * - **FILL** — fill container, crop edges
+ * - **STRETCH** — stretch to fill (distorts)
+ *
+ * Also handles:
+ * - Orientation detection (landscape/portrait)
+ * - Safe areas (mobile notch)
+ * - ResizeObserver for smooth container resizing
+ *
+ * @example
+ * ```ts
+ * const viewport = new ViewportManager(app, container, {
+ *   designWidth: 1920,
+ *   designHeight: 1080,
+ *   scaleMode: ScaleMode.FIT,
+ *   orientation: Orientation.LANDSCAPE,
+ * });
+ *
+ * viewport.on('resize', ({ width, height, scale }) => {
+ *   console.log(`New size: ${width}x${height} @ ${scale}x`);
+ * });
+ * ```
+ */
+declare class ViewportManager extends EventEmitter<ViewportEvents> {
+    private _app;
+    private _container;
+    private _config;
+    private _resizeObserver;
+    private _currentOrientation;
+    private _currentWidth;
+    private _currentHeight;
+    private _currentScale;
+    private _destroyed;
+    private _resizeTimeout;
+    constructor(app: Application, container: HTMLElement, config: ViewportConfig);
+    /** Current canvas width in game units */
+    get width(): number;
+    /** Current canvas height in game units */
+    get height(): number;
+    /** Current scale factor */
+    get scale(): number;
+    /** Current orientation */
+    get orientation(): Orientation;
+    /** Design reference width */
+    get designWidth(): number;
+    /** Design reference height */
+    get designHeight(): number;
+    /**
+     * Force a resize calculation. Called automatically on container size change.
+     */
+    refresh(): void;
+    /**
+     * Destroy the viewport manager.
+     */
+    destroy(): void;
+    private setupObserver;
+    private onWindowResize;
+    private debouncedRefresh;
+}
+
+/**
+ * FPS overlay for debugging performance.
+ *
+ * Shows FPS, frame time, and draw call count in the corner of the screen.
+ *
+ * @example
+ * ```ts
+ * const fps = new FPSOverlay(app);
+ * fps.show();
+ * ```
+ */
+declare class FPSOverlay {
+    private _app;
+    private _container;
+    private _fpsText;
+    private _visible;
+    private _samples;
+    private _maxSamples;
+    private _lastUpdate;
+    private _tickFn;
+    constructor(app: Application);
+    /** Show the FPS overlay */
+    show(): void;
+    /** Hide the FPS overlay */
+    hide(): void;
+    /** Toggle visibility */
+    toggle(): void;
+    /** Destroy the overlay */
+    destroy(): void;
+}
+
+/**
+ * The main entry point for a game built on @energy8platform/game-engine.
+ *
+ * Orchestrates the full lifecycle:
+ * 1. Create PixiJS Application
+ * 2. Initialize SDK (or run offline)
+ * 3. Show CSS preloader → Canvas loading screen with progress bar
+ * 4. Load asset manifest
+ * 5. Transition to the first game scene
+ *
+ * @example
+ * ```ts
+ * import { GameApplication, ScaleMode } from '@energy8platform/game-engine';
+ * import { GameScene } from './scenes/GameScene';
+ *
+ * const game = new GameApplication({
+ *   container: '#game',
+ *   designWidth: 1920,
+ *   designHeight: 1080,
+ *   scaleMode: ScaleMode.FIT,
+ *   manifest: { bundles: [
+ *     { name: 'preload', assets: [{ alias: 'logo', src: 'logo.png' }] },
+ *     { name: 'game', assets: [{ alias: 'bg', src: 'background.png' }] },
+ *   ]},
+ *   loading: { tapToStart: true },
+ * });
+ *
+ * game.scenes.register('game', GameScene);
+ * await game.start('game');
+ * ```
+ */
+declare class GameApplication extends EventEmitter<GameEngineEvents> {
+    /** PixiJS Application instance */
+    app: Application;
+    /** Scene manager */
+    scenes: SceneManager;
+    /** Asset manager */
+    assets: AssetManager;
+    /** Audio manager */
+    audio: AudioManager;
+    /** Input manager */
+    input: InputManager;
+    /** Viewport manager */
+    viewport: ViewportManager;
+    /** SDK instance (null in offline mode) */
+    sdk: CasinoGameSDK | null;
+    /** FPS overlay instance (only when debug: true) */
+    fpsOverlay: FPSOverlay | null;
+    /** Data received from SDK initialization */
+    initData: InitData | null;
+    /** Platform session (SDK + optional DevBridge). null until start() runs. */
+    platformSession: PlatformSession | null;
+    /** Branded game shell (only when config.shell is set). */
+    shell?: _energy8platform_platform_core_shell.GameShell;
+    /** Configuration */
+    readonly config: GameApplicationConfig;
+    private _running;
+    private _destroyed;
+    private _container;
+    constructor(config?: GameApplicationConfig);
+    /** Current game config from SDK (or null in offline mode) */
+    get gameConfig(): GameConfigData | null;
+    /** Current session data */
+    get session(): SessionData | null;
+    /** Current balance */
+    get balance(): number;
+    /** Current currency */
+    get currency(): string;
+    /** Whether the engine is running */
+    get isRunning(): boolean;
+    /**
+     * Start the game engine. This is the main entry point.
+     *
+     * @param firstScene - Key of the first scene to show after loading (must be registered)
+     * @param sceneData - Optional data to pass to the first scene's onEnter
+     */
+    start(firstScene: string, sceneData?: unknown): Promise<void>;
+    /**
+     * Destroy the engine and free all resources.
+     */
+    destroy(): Promise<void>;
+    private resolveContainer;
+    private initPixi;
+    private initSDK;
+    private applySDKConfig;
+    private initSubSystems;
+    private loadAssets;
+}
+
+interface WinTier {
+    id: string;
+    minMultiplier: number;
+    title: string;
+    accentColor: number;
+    bannerTexture?: Texture;
+}
+
+interface SlotShellOptions {
+    mount?: HTMLElement;
+    /** Override the derived currency (normally taken from initData). */
+    currency?: CurrencyConfig;
+    /** Author-supplied info sections, MERGED over the host-derived set by section identity (an author
+     *  section REPLACES the derived one of the same `type`/`kind`; a new `type` is appended; derived
+     *  sections without an override are kept).
+     *
+     *  Pass a plain `GameInfoContent`, OR a function `(t) => GameInfoContent` where `t` is the
+     *  social-aware translator (it rewrites restricted gambling words when in social mode, and is the
+     *  identity otherwise) — wrap player-facing copy in `t(...)` so it socializes. Either way the
+     *  merged result is also run through `socialize` in social mode as a safety net, so forbidden
+     *  words never leak even if `t()` was forgotten. */
+    gameInfo?: GameInfoContent | ((t: (text: string) => string) => GameInfoContent);
+    /** Override the derived buy/ante options. In social mode the card copy is socialized too. */
+    buyBonus?: BonusOption[];
+    tiers?: WinTier[];
+    features?: Partial<ShellFeatures>;
+}
+/** Runtime context from the SDK handshake (initData) + the resolved mode. */
+interface ShellRuntime {
+    balance: number;
+    /** Resolved shell currency, derived from `initData.config.currency` (the SAME meta the Stake
+     *  bridge builds). Pass a full `CurrencyConfig` — see `resolveCurrency`. */
+    currency?: CurrencyConfig;
+    language?: string;
+    mode: ShellMode;
+    /** Social-casino mode from initData (`config.socialMode`); swaps shell vocabulary. */
+    social?: boolean;
+    /** Stake-required disclaimer lines from initData (`config.disclaimerLines`); when
+     *  absent (non-stake/dev) no disclaimer section is rendered. */
+    disclaimerLines?: string[];
+    /** Jurisdiction flags from initData (`config.jurisdiction`). Restrict shell features — applied
+     *  OVER the author's features so a jurisdiction restriction always wins. */
+    jurisdiction?: JurisdictionRestrictions;
+    /** Bet ladder from `/wallet/authenticate` (`initData.config.betLevels`, major units). Stake ladders
+     *  are CURRENCY-SPECIFIC (us_/non_us_/social_), so this overrides the spec's static `betLevels` on a
+     *  Stake launch; falls back to the spec on dev/devBridge. */
+    betLevels?: number[];
+    /** Per-currency default bet from `/wallet/authenticate` (the bridge surfaces it as
+     *  `config.stake.defaultBetLevel`). Stake requires the selector to start here on every entry. */
+    defaultBet?: number;
+}
+/** The subset of Stake's jurisdiction flags the shell can enforce via `ShellFeatures`. */
+interface JurisdictionRestrictions {
+    /** No turbo at all → `features.turbo = 0`. */
+    disabledTurbo?: boolean;
+    /** Basic turbo allowed, but no super-turbo → cap `features.turbo` at 1. */
+    disabledSuperTurbo?: boolean;
+    /** No spacebar quick-spin → `features.spacebar = false`. */
+    disabledSpacebar?: boolean;
+    /** No autoplay → `features.autoplay = null`. */
+    disabledAutoplay?: boolean;
+    /** No buy-feature → `features.buyBonus = false`. */
+    disabledBuyFeature?: boolean;
+}
+/** Total stake for an action = bet × the action's cost multiplier (1 for a base spin; e.g. 100 for
+ *  a buy bonus). The host uses this to block a play the balance can't cover. */
+declare function stakeForAction(model: GameModel, action: string, bet: number): number;
+/** Pure: assemble a ShellConfig from the model + runtime context (currency/balance/language/mode). */
+declare function buildShellConfig(opts: SlotShellOptions, model: GameModel, runtime: ShellRuntime): ShellConfig;
+
+interface StakeIntegration {
+    /** The game's BookAdapter (or its module). modeMap + gameId come from the model. */
+    adapter: BookAdapter | AdapterModule;
+}
+/** One scene registered with the host: a key + its constructor. The list order matters — the
+ *  first scene that is eligible for the current launch mode is the start scene (unless an explicit
+ *  `startScene` overrides it). */
+interface SceneRegistration {
+    key: string;
+    scene: SceneConstructor;
+    /** Skip this scene as a START scene on a replay launch (e.g. an intro). It is still registered
+     *  (other scenes can `goto` it), it just isn't auto-started — the first non-skipped scene is. */
+    skipOnReplay?: boolean;
+}
+/** @deprecated alias kept for one release — use {@link SceneRegistration}. */
+type SceneEntry = SceneRegistration;
+/** Navigation injected into the start data of EVERY scene the host registers.
+ *  Any scene (intro, game, …) reads it from its `onEnter(data)` to navigate. */
+interface SceneNavData {
+    /** Switch to another registered scene by key. */
+    goto: (key: string, data?: unknown) => void;
+}
+interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinResultBase> {
+    model: GameModel;
+    /** REQUIRED: maps the raw play result into the game's typed result. The host calls it on every play. */
+    normalize: SlotResultNormalizer<T>;
+    /** ALL scenes the game uses, registered up front, in order. The first scene eligible for the
+     *  launch mode is the start scene — so a replay launch skips any leading `skipOnReplay` scene
+     *  (e.g. the intro) and starts directly on the game scene. */
+    scenes: SceneRegistration[];
+    /** Optional explicit start scene key. Defaults to the first scene eligible for the launch mode
+     *  (honoured only when that scene is itself eligible; otherwise the first eligible one wins). */
+    startScene?: string;
+    /** Start data passed to the start scene's `onEnter` (merged with the injected `goto`). */
+    startData?: unknown;
+    manifest: AssetManifest;
+    container?: HTMLElement | string;
+    design?: {
+        width: number;
+        height: number;
+    };
+    scaleMode?: ScaleMode;
+    orientation?: Orientation;
+    loading?: LoadingScreenConfig;
+    audio?: AudioConfig;
+    pixi?: Partial<ApplicationOptions>;
+    fonts?: string[];
+    textureDefaults?: boolean;
+    dev?: boolean;
+    stake?: StakeIntegration;
+    shell?: SlotShellOptions;
+    onFatalError?: (message: string) => void;
+}
+interface SlotGameHandle {
+    game: GameApplication;
+    stakeBridge: StakeBridge | null;
+    shell: GameShell | null;
+}
+
+/**
+ * One-call slot bootstrap: preboot → (optional Stake bridge) → GameApplication
+ * → register scene → start. Collapses the per-game main.ts boilerplate.
+ *
+ * Not unit-tested: GameApplication.init() drives Pixi, which hangs in headless
+ * environments. The pure helpers it sequences are unit-tested individually.
+ */
+declare function createSlotGame<T extends SlotSpinResultBase = SlotSpinResultBase>(opts: CreateSlotGameOptions<T>): Promise<SlotGameHandle>;
+
+/** Reverse the model's modeMap (Stake bet mode → SDK action key) for replay labelling/cost. */
+declare function resolveReplayBonusId(model: GameModel, stakeMode: string): string;
+
+/**
+ * Pick the scene to START with, given the registered scenes (in order) and the launch mode.
+ *
+ * Rules:
+ *  - On a replay launch, scenes flagged `skipOnReplay` are NOT eligible to start (they stay
+ *    registered for `goto`, they just aren't auto-started) — so a leading intro is skipped and
+ *    the game scene starts directly.
+ *  - An explicit `startScene` wins, but only if that scene is itself eligible; otherwise the first
+ *    eligible scene wins.
+ *  - Falls back to the first scene unconditionally if nothing is eligible (degenerate config).
+ */
+declare function resolveStartScene(scenes: SceneRegistration[], isReplay: boolean, explicitStart?: string): string;
+
+/** Everything a scene needs to render one result. The host builds it once per round. */
+interface RenderContext {
+    /** Bet for this round (major units). Stable for the whole round (a bonus is one round). */
+    bet: number;
+    /** Trigger action in the game's own vocabulary (gameSpec.actions keys): 'spin' | 'ante' |
+     *  'buy_bonus' | … Stable for the whole round. */
+    action: string;
+    /** Stake bet-mode of the round (model.spec.modeMap[action]): 'BASE' | 'ANTE' | 'BONUS' | …
+     *  Canonical per-round identifier of WHICH bonus/feature this is. Stable for the whole round. */
+    mode: string;
+    /** Currency-aware money formatter. win/totalWin get variable decimals (0.0041 stays 0.0041). */
+    formatAmount(value: number): string;
+    /** LIVE turbo level (0 = off, 1..3 = escalating speed), matching the shell's state.turbo. Read at
+     *  the moment of access (getter) so a mid-round toggle is reflected. */
+    readonly turbo: number;
+}
+/** The contract a slot scene implements. The HOST owns the play→present→ack→drain loop and calls
+ *  these; the scene only renders. The game never sees play/ack/roundId. */
+interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResultBase> {
+    /** Render ONE segment (a spin, or one free spin). All pacing/pauses/overlays live here
+     *  (await your own animations). The host calls this once per segment. */
+    present(result: T, ctx: RenderContext): Promise<void>;
+    /** Optional. Fires EXACTLY before the first free spin of a bonus (intro; spin counts in
+     *  trigger.freeSpins). */
+    onBonusEnter?(trigger: T, ctx: RenderContext): Promise<void>;
+    /** Optional. Fires after the last free spin of a bonus (summary; last.totalWin = bonus total). */
+    onBonusExit?(last: T, ctx: RenderContext): Promise<void>;
+}
+
+export { buildShellConfig, createSlotGame, resolveReplayBonusId, resolveStartScene, stakeForAction };
+export type { CreateSlotGameOptions, RenderContext, SceneEntry, SceneNavData, SceneRegistration, SlotGameHandle, SlotSceneController, SlotShellOptions, StakeIntegration };