@applicaster/zapp-react-native-ui-components 15.0.0-rc.13 → 15.0.0-rc.131

package/Components/ScreenRevealManager/withScreenRevealManager.tsx

@@ -1,8 +1,8 @@
 import * as React from "react";
-import { Animated } from "react-native";
+import { Animated, StyleSheet } from "react-native";
 import { isFirstComponentScreenPicker } from "@applicaster/zapp-react-native-utils/componentsUtils";
-import { platformSelect } from "@applicaster/zapp-react-native-utils/reactUtils";
 import { useRefWithInitialValue } from "@applicaster/zapp-react-native-utils/reactHooks/state/useRefWithInitialValue";
+import { useTheme } from "@applicaster/zapp-react-native-utils/theme";
 
 import { ScreenRevealManager } from "./ScreenRevealManager";
 import {
@@ -10,16 +10,14 @@ import {
   emitScreenRevealManagerIsNotReadyToShow,
 } from "./utils";
 
-const flex = platformSelect({
-  tvos: 1,
-  android_tv: 1,
-  web: undefined,
-  samsung_tv: undefined,
-  lg_tv: undefined,
-  default: undefined,
+const styles = StyleSheet.create({
+  container: {
+    ...StyleSheet.absoluteFillObject,
+    position: "absolute",
+  },
 });
 
-export const TIMEOUT = 500; // 500 ms
+export const TIMEOUT = 300; // 300 ms
 
 const HIDDEN = 0; // opacity = 0
 
@@ -33,37 +31,48 @@ export const withScreenRevealManager = (Component) => {
   return function WithScreenRevealManager(props: Props) {
     const { componentsToRender } = props;
 
-    const [isReadyToShow, setIsReadyToShow] = React.useState(false);
+    const [isContentReadyToBeShown, setIsContentReadyToBeShown] =
+      React.useState(false);
 
-    const handleSetIsReadyToShow = React.useCallback(() => {
-      setIsReadyToShow(true);
+    const [isShowOverlay, setIsShowOverlay] = React.useState(true);
+
+    const theme = useTheme<BaseThemePropertiesTV>();
+
+    const handleSetIsContentReadyToBeShown = React.useCallback(() => {
+      setIsContentReadyToBeShown(true);
     }, []);
 
     const managerRef = useRefWithInitialValue<ScreenRevealManager>(
-      () => new ScreenRevealManager(componentsToRender, handleSetIsReadyToShow)
+      () =>
+        new ScreenRevealManager(
+          componentsToRender,
+          handleSetIsContentReadyToBeShown
+        )
     );
 
     const opacityRef = useRefWithInitialValue<Animated.Value>(
-      () => new Animated.Value(HIDDEN)
+      () => new Animated.Value(SHOWN)
     );
 
     React.useEffect(() => {
-      if (!isReadyToShow) {
+      if (!isContentReadyToBeShown) {
         emitScreenRevealManagerIsNotReadyToShow();
       } else {
         emitScreenRevealManagerIsReadyToShow();
       }
-    }, [isReadyToShow]);
+    }, [isContentReadyToBeShown]);
 
     React.useEffect(() => {
-      if (isReadyToShow) {
+      if (isContentReadyToBeShown) {
         Animated.timing(opacityRef.current, {
-          toValue: SHOWN,
+          toValue: HIDDEN,
           duration: TIMEOUT,
           useNativeDriver: true,
-        }).start();
+        }).start(() => {
+          setIsShowOverlay(false);
+        });
       }
-    }, [isReadyToShow]);
+    }, [isContentReadyToBeShown]);
 
     if (isFirstComponentScreenPicker(componentsToRender)) {
       // for screen-picker with have additional internal ComponentsMap, no need to add this wrapper
@@ -71,10 +80,7 @@ export const withScreenRevealManager = (Component) => {
     }
 
     return (
-      <Animated.View
-        style={{ opacity: opacityRef.current, flex }}
-        testID="animated-component"
-      >
+      <>
         <Component
           {...props}
           initialNumberToLoad={
@@ -85,7 +91,19 @@ export const withScreenRevealManager = (Component) => {
           }
           onLoadFailedFromScreenRevealManager={managerRef.current.onLoadFailed}
         />
-      </Animated.View>
+        {isShowOverlay ? (
+          <Animated.View
+            style={[
+              styles.container,
+              {
+                opacity: opacityRef.current,
+                backgroundColor: theme.app_background_color,
+              },
+            ]}
+            testID="animated-component"
+          />
+        ) : null}
+      </>
     );
   };
 };

package/Components/Tabs/TV/Tabs.tsx

@@ -8,6 +8,7 @@ import { isEmptyOrNil } from "@applicaster/zapp-react-native-utils/cellUtils";
 import { focusManager } from "@applicaster/zapp-react-native-utils/appUtils/focusManager";
 import { FocusableGroup } from "@applicaster/zapp-react-native-ui-components/Components/FocusableGroup";
 import { Focusable } from "@applicaster/zapp-react-native-ui-components/Components/Focusable";
+import { useAccessibilityManager } from "@applicaster/zapp-react-native-utils/appUtils/accessibilityManager/hooks";
 import { Gutter } from "../Gutter";
 import Tab from "./Tab";
 import { getStyles } from "./styles";
@@ -28,11 +29,14 @@ const TabsComponent = ({
   style,
   selectedEntryIndex,
   setSelectedEntry,
+  accessibility,
 }: TabsProps & Partial<TabsSelectionContextType>) => {
   const configuration = useConfiguration();
   const config = applyFontConfig(configuration);
   const styles = useMemo(() => getStyles(config), [config]);
 
+  const accessibilityManager = useAccessibilityManager({});
+
   const {
     tab_bar_gutter: horizontalGutter,
     tab_bar_background_image: bgImage,
@@ -60,10 +64,20 @@ const TabsComponent = ({
   );
 
   const onListElementFocus = useCallback(
-    (index) => {
+    (index, isSelected: boolean, item: ZappEntry) => {
+      if (isSelected) {
+        accessibilityManager.readText({
+          text: `${accessibility?.selectedHint} ${item.title}`,
+        });
+      } else {
+        accessibilityManager.readText({
+          text: `${accessibility?.hint} ${item.title}`,
+        });
+      }
+
       scrollToSelectedIndex(index, VIEW_POSITION);
     },
-    [scrollToSelectedIndex]
+    [scrollToSelectedIndex, accessibility]
   );
 
   const renderItem = useCallback(
@@ -94,7 +108,7 @@ const TabsComponent = ({
           id={itemId}
           testID={itemId}
           preferredFocus={isSelected}
-          onFocus={() => onListElementFocus(index)}
+          onFocus={() => onListElementFocus(index, isSelected, item)}
           onPress={() => setSelectedEntry && setSelectedEntry(item)}
           style={style}
         >
@@ -149,6 +163,9 @@ const TabsComponent = ({
         shouldUsePreferredFocus
         isWithMemory={false}
         nextFocusDown={parentFocus?.nextFocusDown}
+        onFocus={() => {
+          accessibilityManager.addHeading(accessibility?.announcement);
+        }}
       >
         <View style={tabs}>
           <ImageBackground

package/Components/Tabs/TabContent.tsx

@@ -1,11 +1,10 @@
 import React from "react";
-import { View, ViewStyle } from "react-native";
+import { View, StyleSheet } from "react-native";
 
 import { River } from "@applicaster/zapp-react-native-ui-components/Components";
 import { withNestedNavigationContextProvider } from "@applicaster/zapp-react-native-ui-components/Contexts/NestedNavigationContext";
 
 type Props = {
-  styles: Record<string, ViewStyle>;
   minHeight: number;
   changingTab: boolean;
   feedUrl: string;
@@ -14,9 +13,14 @@ type Props = {
   backgroundColor: string;
 };
 
+const styles = StyleSheet.create({
+  riverWrapper: {
+    flex: 1,
+  },
+});
+
 function TabContentComponent(props: Props) {
   const {
-    styles,
     minHeight,
     backgroundColor,
     changingTab,
@@ -29,7 +33,6 @@ function TabContentComponent(props: Props) {
     <View
       style={[
         styles.riverWrapper,
-
         {
           backgroundColor,
           minHeight,

package/Components/Transitioner/Scene.tsx

@@ -1,9 +1,9 @@
 import React from "react";
 import { equals } from "ramda";
 import { Animated, ViewProps, ViewStyle } from "react-native";
-import { useSafeAreaFrame } from "react-native-safe-area-context";
 
 import { useScreenOrientationHandler } from "@applicaster/zapp-react-native-ui-components/Components/Screen/orientationHandler";
+import { useMemoizedSafeAreaFrameWithActiveState } from "@applicaster/zapp-react-native-ui-components/Components/Screen/hooks";
 
 import { PathnameContext } from "../../Contexts/PathnameContext";
 import { ScreenDataContext } from "../../Contexts/ScreenDataContext";
@@ -94,10 +94,17 @@ function SceneComponent({
     isActive,
   });
 
-  const frame = useSafeAreaFrame();
+  // Use shared memoized frame hook - synchronized with useWaitForValidOrientation
+  // to prevent race conditions during orientation changes
+  // Pass isActive from props since Scene knows its active state from Transitioner
+  const memoFrame = useMemoizedSafeAreaFrameWithActiveState({
+    updateForInactiveScreens: false,
+    isActive,
+  });
+
   const isAnimating = animating && overlayStyle;
 
-  const dimensions = isAnimating ? fullWidthDimensions : frame;
+  const dimensions = isAnimating ? fullWidthDimensions : memoFrame;
 
   return (
     <Animated.View

package/Components/Transitioner/index.js

@@ -1,7 +1,8 @@
 import * as React from "react";
 import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks/navigation";
 import { useDimensions } from "@applicaster/zapp-react-native-utils/reactHooks/layout";
-import { usePickFromState } from "@applicaster/zapp-react-native-redux/hooks";
+import { useAppData } from "@applicaster/zapp-react-native-redux";
+
 import { TransitionerComponent } from "./Transitioner";
 
 export const Transitioner = (props) => {
@@ -16,8 +17,7 @@ export const Transitioner = (props) => {
     deviceInfo: true,
   });
 
-  const { appData } = usePickFromState(["appData"]);
-  const isTabletPortrait = appData?.isTabletPortrait;
+  const { isTabletPortrait } = useAppData();
 
   return (
     <TransitionerComponent

package/Components/VideoLive/LiveImageManager.ts

@@ -4,9 +4,14 @@ import {
   playerManager,
 } from "@applicaster/zapp-react-native-utils/appUtils/playerManager";
 import { setUserCellPlayerMutedPreference } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/userCellPlayerMutedPreference";
+import { playerFactory } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/playerFactory";
+import { PlayerRole } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/conts";
 import { loggerLiveImageManager } from "./loggerHelper";
 import { isTV } from "@applicaster/zapp-react-native-utils/reactUtils";
-import { Component } from "react";
+import {
+  executePreloadHooks,
+  PreloadHookConfig,
+} from "../MasterCell/DefaultComponents/LiveImage/executePreloadHooks";
 
 const TIMEOUT_FOR_DELAY_CHECK_PLAYER_POSITION = 500; // ms
 
@@ -40,13 +45,21 @@ type Position = {
   right: number;
 };
 
+type PlayerFactoryConfig = {
+  player: any; // React ref for native view
+  playerId: string;
+  muted: boolean;
+  playerPluginId: string;
+  screenConfig: Record<string, any>;
+  entry: ZappEntry; // original entry, used as fallback if no hooks
+};
+
 type LiveImageProps = {
-  player: Player;
   playerId: string;
   setMode?: (type: LiveImageType) => void;
-  component: Component;
-  // TODO: ...primary, powerCell, tvGallery, etc.
-  // type: string;
+  preloadHooks?: PreloadHookConfig[];
+  factoryConfig: PlayerFactoryConfig;
+  tag: string;
 };
 
 // Disabled because we have only unmute button but no play/pause state anymore
@@ -85,7 +98,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
 
   public register = (item: LiveImage): (() => void) => {
     this.items.push(item);
-    log_debug(`register: live image ${playerInfo(item.player)}`);
+    log_debug(`register: live image ${item.playerId} - ${item.tag}`);
 
     // TV only Start playing video once registered
     if (isTV()) {
@@ -96,15 +109,13 @@ export class LiveImageManager implements PlayerLifecycleListener {
   };
 
   public unregister = (item: LiveImage) => {
-    log_debug(`unregister: live-image ${playerInfo(item.player)}`);
+    log_debug(`unregister: live-image ${item.playerId} - ${item.tag}`);
 
     if (this.currentlyPlaying === item) {
       this.currentlyPlaying = null;
 
       log_debug(
-        `unregister: currently playing live-image was destroyed, ${playerInfo(
-          item.player
-        )}`
+        `unregister: currently playing live-image was destroyed, ${item.playerId} - ${item.tag}`
       );
 
       // TODO: Maybe start another one
@@ -118,7 +129,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
         item,
         playerId: this.currentlyPlaying?.playerId,
         primaryPlayerId: this.primaryPlayer?.playerId,
-        entry: item.getPlayer().getEntry(),
+        entry: item.getPlayer()?.getEntry(),
       },
     });
   };
@@ -130,9 +141,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
 
   public onViewportEnter = (item: LiveImage) => {
     log_debug(
-      `onViewportEnter: live-image ${playerInfo(
-        item.player
-      )}, primary ${playerInfo(this.primaryPlayer)}`
+      `onViewportEnter: live-image ${item.playerId} - ${item.tag}, primary ${playerInfo(this.primaryPlayer)} - position:${item.positionToString()}`
     );
 
     if (!isTV()) {
@@ -154,9 +163,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
 
   public onViewportLeave = (item: LiveImage) => {
     log_debug(
-      `onViewportLeave: live-image playerId: ${playerInfo(
-        item.player
-      )}, primary ${playerInfo(this.primaryPlayer)}`
+      `onViewportLeave: live-image ${item.playerId} - ${item.tag}, primary ${playerInfo(this.primaryPlayer)} - position:${item.positionToString()}`
     );
 
     this.pauseItem(item);
@@ -190,20 +197,29 @@ export class LiveImageManager implements PlayerLifecycleListener {
     this.items.find((i) => i.playerId === playerId) || null;
 
   private pauseItem = (item: LiveImage) => {
-    log_debug(`pauseItem: live-image ${playerInfo(item.player)}`);
+    log_debug(`pauseItem: live-image ${item.playerId} - ${item.tag}`);
+
+    if (!item.player) {
+      // Player not yet created (e.g. hooks still running) — just reset mode
+      item.setMode?.(LiveImageType.Image);
+
+      if (item === this.currentlyPlaying) {
+        this.currentlyPlaying = null;
+      }
+
+      return;
+    }
 
     if (!item.player.playerState.isReadyToPlay) {
       log_debug(
-        `playItem: live-image not ready, will start playback after loading, ${playerInfo(
-          item.player
-        )}`
+        `pauseItem: live-image not ready, ${item.playerId} - ${item.tag}`
       );
     } else {
-      item.player?.pause();
+      item.player.pause();
     }
 
     // Fake close event, because we unmount native view
-    item.player?.onPlayerClose();
+    item.player.onPlayerClose();
     item.setMode?.(LiveImageType.Image);
 
     if (item === this.currentlyPlaying) {
@@ -213,9 +229,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
 
   public playLiveImage = (item: LiveImage) => {
     log_debug(
-      `playLiveImage: live-image ${playerInfo(
-        item.player
-      )}, primary ${playerInfo(this.primaryPlayer)}`
+      `playLiveImage: live-image ${item.playerId} - ${item.tag}, primary ${playerInfo(this.primaryPlayer)}`
     );
 
     if (this.primaryPlayer) {
@@ -223,7 +237,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
     }
 
     if (this.currentlyPlaying) {
-      if (this.currentlyPlaying?.player?.playerId === item.player.playerId) {
+      if (this.currentlyPlaying.playerId === item.playerId) {
         return;
       } else {
         this.pauseItem(this.currentlyPlaying);
@@ -231,18 +245,42 @@ export class LiveImageManager implements PlayerLifecycleListener {
     }
 
     this.currentlyPlaying = item;
-    item.setMode?.(LiveImageType.Video);
 
-    if (item.player.playerState.isReadyToPlay) {
-      item.player.play();
-    }
+    item
+      .prepareForPlayback()
+      .then((result) => {
+        if (!result) {
+          log_error(
+            `Failed to prepare live image ${item.playerId} - ${item.tag} for playback: prepareForPlayback returned false`
+          );
+
+          this.currentlyPlaying = null;
+          item.setMode?.(LiveImageType.Image);
+
+          return;
+        }
+
+        // Guard: item might have been replaced while hooks were running
+        if (this.currentlyPlaying !== item) return;
+
+        item.setMode?.(LiveImageType.Video);
+
+        if (item.player?.playerState.isReadyToPlay) {
+          item.player.play();
+        }
+      })
+      .catch((error) => {
+        log_error(
+          `Failed to prepare live image ${item.playerId} - ${item.tag} for playback: ${error?.message}`
+        );
+
+        this.onLiveImageError(item, error);
+      });
   };
 
   public pauseLiveImage = (item: LiveImage) => {
     log_debug(
-      `pauseLiveImage: live-image playerId: ${playerInfo(
-        item.player
-      )}, primary ${playerInfo(this.primaryPlayer)}`
+      `pauseLiveImage: live-image ${item.playerId} - ${item.tag}, primary ${playerInfo(this.primaryPlayer)}`
     );
 
     this.pauseItem(item);
@@ -258,7 +296,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
 
     setUserCellPlayerMutedPreference(true);
 
-    this.items.forEach((liveImage) => liveImage.player.mute());
+    this.items.forEach((liveImage) => liveImage.player?.mute());
   };
 
   public unmuteAll = () => {
@@ -266,16 +304,36 @@ export class LiveImageManager implements PlayerLifecycleListener {
 
     setUserCellPlayerMutedPreference(false);
 
-    this.items.forEach((liveImage) => liveImage.player.unmute());
+    this.items.forEach((liveImage) => liveImage.player?.unmute());
   };
 
-  public checkPlayerPosition = (item: LiveImage) => {
+  public onViewPositionChanged = (item: LiveImage) => {
+    log_debug(
+      `onViewPositionChanged: live-image ${item.playerId} - ${item.tag}, primary ${playerInfo(this.primaryPlayer)} - position:${item.positionToString()}`
+    );
+
+    if (!isTV()) {
+      // mobile only
+      // we have to delay running checkPlayerPosition, because sometimes on fast scrolling we get wrong order onEnter, then onLeave.
+      // which could cause select wrong item to play
+
+      this.cancelCheckPlayerPositionTimeout();
+
+      this.checkPlayerPositionTimeout = setTimeout(() => {
+        this.cancelCheckPlayerPositionTimeout();
+
+        this.checkPlayerPosition(item);
+      }, TIMEOUT_FOR_DELAY_CHECK_PLAYER_POSITION);
+    } else {
+      this.checkPlayerPosition(item);
+    }
+  };
+
+  private checkPlayerPosition = (item: LiveImage) => {
     this.cancelCheckPlayerPositionTimeout();
 
     log_debug(
-      `checkPlayerPosition: live-image playerId: ${playerInfo(
-        item.player
-      )}, primary ${playerInfo(this.primaryPlayer)}`
+      `checkPlayerPosition: live-image ${item.playerId} - ${item.tag}, primary ${playerInfo(this.primaryPlayer)}`
     );
 
     const playerItem = this.findNextPlayableItem();
@@ -391,7 +449,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
         item,
         playerId: this.currentlyPlaying?.playerId,
         primaryPlayerId: this.primaryPlayer?.playerId,
-        entry: item.getPlayer().getEntry(),
+        entry: item.getPlayer()?.getEntry(),
       },
     });
   };
@@ -426,7 +484,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
           item,
           playerId: this.currentlyPlaying?.playerId,
           primaryPlayerId: this.primaryPlayer?.playerId,
-          entry: item.getPlayer().getEntry(),
+          entry: item.getPlayer()?.getEntry(),
         },
       });
   };
@@ -448,7 +506,7 @@ export class LiveImageManager implements PlayerLifecycleListener {
       this.currentlyPlaying = null;
 
       log_debug(
-        `onLiveImageError: currentitem: ${currentItem.playerId} was removed`
+        `onLiveImageError: currentItem: ${currentItem.playerId} - ${currentItem.tag} was removed`
       );
 
       // TODO: ...Maybe player some other item
@@ -460,8 +518,8 @@ export class LiveImageManager implements PlayerLifecycleListener {
         item,
         error,
         playerId: currentItem?.playerId,
-        primaryPlayerId: currentItem?.playerId,
-        entry: item.getPlayer().getEntry(),
+        primaryPlayerId: this.primaryPlayer?.playerId,
+        entry: item.getPlayer()?.getEntry(),
       },
     });
   };
@@ -503,10 +561,10 @@ export class LiveImageManager implements PlayerLifecycleListener {
 LiveImageManager.instance;
 
 export class LiveImage implements QuickBrickPlayer.SharedPlayerCallBacks {
-  public player: Player;
-  public setMode: (type: LiveImageType) => void;
-  // Will be replaced with rects
+  public player: Player | null = null;
+  public setMode?: (type: LiveImageType) => void;
   public isFullyVisible: boolean = false;
+  public tag: string;
   public position: Position = {
     centerX: 0,
     centerY: 0,
@@ -516,18 +574,105 @@ export class LiveImage implements QuickBrickPlayer.SharedPlayerCallBacks {
     left: 0,
   };
 
+  positionToString() {
+    if (!this.position) {
+      return "position not set";
+    }
+
+    const { centerX, centerY, top, bottom, left, right } = this.position;
+
+    return `centerX: ${centerX.toFixed(2)}, centerY: ${centerY.toFixed(2)}, top: ${top.toFixed(2)}, bottom: ${bottom.toFixed(2)}, left: ${left.toFixed(2)}, right: ${right.toFixed(2)}`;
+  }
+
   readonly playerId: string;
-  readonly component: Component;
+  public component: any = null;
+
+  private factoryConfig: PlayerFactoryConfig;
+  public preloadHooks?: PreloadHookConfig[];
+  public processedEntry: ZappEntry | null = null;
+  private _preparePromise: Promise<boolean> | null = null;
 
   constructor(props: LiveImageProps) {
-    this.player = props.player;
     this.setMode = props.setMode;
-    this.playerId = this.player.playerId;
-    this.component = props.component;
-    this.player.addListener({ id: "live-image", listener: this });
+    this.playerId = props.playerId;
+    this.preloadHooks = props.preloadHooks;
+    this.factoryConfig = props.factoryConfig;
+    this.tag = props.tag || "untagged";
+  }
+
+  async prepareForPlayback(): Promise<boolean> {
+    // Already prepared — player exists
+    if (this.player) {
+      return true;
+    }
+
+    // Deduplicate: if preparation is already in flight, await the same promise
+    if (this._preparePromise) {
+      return this._preparePromise;
+    }
+
+    this._preparePromise = (async (): Promise<boolean> => {
+      // 1. Run hooks if configured
+      let entry = this.factoryConfig.entry;
+
+      if (this.preloadHooks?.length) {
+        const result = await executePreloadHooks({
+          preloadHooks: this.preloadHooks,
+          entry,
+        });
+
+        if (result) {
+          this.processedEntry = result;
+          entry = result;
+        } else {
+          return false;
+        }
+      }
+
+      // 2. Create the player with the correct entry
+      const factoryItem = playerFactory({
+        player: this.factoryConfig.player,
+        playerId: this.factoryConfig.playerId,
+        autoplay: false,
+        entry,
+        muted: this.factoryConfig.muted,
+        playerPluginId: this.factoryConfig.playerPluginId,
+        screenConfig: this.factoryConfig.screenConfig,
+        playerRole: PlayerRole.Cell,
+      });
+
+      if (!factoryItem) {
+        throw new Error("Player factory returned null");
+      }
+
+      this.player = factoryItem.controller;
+      this.component = factoryItem.Component;
+
+      // 3. Register callbacks — player now exists
+      this.player.addListener({ id: "live-image", listener: this });
+
+      return true;
+    })()
+      .then((result) => {
+        this._preparePromise = null;
+
+        return result;
+      })
+      .catch((error) => {
+        this._preparePromise = null;
+
+        log_error(
+          `prepareForPlayback: live-image ${this.playerId}, error preparing for playback: ${error?.message}`,
+          { error }
+        );
+
+        throw error;
+      });
+
+    return this._preparePromise;
   }
 
-  public getPlayer = (): Player => {
+  public getPlayer = (): Player | null => {
     return this.player;
   };