@energy8platform/game-engine 0.18.0 → 0.19.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;
@@ -1904,6 +1919,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) */
@@ -2083,20 +2104,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 +2440,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 +2477,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 +2524,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 +2540,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 +2628,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 +2693,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 +2706,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 +2730,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 +2758,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 +2806,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 +2819,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 +2879,8 @@ async function createSlotGame(opts) {
 }
 
 // packages/game-engine/src/host/shellConfig.ts
+// `socialize` is a runtime helper that pixi-shell does NOT re-export (its index only re-exports
+// types), so it stays sourced from platform-core/shell; the shapes are structurally identical.
 /**
  * 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).
@@ -2983,7 +3133,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;
@@ -3026,7 +3177,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 +3285,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 +3417,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;