fix(qconnect): render connect queue in remote shuffle order

cx

src/lib/services/qconnectRemoteQueue.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import {
+  resolveQconnectQueueDisplayItems,
   resolveQconnectPlayNextInsertAfter,
   type QconnectQueueSnapshot,
   type QconnectRendererSnapshot
@@ -15,11 +16,38 @@ function buildQueueSnapshot(trackIds: number[], queueItemIds: number[]): Qconnec
       track_context_uuid: `ctx-${index + 1}`
     })),
     shuffle_mode: false,
+    shuffle_order: null,
     autoplay_mode: false,
     autoplay_items: []
   };
 }
 
+describe('resolveQconnectQueueDisplayItems', () => {
+  it('returns queue items in shuffle order when the snapshot provides one', () => {
+    const queueSnapshot: QconnectQueueSnapshot = {
+      ...buildQueueSnapshot([101, 102, 103, 104], [1, 2, 3, 4]),
+      shuffle_mode: true,
+      shuffle_order: [0, 2, 3, 1]
+    };
+
+    expect(resolveQconnectQueueDisplayItems(queueSnapshot).map((item) => item.track_id)).toEqual([
+      101, 103, 104, 102
+    ]);
+  });
+
+  it('falls back to raw queue items when shuffle order is invalid', () => {
+    const queueSnapshot: QconnectQueueSnapshot = {
+      ...buildQueueSnapshot([201, 202, 203], [11, 12, 13]),
+      shuffle_mode: true,
+      shuffle_order: [0, 99, 1]
+    };
+
+    expect(resolveQconnectQueueDisplayItems(queueSnapshot).map((item) => item.track_id)).toEqual([
+      201, 202, 203
+    ]);
+  });
+});
+
 describe('resolveQconnectPlayNextInsertAfter', () => {
   it('prefers a renderer queue_item_id that exists in the queue snapshot', () => {
     const queueSnapshot = buildQueueSnapshot([101, 102, 103], [9001, 9002, 9003]);

src/lib/services/qconnectRemoteQueue.ts

@@ -8,6 +8,7 @@ export type QconnectQueueSnapshot = {
   version?: { major: number; minor: number };
   queue_items: QconnectQueueItemSnapshot[];
   shuffle_mode: boolean;
+  shuffle_order?: number[] | null;
   autoplay_mode: boolean;
   autoplay_items: QconnectQueueItemSnapshot[];
 };
@@ -130,6 +131,25 @@ function resolvedQueueItemId(
     : queueItems[queueIndex].queue_item_id;
 }
 
+export function resolveQconnectQueueDisplayItems(
+  queueSnapshot: QconnectQueueSnapshot | null | undefined
+): QconnectQueueItemSnapshot[] {
+  const queueItems = queueSnapshot?.queue_items ?? [];
+  const shuffleOrder = queueSnapshot?.shuffle_order ?? null;
+
+  if (!queueSnapshot?.shuffle_mode || !Array.isArray(shuffleOrder) || shuffleOrder.length === 0) {
+    return queueItems;
+  }
+
+  const ordered = shuffleOrder
+    .map((queueIndex) => (
+      Number.isInteger(queueIndex) && queueIndex >= 0 ? queueItems[queueIndex] ?? null : null
+    ))
+    .filter((queueItem): queueItem is QconnectQueueItemSnapshot => queueItem !== null);
+
+  return ordered.length === queueItems.length ? ordered : queueItems;
+}
+
 export function resolveQconnectPlayNextInsertAfter(
   queueSnapshot: QconnectQueueSnapshot | null | undefined,
   rendererSnapshot: QconnectRendererSnapshot | null | undefined,