@mpgd/target-config 0.15.2 → 0.17.0

package/dist/runtime.js

@@ -5,10 +5,13 @@ const adPlacementFeatureByType = {
 };
 export const platformFeatures = [
     'iap',
+    'subscriptions',
     'bannerAds',
     'rewardedAds',
     'interstitialAds',
     'leaderboard',
+    'nativeLeaderboard',
+    'remoteLeaderboard',
     'localization',
 ];
 export function adPlacementFeatureFor(type) {
@@ -55,7 +58,9 @@ const integrationAvailabilityStateValues = [
     'available',
     'disabled',
     'approval-required',
+    'action-required',
     'configuration-required',
+    'temporarily-unavailable',
     'unsupported',
 ];
 export const integrationAvailabilityStates = integrationAvailabilityStateValues;
@@ -129,7 +134,18 @@ export function getTargetConfig(matrix, target) {
     return config;
 }
 export function isPlatformFeatureEnabled(config, feature) {
-    return config.features[feature] === true;
+    switch (feature) {
+        case 'subscriptions':
+            return config.features.iap && config.features.subscriptions === true;
+        case 'nativeLeaderboard':
+            return config.features.leaderboard
+                && (config.features.nativeLeaderboard ?? config.leaderboard.native);
+        case 'remoteLeaderboard':
+            return config.features.leaderboard
+                && (config.features.remoteLeaderboard ?? true);
+        default:
+            return config.features[feature] === true;
+    }
 }
 export function applyTargetConfigToCapabilities(capabilities, config) {
     const bannerAds = capabilities.bannerAds === true && config.features.bannerAds === true;
@@ -138,46 +154,61 @@ export function applyTargetConfigToCapabilities(capabilities, config) {
     return {
         ...capabilities,
         nativeIap: capabilities.nativeIap && config.features.iap,
+        ...(capabilities.subscriptionIap === undefined
+            ? {}
+            : { subscriptionIap: capabilities.subscriptionIap && isPlatformFeatureEnabled(config, 'subscriptions') }),
         nativeAds: capabilities.nativeAds &&
             (bannerAds || rewardedAds || interstitialAds),
         bannerAds,
         rewardedAds,
         interstitialAds,
-        nativeLeaderboard: capabilities.nativeLeaderboard && config.features.leaderboard,
-        remoteLeaderboard: capabilities.remoteLeaderboard && config.features.leaderboard,
+        nativeLeaderboard: capabilities.nativeLeaderboard && isPlatformFeatureEnabled(config, 'nativeLeaderboard'),
+        remoteLeaderboard: capabilities.remoteLeaderboard && isPlatformFeatureEnabled(config, 'remoteLeaderboard'),
         localizedContent: capabilities.localizedContent && config.features.localization,
     };
 }
 export function getFeatureAvailability(feature, config, capabilities) {
-    const targetEnabled = config.features[feature] === true;
-    const capabilitySupported = isFeatureCapabilitySupported(feature, capabilities);
-    const enabled = targetEnabled && capabilitySupported;
+    const targetEnabled = isPlatformFeatureEnabled(config, feature);
+    const capabilitySupported = isFeatureCapabilitySupported(feature, capabilities, config);
+    const providerState = getFeatureProviderAvailability(feature, capabilities, config);
+    const enabled = targetEnabled && capabilitySupported && (providerState === undefined || providerState === 'available');
     return {
         feature,
         enabled,
         targetEnabled,
         capabilitySupported,
-        reason: enabled ? 'available' : targetEnabled ? 'capability-unsupported' : 'target-disabled',
+        reason: !targetEnabled
+            ? 'target-disabled'
+            : enabled
+                ? 'available'
+                : providerState === 'configuration-required'
+                    || providerState === 'action-required'
+                    || providerState === 'temporarily-unavailable'
+                    ? providerState
+                    : 'capability-unsupported',
     };
 }
-export function getIntegrationAvailability(integration, config, gateway) {
+export function getIntegrationAvailability(integration, config, gateway, capabilities) {
     const integrations = normalizeTargetIntegrationConfig(config.integrations);
-    return createIntegrationAvailability(integration, integrations[integration], gateway);
+    return createIntegrationAvailability(integration, integrations[integration], gateway, capabilities);
 }
 export function createTargetRuntimeSnapshot(input) {
     const configTarget = input.configTarget ?? targetConfigKeyForPlatform(input.target);
     const availabilityConfig = resolveAvailabilityConfig(input.config, input.effectiveConfig);
     const features = {
         iap: getFeatureAvailability('iap', availabilityConfig, input.capabilities),
+        subscriptions: getFeatureAvailability('subscriptions', availabilityConfig, input.capabilities),
         bannerAds: getFeatureAvailability('bannerAds', availabilityConfig, input.capabilities),
         rewardedAds: getFeatureAvailability('rewardedAds', availabilityConfig, input.capabilities),
         interstitialAds: getFeatureAvailability('interstitialAds', availabilityConfig, input.capabilities),
         leaderboard: getFeatureAvailability('leaderboard', availabilityConfig, input.capabilities),
+        nativeLeaderboard: getFeatureAvailability('nativeLeaderboard', availabilityConfig, input.capabilities),
+        remoteLeaderboard: getFeatureAvailability('remoteLeaderboard', availabilityConfig, input.capabilities),
         localization: getFeatureAvailability('localization', availabilityConfig, input.capabilities),
     };
     const integrationConfig = normalizeTargetIntegrationConfig(input.effectiveConfig?.integrations ?? input.config.integrations);
     const integrationEntries = targetIntegrations.map((integration) => {
-        const availability = createIntegrationAvailability(integration, integrationConfig[integration], input.gateway);
+        const availability = createIntegrationAvailability(integration, integrationConfig[integration], input.gateway, input.capabilities);
         return [integration, availability];
     });
     const integrations = Object.fromEntries(integrationEntries);
@@ -208,13 +239,16 @@ export function withTargetAvailability(gateway, config, options = {}) {
     const configTarget = options.configTarget ?? targetConfigKeyForPlatform(gateway.target);
     const { identity: gatewayIdentity, presentation: gatewayPresentation, sharing: gatewaySharing, notifications: gatewayNotifications, ...gatewayWithoutIntegrations } = gateway;
     const integrations = normalizeTargetIntegrationConfig(options.effectiveConfig?.integrations ?? config.integrations);
-    const isIntegrationAvailable = (integration) => (createIntegrationAvailability(integration, integrations[integration], gateway).state
-        === 'available');
-    const identityUpgradeAvailable = isIntegrationAvailable('identityUpgrade');
-    const presentationAvailable = isIntegrationAvailable('presentation');
-    const sharingAvailable = isIntegrationAvailable('sharing');
-    const inboundShareAvailable = isIntegrationAvailable('inboundShare');
-    const notificationsAvailable = isIntegrationAvailable('notifications');
+    const isIntegrationCallable = (integration) => {
+        const state = createIntegrationAvailability(integration, integrations[integration], gateway).state;
+        return state === 'available' || (state === 'action-required'
+            && (integration === 'identityUpgrade' || integration === 'notifications'));
+    };
+    const identityUpgradeAvailable = isIntegrationCallable('identityUpgrade');
+    const presentationAvailable = isIntegrationCallable('presentation');
+    const sharingAvailable = isIntegrationCallable('sharing');
+    const inboundShareAvailable = isIntegrationCallable('inboundShare');
+    const notificationsAvailable = isIntegrationCallable('notifications');
     const getIdentitySession = gatewayIdentity.getSession?.bind(gatewayIdentity);
     const requestIdentityUpgrade = gatewayIdentity.requestUpgrade?.bind(gatewayIdentity);
     const shareOutbound = gatewaySharing?.share?.bind(gatewaySharing);
@@ -236,13 +270,32 @@ export function withTargetAvailability(gateway, config, options = {}) {
             ...(exposeInboundShare ? { readInboundShare } : {}),
         };
     const notifications = notificationsAvailable ? gatewayNotifications : undefined;
-    const isIapAvailable = async () => (availabilityConfig.features.iap && (await getGatewayCapabilities()).nativeIap);
-    const isLeaderboardAvailable = async () => {
+    const getIapAvailability = async () => {
+        const oneTimeEnabled = availabilityConfig.features.iap;
+        const subscriptionsEnabled = isPlatformFeatureEnabled(availabilityConfig, 'subscriptions');
+        if (!oneTimeEnabled && !subscriptionsEnabled) {
+            return { oneTime: false, subscriptions: false };
+        }
+        const capabilities = await getGatewayCapabilities();
+        return {
+            oneTime: oneTimeEnabled && capabilities.nativeIap,
+            subscriptions: subscriptionsEnabled && capabilities.subscriptionIap === true,
+        };
+    };
+    const getLeaderboardRoute = async () => {
         if (!availabilityConfig.features.leaderboard) {
-            return false;
+            return null;
         }
         const capabilities = await getGatewayCapabilities();
-        return capabilities.nativeLeaderboard || capabilities.remoteLeaderboard;
+        if (capabilities.nativeLeaderboard
+            && isPlatformFeatureEnabled(availabilityConfig, 'nativeLeaderboard')) {
+            return 'native';
+        }
+        if (capabilities.remoteLeaderboard
+            && isPlatformFeatureEnabled(availabilityConfig, 'remoteLeaderboard')) {
+            return 'remote';
+        }
+        return null;
     };
     const isAdPlacementAllowed = (placementId, expectedType) => {
         const actualType = options.resolveAdPlacementType?.(placementId);
@@ -251,14 +304,19 @@ export function withTargetAvailability(gateway, config, options = {}) {
         }
         return availabilityConfig.features[adPlacementFeatureFor(expectedType)] === true;
     };
-    const canPreloadAdPlacement = (placementId) => {
-        const actualType = options.resolveAdPlacementType?.(placementId);
+    const canPreloadAdPlacement = (placementId, requestedFormat) => {
+        const resolvedType = options.resolveAdPlacementType?.(placementId);
+        if (resolvedType !== undefined && requestedFormat !== undefined
+            && resolvedType !== requestedFormat) {
+            return false;
+        }
+        const actualType = resolvedType ?? requestedFormat;
         if (actualType !== undefined) {
-            return availabilityConfig.features[adPlacementFeatureFor(actualType)] === true;
+            return actualType !== 'banner'
+                && availabilityConfig.features[adPlacementFeatureFor(actualType)] === true;
         }
         return (availabilityConfig.features.rewardedAds ||
-            availabilityConfig.features.interstitialAds ||
-            availabilityConfig.features.bannerAds === true);
+            availabilityConfig.features.interstitialAds);
     };
     return {
         ...gatewayWithoutIntegrations,
@@ -289,10 +347,29 @@ export function withTargetAvailability(gateway, config, options = {}) {
         },
         commerce: {
             async getProducts() {
-                return await isIapAvailable() ? gateway.commerce.getProducts() : [];
+                const available = await getIapAvailability();
+                if (!available.oneTime && !available.subscriptions) {
+                    return [];
+                }
+                return (await gateway.commerce.getProducts()).filter((product) => product.type === 'subscription' ? available.subscriptions : available.oneTime);
             },
             async purchase(input) {
-                if (!await isIapAvailable()) {
+                const available = await getIapAvailability();
+                const configuredProduct = options.effectiveConfig?.monetization.products.find((product) => product.id === input.productId);
+                let productType = configuredProduct?.type;
+                if (productType === undefined
+                    && options.effectiveConfig === undefined
+                    && available.oneTime !== available.subscriptions) {
+                    productType = (await gateway.commerce.getProducts()).find((product) => product.id === input.productId)?.type;
+                }
+                // When only one purchase route is available, unknown product types
+                // must not fall through to that route. An effective catalog is binding.
+                const allowed = productType === 'subscription'
+                    ? available.subscriptions
+                    : productType === undefined
+                        ? available.oneTime && available.subscriptions
+                        : available.oneTime;
+                if (!allowed || (options.effectiveConfig !== undefined && configuredProduct?.enabled !== true)) {
                     return {
                         status: 'cancelled',
                         entitlementIds: [],
@@ -301,7 +378,8 @@ export function withTargetAvailability(gateway, config, options = {}) {
                 return gateway.commerce.purchase(input);
             },
             async restore() {
-                if (!await isIapAvailable() || gateway.commerce.restore === undefined) {
+                const available = await getIapAvailability();
+                if ((!available.oneTime && !available.subscriptions) || gateway.commerce.restore === undefined) {
                     return {
                         restoredEntitlements: [],
                     };
@@ -309,13 +387,17 @@ export function withTargetAvailability(gateway, config, options = {}) {
                 return gateway.commerce.restore();
             },
             async getEntitlements() {
-                return await isIapAvailable() ? gateway.commerce.getEntitlements() : [];
+                const available = await getIapAvailability();
+                return available.oneTime || available.subscriptions
+                    ? gateway.commerce.getEntitlements()
+                    : [];
             },
         },
         ads: {
             async preload(input) {
-                if (canPreloadAdPlacement(input.placementId)) {
-                    await gateway.ads.preload(input);
+                if (canPreloadAdPlacement(input.placementId, input.format)) {
+                    const format = options.resolveAdPlacementType?.(input.placementId) ?? input.format;
+                    await gateway.ads.preload(format === undefined ? input : { ...input, format });
                 }
             },
             async showRewarded(input) {
@@ -351,16 +433,22 @@ export function withTargetAvailability(gateway, config, options = {}) {
         },
         leaderboard: {
             async submitScore(input) {
-                if (!await isLeaderboardAvailable()) {
+                const route = await getLeaderboardRoute();
+                if (route === null) {
                     return {
                         submitted: false,
                     };
                 }
-                return gateway.leaderboard.submitScore(input);
+                return gateway.leaderboard.submitScore(gateway.target === 'android' || gateway.target === 'ios'
+                    ? { ...input, route }
+                    : input);
             },
             async open(input) {
-                if (await isLeaderboardAvailable()) {
-                    await gateway.leaderboard.open(input);
+                const route = await getLeaderboardRoute();
+                if (route !== null) {
+                    await gateway.leaderboard.open(gateway.target === 'android' || gateway.target === 'ios'
+                        ? { ...input, route }
+                        : input);
                 }
             },
         },
@@ -377,10 +465,12 @@ function resolveAvailabilityConfig(config, effectiveConfig) {
 export function isTargetConfiguredGateway(gateway) {
     return typeof gateway.getTargetRuntime === 'function';
 }
-function isFeatureCapabilitySupported(feature, capabilities) {
+function isFeatureCapabilitySupported(feature, capabilities, config) {
     switch (feature) {
         case 'iap':
             return capabilities.nativeIap;
+        case 'subscriptions':
+            return capabilities.subscriptionIap === true;
         case 'bannerAds':
             return capabilities.bannerAds === true;
         case 'rewardedAds':
@@ -388,11 +478,45 @@ function isFeatureCapabilitySupported(feature, capabilities) {
         case 'interstitialAds':
             return capabilities.interstitialAds;
         case 'leaderboard':
-            return capabilities.nativeLeaderboard || capabilities.remoteLeaderboard;
+            return (capabilities.nativeLeaderboard && isPlatformFeatureEnabled(config, 'nativeLeaderboard')) || (capabilities.remoteLeaderboard && isPlatformFeatureEnabled(config, 'remoteLeaderboard'));
+        case 'nativeLeaderboard':
+            return capabilities.nativeLeaderboard;
+        case 'remoteLeaderboard':
+            return capabilities.remoteLeaderboard;
         case 'localization':
             return capabilities.localizedContent;
     }
 }
+function getFeatureProviderAvailability(feature, capabilities, config) {
+    const states = capabilities.providerAvailability;
+    if (states === undefined) {
+        return undefined;
+    }
+    switch (feature) {
+        case 'iap':
+            return states.nativeIap;
+        case 'subscriptions':
+            return states.subscriptionIap;
+        case 'rewardedAds':
+            return states.rewardedAds;
+        case 'interstitialAds':
+            return states.interstitialAds;
+        case 'bannerAds':
+            return states.bannerAds;
+        case 'nativeLeaderboard':
+            return states.nativeLeaderboard;
+        case 'leaderboard':
+            // A game-owned remote leaderboard remains usable without a native provider.
+            return capabilities.remoteLeaderboard && isPlatformFeatureEnabled(config, 'remoteLeaderboard')
+                ? 'available'
+                : isPlatformFeatureEnabled(config, 'nativeLeaderboard')
+                    ? states.nativeLeaderboard
+                    : undefined;
+        case 'remoteLeaderboard':
+        case 'localization':
+            return undefined;
+    }
+}
 function isIntegrationAdapterSupported(integration, gateway) {
     if (gateway === undefined) {
         return false;
@@ -412,11 +536,23 @@ function isIntegrationAdapterSupported(integration, gateway) {
                 && typeof gateway.notifications?.requestSubscription === 'function');
     }
 }
-function createIntegrationAvailability(integration, configuredState, gateway) {
+function createIntegrationAvailability(integration, configuredState, gateway, capabilities) {
     const adapterSupported = isIntegrationAdapterSupported(integration, gateway);
+    const providerState = integration === 'identityUpgrade'
+        ? capabilities?.providerAvailability?.identityUpgrade
+        : integration === 'notifications'
+            ? capabilities?.providerAvailability?.pushNotifications
+            : undefined;
+    const state = configuredState === 'disabled' || configuredState === 'unsupported'
+        ? configuredState
+        : !adapterSupported || providerState === 'unsupported'
+            ? 'unsupported'
+            : providerState !== undefined && providerState !== 'available'
+                ? providerState
+                : configuredState;
     return {
         integration,
-        state: adapterSupported ? configuredState : 'unsupported',
+        state,
         configuredState,
         adapterSupported,
     };

package/dist/viewport.d.ts

@@ -106,6 +106,27 @@ export interface TargetViewportSafeArea {
   readonly contentBounds: TargetViewportBounds;
 }
 /**
+* A named host-owned surface in full-viewport CSS-pixel coordinates. The
+* effective inset extends from `edge` to the surface's far bound, so any gap
+* between a floating surface and that edge is conservatively treated as used.
+*/
+export interface TargetViewportOccupiedSurface {
+  readonly surfaceId: string;
+  readonly edge: 'top' | 'right' | 'bottom' | 'left';
+  readonly bounds: TargetViewportBounds;
+}
+/** Independent occlusion measurements. Overlap is combined, never summed. */
+export interface TargetViewportUsableAreaInput {
+  readonly safeAreaInsets?: Partial<TargetViewportSafeAreaInsets>;
+  readonly systemBarInsets?: Partial<TargetViewportSafeAreaInsets>;
+  readonly keyboardInsets?: Partial<TargetViewportSafeAreaInsets>;
+  readonly occupiedSurfaces?: readonly TargetViewportOccupiedSurface[];
+}
+/** Remaining geometry shared by a canvas and any DOM overlays. */
+export interface TargetViewportUsableArea extends TargetViewportSafeArea {
+  readonly occupiedSurfaceIds: readonly string[];
+}
+/**
 * A viewport plan enriched with concrete safe-area geometry. It is assignable
 * to `TargetViewportPlan`, so existing scene code can adopt it incrementally.
 */
@@ -206,6 +227,67 @@ export declare function resolveTargetViewportPlan(input: TargetViewportInput, br
 * render persistent DOM controls or position Phaser HUD elements themselves.
 */
 export declare function resolveTargetViewportSnapshot(input: TargetViewportSnapshotInput, breakpoints?: TargetViewportBreakpoints): TargetViewportSnapshot;
+/** A raw viewport size reported by a host surface, before a plan validates it. */
+export interface TargetViewportMeasurement {
+  readonly width: number;
+  readonly height: number;
+  readonly source: TargetViewportMeasurementSource;
+}
+/** A surface that reports its layout box, such as the element that mounts the game. */
+export interface TargetViewportMeasurableElement {
+  getBoundingClientRect(): {
+    readonly width: number;
+    readonly height: number;
+  };
+}
+/**
+* Host surfaces for {@link measureTargetViewport}. Structural types keep the helper usable in
+* tests and non-DOM hosts; a browser passes the game container, `window.visualViewport` and
+* `window`.
+*/
+export interface TargetViewportMeasurementSources {
+  readonly container?: TargetViewportMeasurableElement | null;
+  readonly visualViewport?: {
+    readonly width: number;
+    readonly height: number;
+  } | null;
+  readonly window?: {
+    readonly innerWidth: number;
+    readonly innerHeight: number;
+  } | null;
+}
+/** Inputs for {@link waitForTargetViewportMeasurement}. */
+export interface TargetViewportMeasurementWait {
+  /** Returns a measurement, or `null` while the surface has no usable size. */
+  readonly measure: () => TargetViewportMeasurement | null;
+  /**
+  * Calls the listener whenever the surface may have resized or become visible and returns an
+  * unsubscribe function. Browsers typically combine window and `visualViewport` `resize`,
+  * document `visibilitychange` and a `ResizeObserver` on the game container.
+  */
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Stops waiting; the promise then rejects with the signal's reason. */
+  readonly signal?: AbortSignal;
+}
+/** Whether a size can produce a viewport plan: both sides finite and at least one CSS pixel. */
+export declare function isMeasurableTargetViewport(size: {
+  readonly width: number;
+  readonly height: number;
+}): boolean;
+/**
+* Measure the first host surface with a usable area: the game container, then the visual
+* viewport, then the window. Returns `null` while every surface is still zero-sized, as in a
+* hidden iframe, a collapsed embed or a background tab before layout. Resolve a viewport plan
+* only from a measurement; {@link waitForTargetViewportMeasurement} waits for the first one.
+*/
+export declare function measureTargetViewport(sources: TargetViewportMeasurementSources): TargetViewportMeasurement | null;
+/**
+* Resolve with the first usable measurement, so a game that boots inside a zero-sized surface
+* starts once the host lays it out instead of failing viewport validation. Resolves immediately
+* when the surface is already measurable and unsubscribes as soon as it settles. A measurement
+* that throws, including the first one, rejects the returned promise.
+*/
+export declare function waitForTargetViewportMeasurement(input: TargetViewportMeasurementWait): Promise<TargetViewportMeasurement>;
 /**
 * Resolve an adaptive game shell inside the snapshot's safe content bounds.
 *
@@ -225,6 +307,14 @@ export declare function resolveTargetViewportComposition(input: TargetViewportCo
 */
 export declare function resolveTargetViewportSafeArea(layout: Pick<TargetViewportLayout, 'width' | 'height'>, insets?: Partial<TargetViewportSafeAreaInsets>): TargetViewportSafeArea;
 /**
+* Resolve all edge occlusions in one CSS-pixel coordinate space. System bars
+* and CSS safe-area measurements can describe the same pixels, as can a banner
+* and the home-indicator inset. Taking the maximum intrusion per edge avoids
+* subtracting those regions twice. A surface's bounds are absolute viewport
+* coordinates, not a banner height to add to another inset.
+*/
+export declare function resolveTargetViewportUsableArea(layout: Pick<TargetViewportLayout, 'width' | 'height'>, input?: TargetViewportUsableAreaInput): TargetViewportUsableArea;
+/**
 * Read the starter's computed CSS variables. Unknown or non-pixel values are
 * intentionally treated as zero so browser shells without CSS env support keep
 * the same full-viewport layout as before.