@mpgd/platform 0.12.2 → 0.14.0

package/dist/capability-conformance.d.ts

@@ -1,6 +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 declare const optionalPlatformCapabilityKeys: readonly ["bannerAds", "subscriptionIap"];
 export interface PlatformGatewayCapabilityConformanceTransition {
   readonly update: () => Promise<void> | void;
   readonly expectedCapabilities: PlatformCapabilities;
@@ -27,7 +27,7 @@ export interface PlatformGatewayCapabilityConformanceReport {
 * target-configured wrappers. Every read must return a complete boolean
 * snapshot, a fresh object, and the provider's latest state.
 * @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
-* @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #f83948b Reviewed the required keys, optional banner default, and fresh reread in runFixture.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #a1834db Reviewed required booleans, optional banner/subscription defaults, ordered readiness comparison, and fresh nested rereads.
 * @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
 * @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
 * @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.

package/dist/capability-conformance.js

@@ -13,19 +13,40 @@ export const platformCapabilityKeys = Object.freeze([
 ]);
 export const optionalPlatformCapabilityKeys = Object.freeze([
     'bannerAds',
+    'subscriptionIap',
 ]);
 const allowedPlatformCapabilityKeys = Object.freeze([
     ...platformCapabilityKeys,
     ...optionalPlatformCapabilityKeys,
 ]);
-const allowedPlatformCapabilityKeySet = new Set(allowedPlatformCapabilityKeys);
+const allowedPlatformCapabilityKeySet = new Set([
+    ...allowedPlatformCapabilityKeys,
+    'providerAvailability',
+]);
 const optionalPlatformCapabilityKeySet = new Set(optionalPlatformCapabilityKeys);
+const providerFeatureSet = new Set([
+    'nativeIap',
+    'subscriptionIap',
+    'rewardedAds',
+    'interstitialAds',
+    'bannerAds',
+    'nativeLeaderboard',
+    'identityUpgrade',
+    'pushNotifications',
+]);
+const providerAvailabilitySet = new Set([
+    'unsupported',
+    'configuration-required',
+    'action-required',
+    'temporarily-unavailable',
+    'available',
+]);
 /**
  * Runs provider-neutral capability checks against real adapter gateways or
  * target-configured wrappers. Every read must return a complete boolean
  * snapshot, a fresh object, and the provider's latest state.
  * @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
- * @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #f83948b Reviewed the required keys, optional banner default, and fresh reread in runFixture.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #a1834db Reviewed required booleans, optional banner/subscription defaults, ordered readiness comparison, and fresh nested rereads.
  * @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
  * @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
  * @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.
@@ -60,10 +81,10 @@ export async function runPlatformGatewayCapabilityConformance(input) {
 async function runFixture(fixture) {
     // A fixture may accidentally share its expected object with the provider.
     // Keep the oracle independent before tryMutateSnapshot probes isolation.
-    const initialExpected = { ...fixture.expectedCapabilities };
+    const initialExpected = cloneExpectedCapabilities(fixture.expectedCapabilities);
     const transitionExpected = fixture.transition === undefined
         ? undefined
-        : { ...fixture.transition.expectedCapabilities };
+        : cloneExpectedCapabilities(fixture.transition.expectedCapabilities);
     assertEqual(fixture.gateway.target, fixture.expectedTarget, 'gateway target must match the fixture target');
     const first = await fixture.gateway.getCapabilities();
     assertCapabilitySnapshot(first, initialExpected);
@@ -93,6 +114,29 @@ function assertCapabilitySnapshot(actual, expected) {
         }
         assertEqual(optional ? (actual[key] ?? false) : actual[key], optional ? (expected[key] ?? false) : expected[key], `capability ${key} must match the expected provider state`);
     }
+    assertProviderAvailabilityShape(actual.providerAvailability);
+    assertEqual(normalizedAvailability(actual.providerAvailability), normalizedAvailability(expected.providerAvailability), 'provider availability must match the expected provider state');
+}
+function assertProviderAvailabilityShape(value) {
+    if (value === undefined) {
+        return;
+    }
+    assert(typeof value === 'object' && value !== null && !Array.isArray(value), 'provider availability must be a non-array record');
+    for (const [feature, state] of Object.entries(value)) {
+        assert(providerFeatureSet.has(feature)
+            && providerAvailabilitySet.has(state), 'provider availability must contain only known features and readiness states');
+    }
+}
+function cloneExpectedCapabilities(value) {
+    return {
+        ...value,
+        ...(value.providerAvailability === undefined
+            ? {}
+            : { providerAvailability: { ...value.providerAvailability } }),
+    };
+}
+function normalizedAvailability(value) {
+    return JSON.stringify(Object.entries(value ?? {}).sort(([a], [b]) => a.localeCompare(b)));
 }
 function tryMutateSnapshot(snapshot) {
     try {
@@ -101,10 +145,23 @@ function tryMutateSnapshot(snapshot) {
     catch {
         // Frozen snapshots already satisfy the isolation requirement.
     }
+    if (snapshot.providerAvailability !== undefined) {
+        try {
+            const next = snapshot.providerAvailability.nativeIap === 'available'
+                ? 'unsupported'
+                : 'available';
+            Reflect.set(snapshot.providerAvailability, 'nativeIap', next);
+        }
+        catch {
+            // A frozen nested readiness record already satisfies isolation.
+        }
+    }
 }
 function hasCapabilityDifference(first, second) {
     return allowedPlatformCapabilityKeys
-        .some((key) => (first[key] ?? false) !== (second[key] ?? false));
+        .some((key) => (first[key] ?? false) !== (second[key] ?? false))
+        || normalizedAvailability(first.providerAvailability)
+            !== normalizedAvailability(second.providerAvailability);
 }
 function assert(condition, message) {
     if (!condition) {

package/dist/index.d.ts

@@ -83,7 +83,7 @@ export declare function findAuthoritativePurchaseSettlement(input: {
   readonly restore?: PurchaseRestoreResult;
 }): PurchaseSettlement | null;
 export interface RewardedAdResult {
-  readonly status: 'completed' | 'skipped' | 'unavailable' | 'failed';
+  readonly status: 'completed' | 'pending' | 'skipped' | 'unavailable' | 'failed';
   readonly rewardGranted: boolean;
   readonly ledgerEntryId?: string;
   readonly evidence?: PlatformEvidenceEnvelope;
@@ -114,6 +114,8 @@ export interface CommerceAdapter {
 export interface AdAdapter {
   preload(input: {
     readonly placementId: LogicalAdPlacementId;
+    /** Allows a shared provider preload method to enforce format readiness. */
+    readonly format?: 'rewarded' | 'interstitial' | 'banner';
   }): Promise<void>;
   showRewarded(input: {
     readonly placementId: LogicalAdPlacementId;
@@ -161,6 +163,8 @@ export interface LeaderboardScoreInput {
   readonly score: number;
   readonly runId: string;
   readonly submittedAt: string;
+  /** Optional target-selected route when native and remote backends coexist. */
+  readonly route?: 'native' | 'remote';
 }
 export interface LeaderboardSubmitResult {
   readonly submitted: boolean;
@@ -170,10 +174,17 @@ export interface LeaderboardAdapter {
   submitScore(input: LeaderboardScoreInput): Promise<LeaderboardSubmitResult>;
   open(input?: {
     readonly leaderboardId?: string;
+    readonly route?: 'native' | 'remote';
   }): Promise<void>;
 }
+/** Readiness of an installed platform provider, independent of target policy. */
+export type PlatformProviderAvailability = 'unsupported' | 'configuration-required' | 'action-required' | 'temporarily-unavailable' | 'available';
+/** Existing capabilities and integrations annotated by optional providers. */
+export type PlatformProviderFeature = 'nativeIap' | 'subscriptionIap' | 'rewardedAds' | 'interstitialAds' | 'bannerAds' | 'nativeLeaderboard' | 'identityUpgrade' | 'pushNotifications';
 export interface PlatformCapabilities {
   readonly nativeIap: boolean;
+  /** Optional for adapters published before subscription-specific support. */
+  readonly subscriptionIap?: boolean;
   readonly nativeAds: boolean;
   readonly rewardedAds: boolean;
   readonly interstitialAds: boolean;
@@ -187,6 +198,8 @@ export interface PlatformCapabilities {
   readonly socialShare: boolean;
   readonly haptics: boolean;
   readonly localizedContent: boolean;
+  /** Explains a false capability without claiming an unavailable SDK works. */
+  readonly providerAvailability?: Readonly<Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>>;
 }
 export interface PlayerIdentity {
   readonly playerId: string;
@@ -267,9 +280,77 @@ export interface NotificationSubscriptionAdapter {
   getStatus(topic: NotificationTopic): Promise<NotificationSubscriptionStatus>;
   requestSubscription(topic: NotificationTopic): Promise<NotificationSubscriptionResult>;
 }
+/** The source of an app URL, not a claim that the URL is trusted. */
+export interface NativeOpenUrlEvent {
+  readonly url: string;
+  readonly source: 'cold' | 'warm';
+}
+export interface NativeBackButtonEvent {
+  /** Whether the WebView history can navigate back, not the game's own scene stack. */
+  readonly canGoBack: boolean;
+}
+/** Full WebView viewport geometry in CSS pixels, before applying game-owned padding. */
+export interface PlatformViewportInsets {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+export interface PlatformViewportBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+/** An occupied game surface with stable identity, not an extra inset to sum. */
+export interface PlatformViewportOccupiedSurface {
+  readonly surfaceId: string;
+  readonly edge: 'top' | 'right' | 'bottom' | 'left';
+  readonly bounds: PlatformViewportBounds;
+}
+/**
+* Structurally matches `TargetViewportUsableAreaInput` in @mpgd/target-config
+* (field names, CSS-pixel units, and edge union), so consumers can pass the
+* same state to `resolveTargetViewportUsableArea` without conversion.
+*/
+export interface PlatformViewportState {
+  readonly width: number;
+  readonly height: number;
+  readonly safeAreaInsets: PlatformViewportInsets;
+  readonly systemBarInsets: PlatformViewportInsets;
+  readonly keyboardInsets: PlatformViewportInsets;
+  readonly occupiedSurfaces: readonly PlatformViewportOccupiedSurface[];
+}
+/** Optional native viewport source; consumers use one owner for canvas and DOM layout. */
+export interface ViewportAdapter {
+  getState(): PlatformViewportState;
+  onChange(callback: (state: PlatformViewportState) => void): () => void;
+  dispose?(): void;
+}
 export interface LifecycleAdapter {
   onPause(callback: () => void): () => void;
   onResume(callback: () => void): () => void;
+  /**
+  * Android handlers run last-registered-first until one returns true. If none
+  * consumes the event, Capacitor navigates WebView history when possible or
+  * exits the app. The method's presence does not imply support on iOS: check
+  * the gateway target. Persist progress at checkpoints; back/exit callbacks
+  * are not guaranteed to run before process termination.
+  */
+  onBackButton?(handler: (event: NativeBackButtonEvent) => boolean | Promise<boolean>): () => void;
+  /** Game links and OAuth redirects use separate callbacks. */
+  onGameUrlOpen?(callback: (event: NativeOpenUrlEvent) => void): () => void;
+  onOAuthRedirect?(callback: (event: NativeOpenUrlEvent) => void): () => void;
+  getInitialGameUrl?(): Promise<NativeOpenUrlEvent | null>;
+  getInitialOAuthRedirect?(): Promise<NativeOpenUrlEvent | null>;
+  /**
+  * Keep execution paused while external UI is open. Call the returned
+  * idempotent release function when it closes, including failure paths;
+  * otherwise execution remains paused.
+  */
+  beginExternalActivity?(): () => void;
+  /** Remove only the native listeners owned by this adapter instance. */
+  dispose?(): Promise<void>;
 }
 export interface StorageLoadResult {
   readonly value: unknown;
@@ -284,6 +365,19 @@ export interface StorageAdapter {
     readonly value: unknown;
   }): Promise<void>;
 }
+/** Device-protected opaque credentials; never backed by ordinary game storage. */
+export interface SecureCredentialStore {
+  load(input: {
+    readonly key: string;
+  }): Promise<string | null>;
+  save(input: {
+    readonly key: string;
+    readonly value: string;
+  }): Promise<void>;
+  remove(input: {
+    readonly key: string;
+  }): Promise<void>;
+}
 export interface PlatformGateway {
   readonly target: PlatformTarget;
   getCapabilities(): Promise<PlatformCapabilities>;
@@ -292,7 +386,10 @@ export interface PlatformGateway {
   readonly ads: AdAdapter;
   readonly leaderboard: LeaderboardAdapter;
   readonly lifecycle: LifecycleAdapter;
+  readonly viewport?: ViewportAdapter;
   readonly storage: StorageAdapter;
+  /** Optional: missing native support must not fall back to plaintext storage. */
+  readonly secureCredentials?: SecureCredentialStore;
   readonly presentation?: PresentationAdapter;
   readonly sharing?: ShareAdapter;
   readonly notifications?: NotificationSubscriptionAdapter;

package/package.json

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