@mpgd/cli 0.19.0 → 0.20.1

package/dist/build-targets.d.ts

@@ -0,0 +1,4 @@
+export type ConfiguredBuildTargets = Readonly<Record<string, unknown>>;
+export declare const supportedBuildTargets: readonly ['browser', 'web', 'web-preview', 'microsoft-store', 'msstore', 'verse8', 'android', 'ios', 'ait', 'devvit', 'reddit'];
+export declare function normalizeBuildTarget(target: string, configuredTargets?: ConfiguredBuildTargets): string;
+export declare function normalizeConfiguredBuildTargets(configuredTargets: ConfiguredBuildTargets): readonly string[];

package/dist/build-targets.js

@@ -0,0 +1,80 @@
+import { assertDeploymentTargetName } from './target-name.js';
+export const supportedBuildTargets = [
+    'browser',
+    'web',
+    'web-preview',
+    'microsoft-store',
+    'msstore',
+    'verse8',
+    'android',
+    'ios',
+    'ait',
+    'devvit',
+    'reddit',
+];
+const canonicalBuildTargets = new Set([
+    'web-preview',
+    'microsoft-store',
+    'verse8',
+    'android',
+    'ios',
+    'ait',
+    'reddit',
+]);
+export function normalizeBuildTarget(target, configuredTargets = {}) {
+    const normalizedTarget = resolveBuildTarget(target, configuredTargets);
+    if (normalizedTarget !== undefined) {
+        return normalizedTarget;
+    }
+    throw new Error(`Unsupported target: ${target}`);
+}
+export function normalizeConfiguredBuildTargets(configuredTargets) {
+    const targets = new Set();
+    for (const target of Object.keys(configuredTargets)) {
+        const normalizedTarget = resolveBuildTarget(target, configuredTargets);
+        if (normalizedTarget !== undefined) {
+            targets.add(normalizedTarget);
+        }
+    }
+    return [...targets];
+}
+function resolveBuildTarget(target, configuredTargets) {
+    const configuredWebTarget = isConfiguredWebTarget(target, configuredTargets);
+    if (configuredWebTarget) {
+        assertDeploymentTargetName(target);
+    }
+    if (target === 'web' && configuredWebTarget) {
+        return target;
+    }
+    const builtInTarget = normalizeBuiltInBuildTarget(target);
+    if (builtInTarget !== undefined) {
+        return builtInTarget;
+    }
+    if (configuredWebTarget) {
+        return target;
+    }
+    return undefined;
+}
+function normalizeBuiltInBuildTarget(target) {
+    if (target === 'browser' || target === 'web') {
+        return 'web-preview';
+    }
+    if (target === 'msstore') {
+        return 'microsoft-store';
+    }
+    if (target === 'devvit') {
+        return 'reddit';
+    }
+    return canonicalBuildTargets.has(target) ? target : undefined;
+}
+function isConfiguredWebTarget(target, configuredTargets) {
+    if (!Object.prototype.hasOwnProperty.call(configuredTargets, target)) {
+        return false;
+    }
+    const configuredTarget = configuredTargets[target];
+    return typeof configuredTarget === 'object'
+        && configuredTarget !== null
+        && !Array.isArray(configuredTarget)
+        && 'kind' in configuredTarget
+        && configuredTarget.kind === 'web';
+}

package/dist/index.js

@@ -6,12 +6,14 @@ import completion from '@gunshi/plugin-completion';
 import i18n, { defineI18n } from '@gunshi/plugin-i18n';
 import resources from '@gunshi/resources';
 import { cli } from 'gunshi';
+import { normalizeConfiguredBuildTargets, normalizeBuildTarget as normalizeConfiguredTargetName, supportedBuildTargets, } from './build-targets.js';
 import { defaultGameAcceptanceCommandTimeoutMs, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, } from './game-acceptance.js';
 import { resolveGameplayE2EReportFile } from './gameplay-e2e.js';
 import { createMicrosoftStorePackageAcceptanceRuntime, runMicrosoftStorePackageAcceptance, } from './microsoft-store-package-acceptance.js';
 import { runMicrosoftStorePackageGeneration } from './microsoft-store-package-generation.js';
 import { defaultMpgdKitPath, initializeMicrosoftStoreStarter, listMicrosoftStoreInitializerTemplateFiles, prepareBaseGameTemplateFile, } from './microsoft-store-starter.js';
 import { runMicrosoftStoreSubmissionPreflight } from './microsoft-store-submission.js';
+import { targetConfigExtensionsFileEnv } from './target-config-env.js';
 export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, maximumGameplayE2EReportBytes, } from './game-acceptance.js';
 export { createBrowserGameplayE2EDriver, } from './browser-gameplay-e2e.js';
 export { collectGameplayE2EPathEvidence, defaultGameplayE2EReportFile, maximumGameplayE2EStates, parseGameplayE2EPlan, readGameplayE2EPlan, renderGameplayE2EMarkdown, resolveGameplayE2EReportFile, runGameplayE2E, } from './gameplay-e2e.js';
@@ -67,19 +69,6 @@ const allMatrixTargetOrder = [
     'ait',
     'reddit',
 ];
-const supportedBuildTargets = [
-    'browser',
-    'web',
-    'web-preview',
-    'microsoft-store',
-    'msstore',
-    'verse8',
-    'android',
-    'ios',
-    'ait',
-    'devvit',
-    'reddit',
-];
 const supportedVariants = ['wrapper', 'sync', 'simulator', 'archive'];
 const acceptanceStepIds = {
     check: 'check',
@@ -1024,7 +1013,7 @@ const targetCommand = defineI18n({
             },
             run: async (ctx) => {
                 const positionals = readLocalPositionals(ctx.positionals, ['target', 'generate-package']);
-                const target = normalizeBuildTarget(readRequiredPositional(positionals, 0, 'target'));
+                const target = normalizeConfiguredTargetName(readRequiredPositional(positionals, 0, 'target'));
                 if (target !== 'microsoft-store') {
                     throw new Error(`Package generation is not available for target: ${target}`);
                 }
@@ -1102,7 +1091,7 @@ const targetCommand = defineI18n({
             },
             run: (ctx) => {
                 const positionals = readLocalPositionals(ctx.positionals, ['target', 'preflight']);
-                const target = normalizeBuildTarget(readRequiredPositional(positionals, 0, 'target'));
+                const target = normalizeConfiguredTargetName(readRequiredPositional(positionals, 0, 'target'));
                 if (target !== 'microsoft-store') {
                     throw new Error(`Submission preflight is not available for target: ${target}`);
                 }
@@ -1204,7 +1193,7 @@ const targetCommand = defineI18n({
             },
             run: (ctx) => {
                 const positionals = readLocalPositionals(ctx.positionals, ['target', 'accept-package']);
-                const target = normalizeBuildTarget(readRequiredPositional(positionals, 0, 'target'));
+                const target = normalizeConfiguredTargetName(readRequiredPositional(positionals, 0, 'target'));
                 if (target !== 'microsoft-store') {
                     throw new Error(`Package acceptance is not available for target: ${target}`);
                 }
@@ -1397,6 +1386,11 @@ function targetConfigArgs() {
             required: false,
             description: 'Output path for the resolved target config file.',
         },
+        'target-config-extensions-file': {
+            type: 'string',
+            required: false,
+            description: 'Optional game-owned target config extensions file.',
+        },
     };
 }
 function matrixArgResources() {
@@ -1836,6 +1830,7 @@ function createTargetCommandEnv(values) {
     const gameRoot = path.dirname(targetsFile);
     const kitPath = resolveKitPathForTarget(values);
     const resolvedTargetsFile = readOptionalString(values['resolved-targets-file']);
+    const targetConfigExtensionsFile = resolveTargetConfigExtensionsFile(gameRoot, readOptionalString(values['target-config-extensions-file']));
     const preparedTargetsFile = preparePlatformTargetsFile({
         targetsFile,
         kitPath,
@@ -1848,8 +1843,20 @@ function createTargetCommandEnv(values) {
         ...createGameOwnedReleaseEnv(gameRoot, process.env),
         MPGD_KIT_PATH: kitPath,
         MPGD_PLATFORM_TARGETS_FILE: preparedTargetsFile,
+        ...(targetConfigExtensionsFile === undefined
+            ? {}
+            : { [targetConfigExtensionsFileEnv]: targetConfigExtensionsFile }),
     };
 }
+function resolveTargetConfigExtensionsFile(gameRoot, configuredFile) {
+    const inheritedFile = readConfiguredPath(process.env[targetConfigExtensionsFileEnv]);
+    const candidate = configuredFile ?? inheritedFile;
+    if (candidate !== undefined) {
+        return path.resolve(gameRoot, candidate);
+    }
+    const gameOwnedFile = path.join(gameRoot, 'mpgd.target-config.json');
+    return existsSync(gameOwnedFile) ? gameOwnedFile : undefined;
+}
 function createGameOwnedReleaseEnv(gameRoot, baseEnv) {
     const monetizationFiles = resolveGameOwnedMonetizationFiles(gameRoot, baseEnv);
     const sourceGitSha = readOptionalString(baseEnv.MPGD_SOURCE_GIT_SHA)
@@ -1970,7 +1977,7 @@ function replaceTargetTokens(value, context) {
     return value;
 }
 function runTargetCommand(input) {
-    const target = normalizeBuildTarget(input.target);
+    const target = normalizeBuildTarget(input.target, input.env);
     const env = withTargetVariantEnv(target, input.variant, input.env);
     const profile = input.profile ?? 'production';
     const args = input.action === 'build'
@@ -1991,11 +1998,10 @@ function runTargetMatrix(input) {
     }
 }
 function variantForTarget(target, input) {
-    const normalized = normalizeBuildTarget(target);
-    if (normalized === 'ait') {
+    if (target === 'ait') {
         return input.aitVariant;
     }
-    if (normalized === 'ios') {
+    if (target === 'ios') {
         return input.iosVariant;
     }
     return undefined;
@@ -2033,7 +2039,7 @@ function parseTargetList(value, env) {
         .split(',')
         .map((target) => target.trim())
         .filter((target) => target.length > 0)
-        .map((target) => normalizeBuildTarget(target));
+        .map((target) => normalizeBuildTarget(target, env));
     if (targets.length === 0) {
         throw new Error('Target list cannot be empty.');
     }
@@ -2042,6 +2048,13 @@ function parseTargetList(value, env) {
 function configuredTargetsForOrder(env, order, label) {
     const configuredTargets = readConfiguredBuildTargets(env);
     const targets = order.filter((target) => configuredTargets.has(target));
+    if (label === 'all') {
+        for (const target of configuredTargets) {
+            if (!targets.includes(target)) {
+                targets.push(target);
+            }
+        }
+    }
     if (targets.length === 0) {
         throw new Error(`No ${label} targets are configured in ${readConfiguredTargetsFile(env)}.`);
     }
@@ -2052,14 +2065,7 @@ function readConfiguredBuildTargets(env) {
     const parsed = readJsonForCli(file);
     assertJsonObject(parsed, `targets file ${file}`);
     assertJsonObject(parsed.targets, `targets in ${file}`);
-    const targets = new Set();
-    for (const target of Object.keys(parsed.targets)) {
-        const normalized = normalizeConfiguredBuildTarget(target);
-        if (normalized !== undefined) {
-            targets.add(normalized);
-        }
-    }
-    return targets;
+    return new Set(normalizeConfiguredBuildTargets(parsed.targets));
 }
 function readConfiguredTargetsFile(env) {
     const file = env.MPGD_PLATFORM_TARGETS_FILE;
@@ -2111,26 +2117,24 @@ function resolvePotentiallyMissingPath(input) {
 }
 function normalizeConfiguredBuildTarget(target) {
     try {
-        return normalizeBuildTarget(target);
+        return normalizeConfiguredTargetName(target);
     }
     catch {
         return undefined;
     }
 }
-function normalizeBuildTarget(target) {
-    if (target === 'browser' || target === 'web') {
-        return 'web-preview';
-    }
-    if (target === 'msstore') {
-        return 'microsoft-store';
-    }
-    if (target === 'devvit') {
-        return 'reddit';
-    }
-    if (!supportedBuildTargets.includes(target)) {
-        throw new Error(`Unsupported target: ${target}`);
+function normalizeBuildTarget(target, env = process.env) {
+    return normalizeConfiguredTargetName(target, readConfiguredTargetMap(env));
+}
+function readConfiguredTargetMap(env) {
+    const file = env.MPGD_PLATFORM_TARGETS_FILE;
+    if (file === undefined || file.length === 0 || !existsSync(file)) {
+        return {};
     }
-    return target;
+    const parsed = readJsonForCli(file);
+    assertJsonObject(parsed, `targets file ${file}`);
+    assertJsonObject(parsed.targets, `targets in ${file}`);
+    return parsed.targets;
 }
 function assertJsonObject(input, label) {
     if (typeof input !== 'object' || input === null || Array.isArray(input)) {

package/dist/production-target-readiness.d.ts

@@ -4,5 +4,15 @@ export interface ProductionTargetReadinessInput {
   readonly targetsFile: string;
   readonly gameRoot: string;
   readonly gameServicesUrl?: string;
+  readonly targetPolicy?: ProductionTargetPolicy;
+}
+export interface ProductionTargetPolicy {
+  readonly runtime: string;
+  readonly features: {
+    readonly rewardedAds: boolean;
+  };
+  readonly monetization: {
+    readonly rewardedAds: boolean;
+  };
 }
 export declare function assertProductionTargetReadiness(input: ProductionTargetReadinessInput): void;

package/dist/production-target-readiness.js

@@ -16,13 +16,30 @@ export function assertProductionTargetReadiness(input) {
         return;
     }
     const ownerPathKey = ownerPathByTarget[input.target];
-    if (ownerPathKey === undefined) {
+    if (ownerPathKey === undefined && input.targetPolicy === undefined) {
+        throw new Error(`Production target ${input.target} requires a target policy.`);
+    }
+    const requiresVerse8RewardAuthority = input.targetPolicy?.runtime === 'verse8-web'
+        && (input.targetPolicy.features.rewardedAds
+            || input.targetPolicy.monetization.rewardedAds);
+    if (ownerPathKey === undefined && !requiresVerse8RewardAuthority) {
         return;
     }
     const targetConfig = readTargets(input.targetsFile)[input.target];
     if (!isRecord(targetConfig)) {
         throw new Error(`Missing target configuration for ${input.target}.`);
     }
+    if (ownerPathKey === undefined) {
+        if (requiresVerse8RewardAuthority
+            && targetConfig.authoritativeGameServices === false) {
+            throw new Error(`Production target ${input.target} cannot enable rewarded ads without `
+                + 'authoritative game services.');
+        }
+        if (requiresVerse8RewardAuthority || targetConfig.authoritativeGameServices !== false) {
+            assertAuthoritativeGameServicesUrl(input.gameServicesUrl, input.target);
+        }
+        return;
+    }
     const ownerPath = targetConfig[ownerPathKey];
     const webDir = targetConfig.webDir;
     if (typeof ownerPath !== 'string' || ownerPath.length === 0) {

package/dist/target-config-env.d.ts

@@ -0,0 +1,2 @@
+export declare const targetConfigExtensionsFileEnv = "MPGD_TARGET_CONFIG_EXTENSIONS_FILE";
+export declare const targetConfigMatrixFileEnv = "MPGD_TARGET_CONFIG_MATRIX_FILE";

package/dist/target-config-env.js

@@ -0,0 +1,2 @@
+export const targetConfigExtensionsFileEnv = 'MPGD_TARGET_CONFIG_EXTENSIONS_FILE';
+export const targetConfigMatrixFileEnv = 'MPGD_TARGET_CONFIG_MATRIX_FILE';

package/dist/target-name.d.ts

@@ -0,0 +1 @@
+export declare function assertDeploymentTargetName(target: string): void;

package/dist/target-name.js

@@ -0,0 +1,23 @@
+const deploymentTargetNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const reservedDeploymentTargetNames = new Set([
+    'aux',
+    'browser',
+    'con',
+    'devvit',
+    'index',
+    'msstore',
+    'nul',
+    'prn',
+    'constructor',
+    'prototype',
+    ...Array.from({ length: 9 }, (_, index) => `com${String(index + 1)}`),
+    ...Array.from({ length: 9 }, (_, index) => `lpt${String(index + 1)}`),
+]);
+const maximumDeploymentTargetNameLength = 64;
+export function assertDeploymentTargetName(target) {
+    if (!deploymentTargetNamePattern.test(target)
+        || target.length > maximumDeploymentTargetNameLength
+        || reservedDeploymentTargetNames.has(target)) {
+        throw new Error(`Invalid deployment target name: ${target}. Use lowercase kebab-case and avoid reserved names.`);
+    }
+}

package/package.json

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

package/templates/phaser-game/README.md

@@ -127,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,
@@ -146,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/env.d.ts

@@ -5,6 +5,9 @@ declare const __MPGD_CONFIG_TARGET__: string;
 declare const __MPGD_PLATFORM_TARGET__:
   | import('@mpgd/target-config').EffectivePlatformTargetMetadata
   | undefined;
+declare const __MPGD_TARGET_CONFIG_MATRIX__:
+  | import('@mpgd/target-config').TargetConfigMatrix
+  | undefined;
 declare const __APP_VERSION__: string;
 declare const __BUILD_ID__: string;
 declare const __SOURCE_GIT_SHA__: string;

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,18 @@ 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,
+      configTarget: runtime.configTarget,
+      analytics: analyticsSink,
+      analyticsSessionId,
     });
 
     await analytics.track({
@@ -98,6 +103,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 +116,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 +126,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 +135,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 +151,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/buildGateways/verse8.ts

@@ -1,15 +1,21 @@
 import { createVerse8PlatformGateway } from '@mpgd/adapter-verse8';
-import type { AdPlacements } from '@mpgd/catalog';
+import {
+  resolveAdPlacementPlatformId,
+  type AdPlacements,
+} from '@mpgd/catalog';
 import adPlacementsJson from '@mpgd/catalog/placements.json';
 import type { PlatformGateway } from '@mpgd/platform';
 
 import type { RuntimeConfig } from '../runtimeDetector';
 
-export async function createBuildGateway(_runtime: RuntimeConfig): Promise<PlatformGateway> {
+export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
   const adPlacements = adPlacementsJson as AdPlacements;
   const placementIds = new Map(
     adPlacements.placements.flatMap((placement) => {
-      const platformPlacementId = placement.platformPlacementIds.verse8;
+      const platformPlacementId = resolveAdPlacementPlatformId(
+        placement,
+        runtime.configTarget,
+      );
 
       return platformPlacementId === undefined
         ? []

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

@@ -1,3 +1,4 @@
+import type { AnalyticsSink } from '@mpgd/analytics';
 import {
   createGameServicesRuntime,
   resolveGameServicesAuthorityMode,
@@ -13,12 +14,20 @@ export type StarterGameServices = GameServicesRuntime;
 export function createStarterGameServices(input: {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
+  readonly configTarget: 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,
+    deploymentTarget: input.configTarget,
     ...(import.meta.env.VITE_MPGD_GAME_SERVICES_URL === undefined
       ? {}
       : { baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL }),

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

@@ -15,7 +15,8 @@ import targetConfigMatrixJson from '@mpgd/target-config/targets.json';
 
 import type { RuntimeConfig } from './runtimeDetector';
 
-const targetConfigMatrix = targetConfigMatrixJson as TargetConfigMatrix;
+const targetConfigMatrix = __MPGD_TARGET_CONFIG_MATRIX__
+  ?? targetConfigMatrixJson as TargetConfigMatrix;
 const productCatalog = productCatalogJson as ProductCatalog;
 const adPlacements = adPlacementsJson as AdPlacements;
 const targetAdPlacements = adPlacements.placements.map((placement) => ({

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;

package/templates/phaser-game/vite.runtime-target-config.ts

@@ -0,0 +1,176 @@
+import type {
+  IntegrationAvailabilityState,
+  PresentationMode,
+  ReleaseProfile,
+  StorageSupport,
+  TargetConfig,
+  TargetConfigMatrix,
+  TargetIntegration,
+  TargetRuntimeKind,
+} from '@mpgd/target-config';
+
+export type { TargetConfigMatrix } from '@mpgd/target-config';
+
+const runtimeKinds = valueSet({
+  'web-preview': true,
+  'microsoft-store-pwa': true,
+  'capacitor-android': true,
+  'capacitor-ios': true,
+  'apps-in-toss': true,
+  'devvit-web': true,
+  'verse8-web': true,
+} satisfies Record<TargetRuntimeKind, true>);
+const releaseProfiles = valueSet({
+  'web-preview': true,
+  'microsoft-store': true,
+  'google-play': true,
+  'app-store': true,
+  'apps-in-toss': true,
+  'devvit': true,
+  'verse8': true,
+} satisfies Record<ReleaseProfile, true>);
+const storageSupportValues = valueSet({
+  local: true,
+  native: true,
+  none: true,
+} satisfies Record<StorageSupport, true>);
+const integrationAvailabilityValues = valueSet({
+  available: true,
+  disabled: true,
+  'approval-required': true,
+  'configuration-required': true,
+  unsupported: true,
+} satisfies Record<IntegrationAvailabilityState, true>);
+const presentationModeValues = valueSet({
+  fullscreen: true,
+  'inline-expanded': true,
+} satisfies Record<PresentationMode, true>);
+const targetIntegrations = Object.keys({
+  identityUpgrade: true,
+  presentation: true,
+  sharing: true,
+  inboundShare: true,
+  notifications: true,
+} satisfies Record<TargetIntegration, true>);
+
+export function assertRuntimeTargetConfigMatrix(input: unknown): TargetConfigMatrix {
+  assertRecord(input, 'target config matrix');
+  assertNonEmptyString(input.version, 'target config matrix.version');
+  assertRecord(input.targets, 'target config matrix.targets');
+
+  for (const [target, config] of Object.entries(input.targets)) {
+    assertNonEmptyString(target, 'target config matrix target name');
+    assertTargetConfig(config, `target config matrix.targets.${target}`);
+  }
+
+  return input as unknown as TargetConfigMatrix;
+}
+
+function assertTargetConfig(input: unknown, label: string): asserts input is TargetConfig {
+  assertRecord(input, label);
+  assertOneOf(input.runtime, runtimeKinds, `${label}.runtime`);
+
+  assertRecord(input.features, `${label}.features`);
+  assertBooleanFields(
+    input.features,
+    ['iap', 'rewardedAds', 'interstitialAds', 'leaderboard', 'localization'],
+    `${label}.features`,
+  );
+
+  assertRecord(input.capabilities, `${label}.capabilities`);
+  assertOneOf(input.capabilities.storage, storageSupportValues, `${label}.capabilities.storage`);
+  assertBoolean(input.capabilities.localization, `${label}.capabilities.localization`);
+
+  assertRecord(input.localization, `${label}.localization`);
+  assertNonEmptyString(input.localization.fallbackLocale, `${label}.localization.fallbackLocale`);
+
+  assertRecord(input.monetization, `${label}.monetization`);
+  assertBooleanFields(
+    input.monetization,
+    ['iap', 'rewardedAds', 'interstitialAds'],
+    `${label}.monetization`,
+  );
+
+  assertRecord(input.leaderboard, `${label}.leaderboard`);
+  assertBoolean(input.leaderboard.native, `${label}.leaderboard.native`);
+
+  assertRecord(input.release, `${label}.release`);
+  assertOneOf(input.release.profile, releaseProfiles, `${label}.release.profile`);
+
+  assertRecord(input.policy, `${label}.policy`);
+  assertBooleanFields(
+    input.policy,
+    [
+      'externalPaymentAllowed',
+      'remoteExecutableCodeAllowed',
+      'installOtherAppCTAAllowed',
+      'requiresStoreReview',
+      'requiresAitReview',
+    ],
+    `${label}.policy`,
+  );
+
+  if (input.integrations !== undefined) {
+    assertRecord(input.integrations, `${label}.integrations`);
+    for (const key of targetIntegrations) {
+      assertOneOf(
+        input.integrations[key],
+        integrationAvailabilityValues,
+        `${label}.integrations.${key}`,
+      );
+    }
+    assertOneOf(
+      input.integrations.presentationMode,
+      presentationModeValues,
+      `${label}.integrations.presentationMode`,
+    );
+  }
+}
+
+function assertBooleanFields(
+  input: Record<string, unknown>,
+  fields: readonly string[],
+  label: string,
+): void {
+  for (const field of fields) {
+    assertBoolean(input[field], `${label}.${field}`);
+  }
+}
+
+function assertBoolean(input: unknown, label: string): asserts input is boolean {
+  if (typeof input !== 'boolean') {
+    throw new Error(`${label} must be a boolean.`);
+  }
+}
+
+function assertNonEmptyString(input: unknown, label: string): asserts input is string {
+  if (typeof input !== 'string' || input.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+}
+
+function assertOneOf(input: unknown, values: ReadonlySet<string>, label: string): void {
+  if (typeof input !== 'string' || !values.has(input)) {
+    throw new Error(
+      `${label} has unsupported value ${formatValue(input)}; expected one of ${[...values].join(', ')}.`,
+    );
+  }
+}
+
+function formatValue(input: unknown): string {
+  try {
+    return JSON.stringify(input) ?? String(input);
+  } catch {
+    return String(input);
+  }
+}
+
+function valueSet<T extends string>(values: Record<T, true>): ReadonlySet<string> {
+  return new Set(Object.keys(values));
+}
+
+function assertRecord(input: unknown, label: string): asserts input is Record<string, unknown> {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    throw new Error(`${label} must be an object.`);
+  }
+}

package/templates/phaser-game/vite.shared.ts

@@ -4,6 +4,11 @@ import { resolve } from 'node:path';
 import ttsc from '@ttsc/unplugin/vite';
 import type { UserConfig } from 'vite';
 
+import {
+  assertRuntimeTargetConfigMatrix,
+  type TargetConfigMatrix,
+} from './vite.runtime-target-config';
+
 interface RuntimePlatformTargetMetadata {
   readonly kind: string;
   readonly adapter: string;
@@ -39,6 +44,9 @@ export function createGameViteSharedConfig(
     debug: !isProduction,
     buildId: process.env.BUILD_ID ?? 'local',
   });
+  const runtimeTargetConfigMatrix = readRuntimeTargetConfigMatrix(
+    process.env.MPGD_TARGET_CONFIG_MATRIX_FILE,
+  );
 
   return {
     base: './',
@@ -63,6 +71,10 @@ export function createGameViteSharedConfig(
       __MPGD_CONFIG_TARGET__: JSON.stringify(configTarget),
       __MPGD_PLATFORM_TARGET__:
         platformTarget === undefined ? 'undefined' : JSON.stringify(platformTarget),
+      __MPGD_TARGET_CONFIG_MATRIX__:
+        runtimeTargetConfigMatrix === undefined
+          ? 'undefined'
+          : JSON.stringify(runtimeTargetConfigMatrix),
       __APP_VERSION__: JSON.stringify(process.env.APP_VERSION ?? '0.0.0-dev'),
       __BUILD_ID__: JSON.stringify(process.env.BUILD_ID ?? 'local'),
       __SOURCE_GIT_SHA__: JSON.stringify(process.env.MPGD_SOURCE_GIT_SHA ?? 'uncommitted'),
@@ -71,6 +83,27 @@ export function createGameViteSharedConfig(
   };
 }
 
+function readRuntimeTargetConfigMatrix(
+  source: string | undefined,
+): TargetConfigMatrix | undefined {
+  const matrixFile = source?.trim();
+  if (matrixFile === undefined || matrixFile.length === 0) {
+    return undefined;
+  }
+
+  const resolvedMatrixFile = resolve(matrixFile);
+
+  try {
+    return assertRuntimeTargetConfigMatrix(
+      JSON.parse(readFileSync(resolvedMatrixFile, 'utf8')) as unknown,
+    );
+  } catch (error) {
+    throw new Error(
+      `Failed to read or validate MPGD_TARGET_CONFIG_MATRIX_FILE at ${resolvedMatrixFile}: ${formatError(error)}`,
+    );
+  }
+}
+
 export function resolveBuildGatewayModule(input: {
   readonly target: string;
   readonly debug: boolean;