@mpgd/game-runtime 0.2.6 → 0.4.0

package/dist/game/index.d.ts

@@ -0,0 +1,47 @@
+import type { GameServicesOperationClient, GameServicesRewardedAdResult } from '@mpgd/game-services/operations';
+import type { PlatformGateway, RewardedAdResult } from '@mpgd/platform';
+import type { AdPlacementInput } from '@mpgd/platform/ads';
+import { type GameExecutionController } from '../index.js';
+import { type GameLifecycleState } from '../platform/index.js';
+import { type FullScreenPresentationScope } from '../presentation/index.js';
+import { type AdWaitDeadline, type PurchasePresentationEvent } from '../ads/index.js';
+import { type GameActionCoordinator, type GameActionReconciliationPort } from '../actions/index.js';
+import { type ObserverErrorHandler } from '../observers.js';
+/** Structural service ports keep the core usable without DOM, HTTP, or schema libraries. */
+export interface GameServicePorts {
+  readonly client?: GameServicesOperationClient;
+  readonly monetizationRecovery?: {
+    recoverRewardResult(idempotencyKey: string, platform: RewardedAdResult): Promise<GameServicesRewardedAdResult>;
+    reconcile(): Promise<unknown>;
+  };
+}
+/** One scene's logical play state; execution blocks remain owned by the game runtime. */
+export interface GameGameplayScope {
+  setActive(active: boolean): void;
+  dispose(): void;
+}
+export interface GamePlatformRuntime<T extends PlatformGateway = PlatformGateway, S extends GameServicePorts = GameServicePorts> {
+  readonly gateway: T;
+  readonly execution: GameExecutionController;
+  readonly presentation: FullScreenPresentationScope;
+  readonly services: S;
+  readonly actions?: GameActionCoordinator;
+  createGameplayScope(): GameGameplayScope;
+  /** Reconcile existing journal entries only; this method never opens platform UI. */
+  reconcile(): Promise<void>;
+  /** Game teardown; native observers and application-owned late recovery may continue. */
+  dispose(): void;
+}
+/** Construct once above every scene, preserving target gateway extensions and receiver binding. */
+export declare function createGamePlatformRuntime<T extends PlatformGateway, S extends GameServicePorts>(input: {
+  readonly gateway: T;
+  readonly createServices: (gateway: T) => S;
+  readonly initialLifecycleState: GameLifecycleState;
+  readonly canShow?: (placement: AdPlacementInput) => boolean;
+  readonly deadline?: AdWaitDeadline;
+  readonly reconciliation?: GameActionReconciliationPort;
+  readonly purchasePresentation?: {
+    subscribe(listener: (event: PurchasePresentationEvent) => void): () => void;
+  };
+  readonly onObserverError?: ObserverErrorHandler;
+}): GamePlatformRuntime<T, S>;

package/dist/game/index.js

@@ -0,0 +1,194 @@
+import { createGameExecutionController, } from '../index.js';
+import { bindGameLifecycle } from '../platform/index.js';
+import { createFullScreenPresentationScope, } from '../presentation/index.js';
+import { createAdClaimEvidenceRecoveryObserver, createCoordinatedPlatformGateway, } from '../ads/index.js';
+import { createGameActionCoordinator, } from '../actions/index.js';
+import { observe } from '../observers.js';
+/** Construct once above every scene, preserving target gateway extensions and receiver binding. */
+export function createGamePlatformRuntime(input) {
+    const execution = createGameExecutionController({
+        ...(input.onObserverError === undefined ? {} : { onListenerError: input.onObserverError }),
+    });
+    const presentation = createFullScreenPresentationScope({ execution });
+    let services;
+    let lateEvidence;
+    const source = input.gateway.ads.provider;
+    const coordinated = source === undefined ? undefined : createCoordinatedPlatformGateway({
+        gateway: input.gateway, provider: source, presentation,
+        canShow: (placement) => input.canShow?.(placement) !== false && (placement.format !== 'rewarded' || services?.monetizationRecovery !== undefined),
+        ...(input.deadline === undefined ? {} : { deadline: input.deadline }),
+        ...(input.purchasePresentation === undefined ? {} : { purchasePresentation: input.purchasePresentation }),
+        ...(input.onObserverError === undefined ? {} : { onObserverError: input.onObserverError }),
+        onClaimEvidence: (observation) => lateEvidence?.(observation),
+        onLateResult: async ({ input: request, result }) => {
+            if (request.format !== 'rewarded' || result.eligibility === 'eligible' || result.presentation !== 'not-started'
+                || result.evidence !== undefined || result.claimEvidence !== undefined || services?.monetizationRecovery === undefined) {
+                return;
+            }
+            if (result.outcome !== 'failed' && result.outcome !== 'unavailable' && result.outcome !== 'skipped') {
+                return;
+            }
+            const recovered = await services.monetizationRecovery.recoverRewardResult(request.idempotencyKey, { status: result.outcome, rewardGranted: false });
+            if (!disposed) {
+                actions?.confirmRecoveredRewardResult(request.idempotencyKey, recovered);
+            }
+        },
+    });
+    const gateway = (coordinated ?? input.gateway);
+    let lifecycle;
+    let actions;
+    let unsubscribeResume;
+    let disposed = false;
+    let hostAudio;
+    let unsubscribeHostAudio;
+    const gameplayScopes = new Map();
+    const lifecycleReason = 'game-runtime:lifecycle';
+    let gameplayActive = false;
+    let hasPlayed = false;
+    let loading = true;
+    let unsubscribeActivity;
+    const updateActivity = () => {
+        const snapshot = execution.getSnapshot();
+        const activity = gateway.gameActivity;
+        const playable = [...gameplayScopes.values()].some(Boolean);
+        const blocked = snapshot.blocks.some((block) => block.channels.includes('simulation')
+            && !(activity?.handlesFocusChanges === true && hasPlayed && block.reason === lifecycleReason));
+        const next = !disposed && snapshot.status === 'active' && playable && !blocked;
+        if (next && loading) {
+            observe(() => {
+                activity?.setLoading(false);
+                loading = false;
+            }, input.onObserverError);
+            if (loading) {
+                return;
+            }
+        }
+        if (next !== gameplayActive) {
+            observe(() => {
+                activity?.setGameplayActive(next);
+                gameplayActive = next;
+                if (next) {
+                    hasPlayed = true;
+                }
+            }, input.onObserverError);
+        }
+    };
+    const createGameplayScope = () => {
+        const owner = {};
+        let ended = disposed;
+        if (!ended) {
+            gameplayScopes.set(owner, false);
+        }
+        return Object.freeze({
+            setActive(active) {
+                if (!ended && !disposed) {
+                    gameplayScopes.set(owner, active);
+                    updateActivity();
+                }
+            },
+            dispose() {
+                if (!ended) {
+                    ended = true;
+                    gameplayScopes.delete(owner);
+                    updateActivity();
+                }
+            },
+        });
+    };
+    const dispose = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        updateActivity();
+        if (loading) {
+            observe(() => {
+                gateway.gameActivity?.setLoading(false);
+                loading = false;
+            }, input.onObserverError);
+        }
+        unsubscribeActivity?.();
+        gameplayScopes.clear();
+        execution.destroy();
+        if (unsubscribeHostAudio !== undefined) {
+            observe(unsubscribeHostAudio, input.onObserverError);
+        }
+        hostAudio?.release();
+        actions?.dispose();
+        coordinated?.dispose();
+        presentation.dispose();
+        lifecycle?.dispose();
+        if (unsubscribeResume !== undefined) {
+            observe(unsubscribeResume, input.onObserverError);
+        }
+    };
+    const reconcile = async () => {
+        if (disposed) {
+            return;
+        }
+        await services?.monetizationRecovery?.reconcile();
+        if (!disposed && input.reconciliation !== undefined) {
+            await actions?.reconcile();
+        }
+    };
+    try {
+        services = input.createServices(gateway);
+        const recovery = services.monetizationRecovery;
+        if (recovery !== undefined) {
+            lateEvidence = createAdClaimEvidenceRecoveryObserver({ recovery, onResult: async (request, result) => {
+                    if (!disposed && result.status === 'rejected') {
+                        actions?.confirmRecoveredRewardResult(request.idempotencyKey, result);
+                    }
+                    if (!disposed && input.reconciliation !== undefined) {
+                        await actions?.reconcile();
+                    }
+                } });
+        }
+        if (services.client !== undefined) {
+            actions = createGameActionCoordinator({ execution, client: services.client,
+                ...(coordinated === undefined ? {} : { presentation }),
+                ...(input.reconciliation === undefined ? {} : { reconciliation: input.reconciliation }),
+                ...(input.onObserverError === undefined ? {} : { onObserverError: input.onObserverError }),
+            });
+        }
+        lifecycle = bindGameLifecycle({ controller: execution, source: gateway.lifecycle, initialState: input.initialLifecycleState,
+            reason: lifecycleReason,
+            ...(input.onObserverError === undefined ? {} : { onError: input.onObserverError }),
+        });
+        unsubscribeResume = gateway.lifecycle.onResume(() => { observe(reconcile, input.onObserverError); });
+        const settings = gateway.gameSettings;
+        if (settings !== undefined) {
+            const updateMute = (muted) => {
+                if (disposed) {
+                    return;
+                }
+                if (muted && hostAudio === undefined) {
+                    hostAudio = execution.acquireBlock({ reason: 'game-runtime:host-audio', channels: ['audio'] });
+                }
+                else if (!muted && hostAudio !== undefined) {
+                    const owned = hostAudio;
+                    hostAudio = undefined;
+                    owned.release();
+                }
+            };
+            unsubscribeHostAudio = settings.onAudioMuteChange(updateMute);
+            updateMute(settings.getAudioMuted());
+        }
+        observe(() => gateway.gameActivity?.setLoading(true), input.onObserverError);
+        unsubscribeActivity = execution.subscribe(updateActivity);
+        return Object.freeze({
+            gateway,
+            execution,
+            presentation,
+            services,
+            createGameplayScope,
+            ...(actions === undefined ? {} : { actions }),
+            reconcile,
+            dispose,
+        });
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+}

package/dist/phaser/index.d.ts

@@ -1,4 +1,5 @@
 import type Phaser from 'phaser';
+import type { GameGameplayScope } from '../game/index.js';
 import type { GameExecutionController, GameExecutionSnapshot } from '../index.js';
 export interface GameplayAudioSink {
   getMuted(): boolean;
@@ -16,9 +17,12 @@ export interface BindPhaserGameSceneInput {
   readonly resetInput: () => void;
   readonly renderingPolicy: 'visibility';
   readonly audio?: GameplayAudioSink;
+  /** A game-owned bindGameAudio projection survives this scene's disposal. */
+  readonly audioOwner?: 'scene' | 'game';
   readonly uiScope?: {
     dispose(): void;
   };
+  readonly gameplayScope?: GameGameplayScope;
   /** Phaser pause also suspends input: simulation-only blocking cannot preserve active input. */
   readonly onUnsupportedState: (snapshot: GameExecutionSnapshot, reason: UnsupportedPhaserExecutionState) => void | Promise<void>;
   readonly onError?: (error: unknown) => void | Promise<void>;

package/dist/phaser/index.js

@@ -9,6 +9,9 @@ export function bindPhaserGameScene(input) {
     if (controller.getSnapshot().status === 'destroyed') {
         throw new Error('Cannot bind a destroyed game execution controller.');
     }
+    if (input.audioOwner === 'game' && audio !== undefined) {
+        throw new TypeError('Game-owned audio cannot also be controlled by a scene sink.');
+    }
     const events = scene.sys.events;
     let disposed = false;
     let sceneEnded = false;
@@ -20,6 +23,7 @@ export function bindPhaserGameScene(input) {
     let ownedVisibility = false;
     let ownedAudio = false;
     let inputBlocked = false;
+    let externallyInactive = scene.sys.isPaused();
     const ownedInput = new Set();
     let unsubscribe = () => { };
     function report(error) {
@@ -96,6 +100,7 @@ export function bindPhaserGameScene(input) {
             }
             disposed = true;
             attempt(unsubscribe);
+            attempt(() => input.gameplayScope?.dispose());
             // Keep shutdown observation installed while restoration calls into consumer/engine code.
             if (mode !== 'terminal') {
                 attempt(() => {
@@ -138,11 +143,14 @@ export function bindPhaserGameScene(input) {
     function onPause() {
         if (!disposed && !applying) {
             ownedPause = false;
+            externallyInactive = true;
+            attempt(() => input.gameplayScope?.setActive(false));
         }
     }
     function onResume() {
         if (!disposed && !applying) {
             ownedPause = false;
+            externallyInactive = false;
             apply();
         }
     }
@@ -150,8 +158,11 @@ export function bindPhaserGameScene(input) {
         // External sleep owns activity/visibility until an external wake. Never wake it ourselves.
         ownedPause = false;
         ownedVisibility = false;
+        externallyInactive = true;
+        attempt(() => input.gameplayScope?.setActive(false));
     }
     function onWake() {
+        externallyInactive = false;
         if (controller.getSnapshot().blocked['gameplay-input']) {
             inputBlocked = false;
         }
@@ -172,9 +183,10 @@ export function bindPhaserGameScene(input) {
                     dispose('terminal');
                     break;
                 }
+                attempt(() => input.gameplayScope?.setActive(!externallyInactive && (scene.sys.isActive() || scene.sys.isPaused())));
                 const blocked = snapshot.blocked;
                 const simulationUnsupported = blocked.simulation && !blocked['gameplay-input'];
-                const audioUnsupported = blocked.audio && audio === undefined;
+                const audioUnsupported = blocked.audio && audio === undefined && input.audioOwner !== 'game';
                 const notifySimulation = simulationUnsupported && !reportedSimulation;
                 const notifyAudio = audioUnsupported && !reportedAudio;
                 reportedSimulation = simulationUnsupported;

package/dist/presentation/index.d.ts

@@ -0,0 +1,41 @@
+import type { GameExecutionController } from '../index.js';
+import { type UiListener } from '../ui/index.js';
+import type { ObserverErrorHandler } from '../observers.js';
+export type FullScreenPresentationKind = 'purchase' | 'rewarded' | 'interstitial';
+export interface FullScreenPresentationOwner {
+  readonly kind: FullScreenPresentationKind;
+  readonly invocationId: string;
+  readonly state: 'requested' | 'open' | 'unknown';
+}
+export interface FullScreenPresentationSnapshot {
+  readonly version: number;
+  readonly status: 'ready' | 'busy' | 'unknown' | 'disposed';
+  readonly owner?: FullScreenPresentationOwner;
+}
+export interface FullScreenPresentationLease {
+  /** Native facts only. A caller deadline or a backend grant cannot confirm closure. */
+  markStarted(): void;
+  markUnknown(): void;
+  confirmClosed(): void;
+}
+export interface FullScreenPresentationScope {
+  readonly execution: GameExecutionController;
+  acquire(input: {
+    readonly kind: FullScreenPresentationKind;
+    readonly invocationId: string;
+    readonly audioStart?: 'requested' | 'started';
+  }): FullScreenPresentationLease;
+  getSnapshot(): FullScreenPresentationSnapshot;
+  subscribe(listener: UiListener<FullScreenPresentationSnapshot>): () => void;
+  /** Stop new presentations and detach projections; retain any live native ownership. */
+  dispose(): void;
+}
+export declare class PresentationExecutionError extends Error {
+  readonly code: 'busy' | 'disposed' | 'key-conflict' | 'history-full' | 'already-completed';
+  constructor(code: 'busy' | 'disposed' | 'key-conflict' | 'history-full' | 'already-completed');
+}
+/** Share one scope above all screens, providers, and purchase/ad entrypoints. */
+export declare function createFullScreenPresentationScope(input: {
+  readonly execution: GameExecutionController;
+  readonly onObserverError?: ObserverErrorHandler;
+}): FullScreenPresentationScope;

package/dist/presentation/index.js

@@ -0,0 +1,153 @@
+import { createGameUiBridge } from '../ui/index.js';
+export class PresentationExecutionError extends Error {
+    code;
+    constructor(code) {
+        super(`Presentation cannot start: ${code}`);
+        this.code = code;
+        this.name = 'PresentationExecutionError';
+    }
+}
+/** Share one scope above all screens, providers, and purchase/ad entrypoints. */
+export function createFullScreenPresentationScope(input) {
+    let disposed = false;
+    let version = 0;
+    let owner;
+    let snapshot = Object.freeze({ version, status: 'ready' });
+    const bridge = createGameUiBridge({
+        initialSnapshot: snapshot,
+        ...(input.onObserverError === undefined ? {} : { onListenerError: input.onObserverError }),
+    });
+    const isDisposed = () => disposed || input.execution.getSnapshot().status === 'destroyed';
+    function publish() {
+        let status = 'ready';
+        if (isDisposed()) {
+            status = 'disposed';
+        }
+        else if (owner?.info.state === 'unknown') {
+            status = 'unknown';
+        }
+        else if (owner !== undefined) {
+            status = 'busy';
+        }
+        snapshot = Object.freeze({
+            version: ++version,
+            status,
+            ...(owner === undefined ? {} : { owner: owner.info }),
+        });
+        if (!disposed) {
+            bridge.setSnapshot(snapshot);
+        }
+    }
+    return Object.freeze({
+        execution: input.execution,
+        acquire(request) {
+            if (isDisposed()) {
+                throw new PresentationExecutionError('disposed');
+            }
+            if (owner !== undefined) {
+                throw new PresentationExecutionError('busy');
+            }
+            const kind = request.kind;
+            const invocationId = request.invocationId;
+            const audioStart = request.audioStart ?? 'requested';
+            if (!['purchase', 'rewarded', 'interstitial'].includes(kind)
+                || typeof invocationId !== 'string' || invocationId.trim() === '' || invocationId.length > 512
+                || (audioStart !== 'requested' && audioStart !== 'started')) {
+                throw new TypeError('Invalid presentation identity.');
+            }
+            if (isDisposed()) {
+                throw new PresentationExecutionError('disposed');
+            }
+            if (owner !== undefined) {
+                throw new PresentationExecutionError('busy');
+            }
+            const owned = {
+                info: Object.freeze({ kind, invocationId, state: 'requested' }),
+            };
+            // Install ownership before execution listeners can reenter during acquisition.
+            owner = owned;
+            try {
+                owned.block = input.execution.acquireBlock({
+                    reason: `presentation:${kind}`, channels: audioStart === 'started' ? ['simulation', 'gameplay-input'] : ['simulation', 'gameplay-input', 'audio'],
+                });
+            }
+            catch (error) {
+                if (owner === owned) {
+                    owner = undefined;
+                }
+                throw error;
+            }
+            let acquiringAudio = false;
+            const ensureAudio = () => {
+                if (audioStart !== 'started' || acquiringAudio || owned.audioBlock !== undefined || input.execution.getSnapshot().status === 'destroyed') {
+                    return;
+                }
+                acquiringAudio = true;
+                try {
+                    const block = input.execution.acquireBlock({ reason: `presentation:${kind}:audio`, channels: ['audio'] });
+                    if (owner === owned) {
+                        owned.audioBlock = block;
+                    }
+                    else {
+                        block.release();
+                    }
+                }
+                finally {
+                    acquiringAudio = false;
+                }
+            };
+            publish();
+            return Object.freeze({
+                markStarted() {
+                    if (owner === owned && owned.info.state !== 'open') {
+                        const previousInfo = owned.info;
+                        ensureAudio();
+                        if (owner !== owned || owned.info !== previousInfo) {
+                            return;
+                        }
+                        owned.info = Object.freeze({ ...owned.info, state: 'open' });
+                        publish();
+                    }
+                },
+                markUnknown() {
+                    if (owner === owned && owned.info.state !== 'unknown') {
+                        const previousInfo = owned.info;
+                        // Lost native observations quarantine audio as well as execution.
+                        ensureAudio();
+                        if (owner !== owned || owned.info !== previousInfo) {
+                            return;
+                        }
+                        owned.info = Object.freeze({ ...owned.info, state: 'unknown' });
+                        publish();
+                    }
+                },
+                confirmClosed() {
+                    if (owner !== owned) {
+                        return;
+                    }
+                    owner = undefined;
+                    publish();
+                    owned.audioBlock?.release();
+                    owned.block?.release();
+                },
+            });
+        },
+        getSnapshot() {
+            if (isDisposed() && snapshot.status !== 'disposed') {
+                publish();
+            }
+            return snapshot;
+        },
+        subscribe: (listener) => bridge.subscribeSnapshot(listener),
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            // Publish disposal before detaching view projections, without proving native closure.
+            snapshot = Object.freeze({ version: ++version, status: 'disposed', ...(owner === undefined ? {} : { owner: owner.info }) });
+            disposed = true;
+            bridge.setSnapshot(snapshot);
+            bridge.destroy();
+        },
+    });
+}

package/docs/phaser.md

@@ -104,3 +104,14 @@ subsequent explicit `dispose()` retries it while the runtime is active. Successf
 cleanup stays idempotent; terminal runtime destruction never retries an unmute.
 Complete this explicit cleanup before reusing the same sink for another binding,
 as required by the single-writer ownership contract. No retry timer is installed.
+
+## Game-owned sound manager
+
+Use `bindGameAudio` from `@mpgd/game-runtime/audio` above every scene and select
+`audioOwner: 'game'` in scene bindings. That option prevents scene-level audio
+projection and suppresses the missing-scene-audio diagnostic; providing both
+it and a scene audio sink is rejected. Connect the game sound manager's mute
+property to the sink. Scene shutdown only detaches its input/render binding.
+Destroy the shared runtime on the Phaser game's destroy event, then detach the
+audio projection. Unknown native presentation and application-owned claim
+recovery survive scene disposal and must not be canceled by SDK cleanup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-runtime",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "description": "Gameplay execution, scoped UI and action coordination with optional Phaser scene bindings.",
   "license": "MIT",
   "keywords": [
@@ -34,6 +34,22 @@
     "./phaser": {
       "types": "./dist/phaser/index.d.ts",
       "default": "./dist/phaser/index.js"
+    },
+    "./presentation": {
+      "types": "./dist/presentation/index.d.ts",
+      "default": "./dist/presentation/index.js"
+    },
+    "./ads": {
+      "types": "./dist/ads/index.d.ts",
+      "default": "./dist/ads/index.js"
+    },
+    "./audio": {
+      "types": "./dist/audio/index.d.ts",
+      "default": "./dist/audio/index.js"
+    },
+    "./game": {
+      "types": "./dist/game/index.d.ts",
+      "default": "./dist/game/index.js"
     }
   },
   "files": [
@@ -48,7 +64,8 @@
     "@types/node": "^24.0.0"
   },
   "dependencies": {
-    "@mpgd/game-services": "0.17.2"
+    "@mpgd/game-services": "0.18.1",
+    "@mpgd/platform": "0.16.0"
   },
   "repository": {
     "type": "git",