@mpgd/cli 0.53.0 → 0.54.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, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, wireCapacitorGatewayNotifications, } from './notifications-starter.js';
+import { capacitorGatewayRegistersNotifications, conflictingPushPlugin, notificationsCapacitorGatewayModules, notificationsCapacitorGateways, notificationsCapacitorSupportFiles, notificationsCapacitorTemplateSupportFiles, notificationsGameDependencies, notificationsMessagingFirebaseRange, notificationsMessagingPlugin, notificationsProviderId, notificationsShellPlugins, 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';
@@ -2793,6 +2793,14 @@ function planNotificationsProvider(input) {
                 files.push({ path: file, content: starterFile(overlayRoot, file) });
             }
         }
+        // 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) });
+                }
+            }
+        }
         warnings.push('The notification settings screen is not added to an existing game; render one from '
             + 'src/platform/notificationSettings.ts (see docs/NOTIFICATIONS.md) so players can turn '
             + 'reminders and advertising consent on and off.');

package/dist/deploy-planning.js

@@ -356,8 +356,8 @@ function assertGameOwnedNativePaths(gameRoot, target, config) {
             throw new Error(`${target} ${field} still points to a Kit checkout; initialize a game-owned shell.`);
         }
         const expanded = value
-            .replaceAll('${MPGD_GAME_ROOT}', root)
-            .replaceAll('${MPGD_GAME_APP_ROOT}', root);
+            .replaceAll('${MPGD_GAME_ROOT}', () => root)
+            .replaceAll('${MPGD_GAME_APP_ROOT}', () => root);
         const candidate = resolve(root, expanded);
         let ancestor = candidate;
         while (!existsSync(ancestor)) {

package/dist/index.js

@@ -2976,7 +2976,14 @@ function createGameApp(input) {
             relativePath: file.relativePath,
             content: file.content,
         });
-        return prepared === undefined ? [] : [{ ...file, content: renderTemplate(prepared, context) }];
+        return prepared === undefined
+            ? []
+            : [
+                {
+                    ...file,
+                    content: renderTemplate(prepared, context, file.relativePath),
+                },
+            ];
     });
     if (input.dryRun) {
         console.info(`Would create ${path.relative(process.cwd(), appDir) || appDir}:`);
@@ -3187,8 +3194,10 @@ function assertValidGameTitle(title) {
     if (title.trim().length === 0) {
         throw new Error('Game title cannot be empty.');
     }
-    if (/[\u0000-\u001f<>"'\\]/u.test(title)) {
-        throw new Error('Game title cannot contain control characters, quotes, backslashes, or angle brackets.');
+    // Quotes, backslashes, and `$` are allowed: JSON files and JS string literals
+    // escape them. `<` would break the generated HTML title.
+    if (/[\u0000-\u001f<>]/u.test(title)) {
+        throw new Error('Game title cannot contain control characters or angle brackets.');
     }
 }
 function collectTemplateFiles(templateDir) {
@@ -3210,28 +3219,79 @@ function walkTemplateDir(templateDir, relativeDir, files) {
         });
     }
 }
-function renderTemplate(content, context) {
-    let rendered = content
-        .replaceAll("from '@mpgd/cli/devvit'", `from ${context.devvitOutputPluginImport}`)
-        .replaceAll('__GAME_NAME__', context.gameName)
-        .replaceAll('__DEVVIT_APP_NAME__', context.devvitAppName)
-        .replaceAll('__GAME_TITLE_TS_LITERAL__', context.gameTitleTsLiteral)
-        .replaceAll('__GAME_TITLE__', context.gameTitle)
-        .replaceAll('__LEGAL_LAST_UPDATED__', context.legalLastUpdated)
-        .replaceAll('__PACKAGE_NAME__', context.packageName)
-        .replaceAll('__MPGD_DEPENDENCY_VERSION__', context.defaultDependencyVersion)
-        .replaceAll('__TSCONFIG_EXTENDS_LINE__', context.tsconfigExtendsLine)
-        .replaceAll('__TSCONFIG_ROOT_DIR__', context.tsconfigRootDir)
-        .replaceAll('__TSCONFIG_WORKSPACE_INCLUDES__', context.tsconfigWorkspaceIncludes)
-        .replaceAll('__TSCONFIG_WORKSPACE_EXCLUDES__', context.tsconfigWorkspaceExcludes)
-        .replaceAll('__WORKSPACE_I18N_BUILD_PREFIX__', context.workspaceI18nBuildPrefix)
-        .replaceAll('__DEFAULT_KIT_PATH__', context.defaultKitPath)
-        .replaceAll('__RECOMMENDED_MATRIX_TARGETS__', context.recommendedMatrixTargets)
-        .replaceAll('__PNPM_WORKSPACE_KIT_PACKAGES__', context.pnpmWorkspaceKitPackages)
-        .replaceAll('__PASCAL_NAME__', context.pascalName)
-        .replaceAll('__CAMEL_NAME__', context.camelName);
+/**
+ * String replacements treat `$&`, `$'`, `` $` ``, and `$$` as patterns.
+ * A function replacer inserts `value` literally.
+ */
+function replaceLiteral(content, placeholder, value) {
+    return content.replaceAll(placeholder, () => value);
+}
+/** Interior of a JSON string, without the surrounding quotes. */
+function jsonStringContents(value) {
+    return JSON.stringify(value).slice(1, -1);
+}
+/**
+ * Placeholders substituted inside an existing JSON string. Structural
+ * fragments (`__TSCONFIG_EXTENDS_LINE__` and the workspace include/exclude
+ * lists) stay raw so their quotes remain JSON syntax.
+ */
+function jsonEscapedPlaceholder(placeholder) {
+    return placeholder === '__GAME_TITLE__'
+        || placeholder === '__GAME_NAME__'
+        || placeholder === '__PACKAGE_NAME__'
+        || placeholder === '__DEVVIT_APP_NAME__'
+        || placeholder === '__DEFAULT_KIT_PATH__'
+        || placeholder === '__WORKSPACE_I18N_BUILD_PREFIX__'
+        || placeholder === '__TSCONFIG_ROOT_DIR__'
+        || placeholder === '__LEGAL_LAST_UPDATED__'
+        || placeholder === '__MPGD_DEPENDENCY_VERSION__'
+        || placeholder.startsWith('__MPGD_DEPENDENCY_VERSION_');
+}
+/** Interior of a single-quoted JS string. Backslash first, then quote. */
+function singleQuotedContents(value) {
+    return value.replaceAll('\\', () => '\\\\').replaceAll("'", () => "\\'");
+}
+function renderTemplate(content, context, relativePath) {
+    // `.webmanifest` is JSON. Hosted PWA deploy and Microsoft Store submission parse it.
+    const jsonFile = relativePath.endsWith('.json') || relativePath.endsWith('.webmanifest');
+    const typescriptFile = relativePath.endsWith('.ts');
+    const insert = (placeholder, value) => {
+        if (jsonFile && jsonEscapedPlaceholder(placeholder)) {
+            return jsonStringContents(value);
+        }
+        // Template titles sit in single quotes (`title: '__GAME_TITLE__'`).
+        if (typescriptFile && placeholder === '__GAME_TITLE__') {
+            return singleQuotedContents(value);
+        }
+        return value;
+    };
+    const pairs = [
+        [`from '@mpgd/cli/devvit'`, `from ${context.devvitOutputPluginImport}`],
+        ['__GAME_NAME__', context.gameName],
+        ['__DEVVIT_APP_NAME__', context.devvitAppName],
+        // Longer than `__GAME_TITLE__`, so a title is not written into the literal name.
+        ['__GAME_TITLE_TS_LITERAL__', context.gameTitleTsLiteral],
+        ['__GAME_TITLE__', context.gameTitle],
+        ['__LEGAL_LAST_UPDATED__', context.legalLastUpdated],
+        ['__PACKAGE_NAME__', context.packageName],
+        ['__MPGD_DEPENDENCY_VERSION__', context.defaultDependencyVersion],
+        ['__TSCONFIG_EXTENDS_LINE__', context.tsconfigExtendsLine],
+        ['__TSCONFIG_ROOT_DIR__', context.tsconfigRootDir],
+        ['__TSCONFIG_WORKSPACE_INCLUDES__', context.tsconfigWorkspaceIncludes],
+        ['__TSCONFIG_WORKSPACE_EXCLUDES__', context.tsconfigWorkspaceExcludes],
+        ['__WORKSPACE_I18N_BUILD_PREFIX__', context.workspaceI18nBuildPrefix],
+        ['__DEFAULT_KIT_PATH__', context.defaultKitPath],
+        ['__RECOMMENDED_MATRIX_TARGETS__', context.recommendedMatrixTargets],
+        ['__PNPM_WORKSPACE_KIT_PACKAGES__', context.pnpmWorkspaceKitPackages],
+        ['__PASCAL_NAME__', context.pascalName],
+        ['__CAMEL_NAME__', context.camelName],
+    ];
+    let rendered = content;
+    for (const [placeholder, value] of pairs) {
+        rendered = replaceLiteral(rendered, placeholder, insert(placeholder, value));
+    }
     for (const replacement of context.mpgdDependencyVersionReplacements) {
-        rendered = rendered.replaceAll(replacement.placeholder, replacement.version);
+        rendered = replaceLiteral(rendered, replacement.placeholder, insert(replacement.placeholder, replacement.version));
     }
     return rendered;
 }
@@ -3336,8 +3396,8 @@ function resolveStandaloneNativeBuild(targetsFile, requestedTarget, values) {
             return undefined;
         }
         const candidate = path.resolve(gameRoot, configuredPath
-            .replaceAll('${MPGD_GAME_ROOT}', gameRoot)
-            .replaceAll('${MPGD_GAME_APP_ROOT}', gameRoot));
+            .replaceAll('${MPGD_GAME_ROOT}', () => gameRoot)
+            .replaceAll('${MPGD_GAME_APP_ROOT}', () => gameRoot));
         let existingAncestor = candidate;
         while (!existsSync(existingAncestor)) {
             const parent = path.dirname(existingAncestor);
@@ -3495,10 +3555,7 @@ function formatError(error) {
 }
 function replaceTargetTokens(value, context) {
     if (typeof value === 'string') {
-        return value
-            .replaceAll('${MPGD_KIT_PATH}', context.kitPath)
-            .replaceAll('${MPGD_GAME_ROOT}', context.gameRoot)
-            .replaceAll('${MPGD_GAME_APP_ROOT}', context.gameRoot);
+        return replaceLiteral(replaceLiteral(replaceLiteral(value, '${MPGD_KIT_PATH}', context.kitPath), '${MPGD_GAME_ROOT}', context.gameRoot), '${MPGD_GAME_APP_ROOT}', context.gameRoot);
     }
     if (Array.isArray(value)) {
         return value.map((entry) => replaceTargetTokens(entry, context));

package/dist/kit-upgrade.js

@@ -278,8 +278,8 @@ function discoverGameManifests(gameRoot, notes, blockers, targetsFileName) {
                 continue;
             }
             const resolvedLocation = location
-                .replaceAll('${MPGD_GAME_ROOT}', targetsDirectory)
-                .replaceAll('${MPGD_GAME_APP_ROOT}', targetsDirectory);
+                .replaceAll('${MPGD_GAME_ROOT}', () => targetsDirectory)
+                .replaceAll('${MPGD_GAME_APP_ROOT}', () => targetsDirectory);
             if (resolvedLocation.includes('$' + '{')) {
                 notes.push('Skipped target with unresolved path token: ' + location);
                 continue;

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "78bcaad6a3e53131be44f749c27b9377a2fd96dc",
+  "kitGitSha": "95ea69d3e9755256b27a3b0ea230812a632ed03b",
   "kitDirty": false,
-  "packageVersion": "0.53.0"
+  "packageVersion": "0.54.0"
 }

package/dist/native-build-target.js

@@ -6899,6 +6899,72 @@ var timestampPattern = new RegExp("^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2})
 var fcmAddressKinds = Object.freeze(["fcm-token"]);
 var fcmReservedDataKeys = Object.freeze(["topic", "route"]);
 var tokenRefreshMarginMs = 5 * 60 * 1e3;
+var sha256K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
 
 // node_modules/.cache/mpgd-native-build/packages/game-services/src/notifications/registry.js
 var notificationHistoryRetentionDays = 30;
@@ -14739,6 +14805,7 @@ var notificationsCapacitorGateways = Object.freeze({
 var notificationsCapacitorGatewayModules = Object.freeze([
   "src/platform/capacitorNotifications.ts",
   "src/platform/notifications.ts",
+  "src/platform/notificationBackend.ts",
   "src/platform/notificationSettings.ts",
   "src/platform/notificationOpens.ts"
 ]);
@@ -14749,6 +14816,9 @@ var notificationsCapacitorSupportFiles = Object.freeze([
   "tools/validate-notifications.ts",
   "docs/NOTIFICATIONS.md"
 ]);
+var notificationsCapacitorTemplateSupportFiles = Object.freeze([
+  "src/platform/serverSession.ts"
+]);
 
 // node_modules/.cache/mpgd-native-build/packages/cli/src/native-shell-identity.js
 function assertAndroidSettingsAppProject(source) {

package/dist/notifications-starter.d.ts

@@ -58,6 +58,12 @@ export declare const notificationsCapacitorGatewayModules: readonly string[];
 * catalog files they read, the validator, and the game's notifications doc.
 */
 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.
+*/
+export declare const notificationsCapacitorTemplateSupportFiles: readonly string[];
 /** Whether a Capacitor gateway already registers a notifications provider. */
 export declare function capacitorGatewayRegistersNotifications(source: string): boolean;
 /**

package/dist/notifications-starter.js

@@ -460,6 +460,7 @@ export const notificationsCapacitorGateways = Object.freeze({
 export const notificationsCapacitorGatewayModules = Object.freeze([
     'src/platform/capacitorNotifications.ts',
     'src/platform/notifications.ts',
+    'src/platform/notificationBackend.ts',
     'src/platform/notificationSettings.ts',
     'src/platform/notificationOpens.ts',
 ]);
@@ -475,6 +476,14 @@ export const notificationsCapacitorSupportFiles = Object.freeze([
     'tools/validate-notifications.ts',
     'docs/NOTIFICATIONS.md',
 ]);
+/**
+ * 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.
+ */
+export const notificationsCapacitorTemplateSupportFiles = Object.freeze([
+    'src/platform/serverSession.ts',
+]);
 /** 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/dist/offline-playtest.js

@@ -3125,7 +3125,7 @@ function assembleOfflineHtml(html, bundledEntry, entryAttributes) {
         || output.indexOf(offlineEntryPlaceholder) !== output.lastIndexOf(offlineEntryPlaceholder)) {
         throw new Error('Offline playtest could not preserve the module entry position.');
     }
-    output = output.replace(offlineEntryPlaceholder, inlineScript);
+    output = output.replace(offlineEntryPlaceholder, () => inlineScript);
     if (findActiveHtmlStartTag(output, 'body') !== undefined) {
         return `${output.trim()}\n`;
     }

package/dist/tooling-migration.js

@@ -399,7 +399,7 @@ function migrateKnownRunner(source, template) {
         if (defaults.length !== 1) {
             return undefined;
         }
-        const rendered = template.replace("'__DEFAULT_KIT_PATH__'", JSON.stringify(defaults[0]));
+        const rendered = template.replace("'__DEFAULT_KIT_PATH__'", () => JSON.stringify(defaults[0]));
         const canonical = (value) => JSON.stringify(value, (key, item) => ['start', 'end', 'raw'].includes(key) ? undefined : item);
         return canonical(ast) === canonical(parse(rendered, { ecmaVersion: 'latest', sourceType: 'module' }))
             ? rendered

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.53.0",
+  "version": "0.54.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.4",
-    "@mpgd/platform": "0.26.0",
-    "@mpgd/target-config": "0.23.4",
-    "@mpgd/phaser-assets": "0.9.1"
+    "@mpgd/catalog": "0.10.5",
+    "@mpgd/platform": "0.27.0",
+    "@mpgd/phaser-assets": "0.9.1",
+    "@mpgd/target-config": "0.23.5"
   },
   "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.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/adapter-ait": "0.20.1",
+    "@mpgd/adapter-browser": "0.11.5",
+    "@mpgd/adapter-devvit": "0.13.3",
+    "@mpgd/adapter-verse8": "0.7.5",
+    "@mpgd/bridge": "0.14.2",
+    "@mpgd/adapter-capacitor": "0.12.1",
+    "@mpgd/analytics": "0.4.14",
+    "@mpgd/capacitor-play-billing": "0.3.5",
+    "@mpgd/capacitor-storekit": "0.3.5",
+    "@mpgd/game-services": "0.27.0",
+    "@mpgd/i18n": "0.6.19",
+    "@mpgd/game-runtime": "0.7.5",
     "@mpgd/lite-shell": "0.1.0"
   },
   "main": "./dist/index.js",

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

@@ -57,13 +57,42 @@ left for you.
 
 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
+backend. `createStarterNotificationBackend` in
+`src/platform/notifications.ts` builds the notifications runtime
+(`@mpgd/platform/notifications-runtime`) over the game-services Worker's
+notification routes (`@mpgd/game-services/notifications/client`) when the
+game has both:
+
+- a game-services URL, `VITE_MPGD_GAME_SERVICES_URL`, the one the commerce
+  client uses (a public https URL in production); and
+- a server-backed session, which the game sets with
+  `setStarterServerSession` in `src/platform/serverSession.ts` at the top of
+  `src/main.ts`, before `bootstrap()`: the signed-in `{ playerId, sessionId }`
+  (`undefined` until the player signs in), a sign-in subscription, and the
+  session's `Authorization` header. The commerce client then sends the same
+  header. `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 (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.
+
+Without either, 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
+`listConsent` reads the player's consent records (the Worker's
+`GET /consent`). The runtime also loads the Worker's registry entry for
+its target (`GET /providers`) and turns notifications into a configuration
+error when the provider disagrees with it; a Worker it cannot reach is
+logged and the runtime runs without that check.
+
+Reddit never gets this backend, even with a URL and a session: a Reddit
+game's notifications backend is its Devvit server, which keeps the opt-in,
+the records, and the sends, and the Worker serves no `reddit` target. The
+Worker serves the Android, iOS, and Apps in Toss providers.
+
+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

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

@@ -0,0 +1,157 @@
+import {
+  isPublicGameServicesUrl,
+  resolveGameServicesAuthorityMode,
+  type GameServicesHeaderResolver,
+} from '@mpgd/game-services';
+import {
+  createGameServicesNotificationsClient,
+  type GameServicesNotificationIdentity,
+  type GameServicesNotificationsFetch,
+} from '@mpgd/game-services/notifications/client';
+import type {
+  NotificationConsentRecord,
+  NotificationRuntime,
+  NotificationTopicDeclaration,
+} from '@mpgd/platform/notifications';
+import {
+  createNotificationRuntime,
+  createNotificationRuntimeStorage,
+} from '@mpgd/platform/notifications-runtime';
+import type { TargetConfiguredGateway } from '@mpgd/target-config';
+
+/**
+ * The game backend's notifications surface the starter uses: the runtime
+ * (notifications RFC "Runtime"), which composes the target's provider with
+ * the backend that keeps consent records, endpoint registrations, server
+ * reminders, and notices; and the signed-in player's consent records (the
+ * game-services Worker's `GET /consent`), which the settings screen shows.
+ */
+export interface StarterNotificationBackend {
+  readonly runtime: NotificationRuntime;
+  listConsent(): Promise<readonly NotificationConsentRecord[]>;
+}
+
+/** The server-backed session the Worker client needs (see `serverSession.ts`). */
+export interface StarterWorkerSession extends GameServicesNotificationIdentity {
+  readonly getHeaders: GameServicesHeaderResolver;
+}
+
+export interface StarterWorkerNotificationInput {
+  /** `VITE_MPGD_GAME_SERVICES_URL`. */
+  readonly baseUrl: string | undefined;
+  /** The Vite mode (`import.meta.env.MODE`), which decides the production URL rule. */
+  readonly mode: string;
+  readonly session: StarterWorkerSession | undefined;
+  /** This target's topics, each with its mapping. */
+  readonly topics: readonly NotificationTopicDeclaration[];
+  readonly defaultLocale: string;
+  /** Logs a message, once per gateway and message. */
+  readonly log: (message: string, error?: unknown) => void;
+  /** Defaults to `globalThis.fetch`. */
+  readonly fetch?: GameServicesNotificationsFetch;
+}
+
+/**
+ * Config targets whose notifications backend is not the game-services
+ * Worker. A Reddit game's backend is its Devvit server: the opt-in, the
+ * consent records, and the sends live there, and the Worker serves no
+ * `reddit` target. A runtime over the Worker would send the game's session
+ * header to a backend that cannot use it, so Reddit keeps no backend here,
+ * as before R1, until the Devvit server has a runtime client of its own.
+ */
+const targetsWithoutWorkerBackend: ReadonlySet<string> = new Set(['reddit']);
+
+/**
+ * The notifications runtime over the game-services Worker's notification
+ * routes (`@mpgd/game-services/notifications/client`), when the target's
+ * backend is the Worker, the game has a game-services URL and a
+ * server-backed session, and the target exposes a notifications provider.
+ * Otherwise `undefined`.
+ *
+ * The runtime keeps its registration state in the platform storage, starts
+ * here, and compares its provider with the Worker's registry entry for this
+ * target (`GET /providers`), loaded in the background: a Worker it cannot
+ * reach is logged once and the runtime runs without the comparison.
+ */
+export function createStarterWorkerNotificationBackend(
+  platform: TargetConfiguredGateway,
+  input: StarterWorkerNotificationInput,
+): StarterNotificationBackend | undefined {
+  // By platform, and by config target name for a gateway that reports another platform.
+  if (platform.target === 'reddit' || targetsWithoutWorkerBackend.has(platform.configTarget)) {
+    return undefined;
+  }
+  const baseUrl = input.baseUrl?.trim();
+  const provider = platform.notificationsV2;
+  if (baseUrl === undefined || baseUrl === '' || provider === undefined) {
+    return undefined;
+  }
+  const { session } = input;
+  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.',
+    );
+    return undefined;
+  }
+  try {
+    if (!isAllowedGameServicesUrl(baseUrl, input.mode)) {
+      // The session's credentials never travel in clear text or to a private host in production.
+      input.log(
+        '[notifications] VITE_MPGD_GAME_SERVICES_URL must be an absolute http(s) URL, and a public https URL '
+          + 'without credentials in production; notifications stay off.',
+      );
+      return undefined;
+    }
+    const client = createGameServicesNotificationsClient({
+      baseUrl,
+      identity: session,
+      getHeaders: () => session.getHeaders(),
+      // The catalog target whose mapping applies to this device (android or ios share FCM).
+      target: platform.configTarget,
+      ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
+    });
+    const runtime = createNotificationRuntime({
+      provider,
+      backend: client,
+      catalog: input.topics,
+      defaultLocale: input.defaultLocale,
+      storage: createNotificationRuntimeStorage({ storage: platform.storage }),
+      // This target's entry in the Worker's registry, or none when the Worker does not serve it.
+      async loadRegistryEntry() {
+        const { providers, targets } = await client.getProviders();
+        const id = targets[platform.configTarget];
+        return id === undefined ? undefined : providers.find((entry) => entry.provider === id);
+      },
+      onError(error) {
+        console.error('[notifications]', error);
+      },
+    });
+    // It subscribes to the provider at once; a backend that cannot answer yet does not fail the game.
+    runtime.start().catch((error: unknown) => {
+      console.error('[notifications] the runtime could not start.', error);
+    });
+    return { runtime, listConsent: () => client.listConsent() };
+  } catch (error) {
+    // A configuration the client refuses turns notifications off, never the game.
+    input.log('[notifications] the notifications backend could not be created.', error);
+    return undefined;
+  }
+}
+
+/**
+ * Whether the game-services URL may carry the session's credentials: any
+ * absolute http(s) URL outside production builds, and in production the
+ * public https URL the commerce client requires (`isPublicGameServicesUrl`).
+ */
+function isAllowedGameServicesUrl(baseUrl: string, mode: string): boolean {
+  if (resolveGameServicesAuthorityMode(mode) === 'production') {
+    return isPublicGameServicesUrl(baseUrl);
+  }
+  try {
+    const { protocol } = new URL(baseUrl);
+    return protocol === 'https:' || protocol === 'http:';
+  } catch {
+    return false;
+  }
+}

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

@@ -1,13 +1,13 @@
 import { resolveNotificationTopicsForTarget, type NotificationTopicCatalog } from '@mpgd/catalog';
-import type { PlatformGateway } from '@mpgd/platform';
+import type { NotificationTopicDeclaration } from '@mpgd/platform/notifications';
 import type { TargetConfiguredGateway } from '@mpgd/target-config';
-import type {
-  NotificationConsentRecord,
-  NotificationRuntime,
-  NotificationTopicDeclaration,
-} from '@mpgd/platform/notifications';
 
 import notificationTopicsJson from '../../notifications/topics.json';
+import {
+  createStarterWorkerNotificationBackend,
+  type StarterNotificationBackend,
+} from './notificationBackend';
+import { resolveStarterServerSession } from './serverSession';
 import { routeNotificationOpens, type NotificationOpenRoutes } from './notificationOpens';
 import {
   createStarterNotificationSettings,
@@ -43,45 +43,77 @@ export function starterNotificationTopics(configTarget: string): readonly Notifi
   }
 }
 
-/**
- * The game backend's notifications surface the starter uses: the runtime
- * (notifications RFC "Runtime"), which composes the target's provider with
- * the backend that keeps consent records, endpoint registrations, server
- * reminders, and notices; and the signed-in player's consent records (the
- * game-services Worker's `GET /consent`), which the settings screen shows.
- */
-export interface StarterNotificationBackend {
-  readonly runtime: NotificationRuntime;
-  listConsent(): Promise<readonly NotificationConsentRecord[]>;
-}
+export type { StarterNotificationBackend } from './notificationBackend';
 
 /**
- * The game's notifications backend.
+ * The game's notifications backend: the notifications runtime over the
+ * game-services Worker's notification routes (see `notificationBackend.ts`),
+ * when the game has both a game-services URL (`VITE_MPGD_GAME_SERVICES_URL`,
+ * as the commerce client uses) and a server-backed session
+ * (`setStarterServerSession` in `serverSession.ts`), and the target exposes
+ * a notifications provider. Otherwise `undefined`: the notification settings
+ * screen then asks only for the OS or host permission and shows no
+ * reminder, advertising, or night switch, because nothing could record them.
  *
- * The kit does not ship that runtime's backend client yet: the game-services
- * Worker's notification routes need a session from the identity side, which
- * comes in a later kit release. Until then this returns `undefined`, and the
- * notification settings screen asks only for the OS or host permission and
- * shows no reminder, advertising, or night switch, because nothing could
- * record them. Return your own runtime and consent reader here when your
- * backend implements those routes.
+ * Reddit gets no Worker backend: its notifications backend is the Devvit
+ * server, which keeps the opt-in, the records, and the sends. The Worker
+ * serves the Android, iOS, and Apps in Toss providers and binds a device to
+ * the session its `Authorization` header names, through its
+ * `GAME_SERVICES_NOTIFICATIONS_AUTH` binding to your identity service
+ * (docs/CLOUDFLARE_WORKER_DEPLOY.md, "Sessions"). Call this through the
+ * settings model or `subscribeStarterNotificationOpens`, which keep one
+ * runtime per gateway: a second call starts a second runtime on the same
+ * provider.
  */
 export function createStarterNotificationBackend(
-  _platform: PlatformGateway,
+  platform: TargetConfiguredGateway,
 ): StarterNotificationBackend | undefined {
-  return undefined;
+  return createStarterWorkerNotificationBackend(platform, {
+    baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL,
+    mode: import.meta.env.MODE,
+    session: resolveStarterServerSession(),
+    topics: starterNotificationTopics(platform.configTarget),
+    defaultLocale: starterNotificationCatalog.defaultLocale,
+    log: (message, error) => warnOnce(platform, message, error),
+  });
 }
 
-const backends = new WeakMap<PlatformGateway, StarterNotificationBackend | undefined>();
+/** Messages already logged per gateway: a screen opened again does not log them again. */
+const warned = new WeakMap<TargetConfiguredGateway, Set<string>>();
+function warnOnce(platform: TargetConfiguredGateway, message: string, error?: unknown): void {
+  let messages = warned.get(platform);
+  if (messages === undefined) {
+    messages = new Set();
+    warned.set(platform, messages);
+  }
+  if (!messages.has(message)) {
+    messages.add(message);
+    if (error === undefined) {
+      console.warn(message);
+    } else {
+      console.error(message, error);
+    }
+  }
+}
+
+const backends = new WeakMap<TargetConfiguredGateway, StarterNotificationBackend>();
 /** Per gateway, for the process: agreements given on a host that gives no read. */
-const agreements = new WeakMap<PlatformGateway, Set<string>>();
+const agreements = new WeakMap<TargetConfiguredGateway, Set<string>>();
 
-/** One backend per gateway: a runtime subscribes to its provider once, for the process. */
-function starterNotificationBackend(platform: PlatformGateway): StarterNotificationBackend | undefined {
-  if (!backends.has(platform)) {
-    backends.set(platform, createStarterNotificationBackend(platform));
+/**
+ * One backend per gateway: a runtime subscribes to its provider once, for the
+ * process. A gateway without one yet (no session set) is asked again on the
+ * next use.
+ */
+function starterNotificationBackend(platform: TargetConfiguredGateway): StarterNotificationBackend | undefined {
+  let backend = backends.get(platform);
+  if (backend === undefined) {
+    backend = createStarterNotificationBackend(platform);
+    if (backend !== undefined) {
+      backends.set(platform, backend);
+    }
   }
-  return backends.get(platform);
+  return backend;
 }
 
 /** The settings screen's model for this gateway and locale. */
@@ -121,7 +153,7 @@ export function createStarterNotificationSettingsModel(
  * the game has one, else the provider. Returns the unsubscribe.
  */
 export function subscribeStarterNotificationOpens(
-  platform: PlatformGateway,
+  platform: TargetConfiguredGateway,
   routes: NotificationOpenRoutes,
 ): () => void {
   const source = starterNotificationBackend(platform)?.runtime ?? platform.notificationsV2;

package/templates/notifications-overlay/phaser/src/scenes/NotificationSettingsScene.ts

@@ -16,8 +16,13 @@ export const notificationSettingsSceneKey = 'NotificationSettingsScene';
 
 const textStyle = { color: '#d6dee8', fontFamily: 'Arial, sans-serif', fontSize: '18px' } as const;
 const buttonStyle = { ...textStyle, color: '#5eead4' } as const;
-/** The list's viewport on the 960x540 game: below the title and the outcome strip, above Back. */
-const list = { top: 110, height: 370, width: 960 } as const;
+/** List rows and the outcome strip share this column (x=60..900) on the 960x540 game. */
+const listTextWidth = 840;
+/** Below the title. The outcome strip grows downward from here. */
+const outcomeTop = 68;
+/** The list ends above the Back button. */
+const listBottom = 480;
+const minListTop = 110;
 
 /**
  * Routes notification opens: one whose route is the settings screen (the
@@ -108,10 +113,17 @@ export class NotificationSettingsScene extends Phaser.Scene {
       this.scene.start('LobbyScene');
     }).setOrigin(0.5);
     this.outcome = this.add
-      .text(480, 88, '', { ...textStyle, color: '#f59e0b', fontSize: '16px' })
-      .setOrigin(0.5);
+      .text(480, outcomeTop, '', {
+        ...textStyle,
+        align: 'center',
+        color: '#f59e0b',
+        fontSize: '16px',
+        wordWrap: { width: listTextWidth },
+      })
+      .setOrigin(0.5, 0);
     this.content = this.add.container(0, 0);
-    this.listCamera = this.cameras.add(0, list.top, list.width, list.height);
+    this.listCamera = this.cameras.add(0, minListTop, 960, listBottom - minListTop);
+    this.placeListBelowOutcome();
     this.listCamera.ignore([title, back, this.outcome]);
     this.cameras.main.ignore(this.content);
     this.enableScroll();
@@ -136,9 +148,15 @@ export class NotificationSettingsScene extends Phaser.Scene {
     });
   }
 
+  private placeListBelowOutcome(): void {
+    const top = Math.max(minListTop, Math.ceil(this.outcome.y + this.outcome.height) + 8);
+    this.listCamera.setPosition(0, top);
+    this.listCamera.setSize(960, Math.max(0, listBottom - top));
+  }
+
   private scrollTo(scrollY: number): void {
     const height = this.content.getBounds().height;
-    this.listCamera.scrollY = Phaser.Math.Clamp(scrollY, 0, Math.max(0, height - list.height));
+    this.listCamera.scrollY = Phaser.Math.Clamp(scrollY, 0, Math.max(0, height - this.listCamera.height));
   }
 
   private async apply(visit: number, action: () => Promise<StarterNotificationSettingsView>): Promise<void> {
@@ -172,7 +190,7 @@ export class NotificationSettingsScene extends Phaser.Scene {
     const visit = this.visit;
     let y = 0;
     const line = (value: string, style: Phaser.Types.GameObjects.Text.TextStyle = textStyle) => {
-      const object = this.add.text(60, y, value, { ...style, wordWrap: { width: 840 } });
+      const object = this.add.text(60, y, value, { ...style, wordWrap: { width: listTextWidth } });
       this.content.add(object);
       y += object.height + 10;
     };
@@ -186,6 +204,7 @@ export class NotificationSettingsScene extends Phaser.Scene {
 
     // The outcome of the last tap stays in view above the list, wherever it is scrolled.
     this.outcome.setText(view.message ?? '');
+    this.placeListBelowOutcome();
     if (!view.available) {
       if (view.message === undefined) {
         line(text.unavailable);

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

@@ -15,6 +15,7 @@ import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
 
 import { resolveStarterCommerceProducts } from './commerceProducts';
 import { createStorageMonetizationOperationStore } from './monetizationJournal';
+import { resolveStarterServerSession } from './serverSession';
 
 const productCatalog = productCatalogJson as ProductCatalog;
 
@@ -47,6 +48,7 @@ export function createStarterGameServices(input: {
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
 }): StarterGameServices {
+  const session = resolveStarterServerSession({ once: true });
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
@@ -64,5 +66,6 @@ export function createStarterGameServices(input: {
       ? {}
       : { baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL }),
     transport: resolveGameServicesTransport(import.meta.env.VITE_MPGD_GAME_SERVICES_TRANSPORT),
+    ...(session === undefined ? {} : { getHeaders: () => session.getHeaders() }),
   });
 }

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

@@ -0,0 +1,66 @@
+import type { GameServicesHeaderResolver } from '@mpgd/game-services';
+
+/**
+ * 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.
+ *
+ * `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.
+ */
+export interface StarterServerSession {
+  /**
+   * The signed-in player and session, or `undefined` while signed out.
+   * `sessionId` is the stable session-family id (see above).
+   */
+  current(): { readonly playerId: string; readonly sessionId: string } | undefined;
+  /** Calls `listener` when a session becomes current (sign-in, restore, account switch); returns the unsubscribe. */
+  onAuthenticated(
+    listener: (session: { readonly playerId: string; readonly sessionId: string }) => void,
+  ): () => void;
+  /** The current session's request headers, such as `{ authorization: 'Bearer …' }`. */
+  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 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.
+ */
+export function resolveStarterServerSession(
+  options: { readonly once?: boolean } = {},
+): StarterServerSession | undefined {
+  if (options.once === true) {
+    readOnce = true;
+  }
+  return serverSession;
+}
+
+/**
+ * Sets the game's server-backed session. Call it at the top of `main.ts`,
+ * before `bootstrap()`: `createStarterGameServices` reads it once, and the
+ * 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.
+ */
+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;
+}