@mpgd/game-runtime 0.2.6 → 0.3.0

package/dist/game/index.d.ts

@@ -0,0 +1,41 @@
+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>;
+  };
+}
+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;
+  /** 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,103 @@
+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;
+    const dispose = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        execution.destroy();
+        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,
+            ...(input.onObserverError === undefined ? {} : { onError: input.onObserverError }),
+        });
+        unsubscribeResume = gateway.lifecycle.onResume(() => { observe(reconcile, input.onObserverError); });
+        return Object.freeze({
+            gateway,
+            execution,
+            presentation,
+            services,
+            ...(actions === undefined ? {} : { actions }),
+            reconcile,
+            dispose,
+        });
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+}

package/dist/phaser/index.d.ts

@@ -16,6 +16,8 @@ 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;
   };

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;
@@ -174,7 +177,7 @@ export function bindPhaserGameScene(input) {
                 }
                 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,40 @@
+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;
+  }): 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,120 @@
+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;
+            if (!['purchase', 'rewarded', 'interstitial'].includes(kind)
+                || typeof invocationId !== 'string' || invocationId.trim() === '' || invocationId.length > 512) {
+                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: ['simulation', 'gameplay-input', 'audio'],
+                });
+            }
+            catch (error) {
+                if (owner === owned) {
+                    owner = undefined;
+                }
+                throw error;
+            }
+            publish();
+            return Object.freeze({
+                markStarted() {
+                    if (owner === owned && owned.info.state !== 'open') {
+                        owned.info = Object.freeze({ ...owned.info, state: 'open' });
+                        publish();
+                    }
+                },
+                markUnknown() {
+                    if (owner === owned && owned.info.state !== 'unknown') {
+                        owned.info = Object.freeze({ ...owned.info, state: 'unknown' });
+                        publish();
+                    }
+                },
+                confirmClosed() {
+                    if (owner !== owned) {
+                        return;
+                    }
+                    owner = undefined;
+                    publish();
+                    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.3.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.0",
+    "@mpgd/platform": "0.15.0"
   },
   "repository": {
     "type": "git",