@oasiz/sdk 1.5.2 → 1.5.3

package/README.md

@@ -21,7 +21,9 @@ Typed SDK for integrating browser games with the Oasiz platform: score, haptics,
 npm install @oasiz/sdk
 ```
 
-### Quick start
+The published package includes ESM, CommonJS, and TypeScript declarations.
+
+## Quick start
 
 ```ts
 import { oasiz } from "@oasiz/sdk";
@@ -36,10 +38,10 @@ oasiz.saveGameState({ level, coins: 42 });
 // 3. Trigger haptics on key events
 oasiz.triggerHaptic("medium");
 
-// 4. Respect the host's top safe area
+// 4. Respect the host's top safe area (percent of viewport height → CSS vh)
 document.documentElement.style.setProperty(
   "--safe-top",
-  `${oasiz.safeAreaTop}px`,
+  `${oasiz.safeAreaTop}vh`,
 );
 
 // 5. Submit score when the game ends
@@ -194,15 +196,15 @@ private onGameOver(): void {
 
 ### Layout
 
-Use the runtime safe-area value instead of hardcoded top offsets. The host reports the current top inset in **CSS pixels** for persistent chrome such as the back button and top controls.
+Use the runtime safe-area value instead of hardcoded top offsets. The SDK returns the top inset as **a percentage of the viewport height (0–100)**. If the host exposes CSS pixels via `window.getSafeAreaTop()` or `window.__OASIZ_SAFE_AREA_TOP__`, the SDK converts using `window.innerHeight`. The host may instead set **`window.getSafeAreaTopPercent()`** or **`window.__OASIZ_SAFE_AREA_TOP_PERCENT__`** (0–100) and that value is used directly.
 
 #### `oasiz.getSafeAreaTop(): number`
 
-Returns the current top inset. The host may expose `window.getSafeAreaTop()` or `window.__OASIZ_SAFE_AREA_TOP__`. Unsupported hosts return `0`.
+Returns the top inset as a percentage of viewport height (0–100). To get pixels in JavaScript, use `(getSafeAreaTop() / 100) * window.innerHeight`. In CSS, the same value matches **`vh`** units (for example `12.5vh` for 12.5% of the viewport height). Unsupported hosts return `0`.
 
 ```ts
-const safeTop = oasiz.getSafeAreaTop();
-document.documentElement.style.setProperty("--safe-top", `${safeTop}px`);
+const safeTopPct = oasiz.getSafeAreaTop();
+document.documentElement.style.setProperty("--safe-top", `${safeTopPct}vh`);
 ```
 
 #### `oasiz.safeAreaTop`
@@ -453,9 +455,10 @@ public class GameManager : MonoBehaviour
         OasizSDK.OnPause += OnPause;
         OasizSDK.OnResume += OnResume;
 
-        // Offset UI for the host's top safe area
-        float safeTop = OasizSDK.SafeAreaTop;
-        Debug.Log($"Safe area top: {safeTop}px");
+        // Offset UI for the host's top safe area (0–100 percent of Screen.height)
+        float safeTopPct = OasizSDK.SafeAreaTop;
+        float safeTopPx = safeTopPct / 100f * Screen.height;
+        Debug.Log($"Safe area top: {safeTopPx}px ({safeTopPct}% of height)");
 
         // Emit score normalization anchors
         OasizSDK.EmitScoreConfig(new ScoreConfig(
@@ -498,7 +501,7 @@ public class GameManager : MonoBehaviour
 | `oasiz.loadGameState()` | `OasizSDK.LoadGameState()` → `Dictionary<string, object>` |
 | `oasiz.saveGameState(obj)` | `OasizSDK.SaveGameState(Dictionary<string, object>)` |
 | `oasiz.flushGameState()` | `OasizSDK.FlushGameState()` |
-| `oasiz.getSafeAreaTop()` / `safeAreaTop` | `OasizSDK.GetSafeAreaTop()` / `OasizSDK.SafeAreaTop` (`float`, CSS px) |
+| `oasiz.getSafeAreaTop()` / `safeAreaTop` | `OasizSDK.GetSafeAreaTop()` / `OasizSDK.SafeAreaTop` (`float`, 0–100, % of viewport height) |
 | `oasiz.setLeaderboardVisible(v)` | `OasizSDK.SetLeaderboardVisible(bool)` |
 | `oasiz.onPause` / `onResume` | `OasizSDK.OnPause` / `OnResume` static events |
 | `oasiz.onBackButton` | `OasizSDK.OnBackButton` or `SubscribeBackButton(Action)` (reference-counts `__oasizSetBackOverride`) |

package/dist/index.cjs

@@ -1217,22 +1217,50 @@ function warnMissingBridge4(methodName) {
     );
   }
 }
-function normalizeSafeAreaTop(value) {
+function normalizeSafeAreaTopPixels(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return 0;
   }
   return Math.max(0, value);
 }
+function normalizeSafeAreaTopPercent(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.min(100, Math.max(0, value));
+}
+function viewportInnerHeight(bridge) {
+  const h = bridge.innerHeight;
+  if (typeof h !== "number" || !Number.isFinite(h) || h <= 0) {
+    return 0;
+  }
+  return h;
+}
+function pixelsTopToPercentOfViewport(pixels, bridge) {
+  const h = viewportInnerHeight(bridge);
+  if (h <= 0) {
+    return 0;
+  }
+  return normalizeSafeAreaTopPercent(pixels / h * 100);
+}
 function getSafeAreaTop() {
   const bridge = getBridgeWindow6();
   if (!bridge) {
     return 0;
   }
+  if (typeof bridge.getSafeAreaTopPercent === "function") {
+    return normalizeSafeAreaTopPercent(bridge.getSafeAreaTopPercent());
+  }
+  if (typeof bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__ !== "undefined") {
+    return normalizeSafeAreaTopPercent(bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__);
+  }
   if (typeof bridge.getSafeAreaTop === "function") {
-    return normalizeSafeAreaTop(bridge.getSafeAreaTop());
+    const px = normalizeSafeAreaTopPixels(bridge.getSafeAreaTop());
+    return pixelsTopToPercentOfViewport(px, bridge);
   }
   if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
-    return normalizeSafeAreaTop(bridge.__OASIZ_SAFE_AREA_TOP__);
+    const px = normalizeSafeAreaTopPixels(bridge.__OASIZ_SAFE_AREA_TOP__);
+    return pixelsTopToPercentOfViewport(px, bridge);
   }
   warnMissingBridge4("getSafeAreaTop");
   return 0;

package/dist/index.d.cts

@@ -62,6 +62,12 @@ type Unsubscribe = () => void;
 declare function onPause(callback: () => void): Unsubscribe;
 declare function onResume(callback: () => void): Unsubscribe;
 
+/**
+ * Top safe-area inset as a percentage of the viewport height (0–100).
+ * The host may expose CSS pixels via `getSafeAreaTop` / `__OASIZ_SAFE_AREA_TOP__`
+ * (converted using `window.innerHeight`), or percentages via
+ * `getSafeAreaTopPercent` / `__OASIZ_SAFE_AREA_TOP_PERCENT__`.
+ */
 declare function getSafeAreaTop(): number;
 declare function setLeaderboardVisible(visible: boolean): void;
 

package/dist/index.d.ts

@@ -62,6 +62,12 @@ type Unsubscribe = () => void;
 declare function onPause(callback: () => void): Unsubscribe;
 declare function onResume(callback: () => void): Unsubscribe;
 
+/**
+ * Top safe-area inset as a percentage of the viewport height (0–100).
+ * The host may expose CSS pixels via `getSafeAreaTop` / `__OASIZ_SAFE_AREA_TOP__`
+ * (converted using `window.innerHeight`), or percentages via
+ * `getSafeAreaTopPercent` / `__OASIZ_SAFE_AREA_TOP_PERCENT__`.
+ */
 declare function getSafeAreaTop(): number;
 declare function setLeaderboardVisible(visible: boolean): void;
 

package/dist/index.js

@@ -1171,22 +1171,50 @@ function warnMissingBridge4(methodName) {
     );
   }
 }
-function normalizeSafeAreaTop(value) {
+function normalizeSafeAreaTopPixels(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return 0;
   }
   return Math.max(0, value);
 }
+function normalizeSafeAreaTopPercent(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.min(100, Math.max(0, value));
+}
+function viewportInnerHeight(bridge) {
+  const h = bridge.innerHeight;
+  if (typeof h !== "number" || !Number.isFinite(h) || h <= 0) {
+    return 0;
+  }
+  return h;
+}
+function pixelsTopToPercentOfViewport(pixels, bridge) {
+  const h = viewportInnerHeight(bridge);
+  if (h <= 0) {
+    return 0;
+  }
+  return normalizeSafeAreaTopPercent(pixels / h * 100);
+}
 function getSafeAreaTop() {
   const bridge = getBridgeWindow6();
   if (!bridge) {
     return 0;
   }
+  if (typeof bridge.getSafeAreaTopPercent === "function") {
+    return normalizeSafeAreaTopPercent(bridge.getSafeAreaTopPercent());
+  }
+  if (typeof bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__ !== "undefined") {
+    return normalizeSafeAreaTopPercent(bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__);
+  }
   if (typeof bridge.getSafeAreaTop === "function") {
-    return normalizeSafeAreaTop(bridge.getSafeAreaTop());
+    const px = normalizeSafeAreaTopPixels(bridge.getSafeAreaTop());
+    return pixelsTopToPercentOfViewport(px, bridge);
   }
   if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
-    return normalizeSafeAreaTop(bridge.__OASIZ_SAFE_AREA_TOP__);
+    const px = normalizeSafeAreaTopPixels(bridge.__OASIZ_SAFE_AREA_TOP__);
+    return pixelsTopToPercentOfViewport(px, bridge);
   }
   warnMissingBridge4("getSafeAreaTop");
   return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",