@mpgd/cli 0.52.0 → 0.53.0

package/dist/notifications-starter.js

@@ -0,0 +1,513 @@
+/**
+ * The notifications starter (`mpgd game create --providers notifications`):
+ * the files `templates/notifications-overlay` adds to a generated game, and the
+ * anchored edits it makes to the base template, so a game without
+ * notifications ships none of it (notifications v2 RFC, PR C1).
+ *
+ * Every edit names an anchor that must occur exactly once in the base file,
+ * so a template change that moves an anchor fails the CLI's tests instead of
+ * generating a half-wired game.
+ */
+/** The provider id that selects the notifications starter. */
+export const notificationsProviderId = 'notifications';
+/** The push plugin the notifications starter adds (FCM on Android and iOS). */
+export const notificationsMessagingPlugin = '@capacitor-firebase/messaging';
+/**
+ * The npm packages a game with notifications declares. The two Capacitor
+ * plugins are the optional peers `@mpgd/adapter-capacitor/notifications`
+ * loads, at the versions the adapter is tested with; `firebase` is the
+ * package the messaging plugin's web fallback imports, which the bundler
+ * must resolve even though a native shell never loads it.
+ */
+export const notificationsGameDependencies = Object.freeze({
+    [notificationsMessagingPlugin]: '8.5.2',
+    '@capacitor/local-notifications': '8.3.1',
+    firebase: '12.19.0',
+});
+/**
+ * The `firebase` range the starter's `@capacitor-firebase/messaging` version
+ * declares as its peer (its web fallback imports the SDK). A game that keeps
+ * its own `firebase` must be in it before the starter adds the plugin; the
+ * starter test pins it to the plugin's published metadata.
+ */
+export const notificationsMessagingFirebaseRange = '^12.6.0';
+/** The plugins `mpgd target init capacitor --providers notifications` installs into the shell. */
+export const notificationsShellPlugins = Object.freeze([
+    notificationsMessagingPlugin,
+    '@capacitor/local-notifications',
+]);
+/** Never installed next to the messaging plugin: on iOS both claim Capacitor's one push handler. */
+export const conflictingPushPlugin = '@capacitor/push-notifications';
+const gatewayImport = {
+    anchor: "import type { RuntimeConfig } from '../runtimeDetector';\n",
+    replacement: [
+        "import { createStarterCapacitorNotifications } from '../capacitorNotifications';",
+        "import type { RuntimeConfig } from '../runtimeDetector';",
+        '',
+    ].join('\n'),
+};
+const gatewayProviders = (platform) => ({
+    anchor: '  const providers = createStoreProviders(runtime, () => gateway);\n',
+    replacement: [
+        '  const providers = [',
+        '    ...createStoreProviders(runtime, () => gateway),',
+        '    // Notifications v2 (FCM and local reminders); `notifications/topics.json`',
+        '    // maps the topics, and the shell needs the two plugins',
+        '    // (`mpgd target init capacitor --providers notifications`).',
+        `    ...(await createStarterCapacitorNotifications('${platform}', runtime.configTarget)),`,
+        '  ];',
+        '',
+    ].join('\n'),
+});
+/** Edits to base template files, by path, for both templates unless noted. */
+const commonEdits = {
+    'src/platform/buildGateways/capacitorAndroid.ts': [gatewayImport, gatewayProviders('android')],
+    'src/platform/buildGateways/capacitorIos.ts': [gatewayImport, gatewayProviders('ios')],
+    'src/platform/buildGateways/reddit.ts': [
+        {
+            anchor: "import { createDevvitWebPaymentsClient } from '@mpgd/adapter-devvit/web';\n",
+            replacement: [
+                'import {',
+                '  createDevvitWebLoginPrompt,',
+                '  createDevvitWebPaymentsClient,',
+                "} from '@mpgd/adapter-devvit/web';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: "import type { RuntimeConfig } from '../runtimeDetector';\n",
+            replacement: [
+                "import { starterNotificationTopics } from '../notifications';",
+                "import type { RuntimeConfig } from '../runtimeDetector';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: '    ...(commerce === undefined ? {} : { commerce }),\n',
+            replacement: [
+                '    ...(commerce === undefined ? {} : { commerce }),',
+                '    // Notifications v2: the game-rendered opt-in the server bridge serves',
+                '    // (a gated beta: `integrations.notifications` stays approval-required',
+                '    // until Reddit approves the app), and Reddit login for a logged-out',
+                '    // player, who must log in before opting in.',
+                '    ...notificationOptions(runtime),',
+                '    loginPrompt: createDevvitWebLoginPrompt(),',
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: 'function createCommerceOptions(): DevvitGatewayCommerceOptions | undefined {\n',
+            replacement: [
+                'function notificationOptions(',
+                '  runtime: RuntimeConfig,',
+                "): Pick<Parameters<typeof createDevvitPlatformGateway>[0], 'notifications'> {",
+                '  const topics = starterNotificationTopics(runtime.configTarget).map((topic) => topic.id);',
+                '  return topics.length === 0 ? {} : { notifications: { topics } };',
+                '}',
+                '',
+                'function createCommerceOptions(): DevvitGatewayCommerceOptions | undefined {',
+                '',
+            ].join('\n'),
+        },
+    ],
+    'apps/target-devvit/src/server/index.ts': [
+        {
+            anchor: "import { context, createServer, getServerPort, payments, reddit, redis } from '@devvit/web/server';\n",
+            replacement: [
+                'import {',
+                '  context,',
+                '  createServer,',
+                '  getServerPort,',
+                '  notifications,',
+                '  payments,',
+                '  reddit,',
+                '  redis,',
+                "} from '@devvit/web/server';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: [
+                'import {',
+                '  createDevvitCommerceBridgeProducts,',
+                '  createDevvitCommerceV2BridgeHandler,',
+                "} from '@mpgd/adapter-devvit/server';",
+                '',
+            ].join('\n'),
+            replacement: [
+                'import {',
+                '  createDevvitCommerceBridgeProducts,',
+                '  createDevvitCommerceV2BridgeHandler,',
+                '  createDevvitNotificationService,',
+                '  createDevvitNotificationsV2BridgeHandler,',
+                "} from '@mpgd/adapter-devvit/server';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: "import type { ProductCatalog } from '@mpgd/catalog';\n",
+            replacement: [
+                "import { resolveNotificationTopicsForTarget, type NotificationTopicCatalog, type ProductCatalog } from '@mpgd/catalog';",
+                "import { assertNotificationDeployment } from '@mpgd/platform/notifications';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: "import devvitManifest from '../../devvit.json';\n",
+            replacement: [
+                "import notificationDeploymentJson from '../../../../notifications/deployment.json';",
+                "import notificationTopicsJson from '../../../../notifications/topics.json';",
+                "import devvitManifest from '../../devvit.json';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: [
+                'const handleBridgeRequest = createDevvitBridgeHandler({',
+                '  redis,',
+                '  currentPlayerId,',
+                '  currentDisplayName,',
+                '  storageKeyNamespace: gameName,',
+                '  ...(commerce === undefined ? {} : { commerce }),',
+                '});',
+                '',
+            ].join('\n'),
+            replacement: [
+                '/**',
+                ' * Notifications v2 (`notifications/topics.json`, mapped for the `reddit`',
+                ' * target): the game-rendered opt-in for the logged-in requester, and the',
+                ' * service that records consent and sends server reminders over the Devvit',
+                ' * notifications plugin. Devvit notifications are a gated beta: the game',
+                ' * shows them only once `integrations.notifications` is `available`.',
+                ' */',
+                'const notificationTopicCatalog = notificationTopicsJson as NotificationTopicCatalog;',
+                'const redditNotificationTopics = readRedditNotificationTopics();',
+                "const notificationService: Parameters<typeof handleNotificationTask>[0]['notifications'] =",
+                '  redditNotificationTopics.length === 0 ? undefined : createNotificationService();',
+                '// The opt-in is served only with the service that sends; a refused catalog turns both off.',
+                'const notificationsBridge = notificationService === undefined',
+                '  ? undefined',
+                '  : createDevvitNotificationsV2BridgeHandler({',
+                '      notifications,',
+                '      currentUserId: currentPlayerId,',
+                '      topics: redditNotificationTopics,',
+                '    });',
+                'const handleBridgeRequest = createDevvitBridgeHandler({',
+                '  redis,',
+                '  currentPlayerId,',
+                '  currentDisplayName,',
+                '  storageKeyNamespace: gameName,',
+                '  ...(commerce === undefined ? {} : { commerce }),',
+                '  ...(notificationsBridge === undefined ? {} : { notifications: notificationsBridge }),',
+                '});',
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: [
+                '/**',
+                ' * The notifications v2 service (`createDevvitNotificationService` from',
+                ' * `@mpgd/adapter-devvit/server`). None until the game declares a topic',
+                ' * catalog, so the scheduler tasks below do no work.',
+                ' */',
+                "const notificationService: Parameters<typeof handleNotificationTask>[0]['notifications'] = undefined;",
+                '',
+            ].join('\n'),
+            replacement: [
+                '/** The topic ids the catalog maps for Reddit; none when the catalog cannot be read. */',
+                'function readRedditNotificationTopics(): readonly string[] {',
+                '  try {',
+                "    return resolveNotificationTopicsForTarget(notificationTopicCatalog, 'reddit').map((topic) => topic.id);",
+                '  } catch (error) {',
+                '    console.error(`devvit notifications disabled: ${errorMessage(error)}`);',
+                '    return [];',
+                '  }',
+                '}',
+                '',
+                '/**',
+                ' * The notifications v2 service over Redis and the Devvit plugin; the',
+                ' * scheduler tasks below run its reminders and purges. A catalog or',
+                ' * deployment the service refuses turns notifications off, never the game',
+                ' * server.',
+                ' */',
+                "function createNotificationService(): Parameters<typeof handleNotificationTask>[0]['notifications'] {",
+                '  try {',
+                '    return createDevvitNotificationService({',
+                '      redis,',
+                '      notifications,',
+                '      catalog: notificationTopicCatalog,',
+                '      deployment: assertNotificationDeployment(notificationDeploymentJson),',
+                '    }).service;',
+                '  } catch (error) {',
+                '    console.error(`devvit notifications disabled: ${errorMessage(error)}`);',
+                '    return undefined;',
+                '  }',
+                '}',
+                '',
+            ].join('\n'),
+        },
+    ],
+};
+const phaserEdits = {
+    'src/runtime/createGame.ts': [
+        {
+            anchor: "import { LobbyScene } from '../scenes/LobbyScene';\n",
+            replacement: [
+                "import { LobbyScene } from '../scenes/LobbyScene';",
+                'import {',
+                '  NotificationSettingsScene,',
+                '  routeNotificationSettingsOpens,',
+                "} from '../scenes/NotificationSettingsScene';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: '    scene: [BootScene, LobbyScene, PlayScene],\n',
+            replacement: '    scene: [BootScene, LobbyScene, PlayScene, NotificationSettingsScene],\n',
+        },
+        {
+            anchor: '        ownGameAudio(game, input.context);\n',
+            replacement: [
+                '        ownGameAudio(game, input.context);',
+                '        // The advertising opt-out action and consent notices open the settings screen.',
+                '        routeNotificationSettingsOpens(game, input.context);',
+                '',
+            ].join('\n'),
+        },
+    ],
+    'src/scenes/LobbyScene.ts': [
+        {
+            anchor: "import { starterContextKey, type StarterContext } from '../runtime/gameContext';\n",
+            replacement: [
+                "import { starterContextKey, type StarterContext } from '../runtime/gameContext';",
+                "import { notificationSettingsSceneKey } from './NotificationSettingsScene';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: "    this.input.once('pointerdown', () => this.scene.start('PlayScene'));\n",
+            replacement: [
+                '    // The settings button shows only where this target has notifications.',
+                '    const notificationsButton = context.platform.notificationsV2 === undefined',
+                '      ? undefined',
+                '      : this.add',
+                "          .text(940, 16, locale === 'ko' ? '알림 설정' : 'Notifications', {",
+                "            color: '#5eead4',",
+                "            fontFamily: 'Arial, sans-serif',",
+                "            fontSize: '22px',",
+                '          })',
+                '          .setOrigin(1, 0)',
+                '          .setPadding(16, 12, 16, 12)',
+                '          .setInteractive({ useHandCursor: true });',
+                "    notificationsButton?.on('pointerup', () => this.scene.start(notificationSettingsSceneKey));",
+                '    // A tap anywhere else starts the game; the scene drops this listener on shutdown.',
+                "    this.input.on('pointerdown', (_pointer: Phaser.Input.Pointer, over: Phaser.GameObjects.GameObject[]) => {",
+                '      if (notificationsButton === undefined || !over.includes(notificationsButton)) {',
+                "        this.scene.start('PlayScene');",
+                '      }',
+                '    });',
+                '',
+            ].join('\n'),
+        },
+    ],
+};
+const liteEdits = {
+    'src/runtime/createGame.ts': [
+        {
+            anchor: "import { createTapGame } from '../lite/tapGame';\n",
+            replacement: [
+                "import { mountNotificationSettingsPanel } from '../lite/notificationSettingsPanel';",
+                "import { createTapGame } from '../lite/tapGame';",
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: "  const shell = createTapGame({ mount, title: '__GAME_TITLE__' });\n",
+            replacement: [
+                "  const shell = createTapGame({ mount, title: '__GAME_TITLE__' });",
+                '  const disposeNotificationSettings = mountNotificationSettingsPanel(mount, input.context);',
+                '',
+            ].join('\n'),
+        },
+        {
+            anchor: '    audio.dispose();\n',
+            replacement: ['    audio.dispose();', '    disposeNotificationSettings();', ''].join('\n'),
+        },
+    ],
+};
+const readmeSection = [
+    '',
+    '## Notifications',
+    '',
+    'This game was created with `--providers notifications`. Its topics live in',
+    '`notifications/topics.json` and the backend settings (`advertisingRules`,',
+    'the advertising sender) in `notifications/deployment.json`; run',
+    '`pnpm validate:notifications` after every change and before every release.',
+    'Replace the sender contact placeholder in `notifications/deployment.json`',
+    'before any advertising is sent. The notification settings screen asks for the',
+    'OS or host permission and records reminder, advertising (광고성 정보',
+    '수신동의), and night consent through the notifications runtime. See',
+    '`docs/NOTIFICATIONS.md` and, for Android and iOS, the mpgd-kit Firebase setup',
+    'guide; `mpgd target init capacitor --providers notifications` installs the two',
+    'Capacitor plugins into a game-owned shell.',
+    '',
+].join('\n');
+function applyEdits(path, content, edits) {
+    let next = content;
+    for (const { anchor, replacement } of edits) {
+        const first = next.indexOf(anchor);
+        if (first === -1 || next.indexOf(anchor, first + anchor.length) !== -1) {
+            throw new Error(`The notifications starter could not find exactly one anchor in ${path}; the template changed: ${JSON.stringify(anchor.split('\n')[0])}`);
+        }
+        next = `${next.slice(0, first)}${replacement}${next.slice(first + anchor.length)}`;
+    }
+    return next;
+}
+function editPackageJson(content) {
+    const value = JSON.parse(content);
+    value.scripts = {
+        ...value.scripts,
+        'validate:notifications': 'ttsx --project tsconfig.tools.json tools/validate-notifications.ts',
+    };
+    value.dependencies = Object.fromEntries(Object.entries({ ...value.dependencies, ...notificationsGameDependencies })
+        .sort(([left], [right]) => left.localeCompare(right)));
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/** The Devvit server reads the deployment settings through `@mpgd/platform/notifications`. */
+function editDevvitPackageJson(content) {
+    const value = JSON.parse(content);
+    value.dependencies = Object.fromEntries(Object.entries({
+        ...value.dependencies,
+        '@mpgd/platform': '__MPGD_DEPENDENCY_VERSION_PLATFORM__',
+    }).sort(([left], [right]) => left.localeCompare(right)));
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function editTargets(content) {
+    const value = JSON.parse(content);
+    // Android, iOS, and Apps in Toss expose notifications once their provider
+    // is ready; the provider still reports its own readiness (no plugin, no
+    // mapped topic), which the target config follows. Reddit keeps the
+    // default `approval-required` until Reddit approves the app, and exposes
+    // the login prompt the opt-in needs.
+    for (const name of ['android', 'ios', 'ait']) {
+        const target = value.targets[name];
+        if (target !== undefined) {
+            target.integrations = { ...target.integrations, notifications: 'available' };
+        }
+    }
+    const reddit = value.targets.reddit;
+    if (reddit !== undefined) {
+        reddit.integrations = { ...reddit.integrations, identityUpgrade: 'available' };
+    }
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/**
+ * Applies the notifications starter to a generated game's template files:
+ * adds the overlay's files (`common` and the template's own) and edits the
+ * base files at their anchors. Throws when an anchor is missing, so a
+ * template change cannot silently drop the wiring.
+ */
+export function applyNotificationsStarter(baseFiles, overlay) {
+    const edits = {
+        ...commonEdits,
+        ...(overlay.template === 'phaser' ? phaserEdits : liteEdits),
+    };
+    const pending = new Set(Object.keys(edits));
+    const edited = baseFiles.map((file) => {
+        const fileEdits = edits[file.relativePath];
+        let content = file.content;
+        if (fileEdits !== undefined) {
+            pending.delete(file.relativePath);
+            content = applyEdits(file.relativePath, content, fileEdits);
+        }
+        else if (file.relativePath === 'package.json') {
+            content = editPackageJson(content);
+        }
+        else if (file.relativePath === 'apps/target-devvit/package.json') {
+            content = editDevvitPackageJson(content);
+        }
+        else if (file.relativePath === 'mpgd.targets.json') {
+            content = editTargets(content);
+        }
+        else if (file.relativePath === 'README.md') {
+            content = `${content.trimEnd()}\n${readmeSection}`;
+        }
+        return content === file.content ? file : { ...file, content };
+    });
+    if (pending.size > 0) {
+        throw new Error(`The notifications starter is missing template files: ${[...pending].sort().join(', ')}`);
+    }
+    const added = [
+        ...overlay.common,
+        ...(overlay.template === 'phaser' ? overlay.phaser : overlay.lite),
+    ];
+    const existing = new Set(edited.map((file) => file.relativePath));
+    for (const file of added) {
+        // Also refuses a path the overlay's parts both carry, so neither wins silently.
+        if (existing.has(file.relativePath)) {
+            throw new Error(`The notifications starter would overwrite ${file.relativePath}.`);
+        }
+        existing.add(file.relativePath);
+    }
+    return [...edited, ...added];
+}
+/** The Capacitor gateways the notifications starter wires, by native platform. */
+export const notificationsCapacitorGateways = Object.freeze({
+    android: 'src/platform/buildGateways/capacitorAndroid.ts',
+    ios: 'src/platform/buildGateways/capacitorIos.ts',
+});
+/** The starter modules a wired Capacitor gateway imports, directly or through one another. */
+export const notificationsCapacitorGatewayModules = Object.freeze([
+    'src/platform/capacitorNotifications.ts',
+    'src/platform/notifications.ts',
+    'src/platform/notificationSettings.ts',
+    'src/platform/notificationOpens.ts',
+]);
+/**
+ * The files `mpgd target init capacitor --providers notifications` writes
+ * with a wired gateway when the game has none: the modules it imports, the
+ * catalog files they read, the validator, and the game's notifications doc.
+ */
+export const notificationsCapacitorSupportFiles = Object.freeze([
+    ...notificationsCapacitorGatewayModules,
+    'notifications/topics.json',
+    'notifications/deployment.json',
+    'tools/validate-notifications.ts',
+    'docs/NOTIFICATIONS.md',
+]);
+/** Whether a Capacitor gateway already registers a notifications provider. */
+export function capacitorGatewayRegistersNotifications(source) {
+    // One pass over strings and comments: neither registers anything, and a
+    // string that holds `//` or `/*` does not start a comment. Regex literals
+    // are not tokenized, so a quote or `/*` inside one can hide a call or
+    // expose a commented one; such a gateway gets a warning or keeps its
+    // wiring as it is, and is never rewritten wrongly.
+    const code = source.replace(/'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`|\/\/[^\n]*|\/\*[\s\S]*?\*\//gu, (token) => (token.startsWith('/') ? ' ' : '""'));
+    return /\b(?:createStarterCapacitorNotifications|createCapacitorNotificationServiceProvider)\s*\(/u
+        .test(code);
+}
+/**
+ * The template's Capacitor gateway with the notifications provider wired in:
+ * the same anchored edits `--providers notifications` makes at generation.
+ */
+export function wireCapacitorGatewayNotifications(relativePath, source) {
+    const edits = commonEdits[relativePath];
+    if (edits === undefined || !Object.values(notificationsCapacitorGateways).includes(relativePath)) {
+        throw new Error(`${relativePath} is not a Capacitor gateway the notifications starter wires.`);
+    }
+    return applyEdits(relativePath, source, edits);
+}
+/** Reads `--providers` for `mpgd game create`: only `notifications` is a game-level provider today. */
+export function readGameCreateProviders(value) {
+    if (value === undefined) {
+        return [];
+    }
+    const ids = [...new Set(value.split(',').map((id) => id.trim()).filter((id) => id.length > 0))];
+    for (const id of ids) {
+        if (id !== notificationsProviderId) {
+            throw new Error(`Unsupported --providers ${id} for mpgd game create; expected: ${notificationsProviderId}. `
+                + 'Store plugins (play-billing, storekit) are installed with "mpgd target init capacitor --providers ...".');
+        }
+    }
+    return ids;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.52.0",
+  "version": "0.53.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.3",
-    "@mpgd/platform": "0.25.0",
-    "@mpgd/phaser-assets": "0.9.1",
-    "@mpgd/target-config": "0.23.3"
+    "@mpgd/catalog": "0.10.4",
+    "@mpgd/platform": "0.26.0",
+    "@mpgd/target-config": "0.23.4",
+    "@mpgd/phaser-assets": "0.9.1"
   },
   "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-ait": "0.19.0",
-    "@mpgd/adapter-browser": "0.11.3",
-    "@mpgd/adapter-capacitor": "0.11.1",
-    "@mpgd/adapter-devvit": "0.13.1",
-    "@mpgd/adapter-verse8": "0.7.3",
-    "@mpgd/analytics": "0.4.12",
-    "@mpgd/capacitor-play-billing": "0.3.3",
-    "@mpgd/bridge": "0.14.0",
-    "@mpgd/capacitor-storekit": "0.3.3",
-    "@mpgd/game-services": "0.25.1",
-    "@mpgd/game-runtime": "0.7.3",
-    "@mpgd/i18n": "0.6.17",
+    "@mpgd/adapter-ait": "0.20.0",
+    "@mpgd/adapter-browser": "0.11.4",
+    "@mpgd/adapter-capacitor": "0.12.0",
+    "@mpgd/adapter-devvit": "0.13.2",
+    "@mpgd/adapter-verse8": "0.7.4",
+    "@mpgd/analytics": "0.4.13",
+    "@mpgd/bridge": "0.14.1",
+    "@mpgd/capacitor-storekit": "0.3.4",
+    "@mpgd/game-services": "0.26.0",
+    "@mpgd/capacitor-play-billing": "0.3.4",
+    "@mpgd/i18n": "0.6.18",
+    "@mpgd/game-runtime": "0.7.4",
     "@mpgd/lite-shell": "0.1.0"
   },
   "main": "./dist/index.js",

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

@@ -0,0 +1,75 @@
+# Notifications in __GAME_TITLE__
+
+This game was created with `mpgd game create --providers notifications`. The
+mpgd-kit notifications guide (`docs/NOTIFICATIONS.md` in mpgd-kit) explains
+the whole flow; this page lists what the starter put in this game and what is
+left for you.
+
+## Files
+
+| File | What it is |
+| --- | --- |
+| `notifications/topics.json` | The topic catalog: each topic's purpose, channels, routes, copy, and per-target mapping. The one source for every target and the backend. |
+| `notifications/deployment.json` | The backend settings: `advertisingRules` (`kr`), the advertising sender, and the zone. |
+| `src/platform/notifications.ts` | Reads the catalog for a target, and the place to return your notifications runtime. |
+| `src/platform/capacitorNotifications.ts` | The Android and iOS provider (FCM and local reminders), registered by the Capacitor gateways. |
+| `src/platform/notificationSettings.ts` | The settings screen's logic: permission, reminders, advertising and night consent, notices. |
+| `src/platform/notificationOpens.ts` | The game's one listener for notification opens: the settings route, and an `other` route for your topics. |
+| `src/scenes/NotificationSettingsScene.ts` or `src/lite/notificationSettingsPanel.ts` | The settings screen the game renders. |
+| `tools/validate-notifications.ts` | `pnpm validate:notifications`. |
+
+## Before you release
+
+1. Replace `REPLACE-WITH-SENDER-PHONE-OR-ADDRESS` in
+   `notifications/deployment.json` with the sender's phone number or
+   address. Every advertising push carries it under the Korean rules, and
+   `pnpm validate:notifications` fails until you do. The game backend
+   refuses the placeholder as well: a Worker given this file as is does not
+   start its notifications.
+2. Keep the sender in `notices.copy` (`[__GAME_TITLE__]` in every variant) the
+   same as `advertisingSender.name` in `notifications/deployment.json`: a
+   consent notice must name the sender.
+3. Run `pnpm validate:notifications` after every catalog change.
+4. Decide each topic's purpose with your own legal review. The starter's
+   `daily-ready` and `streak-at-risk` are `requested`: off until the player
+   turns them on, and their copy states only the player's own progress. If
+   you add a reward, a benefit, or a promotion to them, or send them to
+   players who did not turn them on, declare them `advertising` instead.
+5. Android and iOS: set up Firebase (see the mpgd-kit Firebase guide,
+   `docs/FIREBASE_NOTIFICATIONS.md`), then run
+   `mpgd target init capacitor --providers notifications` to install the two
+   plugins into the game-owned shell. Never install
+   `@capacitor/push-notifications` next to them.
+6. Advertising on Android: the sample `events` topic is mapped to iOS only.
+   An Android FCM notification cannot carry the opt-out action that the
+   Korean rules require on every advertising push (a settings path in the
+   text does not replace it), and the kit does not render Android
+   advertising natively yet. Do not add an `android` mapping to an
+   advertising topic until it does.
+7. Apps in Toss: register each functional-message template in the console and
+   add its code to the topic's `targets.ait` mapping
+   (`{ "templateSetCode": "...", "agreement": "required" }`). Apps in Toss
+   cannot deliver advertising topics.
+8. Reddit: apply for Devvit notifications; keep `integrations.notifications`
+   at `approval-required` until Reddit approves the app and its copy.
+
+## The notifications runtime
+
+Consent records (reminders, 광고성 정보 수신동의, night consent), endpoint
+registration, server reminders, and consent notices go through the game
+backend. The kit does not ship that runtime's backend client yet, so
+`createStarterNotificationBackend` in `src/platform/notifications.ts` returns
+`undefined` and the settings screen asks only for the OS or host permission
+(and withdraws a Devvit opt-in the game rendered). Once your backend serves
+the notification routes, return its `NotificationRuntime` there with
+`listConsent`, which reads the signed-in player's consent records (the
+game-services Worker's `GET /consent`). The settings screen shows each
+switch from the latest record, read every time it opens and after every
+change, so a choice made on another device shows. A tap reads the records
+again and writes only what changes. It keeps nothing on the device, and
+shows no switch when the records cannot be read.
+
+Night consent adds to 광고성 정보 수신동의: the screen offers it only while
+advertising consent is granted, and turning advertising consent off also
+withdraws a granted night consent in the same call (two records, two result
+notices).

package/templates/notifications-overlay/common/notifications/deployment.json

@@ -0,0 +1,8 @@
+{
+  "advertisingRules": "kr",
+  "advertisingSender": {
+    "name": "__GAME_TITLE__",
+    "contact": "REPLACE-WITH-SENDER-PHONE-OR-ADDRESS"
+  },
+  "timeZone": "Asia/Seoul"
+}