@oasiz/sdk 1.2.0 → 1.3.0

package/README.md

@@ -35,6 +35,12 @@ oasiz.triggerHaptic("medium");
 
 // 5. Submit score when the game ends
 oasiz.submitScore(score);
+
+// 6. Optionally surface console logs in-game while debugging
+oasiz.enableLogOverlay({
+  enabled: new URLSearchParams(window.location.search).has("oasizLogs"),
+  collapsed: true,
+});
 ```
 
 ---
@@ -128,6 +134,34 @@ Haptics are throttled internally (50ms cooldown) to prevent spam.
 
 ---
 
+## Debugging
+
+### `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.
+
+```ts
+const logOverlay = oasiz.enableLogOverlay({
+  enabled: new URLSearchParams(window.location.search).has("oasizLogs"),
+  collapsed: true,
+});
+
+console.log("[Boot] Scene ready");
+
+// Optional cleanup if your game tears down and remounts
+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`.
+- `title`: optional label shown at the top of the panel. Defaults to `SDK Logs`.
+
+The returned handle supports `show()`, `hide()`, `clear()`, `isVisible()`, and `destroy()`.
+
+---
+
 ## 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.
@@ -327,6 +361,7 @@ import {
   saveGameState,
   flushGameState,
   shareRoomCode,
+  enableLogOverlay,
   onPause,
   onResume,
   onBackButton,
@@ -344,7 +379,14 @@ import {
 ## TypeScript types
 
 ```ts
-import type { HapticType, ScoreConfig, ScoreAnchor, GameState } from "@oasiz/sdk";
+import type {
+  GameState,
+  HapticType,
+  LogOverlayHandle,
+  LogOverlayOptions,
+  ScoreAnchor,
+  ScoreConfig,
+} from "@oasiz/sdk";
 ```
 
 ---