@oasiz/sdk 1.5.1 → 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`
@@ -298,7 +300,18 @@ quitButton.addEventListener("click", () => {
 });
 ```
 
-#### `oasiz.onLeaveGame(callback: () => void): Unsubscribe`
+### `oasiz.share(options: { text?: string; score?: number; image?: string }): Promise<void>`
+
+Ask the host to open the same share flow Oasiz already uses today. Use `text` to customize the share message, `score` to trigger a challenge-style share, and `image` to share an `http(s)` URL or `data:image/...` payload.
+
+```ts
+await oasiz.share({
+  text: "I made it to level 9!",
+  score: 4200,
+});
+```
+
+### `oasiz.onLeaveGame(callback: () => void): Unsubscribe`
 
 Registers a callback fired when the host initiates closing the game (for example, close button, gesture, or host navigation). Use this for lightweight cleanup.
 
@@ -375,6 +388,7 @@ All methods are also available as named exports if you prefer not to use the `oa
 ```ts
 import {
   submitScore,
+  share,
   triggerHaptic,
   loadGameState,
   saveGameState,
@@ -406,6 +420,7 @@ import type {
   LogOverlayHandle,
   LogOverlayLevel,
   LogOverlayOptions,
+  ShareRequest,
   ShareRoomCodeOptions,
   Unsubscribe,
 } from "@oasiz/sdk";
@@ -440,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(
@@ -485,12 +501,13 @@ 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`) |
 | `oasiz.onLeaveGame` | `OasizSDK.OnLeaveGame` |
 | `oasiz.leaveGame()` | `OasizSDK.LeaveGame()` |
+| `oasiz.share(request)` | `OasizSDK.Share(ShareRequest)` |
 | `oasiz.shareRoomCode` | `OasizSDK.ShareRoomCode(string, ShareRoomCodeOptions)` |
 | `oasiz.openInviteModal()` | `OasizSDK.OpenInviteModal()` |
 | `oasiz.gameId` / `roomCode` / ... | `OasizSDK.GameId` / `RoomCode` / `PlayerName` / `PlayerAvatar` |
@@ -498,6 +515,19 @@ public class GameManager : MonoBehaviour
 | `oasiz.enableLogOverlay` | `OasizSDK.EnableLogOverlay(LogOverlayOptions)` (see note below) |
 | -- | `OasizSDK.AppendLogOverlay(level, message, stackTrace)` (see note below) |
 
+### Share (Unity)
+
+HTML5 **`oasiz.share`** returns a **Promise** you can `await`. Unity **`OasizSDK.Share(ShareRequest)`** returns **`void`**: C# validation throws **`ArgumentException`** with the same rules as TypeScript (at least one of text, score, or image; non-negative integer score; `http(s)` or `data:image/...;base64,...` image). The call forwards JSON to **`window.__oasizShareRequest`**. If the host promise rejects, the **WebGL `.jslib` logs the error** to the browser console.
+
+```csharp
+OasizSDK.Share(new ShareRequest
+{
+    Text = "Beat this run!",
+    Score = 1200,
+    Image = "https://example.com/card.png",
+});
+```
+
 ### Types
 
 ```csharp
@@ -508,6 +538,14 @@ public enum HapticType { Light, Medium, Heavy, Success, Error }
 public struct ScoreAnchor { public int raw; public int normalized; }
 public struct ScoreConfig { public ScoreAnchor[] anchors; }
 
+// Host share sheet (text / score / image URL or data URL)
+public class ShareRequest
+{
+    public string Text { get; set; }
+    public int? Score { get; set; }
+    public string Image { get; set; }
+}
+
 // Multiplayer invite options
 public class ShareRoomCodeOptions { public bool InviteOverride { get; set; } }
 

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   openInviteModal: () => openInviteModal,
   saveGameState: () => saveGameState,
   setLeaderboardVisible: () => setLeaderboardVisible,
+  share: () => share,
   shareRoomCode: () => shareRoomCode,
   submitScore: () => submitScore,
   triggerHaptic: () => triggerHaptic
@@ -1044,7 +1045,7 @@ function submitScore(score) {
   warnMissingBridge("submitScore");
 }
 
-// src/state.ts
+// src/share.ts
 function isDevelopment4() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1055,6 +1056,69 @@ function getBridgeWindow4() {
   }
   return window;
 }
+function warnMissingBridge2(methodName) {
+  if (isDevelopment4()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " share bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+function isValidImageReference(image) {
+  if (/^data:image\/[a-zA-Z0-9.+-]+;base64,/.test(image)) {
+    return true;
+  }
+  try {
+    const parsed = new URL(image);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function validateRequest(options) {
+  const text = typeof options.text === "string" ? options.text.trim() : "";
+  const hasText = text.length > 0;
+  const hasScore = options.score !== void 0;
+  const hasImage = typeof options.image === "string" && options.image.length > 0;
+  if (!hasText && !hasScore && !hasImage) {
+    throw new Error("Share request requires text, score, or image.");
+  }
+  if (hasScore) {
+    if (typeof options.score !== "number" || !Number.isInteger(options.score) || options.score < 0) {
+      throw new Error("Share score must be a non-negative integer.");
+    }
+  }
+  if (hasImage && !isValidImageReference(options.image)) {
+    throw new Error(
+      "Share image must be an http(s) URL or a data:image/... base64 string."
+    );
+  }
+  return {
+    ...hasText ? { text } : {},
+    ...hasScore ? { score: options.score } : {},
+    ...hasImage ? { image: options.image } : {}
+  };
+}
+async function share(options) {
+  const request = validateRequest(options);
+  const bridge = getBridgeWindow4();
+  if (typeof bridge?.__oasizShareRequest !== "function") {
+    warnMissingBridge2("__oasizShareRequest");
+    throw new Error("Share bridge unavailable");
+  }
+  await bridge.__oasizShareRequest(request);
+}
+
+// src/state.ts
+function isDevelopment5() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow5() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
 function isPlainObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -1062,22 +1126,22 @@ function isPlainObject(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
-function warnMissingBridge2(methodName) {
-  if (isDevelopment4()) {
+function warnMissingBridge3(methodName) {
+  if (isDevelopment5()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
   }
 }
 function loadGameState() {
-  const bridge = getBridgeWindow4();
+  const bridge = getBridgeWindow5();
   if (typeof bridge?.loadGameState !== "function") {
-    warnMissingBridge2("loadGameState");
+    warnMissingBridge3("loadGameState");
     return {};
   }
   const state = bridge.loadGameState();
   if (!isPlainObject(state)) {
-    if (isDevelopment4()) {
+    if (isDevelopment5()) {
       console.warn(
         "[oasiz/sdk] loadGameState returned invalid data. Falling back to empty object."
       );
@@ -1088,35 +1152,35 @@ function loadGameState() {
 }
 function saveGameState(state) {
   if (!isPlainObject(state)) {
-    if (isDevelopment4()) {
+    if (isDevelopment5()) {
       console.warn("[oasiz/sdk] saveGameState expected a plain object:", state);
     }
     return;
   }
-  const bridge = getBridgeWindow4();
+  const bridge = getBridgeWindow5();
   if (typeof bridge?.saveGameState === "function") {
     bridge.saveGameState(state);
     return;
   }
-  warnMissingBridge2("saveGameState");
+  warnMissingBridge3("saveGameState");
 }
 function flushGameState() {
-  const bridge = getBridgeWindow4();
+  const bridge = getBridgeWindow5();
   if (typeof bridge?.flushGameState === "function") {
     bridge.flushGameState();
     return;
   }
-  warnMissingBridge2("flushGameState");
+  warnMissingBridge3("flushGameState");
 }
 
 // src/lifecycle.ts
-function isDevelopment5() {
+function isDevelopment6() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
 function addLifecycleListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment5()) {
+    if (isDevelopment6()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1136,46 +1200,74 @@ function onResume(callback) {
 }
 
 // src/layout.ts
-function isDevelopment6() {
+function isDevelopment7() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow5() {
+function getBridgeWindow6() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
-function warnMissingBridge3(methodName) {
-  if (isDevelopment6()) {
+function warnMissingBridge4(methodName) {
+  if (isDevelopment7()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
   }
 }
-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 = getBridgeWindow5();
+  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);
   }
-  warnMissingBridge3("getSafeAreaTop");
+  warnMissingBridge4("getSafeAreaTop");
   return 0;
 }
 function setLeaderboardVisible(visible) {
   if (typeof visible !== "boolean") {
-    if (isDevelopment6()) {
+    if (isDevelopment7()) {
       console.warn(
         "[oasiz/sdk] setLeaderboardVisible expected a boolean:",
         visible
@@ -1183,28 +1275,28 @@ function setLeaderboardVisible(visible) {
     }
     return;
   }
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow6();
   if (typeof bridge?.__oasizSetLeaderboardVisible === "function") {
     bridge.__oasizSetLeaderboardVisible(visible);
     return;
   }
-  warnMissingBridge3("__oasizSetLeaderboardVisible");
+  warnMissingBridge4("__oasizSetLeaderboardVisible");
 }
 
 // src/navigation.ts
 var activeBackListeners = 0;
-function isDevelopment7() {
+function isDevelopment8() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow6() {
+function getBridgeWindow7() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
-function warnMissingBridge4(methodName) {
-  if (isDevelopment7()) {
+function warnMissingBridge5(methodName) {
+  if (isDevelopment8()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
@@ -1220,7 +1312,7 @@ function normalizeNavigationError(error) {
 }
 function addNavigationListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment7()) {
+    if (isDevelopment8()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1241,24 +1333,24 @@ function onBackButton(callback) {
       throw normalizeNavigationError(error);
     }
   });
-  const bridge = getBridgeWindow6();
+  const bridge = getBridgeWindow7();
   activeBackListeners += 1;
   if (activeBackListeners === 1) {
     if (typeof bridge?.__oasizSetBackOverride === "function") {
       bridge.__oasizSetBackOverride(true);
     } else {
-      warnMissingBridge4("__oasizSetBackOverride");
+      warnMissingBridge5("__oasizSetBackOverride");
     }
   }
   return () => {
     off();
     activeBackListeners = Math.max(0, activeBackListeners - 1);
     if (activeBackListeners === 0) {
-      const currentBridge = getBridgeWindow6();
+      const currentBridge = getBridgeWindow7();
       if (typeof currentBridge?.__oasizSetBackOverride === "function") {
         currentBridge.__oasizSetBackOverride(false);
       } else {
-        warnMissingBridge4("__oasizSetBackOverride");
+        warnMissingBridge5("__oasizSetBackOverride");
       }
     }
   };
@@ -1267,17 +1359,18 @@ function onLeaveGame(callback) {
   return addNavigationListener("oasiz:leave", callback);
 }
 function leaveGame() {
-  const bridge = getBridgeWindow6();
+  const bridge = getBridgeWindow7();
   if (typeof bridge?.__oasizLeaveGame === "function") {
     bridge.__oasizLeaveGame();
     return;
   }
-  warnMissingBridge4("__oasizLeaveGame");
+  warnMissingBridge5("__oasizLeaveGame");
 }
 
 // src/index.ts
 var oasiz = {
   submitScore,
+  share,
   triggerHaptic,
   enableLogOverlay,
   loadGameState,
@@ -1327,6 +1420,7 @@ var oasiz = {
   openInviteModal,
   saveGameState,
   setLeaderboardVisible,
+  share,
   shareRoomCode,
   submitScore,
   triggerHaptic

package/dist/index.d.cts

@@ -20,6 +20,11 @@ interface LogOverlayHandle {
     show: () => void;
 }
 type GameState = Record<string, unknown>;
+interface ShareRequest {
+    image?: string;
+    score?: number;
+    text?: string;
+}
 
 declare function triggerHaptic(type: HapticType): void;
 
@@ -47,6 +52,8 @@ declare function getPlayerAvatar(): string | undefined;
 
 declare function submitScore(score: number): void;
 
+declare function share(options: ShareRequest): Promise<void>;
+
 declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
 declare function flushGameState(): void;
@@ -55,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;
 
@@ -64,6 +77,7 @@ declare function leaveGame(): void;
 
 declare const oasiz: {
     submitScore: typeof submitScore;
+    share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
     loadGameState: typeof loadGameState;
@@ -85,4 +99,4 @@ declare const oasiz: {
     readonly safeAreaTop: number;
 };
 
-export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ShareRoomCodeOptions, type Unsubscribe, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, shareRoomCode, submitScore, triggerHaptic };
+export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ShareRequest, type ShareRoomCodeOptions, type Unsubscribe, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -20,6 +20,11 @@ interface LogOverlayHandle {
     show: () => void;
 }
 type GameState = Record<string, unknown>;
+interface ShareRequest {
+    image?: string;
+    score?: number;
+    text?: string;
+}
 
 declare function triggerHaptic(type: HapticType): void;
 
@@ -47,6 +52,8 @@ declare function getPlayerAvatar(): string | undefined;
 
 declare function submitScore(score: number): void;
 
+declare function share(options: ShareRequest): Promise<void>;
+
 declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
 declare function flushGameState(): void;
@@ -55,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;
 
@@ -64,6 +77,7 @@ declare function leaveGame(): void;
 
 declare const oasiz: {
     submitScore: typeof submitScore;
+    share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
     loadGameState: typeof loadGameState;
@@ -85,4 +99,4 @@ declare const oasiz: {
     readonly safeAreaTop: number;
 };
 
-export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ShareRoomCodeOptions, type Unsubscribe, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, shareRoomCode, submitScore, triggerHaptic };
+export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ShareRequest, type ShareRoomCodeOptions, type Unsubscribe, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.js

@@ -999,7 +999,7 @@ function submitScore(score) {
   warnMissingBridge("submitScore");
 }
 
-// src/state.ts
+// src/share.ts
 function isDevelopment4() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1010,6 +1010,69 @@ function getBridgeWindow4() {
   }
   return window;
 }
+function warnMissingBridge2(methodName) {
+  if (isDevelopment4()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " share bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+function isValidImageReference(image) {
+  if (/^data:image\/[a-zA-Z0-9.+-]+;base64,/.test(image)) {
+    return true;
+  }
+  try {
+    const parsed = new URL(image);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function validateRequest(options) {
+  const text = typeof options.text === "string" ? options.text.trim() : "";
+  const hasText = text.length > 0;
+  const hasScore = options.score !== void 0;
+  const hasImage = typeof options.image === "string" && options.image.length > 0;
+  if (!hasText && !hasScore && !hasImage) {
+    throw new Error("Share request requires text, score, or image.");
+  }
+  if (hasScore) {
+    if (typeof options.score !== "number" || !Number.isInteger(options.score) || options.score < 0) {
+      throw new Error("Share score must be a non-negative integer.");
+    }
+  }
+  if (hasImage && !isValidImageReference(options.image)) {
+    throw new Error(
+      "Share image must be an http(s) URL or a data:image/... base64 string."
+    );
+  }
+  return {
+    ...hasText ? { text } : {},
+    ...hasScore ? { score: options.score } : {},
+    ...hasImage ? { image: options.image } : {}
+  };
+}
+async function share(options) {
+  const request = validateRequest(options);
+  const bridge = getBridgeWindow4();
+  if (typeof bridge?.__oasizShareRequest !== "function") {
+    warnMissingBridge2("__oasizShareRequest");
+    throw new Error("Share bridge unavailable");
+  }
+  await bridge.__oasizShareRequest(request);
+}
+
+// src/state.ts
+function isDevelopment5() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow5() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
 function isPlainObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -1017,22 +1080,22 @@ function isPlainObject(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
-function warnMissingBridge2(methodName) {
-  if (isDevelopment4()) {
+function warnMissingBridge3(methodName) {
+  if (isDevelopment5()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
   }
 }
 function loadGameState() {
-  const bridge = getBridgeWindow4();
+  const bridge = getBridgeWindow5();
   if (typeof bridge?.loadGameState !== "function") {
-    warnMissingBridge2("loadGameState");
+    warnMissingBridge3("loadGameState");
     return {};
   }
   const state = bridge.loadGameState();
   if (!isPlainObject(state)) {
-    if (isDevelopment4()) {
+    if (isDevelopment5()) {
       console.warn(
         "[oasiz/sdk] loadGameState returned invalid data. Falling back to empty object."
       );
@@ -1043,35 +1106,35 @@ function loadGameState() {
 }
 function saveGameState(state) {
   if (!isPlainObject(state)) {
-    if (isDevelopment4()) {
+    if (isDevelopment5()) {
       console.warn("[oasiz/sdk] saveGameState expected a plain object:", state);
     }
     return;
   }
-  const bridge = getBridgeWindow4();
+  const bridge = getBridgeWindow5();
   if (typeof bridge?.saveGameState === "function") {
     bridge.saveGameState(state);
     return;
   }
-  warnMissingBridge2("saveGameState");
+  warnMissingBridge3("saveGameState");
 }
 function flushGameState() {
-  const bridge = getBridgeWindow4();
+  const bridge = getBridgeWindow5();
   if (typeof bridge?.flushGameState === "function") {
     bridge.flushGameState();
     return;
   }
-  warnMissingBridge2("flushGameState");
+  warnMissingBridge3("flushGameState");
 }
 
 // src/lifecycle.ts
-function isDevelopment5() {
+function isDevelopment6() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
 function addLifecycleListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment5()) {
+    if (isDevelopment6()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1091,46 +1154,74 @@ function onResume(callback) {
 }
 
 // src/layout.ts
-function isDevelopment6() {
+function isDevelopment7() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow5() {
+function getBridgeWindow6() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
-function warnMissingBridge3(methodName) {
-  if (isDevelopment6()) {
+function warnMissingBridge4(methodName) {
+  if (isDevelopment7()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
   }
 }
-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 = getBridgeWindow5();
+  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);
   }
-  warnMissingBridge3("getSafeAreaTop");
+  warnMissingBridge4("getSafeAreaTop");
   return 0;
 }
 function setLeaderboardVisible(visible) {
   if (typeof visible !== "boolean") {
-    if (isDevelopment6()) {
+    if (isDevelopment7()) {
       console.warn(
         "[oasiz/sdk] setLeaderboardVisible expected a boolean:",
         visible
@@ -1138,28 +1229,28 @@ function setLeaderboardVisible(visible) {
     }
     return;
   }
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow6();
   if (typeof bridge?.__oasizSetLeaderboardVisible === "function") {
     bridge.__oasizSetLeaderboardVisible(visible);
     return;
   }
-  warnMissingBridge3("__oasizSetLeaderboardVisible");
+  warnMissingBridge4("__oasizSetLeaderboardVisible");
 }
 
 // src/navigation.ts
 var activeBackListeners = 0;
-function isDevelopment7() {
+function isDevelopment8() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
 }
-function getBridgeWindow6() {
+function getBridgeWindow7() {
   if (typeof window === "undefined") {
     return void 0;
   }
   return window;
 }
-function warnMissingBridge4(methodName) {
-  if (isDevelopment7()) {
+function warnMissingBridge5(methodName) {
+  if (isDevelopment8()) {
     console.warn(
       "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
     );
@@ -1175,7 +1266,7 @@ function normalizeNavigationError(error) {
 }
 function addNavigationListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment7()) {
+    if (isDevelopment8()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1196,24 +1287,24 @@ function onBackButton(callback) {
       throw normalizeNavigationError(error);
     }
   });
-  const bridge = getBridgeWindow6();
+  const bridge = getBridgeWindow7();
   activeBackListeners += 1;
   if (activeBackListeners === 1) {
     if (typeof bridge?.__oasizSetBackOverride === "function") {
       bridge.__oasizSetBackOverride(true);
     } else {
-      warnMissingBridge4("__oasizSetBackOverride");
+      warnMissingBridge5("__oasizSetBackOverride");
     }
   }
   return () => {
     off();
     activeBackListeners = Math.max(0, activeBackListeners - 1);
     if (activeBackListeners === 0) {
-      const currentBridge = getBridgeWindow6();
+      const currentBridge = getBridgeWindow7();
       if (typeof currentBridge?.__oasizSetBackOverride === "function") {
         currentBridge.__oasizSetBackOverride(false);
       } else {
-        warnMissingBridge4("__oasizSetBackOverride");
+        warnMissingBridge5("__oasizSetBackOverride");
       }
     }
   };
@@ -1222,17 +1313,18 @@ function onLeaveGame(callback) {
   return addNavigationListener("oasiz:leave", callback);
 }
 function leaveGame() {
-  const bridge = getBridgeWindow6();
+  const bridge = getBridgeWindow7();
   if (typeof bridge?.__oasizLeaveGame === "function") {
     bridge.__oasizLeaveGame();
     return;
   }
-  warnMissingBridge4("__oasizLeaveGame");
+  warnMissingBridge5("__oasizLeaveGame");
 }
 
 // src/index.ts
 var oasiz = {
   submitScore,
+  share,
   triggerHaptic,
   enableLogOverlay,
   loadGameState,
@@ -1281,6 +1373,7 @@ export {
   openInviteModal,
   saveGameState,
   setLeaderboardVisible,
+  share,
   shareRoomCode,
   submitScore,
   triggerHaptic

package/package.json

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