@mpgd/cli 0.52.0 → 0.54.0

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

@@ -0,0 +1,104 @@
+# 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. `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
+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"
+}

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

@@ -0,0 +1,222 @@
+{
+  "version": "1",
+  "defaultLocale": "ko",
+  "notices": {
+    "topic": "consent-notice",
+    "copy": {
+      "ko": {
+        "consent-result.advertising.granted": {
+          "title": "[__GAME_TITLE__] 광고성 정보 수신동의 결과",
+          "body": "{{consentDate}}에 하신 광고성 정보 수신동의가 처리됐어요. 알림 설정에서 언제든 철회할 수 있어요."
+        },
+        "consent-result.advertising.refused": {
+          "title": "[__GAME_TITLE__] 광고성 정보 수신거부 결과",
+          "body": "{{consentDate}}에 하신 광고성 정보 수신거부가 처리됐어요."
+        },
+        "consent-result.advertising.withdrawn": {
+          "title": "[__GAME_TITLE__] 광고성 정보 수신동의 철회 결과",
+          "body": "{{consentDate}}에 하신 광고성 정보 수신동의 철회가 처리됐어요."
+        },
+        "consent-result.night.granted": {
+          "title": "[__GAME_TITLE__] 야간 광고성 정보 수신동의 결과",
+          "body": "{{consentDate}}에 하신 야간(21시~다음 날 8시) 광고성 정보 수신동의가 처리됐어요. 알림 설정에서 언제든 철회할 수 있어요."
+        },
+        "consent-result.night.refused": {
+          "title": "[__GAME_TITLE__] 야간 광고성 정보 수신거부 결과",
+          "body": "{{consentDate}}에 하신 야간(21시~다음 날 8시) 광고성 정보 수신거부가 처리됐어요."
+        },
+        "consent-result.night.withdrawn": {
+          "title": "[__GAME_TITLE__] 야간 광고성 정보 수신동의 철회 결과",
+          "body": "{{consentDate}}에 하신 야간(21시~다음 날 8시) 광고성 정보 수신동의 철회가 처리됐어요."
+        },
+        "reconfirmation.advertising": {
+          "title": "[__GAME_TITLE__] 광고성 정보 수신동의 확인",
+          "body": "{{consentDate}}에 광고성 정보 수신에 동의하셨어요. 동의를 유지하려면 따로 하실 일은 없고, 철회하려면 게임의 알림 설정에서 광고성 정보 수신을 끄면 돼요."
+        },
+        "reconfirmation.night": {
+          "title": "[__GAME_TITLE__] 야간 광고성 정보 수신동의 확인",
+          "body": "{{consentDate}}에 야간(21시~다음 날 8시) 광고성 정보 수신에 동의하셨어요. 동의를 유지하려면 따로 하실 일은 없고, 철회하려면 게임의 알림 설정에서 야간 수신을 끄면 돼요."
+        }
+      },
+      "en": {
+        "consent-result.advertising.granted": {
+          "title": "[__GAME_TITLE__] Promotional notifications: consent processed",
+          "body": "Your consent to promotional notifications on {{consentDate}} has been processed. You can withdraw it any time in the game's notification settings."
+        },
+        "consent-result.advertising.refused": {
+          "title": "[__GAME_TITLE__] Promotional notifications: refusal processed",
+          "body": "Your refusal of promotional notifications on {{consentDate}} has been processed."
+        },
+        "consent-result.advertising.withdrawn": {
+          "title": "[__GAME_TITLE__] Promotional notifications: withdrawal processed",
+          "body": "Your withdrawal of consent to promotional notifications on {{consentDate}} has been processed."
+        },
+        "consent-result.night.granted": {
+          "title": "[__GAME_TITLE__] Night-time promotional notifications: consent processed",
+          "body": "Your consent to promotional notifications between 21:00 and 08:00 on {{consentDate}} has been processed. You can withdraw it any time in the game's notification settings."
+        },
+        "consent-result.night.refused": {
+          "title": "[__GAME_TITLE__] Night-time promotional notifications: refusal processed",
+          "body": "Your refusal of promotional notifications between 21:00 and 08:00 on {{consentDate}} has been processed."
+        },
+        "consent-result.night.withdrawn": {
+          "title": "[__GAME_TITLE__] Night-time promotional notifications: withdrawal processed",
+          "body": "Your withdrawal of consent to promotional notifications between 21:00 and 08:00 on {{consentDate}} has been processed."
+        },
+        "reconfirmation.advertising": {
+          "title": "[__GAME_TITLE__] Promotional notifications: your consent",
+          "body": "You agreed to promotional notifications on {{consentDate}}. To keep this consent you need do nothing; to withdraw it, turn promotional notifications off in the game's notification settings."
+        },
+        "reconfirmation.night": {
+          "title": "[__GAME_TITLE__] Night-time promotional notifications: your consent",
+          "body": "You agreed to promotional notifications between 21:00 and 08:00 on {{consentDate}}. To keep this consent you need do nothing; to withdraw it, turn night-time promotional notifications off in the game's notification settings."
+        }
+      }
+    }
+  },
+  "topics": [
+    {
+      "id": "daily-ready",
+      "purpose": "requested",
+      "channels": [
+        "local",
+        "remote"
+      ],
+      "route": "/?entry=continue",
+      "copy": {
+        "ko": {
+          "title": "오늘의 플레이",
+          "body": "오늘의 판이 준비됐어요."
+        },
+        "en": {
+          "title": "Today's run",
+          "body": "Today's run is ready."
+        }
+      },
+      "frequency": {
+        "maxPerDay": 1
+      },
+      "quietHours": {
+        "start": "21:00",
+        "end": "08:00"
+      },
+      "targets": {
+        "android": {
+          "channelId": "mpgd-requested"
+        },
+        "ios": {},
+        "reddit": {
+          "title": "Today's run is ready",
+          "body": "Today's run is ready when you are."
+        }
+      }
+    },
+    {
+      "id": "streak-at-risk",
+      "purpose": "requested",
+      "channels": [
+        "local",
+        "remote"
+      ],
+      "route": "/?entry=continue",
+      "copy": {
+        "ko": {
+          "title": "연속 플레이 기록",
+          "body": "오늘 플레이하면 연속 기록이 이어져요."
+        },
+        "en": {
+          "title": "Your streak",
+          "body": "Play today to keep your streak going."
+        }
+      },
+      "frequency": {
+        "maxPerDay": 1
+      },
+      "quietHours": {
+        "start": "21:00",
+        "end": "08:00"
+      },
+      "targets": {
+        "android": {
+          "channelId": "mpgd-requested"
+        },
+        "ios": {},
+        "reddit": {
+          "title": "Your streak",
+          "body": "Play today to keep your streak going."
+        }
+      }
+    },
+    {
+      "id": "friend-challenge",
+      "purpose": "service",
+      "channels": [
+        "remote"
+      ],
+      "route": "/?entry=challenge",
+      "copy": {
+        "ko": {
+          "title": "친구의 도전",
+          "body": "{{friend}} 님이 도전장을 보냈어요."
+        },
+        "en": {
+          "title": "Friend challenge",
+          "body": "{{friend}} sent you a challenge."
+        }
+      },
+      "quietHours": {
+        "start": "22:00",
+        "end": "08:00"
+      },
+      "targets": {
+        "android": {
+          "channelId": "mpgd-service"
+        },
+        "ios": {},
+        "reddit": {
+          "title": "Friend challenge",
+          "body": "A friend sent you a challenge."
+        }
+      }
+    },
+    {
+      "id": "events",
+      "purpose": "advertising",
+      "channels": [
+        "remote"
+      ],
+      "route": "/?entry=events",
+      "optOutRoute": "/?entry=notification-settings",
+      "copy": {
+        "ko": {
+          "title": "이번 주 이벤트",
+          "body": "새 이벤트가 시작됐어요."
+        },
+        "en": {
+          "title": "This week's event",
+          "body": "A new event has started."
+        }
+      },
+      "frequency": {
+        "maxPerDay": 1
+      },
+      "targets": {
+        "ios": {}
+      }
+    },
+    {
+      "id": "consent-notice",
+      "purpose": "service",
+      "channels": [
+        "remote"
+      ],
+      "route": "/?entry=notification-settings",
+      "targets": {
+        "android": {
+          "channelId": "mpgd-service"
+        },
+        "ios": {}
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,59 @@
+import type { CapacitorServiceProvider } from '@mpgd/adapter-capacitor';
+import {
+  createCapacitorNotificationServiceProvider,
+  loadCapacitorNotificationSdks,
+  openCapacitorNotificationSettings,
+} from '@mpgd/adapter-capacitor/notifications';
+
+import { starterNotificationTopics } from './notifications';
+
+/**
+ * The Android and iOS notifications v2 provider over
+ * `@capacitor-firebase/messaging` (remote, FCM for both platforms) and
+ * `@capacitor/local-notifications` (local reminders, the permission read,
+ * and the advertising opt-out action). `mpgd target init capacitor
+ * --providers notifications` installs both into the native shell. A shell
+ * without them still runs: the provider fails closed for the missing half,
+ * and without both it is `unsupported`.
+ *
+ * It is created once, early, because the provider registers its native
+ * listeners when it is created, which is how a cold-start open reaches it.
+ * Never install `@capacitor/push-notifications` next to it: on iOS both
+ * claim Capacitor's one push handler.
+ */
+export async function createStarterCapacitorNotifications(
+  platform: 'android' | 'ios',
+  configTarget: string,
+): Promise<readonly CapacitorServiceProvider[]> {
+  const topics = starterNotificationTopics(configTarget);
+  if (topics.length === 0) {
+    return [];
+  }
+  const sdks = await loadCapacitorNotificationSdks();
+  const korean = (globalThis.navigator?.language ?? '').toLowerCase().startsWith('ko');
+  return [
+    createCapacitorNotificationServiceProvider({
+      platform,
+      topics,
+      ...sdks,
+      // Android channel names the player sees in system settings, in the
+      // device language. The provider creates a channel only for the topics
+      // mapped to Android; `mpgd-advertising` is named for the day an
+      // advertising topic is mapped there, in a channel of its own the
+      // player can turn off.
+      channels: korean
+        ? {
+            'mpgd-service': { name: '알림' },
+            'mpgd-requested': { name: '리마인더' },
+            'mpgd-advertising': { name: '광고성 정보' },
+          }
+        : {
+            'mpgd-service': { name: 'Notifications' },
+            'mpgd-requested': { name: 'Reminders' },
+            'mpgd-advertising': { name: 'Promotions' },
+          },
+      advertisingOptOutTitle: korean ? '수신거부' : 'Unsubscribe',
+      openSettings: openCapacitorNotificationSettings,
+    }),
+  ];
+}

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/notificationOpens.ts

@@ -0,0 +1,60 @@
+import { isRootRelativeNotificationRoute } from '@mpgd/catalog';
+import type { NotificationEvent } from '@mpgd/platform/notifications';
+
+/** The route the advertising opt-out action and the consent notices open. */
+export const starterNotificationSettingsRoute = '/?entry=notification-settings';
+
+export interface NotificationOpenRoutes {
+  /** An open whose route is the settings screen. */
+  readonly settings: () => void;
+  /** Every other open, as the provider reported it, with `route` only when it is safe. */
+  readonly other?: (open: Omit<Extract<NotificationEvent, { readonly type: 'opened' }>, 'route'> & {
+    readonly route?: string;
+  }) => void;
+}
+
+/**
+ * The game's one listener for notification opens. It is the runtime's (or
+ * the provider's) first subscriber, which is the one that receives a
+ * cold-start open (RFC "Buffer before the first listener"), so route every
+ * topic's opens here rather than in a later subscriber. The starter routes
+ * the settings screen: the advertising opt-out action and the consent
+ * notices carry `starterNotificationSettingsRoute`, and the RFC requires the
+ * opt-out to open that screen directly. `other` receives every other open,
+ * with a route only when `isRootRelativeNotificationRoute` accepts it. The
+ * data an open carries is untrusted and never grants anything. Returns the
+ * unsubscribe.
+ */
+export function routeNotificationOpens(
+  source: { subscribe(listener: (event: NotificationEvent) => void): () => void },
+  routes: NotificationOpenRoutes,
+): () => void {
+  return source.subscribe((event) => {
+    if (event.type !== 'opened') {
+      return;
+    }
+    const route = event.route !== undefined && isRootRelativeNotificationRoute(event.route)
+      ? event.route
+      : undefined;
+    if (route !== undefined && isSettingsRoute(route)) {
+      routes.settings();
+      return;
+    }
+    const { route: _unsafe, ...rest } = event;
+    routes.other?.({ ...rest, ...(route === undefined ? {} : { route }) });
+  });
+}
+
+const settingsEntry = new URL(starterNotificationSettingsRoute, 'https://game.invalid')
+  .searchParams.get('entry');
+
+/**
+ * Whether a route opens the settings screen: the same `entry` as
+ * `starterNotificationSettingsRoute`. Only routes
+ * `isRootRelativeNotificationRoute` accepted reach it, which parse.
+ */
+function isSettingsRoute(route: string): boolean {
+  // A settings route without an `entry` would match every route: fail closed.
+  return settingsEntry !== null
+    && new URL(route, 'https://game.invalid').searchParams.get('entry') === settingsEntry;
+}