@mpgd/cli 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -52,19 +52,19 @@
     "@types/node": "^24.0.0",
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.10.0",
-    "@mpgd/adapter-browser": "0.7.1",
+    "@mpgd/adapter-ait": "0.11.0",
     "@mpgd/adapter-capacitor": "0.4.7",
-    "@mpgd/adapter-devvit": "0.9.1",
+    "@mpgd/adapter-devvit": "0.9.3",
+    "@mpgd/adapter-browser": "0.7.1",
     "@mpgd/adapter-verse8": "0.3.1",
     "@mpgd/analytics": "0.3.10",
     "@mpgd/bridge": "0.9.0",
-    "@mpgd/catalog": "0.7.0",
     "@mpgd/game-services": "0.12.1",
-    "@mpgd/phaser-assets": "0.4.1",
-    "@mpgd/platform": "0.10.0",
+    "@mpgd/catalog": "0.7.0",
     "@mpgd/i18n": "0.5.6",
-    "@mpgd/target-config": "0.13.0"
+    "@mpgd/phaser-assets": "0.4.1",
+    "@mpgd/target-config": "0.13.0",
+    "@mpgd/platform": "0.10.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/phaser-game/README.md

@@ -231,12 +231,16 @@ The generated `devvit.json` app name is a Devvit-safe slug derived from the game
 directory name; edit it before `devvit:init` if you need a different Reddit app
 name.
 
-The default post entry builds a lightweight inline mode launch screen without
-importing Phaser eagerly. Play here loads gameplay inside the post only after a
-user click; Open expanded mode requests the separate `game` entrypoint, whose
-`game.html` document starts the Phaser bundle directly. Keep these physical
-entries separate so feed cards meet Devvit's inline mode performance and
-gesture requirements while still supporting playable posts.
+The default post entry builds a fixed, non-scrolling inline preview without
+importing Phaser. Play full screen requests the separate `game` entrypoint,
+whose `game.html` document starts the Phaser bundle directly. Keep these
+physical entries separate so feed cards preserve Reddit-native gestures and do
+not create scroll traps.
+
+Inline gameplay remains an explicit opt-in through `startDevvitWebView`. Use it
+only when the game interaction is tap/click based and the complete inline
+surface has been reviewed against current Reddit requirements. Generated games
+use `startDevvitPreviewWebView` by default.
 
 First-time Devvit setup:
 
@@ -312,8 +316,16 @@ Apps in Toss navigation chrome is target-owned. Configure the `ait` target's
 `navigationBar` in `mpgd.targets.json`; `mpgd target build ait` validates the
 supported appearance options and forwards them to `apps-in-toss.config.ts` at
 build time. The Phaser starter uses a transparent dark navigation bar without
-back, home, title, or app-icon chrome so game content can continue underneath it. Keep
-the game's own safe-area padding clear of Toss controls.
+back, home, title, or app-icon chrome so game content can continue underneath
+it. The wrapper installs `installAitSafeAreaCssVariables()` before the game
+mount, mirrors the official `SafeArea.get()` and `SafeArea.subscribe()` values
+into `--mpgd-safe-area-*`, and exposes
+`--mpgd-ait-navigation-content-top` for a full-width HUD below the native
+controls. CSS `env(safe-area-inset-*)` remains the local and older-host
+fallback. Custom wrappers should import the installer from
+`@mpgd/adapter-ait/safe-area`; keep SDK imports out of Phaser scenes.
+The default 52px navigation band and 10px edge gap can be overridden through
+the installer options when a custom host treatment has measured geometry.
 
 During the SDK 3 origin transition, allow all four exact origins on every API
 called by the mini-app:

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

@@ -32,9 +32,9 @@ continue to expose game-facing behavior through `PlatformGateway`. The Devvit
 app root is game-owned in `apps/target-devvit`; run `pnpm devvit:init` once
 after login before upload or playtest.
 Verify the default post entry renders a lightweight inline mode launch screen,
-Play here starts gameplay inside the post, and the `game` entry opens the
-separate expanded mode Phaser document. Inline gameplay must remain tap/click
-only and must not trap feed scrolling.
+does not load Phaser or create a scroll container, and Play full screen opens
+the separate expanded mode Phaser document. Inline gameplay remains available
+only as an explicit adapter opt-in and must preserve Reddit-native gestures.
 
 <!-- mpgd:microsoft-store:start -->
 For Microsoft Store changes, keep the first pass as a PWA/web target that uses

package/templates/phaser-game/apps/target-ait/src/main.ts

@@ -2,6 +2,7 @@ import './styles.css';
 
 import type { AitAdPlacementType } from '@mpgd/adapter-ait/ad-config';
 import { installAitHostBridge, type InstallAitHostBridgeOptions } from '@mpgd/adapter-ait/host';
+import { installAitSafeAreaCssVariables } from '@mpgd/adapter-ait/safe-area';
 import { mountAitGameBundle } from '@mpgd/adapter-ait/wrapper';
 
 declare const __MPGD_AIT_APP_NAME__: string;
@@ -10,6 +11,7 @@ declare const __MPGD_AIT_AD_PLACEMENT_TYPES__: Readonly<
   Record<string, AitAdPlacementType>
 >;
 
+installAitSafeAreaCssVariables();
 installAitHostBridge({
   appName: __MPGD_AIT_APP_NAME__,
   adGroupIds: __MPGD_AIT_AD_GROUP_IDS__,

package/templates/phaser-game/apps/target-devvit/README.md

@@ -41,11 +41,15 @@ replace the `devvit.json` scheduler endpoint and should not use process-local
 memory when delivery must cross instances. The generated target exposes only
 the oRPC bridge route; the former JSON compatibility route is not generated.
 
-The default post entry uses `index.html` for a lightweight inline mode launch
-screen. Play here loads Phaser inside the post after a user click. Open expanded
-mode requests the `game` entrypoint, which loads the separate `game.html`
-document. Keep launch UI free of eager game runtime imports, and keep inline
-gameplay tap/click only so the post does not trap feed scrolling.
+The default post entry uses `index.html` for a fixed, non-scrolling preview.
+Play full screen requests the `game` entrypoint, which loads Phaser from the
+separate `game.html` document. Keep preview UI free of game runtime imports so
+the post cannot trap feed scrolling.
+
+Games that intentionally support inline gameplay can opt in through
+`startDevvitWebView`; the generated default uses `startDevvitPreviewWebView`.
+An opt-in inline surface must remain tap/click based and preserve Reddit-native
+gestures across its complete gameplay flow.
 
 The generated bridge does not advertise or accept a generic platform
 leaderboard. Devvit ranking should be owned by a server completion handler that

package/templates/phaser-game/apps/target-devvit/package.json

@@ -19,17 +19,17 @@
     "fix": "ttsc fix"
   },
   "dependencies": {
-    "@devvit/web": "0.13.8",
+    "@devvit/web": "0.14.1",
     "@mpgd/adapter-devvit": "__MPGD_DEPENDENCY_VERSION_ADAPTER_DEVVIT__",
     "@mpgd/bridge": "__MPGD_DEPENDENCY_VERSION_BRIDGE__"
   },
   "devDependencies": {
-    "@devvit/start": "0.13.8",
+    "@devvit/start": "0.14.1",
     "@ttsc/unplugin": "0.18.4",
     "@types/node": "^24.0.0",
-    "devvit": "0.13.8",
+    "devvit": "0.14.1",
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
-    "vite": "8.1.3"
+    "vite": "7.3.6"
   }
 }

package/templates/phaser-game/apps/target-devvit/vite.config.ts

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { devvit } from '@devvit/start/vite';
-import { defineConfig } from 'vite';
+import { defineConfig, type PluginOption } from 'vite';
 
 import { createGameViteSharedConfig } from '../../vite.shared';
 
@@ -10,7 +10,7 @@ const wrapperRoot = fileURLToPath(new URL('.', import.meta.url));
 const gameRoot = resolve(wrapperRoot, '../..');
 
 export default defineConfig(({ mode }) => {
-  const shared = createGameViteSharedConfig({
+  const shared = createGameViteSharedConfig<PluginOption>({
     appTarget: 'reddit',
     configTarget: 'reddit',
     gameRoot,

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

@@ -1,28 +1,26 @@
 import {
   requestDevvitExpandedMode,
-  startDevvitWebView,
-  type DevvitInlineModeContext,
+  startDevvitPreviewWebView,
 } from '@mpgd/adapter-devvit/web';
 
-await startDevvitWebView({
-  async mountInlineMode(context) {
+const expandedRequestRecoveryMs = 8_000;
+
+await startDevvitPreviewWebView({
+  async mountInlinePreview() {
     await import('./devvitInlineMode.css');
-    renderInlineLaunchScreen(context);
+    renderInlineLaunchScreen();
   },
-  async loadGameplay() {
+  async loadExpandedGame() {
     await import('../main');
   },
   onModeUnavailable(error) {
     if (!(error instanceof ReferenceError)) {
-      console.warn('[devvit] web view mode unavailable; loading gameplay.', error);
+      console.warn('[devvit] web view mode unavailable; loading expanded gameplay.', error);
     }
   },
 });
 
-function renderInlineLaunchScreen(
-  context: DevvitInlineModeContext,
-  errorMessage?: string,
-): void {
+function renderInlineLaunchScreen(): void {
   const launchScreen = document.createElement('main');
   launchScreen.className = 'devvit-launch-screen';
 
@@ -35,90 +33,69 @@ function renderInlineLaunchScreen(
 
   const description = document.createElement('p');
   description.className = 'devvit-launch-screen__description';
-  description.textContent = 'Play directly in the post or open expanded mode.';
+  description.textContent = 'Open the full game without interrupting your Reddit feed.';
 
   const actions = document.createElement('div');
   actions.className = 'devvit-launch-screen__actions';
 
-  const playInlineButton = document.createElement('button');
-  playInlineButton.className = 'devvit-launch-screen__button';
-  playInlineButton.type = 'button';
-  playInlineButton.textContent = 'Play here';
-
   const expandButton = document.createElement('button');
-  expandButton.className =
-    'devvit-launch-screen__button devvit-launch-screen__button--secondary';
+  expandButton.className = 'devvit-launch-screen__button';
   expandButton.type = 'button';
-  expandButton.textContent = 'Open expanded mode';
+  expandButton.textContent = 'Play full screen';
 
   const status = document.createElement('p');
   status.className = 'devvit-launch-screen__status';
   status.setAttribute('aria-live', 'polite');
-  status.textContent = errorMessage ?? '';
+  status.setAttribute('role', 'status');
+
+  let nextRequestId = 0;
+  let activeRequestId: number | undefined;
+  let recoveryTimeout: ReturnType<typeof globalThis.setTimeout> | undefined;
+  const recover = (requestId: number, message: string) => {
+    if (activeRequestId !== requestId) {
+      return;
+    }
 
-  playInlineButton.addEventListener('click', () => {
-    setBusy(true, 'Loading gameplay…');
-    const loading = mountGameplayDocument();
+    activeRequestId = undefined;
+    if (recoveryTimeout !== undefined) {
+      globalThis.clearTimeout(recoveryTimeout);
+      recoveryTimeout = undefined;
+    }
 
-    void context.startGameplay()
-      .then(() => {
-        loading.remove();
-      })
-      .catch((error: unknown) => {
-        console.error('[devvit] inline mode gameplay failed to load.', error);
-        renderInlineLaunchScreen(context, 'Gameplay could not start. Try again.');
-      });
-  });
+    expandButton.disabled = false;
+    status.textContent = message;
+  };
   expandButton.addEventListener('click', (event) => {
-    setBusy(true, 'Opening expanded mode…');
+    const requestId = ++nextRequestId;
+
+    activeRequestId = requestId;
+    expandButton.disabled = true;
+    status.textContent = 'Opening full screen…';
+    recoveryTimeout = globalThis.setTimeout(() => {
+      recover(requestId, 'Full screen did not open. Try again.');
+    }, expandedRequestRecoveryMs);
 
     void requestDevvitExpandedMode(event, 'game')
-      .then(() => {
-        setBusy(false, '');
-      })
       .catch((error: unknown) => {
         console.error('[devvit] expanded mode request failed.', error);
-        setBusy(false, 'Expanded mode is unavailable. Try again.');
+        recover(requestId, 'Full screen is unavailable. Try again.');
       });
   });
+  const recoverAfterReturn = () => {
+    if (activeRequestId !== undefined) {
+      recover(activeRequestId, '');
+    }
+  };
+  globalThis.addEventListener('focus', recoverAfterReturn);
+  globalThis.addEventListener('pageshow', recoverAfterReturn);
 
-  actions.append(playInlineButton, expandButton);
+  actions.append(expandButton);
   launchScreen.append(eyebrow, title, description, actions, status);
   const body = requireDocumentBody();
 
-  body.classList.remove('devvit-inline-mode-gameplay');
   body.classList.add('devvit-inline-mode-host');
   delete body.dataset.mpgdPreserveBrowserTouchGestures;
   body.replaceChildren(launchScreen);
-
-  function setBusy(busy: boolean, message: string): void {
-    playInlineButton.disabled = busy;
-    expandButton.disabled = busy;
-    status.textContent = message;
-  }
-}
-
-function mountGameplayDocument(): HTMLElement {
-  const body = requireDocumentBody();
-  const app = document.createElement('main');
-  const game = document.createElement('div');
-  const loading = document.createElement('p');
-
-  app.id = 'app';
-  game.id = 'game';
-  loading.className = 'devvit-inline-gameplay-loading';
-  loading.setAttribute('aria-live', 'polite');
-  loading.setAttribute('role', 'status');
-  loading.textContent = 'Loading gameplay…';
-  game.append(loading);
-  app.append(game);
-
-  body.classList.remove('devvit-inline-mode-host');
-  body.classList.add('devvit-inline-mode-gameplay');
-  body.dataset.mpgdPreserveBrowserTouchGestures = 'true';
-  body.replaceChildren(app);
-
-  return loading;
 }
 
 function requireDocumentBody(): HTMLElement {

package/templates/phaser-game/src/platform/devvitInlineMode.css

@@ -1,35 +1,15 @@
-body.devvit-inline-mode-host {
-  min-width: 320px;
-  min-height: 100vh;
+html,
+body {
+  width: 100%;
+  height: 100%;
   margin: 0;
-  background: #0f172a;
-}
-
-body.devvit-inline-mode-gameplay {
-  overflow-y: auto;
-  overscroll-behavior-y: auto;
-}
-
-body.devvit-inline-mode-gameplay #game {
-  position: relative;
-}
-
-body.devvit-inline-mode-gameplay #game,
-body.devvit-inline-mode-gameplay canvas {
-  touch-action: pan-y !important;
+  overflow: hidden;
+  overscroll-behavior: auto;
+  touch-action: pan-y;
 }
 
-.devvit-inline-gameplay-loading {
-  position: fixed;
-  z-index: 1;
-  inset: 0;
-  display: grid;
-  place-items: center;
-  margin: 0;
+body.devvit-inline-mode-host {
   background: #0f172a;
-  color: #cbd5e1;
-  font: 700 0.875rem/1.5 Inter, ui-sans-serif, system-ui, sans-serif;
-  pointer-events: none;
 }
 
 .devvit-launch-screen,
@@ -38,10 +18,14 @@ body.devvit-inline-mode-gameplay canvas {
 }
 
 .devvit-launch-screen {
-  min-height: 100vh;
+  position: fixed;
+  inset: 0;
+  width: 100%;
+  height: 100dvh;
+  overflow: hidden;
   display: grid;
-  place-content: center;
-  justify-items: start;
+  place-content: safe center;
+  justify-items: center;
   gap: 0.75rem;
   padding: clamp(1.25rem, 5vw, 3rem);
   background:
@@ -49,6 +33,8 @@ body.devvit-inline-mode-gameplay canvas {
     linear-gradient(145deg, #0f172a, #172554);
   color: #f8fafc;
   font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  text-align: center;
+  touch-action: pan-y;
 }
 
 .devvit-launch-screen__eyebrow,
@@ -67,9 +53,16 @@ body.devvit-inline-mode-gameplay canvas {
 }
 
 .devvit-launch-screen h1 {
+  display: -webkit-box;
   max-width: 18ch;
+  max-height: 1.9em;
+  overflow: hidden;
   font-size: clamp(2rem, 9vw, 4.5rem);
   line-height: 0.95;
+  overflow-wrap: anywhere;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
 }
 
 .devvit-launch-screen__description {
@@ -79,9 +72,8 @@ body.devvit-inline-mode-gameplay canvas {
 }
 
 .devvit-launch-screen__actions {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.75rem;
+  width: min(100%, 22rem);
+  display: grid;
   margin-top: 0.5rem;
 }
 
@@ -97,12 +89,6 @@ body.devvit-inline-mode-gameplay canvas {
   cursor: pointer;
 }
 
-.devvit-launch-screen__button--secondary {
-  border-color: #7dd3fc;
-  color: #e0f2fe;
-  background: rgb(15 23 42 / 0.64);
-}
-
 .devvit-launch-screen__button:disabled {
   cursor: wait;
   opacity: 0.65;
@@ -131,3 +117,23 @@ body.devvit-inline-mode-gameplay canvas {
     width: 100%;
   }
 }
+
+@media (max-height: 440px) {
+  .devvit-launch-screen {
+    gap: 0.45rem;
+    padding-block: 0.5rem;
+  }
+
+  .devvit-launch-screen h1 {
+    font-size: clamp(1.75rem, 8vw, 2.5rem);
+  }
+
+  .devvit-launch-screen__description {
+    font-size: 0.875rem;
+    line-height: 1.3;
+  }
+
+  .devvit-launch-screen__actions {
+    margin-top: 0.2rem;
+  }
+}

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

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import ttsc from '@ttsc/unplugin/vite';
-import type { PluginOption, UserConfig } from 'vite';
+import type { PluginOption } from 'vite';
 
 import {
   assertRuntimeTargetConfigMatrix,
@@ -29,9 +29,19 @@ export interface CreateGameViteSharedConfigInput {
   readonly adPlacementsFile?: string;
 }
 
-export function createGameViteSharedConfig(
+/** Vite-major-neutral subset shared by every generated target wrapper. */
+export interface GameViteSharedConfig<SharedPluginOption> {
+  readonly base: string;
+  readonly plugins: SharedPluginOption[];
+  readonly resolve: {
+    readonly alias: Record<string, string>;
+  };
+  readonly define: Record<string, string>;
+}
+
+export function createGameViteSharedConfig<SharedPluginOption = PluginOption>(
   input: CreateGameViteSharedConfigInput,
-): UserConfig {
+): GameViteSharedConfig<SharedPluginOption> {
   const isProduction = input.mode === 'production';
   const appTarget = input.appTarget ?? process.env.APP_TARGET ?? 'browser';
   const configTarget = input.configTarget ?? process.env.MPGD_CONFIG_TARGET ?? '';
@@ -56,7 +66,7 @@ export function createGameViteSharedConfig(
       ttsc({
         project: input.project,
         plugins: false,
-      }) as unknown as PluginOption,
+      }) as unknown as SharedPluginOption,
     ],
     resolve: {
       alias: {