@applicaster/quick-brick-player 16.0.0-rc.88 → 16.0.0-rc.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/quick-brick-player",
-  "version": "16.0.0-rc.88",
+  "version": "16.0.0-rc.89",
   "description": "Quick Brick Player",
   "main": "./src/index.ts",
   "types": "index.d.ts",
@@ -37,9 +37,9 @@
   "dependencies": {
     "@applicaster/quick-brick-mobile-transport-controls": "16.0.0-rc.73",
     "@applicaster/quick-brick-tv-transport-controls": "16.0.0-rc.69",
-    "@applicaster/zapp-react-native-tvos-app": "16.0.0-rc.88",
-    "@applicaster/zapp-react-native-ui-components": "16.0.0-rc.88",
-    "@applicaster/zapp-react-native-utils": "16.0.0-rc.88",
+    "@applicaster/zapp-react-native-tvos-app": "16.0.0-rc.89",
+    "@applicaster/zapp-react-native-ui-components": "16.0.0-rc.89",
+    "@applicaster/zapp-react-native-utils": "16.0.0-rc.89",
     "query-string": "7.1.3",
     "shaka-player": "4.3.5",
     "typeface-montserrat": "^0.0.54",

package/src/Player/AudioLayer/PlaylistNavigationController.ts

@@ -0,0 +1,381 @@
+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 QueueManager = (queuePlugin as any)?.module?.QueueManager;
+
+      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 isPlayingFromQueue = Boolean(this.entry?.extensions?.queueItemId);
+    const staticNextUrl = this.entry?.extensions?.play_next_feed_url;
+    const staticPrevUrl = this.entry?.extensions?.play_previous_feed_url;
+
+    const hasNext = isPlayingFromQueue
+      ? upcoming.length > 0 || Boolean(staticNextUrl)
+      : Boolean(staticNextUrl) || upcoming.length > 0;
+
+    const canRestart = (this.playerState?.seekableDuration ?? 0) > 0;
+
+    const hasPrevious = isPlayingFromQueue
+      ? history.length > 0 || Boolean(staticPrevUrl) || canRestart
+      : Boolean(staticPrevUrl) || history.length > 0 || 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;
+
+      const isPlayingFromQueue = Boolean(this.entry?.extensions?.queueItemId);
+
+      if (isPlayingFromQueue && 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);
+
+        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);
+      }
+    } 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 isPlayingFromQueue = Boolean(this.entry?.extensions?.queueItemId);
+      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 = isPlayingFromQueue
+        ? hasQueueHistory || hasStaticPrev
+        : hasStaticPrev || hasQueueHistory;
+
+      const shouldRestart =
+        canRestart && (currentTime > RESTART_THRESHOLD_SECONDS || !hasTarget);
+
+      if (shouldRestart) {
+        if (this.isDestroyed) return;
+        this.player?.seekTo?.(0);
+
+        return;
+      }
+
+      if (isPlayingFromQueue && 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);
+
+        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);
+      }
+    } 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,529 @@
+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 static feed URLs 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).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("prioritizes queue navigation when entry is from queue (has queueItemId)", async () => {
+      const queueNextItem = { id: "queue_next" } as ZappEntry;
+      const queuePrevItem = { id: "queue_prev" } as ZappEntry;
+
+      mockQueueManager.instance.getUpcomingQueue.mockResolvedValue([
+        queueNextItem,
+      ]);
+
+      mockQueueManager.instance.getHistoryQueue.mockResolvedValue([
+        queuePrevItem,
+      ]);
+
+      const entry = entryWith({
+        queueItemId: "current_queue_slot",
+        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(navigator.replaceTop).toHaveBeenCalledWith(queuePrevItem);
+
+      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/usePlaylistNavigation.ts

@@ -2,19 +2,7 @@ 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";
-
-const { log_error, log_info } = createLogger({
-  subsystem: "Player",
-  category: "usePlaylistNavigation",
-});
-
-const RESTART_THRESHOLD_SECONDS = 3;
+import { PlaylistNavigationController } from "./PlaylistNavigationController";
 
 export type PlaylistNavigation = {
   hasNext: boolean;
@@ -24,8 +12,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 +24,52 @@ export const usePlaylistNavigation = (
   // seeking would miss the receiver while casting.
   const player = usePlayer();
 
-  const [nextUrl, setNextUrl] = React.useState<string | null>(null);
-
-  React.useEffect(() => {
-    let cancelled = false;
-
-    retrieveFeedUrl(entry)
-      .then((url) => {
-        if (!cancelled) {
-          setNextUrl(url ?? null);
-        }
+  const [controller] = React.useState(
+    () =>
+      new PlaylistNavigationController({
+        entry,
+        player,
+        navigator,
+        playerState,
       })
-      .catch((error) => {
-        log_error(
-          "usePlaylistNavigation: could not resolve the next feed url",
-          { error }
-        );
-
-        if (!cancelled) {
-          setNextUrl(null);
-        }
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [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]
   );
 
-  const goNext = React.useCallback(async () => {
-    if (!nextUrl) return;
+  const [hasNext, setHasNext] = React.useState(() =>
+    controller.hasNext$.getValue()
+  );
 
-    await navigateTo(nextUrl);
-  }, [nextUrl, navigateTo]);
+  const [hasPrevious, setHasPrevious] = React.useState(() =>
+    controller.hasPrevious$.getValue()
+  );
 
-  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);
+  React.useEffect(() => {
+    controller.updateContext({ player, navigator, entry, playerState });
+  }, [controller, player, navigator, entry, playerState]);
 
-    if (shouldRestart) {
-      player?.seekTo(0);
+  React.useEffect(() => {
+    const subNext = controller.hasNext$.subscribe(setHasNext);
+    const subPrev = controller.hasPrevious$.subscribe(setHasPrevious);
 
-      return;
-    }
+    return () => {
+      subNext.unsubscribe();
+      subPrev.unsubscribe();
+      controller.destroy();
+    };
+  }, [controller]);
 
-    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,
   };