@mpgd/cli 0.64.0 → 0.66.0

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

@@ -4,6 +4,7 @@ import productCatalogJson from '@mpgd/catalog/catalog.json';
 import {
   createGameServicesRuntime,
   resolveGameServicesAuthorityMode,
+  resolveGameServicesBaseUrl,
   resolveGameServicesTransport,
   type GameServicesRuntime,
   type GameServicesRuntimeMode,
@@ -13,11 +14,17 @@ import type { PlatformGateway } from '@mpgd/platform';
 import type { GameActionReconciliationPort } from '@mpgd/game-runtime/actions';
 import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
 
+import {
+  pinStarterCommercePlayer,
+  resolveStarterStoreAccountBindingFor,
+  starterStoreAccountBindingKind,
+} from './commerceAccountBinding';
 import { resolveStarterCommerceProducts } from './commerceProducts';
 import type { StarterGuestSignIn } from './guestIdentity';
 import { createStorageMonetizationOperationStore } from './monetizationJournal';
 import { resolveStarterServerSession } from './serverSession';
 import {
+  bindStarterServicesToPlayer,
   createSessionGatedGameServices,
   type StarterSessionGatedServices,
 } from './sessionGatedServices';
@@ -52,6 +59,20 @@ interface StarterGameServicesInput {
   readonly operationStore?: MonetizationOperationStore;
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
+  /**
+   * Called at once when the server session names another player than the
+   * services' (an account switch within the run): the services refuse
+   * everything from now on; block input or show a switching screen
+   * (`main.ts` does both). `onPlayerChanged` follows.
+   */
+  readonly onPlayerChanging?: (playerId: string) => void;
+  /**
+   * Called once after `onPlayerChanging`, when the closed services have
+   * stopped (an open store sheet first journals its answer, up to
+   * `gameServicesDisposeWaitMs`): restart the game so it boots for that
+   * player (`main.ts` reloads).
+   */
+  readonly onPlayerChanged?: (playerId: string) => void;
 }
 
 /**
@@ -60,9 +81,42 @@ interface StarterGameServicesInput {
  * over the platform storage adapter unless the game supplies its own) and
  * verified through the backend ledger, with the catalog's kinds and SKUs for
  * the gateway target resolved without a store read.
+ *
+ * With a server session (`setStarterServerSession`), the services belong to
+ * `playerId` for their whole life and fail closed for anyone else: while the
+ * session names no player, purchases and backend requests are refused
+ * (retryable); once it names another player (an account switch), the
+ * services close for good before that player's headers or store account
+ * binding reach this player's journal (purchases answer `failed` with the
+ * retryable diagnostic `GAME_SERVICES_PLAYER_CHANGED`), `onPlayerChanging`
+ * tells the host at once, and `onPlayerChanged` asks it to boot again for
+ * the new player once they have stopped. Pass the
+ * session's player as `playerId`, never the platform's local placeholder:
+ * services created for another player than the session's stay closed.
  */
 export function createStarterGameServices(input: StarterGameServicesInput): StarterGameServices {
-  return createRuntime(input, resolveStarterServerSession({ once: true }));
+  const session = resolveStarterServerSession({ once: true });
+  if (session === undefined) {
+    return createRuntime(input, session);
+  }
+  // The store account binding follows the same player as the journal, until
+  // these services were disposed; throws while another player's are open.
+  const releasePin = pinStarterCommercePlayer(input.playerId);
+  let services: GameServicesRuntime;
+  try {
+    services = createRuntime(input, session);
+  } catch (error) {
+    releasePin();
+    throw error;
+  }
+  return bindStarterServicesToPlayer({
+    services,
+    playerId: input.playerId,
+    session,
+    onDisposed: releasePin,
+    ...(input.onPlayerChanging === undefined ? {} : { onPlayerChanging: input.onPlayerChanging }),
+    ...(input.onPlayerChanged === undefined ? {} : { onPlayerChanged: input.onPlayerChanged }),
+  });
 }
 
 /**
@@ -79,14 +133,30 @@ export function createStarterSessionGatedGameServices(
     readonly onActivated?: () => void;
   },
 ): StarterGameServices {
-  const { signIn, onActivated, ...rest } = input;
+  const { signIn, onActivated, onPlayerChanging, onPlayerChanged, ...rest } = input;
+  // The inner services (a session switch) and the gate (a later sign-in) may
+  // both see the same change; the host hears each step once.
+  const once = (callback: (playerId: string) => void): ((playerId: string) => void) => {
+    let called = false;
+    return (playerId) => {
+      if (!called) {
+        called = true;
+        callback(playerId);
+      }
+    };
+  };
+  const hooks = {
+    ...(onPlayerChanging === undefined ? {} : { onPlayerChanging: once(onPlayerChanging) }),
+    ...(onPlayerChanged === undefined ? {} : { onPlayerChanged: once(onPlayerChanged) }),
+  };
   return createSessionGatedGameServices({
     // Configuration only (mode, target, whether a client exists); never sends a request.
     probe: createRuntime({ ...rest, playerId: 'session-pending' }, undefined),
     ensurePlayer: async () => (await signIn.ensure())?.playerId,
     onPlayer: (listener) => signIn.onSignedIn((signedIn) => listener(signedIn.playerId)),
-    create: (playerId) => createStarterGameServices({ ...rest, playerId }),
+    create: (playerId) => createStarterGameServices({ ...rest, playerId, ...hooks }),
     ...(onActivated === undefined ? {} : { onActivated }),
+    ...hooks,
   });
 }
 
@@ -94,6 +164,10 @@ function createRuntime(
   input: StarterGameServicesInput,
   session: ReturnType<typeof resolveStarterServerSession>,
 ): GameServicesRuntime {
+  const baseUrl = resolveGameServicesBaseUrl(import.meta.env.VITE_MPGD_GAME_SERVICES_URL, {
+    target: input.gateway.target,
+    ...(globalThis.location?.origin === undefined ? {} : { pageOrigin: globalThis.location.origin }),
+  });
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
@@ -107,10 +181,23 @@ function createRuntime(
     authorityMode: resolveGameServicesAuthorityMode(import.meta.env.MODE),
     target: import.meta.env.VITE_MPGD_GAME_SERVICES_TARGET ?? input.gateway.target,
     deploymentTarget: input.configTarget,
-    ...(import.meta.env.VITE_MPGD_GAME_SERVICES_URL === undefined
-      ? {}
-      : { baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL }),
+    ...(baseUrl === undefined ? {} : { baseUrl }),
     transport: resolveGameServicesTransport(import.meta.env.VITE_MPGD_GAME_SERVICES_TRANSPORT),
-    ...(session === undefined ? {} : { getHeaders: () => session.getHeaders() }),
+    // A store purchase bound to another player's account is left for that player.
+    // Only where the template binds purchases: elsewhere (Microsoft Store) nothing is compared.
+    ...(starterStoreAccountBindingKind(input.gateway.target) === undefined
+      ? {}
+      : {
+          commerceAccountBinding: () =>
+            resolveStarterStoreAccountBindingFor(input.gateway.target, input.playerId),
+        }),
+    ...(session === undefined
+      ? {}
+      : {
+          getHeaders: () => session.getHeaders(),
+          // Requests, the store account binding, and the journal follow this
+          // session's player; the services refuse while it is not theirs.
+          sessionPlayerId: () => session.current()?.playerId,
+        }),
   });
 }

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

@@ -59,9 +59,10 @@ export type StarterGuestIdentity =
  * place: that session cannot come back, and without a linked account its
  * player cannot either. Any other failure (offline, an outage) leaves the
  * stored token alone for the next attempt (`createStarterGuestSignIn`
- * retries), and until one succeeds purchases are refused with the reason
- * (`ACCOUNT_BINDING_REQUIRED` on Google Play, a StoreKit error naming the
- * missing session). One attempt: the game calls it through
+ * retries), and until one succeeds purchases are refused before the store
+ * opens with a `failed` result (`ACCOUNT_BINDING_REQUIRED`, store code
+ * `PLAY_BILLING_ACCOUNT_LOOKUP_FAILED` or `STOREKIT_ACCOUNT_LOOKUP_FAILED`
+ * when the lookup throws). One attempt: the game calls it through
  * `createStarterGuestSignIn`.
  */
 export async function startStarterGuestIdentity(input: {

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

@@ -1,6 +1,8 @@
 import {
+  isCommercePurchaseOperationRecord,
   isMonetizationOperationGranted,
   isMonetizationOperationRecoverable,
+  isParkedForAnotherAccount,
   type MonetizationOperationRecord,
   type MonetizationOperationStore,
 } from '@mpgd/game-services';
@@ -21,17 +23,55 @@ export const defaultMonetizationJournalRetentionMs = 30 * 24 * 60 * 60 * 1000;
  * age, or by the byte budget (`defaultMonetizationJournalMaxDocumentBytes`)
  * when the document would not fit, so the revocation pass and
  * `findByTransaction` keep them for the window whenever storage allows.
+ * Records parked as another account's purchase are the one kind of open
+ * record that leaves (`defaultMonetizationJournalParkedRetentionMs`).
  */
 export const defaultMonetizationJournalMaxTerminalRecords = 100;
+/**
+ * Records parked as another account's purchase (RFC "Another account's
+ * purchase") leave this long after their last write (30 days): the parking,
+ * or the player's last Restore Purchases resend. They are open records, but
+ * nothing of their player is in progress: the backend's answer granted and
+ * recorded nothing, and the store still holds the purchase for the account it
+ * is bound to, which recovers it under its own key. Dropping one cannot lose
+ * a grant: the backend ledger decides every grant, and a later verify of the
+ * same purchase finds a grant whose answer was lost. It costs one more verify
+ * that parks it again, if the store still lists the purchase and the client
+ * cannot tell its binding is another account's.
+ */
+export const defaultMonetizationJournalParkedRetentionMs = 30 * 24 * 60 * 60 * 1000;
+/**
+ * At most this many parked records are kept across every player of the
+ * install, the most recently written first. A purchase dropped by this bound
+ * that the store keeps listing is verified again by the next pass that meets
+ * it, as an older client resends every such purchase. The byte budget may
+ * drop parked records before granted purchases. Neither drops a record in
+ * the in-flight window (`parkedInFlightMs`).
+ */
+export const defaultMonetizationJournalMaxParkedRecords = 20;
+/**
+ * The default in-flight window (10 minutes, the reconciler's
+ * `defaultInFlightTimeoutMs`): a parked record written this recently, or
+ * later than now (a clock moved back), is kept through every bound. A
+ * Restore Purchases resend rewrites its record before it is sent, in this
+ * context or another tab's, and the record must still be there when the
+ * backend answers. The parked record this journal wrote last is kept too. A
+ * parked record without a readable time is never in flight.
+ */
+export const defaultMonetizationJournalParkedInFlightMs = 10 * 60 * 1000;
 /**
  * Upper bound of the serialized document (192 KiB, below the Devvit bridge's
  * 256 KiB per value). When the records in the window would exceed it, the
  * oldest terminal records leave first: ungranted ones without a store
- * transaction, then ungranted ones that still name a store transaction, then
- * granted purchases. Open records are never dropped.
+ * transaction, then ungranted ones that still name a store transaction and
+ * parked records (except one that may be in flight), then granted purchases.
+ * Other open records are never dropped.
  */
 export const defaultMonetizationJournalMaxDocumentBytes = 192 * 1024;
 
+/** The time of a parked record without a readable one: newest in sort order, never in flight. */
+const unreadableParkedTime = Number.MAX_SAFE_INTEGER;
+
 export interface CreateStorageMonetizationOperationStoreInput {
   /** The platform storage adapter (`gateway.storage`); the host owns its durability. */
   readonly storage: StorageAdapter;
@@ -43,6 +83,18 @@ export interface CreateStorageMonetizationOperationStoreInput {
   readonly maxTerminalRecords?: number;
   /** Defaults to 192 KiB of serialized JSON; see `defaultMonetizationJournalMaxDocumentBytes`. */
   readonly maxDocumentBytes?: number;
+  /** Defaults to 30 days; see `defaultMonetizationJournalParkedRetentionMs`. */
+  readonly parkedRetentionMs?: number;
+  /** Defaults to 20 parked records; see `defaultMonetizationJournalMaxParkedRecords`. */
+  readonly maxParkedRecords?: number;
+  /**
+   * Defaults to 10 minutes; see `defaultMonetizationJournalParkedInFlightMs`.
+   * A game that changes the reconciler's `inFlightTimeoutMs`
+   * (`createCommerceReconciler`) passes the same value here, so a parked
+   * record stays in the journal for as long as its Restore Purchases answer
+   * may be awaited.
+   */
+  readonly parkedInFlightMs?: number;
   readonly now?: () => number;
   /**
    * Cross-context lock for the read-modify-write of the document; defaults to
@@ -67,7 +119,8 @@ interface JournalDocument {
  * The reference durable `MonetizationOperationStore` of the starter: one JSON
  * document in the platform storage adapter, rewritten whole on every change
  * so a record and its index can never disagree, terminal records bounded by
- * age (and, without a ledger grant, by count; open records are always kept),
+ * age (and, without a ledger grant, by count; open records are kept, except
+ * records parked as another account's purchase, bounded by age and count),
  * with every operation
  * serialized through one promise chain so the compare-and-swap of `replace`
  * holds inside the WebView. It is crash recovery, not grant authority: the
@@ -87,10 +140,26 @@ export function createStorageMonetizationOperationStore(
   const maxTerminalRecords = input.maxTerminalRecords
     ?? defaultMonetizationJournalMaxTerminalRecords;
   const maxDocumentBytes = input.maxDocumentBytes ?? defaultMonetizationJournalMaxDocumentBytes;
+  const parkedRetentionMs = input.parkedRetentionMs ?? defaultMonetizationJournalParkedRetentionMs;
+  const parkedLimit = input.maxParkedRecords ?? defaultMonetizationJournalMaxParkedRecords;
+  const maxParkedRecords = parkedLimit >= 0 ? parkedLimit : 0;
+  const parkedInFlightMs = input.parkedInFlightMs ?? defaultMonetizationJournalParkedInFlightMs;
   const now = input.now ?? (() => Date.now());
   const locks = input.locks === undefined ? readHostLockManager() : (input.locks ?? undefined);
   const lockName = `mpgd-monetization-journal:${key}`;
   let chain: Promise<unknown> = Promise.resolve();
+  /**
+   * The parked record this journal wrote last: a Restore Purchases resend
+   * rewrites its record before it is sent, so this is the one whose answer
+   * may be awaited. No bound drops it, whatever its time says.
+   */
+  let lastWrittenParked: string | undefined;
+  const noteWrite = (record: MonetizationOperationRecord): void => {
+    const writtenAt = parkedWrittenAt(record);
+    if (writtenAt !== undefined && writtenAt !== unreadableParkedTime) {
+      lastWrittenParked = record.key;
+    }
+  };
 
   const serialize = <T>(operation: () => Promise<T>): Promise<T> => {
     const run = locks === undefined ? operation : () => locks.request(lockName, () => operation());
@@ -113,11 +182,34 @@ export function createStorageMonetizationOperationStore(
 
   const save = async (records: Map<string, MonetizationOperationRecord>): Promise<void> => {
     const cutoff = now() - retentionMs;
+    const parkedCutoff = now() - parkedRetentionMs;
     const terminal: [string, number][] = [];
+    const parked: [string, number][] = [];
     const kept: Record<string, MonetizationOperationRecord> = {};
-    /** Terminal records the byte budget may drop, with their drop tier (lower leaves first). */
+    /** Records the byte budget may drop, with their drop tier (lower leaves first). */
     const droppable: [string, number, number][] = [];
+    const inFlightSince = now() - parkedInFlightMs;
+    let inFlight = 0;
     for (const [recordKey, record] of records) {
+      const parkedAt = parkedWrittenAt(record);
+      if (
+        parkedAt !== undefined
+        && parkedAt !== unreadableParkedTime
+        && (recordKey === lastWrittenParked || parkedAt >= inFlightSince)
+      ) {
+        // Possibly awaiting a Restore Purchases answer: no bound drops it.
+        kept[recordKey] = record;
+        inFlight += 1;
+        continue;
+      }
+      if (parkedAt !== undefined) {
+        // Another account's purchase: nothing of this player is in progress,
+        // and the purchase's own account recovers it under its own key.
+        if (parkedAt >= parkedCutoff) {
+          parked.push([recordKey, parkedAt]);
+        }
+        continue;
+      }
       const settledAt = terminalSettledAt(record);
       if (settledAt === undefined) {
         kept[recordKey] = record;
@@ -135,6 +227,18 @@ export function createStorageMonetizationOperationStore(
         terminal.push([recordKey, settledAt]);
       }
     }
+    // Newest first; the records kept as in flight count against the bound.
+    parked.sort((left, right) => right[1] - left[1]);
+    for (const [recordKey, writtenAt] of parked.slice(
+      0,
+      Math.max(0, maxParkedRecords - inFlight),
+    )) {
+      const record = records.get(recordKey);
+      if (record !== undefined) {
+        kept[recordKey] = record;
+        droppable.push([recordKey, writtenAt, 1]);
+      }
+    }
     // Newest first; the oldest terminal records beyond the bound are dropped.
     terminal.sort((left, right) => right[1] - left[1]);
     for (const [recordKey, settledAt] of terminal.slice(0, Math.max(0, maxTerminalRecords))) {
@@ -146,7 +250,7 @@ export function createStorageMonetizationOperationStore(
     }
     // The document must fit the host's per-value limit, or every later write
     // fails and monetization stops: the oldest record of the lowest tier leaves
-    // until it fits. Open records are never dropped.
+    // until it fits. Open records other than parked ones are never dropped.
     droppable.sort((left, right) => left[2] - right[2] || left[1] - right[1]);
     let size = documentBytes(kept);
     for (const [recordKey] of droppable) {
@@ -169,6 +273,7 @@ export function createStorageMonetizationOperationStore(
           return { created: false, record: clone(existing) };
         }
         records.set(record.key, clone(record));
+        noteWrite(record);
         await save(records);
         return { created: true, record: clone(record) };
       });
@@ -195,6 +300,7 @@ export function createStorageMonetizationOperationStore(
           throw new Error('Stale or conflicting monetization journal write.');
         }
         records.set(record.key, clone(record));
+        noteWrite(record);
         await save(records);
       });
     },
@@ -245,6 +351,22 @@ function terminalSettledAt(record: MonetizationOperationRecord): number | undefi
   return Number.isFinite(time) ? time : Number.MAX_SAFE_INTEGER;
 }
 
+/**
+ * When a record parked as another account's purchase was last written (its
+ * parking, or a Restore Purchases resend), or `undefined` for any other
+ * record. A parked record without a readable time is never in flight and
+ * sorts as the newest: only the count bound and the byte budget drop it.
+ */
+function parkedWrittenAt(record: MonetizationOperationRecord): number | undefined {
+  if (!isCommercePurchaseOperationRecord(record) || !isParkedForAnotherAccount(record)) {
+    return undefined;
+  }
+  const times = [record.updatedAt, record.anotherAccount?.reportedAt]
+    .map((time) => (time === undefined ? Number.NaN : Date.parse(time)))
+    .filter((time) => Number.isFinite(time));
+  return times.length === 0 ? unreadableParkedTime : Math.max(...times);
+}
+
 /** A commerce purchase record that names a store transaction (the store may still list it). */
 function holdsStoreTransaction(record: MonetizationOperationRecord): boolean {
   return record.kind === 'commerce-purchase' && record.purchase?.transactionId !== undefined;

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

@@ -1,20 +1,22 @@
-import type {
-  GameServicesClient,
-  GameServicesPurchaseResult,
-  GameServicesRewardedAdResult,
-  GameServicesRuntime,
+import {
+  gameServicesPlayerChangedCode,
+  gameServicesRuntimeDisposedCode,
+  type GameServicesClient,
+  type GameServicesPurchaseResult,
+  type GameServicesRewardedAdResult,
+  type GameServicesRuntime,
 } from '@mpgd/game-services';
 
 /** The diagnostic of a purchase refused because the run is not signed in yet (retryable). */
 export const starterSessionRequiredCode = 'STARTER_SESSION_REQUIRED';
 
-function sessionRequiredPurchase(): GameServicesPurchaseResult {
+function refusedPurchase(code: string): GameServicesPurchaseResult {
   return {
     status: 'failed',
     purchase: {
       status: 'failed',
       entitlementIds: [],
-      diagnostic: { code: starterSessionRequiredCode, retryable: true },
+      diagnostic: { code, retryable: true },
     },
   };
 }
@@ -25,11 +27,16 @@ function sessionRequiredReward(): GameServicesRewardedAdResult {
 
 /** A purchase, restore, or reward claim was asked for before the guest sign-in succeeded. */
 export class StarterSessionRequiredError extends Error {
-  readonly code = 'STARTER_SESSION_REQUIRED';
+  readonly code: string;
 
-  constructor() {
-    super('The game is not signed in to its identity service yet; try again when it is online.');
+  constructor(code: string = starterSessionRequiredCode) {
+    super(
+      code === starterSessionRequiredCode
+        ? 'The game is not signed in to its identity service yet; try again when it is online.'
+        : 'Another player signed in; the game restarts for that player.',
+    );
     this.name = 'StarterSessionRequiredError';
+    this.code = code;
   }
 }
 
@@ -69,8 +76,14 @@ export type StarterSessionGatedServices = GameServicesRuntime & {
  *   runtime binds its late reward evidence recovery at boot.
  * - When the player becomes known, the services are created once; the
  *   caller runs the game runtime's `reconcile()` from `onActivated` (the
- *   startup recovery, with the action coordinator's). A later sign-in naming another player
- *   (not expected within one run) is ignored with a warning.
+ *   startup recovery, with the action coordinator's). A later sign-in naming
+ *   another player (not expected within one run) closes them for good, as
+ *   the services' own session check does: purchases answer `failed` with the
+ *   retryable diagnostic `GAME_SERVICES_PLAYER_CHANGED`, recovery and Delete
+ *   account go away, and `onPlayerChanged` asks the host to boot again for
+ *   that player once the old services stopped. They are never re-created
+ *   for the new player inside this run: the scenes, the action coordinator,
+ *   and the notifications still hold the boot player.
  * - `accountDeletion` is `undefined` until then, and the services' after
  *   (read live); `onReady` tells Delete account to appear then.
  * - `ensureSession` is present only when the configuration has a client
@@ -90,19 +103,39 @@ export function createSessionGatedGameServices(input: {
    * one a purchase or restore started): run the game runtime's `reconcile()`.
    */
   readonly onActivated?: () => void;
+  /** Called at once when a later sign-in names another player: block input or show a switching screen. */
+  readonly onPlayerChanging?: (playerId: string) => void;
+  /** Called once, after a sign-in named another player closed the services: boot again for it. */
+  readonly onPlayerChanged?: (playerId: string) => void;
   readonly warn?: (message: string, error?: unknown) => void;
 }): StarterSessionGatedServices {
   const warn = input.warn ?? ((message: string, error?: unknown) => console.warn(message, error ?? ''));
   let inner: GameServicesRuntime | undefined;
   let innerPlayer: string | undefined;
+  /** Set once another player signed in, or the services were disposed: nothing comes up again. */
+  let closedCode: string | undefined;
   const readyListeners = new Set<() => void>();
+  /** The services the scenes may use now: none once closed. */
+  const live = (): GameServicesRuntime | undefined => (closedCode === undefined
+    ? inner
+    : undefined);
 
   const activate = (playerId: string): void => {
+    if (closedCode !== undefined) {
+      return;
+    }
     if (inner !== undefined) {
       if (playerId !== innerPlayer) {
+        closedCode = gameServicesPlayerChangedCode;
+        readyListeners.clear();
         warn(
-          '[game-services] a later sign-in named another player; the services keep the first until restart.',
+          '[game-services] a later sign-in named another player; the services closed until restart.',
         );
+        notifyChanging(input.onPlayerChanging, playerId, warn);
+        // Fail closed first; the host restarts once the old reconciler has stopped.
+        void inner.dispose().catch((error: unknown) => {
+          warn('[game-services] the services could not be closed cleanly', error);
+        }).finally(() => input.onPlayerChanged?.(playerId));
       }
       return;
     }
@@ -132,16 +165,17 @@ export function createSessionGatedGameServices(input: {
   input.onPlayer(activate);
 
   const ready = async (): Promise<GameServicesRuntime> => {
-    if (inner === undefined) {
+    if (inner === undefined && closedCode === undefined) {
       const playerId = await input.ensurePlayer();
       if (playerId !== undefined) {
         activate(playerId);
       }
     }
-    if (inner === undefined) {
-      throw new StarterSessionRequiredError();
+    const services = live();
+    if (services === undefined) {
+      throw new StarterSessionRequiredError(closedCode);
     }
-    return inner;
+    return services;
   };
   const readyClientOrUndefined = async (): Promise<GameServicesClient | undefined> => {
     try {
@@ -166,7 +200,9 @@ export function createSessionGatedGameServices(input: {
     client = {
       purchase: async (purchase, options) => {
         const ready = await readyClientOrUndefined();
-        return ready === undefined ? sessionRequiredPurchase() : ready.purchase(purchase, options);
+        return ready === undefined
+          ? refusedPurchase(closedCode ?? starterSessionRequiredCode)
+          : ready.purchase(purchase, options);
       },
       claimRewardedAd: async (reward, options) => {
         const ready = await readyClientOrUndefined();
@@ -177,7 +213,7 @@ export function createSessionGatedGameServices(input: {
     // Read live: the reconciler of the services created after sign-in.
     Object.defineProperty(client, 'commerceReconciler', {
       enumerable: true,
-      get: () => inner?.client?.commerceReconciler,
+      get: () => live()?.client?.commerceReconciler,
     });
   }
 
@@ -205,13 +241,105 @@ export function createSessionGatedGameServices(input: {
             }
           },
         }),
+    async dispose() {
+      closedCode ??= gameServicesRuntimeDisposedCode;
+      readyListeners.clear();
+      await inner?.dispose();
+    },
   } as StarterSessionGatedServices;
   // Read live: `undefined` until the player is known, so rewarded ads stay off until then,
   // and Delete account appears once there is an account (the lobby's next visit).
   Object.defineProperties(services, {
     mode: { enumerable: true, get: () => inner?.mode ?? input.probe.mode },
-    monetizationRecovery: { enumerable: true, get: () => inner?.monetizationRecovery },
-    accountDeletion: { enumerable: true, get: () => inner?.accountDeletion },
+    monetizationRecovery: { enumerable: true, get: () => live()?.monetizationRecovery },
+    accountDeletion: { enumerable: true, get: () => live()?.accountDeletion },
   });
   return services;
 }
+
+/**
+ * Closes `services` once the server session names another player than
+ * `playerId` (an account switch within the run): `onPlayerChanging` hears it
+ * at once (the runtime's own `sessionPlayerId` check already refuses every
+ * request from that moment; block input or show a switching screen), then
+ * the services are disposed (an open store sheet first journals its answer)
+ * and `onPlayerChanged` asks the host to restart for that player. Services
+ * created for another player than the session's current one stay closed,
+ * which `warn` reports. `onDisposed` runs once, after the services were
+ * disposed either way (the store binding pin is released there).
+ * `dispose()` also stops watching.
+ */
+export function bindStarterServicesToPlayer(input: {
+  readonly services: GameServicesRuntime;
+  readonly playerId: string;
+  readonly session: {
+    current(): { readonly playerId: string } | undefined;
+    onAuthenticated(listener: (session: { readonly playerId: string }) => void): () => void;
+  };
+  readonly onPlayerChanging?: (playerId: string) => void;
+  readonly onPlayerChanged?: (playerId: string) => void;
+  readonly onDisposed?: () => void;
+  readonly warn?: (message: string, error?: unknown) => void;
+}): GameServicesRuntime {
+  const warn = input.warn ?? ((message: string, error?: unknown) => console.warn(message, error ?? ''));
+  const { services } = input;
+  const current = input.session.current()?.playerId;
+  const createdForAnother = current !== undefined && current !== input.playerId;
+  let closing: Promise<void> | undefined;
+  const close = (): Promise<void> => {
+    closing ??= services.dispose().catch((error: unknown) => {
+      warn('[game-services] the services could not be closed cleanly', error);
+    }).finally(() => input.onDisposed?.());
+    return closing;
+  };
+  let changed = false;
+  /** The unsubscribe, once `onAuthenticated` returned it. */
+  const watching: { stop?: () => void } = {};
+  const onSession = (next: { readonly playerId: string }): void => {
+    if (changed || next.playerId === input.playerId) {
+      return;
+    }
+    changed = true;
+    watching.stop?.();
+    notifyChanging(input.onPlayerChanging, next.playerId, warn);
+    void close().finally(() => input.onPlayerChanged?.(next.playerId));
+  };
+  if (createdForAnother) {
+    // Created for another player than the session's (a local placeholder):
+    // closed at once and the pin released, so services for the session's
+    // player can be created. No restart: the host that created these would
+    // create them the same way again.
+    changed = true;
+    warn(
+      "[game-services] created for a player that is not the server session's; they are closed. "
+        + "Create them with the session's player.",
+    );
+    void close();
+  } else {
+    watching.stop = input.session.onAuthenticated(onSession);
+    if (changed) {
+      // The session announced another player while subscribing.
+      watching.stop();
+    }
+  }
+  return {
+    ...services,
+    async dispose() {
+      watching.stop?.();
+      await close();
+    },
+  };
+}
+
+/** Tells the host at once that another player signed in; a throwing callback is only reported. */
+function notifyChanging(
+  callback: ((playerId: string) => void) | undefined,
+  playerId: string,
+  warn: (message: string, error?: unknown) => void,
+): void {
+  try {
+    callback?.(playerId);
+  } catch (error) {
+    warn('[game-services] the player change callback failed', error);
+  }
+}

package/templates/phaser-game/src/styles.css

@@ -61,3 +61,15 @@ canvas {
   font-size: 16px;
   line-height: 1.5;
 }
+
+.player-switch {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgb(0 0 0 / 70%);
+  color: #f8fafc;
+  font-size: 18px;
+}