@oasiz/sdk 1.5.4 → 1.5.6

package/README.md

@@ -196,11 +196,32 @@ private onGameOver(): void {
 
 ### Layout
 
-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.
+Use runtime viewport insets instead of direct CSS `env(safe-area-inset-*)` reads or hardcoded offsets. The SDK resolves host-provided Oasiz values first, then browser CSS `env(safe-area-inset-*)`, then legacy `constant(safe-area-inset-*)`, and finally `0`.
+
+The top inset preserves the existing Oasiz game-safe top behavior: host chrome, invite UI, and leaderboard clearance can contribute to it. Left, right, and bottom are device safe-area insets today and may include future host UI obstructions.
+
+#### `oasiz.getViewportInsets(): ViewportInsets`
+
+Returns effective viewport insets in both CSS pixels and normalized percentages:
+
+```ts
+const insets = oasiz.getViewportInsets();
+hud.style.paddingTop = `${insets.pixels.top}px`;
+hud.style.paddingRight = `${insets.pixels.right}px`;
+hud.style.paddingBottom = `${insets.pixels.bottom}px`;
+hud.style.paddingLeft = `${insets.pixels.left}px`;
+```
+
+Percentages use the matching active viewport axis:
+
+- `top` / `bottom` are percentages of viewport height
+- `left` / `right` are percentages of viewport width
+
+Hosts may expose pixels via `window.getViewportInsets()` or `window.__OASIZ_VIEWPORT_INSETS__`, for example `{ top, right, bottom, left }` or `{ pixels: { top, right, bottom, left } }`. Hosts may expose percentages via `window.getViewportInsetsPercent()`, `window.__OASIZ_VIEWPORT_INSETS_PERCENT__`, or a `percent` object. Per-side globals such as `window.__OASIZ_SAFE_AREA_BOTTOM__` are also supported.
 
 #### `oasiz.getSafeAreaTop(): number`
 
-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`.
+Legacy alias for `oasiz.getViewportInsets().percent.top`. Returns the top inset as a percentage of viewport height (0–100). To get pixels in JavaScript, prefer `oasiz.getViewportInsets().pixels.top`. In CSS, the percent value matches **`vh`** units (for example `12.5vh` for 12.5% of the viewport height). Unsupported hosts return `0`.
 
 ```ts
 const safeTopPct = oasiz.getSafeAreaTop();
@@ -211,6 +232,10 @@ document.documentElement.style.setProperty("--safe-top", `${safeTopPct}vh`);
 
 Getter alias for `getSafeAreaTop()`.
 
+#### `oasiz.viewportInsets`
+
+Getter alias for `getViewportInsets()`.
+
 Recommended CSS pattern:
 
 ```css
@@ -397,6 +422,7 @@ import {
   openInviteModal,
   enableLogOverlay,
   getSafeAreaTop,
+  getViewportInsets,
   setLeaderboardVisible,
   onPause,
   onResume,
@@ -501,7 +527,8 @@ 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`, 0–100, % of viewport height) |
+| `oasiz.getViewportInsets()` / `viewportInsets` | `OasizSDK.GetViewportInsets()` (`ViewportInsets`, each side 0–100, % of matching viewport axis) |
+| `oasiz.getSafeAreaTop()` / `safeAreaTop` | `OasizSDK.GetSafeAreaTop()` / `OasizSDK.SafeAreaTop` (`float`, 0–100, % of viewport height; legacy alias for top viewport inset) |
 | `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

@@ -30,6 +30,7 @@ __export(index_exports, {
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
   getSafeAreaTop: () => getSafeAreaTop,
+  getViewportInsets: () => getViewportInsets,
   leaveGame: () => leaveGame,
   loadGameState: () => loadGameState,
   oasiz: () => oasiz,
@@ -1302,6 +1303,21 @@ function onResume(callback) {
 }
 
 // src/layout.ts
+var INSET_SIDES = ["top", "right", "bottom", "left"];
+var SIDE_TO_AXIS = {
+  top: "vertical",
+  right: "horizontal",
+  bottom: "vertical",
+  left: "horizontal"
+};
+function createInsetEdges(value) {
+  return {
+    top: value,
+    right: value,
+    bottom: value,
+    left: value
+  };
+}
 function isDevelopment9() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1319,53 +1335,279 @@ function warnMissingBridge6(methodName) {
     );
   }
 }
-function normalizeSafeAreaTopPixels(value) {
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function toFiniteNumber(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
-    return 0;
+    if (typeof value !== "string") {
+      return void 0;
+    }
+    const parsed = Number.parseFloat(value.trim());
+    if (!Number.isFinite(parsed)) {
+      return void 0;
+    }
+    return parsed;
   }
-  return Math.max(0, value);
+  return value;
 }
-function normalizeSafeAreaTopPercent(value) {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
+function clampInsetPixels(value) {
+  const numeric = toFiniteNumber(value);
+  if (typeof numeric === "undefined") {
+    return void 0;
+  }
+  return Math.max(0, numeric);
+}
+function normalizeInsetPercent(value) {
+  const numeric = toFiniteNumber(value);
+  if (typeof numeric === "undefined") {
+    return void 0;
+  }
+  return Math.min(100, Math.max(0, numeric));
+}
+function getViewportSize2(bridge, axis) {
+  const visualViewportSize = axis === "vertical" ? bridge.visualViewport?.height : bridge.visualViewport?.width;
+  if (typeof visualViewportSize === "number" && Number.isFinite(visualViewportSize) && visualViewportSize > 0) {
+    return visualViewportSize;
+  }
+  const innerSize = axis === "vertical" ? bridge.innerHeight : bridge.innerWidth;
+  if (typeof innerSize === "number" && Number.isFinite(innerSize) && innerSize > 0) {
+    return innerSize;
+  }
+  const documentSize = axis === "vertical" ? bridge.document?.documentElement?.clientHeight : bridge.document?.documentElement?.clientWidth;
+  if (typeof documentSize === "number" && Number.isFinite(documentSize) && documentSize > 0) {
+    return documentSize;
+  }
+  const bodySize = axis === "vertical" ? bridge.document?.body?.clientHeight : bridge.document?.body?.clientWidth;
+  if (typeof bodySize === "number" && Number.isFinite(bodySize) && bodySize > 0) {
+    return bodySize;
+  }
+  return 0;
+}
+function readCssSafeAreaValue(bridge, cssValue) {
+  const doc = bridge.document;
+  const root = doc?.body ?? doc?.documentElement;
+  if (!doc || !root || typeof doc.createElement !== "function" || typeof root.appendChild !== "function" || typeof bridge.getComputedStyle !== "function") {
     return 0;
   }
-  return Math.min(100, Math.max(0, value));
+  const probe = doc.createElement("div");
+  probe.style.position = "fixed";
+  probe.style.top = "0";
+  probe.style.left = "0";
+  probe.style.width = "0";
+  probe.style.height = "0";
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  probe.style.paddingTop = cssValue;
+  root.appendChild(probe);
+  try {
+    return clampInsetPixels(bridge.getComputedStyle(probe).paddingTop) ?? 0;
+  } finally {
+    if (typeof probe.remove === "function") {
+      probe.remove();
+    } else {
+      probe.parentNode?.removeChild(probe);
+    }
+  }
+}
+function readCssSafeAreaPixels(bridge, side) {
+  const envPixels = readCssSafeAreaValue(
+    bridge,
+    "env(safe-area-inset-" + side + ")"
+  );
+  if (envPixels > 0) {
+    return envPixels;
+  }
+  return readCssSafeAreaValue(
+    bridge,
+    "constant(safe-area-inset-" + side + ")"
+  );
+}
+function getDevicePixelRatio(bridge) {
+  const dpr = bridge.devicePixelRatio;
+  if (typeof dpr !== "number" || !Number.isFinite(dpr) || dpr <= 0) {
+    return 1;
+  }
+  return dpr;
+}
+function roughlyEqualPixels(a, b) {
+  return Math.abs(a - b) <= 2;
+}
+function normalizeInsetPixels(value, bridge, side) {
+  const pixels = clampInsetPixels(value);
+  if (typeof pixels === "undefined") {
+    return void 0;
+  }
+  const cssEnvPixels = readCssSafeAreaPixels(bridge, side);
+  if (pixels <= 0) {
+    return cssEnvPixels;
+  }
+  const dpr = getDevicePixelRatio(bridge);
+  if (cssEnvPixels > 0 && dpr > 1 && roughlyEqualPixels(pixels / dpr, cssEnvPixels)) {
+    return cssEnvPixels;
+  }
+  return pixels;
 }
-function viewportInnerHeight(bridge) {
-  const h = bridge.innerHeight;
-  if (typeof h !== "number" || !Number.isFinite(h) || h <= 0) {
+function pixelsToPercentOfViewport(pixels, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
     return 0;
   }
-  return h;
+  return normalizeInsetPercent(pixels / size * 100) ?? 0;
 }
-function pixelsTopToPercentOfViewport(pixels, bridge) {
-  const h = viewportInnerHeight(bridge);
-  if (h <= 0) {
+function percentToPixelsOfViewport(percent, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
     return 0;
   }
-  return normalizeSafeAreaTopPercent(pixels / h * 100);
+  return percent / 100 * size;
 }
-function getSafeAreaTop() {
+function cssSafeAreaPercent(bridge, side) {
+  return pixelsToPercentOfViewport(readCssSafeAreaPixels(bridge, side), bridge, side);
+}
+function resolvePercentValue(value, bridge, side) {
+  const percent = normalizeInsetPercent(value);
+  if (typeof percent === "undefined") {
+    return void 0;
+  }
+  return percent > 0 ? percent : cssSafeAreaPercent(bridge, side);
+}
+function resolvePixelValue(value, bridge, side) {
+  const numeric = toFiniteNumber(value);
+  if (typeof numeric === "undefined") {
+    return void 0;
+  }
+  return normalizeInsetPixels(numeric, bridge, side);
+}
+function sideSuffix(side) {
+  switch (side) {
+    case "top":
+      return "Top";
+    case "right":
+      return "Right";
+    case "bottom":
+      return "Bottom";
+    case "left":
+      return "Left";
+  }
+}
+function callBridgeFunction(bridge, name) {
+  const fn = bridge[name];
+  if (typeof fn !== "function") {
+    return void 0;
+  }
+  try {
+    return fn.call(bridge);
+  } catch (error) {
+    console.error("[oasiz/sdk] " + String(name) + " failed:", error);
+    return void 0;
+  }
+}
+function readInsetObjectValue(value, side, group) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  if (group) {
+    return isRecord(value[group]) ? value[group][side] : void 0;
+  }
+  return value[side];
+}
+function firstDefined(...values) {
+  return values.find((value) => typeof value !== "undefined");
+}
+function readHostInsetSources(bridge) {
+  return {
+    globalPixels: bridge.__OASIZ_VIEWPORT_INSETS__,
+    globalPercent: bridge.__OASIZ_VIEWPORT_INSETS_PERCENT__,
+    methodPixels: callBridgeFunction(bridge, "getViewportInsets"),
+    methodPercent: callBridgeFunction(bridge, "getViewportInsetsPercent")
+  };
+}
+function readIndividualPercentValue(bridge, side) {
+  const suffix = sideSuffix(side);
+  return firstDefined(
+    callBridgeFunction(
+      bridge,
+      "getSafeArea" + suffix + "Percent"
+    ),
+    bridge["__OASIZ_SAFE_AREA_" + side.toUpperCase() + "_PERCENT__"]
+  );
+}
+function readIndividualPixelValue(bridge, side) {
+  const suffix = sideSuffix(side);
+  return firstDefined(
+    callBridgeFunction(
+      bridge,
+      "getSafeArea" + suffix
+    ),
+    bridge["__OASIZ_SAFE_AREA_" + side.toUpperCase() + "__"]
+  );
+}
+function resolveInsetSide(bridge, sources, side) {
+  const percentCandidate = firstDefined(
+    readInsetObjectValue(sources.methodPercent, side, "percent"),
+    readInsetObjectValue(sources.methodPercent, side),
+    readInsetObjectValue(sources.globalPercent, side, "percent"),
+    readInsetObjectValue(sources.globalPercent, side),
+    readInsetObjectValue(sources.methodPixels, side, "percent"),
+    readInsetObjectValue(sources.globalPixels, side, "percent"),
+    readIndividualPercentValue(bridge, side)
+  );
+  const percent = resolvePercentValue(percentCandidate, bridge, side);
+  if (typeof percent !== "undefined") {
+    return {
+      pixels: percentToPixelsOfViewport(percent, bridge, side),
+      percent
+    };
+  }
+  const pixelCandidate = firstDefined(
+    readInsetObjectValue(sources.methodPixels, side, "pixels"),
+    readInsetObjectValue(sources.methodPixels, side),
+    readInsetObjectValue(sources.globalPixels, side, "pixels"),
+    readInsetObjectValue(sources.globalPixels, side),
+    readIndividualPixelValue(bridge, side)
+  );
+  const pixels = resolvePixelValue(pixelCandidate, bridge, side);
+  if (typeof pixels !== "undefined") {
+    return {
+      pixels,
+      percent: pixelsToPercentOfViewport(pixels, bridge, side)
+    };
+  }
+  const cssPixels = readCssSafeAreaPixels(bridge, side);
+  return {
+    pixels: cssPixels,
+    percent: pixelsToPercentOfViewport(cssPixels, bridge, side)
+  };
+}
+function getViewportInsets() {
   const bridge = getBridgeWindow8();
   if (!bridge) {
-    return 0;
-  }
-  if (typeof bridge.getSafeAreaTopPercent === "function") {
-    return normalizeSafeAreaTopPercent(bridge.getSafeAreaTopPercent());
+    return {
+      pixels: createInsetEdges(0),
+      percent: createInsetEdges(0)
+    };
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__ !== "undefined") {
-    return normalizeSafeAreaTopPercent(bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__);
+  const sources = readHostInsetSources(bridge);
+  const pixels = createInsetEdges(0);
+  const percent = createInsetEdges(0);
+  for (const side of INSET_SIDES) {
+    const resolved = resolveInsetSide(bridge, sources, side);
+    pixels[side] = resolved.pixels;
+    percent[side] = resolved.percent;
   }
-  if (typeof bridge.getSafeAreaTop === "function") {
-    const px = normalizeSafeAreaTopPixels(bridge.getSafeAreaTop());
-    return pixelsTopToPercentOfViewport(px, bridge);
+  return { pixels, percent };
+}
+function getSafeAreaTop() {
+  const bridge = getBridgeWindow8();
+  if (!bridge) {
+    return 0;
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
-    const px = normalizeSafeAreaTopPixels(bridge.__OASIZ_SAFE_AREA_TOP__);
-    return pixelsTopToPercentOfViewport(px, bridge);
+  const top = getViewportInsets().percent.top;
+  if (top <= 0) {
+    warnMissingBridge6("getSafeAreaTop");
   }
-  warnMissingBridge6("getSafeAreaTop");
-  return 0;
+  return top;
 }
 function setLeaderboardVisible(visible) {
   if (typeof visible !== "boolean") {
@@ -1486,6 +1728,7 @@ var oasiz = {
   onPause,
   onResume,
   getSafeAreaTop,
+  getViewportInsets,
   setLeaderboardVisible,
   onBackButton,
   onLeaveGame,
@@ -1507,6 +1750,9 @@ var oasiz = {
   },
   get safeAreaTop() {
     return getSafeAreaTop();
+  },
+  get viewportInsets() {
+    return getViewportInsets();
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1521,6 +1767,7 @@ var oasiz = {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getViewportInsets,
   leaveGame,
   loadGameState,
   oasiz,

package/dist/index.d.cts

@@ -1,3 +1,28 @@
+type ViewportInsetSide = "top" | "right" | "bottom" | "left";
+interface ViewportInsetEdges {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface ViewportInsets {
+    pixels: ViewportInsetEdges;
+    percent: ViewportInsetEdges;
+}
+/**
+ * Effective viewport insets that game UI should avoid.
+ *
+ * `top` preserves the existing Oasiz game-safe top behavior: host chrome and
+ * invite/leaderboard clearance can contribute to it. Other sides are device
+ * safe-area insets today, and can include future host UI obstructions.
+ */
+declare function getViewportInsets(): ViewportInsets;
+/**
+ * Legacy alias for the top entry of `getViewportInsets().percent`.
+ */
+declare function getSafeAreaTop(): number;
+declare function setLeaderboardVisible(visible: boolean): void;
+
 type HapticType = "light" | "medium" | "heavy" | "success" | "error";
 type LogOverlayLevel = "debug" | "log" | "info" | "warn" | "error";
 interface LogOverlayEntry {
@@ -196,15 +221,6 @@ 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;
-
 declare function onBackButton(callback: () => void): Unsubscribe;
 declare function onLeaveGame(callback: () => void): Unsubscribe;
 declare function leaveGame(): void;
@@ -225,6 +241,7 @@ declare const oasiz: {
     onPause: typeof onPause;
     onResume: typeof onResume;
     getSafeAreaTop: typeof getSafeAreaTop;
+    getViewportInsets: typeof getViewportInsets;
     setLeaderboardVisible: typeof setLeaderboardVisible;
     onBackButton: typeof onBackButton;
     onLeaveGame: typeof onLeaveGame;
@@ -235,6 +252,7 @@ declare const oasiz: {
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
     readonly safeAreaTop: number;
+    readonly viewportInsets: ViewportInsets;
 };
 
-export { type FacingFrameMap, type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, addScore, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };
+export { type FacingFrameMap, type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -1,3 +1,28 @@
+type ViewportInsetSide = "top" | "right" | "bottom" | "left";
+interface ViewportInsetEdges {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface ViewportInsets {
+    pixels: ViewportInsetEdges;
+    percent: ViewportInsetEdges;
+}
+/**
+ * Effective viewport insets that game UI should avoid.
+ *
+ * `top` preserves the existing Oasiz game-safe top behavior: host chrome and
+ * invite/leaderboard clearance can contribute to it. Other sides are device
+ * safe-area insets today, and can include future host UI obstructions.
+ */
+declare function getViewportInsets(): ViewportInsets;
+/**
+ * Legacy alias for the top entry of `getViewportInsets().percent`.
+ */
+declare function getSafeAreaTop(): number;
+declare function setLeaderboardVisible(visible: boolean): void;
+
 type HapticType = "light" | "medium" | "heavy" | "success" | "error";
 type LogOverlayLevel = "debug" | "log" | "info" | "warn" | "error";
 interface LogOverlayEntry {
@@ -196,15 +221,6 @@ 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;
-
 declare function onBackButton(callback: () => void): Unsubscribe;
 declare function onLeaveGame(callback: () => void): Unsubscribe;
 declare function leaveGame(): void;
@@ -225,6 +241,7 @@ declare const oasiz: {
     onPause: typeof onPause;
     onResume: typeof onResume;
     getSafeAreaTop: typeof getSafeAreaTop;
+    getViewportInsets: typeof getViewportInsets;
     setLeaderboardVisible: typeof setLeaderboardVisible;
     onBackButton: typeof onBackButton;
     onLeaveGame: typeof onLeaveGame;
@@ -235,6 +252,7 @@ declare const oasiz: {
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
     readonly safeAreaTop: number;
+    readonly viewportInsets: ViewportInsets;
 };
 
-export { type FacingFrameMap, type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, addScore, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };
+export { type FacingFrameMap, type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.js

@@ -1252,6 +1252,21 @@ function onResume(callback) {
 }
 
 // src/layout.ts
+var INSET_SIDES = ["top", "right", "bottom", "left"];
+var SIDE_TO_AXIS = {
+  top: "vertical",
+  right: "horizontal",
+  bottom: "vertical",
+  left: "horizontal"
+};
+function createInsetEdges(value) {
+  return {
+    top: value,
+    right: value,
+    bottom: value,
+    left: value
+  };
+}
 function isDevelopment9() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1269,53 +1284,279 @@ function warnMissingBridge6(methodName) {
     );
   }
 }
-function normalizeSafeAreaTopPixels(value) {
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function toFiniteNumber(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
-    return 0;
+    if (typeof value !== "string") {
+      return void 0;
+    }
+    const parsed = Number.parseFloat(value.trim());
+    if (!Number.isFinite(parsed)) {
+      return void 0;
+    }
+    return parsed;
   }
-  return Math.max(0, value);
+  return value;
 }
-function normalizeSafeAreaTopPercent(value) {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
+function clampInsetPixels(value) {
+  const numeric = toFiniteNumber(value);
+  if (typeof numeric === "undefined") {
+    return void 0;
+  }
+  return Math.max(0, numeric);
+}
+function normalizeInsetPercent(value) {
+  const numeric = toFiniteNumber(value);
+  if (typeof numeric === "undefined") {
+    return void 0;
+  }
+  return Math.min(100, Math.max(0, numeric));
+}
+function getViewportSize2(bridge, axis) {
+  const visualViewportSize = axis === "vertical" ? bridge.visualViewport?.height : bridge.visualViewport?.width;
+  if (typeof visualViewportSize === "number" && Number.isFinite(visualViewportSize) && visualViewportSize > 0) {
+    return visualViewportSize;
+  }
+  const innerSize = axis === "vertical" ? bridge.innerHeight : bridge.innerWidth;
+  if (typeof innerSize === "number" && Number.isFinite(innerSize) && innerSize > 0) {
+    return innerSize;
+  }
+  const documentSize = axis === "vertical" ? bridge.document?.documentElement?.clientHeight : bridge.document?.documentElement?.clientWidth;
+  if (typeof documentSize === "number" && Number.isFinite(documentSize) && documentSize > 0) {
+    return documentSize;
+  }
+  const bodySize = axis === "vertical" ? bridge.document?.body?.clientHeight : bridge.document?.body?.clientWidth;
+  if (typeof bodySize === "number" && Number.isFinite(bodySize) && bodySize > 0) {
+    return bodySize;
+  }
+  return 0;
+}
+function readCssSafeAreaValue(bridge, cssValue) {
+  const doc = bridge.document;
+  const root = doc?.body ?? doc?.documentElement;
+  if (!doc || !root || typeof doc.createElement !== "function" || typeof root.appendChild !== "function" || typeof bridge.getComputedStyle !== "function") {
     return 0;
   }
-  return Math.min(100, Math.max(0, value));
+  const probe = doc.createElement("div");
+  probe.style.position = "fixed";
+  probe.style.top = "0";
+  probe.style.left = "0";
+  probe.style.width = "0";
+  probe.style.height = "0";
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  probe.style.paddingTop = cssValue;
+  root.appendChild(probe);
+  try {
+    return clampInsetPixels(bridge.getComputedStyle(probe).paddingTop) ?? 0;
+  } finally {
+    if (typeof probe.remove === "function") {
+      probe.remove();
+    } else {
+      probe.parentNode?.removeChild(probe);
+    }
+  }
+}
+function readCssSafeAreaPixels(bridge, side) {
+  const envPixels = readCssSafeAreaValue(
+    bridge,
+    "env(safe-area-inset-" + side + ")"
+  );
+  if (envPixels > 0) {
+    return envPixels;
+  }
+  return readCssSafeAreaValue(
+    bridge,
+    "constant(safe-area-inset-" + side + ")"
+  );
+}
+function getDevicePixelRatio(bridge) {
+  const dpr = bridge.devicePixelRatio;
+  if (typeof dpr !== "number" || !Number.isFinite(dpr) || dpr <= 0) {
+    return 1;
+  }
+  return dpr;
+}
+function roughlyEqualPixels(a, b) {
+  return Math.abs(a - b) <= 2;
+}
+function normalizeInsetPixels(value, bridge, side) {
+  const pixels = clampInsetPixels(value);
+  if (typeof pixels === "undefined") {
+    return void 0;
+  }
+  const cssEnvPixels = readCssSafeAreaPixels(bridge, side);
+  if (pixels <= 0) {
+    return cssEnvPixels;
+  }
+  const dpr = getDevicePixelRatio(bridge);
+  if (cssEnvPixels > 0 && dpr > 1 && roughlyEqualPixels(pixels / dpr, cssEnvPixels)) {
+    return cssEnvPixels;
+  }
+  return pixels;
 }
-function viewportInnerHeight(bridge) {
-  const h = bridge.innerHeight;
-  if (typeof h !== "number" || !Number.isFinite(h) || h <= 0) {
+function pixelsToPercentOfViewport(pixels, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
     return 0;
   }
-  return h;
+  return normalizeInsetPercent(pixels / size * 100) ?? 0;
 }
-function pixelsTopToPercentOfViewport(pixels, bridge) {
-  const h = viewportInnerHeight(bridge);
-  if (h <= 0) {
+function percentToPixelsOfViewport(percent, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
     return 0;
   }
-  return normalizeSafeAreaTopPercent(pixels / h * 100);
+  return percent / 100 * size;
 }
-function getSafeAreaTop() {
+function cssSafeAreaPercent(bridge, side) {
+  return pixelsToPercentOfViewport(readCssSafeAreaPixels(bridge, side), bridge, side);
+}
+function resolvePercentValue(value, bridge, side) {
+  const percent = normalizeInsetPercent(value);
+  if (typeof percent === "undefined") {
+    return void 0;
+  }
+  return percent > 0 ? percent : cssSafeAreaPercent(bridge, side);
+}
+function resolvePixelValue(value, bridge, side) {
+  const numeric = toFiniteNumber(value);
+  if (typeof numeric === "undefined") {
+    return void 0;
+  }
+  return normalizeInsetPixels(numeric, bridge, side);
+}
+function sideSuffix(side) {
+  switch (side) {
+    case "top":
+      return "Top";
+    case "right":
+      return "Right";
+    case "bottom":
+      return "Bottom";
+    case "left":
+      return "Left";
+  }
+}
+function callBridgeFunction(bridge, name) {
+  const fn = bridge[name];
+  if (typeof fn !== "function") {
+    return void 0;
+  }
+  try {
+    return fn.call(bridge);
+  } catch (error) {
+    console.error("[oasiz/sdk] " + String(name) + " failed:", error);
+    return void 0;
+  }
+}
+function readInsetObjectValue(value, side, group) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  if (group) {
+    return isRecord(value[group]) ? value[group][side] : void 0;
+  }
+  return value[side];
+}
+function firstDefined(...values) {
+  return values.find((value) => typeof value !== "undefined");
+}
+function readHostInsetSources(bridge) {
+  return {
+    globalPixels: bridge.__OASIZ_VIEWPORT_INSETS__,
+    globalPercent: bridge.__OASIZ_VIEWPORT_INSETS_PERCENT__,
+    methodPixels: callBridgeFunction(bridge, "getViewportInsets"),
+    methodPercent: callBridgeFunction(bridge, "getViewportInsetsPercent")
+  };
+}
+function readIndividualPercentValue(bridge, side) {
+  const suffix = sideSuffix(side);
+  return firstDefined(
+    callBridgeFunction(
+      bridge,
+      "getSafeArea" + suffix + "Percent"
+    ),
+    bridge["__OASIZ_SAFE_AREA_" + side.toUpperCase() + "_PERCENT__"]
+  );
+}
+function readIndividualPixelValue(bridge, side) {
+  const suffix = sideSuffix(side);
+  return firstDefined(
+    callBridgeFunction(
+      bridge,
+      "getSafeArea" + suffix
+    ),
+    bridge["__OASIZ_SAFE_AREA_" + side.toUpperCase() + "__"]
+  );
+}
+function resolveInsetSide(bridge, sources, side) {
+  const percentCandidate = firstDefined(
+    readInsetObjectValue(sources.methodPercent, side, "percent"),
+    readInsetObjectValue(sources.methodPercent, side),
+    readInsetObjectValue(sources.globalPercent, side, "percent"),
+    readInsetObjectValue(sources.globalPercent, side),
+    readInsetObjectValue(sources.methodPixels, side, "percent"),
+    readInsetObjectValue(sources.globalPixels, side, "percent"),
+    readIndividualPercentValue(bridge, side)
+  );
+  const percent = resolvePercentValue(percentCandidate, bridge, side);
+  if (typeof percent !== "undefined") {
+    return {
+      pixels: percentToPixelsOfViewport(percent, bridge, side),
+      percent
+    };
+  }
+  const pixelCandidate = firstDefined(
+    readInsetObjectValue(sources.methodPixels, side, "pixels"),
+    readInsetObjectValue(sources.methodPixels, side),
+    readInsetObjectValue(sources.globalPixels, side, "pixels"),
+    readInsetObjectValue(sources.globalPixels, side),
+    readIndividualPixelValue(bridge, side)
+  );
+  const pixels = resolvePixelValue(pixelCandidate, bridge, side);
+  if (typeof pixels !== "undefined") {
+    return {
+      pixels,
+      percent: pixelsToPercentOfViewport(pixels, bridge, side)
+    };
+  }
+  const cssPixels = readCssSafeAreaPixels(bridge, side);
+  return {
+    pixels: cssPixels,
+    percent: pixelsToPercentOfViewport(cssPixels, bridge, side)
+  };
+}
+function getViewportInsets() {
   const bridge = getBridgeWindow8();
   if (!bridge) {
-    return 0;
-  }
-  if (typeof bridge.getSafeAreaTopPercent === "function") {
-    return normalizeSafeAreaTopPercent(bridge.getSafeAreaTopPercent());
+    return {
+      pixels: createInsetEdges(0),
+      percent: createInsetEdges(0)
+    };
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__ !== "undefined") {
-    return normalizeSafeAreaTopPercent(bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__);
+  const sources = readHostInsetSources(bridge);
+  const pixels = createInsetEdges(0);
+  const percent = createInsetEdges(0);
+  for (const side of INSET_SIDES) {
+    const resolved = resolveInsetSide(bridge, sources, side);
+    pixels[side] = resolved.pixels;
+    percent[side] = resolved.percent;
   }
-  if (typeof bridge.getSafeAreaTop === "function") {
-    const px = normalizeSafeAreaTopPixels(bridge.getSafeAreaTop());
-    return pixelsTopToPercentOfViewport(px, bridge);
+  return { pixels, percent };
+}
+function getSafeAreaTop() {
+  const bridge = getBridgeWindow8();
+  if (!bridge) {
+    return 0;
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
-    const px = normalizeSafeAreaTopPixels(bridge.__OASIZ_SAFE_AREA_TOP__);
-    return pixelsTopToPercentOfViewport(px, bridge);
+  const top = getViewportInsets().percent.top;
+  if (top <= 0) {
+    warnMissingBridge6("getSafeAreaTop");
   }
-  warnMissingBridge6("getSafeAreaTop");
-  return 0;
+  return top;
 }
 function setLeaderboardVisible(visible) {
   if (typeof visible !== "boolean") {
@@ -1436,6 +1677,7 @@ var oasiz = {
   onPause,
   onResume,
   getSafeAreaTop,
+  getViewportInsets,
   setLeaderboardVisible,
   onBackButton,
   onLeaveGame,
@@ -1457,6 +1699,9 @@ var oasiz = {
   },
   get safeAreaTop() {
     return getSafeAreaTop();
+  },
+  get viewportInsets() {
+    return getViewportInsets();
   }
 };
 export {
@@ -1470,6 +1715,7 @@ export {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getViewportInsets,
   leaveGame,
   loadGameState,
   oasiz,

package/package.json

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