@applicaster/quick-brick-player 16.0.0-alpha.1593888345 → 16.0.0-alpha.1701179921

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/quick-brick-player",
-  "version": "16.0.0-alpha.1593888345",
+  "version": "16.0.0-alpha.1701179921",
   "description": "Quick Brick Player",
   "main": "./src/index.ts",
   "types": "index.d.ts",
@@ -35,11 +35,11 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/quick-brick-mobile-transport-controls": "16.0.0-rc.73",
+    "@applicaster/quick-brick-mobile-transport-controls": "16.0.0-rc.93",
     "@applicaster/quick-brick-tv-transport-controls": "16.0.0-rc.69",
-    "@applicaster/zapp-react-native-tvos-app": "16.0.0-alpha.1593888345",
-    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.1593888345",
-    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.1593888345",
+    "@applicaster/zapp-react-native-tvos-app": "16.0.0-alpha.1701179921",
+    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.1701179921",
+    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.1701179921",
     "query-string": "7.1.3",
     "shaka-player": "4.3.5",
     "typeface-montserrat": "^0.0.54",

package/src/Player/AudioLayer/PlaylistNavigationController.ts

@@ -0,0 +1,354 @@
+import { BehaviorSubject } from "rxjs";
+import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
+import { findPluginByIdentifier } from "@applicaster/zapp-react-native-utils/pluginUtils";
+import { loadFeedEntry } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils";
+import { createLogger } from "@applicaster/zapp-react-native-utils/logger";
+
+const { log_error, log_info } = createLogger({
+  subsystem: "Player",
+  category: "PlaylistNavigationController",
+});
+
+export const RESTART_THRESHOLD_SECONDS = 3;
+
+export interface PlayerSeeker {
+  seekTo: (time: number) => void;
+}
+
+export interface PlayerNavigator {
+  replaceTop: (entry: ZappEntry) => void;
+}
+
+export interface PlaylistNavigationControllerOptions {
+  entry: ZappEntry;
+  player: PlayerSeeker;
+  navigator: PlayerNavigator;
+  playerState?: QuickBrickPlayer.PlayerState;
+}
+
+export class PlaylistNavigationController {
+  public readonly hasNext$: BehaviorSubject<boolean>;
+  public readonly hasPrevious$: BehaviorSubject<boolean>;
+
+  private entry: ZappEntry;
+  private player: PlayerSeeker;
+  private navigator: PlayerNavigator;
+  private playerState: QuickBrickPlayer.PlayerState | undefined;
+  private isNavigating = false;
+  private unsubscribeQueueListener: (() => void) | null = null;
+  private isDestroyed = false;
+  private recalculateGeneration = 0;
+
+  constructor(options: PlaylistNavigationControllerOptions) {
+    this.entry = options.entry;
+    this.player = options.player;
+    this.navigator = options.navigator;
+    this.playerState = options.playerState;
+
+    const staticNextUrl = this.entry?.extensions?.play_next_feed_url;
+    const staticPrevUrl = this.entry?.extensions?.play_previous_feed_url;
+    const canRestart = (this.playerState?.seekableDuration ?? 0) > 0;
+
+    this.hasNext$ = new BehaviorSubject<boolean>(Boolean(staticNextUrl));
+
+    this.hasPrevious$ = new BehaviorSubject<boolean>(
+      Boolean(staticPrevUrl) || canRestart
+    );
+
+    this.subscribeToQueue();
+    this.recalculate();
+  }
+
+  public updateContext(
+    options: Partial<PlaylistNavigationControllerOptions>
+  ): void {
+    if (options.player) {
+      this.player = options.player;
+    }
+
+    if (options.navigator) {
+      this.navigator = options.navigator;
+    }
+
+    let needsRecalculate = false;
+
+    if (options.entry) {
+      const isSameEntry =
+        this.entry?.id === options.entry?.id &&
+        this.entry?.extensions?.queueItemId ===
+          options.entry?.extensions?.queueItemId;
+
+      if (!isSameEntry) {
+        this.entry = options.entry;
+        needsRecalculate = true;
+      } else {
+        this.entry = options.entry;
+      }
+    }
+
+    if (options.playerState) {
+      const prevCanRestart = (this.playerState?.seekableDuration ?? 0) > 0;
+      const newCanRestart = (options.playerState?.seekableDuration ?? 0) > 0;
+      this.playerState = options.playerState;
+
+      if (prevCanRestart !== newCanRestart) {
+        needsRecalculate = true;
+      }
+    }
+
+    if (needsRecalculate) {
+      this.recalculate();
+    }
+  }
+
+  public updatePlayerState(playerState?: QuickBrickPlayer.PlayerState): void {
+    const prevCanRestart = (this.playerState?.seekableDuration ?? 0) > 0;
+    const newCanRestart = (playerState?.seekableDuration ?? 0) > 0;
+    this.playerState = playerState;
+
+    if (prevCanRestart !== newCanRestart) {
+      this.recalculate();
+    }
+  }
+
+  public updateEntry(entry: ZappEntry): void {
+    if (
+      this.entry?.id === entry?.id &&
+      this.entry?.extensions?.queueItemId === entry?.extensions?.queueItemId
+    ) {
+      this.entry = entry;
+
+      return;
+    }
+
+    this.entry = entry;
+    this.recalculate();
+  }
+
+  private getQueueManagerInstance() {
+    try {
+      const plugins = appStore?.get?.("plugins") || [];
+      const queuePlugin = findPluginByIdentifier("queue-action", plugins, true);
+      const module = (queuePlugin as any)?.module;
+      const QueueManager = module?.QueueManager;
+      const setupQuickBrickQueue = module?.setupQuickBrickQueue;
+
+      if (
+        QueueManager &&
+        !QueueManager.isInitialized?.() &&
+        typeof setupQuickBrickQueue === "function"
+      ) {
+        setupQuickBrickQueue();
+      }
+
+      if (QueueManager?.isInitialized?.()) {
+        return QueueManager.instance;
+      }
+    } catch {
+      // Safe fallback when store or plugin is not available
+    }
+
+    return null;
+  }
+
+  private subscribeToQueue(): void {
+    const queueManager = this.getQueueManagerInstance();
+
+    if (queueManager?.addListener) {
+      this.unsubscribeQueueListener = queueManager.addListener(() => {
+        if (!this.isDestroyed) {
+          this.recalculate();
+        }
+      });
+    }
+  }
+
+  private async getQueueData(): Promise<{
+    upcoming: ZappEntry[];
+    history: ZappEntry[];
+  }> {
+    const queueManager = this.getQueueManagerInstance();
+
+    if (!queueManager) {
+      return { upcoming: [], history: [] };
+    }
+
+    try {
+      const [upcoming, history] = await Promise.all([
+        queueManager.getUpcomingQueue?.() ?? [],
+        queueManager.getHistoryQueue?.() ?? [],
+      ]);
+
+      return {
+        upcoming: Array.isArray(upcoming) ? upcoming : [],
+        history: Array.isArray(history) ? history : [],
+      };
+    } catch (error) {
+      log_error("PlaylistNavigationController: Error fetching queue items", {
+        error,
+      });
+
+      return { upcoming: [], history: [] };
+    }
+  }
+
+  public async recalculate(): Promise<void> {
+    if (this.isDestroyed) return;
+
+    const generation = ++this.recalculateGeneration;
+    const { upcoming, history } = await this.getQueueData();
+
+    if (this.isDestroyed || generation !== this.recalculateGeneration) {
+      return;
+    }
+
+    const staticNextUrl = this.entry?.extensions?.play_next_feed_url;
+    const staticPrevUrl = this.entry?.extensions?.play_previous_feed_url;
+
+    const hasNext = upcoming.length > 0 || Boolean(staticNextUrl);
+
+    const canRestart = (this.playerState?.seekableDuration ?? 0) > 0;
+
+    const hasPrevious =
+      history.length > 0 || Boolean(staticPrevUrl) || canRestart;
+
+    if (this.hasNext$.getValue() !== hasNext) {
+      this.hasNext$.next(hasNext);
+    }
+
+    if (this.hasPrevious$.getValue() !== hasPrevious) {
+      this.hasPrevious$.next(hasPrevious);
+    }
+  }
+
+  public async goNext(): Promise<void> {
+    if (this.isNavigating || this.isDestroyed) {
+      return;
+    }
+
+    this.isNavigating = true;
+
+    try {
+      const { upcoming } = await this.getQueueData();
+
+      if (this.isDestroyed) return;
+
+      if (upcoming.length > 0) {
+        const nextItem = upcoming[0];
+
+        log_info(
+          `goNext: playing next item from queue "${nextItem.title}", id: ${nextItem.id}`,
+          { targetId: nextItem.id }
+        );
+
+        if (this.isDestroyed) return;
+        this.navigator?.replaceTop?.(nextItem);
+
+        return;
+      }
+
+      const staticNextUrl = this.entry?.extensions?.play_next_feed_url;
+
+      if (staticNextUrl) {
+        const target = await loadFeedEntry(staticNextUrl, this.entry);
+
+        if (this.isDestroyed) return;
+
+        log_info(
+          `goNext: playing "${target.title}", id: ${target.id} from remote feed`,
+          {
+            staticNextUrl,
+            targetId: target.id,
+          }
+        );
+
+        this.navigator?.replaceTop?.(target);
+      }
+    } catch (error) {
+      log_error("goNext: could not navigate to next entry", { error });
+    } finally {
+      this.isNavigating = false;
+    }
+  }
+
+  public async goPrevious(): Promise<void> {
+    if (this.isNavigating || this.isDestroyed) {
+      return;
+    }
+
+    this.isNavigating = true;
+
+    try {
+      const { history } = await this.getQueueData();
+
+      if (this.isDestroyed) return;
+
+      const staticPrevUrl = this.entry?.extensions?.play_previous_feed_url;
+
+      const currentTime = this.playerState?.currentTime ?? 0;
+      const canRestart = (this.playerState?.seekableDuration ?? 0) > 0;
+
+      const hasQueueHistory = history.length > 0;
+      const hasStaticPrev = Boolean(staticPrevUrl);
+
+      const hasTarget = hasQueueHistory || hasStaticPrev;
+
+      const shouldRestart =
+        canRestart && (currentTime > RESTART_THRESHOLD_SECONDS || !hasTarget);
+
+      if (shouldRestart) {
+        if (this.isDestroyed) return;
+        this.player?.seekTo?.(0);
+
+        return;
+      }
+
+      if (hasQueueHistory) {
+        const prevItem = history[history.length - 1];
+
+        log_info(
+          `goPrevious: playing previous item from queue "${prevItem.title}", id: ${prevItem.id}`,
+          { targetId: prevItem.id }
+        );
+
+        if (this.isDestroyed) return;
+        this.navigator?.replaceTop?.(prevItem);
+
+        return;
+      }
+
+      if (hasStaticPrev) {
+        const target = await loadFeedEntry(staticPrevUrl, this.entry);
+
+        if (this.isDestroyed) return;
+
+        log_info(
+          `goPrevious: playing "${target.title}", id: ${target.id} from remote feed`,
+          {
+            staticPrevUrl,
+            targetId: target.id,
+          }
+        );
+
+        this.navigator?.replaceTop?.(target);
+      }
+    } catch (error) {
+      log_error("goPrevious: could not navigate to previous entry", { error });
+    } finally {
+      this.isNavigating = false;
+    }
+  }
+
+  public destroy(): void {
+    this.isDestroyed = true;
+    this.recalculateGeneration++;
+
+    if (this.unsubscribeQueueListener) {
+      this.unsubscribeQueueListener();
+      this.unsubscribeQueueListener = null;
+    }
+
+    this.hasNext$.complete();
+    this.hasPrevious$.complete();
+  }
+}

package/src/Player/AudioLayer/__tests__/PlaylistNavigationController.test.ts

@@ -0,0 +1,528 @@
+import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
+import { findPluginByIdentifier } from "@applicaster/zapp-react-native-utils/pluginUtils";
+import { loadFeedEntry } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils";
+import {
+  PlaylistNavigationController,
+  RESTART_THRESHOLD_SECONDS,
+} from "../PlaylistNavigationController";
+
+jest.mock("@applicaster/zapp-react-native-redux/AppStore", () => ({
+  appStore: {
+    get: jest.fn(),
+  },
+}));
+
+jest.mock("@applicaster/zapp-react-native-utils/pluginUtils", () => ({
+  findPluginByIdentifier: jest.fn(),
+}));
+
+jest.mock(
+  "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils",
+  () => ({
+    loadFeedEntry: jest.fn(),
+  })
+);
+
+const appStoreMock = appStore as unknown as { get: jest.Mock };
+const findPluginByIdentifierMock = findPluginByIdentifier as jest.Mock;
+const loadFeedEntryMock = loadFeedEntry as jest.Mock;
+
+const NEXT_URL = "https://feeds/next.json";
+const PREV_URL = "https://feeds/prev.json";
+
+const entryWith = (extensions: Record<string, unknown>): ZappEntry =>
+  ({
+    id: "current",
+    title: "Current Track",
+    type: { value: "audio" },
+    extensions,
+  }) as ZappEntry;
+
+const stateAt = (
+  currentTime: number,
+  seekableDuration = 600
+): QuickBrickPlayer.PlayerState =>
+  ({ currentTime, seekableDuration }) as QuickBrickPlayer.PlayerState;
+
+const NOT_SEEKABLE = 0;
+
+describe("PlaylistNavigationController", () => {
+  let player: { seekTo: jest.Mock };
+  let navigator: { replaceTop: jest.Mock };
+  let mockQueueManager: any;
+
+  beforeEach(() => {
+    player = { seekTo: jest.fn() };
+    navigator = { replaceTop: jest.fn() };
+    loadFeedEntryMock.mockReset();
+
+    mockQueueManager = {
+      isInitialized: jest.fn().mockReturnValue(false),
+      instance: {
+        getUpcomingQueue: jest.fn().mockResolvedValue([]),
+        getHistoryQueue: jest.fn().mockResolvedValue([]),
+        addListener: jest.fn().mockReturnValue(jest.fn()),
+      },
+    };
+
+    appStoreMock.get.mockReturnValue([]);
+    findPluginByIdentifierMock.mockReturnValue(null);
+  });
+
+  describe("static URL feeds (no queue)", () => {
+    it("reports both directions available when both static extensions are present", async () => {
+      const entry = entryWith({
+        play_next_feed_url: NEXT_URL,
+        play_previous_feed_url: PREV_URL,
+      });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(0),
+      });
+
+      await controller.recalculate();
+
+      expect(controller.hasNext$.getValue()).toBe(true);
+      expect(controller.hasPrevious$.getValue()).toBe(true);
+
+      controller.destroy();
+    });
+
+    it("keeps previous available at head of chain when track is seekable", async () => {
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(0),
+      });
+
+      await controller.recalculate();
+
+      expect(controller.hasNext$.getValue()).toBe(true);
+      expect(controller.hasPrevious$.getValue()).toBe(true);
+
+      controller.destroy();
+    });
+
+    it("reports no previous when track is not seekable and has no previous extension", async () => {
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(0, NOT_SEEKABLE),
+      });
+
+      await controller.recalculate();
+
+      expect(controller.hasNext$.getValue()).toBe(true);
+      expect(controller.hasPrevious$.getValue()).toBe(false);
+
+      controller.destroy();
+    });
+
+    it("fetches and plays next remote feed entry on goNext", async () => {
+      const target = { id: "next-track", title: "Next" } as ZappEntry;
+      loadFeedEntryMock.mockResolvedValue(target);
+
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(0),
+      });
+
+      await controller.goNext();
+
+      expect(loadFeedEntryMock).toHaveBeenCalledWith(NEXT_URL, entry);
+      expect(navigator.replaceTop).toHaveBeenCalledWith(target);
+
+      controller.destroy();
+    });
+
+    it("restarts playback when currentTime > RESTART_THRESHOLD_SECONDS", async () => {
+      const entry = entryWith({ play_previous_feed_url: PREV_URL });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(RESTART_THRESHOLD_SECONDS + 1),
+      });
+
+      await controller.goPrevious();
+
+      expect(player.seekTo).toHaveBeenCalledWith(0);
+      expect(loadFeedEntryMock).not.toHaveBeenCalled();
+      expect(navigator.replaceTop).not.toHaveBeenCalled();
+
+      controller.destroy();
+    });
+
+    it("fetches and plays previous remote feed entry when currentTime <= RESTART_THRESHOLD_SECONDS", async () => {
+      const target = { id: "prev-track", title: "Previous" } as ZappEntry;
+      loadFeedEntryMock.mockResolvedValue(target);
+
+      const entry = entryWith({ play_previous_feed_url: PREV_URL });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(1),
+      });
+
+      await controller.goPrevious();
+
+      expect(player.seekTo).not.toHaveBeenCalled();
+      expect(loadFeedEntryMock).toHaveBeenCalledWith(PREV_URL, entry);
+      expect(navigator.replaceTop).toHaveBeenCalledWith(target);
+
+      controller.destroy();
+    });
+  });
+
+  describe("queue navigation (QueueManager active)", () => {
+    let queueListener: () => void;
+
+    beforeEach(() => {
+      mockQueueManager.isInitialized.mockReturnValue(true);
+
+      mockQueueManager.instance.addListener.mockImplementation(
+        (cb: () => void) => {
+          queueListener = cb;
+
+          return jest.fn();
+        }
+      );
+
+      findPluginByIdentifierMock.mockReturnValue({
+        module: { QueueManager: mockQueueManager },
+      });
+    });
+
+    it("reports availability based on upcoming and history queues", async () => {
+      const upcomingItem = { id: "next_in_queue" } as ZappEntry;
+      const historyItem = { id: "prev_in_queue" } as ZappEntry;
+
+      mockQueueManager.instance.getUpcomingQueue.mockResolvedValue([
+        upcomingItem,
+      ]);
+
+      mockQueueManager.instance.getHistoryQueue.mockResolvedValue([
+        historyItem,
+      ]);
+
+      const controller = new PlaylistNavigationController({
+        entry: entryWith({}),
+        player,
+        navigator,
+        playerState: stateAt(0, NOT_SEEKABLE),
+      });
+
+      await controller.recalculate();
+
+      expect(controller.hasNext$.getValue()).toBe(true);
+      expect(controller.hasPrevious$.getValue()).toBe(true);
+
+      controller.destroy();
+    });
+
+    it("navigates directly to upcoming item on goNext without Pipes roundtrip", async () => {
+      const nextQueueItem = {
+        id: "queue_item_2",
+        title: "Second Track",
+      } as ZappEntry;
+
+      mockQueueManager.instance.getUpcomingQueue.mockResolvedValue([
+        nextQueueItem,
+      ]);
+
+      const controller = new PlaylistNavigationController({
+        entry: entryWith({}),
+        player,
+        navigator,
+        playerState: stateAt(0),
+      });
+
+      await controller.goNext();
+
+      expect(loadFeedEntryMock).not.toHaveBeenCalled();
+      expect(navigator.replaceTop).toHaveBeenCalledWith(nextQueueItem);
+
+      controller.destroy();
+    });
+
+    it("navigates directly to history item on goPrevious without Pipes roundtrip when <= 3s", async () => {
+      const prevQueueItem = {
+        id: "queue_item_0",
+        title: "Zero Track",
+      } as ZappEntry;
+
+      mockQueueManager.instance.getHistoryQueue.mockResolvedValue([
+        prevQueueItem,
+      ]);
+
+      const controller = new PlaylistNavigationController({
+        entry: entryWith({}),
+        player,
+        navigator,
+        playerState: stateAt(1),
+      });
+
+      await controller.goPrevious();
+
+      expect(player.seekTo).not.toHaveBeenCalled();
+      expect(loadFeedEntryMock).not.toHaveBeenCalled();
+      expect(navigator.replaceTop).toHaveBeenCalledWith(prevQueueItem);
+
+      controller.destroy();
+    });
+
+    it("recalculates streams when QueueManager listener fires", async () => {
+      mockQueueManager.instance.getUpcomingQueue.mockResolvedValue([]);
+      mockQueueManager.instance.getHistoryQueue.mockResolvedValue([]);
+
+      const controller = new PlaylistNavigationController({
+        entry: entryWith({}),
+        player,
+        navigator,
+        playerState: stateAt(0, NOT_SEEKABLE),
+      });
+
+      await controller.recalculate();
+      expect(controller.hasNext$.getValue()).toBe(false);
+
+      // Simulate item enqueued
+      mockQueueManager.instance.getUpcomingQueue.mockResolvedValue([
+        { id: "new_item" },
+      ]);
+
+      queueListener();
+
+      // Wait a tick for async recalculate
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(controller.hasNext$.getValue()).toBe(true);
+
+      controller.destroy();
+    });
+
+    it("prevents duplicate navigation calls while in-flight", async () => {
+      const target = { id: "next-track" } as ZappEntry;
+      let resolvePromise: (value: ZappEntry) => void;
+
+      loadFeedEntryMock.mockReturnValue(
+        new Promise((resolve) => {
+          resolvePromise = resolve;
+        })
+      );
+
+      const entry = entryWith({ play_next_feed_url: NEXT_URL });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(0),
+      });
+
+      // First tap starts flight
+      const firstTap = controller.goNext();
+      // Second tap while in-flight
+      const secondTap = controller.goNext();
+
+      resolvePromise!(target);
+      await Promise.all([firstTap, secondTap]);
+
+      expect(loadFeedEntryMock).toHaveBeenCalledTimes(1);
+      expect(navigator.replaceTop).toHaveBeenCalledTimes(1);
+
+      controller.destroy();
+    });
+
+    it("prevents duplicate goPrevious calls while in-flight", async () => {
+      const target = { id: "prev-track" } as ZappEntry;
+      let resolvePromise: (value: ZappEntry) => void;
+
+      loadFeedEntryMock.mockReturnValue(
+        new Promise((resolve) => {
+          resolvePromise = resolve;
+        })
+      );
+
+      const entry = entryWith({ play_previous_feed_url: PREV_URL });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(1),
+      });
+
+      const firstTap = controller.goPrevious();
+      const secondTap = controller.goPrevious();
+
+      resolvePromise!(target);
+      await Promise.all([firstTap, secondTap]);
+
+      expect(loadFeedEntryMock).toHaveBeenCalledTimes(1);
+      expect(navigator.replaceTop).toHaveBeenCalledTimes(1);
+
+      controller.destroy();
+    });
+
+    it("prioritizes queue navigation over static feed URLs even when entry is not from queue", async () => {
+      const queueNextItem = { id: "queue_next" } as ZappEntry;
+      const queuePrevItem = { id: "queue_prev" } as ZappEntry;
+      const staticNextTarget = { id: "static_next" } as ZappEntry;
+      const staticPrevTarget = { id: "static_prev" } as ZappEntry;
+
+      mockQueueManager.instance.getUpcomingQueue.mockResolvedValue([
+        queueNextItem,
+      ]);
+
+      mockQueueManager.instance.getHistoryQueue.mockResolvedValue([
+        queuePrevItem,
+      ]);
+
+      loadFeedEntryMock.mockImplementation((url) =>
+        Promise.resolve(url === NEXT_URL ? staticNextTarget : staticPrevTarget)
+      );
+
+      const entry = entryWith({
+        play_next_feed_url: NEXT_URL,
+        play_previous_feed_url: PREV_URL,
+      });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(1),
+      });
+
+      await controller.goNext();
+      expect(loadFeedEntryMock).not.toHaveBeenCalled();
+      expect(navigator.replaceTop).toHaveBeenCalledWith(queueNextItem);
+
+      await controller.goPrevious();
+      expect(loadFeedEntryMock).not.toHaveBeenCalled();
+      expect(navigator.replaceTop).toHaveBeenCalledWith(queuePrevItem);
+
+      controller.destroy();
+    });
+
+    it("falls back to static feed URLs when queue is empty", async () => {
+      const staticNextTarget = { id: "static_next" } as ZappEntry;
+      const staticPrevTarget = { id: "static_prev" } as ZappEntry;
+
+      mockQueueManager.instance.getUpcomingQueue.mockResolvedValue([]);
+      mockQueueManager.instance.getHistoryQueue.mockResolvedValue([]);
+
+      loadFeedEntryMock.mockImplementation((url) =>
+        Promise.resolve(url === NEXT_URL ? staticNextTarget : staticPrevTarget)
+      );
+
+      const entry = entryWith({
+        play_next_feed_url: NEXT_URL,
+        play_previous_feed_url: PREV_URL,
+      });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(1),
+      });
+
+      await controller.goNext();
+      expect(loadFeedEntryMock).toHaveBeenCalledWith(NEXT_URL, entry);
+      expect(navigator.replaceTop).toHaveBeenCalledWith(staticNextTarget);
+
+      await controller.goPrevious();
+      expect(loadFeedEntryMock).toHaveBeenCalledWith(PREV_URL, entry);
+      expect(navigator.replaceTop).toHaveBeenCalledWith(staticPrevTarget);
+
+      controller.destroy();
+    });
+
+    it("ignores stale recalculate resolution when newer recalculate was called", async () => {
+      let resolveFirst: (val: any) => void;
+
+      const firstPromise = new Promise<{
+        upcoming: ZappEntry[];
+        history: ZappEntry[];
+      }>((resolve) => {
+        resolveFirst = resolve;
+      });
+
+      const entry = entryWith({});
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(0, NOT_SEEKABLE),
+      });
+
+      // Override getUpcomingQueue to control resolution order
+      mockQueueManager.instance.getUpcomingQueue
+        .mockReturnValueOnce(firstPromise.then((d) => d.upcoming))
+        .mockResolvedValueOnce([{ id: "second_call_item" }]);
+
+      // First recalculate (will hang until resolveFirst)
+      const recalc1 = controller.recalculate();
+
+      // Second recalculate resolves immediately with hasNext = true
+      const recalc2 = controller.recalculate();
+      await recalc2;
+      expect(controller.hasNext$.getValue()).toBe(true);
+
+      // Now resolve first with empty array; should NOT overwrite hasNext$ to false
+      resolveFirst!({ upcoming: [], history: [] });
+      await recalc1;
+      expect(controller.hasNext$.getValue()).toBe(true);
+
+      controller.destroy();
+    });
+
+    it("does not navigate if controller is destroyed while resolving feed entry", async () => {
+      let resolvePromise: (value: ZappEntry) => void;
+
+      loadFeedEntryMock.mockReturnValue(
+        new Promise((resolve) => {
+          resolvePromise = resolve;
+        })
+      );
+
+      const entry = entryWith({
+        play_next_feed_url: NEXT_URL,
+        play_previous_feed_url: PREV_URL,
+      });
+
+      const controller = new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState: stateAt(1),
+      });
+
+      const goNextPromise = controller.goNext();
+      controller.destroy();
+
+      resolvePromise!({ id: "target" } as ZappEntry);
+      await goNextPromise;
+
+      expect(navigator.replaceTop).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/Player/AudioLayer/__tests__/usePlaylistNavigation.test.ts

@@ -2,8 +2,12 @@ import { renderHook, act } from "@testing-library/react-native";
 import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
 import { usePlayer } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/usePlayer";
 import { loadFeedEntry } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils";
+import { RemoteCommand } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/const";
 
-import { usePlaylistNavigation } from "../usePlaylistNavigation";
+import {
+  getTransportControls,
+  usePlaylistNavigation,
+} from "../usePlaylistNavigation";
 
 jest.mock("@applicaster/zapp-react-native-utils/reactHooks", () => ({
   useNavigation: jest.fn(),
@@ -24,6 +28,13 @@ jest.mock(
   })
 );
 
+jest.mock(
+  "@applicaster/zapp-react-native-utils/appUtils/playerManager/playerNativeCommand",
+  () => ({
+    PlayerNativeCommandTypes: { setPlayerControls: "setPlayerControls" },
+  })
+);
+
 const useNavigationMock = useNavigation as jest.Mock;
 const loadFeedEntryMock = loadFeedEntry as jest.Mock;
 const usePlayerMock = usePlayer as jest.Mock;
@@ -384,4 +395,145 @@ describe("usePlaylistNavigation", () => {
       expect(loadFeedEntryMock).not.toHaveBeenCalled();
     });
   });
+
+  describe("remote commands", () => {
+    let listeners: Record<string, QuickBrickPlayer.SharedPlayerCallBacks>;
+    const command = jest.fn();
+
+    const remote = (id: RemoteCommand) =>
+      act(async () => {
+        Object.values(listeners).forEach((l) => l.onRemoteCommand?.({ id }));
+      });
+
+    beforeEach(() => {
+      listeners = {};
+      command.mockClear();
+
+      usePlayerMock.mockReturnValue({
+        playerId: "player-1",
+        command,
+        seekTo,
+        addListener: ({ id, listener }) => {
+          listeners[id] = listener;
+
+          return () => delete listeners[id];
+        },
+      });
+    });
+
+    it("plays next when the lock screen / CarPlay next button is pressed", async () => {
+      const target = { id: "next" } as ZappEntry;
+      loadFeedEntryMock.mockResolvedValue(target);
+
+      await renderPlaylistNavigation(
+        entryWith({ play_next_feed_url: NEXT_URL }),
+        stateAt(0)
+      );
+
+      await remote(RemoteCommand.NextTrack);
+
+      expect(replaceTop).toHaveBeenCalledWith(target);
+    });
+
+    it("restarts the track on remote previous past the threshold", async () => {
+      await renderPlaylistNavigation(entryWith({}), stateAt(10));
+
+      await remote(RemoteCommand.PreviousTrack);
+
+      expect(seekTo).toHaveBeenCalledWith(0);
+    });
+
+    it("ignores commands native handles itself", async () => {
+      await renderPlaylistNavigation(
+        entryWith({ play_next_feed_url: NEXT_URL }),
+        stateAt(10)
+      );
+
+      await remote(RemoteCommand.Pause);
+
+      expect(replaceTop).not.toHaveBeenCalled();
+      expect(seekTo).not.toHaveBeenCalled();
+    });
+
+    it("sends native the controls snapshot to show", async () => {
+      await renderPlaylistNavigation(
+        entryWith({ play_next_feed_url: NEXT_URL }),
+        stateAt(0, NOT_SEEKABLE)
+      );
+
+      expect(command).toHaveBeenLastCalledWith("setPlayerControls", {
+        transport: [
+          RemoteCommand.Play,
+          RemoteCommand.Pause,
+          RemoteCommand.SkipBackward,
+          RemoteCommand.NextTrack,
+        ],
+      });
+    });
+
+    it("stops listening once unmounted", async () => {
+      const { unmount } = await renderPlaylistNavigation(
+        entryWith({ play_next_feed_url: NEXT_URL }),
+        stateAt(0)
+      );
+
+      unmount();
+
+      expect(listeners).toEqual({});
+    });
+  });
+});
+
+describe("getTransportControls", () => {
+  it("falls back to skip backward and leaves next out when there is no playlist", () => {
+    expect(
+      getTransportControls({
+        hasNext: false,
+        hasPrevious: false,
+        isLive: false,
+      })
+    ).toEqual([
+      RemoteCommand.Play,
+      RemoteCommand.Pause,
+      RemoteCommand.SkipBackward,
+    ]);
+  });
+
+  it("leaves next out without a next item, so it shows disabled", () => {
+    expect(
+      getTransportControls({ hasNext: false, hasPrevious: true, isLive: false })
+    ).toEqual([
+      RemoteCommand.Play,
+      RemoteCommand.Pause,
+      RemoteCommand.PreviousTrack,
+    ]);
+  });
+
+  it("puts track buttons in place of skip ones", () => {
+    expect(
+      getTransportControls({ hasNext: true, hasPrevious: true, isLive: false })
+    ).toEqual([
+      RemoteCommand.Play,
+      RemoteCommand.Pause,
+      RemoteCommand.PreviousTrack,
+      RemoteCommand.NextTrack,
+    ]);
+  });
+
+  it("uses stop and never skips on live", () => {
+    expect(
+      getTransportControls({ hasNext: false, hasPrevious: false, isLive: true })
+    ).toEqual([RemoteCommand.Play, RemoteCommand.Stop]);
+  });
+
+  it("keeps track buttons on live, e.g. a list of radio stations", () => {
+    expect(
+      getTransportControls({ hasNext: true, hasPrevious: true, isLive: true })
+    ).toEqual([
+      RemoteCommand.Play,
+      RemoteCommand.Stop,
+      RemoteCommand.PreviousTrack,
+      RemoteCommand.NextTrack,
+    ]);
+  });
 });

package/src/Player/AudioLayer/usePlaylistNavigation.ts

@@ -2,19 +2,44 @@ import * as React from "react";
 
 import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
 import { usePlayer } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/usePlayer";
-import {
-  loadFeedEntry,
-  retrieveFeedUrl,
-  retrievePlayPreviousFeedUrl,
-} from "@applicaster/zapp-react-native-utils/appUtils/playerManager/OverlayObserver/utils";
-import { createLogger } from "@applicaster/zapp-react-native-utils/logger";
+import { PlayerNativeCommandTypes } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/playerNativeCommand";
+import { RemoteCommand } from "@applicaster/zapp-react-native-utils/appUtils/playerManager/const";
+import { PlaylistNavigationController } from "./PlaylistNavigationController";
 
-const { log_error, log_info } = createLogger({
-  subsystem: "Player",
-  category: "usePlaylistNavigation",
-});
+const REMOTE_COMMANDS_LISTENER_ID = "playlist-navigation-remote-commands";
 
-const RESTART_THRESHOLD_SECONDS = 3;
+/**
+ * Buttons native should expose on the lock screen / Control Center / CarPlay.
+ * Native enables exactly these and disables the rest. A track button takes its
+ * slot over the skip one, since the system shows only one of them per side.
+ * Without a next item next is left out, so the system shows it disabled.
+ */
+export const getTransportControls = ({
+  hasNext,
+  hasPrevious,
+  isLive,
+}: {
+  hasNext: boolean;
+  hasPrevious: boolean;
+  isLive: boolean;
+}): RemoteCommand[] => {
+  const commands = [
+    RemoteCommand.Play,
+    isLive ? RemoteCommand.Stop : RemoteCommand.Pause,
+  ];
+
+  if (hasPrevious) {
+    commands.push(RemoteCommand.PreviousTrack);
+  } else if (!isLive) {
+    commands.push(RemoteCommand.SkipBackward);
+  }
+
+  if (hasNext) {
+    commands.push(RemoteCommand.NextTrack);
+  }
+
+  return commands;
+};
 
 export type PlaylistNavigation = {
   hasNext: boolean;
@@ -24,8 +49,8 @@ export type PlaylistNavigation = {
 };
 
 /**
- * Each entry points at the feed holding its neighbour, so the chain walks
- * itself and needs no client-side queue.
+ * Thin UI binding hook that subscribes to PlaylistNavigationController's
+ * RxJS streams and exposes hasNext, hasPrevious, goNext, and goPrevious.
  */
 export const usePlaylistNavigation = (
   entry: ZappEntry,
@@ -36,98 +61,87 @@ export const usePlaylistNavigation = (
   // seeking would miss the receiver while casting.
   const player = usePlayer();
 
-  const [nextUrl, setNextUrl] = React.useState<string | null>(null);
+  const [controller] = React.useState(
+    () =>
+      new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState,
+      })
+  );
 
-  React.useEffect(() => {
-    let cancelled = false;
+  const [hasNext, setHasNext] = React.useState(() =>
+    controller.hasNext$.getValue()
+  );
 
-    retrieveFeedUrl(entry)
-      .then((url) => {
-        if (!cancelled) {
-          setNextUrl(url ?? null);
-        }
-      })
-      .catch((error) => {
-        log_error(
-          "usePlaylistNavigation: could not resolve the next feed url",
-          { error }
-        );
+  const [hasPrevious, setHasPrevious] = React.useState(() =>
+    controller.hasPrevious$.getValue()
+  );
 
-        if (!cancelled) {
-          setNextUrl(null);
-        }
-      });
+  React.useEffect(() => {
+    controller.updateContext({ player, navigator, entry, playerState });
+  }, [controller, player, navigator, entry, playerState]);
+
+  React.useEffect(() => {
+    const subNext = controller.hasNext$.subscribe(setHasNext);
+    const subPrev = controller.hasPrevious$.subscribe(setHasPrevious);
 
     return () => {
-      cancelled = true;
+      subNext.unsubscribe();
+      subPrev.unsubscribe();
+      controller.destroy();
     };
-  }, [entry]);
-
-  const previousUrl = retrievePlayPreviousFeedUrl(entry);
-  const currentTime = playerState?.currentTime ?? 0;
-
-  const canRestart = (playerState?.seekableDuration ?? 0) > 0;
-
-  const isNavigatingRef = React.useRef(false);
-
-  const navigateTo = React.useCallback(
-    async (feedUrl: string) => {
-      // A second tap mid-flight resolves to the same target, since `entry` has
-      // not been replaced yet.
-      if (isNavigatingRef.current) {
-        return;
-      }
-
-      isNavigatingRef.current = true;
-
-      try {
-        const target = await loadFeedEntry(feedUrl, entry);
-
-        log_info(`navigateTo: playing "${target.title}", id: ${target.id}`, {
-          feedUrl,
-          targetId: target.id,
-        });
-
-        navigator.replaceTop(target);
-      } catch (error) {
-        log_error("navigateTo: could not play the neighbouring entry", {
-          error,
-          feedUrl,
-        });
-      } finally {
-        // Released on failure too, so one bad request cannot latch the control.
-        isNavigatingRef.current = false;
-      }
-    },
-    [entry, navigator]
+  }, [controller]);
+
+  // Lock screen / Control Center / CarPlay next & previous go through the same
+  // controller as the on-screen buttons, so JS stays the single source of truth.
+  React.useEffect(
+    () =>
+      player?.addListener?.({
+        id: REMOTE_COMMANDS_LISTENER_ID,
+        listener: {
+          onRemoteCommand: ({ id }) => {
+            if (id === RemoteCommand.NextTrack) {
+              controller.goNext();
+            } else if (id === RemoteCommand.PreviousTrack) {
+              controller.goPrevious();
+            }
+          },
+        },
+      }),
+    [player, controller]
   );
 
-  const goNext = React.useCallback(async () => {
-    if (!nextUrl) return;
-
-    await navigateTo(nextUrl);
-  }, [nextUrl, navigateTo]);
+  const isLive = Boolean(playerState?.isLive);
 
-  const goPrevious = React.useCallback(async () => {
-    // Restarting belongs to the stream, not the chain — so it stays available
-    // at the head, where there is nothing to step back to.
-    const shouldRestart =
-      canRestart && (currentTime > RESTART_THRESHOLD_SECONDS || !previousUrl);
-
-    if (shouldRestart) {
-      player?.seekTo(0);
+  // Full snapshot: native renders exactly this and drops the rest. Each key is
+  // one kind of buttons, so they stay separate lists rather than one flat list.
+  React.useEffect(() => {
+    const controls = {
+      transport: getTransportControls({ hasNext, hasPrevious, isLive }),
+      // TODO: other button kinds go in as their own keys next to `transport`,
+      // e.g. custom / native-drawn buttons ("play next", CarPlay / Android Auto
+      // row buttons). Add a composer on Player once more than this hook fills it.
+      // actions: [],
+    };
 
-      return;
-    }
+    player?.command?.(PlayerNativeCommandTypes.setPlayerControls, controls);
+  }, [player, hasNext, hasPrevious, isLive]);
 
-    if (!previousUrl) return;
+  const goNext = React.useCallback(
+    async () => controller.goNext(),
+    [controller]
+  );
 
-    await navigateTo(previousUrl);
-  }, [previousUrl, currentTime, canRestart, navigateTo, player]);
+  const goPrevious = React.useCallback(
+    async () => controller.goPrevious(),
+    [controller]
+  );
 
   return {
-    hasNext: Boolean(nextUrl),
-    hasPrevious: Boolean(previousUrl) || canRestart,
+    hasNext,
+    hasPrevious,
     goNext,
     goPrevious,
   };

package/src/Player/index.tsx

@@ -398,6 +398,22 @@ export default class VideoPlayer extends React.Component<
     RNPlayerManager?.[this.playerPluginId]?.stopBackgroundPlayback?.();
   };
 
+  command = (command: string, userInfo?: Record<string, any>) => {
+    if (
+      this.isReactNativeMethodsSupported() &&
+      RNPlayerManager?.[this.playerPluginId]?.command &&
+      this._root
+    ) {
+      const node = findNodeHandle(this._root);
+
+      if (!node) {
+        return;
+      }
+
+      RNPlayerManager?.[this.playerPluginId]?.command(node, command, userInfo);
+    }
+  };
+
   forward = (seekTime = SEEK_TIME) => {
     const currentTime = this.state.currentTime;
 
@@ -535,6 +551,10 @@ export default class VideoPlayer extends React.Component<
     return this.props?.listener?.onError(newError);
   };
 
+  onRemoteCommand = ({ nativeEvent = null }) => {
+    this.props?.listener?.onRemoteCommand?.(nativeEvent);
+  };
+
   onPlayerPause = ({ nativeEvent = null }) => {
     this.setState({ paused: true });
     this.props?.listener?.onPlayerPause(nativeEvent);
@@ -1069,6 +1089,7 @@ export default class VideoPlayer extends React.Component<
       onPlayerResume: this.onPlayerResume,
       onPlayerSeekComplete: this.onPlayerSeekComplete,
       onPlayerSeekStart: this.onPlayerSeekStart,
+      onRemoteCommand: this.onRemoteCommand,
     };
 
     const lifecycleEvents = {