@mpgd/game-runtime 0.2.5 → 0.3.0

package/README.md

@@ -73,6 +73,10 @@ pnpm add phaser@^4.2.0
 | `@mpgd/game-runtime/ui` | Scoped snapshots, commands and events |
 | `@mpgd/game-runtime/platform` | Injected lifecycle source binding |
 | `@mpgd/game-runtime/actions` | Purchase and rewarded-ad coordination |
+| `@mpgd/game-runtime/presentation` | Shared native full-screen ownership |
+| `@mpgd/game-runtime/game` | Game-owned gateway, service, lifecycle and action assembly |
+| `@mpgd/game-runtime/audio` | Game-owned audio projection |
+| `@mpgd/game-runtime/ads` | Coordinated provider and gateway, injected deadlines and policy |
 | `@mpgd/game-runtime/phaser` | Optional gameplay scene binding |
 
 Phaser is an optional peer dependency. The root and headless subpaths do not
@@ -96,6 +100,56 @@ and `node packages/game-runtime/test/dist-import.mjs`. The package test also
 installs packed tarballs in an isolated consumer, checks headless declarations
 without DOM types, and checks the optional binding with Phaser declarations.
 
+## Native presentation and financial settlement
+
+Create one `createFullScreenPresentationScope({ execution })` above all screens.
+Pass it to `createCoordinatedPlatformGateway` with the original gateway and its
+v2 ad provider. Use the returned gateway for both direct platform calls and the
+game-services client; pass the same scope and execution controller to
+`createGameActionCoordinator`. The coordinator rejects a mismatched controller.
+
+The scope owns simulation, gameplay input, and audio blocks only while native UI
+is open or uncertain. Native closure releases that invocation's blocks even
+while the game-services client is waiting for a backend claim. Settings and
+background blocks remain independently owned. Financial operations retain their
+existing duplicate, pending, and reconciliation guards.
+
+An injected advertising deadline ends caller waiting and returns an uncertain
+result. It never cancels the native SDK or proves closure. Native close and late
+reward observers survive view disposal while needed. `onClaimEvidence` reports
+late candidates under the original invocation and idempotency key for an
+application-owned claim journal; it cannot grant rewards. Use a durable
+game-services operation store when recovery must survive process restart.
+`claimEvidence` carries a server proof-lookup correlation without asserting local
+SDK eligibility. Registered server verification and its ledger remain authoritative.
+
+Use `createAdClaimEvidenceRecoveryObserver({ recovery, onResult })` to connect
+`onClaimEvidence` to an application-owned recoverable monetization client. Bind
+the handler during bootstrap before enabling SDK entrypoints. The observer
+always forwards an ungranted pending candidate under the original idempotency
+key, which may differ from the display invocation ID. Recovery serializes with
+the original operation, attaches a newly registered lookup envelope to a pending
+journal, and retries its recorded verification request without another SDK call.
+Previously recorded evidence and the first journal timestamp remain fixed.
+An eligibility change can prompt another lookup under the same identity.
+`onResult` observes backend settlement; refresh authoritative state or reconcile
+the action coordinator rather than adding rewards directly from SDK callbacks.
+
+Purchase business results do not prove that native UI closed. Without a trusted
+`classifyPurchasePresentation` function or a native `purchasePresentation`
+event source, the wrapper keeps presentation unknown. Wire actual native close
+facts before enabling the managed purchase path. Events are scoped to the
+original idempotency key and a monotonic sequence; late or foreign events cannot
+release another invocation. Disposal rejects new calls and retains uncertain
+native close observation. Lightweight key history prevents retired purchase
+keys from reopening the SDK; only active/uncertain results and the last settled
+result are retained.
+
+`canShow` is an injected placement policy. No target-specific branch belongs in
+the game flow. Availability and preparation gate SDK calls; a shared busy surface
+blocks purchases, rewarded ads, and interstitials together. The adapter-level
+SDK conformance suites certify each provider separately from these runtime tests.
+
 ## Scoped UI bridge
 
 `@mpgd/game-runtime/ui` is a separate, headless entrypoint. Importing the root
@@ -360,3 +414,60 @@ A reentrant same-key joiner cannot cancel that owner's startup by disposing itse
 If owner/runtime disposal prevents any client invocation, the flight rejects with
 a scheduling error, resets its observed state to `idle`, and emits no business
 completion/exception event. An invoked client failure remains `exception`.
+
+## Game-owned platform assembly
+
+Create one `createGamePlatformRuntime` from `@mpgd/game-runtime/game` during
+bootstrap. Pass the original gateway, an explicit initial lifecycle state,
+a game policy, optional injected wait deadline, and `createServices(gateway)`.
+The services factory must use the supplied coordinated gateway. Its structural
+ports keep this subpath independent of DOM, Phaser, network and schema imports,
+while preserving target-specific gateway extensions and concrete service types.
+
+A versioned provider installs one shared scope for purchases, rewarded ads and
+interstitials. Legacy gateways retain their existing surface and coarse action
+blocking. V2 rewarded display is disabled until the services expose
+`monetizationRecovery`: the application must supply a durable, atomic,
+encrypted operation store rather than a memory fallback. Startup and resume
+reconcile existing records without opening SDK UI. Account changes require a
+new client/runtime bound to that account.
+
+Keep the runtime above scenes. Create scene-owned action controllers from
+`runtime.actions`; dispose those controllers and their input listeners on
+scene shutdown. After an await, check the captured controller's disposal state
+before touching scene objects. A trusted `reconciliation` port can unlock new
+financial keys only after reading the matching authoritative ledger grant.
+The original key/history remains retired and never becomes an SDK retry.
+
+Late registered candidates reach `recoverRewardResult` under the original
+operation idempotency key. `onLateResult` also exposes provider settlement
+that follows a caller deadline. The game assembly journals a definitive
+not-started/non-earned result only when no prior candidate was observed;
+previous proof/request identity is never replaced by a negative callback.
+Native closure and business settlement remain independent, including during
+runtime teardown. Purchase results still require native `purchasePresentation`
+facts to prove physical closure; a business success alone remains unknown.
+
+Bind `bindGameAudio({ execution, sink })` once to the game's sound manager.
+Scenes use `bindPhaserGameScene({ audioOwner: 'game', ... })` and never supply
+a competing scene audio sink. Scene shutdown therefore cannot unmute a live
+native presentation or release background/settings ownership. Disposing an
+audio projection while blocked leaves mute in place. Destroy execution on game
+teardown before detaching the audio projection. Express additional user mute
+ownership with an audio execution block.
+
+The AIT SDK/host/proxy integration test combines this assembly with the real
+client recovery, registered independent verifier and replay-safe ledger. It
+proves late evidence after view disposal, pending authority with zero grants,
+authoritative settlement, immutable request/timestamp reuse, proof replay
+rejection and reconstructed-client recovery with one SDK show. Its memory
+journal/ledger are test fixtures, not production persistence or live Toss
+certification.
+
+`actions.confirmRecoveredRewardResult(key, result)` accepts only a trusted
+journal recovery's confirmed non-grant result for a matching rewarded action.
+It can retire a late SDK preparation failure or a definitive server rejection,
+while preserving original key history and any live native lease. Foreign keys,
+purchase actions, pending results and grant-shaped results cannot be unlocked
+through this path. Positive grants continue through the authoritative ledger
+reconciliation port. This method never updates a disposed view or opens UI.

package/dist/actions/index.d.ts

@@ -1,6 +1,7 @@
 import type { GameServicesOperationClient, GameServicesPurchaseInput, GameServicesPurchaseProgress, GameServicesPurchaseResult, GameServicesRewardedAdInput, GameServicesRewardedAdProgress, GameServicesRewardedAdResult } from '@mpgd/game-services/operations';
 import type { GameExecutionController } from '../index.js';
 import { type ObserverErrorHandler } from '../observers.js';
+import type { FullScreenPresentationScope } from '../presentation/index.js';
 import { type GameUiScope, type UiListener } from '../ui/index.js';
 export type GameActionKind = 'purchase' | 'rewarded-ad';
 interface Inputs {
@@ -93,6 +94,8 @@ export interface GameActionCoordinator {
   createPurchaseController(): GameActionController<'purchase'>;
   createRewardedAdController(): GameActionController<'rewarded-ad'>;
   getPendingOperation(): GameActionPendingOperation | undefined;
+  /** Trusted journal recovery only. Retire a matching non-grant reward without reopening SDK UI. */
+  confirmRecoveredRewardResult(idempotencyKey: string, result: GameServicesRewardedAdResult): boolean;
   /** Concurrent callers join one recovery query; only a matching committed grant unlocks new keys. */
   reconcile(): Promise<GameActionReconciliationResult>;
   getAvailability(): 'ready' | 'busy' | 'reconciliation-required' | 'history-full' | 'disposed';
@@ -103,6 +106,8 @@ export interface GameActionCoordinator {
 export declare function createGameActionCoordinator(options: {
   readonly execution: GameExecutionController;
   readonly client: Pick<GameServicesOperationClient, 'purchase' | 'claimRewardedAd'>;
+  /** Use only with a client backed by createCoordinatedPlatformGateway sharing this scope/execution. */
+  readonly presentation?: FullScreenPresentationScope;
   /** Never evicts keys: once full, new keys are rejected until application teardown. Default 1024. */
   readonly maxRememberedKeys?: number;
   readonly reconciliation?: GameActionReconciliationPort;

package/dist/actions/index.js

@@ -18,6 +18,9 @@ const purchaseSources = {
 /** Bind one coordinator to one runtime/client (including its player identity), above all screens. */
 export function createGameActionCoordinator(options) {
     const { execution, client, onObserverError } = options;
+    if (options.presentation !== undefined && options.presentation.execution !== execution) {
+        throw new TypeError('Action and presentation coordination must share one execution controller.');
+    }
     const capacity = options.maxRememberedKeys ?? 1024;
     const recoveryPlayerId = options.reconciliation?.playerId;
     const recoveryPort = options.reconciliation;
@@ -34,9 +37,11 @@ export function createGameActionCoordinator(options) {
     let nextId = 0;
     let disposed = false;
     let unconfirmed;
+    const recoveredNonGrants = new Set();
     let recoveryFlight;
     function isDisposed() {
-        return disposed || execution.getSnapshot().status === 'destroyed';
+        return disposed || execution.getSnapshot().status === 'destroyed'
+            || options.presentation?.getSnapshot().status === 'disposed';
     }
     function reserve(kind, supplied, canStart) {
         if (isDisposed()) {
@@ -78,6 +83,9 @@ export function createGameActionCoordinator(options) {
         if (current !== undefined) {
             throw new GameActionExecutionError('busy');
         }
+        if (options.presentation?.getSnapshot().owner !== undefined) {
+            throw new GameActionExecutionError('busy');
+        }
         if (history.size >= capacity) {
             throw new GameActionExecutionError('history-full');
         }
@@ -99,9 +107,10 @@ export function createGameActionCoordinator(options) {
         let invoked = false;
         function finish(status) {
             flight.settled = true;
-            if (invoked && (status === 'pending' || status === 'exception')) {
+            if (invoked && (status === 'pending' || status === 'exception') && !(kind === 'rewarded-ad' && recoveredNonGrants.has(key))) {
                 unconfirmed = Object.freeze({ kind, operationId: id, input });
             }
+            recoveredNonGrants.delete(key);
             current = undefined;
             if (invoked) {
                 last = flight;
@@ -163,7 +172,9 @@ export function createGameActionCoordinator(options) {
                         if (isDisposed() || !canStart()) {
                             throw new GameActionExecutionError('disposed');
                         }
-                        block = execution.acquireBlock({ reason: `action:${kind}`, channels: ['simulation', 'gameplay-input'] });
+                        if (options.presentation === undefined) {
+                            block = execution.acquireBlock({ reason: `action:${kind}`, channels: ['simulation', 'gameplay-input'] });
+                        }
                         if (isDisposed() || !canStart()) {
                             throw new GameActionExecutionError('disposed');
                         }
@@ -351,6 +362,26 @@ export function createGameActionCoordinator(options) {
     return Object.freeze({
         createPurchaseController: () => makeController('purchase'),
         getPendingOperation: () => unconfirmed,
+        confirmRecoveredRewardResult(idempotencyKey, result) {
+            if (isDisposed()) {
+                throw new GameActionExecutionError('disposed');
+            }
+            const rejected = result.status === 'rejected' && result.claim?.granted === false && result.claim.disposition === 'rejected';
+            const noCandidate = ['failed', 'skipped', 'unavailable'].includes(result.status) && result.reward.status === result.status
+                && result.reward.rewardGranted === false && result.reward.evidence === undefined && result.reward.ledgerEntryId === undefined && result.claim === undefined;
+            if ((!rejected && !noCandidate) || result.ledgerEntryId !== undefined || result.claim?.ledgerEntryId !== undefined || result.reward.ledgerEntryId !== undefined || result.reward.rewardGranted !== false) {
+                throw new GameActionExecutionError('invalid-reconciliation');
+            }
+            if (unconfirmed?.kind === 'rewarded-ad' && unconfirmed.input.idempotencyKey === idempotencyKey) {
+                unconfirmed = undefined;
+                return true;
+            }
+            if (current !== undefined && current.key === idempotencyKey && current.bridge.getSnapshot().kind === 'rewarded-ad' && !current.settled) {
+                recoveredNonGrants.add(idempotencyKey);
+                return true;
+            }
+            return false;
+        },
         reconcile,
         createRewardedAdController: () => makeController('rewarded-ad'),
         getAvailability() {
@@ -360,6 +391,9 @@ export function createGameActionCoordinator(options) {
             if (current !== undefined) {
                 return 'busy';
             }
+            if (options.presentation?.getSnapshot().owner !== undefined) {
+                return 'busy';
+            }
             if (unconfirmed !== undefined) {
                 return 'reconciliation-required';
             }

package/dist/ads/index.d.ts

@@ -0,0 +1,63 @@
+import type { PlatformEvidenceEnvelope, PlatformGateway, PurchaseResult } from '@mpgd/platform';
+import type { GameServicesRewardedAdResult } from '@mpgd/game-services/operations';
+import { type AdPlacementInput, type AdProvider, type AdShowInput, type AdShowResult } from '@mpgd/platform/ads';
+import { type ObserverErrorHandler } from '../observers.js';
+import { type FullScreenPresentationScope } from '../presentation/index.js';
+/** Scheduling is injected so the runtime remains usable without DOM or Node globals. */
+export interface AdWaitDeadline {
+  readonly milliseconds: number;
+  schedule(callback: () => void, milliseconds: number): () => void;
+}
+export interface AdClaimEvidenceObservation {
+  readonly input: AdShowInput;
+  readonly evidence: PlatformEvidenceEnvelope;
+  readonly eligibility: 'eligible' | 'unknown';
+}
+/** Connect late SDK candidates to the reserved journal operation, without reopening UI. */
+export declare function createAdClaimEvidenceRecoveryObserver(input: {
+  readonly recovery: {
+    recoverRewardResult(idempotencyKey: string, reward: {
+      readonly status: 'pending';
+      readonly rewardGranted: false;
+      readonly evidence: PlatformEvidenceEnvelope;
+    }): Promise<GameServicesRewardedAdResult>;
+  };
+  /** Application-owned settlement observation, never a view-scoped SDK grant callback. */
+  readonly onResult?: (request: AdShowInput, result: GameServicesRewardedAdResult) => void | Promise<void>;
+}): (observation: AdClaimEvidenceObservation) => Promise<void>;
+export interface CoordinatedAdProvider extends AdProvider {
+  /** Detach projections and reject new calls; native terminal/reward observers remain while needed. */
+  dispose(): void;
+}
+export declare function createCoordinatedAdProvider(input: {
+  readonly provider: AdProvider;
+  readonly presentation: FullScreenPresentationScope;
+  readonly canShow?: (placement: AdPlacementInput) => boolean;
+  readonly deadline?: AdWaitDeadline;
+  readonly maxRememberedInvocations?: number;
+  readonly onObserverError?: ObserverErrorHandler;
+  /** Application-owned claim/journal observer, never a grant callback. Survives view disposal. */
+  readonly onClaimEvidence?: (observation: AdClaimEvidenceObservation) => void | Promise<void>;
+  /** Application-owned provider settlement after a caller deadline; never a UI callback. */
+  readonly onLateResult?: (observation: {
+    readonly input: AdShowInput;
+    readonly result: AdShowResult;
+  }) => void | Promise<void>;
+}): CoordinatedAdProvider;
+export interface PurchasePresentationEvent {
+  readonly idempotencyKey: string;
+  readonly sequence: number;
+  readonly state: 'open' | 'closed' | 'not-started' | 'unknown';
+}
+export interface CoordinatedPlatformGateway extends PlatformGateway {
+  dispose(): void;
+}
+/** Games receive this gateway so direct gateway calls use the same native surface. */
+export declare function createCoordinatedPlatformGateway(input: Parameters<typeof createCoordinatedAdProvider>[0] & {
+  readonly gateway: PlatformGateway;
+  /** Trusted native facts only. A purchase business result alone defaults to unknown. */
+  readonly classifyPurchasePresentation?: (result: PurchaseResult) => 'closed' | 'not-started' | 'unknown';
+  readonly purchasePresentation?: {
+    subscribe(listener: (event: PurchasePresentationEvent) => void): () => void;
+  };
+}): CoordinatedPlatformGateway;