@scarlett-player/playlist 1.8.0 → 1.9.0

package/README.md

@@ -0,0 +1,126 @@
+# @scarlett-player/playlist
+
+Playlist plugin for [Scarlett Player](https://scarlettplayer.com). Queue management (add, insert, remove, move, clear), shuffle with a Fisher-Yates order, repeat modes, auto-advance when a track ends, optional localStorage persistence, and control-bar buttons for previous, next and a queue panel when `@scarlett-player/ui` is installed.
+
+## Installation
+
+```bash
+pnpm add @scarlett-player/playlist @scarlett-player/core
+```
+
+`@scarlett-player/core` is a required peer dependency. `@scarlett-player/ui` is an optional peer: the control-bar controls register only when it is present, and everything else works without it.
+
+## Usage
+
+This matches the audio example in the root README.
+
+```ts
+import { createPlayer } from '@scarlett-player/core';
+import { createNativePlugin } from '@scarlett-player/native';
+import { createAudioUIPlugin } from '@scarlett-player/audio-ui';
+import { createPlaylistPlugin, type IPlaylistPlugin } from '@scarlett-player/playlist';
+import { createMediaSessionPlugin } from '@scarlett-player/media-session';
+
+const player = await createPlayer({
+  container: document.getElementById('audio-player'),
+  plugins: [
+    createNativePlugin(),
+    createAudioUIPlugin({ layout: 'full' }),
+    createPlaylistPlugin({
+      tracks: [
+        { id: '1', src: '/track1.mp3', title: 'Track 1', artist: 'Artist', artwork: '/art1.jpg' },
+        { id: '2', src: '/track2.mp3', title: 'Track 2', artist: 'Artist', artwork: '/art2.jpg' },
+      ],
+    }),
+    createMediaSessionPlugin(),
+  ],
+});
+
+// Start the first track through the playlist, not through `src` or
+// player.load(). The playlist owns the current index: play() sets it, writes
+// the track's title and artwork into state, and emits `media:load-request`,
+// which the player loads and plays. Loading a source behind the playlist's
+// back leaves its index pointing at nothing, so next/previous and
+// auto-advance start from the wrong place.
+const playlist = player.getPlugin<IPlaylistPlugin>('playlist');
+playlist?.play(0);
+```
+
+If you do pass `src` to `createPlayer()` for the first track, set `initialIndex: 0` so the playlist knows which track is already loaded.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `tracks` | `PlaylistTrack[]` | `[]` | Initial queue. Tracks without an `id` get a generated one |
+| `autoAdvance` | `boolean` | `true` | Select the next track on `playback:ended` |
+| `advanceDelay` | `number` | `0` | Milliseconds to wait before auto-advancing |
+| `autoLoad` | `boolean` | `true` | Emit `media:load-request` with `autoplay: true` whenever the current track changes, so the player loads it. Set to `false` to load from `playlist:change` yourself |
+| `shuffle` | `boolean` | `false` | Initial shuffle state |
+| `repeat` | `'none' \| 'one' \| 'all'` | `'none'` | Initial repeat mode |
+| `initialIndex` | `number` | `-1` | Index of the track already loaded by the player. `-1` means no track is active. Out-of-range values fall back to `-1` |
+| `persist` | `boolean` | `false` | Save tracks, index, shuffle and repeat to localStorage and restore them on init |
+| `persistKey` | `string` | `'scarlett-playlist'` | localStorage key used by `persist` |
+| `preloadNext` | `boolean` | `true` | Accepted and stored, but no code path currently reads it |
+
+A `PlaylistTrack` is `{ id, src, title?, artist?, album?, artwork?, duration?, type?, mimeType?, metadata? }` plus any extra properties you want to carry. `type` defaults to `'audio'` in player state when omitted.
+
+## Plugin API
+
+Registered under the id `playlist`; retrieve it with `player.getPlugin<IPlaylistPlugin>('playlist')`.
+
+| Method | Description |
+|---|---|
+| `add(track \| track[])` | Append to the queue |
+| `insert(index, track)` | Insert at a position (clamped to the queue length) |
+| `remove(idOrIndex)` | Remove by id or index. Removing the current track selects the track that slides into its slot |
+| `move(fromIndex, toIndex)` | Reorder |
+| `clear()` | Empty the queue and reset the index to `-1` |
+| `play(idOrIndex?)` | Select a track. With no argument, resumes the current track or starts the first |
+| `next()` / `previous()` | Step through the queue honouring shuffle and repeat. `previous()` restarts the current track when more than 3 seconds in |
+| `toggleShuffle()` / `setShuffle(enabled)` | Shuffle control. The current track stays first in the new order |
+| `cycleRepeat()` / `setRepeat(mode)` | Repeat control. `cycleRepeat()` goes none, all, one |
+| `getState()` | `{ tracks, currentIndex, currentTrack, shuffle, repeat, shuffleOrder, hasNext, hasPrevious }` |
+| `getTracks()` / `getCurrentTrack()` / `getTrack(id)` | Read the queue |
+
+With the player focused, the `N` and `P` keys call `next()` and `previous()`. Keystrokes inside inputs or with a modifier held are left alone.
+
+## Events
+
+All payload types live in `PlayerEventMap` in `@scarlett-player/core`.
+
+| Event | Payload | When |
+|---|---|---|
+| `playlist:change` | `{ track, index }` | The current track changed. `track` is `null` after `clear()` |
+| `playlist:add` | `{ track, index }` | `add()` (once per track) or `insert()` |
+| `playlist:remove` | `{ track, index }` | `remove()` |
+| `playlist:reorder` | `{ tracks }` | `move()` |
+| `playlist:clear` | `void` | `clear()` |
+| `playlist:shuffle` | `{ enabled }` | Shuffle changed |
+| `playlist:repeat` | `{ mode }` | Repeat mode changed |
+| `playlist:ended` | `void` | The last track ended with nothing to advance to |
+
+On every track change the plugin also writes `title`, `poster` (from `artwork`) and `mediaType` into player state, clearing title and poster when the track has none so a previous track's values never leak.
+
+## Control-bar controls
+
+When `@scarlett-player/ui` is installed, three controls are registered. Nothing is placed until you list them in the UI layout:
+
+```ts
+uiPlugin({ controls: ['playlist-previous', 'play', 'playlist-next', 'progress', 'spacer', 'playlist', 'fullscreen'] })
+```
+
+| Control id | Renders |
+|---|---|
+| `playlist-previous` / `playlist-next` | Skip buttons, disabled at the ends of the queue |
+| `playlist` | A button that opens the queue as a list |
+
+All three hide themselves when the queue has one track or fewer. The classes `PlaylistSkipButton`, `PlaylistPanel` and the `PLAYLIST_ICONS` map are exported for custom layouts.
+
+## Styling
+
+A stylesheet is injected once per document (style element id `sp-playlist-styles`). Override these classes to restyle: `sp-playlist-skip` (with `--previous` / `--next` and the `[disabled]` state), `sp-playlist`, `sp-playlist--open`, `sp-playlist__button`, `sp-playlist__panel`, `sp-playlist__item`, `sp-playlist__item--active`, `sp-playlist__position`, `sp-playlist__text`, `sp-playlist__title` and `sp-playlist__artist`. No CSS custom properties are used.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
+var import_core2 = require("@scarlett-player/core");
 
 // src/controls.ts
 var PLAYLIST_ICONS = {
@@ -197,6 +198,7 @@ var PlaylistPanel = class {
 };
 
 // src/styles.ts
+var import_core = require("@scarlett-player/core");
 var STYLE_ID = "sp-playlist-styles";
 var styles = `
 .sp-playlist-skip[disabled] {
@@ -298,18 +300,11 @@ var styles = `
 }
 `;
 function injectStyles() {
-  if (typeof document === "undefined" || document.getElementById(STYLE_ID)) {
-    return null;
-  }
-  const el = document.createElement("style");
-  el.id = STYLE_ID;
-  el.textContent = styles;
-  document.head.appendChild(el);
-  return el;
+  return (0, import_core.injectSharedStyles)(STYLE_ID, styles);
 }
 
 // src/version.ts
-var PKG_VERSION = true ? "1.7.1" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.9.0" : "0.0.0-dev";
 
 // src/index.ts
 var DEFAULT_CONFIG = {
@@ -336,6 +331,9 @@ function shuffleArray(array) {
 function createPlaylistPlugin(config) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
   let api = null;
+  let releaseStyles = null;
+  let releaseControls = null;
+  let lifecycle = 0;
   let tracks = mergedConfig.tracks || [];
   let currentIndex = mergedConfig.initialIndex ?? -1;
   if (currentIndex < -1 || currentIndex >= tracks.length) {
@@ -458,7 +456,7 @@ function createPlaylistPlugin(config) {
     }
     const track = tracks[index];
     currentIndex = index;
-    api?.logger.info("Track changed", { index, title: track.title, src: track.src });
+    api?.logger.info("Track changed", { index, title: track.title, src: (0, import_core2.sanitizeUrl)(track.src) });
     api?.setState("title", track.title || "");
     api?.setState("poster", track.artwork || "");
     api?.setState("mediaType", track.type || "audio");
@@ -474,6 +472,7 @@ function createPlaylistPlugin(config) {
     type: "feature",
     description: "Playlist management with shuffle, repeat, and gapless playback",
     async init(pluginApi) {
+      const generation = ++lifecycle;
       api = pluginApi;
       api.logger.info("Playlist plugin initialized");
       loadPersistedPlaylist();
@@ -499,20 +498,31 @@ function createPlaylistPlugin(config) {
           api?.emit("playlist:ended", void 0);
         }
       });
-      injectStyles();
-      void import("@scarlett-player/ui").then(({ registerControl }) => {
+      releaseStyles = injectStyles();
+      const owner = api.container;
+      void import("@scarlett-player/ui").then(({ registerControl, unregisterControl }) => {
+        if (generation !== lifecycle) return;
         const self = plugin;
         registerControl(
           "playlist-previous",
-          () => new PlaylistSkipButton(self, "previous")
+          () => new PlaylistSkipButton(self, "previous"),
+          { owner }
         );
-        registerControl("playlist-next", () => new PlaylistSkipButton(self, "next"));
+        registerControl("playlist-next", () => new PlaylistSkipButton(self, "next"), {
+          owner
+        });
         registerControl(
           "playlist",
           () => new PlaylistPanel(self, {
             onSelect: (index) => self.play(index)
-          })
+          }),
+          { owner }
         );
+        releaseControls = () => {
+          unregisterControl("playlist-previous", { owner });
+          unregisterControl("playlist-next", { owner });
+          unregisterControl("playlist", { owner });
+        };
       }).catch(() => {
         api?.logger.debug("@scarlett-player/ui not present, playlist controls not registered");
       });
@@ -543,8 +553,13 @@ function createPlaylistPlugin(config) {
       });
     },
     async destroy() {
+      lifecycle++;
       api?.logger.info("Playlist plugin destroying");
       persistPlaylist();
+      releaseStyles?.();
+      releaseStyles = null;
+      releaseControls?.();
+      releaseControls = null;
       api = null;
     },
     add(trackOrTracks) {

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/index.ts
+import { sanitizeUrl } from "@scarlett-player/core";
+
 // src/controls.ts
 var PLAYLIST_ICONS = {
   previous: '<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" focusable="false"><path d="M6 6h2v12H6V6zm3.5 6L18 6v12l-8.5-6z"/></svg>',
@@ -157,6 +160,7 @@ var PlaylistPanel = class {
 };
 
 // src/styles.ts
+import { injectSharedStyles } from "@scarlett-player/core";
 var STYLE_ID = "sp-playlist-styles";
 var styles = `
 .sp-playlist-skip[disabled] {
@@ -258,18 +262,11 @@ var styles = `
 }
 `;
 function injectStyles() {
-  if (typeof document === "undefined" || document.getElementById(STYLE_ID)) {
-    return null;
-  }
-  const el = document.createElement("style");
-  el.id = STYLE_ID;
-  el.textContent = styles;
-  document.head.appendChild(el);
-  return el;
+  return injectSharedStyles(STYLE_ID, styles);
 }
 
 // src/version.ts
-var PKG_VERSION = true ? "1.7.1" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.9.0" : "0.0.0-dev";
 
 // src/index.ts
 var DEFAULT_CONFIG = {
@@ -296,6 +293,9 @@ function shuffleArray(array) {
 function createPlaylistPlugin(config) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
   let api = null;
+  let releaseStyles = null;
+  let releaseControls = null;
+  let lifecycle = 0;
   let tracks = mergedConfig.tracks || [];
   let currentIndex = mergedConfig.initialIndex ?? -1;
   if (currentIndex < -1 || currentIndex >= tracks.length) {
@@ -418,7 +418,7 @@ function createPlaylistPlugin(config) {
     }
     const track = tracks[index];
     currentIndex = index;
-    api?.logger.info("Track changed", { index, title: track.title, src: track.src });
+    api?.logger.info("Track changed", { index, title: track.title, src: sanitizeUrl(track.src) });
     api?.setState("title", track.title || "");
     api?.setState("poster", track.artwork || "");
     api?.setState("mediaType", track.type || "audio");
@@ -434,6 +434,7 @@ function createPlaylistPlugin(config) {
     type: "feature",
     description: "Playlist management with shuffle, repeat, and gapless playback",
     async init(pluginApi) {
+      const generation = ++lifecycle;
       api = pluginApi;
       api.logger.info("Playlist plugin initialized");
       loadPersistedPlaylist();
@@ -459,20 +460,31 @@ function createPlaylistPlugin(config) {
           api?.emit("playlist:ended", void 0);
         }
       });
-      injectStyles();
-      void import("@scarlett-player/ui").then(({ registerControl }) => {
+      releaseStyles = injectStyles();
+      const owner = api.container;
+      void import("@scarlett-player/ui").then(({ registerControl, unregisterControl }) => {
+        if (generation !== lifecycle) return;
         const self = plugin;
         registerControl(
           "playlist-previous",
-          () => new PlaylistSkipButton(self, "previous")
+          () => new PlaylistSkipButton(self, "previous"),
+          { owner }
         );
-        registerControl("playlist-next", () => new PlaylistSkipButton(self, "next"));
+        registerControl("playlist-next", () => new PlaylistSkipButton(self, "next"), {
+          owner
+        });
         registerControl(
           "playlist",
           () => new PlaylistPanel(self, {
             onSelect: (index) => self.play(index)
-          })
+          }),
+          { owner }
         );
+        releaseControls = () => {
+          unregisterControl("playlist-previous", { owner });
+          unregisterControl("playlist-next", { owner });
+          unregisterControl("playlist", { owner });
+        };
       }).catch(() => {
         api?.logger.debug("@scarlett-player/ui not present, playlist controls not registered");
       });
@@ -503,8 +515,13 @@ function createPlaylistPlugin(config) {
       });
     },
     async destroy() {
+      lifecycle++;
       api?.logger.info("Playlist plugin destroying");
       persistPlaylist();
+      releaseStyles?.();
+      releaseStyles = null;
+      releaseControls?.();
+      releaseControls = null;
       api = null;
     },
     add(trackOrTracks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scarlett-player/playlist",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Playlist Plugin for Scarlett Player - Queue management, shuffle, repeat, and gapless playback",
   "type": "module",
   "main": "dist/index.cjs",
@@ -22,16 +22,16 @@
     "dist"
   ],
   "peerDependencies": {
-    "@scarlett-player/core": "^1.7.0",
-    "@scarlett-player/ui": "^1.7.0"
+    "@scarlett-player/core": "^1.8.0",
+    "@scarlett-player/ui": "^1.8.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^1.6.0",
     "jsdom": "^24.0.0",
-    "@scarlett-player/core": "1.8.0",
-    "@scarlett-player/ui": "1.8.0"
+    "@scarlett-player/core": "1.9.0",
+    "@scarlett-player/ui": "1.9.0"
   },
   "keywords": [
     "video",
@@ -65,6 +65,6 @@
     "dev": "tsup --watch",
     "test": "vitest --run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
   }
 }