@energy8platform/game-engine 0.18.0 → 0.20.0

package/dist/host.cjs.js

@@ -735,6 +735,7 @@ class AudioManager {
     _persist;
     _storageKey;
     _categories;
+    _masterGain = 1.0;
     _currentMusic = null;
     _unlocked = false;
     _unlockHandler = null;
@@ -794,7 +795,7 @@ class AudioManager {
         if (this._globalMuted || this._categories[category].muted)
             return;
         const { sound } = this._soundModule;
-        const vol = (options?.volume ?? 1) * this._categories[category].volume;
+        const vol = (options?.volume ?? 1) * this._categories[category].volume * this._masterGain;
         try {
             sound.play(alias, {
                 volume: vol,
@@ -823,7 +824,7 @@ class AudioManager {
             if (this._globalMuted || this._categories.music.muted)
                 return;
             // Fade out the previous track
-            this.fadeVolume(prevAlias, this._categories.music.volume, 0, fadeDuration, () => {
+            this.fadeVolume(prevAlias, this._categories.music.volume * this._masterGain, 0, fadeDuration, () => {
                 try {
                     sound.stop(prevAlias);
                 }
@@ -835,7 +836,7 @@ class AudioManager {
                     volume: 0,
                     loop: true,
                 });
-                this.fadeVolume(alias, 0, this._categories.music.volume, fadeDuration);
+                this.fadeVolume(alias, 0, this._categories.music.volume * this._masterGain, fadeDuration);
             }
             catch (e) {
                 console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
@@ -854,7 +855,7 @@ class AudioManager {
                 return;
             try {
                 sound.play(alias, {
-                    volume: this._categories.music.volume,
+                    volume: this._categories.music.volume * this._masterGain,
                     loop: true,
                 });
             }
@@ -888,6 +889,15 @@ class AudioManager {
         sound.stopAll();
         this._currentMusic = null;
     }
+    /** Global gain (0..1) folded into every category's effective volume. Driven by the shell's
+     *  'master' settingChange. Does not affect the persisted per-category volumes. */
+    setMasterVolume(volume) {
+        this._masterGain = Math.max(0, Math.min(1, volume));
+        this.applyVolumes();
+    }
+    getMasterVolume() {
+        return this._masterGain;
+    }
     /**
      * Set volume for a category.
      */
@@ -1033,7 +1043,7 @@ class AudioManager {
         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;
+        sound.volumeAll = this._masterGain; // master multiplies the global bus
     }
     setupMobileUnlock() {
         if (this._unlocked)
@@ -1301,6 +1311,7 @@ class ViewportManager extends EventEmitter {
     _app;
     _container;
     _config;
+    _target;
     _resizeObserver = null;
     _currentOrientation = Orientation.LANDSCAPE;
     _currentWidth = 0;
@@ -1308,11 +1319,15 @@ class ViewportManager extends EventEmitter {
     _currentScale = 1;
     _destroyed = false;
     _resizeTimeout = null;
-    constructor(app, container, config) {
+    constructor(app, container, config, target) {
         super();
         this._app = app;
         this._container = container;
         this._config = config;
+        // The container this manager scales/offsets. Defaults to app.stage for backward
+        // compatibility; the engine passes a dedicated scaled world root so app.stage stays
+        // identity (screen space) for unscaled UI layers.
+        this._target = target ?? app.stage;
         this.setupObserver();
     }
     /** Current canvas width in game units */
@@ -1401,19 +1416,19 @@ class ViewportManager extends EventEmitter {
         const stageScale = scaleMode === ScaleMode.STRETCH
             ? Math.min(containerWidth / designWidth, containerHeight / designHeight)
             : scale;
-        this._app.stage.scale.set(stageScale);
+        this._target.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);
+            this._target.x = Math.round((containerWidth - designWidth * stageScale) / 2);
+            this._target.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);
+            this._target.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
+            this._target.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
         }
         else {
-            this._app.stage.x = 0;
-            this._app.stage.y = 0;
+            this._target.x = 0;
+            this._target.y = 0;
         }
         this._currentWidth = gameWidth;
         this._currentHeight = gameHeight;
@@ -1502,34 +1517,20 @@ class Scene {
 }
 
 /**
- * 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.
+ * Built-in loading screen.
  *
- * 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.
+ * It does NOT render its own overlay — the CSS preloader created at boot
+ * (`createPlatformSession`/`GameApplication.start`) stays on screen, and this
+ * scene merely drives it: asset-load progress → `setCSSPreloaderProgress`,
+ * tap-to-start → `waitCSSPreloaderTap`, then fades it out via
+ * `removeCSSPreloader` before entering the game. One continuous overlay from
+ * boot to gameplay — no second logo, no mid-load flash.
  */
 class LoadingScene extends Scene {
     _engine;
     _targetScene;
     _targetData;
     _config;
-    // HTML overlay
-    _overlay = null;
-    _loaderRect = null;
-    _percentEl = null;
-    _tapToStartEl = null;
     // State
     _displayedProgress = 0;
     _targetProgress = 0;
@@ -1542,8 +1543,6 @@ class LoadingScene extends Scene {
         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
@@ -1589,110 +1588,29 @@ class LoadingScene extends Scene {
         // 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();
-        }
+        // Wait for the player's tap — resolves immediately when tapToStart is
+        // false (the preloader honours that flag) — then enter the game.
+        await loading.waitCSSPreloaderTap();
+        await this.transitionToGame();
     }
     onUpdate(dt) {
-        // Smooth progress bar fill via HTML (during active loading)
+        // Smooth progress bar fill (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
+        // The preloader overlay is CSS-based and 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;
+        // Defensive: ensure the preloader is gone even if we never transitioned
+        // (e.g. the scene was popped externally). Idempotent.
+        void loading.removeCSSPreloader(this.hostElement());
     }
     // ─── 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}%`;
-        }
+        loading.setCSSPreloaderProgress(Math.max(0, Math.min(1, progress)));
     }
     /**
      * Smoothly animate the displayed progress from its current value to `target`
@@ -1722,49 +1640,20 @@ class LoadingScene extends Scene {
             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 ────────────────────────────────────────
+    /** The DOM element hosting the canvas + preloader overlay. */
+    hostElement() {
+        return this._engine?.app?.canvas?.parentElement ?? document.body;
+    }
     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();
+        // Fade out and remove the shared CSS preloader (resolves after the fade).
+        await loading.removeCSSPreloader(this.hostElement());
         // 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 }),
+            ...(this._targetData && typeof this._targetData === 'object'
+                ? this._targetData
+                : { data: this._targetData }),
         });
     }
 }
@@ -1904,6 +1793,12 @@ class GameApplication extends EventEmitter {
     input;
     /** Viewport manager */
     viewport;
+    /** Scaled world root (holds scenes). Transformed by the ViewportManager to fit the design
+     *  resolution; lives below the UI layer on app.stage. */
+    worldRoot;
+    /** Unscaled, screen-space UI layer. Sits above {@link worldRoot} and is NOT touched by the
+     *  viewport transform — children fill the real screen (e.g. the host's shell + overlay). */
+    uiLayer;
     /** SDK instance (null in offline mode) */
     sdk = null;
     /** FPS overlay instance (only when debug: true) */
@@ -1985,17 +1880,20 @@ class GameApplication extends EventEmitter {
             // 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
+            // 7. Load assets. The CSS preloader stays on screen — LoadingScene drives
+            //    its progress/tap and removes it before entering the game, so there's
+            //    a single continuous overlay from boot to gameplay (no logo flash).
             await this.loadAssets(firstScene, sceneData);
             this.emit('loaded');
-            // 9. Start the game loop
+            // 8. Start the game loop
             this._running = true;
             this.emit('started');
         }
         catch (err) {
             console.error('[GameEngine] Failed to start:', err);
+            // Tear down the preloader so a failure doesn't strand the brand frame.
+            if (this._container)
+                loading.removeCSSPreloader(this._container);
             this.emit('error', err instanceof Error ? err : new Error(String(err)));
             throw err;
         }
@@ -2083,20 +1981,27 @@ class GameApplication extends EventEmitter {
         this.audio = new AudioManager(this.config.audio);
         // Input Manager
         this.input = new InputManager(this.app.canvas);
-        // Viewport Manager
+        // Stage layers: a scaled world root (scenes, transformed to design resolution by the
+        // viewport) below an unscaled UI layer (screen space). app.stage itself stays identity.
+        this.worldRoot = new pixi_js.Container();
+        this.worldRoot.label = 'world';
+        this.uiLayer = new pixi_js.Container();
+        this.uiLayer.label = 'ui';
+        this.app.stage.addChild(this.worldRoot, this.uiLayer);
+        // Viewport Manager — scales worldRoot (NOT app.stage), so the UI layer is unscaled.
         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.worldRoot);
+        // Wire SceneManager to the scaled world root
+        this.scenes.setRoot(this.worldRoot);
         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.input.setViewportTransform(scale, this.worldRoot.x, this.worldRoot.y);
             this.emit('resize', { width, height });
         });
         this.viewport.on('orientationChange', (orientation) => {
@@ -2412,13 +2317,27 @@ async function createSlotGame(opts) {
     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; });
+    // Injected once per controller scene the first time it becomes current (see `ensureCreated`).
+    // `sceneApi` is assembled inside the shell block; until then injection is a no-op (a shell-less
+    // launch never builds the api, so a controller scene simply never receives onCreate).
+    let sceneApi = null;
+    const createdScenes = new WeakSet();
+    const ensureCreated = (s) => {
+        if (!sceneApi || createdScenes.has(s))
+            return;
+        createdScenes.add(s);
+        s.onCreate?.(sceneApi);
+    };
     /** The current scene IFF it implements the SlotSceneController contract (duck-typed on
-     *  `present`). The host drives the play loop against whichever scene is current. */
+     *  `onSpin`). The host drives the play loop against whichever scene is current. Injects the
+     *  SceneApi via onCreate the first time a controller scene is seen. */
     const gameScene = () => {
         const s = game.scenes.current?.scene;
-        return typeof s?.present === 'function'
-            ? s
-            : undefined;
+        if (typeof s?.onSpin !== 'function')
+            return undefined;
+        const scene = s;
+        ensureCreated(scene);
+        return scene;
     };
     const { runRound } = await Promise.resolve().then(function () { return runRound$1; });
     const { createBalanceGate } = await Promise.resolve().then(function () { return balanceGate; });
@@ -2435,7 +2354,7 @@ async function createSlotGame(opts) {
         ack: (raw) => game.platformSession.playAck(raw),
     });
     if (opts.shell) {
-        const { createGameShell } = await import('@energy8platform/platform-core/shell');
+        const { createPixiShell } = await import('@energy8platform/pixi-shell');
         const { buildShellConfig } = await Promise.resolve().then(function () { return shellConfig; });
         const { resolveReplayBonusId } = await Promise.resolve().then(function () { return replay; });
         const ps = game.platformSession;
@@ -2482,7 +2401,14 @@ async function createSlotGame(opts) {
                 `| spec=${opts.model.spec.currency ?? '∅'} ` +
                 `| RESOLVED.symbol=${runtime.currency?.symbol ?? '∅'} pos=${runtime.currency?.position ?? '∅'}`);
         }
-        shell = createGameShell(buildShellConfig(opts.shell, opts.model, runtime));
+        // pixi-shell mounts its root onto the engine's unscaled, screen-space UI layer (above the
+        // scaled world/scene root) so the control bar fills the real screen, not the letterboxed game.
+        // The host adds the mount target (`app`) + parent; buildShellConfig produces everything else.
+        shell = createPixiShell({ ...buildShellConfig(opts.shell, opts.model, runtime), app: game.app, parent: game.uiLayer });
+        // Scope the bar to the slot scene: show only when a SlotSceneController scene is current
+        // (hidden over the intro / non-slot scenes). Applies in BOTH base and replay modes.
+        shell.setVisible(!!gameScene());
+        game.scenes.on('change', () => shell.setVisible(!!gameScene()));
         // 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`
@@ -2491,8 +2417,52 @@ async function createSlotGame(opts) {
         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; });
+        shell.on('turboChange', (level) => { currentTurbo = level; gameScene()?.onTurboChanged?.(level); });
+        // Double-tap-to-skip is a game-level option (default on), set once via createSlotGame({ skipGesture }).
+        const skipEnabled = opts.skipGesture ?? true;
+        // Shell settings → engine state. Sound/volume map onto the AudioManager.
+        shell.on('settingChange', ({ key, value }) => {
+            switch (key) {
+                case 'sound':
+                    value ? game.audio.unmuteAll() : game.audio.muteAll();
+                    break;
+                case 'master':
+                    game.audio.setMasterVolume(Number(value));
+                    break;
+                case 'music':
+                    game.audio.setVolume('music', Number(value));
+                    break;
+                case 'sfx':
+                    game.audio.setVolume('sfx', Number(value));
+                    break;
+            }
+        });
+        // Overlay layer sits ABOVE the shell (the shell already mounted its root onto the uiLayer;
+        // adding ours afterwards keeps it on top). It eats pointer events while open so shell controls
+        // are unreachable. Mounted on the same unscaled UI layer; tracks viewport via game's 'resize'.
+        const { createSceneAudio } = await Promise.resolve().then(function () { return sceneAudio; });
+        const { createOverlayController } = await Promise.resolve().then(function () { return overlayController; });
+        const overlayLayer = new pixi_js.Container();
+        overlayLayer.label = 'overlay';
+        game.uiLayer.addChild(overlayLayer);
+        const overlayCtl = createOverlayController({
+            parent: overlayLayer,
+            size: () => ({ width: game.app.screen.width, height: game.app.screen.height }),
+        });
+        game.on('resize', ({ width, height }) => overlayCtl.resize(width, height));
+        // Capabilities injected once per controller scene via onCreate (see `gameScene`/`ensureCreated`).
+        sceneApi = {
+            audio: createSceneAudio(game.audio),
+            overlay: overlayCtl.overlay,
+            shell: { get safeArea() { return shell.safeArea; } },
+            formatAmount: (v) => shell.formatWin(v),
+            get bet() { return currentBet; },
+            get mode() { return opts.model.modeMap['spin'] ?? 'BASE'; },
+            get turbo() { return currentTurbo; },
+        };
         const roleOf = (action) => opts.model.spec.actions[action]?.role;
+        // The signal-less context. runRound injects a per-segment `signal` (for skip); resumeDrain
+        // attaches its own. So makeContext returns everything BUT `signal`.
         const makeContext = (action) => ({
             bet: currentBet,
             action,
@@ -2535,19 +2505,62 @@ async function createSlotGame(opts) {
                 body: shell.t('Lost connection to the game server. Trying to reconnect…'),
             });
         });
+        // Skip state: `currentSegmentAbort` is the controller for the segment presently animating;
+        // `presenting` is true for the whole play→drain window (gates the double-tap detector so taps
+        // only skip while a round is animating).
+        let currentSegmentAbort = null;
+        let presenting = false;
+        // Double-tap skip: a double-tap on the play area aborts the current segment (the scene collapses
+        // to its final visual via ctx.signal) and notifies the scene's onSkip. Gated by the shell's
+        // skip-gesture setting (`skipEnabled`) and only active while a round is presenting.
+        const { createDoubleTapSkip } = await Promise.resolve().then(function () { return skipGesture; });
+        const skip = createDoubleTapSkip({
+            enabled: () => skipEnabled,
+            active: () => presenting,
+            onSkip: () => { currentSegmentAbort?.abort(); gameScene()?.onSkip?.(); },
+        });
+        // Listen for taps on the scene root (game.worldRoot — the scaled scene container). The shell
+        // lives on the sibling uiLayer, so its bar taps never reach worldRoot — taps here are the play area.
+        game.scenes.root.eventMode = 'static';
+        game.scenes.root.on('pointertap', () => skip.tap(performance.now()));
+        // Full auto-pause: on tab blur, freeze the ticker (stops tweens/onUpdate/in-flight onSpin),
+        // duck music to silence, hold autoplay, and notify the scene. On focus, reverse it all.
+        // `stopAutoplay` is reassigned in the base-mode block below — the closure reads it live.
+        const { createPauseController } = await Promise.resolve().then(function () { return pauseController; });
+        createPauseController({
+            isHidden: () => typeof document !== 'undefined' && document.hidden,
+            subscribe: (cb) => {
+                if (typeof document === 'undefined')
+                    return () => { };
+                document.addEventListener('visibilitychange', cb);
+                return () => document.removeEventListener('visibilitychange', cb);
+            },
+            onHidden: () => {
+                game.app.ticker.stop(); // freezes tweens, onUpdate, in-flight onSpin animation
+                game.audio.duckMusic(0); // silence music (ducked to 0; restored on resume)
+                stopAutoplay(); // hold autoplay — don't start the next auto-round
+                gameScene()?.onPause?.();
+            },
+            onVisible: () => {
+                game.app.ticker.start();
+                game.audio.unduckMusic();
+                gameScene()?.onResume?.();
+            },
+        });
         /** Drive a full round (trigger + drain) against the current scene. HUD readouts (win + balance)
-         *  update only AFTER each present(), per the HUD-timing requirement. */
+         *  update only AFTER each onSpin(), 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.
+            // the trigger segment (rendered by onSpin before onEnterMode) 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
+            presenting = true; // open the skip window for the whole play→drain
             // 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({
@@ -2557,6 +2570,10 @@ async function createSlotGame(opts) {
                 scene,
                 context: makeContext,
                 roleOf,
+                // Hand the host the per-segment AbortController so a double-tap can skip the live segment.
+                beforeSegment: (ac) => { currentSegmentAbort = ac; },
+                onSpinStart: () => scene.onSpinStart?.(),
+                onSpinEnd: (last, ctx) => scene.onSpinEnd?.(last, ctx),
                 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.
@@ -2566,18 +2583,18 @@ async function createSlotGame(opts) {
                     if (inBonus)
                         shell.setFreeSpins(fsCounter.spin(r.freeSpins?.awarded ?? 0, r.totalWin));
                 },
-                onBonusEnter: async (trigger, ctx) => {
+                onEnterMode: async (trigger, ctx) => {
                     inBonus = true;
                     shell.setMode('freeSpins');
                     shell.setFreeSpins(fsCounter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0));
-                    await scene.onBonusEnter?.(trigger, ctx);
+                    await scene.onEnterMode?.(trigger, ctx);
                 },
-                onBonusExit: async (last, ctx) => {
+                onExitMode: async (last, ctx) => {
                     inBonus = false;
-                    await scene.onBonusExit?.(last, ctx);
+                    await scene.onExitMode?.(last, ctx);
                     shell.setMode('base');
                 },
-            }, action).catch(showPlayError).finally(() => shell.setBusy(false));
+            }, action).catch(showPlayError).finally(() => { presenting = false; shell.setBusy(false); });
         };
         /**
          * Drain a recovered open round to completion and settle it. Plays EVERY remaining segment from
@@ -2590,7 +2607,12 @@ async function createSlotGame(opts) {
             const scene = gameScene();
             if (!scene || !ps)
                 return;
-            const ctx = makeContext(firstRaw.action ?? 'spin');
+            // A recovered drain isn't skippable (no live skip gesture wired to it), so it gets a stable,
+            // never-aborted signal to satisfy onSpin's RenderContext.
+            const ctx = {
+                ...makeContext(firstRaw.action ?? 'spin'),
+                signal: new AbortController().signal,
+            };
             const fsView = (raw, totalWin) => {
                 const s = raw.session;
                 if (!s)
@@ -2613,7 +2635,7 @@ async function createSlotGame(opts) {
                     shell.setMode('freeSpins');
                 }
                 if (animate)
-                    await scene.present(r, ctx);
+                    await scene.onSpin(r, ctx);
                 if (inBonus) {
                     const v = fsView(raw, r.totalWin);
                     if (v)
@@ -2661,7 +2683,7 @@ async function createSlotGame(opts) {
                     return;
                 void playRound(action);
             });
-            shell.on('betChange', (bet) => { currentBet = bet; });
+            shell.on('betChange', (bet) => { currentBet = bet; gameScene()?.onBetChanged?.(bet); });
             shell.on('buyBonusSelect', ({ id }) => {
                 if (!ensureAffordable(id))
                     return;
@@ -2674,7 +2696,10 @@ async function createSlotGame(opts) {
                 resolveAction: () => activeFeature ?? 'spin',
                 canAfford: (a) => ensureAffordable(a),
                 playRound: (a) => Promise.resolve(playRound(a)),
-                onState: (s) => shell.setAutoplay(s),
+                onState: (s) => {
+                    shell.setAutoplay(s);
+                    gameScene()?.onAutoplayChanged?.({ running: s.active, remaining: s.remaining });
+                },
             });
             stopAutoplay = () => autoplay$1.stop();
             shell.on('autoplayStart', (o) => autoplay$1.start(o?.remaining ?? 0));
@@ -2731,6 +2756,8 @@ async function createSlotGame(opts) {
 }
 
 // packages/game-engine/src/host/shellConfig.ts
+// `socialize` / `createI18n` are runtime helpers sourced from platform-core/shell;
+// pixi-shell re-exports only types so we import directly from platform-core.
 /**
  * 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).
@@ -2785,8 +2812,9 @@ 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) {
+/** Derive shell buy cards + ante toggles from the spec's buy/feature actions (SSOT).
+ *  @param t Optional translator applied to `title` and `description` before they enter the shell. */
+function toBonusOptions(model, t = (s) => s) {
     const out = [];
     for (const [key, action] of Object.entries(model.spec.actions)) {
         const role = action.role ?? 'base';
@@ -2795,15 +2823,18 @@ function toBonusOptions(model) {
         out.push({
             id: key,
             type: role === 'buy' ? 'bonus' : 'feature',
-            title: action.title ?? key.replace(/_/g, ' ').toUpperCase(),
-            description: action.description ?? '',
+            title: t(action.title ?? key.replace(/_/g, ' ').toUpperCase()),
+            description: t(action.description ?? ''),
             priceMultiplier: action.cost ?? (role === 'buy' ? 100 : 1),
+            // Volatility (1–5 bolts) is part of the spec action SSOT; forward it so the buy card shows it.
+            ...(action.volatility != null ? { volatility: action.volatility } : {}),
         });
     }
     return out;
 }
-/** Build a paytable section from the model's derived paytable view (multipliers per symbol count). */
-function paytableSection(model) {
+/** Build a paytable section from the model's derived paytable view (multipliers per symbol count).
+ *  @param t Optional translator applied to symbol names before they enter the shell. */
+function paytableSection(model, t = (s) => s) {
     const symbols = model.paytable?.symbols ?? [];
     const rows = [];
     for (const s of symbols) {
@@ -2813,11 +2844,13 @@ function paytableSection(model) {
             .sort((a, b) => Number(a.count) - Number(b.count));
         if (!wins.length)
             continue;
-        rows.push({ symbol: { text: s.name ?? s.id }, wins });
+        rows.push({ symbol: { text: t(s.name ?? s.id) }, wins });
     }
     if (!rows.length)
         return null;
-    return { type: 'paytable', title: 'PAYTABLE', rows };
+    // No literal title — the shell renders `s.title ?? host.t('Paytable')`, so the heading is
+    // localized (matching how the modes/wins sections rely on the shell's translated fallback).
+    return { type: 'paytable', rows };
 }
 /** Build a "wins" illustration section sized to the grid; `kind` follows the spec mechanic hint. */
 function winsSection(model) {
@@ -2859,14 +2892,15 @@ function orderDisclaimerLast(sections) {
  * 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.
+ * @param t Optional translator applied to spec-derived player-facing strings (symbol names, mode titles, etc.).
  */
-function defaultGameInfo(model, runtime) {
+function defaultGameInfo(model, runtime, t = (s) => s) {
     const sections = [];
     sections.push(winsSection(model));
-    const pay = paytableSection(model);
+    const pay = paytableSection(model, t);
     if (pay)
         sections.push(pay);
-    const modes = modesSection(model);
+    const modes = modesSection(model, t);
     if (modes)
         sections.push(modes);
     sections.push({ type: 'controls' });
@@ -2879,8 +2913,9 @@ function defaultGameInfo(model, runtime) {
  *  (`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) {
+ *  already drops them — free spins are part of a bonus, not a purchasable mode).
+ *  @param t Optional translator applied to row `title` and `description` before they enter the shell. */
+function modesSection(model, t = (s) => s) {
     const modes = model.mathModes ?? [];
     if (!modes.length)
         return null;
@@ -2888,7 +2923,7 @@ function modesSection(model) {
         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, ' ')),
+            title: t(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.
@@ -2897,7 +2932,7 @@ function modesSection(model) {
         if (typeof m.rtp === 'number')
             row.rtp = Math.round(m.rtp * 1000) / 10; // 0.965 → 96.5 (%)
         if (action?.description)
-            row.description = action.description;
+            row.description = t(action.description);
         return row;
     });
     return { type: 'modes', title: 'MODES', modes: rows };
@@ -2983,7 +3018,8 @@ function socializeBonusOptions(options, 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). */
+/** Pure: assemble the shell config (sans mount target) from the model + runtime context
+ *  (currency/balance/language/mode). The host adds `app` at the call site. */
 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;
@@ -2993,18 +3029,17 @@ function buildShellConfig(opts, model, runtime) {
     // 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;
+    // Build the merged resolver: game i18n map + shell LOCALES (via createI18n), then socialize on
+    // top for English social mode. For non-English languages, createI18n already handles the
+    // translation lookup; social rewriting is English-only and applied separately after.
+    // Author gameInfo may be a plain object or a `(t) => content` factory. `t` is the resolver so
+    // authors can wrap player-facing copy explicitly; the full merged set is still socialized below
+    // (section pass) as a safety net so restricted words can't slip through even if t() was missed.
+    const { t } = shell.createI18n({ language: runtime.language ?? 'en', isSocial, messages: opts.i18n });
     const authored = typeof opts.gameInfo === 'function' ? opts.gameInfo(t) : opts.gameInfo;
-    let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime), authored);
+    // Pass t() through to spec-derived sections so symbol names, mode titles, and descriptions are
+    // pre-translated before they reach the shell renderer.
+    let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime, t), 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) {
@@ -3014,8 +3049,8 @@ function buildShellConfig(opts, model, runtime) {
     }
     // 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);
+    // Buy-bonus cards: apply t() to spec-derived options (pre-translate), then socialize for en+social.
+    const buyBonus = socializeBonusOptions(opts.buyBonus ?? toBonusOptions(model, t), isSocial);
     // Features: defaults, then author overrides, THEN jurisdiction restrictions (a restriction wins).
     const features = {
         turbo: 0,
@@ -3026,7 +3061,6 @@ function buildShellConfig(opts, model, runtime) {
     };
     applyJurisdiction(features, runtime.jurisdiction);
     return {
-        mount: opts.mount ?? (typeof document !== 'undefined' ? document.body : undefined),
         language: runtime.language ?? 'en',
         isSocial,
         currency,
@@ -3135,39 +3169,32 @@ var slotPlay = /*#__PURE__*/Object.freeze({
     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.onSpinStart?.();
+    const ctxBet = deps.context(action).bet;
+    const segment = async (a, roundId) => {
+        const ac = new AbortController();
+        deps.beforeSegment?.(ac);
+        const r = await deps.play(a, ctxBet, roundId);
+        const ctx = { ...deps.context(action), signal: ac.signal };
+        await deps.scene.onSpin(r, ctx);
         deps.ack();
         deps.afterPresent?.(r);
+        return { r, ctx };
+    };
+    let { r, ctx } = await segment(action, undefined);
+    let inMode = false;
+    while (!r.complete && r.nextActions && r.nextActions.length > 0) {
+        const next = r.nextActions[0];
+        if (!inMode && deps.roleOf(next) === 'free') {
+            inMode = true;
+            await deps.onEnterMode?.(r, ctx);
+        }
+        ({ r, ctx } = await segment(next, r.roundId));
     }
-    if (inBonus)
-        await deps.onBonusExit?.(r, ctx);
+    if (inMode)
+        await deps.onExitMode?.(r, ctx);
+    deps.onSpinEnd?.(r, ctx);
 }
 
 var runRound$1 = /*#__PURE__*/Object.freeze({
@@ -3274,6 +3301,129 @@ var playError = /*#__PURE__*/Object.freeze({
     resolvePlayError: resolvePlayError
 });
 
+/** Wrap the engine's AudioManager into the playback-only handle a scene receives. Volume/mute are
+ *  deliberately omitted — those are driven by the shell's settingChange → host. */
+function createSceneAudio(audio) {
+    return {
+        play: (alias, opts) => audio.play(alias, 'sfx', opts),
+        playMusic: (alias, fadeMs) => audio.playMusic(alias, fadeMs),
+        stopMusic: () => audio.stopMusic(),
+        duck: (factor) => audio.duckMusic(factor),
+        unduck: () => audio.unduckMusic(),
+    };
+}
+
+var sceneAudio = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createSceneAudio: createSceneAudio
+});
+
+function createOverlayController(deps) {
+    let current = null;
+    const teardown = () => {
+        if (!current)
+            return;
+        if (current.timer)
+            clearTimeout(current.timer);
+        const { layer, resolve } = current;
+        current = null;
+        layer.removeFromParent();
+        layer.destroy({ children: true });
+        resolve();
+    };
+    const overlay = {
+        show(opts) {
+            if (current) {
+                console.warn('[overlay] show() ignored — an overlay is already open');
+                return Promise.reject(new Error('Overlay already open'));
+            }
+            const { width, height } = deps.size();
+            const layer = new pixi_js.Container();
+            layer.eventMode = 'static';
+            // Pointer-eating + (optional) dim backdrop sized to the canvas.
+            const hit = new pixi_js.Graphics().rect(0, 0, width, height).fill({
+                color: 0x000000,
+                alpha: opts.dim ?? 0.0001, // ~0 keeps it transparent but hit-testable
+            });
+            hit.eventMode = 'static';
+            layer.addChild(hit);
+            const content = new pixi_js.Container();
+            layer.addChild(content);
+            opts.build(content, { width, height });
+            deps.parent.addChild(layer);
+            return new Promise((resolve) => {
+                const dimValue = opts.dim ?? 0.0001;
+                current = { layer, resolve, timer: null, dim: dimValue };
+                const closeOn = opts.closeOn ?? 'tap';
+                if (closeOn === 'tap')
+                    hit.on('pointertap', teardown);
+                if (typeof opts.autoCloseMs === 'number') {
+                    current.timer = setTimeout(teardown, opts.autoCloseMs);
+                }
+            });
+        },
+        close() { teardown(); },
+    };
+    return {
+        overlay,
+        resize(w, h) {
+            if (!current)
+                return;
+            const hit = current.layer.getChildAt(0);
+            hit.clear().rect(0, 0, w, h).fill({ color: 0x000000, alpha: current.dim });
+        },
+        destroy() { teardown(); },
+    };
+}
+
+var overlayController = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createOverlayController: createOverlayController
+});
+
+/** Pure double-tap recognizer. The host feeds it pointer `tap(now)` (e.g. performance.now()) and
+ *  supplies the enabled/active gates + the onSkip effect. */
+function createDoubleTapSkip(deps) {
+    const threshold = deps.thresholdMs ?? 300;
+    let last = -Infinity;
+    return {
+        tap(now) {
+            const isDouble = now - last <= threshold;
+            last = isDouble ? -Infinity : now; // consume the pair so a 3rd tap starts fresh
+            if (isDouble && deps.enabled() && deps.active())
+                deps.onSkip();
+        },
+        destroy() { last = -Infinity; },
+    };
+}
+
+var skipGesture = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createDoubleTapSkip: createDoubleTapSkip
+});
+
+/** Edge-triggers onHidden/onVisible from a visibility source. Effects (ticker/music/autoplay/scene)
+ *  are supplied by the host so this stays pure + testable. */
+function createPauseController(deps) {
+    let paused = deps.isHidden();
+    const unsub = deps.subscribe(() => {
+        const hidden = deps.isHidden();
+        if (hidden === paused)
+            return;
+        paused = hidden;
+        if (hidden)
+            deps.onHidden();
+        else
+            deps.onVisible();
+    });
+    return { destroy: () => unsub() };
+}
+
+var pauseController = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createPauseController: createPauseController
+});
+
 function createAutoplayLoop(deps) {
     let active = false;
     let remaining = 0;