Merge remote-tracking branch 'origin/main' into t3code/update-jellyfin-authentication

.github/workflows/package-release.yml

@@ -13,6 +13,9 @@ on:
         required: true
       APPLE_TEAM_ID:
         required: true
+      # Project TMDB key baked into release artifacts; builds stay valid without it.
+      SUBMINER_TMDB_API_KEY:
+        required: false
 
 permissions:
   contents: read
@@ -69,6 +72,8 @@ jobs:
 
       - name: Build AppImage
         run: bun run build:appimage
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
       - name: Build unversioned AppImage
         run: |
@@ -168,6 +173,7 @@ jobs:
       - name: Build signed + notarized macOS artifacts
         run: bun run build:mac
         env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
           CSC_LINK: ${{ secrets.CSC_LINK }}
           CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
           APPLE_ID: ${{ secrets.APPLE_ID }}
@@ -248,6 +254,8 @@ jobs:
 
       - name: Build unsigned Windows artifacts
         run: bun run build:win:unsigned
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
       - name: Smoke packaged runtime assets
         shell: bash

.github/workflows/prerelease.yml

@@ -27,6 +27,7 @@ jobs:
       APPLE_ID: ${{ secrets.APPLE_ID }}
       APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
       APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
   release:
     needs: [package]

.github/workflows/release.yml

@@ -28,6 +28,7 @@ jobs:
       APPLE_ID: ${{ secrets.APPLE_ID }}
       APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
       APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
   release:
     needs: [package]

changes/fix-timing-review-cancellation.md

@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Closing the overlay while media timing review is still loading now cancels setup and modal retries, restores playback if the review paused it, and cleans up the hidden preview player.

changes/runtime-ownership.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Cancel pending Linux overlay window replacements during teardown so a delayed close callback cannot reopen the overlay.

changes/stats-request-safety.md

@@ -0,0 +1,6 @@
+type: changed
+breaking: true
+area: stats
+
+- Reject requests from untrusted browser origins and hosts before stats data, media, or Anki operations run, and require JSON for mutation bodies.
+- Load the in-app stats overlay from the local server so it uses the same origin protection as the browser dashboard.

changes/tmdb-linking-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: stats
+
+- Documented provider reassignment, merge compatibility, and TMDB credential command caching and retry cooldown.

changes/tmdb-live-action-library.md

@@ -0,0 +1,8 @@
+type: added
+area: stats
+
+- Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB. Release builds include a project key, so it works out of the box; `tmdb.apiKey` (or `tmdb.apiKeyCommand`) overrides it, and is required when running from source.
+- Unlinked titles that AniList cannot match are looked up on TMDB automatically when the parsed filename matches a Japanese live-action title exactly; otherwise use the new **Link to TMDB** action on a title to pick it by hand.
+- Entries linked to the same TMDB title are merged into one card even when they came from different season folders, and the Library kind selector gained a Live Action option alongside Anime and YouTube.
+- Provider reassignment preserves the previous link and artwork if the replacement download fails, and refreshes completion totals when the episode count changes. Merges and sync keep conflicting AniList and TMDB identities separate, and the merge dialog explains when a selection mixes the two instead of failing.
+- TMDB credential commands cache successful output and wait 30 seconds before retrying failed or empty output, using the bundled key in the meantime when available.

changes/yomitan-upstream-26-9-8.md

@@ -0,0 +1,4 @@
+type: changed
+area: yomitan
+
+- Updated bundled Yomitan with upstream 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.

config.example.jsonc

@@ -659,6 +659,16 @@
     "maxSearchResults": 10 // Maximum TsukiHime search results returned.
   }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
 
+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
   // ==========================================
   // YouTube Playback Settings
   // Defaults for managed subtitle language preferences and YouTube subtitle loading.

docs-site/anilist-integration.md

@@ -71,6 +71,8 @@ SubMiner fetches cover art from AniList for display in the stats dashboard. When
 
 A no-match result is cached for 5 minutes before SubMiner retries, preventing repeated API calls for unrecognized media.
 
+When AniList has no match, SubMiner tries [TMDB](/configuration#tmdb) next so live-action dramas and movies get a poster and synopsis too. See [Immersion tracking](/immersion-tracking#library) for how live-action entries are grouped.
+
 If the automatic match is wrong, use **Change AniList Entry** on a title in the stats Library. Relinking rewrites the cached art for every episode of that title, and both the detail view and the Library grid pick up the new cover right away: the grid refetches after a relink, and cover responses carry an ETag and are revalidated on each request instead of being cached for a day.
 
 ## Rate limiting

docs-site/anki-integration.md

@@ -214,6 +214,8 @@ Confirming writes the combined lines to the sentence field. Reset drops the adde
 
 Clipboard updates and stats-dashboard mining never open timing review. The option is off by default and hot-reloads. **Review Media Timing** in the runtime options palette (`Ctrl/Cmd+Shift+O`) toggles it for the current session.
 
+If SubMiner closes the overlay while a timing review is still loading, it cancels pending setup and modal retries and restores playback if the review paused it. A new timing review can start after the overlay reopens.
+
 ### Screenshots (static)
 
 A single frame is captured at the current playback position.

docs-site/configuration.md

@@ -156,6 +156,7 @@ The configuration file includes several main sections:
 
 - [**Jimaku**](#jimaku) - Jimaku API configuration and defaults
 - [**TsukiHime**](#tsukihime) - Multi-language subtitle search and download
+- [**TMDB**](#tmdb) - Posters and synopses for live-action dramas and movies in the stats Library
 - [**Subtitle Sync**](#subtitle-sync) - Sync current subtitle with `alass`/`ffsubsync`
 - [**AniList**](#anilist) - Optional post-watch progress updates
 - [**Yomitan**](#yomitan) - Reuse an external read-only Yomitan profile
@@ -1158,6 +1159,32 @@ The keyboard shortcut lives under `shortcuts.openTsukihime` (default `Ctrl+Shift
 
 See [TsukiHime Integration](/tsukihime-integration) for the modal workflow, language tabs, and troubleshooting.
 
+### TMDB
+
+TMDB (The Movie Database) supplies posters, synopses, and show grouping for live-action dramas and movies in the stats [Library](/immersion-tracking#library). AniList only covers anime, so TMDB is what gives live-action titles a cover and a description.
+
+Release builds ship with a project TMDB key, so nothing needs to be configured. Set your own key to use your own quota, or when running SubMiner from source, where no key is bundled. Create one for free under **Settings > API** on [themoviedb.org](https://www.themoviedb.org/settings/api); either the short API key or the long "API Read Access Token" works.
+
+```json
+{
+  "tmdb": {
+    "apiKey": "",
+    "apiKeyCommand": "cat ~/.tmdb_key"
+  }
+}
+```
+
+| Option               | Values | Description                                                                                        |
+| -------------------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `tmdb.apiKey`        | string | Your own TMDB API key or read access token; overrides the bundled key (default: empty)             |
+| `tmdb.apiKeyCommand` | string | Shell command that prints the key to stdout, used instead of `apiKey` to keep it out of the config |
+
+Successful `apiKeyCommand` output is cached for the running client until `tmdb.apiKey` or `tmdb.apiKeyCommand` changes. Failed or empty command output uses the bundled key when available and waits 30 seconds before the next request can retry the command. Changing either credential setting resets this cooldown.
+
+Changes apply to the next TMDB request without a restart.
+
+This product uses the TMDB API but is not endorsed or certified by TMDB.
+
 ### Japanese subtitle generation
 
 Open the standalone modal with `Ctrl+Shift+G`, configurable through `shortcuts.openSubtitleGeneration`, or use the subtitle sidebar button. See [shortcuts](/shortcuts) for the shared mpv and overlay keybindings.

docs-site/immersion-tracking.md

@@ -31,6 +31,28 @@ Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_
 
 The same immersion data powers the stats dashboard.
 
+The browser dashboard and in-app stats overlay both load from the local HTTP server.
+The server accepts loopback hosts only and rejects requests from other browser origins,
+including opaque origins such as `file://`. API clients without a browser origin can
+still use the local API. Mutation requests with a body must use `application/json`;
+bodyless deletion and Anki browse requests remain supported. Requests rejected by the
+host or origin checks receive `403`; mutation bodies without a JSON content type
+receive `415`.
+
+Use the loopback dashboard URL directly. Reverse-proxied dashboards and Tailscale
+Serve URLs are unsupported because their host or browser origin is not the local
+server's origin. SSH stats synchronization is unchanged.
+
+Scripts sending a JSON body must include the content type. For example, this
+requests a duplicate-line cleanup preview without changing the database. Replace
+the port if you configured a different `stats.serverPort`:
+
+```bash
+curl http://127.0.0.1:6969/api/stats/maintenance/duplicate-lines \
+  -H 'Content-Type: application/json' \
+  -d '{"dryRun":true}'
+```
+
 - In-app overlay: focus the visible overlay, then press the key from `stats.toggleKey` (default: `` ` `` / `Backquote`).
 - Launcher command: run `subminer stats` to start the local stats server on demand (it also opens the dashboard in your browser when `stats.autoOpenBrowser` is enabled; the default is `false`).
 - Background server: run `subminer stats -b` to start or reuse a dedicated background stats daemon without keeping the launcher attached, and `subminer stats -s` to stop that daemon.
@@ -61,14 +83,16 @@ Local files and Jellyfin items with detected season numbers are split into seaso
 
 When older stats already grouped multiple seasons under one series entry, SubMiner moves parsed episodes into the season-specific entries on startup and rebuilds the affected summaries.
 
+**Live-action dramas and movies.** Anime covers come from AniList, which has no live-action titles. A title that AniList cannot match is looked up on [TMDB](/configuration#tmdb) instead (release builds bundle a key; source builds need your own): only a Japanese-language, non-animated result whose known titles match the parsed filename exactly is accepted, and it supplies the poster, synopsis, English and Japanese titles, and episode count. If nothing matches automatically, open the title and use **Link to TMDB** to search and pick it by hand. A TMDB show spans all of its seasons, so entries that resolve to the same TMDB title are merged into one card regardless of the season folder they came from, and the merged season titles are remembered so later episodes land on the same card. The **All Titles** / **Anime** / **Live Action** / **YouTube** selector above the grid narrows the Library to one kind, and a title's detail view shows whether it is a drama or a movie. Linking a title to AniList again turns it back into an anime entry. Changing providers downloads the replacement cover before saving the new link; a failed download leaves the previous link and artwork intact. A title without a cover clears the previous artwork. Automatic TMDB matching leaves existing AniList links unchanged.
+
 Jellyfin stream URLs are normalized to stable item links before stats titles are shown, so playback query parameters are not displayed in the dashboard.
 
-When YouTube channel metadata is available, the Library tab groups videos by creator/channel. Use **All Titles**, **Anime**, or **YouTube** above the grid to filter the library. Channel pages show tracked videos and their stats without AniList controls. Existing channel entries are classified as YouTube automatically on startup, preserving viewing history and manual video assignments. Anime and YouTube entries with the same normalized title remain separate, including during stats sync. Channels are excluded from anime metadata matching, season repair, and duplicate recommendations.
+When YouTube channel metadata is available, the Library tab groups videos by creator/channel. Use the kind selector above the grid (**All Titles**, **Anime**, **Live Action**, **YouTube**) to filter the library. Channel pages show tracked videos and their stats without AniList controls. Existing channel entries are classified as YouTube automatically on startup, preserving viewing history and manual video assignments. Anime and YouTube entries with the same normalized title remain separate, including during stats sync. Channels are excluded from anime metadata matching, season repair, and duplicate recommendations.
 
 A library entry is identified by its parsed title plus any detected season, so the same show can end up on several cards when releases disagree about the title or omit the season tag. Two fixes are available:
 
-- **Merge duplicates.** Hit **Select** above the grid, tick the cards that are the same show, and choose **Merge Selected**. Pick which entry to keep in the dialog; every episode moves onto it and the other cards are removed. Nothing is deleted, so sessions, mined cards and watch time all carry over. Anime entries and YouTube channels cannot be merged into each other. SubMiner remembers the merged title variants, so future episodes parsed with one of those names join the kept entry instead of recreating a duplicate card.
+- **Merge duplicates.** Hit **Select** above the grid, tick the cards that are the same show, and choose **Merge Selected**. Pick which entry to keep in the dialog; every episode moves onto it and the other cards are removed. Nothing is deleted, so sessions, mined cards and watch time all carry over. AniList-linked and TMDB-linked entries cannot be merged together, and YouTube channels cannot be merged with anime or live-action entries. SubMiner remembers the merged title variants, so future episodes parsed with one of those names join the kept entry instead of recreating a duplicate card.
-- **Move a single episode.** Hover an episode row in a title's episode list and use the **→** button to reassign it to another library entry of the same kind, so a YouTube video can only move between channels. The correction is remembered, so later filename parsing or Jellyfin metadata cannot move that episode back. For local files, later episodes in the same directory inherit the correction when their detected seasons are compatible and every manual correction there points to the same entry; a file that parses to a title which already has its own library entry keeps that identity instead. Conflicting seasons or manual destinations are left for review. If the move empties the old entry, that card is removed and you are returned to the grid.
+- **Move a single episode.** Hover an episode row in a title's episode list and use the **→** button to reassign it to another library entry. Anime and live-action entries are interchangeable here, but a YouTube video can only move between channels. The correction is remembered, so later filename parsing or Jellyfin metadata cannot move that episode back. For local files, later episodes in the same directory inherit the correction when their detected seasons are compatible and every manual correction there points to the same entry; a file that parses to a title which already has its own library entry keeps that identity instead. Conflicting seasons or manual destinations are left for review. If the move empties the old entry, that card is removed and you are returned to the grid.
 
 Once cover art resolves a series to an AniList entry, cards with compatible seasons are folded together automatically only when the searched title exactly matches an AniList title or synonym. A fuzzy result that points at an AniList entry already used by another card appears as a **Possible duplicate** review above the Library grid instead. Choose **Review merge** to compare the cards and pick which one to keep, or **Not duplicates** to dismiss that suggestion permanently. Entries with conflicting explicit season numbers are left alone rather than merged or suggested.
 
@@ -342,7 +366,7 @@ The exact schema version lives in `SCHEMA_VERSION` (`src/core/services/immersion
 Core tables:
 
 - `imm_videos` - video key/title/source metadata
-- `imm_anime` - anime/series or YouTube channel metadata (`media_kind`) referenced by videos and lifetime tables
+- `imm_anime` - series or YouTube channel metadata referenced by videos and lifetime tables, including the media kind (`anime`, `live_action` or `youtube`) and the AniList or TMDB link
 - `imm_anime_title_aliases` - alternate titles that resolve to the same anime row
 - `imm_anime_merge_recommendations` - candidate duplicate-series merges surfaced in the dashboard
 - `imm_sessions` - session UUID, video reference, timing/status, final denormalized totals

docs-site/public/config.example.jsonc

@@ -659,6 +659,16 @@
     "maxSearchResults": 10 // Maximum TsukiHime search results returned.
   }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
 
+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
   // ==========================================
   // YouTube Playback Settings
   // Defaults for managed subtitle language preferences and YouTube subtitle loading.

docs/RELEASING.md

@@ -15,7 +15,10 @@
 
 Stable and prerelease workflows share `.github/workflows/package-release.yml`.
 Both callers explicitly pass the five required macOS signing/notarization
-secrets; `GITHUB_TOKEN` remains automatically available to the reusable workflow.
+secrets plus the optional `SUBMINER_TMDB_API_KEY` (the project TMDB key that
+`scripts/prepare-build-assets.mjs` stages into `dist/bundled-integration-keys.json`;
+artifacts built without it simply require users to set `tmdb.apiKey`).
+`GITHUB_TOKEN` remains automatically available to the reusable workflow.
 Each platform verifies its ASAR and external resources before signing, then
 measures the signed app and installers before upload. Missing runtime assets,
 foreign SQLite/Koffi binaries, duplicate UI fonts, demo media, source maps,

docs/architecture/README.md

@@ -30,6 +30,7 @@ Update checks and startup launcher migration share a serialized update-state sto
 
 - `src/main/` owns composition, runtime setup, IPC wiring, and app lifecycle adapters.
 - `src/main/boot/` owns boot-phase assembly seams so `src/main.ts` can stay focused on lifecycle coordination and startup-path selection.
+- `src/main/runtime/linux-overlay-mode-runtime.ts` owns Linux fullscreen mode state and window replacement. App cleanup cancels pending replacements; `main.ts` supplies window creation and subtitle refresh hooks.
 - `src/core/services/` owns focused runtime services plus pure or side-effect-bounded logic.
 - `src/core/services/subtitle-generation*.ts` shares local whisper.cpp transcription, safe model downloads, and progress between the launcher and Electron. Optional dialogue mode retains both Silero-detected speech and other audible sections, omits confidently silent gaps, decodes passages independently, and restores original media timing. `src/main/runtime/subtitle-generation-runtime.ts` owns the overlay job lifecycle and only loads completed subtitles into the same local media; `src/shared/subtitle-generation*.ts` owns configuration, the multilingual model catalog, and IPC contracts. The overlay runtime retains a session model selection, validates picker requests through IPC, and keeps external model paths authoritative.
 - Subtitle model recommendations use bounded `nvidia-smi` and Whisper CUDA discovery probes in `subtitle-generation-acceleration.ts`. The overlay runtime caches results by executable path for 30 seconds and exposes acceleration status through the existing status IPC. Recommendations do not alter model selection or transcription arguments.

docs/architecture/domains.md

@@ -30,6 +30,7 @@ Read when: you need to find the owner module for a behavior or test surface
 - Immersion sync: `src/core/services/stats-sync/`, bound by `src/main/sync-cli.ts`.
   `snapshot-transfer.ts` selects compressed rsync or scp. `transfer-cache.ts` atomically retains the last successfully received snapshot per hashed peer/database identity under the config directory's `sync-transfer-cache/`. Cache copies seed isolated transfer directories; rsync verifies reconstructed files before the existing merge engine runs. The `--make-temp` / `--remove-temp` helpers accept an internal `--transfer-cache` key, with a fallback for older peers that do not recognize it.
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
+- TMDB live-action metadata: `src/core/services/tmdb/` (client + exact-title resolver), `src/core/services/immersion-tracker/live-action-link.ts` (links an entry to a TMDB title and merges other holders of the same title). The AniList cover-art fetcher calls the resolver as its fallback; `imm_anime.media_kind` marks the result and keeps the entry out of AniList season repair.
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
 - Window trackers: `src/window-trackers/`
 - Stats HTTP app: `src/core/services/stats-server.ts`, with route groups and shared route support

launcher/test-support/immersion-db-schema.test.ts

@@ -31,7 +31,7 @@ const SYNC_SCHEMA_OBJECTS = [
   'imm_lifetime_applied_sessions',
   'imm_stats_excluded_words',
   'idx_anime_normalized_title',
-  'idx_anime_kind_title',
+  'idx_anime_namespace_title',
   'idx_anime_anilist_id',
   'idx_videos_anime_id',
   'idx_sessions_video_started',

launcher/test-support/immersion-db-schema.ts

@@ -20,12 +20,14 @@ export const IMMERSION_DB_FIXTURE_DDL = `
     title_native TEXT,
     episodes_total INTEGER,
     description TEXT,
+    media_kind TEXT NOT NULL DEFAULT 'anime',
+    tmdb_id INTEGER,
+    tmdb_type TEXT,
     metadata_json TEXT,
     CREATED_DATE TEXT,
-    LAST_UPDATE_DATE TEXT,
+    LAST_UPDATE_DATE TEXT
-    media_kind TEXT NOT NULL DEFAULT 'anime' CHECK(media_kind IN ('anime', 'youtube'))
   );
-  CREATE UNIQUE INDEX idx_anime_kind_title ON imm_anime(media_kind, normalized_title_key);
+  CREATE UNIQUE INDEX idx_anime_namespace_title ON imm_anime((media_kind = 'youtube'), normalized_title_key);
   CREATE TABLE imm_videos(
     video_id INTEGER PRIMARY KEY AUTOINCREMENT,
     video_key TEXT NOT NULL UNIQUE,

scripts/bundled-integration-keys.mjs

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Release builds carry a project-owned TMDB key so live-action lookups work
+ * without user setup. The key is injected from the SUBMINER_TMDB_API_KEY
+ * environment variable at build time (a GitHub Actions secret in CI) and never
+ * lives in the repository. The runtime reader is
+ * src/core/services/tmdb/bundled-api-key.ts; keep the file name in sync.
+ */
+export const BUNDLED_INTEGRATION_KEYS_FILENAME = 'bundled-integration-keys.json';
+export const TMDB_API_KEY_ENV = 'SUBMINER_TMDB_API_KEY';
+
+/**
+ * Write the bundled keys file into `distDir`, or remove a stale one when no
+ * key is present so a keyless build never ships an older key by accident.
+ * Returns the names of the keys staged.
+ */
+export function stageBundledIntegrationKeys(distDir, env = process.env) {
+  const outputPath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+  const tmdbApiKey = env[TMDB_API_KEY_ENV]?.trim() ?? '';
+  if (!tmdbApiKey) {
+    fs.rmSync(outputPath, { force: true });
+    return [];
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify({ tmdbApiKey })}\n`, { mode: 0o644 });
+  return ['tmdb'];
+}

scripts/bundled-integration-keys.test.ts

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  BUNDLED_INTEGRATION_KEYS_FILENAME,
+  stageBundledIntegrationKeys,
+} from './bundled-integration-keys.mjs';
+
+function withDistDir(work: (distDir: string) => void): void {
+  const distDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-bundled-keys-'));
+  try {
+    work(distDir);
+  } finally {
+    fs.rmSync(distDir, { recursive: true, force: true });
+  }
+}
+
+test('stageBundledIntegrationKeys writes the TMDB key from the environment', () => {
+  withDistDir((distDir) => {
+    const staged = stageBundledIntegrationKeys(distDir, { SUBMINER_TMDB_API_KEY: ' abc123 ' });
+    assert.deepEqual(staged, ['tmdb']);
+    const written = JSON.parse(
+      fs.readFileSync(path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME), 'utf8'),
+    );
+    assert.deepEqual(written, { tmdbApiKey: 'abc123' });
+  });
+});
+
+test('stageBundledIntegrationKeys removes a stale file when the variable is unset', () => {
+  withDistDir((distDir) => {
+    const outputPath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+    fs.writeFileSync(outputPath, '{"tmdbApiKey":"old"}');
+    assert.deepEqual(stageBundledIntegrationKeys(distDir, {}), []);
+    assert.equal(fs.existsSync(outputPath), false);
+    assert.deepEqual(stageBundledIntegrationKeys(distDir, { SUBMINER_TMDB_API_KEY: '  ' }), []);
+  });
+});

scripts/prepare-build-assets.mjs

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { stageBundledIntegrationKeys, TMDB_API_KEY_ENV } from './bundled-integration-keys.mjs';
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(scriptDir, '..');
@@ -97,6 +98,17 @@ function buildMacosHelper() {
   }
 }
 
+// Only the key names are logged, never the values: CI masks secrets, but a
+// stray echo would still leak them into local build logs.
+function stageIntegrationKeys() {
+  const staged = stageBundledIntegrationKeys(path.join(repoRoot, 'dist'));
+  process.stdout.write(
+    staged.length > 0
+      ? `Staged bundled integration keys: ${staged.join(', ')}\n`
+      : `No bundled integration keys (${TMDB_API_KEY_ENV} unset)\n`,
+  );
+}
+
 function main() {
   fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(repoRoot, 'dist', 'fonts'), {
     recursive: true,
@@ -106,6 +118,7 @@ function main() {
   copySettingsAssets();
   copySyncUiAssets();
   buildMacosHelper();
+  stageIntegrationKeys();
 }
 
 main();

src/config/definitions.ts

@@ -42,6 +42,7 @@ const {
   ankiConnect,
   jimaku,
   tsukihime,
+  tmdb,
   anilist,
   mpv,
   yomitan,
@@ -76,6 +77,7 @@ export const DEFAULT_CONFIG: ResolvedConfig = {
   auto_start_overlay,
   jimaku,
   tsukihime,
+  tmdb,
   anilist,
   mpv,
   yomitan,

src/config/definitions/defaults-integrations.ts

@@ -6,6 +6,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
   | 'ankiConnect'
   | 'jimaku'
   | 'tsukihime'
+  | 'tmdb'
   | 'anilist'
   | 'mpv'
   | 'yomitan'
@@ -113,6 +114,10 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
     apiBaseUrl: 'https://api.tsukihime.org/v1',
     maxSearchResults: 10,
   },
+  tmdb: {
+    apiKey: '',
+    apiKeyCommand: '',
+  },
   mpv: {
     executablePath: '',
     launchMode: 'normal',

src/config/definitions/options-integrations.ts

@@ -479,6 +479,20 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.tsukihime.maxSearchResults,
       description: 'Maximum TsukiHime search results returned.',
     },
+    {
+      path: 'tmdb.apiKey',
+      kind: 'string',
+      defaultValue: defaultConfig.tmdb.apiKey,
+      description:
+        'Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).',
+    },
+    {
+      path: 'tmdb.apiKeyCommand',
+      kind: 'string',
+      defaultValue: defaultConfig.tmdb.apiKeyCommand,
+      description:
+        'Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.',
+    },
     {
       path: 'anilist.enabled',
       kind: 'boolean',

src/config/definitions/template-sections.ts

@@ -164,6 +164,14 @@ const INTEGRATION_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
     notes: ['Hot-reload: TsukiHime changes apply to the next TsukiHime request.'],
     key: 'tsukihime',
   },
+  {
+    title: 'TMDB',
+    description: [
+      'TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.',
+    ],
+    notes: ['Hot-reload: TMDB changes apply to the next TMDB request.'],
+    key: 'tmdb',
+  },
   {
     title: 'YouTube Playback Settings',
     description: [

src/config/hot-reload.ts

@@ -54,7 +54,7 @@ export function getConfigHotReloadField(path: string): string | null {
 
   // These consumers read the current config when the next operation starts.
   if (
-    ['jimaku', 'subsync', 'notifications', 'subtitleGeneration'].some((root) =>
+    ['jimaku', 'tmdb', 'subsync', 'notifications', 'subtitleGeneration'].some((root) =>
       pathStartsWith(path, root),
     )
   ) {

src/config/resolve/integrations.ts

@@ -58,6 +58,19 @@ export function applyIntegrationConfig(context: ResolveContext): void {
     warn('ai', src.ai, resolved.ai, 'Expected object.');
   }
 
+  if (isObject(src.tmdb)) {
+    for (const key of ['apiKey', 'apiKeyCommand'] as const) {
+      const value = asString(src.tmdb[key]);
+      if (value !== undefined) {
+        resolved.tmdb[key] = value;
+      } else if (src.tmdb[key] !== undefined) {
+        warn(`tmdb.${key}`, src.tmdb[key], resolved.tmdb[key], 'Expected string.');
+      }
+    }
+  } else if (src.tmdb !== undefined) {
+    warn('tmdb', src.tmdb, resolved.tmdb, 'Expected object.');
+  }
+
   if (isObject(src.anilist)) {
     const enabled = asBoolean(src.anilist.enabled);
     if (enabled !== undefined) {

src/config/settings/registry.test.ts

@@ -275,6 +275,9 @@ test('settings registry routes playback-related integrations into integrations',
   assert.equal(field('subsync.replace').section, 'Subtitle Sync');
   assert.equal(field('tsukihime.apiBaseUrl').category, 'integrations');
   assert.equal(field('tsukihime.apiBaseUrl').section, 'TsukiHime');
+  assert.equal(field('tmdb.apiKey').category, 'integrations');
+  assert.equal(field('tmdb.apiKey').section, 'TMDB');
+  assert.equal(field('tmdb.apiKey').secret, true);
 });
 
 test('settings registry puts feature toggles first, then other toggles alphabetically', () => {

src/config/settings/registry.ts

@@ -93,7 +93,12 @@ const JSON_OBJECT_FIELDS = new Set([
   'subtitleSidebar.css',
 ]);
 
-export const SECRET_PATHS = new Set(['ai.apiKey', 'jimaku.apiKey', 'anilist.accessToken']);
+export const SECRET_PATHS = new Set([
+  'ai.apiKey',
+  'jimaku.apiKey',
+  'tmdb.apiKey',
+  'anilist.accessToken',
+]);
 
 const COLOR_SUFFIXES = new Set(['Color', 'color', 'backgroundColor', 'singleColor']);
 const SUBTITLE_CSS_MANAGED_CONFIG_PATHS = new Set([
@@ -135,6 +140,7 @@ const SECTION_ORDER = new Map<string, number>(
     'Anki AI',
     'AnkiConnect Proxy',
     'Jimaku',
+    'TMDB',
     'Subtitle Sync',
     'MPV Keybindings',
     'Overlay Shortcuts',
@@ -327,6 +333,7 @@ function humanizePath(path: string): string {
     .replace(/\bmpv\b/i, 'mpv')
     .replace(/\byomitan\b/i, 'Yomitan')
     .replace(/\bjimaku\b/i, 'Jimaku')
+    .replace(/\btmdb\b/i, 'TMDB')
     .replace(/\banilist\b/i, 'AniList')
     .replace(/\banki\b/i, 'Anki');
   return spaced.charAt(0).toUpperCase() + spaced.slice(1);
@@ -442,7 +449,7 @@ function categoryAndSection(path: string): { category: ConfigSettingsCategory; s
   if (path.startsWith('mpv.') || path.startsWith('youtube.')) {
     return { category: 'behavior', section: topSection(path) };
   }
-  if (path.startsWith('jimaku.') || path.startsWith('tsukihime.')) {
+  if (path.startsWith('jimaku.') || path.startsWith('tsukihime.') || path.startsWith('tmdb.')) {
     return { category: 'integrations', section: topSection(path) };
   }
   if (path.startsWith('subsync.')) {
@@ -510,6 +517,7 @@ function topSection(path: string): string {
     subsync: 'Subtitle Sync',
     texthooker: 'Texthooker',
     tsukihime: 'TsukiHime',
+    tmdb: 'TMDB',
     updates: 'Updates',
     websocket: 'WebSocket server',
     yomitan: 'Yomitan',

src/core/services/__tests__/stats-server.test.ts

@@ -11,6 +11,7 @@ import {
   startStatsServerWithRuntime,
 } from '../stats-server.js';
 import type { ImmersionTrackerService } from '../immersion-tracker-service.js';
+import { INCOMPATIBLE_PROVIDER_MERGE_MESSAGE } from '../immersion-tracker/anime-merge.js';
 import {
   clearRetimedSecondarySubtitleCache,
   resolveRetimedSecondarySubtitleTextFromSidecar,
@@ -311,6 +312,7 @@ function createMockTracker(
     getKanjiOccurrences: async () => OCCURRENCES,
     getAnimeLibrary: async () => ANIME_LIBRARY,
     getAnimeDetail: async (animeId: number) => (animeId === 1 ? ANIME_DETAIL : null),
+    hasAnime: async (animeId: number) => animeId === 1,
     getAnimeEpisodes: async () => ANIME_EPISODES,
     getAnimeAnilistEntries: async () => [],
     getAnimeWords: async () => ANIME_WORDS,
@@ -444,6 +446,73 @@ async function withFakeAnkiConnect<T>(
 }
 
 describe('stats server API routes', () => {
+  it('rejects untrusted mutation requests before merging anime', async () => {
+    let merges = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        mergeAnime: async () => {
+          merges += 1;
+          return { survivingAnimeId: 1, mergedAnimeIds: [2], movedVideos: 1 };
+        },
+      }),
+    );
+    const rejectedHeaders: Record<string, string>[] = [
+      { Origin: 'https://attacker.example', 'Content-Type': 'text/plain' },
+      { Origin: 'https://attacker.example', 'Content-Type': 'application/json' },
+      { Origin: 'null', 'Content-Type': 'application/json' },
+      { Origin: 'http://localhost:4321', 'Content-Type': 'application/json' },
+      { Origin: 'http://localhost/', 'Content-Type': 'application/json' },
+      { 'Sec-Fetch-Site': 'cross-site', 'Content-Type': 'application/json' },
+      { Host: 'attacker.example', 'Content-Type': 'application/json' },
+    ];
+    for (const headers of rejectedHeaders) {
+      const response = await app.request('/api/stats/anime/1/merge', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ sourceAnimeIds: [2] }),
+      });
+      assert.equal(response.status, 403, JSON.stringify(headers));
+    }
+    assert.equal(merges, 0);
+    for (const origin of [undefined, 'http://localhost']) {
+      const headers = new Headers({ 'Content-Type': 'application/json; charset=utf-8' });
+      if (origin) headers.set('Origin', origin);
+      const response = await app.request('/api/stats/anime/1/merge', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ sourceAnimeIds: [2] }),
+      });
+      assert.equal(response.status, 200);
+    }
+    assert.equal(merges, 2);
+  });
+
+  it('requires JSON for mutation bodies and preserves bodyless deletion', async () => {
+    let deletions = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        deleteSession: async () => {
+          deletions += 1;
+        },
+      }),
+    );
+    const invalid = await app.request('/api/stats/sessions/1', {
+      method: 'DELETE',
+      body: '{}',
+    });
+    assert.equal(invalid.status, 415);
+    assert.equal(deletions, 0);
+    const valid = await app.request('/api/stats/sessions/1', { method: 'DELETE' });
+    assert.equal(valid.status, 200);
+    assert.equal(deletions, 1);
+    const rebound = await app.request('http://attacker.example/api/stats/sessions/1', {
+      method: 'DELETE',
+      headers: { Origin: 'http://attacker.example' },
+    });
+    assert.equal(rebound.status, 403);
+    assert.equal(deletions, 1);
+  });
+
   it('GET /api/stats/overview returns overview data', async () => {
     const app = createStatsApp(createMockTracker());
     const res = await app.request('/api/stats/overview');
@@ -1153,7 +1222,7 @@ describe('stats server API routes', () => {
       body: JSON.stringify({ dryRun: false, lookbackDays: null }),
     });
 
-    assert.equal(res.status, 415);
+    assert.equal(res.status, 403);
     assert.equal(cleanupCalls, 0);
   });
 
@@ -3662,6 +3731,25 @@ Aligned English subtitle
     assert.equal(res.status, 404);
   });
 
+  it('POST /api/stats/anime/:animeId/merge rejects mixed AniList and TMDB entries as 409', async () => {
+    const app = createStatsApp(
+      createMockTracker({
+        mergeAnime: async () => {
+          throw new Error(INCOMPATIBLE_PROVIDER_MERGE_MESSAGE);
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/7/merge', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"sourceAnimeIds":[8]}',
+    });
+
+    assert.equal(res.status, 409);
+    assert.deepEqual(await res.json(), { error: INCOMPATIBLE_PROVIDER_MERGE_MESSAGE });
+  });
+
   it('PATCH /api/stats/media/:videoId/anime reports an unknown target as 404', async () => {
     const app = createStatsApp(
       createMockTracker({
@@ -4128,4 +4216,108 @@ Aligned English subtitle
       });
     }
   });
+
+  it('enforces request safety through node:http without rejecting bodyless DELETEs', async () => {
+    await withTempDir(async (staticDir) => {
+      let deletions = 0;
+      const tracker = createMockTracker({
+        deleteSession: async () => {
+          deletions += 1;
+        },
+      });
+      const listener = http.createServer();
+      const server = await startNodeHttpServer(
+        createStatsApp(tracker),
+        { port: 0, staticDir, tracker },
+        (handler) => {
+          listener.on('request', handler);
+          return listener;
+        },
+      );
+      try {
+        const address = listener.address();
+        assert.ok(address && typeof address !== 'string');
+        const origin = `http://127.0.0.1:${address.port}`;
+        const url = `${origin}/api/stats/sessions/1`;
+        for (const headers of [undefined, { 'Content-Length': '0' }]) {
+          const response = await fetch(url, { method: 'DELETE', headers });
+          assert.equal(response.status, 200);
+          await response.arrayBuffer();
+        }
+        assert.equal(deletions, 2);
+        for (const headers of [
+          new Headers({ Origin: 'https://attacker.example' }),
+          new Headers({ Origin: 'null' }),
+          new Headers({ Host: 'attacker.example' }),
+          new Headers({ 'Sec-Fetch-Site': 'same-site' }),
+        ]) {
+          const response = await fetch(url, { method: 'DELETE', headers });
+          assert.equal(response.status, 403, JSON.stringify(headers));
+          await response.arrayBuffer();
+        }
+        const invalid = await fetch(url, { method: 'DELETE', body: '{}' });
+        assert.equal(invalid.status, 415);
+        await invalid.arrayBuffer();
+        assert.equal(deletions, 2);
+        const valid = await fetch(url, {
+          method: 'DELETE',
+          headers: { Origin: origin, 'Content-Type': 'application/json' },
+          body: '{}',
+        });
+        assert.equal(valid.status, 200);
+        await valid.arrayBuffer();
+        assert.equal(deletions, 3);
+      } finally {
+        await server.close();
+      }
+    });
+  });
+});
+
+it('TMDB reassignment returns 404 for a missing library entry before fetching details', async () => {
+  const assignments: number[] = [];
+  let fetches = 0;
+  const app = createStatsApp(
+    createMockTracker({
+      reassignAnimeTmdb: async (animeId: number) => {
+        assignments.push(animeId);
+        return { animeId, mergedAnimeIds: [] };
+      },
+    }),
+    {
+      tmdbClient: {
+        search: async () => [],
+        getDetails: async () => {
+          fetches += 1;
+          return {
+            tmdbId: 12,
+            tmdbType: 'tv',
+            titleEnglish: 'Drama',
+            titleNative: null,
+            description: null,
+            posterUrl: null,
+            episodesTotal: 10,
+            year: null,
+            originalLanguage: 'ja',
+            isAnimation: false,
+            allTitles: ['Drama'],
+          };
+        },
+      },
+    },
+  );
+  const request = (animeId: number) =>
+    app.request(`/api/stats/anime/${animeId}/tmdb`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ tmdbId: 12, tmdbType: 'tv' }),
+    });
+  assert.equal((await request(99999)).status, 404);
+  assert.equal(fetches, 0);
+  assert.deepEqual(assignments, []);
+  const response = await request(1);
+  assert.equal(response.status, 200);
+  assert.deepEqual(await response.json(), { ok: true });
+  assert.equal(fetches, 1);
+  assert.deepEqual(assignments, [1]);
 });

src/core/services/anilist/cover-art-fetcher.test.ts

@@ -540,3 +540,200 @@ test('fetchIfMissing re-resolves an unresolved season once AniList publishes the
     cleanupDbPath(dbPath);
   }
 });
+
+for (const linkedToAnilist of [false, true]) {
+  test(`TMDB fallback preserves AniList identity when linked=${linkedToAnilist}`, async () => {
+    const dbPath = makeDbPath();
+    const db = new Database(dbPath);
+    ensureSchema(db);
+    const videoId = getOrCreateVideoRecord(db, 'local:/tmp/hanzawa-01.mkv', {
+      canonicalTitle: 'Hanzawa Naoki - 01.mkv',
+      sourcePath: '/tmp/hanzawa-01.mkv',
+      sourceUrl: null,
+      sourceType: SOURCE_TYPE_LOCAL,
+    });
+    const animeId = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Hanzawa Naoki',
+      canonicalTitle: 'Hanzawa Naoki',
+      anilistId: linkedToAnilist ? 42 : null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+    linkVideoToAnimeRecord(db, videoId, {
+      animeId,
+      parsedBasename: null,
+      parsedTitle: 'Hanzawa Naoki',
+      parsedSeason: null,
+      parsedEpisode: 1,
+      parserSource: 'fallback',
+      parserConfidence: 1,
+      parseMetadataJson: null,
+    });
+
+    const fetchCalls: string[] = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      fetchCalls.push(url);
+      if (url.startsWith('https://graphql.anilist.co')) {
+        return createJsonResponse({ data: { Page: { media: [] } } });
+      }
+      assert.equal(url, 'https://image.tmdb.org/t/p/w500/hanzawa.jpg');
+      return new Response(new Uint8Array([5, 6, 7]), {
+        status: 200,
+        headers: { 'Content-Type': 'image/jpeg' },
+      });
+    }) as typeof fetch;
+
+    const resolvedTitles: string[] = [];
+    try {
+      const fetcher = createCoverArtFetcher(
+        { acquire: async () => {}, recordResponse: () => {} },
+        console,
+        {
+          runGuessit: async () => {
+            throw new Error('guessit unavailable');
+          },
+          liveAction: {
+            async resolveByTitle(title) {
+              resolvedTitles.push(title);
+              if (title !== 'Hanzawa Naoki') return null;
+              return {
+                tmdbId: 61222,
+                tmdbType: 'tv',
+                titleEnglish: 'Hanzawa Naoki',
+                titleNative: '半沢直樹',
+                description: 'A banker fights back.',
+                posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+                episodesTotal: 10,
+                year: 2013,
+                originalLanguage: 'ja',
+                isAnimation: false,
+                allTitles: ['Hanzawa Naoki', '半沢直樹'],
+              };
+            },
+            async resolveById() {
+              return null;
+            },
+          },
+        },
+      );
+
+      const fetched = await fetcher.fetchIfMissing(db, videoId, 'Hanzawa Naoki - 01.mkv');
+      const stored = getCoverArt(db, videoId);
+      const anime = db
+        .prepare(
+          'SELECT media_kind AS mediaKind, tmdb_id AS tmdbId, description FROM imm_anime WHERE anime_id = ?',
+        )
+        .get(animeId) as { mediaKind: string; tmdbId: number | null; description: string | null };
+
+      if (linkedToAnilist) {
+        assert.equal(fetched, false);
+        assert.equal(stored?.coverBlob, null);
+        assert.equal(stored?.coverUrl, null);
+        assert.equal(anime.mediaKind, 'anime');
+        assert.equal(anime.tmdbId, null);
+        assert.deepEqual(resolvedTitles, []);
+        const requestCount = fetchCalls.length;
+        assert.equal(await fetcher.fetchIfMissing(db, videoId, 'Hanzawa Naoki - 01.mkv'), false);
+        assert.equal(fetchCalls.length, requestCount);
+        return;
+      }
+      assert.equal(fetched, true);
+      // The raw fallback-parser title is tried first, then the tag-stripped one.
+      assert.deepEqual(resolvedTitles, ['Hanzawa Naoki - 01', 'Hanzawa Naoki']);
+      assert.equal(stored?.anilistId, null);
+      assert.equal(stored?.coverUrl, 'https://image.tmdb.org/t/p/w500/hanzawa.jpg');
+      assert.equal(Buffer.from(stored?.coverBlob ?? []).toString('hex'), '050607');
+      assert.equal(anime.mediaKind, 'live_action');
+      assert.equal(anime.tmdbId, 61222);
+      assert.equal(anime.description, 'A banker fights back.');
+      assert.ok(fetchCalls.some((url) => url.startsWith('https://graphql.anilist.co')));
+    } finally {
+      globalThis.fetch = originalFetch;
+      db.close();
+      cleanupDbPath(dbPath);
+    }
+  });
+}
+
+test('fetchIfMissing skips AniList for an entry already linked to TMDB', async () => {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  ensureSchema(db);
+  const videoId = getOrCreateVideoRecord(db, 'local:/tmp/hanzawa-02.mkv', {
+    canonicalTitle: 'Hanzawa Naoki - 02.mkv',
+    sourcePath: '/tmp/hanzawa-02.mkv',
+    sourceUrl: null,
+    sourceType: SOURCE_TYPE_LOCAL,
+  });
+  const animeId = getOrCreateAnimeRecord(db, {
+    parsedTitle: 'Hanzawa Naoki',
+    canonicalTitle: 'Hanzawa Naoki',
+    anilistId: null,
+    titleRomaji: null,
+    titleEnglish: null,
+    titleNative: null,
+    metadataJson: null,
+  });
+  linkVideoToAnimeRecord(db, videoId, {
+    animeId,
+    parsedBasename: null,
+    parsedTitle: 'Hanzawa Naoki',
+    parsedSeason: null,
+    parsedEpisode: 2,
+    parserSource: 'fallback',
+    parserConfidence: 1,
+    parseMetadataJson: null,
+  });
+  db.prepare(
+    "UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = 61222, tmdb_type = 'tv' WHERE anime_id = ?",
+  ).run(animeId);
+
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    assert.equal(String(input), 'https://image.tmdb.org/t/p/w500/hanzawa.jpg');
+    return new Response(new Uint8Array([1]), { status: 200 });
+  }) as typeof fetch;
+
+  const byIdCalls: Array<[string, number]> = [];
+  try {
+    const fetcher = createCoverArtFetcher(
+      { acquire: async () => {}, recordResponse: () => {} },
+      console,
+      {
+        liveAction: {
+          async resolveByTitle() {
+            throw new Error('title search must not run for a linked entry');
+          },
+          async resolveById(tmdbType, tmdbId) {
+            byIdCalls.push([tmdbType, tmdbId]);
+            return {
+              tmdbId,
+              tmdbType,
+              titleEnglish: 'Hanzawa Naoki',
+              titleNative: null,
+              description: null,
+              posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+              episodesTotal: 10,
+              year: null,
+              originalLanguage: 'ja',
+              isAnimation: false,
+              allTitles: [],
+            };
+          },
+        },
+      },
+    );
+
+    assert.equal(await fetcher.fetchIfMissing(db, videoId, 'Hanzawa Naoki - 02.mkv'), true);
+    assert.deepEqual(byIdCalls, [['tv', 61222]]);
+    assert.equal(getCoverArt(db, videoId)?.coverBlob?.length, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});

src/core/services/anilist/cover-art-fetcher.ts

@@ -16,6 +16,9 @@ import {
   type AnilistQueryExecutor,
   type AnilistSeasonResolution,
 } from './season-resolver';
+import { getVideoTmdbLink, linkAnimeToTmdbTitle } from '../immersion-tracker/live-action-link';
+import type { LiveActionMetadataResolver } from '../tmdb/live-action-resolver';
+import type { TmdbTitleDetails } from '../tmdb/tmdb-client';
 
 const ANILIST_GRAPHQL_URL = 'https://graphql.anilist.co';
 const NO_MATCH_RETRY_MS = 5 * 60 * 1000;
@@ -39,6 +42,8 @@ interface CoverArtCandidate {
 
 interface CoverArtFetcherOptions {
   runGuessit?: GuessAnilistMediaInfoDeps['runGuessit'];
+  /** Live-action fallback consulted when AniList has no match for a title. */
+  liveAction?: LiveActionMetadataResolver;
 }
 
 export function stripFilenameTags(raw: string): string {
@@ -152,6 +157,60 @@ export function createCoverArtFetcher(
     return true;
   };
 
+  const cacheNoMatch = (db: DatabaseSync, videoId: number): void => {
+    upsertCoverArt(db, videoId, {
+      anilistId: null,
+      coverUrl: null,
+      coverBlob: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      episodesTotal: null,
+    });
+  };
+
+  // Links the video's library entry to the TMDB title and stores its poster.
+  const storeLiveActionArt = async (
+    db: DatabaseSync,
+    videoId: number,
+    details: TmdbTitleDetails,
+  ): Promise<boolean> => {
+    const row = db
+      .prepare(
+        `SELECT v.anime_id AS animeId, a.anilist_id AS anilistId
+                FROM imm_videos v LEFT JOIN imm_anime a ON a.anime_id = v.anime_id
+                WHERE v.video_id = ?`,
+      )
+      .get(videoId) as { animeId: number | null; anilistId: number | null } | undefined;
+    if (row?.anilistId != null) return false;
+    if (row?.animeId) {
+      const link = linkAnimeToTmdbTitle(db, row.animeId, details, { mode: 'auto' });
+      if (link.mergedAnimeIds.length > 0) {
+        logger.info(
+          'cover-art: folded library entries %s into %d (same TMDB title)',
+          link.mergedAnimeIds.join(','),
+          link.animeId,
+        );
+      }
+    }
+    const coverBlob = details.posterUrl ? await downloadImage(details.posterUrl) : null;
+    upsertCoverArt(db, videoId, {
+      anilistId: null,
+      coverUrl: details.posterUrl,
+      coverBlob,
+      titleRomaji: null,
+      titleEnglish: details.titleEnglish,
+      episodesTotal: details.episodesTotal,
+    });
+    logger.info(
+      'cover-art: linked videoId=%d to TMDB %s/%d "%s"',
+      videoId,
+      details.tmdbType,
+      details.tmdbId,
+      details.titleEnglish ?? details.titleNative ?? '',
+    );
+    return coverBlob !== null;
+  };
+
   const resolveCanonicalTitle = (
     db: DatabaseSync,
     videoId: number,
@@ -197,7 +256,7 @@ export function createCoverArtFetcher(
           `
         SELECT 1 FROM imm_videos v
         JOIN imm_anime a ON a.anime_id = v.anime_id
-        WHERE v.video_id = ? AND a.media_kind != 'anime'
+        WHERE v.video_id = ? AND a.media_kind = 'youtube'
       `,
         )
         .get(videoId);
@@ -235,18 +294,31 @@ export function createCoverArtFetcher(
         return false;
       }
 
+      // A live-action entry already knows its TMDB title; AniList has nothing
+      // to add and would only produce a spurious anime match.
+      const hasAnilistLink = Boolean(
+        db
+          .prepare(
+            `SELECT 1 FROM imm_videos v JOIN imm_anime a ON a.anime_id = v.anime_id
+         WHERE v.video_id = ? AND a.anilist_id IS NOT NULL`,
+          )
+          .get(videoId),
+      );
+      const tmdbLink = getVideoTmdbLink(db, videoId);
+      if (tmdbLink && !hasAnilistLink) {
+        const details = await options.liveAction?.resolveById(tmdbLink.tmdbType, tmdbLink.tmdbId);
+        if (details) {
+          return storeLiveActionArt(db, videoId, details);
+        }
+        cacheNoMatch(db, videoId);
+        return false;
+      }
+
       const effectiveTitle = resolveCanonicalTitle(db, videoId, canonicalTitle);
       const cleaned = stripFilenameTags(effectiveTitle);
       if (!cleaned) {
         logger.warn('cover-art: empty title after stripping tags for videoId=%d', videoId);
-        upsertCoverArt(db, videoId, {
+        cacheNoMatch(db, videoId);
-          anilistId: null,
-          coverUrl: null,
-          coverBlob: null,
-          titleRomaji: null,
-          titleEnglish: null,
-          episodesTotal: null,
-        });
         return false;
       }
 
@@ -304,15 +376,16 @@ export function createCoverArtFetcher(
 
       const selected = resolution?.media ?? null;
       if (!selected) {
-        logger.info('cover-art: no Anilist results for "%s", caching no-match', searchBase);
+        if (options.liveAction && !hasAnilistLink) {
-        upsertCoverArt(db, videoId, {
+          for (const searchTitle of searchTitles) {
-          anilistId: null,
+            const details = await options.liveAction.resolveByTitle(searchTitle);
-          coverUrl: null,
+            if (details) {
-          coverBlob: null,
+              return storeLiveActionArt(db, videoId, details);
-          titleRomaji: null,
+            }
-          titleEnglish: null,
+          }
-          episodesTotal: null,
+        }
-        });
+        logger.info('cover-art: no Anilist or TMDB results for "%s", caching no-match', searchBase);
+        cacheNoMatch(db, videoId);
         return false;
       }
 

src/core/services/immersion-tracker-service.test.ts

@@ -5395,3 +5395,91 @@ test('getVocabularySummary keeps different known-word snapshots independent', as
     cleanupDbPath(dbPath);
   }
 });
+
+for (const provider of ['anilist', 'tmdb'] as const) {
+  test(`${provider} reassignment keeps metadata and artwork on download failure, then replaces or clears both`, async () => {
+    const dbPath = makeDbPath();
+    const originalFetch = globalThis.fetch;
+    let tracker: ImmersionTrackerService | null = null;
+    try {
+      const Ctor = await loadTrackerCtor();
+      tracker = new Ctor({ dbPath });
+      const { db } = tracker as unknown as { db: DatabaseSync };
+      db.exec(`
+        INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES (1, 'show', 'Show', 1000, 1000);
+        INSERT INTO imm_videos(video_id, video_key, canonical_title, source_type, anime_id, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES (1, 'local:/tmp/show.mkv', 'Show', 1, 1, 0, 1000, 1000);
+      `);
+      const tmdb = {
+        tmdbId: 12,
+        tmdbType: 'tv' as const,
+        titleEnglish: 'Drama',
+        titleNative: null,
+        description: 'New description',
+        episodesTotal: 10,
+      };
+      globalThis.fetch = async () => new Response(new Uint8Array([1, 2, 3]));
+      if (provider === 'anilist') {
+        await tracker.reassignAnimeTmdb(1, { ...tmdb, posterUrl: 'https://images.test/old' });
+      } else {
+        await tracker.reassignAnimeAnilist(1, {
+          anilistId: 42,
+          coverUrl: 'https://images.test/old',
+        });
+      }
+      assert.equal(await tracker.hasAnime(1), true);
+      assert.equal(await tracker.hasAnime(999), false);
+      const readMetadata = () =>
+        db.prepare('SELECT * FROM imm_anime WHERE anime_id = 1').get() as {
+          media_kind: string;
+          anilist_id: number | null;
+          tmdb_id: number | null;
+        };
+      const before = readMetadata();
+      const oldArt = await tracker.getAnimeCoverArt(1);
+      const snapshot = (value: unknown) =>
+        JSON.stringify(value, (key, item: unknown) => (key === '_metadata' ? undefined : item));
+      const reassign = (url: string | null) =>
+        provider === 'anilist'
+          ? tracker!.reassignAnimeAnilist(1, { anilistId: 99, coverUrl: url })
+          : tracker!.reassignAnimeTmdb(1, { ...tmdb, posterUrl: url });
+      for (const failure of ['http', 'network']) {
+        globalThis.fetch = async () => {
+          if (failure === 'network') throw new Error('offline');
+          return new Response(null, { status: 503 });
+        };
+        await assert.rejects(reassign('https://images.test/new'));
+        assert.equal(snapshot(readMetadata()), snapshot(before));
+        assert.equal(snapshot(await tracker.getAnimeCoverArt(1)), snapshot(oldArt));
+      }
+      globalThis.fetch = async () => new Response(new Uint8Array([9, 8, 7]));
+      if (provider === 'anilist') {
+        // Retained sessions without lifetime summaries exercise the bootstrap
+        // inside the reassignment transaction.
+        db.exec(`INSERT INTO imm_sessions(session_uuid, video_id, started_at_ms, ended_at_ms,
+          status, active_watched_ms, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES ('retained-session', 1, '1000', '2000', 2, 1000, 1000, 2000)`);
+      }
+      await reassign('https://images.test/new');
+      const detail = readMetadata();
+      assert.equal(detail.media_kind, provider === 'anilist' ? 'anime' : 'live_action');
+      assert.equal(detail.anilist_id, provider === 'anilist' ? 99 : null);
+      assert.equal(detail.tmdb_id, provider === 'tmdb' ? 12 : null);
+      if (provider === 'anilist') {
+        assert.equal((await tracker.getAnimeDetail(1))?.totalActiveMs, 1000);
+      }
+      assert.deepEqual(
+        new Uint8Array((await tracker.getAnimeCoverArt(1))!.coverBlob!),
+        new Uint8Array([9, 8, 7]),
+      );
+      await reassign(null);
+      assert.equal(await tracker.getAnimeCoverArt(1), null);
+      assert.equal(readMetadata().media_kind, detail.media_kind);
+    } finally {
+      globalThis.fetch = originalFetch;
+      tracker?.destroy();
+      cleanupDbPath(dbPath);
+    }
+  });
+}

src/core/services/immersion-tracker-service.ts

@@ -33,6 +33,7 @@ import {
   applySessionLifetimeSummary,
   reconcileStaleActiveSessions,
   rebuildLifetimeSummaries as rebuildLifetimeSummaryTables,
+  rebuildLifetimeSummariesInTransaction,
   recomputeLifetimeAnimeFromMedia,
   recomputeLifetimeGlobalFromSummaries,
   repairLifetimeSummariesFromMedia,
@@ -90,6 +91,7 @@ import {
 } from './immersion-tracker/query-library';
 import {
   cleanupVocabularyStats,
+  clearAnimeCoverArt,
   getVideoDurationMs,
   markVideoWatched,
   upsertCoverArt,
@@ -115,7 +117,7 @@ import {
   dismissAnimeMergeRecommendation,
   getAnimeMergeRecommendations,
   repairLegacySeasonlessAnimeRows,
-  resolveAnimeAnilistConflict,
+  resolveAnimeAnilistConflictInTransaction,
   type AnimeMergeRecommendation,
 } from './immersion-tracker/anime-season-repair';
 import {
@@ -124,6 +126,11 @@ import {
   type AnimeMergeSummary,
   type VideoMoveSummary,
 } from './immersion-tracker/anime-merge';
+import {
+  linkAnimeToTmdbTitleInTransaction,
+  type LiveActionLinkResult,
+  type LiveActionTitleInput,
+} from './immersion-tracker/live-action-link';
 import {
   buildVideoKey,
   deriveCanonicalTitle,
@@ -819,6 +826,10 @@ export class ImmersionTrackerService {
     return getAnimeDetail(this.db, animeId);
   }
 
+  async hasAnime(animeId: number): Promise<boolean> {
+    return Boolean(this.db.prepare('SELECT 1 FROM imm_anime WHERE anime_id = ?').get(animeId));
+  }
+
   async getAnimeEpisodes(animeId: number): Promise<AnimeEpisodeRow[]> {
     return getAnimeEpisodes(this.db, animeId);
   }
@@ -1017,19 +1028,31 @@ export class ImmersionTrackerService {
       coverUrl?: string | null;
     },
   ): Promise<void> {
+    const coverBlob = await this.downloadReplacementCover(info.coverUrl);
     this.requireWriteQueueDrained('reassigning an AniList entry');
-    // The user is acting on this entry, so it is the one that survives when
+    this.db.exec('BEGIN IMMEDIATE');
-    // another row already claims the same AniList id.
+    try {
-    const repair = resolveAnimeAnilistConflict(this.db, animeId, info.anilistId, {
+      this.db
-      survivor: 'target',
+        .prepare('UPDATE imm_anime SET tmdb_id = NULL, tmdb_type = NULL WHERE anime_id = ?')
-      matchConfidence: 'manual',
+        .run(animeId);
-    });
+      // The user is acting on this entry, so it is the one that survives when
-    if (repair.anilistAssignmentBlocked) return;
+      // another row already claims the same AniList id.
-    this.db
+      const repair = resolveAnimeAnilistConflictInTransaction(this.db, animeId, info.anilistId, {
-      .prepare(
+        survivor: 'target',
-        `
+        matchConfidence: 'manual',
+      });
+      if (repair.anilistAssignmentBlocked) {
+        this.db.exec('ROLLBACK');
+        return;
+      }
+      this.db
+        .prepare(
+          `
       UPDATE imm_anime
       SET anilist_id = ?,
+          media_kind = 'anime',
+          tmdb_id = NULL,
+          tmdb_type = NULL,
           title_romaji = COALESCE(?, title_romaji),
           title_english = COALESCE(?, title_english),
           title_native = COALESCE(?, title_native),
@@ -1038,46 +1061,32 @@ export class ImmersionTrackerService {
           LAST_UPDATE_DATE = ?
       WHERE anime_id = ?
     `,
-      )
+        )
-      .run(
+        .run(
-        info.anilistId,
+          info.anilistId,
-        info.titleRomaji ?? null,
+          info.titleRomaji ?? null,
-        info.titleEnglish ?? null,
+          info.titleEnglish ?? null,
-        info.titleNative ?? null,
+          info.titleNative ?? null,
-        info.episodesTotal ?? null,
+          info.episodesTotal ?? null,
-        info.description !== undefined ? 1 : 0,
+          info.description !== undefined ? 1 : 0,
-        info.description ?? null,
+          info.description ?? null,
-        nowMs(),
+          nowMs(),
-        animeId,
+          animeId,
-      );
+        );
-    // Empty lifetime tables still need the retained-session bootstrap. Once a
+      // Empty lifetime tables still need the retained-session bootstrap. Once a
-    // media ledger exists, only the redistributed and explicitly edited anime
+      // media ledger exists, only the redistributed and explicitly edited anime
-    // can have changed.
+      // can have changed.
-    if (shouldBackfillLifetimeSummaries(this.db)) {
+      if (shouldBackfillLifetimeSummaries(this.db)) {
-      repairLifetimeSummariesFromMedia(this.db);
+        rebuildLifetimeSummariesInTransaction(this.db);
-    } else {
+      } else {
-      const affectedAnimeIds = new Set(repair.affectedAnimeIds);
+        const affectedAnimeIds = new Set(repair.affectedAnimeIds);
-      affectedAnimeIds.add(animeId);
+        affectedAnimeIds.add(animeId);
-      recomputeLifetimeAnimeFromMedia(this.db, [...affectedAnimeIds]);
+        recomputeLifetimeAnimeFromMedia(this.db, [...affectedAnimeIds]);
-      recomputeLifetimeGlobalFromSummaries(this.db);
+        recomputeLifetimeGlobalFromSummaries(this.db);
-    }
-
-    // Update cover art for all videos in this anime
-    if (info.coverUrl) {
-      const videos = this.db
-        .prepare('SELECT video_id FROM imm_videos WHERE anime_id = ?')
-        .all(animeId) as Array<{ video_id: number }>;
-      let coverBlob: Buffer | null = null;
-      try {
-        const res = await fetch(info.coverUrl);
-        if (res.ok) {
-          coverBlob = Buffer.from(await res.arrayBuffer());
-        }
-      } catch {
-        /* ignore */
       }
-      for (const v of videos) {
+
-        upsertCoverArt(this.db, v.video_id, {
+      if (info.coverUrl) {
+        this.applyCoverArtToAnimeVideos(animeId, {
           anilistId: info.anilistId,
           coverUrl: info.coverUrl,
           coverBlob,
@@ -1085,7 +1094,85 @@ export class ImmersionTrackerService {
           titleEnglish: info.titleEnglish ?? null,
           episodesTotal: info.episodesTotal ?? null,
         });
+      } else {
+        clearAnimeCoverArt(this.db, animeId);
       }
+      this.db.exec('COMMIT');
+    } catch (error) {
+      this.db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  /**
+   * Link a library entry to a TMDB title chosen in the dashboard. Every other
+   * entry pointing at the same title is folded into this one, and its poster
+   * replaces the art of every episode.
+   */
+  async reassignAnimeTmdb(
+    animeId: number,
+    details: LiveActionTitleInput & { posterUrl: string | null },
+  ): Promise<LiveActionLinkResult> {
+    const coverBlob = await this.downloadReplacementCover(details.posterUrl);
+    this.requireWriteQueueDrained('linking a TMDB title');
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const result = linkAnimeToTmdbTitleInTransaction(this.db, animeId, details, {
+        mode: 'manual',
+      });
+      if (details.posterUrl) {
+        this.applyCoverArtToAnimeVideos(result.animeId, {
+          anilistId: null,
+          coverUrl: details.posterUrl,
+          coverBlob,
+          titleRomaji: null,
+          titleEnglish: details.titleEnglish,
+          episodesTotal: details.episodesTotal,
+        });
+      } else {
+        // The user chose this title deliberately, so art from the previous link
+        // must not keep standing in for it.
+        clearAnimeCoverArt(this.db, result.animeId);
+      }
+      this.db.exec('COMMIT');
+      return result;
+    } catch (error) {
+      this.db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  private async downloadReplacementCover(url: string | null | undefined): Promise<Buffer | null> {
+    if (!url) return null;
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Cover download failed: ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  /** Stores the downloaded replacement against every episode of the entry. */
+  private applyCoverArtToAnimeVideos(
+    animeId: number,
+    art: {
+      anilistId: number | null;
+      coverUrl: string;
+      coverBlob: Buffer | null;
+      titleRomaji: string | null;
+      titleEnglish: string | null;
+      episodesTotal: number | null;
+    },
+  ): void {
+    const videos = this.db
+      .prepare('SELECT video_id FROM imm_videos WHERE anime_id = ?')
+      .all(animeId) as Array<{ video_id: number }>;
+    for (const v of videos) {
+      upsertCoverArt(this.db, v.video_id, {
+        anilistId: art.anilistId,
+        coverUrl: art.coverUrl,
+        coverBlob: art.coverBlob,
+        titleRomaji: art.titleRomaji,
+        titleEnglish: art.titleEnglish,
+        episodesTotal: art.episodesTotal,
+      });
     }
   }
 

src/core/services/immersion-tracker/__tests__/live-action-link.test.ts

@@ -0,0 +1,309 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { Database } from '../sqlite.js';
+import type { DatabaseSync } from '../sqlite.js';
+import { applyPragmas, ensureSchema, getOrCreateAnimeRecord } from '../storage.js';
+import { repairLegacySeasonlessAnimeRows } from '../anime-season-repair.js';
+import { mergeAnimeRecords, mergeAnimeRecordsInTransaction } from '../anime-merge.js';
+import { getVideoTmdbLink, linkAnimeToTmdbTitle } from '../live-action-link.js';
+import { getAnimeCoverArt, getCoverArt } from '../query-library.js';
+import { clearAnimeCoverArt, upsertCoverArt } from '../query-maintenance.js';
+
+const BASE_MS = 1_700_000_000_000;
+
+function withDb(work: (db: DatabaseSync) => void): void {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-live-action-link-'));
+  const db = new Database(path.join(dir, 'immersion.sqlite'));
+  try {
+    applyPragmas(db);
+    ensureSchema(db);
+    work(db);
+  } finally {
+    db.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function insertAnime(
+  db: DatabaseSync,
+  animeId: number,
+  title: string,
+  anilistId: number | null = null,
+) {
+  db.prepare(
+    `INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, anilist_id, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+  ).run(animeId, title.toLowerCase(), title, anilistId, BASE_MS, BASE_MS);
+}
+
+function insertEpisode(db: DatabaseSync, videoId: number, animeId: number, season: number | null) {
+  db.prepare(
+    `INSERT INTO imm_videos(video_id, video_key, anime_id, canonical_title, source_type, parsed_title, parsed_season, parsed_episode, watched, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?, 1, 'Hanzawa Naoki', ?, ?, 1, 1440000, ?, ?)`,
+  ).run(
+    videoId,
+    `local:/tmp/${videoId}.mkv`,
+    animeId,
+    `Ep ${videoId}`,
+    season,
+    videoId,
+    BASE_MS,
+    BASE_MS,
+  );
+  db.prepare(
+    `INSERT INTO imm_lifetime_media(video_id, total_sessions, total_active_ms, total_cards, completed, first_watched_ms, last_watched_ms, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, 1, 1000, 0, 1, ?, ?, ?, ?)`,
+  ).run(videoId, String(BASE_MS), String(BASE_MS + 1000), BASE_MS, BASE_MS);
+}
+
+interface AnimeRowView {
+  mediaKind: string;
+  tmdbId: number | null;
+  tmdbType: string | null;
+  anilistId: number | null;
+  titleEnglish: string | null;
+  titleNative: string | null;
+  description: string | null;
+}
+
+// Copies the selected columns so the driver's row metadata does not leak into
+// deep-equality assertions.
+function animeRow(db: DatabaseSync, animeId: number): AnimeRowView | undefined {
+  const row = db
+    .prepare(
+      `SELECT media_kind AS mediaKind, tmdb_id AS tmdbId, tmdb_type AS tmdbType, anilist_id AS anilistId,
+              title_english AS titleEnglish, title_native AS titleNative, description
+       FROM imm_anime WHERE anime_id = ?`,
+    )
+    .get(animeId) as AnimeRowView | undefined;
+  if (!row) return undefined;
+  const { mediaKind, tmdbId, tmdbType, anilistId, titleEnglish, titleNative, description } = row;
+  return { mediaKind, tmdbId, tmdbType, anilistId, titleEnglish, titleNative, description };
+}
+
+function animeCount(db: DatabaseSync): number {
+  return (db.prepare('SELECT COUNT(*) AS n FROM imm_anime').get() as { n: number }).n;
+}
+
+function videoOwner(db: DatabaseSync, videoId: number): number | null {
+  return (
+    db.prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = ?').get(videoId) as {
+      animeId: number | null;
+    }
+  ).animeId;
+}
+
+const HANZAWA = {
+  tmdbId: 61222,
+  tmdbType: 'tv' as const,
+  titleEnglish: 'Hanzawa Naoki',
+  titleNative: '半沢直樹',
+  description: 'A banker fights back.',
+  episodesTotal: 10,
+};
+
+test('a manual link overwrites metadata, drops the AniList link, and folds other holders in', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki', 4242);
+    insertAnime(db, 2, 'Hanzawa Naoki Season 2');
+    insertEpisode(db, 1, 1, 1);
+    insertEpisode(db, 2, 2, 2);
+    db.prepare(
+      `UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = ?, tmdb_type = 'tv', description = 'old' WHERE anime_id = 2`,
+    ).run(HANZAWA.tmdbId);
+
+    const result = linkAnimeToTmdbTitle(db, 1, HANZAWA, { mode: 'manual' });
+
+    assert.deepEqual(result, { animeId: 1, mergedAnimeIds: [2] });
+    assert.deepEqual(animeRow(db, 1), {
+      mediaKind: 'live_action',
+      tmdbId: 61222,
+      tmdbType: 'tv',
+      anilistId: null,
+      titleEnglish: 'Hanzawa Naoki',
+      titleNative: '半沢直樹',
+      description: 'A banker fights back.',
+    });
+    assert.equal(animeRow(db, 2), undefined);
+    assert.equal(animeCount(db), 1);
+    assert.equal(videoOwner(db, 2), 1);
+    assert.deepEqual(getVideoTmdbLink(db, 2), { animeId: 1, tmdbId: 61222, tmdbType: 'tv' });
+  });
+});
+
+test('an automatic link joins the entry that already owns the title and only fills gaps', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki');
+    insertEpisode(db, 1, 1, 1);
+    linkAnimeToTmdbTitle(db, 1, { ...HANZAWA, description: 'kept' }, { mode: 'manual' });
+    const newcomer = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Hanzawa Naoki',
+      canonicalTitle: 'Hanzawa Naoki',
+      seasonScope: 2,
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+    insertEpisode(db, 2, newcomer, 2);
+
+    const result = linkAnimeToTmdbTitle(db, newcomer, HANZAWA, { mode: 'auto' });
+
+    assert.deepEqual(result, { animeId: 1, mergedAnimeIds: [newcomer] });
+    assert.equal(animeRow(db, 1)?.description, 'kept');
+    assert.equal(animeCount(db), 1);
+    assert.equal(videoOwner(db, 2), 1);
+    // The merged-away season title is remembered, so the next episode of that
+    // season lands on the survivor without a detour through a new row.
+    const again = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Hanzawa Naoki',
+      canonicalTitle: 'Hanzawa Naoki',
+      seasonScope: 2,
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+    assert.equal(again, 1);
+  });
+});
+
+test('startup season repair leaves multi-season live-action entries alone', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki');
+    insertEpisode(db, 1, 1, 1);
+    insertEpisode(db, 2, 1, 2);
+    linkAnimeToTmdbTitle(db, 1, HANZAWA, { mode: 'manual' });
+
+    repairLegacySeasonlessAnimeRows(db);
+
+    assert.equal(animeCount(db), 1);
+    assert.equal(videoOwner(db, 1), 1);
+    assert.equal(videoOwner(db, 2), 1);
+    assert.equal(getVideoTmdbLink(db, 2)?.animeId, 1);
+  });
+});
+
+test('getVideoTmdbLink is null for anime entries and unlinked videos', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Some Anime', 77);
+    insertEpisode(db, 1, 1, 1);
+    assert.equal(getVideoTmdbLink(db, 1), null);
+    assert.equal(getVideoTmdbLink(db, 99), null);
+  });
+});
+
+test('clearAnimeCoverArt drops every episode cover of the entry and its orphaned blob', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki');
+    insertAnime(db, 2, 'Other Show');
+    insertEpisode(db, 1, 1, 1);
+    insertEpisode(db, 2, 1, 1);
+    insertEpisode(db, 3, 2, 1);
+    const shared = Buffer.from([1, 2, 3]);
+    for (const videoId of [1, 2]) {
+      upsertCoverArt(db, videoId, {
+        anilistId: 4242,
+        coverUrl: 'https://images.test/a.jpg',
+        coverBlob: shared,
+        titleRomaji: null,
+        titleEnglish: null,
+        episodesTotal: null,
+      });
+    }
+    upsertCoverArt(db, 3, {
+      anilistId: 99,
+      coverUrl: 'https://images.test/b.jpg',
+      coverBlob: Buffer.from([9]),
+      titleRomaji: null,
+      titleEnglish: null,
+      episodesTotal: null,
+    });
+
+    clearAnimeCoverArt(db, 1);
+
+    assert.equal(getAnimeCoverArt(db, 1), null);
+    assert.equal(getCoverArt(db, 3)?.coverBlob?.length, 1);
+    const blobs = (
+      db.prepare('SELECT COUNT(*) AS n FROM imm_cover_art_blobs').get() as { n: number }
+    ).n;
+    assert.equal(blobs, 1);
+  });
+});
+
+for (const targetId of [1, 2, 3]) {
+  test(`merge rejects mixed providers before moving any source into entry ${targetId}`, () => {
+    withDb((db) => {
+      insertAnime(db, 1, 'Anime', 77);
+      insertAnime(db, 2, 'Drama');
+      insertAnime(db, 3, 'Unlinked');
+      insertEpisode(db, 1, 1, 1);
+      insertEpisode(db, 2, 2, 1);
+      db.exec(
+        "UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = 12, tmdb_type = 'tv' WHERE anime_id = 2",
+      );
+      for (const merge of [mergeAnimeRecords, mergeAnimeRecordsInTransaction]) {
+        assert.throws(
+          () => merge(db, targetId, [3, 1, 2]),
+          /AniList-linked and TMDB-linked library entries cannot be merged/,
+        );
+        assert.equal(animeCount(db), 3);
+        assert.equal(videoOwner(db, 1), 1);
+        assert.equal(videoOwner(db, 2), 2);
+      }
+    });
+  });
+}
+
+for (const mode of ['manual', 'auto'] as const) {
+  test(`TMDB ${mode} linking rolls back the merge when the survivor update fails`, () => {
+    withDb((db) => {
+      insertAnime(db, 1, 'New entry');
+      insertAnime(db, 2, 'Existing entry');
+      insertEpisode(db, 1, 1, 1);
+      insertEpisode(db, 2, 2, 2);
+      db.prepare(
+        "UPDATE imm_anime SET tmdb_id = ?, tmdb_type = 'tv', media_kind = 'live_action' WHERE anime_id = 2",
+      ).run(HANZAWA.tmdbId);
+      db.exec(`CREATE TRIGGER reject_link BEFORE UPDATE ON imm_anime
+        WHEN NEW.description = 'A banker fights back.'
+        BEGIN SELECT RAISE(ABORT, 'rejected survivor update'); END`);
+      assert.throws(
+        () => linkAnimeToTmdbTitle(db, 1, HANZAWA, { mode }),
+        /rejected survivor update/,
+      );
+      assert.equal(animeCount(db), 2);
+      assert.equal(videoOwner(db, 1), 1);
+      assert.equal(videoOwner(db, 2), 2);
+      assert.equal(animeRow(db, 1)?.tmdbId, null);
+      assert.equal(animeRow(db, 2)?.tmdbId, HANZAWA.tmdbId);
+    });
+  });
+}
+
+for (const mode of ['manual', 'auto'] as const) {
+  test(`${mode} TMDB linking refreshes completion totals without merging records`, () => {
+    withDb((db) => {
+      insertAnime(db, 1, 'Hanzawa Naoki');
+      insertEpisode(db, 1, 1, 1);
+      const completed = () =>
+        (
+          db
+            .prepare('SELECT anime_completed AS count FROM imm_lifetime_global WHERE global_id = 1')
+            .get() as { count: number }
+        ).count;
+      assert.equal(completed(), 0);
+      const result = linkAnimeToTmdbTitle(db, 1, { ...HANZAWA, episodesTotal: 1 }, { mode });
+      assert.deepEqual(result.mergedAnimeIds, []);
+      assert.equal(completed(), 1);
+      linkAnimeToTmdbTitle(db, 1, { ...HANZAWA, episodesTotal: 2 }, { mode: 'manual' });
+      assert.equal(completed(), 0);
+      assert.equal(animeCount(db), 1);
+    });
+  });
+}

src/core/services/immersion-tracker/anime-merge.ts

@@ -1,4 +1,4 @@
-import type { MediaKind } from '../../../shared/media-kind';
+import { shareTitleNamespace, type MediaKind } from '../../../shared/media-kind';
 import type { DatabaseSync } from './sqlite';
 import { recomputeLifetimeAnimeAggregatesInTransaction } from './lifetime';
 import { toDbTimestamp } from './query-shared';
@@ -6,8 +6,12 @@ import { nowMs } from './time';
 
 /** Thrown when a move names an episode or destination entry that is not there. */
 export const UNKNOWN_MOVE_TARGET_MESSAGE = 'Unknown episode or target library entry';
-/** Thrown when a merge or move would mix an anime entry with a YouTube channel. */
+/** Thrown when a merge would combine an AniList-linked entry with a TMDB-linked one. */
-export const MEDIA_KIND_MISMATCH_MESSAGE = 'Anime and YouTube channel entries cannot be combined';
+export const INCOMPATIBLE_PROVIDER_MERGE_MESSAGE =
+  'AniList-linked and TMDB-linked library entries cannot be merged together';
+/** Thrown when a merge or move would mix a YouTube channel with an anime or live-action entry. */
+export const MEDIA_KIND_MISMATCH_MESSAGE =
+  'YouTube channels cannot be combined with anime or live-action entries';
 
 export interface AnimeMergeSummary {
   /** Library entry that owns every moved episode once the merge finishes. */
@@ -33,6 +37,9 @@ interface AnimeMetadataRow {
   title_native: string | null;
   episodes_total: number | null;
   description: string | null;
+  media_kind: string;
+  tmdb_id: number | null;
+  tmdb_type: string | null;
 }
 
 function emptyMergeSummary(survivingAnimeId: number): AnimeMergeSummary {
@@ -55,7 +62,8 @@ function readAnimeMetadata(db: DatabaseSync, animeId: number): AnimeMetadataRow
   return (db
     .prepare(
       `
-        SELECT normalized_title_key, anilist_id, title_romaji, title_english, title_native, episodes_total, description
+        SELECT normalized_title_key, anilist_id, title_romaji, title_english, title_native, episodes_total, description,
+               media_kind, tmdb_id, tmdb_type
         FROM imm_anime
         WHERE anime_id = ?
       `,
@@ -137,6 +145,12 @@ function absorbAnimeMetadata(
         title_native = COALESCE(title_native, ?),
         episodes_total = COALESCE(episodes_total, ?),
         description = COALESCE(description, ?),
+        tmdb_id = COALESCE(tmdb_id, ?),
+        tmdb_type = CASE WHEN tmdb_id IS NULL THEN ? ELSE tmdb_type END,
+        media_kind = CASE
+          WHEN anilist_id IS NULL AND tmdb_id IS NULL AND ? IS NOT NULL THEN ?
+          ELSE media_kind
+        END,
         LAST_UPDATE_DATE = ?
       WHERE anime_id = ?
     `,
@@ -147,6 +161,10 @@ function absorbAnimeMetadata(
     source.title_native,
     source.episodes_total,
     source.description,
+    source.tmdb_id,
+    source.tmdb_type,
+    source.tmdb_id,
+    source.media_kind,
     updatedAt,
     targetAnimeId,
   );
@@ -172,6 +190,18 @@ export function mergeAnimeRecordsInTransaction(
     return summary;
   }
 
+  // Validate the whole group before moving anything, including when the
+  // unlinked target would inherit conflicting providers from two sources.
+  const metadata = [targetAnimeId, ...new Set(sourceAnimeIds)].map((id) =>
+    readAnimeMetadata(db, id),
+  );
+  if (
+    metadata.some((row) => row?.anilist_id != null) &&
+    metadata.some((row) => row?.tmdb_id != null)
+  ) {
+    throw new Error(INCOMPATIBLE_PROVIDER_MERGE_MESSAGE);
+  }
+
   const updatedAt = toDbTimestamp(nowMs());
   const sourceVideosStmt = db.prepare(
     'SELECT video_id AS videoId FROM imm_videos WHERE anime_id = ?',
@@ -206,8 +236,8 @@ export function mergeAnimeRecordsInTransaction(
     const sourceKind = readMediaKind(db, sourceAnimeId);
     if (sourceKind === null) continue;
     // A channel folded into an anime would only be recreated on the next
-    // watch, because title lookups never cross kinds; refuse instead.
+    // watch, because title lookups never cross namespaces; refuse instead.
-    if (sourceKind !== targetKind) {
+    if (!shareTitleNamespace(sourceKind, targetKind)) {
       throw new Error(MEDIA_KIND_MISMATCH_MESSAGE);
     }
 
@@ -275,7 +305,8 @@ export function moveVideoToAnime(
     }
 
     const previousAnimeId = videoRow.animeId;
-    if (previousAnimeId !== null && readMediaKind(db, previousAnimeId) !== targetKind) {
+    const previousKind = previousAnimeId === null ? null : readMediaKind(db, previousAnimeId);
+    if (previousKind !== null && !shareTitleNamespace(previousKind, targetKind)) {
       throw new Error(MEDIA_KIND_MISMATCH_MESSAGE);
     }
     if (previousAnimeId === targetAnimeId) {

src/core/services/immersion-tracker/anime-season-repair.ts

@@ -134,7 +134,7 @@ function getAnimeRow(db: DatabaseSync, animeId: number): AnimeRow | null {
           episodes_total,
           description
         FROM imm_anime
-        WHERE anime_id = ? AND media_kind = 'anime'
+        WHERE anime_id = ? AND media_kind != 'youtube'
       `,
     )
     .get(animeId) as AnimeRow | null;
@@ -372,6 +372,18 @@ export function resolveAnimeAnilistConflict(
   targetAnimeId: number,
   anilistId: number,
   options: AnimeAnilistConflictOptions = {},
+): AnimeSeasonRepairSummary {
+  return runInTransaction(db, () =>
+    resolveAnimeAnilistConflictInTransaction(db, targetAnimeId, anilistId, options),
+  );
+}
+
+/** Caller owns the write transaction. */
+export function resolveAnimeAnilistConflictInTransaction(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  anilistId: number,
+  options: AnimeAnilistConflictOptions = {},
 ): AnimeSeasonRepairSummary {
   if (!getAnimeRow(db, targetAnimeId)) {
     const summary = emptySummary();
@@ -392,90 +404,88 @@ export function resolveAnimeAnilistConflict(
   if (!conflict) {
     return emptySummary();
   }
-
   if (!getAnimeRow(db, conflict.animeId)) {
     const summary = emptySummary();
     summary.anilistAssignmentBlocked = true;
     return summary;
   }
-  return runInTransaction(db, () => {
-    const targetRow = getAnimeRow(db, targetAnimeId);
-    if (
-      options.survivor !== 'target' &&
-      targetRow?.anilist_id != null &&
-      targetRow.anilist_id !== anilistId
-    ) {
-      // An automatic lookup disagreeing with an existing explicit link is a
-      // mis-resolution, not evidence that either row should move or merge. The
-      // colliding id must not be assigned either: another row owns it and
-      // imm_anime.anilist_id is UNIQUE.
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
-    const isManual = options.survivor === 'target' || options.matchConfidence === 'manual';
-    if (!isManual && hasDismissedAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId)) {
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
-    const targetSeasons = getParsedSeasonsForAnime(db, targetAnimeId);
-    const conflictSeasons = getParsedSeasonsForAnime(db, conflict.animeId);
-    if (
-      !isManual &&
-      targetSeasons.size === 1 &&
-      conflictSeasons.size === 1 &&
-      [...targetSeasons][0] !== [...conflictSeasons][0]
-    ) {
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
-    if (canMergeAnilistConflict(db, targetAnimeId, conflict.animeId, anilistId, options)) {
-      const survivingAnimeId = options.survivor === 'target' ? targetAnimeId : conflict.animeId;
-      const absorbedAnimeId = survivingAnimeId === targetAnimeId ? conflict.animeId : targetAnimeId;
-      const merge = mergeAnimeRecordsInTransaction(db, survivingAnimeId, [absorbedAnimeId]);
-      const summary = emptySummary(1);
-      summary.movedVideos = merge.movedVideos;
-      summary.deletedAnimeRows = merge.mergedAnimeIds.length;
-      if (merge.mergedAnimeIds.length > 0) {
-        summary.repaired = 1;
-        // Only reported once a row really absorbed the other, so callers never
-        // follow this to an anime id that was never written.
-        summary.survivingAnimeId = survivingAnimeId;
-        summary.affectedAnimeIds.push(survivingAnimeId, absorbedAnimeId);
-      }
-      // Lifetime summaries are rebuilt by the caller off this summary, the same
-      // as the redistribution path below.
-      return summary;
-    }
 
-    if (shouldRecommendAnilistConflict(db, targetAnimeId, conflict.animeId, options)) {
+  const targetRow = getAnimeRow(db, targetAnimeId);
-      recordAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId, anilistId);
+  if (
-      const summary = emptySummary(1);
+    options.survivor !== 'target' &&
-      summary.mergeRecommended = true;
+    targetRow?.anilist_id != null &&
-      return summary;
+    targetRow.anilist_id !== anilistId
+  ) {
+    // An automatic lookup disagreeing with an existing explicit link is a
+    // mis-resolution, not evidence that either row should move or merge. The
+    // colliding id must not be assigned either: another row owns it and
+    // imm_anime.anilist_id is UNIQUE.
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
+  const isManual = options.survivor === 'target' || options.matchConfidence === 'manual';
+  if (!isManual && hasDismissedAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId)) {
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
+  const targetSeasons = getParsedSeasonsForAnime(db, targetAnimeId);
+  const conflictSeasons = getParsedSeasonsForAnime(db, conflict.animeId);
+  if (
+    !isManual &&
+    targetSeasons.size === 1 &&
+    conflictSeasons.size === 1 &&
+    [...targetSeasons][0] !== [...conflictSeasons][0]
+  ) {
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
+  if (canMergeAnilistConflict(db, targetAnimeId, conflict.animeId, anilistId, options)) {
+    const survivingAnimeId = options.survivor === 'target' ? targetAnimeId : conflict.animeId;
+    const absorbedAnimeId = survivingAnimeId === targetAnimeId ? conflict.animeId : targetAnimeId;
+    const merge = mergeAnimeRecordsInTransaction(db, survivingAnimeId, [absorbedAnimeId]);
+    const summary = emptySummary(1);
+    summary.movedVideos = merge.movedVideos;
+    summary.deletedAnimeRows = merge.mergedAnimeIds.length;
+    if (merge.mergedAnimeIds.length > 0) {
+      summary.repaired = 1;
+      // Only reported once a row really absorbed the other, so callers never
+      // follow this to an anime id that was never written.
+      summary.survivingAnimeId = survivingAnimeId;
+      summary.affectedAnimeIds.push(survivingAnimeId, absorbedAnimeId);
     }
+    // Lifetime summaries are rebuilt by the caller off this summary, the same
+    // as the redistribution path below.
+    return summary;
+  }
 
-    const isExactAutomaticMatch =
+  if (shouldRecommendAnilistConflict(db, targetAnimeId, conflict.animeId, options)) {
-      options.matchConfidence === 'exact' ||
+    recordAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId, anilistId);
-      (options.matchConfidence === undefined &&
+    const summary = emptySummary(1);
-        hasExactStoredTitleMatch(db, targetAnimeId, conflict.animeId));
+    summary.mergeRecommended = true;
-    if (!isManual && !isExactAutomaticMatch) {
+    return summary;
-      // Redistribution dismantles the id's current owner and hands the id to
+  }
-      // the target. On a weak automatic match that owner is usually the
-      // correctly linked card (e.g. a legitimate multi-season entry), so
-      // splitting it here is exactly the fuzzy false merge this gate exists to
-      // stop. Only exact or manual evidence may fall through.
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
 
-    return redistributeAnimeRowByParsedSeasonsInTransaction(db, conflict.animeId, {
+  const isExactAutomaticMatch =
-      transferAnilistToAnimeId: targetAnimeId,
+    options.matchConfidence === 'exact' ||
-      overwriteTargetAnilist: true,
+    (options.matchConfidence === undefined &&
-    });
+      hasExactStoredTitleMatch(db, targetAnimeId, conflict.animeId));
+  if (!isManual && !isExactAutomaticMatch) {
+    // Redistribution dismantles the id's current owner and hands the id to
+    // the target. On a weak automatic match that owner is usually the
+    // correctly linked card (e.g. a legitimate multi-season entry), so
+    // splitting it here is exactly the fuzzy false merge this gate exists to
+    // stop. Only exact or manual evidence may fall through.
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
+
+  return redistributeAnimeRowByParsedSeasonsInTransaction(db, conflict.animeId, {
+    transferAnilistToAnimeId: targetAnimeId,
+    overwriteTargetAnilist: true,
   });
 }
 

src/core/services/immersion-tracker/live-action-link.ts

@@ -0,0 +1,179 @@
+import type { DatabaseSync } from './sqlite';
+import type { TmdbMediaType } from '../../../shared/media-kind';
+import { mergeAnimeRecordsInTransaction } from './anime-merge';
+import { recomputeLifetimeAnimeAggregatesInTransaction } from './lifetime';
+import { toDbTimestamp } from './query-shared';
+import { nowMs } from './time';
+
+export interface LiveActionTitleInput {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+  titleEnglish: string | null;
+  titleNative: string | null;
+  description: string | null;
+  episodesTotal: number | null;
+}
+
+export interface LiveActionLinkResult {
+  /** Library entry that carries the TMDB link once the call finishes. */
+  animeId: number;
+  /** Entries folded into `animeId` because they pointed at the same TMDB title. */
+  mergedAnimeIds: number[];
+}
+
+export interface LiveActionLinkOptions {
+  /**
+   * `manual`: the user picked this title, so stored titles are overwritten and
+   * every other holder of the TMDB id is folded into this entry.
+   * `auto`: an exact filename match, so gaps are filled and the entry joins an
+   * existing holder rather than displacing it.
+   */
+  mode: 'manual' | 'auto';
+}
+
+export interface VideoTmdbLink {
+  animeId: number;
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+}
+
+function findOtherTmdbHolders(
+  db: DatabaseSync,
+  animeId: number,
+  input: Pick<LiveActionTitleInput, 'tmdbId' | 'tmdbType'>,
+): number[] {
+  return (
+    db
+      .prepare(
+        `SELECT anime_id AS animeId
+         FROM imm_anime
+         WHERE tmdb_id = ? AND tmdb_type = ? AND anime_id != ?
+         ORDER BY anime_id ASC`,
+      )
+      .all(input.tmdbId, input.tmdbType, animeId) as Array<{ animeId: number }>
+  ).map((row) => row.animeId);
+}
+
+/**
+ * Link a library entry to a TMDB title. Unlike AniList, a TMDB show spans all
+ * of its seasons, so entries that resolve to the same title are one show and
+ * are merged regardless of the season each was parsed with.
+ */
+export function linkAnimeToTmdbTitle(
+  db: DatabaseSync,
+  animeId: number,
+  input: LiveActionTitleInput,
+  options: LiveActionLinkOptions,
+): LiveActionLinkResult {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const result = linkAnimeToTmdbTitleInTransaction(db, animeId, input, options);
+    db.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+/** Caller owns the write transaction, including any artwork replacement. */
+export function linkAnimeToTmdbTitleInTransaction(
+  db: DatabaseSync,
+  animeId: number,
+  input: LiveActionTitleInput,
+  options: LiveActionLinkOptions,
+): LiveActionLinkResult {
+  const target = db.prepare('SELECT anilist_id FROM imm_anime WHERE anime_id = ?').get(animeId) as
+    | { anilist_id: number | null }
+    | undefined;
+  if (!target) throw new Error('Unknown library entry');
+  if (target.anilist_id !== null) {
+    if (options.mode === 'auto')
+      throw new Error('Cannot automatically replace an AniList identity');
+    // An explicit reassignment changes providers before compatible rows merge.
+    db.prepare('UPDATE imm_anime SET anilist_id = NULL WHERE anime_id = ?').run(animeId);
+  }
+  const others = findOtherTmdbHolders(db, animeId, input);
+  let survivor = animeId;
+  let mergedAnimeIds: number[] = [];
+  if (others.length > 0) {
+    if (options.mode === 'manual') {
+      mergedAnimeIds = mergeAnimeRecordsInTransaction(db, animeId, others).mergedAnimeIds;
+    } else {
+      // Keep the entry the user already sees; the newcomer is the transient
+      // "Show Season 3" row that a fresh season folder just created.
+      survivor = others[0]!;
+      mergedAnimeIds = mergeAnimeRecordsInTransaction(db, survivor, [
+        animeId,
+        ...others.slice(1),
+      ]).mergedAnimeIds;
+    }
+  }
+
+  const updatedAt = toDbTimestamp(nowMs());
+  if (options.mode === 'manual') {
+    db.prepare(
+      `UPDATE imm_anime
+       SET media_kind = 'live_action',
+           tmdb_id = ?,
+           tmdb_type = ?,
+           anilist_id = NULL,
+           title_romaji = NULL,
+           title_english = ?,
+           title_native = ?,
+           episodes_total = ?,
+           description = ?,
+           LAST_UPDATE_DATE = ?
+       WHERE anime_id = ?`,
+    ).run(
+      input.tmdbId,
+      input.tmdbType,
+      input.titleEnglish,
+      input.titleNative,
+      input.episodesTotal,
+      input.description,
+      updatedAt,
+      survivor,
+    );
+  } else {
+    db.prepare(
+      `UPDATE imm_anime
+       SET media_kind = 'live_action',
+           tmdb_id = ?,
+           tmdb_type = ?,
+           title_english = COALESCE(title_english, ?),
+           title_native = COALESCE(title_native, ?),
+           episodes_total = COALESCE(episodes_total, ?),
+           description = COALESCE(description, ?),
+           LAST_UPDATE_DATE = ?
+       WHERE anime_id = ?`,
+    ).run(
+      input.tmdbId,
+      input.tmdbType,
+      input.titleEnglish,
+      input.titleNative,
+      input.episodesTotal,
+      input.description,
+      updatedAt,
+      survivor,
+    );
+  }
+  recomputeLifetimeAnimeAggregatesInTransaction(db);
+  return { animeId: survivor, mergedAnimeIds };
+}
+
+/** The TMDB link of the live-action entry a video belongs to, if any. */
+export function getVideoTmdbLink(db: DatabaseSync, videoId: number): VideoTmdbLink | null {
+  const row = db
+    .prepare(
+      `SELECT a.anime_id AS animeId, a.tmdb_id AS tmdbId, a.tmdb_type AS tmdbType
+       FROM imm_videos v
+       JOIN imm_anime a ON a.anime_id = v.anime_id
+       WHERE v.video_id = ?
+         AND a.media_kind = 'live_action'
+         AND a.tmdb_id IS NOT NULL
+         AND a.tmdb_type IN ('tv', 'movie')`,
+    )
+    .get(videoId) as VideoTmdbLink | undefined;
+  return row ? { animeId: row.animeId, tmdbId: row.tmdbId, tmdbType: row.tmdbType } : null;
+}

src/core/services/immersion-tracker/query-library.ts

@@ -35,6 +35,9 @@ export function getAnimeLibrary(db: DatabaseSync): AnimeLibraryRow[] {
       a.canonical_title AS canonicalTitle,
       a.media_kind AS mediaKind,
       a.anilist_id AS anilistId,
+      a.media_kind AS mediaKind,
+      a.tmdb_id AS tmdbId,
+      a.tmdb_type AS tmdbType,
       COALESCE(lm.total_sessions, 0) AS totalSessions,
       COALESCE(lm.total_active_ms, 0) AS totalActiveMs,
       COALESCE(lm.total_cards, 0) AS totalCards,
@@ -66,6 +69,9 @@ export function getAnimeDetail(db: DatabaseSync, animeId: number): AnimeDetailRo
       a.canonical_title AS canonicalTitle,
       a.media_kind AS mediaKind,
       a.anilist_id AS anilistId,
+      a.media_kind AS mediaKind,
+      a.tmdb_id AS tmdbId,
+      a.tmdb_type AS tmdbType,
       a.title_romaji AS titleRomaji,
       a.title_english AS titleEnglish,
       a.title_native AS titleNative,

src/core/services/immersion-tracker/query-maintenance.ts

@@ -331,6 +331,29 @@ export async function cleanupVocabularyStats(
   };
 }
 
+/**
+ * Drop the cached art of every episode in a library entry. Used when a manual
+ * relink points at a title with no artwork, so the previous link's cover does
+ * not keep standing in for it.
+ */
+export function clearAnimeCoverArt(db: DatabaseSync, animeId: number): void {
+  const rows = db
+    .prepare(
+      `SELECT m.cover_blob_hash AS coverBlobHash
+       FROM imm_media_art m
+       JOIN imm_videos v ON v.video_id = m.video_id
+       WHERE v.anime_id = ?`,
+    )
+    .all(animeId) as Array<{ coverBlobHash: string | null }>;
+  if (rows.length === 0) return;
+  db.prepare(
+    'DELETE FROM imm_media_art WHERE video_id IN (SELECT video_id FROM imm_videos WHERE anime_id = ?)',
+  ).run(animeId);
+  for (const hash of new Set(rows.map((row) => row.coverBlobHash))) {
+    cleanupUnusedCoverArtBlobHash(db, hash);
+  }
+}
+
 export function upsertCoverArt(
   db: DatabaseSync,
   videoId: number,

src/core/services/immersion-tracker/storage.ts

@@ -1,4 +1,4 @@
-import type { MediaKind } from '../../../shared/media-kind';
+import { sameTitleNamespaceSql, type MediaKind } from '../../../shared/media-kind';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { parseMediaInfo } from '../../../jimaku/utils';
@@ -591,14 +591,19 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
           anime_id: number;
         } | null)
       : null;
+  // Title lookups stay inside the kind's namespace: a parsed filename may land
+  // on a TMDB-linked live-action row, but never on a YouTube channel.
   const byNormalizedTitle = db
-    .prepare('SELECT anime_id FROM imm_anime WHERE normalized_title_key = ? AND media_kind = ?')
+    .prepare(
+      `SELECT anime_id FROM imm_anime
+      WHERE normalized_title_key = ? AND ${sameTitleNamespaceSql()}`,
+    )
     .get(normalizedTitleKey, mediaKind) as { anime_id: number } | null;
   const byTitleAlias = db
     .prepare(
       `SELECT a.anime_id FROM imm_anime_title_aliases AS alias
       JOIN imm_anime AS a ON a.anime_id = alias.anime_id
-      WHERE alias.normalized_title_key = ? AND a.media_kind = ?`,
+      WHERE alias.normalized_title_key = ? AND ${sameTitleNamespaceSql('a.media_kind')}`,
     )
     .get(normalizedTitleKey, mediaKind) as { anime_id: number } | null;
   const existing = byAnilistId ?? byNormalizedTitle ?? byTitleAlias;
@@ -611,7 +616,11 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
         UPDATE imm_anime
         SET
           canonical_title = COALESCE(NULLIF(?, ''), canonical_title),
-          anilist_id = CASE WHEN ? = 'youtube' THEN NULL ELSE COALESCE(?, anilist_id) END,
+          anilist_id = CASE
+            WHEN ? = 'youtube' THEN NULL
+            WHEN tmdb_id IS NOT NULL THEN anilist_id
+            ELSE COALESCE(?, anilist_id)
+          END,
           title_romaji = COALESCE(?, title_romaji),
           title_english = COALESCE(?, title_english),
           title_native = COALESCE(?, title_native),
@@ -889,13 +898,19 @@ function migrateLegacyAnimeMetadata(db: DatabaseSync): void {
   }
 }
 
-// SQLite cannot drop a table-level UNIQUE constraint. Rebuild with IDs intact
+// SQLite cannot drop a table-level UNIQUE constraint or a column CHECK.
-// and foreign keys disabled so dependent history and manual assignments survive.
+// Rebuild with IDs intact and foreign keys disabled so dependent history and
-function migrateAnimeTitleUniqueness(db: DatabaseSync): void {
+// manual assignments survive. Two shapes need it: the original
+// `normalized_title_key UNIQUE`, and the v0.19.6 `media_kind` column whose
+// CHECK only allowed 'anime' and 'youtube'.
+const LEGACY_TITLE_UNIQUE_RE = /normalized_title_key TEXT NOT NULL UNIQUE/i;
+const LEGACY_MEDIA_KIND_CHECK_RE = /\s*CHECK\s*\(\s*media_kind IN \('anime',\s*'youtube'\)\s*\)/i;
+
+function migrateAnimeTableConstraints(db: DatabaseSync): void {
   const schema = db.prepare("SELECT sql FROM sqlite_master WHERE name = 'imm_anime'").get() as {
     sql: string;
   };
-  if (/normalized_title_key TEXT NOT NULL UNIQUE/i.test(schema.sql)) {
+  if (LEGACY_TITLE_UNIQUE_RE.test(schema.sql) || LEGACY_MEDIA_KIND_CHECK_RE.test(schema.sql)) {
     const foreignKeys = db.prepare('PRAGMA foreign_keys').get() as { foreign_keys: number };
     const sequence = db
       .prepare("SELECT seq FROM sqlite_sequence WHERE name = 'imm_anime'")
@@ -909,10 +924,8 @@ function migrateAnimeTitleUniqueness(db: DatabaseSync): void {
             /CREATE TABLE (?:IF NOT EXISTS )?["`]?imm_anime["`]?/i,
             'CREATE TABLE imm_anime_new',
           )
-          .replace(
+          .replace(LEGACY_TITLE_UNIQUE_RE, 'normalized_title_key TEXT NOT NULL')
-            /normalized_title_key TEXT NOT NULL UNIQUE/i,
+          .replace(LEGACY_MEDIA_KIND_CHECK_RE, ''),
-            'normalized_title_key TEXT NOT NULL',
-          ),
       );
       db.exec(`INSERT INTO imm_anime_new SELECT * FROM imm_anime;
         DROP TABLE imm_anime;
@@ -930,8 +943,11 @@ function migrateAnimeTitleUniqueness(db: DatabaseSync): void {
       db.exec(`PRAGMA foreign_keys = ${foreignKeys.foreign_keys}`);
     }
   }
-  db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_anime_kind_title
+  // v0.19.6 scoped titles per kind; anime and live-action now share one
-    ON imm_anime(media_kind, normalized_title_key)`);
+  // namespace (an entry moves between them when relinked), YouTube is separate.
+  db.exec(`DROP INDEX IF EXISTS idx_anime_kind_title;
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_anime_namespace_title
+    ON imm_anime((media_kind = 'youtube'), normalized_title_key)`);
 }
 
 // Older builds can create channel rows with the default anime kind even after
@@ -995,17 +1011,20 @@ export function ensureSchema(db: DatabaseSync): void {
       title_native TEXT,
       episodes_total INTEGER,
       description TEXT,
+      media_kind TEXT NOT NULL DEFAULT 'anime',
+      tmdb_id INTEGER,
+      tmdb_type TEXT,
       metadata_json TEXT,
       CREATED_DATE TEXT,
       LAST_UPDATE_DATE TEXT
     );
   `);
-  addColumnIfMissing(
+  // Schema 26: media_kind separates anime, live-action (TMDB link) and YouTube
-    db,
+  // channel entries. Kinds are validated in code, not by a CHECK constraint,
-    'imm_anime',
+  // so adding one later does not need a table rebuild.
-    'media_kind',
+  addColumnIfMissing(db, 'imm_anime', 'media_kind', "TEXT NOT NULL DEFAULT 'anime'");
-    "TEXT NOT NULL DEFAULT 'anime' CHECK(media_kind IN ('anime', 'youtube'))",
+  addColumnIfMissing(db, 'imm_anime', 'tmdb_id', 'INTEGER');
-  );
+  addColumnIfMissing(db, 'imm_anime', 'tmdb_type', 'TEXT');
   db.exec(`
     CREATE TABLE IF NOT EXISTS imm_videos(
       video_id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -1549,7 +1568,7 @@ export function ensureSchema(db: DatabaseSync): void {
     );
   }
 
-  migrateAnimeTitleUniqueness(db);
+  migrateAnimeTableConstraints(db);
   classifyYoutubeChannels(db);
   migrateSessionEventTimestampsToText(db);
 
@@ -1565,6 +1584,10 @@ export function ensureSchema(db: DatabaseSync): void {
     CREATE INDEX IF NOT EXISTS idx_anime_anilist_id
     ON imm_anime(anilist_id)
   `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_anime_tmdb_id
+    ON imm_anime(tmdb_id, tmdb_type)
+  `);
   db.exec(`
     CREATE INDEX IF NOT EXISTS idx_videos_anime_id
     ON imm_videos(anime_id)

src/core/services/immersion-tracker/types.ts

@@ -1,6 +1,7 @@
-import type { MediaKind } from '../../../shared/media-kind';
+import type { MediaKind, TmdbMediaType } from '../../../shared/media-kind';
 
-export const SCHEMA_VERSION = 25;
+// 26: live-action entries (TMDB link) and YouTube channels share the media_kind column.
+export const SCHEMA_VERSION = 26;
 export const DEFAULT_QUEUE_CAP = 1_000;
 export const DEFAULT_BATCH_SIZE = 25;
 export const DEFAULT_FLUSH_INTERVAL_MS = 500;
@@ -524,6 +525,8 @@ export interface AnimeLibraryRow {
   animeId: number;
   canonicalTitle: string;
   anilistId: number | null;
+  tmdbId: number | null;
+  tmdbType: TmdbMediaType | null;
   totalSessions: number;
   totalActiveMs: number;
   totalCards: number;
@@ -538,6 +541,8 @@ export interface AnimeDetailRow {
   animeId: number;
   canonicalTitle: string;
   anilistId: number | null;
+  tmdbId: number | null;
+  tmdbType: TmdbMediaType | null;
   titleRomaji: string | null;
   titleEnglish: string | null;
   titleNative: string | null;

src/core/services/immersion-tracker/youtube-kind.test.ts

@@ -81,7 +81,7 @@ test('schema 23 channel migration preserves history and manual assignments and i
     const history = getAnimeLibrary(db);
     // Reproduce the previous schema, including its lack of a media kind column.
     db.exec(
-      'DROP INDEX idx_anime_kind_title; ALTER TABLE imm_anime DROP COLUMN media_kind; DELETE FROM imm_schema_version; INSERT INTO imm_schema_version VALUES (23, 0)',
+      'DROP INDEX idx_anime_namespace_title; ALTER TABLE imm_anime DROP COLUMN media_kind; DELETE FROM imm_schema_version; INSERT INTO imm_schema_version VALUES (23, 0)',
     );
     ensureSchema(db);
     ensureSchema(db);
@@ -240,6 +240,52 @@ test('title identity and aliases never cross media kinds', () => {
   }
 });
 
+test('anime title lookups land on a same-named live-action entry but never on a channel', () => {
+  const db = new Database(':memory:');
+  try {
+    ensureSchema(db);
+    const dramaId = createAnime(db, 'Hanzawa Naoki');
+    db.prepare(
+      "UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = 61222, tmdb_type = 'tv' WHERE anime_id = ?",
+    ).run(dramaId);
+    // A later season folder parses to the same title with the default anime
+    // kind and must join the TMDB-linked entry rather than duplicate it.
+    assert.equal(
+      getOrCreateAnimeRecord(db, {
+        parsedTitle: 'Hanzawa Naoki',
+        canonicalTitle: 'Hanzawa Naoki',
+        anilistId: 99,
+        titleRomaji: null,
+        titleEnglish: null,
+        titleNative: null,
+        metadataJson: null,
+      }),
+      dramaId,
+    );
+    const row = db
+      .prepare('SELECT media_kind, anilist_id, tmdb_id FROM imm_anime WHERE anime_id = ?')
+      .get(dramaId) as { media_kind: string; anilist_id: number | null; tmdb_id: number };
+    assert.equal(row.media_kind, 'live_action');
+    assert.equal(row.anilist_id, null);
+    assert.equal(row.tmdb_id, 61222);
+    assert.notEqual(
+      getOrCreateAnimeRecord(db, {
+        mediaKind: 'youtube',
+        parsedTitle: 'Hanzawa Naoki',
+        canonicalTitle: 'Hanzawa Naoki',
+        anilistId: null,
+        titleRomaji: null,
+        titleEnglish: null,
+        titleNative: null,
+        metadataJson: null,
+      }),
+      dramaId,
+    );
+  } finally {
+    db.close();
+  }
+});
+
 test('schema 24 title constraint migration preserves referenced data', () => {
   const db = new Database(':memory:');
   try {
@@ -273,7 +319,9 @@ test('schema 24 title constraint migration preserves referenced data', () => {
         title_romaji TEXT, title_english TEXT, title_native TEXT, episodes_total INTEGER,
         description TEXT, metadata_json TEXT, CREATED_DATE TEXT, LAST_UPDATE_DATE TEXT,
         media_kind TEXT NOT NULL DEFAULT 'anime' CHECK(media_kind IN ('anime', 'youtube')));
-      INSERT INTO imm_anime SELECT * FROM old_anime;
+      INSERT INTO imm_anime SELECT anime_id, normalized_title_key, canonical_title, anilist_id,
+        title_romaji, title_english, title_native, episodes_total, description, metadata_json,
+        CREATED_DATE, LAST_UPDATE_DATE, media_kind FROM old_anime;
       DROP TABLE old_anime;
       DELETE FROM imm_schema_version;
       INSERT INTO imm_schema_version VALUES (24, 0);
@@ -281,6 +329,10 @@ test('schema 24 title constraint migration preserves referenced data', () => {
     ensureSchema(db);
     ensureSchema(db);
     assert.deepEqual(db.prepare('PRAGMA foreign_key_check').all(), []);
+    // The v0.19.6 CHECK only allowed anime and youtube; live-action must fit now.
+    db.prepare(
+      "INSERT INTO imm_anime(normalized_title_key, canonical_title, media_kind, tmdb_id, tmdb_type) VALUES ('drama', 'Drama', 'live_action', 1, 'tv')",
+    ).run();
     assert.equal(
       (db.prepare('PRAGMA foreign_keys').get() as { foreign_keys: number }).foreign_keys,
       1,

src/core/services/stats-server.ts

@@ -3,9 +3,11 @@ import http, { type IncomingMessage, type ServerResponse } from 'node:http';
 import { Readable } from 'node:stream';
 import type { AnkiConnectConfig } from '../../types.js';
 import type { AnilistRateLimiter } from './anilist/rate-limiter.js';
+import type { TmdbClient } from './tmdb/tmdb-client.js';
 import type { ImmersionTrackerService } from './immersion-tracker-service.js';
 import type { RetimedSecondarySubtitleInput } from './secondary-subtitle-sidecar.js';
 import type { StatsServerMediaGenerator } from './stats-server/mining-support.js';
+import { enforceStatsRequestSafety } from './stats-server/request-safety.js';
 import {
   registerStatsAnalyticsRoutes,
   registerStatsIntegrationRoutes,
@@ -37,7 +39,10 @@ function toFetchRequest(req: IncomingMessage): Request {
     method,
     headers: toFetchHeaders(req.headers),
   };
-  if (method !== 'GET' && method !== 'HEAD') {
+  const hasBody =
+    req.headers['transfer-encoding'] !== undefined ||
+    Number(req.headers['content-length'] ?? 0) > 0;
+  if (method !== 'GET' && method !== 'HEAD' && hasBody) {
     init.body = Readable.toWeb(req) as BodyInit;
     init.duplex = 'half';
   }
@@ -125,6 +130,7 @@ export interface StatsServerConfig {
     input: RetimedSecondarySubtitleInput,
   ) => Promise<string> | string;
   anilistRateLimiter?: AnilistRateLimiter;
+  tmdbClient?: TmdbClient;
   addYomitanNote?: (word: string) => Promise<number | null>;
   resolveAnkiNoteId?: (noteId: number) => number;
   resolveSentenceSearchHeadwords?: (term: string) => Promise<string[]> | string[];
@@ -147,6 +153,7 @@ export function createStatsApp(
       input: RetimedSecondarySubtitleInput,
     ) => Promise<string> | string;
     anilistRateLimiter?: AnilistRateLimiter;
+    tmdbClient?: TmdbClient;
     addYomitanNote?: (word: string) => Promise<number | null>;
     resolveAnkiNoteId?: (noteId: number) => number;
     resolveSentenceSearchHeadwords?: (term: string) => Promise<string[]> | string[];
@@ -156,6 +163,7 @@ export function createStatsApp(
   },
 ) {
   const app = new Hono();
+  app.use('*', enforceStatsRequestSafety);
   registerStatsAnalyticsRoutes(app, tracker, options);
   registerStatsLibraryRoutes(app, tracker, options);
   registerStatsIntegrationRoutes(app, tracker, options);
@@ -181,6 +189,7 @@ export async function startStatsServerWithRuntime(
     getStatsMiningAlassPath: config.getStatsMiningAlassPath,
     resolveRetimedSecondarySubtitleText: config.resolveRetimedSecondarySubtitleText,
     anilistRateLimiter: config.anilistRateLimiter,
+    tmdbClient: config.tmdbClient,
     addYomitanNote: config.addYomitanNote,
     resolveAnkiNoteId: config.resolveAnkiNoteId,
     resolveSentenceSearchHeadwords: config.resolveSentenceSearchHeadwords,

src/core/services/stats-server/integration-routes.ts

@@ -1,11 +1,13 @@
-import type { Hono } from 'hono';
+import type { Context, Hono } from 'hono';
 import type { AnkiConnectConfig } from '../../../types.js';
 import {
   statsJson,
   type StatsAnilistSearchResult,
   type StatsAnkiBrowseResponse,
 } from '../../../types/stats-http-contract.js';
+import { isTmdbMediaType } from '../../../shared/media-kind.js';
 import type { AnilistRateLimiter } from '../anilist/rate-limiter.js';
+import { TmdbApiKeyMissingError, type TmdbClient } from '../tmdb/tmdb-client.js';
 import { registerStatsCoverRoutes } from '../stats-cover-routes.js';
 import type { ImmersionTrackerService } from '../immersion-tracker-service.js';
 import {
@@ -29,6 +31,7 @@ export function registerStatsIntegrationRoutes(
     ankiConnectConfig?: AnkiConnectConfig;
     getAnkiConnectConfig?: () => AnkiConnectConfig | undefined;
     anilistRateLimiter?: AnilistRateLimiter;
+    tmdbClient?: TmdbClient;
     resolveAnkiNoteId?: (noteId: number) => number;
   },
 ): void {
@@ -73,6 +76,51 @@ export function registerStatsIntegrationRoutes(
     }
   });
 
+  const tmdbUnavailable = (c: Context, err: unknown) => {
+    if (err instanceof TmdbApiKeyMissingError) {
+      return c.json(statsJson('error', { error: err.message }), 503);
+    }
+    return c.json(statsJson('error', { error: 'TMDB request failed' }), 502);
+  };
+
+  app.get('/api/stats/tmdb/search', async (c) => {
+    const query = (c.req.query('q') ?? '').trim();
+    if (!query) return c.json(statsJson('tmdbSearch', []));
+    const tmdbClient = options?.tmdbClient;
+    if (!tmdbClient) return c.json(statsJson('tmdbSearch', []));
+    try {
+      return c.json(statsJson('tmdbSearch', await tmdbClient.search(query)));
+    } catch (err) {
+      return tmdbUnavailable(c, err);
+    }
+  });
+
+  app.patch('/api/stats/anime/:animeId/tmdb', async (c) => {
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) return c.body(null, 400);
+    const body = await c.req.json().catch(() => null);
+    const tmdbId = body?.tmdbId;
+    if (
+      typeof tmdbId !== 'number' ||
+      !Number.isInteger(tmdbId) ||
+      tmdbId <= 0 ||
+      !isTmdbMediaType(body?.tmdbType)
+    ) {
+      return c.body(null, 400);
+    }
+    if (!(await tracker.hasAnime(animeId))) return c.body(null, 404);
+    const tmdbClient = options?.tmdbClient;
+    if (!tmdbClient) return c.json(statsJson('error', { error: 'TMDB is not available' }), 503);
+    try {
+      const details = await tmdbClient.getDetails(body.tmdbType, tmdbId);
+      if (!details) return c.body(null, 404);
+      await tracker.reassignAnimeTmdb(animeId, details);
+      return c.json(statsJson('reassignAnimeTmdb', { ok: true }));
+    } catch (err) {
+      return tmdbUnavailable(c, err);
+    }
+  });
+
   app.get('/api/stats/known-words', (c) => {
     const knownWordsSet = loadKnownWordsSet(options?.knownWordCachePath);
     if (!knownWordsSet) return c.json(statsJson('knownWords', []));

src/core/services/stats-server/library-routes.ts

@@ -1,6 +1,7 @@
 import type { Hono } from 'hono';
 import { statsJson } from '../../../types/stats-http-contract.js';
 import {
+  INCOMPATIBLE_PROVIDER_MERGE_MESSAGE,
   MEDIA_KIND_MISMATCH_MESSAGE,
   UNKNOWN_MOVE_TARGET_MESSAGE,
 } from '../immersion-tracker/anime-merge.js';
@@ -252,8 +253,14 @@ export function registerStatsLibraryRoutes(
     try {
       summary = await tracker.mergeAnime(animeId, sourceAnimeIds);
     } catch (error) {
-      if (error instanceof Error && error.message === MEDIA_KIND_MISMATCH_MESSAGE) {
+      // Mixing providers or kinds is a rejected request, not a server fault,
-        return c.text(MEDIA_KIND_MISMATCH_MESSAGE, 409);
+      // so the dashboard can explain it instead of showing a bare 500.
+      if (
+        error instanceof Error &&
+        (error.message === INCOMPATIBLE_PROVIDER_MERGE_MESSAGE ||
+          error.message === MEDIA_KIND_MISMATCH_MESSAGE)
+      ) {
+        return c.json(statsJson('error', { error: error.message }), 409);
       }
       throw error;
     }

src/core/services/stats-server/request-safety.ts

@@ -0,0 +1,42 @@
+import type { MiddlewareHandler } from 'hono';
+
+function isLoopbackUrl(url: URL): boolean {
+  return (
+    url.protocol === 'http:' &&
+    !url.username &&
+    !url.password &&
+    ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+  );
+}
+
+/** Protect the local API even when a browser can reach the loopback listener. */
+export const enforceStatsRequestSafety: MiddlewareHandler = async (c, next) => {
+  const url = new URL(c.req.url);
+  if (!isLoopbackUrl(url)) return c.body(null, 403);
+
+  const host = c.req.header('host');
+  if (host !== undefined) {
+    if (!/^(localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?$/i.test(host)) {
+      return c.body(null, 403);
+    }
+    // Node derives the request URL from Host; Bun provides them independently.
+    try {
+      if (new URL(`http://${host}`).origin !== url.origin) return c.body(null, 403);
+    } catch {
+      return c.body(null, 403);
+    }
+  }
+
+  // Compare the serialized origin exactly. Opaque origins and malformed values
+  // containing credentials, paths, or multiple origins must not gain trust.
+  const origin = c.req.header('origin');
+  if (origin !== undefined && origin !== url.origin) return c.body(null, 403);
+  const site = c.req.header('sec-fetch-site');
+  if (site === 'cross-site' || site === 'same-site') return c.body(null, 403);
+
+  if (!['GET', 'HEAD', 'OPTIONS'].includes(c.req.method) && c.req.raw.body !== null) {
+    const contentType = c.req.header('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+    if (contentType !== 'application/json') return c.body(null, 415);
+  }
+  await next();
+};

src/core/services/stats-sync/merge-catalog.test.ts

@@ -0,0 +1,60 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Database, type DatabaseSync } from '../immersion-tracker/sqlite';
+import { ensureSchema } from '../immersion-tracker/storage';
+import { mergeAnime } from './merge-catalog';
+import { createEmptyMergeSummary } from './shared';
+
+const identities = {
+  unlinked: [null, null, null],
+  anilist: [42, null, null],
+  tmdb: [null, 12, 'tv'],
+  otherTmdb: [null, 13, 'tv'],
+} as const;
+
+for (const [localKind, remoteKind, sameEntry] of [
+  ['anilist', 'tmdb', false],
+  ['tmdb', 'anilist', false],
+  ['tmdb', 'otherTmdb', false],
+  ['unlinked', 'tmdb', true],
+  ['unlinked', 'anilist', true],
+  ['tmdb', 'unlinked', true],
+  ['tmdb', 'tmdb', true],
+  ['anilist', 'anilist', true],
+] as const) {
+  test(`catalog title match: ${localKind} with ${remoteKind}`, () => {
+    const local = new Database(':memory:');
+    const remote = new Database(':memory:');
+    const adapt = (db: DatabaseSync) => ({
+      query: (sql: string) => db.prepare(sql),
+      exec: (sql: string) => {
+        db.exec(sql);
+      },
+      close: () => {
+        db.close();
+      },
+    });
+    try {
+      for (const [db, kind] of [
+        [local, localKind],
+        [remote, remoteKind],
+      ] as const) {
+        ensureSchema(db);
+        db.prepare(
+          `INSERT INTO imm_anime(normalized_title_key, canonical_title, anilist_id, tmdb_id, tmdb_type, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES ('same title', 'Same title', ?, ?, ?, 1000, 1000)`,
+        ).run(...identities[kind]);
+      }
+      const summary = createEmptyMergeSummary();
+      const map = mergeAnime(adapt(local), adapt(remote), summary);
+      assert.equal(map.get(1) === 1, sameEntry);
+      assert.equal(summary.animeAdded, sameEntry ? 0 : 1);
+      const again = createEmptyMergeSummary();
+      assert.equal(mergeAnime(adapt(local), adapt(remote), again).get(1), map.get(1));
+      assert.equal(again.animeAdded, 0);
+    } finally {
+      local.close();
+      remote.close();
+    }
+  });
+}

src/core/services/stats-sync/merge-catalog.ts

@@ -1,5 +1,6 @@
 import { selectAll, selectOne, type SqlRow, type SyncDb } from './libsql-driver';
 import { insertRow, tableExists, type SyncMergeSummary } from './shared';
+import { sameTitleNamespaceSql } from '../../../shared/media-kind';
 
 const ANIME_COPY_COLUMNS = [
   'media_kind',
@@ -11,6 +12,8 @@ const ANIME_COPY_COLUMNS = [
   'title_native',
   'episodes_total',
   'description',
+  'tmdb_id',
+  'tmdb_type',
   'metadata_json',
   'CREATED_DATE',
   'LAST_UPDATE_DATE',
@@ -102,8 +105,14 @@ export function mergeAnime(
   const byAnilist = local.query(
     "SELECT anime_id FROM imm_anime WHERE anilist_id = ? AND media_kind = 'anime'",
   );
+  const byTmdb = local.query(
+    'SELECT anime_id FROM imm_anime WHERE tmdb_id = ? AND tmdb_type = ? ORDER BY anime_id LIMIT 1',
+  );
+  // Anime and live-action rows share a title namespace; YouTube channels are
+  // looked up on their own, so a same-named anime and channel stay separate.
   const byTitleKey = local.query(
-    'SELECT anime_id FROM imm_anime WHERE normalized_title_key = ? AND media_kind = ?',
+    `SELECT anime_id, anilist_id, tmdb_id, tmdb_type FROM imm_anime
+     WHERE normalized_title_key = ? AND ${sameTitleNamespaceSql()}`,
   );
   // A pre-classification channel can be repaired, but a genuine anime sharing
   // its title must remain a separate entry.
@@ -116,16 +125,25 @@ export function mergeAnime(
   const releaseChannelAnilistId = local.query(
     "UPDATE imm_anime SET anilist_id = NULL WHERE media_kind = 'youtube' AND anilist_id = ?",
   );
+  // A TMDB link only fills in when the local row is unlinked: a row already
+  // pinned to AniList stays anime, and vice versa, so the two link kinds never
+  // coexist on one entry. A channel match always becomes a channel.
   const fillMissing = local.query(
     `UPDATE imm_anime
      SET
-       media_kind = ?,
        anilist_id = CASE WHEN ? = 'youtube' THEN NULL ELSE anilist_id END,
        title_romaji = COALESCE(title_romaji, ?),
        title_english = COALESCE(title_english, ?),
        title_native = COALESCE(title_native, ?),
        episodes_total = COALESCE(episodes_total, ?),
-       description = COALESCE(description, ?)
+       description = COALESCE(description, ?),
+       tmdb_id = CASE WHEN anilist_id IS NULL THEN COALESCE(tmdb_id, ?) ELSE tmdb_id END,
+       tmdb_type = CASE WHEN anilist_id IS NULL AND tmdb_id IS NULL THEN ? ELSE tmdb_type END,
+       media_kind = CASE
+         WHEN ? = 'youtube' THEN 'youtube'
+         WHEN anilist_id IS NULL AND tmdb_id IS NULL THEN ?
+         ELSE media_kind
+       END
      WHERE anime_id = ?`,
   );
 
@@ -139,10 +157,25 @@ export function mergeAnime(
       // incorrectly attached one to a channel.
       releaseChannelAnilistId.run(row.anilist_id);
     }
+    const titleMatch = byTitleKey.get(row.normalized_title_key, row.media_kind) as
+      | SqlRow
+      | undefined;
+    const compatibleTitleMatch =
+      titleMatch &&
+      ((titleMatch.anilist_id === null && titleMatch.tmdb_id === null) ||
+        (row.anilist_id === null && row.tmdb_id === null) ||
+        (titleMatch.tmdb_id === null &&
+          row.tmdb_id === null &&
+          titleMatch.anilist_id === row.anilist_id) ||
+        (titleMatch.anilist_id === null &&
+          row.anilist_id === null &&
+          titleMatch.tmdb_id === row.tmdb_id &&
+          titleMatch.tmdb_type === row.tmdb_type));
     const existing = ((row.media_kind === 'anime' && row.anilist_id !== null
       ? byAnilist.get(row.anilist_id)
       : undefined) ??
-      byTitleKey.get(row.normalized_title_key, row.media_kind) ??
+      (row.tmdb_id !== null ? byTmdb.get(row.tmdb_id, row.tmdb_type) : undefined) ??
+      (compatibleTitleMatch ? titleMatch : undefined) ??
       (row.media_kind === 'youtube' ? legacyChannel.get(row.normalized_title_key) : undefined)) as
       | SqlRow
       | undefined;
@@ -150,22 +183,34 @@ export function mergeAnime(
       const localId = Number(existing.anime_id);
       map.set(remoteId, localId);
       fillMissing.run(
-        row.media_kind,
         row.media_kind,
         row.title_romaji,
         row.title_english,
         row.title_native,
         row.episodes_total,
         row.description,
+        row.tmdb_id,
+        row.tmdb_type,
+        row.media_kind,
+        row.media_kind,
         localId,
       );
       continue;
     }
-    // No local row matched by anilist_id (checked first in `existing` above)
+    // Conflicting providers can share a title, but the stored title key is
-    // or title key, so the remote anilist_id — if any — is free to insert as-is.
+    // unique within its namespace.
-    const values = ANIME_COPY_COLUMNS.map((column) =>
+    let titleKey = row.normalized_title_key;
-      column === 'anilist_id' && row.media_kind !== 'anime' ? null : row[column],
+    for (let suffix = 1; byTitleKey.get(titleKey, row.media_kind); suffix += 1) {
-    );
+      titleKey = `${row.normalized_title_key}:sync:${suffix}`;
+    }
+    const values = ANIME_COPY_COLUMNS.map((column) => {
+      if (column === 'normalized_title_key') return titleKey;
+      // No local row matched by anilist_id (checked first in `existing` above)
+      // or title key, so the remote anilist_id is free to insert as-is, except
+      // that channels never carry one.
+      if (column === 'anilist_id' && row.media_kind !== 'anime') return null;
+      return row[column];
+    });
     map.set(remoteId, insertRow(local, 'imm_anime', ANIME_COPY_COLUMNS, values));
     summary.animeAdded += 1;
   }

src/core/services/stats-window-runtime.ts

@@ -219,13 +219,8 @@ export function scheduleStatsWindowPostShowReconciles(
   }
 }
 
-export function buildStatsWindowLoadFileOptions(apiBaseUrl?: string): {
+export function buildStatsWindowUrl(apiBaseUrl: string): string {
-  query: Record<string, string>;
+  const url = new URL('/', apiBaseUrl);
-} {
+  url.searchParams.set('overlay', '1');
-  return {
+  return url.toString();
-    query: {
-      overlay: '1',
-      ...(apiBaseUrl ? { apiBase: apiBaseUrl } : {}),
-    },
-  };
 }

src/core/services/stats-window.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import {
-  buildStatsWindowLoadFileOptions,
+  buildStatsWindowUrl,
   buildStatsWindowOptions,
   buildStatsNativeConfirmDialogOptions,
   demoteVisibleStatsWindowBelowDialogs,
@@ -168,21 +168,12 @@ test('shouldHideStatsWindowForInput matches Escape and configured bare toggle ke
   );
 });
 
-test('buildStatsWindowLoadFileOptions enables overlay rendering mode', () => {
+test('buildStatsWindowUrl enables overlay rendering on the local HTTP origin', () => {
-  assert.deepEqual(buildStatsWindowLoadFileOptions(), {
+  assert.equal(buildStatsWindowUrl('http://127.0.0.1:6969'), 'http://127.0.0.1:6969/?overlay=1');
-    query: {
-      overlay: '1',
-    },
-  });
 });
 
-test('buildStatsWindowLoadFileOptions includes provided stats API base URL', () => {
+test('buildStatsWindowUrl uses the active server port as the document origin', () => {
-  assert.deepEqual(buildStatsWindowLoadFileOptions('http://127.0.0.1:6123'), {
+  assert.equal(buildStatsWindowUrl('http://127.0.0.1:6123'), 'http://127.0.0.1:6123/?overlay=1');
-    query: {
-      overlay: '1',
-      apiBase: 'http://127.0.0.1:6123',
-    },
-  });
 });
 
 test('resolveStatsWindowOuterBoundsForContent compensates for Wayland content insets', () => {

src/core/services/stats-window.ts

@@ -1,10 +1,9 @@
 import { BrowserWindow, dialog, ipcMain } from 'electron';
-import * as path from 'path';
 import { createLogger } from '../../logger.js';
 import type { WindowGeometry } from '../../types.js';
 import { IPC_CHANNELS } from '../../shared/ipc/contracts.js';
 import {
-  buildStatsWindowLoadFileOptions,
+  buildStatsWindowUrl,
   buildStatsWindowOptions,
   demoteVisibleStatsWindowBelowDialogs,
   presentStatsWindow,
@@ -34,12 +33,10 @@ const nativeDialogLayerSuspension = createStatsWindowLayerSuspensionState();
 const logger = createLogger('main:stats-window');
 
 export interface StatsWindowOptions {
-  /** Absolute path to stats/dist/ directory */
-  staticDir: string;
   /** Absolute path to the compiled preload-stats.js */
   preloadPath: string;
   /** Resolve the active stats API base URL */
-  getApiBaseUrl?: () => Promise<string> | string;
+  getApiBaseUrl: () => Promise<string> | string;
   /** Report server startup failure through the configured notification surface. */
   onStartupError?: (error: unknown) => void;
   /** Resolve the active stats toggle key from config */
@@ -188,7 +185,7 @@ export async function toggleStatsOverlay(options: StatsWindowOptions): Promise<v
   if (!statsWindow) {
     const generation = statsWindowGeneration;
     const apiBaseUrl = await Promise.resolve()
-      .then(() => options.getApiBaseUrl?.())
+      .then(() => options.getApiBaseUrl())
       .catch((error: unknown) => {
         options.onStartupError?.(error);
         throw error;
@@ -207,8 +204,7 @@ export async function toggleStatsOverlay(options: StatsWindowOptions): Promise<v
       statsWindow?.setTitle(STATS_WINDOW_TITLE);
     });
 
-    const indexPath = path.join(options.staticDir, 'index.html');
+    statsWindow.loadURL(buildStatsWindowUrl(apiBaseUrl));
-    statsWindow.loadFile(indexPath, buildStatsWindowLoadFileOptions(apiBaseUrl));
 
     statsWindow.on('closed', () => {
       options.onVisibilityChanged?.(false);

src/core/services/tmdb/bundled-api-key.test.ts

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { BUNDLED_INTEGRATION_KEYS_FILENAME, readBundledTmdbApiKey } from './bundled-api-key.js';
+
+test('readBundledTmdbApiKey reads the staged key and tolerates a missing or malformed file', () => {
+  const distDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-bundled-key-'));
+  const filePath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+  try {
+    assert.equal(readBundledTmdbApiKey(distDir), null);
+    fs.writeFileSync(filePath, '{"tmdbApiKey":" abc "}');
+    assert.equal(readBundledTmdbApiKey(distDir), 'abc');
+    fs.writeFileSync(filePath, '{"tmdbApiKey":""}');
+    assert.equal(readBundledTmdbApiKey(distDir), null);
+    fs.writeFileSync(filePath, 'not json');
+    assert.equal(readBundledTmdbApiKey(distDir), null);
+  } finally {
+    fs.rmSync(distDir, { recursive: true, force: true });
+  }
+});

src/core/services/tmdb/bundled-api-key.ts

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Release builds stage a project-owned TMDB key into dist/ (see
+ * scripts/bundled-integration-keys.mjs). Source checkouts and CI builds have no
+ * such file, and TMDB lookups then depend on the user's own `tmdb.apiKey`.
+ */
+export const BUNDLED_INTEGRATION_KEYS_FILENAME = 'bundled-integration-keys.json';
+
+export function readBundledTmdbApiKey(distDir: string): string | null {
+  try {
+    const raw = fs.readFileSync(path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME), 'utf8');
+    const parsed = JSON.parse(raw) as { tmdbApiKey?: unknown };
+    const key = typeof parsed.tmdbApiKey === 'string' ? parsed.tmdbApiKey.trim() : '';
+    return key.length > 0 ? key : null;
+  } catch {
+    return null;
+  }
+}

src/core/services/tmdb/live-action-resolver.test.ts

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createLiveActionMetadataResolver, titlesMatch } from './live-action-resolver.js';
+import {
+  TmdbApiKeyMissingError,
+  type TmdbClient,
+  type TmdbSearchResult,
+  type TmdbTitleDetails,
+} from './tmdb-client.js';
+
+const silentLogger = { info: () => {}, warn: () => {} };
+
+function searchResult(over: Partial<TmdbSearchResult> & { tmdbId: number }): TmdbSearchResult {
+  return {
+    tmdbType: 'tv',
+    title: 'Title',
+    originalTitle: 'Title',
+    originalLanguage: 'ja',
+    overview: null,
+    posterUrl: null,
+    year: null,
+    isAnimation: false,
+    ...over,
+  };
+}
+
+function details(over: Partial<TmdbTitleDetails> & { tmdbId: number }): TmdbTitleDetails {
+  return {
+    tmdbType: 'tv',
+    titleEnglish: null,
+    titleNative: null,
+    description: null,
+    posterUrl: null,
+    episodesTotal: null,
+    year: null,
+    originalLanguage: 'ja',
+    isAnimation: false,
+    allTitles: [],
+    ...over,
+  };
+}
+
+test('titlesMatch ignores case, width, and punctuation but not extra words', () => {
+  assert.equal(titlesMatch('Hanzawa Naoki', ['HANZAWA　NAOKI!']), true);
+  assert.equal(titlesMatch('半沢直樹', ['半沢直樹']), true);
+  assert.equal(titlesMatch('Hanzawa Naoki', ['Hanzawa Naoki Season 2']), false);
+  assert.equal(titlesMatch('', ['']), false);
+});
+
+test('resolveByTitle only accepts a Japanese non-animated result whose known titles match exactly', async () => {
+  const detailCalls: number[] = [];
+  const client: TmdbClient = {
+    async search() {
+      return [
+        searchResult({ tmdbId: 1, title: 'Hanzawa Naoki', originalLanguage: 'ko' }),
+        searchResult({ tmdbId: 2, title: 'Hanzawa Naoki', isAnimation: true }),
+        searchResult({ tmdbId: 3, title: 'Hanzawa Naoki: The Movie' }),
+        searchResult({ tmdbId: 4, title: 'Hanzawa Naoki' }),
+      ];
+    },
+    async getDetails(_type, tmdbId) {
+      detailCalls.push(tmdbId);
+      if (tmdbId === 3) return details({ tmdbId: 3, allTitles: ['Hanzawa Naoki: The Movie'] });
+      if (tmdbId === 4) return details({ tmdbId: 4, allTitles: ['Hanzawa Naoki', '半沢直樹'] });
+      return null;
+    },
+  };
+  const resolver = createLiveActionMetadataResolver(client, silentLogger);
+
+  const resolved = await resolver.resolveByTitle('hanzawa naoki');
+
+  assert.equal(resolved?.tmdbId, 4);
+  assert.deepEqual(detailCalls, [3, 4]);
+});
+
+test('resolveByTitle returns null when nothing matches or the key is missing', async () => {
+  const noMatch: TmdbClient = {
+    async search() {
+      return [searchResult({ tmdbId: 1, title: 'Something Else' })];
+    },
+    async getDetails() {
+      return details({ tmdbId: 1, allTitles: ['Something Else'] });
+    },
+  };
+  assert.equal(
+    await createLiveActionMetadataResolver(noMatch, silentLogger).resolveByTitle('Hanzawa Naoki'),
+    null,
+  );
+
+  let infoCount = 0;
+  const noKey: TmdbClient = {
+    async search() {
+      throw new TmdbApiKeyMissingError();
+    },
+    async getDetails() {
+      throw new TmdbApiKeyMissingError();
+    },
+  };
+  const resolver = createLiveActionMetadataResolver(noKey, {
+    info: () => {
+      infoCount += 1;
+    },
+    warn: () => {},
+  });
+  assert.equal(await resolver.resolveByTitle('Hanzawa Naoki'), null);
+  assert.equal(await resolver.resolveById('tv', 1), null);
+  assert.equal(infoCount, 1);
+});

src/core/services/tmdb/live-action-resolver.ts

@@ -0,0 +1,75 @@
+import { normalizeTitleIdentity } from '../../utils/title-normalization';
+import type { TmdbMediaType } from '../../../shared/media-kind';
+import { TmdbApiKeyMissingError, type TmdbClient, type TmdbTitleDetails } from './tmdb-client';
+
+const MAX_DETAIL_LOOKUPS = 3;
+
+/**
+ * Resolves live-action titles for the automatic cover-art path. Anime is
+ * AniList's job, so only non-animated Japanese-language results qualify, and
+ * a candidate must match the parsed title exactly under one of the names TMDB
+ * knows for it. Fuzzy search hits are never trusted on their own: a stray
+ * filename would otherwise pin the wrong show to a library entry.
+ */
+export interface LiveActionMetadataResolver {
+  resolveByTitle(title: string): Promise<TmdbTitleDetails | null>;
+  resolveById(tmdbType: TmdbMediaType, tmdbId: number): Promise<TmdbTitleDetails | null>;
+}
+
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+}
+
+export function titlesMatch(candidate: string, knownTitles: Iterable<string>): boolean {
+  const key = normalizeTitleIdentity(candidate);
+  if (!key) return false;
+  for (const known of knownTitles) {
+    if (normalizeTitleIdentity(known) === key) return true;
+  }
+  return false;
+}
+
+export function createLiveActionMetadataResolver(
+  client: TmdbClient,
+  logger: Logger,
+): LiveActionMetadataResolver {
+  let warnedMissingKey = false;
+
+  const guard = async <T>(work: () => Promise<T>): Promise<T | null> => {
+    try {
+      return await work();
+    } catch (err) {
+      if (err instanceof TmdbApiKeyMissingError) {
+        if (!warnedMissingKey) {
+          warnedMissingKey = true;
+          logger.info('tmdb: no API key configured, skipping live-action metadata lookups');
+        }
+        return null;
+      }
+      logger.warn('tmdb: lookup failed: %s', err instanceof Error ? err.message : String(err));
+      return null;
+    }
+  };
+
+  return {
+    resolveByTitle(title) {
+      return guard(async () => {
+        const results = await client.search(title);
+        const candidates = results
+          .filter((result) => result.originalLanguage === 'ja' && !result.isAnimation)
+          .slice(0, MAX_DETAIL_LOOKUPS);
+        for (const candidate of candidates) {
+          const details = await client.getDetails(candidate.tmdbType, candidate.tmdbId);
+          if (details && !details.isAnimation && titlesMatch(title, details.allTitles)) {
+            return details;
+          }
+        }
+        return null;
+      });
+    },
+    resolveById(tmdbType, tmdbId) {
+      return guard(() => client.getDetails(tmdbType, tmdbId));
+    },
+  };
+}

src/core/services/tmdb/tmdb-client.test.ts

@@ -0,0 +1,335 @@
+import assert from 'node:assert/strict';
+import test, { type TestContext } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { TmdbConfig } from '../../../types/integrations';
+import {
+  TmdbApiKeyMissingError,
+  createTmdbClient,
+  createTmdbApiKeyResolver,
+  resolveTmdbApiKey,
+} from './tmdb-client.js';
+
+function commandFixture(t: TestContext) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer tmdb command-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  let nextId = 0;
+  const quotePath = (value: string) =>
+    `"${process.platform === 'win32' ? value : value.replace(/["\\$`]/g, '\\$&')}"`;
+  return {
+    dir,
+    command(source: string): string {
+      const script = path.join(dir, `credential-${nextId++}.cjs`);
+      fs.writeFileSync(script, source);
+      return `${quotePath(process.execPath)} ${quotePath(script)}`;
+    },
+  };
+}
+
+function jsonResponse(payload: unknown, status = 200): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function captureFetch(handler: (url: URL, init?: RequestInit) => Response) {
+  const calls: Array<{ url: URL; init?: RequestInit }> = [];
+  const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = new URL(String(input));
+    calls.push({ url, init });
+    return handler(url, init);
+  }) as typeof fetch;
+  return { calls, fetchImpl };
+}
+
+test('resolveTmdbApiKey prefers the literal key and trims it', async (t) => {
+  const { command } = commandFixture(t);
+  assert.equal(
+    await resolveTmdbApiKey({ apiKey: '  abc  ', apiKeyCommand: command('process.exit(3)') }),
+    'abc',
+  );
+  assert.equal(await resolveTmdbApiKey({ apiKey: '', apiKeyCommand: '' }), null);
+  assert.equal(await resolveTmdbApiKey(undefined), null);
+});
+
+test('resolveTmdbApiKey runs apiKeyCommand when no literal key is set', async (t) => {
+  const { command } = commandFixture(t);
+  assert.equal(
+    await resolveTmdbApiKey({ apiKeyCommand: command('process.stdout.write(" from-cmd ")') }),
+    'from-cmd',
+  );
+  assert.equal(await resolveTmdbApiKey({ apiKeyCommand: command('process.exit(3)') }), null);
+});
+
+test('resolveTmdbApiKey falls back to the bundled key only when the user set nothing usable', async (t) => {
+  const { command } = commandFixture(t);
+  assert.equal(await resolveTmdbApiKey({}, 'bundled'), 'bundled');
+  assert.equal(await resolveTmdbApiKey({ apiKey: 'mine' }, 'bundled'), 'mine');
+  assert.equal(
+    await resolveTmdbApiKey({ apiKeyCommand: command('process.stdout.write("mine")') }, 'bundled'),
+    'mine',
+  );
+  assert.equal(
+    await resolveTmdbApiKey({ apiKeyCommand: command('process.exit(3)') }, 'bundled'),
+    'bundled',
+  );
+});
+
+test('search rejects without a key and never touches the network', async () => {
+  const { calls, fetchImpl } = captureFetch(() => jsonResponse({ results: [] }));
+  const client = createTmdbClient({ resolveApiKey: async () => null, fetch: fetchImpl });
+  await assert.rejects(client.search('半沢直樹'), TmdbApiKeyMissingError);
+  assert.equal(calls.length, 0);
+});
+
+test('search sends a v3 key as a query parameter and drops people from multi results', async () => {
+  const { calls, fetchImpl } = captureFetch(() =>
+    jsonResponse({
+      results: [
+        { media_type: 'person', id: 1, name: 'Sakai Masato' },
+        {
+          media_type: 'tv',
+          id: 61222,
+          name: 'Hanzawa Naoki',
+          original_name: '半沢直樹',
+          original_language: 'ja',
+          overview: 'A banker fights back.',
+          poster_path: '/hanzawa.jpg',
+          first_air_date: '2013-07-07',
+          genre_ids: [18],
+        },
+        {
+          media_type: 'movie',
+          id: 9,
+          title: 'Anime Film',
+          original_title: 'アニメ映画',
+          original_language: 'ja',
+          release_date: '2020-01-01',
+          genre_ids: [16],
+        },
+      ],
+    }),
+  );
+  const client = createTmdbClient({ resolveApiKey: async () => 'v3key', fetch: fetchImpl });
+
+  const results = await client.search(' 半沢直樹 ');
+
+  assert.equal(calls.length, 1);
+  const url = calls[0]!.url;
+  assert.equal(url.pathname, '/3/search/multi');
+  assert.equal(url.searchParams.get('query'), '半沢直樹');
+  assert.equal(url.searchParams.get('api_key'), 'v3key');
+  assert.equal((calls[0]!.init?.headers as Record<string, string>).Authorization, undefined);
+  assert.deepEqual(results, [
+    {
+      tmdbId: 61222,
+      tmdbType: 'tv',
+      title: 'Hanzawa Naoki',
+      originalTitle: '半沢直樹',
+      originalLanguage: 'ja',
+      overview: 'A banker fights back.',
+      posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+      year: 2013,
+      isAnimation: false,
+    },
+    {
+      tmdbId: 9,
+      tmdbType: 'movie',
+      title: 'Anime Film',
+      originalTitle: 'アニメ映画',
+      originalLanguage: 'ja',
+      overview: null,
+      posterUrl: null,
+      year: 2020,
+      isAnimation: true,
+    },
+  ]);
+});
+
+test('a v4 read token travels as a bearer header instead of api_key', async () => {
+  const v4Token = ['eyJ', 'test-header', '.payload', '.sig'].join('');
+  const { calls, fetchImpl } = captureFetch(() => jsonResponse({ results: [] }));
+  const client = createTmdbClient({
+    resolveApiKey: async () => v4Token,
+    fetch: fetchImpl,
+  });
+  await client.search('x');
+  assert.equal(calls[0]!.url.searchParams.has('api_key'), false);
+  assert.equal(
+    (calls[0]!.init?.headers as Record<string, string>).Authorization,
+    `Bearer ${v4Token}`,
+  );
+});
+
+test('getDetails folds translations and alternative titles into the normalized shape', async () => {
+  const { calls, fetchImpl } = captureFetch(() =>
+    jsonResponse({
+      id: 61222,
+      name: 'Hanzawa Naoki',
+      original_name: '半沢直樹',
+      original_language: 'ja',
+      overview: 'A banker fights back.',
+      poster_path: '/hanzawa.jpg',
+      first_air_date: '2013-07-07',
+      number_of_episodes: 10,
+      genres: [{ id: 18, name: 'Drama' }],
+      alternative_titles: { results: [{ iso_3166_1: 'JP', title: 'Hanzawa Naoki Season 1' }] },
+      translations: {
+        translations: [
+          { iso_639_1: 'en', data: { name: 'Hanzawa Naoki', overview: 'A banker fights back.' } },
+          { iso_639_1: 'ja', data: { name: '半沢直樹', overview: '銀行員の物語' } },
+        ],
+      },
+    }),
+  );
+  const client = createTmdbClient({ resolveApiKey: async () => 'k', fetch: fetchImpl });
+
+  const details = await client.getDetails('tv', 61222);
+
+  assert.equal(calls[0]!.url.pathname, '/3/tv/61222');
+  assert.equal(
+    calls[0]!.url.searchParams.get('append_to_response'),
+    'alternative_titles,translations',
+  );
+  assert.deepEqual(details, {
+    tmdbId: 61222,
+    tmdbType: 'tv',
+    titleEnglish: 'Hanzawa Naoki',
+    titleNative: '半沢直樹',
+    description: 'A banker fights back.',
+    posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+    episodesTotal: 10,
+    year: 2013,
+    originalLanguage: 'ja',
+    isAnimation: false,
+    allTitles: ['Hanzawa Naoki', '半沢直樹', 'Hanzawa Naoki Season 1'],
+  });
+});
+
+test('getDetails falls back to the Japanese overview and counts a movie as one episode', async () => {
+  const { fetchImpl } = captureFetch(() =>
+    jsonResponse({
+      id: 5,
+      title: '半沢直樹',
+      original_title: '半沢直樹',
+      original_language: 'ja',
+      overview: '',
+      release_date: '2019-03-01',
+      translations: {
+        translations: [{ iso_639_1: 'ja', data: { title: '半沢直樹', overview: 'あらすじ' } }],
+      },
+    }),
+  );
+  const client = createTmdbClient({ resolveApiKey: async () => 'k', fetch: fetchImpl });
+  const details = await client.getDetails('movie', 5);
+  assert.equal(details?.titleEnglish, null);
+  assert.equal(details?.titleNative, '半沢直樹');
+  assert.equal(details?.description, 'あらすじ');
+  assert.equal(details?.episodesTotal, 1);
+});
+
+test('getDetails returns null for an unknown id', async () => {
+  const { fetchImpl } = captureFetch(() => jsonResponse({ status_message: 'nope' }, 404));
+  const client = createTmdbClient({ resolveApiKey: async () => 'k', fetch: fetchImpl });
+  assert.equal(await client.getDetails('tv', 1), null);
+});
+
+test('client reuses command output across requests and invalidates it when either setting changes', async (t) => {
+  const fixture = commandFixture(t);
+  const counter = path.join(fixture.dir, 'calls');
+  const createCommand = (key: string) =>
+    fixture.command(`
+    const fs = require('node:fs');
+    const path = require('node:path');
+    fs.appendFileSync(path.join(__dirname, 'calls'), 'x');
+    process.stdout.write(${JSON.stringify(key)});
+  `);
+  let config: TmdbConfig = { apiKeyCommand: createCommand('command-key') };
+  const { calls, fetchImpl } = captureFetch(() => jsonResponse({ results: [] }));
+  const client = createTmdbClient({
+    resolveApiKey: createTmdbApiKeyResolver(
+      () => config,
+      () => 'bundled',
+    ),
+    fetch: fetchImpl,
+  });
+  await Promise.all([client.search('a'), client.search('b')]);
+  await client.getDetails('tv', 1);
+  assert.equal(fs.readFileSync(counter, 'utf8'), 'x');
+  assert.ok(calls.every(({ url }) => url.searchParams.get('api_key') === 'command-key'));
+  config = { ...config, apiKey: 'literal' };
+  await client.search('c');
+  assert.equal(calls.at(-1)?.url.searchParams.get('api_key'), 'literal');
+  config = { ...config, apiKey: '' };
+  await client.search('d');
+  assert.equal(fs.readFileSync(counter, 'utf8'), 'xx');
+  config = { apiKeyCommand: createCommand('new-key') };
+  await client.search('e');
+  assert.equal(fs.readFileSync(counter, 'utf8'), 'xxx');
+  assert.equal(calls.at(-1)?.url.searchParams.get('api_key'), 'new-key');
+});
+
+for (const failure of ['error', 'empty'] as const) {
+  test(`${failure} command output uses a bounded cooldown before retrying`, async (t) => {
+    const fixture = commandFixture(t);
+    const counter = path.join(fixture.dir, 'calls');
+    const command = fixture.command(`
+      const fs = require('node:fs');
+      const path = require('node:path');
+      const counter = path.join(__dirname, 'calls');
+      fs.appendFileSync(counter, 'x');
+      if (fs.readFileSync(counter, 'utf8').length === 1) process.exit(${failure === 'error' ? 1 : 0});
+      process.stdout.write('recovered');
+    `);
+    let now = 1000;
+    const originalNow = Date.now;
+    Date.now = () => now;
+    t.after(() => {
+      Date.now = originalNow;
+    });
+    let bundledKey: string | null = 'bundled';
+    const resolve = createTmdbApiKeyResolver(
+      () => ({ apiKeyCommand: command }),
+      () => bundledKey,
+    );
+    assert.deepEqual(await Promise.all([resolve(), resolve()]), ['bundled', 'bundled']);
+    now += 29_999;
+    assert.equal(await resolve(), 'bundled');
+    bundledKey = null;
+    assert.equal(await resolve(), null);
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'x');
+    now += 1;
+    assert.equal(await resolve(), 'recovered');
+    assert.equal(await resolve(), 'recovered');
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'xx');
+  });
+}
+
+for (const setting of ['apiKey', 'apiKeyCommand'] as const) {
+  test(`changing ${setting} clears a failed command cooldown`, async (t) => {
+    const fixture = commandFixture(t);
+    const counter = path.join(fixture.dir, 'calls');
+    const source = `
+      const fs = require('node:fs');
+      const path = require('node:path');
+      fs.appendFileSync(path.join(__dirname, 'calls'), 'x');
+      process.exit(1);
+    `;
+    let config: TmdbConfig = { apiKeyCommand: fixture.command(source) };
+    const resolve = createTmdbApiKeyResolver(
+      () => config,
+      () => 'bundled',
+    );
+    assert.equal(await resolve(), 'bundled');
+    assert.equal(await resolve(), 'bundled');
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'x');
+    config =
+      setting === 'apiKey'
+        ? { ...config, apiKey: ' ' }
+        : { apiKeyCommand: fixture.command(source) };
+    assert.equal(await resolve(), 'bundled');
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'xx');
+  });
+}

src/core/services/tmdb/tmdb-client.ts

@@ -0,0 +1,311 @@
+import * as childProcess from 'node:child_process';
+import type { TmdbMediaType } from '../../../shared/media-kind';
+import type { TmdbConfig } from '../../../types/integrations';
+import type { StatsTmdbSearchResult } from '../../../types/stats-http-contract';
+
+export const TMDB_API_BASE_URL = 'https://api.themoviedb.org/3';
+const TMDB_POSTER_BASE_URL = 'https://image.tmdb.org/t/p/w500';
+const REQUEST_TIMEOUT_MS = 8_000;
+const API_KEY_COMMAND_RETRY_MS = 30_000;
+const ANIMATION_GENRE_ID = 16;
+
+export type TmdbSearchResult = StatsTmdbSearchResult;
+
+export interface TmdbTitleDetails {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+  titleEnglish: string | null;
+  titleNative: string | null;
+  /** English synopsis, falling back to the Japanese one. */
+  description: string | null;
+  posterUrl: string | null;
+  episodesTotal: number | null;
+  year: number | null;
+  originalLanguage: string;
+  isAnimation: boolean;
+  /** Every name TMDB knows for the title, used for exact-title matching. */
+  allTitles: string[];
+}
+
+export interface TmdbClient {
+  search(query: string): Promise<TmdbSearchResult[]>;
+  getDetails(tmdbType: TmdbMediaType, tmdbId: number): Promise<TmdbTitleDetails | null>;
+}
+
+export class TmdbApiKeyMissingError extends Error {
+  constructor() {
+    super('TMDB API key not configured. Set tmdb.apiKey or tmdb.apiKeyCommand.');
+    this.name = 'TmdbApiKeyMissingError';
+  }
+}
+
+export class TmdbRequestError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = 'TmdbRequestError';
+  }
+}
+
+function execCommand(command: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    childProcess.exec(command, { timeout: 10_000 }, (err, stdout) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+/**
+ * Resolves the key in priority order: the user's literal `apiKey`, then the
+ * output of `apiKeyCommand`, then the key bundled into release builds.
+ */
+export async function resolveTmdbApiKey(
+  config: TmdbConfig | undefined,
+  bundledKey: string | null = null,
+): Promise<string | null> {
+  const literal = config?.apiKey?.trim();
+  if (literal) return literal;
+  const command = config?.apiKeyCommand?.trim();
+  if (command) {
+    try {
+      const key = (await execCommand(command)).trim();
+      if (key.length > 0) return key;
+    } catch {
+      /* fall through to the bundled key */
+    }
+  }
+  return bundledKey;
+}
+
+/** Cache successful command output until either credential setting changes. */
+export function createTmdbApiKeyResolver(
+  getConfig: () => TmdbConfig | undefined,
+  getBundledKey: () => string | null = () => null,
+): () => Promise<string | null> {
+  let state:
+    | {
+        apiKey: string | undefined;
+        apiKeyCommand: string | undefined;
+        pending: Promise<string | null> | null;
+        retryAfterMs: number;
+      }
+    | undefined;
+
+  return async () => {
+    const config = getConfig();
+    if (
+      !state ||
+      state.apiKey !== config?.apiKey ||
+      state.apiKeyCommand !== config?.apiKeyCommand
+    ) {
+      state = {
+        apiKey: config?.apiKey,
+        apiKeyCommand: config?.apiKeyCommand,
+        pending: null,
+        retryAfterMs: 0,
+      };
+    }
+    const current = state;
+    const literal = current.apiKey?.trim();
+    if (literal) return literal;
+    if (!current.apiKeyCommand?.trim()) return getBundledKey();
+    if (Date.now() < current.retryAfterMs) return getBundledKey();
+    current.pending ??= resolveTmdbApiKey(current).then((key) => {
+      if (!key) {
+        current.retryAfterMs = Date.now() + API_KEY_COMMAND_RETRY_MS;
+        current.pending = null;
+      }
+      return key;
+    });
+    const key = await current.pending;
+    return key ?? getBundledKey();
+  };
+}
+
+interface RawSearchItem {
+  media_type?: string;
+  id?: number;
+  name?: string;
+  original_name?: string;
+  title?: string;
+  original_title?: string;
+  original_language?: string;
+  overview?: string;
+  poster_path?: string | null;
+  first_air_date?: string;
+  release_date?: string;
+  genre_ids?: number[];
+}
+
+interface RawTranslation {
+  iso_639_1?: string;
+  data?: { name?: string; title?: string; overview?: string };
+}
+
+interface RawDetails extends RawSearchItem {
+  number_of_episodes?: number;
+  genres?: Array<{ id?: number }>;
+  alternative_titles?: { results?: Array<{ title?: string }>; titles?: Array<{ title?: string }> };
+  translations?: { translations?: RawTranslation[] };
+}
+
+function nonEmpty(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function yearOf(date: string | undefined): number | null {
+  const year = Number.parseInt(date?.slice(0, 4) ?? '', 10);
+  return Number.isFinite(year) && year > 0 ? year : null;
+}
+
+function posterUrlOf(path: string | null | undefined): string | null {
+  return path ? `${TMDB_POSTER_BASE_URL}${path}` : null;
+}
+
+function mediaTypeOf(value: unknown): TmdbMediaType | null {
+  return value === 'tv' || value === 'movie' ? value : null;
+}
+
+function normalizeSearchItem(item: RawSearchItem): TmdbSearchResult | null {
+  const tmdbType = mediaTypeOf(item.media_type);
+  if (!tmdbType || typeof item.id !== 'number') return null;
+  const title = nonEmpty(item.name) ?? nonEmpty(item.title);
+  const originalTitle = nonEmpty(item.original_name) ?? nonEmpty(item.original_title) ?? title;
+  if (!title || !originalTitle) return null;
+  return {
+    tmdbId: item.id,
+    tmdbType,
+    title,
+    originalTitle,
+    originalLanguage: item.original_language ?? '',
+    overview: nonEmpty(item.overview),
+    posterUrl: posterUrlOf(item.poster_path),
+    year: yearOf(item.first_air_date ?? item.release_date),
+    isAnimation: (item.genre_ids ?? []).includes(ANIMATION_GENRE_ID),
+  };
+}
+
+function normalizeDetails(tmdbType: TmdbMediaType, raw: RawDetails): TmdbTitleDetails | null {
+  if (typeof raw.id !== 'number') return null;
+  const localizedTitle = nonEmpty(raw.name) ?? nonEmpty(raw.title);
+  const originalTitle = nonEmpty(raw.original_name) ?? nonEmpty(raw.original_title);
+  const originalLanguage = raw.original_language ?? '';
+  const translations = raw.translations?.translations ?? [];
+  const translationFor = (language: string) =>
+    translations.find((entry) => entry.iso_639_1 === language)?.data;
+  const english = translationFor('en');
+  const japanese = translationFor('ja');
+  const englishTitle =
+    nonEmpty(english?.name) ??
+    nonEmpty(english?.title) ??
+    (localizedTitle && localizedTitle !== originalTitle ? localizedTitle : null);
+  const nativeTitle =
+    originalLanguage === 'ja'
+      ? originalTitle
+      : (nonEmpty(japanese?.name) ?? nonEmpty(japanese?.title));
+  const alternativeTitles = [
+    ...(raw.alternative_titles?.results ?? []),
+    ...(raw.alternative_titles?.titles ?? []),
+  ].map((entry) => nonEmpty(entry.title));
+  const translatedTitles = translations.map(
+    (entry) => nonEmpty(entry.data?.name) ?? nonEmpty(entry.data?.title),
+  );
+  const allTitles = [
+    ...new Set(
+      [
+        localizedTitle,
+        originalTitle,
+        englishTitle,
+        nativeTitle,
+        ...translatedTitles,
+        ...alternativeTitles,
+      ].filter((title): title is string => Boolean(title)),
+    ),
+  ];
+  return {
+    tmdbId: raw.id,
+    tmdbType,
+    titleEnglish: englishTitle,
+    titleNative: nativeTitle,
+    description:
+      nonEmpty(raw.overview) ?? nonEmpty(english?.overview) ?? nonEmpty(japanese?.overview),
+    posterUrl: posterUrlOf(raw.poster_path),
+    episodesTotal:
+      tmdbType === 'movie'
+        ? 1
+        : typeof raw.number_of_episodes === 'number' && raw.number_of_episodes > 0
+          ? raw.number_of_episodes
+          : null,
+    year: yearOf(raw.first_air_date ?? raw.release_date),
+    originalLanguage,
+    isAnimation: (raw.genres ?? []).some((genre) => genre.id === ANIMATION_GENRE_ID),
+    allTitles,
+  };
+}
+
+// TMDB issues two kinds of credential: a short v3 key that travels as a query
+// parameter and a long v4 read token (a JWT) that goes in the Authorization
+// header. Users paste whichever the settings page showed them.
+function isV4Token(apiKey: string): boolean {
+  return apiKey.startsWith('eyJ');
+}
+
+export function createTmdbClient(deps: {
+  resolveApiKey: () => Promise<string | null>;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}): TmdbClient {
+  const fetchImpl = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? TMDB_API_BASE_URL).replace(/\/+$/, '');
+
+  async function request<T>(path: string, params: Record<string, string>): Promise<T | null> {
+    const apiKey = await deps.resolveApiKey();
+    if (!apiKey) throw new TmdbApiKeyMissingError();
+    const url = new URL(`${baseUrl}${path}`);
+    for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (isV4Token(apiKey)) {
+      headers.Authorization = `Bearer ${apiKey}`;
+    } else {
+      url.searchParams.set('api_key', apiKey);
+    }
+    const res = await fetchImpl(url, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new TmdbRequestError(
+        `TMDB request failed: ${res.status} ${res.statusText}`,
+        res.status,
+      );
+    }
+    return (await res.json()) as T;
+  }
+
+  return {
+    async search(query) {
+      const trimmed = query.trim();
+      if (!trimmed) return [];
+      const payload = await request<{ results?: RawSearchItem[] }>('/search/multi', {
+        query: trimmed,
+        include_adult: 'false',
+        language: 'en-US',
+        page: '1',
+      });
+      return (payload?.results ?? [])
+        .map(normalizeSearchItem)
+        .filter((item): item is TmdbSearchResult => item !== null);
+    },
+    async getDetails(tmdbType, tmdbId) {
+      const raw = await request<RawDetails>(`/${tmdbType}/${tmdbId}`, {
+        language: 'en-US',
+        append_to_response: 'alternative_titles,translations',
+      });
+      return raw ? normalizeDetails(tmdbType, raw) : null;
+    },
+  };
+}

src/main.ts

@@ -49,10 +49,7 @@ import {
   clearLinuxMpvFullscreenOverlayRefreshTimeouts,
   updateLinuxMpvFullscreenOverlayRefreshBurst,
 } from './main/runtime/linux-mpv-fullscreen-overlay-refresh';
-import {
+import { createLinuxOverlayModeRuntime } from './main/runtime/linux-overlay-mode-runtime';
-  resolveLinuxVisibleOverlayWindowModeAction,
-  type LinuxVisibleOverlayWindowMode,
-} from './main/runtime/linux-visible-overlay-window-mode';
 import { shouldRunLinuxOverlayZOrderKeepAlive } from './main/runtime/linux-overlay-zorder-keepalive';
 import { focusMacOSOverlayWindow } from './main/runtime/macos-overlay-window-focus';
 import { restoreMacOSMpvFocusAfterModalClose } from './main/runtime/macos-modal-focus-handoff';
@@ -430,6 +427,9 @@ import {
 } from './core/services/anilist/anilist-updater';
 import { createCoverArtFetcher } from './core/services/anilist/cover-art-fetcher';
 import { createAnilistRateLimiter } from './core/services/anilist/rate-limiter';
+import { createLiveActionMetadataResolver } from './core/services/tmdb/live-action-resolver';
+import { createTmdbClient, createTmdbApiKeyResolver } from './core/services/tmdb/tmdb-client';
+import { readBundledTmdbApiKey } from './core/services/tmdb/bundled-api-key';
 import { createJellyfinTokenStore } from './core/services/jellyfin-token-store';
 import { applyRuntimeOptionResultRuntime } from './core/services/runtime-options-ipc';
 import { createAnilistTokenStore } from './core/services/anilist/anilist-token-store';
@@ -964,6 +964,8 @@ const reportFatalError = createFatalErrorReporter({
 
 let forceQuitTimer: ReturnType<typeof setTimeout> | null = null;
 const statsDistPath = path.join(__dirname, '..', 'stats', 'dist');
+// Release builds stage a project TMDB key next to the compiled main process.
+const bundledTmdbApiKey = readBundledTmdbApiKey(__dirname);
 const statsPreloadPath = path.join(__dirname, 'preload-stats.js');
 const statsServerRuntime = createStatsServerRuntime({
   userDataPath: USER_DATA_PATH,
@@ -990,6 +992,7 @@ const statsServerRuntime = createStatsServerRuntime({
   },
   getYomitanAnkiDeckName: () => getCurrentYomitanAnkiDeckNameForRuntime(),
   getAnilistRateLimiter: () => anilistRateLimiter,
+  getBundledTmdbApiKey: () => bundledTmdbApiKey,
   resolveAnkiNoteId: (noteId) => appState.ankiIntegration?.resolveCurrentNoteId(noteId) ?? noteId,
   trackDuplicateNoteIdsForNote: (noteId, duplicateNoteIds) => {
     appState.ankiIntegration?.trackDuplicateNoteIdsForNote(noteId, duplicateNoteIds);
@@ -1688,6 +1691,17 @@ const anilistRateLimiter = createAnilistRateLimiter();
 const statsCoverArtFetcher = createCoverArtFetcher(
   anilistRateLimiter,
   createLogger('main:stats-cover-art'),
+  {
+    liveAction: createLiveActionMetadataResolver(
+      createTmdbClient({
+        resolveApiKey: createTmdbApiKeyResolver(
+          () => configService.getConfig().tmdb,
+          () => bundledTmdbApiKey,
+        ),
+      }),
+      createLogger('main:tmdb'),
+    ),
+  },
 );
 const anilistStateRuntime = createAnilistStateRuntime(buildAnilistStateRuntimeMainDepsHandler());
 const configDerivedRuntime = createConfigDerivedRuntime(buildConfigDerivedRuntimeMainDepsHandler());
@@ -1982,11 +1996,27 @@ let lastObservedTimePos = 0;
 let lastObservedPrimarySubtitleTrackId: number | null = null;
 let cancelLinuxMpvFullscreenOverlayRefreshBurst: CancelLinuxMpvFullscreenOverlayRefreshBurst | null =
   null;
-let linuxVisibleOverlayWindowMode: LinuxVisibleOverlayWindowMode = 'managed';
+const linuxOverlayModeRuntime = createLinuxOverlayModeRuntime({
-let linuxTrackedMpvFullscreen = false;
+  isEnabled: shouldRunLinuxOverlayZOrderKeepAlive,
-let linuxTrackedMpvFullscreenChangedAtMs = 0;
+  isVisible: () => overlayManager.getVisibleOverlayVisible(),
-let linuxVisibleOverlayOwnerBindingKey: string | null = null;
+  getWindow: () => overlayManager.getMainWindow(),
-let linuxVisibleOverlayWindowModeSwitchToken = 0;
+  clearWindow: () => overlayManager.setMainWindow(null),
+  createWindow: () => {
+    visibleOverlayInteractionRuntime.resetVisibleOverlayInputState();
+    createMainWindow();
+  },
+  refreshWindow: () => {
+    const trackedGeometry = overlayGeometryRuntime.getCurrentTrackedOverlayGeometry();
+    if (trackedGeometry) overlayManager.setOverlayWindowBounds(trackedGeometry);
+    overlayVisibilityRuntime.updateVisibleOverlayVisibility();
+    void ensureOverlayMpvSubtitlesHidden();
+    if (appState.currentSubText.trim()) {
+      subtitleProcessingController.refreshCurrentSubtitle(appState.currentSubText);
+    }
+  },
+  now: Date.now,
+  logDebug: (message) => logger.debug(message),
+});
 let subtitleSidebarRequestedOpen = false;
 const SEEK_THRESHOLD_SECONDS = 3;
 const EXPLICIT_SEEK_INTENT_TTL_MS = 2000;
@@ -2746,7 +2776,7 @@ const overlayVisibilityRuntime = createOverlayVisibilityRuntimeService(
     },
     hideNonNativeOverlayWhenTargetUnfocused: () =>
       shouldRunLinuxOverlayZOrderKeepAlive() &&
-      linuxVisibleOverlayWindowMode === 'fullscreen-override',
+      linuxOverlayModeRuntime.mode === 'fullscreen-override',
     resolveFallbackBounds: () => {
       const cursorPoint = screen.getCursorScreenPoint();
       const display = screen.getDisplayNearestPoint(cursorPoint);
@@ -2792,9 +2822,9 @@ const visibleOverlayInteractionRuntime = createVisibleOverlayInteractionRuntime(
   getBackendOverride: () => appState.backendOverride,
   getInitialArgs: () => appState.initialArgs,
   getOverlayRuntimeInitialized: () => appState.overlayRuntimeInitialized,
-  getLinuxVisibleOverlayWindowMode: () => linuxVisibleOverlayWindowMode,
+  getLinuxVisibleOverlayWindowMode: () => linuxOverlayModeRuntime.mode,
   setLinuxVisibleOverlayOwnerBindingKey: (key) => {
-    linuxVisibleOverlayOwnerBindingKey = key;
+    linuxOverlayModeRuntime.ownerBindingKey = key;
   },
   bindVisibleOverlayToTrackedX11Window: (window) =>
     overlayGeometryRuntime.bindVisibleOverlayToTrackedX11Window(window),
@@ -2952,7 +2982,8 @@ const mediaTimingReviewRuntime = createMediaTimingReviewRuntime({
       startTime: range.startTime,
       endTime: range.endTime,
     }),
-  openModal: (payload) => openMediaTimingReviewModal(createOverlayHostedModalOpenDeps(), payload),
+  openModal: (payload, signal) =>
+    openMediaTimingReviewModal(createOverlayHostedModalOpenDeps(), payload, signal),
   onPreviewEnded: (reviewId) => {
     // The review may live in either overlay window; the renderer ignores foreign review ids.
     for (const window of [overlayManager.getMainWindow(), overlayManager.getModalWindow()]) {
@@ -3989,6 +4020,7 @@ const {
     clearWindowsVisibleOverlayForegroundPollLoop: () =>
       visibleOverlayInteractionRuntime.clearWindowsVisibleOverlayForegroundPollLoop(),
     clearLinuxMpvFullscreenOverlayRefreshTimeouts: () => {
+      linuxOverlayModeRuntime.cancelPendingTransition();
       cancelLinuxMpvFullscreenOverlayRefreshBurst = null;
       clearLinuxMpvFullscreenOverlayRefreshTimeouts();
     },
@@ -4123,7 +4155,6 @@ const immersionTrackerStartupMainDeps: Parameters<
 
       // Register stats overlay toggle IPC handler (idempotent)
       registerStatsOverlayToggle({
-        staticDir: statsDistPath,
         preloadPath: statsPreloadPath,
         getApiBaseUrl: async () => (await ensureStatsServerStarted()).url,
         onStartupError: (error) =>
@@ -4709,7 +4740,7 @@ const {
           },
           overlayVisibilityRuntime,
           syncVisibleOverlayMpvFullscreenMode: (nextFullscreen) =>
-            syncLinuxVisibleOverlayMpvFullscreenMode(nextFullscreen),
+            linuxOverlayModeRuntime.sync(nextFullscreen),
           getOverlayInteractionActive: () =>
             visibleOverlayInteractionRuntime.getVisibleOverlayInteractionActive() ||
             visibleOverlayInteractionRuntime.getLinuxOverlayInputShapeActive(),
@@ -5021,14 +5052,14 @@ const overlayGeometryRuntime = createOverlayGeometryRuntime({
   getTrackedWindowNativeId: () => appState.windowTracker?.getTargetWindowNativeId?.(),
   getStatsOverlayVisible: () => appState.statsOverlayVisible,
   getOverlayForegroundSeparateWindows: () => getOverlayForegroundSeparateWindows(),
-  getLinuxVisibleOverlayWindowMode: () => linuxVisibleOverlayWindowMode,
+  getLinuxVisibleOverlayWindowMode: () => linuxOverlayModeRuntime.mode,
-  getLinuxTrackedMpvFullscreen: () => linuxTrackedMpvFullscreen,
+  getLinuxTrackedMpvFullscreen: () => linuxOverlayModeRuntime.fullscreen,
-  getLinuxTrackedMpvFullscreenChangedAtMs: () => linuxTrackedMpvFullscreenChangedAtMs,
+  getLinuxTrackedMpvFullscreenChangedAtMs: () => linuxOverlayModeRuntime.fullscreenChangedAtMs,
   syncLinuxVisibleOverlayMpvFullscreenMode: (fullscreen) =>
-    syncLinuxVisibleOverlayMpvFullscreenMode(fullscreen),
+    linuxOverlayModeRuntime.sync(fullscreen),
-  getLinuxVisibleOverlayOwnerBindingKey: () => linuxVisibleOverlayOwnerBindingKey,
+  getLinuxVisibleOverlayOwnerBindingKey: () => linuxOverlayModeRuntime.ownerBindingKey,
   setLinuxVisibleOverlayOwnerBindingKey: (key) => {
-    linuxVisibleOverlayOwnerBindingKey = key;
+    linuxOverlayModeRuntime.ownerBindingKey = key;
   },
   clearVisibleOverlayX11OwnerBinding: (window) =>
     visibleOverlayInteractionRuntime.clearVisibleOverlayX11OwnerBinding(window),
@@ -5113,85 +5144,6 @@ function createMainWindow(): BrowserWindow {
   return window;
 }
 
-function createLinuxVisibleOverlayWindowForCurrentMode(token: number, fullscreen: boolean): void {
-  if (token !== linuxVisibleOverlayWindowModeSwitchToken) {
-    return;
-  }
-  if (!overlayManager.getVisibleOverlayVisible()) {
-    return;
-  }
-  const existingWindow = overlayManager.getMainWindow();
-  if (existingWindow && !existingWindow.isDestroyed()) {
-    return;
-  }
-
-  visibleOverlayInteractionRuntime.resetVisibleOverlayInputState();
-  createMainWindow();
-  const trackedGeometry = overlayGeometryRuntime.getCurrentTrackedOverlayGeometry();
-  if (trackedGeometry) {
-    overlayManager.setOverlayWindowBounds(trackedGeometry);
-  }
-  overlayVisibilityRuntime.updateVisibleOverlayVisibility();
-  void ensureOverlayMpvSubtitlesHidden();
-  if (appState.currentSubText.trim()) {
-    subtitleProcessingController.refreshCurrentSubtitle(appState.currentSubText);
-  }
-  logger.debug(
-    `Switched Linux visible overlay window mode to ${linuxVisibleOverlayWindowMode} for mpv fullscreen=${fullscreen}`,
-  );
-}
-
-function syncLinuxVisibleOverlayMpvFullscreenMode(fullscreen: boolean): void {
-  if (!shouldRunLinuxOverlayZOrderKeepAlive()) {
-    return;
-  }
-  if (linuxTrackedMpvFullscreen !== fullscreen) {
-    linuxTrackedMpvFullscreenChangedAtMs = Date.now();
-  }
-  linuxTrackedMpvFullscreen = fullscreen;
-  const currentWindow = overlayManager.getMainWindow();
-  const hasLiveWindow = Boolean(currentWindow && !currentWindow.isDestroyed());
-  const action = resolveLinuxVisibleOverlayWindowModeAction({
-    currentMode: linuxVisibleOverlayWindowMode,
-    fullscreen,
-    hasLiveWindow,
-    visibleOverlayVisible: overlayManager.getVisibleOverlayVisible(),
-  });
-
-  linuxVisibleOverlayWindowMode = action.nextMode;
-  linuxVisibleOverlayOwnerBindingKey = null;
-  linuxVisibleOverlayWindowModeSwitchToken += 1;
-  const token = linuxVisibleOverlayWindowModeSwitchToken;
-  if (!action.shouldCreateWindow && !action.shouldDestroyCurrentWindow) {
-    return;
-  }
-
-  const previousWindow = currentWindow;
-  if (action.shouldDestroyCurrentWindow && previousWindow && !previousWindow.isDestroyed()) {
-    previousWindow.once('closed', () => {
-      if (overlayManager.getMainWindow() === previousWindow) {
-        overlayManager.setMainWindow(null);
-      }
-      if (action.createWindowTiming === 'after-current-destroyed') {
-        createLinuxVisibleOverlayWindowForCurrentMode(token, fullscreen);
-      }
-    });
-    previousWindow.hide();
-    previousWindow.destroy();
-  }
-
-  if (!action.shouldCreateWindow) {
-    logger.debug(
-      `Recorded Linux visible overlay window mode ${action.nextMode} for hidden mpv fullscreen=${fullscreen}`,
-    );
-    return;
-  }
-
-  if (action.createWindowTiming === 'now') {
-    createLinuxVisibleOverlayWindowForCurrentMode(token, fullscreen);
-  }
-}
-
 function initializeOverlayRuntime(): void {
   initializeOverlayRuntimeHandler();
   if (!(appState.initialArgs && isHeadlessInitialCommand(appState.initialArgs))) {
@@ -5506,7 +5458,6 @@ async function dispatchSessionAction(request: SessionActionDispatchRequest): Pro
   await dispatchSessionActionCore(request, {
     toggleStatsOverlay: async () =>
       await toggleStatsOverlayWindow({
-        staticDir: statsDistPath,
         preloadPath: statsPreloadPath,
         getApiBaseUrl: async () => (await ensureStatsServerStarted()).url,
         onStartupError: (error) =>
@@ -6358,8 +6309,8 @@ const { createMainWindow: createMainWindowHandler, createModalWindow: createModa
       forwardTabToMpv: () => sendMpvCommandRuntime(appState.mpvClient, ['keypress', 'TAB']),
       getLinuxX11FullscreenOverlay: () =>
         shouldRunLinuxOverlayZOrderKeepAlive() &&
-        linuxTrackedMpvFullscreen &&
+        linuxOverlayModeRuntime.fullscreen &&
-        linuxVisibleOverlayWindowMode === 'fullscreen-override',
+        linuxOverlayModeRuntime.mode === 'fullscreen-override',
       onVisibleWindowBlurred: () =>
         visibleOverlayInteractionRuntime.scheduleVisibleOverlayBlurRefresh(),
       onVisibleWindowFocused: () =>

src/main/main-wiring.test.ts

@@ -453,7 +453,7 @@ test('Linux visible overlay recreation clears stale input state before creating
   const source = readMainSource();
   const runtimeSource = readSource('src/main/runtime/visible-overlay-interaction-runtime.ts');
   const actionBlock = source.match(
-    /function createLinuxVisibleOverlayWindowForCurrentMode\([\s\S]*?\): void \{(?<body>[\s\S]*?)\n\}/,
+    /const linuxOverlayModeRuntime = createLinuxOverlayModeRuntime\(\{[\s\S]*?createWindow: \(\) => \{(?<body>[\s\S]*?)\n  \},/,
   )?.groups?.body;
   const resetBlock = runtimeSource.match(
     /function resetVisibleOverlayInputState\(\): void \{(?<body>[\s\S]*?)\n  \}/,
@@ -472,7 +472,7 @@ test('Linux visible overlay recreation clears stale input state before creating
 test('Linux visible overlay recreation avoids display fallback before tracked geometry exists', () => {
   const source = readMainSource();
   const actionBlock = source.match(
-    /function createLinuxVisibleOverlayWindowForCurrentMode\([\s\S]*?\): void \{(?<body>[\s\S]*?)\n\}/,
+    /const linuxOverlayModeRuntime = createLinuxOverlayModeRuntime\(\{[\s\S]*?refreshWindow: \(\) => \{(?<body>[\s\S]*?)\n  \},/,
   )?.groups?.body;
 
   assert.ok(actionBlock);
@@ -480,7 +480,10 @@ test('Linux visible overlay recreation avoids display fallback before tracked ge
     actionBlock,
     /const trackedGeometry = overlayGeometryRuntime\.getCurrentTrackedOverlayGeometry\(\);/,
   );
-  assert.match(actionBlock, /if \(trackedGeometry\) \{/);
+  assert.match(
+    actionBlock,
+    /if \(trackedGeometry\) overlayManager\.setOverlayWindowBounds\(trackedGeometry\);/,
+  );
   assert.match(actionBlock, /overlayManager\.setOverlayWindowBounds\(trackedGeometry\);/);
   assert.doesNotMatch(actionBlock, /setOverlayWindowBounds\(getCurrentOverlayGeometry\(\)\)/);
 });

src/main/runtime/composers/startup-lifecycle-composer.ts

@@ -8,13 +8,10 @@ import {
   createBuildRestoreWindowsOnActivateMainDepsHandler,
   createBuildShouldRestoreWindowsOnActivateMainDepsHandler,
 } from '../app-lifecycle-main-activate';
-import { createBuildRegisterProtocolUrlHandlersMainDepsHandler } from '../protocol-url-handlers-main-deps';
 import { registerProtocolUrlHandlers } from '../protocol-url-handlers';
 import type { ComposerInputs, ComposerOutputs } from './contracts';
 
-type RegisterProtocolUrlHandlersMainDeps = Parameters<
+type RegisterProtocolUrlHandlersMainDeps = Parameters<typeof registerProtocolUrlHandlers>[0];
-  typeof createBuildRegisterProtocolUrlHandlersMainDepsHandler
->[0];
 type OnWillQuitCleanupDeps = Parameters<typeof createBuildOnWillQuitCleanupDepsHandler>[0];
 type ShouldRestoreWindowsOnActivateMainDeps = Parameters<
   typeof createBuildShouldRestoreWindowsOnActivateMainDepsHandler
@@ -40,10 +37,6 @@ export type StartupLifecycleComposerResult = ComposerOutputs<{
 export function composeStartupLifecycleHandlers(
   options: StartupLifecycleComposerOptions,
 ): StartupLifecycleComposerResult {
-  const registerProtocolUrlHandlersMainDeps = createBuildRegisterProtocolUrlHandlersMainDepsHandler(
-    options.registerProtocolUrlHandlersMainDeps,
-  )();
-
   const onWillQuitCleanupHandler = createOnWillQuitCleanupHandler(
     createBuildOnWillQuitCleanupDepsHandler(options.onWillQuitCleanupMainDeps)(),
   );
@@ -58,9 +51,9 @@ export function composeStartupLifecycleHandlers(
 
   return {
     registerProtocolUrlHandlers: () =>
-      registerProtocolUrlHandlers(registerProtocolUrlHandlersMainDeps),
+      registerProtocolUrlHandlers(options.registerProtocolUrlHandlersMainDeps),
-    onWillQuitCleanup: () => onWillQuitCleanupHandler(),
+    onWillQuitCleanup: onWillQuitCleanupHandler,
-    shouldRestoreWindowsOnActivate: () => shouldRestoreWindowsOnActivateHandler(),
+    shouldRestoreWindowsOnActivate: shouldRestoreWindowsOnActivateHandler,
-    restoreWindowsOnActivate: () => restoreWindowsOnActivateHandler(),
+    restoreWindowsOnActivate: restoreWindowsOnActivateHandler,
   };
 }

src/main/runtime/domains/anilist.ts

@@ -13,4 +13,3 @@ export * from '../anilist-state';
 export * from '../anilist-token-refresh';
 export * from '../anilist-token-refresh-main-deps';
 export * from '../protocol-url-handlers';
-export * from '../protocol-url-handlers-main-deps';

src/main/runtime/linux-overlay-mode-runtime.test.ts

@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { test } from 'node:test';
+import { createLinuxOverlayModeRuntime } from './linux-overlay-mode-runtime';
+
+class TestWindow extends EventEmitter {
+  destroyed = false;
+  hidden = false;
+  isDestroyed() {
+    return this.destroyed;
+  }
+  hide() {
+    this.hidden = true;
+  }
+  destroy() {
+    this.destroyed = true;
+  }
+  finishClose() {
+    this.emit('closed');
+  }
+}
+
+function fixture() {
+  const initial = new TestWindow();
+  const state: { window: TestWindow | null; visible: boolean; creates: number; refreshes: number } =
+    {
+      window: initial,
+      visible: true,
+      creates: 0,
+      refreshes: 0,
+    };
+  const runtime = createLinuxOverlayModeRuntime({
+    isEnabled: () => true,
+    isVisible: () => state.visible,
+    getWindow: () => state.window,
+    clearWindow: () => {
+      state.window = null;
+    },
+    createWindow: () => {
+      state.creates += 1;
+      state.window = new TestWindow();
+    },
+    refreshWindow: () => {
+      state.refreshes += 1;
+    },
+    now: () => 42,
+    logDebug: () => {},
+  });
+  return { initial, state, runtime };
+}
+
+test('Linux mode transition waits for close before replacing and refreshing the window', () => {
+  const { initial, state, runtime } = fixture();
+  runtime.ownerBindingKey = 'old-owner';
+  runtime.sync(true);
+  assert.equal(runtime.mode, 'fullscreen-override');
+  assert.equal(runtime.fullscreenChangedAtMs, 42);
+  assert.equal(runtime.ownerBindingKey, null);
+  assert.equal(initial.hidden, true);
+  assert.equal(state.creates, 0);
+  initial.finishClose();
+  assert.equal(state.creates, 1);
+  assert.equal(state.refreshes, 1);
+  runtime.sync(true);
+  assert.equal(state.creates, 1);
+});
+
+test('an older close callback cannot clear or replace a newer overlay', () => {
+  const { initial, state, runtime } = fixture();
+  runtime.sync(true);
+  runtime.sync(false);
+  const replacement = state.window;
+  assert.equal(state.creates, 1);
+  initial.finishClose();
+  assert.equal(state.window, replacement);
+  assert.equal(state.creates, 1);
+  assert.equal(runtime.mode, 'managed');
+});
+
+test('hiding or cancelling a transition prevents delayed window creation', () => {
+  for (const cancel of [false, true]) {
+    const { initial, state, runtime } = fixture();
+    runtime.sync(true);
+    if (cancel) runtime.cancelPendingTransition();
+    else state.visible = false;
+    initial.finishClose();
+    assert.equal(state.creates, 0);
+    assert.equal(state.window, null);
+    state.visible = true;
+    runtime.sync(true);
+    assert.equal(state.creates, 1);
+  }
+});

src/main/runtime/linux-overlay-mode-runtime.ts

@@ -0,0 +1,94 @@
+import type { BrowserWindow } from 'electron';
+import {
+  resolveLinuxVisibleOverlayWindowModeAction,
+  type LinuxVisibleOverlayWindowMode,
+} from './linux-visible-overlay-window-mode';
+
+type OverlayWindow = Pick<BrowserWindow, 'isDestroyed' | 'hide' | 'destroy'> & {
+  once: (event: 'closed', listener: () => void) => unknown;
+};
+
+export function createLinuxOverlayModeRuntime<Window extends OverlayWindow>(deps: {
+  isEnabled: () => boolean;
+  isVisible: () => boolean;
+  getWindow: () => Window | null;
+  clearWindow: () => void;
+  createWindow: () => void;
+  refreshWindow: () => void;
+  now: () => number;
+  logDebug: (message: string) => void;
+}) {
+  let mode: LinuxVisibleOverlayWindowMode = 'managed';
+  let fullscreen = false;
+  let fullscreenChangedAtMs = 0;
+  let ownerBindingKey: string | null = null;
+  let generation = 0;
+
+  function createWindowForMode(token: number, nextFullscreen: boolean): void {
+    if (token !== generation || !deps.isVisible()) return;
+    const existing = deps.getWindow();
+    if (existing && !existing.isDestroyed()) return;
+    deps.createWindow();
+    deps.refreshWindow();
+    deps.logDebug(
+      `Switched Linux visible overlay window mode to ${mode} for mpv fullscreen=${nextFullscreen}`,
+    );
+  }
+
+  function sync(nextFullscreen: boolean): void {
+    if (!deps.isEnabled()) return;
+    if (fullscreen !== nextFullscreen) fullscreenChangedAtMs = deps.now();
+    fullscreen = nextFullscreen;
+    const current = deps.getWindow();
+    const action = resolveLinuxVisibleOverlayWindowModeAction({
+      currentMode: mode,
+      fullscreen,
+      hasLiveWindow: Boolean(current && !current.isDestroyed()),
+      visibleOverlayVisible: deps.isVisible(),
+    });
+    mode = action.nextMode;
+    ownerBindingKey = null;
+    const token = ++generation;
+    if (!action.shouldCreateWindow && !action.shouldDestroyCurrentWindow) return;
+
+    if (action.shouldDestroyCurrentWindow && current && !current.isDestroyed()) {
+      current.once('closed', () => {
+        if (deps.getWindow() === current) deps.clearWindow();
+        if (action.createWindowTiming === 'after-current-destroyed') {
+          createWindowForMode(token, nextFullscreen);
+        }
+      });
+      current.hide();
+      current.destroy();
+    }
+    if (!action.shouldCreateWindow) {
+      deps.logDebug(
+        `Recorded Linux visible overlay window mode ${action.nextMode} for hidden mpv fullscreen=${fullscreen}`,
+      );
+      return;
+    }
+    if (action.createWindowTiming === 'now') createWindowForMode(token, nextFullscreen);
+  }
+
+  return {
+    get mode() {
+      return mode;
+    },
+    get fullscreen() {
+      return fullscreen;
+    },
+    get fullscreenChangedAtMs() {
+      return fullscreenChangedAtMs;
+    },
+    get ownerBindingKey() {
+      return ownerBindingKey;
+    },
+    set ownerBindingKey(key: string | null) {
+      ownerBindingKey = key;
+    },
+    sync,
+    cancelPendingTransition: () => {
+      generation += 1;
+    },
+  };
+}

src/main/runtime/media-timing-review-open.ts

@@ -20,11 +20,13 @@ export async function openMediaTimingReviewModal(
     logWarn: (message: string) => void;
   },
   payload: MediaTimingReviewOpenPayload,
+  signal?: AbortSignal,
 ): Promise<boolean> {
   return await retryOverlayModalOpen(
     { waitForModalOpen: deps.waitForModalOpen, logWarn: deps.logWarn },
     {
       modal: MODAL,
+      signal,
       // The review renderer regularly needs more than the 1.5 s the other modals allow; a
       // premature retry re-sends the payload and reloads the waveform for nothing.
       timeoutMs: 4_000,

src/main/runtime/media-timing-review.test.ts

@@ -8,6 +8,7 @@ import type {
   RemoteMediaWindowSource,
 } from '../../core/services/remote-media-window-cache';
 import type { MediaTimingPreviewSession } from '../../core/services/media-timing-preview';
+import { openMediaTimingReviewModal } from './media-timing-review-open';
 
 type MediaTimingPreviewSessionLike = Pick<MediaTimingPreviewSession, 'start'>;
 import {
@@ -16,6 +17,20 @@ import {
   createMediaTimingReviewRuntime,
 } from './media-timing-review';
 
+function createDeferred<T>() {
+  let settle: ((value: T) => void) | null = null;
+  const promise = new Promise<T>((resolve) => {
+    settle = resolve;
+  });
+  return {
+    promise,
+    resolve(value: T): void {
+      if (!settle) throw new Error('deferred promise is unavailable');
+      settle(value);
+    },
+  };
+}
+
 describe('buildMediaTimingReviewPayload', () => {
   test('starts from the padded range and leaves two seconds to drag on each side', () => {
     const payload = buildMediaTimingReviewPayload(
@@ -764,6 +779,206 @@ test('disposing an open review settles it with original timing and restores play
   ]);
 });
 
+for (const pendingSetup of ['properties', 'video-source'] as const) {
+  test(`disposing pending ${pendingSetup} cancels side effects and permits a fresh review`, async () => {
+    const setupGate = createDeferred<void>();
+    const commands: Array<Array<string | number>> = [];
+    let blockSetup = true;
+    let modalOpenCalls = 0;
+    let previewCreateCalls = 0;
+    let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+    runtime = createMediaTimingReviewRuntime({
+      getMpvClient: () => ({
+        connected: true,
+        currentVideoPath: '/video/show.mkv',
+        requestProperty: async (name) => {
+          if (blockSetup && pendingSetup === 'properties') await setupGate.promise;
+          return name === 'pause' ? false : name === 'duration' ? 100 : null;
+        },
+        send: ({ command }) => commands.push(command),
+      }),
+      resolveVideoSource: async () => {
+        if (blockSetup && pendingSetup === 'video-source') await setupGate.promise;
+        return { path: '/video/show.mkv' };
+      },
+      getCurrentMediaPath: () => '/video/show.mkv',
+      getMpvExecutablePath: () => 'mpv',
+      generateWaveform: async () => [],
+      createPreviewSession: () => {
+        previewCreateCalls += 1;
+        return {
+          start: async () => undefined,
+          play: async () => undefined,
+          stop: async () => undefined,
+          onPlaybackEnded: () => undefined,
+          dispose: () => undefined,
+        };
+      },
+      openModal: async (payload) => {
+        modalOpenCalls += 1;
+        runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+        return true;
+      },
+      showStatus: () => undefined,
+    });
+    const request = {
+      kind: 'word' as const,
+      text: '字幕',
+      startTime: 10,
+      endTime: 12,
+      audioPadding: 0,
+      maxMediaDuration: 30,
+      screenshotEnabled: true,
+    };
+
+    const pending = runtime.requestReview(request);
+    let pendingSettled = false;
+    void pending.finally(() => {
+      pendingSettled = true;
+    });
+    await Promise.resolve();
+    await runtime.dispose();
+
+    assert.equal(pendingSettled, true);
+    assert.deepEqual(await pending, { action: 'use-original' });
+    assert.deepEqual(commands, []);
+    assert.equal(modalOpenCalls, 0);
+    assert.equal(previewCreateCalls, 0);
+
+    setupGate.resolve();
+    await Promise.resolve();
+
+    blockSetup = false;
+    assert.deepEqual(await runtime.requestReview(request), { action: 'use-original' });
+    assert.equal(modalOpenCalls, 1);
+    assert.equal(previewCreateCalls, 1);
+  });
+}
+
+test('disposing during modal acknowledgement prevents the real opener from retrying', async () => {
+  const waiting = createDeferred<void>();
+  const acknowledgement = createDeferred<boolean>();
+  const commands: Array<Array<string | number>> = [];
+  let sendCalls = 0;
+  let previewDisposeCalls = 0;
+  let opening: Promise<boolean> | undefined;
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'pause' ? false : null),
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => {
+        previewDisposeCalls += 1;
+      },
+    }),
+    openModal: (payload, signal) => {
+      opening = openMediaTimingReviewModal(
+        {
+          ensureOverlayStartupPrereqs: () => {},
+          ensureOverlayWindowsReadyForVisibilityActions: () => {},
+          sendToActiveOverlayWindow: () => {
+            sendCalls += 1;
+            return true;
+          },
+          waitForModalOpen: () => {
+            waiting.resolve();
+            return acknowledgement.promise;
+          },
+          logWarn: () => {},
+        },
+        payload,
+        signal,
+      );
+      return opening;
+    },
+    showStatus: () => {},
+  });
+  const pending = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  await waiting.promise;
+  await runtime.dispose();
+  assert.deepEqual(await pending, { action: 'use-original' });
+
+  acknowledgement.resolve(false);
+  assert.equal(await opening, false);
+  assert.equal(sendCalls, 1);
+  assert.equal(previewDisposeCalls, 1);
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+});
+
+test('disposing owns a preview session whose startup is still pending', async () => {
+  const openedPayload = createDeferred<MediaTimingReviewOpenPayload>();
+  const previewStarted = createDeferred<void>();
+  const previewStartGate = createDeferred<void>();
+  let previewDisposeCalls = 0;
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => {
+        previewStarted.resolve();
+        await previewStartGate.promise;
+      },
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => {
+        previewDisposeCalls += 1;
+      },
+    }),
+    openModal: async (payload) => {
+      openedPayload.resolve(payload);
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  const pending = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  await openedPayload.promise;
+  await previewStarted.promise;
+
+  await runtime.dispose();
+  assert.deepEqual(await pending, { action: 'use-original' });
+  assert.equal(previewDisposeCalls, 0);
+
+  previewStartGate.resolve();
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  assert.equal(previewDisposeCalls, 1);
+});
+
 test('media timing review forwards the hidden player finishing a preview to the modal', async () => {
   const endedReviewIds: string[] = [];
   const playback: { ended?: () => void } = {};

src/main/runtime/media-timing-review.ts

@@ -78,6 +78,15 @@ interface ActiveReview {
   resolve: (decision: MediaTimingReviewDecision) => void;
 }
 
+interface ReviewRequestLifecycle {
+  signal: AbortSignal;
+  cancelled: Promise<void>;
+  settled: Promise<void>;
+  isCancelled(): boolean;
+  cancel(): void;
+  markSettled(): void;
+}
+
 export interface MediaTimingReviewRuntimeDeps {
   getMpvClient: () => ReviewMpvClient | null;
   getCurrentMediaPath: () => string | null;
@@ -101,7 +110,7 @@ export interface MediaTimingReviewRuntimeDeps {
     next: MediaTimingReviewContextLine[];
   };
   decisionTimeoutMs?: number;
-  openModal: (payload: MediaTimingReviewOpenPayload) => Promise<boolean>;
+  openModal: (payload: MediaTimingReviewOpenPayload, signal: AbortSignal) => Promise<boolean>;
   /** Tells the modal that the hidden player finished the previewed clip. */
   onPreviewEnded?: (reviewId: string) => void;
   showStatus: (message: string) => void;
@@ -118,6 +127,33 @@ function booleanProperty(value: unknown): boolean | null {
   return null;
 }
 
+function createReviewRequestLifecycle(): ReviewRequestLifecycle {
+  const controller = new AbortController();
+  let resolveCancellation: (() => void) | null = null;
+  let resolveSettled: (() => void) | null = null;
+  const cancellation = new Promise<void>((resolve) => {
+    resolveCancellation = resolve;
+  });
+  const settled = new Promise<void>((resolve) => {
+    resolveSettled = resolve;
+  });
+  return {
+    signal: controller.signal,
+    cancelled: cancellation,
+    settled,
+    isCancelled: () => controller.signal.aborted,
+    cancel: () => {
+      if (controller.signal.aborted) return;
+      controller.abort();
+      resolveCancellation?.();
+    },
+    markSettled: () => {
+      resolveSettled?.();
+      resolveSettled = null;
+    },
+  };
+}
+
 /**
  * Picks the subtitle lines adjacent to the mined range that the review modal can pull
  * onto the card. Parsed cues cover both directions; when none are loaded (e.g. the
@@ -245,7 +281,7 @@ export function buildMediaTimingReviewPayload(
 
 export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDeps) {
   let active: ActiveReview | null = null;
-  let reviewInProgress = false;
+  let currentRequest: ReviewRequestLifecycle | null = null;
   let pendingPauseRestore: ReviewMpvClient | null = null;
 
   function restorePendingPlayback(): void {
@@ -311,14 +347,12 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
 
     const previous = review.preview;
     const session = deps.createPreviewSession();
-    session.onPlaybackEnded(() => {
-      if (active === review && review.preview?.session === started) {
-        deps.onPreviewEnded?.(review.payload.reviewId);
-      }
-    });
     const { audioTrackId, ...previewOptions } = review.previewOptions;
-    const started = session
+    const startSession = async (): Promise<PreviewSession> => {
-      .start({
+      if (active !== review) {
+        throw new Error('This timing review is no longer active.');
+      }
+      await session.start({
         mediaPath,
         ...previewOptions,
         // A cached window keeps one audio stream, so mpv's track id from the source no longer applies.
@@ -327,19 +361,30 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
           : audioTrackId !== undefined
             ? { audioTrackId }
             : {}),
-      })
+      });
-      .then(() => session)
+      return session;
-      .catch((error) => {
+    };
+    const started = Promise.resolve()
+      .then(startSession)
+      .catch((error: unknown) => {
         session.dispose();
         throw error;
       });
     review.preview = { path: mediaPath, session: started };
+    session.onPlaybackEnded(() => {
+      if (active === review && review.preview?.session === started) {
+        deps.onPreviewEnded?.(review.payload.reviewId);
+      }
+    });
     void started.catch(() => {});
     if (previous) void previous.session.then((old) => old.dispose()).catch(() => {});
     return started;
   }
 
-  async function runReview(request: MediaTimingReviewRequest): Promise<MediaTimingReviewDecision> {
+  async function runReview(
+    request: MediaTimingReviewRequest,
+    lifecycle: ReviewRequestLifecycle,
+  ): Promise<MediaTimingReviewDecision> {
     const mpvClient = deps.getMpvClient();
     const mediaPath =
       deps.getCurrentMediaPath()?.trim() || mpvClient?.currentVideoPath?.trim() || '';
@@ -348,18 +393,30 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
       return { action: 'use-original' };
     }
 
+    const setupPromise = Promise.all([
+      mpvClient.requestProperty?.('pause').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('duration').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('aid').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('volume').catch(() => null) ?? null,
+      deps.resolveMediaSource?.().catch(() => null) ?? null,
+      request.screenshotEnabled ? (deps.resolveVideoSource?.().catch(() => null) ?? null) : null,
+    ]);
+    const setup = await Promise.race([
+      setupPromise.then((values) => ({ kind: 'ready' as const, values })),
+      lifecycle.cancelled.then(() => ({ kind: 'cancelled' as const })),
+    ]);
+    if (setup.kind === 'cancelled' || lifecycle.isCancelled()) {
+      return { action: 'use-original' };
+    }
     const [pauseRaw, durationRaw, audioTrackRaw, volumeRaw, resolvedSource, videoSource] =
-      await Promise.all([
+      setup.values;
-        mpvClient.requestProperty?.('pause').catch(() => null) ?? null,
-        mpvClient.requestProperty?.('duration').catch(() => null) ?? null,
-        mpvClient.requestProperty?.('aid').catch(() => null) ?? null,
-        mpvClient.requestProperty?.('volume').catch(() => null) ?? null,
-        deps.resolveMediaSource?.().catch(() => null) ?? null,
-        request.screenshotEnabled ? (deps.resolveVideoSource?.().catch(() => null) ?? null) : null,
-      ]);
     const pauseState = booleanProperty(pauseRaw);
-    mpvClient.send({ command: ['set_property', 'pause', 'yes'] });
     pendingPauseRestore = pauseState === false ? mpvClient : null;
+    mpvClient.send({ command: ['set_property', 'pause', 'yes'] });
+    if (lifecycle.isCancelled()) {
+      restorePendingPlayback();
+      return { action: 'use-original' };
+    }
 
     let contextLines: ReturnType<NonNullable<typeof deps.getSubtitleContextLines>> | undefined;
     try {
@@ -423,9 +480,22 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
       endTime: payload.timelineEndTime,
     }).catch(() => {});
 
-    const opened = await deps.openModal(payload).catch(() => false);
+    if (lifecycle.isCancelled() || active !== review) {
+      await cleanupActiveReview(review);
+      return { action: 'use-original' };
+    }
+    const openModal = deps.openModal(payload, lifecycle.signal).catch(() => false);
+    const openResult = await Promise.race([
+      openModal.then((opened) => ({ kind: 'opened' as const, opened })),
+      lifecycle.cancelled.then(() => ({ kind: 'cancelled' as const })),
+    ]);
+    if (openResult.kind === 'cancelled' || lifecycle.isCancelled() || active !== review) {
+      await cleanupActiveReview(review);
+      return { action: 'use-original' };
+    }
+    const { opened } = openResult;
     if (!opened) {
-      await cleanupActiveReview();
+      await cleanupActiveReview(review);
       deps.showStatus('Timing review could not open. Using the original subtitle timing.');
       return { action: 'use-original' };
     }
@@ -434,33 +504,43 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
       () => resolveDecision({ action: 'use-original' }),
       Math.max(0, deps.decisionTimeoutMs ?? REVIEW_DECISION_TIMEOUT_MS),
     );
-    let decision: MediaTimingReviewDecision;
+    let decision: MediaTimingReviewDecision = { action: 'use-original' };
     try {
-      decision = await decisionPromise;
+      const decisionResult = await Promise.race([
+        decisionPromise.then((value) => ({ kind: 'decided' as const, value })),
+        lifecycle.cancelled.then(() => ({ kind: 'cancelled' as const })),
+      ]);
+      if (decisionResult.kind === 'decided') {
+        decision = decisionResult.value;
+      }
     } finally {
       clearTimeout(decisionWatchdog);
     }
-    await cleanupActiveReview();
+    await cleanupActiveReview(review);
     return decision;
   }
 
   async function requestReview(
     request: MediaTimingReviewRequest,
   ): Promise<MediaTimingReviewDecision> {
-    if (active || reviewInProgress) {
+    if (active || currentRequest) {
       deps.showStatus('Finish the current timing review before mining another card.');
       return { action: 'use-original' };
     }
-    reviewInProgress = true;
+    const lifecycle = createReviewRequestLifecycle();
+    currentRequest = lifecycle;
     try {
-      return await runReview(request);
+      return await runReview(request, lifecycle);
     } catch {
       await cleanupActiveReview();
       restorePendingPlayback();
       deps.showStatus('Timing review failed. Using the original subtitle timing.');
       return { action: 'use-original' };
     } finally {
-      reviewInProgress = false;
+      if (currentRequest === lifecycle) {
+        currentRequest = null;
+      }
+      lifecycle.markSettled();
     }
   }
 
@@ -603,9 +683,18 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
     }
     try {
       const previewSession = current.preview ? await current.preview.session : null;
+      if (active !== current) {
+        return staleReviewResult();
+      }
       await previewSession?.stop();
+      if (active !== current) {
+        return staleReviewResult();
+      }
       return { ok: true };
     } catch (error) {
+      if (active !== current) {
+        return staleReviewResult();
+      }
       return {
         ok: false,
         message: `Could not stop preview: ${error instanceof Error ? error.message : String(error)}`,
@@ -641,8 +730,9 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
     return { ok: true };
   }
 
-  async function cleanupActiveReview(): Promise<void> {
+  async function cleanupActiveReview(expected?: ActiveReview): Promise<void> {
     const current = active;
+    if (expected && current !== expected) return;
     active = null;
     if (!current) return;
     deps.clearFrameCache?.();
@@ -653,9 +743,12 @@ export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDep
   }
 
   async function dispose(): Promise<void> {
+    const request = currentRequest;
+    request?.cancel();
     active?.resolve({ action: 'use-original' });
     await cleanupActiveReview();
     restorePendingPlayback();
+    await request?.settled;
   }
 
   return {

src/main/runtime/overlay-hosted-modal-open.test.ts

@@ -1,6 +1,77 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { openOverlayHostedModal } from './overlay-hosted-modal-open';
+import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
+
+test('retryOverlayModalOpen skips the first send when already aborted', async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const unexpectedCall = () => assert.fail('aborted open must not send or wait');
+  assert.equal(
+    await retryOverlayModalOpen(
+      { waitForModalOpen: unexpectedCall, logWarn: unexpectedCall },
+      {
+        modal: 'media-timing-review',
+        timeoutMs: 4_000,
+        retryWarning: 'retry',
+        sendOpen: unexpectedCall,
+        signal: controller.signal,
+      },
+    ),
+    false,
+  );
+});
+
+for (const abortOnWait of [1, 2]) {
+  test(`retryOverlayModalOpen rejects an acknowledgement aborted during wait ${abortOnWait}`, async () => {
+    const controller = new AbortController();
+    let waitCalls = 0;
+    let sendCalls = 0;
+    const opened = await retryOverlayModalOpen(
+      {
+        waitForModalOpen: async () => {
+          waitCalls += 1;
+          if (waitCalls === abortOnWait) {
+            controller.abort();
+            return true;
+          }
+          return false;
+        },
+        logWarn: () => {},
+      },
+      {
+        modal: 'media-timing-review',
+        timeoutMs: 4_000,
+        retryWarning: 'retry',
+        sendOpen: () => {
+          sendCalls += 1;
+          return true;
+        },
+        signal: controller.signal,
+      },
+    );
+    assert.equal(opened, false);
+    assert.equal(sendCalls, abortOnWait);
+    assert.equal(waitCalls, abortOnWait);
+  });
+}
+
+test('retryOverlayModalOpen still retries other modals without a signal', async () => {
+  let sendCalls = 0;
+  const opened = await retryOverlayModalOpen(
+    { waitForModalOpen: async () => sendCalls === 2, logWarn: () => {} },
+    {
+      modal: 'runtime-options',
+      timeoutMs: 1_500,
+      retryWarning: 'retry',
+      sendOpen: () => {
+        sendCalls += 1;
+        return true;
+      },
+    },
+  );
+  assert.equal(opened, true);
+  assert.equal(sendCalls, 2);
+});
 
 test('openOverlayHostedModal ensures overlay readiness before sending the open event', () => {
   const calls: string[] = [];

src/main/runtime/overlay-hosted-modal-open.ts

@@ -38,20 +38,24 @@ export async function retryOverlayModalOpen(
     timeoutMs: number;
     retryWarning: string;
     sendOpen: () => boolean;
+    signal?: AbortSignal;
   },
 ): Promise<boolean> {
-  if (!input.sendOpen()) {
+  if (input.signal?.aborted || !input.sendOpen()) {
     return false;
   }
 
-  if (await deps.waitForModalOpen(input.modal, input.timeoutMs)) {
+  const opened = await deps.waitForModalOpen(input.modal, input.timeoutMs);
+  if (input.signal?.aborted) return false;
+  if (opened) {
     return true;
   }
 
   deps.logWarn(input.retryWarning);
-  if (!input.sendOpen()) {
+  if (input.signal?.aborted || !input.sendOpen()) {
     return false;
   }
 
-  return await deps.waitForModalOpen(input.modal, input.timeoutMs);
+  const retryOpened = await deps.waitForModalOpen(input.modal, input.timeoutMs);
+  return !input.signal?.aborted && retryOpened;
 }

src/main/runtime/protocol-url-handlers-main-deps.test.ts

@@ -1,29 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-import { createBuildRegisterProtocolUrlHandlersMainDepsHandler } from './protocol-url-handlers-main-deps';
-
-test('protocol url handlers main deps builder maps callbacks', () => {
-  const calls: string[] = [];
-  const deps = createBuildRegisterProtocolUrlHandlersMainDepsHandler({
-    registerOpenUrl: () => calls.push('open-register'),
-    registerSecondInstance: () => calls.push('second-register'),
-    handleAnilistSetupProtocolUrl: () => true,
-    findAnilistSetupDeepLinkArgvUrl: () => 'subminer://anilist-setup',
-    logUnhandledOpenUrl: (rawUrl) => calls.push(`open:${rawUrl}`),
-    logUnhandledSecondInstanceUrl: (rawUrl) => calls.push(`second:${rawUrl}`),
-  })();
-
-  deps.registerOpenUrl(() => {});
-  deps.registerSecondInstance(() => {});
-  assert.equal(deps.handleAnilistSetupProtocolUrl('subminer://anilist-setup'), true);
-  assert.equal(deps.findAnilistSetupDeepLinkArgvUrl(['x']), 'subminer://anilist-setup');
-  deps.logUnhandledOpenUrl('subminer://noop');
-  deps.logUnhandledSecondInstanceUrl('subminer://noop');
-
-  assert.deepEqual(calls, [
-    'open-register',
-    'second-register',
-    'open:subminer://noop',
-    'second:subminer://noop',
-  ]);
-});

src/main/runtime/protocol-url-handlers-main-deps.ts

@@ -1,16 +0,0 @@
-import type { registerProtocolUrlHandlers } from './protocol-url-handlers';
-
-type RegisterProtocolUrlHandlersMainDeps = Parameters<typeof registerProtocolUrlHandlers>[0];
-
-export function createBuildRegisterProtocolUrlHandlersMainDepsHandler(
-  deps: RegisterProtocolUrlHandlersMainDeps,
-) {
-  return (): RegisterProtocolUrlHandlersMainDeps => ({
-    registerOpenUrl: (listener) => deps.registerOpenUrl(listener),
-    registerSecondInstance: (listener) => deps.registerSecondInstance(listener),
-    handleAnilistSetupProtocolUrl: (rawUrl: string) => deps.handleAnilistSetupProtocolUrl(rawUrl),
-    findAnilistSetupDeepLinkArgvUrl: (argv: string[]) => deps.findAnilistSetupDeepLinkArgvUrl(argv),
-    logUnhandledOpenUrl: (rawUrl: string) => deps.logUnhandledOpenUrl(rawUrl),
-    logUnhandledSecondInstanceUrl: (rawUrl: string) => deps.logUnhandledSecondInstanceUrl(rawUrl),
-  });
-}

src/main/runtime/stats-server-runtime.ts

@@ -5,6 +5,7 @@ import {
   syncYomitanDefaultAnkiServer as syncYomitanDefaultAnkiServerCore,
 } from '../../core/services';
 import { startStatsServer, type StatsServer } from '../../core/services/stats-server';
+import { createTmdbClient, createTmdbApiKeyResolver } from '../../core/services/tmdb/tmdb-client';
 import { createLogger } from '../../logger';
 import type { ResolvedConfig } from '../../types/config';
 import type { AppState } from '../state';
@@ -46,6 +47,8 @@ export interface StatsServerRuntimeDeps {
   getAnilistRateLimiter: () => NonNullable<
     Parameters<typeof startStatsServer>[0]['anilistRateLimiter']
   >;
+  /** Project TMDB key staged into release builds; null for source builds. */
+  getBundledTmdbApiKey?: () => string | null;
   resolveAnkiNoteId: (noteId: number) => number;
   trackDuplicateNoteIdsForNote: (noteId: number, duplicateNoteIds: number[]) => void;
   resolveSentenceSearchHeadwords: (term: string) => Promise<string[]>;
@@ -155,6 +158,12 @@ export function createStatsServerRuntime(deps: StatsServerRuntimeDeps): {
         deps.getResolvedConfig().secondarySub.secondarySubLanguages,
       getStatsMiningAlassPath: () => deps.getResolvedConfig().subsync.alass_path,
       anilistRateLimiter: deps.getAnilistRateLimiter(),
+      tmdbClient: createTmdbClient({
+        resolveApiKey: createTmdbApiKeyResolver(
+          () => deps.getResolvedConfig().tmdb,
+          () => deps.getBundledTmdbApiKey?.() ?? null,
+        ),
+      }),
       resolveAnkiNoteId: (noteId: number) => deps.resolveAnkiNoteId(noteId),
       resolveSentenceSearchHeadwords: (term: string) => deps.resolveSentenceSearchHeadwords(term),
       addYomitanNote: async (word: string) => {

src/prerelease-workflow.test.ts

@@ -125,18 +125,21 @@ test('prerelease workflow builds and uploads all release platforms', () => {
   assert.ok(executableRunLines(publish).includes('release/package-size-*.json'));
 });
 
-test('release callers pass only the declared macOS signing secrets to packaging', () => {
+test('release callers pass only the declared packaging secrets', () => {
-  const secrets = [
+  const signingSecrets = [
     'CSC_LINK',
     'CSC_KEY_PASSWORD',
     'APPLE_ID',
     'APPLE_APP_SPECIFIC_PASSWORD',
     'APPLE_TEAM_ID',
   ];
-  assert.deepEqual(
+  // The bundled TMDB key is optional: artifacts stay valid without it and
-    parsedPackageWorkflow.on?.workflow_call?.secrets,
+  // users fall back to their own tmdb.apiKey.
-    Object.fromEntries(secrets.map((name) => [name, { required: true }])),
+  const optionalSecrets = ['SUBMINER_TMDB_API_KEY'];
-  );
+  assert.deepEqual(parsedPackageWorkflow.on?.workflow_call?.secrets, {
+    ...Object.fromEntries(signingSecrets.map((name) => [name, { required: true }])),
+    ...Object.fromEntries(optionalSecrets.map((name) => [name, { required: false }])),
+  });
   for (const workflow of [
     parsedPrereleaseWorkflow,
     readWorkflow(resolve(__dirname, '../.github/workflows/release.yml')),
@@ -144,7 +147,12 @@ test('release callers pass only the declared macOS signing secrets to packaging'
     assert.equal(workflow.jobs?.package?.uses, './.github/workflows/package-release.yml');
     assert.deepEqual(
       workflow.jobs?.package?.secrets,
-      Object.fromEntries(secrets.map((name) => [name, '${{ secrets.' + name + ' }}'])),
+      Object.fromEntries(
+        [...signingSecrets, ...optionalSecrets].map((name) => [
+          name,
+          '${{ secrets.' + name + ' }}',
+        ]),
+      ),
     );
   }
 });

src/shared/media-kind.ts

@@ -1,3 +1,37 @@
-export const MEDIA_KINDS = ['anime', 'youtube'] as const;
+/**
-
+ * Library entry classification shared by the tracker, the stats HTTP layer and
+ * the stats SPA. Anime entries link to AniList, live-action entries link to
+ * TMDB, and YouTube entries are channels grouping tracked videos.
+ */
+export const MEDIA_KINDS = ['anime', 'live_action', 'youtube'] as const;
 export type MediaKind = (typeof MEDIA_KINDS)[number];
+
+export const TMDB_MEDIA_TYPES = ['tv', 'movie'] as const;
+export type TmdbMediaType = (typeof TMDB_MEDIA_TYPES)[number];
+
+export function isMediaKind(value: unknown): value is MediaKind {
+  return typeof value === 'string' && (MEDIA_KINDS as readonly string[]).includes(value);
+}
+
+export function isTmdbMediaType(value: unknown): value is TmdbMediaType {
+  return typeof value === 'string' && (TMDB_MEDIA_TYPES as readonly string[]).includes(value);
+}
+
+/**
+ * Anime and live-action entries share one title namespace: both come from the
+ * filename/Jellyfin parser and an entry switches between them when it is
+ * relinked from AniList to TMDB or back. YouTube channels are a separate
+ * namespace, so a channel never combines with a series entry and a same-named
+ * anime and channel stay separate.
+ */
+export function shareTitleNamespace(a: MediaKind, b: MediaKind): boolean {
+  return (a === 'youtube') === (b === 'youtube');
+}
+
+/**
+ * SQL predicate matching rows in the same title namespace as the bound kind
+ * parameter (the SQL twin of `shareTitleNamespace`).
+ */
+export function sameTitleNamespaceSql(column = 'media_kind'): string {
+  return `(${column} = 'youtube') = (? = 'youtube')`;
+}

src/stats-daemon-runner.ts

@@ -7,6 +7,9 @@ import { createLogger, setLogLevel } from './logger';
 import { ImmersionTrackerService } from './core/services/immersion-tracker-service';
 import { createCoverArtFetcher } from './core/services/anilist/cover-art-fetcher';
 import { createAnilistRateLimiter } from './core/services/anilist/rate-limiter';
+import { createLiveActionMetadataResolver } from './core/services/tmdb/live-action-resolver';
+import { createTmdbClient, createTmdbApiKeyResolver } from './core/services/tmdb/tmdb-client';
+import { readBundledTmdbApiKey } from './core/services/tmdb/bundled-api-key';
 import { startStatsServer } from './core/services/stats-server';
 import {
   removeBackgroundStatsServerState,
@@ -124,6 +127,7 @@ const daemonUserDataPath = userDataPath;
 const statePath = path.join(userDataPath, 'stats-daemon.json');
 const knownWordCachePath = path.join(userDataPath, 'known-words-cache.json');
 const statsDistPath = path.join(__dirname, '..', 'stats', 'dist');
+const bundledTmdbApiKey = readBundledTmdbApiKey(__dirname);
 const wordHelperScriptPath = path.join(__dirname, 'stats-word-helper.js');
 
 let tracker: ImmersionTrackerService | null = null;
@@ -202,8 +206,16 @@ async function main(): Promise<void> {
         },
       },
     });
+    const tmdbClient = createTmdbClient({
+      resolveApiKey: createTmdbApiKeyResolver(
+        () => configService.reloadConfig().tmdb,
+        () => bundledTmdbApiKey,
+      ),
+    });
     tracker.setCoverArtFetcher(
-      createCoverArtFetcher(createAnilistRateLimiter(), createLogger('stats-daemon:cover-art')),
+      createCoverArtFetcher(createAnilistRateLimiter(), createLogger('stats-daemon:cover-art'), {
+        liveAction: createLiveActionMetadataResolver(tmdbClient, createLogger('stats-daemon:tmdb')),
+      }),
     );
 
     statsServer = await startStatsServer({
@@ -212,6 +224,7 @@ async function main(): Promise<void> {
       tracker,
       knownWordCachePath,
       getAnkiConnectConfig: () => configService.reloadConfig().ankiConnect,
+      tmdbClient,
       getYomitanAnkiDeckName: async () =>
         await readStatsYomitanDeckName({
           helperScriptPath: wordHelperScriptPath,

src/types/config.ts

@@ -12,6 +12,7 @@ import type {
   ImmersionTrackingRetentionMode,
   ImmersionTrackingRetentionPreset,
   TsukihimeConfig,
+  TmdbConfig,
   JellyfinConfig,
   JimakuConfig,
   JimakuLanguagePreference,
@@ -160,6 +161,7 @@ export interface Config {
   /** @deprecated Use tsukihime. */
   animetosho?: TsukihimeConfig;
   tsukihime?: TsukihimeConfig;
+  tmdb?: TmdbConfig;
   anilist?: AnilistConfig;
   yomitan?: YomitanConfig;
   jellyfin?: JellyfinConfig;
@@ -333,6 +335,10 @@ export interface ResolvedConfig {
     apiBaseUrl: string;
     maxSearchResults: number;
   };
+  tmdb: {
+    apiKey: string;
+    apiKeyCommand: string;
+  };
   anilist: {
     enabled: boolean;
     accessToken: string;

src/types/integrations.ts

@@ -287,3 +287,9 @@ export interface TsukihimeConfig {
   apiBaseUrl?: string;
   maxSearchResults?: number;
 }
+
+/** TMDB (The Movie Database) access for live-action drama and movie metadata. */
+export interface TmdbConfig {
+  apiKey?: string;
+  apiKeyCommand?: string;
+}

src/types/stats-http-contract.ts

@@ -27,6 +27,7 @@ import type {
   WatchTimePerAnime,
   WordDetailData,
 } from './stats-wire';
+import type { TmdbMediaType } from '../shared/media-kind';
 
 export type StatsTrendRange = '7d' | '30d' | '90d' | '365d' | 'all';
 export type StatsTrendGroupBy = 'day' | 'month';
@@ -78,6 +79,25 @@ export interface StatsAnilistSearchResult {
   title: { romaji: string | null; english: string | null; native: string | null } | null;
 }
 
+export interface StatsTmdbSearchResult {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+  /** English title when TMDB has one, otherwise the original title. */
+  title: string;
+  originalTitle: string;
+  originalLanguage: string;
+  overview: string | null;
+  posterUrl: string | null;
+  year: number | null;
+  /** True when TMDB tags the title with the Animation genre. */
+  isAnimation: boolean;
+}
+
+export interface StatsTmdbAssignment {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+}
+
 export interface StatsAnilistAssignment {
   anilistId: number;
   titleRomaji?: string | null;
@@ -209,11 +229,13 @@ export interface StatsJsonResponseMap {
   moveVideoToAnime: StatsMoveVideoResponse;
   dismissAnimeMergeRecommendation: StatsOkResponse;
   anilistSearch: StatsAnilistSearchResult[];
+  tmdbSearch: StatsTmdbSearchResult[];
   knownWords: string[];
   knownWordsSummary: StatsKnownWordsSummary;
   animeKnownWordsSummary: StatsKnownWordsSummary;
   mediaKnownWordsSummary: StatsKnownWordsSummary;
   reassignAnimeAnilist: StatsOkResponse;
+  reassignAnimeTmdb: StatsOkResponse;
   coverImages: StatsCoverImagesData;
   episodeDetail: EpisodeDetailData;
   ankiBrowse: StatsAnkiBrowseResponse;
@@ -302,6 +324,8 @@ export interface StatsHttpClient {
   getMediaKnownWordsSummary: (videoId: number) => Promise<StatsKnownWordsSummary>;
   searchAnilist: (query: string) => Promise<StatsAnilistSearchResult[]>;
   reassignAnimeAnilist: (animeId: number, info: StatsAnilistAssignment) => Promise<void>;
+  searchTmdb: (query: string) => Promise<StatsTmdbSearchResult[]>;
+  reassignAnimeTmdb: (animeId: number, info: StatsTmdbAssignment) => Promise<void>;
   mineCard: (params: StatsMineCardParams) => Promise<StatsMineCardResponse>;
   ankiBrowse: (noteId: number) => Promise<void>;
   ankiNotesInfo: (noteIds: number[]) => Promise<StatsAnkiNoteInfo[]>;

src/types/stats-wire.ts

@@ -1,4 +1,5 @@
-import type { MediaKind } from '../shared/media-kind';
+import type { MediaKind, TmdbMediaType } from '../shared/media-kind';
+
 export interface SessionSummary {
   sessionId: number;
   canonicalTitle: string | null;
@@ -245,6 +246,8 @@ export interface AnimeLibraryItem {
   animeId: number;
   canonicalTitle: string;
   anilistId: number | null;
+  tmdbId: number | null;
+  tmdbType: TmdbMediaType | null;
   totalSessions: number;
   totalActiveMs: number;
   totalCards: number;
@@ -267,6 +270,8 @@ export interface AnimeDetailData {
     animeId: number;
     canonicalTitle: string;
     anilistId: number | null;
+    tmdbId: number | null;
+    tmdbType: TmdbMediaType | null;
     titleRomaji: string | null;
     titleEnglish: string | null;
     titleNative: string | null;

stats/src/App.tsx

@@ -4,7 +4,6 @@ import { DeleteProgressToast } from './components/common/DeleteProgressToast';
 import { TabBar } from './components/layout/TabBar';
 import { OverviewTab } from './components/overview/OverviewTab';
 import { useExcludedWords } from './hooks/useExcludedWords';
-import { assetUrl } from './lib/asset-url';
 import type { TabId } from './components/layout/TabBar';
 import {
   closeMediaDetail,
@@ -142,7 +141,7 @@ export function App() {
           onClick={() => handleTabChange('overview')}
           className="flex items-center gap-2 mb-2 hover:opacity-80 transition-opacity"
         >
-          <img src={assetUrl('favicon.png')} alt="" className="h-6 object-contain" />
+          <img src={'/favicon.png'} alt="" className="h-6 object-contain" />
           <h1 className="text-lg font-semibold text-ctp-text">SubMiner Stats</h1>
         </button>
         <TabBar activeTab={activeTab} onTabChange={handleTabChange} />

stats/src/components/anime/AnimeCard.test.tsx

@@ -11,6 +11,8 @@ test('AnimeCard includes linked AniList id in cover URLs to avoid stale library
         animeId: 42,
         canonicalTitle: 'Test Anime',
         anilistId: 21699,
+        tmdbId: null,
+        tmdbType: null,
         totalSessions: 1,
         totalActiveMs: 600_000,
         totalCards: 0,

stats/src/components/anime/AnimeCard.tsx

@@ -29,7 +29,7 @@ export function AnimeCard({
         <AnimeCoverImage
           animeId={anime.animeId}
           title={anime.canonicalTitle}
-          coverRetryToken={anime.anilistId ?? 0}
+          coverRetryToken={anime.anilistId ?? anime.tmdbId ?? 0}
           className="w-full aspect-[3/4] rounded-t-lg transition-transform duration-200 group-hover:scale-105"
         />
         {selectable && (

stats/src/components/anime/AnimeCoverImage.test.tsx

@@ -20,6 +20,8 @@ test('AnimeHeader uses the linked AniList id to avoid stale cached cover art', (
         animeId: 42,
         canonicalTitle: 'Test Anime',
         anilistId: 21699,
+        tmdbId: null,
+        tmdbType: null,
         titleRomaji: null,
         titleEnglish: null,
         titleNative: null,

stats/src/components/anime/AnimeDetailView.tsx

@@ -7,6 +7,7 @@ import { AnimeHeader } from './AnimeHeader';
 import { EpisodeList } from './EpisodeList';
 import { AnimeWordList } from './AnimeWordList';
 import { AnilistSelector } from './AnilistSelector';
+import { TmdbSelector } from './TmdbSelector';
 import { AnimeOverviewStats } from './AnimeOverviewStats';
 import { CHART_THEME } from '../../lib/chart-theme';
 import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer } from 'recharts';
@@ -20,11 +21,11 @@ interface AnimeDetailViewProps {
   /** Called after the whole library entry is deleted, so the caller can refresh. */
   onAnimeDeleted?: () => void;
   /**
-   * Called after the AniList link changes. The library list caches the old
+   * Called after the AniList or TMDB link changes. The library list caches the
-   * anilistId (and with it the cover URL), so it has to refetch or the grid
+   * old provider ids (and with them the cover URL and media kind), so it has to
-   * keeps showing the previous title's art.
+   * refetch or the grid keeps showing the previous title's art.
    */
-  onAnilistRelinked?: () => void;
+  onProviderRelinked?: () => void;
   /** Called after an episode is reassigned to another entry. */
   onEpisodeMoved?: () => void;
 }
@@ -151,11 +152,12 @@ export function AnimeDetailView({
   onNavigateToWord,
   onOpenEpisodeDetail,
   onAnimeDeleted,
-  onAnilistRelinked,
+  onProviderRelinked,
   onEpisodeMoved,
 }: AnimeDetailViewProps) {
   const { data, loading, error, reload } = useAnimeDetail(animeId);
   const [showAnilistSelector, setShowAnilistSelector] = useState(false);
+  const [showTmdbSelector, setShowTmdbSelector] = useState(false);
   const [coverRetryToken, setCoverRetryToken] = useState(0);
   const [isDeletingAnime, setIsDeletingAnime] = useState(false);
   const [deleteError, setDeleteError] = useState<string | null>(null);
@@ -219,6 +221,7 @@ export function AnimeDetailView({
         anilistEntries={anilistEntries ?? []}
         coverRetryToken={coverRetryToken}
         onChangeAnilist={() => setShowAnilistSelector(true)}
+        onChangeTmdb={() => setShowTmdbSelector(true)}
         onDeleteAnime={() => void handleDeleteAnime()}
         isDeletingAnime={isDeletingAnime}
       />
@@ -238,7 +241,7 @@ export function AnimeDetailView({
       />
       <AnimeWatchChart animeId={animeId} />
       <AnimeWordList animeId={animeId} onNavigateToWord={onNavigateToWord} />
-      {detail.mediaKind === 'anime' && showAnilistSelector && (
+      {detail.mediaKind !== 'youtube' && showAnilistSelector && (
         <AnilistSelector
           animeId={animeId}
           initialQuery={detail.canonicalTitle}
@@ -247,7 +250,20 @@ export function AnimeDetailView({
             setShowAnilistSelector(false);
             setCoverRetryToken((value) => value + 1);
             reload();
-            onAnilistRelinked?.();
+            onProviderRelinked?.();
+          }}
+        />
+      )}
+      {showTmdbSelector && (
+        <TmdbSelector
+          animeId={animeId}
+          initialQuery={detail.canonicalTitle}
+          onClose={() => setShowTmdbSelector(false)}
+          onLinked={() => {
+            setShowTmdbSelector(false);
+            setCoverRetryToken((value) => value + 1);
+            reload();
+            onProviderRelinked?.();
           }}
         />
       )}

stats/src/components/anime/AnimeDialogAccessibility.test.tsx

@@ -50,6 +50,8 @@ function libraryItem(animeId: number, title: string): AnimeLibraryItem {
     animeId,
     canonicalTitle: title,
     anilistId: null,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 0,

stats/src/components/anime/AnimeHeader.test.tsx

@@ -10,6 +10,8 @@ const DETAIL: AnimeDetailData['detail'] = {
   animeId: 3,
   canonicalTitle: 'Project Radio Noise Season 2',
   anilistId: 20661,
+  tmdbId: null,
+  tmdbType: null,
   titleRomaji: 'Toaru Kagaku no Railgun S',
   titleEnglish: 'A Certain Scientific Railgun S',
   titleNative: null,
@@ -71,6 +73,46 @@ test('confirmAnimeDelete spells out how much data the entry deletion removes', a
   assert.match(seen[0] ?? '', /every session and stat/);
 });
 
+test('AnimeHeader shows TMDB actions for a live-action entry and hides AniList links', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeHeader
+      detail={{
+        ...DETAIL,
+        anilistId: null,
+        mediaKind: 'live_action',
+        tmdbId: 61222,
+        tmdbType: 'tv',
+        titleRomaji: null,
+        titleEnglish: 'Hanzawa Naoki',
+        titleNative: '半沢直樹',
+        description: 'A banker fights back.',
+      }}
+      anilistEntries={[]}
+      onChangeAnilist={() => {}}
+      onChangeTmdb={() => {}}
+    />,
+  );
+
+  assert.match(markup, /https:\/\/www\.themoviedb\.org\/tv\/61222/);
+  assert.match(markup, /Change TMDB Title/);
+  assert.match(markup, /Live action/);
+  assert.match(markup, /A banker fights back\./);
+  assert.doesNotMatch(markup, /anilist\.co/);
+});
+
+test('AnimeHeader offers to link an unlinked anime entry to TMDB', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeHeader
+      detail={{ ...DETAIL, anilistId: null }}
+      anilistEntries={[]}
+      onChangeTmdb={() => {}}
+    />,
+  );
+
+  assert.match(markup, /Link to TMDB/);
+  assert.doesNotMatch(markup, /themoviedb\.org/);
+});
+
 test('YouTube channel headers show videos and omit all AniList controls', () => {
   const markup = renderToStaticMarkup(
     <AnimeHeader

stats/src/components/anime/AnimeHeader.tsx

@@ -6,6 +6,7 @@ interface AnimeHeaderProps {
   anilistEntries: AnilistEntry[];
   coverRetryToken?: number;
   onChangeAnilist?: () => void;
+  onChangeTmdb?: () => void;
   onDeleteAnime?: () => void;
   isDeletingAnime?: boolean;
 }
@@ -34,6 +35,7 @@ export function AnimeHeader({
   anilistEntries,
   coverRetryToken = 0,
   onChangeAnilist,
+  onChangeTmdb,
   onDeleteAnime,
   isDeletingAnime = false,
 }: AnimeHeaderProps) {
@@ -44,7 +46,12 @@ export function AnimeHeader({
   const uniqueAltTitles = [...new Set(altTitles)];
 
   const hasMultipleEntries = anilistEntries.length > 1;
-  const coverCacheToken = (detail.anilistId ?? 0) * 1_000_000 + coverRetryToken;
+  const isLiveAction = detail.mediaKind === 'live_action';
+  const tmdbUrl =
+    detail.tmdbId && detail.tmdbType
+      ? `https://www.themoviedb.org/${detail.tmdbType}/${detail.tmdbId}`
+      : null;
+  const coverCacheToken = (detail.anilistId ?? detail.tmdbId ?? 0) * 1_000_000 + coverRetryToken;
 
   return (
     <div className="flex gap-4">
@@ -61,13 +68,31 @@ export function AnimeHeader({
             {uniqueAltTitles.join(' · ')}
           </div>
         )}
-        <div className="text-sm text-ctp-subtext0 mt-2">
+        <div className="text-sm text-ctp-subtext0 mt-2 flex items-center gap-2">
-          {isYoutube ? 'YouTube channel · ' : ''}
+          <span>
-          {detail.episodeCount} {isYoutube ? 'video' : 'episode'}
+            {isYoutube ? 'YouTube channel · ' : ''}
-          {detail.episodeCount !== 1 ? 's' : ''}
+            {detail.episodeCount} {isYoutube ? 'video' : 'episode'}
+            {detail.episodeCount !== 1 ? 's' : ''}
+          </span>
+          {isLiveAction && (
+            <span className="px-1.5 py-0.5 rounded text-[10px] uppercase tracking-wide bg-ctp-peach/15 text-ctp-peach">
+              {detail.tmdbType === 'movie' ? 'Movie' : 'Live action'}
+            </span>
+          )}
         </div>
         <div className="flex flex-wrap gap-1.5 mt-2">
+          {tmdbUrl && (
+            <a
+              href={tmdbUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-1 px-2 py-1 text-xs rounded bg-ctp-surface1 text-ctp-blue hover:bg-ctp-surface2 hover:text-ctp-sapphire transition-colors"
+            >
+              View on TMDB <span className="text-[10px]">{'\u2197'}</span>
+            </a>
+          )}
           {!isYoutube &&
+            !isLiveAction &&
             (anilistEntries.length > 0 ? (
               hasMultipleEntries ? (
                 anilistEntries.map((entry) => <AnilistButton key={entry.anilistId} entry={entry} />)
@@ -103,6 +128,16 @@ export function AnimeHeader({
                 : 'Link to AniList'}
             </button>
           )}
+          {!isYoutube && onChangeTmdb && (
+            <button
+              type="button"
+              onClick={onChangeTmdb}
+              title="Search TMDB and link this title to a live-action drama or movie"
+              className="inline-flex items-center gap-1 px-2 py-1 text-xs rounded bg-ctp-surface1 text-ctp-overlay2 hover:bg-ctp-surface2 hover:text-ctp-subtext0 transition-colors"
+            >
+              {tmdbUrl ? 'Change TMDB Title' : 'Link to TMDB'}
+            </button>
+          )}
           {onDeleteAnime && (
             <button
               type="button"

stats/src/components/anime/AnimeMergeDialog.tsx

@@ -11,6 +11,27 @@ interface AnimeMergeDialogProps {
   onMerged: (survivingAnimeId: number) => void;
 }
 
+const PROVIDER_CONFLICT_MESSAGE =
+  'AniList-linked and TMDB-linked entries cannot be merged together. Relink one of them first.';
+const KIND_CONFLICT_MESSAGE =
+  'YouTube channels cannot be merged with anime or live-action entries.';
+
+/** Merging an AniList entry with a TMDB entry is rejected by the server (409), as is mixing in a channel. */
+function hasProviderConflict(entries: AnimeLibraryItem[]): boolean {
+  return (
+    entries.some((entry) => entry.anilistId !== null) &&
+    entries.some((entry) => entry.tmdbId !== null)
+  );
+}
+
+function describeMergeError(err: unknown, entries: AnimeLibraryItem[]): string {
+  const message = err instanceof Error ? err.message : '';
+  if (/^Stats API error: 409\b/.test(message)) {
+    return hasProviderConflict(entries) ? PROVIDER_CONFLICT_MESSAGE : KIND_CONFLICT_MESSAGE;
+  }
+  return message || 'Failed to merge these entries.';
+}
+
 /** Biggest entry first: the one most likely to carry the right title and art. */
 function pickDefaultKeeper(entries: AnimeLibraryItem[]): number {
   const best = [...entries].sort(
@@ -26,6 +47,7 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
   const [keeperId, setKeeperId] = useState(() => pickDefaultKeeper(entries));
   const [merging, setMerging] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const providerConflict = hasProviderConflict(entries);
 
   const totalEpisodes = entries.reduce((sum, entry) => sum + entry.episodeCount, 0);
   const totalCards = entries.reduce((sum, entry) => sum + entry.totalCards, 0);
@@ -42,14 +64,14 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
     const sourceAnimeIds = entries
       .map((entry) => entry.animeId)
       .filter((animeId) => animeId !== keeperId);
-    if (sourceAnimeIds.length === 0) return;
+    if (sourceAnimeIds.length === 0 || providerConflict) return;
     setMerging(true);
     setError(null);
     try {
       const result = await apiClient.mergeAnime(keeperId, sourceAnimeIds);
       onMerged(result.animeId);
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Failed to merge these entries.');
+      setError(describeMergeError(err, entries));
       setMerging(false);
     }
   };
@@ -120,7 +142,7 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
               <AnimeCoverImage
                 animeId={entry.animeId}
                 title={entry.canonicalTitle}
-                coverRetryToken={entry.anilistId ?? 0}
+                coverRetryToken={entry.anilistId ?? entry.tmdbId ?? 0}
                 className="w-10 h-14 rounded shrink-0"
               />
               <div className="min-w-0 flex-1">
@@ -138,7 +160,11 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
         </div>
 
         <div className="p-4 border-t border-ctp-surface1 space-y-2">
-          {error ? (
+          {providerConflict ? (
+            <div role="alert" className="text-xs text-ctp-peach">
+              {PROVIDER_CONFLICT_MESSAGE}
+            </div>
+          ) : error ? (
             <div role="alert" className="text-xs text-ctp-red">
               {error}
             </div>
@@ -150,7 +176,7 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
             </div>
             <button
               type="button"
-              disabled={merging}
+              disabled={merging || providerConflict}
               onClick={() => void handleMerge()}
               className="px-3 py-1.5 rounded-lg bg-ctp-blue/15 border border-ctp-blue/40 text-xs text-ctp-blue hover:bg-ctp-blue/25 transition-colors disabled:opacity-50"
             >

stats/src/components/anime/AnimeMergeFlow.test.tsx

@@ -5,6 +5,7 @@ import { act } from 'react';
 import { createRoot } from 'react-dom/client';
 import { apiClient } from '../../lib/api-client';
 import type { AnimeLibraryItem, StatsMergeAnimeResponse } from '../../types/stats';
+import { AnimeMergeDialog } from './AnimeMergeDialog';
 import { AnimeTab } from './AnimeTab';
 
 interface TestWindow extends Window {
@@ -49,6 +50,8 @@ function libraryItem(animeId: number, title: string, episodeCount: number): Anim
     animeId,
     canonicalTitle: title,
     anilistId: null,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 1,
@@ -165,6 +168,52 @@ test('AnimeTab merges the selected duplicate entries into the chosen keeper', as
   }
 });
 
+test('AnimeMergeDialog refuses to merge an AniList entry with a TMDB entry', async () => {
+  const uninstallDom = installDom();
+  const originalMerge = apiClient.mergeAnime;
+  let mergeCalls = 0;
+  apiClient.mergeAnime = (async () => {
+    mergeCalls += 1;
+    throw new Error('unexpected merge');
+  }) as typeof apiClient.mergeAnime;
+
+  const anime = { ...libraryItem(1, 'Show', 2), anilistId: 100 };
+  const drama = {
+    ...libraryItem(2, 'Show', 1),
+    mediaKind: 'live_action' as const,
+    tmdbId: 200,
+    tmdbType: 'tv' as const,
+  };
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <AnimeMergeDialog entries={[anime, drama]} onClose={() => {}} onMerged={() => {}} />,
+      );
+    });
+
+    const merge = findButton(container, 'Merge Entries') as HTMLButtonElement;
+    assert.equal(merge.disabled, true);
+    assert.match(container.textContent ?? '', /cannot be merged together/);
+
+    await act(async () => {
+      merge.click();
+    });
+    assert.equal(mergeCalls, 0);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.mergeAnime = originalMerge;
+    uninstallDom();
+  }
+});
+
 test('AnimeTab keeps a suggested duplicate visible until it is reviewed and merged', async () => {
   const uninstallDom = installDom();
   const original = {

stats/src/components/anime/AnimeTab.test.tsx

@@ -49,6 +49,8 @@ function libraryItem(anilistId: number | null): AnimeLibraryItem {
     animeId: 7,
     canonicalTitle: 'Test Anime Season 2',
     anilistId,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 0,
@@ -66,6 +68,8 @@ function detailData(anilistId: number | null): AnimeDetailData {
       animeId: 7,
       canonicalTitle: 'Test Anime Season 2',
       anilistId,
+      tmdbId: null,
+      tmdbType: null,
       titleRomaji: null,
       titleEnglish: null,
       titleNative: null,
@@ -180,6 +184,43 @@ test('AnimeTab refetches the library after the AniList entry is relinked', async
   }
 });
 
+test('AnimeTab watch time follows the displayed kind filter', async () => {
+  const uninstallDom = installDom();
+  const original = apiClient.getAnimeLibrary;
+  apiClient.getAnimeLibrary = async () => [
+    { ...libraryItem(42), totalActiveMs: 3600000 },
+    {
+      ...libraryItem(null),
+      animeId: 8,
+      canonicalTitle: 'Drama',
+      mediaKind: 'live_action',
+      tmdbId: 12,
+      tmdbType: 'tv',
+      totalActiveMs: 7200000,
+    },
+  ];
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () => {
+      root.render(<AnimeTab />);
+    });
+    assert.match(container.textContent ?? '', /2 titles · 3h/);
+    await act(async () => {
+      findButton(container, 'Live Action').click();
+    });
+    assert.match(container.textContent ?? '', /1 title · 2h/);
+    assert.equal(findButton(container, 'Live Action').getAttribute('aria-pressed'), 'true');
+  } finally {
+    await act(async () => {
+      root.unmount();
+    });
+    apiClient.getAnimeLibrary = original;
+    uninstallDom();
+  }
+});
+
 test('Library kind filter separates YouTube channels from anime and updates totals', async () => {
   const uninstallDom = installDom();
   const original = {

stats/src/components/anime/AnimeTab.tsx

@@ -1,4 +1,8 @@
-import { MEDIA_KINDS, type MediaKind } from '../../../../src/shared/media-kind';
+import {
+  MEDIA_KINDS,
+  shareTitleNamespace,
+  type MediaKind,
+} from '../../../../src/shared/media-kind';
 import { useState, useMemo, useEffect } from 'react';
 import { useAnimeLibrary } from '../../hooks/useAnimeLibrary';
 import { formatDuration } from '../../lib/formatters';
@@ -21,6 +25,13 @@ const GRID_CLASSES: Record<LibraryCardSize, string> = {
   lg: 'grid-cols-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-7',
 };
 
+const KIND_LABELS: Record<MediaKind | 'all', string> = {
+  all: 'All Titles',
+  anime: 'Anime',
+  live_action: 'Live Action',
+  youtube: 'YouTube',
+};
+
 const SORT_OPTIONS: { key: SortKey; label: string }[] = [
   { key: 'lastWatched', label: 'Last Watched' },
   { key: 'watchTime', label: 'Watch Time' },
@@ -121,7 +132,11 @@ export function AnimeTab({
   const checkedEntries = checkedAnimeIds
     .map((animeId) => anime.find((entry) => entry.animeId === animeId))
     .filter((entry): entry is (typeof anime)[number] => entry !== undefined);
-  const mixedKindsChecked = new Set(checkedEntries.map((entry) => entry.mediaKind)).size > 1;
+  // Anime and live-action entries may be combined (the server only rejects
+  // conflicting AniList/TMDB links); channels never mix with either.
+  const mixedKindsChecked = checkedEntries.some(
+    (entry) => !shareTitleNamespace(entry.mediaKind, checkedEntries[0]!.mediaKind),
+  );
   const hydratedRecommendations = recommendations
     .map((recommendation) => ({
       ...recommendation,
@@ -153,7 +168,7 @@ export function AnimeTab({
             : undefined
         }
         onAnimeDeleted={reload}
-        onAnilistRelinked={reload}
+        onProviderRelinked={reload}
         onEpisodeMoved={reload}
       />
     );
@@ -185,7 +200,7 @@ export function AnimeTab({
                   : 'text-ctp-overlay2 hover:text-ctp-subtext0'
               }`}
             >
-              {kind === 'all' ? 'All Titles' : kind === 'youtube' ? 'YouTube' : 'Anime'}
+              {KIND_LABELS[kind]}
             </button>
           ))}
         </div>
@@ -269,7 +284,7 @@ export function AnimeTab({
             {checkedEntries.length === 0
               ? 'Pick the duplicate entries to combine'
               : mixedKindsChecked
-                ? 'Anime and YouTube channels cannot be combined'
+                ? 'YouTube channels cannot be combined with other titles'
                 : `${checkedEntries.length} selected`}
           </div>
           <button
@@ -301,6 +316,11 @@ export function AnimeTab({
         </div>
       )}
 
+      <p className="text-[11px] text-ctp-overlay2 pt-2">
+        Cover art and synopses come from AniList and TMDB. This product uses the TMDB API but is not
+        endorsed or certified by TMDB.
+      </p>
+
       {showMergeDialog && mergeEntries.length >= 2 && (
         <AnimeMergeDialog
           entries={mergeEntries}

stats/src/components/anime/EpisodeMove.test.tsx

@@ -67,6 +67,8 @@ function libraryItem(animeId: number, title: string): AnimeLibraryItem {
     animeId,
     canonicalTitle: title,
     anilistId: null,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 0,

stats/src/components/anime/LibraryEntryPicker.tsx

@@ -4,7 +4,7 @@ import { formatDuration } from '../../lib/formatters';
 import { useModalFocus } from '../../hooks/useModalFocus';
 import { AnimeCoverImage } from './AnimeCoverImage';
 import type { AnimeLibraryItem } from '../../types/stats';
-import type { MediaKind } from '../../../../src/shared/media-kind';
+import { shareTitleNamespace, type MediaKind } from '../../../../src/shared/media-kind';
 
 interface LibraryEntryPickerProps {
   heading: string;
@@ -73,7 +73,7 @@ export function LibraryEntryPicker({
     const term = query.trim().toLowerCase();
     return (entries ?? [])
       .filter((entry) => !excluded.has(entry.animeId))
-      .filter((entry) => mediaKind === undefined || entry.mediaKind === mediaKind)
+      .filter((entry) => mediaKind === undefined || shareTitleNamespace(entry.mediaKind, mediaKind))
       .filter((entry) => !term || entry.canonicalTitle.toLowerCase().includes(term))
       .sort((a, b) => b.lastWatchedMs - a.lastWatchedMs);
   }, [entries, excluded, mediaKind, query]);
@@ -149,7 +149,7 @@ export function LibraryEntryPicker({
               <AnimeCoverImage
                 animeId={entry.animeId}
                 title={entry.canonicalTitle}
-                coverRetryToken={entry.anilistId ?? 0}
+                coverRetryToken={entry.anilistId ?? entry.tmdbId ?? 0}
                 className="w-10 h-14 rounded shrink-0"
               />
               <div className="min-w-0 flex-1">

stats/src/components/anime/TmdbSelector.test.tsx

@@ -0,0 +1,387 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Window } from 'happy-dom';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { apiClient } from '../../lib/api-client';
+import type { StatsTmdbSearchResult } from '../../types/stats';
+import { TmdbSelector } from './TmdbSelector';
+
+interface TestWindow extends Window {
+  IS_REACT_ACT_ENVIRONMENT?: boolean;
+}
+
+function installDom(): () => void {
+  const previousWindow = globalThis.window;
+  const previousDocument = globalThis.document;
+  const previousHTMLElement = globalThis.HTMLElement;
+  const previousISReactActEnvironment = (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT;
+  const window = new Window() as TestWindow;
+
+  Object.defineProperty(globalThis, 'window', { value: window, configurable: true });
+  Object.defineProperty(globalThis, 'document', { value: window.document, configurable: true });
+  Object.defineProperty(globalThis, 'HTMLElement', {
+    value: window.HTMLElement,
+    configurable: true,
+  });
+  (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT = true;
+
+  return () => {
+    Object.defineProperty(globalThis, 'window', { value: previousWindow, configurable: true });
+    Object.defineProperty(globalThis, 'document', {
+      value: previousDocument,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, 'HTMLElement', {
+      value: previousHTMLElement,
+      configurable: true,
+    });
+    (
+      globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+    ).IS_REACT_ACT_ENVIRONMENT = previousISReactActEnvironment;
+  };
+}
+
+const HANZAWA: StatsTmdbSearchResult = {
+  tmdbId: 61222,
+  tmdbType: 'tv',
+  title: 'Hanzawa Naoki',
+  originalTitle: '半沢直樹',
+  originalLanguage: 'ja',
+  overview: null,
+  posterUrl: null,
+  year: 2013,
+  isAnimation: false,
+};
+
+test('TmdbSelector searches the normalized title and links the picked result by id', async () => {
+  const uninstallDom = installDom();
+  const original = {
+    searchTmdb: apiClient.searchTmdb,
+    reassignAnimeTmdb: apiClient.reassignAnimeTmdb,
+  };
+  const searchCalls: string[] = [];
+  const linkCalls: Array<[number, { tmdbId: number; tmdbType: string }]> = [];
+  let linked = 0;
+  apiClient.searchTmdb = (async (query: string) => {
+    searchCalls.push(query);
+    return [HANZAWA];
+  }) as typeof apiClient.searchTmdb;
+  apiClient.reassignAnimeTmdb = (async (animeId: number, info) => {
+    linkCalls.push([animeId, info]);
+  }) as typeof apiClient.reassignAnimeTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={9}
+          initialQuery="Hanzawa Naoki Season 2"
+          onClose={() => {}}
+          onLinked={() => {
+            linked += 1;
+          }}
+        />,
+      );
+    });
+
+    assert.deepEqual(searchCalls, ['Hanzawa Naoki']);
+    assert.match(container.textContent ?? '', /半沢直樹/);
+    assert.match(container.textContent ?? '', /TV · 2013/);
+
+    const pick = [...container.querySelectorAll('button')].find((button) =>
+      /Select/.test(button.textContent ?? ''),
+    );
+    assert.ok(pick);
+    await act(async () => {
+      pick.click();
+    });
+
+    assert.deepEqual(linkCalls, [[9, { tmdbId: 61222, tmdbType: 'tv' }]]);
+    assert.equal(linked, 1);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = original.searchTmdb;
+    apiClient.reassignAnimeTmdb = original.reassignAnimeTmdb;
+    uninstallDom();
+  }
+});
+
+test('TmdbSelector explains a missing API key instead of showing "No results"', async () => {
+  const uninstallDom = installDom();
+  const originalSearch = apiClient.searchTmdb;
+  apiClient.searchTmdb = (async () => {
+    throw new Error('Stats API error: 503 {"error":"TMDB API key not configured."}');
+  }) as typeof apiClient.searchTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={1}
+          initialQuery="Hanzawa Naoki"
+          onClose={() => {}}
+          onLinked={() => {}}
+        />,
+      );
+    });
+
+    assert.match(container.textContent ?? '', /tmdb\.apiKey/);
+    assert.doesNotMatch(container.textContent ?? '', /No results/);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = originalSearch;
+    uninstallDom();
+  }
+});
+
+test('TmdbSelector reports a failed link as a link problem, not a search failure', async () => {
+  const uninstallDom = installDom();
+  const original = {
+    searchTmdb: apiClient.searchTmdb,
+    reassignAnimeTmdb: apiClient.reassignAnimeTmdb,
+  };
+  apiClient.searchTmdb = (async () => [HANZAWA]) as typeof apiClient.searchTmdb;
+  apiClient.reassignAnimeTmdb = (async () => {
+    throw new Error('Stats API error: 404');
+  }) as typeof apiClient.reassignAnimeTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={9}
+          initialQuery="Hanzawa Naoki"
+          onClose={() => {}}
+          onLinked={() => {}}
+        />,
+      );
+    });
+
+    const pick = [...container.querySelectorAll('button')].find((button) =>
+      /Select/.test(button.textContent ?? ''),
+    );
+    assert.ok(pick);
+    await act(async () => {
+      pick.click();
+    });
+
+    assert.match(container.textContent ?? '', /TMDB has no details for this title/);
+    assert.doesNotMatch(container.textContent ?? '', /search failed/);
+    // The results stay on screen so the user can pick another one.
+    assert.match(container.textContent ?? '', /半沢直樹/);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = original.searchTmdb;
+    apiClient.reassignAnimeTmdb = original.reassignAnimeTmdb;
+    uninstallDom();
+  }
+});
+
+test('TmdbSelector cannot be dismissed while a link is in flight', async () => {
+  const uninstallDom = installDom();
+  const original = {
+    searchTmdb: apiClient.searchTmdb,
+    reassignAnimeTmdb: apiClient.reassignAnimeTmdb,
+  };
+  let finishLink: () => void = () => {};
+  let closed = 0;
+  apiClient.searchTmdb = (async () => [HANZAWA]) as typeof apiClient.searchTmdb;
+  apiClient.reassignAnimeTmdb = (() =>
+    new Promise<void>((resolve) => {
+      finishLink = resolve;
+    })) as typeof apiClient.reassignAnimeTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={9}
+          initialQuery="Hanzawa Naoki"
+          onClose={() => {
+            closed += 1;
+          }}
+          onLinked={() => {}}
+        />,
+      );
+    });
+
+    const pick = [...container.querySelectorAll('button')].find((button) =>
+      /Select/.test(button.textContent ?? ''),
+    );
+    assert.ok(pick);
+    await act(async () => {
+      pick.click();
+    });
+
+    const close = [...container.querySelectorAll('button')].find((button) =>
+      /✕/.test(button.textContent ?? ''),
+    ) as HTMLButtonElement | undefined;
+    assert.ok(close);
+    assert.equal(close.disabled, true);
+    await act(async () => {
+      (container.firstElementChild as HTMLElement).click();
+    });
+    assert.equal(closed, 0);
+
+    await act(async () => {
+      finishLink();
+    });
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = original.searchTmdb;
+    apiClient.reassignAnimeTmdb = original.reassignAnimeTmdb;
+    uninstallDom();
+  }
+});
+
+for (const staleFailure of [false, true]) {
+  test(`TmdbSelector ignores superseded ${staleFailure ? 'errors' : 'results'} and loading changes`, async () => {
+    const uninstallDom = installDom();
+    const originalSearch = apiClient.searchTmdb;
+    const requests: Array<{
+      resolve: (results: StatsTmdbSearchResult[]) => void;
+      reject: (error: Error) => void;
+    }> = [];
+    apiClient.searchTmdb = () =>
+      new Promise((resolve, reject) => {
+        requests.push({ resolve, reject });
+      });
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+    try {
+      const render = (initialQuery: string) =>
+        root.render(
+          <TmdbSelector
+            animeId={1}
+            initialQuery={initialQuery}
+            onClose={() => {}}
+            onLinked={() => {}}
+          />,
+        );
+      await act(async () => {
+        render('First title');
+      });
+      await act(async () => {
+        render('Second title');
+      });
+      assert.equal(requests.length, 2);
+      await act(async () => {
+        if (staleFailure) requests[0]!.reject(new Error('stale error'));
+        else requests[0]!.resolve([HANZAWA]);
+      });
+      assert.match(container.textContent ?? '', /Searching/);
+      assert.doesNotMatch(container.textContent ?? '', /Hanzawa|failed/);
+      await act(async () => {
+        requests[1]!.resolve([HANZAWA]);
+      });
+      assert.match(container.textContent ?? '', /Hanzawa/);
+      assert.doesNotMatch(container.textContent ?? '', /Searching/);
+      await act(async () => {
+        render('Third title');
+      });
+      await act(async () => {
+        render('');
+      });
+      await act(async () => {
+        requests[2]!.resolve([HANZAWA]);
+      });
+      assert.doesNotMatch(container.textContent ?? '', /Hanzawa|Searching/);
+    } finally {
+      await act(async () => {
+        root.unmount();
+      });
+      apiClient.searchTmdb = originalSearch;
+      uninstallDom();
+    }
+  });
+}
+
+test('TmdbSelector invalidates requests as soon as the user edits or clears the query', async () => {
+  const uninstallDom = installDom();
+  const originalSearch = apiClient.searchTmdb;
+  const requests: Array<(results: StatsTmdbSearchResult[]) => void> = [];
+  apiClient.searchTmdb = () =>
+    new Promise((resolve) => {
+      requests.push(resolve);
+    });
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () => {
+      root.render(
+        <TmdbSelector animeId={1} initialQuery="First" onClose={() => {}} onLinked={() => {}} />,
+      );
+    });
+    const input = container.querySelector('input');
+    assert.ok(input);
+    const setValue = Object.getOwnPropertyDescriptor(
+      window.HTMLInputElement.prototype,
+      'value',
+    )?.set;
+    assert.ok(setValue);
+    const edit = async (value: string) => {
+      await act(async () => {
+        setValue.call(input, value);
+        input.dispatchEvent(new window.Event('input', { bubbles: true }));
+        input.dispatchEvent(new window.KeyboardEvent('keyup', { bubbles: true }));
+      });
+    };
+    await edit('Second');
+    await act(async () => {
+      requests[0]!([HANZAWA]);
+    });
+    assert.doesNotMatch(container.textContent ?? '', /Hanzawa|No results/);
+    assert.match(container.textContent ?? '', /Searching/);
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 450));
+    });
+    assert.equal(requests.length, 2);
+    await edit('');
+    assert.doesNotMatch(container.textContent ?? '', /Searching/);
+    await act(async () => {
+      requests[1]!([HANZAWA]);
+    });
+    assert.doesNotMatch(container.textContent ?? '', /Hanzawa|Searching/);
+  } finally {
+    await act(async () => {
+      root.unmount();
+    });
+    apiClient.searchTmdb = originalSearch;
+    uninstallDom();
+  }
+});

stats/src/components/anime/TmdbSelector.tsx

@@ -0,0 +1,199 @@
+import { useState, useEffect, useRef } from 'react';
+import { apiClient } from '../../lib/api-client';
+import { normalizeAnilistSearchQuery } from '../../lib/anilist-search-query';
+import type { StatsTmdbSearchResult } from '../../types/stats';
+
+interface TmdbSelectorProps {
+  animeId: number;
+  initialQuery: string;
+  onClose: () => void;
+  onLinked: () => void;
+}
+
+const MISSING_KEY_MESSAGE =
+  'TMDB API key not configured. Set tmdb.apiKey or tmdb.apiKeyCommand in your config.';
+
+function statusOf(err: unknown): number | null {
+  const match = err instanceof Error ? /^Stats API error: (\d{3})\b/.exec(err.message) : null;
+  return match ? Number(match[1]) : null;
+}
+
+// The stats API answers a missing key with 503 and the message from config.
+function describeSearchError(err: unknown): string {
+  if (statusOf(err) === 503) return MISSING_KEY_MESSAGE;
+  return 'TMDB search failed. Check your connection and API key.';
+}
+
+// The link route answers 404 when TMDB has no details for the picked id or
+// when the library entry itself is gone.
+function describeLinkError(err: unknown): string {
+  switch (statusOf(err)) {
+    case 503:
+      return MISSING_KEY_MESSAGE;
+    case 404:
+      return 'TMDB has no details for this title. Pick another result or refresh the Library.';
+    default:
+      return 'Linking to TMDB failed. Check your connection and try again.';
+  }
+}
+
+export function TmdbSelector({ animeId, initialQuery, onClose, onLinked }: TmdbSelectorProps) {
+  const [query, setQuery] = useState(() => normalizeAnilistSearchQuery(initialQuery));
+  const [results, setResults] = useState<StatsTmdbSearchResult[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [linking, setLinking] = useState<number | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const searchSequenceRef = useRef(0);
+
+  useEffect(() => {
+    inputRef.current?.focus();
+    const normalizedInitialQuery = normalizeAnilistSearchQuery(initialQuery);
+    setQuery(normalizedInitialQuery);
+    setResults([]);
+    setError(null);
+    setLoading(false);
+    setLinking(null);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    if (normalizedInitialQuery) void doSearch(normalizedInitialQuery);
+    return () => {
+      searchSequenceRef.current += 1;
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+    };
+  }, [initialQuery, animeId]);
+
+  const doSearch = async (q: string) => {
+    const sequence = ++searchSequenceRef.current;
+    const searchQuery = normalizeAnilistSearchQuery(q);
+    if (!searchQuery) {
+      setResults([]);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const nextResults = await apiClient.searchTmdb(searchQuery);
+      if (sequence === searchSequenceRef.current) setResults(nextResults);
+    } catch (err) {
+      if (sequence !== searchSequenceRef.current) return;
+      setResults([]);
+      setError(describeSearchError(err));
+    } finally {
+      if (sequence === searchSequenceRef.current) setLoading(false);
+    }
+  };
+
+  const handleInput = (value: string) => {
+    searchSequenceRef.current += 1;
+    setQuery(value);
+    setResults([]);
+    setError(null);
+    const hasQuery = Boolean(normalizeAnilistSearchQuery(value));
+    setLoading(hasQuery);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    if (!hasQuery) return;
+    debounceRef.current = setTimeout(() => void doSearch(value), 400);
+  };
+
+  const handleSelect = async (media: StatsTmdbSearchResult) => {
+    setLinking(media.tmdbId);
+    setError(null);
+    try {
+      await apiClient.reassignAnimeTmdb(animeId, {
+        tmdbId: media.tmdbId,
+        tmdbType: media.tmdbType,
+      });
+      onLinked();
+    } catch (err) {
+      setError(describeLinkError(err));
+      setLinking(null);
+    }
+  };
+
+  // Dismissing mid-link would leave the caller unaware of a relink that is
+  // still going to land, so the backdrop and close button wait for it.
+  const handleDismiss = () => {
+    if (linking === null) onClose();
+  };
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center pt-[10vh]"
+      onClick={handleDismiss}
+    >
+      <div className="absolute inset-0 bg-ctp-crust/70 backdrop-blur-[2px]" />
+      <div
+        className="relative bg-ctp-base border border-ctp-surface1 rounded-xl shadow-2xl w-full max-w-lg max-h-[70vh] flex flex-col animate-fade-in"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="p-4 border-b border-ctp-surface1">
+          <div className="flex items-center justify-between mb-3">
+            <h3 className="text-sm font-semibold text-ctp-text">Select TMDB Title</h3>
+            <button
+              type="button"
+              onClick={handleDismiss}
+              disabled={linking !== null}
+              className="text-ctp-overlay2 hover:text-ctp-text text-lg leading-none disabled:opacity-50"
+            >
+              {'✕'}
+            </button>
+          </div>
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => handleInput(e.target.value)}
+            placeholder="Search TMDB for a drama or movie..."
+            className="w-full bg-ctp-surface0 border border-ctp-surface1 rounded-lg px-3 py-2 text-sm text-ctp-text placeholder:text-ctp-overlay2 focus:outline-none focus:border-ctp-blue"
+          />
+        </div>
+
+        <div className="flex-1 overflow-y-auto p-2">
+          {loading && <div className="text-xs text-ctp-overlay2 p-3">Searching...</div>}
+          {error && <div className="text-xs text-ctp-red p-3">{error}</div>}
+          {!loading && !error && results.length === 0 && query.trim() && (
+            <div className="text-xs text-ctp-overlay2 p-3">No results</div>
+          )}
+          {results.map((media) => (
+            <button
+              key={`${media.tmdbType}-${media.tmdbId}`}
+              type="button"
+              disabled={linking !== null}
+              onClick={() => void handleSelect(media)}
+              className="w-full flex items-center gap-3 p-2.5 rounded-lg hover:bg-ctp-surface0 transition-colors text-left disabled:opacity-50"
+            >
+              {media.posterUrl ? (
+                <img
+                  src={media.posterUrl}
+                  alt=""
+                  className="w-10 h-14 rounded object-cover shrink-0 bg-ctp-surface1"
+                />
+              ) : (
+                <div className="w-10 h-14 rounded bg-ctp-surface1 shrink-0" />
+              )}
+              <div className="min-w-0 flex-1">
+                <div className="text-sm text-ctp-text truncate">{media.title}</div>
+                {media.originalTitle !== media.title && (
+                  <div className="text-xs text-ctp-subtext0 truncate">{media.originalTitle}</div>
+                )}
+                <div className="text-xs text-ctp-overlay2 mt-0.5">
+                  {media.tmdbType === 'movie' ? 'Movie' : 'TV'}
+                  {media.year ? ` · ${media.year}` : ''}
+                  {media.isAnimation ? ' · Animation' : ''}
+                </div>
+              </div>
+              {linking === media.tmdbId ? (
+                <span className="text-xs text-ctp-blue shrink-0">Linking...</span>
+              ) : (
+                <span className="text-xs text-ctp-overlay2 shrink-0">Select</span>
+              )}
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

stats/src/components/vocabulary/WordDetailPanel.tsx

@@ -1,7 +1,6 @@
 import { useRef, useState, useEffect } from 'react';
 import { useWordDetail } from '../../hooks/useWordDetail';
 import { apiClient } from '../../lib/api-client';
-import { assetUrl } from '../../lib/asset-url';
 import { epochMsFromDbTimestamp, formatNumber, formatRelativeDate } from '../../lib/formatters';
 import {
   buildStatsMineCardParams,
@@ -167,7 +166,7 @@ export function WordDetailPanel({
         if (typeof Notification !== 'undefined' && Notification.permission === 'granted') {
           new Notification('Anki Card Created', {
             body: `Mined: ${label}`,
-            icon: assetUrl('favicon.png'),
+            icon: '/favicon.png',
           });
         } else if (typeof Notification !== 'undefined' && Notification.permission !== 'denied') {
           Notification.requestPermission().then((p) => {

stats/src/lib/api-client.test.ts

@@ -1,36 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { apiClient, BASE_URL, resolveStatsBaseUrl } from './api-client';
+import { apiClient, BASE_URL } from './api-client';
-
-test('resolveStatsBaseUrl prefers apiBase query parameter for file-based overlay mode', () => {
-  const baseUrl = resolveStatsBaseUrl({
-    protocol: 'file:',
-    origin: 'null',
-    search: '?overlay=1&apiBase=http%3A%2F%2F127.0.0.1%3A6123',
-  });
-
-  assert.equal(baseUrl, 'http://127.0.0.1:6123');
-});
-
-test('resolveStatsBaseUrl falls back to configured window origin for browser mode', () => {
-  const baseUrl = resolveStatsBaseUrl({
-    protocol: 'http:',
-    origin: 'http://127.0.0.1:6123',
-    search: '',
-  });
-
-  assert.equal(baseUrl, 'http://127.0.0.1:6123');
-});
-
-test('resolveStatsBaseUrl keeps legacy localhost fallback for file mode without apiBase', () => {
-  const baseUrl = resolveStatsBaseUrl({
-    protocol: 'file:',
-    origin: 'null',
-    search: '?overlay=1',
-  });
-
-  assert.equal(baseUrl, 'http://127.0.0.1:6969');
-});
 
 test('getAnimeCoverUrl appends retry tokens for late cover refreshes', () => {
   const getAnimeCoverUrl = apiClient.getAnimeCoverUrl as (
@@ -38,10 +8,7 @@ test('getAnimeCoverUrl appends retry tokens for late cover refreshes', () => {
     retryToken?: number,
   ) => string;
 
-  assert.equal(
+  assert.equal(getAnimeCoverUrl(42, 3), `${BASE_URL}/api/stats/anime/42/cover?coverRetry=3`);
-    getAnimeCoverUrl(42, 3),
-    'http://127.0.0.1:6969/api/stats/anime/42/cover?coverRetry=3',
-  );
 });
 
 test('getAnimeMergeRecommendations loads pending duplicate pairs', async () => {

stats/src/lib/api-client.ts

@@ -15,6 +15,7 @@ import type {
   StatsMergeAnimeResponse,
   StatsMoveVideoRequest,
   StatsMoveVideoResponse,
+  StatsTmdbAssignment,
   StatsTrendGroupBy,
   StatsTrendRange,
   StatsVideoWatchedRequest,
@@ -23,24 +24,8 @@ import type { StatsMineCardParams, StatsMineCardResponse } from './mining';
 import { appendCoverRetryToken } from './cover-retry';
 import { trackDelete } from './delete-progress';
 
-type StatsLocationLike = Pick<Location, 'protocol' | 'origin' | 'search'>;
+// Both browser and in-app dashboards use the server that served the page.
-
+export const BASE_URL = typeof window === 'undefined' ? '' : window.location.origin;
-export function resolveStatsBaseUrl(location?: StatsLocationLike): string {
-  const resolvedLocation =
-    location ??
-    (typeof window === 'undefined'
-      ? { protocol: 'file:', origin: 'null', search: '' }
-      : window.location);
-
-  const queryApiBase = new URLSearchParams(resolvedLocation.search).get('apiBase')?.trim();
-  if (queryApiBase) {
-    return queryApiBase;
-  }
-
-  return resolvedLocation.protocol === 'file:' ? 'http://127.0.0.1:6969' : resolvedLocation.origin;
-}
-
-export const BASE_URL = resolveStatsBaseUrl();
 
 async function fetchResponse(path: string, init?: RequestInit): Promise<Response> {
   const res = await fetch(`${BASE_URL}${path}`, init);
@@ -256,6 +241,15 @@ export const apiClient = {
       body: JSON.stringify(info),
     });
   },
+  searchTmdb: (query: string) =>
+    fetchJson('tmdbSearch', `/api/stats/tmdb/search?q=${encodeURIComponent(query)}`),
+  reassignAnimeTmdb: async (animeId: number, info: StatsTmdbAssignment): Promise<void> => {
+    await fetchResponse(`/api/stats/anime/${animeId}/tmdb`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(info satisfies StatsTmdbAssignment),
+    });
+  },
   mineCard: async (params: StatsMineCardParams): Promise<StatsMineCardResponse> => {
     const res = await fetch(`${BASE_URL}/api/stats/mine-card?mode=${params.mode}`, {
       method: 'POST',