@mpgd/target-config 0.9.0 → 0.10.0

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.0",
+  "version": "0.10.0",
   "description": "Target-specific platform feature availability and effective config helpers for mpgd.",
   "license": "MIT",
   "repository": {
@@ -37,9 +37,9 @@
   ],
   "dependencies": {
     "typia": "13.0.2",
-    "@mpgd/catalog": "0.5.0",
-    "@mpgd/i18n": "0.5.3",
-    "@mpgd/platform": "0.7.0"
+    "@mpgd/catalog": "0.5.1",
+    "@mpgd/i18n": "0.5.4",
+    "@mpgd/platform": "0.8.0"
   },
   "devDependencies": {
     "ttsc": "0.18.4",