@mpgd/target-config 0.15.2 → 0.17.0

package/dist/viewport.js

@@ -152,6 +152,104 @@ export function resolveTargetViewportSnapshot(input, breakpoints = defaultTarget
         safeArea: resolveTargetViewportSafeArea(plan.layout, input.safeAreaInsets),
     };
 }
+/** Whether a size can produce a viewport plan: both sides finite and at least one CSS pixel. */
+export function isMeasurableTargetViewport(size) {
+    return isMeasurableViewportDimension(size.width) && isMeasurableViewportDimension(size.height);
+}
+/**
+ * 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 function measureTargetViewport(sources) {
+    const rect = sources.container?.getBoundingClientRect();
+    if (rect !== undefined && isMeasurableTargetViewport(rect)) {
+        return { width: rect.width, height: rect.height, source: 'container' };
+    }
+    const visualViewport = sources.visualViewport;
+    if (visualViewport !== undefined &&
+        visualViewport !== null &&
+        isMeasurableTargetViewport(visualViewport)) {
+        return {
+            width: visualViewport.width,
+            height: visualViewport.height,
+            source: 'visual-viewport',
+        };
+    }
+    const host = sources.window;
+    if (host !== undefined && host !== null) {
+        const size = { width: host.innerWidth, height: host.innerHeight };
+        if (isMeasurableTargetViewport(size)) {
+            return { ...size, source: 'window' };
+        }
+    }
+    return 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 function waitForTargetViewportMeasurement(input) {
+    let initial;
+    try {
+        initial = input.measure();
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    if (initial !== null) {
+        return Promise.resolve(initial);
+    }
+    if (input.signal?.aborted === true) {
+        return Promise.reject(input.signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        // The listener may settle synchronously inside `subscribe`, before its cleanup is returned.
+        const subscription = {};
+        const settle = () => {
+            settled = true;
+            subscription.unsubscribe?.();
+            input.signal?.removeEventListener('abort', abort);
+        };
+        const check = () => {
+            if (settled) {
+                return;
+            }
+            let measurement;
+            try {
+                measurement = input.measure();
+            }
+            catch (error) {
+                settle();
+                reject(error);
+                return;
+            }
+            if (measurement !== null) {
+                settle();
+                resolve(measurement);
+            }
+        };
+        const abort = () => {
+            if (!settled) {
+                settle();
+                reject(input.signal?.reason);
+            }
+        };
+        input.signal?.addEventListener('abort', abort, { once: true });
+        const unsubscribe = input.subscribe(check);
+        if (settled) {
+            unsubscribe();
+            return;
+        }
+        subscription.unsubscribe = unsubscribe;
+        // A resize may land between the first measurement and the subscription.
+        check();
+    });
+}
 /**
  * Resolve an adaptive game shell inside the snapshot's safe content bounds.
  *
@@ -255,6 +353,75 @@ export function resolveTargetViewportSafeArea(layout, insets) {
         },
     };
 }
+/**
+ * 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 function resolveTargetViewportUsableArea(layout, input = {}) {
+    const viewport = {
+        width: normalizeViewportDimension(layout.width, 'width'),
+        height: normalizeViewportDimension(layout.height, 'height'),
+    };
+    const safeArea = normalizeTargetViewportSafeAreaInsets(input.safeAreaInsets);
+    const systemBars = normalizeTargetViewportSafeAreaInsets(input.systemBarInsets);
+    const keyboard = normalizeTargetViewportSafeAreaInsets(input.keyboardInsets);
+    const insets = {
+        top: Math.max(safeArea.top, systemBars.top, keyboard.top),
+        right: Math.max(safeArea.right, systemBars.right, keyboard.right),
+        bottom: Math.max(safeArea.bottom, systemBars.bottom, keyboard.bottom),
+        left: Math.max(safeArea.left, systemBars.left, keyboard.left),
+    };
+    const occupiedSurfaceIds = new Set();
+    for (const surface of input.occupiedSurfaces ?? []) {
+        if (surface.surfaceId.trim() === '' || occupiedSurfaceIds.has(surface.surfaceId)) {
+            throw new Error('Viewport occupied surface IDs must be non-empty and unique.');
+        }
+        occupiedSurfaceIds.add(surface.surfaceId);
+        const { x: rawX, y: rawY, width: rawWidth, height: rawHeight } = surface.bounds;
+        if (![rawX, rawY, rawWidth, rawHeight].every(Number.isFinite)
+            || rawX < 0 || rawY < 0 || rawWidth < 0 || rawHeight < 0) {
+            throw new Error(`Viewport occupied surface ${surface.surfaceId} is outside the viewport.`);
+        }
+        // Round endpoints using the same whole-CSS-pixel convention as viewport
+        // dimensions. Rounding an origin and size separately can make a valid
+        // full-width fractional surface appear to exceed the rounded viewport.
+        const x = Math.round(rawX);
+        const y = Math.round(rawY);
+        const right = Math.round(rawX + rawWidth);
+        const bottom = Math.round(rawY + rawHeight);
+        const width = right - x;
+        const height = bottom - y;
+        if (right > viewport.width || bottom > viewport.height) {
+            throw new Error(`Viewport occupied surface ${surface.surfaceId} is outside the viewport.`);
+        }
+        if (width === 0 || height === 0) {
+            continue;
+        }
+        switch (surface.edge) {
+            case 'top':
+                insets.top = Math.max(insets.top, y + height);
+                break;
+            case 'right':
+                insets.right = Math.max(insets.right, viewport.width - x);
+                break;
+            case 'bottom':
+                insets.bottom = Math.max(insets.bottom, viewport.height - y);
+                break;
+            case 'left':
+                insets.left = Math.max(insets.left, x + width);
+                break;
+            default:
+                throw new Error('Viewport occupied surface edge is invalid.');
+        }
+    }
+    return {
+        ...resolveTargetViewportSafeArea(viewport, insets),
+        occupiedSurfaceIds: [...occupiedSurfaceIds],
+    };
+}
 /**
  * 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
@@ -345,6 +512,10 @@ function readTargetViewportCssPixels(style, property) {
     const match = /^(\d+(?:\.\d+)?)px$/u.exec(value);
     return match === null ? 0 : Math.round(Number(match[1]));
 }
+/** Whether a dimension would pass {@link normalizeViewportDimension}. */
+function isMeasurableViewportDimension(value) {
+    return Number.isFinite(value) && value > 0 && Math.round(value) > 0;
+}
 /** Normalize a positive viewport dimension to at least one CSS pixel. */
 function normalizeViewportDimension(value, name) {
     if (!Number.isFinite(value) || value <= 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/target-config",
-  "version": "0.15.2",
+  "version": "0.17.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.7.4",
-    "@mpgd/i18n": "0.6.3",
-    "@mpgd/platform": "0.12.2"
+    "@mpgd/catalog": "0.7.6",
+    "@mpgd/i18n": "0.6.5",
+    "@mpgd/platform": "0.14.0"
   },
   "devDependencies": {
     "ttsc": "0.30.4",
@@ -55,6 +55,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "cd ../.. && node tools/run-ttsx.mjs packages/target-config/test/target-config-smoke.ts && node tools/run-ttsx.mjs packages/target-config/test/platform-version-allocation-smoke.ts"
+    "test": "cd ../.. && node tools/run-ttsx.mjs packages/target-config/test/target-config-smoke.ts && node tools/run-ttsx.mjs packages/target-config/test/platform-version-allocation-smoke.ts && node tools/run-ttsx.mjs packages/target-config/test/provider-availability-smoke.ts"
   }
 }