@energy8platform/game-engine 0.16.0 → 0.18.0

package/dist/host.cjs.js

@@ -0,0 +1,3346 @@
+'use strict';
+
+var pixi_js = require('pixi.js');
+var platformCore = require('@energy8platform/platform-core');
+var loading = require('@energy8platform/platform-core/loading');
+var shell = require('@energy8platform/platform-core/shell');
+
+// ─── Scale Modes ───────────────────────────────────────────
+var ScaleMode;
+(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";
+})(ScaleMode || (ScaleMode = {}));
+// ─── Orientation ───────────────────────────────────────────
+var Orientation;
+(function (Orientation) {
+    Orientation["LANDSCAPE"] = "landscape";
+    Orientation["PORTRAIT"] = "portrait";
+    Orientation["ANY"] = "any";
+})(Orientation || (Orientation = {}));
+// ─── Transition Types ──────────────────────────────────────
+var TransitionType;
+(function (TransitionType) {
+    TransitionType["NONE"] = "none";
+    TransitionType["FADE"] = "fade";
+    TransitionType["SLIDE_LEFT"] = "slide-left";
+    TransitionType["SLIDE_RIGHT"] = "slide-right";
+})(TransitionType || (TransitionType = {}));
+
+/**
+ * Minimal typed event emitter.
+ * Used internally by GameApplication, SceneManager, AudioManager, etc.
+ *
+ * Supports `void` event types — events that carry no data can be emitted
+ * without arguments: `emitter.emit('eventName')`.
+ */
+// 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(...args) {
+        const [event, data] = args;
+        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).
+     * Uses PixiJS Ticker for consistent timing with other tweens.
+     */
+    static delay(ms) {
+        return new Promise((resolve) => {
+            let elapsed = 0;
+            const onTick = (ticker) => {
+                elapsed += ticker.deltaMS;
+                if (elapsed >= ms) {
+                    pixi_js.Ticker.shared.remove(onTick);
+                    resolve();
+                }
+            };
+            pixi_js.Ticker.shared.add(onTick);
+        });
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Reset the tween system — kill all tweens and remove the ticker.
+     * Useful for cleanup between game instances, tests, or hot-reload.
+     */
+    static reset() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+        if (Tween._tickerAdded) {
+            pixi_js.Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    }
+    // ─── 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 {
+    static MAX_TRANSITION_DEPTH = 10;
+    /** Root container that scenes are added to */
+    root;
+    registry = new Map();
+    stack = [];
+    _transitionDepth = 0;
+    /** Current viewport dimensions — set by ViewportManager */
+    _width = 0;
+    _height = 0;
+    /** @internal GameApplication reference — passed to scenes */
+    _app;
+    constructor(root) {
+        super();
+        if (root)
+            this.root = root;
+    }
+    /** @internal Set the root container (called by GameApplication after PixiJS init) */
+    setRoot(root) {
+        this.root = root;
+    }
+    /** @internal Set the app reference (called by GameApplication) */
+    setApp(app) {
+        this._app = app;
+    }
+    /** 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._transitionDepth > 0;
+    }
+    /**
+     * Navigate to a scene, replacing the entire stack.
+     */
+    async goto(key, data, transition) {
+        if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+            throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+        }
+        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) {
+        if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+            throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+        }
+        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;
+        }
+        if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+            throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+        }
+        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) {
+        if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+            throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+        }
+        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`);
+        }
+        const scene = new Ctor();
+        if (this._app) {
+            scene.__engineApp = this._app;
+        }
+        return scene;
+    }
+    async pushInternal(key, data, transition) {
+        this._transitionDepth++;
+        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);
+        // Push to stack BEFORE onEnter so currentKey is correct during initialization
+        this.stack.push({ scene, key });
+        await scene.onEnter?.(data);
+        this._transitionDepth--;
+    }
+    async popInternal(showTransition, transition) {
+        const entry = this.stack.pop();
+        if (!entry)
+            return;
+        this._transitionDepth++;
+        await entry.scene.onExit?.();
+        if (showTransition) {
+            await this.transitionOut(entry.scene.container, transition);
+        }
+        entry.scene.onDestroy?.();
+        entry.scene.container.destroy({ children: true });
+        this._transitionDepth--;
+    }
+    async transitionIn(container, config) {
+        const type = config?.type ?? TransitionType.NONE;
+        const duration = config?.duration ?? 300;
+        if (type === TransitionType.NONE || duration <= 0)
+            return;
+        if (type === TransitionType.FADE) {
+            container.alpha = 0;
+            await Tween.to(container, { alpha: 1 }, duration, config?.easing);
+        }
+        else if (type === TransitionType.SLIDE_LEFT) {
+            container.x = this._width;
+            await Tween.to(container, { x: 0 }, duration, config?.easing);
+        }
+        else if (type === TransitionType.SLIDE_RIGHT) {
+            container.x = -this._width;
+            await Tween.to(container, { x: 0 }, duration, config?.easing);
+        }
+    }
+    async transitionOut(container, config) {
+        const type = config?.type ?? TransitionType.FADE;
+        const duration = config?.duration ?? 300;
+        if (type === TransitionType.NONE || duration <= 0)
+            return;
+        if (type === TransitionType.FADE) {
+            await Tween.to(container, { alpha: 0 }, duration, config?.easing);
+        }
+        else if (type === TransitionType.SLIDE_LEFT) {
+            await Tween.to(container, { x: -this._width }, duration, config?.easing);
+        }
+        else if (type === 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();
+            if (this._globalMuted) {
+                this._soundModule.sound.muteAll();
+            }
+            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 with fade-out, start new music with fade-in
+        if (this._currentMusic && fadeDuration > 0) {
+            const prevAlias = this._currentMusic;
+            this._currentMusic = alias;
+            if (this._globalMuted || this._categories.music.muted)
+                return;
+            // Fade out the previous track
+            this.fadeVolume(prevAlias, this._categories.music.volume, 0, fadeDuration, () => {
+                try {
+                    sound.stop(prevAlias);
+                }
+                catch { /* ignore */ }
+            });
+            // Start new track at zero volume, fade in
+            try {
+                sound.play(alias, {
+                    volume: 0,
+                    loop: true,
+                });
+                this.fadeVolume(alias, 0, this._categories.music.volume, fadeDuration);
+            }
+            catch (e) {
+                console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
+            }
+        }
+        else {
+            // No crossfade — instant switch
+            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 ───────────────────────────────────────────
+    /**
+     * Smoothly fade a sound's volume from `fromVol` to `toVol` over `durationMs`.
+     */
+    fadeVolume(alias, fromVol, toVol, durationMs, onComplete) {
+        if (!this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        const startTime = Date.now();
+        const tick = () => {
+            const elapsed = Date.now() - startTime;
+            const t = Math.min(elapsed / durationMs, 1);
+            const vol = fromVol + (toVol - fromVol) * t;
+            try {
+                sound.volume(alias, vol);
+            }
+            catch { /* ignore */ }
+            if (t < 1) {
+                requestAnimationFrame(tick);
+            }
+            else {
+                onComplete?.();
+            }
+        };
+        requestAnimationFrame(tick);
+    }
+    applyVolumes() {
+        if (!this._soundModule)
+            return;
+        const { sound } = this._soundModule;
+        // Global mute is owned by sound.muteAll()/unmuteAll() (context.muted),
+        // not by volumeAll — mixing both leaves mute un-undoable after reload.
+        sound.volumeAll = 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
+        }
+    }
+}
+
+/**
+ * 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;
+    // Viewport transform (set by ViewportManager via setViewportTransform)
+    _viewportScale = 1;
+    _viewportOffsetX = 0;
+    _viewportOffsetY = 0;
+    // 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());
+    }
+    /**
+     * Update the viewport transform used for DOM→world coordinate mapping.
+     * Called automatically by GameApplication when ViewportManager emits resize.
+     */
+    setViewportTransform(scale, offsetX, offsetY) {
+        this._viewportScale = scale;
+        this._viewportOffsetX = offsetX;
+        this._viewportOffsetY = offsetY;
+    }
+    /**
+     * Convert a DOM canvas position to game-world coordinates,
+     * accounting for viewport scaling and offset.
+     */
+    getWorldPosition(canvasX, canvasY) {
+        return {
+            x: (canvasX - this._viewportOffsetX) / this._viewportScale,
+            y: (canvasY - this._viewportOffsetY) / this._viewportScale,
+        };
+    }
+    /** 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 });
+    };
+}
+
+/**
+ * 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 = 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 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 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 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 === ScaleMode.STRETCH
+            ? Math.min(containerWidth / designWidth, containerHeight / designHeight)
+            : scale;
+        this._app.stage.scale.set(stageScale);
+        // Center the stage for FIT mode
+        if (scaleMode === 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 === 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 ? Orientation.LANDSCAPE : 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;
+        // Remove fallback window resize listener if it was used
+        window.removeEventListener('resize', this.onWindowResize);
+        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;
+    }
+}
+
+/**
+ * Build the loading scene variant of the logo SVG.
+ * Uses unique IDs (prefixed with 'ls') to avoid collisions with CSSPreloader.
+ */
+function buildLoadingLogoSVG() {
+    return loading.buildLogoSVG({
+        idPrefix: 'ls',
+        svgStyle: 'width:100%;height:auto;',
+        clipRectId: 'ge-loader-rect',
+        textId: 'ge-loader-pct',
+        textContent: '0%',
+    });
+}
+/**
+ * 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">
+        ${buildLoadingLogoSVG()}
+      </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(loading.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, always passing the engine reference
+        await this._engine.scenes.goto(this._targetScene, {
+            engine: this._engine,
+            ...(this._targetData && typeof this._targetData === 'object' ? this._targetData : { data: this._targetData }),
+        });
+    }
+}
+
+/**
+ * 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 });
+    }
+}
+
+/**
+ * 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;
+    /** Input manager */
+    input;
+    /** Viewport manager */
+    viewport;
+    /** SDK instance (null in offline mode) */
+    sdk = null;
+    /** FPS overlay instance (only when debug: true) */
+    fpsOverlay = null;
+    /** Data received from SDK initialization */
+    initData = null;
+    /** Platform session (SDK + optional DevBridge). null until start() runs. */
+    platformSession = null;
+    /** Branded game shell (only when config.shell is set). */
+    shell;
+    /** Configuration */
+    config;
+    // ─── Private state ──────────────────────────────────────
+    _running = false;
+    _destroyed = false;
+    _container = null;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            designWidth: 1920,
+            designHeight: 1080,
+            scaleMode: ScaleMode.FIT,
+            orientation: 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)
+            loading.createCSSPreloader(this._container, this.config.loading);
+            // 3. Initialize PixiJS
+            await this.initPixi();
+            // 4. Initialize SDK (if enabled)
+            await this.initSDK();
+            // 4b. Mount the branded game shell after the SDK handshake (optional)
+            if (this.config.shell) {
+                const { createGameShell } = await import('@energy8platform/platform-core/shell');
+                this.shell = createGameShell(this.config.shell);
+            }
+            // 5. Merge design dimensions from SDK config
+            this.applySDKConfig();
+            // 6. Initialize sub-systems
+            this.initSubSystems();
+            this.emit('initialized');
+            // 7. Remove CSS preloader, show Canvas loading screen
+            loading.removeCSSPreloader(this._container);
+            // 8. Load assets with loading screen
+            await this.loadAssets(firstScene, sceneData);
+            this.emit('loaded');
+            // 9. Start the game loop
+            this._running = true;
+            this.emit('started');
+        }
+        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.
+     */
+    async destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        this._running = false;
+        if (this.shell) {
+            const { removeGameShell } = await import('@energy8platform/platform-core/shell');
+            await removeGameShell();
+            this.shell = undefined;
+        }
+        this.scenes?.destroy();
+        this.input?.destroy();
+        this.audio?.destroy();
+        this.viewport?.destroy();
+        this.platformSession?.destroy();
+        this.app?.destroy(true, { children: true, texture: true });
+        this.emit('destroyed');
+        this.removeAllListeners();
+    }
+    // ─── 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 = {
+            preference: 'webgl',
+            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() {
+        // Delegate the SDK handshake (and any optional in-process DevBridge
+        // wiring) to platform-core. The session forwards SDK events upward.
+        this.platformSession = await platformCore.createPlatformSession({ sdk: this.config.sdk });
+        this.sdk = this.platformSession.sdk;
+        this.initData = this.platformSession.initData;
+        this.platformSession.on('error', (err) => {
+            this.emit('error', err);
+        });
+        this.platformSession.on('balanceUpdate', (data) => {
+            this.emit('balanceUpdate', data);
+        });
+    }
+    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);
+        // Input Manager
+        this.input = new InputManager(this.app.canvas);
+        // 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);
+        this.scenes.setApp(this);
+        // Wire viewport resize → scene manager + input manager
+        this.viewport.on('resize', ({ width, height, scale }) => {
+            this.scenes.resize(width, height);
+            this.input.setViewportTransform(scale, this.app.stage.x, this.app.stage.y);
+            this.emit('resize', { width, height });
+        });
+        this.viewport.on('orientationChange', (orientation) => {
+            this.emit('orientationChange', orientation);
+        });
+        // Wire scene changes → engine event
+        this.scenes.on('change', ({ from, to }) => {
+            this.emit('sceneChange', { from, to });
+        });
+        // 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();
+        // Enable FPS overlay in debug mode
+        if (this.config.debug) {
+            this.fpsOverlay = new FPSOverlay(this.app);
+            this.fpsOverlay.show();
+        }
+    }
+    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,
+        });
+    }
+}
+
+// packages/game-engine/src/scenes/IntroScene.ts
+/**
+ * Reusable splash scene: shows a title (or logo) + "tap to start", then advances.
+ *
+ * The host no longer special-cases the intro. Navigation works like every other
+ * scene: the host injects `goto(key)` into this scene's start data. On tap this
+ * scene calls `onStart` if the game supplied one, otherwise `goto(next ?? 'game')`.
+ * (The built-in can't know the game's scene key generically, so it falls back to
+ * the conventional 'game' key — override via `next`. Scaffold-generated intros
+ * skip this primitive and call `goto('game')` directly.)
+ */
+class IntroScene extends Scene {
+    layer;
+    async onEnter(data) {
+        const cfg = (data ?? {});
+        const start = () => cfg.onStart ? cfg.onStart() : cfg.goto?.(cfg.next ?? 'game');
+        const layer = new pixi_js.Container();
+        this.layer = layer;
+        this.container.addChild(layer);
+        const title = new pixi_js.Text({
+            text: cfg.title ?? 'PLAY',
+            style: { fill: 0xffffff, fontSize: 96, fontFamily: 'Inter', align: 'center' },
+        });
+        title.anchor.set(0.5);
+        title.position.set(960, 460);
+        layer.addChild(title);
+        if (cfg.tapToStart !== false) {
+            const hint = new pixi_js.Text({
+                text: 'Tap to start',
+                style: { fill: 0xffd24a, fontSize: 36, fontFamily: 'Inter' },
+            });
+            hint.anchor.set(0.5);
+            hint.position.set(960, 600);
+            layer.addChild(hint);
+        }
+        // full-screen tap target
+        const hit = new pixi_js.Graphics().rect(0, 0, 1920, 1080).fill({ color: 0x000000, alpha: 0.001 });
+        hit.eventMode = 'static';
+        hit.cursor = 'pointer';
+        hit.once('pointerdown', () => start());
+        layer.addChild(hit);
+    }
+    onExit() {
+        this.layer?.destroy({ children: true });
+        this.layer = undefined;
+    }
+}
+
+/**
+ * Pure: map host options to a GameApplicationConfig with sane defaults.
+ * `isStakeNow` is computed by the orchestrator (kept out of here so this
+ * stays a pure, renderer-free function).
+ */
+function buildAppConfig(opts, isStakeNow) {
+    return {
+        container: opts.container ?? '#game',
+        designWidth: opts.design?.width ?? 1920,
+        designHeight: opts.design?.height ?? 1080,
+        scaleMode: opts.scaleMode ?? ScaleMode.FILL,
+        orientation: opts.orientation ?? Orientation.ANY,
+        loading: opts.loading ?? { tapToStart: false, minDisplayTime: 600 },
+        manifest: opts.manifest,
+        audio: opts.audio,
+        pixi: opts.pixi,
+        sdk: { devMode: isStakeNow || (opts.dev ?? false) },
+        debug: opts.dev ?? false,
+    };
+}
+
+/** Preload web fonts so Pixi text rasterizes with the right glyphs. Never throws. */
+async function loadFonts(specs) {
+    if (!specs || specs.length === 0)
+        return;
+    try {
+        await Promise.all(specs.map((s) => document.fonts.load(s)));
+        await document.fonts.ready;
+    }
+    catch {
+        /* font CDN unreachable → fall back to system fonts */
+    }
+}
+/** Smoother default downscaling for art-heavy slots. Pixel-art games omit this. */
+function applyTextureDefaults() {
+    pixi_js.TextureSource.defaultOptions.autoGenerateMipmaps = true;
+}
+/** Idempotent double-boot guard. Returns true the first time, false thereafter. */
+function bootGuard(flag = '__e8SlotBooted__') {
+    const w = window;
+    if (w[flag])
+        return false;
+    w[flag] = true;
+    return true;
+}
+
+// packages/game-engine/src/host/fatalError.ts
+/** Marker id so the modal is idempotent (first one wins; later calls replace its message). */
+const FATAL_ID = 'e8-fatal-error';
+/** Pure: extract a human-readable message from any thrown value / event reason. */
+function fatalMessage(input) {
+    if (input == null)
+        return 'Something went wrong.';
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof Error)
+        return input.message || input.name || 'Something went wrong.';
+    const anyIn = input;
+    if (typeof anyIn.message === 'string' && anyIn.message)
+        return anyIn.message;
+    if (anyIn.reason != null)
+        return fatalMessage(anyIn.reason);
+    try {
+        return String(input);
+    }
+    catch {
+        return 'Something went wrong.';
+    }
+}
+/** Pure: build the modal overlay element (error text + a Reload button). */
+function buildFatalErrorModal(message, onReload) {
+    const overlay = document.createElement('div');
+    overlay.id = FATAL_ID;
+    overlay.setAttribute('role', 'alertdialog');
+    overlay.style.cssText =
+        'position:fixed;inset:0;display:flex;align-items:center;justify-content:center;' +
+            'background:rgba(10,5,4,0.92);z-index:99999;font-family:system-ui,sans-serif;padding:24px';
+    const card = document.createElement('div');
+    card.style.cssText =
+        'max-width:420px;width:100%;background:#1a0f0a;border:1px solid #5a3a1e;border-radius:12px;' +
+            'padding:28px 24px;text-align:center;box-shadow:0 12px 40px rgba(0,0,0,0.6)';
+    const text = document.createElement('div');
+    text.className = 'e8-fatal-message';
+    text.style.cssText = 'color:#f0c98a;font:600 17px/1.4 system-ui,sans-serif;margin-bottom:22px';
+    text.textContent = message;
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'e8-fatal-reload';
+    button.textContent = 'Reload';
+    button.style.cssText =
+        'cursor:pointer;border:none;border-radius:8px;padding:12px 28px;font:600 15px system-ui,sans-serif;' +
+            'color:#1a0f0a;background:#f0c98a';
+    button.addEventListener('click', onReload);
+    card.appendChild(text);
+    card.appendChild(button);
+    overlay.appendChild(card);
+    return overlay;
+}
+/**
+ * Render a blocking fatal-error modal with a Reload button. Idempotent: if a modal is already
+ * shown, its message is replaced instead of stacking a second overlay.
+ */
+function showFatalError(container, message) {
+    if (typeof document === 'undefined')
+        return;
+    const host = typeof container === 'string'
+        ? document.querySelector(container) ?? document.body
+        : container;
+    const existing = document.getElementById(FATAL_ID);
+    if (existing) {
+        const msg = existing.querySelector('.e8-fatal-message');
+        if (msg)
+            msg.textContent = message;
+        return;
+    }
+    const overlay = buildFatalErrorModal(message, () => {
+        try {
+            location.reload();
+        }
+        catch {
+            /* no-op in non-browser environments */
+        }
+    });
+    host.appendChild(overlay);
+}
+/**
+ * Install global handlers so ANY uncaught error or unhandled promise rejection surfaces the
+ * fatal modal (game devs don't have to handle errors themselves). `fatal` defaults to the
+ * built-in modal targeting `container`. Returns a disposer that removes the listeners.
+ */
+function installGlobalErrorHandlers(container, fatal = (m) => showFatalError(container, m)) {
+    if (typeof window === 'undefined')
+        return () => { };
+    const onError = (e) => fatal(fatalMessage(e.error ?? e.message));
+    const onRejection = (e) => fatal(fatalMessage(e.reason));
+    window.addEventListener('error', onError);
+    window.addEventListener('unhandledrejection', onRejection);
+    return () => {
+        window.removeEventListener('error', onError);
+        window.removeEventListener('unhandledrejection', onRejection);
+    };
+}
+
+// packages/game-engine/src/host/createSlotGame.ts
+/**
+ * One-call slot bootstrap: preboot → (optional Stake bridge) → GameApplication
+ * → register scene → start. Collapses the per-game main.ts boilerplate.
+ *
+ * Not unit-tested: GameApplication.init() drives Pixi, which hangs in headless
+ * environments. The pure helpers it sequences are unit-tested individually.
+ */
+async function createSlotGame(opts) {
+    if (!bootGuard())
+        throw new Error('createSlotGame() called more than once');
+    if (opts.textureDefaults)
+        applyTextureDefaults();
+    await loadFonts(opts.fonts);
+    // Declared up front so `fatal` can route errors through the shell's own modal once it exists.
+    let shell = null;
+    const fatal = (message) => {
+        if (opts.onFatalError)
+            return opts.onFatalError(message);
+        // Once the shell is up, use ITS branded modal (consistent chrome, social vocabulary, fit
+        // scaling) rather than the bare DOM fallback. Errors thrown before the shell boots (asset
+        // load, SDK handshake) still get the standalone overlay.
+        if (shell) {
+            shell.openModal({
+                availableClose: false,
+                title: shell.t('Something went wrong'),
+                body: shell.t(message),
+                actions: [{ title: shell.t('Reload'), on: () => { try {
+                            location.reload();
+                        }
+                        catch { /* non-browser */ } } }],
+            });
+            return;
+        }
+        showFatalError(opts.container ?? '#game', message);
+    };
+    // Global safety net: surface ANY uncaught error / unhandled rejection (e.g. an
+    // `Uncaught (in promise) SDKError` on spin) through the same fatal modal so games
+    // don't have to handle errors themselves. Honours the onFatalError override.
+    installGlobalErrorHandlers(opts.container ?? '#game', fatal);
+    let stakeBridge = null;
+    let isStakeNow = false;
+    if (opts.stake) {
+        const { isStakeLaunch } = await import('@energy8platform/stake-bridge/detect');
+        isStakeNow = isStakeLaunch(location.href);
+        if (isStakeNow) {
+            try {
+                const { StakeBridge } = await import('@energy8platform/stake-bridge');
+                stakeBridge = new StakeBridge({
+                    devMode: true,
+                    // In the dev harness the iframe is served over http and the dev-RGS
+                    // lives at the same (http) origin; force the matching scheme so
+                    // RGSClient can reach it. Prod (https) is unaffected.
+                    protocol: location.protocol === 'http:' ? 'http' : 'https',
+                    adapter: opts.stake.adapter,
+                    modeMap: opts.model.modeMap,
+                    gameId: opts.model.spec.id,
+                    url: location.href,
+                });
+                await stakeBridge.ready();
+            }
+            catch (err) {
+                fatal('Could not connect to the game server. Please reload.');
+                throw err;
+            }
+        }
+    }
+    const game = new GameApplication(buildAppConfig(opts, isStakeNow));
+    // Register EVERY scene up front so any of them can navigate to any other.
+    for (const { key, scene } of opts.scenes)
+        game.scenes.register(key, scene);
+    // Navigation injected into the start data of every scene: a scene reads `goto`
+    // from its `onEnter(data)` and calls it to switch scenes (intro → game, etc.).
+    const goto = (key, data) => {
+        void game.scenes.goto(key, { ...data, goto });
+    };
+    // Pick the start scene from the ordered list + launch mode: a replay launch skips any leading
+    // `skipOnReplay` scene (the intro) and starts directly on the game scene.
+    const { resolveStartScene } = await Promise.resolve().then(function () { return sceneStart; });
+    const startScene = resolveStartScene(opts.scenes, !!stakeBridge?.isReplay, opts.startScene);
+    try {
+        await game.start(startScene, { ...opts.startData, goto });
+    }
+    catch (err) {
+        fatal('Could not start the game.');
+        throw err;
+    }
+    let currentBet = opts.model.spec.defaultBet ?? opts.model.spec.betLevels[0];
+    // Build slotPlay FIRST — bindGameScene() needs it to be in scope.
+    const { createSlotPlay, enrichRoundMeta } = await Promise.resolve().then(function () { return slotPlay; });
+    /** The current scene IFF it implements the SlotSceneController contract (duck-typed on
+     *  `present`). The host drives the play loop against whichever scene is current. */
+    const gameScene = () => {
+        const s = game.scenes.current?.scene;
+        return typeof s?.present === 'function'
+            ? s
+            : undefined;
+    };
+    const { runRound } = await Promise.resolve().then(function () { return runRound$1; });
+    const { createBalanceGate } = await Promise.resolve().then(function () { return balanceGate; });
+    const { createFreeSpinsCounter } = await Promise.resolve().then(function () { return freeSpinsCounter; });
+    const { resolvePlayError } = await Promise.resolve().then(function () { return playError; });
+    // slotPlay references shell via closure — define it after shell is assigned below.
+    // We use a late-binding wrapper so the closure captures the variable, not null.
+    const slotPlay$1 = createSlotPlay({
+        play: (p) => game.platformSession.play(p),
+        normalize: opts.normalize,
+        // ACK the result AFTER the scene animates it (the scene calls host.ack()). On Stake this
+        // triggers /wallet/end-round so a winning round settles post-animation instead of staying
+        // open and blocking the next spin.
+        ack: (raw) => game.platformSession.playAck(raw),
+    });
+    if (opts.shell) {
+        const { createGameShell } = await import('@energy8platform/platform-core/shell');
+        const { buildShellConfig } = await Promise.resolve().then(function () { return shellConfig; });
+        const { resolveReplayBonusId } = await Promise.resolve().then(function () { return replay; });
+        const ps = game.platformSession;
+        const balance = game.initData?.balance ?? 0;
+        const isReplay = !!stakeBridge?.isReplay;
+        const mode = isReplay ? 'replay' : 'base';
+        // initData.config carries the Stake bridge's currency/social/disclaimer surface (GameConfigData);
+        // all are absent in non-stake/dev launches → graceful fallbacks downstream.
+        const initData = game.initData;
+        const config = initData?.config;
+        const { resolveCurrency } = await Promise.resolve().then(function () { return shellConfig; });
+        // SINGLE source of truth for the symbol: the Stake bridge already puts a full CurrencyMetaData
+        // (symbol + placement) on initData.config.currency. In the non-stake/devBridge path that meta
+        // is absent and we only have the spec's currency CODE — resolve it through the SAME table
+        // (stake-bridge's lookupCurrency) so e.g. 'EUR' renders as '€', not the literal text "EUR".
+        // stake-bridge ships with every scaffold; if it's somehow absent we degrade to the code.
+        let currencyMeta = config?.currency;
+        if (!currencyMeta?.symbol && opts.model.spec.currency) {
+            try {
+                const { lookupCurrency } = await import('@energy8platform/stake-bridge');
+                currencyMeta = lookupCurrency(opts.model.spec.currency);
+            }
+            catch { /* stake-bridge not installed — resolveCurrency falls back to the code */ }
+        }
+        const runtime = {
+            balance,
+            currency: resolveCurrency(currencyMeta, opts.model.spec.currency),
+            language: initData?.lang,
+            mode,
+            social: config?.socialMode,
+            disclaimerLines: config?.disclaimerLines,
+            jurisdiction: config?.jurisdiction,
+            // Currency-specific ladder + per-currency default from /wallet/authenticate (Stake);
+            // absent on dev/devBridge → buildShellConfig falls back to the spec.
+            betLevels: config?.betLevels,
+            defaultBet: config?.stake?.defaultBetLevel ?? config?.defaultBet,
+        };
+        if (opts.dev) {
+            // Dev-only diagnostic. Logged as PLAIN STRINGS (not collapsed objects) so the values are
+            // readable in the console without expanding. If the shown symbol is a bare code ("EUR")
+            // instead of a glyph ("€"), paste this whole line.
+            const cc = config?.currency;
+            console.info(`[e8] currency → bridge.code=${cc?.code ?? '∅'} bridge.symbol=${cc?.symbol ?? '∅'} ` +
+                `| spec=${opts.model.spec.currency ?? '∅'} ` +
+                `| RESOLVED.symbol=${runtime.currency?.symbol ?? '∅'} pos=${runtime.currency?.position ?? '∅'}`);
+        }
+        shell = createGameShell(buildShellConfig(opts.shell, opts.model, runtime));
+        // The gate tracks the live wallet (for the affordability guard) but only PAINTS the balance per
+        // the HUD-timing rule: the debit is buffered during play→present and shown at afterPresent; the
+        // async win credit (/wallet/end-round, after the final ack) paints when it lands. `balanceGate`
+        // is the single source for both the displayed balance and `ensureAffordable`.
+        const balanceGate = createBalanceGate((b) => shell.setBalance(b), balance);
+        ps?.on('balanceUpdate', (d) => { balanceGate.onBalance(d.balance); });
+        // Live turbo level (0..3) — read fresh on each ctx.turbo access so a mid-round toggle is honoured.
+        let currentTurbo = shell.state.turbo;
+        shell.on('turboChange', (level) => { currentTurbo = level; });
+        const roleOf = (action) => opts.model.spec.actions[action]?.role;
+        const makeContext = (action) => ({
+            bet: currentBet,
+            action,
+            mode: opts.model.modeMap[action] ?? action.toUpperCase(),
+            formatAmount: (v) => shell.formatWin(v),
+            get turbo() { return currentTurbo; },
+        });
+        // Play-error + connection handling. A play rejection is classified into a player-facing modal
+        // (ACTIVE_SESSION_EXISTS → Reload, etc.) instead of a misleading reconnect overlay; the reconnect
+        // overlay is suppressed while a play-error modal owns the screen.
+        let playErrorOpen = false;
+        let stopAutoplay = () => { }; // wired to the autoplay loop once it's created (below)
+        const showPlayError = (err) => {
+            stopAutoplay(); // a play error halts an autoplay run (the .catch swallows, so stop explicitly)
+            const v = resolvePlayError(err);
+            playErrorOpen = true;
+            shell.openModal({
+                availableClose: !v.reload,
+                title: shell.t(v.title),
+                body: shell.t(v.body),
+                actions: v.reload
+                    ? [{ title: shell.t('Reload'), on: () => { try {
+                                window.location.reload();
+                            }
+                            catch { /* non-browser */ } } }]
+                    : [{ title: shell.t('OK'), on: () => { playErrorOpen = false; } }],
+            });
+        };
+        ps?.on('connectionStateChanged', (s) => {
+            if (s.status === 'restored') {
+                if (!playErrorOpen)
+                    shell.closeModal();
+                return;
+            }
+            if (playErrorOpen)
+                return; // a play-error modal owns the screen — don't mask it with "reconnecting"
+            shell.openModal({
+                availableClose: false,
+                title: shell.t('Reconnecting…'),
+                body: shell.t('Lost connection to the game server. Trying to reconnect…'),
+            });
+        });
+        /** Drive a full round (trigger + drain) against the current scene. HUD readouts (win + balance)
+         *  update only AFTER each present(), per the HUD-timing requirement. */
+        const playRound = (action) => {
+            const scene = gameScene();
+            if (!scene)
+                return;
+            // Per-round free-spins state: the shell enters FS mode on bonus-enter and shows current/total
+            // (growing on retriggers) + cumulative win per spin. `inBonus` gates the per-spin counter so
+            // the trigger segment (presented before onBonusEnter) doesn't count as a free spin.
+            let inBonus = false;
+            let prevWin = 0; // cumulative win up to the previous segment — the WIN readout shows the delta
+            const fsCounter = createFreeSpinsCounter();
+            shell.setBusy(true); // block re-spin / spacebar while the round plays out
+            // RETURN the promise: the replay modal awaits onReplay() and only reopens once the round's
+            // animation has finished — returning void would reopen it instantly, over a running animation.
+            return runRound({
+                // Suppress the debit paint from play() until this segment's afterPresent (HUD timing).
+                play: (a, b, rid) => { balanceGate.beginPlay(); return slotPlay$1.play(a, b, rid); },
+                ack: slotPlay$1.ack,
+                scene,
+                context: makeContext,
+                roleOf,
+                afterPresent: (r) => {
+                    // WIN readout = THIS spin's win (cumulative delta); the cumulative total goes to the
+                    // free-spins counter (totalWin) below, not the WIN readout.
+                    shell.setWin(r.totalWin - prevWin);
+                    prevWin = r.totalWin;
+                    balanceGate.afterPresent();
+                    if (inBonus)
+                        shell.setFreeSpins(fsCounter.spin(r.freeSpins?.awarded ?? 0, r.totalWin));
+                },
+                onBonusEnter: async (trigger, ctx) => {
+                    inBonus = true;
+                    shell.setMode('freeSpins');
+                    shell.setFreeSpins(fsCounter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0));
+                    await scene.onBonusEnter?.(trigger, ctx);
+                },
+                onBonusExit: async (last, ctx) => {
+                    inBonus = false;
+                    await scene.onBonusExit?.(last, ctx);
+                    shell.setMode('base');
+                },
+            }, action).catch(showPlayError).finally(() => shell.setBusy(false));
+        };
+        /**
+         * Drain a recovered open round to completion and settle it. Plays EVERY remaining segment from
+         * the bonus start (Continue animates each; Finish fast-forwards without animation), reaching the
+         * final ack so /wallet/end-round credits the win — fixing the old resume that presented one
+         * snapshot and never settled. The original trigger is gone on reload, so the FS counter here uses
+         * the bridge's session counts; FS mode is entered/exited around the drain.
+         */
+        const resumeDrain = async (firstRaw, animate) => {
+            const scene = gameScene();
+            if (!scene || !ps)
+                return;
+            const ctx = makeContext(firstRaw.action ?? 'spin');
+            const fsView = (raw, totalWin) => {
+                const s = raw.session;
+                if (!s)
+                    return null;
+                // The bridge session counts ALL segments incl. the trigger (segment 0); the free-spins
+                // counter is over FREE spins only, so drop the one trigger segment → 1/10, not 2/11.
+                const played = s.spinsPlayed ?? 0;
+                const current = Math.max(0, played - 1);
+                const total = Math.max(0, played + (s.spinsRemaining ?? 0) - 1);
+                return { current, total, totalWin };
+            };
+            let raw = firstRaw;
+            let r = enrichRoundMeta(opts.normalize(raw), raw);
+            let inBonus = false;
+            let prevWin = 0; // cumulative win up to the previous segment — WIN readout shows the delta
+            const applySegment = async () => {
+                // A recovered open round with remaining segments is a bonus → show FS mode + counter.
+                if (!inBonus && !r.complete) {
+                    inBonus = true;
+                    shell.setMode('freeSpins');
+                }
+                if (animate)
+                    await scene.present(r, ctx);
+                if (inBonus) {
+                    const v = fsView(raw, r.totalWin);
+                    if (v)
+                        shell.setFreeSpins(v);
+                }
+                shell.setWin(r.totalWin - prevWin); // THIS spin's win, not the cumulative bonus total
+                prevWin = r.totalWin;
+                ps.playAck(raw); // settles via /wallet/end-round on the FINAL segment
+            };
+            shell.setBusy(true); // block input while the recovered round drains
+            try {
+                await applySegment();
+                while (!r.complete && r.nextActions && r.nextActions.length > 0) {
+                    raw = (await ps.play({ action: r.nextActions[0], bet: ctx.bet, roundId: r.roundId }));
+                    r = enrichRoundMeta(opts.normalize(raw), raw);
+                    await applySegment();
+                }
+                if (inBonus)
+                    shell.setMode('base');
+            }
+            finally {
+                shell.setBusy(false);
+            }
+        };
+        if (mode === 'base') {
+            let activeFeature = null;
+            shell.on('featureActivate', ({ id }) => { activeFeature = id; });
+            shell.on('featureDeactivate', ({ id: _id }) => { activeFeature = null; });
+            const { stakeForAction } = await Promise.resolve().then(function () { return shellConfig; });
+            // Guard a play: if the stake exceeds the balance, show a shell modal and DON'T play.
+            const ensureAffordable = (action) => {
+                if (stakeForAction(opts.model, action, currentBet) <= balanceGate.balance + 1e-9)
+                    return true;
+                shell.openModal({
+                    availableClose: true,
+                    title: shell.t('Insufficient balance'),
+                    body: shell.t('You don’t have enough balance for this bet. Lower your bet or top up.'),
+                    actions: [{ title: shell.t('OK') }],
+                });
+                return false;
+            };
+            shell.on('spin', () => {
+                const action = activeFeature ?? 'spin';
+                if (!ensureAffordable(action))
+                    return;
+                void playRound(action);
+            });
+            shell.on('betChange', (bet) => { currentBet = bet; });
+            shell.on('buyBonusSelect', ({ id }) => {
+                if (!ensureAffordable(id))
+                    return;
+                void playRound(id);
+            });
+            // Autoplay: the shell owns the picker/confirm/STOP/counter/lockout (all driven by state.autoplay);
+            // the host just runs the loop and pushes the per-spin remaining back via setAutoplay.
+            const { createAutoplayLoop } = await Promise.resolve().then(function () { return autoplay; });
+            const autoplay$1 = createAutoplayLoop({
+                resolveAction: () => activeFeature ?? 'spin',
+                canAfford: (a) => ensureAffordable(a),
+                playRound: (a) => Promise.resolve(playRound(a)),
+                onState: (s) => shell.setAutoplay(s),
+            });
+            stopAutoplay = () => autoplay$1.stop();
+            shell.on('autoplayStart', (o) => autoplay$1.start(o?.remaining ?? 0));
+            shell.on('autoplayStop', () => autoplay$1.stop());
+            // Resume offer: when the game scene is (or becomes) current on a reload, ask the host whether
+            // a round is still open. If so, offer Continue (replay its animation, then settle) or Finish
+            // (settle now). Settlement is the same playAck path a normal spin uses. Runs at most once.
+            let resumeOffered = false;
+            const offerResume = async () => {
+                if (resumeOffered || !shell || !gameScene())
+                    return;
+                resumeOffered = true;
+                let snap = null;
+                try {
+                    snap = await ps?.getState() ?? null;
+                }
+                catch {
+                    snap = null;
+                }
+                if (!snap)
+                    return;
+                shell.openModal({
+                    availableClose: false,
+                    title: shell.t('Unfinished round'),
+                    body: shell.t('You have an unfinished round. Continue it or finish it now?'),
+                    actions: [
+                        // Continue: replay the round from the start with animation, then settle.
+                        { title: shell.t('Continue'), on: () => { void resumeDrain(snap, true); } },
+                        // Finish: fast-forward the remaining segments (no animation) to settle the win now.
+                        { title: shell.t('Finish'), on: () => { void resumeDrain(snap, false); } },
+                    ],
+                });
+            };
+            game.scenes.on('change', () => { void offerResume(); });
+            void offerResume();
+        }
+        else {
+            const stakeMode = stakeBridge?.replayMode ?? 'BASE';
+            const bonusId = resolveReplayBonusId(opts.model, stakeMode);
+            // The replayed round's OWN bet + payout (fetched up front per Stake rules), not the spec's
+            // default bet — otherwise the replay modal always shows bet 1.
+            const replayBet = stakeBridge?.replayBet || currentBet;
+            currentBet = replayBet;
+            // onReplay only spins — the shell reopens the modal after it resolves; never call openReplay inside onReplay (double-open).
+            shell.openReplay({
+                bonusId,
+                bet: replayBet,
+                payoutMultiplier: stakeBridge?.replayPayoutMultiplier ?? 0,
+                onReplay: () => playRound(bonusId),
+            });
+        }
+    }
+    return { game, stakeBridge, shell };
+}
+
+// packages/game-engine/src/host/shellConfig.ts
+/**
+ * Apply jurisdiction restrictions over the resolved shell features, in place. A restriction ALWAYS
+ * wins over the author's intent (a forbidden control must stay off even if the game enabled it).
+ */
+function applyJurisdiction(features, j) {
+    if (!j)
+        return;
+    if (j.disabledTurbo)
+        features.turbo = 0;
+    else if (j.disabledSuperTurbo && features.turbo > 1)
+        features.turbo = 1;
+    if (j.disabledSpacebar)
+        features.spacebar = false;
+    if (j.disabledAutoplay)
+        features.autoplay = null;
+    if (j.disabledBuyFeature)
+        features.buyBonus = false;
+}
+/**
+ * Resolve the shell `CurrencyConfig` from the SAME data the Stake bridge uses — the
+ * `CurrencyMetaData` it puts on `initData.config.currency` (symbol + placement from
+ * `symbolAfter`). No second symbol table lives here.
+ *
+ * Fallback chain (dev/devBridge with no Stake meta): `initData.config.currency`
+ * → the spec's currency `code` (neutral `{ symbol: code, position: 'left' }`)
+ * → `{ symbol: '€', position: 'left' }`.
+ */
+/** Extra precision for WIN / TOTAL-WIN readouts so small-bet wins (e.g. 0.0041 on a 0.01 bet) are
+ *  not rounded away to 0.00. Balance / bet stay at the currency's own decimals (`minDecimals`). */
+const WIN_MAX_DECIMALS = 4;
+/** Attach decimals: `minDecimals` (balance/bet/prices, fixed) = the currency's decimals; `maxDecimals`
+ *  (win/total-win, variable, trailing zeros trimmed) = up to WIN_MAX_DECIMALS — but only when the
+ *  currency actually has fraction digits (a 0-decimal currency like JPY keeps wins integer). */
+function withDecimals(base, decimals) {
+    return {
+        ...base,
+        minDecimals: decimals,
+        maxDecimals: decimals > 0 ? Math.max(decimals, WIN_MAX_DECIMALS) : 0,
+    };
+}
+function resolveCurrency(meta, specCurrency) {
+    const hasMeta = !!(meta && meta.symbol);
+    // Single expression, no early-return branches (the bundler was treeshaking the meta branch away).
+    const symbol = hasMeta ? meta.symbol : (specCurrency || '€');
+    const position = hasMeta && meta.symbolAfter ? 'right' : 'left';
+    const decimals = hasMeta && typeof meta.decimals === 'number' ? meta.decimals : 2;
+    return withDecimals({ symbol, position }, decimals);
+}
+/** Total stake for an action = bet × the action's cost multiplier (1 for a base spin; e.g. 100 for
+ *  a buy bonus). The host uses this to block a play the balance can't cover. */
+function stakeForAction(model, action, bet) {
+    const cost = (model.spec.actions?.[action]?.cost ?? 1);
+    return cost * bet;
+}
+/** Derive shell buy cards + ante toggles from the spec's buy/feature actions (SSOT). */
+function toBonusOptions(model) {
+    const out = [];
+    for (const [key, action] of Object.entries(model.spec.actions)) {
+        const role = action.role ?? 'base';
+        if (role !== 'buy' && role !== 'feature')
+            continue;
+        out.push({
+            id: key,
+            type: role === 'buy' ? 'bonus' : 'feature',
+            title: action.title ?? key.replace(/_/g, ' ').toUpperCase(),
+            description: action.description ?? '',
+            priceMultiplier: action.cost ?? (role === 'buy' ? 100 : 1),
+        });
+    }
+    return out;
+}
+/** Build a paytable section from the model's derived paytable view (multipliers per symbol count). */
+function paytableSection(model) {
+    const symbols = model.paytable?.symbols ?? [];
+    const rows = [];
+    for (const s of symbols) {
+        const wins = Object.entries(s.pay ?? {})
+            .map(([count, multiplier]) => ({ count: String(count), multiplier: Number(multiplier) }))
+            .filter((w) => Number.isFinite(w.multiplier) && w.multiplier > 0)
+            .sort((a, b) => Number(a.count) - Number(b.count));
+        if (!wins.length)
+            continue;
+        rows.push({ symbol: { text: s.name ?? s.id }, wins });
+    }
+    if (!rows.length)
+        return null;
+    return { type: 'paytable', title: 'PAYTABLE', rows };
+}
+/** Build a "wins" illustration section sized to the grid; `kind` follows the spec mechanic hint. */
+function winsSection(model) {
+    const { cols, rows } = model.spec.grid;
+    const grid = { cols, rows };
+    switch (model.spec.mechanic) {
+        case 'cluster':
+            return { type: 'wins', kind: 'cluster', minCount: 5, grid };
+        case 'ways':
+            return { type: 'wins', kind: 'ways', grid };
+        default:
+            return { type: 'wins', kind: 'anywhere', minCount: 3, grid };
+    }
+}
+/** Title of the legal disclaimer section — used to build it and to exempt it from socialization. */
+const DISCLAIMER_TITLE = 'DISCLAIMER';
+/** A disclaimer section from initData's disclaimer lines; null when none supplied. */
+function disclaimerSection(lines) {
+    const clean = (lines ?? []).map((l) => l.trim()).filter(Boolean);
+    if (!clean.length)
+        return null;
+    const html = clean.map((l) => `<p>${l}</p>`).join('');
+    return { type: 'custom', title: DISCLAIMER_TITLE, html };
+}
+/** The legal disclaimer must be shown verbatim — this identifies it so socialization skips it. */
+function isDisclaimerSection(s) {
+    return s.type === 'custom' && s.title === DISCLAIMER_TITLE;
+}
+/** Move the legal disclaimer to the very END of the section list — it must always render last,
+ *  regardless of where an author merge or an extra section would otherwise place it. */
+function orderDisclaimerLast(sections) {
+    const disclaimer = sections.filter(isDisclaimerSection);
+    if (!disclaimer.length)
+        return sections;
+    return [...sections.filter((s) => !isDisclaimerSection(s)), ...disclaimer];
+}
+/**
+ * Pure: derive a maximal default GameInfoContent from the model + runtime so every game
+ * gets a real info panel for free (paytable, win illustration, controls, and the Stake
+ * disclaimer when present). Author-supplied `opts.gameInfo` is MERGED over this set by
+ * section identity (see `mergeGameInfo`), not wholesale-replaced.
+ */
+function defaultGameInfo(model, runtime) {
+    const sections = [];
+    sections.push(winsSection(model));
+    const pay = paytableSection(model);
+    if (pay)
+        sections.push(pay);
+    const modes = modesSection(model);
+    if (modes)
+        sections.push(modes);
+    sections.push({ type: 'controls' });
+    const disclaimer = disclaimerSection(runtime.disclaimerLines);
+    if (disclaimer)
+        sections.push(disclaimer);
+    return { sections };
+}
+/** Per-mode info table (BASE / ANTE / each buy tier) derived from the spec's modes — the SAME SSOT
+ *  (`model.mathModes` + `spec.actions`) that drives the buy cards and the math pipeline. Stake
+ *  compliance requires Cost / RTP / Max Win per mode; deriving it here means the author declares a
+ *  mode once (in game.spec) and the info table can't drift. `free` actions are excluded (mathModes
+ *  already drops them — free spins are part of a bonus, not a purchasable mode). */
+function modesSection(model) {
+    const modes = model.mathModes ?? [];
+    if (!modes.length)
+        return null;
+    const rows = modes.map((m) => {
+        const action = model.spec.actions[m.action];
+        const isBase = (action?.role ?? 'base') === 'base' || m.mode === 'BASE';
+        const row = {
+            title: action?.title ?? (isBase ? 'Base game' : m.mode.replace(/_/g, ' ')),
+            maxWin: `${m.maxWin.toLocaleString('en-US')}×`,
+        };
+        // Cost is a bet-multiplier; a base spin (1×) reads as no premium, so only show it for buys/features.
+        if (m.costMultiplier && m.costMultiplier !== 1)
+            row.price = `${m.costMultiplier}×`;
+        if (typeof m.rtp === 'number')
+            row.rtp = Math.round(m.rtp * 1000) / 10; // 0.965 → 96.5 (%)
+        if (action?.description)
+            row.description = action.description;
+        return row;
+    });
+    return { type: 'modes', title: 'MODES', modes: rows };
+}
+/** Identity key for merge. `wins` is keyed by `kind` (different mechanics coexist). `custom` has
+ *  no structural discriminant and several can coexist (MAX WIN, DISCLAIMER, …) so it is keyed by
+ *  its `title` (an author `custom` with a matching title replaces that derived block; a new title
+ *  is added). Every other type is a singleton keyed by `type`. */
+function sectionKey(s) {
+    if (s.type === 'wins')
+        return `wins:${s.kind}`;
+    if (s.type === 'custom')
+        return `custom:${s.title ?? ''}`;
+    return s.type;
+}
+/**
+ * Merge author `gameInfo` over the host-derived set by section identity: an author section
+ * REPLACES the derived section of the same identity (same `type`, or same `wins` `kind`); a new
+ * identity is APPENDED (after the derived ones, in author order); derived sections without an
+ * author override are KEPT. `override` undefined → the pure derived set.
+ */
+function mergeGameInfo(derived, override) {
+    if (!override)
+        return derived;
+    const authorByKey = new Map();
+    for (const s of override.sections ?? [])
+        authorByKey.set(sectionKey(s), s);
+    const out = [];
+    const used = new Set();
+    // Keep derived order; swap in the author's version where identities collide.
+    for (const s of derived.sections ?? []) {
+        const k = sectionKey(s);
+        const replacement = authorByKey.get(k);
+        if (replacement) {
+            out.push(replacement);
+            used.add(k);
+        }
+        else
+            out.push(s);
+    }
+    // Append author sections whose identity wasn't in the derived set, in author order.
+    for (const s of override.sections ?? []) {
+        const k = sectionKey(s);
+        if (!used.has(k)) {
+            out.push(s);
+            used.add(k);
+        }
+    }
+    return { sections: out };
+}
+/** Run a section's player-facing text through `socialize`. Applied to the full MERGED set
+ *  (host-derived + author) in social mode. Covers section titles, custom HTML, and PAYTABLE row
+ *  symbol labels — the paytable's symbol text comes straight from the gameSpec's `symbols[].name`,
+ *  so a forbidden word in a spec symbol name is rewritten here too. A `node`-based custom section is
+ *  returned untouched — its DOM is author-owned and not introspected. */
+function socializeSection(s) {
+    const next = { ...s };
+    if ('title' in next && typeof next.title === 'string') {
+        next.title = shell.socialize(next.title);
+    }
+    if (next.type === 'custom' && typeof next.html === 'string') {
+        next.html = shell.socialize(next.html);
+    }
+    if (next.type === 'paytable' && Array.isArray(next.rows)) {
+        next.rows = next.rows.map((r) => typeof r.symbol?.text === 'string'
+            ? { ...r, symbol: { ...r.symbol, text: shell.socialize(r.symbol.text) } }
+            : r);
+    }
+    if (next.type === 'modes' && Array.isArray(next.modes)) {
+        next.modes = next.modes.map((m) => ({
+            ...m,
+            title: shell.socialize(m.title),
+            ...(m.description ? { description: shell.socialize(m.description) } : {}),
+        }));
+    }
+    return next;
+}
+/** Socialize buy-bonus card copy (title/description) when in social mode; a no-op otherwise.
+ *  Applied to the final option set (author override or spec-derived) so forbidden words in author
+ *  card copy are rewritten too. */
+function socializeBonusOptions(options, isSocial) {
+    if (!isSocial)
+        return options;
+    return options.map((o) => ({ ...o, title: shell.socialize(o.title), description: shell.socialize(o.description) }));
+}
+/** Pure: assemble a ShellConfig from the model + runtime context (currency/balance/language/mode). */
+function buildShellConfig(opts, model, runtime) {
+    // Prefer the currency-specific ladder from /wallet/authenticate; fall back to the spec (dev/devBridge).
+    const betLevels = runtime.betLevels?.length ? runtime.betLevels : model.spec.betLevels;
+    // Stake requires the default to come from authenticate on every entry; spec default is the dev fallback.
+    const defaultBet = runtime.defaultBet ?? model.spec.defaultBet ?? betLevels[0];
+    // runtime.currency is the resolved CurrencyConfig (derived from initData.config.currency by the
+    // host); opts.currency still wins. Fall back to the spec code, then a neutral euro.
+    const currency = opts.currency ?? runtime.currency ?? resolveCurrency(null, model.spec.currency);
+    const isSocial = runtime.social ?? false;
+    // Merge author sections over the host-derived defaults, THEN socialize the WHOLE merged set in
+    // social mode — so restricted gambling vocabulary is rewritten in BOTH the built-in copy AND any
+    // author-supplied text (title + custom HTML). A game can no longer surface a forbidden word in
+    // social mode just because the author wrote it in their own info section. (Custom sections built
+    // from a raw DOM `node` can't be rewritten automatically — author owns the node and can call the
+    // exported `socialize` from '@energy8platform/game-engine/host' on their own strings.)
+    // Author gameInfo may be a plain object or a `(t) => content` factory. `t` socializes when in
+    // social mode (identity otherwise) so authors can wrap copy explicitly; the full merged set is
+    // still socialized below as a safety net.
+    const t = isSocial ? shell.socialize : (text) => text;
+    const authored = typeof opts.gameInfo === 'function' ? opts.gameInfo(t) : opts.gameInfo;
+    let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime), authored);
+    // The DISCLAIMER is required legal copy and must be shown VERBATIM — never socialized (its
+    // wording is mandated, and word-swaps like "bet → play" would corrupt the legal text).
+    if (isSocial) {
+        gameInfo = {
+            sections: (gameInfo.sections ?? []).map((s) => (isDisclaimerSection(s) ? s : socializeSection(s))),
+        };
+    }
+    // The legal DISCLAIMER always renders LAST — author-merged or extra sections never push below it.
+    gameInfo = { sections: orderDisclaimerLast(gameInfo.sections ?? []) };
+    // Buy-bonus cards: socialize the FINAL options (author override or spec-derived) in social mode.
+    const buyBonus = socializeBonusOptions(opts.buyBonus ?? toBonusOptions(model), isSocial);
+    // Features: defaults, then author overrides, THEN jurisdiction restrictions (a restriction wins).
+    const features = {
+        turbo: 0,
+        spacebar: true,
+        autoplay: {},
+        buyBonus,
+        ...(opts.features ?? {}),
+    };
+    applyJurisdiction(features, runtime.jurisdiction);
+    return {
+        mount: opts.mount ?? (typeof document !== 'undefined' ? document.body : undefined),
+        language: runtime.language ?? 'en',
+        isSocial,
+        currency,
+        gameInfo,
+        availableBets: [...betLevels],
+        defaultBet,
+        currentBet: defaultBet,
+        balance: runtime.balance,
+        win: 0,
+        mode: runtime.mode,
+        features,
+    };
+}
+
+var shellConfig = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    applyJurisdiction: applyJurisdiction,
+    buildShellConfig: buildShellConfig,
+    defaultGameInfo: defaultGameInfo,
+    mergeGameInfo: mergeGameInfo,
+    resolveCurrency: resolveCurrency,
+    stakeForAction: stakeForAction,
+    toBonusOptions: toBonusOptions
+});
+
+/** Reverse the model's modeMap (Stake bet mode → SDK action key) for replay labelling/cost. */
+function resolveReplayBonusId(model, stakeMode) {
+    for (const [action, mode] of Object.entries(model.modeMap)) {
+        if (mode === stakeMode)
+            return action;
+    }
+    return stakeMode;
+}
+
+var replay = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    resolveReplayBonusId: resolveReplayBonusId
+});
+
+/**
+ * Pick the scene to START with, given the registered scenes (in order) and the launch mode.
+ *
+ * Rules:
+ *  - On a replay launch, scenes flagged `skipOnReplay` are NOT eligible to start (they stay
+ *    registered for `goto`, they just aren't auto-started) — so a leading intro is skipped and
+ *    the game scene starts directly.
+ *  - An explicit `startScene` wins, but only if that scene is itself eligible; otherwise the first
+ *    eligible scene wins.
+ *  - Falls back to the first scene unconditionally if nothing is eligible (degenerate config).
+ */
+function resolveStartScene(scenes, isReplay, explicitStart) {
+    const eligible = scenes.filter((s) => !(isReplay && s.skipOnReplay));
+    if (explicitStart) {
+        const ok = eligible.find((s) => s.key === explicitStart);
+        if (ok)
+            return ok.key;
+    }
+    return eligible[0]?.key ?? scenes[0]?.key;
+}
+
+var sceneStart = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    resolveStartScene: resolveStartScene
+});
+
+// packages/game-engine/src/host/index.ts
+
+/**
+ * Enrich a normalized result with round-continuation metadata (roundId / nextActions / complete)
+ * read from the raw play result, so a caller can drain the remaining segments of a multi-segment
+ * round by replaying the SAME roundId. The game's normalizer stays focused on render data. Shared by
+ * `createSlotPlay` (normal play) and the host's resume path (draining a recovered open round).
+ */
+function enrichRoundMeta(result, raw) {
+    const meta = (raw ?? {});
+    result.roundId = meta.roundId;
+    result.nextActions = meta.nextActions;
+    // A round is complete when there is no open session, or the session reports completed. The host
+    // sets a session on every segment, so this is `session.completed` in practice.
+    result.complete = !meta.session || meta.session.completed === true;
+    return result;
+}
+/** Build the host play/ack pair. Host-agnostic wiring; unit-testable. The returned `play` stashes
+ *  the raw host result so the matching `ack()` can forward it to `deps.ack` (PlatformSession.playAck)
+ *  once the scene has finished animating. Plays are sequential (awaited), so a single stash is safe. */
+function createSlotPlay(deps) {
+    let lastRaw = null;
+    return {
+        play: async (action, bet, roundId) => {
+            const raw = await deps.play({ action, bet, roundId });
+            lastRaw = raw;
+            const result = enrichRoundMeta(deps.normalize(raw), raw);
+            deps.onWin?.(result.totalWin);
+            return result;
+        },
+        ack: () => {
+            if (lastRaw != null)
+                deps.ack?.(lastRaw);
+        },
+    };
+}
+
+var slotPlay = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createSlotPlay: createSlotPlay,
+    enrichRoundMeta: enrichRoundMeta
+});
+
+/**
+ * Drive ONE round end-to-end: play the trigger, present it, ack; then drain the remaining segments
+ * (a bonus's free spins) by replaying nextActions[0] with the SAME roundId until the round reports
+ * `complete`. Fires `onBonusEnter` EXACTLY before the first free-role segment and `onBonusExit`
+ * after the last. A plain spin with no bonus is already `complete`, so the while-loop is a no-op.
+ *
+ * `ctx.bet` is captured once (bet can't change mid-round); `ctx.turbo` is a live getter so a
+ * mid-round toggle is honoured on the next segment.
+ */
+async function runRound(deps, action) {
+    const ctx = deps.context(action);
+    let r = await deps.play(action, ctx.bet);
+    await deps.scene.present(r, ctx);
+    deps.ack();
+    deps.afterPresent?.(r); // HUD readouts update AFTER the animation, not before
+    let inBonus = false;
+    while (!r.complete && r.nextActions && r.nextActions.length > 0) {
+        const next = r.nextActions[0];
+        if (!inBonus && deps.roleOf(next) === 'free') {
+            inBonus = true;
+            await deps.onBonusEnter?.(r, ctx);
+        }
+        // Snapshot the TRIGGER context per segment: { ... } freezes the live `turbo` getter into a data
+        // property (so a mid-round toggle is reflected on the NEXT segment), while action/mode/bet stay
+        // the round's (the trigger's) identity — a scene must see the same bonus identity all round.
+        const segCtx = { ...deps.context(action) };
+        r = await deps.play(next, ctx.bet, r.roundId);
+        await deps.scene.present(r, segCtx);
+        deps.ack();
+        deps.afterPresent?.(r);
+    }
+    if (inBonus)
+        await deps.onBonusExit?.(r, ctx);
+}
+
+var runRound$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    runRound: runRound
+});
+
+function createBalanceGate(paint, initial = 0) {
+    let latest = initial;
+    let suppressed = false;
+    return {
+        onBalance(amount) {
+            latest = amount;
+            if (!suppressed)
+                paint(amount);
+        },
+        beginPlay() {
+            suppressed = true;
+        },
+        afterPresent() {
+            paint(latest);
+            suppressed = false;
+        },
+        get balance() {
+            return latest;
+        },
+    };
+}
+
+var balanceGate = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createBalanceGate: createBalanceGate
+});
+
+function createFreeSpinsCounter() {
+    let total = 0;
+    let current = 0;
+    return {
+        enter(awarded) {
+            total = awarded;
+            current = 0;
+            return { current, total, totalWin: 0 };
+        },
+        spin(awarded, totalWin) {
+            current += 1;
+            total += awarded; // a retrigger grows the pool
+            return { current, total, totalWin };
+        },
+    };
+}
+
+var freeSpinsCounter = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createFreeSpinsCounter: createFreeSpinsCounter
+});
+
+/** Pull a Stake/SDK error code off an unknown thrown value. */
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function resolvePlayError(err) {
+    const code = errorCode(err);
+    const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+    switch (code) {
+        case 'ACTIVE_SESSION_EXISTS':
+            return {
+                title: 'Round in progress',
+                body: 'You have an unfinished round. Reload to resume it.',
+                reload: true,
+            };
+        case 'NO_ACTIVE_SESSION':
+            return {
+                title: 'Round expired',
+                body: 'This round is no longer active. Reload to continue.',
+                reload: true,
+            };
+        case 'INSUFFICIENT_FUNDS':
+            return {
+                title: 'Insufficient balance',
+                body: 'You don’t have enough balance for this bet. Lower your bet or top up.',
+                reload: false,
+            };
+        case 'TIMEOUT':
+            return {
+                title: 'Connection timed out',
+                body: 'The game server did not respond in time. Please try again.',
+                reload: false,
+            };
+        default:
+            // Unknown code: surface the server message verbatim under a generic heading (never the
+            // connection overlay), so an operator can diagnose without a code change.
+            return {
+                title: 'Game error',
+                body: message || 'Something went wrong. Please reload the game.',
+                reload: true,
+            };
+    }
+}
+
+var playError = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    errorCode: errorCode,
+    resolvePlayError: resolvePlayError
+});
+
+function createAutoplayLoop(deps) {
+    let active = false;
+    let remaining = 0;
+    let running = false; // guards against a second concurrent loop
+    const stop = () => {
+        if (!active && remaining === 0)
+            return;
+        active = false;
+        remaining = 0;
+        deps.onState({ active: false, remaining: 0 });
+    };
+    async function loop() {
+        if (running)
+            return;
+        running = true;
+        try {
+            while (active && remaining > 0) {
+                const action = deps.resolveAction();
+                if (!deps.canAfford(action)) {
+                    stop();
+                    return;
+                }
+                // Decrement at spin START (so the spin in flight is `total − remaining`), then play it out.
+                remaining -= 1;
+                deps.onState({ active: true, remaining });
+                try {
+                    await deps.playRound(action);
+                }
+                catch {
+                    stop(); // a play error already surfaced its own modal — just halt the run
+                    return;
+                }
+            }
+            if (active)
+                stop(); // ran the budget out
+        }
+        finally {
+            running = false;
+        }
+    }
+    return {
+        start(count) {
+            if (active || running || count <= 0)
+                return;
+            active = true;
+            remaining = count;
+            deps.onState({ active: true, remaining });
+            void loop();
+        },
+        stop,
+        get active() { return active; },
+        get remaining() { return remaining; },
+    };
+}
+
+var autoplay = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createAutoplayLoop: createAutoplayLoop
+});
+
+Object.defineProperty(exports, "socialize", {
+    enumerable: true,
+    get: function () { return shell.socialize; }
+});
+exports.buildShellConfig = buildShellConfig;
+exports.createSlotGame = createSlotGame;
+exports.resolveReplayBonusId = resolveReplayBonusId;
+exports.resolveStartScene = resolveStartScene;
+exports.stakeForAction = stakeForAction;
+//# sourceMappingURL=host.cjs.js.map