@mpgd/cli 0.55.0 → 0.57.0

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

@@ -64,6 +64,15 @@ const commonEdits = {
     'src/platform/buildGateways/capacitorAndroid.ts': [gatewayImport, gatewayProviders('android')],
     'src/platform/buildGateways/capacitorIos.ts': [gatewayImport, gatewayProviders('ios')],
     'src/platform/buildGateways/reddit.ts': [
+        {
+            anchor: '  createDevvitCommerceProducts,\n  createDevvitPlatformGateway,\n',
+            replacement: [
+                '  createDevvitCommerceProducts,',
+                '  createDevvitNotificationsBackend,',
+                '  createDevvitPlatformGateway,',
+                '',
+            ].join('\n'),
+        },
         {
             anchor: "import { createDevvitWebPaymentsClient } from '@mpgd/adapter-devvit/web';\n",
             replacement: [
@@ -77,6 +86,7 @@ const commonEdits = {
         {
             anchor: "import type { RuntimeConfig } from '../runtimeDetector';\n",
             replacement: [
+                "import { setStarterHostedNotificationBackend } from '../notificationBackend';",
                 "import { starterNotificationTopics } from '../notifications';",
                 "import type { RuntimeConfig } from '../runtimeDetector';",
                 '',
@@ -102,7 +112,14 @@ const commonEdits = {
                 '  runtime: RuntimeConfig,',
                 "): Pick<Parameters<typeof createDevvitPlatformGateway>[0], 'notifications'> {",
                 '  const topics = starterNotificationTopics(runtime.configTarget).map((topic) => topic.id);',
-                '  return topics.length === 0 ? {} : { notifications: { topics } };',
+                '  if (topics.length === 0) {',
+                '    return {};',
+                '  }',
+                "  // The runtime's backend is the Devvit server (consent records, reminders, notices for the",
+                '  // logged-in Reddit user), over the same server bridge as the gateway; created on first use.',
+                '  setStarterHostedNotificationBackend(runtime.configTarget, () =>',
+                '    createDevvitNotificationsBackend({ appVersion: runtime.appVersion, buildId: runtime.buildId }));',
+                '  return { notifications: { topics } };',
                 '}',
                 '',
                 'function createCommerceOptions(): DevvitGatewayCommerceOptions | undefined {',
@@ -139,6 +156,7 @@ const commonEdits = {
                 '  createDevvitCommerceBridgeProducts,',
                 '  createDevvitCommerceV2BridgeHandler,',
                 '  createDevvitNotificationService,',
+                '  createDevvitNotificationsBackendBridgeHandler,',
                 '  createDevvitNotificationsV2BridgeHandler,',
                 "} from '@mpgd/adapter-devvit/server';",
                 '',
@@ -182,7 +200,7 @@ const commonEdits = {
                 ' */',
                 'const notificationTopicCatalog = notificationTopicsJson as NotificationTopicCatalog;',
                 'const redditNotificationTopics = readRedditNotificationTopics();',
-                "const notificationService: Parameters<typeof handleNotificationTask>[0]['notifications'] =",
+                "const notificationService: ReturnType<typeof createDevvitNotificationService>['service'] | undefined =",
                 '  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',
@@ -192,6 +210,10 @@ const commonEdits = {
                 '      currentUserId: currentPlayerId,',
                 '      topics: redditNotificationTopics,',
                 '    });',
+                "// The webview runtime's backend: consent records, reminders, and notices for the request's user.",
+                'const notificationsBackend = notificationService === undefined',
+                '  ? undefined',
+                '  : createDevvitNotificationsBackendBridgeHandler({ service: notificationService, context: () => context });',
                 'const handleBridgeRequest = createDevvitBridgeHandler({',
                 '  redis,',
                 '  currentPlayerId,',
@@ -199,6 +221,7 @@ const commonEdits = {
                 '  storageKeyNamespace: gameName,',
                 '  ...(commerce === undefined ? {} : { commerce }),',
                 '  ...(notificationsBridge === undefined ? {} : { notifications: notificationsBridge }),',
+                '  ...(notificationsBackend === undefined ? {} : { notificationsBackend }),',
                 '});',
                 '',
             ].join('\n'),
@@ -230,7 +253,7 @@ const commonEdits = {
                 ' * deployment the service refuses turns notifications off, never the game',
                 ' * server.',
                 ' */',
-                "function createNotificationService(): Parameters<typeof handleNotificationTask>[0]['notifications'] {",
+                "function createNotificationService(): ReturnType<typeof createDevvitNotificationService>['service'] | undefined {",
                 '  try {',
                 '    return createDevvitNotificationService({',
                 '      redis,',
@@ -479,11 +502,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.55.0",
+  "version": "0.57.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.7",
-    "@mpgd/target-config": "0.23.7",
-    "@mpgd/platform": "0.27.2",
-    "@mpgd/phaser-assets": "0.9.1"
+    "@mpgd/catalog": "0.10.8",
+    "@mpgd/platform": "0.28.0",
+    "@mpgd/phaser-assets": "0.9.1",
+    "@mpgd/target-config": "0.23.8"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -81,19 +81,19 @@
     "@types/yauzl": "3.4.0",
     "ttsc": "0.32.1",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.20.3",
-    "@mpgd/adapter-browser": "0.11.7",
-    "@mpgd/adapter-capacitor": "0.12.3",
-    "@mpgd/adapter-devvit": "0.13.5",
-    "@mpgd/adapter-verse8": "0.7.7",
-    "@mpgd/analytics": "0.4.16",
-    "@mpgd/capacitor-play-billing": "0.3.7",
-    "@mpgd/bridge": "0.15.0",
-    "@mpgd/capacitor-storekit": "0.3.7",
-    "@mpgd/game-runtime": "0.8.0",
-    "@mpgd/game-services": "0.27.2",
-    "@mpgd/i18n": "0.6.21",
-    "@mpgd/lite-shell": "0.1.0"
+    "@mpgd/adapter-ait": "0.20.5",
+    "@mpgd/adapter-browser": "0.11.8",
+    "@mpgd/adapter-capacitor": "0.12.5",
+    "@mpgd/adapter-devvit": "0.14.0",
+    "@mpgd/adapter-verse8": "0.7.9",
+    "@mpgd/capacitor-play-billing": "0.3.9",
+    "@mpgd/game-runtime": "0.8.2",
+    "@mpgd/bridge": "0.16.0",
+    "@mpgd/capacitor-storekit": "0.3.9",
+    "@mpgd/analytics": "0.5.1",
+    "@mpgd/game-services": "0.28.1",
+    "@mpgd/lite-shell": "0.1.0",
+    "@mpgd/i18n": "0.6.22"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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
@@ -92,6 +104,22 @@ 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.
 
+On Reddit the runtime runs over the Devvit server instead:
+`src/platform/buildGateways/reddit.ts` sets
+`createDevvitNotificationsBackend` as the hosted backend
+(`setStarterHostedNotificationBackend`), and the generated Devvit server
+serves it with `createDevvitNotificationsBackendBridgeHandler`. No session
+is needed: the server answers for the logged-in Reddit user, and a
+logged-out player is asked to log in first. Once Reddit approves the app
+and `integrations.notifications` is `available`, the settings screen shows
+the reminder switches there; advertising and night consent stay off,
+because Devvit delivers `service` and `requested` topics only. A reminder
+the game schedules on Reddit (`runtime.reminders.set`) needs a post or
+comment to open: pass `link` (the post id, `context.postId` from
+`@devvit/web/client`), or give the topic's `reddit` mapping a default
+`link`; the `mpgd-notifications-dispatch` task sends it through Devvit when
+it is due.
+
 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
@@ -102,3 +130,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

@@ -16,6 +16,7 @@ import type {
 import {
   createNotificationRuntime,
   createNotificationRuntimeStorage,
+  type NotificationRuntimeBackend,
 } from '@mpgd/platform/notifications-runtime';
 import type { TargetConfiguredGateway } from '@mpgd/target-config';
 
@@ -56,8 +57,8 @@ export interface StarterWorkerNotificationInput {
  * 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.
+ * header to a backend that cannot use it, so Reddit gets the hosted backend
+ * below instead (`createStarterHostedNotificationBackend`).
  */
 const targetsWithoutWorkerBackend: ReadonlySet<string> = new Set(['reddit']);
 
@@ -90,7 +91,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;
   }
@@ -139,6 +141,114 @@ export function createStarterWorkerNotificationBackend(
   }
 }
 
+/**
+ * A backend the target's own server hosts, set by the target's gateway
+ * builder for its config target: on Reddit, `createDevvitNotificationsBackend`
+ * from `@mpgd/adapter-devvit` over the Devvit server bridge
+ * (`buildGateways/reddit.ts`). The server answers for the request's
+ * logged-in Reddit user, so the game sets no session of its own. The
+ * backend is created on first use, so a game whose target exposes no
+ * notifications provider (Reddit's gated beta before approval) sends
+ * nothing.
+ */
+let hostedBackend:
+  | {
+      readonly configTarget: string;
+      readonly create: () => NotificationRuntimeBackend;
+      created?: NotificationRuntimeBackend;
+      /** The factory threw once: notifications stay off, and the failure is logged once. */
+      failed?: true;
+    }
+  | undefined;
+
+/**
+ * Sets the backend `configTarget`'s own server hosts, as a factory called on
+ * first use; `undefined` clears it.
+ */
+export function setStarterHostedNotificationBackend(
+  configTarget: string,
+  create: (() => NotificationRuntimeBackend) | undefined,
+): void {
+  hostedBackend = create === undefined ? undefined : { configTarget, create };
+}
+
+/**
+ * The backend `configTarget`'s own server hosts, created on the first call;
+ * `undefined` when none was set for this config target, or when its factory
+ * threw (logged once; not called again until a new factory is set).
+ */
+export function resolveStarterHostedNotificationBackend(configTarget: string): NotificationRuntimeBackend | undefined {
+  if (hostedBackend === undefined || hostedBackend.configTarget !== configTarget) {
+    return undefined;
+  }
+  if (hostedBackend.failed === true) {
+    return undefined;
+  }
+  try {
+    hostedBackend.created ??= hostedBackend.create();
+  } catch (error) {
+    // A backend that cannot be created turns notifications off, never the game.
+    hostedBackend.failed = true;
+    console.error('[notifications] the hosted notifications backend could not be created.', error);
+    return undefined;
+  }
+  return hostedBackend.created;
+}
+
+export interface StarterHostedNotificationInput {
+  readonly backend: NotificationRuntimeBackend | 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;
+}
+
+/**
+ * The notifications runtime over a backend the target's own server hosts
+ * (Reddit: the Devvit server's notifications service), when the target
+ * exposes a notifications provider and its gateway builder set the backend.
+ * Otherwise `undefined`.
+ *
+ * The runtime keeps its registration state in the platform storage and
+ * starts here. It learns the player from the backend, which reads the
+ * session the server answers, so the settings screen shows the reminder
+ * switches once a logged-in Reddit user is known; a logged-out viewer is
+ * asked to log in first. It runs without a registry entry comparison: the
+ * provider and the server's service come from the same adapter and
+ * deployment, and the entry lives in server code the webview does not load.
+ */
+export function createStarterHostedNotificationBackend(
+  platform: TargetConfiguredGateway,
+  input: StarterHostedNotificationInput,
+): StarterNotificationBackend | undefined {
+  const provider = platform.notificationsV2;
+  const { backend } = input;
+  if (provider === undefined || backend === undefined) {
+    return undefined;
+  }
+  try {
+    const runtime = createNotificationRuntime({
+      provider,
+      backend,
+      catalog: input.topics,
+      defaultLocale: input.defaultLocale,
+      storage: createNotificationRuntimeStorage({ storage: platform.storage }),
+      onError(error) {
+        console.error('[notifications]', error);
+      },
+    });
+    runtime.start().catch((error: unknown) => {
+      console.error('[notifications] the runtime could not start.', error);
+    });
+    return { runtime, listConsent: () => backend.listConsent() };
+  } catch (error) {
+    // A configuration the runtime 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

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

@@ -4,7 +4,9 @@ import type { TargetConfiguredGateway } from '@mpgd/target-config';
 
 import notificationTopicsJson from '../../notifications/topics.json';
 import {
+  createStarterHostedNotificationBackend,
   createStarterWorkerNotificationBackend,
+  resolveStarterHostedNotificationBackend,
   type StarterNotificationBackend,
 } from './notificationBackend';
 import { resolveStarterServerSession } from './serverSession';
@@ -56,7 +58,11 @@ export type { StarterNotificationBackend } from './notificationBackend';
  * reminder, advertising, or night switch, because nothing could record them.
  *
  * Reddit gets no Worker backend: its notifications backend is the Devvit
- * server, which keeps the opt-in, the records, and the sends. The Worker
+ * server, which keeps the opt-in, the records, and the sends. The runtime
+ * there runs over the backend `buildGateways/reddit.ts` sets
+ * (`createDevvitNotificationsBackend`, through
+ * `setStarterHostedNotificationBackend`), which needs no game session: the
+ * Devvit server answers for the logged-in Reddit user. 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
@@ -68,6 +74,18 @@ export type { StarterNotificationBackend } from './notificationBackend';
 export function createStarterNotificationBackend(
   platform: TargetConfiguredGateway,
 ): StarterNotificationBackend | undefined {
+  // Only a hosted backend set for this config target; other targets keep the Worker path.
+  const hosted = platform.notificationsV2 === undefined
+    ? undefined
+    : resolveStarterHostedNotificationBackend(platform.configTarget);
+  if (hosted !== undefined) {
+    return createStarterHostedNotificationBackend(platform, {
+      backend: hosted,
+      topics: starterNotificationTopics(platform.configTarget),
+      defaultLocale: starterNotificationCatalog.defaultLocale,
+      log: (message, error) => warnOnce(platform, message, error),
+    });
+  }
   return createStarterWorkerNotificationBackend(platform, {
     baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL,
     mode: import.meta.env.MODE,

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/src/server/bridge.ts

@@ -3,7 +3,9 @@ import {
   bridgeStorageLoadProtocol,
   createBridgeError,
   createCommerceV2UnavailableBridgeError,
+  createNotificationsBackendUnavailableBridgeError,
   createNotificationsV2UnavailableBridgeError,
+  isBridgeNotificationsBackendMethod,
   isBridgeNotificationsV2Method,
   type BridgeRequest,
   type BridgeResponse,
@@ -68,6 +70,16 @@ export interface DevvitBridgeNotificationsHandler {
   request(input: BridgeRequest): Promise<BridgeResponse>;
 }
 
+/**
+ * Serves the nine `notifications.backend.*` bridge methods:
+ * `createDevvitNotificationsBackendBridgeHandler` from
+ * `@mpgd/adapter-devvit/server` over the Devvit notifications service, for
+ * the request's logged-in user.
+ */
+export interface DevvitBridgeNotificationsBackendHandler {
+  request(input: BridgeRequest): Promise<BridgeResponse>;
+}
+
 export interface DevvitBridgeHandlerDependencies {
   readonly redis: DevvitBridgeRedisLike;
   /** Authenticated Reddit user ID from the Devvit request context, never from the payload. */
@@ -91,6 +103,14 @@ export interface DevvitBridgeHandlerDependencies {
    * `unavailable`.
    */
   readonly notifications?: DevvitBridgeNotificationsHandler | undefined;
+  /**
+   * The notifications runtime's backend: consent records, the player's
+   * registration, server reminders, and notices, kept by the Devvit
+   * notifications service. Absent, every `notifications.backend.*` method
+   * answers `NOTIFICATIONS_CONFIGURATION_REQUIRED`, and the webview's
+   * runtime runs without a backend.
+   */
+  readonly notificationsBackend?: DevvitBridgeNotificationsBackendHandler | undefined;
   readonly warn?: ((message: string) => void) | undefined;
 }
 
@@ -129,6 +149,23 @@ export function createDevvitBridgeHandler(
         );
       }
     }
+    // The runtime's backend calls, kept apart from the provider methods above.
+    if (isBridgeNotificationsBackendMethod(input.method)) {
+      if (dependencies.notificationsBackend === undefined) {
+        return createNotificationsBackendUnavailableBridgeError(input, 'Devvit server bridge');
+      }
+      try {
+        return await dependencies.notificationsBackend.request(input);
+      } catch (error) {
+        warn(`devvit notifications ${input.method} failed: ${errorMessage(error)}`);
+        return createBridgeError(
+          input.id,
+          'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+          `${input.method} failed on the Devvit server.`,
+          true,
+        );
+      }
+    }
     switch (input.method) {
       case 'runtime.getCapabilities':
         return ok(input, {