@scarlett-player/playlist 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hackney Enterprises Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,395 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createPlaylistPlugin: () => createPlaylistPlugin,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_CONFIG = {
+  autoAdvance: true,
+  preloadNext: true,
+  persist: false,
+  persistKey: "scarlett-playlist",
+  shuffle: false,
+  repeat: "none"
+};
+function generateId() {
+  return `track-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function shuffleArray(array) {
+  const result = [...array];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+function createPlaylistPlugin(config) {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  let api = null;
+  let tracks = mergedConfig.tracks || [];
+  let currentIndex = -1;
+  let shuffle = mergedConfig.shuffle || false;
+  let repeat = mergedConfig.repeat || "none";
+  let shuffleOrder = [];
+  tracks = tracks.map((t) => ({ ...t, id: t.id || generateId() }));
+  const generateShuffleOrder = () => {
+    const indices = tracks.map((_, i) => i);
+    shuffleOrder = shuffleArray(indices);
+    if (currentIndex >= 0) {
+      const currentPos = shuffleOrder.indexOf(currentIndex);
+      if (currentPos > 0) {
+        shuffleOrder.splice(currentPos, 1);
+        shuffleOrder.unshift(currentIndex);
+      }
+    }
+  };
+  const getActualIndex = (logicalIndex) => {
+    if (!shuffle || shuffleOrder.length === 0) {
+      return logicalIndex;
+    }
+    return shuffleOrder[logicalIndex] ?? logicalIndex;
+  };
+  const getLogicalIndex = (actualIndex) => {
+    if (!shuffle || shuffleOrder.length === 0) {
+      return actualIndex;
+    }
+    return shuffleOrder.indexOf(actualIndex);
+  };
+  const hasNextTrack = () => {
+    if (tracks.length === 0) return false;
+    if (repeat === "one" || repeat === "all") return true;
+    const logicalIndex = getLogicalIndex(currentIndex);
+    return logicalIndex < tracks.length - 1;
+  };
+  const hasPreviousTrack = () => {
+    if (tracks.length === 0) return false;
+    if (repeat === "one" || repeat === "all") return true;
+    const logicalIndex = getLogicalIndex(currentIndex);
+    return logicalIndex > 0;
+  };
+  const getNextIndex = () => {
+    if (tracks.length === 0) return -1;
+    if (repeat === "one") {
+      return currentIndex;
+    }
+    const logicalIndex = getLogicalIndex(currentIndex);
+    let nextLogical = logicalIndex + 1;
+    if (nextLogical >= tracks.length) {
+      if (repeat === "all") {
+        if (shuffle) {
+          generateShuffleOrder();
+        }
+        nextLogical = 0;
+      } else {
+        return -1;
+      }
+    }
+    return getActualIndex(nextLogical);
+  };
+  const getPreviousIndex = () => {
+    if (tracks.length === 0) return -1;
+    if (repeat === "one") {
+      return currentIndex;
+    }
+    const logicalIndex = getLogicalIndex(currentIndex);
+    let prevLogical = logicalIndex - 1;
+    if (prevLogical < 0) {
+      if (repeat === "all") {
+        prevLogical = tracks.length - 1;
+      } else {
+        return -1;
+      }
+    }
+    return getActualIndex(prevLogical);
+  };
+  const persistPlaylist = () => {
+    if (!mergedConfig.persist) return;
+    try {
+      const data = {
+        tracks,
+        currentIndex,
+        shuffle,
+        repeat,
+        shuffleOrder
+      };
+      localStorage.setItem(mergedConfig.persistKey, JSON.stringify(data));
+    } catch (e) {
+      api?.logger.warn("Failed to persist playlist", e);
+    }
+  };
+  const loadPersistedPlaylist = () => {
+    if (!mergedConfig.persist) return;
+    try {
+      const data = localStorage.getItem(mergedConfig.persistKey);
+      if (data) {
+        const parsed = JSON.parse(data);
+        tracks = parsed.tracks || [];
+        currentIndex = parsed.currentIndex ?? -1;
+        shuffle = parsed.shuffle ?? false;
+        repeat = parsed.repeat ?? "none";
+        shuffleOrder = parsed.shuffleOrder || [];
+      }
+    } catch (e) {
+      api?.logger.warn("Failed to load persisted playlist", e);
+    }
+  };
+  const emitChange = () => {
+    const track = currentIndex >= 0 ? tracks[currentIndex] : null;
+    api?.emit("playlist:change", { track, index: currentIndex });
+    persistPlaylist();
+  };
+  const setCurrentTrack = (index) => {
+    if (index < 0 || index >= tracks.length) {
+      api?.logger.warn("Invalid track index", { index });
+      return;
+    }
+    const track = tracks[index];
+    currentIndex = index;
+    api?.logger.info("Track changed", { index, title: track.title, src: track.src });
+    if (track.title) {
+      api?.setState("title", track.title);
+    }
+    if (track.artwork) {
+      api?.setState("poster", track.artwork);
+    }
+    api?.setState("mediaType", track.type || "audio");
+    emitChange();
+  };
+  const plugin = {
+    id: "playlist",
+    name: "Playlist",
+    version: "1.0.0",
+    type: "feature",
+    description: "Playlist management with shuffle, repeat, and gapless playback",
+    async init(pluginApi) {
+      api = pluginApi;
+      api.logger.info("Playlist plugin initialized");
+      loadPersistedPlaylist();
+      if (shuffle && tracks.length > 0) {
+        generateShuffleOrder();
+      }
+      const unsubEnded = api.on("playback:ended", () => {
+        if (!mergedConfig.autoAdvance) return;
+        const nextIdx = getNextIndex();
+        if (nextIdx >= 0) {
+          api?.logger.debug("Auto-advancing to next track", { nextIdx });
+          setCurrentTrack(nextIdx);
+        } else {
+          api?.logger.info("Playlist ended");
+          api?.emit("playlist:ended", void 0);
+        }
+      });
+      api.onDestroy(() => {
+        unsubEnded();
+        persistPlaylist();
+      });
+    },
+    async destroy() {
+      api?.logger.info("Playlist plugin destroying");
+      persistPlaylist();
+      api = null;
+    },
+    add(trackOrTracks) {
+      const newTracks = Array.isArray(trackOrTracks) ? trackOrTracks : [trackOrTracks];
+      newTracks.forEach((track) => {
+        const normalizedTrack = { ...track, id: track.id || generateId() };
+        const index = tracks.length;
+        tracks.push(normalizedTrack);
+        api?.emit("playlist:add", { track: normalizedTrack, index });
+        api?.logger.debug("Track added", { title: normalizedTrack.title, index });
+      });
+      if (shuffle) {
+        const startIndex = tracks.length - newTracks.length;
+        for (let i = startIndex; i < tracks.length; i++) {
+          const insertPos = Math.floor(Math.random() * (shuffleOrder.length - getLogicalIndex(currentIndex))) + getLogicalIndex(currentIndex) + 1;
+          shuffleOrder.splice(Math.min(insertPos, shuffleOrder.length), 0, i);
+        }
+      }
+      persistPlaylist();
+    },
+    insert(index, track) {
+      const normalizedTrack = { ...track, id: track.id || generateId() };
+      const clampedIndex = Math.max(0, Math.min(index, tracks.length));
+      tracks.splice(clampedIndex, 0, normalizedTrack);
+      if (currentIndex >= clampedIndex) {
+        currentIndex++;
+      }
+      if (shuffle) {
+        shuffleOrder = shuffleOrder.map((i) => i >= clampedIndex ? i + 1 : i);
+        const insertPos = Math.floor(Math.random() * shuffleOrder.length);
+        shuffleOrder.splice(insertPos, 0, clampedIndex);
+      }
+      api?.emit("playlist:add", { track: normalizedTrack, index: clampedIndex });
+      persistPlaylist();
+    },
+    remove(idOrIndex) {
+      let index;
+      if (typeof idOrIndex === "string") {
+        index = tracks.findIndex((t) => t.id === idOrIndex);
+        if (index === -1) {
+          api?.logger.warn("Track not found", { id: idOrIndex });
+          return;
+        }
+      } else {
+        index = idOrIndex;
+      }
+      if (index < 0 || index >= tracks.length) {
+        api?.logger.warn("Invalid track index", { index });
+        return;
+      }
+      const [removedTrack] = tracks.splice(index, 1);
+      if (index < currentIndex) {
+        currentIndex--;
+      } else if (index === currentIndex) {
+        if (currentIndex >= tracks.length) {
+          currentIndex = tracks.length - 1;
+        }
+        emitChange();
+      }
+      if (shuffle) {
+        shuffleOrder = shuffleOrder.filter((i) => i !== index).map((i) => i > index ? i - 1 : i);
+      }
+      api?.emit("playlist:remove", { track: removedTrack, index });
+      persistPlaylist();
+    },
+    clear() {
+      tracks = [];
+      currentIndex = -1;
+      shuffleOrder = [];
+      api?.emit("playlist:clear", void 0);
+      emitChange();
+    },
+    play(idOrIndex) {
+      let index;
+      if (idOrIndex === void 0) {
+        index = currentIndex >= 0 ? currentIndex : shuffle ? getActualIndex(0) : 0;
+      } else if (typeof idOrIndex === "string") {
+        index = tracks.findIndex((t) => t.id === idOrIndex);
+        if (index === -1) {
+          api?.logger.warn("Track not found", { id: idOrIndex });
+          return;
+        }
+      } else {
+        index = idOrIndex;
+      }
+      if (tracks.length === 0) {
+        api?.logger.warn("Playlist is empty");
+        return;
+      }
+      setCurrentTrack(index);
+    },
+    next() {
+      const nextIdx = getNextIndex();
+      if (nextIdx >= 0) {
+        setCurrentTrack(nextIdx);
+      } else {
+        api?.logger.info("No next track");
+      }
+    },
+    previous() {
+      const currentTime = api?.getState("currentTime") || 0;
+      if (currentTime > 3) {
+        api?.emit("playback:seeking", { time: 0 });
+        return;
+      }
+      const prevIdx = getPreviousIndex();
+      if (prevIdx >= 0) {
+        setCurrentTrack(prevIdx);
+      } else {
+        api?.logger.info("No previous track");
+      }
+    },
+    toggleShuffle() {
+      this.setShuffle(!shuffle);
+    },
+    setShuffle(enabled) {
+      shuffle = enabled;
+      if (enabled) {
+        generateShuffleOrder();
+      } else {
+        shuffleOrder = [];
+      }
+      api?.emit("playlist:shuffle", { enabled });
+      api?.logger.info("Shuffle mode", { enabled });
+      persistPlaylist();
+    },
+    cycleRepeat() {
+      const modes = ["none", "all", "one"];
+      const currentIdx = modes.indexOf(repeat);
+      const nextIdx = (currentIdx + 1) % modes.length;
+      this.setRepeat(modes[nextIdx]);
+    },
+    setRepeat(mode) {
+      repeat = mode;
+      api?.emit("playlist:repeat", { mode });
+      api?.logger.info("Repeat mode", { mode });
+      persistPlaylist();
+    },
+    move(fromIndex, toIndex) {
+      if (fromIndex < 0 || fromIndex >= tracks.length) return;
+      if (toIndex < 0 || toIndex >= tracks.length) return;
+      if (fromIndex === toIndex) return;
+      const [track] = tracks.splice(fromIndex, 1);
+      tracks.splice(toIndex, 0, track);
+      if (currentIndex === fromIndex) {
+        currentIndex = toIndex;
+      } else if (fromIndex < currentIndex && toIndex >= currentIndex) {
+        currentIndex--;
+      } else if (fromIndex > currentIndex && toIndex <= currentIndex) {
+        currentIndex++;
+      }
+      if (shuffle) {
+        generateShuffleOrder();
+      }
+      api?.emit("playlist:reorder", { tracks: [...tracks] });
+      persistPlaylist();
+    },
+    getState() {
+      return {
+        tracks: [...tracks],
+        currentIndex,
+        currentTrack: currentIndex >= 0 ? tracks[currentIndex] : null,
+        shuffle,
+        repeat,
+        shuffleOrder: [...shuffleOrder],
+        hasNext: hasNextTrack(),
+        hasPrevious: hasPreviousTrack()
+      };
+    },
+    getTracks() {
+      return [...tracks];
+    },
+    getCurrentTrack() {
+      return currentIndex >= 0 ? tracks[currentIndex] : null;
+    },
+    getTrack(id) {
+      return tracks.find((t) => t.id === id) || null;
+    }
+  };
+  return plugin;
+}
+var index_default = createPlaylistPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPlaylistPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,197 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Playlist Plugin Types
+ */
+
+/**
+ * A track in the playlist
+ */
+interface PlaylistTrack {
+    /** Unique track ID */
+    id: string;
+    /** Media source URL */
+    src: string;
+    /** Track title */
+    title?: string;
+    /** Artist/creator name */
+    artist?: string;
+    /** Album name */
+    album?: string;
+    /** Album art / thumbnail URL */
+    artwork?: string;
+    /** Duration in seconds (if known) */
+    duration?: number;
+    /** Media type */
+    type?: 'audio' | 'video';
+    /** MIME type hint */
+    mimeType?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Repeat mode
+ */
+type RepeatMode = 'none' | 'one' | 'all';
+/**
+ * Playlist state
+ */
+interface PlaylistState {
+    /** All tracks in the playlist */
+    tracks: PlaylistTrack[];
+    /** Current track index (-1 if no track) */
+    currentIndex: number;
+    /** Currently playing track */
+    currentTrack: PlaylistTrack | null;
+    /** Shuffle mode enabled */
+    shuffle: boolean;
+    /** Repeat mode */
+    repeat: RepeatMode;
+    /** Shuffled order (indices into tracks array) */
+    shuffleOrder: number[];
+    /** Whether there's a next track available */
+    hasNext: boolean;
+    /** Whether there's a previous track available */
+    hasPrevious: boolean;
+}
+/**
+ * Playlist plugin configuration
+ */
+interface PlaylistPluginConfig {
+    /** Auto-advance to next track when current ends (default: true) */
+    autoAdvance?: boolean;
+    /** Preload next track for gapless playback (default: true) */
+    preloadNext?: boolean;
+    /** Persist playlist to localStorage (default: false) */
+    persist?: boolean;
+    /** localStorage key for persistence (default: 'scarlett-playlist') */
+    persistKey?: string;
+    /** Initial tracks */
+    tracks?: PlaylistTrack[];
+    /** Initial shuffle state */
+    shuffle?: boolean;
+    /** Initial repeat mode */
+    repeat?: RepeatMode;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Playlist plugin interface
+ */
+interface IPlaylistPlugin extends Plugin<PlaylistPluginConfig> {
+    /**
+     * Add a track to the end of the playlist
+     */
+    add(track: PlaylistTrack | PlaylistTrack[]): void;
+    /**
+     * Insert a track at a specific position
+     */
+    insert(index: number, track: PlaylistTrack): void;
+    /**
+     * Remove a track by ID or index
+     */
+    remove(idOrIndex: string | number): void;
+    /**
+     * Clear all tracks
+     */
+    clear(): void;
+    /**
+     * Select a specific track by ID or index.
+     * Emits playlist:change event - consumer should load and play from that event.
+     */
+    play(idOrIndex?: string | number): void;
+    /**
+     * Select the next track.
+     * Emits playlist:change event - consumer should load and play from that event.
+     */
+    next(): void;
+    /**
+     * Select the previous track.
+     * Emits playlist:change event - consumer should load and play from that event.
+     */
+    previous(): void;
+    /**
+     * Toggle shuffle mode
+     */
+    toggleShuffle(): void;
+    /**
+     * Set shuffle mode
+     */
+    setShuffle(enabled: boolean): void;
+    /**
+     * Cycle through repeat modes (none -> all -> one -> none)
+     */
+    cycleRepeat(): void;
+    /**
+     * Set repeat mode
+     */
+    setRepeat(mode: RepeatMode): void;
+    /**
+     * Move a track to a new position
+     */
+    move(fromIndex: number, toIndex: number): void;
+    /**
+     * Get current playlist state
+     */
+    getState(): PlaylistState;
+    /**
+     * Get all tracks
+     */
+    getTracks(): PlaylistTrack[];
+    /**
+     * Get current track
+     */
+    getCurrentTrack(): PlaylistTrack | null;
+    /**
+     * Get track by ID
+     */
+    getTrack(id: string): PlaylistTrack | null;
+}
+
+/**
+ * Playlist Plugin for Scarlett Player
+ *
+ * Provides playlist management with:
+ * - Queue management (add, remove, reorder)
+ * - Shuffle mode with Fisher-Yates algorithm
+ * - Repeat modes (none, one, all)
+ * - Auto-advance to next track
+ * - Gapless playback preparation
+ * - LocalStorage persistence
+ */
+
+/**
+ * Create a Playlist Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Playlist Plugin instance
+ *
+ * @example
+ * ```ts
+ * import { createPlaylistPlugin } from '@scarlett-player/playlist';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: document.getElementById('player'),
+ *   plugins: [
+ *     createPlaylistPlugin({
+ *       autoAdvance: true,
+ *       shuffle: false,
+ *       repeat: 'none',
+ *     }),
+ *   ],
+ * });
+ *
+ * // Add tracks
+ * const playlist = player.getPlugin('playlist');
+ * playlist.add([
+ *   { id: '1', src: 'track1.mp3', title: 'Track 1', artist: 'Artist' },
+ *   { id: '2', src: 'track2.mp3', title: 'Track 2', artist: 'Artist' },
+ * ]);
+ *
+ * // Start playback
+ * playlist.play();
+ * ```
+ */
+declare function createPlaylistPlugin(config?: Partial<PlaylistPluginConfig>): IPlaylistPlugin;
+
+export { type IPlaylistPlugin, type PlaylistPluginConfig, type PlaylistState, type PlaylistTrack, type RepeatMode, createPlaylistPlugin, createPlaylistPlugin as default };

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Playlist Plugin Types
+ */
+
+/**
+ * A track in the playlist
+ */
+interface PlaylistTrack {
+    /** Unique track ID */
+    id: string;
+    /** Media source URL */
+    src: string;
+    /** Track title */
+    title?: string;
+    /** Artist/creator name */
+    artist?: string;
+    /** Album name */
+    album?: string;
+    /** Album art / thumbnail URL */
+    artwork?: string;
+    /** Duration in seconds (if known) */
+    duration?: number;
+    /** Media type */
+    type?: 'audio' | 'video';
+    /** MIME type hint */
+    mimeType?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Repeat mode
+ */
+type RepeatMode = 'none' | 'one' | 'all';
+/**
+ * Playlist state
+ */
+interface PlaylistState {
+    /** All tracks in the playlist */
+    tracks: PlaylistTrack[];
+    /** Current track index (-1 if no track) */
+    currentIndex: number;
+    /** Currently playing track */
+    currentTrack: PlaylistTrack | null;
+    /** Shuffle mode enabled */
+    shuffle: boolean;
+    /** Repeat mode */
+    repeat: RepeatMode;
+    /** Shuffled order (indices into tracks array) */
+    shuffleOrder: number[];
+    /** Whether there's a next track available */
+    hasNext: boolean;
+    /** Whether there's a previous track available */
+    hasPrevious: boolean;
+}
+/**
+ * Playlist plugin configuration
+ */
+interface PlaylistPluginConfig {
+    /** Auto-advance to next track when current ends (default: true) */
+    autoAdvance?: boolean;
+    /** Preload next track for gapless playback (default: true) */
+    preloadNext?: boolean;
+    /** Persist playlist to localStorage (default: false) */
+    persist?: boolean;
+    /** localStorage key for persistence (default: 'scarlett-playlist') */
+    persistKey?: string;
+    /** Initial tracks */
+    tracks?: PlaylistTrack[];
+    /** Initial shuffle state */
+    shuffle?: boolean;
+    /** Initial repeat mode */
+    repeat?: RepeatMode;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Playlist plugin interface
+ */
+interface IPlaylistPlugin extends Plugin<PlaylistPluginConfig> {
+    /**
+     * Add a track to the end of the playlist
+     */
+    add(track: PlaylistTrack | PlaylistTrack[]): void;
+    /**
+     * Insert a track at a specific position
+     */
+    insert(index: number, track: PlaylistTrack): void;
+    /**
+     * Remove a track by ID or index
+     */
+    remove(idOrIndex: string | number): void;
+    /**
+     * Clear all tracks
+     */
+    clear(): void;
+    /**
+     * Select a specific track by ID or index.
+     * Emits playlist:change event - consumer should load and play from that event.
+     */
+    play(idOrIndex?: string | number): void;
+    /**
+     * Select the next track.
+     * Emits playlist:change event - consumer should load and play from that event.
+     */
+    next(): void;
+    /**
+     * Select the previous track.
+     * Emits playlist:change event - consumer should load and play from that event.
+     */
+    previous(): void;
+    /**
+     * Toggle shuffle mode
+     */
+    toggleShuffle(): void;
+    /**
+     * Set shuffle mode
+     */
+    setShuffle(enabled: boolean): void;
+    /**
+     * Cycle through repeat modes (none -> all -> one -> none)
+     */
+    cycleRepeat(): void;
+    /**
+     * Set repeat mode
+     */
+    setRepeat(mode: RepeatMode): void;
+    /**
+     * Move a track to a new position
+     */
+    move(fromIndex: number, toIndex: number): void;
+    /**
+     * Get current playlist state
+     */
+    getState(): PlaylistState;
+    /**
+     * Get all tracks
+     */
+    getTracks(): PlaylistTrack[];
+    /**
+     * Get current track
+     */
+    getCurrentTrack(): PlaylistTrack | null;
+    /**
+     * Get track by ID
+     */
+    getTrack(id: string): PlaylistTrack | null;
+}
+
+/**
+ * Playlist Plugin for Scarlett Player
+ *
+ * Provides playlist management with:
+ * - Queue management (add, remove, reorder)
+ * - Shuffle mode with Fisher-Yates algorithm
+ * - Repeat modes (none, one, all)
+ * - Auto-advance to next track
+ * - Gapless playback preparation
+ * - LocalStorage persistence
+ */
+
+/**
+ * Create a Playlist Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Playlist Plugin instance
+ *
+ * @example
+ * ```ts
+ * import { createPlaylistPlugin } from '@scarlett-player/playlist';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: document.getElementById('player'),
+ *   plugins: [
+ *     createPlaylistPlugin({
+ *       autoAdvance: true,
+ *       shuffle: false,
+ *       repeat: 'none',
+ *     }),
+ *   ],
+ * });
+ *
+ * // Add tracks
+ * const playlist = player.getPlugin('playlist');
+ * playlist.add([
+ *   { id: '1', src: 'track1.mp3', title: 'Track 1', artist: 'Artist' },
+ *   { id: '2', src: 'track2.mp3', title: 'Track 2', artist: 'Artist' },
+ * ]);
+ *
+ * // Start playback
+ * playlist.play();
+ * ```
+ */
+declare function createPlaylistPlugin(config?: Partial<PlaylistPluginConfig>): IPlaylistPlugin;
+
+export { type IPlaylistPlugin, type PlaylistPluginConfig, type PlaylistState, type PlaylistTrack, type RepeatMode, createPlaylistPlugin, createPlaylistPlugin as default };

package/dist/index.js

@@ -0,0 +1,370 @@
+// src/index.ts
+var DEFAULT_CONFIG = {
+  autoAdvance: true,
+  preloadNext: true,
+  persist: false,
+  persistKey: "scarlett-playlist",
+  shuffle: false,
+  repeat: "none"
+};
+function generateId() {
+  return `track-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function shuffleArray(array) {
+  const result = [...array];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+function createPlaylistPlugin(config) {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  let api = null;
+  let tracks = mergedConfig.tracks || [];
+  let currentIndex = -1;
+  let shuffle = mergedConfig.shuffle || false;
+  let repeat = mergedConfig.repeat || "none";
+  let shuffleOrder = [];
+  tracks = tracks.map((t) => ({ ...t, id: t.id || generateId() }));
+  const generateShuffleOrder = () => {
+    const indices = tracks.map((_, i) => i);
+    shuffleOrder = shuffleArray(indices);
+    if (currentIndex >= 0) {
+      const currentPos = shuffleOrder.indexOf(currentIndex);
+      if (currentPos > 0) {
+        shuffleOrder.splice(currentPos, 1);
+        shuffleOrder.unshift(currentIndex);
+      }
+    }
+  };
+  const getActualIndex = (logicalIndex) => {
+    if (!shuffle || shuffleOrder.length === 0) {
+      return logicalIndex;
+    }
+    return shuffleOrder[logicalIndex] ?? logicalIndex;
+  };
+  const getLogicalIndex = (actualIndex) => {
+    if (!shuffle || shuffleOrder.length === 0) {
+      return actualIndex;
+    }
+    return shuffleOrder.indexOf(actualIndex);
+  };
+  const hasNextTrack = () => {
+    if (tracks.length === 0) return false;
+    if (repeat === "one" || repeat === "all") return true;
+    const logicalIndex = getLogicalIndex(currentIndex);
+    return logicalIndex < tracks.length - 1;
+  };
+  const hasPreviousTrack = () => {
+    if (tracks.length === 0) return false;
+    if (repeat === "one" || repeat === "all") return true;
+    const logicalIndex = getLogicalIndex(currentIndex);
+    return logicalIndex > 0;
+  };
+  const getNextIndex = () => {
+    if (tracks.length === 0) return -1;
+    if (repeat === "one") {
+      return currentIndex;
+    }
+    const logicalIndex = getLogicalIndex(currentIndex);
+    let nextLogical = logicalIndex + 1;
+    if (nextLogical >= tracks.length) {
+      if (repeat === "all") {
+        if (shuffle) {
+          generateShuffleOrder();
+        }
+        nextLogical = 0;
+      } else {
+        return -1;
+      }
+    }
+    return getActualIndex(nextLogical);
+  };
+  const getPreviousIndex = () => {
+    if (tracks.length === 0) return -1;
+    if (repeat === "one") {
+      return currentIndex;
+    }
+    const logicalIndex = getLogicalIndex(currentIndex);
+    let prevLogical = logicalIndex - 1;
+    if (prevLogical < 0) {
+      if (repeat === "all") {
+        prevLogical = tracks.length - 1;
+      } else {
+        return -1;
+      }
+    }
+    return getActualIndex(prevLogical);
+  };
+  const persistPlaylist = () => {
+    if (!mergedConfig.persist) return;
+    try {
+      const data = {
+        tracks,
+        currentIndex,
+        shuffle,
+        repeat,
+        shuffleOrder
+      };
+      localStorage.setItem(mergedConfig.persistKey, JSON.stringify(data));
+    } catch (e) {
+      api?.logger.warn("Failed to persist playlist", e);
+    }
+  };
+  const loadPersistedPlaylist = () => {
+    if (!mergedConfig.persist) return;
+    try {
+      const data = localStorage.getItem(mergedConfig.persistKey);
+      if (data) {
+        const parsed = JSON.parse(data);
+        tracks = parsed.tracks || [];
+        currentIndex = parsed.currentIndex ?? -1;
+        shuffle = parsed.shuffle ?? false;
+        repeat = parsed.repeat ?? "none";
+        shuffleOrder = parsed.shuffleOrder || [];
+      }
+    } catch (e) {
+      api?.logger.warn("Failed to load persisted playlist", e);
+    }
+  };
+  const emitChange = () => {
+    const track = currentIndex >= 0 ? tracks[currentIndex] : null;
+    api?.emit("playlist:change", { track, index: currentIndex });
+    persistPlaylist();
+  };
+  const setCurrentTrack = (index) => {
+    if (index < 0 || index >= tracks.length) {
+      api?.logger.warn("Invalid track index", { index });
+      return;
+    }
+    const track = tracks[index];
+    currentIndex = index;
+    api?.logger.info("Track changed", { index, title: track.title, src: track.src });
+    if (track.title) {
+      api?.setState("title", track.title);
+    }
+    if (track.artwork) {
+      api?.setState("poster", track.artwork);
+    }
+    api?.setState("mediaType", track.type || "audio");
+    emitChange();
+  };
+  const plugin = {
+    id: "playlist",
+    name: "Playlist",
+    version: "1.0.0",
+    type: "feature",
+    description: "Playlist management with shuffle, repeat, and gapless playback",
+    async init(pluginApi) {
+      api = pluginApi;
+      api.logger.info("Playlist plugin initialized");
+      loadPersistedPlaylist();
+      if (shuffle && tracks.length > 0) {
+        generateShuffleOrder();
+      }
+      const unsubEnded = api.on("playback:ended", () => {
+        if (!mergedConfig.autoAdvance) return;
+        const nextIdx = getNextIndex();
+        if (nextIdx >= 0) {
+          api?.logger.debug("Auto-advancing to next track", { nextIdx });
+          setCurrentTrack(nextIdx);
+        } else {
+          api?.logger.info("Playlist ended");
+          api?.emit("playlist:ended", void 0);
+        }
+      });
+      api.onDestroy(() => {
+        unsubEnded();
+        persistPlaylist();
+      });
+    },
+    async destroy() {
+      api?.logger.info("Playlist plugin destroying");
+      persistPlaylist();
+      api = null;
+    },
+    add(trackOrTracks) {
+      const newTracks = Array.isArray(trackOrTracks) ? trackOrTracks : [trackOrTracks];
+      newTracks.forEach((track) => {
+        const normalizedTrack = { ...track, id: track.id || generateId() };
+        const index = tracks.length;
+        tracks.push(normalizedTrack);
+        api?.emit("playlist:add", { track: normalizedTrack, index });
+        api?.logger.debug("Track added", { title: normalizedTrack.title, index });
+      });
+      if (shuffle) {
+        const startIndex = tracks.length - newTracks.length;
+        for (let i = startIndex; i < tracks.length; i++) {
+          const insertPos = Math.floor(Math.random() * (shuffleOrder.length - getLogicalIndex(currentIndex))) + getLogicalIndex(currentIndex) + 1;
+          shuffleOrder.splice(Math.min(insertPos, shuffleOrder.length), 0, i);
+        }
+      }
+      persistPlaylist();
+    },
+    insert(index, track) {
+      const normalizedTrack = { ...track, id: track.id || generateId() };
+      const clampedIndex = Math.max(0, Math.min(index, tracks.length));
+      tracks.splice(clampedIndex, 0, normalizedTrack);
+      if (currentIndex >= clampedIndex) {
+        currentIndex++;
+      }
+      if (shuffle) {
+        shuffleOrder = shuffleOrder.map((i) => i >= clampedIndex ? i + 1 : i);
+        const insertPos = Math.floor(Math.random() * shuffleOrder.length);
+        shuffleOrder.splice(insertPos, 0, clampedIndex);
+      }
+      api?.emit("playlist:add", { track: normalizedTrack, index: clampedIndex });
+      persistPlaylist();
+    },
+    remove(idOrIndex) {
+      let index;
+      if (typeof idOrIndex === "string") {
+        index = tracks.findIndex((t) => t.id === idOrIndex);
+        if (index === -1) {
+          api?.logger.warn("Track not found", { id: idOrIndex });
+          return;
+        }
+      } else {
+        index = idOrIndex;
+      }
+      if (index < 0 || index >= tracks.length) {
+        api?.logger.warn("Invalid track index", { index });
+        return;
+      }
+      const [removedTrack] = tracks.splice(index, 1);
+      if (index < currentIndex) {
+        currentIndex--;
+      } else if (index === currentIndex) {
+        if (currentIndex >= tracks.length) {
+          currentIndex = tracks.length - 1;
+        }
+        emitChange();
+      }
+      if (shuffle) {
+        shuffleOrder = shuffleOrder.filter((i) => i !== index).map((i) => i > index ? i - 1 : i);
+      }
+      api?.emit("playlist:remove", { track: removedTrack, index });
+      persistPlaylist();
+    },
+    clear() {
+      tracks = [];
+      currentIndex = -1;
+      shuffleOrder = [];
+      api?.emit("playlist:clear", void 0);
+      emitChange();
+    },
+    play(idOrIndex) {
+      let index;
+      if (idOrIndex === void 0) {
+        index = currentIndex >= 0 ? currentIndex : shuffle ? getActualIndex(0) : 0;
+      } else if (typeof idOrIndex === "string") {
+        index = tracks.findIndex((t) => t.id === idOrIndex);
+        if (index === -1) {
+          api?.logger.warn("Track not found", { id: idOrIndex });
+          return;
+        }
+      } else {
+        index = idOrIndex;
+      }
+      if (tracks.length === 0) {
+        api?.logger.warn("Playlist is empty");
+        return;
+      }
+      setCurrentTrack(index);
+    },
+    next() {
+      const nextIdx = getNextIndex();
+      if (nextIdx >= 0) {
+        setCurrentTrack(nextIdx);
+      } else {
+        api?.logger.info("No next track");
+      }
+    },
+    previous() {
+      const currentTime = api?.getState("currentTime") || 0;
+      if (currentTime > 3) {
+        api?.emit("playback:seeking", { time: 0 });
+        return;
+      }
+      const prevIdx = getPreviousIndex();
+      if (prevIdx >= 0) {
+        setCurrentTrack(prevIdx);
+      } else {
+        api?.logger.info("No previous track");
+      }
+    },
+    toggleShuffle() {
+      this.setShuffle(!shuffle);
+    },
+    setShuffle(enabled) {
+      shuffle = enabled;
+      if (enabled) {
+        generateShuffleOrder();
+      } else {
+        shuffleOrder = [];
+      }
+      api?.emit("playlist:shuffle", { enabled });
+      api?.logger.info("Shuffle mode", { enabled });
+      persistPlaylist();
+    },
+    cycleRepeat() {
+      const modes = ["none", "all", "one"];
+      const currentIdx = modes.indexOf(repeat);
+      const nextIdx = (currentIdx + 1) % modes.length;
+      this.setRepeat(modes[nextIdx]);
+    },
+    setRepeat(mode) {
+      repeat = mode;
+      api?.emit("playlist:repeat", { mode });
+      api?.logger.info("Repeat mode", { mode });
+      persistPlaylist();
+    },
+    move(fromIndex, toIndex) {
+      if (fromIndex < 0 || fromIndex >= tracks.length) return;
+      if (toIndex < 0 || toIndex >= tracks.length) return;
+      if (fromIndex === toIndex) return;
+      const [track] = tracks.splice(fromIndex, 1);
+      tracks.splice(toIndex, 0, track);
+      if (currentIndex === fromIndex) {
+        currentIndex = toIndex;
+      } else if (fromIndex < currentIndex && toIndex >= currentIndex) {
+        currentIndex--;
+      } else if (fromIndex > currentIndex && toIndex <= currentIndex) {
+        currentIndex++;
+      }
+      if (shuffle) {
+        generateShuffleOrder();
+      }
+      api?.emit("playlist:reorder", { tracks: [...tracks] });
+      persistPlaylist();
+    },
+    getState() {
+      return {
+        tracks: [...tracks],
+        currentIndex,
+        currentTrack: currentIndex >= 0 ? tracks[currentIndex] : null,
+        shuffle,
+        repeat,
+        shuffleOrder: [...shuffleOrder],
+        hasNext: hasNextTrack(),
+        hasPrevious: hasPreviousTrack()
+      };
+    },
+    getTracks() {
+      return [...tracks];
+    },
+    getCurrentTrack() {
+      return currentIndex >= 0 ? tracks[currentIndex] : null;
+    },
+    getTrack(id) {
+      return tracks.find((t) => t.id === id) || null;
+    }
+  };
+  return plugin;
+}
+var index_default = createPlaylistPlugin;
+export {
+  createPlaylistPlugin,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@scarlett-player/playlist",
+  "version": "0.2.0",
+  "description": "Playlist Plugin for Scarlett Player - Queue management, shuffle, repeat, and gapless playback",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@scarlett-player/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.0",
+    "jsdom": "^24.0.0",
+    "@scarlett-player/core": "0.2.0"
+  },
+  "keywords": [
+    "video",
+    "audio",
+    "player",
+    "playlist",
+    "queue",
+    "shuffle",
+    "repeat",
+    "gapless",
+    "scarlett"
+  ],
+  "author": "The Stream Platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hackney-Enterprises-Inc/scarlett-player.git",
+    "directory": "packages/plugins/playlist"
+  },
+  "bugs": {
+    "url": "https://github.com/Hackney-Enterprises-Inc/scarlett-player/issues"
+  },
+  "homepage": "https://scarlettplayer.com",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}