@thestatic-tv/dcl-sdk 2.3.0 → 2.5.0

package/README.md

@@ -5,489 +5,117 @@ Connect your Decentraland scene to [thestatic.tv](https://thestatic.tv) - the de
 [![npm version](https://img.shields.io/npm/v/@thestatic-tv/dcl-sdk?color=00e5e5)](https://www.npmjs.com/package/@thestatic-tv/dcl-sdk)
 [![DCL SDK](https://img.shields.io/badge/DCL%20SDK-7.x-blue)](https://docs.decentraland.org/)
 
-This SDK allows DCL scene builders to:
-- Track visitors to your Decentraland scene
-- Display the full thestatic.tv channel lineup in their scenes
-- Track video watching metrics
-- Enable likes/follows from within DCL
-- Get referral credit for driving traffic to channels
+## Features
 
-## Pricing
+- **Visitor Analytics** - Track visitors and session metrics
+- **Channel Guide** - Display live streams and VODs in your scene
+- **Watch Metrics** - Track video viewing time
+- **Interactions** - Enable likes/follows from within DCL
+- **Built-in UI** - Pre-built Guide and Chat components
+- **Admin Panel** - In-scene controls for Pro tier
 
-| Tier | Price | Features |
-|------|-------|----------|
-| **Free** | $5/mo | Session/visitor tracking only |
-| **Standard** | $10/mo | Free + Guide UI, Chat UI, Heartbeat, Interactions |
-| **Pro** | $15/mo | Standard + Admin Panel (Video tab, Mod tab, Custom scene tabs) |
-
-> **All keys use `dcls_` prefix** - the server determines your subscription level.
->
-> **Free Trial**: All new scene keys include a 7-day free trial!
->
-> **Expiry Warnings**: You'll receive dashboard notifications at 7, 3, and 1 days before your subscription expires.
-
-Get your key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) → DCL Scenes tab.
-
-### Coordinate Locking
-
-When you create a scene key, you'll be asked to confirm your parcel coordinates. **Once confirmed, coordinates are permanently locked** to prevent key reuse across different scenes. This ensures analytics accurately reflect a single scene.
-
-### Key Rotation
-
-If you need to rotate your API key (e.g., if compromised), you can do so from the dashboard without losing your subscription or analytics history. The old key is immediately invalidated.
-
-## Example Scene
-
-Clone our example scene to get started quickly:
-
-```bash
-git clone https://github.com/thestatic-tv/thestatic-dcl-example.git
-cd thestatic-dcl-example
-npm install
-npm start
-```
+## Quick Start
 
-See the [example repo](https://github.com/thestatic-tv/thestatic-dcl-example) for a complete working scene with video player integration.
+1. Get your API key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
 
-## Installation
+2. Install the SDK:
 
 ```bash
 npm install @thestatic-tv/dcl-sdk
 ```
 
-## Quick Start
-
-1. Get your API key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
-
-2. Initialize the client in your scene's `main()` function:
+3. Initialize in your scene:
 
 ```typescript
-import {} from '@dcl/sdk/math'
-import { engine } from '@dcl/sdk/ecs'
 import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
 
 let staticTV: StaticTVClient
 
 export function main() {
   staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_api_key_here'
+    apiKey: 'your_api_key_here'
   })
-  // Session tracking starts automatically!
+  // Session tracking starts automatically
 }
 ```
 
-3. Fetch channels and display them (Full mode only):
-
-```typescript
-// Get all channels
-const channels = await staticTV.guide.getChannels()
+## Example Scene
 
-// Get only live channels
-const liveChannels = await staticTV.guide.getLiveChannels()
+Clone our starter scene to get up and running quickly:
 
-// Get a specific channel
-const channel = await staticTV.guide.getChannel('channel-slug')
+```bash
+git clone https://github.com/thestatic-tv/thestatic-dcl-starter.git
+cd thestatic-dcl-starter
+npm install
+npm start
 ```
 
-4. Track video watching:
+## Basic Usage
 
 ```typescript
-// When user enters video viewing area
-staticTV.heartbeat.startWatching('channel-slug')
+// Get channels (Standard/Pro tier)
+const channels = await staticTV.guide.getChannels()
+const liveChannels = await staticTV.guide.getLiveChannels()
 
-// When user leaves video viewing area
+// Track video watching
+staticTV.heartbeat.startWatching('channel-slug')
 staticTV.heartbeat.stopWatching()
-```
-
-5. Enable interactions:
 
-```typescript
-// Like a channel (requires wallet connection)
+// User interactions (requires wallet)
 await staticTV.interactions.like('channel-slug')
-
-// Follow a channel
 await staticTV.interactions.follow('channel-slug')
-```
 
-6. Cleanup before scene unload:
+// Check your tier
+console.log('Tier:', staticTV.tier) // 'free', 'standard', or 'pro'
 
-```typescript
+// Cleanup
 await staticTV.destroy()
 ```
 
-## Free Tier (Visitor Tracking Only)
-
-If you don't have a channel but want to track visitors to your scene:
-
-1. Get a scene key from [thestatic.tv/dashboard](https://thestatic.tv/dashboard) (DCL Scenes tab)
-
-2. Initialize with your scene key in `main()`:
-
-```typescript
-import {} from '@dcl/sdk/math'
-import { engine } from '@dcl/sdk/ecs'
-import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
-
-let staticTV: StaticTVClient
-
-export function main() {
-  staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_scene_key_here'
-  })
-  // Session tracking starts automatically!
-}
-```
-
-3. Check the current tier:
-
-```typescript
-// Check tier (free, standard, or pro)
-console.log('Current tier:', staticTV.tier)
-
-if (staticTV.isFree) {
-  console.log('Running in free tier - session tracking only')
-}
-
-// guide, heartbeat, and interactions are null in free tier
-if (staticTV.guide) {
-  const channels = await staticTV.guide.getChannels()
-}
-```
-
-## API Reference
-
-### StaticTVClient
-
-Main client class for interacting with thestatic.tv.
-
-#### Constructor Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiKey` | `string` | required | Your API key (all keys use `dcls_` prefix) |
-| `autoStartSession` | `boolean` | `true` | Automatically start session tracking |
-| `sessionHeartbeatInterval` | `number` | `30000` | Session heartbeat interval (ms) |
-| `watchHeartbeatInterval` | `number` | `60000` | Watch heartbeat interval (ms) |
-| `debug` | `boolean` | `false` | Enable debug logging |
-
-#### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `keyType` | `'channel' \| 'scene'` | The detected key type |
-| `tier` | `'free' \| 'standard' \| 'pro'` | Current subscription tier |
-| `isFree` | `boolean` | `true` if free tier (session tracking only) |
-| `hasStandardFeatures` | `boolean` | `true` if standard features enabled |
-| `hasProFeatures` | `boolean` | `true` if pro features enabled |
-| `guide` | `GuideModule \| null` | Guide module (null in free tier) |
-| `session` | `SessionModule` | Session module (always available) |
-| `heartbeat` | `HeartbeatModule \| null` | Heartbeat module (null in free tier) |
-| `interactions` | `InteractionsModule \| null` | Interactions module (null in free tier) |
-| `guideUI` | `GuideUIModule \| null` | Guide UI module (null in free tier) |
-| `chatUI` | `ChatUIModule \| null` | Chat UI module (null in free tier) |
-| `adminPanel` | `AdminPanelUIModule \| null` | Admin panel (null until enableProFeatures() called) |
-| `isLite` | `boolean` | **Deprecated**: Use `isFree` instead |
-
-#### Methods
-
-| Method | Description |
-|--------|-------------|
-| `enableProFeatures(config)` | Enable Pro tier admin panel |
-| `registerSceneTab(tab)` | Add custom scene tab (Pro tier) |
-| `destroy()` | Cleanup before scene unload |
-
-### Guide Module (Standard/Pro Tier)
-
-```typescript
-staticTV.guide.getChannels()       // Get all channels (cached 30s)
-staticTV.guide.getLiveChannels()   // Get only live channels
-staticTV.guide.getChannel(slug)    // Get a specific channel
-staticTV.guide.getVods()           // Get VODs
-staticTV.guide.clearCache()        // Clear the channel cache
-```
-
-### Session Module
-
-Session tracking starts automatically by default.
-
-```typescript
-staticTV.session.startSession()    // Manually start session
-staticTV.session.endSession()      // End session
-staticTV.session.getSessionId()    // Get current session ID
-staticTV.session.isSessionActive() // Check if session is active
-
-// Get scene stats (visitors, sessions, etc.)
-const stats = await staticTV.session.getStats()
-if (stats) {
-  console.log('Total sessions today:', stats.totalSessions)
-  console.log('Unique visitors:', stats.uniqueVisitors)
-  console.log('Total minutes watched:', stats.totalMinutes)
-  console.log('You are visitor #', stats.visitorNumber)
-}
-```
-
-### Heartbeat Module (Standard/Pro Tier)
-
-Track video watching. Each heartbeat represents 1 minute watched.
-
-```typescript
-staticTV.heartbeat.startWatching(channelSlug)  // Start tracking
-staticTV.heartbeat.stopWatching()               // Stop tracking
-staticTV.heartbeat.getCurrentChannel()          // Get currently watched channel
-staticTV.heartbeat.isCurrentlyWatching()        // Check if watching
-```
-
-### Interactions Module (Standard/Pro Tier)
+## Built-in UI Components
 
-Like and follow channels. Requires wallet connection.
+The SDK includes pre-built UI for channel browsing and chat:
 
 ```typescript
-staticTV.interactions.like(channelSlug)   // Like a channel
-staticTV.interactions.follow(channelSlug) // Follow a channel
-```
-
-### Guide UI Module (Standard/Pro Tier)
-
-Built-in channel browser UI. You provide a callback to handle video selection.
-
-```typescript
-let staticTV: StaticTVClient
-
-export function main() {
-  staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_api_key',
-    guideUI: {
-      onVideoSelect: (video) => {
-        // Handle video playback in your scene
-        console.log('Playing:', video.name, video.src)
-      }
+staticTV = new StaticTVClient({
+  apiKey: 'your_api_key',
+  guideUI: {
+    onVideoSelect: (video) => {
+      // Handle video playback
+      console.log('Playing:', video.name)
     }
-  })
+  },
+  chatUI: {
+    position: 'right'
+  }
+})
 
-  // Initialize the UI (call once after client is created)
-  staticTV.guideUI.init()
-}
+// Initialize UI components
+staticTV.guideUI.init()
+staticTV.chatUI.init()
 
-// Show/hide the guide
-staticTV.guideUI.show()
-staticTV.guideUI.hide()
+// Show/hide
 staticTV.guideUI.toggle()
-
-// Check visibility
-if (staticTV.guideUI.isVisible) { ... }
-
-// Update "PLAYING" indicator
-staticTV.guideUI.currentVideoId = 'video-id'
-
-// Refresh data
-await staticTV.guideUI.refresh()
-```
-
-### Chat UI Module (Standard/Pro Tier)
-
-Real-time chat with Firebase authentication.
-
-```typescript
-let staticTV: StaticTVClient
-
-export function main() {
-  staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_api_key',
-    chatUI: {
-      position: 'right',  // 'left', 'center', or 'right'
-      fontScale: 1.0
-    }
-  })
-
-  // Initialize the chat (call once after client is created)
-  staticTV.chatUI.init()
-}
-
-// Show/hide the chat
-staticTV.chatUI.show()
-staticTV.chatUI.hide()
 staticTV.chatUI.toggle()
-
-// Check visibility
-if (staticTV.chatUI.isVisible) { ... }
-
-// Get unread message count (for badge display)
-const unread = staticTV.chatUI.unreadCount
-
-// Switch channels
-staticTV.chatUI.setChannel('channel-slug')
-```
-
-### Admin Panel Module (Pro Tier)
-
-In-scene admin panel with Video and Mod tabs. Allows scene owners/admins to:
-- Control live streaming (start/stop, rotate keys)
-- Play videos from URL or predefined slots
-- Manage scene admins and banned wallets
-- Send broadcast messages to all players
-
-```typescript
-import { StaticTVClient } from '@thestatic-tv/dcl-sdk'
-import ReactEcs, { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
-
-let staticTV: StaticTVClient
-
-export function main() {
-  staticTV = new StaticTVClient({
-    apiKey: 'dcls_your_api_key'
-  })
-
-  // Enable admin panel (Pro tier)
-  staticTV.enableProFeatures({
-    // sceneId is optional - defaults to your API key ID
-    title: 'MY SCENE ADMIN',       // Panel header title
-    onVideoPlay: (url) => {
-      // Handle video playback in your scene
-      videoPlayer.play(url)
-    },
-    onVideoStop: () => {
-      videoPlayer.stop()
-    },
-    onVideoSlotPlay: (slot) => {
-      // Play a predefined video slot (slot1-slot5)
-      fetchAndPlaySlot(slot)
-    },
-    onBroadcast: (text) => {
-      // Show notification to all players
-      showNotification(text)
-    },
-    onCommand: (type, payload) => {
-      // Handle custom commands (kickAll, kickBanned, etc.)
-      handleCommand(type, payload)
-    }
-  })
-}
-
-// Render the admin panel
-ReactEcsRenderer.setUiRenderer(() => {
-  return staticTV.adminPanel?.getComponent()
-})
-
-// Toggle panel visibility
-staticTV.adminPanel.toggle()
-
-// Check if user has admin access
-if (staticTV.adminPanel.hasAccess) { ... }
 ```
 
-#### Admin Panel Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `sceneId` | `string` | API key ID | Scene ID for API calls (optional - defaults to your API key ID) |
-| `title` | `string` | `'ADMIN PANEL'` | Header title |
-| `headerColor` | `{r,g,b,a}` | red | Header background color |
-| `showVideoTab` | `boolean` | `true` | Show Video tab |
-| `showModTab` | `boolean` | `true` | Show Mod tab (owners only) |
-| `onVideoPlay` | `(url) => void` | - | Called when video should play |
-| `onVideoStop` | `() => void` | - | Called when video should stop |
-| `onVideoSlotPlay` | `(slot) => void` | - | Called when slot is selected |
-| `onBroadcast` | `(text) => void` | - | Called for broadcast messages |
-| `onCommand` | `(type, payload) => void` | - | Called for custom commands |
-| `footerLink` | `string` | scene page | Link shown in footer |
-| `debug` | `boolean` | `false` | Enable debug logging |
-
-### Custom Scene Tabs (Pro Tier)
+## Pricing & Tiers
 
-Add your own scene-specific control tabs to the admin panel:
+See [thestatic.tv/info](https://thestatic.tv/info) for current pricing and tier features.
 
-```typescript
-import ReactEcs, { UiEntity, Button, Label } from '@dcl/sdk/react-ecs'
-
-// Enable pro features first
-staticTV.enableProFeatures({ sceneId: 'my-scene', ... })
-
-// Register custom tabs
-staticTV.registerSceneTab({
-  label: 'LIGHTS',
-  id: 'lights',
-  render: () => (
-    <UiEntity uiTransform={{ flexDirection: 'column', padding: 8 }}>
-      <Label value="Light Controls" fontSize={14} />
-      <Button value="Disco Mode" onMouseDown={() => setDiscoLights()} />
-      <Button value="Ambient" onMouseDown={() => setAmbientLights()} />
-      <Button value="Off" onMouseDown={() => turnOffLights()} />
-    </UiEntity>
-  )
-})
-
-staticTV.registerSceneTab({
-  label: 'DOORS',
-  id: 'doors',
-  render: () => <MyDoorsControls />
-})
-```
+All new keys include a **7-day free trial**.
 
-Custom tabs appear before the Video and Mod tabs in the tab bar.
+## Documentation
 
-### Rendering UI Components
+Full API reference and Pro tier features (Admin Panel, Custom Tabs) available at:
 
-The UI modules provide `getComponent()` methods that return React-ECS elements. Add the renderer **outside** your `main()` function:
-
-```typescript
-import ReactEcs, { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs'
-
-// Outside main() - required by DCL
-ReactEcsRenderer.setUiRenderer(() => {
-  if (!staticTV) return null
-  return ReactEcs.createElement(UiEntity, {
-    uiTransform: { width: '100%', height: '100%', positionType: 'absolute' },
-    children: [
-      staticTV.guideUI?.getComponent(),
-      staticTV.chatUI?.getComponent()
-    ].filter(Boolean)
-  })
-})
-```
-
-## Metrics Attribution
-
-This SDK implements dual attribution:
-
-- **Watched Channel**: Gets view metrics (minutes watched, likes, follows)
-- **Scene Owner**: Gets referral metrics (unique visitors, traffic driven)
-
-Your channel (linked to your API key) receives credit for all traffic your scene drives to thestatic.tv channels.
-
-## Types
-
-```typescript
-interface Channel {
-  id: string
-  slug: string
-  name: string
-  streamUrl: string
-  isLive: boolean
-  currentViewers: number
-  poster: string | null
-  logo: string | null
-  description: string
-}
-
-interface Vod {
-  id: string
-  title: string
-  url: string
-  thumbnail: string | null
-  channelId: string
-}
-```
-
-## Requirements
-
-- Decentraland SDK 7.0.0 or higher
-- API key from thestatic.tv
+- **Docs**: [thestatic.tv/info](https://thestatic.tv/info)
+- **Examples**: [github.com/thestatic-tv/thestatic-dcl-starter](https://github.com/thestatic-tv/thestatic-dcl-starter)
 
 ## Support
 
-- Documentation: [thestatic.tv/info](https://thestatic.tv/info)
-- Issues: [GitHub Issues](https://github.com/thestatic-tv/dcl-sdk/issues)
 - Discord: [thestatic.tv Discord](https://discord.gg/thestatic)
+- Issues: [GitHub Issues](https://github.com/thestatic-tv/dcl-sdk/issues)
 
 ## License
 

package/dist/index.d.mts

@@ -45,6 +45,12 @@ interface StaticTVConfig {
      * ```
      */
     videoScreen?: Entity;
+    /**
+     * Fallback video URL to play when no stream is active or stopVideo() is called.
+     * Prevents "broken screen" appearance. Set to empty string to disable.
+     * @default 'https://media.thestatic.tv/fallback-loop.mp4'
+     */
+    fallbackVideoUrl?: string;
     /**
      * Scene ID for Admin Panel API calls.
      * Optional - defaults to API key ID if not provided.
@@ -863,6 +869,9 @@ declare class StaticTVClient {
     private _standardFeaturesEnabled;
     private _proFeaturesEnabled;
     private _pendingProConfig;
+    private _featuresReadyPromise;
+    private _featuresReadyResolve;
+    private _featuresResolved;
     /** Guide module - fetch channel lineup (standard/pro tier) */
     guide: GuideModule | null;
     /** Session module - track visitor sessions (all tiers, null when disabled) */
@@ -933,6 +942,33 @@ declare class StaticTVClient {
      * @deprecated Use `isFree` instead. Kept for backward compatibility.
      */
     get isLite(): boolean;
+    /**
+     * Wait for tier confirmation from the server.
+     * Resolves when the SDK knows which features are available.
+     *
+     * Use this instead of polling `isLite` or `isFree` in a while loop.
+     *
+     * @returns Promise that resolves with the confirmed tier ('free', 'standard', or 'pro')
+     *
+     * @example
+     * ```typescript
+     * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+     *
+     * // Wait for tier to be confirmed
+     * const tier = await staticTV.onFeaturesReady()
+     *
+     * // Now modules are guaranteed to be initialized (or confirmed unavailable)
+     * if (staticTV.guideUI) {
+     *   await staticTV.guideUI.init()
+     *   console.log('Guide ready!')
+     * }
+     *
+     * if (tier === 'free') {
+     *   console.log('Upgrade at thestatic.tv for Guide & Chat!')
+     * }
+     * ```
+     */
+    onFeaturesReady(): Promise<SDKTier>;
     /**
      * Make an authenticated API request
      * @internal
@@ -968,9 +1004,15 @@ declare class StaticTVClient {
     playVideo(url: string): void;
     /**
      * Stop video playback on the configured videoScreen entity.
+     * If fallbackVideoUrl is configured (default), plays the fallback loop.
      * Called by Admin Panel.
      */
     stopVideo(): void;
+    /**
+     * Internal video player - handles both regular videos and fallback
+     * @internal
+     */
+    private _playVideoInternal;
     /**
      * Get the currently playing video URL
      */
@@ -995,6 +1037,11 @@ declare class StaticTVClient {
      * @internal
      */
     private _initProModules;
+    /**
+     * Resolve the features ready promise (only once)
+     * @internal
+     */
+    private _resolveFeaturesReady;
     /**
      * Called by SessionModule when server returns the tier
      * Enables modules based on tier level

package/dist/index.d.ts

@@ -45,6 +45,12 @@ interface StaticTVConfig {
      * ```
      */
     videoScreen?: Entity;
+    /**
+     * Fallback video URL to play when no stream is active or stopVideo() is called.
+     * Prevents "broken screen" appearance. Set to empty string to disable.
+     * @default 'https://media.thestatic.tv/fallback-loop.mp4'
+     */
+    fallbackVideoUrl?: string;
     /**
      * Scene ID for Admin Panel API calls.
      * Optional - defaults to API key ID if not provided.
@@ -863,6 +869,9 @@ declare class StaticTVClient {
     private _standardFeaturesEnabled;
     private _proFeaturesEnabled;
     private _pendingProConfig;
+    private _featuresReadyPromise;
+    private _featuresReadyResolve;
+    private _featuresResolved;
     /** Guide module - fetch channel lineup (standard/pro tier) */
     guide: GuideModule | null;
     /** Session module - track visitor sessions (all tiers, null when disabled) */
@@ -933,6 +942,33 @@ declare class StaticTVClient {
      * @deprecated Use `isFree` instead. Kept for backward compatibility.
      */
     get isLite(): boolean;
+    /**
+     * Wait for tier confirmation from the server.
+     * Resolves when the SDK knows which features are available.
+     *
+     * Use this instead of polling `isLite` or `isFree` in a while loop.
+     *
+     * @returns Promise that resolves with the confirmed tier ('free', 'standard', or 'pro')
+     *
+     * @example
+     * ```typescript
+     * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+     *
+     * // Wait for tier to be confirmed
+     * const tier = await staticTV.onFeaturesReady()
+     *
+     * // Now modules are guaranteed to be initialized (or confirmed unavailable)
+     * if (staticTV.guideUI) {
+     *   await staticTV.guideUI.init()
+     *   console.log('Guide ready!')
+     * }
+     *
+     * if (tier === 'free') {
+     *   console.log('Upgrade at thestatic.tv for Guide & Chat!')
+     * }
+     * ```
+     */
+    onFeaturesReady(): Promise<SDKTier>;
     /**
      * Make an authenticated API request
      * @internal
@@ -968,9 +1004,15 @@ declare class StaticTVClient {
     playVideo(url: string): void;
     /**
      * Stop video playback on the configured videoScreen entity.
+     * If fallbackVideoUrl is configured (default), plays the fallback loop.
      * Called by Admin Panel.
      */
     stopVideo(): void;
+    /**
+     * Internal video player - handles both regular videos and fallback
+     * @internal
+     */
+    private _playVideoInternal;
     /**
      * Get the currently playing video URL
      */
@@ -995,6 +1037,11 @@ declare class StaticTVClient {
      * @internal
      */
     private _initProModules;
+    /**
+     * Resolve the features ready promise (only once)
+     * @internal
+     */
+    private _resolveFeaturesReady;
     /**
      * Called by SessionModule when server returns the tier
      * Enables modules based on tier level

package/dist/index.js

@@ -2540,7 +2540,7 @@ var AdminPanelUIModule = class {
         {
           uiTransform: { height: this.s(24) },
           uiBackground: { color: import_math5.Color4.create(0, 0, 0, 0) },
-          value: "Edit slots at thestatic.tv \u2192",
+          value: "Edit slots at thestatic.tv",
           fontSize: t.labelSmall,
           color: C.cyan,
           onMouseDown: () => (0, import_RestrictedActions3.openExternalUrl)({ url: this.config.footerLink || `https://thestatic.tv/scene/${this.config.sceneId}` })
@@ -2695,7 +2695,7 @@ var AdminPanelUIModule = class {
         {
           uiTransform: { height: this.s(24) },
           uiBackground: { color: import_math5.Color4.create(0, 0, 0, 0) },
-          value: "Manage at thestatic.tv \u2192",
+          value: "Manage at thestatic.tv",
           fontSize: t.labelSmall,
           color: C.cyan,
           onMouseDown: () => (0, import_RestrictedActions3.openExternalUrl)({ url: this.config.footerLink || `https://thestatic.tv/scene/${this.config.sceneId}` })
@@ -2821,7 +2821,7 @@ var AdminPanelUIModule = class {
               {
                 uiTransform: { height: this.s(24) },
                 uiBackground: { color: import_math5.Color4.create(0, 0, 0, 0) },
-                value: `thestatic.tv/scene/${this.config.sceneId} \u2192`,
+                value: `thestatic.tv/scene/${this.config.sceneId}`,
                 fontSize: t.labelSmall,
                 color: C.cyan,
                 onMouseDown: () => (0, import_RestrictedActions3.openExternalUrl)({ url: this.config.footerLink || `https://thestatic.tv/scene/${this.config.sceneId}` })
@@ -3494,6 +3494,7 @@ function setupStaticUI(client) {
 // src/StaticTVClient.ts
 var import_ecs3 = require("@dcl/sdk/ecs");
 var DEFAULT_BASE_URL = "https://thestatic.tv/api/v1/dcl";
+var DEFAULT_FALLBACK_VIDEO = "https://media.thestatic.tv/fallback-loop.mp4";
 var KEY_TYPE_CHANNEL = "channel";
 var KEY_TYPE_SCENE = "scene";
 var StaticTVClient = class {
@@ -3535,6 +3536,7 @@ var StaticTVClient = class {
     this._standardFeaturesEnabled = false;
     this._proFeaturesEnabled = false;
     this._pendingProConfig = null;
+    this._featuresResolved = false;
     /** Guide module - fetch channel lineup (standard/pro tier) */
     this.guide = null;
     /** Session module - track visitor sessions (all tiers, null when disabled) */
@@ -3555,6 +3557,9 @@ var StaticTVClient = class {
     // --- VIDEO PLAYBACK (Internal handler for videoScreen) ---
     // =============================================================================
     this._currentVideoUrl = "";
+    this._featuresReadyPromise = new Promise((resolve) => {
+      this._featuresReadyResolve = resolve;
+    });
     this.config = {
       autoStartSession: true,
       sessionHeartbeatInterval: 3e4,
@@ -3572,6 +3577,7 @@ var StaticTVClient = class {
       this.interactions = null;
       this.guideUI = null;
       this.chatUI = null;
+      this._resolveFeaturesReady("free");
       return;
     }
     if (config.apiKey.startsWith("dclk_")) {
@@ -3582,12 +3588,14 @@ var StaticTVClient = class {
       console.warn("[TheStatic] Invalid API key format - get your key at thestatic.tv/dashboard");
       this._disabled = true;
       this._keyType = null;
+      this._resolveFeaturesReady("free");
       return;
     }
     this.session = new SessionModule(this);
     if (this._keyType === KEY_TYPE_CHANNEL) {
       this._tier = "standard";
       this._initStandardModules();
+      this._resolveFeaturesReady("standard");
     }
     if (this.config.autoStartSession) {
       fetchUserData().then(() => {
@@ -3638,6 +3646,35 @@ var StaticTVClient = class {
   get isLite() {
     return this.isFree;
   }
+  /**
+   * Wait for tier confirmation from the server.
+   * Resolves when the SDK knows which features are available.
+   *
+   * Use this instead of polling `isLite` or `isFree` in a while loop.
+   *
+   * @returns Promise that resolves with the confirmed tier ('free', 'standard', or 'pro')
+   *
+   * @example
+   * ```typescript
+   * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+   *
+   * // Wait for tier to be confirmed
+   * const tier = await staticTV.onFeaturesReady()
+   *
+   * // Now modules are guaranteed to be initialized (or confirmed unavailable)
+   * if (staticTV.guideUI) {
+   *   await staticTV.guideUI.init()
+   *   console.log('Guide ready!')
+   * }
+   *
+   * if (tier === 'free') {
+   *   console.log('Upgrade at thestatic.tv for Guide & Chat!')
+   * }
+   * ```
+   */
+  async onFeaturesReady() {
+    return this._featuresReadyPromise;
+  }
   /**
    * Make an authenticated API request
    * @internal
@@ -3695,17 +3732,7 @@ var StaticTVClient = class {
     if (screen !== void 0) {
       this.log(`Playing video: ${url}`);
       this._currentVideoUrl = url;
-      if (import_ecs3.VideoPlayer.has(screen)) {
-        import_ecs3.VideoPlayer.deleteFrom(screen);
-      }
-      import_ecs3.VideoPlayer.create(screen, {
-        src: url,
-        playing: true,
-        volume: 1
-      });
-      import_ecs3.Material.setBasicMaterial(screen, {
-        texture: import_ecs3.Material.Texture.Video({ videoPlayerEntity: screen })
-      });
+      this._playVideoInternal(url, false);
       if (this.guideUI) {
         const videos = this.guideUI.getVideos();
         const video = videos.find((v) => v.src === url);
@@ -3720,22 +3747,55 @@ var StaticTVClient = class {
   }
   /**
    * Stop video playback on the configured videoScreen entity.
+   * If fallbackVideoUrl is configured (default), plays the fallback loop.
    * Called by Admin Panel.
    */
   stopVideo() {
     const screen = this.config.videoScreen;
-    if (screen !== void 0 && import_ecs3.VideoPlayer.has(screen)) {
-      this.log("Stopping video");
-      import_ecs3.VideoPlayer.getMutable(screen).playing = false;
-      this._currentVideoUrl = "";
+    if (screen !== void 0) {
       if (this.guideUI) {
         this.guideUI.currentVideoId = null;
       }
+      const fallbackUrl = this.config.fallbackVideoUrl;
+      const fallbackDisabled = fallbackUrl === "";
+      if (fallbackDisabled) {
+        if (import_ecs3.VideoPlayer.has(screen)) {
+          this.log("Stopping video (no fallback)");
+          import_ecs3.VideoPlayer.getMutable(screen).playing = false;
+        }
+        this._currentVideoUrl = "";
+      } else {
+        const url = fallbackUrl || DEFAULT_FALLBACK_VIDEO;
+        this.log(`Playing fallback: ${url}`);
+        this._currentVideoUrl = "";
+        this._playVideoInternal(url, true);
+      }
     }
     if (this.config.onVideoStop) {
       this.config.onVideoStop();
     }
   }
+  /**
+   * Internal video player - handles both regular videos and fallback
+   * @internal
+   */
+  _playVideoInternal(url, isFallback = false) {
+    const screen = this.config.videoScreen;
+    if (screen === void 0) return;
+    if (import_ecs3.VideoPlayer.has(screen)) {
+      import_ecs3.VideoPlayer.deleteFrom(screen);
+    }
+    import_ecs3.VideoPlayer.create(screen, {
+      src: url,
+      playing: true,
+      loop: isFallback,
+      // Loop fallback videos
+      volume: 1
+    });
+    import_ecs3.Material.setBasicMaterial(screen, {
+      texture: import_ecs3.Material.Texture.Video({ videoPlayerEntity: screen })
+    });
+  }
   /**
    * Get the currently playing video URL
    */
@@ -3818,6 +3878,16 @@ var StaticTVClient = class {
     });
     this.log(`Pro features enabled (admin panel) - sceneId: ${sceneId}`);
   }
+  /**
+   * Resolve the features ready promise (only once)
+   * @internal
+   */
+  _resolveFeaturesReady(tier) {
+    if (!this._featuresResolved) {
+      this._featuresResolved = true;
+      this._featuresReadyResolve(tier);
+    }
+  }
   /**
    * Called by SessionModule when server returns the tier
    * Enables modules based on tier level
@@ -3839,6 +3909,7 @@ var StaticTVClient = class {
         this.log("Pro tier detected but no video config - call enableProFeatures() or set videoScreen to enable admin panel");
       }
     }
+    this._resolveFeaturesReady(tier);
   }
   /**
    * @deprecated Use `_enableFeaturesForTier` instead

package/dist/index.mjs

@@ -2497,7 +2497,7 @@ var AdminPanelUIModule = class {
         {
           uiTransform: { height: this.s(24) },
           uiBackground: { color: Color45.create(0, 0, 0, 0) },
-          value: "Edit slots at thestatic.tv \u2192",
+          value: "Edit slots at thestatic.tv",
           fontSize: t.labelSmall,
           color: C.cyan,
           onMouseDown: () => openExternalUrl3({ url: this.config.footerLink || `https://thestatic.tv/scene/${this.config.sceneId}` })
@@ -2652,7 +2652,7 @@ var AdminPanelUIModule = class {
         {
           uiTransform: { height: this.s(24) },
           uiBackground: { color: Color45.create(0, 0, 0, 0) },
-          value: "Manage at thestatic.tv \u2192",
+          value: "Manage at thestatic.tv",
           fontSize: t.labelSmall,
           color: C.cyan,
           onMouseDown: () => openExternalUrl3({ url: this.config.footerLink || `https://thestatic.tv/scene/${this.config.sceneId}` })
@@ -2778,7 +2778,7 @@ var AdminPanelUIModule = class {
               {
                 uiTransform: { height: this.s(24) },
                 uiBackground: { color: Color45.create(0, 0, 0, 0) },
-                value: `thestatic.tv/scene/${this.config.sceneId} \u2192`,
+                value: `thestatic.tv/scene/${this.config.sceneId}`,
                 fontSize: t.labelSmall,
                 color: C.cyan,
                 onMouseDown: () => openExternalUrl3({ url: this.config.footerLink || `https://thestatic.tv/scene/${this.config.sceneId}` })
@@ -3451,6 +3451,7 @@ function setupStaticUI(client) {
 // src/StaticTVClient.ts
 import { VideoPlayer, Material } from "@dcl/sdk/ecs";
 var DEFAULT_BASE_URL = "https://thestatic.tv/api/v1/dcl";
+var DEFAULT_FALLBACK_VIDEO = "https://media.thestatic.tv/fallback-loop.mp4";
 var KEY_TYPE_CHANNEL = "channel";
 var KEY_TYPE_SCENE = "scene";
 var StaticTVClient = class {
@@ -3492,6 +3493,7 @@ var StaticTVClient = class {
     this._standardFeaturesEnabled = false;
     this._proFeaturesEnabled = false;
     this._pendingProConfig = null;
+    this._featuresResolved = false;
     /** Guide module - fetch channel lineup (standard/pro tier) */
     this.guide = null;
     /** Session module - track visitor sessions (all tiers, null when disabled) */
@@ -3512,6 +3514,9 @@ var StaticTVClient = class {
     // --- VIDEO PLAYBACK (Internal handler for videoScreen) ---
     // =============================================================================
     this._currentVideoUrl = "";
+    this._featuresReadyPromise = new Promise((resolve) => {
+      this._featuresReadyResolve = resolve;
+    });
     this.config = {
       autoStartSession: true,
       sessionHeartbeatInterval: 3e4,
@@ -3529,6 +3534,7 @@ var StaticTVClient = class {
       this.interactions = null;
       this.guideUI = null;
       this.chatUI = null;
+      this._resolveFeaturesReady("free");
       return;
     }
     if (config.apiKey.startsWith("dclk_")) {
@@ -3539,12 +3545,14 @@ var StaticTVClient = class {
       console.warn("[TheStatic] Invalid API key format - get your key at thestatic.tv/dashboard");
       this._disabled = true;
       this._keyType = null;
+      this._resolveFeaturesReady("free");
       return;
     }
     this.session = new SessionModule(this);
     if (this._keyType === KEY_TYPE_CHANNEL) {
       this._tier = "standard";
       this._initStandardModules();
+      this._resolveFeaturesReady("standard");
     }
     if (this.config.autoStartSession) {
       fetchUserData().then(() => {
@@ -3595,6 +3603,35 @@ var StaticTVClient = class {
   get isLite() {
     return this.isFree;
   }
+  /**
+   * Wait for tier confirmation from the server.
+   * Resolves when the SDK knows which features are available.
+   *
+   * Use this instead of polling `isLite` or `isFree` in a while loop.
+   *
+   * @returns Promise that resolves with the confirmed tier ('free', 'standard', or 'pro')
+   *
+   * @example
+   * ```typescript
+   * const staticTV = new StaticTVClient({ apiKey: 'dcls_...' })
+   *
+   * // Wait for tier to be confirmed
+   * const tier = await staticTV.onFeaturesReady()
+   *
+   * // Now modules are guaranteed to be initialized (or confirmed unavailable)
+   * if (staticTV.guideUI) {
+   *   await staticTV.guideUI.init()
+   *   console.log('Guide ready!')
+   * }
+   *
+   * if (tier === 'free') {
+   *   console.log('Upgrade at thestatic.tv for Guide & Chat!')
+   * }
+   * ```
+   */
+  async onFeaturesReady() {
+    return this._featuresReadyPromise;
+  }
   /**
    * Make an authenticated API request
    * @internal
@@ -3652,17 +3689,7 @@ var StaticTVClient = class {
     if (screen !== void 0) {
       this.log(`Playing video: ${url}`);
       this._currentVideoUrl = url;
-      if (VideoPlayer.has(screen)) {
-        VideoPlayer.deleteFrom(screen);
-      }
-      VideoPlayer.create(screen, {
-        src: url,
-        playing: true,
-        volume: 1
-      });
-      Material.setBasicMaterial(screen, {
-        texture: Material.Texture.Video({ videoPlayerEntity: screen })
-      });
+      this._playVideoInternal(url, false);
       if (this.guideUI) {
         const videos = this.guideUI.getVideos();
         const video = videos.find((v) => v.src === url);
@@ -3677,22 +3704,55 @@ var StaticTVClient = class {
   }
   /**
    * Stop video playback on the configured videoScreen entity.
+   * If fallbackVideoUrl is configured (default), plays the fallback loop.
    * Called by Admin Panel.
    */
   stopVideo() {
     const screen = this.config.videoScreen;
-    if (screen !== void 0 && VideoPlayer.has(screen)) {
-      this.log("Stopping video");
-      VideoPlayer.getMutable(screen).playing = false;
-      this._currentVideoUrl = "";
+    if (screen !== void 0) {
       if (this.guideUI) {
         this.guideUI.currentVideoId = null;
       }
+      const fallbackUrl = this.config.fallbackVideoUrl;
+      const fallbackDisabled = fallbackUrl === "";
+      if (fallbackDisabled) {
+        if (VideoPlayer.has(screen)) {
+          this.log("Stopping video (no fallback)");
+          VideoPlayer.getMutable(screen).playing = false;
+        }
+        this._currentVideoUrl = "";
+      } else {
+        const url = fallbackUrl || DEFAULT_FALLBACK_VIDEO;
+        this.log(`Playing fallback: ${url}`);
+        this._currentVideoUrl = "";
+        this._playVideoInternal(url, true);
+      }
     }
     if (this.config.onVideoStop) {
       this.config.onVideoStop();
     }
   }
+  /**
+   * Internal video player - handles both regular videos and fallback
+   * @internal
+   */
+  _playVideoInternal(url, isFallback = false) {
+    const screen = this.config.videoScreen;
+    if (screen === void 0) return;
+    if (VideoPlayer.has(screen)) {
+      VideoPlayer.deleteFrom(screen);
+    }
+    VideoPlayer.create(screen, {
+      src: url,
+      playing: true,
+      loop: isFallback,
+      // Loop fallback videos
+      volume: 1
+    });
+    Material.setBasicMaterial(screen, {
+      texture: Material.Texture.Video({ videoPlayerEntity: screen })
+    });
+  }
   /**
    * Get the currently playing video URL
    */
@@ -3775,6 +3835,16 @@ var StaticTVClient = class {
     });
     this.log(`Pro features enabled (admin panel) - sceneId: ${sceneId}`);
   }
+  /**
+   * Resolve the features ready promise (only once)
+   * @internal
+   */
+  _resolveFeaturesReady(tier) {
+    if (!this._featuresResolved) {
+      this._featuresResolved = true;
+      this._featuresReadyResolve(tier);
+    }
+  }
   /**
    * Called by SessionModule when server returns the tier
    * Enables modules based on tier level
@@ -3796,6 +3866,7 @@ var StaticTVClient = class {
         this.log("Pro tier detected but no video config - call enableProFeatures() or set videoScreen to enable admin panel");
       }
     }
+    this._resolveFeaturesReady(tier);
   }
   /**
    * @deprecated Use `_enableFeaturesForTier` instead

package/package.json

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