feat(anime): queue episodes to play next across anime

- Episode rows gain Play/Queue actions (and matching context-menu items); queued rows show their place in line, with a queue count and Clear queue in the episode header
- Queue lives in the main process (`anime-browser-queue.ts`) so it survives the browser window closing and advances on mpv's end-file even when nobody is watching; streams resolve at play time so a signed URL cannot expire while queued
- Holds mpv's keep-open off while the queue waits and restores it once empty; queueing with nothing playing just plays immediately
- Adds anime-browser-queue and episode-queue unit tests, IPC channels/contracts, and doc updates

src/animeui/animeui.ts

@@ -405,8 +405,15 @@ loadMoreButton.addEventListener('click', () => void loadNextPage());
 
 api.onBridgeState(renderBridgeState);
 
+// The queue changes without this window asking: it advances by itself when an
+// episode ends, whether or not anyone is looking at the browser.
+api.onQueueState((state) => detailPanel.setQueue(state));
+
 void (async () => {
   renderBridgeState({ stage: 'idle', progress: null, message: null });
+  // A queue survives the window being closed and reopened, so start from what
+  // the main process already holds rather than from empty.
+  void api.getQueue().then((state) => detailPanel.setQueue(state));
   try {
     const state = await api.ensureBridge();
     renderBridgeState(state);

src/animeui/detail-panel.ts

@@ -96,5 +96,7 @@ export function createDetailPanel({ api, setStatus }: DetailPanelOptions) {
     open,
     close,
     isOpen: (): boolean => !detail.classList.contains('hidden'),
+    /** The queue outlives the open anime, so it is pushed in from outside. */
+    setQueue: episodeList.setQueue,
   };
 }

src/animeui/detail.css

@@ -124,6 +124,19 @@
   color: var(--ok);
 }
 
+/* Everything lined up behind the episode playing now, across every anime. */
+.episodes-queued {
+  font-family: var(--mono);
+  font-size: 11px;
+  color: var(--accent);
+}
+
+.episodes-queue-clear {
+  padding: 3px 9px;
+  font-size: 11px;
+  border-radius: 7px;
+}
+
 /* Pushed to the far end so the counters stay next to the heading. */
 .episodes-filter {
   margin-left: auto;
@@ -155,6 +168,17 @@
   background: var(--line);
 }
 
+/*
+ * The row is the cue plus the two things you can do with it. The cue still
+ * fills the row and still plays on click; the actions sit over its trailing
+ * edge, so a row with nothing hovered looks exactly as it did before them.
+ */
+.cue-row {
+  position: relative;
+  display: flex;
+  align-items: stretch;
+}
+
 .cue {
   position: relative;
   display: grid;
@@ -162,7 +186,9 @@
   gap: 26px;
   align-items: baseline;
   width: 100%;
-  padding: 9px 10px 9px 0;
+  /* Room at the trailing edge for the actions that sit over it, kept whether or
+   * not they are showing, so a hover never slides them across the title. */
+  padding: 9px 132px 9px 0;
   border: none;
   border-radius: 8px;
   background: none;
@@ -243,6 +269,72 @@
   white-space: nowrap;
 }
 
+/*
+ * Hidden until the row is hovered or something inside it has focus, so the
+ * rail stays a list of episodes rather than a grid of buttons. Queued rows keep
+ * theirs on: that button is the only way back out of the queue.
+ */
+.cue-actions {
+  position: absolute;
+  right: 8px;
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  gap: 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.14s ease;
+}
+
+.cue-row:hover .cue-actions,
+.cue-row:focus-within .cue-actions,
+.cue-row[data-queued='true'] .cue-actions {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.cue-action {
+  padding: 4px 10px;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  background: var(--panel-elevated);
+  color: var(--faint);
+  font: inherit;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  cursor: pointer;
+  backdrop-filter: blur(6px);
+  transition:
+    color 0.14s ease,
+    border-color 0.14s ease;
+}
+
+.cue-action:hover {
+  color: var(--text);
+  border-color: var(--accent);
+}
+
+.cue-action[data-active='true'] {
+  color: var(--accent);
+  border-color: var(--accent);
+}
+
+/* The badge says where in line it is; the button beside it says it can leave. */
+.cue-queued {
+  margin-left: 10px;
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.06em;
+  color: var(--accent);
+  white-space: nowrap;
+}
+
+.cue[data-queued='true']::after {
+  background: var(--accent);
+  border-color: var(--accent);
+}
+
 .cue[data-state='loading'] {
   background: var(--panel-elevated);
 }

src/animeui/episode-list.ts

@@ -3,6 +3,8 @@ import { describe, el } from './dom';
 import { closeContextMenu, showContextMenu, type ContextMenuItem } from './context-menu';
 import { filterEpisodes } from './episode-filter';
 import { describeMarkCount, episodesInScope } from './episode-marks';
+import { describeQueuePosition } from './episode-queue';
+import { createEpisodeQueueControls } from './episode-queue-controls';
 import type { AnimeBrowserAPI, AnimeBrowserEpisode } from '../types/anime-browser';
 
 export interface SelectedAnime {
@@ -67,6 +69,25 @@ export function createEpisodeList({ api, setStatus, selectedAnime }: EpisodeList
     }
   }
 
+  const queue = createEpisodeQueueControls({
+    api,
+    setStatus,
+    selectedAnime,
+    playEpisode: (episode) => playEpisode(episode),
+    onChange: () => paint(),
+    onAdvance: (entry) => {
+      // The queue started this one, so the cue this window was holding belongs
+      // to an episode that has finished. The new one only earns the cue when it
+      // is an episode of the anime on screen.
+      const anime = selectedAnime();
+      const mine =
+        anime !== null && anime.sourceId === entry.sourceId && anime.url === entry.animeUrl;
+      cueState = mine ? { url: entry.episodeUrl, state: 'playing' } : null;
+      applyCueState();
+      setStatus(`Queue started ${entry.episodeName}.`, 'ok');
+    },
+  });
+
   async function playEpisode(episode: AnimeBrowserEpisode) {
     const anime = selectedAnime();
     if (!anime) return;
@@ -116,6 +137,7 @@ export function createEpisodeList({ api, setStatus, selectedAnime }: EpisodeList
   function createRow(item: ListedEpisode): HTMLLIElement {
     const { episode } = item;
     const row = document.createElement('li');
+    row.className = 'cue-row';
     const button = document.createElement('button');
     button.type = 'button';
     button.className = 'cue';
@@ -138,6 +160,17 @@ export function createEpisodeList({ api, setStatus, selectedAnime }: EpisodeList
       mark.textContent = '✓ watched';
       name.append(mark);
     }
+    const position = queue.positionOf(episode);
+    if (position !== undefined) {
+      button.dataset.queued = 'true';
+      // On the row too, so the actions can stay visible without asking the CSS
+      // to look inside for a queued cue.
+      row.dataset.queued = 'true';
+      const mark = document.createElement('span');
+      mark.className = 'cue-queued';
+      mark.textContent = describeQueuePosition(position);
+      name.append(mark);
+    }
     if (episode.uploadedAt !== null) {
       const uploaded = safeUploadDate(episode.uploadedAt);
       if (uploaded) {
@@ -154,10 +187,45 @@ export function createEpisodeList({ api, setStatus, selectedAnime }: EpisodeList
       event.preventDefault();
       openRowMenu(event, item);
     });
-    row.append(button);
+
+    // The row itself plays, which leaves the other choice — after this one, not
+    // instead of it — with nothing to click. These two spell both out, and a
+    // right-click on the row says the same thing in words.
+    const actions = document.createElement('div');
+    actions.className = 'cue-actions';
+    actions.append(
+      createRowAction('Play', `Play ${episode.name} now`, () => void playEpisode(episode)),
+      createRowAction(
+        position === undefined ? 'Queue' : 'Queued',
+        position === undefined
+          ? `Play ${episode.name} after the current episode`
+          : `Take ${episode.name} out of the queue`,
+        () => void queue.toggle(episode),
+        position !== undefined,
+      ),
+    );
+
+    row.append(button, actions);
     return row;
   }
 
+  function createRowAction(
+    label: string,
+    title: string,
+    onClick: () => void,
+    active = false,
+  ): HTMLButtonElement {
+    const action = document.createElement('button');
+    action.type = 'button';
+    action.className = 'cue-action';
+    action.textContent = label;
+    action.title = title;
+    action.setAttribute('aria-label', title);
+    if (active) action.dataset.active = 'true';
+    action.addEventListener('click', onClick);
+    return action;
+  }
+
   /**
    * The right-click menu on one episode: this episode, or this one and every
    * episode listed below it, which for a newest-first source is everything
@@ -169,8 +237,17 @@ export function createEpisodeList({ api, setStatus, selectedAnime }: EpisodeList
     const isWatched = watched.has(item.episode.url);
     const below = episodesInScope(listed, index, 'below');
     const items: ContextMenuItem[] = [
+      {
+        label: 'Play now',
+        onSelect: () => void playEpisode(item.episode),
+      },
+      {
+        label: queue.isQueued(item.episode) ? 'Remove from queue' : 'Play after current',
+        onSelect: () => void queue.toggle(item.episode),
+      },
       {
         label: isWatched ? 'Mark unwatched' : 'Mark watched',
+        separated: true,
         onSelect: () => void applyMark([item], !isWatched),
       },
     ];
@@ -335,5 +412,5 @@ export function createEpisodeList({ api, setStatus, selectedAnime }: EpisodeList
   });
   window.addEventListener('focus', () => void refreshWatchState());
 
-  return { render, clear, refreshWatchState };
+  return { render, clear, refreshWatchState, setQueue: queue.setState };
 }

src/animeui/episode-queue-controls.ts

@@ -0,0 +1,142 @@
+import { capture } from './browse-state';
+import { describe, el } from './dom';
+import { describeQueuePosition, queueKey, queuePositions } from './episode-queue';
+import type { SelectedAnime } from './episode-list';
+import type {
+  AnimeBrowserAPI,
+  AnimeBrowserEpisode,
+  AnimeBrowserQueueEntry,
+  AnimeBrowserQueueState,
+} from '../types/anime-browser';
+
+interface EpisodeQueueControlsOptions {
+  api: AnimeBrowserAPI;
+  setStatus: (message: string, tone?: 'info' | 'ok' | 'error') => void;
+  /** The anime the open detail page belongs to, or null once it is closed. */
+  selectedAnime: () => SelectedAnime | null;
+  /** Play now, with the cue states and status line the episode list owns. */
+  playEpisode: (episode: AnimeBrowserEpisode) => Promise<void>;
+  /** Repaint the rows; their badges and buttons read from this queue. */
+  onChange: () => void;
+  /** The queue started this episode by itself, so nothing else is playing now. */
+  onAdvance: (entry: AnimeBrowserQueueEntry) => void;
+}
+
+/**
+ * The play queue as this window sees it.
+ *
+ * The queue itself lives in the main process — it has to, since it advances
+ * when an episode ends whether or not this window is open. Everything here is a
+ * view of what it pushes back, plus the two calls that change it.
+ */
+export function createEpisodeQueueControls(options: EpisodeQueueControlsOptions) {
+  const { api, setStatus, selectedAnime, playEpisode, onChange, onAdvance } = options;
+  const queuedLabel = el<HTMLSpanElement>('episodes-queued');
+  const clearButton = el<HTMLButtonElement>('episodes-queue-clear');
+
+  let queue: AnimeBrowserQueueState = {
+    entries: [],
+    lastError: null,
+    advances: 0,
+    lastStarted: null,
+  };
+  let positions = new Map<string, number>();
+
+  function positionOf(episode: AnimeBrowserEpisode): number | undefined {
+    const anime = selectedAnime();
+    return anime ? positions.get(queueKey(anime.sourceId, episode.url)) : undefined;
+  }
+
+  function isQueued(episode: AnimeBrowserEpisode): boolean {
+    return positionOf(episode) !== undefined;
+  }
+
+  /** The queue as the main process now holds it, from a call or from a push. */
+  function setState(next: AnimeBrowserQueueState): void {
+    const previousError = queue.lastError;
+    const advanced = next.advances > queue.advances;
+    queue = next;
+    positions = queuePositions(next.entries);
+    paintHeader();
+    onChange();
+    // The episode this window had marked playing has ended, whether or not the
+    // one that replaced it is in the list on screen.
+    if (advanced && next.lastStarted) onAdvance(next.lastStarted);
+    // An advance that failed happened with nobody watching this window, so it
+    // is reported once rather than on every repaint after it.
+    if (next.lastError && next.lastError !== previousError) {
+      setStatus(`Queue stopped — ${next.lastError}`, 'error');
+    }
+  }
+
+  /**
+   * The queue spans every anime, so it is counted whole even when none of its
+   * episodes are in the list on screen.
+   */
+  function paintHeader(): void {
+    const queued = queue.entries.length;
+    queuedLabel.textContent = queued > 0 ? `Queue · ${queued}` : '';
+    queuedLabel.classList.toggle('hidden', queued === 0);
+    clearButton.classList.toggle('hidden', queued === 0);
+  }
+
+  /** Queue the episode, or take it back out when it is already in line. */
+  async function toggle(episode: AnimeBrowserEpisode): Promise<void> {
+    const anime = selectedAnime();
+    if (!anime) return;
+
+    const queued = isQueued(episode);
+    // Queueing behind nothing would wait for an end that never comes, so with
+    // an idle player the second option collapses into the first.
+    if (!queued) {
+      const playing = await capture(() => api.isPlaying());
+      if (playing.ok && !playing.value) {
+        setStatus('Nothing was playing, so this starts now.');
+        await playEpisode(episode);
+        return;
+      }
+    }
+
+    const attempt = await capture(() =>
+      queued
+        ? api.dequeueEpisode(anime.sourceId, episode.url)
+        : api.queueEpisode({
+            sourceId: anime.sourceId,
+            animeUrl: anime.url,
+            animeTitle: anime.title,
+            episodeUrl: episode.url,
+            episodeName: episode.name,
+            episodeNumber: episode.number,
+          }),
+    );
+    if (!attempt.ok) {
+      setStatus(describe(attempt.error), 'error');
+      return;
+    }
+
+    // Applied from what the call returned rather than waited for on the push
+    // channel, so the row settles on the click that changed it.
+    setState(attempt.value);
+    const position = positionOf(episode);
+    setStatus(
+      position === undefined
+        ? `${episode.name} left the queue.`
+        : `${episode.name} is ${describeQueuePosition(position)}.`,
+      'ok',
+    );
+  }
+
+  async function clear(): Promise<void> {
+    const attempt = await capture(() => api.clearQueue());
+    if (!attempt.ok) {
+      setStatus(describe(attempt.error), 'error');
+      return;
+    }
+    setState(attempt.value);
+    setStatus('Queue cleared.', 'ok');
+  }
+
+  clearButton.addEventListener('click', () => void clear());
+
+  return { positionOf, isQueued, setState, toggle };
+}

src/animeui/episode-queue.test.ts

@@ -0,0 +1,40 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { describeQueuePosition, queueKey, queuePositions } from './episode-queue';
+import type { AnimeBrowserQueueEntry } from '../types/anime-browser';
+
+function entry(overrides: Partial<AnimeBrowserQueueEntry> = {}): AnimeBrowserQueueEntry {
+  return {
+    sourceId: 'source',
+    animeUrl: '/anime',
+    animeTitle: 'Anime',
+    episodeUrl: '/episode-1',
+    episodeName: 'Episode 1',
+    episodeNumber: 1,
+    ...overrides,
+  };
+}
+
+test('positions count across the whole queue, not within one anime', () => {
+  const positions = queuePositions([
+    entry(),
+    entry({ animeUrl: '/other', episodeUrl: '/other-1' }),
+    entry({ episodeUrl: '/episode-2' }),
+  ]);
+
+  assert.equal(positions.get(queueKey('source', '/episode-1')), 1);
+  assert.equal(positions.get(queueKey('source', '/other-1')), 2);
+  assert.equal(positions.get(queueKey('source', '/episode-2')), 3);
+});
+
+test('the same episode url on two sources keeps two positions', () => {
+  const positions = queuePositions([entry(), entry({ sourceId: 'other' })]);
+
+  assert.equal(positions.get(queueKey('source', '/episode-1')), 1);
+  assert.equal(positions.get(queueKey('other', '/episode-1')), 2);
+});
+
+test('the episode about to play is named rather than numbered', () => {
+  assert.equal(describeQueuePosition(1), 'next up');
+  assert.equal(describeQueuePosition(4), '#4 in queue');
+});

src/animeui/episode-queue.ts

@@ -0,0 +1,28 @@
+import type { AnimeBrowserQueueEntry } from '../types/anime-browser';
+
+/**
+ * Where each queued episode sits in line, keyed by source and episode url.
+ *
+ * The position is counted across the whole queue rather than within one anime:
+ * "3rd up" has to mean the same thing on every detail page, or the number is
+ * worse than no number at all.
+ */
+export function queuePositions(entries: AnimeBrowserQueueEntry[]): Map<string, number> {
+  const positions = new Map<string, number>();
+  entries.forEach((entry, index) => {
+    const key = queueKey(entry.sourceId, entry.episodeUrl);
+    // A duplicate should never reach the renderer, but if one did, the earlier
+    // position is the one that will actually play.
+    if (!positions.has(key)) positions.set(key, index + 1);
+  });
+  return positions;
+}
+
+export function queueKey(sourceId: string, episodeUrl: string): string {
+  return `${sourceId} ${episodeUrl}`;
+}
+
+/** "Next up" reads better than "#1" for the episode about to play. */
+export function describeQueuePosition(position: number): string {
+  return position === 1 ? 'next up' : `#${position} in queue`;
+}

src/animeui/index.html

@@ -152,6 +152,14 @@
             <h3 class="episodes-title">Episodes</h3>
             <span class="episodes-count" id="episodes-count"></span>
             <span class="episodes-watched hidden" id="episodes-watched"></span>
+            <span class="episodes-queued hidden" id="episodes-queued"></span>
+            <button
+              class="ghost-button episodes-queue-clear hidden"
+              id="episodes-queue-clear"
+              type="button"
+            >
+              Clear queue
+            </button>
             <input
               class="text-input episodes-filter hidden"
               id="episodes-filter"