@mpgd/adapter-ait 0.9.0 → 0.11.0

package/dist/ad-config.d.ts

@@ -1,5 +1,6 @@
+export type AitAdPlacementType = 'rewarded' | 'interstitial' | 'banner';
 export interface AitAdBridgeConfig {
   readonly adGroupIds: Readonly<Record<string, string>>;
-  readonly adPlacementTypes: Readonly<Record<string, 'rewarded' | 'interstitial'>>;
+  readonly adPlacementTypes: Readonly<Record<string, AitAdPlacementType>>;
 }
 export declare function extractAitAdBridgeConfig(input: unknown, sourceLabel?: string): AitAdBridgeConfig;

package/dist/ad-config.js

@@ -9,7 +9,7 @@ export function extractAitAdBridgeConfig(input, sourceLabel = 'ad placements') {
     for (const [placementIndex, placement] of placements.entries()) {
         if (!isRecord(placement)
             || typeof placement.id !== 'string'
-            || (placement.type !== 'rewarded' && placement.type !== 'interstitial')) {
+            || !isAitAdPlacementType(placement.type)) {
             throw new Error(`AIT ad placement entry at index ${placementIndex} is invalid: ${sourceLabel}`);
         }
         if (placementIds.has(placement.id)) {
@@ -28,6 +28,9 @@ export function extractAitAdBridgeConfig(input, sourceLabel = 'ad placements') {
     }
     return { adGroupIds, adPlacementTypes };
 }
+function isAitAdPlacementType(value) {
+    return value === 'rewarded' || value === 'interstitial' || value === 'banner';
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/host.d.ts

@@ -1,5 +1,6 @@
-import { getTossShareLink, grantPromotionRewardForGame as grantPromotionReward, IAP, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, requestNotificationAgreement, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';
+import { getTossShareLink, grantPromotionRewardForGame as grantPromotionReward, IAP, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, requestNotificationAgreement, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore, TossAds } from '@apps-in-toss/web-framework';
 import type { Entitlement, LogicalProductId, NotificationTopic, ShareResult } from '@mpgd/platform';
+import type { AitAdPlacementType } from './ad-config.js';
 import type { GamePlatformBridge } from './index.js';
 export type AitIdentityProvider = () => Promise<unknown>;
 /**
@@ -18,6 +19,10 @@ interface AitIapDependencies {
   readonly getPendingOrders: AitNativeMethod<typeof IAP.getPendingOrders>;
   readonly completeProductGrant: AitNativeMethod<typeof IAP.completeProductGrant>;
 }
+interface AitBannerDependencies {
+  readonly initialize: typeof TossAds.initialize;
+  readonly attachBanner: typeof TossAds.attachBanner;
+}
 export interface AitHostDependencies {
   readonly identityProvider: AitIdentityProvider;
   readonly storage: Pick<typeof Storage, 'getItem' | 'removeItem' | 'setItem'>;
@@ -28,6 +33,7 @@ export interface AitHostDependencies {
   readonly isMinVersionSupported: typeof isMinVersionSupported;
   readonly loadFullScreenAd: AitNativeMethod<typeof loadFullScreenAd>;
   readonly showFullScreenAd: AitNativeMethod<typeof showFullScreenAd>;
+  readonly tossAds: AitBannerDependencies;
   readonly openGameCenterLeaderboard: AitNativeMethod<typeof openGameCenterLeaderboard>;
   readonly submitGameCenterLeaderBoardScore: AitNativeMethod<typeof submitGameCenterLeaderBoardScore>;
   readonly iap: AitIapDependencies;
@@ -108,10 +114,15 @@ export type AitPromotionGrantAuthorization = {
 * single-use game claim.
 */
 export type AitPromotionGrantAuthorizer = (input: AitPromotionGrantAuthorizationInput) => Promise<AitPromotionGrantAuthorization>;
+export interface AitBannerAppearance {
+  readonly theme?: 'auto' | 'light' | 'dark';
+  readonly tone?: 'blackAndWhite' | 'grey';
+  readonly variant?: 'card' | 'expanded';
+}
 export interface InstallAitHostBridgeOptions {
   readonly appName?: string;
   readonly adGroupIds?: Readonly<Record<string, string>>;
-  readonly adPlacementTypes?: Readonly<Record<string, 'rewarded' | 'interstitial'>>;
+  readonly adPlacementTypes?: Readonly<Record<string, AitAdPlacementType>>;
   /** Logical campaign ids mapped to console-issued Apps in Toss promotion configuration. */
   readonly promotionRewards?: Readonly<Record<string, AitPromotionRewardConfig>>;
   readonly authorizePromotionGrant?: AitPromotionGrantAuthorizer;
@@ -134,6 +145,10 @@ export interface InstallAitHostBridgeOptions {
   readonly adDisplayStartTimeoutMs?: number;
   /** Last-resort cleanup when the native SDK omits its terminal display callback. */
   readonly adMaximumDisplayMs?: number;
+  /** Maximum wait for an inline banner to render or report no-fill/failure. */
+  readonly bannerRenderTimeoutMs?: number;
+  /** Provider-neutral host preference mapped to the Apps in Toss banner appearance. */
+  readonly bannerAppearance?: AitBannerAppearance;
   readonly dependencies?: Partial<AitHostDependencies>;
 }
 export declare function installAitHostBridge(options?: InstallAitHostBridgeOptions): GamePlatformBridge;

package/dist/host.js

@@ -1,10 +1,11 @@
-import { getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame as grantPromotionReward, IAP, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, requestNotificationAgreement, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore, } from '@apps-in-toss/web-framework';
+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 { dispatchAitLifecycleEvent } from './lifecycle.js';
 const defaultAdTimeoutMs = 60000;
 const defaultAdLoadQueueTimeoutMs = 5000;
 const defaultAdDisplayStartTimeoutMs = 60000;
 const defaultAdMaximumDisplayMs = 30 * 60000;
+const defaultBannerRenderTimeoutMs = 15000;
 /** Leaves five seconds of headroom inside the native IAP 30-second grant callback. */
 const defaultIapProductGrantTimeoutMs = 25000;
 /** Bounds abandoned checkout UI while still allowing the user to finish an interactive purchase. */
@@ -53,6 +54,7 @@ const defaultDependencies = {
     isMinVersionSupported,
     loadFullScreenAd,
     showFullScreenAd,
+    tossAds: TossAds,
     openGameCenterLeaderboard,
     submitGameCenterLeaderBoardScore,
     iap: IAP,
@@ -80,11 +82,21 @@ export function createAitHostBridge(options = {}) {
     const loadedAdGroupIds = new Set();
     const loadingAdGroups = new Map();
     const activeAdGroupIds = new Set();
+    const activeBannerAttachments = new Map();
+    const bannerMountOwners = new Map();
+    const pendingBannerMountSettlements = new Map();
+    let bannerInitialization;
     let warnedUnsupportedAdPreload = false;
     const adTimeoutMs = normalizeTimeout(options.adTimeoutMs);
     const adLoadQueueTimeoutMs = normalizeLoadQueueTimeout(options.adLoadQueueTimeoutMs);
     const adDisplayStartTimeoutMs = normalizeDisplayStartTimeout(options.adDisplayStartTimeoutMs);
     const adMaximumDisplayMs = normalizeMaximumDisplayTimeout(options.adMaximumDisplayMs);
+    const bannerRenderTimeoutMs = normalizeBannerRenderTimeout(options.bannerRenderTimeoutMs);
+    const bannerAppearance = {
+        theme: options.bannerAppearance?.theme ?? 'dark',
+        tone: options.bannerAppearance?.tone ?? 'blackAndWhite',
+        variant: options.bannerAppearance?.variant ?? 'expanded',
+    };
     const adLoadCoordinator = {
         active: undefined,
         waitTimeoutMs: adLoadQueueTimeoutMs,
@@ -116,6 +128,8 @@ export function createAitHostBridge(options = {}) {
                     && hasConfiguredAdType(adGroupIds, adPlacementTypes, 'rewarded');
                 const interstitialAds = adsSupported
                     && hasConfiguredAdType(adGroupIds, adPlacementTypes, 'interstitial');
+                const bannerAds = areBannerAdsSupported(dependencies)
+                    && hasConfiguredAdType(adGroupIds, adPlacementTypes, 'banner');
                 const nativeIap = isAitIapSupported({
                     dependencies,
                     products: iapProducts,
@@ -126,7 +140,8 @@ export function createAitHostBridge(options = {}) {
                 });
                 return ok(request, {
                     nativeIap,
-                    nativeAds: rewardedAds || interstitialAds,
+                    nativeAds: rewardedAds || interstitialAds || bannerAds,
+                    bannerAds,
                     rewardedAds,
                     interstitialAds,
                     nativeLeaderboard: isGameCenterSupported(dependencies),
@@ -315,6 +330,9 @@ export function createAitHostBridge(options = {}) {
                 if (adGroupId === undefined || placementType === undefined) {
                     return createBridgeError(request.id, 'AIT_AD_UNAVAILABLE', `AIT ad placement is unavailable: ${placementId}`);
                 }
+                if (placementType === 'banner') {
+                    return ok(request, {});
+                }
                 if (!isAitNativeMethodSupported(dependencies.loadFullScreenAd)) {
                     if (!warnedUnsupportedAdPreload) {
                         warnedUnsupportedAdPreload = true;
@@ -370,6 +388,61 @@ export function createAitHostBridge(options = {}) {
                 const shown = await withLoadedAdSlot(dependencies, adGroupId, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, activeAdGroupIds, adTimeoutMs, 'interstitial', showInterstitial);
                 return ok(request, shown.acquired ? shown.value : { status: 'unavailable' });
             }
+            case 'ads.mountBanner': {
+                const placementId = readPlacementId(request.payload);
+                const surfaceId = readBannerSurfaceId(request.payload);
+                const adGroupId = adGroupIds.get(placementId);
+                if (adGroupId === undefined
+                    || adPlacementTypes.get(placementId) !== 'banner'
+                    || !areBannerAdsSupported(dependencies)) {
+                    return ok(request, { status: 'unavailable' });
+                }
+                const target = globalThis.document?.getElementById(surfaceId);
+                if (target === null || target === undefined) {
+                    return ok(request, { status: 'failed' });
+                }
+                pendingBannerMountSettlements.get(surfaceId)?.settleUnavailable();
+                const mountOwner = Symbol(surfaceId);
+                bannerMountOwners.set(surfaceId, mountOwner);
+                activeBannerAttachments.get(surfaceId)?.destroy();
+                activeBannerAttachments.delete(surfaceId);
+                const initializeBanner = bannerInitialization
+                    ?? initializeAitBannerAds(dependencies, bannerRenderTimeoutMs);
+                void (bannerInitialization = initializeBanner);
+                if (!await initializeBanner) {
+                    bannerInitialization = undefined;
+                    if (bannerMountOwners.get(surfaceId) === mountOwner) {
+                        bannerMountOwners.delete(surfaceId);
+                    }
+                    return ok(request, { status: 'failed' });
+                }
+                if (bannerMountOwners.get(surfaceId) !== mountOwner) {
+                    return ok(request, { status: 'unavailable' });
+                }
+                activeBannerAttachments.get(surfaceId)?.destroy();
+                activeBannerAttachments.delete(surfaceId);
+                const result = await attachAitBanner({
+                    dependencies,
+                    adGroupId,
+                    surfaceId,
+                    target,
+                    timeoutMs: bannerRenderTimeoutMs,
+                    appearance: bannerAppearance,
+                    activeAttachments: activeBannerAttachments,
+                    mountOwner,
+                    mountOwners: bannerMountOwners,
+                    pendingSettlements: pendingBannerMountSettlements,
+                });
+                return ok(request, result);
+            }
+            case 'ads.unmountBanner': {
+                const surfaceId = readBannerSurfaceId(request.payload);
+                pendingBannerMountSettlements.get(surfaceId)?.settleUnavailable();
+                bannerMountOwners.delete(surfaceId);
+                activeBannerAttachments.get(surfaceId)?.destroy();
+                activeBannerAttachments.delete(surfaceId);
+                return ok(request, {});
+            }
             case 'leaderboard.submitScore': {
                 if (!isGameCenterSupported(dependencies)) {
                     return ok(request, { submitted: false });
@@ -1837,6 +1910,122 @@ function areFullScreenAdsSupported(dependencies) {
     return isAitNativeMethodSupported(dependencies.loadFullScreenAd)
         && isAitNativeMethodSupported(dependencies.showFullScreenAd);
 }
+function areBannerAdsSupported(dependencies) {
+    return isAitNativeMethodSupported(dependencies.tossAds.initialize)
+        && isAitNativeMethodSupported(dependencies.tossAds.attachBanner);
+}
+function initializeAitBannerAds(dependencies, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (initialized) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            globalThis.clearTimeout(timer);
+            resolve(initialized);
+        };
+        const timer = globalThis.setTimeout(() => finish(false), timeoutMs);
+        try {
+            dependencies.tossAds.initialize({
+                callbacks: {
+                    onInitialized: () => finish(true),
+                    onInitializationFailed: () => finish(false),
+                },
+            });
+        }
+        catch (error) {
+            console.warn('Failed to initialize AIT banner ads.', error);
+            finish(false);
+        }
+    });
+}
+async function attachAitBanner(input) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let terminalStatus;
+        let attachment;
+        const finish = (requestedStatus) => {
+            const ownsSurface = input.mountOwners.get(input.surfaceId) === input.mountOwner;
+            const status = requestedStatus === 'mounted' && !ownsSurface
+                ? 'unavailable'
+                : requestedStatus;
+            if (settled) {
+                if (status !== 'mounted' && input.activeAttachments.get(input.surfaceId) === attachment) {
+                    attachment?.destroy();
+                    input.activeAttachments.delete(input.surfaceId);
+                }
+                if (status !== 'mounted' && ownsSurface) {
+                    input.mountOwners.delete(input.surfaceId);
+                }
+                return;
+            }
+            settled = true;
+            terminalStatus = status;
+            globalThis.clearTimeout(timer);
+            if (input.pendingSettlements.get(input.surfaceId)?.mountOwner === input.mountOwner) {
+                input.pendingSettlements.delete(input.surfaceId);
+            }
+            if (status !== 'mounted') {
+                attachment?.destroy();
+                if (input.activeAttachments.get(input.surfaceId) === attachment) {
+                    input.activeAttachments.delete(input.surfaceId);
+                }
+                if (ownsSurface) {
+                    input.mountOwners.delete(input.surfaceId);
+                }
+            }
+            resolve({ status });
+        };
+        const timer = globalThis.setTimeout(() => finish('failed'), input.timeoutMs);
+        input.pendingSettlements.set(input.surfaceId, {
+            mountOwner: input.mountOwner,
+            settleUnavailable: () => finish('unavailable'),
+        });
+        try {
+            const sdkAttachment = input.dependencies.tossAds.attachBanner(input.adGroupId, input.target, {
+                theme: input.appearance.theme,
+                tone: input.appearance.tone,
+                variant: input.appearance.variant,
+                callbacks: {
+                    onAdRendered: () => finish('mounted'),
+                    onNoFill: () => finish('unavailable'),
+                    onAdFailedToRender: (payload) => {
+                        console.warn('Failed to render an AIT banner ad.', input.adGroupId, payload.error);
+                        finish('failed');
+                    },
+                },
+            });
+            let attachmentDestroyed = false;
+            attachment = {
+                destroy() {
+                    if (!attachmentDestroyed) {
+                        attachmentDestroyed = true;
+                        sdkAttachment.destroy();
+                    }
+                },
+            };
+            if (terminalStatus === 'unavailable' || terminalStatus === 'failed') {
+                attachment.destroy();
+                return;
+            }
+            if (input.mountOwners.get(input.surfaceId) !== input.mountOwner) {
+                attachment.destroy();
+                finish('unavailable');
+                return;
+            }
+            const existingAttachment = input.activeAttachments.get(input.surfaceId);
+            if (existingAttachment !== undefined && existingAttachment !== attachment) {
+                existingAttachment.destroy();
+            }
+            input.activeAttachments.set(input.surfaceId, attachment);
+        }
+        catch (error) {
+            console.warn('Failed to attach an AIT banner ad.', input.adGroupId, error);
+            finish('failed');
+        }
+    });
+}
 function isAitNativeMethodSupported(method) {
     return isCapabilitySupported(() => method.isSupported?.() === true);
 }
@@ -1930,6 +2119,9 @@ function normalizeDisplayStartTimeout(value) {
 function normalizeMaximumDisplayTimeout(value) {
     return normalizePositiveTimeout(value, defaultAdMaximumDisplayMs, 'AIT ad maximum display timeout must be a positive finite number.');
 }
+function normalizeBannerRenderTimeout(value) {
+    return normalizePositiveTimeout(value, defaultBannerRenderTimeoutMs, 'AIT banner render timeout must be a positive finite number.');
+}
 function normalizeIapProductGrantTimeout(value) {
     const timeout = normalizePositiveTimeout(value, defaultIapProductGrantTimeoutMs, 'AIT IAP product-grant timeout must be a positive finite number.');
     if (timeout > defaultIapProductGrantTimeoutMs) {
@@ -1960,6 +2152,13 @@ function readPlacementId(payload) {
     }
     return placementId;
 }
+function readBannerSurfaceId(payload) {
+    const surfaceId = readPayloadRecord(payload).surfaceId;
+    if (typeof surfaceId !== 'string' || surfaceId.length === 0) {
+        throw new TypeError('AIT banner surfaceId must be a valid non-empty element id.');
+    }
+    return surfaceId;
+}
 function readIdempotencyKey(payload, fallback) {
     const value = readPayloadRecord(payload).idempotencyKey;
     return typeof value === 'string' && value.length > 0 ? value : fallback;

package/dist/index.js

@@ -58,6 +58,8 @@ export function createAitPlatformGateway(input) {
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
             showInterstitial: (payload) => request('ads.showInterstitial', payload),
+            mountBanner: (payload) => request('ads.mountBanner', payload),
+            unmountBanner: (payload) => request('ads.unmountBanner', payload),
         },
         leaderboard: {
             submitScore: (payload) => request('leaderboard.submitScore', payload),
@@ -95,6 +97,7 @@ export function createAitSandboxBridge(options = {}) {
                     return ok(input, {
                         nativeIap: true,
                         nativeAds: true,
+                        bannerAds: false,
                         rewardedAds: true,
                         interstitialAds: true,
                         nativeLeaderboard: true,
@@ -178,6 +181,10 @@ export function createAitSandboxBridge(options = {}) {
                     return ok(input, {
                         status: 'shown',
                     });
+                case 'ads.mountBanner':
+                    return ok(input, { status: 'unavailable' });
+                case 'ads.unmountBanner':
+                    return ok(input, {});
                 case 'leaderboard.submitScore':
                     return ok(input, {
                         submitted: true,

package/dist/local-mock.d.ts

@@ -6,6 +6,17 @@
 * commerce: those paths must be verified in the Toss app sandbox/console.
 */
 declare function unsupported(): boolean;
+/**
+* Local browsers have no native safe-area constant. Throwing preserves the
+* wrapper's CSS `env(safe-area-inset-*)` fallback while keeping ESM exports in
+* parity with the SDK surface consumed by the adapter.
+*/
+export declare const SafeArea: {
+  get(): never;
+  subscribe(_input: {
+    readonly onEvent: (insets: unknown) => void;
+  }): () => void;
+};
 export declare const Storage: {
   getItem(key: string): Promise<string | null>;
   setItem(key: string, value: string): Promise<void>;
@@ -30,6 +41,22 @@ export declare const loadFullScreenAd: ((_callbacks: unknown) => (() => void)) &
 export declare const showFullScreenAd: ((_callbacks: unknown) => (() => void)) & {
   isSupported: typeof unsupported;
 };
+export declare const TossAds: {
+  initialize: ((_options: unknown) => void) & {
+    isSupported: typeof unsupported;
+  };
+  attachBanner: ((_adGroupId: string, _target: string | HTMLElement, _options?: unknown) => {
+    destroy(): void;
+  }) & {
+    isSupported: typeof unsupported;
+  };
+  destroy: ((_slotId: string) => void) & {
+    isSupported: typeof unsupported;
+  };
+  destroyAll: (() => void) & {
+    isSupported: typeof unsupported;
+  };
+};
 export declare function openGameCenterLeaderboard(): Promise<void>;
 export declare function submitGameCenterLeaderBoardScore(): Promise<{
   readonly statusCode: 'ERROR';

package/dist/local-mock.js

@@ -12,6 +12,19 @@ function unsupported() {
 function noOpSubscription() {
     return () => { };
 }
+/**
+ * Local browsers have no native safe-area constant. Throwing preserves the
+ * wrapper's CSS `env(safe-area-inset-*)` fallback while keeping ESM exports in
+ * parity with the SDK surface consumed by the adapter.
+ */
+export const SafeArea = {
+    get() {
+        throw new Error('SafeArea is unavailable in the Apps in Toss local mock.');
+    },
+    subscribe(_input) {
+        return noOpSubscription();
+    },
+};
 export const Storage = {
     async getItem(key) {
         return localStorageValues.get(key) ?? null;
@@ -39,6 +52,14 @@ export const grantPromotionRewardForGame = Object.assign(async () => 'ERROR', {
 export const requestNotificationAgreement = Object.assign((_callbacks) => noOpSubscription(), { isSupported: unsupported });
 export const loadFullScreenAd = Object.assign((_callbacks) => noOpSubscription(), { isSupported: unsupported });
 export const showFullScreenAd = Object.assign((_callbacks) => noOpSubscription(), { isSupported: unsupported });
+export const TossAds = {
+    initialize: Object.assign((_options) => { }, { isSupported: unsupported }),
+    attachBanner: Object.assign((_adGroupId, _target, _options) => ({
+        destroy() { },
+    }), { isSupported: unsupported }),
+    destroy: Object.assign((_slotId) => { }, { isSupported: unsupported }),
+    destroyAll: Object.assign(() => { }, { isSupported: unsupported }),
+};
 export async function openGameCenterLeaderboard() { }
 export async function submitGameCenterLeaderBoardScore() {
     return { statusCode: 'ERROR' };

package/dist/safe-area.d.ts

@@ -0,0 +1,54 @@
+/** Raw Apps in Toss safe-area values expressed in CSS pixels. */
+export interface AitSafeAreaInsets {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+/** Minimal SDK surface kept injectable for deterministic wrapper tests. */
+export interface AitSafeAreaSource {
+  get(): unknown;
+  subscribe(input: {
+    readonly onEvent: (insets: unknown) => void;
+  }): () => void;
+}
+/** Minimal CSS declaration surface required by the bridge. */
+export interface AitSafeAreaCssStyle {
+  getPropertyValue(property: string): string;
+  getPropertyPriority?(property: string): string;
+  setProperty(property: string, value: string, priority?: string): void;
+  removeProperty(property: string): string;
+}
+export interface InstallAitSafeAreaCssVariablesOptions {
+  readonly source?: AitSafeAreaSource;
+  readonly style?: AitSafeAreaCssStyle;
+  /** Override only when a host version or custom navigation treatment has a measured band. */
+  readonly navigationControlBandHeightPx?: number;
+  /** Override only when native navigation uses a measured right-edge gap. */
+  readonly navigationControlEdgeGapPx?: number;
+}
+/**
+* Apps in Toss positions the game navigation controls immediately below the
+* native top safe area. Keep full-width app chrome below this additional band.
+*/
+export declare const aitNavigationControlBandHeightPx = 52;
+/** Apps in Toss navigation controls retain this edge gap from the safe right inset. */
+export declare const aitNavigationControlEdgeGapPx = 10;
+/** CSS contract shared by generated AIT wrappers and full-bleed games. */
+export declare const aitSafeAreaCssVariables: Readonly<{
+  readonly top: '--mpgd-safe-area-top';
+  readonly right: '--mpgd-safe-area-right';
+  readonly bottom: '--mpgd-safe-area-bottom';
+  readonly left: '--mpgd-safe-area-left';
+  readonly navigationControlTop: '--mpgd-ait-navigation-control-top';
+  readonly navigationControlRight: '--mpgd-ait-navigation-control-right';
+  readonly navigationContentTop: '--mpgd-ait-navigation-content-top';
+}>;
+/**
+* Mirror the official AIT `SafeArea` snapshot into CSS custom properties and
+* keep them current when the WebView changes presentation or orientation.
+*
+* CSS `env(safe-area-inset-*)` remains the wrapper's pre-SDK fallback. Invalid
+* or unavailable native values never overwrite that fallback.
+*/
+export declare function installAitSafeAreaCssVariables(options?: InstallAitSafeAreaCssVariablesOptions): () => void;

package/dist/safe-area.js

@@ -0,0 +1,132 @@
+import { SafeArea } from '@apps-in-toss/web-framework';
+/**
+ * Apps in Toss positions the game navigation controls immediately below the
+ * native top safe area. Keep full-width app chrome below this additional band.
+ */
+export const aitNavigationControlBandHeightPx = 52;
+/** Apps in Toss navigation controls retain this edge gap from the safe right inset. */
+export const aitNavigationControlEdgeGapPx = 10;
+/** CSS contract shared by generated AIT wrappers and full-bleed games. */
+export const aitSafeAreaCssVariables = Object.freeze({
+    top: '--mpgd-safe-area-top',
+    right: '--mpgd-safe-area-right',
+    bottom: '--mpgd-safe-area-bottom',
+    left: '--mpgd-safe-area-left',
+    navigationControlTop: '--mpgd-ait-navigation-control-top',
+    navigationControlRight: '--mpgd-ait-navigation-control-right',
+    navigationContentTop: '--mpgd-ait-navigation-content-top',
+});
+const maximumSafeAreaInsetPx = 4096;
+const maximumCssPixelOptionPx = 4096;
+/**
+ * Mirror the official AIT `SafeArea` snapshot into CSS custom properties and
+ * keep them current when the WebView changes presentation or orientation.
+ *
+ * CSS `env(safe-area-inset-*)` remains the wrapper's pre-SDK fallback. Invalid
+ * or unavailable native values never overwrite that fallback.
+ */
+export function installAitSafeAreaCssVariables(options = {}) {
+    const navigationControlBandHeightPx = normalizeCssPixelOption(options.navigationControlBandHeightPx, aitNavigationControlBandHeightPx, 'navigationControlBandHeightPx');
+    const navigationControlEdgeGapPx = normalizeCssPixelOption(options.navigationControlEdgeGapPx, aitNavigationControlEdgeGapPx, 'navigationControlEdgeGapPx');
+    const style = options.style ?? resolveDocumentRootStyle();
+    if (style === undefined) {
+        return () => { };
+    }
+    const source = options.source ?? SafeArea;
+    const previous = rememberCssVariables(style);
+    let active = true;
+    let unsubscribe = () => { };
+    const apply = (input) => {
+        if (!active) {
+            return;
+        }
+        const insets = normalizeAitSafeAreaInsets(input);
+        if (insets === null) {
+            return;
+        }
+        style.setProperty(aitSafeAreaCssVariables.top, formatCssPixels(insets.top));
+        style.setProperty(aitSafeAreaCssVariables.right, formatCssPixels(insets.right));
+        style.setProperty(aitSafeAreaCssVariables.bottom, formatCssPixels(insets.bottom));
+        style.setProperty(aitSafeAreaCssVariables.left, formatCssPixels(insets.left));
+        style.setProperty(aitSafeAreaCssVariables.navigationControlTop, formatCssPixels(insets.top));
+        style.setProperty(aitSafeAreaCssVariables.navigationControlRight, formatCssPixels(insets.right + navigationControlEdgeGapPx));
+        style.setProperty(aitSafeAreaCssVariables.navigationContentTop, formatCssPixels(insets.top + navigationControlBandHeightPx));
+    };
+    try {
+        apply(source.get());
+    }
+    catch {
+        // Local browsers and older Toss hosts keep the CSS env() fallback.
+    }
+    try {
+        const subscribed = source.subscribe({ onEvent: apply });
+        unsubscribe = typeof subscribed === 'function' ? subscribed : () => { };
+    }
+    catch {
+        // A missing native event bridge must not prevent the game from booting.
+    }
+    return () => {
+        if (!active) {
+            return;
+        }
+        active = false;
+        try {
+            unsubscribe();
+        }
+        finally {
+            restoreCssVariables(style, previous);
+        }
+    };
+}
+function normalizeAitSafeAreaInsets(input) {
+    if (typeof input !== 'object' || input === null) {
+        return null;
+    }
+    const record = input;
+    const top = normalizeInset(record.top);
+    const right = normalizeInset(record.right);
+    const bottom = normalizeInset(record.bottom);
+    const left = normalizeInset(record.left);
+    if (top === null || right === null || bottom === null || left === null) {
+        return null;
+    }
+    return { top, right, bottom, left };
+}
+function normalizeInset(input) {
+    return typeof input === 'number'
+        && Number.isFinite(input)
+        && input >= 0
+        && input <= maximumSafeAreaInsetPx
+        ? input
+        : null;
+}
+function normalizeCssPixelOption(input, fallback, name) {
+    const value = input ?? fallback;
+    if (!Number.isFinite(value) || value < 0 || value > maximumCssPixelOptionPx) {
+        throw new TypeError(`${name} must be a non-negative finite CSS pixel value.`);
+    }
+    return value;
+}
+function formatCssPixels(value) {
+    return `${Object.is(value, -0) ? 0 : value}px`;
+}
+function resolveDocumentRootStyle() {
+    return typeof document === 'undefined' ? undefined : document.documentElement.style;
+}
+function rememberCssVariables(style) {
+    return Object.values(aitSafeAreaCssVariables).map((property) => ({
+        property,
+        value: style.getPropertyValue(property),
+        priority: style.getPropertyPriority?.(property) ?? '',
+    }));
+}
+function restoreCssVariables(style, previous) {
+    for (const entry of previous) {
+        if (entry.value.length === 0) {
+            style.removeProperty(entry.property);
+        }
+        else {
+            style.setProperty(entry.property, entry.value, entry.priority);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-ait",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Apps in Toss WebView platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -45,14 +45,18 @@
       "types": "./dist/local-mock.d.ts",
       "default": "./dist/local-mock.js"
     },
+    "./safe-area": {
+      "types": "./dist/safe-area.d.ts",
+      "default": "./dist/safe-area.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@mpgd/bridge": "0.8.0",
-    "@mpgd/platform": "0.9.0"
+    "@mpgd/bridge": "0.9.0",
+    "@mpgd/platform": "0.10.0"
   },
   "peerDependencies": {
     "@apps-in-toss/web-framework": ">=3.0.0 <4"
@@ -63,7 +67,7 @@
     }
   },
   "devDependencies": {
-    "@apps-in-toss/web-framework": "3.0.2",
+    "@apps-in-toss/web-framework": "3.1.1",
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
     "vitest": "^4.0.0"