@mpgd/cli 0.36.1 → 0.37.0

package/dist/index.js

@@ -72,6 +72,7 @@ const mpgdTemplateDependencyPackages = [
     { name: '@mpgd/catalog', packageDir: 'packages/catalog' },
     { name: '@mpgd/cli', packageDir: 'packages/cli' },
     { name: '@mpgd/game-services', packageDir: 'packages/game-services' },
+    { name: '@mpgd/game-runtime', packageDir: 'packages/game-runtime' },
     { name: '@mpgd/i18n', packageDir: 'packages/i18n' },
     { name: '@mpgd/phaser-assets', packageDir: 'packages/phaser-assets' },
     { name: '@mpgd/platform', packageDir: 'packages/platform' },

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "646745bcd2b326e05dfb7030e8c15d8a102e054b",
+  "kitGitSha": "9573fe71b8e4a1a338f88582f28bf058448e0aa8",
   "kitDirty": false,
-  "packageVersion": "0.36.1"
+  "packageVersion": "0.37.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.36.1",
+  "version": "0.37.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -54,25 +54,26 @@
     "typia": "13.0.2",
     "undici": "^7.29.1",
     "vite": "8.1.3",
-    "@mpgd/catalog": "0.7.6",
-    "@mpgd/target-config": "0.17.0",
-    "@mpgd/phaser-assets": "0.7.0"
+    "@mpgd/catalog": "0.7.7",
+    "@mpgd/phaser-assets": "0.7.0",
+    "@mpgd/target-config": "0.17.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@types/semver": "^7.8.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.12.7",
-    "@mpgd/adapter-browser": "0.7.8",
-    "@mpgd/adapter-capacitor": "0.6.1",
-    "@mpgd/adapter-verse8": "0.3.11",
-    "@mpgd/adapter-devvit": "0.9.13",
-    "@mpgd/bridge": "0.10.0",
-    "@mpgd/analytics": "0.4.0",
-    "@mpgd/game-services": "0.17.1",
-    "@mpgd/i18n": "0.6.5",
-    "@mpgd/platform": "0.14.0"
+    "@mpgd/adapter-browser": "0.7.9",
+    "@mpgd/adapter-ait": "0.13.0",
+    "@mpgd/adapter-capacitor": "0.7.0",
+    "@mpgd/analytics": "0.4.1",
+    "@mpgd/adapter-verse8": "0.4.0",
+    "@mpgd/game-runtime": "0.3.0",
+    "@mpgd/i18n": "0.6.6",
+    "@mpgd/adapter-devvit": "0.9.15",
+    "@mpgd/platform": "0.15.0",
+    "@mpgd/bridge": "0.11.0",
+    "@mpgd/game-services": "0.18.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/phaser-game/agent/acceptance.md

@@ -63,3 +63,16 @@ locked orientation modes as soft prompts instead of unsafe WebView hard locks.
 Verify safe-area geometry is reserved exactly once: CSS-padded containers must
 not also subtract `safeArea.contentBounds`, while full-bleed game surfaces use
 the snapshot bounds for persistent controls.
+
+## Shared native presentation
+
+- Purchase, rewarded, and interstitial requests use the same game-owned scope.
+- Native closure resumes gameplay while backend verification can remain pending.
+- Timeouts preserve unknown occupancy and late native/recovery observers.
+- Scene shutdown removes its action view and keyboard handler; it never unmutes
+  a live ad or updates a replacement scene from an old Promise.
+- Background and settings ownership remain after another native lease closes.
+- Rewarded v2 is unavailable until a durable encrypted journal is supplied via
+  bootstrap monetization ports. A test memory store is not durable recovery.
+- Use the real adapter's SDK-driven conformance tests and a game-owned platform
+  test environment; generic unit tests do not certify live ad delivery.

package/templates/phaser-game/agent/brief.md

@@ -39,3 +39,12 @@ the game-owned PWA before package generation, then run package acceptance on
 Windows before Partner Center submission. WACK remains an optional recommended
 evidence source, not a universal prerequisite.
 <!-- mpgd:microsoft-store:end -->
+
+## Game-owned execution and advertising
+
+Construct one `createGamePlatformRuntime` during bootstrap. Scenes bind gameplay
+execution with `audioOwner: 'game'`; the Phaser game's sound manager owns audio
+projection. Add SDKs only in target assembly or adapters. All rewarded views use
+the game-owned action coordinator and authoritative services, with an
+application-owned durable encrypted operation store. Keep recovery above scenes
+and reconcile existing operations on startup and resume without opening SDK UI.

package/templates/phaser-game/agent/game-manifest.json

@@ -5,8 +5,19 @@
     "title": "__GAME_TITLE__",
     "engine": "phaser-4"
   },
-  "targets": ["web-preview", "microsoft-store", "verse8", "android", "ios", "ait", "reddit"],
-  "futureTargets": ["telegram", "tauri"],
+  "targets": [
+    "web-preview",
+    "microsoft-store",
+    "verse8",
+    "android",
+    "ios",
+    "ait",
+    "reddit"
+  ],
+  "futureTargets": [
+    "telegram",
+    "tauri"
+  ],
   "platformBoundary": "PlatformGateway",
   "agentWorkflow": {
     "guide": "docs/MPGD_KIT_WORKFLOWS.md",
@@ -67,6 +78,22 @@
     {
       "id": "telemetry.analytics.best-effort",
       "owner": "src/main.ts"
+    },
+    {
+      "id": "runtime.game.owned-presentation",
+      "owner": "src/main.ts",
+      "capabilities": [
+        "game-owned-execution",
+        "shared-full-screen-presentation",
+        "late-claim-recovery",
+        "game-owned-audio"
+      ],
+      "gotchas": [
+        "Create one game runtime above scene lifetimes; scene teardown must not release native presentation or global audio.",
+        "Rewarded v2 requires an application-owned durable encrypted operation journal; never substitute an in-memory map.",
+        "SDK earning and physical closure are separate from an authoritative backend ledger grant.",
+        "Recover existing claims on startup and resume without reopening SDK UI."
+      ]
     }
   ],
   "acceptance": [

package/templates/phaser-game/package.json

@@ -72,7 +72,8 @@
     "@mpgd/platform": "__MPGD_DEPENDENCY_VERSION_PLATFORM__",
     "@mpgd/phaser-assets": "__MPGD_DEPENDENCY_VERSION_PHASER_ASSETS__",
     "@mpgd/target-config": "__MPGD_DEPENDENCY_VERSION_TARGET_CONFIG__",
-    "phaser": "4.2.0"
+    "phaser": "4.2.0",
+    "@mpgd/game-runtime": "__MPGD_DEPENDENCY_VERSION_GAME_RUNTIME__"
   },
   "devDependencies": {
     "@ait-co/console-cli": "^0.1.49",

package/templates/phaser-game/src/main.ts

@@ -1,9 +1,11 @@
+import { createGamePlatformRuntime, type GamePlatformRuntime } from '@mpgd/game-runtime/game';
 import './styles.css';
 
 import { createAnalyticsReporter, createBufferedAnalyticsSink } from '@mpgd/analytics';
 import { resolveTargetMpgdLocale, type Locale } from '@mpgd/i18n';
 import type { IdentitySession, LaunchIntent, PlatformGateway } from '@mpgd/platform';
 import {
+  getEffectiveAdPlacementConfig,
   measureTargetViewport,
   resolveTargetViewportSnapshot,
   waitForTargetViewportMeasurement,
@@ -15,14 +17,15 @@ import { t } from './i18n/messages';
 import { createClientId } from './runtime/id';
 import { createStarterGame } from './runtime/createGame';
 import { detectRuntime } from './platform/runtimeDetector';
-import { createStarterGameServices } from './platform/gameServices';
+import { createStarterGameServices, type StarterMonetizationPorts } from './platform/gameServices';
 import { installPlatform } from './platform/installPlatform';
 import { installMicrosoftStorePwa } from './platform/microsoftStorePwa';
 
 await bootstrap();
 
 /** Install target services, analytics, and viewport state before starting the game. */
-async function bootstrap(): Promise<void> {
+async function bootstrap(options: { readonly monetization?: StarterMonetizationPorts } = {}): Promise<void> {
+  let gameRuntime: GamePlatformRuntime | undefined;
   let locale: Locale = 'en';
   let disposeMicrosoftStorePwa: (() => void) | undefined;
 
@@ -71,13 +74,43 @@ async function bootstrap(): Promise<void> {
       sessionId: analyticsSessionId,
       sink: analyticsSink,
     });
-    const gameServices = createStarterGameServices({
+    const ownedRuntime = createGamePlatformRuntime({
       gateway: platform,
-      playerId: identitySession.playerId ?? player.playerId,
-      configTarget: runtime.configTarget,
-      analytics: analyticsSink,
-      analyticsSessionId,
+      initialLifecycleState: document.visibilityState === 'hidden' ? 'inactive' : 'active',
+      canShow: (placement) => {
+        const enabled = placement.format === 'rewarded'
+          ? runtime.config.features.rewardedAds
+          : runtime.config.features.interstitialAds;
+        const configured = runtime.effectiveConfig === undefined
+          ? undefined
+          : getEffectiveAdPlacementConfig(runtime.effectiveConfig, placement.placementId);
+        return enabled && (runtime.effectiveConfig === undefined || configured !== undefined && configured.reason !== 'target-disabled');
+      },
+      deadline: {
+        milliseconds: 30000,
+        schedule(callback, milliseconds) {
+          const timer = setTimeout(callback, milliseconds);
+          return () => clearTimeout(timer);
+        },
+      },
+      ...(options.monetization?.reconciliation === undefined ? {} : { reconciliation: options.monetization.reconciliation }),
+      ...(options.monetization?.purchasePresentation === undefined ? {} : { purchasePresentation: options.monetization.purchasePresentation }),
+      onObserverError: (error) => {
+        console.error('[game-runtime]', error);
+      },
+      createServices: (gateway) =>
+        createStarterGameServices({
+          gateway,
+          playerId: identitySession.playerId ?? player.playerId,
+          configTarget: runtime.configTarget,
+          ...(options.monetization === undefined ? {} : { operationStore: options.monetization.operationStore }),
+          analytics: analyticsSink,
+          analyticsSessionId,
+        }),
     });
+    gameRuntime = ownedRuntime;
+    const gameServices = ownedRuntime.services;
+    await ownedRuntime.reconcile();
 
     await analytics.track({
       name: 'game_started',
@@ -92,7 +125,8 @@ async function bootstrap(): Promise<void> {
       preserveBrowserTouchGestures:
         document.body.dataset.mpgdPreserveBrowserTouchGestures === 'true',
       context: {
-        platform,
+        platform: ownedRuntime.gateway,
+        gameRuntime: ownedRuntime,
         runtime,
         viewport,
         player,
@@ -105,6 +139,7 @@ async function bootstrap(): Promise<void> {
       },
     });
   } catch (error) {
+    gameRuntime?.dispose();
     disposeMicrosoftStorePwa?.();
     renderBootstrapError(error, locale);
     console.error('[bootstrap]', error);

package/templates/phaser-game/src/platform/gameServices.ts

@@ -5,8 +5,18 @@ import {
   resolveGameServicesTransport,
   type GameServicesRuntime,
   type GameServicesRuntimeMode,
+  type MonetizationOperationStore,
 } from '@mpgd/game-services';
 import type { PlatformGateway } from '@mpgd/platform';
+import type { GameActionReconciliationPort } from '@mpgd/game-runtime/actions';
+import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
+
+/** Supply a game-owned durable encrypted journal and trusted recovery/native facts. */
+export interface StarterMonetizationPorts {
+  readonly operationStore: MonetizationOperationStore;
+  readonly reconciliation?: GameActionReconciliationPort;
+  readonly purchasePresentation?: { subscribe(listener: (event: PurchasePresentationEvent) => void): () => void };
+}
 
 export type StarterBackendMode = GameServicesRuntimeMode;
 export type StarterGameServices = GameServicesRuntime;
@@ -15,12 +25,14 @@ export function createStarterGameServices(input: {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
   readonly configTarget: string;
+  readonly operationStore?: MonetizationOperationStore;
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
 }): StarterGameServices {
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
+    ...(input.operationStore === undefined ? {} : { operationStore: input.operationStore }),
     ...(input.analytics === undefined ? {} : { analytics: input.analytics }),
     ...(input.analyticsSessionId === undefined
       ? {}

package/templates/phaser-game/src/runtime/createGame.ts

@@ -1,3 +1,4 @@
+import { bindGameAudio } from '@mpgd/game-runtime/audio';
 import Phaser from 'phaser';
 
 import { BootScene } from '../scenes/BootScene';
@@ -26,9 +27,35 @@ export function createStarterGame(input: {
       autoCenter: Phaser.Scale.CENTER_BOTH,
     },
     scene: [BootScene, LobbyScene, PlayScene],
+    callbacks: {
+      postBoot(game: Phaser.Game) {
+        game.registry.set(starterContextKey, input.context);
+        ownGameAudio(game, input.context);
+      },
+    },
   });
 
   game.registry.set(starterContextKey, input.context);
 
   return game;
 }
+
+/** The sound manager and execution projection belong to the game, not a scene. */
+function ownGameAudio(game: Phaser.Game, context: StarterContext): void {
+  const audio = bindGameAudio({
+    execution: context.gameRuntime.execution,
+    sink: {
+      getMuted: () => game.sound.mute,
+      setMuted: (muted) => {
+        game.sound.mute = muted;
+      },
+    },
+    onError: (error) => {
+      console.error('[game-audio]', error);
+    },
+  });
+  game.events.once('destroy', () => {
+    context.gameRuntime.dispose();
+    audio.dispose();
+  });
+}

package/templates/phaser-game/src/runtime/gameContext.ts

@@ -1,4 +1,5 @@
 import type { AnalyticsReporter, BufferedAnalyticsSink } from '@mpgd/analytics';
+import type { GamePlatformRuntime } from '@mpgd/game-runtime/game';
 import type { Locale } from '@mpgd/i18n';
 import type { IdentitySession, LaunchIntent, PlayerIdentity } from '@mpgd/platform';
 import type {
@@ -12,6 +13,7 @@ import type { StarterGameServices } from '../platform/gameServices';
 export const starterContextKey = 'starterContext';
 
 export interface StarterContext {
+  readonly gameRuntime: GamePlatformRuntime<TargetConfiguredGateway, StarterGameServices>;
   readonly platform: TargetConfiguredGateway;
   readonly runtime: TargetRuntimeSnapshot;
   readonly viewport: TargetViewportSnapshot;

package/templates/phaser-game/src/scenes/PlayScene.ts

@@ -1,3 +1,5 @@
+import type { GameActionController } from '@mpgd/game-runtime/actions';
+import { bindPhaserGameScene } from '@mpgd/game-runtime/phaser';
 import Phaser from 'phaser';
 
 import type { LogicalAdPlacementId } from '@mpgd/platform';
@@ -17,6 +19,7 @@ export class PlayScene extends Phaser.Scene {
   private rewardText!: Phaser.GameObjects.Text;
   private analyticsText!: Phaser.GameObjects.Text;
   private context!: StarterContext;
+  private rewardedAction: GameActionController<'rewarded-ad'> | undefined;
   private lastScore = -1;
   private lastAnalyticsCount = -1;
 
@@ -26,6 +29,18 @@ export class PlayScene extends Phaser.Scene {
 
   create(): void {
     this.context = this.registry.get(starterContextKey) as StarterContext;
+    bindPhaserGameScene({
+      controller: this.context.gameRuntime.execution,
+      scene: this,
+      renderingPolicy: 'visibility',
+      audioOwner: 'game',
+      resetInput: () => {
+        this.input.keyboard?.resetKeys();
+      },
+      onUnsupportedState: (_snapshot, reason) => {
+        console.error('[game-execution]', reason);
+      },
+    });
 
     this.marker = this.add.image(480, 250, starterAssetKeys.marker).setDisplaySize(72, 72);
     this.scoreText = this.add
@@ -50,8 +65,16 @@ export class PlayScene extends Phaser.Scene {
       })
       .setOrigin(0.5);
 
-    this.input.keyboard?.on('keydown-R', () => {
+    this.rewardedAction = this.context.gameRuntime.actions?.createRewardedAdController();
+    const action = this.rewardedAction;
+    const keyboard = this.input.keyboard;
+    const onReward = () => {
       void this.requestRewardedAd();
+    };
+    keyboard?.on('keydown-R', onReward);
+    this.events.once('shutdown', () => {
+      action?.dispose();
+      keyboard?.off('keydown-R', onReward);
     });
   }
 
@@ -77,7 +100,7 @@ export class PlayScene extends Phaser.Scene {
   private rewardHint(): string {
     const rewardedAds = this.context.runtime.features.rewardedAds;
 
-    if (!rewardedAds.enabled || this.context.gameServices.client === undefined) {
+    if (!rewardedAds.enabled || this.context.gameServices.client === undefined || this.context.gameServices.monetizationRecovery === undefined) {
       return t(this.context.locale, 'rewardUnavailable');
     }
 
@@ -86,19 +109,25 @@ export class PlayScene extends Phaser.Scene {
 
   private async requestRewardedAd(): Promise<void> {
     const rewardedAds = this.context.runtime.features.rewardedAds;
-    const gameServicesClient = this.context.gameServices.client;
+    const action = this.rewardedAction;
 
-    if (!rewardedAds.enabled || gameServicesClient === undefined) {
+    if (!rewardedAds.enabled || action === undefined || this.context.gameServices.monetizationRecovery === undefined) {
       this.rewardText.setText(t(this.context.locale, 'rewardUnavailable'));
       return;
     }
 
+    if (this.context.gameRuntime.actions?.getAvailability() !== 'ready') {
+      return;
+    }
     try {
-      const result = await gameServicesClient.claimRewardedAd({
+      const result = await action.execute({
         placementId: rewardedPlacementId,
         idempotencyKey: createClientId('starter-reward'),
       });
 
+      if (action.isDisposed() || this.rewardedAction !== action) {
+        return;
+      }
       this.rewardText.setText(
         result.claim?.granted === true
           ? t(this.context.locale, 'reward', { status: result.status })
@@ -112,7 +141,9 @@ export class PlayScene extends Phaser.Scene {
           granted: false,
         },
       });
-      this.rewardText.setText(t(this.context.locale, 'rewardError'));
+      if (!action.isDisposed() && this.rewardedAction === action) {
+        this.rewardText.setText(t(this.context.locale, 'rewardError'));
+      }
       console.error('[rewarded-ad]', error);
     }
   }