@oasiz/sdk 1.5.0 → 1.5.2

package/README.md

@@ -298,7 +298,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 +386,7 @@ All methods are also available as named exports if you prefer not to use the `oa
 ```ts
 import {
   submitScore,
+  share,
   triggerHaptic,
   loadGameState,
   saveGameState,
@@ -402,8 +414,11 @@ import {
 import type {
   GameState,
   HapticType,
+  LogOverlayEntry,
   LogOverlayHandle,
+  LogOverlayLevel,
   LogOverlayOptions,
+  ShareRequest,
   ShareRoomCodeOptions,
   Unsubscribe,
 } from "@oasiz/sdk";
@@ -421,6 +436,59 @@ C# API and **WebGL-only** `OasizBridge.jslib` live in this repository at **`pack
 2. Ensure the **WebGL** platform is selected for release builds; the `.jslib` under `Runtime/Plugins/WebGL/` is included automatically for WebGL.
 3. Add an **`OasizSDK`** component to a persistent GameObject early (for example a bootstrap scene), **or** rely on `OasizSDK.Instance` which creates a `DontDestroyOnLoad` object. The component registers listeners for `oasiz:pause`, `oasiz:resume`, `oasiz:back`, and `oasiz:leave` via `SendMessage`.
 
+### Quick start
+
+```csharp
+using Oasiz;
+using UnityEngine;
+
+public class GameManager : MonoBehaviour
+{
+    void Start()
+    {
+        // Ensure the singleton is initialized early
+        _ = OasizSDK.Instance;
+
+        // Subscribe to lifecycle events
+        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");
+
+        // Emit score normalization anchors
+        OasizSDK.EmitScoreConfig(new ScoreConfig(
+            new ScoreAnchor(10, 100),
+            new ScoreAnchor(30, 300),
+            new ScoreAnchor(75, 600),
+            new ScoreAnchor(200, 950)
+        ));
+    }
+
+    void OnGameOver(int finalScore)
+    {
+        OasizSDK.SubmitScore(finalScore);
+        OasizSDK.FlushGameState();
+        OasizSDK.SetLeaderboardVisible(true);
+    }
+
+    void OnGameplayStart()
+    {
+        OasizSDK.SetLeaderboardVisible(false);
+    }
+
+    void OnPause() => Time.timeScale = 0f;
+    void OnResume() => Time.timeScale = 1f;
+
+    void OnDestroy()
+    {
+        OasizSDK.OnPause -= OnPause;
+        OasizSDK.OnResume -= OnResume;
+    }
+}
+```
+
 ### API parity (TypeScript → C#)
 
 | HTML5 (`@oasiz/sdk`) | Unity (`Oasiz` namespace) |
@@ -436,23 +504,95 @@ C# API and **WebGL-only** `OasizBridge.jslib` live in this repository at **`pack
 | `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` |
-| — | `OasizSDK.EmitScoreConfig(ScoreConfig)` → `window.emitScoreConfig` (Unity-only helper for normalized score UI) |
+| `oasiz.gameId` / `roomCode` / ... | `OasizSDK.GameId` / `RoomCode` / `PlayerName` / `PlayerAvatar` |
+| -- | `OasizSDK.EmitScoreConfig(ScoreConfig)` → `window.emitScoreConfig` (Unity-only helper for normalized score UI) |
 | `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
+// Haptic feedback intensity
+public enum HapticType { Light, Medium, Heavy, Success, Error }
+
+// Score normalization (exactly 4 anchors required)
+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; } }
+
+// Log overlay configuration
+public class LogOverlayOptions
+{
+    public bool Enabled { get; set; } = true;
+    public bool Collapsed { get; set; } = false;
+    public int MaxEntries { get; set; } = 200;
+    public string Title { get; set; } = "SDK Logs";
+}
+
+// Log overlay lifecycle handle
+public class LogOverlayHandle
+{
+    public void Clear();
+    public void Hide();
+    public void Show();
+    public bool IsVisible();
+    public void Destroy();
+}
+```
 
 ### Back button and errors
 
 Matching the HTML5 SDK: if any **`OnBackButton`** handler throws, **`OasizSDK.LeaveGame()`** is invoked and the **original exception is rethrown** (`throw;` preserves the stack trace). Use **`SubscribeBackButton`** when you want an unsubscribe delegate; you can also use `OnBackButton +=` / `-=` directly.
 
+```csharp
+// Subscribe with automatic unsubscribe support
+var offBack = OasizSDK.SubscribeBackButton(() =>
+{
+    if (isPaused)
+        Resume();
+    else
+        Pause();
+});
+
+// Unsubscribe when no longer needed
+offBack();
+```
+
 ### Editor vs WebGL builds
 
 In the **Unity Editor**, bridge calls are mostly **logged** and return safe defaults (for example safe area `0`, `null` platform IDs). Real host integration applies to **WebGL player** builds running inside Oasiz.
 
 ### Log overlay (Unity)
 
-The C# API for the log overlay exists for API compatibility, but the **default `OasizBridge.jslib` in this repo does not inject DOM UI** — `EnableLogOverlay` / `AppendLogOverlay` are no-ops at the JavaScript layer. Use Unity’s console and device logs for debugging unless you replace or extend the `.jslib` on your side.
+The C# API for the log overlay exists for API compatibility, but the **default `OasizBridge.jslib` in this repo does not inject DOM UI** — `EnableLogOverlay` / `AppendLogOverlay` are no-ops at the JavaScript layer. Use Unity's console and device logs for debugging unless you replace or extend the `.jslib` on your side.
+
+`AppendLogOverlay(level, message, stackTrace)` lets you pipe `Debug.Log` output into the overlay manually, since many embedded WebViews do not route Unity player logs through `console.log`. Valid levels: `"debug"`, `"log"`, `"info"`, `"warn"`, `"error"`.
 
 ---
 

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,18 +1200,18 @@ 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."
     );
@@ -1160,7 +1224,7 @@ function normalizeSafeAreaTop(value) {
   return Math.max(0, value);
 }
 function getSafeAreaTop() {
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow6();
   if (!bridge) {
     return 0;
   }
@@ -1170,12 +1234,12 @@ function getSafeAreaTop() {
   if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
     return normalizeSafeAreaTop(bridge.__OASIZ_SAFE_AREA_TOP__);
   }
-  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 +1247,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 +1284,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 +1305,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 +1331,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 +1392,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;
@@ -64,6 +71,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 +93,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;
@@ -64,6 +71,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 +93,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,18 +1154,18 @@ 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."
     );
@@ -1115,7 +1178,7 @@ function normalizeSafeAreaTop(value) {
   return Math.max(0, value);
 }
 function getSafeAreaTop() {
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow6();
   if (!bridge) {
     return 0;
   }
@@ -1125,12 +1188,12 @@ function getSafeAreaTop() {
   if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
     return normalizeSafeAreaTop(bridge.__OASIZ_SAFE_AREA_TOP__);
   }
-  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 +1201,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 +1238,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 +1259,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 +1285,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 +1345,7 @@ export {
   openInviteModal,
   saveGameState,
   setLeaderboardVisible,
+  share,
   shareRoomCode,
   submitScore,
   triggerHaptic

package/package.json

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