@mpgd/adapter-ait 0.10.0 → 0.11.0

package/dist/local-mock.d.ts

@@ -6,6 +6,17 @@
 * commerce: those paths must be verified in the Toss app sandbox/console.
 */
 declare function unsupported(): boolean;
+/**
+* Local browsers have no native safe-area constant. Throwing preserves the
+* wrapper's CSS `env(safe-area-inset-*)` fallback while keeping ESM exports in
+* parity with the SDK surface consumed by the adapter.
+*/
+export declare const SafeArea: {
+  get(): never;
+  subscribe(_input: {
+    readonly onEvent: (insets: unknown) => void;
+  }): () => void;
+};
 export declare const Storage: {
   getItem(key: string): Promise<string | null>;
   setItem(key: string, value: string): Promise<void>;

package/dist/local-mock.js

@@ -12,6 +12,19 @@ function unsupported() {
 function noOpSubscription() {
     return () => { };
 }
+/**
+ * Local browsers have no native safe-area constant. Throwing preserves the
+ * wrapper's CSS `env(safe-area-inset-*)` fallback while keeping ESM exports in
+ * parity with the SDK surface consumed by the adapter.
+ */
+export const SafeArea = {
+    get() {
+        throw new Error('SafeArea is unavailable in the Apps in Toss local mock.');
+    },
+    subscribe(_input) {
+        return noOpSubscription();
+    },
+};
 export const Storage = {
     async getItem(key) {
         return localStorageValues.get(key) ?? null;

package/dist/safe-area.d.ts

@@ -0,0 +1,54 @@
+/** Raw Apps in Toss safe-area values expressed in CSS pixels. */
+export interface AitSafeAreaInsets {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+/** Minimal SDK surface kept injectable for deterministic wrapper tests. */
+export interface AitSafeAreaSource {
+  get(): unknown;
+  subscribe(input: {
+    readonly onEvent: (insets: unknown) => void;
+  }): () => void;
+}
+/** Minimal CSS declaration surface required by the bridge. */
+export interface AitSafeAreaCssStyle {
+  getPropertyValue(property: string): string;
+  getPropertyPriority?(property: string): string;
+  setProperty(property: string, value: string, priority?: string): void;
+  removeProperty(property: string): string;
+}
+export interface InstallAitSafeAreaCssVariablesOptions {
+  readonly source?: AitSafeAreaSource;
+  readonly style?: AitSafeAreaCssStyle;
+  /** Override only when a host version or custom navigation treatment has a measured band. */
+  readonly navigationControlBandHeightPx?: number;
+  /** Override only when native navigation uses a measured right-edge gap. */
+  readonly navigationControlEdgeGapPx?: number;
+}
+/**
+* Apps in Toss positions the game navigation controls immediately below the
+* native top safe area. Keep full-width app chrome below this additional band.
+*/
+export declare const aitNavigationControlBandHeightPx = 52;
+/** Apps in Toss navigation controls retain this edge gap from the safe right inset. */
+export declare const aitNavigationControlEdgeGapPx = 10;
+/** CSS contract shared by generated AIT wrappers and full-bleed games. */
+export declare const aitSafeAreaCssVariables: Readonly<{
+  readonly top: '--mpgd-safe-area-top';
+  readonly right: '--mpgd-safe-area-right';
+  readonly bottom: '--mpgd-safe-area-bottom';
+  readonly left: '--mpgd-safe-area-left';
+  readonly navigationControlTop: '--mpgd-ait-navigation-control-top';
+  readonly navigationControlRight: '--mpgd-ait-navigation-control-right';
+  readonly navigationContentTop: '--mpgd-ait-navigation-content-top';
+}>;
+/**
+* Mirror the official AIT `SafeArea` snapshot into CSS custom properties and
+* keep them current when the WebView changes presentation or orientation.
+*
+* CSS `env(safe-area-inset-*)` remains the wrapper's pre-SDK fallback. Invalid
+* or unavailable native values never overwrite that fallback.
+*/
+export declare function installAitSafeAreaCssVariables(options?: InstallAitSafeAreaCssVariablesOptions): () => void;

package/dist/safe-area.js

@@ -0,0 +1,132 @@
+import { SafeArea } from '@apps-in-toss/web-framework';
+/**
+ * Apps in Toss positions the game navigation controls immediately below the
+ * native top safe area. Keep full-width app chrome below this additional band.
+ */
+export const aitNavigationControlBandHeightPx = 52;
+/** Apps in Toss navigation controls retain this edge gap from the safe right inset. */
+export const aitNavigationControlEdgeGapPx = 10;
+/** CSS contract shared by generated AIT wrappers and full-bleed games. */
+export const aitSafeAreaCssVariables = Object.freeze({
+    top: '--mpgd-safe-area-top',
+    right: '--mpgd-safe-area-right',
+    bottom: '--mpgd-safe-area-bottom',
+    left: '--mpgd-safe-area-left',
+    navigationControlTop: '--mpgd-ait-navigation-control-top',
+    navigationControlRight: '--mpgd-ait-navigation-control-right',
+    navigationContentTop: '--mpgd-ait-navigation-content-top',
+});
+const maximumSafeAreaInsetPx = 4096;
+const maximumCssPixelOptionPx = 4096;
+/**
+ * Mirror the official AIT `SafeArea` snapshot into CSS custom properties and
+ * keep them current when the WebView changes presentation or orientation.
+ *
+ * CSS `env(safe-area-inset-*)` remains the wrapper's pre-SDK fallback. Invalid
+ * or unavailable native values never overwrite that fallback.
+ */
+export function installAitSafeAreaCssVariables(options = {}) {
+    const navigationControlBandHeightPx = normalizeCssPixelOption(options.navigationControlBandHeightPx, aitNavigationControlBandHeightPx, 'navigationControlBandHeightPx');
+    const navigationControlEdgeGapPx = normalizeCssPixelOption(options.navigationControlEdgeGapPx, aitNavigationControlEdgeGapPx, 'navigationControlEdgeGapPx');
+    const style = options.style ?? resolveDocumentRootStyle();
+    if (style === undefined) {
+        return () => { };
+    }
+    const source = options.source ?? SafeArea;
+    const previous = rememberCssVariables(style);
+    let active = true;
+    let unsubscribe = () => { };
+    const apply = (input) => {
+        if (!active) {
+            return;
+        }
+        const insets = normalizeAitSafeAreaInsets(input);
+        if (insets === null) {
+            return;
+        }
+        style.setProperty(aitSafeAreaCssVariables.top, formatCssPixels(insets.top));
+        style.setProperty(aitSafeAreaCssVariables.right, formatCssPixels(insets.right));
+        style.setProperty(aitSafeAreaCssVariables.bottom, formatCssPixels(insets.bottom));
+        style.setProperty(aitSafeAreaCssVariables.left, formatCssPixels(insets.left));
+        style.setProperty(aitSafeAreaCssVariables.navigationControlTop, formatCssPixels(insets.top));
+        style.setProperty(aitSafeAreaCssVariables.navigationControlRight, formatCssPixels(insets.right + navigationControlEdgeGapPx));
+        style.setProperty(aitSafeAreaCssVariables.navigationContentTop, formatCssPixels(insets.top + navigationControlBandHeightPx));
+    };
+    try {
+        apply(source.get());
+    }
+    catch {
+        // Local browsers and older Toss hosts keep the CSS env() fallback.
+    }
+    try {
+        const subscribed = source.subscribe({ onEvent: apply });
+        unsubscribe = typeof subscribed === 'function' ? subscribed : () => { };
+    }
+    catch {
+        // A missing native event bridge must not prevent the game from booting.
+    }
+    return () => {
+        if (!active) {
+            return;
+        }
+        active = false;
+        try {
+            unsubscribe();
+        }
+        finally {
+            restoreCssVariables(style, previous);
+        }
+    };
+}
+function normalizeAitSafeAreaInsets(input) {
+    if (typeof input !== 'object' || input === null) {
+        return null;
+    }
+    const record = input;
+    const top = normalizeInset(record.top);
+    const right = normalizeInset(record.right);
+    const bottom = normalizeInset(record.bottom);
+    const left = normalizeInset(record.left);
+    if (top === null || right === null || bottom === null || left === null) {
+        return null;
+    }
+    return { top, right, bottom, left };
+}
+function normalizeInset(input) {
+    return typeof input === 'number'
+        && Number.isFinite(input)
+        && input >= 0
+        && input <= maximumSafeAreaInsetPx
+        ? input
+        : null;
+}
+function normalizeCssPixelOption(input, fallback, name) {
+    const value = input ?? fallback;
+    if (!Number.isFinite(value) || value < 0 || value > maximumCssPixelOptionPx) {
+        throw new TypeError(`${name} must be a non-negative finite CSS pixel value.`);
+    }
+    return value;
+}
+function formatCssPixels(value) {
+    return `${Object.is(value, -0) ? 0 : value}px`;
+}
+function resolveDocumentRootStyle() {
+    return typeof document === 'undefined' ? undefined : document.documentElement.style;
+}
+function rememberCssVariables(style) {
+    return Object.values(aitSafeAreaCssVariables).map((property) => ({
+        property,
+        value: style.getPropertyValue(property),
+        priority: style.getPropertyPriority?.(property) ?? '',
+    }));
+}
+function restoreCssVariables(style, previous) {
+    for (const entry of previous) {
+        if (entry.value.length === 0) {
+            style.removeProperty(entry.property);
+        }
+        else {
+            style.setProperty(entry.property, entry.value, entry.priority);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-ait",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Apps in Toss WebView platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -45,6 +45,10 @@
       "types": "./dist/local-mock.d.ts",
       "default": "./dist/local-mock.js"
     },
+    "./safe-area": {
+      "types": "./dist/safe-area.d.ts",
+      "default": "./dist/safe-area.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [