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/main/runtime/anime-browser-ipc-handlers.ts

@@ -60,8 +60,17 @@ export function registerAnimeBrowserIpcHandlers(deps: AnimeBrowserIpcDeps): void
   handle(channels.animeBrowserAddRepo, (_event, url) => runtime.addRepo(String(url)));
   handle(channels.animeBrowserRemoveRepo, (_event, url) => runtime.removeRepo(String(url)));
   handle(channels.animeBrowserPlayEpisode, (_event, request) =>
-    runtime.playEpisode(request as AnimeBrowserPlayRequest),
+    runtime.playEpisode(toPlayRequest(request)),
   );
+  handle(channels.animeBrowserQueueEpisode, (_event, request) =>
+    runtime.queueEpisode(toPlayRequest(request)),
+  );
+  handle(channels.animeBrowserDequeueEpisode, (_event, sourceId, episodeUrl) =>
+    runtime.dequeueEpisode(String(sourceId ?? ''), String(episodeUrl ?? '')),
+  );
+  handle(channels.animeBrowserClearQueue, () => runtime.clearQueue());
+  handle(channels.animeBrowserGetQueue, () => runtime.getQueue());
+  handle(channels.animeBrowserIsPlaying, () => runtime.isPlaying());
   handle(channels.animeBrowserGetPreferences, (_event, sourceId) =>
     runtime.getPreferences(String(sourceId)),
   );
@@ -70,6 +79,24 @@ export function registerAnimeBrowserIpcHandlers(deps: AnimeBrowserIpcDeps): void
   );
 }
 
+/**
+ * Coerce a play (or queue) request. A queued request is held until its turn
+ * comes, so a bad field would surface long after the click that sent it.
+ */
+function toPlayRequest(value: unknown): AnimeBrowserPlayRequest {
+  const request = (value ?? {}) as Partial<AnimeBrowserPlayRequest>;
+  return {
+    sourceId: String(request.sourceId ?? ''),
+    animeUrl: String(request.animeUrl ?? ''),
+    animeTitle: String(request.animeTitle ?? ''),
+    episodeUrl: String(request.episodeUrl ?? ''),
+    episodeName: String(request.episodeName ?? ''),
+    // NaN and Infinity are numbers as far as typeof is concerned, and either
+    // one would reach the stats row as a nonsense episode number.
+    episodeNumber: Number.isFinite(request.episodeNumber) ? request.episodeNumber! : null,
+  };
+}
+
 /** Coerce a watch-state request; the renderer's arrays arrive untyped. */
 function toWatchStateRequest(value: unknown): AnimeBrowserWatchStateRequest {
   const request = (value ?? {}) as Partial<AnimeBrowserWatchStateRequest>;

src/main/runtime/anime-browser-queue.test.ts

@@ -0,0 +1,278 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { PlaybackEndFileEvent } from '../../anime-bridge/playback-outcome';
+import type { AnimeBrowserPlayRequest, AnimeBrowserQueueState } from '../../types/anime-browser';
+import { createAnimeBrowserQueue, type AnimeBrowserQueueDeps } from './anime-browser-queue';
+
+function makeRequest(overrides: Partial<AnimeBrowserPlayRequest> = {}): AnimeBrowserPlayRequest {
+  return {
+    sourceId: 'source',
+    animeUrl: '/anime',
+    animeTitle: 'Anime',
+    episodeUrl: '/episode-1',
+    episodeName: 'Episode 1',
+    episodeNumber: 1,
+    ...overrides,
+  };
+}
+
+interface Harness {
+  deps: AnimeBrowserQueueDeps;
+  played: AnimeBrowserPlayRequest[];
+  commands: Array<Array<string | number>>;
+  states: AnimeBrowserQueueState[];
+  osd: string[];
+  endFile: (event: PlaybackEndFileEvent) => void;
+  /** How many listeners are subscribed right now. */
+  listenerCount: () => number;
+}
+
+function makeHarness(
+  options: {
+    play?: (request: AnimeBrowserPlayRequest) => Promise<{
+      ok: boolean;
+      error: string | null;
+      quality: string | null;
+    }>;
+    keepOpen?: unknown;
+    withEndFile?: boolean;
+  } = {},
+): Harness {
+  const played: AnimeBrowserPlayRequest[] = [];
+  const commands: Array<Array<string | number>> = [];
+  const states: AnimeBrowserQueueState[] = [];
+  const osd: string[] = [];
+  const listeners = new Set<(event: PlaybackEndFileEvent) => void>();
+
+  const deps: AnimeBrowserQueueDeps = {
+    play: async (request) => {
+      played.push(request);
+      return options.play
+        ? await options.play(request)
+        : { ok: true, error: null, quality: '1080p' };
+    },
+    sendMpvCommand: (command) => void commands.push(command),
+    onQueueState: (state) => void states.push(state),
+    showMpvOsd: (message) => void osd.push(message),
+    log: () => undefined,
+  };
+  if (options.withEndFile !== false) {
+    deps.onPlaybackEndFile = (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    };
+  }
+  if (options.keepOpen !== undefined) {
+    deps.readMpvProperty = async (name) => {
+      if (name !== 'keep-open') throw new Error(`unexpected property ${name}`);
+      return options.keepOpen;
+    };
+  }
+
+  return {
+    deps,
+    played,
+    commands,
+    states,
+    osd,
+    endFile: (event) => {
+      for (const listener of [...listeners]) listener(event);
+    },
+    listenerCount: () => listeners.size,
+  };
+}
+
+const EOF: PlaybackEndFileEvent = { reason: 'eof', fileError: null };
+
+test('an episode that runs to its end hands the queue its turn', async () => {
+  const harness = makeHarness();
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  queue.enqueue(makeRequest({ episodeUrl: '/episode-2', episodeName: 'Episode 2' }));
+  harness.endFile(EOF);
+  await new Promise(setImmediate);
+
+  assert.deepEqual(
+    harness.played.map((request) => request.episodeUrl),
+    ['/episode-1'],
+  );
+  assert.deepEqual(
+    queue.getState().entries.map((entry) => entry.episodeUrl),
+    ['/episode-2'],
+  );
+});
+
+test('only a file that ended by itself advances the queue', async () => {
+  const harness = makeHarness();
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  harness.endFile({ reason: 'stop', fileError: null });
+  harness.endFile({ reason: 'quit', fileError: null });
+  harness.endFile({ reason: 'error', fileError: 'dead host' });
+  await new Promise(setImmediate);
+
+  assert.deepEqual(harness.played, []);
+  assert.equal(queue.getState().entries.length, 1);
+});
+
+test('queueing the same episode twice leaves one entry', () => {
+  const harness = makeHarness();
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  const state = queue.enqueue(makeRequest());
+
+  assert.equal(state.entries.length, 1);
+});
+
+test('an advance is counted and names the episode it started', async () => {
+  const harness = makeHarness();
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  assert.equal(queue.getState().advances, 0);
+  harness.endFile(EOF);
+  await new Promise(setImmediate);
+
+  const state = queue.getState();
+  assert.equal(state.advances, 1);
+  assert.equal(state.lastStarted?.episodeUrl, '/episode-1');
+});
+
+test('an episode dequeues by its own source and url', () => {
+  const harness = makeHarness();
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  queue.enqueue(makeRequest({ sourceId: 'other' }));
+  const state = queue.dequeue('source', '/episode-1');
+
+  assert.deepEqual(
+    state.entries.map((entry) => entry.sourceId),
+    ['other'],
+  );
+});
+
+test('a queued episode that will not play stops the queue and reports why', async () => {
+  const harness = makeHarness({
+    play: async () => ({
+      ok: false,
+      error: 'That source returned no playable video.',
+      quality: null,
+    }),
+  });
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  queue.enqueue(makeRequest({ episodeUrl: '/episode-2', episodeName: 'Episode 2' }));
+  harness.endFile(EOF);
+  await new Promise(setImmediate);
+
+  const state = queue.getState();
+  assert.equal(state.lastError, 'Episode 1: That source returned no playable video.');
+  // The failed episode is gone; the rest is still the user's queue.
+  assert.deepEqual(
+    state.entries.map((entry) => entry.episodeUrl),
+    ['/episode-2'],
+  );
+  assert.equal(harness.osd.length, 1);
+});
+
+test('a second end-file while an advance is resolving does not double-load', async () => {
+  let release = (): void => undefined;
+  const started = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const harness = makeHarness({
+    play: async () => {
+      await started;
+      return { ok: true, error: null, quality: null };
+    },
+  });
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  queue.enqueue(makeRequest({ episodeUrl: '/episode-2', episodeName: 'Episode 2' }));
+  harness.endFile(EOF);
+  harness.endFile(EOF);
+  release();
+  await new Promise(setImmediate);
+
+  assert.deepEqual(
+    harness.played.map((request) => request.episodeUrl),
+    ['/episode-1'],
+  );
+});
+
+test('mpv is told not to hold the last file open while the queue waits', async () => {
+  const harness = makeHarness({ keepOpen: 'yes' });
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  await new Promise(setImmediate);
+  assert.deepEqual(harness.commands, [['set_property', 'keep-open', 'no']]);
+
+  queue.clear();
+  assert.deepEqual(harness.commands[1], ['set_property', 'keep-open', 'yes']);
+});
+
+test('mpv that already lets files end is left alone', async () => {
+  const harness = makeHarness({ keepOpen: 'no' });
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  await new Promise(setImmediate);
+  queue.clear();
+
+  assert.deepEqual(harness.commands, []);
+});
+
+test('the last queued episode plays under the user own keep-open setting', async () => {
+  const harness = makeHarness({ keepOpen: 'always' });
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  await new Promise(setImmediate);
+  harness.endFile(EOF);
+  await new Promise(setImmediate);
+
+  assert.deepEqual(harness.commands, [
+    ['set_property', 'keep-open', 'no'],
+    ['set_property', 'keep-open', 'always'],
+  ]);
+});
+
+test('playback started outside the queue re-points the end-file listener', async () => {
+  const harness = makeHarness();
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  queue.handlePlaybackStarted();
+  queue.handlePlaybackStarted();
+
+  // Each re-arm replaces the previous subscription rather than stacking on it,
+  // so one end-file cannot advance the queue several times over.
+  assert.equal(harness.listenerCount(), 1);
+  harness.endFile(EOF);
+  await new Promise(setImmediate);
+  assert.equal(harness.played.length, 1);
+});
+
+test('an emptied queue stops listening for the end of the file', () => {
+  const harness = makeHarness();
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  queue.enqueue(makeRequest());
+  assert.equal(harness.listenerCount(), 1);
+  queue.dequeue('source', '/episode-1');
+  assert.equal(harness.listenerCount(), 0);
+});
+
+test('the queue still accepts episodes when mpv reports no events', () => {
+  const harness = makeHarness({ withEndFile: false });
+  const queue = createAnimeBrowserQueue(harness.deps);
+
+  assert.equal(queue.enqueue(makeRequest()).entries.length, 1);
+});

src/main/runtime/anime-browser-runtime-deps.ts

@@ -11,7 +11,11 @@ import type { SubtitleCacheIo } from '../../anime-bridge/subtitle-cache';
 import type { BundleBinaries } from '../../anime-bridge/sidecar-bundle';
 import { startSidecar } from '../../anime-bridge/sidecar-process';
 import { startStreamStripProxy } from '../../anime-bridge/stream-strip-proxy';
-import type { AnimeBrowserBridgeState, AnimeBrowserSearchUpdate } from '../../types/anime-browser';
+import type {
+  AnimeBrowserBridgeState,
+  AnimeBrowserQueueState,
+  AnimeBrowserSearchUpdate,
+} from '../../types/anime-browser';
 import type { InstallProgress } from './anime-bridge-installer';
 
 export interface AnimeBrowserRuntimeDeps {
@@ -53,6 +57,8 @@ export interface AnimeBrowserRuntimeDeps {
   /** Overrides the filesystem/network the subtitle cache uses. Tests only. */
   subtitleCacheIo?: SubtitleCacheIo;
   onBridgeState: (state: AnimeBrowserBridgeState) => void;
+  /** Pushes the play queue to the browser window, advances included. */
+  onQueueState?: (state: AnimeBrowserQueueState) => void;
   /** Streams per-source progress while a search invoke is pending. */
   onSearchUpdate?: (update: AnimeBrowserSearchUpdate) => void;
   preferredQuality?: () => string | undefined;

src/main/runtime/anime-browser-runtime.ts

@@ -37,6 +37,9 @@ import type {
   AnimeBrowserEntry,
   AnimeBrowserEpisode,
   AnimeBrowserEpisodeWatchState,
+  AnimeBrowserPlayRequest,
+  AnimeBrowserPlayResult,
+  AnimeBrowserQueueState,
   AnimeBrowserSetWatchedRequest,
   AnimeBrowserWatchStateRequest,
   AnimeBrowserSearchResult,
@@ -47,6 +50,7 @@ import type {
 } from '../../types/anime-browser';
 import type { BridgeAnimePage, BridgePreference } from '../../anime-bridge/types';
 import { createAnimeBrowserPlayback } from './anime-browser-playback';
+import { createAnimeBrowserQueue } from './anime-browser-queue';
 import type { AnimeBrowserRuntimeDeps } from './anime-browser-runtime-deps';
 export type { AnimeBrowserRuntimeDeps } from './anime-browser-runtime-deps';
 
@@ -350,6 +354,16 @@ export function createAnimeBrowserRuntime(deps: AnimeBrowserRuntimeDeps) {
     stripProxy: () => stripProxy,
   });
 
+  const queue = createAnimeBrowserQueue({
+    play: (request) => playback.playEpisode(request),
+    onPlaybackEndFile: deps.onPlaybackEndFile,
+    readMpvProperty: deps.readMpvProperty,
+    sendMpvCommand: deps.sendMpvCommand,
+    onQueueState: deps.onQueueState,
+    showMpvOsd: deps.showMpvOsd,
+    log: deps.log,
+  });
+
   return {
     getSnapshot(): AnimeBrowserSnapshot {
       return {
@@ -573,7 +587,45 @@ export function createAnimeBrowserRuntime(deps: AnimeBrowserRuntimeDeps) {
       });
     },
 
-    playEpisode: playback.playEpisode,
+    /**
+     * Play now, replacing whatever mpv has. The queue is left standing and
+     * re-armed behind this file, so an episode played by hand mid-queue is a
+     * detour rather than a reset.
+     */
+    async playEpisode(request: AnimeBrowserPlayRequest): Promise<AnimeBrowserPlayResult> {
+      const result = await playback.playEpisode(request);
+      if (result.ok) queue.handlePlaybackStarted();
+      return result;
+    },
+
+    queueEpisode(request: AnimeBrowserPlayRequest): AnimeBrowserQueueState {
+      return queue.enqueue(request);
+    },
+
+    dequeueEpisode(sourceId: string, episodeUrl: string): AnimeBrowserQueueState {
+      return queue.dequeue(sourceId, episodeUrl);
+    },
+
+    clearQueue(): AnimeBrowserQueueState {
+      return queue.clear();
+    },
+
+    getQueue(): AnimeBrowserQueueState {
+      return queue.getState();
+    },
+
+    /**
+     * Whether mpv has a file open. An mpv that is not running cannot answer,
+     * and there is nothing playing in it either, so both read as false.
+     */
+    async isPlaying(): Promise<boolean> {
+      if (!deps.readMpvProperty) return false;
+      try {
+        return (await deps.readMpvProperty('idle-active')) !== true;
+      } catch {
+        return false;
+      }
+    },
 
     async dispose(): Promise<void> {
       const handle = sidecar;
@@ -582,6 +634,7 @@ export function createAnimeBrowserRuntime(deps: AnimeBrowserRuntimeDeps) {
       stripProxy = null;
       starting = null;
       setState(IDLE_STATE);
+      queue.dispose();
       await playback.dispose();
       await proxy?.close();
       await handle?.stop();