@thestatic-tv/dcl-sdk 2.5.17 → 2.5.18

package/dist/index.d.mts

@@ -320,6 +320,25 @@ interface SceneTabDefinition {
     /** React-ECS component that renders the tab content */
     render: () => JSX.Element | null;
 }
+/**
+ * Scene boundary information calculated from parcels
+ */
+interface SceneBounds$1 {
+    /** Minimum X coordinate (always 0 in local coords) */
+    minX: number;
+    /** Maximum X coordinate (width in meters) */
+    maxX: number;
+    /** Minimum Z coordinate (always 0 in local coords) */
+    minZ: number;
+    /** Maximum Z coordinate (depth in meters) */
+    maxZ: number;
+    /** Scene width in meters */
+    width: number;
+    /** Scene depth in meters */
+    depth: number;
+    /** Original parcel strings from scene.json */
+    parcels: string[];
+}
 /**
  * Configuration options for AdminPanelModule
  */
@@ -428,6 +447,9 @@ declare class GuideModule {
  *
  * Works with both channel keys (dclk_) and scene keys (dcls_).
  * Scene keys use /scene-session endpoint, channel keys use /session.
+ *
+ * Includes automatic boundary detection to ensure metrics only track
+ * players who are actually within the scene's parcel boundaries.
  */
 
 declare class SessionModule {
@@ -437,7 +459,19 @@ declare class SessionModule {
     private heartbeatTimerId;
     private isActive;
     private _tier;
+    private _bounds;
+    private _boundsInitialized;
+    private _outOfBoundsCount;
     constructor(client: StaticTVClient);
+    /**
+     * Get the scene bounds (auto-detected from parcels)
+     * Returns null if bounds haven't been initialized yet
+     */
+    get bounds(): SceneBounds$1 | null;
+    /**
+     * Check if player is currently within scene bounds
+     */
+    isPlayerInScene(): boolean;
     /**
      * Get the API key ID (used as default sceneId for Pro users)
      */
@@ -466,6 +500,11 @@ declare class SessionModule {
      * Get player display name - prioritize config, fallback to runtime detection
      */
     private getDisplayName;
+    /**
+     * Initialize scene bounds from DCL Runtime
+     * Called once on session start
+     */
+    private initializeBounds;
     /**
      * Start a new session
      * Called automatically if autoStartSession is true
@@ -477,6 +516,7 @@ declare class SessionModule {
     private startHeartbeat;
     /**
      * Send a session heartbeat
+     * Always sends heartbeat with inScene status so dashboard can track location
      */
     private sendHeartbeat;
     /**
@@ -500,6 +540,8 @@ declare class SessionModule {
 
 /**
  * Heartbeat module - track video watching metrics
+ *
+ * Only tracks when player is within scene bounds.
  */
 
 declare class HeartbeatModule {
@@ -525,6 +567,7 @@ declare class HeartbeatModule {
     private getWallet;
     /**
      * Send a watching heartbeat (1 heartbeat = 1 minute watched)
+     * Only sends if player is within scene bounds
      */
     private sendHeartbeat;
     /**
@@ -1301,4 +1344,32 @@ declare function getPlayerWallet(): string | null;
  */
 declare function getPlayerDisplayName(): string | null;
 
-export { type AdminPanelConfig, AdminPanelUIModule, type Channel, type ChatChannel, type ChatMessage, type ChatUIConfig, ChatUIModule, type CommandHandler, type GuideFeaturedPlaylist, GuideModule, type GuideResponse, type GuideUIConfig, GuideUIModule, type GuideVideo, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, NotificationBanner, type PlayerData, type SDKTier, type SceneStats, type SceneStatsResponse, type SceneTabDefinition, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type StreamData, type VideoSlot, type Vod, fetchUserData, getPlayerDisplayName, getPlayerWallet, hideNotification, setupStaticUI, showNotification };
+interface SceneBounds {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+    width: number;
+    depth: number;
+    parcels: string[];
+}
+/**
+ * Get scene bounds from DCL Runtime
+ * Auto-detects parcels and calculates local coordinate bounds
+ */
+declare function getSceneBounds(): Promise<SceneBounds | null>;
+/**
+ * Check if player is within scene boundaries
+ * Returns true if in bounds, false if out of bounds or can't determine
+ */
+declare function isPlayerInBounds(bounds: SceneBounds): boolean;
+/**
+ * Get player's current position
+ */
+declare function getPlayerPosition(): {
+    x: number;
+    y: number;
+    z: number;
+} | null;
+
+export { type AdminPanelConfig, AdminPanelUIModule, type Channel, type ChatChannel, type ChatMessage, type ChatUIConfig, ChatUIModule, type CommandHandler, type GuideFeaturedPlaylist, GuideModule, type GuideResponse, type GuideUIConfig, GuideUIModule, type GuideVideo, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, NotificationBanner, type PlayerData, type SDKTier, type SceneBounds$1 as SceneBounds, type SceneStats, type SceneStatsResponse, type SceneTabDefinition, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type StreamData, type VideoSlot, type Vod, fetchUserData, getPlayerDisplayName, getPlayerPosition, getPlayerWallet, getSceneBounds, hideNotification, isPlayerInBounds, setupStaticUI, showNotification };

package/dist/index.d.ts

@@ -320,6 +320,25 @@ interface SceneTabDefinition {
     /** React-ECS component that renders the tab content */
     render: () => JSX.Element | null;
 }
+/**
+ * Scene boundary information calculated from parcels
+ */
+interface SceneBounds$1 {
+    /** Minimum X coordinate (always 0 in local coords) */
+    minX: number;
+    /** Maximum X coordinate (width in meters) */
+    maxX: number;
+    /** Minimum Z coordinate (always 0 in local coords) */
+    minZ: number;
+    /** Maximum Z coordinate (depth in meters) */
+    maxZ: number;
+    /** Scene width in meters */
+    width: number;
+    /** Scene depth in meters */
+    depth: number;
+    /** Original parcel strings from scene.json */
+    parcels: string[];
+}
 /**
  * Configuration options for AdminPanelModule
  */
@@ -428,6 +447,9 @@ declare class GuideModule {
  *
  * Works with both channel keys (dclk_) and scene keys (dcls_).
  * Scene keys use /scene-session endpoint, channel keys use /session.
+ *
+ * Includes automatic boundary detection to ensure metrics only track
+ * players who are actually within the scene's parcel boundaries.
  */
 
 declare class SessionModule {
@@ -437,7 +459,19 @@ declare class SessionModule {
     private heartbeatTimerId;
     private isActive;
     private _tier;
+    private _bounds;
+    private _boundsInitialized;
+    private _outOfBoundsCount;
     constructor(client: StaticTVClient);
+    /**
+     * Get the scene bounds (auto-detected from parcels)
+     * Returns null if bounds haven't been initialized yet
+     */
+    get bounds(): SceneBounds$1 | null;
+    /**
+     * Check if player is currently within scene bounds
+     */
+    isPlayerInScene(): boolean;
     /**
      * Get the API key ID (used as default sceneId for Pro users)
      */
@@ -466,6 +500,11 @@ declare class SessionModule {
      * Get player display name - prioritize config, fallback to runtime detection
      */
     private getDisplayName;
+    /**
+     * Initialize scene bounds from DCL Runtime
+     * Called once on session start
+     */
+    private initializeBounds;
     /**
      * Start a new session
      * Called automatically if autoStartSession is true
@@ -477,6 +516,7 @@ declare class SessionModule {
     private startHeartbeat;
     /**
      * Send a session heartbeat
+     * Always sends heartbeat with inScene status so dashboard can track location
      */
     private sendHeartbeat;
     /**
@@ -500,6 +540,8 @@ declare class SessionModule {
 
 /**
  * Heartbeat module - track video watching metrics
+ *
+ * Only tracks when player is within scene bounds.
  */
 
 declare class HeartbeatModule {
@@ -525,6 +567,7 @@ declare class HeartbeatModule {
     private getWallet;
     /**
      * Send a watching heartbeat (1 heartbeat = 1 minute watched)
+     * Only sends if player is within scene bounds
      */
     private sendHeartbeat;
     /**
@@ -1301,4 +1344,32 @@ declare function getPlayerWallet(): string | null;
  */
 declare function getPlayerDisplayName(): string | null;
 
-export { type AdminPanelConfig, AdminPanelUIModule, type Channel, type ChatChannel, type ChatMessage, type ChatUIConfig, ChatUIModule, type CommandHandler, type GuideFeaturedPlaylist, GuideModule, type GuideResponse, type GuideUIConfig, GuideUIModule, type GuideVideo, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, NotificationBanner, type PlayerData, type SDKTier, type SceneStats, type SceneStatsResponse, type SceneTabDefinition, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type StreamData, type VideoSlot, type Vod, fetchUserData, getPlayerDisplayName, getPlayerWallet, hideNotification, setupStaticUI, showNotification };
+interface SceneBounds {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+    width: number;
+    depth: number;
+    parcels: string[];
+}
+/**
+ * Get scene bounds from DCL Runtime
+ * Auto-detects parcels and calculates local coordinate bounds
+ */
+declare function getSceneBounds(): Promise<SceneBounds | null>;
+/**
+ * Check if player is within scene boundaries
+ * Returns true if in bounds, false if out of bounds or can't determine
+ */
+declare function isPlayerInBounds(bounds: SceneBounds): boolean;
+/**
+ * Get player's current position
+ */
+declare function getPlayerPosition(): {
+    x: number;
+    y: number;
+    z: number;
+} | null;
+
+export { type AdminPanelConfig, AdminPanelUIModule, type Channel, type ChatChannel, type ChatMessage, type ChatUIConfig, ChatUIModule, type CommandHandler, type GuideFeaturedPlaylist, GuideModule, type GuideResponse, type GuideUIConfig, GuideUIModule, type GuideVideo, HeartbeatModule, type HeartbeatResponse, type InteractionResponse, InteractionsModule, KEY_TYPE_CHANNEL, KEY_TYPE_SCENE, NotificationBanner, type PlayerData, type SDKTier, type SceneBounds$1 as SceneBounds, type SceneStats, type SceneStatsResponse, type SceneTabDefinition, SessionModule, type SessionResponse, StaticTVClient, type StaticTVConfig, type StreamData, type VideoSlot, type Vod, fetchUserData, getPlayerDisplayName, getPlayerPosition, getPlayerWallet, getSceneBounds, hideNotification, isPlayerInBounds, setupStaticUI, showNotification };

package/dist/index.js

@@ -43,8 +43,11 @@ __export(index_exports, {
   StaticTVClient: () => StaticTVClient,
   fetchUserData: () => fetchUserData,
   getPlayerDisplayName: () => getPlayerDisplayName,
+  getPlayerPosition: () => getPlayerPosition,
   getPlayerWallet: () => getPlayerWallet,
+  getSceneBounds: () => getSceneBounds,
   hideNotification: () => hideNotification,
+  isPlayerInBounds: () => isPlayerInBounds,
   setupStaticUI: () => setupStaticUI,
   showNotification: () => showNotification
 });
@@ -248,6 +251,93 @@ function dclClearTimeout(timeoutId) {
   }
 }
 
+// src/utils/bounds.ts
+var import_ecs2 = require("@dcl/sdk/ecs");
+var import_Runtime = require("~system/Runtime");
+var PARCEL_SIZE = 16;
+var cachedBounds = null;
+var boundsInitialized = false;
+var boundsError = false;
+function parseParcel(parcel) {
+  const parts = parcel.split(",");
+  if (parts.length !== 2) return null;
+  const x = parseInt(parts[0], 10);
+  const z = parseInt(parts[1], 10);
+  if (isNaN(x) || isNaN(z)) return null;
+  return { x, z };
+}
+async function getSceneBounds() {
+  if (boundsInitialized && cachedBounds) {
+    return cachedBounds;
+  }
+  if (boundsError) {
+    return null;
+  }
+  try {
+    const sceneInfo = await (0, import_Runtime.getSceneInformation)({});
+    let parcels = [];
+    let baseParcel;
+    if (sceneInfo.metadataJson) {
+      const metadata = JSON.parse(sceneInfo.metadataJson);
+      parcels = metadata?.scene?.parcels || [];
+      baseParcel = metadata?.scene?.base;
+    }
+    if (parcels.length === 0) {
+      boundsError = true;
+      return null;
+    }
+    const coords = parcels.map(parseParcel).filter((c) => c !== null);
+    if (coords.length === 0) {
+      boundsError = true;
+      return null;
+    }
+    const worldMinX = Math.min(...coords.map((c) => c.x));
+    const worldMaxX = Math.max(...coords.map((c) => c.x));
+    const worldMinZ = Math.min(...coords.map((c) => c.z));
+    const worldMaxZ = Math.max(...coords.map((c) => c.z));
+    const width = (worldMaxX - worldMinX + 1) * PARCEL_SIZE;
+    const depth = (worldMaxZ - worldMinZ + 1) * PARCEL_SIZE;
+    cachedBounds = {
+      minX: 0,
+      maxX: width,
+      minZ: 0,
+      maxZ: depth,
+      width,
+      depth,
+      parcels
+    };
+    boundsInitialized = true;
+    return cachedBounds;
+  } catch (error) {
+    boundsError = true;
+    return null;
+  }
+}
+function isPlayerInBounds(bounds) {
+  try {
+    const transform = import_ecs2.Transform.getOrNull(import_ecs2.engine.PlayerEntity);
+    if (!transform) return false;
+    const pos = transform.position;
+    const buffer = 0.5;
+    return pos.x >= bounds.minX - buffer && pos.x <= bounds.maxX + buffer && pos.z >= bounds.minZ - buffer && pos.z <= bounds.maxZ + buffer;
+  } catch {
+    return false;
+  }
+}
+function getPlayerPosition() {
+  try {
+    const transform = import_ecs2.Transform.getOrNull(import_ecs2.engine.PlayerEntity);
+    if (!transform) return null;
+    return {
+      x: transform.position.x,
+      y: transform.position.y,
+      z: transform.position.z
+    };
+  } catch {
+    return null;
+  }
+}
+
 // src/modules/session.ts
 function normalizeTier(tier) {
   if (tier === "lite") return "free";
@@ -262,8 +352,26 @@ var SessionModule = class {
     this.heartbeatTimerId = null;
     this.isActive = false;
     this._tier = "free";
+    // Boundary checking - auto-detected from scene parcels
+    this._bounds = null;
+    this._boundsInitialized = false;
+    this._outOfBoundsCount = 0;
     this.client = client;
   }
+  /**
+   * Get the scene bounds (auto-detected from parcels)
+   * Returns null if bounds haven't been initialized yet
+   */
+  get bounds() {
+    return this._bounds;
+  }
+  /**
+   * Check if player is currently within scene bounds
+   */
+  isPlayerInScene() {
+    if (!this._bounds) return true;
+    return isPlayerInBounds(this._bounds);
+  }
   /**
    * Get the API key ID (used as default sceneId for Pro users)
    */
@@ -306,6 +414,25 @@ var SessionModule = class {
     const config = this.client.getConfig();
     return config.player?.name || getPlayerDisplayName();
   }
+  /**
+   * Initialize scene bounds from DCL Runtime
+   * Called once on session start
+   */
+  async initializeBounds() {
+    if (this._boundsInitialized) return;
+    try {
+      this._bounds = await getSceneBounds();
+      this._boundsInitialized = true;
+      if (this._bounds) {
+        this.client.log(`Scene bounds detected: ${this._bounds.width}x${this._bounds.depth}m (${this._bounds.parcels.length} parcels)`);
+      } else {
+        this.client.log("Could not detect scene bounds - boundary checking disabled");
+      }
+    } catch (error) {
+      this.client.log(`Failed to detect scene bounds: ${error}`);
+      this._boundsInitialized = true;
+    }
+  }
   /**
    * Start a new session
    * Called automatically if autoStartSession is true
@@ -315,6 +442,7 @@ var SessionModule = class {
       this.client.log("Session already active");
       return this.sessionId;
     }
+    await this.initializeBounds();
     try {
       const walletAddress = this.getWallet();
       const dclDisplayName = this.getDisplayName();
@@ -356,18 +484,33 @@ var SessionModule = class {
   }
   /**
    * Send a session heartbeat
+   * Always sends heartbeat with inScene status so dashboard can track location
    */
   async sendHeartbeat() {
     if (!this.sessionId || !this.isActive) return;
+    const inScene = this.isPlayerInScene();
+    const pos = getPlayerPosition();
+    if (!inScene && this._outOfBoundsCount === 0) {
+      this.client.log(`Player left scene bounds (${pos?.x.toFixed(1)}, ${pos?.z.toFixed(1)})`);
+    } else if (inScene && this._outOfBoundsCount > 0) {
+      this.client.log(`Player returned to scene after ${this._outOfBoundsCount} heartbeats outside`);
+    }
+    if (!inScene) {
+      this._outOfBoundsCount++;
+    } else {
+      this._outOfBoundsCount = 0;
+    }
     try {
       await this.client.request(this.getEndpoint(), {
         method: "POST",
         body: JSON.stringify({
           action: "heartbeat",
-          sessionId: this.sessionId
+          sessionId: this.sessionId,
+          inScene,
+          position: pos ? { x: Math.round(pos.x), z: Math.round(pos.z) } : null
         })
       });
-      this.client.log("Session heartbeat sent");
+      this.client.log(`Session heartbeat sent (inScene: ${inScene})`);
     } catch (error) {
       this.client.log(`Session heartbeat failed: ${error}`);
     }
@@ -487,9 +630,14 @@ var HeartbeatModule = class {
   }
   /**
    * Send a watching heartbeat (1 heartbeat = 1 minute watched)
+   * Only sends if player is within scene bounds
    */
   async sendHeartbeat() {
     if (!this.currentChannel || !this.isWatching) return;
+    if (this.client.session && !this.client.session.isPlayerInScene()) {
+      this.client.log(`Watch heartbeat skipped - player out of scene bounds`);
+      return;
+    }
     try {
       const sessionId = this.client.session?.getSessionId();
       await this.client.request("/heartbeat", {
@@ -2315,7 +2463,7 @@ var import_RestrictedActions3 = require("~system/RestrictedActions");
 
 // src/ui/ui-renderer.tsx
 var import_react_ecs4 = __toESM(require("@dcl/sdk/react-ecs"));
-var import_ecs2 = require("@dcl/sdk/ecs");
+var import_ecs3 = require("@dcl/sdk/ecs");
 var notificationText = "";
 var notificationVisible = false;
 var notificationEndTime = 0;
@@ -2336,7 +2484,7 @@ function getNotificationState() {
 function initNotificationSystem() {
   if (notificationInitialized) return;
   notificationInitialized = true;
-  import_ecs2.engine.addSystem(() => {
+  import_ecs3.engine.addSystem(() => {
     if (notificationVisible && Date.now() > notificationEndTime) {
       notificationVisible = false;
     }
@@ -3722,7 +3870,7 @@ var AdminPanelUIModule = class {
 };
 
 // src/StaticTVClient.ts
-var import_ecs3 = require("@dcl/sdk/ecs");
+var import_ecs4 = require("@dcl/sdk/ecs");
 var utils = __toESM(require("@dcl-sdk/utils"));
 var DEFAULT_BASE_URL = "https://thestatic.tv/api/v1/dcl";
 var DEFAULT_FALLBACK_VIDEO = "https://media.thestatic.tv/fallback-loop.mp4";
@@ -4011,9 +4159,9 @@ var StaticTVClient = class {
       const fallbackUrl = this.config.fallbackVideoUrl;
       const fallbackDisabled = fallbackUrl === "";
       if (fallbackDisabled) {
-        if (import_ecs3.VideoPlayer.has(screen)) {
+        if (import_ecs4.VideoPlayer.has(screen)) {
           this.log("Stopping video (no fallback)");
-          import_ecs3.VideoPlayer.getMutable(screen).playing = false;
+          import_ecs4.VideoPlayer.getMutable(screen).playing = false;
         }
         this._currentVideoUrl = "";
       } else {
@@ -4036,14 +4184,14 @@ var StaticTVClient = class {
     if (screen === void 0) return;
     this._clearVerificationTimeout();
     this._streamVerified = false;
-    if (import_ecs3.VideoPlayer.has(screen)) {
-      const player = import_ecs3.VideoPlayer.getMutable(screen);
+    if (import_ecs4.VideoPlayer.has(screen)) {
+      const player = import_ecs4.VideoPlayer.getMutable(screen);
       player.src = url;
       player.playing = true;
       player.loop = isFallback;
       player.volume = 1;
     } else {
-      import_ecs3.VideoPlayer.create(screen, {
+      import_ecs4.VideoPlayer.create(screen, {
         src: url,
         playing: true,
         loop: isFallback,
@@ -4065,8 +4213,8 @@ var StaticTVClient = class {
     const screen = this.config.videoScreen;
     if (screen === void 0) return;
     this._videoEventsRegistered = true;
-    import_ecs3.videoEventsSystem.registerVideoEventsEntity(screen, (videoEvent) => {
-      if (videoEvent.state === import_ecs3.VideoState.VS_PLAYING) {
+    import_ecs4.videoEventsSystem.registerVideoEventsEntity(screen, (videoEvent) => {
+      if (videoEvent.state === import_ecs4.VideoState.VS_PLAYING) {
         const timeSinceStart = Date.now() - this._verificationStartTime;
         const MIN_VERIFICATION_DELAY = 2e3;
         if (this._pendingVideoData && !this._streamVerified && timeSinceStart >= MIN_VERIFICATION_DELAY) {
@@ -4075,7 +4223,7 @@ var StaticTVClient = class {
           this.log(`Stream verified: ${this._pendingVideoData.name} (after ${timeSinceStart}ms)`);
         }
       }
-      if (videoEvent.state === import_ecs3.VideoState.VS_ERROR) {
+      if (videoEvent.state === import_ecs4.VideoState.VS_ERROR) {
         if (this._pendingVideoData) {
           this.log(`Stream error for: ${this._pendingVideoData.name}`);
           this._handleStreamOffline();
@@ -4496,8 +4644,11 @@ var StaticTVClient = class {
   StaticTVClient,
   fetchUserData,
   getPlayerDisplayName,
+  getPlayerPosition,
   getPlayerWallet,
+  getSceneBounds,
   hideNotification,
+  isPlayerInBounds,
   setupStaticUI,
   showNotification
 });

package/dist/index.mjs

@@ -203,6 +203,93 @@ function dclClearTimeout(timeoutId) {
   }
 }
 
+// src/utils/bounds.ts
+import { engine as engine2, Transform } from "@dcl/sdk/ecs";
+import { getSceneInformation } from "~system/Runtime";
+var PARCEL_SIZE = 16;
+var cachedBounds = null;
+var boundsInitialized = false;
+var boundsError = false;
+function parseParcel(parcel) {
+  const parts = parcel.split(",");
+  if (parts.length !== 2) return null;
+  const x = parseInt(parts[0], 10);
+  const z = parseInt(parts[1], 10);
+  if (isNaN(x) || isNaN(z)) return null;
+  return { x, z };
+}
+async function getSceneBounds() {
+  if (boundsInitialized && cachedBounds) {
+    return cachedBounds;
+  }
+  if (boundsError) {
+    return null;
+  }
+  try {
+    const sceneInfo = await getSceneInformation({});
+    let parcels = [];
+    let baseParcel;
+    if (sceneInfo.metadataJson) {
+      const metadata = JSON.parse(sceneInfo.metadataJson);
+      parcels = metadata?.scene?.parcels || [];
+      baseParcel = metadata?.scene?.base;
+    }
+    if (parcels.length === 0) {
+      boundsError = true;
+      return null;
+    }
+    const coords = parcels.map(parseParcel).filter((c) => c !== null);
+    if (coords.length === 0) {
+      boundsError = true;
+      return null;
+    }
+    const worldMinX = Math.min(...coords.map((c) => c.x));
+    const worldMaxX = Math.max(...coords.map((c) => c.x));
+    const worldMinZ = Math.min(...coords.map((c) => c.z));
+    const worldMaxZ = Math.max(...coords.map((c) => c.z));
+    const width = (worldMaxX - worldMinX + 1) * PARCEL_SIZE;
+    const depth = (worldMaxZ - worldMinZ + 1) * PARCEL_SIZE;
+    cachedBounds = {
+      minX: 0,
+      maxX: width,
+      minZ: 0,
+      maxZ: depth,
+      width,
+      depth,
+      parcels
+    };
+    boundsInitialized = true;
+    return cachedBounds;
+  } catch (error) {
+    boundsError = true;
+    return null;
+  }
+}
+function isPlayerInBounds(bounds) {
+  try {
+    const transform = Transform.getOrNull(engine2.PlayerEntity);
+    if (!transform) return false;
+    const pos = transform.position;
+    const buffer = 0.5;
+    return pos.x >= bounds.minX - buffer && pos.x <= bounds.maxX + buffer && pos.z >= bounds.minZ - buffer && pos.z <= bounds.maxZ + buffer;
+  } catch {
+    return false;
+  }
+}
+function getPlayerPosition() {
+  try {
+    const transform = Transform.getOrNull(engine2.PlayerEntity);
+    if (!transform) return null;
+    return {
+      x: transform.position.x,
+      y: transform.position.y,
+      z: transform.position.z
+    };
+  } catch {
+    return null;
+  }
+}
+
 // src/modules/session.ts
 function normalizeTier(tier) {
   if (tier === "lite") return "free";
@@ -217,8 +304,26 @@ var SessionModule = class {
     this.heartbeatTimerId = null;
     this.isActive = false;
     this._tier = "free";
+    // Boundary checking - auto-detected from scene parcels
+    this._bounds = null;
+    this._boundsInitialized = false;
+    this._outOfBoundsCount = 0;
     this.client = client;
   }
+  /**
+   * Get the scene bounds (auto-detected from parcels)
+   * Returns null if bounds haven't been initialized yet
+   */
+  get bounds() {
+    return this._bounds;
+  }
+  /**
+   * Check if player is currently within scene bounds
+   */
+  isPlayerInScene() {
+    if (!this._bounds) return true;
+    return isPlayerInBounds(this._bounds);
+  }
   /**
    * Get the API key ID (used as default sceneId for Pro users)
    */
@@ -261,6 +366,25 @@ var SessionModule = class {
     const config = this.client.getConfig();
     return config.player?.name || getPlayerDisplayName();
   }
+  /**
+   * Initialize scene bounds from DCL Runtime
+   * Called once on session start
+   */
+  async initializeBounds() {
+    if (this._boundsInitialized) return;
+    try {
+      this._bounds = await getSceneBounds();
+      this._boundsInitialized = true;
+      if (this._bounds) {
+        this.client.log(`Scene bounds detected: ${this._bounds.width}x${this._bounds.depth}m (${this._bounds.parcels.length} parcels)`);
+      } else {
+        this.client.log("Could not detect scene bounds - boundary checking disabled");
+      }
+    } catch (error) {
+      this.client.log(`Failed to detect scene bounds: ${error}`);
+      this._boundsInitialized = true;
+    }
+  }
   /**
    * Start a new session
    * Called automatically if autoStartSession is true
@@ -270,6 +394,7 @@ var SessionModule = class {
       this.client.log("Session already active");
       return this.sessionId;
     }
+    await this.initializeBounds();
     try {
       const walletAddress = this.getWallet();
       const dclDisplayName = this.getDisplayName();
@@ -311,18 +436,33 @@ var SessionModule = class {
   }
   /**
    * Send a session heartbeat
+   * Always sends heartbeat with inScene status so dashboard can track location
    */
   async sendHeartbeat() {
     if (!this.sessionId || !this.isActive) return;
+    const inScene = this.isPlayerInScene();
+    const pos = getPlayerPosition();
+    if (!inScene && this._outOfBoundsCount === 0) {
+      this.client.log(`Player left scene bounds (${pos?.x.toFixed(1)}, ${pos?.z.toFixed(1)})`);
+    } else if (inScene && this._outOfBoundsCount > 0) {
+      this.client.log(`Player returned to scene after ${this._outOfBoundsCount} heartbeats outside`);
+    }
+    if (!inScene) {
+      this._outOfBoundsCount++;
+    } else {
+      this._outOfBoundsCount = 0;
+    }
     try {
       await this.client.request(this.getEndpoint(), {
         method: "POST",
         body: JSON.stringify({
           action: "heartbeat",
-          sessionId: this.sessionId
+          sessionId: this.sessionId,
+          inScene,
+          position: pos ? { x: Math.round(pos.x), z: Math.round(pos.z) } : null
         })
       });
-      this.client.log("Session heartbeat sent");
+      this.client.log(`Session heartbeat sent (inScene: ${inScene})`);
     } catch (error) {
       this.client.log(`Session heartbeat failed: ${error}`);
     }
@@ -442,9 +582,14 @@ var HeartbeatModule = class {
   }
   /**
    * Send a watching heartbeat (1 heartbeat = 1 minute watched)
+   * Only sends if player is within scene bounds
    */
   async sendHeartbeat() {
     if (!this.currentChannel || !this.isWatching) return;
+    if (this.client.session && !this.client.session.isPlayerInScene()) {
+      this.client.log(`Watch heartbeat skipped - player out of scene bounds`);
+      return;
+    }
     try {
       const sessionId = this.client.session?.getSessionId();
       await this.client.request("/heartbeat", {
@@ -2270,7 +2415,7 @@ import { movePlayerTo, openExternalUrl as openExternalUrl3 } from "~system/Restr
 
 // src/ui/ui-renderer.tsx
 import ReactEcs4, { ReactEcsRenderer, UiEntity as UiEntity4, Label as Label4 } from "@dcl/sdk/react-ecs";
-import { engine as engine2 } from "@dcl/sdk/ecs";
+import { engine as engine3 } from "@dcl/sdk/ecs";
 var notificationText = "";
 var notificationVisible = false;
 var notificationEndTime = 0;
@@ -2291,7 +2436,7 @@ function getNotificationState() {
 function initNotificationSystem() {
   if (notificationInitialized) return;
   notificationInitialized = true;
-  engine2.addSystem(() => {
+  engine3.addSystem(() => {
     if (notificationVisible && Date.now() > notificationEndTime) {
       notificationVisible = false;
     }
@@ -4450,8 +4595,11 @@ export {
   StaticTVClient,
   fetchUserData,
   getPlayerDisplayName,
+  getPlayerPosition,
   getPlayerWallet,
+  getSceneBounds,
   hideNotification,
+  isPlayerInBounds,
   setupStaticUI,
   showNotification
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thestatic-tv/dcl-sdk",
-  "version": "2.5.17",
+  "version": "2.5.18",
   "description": "Connect your Decentraland scene to thestatic.tv - full channel lineup, metrics tracking, and interactions",
   "main": "dist/index.js",
   "module": "dist/index.mjs",