@applicaster/zapp-react-native-utils 16.0.0-alpha.8101951023 → 16.0.0-alpha.8114431136

package/appUtils/playerManager/__tests__/playerToolbox.test.ts

@@ -0,0 +1,97 @@
+const mockRegister = jest.fn();
+let mockXray: Record<string, unknown> | null = {};
+
+jest.mock("../../../logger", () => ({
+  getXray: () => mockXray,
+}));
+
+const loadToolbox = () => {
+  let module;
+
+  jest.isolateModules(() => {
+    module = require("../playerToolbox");
+  });
+
+  return module as typeof import("../playerToolbox");
+};
+
+const player = (overrides = {}) => ({
+  getSeekableDuration: () => 100,
+  getContentPosition: () => 40,
+  seekTo: jest.fn(),
+  ...overrides,
+});
+
+const manager = (active) =>
+  ({ getActivePlayer: () => active, isCasting: () => false }) as any;
+
+const registeredTools = async (active) => {
+  mockRegister.mockResolvedValue(undefined);
+  mockXray = { registerReactToolbox: mockRegister };
+  await loadToolbox().registerPlayerToolbox(manager(active));
+
+  const { tools } = mockRegister.mock.calls[0][0];
+
+  return Object.fromEntries(tools.map((tool) => [tool.name, tool.handler]));
+};
+
+describe("playerToolbox", () => {
+  beforeEach(() => {
+    mockRegister.mockReset();
+  });
+
+  it("does nothing when X-Ray has no React toolbox API", async () => {
+    mockXray = {};
+
+    await expect(
+      loadToolbox().registerPlayerToolbox(manager(null))
+    ).resolves.toBe(false);
+  });
+
+  it("does nothing when getXray returns null", async () => {
+    mockXray = null;
+
+    await expect(
+      loadToolbox().registerPlayerToolbox(manager(null))
+    ).resolves.toBe(false);
+  });
+
+  it("swallows a failed registration", async () => {
+    mockRegister.mockRejectedValue(new Error("no native bridge"));
+    mockXray = { registerReactToolbox: mockRegister };
+
+    await expect(
+      loadToolbox().registerPlayerToolbox(manager(null))
+    ).resolves.toBe(false);
+  });
+
+  it("seeks to an absolute position, from the end when negative, clamped", async () => {
+    const active = player();
+    const tools = await registeredTools(active);
+
+    expect(tools.seek({ position: 30 })).toEqual({ position: 30 });
+    expect(tools.seek({ position: -10 })).toEqual({ position: 90 });
+    expect(tools.seek({ position: 500 })).toEqual({ position: 100 });
+    expect(tools.seek({ position: -500 })).toEqual({ position: 0 });
+    expect(active.seekTo.mock.calls).toEqual([[30], [90], [100], [0]]);
+  });
+
+  it("offsets from the current position and refuses zero", async () => {
+    const tools = await registeredTools(player());
+
+    expect(tools.offset({ seconds: 15 })).toEqual({ from: 40, position: 55 });
+    expect(tools.offset({ seconds: -60 })).toEqual({ from: 40, position: 0 });
+
+    expect(() => tools.offset({ seconds: 0 })).toThrow(
+      "Ignored zero relative seek"
+    );
+  });
+
+  it("refuses to seek a stream that is not seekable", async () => {
+    const tools = await registeredTools(
+      player({ getSeekableDuration: () => 0 })
+    );
+
+    expect(() => tools.seek({ position: 10 })).toThrow("Seek is not supported");
+  });
+});

package/appUtils/playerManager/__tests__/usePlayerControllerSetup.test.tsx

@@ -0,0 +1,62 @@
+import { renderHook } from "@testing-library/react-native";
+
+import { usePlayerControllerSetup } from "../usePlayerControllerSetup";
+import { PlayerAnalyticsManager } from "../../../analyticsUtils/PlayerAnalyticsManager";
+
+const calls: string[] = [];
+
+jest.mock("../index", () => ({
+  playerManager: {
+    isPlayerRegistered: jest.fn(() => false),
+    registerPlayer: jest.fn(() => calls.push("registerPlayer")),
+    unregisterPlayer: jest.fn(),
+  },
+}));
+
+jest.mock("../../../analyticsUtils/PlayerAnalyticsManager", () => ({
+  PlayerAnalyticsManager: {
+    getInstance: jest.fn(() => calls.push("analyticsManager")),
+  },
+}));
+
+jest.mock("../../../reactHooks/useConfiguration", () => ({
+  useConfiguration: () => ({}),
+}));
+
+jest.mock("../../../playerUtils/useValidatePlayerConfig", () => ({
+  useValidatePlayerConfig: jest.fn(),
+}));
+
+jest.mock("../../../reactUtils", () => ({
+  isTV: () => false,
+}));
+
+jest.mock(
+  "@applicaster/zapp-react-native-ui-components/Helpers/Platform",
+  () => ({
+    isAppleTV: () => false,
+  })
+);
+
+class Controller {
+  destroy = jest.fn();
+}
+
+describe("usePlayerControllerSetup", () => {
+  it("creates the analytics manager before the player registers", () => {
+    renderHook(() =>
+      usePlayerControllerSetup({
+        props: { playerId: "player-1", entry: { id: "entry-1" } },
+        ControllerType: Controller,
+        ref: null,
+        manifest: {},
+        pluginId: "plugin",
+      })
+    );
+
+    // The manager attaches analytics to players as they register, so a player
+    // registered before it exists would send no player analytics events
+    expect(PlayerAnalyticsManager.getInstance).toHaveBeenCalled();
+    expect(calls).toEqual(["analyticsManager", "registerPlayer"]);
+  });
+});

package/appUtils/playerManager/const.ts

@@ -59,6 +59,19 @@ export enum SharedPlayerCallBacksKeys {
   // PIP
   OnPlayerDetached = "onPlayerDetached",
   OnPlayerAttached = "onPlayerAttached",
+
+  OnRemoteCommand = "onRemoteCommand",
+}
+
+// Ids native sends in onRemoteCommand (lock screen / Control Center / CarPlay buttons)
+export enum RemoteCommand {
+  Play = "play",
+  Pause = "pause",
+  Stop = "stop",
+  NextTrack = "nextTrack",
+  PreviousTrack = "previousTrack",
+  SkipForward = "skipForward",
+  SkipBackward = "skipBackward",
 }
 
 export enum PlayerRole {

package/appUtils/playerManager/index.ts

@@ -11,6 +11,7 @@ import {
 import { setUserLanguagePreference } from "./userLanguagePreference";
 import { PlayerRole } from "./const";
 import { RNPlayerManager } from "./nativePlayerManager";
+import { registerPlayerToolbox } from "./playerToolbox";
 
 const { log_error, log_debug, log_warning } = createLogger({
   category: "General",
@@ -54,6 +55,7 @@ export class PlayerManager {
   public static getInstance() {
     if (!PlayerManager.instance) {
       PlayerManager.instance = new PlayerManager();
+      registerPlayerToolbox(PlayerManager.instance);
     }
 
     return PlayerManager.instance;
@@ -395,6 +397,11 @@ export class PlayerManager {
     return this.manager.removeHandler(event, handler);
   }
 
+  /** Whether anything handles `event` now, e.g. a mounted PlayerContainer for "toggleFullscreen". */
+  public hasHandler(event: string) {
+    return this.manager.handlers[event]?.length > 0;
+  }
+
   // TODO: should not be
   public invokeHandler(event, ...args) {
     return this.manager.invokeHandler(event, ...args);

package/appUtils/playerManager/player.ts

@@ -746,6 +746,13 @@ export class Player {
     });
   };
 
+  onRemoteCommand = (event: QuickBrickPlayer.RemoteCommandEvent) => {
+    this.invokeListenersUpdate({
+      callbackName: SharedPlayerCallBacksKeys.OnRemoteCommand,
+      event,
+    });
+  };
+
   getTracksState = (): QuickBrickPlayer.TracksState =>
     this.playerState.trackState;
 
@@ -823,6 +830,8 @@ export class Player {
     // PIP
     onPlayerDetached: this.onPlayerDetached,
     onPlayerAttached: this.onPlayerAttached,
+
+    onRemoteCommand: this.onRemoteCommand,
   });
 
   play = () => {};
@@ -832,6 +841,7 @@ export class Player {
   setPlaybackRate = (_rate) => {};
   startSleepTimer = (_timestamp) => {};
   cancelSleepTimer = () => {};
+  command = (_command: string, _userInfo?: Record<string, any>) => {};
 
   getPluginConfiguration = () => null;
   appStateChange = (_appState, _previousAppState) => {};

package/appUtils/playerManager/playerNative.ts

@@ -6,6 +6,7 @@ import { findNodeHandle } from "react-native";
 import { PlayerRole } from "./const";
 import { toBooleanWithDefaultFalse } from "../../booleanUtils";
 import { RNPlayerManager } from "./nativePlayerManager";
+import { isApplePlatform } from "../../reactUtils";
 
 const logger = createLogger({
   category: "PlayerNativeController",
@@ -27,6 +28,7 @@ interface PlayerMethods {
   appStateChange?: (appState: string, previousAppState: string) => void;
   closeNativePlayer?: () => void;
   togglePlayPause?: () => void;
+  command?: (command: string, userInfo?: Record<string, any>) => void;
 }
 
 type PlayerComponent = ReactComponent<PlayerRefProps> & PlayerMethods;
@@ -52,6 +54,7 @@ const PlayerModuleFuncNames = {
   startSleepTimer: "startSleepTimer",
   cancelSleepTimer: "cancelSleepTimer",
   getSleepTimerEnd: "getSleepTimerEnd",
+  command: "command",
 };
 
 export class PlayerNative extends Player {
@@ -206,6 +209,25 @@ export class PlayerNative extends Player {
     }
   };
 
+  command = (command: string, userInfo?: Record<string, any>) => {
+    if (isApplePlatform()) {
+      const module = this.getPlayerModule();
+      module?.command?.(command, this.playerId, userInfo);
+
+      return true;
+    }
+
+    if (
+      !this.invokeNativeFunction(
+        PlayerModuleFuncNames.command,
+        command,
+        userInfo
+      )
+    ) {
+      this.currentPlayerComponent()?.command?.(command, userInfo);
+    }
+  };
+
   disableBufferAnimation = (): boolean => false;
 
   selectTrack = (

package/appUtils/playerManager/playerNativeCommand.ts

@@ -1,14 +1,11 @@
 import { isApplePlatform } from "../../reactUtils";
 import { NativeModules } from "react-native";
 
-const NativePlayerModule = isApplePlatform()
-  ? NativeModules.PlayerModule
-  : NativeModules.QuickBrickDefaultPlayerModule;
-
 const PlayerNativeCommandTypes = {
   pause: "pause",
   clearPlayerData: "clearPlayerData",
   removeViewByNativeId: "removeViewByNativeId",
+  setPlayerControls: "setPlayerControls",
 };
 
 const PlayerNativeSendCommand = (
@@ -16,8 +13,8 @@ const PlayerNativeSendCommand = (
   playerId: string,
   userInfo?: Record<string, any>
 ) => {
-  if (playerId && command) {
-    NativePlayerModule?.command?.(command, playerId, userInfo);
+  if (isApplePlatform() && playerId && command) {
+    NativeModules.PlayerModule?.command?.(command, playerId, userInfo);
   }
 };
 

package/appUtils/playerManager/playerToolbox.ts

@@ -0,0 +1,157 @@
+import { registerXrayToolbox, XrayToolSpec } from "../../logger/xrayToolbox";
+import type { PlayerManager } from "./index";
+
+/**
+ * X-Ray `player.*` toolbox: lets an agent read and drive the active player without screenshots.
+ * Registered by the PlayerManager singleton itself, so it exists wherever players do. Skipped
+ * when the installed X-Ray plugin has no React toolbox API.
+ *
+ * How the player is shown (video modal mode, mini player) is navigation state: see `nav.*`.
+ */
+
+const toNumber = (value: unknown) =>
+  typeof value === "number" && Number.isFinite(value) ? value : null;
+
+const clamp = (value: number, max: number) => Math.min(Math.max(value, 0), max);
+
+/** The range a seek can reach: the DVR window on live, the content on VOD. */
+const requireSeekable = (player: {
+  getSeekableDuration: () => number | undefined;
+}) => {
+  const seekable = toNumber(player.getSeekableDuration());
+
+  if (!seekable) throw new Error("Seek is not supported");
+
+  return seekable;
+};
+
+const tools = (manager: PlayerManager): XrayToolSpec[] => {
+  const requirePlayer = () => {
+    const player = manager.getActivePlayer();
+
+    if (!player) throw new Error("No active player");
+
+    return player;
+  };
+
+  return [
+    {
+      name: "state",
+      description:
+        "The active player: entry, position and duration in seconds, playing/buffering/ad/live/muted, " +
+        "role (Primary, Cell, Chromecast) and casting. active: false when nothing plays.",
+      handler: () => {
+        const player = manager.getActivePlayer();
+
+        if (!player) return { active: false, casting: manager.isCasting() };
+
+        const entry = player.getEntry();
+
+        return {
+          active: true,
+          playerId: player.playerId,
+          entry: entry ? { id: entry.id, title: entry.title } : null,
+          position: toNumber(player.getPosition()),
+          duration: toNumber(player.getDuration()),
+          // isPlaying() only means "not paused", which is also true before the stream starts.
+          playing: !!player.isReadyToPlay() && player.isPlaying(),
+          buffering: !!player.isBuffering(),
+          readyToPlay: !!player.isReadyToPlay(),
+          ad: player.isAd(),
+          live: !!player.isLive(),
+          muted: !!player.getIsMuted(),
+          role: player.playerRole,
+          casting: manager.isCasting(),
+        };
+      },
+    },
+    {
+      name: "play",
+      description: "Resume the active player.",
+      handler: () => {
+        requirePlayer().play();
+
+        return "OK";
+      },
+    },
+    {
+      name: "pause",
+      description: "Pause the active player.",
+      handler: () => {
+        requirePlayer().pause();
+
+        return "OK";
+      },
+    },
+    {
+      name: "seek",
+      description:
+        "Seek to an absolute position, as the player's console command does: seconds from the start, " +
+        "or from the end when negative. Clamped to the seekable range. Where it lands can differ: " +
+        "server-side ads snap back to the break before the target; read player.state afterwards.",
+      parameters: [
+        {
+          name: "position",
+          type: "number",
+          description:
+            "Seconds from the start; negative values count back from the end.",
+        },
+      ],
+      handler: ({ position }) => {
+        const player = requirePlayer();
+        const seconds = toNumber(position);
+
+        if (seconds === null) {
+          throw new Error("'position' must be a number of seconds");
+        }
+
+        const seekable = requireSeekable(player);
+
+        const target =
+          seconds >= 0
+            ? Math.min(seconds, seekable)
+            : clamp(seekable + seconds, seekable);
+
+        player.seekTo(target);
+
+        return { position: target };
+      },
+    },
+    {
+      name: "offset",
+      description:
+        "Seek relative to the current position, as the player's console command does: positive " +
+        "forward, negative back. Clamped to the seekable range.",
+      parameters: [
+        {
+          name: "seconds",
+          type: "number",
+          description: "Seconds to move: positive forward, negative back.",
+        },
+      ],
+      handler: ({ seconds }) => {
+        const player = requirePlayer();
+        const delta = toNumber(seconds);
+
+        if (delta === null) throw new Error("'seconds' must be a number");
+
+        if (delta === 0) throw new Error("Ignored zero relative seek");
+
+        const seekable = requireSeekable(player);
+        const from = toNumber(player.getContentPosition()) ?? 0;
+        const target = clamp(from + delta, seekable);
+
+        player.seekTo(target);
+
+        return { from, position: target };
+      },
+    },
+  ];
+};
+
+export const registerPlayerToolbox = (manager: PlayerManager) =>
+  registerXrayToolbox({
+    name: "player",
+    description: "Inspect and control the active player.",
+    tools: tools(manager),
+  });

package/appUtils/playerManager/usePlayerControllerSetup.tsx

@@ -8,6 +8,7 @@ import { isAppleTV } from "@applicaster/zapp-react-native-ui-components/Helpers/
 import { TVSeekController } from "../../reactHooks/player/TVSeekControlller/TVSeekController";
 import { KeyInputHandler } from "../keyInputHandler/KeyInputHandler";
 import { isTV } from "../../reactUtils";
+import { PlayerAnalyticsManager } from "../../analyticsUtils/PlayerAnalyticsManager";
 
 // TODO: Rename to ControllerType
 export const usePlayerControllerSetup = ({
@@ -68,6 +69,11 @@ export const usePlayerControllerSetup = ({
       return;
     }
 
+    // The analytics manager attaches its listener when a player registers, so it
+    // must exist first; on web the Player wrapper that also creates it renders
+    // only after the lazily loaded engine chunk, i.e. after registration.
+    PlayerAnalyticsManager.getInstance();
+
     playerManager.registerPlayer({
       id: playerId,
       playerController,

package/arrayUtils/__tests__/reorderByIds.test.ts

@@ -47,4 +47,17 @@ describe("reorderByIds", () => {
 
     expect(result.map((i) => i.key)).toEqual(["c", "b", "a"]);
   });
+
+  it("reorders duplicate items when using unique slot identifiers via getId", () => {
+    const duplicateItems = [
+      { id: "x", slot: "s1", name: "First X" },
+      { id: "y", slot: "s2", name: "Y" },
+      { id: "x", slot: "s3", name: "Second X" },
+    ];
+
+    const result = reorderByIds(duplicateItems, ["s3", "s1"], (i) => i.slot);
+
+    expect(result).toHaveLength(3);
+    expect(result.map((i) => i.name)).toEqual(["Second X", "Y", "First X"]);
+  });
 });

package/arrayUtils/index.ts

@@ -167,7 +167,7 @@ export const anyTruthy = (xs: boolean[]) => xs.some(Boolean);
 export function reorderByIds<T>(
   items: T[],
   orderedIds: string[],
-  getId: (item: T) => string | string[] = (item: any) => item?.id
+  getId: (item: T) => string = (item: any) => item?.id
 ): T[] {
   if (!items || items.length === 0) return [];
   if (!orderedIds || orderedIds.length === 0) return [...items];
@@ -175,14 +175,16 @@ export function reorderByIds<T>(
   const itemMap = new Map<string, T>();
 
   items.forEach((item) => {
-    const rawId = getId(item);
-    const keys = Array.isArray(rawId) ? rawId : [rawId];
-
-    keys.forEach((key) => {
-      if (key !== undefined && key !== null && key !== "") {
-        itemMap.set(String(key), item);
-      }
-    });
+    const id = getId(item);
+
+    if (
+      id !== undefined &&
+      id !== null &&
+      id !== "" &&
+      !itemMap.has(String(id))
+    ) {
+      itemMap.set(String(id), item);
+    }
   });
 
   const reorderedSubset: T[] = [];
@@ -192,48 +194,29 @@ export function reorderByIds<T>(
     const strId = String(id);
     const item = itemMap.get(strId);
 
-    if (item && !reorderedSubset.includes(item)) {
+    if (item && !orderedIdsSet.has(strId)) {
       reorderedSubset.push(item);
-      const rawId = getId(item);
-      const keys = Array.isArray(rawId) ? rawId : [rawId];
-
-      keys.forEach((k) => {
-        if (k !== undefined && k !== null && k !== "") {
-          orderedIdsSet.add(String(k));
-        }
-      });
+      orderedIdsSet.add(strId);
     }
   });
 
   if (reorderedSubset.length === 0) return [...items];
 
   let subsetIdx = 0;
-  const result: T[] = [];
-
-  items.forEach((item) => {
-    const rawId = getId(item);
-    const keys = Array.isArray(rawId) ? rawId : [rawId];
-
-    const isMatched = keys.some(
-      (k) =>
-        k !== undefined &&
-        k !== null &&
-        k !== "" &&
-        orderedIdsSet.has(String(k))
-    );
 
-    if (isMatched) {
-      if (subsetIdx < reorderedSubset.length) {
-        result.push(reorderedSubset[subsetIdx++]);
-      }
-    } else {
-      result.push(item);
+  return items.map((item) => {
+    const id = getId(item);
+
+    if (
+      id !== undefined &&
+      id !== null &&
+      id !== "" &&
+      orderedIdsSet.has(String(id)) &&
+      subsetIdx < reorderedSubset.length
+    ) {
+      return reorderedSubset[subsetIdx++];
     }
-  });
-
-  while (subsetIdx < reorderedSubset.length) {
-    result.push(reorderedSubset[subsetIdx++]);
-  }
 
-  return result;
+    return item;
+  });
 }