@mpgd/cli 0.54.1 → 0.56.0

package/dist/capacitor-shell-starter.js

@@ -5,7 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { DOMParser } from '@xmldom/xmldom';
 import { satisfies, valid, validRange } from 'semver';
-import { capacitorGatewayRegistersNotifications, conflictingPushPlugin, notificationsCapacitorGatewayModules, notificationsCapacitorGateways, notificationsCapacitorSupportFiles, notificationsCapacitorTemplateSupportFiles, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, wireCapacitorGatewayNotifications, } from './notifications-starter.js';
+import { capacitorGatewayRegistersNotifications, conflictingPushPlugin, notificationsCapacitorGatewayModules, notificationsCapacitorGateways, notificationsCapacitorSupportFiles, notificationsCapacitorTemplateSupportFiles, notificationsCapacitorTemplateSupportImporters, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, sourceReferencesRelativeModule, wireCapacitorGatewayNotifications, } from './notifications-starter.js';
 import { isNonPublicServiceHostname } from './production-target-readiness.js';
 import { assertAndroidSettingsAppProject, assertAndroidSettingsNoAppRemap, assertIosReleaseInfoPlistExpansion, assertIosReleasePackagingSettings, assertIosReleaseProductName, assertNativeShellIdentity, hasAndroidDisplayNameResourceOverride, hasAndroidManifestSourceSetOverride, hasAndroidResourceSourceSetOverride, hasGradleIdentityMutation, hasGradleTaskAction, maskGradleStrings, readIosAppTargetId, readIosReleaseInfoPlist, stripGradleComments, } from './native-shell-identity.js';
 const shellPath = 'apps/mobile-capacitor';
@@ -2796,9 +2796,29 @@ function planNotificationsProvider(input) {
         // Base-template modules they import, missing from a game an earlier release created.
         if (input.templateRoot !== undefined) {
             for (const file of notificationsCapacitorTemplateSupportFiles) {
-                if (readExisting(safeDestination(gameRoot, file)) === undefined) {
-                    files.push({ path: file, content: starterFile(input.templateRoot, file) });
+                if (readExisting(safeDestination(gameRoot, file)) !== undefined) {
+                    continue;
                 }
+                const imported = notificationsCapacitorTemplateSupportImporters[file];
+                const importerSource = imported === undefined
+                    ? undefined
+                    : readExisting(safeDestination(gameRoot, imported.importer));
+                // A game whose own importer does not import the module would never use it.
+                if (imported !== undefined && importerSource !== undefined
+                    && !sourceReferencesRelativeModule(importerSource, path.posix.basename(file, '.ts'))) {
+                    warnings.push(imported.warning);
+                    continue;
+                }
+                // The file imports a kit export an older installed package lacks.
+                const required = imported?.requires;
+                if (required !== undefined
+                    && installedPackageLacksExport(gameRoot, required.packageName, required.exportName)) {
+                    const version = installedPackageVersion(gameRoot, required.packageName);
+                    throw new Error(`--providers notifications writes ${file}, which imports ${required.exportName} from `
+                        + `${required.packageName}; the game's ${required.packageName} ${version} does not export it. `
+                        + "Upgrade the game's kit packages (mpgd kit upgrade) first.");
+                }
+                files.push({ path: file, content: starterFile(input.templateRoot, file) });
             }
         }
         warnings.push('The notification settings screen is not added to an existing game; render one from '
@@ -2905,3 +2925,110 @@ function requireString(value, label) {
 function json(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
+/** Declaration files the export check reads at most: a guard against a pathological graph. */
+const maxDeclarationFilesChecked = 500;
+/** The declaration file names TypeScript pairs with a module specifier. */
+function declarationCandidates(base) {
+    // A specifier that already names a declaration file is that file.
+    if (/\.d\.[cm]?ts$/u.test(base)) {
+        return [base];
+    }
+    const extension = path.extname(base);
+    const stem = base.slice(0, base.length - extension.length);
+    switch (extension) {
+        case '.js':
+        case '.ts':
+            return [`${stem}.d.ts`];
+        case '.mjs':
+        case '.mts':
+            return [`${stem}.d.mts`];
+        case '.cjs':
+        case '.cts':
+            return [`${stem}.d.cts`];
+        default:
+            return [`${base}.d.ts`, path.join(base, 'index.d.ts')];
+    }
+}
+/**
+ * Whether the game's installed `packageName` provably lacks `exportName`:
+ * its root type declarations, and every declaration file they re-export
+ * from through relative specifiers, at any depth, never name it. Anything
+ * the check cannot follow passes, and the game's build then decides, as for
+ * the adapter's settings opener: an uninstalled or unreadable package, a
+ * module it cannot read, or an `export *` from another package.
+ */
+function installedPackageLacksExport(gameRoot, packageName, exportName) {
+    // Only a plain identifier is searched for; anything else is not proof of absence.
+    if (!/^[A-Za-z_$][\w$]*$/u.test(exportName)) {
+        return false;
+    }
+    const packageRoot = path.join(gameRoot, 'node_modules', packageName);
+    const manifest = readInstalledManifest(gameRoot, packageName);
+    if (manifest === undefined) {
+        return false;
+    }
+    const rootExport = typeof manifest.exports === 'object' && manifest.exports !== null
+        ? manifest.exports['.']
+        : undefined;
+    const rootTypes = typeof rootExport === 'object' && rootExport !== null
+        ? rootExport.types
+        : undefined;
+    const typesPath = typeof rootTypes === 'string' ? rootTypes : manifest.types;
+    if (typeof typesPath !== 'string') {
+        return false;
+    }
+    // Every declaration file the root re-exports from, followed through relative
+    // `export … from` specifiers at any depth; the name is searched as text, so a
+    // named re-export of it counts as well.
+    const relativeFrom = /\bexport\b[^;]*?\bfrom\s*['"](\.{1,2}\/[^'"]+)['"]/gu;
+    const packageStar = /\bexport\s*(?:type\s*)?\*\s*(?:as\s+[\w$]+\s*)?from\s*['"](?!\.{1,2}\/)[^'"]+['"]/u;
+    const nameUsed = new RegExp(`(?<![\\w$])${exportName.replace(/\$/gu, '\\$')}(?![\\w$])`, 'u');
+    const pending = [path.join(packageRoot, typesPath)];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const file = pending.pop() ?? '';
+        if (visited.has(file)) {
+            continue;
+        }
+        visited.add(file);
+        if (visited.size > maxDeclarationFilesChecked) {
+            return false;
+        }
+        let source;
+        try {
+            source = readExisting(file);
+        }
+        catch {
+            source = undefined;
+        }
+        if (source === undefined || packageStar.test(source)) {
+            // A module the check cannot read, or names from another package: do not refuse on a guess.
+            return false;
+        }
+        if (nameUsed.test(source)) {
+            return false;
+        }
+        for (const match of source.matchAll(relativeFrom)) {
+            const candidates = declarationCandidates(path.join(path.dirname(file), match[1] ?? ''));
+            pending.push(candidates.find((candidate) => existsSync(candidate)) ?? candidates[0] ?? file);
+        }
+    }
+    return true;
+}
+/** The game's installed `packageName` manifest, or `undefined` when it is missing or unreadable. */
+function readInstalledManifest(gameRoot, packageName) {
+    try {
+        const source = readExisting(path.join(gameRoot, 'node_modules', packageName, 'package.json'));
+        return source === undefined
+            ? undefined
+            : parseJsonObject(source, `${packageName}/package.json`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The installed package's version, for a message. */
+function installedPackageVersion(gameRoot, packageName) {
+    const version = readInstalledManifest(gameRoot, packageName)?.version;
+    return typeof version === 'string' ? version : 'unknown';
+}

package/dist/devvit-sdk-check.d.ts

@@ -0,0 +1,14 @@
+export interface DevvitSdkVersion {
+  readonly name: string;
+  readonly declared: string;
+  readonly installed: string;
+  readonly latest: string;
+  readonly source?: 'adapter';
+}
+export interface CheckDevvitSdkOptions {
+  /** Test seam. Production looks up the npm `latest` dist-tag. */
+  readonly lookupLatest?: (name: string) => Promise<string>;
+}
+export declare function assertLatestDevvitSdk(entries: readonly DevvitSdkVersion[]): void;
+/** Read-only pre-upload gate. Never install a new SDK between verified build and upload. */
+export declare function checkDevvitSdk(project: string, options?: CheckDevvitSdkOptions): Promise<readonly DevvitSdkVersion[]>;

package/dist/devvit-sdk-check.js

@@ -0,0 +1,112 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+const execFile = promisify(execFileCallback);
+const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
+function isFirstPartyDevvitPackage(name) {
+    return name === 'devvit' || name.startsWith('@devvit/');
+}
+function devvitPackageNames(dependencies) {
+    return Object.keys(dependencies).filter(isFirstPartyDevvitPackage);
+}
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid package metadata.');
+    }
+    return value;
+}
+async function npmLatestStable(name, cwd) {
+    const { stdout } = await execFile(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['view', `${name}@latest`, 'version', '--json', '--registry=https://registry.npmjs.org'], {
+        cwd,
+        encoding: 'utf8',
+        timeout: 20_000,
+        maxBuffer: 16_384,
+        shell: process.platform === 'win32',
+    });
+    return requireStableVersion(name, JSON.parse(stdout));
+}
+function requireStableVersion(name, latest) {
+    if (typeof latest !== 'string' || !stable.test(latest)) {
+        throw new Error('Registry did not return a stable Devvit version: ' + name);
+    }
+    return latest;
+}
+export function assertLatestDevvitSdk(entries) {
+    if (!entries.some((e) => e.name === 'devvit' || e.name === '@devvit/cli') || !entries.some((e) => e.name === '@devvit/web' || e.name === '@devvit/public-api')) {
+        throw new Error('Devvit upload needs both an installed CLI and SDK in this project.');
+    }
+    for (const entry of entries) {
+        if (!stable.test(entry.latest) || (entry.source !== 'adapter' && entry.declared !== entry.latest) || entry.installed !== entry.latest) {
+            throw new Error(`${entry.name}: declared=${entry.declared}, installed=${entry.installed}, latest=${entry.latest}. Update exact SDK/CLI pins and lockfile, rebuild and test, then retry upload.`);
+        }
+    }
+}
+/** Read-only pre-upload gate. Never install a new SDK between verified build and upload. */
+export async function checkDevvitSdk(project, options = {}) {
+    const manifestPath = path.resolve(project, 'package.json');
+    const manifest = record(JSON.parse(await readFile(manifestPath, 'utf8')));
+    const dependencies = {
+        ...(manifest.dependencies === undefined ? {} : record(manifest.dependencies)),
+        ...(manifest.devDependencies === undefined ? {} : record(manifest.devDependencies)),
+    };
+    async function installedPackage(from, name) {
+        let directory = from;
+        for (;;) {
+            const file = path.join(directory, 'node_modules', name, 'package.json');
+            try {
+                const metadata = record(JSON.parse(await readFile(file, 'utf8')));
+                if (metadata.name !== name || typeof metadata.version !== 'string') {
+                    throw new Error('Invalid installed package: ' + name);
+                }
+                return { metadata, directory: path.dirname(await realpath(file)) };
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+                    throw error;
+                }
+            }
+            const parent = path.dirname(directory);
+            if (parent === directory) {
+                throw new Error('Cannot resolve installed Devvit package: ' + name);
+            }
+            directory = parent;
+        }
+    }
+    const targetDirectory = path.dirname(manifestPath);
+    const subjects = devvitPackageNames(dependencies).map((name) => ({
+        name,
+        declared: dependencies[name],
+        directory: targetDirectory,
+        transitive: false,
+    }));
+    if (Object.hasOwn(dependencies, '@mpgd/adapter-devvit')) {
+        const adapter = await installedPackage(targetDirectory, '@mpgd/adapter-devvit');
+        const adapterDependencies = record(adapter.metadata.dependencies);
+        for (const name of devvitPackageNames(adapterDependencies)) {
+            subjects.push({
+                name,
+                declared: adapterDependencies[name],
+                directory: adapter.directory,
+                transitive: true,
+            });
+        }
+    }
+    const entries = await Promise.all(subjects.map(async ({ name, declared, directory, transitive }) => {
+        if (typeof declared !== 'string') {
+            throw new Error('Invalid Devvit dependency: ' + name);
+        }
+        const resolved = await installedPackage(directory, name);
+        const installed = resolved.metadata.version;
+        if (typeof installed !== 'string') {
+            throw new Error('Missing installed Devvit version: ' + name);
+        }
+        const latest = options.lookupLatest
+            ? requireStableVersion(name, await options.lookupLatest(name))
+            : await npmLatestStable(name, path.dirname(manifestPath));
+        // A consumer may use a reviewed exact override until the adapter release catches up.
+        return { name, declared, installed, latest, ...(transitive ? { source: 'adapter' } : {}) };
+    }));
+    assertLatestDevvitSdk(entries);
+    return entries;
+}

package/dist/index.js

@@ -27,6 +27,7 @@ import { runMicrosoftStorePackageGeneration } from './microsoft-store-package-ge
 import { defaultMpgdKitPath, initializeMicrosoftStoreStarter, listMicrosoftStoreInitializerTemplateFiles, prepareBaseGameTemplateFile, resolveMicrosoftStoreAdapterDependencyVersion, } from './microsoft-store-starter.js';
 import { applyNotificationsStarter, notificationsProviderId, readGameCreateProviders, } from './notifications-starter.js';
 import { applyKitUpgrade, planKitUpgrade } from './kit-upgrade.js';
+import { checkDevvitSdk } from './devvit-sdk-check.js';
 import { applyToolingMigration, planToolingMigration } from './tooling-migration.js';
 import { runMicrosoftStoreSubmissionPreflight } from './microsoft-store-submission.js';
 import { defaultOfflinePlaytestArtifactDir, defaultOfflinePlaytestMaximumBytes, defaultOfflinePlaytestOutputDir, runOfflinePlaytestPackaging, } from './offline-playtest.js';
@@ -2525,6 +2526,18 @@ const kitCommand = defineI18n({
         ko: '현재 mpgd-kit 체크아웃을 점검합니다.',
     }),
     subCommands: {
+        'devvit-check': defineI18n({
+            name: 'devvit-check',
+            description: 'Require exact installed latest stable Devvit SDK and CLI before upload.',
+            resource: commandResource({ en: 'Check latest stable Devvit SDK before upload.', ko: '업로드 전 Devvit 최신 안정 SDK를 확인합니다.' }),
+            args: { project: { type: 'string', default: '.', description: 'Devvit target directory.' } },
+            run: async (ctx) => {
+                const entries = await checkDevvitSdk(readOptionalString(ctx.values.project) ?? '.');
+                for (const entry of entries) {
+                    console.info(entry.name + '@' + entry.installed + ' (latest stable)');
+                }
+            },
+        }),
         upgrade: defineI18n({
             name: 'upgrade',
             description: 'Plan or apply the latest published Kit package versions for a game.',

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "ed8837541cc3c5737c21638a596ba2dc121112da",
+  "kitGitSha": "dc28031ea2d85c442c084cd118cdd3fa2cecadba",
   "kitDirty": false,
-  "packageVersion": "0.54.1"
+  "packageVersion": "0.56.0"
 }

package/dist/native-build-target.js

@@ -6990,9 +6990,6 @@ var releaseBackoffMs = 60 * secondMs;
 // node_modules/.cache/mpgd-native-build/adapters/devvit/src/server/redis-notification-store.js
 var defaultPurgeLimit = Number.POSITIVE_INFINITY;
 
-// node_modules/.cache/mpgd-native-build/adapters/devvit/src/notifications-contract.js
-var devvitHostCodeCharacters = "[A-Za-z0-9_.:-]{1,128}";
-
 // node_modules/.cache/mpgd-native-build/adapters/devvit/src/server/notifications-delivery.js
 var devvitNotificationProviderCodes = Object.freeze({
   deviceRecipient: "DEVVIT_DEVICE_RECIPIENT",
@@ -7023,13 +7020,17 @@ var devvitNotificationSchedulerTasks = Object.freeze({
   })
 });
 
+// node_modules/.cache/mpgd-native-build/packages/bridge/src/notifications.js
+var hostCodeCharacters = "[A-Za-z0-9_.:-]{1,128}";
+var hostCodeValue = new RegExp(`^${hostCodeCharacters}$`, "u");
+var hostCodeSuffix = new RegExp(`\\(host code (${hostCodeCharacters})\\)$`, "u");
+
 // node_modules/.cache/mpgd-native-build/adapters/devvit/src/server/notifications-bridge.js
 var devvitNotificationHostCodes = Object.freeze({
   optInRefused: "DEVVIT_OPT_IN_REFUSED",
   optOutRefused: "DEVVIT_OPT_OUT_REFUSED",
   pluginFailed: "DEVVIT_NOTIFICATIONS_PLUGIN_FAILED"
 });
-var hostCodeValue = new RegExp(`^${devvitHostCodeCharacters}$`, "u");
 
 // node_modules/.cache/mpgd-native-build/packages/cli/src/target-name.js
 var deploymentTargetNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -14899,8 +14900,16 @@ var notificationsCapacitorSupportFiles = Object.freeze([
   "docs/NOTIFICATIONS.md"
 ]);
 var notificationsCapacitorTemplateSupportFiles = Object.freeze([
-  "src/platform/serverSession.ts"
+  "src/platform/serverSession.ts",
+  "src/platform/developmentServerSession.ts"
 ]);
+var notificationsCapacitorTemplateSupportImporters = Object.freeze({
+  "src/platform/developmentServerSession.ts": {
+    importer: "src/platform/serverSession.ts",
+    requires: { packageName: "@mpgd/game-services", exportName: "createDevelopmentServerSession" },
+    warning: "src/platform/serverSession.ts predates development notification sessions (VITE_MPGD_DEV_NOTIFICATION_SESSION); to try notifications locally, copy serverSession.ts and developmentServerSession.ts from the starter template."
+  }
+});
 
 // node_modules/.cache/mpgd-native-build/packages/cli/src/native-shell-identity.js
 function assertAndroidSettingsAppProject(source) {

package/dist/notifications-starter.d.ts

@@ -61,9 +61,36 @@ export declare const notificationsCapacitorSupportFiles: readonly string[];
 /**
 * Files of the base game template the notifications modules import, which a
 * game created by an earlier CLI release may not have: written from the
-* template when missing, kept when the game has one.
+* template when missing, kept when the game has one. A file listed in
+* `notificationsCapacitorTemplateSupportImporters` is written only together
+* with its importer.
 */
-export declare const notificationsCapacitorTemplateSupportFiles: readonly string[];
+export declare const notificationsCapacitorTemplateSupportFiles: readonly ["src/platform/serverSession.ts", "src/platform/developmentServerSession.ts"];
+/**
+* Template support files only one other support file imports: the importer,
+* and the warning for a game that keeps its own importer without importing
+* the file (an earlier `serverSession.ts`). Such a game would never import the
+* file, and its `@mpgd/game-services` may predate what the file imports, so
+* the file is not written for it. An importer that imports it gets it back.
+*/
+export declare const notificationsCapacitorTemplateSupportImporters: Readonly<Partial<Record<(typeof notificationsCapacitorTemplateSupportFiles)[number], {
+  readonly importer: (typeof notificationsCapacitorTemplateSupportFiles)[number];
+  readonly warning: string;
+  /**
+  * A kit export the file imports, which the game's installed package
+  * must have before the file is written (an older package lacks it).
+  */
+  readonly requires?: {
+    readonly packageName: string;
+    readonly exportName: string;
+  };
+}>>>;
+/**
+* Whether `source` names the module `./<name>` (with or without `.js` or
+* `.ts`) as a string outside comments: any static, side-effect, or dynamic
+* import or re-export of it. A commented-out import does not count.
+*/
+export declare function sourceReferencesRelativeModule(source: string, name: string): boolean;
 /** Whether a Capacitor gateway already registers a notifications provider. */
 export declare function capacitorGatewayRegistersNotifications(source: string): boolean;
 /**

package/dist/notifications-starter.js

@@ -479,11 +479,47 @@ export const notificationsCapacitorSupportFiles = Object.freeze([
 /**
  * Files of the base game template the notifications modules import, which a
  * game created by an earlier CLI release may not have: written from the
- * template when missing, kept when the game has one.
+ * template when missing, kept when the game has one. A file listed in
+ * `notificationsCapacitorTemplateSupportImporters` is written only together
+ * with its importer.
  */
 export const notificationsCapacitorTemplateSupportFiles = Object.freeze([
     'src/platform/serverSession.ts',
+    'src/platform/developmentServerSession.ts',
 ]);
+/**
+ * Template support files only one other support file imports: the importer,
+ * and the warning for a game that keeps its own importer without importing
+ * the file (an earlier `serverSession.ts`). Such a game would never import the
+ * file, and its `@mpgd/game-services` may predate what the file imports, so
+ * the file is not written for it. An importer that imports it gets it back.
+ */
+export const notificationsCapacitorTemplateSupportImporters = Object.freeze({
+    'src/platform/developmentServerSession.ts': {
+        importer: 'src/platform/serverSession.ts',
+        requires: { packageName: '@mpgd/game-services', exportName: 'createDevelopmentServerSession' },
+        warning: 'src/platform/serverSession.ts predates development notification sessions '
+            + '(VITE_MPGD_DEV_NOTIFICATION_SESSION); to try notifications locally, copy serverSession.ts and '
+            + 'developmentServerSession.ts from the starter template.',
+    },
+});
+/**
+ * Whether `source` names the module `./<name>` (with or without `.js` or
+ * `.ts`) as a string outside comments: any static, side-effect, or dynamic
+ * import or re-export of it. A commented-out import does not count.
+ */
+export function sourceReferencesRelativeModule(source, name) {
+    const specifiers = new Set([`./${name}`, `./${name}.js`, `./${name}.ts`]);
+    let found = false;
+    // One pass over strings and comments, as in capacitorGatewayRegistersNotifications.
+    source.replace(/'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`|\/\/[^\n]*|\/\*[\s\S]*?\*\//gu, (token) => {
+        if (!token.startsWith('/') && specifiers.has(token.slice(1, -1))) {
+            found = true;
+        }
+        return token;
+    });
+    return found;
+}
 /** Whether a Capacitor gateway already registers a notifications provider. */
 export function capacitorGatewayRegistersNotifications(source) {
     // One pass over strings and comments: neither registers anything, and a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.54.1",
+  "version": "0.56.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -70,10 +70,10 @@
     "parse5": "7.3.0",
     "postcss": "8.5.28",
     "postcss-value-parser": "4.2.0",
-    "@mpgd/catalog": "0.10.6",
-    "@mpgd/platform": "0.27.1",
+    "@mpgd/catalog": "0.10.7",
     "@mpgd/phaser-assets": "0.9.1",
-    "@mpgd/target-config": "0.23.6"
+    "@mpgd/target-config": "0.23.7",
+    "@mpgd/platform": "0.27.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -81,18 +81,18 @@
     "@types/yauzl": "3.4.0",
     "ttsc": "0.32.1",
     "typescript": "7.0.2",
-    "@mpgd/adapter-browser": "0.11.6",
-    "@mpgd/adapter-capacitor": "0.12.2",
-    "@mpgd/adapter-ait": "0.20.2",
-    "@mpgd/adapter-verse8": "0.7.6",
-    "@mpgd/bridge": "0.14.3",
-    "@mpgd/analytics": "0.4.15",
-    "@mpgd/adapter-devvit": "0.13.4",
-    "@mpgd/capacitor-play-billing": "0.3.6",
-    "@mpgd/capacitor-storekit": "0.3.6",
-    "@mpgd/game-runtime": "0.7.6",
-    "@mpgd/game-services": "0.27.1",
-    "@mpgd/i18n": "0.6.20",
+    "@mpgd/adapter-ait": "0.20.4",
+    "@mpgd/adapter-browser": "0.11.7",
+    "@mpgd/adapter-capacitor": "0.12.4",
+    "@mpgd/adapter-devvit": "0.13.6",
+    "@mpgd/adapter-verse8": "0.7.8",
+    "@mpgd/analytics": "0.5.0",
+    "@mpgd/bridge": "0.15.0",
+    "@mpgd/capacitor-play-billing": "0.3.8",
+    "@mpgd/capacitor-storekit": "0.3.8",
+    "@mpgd/game-runtime": "0.8.1",
+    "@mpgd/i18n": "0.6.21",
+    "@mpgd/game-services": "0.28.0",
     "@mpgd/lite-shell": "0.1.0"
   },
   "main": "./dist/index.js",

package/templates/lite-overlay/agent/acceptance.md

@@ -11,6 +11,7 @@ Preserve the generated JSON and Markdown in `artifacts/acceptance` or the target
 - Verify renderer teardown removes its own listeners and never updates a replacement view from an old promise.
 - Purchases and rewarded-ad callbacks never grant locally; verify authoritative ledger grants and durable reconciliation before release.
 - Keep unknown native outcomes and late recovery observers; closing one lease must not release another owner's presentation or audio.
+- Verify the game sets its real server session with `setStarterServerSession` and does not rely on the development fallback (read only with `--providers notifications`): `VITE_MPGD_DEV_NOTIFICATION_SESSION` is local-only (its `mpgd-dev` header needs the Vite dev server, so a `pnpm build` never signs in with it), and deployed acceptance uses the identity service's sessions.
 
 ## Reddit Devvit
 

package/templates/lite-overlay/agent/brief.md

@@ -11,6 +11,7 @@ Read `AGENTS.md`, the agent manifest, and the `use-mpgd-kit` router before editi
 - Keep recovery above renderer lifetimes; reconcile existing operations on startup and resume without opening SDK UI.
 - Rewarded v2 needs an application-owned durable encrypted journal. An in-memory store is not recovery evidence.
 - Reserve safe-area geometry once and preserve feed scrolling and browser touch gestures.
+- Set the server session with `setStarterServerSession` in `src/main.ts` before `bootstrap()` (a guest backend through `createGuestServerSession`). In a game created with `--providers notifications`, `VITE_MPGD_DEV_NOTIFICATION_SESSION` on the Vite dev server in the `development` mode is a local-only development session for notifications (`src/platform/developmentServerSession.ts`); it never reaches a build, commerce, or a deployed Worker.
 
 Run `pnpm dev`, `pnpm check`, `pnpm build`, and `pnpm accept`.
 Devvit inline and expanded entries both use the lite renderer. Keep optional engines behind explicit dynamic import boundaries and verify the inline budget.

package/templates/notifications-overlay/common/docs/NOTIFICATIONS.md

@@ -74,10 +74,22 @@ game has both:
   identity service answers to the Worker's `authenticateNotificationSession`
   for this session's header, the same across token refreshes (see the kit's
   `docs/CLOUDFLARE_WORKER_DEPLOY.md`, "Sessions"). Do not pass a per-token
-  or rotating id: a `GuestSessionCoordinator` view's `sessionId` may rotate
-  on refresh, so it is not that id.
+  or rotating id. With a guest-session backend, pass
+  `createGuestServerSession(coordinator)` from `@mpgd/game-services`: it
+  answers the coordinator's `sessionFamilyId` (not a view's `sessionId`,
+  which may rotate on refresh), and refreshes the access token as needed
+  (an expired one before the request, one about to expire in the
+  background).
 
-Without either, it returns `undefined` and the settings screen asks only
+  ```ts
+  // src/main.ts, before bootstrap()
+  const guest = createGuestSessionCoordinator({ backend, credentials, installationId });
+  setStarterServerSession(createGuestServerSession(guest));
+  void guest.start();
+  ```
+
+Without either (on the Vite dev server, a development session counts as a
+session; see "Try it locally"), it returns `undefined` and the settings screen asks only
 for the OS or host permission (and withdraws a Devvit opt-in the game
 rendered). With them, the runtime registers the device for the signed-in
 player, keeps its registration state in the platform storage, and
@@ -102,3 +114,63 @@ Night consent adds to 광고성 정보 수신동의: the screen offers it only w
 advertising consent is granted, and turning advertising consent off also
 withdraws a granted night consent in the same call (two records, two result
 notices).
+
+## Try it locally
+
+You can see the settings switches record consent before you have an
+identity service, against the kit's game-services Worker on your machine:
+
+1. Fill in `advertisingSender` in `notifications/deployment.json` (the
+   Worker refuses a placeholder). In mpgd-kit, give the Worker this game's
+   catalog and deployment and the development sessions flag in
+   `apps/game-services-worker/.dev.vars` (local variables, never
+   committed), then run it with the memory store, the default in its
+   `wrangler.toml`:
+
+   ```sh
+   cd <mpgd-kit>
+   node - <game>/notifications/topics.json <game>/notifications/deployment.json \
+     > apps/game-services-worker/.dev.vars <<'EOF'
+   const fs = require('node:fs');
+   // One line of JSON in single quotes, with any ' written as \u0027.
+   const value = (file) =>
+     `'${JSON.stringify(JSON.parse(fs.readFileSync(file, 'utf8'))).replaceAll("'", '\\u0027')}'`;
+   console.log('MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS=true');
+   console.log(`MPGD_NOTIFICATIONS_CATALOG=${value(process.argv[2])}`);
+   console.log(`MPGD_NOTIFICATIONS_DEPLOYMENT=${value(process.argv[3])}`);
+   EOF
+   pnpm --dir apps/game-services-worker dev --host 127.0.0.1 --port 8787
+   ```
+
+   The Worker logs once that sessions are not authenticated. To send real
+   pushes to a phone or an emulator, follow mpgd-kit's live test runbook
+   (`docs/NOTIFICATIONS_LIVE_TEST.md`) instead of adding the key here: it
+   runs this same Worker, with `pnpm notifications:live env` writing the
+   variables and the Firebase service-account key to a file outside the
+   checkout that you link as `.dev.vars`.
+2. Start this game's dev server with the Worker URL and a development
+   session, `<playerId>` or `<playerId>.<installationId>` (letters, digits,
+   `_`, `-`):
+
+   ```sh
+   VITE_MPGD_GAME_SERVICES_URL=http://127.0.0.1:8787 \
+   VITE_MPGD_DEV_NOTIFICATION_SESSION=player-1 \
+   pnpm dev
+   ```
+
+`src/platform/developmentServerSession.ts` then signs the game in as that
+player with `Authorization: Bearer mpgd-dev.<playerId>.<sessionId>.<installationId>`,
+which the Worker accepts only with the flag. Anyone can write that header,
+so it authenticates nothing: the session exists only on the Vite dev server
+(`import.meta.env.DEV`) in the `development` mode, and the Worker refuses
+the flag with its D1 store, ignores it once `GAME_SERVICES_NOTIFICATIONS_AUTH`
+is bound, and takes development sessions only on a local host (`localhost`,
+`127.0.0.1`, `[::1]`, `*.localhost`, or `10.0.2.2`, which the Android
+emulator uses for your machine). That check reads the request's host, so
+it protects a deployed Worker, not your network: keep the local Worker on
+loopback, its default. Calling `setStarterServerSession`, even with `undefined`, turns it
+off; the first call after the game used it warns, since the notifications
+backend keeps the session it first read.
+The development session is for the notifications backend only: the
+commerce client keeps the session the game set with `setStarterServerSession`
+(or none), so its requests never carry a development header.

package/templates/notifications-overlay/common/src/platform/notificationBackend.ts

@@ -90,7 +90,8 @@ export function createStarterWorkerNotificationBackend(
   if (session === undefined) {
     input.log(
       '[notifications] VITE_MPGD_GAME_SERVICES_URL is set but no server session is: call setStarterServerSession '
-        + '(src/platform/serverSession.ts) before the game starts. The settings screen shows no switch until then.',
+        + '(src/platform/serverSession.ts) before the game starts, or on the dev server set '
+        + 'VITE_MPGD_DEV_NOTIFICATION_SESSION (docs/NOTIFICATIONS.md). The settings screen shows no switch until then.',
     );
     return undefined;
   }

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

@@ -64,6 +64,16 @@ 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.
 
+## Server session
+
+Verify the game sets its real server-backed session with `setStarterServerSession`
+before `bootstrap()` (a guest backend through `createGuestServerSession`) and does
+not rely on the development fallback, which only a game created with
+`--providers notifications` reads. `VITE_MPGD_DEV_NOTIFICATION_SESSION` is local-only evidence:
+a `pnpm build` never signs in with it (its `mpgd-dev` header needs the Vite dev
+server), and acceptance against a deployed Worker uses the identity service's
+sessions.
+
 ## Shared native presentation
 
 - Purchase, rewarded, and interstitial requests use the same game-owned scope.

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

@@ -49,6 +49,18 @@ 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.
 
+## Server session
+
+Set the game's server-backed session with `setStarterServerSession`
+(`src/platform/serverSession.ts`) before `bootstrap()`; with a guest backend use
+`createGuestServerSession(coordinator)`, whose `sessionId` is the stable
+session-family id. For local notifications work only (a game created with
+`--providers notifications`), `VITE_MPGD_DEV_NOTIFICATION_SESSION` on the Vite
+dev server in the `development` mode signs in with an unauthenticated
+development session (`src/platform/developmentServerSession.ts`)
+against a local Worker run with `MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS`;
+it never reaches a build, the commerce client, or a deployed Worker.
+
 ## ONE play server-owned monetization
 
 Specify issued placement/product IDs, the authenticated reward and checkout intent routes, durable SSV/intent/ledger stores, an encrypted client operation journal, and reconciliation plus atomic cancellation fencing. Keep monetization disabled until these ports are wired. Purchase/ad callbacks are evidence; backend grants precede consume/acknowledge. Separate confirmed checkout closure from financial completion. Plan real-app acceptance with ONEconsole credentials and hosting headers.

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

@@ -6,29 +6,30 @@
   "scripts": {
     "prepare:icon": "pnpm --dir ../.. icons:generate:devvit",
     "prepare:icon:production": "pnpm --dir ../.. icons:generate:devvit:production",
-    "init": "pnpm run prepare:icon:production && devvit upload --config devvit.json",
-    "init:copy-paste": "pnpm run prepare:icon:production && devvit upload --copy-paste --config devvit.json",
-    "dev": "pnpm run prepare:icon && devvit playtest --config devvit.json",
+    "init": "pnpm run check:sdk && pnpm run prepare:icon:production && devvit upload --config devvit.json",
+    "init:copy-paste": "pnpm run check:sdk && pnpm run prepare:icon:production && devvit upload --copy-paste --config devvit.json",
+    "dev": "pnpm run check:sdk && pnpm run prepare:icon && devvit playtest --config devvit.json",
     "build": "pnpm --dir ../.. build:devvit",
     "whoami": "devvit whoami",
-    "upload": "pnpm run prepare:icon:production && devvit upload --config devvit.json",
-    "publish": "pnpm run prepare:icon:production && devvit publish --config devvit.json",
+    "upload": "pnpm run check:sdk && pnpm run prepare:icon:production && devvit upload --config devvit.json",
+    "publish": "pnpm run check:sdk && pnpm run prepare:icon:production && devvit publish --config devvit.json",
     "check": "ttsc --noEmit -p tsconfig.json",
     "lint": "ttsc --noEmit -p tsconfig.json",
     "format": "ttsc format",
-    "fix": "ttsc fix"
+    "fix": "ttsc fix",
+    "check:sdk": "pnpm exec mpgd kit devvit-check --project ."
   },
   "dependencies": {
-    "@devvit/web": "0.14.1",
+    "@devvit/web": "0.15.0",
     "@mpgd/adapter-devvit": "__MPGD_DEPENDENCY_VERSION_ADAPTER_DEVVIT__",
     "@mpgd/bridge": "__MPGD_DEPENDENCY_VERSION_BRIDGE__",
     "@mpgd/catalog": "__MPGD_DEPENDENCY_VERSION_CATALOG__"
   },
   "devDependencies": {
-    "@devvit/start": "0.14.1",
+    "@devvit/start": "0.15.0",
     "@ttsc/unplugin": "0.32.1",
     "@types/node": "^24.0.0",
-    "devvit": "0.14.1",
+    "devvit": "0.15.0",
     "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vite": "7.3.6"

package/templates/phaser-game/src/env.d.ts

@@ -19,4 +19,9 @@ interface ImportMetaEnv {
   readonly VITE_MPGD_GAME_SERVICES_URL?: string;
   readonly VITE_MPGD_GAME_SERVICES_TARGET?: string;
   readonly VITE_MPGD_GAME_SERVICES_TRANSPORT?: string;
+  /**
+   * Local development only: `<playerId>` or `<playerId>.<installationId>`
+   * for an unauthenticated notifications session (see `serverSession.ts`).
+   */
+  readonly VITE_MPGD_DEV_NOTIFICATION_SESSION?: string;
 }

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

@@ -0,0 +1,104 @@
+import { createDevelopmentServerSession, type DevelopmentServerSession } from '@mpgd/game-services';
+
+/**
+ * Local development only: an unauthenticated session for a game-services
+ * Worker run with `MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS = "true"`
+ * (see docs/NOTIFICATIONS.md, "Try it locally"). On only when the Vite dev
+ * server runs (`dev`, `import.meta.env.DEV`), the mode is `development`, and
+ * `VITE_MPGD_DEV_NOTIFICATION_SESSION` is `<playerId>` or
+ * `<playerId>.<installationId>` (each 1 to 64 letters, digits, `_`, or `-`;
+ * the installation defaults to `dev-installation`). The session id is
+ * `dev-<installationId>`. Anyone can write such a header, so the Worker
+ * refuses the flag with its D1 store. Otherwise `undefined`; an invalid
+ * value logs why.
+ */
+export function resolveStarterDevelopmentServerSession(env: {
+  readonly dev: boolean;
+  readonly mode: string;
+  readonly value: string | undefined;
+}): DevelopmentServerSession | undefined {
+  const value = env.value?.trim();
+  // Only the development mode: a staging or release build that runs with
+  // NODE_ENV=development has `dev` set too.
+  if (!env.dev || env.mode !== 'development' || value === undefined || value === '') {
+    return undefined;
+  }
+  const [playerId = '', installationId = 'dev-installation', ...rest] = value.split('.');
+  try {
+    if (rest.length > 0) {
+      throw new Error('Expected <playerId> or <playerId>.<installationId>.');
+    }
+    const session = createDevelopmentServerSession({ mode: env.mode, playerId, installationId });
+    console.warn(
+      `[game-services] VITE_MPGD_DEV_NOTIFICATION_SESSION: signed in as ${playerId} with an `
+        + 'unauthenticated development session. Local development only.',
+    );
+    return session;
+  } catch (error) {
+    console.error('[game-services] VITE_MPGD_DEV_NOTIFICATION_SESSION is ignored.', error);
+    return undefined;
+  }
+}
+
+/**
+ * What `serverSession.ts` hands out, kept apart from `import.meta.env` so it
+ * can be tested: the game's own session once it called `set` (even with
+ * `undefined`), else the development session, read once. `once` marks the
+ * reader that keeps what it reads, the commerce client, which only ever
+ * gets the game's own session: the development session is for the
+ * notifications Worker, and a commerce backend with ingress authentication
+ * would refuse its header. A `set` that changes the session after a reader
+ * kept the old one warns: after the commerce client read it, or after the
+ * development session was handed out (a notifications backend keeps it).
+ */
+export function createStarterServerSessionSlot<Session extends object>(input: {
+  /** The development session; called at most once. */
+  readonly development: () => Session | undefined;
+  readonly warn: (message: string) => void;
+}): {
+  resolve(options?: { readonly once?: boolean }): Session | undefined;
+  set(session: Session | undefined): void;
+} {
+  let session: Session | undefined;
+  let setByGame = false;
+  let readOnce = false;
+  let development: Session | null | undefined;
+  let developmentHandedOut = false;
+  return {
+    resolve(options = {}) {
+      if (options.once === true) {
+        readOnce = true;
+      }
+      // The commerce client never gets the development session.
+      if (setByGame || options.once === true) {
+        return session;
+      }
+      if (development === undefined) {
+        development = input.development() ?? null;
+      }
+      if (development === null) {
+        return undefined;
+      }
+      developmentHandedOut = true;
+      return development;
+    },
+    set(next) {
+      if (developmentHandedOut && !setByGame) {
+        // Even `undefined`: a notifications backend that kept the development session keeps sending its header.
+        input.warn(
+          '[game-services] setStarterServerSession ran after the development session '
+            + '(VITE_MPGD_DEV_NOTIFICATION_SESSION) was in use; a notifications backend created '
+            + 'already keeps it. Unset the variable, or call setStarterServerSession before bootstrap().',
+        );
+      }
+      if (readOnce && next !== undefined && next !== session) {
+        input.warn(
+          '[game-services] setStarterServerSession ran after the commerce client was created; '
+            + "it does not send this session's header. Call it before bootstrap().",
+        );
+      }
+      session = next;
+      setByGame = true;
+    },
+  };
+}

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

@@ -1,19 +1,37 @@
 import type { GameServicesHeaderResolver } from '@mpgd/game-services';
 
+import {
+  createStarterServerSessionSlot,
+  resolveStarterDevelopmentServerSession,
+} from './developmentServerSession';
+
 /**
  * The game's server-backed session: who is signed in to the game backend,
  * and the `Authorization` header for that session. The starter has none, so
  * `resolveStarterServerSession` returns `undefined`. Set yours with
- * `setStarterServerSession`, over your own session holder and identity
- * service. The commerce client then sends its header. In a game created with
- * `--providers notifications`, the notifications runtime uses the same
- * session and header for the game-services Worker's notification routes.
+ * `setStarterServerSession`. The commerce client then sends its header. In
+ * a game created with `--providers notifications`, the notifications
+ * runtime uses the same session and header for the game-services Worker's
+ * notification routes.
+ *
+ * With a guest-session backend, `createGuestServerSession` from
+ * `@mpgd/game-services` reads a `GuestSessionCoordinator` as this session:
+ *
+ * ```ts
+ * const guest = createGuestSessionCoordinator({ backend, credentials, installationId });
+ * setStarterServerSession(createGuestServerSession(guest));
+ * void guest.start();
+ * ```
+ *
+ * `sessionId` must be the stable session-family id: the same across token
+ * refreshes, and the session your identity service answers to the Worker's
+ * `authenticateNotificationSession` for this session's header. Do not pass
+ * a per-token or rotating id: `createGuestServerSession` answers the
+ * coordinator's `sessionFamilyId`, never a view's `sessionId`, which may
+ * rotate on refresh. With another session holder, pass its family id.
  *
- * `sessionId` must be the stable session-family id: the `sessionId` your
- * identity service answers to the Worker's `authenticateNotificationSession`
- * for this session's header, the same across token refreshes. Do not pass a
- * per-token or rotating id: a `GuestSessionCoordinator` view's `sessionId`
- * may rotate on refresh, so it is not that id.
+ * For local development without an identity service, see
+ * `developmentServerSession.ts`.
  */
 export interface StarterServerSession {
   /**
@@ -29,22 +47,31 @@ export interface StarterServerSession {
   readonly getHeaders: GameServicesHeaderResolver;
 }
 
-let serverSession: StarterServerSession | undefined;
-/** Whether the commerce client read the session already: it reads it once. */
-let readOnce = false;
+/** The game's session, or the development one (see `developmentServerSession.ts`). */
+const slot = createStarterServerSessionSlot<StarterServerSession>({
+  // `import.meta.env.DEV` is false in a normal `vite build`, which drops this branch.
+  development: () =>
+    import.meta.env.DEV
+      ? resolveStarterDevelopmentServerSession({
+          dev: import.meta.env.DEV,
+          mode: import.meta.env.MODE,
+          value: import.meta.env.VITE_MPGD_DEV_NOTIFICATION_SESSION,
+        })
+      : undefined,
+  warn: (message) => console.warn(message),
+});
 
 /**
  * The game's server-backed session; `undefined` until the game sets one with
- * `setStarterServerSession`. `once` marks a reader that keeps what it reads
- * (the commerce client), so a later change warns.
+ * `setStarterServerSession`, unless a development session is on (see
+ * `developmentServerSession.ts`). `once` marks the reader that keeps what
+ * it reads, the commerce client, so a later change warns; it gets only the
+ * game's own session, never the development one.
  */
 export function resolveStarterServerSession(
   options: { readonly once?: boolean } = {},
 ): StarterServerSession | undefined {
-  if (options.once === true) {
-    readOnce = true;
-  }
-  return serverSession;
+  return slot.resolve(options);
 }
 
 /**
@@ -53,14 +80,10 @@ export function resolveStarterServerSession(
  * notification settings and opens read it until a backend exists. Its
  * `current()` may answer `undefined` until the player signs in. A session
  * set after the commerce client was created does not reach that client,
- * which this warns about.
+ * which this warns about. Any call, `undefined` included, turns the
+ * development session off; the first call after the development session
+ * was handed out warns, `undefined` included.
  */
 export function setStarterServerSession(session: StarterServerSession | undefined): void {
-  if (readOnce && session !== undefined && session !== serverSession) {
-    console.warn(
-      '[game-services] setStarterServerSession ran after the commerce client was created; '
-        + "it does not send this session's header. Call it before bootstrap().",
-    );
-  }
-  serverSession = session;
+  slot.set(session);
 }