@mpgd/platform 0.9.0 → 0.10.0

package/dist/capability-conformance.d.ts

@@ -1,5 +1,6 @@
 import type { PlatformCapabilities, PlatformGateway, PlatformTarget } from './index.js';
 export declare const platformCapabilityKeys: readonly ["nativeIap", "nativeAds", "rewardedAds", "interstitialAds", "nativeLeaderboard", "remoteLeaderboard", "achievements", "cloudSave", "socialShare", "haptics", "localizedContent"];
+export declare const optionalPlatformCapabilityKeys: readonly ["bannerAds"];
 export interface PlatformGatewayCapabilityConformanceTransition {
   readonly update: () => Promise<void> | void;
   readonly expectedCapabilities: PlatformCapabilities;

package/dist/capability-conformance.js

@@ -11,6 +11,15 @@ export const platformCapabilityKeys = Object.freeze([
     'haptics',
     'localizedContent',
 ]);
+export const optionalPlatformCapabilityKeys = Object.freeze([
+    'bannerAds',
+]);
+const allowedPlatformCapabilityKeys = Object.freeze([
+    ...platformCapabilityKeys,
+    ...optionalPlatformCapabilityKeys,
+]);
+const allowedPlatformCapabilityKeySet = new Set(allowedPlatformCapabilityKeys);
+const optionalPlatformCapabilityKeySet = new Set(optionalPlatformCapabilityKeys);
 /**
  * Runs provider-neutral capability checks against real adapter gateways or
  * target-configured wrappers. Every read must return a complete boolean
@@ -61,11 +70,15 @@ async function runFixture(fixture) {
 }
 function assertCapabilitySnapshot(actual, expected) {
     const actualKeys = Object.keys(actual).sort();
-    const expectedKeys = [...platformCapabilityKeys].sort();
-    assertEqual(JSON.stringify(actualKeys), JSON.stringify(expectedKeys), 'capability snapshots must contain exactly the public capability keys');
-    for (const key of platformCapabilityKeys) {
-        assertEqual(typeof actual[key], 'boolean', `capability ${key} must be a boolean`);
-        assertEqual(actual[key], expected[key], `capability ${key} must match the expected provider state`);
+    const missingKeys = platformCapabilityKeys.filter((key) => !Object.hasOwn(actual, key));
+    const unexpectedKeys = actualKeys.filter((key) => !allowedPlatformCapabilityKeySet.has(key));
+    assertEqual(JSON.stringify({ missingKeys, unexpectedKeys }), JSON.stringify({ missingKeys: [], unexpectedKeys: [] }), 'capability snapshots must contain all required keys and no unknown keys');
+    for (const key of allowedPlatformCapabilityKeys) {
+        const optional = optionalPlatformCapabilityKeySet.has(key);
+        if (!optional || Object.hasOwn(actual, key)) {
+            assertEqual(typeof actual[key], 'boolean', `capability ${key} must be a boolean`);
+        }
+        assertEqual(optional ? (actual[key] ?? false) : actual[key], optional ? (expected[key] ?? false) : expected[key], `capability ${key} must match the expected provider state`);
     }
 }
 function tryMutateSnapshot(snapshot) {
@@ -77,7 +90,8 @@ function tryMutateSnapshot(snapshot) {
     }
 }
 function hasCapabilityDifference(first, second) {
-    return platformCapabilityKeys.some((key) => first[key] !== second[key]);
+    return allowedPlatformCapabilityKeys
+        .some((key) => (first[key] ?? false) !== (second[key] ?? false));
 }
 function assert(condition, message) {
     if (!condition) {

package/dist/index.d.ts

@@ -47,6 +47,16 @@ export interface RewardedAdResult {
 export interface InterstitialAdResult {
   readonly status: 'shown' | 'skipped' | 'unavailable';
 }
+/**
+* Result of mounting a platform-rendered inline banner into a game-owned surface.
+* The platform host owns the native/SDK attachment; games only reserve and name
+* a surface, so this contract does not leak DOM or provider types. Adapters must
+* release any partial attachment before resolving `unavailable` or `failed`;
+* games only need to unmount a successfully mounted banner.
+*/
+export interface BannerAdMountResult {
+  readonly status: 'mounted' | 'unavailable' | 'failed';
+}
 export interface CommerceAdapter {
   getProducts(): Promise<readonly ProductInfo[]>;
   purchase(input: {
@@ -68,6 +78,14 @@ export interface AdAdapter {
   showInterstitial?(input: {
     readonly placementId: LogicalAdPlacementId;
   }): Promise<InterstitialAdResult>;
+  mountBanner?(input: {
+    readonly placementId: LogicalAdPlacementId;
+    /** Host-resolvable identifier for an empty, game-owned inline ad surface. */
+    readonly surfaceId: string;
+  }): Promise<BannerAdMountResult>;
+  unmountBanner?(input: {
+    readonly surfaceId: string;
+  }): Promise<void>;
 }
 export type PromotionRewardAvailability = 'available' | 'configuration-required' | 'unsupported';
 export type PromotionRewardResult = {
@@ -115,6 +133,8 @@ export interface PlatformCapabilities {
   readonly nativeAds: boolean;
   readonly rewardedAds: boolean;
   readonly interstitialAds: boolean;
+  /** Optional for compatibility with adapters published before inline ads. */
+  readonly bannerAds?: boolean;
   readonly nativeLeaderboard: boolean;
   /** A game-owned server leaderboard is available without a native platform surface. */
   readonly remoteLeaderboard: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/platform",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Shared platform gateway, monetization, ads, leaderboard, identity, lifecycle, and storage contracts for mpgd games.",
   "license": "MIT",
   "repository": {