@oasiz/sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,11 +1,11 @@
 # @oasiz/sdk
 
-Typed SDK for integrating games with the Oasiz platform. Handles score submission, haptic feedback, cross-session state persistence, multiplayer room codes, and app lifecycle events for local development.
+Typed SDK for integrating games with the Oasiz platform. Handles score submission, haptic feedback, cross-session state persistence, multiplayer room codes, and app lifecycle events.
 
 ## Install
 
 ```bash
-npm install @oasiz/sdk@^0.1.0
+npm install @oasiz/sdk
 ```
 
 ## Quick start
@@ -13,27 +13,17 @@ npm install @oasiz/sdk@^0.1.0
 ```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");
 
-// 5. Submit score when the game ends
+// 4. Submit score when the game ends
 oasiz.submitScore(score);
 ```
 
@@ -43,44 +33,14 @@ oasiz.submitScore(score);
 
 ### `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.
+Submit the player's score. The platform handles leaderboard persistence — do not track high scores locally.
 
 ```ts
-private onGameOver(): void {
-  oasiz.submitScore(Math.floor(this.score));
-}
+oasiz.submitScore(this.score);
 ```
 
 - `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
-  ],
-});
-```
-
-**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`
+- When and how often you call this depends on your game type (once at game over, end of each level, or throttled for long sessions).
 
 ---
 
@@ -99,23 +59,14 @@ type HapticType = "light" | "medium" | "heavy" | "success" | "error";
 | `"light"` | UI button taps, menu navigation, D-pad press |
 | `"medium"` | Collecting items, standard collisions, scoring |
 | `"heavy"` | Explosions, major impacts, screen shake |
-| `"success"` | Level complete, new high score, achievement unlocked |
+| `"success"` | Level complete, achievement unlocked |
 | `"error"` | Damage taken, game over, invalid action |
 
 ```ts
-// UI buttons — always light
 button.addEventListener("click", () => {
   oasiz.triggerHaptic("light");
 });
 
-// Tiered hit feedback
-private onBallHit(zone: "center" | "edge"): void {
-  if (this.settings.haptics) {
-    oasiz.triggerHaptic(zone === "center" ? "success" : "medium");
-  }
-}
-
-// Game over
 private onGameOver(): void {
   oasiz.submitScore(this.score);
   if (this.settings.haptics) {
@@ -124,75 +75,54 @@ private onGameOver(): void {
 }
 ```
 
-Haptics are throttled internally (50ms cooldown) to prevent spam.
-
 ---
 
 ## 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.
+Persist cross-session data such as unlocked levels, inventory, or lifetime stats. Available across devices and app reinstalls.
 
 ### `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.
+Returns the player's saved state synchronously. Returns `{}` if no state has been saved yet.
 
 ```ts
-private initFromSavedState(): void {
-  const state = oasiz.loadGameState();
-  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 : [];
-}
+const state = oasiz.loadGameState();
+this.level = typeof state.level === "number" ? state.level : 1;
 ```
 
-Always validate the shape of loaded data — it may be `{}` on first play.
-
 ### `oasiz.saveGameState(state: Record<string, unknown>)`
 
-Queues a debounced save. Saves are batched automatically — call freely at checkpoints without worrying about request spam.
+Queues a debounced save. Call freely at checkpoints.
 
 ```ts
-// Save after each level completion
-private onLevelComplete(): void {
-  this.level += 1;
-  oasiz.saveGameState({
-    level: this.level,
-    lifetimeHits: this.lifetimeHits,
-    unlockedSkins: this.unlockedSkins,
-  });
-}
+oasiz.saveGameState({ level: this.level, unlockedSkins: this.unlockedSkins });
 ```
 
-**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`.
+- Use `saveGameState` instead of `localStorage` for cross-session progress.
+- Do not store scores here — use `submitScore`.
 
 ### `oasiz.flushGameState()`
 
-Forces an immediate write, bypassing the debounce. Use at important checkpoints like game over or before the page unloads.
+Forces an immediate write, bypassing the debounce. Use at game over or before page unload.
 
 ```ts
-private onGameOver(): void {
-  oasiz.saveGameState({ level: this.level, lifetimeHits: this.lifetimeHits });
-  oasiz.flushGameState(); // ensure it lands before the page closes
-  oasiz.submitScore(this.score);
-}
+oasiz.saveGameState({ level: this.level });
+oasiz.flushGameState();
+oasiz.submitScore(this.score);
 ```
 
 ---
 
 ## 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`
 
 Both return an unsubscribe function.
 
 ```ts
-const offPause  = oasiz.onPause(() => {
+const offPause = oasiz.onPause(() => {
   this.gameLoop.stop();
   this.bgMusic.pause();
 });
@@ -202,7 +132,6 @@ const offResume = oasiz.onResume(() => {
   this.bgMusic.play();
 });
 
-// Clean up when the game is destroyed
 offPause();
 offResume();
 ```
@@ -213,47 +142,29 @@ offResume();
 
 ### `oasiz.shareRoomCode(code: string | null)`
 
-Notify the platform of the active multiplayer room so friends can join via the invite system. Pass `null` when leaving a room.
+Notify the platform of the active multiplayer room. Pass `null` when leaving.
 
 ```ts
-import { insertCoin, getRoomCode } from "playroomkit";
-import { oasiz } from "@oasiz/sdk";
-
-await insertCoin({ skipLobby: true });
 oasiz.shareRoomCode(getRoomCode());
-
-// On disconnect
 oasiz.shareRoomCode(null);
 ```
 
-### Read-only injected values
-
-These are populated by the platform before the game loads. Always check for `undefined` before using.
+### Read-only properties
 
-```ts
-// The platform's internal game ID
-const gameId = oasiz.gameId;
-
-// Pre-filled room code for auto-joining a friend's session
-if (oasiz.roomCode) {
-  await connectToRoom(oasiz.roomCode);
-}
-
-// Player identity for multiplayer games
-const name   = oasiz.playerName;
-const avatar = oasiz.playerAvatar;
-```
+| Property | Type | Description |
+|---|---|---|
+| `oasiz.gameId` | string \| undefined | The platform's game ID |
+| `oasiz.roomCode` | string \| undefined | Pre-filled room code from invite |
+| `oasiz.playerName` | string \| undefined | Player's display name |
+| `oasiz.playerAvatar` | string \| undefined | Player's profile picture URL |
 
 ---
 
 ## 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,
@@ -273,17 +184,15 @@ import {
 ## TypeScript types
 
 ```ts
-import type { HapticType, ScoreConfig, ScoreAnchor, GameState } from "@oasiz/sdk";
+import type { HapticType, GameState } from "@oasiz/sdk";
 ```
 
 ---
 
 ## Local development
 
-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:
+All methods safely no-op when the platform bridges are not injected. In development mode a console warning is logged:
 
 ```
 [oasiz/sdk] submitScore bridge is unavailable. This is expected in local development.
 ```
-
-No crashes, no special setup required for local dev.

package/dist/index.cjs

@@ -20,14 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  emitScoreConfig: () => emitScoreConfig,
   flushGameState: () => flushGameState,
   getGameId: () => getGameId,
   getPlayerAvatar: () => getPlayerAvatar,
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
   loadGameState: () => loadGameState,
-  oasis: () => oasis,
+  oasiz: () => oasiz,
   onPause: () => onPause,
   onResume: () => onResume,
   saveGameState: () => saveGameState,
@@ -134,14 +133,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() {
@@ -235,9 +226,8 @@ function onResume(callback) {
 }
 
 // src/index.ts
-var oasis = {
+var oasiz = {
   submitScore,
-  emitScoreConfig,
   triggerHaptic,
   loadGameState,
   saveGameState,
@@ -260,14 +250,13 @@ var oasis = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  emitScoreConfig,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
   loadGameState,
-  oasis,
+  oasiz,
   onPause,
   onResume,
   saveGameState,

package/dist/index.d.cts

@@ -1,35 +1,245 @@
+/**
+ * Intensity level for native haptic feedback.
+ *
+ * | Type        | Use case                                        |
+ * |-------------|-------------------------------------------------|
+ * | `"light"`   | UI button taps, menu navigation, D-pad press    |
+ * | `"medium"`  | Collecting items, standard collisions, scoring   |
+ * | `"heavy"`   | Explosions, major impacts, screen shake          |
+ * | `"success"` | Level complete, achievement unlocked             |
+ * | `"error"`   | Damage taken, game over, invalid action          |
+ *
+ * @category Haptics
+ */
 type HapticType = "light" | "medium" | "heavy" | "success" | "error";
-interface ScoreAnchor {
-    raw: number;
-    normalized: 100 | 300 | 600 | 950;
-}
-interface ScoreConfig {
-    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
-}
+/**
+ * A plain JSON-serializable object used for cross-session game state
+ * persistence.
+ *
+ * @category State
+ */
 type GameState = Record<string, unknown>;
 
+/**
+ * Trigger native haptic feedback on the player's device.
+ *
+ * Always guard calls with the user's haptics preference toggle.
+ * The bridge is a no-op in local development (a console warning is logged).
+ *
+ * @param type - The haptic intensity level.
+ *
+ * @example
+ * ```ts
+ * // UI button tap
+ * oasiz.triggerHaptic("light");
+ *
+ * // Tiered hit feedback
+ * oasiz.triggerHaptic(isPerfectHit ? "success" : "medium");
+ *
+ * // Game over
+ * oasiz.triggerHaptic("error");
+ * ```
+ *
+ * @category Haptics
+ */
 declare function triggerHaptic(type: HapticType): void;
 
+/**
+ * Notify the platform of the active multiplayer room so friends can join
+ * via the invite system. Pass `null` when leaving a room.
+ *
+ * @param roomCode - The room code string, or `null` to clear.
+ *
+ * @example
+ * ```ts
+ * import { insertCoin, getRoomCode } from "playroomkit";
+ *
+ * await insertCoin({ skipLobby: true });
+ * oasiz.shareRoomCode(getRoomCode());
+ *
+ * // On disconnect
+ * oasiz.shareRoomCode(null);
+ * ```
+ *
+ * @category Multiplayer
+ */
 declare function shareRoomCode(roomCode: string | null): void;
+/**
+ * Get the platform's internal game ID, injected before the game loads.
+ *
+ * @returns The game ID string, or `undefined` if not yet injected.
+ *
+ * @category Multiplayer
+ */
 declare function getGameId(): string | undefined;
+/**
+ * Get the pre-filled room code for auto-joining a friend's multiplayer session.
+ *
+ * @returns The room code string, or `undefined` if not in a multiplayer context.
+ *
+ * @category Multiplayer
+ */
 declare function getRoomCode(): string | undefined;
+/**
+ * Get the current player's display name, injected by the platform.
+ *
+ * @returns The player name, or `undefined` if not available.
+ *
+ * @category Multiplayer
+ */
 declare function getPlayerName(): string | undefined;
+/**
+ * Get the current player's avatar URL, injected by the platform.
+ *
+ * @returns The avatar URL string, or `undefined` if not available.
+ *
+ * @category Multiplayer
+ */
 declare function getPlayerAvatar(): string | undefined;
 
+/**
+ * Submit the player's score.
+ *
+ * The platform handles leaderboard persistence — do not track high scores locally.
+ *
+ * - `score` must be a finite number. Floats are floored, negatives are clamped to 0.
+ * - In development mode a console warning is logged when the bridge is unavailable.
+ *
+ * @param score - The player's score (non-negative integer).
+ *
+ * @example
+ * ```ts
+ * oasiz.submitScore(Math.floor(this.score));
+ * ```
+ *
+ * @category Score
+ */
 declare function submitScore(score: number): void;
-declare function emitScoreConfig(config: ScoreConfig): void;
 
+/**
+ * Load the player's persisted game state.
+ *
+ * Returns the saved state synchronously. Returns `{}` if no state has been
+ * saved yet or if the bridge is unavailable. Always validate the shape of
+ * the returned data — it may be empty on first play.
+ *
+ * Call once at the start of the game.
+ *
+ * @returns The player's saved {@link GameState}, or an empty object.
+ *
+ * @example
+ * ```ts
+ * const state = oasiz.loadGameState();
+ * this.level = typeof state.level === "number" ? state.level : 1;
+ * ```
+ *
+ * @category State
+ */
 declare function loadGameState(): GameState;
+/**
+ * Queue a debounced save of the player's game state.
+ *
+ * Saves are batched automatically — call freely at checkpoints without
+ * worrying about request spam. State must be a plain JSON-serializable object.
+ *
+ * @param state - A plain object to persist. Do not pass arrays or primitives.
+ *
+ * @example
+ * ```ts
+ * oasiz.saveGameState({
+ *   level: this.level,
+ *   lifetimeHits: this.lifetimeHits,
+ *   unlockedSkins: this.unlockedSkins,
+ * });
+ * ```
+ *
+ * @category State
+ */
 declare function saveGameState(state: GameState): void;
+/**
+ * Force an immediate write of the pending game state, bypassing the debounce.
+ *
+ * Use at critical checkpoints like game over or before the page unloads
+ * to ensure data is persisted.
+ *
+ * @example
+ * ```ts
+ * oasiz.saveGameState({ level: this.level });
+ * oasiz.flushGameState(); // ensure it lands before the page closes
+ * oasiz.submitScore(this.score);
+ * ```
+ *
+ * @category State
+ */
 declare function flushGameState(): void;
 
+/**
+ * A function that removes an event listener when called.
+ * Returned by {@link onPause} and {@link onResume}.
+ *
+ * @category Lifecycle
+ */
 type Unsubscribe = () => void;
+/**
+ * Register a callback that fires when the app goes to the background.
+ *
+ * Use this to pause game loops, audio, and animations so the game
+ * doesn't continue running while the player is away.
+ *
+ * @param callback - Invoked when the platform dispatches `oasiz:pause`.
+ * @returns An {@link Unsubscribe} function that removes the listener.
+ *
+ * @example
+ * ```ts
+ * const off = oasiz.onPause(() => {
+ *   this.gameLoop.stop();
+ *   this.bgMusic.pause();
+ * });
+ *
+ * // Later, clean up:
+ * off();
+ * ```
+ *
+ * @category Lifecycle
+ */
 declare function onPause(callback: () => void): Unsubscribe;
+/**
+ * Register a callback that fires when the app returns to the foreground.
+ *
+ * Use this to resume game loops, audio, and animations after a pause.
+ *
+ * @param callback - Invoked when the platform dispatches `oasiz:resume`.
+ * @returns An {@link Unsubscribe} function that removes the listener.
+ *
+ * @example
+ * ```ts
+ * const off = oasiz.onResume(() => {
+ *   this.gameLoop.start();
+ *   this.bgMusic.play();
+ * });
+ *
+ * // Later, clean up:
+ * off();
+ * ```
+ *
+ * @category Lifecycle
+ */
 declare function onResume(callback: () => void): Unsubscribe;
 
-declare const oasis: {
+/**
+ * The main SDK namespace object. Provides convenient access to all
+ * platform bridge APIs as a single import.
+ *
+ * @example
+ * ```ts
+ * import { oasiz } from "@oasiz/sdk";
+ *
+ * oasiz.triggerHaptic("medium");
+ * oasiz.submitScore(score);
+ * ```
+ */
+declare const oasiz: {
     submitScore: typeof submitScore;
-    emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
     loadGameState: typeof loadGameState;
     saveGameState: typeof saveGameState;
@@ -43,4 +253,4 @@ declare const oasis: {
     readonly playerAvatar: string | undefined;
 };
 
-export { type GameState, type HapticType, type ScoreAnchor, type ScoreConfig, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasis, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };
+export { type GameState, type HapticType, type Unsubscribe, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasiz, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -1,35 +1,245 @@
+/**
+ * Intensity level for native haptic feedback.
+ *
+ * | Type        | Use case                                        |
+ * |-------------|-------------------------------------------------|
+ * | `"light"`   | UI button taps, menu navigation, D-pad press    |
+ * | `"medium"`  | Collecting items, standard collisions, scoring   |
+ * | `"heavy"`   | Explosions, major impacts, screen shake          |
+ * | `"success"` | Level complete, achievement unlocked             |
+ * | `"error"`   | Damage taken, game over, invalid action          |
+ *
+ * @category Haptics
+ */
 type HapticType = "light" | "medium" | "heavy" | "success" | "error";
-interface ScoreAnchor {
-    raw: number;
-    normalized: 100 | 300 | 600 | 950;
-}
-interface ScoreConfig {
-    anchors: [ScoreAnchor, ScoreAnchor, ScoreAnchor, ScoreAnchor];
-}
+/**
+ * A plain JSON-serializable object used for cross-session game state
+ * persistence.
+ *
+ * @category State
+ */
 type GameState = Record<string, unknown>;
 
+/**
+ * Trigger native haptic feedback on the player's device.
+ *
+ * Always guard calls with the user's haptics preference toggle.
+ * The bridge is a no-op in local development (a console warning is logged).
+ *
+ * @param type - The haptic intensity level.
+ *
+ * @example
+ * ```ts
+ * // UI button tap
+ * oasiz.triggerHaptic("light");
+ *
+ * // Tiered hit feedback
+ * oasiz.triggerHaptic(isPerfectHit ? "success" : "medium");
+ *
+ * // Game over
+ * oasiz.triggerHaptic("error");
+ * ```
+ *
+ * @category Haptics
+ */
 declare function triggerHaptic(type: HapticType): void;
 
+/**
+ * Notify the platform of the active multiplayer room so friends can join
+ * via the invite system. Pass `null` when leaving a room.
+ *
+ * @param roomCode - The room code string, or `null` to clear.
+ *
+ * @example
+ * ```ts
+ * import { insertCoin, getRoomCode } from "playroomkit";
+ *
+ * await insertCoin({ skipLobby: true });
+ * oasiz.shareRoomCode(getRoomCode());
+ *
+ * // On disconnect
+ * oasiz.shareRoomCode(null);
+ * ```
+ *
+ * @category Multiplayer
+ */
 declare function shareRoomCode(roomCode: string | null): void;
+/**
+ * Get the platform's internal game ID, injected before the game loads.
+ *
+ * @returns The game ID string, or `undefined` if not yet injected.
+ *
+ * @category Multiplayer
+ */
 declare function getGameId(): string | undefined;
+/**
+ * Get the pre-filled room code for auto-joining a friend's multiplayer session.
+ *
+ * @returns The room code string, or `undefined` if not in a multiplayer context.
+ *
+ * @category Multiplayer
+ */
 declare function getRoomCode(): string | undefined;
+/**
+ * Get the current player's display name, injected by the platform.
+ *
+ * @returns The player name, or `undefined` if not available.
+ *
+ * @category Multiplayer
+ */
 declare function getPlayerName(): string | undefined;
+/**
+ * Get the current player's avatar URL, injected by the platform.
+ *
+ * @returns The avatar URL string, or `undefined` if not available.
+ *
+ * @category Multiplayer
+ */
 declare function getPlayerAvatar(): string | undefined;
 
+/**
+ * Submit the player's score.
+ *
+ * The platform handles leaderboard persistence — do not track high scores locally.
+ *
+ * - `score` must be a finite number. Floats are floored, negatives are clamped to 0.
+ * - In development mode a console warning is logged when the bridge is unavailable.
+ *
+ * @param score - The player's score (non-negative integer).
+ *
+ * @example
+ * ```ts
+ * oasiz.submitScore(Math.floor(this.score));
+ * ```
+ *
+ * @category Score
+ */
 declare function submitScore(score: number): void;
-declare function emitScoreConfig(config: ScoreConfig): void;
 
+/**
+ * Load the player's persisted game state.
+ *
+ * Returns the saved state synchronously. Returns `{}` if no state has been
+ * saved yet or if the bridge is unavailable. Always validate the shape of
+ * the returned data — it may be empty on first play.
+ *
+ * Call once at the start of the game.
+ *
+ * @returns The player's saved {@link GameState}, or an empty object.
+ *
+ * @example
+ * ```ts
+ * const state = oasiz.loadGameState();
+ * this.level = typeof state.level === "number" ? state.level : 1;
+ * ```
+ *
+ * @category State
+ */
 declare function loadGameState(): GameState;
+/**
+ * Queue a debounced save of the player's game state.
+ *
+ * Saves are batched automatically — call freely at checkpoints without
+ * worrying about request spam. State must be a plain JSON-serializable object.
+ *
+ * @param state - A plain object to persist. Do not pass arrays or primitives.
+ *
+ * @example
+ * ```ts
+ * oasiz.saveGameState({
+ *   level: this.level,
+ *   lifetimeHits: this.lifetimeHits,
+ *   unlockedSkins: this.unlockedSkins,
+ * });
+ * ```
+ *
+ * @category State
+ */
 declare function saveGameState(state: GameState): void;
+/**
+ * Force an immediate write of the pending game state, bypassing the debounce.
+ *
+ * Use at critical checkpoints like game over or before the page unloads
+ * to ensure data is persisted.
+ *
+ * @example
+ * ```ts
+ * oasiz.saveGameState({ level: this.level });
+ * oasiz.flushGameState(); // ensure it lands before the page closes
+ * oasiz.submitScore(this.score);
+ * ```
+ *
+ * @category State
+ */
 declare function flushGameState(): void;
 
+/**
+ * A function that removes an event listener when called.
+ * Returned by {@link onPause} and {@link onResume}.
+ *
+ * @category Lifecycle
+ */
 type Unsubscribe = () => void;
+/**
+ * Register a callback that fires when the app goes to the background.
+ *
+ * Use this to pause game loops, audio, and animations so the game
+ * doesn't continue running while the player is away.
+ *
+ * @param callback - Invoked when the platform dispatches `oasiz:pause`.
+ * @returns An {@link Unsubscribe} function that removes the listener.
+ *
+ * @example
+ * ```ts
+ * const off = oasiz.onPause(() => {
+ *   this.gameLoop.stop();
+ *   this.bgMusic.pause();
+ * });
+ *
+ * // Later, clean up:
+ * off();
+ * ```
+ *
+ * @category Lifecycle
+ */
 declare function onPause(callback: () => void): Unsubscribe;
+/**
+ * Register a callback that fires when the app returns to the foreground.
+ *
+ * Use this to resume game loops, audio, and animations after a pause.
+ *
+ * @param callback - Invoked when the platform dispatches `oasiz:resume`.
+ * @returns An {@link Unsubscribe} function that removes the listener.
+ *
+ * @example
+ * ```ts
+ * const off = oasiz.onResume(() => {
+ *   this.gameLoop.start();
+ *   this.bgMusic.play();
+ * });
+ *
+ * // Later, clean up:
+ * off();
+ * ```
+ *
+ * @category Lifecycle
+ */
 declare function onResume(callback: () => void): Unsubscribe;
 
-declare const oasis: {
+/**
+ * The main SDK namespace object. Provides convenient access to all
+ * platform bridge APIs as a single import.
+ *
+ * @example
+ * ```ts
+ * import { oasiz } from "@oasiz/sdk";
+ *
+ * oasiz.triggerHaptic("medium");
+ * oasiz.submitScore(score);
+ * ```
+ */
+declare const oasiz: {
     submitScore: typeof submitScore;
-    emitScoreConfig: typeof emitScoreConfig;
     triggerHaptic: typeof triggerHaptic;
     loadGameState: typeof loadGameState;
     saveGameState: typeof saveGameState;
@@ -43,4 +253,4 @@ declare const oasis: {
     readonly playerAvatar: string | undefined;
 };
 
-export { type GameState, type HapticType, type ScoreAnchor, type ScoreConfig, type Unsubscribe, emitScoreConfig, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasis, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };
+export { type GameState, type HapticType, type Unsubscribe, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, loadGameState, oasiz, onPause, onResume, saveGameState, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.global.js

@@ -0,0 +1,252 @@
+"use strict";
+var oasiz = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/index.ts
+  var index_exports = {};
+  __export(index_exports, {
+    flushGameState: () => flushGameState,
+    getGameId: () => getGameId,
+    getPlayerAvatar: () => getPlayerAvatar,
+    getPlayerName: () => getPlayerName,
+    getRoomCode: () => getRoomCode,
+    loadGameState: () => loadGameState,
+    oasiz: () => oasiz,
+    onPause: () => onPause,
+    onResume: () => onResume,
+    saveGameState: () => saveGameState,
+    shareRoomCode: () => shareRoomCode,
+    submitScore: () => submitScore,
+    triggerHaptic: () => triggerHaptic
+  });
+
+  // src/haptics.ts
+  function isDevelopment() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function getBridgeWindow() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return window;
+  }
+  function triggerHaptic(type) {
+    const bridge = getBridgeWindow();
+    if (typeof bridge?.triggerHaptic === "function") {
+      bridge.triggerHaptic(type);
+      return;
+    }
+    if (isDevelopment()) {
+      console.warn(
+        "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+
+  // src/multiplayer.ts
+  function isDevelopment2() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function getBridgeWindow2() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return window;
+  }
+  function shareRoomCode(roomCode) {
+    const bridge = getBridgeWindow2();
+    if (typeof bridge?.shareRoomCode === "function") {
+      bridge.shareRoomCode(roomCode);
+      return;
+    }
+    if (isDevelopment2()) {
+      console.warn(
+        "[oasiz/sdk] shareRoomCode bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+  function getGameId() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__GAME_ID__;
+  }
+  function getRoomCode() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__ROOM_CODE__;
+  }
+  function getPlayerName() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__PLAYER_NAME__;
+  }
+  function getPlayerAvatar() {
+    const bridge = getBridgeWindow2();
+    return bridge?.__PLAYER_AVATAR__;
+  }
+
+  // src/score.ts
+  function isDevelopment3() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function warnMissingBridge(methodName) {
+    if (isDevelopment3()) {
+      console.warn(
+        "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+  function getBridgeWindow3() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return window;
+  }
+  function submitScore(score) {
+    if (!Number.isFinite(score)) {
+      if (isDevelopment3()) {
+        console.warn("[oasiz/sdk] submitScore expected a finite number:", score);
+      }
+      return;
+    }
+    const bridge = getBridgeWindow3();
+    const normalizedScore = Math.max(0, Math.floor(score));
+    if (typeof bridge?.submitScore === "function") {
+      bridge.submitScore(normalizedScore);
+      return;
+    }
+    warnMissingBridge("submitScore");
+  }
+
+  // src/state.ts
+  function isDevelopment4() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function getBridgeWindow4() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return window;
+  }
+  function isPlainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+  }
+  function warnMissingBridge2(methodName) {
+    if (isDevelopment4()) {
+      console.warn(
+        "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+      );
+    }
+  }
+  function loadGameState() {
+    const bridge = getBridgeWindow4();
+    if (typeof bridge?.loadGameState !== "function") {
+      warnMissingBridge2("loadGameState");
+      return {};
+    }
+    const state = bridge.loadGameState();
+    if (!isPlainObject(state)) {
+      if (isDevelopment4()) {
+        console.warn(
+          "[oasiz/sdk] loadGameState returned invalid data. Falling back to empty object."
+        );
+      }
+      return {};
+    }
+    return state;
+  }
+  function saveGameState(state) {
+    if (!isPlainObject(state)) {
+      if (isDevelopment4()) {
+        console.warn("[oasiz/sdk] saveGameState expected a plain object:", state);
+      }
+      return;
+    }
+    const bridge = getBridgeWindow4();
+    if (typeof bridge?.saveGameState === "function") {
+      bridge.saveGameState(state);
+      return;
+    }
+    warnMissingBridge2("saveGameState");
+  }
+  function flushGameState() {
+    const bridge = getBridgeWindow4();
+    if (typeof bridge?.flushGameState === "function") {
+      bridge.flushGameState();
+      return;
+    }
+    warnMissingBridge2("flushGameState");
+  }
+
+  // src/lifecycle.ts
+  function isDevelopment5() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    return nodeEnv !== "production";
+  }
+  function addLifecycleListener(eventName, callback) {
+    if (typeof window === "undefined") {
+      if (isDevelopment5()) {
+        console.warn(
+          "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
+        );
+      }
+      return () => {
+      };
+    }
+    const handler = () => callback();
+    window.addEventListener(eventName, handler);
+    return () => window.removeEventListener(eventName, handler);
+  }
+  function onPause(callback) {
+    return addLifecycleListener("oasiz:pause", callback);
+  }
+  function onResume(callback) {
+    return addLifecycleListener("oasiz:resume", callback);
+  }
+
+  // src/index.ts
+  var oasiz = {
+    submitScore,
+    triggerHaptic,
+    loadGameState,
+    saveGameState,
+    flushGameState,
+    shareRoomCode,
+    onPause,
+    onResume,
+    get gameId() {
+      return getGameId();
+    },
+    get roomCode() {
+      return getRoomCode();
+    },
+    get playerName() {
+      return getPlayerName();
+    },
+    get playerAvatar() {
+      return getPlayerAvatar();
+    }
+  };
+  return __toCommonJS(index_exports);
+})();

package/dist/index.js

@@ -95,14 +95,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() {
@@ -196,9 +188,8 @@ function onResume(callback) {
 }
 
 // src/index.ts
-var oasis = {
+var oasiz = {
   submitScore,
-  emitScoreConfig,
   triggerHaptic,
   loadGameState,
   saveGameState,
@@ -220,14 +211,13 @@ var oasis = {
   }
 };
 export {
-  emitScoreConfig,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
   loadGameState,
-  oasis,
+  oasiz,
   onPause,
   onResume,
   saveGameState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -10,7 +10,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.cjs",
+      "script": "./dist/index.global.js"
     }
   },
   "files": [
@@ -18,9 +19,11 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts --format esm,cjs,iife --global-name oasiz --dts",
     "prepack": "bun run build",
-    "test": "node --experimental-strip-types --test ./tests/**/*.test.ts"
+    "test": "node --experimental-strip-types --test ./tests/**/*.test.ts",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch"
   },
   "publishConfig": {
     "access": "public"
@@ -47,6 +50,7 @@
     "@types/node": "^25.3.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3"
   }
 }