@energy8platform/game-engine 0.1.0

package/dist/index.cjs.js

@@ -0,0 +1,3623 @@
+'use strict';
+
+var pixi_js = require('pixi.js');
+var gameSdk = require('@energy8platform/game-sdk');
+
+// ─── Scale Modes ───────────────────────────────────────────
+exports.ScaleMode = void 0;
+(function (ScaleMode) {
+    /** Fit inside container, maintain aspect ratio (letterbox/pillarbox) */
+    ScaleMode["FIT"] = "FIT";
+    /** Fill container, maintain aspect ratio (crop edges) */
+    ScaleMode["FILL"] = "FILL";
+    /** Stretch to fill (distorts) */
+    ScaleMode["STRETCH"] = "STRETCH";
+})(exports.ScaleMode || (exports.ScaleMode = {}));
+// ─── Orientation ───────────────────────────────────────────
+exports.Orientation = void 0;
+(function (Orientation) {
+    Orientation["LANDSCAPE"] = "landscape";
+    Orientation["PORTRAIT"] = "portrait";
+    Orientation["ANY"] = "any";
+})(exports.Orientation || (exports.Orientation = {}));
+// ─── Transition Types ──────────────────────────────────────
+exports.TransitionType = void 0;
+(function (TransitionType) {
+    TransitionType["NONE"] = "none";
+    TransitionType["FADE"] = "fade";
+    TransitionType["SLIDE_LEFT"] = "slide-left";
+    TransitionType["SLIDE_RIGHT"] = "slide-right";
+})(exports.TransitionType || (exports.TransitionType = {}));
+
+/**
+ * Minimal typed event emitter.
+ * Used internally by GameApplication, SceneManager, AudioManager, etc.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+class EventEmitter {
+    listeners = new Map();
+    on(event, handler) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(handler);
+        return this;
+    }
+    once(event, handler) {
+        const wrapper = (data) => {
+            this.off(event, wrapper);
+            handler(data);
+        };
+        return this.on(event, wrapper);
+    }
+    off(event, handler) {
+        this.listeners.get(event)?.delete(handler);
+        return this;
+    }
+    emit(event, data) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(data);
+            }
+        }
+    }
+    removeAllListeners(event) {
+        if (event) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+        }
+        return this;
+    }
+}
+
+/**
+ * Collection of easing functions for use with Tween and Timeline.
+ *
+ * All functions take a progress value t (0..1) and return the eased value.
+ */
+const Easing = {
+    linear: (t) => t,
+    easeInQuad: (t) => t * t,
+    easeOutQuad: (t) => t * (2 - t),
+    easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+    easeInCubic: (t) => t * t * t,
+    easeOutCubic: (t) => --t * t * t + 1,
+    easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,
+    easeInQuart: (t) => t * t * t * t,
+    easeOutQuart: (t) => 1 - --t * t * t * t,
+    easeInOutQuart: (t) => t < 0.5 ? 8 * t * t * t * t : 1 - 8 * --t * t * t * t,
+    easeInSine: (t) => 1 - Math.cos((t * Math.PI) / 2),
+    easeOutSine: (t) => Math.sin((t * Math.PI) / 2),
+    easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+    easeInExpo: (t) => (t === 0 ? 0 : Math.pow(2, 10 * t - 10)),
+    easeOutExpo: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+    easeInOutExpo: (t) => t === 0
+        ? 0
+        : t === 1
+            ? 1
+            : t < 0.5
+                ? Math.pow(2, 20 * t - 10) / 2
+                : (2 - Math.pow(2, -20 * t + 10)) / 2,
+    easeInBack: (t) => {
+        const c1 = 1.70158;
+        const c3 = c1 + 1;
+        return c3 * t * t * t - c1 * t * t;
+    },
+    easeOutBack: (t) => {
+        const c1 = 1.70158;
+        const c3 = c1 + 1;
+        return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+    },
+    easeInOutBack: (t) => {
+        const c1 = 1.70158;
+        const c2 = c1 * 1.525;
+        return t < 0.5
+            ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+            : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
+    },
+    easeOutBounce: (t) => {
+        const n1 = 7.5625;
+        const d1 = 2.75;
+        if (t < 1 / d1)
+            return n1 * t * t;
+        if (t < 2 / d1)
+            return n1 * (t -= 1.5 / d1) * t + 0.75;
+        if (t < 2.5 / d1)
+            return n1 * (t -= 2.25 / d1) * t + 0.9375;
+        return n1 * (t -= 2.625 / d1) * t + 0.984375;
+    },
+    easeInBounce: (t) => 1 - Easing.easeOutBounce(1 - t),
+    easeInOutBounce: (t) => t < 0.5
+        ? (1 - Easing.easeOutBounce(1 - 2 * t)) / 2
+        : (1 + Easing.easeOutBounce(2 * t - 1)) / 2,
+    easeOutElastic: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0
+            ? 0
+            : t === 1
+                ? 1
+                : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+    },
+    easeInElastic: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0
+            ? 0
+            : t === 1
+                ? 1
+                : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4);
+    },
+};
+
+/**
+ * Lightweight tween system integrated with PixiJS Ticker.
+ * Zero external dependencies — no GSAP required.
+ *
+ * All tweens return a Promise that resolves on completion.
+ *
+ * @example
+ * ```ts
+ * // Fade in a sprite
+ * await Tween.to(sprite, { alpha: 1, y: 100 }, 500, Easing.easeOutBack);
+ *
+ * // Move and wait
+ * await Tween.to(sprite, { x: 500 }, 300);
+ *
+ * // From a starting value
+ * await Tween.from(sprite, { scale: 0, alpha: 0 }, 400);
+ * ```
+ */
+class Tween {
+    static _tweens = [];
+    static _tickerAdded = false;
+    /**
+     * Animate properties from current values to target values.
+     *
+     * @param target - Object to animate (Sprite, Container, etc.)
+     * @param props - Target property values
+     * @param duration - Duration in milliseconds
+     * @param easing - Easing function (default: easeOutQuad)
+     * @param onUpdate - Progress callback (0..1)
+     */
+    static to(target, props, duration, easing, onUpdate) {
+        return new Promise((resolve) => {
+            // Capture starting values
+            const from = {};
+            for (const key of Object.keys(props)) {
+                from[key] = Tween.getProperty(target, key);
+            }
+            const tween = {
+                target,
+                from,
+                to: { ...props },
+                duration: Math.max(1, duration),
+                easing: easing ?? Easing.easeOutQuad,
+                elapsed: 0,
+                delay: 0,
+                resolve,
+                onUpdate,
+            };
+            Tween._tweens.push(tween);
+            Tween.ensureTicker();
+        });
+    }
+    /**
+     * Animate properties from given values to current values.
+     */
+    static from(target, props, duration, easing, onUpdate) {
+        // Capture current values as "to"
+        const to = {};
+        for (const key of Object.keys(props)) {
+            to[key] = Tween.getProperty(target, key);
+            Tween.setProperty(target, key, props[key]);
+        }
+        return Tween.to(target, to, duration, easing, onUpdate);
+    }
+    /**
+     * Animate from one set of values to another.
+     */
+    static fromTo(target, fromProps, toProps, duration, easing, onUpdate) {
+        // Set starting values
+        for (const key of Object.keys(fromProps)) {
+            Tween.setProperty(target, key, fromProps[key]);
+        }
+        return Tween.to(target, toProps, duration, easing, onUpdate);
+    }
+    /**
+     * Wait for a given duration (useful in timelines).
+     */
+    static delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Kill all tweens on a target.
+     */
+    static killTweensOf(target) {
+        Tween._tweens = Tween._tweens.filter((tw) => {
+            if (tw.target === target) {
+                tw.resolve();
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Kill all active tweens.
+     */
+    static killAll() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+    }
+    /** Number of active tweens */
+    static get activeTweens() {
+        return Tween._tweens.length;
+    }
+    // ─── Internal ──────────────────────────────────────────
+    static ensureTicker() {
+        if (Tween._tickerAdded)
+            return;
+        Tween._tickerAdded = true;
+        pixi_js.Ticker.shared.add(Tween.tick);
+    }
+    static tick = (ticker) => {
+        const dt = ticker.deltaMS;
+        const completed = [];
+        for (const tw of Tween._tweens) {
+            tw.elapsed += dt;
+            if (tw.elapsed < tw.delay)
+                continue;
+            const raw = Math.min((tw.elapsed - tw.delay) / tw.duration, 1);
+            const t = tw.easing(raw);
+            // Interpolate each property
+            for (const key of Object.keys(tw.to)) {
+                const start = tw.from[key];
+                const end = tw.to[key];
+                const value = start + (end - start) * t;
+                Tween.setProperty(tw.target, key, value);
+            }
+            tw.onUpdate?.(raw);
+            if (raw >= 1) {
+                completed.push(tw);
+            }
+        }
+        // Remove completed tweens
+        for (const tw of completed) {
+            const idx = Tween._tweens.indexOf(tw);
+            if (idx !== -1)
+                Tween._tweens.splice(idx, 1);
+            tw.resolve();
+        }
+        // Remove ticker when no active tweens
+        if (Tween._tweens.length === 0 && Tween._tickerAdded) {
+            pixi_js.Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    };
+    /**
+     * Get a potentially nested property (supports 'scale.x', 'position.y', etc.)
+     */
+    static getProperty(target, key) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj[parts[i]];
+        }
+        return obj[parts[parts.length - 1]] ?? 0;
+    }
+    /**
+     * Set a potentially nested property.
+     */
+    static setProperty(target, key, value) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj[parts[i]];
+        }
+        obj[parts[parts.length - 1]] = value;
+    }
+}
+
+/**
+ * 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');
+ * ```
+ */
+class SceneManager extends EventEmitter {
+    /** Root container that scenes are added to */
+    root;
+    registry = new Map();
+    stack = [];
+    _transitioning = false;
+    /** Current viewport dimensions — set by ViewportManager */
+    _width = 0;
+    _height = 0;
+    constructor(root) {
+        super();
+        if (root)
+            this.root = root;
+    }
+    /** @internal Set the root container (called by GameApplication after PixiJS init) */
+    setRoot(root) {
+        this.root = root;
+    }
+    /** Register a scene class by key */
+    register(key, ctor) {
+        this.registry.set(key, ctor);
+        return this;
+    }
+    /** Get the current (topmost) scene entry */
+    get current() {
+        return this.stack.length > 0 ? this.stack[this.stack.length - 1] : null;
+    }
+    /** Get the current scene key */
+    get currentKey() {
+        return this.current?.key ?? null;
+    }
+    /** Whether a scene transition is in progress */
+    get isTransitioning() {
+        return this._transitioning;
+    }
+    /**
+     * Navigate to a scene, replacing the entire stack.
+     */
+    async goto(key, data, transition) {
+        const prevKey = this.currentKey;
+        // Exit all current scenes
+        while (this.stack.length > 0) {
+            await this.popInternal(false);
+        }
+        // Enter new scene
+        await this.pushInternal(key, data, transition);
+        this.emit('change', { from: prevKey, to: key });
+    }
+    /**
+     * Push a scene onto the stack (the previous scene stays underneath).
+     * Useful for overlays, modals, pause screens.
+     */
+    async push(key, data, transition) {
+        const prevKey = this.currentKey;
+        await this.pushInternal(key, data, transition);
+        this.emit('change', { from: prevKey, to: key });
+    }
+    /**
+     * Pop the top scene from the stack.
+     */
+    async pop(transition) {
+        if (this.stack.length <= 1) {
+            console.warn('[SceneManager] Cannot pop the last scene');
+            return;
+        }
+        const prevKey = this.currentKey;
+        await this.popInternal(true, transition);
+        this.emit('change', { from: prevKey, to: this.currentKey });
+    }
+    /**
+     * Replace the top scene with a new one.
+     */
+    async replace(key, data, transition) {
+        const prevKey = this.currentKey;
+        await this.popInternal(false);
+        await this.pushInternal(key, data, transition);
+        this.emit('change', { from: prevKey, to: key });
+    }
+    /**
+     * Called every frame by GameApplication.
+     */
+    update(dt) {
+        // Update only the top scene
+        this.current?.scene.onUpdate?.(dt);
+    }
+    /**
+     * Called on viewport resize.
+     */
+    resize(width, height) {
+        this._width = width;
+        this._height = height;
+        // Notify all scenes in the stack
+        for (const entry of this.stack) {
+            entry.scene.onResize?.(width, height);
+        }
+    }
+    /**
+     * Destroy all scenes and clear the manager.
+     */
+    destroy() {
+        for (const entry of this.stack) {
+            entry.scene.onDestroy?.();
+            entry.scene.container.destroy({ children: true });
+        }
+        this.stack.length = 0;
+        this.registry.clear();
+        this.removeAllListeners();
+    }
+    // ─── Internal ──────────────────────────────────────────
+    createScene(key) {
+        const Ctor = this.registry.get(key);
+        if (!Ctor) {
+            throw new Error(`[SceneManager] Scene "${key}" is not registered`);
+        }
+        return new Ctor();
+    }
+    async pushInternal(key, data, transition) {
+        this._transitioning = true;
+        const scene = this.createScene(key);
+        this.root.addChild(scene.container);
+        // Set initial size
+        if (this._width && this._height) {
+            scene.onResize?.(this._width, this._height);
+        }
+        // Transition in
+        await this.transitionIn(scene.container, transition);
+        await scene.onEnter?.(data);
+        this.stack.push({ scene, key });
+        this._transitioning = false;
+    }
+    async popInternal(showTransition, transition) {
+        const entry = this.stack.pop();
+        if (!entry)
+            return;
+        this._transitioning = true;
+        await entry.scene.onExit?.();
+        if (showTransition) {
+            await this.transitionOut(entry.scene.container, transition);
+        }
+        entry.scene.onDestroy?.();
+        entry.scene.container.destroy({ children: true });
+        this._transitioning = false;
+    }
+    async transitionIn(container, config) {
+        const type = config?.type ?? exports.TransitionType.NONE;
+        const duration = config?.duration ?? 300;
+        if (type === exports.TransitionType.NONE || duration <= 0)
+            return;
+        if (type === exports.TransitionType.FADE) {
+            container.alpha = 0;
+            await Tween.to(container, { alpha: 1 }, duration, config?.easing);
+        }
+        else if (type === exports.TransitionType.SLIDE_LEFT) {
+            container.x = this._width;
+            await Tween.to(container, { x: 0 }, duration, config?.easing);
+        }
+        else if (type === exports.TransitionType.SLIDE_RIGHT) {
+            container.x = -this._width;
+            await Tween.to(container, { x: 0 }, duration, config?.easing);
+        }
+    }
+    async transitionOut(container, config) {
+        const type = config?.type ?? exports.TransitionType.FADE;
+        const duration = config?.duration ?? 300;
+        if (type === exports.TransitionType.NONE || duration <= 0)
+            return;
+        if (type === exports.TransitionType.FADE) {
+            await Tween.to(container, { alpha: 0 }, duration, config?.easing);
+        }
+        else if (type === exports.TransitionType.SLIDE_LEFT) {
+            await Tween.to(container, { x: -this._width }, duration, config?.easing);
+        }
+        else if (type === exports.TransitionType.SLIDE_RIGHT) {
+            await Tween.to(container, { x: this._width }, duration, config?.easing);
+        }
+    }
+}
+
+/**
+ * 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');
+ * ```
+ */
+class AssetManager {
+    _initialized = false;
+    _basePath;
+    _manifest;
+    _loadedBundles = new Set();
+    constructor(basePath = '', manifest) {
+        this._basePath = basePath;
+        this._manifest = manifest ?? null;
+    }
+    /** Whether the asset system has been initialized */
+    get initialized() {
+        return this._initialized;
+    }
+    /** Base path for all assets (usually from SDK's assetsUrl) */
+    get basePath() {
+        return this._basePath;
+    }
+    /** Set of loaded bundle names */
+    get loadedBundles() {
+        return this._loadedBundles;
+    }
+    /**
+     * Initialize the asset system.
+     * Must be called before loading any assets.
+     */
+    async init() {
+        if (this._initialized)
+            return;
+        await pixi_js.Assets.init({
+            basePath: this._basePath || undefined,
+            texturePreference: {
+                resolution: Math.min(window.devicePixelRatio, 2),
+                format: ['webp', 'png'],
+            },
+        });
+        // Register bundles from manifest
+        if (this._manifest) {
+            for (const bundle of this._manifest.bundles) {
+                pixi_js.Assets.addBundle(bundle.name, bundle.assets.map((a) => ({
+                    alias: a.alias,
+                    src: a.src,
+                    data: a.data,
+                })));
+            }
+        }
+        this._initialized = true;
+    }
+    /**
+     * 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
+     */
+    async loadBundle(name, onProgress) {
+        this.ensureInitialized();
+        const result = await pixi_js.Assets.loadBundle(name, onProgress);
+        this._loadedBundles.add(name);
+        return result;
+    }
+    /**
+     * Load multiple bundles simultaneously.
+     * Progress is aggregated across all bundles.
+     *
+     * @param names - Bundle names
+     * @param onProgress - Progress callback (0..1)
+     */
+    async loadBundles(names, onProgress) {
+        this.ensureInitialized();
+        const result = await pixi_js.Assets.loadBundle(names, onProgress);
+        for (const name of names) {
+            this._loadedBundles.add(name);
+        }
+        return result;
+    }
+    /**
+     * Load individual assets by URL or alias.
+     *
+     * @param urls - Asset URLs or aliases
+     * @param onProgress - Progress callback (0..1)
+     */
+    async load(urls, onProgress) {
+        this.ensureInitialized();
+        return pixi_js.Assets.load(urls, onProgress);
+    }
+    /**
+     * Get a loaded asset synchronously from cache.
+     *
+     * @param alias - Asset alias
+     * @throws if not loaded
+     */
+    get(alias) {
+        return pixi_js.Assets.get(alias);
+    }
+    /**
+     * Unload a bundle to free memory.
+     */
+    async unloadBundle(name) {
+        await pixi_js.Assets.unloadBundle(name);
+        this._loadedBundles.delete(name);
+    }
+    /**
+     * Start background loading a bundle (low-priority preload).
+     * Useful for loading bonus round assets while player is in base game.
+     */
+    async backgroundLoad(name) {
+        this.ensureInitialized();
+        await pixi_js.Assets.backgroundLoadBundle(name);
+    }
+    /**
+     * Get all bundle names from the manifest.
+     */
+    getBundleNames() {
+        return this._manifest?.bundles.map((b) => b.name) ?? [];
+    }
+    /**
+     * Check if a bundle is loaded.
+     */
+    isBundleLoaded(name) {
+        return this._loadedBundles.has(name);
+    }
+    ensureInitialized() {
+        if (!this._initialized) {
+            throw new Error('[AssetManager] Not initialized. Call init() first.');
+        }
+    }
+}
+
+/**
+ * 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');
+ * ```
+ */
+class AudioManager {
+    _soundModule = null;
+    _initialized = false;
+    _globalMuted = false;
+    _persist;
+    _storageKey;
+    _categories;
+    _currentMusic = null;
+    _unlocked = false;
+    _unlockHandler = null;
+    constructor(config) {
+        this._persist = config?.persist ?? true;
+        this._storageKey = config?.storageKey ?? 'ge_audio';
+        this._categories = {
+            music: { volume: config?.music ?? 0.7, muted: false },
+            sfx: { volume: config?.sfx ?? 1.0, muted: false },
+            ui: { volume: config?.ui ?? 0.8, muted: false },
+            ambient: { volume: config?.ambient ?? 0.5, muted: false },
+        };
+        // Restore persisted state
+        if (this._persist) {
+            this.restoreState();
+        }
+    }
+    /** Whether the audio system is initialized */
+    get initialized() {
+        return this._initialized;
+    }
+    /** Whether audio is globally muted */
+    get muted() {
+        return this._globalMuted;
+    }
+    /**
+     * Initialize the audio system.
+     * Dynamically imports @pixi/sound to keep it optional.
+     */
+    async init() {
+        if (this._initialized)
+            return;
+        try {
+            this._soundModule = await import('@pixi/sound');
+            this._initialized = true;
+            this.applyVolumes();
+            this.setupMobileUnlock();
+        }
+        catch {
+            console.warn('[AudioManager] @pixi/sound not available. Audio disabled.');
+            this._initialized = false;
+        }
+    }
+    /**
+     * 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, category = 'sfx', options) {
+        if (!this._initialized || !this._soundModule)
+            return;
+        if (this._globalMuted || this._categories[category].muted)
+            return;
+        const { sound } = this._soundModule;
+        const vol = (options?.volume ?? 1) * this._categories[category].volume;
+        try {
+            sound.play(alias, {
+                volume: vol,
+                loop: options?.loop ?? false,
+                speed: options?.speed ?? 1,
+            });
+        }
+        catch (e) {
+            console.warn(`[AudioManager] Failed to play "${alias}":`, e);
+        }
+    }
+    /**
+     * Play background music with optional crossfade.
+     *
+     * @param alias - Music alias
+     * @param fadeDuration - Crossfade duration in ms (default: 500)
+     */
+    playMusic(alias, fadeDuration = 500) {
+        if (!this._initialized || !this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        // Stop current music
+        if (this._currentMusic) {
+            try {
+                sound.stop(this._currentMusic);
+            }
+            catch {
+                // ignore
+            }
+        }
+        this._currentMusic = alias;
+        if (this._globalMuted || this._categories.music.muted)
+            return;
+        try {
+            sound.play(alias, {
+                volume: this._categories.music.volume,
+                loop: true,
+            });
+        }
+        catch (e) {
+            console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
+        }
+    }
+    /**
+     * Stop current music.
+     */
+    stopMusic() {
+        if (!this._initialized || !this._soundModule || !this._currentMusic)
+            return;
+        const { sound } = this._soundModule;
+        try {
+            sound.stop(this._currentMusic);
+        }
+        catch {
+            // ignore
+        }
+        this._currentMusic = null;
+    }
+    /**
+     * Stop all sounds.
+     */
+    stopAll() {
+        if (!this._initialized || !this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        sound.stopAll();
+        this._currentMusic = null;
+    }
+    /**
+     * Set volume for a category.
+     */
+    setVolume(category, volume) {
+        this._categories[category].volume = Math.max(0, Math.min(1, volume));
+        this.applyVolumes();
+        this.saveState();
+    }
+    /**
+     * Get volume for a category.
+     */
+    getVolume(category) {
+        return this._categories[category].volume;
+    }
+    /**
+     * Mute a specific category.
+     */
+    muteCategory(category) {
+        this._categories[category].muted = true;
+        this.applyVolumes();
+        this.saveState();
+    }
+    /**
+     * Unmute a specific category.
+     */
+    unmuteCategory(category) {
+        this._categories[category].muted = false;
+        this.applyVolumes();
+        this.saveState();
+    }
+    /**
+     * Toggle mute for a category.
+     */
+    toggleCategory(category) {
+        this._categories[category].muted = !this._categories[category].muted;
+        this.applyVolumes();
+        this.saveState();
+        return this._categories[category].muted;
+    }
+    /**
+     * Mute all audio globally.
+     */
+    muteAll() {
+        this._globalMuted = true;
+        if (this._soundModule) {
+            this._soundModule.sound.muteAll();
+        }
+        this.saveState();
+    }
+    /**
+     * Unmute all audio globally.
+     */
+    unmuteAll() {
+        this._globalMuted = false;
+        if (this._soundModule) {
+            this._soundModule.sound.unmuteAll();
+        }
+        this.saveState();
+    }
+    /**
+     * Toggle global mute.
+     */
+    toggleMute() {
+        if (this._globalMuted) {
+            this.unmuteAll();
+        }
+        else {
+            this.muteAll();
+        }
+        return this._globalMuted;
+    }
+    /**
+     * Duck music volume (e.g., during big win presentation).
+     *
+     * @param factor - Volume multiplier (0..1), e.g. 0.3 = 30% of normal
+     */
+    duckMusic(factor) {
+        if (!this._initialized || !this._soundModule || !this._currentMusic)
+            return;
+        const { sound } = this._soundModule;
+        const vol = this._categories.music.volume * factor;
+        try {
+            sound.volume(this._currentMusic, vol);
+        }
+        catch {
+            // ignore
+        }
+    }
+    /**
+     * Restore music to normal volume after ducking.
+     */
+    unduckMusic() {
+        if (!this._initialized || !this._soundModule || !this._currentMusic)
+            return;
+        const { sound } = this._soundModule;
+        try {
+            sound.volume(this._currentMusic, this._categories.music.volume);
+        }
+        catch {
+            // ignore
+        }
+    }
+    /**
+     * Destroy the audio manager and free resources.
+     */
+    destroy() {
+        this.stopAll();
+        this.removeMobileUnlock();
+        if (this._soundModule) {
+            this._soundModule.sound.removeAll();
+        }
+        this._initialized = false;
+    }
+    // ─── Private ───────────────────────────────────────────
+    applyVolumes() {
+        if (!this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        sound.volumeAll = this._globalMuted ? 0 : 1;
+    }
+    setupMobileUnlock() {
+        if (this._unlocked)
+            return;
+        this._unlockHandler = () => {
+            if (!this._soundModule)
+                return;
+            const { sound } = this._soundModule;
+            // Resume WebAudio context
+            if (sound.context?.audioContext?.state === 'suspended') {
+                sound.context.audioContext.resume();
+            }
+            this._unlocked = true;
+            this.removeMobileUnlock();
+        };
+        const events = ['touchstart', 'mousedown', 'pointerdown', 'keydown'];
+        for (const event of events) {
+            document.addEventListener(event, this._unlockHandler, { once: true });
+        }
+    }
+    removeMobileUnlock() {
+        if (!this._unlockHandler)
+            return;
+        const events = ['touchstart', 'mousedown', 'pointerdown', 'keydown'];
+        for (const event of events) {
+            document.removeEventListener(event, this._unlockHandler);
+        }
+        this._unlockHandler = null;
+    }
+    saveState() {
+        if (!this._persist)
+            return;
+        try {
+            const state = {
+                globalMuted: this._globalMuted,
+                categories: this._categories,
+            };
+            localStorage.setItem(this._storageKey, JSON.stringify(state));
+        }
+        catch {
+            // localStorage may not be available
+        }
+    }
+    restoreState() {
+        try {
+            const raw = localStorage.getItem(this._storageKey);
+            if (!raw)
+                return;
+            const state = JSON.parse(raw);
+            if (typeof state.globalMuted === 'boolean') {
+                this._globalMuted = state.globalMuted;
+            }
+            if (state.categories) {
+                for (const key of ['music', 'sfx', 'ui', 'ambient']) {
+                    if (state.categories[key]) {
+                        this._categories[key] = {
+                            volume: state.categories[key].volume ?? this._categories[key].volume,
+                            muted: state.categories[key].muted ?? false,
+                        };
+                    }
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+
+/**
+ * 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`);
+ * });
+ * ```
+ */
+class ViewportManager extends EventEmitter {
+    _app;
+    _container;
+    _config;
+    _resizeObserver = null;
+    _currentOrientation = exports.Orientation.LANDSCAPE;
+    _currentWidth = 0;
+    _currentHeight = 0;
+    _currentScale = 1;
+    _destroyed = false;
+    _resizeTimeout = null;
+    constructor(app, container, config) {
+        super();
+        this._app = app;
+        this._container = container;
+        this._config = config;
+        this.setupObserver();
+    }
+    /** Current canvas width in game units */
+    get width() {
+        return this._currentWidth;
+    }
+    /** Current canvas height in game units */
+    get height() {
+        return this._currentHeight;
+    }
+    /** Current scale factor */
+    get scale() {
+        return this._currentScale;
+    }
+    /** Current orientation */
+    get orientation() {
+        return this._currentOrientation;
+    }
+    /** Design reference width */
+    get designWidth() {
+        return this._config.designWidth;
+    }
+    /** Design reference height */
+    get designHeight() {
+        return this._config.designHeight;
+    }
+    /**
+     * Force a resize calculation. Called automatically on container size change.
+     */
+    refresh() {
+        if (this._destroyed)
+            return;
+        const containerWidth = this._container.clientWidth || window.innerWidth;
+        const containerHeight = this._container.clientHeight || window.innerHeight;
+        if (containerWidth === 0 || containerHeight === 0)
+            return;
+        const { designWidth, designHeight, scaleMode } = this._config;
+        const designRatio = designWidth / designHeight;
+        const containerRatio = containerWidth / containerHeight;
+        let gameWidth;
+        let gameHeight;
+        let scale;
+        switch (scaleMode) {
+            case exports.ScaleMode.FIT: {
+                if (containerRatio > designRatio) {
+                    // Container is wider → pillarbox
+                    scale = containerHeight / designHeight;
+                    gameWidth = designWidth;
+                    gameHeight = designHeight;
+                }
+                else {
+                    // Container is taller → letterbox
+                    scale = containerWidth / designWidth;
+                    gameWidth = designWidth;
+                    gameHeight = designHeight;
+                }
+                break;
+            }
+            case exports.ScaleMode.FILL: {
+                if (containerRatio > designRatio) {
+                    // Container is wider → crop top/bottom
+                    scale = containerWidth / designWidth;
+                }
+                else {
+                    // Container is taller → crop left/right
+                    scale = containerHeight / designHeight;
+                }
+                gameWidth = containerWidth / scale;
+                gameHeight = containerHeight / scale;
+                break;
+            }
+            case exports.ScaleMode.STRETCH: {
+                gameWidth = designWidth;
+                gameHeight = designHeight;
+                scale = 1; // stretch is handled by CSS
+                break;
+            }
+            default:
+                gameWidth = designWidth;
+                gameHeight = designHeight;
+                scale = 1;
+        }
+        // Resize the renderer
+        this._app.renderer.resize(Math.round(containerWidth), Math.round(containerHeight));
+        // Scale the stage
+        const stageScale = scaleMode === exports.ScaleMode.STRETCH
+            ? Math.min(containerWidth / designWidth, containerHeight / designHeight)
+            : scale;
+        this._app.stage.scale.set(stageScale);
+        // Center the stage for FIT mode
+        if (scaleMode === exports.ScaleMode.FIT) {
+            this._app.stage.x = Math.round((containerWidth - designWidth * stageScale) / 2);
+            this._app.stage.y = Math.round((containerHeight - designHeight * stageScale) / 2);
+        }
+        else if (scaleMode === exports.ScaleMode.FILL) {
+            this._app.stage.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
+            this._app.stage.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
+        }
+        else {
+            this._app.stage.x = 0;
+            this._app.stage.y = 0;
+        }
+        this._currentWidth = gameWidth;
+        this._currentHeight = gameHeight;
+        this._currentScale = stageScale;
+        // Check orientation
+        const newOrientation = containerWidth >= containerHeight ? exports.Orientation.LANDSCAPE : exports.Orientation.PORTRAIT;
+        if (newOrientation !== this._currentOrientation) {
+            this._currentOrientation = newOrientation;
+            this.emit('orientationChange', newOrientation);
+        }
+        this.emit('resize', {
+            width: gameWidth,
+            height: gameHeight,
+            scale: stageScale,
+        });
+    }
+    /**
+     * Destroy the viewport manager.
+     */
+    destroy() {
+        this._destroyed = true;
+        this._resizeObserver?.disconnect();
+        this._resizeObserver = null;
+        if (this._resizeTimeout !== null) {
+            clearTimeout(this._resizeTimeout);
+        }
+        this.removeAllListeners();
+    }
+    // ─── Private ───────────────────────────────────────────
+    setupObserver() {
+        if (typeof ResizeObserver !== 'undefined') {
+            this._resizeObserver = new ResizeObserver(() => {
+                this.debouncedRefresh();
+            });
+            this._resizeObserver.observe(this._container);
+        }
+        else {
+            // Fallback for older browsers
+            window.addEventListener('resize', this.onWindowResize);
+        }
+    }
+    onWindowResize = () => {
+        this.debouncedRefresh();
+    };
+    debouncedRefresh() {
+        if (this._resizeTimeout !== null) {
+            clearTimeout(this._resizeTimeout);
+        }
+        this._resizeTimeout = window.setTimeout(() => {
+            this.refresh();
+            this._resizeTimeout = null;
+        }, 16); // ~1 frame
+    }
+}
+
+/**
+ * Base class for all scenes.
+ * Provides a root PixiJS Container and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * class MenuScene extends Scene {
+ *   async onEnter() {
+ *     const bg = Sprite.from('menu-bg');
+ *     this.container.addChild(bg);
+ *   }
+ *
+ *   onUpdate(dt: number) {
+ *     // per-frame logic
+ *   }
+ *
+ *   onResize(width: number, height: number) {
+ *     // reposition UI
+ *   }
+ * }
+ * ```
+ */
+class Scene {
+    container;
+    constructor() {
+        this.container = new pixi_js.Container();
+        this.container.label = this.constructor.name;
+    }
+}
+
+/**
+ * Inline SVG logo with a loader bar (clip-animated for progress).
+ * The clipPath rect width is set to 0 initially, expanded as loading progresses.
+ */
+function buildLogoSVG() {
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none" style="width:100%;height:auto;">
+  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#ls0)"/>
+  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#ls1)"/>
+  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#ls2)"/>
+  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#ls3)"/>
+  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#ls4)"/>
+  <clipPath id="ge-canvas-loader-clip">
+    <rect id="ge-loader-rect" x="37" y="148" width="0" height="20"/>
+  </clipPath>
+  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#ls5)" clip-path="url(#ge-canvas-loader-clip)"/>
+  <text id="ge-loader-pct" x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.7)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5">0%</text>
+  <defs>
+    <linearGradient id="ls0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+    <linearGradient id="ls5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+  </defs>
+</svg>`;
+}
+/** Max width of the loader bar in SVG units */
+const LOADER_BAR_MAX_WIDTH = 174;
+/**
+ * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
+ *
+ * Renders as an HTML overlay on top of the canvas for crisp SVG quality.
+ * The loader bar fill width is driven by asset loading progress.
+ */
+class LoadingScene extends Scene {
+    _engine;
+    _targetScene;
+    _targetData;
+    _config;
+    // HTML overlay
+    _overlay = null;
+    _loaderRect = null;
+    _percentEl = null;
+    _tapToStartEl = null;
+    // State
+    _displayedProgress = 0;
+    _targetProgress = 0;
+    _loadingComplete = false;
+    _startTime = 0;
+    async onEnter(data) {
+        const { engine, targetScene, targetData } = data;
+        this._engine = engine;
+        this._targetScene = targetScene;
+        this._targetData = targetData;
+        this._config = engine.config.loading ?? {};
+        this._startTime = Date.now();
+        // Create the HTML overlay with the SVG logo
+        this.createOverlay();
+        // Initialize asset manager
+        await this._engine.assets.init();
+        // Initialize audio manager
+        await this._engine.audio.init();
+        // Phase 1: Load preload bundle
+        const bundles = this._engine.assets.getBundleNames();
+        const hasPreload = bundles.includes('preload');
+        if (hasPreload) {
+            const preloadAssets = this._engine.config.manifest?.bundles?.find((b) => b.name === 'preload')?.assets;
+            if (preloadAssets && preloadAssets.length > 0) {
+                await this._engine.assets.loadBundle('preload', (p) => {
+                    this._targetProgress = p * 0.15;
+                });
+            }
+            else {
+                this._targetProgress = 0.15;
+            }
+        }
+        // Phase 2: Load remaining bundles
+        const remainingBundles = bundles.filter((b) => b !== 'preload' && !this._engine.assets.isBundleLoaded(b));
+        if (remainingBundles.length > 0) {
+            const hasAssets = remainingBundles.some((name) => {
+                const bundle = this._engine.config.manifest?.bundles?.find((b) => b.name === name);
+                return bundle?.assets && bundle.assets.length > 0;
+            });
+            if (hasAssets) {
+                await this._engine.assets.loadBundles(remainingBundles, (p) => {
+                    this._targetProgress = 0.15 + p * 0.85;
+                });
+            }
+        }
+        this._targetProgress = 1;
+        this._loadingComplete = true;
+        // Enforce minimum display time: spread the remaining progress fill
+        // over the remaining time so the bar fills smoothly, not abruptly
+        const minTime = this._config.minDisplayTime ?? 1500;
+        const elapsed = Date.now() - this._startTime;
+        const remaining = Math.max(0, minTime - elapsed);
+        if (remaining > 0) {
+            // Distribute fill animation over the remaining time
+            await this.animateProgressTo(1, remaining);
+        }
+        // Final snap to 100%
+        this._displayedProgress = 1;
+        this.updateLoaderBar(1);
+        // Show "Tap to Start" or transition directly
+        if (this._config.tapToStart !== false) {
+            await this.showTapToStart();
+        }
+        else {
+            await this.transitionToGame();
+        }
+    }
+    onUpdate(dt) {
+        // Smooth progress bar fill via HTML (during active loading)
+        if (!this._loadingComplete && this._displayedProgress < this._targetProgress) {
+            this._displayedProgress = Math.min(this._displayedProgress + dt * 1.5, this._targetProgress);
+            this.updateLoaderBar(this._displayedProgress);
+        }
+    }
+    onResize(_width, _height) {
+        // Overlay is CSS-based, auto-resizes
+    }
+    onDestroy() {
+        this.removeOverlay();
+    }
+    // ─── HTML Overlay ──────────────────────────────────────
+    createOverlay() {
+        const bgColor = typeof this._config.backgroundColor === 'string'
+            ? this._config.backgroundColor
+            : typeof this._config.backgroundColor === 'number'
+                ? `#${this._config.backgroundColor.toString(16).padStart(6, '0')}`
+                : '#0a0a1a';
+        const bgGradient = this._config.backgroundGradient ??
+            `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
+        this._overlay = document.createElement('div');
+        this._overlay.id = '__ge-loading-overlay__';
+        this._overlay.innerHTML = `
+      <div class="ge-loading-content">
+        ${buildLogoSVG()}
+      </div>
+    `;
+        const style = document.createElement('style');
+        style.id = '__ge-loading-style__';
+        style.textContent = `
+      #__ge-loading-overlay__ {
+        position: absolute;
+        top: 0; left: 0;
+        width: 100%; height: 100%;
+        background: ${bgGradient};
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 9999;
+        transition: opacity 0.5s ease-out;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      }
+      #__ge-loading-overlay__.ge-fade-out {
+        opacity: 0;
+        pointer-events: none;
+      }
+      .ge-loading-content {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        width: 75%;
+        max-width: 650px;
+      }
+      .ge-loading-content svg {
+        filter: drop-shadow(0 0 40px rgba(121, 57, 194, 0.5));
+        cursor: default;
+      }
+
+      .ge-svg-pulse {
+        animation: ge-tap-pulse 1.2s ease-in-out infinite;
+      }
+      @keyframes ge-tap-pulse {
+        0%, 100% { opacity: 0.5; }
+        50% { opacity: 1; }
+      }
+    `;
+        // Get the container that holds the canvas
+        const container = this._engine.app?.canvas?.parentElement;
+        if (container) {
+            container.style.position = container.style.position || 'relative';
+            container.appendChild(style);
+            container.appendChild(this._overlay);
+        }
+        // Cache the SVG loader rect for progress updates
+        this._loaderRect = this._overlay.querySelector('#ge-loader-rect');
+        this._percentEl = this._overlay.querySelector('#ge-loader-pct');
+    }
+    removeOverlay() {
+        this._overlay?.remove();
+        document.getElementById('__ge-loading-style__')?.remove();
+        this._overlay = null;
+        this._loaderRect = null;
+        this._percentEl = null;
+        this._tapToStartEl = null;
+    }
+    // ─── Progress ──────────────────────────────────────────
+    updateLoaderBar(progress) {
+        if (this._loaderRect) {
+            this._loaderRect.setAttribute('width', String(LOADER_BAR_MAX_WIDTH * progress));
+        }
+        if (this._percentEl) {
+            const pct = Math.round(progress * 100);
+            this._percentEl.textContent = `${pct}%`;
+        }
+    }
+    /**
+     * Smoothly animate the displayed progress from its current value to `target`
+     * over `durationMs` using an easeOutCubic curve.
+     */
+    async animateProgressTo(target, durationMs) {
+        const startVal = this._displayedProgress;
+        const delta = target - startVal;
+        if (delta <= 0 || durationMs <= 0)
+            return;
+        const startTime = Date.now();
+        return new Promise((resolve) => {
+            const tick = () => {
+                const elapsed = Date.now() - startTime;
+                const t = Math.min(elapsed / durationMs, 1);
+                // easeOutCubic for a natural deceleration feel
+                const eased = 1 - Math.pow(1 - t, 3);
+                this._displayedProgress = startVal + delta * eased;
+                this.updateLoaderBar(this._displayedProgress);
+                if (t < 1) {
+                    requestAnimationFrame(tick);
+                }
+                else {
+                    resolve();
+                }
+            };
+            requestAnimationFrame(tick);
+        });
+    }
+    // ─── Tap to Start ─────────────────────────────────────
+    async showTapToStart() {
+        const tapText = this._config.tapToStartText ?? 'TAP TO START';
+        // Reuse the same SVG text element — replace percentage with tap text
+        if (this._percentEl) {
+            const el = this._percentEl;
+            el.textContent = tapText;
+            el.setAttribute('fill', '#ffffff');
+            el.classList.add('ge-svg-pulse');
+            this._tapToStartEl = el;
+        }
+        // Make overlay clickable
+        if (this._overlay) {
+            this._overlay.style.cursor = 'pointer';
+        }
+        // Wait for tap
+        return new Promise((resolve) => {
+            const handler = async () => {
+                this._overlay?.removeEventListener('click', handler);
+                await this.transitionToGame();
+                resolve();
+            };
+            // Listen on the full overlay for easier mobile tap
+            this._overlay?.addEventListener('click', handler);
+        });
+    }
+    // ─── Transition ────────────────────────────────────────
+    async transitionToGame() {
+        // Fade out the HTML overlay
+        if (this._overlay) {
+            this._overlay.classList.add('ge-fade-out');
+            await new Promise((resolve) => {
+                this._overlay.addEventListener('transitionend', () => resolve(), { once: true });
+                // Safety timeout
+                setTimeout(resolve, 600);
+            });
+        }
+        // Remove overlay
+        this.removeOverlay();
+        // Navigate to the target scene
+        await this._engine.scenes.goto(this._targetScene, this._targetData);
+    }
+}
+
+const PRELOADER_ID = '__ge-css-preloader__';
+/**
+ * Inline SVG logo with animated loader bar.
+ * The `#loader` path acts as the progress fill — animated via clipPath.
+ */
+const LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none" class="ge-logo-svg">
+  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#pl0)"/>
+  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#pl1)"/>
+  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#pl2)"/>
+  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#pl3)"/>
+  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#pl4)"/>
+  <!-- Loader fill with clip for progress animation -->
+  <clipPath id="ge-loader-clip">
+    <rect x="37" y="148" width="0" height="20" class="ge-clip-rect"/>
+  </clipPath>
+  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#pl5)" clip-path="url(#ge-loader-clip)"/>
+  <text x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.6)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5" class="ge-preloader-svg-text">Loading...</text>
+  <defs>
+    <linearGradient id="pl0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+    <linearGradient id="pl5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+  </defs>
+</svg>`;
+/**
+ * Creates a lightweight CSS-only preloader that appears instantly,
+ * BEFORE PixiJS/WebGL is initialized.
+ *
+ * Displays the Energy8 logo SVG with an animated loader bar.
+ */
+function createCSSPreloader(container, config) {
+    if (document.getElementById(PRELOADER_ID))
+        return;
+    const bgColor = typeof config?.backgroundColor === 'string'
+        ? config.backgroundColor
+        : typeof config?.backgroundColor === 'number'
+            ? `#${config.backgroundColor.toString(16).padStart(6, '0')}`
+            : '#0a0a1a';
+    const bgGradient = config?.backgroundGradient ?? `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
+    const customHTML = config?.cssPreloaderHTML ?? '';
+    const el = document.createElement('div');
+    el.id = PRELOADER_ID;
+    el.innerHTML = customHTML || `
+    <div class="ge-preloader-content">
+      ${LOGO_SVG}
+    </div>
+  `;
+    const style = document.createElement('style');
+    style.textContent = `
+    #${PRELOADER_ID} {
+      position: absolute;
+      top: 0; left: 0;
+      width: 100%; height: 100%;
+      background: ${bgGradient};
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 10000;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      transition: opacity 0.4s ease-out;
+    }
+
+    #${PRELOADER_ID}.ge-preloader-hidden {
+      opacity: 0;
+      pointer-events: none;
+    }
+
+    .ge-preloader-content {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      width: 80%;
+      max-width: 700px;
+    }
+
+    .ge-logo-svg {
+      width: 100%;
+      height: auto;
+      filter: drop-shadow(0 0 30px rgba(121, 57, 194, 0.4));
+    }
+
+    /* Animate the loader clip-rect to shimmer while waiting */
+    .ge-clip-rect {
+      animation: ge-loader-fill 2s ease-in-out infinite;
+    }
+
+    @keyframes ge-loader-fill {
+      0%   { width: 0; }
+      50%  { width: 174; }
+      100% { width: 0; }
+    }
+
+    /* Animate the SVG text opacity */
+    .ge-preloader-svg-text {
+      animation: ge-pulse 1.5s ease-in-out infinite;
+    }
+
+    @keyframes ge-pulse {
+      0%, 100% { opacity: 0.4; }
+      50% { opacity: 1; }
+    }
+  `;
+    container.style.position = container.style.position || 'relative';
+    container.appendChild(style);
+    container.appendChild(el);
+}
+/**
+ * Remove the CSS preloader with a smooth fade-out transition.
+ */
+function removeCSSPreloader(container) {
+    const el = document.getElementById(PRELOADER_ID);
+    if (!el)
+        return;
+    el.classList.add('ge-preloader-hidden');
+    // Remove after transition
+    el.addEventListener('transitionend', () => {
+        el.remove();
+        // Also remove the style element
+        const styles = container.querySelectorAll('style');
+        for (const style of styles) {
+            if (style.textContent?.includes(PRELOADER_ID)) {
+                style.remove();
+            }
+        }
+    });
+}
+
+/**
+ * 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');
+ * ```
+ */
+class GameApplication extends EventEmitter {
+    // ─── Public references ──────────────────────────────────
+    /** PixiJS Application instance */
+    app;
+    /** Scene manager */
+    scenes;
+    /** Asset manager */
+    assets;
+    /** Audio manager */
+    audio;
+    /** Viewport manager */
+    viewport;
+    /** SDK instance (null in offline mode) */
+    sdk = null;
+    /** Data received from SDK initialization */
+    initData = null;
+    /** Configuration */
+    config;
+    // ─── Private state ──────────────────────────────────────
+    _running = false;
+    _destroyed = false;
+    _container = null;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            designWidth: 1920,
+            designHeight: 1080,
+            scaleMode: exports.ScaleMode.FIT,
+            orientation: exports.Orientation.ANY,
+            debug: false,
+            ...config,
+        };
+        // Create SceneManager early so scenes can be registered before start()
+        this.scenes = new SceneManager();
+    }
+    // ─── Public getters ─────────────────────────────────────
+    /** Current game config from SDK (or null in offline mode) */
+    get gameConfig() {
+        return this.initData?.config ?? null;
+    }
+    /** Current session data */
+    get session() {
+        return this.initData?.session ?? null;
+    }
+    /** Current balance */
+    get balance() {
+        return this.sdk?.balance ?? 0;
+    }
+    /** Current currency */
+    get currency() {
+        return this.sdk?.currency ?? 'USD';
+    }
+    /** Whether the engine is running */
+    get isRunning() {
+        return this._running;
+    }
+    // ─── Lifecycle ──────────────────────────────────────────
+    /**
+     * 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
+     */
+    async start(firstScene, sceneData) {
+        if (this._running) {
+            console.warn('[GameEngine] Already running');
+            return;
+        }
+        try {
+            // 1. Resolve container element
+            this._container = this.resolveContainer();
+            // 2. Show CSS preloader immediately (before PixiJS)
+            createCSSPreloader(this._container, this.config.loading);
+            // 3. Initialize PixiJS
+            await this.initPixi();
+            // 4. Initialize SDK (if enabled)
+            await this.initSDK();
+            // 5. Merge design dimensions from SDK config
+            this.applySDKConfig();
+            // 6. Initialize sub-systems
+            this.initSubSystems();
+            this.emit('initialized', undefined);
+            // 7. Remove CSS preloader, show Canvas loading screen
+            removeCSSPreloader(this._container);
+            // 8. Load assets with loading screen
+            await this.loadAssets(firstScene, sceneData);
+            // 9. Start the game loop
+            this._running = true;
+            this.emit('started', undefined);
+        }
+        catch (err) {
+            console.error('[GameEngine] Failed to start:', err);
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+    }
+    /**
+     * Destroy the engine and free all resources.
+     */
+    destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        this._running = false;
+        this.scenes?.destroy();
+        this.audio?.destroy();
+        this.viewport?.destroy();
+        this.sdk?.destroy();
+        this.app?.destroy(true, { children: true, texture: true });
+        this.removeAllListeners();
+        this.emit('destroyed', undefined);
+    }
+    // ─── Private initialization steps ──────────────────────
+    resolveContainer() {
+        if (typeof this.config.container === 'string') {
+            const el = document.querySelector(this.config.container);
+            if (!el)
+                throw new Error(`[GameEngine] Container "${this.config.container}" not found`);
+            return el;
+        }
+        return this.config.container ?? document.body;
+    }
+    async initPixi() {
+        this.app = new pixi_js.Application();
+        const pixiOpts = {
+            background: typeof this.config.loading?.backgroundColor === 'number'
+                ? this.config.loading.backgroundColor
+                : 0x000000,
+            antialias: true,
+            resolution: Math.min(window.devicePixelRatio, 2),
+            autoDensity: true,
+            ...this.config.pixi,
+        };
+        await this.app.init(pixiOpts);
+        // Append canvas to container
+        this._container.appendChild(this.app.canvas);
+        // Set canvas style
+        this.app.canvas.style.display = 'block';
+        this.app.canvas.style.width = '100%';
+        this.app.canvas.style.height = '100%';
+    }
+    async initSDK() {
+        if (this.config.sdk === false) {
+            // Offline / development mode — no SDK
+            this.initData = null;
+            return;
+        }
+        const sdkOpts = typeof this.config.sdk === 'object' ? this.config.sdk : {};
+        this.sdk = new gameSdk.CasinoGameSDK(sdkOpts);
+        // Perform the handshake
+        this.initData = await this.sdk.ready();
+        // Forward SDK events
+        this.sdk.on('error', (err) => {
+            this.emit('error', err);
+        });
+    }
+    applySDKConfig() {
+        // If SDK provides viewport dimensions, use them as design reference
+        if (this.initData?.config?.viewport) {
+            const vp = this.initData.config.viewport;
+            if (!this.config.designWidth)
+                this.config.designWidth = vp.width;
+            if (!this.config.designHeight)
+                this.config.designHeight = vp.height;
+        }
+    }
+    initSubSystems() {
+        // Asset Manager
+        const basePath = this.initData?.assetsUrl ?? '';
+        this.assets = new AssetManager(basePath, this.config.manifest);
+        // Audio Manager
+        this.audio = new AudioManager(this.config.audio);
+        // Viewport Manager
+        this.viewport = new ViewportManager(this.app, this._container, {
+            designWidth: this.config.designWidth,
+            designHeight: this.config.designHeight,
+            scaleMode: this.config.scaleMode,
+            orientation: this.config.orientation,
+        });
+        // Wire SceneManager to the PixiJS stage
+        this.scenes.setRoot(this.app.stage);
+        // Wire viewport resize → scene manager
+        this.viewport.on('resize', ({ width, height }) => {
+            this.scenes.resize(width, height);
+            this.emit('resize', { width, height });
+        });
+        this.viewport.on('orientationChange', (orientation) => {
+            this.emit('orientationChange', orientation);
+        });
+        // Connect ticker → scene updates
+        this.app.ticker.add((ticker) => {
+            // Always update scenes (loading screen needs onUpdate before _running=true)
+            this.scenes.update(ticker.deltaTime / 60); // convert to seconds
+        });
+        // Trigger initial resize
+        this.viewport.refresh();
+    }
+    async loadAssets(firstScene, sceneData) {
+        // Register built-in loading scene
+        this.scenes.register('__loading__', LoadingScene);
+        // Enter loading scene
+        await this.scenes.goto('__loading__', {
+            engine: this,
+            targetScene: firstScene,
+            targetData: sceneData,
+        });
+    }
+}
+
+/**
+ * Generic finite state machine for game flow management.
+ *
+ * Supports:
+ * - Typed context object shared across all states
+ * - Async enter/exit hooks
+ * - Per-frame update per state
+ * - Transition guards
+ * - Event emission on state change
+ *
+ * @example
+ * ```ts
+ * interface GameContext {
+ *   balance: number;
+ *   bet: number;
+ *   lastWin: number;
+ * }
+ *
+ * const fsm = new StateMachine<GameContext>({ balance: 1000, bet: 10, lastWin: 0 });
+ *
+ * fsm.addState('idle', {
+ *   enter: (ctx) => console.log('Waiting for spin...'),
+ *   update: (ctx, dt) => { // optional per-frame },
+ * });
+ *
+ * fsm.addState('spinning', {
+ *   enter: async (ctx) => {
+ *     const result = await sdk.play({ action: 'spin', bet: ctx.bet });
+ *     ctx.lastWin = result.totalWin;
+ *     await fsm.transition('presenting');
+ *   },
+ * });
+ *
+ * fsm.addState('presenting', {
+ *   enter: async (ctx) => {
+ *     await showWinPresentation(ctx.lastWin);
+ *     await fsm.transition('idle');
+ *   },
+ * });
+ *
+ * // Optional guard
+ * fsm.addGuard('idle', 'spinning', (ctx) => ctx.balance >= ctx.bet);
+ *
+ * await fsm.start('idle');
+ * ```
+ */
+class StateMachine extends EventEmitter {
+    _states = new Map();
+    _guards = new Map();
+    _current = null;
+    _transitioning = false;
+    _context;
+    constructor(context) {
+        super();
+        this._context = context;
+    }
+    /** Current state name */
+    get current() {
+        return this._current;
+    }
+    /** Whether a transition is in progress */
+    get isTransitioning() {
+        return this._transitioning;
+    }
+    /** State machine context (shared data) */
+    get context() {
+        return this._context;
+    }
+    /**
+     * Register a state with optional enter/exit/update hooks.
+     */
+    addState(name, config) {
+        this._states.set(name, config);
+        return this;
+    }
+    /**
+     * Add a transition guard.
+     * The guard function must return true to allow the transition.
+     *
+     * @param from - Source state
+     * @param to - Target state
+     * @param guard - Guard function
+     */
+    addGuard(from, to, guard) {
+        this._guards.set(`${from}->${to}`, guard);
+        return this;
+    }
+    /**
+     * Start the state machine in the given initial state.
+     */
+    async start(initialState, data) {
+        if (this._current !== null) {
+            throw new Error('[StateMachine] Already started. Use transition() to change states.');
+        }
+        const state = this._states.get(initialState);
+        if (!state) {
+            throw new Error(`[StateMachine] State "${initialState}" not registered.`);
+        }
+        this._current = initialState;
+        await state.enter?.(this._context, data);
+        this.emit('transition', { from: null, to: initialState });
+    }
+    /**
+     * Transition to a new state.
+     *
+     * @param to - Target state name
+     * @param data - Optional data passed to the new state's enter hook
+     * @returns true if the transition succeeded, false if blocked by a guard
+     */
+    async transition(to, data) {
+        if (this._transitioning) {
+            console.warn('[StateMachine] Transition already in progress');
+            return false;
+        }
+        const from = this._current;
+        // Check guard
+        if (from !== null) {
+            const guardKey = `${from}->${to}`;
+            const guard = this._guards.get(guardKey);
+            if (guard && !guard(this._context)) {
+                return false;
+            }
+        }
+        const toState = this._states.get(to);
+        if (!toState) {
+            throw new Error(`[StateMachine] State "${to}" not registered.`);
+        }
+        this._transitioning = true;
+        try {
+            // Exit current state
+            if (from !== null) {
+                const fromState = this._states.get(from);
+                await fromState?.exit?.(this._context);
+            }
+            // Enter new state
+            this._current = to;
+            await toState.enter?.(this._context, data);
+            this.emit('transition', { from, to });
+        }
+        catch (err) {
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            this._transitioning = false;
+        }
+        return true;
+    }
+    /**
+     * Call the current state's update function.
+     * Should be called from the game loop.
+     */
+    update(dt) {
+        if (this._current === null)
+            return;
+        const state = this._states.get(this._current);
+        state?.update?.(this._context, dt);
+    }
+    /**
+     * Check if a state is registered.
+     */
+    hasState(name) {
+        return this._states.has(name);
+    }
+    /**
+     * Check if a transition is allowed (guard passes).
+     */
+    canTransition(to) {
+        if (this._current === null)
+            return false;
+        const guardKey = `${this._current}->${to}`;
+        const guard = this._guards.get(guardKey);
+        if (!guard)
+            return true;
+        return guard(this._context);
+    }
+    /**
+     * Reset the state machine (exit current state, clear current).
+     */
+    async reset() {
+        if (this._current !== null) {
+            const state = this._states.get(this._current);
+            await state?.exit?.(this._context);
+        }
+        this._current = null;
+        this._transitioning = false;
+    }
+    /**
+     * Destroy the state machine.
+     */
+    async destroy() {
+        await this.reset();
+        this._states.clear();
+        this._guards.clear();
+        this.removeAllListeners();
+    }
+}
+
+/**
+ * Sequential/parallel animation timeline built on top of Tween.
+ *
+ * @example
+ * ```ts
+ * const timeline = new Timeline();
+ *
+ * // Sequential: one after another
+ * timeline
+ *   .to(sprite1, { alpha: 1 }, 300)
+ *   .to(sprite2, { x: 200 }, 500)
+ *   .delay(200)
+ *   .call(() => console.log('done'));
+ *
+ * // Parallel: all at once
+ * timeline.parallel(
+ *   () => Tween.to(sprite1, { x: 100 }, 300),
+ *   () => Tween.to(sprite2, { y: 200 }, 300),
+ * );
+ *
+ * await timeline.play();
+ * ```
+ */
+class Timeline {
+    _steps = [];
+    _playing = false;
+    _cancelled = false;
+    /**
+     * Add a tween step (animate to target values).
+     */
+    to(target, props, duration, easing) {
+        this._steps.push({
+            fn: () => Tween.to(target, props, duration, easing),
+        });
+        return this;
+    }
+    /**
+     * Add a tween step (animate from given values).
+     */
+    from(target, props, duration, easing) {
+        this._steps.push({
+            fn: () => Tween.from(target, props, duration, easing),
+        });
+        return this;
+    }
+    /**
+     * Add a delay step.
+     */
+    delay(ms) {
+        this._steps.push({
+            fn: () => Tween.delay(ms),
+        });
+        return this;
+    }
+    /**
+     * Add a callback step.
+     */
+    call(fn) {
+        this._steps.push({
+            fn: async () => {
+                await fn();
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a parallel step — all functions run simultaneously,
+     * step completes when all are done.
+     */
+    parallel(...fns) {
+        this._steps.push({
+            fn: () => Promise.all(fns.map((f) => f())).then(() => { }),
+        });
+        return this;
+    }
+    /**
+     * Play the timeline from start.
+     * Returns a promise that resolves when all steps complete.
+     */
+    async play() {
+        if (this._playing)
+            return;
+        this._playing = true;
+        this._cancelled = false;
+        for (const step of this._steps) {
+            if (this._cancelled)
+                break;
+            await step.fn();
+        }
+        this._playing = false;
+    }
+    /**
+     * Cancel the timeline.
+     */
+    cancel() {
+        this._cancelled = true;
+    }
+    /**
+     * Clear all steps.
+     */
+    clear() {
+        this._steps.length = 0;
+        this._cancelled = false;
+        this._playing = false;
+        return this;
+    }
+    /** Whether the timeline is currently playing */
+    get isPlaying() {
+        return this._playing;
+    }
+}
+
+/**
+ * Helper for working with Spine animations in PixiJS v8.
+ *
+ * Optional — only works if @esotericsoftware/spine-pixi-v8 is installed.
+ * Provides convenience methods for creating and playing Spine animations.
+ *
+ * @example
+ * ```ts
+ * // Load spine assets via AssetManager first
+ * const spine = SpineHelper.create('char-data', 'char-atlas');
+ * app.stage.addChild(spine);
+ * await SpineHelper.playAnimation(spine, 'idle', true);
+ * await SpineHelper.playAnimation(spine, 'win');
+ * ```
+ */
+class SpineHelper {
+    static _SpineClass = null;
+    static _loaded = false;
+    /**
+     * Ensure the Spine module is loaded.
+     * Called automatically by create/playAnimation.
+     */
+    static async ensureLoaded() {
+        if (SpineHelper._loaded)
+            return !!SpineHelper._SpineClass;
+        try {
+            const spineModule = await import('@esotericsoftware/spine-pixi-v8');
+            SpineHelper._SpineClass = spineModule.Spine;
+            SpineHelper._loaded = true;
+            return true;
+        }
+        catch {
+            console.warn('[SpineHelper] @esotericsoftware/spine-pixi-v8 not available.');
+            SpineHelper._loaded = true;
+            return false;
+        }
+    }
+    /**
+     * Create a Spine display object.
+     *
+     * @param skeletonAlias - Alias of the loaded .skel/.json asset
+     * @param atlasAlias - Alias of the loaded .atlas asset
+     * @param options - Additional Spine options
+     * @returns Spine container (or null if Spine is not available)
+     */
+    static async create(skeletonAlias, atlasAlias, options) {
+        const available = await SpineHelper.ensureLoaded();
+        if (!available || !SpineHelper._SpineClass)
+            return null;
+        const SpineClass = SpineHelper._SpineClass;
+        // Use Spine.from for v4.2, constructor for v4.3+
+        if (typeof SpineClass.from === 'function') {
+            return SpineClass.from({
+                skeleton: skeletonAlias,
+                atlas: atlasAlias,
+                scale: options?.scale,
+                autoUpdate: options?.autoUpdate ?? true,
+            });
+        }
+        return new SpineClass({
+            skeleton: skeletonAlias,
+            atlas: atlasAlias,
+            scale: options?.scale,
+            autoUpdate: options?.autoUpdate ?? true,
+        });
+    }
+    /**
+     * Play a named animation on a Spine object.
+     * Returns a promise that resolves when the animation completes.
+     * For looping animations, the promise never resolves.
+     *
+     * @param spine - Spine display object
+     * @param animationName - Name of the animation
+     * @param loop - Whether to loop (default: false)
+     * @param track - Animation track (default: 0)
+     */
+    static playAnimation(spine, animationName, loop = false, track = 0) {
+        return new Promise((resolve) => {
+            if (!spine?.state) {
+                resolve();
+                return;
+            }
+            const entry = spine.state.setAnimation(track, animationName, loop);
+            if (loop) {
+                // Looping animations never complete — resolve immediately
+                // so callers can fire-and-forget
+                resolve();
+                return;
+            }
+            // Wait for the animation to complete
+            spine.state.addListener({
+                complete: (completedEntry) => {
+                    if (completedEntry === entry) {
+                        resolve();
+                    }
+                },
+            });
+        });
+    }
+    /**
+     * Queue an animation after the current one finishes.
+     *
+     * @param spine - Spine display object
+     * @param animationName - Animation name
+     * @param delay - Mix duration / delay before starting
+     * @param loop - Loop the queued animation
+     * @param track - Animation track
+     */
+    static addAnimation(spine, animationName, delay = 0, loop = false, track = 0) {
+        spine?.state?.addAnimation(track, animationName, loop, delay);
+    }
+    /**
+     * Get all animation names available on a Spine skeleton.
+     */
+    static getAnimationNames(spine) {
+        if (!spine?.skeleton?.data?.animations)
+            return [];
+        return spine.skeleton.data.animations.map((a) => a.name);
+    }
+    /**
+     * Get all skin names available on a Spine skeleton.
+     */
+    static getSkinNames(spine) {
+        if (!spine?.skeleton?.data?.skins)
+            return [];
+        return spine.skeleton.data.skins.map((s) => s.name);
+    }
+    /**
+     * Set the active skin on a Spine skeleton.
+     */
+    static setSkin(spine, skinName) {
+        spine?.skeleton?.setSkinByName(skinName);
+        spine?.skeleton?.setSlotsToSetupPose();
+    }
+}
+
+/**
+ * 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();
+ * ```
+ */
+class InputManager extends EventEmitter {
+    _canvas;
+    _locked = false;
+    _keysDown = new Set();
+    _destroyed = false;
+    // Gesture tracking
+    _pointerStart = null;
+    _swipeThreshold = 50; // minimum distance in px
+    _swipeMaxTime = 300; // max ms for swipe gesture
+    constructor(canvas) {
+        super();
+        this._canvas = canvas;
+        this.setupPointerEvents();
+        this.setupKeyboardEvents();
+    }
+    /** Whether input is currently locked */
+    get locked() {
+        return this._locked;
+    }
+    /** Lock all input (e.g., during animations) */
+    lock() {
+        this._locked = true;
+    }
+    /** Unlock input */
+    unlock() {
+        this._locked = false;
+    }
+    /** Check if a key is currently pressed */
+    isKeyDown(key) {
+        return this._keysDown.has(key.toLowerCase());
+    }
+    /** Destroy the input manager */
+    destroy() {
+        this._destroyed = true;
+        this._canvas.removeEventListener('pointerdown', this.onPointerDown);
+        this._canvas.removeEventListener('pointerup', this.onPointerUp);
+        this._canvas.removeEventListener('pointermove', this.onPointerMove);
+        document.removeEventListener('keydown', this.onKeyDown);
+        document.removeEventListener('keyup', this.onKeyUp);
+        this._keysDown.clear();
+        this.removeAllListeners();
+    }
+    // ─── Private: Pointer ──────────────────────────────────
+    setupPointerEvents() {
+        this._canvas.addEventListener('pointerdown', this.onPointerDown);
+        this._canvas.addEventListener('pointerup', this.onPointerUp);
+        this._canvas.addEventListener('pointermove', this.onPointerMove);
+    }
+    onPointerDown = (e) => {
+        if (this._locked || this._destroyed)
+            return;
+        const pos = this.getCanvasPosition(e);
+        this._pointerStart = { ...pos, time: Date.now() };
+        this.emit('press', pos);
+    };
+    onPointerUp = (e) => {
+        if (this._locked || this._destroyed)
+            return;
+        const pos = this.getCanvasPosition(e);
+        this.emit('release', pos);
+        // Check for tap vs swipe
+        if (this._pointerStart) {
+            const dx = pos.x - this._pointerStart.x;
+            const dy = pos.y - this._pointerStart.y;
+            const dist = Math.sqrt(dx * dx + dy * dy);
+            const elapsed = Date.now() - this._pointerStart.time;
+            if (dist > this._swipeThreshold && elapsed < this._swipeMaxTime) {
+                // Swipe detected
+                const absDx = Math.abs(dx);
+                const absDy = Math.abs(dy);
+                let direction;
+                if (absDx > absDy) {
+                    direction = dx > 0 ? 'right' : 'left';
+                }
+                else {
+                    direction = dy > 0 ? 'down' : 'up';
+                }
+                this.emit('swipe', { direction, velocity: dist / elapsed });
+            }
+            else if (dist < 10) {
+                // Tap (minimal movement)
+                this.emit('tap', pos);
+            }
+        }
+        this._pointerStart = null;
+    };
+    onPointerMove = (e) => {
+        if (this._locked || this._destroyed)
+            return;
+        this.emit('move', this.getCanvasPosition(e));
+    };
+    getCanvasPosition(e) {
+        const rect = this._canvas.getBoundingClientRect();
+        return {
+            x: e.clientX - rect.left,
+            y: e.clientY - rect.top,
+        };
+    }
+    // ─── Private: Keyboard ─────────────────────────────────
+    setupKeyboardEvents() {
+        document.addEventListener('keydown', this.onKeyDown);
+        document.addEventListener('keyup', this.onKeyUp);
+    }
+    onKeyDown = (e) => {
+        if (this._locked || this._destroyed)
+            return;
+        this._keysDown.add(e.key.toLowerCase());
+        this.emit('keydown', { key: e.key, code: e.code });
+    };
+    onKeyUp = (e) => {
+        if (this._destroyed)
+            return;
+        this._keysDown.delete(e.key.toLowerCase());
+        if (this._locked)
+            return;
+        this.emit('keyup', { key: e.key, code: e.code });
+    };
+}
+
+const DEFAULT_COLORS = {
+    normal: 0xffd700,
+    hover: 0xffe44d,
+    pressed: 0xccac00,
+    disabled: 0x666666,
+};
+/**
+ * Interactive button component with state management and animation.
+ *
+ * Supports both texture-based and Graphics-based rendering.
+ *
+ * @example
+ * ```ts
+ * const btn = new Button({
+ *   width: 200, height: 60, borderRadius: 12,
+ *   colors: { normal: 0x22aa22, hover: 0x33cc33 },
+ * });
+ *
+ * btn.onTap = () => console.log('Clicked!');
+ * scene.container.addChild(btn);
+ * ```
+ */
+class Button extends pixi_js.Container {
+    _state = 'normal';
+    _bg;
+    _sprites = {};
+    _config;
+    /** Called when the button is tapped/clicked */
+    onTap;
+    /** Called when the button state changes */
+    onStateChange;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            width: 200,
+            height: 60,
+            borderRadius: 8,
+            pressScale: 0.95,
+            animationDuration: 100,
+            ...config,
+        };
+        // Create Graphics background
+        this._bg = new pixi_js.Graphics();
+        this.addChild(this._bg);
+        // Create texture sprites if provided
+        if (config.textures) {
+            for (const [state, tex] of Object.entries(config.textures)) {
+                const texture = typeof tex === 'string' ? pixi_js.Texture.from(tex) : tex;
+                const sprite = new pixi_js.Sprite(texture);
+                sprite.anchor.set(0.5);
+                sprite.visible = state === 'normal';
+                this._sprites[state] = sprite;
+                this.addChild(sprite);
+            }
+        }
+        // Make interactive
+        this.eventMode = 'static';
+        this.cursor = 'pointer';
+        // Set up hit area for Graphics-based
+        this.pivot.set(this._config.width / 2, this._config.height / 2);
+        // Bind events
+        this.on('pointerover', this.onPointerOver);
+        this.on('pointerout', this.onPointerOut);
+        this.on('pointerdown', this.onPointerDown);
+        this.on('pointerup', this.onPointerUp);
+        this.on('pointertap', this.onPointerTap);
+        // Initial render
+        this.setState('normal');
+        if (config.disabled) {
+            this.disable();
+        }
+    }
+    /** Current button state */
+    get state() {
+        return this._state;
+    }
+    /** Enable the button */
+    enable() {
+        if (this._state === 'disabled') {
+            this.setState('normal');
+            this.eventMode = 'static';
+            this.cursor = 'pointer';
+        }
+    }
+    /** Disable the button */
+    disable() {
+        this.setState('disabled');
+        this.eventMode = 'none';
+        this.cursor = 'default';
+    }
+    /** Whether the button is disabled */
+    get disabled() {
+        return this._state === 'disabled';
+    }
+    setState(state) {
+        if (this._state === state)
+            return;
+        this._state = state;
+        this.render();
+        this.onStateChange?.(state);
+    }
+    render() {
+        const { width, height, borderRadius, colors } = this._config;
+        const colorMap = { ...DEFAULT_COLORS, ...colors };
+        // Update Graphics
+        this._bg.clear();
+        this._bg.roundRect(0, 0, width, height, borderRadius).fill(colorMap[this._state]);
+        // Add highlight for normal/hover
+        if (this._state === 'normal' || this._state === 'hover') {
+            this._bg
+                .roundRect(2, 2, width - 4, height * 0.45, borderRadius)
+                .fill({ color: 0xffffff, alpha: 0.1 });
+        }
+        // Update sprite visibility
+        for (const [state, sprite] of Object.entries(this._sprites)) {
+            if (sprite)
+                sprite.visible = state === this._state;
+        }
+        // Fall back to normal sprite if state sprite doesn't exist
+        if (!this._sprites[this._state] && this._sprites.normal) {
+            this._sprites.normal.visible = true;
+        }
+    }
+    onPointerOver = () => {
+        if (this._state === 'disabled')
+            return;
+        this.setState('hover');
+    };
+    onPointerOut = () => {
+        if (this._state === 'disabled')
+            return;
+        this.setState('normal');
+        Tween.to(this.scale, { x: 1, y: 1 }, this._config.animationDuration);
+    };
+    onPointerDown = () => {
+        if (this._state === 'disabled')
+            return;
+        this.setState('pressed');
+        const s = this._config.pressScale;
+        Tween.to(this.scale, { x: s, y: s }, this._config.animationDuration, Easing.easeOutQuad);
+    };
+    onPointerUp = () => {
+        if (this._state === 'disabled')
+            return;
+        this.setState('hover');
+        Tween.to(this.scale, { x: 1, y: 1 }, this._config.animationDuration, Easing.easeOutBack);
+    };
+    onPointerTap = () => {
+        if (this._state === 'disabled')
+            return;
+        this.onTap?.();
+    };
+}
+
+/**
+ * Horizontal progress bar with optional smooth fill animation.
+ *
+ * @example
+ * ```ts
+ * const bar = new ProgressBar({ width: 300, height: 20, fillColor: 0x22cc22 });
+ * scene.container.addChild(bar);
+ * bar.progress = 0.5; // 50%
+ * ```
+ */
+class ProgressBar extends pixi_js.Container {
+    _track;
+    _fill;
+    _border;
+    _config;
+    _progress = 0;
+    _displayedProgress = 0;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            width: 300,
+            height: 16,
+            borderRadius: 8,
+            fillColor: 0xffd700,
+            trackColor: 0x333333,
+            borderColor: 0x555555,
+            borderWidth: 1,
+            animated: true,
+            animationSpeed: 0.1,
+            ...config,
+        };
+        this._track = new pixi_js.Graphics();
+        this._fill = new pixi_js.Graphics();
+        this._border = new pixi_js.Graphics();
+        this.addChild(this._track, this._fill, this._border);
+        this.drawTrack();
+        this.drawBorder();
+        this.drawFill(0);
+    }
+    /** Get/set progress (0..1) */
+    get progress() {
+        return this._progress;
+    }
+    set progress(value) {
+        this._progress = Math.max(0, Math.min(1, value));
+        if (!this._config.animated) {
+            this._displayedProgress = this._progress;
+            this.drawFill(this._displayedProgress);
+        }
+    }
+    /**
+     * Call each frame if animated is true.
+     */
+    update(dt) {
+        if (!this._config.animated)
+            return;
+        if (Math.abs(this._displayedProgress - this._progress) < 0.001) {
+            this._displayedProgress = this._progress;
+            return;
+        }
+        this._displayedProgress +=
+            (this._progress - this._displayedProgress) * this._config.animationSpeed;
+        this.drawFill(this._displayedProgress);
+    }
+    drawTrack() {
+        const { width, height, borderRadius, trackColor } = this._config;
+        this._track.clear();
+        this._track.roundRect(0, 0, width, height, borderRadius).fill(trackColor);
+    }
+    drawBorder() {
+        const { width, height, borderRadius, borderColor, borderWidth } = this._config;
+        this._border.clear();
+        this._border
+            .roundRect(0, 0, width, height, borderRadius)
+            .stroke({ color: borderColor, width: borderWidth });
+    }
+    drawFill(progress) {
+        const { width, height, borderRadius, fillColor, borderWidth } = this._config;
+        const innerWidth = width - borderWidth * 2;
+        const innerHeight = height - borderWidth * 2;
+        const fillWidth = Math.max(0, innerWidth * progress);
+        this._fill.clear();
+        if (fillWidth > 0) {
+            this._fill.x = borderWidth;
+            this._fill.y = borderWidth;
+            this._fill.roundRect(0, 0, fillWidth, innerHeight, borderRadius - 1).fill(fillColor);
+            // Highlight
+            this._fill
+                .roundRect(0, 0, fillWidth, innerHeight * 0.4, borderRadius - 1)
+                .fill({ color: 0xffffff, alpha: 0.15 });
+        }
+    }
+}
+
+/**
+ * Enhanced text label with auto-fit scaling and currency formatting.
+ *
+ * @example
+ * ```ts
+ * const label = new Label({
+ *   text: 'BALANCE',
+ *   style: { fontSize: 24, fill: 0xffd700 },
+ *   maxWidth: 200,
+ *   autoFit: true,
+ * });
+ * ```
+ */
+class Label extends pixi_js.Container {
+    _text;
+    _maxWidth;
+    _autoFit;
+    constructor(config = {}) {
+        super();
+        this._maxWidth = config.maxWidth ?? Infinity;
+        this._autoFit = config.autoFit ?? false;
+        this._text = new pixi_js.Text({
+            text: config.text ?? '',
+            style: {
+                fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+                fontSize: 24,
+                fill: 0xffffff,
+                ...config.style,
+            },
+        });
+        this._text.anchor.set(0.5);
+        this.addChild(this._text);
+        this.fitText();
+    }
+    /** Get/set the displayed text */
+    get text() {
+        return this._text.text;
+    }
+    set text(value) {
+        this._text.text = value;
+        this.fitText();
+    }
+    /** Get/set the text style */
+    get style() {
+        return this._text.style;
+    }
+    /** Set max width constraint */
+    set maxWidth(value) {
+        this._maxWidth = value;
+        this.fitText();
+    }
+    /**
+     * Format and display a number as currency.
+     *
+     * @param amount - The numeric amount
+     * @param currency - Currency code (e.g., 'USD', 'EUR')
+     * @param locale - Locale string (default: 'en-US')
+     */
+    setCurrency(amount, currency, locale = 'en-US') {
+        try {
+            this.text = new Intl.NumberFormat(locale, {
+                style: 'currency',
+                currency,
+                minimumFractionDigits: 2,
+                maximumFractionDigits: 2,
+            }).format(amount);
+        }
+        catch {
+            this.text = `${amount.toFixed(2)} ${currency}`;
+        }
+    }
+    /**
+     * Format a number with thousands separators.
+     */
+    setNumber(value, decimals = 0, locale = 'en-US') {
+        this.text = new Intl.NumberFormat(locale, {
+            minimumFractionDigits: decimals,
+            maximumFractionDigits: decimals,
+        }).format(value);
+    }
+    fitText() {
+        if (!this._autoFit || this._maxWidth === Infinity)
+            return;
+        this._text.scale.set(1);
+        if (this._text.width > this._maxWidth) {
+            const scale = this._maxWidth / this._text.width;
+            this._text.scale.set(scale);
+        }
+    }
+}
+
+/**
+ * Background panel that can use either Graphics or 9-slice sprite.
+ *
+ * @example
+ * ```ts
+ * // Simple colored panel
+ * const panel = new Panel({ width: 400, height: 300, backgroundColor: 0x222222, borderRadius: 12 });
+ *
+ * // 9-slice panel (texture-based)
+ * const panel = new Panel({
+ *   nineSliceTexture: 'panel-bg',
+ *   nineSliceBorders: [20, 20, 20, 20],
+ *   width: 400, height: 300,
+ * });
+ * ```
+ */
+class Panel extends pixi_js.Container {
+    _bg;
+    _content;
+    _config;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            width: 400,
+            height: 300,
+            padding: 16,
+            backgroundAlpha: 1,
+            ...config,
+        };
+        // Create background
+        if (config.nineSliceTexture) {
+            const texture = typeof config.nineSliceTexture === 'string'
+                ? pixi_js.Texture.from(config.nineSliceTexture)
+                : config.nineSliceTexture;
+            const [left, top, right, bottom] = config.nineSliceBorders ?? [10, 10, 10, 10];
+            this._bg = new pixi_js.NineSliceSprite({
+                texture,
+                leftWidth: left,
+                topHeight: top,
+                rightWidth: right,
+                bottomHeight: bottom,
+            });
+            this._bg.width = this._config.width;
+            this._bg.height = this._config.height;
+        }
+        else {
+            this._bg = new pixi_js.Graphics();
+            this.drawGraphicsBg();
+        }
+        this._bg.alpha = this._config.backgroundAlpha;
+        this.addChild(this._bg);
+        // Content container with padding
+        this._content = new pixi_js.Container();
+        this._content.x = this._config.padding;
+        this._content.y = this._config.padding;
+        this.addChild(this._content);
+    }
+    /** Content container — add children here */
+    get content() {
+        return this._content;
+    }
+    /** Resize the panel */
+    setSize(width, height) {
+        this._config.width = width;
+        this._config.height = height;
+        if (this._bg instanceof pixi_js.Graphics) {
+            this.drawGraphicsBg();
+        }
+        else {
+            this._bg.width = width;
+            this._bg.height = height;
+        }
+    }
+    drawGraphicsBg() {
+        const bg = this._bg;
+        const { width, height, backgroundColor, borderRadius, borderColor, borderWidth, } = this._config;
+        bg.clear();
+        bg.roundRect(0, 0, width, height, borderRadius ?? 0).fill(backgroundColor ?? 0x1a1a2e);
+        if (borderColor !== undefined && borderWidth) {
+            bg.roundRect(0, 0, width, height, borderRadius ?? 0)
+                .stroke({ color: borderColor, width: borderWidth });
+        }
+    }
+}
+
+/**
+ * Reactive balance display component.
+ *
+ * Automatically formats currency and can animate value changes
+ * with a smooth countup/countdown effect.
+ *
+ * @example
+ * ```ts
+ * const balance = new BalanceDisplay({ currency: 'USD', animated: true });
+ * balance.setValue(1000);
+ *
+ * // Wire to SDK
+ * sdk.on('balanceUpdate', ({ balance: val }) => balance.setValue(val));
+ * ```
+ */
+class BalanceDisplay extends pixi_js.Container {
+    _prefixLabel = null;
+    _valueLabel;
+    _config;
+    _currentValue = 0;
+    _displayedValue = 0;
+    _animating = false;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            currency: config.currency ?? 'USD',
+            locale: config.locale ?? 'en-US',
+            animated: config.animated ?? true,
+            animationDuration: config.animationDuration ?? 500,
+        };
+        // Prefix label
+        if (config.prefix) {
+            this._prefixLabel = new Label({
+                text: config.prefix,
+                style: {
+                    fontSize: 16,
+                    fill: 0xaaaaaa,
+                    ...config.style,
+                },
+            });
+            this.addChild(this._prefixLabel);
+        }
+        // Value label
+        this._valueLabel = new Label({
+            text: '0.00',
+            style: {
+                fontSize: 28,
+                fontWeight: 'bold',
+                fill: 0xffffff,
+                ...config.style,
+            },
+            maxWidth: config.maxWidth,
+            autoFit: !!config.maxWidth,
+        });
+        this.addChild(this._valueLabel);
+        this.layoutLabels();
+    }
+    /** Current displayed value */
+    get value() {
+        return this._currentValue;
+    }
+    /**
+     * Set the balance value. If animated, smoothly counts to the new value.
+     */
+    setValue(value) {
+        const oldValue = this._currentValue;
+        this._currentValue = value;
+        if (this._config.animated && oldValue !== value) {
+            this.animateValue(oldValue, value);
+        }
+        else {
+            this._displayedValue = value;
+            this.updateDisplay();
+        }
+    }
+    /**
+     * Set the currency code.
+     */
+    setCurrency(currency) {
+        this._config.currency = currency;
+        this.updateDisplay();
+    }
+    async animateValue(from, to) {
+        this._animating = true;
+        const duration = this._config.animationDuration;
+        const startTime = Date.now();
+        return new Promise((resolve) => {
+            const tick = () => {
+                const elapsed = Date.now() - startTime;
+                const t = Math.min(elapsed / duration, 1);
+                const eased = Easing.easeOutCubic(t);
+                this._displayedValue = from + (to - from) * eased;
+                this.updateDisplay();
+                if (t < 1) {
+                    requestAnimationFrame(tick);
+                }
+                else {
+                    this._displayedValue = to;
+                    this.updateDisplay();
+                    this._animating = false;
+                    resolve();
+                }
+            };
+            requestAnimationFrame(tick);
+        });
+    }
+    updateDisplay() {
+        this._valueLabel.setCurrency(this._displayedValue, this._config.currency, this._config.locale);
+    }
+    layoutLabels() {
+        if (this._prefixLabel) {
+            this._prefixLabel.y = -14;
+            this._valueLabel.y = 14;
+        }
+    }
+}
+
+/**
+ * Win amount display with countup animation.
+ *
+ * Shows a dramatic countup from 0 to the win amount, with optional
+ * scale pop effect — typical of slot games.
+ *
+ * @example
+ * ```ts
+ * const winDisplay = new WinDisplay({ currency: 'USD' });
+ * scene.container.addChild(winDisplay);
+ * await winDisplay.showWin(150.50); // countup animation
+ * winDisplay.hide();
+ * ```
+ */
+class WinDisplay extends pixi_js.Container {
+    _label;
+    _config;
+    _cancelCountup = false;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            currency: config.currency ?? 'USD',
+            locale: config.locale ?? 'en-US',
+            countupDuration: config.countupDuration ?? 1500,
+            popScale: config.popScale ?? 1.2,
+        };
+        this._label = new Label({
+            text: '',
+            style: {
+                fontSize: 48,
+                fontWeight: 'bold',
+                fill: 0xffd700,
+                stroke: { color: 0x000000, width: 3 },
+                ...config.style,
+            },
+        });
+        this.addChild(this._label);
+        this.visible = false;
+    }
+    /**
+     * Show a win with countup animation.
+     *
+     * @param amount - Win amount
+     * @returns Promise that resolves when the animation completes
+     */
+    async showWin(amount) {
+        this.visible = true;
+        this._cancelCountup = false;
+        this.alpha = 1;
+        const duration = this._config.countupDuration;
+        const startTime = Date.now();
+        // Scale pop
+        this.scale.set(0.5);
+        return new Promise((resolve) => {
+            const tick = () => {
+                if (this._cancelCountup) {
+                    this.displayAmount(amount);
+                    resolve();
+                    return;
+                }
+                const elapsed = Date.now() - startTime;
+                const t = Math.min(elapsed / duration, 1);
+                const eased = Easing.easeOutCubic(t);
+                // Countup
+                const current = amount * eased;
+                this.displayAmount(current);
+                // Scale animation
+                const scaleT = Math.min(elapsed / 300, 1);
+                const scaleEased = Easing.easeOutBack(scaleT);
+                const targetScale = 1;
+                this.scale.set(0.5 + (targetScale - 0.5) * scaleEased);
+                if (t < 1) {
+                    requestAnimationFrame(tick);
+                }
+                else {
+                    this.displayAmount(amount);
+                    this.scale.set(1);
+                    resolve();
+                }
+            };
+            requestAnimationFrame(tick);
+        });
+    }
+    /**
+     * Skip the countup animation and show the final amount immediately.
+     */
+    skipCountup(amount) {
+        this._cancelCountup = true;
+        this.displayAmount(amount);
+        this.scale.set(1);
+    }
+    /**
+     * Hide the win display.
+     */
+    hide() {
+        this.visible = false;
+        this._label.text = '';
+    }
+    displayAmount(amount) {
+        this._label.setCurrency(amount, this._config.currency, this._config.locale);
+    }
+}
+
+/**
+ * Modal overlay component.
+ * Shows content on top of a dark overlay with enter/exit animations.
+ *
+ * @example
+ * ```ts
+ * const modal = new Modal({ closeOnOverlay: true });
+ * modal.content.addChild(settingsPanel);
+ * modal.onClose = () => console.log('Closed');
+ * await modal.show(1920, 1080);
+ * ```
+ */
+class Modal extends pixi_js.Container {
+    _overlay;
+    _contentContainer;
+    _config;
+    _showing = false;
+    /** Called when the modal is closed */
+    onClose;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            overlayColor: 0x000000,
+            overlayAlpha: 0.7,
+            closeOnOverlay: true,
+            animationDuration: 300,
+            ...config,
+        };
+        // Overlay
+        this._overlay = new pixi_js.Graphics();
+        this._overlay.eventMode = 'static';
+        this.addChild(this._overlay);
+        if (this._config.closeOnOverlay) {
+            this._overlay.on('pointertap', () => this.hide());
+        }
+        // Content container
+        this._contentContainer = new pixi_js.Container();
+        this.addChild(this._contentContainer);
+        this.visible = false;
+    }
+    /** Content container — add your UI here */
+    get content() {
+        return this._contentContainer;
+    }
+    /** Whether the modal is currently showing */
+    get isShowing() {
+        return this._showing;
+    }
+    /**
+     * Show the modal with animation.
+     */
+    async show(viewWidth, viewHeight) {
+        this._showing = true;
+        this.visible = true;
+        // Draw overlay to cover full screen
+        this._overlay.clear();
+        this._overlay.rect(0, 0, viewWidth, viewHeight).fill(this._config.overlayColor);
+        this._overlay.alpha = 0;
+        // Center content
+        this._contentContainer.x = viewWidth / 2;
+        this._contentContainer.y = viewHeight / 2;
+        this._contentContainer.alpha = 0;
+        this._contentContainer.scale.set(0.8);
+        // Animate in
+        await Promise.all([
+            Tween.to(this._overlay, { alpha: this._config.overlayAlpha }, this._config.animationDuration, Easing.easeOutCubic),
+            Tween.to(this._contentContainer, { alpha: 1, 'scale.x': 1, 'scale.y': 1 }, this._config.animationDuration, Easing.easeOutBack),
+        ]);
+    }
+    /**
+     * Hide the modal with animation.
+     */
+    async hide() {
+        if (!this._showing)
+            return;
+        await Promise.all([
+            Tween.to(this._overlay, { alpha: 0 }, this._config.animationDuration * 0.7, Easing.easeInCubic),
+            Tween.to(this._contentContainer, { alpha: 0, 'scale.x': 0.8, 'scale.y': 0.8 }, this._config.animationDuration * 0.7, Easing.easeInCubic),
+        ]);
+        this.visible = false;
+        this._showing = false;
+        this.onClose?.();
+    }
+}
+
+const TOAST_COLORS = {
+    info: 0x3498db,
+    success: 0x27ae60,
+    warning: 0xf39c12,
+    error: 0xe74c3c,
+};
+/**
+ * Toast notification component for displaying transient messages.
+ *
+ * @example
+ * ```ts
+ * const toast = new Toast();
+ * scene.container.addChild(toast);
+ * await toast.show('Connection lost', 'error', 1920, 1080);
+ * ```
+ */
+class Toast extends pixi_js.Container {
+    _bg;
+    _text;
+    _config;
+    _dismissTimeout = null;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            duration: 3000,
+            bottomOffset: 60,
+            ...config,
+        };
+        this._bg = new pixi_js.Graphics();
+        this.addChild(this._bg);
+        this._text = new pixi_js.Text({
+            text: '',
+            style: {
+                fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+                fontSize: 16,
+                fill: 0xffffff,
+            },
+        });
+        this._text.anchor.set(0.5);
+        this.addChild(this._text);
+        this.visible = false;
+    }
+    /**
+     * Show a toast message.
+     */
+    async show(message, type = 'info', viewWidth, viewHeight) {
+        // Clear previous dismiss
+        if (this._dismissTimeout) {
+            clearTimeout(this._dismissTimeout);
+        }
+        this._text.text = message;
+        const padding = 20;
+        const width = Math.max(200, this._text.width + padding * 2);
+        const height = 44;
+        const radius = 8;
+        this._bg.clear();
+        this._bg.roundRect(-width / 2, -height / 2, width, height, radius).fill(TOAST_COLORS[type]);
+        this._bg.roundRect(-width / 2, -height / 2, width, height, radius)
+            .fill({ color: 0x000000, alpha: 0.2 });
+        // Position
+        if (viewWidth && viewHeight) {
+            this.x = viewWidth / 2;
+            this.y = viewHeight - this._config.bottomOffset;
+        }
+        this.visible = true;
+        this.alpha = 0;
+        this.y += 20;
+        // Animate in
+        await Tween.to(this, { alpha: 1, y: this.y - 20 }, 300, Easing.easeOutCubic);
+        // Auto-dismiss
+        if (this._config.duration > 0) {
+            this._dismissTimeout = setTimeout(() => {
+                this.dismiss();
+            }, this._config.duration);
+        }
+    }
+    /**
+     * Dismiss the toast.
+     */
+    async dismiss() {
+        if (!this.visible)
+            return;
+        if (this._dismissTimeout) {
+            clearTimeout(this._dismissTimeout);
+            this._dismissTimeout = null;
+        }
+        await Tween.to(this, { alpha: 0, y: this.y + 20 }, 200, Easing.easeInCubic);
+        this.visible = false;
+    }
+}
+
+const DEFAULT_CONFIG = {
+    balance: 10000,
+    currency: 'USD',
+    gameConfig: {
+        id: 'dev-game',
+        type: 'slot',
+        version: '1.0.0',
+        viewport: { width: 1920, height: 1080 },
+        betLevels: [0.1, 0.2, 0.5, 1, 2, 5, 10, 20, 50],
+    },
+    assetsUrl: '/assets/',
+    session: null,
+    onPlay: () => ({}),
+    networkDelay: 200,
+    debug: true,
+};
+/**
+ * Mock host bridge for local development.
+ *
+ * Intercepts postMessage communication from the SDK and responds
+ * with mock data, simulating a real casino host environment.
+ *
+ * This allows games to be developed and tested without a real backend.
+ *
+ * @example
+ * ```ts
+ * // In your dev entry point or vite plugin
+ * import { DevBridge } from '@energy8platform/game-engine/debug';
+ *
+ * const devBridge = new DevBridge({
+ *   balance: 5000,
+ *   currency: 'EUR',
+ *   gameConfig: { id: 'my-slot', type: 'slot', betLevels: [0.2, 0.5, 1, 2] },
+ *   onPlay: ({ action, bet }) => ({
+ *     totalWin: Math.random() > 0.5 ? bet * (Math.random() * 20) : 0,
+ *     data: {
+ *       matrix: generateRandomMatrix(5, 3, 10),
+ *       win_lines: [],
+ *     },
+ *   }),
+ * });
+ * devBridge.start();
+ * ```
+ */
+class DevBridge {
+    _config;
+    _balance;
+    _roundCounter = 0;
+    _listening = false;
+    _handler = null;
+    constructor(config = {}) {
+        this._config = { ...DEFAULT_CONFIG, ...config };
+        this._balance = this._config.balance;
+    }
+    /** Current mock balance */
+    get balance() {
+        return this._balance;
+    }
+    /** Start listening for SDK messages */
+    start() {
+        if (this._listening)
+            return;
+        this._handler = (e) => {
+            this.handleMessage(e);
+        };
+        window.addEventListener('message', this._handler);
+        this._listening = true;
+        if (this._config.debug) {
+            console.log('[DevBridge] Started — listening for SDK messages');
+        }
+    }
+    /** Stop listening */
+    stop() {
+        if (this._handler) {
+            window.removeEventListener('message', this._handler);
+            this._handler = null;
+        }
+        this._listening = false;
+        if (this._config.debug) {
+            console.log('[DevBridge] Stopped');
+        }
+    }
+    /** Set mock balance */
+    setBalance(balance) {
+        this._balance = balance;
+        // Send balance update
+        this.sendMessage('BALANCE_UPDATE', { balance: this._balance });
+    }
+    /** Destroy the dev bridge */
+    destroy() {
+        this.stop();
+    }
+    // ─── Message Handling ──────────────────────────────────
+    handleMessage(e) {
+        const data = e.data;
+        // Only process bridge messages
+        if (!data || data.__casino_bridge !== true)
+            return;
+        if (this._config.debug) {
+            console.log('[DevBridge] ←', data.type, data.payload);
+        }
+        switch (data.type) {
+            case 'GAME_READY':
+                this.handleGameReady(data.id);
+                break;
+            case 'PLAY_REQUEST':
+                this.handlePlayRequest(data.payload, data.id);
+                break;
+            case 'PLAY_RESULT_ACK':
+                this.handlePlayAck(data.payload, data.id);
+                break;
+            case 'GET_BALANCE':
+                this.handleGetBalance(data.id);
+                break;
+            case 'GET_STATE':
+                this.handleGetState(data.id);
+                break;
+            case 'OPEN_DEPOSIT':
+                this.handleOpenDeposit();
+                break;
+            default:
+                if (this._config.debug) {
+                    console.log('[DevBridge] Unknown message type:', data.type);
+                }
+        }
+    }
+    handleGameReady(id) {
+        const initData = {
+            balance: this._balance,
+            currency: this._config.currency,
+            config: this._config.gameConfig,
+            session: this._config.session,
+            assetsUrl: this._config.assetsUrl,
+        };
+        this.delayedSend('INIT', initData, id);
+    }
+    handlePlayRequest(payload, id) {
+        const { action, bet, roundId } = payload;
+        // Deduct bet
+        this._balance -= bet;
+        this._roundCounter++;
+        // Generate result
+        const customResult = this._config.onPlay({ action, bet, roundId });
+        const totalWin = customResult.totalWin ?? (Math.random() > 0.6 ? bet * (1 + Math.random() * 10) : 0);
+        // Credit win
+        this._balance += totalWin;
+        const result = {
+            roundId: roundId ?? `dev-round-${this._roundCounter}`,
+            action,
+            balanceAfter: this._balance,
+            totalWin: Math.round(totalWin * 100) / 100,
+            data: customResult.data ?? {},
+            nextActions: customResult.nextActions ?? ['spin'],
+            session: customResult.session ?? null,
+            creditPending: false,
+        };
+        this.delayedSend('PLAY_RESULT', result, id);
+    }
+    handlePlayAck(_payload, _id) {
+        if (this._config.debug) {
+            console.log('[DevBridge] Play acknowledged');
+        }
+    }
+    handleGetBalance(id) {
+        this.delayedSend('BALANCE_RESPONSE', { balance: this._balance }, id);
+    }
+    handleGetState(id) {
+        this.delayedSend('STATE_RESPONSE', this._config.session, id);
+    }
+    handleOpenDeposit() {
+        if (this._config.debug) {
+            console.log('[DevBridge] 💰 Open deposit requested (mock: adding 1000)');
+        }
+        this._balance += 1000;
+        this.sendMessage('BALANCE_UPDATE', { balance: this._balance });
+    }
+    // ─── Communication ─────────────────────────────────────
+    delayedSend(type, payload, id) {
+        const delay = this._config.networkDelay;
+        if (delay > 0) {
+            setTimeout(() => this.sendMessage(type, payload, id), delay);
+        }
+        else {
+            this.sendMessage(type, payload, id);
+        }
+    }
+    sendMessage(type, payload, id) {
+        const message = {
+            __casino_bridge: true,
+            type,
+            payload,
+            id,
+        };
+        if (this._config.debug) {
+            console.log('[DevBridge] →', type, payload);
+        }
+        // Post to the same window (SDK listens on window)
+        window.postMessage(message, '*');
+    }
+}
+
+/**
+ * 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();
+ * ```
+ */
+class FPSOverlay {
+    _app;
+    _container;
+    _fpsText;
+    _visible = false;
+    _samples = [];
+    _maxSamples = 60;
+    _lastUpdate = 0;
+    _tickFn = null;
+    constructor(app) {
+        this._app = app;
+        this._container = new pixi_js.Container();
+        this._container.label = 'FPSOverlay';
+        this._container.zIndex = 99999;
+        this._fpsText = new pixi_js.Text({
+            text: 'FPS: --',
+            style: {
+                fontFamily: 'monospace',
+                fontSize: 14,
+                fill: 0x00ff00,
+                stroke: { color: 0x000000, width: 2 },
+            },
+        });
+        this._fpsText.x = 8;
+        this._fpsText.y = 8;
+        this._container.addChild(this._fpsText);
+    }
+    /** Show the FPS overlay */
+    show() {
+        if (this._visible)
+            return;
+        this._visible = true;
+        this._app.stage.addChild(this._container);
+        this._tickFn = (ticker) => {
+            this._samples.push(ticker.FPS);
+            if (this._samples.length > this._maxSamples) {
+                this._samples.shift();
+            }
+            // Update display every ~500ms
+            const now = Date.now();
+            if (now - this._lastUpdate > 500) {
+                const avg = this._samples.reduce((a, b) => a + b, 0) / this._samples.length;
+                const min = Math.min(...this._samples);
+                this._fpsText.text = [
+                    `FPS: ${Math.round(avg)} (min: ${Math.round(min)})`,
+                    `Frame: ${ticker.deltaMS.toFixed(1)}ms`,
+                ].join('\n');
+                this._lastUpdate = now;
+            }
+        };
+        this._app.ticker.add(this._tickFn);
+    }
+    /** Hide the FPS overlay */
+    hide() {
+        if (!this._visible)
+            return;
+        this._visible = false;
+        this._container.removeFromParent();
+        if (this._tickFn) {
+            this._app.ticker.remove(this._tickFn);
+            this._tickFn = null;
+        }
+    }
+    /** Toggle visibility */
+    toggle() {
+        if (this._visible) {
+            this.hide();
+        }
+        else {
+            this.show();
+        }
+    }
+    /** Destroy the overlay */
+    destroy() {
+        this.hide();
+        this._container.destroy({ children: true });
+    }
+}
+
+exports.AssetManager = AssetManager;
+exports.AudioManager = AudioManager;
+exports.BalanceDisplay = BalanceDisplay;
+exports.Button = Button;
+exports.DevBridge = DevBridge;
+exports.Easing = Easing;
+exports.EventEmitter = EventEmitter;
+exports.FPSOverlay = FPSOverlay;
+exports.GameApplication = GameApplication;
+exports.InputManager = InputManager;
+exports.Label = Label;
+exports.LoadingScene = LoadingScene;
+exports.Modal = Modal;
+exports.Panel = Panel;
+exports.ProgressBar = ProgressBar;
+exports.Scene = Scene;
+exports.SceneManager = SceneManager;
+exports.SpineHelper = SpineHelper;
+exports.StateMachine = StateMachine;
+exports.Timeline = Timeline;
+exports.Toast = Toast;
+exports.Tween = Tween;
+exports.ViewportManager = ViewportManager;
+exports.WinDisplay = WinDisplay;
+//# sourceMappingURL=index.cjs.js.map