kryten-webqueue 0.14.0__tar.gz → 0.14.2__tar.gz

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
+## [0.14.2] — 2026-06-13
+
+### Added
+
+- **Save all search/browse results to a playlist.** The Browse/search results page now shows an admin-only **Save results to playlist** button. It appends every catalog item matching the current search query or browse facets (across all pages, honouring the hidden-items toggle) to a playlist of your choosing. Where a season/episode marker is detectable in the title (`S01E02`, `1x02`, `Season 1 Episode 2`, …) items are laid out in proper series → season → episode order; everything else falls back to a stable alphabetical placement. Items already in the target playlist are skipped, so re-running is idempotent. Backend: `POST /admin/playlists/{id}/append-results` (admin-only) plus a de-duplicating bulk `Database.append_playlist_items` and a pure `playlists.ordering` helper.
+
+## [0.14.1] — 2026-06-13
+
+### Fixed
+
+- **Cancel/refund PM notifications only fire for AFK owners.** A user who *leaves* the channel is no longer connected to CyTube and cannot receive a PM, so the leave path now skips the notification entirely (the refund + WS state update still happen). AFK owners — who are still present — are PM'd as before. `presence_refund.notify_user` now governs the AFK case only.
+- **`no_repeat` promo selection is now deterministic.** When a `no_repeat` random draw matched the previous clip it was retried up to 8 times and could still return a repeat (a flaky guarantee for small pools). It now draws from the pool excluding the last clip, so a consecutive repeat never occurs for pools of 2+.
+
 ## [0.14.0] — 2026-06-13
 
 ### Added

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kryten-webqueue
-Version: 0.14.0
+Version: 0.14.2
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/docs/PLAN_PRESENCE_AND_PROMOS.md

@@ -419,6 +419,10 @@ load-time. (FP and general promos stay purely poller-driven.)
   a notice.)
 
   **RESOLVED (v0.13.0):** a PM is now sent. On a presence-based cancel the owner
-  receives a PM ("… cancelled and refunded because you left the channel / you
-  went AFK"), gated by `presence_refund.notify_user` (default on) and best-effort
-  so a failed PM never blocks the refund.
+  receives a PM ("… cancelled and refunded because you went AFK"), gated by
+  `presence_refund.notify_user` (default on) and best-effort so a failed PM never
+  blocks the refund.
+
+  **AMENDED (v0.14.1):** the PM only fires for **AFK** owners. A user who *left*
+  the channel is no longer connected to CyTube and cannot receive a PM, so the
+  leave path skips the notice (refund + WS state update still happen).

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/kryten_webqueue/catalog/db.py

@@ -980,6 +980,39 @@ class Database:
         await self._db.commit()
         return count
 
+    async def append_playlist_items(self, playlist_id: int, items: list[dict]) -> int:
+        """Append many items to the end of a playlist, skipping any whose
+        ``media_id`` is already present. Returns the number actually added."""
+        existing_rows = await self._fetch_all(
+            "SELECT media_id FROM saved_playlist_items WHERE playlist_id=?", [playlist_id]
+        )
+        seen = {r["media_id"] for r in existing_rows}
+        row = await self._fetch_one(
+            "SELECT COALESCE(MAX(position), -1) AS pos FROM saved_playlist_items WHERE playlist_id=?",
+            [playlist_id],
+        )
+        next_pos = (row["pos"] + 1) if row else 0
+        added = 0
+        for item in items:
+            media_id = item.get("media_id")
+            if not media_id or media_id in seen:
+                continue
+            seen.add(media_id)
+            await self._db.execute(
+                "INSERT INTO saved_playlist_items (playlist_id, position, media_type, media_id, title, duration_sec) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                [playlist_id, next_pos, item.get("media_type", "cm"), media_id,
+                 item.get("title"), item.get("duration_sec")],
+            )
+            next_pos += 1
+            added += 1
+        if added:
+            await self._db.execute(
+                "UPDATE saved_playlists SET updated_at=datetime('now') WHERE id=?", [playlist_id]
+            )
+        await self._db.commit()
+        return added
+
     async def get_most_recent_playlist(self, created_by: str) -> dict | None:
         """The given admin's most recently *created* saved playlist, if any."""
         return await self._fetch_one(

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/kryten_webqueue/config.py

@@ -35,7 +35,8 @@ class PresenceRefundConfig(BaseModel):
     off if running against an older Robot whose ``meta.afk`` goes stale.
 
     ``notify_user`` PMs the owner when a pending paid item is cancelled & refunded
-    so the cancellation isn't silent.
+    so the cancellation isn't silent. This only applies to **AFK** owners — a
+    user who left the channel is no longer connected and cannot receive a PM.
     """
 
     enabled: bool = True
@@ -43,7 +44,7 @@ class PresenceRefundConfig(BaseModel):
     on_afk: bool = True               # needs Kryten-Robot >= 1.10.0 deployed
     grace_seconds: float = 60.0       # wait before acting; re-check after grace
     check_interval_seconds: float = 15.0  # how often to evaluate owners
-    notify_user: bool = True          # PM the owner on cancel/refund
+    notify_user: bool = True          # PM the AFK owner on cancel/refund
 
 
 class PromoTypeConfig(BaseModel):

kryten_webqueue-0.14.2/kryten_webqueue/playlists/ordering.py

@@ -0,0 +1,77 @@
+"""Season/episode aware ordering for playlists built from search results (0.14.2).
+
+When an admin saves a whole result set to a playlist we try to lay episodic
+content out in natural watch order: grouped by series, then by season, then by
+episode. Items with no detectable season/episode marker fall back to an
+alphabetical-by-title placement, and ties always preserve the original input
+order (a stable sort) so the behaviour is deterministic.
+"""
+
+import re
+
+# Ordered most-specific first. Each pattern must expose season as group 1 and
+# episode as group 2.
+_SE_PATTERNS = [
+    # S01E02, s1e2, S01 E02, S01.E02, S01-E02
+    re.compile(r"[Ss](\d{1,2})\s*[._\- ]?\s*[Ee](\d{1,3})"),
+    # Season 1 Episode 2 / Season 1, Episode 02
+    re.compile(r"[Ss]eason\s*(\d{1,2}).*?[Ee]pisode\s*(\d{1,3})"),
+    # 1x02, 01x003
+    re.compile(r"\b(\d{1,2})[Xx](\d{1,3})\b"),
+]
+
+
+def parse_season_episode(title: str | None) -> tuple[int, int, int, int] | None:
+    """Parse a season/episode marker from ``title``.
+
+    Returns ``(season, episode, match_start, match_end)`` or ``None`` when no
+    recognised marker is present.
+    """
+    if not title:
+        return None
+    for pattern in _SE_PATTERNS:
+        m = pattern.search(title)
+        if not m:
+            continue
+        try:
+            season = int(m.group(1))
+            episode = int(m.group(2))
+        except (TypeError, ValueError):
+            continue
+        return season, episode, m.start(), m.end()
+    return None
+
+
+def _series_base(title: str, match_start: int) -> str:
+    """Best-effort series name: the text before the season/episode marker.
+
+    Falls back to the whole title when the marker sits at the very start.
+    """
+    base = title[:match_start].strip(" \t-–—_.:|")
+    return (base or title).strip().lower()
+
+
+def episode_sort_key(item: dict, index: int) -> tuple:
+    """Sort key for a catalog item.
+
+    Episodic items group under their series name then sort by season/episode.
+    Non-episodic items sort by their (lowercased) title. ``index`` is appended
+    so equal keys retain the caller's original ordering.
+    """
+    title = (item.get("title") or "").strip()
+    parsed = parse_season_episode(title)
+    if parsed:
+        season, episode, start, _ = parsed
+        return (_series_base(title, start), season, episode, index)
+    return (title.lower(), 0, 0, index)
+
+
+def order_for_playlist(items: list[dict]) -> list[dict]:
+    """Return ``items`` ordered for a playlist (season/episode aware, stable)."""
+    return [
+        item
+        for _, item in sorted(
+            enumerate(items),
+            key=lambda pair: episode_sort_key(pair[1], pair[0]),
+        )
+    ]

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/kryten_webqueue/promos/director.py

@@ -221,10 +221,13 @@ class PromoDirector:
             clip = self._rng.choice(pool)
             if self._config.general.no_repeat and len(pool) > 1:
                 last = self._last_clip_token.get(promo_type)
-                attempts = 0
-                while clip.get("media_id") == last and attempts < 8:
-                    clip = self._rng.choice(pool)
-                    attempts += 1
+                if clip.get("media_id") == last:
+                    # Draw from the rest of the pool so the no-repeat guarantee
+                    # always holds (bounded random retries could otherwise give
+                    # up and return a repeat).
+                    alternatives = [c for c in pool if c.get("media_id") != last]
+                    if alternatives:
+                        clip = self._rng.choice(alternatives)
         self._last_clip_token[promo_type] = clip.get("media_id")
         return clip
 

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/kryten_webqueue/queue/presence.py

@@ -178,19 +178,24 @@ class PresenceRefundMonitor:
     async def _notify_owner(self, item: dict, reason: str):
         """PM the owner that their paid item was cancelled & refunded.
 
+        Only AFK owners are notified: a user who *left* the channel is no longer
+        connected to CyTube and cannot receive a PM, so there is no point trying.
+        AFK users are still present and will see the message.
+
         Best-effort: a failed PM never blocks the cancel/refund itself.
         """
         if not getattr(self._config, "notify_user", False):
             return
+        if reason != "owner_afk":
+            return  # owner left the channel — unreachable by PM
         owner = item.get("paid_by")
         if not owner:
             return
-        why = "you left the channel" if reason == "owner_left" else "you went AFK"
         title = item.get("title") or "your queued item"
         try:
             await self._api_gate.send_pm(
                 owner,
-                f"Your queued item \"{title}\" was cancelled and refunded because {why}.",
+                f"Your queued item \"{title}\" was cancelled and refunded because you went AFK.",
             )
         except Exception:
             logger.debug("Presence cancel: failed to PM %s", owner, exc_info=True)

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/kryten_webqueue/routes/admin_playlists.py

@@ -166,6 +166,64 @@ async def append_item(request: Request, playlist_id: int, user: dict = Depends(r
     return {"success": True, "playlist_id": playlist_id, "name": playlist["name"], "count": count}
 
 
+@router.post("/{playlist_id}/append-results")
+async def append_results(request: Request, playlist_id: int, user: dict = Depends(require_admin)):
+    """Append every catalog item matching the current browse/search filters to a
+    playlist (0.14.2).
+
+    The browse/search facets are sent in the body so the server re-runs the same
+    (unpaginated) query the admin is looking at. Items are laid out in
+    season/episode order where a marker is detectable in the title, and any item
+    already present in the playlist is skipped.
+    """
+    from ..playlists.ordering import order_for_playlist
+
+    body = await request.json()
+    db = request.app.state.db
+    playlist = await db.get_saved_playlist(playlist_id)
+    if not playlist:
+        raise HTTPException(404, "Playlist not found")
+
+    mode = body.get("mode", "browse")
+    show_hidden = bool(body.get("show_hidden"))
+    sort = body.get("sort") or "default"
+
+    if mode == "search":
+        q = (body.get("q") or "").strip()
+        if not q:
+            raise HTTPException(400, "Query required for search results")
+        total = await db.search_count(q, show_hidden=show_hidden)
+        items = await db.search(q, page=1, per_page=max(total, 1),
+                                show_hidden=show_hidden, sort=sort)
+    else:
+        category = body.get("category") or None
+        tag = body.get("tag") or None
+        total = await db.browse_count(category=category, tag=tag, show_hidden=show_hidden)
+        items = await db.browse(category=category, tag=tag, page=1, per_page=max(total, 1),
+                                show_hidden=show_hidden, sort=sort)
+
+    ordered = order_for_playlist(items)
+    playlist_items = [
+        {
+            "media_type": "cm",
+            "media_id": it["manifest_url"],
+            "title": it.get("title"),
+            "duration_sec": it.get("duration_sec"),
+        }
+        for it in ordered
+        if it.get("manifest_url")
+    ]
+    added = await db.append_playlist_items(playlist_id, playlist_items)
+    count = len(await db.get_saved_playlist_items(playlist_id))
+    return {
+        "success": True,
+        "playlist_id": playlist_id,
+        "name": playlist["name"],
+        "added": added,
+        "count": count,
+    }
+
+
 @router.post("/parse-text")
 async def parse_text(request: Request, user: dict = Depends(require_admin)):
     """Parse the plain-text playlist import format into resolved items.

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/kryten_webqueue/static/css/main.css

@@ -150,6 +150,9 @@ a:hover {
 .admin-hidden-notice a {
     font-weight: 600;
 }
+.admin-results-actions {
+    margin-top: 0.85rem;
+}
 .search-form {
     display: flex;
     gap: 0.5rem;

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/kryten_webqueue/templates/catalog/browse.html

@@ -39,6 +39,9 @@
             <a href="{{ request.url.include_query_params(show_hidden=1) }}">Show hidden items?</a>
         {% endif %}
     </div>
+    <div class="admin-results-actions">
+        <button class="btn btn-sm btn-admin" onclick="saveResultsToPlaylist()">Save results to playlist</button>
+    </div>
     {% endif %}
 </div>
 
@@ -233,6 +236,83 @@ async function submitAddToPlaylist(playlistId, token) {
     }
 }
 
+// --- Save all current results to a playlist (rank >= 3) ---
+
+async function saveResultsToPlaylist() {
+    let playlists = [];
+    try {
+        const resp = await fetch('/admin/playlists/', { credentials: 'same-origin' });
+        if (resp.ok) playlists = await resp.json();
+    } catch (e) { /* handled below */ }
+    if (!playlists.length) {
+        showToast('No playlists yet — create one first', 'error');
+        return;
+    }
+    showResultsPlaylistPicker(playlists);
+}
+
+function showResultsPlaylistPicker(playlists) {
+    closePlaylistPickerModal();
+    const overlay = document.createElement('div');
+    overlay.id = 'playlist-picker-modal';
+    overlay.className = 'modal-overlay';
+    const opts = playlists.map(p => `<option value="${p.id}">${escapeHtml(p.name)}</option>`).join('');
+    const scope = CURRENT_QUERY ? 'search' : 'filter';
+    overlay.innerHTML = `
+        <div class="modal-box" role="dialog" aria-modal="true">
+            <h3>Save all results to playlist</h3>
+            <p class="muted">Every item matching the current ${scope} will be appended, ordered by season/episode where detected. Items already in the playlist are skipped.</p>
+            <div class="field">
+                <label for="playlist-picker-select">Playlist</label>
+                <select id="playlist-picker-select">${opts}</select>
+            </div>
+            <div class="modal-actions">
+                <button class="btn btn-secondary" data-action="cancel">Cancel</button>
+                <button class="btn btn-primary" data-action="save">Save results</button>
+            </div>
+        </div>`;
+    overlay.addEventListener('click', (e) => {
+        if (e.target === overlay) closePlaylistPickerModal();
+        const action = e.target.getAttribute('data-action');
+        if (action === 'cancel') closePlaylistPickerModal();
+        if (action === 'save') {
+            const pid = document.getElementById('playlist-picker-select').value;
+            closePlaylistPickerModal();
+            submitSaveResults(pid);
+        }
+    });
+    document.body.appendChild(overlay);
+}
+
+async function submitSaveResults(playlistId) {
+    const url = new URL(window.location.href);
+    const isSearch = url.pathname.indexOf('/catalog/search') !== -1;
+    const body = {
+        mode: isSearch ? 'search' : 'browse',
+        q: url.searchParams.get('q') || '',
+        category: url.searchParams.get('category') || '',
+        tag: url.searchParams.get('tag') || '',
+        sort: url.searchParams.get('sort') || 'default',
+        show_hidden: url.searchParams.get('show_hidden') ? 1 : 0,
+    };
+    showToast('Saving results…');
+    try {
+        const resp = await fetch(`/admin/playlists/${playlistId}/append-results`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            credentials: 'same-origin',
+            body: JSON.stringify(body),
+        });
+        const data = await resp.json();
+        showToast(
+            resp.ok ? `Added ${data.added} item(s) — playlist now ${data.count}`
+                    : (data.detail || `Failed (${resp.status})`),
+            resp.ok ? 'success' : 'error');
+    } catch (e) {
+        showToast(`Network error: ${e.message}`, 'error');
+    }
+}
+
 async function addToRecentPlaylist(token) {
     try {
         const resp = await fetch('/admin/playlists/recent/append', {

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kryten-webqueue"
-version = "0.14.0"
+version = "0.14.2"
 description = "Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube"
 readme = "README.md"
 license = "MIT"

{kryten_webqueue-0.14.0 → kryten_webqueue-0.14.2}/tests/test_presence_refund.py

@@ -126,12 +126,13 @@ async def test_owner_offline_cancels_paid_keeps_free():
     assert ws.messages and ws.messages[-1]["type"] == "queue_state"
 
 
-async def test_cancel_pms_owner_when_notify_enabled():
+async def test_afk_cancel_pms_owner_when_notify_enabled():
+    # AFK owners are still connected and CAN be PM'd.
     shadow = _FakeShadow([_paid(11, "alice", title="Cool Video")], now_playing={"uid": 10})
-    api = _FakeApiGate({"alice": {"online": False}}, np={"uid": 10})
+    api = _FakeApiGate({"alice": {"online": True, "meta": {"afk": True}}}, np={"uid": 10})
     db = _FakeDb({11: {"request_id": "r11", "username": "alice"}})
     ws = _FakeWs()
-    mon = _monitor(api, shadow, db, ws, notify_user=True)
+    mon = _monitor(api, shadow, db, ws, notify_user=True, on_afk=True)
 
     await mon.check_once()                        # first sighting: starts grace
     await mon.check_once()                        # grace elapsed: acts
@@ -140,21 +141,36 @@ async def test_cancel_pms_owner_when_notify_enabled():
     user, msg = api.pms[0]
     assert user == "alice"
     assert "Cool Video" in msg
-    assert "left the channel" in msg
+    assert "AFK" in msg
 
 
-async def test_cancel_silent_when_notify_disabled():
+async def test_left_channel_cancel_does_not_pm():
+    # A user who LEFT the channel is unreachable by PM — no PM attempted.
     shadow = _FakeShadow([_paid(11, "alice")], now_playing={"uid": 10})
     api = _FakeApiGate({"alice": {"online": False}}, np={"uid": 10})
     db = _FakeDb({11: {"request_id": "r11", "username": "alice"}})
     ws = _FakeWs()
-    mon = _monitor(api, shadow, db, ws, notify_user=False)
+    mon = _monitor(api, shadow, db, ws, notify_user=True)
 
     await mon.check_once()
     await mon.check_once()
 
     assert api.refunds == [("alice", "r11", "owner_left")]
     assert api.pms == []
+
+
+async def test_cancel_silent_when_notify_disabled():
+    shadow = _FakeShadow([_paid(11, "alice")], now_playing={"uid": 10})
+    api = _FakeApiGate({"alice": {"online": True, "meta": {"afk": True}}}, np={"uid": 10})
+    db = _FakeDb({11: {"request_id": "r11", "username": "alice"}})
+    ws = _FakeWs()
+    mon = _monitor(api, shadow, db, ws, notify_user=False, on_afk=True)
+
+    await mon.check_once()
+    await mon.check_once()
+
+    assert api.refunds == [("alice", "r11", "owner_afk")]
+    assert api.pms == []
     shadow = _FakeShadow([_paid(11, "bob")], now_playing={"uid": 10})
     api = _FakeApiGate({"bob": {"meta": {"afk": True}}}, np={"uid": 10})
     db = _FakeDb({11: {"request_id": "r11", "username": "bob"}})

kryten_webqueue-0.14.2/tests/test_save_results_to_playlist.py

@@ -0,0 +1,141 @@
+"""Save-all-results-to-playlist feature (0.14.2).
+
+Covers the pure season/episode ordering helper and the bulk, de-duplicating
+playlist append used by the admin "Save results to playlist" button.
+"""
+
+import pytest
+
+from kryten_webqueue.catalog.db import Database
+from kryten_webqueue.playlists.ordering import (
+    parse_season_episode,
+    order_for_playlist,
+)
+
+MEDIACMS = "https://www.dropsugar.com"
+
+
+@pytest.fixture
+async def db(tmp_path):
+    database = Database(str(tmp_path / "test.db"))
+    await database.connect()
+    await database.run_migrations()
+    yield database
+    await database.close()
+
+
+# --- pure: season/episode parsing ---
+
+@pytest.mark.parametrize("title,expected", [
+    ("Show Name S01E02 - The Title", (1, 2)),
+    ("Show Name s1e2", (1, 2)),
+    ("Show Name S01 E02", (1, 2)),
+    ("Show Name S01.E02", (1, 2)),
+    ("Show Name 1x02", (1, 2)),
+    ("Show Name 01x003", (1, 3)),
+    ("Show Name Season 2 Episode 11", (2, 11)),
+    ("A Plain Movie (2020)", None),
+    ("", None),
+    (None, None),
+])
+def test_parse_season_episode(title, expected):
+    parsed = parse_season_episode(title)
+    if expected is None:
+        assert parsed is None
+    else:
+        assert parsed is not None
+        assert (parsed[0], parsed[1]) == expected
+
+
+# --- pure: ordering ---
+
+def test_order_groups_series_by_season_episode():
+    items = [
+        {"title": "Cool Show S01E03"},
+        {"title": "Cool Show S02E01"},
+        {"title": "Cool Show S01E01"},
+        {"title": "Cool Show S01E02"},
+    ]
+    ordered = [i["title"] for i in order_for_playlist(items)]
+    assert ordered == [
+        "Cool Show S01E01",
+        "Cool Show S01E02",
+        "Cool Show S01E03",
+        "Cool Show S02E01",
+    ]
+
+
+def test_order_is_stable_for_non_episodic():
+    # No S/E markers: alphabetical by title, ties keep input order.
+    items = [
+        {"title": "Banana"},
+        {"title": "apple"},
+        {"title": "Cherry"},
+    ]
+    ordered = [i["title"] for i in order_for_playlist(items)]
+    assert ordered == ["apple", "Banana", "Cherry"]
+
+
+def test_order_separates_distinct_series():
+    items = [
+        {"title": "Zeta Show S01E02"},
+        {"title": "Alpha Show S01E02"},
+        {"title": "Alpha Show S01E01"},
+        {"title": "Zeta Show S01E01"},
+    ]
+    ordered = [i["title"] for i in order_for_playlist(items)]
+    assert ordered == [
+        "Alpha Show S01E01",
+        "Alpha Show S01E02",
+        "Zeta Show S01E01",
+        "Zeta Show S01E02",
+    ]
+
+
+# --- db: bulk append with de-dupe ---
+
+async def _make_playlist(db):
+    return await db.create_saved_playlist(
+        name="Results", description=None, is_immutable=False, created_by="admin",
+    )
+
+
+async def test_append_playlist_items_appends_in_order(db):
+    pid = await _make_playlist(db)
+    added = await db.append_playlist_items(pid, [
+        {"media_type": "cm", "media_id": "a", "title": "A", "duration_sec": 60},
+        {"media_type": "cm", "media_id": "b", "title": "B", "duration_sec": 60},
+    ])
+    assert added == 2
+    items = await db.get_saved_playlist_items(pid)
+    assert [i["media_id"] for i in items] == ["a", "b"]
+    assert [i["position"] for i in items] == [0, 1]
+
+
+async def test_append_playlist_items_skips_existing(db):
+    pid = await _make_playlist(db)
+    await db.append_playlist_items(pid, [
+        {"media_type": "cm", "media_id": "a", "title": "A"},
+        {"media_type": "cm", "media_id": "b", "title": "B"},
+    ])
+    # Second pass: only "c" is new; "a"/"b" already present.
+    added = await db.append_playlist_items(pid, [
+        {"media_type": "cm", "media_id": "a", "title": "A"},
+        {"media_type": "cm", "media_id": "c", "title": "C"},
+        {"media_type": "cm", "media_id": "b", "title": "B"},
+    ])
+    assert added == 1
+    items = await db.get_saved_playlist_items(pid)
+    assert [i["media_id"] for i in items] == ["a", "b", "c"]
+    assert [i["position"] for i in items] == [0, 1, 2]
+
+
+async def test_append_playlist_items_dedupes_within_batch(db):
+    pid = await _make_playlist(db)
+    added = await db.append_playlist_items(pid, [
+        {"media_type": "cm", "media_id": "x", "title": "X"},
+        {"media_type": "cm", "media_id": "x", "title": "X dup"},
+    ])
+    assert added == 1
+    items = await db.get_saved_playlist_items(pid)
+    assert [i["media_id"] for i in items] == ["x"]