@oasiz/sdk 1.5.5 → 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 active viewport height (0–100)**. If the host exposes CSS pixels via `window.getSafeAreaTop()` or `window.__OASIZ_SAFE_AREA_TOP__`, the SDK converts using `window.visualViewport.height` when available, then `window.innerHeight`, then document height. The host may instead set **`window.getSafeAreaTopPercent()`** or **`window.__OASIZ_SAFE_AREA_TOP_PERCENT__`** (0–100) and that value is used directly. When no host bridge is available, the SDK falls back to CSS `env(safe-area-inset-top)` / `constant(safe-area-inset-top)`.
+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, multiply by `window.visualViewport?.height || 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,6 +1335,9 @@ function warnMissingBridge6(methodName) {
     );
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
 function toFiniteNumber(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     if (typeof value !== "string") {
@@ -1332,36 +1351,36 @@ function toFiniteNumber(value) {
   }
   return value;
 }
-function clampSafeAreaTopPixels(value) {
+function clampInsetPixels(value) {
   const numeric = toFiniteNumber(value);
   if (typeof numeric === "undefined") {
-    return 0;
+    return void 0;
   }
   return Math.max(0, numeric);
 }
-function normalizeSafeAreaTopPercent(value) {
+function normalizeInsetPercent(value) {
   const numeric = toFiniteNumber(value);
   if (typeof numeric === "undefined") {
     return void 0;
   }
   return Math.min(100, Math.max(0, numeric));
 }
-function getViewportHeight(bridge) {
-  const visualViewportHeight = bridge.visualViewport?.height;
-  if (typeof visualViewportHeight === "number" && Number.isFinite(visualViewportHeight) && visualViewportHeight > 0) {
-    return visualViewportHeight;
+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 innerHeight = bridge.innerHeight;
-  if (typeof innerHeight === "number" && Number.isFinite(innerHeight) && innerHeight > 0) {
-    return innerHeight;
+  const innerSize = axis === "vertical" ? bridge.innerHeight : bridge.innerWidth;
+  if (typeof innerSize === "number" && Number.isFinite(innerSize) && innerSize > 0) {
+    return innerSize;
   }
-  const documentHeight = bridge.document?.documentElement?.clientHeight;
-  if (typeof documentHeight === "number" && Number.isFinite(documentHeight) && documentHeight > 0) {
-    return documentHeight;
+  const documentSize = axis === "vertical" ? bridge.document?.documentElement?.clientHeight : bridge.document?.documentElement?.clientWidth;
+  if (typeof documentSize === "number" && Number.isFinite(documentSize) && documentSize > 0) {
+    return documentSize;
   }
-  const bodyHeight = bridge.document?.body?.clientHeight;
-  if (typeof bodyHeight === "number" && Number.isFinite(bodyHeight) && bodyHeight > 0) {
-    return bodyHeight;
+  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;
 }
@@ -1382,7 +1401,7 @@ function readCssSafeAreaValue(bridge, cssValue) {
   probe.style.paddingTop = cssValue;
   root.appendChild(probe);
   try {
-    return clampSafeAreaTopPixels(bridge.getComputedStyle(probe).paddingTop);
+    return clampInsetPixels(bridge.getComputedStyle(probe).paddingTop) ?? 0;
   } finally {
     if (typeof probe.remove === "function") {
       probe.remove();
@@ -1391,12 +1410,18 @@ function readCssSafeAreaValue(bridge, cssValue) {
     }
   }
 }
-function readCssSafeAreaTopPixels(bridge) {
-  const envPixels = readCssSafeAreaValue(bridge, "env(safe-area-inset-top)");
+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-top)");
+  return readCssSafeAreaValue(
+    bridge,
+    "constant(safe-area-inset-" + side + ")"
+  );
 }
 function getDevicePixelRatio(bridge) {
   const dpr = bridge.devicePixelRatio;
@@ -1408,9 +1433,12 @@ function getDevicePixelRatio(bridge) {
 function roughlyEqualPixels(a, b) {
   return Math.abs(a - b) <= 2;
 }
-function normalizeSafeAreaTopPixels(value, bridge) {
-  const pixels = clampSafeAreaTopPixels(value);
-  const cssEnvPixels = readCssSafeAreaTopPixels(bridge);
+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;
   }
@@ -1420,65 +1448,166 @@ function normalizeSafeAreaTopPixels(value, bridge) {
   }
   return pixels;
 }
-function pixelsTopToPercentOfViewport(pixels, bridge) {
-  const h = getViewportHeight(bridge);
-  if (h <= 0) {
+function pixelsToPercentOfViewport(pixels, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
+    return 0;
+  }
+  return normalizeInsetPercent(pixels / size * 100) ?? 0;
+}
+function percentToPixelsOfViewport(percent, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
     return 0;
   }
-  return normalizeSafeAreaTopPercent(pixels / h * 100) ?? 0;
+  return percent / 100 * size;
 }
-function cssSafeAreaTopPercent(bridge) {
-  return pixelsTopToPercentOfViewport(readCssSafeAreaTopPixels(bridge), bridge);
+function cssSafeAreaPercent(bridge, side) {
+  return pixelsToPercentOfViewport(readCssSafeAreaPixels(bridge, side), bridge, side);
 }
-function resolvePercentValue(value, bridge) {
-  const percent = normalizeSafeAreaTopPercent(value);
+function resolvePercentValue(value, bridge, side) {
+  const percent = normalizeInsetPercent(value);
   if (typeof percent === "undefined") {
     return void 0;
   }
-  return percent > 0 ? percent : cssSafeAreaTopPercent(bridge);
+  return percent > 0 ? percent : cssSafeAreaPercent(bridge, side);
 }
-function resolvePixelValue(value, bridge) {
+function resolvePixelValue(value, bridge, side) {
   const numeric = toFiniteNumber(value);
   if (typeof numeric === "undefined") {
     return void 0;
   }
-  return pixelsTopToPercentOfViewport(normalizeSafeAreaTopPixels(numeric, bridge), bridge);
+  return normalizeInsetPixels(numeric, bridge, side);
 }
-function getSafeAreaTop() {
-  const bridge = getBridgeWindow8();
-  if (!bridge) {
-    return 0;
+function sideSuffix(side) {
+  switch (side) {
+    case "top":
+      return "Top";
+    case "right":
+      return "Right";
+    case "bottom":
+      return "Bottom";
+    case "left":
+      return "Left";
   }
-  if (typeof bridge.getSafeAreaTopPercent === "function") {
-    const percent = resolvePercentValue(bridge.getSafeAreaTopPercent(), bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+}
+function callBridgeFunction(bridge, name) {
+  const fn = bridge[name];
+  if (typeof fn !== "function") {
+    return void 0;
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__ !== "undefined") {
-    const percent = resolvePercentValue(bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__, bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+  try {
+    return fn.call(bridge);
+  } catch (error) {
+    console.error("[oasiz/sdk] " + String(name) + " failed:", error);
+    return void 0;
   }
-  if (typeof bridge.getSafeAreaTop === "function") {
-    const percent = resolvePixelValue(bridge.getSafeAreaTop(), bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+}
+function readInsetObjectValue(value, side, group) {
+  if (!isRecord(value)) {
+    return void 0;
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
-    const percent = resolvePixelValue(bridge.__OASIZ_SAFE_AREA_TOP__, bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+  if (group) {
+    return isRecord(value[group]) ? value[group][side] : void 0;
   }
-  const cssPercent = cssSafeAreaTopPercent(bridge);
-  if (cssPercent > 0) {
-    return cssPercent;
+  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
+    };
   }
-  warnMissingBridge6("getSafeAreaTop");
-  return 0;
+  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 {
+      pixels: createInsetEdges(0),
+      percent: createInsetEdges(0)
+    };
+  }
+  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;
+  }
+  return { pixels, percent };
+}
+function getSafeAreaTop() {
+  const bridge = getBridgeWindow8();
+  if (!bridge) {
+    return 0;
+  }
+  const top = getViewportInsets().percent.top;
+  if (top <= 0) {
+    warnMissingBridge6("getSafeAreaTop");
+  }
+  return top;
 }
 function setLeaderboardVisible(visible) {
   if (typeof visible !== "boolean") {
@@ -1599,6 +1728,7 @@ var oasiz = {
   onPause,
   onResume,
   getSafeAreaTop,
+  getViewportInsets,
   setLeaderboardVisible,
   onBackButton,
   onLeaveGame,
@@ -1620,6 +1750,9 @@ var oasiz = {
   },
   get safeAreaTop() {
     return getSafeAreaTop();
+  },
+  get viewportInsets() {
+    return getViewportInsets();
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1634,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,6 +1284,9 @@ function warnMissingBridge6(methodName) {
     );
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
 function toFiniteNumber(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     if (typeof value !== "string") {
@@ -1282,36 +1300,36 @@ function toFiniteNumber(value) {
   }
   return value;
 }
-function clampSafeAreaTopPixels(value) {
+function clampInsetPixels(value) {
   const numeric = toFiniteNumber(value);
   if (typeof numeric === "undefined") {
-    return 0;
+    return void 0;
   }
   return Math.max(0, numeric);
 }
-function normalizeSafeAreaTopPercent(value) {
+function normalizeInsetPercent(value) {
   const numeric = toFiniteNumber(value);
   if (typeof numeric === "undefined") {
     return void 0;
   }
   return Math.min(100, Math.max(0, numeric));
 }
-function getViewportHeight(bridge) {
-  const visualViewportHeight = bridge.visualViewport?.height;
-  if (typeof visualViewportHeight === "number" && Number.isFinite(visualViewportHeight) && visualViewportHeight > 0) {
-    return visualViewportHeight;
+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 innerHeight = bridge.innerHeight;
-  if (typeof innerHeight === "number" && Number.isFinite(innerHeight) && innerHeight > 0) {
-    return innerHeight;
+  const innerSize = axis === "vertical" ? bridge.innerHeight : bridge.innerWidth;
+  if (typeof innerSize === "number" && Number.isFinite(innerSize) && innerSize > 0) {
+    return innerSize;
   }
-  const documentHeight = bridge.document?.documentElement?.clientHeight;
-  if (typeof documentHeight === "number" && Number.isFinite(documentHeight) && documentHeight > 0) {
-    return documentHeight;
+  const documentSize = axis === "vertical" ? bridge.document?.documentElement?.clientHeight : bridge.document?.documentElement?.clientWidth;
+  if (typeof documentSize === "number" && Number.isFinite(documentSize) && documentSize > 0) {
+    return documentSize;
   }
-  const bodyHeight = bridge.document?.body?.clientHeight;
-  if (typeof bodyHeight === "number" && Number.isFinite(bodyHeight) && bodyHeight > 0) {
-    return bodyHeight;
+  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;
 }
@@ -1332,7 +1350,7 @@ function readCssSafeAreaValue(bridge, cssValue) {
   probe.style.paddingTop = cssValue;
   root.appendChild(probe);
   try {
-    return clampSafeAreaTopPixels(bridge.getComputedStyle(probe).paddingTop);
+    return clampInsetPixels(bridge.getComputedStyle(probe).paddingTop) ?? 0;
   } finally {
     if (typeof probe.remove === "function") {
       probe.remove();
@@ -1341,12 +1359,18 @@ function readCssSafeAreaValue(bridge, cssValue) {
     }
   }
 }
-function readCssSafeAreaTopPixels(bridge) {
-  const envPixels = readCssSafeAreaValue(bridge, "env(safe-area-inset-top)");
+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-top)");
+  return readCssSafeAreaValue(
+    bridge,
+    "constant(safe-area-inset-" + side + ")"
+  );
 }
 function getDevicePixelRatio(bridge) {
   const dpr = bridge.devicePixelRatio;
@@ -1358,9 +1382,12 @@ function getDevicePixelRatio(bridge) {
 function roughlyEqualPixels(a, b) {
   return Math.abs(a - b) <= 2;
 }
-function normalizeSafeAreaTopPixels(value, bridge) {
-  const pixels = clampSafeAreaTopPixels(value);
-  const cssEnvPixels = readCssSafeAreaTopPixels(bridge);
+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;
   }
@@ -1370,65 +1397,166 @@ function normalizeSafeAreaTopPixels(value, bridge) {
   }
   return pixels;
 }
-function pixelsTopToPercentOfViewport(pixels, bridge) {
-  const h = getViewportHeight(bridge);
-  if (h <= 0) {
+function pixelsToPercentOfViewport(pixels, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
+    return 0;
+  }
+  return normalizeInsetPercent(pixels / size * 100) ?? 0;
+}
+function percentToPixelsOfViewport(percent, bridge, side) {
+  const size = getViewportSize2(bridge, SIDE_TO_AXIS[side]);
+  if (size <= 0) {
     return 0;
   }
-  return normalizeSafeAreaTopPercent(pixels / h * 100) ?? 0;
+  return percent / 100 * size;
 }
-function cssSafeAreaTopPercent(bridge) {
-  return pixelsTopToPercentOfViewport(readCssSafeAreaTopPixels(bridge), bridge);
+function cssSafeAreaPercent(bridge, side) {
+  return pixelsToPercentOfViewport(readCssSafeAreaPixels(bridge, side), bridge, side);
 }
-function resolvePercentValue(value, bridge) {
-  const percent = normalizeSafeAreaTopPercent(value);
+function resolvePercentValue(value, bridge, side) {
+  const percent = normalizeInsetPercent(value);
   if (typeof percent === "undefined") {
     return void 0;
   }
-  return percent > 0 ? percent : cssSafeAreaTopPercent(bridge);
+  return percent > 0 ? percent : cssSafeAreaPercent(bridge, side);
 }
-function resolvePixelValue(value, bridge) {
+function resolvePixelValue(value, bridge, side) {
   const numeric = toFiniteNumber(value);
   if (typeof numeric === "undefined") {
     return void 0;
   }
-  return pixelsTopToPercentOfViewport(normalizeSafeAreaTopPixels(numeric, bridge), bridge);
+  return normalizeInsetPixels(numeric, bridge, side);
 }
-function getSafeAreaTop() {
-  const bridge = getBridgeWindow8();
-  if (!bridge) {
-    return 0;
+function sideSuffix(side) {
+  switch (side) {
+    case "top":
+      return "Top";
+    case "right":
+      return "Right";
+    case "bottom":
+      return "Bottom";
+    case "left":
+      return "Left";
   }
-  if (typeof bridge.getSafeAreaTopPercent === "function") {
-    const percent = resolvePercentValue(bridge.getSafeAreaTopPercent(), bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+}
+function callBridgeFunction(bridge, name) {
+  const fn = bridge[name];
+  if (typeof fn !== "function") {
+    return void 0;
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__ !== "undefined") {
-    const percent = resolvePercentValue(bridge.__OASIZ_SAFE_AREA_TOP_PERCENT__, bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+  try {
+    return fn.call(bridge);
+  } catch (error) {
+    console.error("[oasiz/sdk] " + String(name) + " failed:", error);
+    return void 0;
   }
-  if (typeof bridge.getSafeAreaTop === "function") {
-    const percent = resolvePixelValue(bridge.getSafeAreaTop(), bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+}
+function readInsetObjectValue(value, side, group) {
+  if (!isRecord(value)) {
+    return void 0;
   }
-  if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
-    const percent = resolvePixelValue(bridge.__OASIZ_SAFE_AREA_TOP__, bridge);
-    if (typeof percent !== "undefined") {
-      return percent;
-    }
+  if (group) {
+    return isRecord(value[group]) ? value[group][side] : void 0;
   }
-  const cssPercent = cssSafeAreaTopPercent(bridge);
-  if (cssPercent > 0) {
-    return cssPercent;
+  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
+    };
   }
-  warnMissingBridge6("getSafeAreaTop");
-  return 0;
+  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 {
+      pixels: createInsetEdges(0),
+      percent: createInsetEdges(0)
+    };
+  }
+  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;
+  }
+  return { pixels, percent };
+}
+function getSafeAreaTop() {
+  const bridge = getBridgeWindow8();
+  if (!bridge) {
+    return 0;
+  }
+  const top = getViewportInsets().percent.top;
+  if (top <= 0) {
+    warnMissingBridge6("getSafeAreaTop");
+  }
+  return top;
 }
 function setLeaderboardVisible(visible) {
   if (typeof visible !== "boolean") {
@@ -1549,6 +1677,7 @@ var oasiz = {
   onPause,
   onResume,
   getSafeAreaTop,
+  getViewportInsets,
   setLeaderboardVisible,
   onBackButton,
   onLeaveGame,
@@ -1570,6 +1699,9 @@ var oasiz = {
   },
   get safeAreaTop() {
     return getSafeAreaTop();
+  },
+  get viewportInsets() {
+    return getViewportInsets();
   }
 };
 export {
@@ -1583,6 +1715,7 @@ export {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getViewportInsets,
   leaveGame,
   loadGameState,
   oasiz,

package/package.json

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