feat(queue): play queue sync — manual pull, idle auto-sync, multi-server push (#1131)

src/hooks/useIdlePlayQueuePull.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef } from 'react';
+import { applyServerPlayQueue } from '../store/applyServerPlayQueue';
+import { useAuthStore } from '../store/authStore';
+import { useOrbitStore } from '../store/orbitStore';
+import { usePlayerStore } from '../store/playerStore';
+import {
+  getPlaybackIdleSinceMs,
+  hasRecentQueueMutation,
+  isPlaybackIdleLongEnough,
+  markPlaybackIdle,
+} from '../store/queuePlaybackIdle';
+import type { ConnectionStatus } from './useConnectionStatus';
+import { canAutoIdlePlayQueuePull } from './usePlayQueueSyncLedState';
+
+const IDLE_THRESHOLD_MS = 30_000;
+const MUTATION_QUIET_MS = 15_000;
+const POLL_INTERVAL_MS = 10_000;
+
+/** Background pull when paused/stopped long enough on a single-server, in-sync browse context. */
+export function useIdlePlayQueuePull(status: ConnectionStatus) {
+  const activeServerId = useAuthStore(s => s.activeServerId);
+  const orbitRole = useOrbitStore(s => s.role);
+  const isPlaying = usePlayerStore(s => s.isPlaying);
+  const inFlightRef = useRef(false);
+
+  useEffect(() => {
+    if (!isPlaying && getPlaybackIdleSinceMs() === 0) {
+      markPlaybackIdle();
+    }
+  }, [isPlaying]);
+
+  useEffect(() => {
+    if (!canAutoIdlePlayQueuePull(status, orbitRole)) return;
+
+    const tick = () => {
+      if (inFlightRef.current) return;
+      if (!canAutoIdlePlayQueuePull(status, orbitRole)) return;
+      if (isPlaying) return;
+      if (!isPlaybackIdleLongEnough(IDLE_THRESHOLD_MS)) return;
+      if (hasRecentQueueMutation(MUTATION_QUIET_MS)) return;
+      if (!activeServerId) return;
+
+      inFlightRef.current = true;
+      void applyServerPlayQueue(activeServerId, { mode: 'idle', preferServerPosition: true })
+        .finally(() => {
+          inFlightRef.current = false;
+        });
+    };
+
+    const id = window.setInterval(tick, POLL_INTERVAL_MS);
+    return () => window.clearInterval(id);
+  }, [activeServerId, isPlaying, orbitRole, status]);
+}

src/hooks/usePlayQueueSyncLedState.ts

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import type { ConnectionStatus } from '../hooks/useConnectionStatus';
+import { pullPlayQueueFromActiveServer } from '../store/applyServerPlayQueue';
+import { useAuthStore } from '../store/authStore';
+import { useOrbitStore } from '../store/orbitStore';
+import { usePlayerStore } from '../store/playerStore';
+import { getPlaybackServerId, queueIsMultiServer } from '../utils/playback/playbackServer';
+import { clearQueueHandoffPending, isQueueHandoffPending } from '../store/queueSyncUiState';
+import { showToast } from '../utils/ui/toast';
+
+export function usePlayQueueSyncLedState(status: ConnectionStatus) {
+  const { t } = useTranslation();
+  const activeServerId = useAuthStore(s => s.activeServerId);
+  const orbitRole = useOrbitStore(s => s.role);
+  const isPlaying = usePlayerStore(s => s.isPlaying);
+  const currentRadio = usePlayerStore(s => s.currentRadio);
+  const [pullInFlight, setPullInFlight] = useState(false);
+
+  const queueItems = usePlayerStore(s => s.queueItems);
+  const queueIndex = usePlayerStore(s => s.queueIndex);
+  const currentTrackId = usePlayerStore(s => s.currentTrack?.id);
+
+  const playbackServerId = useMemo(
+    () => getPlaybackServerId(),
+    [activeServerId, queueItems, queueIndex, currentTrackId],
+  );
+
+  useEffect(() => {
+    if (activeServerId && playbackServerId && activeServerId === playbackServerId) {
+      clearQueueHandoffPending();
+    }
+  }, [activeServerId, playbackServerId]);
+
+  const needsQueuePull = status === 'connected'
+    && Boolean(activeServerId)
+    && (
+      (Boolean(playbackServerId) && activeServerId !== playbackServerId)
+      || isQueueHandoffPending()
+    );
+
+  const ledVariant = status === 'checking'
+    ? 'checking'
+    : status === 'disconnected'
+      ? 'disconnected'
+      : needsQueuePull
+        ? 'queue-handoff'
+        : 'connected';
+
+  const pullFromActiveServer = useCallback(async () => {
+    if (status !== 'connected' || pullInFlight) return;
+    if (orbitRole === 'host' || orbitRole === 'guest') return;
+    if (currentRadio) return;
+
+    setPullInFlight(true);
+    try {
+      const result = await pullPlayQueueFromActiveServer();
+      switch (result) {
+        case 'noop':
+          showToast(t('connection.queueSynced'), 2500, 'info');
+          break;
+        case 'empty':
+          showToast(t('connection.queuePullEmpty'), 4000, 'info');
+          break;
+        case 'applied':
+          showToast(t('connection.queuePullSuccess'), 3000, 'info');
+          break;
+        case 'error':
+          showToast(t('connection.queuePullFailed'), 5000, 'error');
+          break;
+        default:
+          break;
+      }
+    } finally {
+      setPullInFlight(false);
+    }
+  }, [currentRadio, orbitRole, pullInFlight, status, t]);
+
+  const syncRingVisible = status === 'connected' && (needsQueuePull || pullInFlight);
+
+  return {
+    ledVariant,
+    needsQueuePull,
+    pullInFlight,
+    syncRingVisible,
+    pullFromActiveServer,
+  };
+}
+
+export function canAutoIdlePlayQueuePull(
+  status: ConnectionStatus,
+  orbitRole: string | null,
+): boolean {
+  if (status !== 'connected') return false;
+  if (orbitRole === 'host' || orbitRole === 'guest') return false;
+  if (usePlayerStore.getState().currentRadio) return false;
+  if (queueIsMultiServer()) return false;
+  const activeId = useAuthStore.getState().activeServerId;
+  const playbackId = getPlaybackServerId();
+  if (!activeId || !playbackId || activeId !== playbackId) return false;
+  return true;
+}