@mpgd/adapter-ait 0.12.6 → 0.13.0

package/dist/ad-provider.d.ts

@@ -0,0 +1,18 @@
+import { type AdProvider, type AdShowInput, type AdShowResult } from '@mpgd/platform/ads';
+import type { AitHostDependencies } from './host.js';
+import type { AitAdPlacementType } from './ad-config.js';
+/** SDK event interpretation only. Game execution and backend grants are separate owners. */
+export declare function createAitAdProvider(input: {
+  readonly dependencies: Pick<AitHostDependencies, 'showFullScreenAd'>;
+  readonly groups: ReadonlyMap<string, string>;
+  readonly types: ReadonlyMap<string, AitAdPlacementType>;
+  readonly isSupported: () => boolean;
+  readonly prepare: (group: string) => Promise<void>;
+  readonly consume: (group: string) => boolean;
+  readonly requestTimeoutMs: number;
+  readonly startTimeoutMs: number;
+  readonly displayTimeoutMs: number;
+  readonly onLegacyPhase?: (active: boolean) => void;
+}): AdProvider & {
+  showLegacy(request: AdShowInput): Promise<AdShowResult>;
+};

package/dist/ad-provider.js

@@ -0,0 +1,295 @@
+import { adProtocol, adProtocolVersion, assertAdPresentationEvent, assertAdShowInput, assertAdShowResult, } from '@mpgd/platform/ads';
+const nativeOwners = new WeakMap();
+/** SDK event interpretation only. Game execution and backend grants are separate owners. */
+export function createAitAdProvider(input) {
+    const id = 'apps-in-toss-ads';
+    const sdk = input.dependencies.showFullScreenAd;
+    const listeners = new Set();
+    function availability(request) {
+        if (!input.isSupported()) {
+            return { state: 'unsupported', reason: 'unsupported' };
+        }
+        if (input.types.has(request.placementId) && input.types.get(request.placementId) !== request.format) {
+            return {
+                state: 'unsupported',
+                reason: 'unsupported',
+            };
+        }
+        if (!input.groups.has(request.placementId) || !input.types.has(request.placementId)) {
+            return {
+                state: 'configuration-required',
+                reason: 'configuration-required',
+            };
+        }
+        const owner = nativeOwners.get(sdk);
+        if (owner?.state === 'unknown') {
+            return {
+                state: 'action-required',
+                reason: 'action-required',
+            };
+        }
+        if (owner !== undefined) {
+            return { state: 'temporarily-unavailable', reason: 'busy' };
+        }
+        return { state: 'available' };
+    }
+    async function show(supplied, legacy) {
+        const request = assertAdShowInput(supplied);
+        if (request.idempotencyKey.length > 256 || /[\p{Cc}\p{Cf}]/u.test(request.idempotencyKey)) {
+            throw new TypeError('AIT ad correlation must contain 1 to 256 visible characters.');
+        }
+        const makeResult = (state) => assertAdShowResult({ providerId: id, invocationId: request.invocationId, format: request.format, ...state });
+        const noStart = (outcome, reason) => makeResult({
+            outcome,
+            presentation: 'not-started',
+            eligibility: request.format === 'rewarded' ? 'not-earned' : 'not-applicable',
+            ...(reason === undefined ? {} : { reason }),
+        });
+        const available = availability(request);
+        if (available.state !== 'available') {
+            return noStart('unavailable', available.reason);
+        }
+        const group = input.groups.get(request.placementId);
+        if (group === undefined) {
+            return noStart('unavailable', 'configuration-required');
+        }
+        const owned = { state: 'requested' };
+        nativeOwners.set(sdk, owned);
+        const legacyPhase = (active) => {
+            if (!legacy) {
+                return;
+            }
+            try {
+                input.onLegacyPhase?.(active);
+            }
+            catch { /* Isolate lifecycle observation. */ }
+        };
+        const release = () => {
+            if (nativeOwners.get(sdk) === owned) {
+                nativeOwners.delete(sdk);
+            }
+        };
+        try {
+            await input.prepare(group);
+        }
+        catch {
+            release();
+            return noStart('failed', 'transient-failure');
+        }
+        if (!input.consume(group)) {
+            release();
+            return noStart('failed', 'transient-failure');
+        }
+        let started = false;
+        let closed = false;
+        let earned;
+        let sequence = 0;
+        let cleanup;
+        let cleaned = false;
+        let timer;
+        let displayTimerArmed = false;
+        let delivered = false;
+        let resolve;
+        const result = new Promise((done) => {
+            resolve = done;
+        });
+        const startedAt = Date.now();
+        const emit = (event) => {
+            const safe = assertAdPresentationEvent({
+                ...event,
+                providerId: id,
+                invocationId: request.invocationId,
+                sequence: ++sequence,
+            });
+            for (const listener of [...listeners]) {
+                try {
+                    void Promise.resolve(listener(safe)).catch(() => undefined);
+                }
+                catch { /* Keep native terminal observation alive. */ }
+            }
+        };
+        const clean = () => {
+            if (cleaned || cleanup === undefined || !closed || request.format === 'rewarded' && earned === undefined) {
+                return;
+            }
+            cleaned = true;
+            try {
+                cleanup();
+            }
+            catch { /* Cleanup does not change native closure. */ }
+        };
+        const finish = (value) => {
+            if (!delivered) {
+                delivered = true;
+                resolve(value);
+            }
+        };
+        const eligibility = () => {
+            if (request.format === 'interstitial') {
+                return 'not-applicable';
+            }
+            return earned === undefined ? 'unknown' : 'eligible';
+        };
+        const uncertain = () => {
+            if (closed || owned.state === 'unknown') {
+                return;
+            }
+            owned.state = 'unknown';
+            emit({ type: 'unknown' });
+            finish(makeResult({
+                outcome: 'pending',
+                presentation: 'unknown',
+                eligibility: eligibility(),
+                reason: 'outcome-unknown',
+                ...(earned === undefined ? {} : { evidence: earned }),
+            }));
+        };
+        const close = (failed) => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            release();
+            legacyPhase(false);
+            emit(failed ? { type: 'failed', reason: 'transient-failure' } : { type: 'closed' });
+            if (failed && !started && earned === undefined) {
+                finish(noStart('failed', 'transient-failure'));
+            }
+            else {
+                finish(makeResult({
+                    outcome: failed ? 'failed' : 'shown',
+                    presentation: 'closed',
+                    eligibility: eligibility(),
+                    ...(failed ? { reason: 'transient-failure' } : {}),
+                    ...(earned === undefined ? {} : { evidence: earned }),
+                }));
+            }
+            // Failure before presentation proves no earning is forthcoming. After a
+            // started presentation, retain the scoped callback for a delayed reward.
+            if (failed && !started && earned === undefined) {
+                cleaned = true;
+                if (cleanup !== undefined) {
+                    try {
+                        cleanup();
+                    }
+                    catch { /* Isolate cleanup. */ }
+                }
+            }
+            else {
+                clean();
+            }
+        };
+        const startedEvent = () => {
+            if (closed) {
+                return;
+            }
+            if (!started) {
+                started = true;
+                owned.state = 'open';
+                emit({ type: 'started' });
+            }
+            if (!displayTimerArmed) {
+                displayTimerArmed = true;
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                timer = setTimeout(uncertain, input.displayTimeoutMs);
+            }
+        };
+        legacyPhase(true);
+        emit({ type: 'requested' });
+        timer = setTimeout(uncertain, input.requestTimeoutMs);
+        try {
+            cleanup = sdk({
+                options: { adGroupId: group },
+                onEvent(event) {
+                    switch (event.type) {
+                        case 'requested':
+                            if (!closed && !started) {
+                                if (timer !== undefined) {
+                                    clearTimeout(timer);
+                                }
+                                timer = setTimeout(uncertain, Math.min(input.startTimeoutMs, Math.max(0, input.requestTimeoutMs - (Date.now() - startedAt))));
+                            }
+                            break;
+                        case 'show':
+                        case 'impression':
+                        case 'clicked':
+                            startedEvent();
+                            break;
+                        case 'userEarnedReward':
+                            if (request.format !== 'rewarded' || earned !== undefined || cleaned) {
+                                break;
+                            }
+                            if (!closed) {
+                                startedEvent();
+                            }
+                            earned = { schema: 'apps-in-toss.rewarded-ad.callback.v1', payload: { event: 'user-earned-reward', correlationId: request.idempotencyKey, placementId: group } };
+                            emit({ type: 'reward-earned', evidence: earned });
+                            clean();
+                            break;
+                        case 'dismissed':
+                            close(false);
+                            break;
+                        case 'failedToShow':
+                            close(true);
+                            break;
+                    }
+                },
+                // A bridge error does not prove the native UI never opened.
+                onError() { uncertain(); },
+            });
+            if (cleaned) {
+                try {
+                    cleanup();
+                }
+                catch { /* Isolate synchronous terminal cleanup. */ }
+            }
+            else {
+                clean();
+            }
+        }
+        catch {
+            uncertain();
+        }
+        return result;
+    }
+    return {
+        id,
+        protocol: adProtocol,
+        protocolVersion: adProtocolVersion,
+        rewardSignal: 'delayed',
+        getAvailability: async (request) => availability(request),
+        async preload(request) {
+            const available = availability(request);
+            if (available.state !== 'available') {
+                return {
+                    status: 'unavailable',
+                    ...(available.reason === undefined ? {} : { reason: available.reason }),
+                };
+            }
+            const group = input.groups.get(request.placementId);
+            if (group === undefined) {
+                return { status: 'unavailable', reason: 'configuration-required' };
+            }
+            try {
+                await input.prepare(group);
+                return { status: 'ready' };
+            }
+            catch {
+                return { status: 'failed', reason: 'transient-failure' };
+            }
+        },
+        show: (request) => show(request, false),
+        showLegacy: (request) => show(request, true),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/authority-fetch.d.ts

@@ -8,6 +8,19 @@
 * response validation in its authority client. This helper only owns the
 * WebView transport invocation, so all game-owned authority endpoints can use
 * the same safe call shape.
+*
+* Authority calls carry grant evidence and idempotency headers, so the
+* resource must resolve to an `https:` origin. Plain `http:` is accepted only
+* for a loopback development authority (`localhost` or `127.0.0.1`).
+*
+* The transport receives exactly the representation that passed the policy
+* check. A string, or a URL-like object (a string `href` and no `url`, which
+* also covers a `URL` created in another realm such as an iframe), is
+* forwarded as its validated absolute `href`. A same-realm `Request` is
+* forwarded unchanged after its immutable `url` validated. Anything else is
+* rejected: a Request-like object that is not a same-realm `Request` would be
+* stringified by native fetch through `toString`, not `url`, so validating its
+* `url` would not cover what is actually fetched.
 */
 export declare function fetchAitAuthority(input: {
   readonly resource: RequestInfo | URL;

package/dist/authority-fetch.js

@@ -8,11 +8,91 @@
  * response validation in its authority client. This helper only owns the
  * WebView transport invocation, so all game-owned authority endpoints can use
  * the same safe call shape.
+ *
+ * Authority calls carry grant evidence and idempotency headers, so the
+ * resource must resolve to an `https:` origin. Plain `http:` is accepted only
+ * for a loopback development authority (`localhost` or `127.0.0.1`).
+ *
+ * The transport receives exactly the representation that passed the policy
+ * check. A string, or a URL-like object (a string `href` and no `url`, which
+ * also covers a `URL` created in another realm such as an iframe), is
+ * forwarded as its validated absolute `href`. A same-realm `Request` is
+ * forwarded unchanged after its immutable `url` validated. Anything else is
+ * rejected: a Request-like object that is not a same-realm `Request` would be
+ * stringified by native fetch through `toString`, not `url`, so validating its
+ * `url` would not cover what is actually fetched.
  */
 export function fetchAitAuthority(input) {
     const fetchImplementation = input.fetch ?? globalThis.fetch;
     if (typeof fetchImplementation !== 'function') {
         return Promise.reject(new TypeError('AIT authority fetch is unavailable.'));
     }
-    return fetchImplementation(input.resource, input.init);
+    const resolution = resolveAitAuthorityResource(input.resource);
+    if (!resolution.ok) {
+        return Promise.reject(resolution.error);
+    }
+    return fetchImplementation(resolution.resource, input.init);
+}
+const loopbackHostnames = new Set(['localhost', '127.0.0.1']);
+function resolveAitAuthorityResource(resource) {
+    const candidate = readAitAuthorityResourceCandidate(resource);
+    if (candidate === undefined) {
+        return {
+            ok: false,
+            error: new TypeError('AIT authority resource must be a string, URL, or same-realm Request.'),
+        };
+    }
+    let url;
+    try {
+        url = new URL(candidate.href, globalThis.location?.href);
+    }
+    catch {
+        return {
+            ok: false,
+            error: new TypeError('AIT authority resource must be an absolute https: URL.'),
+        };
+    }
+    const policyError = checkAitAuthorityUrl(url);
+    if (policyError !== undefined) {
+        return { ok: false, error: policyError };
+    }
+    return {
+        ok: true,
+        resource: candidate.kind === 'request' ? candidate.request : url.href,
+    };
+}
+function checkAitAuthorityUrl(url) {
+    if (url.protocol === 'https:') {
+        return undefined;
+    }
+    if (url.protocol === 'http:' && loopbackHostnames.has(url.hostname)) {
+        return undefined;
+    }
+    return new TypeError(`AIT authority resource must use https: (http: is allowed only for localhost); received ${url.protocol}//${url.host}.`);
+}
+/**
+ * Reads the URL text once so the same value is both validated and forwarded.
+ *
+ * URL-like objects are recognized by shape (`instanceof URL` is false for a
+ * URL from another realm) and forwarded as their href string, so the object
+ * itself never reaches the transport. Requests are only accepted via a
+ * same-realm `instanceof Request`: the instance must be forwarded as-is, and
+ * native fetch stringifies any non-Request object through `toString` rather
+ * than reading `url`, so a duck-typed `{ url }` cannot be trusted.
+ */
+function readAitAuthorityResourceCandidate(resource) {
+    if (typeof resource === 'string') {
+        return { kind: 'href', href: resource };
+    }
+    if (typeof resource !== 'object' || resource === null) {
+        return undefined;
+    }
+    if (typeof Request === 'function' && resource instanceof Request) {
+        return { kind: 'request', href: resource.url, request: resource };
+    }
+    const { href, url } = resource;
+    if (typeof href === 'string' && url === undefined) {
+        return { kind: 'href', href };
+    }
+    return undefined;
 }

package/dist/host.d.ts

@@ -149,7 +149,7 @@ export interface InstallAitHostBridgeOptions {
   readonly adLoadQueueTimeoutMs?: number;
   /** Upper bound for the requested-to-display portion of the total show timeout. */
   readonly adDisplayStartTimeoutMs?: number;
-  /** Last-resort cleanup when the native SDK omits its terminal display callback. */
+  /** Caller wait limit; a missing native terminal callback keeps presentation unknown. */
   readonly adMaximumDisplayMs?: number;
   /** Maximum wait for an inline banner to render or report no-fill/failure. */
   readonly bannerRenderTimeoutMs?: number;

package/dist/host.js

@@ -1,5 +1,7 @@
 import { getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame as grantPromotionReward, IAP, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, requestNotificationAgreement, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore, TossAds, } from '@apps-in-toss/web-framework';
 import { assertBridgeRequest, bridgeStorageLoadProtocol, } from '@mpgd/bridge';
+import { assertAdShowInput, toAdAdapter } from '@mpgd/platform/ads';
+import { createAitAdProvider } from './ad-provider.js';
 import { dispatchAitLifecycleEvent } from './lifecycle.js';
 const defaultAdTimeoutMs = 60_000;
 const defaultAdLoadQueueTimeoutMs = 5_000;
@@ -13,9 +15,15 @@ const defaultIapPurchaseSessionTimeoutMs = 30 * 60_000;
 /** A provider response is untrusted input; keep restore work bounded per launch. */
 const maximumPendingIapOrders = 20;
 const invalidBridgeRequestId = 'ait-invalid-request';
-const rewardedAdEvidenceSchema = 'apps-in-toss.rewarded-ad.callback.v1';
 const iapEvidenceSchema = 'apps-in-toss.iap.callback.v1';
 const minimumPromotionTossAppVersion = '5.232.0';
+/**
+ * Every adapter-owned durable marker (purchase attempts, promotion grants,
+ * recovery cursors) lives under this prefix. Game code shares the same native
+ * storage, so `storage.save`/`storage.load` must never touch these keys: a
+ * forged `completed` marker would otherwise short-circuit purchase verification.
+ */
+const reservedStorageKeyPrefix = 'mpgd:ait:';
 const promotionGrantStoragePrefix = 'mpgd:ait:promotion-grant:v1:';
 /**
  * A client idempotency key must survive a bridge reload. The authoritative
@@ -108,7 +116,6 @@ export function createAitHostBridge(options = {}) {
     const notificationSubscriptions = new Set();
     const loadedAdGroupIds = new Set();
     const loadingAdGroups = new Map();
-    const activeAdGroupIds = new Set();
     const activeBannerAttachments = new Map();
     const bannerMountOwners = new Map();
     const pendingBannerMountSettlements = new Map();
@@ -124,10 +131,20 @@ export function createAitHostBridge(options = {}) {
         tone: options.bannerAppearance?.tone ?? 'blackAndWhite',
         variant: options.bannerAppearance?.variant ?? 'expanded',
     };
-    const adLoadCoordinator = {
-        active: undefined,
-        waitTimeoutMs: adLoadQueueTimeoutMs,
-    };
+    const adLoadCoordinator = createAdLoadCoordinator(dependencies.loadFullScreenAd, adLoadQueueTimeoutMs);
+    const nativeAds = createAitAdProvider({
+        dependencies,
+        groups: adGroupIds,
+        types: adPlacementTypes,
+        isSupported: () => areFullScreenAdsSupported(dependencies),
+        prepare: (group) => preloadAdGroup(dependencies, group, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, adTimeoutMs),
+        consume: (group) => consumeLoadedAd(group, loadedAdGroupIds),
+        requestTimeoutMs: adTimeoutMs,
+        startTimeoutMs: adDisplayStartTimeoutMs,
+        displayTimeoutMs: adMaximumDisplayMs,
+        onLegacyPhase: (active) => dispatchAitLifecycleEvent(active ? 'pause' : 'resume'),
+    });
+    const legacyAds = toAdAdapter({ ...nativeAds, show: nativeAds.showLegacy });
     const enqueueCompletedIapAttemptRetention = (storage, storageKey) => {
         const scheduled = completedIapAttemptRetention.then(async () => {
             await retainCompletedAitIapPurchaseAttempt(storage, storageKey, iapProductGrantTimeoutMs);
@@ -138,6 +155,13 @@ export function createAitHostBridge(options = {}) {
         return next;
     };
     return {
+        advertising: {
+            id: nativeAds.id,
+            protocol: nativeAds.protocol,
+            protocolVersion: nativeAds.protocolVersion,
+            rewardSignal: nativeAds.rewardSignal,
+            subscribe: (listener) => nativeAds.subscribe(listener),
+        },
         async request(input) {
             try {
                 return await handleRequest(parseBridgeRequest(input));
@@ -370,51 +394,24 @@ export function createAitHostBridge(options = {}) {
                 await preloadAdGroupWithDiagnostics(dependencies, adGroupId, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, adTimeoutMs, placementType);
                 return ok(request, {});
             }
-            case 'ads.showRewarded': {
-                const placementId = readPlacementId(request.payload);
-                const adGroupId = adGroupIds.get(placementId);
-                if (adGroupId === undefined
-                    || adPlacementTypes.get(placementId) !== 'rewarded'
-                    || !areFullScreenAdsSupported(dependencies)) {
-                    return ok(request, { status: 'unavailable', rewardGranted: false });
-                }
-                const shown = await withLoadedAdSlot(dependencies, adGroupId, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, activeAdGroupIds, adTimeoutMs, 'rewarded', async () => {
-                    const correlationId = readIdempotencyKey(request.payload, request.id);
-                    const result = await showRewardedAd(dependencies, adGroupId, adTimeoutMs, adDisplayStartTimeoutMs, adMaximumDisplayMs);
-                    return result.rewardGranted
-                        ? {
-                            ...result,
-                            // game-services forwards this as platformImpressionId and compares it
-                            // with the native callback correlationId during authority verification.
-                            ledgerEntryId: correlationId,
-                            evidence: {
-                                schema: rewardedAdEvidenceSchema,
-                                payload: {
-                                    event: 'user-earned-reward',
-                                    correlationId,
-                                    placementId: adGroupId,
-                                },
-                            },
-                        }
-                        : result;
+            case 'ads.getAvailability':
+            case 'ads.prepare': {
+                const payload = readPayloadRecord(request.payload);
+                const query = assertAdShowInput({
+                    ...payload,
+                    invocationId: 'host-query',
+                    idempotencyKey: 'host-query',
                 });
-                if (!shown.acquired) {
-                    return ok(request, { status: 'unavailable', rewardGranted: false });
-                }
-                return ok(request, shown.value);
-            }
-            case 'ads.showInterstitial': {
-                const placementId = readPlacementId(request.payload);
-                const adGroupId = adGroupIds.get(placementId);
-                if (adGroupId === undefined
-                    || adPlacementTypes.get(placementId) !== 'interstitial'
-                    || !areFullScreenAdsSupported(dependencies)) {
-                    return ok(request, { status: 'unavailable' });
-                }
-                const showInterstitial = () => showInterstitialAd(dependencies, adGroupId, adTimeoutMs, adDisplayStartTimeoutMs, adMaximumDisplayMs);
-                const shown = await withLoadedAdSlot(dependencies, adGroupId, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, activeAdGroupIds, adTimeoutMs, 'interstitial', showInterstitial);
-                return ok(request, shown.acquired ? shown.value : { status: 'unavailable' });
+                return ok(request, request.method === 'ads.prepare'
+                    ? await nativeAds.preload(query)
+                    : await nativeAds.getAvailability(query));
             }
+            case 'ads.show':
+                return ok(request, await nativeAds.show(assertAdShowInput(request.payload)));
+            case 'ads.showRewarded':
+                return ok(request, await legacyAds.showRewarded({ placementId: readPlacementId(request.payload), idempotencyKey: readRewardedAdCorrelationId(request.payload, request.id) }));
+            case 'ads.showInterstitial':
+                return ok(request, await legacyAds.showInterstitial?.({ placementId: readPlacementId(request.payload) }));
             case 'ads.mountBanner': {
                 const placementId = readPlacementId(request.payload);
                 const surfaceId = readBannerSurfaceId(request.payload);
@@ -828,6 +825,24 @@ async function preloadAdGroup(dependencies, adGroupId, loaded, loading, coordina
         }
     }
 }
+const nativeAdLoadScopes = new WeakMap();
+function createAdLoadCoordinator(sdk, waitTimeoutMs) {
+    let shared = nativeAdLoadScopes.get(sdk);
+    if (shared === undefined) {
+        shared = { active: undefined };
+        nativeAdLoadScopes.set(sdk, shared);
+    }
+    const owned = shared;
+    return {
+        get active() {
+            return owned.active;
+        },
+        set active(value) {
+            owned.active = value;
+        },
+        waitTimeoutMs,
+    };
+}
 async function runSerializedAdLoad(coordinator, adGroupId, startNativeLoad) {
     const waitDeadline = Date.now() + coordinator.waitTimeoutMs;
     while (coordinator.active !== undefined) {
@@ -871,22 +886,6 @@ function waitForAdLoadSettlement(active, timeoutMs, adGroupId) {
         void active.then(() => finish(), () => finish());
     });
 }
-async function acquireLoadedAdSlot(dependencies, adGroupId, loaded, loading, coordinator, active, timeoutMs, placementType) {
-    if (active.has(adGroupId)) {
-        return false;
-    }
-    const loadedSuccessfully = await preloadAdGroupWithDiagnostics(dependencies, adGroupId, loaded, loading, coordinator, timeoutMs, placementType);
-    if (!loadedSuccessfully) {
-        return false;
-    }
-    // Re-check after the asynchronous load so concurrent callers cannot consume
-    // or display the same native ad slot twice.
-    if (active.has(adGroupId) || !consumeLoadedAd(adGroupId, loaded)) {
-        return false;
-    }
-    active.add(adGroupId);
-    return true;
-}
 async function preloadAdGroupWithDiagnostics(dependencies, adGroupId, loaded, loading, coordinator, timeoutMs, placementType) {
     // The first caller enters preloadAdGroup synchronously and publishes its promise
     // before yielding. Remember that ownership so concurrent waiters do not emit the
@@ -905,136 +904,19 @@ async function preloadAdGroupWithDiagnostics(dependencies, adGroupId, loaded, lo
         return false;
     }
 }
-async function withLoadedAdSlot(dependencies, adGroupId, loaded, loading, coordinator, active, timeoutMs, placementType, display) {
-    const acquired = await acquireLoadedAdSlot(dependencies, adGroupId, loaded, loading, coordinator, active, timeoutMs, placementType);
-    if (!acquired) {
-        return { acquired: false };
-    }
-    try {
-        return { acquired: true, value: await display() };
-    }
-    finally {
-        active.delete(adGroupId);
-    }
-}
-async function showRewardedAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs) {
-    let rewardGranted = false;
-    const status = await showAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs, (eventType) => {
-        if (eventType === 'userEarnedReward') {
-            rewardGranted = true;
-        }
-    });
-    let resultStatus;
-    if (status === 'shown' && rewardGranted) {
-        resultStatus = 'completed';
-    }
-    else if (status === 'failed') {
-        resultStatus = 'failed';
-    }
-    else {
-        resultStatus = 'skipped';
-    }
-    return {
-        status: resultStatus,
-        rewardGranted,
-    };
-}
-async function showInterstitialAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs) {
-    const status = await showAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs);
-    return { status: status === 'failed' ? 'skipped' : status };
-}
-function showAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs, observe) {
-    dispatchAitLifecycleEvent('pause');
-    return new Promise((resolve) => {
-        const startedAt = Date.now();
-        let cleanup = () => { };
-        let settled = false;
-        let maximumDisplayTimeoutArmed = false;
-        let adTimer;
-        const clearAdTimer = () => {
-            if (adTimer !== undefined) {
-                globalThis.clearTimeout(adTimer);
-                adTimer = undefined;
-            }
-        };
-        const finish = (status) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            clearAdTimer();
-            cleanup();
-            dispatchAitLifecycleEvent('resume');
-            resolve(status);
-        };
-        const armDisplayStartTimeout = () => {
-            clearAdTimer();
-            const elapsedMs = Math.max(0, Date.now() - startedAt);
-            const remainingMs = Math.max(0, timeoutMs - elapsedMs);
-            adTimer = globalThis.setTimeout(() => finish('failed'), Math.min(displayStartTimeoutMs, remainingMs));
-        };
-        const armMaximumDisplayTimeout = () => {
-            if (maximumDisplayTimeoutArmed) {
-                return;
-            }
-            maximumDisplayTimeoutArmed = true;
-            clearAdTimer();
-            adTimer = globalThis.setTimeout(() => {
-                console.warn('AIT full-screen ad omitted its terminal callback; recovering the game lifecycle.', adGroupId);
-                finish('shown');
-            }, maximumDisplayMs);
-        };
-        const failShow = (error) => {
-            if (settled) {
-                return;
-            }
-            console.warn('Failed to show AIT full-screen ad.', adGroupId, error ?? 'unknown native error');
-            finish('failed');
-        };
-        adTimer = globalThis.setTimeout(() => finish('failed'), timeoutMs);
-        try {
-            const unregister = dependencies.showFullScreenAd({
-                options: { adGroupId },
-                onEvent: (event) => {
-                    observe?.(event.type);
-                    switch (event.type) {
-                        case 'requested':
-                            armDisplayStartTimeout();
-                            break;
-                        case 'show':
-                        case 'impression':
-                        case 'clicked':
-                        case 'userEarnedReward':
-                            // Native terminal callbacks remain authoritative. A long, one-shot
-                            // recovery timeout prevents a broken SDK callback from deadlocking
-                            // the game forever without treating ordinary end-card dwell as failure.
-                            armMaximumDisplayTimeout();
-                            break;
-                        case 'dismissed':
-                            finish('shown');
-                            break;
-                        case 'failedToShow':
-                            finish('failed');
-                            break;
-                    }
-                },
-                onError: failShow,
-            });
-            cleanup = unregister;
-            if (settled) {
-                cleanup();
-            }
-        }
-        catch (error) {
-            failShow(error);
-        }
-    });
-}
+/**
+ * Launch and inbound-share parameters arrive from untrusted deep links. Bound
+ * each forwarded value and the nested `queryParams` JSON so a hostile link
+ * cannot push oversized or unbounded data into the game.
+ */
+const maximumLaunchParamLength = 256;
+const maximumNestedQueryParamsJsonLength = 4_096;
+const maximumNestedQueryParamCount = 32;
 function getLaunchIntent() {
     const params = inboundSearchParams();
-    const challengeToken = nonEmptyParam(params.get('challengeToken'));
-    const puzzleId = nonEmptyParam(params.get('puzzleId'));
-    const requestedEntry = nonEmptyParam(params.get('entry'));
+    const challengeToken = boundedParam(params.get('challengeToken'));
+    const puzzleId = boundedParam(params.get('puzzleId'));
+    const requestedEntry = boundedParam(params.get('entry'));
     let entry;
     if (requestedEntry !== undefined && launchEntries.has(requestedEntry)) {
         entry = requestedEntry;
@@ -1053,8 +935,8 @@ function getLaunchIntent() {
 }
 function readInboundShare() {
     const params = inboundSearchParams();
-    const puzzleId = nonEmptyParam(params.get('puzzleId'));
-    const challengeToken = nonEmptyParam(params.get('challengeToken'));
+    const puzzleId = boundedParam(params.get('puzzleId'));
+    const challengeToken = boundedParam(params.get('challengeToken'));
     return puzzleId === undefined && challengeToken === undefined
         ? null
         : {
@@ -1065,12 +947,24 @@ function readInboundShare() {
 function inboundSearchParams() {
     const params = new URLSearchParams(globalThis.location?.search ?? '');
     const nested = params.get('queryParams');
-    if (nested !== null) {
+    if (nested !== null && nested.length <= maximumNestedQueryParamsJsonLength) {
         try {
             const parsed = JSON.parse(nested);
             if (isRecord(parsed)) {
+                let merged = 0;
                 for (const [key, value] of Object.entries(parsed)) {
-                    if (typeof value === 'string' && !params.has(key)) {
+                    if (merged >= maximumNestedQueryParamCount) {
+                        break;
+                    }
+                    // Direct search params win; nested values only fill missing keys and
+                    // must be bounded strings. Keys are counted whether or not they merge
+                    // so an attacker cannot pad past the cap with ignored entries.
+                    merged += 1;
+                    if (typeof value === 'string'
+                        && key.length > 0
+                        && key.length <= maximumLaunchParamLength
+                        && value.length <= maximumLaunchParamLength
+                        && !params.has(key)) {
                         params.set(key, value);
                     }
                 }
@@ -2170,6 +2064,9 @@ function readStorageKey(payload) {
     if (typeof key !== 'string' || key.length === 0) {
         throw new TypeError('AIT storage key must be a non-empty string.');
     }
+    if (key.startsWith(reservedStorageKeyPrefix)) {
+        throw new TypeError(`AIT storage keys starting with "${reservedStorageKeyPrefix}" are reserved for adapter-owned markers.`);
+    }
     return key;
 }
 function readPlacementId(payload) {
@@ -2186,9 +2083,24 @@ function readBannerSurfaceId(payload) {
     }
     return surfaceId;
 }
-function readIdempotencyKey(payload, fallback) {
+/**
+ * A rewarded-ad idempotencyKey becomes the client-supplied evidence
+ * correlationId. It is optional, but when present it must obey the same
+ * bounded visible-character rule as purchase keys so a game cannot push
+ * arbitrary blobs into reward evidence.
+ */
+function readRewardedAdCorrelationId(payload, fallback) {
     const value = readPayloadRecord(payload).idempotencyKey;
-    return typeof value === 'string' && value.length > 0 ? value : fallback;
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== 'string'
+        || value.length === 0
+        || value.length > 256
+        || /[\p{Cc}\p{Cf}]/u.test(value)) {
+        throw new TypeError('AIT rewarded ad idempotencyKey must contain 1 to 256 visible characters.');
+    }
+    return value;
 }
 function readCommercePurchase(payload) {
     const value = readPayloadRecord(payload);
@@ -2256,8 +2168,10 @@ function ok(request, data) {
 function createBridgeError(id, code, message, retryable = false) {
     return { id, ok: false, error: { code, message, retryable } };
 }
-function nonEmptyParam(value) {
-    return value === null || value.length === 0 ? undefined : value;
+function boundedParam(value) {
+    return value === null || value.length === 0 || value.length > maximumLaunchParamLength
+        ? undefined
+        : value;
 }
 function isAbortError(error) {
     return isRecord(error) && error.name === 'AbortError';

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 import { type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import { type PlatformGateway } from '@mpgd/platform';
+import { type AdProvider } from '@mpgd/platform/ads';
 export interface GamePlatformBridge {
   request(input: BridgeRequest): Promise<BridgeResponse>;
+  /** Native observations are scoped to this host; SDK commands still use request envelopes. */
+  readonly advertising?: Pick<AdProvider, 'id' | 'protocol' | 'protocolVersion' | 'rewardSignal' | 'subscribe'>;
 }
 export interface AitSandboxStorage {
   readonly getItem: (key: string) => string | null;

package/dist/index.js

@@ -1,7 +1,48 @@
-import { bridgeStorageLoadProtocol, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
+import { assertBridgeResponse, bridgeStorageLoadProtocol, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
 import { PlatformOperationError, } from '@mpgd/platform';
+import { assertAdAvailability, assertAdPreparationResult, assertAdPresentationEvent, assertAdShowInput, assertAdShowResult, toAdAdapter, } from '@mpgd/platform/ads';
 import { createAitLifecycleAdapter } from './lifecycle.js';
 export function createAitPlatformGateway(input) {
+    const advertisingBridge = input.bridge ?? getBridge() ?? input.fallbackBridge;
+    const advertising = advertisingBridge?.advertising;
+    async function requestAdvertising(method, payload) {
+        if (advertisingBridge === undefined) {
+            throw new PlatformOperationError({
+                code: 'AIT_BRIDGE_NOT_INSTALLED',
+            });
+        }
+        const id = crypto.randomUUID();
+        const response = assertBridgeResponse(await advertisingBridge.request({ id, method, payload, meta: { target: 'ait', appVersion: input.appVersion, buildId: input.buildId, sentAt: new Date().toISOString() } }));
+        if (response.id !== id) {
+            throw new TypeError('Advertising response belongs to another bridge request.');
+        }
+        if (!response.ok) {
+            throw new PlatformOperationError(response.error);
+        }
+        return response.data;
+    }
+    const provider = advertising === undefined
+        ? undefined
+        : {
+            id: advertising.id,
+            protocol: advertising.protocol,
+            protocolVersion: advertising.protocolVersion,
+            rewardSignal: advertising.rewardSignal,
+            getAvailability: async (payload) => assertAdAvailability(await requestAdvertising('ads.getAvailability', payload)),
+            preload: async (payload) => assertAdPreparationResult(await requestAdvertising('ads.prepare', payload)),
+            show: async (supplied) => {
+                const request = assertAdShowInput(supplied);
+                const result = assertAdShowResult(await requestAdvertising('ads.show', request));
+                if (result.providerId !== advertising.id || result.invocationId !== request.invocationId || result.format !== request.format) {
+                    throw new TypeError('Advertising result belongs to another invocation.');
+                }
+                return result;
+            },
+            subscribe: (listener) => advertising.subscribe((event) => listener(assertAdPresentationEvent(event))),
+        };
+    if (provider !== undefined) {
+        toAdAdapter(provider);
+    }
     async function request(method, payload) {
         const bridge = input.bridge ?? getBridge() ?? input.fallbackBridge;
         if (bridge === undefined) {
@@ -60,6 +101,7 @@ export function createAitPlatformGateway(input) {
             getEntitlements: () => request('commerce.getEntitlements', {}),
         },
         ads: {
+            ...(provider === undefined ? {} : { provider }),
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
             showInterstitial: (payload) => request('ads.showInterstitial', payload),

package/dist/lifecycle.d.ts

@@ -1,5 +1,6 @@
 import type { LifecycleAdapter } from '@mpgd/platform';
 export declare const aitLifecyclePauseEvent = "mpgd:ait:pause";
 export declare const aitLifecycleResumeEvent = "mpgd:ait:resume";
+/** Legacy SDK presentation, page lifetime, and visibility are independent owners. */
 export declare function createAitLifecycleAdapter(): LifecycleAdapter;
 export declare function dispatchAitLifecycleEvent(type: 'pause' | 'resume'): void;

package/dist/lifecycle.js

@@ -1,45 +1,92 @@
 export const aitLifecyclePauseEvent = 'mpgd:ait:pause';
 export const aitLifecycleResumeEvent = 'mpgd:ait:resume';
-const lifecycleEventDedupeWindowMs = 500;
+/** Legacy SDK presentation, page lifetime, and visibility are independent owners. */
 export function createAitLifecycleAdapter() {
-    return {
-        onPause(callback) {
-            return subscribeToAitLifecycle('pause', callback);
-        },
-        onResume(callback) {
-            return subscribeToAitLifecycle('resume', callback);
-        },
-    };
-}
-export function dispatchAitLifecycleEvent(type) {
-    globalThis.dispatchEvent?.(new Event(type === 'pause' ? aitLifecyclePauseEvent : aitLifecycleResumeEvent));
-}
-function subscribeToAitLifecycle(type, callback) {
     const target = globalThis;
     const documentTarget = target.document;
-    const eventName = type === 'pause' ? aitLifecyclePauseEvent : aitLifecycleResumeEvent;
-    let lastFiredAt = Number.NEGATIVE_INFINITY;
-    const fire = () => {
-        const now = Date.now();
-        if (now - lastFiredAt < lifecycleEventDedupeWindowMs) {
-            return;
+    const pauses = new Set();
+    const resumes = new Set();
+    let nativePaused = false;
+    let pageActive = true;
+    let attached = false;
+    let active = documentTarget?.visibilityState !== 'hidden';
+    const notify = (callback) => {
+        try {
+            void Promise.resolve(callback()).catch(() => undefined);
         }
-        lastFiredAt = now;
-        callback();
+        catch { /* Keep lifecycle observation alive. */ }
     };
-    const handleCustomEvent = () => fire();
-    const handleVisibilityChange = () => {
-        if (documentTarget?.visibilityState === (type === 'pause' ? 'hidden' : 'visible')) {
-            fire();
+    function reconcile() {
+        const next = !nativePaused && pageActive && documentTarget?.visibilityState !== 'hidden';
+        if (next === active) {
+            return;
+        }
+        active = next;
+        for (const callback of [...(active ? resumes : pauses)]) {
+            notify(callback);
         }
+    }
+    const nativePause = () => {
+        nativePaused = true;
+        reconcile();
+    };
+    const nativeResume = () => {
+        nativePaused = false;
+        reconcile();
     };
-    const handlePageTransition = () => fire();
-    target.addEventListener?.(eventName, handleCustomEvent);
-    documentTarget?.addEventListener('visibilitychange', handleVisibilityChange);
-    target.addEventListener?.(type === 'pause' ? 'pagehide' : 'pageshow', handlePageTransition);
-    return () => {
-        target.removeEventListener?.(eventName, handleCustomEvent);
-        documentTarget?.removeEventListener('visibilitychange', handleVisibilityChange);
-        target.removeEventListener?.(type === 'pause' ? 'pagehide' : 'pageshow', handlePageTransition);
+    const pageHide = () => {
+        pageActive = false;
+        reconcile();
     };
+    const pageShow = () => {
+        pageActive = true;
+        reconcile();
+    };
+    function attach() {
+        if (attached) {
+            return;
+        }
+        attached = true;
+        target.addEventListener?.(aitLifecyclePauseEvent, nativePause);
+        target.addEventListener?.(aitLifecycleResumeEvent, nativeResume);
+        target.addEventListener?.('pagehide', pageHide);
+        target.addEventListener?.('pageshow', pageShow);
+        documentTarget?.addEventListener('visibilitychange', reconcile);
+    }
+    function detach() {
+        if (!attached) {
+            return;
+        }
+        attached = false;
+        target.removeEventListener?.(aitLifecyclePauseEvent, nativePause);
+        target.removeEventListener?.(aitLifecycleResumeEvent, nativeResume);
+        target.removeEventListener?.('pagehide', pageHide);
+        target.removeEventListener?.('pageshow', pageShow);
+        documentTarget?.removeEventListener('visibilitychange', reconcile);
+    }
+    function subscribe(callbacks, callback) {
+        callbacks.add(callback);
+        attach();
+        if (callbacks === pauses && !active) {
+            notify(callback);
+        }
+        return () => {
+            callbacks.delete(callback);
+            if (pauses.size + resumes.size === 0) {
+                detach();
+            }
+        };
+    }
+    return {
+        onPause: (callback) => subscribe(pauses, callback),
+        onResume: (callback) => subscribe(resumes, callback),
+        async dispose() {
+            pauses.clear();
+            resumes.clear();
+            detach();
+        },
+    };
+}
+export function dispatchAitLifecycleEvent(type) {
+    globalThis.dispatchEvent?.(new Event(type === 'pause' ? aitLifecyclePauseEvent : aitLifecycleResumeEvent));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-ait",
-  "version": "0.12.6",
+  "version": "0.13.0",
   "description": "Apps in Toss WebView platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -59,8 +59,8 @@
     "dist"
   ],
   "dependencies": {
-    "@mpgd/bridge": "0.10.0",
-    "@mpgd/platform": "0.14.0"
+    "@mpgd/platform": "0.15.0",
+    "@mpgd/bridge": "0.11.0"
   },
   "peerDependencies": {
     "@apps-in-toss/web-framework": ">=3.0.0 <4"
@@ -71,10 +71,12 @@
     }
   },
   "devDependencies": {
+    "@types/node": "^24.0.0",
     "@apps-in-toss/web-framework": "3.5.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@mpgd/game-runtime": "0.3.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",