@mpgd/adapter-capacitor 0.4.12 → 0.6.0

package/README.md

@@ -0,0 +1,318 @@
+# @mpgd/adapter-capacitor
+
+The base adapter uses `@mpgd/capacitor-game-services` for bounded local JSON
+storage and a small fail-closed bridge. It does **not** install a store, ad,
+identity, leaderboard, or push SDK. Pass separately installed modules through
+`createCapacitorPlatformGateway({ providers })`; each module declares its
+owned bridge methods, provider features, and current availability. Duplicate
+method/feature registrations and attempts to replace base storage are errors.
+
+```ts
+import {
+  createCapacitorPlatformGateway,
+  type CapacitorServiceProvider,
+} from '@mpgd/adapter-capacitor';
+
+export function createGameGateway(providers: readonly CapacitorServiceProvider[]) {
+  return createCapacitorPlatformGateway({
+    target: 'android',
+    appVersion: '1.0.0',
+    buildId: 'game-build',
+    providers,
+    classifyIncomingUrl(url) {
+      const incoming = new URL(url);
+      // Replace this example scheme with one registered by your native host.
+      if (incoming.protocol !== 'mygame:') return null;
+      if (incoming.hostname === 'oauth') return 'oauth';
+      if (incoming.hostname === 'game') return 'game';
+      return null;
+    },
+  });
+}
+```
+
+`getCapabilities()` reports a fresh boolean snapshot and optional
+`providerAvailability` detail. The possible states are `unsupported`,
+`configuration-required`, `action-required`, `temporarily-unavailable`, and
+`available`. A target's `features` configuration is an upper bound, **not**
+proof that a provider is installed or ready. `nativeIap` describes one-time
+purchases; `subscriptionIap` is separate. Rewarded, interstitial, and banner
+ads and native versus remote leaderboards remain distinct. Target-config
+applies the configured upper bound to this live provider state.
+
+When native and remote leaderboard routes coexist, the target-config wrapper
+selects a `route` on score/open calls; direct adapter callers can request
+`route: 'remote'` to use the base remote bridge instead of the native provider.
+When one ads provider handles multiple formats, pass `format` to `ads.preload`
+so its readiness check cannot use an available format for an unavailable one.
+
+Provider initialization failures and availability reads stalled beyond three
+seconds leave the base bridge and local guest boot available. A registered
+provider never silently falls back for purchase, ad, or native leaderboard
+operations; an explicit remote leaderboard route is a separate path. Errors
+retain a stable code and retry hint. The
+provider bridge must return a method-shaped response. In particular, an ad
+`rewardGranted: true` result requires a backend ledger entry. The AdMob SDK
+provider always returns `rewardGranted: false`, even after the SDK fires a
+reward callback. Its explicitly non-authoritative evidence envelope only lets
+the game-services client request a grant; the server must independently verify
+a signed SSV callback before writing its ledger. A native callback alone is
+never a grant. Game-specific product, consent, entitlement, and
+identity policy belongs to the consuming game and its backend.
+
+The source tests and installed-tarball consumer validate composition, types,
+error paths, and fallback behavior. They do not establish that any optional
+SDK works on a physical device or that a store/ad setup is release-ready.
+
+## App Store server-side transaction signatures
+
+For an iOS game backend, install the optional
+`@apple/app-store-server-library@3.1.0` peer and import
+`createAppleSignedTransactionVerifier` from
+`@mpgd/adapter-capacitor/app-store-server`. Supply DER-encoded Apple root
+certificates from the [Apple PKI](https://www.apple.com/certificateauthority/),
+the game's bundle ID, environment, and production App Apple ID. Use the
+result as `signedTransactionVerifier` in
+`createAppStoreGameServicesEvidenceVerifier`. Keep App Store API credentials,
+trust roots, and this verifier on the backend, not in the Capacitor game.
+
+The server fetches the transaction from Apple's API, verifies its JWS, checks
+the product, bundle, environment, account token and transaction ID, then
+writes the game-services grant. A StoreKit device callback is only provisional
+evidence; it never grants a product. Retryable certificate-status failures
+remain pending, while invalid signatures are rejected. Mock verification does
+not prove a real App Store purchase or device delivery.
+
+## Opt-in AdMob rewarded ads
+
+Install `@capacitor-community/admob@8.1.0` in the game-owned Capacitor project,
+configure the distinct AdMob **application ID** in AndroidManifest.xml and
+Info.plist, and run `cap sync`. Use the [plugin installation and native setup
+guide](https://github.com/capacitor-community/admob#installation) for the exact
+Android and iOS keys, SKAdNetwork list, and tracking disclosure. The optional
+`@mpgd/adapter-capacitor/admob` subpath does not load from the base adapter;
+games that do not install AdMob retain their existing SDK-free gateway.
+The community plugin currently targets Google Mobile Ads Android 25.4.x and
+iOS 13.6.0. Its Android default uses a dynamic patch selector; set
+`playServicesAdsVersion = '25.4.0'` in the game-owned `variables.gradle` to
+keep release builds reproducible until the plugin adopts a newer tested SDK.
+
+```ts
+import { createCapacitorPlatformGateway } from '@mpgd/adapter-capacitor';
+import { createCapacitorAdMobRewardedProvider } from '@mpgd/adapter-capacitor/admob';
+
+const admob = createCapacitorAdMobRewardedProvider({
+  adUnits: { CONTINUE_AFTER_FAIL: 'ca-app-pub-1234567890123456/1234567890' },
+  getPlayerId: () => authenticatedPlayerId,
+});
+const gateway = createCapacitorPlatformGateway({
+  target: 'android', appVersion: '1.0.0', buildId: 'game-build',
+  providers: [admob],
+});
+const consentAllowsAds = await admob.requestConsent();
+if (!consentAllowsAds) {
+  // Keep the ad action disabled; never bypass the privacy choice.
+}
+```
+
+Use target-specific ad unit IDs for Android and iOS; the logical placement
+ID must match the game catalog and backend config. `getPlayerId()` must return
+the same authenticated player ID as `GameServicesClient`, not a device ID or
+an unverified local guest label. Re-check consent when the game resumes or
+the privacy choice changes, and expose `admob.showPrivacyOptions()` from game
+settings where required. `getCapabilities()` reports `action-required` until
+consent is ready and `temporarily-unavailable` during a show. A timed-out
+native load or presentation reports non-retryable `action-required` and
+quarantines that SDK instance to avoid overlapping shows
+while its state is unknown. Recreating the Kit provider with the same SDK does
+not clear the quarantine; restart the native app before trying again. Do not
+show rewarded ads through another direct SDK caller concurrently: the plugin's
+reward and dismissal events are global, not tagged with a Kit operation ID.
+
+`gateway.ads.preload()` validates the logical placement but deliberately does
+not load an ad: this SDK attaches SSV data at load time, whereas the Kit's
+operation ID exists only at show time. `gateway.ads.showRewarded()` therefore
+loads a fresh ad with SSV `userId` and encoded player/placement/operation
+binding, waits for native dismissal, then returns SDK reward evidence. Call
+`GameServicesClient.claimRewardedAd()` rather than award currency from that
+result; `rewardGranted` remains `false` in that provisional platform result.
+If dismissal arrives without an observed reward, the provider returns
+`pending` with the same non-authoritative binding. The backend can then look
+for a later signed SSV callback without replaying the ad UI; a genuinely
+skipped ad may remain pending until game-owned support or expiry policy
+settles it. Mediation and asynchronous bridge delivery have no safe universal
+250 ms reward-event cutoff.
+The receiver and ledger described in [AdMob SSV](../../docs/ADMOB_SSV.md)
+remain mandatory. A late SSV callback can leave the claim pending for
+reconciliation. `isTesting: true` is for SDK test ads only; [the plugin notes
+that test ads do not invoke the SSV endpoint](https://github.com/capacitor-community/admob/blob/main/docs/rewarded.md#server-side-verification),
+so they cannot prove a production grant.
+
+The Kit tests cover consent, per-operation binding, reward versus dismissal,
+and bridge contracts with an injected SDK. They are not evidence of a real
+AdMob account, live callback delivery, native device behavior, or store policy
+approval.
+
+`gateway.secureCredentials` uses dedicated native Keychain/Keystore methods for
+opaque session credentials. Its absence or a native error must not be hidden by
+writing the secret into `gateway.storage`. Keys are bounded, values are
+size-limited, and malformed bridge responses fail closed. This is a storage
+boundary, not proof of server authentication: an installation ID or local
+`playerId` is never a server principal by itself.
+
+## App lifecycle and native entry
+
+The adapter uses the official Capacitor App plugin for foreground state,
+Android back navigation, and incoming URLs. Install `@capacitor/app` in the
+native shell and run `cap sync` so the native plugin is present. The reference
+shell and generated game template include it. A `classifyIncomingUrl` callback
+must explicitly return `game` or `oauth`; unknown URLs are discarded rather
+than being delivered to gameplay. Register your URL scheme or App/Universal
+Links in the native host separately. See the [Capacitor App API](https://capacitorjs.com/docs/apis/app).
+
+`lifecycle.onPause` and `onResume` deduplicate App and web visibility events.
+Purchases, ads, and identity upgrades keep execution paused until their
+provider operation settles. Use `beginExternalActivity` for other external UI.
+On Android, a back handler returns `true` if the game consumed the event;
+otherwise the adapter navigates browser history when possible or exits the
+app. Cold URLs are read through `getInitialGameUrl` or
+`getInitialOAuthRedirect`; warm URLs use separate `onGameUrlOpen` and
+`onOAuthRedirect` callbacks. OAuth responses never enter the game-link
+callback. Call `lifecycle.dispose()` when the host tears down this gateway;
+the adapter removes only its own listener handles, never every App listener.
+
+Save progress at checkpoints and transaction boundaries. A pause callback can
+request a best-effort save, but neither pause nor back is guaranteed to run
+before the operating system terminates a process. The lifecycle tests use an
+injected App API and do not claim device-level lifecycle verification.
+
+For example, let the game's checkpoint flow own durability; the native pause
+event is only an additional opportunity to flush the latest checkpoint:
+
+```ts
+import type { PlatformGateway } from '@mpgd/platform';
+
+export function attachCheckpointSaving(
+  gateway: PlatformGateway,
+  saveCheckpoint: () => Promise<void>,
+): () => void {
+  return gateway.lifecycle.onPause(() => {
+    void saveCheckpoint().catch((error: unknown) => {
+      console.error('Best-effort pause save failed.', error);
+    });
+  });
+}
+
+// The game also awaits saveCheckpoint() at level and transaction boundaries;
+// it must never defer its only save until a close, back, or pause event.
+```
+
+## Scoped native JSON HTTP
+
+`createCapacitorNativeJsonTransport` uses the explicit `CapacitorHttp.request`
+helper from `@capacitor/core`; it does not enable global `fetch` or XHR patching.
+Use it with the HTTP JSON path of `createGameServicesRuntime`, not the oRPC
+path. The game imports only public kit APIs:
+
+```ts
+import { createCapacitorNativeJsonTransport } from '@mpgd/adapter-capacitor';
+import { createGameServicesRuntime } from '@mpgd/game-services/runtime';
+
+const baseUrl = 'https://api.example.com';
+const httpTransport = createCapacitorNativeJsonTransport({
+  target: 'android',
+  baseUrl,
+  allowedOrigin: 'https://api.example.com',
+});
+const runtime = createGameServicesRuntime({
+  gateway,
+  playerId,
+  authorityMode: 'production',
+  baseUrl,
+  transport: 'http',
+  httpTransport,
+  getHeaders: () => ({ authorization: `Bearer ${currentAccessToken()}` }),
+});
+```
+
+The game supplies its real gateway, player ID, and token resolver. The native
+transport permits only its configured HTTPS origin and relative JSON API paths;
+it rejects 3xx responses and changed routes while tolerating equivalent native
+URL encoding of the same path or query. It requests
+`disableRedirects: true` from Capacitor. A native implementation that ignored
+that option could have followed a redirect before JS sees the result, so
+redirect and credential handling still require native integration testing.
+The transport owns `Accept: application/json` and POST `Content-Type`; callers
+supplying either header are rejected instead of having it silently rewritten.
+It supports GET and POST JSON only, not streaming, file uploads, or arbitrary
+Fetch semantics. `AbortSignal` and the overall timeout stop the
+JS wait; they do **not** prove the native request or server operation was
+canceled. Reconcile purchases and reward claims before retrying them.
+
+Request size is checked before calling the native bridge. The response size
+limit is checked **after** Capacitor returns data to JS; it is not a native
+receive-memory cap. The injected Http tests and platform staging builds cover
+the contract, not real network behavior on both physical OSes. See the
+[Capacitor HTTP API](https://capacitorjs.com/docs/apis/http) for the native
+helper and its redirect/timeout options.
+
+## Usable viewport and native occupied surfaces
+
+`gateway.viewport` reports the full WebView size and separate safe-area,
+system-bar, keyboard, and named occupied-surface measurements in **CSS pixels**.
+Pass the state to `resolveTargetViewportUsableArea` from `@mpgd/target-config`;
+it takes the furthest intrusion per edge rather than summing overlapping
+safe-area, system-bar, keyboard, and banner values. The default host reads the
+starter's `--mpgd-safe-area-*` CSS variables, Capacitor SystemBars'
+`--safe-area-inset-*` fallback, and `visualViewport` changes. On Android,
+SystemBars injects fallback CSS variables for older WebViews whose CSS `env`
+safe-area values are incorrect. The injected `--safe-area-inset-*` values must
+be valid CSS lengths on `documentElement` (`:root`); putting them only on
+`body` or a nested container does not update the root aliases. See the
+[SystemBars API](https://capacitorjs.com/docs/apis/system-bars).
+Keyboard behavior also depends on the native [Keyboard resize mode](https://capacitorjs.com/docs/apis/keyboard),
+so inspect the actual device layout before promising a particular inset.
+
+Choose **one layout owner**. The starter's existing CSS padding already
+reserves safe-area space; do not apply `usableArea.contentBounds` to that
+already-padded `#game` element. For a JS-owned full-viewport canvas and DOM
+overlay, remove the host's safe-area padding and apply the same rectangle to
+both elements:
+
+```ts
+import { resolveTargetViewportUsableArea } from '@mpgd/target-config';
+import type { PlatformGateway } from '@mpgd/platform';
+
+export function mountUsableViewport(
+  gateway: PlatformGateway,
+  canvasHost: HTMLElement,
+  overlayHost: HTMLElement,
+): () => void {
+  const viewport = gateway.viewport;
+  if (viewport === undefined) return () => undefined;
+  const apply = () => {
+    const state = viewport.getState();
+    const bounds = resolveTargetViewportUsableArea(state, state).contentBounds;
+    for (const element of [canvasHost, overlayHost]) {
+      element.style.position = 'absolute';
+      element.style.left = `${bounds.x}px`;
+      element.style.top = `${bounds.y}px`;
+      element.style.width = `${bounds.width}px`;
+      element.style.height = `${bounds.height}px`;
+    }
+  };
+  apply();
+  return viewport.onChange(apply);
+}
+
+// Call the returned unsubscribe during game teardown. lifecycle.dispose()
+// tears down the gateway-owned native viewport listeners.
+```
+
+Future banner providers can call `createCapacitorViewport()` and pass that
+controller to `createCapacitorPlatformGateway({ viewport })`, then report
+actual `surfaceId` bounds with `setOccupiedSurface`. For physical-pixel
+measurements, the provider supplies `pixelsPerCssPixel`; the game never guesses
+device pixel ratio. A caller-injected controller remains caller-owned and must
+be disposed separately. Tests cover layout, rotation, multiple surfaces, and
+unsubscribe, but do not establish physical-device inset or keyboard accuracy.

package/dist/admob.d.ts

@@ -0,0 +1,26 @@
+import { type AdMobPlugin } from '@capacitor-community/admob';
+import type { CapacitorServiceProvider } from './providers.js';
+/** Only the AdMob subpath imports the optional native SDK. */
+export type RewardedAdMobSdk = Pick<AdMobPlugin, 'initialize' | 'requestConsentInfo' | 'showConsentForm' | 'showPrivacyOptionsForm' | 'prepareRewardVideoAd' | 'showRewardVideoAd' | 'addListener'>;
+export interface CreateCapacitorAdMobRewardedProviderInput {
+  /** Logical placement IDs mapped to target-specific, game-owned AdMob ad units. */
+  readonly adUnits: Readonly<Record<string, string>>;
+  /** Must resolve to the same authenticated player ID used by GameServicesClient. */
+  readonly getPlayerId: () => Promise<string> | string;
+  /** Test ads do not send Google SSV callbacks; server grants remain pending. */
+  readonly isTesting?: boolean;
+  readonly sdk?: RewardedAdMobSdk;
+  readonly showTimeoutMs?: number;
+}
+export interface CapacitorAdMobRewardedProvider extends CapacitorServiceProvider {
+  /** Present UMP when required. Call before the gateway advertises ad readiness. */
+  requestConsent(): Promise<boolean>;
+  /** Game settings should expose this when the privacy message requires it. */
+  showPrivacyOptions(): Promise<void>;
+}
+/**
+* Opt-in rewarded-only provider. The SDK's SSV options are attached when an
+* operation is shown, never to an earlier unbound preload. A local reward
+* callback is only a signal to ask the backend; it is not a ledger grant.
+*/
+export declare function createCapacitorAdMobRewardedProvider(input: CreateCapacitorAdMobRewardedProviderInput): CapacitorAdMobRewardedProvider;

package/dist/admob.js

@@ -0,0 +1,288 @@
+import { AdMob, AdmobConsentStatus, RewardAdPluginEvents, } from '@capacitor-community/admob';
+import { admobClientRewardEvidenceSchema } from '@mpgd/game-services/admob-client-reward';
+import { admobSsvMaximumBindingFieldLength, encodeAdMobSsvCustomData, } from '@mpgd/game-services/admob-ssv';
+const unitPattern = /^ca-app-pub-\d+\/\d+$/u;
+const defaultShowTimeoutMs = 180_000;
+const loadTimeoutMs = 30_000;
+const preflightTimeoutMs = 10_000;
+const listenerCleanupTimeoutMs = 1_000;
+const maximumCustomDataBytes = 1_024;
+// The native plugin's rewarded event stream and prepared-ad table are global.
+// Coordinate Kit providers sharing one SDK instance, even across gateways.
+const activeSdk = new WeakSet();
+const uncertainSdk = new WeakSet();
+function response(input, result) {
+    return { id: input.id, ok: true, data: result };
+}
+function failure(input, code, retryable = false) {
+    return { id: input.id, ok: false, error: { code, message: code, retryable } };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isRewardItem(value) {
+    return isRecord(value)
+        && typeof value.type === 'string'
+        && value.type.length > 0
+        && typeof value.amount === 'number'
+        && Number.isFinite(value.amount)
+        && value.amount > 0;
+}
+class PreflightTimeoutError extends Error {
+}
+async function withTimeout(promise, milliseconds, onLate) {
+    let timer;
+    let expired = false;
+    const watched = promise.then((value) => {
+        if (expired && onLate !== undefined) {
+            void Promise.resolve().then(() => onLate(value)).catch(() => undefined);
+        }
+        return value;
+    });
+    try {
+        return await Promise.race([
+            watched,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    expired = true;
+                    reject(new PreflightTimeoutError('AdMob preflight timed out.'));
+                }, milliseconds);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Opt-in rewarded-only provider. The SDK's SSV options are attached when an
+ * operation is shown, never to an earlier unbound preload. A local reward
+ * callback is only a signal to ask the backend; it is not a ledger grant.
+ */
+export function createCapacitorAdMobRewardedProvider(input) {
+    const sdk = input.sdk ?? AdMob;
+    const showTimeoutMs = input.showTimeoutMs ?? defaultShowTimeoutMs;
+    if (!Number.isSafeInteger(showTimeoutMs) || showTimeoutMs < 1_000 || showTimeoutMs > 300_000) {
+        throw new Error('AdMob show timeout must be between 1 and 300 seconds.');
+    }
+    const adUnits = new Map();
+    for (const [placementId, unit] of Object.entries(input.adUnits)) {
+        if (placementId.trim() === '' || !unitPattern.test(unit)) {
+            throw new Error('AdMob rewarded placements require non-empty IDs and production-format ad units.');
+        }
+        adUnits.set(placementId, unit);
+    }
+    if (adUnits.size === 0) {
+        throw new Error('AdMob rewarded provider requires at least one ad unit.');
+    }
+    let initialized;
+    let consentTask;
+    let canRequestAds = false;
+    let privacyOptionsRequired = false;
+    const initialize = async () => {
+        if (initialized === undefined) {
+            initialized = sdk.initialize().catch((error) => {
+                initialized = undefined;
+                throw error;
+            });
+        }
+        await initialized;
+    };
+    const requestConsent = () => {
+        if (consentTask === undefined) {
+            consentTask = (async () => {
+                canRequestAds = false;
+                await initialize();
+                let info = await sdk.requestConsentInfo();
+                if (info.status === AdmobConsentStatus.REQUIRED && info.isConsentFormAvailable) {
+                    info = await sdk.showConsentForm();
+                }
+                canRequestAds = info.canRequestAds === true;
+                privacyOptionsRequired = info.privacyOptionsRequirementStatus === 'REQUIRED';
+                return canRequestAds;
+            })().finally(() => { consentTask = undefined; });
+        }
+        return consentTask;
+    };
+    const showRewarded = async (placementId, idempotencyKey) => {
+        const adId = adUnits.get(placementId);
+        if (adId === undefined || !canRequestAds || activeSdk.has(sdk) || uncertainSdk.has(sdk)) {
+            return { status: 'unavailable', rewardGranted: false };
+        }
+        if (idempotencyKey.trim() === ''
+            || idempotencyKey.length > admobSsvMaximumBindingFieldLength
+            || placementId.length > admobSsvMaximumBindingFieldLength) {
+            return { status: 'failed', rewardGranted: false };
+        }
+        activeSdk.add(sdk);
+        const handles = [];
+        let rewardEarned = false;
+        let timer;
+        let loadTimer;
+        let loadTimedOut = false;
+        let nativePreflightStarted = false;
+        try {
+            const playerId = await withTimeout(Promise.resolve().then(() => input.getPlayerId()), preflightTimeoutMs);
+            if (typeof playerId !== 'string' || playerId.trim() === ''
+                || playerId.length > admobSsvMaximumBindingFieldLength) {
+                return { status: 'failed', rewardGranted: false };
+            }
+            const customData = encodeAdMobSsvCustomData({ playerId, placementId, idempotencyKey });
+            if (new TextEncoder().encode(customData).byteLength > maximumCustomDataBytes) {
+                return { status: 'failed', rewardGranted: false };
+            }
+            // This plugin resolves showRewardVideoAd on reward, but on Android a
+            // dismissal without reward leaves that promise unresolved. Observe the
+            // terminal native events separately, and hold lifecycle through close.
+            let finish;
+            const terminal = new Promise((resolve) => {
+                finish = resolve;
+            });
+            nativePreflightStarted = true;
+            handles.push(await withTimeout(sdk.addListener(RewardAdPluginEvents.Rewarded, (reward) => {
+                if (isRewardItem(reward)) {
+                    rewardEarned = true;
+                }
+            }), preflightTimeoutMs, (handle) => handle.remove()));
+            handles.push(await withTimeout(sdk.addListener(RewardAdPluginEvents.Dismissed, () => {
+                // Let a same-turn Rewarded event settle before reading the flag.
+                queueMicrotask(() => finish('dismissed'));
+            }), preflightTimeoutMs, (handle) => handle.remove()));
+            handles.push(await withTimeout(sdk.addListener(RewardAdPluginEvents.FailedToShow, () => {
+                finish('failed');
+            }), preflightTimeoutMs, (handle) => handle.remove()));
+            const loaded = await Promise.race([
+                sdk.prepareRewardVideoAd({
+                    adId,
+                    ...(input.isTesting === undefined ? {} : { isTesting: input.isTesting }),
+                    ssv: { userId: playerId, customData },
+                }),
+                new Promise((_resolve, reject) => {
+                    loadTimer = setTimeout(() => {
+                        loadTimedOut = true;
+                        reject(new Error('AdMob load timed out.'));
+                    }, loadTimeoutMs);
+                }),
+            ]);
+            if (loadTimer !== undefined) {
+                clearTimeout(loadTimer);
+                loadTimer = undefined;
+            }
+            if (typeof loaded.adUnitId !== 'string' || loaded.adUnitId.length === 0) {
+                return { status: 'failed', rewardGranted: false };
+            }
+            timer = setTimeout(() => finish('timeout'), showTimeoutMs);
+            // Always observe rejection, even if a Dismissed event wins the race.
+            const showResult = sdk.showRewardVideoAd({ adId: loaded.adUnitId });
+            const onReward = (reward) => {
+                if (isRewardItem(reward)) {
+                    rewardEarned = true;
+                }
+            };
+            const onShowError = () => finish('failed');
+            void showResult.then(onReward, onShowError);
+            const outcome = await terminal;
+            if (outcome === 'timeout') {
+                // Native presentation state is unknown: do not allow another show.
+                uncertainSdk.add(sdk);
+            }
+            let status = 'failed';
+            if (rewardEarned) {
+                status = 'completed';
+            }
+            else if (outcome === 'dismissed') {
+                // Mediation may deliver reward after dismissal. Only signed SSV can
+                // later distinguish a true skip from an earned reward.
+                status = 'pending';
+            }
+            else if (outcome === 'timeout') {
+                status = 'pending';
+            }
+            return {
+                status,
+                rewardGranted: false,
+                ...(status === 'completed' || status === 'pending' ? { evidence: {
+                        schema: admobClientRewardEvidenceSchema,
+                        payload: { adUnitId: adId },
+                    } } : {}),
+            };
+        }
+        catch (error) {
+            const uncertain = loadTimedOut
+                || (nativePreflightStarted && error instanceof PreflightTimeoutError);
+            if (uncertain) {
+                uncertainSdk.add(sdk);
+            }
+            return { status: uncertain ? 'pending' : 'failed', rewardGranted: false };
+        }
+        finally {
+            if (loadTimer !== undefined) {
+                clearTimeout(loadTimer);
+            }
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            try {
+                const removals = handles.map((handle) => {
+                    const removal = Promise.resolve().then(() => handle.remove());
+                    return withTimeout(removal, listenerCleanupTimeoutMs);
+                });
+                const settled = await Promise.allSettled(removals);
+                if (settled.some((result) => result.status === 'rejected')) {
+                    uncertainSdk.add(sdk);
+                }
+            }
+            finally {
+                activeSdk.delete(sdk);
+            }
+        }
+    };
+    return {
+        id: 'admob-rewarded',
+        features: ['rewardedAds'],
+        methods: ['ads.preload', 'ads.showRewarded'],
+        async getAvailability() {
+            if (uncertainSdk.has(sdk) || !canRequestAds) {
+                return { rewardedAds: 'action-required' };
+            }
+            return { rewardedAds: activeSdk.has(sdk) ? 'temporarily-unavailable' : 'available' };
+        },
+        requestConsent,
+        async showPrivacyOptions() {
+            if (!privacyOptionsRequired) {
+                return;
+            }
+            canRequestAds = false;
+            await initialize();
+            try {
+                await sdk.showPrivacyOptionsForm();
+            }
+            finally {
+                await requestConsent();
+            }
+        },
+        bridge: {
+            async request(request) {
+                if (request.method === 'ads.preload') {
+                    const payload = request.payload;
+                    if (!isRecord(payload)
+                        || (payload.format !== undefined && payload.format !== 'rewarded')
+                        || typeof payload.placementId !== 'string'
+                        || !adUnits.has(payload.placementId)) {
+                        return failure(request, 'ADMOB_PLACEMENT_INVALID');
+                    }
+                    // Preloading an unbound ad would omit the operation's SSV key.
+                    return response(request, undefined);
+                }
+                if (request.method !== 'ads.showRewarded' || !isRecord(request.payload)
+                    || typeof request.payload.placementId !== 'string'
+                    || typeof request.payload.idempotencyKey !== 'string') {
+                    return failure(request, 'ADMOB_REQUEST_INVALID');
+                }
+                return response(request, await showRewarded(request.payload.placementId, request.payload.idempotencyKey));
+            },
+        },
+    };
+}

package/dist/app-events.d.ts

@@ -0,0 +1,23 @@
+import { type AppPlugin } from '@capacitor/app';
+import type { LifecycleAdapter } from '@mpgd/platform';
+export type CapacitorIncomingUrlKind = 'game' | 'oauth';
+export interface CapacitorVisibilitySource {
+  readonly hidden: boolean;
+  addEventListener(type: 'visibilitychange', listener: () => void): void;
+  removeEventListener(type: 'visibilitychange', listener: () => void): void;
+}
+export type CapacitorAppEventsApi = Pick<AppPlugin, 'addListener' | 'getState' | 'getLaunchUrl' | 'exitApp'>;
+export interface CreateCapacitorAppEventsInput {
+  readonly target: 'android' | 'ios';
+  readonly app?: CapacitorAppEventsApi;
+  readonly visibility?: CapacitorVisibilitySource | null;
+  /** Return null for URLs that this game does not own. Never default OAuth to game. */
+  readonly classifyIncomingUrl?: (url: string) => CapacitorIncomingUrlKind | null;
+  readonly historyBack?: () => void;
+  readonly onError?: (error: unknown) => void;
+}
+/**
+* Owns only handles it registers. Disposing during an awaited addListener
+* removes the eventual handle without touching another gateway's listeners.
+*/
+export declare function createCapacitorAppEvents(input: CreateCapacitorAppEventsInput): LifecycleAdapter;