@mpgd/target-config 0.9.1 → 0.10.1

package/dist/effective.d.ts

@@ -1,4 +1,4 @@
-import type { AdPlacementEntry, AdPlacements, ProductCatalog, ProductCatalogEntry } from '@mpgd/catalog';
+import { type AdPlacementEntry, type AdPlacements, type ProductCatalog, type ProductCatalogEntry } from '@mpgd/catalog';
 import { type FeatureAvailabilityReason, type TargetCapabilityConfig, type TargetConfig, type TargetConfigMatrix, type TargetFeatureConfig, type TargetIntegrationConfig, type TargetLocalizationConfig, type TargetPolicyRestrictions, type TargetReleaseConfig, type TargetRuntimeKind } from './runtime.js';
 export type EffectiveAvailabilityReason = FeatureAvailabilityReason | 'missing-platform-id';
 export interface EffectivePlatformTargetMetadata {

package/dist/effective.js

@@ -1,4 +1,5 @@
-import { normalizeTargetIntegrationConfig, } from './runtime.js';
+import { resolveAdPlacementPlatformId, resolveProductPlatformId, } from '@mpgd/catalog';
+import { assertTargetIntegrationRuntimeBounds, } from './runtime.js';
 export const defaultLeaderboardId = 'default';
 const disabledAuthoritativeMonetization = {
     iap: false,
@@ -10,10 +11,10 @@ export function createEffectiveTargetConfig(input) {
     const products = input.catalog.products.map((product) => createEffectiveProductConfig(input.target, config, product));
     const placements = input.adPlacements.placements.map((placement) => createEffectiveAdPlacementConfig(input.target, config, placement));
     const leaderboardEnabled = config.features.leaderboard;
-    const integrations = normalizeTargetIntegrationConfig({
+    const integrations = assertTargetIntegrationRuntimeBounds(config.runtime, {
         ...config.integrations,
         ...input.platformTarget?.integrations,
-    });
+    }, `Effective target ${input.target}`);
     return {
         version: effectiveTargetConfigVersion({
             targetConfig: input.targetConfigVersion,
@@ -107,8 +108,8 @@ export function getEffectiveAdPlacementConfig(config, placementId) {
     return config.ads.placements.find((placement) => placement.id === placementId);
 }
 function createEffectiveProductConfig(target, config, product) {
-    const platformProductId = productPlatformId(product, target);
-    const reason = effectiveProductReason(target, config.features.iap, product, platformProductId);
+    const platformProductId = resolveProductPlatformId(product, target);
+    const reason = effectiveProductReason(config.runtime, config.features.iap, product, platformProductId);
     return {
         id: product.id,
         type: product.type,
@@ -118,11 +119,11 @@ function createEffectiveProductConfig(target, config, product) {
         ...(platformProductId === undefined ? {} : { platformProductId }),
     };
 }
-function effectiveProductReason(target, targetEnabled, product, platformProductId) {
+function effectiveProductReason(runtime, targetEnabled, product, platformProductId) {
     if (!targetEnabled) {
         return 'target-disabled';
     }
-    if (target === 'verse8' && product.grant.type === 'resource') {
+    if (runtime === 'verse8-web' && product.grant.type === 'resource') {
         return 'capability-unsupported';
     }
     return effectiveItemReason(targetEnabled, platformProductId);
@@ -131,7 +132,7 @@ function createEffectiveAdPlacementConfig(target, config, placement) {
     const featureEnabled = isRewardedPlacement(placement)
         ? config.features.rewardedAds
         : config.features.interstitialAds;
-    const platformPlacementId = adPlacementPlatformId(placement, target);
+    const platformPlacementId = resolveAdPlacementPlatformId(placement, target);
     const reason = effectiveItemReason(featureEnabled, platformPlacementId);
     return {
         id: placement.id,
@@ -152,35 +153,6 @@ function effectiveItemReason(targetEnabled, platformId) {
 function effectiveTargetConfigVersion(input) {
     return `${input.targetConfig}+catalog.${input.productCatalog}+ads.${input.adPlacements}`;
 }
-function productPlatformId(product, target) {
-    if (!isProductStoreTarget(target)) {
-        return undefined;
-    }
-    return normalizePlatformId(product.platformProductIds[target]);
-}
-function adPlacementPlatformId(placement, target) {
-    if (!isAdStoreTarget(target)) {
-        return undefined;
-    }
-    return normalizePlatformId(placement.platformPlacementIds[target]);
-}
-function normalizePlatformId(platformId) {
-    if (platformId === undefined) {
-        return undefined;
-    }
-    const trimmed = platformId.trim();
-    return trimmed.length === 0 ? undefined : trimmed;
-}
-function isProductStoreTarget(target) {
-    return target === 'android'
-        || target === 'ios'
-        || target === 'ait'
-        || target === 'reddit'
-        || target === 'verse8';
-}
-function isAdStoreTarget(target) {
-    return target === 'android' || target === 'ios' || target === 'ait' || target === 'verse8';
-}
 function isRewardedPlacement(placement) {
     return placement.type === 'rewarded';
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { EffectiveTargetConfigMatrix } from './effective.js';
 import type { TargetConfigMatrix } from './runtime.js';
 export * from './effective.js';
+export * from './releaseIdentity.js';
 export * from './runtime.js';
 export * from './viewport.js';
 export declare const assertEffectiveTargetConfigMatrix: (input: unknown) => EffectiveTargetConfigMatrix;

package/dist/index.js

@@ -3,6 +3,7 @@ import * as _accessExpressionAsString_1 from "typia/lib/internal/_accessExpressi
 const __typia_transform__accessExpressionAsString = _accessExpressionAsString_1._accessExpressionAsString;
 import typia from 'typia';
 export * from './effective.js';
+export * from './releaseIdentity.js';
 export * from './runtime.js';
 export * from './viewport.js';
 export const assertEffectiveTargetConfigMatrix = (() => {

package/dist/releaseIdentity.d.ts

@@ -0,0 +1,33 @@
+/**
+* A human-facing release identity shared by every target artifact for one game release.
+*
+* `gameVersion` remains the game's SemVer value. `releaseRevision` is deliberately
+* separate so a game can keep one semantic release while targets are promoted or
+* rebuilt independently. For example, the common label for game `0.3.30` and
+* revision `42` is `0.3.30-v42`.
+*/
+export interface MpgdReleaseIdentity {
+  readonly gameVersion: string;
+  readonly releaseRevision?: number;
+  readonly label: string;
+}
+export interface CreateMpgdReleaseIdentityInput {
+  readonly gameVersion: string;
+  readonly releaseRevision?: number;
+  /**
+  * Optional value from a build environment. It must equal the derived label so
+  * a stale or hand-edited label cannot be embedded into an artifact.
+  */
+  readonly expectedLabel?: string;
+}
+export declare function createMpgdReleaseIdentity(input: CreateMpgdReleaseIdentityInput): MpgdReleaseIdentity;
+export declare function formatMpgdReleaseLabel(gameVersion: string, releaseRevision: number | undefined): string;
+/** Whether a normalized game version is eligible for an immutable production release. */
+export declare function isMpgdFinalSemVer(value: string): boolean;
+/**
+* Canonical release-manifest identifier derived from a common release label.
+* Both components must be non-empty canonical tokens without the `+` delimiter.
+*/
+export declare function formatMpgdReleaseId(label: string, buildId: string): string;
+/** Parse an optional release revision without making empty values meaningful. */
+export declare function parseMpgdReleaseRevision(value: string | undefined): number | undefined;

package/dist/releaseIdentity.js

@@ -0,0 +1,80 @@
+const semVerCore = '(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)';
+const preReleaseNumericIdentifier = '(?:0|[1-9]\\d*)';
+const preReleaseAlphanumericIdentifier = '(?:\\d*[A-Za-z-][0-9A-Za-z-]*)';
+const preReleaseIdentifier = `(?:${preReleaseNumericIdentifier}|${preReleaseAlphanumericIdentifier})`;
+const finalSemVerPattern = new RegExp(`^${semVerCore}$`, 'u');
+const semVerPattern = new RegExp(`^${semVerCore}(?:-${preReleaseIdentifier}(?:\\.${preReleaseIdentifier})*)?$`, 'u');
+export function createMpgdReleaseIdentity(input) {
+    const gameVersion = normalizeMpgdSemVer(input.gameVersion);
+    const releaseRevision = input.releaseRevision;
+    const label = formatNormalizedMpgdReleaseLabel(gameVersion, releaseRevision);
+    const expectedLabel = input.expectedLabel?.trim();
+    if (expectedLabel !== undefined && expectedLabel !== label) {
+        const detail = `${label}; received ${expectedLabel}.`;
+        throw new TypeError(`Release identity label must equal ${detail}`);
+    }
+    return releaseRevision === undefined
+        ? { gameVersion, label }
+        : { gameVersion, releaseRevision, label };
+}
+export function formatMpgdReleaseLabel(gameVersion, releaseRevision) {
+    return formatNormalizedMpgdReleaseLabel(normalizeMpgdSemVer(gameVersion), releaseRevision);
+}
+function formatNormalizedMpgdReleaseLabel(gameVersion, releaseRevision) {
+    if (releaseRevision === undefined) {
+        return gameVersion;
+    }
+    if (!isMpgdFinalSemVer(gameVersion)) {
+        throw new TypeError('Release identity gameVersion must be a final SemVer when releaseRevision is set.');
+    }
+    if (!Number.isSafeInteger(releaseRevision) || releaseRevision < 1) {
+        throw new TypeError('Release identity releaseRevision must be a positive safe integer.');
+    }
+    return `${gameVersion}-v${releaseRevision}`;
+}
+/** Whether a normalized game version is eligible for an immutable production release. */
+export function isMpgdFinalSemVer(value) {
+    return finalSemVerPattern.test(value);
+}
+/**
+ * Canonical release-manifest identifier derived from a common release label.
+ * Both components must be non-empty canonical tokens without the `+` delimiter.
+ */
+export function formatMpgdReleaseId(label, buildId) {
+    assertReleaseIdComponent(label, 'label');
+    assertReleaseIdComponent(buildId, 'buildId');
+    return `mpgd-${label}+${buildId}`;
+}
+/** Parse an optional release revision without making empty values meaningful. */
+export function parseMpgdReleaseRevision(value) {
+    if (value === undefined || value.trim().length === 0) {
+        return undefined;
+    }
+    const normalized = value.trim();
+    if (!/^[1-9]\d*$/u.test(normalized)) {
+        throw new TypeError('Release revision must be a positive safe integer.');
+    }
+    const releaseRevision = Number.parseInt(normalized, 10);
+    if (!Number.isSafeInteger(releaseRevision)) {
+        throw new TypeError('Release revision must be a positive safe integer.');
+    }
+    return releaseRevision;
+}
+function normalizeMpgdSemVer(value) {
+    const normalized = value.trim();
+    if (normalized.includes('+')) {
+        throw new TypeError('Release identity gameVersion must not contain SemVer build metadata because "+" is reserved for release IDs.');
+    }
+    if (!semVerPattern.test(normalized)) {
+        throw new TypeError('Release identity gameVersion must be a SemVer value.');
+    }
+    return normalized;
+}
+function assertReleaseIdComponent(value, label) {
+    if (value.length === 0 || /\s/u.test(value)) {
+        throw new TypeError(`Release identifier ${label} must be a non-empty canonical token.`);
+    }
+    if (value.includes('+')) {
+        throw new TypeError(`Release identifier ${label} must not contain "+".`);
+    }
+}

package/dist/runtime.d.ts

@@ -128,6 +128,7 @@ export declare const defaultTargetIntegrationConfig: {
   readonly presentationMode: 'fullscreen';
 };
 export declare function normalizeTargetIntegrationConfig(config: Partial<TargetIntegrationConfig> | undefined): TargetIntegrationConfig;
+export declare function assertTargetIntegrationRuntimeBounds(runtime: TargetRuntimeKind, config: Partial<TargetIntegrationConfig> | undefined, label: string): TargetIntegrationConfig;
 export declare function targetConfigKeyForPlatform(target: PlatformConfigTarget): string;
 export declare function getTargetConfig(matrix: TargetConfigMatrix, target: PlatformConfigTarget | string): TargetConfig;
 export declare function isPlatformFeatureEnabled(config: TargetConfig, feature: PlatformFeature): boolean;

package/dist/runtime.js

@@ -12,6 +12,22 @@ export const targetIntegrations = [
     'inboundShare',
     'notifications',
 ];
+const integrationUpperBoundsByRuntime = {
+    'verse8-web': {
+        identityUpgrade: 'unsupported',
+        presentation: 'available',
+        sharing: 'unsupported',
+        inboundShare: 'unsupported',
+        notifications: 'unsupported',
+    },
+    'web-preview': {
+        identityUpgrade: 'disabled',
+        presentation: 'available',
+        sharing: 'available',
+        inboundShare: 'available',
+        notifications: 'unsupported',
+    },
+};
 const integrationAvailabilityStateValues = [
     'available',
     'disabled',
@@ -48,6 +64,31 @@ export function normalizeTargetIntegrationConfig(config) {
         presentationMode: normalizePresentationMode(config.presentationMode),
     };
 }
+export function assertTargetIntegrationRuntimeBounds(runtime, config, label) {
+    const integrations = normalizeTargetIntegrationConfig(config);
+    if (runtime !== 'verse8-web' && runtime !== 'web-preview') {
+        return integrations;
+    }
+    const upperBounds = integrationUpperBoundsByRuntime[runtime];
+    for (const integration of targetIntegrations) {
+        const state = integrations[integration];
+        const upperBound = upperBounds[integration];
+        if (!isIntegrationStateWithinUpperBound(state, upperBound)) {
+            throw new Error(`${label} cannot configure ${integration} as ${state} for ${runtime} runtime; maximum supported state is ${upperBound}.`);
+        }
+    }
+    return integrations;
+}
+function isIntegrationStateWithinUpperBound(state, upperBound) {
+    switch (upperBound) {
+        case 'available':
+            return true;
+        case 'disabled':
+            return state === 'disabled' || state === 'unsupported';
+        case 'unsupported':
+            return state === 'unsupported';
+    }
+}
 export function targetConfigKeyForPlatform(target) {
     return target === 'browser' ? 'web-preview' : target;
 }

package/dist/viewport.d.ts

@@ -1,16 +1,26 @@
 import type { TargetConfig, TargetRuntimeKind } from './runtime.js';
+/** The physical orientation derived from a viewport measurement. */
 export type TargetViewportOrientation = 'portrait' | 'landscape';
+/** How a game prefers or constrains viewport orientation. */
 export type TargetViewportOrientationPolicyMode = 'responsive' | 'prefer-landscape' | 'prefer-portrait' | 'lock-landscape' | 'lock-portrait';
+/** Presentation behavior when the measured orientation does not match policy. */
 export type TargetViewportOrientationMismatchBehavior = 'continue' | 'letterbox' | 'show-rotate-prompt';
+/** Responsive width class used by target-independent game layout. */
 export type TargetViewportSizeClass = 'compact' | 'medium' | 'expanded';
+/** Browser or embedded host shell that owns the game surface. */
 export type TargetViewportShell = 'browser' | 'mobile-webview' | 'embedded-webview';
+/** Browser measurement surface used to construct the viewport snapshot. */
 export type TargetViewportMeasurementSource = 'container' | 'visual-viewport' | 'window' | 'unknown';
+/** Recommended placement for primary game controls. */
 export type TargetViewportControlPlacement = 'bottom' | 'side';
+/** Recommended placement for secondary game panels. */
 export type TargetViewportPanelPlacement = 'below' | 'side' | 'drawer';
+/** Width thresholds used to classify target viewports. */
 export interface TargetViewportBreakpoints {
   readonly compactMaxWidth: number;
   readonly expandedMinWidth: number;
 }
+/** Raw viewport measurement and optional target context. */
 export interface TargetViewportInput {
   readonly width: number;
   readonly height: number;
@@ -18,6 +28,32 @@ export interface TargetViewportInput {
   readonly source?: TargetViewportMeasurementSource;
   readonly orientationPolicy?: TargetViewportOrientationPolicy;
 }
+/**
+* Insets expressed in CSS pixels between a viewport edge and content that can
+* safely receive persistent controls. A target adapter or browser host owns
+* measuring these values; the viewport helpers only normalize their use.
+*/
+export interface TargetViewportSafeAreaInsets {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+/** A rectangular region expressed in the coordinate space of a viewport. */
+export interface TargetViewportBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+/**
+* An optional safe-area extension for an otherwise ordinary viewport
+* measurement. Omitted values are treated as zero.
+*/
+export interface TargetViewportSnapshotInput extends TargetViewportInput {
+  readonly safeAreaInsets?: Partial<TargetViewportSafeAreaInsets>;
+}
+/** Normalized viewport geometry and responsive classification. */
 export interface TargetViewportLayout {
   readonly width: number;
   readonly height: number;
@@ -29,15 +65,18 @@ export interface TargetViewportLayout {
   readonly shell: TargetViewportShell;
   readonly source: TargetViewportMeasurementSource;
 }
+/** Target-independent control and panel placement recommendations. */
 export interface TargetViewportRecommendation {
   readonly primaryControls: TargetViewportControlPlacement;
   readonly secondaryPanels: TargetViewportPanelPlacement;
   readonly safeAreaAware: boolean;
 }
+/** A game's orientation preference and mismatch behavior. */
 export interface TargetViewportOrientationPolicy {
   readonly mode: TargetViewportOrientationPolicyMode;
   readonly mismatchBehavior?: TargetViewportOrientationMismatchBehavior;
 }
+/** Resolved orientation state for the current viewport and policy. */
 export interface TargetViewportOrientationPlan {
   readonly mode: TargetViewportOrientationPolicyMode;
   readonly preferredOrientation?: TargetViewportOrientation;
@@ -47,23 +86,102 @@ export interface TargetViewportOrientationPlan {
   readonly shouldLetterbox: boolean;
   readonly shouldShowRotatePrompt: boolean;
 }
+/** Complete responsive layout plan without concrete safe-area geometry. */
 export interface TargetViewportPlan {
   readonly layout: TargetViewportLayout;
   readonly recommendation: TargetViewportRecommendation;
   readonly orientation: TargetViewportOrientationPlan;
 }
+/**
+* The effective safe-area insets and the remaining rectangle for a game board
+* or persistent HUD. Insets are clamped to the measured viewport so a malformed
+* host measurement cannot produce a negative-sized content region.
+*/
+export interface TargetViewportSafeArea {
+  readonly insets: TargetViewportSafeAreaInsets;
+  readonly contentBounds: TargetViewportBounds;
+}
+/**
+* A viewport plan enriched with concrete safe-area geometry. It is assignable
+* to `TargetViewportPlan`, so existing scene code can adopt it incrementally.
+*/
+export interface TargetViewportSnapshot extends TargetViewportPlan {
+  readonly safeArea: TargetViewportSafeArea;
+}
+/**
+* The minimal browser style surface needed to read CSS safe-area custom
+* properties. Keeping this structural avoids a runtime DOM dependency in the
+* target-config package.
+*/
+export interface TargetViewportComputedStyle {
+  getPropertyValue(property: string): string;
+}
+/** CSS custom-property names used to expose host safe-area insets. */
+export interface TargetViewportSafeAreaCssVariables {
+  readonly top: string;
+  readonly right: string;
+  readonly bottom: string;
+  readonly left: string;
+}
+/** Default responsive breakpoints shared by generated game starters. */
 export declare const defaultTargetViewportBreakpoints: {
   readonly compactMaxWidth: 599;
   readonly expandedMinWidth: 900;
 };
+/** Default policy that keeps games responsive in every orientation. */
 export declare const defaultTargetViewportOrientationPolicy: {
   readonly mode: 'responsive';
   readonly mismatchBehavior: 'continue';
 };
+/** Zero-inset fallback for hosts without safe-area support. */
+export declare const defaultTargetViewportSafeAreaInsets: {
+  readonly top: 0;
+  readonly right: 0;
+  readonly bottom: 0;
+  readonly left: 0;
+};
+/**
+* CSS variables emitted by the Phaser starter. They deliberately mirror the
+* platform `safe-area-inset-*` environment variables while remaining readable
+* from a Phaser/TypeScript layout pass.
+*/
+export declare const defaultTargetViewportSafeAreaCssVariables: {
+  readonly top: '--mpgd-safe-area-top';
+  readonly right: '--mpgd-safe-area-right';
+  readonly bottom: '--mpgd-safe-area-bottom';
+  readonly left: '--mpgd-safe-area-left';
+};
+/** Map a configured target runtime to its viewport host shell. */
 export declare function targetViewportShellForRuntime(runtime: TargetRuntimeKind): TargetViewportShell;
+/** Resolve a viewport shell from the runtime field of a target config. */
 export declare function targetViewportShellForConfig(config: Pick<TargetConfig, 'runtime'>): TargetViewportShell;
+/** Normalize viewport input into responsive layout geometry. */
 export declare function resolveTargetViewportLayout(input: TargetViewportInput, breakpoints?: TargetViewportBreakpoints): TargetViewportLayout;
+/** Classify a viewport width against normalized responsive breakpoints. */
 export declare function resolveTargetViewportSizeClass(width: number, breakpoints?: TargetViewportBreakpoints): TargetViewportSizeClass;
+/** Recommend primary-control and secondary-panel placement for a layout. */
 export declare function resolveTargetViewportRecommendation(layout: TargetViewportLayout): TargetViewportRecommendation;
+/** Resolve orientation mismatch behavior for a measured layout. */
 export declare function resolveTargetViewportOrientationPlan(layout: Pick<TargetViewportLayout, 'orientation'>, policy?: TargetViewportOrientationPolicy): TargetViewportOrientationPlan;
+/** Build a responsive viewport plan from raw input and breakpoints. */
 export declare function resolveTargetViewportPlan(input: TargetViewportInput, breakpoints?: TargetViewportBreakpoints): TargetViewportPlan;
+/**
+* Build a target viewport plan together with safe-area geometry for games that
+* render persistent DOM controls or position Phaser HUD elements themselves.
+*/
+export declare function resolveTargetViewportSnapshot(input: TargetViewportSnapshotInput, breakpoints?: TargetViewportBreakpoints): TargetViewportSnapshot;
+/**
+* Resolve safe-area insets and content bounds for a given layout.
+*
+* Insets are clamped sequentially (top before bottom, left before right) so
+* malformed host measurements cannot produce a negative-sized content region.
+* When opposing insets exceed a viewport dimension, the first-processed side
+* (top or left) takes priority.
+*/
+export declare function resolveTargetViewportSafeArea(layout: Pick<TargetViewportLayout, 'width' | 'height'>, insets?: Partial<TargetViewportSafeAreaInsets>): TargetViewportSafeArea;
+/**
+* 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.
+*/
+export declare function readTargetViewportSafeAreaInsets(style: TargetViewportComputedStyle, variables?: TargetViewportSafeAreaCssVariables): TargetViewportSafeAreaInsets;

package/dist/viewport.js

@@ -1,11 +1,31 @@
+/** Default responsive breakpoints shared by generated game starters. */
 export const defaultTargetViewportBreakpoints = {
     compactMaxWidth: 599,
     expandedMinWidth: 900,
 };
+/** Default policy that keeps games responsive in every orientation. */
 export const defaultTargetViewportOrientationPolicy = {
     mode: 'responsive',
     mismatchBehavior: 'continue',
 };
+/** Zero-inset fallback for hosts without safe-area support. */
+export const defaultTargetViewportSafeAreaInsets = {
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+};
+/**
+ * CSS variables emitted by the Phaser starter. They deliberately mirror the
+ * platform `safe-area-inset-*` environment variables while remaining readable
+ * from a Phaser/TypeScript layout pass.
+ */
+export const defaultTargetViewportSafeAreaCssVariables = {
+    top: '--mpgd-safe-area-top',
+    right: '--mpgd-safe-area-right',
+    bottom: '--mpgd-safe-area-bottom',
+    left: '--mpgd-safe-area-left',
+};
 const targetViewportOrientationPolicyModeDescriptors = {
     responsive: {
         preferredOrientation: undefined,
@@ -33,6 +53,7 @@ const targetViewportOrientationPolicyModeDescriptors = {
         isLocked: true,
     },
 };
+/** Map a configured target runtime to its viewport host shell. */
 export function targetViewportShellForRuntime(runtime) {
     switch (runtime) {
         case 'capacitor-android':
@@ -49,9 +70,11 @@ export function targetViewportShellForRuntime(runtime) {
     const exhaustive = runtime;
     return exhaustive;
 }
+/** Resolve a viewport shell from the runtime field of a target config. */
 export function targetViewportShellForConfig(config) {
     return targetViewportShellForRuntime(config.runtime);
 }
+/** Normalize viewport input into responsive layout geometry. */
 export function resolveTargetViewportLayout(input, breakpoints = defaultTargetViewportBreakpoints) {
     const normalizedBreakpoints = normalizeTargetViewportBreakpoints(breakpoints);
     const width = normalizeViewportDimension(input.width, 'width');
@@ -69,9 +92,11 @@ export function resolveTargetViewportLayout(input, breakpoints = defaultTargetVi
         source: input.source ?? 'unknown',
     };
 }
+/** Classify a viewport width against normalized responsive breakpoints. */
 export function resolveTargetViewportSizeClass(width, breakpoints = defaultTargetViewportBreakpoints) {
     return classifyTargetViewportSize(normalizeViewportDimension(width, 'width'), normalizeTargetViewportBreakpoints(breakpoints));
 }
+/** Recommend primary-control and secondary-panel placement for a layout. */
 export function resolveTargetViewportRecommendation(layout) {
     const narrowOrPortrait = layout.sizeClass === 'compact' || layout.orientation === 'portrait';
     const browserSafeAreaRisk = layout.shell === 'browser' &&
@@ -83,6 +108,7 @@ export function resolveTargetViewportRecommendation(layout) {
         safeAreaAware: layout.shell !== 'browser' || layout.sizeClass === 'compact' || browserSafeAreaRisk,
     };
 }
+/** Resolve orientation mismatch behavior for a measured layout. */
 export function resolveTargetViewportOrientationPlan(layout, policy = defaultTargetViewportOrientationPolicy) {
     const normalizedPolicy = normalizeTargetViewportOrientationPolicy(policy);
     const descriptor = targetViewportOrientationPolicyModeDescriptors[normalizedPolicy.mode];
@@ -100,6 +126,7 @@ export function resolveTargetViewportOrientationPlan(layout, policy = defaultTar
         shouldShowRotatePrompt: isMismatch && mismatchBehavior === 'show-rotate-prompt',
     };
 }
+/** Build a responsive viewport plan from raw input and breakpoints. */
 export function resolveTargetViewportPlan(input, breakpoints = defaultTargetViewportBreakpoints) {
     const layout = resolveTargetViewportLayout(input, breakpoints);
     return {
@@ -108,6 +135,60 @@ export function resolveTargetViewportPlan(input, breakpoints = defaultTargetView
         orientation: resolveTargetViewportOrientationPlan(layout, input.orientationPolicy),
     };
 }
+/**
+ * Build a target viewport plan together with safe-area geometry for games that
+ * render persistent DOM controls or position Phaser HUD elements themselves.
+ */
+export function resolveTargetViewportSnapshot(input, breakpoints = defaultTargetViewportBreakpoints) {
+    const plan = resolveTargetViewportPlan(input, breakpoints);
+    return {
+        ...plan,
+        safeArea: resolveTargetViewportSafeArea(plan.layout, input.safeAreaInsets),
+    };
+}
+/**
+ * Resolve safe-area insets and content bounds for a given layout.
+ *
+ * Insets are clamped sequentially (top before bottom, left before right) so
+ * malformed host measurements cannot produce a negative-sized content region.
+ * When opposing insets exceed a viewport dimension, the first-processed side
+ * (top or left) takes priority.
+ */
+export function resolveTargetViewportSafeArea(layout, insets) {
+    const requested = normalizeTargetViewportSafeAreaInsets(insets);
+    const top = Math.min(requested.top, layout.height);
+    const bottom = Math.min(requested.bottom, layout.height - top);
+    const left = Math.min(requested.left, layout.width);
+    const right = Math.min(requested.right, layout.width - left);
+    return {
+        insets: {
+            top,
+            right,
+            bottom,
+            left,
+        },
+        contentBounds: {
+            x: left,
+            y: top,
+            width: layout.width - left - right,
+            height: layout.height - top - bottom,
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function readTargetViewportSafeAreaInsets(style, variables = defaultTargetViewportSafeAreaCssVariables) {
+    return {
+        top: readTargetViewportCssPixels(style, variables.top),
+        right: readTargetViewportCssPixels(style, variables.right),
+        bottom: readTargetViewportCssPixels(style, variables.bottom),
+        left: readTargetViewportCssPixels(style, variables.left),
+    };
+}
+/** Classify a normalized width against normalized breakpoints. */
 function classifyTargetViewportSize(width, breakpoints) {
     if (width <= breakpoints.compactMaxWidth) {
         return 'compact';
@@ -117,6 +198,7 @@ function classifyTargetViewportSize(width, breakpoints) {
     }
     return 'expanded';
 }
+/** Choose a secondary-panel placement for the resolved layout. */
 function resolveTargetViewportPanelPlacement(layout) {
     if (layout.sizeClass === 'compact') {
         return 'drawer';
@@ -126,6 +208,7 @@ function resolveTargetViewportPanelPlacement(layout) {
     }
     return 'side';
 }
+/** Fill the policy mismatch behavior from its orientation mode. */
 function normalizeTargetViewportOrientationPolicy(policy) {
     const descriptor = targetViewportOrientationPolicyModeDescriptors[policy.mode];
     return {
@@ -134,6 +217,7 @@ function normalizeTargetViewportOrientationPolicy(policy) {
             (descriptor.isLocked ? 'show-rotate-prompt' : 'continue'),
     };
 }
+/** Validate and normalize responsive breakpoint dimensions. */
 function normalizeTargetViewportBreakpoints(breakpoints) {
     const compactMaxWidth = normalizeViewportDimension(breakpoints.compactMaxWidth, 'compactMaxWidth');
     const expandedMinWidth = normalizeViewportDimension(breakpoints.expandedMinWidth, 'expandedMinWidth');
@@ -145,6 +229,29 @@ function normalizeTargetViewportBreakpoints(breakpoints) {
         expandedMinWidth,
     };
 }
+/** Validate every supplied inset and fill omitted sides with zero. */
+function normalizeTargetViewportSafeAreaInsets(insets) {
+    return {
+        top: normalizeViewportInset(insets?.top ?? 0, 'top'),
+        right: normalizeViewportInset(insets?.right ?? 0, 'right'),
+        bottom: normalizeViewportInset(insets?.bottom ?? 0, 'bottom'),
+        left: normalizeViewportInset(insets?.left ?? 0, 'left'),
+    };
+}
+/** Normalize a non-negative safe-area inset to whole CSS pixels. */
+function normalizeViewportInset(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`Viewport safe-area inset ${name} must be a non-negative finite number.`);
+    }
+    return Math.round(value);
+}
+/** Parse a non-negative CSS pixel custom-property value. */
+function readTargetViewportCssPixels(style, property) {
+    const value = style.getPropertyValue(property).trim();
+    const match = /^(\d+(?:\.\d+)?)px$/u.exec(value);
+    return match === null ? 0 : Math.round(Number(match[1]));
+}
+/** Normalize a positive viewport dimension to at least one CSS pixel. */
 function normalizeViewportDimension(value, name) {
     if (!Number.isFinite(value) || value <= 0) {
         throw new Error(`Viewport ${name} must be a positive finite number.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/target-config",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "Target-specific platform feature availability and effective config helpers for mpgd.",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
   ],
   "dependencies": {
     "typia": "13.0.2",
-    "@mpgd/catalog": "0.5.1",
+    "@mpgd/catalog": "0.5.2",
     "@mpgd/platform": "0.8.0",
     "@mpgd/i18n": "0.5.4"
   },