@oasiz/sdk 1.3.0 → 1.5.0

package/README.md

@@ -1,53 +1,63 @@
-# @oasiz/sdk
+# Oasiz game SDKs
 
-Typed SDK for integrating games with the Oasiz platform. Handles score submission, haptic feedback, cross-session state persistence, multiplayer room codes, navigation hooks, and app lifecycle events for local development.
+Games on Oasiz can integrate using either of these official SDKs:
 
-## Install
+| Platform | Package | Use for |
+| --- | --- | --- |
+| **HTML5 / TypeScript** | [`@oasiz/sdk`](#html5--typescript-oasizsdk) (npm) | Canvas, Phaser, custom JS/TS, any browser game |
+| **Unity WebGL** | [Unity runtime](#unity-webgl-sdk) in this repo (`packages/OasizSDK/`) | Unity projects targeting WebGL |
+
+Both talk to the same host bridges (`window.submitScore`, `__oasizLeaveGame`, layout APIs, custom DOM events such as `oasiz:pause`, etc.). Unsupported hosts no-op safely; local dev usually logs warnings instead of crashing.
+
+---
+
+## HTML5 / TypeScript (`@oasiz/sdk`)
+
+Typed SDK for integrating browser games with the Oasiz platform: score, haptics, cross-session state, multiplayer hooks, layout (safe area, leaderboard visibility), navigation (back / leave), and lifecycle events.
+
+### Install
 
 ```bash
-npm install @oasiz/sdk@^0.1.0
+npm install @oasiz/sdk
 ```
 
-## Quick start
+### Quick start
 
 ```ts
 import { oasiz } from "@oasiz/sdk";
 
-// 1. Emit score normalization config once on init
-oasiz.emitScoreConfig({
-  anchors: [
-    { raw: 30, normalized: 100 },
-    { raw: 60, normalized: 300 },
-    { raw: 120, normalized: 600 },
-    { raw: 300, normalized: 950 },
-  ],
-});
-
-// 2. Load persisted state at the start of each session
+// 1. Load persisted state at the start of each session
 const state = oasiz.loadGameState();
 let level = typeof state.level === "number" ? state.level : 1;
 
-// 3. Save state at checkpoints
+// 2. Save state at checkpoints
 oasiz.saveGameState({ level, coins: 42 });
 
-// 4. Trigger haptics on key events
+// 3. Trigger haptics on key events
 oasiz.triggerHaptic("medium");
 
+// 4. Respect the host's top safe area
+document.documentElement.style.setProperty(
+  "--safe-top",
+  `${oasiz.safeAreaTop}px`,
+);
+
 // 5. Submit score when the game ends
 oasiz.submitScore(score);
 
-// 6. Optionally surface console logs in-game while debugging
+// 6. Optionally hide the leaderboard while a custom overlay is open
+oasiz.setLeaderboardVisible(false);
+
+// 7. Optionally surface console logs in-game while debugging
 oasiz.enableLogOverlay({
   enabled: new URLSearchParams(window.location.search).has("oasizLogs"),
   collapsed: true,
 });
 ```
 
----
+### Score
 
-## Score
-
-### `oasiz.submitScore(score: number)`
+#### `oasiz.submitScore(score: number)`
 
 Submit the player's final score at game over. Call this exactly once per session, when the game ends. The platform handles leaderboard persistence — do not track high scores locally.
 
@@ -60,39 +70,9 @@ private onGameOver(): void {
 - `score` must be a non-negative integer. Floats are floored automatically.
 - Do not call on intermediate scores or level completions, only on final game over.
 
----
-
-### `oasiz.emitScoreConfig(config)`
-
-Maps raw score values to the platform's normalized 0–1000 scale. Call once during initialization, not every frame.
-
-```ts
-oasiz.emitScoreConfig({
-  anchors: [
-    { raw: 10,  normalized: 100 }, // beginner
-    { raw: 30,  normalized: 300 }, // good
-    { raw: 75,  normalized: 600 }, // great
-    { raw: 200, normalized: 950 }, // godlike
-  ],
-});
-```
+### Haptics
 
-**Anchor rules:**
-- Exactly 4 anchors required.
-- `raw` values must be strictly increasing.
-- `normalized` values must end at exactly `950`.
-- Choose thresholds based on realistic player skill bands.
-
-**Practical guidance by game type:**
-- Survival / time games → use seconds survived as `raw`
-- Score accumulation games → use points as `raw`
-- Puzzle games → use level reached or stars earned as `raw`
-
----
-
-## Haptics
-
-### `oasiz.triggerHaptic(type: HapticType)`
+#### `oasiz.triggerHaptic(type: HapticType)`
 
 Trigger native haptic feedback. Always guard with the user's haptics setting.
 
@@ -101,7 +81,7 @@ type HapticType = "light" | "medium" | "heavy" | "success" | "error";
 ```
 
 | Type | When to use |
-|---|---|
+| --- | --- |
 | `"light"` | UI button taps, menu navigation, D-pad press |
 | `"medium"` | Collecting items, standard collisions, scoring |
 | `"heavy"` | Explosions, major impacts, screen shake |
@@ -132,11 +112,9 @@ private onGameOver(): void {
 
 Haptics are throttled internally (50ms cooldown) to prevent spam.
 
----
-
-## Debugging
+### Debugging
 
-### `oasiz.enableLogOverlay(options?: LogOverlayOptions)`
+#### `oasiz.enableLogOverlay(options?: LogOverlayOptions)`
 
 Mount an opt-in in-game console viewer for local debugging, QA sessions, or creator support. It mirrors `console.log`, `console.info`, `console.warn`, `console.error`, and `console.debug` into a floating overlay inside the game iframe. The overlay can be collapsed, repositioned by dragging the top bar, and resized from the bottom-right corner while the action buttons remain clickable.
 
@@ -153,6 +131,7 @@ logOverlay.destroy();
 ```
 
 Options:
+
 - `enabled`: defaults to `true`. Pass your own flag or query-param check here.
 - `collapsed`: start with only the toggle pill visible.
 - `maxEntries`: cap retained log lines. Defaults to `200`.
@@ -160,20 +139,18 @@ Options:
 
 The returned handle supports `show()`, `hide()`, `clear()`, `isVisible()`, and `destroy()`.
 
----
-
-## Game state persistence
+### Game state persistence
 
 Persist cross-session data such as unlocked levels, inventory, or lifetime stats. State is stored per-user per-game in the Oasiz backend — available across devices and app reinstalls.
 
-### `oasiz.loadGameState(): Record<string, unknown>`
+#### `oasiz.loadGameState(): Record<string, unknown>`
 
 Returns the player's saved state synchronously. Returns `{}` if no state has been saved yet. Call once at the start of the game.
 
 ```ts
 private initFromSavedState(): void {
   const state = oasiz.loadGameState();
-  this.level        = typeof state.level === "number" ? state.level : 1;
+  this.level = typeof state.level === "number" ? state.level : 1;
   this.lifetimeHits = typeof state.lifetimeHits === "number" ? state.lifetimeHits : 0;
   this.unlockedSkins = Array.isArray(state.unlockedSkins) ? state.unlockedSkins : [];
 }
@@ -181,7 +158,7 @@ private initFromSavedState(): void {
 
 Always validate the shape of loaded data — it may be `{}` on first play.
 
-### `oasiz.saveGameState(state: Record<string, unknown>)`
+#### `oasiz.saveGameState(state: Record<string, unknown>)`
 
 Queues a debounced save. Saves are batched automatically — call freely at checkpoints without worrying about request spam.
 
@@ -198,11 +175,12 @@ private onLevelComplete(): void {
 ```
 
 **Rules:**
+
 - State must be a plain JSON object (not an array or primitive).
 - Do not use `localStorage` for cross-session progress — use `saveGameState` so data syncs across platforms.
 - Do not store scores here — scores are submitted via `submitScore`.
 
-### `oasiz.flushGameState()`
+#### `oasiz.flushGameState()`
 
 Forces an immediate write, bypassing the debounce. Use at important checkpoints like game over or before the page unloads.
 
@@ -214,19 +192,63 @@ 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.
+
+#### `oasiz.getSafeAreaTop(): number`
+
+Returns the current top inset. The host may expose `window.getSafeAreaTop()` or `window.__OASIZ_SAFE_AREA_TOP__`. Unsupported hosts return `0`.
+
+```ts
+const safeTop = oasiz.getSafeAreaTop();
+document.documentElement.style.setProperty("--safe-top", `${safeTop}px`);
+```
+
+#### `oasiz.safeAreaTop`
+
+Getter alias for `getSafeAreaTop()`.
+
+Recommended CSS pattern:
+
+```css
+:root {
+  --safe-top: 0px;
+}
+
+#top-bar {
+  padding-top: var(--safe-top);
+}
+```
+
+#### `oasiz.setLeaderboardVisible(visible: boolean): void`
+
+Show or hide the host leaderboard UI from inside the game. This only affects the leaderboard; back and social controls remain visible. Calls `window.__oasizSetLeaderboardVisible` when present.
 
-## Lifecycle
+```ts
+function openCustomOverlay(): void {
+  oasiz.setLeaderboardVisible(false);
+}
+
+function closeCustomOverlay(): void {
+  oasiz.setLeaderboardVisible(true);
+}
+```
+
+Unsupported hosts safely no-op.
+
+### Lifecycle
 
 The platform dispatches lifecycle events when the app goes to the background or returns to the foreground. Subscribe to pause game loops and audio accordingly.
 
-### `oasiz.onPause(callback: () => void): Unsubscribe`
-### `oasiz.onResume(callback: () => void): Unsubscribe`
+#### `oasiz.onPause(callback: () => void): Unsubscribe`
+
+#### `oasiz.onResume(callback: () => void): Unsubscribe`
 
 Both return an unsubscribe function.
 
 ```ts
-const offPause  = oasiz.onPause(() => {
+const offPause = oasiz.onPause(() => {
   this.gameLoop.stop();
   this.bgMusic.pause();
 });
@@ -241,18 +263,18 @@ offPause();
 offResume();
 ```
 
----
-
-## Navigation
+### Navigation
 
 Use navigation hooks when your game needs to control back behavior (Android back / web Escape) or participate in host-driven close events.
 
-### `oasiz.onBackButton(callback: () => void): Unsubscribe`
+#### `oasiz.onBackButton(callback: () => void): Unsubscribe`
 
 Registers a callback for platform back actions. While at least one back listener is subscribed, back actions are routed to your game instead of immediately closing it.
 
 Use this for pause menus, in-game overlays, or custom back-stack behavior.
 
+**If your callback throws**, the SDK calls `leaveGame()` (host close) and **rethrows** the error so you still see it in devtools or error reporting. Non-`Error` throws are normalized to an `Error` (strings become the message; otherwise `"Back button callback failed."`).
+
 ```ts
 const offBack = oasiz.onBackButton(() => {
   if (this.isPauseMenuOpen) {
@@ -266,7 +288,7 @@ const offBack = oasiz.onBackButton(() => {
 offBack();
 ```
 
-### `oasiz.leaveGame(): void`
+#### `oasiz.leaveGame(): void`
 
 Programmatically request the host to close the current game (for example, from a Quit button inside your game UI).
 
@@ -276,7 +298,7 @@ quitButton.addEventListener("click", () => {
 });
 ```
 
-### `oasiz.onLeaveGame(callback: () => void): Unsubscribe`
+#### `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.
 
@@ -290,11 +312,9 @@ const offLeave = oasiz.onLeaveGame(() => {
 offLeave();
 ```
 
----
-
-## Multiplayer
+### Multiplayer
 
-### `oasiz.shareRoomCode(code: string | null, options?: { inviteOverride?: boolean })`
+#### `oasiz.shareRoomCode(code: string | null, options?: { inviteOverride?: boolean })`
 
 Notify the platform of the active multiplayer room so friends can join via the invite system. Pass `null` when leaving a room.
 
@@ -316,7 +336,9 @@ oasiz.shareRoomCode(null);
 oasiz.shareRoomCode(getRoomCode(), { inviteOverride: true });
 ```
 
-If you still want to use the platform invite sheet from your own in-game button, combine it with `openInviteModal()`:
+#### `oasiz.openInviteModal(): void`
+
+Opens the platform invite-friends UI when the bridge is available. Typically used together with `shareRoomCode` (for example, your own invite button calls this).
 
 ```ts
 import { openInviteModal, shareRoomCode } from "@oasiz/sdk";
@@ -328,7 +350,7 @@ inviteButton.addEventListener("click", () => {
 });
 ```
 
-### Read-only injected values
+#### Read-only injected values
 
 These are populated by the platform before the game loads. Always check for `undefined` before using.
 
@@ -342,26 +364,26 @@ if (oasiz.roomCode) {
 }
 
 // Player identity for multiplayer games
-const name   = oasiz.playerName;
+const name = oasiz.playerName;
 const avatar = oasiz.playerAvatar;
 ```
 
----
-
-## Named exports
+### Named exports
 
 All methods are also available as named exports if you prefer not to use the `oasiz` namespace object:
 
 ```ts
 import {
   submitScore,
-  emitScoreConfig,
   triggerHaptic,
   loadGameState,
   saveGameState,
   flushGameState,
   shareRoomCode,
+  openInviteModal,
   enableLogOverlay,
+  getSafeAreaTop,
+  setLeaderboardVisible,
   onPause,
   onResume,
   onBackButton,
@@ -374,9 +396,7 @@ import {
 } from "@oasiz/sdk";
 ```
 
----
-
-## TypeScript types
+### TypeScript types
 
 ```ts
 import type {
@@ -384,15 +404,62 @@ import type {
   HapticType,
   LogOverlayHandle,
   LogOverlayOptions,
-  ScoreAnchor,
-  ScoreConfig,
+  ShareRoomCodeOptions,
+  Unsubscribe,
 } from "@oasiz/sdk";
 ```
 
 ---
 
+## Unity WebGL SDK
+
+C# API and **WebGL-only** `OasizBridge.jslib` live in this repository at **`packages/OasizSDK/`**. Copy the **`OasizSDK`** folder into your Unity project under **`Assets/`** (for example `Assets/OasizSDK`).
+
+### Setup
+
+1. Copy `packages/OasizSDK` from this repo into `Assets/OasizSDK`.
+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`.
+
+### API parity (TypeScript → C#)
+
+| HTML5 (`@oasiz/sdk`) | Unity (`Oasiz` namespace) |
+| --- | --- |
+| `oasiz.submitScore(n)` | `OasizSDK.SubmitScore(int)` |
+| `oasiz.triggerHaptic(type)` | `OasizSDK.TriggerHaptic(HapticType)` |
+| `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.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.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.enableLogOverlay` | `OasizSDK.EnableLogOverlay(LogOverlayOptions)` (see note below) |
+
+### 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.
+
+### 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.
+
+---
+
 ## Local development
 
+### HTML5 / TypeScript
+
 All methods safely no-op when the platform bridges are not injected. In development mode a console warning is logged so you know the call was made:
 
 ```
@@ -400,3 +467,7 @@ All methods safely no-op when the platform bridges are not injected. In developm
 ```
 
 No crashes, no special setup required for local dev.
+
+### Unity WebGL
+
+The `.jslib` logs warnings when `window.*` bridges are missing (for example `submitScore`, `__oasizLeaveGame`). The Editor path avoids calling native plugins and prints `Debug.Log` for most operations instead.

package/dist/index.cjs

@@ -20,13 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  emitScoreConfig: () => emitScoreConfig,
   enableLogOverlay: () => enableLogOverlay,
   flushGameState: () => flushGameState,
   getGameId: () => getGameId,
   getPlayerAvatar: () => getPlayerAvatar,
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
+  getSafeAreaTop: () => getSafeAreaTop,
   leaveGame: () => leaveGame,
   loadGameState: () => loadGameState,
   oasiz: () => oasiz,
@@ -36,6 +36,7 @@ __export(index_exports, {
   onResume: () => onResume,
   openInviteModal: () => openInviteModal,
   saveGameState: () => saveGameState,
+  setLeaderboardVisible: () => setLeaderboardVisible,
   shareRoomCode: () => shareRoomCode,
   submitScore: () => submitScore,
   triggerHaptic: () => triggerHaptic
@@ -1042,14 +1043,6 @@ function submitScore(score) {
   }
   warnMissingBridge("submitScore");
 }
-function emitScoreConfig(config) {
-  const bridge = getBridgeWindow3();
-  if (typeof bridge?.emitScoreConfig === "function") {
-    bridge.emitScoreConfig(config);
-    return;
-  }
-  warnMissingBridge("emitScoreConfig");
-}
 
 // src/state.ts
 function isDevelopment4() {
@@ -1142,8 +1135,7 @@ function onResume(callback) {
   return addLifecycleListener("oasiz:resume", callback);
 }
 
-// src/navigation.ts
-var activeBackListeners = 0;
+// src/layout.ts
 function isDevelopment6() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1161,9 +1153,74 @@ function warnMissingBridge3(methodName) {
     );
   }
 }
+function normalizeSafeAreaTop(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, value);
+}
+function getSafeAreaTop() {
+  const bridge = getBridgeWindow5();
+  if (!bridge) {
+    return 0;
+  }
+  if (typeof bridge.getSafeAreaTop === "function") {
+    return normalizeSafeAreaTop(bridge.getSafeAreaTop());
+  }
+  if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
+    return normalizeSafeAreaTop(bridge.__OASIZ_SAFE_AREA_TOP__);
+  }
+  warnMissingBridge3("getSafeAreaTop");
+  return 0;
+}
+function setLeaderboardVisible(visible) {
+  if (typeof visible !== "boolean") {
+    if (isDevelopment6()) {
+      console.warn(
+        "[oasiz/sdk] setLeaderboardVisible expected a boolean:",
+        visible
+      );
+    }
+    return;
+  }
+  const bridge = getBridgeWindow5();
+  if (typeof bridge?.__oasizSetLeaderboardVisible === "function") {
+    bridge.__oasizSetLeaderboardVisible(visible);
+    return;
+  }
+  warnMissingBridge3("__oasizSetLeaderboardVisible");
+}
+
+// src/navigation.ts
+var activeBackListeners = 0;
+function isDevelopment7() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow6() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function warnMissingBridge4(methodName) {
+  if (isDevelopment7()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+function normalizeNavigationError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(
+    typeof error === "string" ? error : "Back button callback failed."
+  );
+}
 function addNavigationListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment6()) {
+    if (isDevelopment7()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1176,25 +1233,32 @@ function addNavigationListener(eventName, callback) {
   return () => window.removeEventListener(eventName, handler);
 }
 function onBackButton(callback) {
-  const off = addNavigationListener("oasiz:back", callback);
-  const bridge = getBridgeWindow5();
+  const off = addNavigationListener("oasiz:back", () => {
+    try {
+      callback();
+    } catch (error) {
+      leaveGame();
+      throw normalizeNavigationError(error);
+    }
+  });
+  const bridge = getBridgeWindow6();
   activeBackListeners += 1;
   if (activeBackListeners === 1) {
     if (typeof bridge?.__oasizSetBackOverride === "function") {
       bridge.__oasizSetBackOverride(true);
     } else {
-      warnMissingBridge3("__oasizSetBackOverride");
+      warnMissingBridge4("__oasizSetBackOverride");
     }
   }
   return () => {
     off();
     activeBackListeners = Math.max(0, activeBackListeners - 1);
     if (activeBackListeners === 0) {
-      const currentBridge = getBridgeWindow5();
+      const currentBridge = getBridgeWindow6();
       if (typeof currentBridge?.__oasizSetBackOverride === "function") {
         currentBridge.__oasizSetBackOverride(false);
       } else {
-        warnMissingBridge3("__oasizSetBackOverride");
+        warnMissingBridge4("__oasizSetBackOverride");
       }
     }
   };
@@ -1203,18 +1267,17 @@ function onLeaveGame(callback) {
   return addNavigationListener("oasiz:leave", callback);
 }
 function leaveGame() {
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow6();
   if (typeof bridge?.__oasizLeaveGame === "function") {
     bridge.__oasizLeaveGame();
     return;
   }
-  warnMissingBridge3("__oasizLeaveGame");
+  warnMissingBridge4("__oasizLeaveGame");
 }
 
 // src/index.ts
 var oasiz = {
   submitScore,
-  emitScoreConfig,
   triggerHaptic,
   enableLogOverlay,
   loadGameState,
@@ -1224,6 +1287,8 @@ var oasiz = {
   openInviteModal,
   onPause,
   onResume,
+  getSafeAreaTop,
+  setLeaderboardVisible,
   onBackButton,
   onLeaveGame,
   leaveGame,
@@ -1238,17 +1303,20 @@ var oasiz = {
   },
   get playerAvatar() {
     return getPlayerAvatar();
+  },
+  get safeAreaTop() {
+    return getSafeAreaTop();
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  emitScoreConfig,
   enableLogOverlay,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
+  getSafeAreaTop,
   leaveGame,
   loadGameState,
   oasiz,
@@ -1258,6 +1326,7 @@ var oasiz = {
   onResume,
   openInviteModal,
   saveGameState,
+  setLeaderboardVisible,
   shareRoomCode,
   submitScore,
   triggerHaptic

package/dist/index.d.cts

@@ -19,13 +19,6 @@ interface LogOverlayHandle {
     isVisible: () => boolean;
     show: () => void;
 }
-interface ScoreAnchor {
-    raw: number;
-    normalized: 100 | 300 | 600 | 950;
-}
-interface ScoreConfig {
-    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
-}
 type GameState = Record<string, unknown>;
 
 declare function triggerHaptic(type: HapticType): void;
@@ -53,7 +46,6 @@ declare function getPlayerName(): string | undefined;
 declare function getPlayerAvatar(): string | undefined;
 
 declare function submitScore(score: number): void;
-declare function emitScoreConfig(config: ScoreConfig): void;
 
 declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
@@ -63,13 +55,15 @@ type Unsubscribe = () => void;
 declare function onPause(callback: () => void): Unsubscribe;
 declare function onResume(callback: () => void): Unsubscribe;
 
+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;
 
 declare const oasiz: {
     submitScore: typeof submitScore;
-    emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
     loadGameState: typeof loadGameState;
@@ -79,6 +73,8 @@ declare const oasiz: {
     openInviteModal: typeof openInviteModal;
     onPause: typeof onPause;
     onResume: typeof onResume;
+    getSafeAreaTop: typeof getSafeAreaTop;
+    setLeaderboardVisible: typeof setLeaderboardVisible;
     onBackButton: typeof onBackButton;
     onLeaveGame: typeof onLeaveGame;
     leaveGame: typeof leaveGame;
@@ -86,6 +82,7 @@ declare const oasiz: {
     readonly roomCode: string | undefined;
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
+    readonly safeAreaTop: number;
 };
 
-export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ScoreAnchor, type ScoreConfig, type ShareRoomCodeOptions, type Unsubscribe, emitScoreConfig, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, shareRoomCode, submitScore, triggerHaptic };
+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 };

package/dist/index.d.ts

@@ -19,13 +19,6 @@ interface LogOverlayHandle {
     isVisible: () => boolean;
     show: () => void;
 }
-interface ScoreAnchor {
-    raw: number;
-    normalized: 100 | 300 | 600 | 950;
-}
-interface ScoreConfig {
-    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
-}
 type GameState = Record<string, unknown>;
 
 declare function triggerHaptic(type: HapticType): void;
@@ -53,7 +46,6 @@ declare function getPlayerName(): string | undefined;
 declare function getPlayerAvatar(): string | undefined;
 
 declare function submitScore(score: number): void;
-declare function emitScoreConfig(config: ScoreConfig): void;
 
 declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
@@ -63,13 +55,15 @@ type Unsubscribe = () => void;
 declare function onPause(callback: () => void): Unsubscribe;
 declare function onResume(callback: () => void): Unsubscribe;
 
+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;
 
 declare const oasiz: {
     submitScore: typeof submitScore;
-    emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
     loadGameState: typeof loadGameState;
@@ -79,6 +73,8 @@ declare const oasiz: {
     openInviteModal: typeof openInviteModal;
     onPause: typeof onPause;
     onResume: typeof onResume;
+    getSafeAreaTop: typeof getSafeAreaTop;
+    setLeaderboardVisible: typeof setLeaderboardVisible;
     onBackButton: typeof onBackButton;
     onLeaveGame: typeof onLeaveGame;
     leaveGame: typeof leaveGame;
@@ -86,6 +82,7 @@ declare const oasiz: {
     readonly roomCode: string | undefined;
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
+    readonly safeAreaTop: number;
 };
 
-export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ScoreAnchor, type ScoreConfig, type ShareRoomCodeOptions, type Unsubscribe, emitScoreConfig, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, shareRoomCode, submitScore, triggerHaptic };
+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 };

package/dist/index.js

@@ -998,14 +998,6 @@ function submitScore(score) {
   }
   warnMissingBridge("submitScore");
 }
-function emitScoreConfig(config) {
-  const bridge = getBridgeWindow3();
-  if (typeof bridge?.emitScoreConfig === "function") {
-    bridge.emitScoreConfig(config);
-    return;
-  }
-  warnMissingBridge("emitScoreConfig");
-}
 
 // src/state.ts
 function isDevelopment4() {
@@ -1098,8 +1090,7 @@ function onResume(callback) {
   return addLifecycleListener("oasiz:resume", callback);
 }
 
-// src/navigation.ts
-var activeBackListeners = 0;
+// src/layout.ts
 function isDevelopment6() {
   const nodeEnv = globalThis.process?.env?.NODE_ENV;
   return nodeEnv !== "production";
@@ -1117,9 +1108,74 @@ function warnMissingBridge3(methodName) {
     );
   }
 }
+function normalizeSafeAreaTop(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, value);
+}
+function getSafeAreaTop() {
+  const bridge = getBridgeWindow5();
+  if (!bridge) {
+    return 0;
+  }
+  if (typeof bridge.getSafeAreaTop === "function") {
+    return normalizeSafeAreaTop(bridge.getSafeAreaTop());
+  }
+  if (typeof bridge.__OASIZ_SAFE_AREA_TOP__ !== "undefined") {
+    return normalizeSafeAreaTop(bridge.__OASIZ_SAFE_AREA_TOP__);
+  }
+  warnMissingBridge3("getSafeAreaTop");
+  return 0;
+}
+function setLeaderboardVisible(visible) {
+  if (typeof visible !== "boolean") {
+    if (isDevelopment6()) {
+      console.warn(
+        "[oasiz/sdk] setLeaderboardVisible expected a boolean:",
+        visible
+      );
+    }
+    return;
+  }
+  const bridge = getBridgeWindow5();
+  if (typeof bridge?.__oasizSetLeaderboardVisible === "function") {
+    bridge.__oasizSetLeaderboardVisible(visible);
+    return;
+  }
+  warnMissingBridge3("__oasizSetLeaderboardVisible");
+}
+
+// src/navigation.ts
+var activeBackListeners = 0;
+function isDevelopment7() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow6() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function warnMissingBridge4(methodName) {
+  if (isDevelopment7()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+function normalizeNavigationError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(
+    typeof error === "string" ? error : "Back button callback failed."
+  );
+}
 function addNavigationListener(eventName, callback) {
   if (typeof window === "undefined") {
-    if (isDevelopment6()) {
+    if (isDevelopment7()) {
       console.warn(
         "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
       );
@@ -1132,25 +1188,32 @@ function addNavigationListener(eventName, callback) {
   return () => window.removeEventListener(eventName, handler);
 }
 function onBackButton(callback) {
-  const off = addNavigationListener("oasiz:back", callback);
-  const bridge = getBridgeWindow5();
+  const off = addNavigationListener("oasiz:back", () => {
+    try {
+      callback();
+    } catch (error) {
+      leaveGame();
+      throw normalizeNavigationError(error);
+    }
+  });
+  const bridge = getBridgeWindow6();
   activeBackListeners += 1;
   if (activeBackListeners === 1) {
     if (typeof bridge?.__oasizSetBackOverride === "function") {
       bridge.__oasizSetBackOverride(true);
     } else {
-      warnMissingBridge3("__oasizSetBackOverride");
+      warnMissingBridge4("__oasizSetBackOverride");
     }
   }
   return () => {
     off();
     activeBackListeners = Math.max(0, activeBackListeners - 1);
     if (activeBackListeners === 0) {
-      const currentBridge = getBridgeWindow5();
+      const currentBridge = getBridgeWindow6();
       if (typeof currentBridge?.__oasizSetBackOverride === "function") {
         currentBridge.__oasizSetBackOverride(false);
       } else {
-        warnMissingBridge3("__oasizSetBackOverride");
+        warnMissingBridge4("__oasizSetBackOverride");
       }
     }
   };
@@ -1159,18 +1222,17 @@ function onLeaveGame(callback) {
   return addNavigationListener("oasiz:leave", callback);
 }
 function leaveGame() {
-  const bridge = getBridgeWindow5();
+  const bridge = getBridgeWindow6();
   if (typeof bridge?.__oasizLeaveGame === "function") {
     bridge.__oasizLeaveGame();
     return;
   }
-  warnMissingBridge3("__oasizLeaveGame");
+  warnMissingBridge4("__oasizLeaveGame");
 }
 
 // src/index.ts
 var oasiz = {
   submitScore,
-  emitScoreConfig,
   triggerHaptic,
   enableLogOverlay,
   loadGameState,
@@ -1180,6 +1242,8 @@ var oasiz = {
   openInviteModal,
   onPause,
   onResume,
+  getSafeAreaTop,
+  setLeaderboardVisible,
   onBackButton,
   onLeaveGame,
   leaveGame,
@@ -1194,16 +1258,19 @@ var oasiz = {
   },
   get playerAvatar() {
     return getPlayerAvatar();
+  },
+  get safeAreaTop() {
+    return getSafeAreaTop();
   }
 };
 export {
-  emitScoreConfig,
   enableLogOverlay,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
+  getSafeAreaTop,
   leaveGame,
   loadGameState,
   oasiz,
@@ -1213,6 +1280,7 @@ export {
   onResume,
   openInviteModal,
   saveGameState,
+  setLeaderboardVisible,
   shareRoomCode,
   submitScore,
   triggerHaptic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -19,19 +19,25 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
-    "prepack": "bun run build",
+    "prepack": "npm run build",
     "test": "node --experimental-strip-types --test ./tests/**/*.test.ts"
   },
   "publishConfig": {
     "access": "public"
   },
+  "tagFormat": "sdk-v${version}",
   "release": {
     "branches": [
       "main"
     ],
     "plugins": [
-      "@semantic-release/commit-analyzer",
-      "@semantic-release/release-notes-generator",
+      [
+        "../../scripts/semantic-release/workspace-release.mjs",
+        {
+          "packageName": "@oasiz/sdk",
+          "packagePath": "packages/sdk"
+        }
+      ],
       "@semantic-release/github",
       [
         "@semantic-release/exec",
@@ -48,5 +54,9 @@
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oasiz-ai/oasiz-tooling.git"
   }
 }