@applicaster/zapp-react-native-ui-components 14.0.20-rc.1 → 14.0.21-alpha.1214400134

package/Components/MasterCell/DefaultComponents/LiveImage/__tests__/prepareEntry.test.ts

@@ -0,0 +1,352 @@
+import { prepareEntry } from "../index";
+
+const makeEntry = (overrides = {}): any => ({
+  content: { src: "https://example.com/video.mp4", type: "video/mp4" },
+  extensions: {},
+  ...overrides,
+});
+
+describe("prepareEntry", () => {
+  it("should return null when entry is null or undefined", () => {
+    expect(prepareEntry(null)).toBeNull();
+    expect(prepareEntry(undefined)).toBeNull();
+  });
+
+  describe("preview_playback_override", () => {
+    it("should deep merge override with entry, override taking precedence", () => {
+      const override = {
+        link: { href: "https://video-preload.com/id", rel: "self" },
+        extensions: {
+          brightcove: { video_id: 1234 },
+          preview: true,
+          free: true,
+          requires_authentication: false,
+        },
+      };
+
+      const entry = makeEntry({
+        extensions: {
+          preview_playback_override: override,
+          existing_field: "keep-me",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.extensions.brightcove.video_id).toBe(1234);
+      expect(result.extensions.preview).toBe(true);
+      expect(result.extensions.existing_field).toBe("keep-me");
+
+      expect(result.link).toEqual({
+        href: "https://video-preload.com/id",
+        rel: "self",
+      });
+
+      expect(result.content).toEqual(entry.content);
+    });
+
+    it("should override entry fields when both have the same key", () => {
+      const override = {
+        extensions: {
+          brightcove: { video_id: 9999 },
+        },
+        content: { src: "https://override.com/video.mp4" },
+      };
+
+      const entry = makeEntry({
+        extensions: {
+          preview_playback_override: override,
+          brightcove: { video_id: 1111, account_id: "abc" },
+        },
+        content: { src: "https://original.com/video.mp4", type: "video/mp4" },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.extensions.brightcove.video_id).toBe(9999);
+      expect(result.extensions.brightcove.account_id).toBe("abc");
+      expect(result.content.src).toBe("https://override.com/video.mp4");
+      expect(result.content.type).toBe("video/mp4");
+    });
+
+    it("should take priority over other playback sources", () => {
+      const override = {
+        link: { href: "https://override.com" },
+        extensions: { brightcove: { video_id: 5555 } },
+      };
+
+      const entry = makeEntry({
+        extensions: {
+          preview_playback_override: override,
+          brightcove: { preview_playback: "other-id" },
+          preview_playback: "https://other.com/video.mp4",
+        },
+        content: {
+          src: "https://example.com/video.mp4",
+          teaser: "https://teaser.com/video.mp4",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.link).toEqual({ href: "https://override.com" });
+      expect(result.extensions.brightcove.video_id).toBe(5555);
+    });
+  });
+
+  describe("brightcove preview_playback", () => {
+    it("should return entry with brightcove video_id replaced by preview_playback", () => {
+      const entry = makeEntry({
+        extensions: {
+          brightcove: {
+            video_id: "original-id",
+            preview_playback: "preview-id",
+          },
+          some_other: "value",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result).toEqual({
+        ...entry,
+        extensions: {
+          ...entry.extensions,
+          brightcove: {
+            video_id: "preview-id",
+            preview_playback: "preview-id",
+          },
+        },
+      });
+    });
+
+    it("should preserve other extensions", () => {
+      const entry = makeEntry({
+        extensions: {
+          brightcove: { preview_playback: "preview-id" },
+          custom_field: "keep-me",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.extensions.custom_field).toBe("keep-me");
+    });
+  });
+
+  describe("extensions.preview_playback (non-brightcove)", () => {
+    it("should return entry with content.src set to preview_playback URL", () => {
+      const entry = makeEntry({
+        extensions: { preview_playback: "https://preview.com/video.m3u8" },
+        content: { src: "https://original.com/video.mp4" },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.content.src).toBe("https://preview.com/video.m3u8");
+    });
+
+    it("should preserve other content fields", () => {
+      const entry = makeEntry({
+        extensions: { preview_playback: "https://preview.com/video.m3u8" },
+        content: { src: "https://original.com/video.mp4", type: "video/mp4" },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.content.type).toBe("video/mp4");
+    });
+  });
+
+  describe("content.teaser", () => {
+    it("should return entry with content.src set to teaser URL", () => {
+      const entry = makeEntry({
+        extensions: {},
+        content: {
+          src: "https://original.com/video.mp4",
+          teaser: "https://teaser.com/teaser.mp4",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.content.src).toBe("https://teaser.com/teaser.mp4");
+    });
+  });
+
+  describe("brightcove video_id (without preview_playback)", () => {
+    it("should return the entry as-is when brightcove video_id exists", () => {
+      const entry = makeEntry({
+        extensions: { brightcove: { video_id: "some-id" } },
+        content: { src: "" },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result).toBe(entry);
+    });
+  });
+
+  describe("content.src fallback", () => {
+    it("should return null when content.src is missing", () => {
+      const entry = makeEntry({
+        extensions: {},
+        content: {},
+      });
+
+      expect(prepareEntry(entry)).toBeNull();
+    });
+
+    it("should return null when content.src is empty", () => {
+      const entry = makeEntry({
+        extensions: {},
+        content: { src: "" },
+      });
+
+      expect(prepareEntry(entry)).toBeNull();
+    });
+
+    it("should return entry when content.type starts with video", () => {
+      const entry = makeEntry({
+        extensions: {},
+        content: { src: "https://example.com/stream", type: "video/mp4" },
+      });
+
+      expect(prepareEntry(entry)).toBe(entry);
+    });
+
+    it("should return entry when src has a known video extension", () => {
+      const extensions = ["m3u8", "mp4", "m4v", "mkv", "mov", "mpd", "ogv"];
+
+      for (const ext of extensions) {
+        const entry = makeEntry({
+          extensions: {},
+          content: { src: `https://example.com/video.${ext}` },
+        });
+
+        expect(prepareEntry(entry)).toBe(entry);
+      }
+    });
+
+    it("should return entry for audio extensions", () => {
+      const extensions = ["mp3", "oga", "opus"];
+
+      for (const ext of extensions) {
+        const entry = makeEntry({
+          extensions: {},
+          content: { src: `https://example.com/audio.${ext}` },
+        });
+
+        expect(prepareEntry(entry)).toBe(entry);
+      }
+    });
+
+    it("should return null for non-video/non-audio URLs", () => {
+      const entry = makeEntry({
+        extensions: {},
+        content: { src: "https://example.com/page.html" },
+      });
+
+      expect(prepareEntry(entry)).toBeNull();
+    });
+
+    it("should return null for URLs without extensions", () => {
+      const entry = makeEntry({
+        extensions: {},
+        content: { src: "https://example.com/stream" },
+      });
+
+      expect(prepareEntry(entry)).toBeNull();
+    });
+  });
+
+  describe("priority order", () => {
+    it("should prefer brightcove.preview_playback over extensions.preview_playback", () => {
+      const entry = makeEntry({
+        extensions: {
+          brightcove: { preview_playback: "bc-preview" },
+          preview_playback: "ext-preview",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.extensions.brightcove.video_id).toBe("bc-preview");
+    });
+
+    it("should prefer extensions.preview_playback over content.teaser", () => {
+      const entry = makeEntry({
+        extensions: { preview_playback: "https://preview.com/video.mp4" },
+        content: {
+          src: "https://original.com/video.mp4",
+          teaser: "https://teaser.com/video.mp4",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.content.src).toBe("https://preview.com/video.mp4");
+    });
+
+    it("should prefer preview_playback_override over all other sources", () => {
+      const override = {
+        extensions: { brightcove: { video_id: "override-id" } },
+      };
+
+      const entry = makeEntry({
+        extensions: {
+          preview_playback_override: override,
+          brightcove: { preview_playback: "bc-preview", video_id: "original" },
+          preview_playback: "https://ext-preview.com/video.mp4",
+        },
+        content: {
+          src: "https://original.com/video.mp4",
+          teaser: "https://teaser.com/video.mp4",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.extensions.brightcove.video_id).toBe("override-id");
+    });
+
+    it("should prefer content.teaser over brightcove.video_id", () => {
+      const entry = makeEntry({
+        extensions: { brightcove: { video_id: "some-id" } },
+        content: {
+          src: "https://original.com/video.mp4",
+          teaser: "https://teaser.com/teaser.mp4",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.content.src).toBe("https://teaser.com/teaser.mp4");
+    });
+
+    it("should prefer content.teaser over content.src URL check", () => {
+      const entry = makeEntry({
+        extensions: {},
+        content: {
+          src: "https://original.com/video.mp4",
+          teaser: "https://teaser.com/teaser.m3u8",
+        },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result.content.src).toBe("https://teaser.com/teaser.m3u8");
+    });
+
+    it("should prefer brightcove.video_id over content.src URL check", () => {
+      const entry = makeEntry({
+        extensions: { brightcove: { video_id: "bc-id" } },
+        content: { src: "https://example.com/page.html" },
+      });
+
+      const result = prepareEntry(entry);
+
+      expect(result).toBe(entry);
+    });
+  });
+});

package/Components/MasterCell/DefaultComponents/LiveImage/executePreloadHooks.ts

@@ -0,0 +1,136 @@
+import { findPluginByIdentifier } from "@applicaster/zapp-react-native-utils/pluginUtils";
+import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
+import { loggerLiveImageManager } from "../../../VideoLive/loggerHelper";
+
+const { log_debug, log_error } = loggerLiveImageManager;
+
+export type PreloadHookConfig = ZappPreloadPlugins & {
+  configuration: any;
+};
+
+function runHookWithCallback(
+  invoke: (
+    payload: any,
+    callback: (result: hookCallbackArgs) => void,
+    abortCallback: () => void
+  ) => void,
+  payload: any
+): Promise<{ payload: any; aborted: boolean }> {
+  return new Promise((resolve, reject) => {
+    const abortCallback = () => {
+      resolve({ payload, aborted: true });
+    };
+
+    try {
+      invoke(
+        payload,
+        ({
+          success,
+          error,
+          payload: resultPayload,
+          abort,
+        }: hookCallbackArgs) => {
+          if (error) {
+            reject(error);
+          } else if (!success || abort) {
+            resolve({ payload: resultPayload ?? payload, aborted: true });
+          } else {
+            resolve({ payload: resultPayload ?? payload, aborted: false });
+          }
+        },
+        abortCallback
+      );
+    } catch (error) {
+      log_error(`Error running preload hook: ${error.message}`, { error });
+      reject(error);
+    }
+  });
+}
+
+// TODO: Move this function to a more generic place,
+//  as it can be used by other components that want to run preload hooks
+//  and add test coverage for it
+export async function executePreloadHooks({
+  preloadHooks,
+  entry,
+}: {
+  preloadHooks: PreloadHookConfig[];
+  entry: ZappEntry;
+}): Promise<ZappEntry | null> {
+  if (!preloadHooks?.length) {
+    return entry;
+  }
+
+  const sortedHooks = [...preloadHooks].sort(
+    (a, b) => (a.weight || 0) - (b.weight || 0)
+  );
+
+  const hookNames = sortedHooks.map((hook) => hook.identifier).join(", ");
+
+  log_debug(
+    `Preload hook sequence: ${hookNames}, entry: ${entry.id} - ${entry.title}`
+  );
+
+  let payload: any = entry;
+
+  let needsAbort = false;
+  const plugins = appStore.get("plugins");
+
+  for (const hookConfig of sortedHooks) {
+    const plugin = findPluginByIdentifier(hookConfig.identifier, plugins, true);
+
+    if (!plugin?.module) {
+      log_debug(
+        `Preload hook plugin not found: ${hookConfig.identifier}, skipping`
+      );
+
+      continue;
+    }
+
+    const { module: hookModule } = plugin;
+
+    if (hookModule.skipHook?.(payload)) {
+      log_debug(`Skipping hook: ${hookConfig.identifier}`);
+
+      continue;
+    }
+
+    if (hookModule.runInBackground) {
+      log_debug(
+        `Running background hook: ${hookConfig.identifier}, entry: ${payload?.id} - ${payload?.title}`
+      );
+
+      const result = await runHookWithCallback(
+        (item, callback, abortCallback) =>
+          hookModule
+            .runInBackground(item, callback, hookConfig, abortCallback)
+            ?.catch?.((error: Error) => {
+              log_error(
+                `Error running background preload hook: ${hookConfig.identifier}, error: ${error.message}`,
+                { error }
+              );
+
+              callback({ success: false, payload: item, error });
+            }),
+        payload
+      );
+
+      payload = result.payload;
+      needsAbort = result.aborted;
+    }
+
+    if (needsAbort) {
+      log_debug(
+        `Preload hook requested abort: ${hookConfig.identifier}, stopping chain`
+      );
+
+      break;
+    }
+  }
+
+  if (needsAbort) {
+    return null;
+  }
+
+  return payload;
+}

package/Components/MasterCell/DefaultComponents/LiveImage/index.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
-import * as R from "ramda";
+import merge from "lodash/merge";
+import { clone } from "@applicaster/zapp-react-native-utils/utils";
 import { Platform, View, ViewStyle } from "react-native";
 import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
 import { isTV, isWeb } from "@applicaster/zapp-react-native-utils/reactUtils";
@@ -83,30 +84,22 @@ const removeAdsFromEntry = (entry) => {
     return entry;
   }
 
-  const newEntry = R.clone(entry);
+  const newEntry = clone(entry);
 
   delete newEntry.extensions.video_ads;
 
   return newEntry;
 };
 
-const prepareEntry = (entry) => {
+export const prepareEntry = (entry: ZappEntry) => {
   if (!entry) {
     return null;
   }
 
-  if (entry.extensions?.preview_playback) {
-    return {
-      ...entry,
-      content: { ...entry?.content, src: entry?.extensions?.preview_playback },
-    };
-  }
+  const previewPlaybackOverride = entry.extensions?.preview_playback_override;
 
-  if (entry.content?.teaser) {
-    return {
-      ...entry,
-      content: { ...entry?.content, src: entry?.content?.teaser },
-    };
+  if (previewPlaybackOverride) {
+    return merge({}, entry, previewPlaybackOverride);
   }
 
   const previewPlayback = entry.extensions?.brightcove?.preview_playback;
@@ -124,6 +117,20 @@ const prepareEntry = (entry) => {
     };
   }
 
+  if (entry.extensions?.preview_playback) {
+    return {
+      ...entry,
+      content: { ...entry?.content, src: entry?.extensions?.preview_playback },
+    };
+  }
+
+  if (entry.content?.teaser) {
+    return {
+      ...entry,
+      content: { ...entry?.content, src: entry?.content?.teaser },
+    };
+  }
+
   if (entry.extensions?.brightcove?.video_id) {
     return entry;
   }
@@ -167,14 +174,24 @@ function getFocusedState(
 const getPlayerConfig = (player_screen_id, actionIdentifier) => {
   if (player_screen_id) {
     const rivers = appStore.get("rivers");
+    const plugins = appStore.get("plugins");
     const playerScreen = rivers?.[player_screen_id] ?? null;
 
+    const preloadHooks = playerScreen?.hooks?.preload_plugins?.map((hook) => {
+      const configuration =
+        plugins.find((plugin) => plugin.identifier === hook.identifier)
+          ?.configuration || {};
+
+      return { ...hook, configuration, ...rivers[hook.screen_id] };
+    });
+
     // TODO: Check is it a player later
 
     // TODO: Add more dict if needed from the screen component, styles, data etc
     return {
       playerPluginId: playerScreen?.type ?? DEFAULT_PLAYER_IDENTIFIER,
       screenConfig: playerScreen?.general,
+      preloadHooks,
     };
   }
 
@@ -229,7 +246,7 @@ const LiveImageComponent = (props: LiveImageProps) => {
 
   const isCurrentlyFocused = useTrackCurrentAutoScrollingElement(componentId);
 
-  const { playerPluginId, screenConfig } =
+  const { playerPluginId, screenConfig, preloadHooks } =
     getPlayerConfig(player_screen_id, actionIdentifier) ?? {};
 
   const playableEntry = playerPluginId ? getPlayableEntry(item) : null;
@@ -239,8 +256,8 @@ const LiveImageComponent = (props: LiveImageProps) => {
 
   const isShouldRender =
     playerPlugin &&
-    getFocusedState(state, componentType, isCurrentlyFocused) &&
     playableEntry &&
+    getFocusedState(state, componentType, isCurrentlyFocused) &&
     cellUUID &&
     isSupportedTVForLiveImage() &&
     !isScreenReaderEnabled;
@@ -259,6 +276,7 @@ const LiveImageComponent = (props: LiveImageProps) => {
             imageKey={imageKey}
             item={playableEntry}
             audioMutedByDefault={audio_muted_by_default}
+            preloadHooks={preloadHooks}
           />
         </View>
       ) : null}

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;
   };
 

package/Components/VideoLive/PlayerLiveImageComponent.tsx

@@ -7,8 +7,6 @@ import { AppState, AppStateStatus, View } from "react-native";
 import { TrackedView } from "../TrackedView";
 import { useDimensions } from "@applicaster/zapp-react-native-utils/reactHooks/layout";
 
-import { playerFactory } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/playerFactory";
-
 import {
   isApplePlatform,
   isTV,
@@ -22,15 +20,15 @@ import { AnimatedInOut } from "@applicaster/zapp-react-native-ui-components/Comp
 import { overlayFadeIn } from "./animationUtils";
 import { loggerLiveImageComponent } from "./loggerHelper";
 import { usePlayer } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/usePlayer";
-import { PlayerRole } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/conts";
 import { getAutoplaySettings } from "./utils";
 import { isString } from "@applicaster/zapp-react-native-utils/stringUtils";
 import { BufferAnimation } from "../PlayerContainer/BufferAnimation";
+import { PreloadHookConfig } from "../MasterCell/DefaultComponents/LiveImage/executePreloadHooks";
 
 const { log_error, log_debug } = loggerLiveImageComponent;
 
-const isMeasurement = (item: ZappEntry) =>
-  isString(item.id) && item.id.startsWith("pre-measurement-");
+const isMeasurement = (itemId: string | number | null): boolean =>
+  isString(itemId) && itemId.startsWith("pre-measurement-");
 
 // Pixels by which the view can slightly extend outside the viewport and still be considered fully visible.
 const CLIP_THRESHOLD = 10;
@@ -44,6 +42,7 @@ type Props = {
   screenConfig: Record<string, any>;
   audioMutedByDefault?: boolean;
   uri: string; // cover image url
+  preloadHooks?: PreloadHookConfig[];
 };
 
 const PlayerLiveImageComponent = (props: Props) => {
@@ -116,43 +115,36 @@ const PlayerLiveImageComponent = (props: Props) => {
     }
 
     entryToViewIdMapping.current[nativeTag] = { itemId: item.id };
-  }, [trackViewRef.current, item.id, mode]);
+  }, [item.id, mode]);
 
-  const { screenConfig, playerPluginId } = props;
+  const { screenConfig, playerPluginId, preloadHooks } = props;
 
   const liveImageItem: LiveImage = React.useMemo(() => {
-    const playerFactoryItem = playerFactory({
-      player: ref,
+    return new LiveImage({
       playerId,
-      autoplay: false,
-      entry: item,
-      muted, // Initial muted state, not needed in dependencies
-      playerPluginId: playerPluginId,
-      screenConfig: screenConfig,
-      playerRole: PlayerRole.Cell,
-    });
-
-    if (playerFactoryItem) {
-      return new LiveImage({
+      preloadHooks,
+      factoryConfig: {
+        player: ref,
         playerId,
-        player: playerFactoryItem.controller,
-        component: playerFactoryItem?.Component,
-      });
-    } else {
-      throw new Error("Player factory item is null");
-    }
-  }, [playerId, item.id, playerPluginId, screenConfig]);
+        muted,
+        playerPluginId: playerPluginId,
+        screenConfig: screenConfig,
+        entry: item,
+      },
+      tag: item.title?.toString(),
+    });
+  }, [playerId, preloadHooks, muted, playerPluginId, screenConfig, item]);
 
   React.useEffect(() => {
     liveImageItem.setMode = setModeDebounced;
   }, [setModeDebounced, liveImageItem]);
 
+  // todo: no need for it to be react, can be moved into `player.addListener`
   const { start, end } = React.useMemo(
     () => getAutoplaySettings(item),
     [item.id]
   );
 
-  const controller = liveImageItem.getPlayer();
   const player = usePlayer(playerId);
 
   const _assignRoot = (component) => {
@@ -169,7 +161,7 @@ const PlayerLiveImageComponent = (props: Props) => {
 
   React.useEffect(() => {
     // FIXME - find a more elegant way to disable live-image on cell for measurement
-    if (isMeasurement(item)) {
+    if (isMeasurement(item.id)) {
       return;
     }
 
@@ -253,7 +245,13 @@ const PlayerLiveImageComponent = (props: Props) => {
   }, [item.id]);
 
   React.useEffect(() => {
-    if (isMeasurement(item) || !playerManager) {
+    if (isMeasurement(item.id) || !playerManager) {
+      return;
+    }
+
+    const controller = liveImageItem.getPlayer();
+
+    if (!controller) {
       return;
     }
 
@@ -273,7 +271,7 @@ const PlayerLiveImageComponent = (props: Props) => {
         playerManager.unregisterPlayer(playerId);
       };
     }
-  }, [liveImageItem, playerId, controller, item.id]);
+  }, [liveImageItem, playerId, mode, item.id]);
 
   const onPositionUpdated = React.useCallback(
     (data) => {
@@ -310,7 +308,7 @@ const PlayerLiveImageComponent = (props: Props) => {
           ? LiveImageManager.instance.onViewportEnter(liveImageItem)
           : LiveImageManager.instance.onViewportLeave(liveImageItem);
       } else {
-        LiveImageManager.instance.checkPlayerPosition(liveImageItem);
+        LiveImageManager.instance.onViewPositionChanged(liveImageItem);
       }
     },
     [liveImageItem, dimensions.height, dimensions.width]
@@ -338,11 +336,11 @@ const PlayerLiveImageComponent = (props: Props) => {
           <Player
             autoplay={false}
             ref={_assignRoot}
-            entry={item} // Must be passed first in list
+            entry={liveImageItem.processedEntry || item} // Must be passed first in list
             style={videoStyles}
             playerId={playerId}
             muted={muted}
-            listener={controller?.getListener()}
+            listener={liveImageItem.getPlayer()?.getListener()}
             resizeMode={"cover"}
             {...platformSpecificProps}
           />

package/Components/VideoLive/__tests__/PlayerLiveImageComponent.test.tsx

@@ -120,29 +120,14 @@ describe("PlayerLiveImageComponent", () => {
     // TODO: implement this test
   });
 
-  it("should register the player for normal item", () => {
+  it("should not register the player at mount (lazy creation)", () => {
     render(
       <Wrapper>
         <PlayerLiveImage {...defaultProps} />
       </Wrapper>
     );
 
-    const isPlayerRegistered = playerManager.isPlayerRegistered(
-      defaultProps.playerId
-    );
-
-    expect(isPlayerRegistered).toBe(true);
-  });
-
-  it("should unregister the player for normal item", () => {
-    const component = render(
-      <Wrapper>
-        <PlayerLiveImage {...defaultProps} />
-      </Wrapper>
-    );
-
-    component.unmount();
-
+    // Player is not registered until playback starts (lazy creation)
     const isPlayerRegistered = playerManager.isPlayerRegistered(
       defaultProps.playerId
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-ui-components",
-  "version": "14.0.20-rc.1",
+  "version": "14.0.21-alpha.1214400134",
   "description": "Applicaster Zapp React Native ui components for the Quick Brick App",
   "main": "index.js",
   "types": "index.d.ts",
@@ -28,10 +28,10 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "14.0.20-rc.1",
-    "@applicaster/zapp-react-native-bridge": "14.0.20-rc.1",
-    "@applicaster/zapp-react-native-redux": "14.0.20-rc.1",
-    "@applicaster/zapp-react-native-utils": "14.0.20-rc.1",
+    "@applicaster/applicaster-types": "14.0.21-alpha.1214400134",
+    "@applicaster/zapp-react-native-bridge": "14.0.21-alpha.1214400134",
+    "@applicaster/zapp-react-native-redux": "14.0.21-alpha.1214400134",
+    "@applicaster/zapp-react-native-utils": "14.0.21-alpha.1214400134",
     "fast-json-stable-stringify": "^2.1.0",
     "promise": "^8.3.0",
     "url": "^0.11.0",