@mpgd/cli 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -51,15 +51,15 @@
     "typescript": "7.0.1-rc",
     "@mpgd/adapter-ait": "0.3.3",
     "@mpgd/adapter-browser": "0.3.2",
+    "@mpgd/adapter-capacitor": "0.3.3",
     "@mpgd/adapter-devvit": "0.3.3",
     "@mpgd/analytics": "0.3.2",
-    "@mpgd/adapter-capacitor": "0.3.3",
     "@mpgd/bridge": "0.4.0",
-    "@mpgd/game-services": "0.3.3",
     "@mpgd/catalog": "0.3.2",
-    "@mpgd/i18n": "0.3.2",
+    "@mpgd/game-services": "0.3.3",
     "@mpgd/phaser-assets": "0.4.0",
-    "@mpgd/target-config": "0.3.3",
+    "@mpgd/i18n": "0.4.0",
+    "@mpgd/target-config": "0.4.0",
     "@mpgd/platform": "0.3.2"
   },
   "main": "./dist/index.js",

package/templates/phaser-game/README.md

@@ -71,6 +71,51 @@ emitted URLs into the manifest with `?url` imports, or keep static
 starter keeps Vite `base: './'` so generated asset URLs stay portable across web
 preview, Apps in Toss, Devvit, Android, and iOS bundles.
 
+## Viewport And Controls
+
+The starter computes an initial viewport plan with `@mpgd/target-config`.
+Measure the game container first, then fall back to `visualViewport` or
+`window.innerWidth`:
+
+```ts
+const measured = measureGameViewport();
+const viewport = resolveTargetViewportPlan({
+  width: measured.width,
+  height: measured.height,
+  source: measured.source,
+  runtime: runtime.config.runtime,
+  orientationPolicy: {
+    mode: 'prefer-landscape',
+  },
+});
+```
+
+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.
+
+- `compact` is `<= 599px`: phone and narrow Devvit/card layouts. Prefer bottom
+  controls and drawers.
+- `medium` is `600px` through `899px`: larger phones, small tablets, and
+  moderate embeds. Keep the play surface centered and only add side controls
+  when touch targets remain comfortable.
+- `expanded` is `>= 900px`: desktop-like layouts. Side controls and panels are
+  acceptable.
+
+Orientation is measured from the container: height greater than width is
+`portrait`; width greater than or equal to height is `landscape`. Devvit should
+be treated as an embedded webview, so do not assume desktop Reddit always means
+an expanded game surface.
+
+Orientation policy is a runtime contract, not a guarantee that every shell can
+hard-lock the device. Use `responsive` when both orientations are playable,
+`prefer-landscape` or `prefer-portrait` when layout guidance should favor one
+orientation, and `lock-landscape` or `lock-portrait` when the game should show a
+soft rotate prompt on mismatch. The generated PWA manifest also declares
+`"orientation": "landscape"` for installed web and Microsoft Store shells; keep
+that manifest value aligned with the runtime policy if you make a portrait-first
+game.
+
 ## Reddit Devvit
 
 This starter owns its Devvit app root in `apps/target-devvit`. That directory

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

@@ -21,3 +21,6 @@ after login before upload or playtest.
 For Microsoft Store changes, keep the first pass as a PWA/web target that uses
 the browser adapter. Add a dedicated Store commerce adapter only when wiring
 Digital Goods API and Payment Request through backend ledger verification.
+
+Verify the first screen reports the viewport orientation policy, and treat
+locked orientation modes as soft prompts instead of unsafe WebView hard locks.

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

@@ -9,6 +9,8 @@ Boundaries:
 - Purchases, rewarded ad grants, and leaderboard records should go through
   backend ledger APIs before mutating durable game save state.
 - 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.
 
 Useful commands:
 

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

@@ -25,6 +25,10 @@
       "id": "runtime.platform.gateway",
       "owner": "src/platform/installPlatform.ts"
     },
+    {
+      "id": "runtime.viewport.orientation-policy",
+      "owner": "src/main.ts"
+    },
     {
       "id": "platform.devvit.app-root",
       "owner": "apps/target-devvit"

package/templates/phaser-game/src/i18n/messages.ts

@@ -3,6 +3,9 @@ import type { Locale } from '@mpgd/i18n';
 export type GameMessageKey =
   | 'title'
   | 'target'
+  | 'viewport'
+  | 'orientationPolicy'
+  | 'orientationMismatch'
   | 'backend'
   | 'features'
   | 'featuresNone'
@@ -19,6 +22,9 @@ const messages = {
   en: {
     title: '__GAME_TITLE__',
     target: 'Target: {target}',
+    viewport: 'Viewport: {sizeClass} {orientation} - controls {controls}',
+    orientationPolicy: 'Orientation policy: {mode}',
+    orientationMismatch: 'Rotate to {orientation} for {mode}',
     backend: 'Game Services: {mode}',
     features: 'Features: {features}',
     featuresNone: 'none',
@@ -34,6 +40,9 @@ const messages = {
   ko: {
     title: '__GAME_TITLE__',
     target: '타깃: {target}',
+    viewport: '뷰포트: {sizeClass} {orientation} - 컨트롤 {controls}',
+    orientationPolicy: '방향 정책: {mode}',
+    orientationMismatch: '{mode}: {orientation} 방향으로 회전',
     backend: 'Game Services: {mode}',
     features: '기능: {features}',
     featuresNone: '없음',

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

@@ -2,6 +2,10 @@ import './styles.css';
 
 import { createAnalyticsReporter, createBufferedAnalyticsSink } from '@mpgd/analytics';
 import { resolveMpgdLocale, type Locale } from '@mpgd/i18n';
+import {
+  resolveTargetViewportPlan,
+  type TargetViewportOrientationPolicy,
+} from '@mpgd/target-config';
 
 import { t } from './i18n/messages';
 import { createClientId } from './runtime/id';
@@ -24,6 +28,14 @@ async function bootstrap(): Promise<void> {
     const runtimeConfig = detectRuntime();
     const platform = await installPlatform(runtimeConfig);
     const runtime = await platform.getTargetRuntime();
+    const orientationPolicy = {
+      mode: 'prefer-landscape',
+    } as const satisfies TargetViewportOrientationPolicy;
+    const viewport = resolveTargetViewportPlan({
+      ...measureGameViewport(),
+      runtime: runtime.config.runtime,
+      orientationPolicy,
+    });
     const player =
       (await platform.identity.getPlayer()) ?? {
         playerId: 'local-player',
@@ -54,6 +66,7 @@ async function bootstrap(): Promise<void> {
       context: {
         platform,
         runtime,
+        viewport,
         player,
         locale,
         gameServices,
@@ -81,3 +94,41 @@ function renderBootstrapError(error: unknown, locale: Locale): void {
   panel.textContent = `${t(locale, 'bootError')}: ${message}`;
   root.append(panel);
 }
+
+function measureGameViewport(): {
+  readonly width: number;
+  readonly height: number;
+  readonly source: 'container' | 'visual-viewport' | 'window';
+} {
+  const container = document.querySelector<HTMLElement>('#game');
+  const rect = container?.getBoundingClientRect();
+
+  if (rect !== undefined && rect.width > 0 && rect.height > 0) {
+    return {
+      width: rect.width,
+      height: rect.height,
+      source: 'container',
+    };
+  }
+
+  const visualViewport = window.visualViewport;
+
+  if (
+    visualViewport !== undefined &&
+    visualViewport !== null &&
+    visualViewport.width > 0 &&
+    visualViewport.height > 0
+  ) {
+    return {
+      width: visualViewport.width,
+      height: visualViewport.height,
+      source: 'visual-viewport',
+    };
+  }
+
+  return {
+    width: window.innerWidth,
+    height: window.innerHeight,
+    source: 'window',
+  };
+}

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

@@ -1,7 +1,11 @@
 import type { AnalyticsReporter, BufferedAnalyticsSink } from '@mpgd/analytics';
 import type { Locale } from '@mpgd/i18n';
 import type { PlayerIdentity } from '@mpgd/platform';
-import type { TargetConfiguredGateway, TargetRuntimeSnapshot } from '@mpgd/target-config';
+import type {
+  TargetConfiguredGateway,
+  TargetRuntimeSnapshot,
+  TargetViewportPlan,
+} from '@mpgd/target-config';
 
 import type { StarterGameServices } from '../platform/gameServices';
 
@@ -10,6 +14,7 @@ export const starterContextKey = 'starterContext';
 export interface StarterContext {
   readonly platform: TargetConfiguredGateway;
   readonly runtime: TargetRuntimeSnapshot;
+  readonly viewport: TargetViewportPlan;
   readonly player: PlayerIdentity;
   readonly locale: Locale;
   readonly gameServices: StarterGameServices;

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

@@ -21,6 +21,16 @@ export class LobbyScene extends Phaser.Scene {
       .filter((feature) => feature.enabled)
       .map((feature) => feature.feature)
       .join(', ') || t(locale, 'featuresNone');
+    const orientation = context.viewport.orientation;
+    const orientationText =
+      orientation.shouldShowRotatePrompt && orientation.preferredOrientation !== undefined
+        ? t(locale, 'orientationMismatch', {
+            mode: orientation.mode,
+            orientation: orientation.preferredOrientation,
+          })
+        : t(locale, 'orientationPolicy', {
+            mode: orientation.mode,
+          });
 
     this.add
       .text(480, 106, t(locale, 'title'), {
@@ -45,14 +55,37 @@ export class LobbyScene extends Phaser.Scene {
       })
       .setOrigin(0.5);
     this.add
-      .text(480, 258, t(locale, 'backend', { mode: context.gameServices.mode }), {
+      .text(
+        480,
+        258,
+        t(locale, 'viewport', {
+          sizeClass: context.viewport.layout.sizeClass,
+          orientation: context.viewport.layout.orientation,
+          controls: context.viewport.recommendation.primaryControls,
+        }),
+        {
+          color: '#d6dee8',
+          fontFamily: 'Arial, sans-serif',
+          fontSize: '18px',
+        },
+      )
+      .setOrigin(0.5);
+    this.add
+      .text(480, 300, orientationText, {
+        color: orientation.shouldShowRotatePrompt ? '#f59e0b' : '#d6dee8',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '18px',
+      })
+      .setOrigin(0.5);
+    this.add
+      .text(480, 342, t(locale, 'backend', { mode: context.gameServices.mode }), {
         color: context.gameServices.mode === 'disabled' ? '#f59e0b' : '#2dd4bf',
         fontFamily: 'Arial, sans-serif',
         fontSize: '18px',
       })
       .setOrigin(0.5);
     this.add
-      .text(480, 336, t(locale, 'tapToStart'), {
+      .text(480, 384, t(locale, 'tapToStart'), {
         color: '#ffffff',
         fontFamily: 'Arial, sans-serif',
         fontSize: '22px',

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

@@ -1,20 +1,43 @@
 html,
-body,
-#game {
+body {
   width: 100%;
   height: 100%;
   margin: 0;
 }
 
 body {
+  display: grid;
+  place-items: center;
+  box-sizing: border-box;
+  min-width: 0;
+  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);
   background: #07111f;
   color: #ffffff;
   font-family: Arial, sans-serif;
 }
 
+#game {
+  --mpgd-game-max-height: calc(
+    100dvh - env(safe-area-inset-top, 0px) - env(safe-area-inset-bottom, 0px)
+  );
+
+  box-sizing: border-box;
+  width: min(100%, 960px, calc(var(--mpgd-game-max-height) * 16 / 9));
+  aspect-ratio: 16 / 9;
+  min-width: 0;
+  min-height: 0;
+  touch-action: none;
+}
+
 canvas {
   display: block;
+  touch-action: none;
 }
 
 .boot-error {