@mpgd/cli 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -50,19 +50,19 @@
     "@types/node": "^24.0.0",
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-capacitor": "0.4.5",
     "@mpgd/adapter-ait": "0.8.0",
+    "@mpgd/adapter-browser": "0.5.1",
     "@mpgd/adapter-devvit": "0.8.5",
     "@mpgd/adapter-verse8": "0.2.2",
-    "@mpgd/adapter-browser": "0.5.1",
-    "@mpgd/analytics": "0.3.8",
+    "@mpgd/adapter-capacitor": "0.4.5",
     "@mpgd/bridge": "0.7.0",
-    "@mpgd/catalog": "0.5.1",
     "@mpgd/game-services": "0.11.0",
-    "@mpgd/phaser-assets": "0.4.1",
     "@mpgd/i18n": "0.5.4",
+    "@mpgd/analytics": "0.3.8",
+    "@mpgd/phaser-assets": "0.4.1",
     "@mpgd/platform": "0.8.0",
-    "@mpgd/target-config": "0.9.1"
+    "@mpgd/catalog": "0.5.1",
+    "@mpgd/target-config": "0.10.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/phaser-game/README.md

@@ -84,6 +84,10 @@ blocks localhost plus literal private or reserved IP addresses.
 this game directory, including non-production builds that use kit reference
 Capacitor shells.
 
+For Sampo private-workspace releases, Devvit RC/final separation, and native
+store-version provenance, see the
+[multi-target release versioning guide](https://github.com/imjlk/mpgd-kit/blob/main/docs/MULTI_TARGET_RELEASE_VERSIONING.md).
+
 Optional targets can add their own config, scripts, runtime wiring, and release
 skill. To enable Microsoft Store after creation, run
 `pnpm exec mpgd target init microsoft-store --game . --kit-path ../mpgd-kit`.
@@ -123,13 +127,15 @@ preview, Apps in Toss, Devvit, Android, and iOS bundles.
 
 ## Viewport And Controls
 
-The starter computes an initial viewport plan with `@mpgd/target-config`.
+The starter computes an initial viewport snapshot with `@mpgd/target-config`.
 Measure the game container first, then fall back to `visualViewport` or
 `window.innerWidth`:
 
 ```ts
+import { resolveTargetViewportSnapshot } from '@mpgd/target-config';
+
 const measured = measureGameViewport();
-const viewport = resolveTargetViewportPlan({
+const viewport = resolveTargetViewportSnapshot({
   width: measured.width,
   height: measured.height,
   source: measured.source,
@@ -142,7 +148,17 @@ const viewport = resolveTargetViewportPlan({
 
 Use this as a starting point for game-specific layout. The returned
 recommendation is not a hard target rule; override it when your playfield or
-input model needs a different UI arrangement.
+input model needs a different UI arrangement. The snapshot also includes
+`safeArea.contentBounds` for a full-bleed game that places its own persistent
+HUD.
+
+The generated HTML uses `viewport-fit=cover`, and the shared stylesheet exposes
+the browser values as `--mpgd-safe-area-*`. The starter's `#game` mount is
+already inside that CSS padding, so its default snapshot has zero local insets.
+If a game instead measures the full browser viewport, pass
+`readTargetViewportSafeAreaInsets(getComputedStyle(document.documentElement))`
+to `resolveTargetViewportSnapshot`. Do not reserve the same inset in both the
+outer CSS and the Phaser layout; that would shrink content twice.
 
 - `compact` is `<= 599px`: phone and narrow Devvit/card layouts. Prefer bottom
   controls and drawers.

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

@@ -60,3 +60,6 @@ game server or replace game-owned production evidence.
 
 Verify the first screen reports the viewport orientation policy, and treat
 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.

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

@@ -15,6 +15,8 @@ Boundaries:
 - Platform SDK imports belong in adapters or target wrappers.
 - Orientation policy should be chosen before adding resize behavior; treat
   locked modes as soft prompts unless a platform adapter supports hard locks.
+- Safe-area geometry must be reserved exactly once: use outer CSS safe-area
+  padding or the viewport snapshot `safeArea.contentBounds`, never both.
 
 Useful commands:
 

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

@@ -40,6 +40,10 @@
       "id": "runtime.viewport.orientation-policy",
       "owner": "src/main.ts"
     },
+    {
+      "id": "runtime.viewport.safe-area-contract",
+      "owner": "src/main.ts"
+    },
     {
       "id": "platform.devvit.app-root",
       "owner": "apps/target-devvit"

package/templates/phaser-game/apps/target-ait/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta
       name="viewport"
-      content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
+      content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"
     />
     <title>__GAME_TITLE__</title>
   </head>

package/templates/phaser-game/apps/target-devvit/src/client/game.html

@@ -2,7 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
+    />
     <meta name="theme-color" content="#0f172a" />
     <title>__GAME_TITLE__</title>
   </head>

package/templates/phaser-game/apps/target-devvit/src/client/index.html

@@ -2,7 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
+    />
     <meta name="theme-color" content="#0f172a" />
     <title>__GAME_TITLE__</title>
   </head>

package/templates/phaser-game/game.html

@@ -2,7 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
+    />
     <meta name="theme-color" content="#0f172a" />
     <title>__GAME_TITLE__</title>
   </head>

package/templates/phaser-game/index.html

@@ -2,7 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
+    />
     <meta name="theme-color" content="#0f172a" />
     <link rel="manifest" href="./manifest.webmanifest" />
     <title>__GAME_TITLE__</title>

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

@@ -4,7 +4,7 @@ import { createAnalyticsReporter, createBufferedAnalyticsSink } from '@mpgd/anal
 import { resolveTargetMpgdLocale, type Locale } from '@mpgd/i18n';
 import type { IdentitySession, LaunchIntent, PlatformGateway } from '@mpgd/platform';
 import {
-  resolveTargetViewportPlan,
+  resolveTargetViewportSnapshot,
   type TargetViewportOrientationPolicy,
 } from '@mpgd/target-config';
 
@@ -18,6 +18,7 @@ import { installMicrosoftStorePwa } from './platform/microsoftStorePwa';
 
 await bootstrap();
 
+/** Install target services, analytics, and viewport state before starting the game. */
 async function bootstrap(): Promise<void> {
   let locale: Locale = 'en';
   let disposeMicrosoftStorePwa: (() => void) | undefined;
@@ -35,7 +36,7 @@ async function bootstrap(): Promise<void> {
     const orientationPolicy = {
       mode: 'prefer-landscape',
     } as const satisfies TargetViewportOrientationPolicy;
-    const viewport = resolveTargetViewportPlan({
+    const viewport = resolveTargetViewportSnapshot({
       ...measureGameViewport(),
       runtime: runtime.config.runtime,
       orientationPolicy,
@@ -56,14 +57,17 @@ async function bootstrap(): Promise<void> {
         ?? runtime.config.localization.fallbackLocale,
     });
     const analyticsSink = createBufferedAnalyticsSink();
+    const analyticsSessionId = createClientId('session');
     const analytics = createAnalyticsReporter({
       target: platform.target,
-      sessionId: createClientId('session'),
+      sessionId: analyticsSessionId,
       sink: analyticsSink,
     });
     const gameServices = createStarterGameServices({
       gateway: platform,
       playerId: identitySession.playerId ?? player.playerId,
+      analytics: analyticsSink,
+      analyticsSessionId,
     });
 
     await analytics.track({
@@ -98,6 +102,7 @@ async function bootstrap(): Promise<void> {
   }
 }
 
+/** Resolve a verified platform session or fall back to a local guest. */
 async function resolveIdentitySession(
   platform: PlatformGateway,
   fallbackPlayerId: string,
@@ -110,6 +115,7 @@ async function resolveIdentitySession(
   }
 }
 
+/** Resolve the host launch intent while preserving a home-entry fallback. */
 async function resolveLaunchIntent(platform: PlatformGateway): Promise<LaunchIntent> {
   try {
     return (await platform.presentation?.getLaunchIntent()) ?? { entry: 'home' };
@@ -119,6 +125,7 @@ async function resolveLaunchIntent(platform: PlatformGateway): Promise<LaunchInt
   }
 }
 
+/** Create the minimal local identity used when a host session is unavailable. */
 function createGuestSession(playerId: string): IdentitySession {
   return {
     identityLevel: 'guest',
@@ -127,6 +134,7 @@ function createGuestSession(playerId: string): IdentitySession {
   };
 }
 
+/** Render a localized bootstrap failure inside the game mount. */
 function renderBootstrapError(error: unknown, locale: Locale): void {
   const message = error instanceof Error ? error.message : String(error);
   const root = document.querySelector<HTMLDivElement>('#game');
@@ -142,6 +150,7 @@ function renderBootstrapError(error: unknown, locale: Locale): void {
   root.append(panel);
 }
 
+/** Measure the game surface before falling back to browser viewport geometry. */
 function measureGameViewport(): {
   readonly width: number;
   readonly height: number;

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

@@ -1,3 +1,4 @@
+import type { AnalyticsSink } from '@mpgd/analytics';
 import {
   createGameServicesRuntime,
   resolveGameServicesAuthorityMode,
@@ -13,10 +14,16 @@ export type StarterGameServices = GameServicesRuntime;
 export function createStarterGameServices(input: {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
+  readonly analytics?: AnalyticsSink;
+  readonly analyticsSessionId?: string;
 }): StarterGameServices {
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
+    ...(input.analytics === undefined ? {} : { analytics: input.analytics }),
+    ...(input.analyticsSessionId === undefined
+      ? {}
+      : { analyticsSessionId: input.analyticsSessionId }),
     authorityMode: resolveGameServicesAuthorityMode(import.meta.env.MODE),
     target: import.meta.env.VITE_MPGD_GAME_SERVICES_TARGET ?? input.gateway.target,
     ...(import.meta.env.VITE_MPGD_GAME_SERVICES_URL === undefined

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

@@ -4,7 +4,7 @@ import type { IdentitySession, LaunchIntent, PlayerIdentity } from '@mpgd/platfo
 import type {
   TargetConfiguredGateway,
   TargetRuntimeSnapshot,
-  TargetViewportPlan,
+  TargetViewportSnapshot,
 } from '@mpgd/target-config';
 
 import type { StarterGameServices } from '../platform/gameServices';
@@ -14,7 +14,7 @@ export const starterContextKey = 'starterContext';
 export interface StarterContext {
   readonly platform: TargetConfiguredGateway;
   readonly runtime: TargetRuntimeSnapshot;
-  readonly viewport: TargetViewportPlan;
+  readonly viewport: TargetViewportSnapshot;
   readonly player: PlayerIdentity;
   readonly identitySession: IdentitySession;
   readonly launchIntent: LaunchIntent;

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

@@ -77,7 +77,7 @@ export class PlayScene extends Phaser.Scene {
   private rewardHint(): string {
     const rewardedAds = this.context.runtime.features.rewardedAds;
 
-    if (!rewardedAds.enabled) {
+    if (!rewardedAds.enabled || this.context.gameServices.client === undefined) {
       return t(this.context.locale, 'rewardUnavailable');
     }
 
@@ -86,27 +86,24 @@ export class PlayScene extends Phaser.Scene {
 
   private async requestRewardedAd(): Promise<void> {
     const rewardedAds = this.context.runtime.features.rewardedAds;
+    const gameServicesClient = this.context.gameServices.client;
 
-    if (!rewardedAds.enabled) {
+    if (!rewardedAds.enabled || gameServicesClient === undefined) {
       this.rewardText.setText(t(this.context.locale, 'rewardUnavailable'));
       return;
     }
 
     try {
-      const result = await this.context.platform.ads.showRewarded({
+      const result = await gameServicesClient.claimRewardedAd({
         placementId: rewardedPlacementId,
         idempotencyKey: createClientId('starter-reward'),
       });
 
-      await this.context.analytics.track({
-        name: result.status === 'completed' ? 'rewarded_ad_completed' : 'rewarded_ad_rejected',
-        properties: {
-          status: result.status,
-          granted: result.rewardGranted,
-        },
-      });
-
-      this.rewardText.setText(t(this.context.locale, 'reward', { status: result.status }));
+      this.rewardText.setText(
+        result.claim?.granted === true
+          ? t(this.context.locale, 'reward', { status: result.status })
+          : t(this.context.locale, 'rewardError'),
+      );
     } catch (error) {
       await this.context.analytics.track({
         name: 'rewarded_ad_rejected',

package/templates/phaser-game/src/styles.css

@@ -1,3 +1,10 @@
+:root {
+  --mpgd-safe-area-top: env(safe-area-inset-top, 0px);
+  --mpgd-safe-area-right: env(safe-area-inset-right, 0px);
+  --mpgd-safe-area-bottom: env(safe-area-inset-bottom, 0px);
+  --mpgd-safe-area-left: env(safe-area-inset-left, 0px);
+}
+
 html,
 body {
   width: 100%;
@@ -13,10 +20,10 @@ body {
   min-height: 100dvh;
   overflow: hidden;
   padding:
-    env(safe-area-inset-top)
-    env(safe-area-inset-right)
-    env(safe-area-inset-bottom)
-    env(safe-area-inset-left);
+    var(--mpgd-safe-area-top)
+    var(--mpgd-safe-area-right)
+    var(--mpgd-safe-area-bottom)
+    var(--mpgd-safe-area-left);
   background: #07111f;
   color: #ffffff;
   font-family: Arial, sans-serif;
@@ -24,7 +31,7 @@ body {
 
 #game {
   --mpgd-game-max-height: calc(
-    100dvh - env(safe-area-inset-top, 0px) - env(safe-area-inset-bottom, 0px)
+    100dvh - var(--mpgd-safe-area-top) - var(--mpgd-safe-area-bottom)
   );
 
   box-sizing: border-box;