fix(stats): preserve season boundaries during AniList merge resolution

- Allow manual cross-season reassignment without merging entries - Require validated title matches for automatic merges - Share title normalization across AniList and stats flows
fix(stats): review fuzzy AniList duplicates before merging
2026-08-12 13:55:51 -07:00 · 2026-08-11 23:40:27 -07:00 · 2026-08-11 23:11:39 -07:00 · 2026-08-11 00:04:03 -07:00 · 2026-08-10 23:50:37 -07:00 · 2026-08-10 23:18:02 -07:00
269 changed files with 18611 additions and 3240 deletions
@@ -1,5 +1,68 @@
 # Changelog

+## v0.19.2 (2026-08-04)
+
+### Changed
+- Subsync: The sync modal now lets you choose both the reference subtitle (correct timing) and the out-of-sync subtitle to retime, for both alass and ffsubsync. alass can also use the loaded video's audio as a reference for local files. Retiming the secondary track now reloads the result into the secondary slot instead of overwriting the primary subtitle.
+
+### Fixed
+- Streaming Subtitle Tokenization: Jellyfin streams now seed subtitle tokenization directly from the downloaded subtitle file instead of relying on an mpv event that could be missed, and prefetching now runs to the end of the file and clears between episodes. The tokenization cache was raised from 256 to 2500 lines, and parsed cues are no longer lost when the active subtitle track briefly can't be resolved (e.g. switching to an embedded track). Together these prevent episodes from falling back to slow, line-by-line tokenization during playback.
+- Overlay: Subtitle lines now appear immediately at their cue time even on a tokenization cache miss, upgrading in place once tokens and annotations are ready, instead of waiting on a line still being processed. A failed tokenization is no longer cached as plain text, so repeated lines get another chance at annotations.
+- Background Logging: Background startup now respects the configured logging level when no explicit log level is passed.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Patched three high-severity dependency advisories (`undici`, `brace-expansion`, `fast-uri`).
+
+</details>
+
+## v0.19.1 (2026-08-01)
+
+### Added
+- Word Card Type: Adds a setting (Settings > Mining/Anki > Kiku/Lapis Features > "Word Card Type") to choose which card-type flag SubMiner marks on Kiku/Lapis word cards — `word-and-sentence` (default), `click`, `sentence`, `audio`, or `none`. Click cards (`IsClickCard`) can now be flagged, and setting any card-type flag clears the others so a note can't claim two types at once.
+
+### Fixed
+- Yomitan Popup: Fixes the macOS Yomitan popup going inert after mining a card — clicks outside the popup no longer pass through to mpv, and scrolling over the popup scrolls its definitions instead of seeking playback.
+- YouTube Playlist Links: Fixes opening a video from a playlist URL (e.g. a Watch Later link with `list=`/`index=`) timing out while probing subtitles, metadata, or the playback URL.
+
+## v0.19.0 (2026-07-29)
+
+### Added
+- Anki Maturity Highlighting: Known-word subtitle highlights can now be colored by Anki card maturity (new, learning, young, mature), similar to asbplayer. Tier thresholds and colors are configurable, with a runtime toggle and an updated help legend.
+- Post-Playback Menu: After a watch-history episode ends, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit. The pre-playback series menu now offers the previous episode too.
+- Delete Library Entries: The stats Library detail view can now delete an entire title in one step (episodes, sessions, subtitle lines, rollups, cover art, and vocabulary counts). Delete progress is now shown app-wide via a progress bar and status toast instead of disappearing when you switch tabs.
+- Cross-Machine Sync: Added SSH-based syncing of stats and watch history between machines, available from the tray ("Sync Stats & History") or `subminer sync`, with saved devices, per-host sync direction, background auto-sync, connection testing, manual snapshots, and support for Windows remotes.
+- TsukiHime Subtitle Downloads: Added subtitle downloads for the current video via TsukiHime, loading Japanese as the primary track and your configured secondary language directly into mpv.
+
+### Changed
+- Clipboard-Video Shortcut: The "append clipboard video to queue" shortcut is now configurable.
+
+### Fixed
+- AniList Season Resolution: Season 2+ files now resolve to the correct AniList entry instead of silently falling back to season 1 (which mismatched character dictionaries and watch progress). Manual overrides now stay scoped per season, fix both the dictionary and progress tracking together, and also correct per-season cover art.
+- Subtitle Annotation Accuracy: Fixed several annotation edge cases, including inconsistent POS exclusions on merged quote-particle tokens, dropped annotations on supplementary-plane kanji, katakana punctuation wrongly treated as noise, and certain kanji vocabulary losing N+1 highlighting eligibility.
+- AnkiConnect Proxy Port Conflict: Video startup no longer crashes when another process already holds the configured AnkiConnect proxy port; a notification now explains how to resolve it.
+- AppImage Quit Crash: Fixed a "Service Crash" desktop notification appearing after closing a video when running the Linux AppImage.
+- Autoplay Pause Timing: Fixed playback resuming a few seconds before subtitle tokenization warmup finished, most noticeable when resuming mid-episode or when a cue starts within the first two seconds.
+- Stats Known-Word Count: Fixed stats reporting 0 known words for every session after the known-word cache format changed.
+- Stats Library Cover Art: Relinking a title to a different AniList entry now updates its cover in the Library grid immediately instead of leaving a stale, mismatched cover cached.
+- Rofi Prompt Spacing: Rofi menu prompts now keep a space before the input field instead of running into the placeholder text.
+- Stats Settings & Reliability: Hardened stats settings validation (nested/legacy AnkiConnect config now falls back safely instead of breaking) and stats routes against malformed requests and other edge cases.
+- Stats Delete Performance: Deleting sessions, episodes, and library entries is now dramatically faster and no longer stalls playback (e.g. a 12-episode title dropped from about a minute to under a second on a large library); the Vocabulary tab also loads much faster. The first launch after upgrading runs a one-time database migration.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Added a golden-file regression test corpus for the tokenizer/annotation pipeline, plus scripts to record new fixtures and diff against stock Yomitan.
+- Consolidated renderer modal state handling into a descriptor registry.
+- Consolidated CI quality checks (PR, stable, and prerelease) into one reusable workflow with mpv plugin tests and dependency audits.
+- Removed the unused stats IPC transport and unified stats dashboard HTTP types with the backend contract.
+- Added a script to verify known-word highlight tiers against live Anki data outside of playback.
+
+</details>
+
 ## v0.18.0 (2026-07-10)

 ### Added
@@ -66,7 +66,7 @@ Local stats dashboard tracking watch time, vocabulary growth, mining throughput,
 Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.

 <div align="center">
-  <img src="docs-site/public/screenshots/playlist-browser.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
+  <img src="docs-site/public/screenshots/playlist-browser.png" width="800" alt="Playlist browser modal showing sibling episode files beside the active mpv queue">
 </div>

 <br>
@@ -90,6 +90,14 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
    <td><b>Jimaku</b></td>
    <td>Search and download Japanese subtitles</td>
  </tr>
+  <tr>
+    <td><b>TsukiHime</b></td>
+    <td>Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (<code>Ctrl+Shift+T</code>) — no API key, requires <code>xz</code> on your <code>PATH</code></td>
+  </tr>
+  <tr>
+    <td><b>AniSkip</b></td>
+    <td>Automatic intro detection with chapter markers and a one-key skip (<code>TAB</code> by default)</td>
+  </tr>
  <tr>
    <td><b>alass / ffsubsync</b></td>
    <td>Manual subtitle retiming — requires <code>alass</code> or <code>ffsubsync</code> on your <code>PATH</code> (optional; subtitle syncing is disabled without them)</td>
@@ -110,18 +118,19 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open

 ## Requirements

-Only **mpv** and Anki+AnkiConnect are required. Everything else is optional but enhances the experience.
+Only **mpv** is required to run SubMiner. Anki + AnkiConnect are required to mine cards, which is the point of the app, but everything else is optional.

 | Dependency           | Status           | What it does                                             |
-| -------------------- | ----------- | ---------------------------------------- |
+| -------------------- | ---------------- | -------------------------------------------------------- |
 | mpv                  | Required         | The video player SubMiner overlays on                    |
-| Anki + AnkiConnect   | Required    | Card creation from the Yomitan popup     |
+| Anki + AnkiConnect   | Required to mine | Card creation from the Yomitan popup                     |
 | ffmpeg               | Recommended      | Audio clips & screenshots for Anki cards                 |
 | MeCab + mecab-ipadic | Recommended      | More precise annotations and filtering                   |
 | yt-dlp               | Optional         | YouTube playback                                         |
-| fzf / rofi           | Optional    | Video picker in the launcher             |
+| xz                   | Optional         | TsukiHime subtitle downloads (not on Windows by default) |
 | alass / ffsubsync    | Optional         | Subtitle sync                                            |
 | guessit              | Optional         | Better anime title and episode detection                 |
+| fzf / rofi           | Optional         | Video picker in the `subminer` launcher (Linux/macOS)    |

 <details>
 <summary><b>Platform-specific install commands</b></summary>
@@ -138,9 +147,23 @@ sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic
 brew install mpv ffmpeg mecab mecab-ipadic
 ```

-**Windows:** Install [mpv](https://mpv.io/installation/) and [ffmpeg](https://ffmpeg.org/download.html) and ensure both are on `PATH`.
+**Windows:**

-See the [full requirements list](https://docs.subminer.moe/installation#1-install-requirements) for optional dependencies.
+```powershell
+winget install shinchiro.mpv
+winget install Gyan.FFmpeg
+```
+
+Then reopen your terminal and check `mpv --version` and `ffmpeg -version`. winget puts `ffmpeg` on `PATH` automatically; mpv uses a regular installer that may not, so if `mpv` is not found, either add its folder (usually `%LOCALAPPDATA%\Programs\mpv`) to `PATH` or set `mpv.executablePath` during first-run setup.
+
+[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything, since it is the only one that also carries `xz`:
+
+```powershell
+scoop bucket add extras
+scoop install extras/mpv main/ffmpeg main/yt-dlp main/xz
+```
+
+See the [full requirements list](https://docs.subminer.moe/installation#_1-install-requirements) for optional dependencies.

 </details>

@@ -166,6 +189,11 @@ paru -S subminer-bin
 mkdir -p ~/.local/bin
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage \
 && chmod +x ~/.local/bin/SubMiner.AppImage
+```
+
+The AppImage is all you need. The optional `subminer` command-line launcher runs on [Bun](https://bun.sh), and first-run setup can install both for you. To grab it manually instead, install Bun first, then:
+
+```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
 && chmod +x ~/.local/bin/subminer
 ```
@@ -26,7 +26,7 @@
        "eslint": "^10.8.0",
        "prettier": "^3.8.1",
        "typescript": "^5.9.3",
-        "undici": "7.28.0",
+        "undici": "7.29.0",
      },
    },
  },
@@ -36,8 +36,9 @@
  "overrides": {
    "@xmldom/xmldom": "0.8.13",
    "app-builder-lib": "26.15.3",
-    "brace-expansion": "5.0.8",
+    "brace-expansion": "5.0.9",
    "electron-builder-squirrel-windows": "26.15.3",
+    "fast-uri": "3.1.5",
    "form-data": "4.0.6",
    "ip-address": "10.2.0",
    "js-yaml": "4.3.0",
@@ -46,6 +47,7 @@
    "picomatch": "4.0.4",
    "tar": "7.5.21",
    "tmp": "0.2.7",
+    "undici": "7.29.0",
  },
  "packages": {
    "@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
@@ -266,7 +268,7 @@

    "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],

-    "brace-expansion": ["brace-expansion@5.0.8", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-JZyDyq3D4AUifKTPOB7DELf6XsB3WdPuNxCtob1vFXPsSXhdAiHBWJ/tJ8HAc9aH84BK+5JFZLNkJKx3G9kzQg=="],
+    "brace-expansion": ["brace-expansion@5.0.9", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg=="],

    "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],

@@ -404,7 +406,7 @@

    "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],

-    "fast-uri": ["fast-uri@3.1.4", "", {}, "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw=="],
+    "fast-uri": ["fast-uri@3.1.5", "", {}, "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw=="],

    "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],

@@ -714,7 +716,7 @@

    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],

-    "undici": ["undici@7.28.0", "", {}, "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA=="],
+    "undici": ["undici@7.29.0", "", {}, "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw=="],

    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],

@@ -754,8 +756,6 @@

    "@discordjs/rest/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],

-    "@discordjs/rest/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
-
    "@discordjs/util/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],

    "@electron/asar/commander": ["commander@5.1.0", "", {}, "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg=="],
@@ -808,8 +808,6 @@

    "node-gyp/env-paths": ["env-paths@2.2.1", "", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],

-    "node-gyp/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
-
    "node-gyp/which": ["which@6.0.1", "", { "dependencies": { "isexe": "^4.0.0" }, "bin": { "node-which": "bin/which.js" } }, "sha512-oGLe46MIrCRqX7ytPUf66EAYvdeMIZYn3WaocqqKZAxrBpkqHfL/qvTyJ/bTk5+AqHCjXmrv3CEWgy368zhRUg=="],

    "pkijs/@noble/hashes": ["@noble/hashes@1.4.0", "", {}, "sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg=="],
@@ -1,5 +0,0 @@
-type: added
-area: overlay
-
- Known-word subtitle highlights can now be colored by Anki card maturity (new, learning, young, mature) like asbplayer. Enable with `ankiConnect.knownWords.maturityEnabled`; the mature interval threshold (`matureThresholdDays`, default 21) and the four tier colors (`subtitleStyle.knownWordMaturityColors`) are configurable, and a runtime option toggles it in-session. The session help color legend shows the four tier colors while maturity highlighting is on.
- Tiers follow Anki's own card counts: the interval tiers exclude cards in the learning/relearning queue, so a lapsed card shows the learning color instead of young (its interval is reset to at least 1 day, which previously made the learning tier unreachable). A note with a mature card alongside a relearning card still shows mature.
@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
- Applied configured primary POS exclusions consistently to merged trailing quote-particle tokens, preserved annotations for supplementary-plane kanji, and stopped treating katakana punctuation as kana-only annotation noise.
- Kept kanji vocabulary tagged `名詞/非自立` eligible for N+1 highlighting, consistent with frequency, JLPT, and vocabulary persistence.
@@ -0,0 +1,7 @@
+type: added
+area: overlay
+
+- Added an in-app changelog modal, opened from the tray ("View Changelog") or the "What's New" button on the update-available notification, which now stays on screen so "Update" is still reachable after reading the notes. It renders inside the player bounds when a video is playing and in its own window otherwise, the same as the help modal.
+- The changelog is fetched from the newest published release, so release notes for versions newer than the installed build are visible; a failed download falls back to the changelog bundled with the install and says so in the modal.
+- Versions are foldable: the current `0.x` line is expanded and older lines are folded, matching the docs-site changelog. A badge marks the installed version and newer versions are tagged "New".
+- Keyboard: `J`/`K` or arrows move between versions, `Enter` folds/unfolds, `R` refetches, `Esc` closes.
@@ -1,4 +0,0 @@
-type: changed
-area: shortcuts
-
- Made the clipboard-video playlist shortcut configurable through `shortcuts.appendClipboardVideoToQueue`.
@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
- Prevented video startup from crashing when another process already owns the configured AnkiConnect proxy port, and added a notification explaining how to resolve the conflict.
@@ -1,4 +0,0 @@
-type: fixed
-area: app
-
- Fixed "Service Crash" desktop notifications (KDE DrKonqi) after closing a video when running the Linux AppImage: the short-lived background bootstrap spawned a Chromium GPU child that outlived it (surviving `app.exit`) and died with SIGBUS at session end when the bootstrap's FUSE mount was finally released. The bootstrap now runs with the GPU in-process so it leaves no children behind, and the detached app's mount remains supervised until its Chromium children finish. Set `SUBMINER_NO_APPIMAGE_MOUNT_KEEPALIVE=1` to disable the detached-app mount supervisor.
@@ -1,4 +0,0 @@
-type: fixed
-area: character dictionary
-
- Kept manual AniList overrides active across episodes in the same season directory when filename guesses differ.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed `mpv.pauseUntilOverlayReady` releasing playback seconds before tokenization warmup finished: startup subtitle priming emits the current cue untokenized so the overlay can paint early, and that emission was treated as the autoplay-readiness signal as soon as the overlay window loaded. The autoplay gate now ignores untokenized subtitle payloads while tokenization warmup is pending, so playback resumes only after the first tokenized delivery (or the post-warmup release). Most visible when resuming mid-episode or when a subtitle cue starts within the first two seconds.
@@ -1,5 +0,0 @@
-type: fixed
-area: stats
-
- Stats reported 0 known words for every session after the known-word cache gained maturity tiers. The stats server carried its own copy of the cache parser that only recognized versions up to 3, so the new v4 file was read as "no cache" rather than as a format it should understand.
- The cache format, its parser, and the derived known-word set now live in one module that both the cache manager and the stats server read, and the version dispatch ends in an exhaustive check so a future format bump fails the build instead of silently reporting zero. A cache that exists but does not parse now logs a warning rather than passing for an empty one.
@@ -1,7 +0,0 @@
-type: internal
-area: tokenizer
-
- Added a golden-file regression corpus for the tokenizer/annotation pipeline: recorded Yomitan backend responses and MeCab tokens replay through the real tokenizeSubtitle pipeline in bun tests without Electron or dictionaries.
- Added `record-tokenizer-fixture:electron` script to capture new fixtures from a live Yomitan/MeCab session, with flags for known words, JLPT levels, and annotation toggles.
- Seeded eleven fixtures covering the #147–#156 regression classes (grammar-helper suppression, lexical くれる, kanji non-independent nouns, N+1 targeting, reading collisions, unparsed runs, ordinal/honorific prefixes).
- Added `compare-yomitan-api:electron` script that diffs SubMiner tokenization against a stock Yomitan instance via the yomitan-api bridge (segmentation, readings, headword forms).
@@ -1,5 +0,0 @@
-type: added
-area: launcher
-
- After a watch-history episode ends or mpv closes, the fzf or rofi launcher returns to that series with options to play the previous episode, rewatch, play the next episode, select another episode, or quit SubMiner. Previous and Next continue across season directories.
- The action menu shown right after picking a series from `subminer -H` now also offers the previous episode, matching the menu shown after playback.
@@ -0,0 +1,6 @@
+type: added
+area: stats
+
+- Library: duplicate cards for the same show can now be combined. Press "Select" above the library grid, tick the cards, and use "Merge Selected"; the dialog picks which entry to keep and moves every episode onto it. Sessions, mined cards, and watch time are preserved, the emptied entries disappear, and remembered title aliases keep future episodes on the merged card.
+- Library: episodes can be reassigned to another library entry from the "→" button on an episode row, which is the fix when one file lands under a stray title (e.g. an episode name parsed as the series). Emptying an entry this way removes it and returns to the grid.
+- Library: exact AniList title matches with compatible seasons fold duplicate cards automatically. Fuzzy same-AniList matches appear as dismissible "Possible duplicate" reviews instead of changing the library without confirmation; conflicting explicit seasons are left alone.
@@ -1,4 +0,0 @@
-type: internal
-area: overlay
-
- Consolidated renderer modal state handling into a descriptor registry.
@@ -1,4 +0,0 @@
-type: internal
-area: release
-
- Consolidated pull request, stable release, and prerelease quality checks in one reusable workflow, with Lua mpv plugin tests and blocking high-severity dependency audits running in every gate.
@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
- Rofi menu prompts now keep a space between the prompt text and the input field instead of running into the search placeholder.
@@ -1,5 +0,0 @@
-type: fixed
-area: stats
-
- Validated nested and legacy AnkiConnect settings after splitting the resolver, preserving valid modern overrides while warning and falling back for invalid primitive values.
- Hardened stats routes against malformed IDs and static paths, stalled AniList searches, word-mining media collisions, missing Yomitan bridges, and throwing timing observers.
@@ -0,0 +1,20 @@
+type: changed
+area: subtitles
+
+- Subtitle tokenization no longer runs a duplicate full `parseText` pass per line: the termsFind scanner walk is now the only tokenizer and emits its own hoverable filler runs for unmatched text (parseText is kept only as an error fallback). This roughly halves the dictionary work per line.
+- The Yomitan scanning helpers are now installed once per parser window (`__subminerYomitanScan`) instead of re-shipping and re-parsing a ~500-line script for every subtitle line; each line only evaluates a tiny call.
+- termsFind lookups are cached across subtitle lines in a window-persistent LRU keyed by substring, so repeated particles and verb forms stop costing backend round trips. The cache invalidates on dictionary/settings changes and window reloads.
+- The scanner walk now skips lookups at punctuation and whitespace positions (latin letters and digits still look up, e.g. Tシャツ). The shrinking-window retry ladder keeps following the consumed lengths the backend reports, and only blind guesses (windows the backend consumed whole, which tell it nothing) are capped at four per position. A line that hits that cap escalates to a single `parseText` for the whole line, so a hard line still resolves to dictionary tokens instead of an unparsed run, without letting the ladder run to one lookup per window length.
+- Tokenizer runtime dependencies are built once instead of per line, fixing a JLPT lookup cache that never hit (it was keyed on a per-call closure identity and leaked a Map per line) and a `which mecab` availability check that re-ran synchronously on every line when MeCab is absent.
+- Subtitle changes no longer restart the prefetch run per line (which discarded in-flight tokenization work); prefetch now only pauses for the live line and restarts on real seeks, cache invalidation, or option changes. Prefetch also stays paused for the whole time the subtitle processing controller is working on the line, including the provisional raw emit that precedes tokenization, so it never competes with the on-screen line for the parser window. The pause is released when the controller reports it has settled, which also covers the lines that finish without an emit (a suppressed duplicate or a failed tokenization) and used to leave prefetching paused indefinitely.
+- Added per-stage debug timings (`scanMs`, `mecabMs`, `frequencyMs`, `annotateMs`) to the subtitle tokenization pipeline log.
+- Fixed a reading that stopped covering its surface when an unmatched kana run extended the preceding token (for example a trailing る on 待ち合わせ), which silently disabled the known-word reading fallback for those tokens.
+- Subtitle prefetching no longer stays paused for the rest of a cue when the same subtitle text is reported twice and there is nothing to tokenize. This covers the startup and overlay priming paths as well as ordinary subtitle changes.
+- Character name and image lookups are now refreshed centrally whenever a character dictionary sync changes its content, so a newly added name can no longer be skipped by a stale candidate list.
+- A subtitle that was on screen when its annotations were invalidated (by mining a card, for example) is now re-annotated instead of staying plain for the rest of the line.
+- Character name annotations no longer cost a dictionary lookup at every position in a line. The scanner now knows which name forms the current title's character dictionary actually contains and only checks where one can start, which removes the whole overhead of having the character dictionary enabled (measured: 21 lookups per line down to 10, the same as with it disabled). Titles with no cached character data keep the previous exhaustive scan, so a missing snapshot costs speed rather than a missing name.
+- The cross-line termsFind cache is now bounded by the number of retained dictionary entries as well as by key count, so a run of lookups that each carry hundreds of entries with full glossaries cannot grow the parser window's memory without limit. The budget is re-checked when a lookup resolves, so a single oversized response is dropped rather than parked in the cache and reused.
+- The unnamed-mob disambiguator filter (Girl A / Girl B) now only drops a single letter or digit split off a name, instead of every one-character term: a name that is genuinely one character keeps its terms whatever the script (𠮷, あ, 별 김, ア・ベ). The character dictionary and the scanner's name pre-pass also share one Han code-point table now, so a name the dictionary accepts is a name the scanner will look for.
+- A character name written in halfwidth katakana takes part in the greedy name pre-pass again, so a longer generic word can no longer swallow the start of it, and it now carries a reading (it used to come out blank, which disables known-word matching and frequency lookups for the token). Voiced halfwidth kana compose properly, so ｶﾞｸ reads ガク rather than カﾞク, and kana normalization folds halfwidth throughout so those tokens compare equal to the same word written fullwidth. Because the fold makes halfwidth text indexable, the character-name prefilter now judges halfwidth spellings like any other, and a position only bypasses it when an unfoldable voiced mark sits inside the lookup window. That covers a name that starts on a kanji and turns halfwidth later (山ｶﾞｸ), and one stretched out with emphatic characters in between (山ーーーーーーｶﾞｸ).
+- Dictionary-entry classification (source dictionaries, character-dictionary media ids) is memoized per entry object for as long as the entry is cached, instead of being recomputed for every headword comparison and every retry window.
+- Autoplay priming no longer broadcasts the plain subtitle twice: it tells the processing controller the line has already been painted, so the controller goes straight to the annotated payload.
@@ -1,8 +0,0 @@
-type: added
-area: sync
-
- Added cross-machine immersion sync for stats and watch history over SSH, available as a window (**Sync Stats & History** in the tray menu, or `subminer sync --ui`) and as a command (`subminer sync <host>`, with `--push` / `--pull` for one-way insert-only transfers). The window keeps saved devices with per-host direction, one-click sync with live stage-by-stage progress and separate merge summaries for each machine, connection testing for first-time setup, cancellable runs while the app/stats server/playback is active, and manual database snapshots (create/merge/reveal/delete, stored in `/tmp/subminer-db-snapshots/` by default). Hosts with auto-sync enabled sync in the background on a configurable interval, including during playback, with results reported as overlay notifications; hosts synced from the CLI are remembered in `<config dir>/sync-hosts.json` and appear in the window automatically.
- Merges are an insert-only union keyed on session UUIDs / video keys / series title keys, so re-syncing is idempotent and nothing is double-counted: each side snapshots its database (`VACUUM INTO`) from a consistent WAL point, snapshots are exchanged with `scp`, and each machine merges the other's data transactionally. Lifetime totals and daily/monthly rollups are updated incrementally (history older than the session retention window is preserved), unfinished sessions are excluded until a later sync sees them finalized, and remote-only historical rollups are copied only when they do not conflict with retained local session history. Sync aborts on stats schema version mismatches and refuses to run while the stats daemon or a live mpv session is active (`--force` overrides).
- The sync engine runs only inside the app: the sync window and the `subminer sync` command both delegate to `SubMiner --sync-cli` (headless, works over SSH with no display), so neither machine needs bun or the command-line launcher. A remote machine only needs SubMiner itself, found automatically as the app binary or via the launcher proxy.
- Windows remotes are supported: sync detects the remote shell (POSIX, cmd, or PowerShell) and manages remote temp files through SubMiner itself (`sync --make-temp` / `--remove-temp`) instead of `mktemp` / `rm`, so a Windows machine with the built-in OpenSSH Server works as a sync remote, found in its default Windows install location automatically.
- Added supporting flags: `subminer sync <host> --check` tests the SSH connection and remote launcher availability without syncing, `subminer sync --snapshot <file>` and `--merge <file>` expose the underlying steps for manual transfers, and `subminer sync --json` emits machine-readable NDJSON progress (the protocol the sync window consumes).
@@ -1,4 +0,0 @@
-type: added
-area: overlay
-
- Added TsukiHime subtitle downloads for the current video, with Japanese primary and configured secondary-language tracks loaded directly into mpv.
@@ -1,4 +0,0 @@
-type: internal
-area: stats
-
- Removed the unused stats IPC data transport and unified the stats dashboard's HTTP wire types with the backend contract.
@@ -1,7 +0,0 @@
-type: internal
-area: tokenizer
-
- Added `verify-known-word-highlights:electron` script: tokenizes a real subtitle file through the app's Yomitan/MeCab pipeline with the live known-word cache, prints each line in the configured tier colors, and summarizes the tier counts so highlighting can be checked outside of playback.
- Added `--audit`, which re-derives every highlighted tier from live Anki card data (`notesInfo` + `cardsInfo` intervals) and reports each token whose rendered tier disagrees, catching both stale cache entries and tier-classification bugs.
- Added `--profile-copy` so the check can run while SubMiner is open (Electron locks the Yomitan userData dir), plus `--refresh`, `--limit`, `--json`, and `--quiet`.
- Added `KnownWordCacheManager.getKnownWordMatchNoteIds`, exposing the note ids behind a known-word match so an audit can trace a rendered tier back to the exact Anki notes.
@@ -0,0 +1,4 @@
+type: fixed
+area: playback
+
+- XWayland/X11 mode (`--backend=x11`, or the automatic fallback on non-Hyprland/Sway Wayland sessions) no longer forces mpv onto `--vo=gpu --gpu-api=opengl`. It now only pins the window context (`--gpu-context=x11vk,x11egl,x11`), so a `vo=gpu-next` config keeps its renderer, API, and user shaders. Forcing the legacy OpenGL renderer crashed mpv on the first fullscreen toggle for anyone using a gpu-next user shader that emits a 4-component LUMA hook (ArtCNN and friends), which asserts in mpv's old renderer (`copy_image: *offset + count < sizeof(dst)`) as soon as the shader's upscale-only condition turns on.
@@ -523,7 +523,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
  // Shared AI provider transport settings are read from top-level ai and typically require restart.
  // Most other AnkiConnect settings still require restart.
  // ==========================================
@@ -605,7 +605,10 @@
      "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
      "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
      "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
-    } // Is kiku setting.
+    }, // Is kiku setting.
+    "lapisKiku": {
+      "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
+    } // Lapis kiku setting.
  }, // Automatic Anki updates and media generation options.

  // ==========================================
@@ -39,7 +39,7 @@ SubMiner monitors playback and triggers an AniList progress update when an episo
 The update flow:

 1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename and path. Season folders such as `Season 2` are treated as a strong season signal. SubMiner tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
-2. **AniList search** -- The detected title is searched against the AniList GraphQL API. For season 2 and later files, SubMiner searches the season-specific title first, then falls back to the base title. SubMiner picks the best match by comparing titles (romaji, English, native) and filtering by episode count.
+2. **AniList search** -- The base title (with any `Season N` / `SN` marker stripped) is searched against the AniList GraphQL API, and SubMiner picks the best match by comparing titles (romaji, English, native, synonyms) and filtering by episode count. AniList has no notion of numbered seasons -- sequels are separate entries with their own titles (`Zoku`, `Kan`, `2nd Season`), so searching `<title> Season 3` finds nothing. For season 2 and later, SubMiner instead walks `SEQUEL` relations from the season 1 entry, preferring the TV line, and falls back to ordering the franchise's TV entries by air date when the relation chain is incomplete. If neither locates the season, SubMiner **skips the update** rather than writing progress to the season 1 entry, and tells you to pin the right entry with a [character dictionary override](/character-dictionary#correcting-anilist-matches).
 3. **Progress check** -- SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
 4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`, or `COMPLETED` when the watched episode is the final episode of the season (the "already at this progress" skip is bypassed for the final episode so completion still lands).

@@ -69,6 +69,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.

+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

 All AniList API calls go through a shared rate limiter that enforces a sliding window of 20 requests per minute. The limiter also reads AniList's `X-RateLimit-Remaining` and `Retry-After` response headers and pauses requests when the server signals throttling. This applies to both episode tracking and cover art fetching.
@@ -94,7 +96,7 @@ All AniList API calls go through a shared rate limiter that enforces a sliding w
 ```

 | Option                                      | Values                  | Description                                                                                                  |
-| ------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| ------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
 | `enabled`                                   | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                                |
 | `accessToken`                               | string                  | Explicit AniList access token override; when blank, SubMiner uses the stored encrypted token (default: `""`) |
 | `characterDictionary.maxLoaded`             | number                  | Number of recent media snapshots kept in the merged dictionary (default: `3`)                                |
@@ -289,6 +289,21 @@ Trigger with the mine sentence shortcut (`Ctrl/Cmd+S` by default). The card is c

 To mine multiple subtitle lines as one sentence card, use `Ctrl/Cmd+Shift+S` followed by a digit (1–9) to select how many recent lines to combine.

+## Word Card Type (Kiku/Lapis)
+
+Word cards get a card-type flag when SubMiner fills their sentence, whether that comes from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining. By default the flag is `IsWordAndSentenceCard`; pick a different one with `ankiConnect.lapisKiku.wordCardKind`.
+
+```jsonc
+"ankiConnect": {
+  "isKiku": { "enabled": true },
+  "lapisKiku": {
+    "wordCardKind": "click" // word-and-sentence (default), click, sentence, audio, none
+  }
+}
+```
+
+`click` marks `IsClickCard`, `sentence` marks `IsSentenceCard`, `audio` marks `IsAudioCard`, and `none` leaves the flags untouched for templates that manage them elsewhere. Whichever flag is chosen, the other card-type flags are cleared so the note never claims two card types. The setting is only read when `isKiku` or `isLapis` is enabled, and cards mined with Mine Sentence or Mine Audio keep their own flag.
+
 ## Field Grouping (Kiku)

 When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types like [Kiku](https://github.com/youyoumu/kiku) that support grouped sentence/audio/image fields.
@@ -314,7 +329,7 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
 ### What Gets Merged

 | Field    | Merge behavior                                |
-| -------- | ---------------------------------------- |
+| -------- | --------------------------------------------- |
 | Sentence | Both cards' sentences kept as grouped entries |
 | Audio    | Both cards' `[sound:...]` entries kept        |
 | Image    | Both cards' images kept                       |
@@ -75,8 +75,8 @@ src/
  renderer/                # Overlay renderer (modularized UI/runtime)
    handlers/              # Keyboard/mouse/gamepad interaction modules
    modals/                # Modal flows (Jimaku, Kiku, subsync, runtime options, session help,
-                           #   character dictionary, playlist browser, subtitle sidebar,
-                           #   YouTube track picker, controller config/debug/select)
+                           #   changelog, character dictionary, playlist browser, subtitle
+                           #   sidebar, YouTube track picker, controller config/debug/select)
    positioning/           # Subtitle position controller (drag-to-reposition)
  settings/                # Settings window UI (model, controls, markup)
  types/                   # Domain type modules (anki, config, integrations, ...)
@@ -1,6 +1,74 @@
 # Changelog

-## v0.18.0 (2026-07-10)
+## v0.19.2 (2026-08-04)
+
+**Changed**
+- Subsync: The sync modal now lets you choose both the reference subtitle (correct timing) and the out-of-sync subtitle to retime, for both alass and ffsubsync. alass can also use the loaded video's audio as a reference for local files. Retiming the secondary track now reloads the result into the secondary slot instead of overwriting the primary subtitle.
+
+**Fixed**
+- Streaming Subtitle Tokenization: Jellyfin streams now seed subtitle tokenization directly from the downloaded subtitle file instead of relying on an mpv event that could be missed, and prefetching now runs to the end of the file and clears between episodes. The tokenization cache was raised from 256 to 2500 lines, and parsed cues are no longer lost when the active subtitle track briefly can't be resolved (e.g. switching to an embedded track). Together these prevent episodes from falling back to slow, line-by-line tokenization during playback.
+- Overlay: Subtitle lines now appear immediately at their cue time even on a tokenization cache miss, upgrading in place once tokens and annotations are ready, instead of waiting on a line still being processed. A failed tokenization is no longer cached as plain text, so repeated lines get another chance at annotations.
+- Background Logging: Background startup now respects the configured logging level when no explicit log level is passed.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Patched three high-severity dependency advisories (`undici`, `brace-expansion`, `fast-uri`).
+
+</details>
+
+## v0.19.1 (2026-08-01)
+
+**Added**
+- Word Card Type: Adds a setting (Settings > Mining/Anki > Kiku/Lapis Features > "Word Card Type") to choose which card-type flag SubMiner marks on Kiku/Lapis word cards — `word-and-sentence` (default), `click`, `sentence`, `audio`, or `none`. Click cards (`IsClickCard`) can now be flagged, and setting any card-type flag clears the others so a note can't claim two types at once.
+
+**Fixed**
+- Yomitan Popup: Fixes the macOS Yomitan popup going inert after mining a card — clicks outside the popup no longer pass through to mpv, and scrolling over the popup scrolls its definitions instead of seeking playback.
+- YouTube Playlist Links: Fixes opening a video from a playlist URL (e.g. a Watch Later link with `list=`/`index=`) timing out while probing subtitles, metadata, or the playback URL.
+
+## v0.19.0 (2026-07-29)
+
+**Added**
+- Anki Maturity Highlighting: Known-word subtitle highlights can now be colored by Anki card maturity (new, learning, young, mature), similar to asbplayer. Tier thresholds and colors are configurable, with a runtime toggle and an updated help legend.
+- Post-Playback Menu: After a watch-history episode ends, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit. The pre-playback series menu now offers the previous episode too.
+- Delete Library Entries: The stats Library detail view can now delete an entire title in one step (episodes, sessions, subtitle lines, rollups, cover art, and vocabulary counts). Delete progress is now shown app-wide via a progress bar and status toast instead of disappearing when you switch tabs.
+- Cross-Machine Sync: Added SSH-based syncing of stats and watch history between machines, available from the tray ("Sync Stats & History") or `subminer sync`, with saved devices, per-host sync direction, background auto-sync, connection testing, manual snapshots, and support for Windows remotes.
+- TsukiHime Subtitle Downloads: Added subtitle downloads for the current video via TsukiHime, loading Japanese as the primary track and your configured secondary language directly into mpv.
+
+**Changed**
+- Clipboard-Video Shortcut: The "append clipboard video to queue" shortcut is now configurable.
+
+**Fixed**
+- AniList Season Resolution: Season 2+ files now resolve to the correct AniList entry instead of silently falling back to season 1 (which mismatched character dictionaries and watch progress). Manual overrides now stay scoped per season, fix both the dictionary and progress tracking together, and also correct per-season cover art.
+- Subtitle Annotation Accuracy: Fixed several annotation edge cases, including inconsistent POS exclusions on merged quote-particle tokens, dropped annotations on supplementary-plane kanji, katakana punctuation wrongly treated as noise, and certain kanji vocabulary losing N+1 highlighting eligibility.
+- AnkiConnect Proxy Port Conflict: Video startup no longer crashes when another process already holds the configured AnkiConnect proxy port; a notification now explains how to resolve it.
+- AppImage Quit Crash: Fixed a "Service Crash" desktop notification appearing after closing a video when running the Linux AppImage.
+- Autoplay Pause Timing: Fixed playback resuming a few seconds before subtitle tokenization warmup finished, most noticeable when resuming mid-episode or when a cue starts within the first two seconds.
+- Stats Known-Word Count: Fixed stats reporting 0 known words for every session after the known-word cache format changed.
+- Stats Library Cover Art: Relinking a title to a different AniList entry now updates its cover in the Library grid immediately instead of leaving a stale, mismatched cover cached.
+- Rofi Prompt Spacing: Rofi menu prompts now keep a space before the input field instead of running into the placeholder text.
+- Stats Settings & Reliability: Hardened stats settings validation (nested/legacy AnkiConnect config now falls back safely instead of breaking) and stats routes against malformed requests and other edge cases.
+- Stats Delete Performance: Deleting sessions, episodes, and library entries is now dramatically faster and no longer stalls playback (e.g. a 12-episode title dropped from about a minute to under a second on a large library); the Vocabulary tab also loads much faster. The first launch after upgrading runs a one-time database migration.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Added a golden-file regression test corpus for the tokenizer/annotation pipeline, plus scripts to record new fixtures and diff against stock Yomitan.
+- Consolidated renderer modal state handling into a descriptor registry.
+- Consolidated CI quality checks (PR, stable, and prerelease) into one reusable workflow with mpv plugin tests and dependency audits.
+- Removed the unused stats IPC transport and unified stats dashboard HTTP types with the backend contract.
+- Added a script to verify known-word highlight tiers against live Anki data outside of playback.
+
+</details>
+
+## Previous Versions
+
+<details>
+<summary>v0.18.x</summary>
+
+<h2>v0.18.0 (2026-07-10)</h2>

 **Added**
 - Sentence Audio Normalization: Generated sentence audio is now normalized to -23 LUFS by default, and clips mined from playback mirror mpv's software volume curve with a limiter to prevent clipping. Both behaviors are configurable independently.
@@ -31,7 +99,7 @@

 </details>

-## Previous Versions
+</details>

 <details>
 <summary>v0.17.x</summary>
@@ -223,7 +223,9 @@ SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary
 subminer app --session-action '{"actionId":"openCharacterDictionaryManager"}'
 ```

-SubMiner stores manual selections in `character-dictionaries/anilist-overrides.json`. The episode's parent directory defines the override scope, so later episodes in the same season directory keep the selected AniList ID even if their filename guesses differ. Separate season directories can keep separate overrides and character dictionaries. When you replace a wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+SubMiner stores manual selections in `character-dictionaries/anilist-overrides.json`. The episode's parent directory **and detected season** define the override scope, so later episodes in the same season keep the selected AniList ID even if their filename guesses differ, while a different season never inherits the override -- including when every season sits in one flat folder. When you replace a wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+
+An override also pins the entry used for [AniList watch progress](/anilist-integration), so correcting a wrong match once fixes both the character dictionary and progress tracking.

 ## Managing Loaded Entries

@@ -399,7 +399,7 @@ See `config.example.jsonc` for detailed configuration options.
 ```

 | Option                             | Values   | Description                                                                                                                                                               |
-| ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `primaryDefaultMode`               | string   | Default primary subtitle bar visibility mode: `"hidden"`, `"visible"`, or `"hover"` (default: `"visible"`)                                                                |
 | `subtitleStyle.css`                | object   | CSS declaration object applied to primary subtitles after normal style defaults. Use CSS property names such as `font-size`.                                              |
 | `secondary.css`                    | object   | CSS declaration object applied to secondary subtitles after normal secondary style defaults.                                                                              |
@@ -556,7 +556,7 @@ Secondary subtitles do **not** auto-load by default. To turn them on for local a
 ```

 | Option                  | Values                             | Description                                                                                                                                   |
-| ----------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ----------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `secondarySubLanguages` | string[]                           | Language codes to auto-load (e.g., `["eng", "en"]`); non-Signs/Songs tracks are preferred when several tracks match. Default is empty (`[]`). |
 | `autoLoadSecondarySub`  | `true`, `false`                    | Auto-detect and load a matching secondary subtitle track for local/Jellyfin sidecar files (default: `false`)                                  |
 | `defaultMode`           | `"hidden"`, `"visible"`, `"hover"` | Initial display mode (default: `"hover"`)                                                                                                     |
@@ -1069,6 +1069,9 @@ SubMiner is intentionally built for [Kiku](https://kiku.youyoumu.my.id/) and [La
    "enabled": true,
    "fieldGrouping": "manual",
    "deleteDuplicateInAuto": true
+  },
+  "lapisKiku": {
+    "wordCardKind": "word-and-sentence"
  }
 }
 ```
@@ -1077,6 +1080,21 @@ SubMiner is intentionally built for [Kiku](https://kiku.youyoumu.my.id/) and [La
 - Enable `isKiku` to turn on duplicate merge behavior for mined Word/Expression hits.
 - When both are enabled, Kiku behavior is applied for grouping while sentence-card model settings are still read from `isLapis`.
 - `isKiku.fieldGrouping` supports `disabled`, `auto`, and `manual` merge modes; see [Field Grouping Modes](#field-grouping-modes).
+- `lapisKiku.wordCardKind` picks the card-type flag set on word cards; see [Word Card Type](#word-card-type). It is read only while `isLapis` or `isKiku` is enabled.
+
+### Word Card Type
+
+When SubMiner fills the sentence on a mined word card - from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining - it marks which card that note should generate. `ankiConnect.lapisKiku.wordCardKind` chooses the flag:
+
+| Value                         | Flag set                |
+| ----------------------------- | ----------------------- |
+| `word-and-sentence` (default) | `IsWordAndSentenceCard` |
+| `click`                       | `IsClickCard`           |
+| `sentence`                    | `IsSentenceCard`        |
+| `audio`                       | `IsAudioCard`           |
+| `none`                        | none; flags left as-is  |
+
+The other card-type flags are cleared so a note never claims two card types at once. Notes are skipped when the note type has no field for the chosen flag, and when the note was already mined as a sentence or audio card. Cards created by Mine Sentence and Mine Audio keep their own flag regardless of this setting.

 ### N+1 Word Highlighting

@@ -1168,7 +1186,7 @@ TsukiHime subtitle search works out of the box and needs no account or API key.
 ```

 | Option                       | Values       | Description                                                                                           |
-| ---------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| ---------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
 | `tsukihime.apiBaseUrl`       | string (URL) | Base URL of the TsukiHime API (default: `https://api.tsukihime.org/v1`). Only change it for a mirror. |
 | `tsukihime.maxSearchResults` | number       | Maximum releases returned per search (default: `10`; the API caps this at 100)                        |

@@ -1178,9 +1196,9 @@ See [TsukiHime Integration](/tsukihime-integration) for the modal workflow, lang

 ### Subtitle Sync

-Sync the active subtitle track from the overlay picker using `alass` or `ffsubsync`. Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).
+Sync a subtitle track from the overlay picker using `alass` or `ffsubsync`. The picker lets you choose which track gets retimed (the active primary track by default) and, for alass, which reference it is aligned against (the secondary subtitle track by default). Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).

- [`alass`](https://github.com/kaegi/alass) - fast, audio-independent sync using a secondary subtitle as reference
+- [`alass`](https://github.com/kaegi/alass) - fast, audio-independent sync using another subtitle as reference; it can also take the local video file as reference (alass extracts the audio itself)
 - [`ffsubsync`](https://github.com/smacke/ffsubsync) - audio-based sync using the video file as reference

 ```json
@@ -1229,7 +1247,7 @@ AniList integration is opt-in and disabled by default. Enable it to allow SubMin
 ```

 | Option                                                         | Values                  | Description                                                                                                   |
-| -------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| -------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
 | `anilist.enabled`                                              | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                                 |
 | `accessToken`                                                  | string                  | Optional explicit AniList access token override (default: empty string)                                       |
 | `characterDictionary.maxLoaded`                                | number                  | Maximum number of most-recently-used AniList media snapshots included in the merged dictionary (default: `3`) |
@@ -1540,7 +1558,7 @@ Configure the mpv executable, profile, and window state for SubMiner-managed mpv
 ```

 | Option                   | Values                                                                      | Description                                                                                                                                                                         |
-| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `executablePath`         | string                                                                      | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`)                                                 |
 | `profile`                | string                                                                      | mpv profile name passed as `--profile=<name>`. Leave empty to pass no profile (default `""`)                                                                                        |
 | `launchMode`             | `"normal"` \| `"maximized"` \| `"fullscreen"`                               | Window state when SubMiner spawns mpv (default `"normal"`)                                                                                                                          |
@@ -57,6 +57,15 @@ Jellyfin stream URLs are normalized to stable item links before stats titles are

 When YouTube channel metadata is available, the Library tab groups videos by creator/channel and treats each tracked video as an episode-like entry inside that channel section.

+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. 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. If that was the entry's last episode, the now-empty 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.
+
+Open a title and use **Delete Entry** in its header to remove a mistakenly tracked show outright. This deletes every episode of that title along with their sessions, subtitle lines, rollups and cover art, drops the words and kanji that were only seen there, and removes the card from the Library grid. Individual episodes and sessions can still be deleted on their own from the episode list and session rows. Entry deletion is refused while that title is the one currently playing.
+
 ![Stats Library](/screenshots/stats-library.png)

 #### Trends
@@ -183,12 +183,8 @@ Close and reopen your terminal, then verify with `mpv --version` and `ffmpeg -ve

 1. Download mpv from [mpv.io/installation](https://mpv.io/installation/) (the Windows builds link) and ffmpeg from [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
 2. Unzip each one somewhere permanent, for example `C:\Tools\mpv` and `C:\Tools\ffmpeg`. Note the folder that actually contains `mpv.exe` and the one containing `ffmpeg.exe` (for ffmpeg this is usually a `bin` subfolder).
-3. Press `Win`, type **Edit the system environment variables**, and open it.
-4. Click **Environment Variables…**
-5. Under **User variables**, select **Path** and click **Edit…**
-6. Click **New** and paste the folder containing `mpv.exe`. Click **New** again and paste the folder containing `ffmpeg.exe`.
-7. Click **OK** on all three dialogs.
-8. Close and reopen your terminal (PATH changes only apply to newly opened windows), then check:
+3. Press `Win`, type **Edit the system environment variables**, and open it. Click **Environment Variables…**, select **Path** under **User variables**, click **Edit…**, then use **New** to add each of those two folders. Confirm with **OK** on every dialog. Microsoft documents this in more detail under [environment variables](https://learn.microsoft.com/windows/deployment/usmt/usmt-recognized-environment-variables).
+4. Close and reopen your terminal, since `PATH` changes only apply to newly opened windows. Then check:

 ```powershell
 mpv --version
@@ -197,8 +193,10 @@ ffmpeg -version

 If you see `not recognized as the name of a cmdlet`, the folder you added is not the one holding the `.exe`. Reopen the Path editor and double-check.

-::: tip Don't want to touch PATH at all?
-mpv is the only hard requirement, and you can point SubMiner straight at it instead: leave `PATH` alone and set `mpv.executablePath` to the full path of `mpv.exe` during first-run setup. ffmpeg still needs to be on `PATH` for card audio and screenshots.
+::: tip mpv can skip PATH, ffmpeg cannot
+If you would rather not edit `PATH` for mpv, set `mpv.executablePath` to the full path of `mpv.exe` during first-run setup instead.
+
+There is no equivalent setting for ffmpeg: SubMiner invokes it by bare name when generating card audio and screenshots, so ffmpeg has to be on `PATH`. Without it, cards are still created but their audio and image fields come out empty. (`subsync.ffmpeg_path` only affects subtitle sync, not card media.)
 :::

 </details>
@@ -161,10 +161,13 @@ If your subtitle file is out of sync with the audio, SubMiner can resynchronize

 1. Open the subsync modal from the overlay.
 2. Select the sync engine (alass or ffsubsync).
-3. For alass, select a reference subtitle track from the video.
-4. SubMiner runs the sync and reloads the corrected subtitle.
+3. For alass, pick the **reference** - the subtitle with correct timing. This defaults to the secondary subtitle track. The loaded video file can also be used as the reference (alass extracts the audio itself), but it is never the default.
+4. Pick the **out-of-sync subtitle** - the track that gets retimed. This defaults to the active primary subtitle track and applies to both engines.
+5. SubMiner runs the sync and reloads the corrected subtitle into the slot the out-of-sync track came from: retiming the secondary track keeps it secondary and leaves the primary track selected.

-For remote streams, including Jellyfin playback, the modal only offers alass. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync needs direct access to the local media file and is unavailable for stream URLs.
+The reference and the out-of-sync subtitle must be different tracks; the reference list hides whichever track is selected as the target.
+
+For remote streams, including Jellyfin playback, the modal only offers alass with a subtitle reference. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync and the video-file reference need direct access to the local media file and are unavailable for stream URLs.

 When you mine a sentence card from the stats dashboard, SubMiner can also use `alass` automatically to align a local English sidecar against the matching local Japanese sidecar before filling the card translation field. The source subtitle files are not modified; SubMiner writes a temporary retimed copy and reuses it while the stats server is running.

@@ -523,7 +523,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
  // Shared AI provider transport settings are read from top-level ai and typically require restart.
  // Most other AnkiConnect settings still require restart.
  // ==========================================
@@ -605,7 +605,10 @@
      "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
      "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
      "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
-    } // Is kiku setting.
+    }, // Is kiku setting.
+    "lapisKiku": {
+      "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
+    } // Lapis kiku setting.
  }, // Automatic Anki updates and media generation options.

  // ==========================================
@@ -227,7 +227,7 @@ Install ffsubsync or configure the path:

 If subtitle sync fails (the error message is prefixed with the engine name):

- Ensure the reference subtitle track exists in the video (alass requires a source track).
+- Ensure a reference is selected (alass needs either a second subtitle track or the local video file, and it cannot be the same track that is being retimed).
 - Check that `ffmpeg` is available (used to extract the internal subtitle track).
 - Try running the sync tool manually to see detailed error output.
 - ffsubsync requires local files and cannot handle remote media streams (e.g., streaming URLs).
@@ -406,7 +406,7 @@ On any Wayland session that is not Hyprland or Sway (KDE Plasma, GNOME, and othe
 SubMiner handles this automatically:

 - It launches its own window under XWayland (it sets `--ozone-platform-hint=x11`).
- Every mpv it launches (via the `subminer` launcher, Jellyfin, or YouTube) is pinned to XWayland too - Wayland environment hints are stripped and an X11 GPU context (`--gpu-context=x11egl,x11`) is applied.
+- Every mpv it launches (via the `subminer` launcher, Jellyfin, or YouTube) is pinned to XWayland too - Wayland environment hints are stripped and an X11 GPU context (`--gpu-context=x11vk,x11egl,x11`) is applied. Only the window context is overridden; your `vo`/`gpu-api` and user shaders are left alone.
 - While mpv is windowed, the overlay is a managed X11 window owned by the tracked mpv window (`WM_TRANSIENT_FOR`), so it stays above mpv while other foreground X11/Xwayland apps can still cover both windows.
 - While tracked mpv is fullscreen, SubMiner swaps the visible overlay to a focusable-false X11 override-redirect window. That path can stay above the active fullscreen mpv window without requiring a KDE/KWin-specific rule, and SubMiner hides/releases it when mpv is no longer the active X11/Xwayland window.
 - The visible overlay is shown inactive on Linux, so normal hover should not steal keyboard focus from mpv.
@@ -420,7 +420,7 @@ Requirements: `xdotool`, `xprop`, and `xwininfo` must be installed. SubMiner use
 This almost always means mpv came up as a **native Wayland** window that the XWayland overlay cannot cover. It happens when mpv is launched **manually** (your own command), because SubMiner can only force XWayland on the mpv processes it launches itself. Fix it one of these ways:

 - Launch playback through SubMiner (the `subminer` launcher or the tray), which forces XWayland for you, or
- Force XWayland in your own mpv invocation, e.g. `mpv --gpu-context=x11egl …`, or launch with `WAYLAND_DISPLAY= mpv …`, or set `gpu-context=x11egl` in your `mpv.conf`.
+- Force XWayland in your own mpv invocation, e.g. `mpv --gpu-context=x11vk,x11egl,x11 …`, or launch with `WAYLAND_DISPLAY= mpv …`, or set `gpu-context=x11vk` (Vulkan) / `gpu-context=x11egl` (OpenGL) in your `mpv.conf`.

 To confirm mpv is on XWayland, `xdotool search --class mpv` should return a window id (a native Wayland mpv returns nothing).

@@ -145,11 +145,13 @@ The tray menu includes `Export Logs`, which creates the same sanitized local-dat

 Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for starting or stopping cast discovery in the current app session without changing config.

+The tray menu also includes `View Changelog`, which opens the in-app changelog modal. It fetches the changelog from the newest published release, so you see release notes for versions newer than the one you run; if the download fails it falls back to the changelog bundled with your install and says so. Versions in the current `0.x` line are expanded by default and older lines are folded, matching this site's [Changelog](/changelog). A badge marks the version you have installed, and newer versions are tagged `New`. The same modal opens from the `What's New` button on the update-available overlay notification.
+
 ### Logging and App Mode

 - `--log-level` controls logger verbosity.
 - `--dev` and `--debug` are app/dev-mode switches; they are not log-level aliases.
- `--background` defaults to quieter logging (`warn`) unless `--log-level` is set.
+- `--background` starts at the default quieter logging level (`warn`), then follows `logging.level` after config loads. An explicit `--log-level` remains the override.
 - `--background` launched from a terminal detaches and returns the prompt; stop it with tray Quit or `SubMiner.AppImage --stop` (`SubMiner.exe --stop` on Windows).
 - Linux desktop launcher starts SubMiner with `--background` by default (via electron-builder `linux.executableArgs`).
 - On Hyprland and other Wayland compositors, the tray icon appears only when your panel provides a StatusNotifier/AppIndicator tray host.
@@ -368,6 +370,8 @@ Press `V` to cycle the primary SubMiner subtitle bar through hidden → visible

 `Ctrl/Cmd+/` opens the session help modal with the current overlay and mpv keybindings. The same help view is also available through the `y-h` chord in mpv.

+The changelog modal (tray > `View Changelog`) works the same way: it renders over mpv when a video is playing and in its own window otherwise. Use `J`/`K` or the arrow keys to move between versions, `Enter` to fold or unfold one, `R` to refetch, and `Esc` to close.
+
 Hovering over subtitle text pauses mpv by default; leaving resumes it. Yomitan popups also pause playback by default. Set `subtitleStyle.autoPauseVideoOnHover: false` or `subtitleStyle.autoPauseVideoOnYomitanPopup: false` to disable either behavior.

 ### Drag-and-Drop
@@ -64,7 +64,7 @@ Use the basic subtitle websocket when you only need the current subtitle line as
 - **Client auth:** none
 - **Reconnects:** client-managed

-When a client connects, SubMiner immediately sends the latest subtitle payload if one is available. After that, it pushes a new message each time the current subtitle changes.
+When a client connects, SubMiner immediately sends the latest subtitle payload if one is available. After that, it pushes a new message each time the current subtitle changes. Annotation-only upgrades do not repeat the same line on this basic stream.

 #### Message shape

@@ -96,6 +96,8 @@ Use the annotation websocket for custom clients that want the same structured to

 In practice, if you are building a new client, prefer `annotationWebsocket` unless you specifically need compatibility with an existing `websocket` consumer.

+On a tokenization cache miss, this stream first sends the cue as plain text with an empty `tokens` array, then sends the annotated replacement when tokenization finishes. Treat each message as the complete current state, replacing the previous payload.
+
 #### Message shape

 ```json
@@ -11,7 +11,7 @@ SubMiner auto-loads Japanese subtitles when you play a YouTube URL, giving you t

 When SubMiner detects a YouTube URL (or `ytsearch:` target), it pauses mpv at startup and runs a subtitle pipeline before resuming playback:

-1. **Probe** --- `yt-dlp --dump-single-json` extracts all available subtitle tracks (manual uploads and auto-generated captions) along with video metadata.
+1. **Probe** --- `yt-dlp --dump-single-json` extracts all available subtitle tracks (manual uploads and auto-generated captions) along with video metadata. Every yt-dlp call passes `--no-playlist`, so playlist links (for example a Watch Later URL with `list=`/`index=`) resolve to the single video instead of the whole playlist.
 2. **Discover** --- Each track is normalized into a `YoutubeTrackOption` with language code, kind (`manual` or `auto`), display label, and direct download URL.
 3. **Select** --- SubMiner picks the best primary track (Japanese, preferring manual over auto) and secondary track (English, preferring manual over auto).
 4. **Download** --- Selected tracks are fetched via direct URL when available, falling back to `yt-dlp --write-subs` / `--write-auto-subs`. YouTube TimedText XML formats (`srv1`/`srv2`/`srv3`) are converted to VTT on the fly. Auto-generated VTT captions are normalized to remove rolling-caption duplication.
@@ -24,7 +24,7 @@ Read when: you need to find the owner module for a behavior or test surface
 - Subtitle/token pipeline: `src/core/services/subtitle-*.ts`, `src/core/services/tokenizer*`, `src/core/services/tokenizer/`, `src/subsync/`
 - Anki workflow: `src/anki-integration/`, `src/core/services/anki-jimaku*.ts`
 - Immersion tracking: `src/core/services/immersion-tracker/`
-  Includes stats storage/query schema such as `imm_videos`, `imm_media_art`, and `imm_youtube_videos` for per-video and YouTube-specific library metadata.
+  Includes stats storage/query schema such as `imm_videos`, `imm_media_art`, and `imm_youtube_videos` for per-video and YouTube-specific library metadata. Library-entry identity aliases and merge recommendations are persisted alongside this schema; the stats HTTP and SPA layers only expose and present those domain decisions.
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
 - Window trackers: `src/window-trackers/`
@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming

 Status: active
-Last verified: 2026-06-14
+Last verified: 2026-08-04
 Owner: Kyle Yasuda
 Read when: debugging subtitle state or blank Linux/X11 overlay windows when the visible overlay is shown or recreated

@@ -47,18 +47,43 @@ subtitles do not draw.
   `emitSubtitle(payload)` and `refreshCurrentSubtitle(text)`, then prime secondary subtitles.
 6. Tokenization cache hit: call `consumeCachedSubtitle(text)`, `onSubtitleChange(text)`, and
   `emitSubtitle(cachedPayload)`, then prime secondary subtitles.
-7. Cache miss: call `refreshCurrentSubtitle(text)` and let normal tokenization emit the final
-   payload.
+7. Cache miss: call `refreshCurrentSubtitle(text)`. Normal processing emits a plain payload
+   synchronously, then replaces it with the tokenized payload when ready.

-In `src/main.ts`, both `onSubtitleChange` and `refreshCurrentSubtitle` pause
-`subtitlePrefetchService`, notify it with `onSeek(lastObservedTimePos)`, and then call the matching
-`subtitleProcessingController` method. This gives the visible overlay priority over background
-prefetch work and re-centers prefetch around the live playback time.
+Both `onSubtitleChange` and `refreshCurrentSubtitle` pause `subtitlePrefetchService` and then call
+the matching `subtitleProcessingController` method, giving the visible overlay priority over
+background prefetch work. Prefetch is not re-centered here: restarting the run per line
+(`onSeek`) discarded the in-flight tokenization every time the subtitle changed, so only real
+seeks restart it (see `onTimePosUpdate` in `src/main.ts`).
+
+On an uncached autoplay prime the raw payload is emitted here and reported to the controller with
+`notePlainSubtitleEmitted`, so the controller skips its own plain emit for that line and the
+overlay receives one plain payload followed by the annotated one.
+
+The pause is released by the controller's `onProcessingSettled` callback, which fires once it has
+no work left. Emits do not release it: the first emit for an uncached line is the plain payload
+that precedes tokenization, and a run can finish without emitting at all (a suppressed duplicate,
+a failed tokenization). Both controller methods return whether processing is now pending, and the
+caller resumes immediately when it is not — a repeated subtitle schedules no work, so no settle is
+coming and prefetching would otherwise idle for the rest of the cue.
+
+## Live Cue Delivery
+
+- A tokenization cache miss emits the plain cue synchronously. Tokenization remains serialized so
+  live work does not contend for Yomitan state.
+- If a newer cue arrives while an older line is still tokenizing, the newer plain cue or empty
+  clear payload is emitted immediately. The older tokenization result is dropped before it can
+  replace the current cue.
+- The current cue upgrades in place when its tokens and annotations are ready. This can reflow text
+  or character images, but cue visibility does not wait for that work.

 ## Emitted State

- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`, which sends the normal
-  annotated subtitle payload to overlay windows and subtitle websocket listeners.
+- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`. Overlay windows and annotation
+  websocket listeners receive both the immediate plain cue and its later annotation upgrade.
+- The basic subtitle websocket receives the immediate plain cue only. Because its serialized
+  payload discards annotations, the later upgrade would be an identical duplicate and is skipped
+  when text and cue timing match.
 - Secondary priming reads mpv `secondary-sub-text`, stores it in
  `mpvClient.currentSecondarySubText`, and broadcasts `secondary-subtitle:set` to overlay windows.
 - If secondary `requestProperty` fails, the primary flow stays complete and only a debug line is
@@ -222,7 +222,7 @@ test('buildMpvEnv preserves native Wayland env for supported Hyprland and Sway a
  });
 });

-test('buildMpvBackendArgs forces an explicit X11 renderer stack when backend resolves to x11', () => {
+test('buildMpvBackendArgs pins the X11 window context when backend resolves to x11', () => {
  withPlatform('linux', () => {
    assert.deepEqual(
      buildMpvBackendArgs(makeArgs({ backend: 'x11' }), {
@@ -230,12 +230,12 @@ test('buildMpvBackendArgs forces an explicit X11 renderer stack when backend res
        WAYLAND_DISPLAY: 'wayland-0',
        XDG_SESSION_TYPE: 'wayland',
      }),
-      ['--vo=gpu', '--gpu-api=opengl', '--gpu-context=x11egl,x11'],
+      ['--gpu-context=x11vk,x11egl,x11'],
    );
  });
 });

-test('buildMpvBackendArgs forces the same X11 renderer stack for unsupported Wayland auto fallback', () => {
+test('buildMpvBackendArgs pins the same X11 window context for unsupported Wayland auto fallback', () => {
  withPlatform('linux', () => {
    assert.deepEqual(
      buildMpvBackendArgs(makeArgs({ backend: 'auto' }), {
@@ -245,7 +245,7 @@ test('buildMpvBackendArgs forces the same X11 renderer stack for unsupported Way
        XDG_CURRENT_DESKTOP: 'KDE',
        XDG_SESSION_DESKTOP: 'plasma',
      }),
-      ['--vo=gpu', '--gpu-api=opengl', '--gpu-context=x11egl,x11'],
+      ['--gpu-context=x11vk,x11egl,x11'],
    );
  });
 });
@@ -292,9 +292,7 @@ test('buildConfiguredMpvDefaultArgs appends maximized launch mode to configured
        '--secondary-sub-visibility=no',
        '--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
        '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
-        '--vo=gpu',
-        '--gpu-api=opengl',
-        '--gpu-context=x11egl,x11',
+        '--gpu-context=x11vk,x11egl,x11',
        '--window-maximized=yes',
      ],
    );
@@ -185,6 +185,7 @@ export const IMMERSION_DB_FIXTURE_DDL = `
    line_id INTEGER NOT NULL,
    word_id INTEGER NOT NULL,
    occurrence_count INTEGER NOT NULL,
+    seen_ms INTEGER,
    PRIMARY KEY(line_id, word_id),
    FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
    FOREIGN KEY(word_id) REFERENCES imm_words(id) ON DELETE CASCADE
@@ -193,6 +194,7 @@ export const IMMERSION_DB_FIXTURE_DDL = `
    line_id INTEGER NOT NULL,
    kanji_id INTEGER NOT NULL,
    occurrence_count INTEGER NOT NULL,
+    seen_ms INTEGER,
    PRIMARY KEY(line_id, kanji_id),
    FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
    FOREIGN KEY(kanji_id) REFERENCES imm_kanji(id) ON DELETE CASCADE
@@ -313,8 +315,8 @@ export const IMMERSION_DB_FIXTURE_DDL = `
  CREATE INDEX idx_subtitle_lines_session_line ON imm_subtitle_lines(session_id, line_index);
  CREATE INDEX idx_subtitle_lines_video_line ON imm_subtitle_lines(video_id, line_index);
  CREATE INDEX idx_subtitle_lines_anime_line ON imm_subtitle_lines(anime_id, line_index);
-  CREATE INDEX idx_word_line_occurrences_word ON imm_word_line_occurrences(word_id, line_id);
-  CREATE INDEX idx_kanji_line_occurrences_kanji ON imm_kanji_line_occurrences(kanji_id, line_id);
+  CREATE INDEX idx_word_line_occurrences_word_seen ON imm_word_line_occurrences(word_id, seen_ms, occurrence_count, line_id);
+  CREATE INDEX idx_kanji_line_occurrences_kanji_seen ON imm_kanji_line_occurrences(kanji_id, seen_ms, occurrence_count, line_id);
  CREATE INDEX idx_media_art_cover_blob_hash ON imm_media_art(cover_blob_hash);
  CREATE INDEX idx_media_art_anilist_id ON imm_media_art(anilist_id);
  CREATE INDEX idx_media_art_cover_url ON imm_media_art(cover_url);
@@ -2,7 +2,7 @@
  "name": "subminer",
  "productName": "SubMiner",
  "desktopName": "SubMiner.desktop",
-  "version": "0.19.0-beta.4",
+  "version": "0.19.2",
  "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
  "packageManager": "bun@1.3.5",
  "main": "dist/main-entry.js",
@@ -84,8 +84,9 @@
  "overrides": {
    "@xmldom/xmldom": "0.8.13",
    "app-builder-lib": "26.15.3",
-    "brace-expansion": "5.0.8",
+    "brace-expansion": "5.0.9",
    "electron-builder-squirrel-windows": "26.15.3",
+    "fast-uri": "3.1.5",
    "form-data": "4.0.6",
    "ip-address": "10.2.0",
    "js-yaml": "4.3.0",
@@ -93,7 +94,8 @@
    "minimatch": "10.2.5",
    "picomatch": "4.0.4",
    "tar": "7.5.21",
-    "tmp": "0.2.7"
+    "tmp": "0.2.7",
+    "undici": "7.29.0"
  },
  "keywords": [
    "anki",
@@ -125,7 +127,7 @@
    "@types/ws": "^8.18.1",
    "electron": "42.6.0",
    "electron-builder": "26.15.3",
-    "undici": "7.28.0",
+    "undici": "7.29.0",
    "esbuild": "^0.25.12",
    "eslint": "^10.8.0",
    "prettier": "^3.8.1",
@@ -258,6 +260,10 @@
      {
        "from": "dist/launcher/subminer",
        "to": "launcher/subminer"
+      },
+      {
+        "from": "CHANGELOG.md",
+        "to": "CHANGELOG.md"
      }
    ]
  },
@@ -24,6 +24,11 @@
  - The mature-interval threshold and the four tier colors are configurable, and the in-session help legend shows the active tier colors while maturity highlighting is on.
  - Tiers follow Anki's own card state: a lapsed card correctly shows as learning rather than young, and a note is treated as mature if any of its cards are mature. Stats and other known-word tools stay accurate with this new data.

+- **Stats Library Entry Deletion**
+  - Added a "Delete Entry" action in the stats Library detail view that removes an entire title in one step: every episode, session, subtitle line, rollup, cover, and vocabulary count derived from it. Previously a mistaken entry had to be cleared episode by episode and still lingered in the Library.
+  - Delete progress (session, session group, episode, or full entry) now shows app-wide as a progress bar plus a status toast, staying visible across tabs and windows instead of disappearing when you switch away.
+  - Deletes are dramatically faster on large libraries, and opening the Vocabulary tab no longer stalls; the first launch after upgrading migrates the stats database in place to support this.
+
 ### Changed

 - **Clipboard-Video Shortcut**
@@ -34,8 +39,9 @@
 - **Word Highlighting Accuracy**
  - Fixed several incorrect word highlighting and annotation cases: inconsistent part-of-speech exclusions on merged quote-particle tokens, missing annotations for rare kanji, katakana punctuation wrongly treated as non-kana noise, and certain kanji vocabulary skipped for next-level ("N+1") highlighting.

- **Character Dictionary Season Overrides**
-  - Manual AniList overrides for a series now stay in effect for every episode in the same season folder, even when individual episode filenames produce different automatic guesses.
+- **AniList Season Resolution**
+  - Season 2 and later episodes now resolve to the correct AniList entry by walking sequel relations instead of guessing from the title, so watch progress, the character dictionary, and cover art for later seasons no longer silently fall back to season 1.
+  - Manual AniList overrides now stay in effect for every episode in the same season (by folder and detected season), and setting an override now fixes both the character dictionary and AniList watch progress together instead of needing separate corrections.

 - **Startup Playback Pausing Too Early**
  - Fixed playback resuming before subtitle processing finished warming up, which could briefly show untranslated subtitles right after opening a video.
@@ -53,6 +59,9 @@
  - Hardened the stats server against malformed requests, stalled AniList lookups, media mismatches during word mining, and missing Yomitan connections.
  - AnkiConnect settings validation now preserves valid custom configurations while safely falling back on invalid values instead of failing.

+- **Stats Library Cover After Relink**
+  - Relinking a title to a different AniList entry now updates its cover art in the stats Library grid, not just the detail view, so unrelated titles no longer end up sharing the wrong cover.
+
 - **Rofi Menu Prompt Spacing**
  - Rofi menu prompts now keep a space between the prompt label and the input field instead of crowding the search placeholder text.

@@ -64,6 +73,8 @@
 - refactor: split anki-connect and stats-server resolvers into modules by @ksyasuda in #169
 - feat(launcher): add post-playback history menu with previous episode by @ksyasuda in #170
 - Anki maturity-based known-word highlighting by @ksyasuda in #172
+- fix(anilist): resolve later seasons via sequel relations, not title guessing by @ksyasuda in #173
+- feat(stats): add library entry deletion and app-wide delete progress by @ksyasuda in #174

 ## Installation

@@ -22,10 +22,12 @@ import { MediaGenerator } from './media-generator';
 import path from 'path';
 import {
  AnkiConnectConfig,
+  type CardKind,
  KikuDuplicateCardInfo,
  KikuFieldGroupingChoice,
  KikuMergePreviewResponse,
  NotificationOptions,
+  type WordCardKind,
 } from './types/anki';
 import { AiConfig } from './types/integrations';
 import type { KnownWordMaturityTier } from './types/subtitle';
@@ -50,6 +52,7 @@ import {
  withUpdateProgress,
  UiFeedbackState,
 } from './anki-integration/ui-feedback';
+import { applyCardKindFlagFields, resolveWordCardKindSetting } from './anki-integration/card-kinds';
 import { KnownWordCacheManager } from './anki-integration/known-word-cache';
 import { PollingRunner } from './anki-integration/polling';
 import type { AnkiConnectProxyServer } from './anki-integration/anki-connect-proxy';
@@ -83,8 +86,6 @@ interface NoteInfo {
  fields: Record<string, { value: string }>;
 }

-type CardKind = 'sentence' | 'audio' | 'word-and-sentence';
-
 function trimToNonEmptyString(value: unknown): string | null {
  if (typeof value !== 'string') return null;
  const trimmed = value.trim();
@@ -840,6 +841,7 @@ export class AnkiIntegration {
    kikuEnabled: boolean;
    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
    kikuDeleteDuplicateInAuto: boolean;
+    wordCardKind: WordCardKind;
  } {
    const lapis = this.getLapisConfig();
    const kiku = this.getKikuConfig();
@@ -852,6 +854,7 @@ export class AnkiIntegration {
      kikuEnabled: kiku.enabled,
      kikuFieldGrouping: (kiku.fieldGrouping || 'disabled') as 'auto' | 'manual' | 'disabled',
      kikuDeleteDuplicateInAuto: kiku.deleteDuplicateInAuto !== false,
+      wordCardKind: resolveWordCardKindSetting(this.config.lapisKiku?.wordCardKind),
    };
  }

@@ -1315,79 +1318,9 @@ export class AnkiIntegration {
    availableFieldNames: string[],
    cardKind: CardKind,
  ): void {
-    const audioFlagNames = ['IsAudioCard'];
-
-    if (cardKind === 'word-and-sentence') {
-      const wordAndSentenceFlag = this.resolveFieldName(
-        availableFieldNames,
-        'IsWordAndSentenceCard',
+    applyCardKindFlagFields(updatedFields, cardKind, (preferredName) =>
+      this.resolveFieldName(availableFieldNames, preferredName),
    );
-      if (!wordAndSentenceFlag) {
-        return;
-      }
-      updatedFields[wordAndSentenceFlag] = 'x';
-
-      const sentenceFlag = this.resolveFieldName(availableFieldNames, 'IsSentenceCard');
-      if (sentenceFlag && sentenceFlag !== wordAndSentenceFlag) {
-        updatedFields[sentenceFlag] = '';
-      }
-
-      for (const audioFlagName of audioFlagNames) {
-        const resolved = this.resolveFieldName(availableFieldNames, audioFlagName);
-        if (resolved && resolved !== wordAndSentenceFlag) {
-          updatedFields[resolved] = '';
-        }
-      }
-      return;
-    }
-
-    if (cardKind === 'sentence') {
-      const sentenceFlag = this.resolveFieldName(availableFieldNames, 'IsSentenceCard');
-      if (sentenceFlag) {
-        updatedFields[sentenceFlag] = 'x';
-      }
-
-      for (const audioFlagName of audioFlagNames) {
-        const resolved = this.resolveFieldName(availableFieldNames, audioFlagName);
-        if (resolved && resolved !== sentenceFlag) {
-          updatedFields[resolved] = '';
-        }
-      }
-
-      const wordAndSentenceFlag = this.resolveFieldName(
-        availableFieldNames,
-        'IsWordAndSentenceCard',
-      );
-      if (wordAndSentenceFlag && wordAndSentenceFlag !== sentenceFlag) {
-        updatedFields[wordAndSentenceFlag] = '';
-      }
-      return;
-    }
-
-    const resolvedAudioFlags = Array.from(
-      new Set(
-        audioFlagNames
-          .map((name) => this.resolveFieldName(availableFieldNames, name))
-          .filter((name): name is string => Boolean(name)),
-      ),
-    );
-    const audioFlagName = resolvedAudioFlags[0] || null;
-    if (audioFlagName) {
-      updatedFields[audioFlagName] = 'x';
-    }
-    for (const extraAudioFlag of resolvedAudioFlags.slice(1)) {
-      updatedFields[extraAudioFlag] = '';
-    }
-
-    const sentenceFlag = this.resolveFieldName(availableFieldNames, 'IsSentenceCard');
-    if (sentenceFlag && sentenceFlag !== audioFlagName) {
-      updatedFields[sentenceFlag] = '';
-    }
-
-    const wordAndSentenceFlag = this.resolveFieldName(availableFieldNames, 'IsWordAndSentenceCard');
-    if (wordAndSentenceFlag && wordAndSentenceFlag !== audioFlagName) {
-      updatedFields[wordAndSentenceFlag] = '';
-    }
  }

  private async showNotification(
@@ -4,29 +4,23 @@ import test from 'node:test';
 import { CardCreationService } from './card-creation';
 import { toMpvEdlValue } from './mpv-edl-test-utils';
 import type { MediaInput } from '../media-generator';
-import type { AnkiConnectConfig } from '../types/anki';
+import type { AnkiConnectConfig, CardKind } from '../types/anki';
+import { applyCardKindFlagFields } from './card-kinds';

 type CardCreationDeps = ConstructorParameters<typeof CardCreationService>[0];

-function setWordAndSentenceCardTypeFields(
+function setCardTypeFields(
  updatedFields: Record<string, string>,
  availableFieldNames: string[],
-  cardKind: 'sentence' | 'audio' | 'word-and-sentence',
+  cardKind: CardKind,
 ): void {
-  if (cardKind !== 'word-and-sentence') return;
-
-  const resolveFieldName = (preferredName: string): string | null =>
-    availableFieldNames.find((name) => name.toLowerCase() === preferredName.toLowerCase()) ?? null;
-  const wordAndSentenceFlag = resolveFieldName('IsWordAndSentenceCard');
-  if (!wordAndSentenceFlag) return;
-
-  updatedFields[wordAndSentenceFlag] = 'x';
-  for (const flagName of ['IsSentenceCard', 'IsAudioCard']) {
-    const resolved = resolveFieldName(flagName);
-    if (resolved && resolved !== wordAndSentenceFlag) {
-      updatedFields[resolved] = '';
-    }
-  }
+  applyCardKindFlagFields(
+    updatedFields,
+    cardKind,
+    (preferredName) =>
+      availableFieldNames.find((name) => name.toLowerCase() === preferredName.toLowerCase()) ??
+      null,
+  );
 }

 function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
@@ -217,7 +211,7 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
      kikuFieldGrouping: 'disabled',
      kikuDeleteDuplicateInAuto: false,
    }),
-    setCardTypeFields: setWordAndSentenceCardTypeFields,
+    setCardTypeFields,
  });

  await service.updateLastAddedFromClipboard('字幕');
@@ -3,7 +3,7 @@ import {
  getConfiguredWordFieldName,
  getPreferredWordValueFromExtractedFields,
 } from '../anki-field-config';
-import { AnkiConnectConfig } from '../types/anki';
+import { AnkiConnectConfig, type CardKind, type WordCardKind } from '../types/anki';
 import { createLogger } from '../logger';
 import type { MediaInput } from '../media-input';
 import { SubtitleTimingTracker } from '../subtitle-timing-tracker';
@@ -15,7 +15,7 @@ import {
  resolveAudioStreamIndexForMediaGeneration,
  type MediaGenerationInputResolverOptions,
 } from './media-source';
-import { shouldMarkWordAndSentenceCard } from './note-field-utils';
+import { resolveWordCardKind } from './note-field-utils';
 import type { PendingYoutubeMediaUpdate } from './pending-youtube-media';
 import { resolveMpvVolumeScale } from './mpv-volume';

@@ -42,8 +42,6 @@ export interface CardCreationNoteInfo {
  fields: Record<string, { value: string }>;
 }

-type CardKind = 'sentence' | 'audio' | 'word-and-sentence';
-
 interface CardCreationClient {
  addNote(
    deck: string,
@@ -136,6 +134,7 @@ interface CardCreationDeps {
    kikuEnabled: boolean;
    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
    kikuDeleteDuplicateInAuto: boolean;
+    wordCardKind?: WordCardKind;
  };
  getFallbackDurationSeconds: () => number;
  appendKnownWordsFromNoteInfo: (noteInfo: CardCreationNoteInfo) => void;
@@ -274,12 +273,9 @@ export class CardCreationService {
        if (sentenceField) {
          const processedSentence = this.deps.processSentence(sentence, fields);
          updatedFields[sentenceField] = processedSentence;
-          if (shouldMarkWordAndSentenceCard(noteInfo, sentenceCardConfig)) {
-            this.deps.setCardTypeFields(
-              updatedFields,
-              Object.keys(noteInfo.fields),
-              'word-and-sentence',
-            );
+          const wordCardKind = resolveWordCardKind(noteInfo, sentenceCardConfig);
+          if (wordCardKind) {
+            this.deps.setCardTypeFields(updatedFields, Object.keys(noteInfo.fields), wordCardKind);
          }
          updatePerformed = true;
        }
@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { applyCardKindFlagFields } from './card-kinds';
+
+function resolverFor(availableFieldNames: string[]) {
+  return (preferredName: string): string | null =>
+    availableFieldNames.find((name) => name.toLowerCase() === preferredName.toLowerCase()) ?? null;
+}
+
+const KIKU_FLAG_FIELDS = ['IsWordAndSentenceCard', 'IsClickCard', 'IsSentenceCard', 'IsAudioCard'];
+
+test('flags the requested card kind and clears the others', () => {
+  const fields: Record<string, string> = {};
+
+  applyCardKindFlagFields(fields, 'click', resolverFor(KIKU_FLAG_FIELDS));
+
+  assert.deepEqual(fields, {
+    IsClickCard: 'x',
+    IsWordAndSentenceCard: '',
+    IsSentenceCard: '',
+    IsAudioCard: '',
+  });
+});
+
+test('matches flag fields case-insensitively', () => {
+  const fields: Record<string, string> = {};
+
+  applyCardKindFlagFields(fields, 'word-and-sentence', resolverFor(['iswordandsentencecard']));
+
+  assert.deepEqual(fields, { iswordandsentencecard: 'x' });
+});
+
+test('leaves flags untouched when the note type has no flag for a word card kind', () => {
+  const fields: Record<string, string> = {};
+
+  applyCardKindFlagFields(
+    fields,
+    'click',
+    resolverFor(['IsWordAndSentenceCard', 'IsSentenceCard']),
+  );
+
+  assert.deepEqual(fields, {});
+});
+
+test('clears stale flags for explicit mine actions even without the target flag', () => {
+  const fields: Record<string, string> = {};
+
+  applyCardKindFlagFields(
+    fields,
+    'audio',
+    resolverFor(['IsWordAndSentenceCard', 'IsSentenceCard']),
+  );
+
+  assert.deepEqual(fields, { IsWordAndSentenceCard: '', IsSentenceCard: '' });
+});
+
+test('does not blank the target flag it just set', () => {
+  const fields: Record<string, string> = {};
+
+  applyCardKindFlagFields(fields, 'sentence', resolverFor(['IsSentenceCard']));
+
+  assert.deepEqual(fields, { IsSentenceCard: 'x' });
+});
@@ -0,0 +1,63 @@
+import type { CardKind, WordCardKind } from '../types/anki';
+
+/**
+ * Kiku/Lapis note types decide which card a note generates from mutually exclusive
+ * `Is...Card` flag fields. Setting one always means clearing the others.
+ */
+export const CARD_KIND_FLAG_FIELDS: Record<CardKind, string> = {
+  'word-and-sentence': 'IsWordAndSentenceCard',
+  click: 'IsClickCard',
+  sentence: 'IsSentenceCard',
+  audio: 'IsAudioCard',
+};
+
+export const WORD_CARD_KINDS: readonly WordCardKind[] = [
+  'word-and-sentence',
+  'click',
+  'sentence',
+  'audio',
+  'none',
+];
+
+export const DEFAULT_WORD_CARD_KIND: WordCardKind = 'word-and-sentence';
+
+/**
+ * Card kinds SubMiner marks on its own initiative (word cards). They are only applied
+ * when the note type actually carries the matching flag field, so plain note types keep
+ * their fields untouched.
+ */
+const IMPLICIT_CARD_KINDS = new Set<CardKind>(['word-and-sentence', 'click']);
+
+export function isWordCardKind(value: unknown): value is WordCardKind {
+  return typeof value === 'string' && WORD_CARD_KINDS.includes(value as WordCardKind);
+}
+
+export function resolveWordCardKindSetting(value: unknown): WordCardKind {
+  return isWordCardKind(value) ? value : DEFAULT_WORD_CARD_KIND;
+}
+
+/**
+ * Flags `cardKind` on the note and clears every other card-kind flag it has, so the note
+ * never ends up claiming to be two kinds of card at once.
+ */
+export function applyCardKindFlagFields(
+  updatedFields: Record<string, string>,
+  cardKind: CardKind,
+  resolveFieldName: (preferredName: string) => string | null,
+): void {
+  const targetFlag = resolveFieldName(CARD_KIND_FLAG_FIELDS[cardKind]);
+  if (!targetFlag && IMPLICIT_CARD_KINDS.has(cardKind)) {
+    return;
+  }
+  if (targetFlag) {
+    updatedFields[targetFlag] = 'x';
+  }
+
+  for (const [kind, flagName] of Object.entries(CARD_KIND_FLAG_FIELDS)) {
+    if (kind === cardKind) continue;
+    const resolved = resolveFieldName(flagName);
+    if (resolved && resolved !== targetFlag) {
+      updatedFields[resolved] = '';
+    }
+  }
+}
@@ -0,0 +1,118 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { resolveWordCardKind, type NoteFieldValueInfo } from './note-field-utils';
+
+function kikuNote(values: Record<string, string> = {}): NoteFieldValueInfo {
+  const defaults: Record<string, string> = {
+    Expression: '単語',
+    Sentence: '',
+    IsWordAndSentenceCard: '',
+    IsClickCard: '',
+    IsSentenceCard: '',
+    IsAudioCard: '',
+  };
+  return {
+    fields: Object.fromEntries(
+      Object.entries({ ...defaults, ...values }).map(([name, value]) => [name, { value }]),
+    ),
+  };
+}
+
+test('marks word-and-sentence cards by default when Kiku is enabled', () => {
+  assert.equal(
+    resolveWordCardKind(kikuNote(), { lapisEnabled: false, kikuEnabled: true }),
+    'word-and-sentence',
+  );
+});
+
+test('honors the configured word card kind', () => {
+  assert.equal(
+    resolveWordCardKind(kikuNote(), {
+      lapisEnabled: false,
+      kikuEnabled: true,
+      wordCardKind: 'click',
+    }),
+    'click',
+  );
+});
+
+test('marks nothing when neither Kiku nor Lapis is enabled', () => {
+  assert.equal(
+    resolveWordCardKind(kikuNote(), {
+      lapisEnabled: false,
+      kikuEnabled: false,
+      wordCardKind: 'click',
+    }),
+    null,
+  );
+});
+
+test('marks nothing when the word card kind is "none"', () => {
+  assert.equal(
+    resolveWordCardKind(kikuNote(), {
+      lapisEnabled: true,
+      kikuEnabled: false,
+      wordCardKind: 'none',
+    }),
+    null,
+  );
+});
+
+test('falls back to the default kind for an unrecognized setting', () => {
+  assert.equal(
+    resolveWordCardKind(kikuNote(), {
+      lapisEnabled: false,
+      kikuEnabled: true,
+      wordCardKind: 'bogus' as never,
+    }),
+    'word-and-sentence',
+  );
+});
+
+test('marks nothing when the note type lacks the configured flag field', () => {
+  const note: NoteFieldValueInfo = {
+    fields: { Expression: { value: '単語' }, Sentence: { value: '' } },
+  };
+
+  assert.equal(
+    resolveWordCardKind(note, { lapisEnabled: false, kikuEnabled: true, wordCardKind: 'click' }),
+    null,
+  );
+});
+
+test('leaves cards already mined as sentence or audio cards alone', () => {
+  for (const flagField of ['IsSentenceCard', 'IsAudioCard']) {
+    assert.equal(
+      resolveWordCardKind(kikuNote({ [flagField]: 'x' }), {
+        lapisEnabled: false,
+        kikuEnabled: true,
+        wordCardKind: 'click',
+      }),
+      null,
+      flagField,
+    );
+  }
+});
+
+test('re-affirms the configured kind when the note already carries its flag', () => {
+  assert.equal(
+    resolveWordCardKind(kikuNote({ IsSentenceCard: 'x' }), {
+      lapisEnabled: false,
+      kikuEnabled: true,
+      wordCardKind: 'sentence',
+    }),
+    'sentence',
+  );
+});
+
+test('overrides a differently flagged word card', () => {
+  assert.equal(
+    resolveWordCardKind(kikuNote({ IsWordAndSentenceCard: 'x' }), {
+      lapisEnabled: false,
+      kikuEnabled: true,
+      wordCardKind: 'click',
+    }),
+    'click',
+  );
+});
@@ -1,3 +1,13 @@
+import type { CardKind, WordCardKind } from '../types/anki';
+import { createLogger } from '../logger';
+import {
+  CARD_KIND_FLAG_FIELDS,
+  DEFAULT_WORD_CARD_KIND,
+  resolveWordCardKindSetting,
+} from './card-kinds';
+
+const log = createLogger('anki').child('integration.note-fields');
+
 export interface NoteFieldValueInfo {
  fields: Record<string, { value: string }>;
 }
@@ -16,22 +26,57 @@ export function hasNoteFieldValue(noteInfo: NoteFieldValueInfo, preferredName: s
  return (getNoteFieldValue(noteInfo, preferredName) ?? '').trim().length > 0;
 }

-export function shouldMarkWordAndSentenceCard(
-  noteInfo: NoteFieldValueInfo,
-  sentenceCardConfig: { lapisEnabled: boolean; kikuEnabled: boolean },
-): boolean {
-  if (!sentenceCardConfig.lapisEnabled && !sentenceCardConfig.kikuEnabled) {
-    return false;
-  }
+/** Flags set only by an explicit mine action; a note carrying one is not a word card. */
+const EXPLICIT_CARD_FLAG_FIELDS = [CARD_KIND_FLAG_FIELDS.sentence, CARD_KIND_FLAG_FIELDS.audio];

-  const wordAndSentenceValue = getNoteFieldValue(noteInfo, 'IsWordAndSentenceCard');
-  if (wordAndSentenceValue === null) {
-    return false;
+const warnedMissingFlagFields = new Set<CardKind>();
+
+function warnMissingFlagFieldOnce(wordCardKind: CardKind, flagField: string): void {
+  if (wordCardKind === DEFAULT_WORD_CARD_KIND || warnedMissingFlagFields.has(wordCardKind)) {
+    // The default kind is also the fallback for plain note types, so its absence is expected.
+    return;
  }
-  if (wordAndSentenceValue.trim().length > 0) {
-    return true;
-  }
-  return (
-    !hasNoteFieldValue(noteInfo, 'IsSentenceCard') && !hasNoteFieldValue(noteInfo, 'IsAudioCard')
+  warnedMissingFlagFields.add(wordCardKind);
+  log.warn(
+    `Word card type "${wordCardKind}" is configured but the note has no ${flagField} field; leaving card type flags unchanged.`,
  );
 }
+
+/**
+ * Card kind to flag when SubMiner fills a word card's sentence, or null to leave the
+ * card-kind flags alone. Kiku/Lapis only: other note types have no such fields.
+ */
+export function resolveWordCardKind(
+  noteInfo: NoteFieldValueInfo,
+  sentenceCardConfig: {
+    lapisEnabled: boolean;
+    kikuEnabled: boolean;
+    wordCardKind?: WordCardKind;
+  },
+): CardKind | null {
+  if (!sentenceCardConfig.lapisEnabled && !sentenceCardConfig.kikuEnabled) {
+    return null;
+  }
+
+  const wordCardKind = resolveWordCardKindSetting(sentenceCardConfig.wordCardKind);
+  if (wordCardKind === 'none') {
+    return null;
+  }
+
+  const flagField = CARD_KIND_FLAG_FIELDS[wordCardKind];
+  const flagValue = getNoteFieldValue(noteInfo, flagField);
+  if (flagValue === null) {
+    // Note type has no flag field for the configured kind.
+    warnMissingFlagFieldOnce(wordCardKind, flagField);
+    return null;
+  }
+  if (flagValue.trim().length > 0) {
+    return wordCardKind;
+  }
+
+  const alreadyExplicitCard = EXPLICIT_CARD_FLAG_FIELDS.some(
+    (fieldName) =>
+      fieldName.toLowerCase() !== flagField.toLowerCase() && hasNoteFieldValue(noteInfo, fieldName),
+  );
+  return alreadyExplicitCard ? null : wordCardKind;
+}
@@ -6,26 +6,21 @@ import {
  type NoteUpdateWorkflowNoteInfo,
 } from './note-update-workflow';
 import type { SubtitleMiningContext } from '../types/subtitle';
+import type { CardKind } from '../types/anki';
+import { applyCardKindFlagFields } from './card-kinds';

-function setWordAndSentenceCardTypeFields(
+function setCardTypeFields(
  updatedFields: Record<string, string>,
  availableFieldNames: string[],
-  cardKind: 'word-and-sentence',
+  cardKind: CardKind,
 ): void {
-  assert.equal(cardKind, 'word-and-sentence');
-  const resolveFieldName = (preferredName: string): string | null =>
-    availableFieldNames.find((name) => name.toLowerCase() === preferredName.toLowerCase()) ?? null;
-
-  const wordAndSentenceFlag = resolveFieldName('IsWordAndSentenceCard');
-  if (!wordAndSentenceFlag) return;
-
-  updatedFields[wordAndSentenceFlag] = 'x';
-  for (const flagName of ['IsSentenceCard', 'IsAudioCard']) {
-    const resolved = resolveFieldName(flagName);
-    if (resolved && resolved !== wordAndSentenceFlag) {
-      updatedFields[resolved] = '';
-    }
-  }
+  applyCardKindFlagFields(
+    updatedFields,
+    cardKind,
+    (preferredName) =>
+      availableFieldNames.find((name) => name.toLowerCase() === preferredName.toLowerCase()) ??
+      null,
+  );
 }

 function createWorkflowHarness() {
@@ -79,7 +74,7 @@ function createWorkflowHarness() {
    handleFieldGroupingManual: async (_originalNoteId, _newNoteId, _newNoteInfo, _expression) =>
      false,
    processSentence: (text: string, _noteFields: Record<string, string>) => text,
-    setCardTypeFields: setWordAndSentenceCardTypeFields,
+    setCardTypeFields,
    resolveConfiguredFieldName: (noteInfo: NoteUpdateWorkflowNoteInfo, preferred?: string) => {
      if (!preferred) return null;
      const names = Object.keys(noteInfo.fields);
@@ -183,6 +178,73 @@ test('NoteUpdateWorkflow marks enriched Kiku word cards as word-and-sentence car
  });
 });

+test('NoteUpdateWorkflow marks the configured word card kind instead of word-and-sentence', async () => {
+  const harness = createWorkflowHarness();
+  harness.deps.getEffectiveSentenceCardConfig = () => ({
+    sentenceField: 'Sentence',
+    lapisEnabled: false,
+    kikuEnabled: true,
+    kikuFieldGrouping: 'manual',
+    wordCardKind: 'click',
+  });
+  harness.deps.client.notesInfo = async () =>
+    [
+      {
+        noteId: 42,
+        fields: {
+          Expression: { value: 'taberu' },
+          Sentence: { value: '' },
+          IsWordAndSentenceCard: { value: 'x' },
+          IsClickCard: { value: '' },
+          IsSentenceCard: { value: '' },
+          IsAudioCard: { value: '' },
+        },
+      },
+    ] satisfies NoteUpdateWorkflowNoteInfo[];
+
+  await harness.workflow.execute(42);
+
+  assert.equal(harness.updates.length, 1);
+  assert.deepEqual(harness.updates[0]?.fields, {
+    Sentence: 'subtitle-text',
+    IsClickCard: 'x',
+    IsWordAndSentenceCard: '',
+    IsSentenceCard: '',
+    IsAudioCard: '',
+  });
+});
+
+test('NoteUpdateWorkflow leaves card type flags alone when the word card kind is none', async () => {
+  const harness = createWorkflowHarness();
+  harness.deps.getEffectiveSentenceCardConfig = () => ({
+    sentenceField: 'Sentence',
+    lapisEnabled: false,
+    kikuEnabled: true,
+    kikuFieldGrouping: 'manual',
+    wordCardKind: 'none',
+  });
+  harness.deps.client.notesInfo = async () =>
+    [
+      {
+        noteId: 42,
+        fields: {
+          Expression: { value: 'taberu' },
+          Sentence: { value: '' },
+          IsWordAndSentenceCard: { value: '' },
+          IsSentenceCard: { value: '' },
+          IsAudioCard: { value: '' },
+        },
+      },
+    ] satisfies NoteUpdateWorkflowNoteInfo[];
+
+  await harness.workflow.execute(42);
+
+  assert.equal(harness.updates.length, 1);
+  assert.deepEqual(harness.updates[0]?.fields, {
+    Sentence: 'subtitle-text',
+  });
+});
+
 test('NoteUpdateWorkflow does not set Kiku card flags when Lapis and Kiku are disabled', async () => {
  const harness = createWorkflowHarness();
  harness.deps.client.notesInfo = async () =>
@@ -1,7 +1,8 @@
 import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
 import { getPreferredWordValueFromExtractedFields } from '../anki-field-config';
 import type { SubtitleMiningContext } from '../types/subtitle';
-import { shouldMarkWordAndSentenceCard } from './note-field-utils';
+import type { CardKind, WordCardKind } from '../types/anki';
+import { resolveWordCardKind } from './note-field-utils';

 export interface NoteUpdateWorkflowNoteInfo {
  noteId: number;
@@ -39,6 +40,7 @@ export interface NoteUpdateWorkflowDeps {
    lapisEnabled: boolean;
    kikuEnabled: boolean;
    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
+    wordCardKind?: WordCardKind;
  };
  appendKnownWordsFromNoteInfo: (noteInfo: NoteUpdateWorkflowNoteInfo) => void;
  extractFields: (fields: Record<string, { value: string }>) => Record<string, string>;
@@ -67,7 +69,7 @@ export interface NoteUpdateWorkflowDeps {
  setCardTypeFields: (
    updatedFields: Record<string, string>,
    availableFieldNames: string[],
-    cardKind: 'word-and-sentence',
+    cardKind: CardKind,
  ) => void;
  resolveConfiguredFieldName: (
    noteInfo: NoteUpdateWorkflowNoteInfo,
@@ -207,12 +209,9 @@ export class NoteUpdateWorkflow {
      if (sentenceField && currentSubtitleText) {
        const processedSentence = this.deps.processSentence(currentSubtitleText, fields);
        updatedFields[sentenceField] = processedSentence;
-        if (shouldMarkWordAndSentenceCard(noteInfo, sentenceCardConfig)) {
-          this.deps.setCardTypeFields(
-            updatedFields,
-            Object.keys(noteInfo.fields),
-            'word-and-sentence',
-          );
+        const wordCardKind = resolveWordCardKind(noteInfo, sentenceCardConfig);
+        if (wordCardKind) {
+          this.deps.setCardTypeFields(updatedFields, Object.keys(noteInfo.fields), wordCardKind);
        }
        updatePerformed = true;
      }
@@ -116,6 +116,10 @@ export function normalizeAnkiIntegrationConfig(config: AnkiConnectConfig): AnkiC
      ...DEFAULT_ANKI_CONNECT_CONFIG.isKiku,
      ...(config.isKiku ?? {}),
    },
+    lapisKiku: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.lapisKiku,
+      ...(config.lapisKiku ?? {}),
+    },
  } as AnkiConnectConfig;
 }

@@ -205,6 +209,10 @@ export class AnkiIntegrationRuntime {
        patch.isKiku !== undefined
          ? { ...this.config.isKiku, ...patch.isKiku }
          : this.config.isKiku,
+      lapisKiku:
+        patch.lapisKiku !== undefined
+          ? { ...this.config.lapisKiku, ...patch.lapisKiku }
+          : this.config.lapisKiku,
    };
    this.config = normalizeAnkiIntegrationConfig(mergedConfig);
    this.deps.onConfigChanged?.(this.config);
@@ -2738,6 +2738,43 @@ test('ignores deprecated isLapis sentence-card field overrides', () => {
  );
 });

+test('accepts a Kiku/Lapis word card kind and warns on an unknown one', () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "isKiku": { "enabled": true },
+        "lapisKiku": { "wordCardKind": "click" }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const service = new ConfigService(dir);
+  assert.equal(service.getConfig().ankiConnect.lapisKiku.wordCardKind, 'click');
+  assert.equal(service.getWarnings().length, 0);
+
+  const invalidDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(invalidDir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "lapisKiku": { "wordCardKind": "isClickCard" }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const invalidService = new ConfigService(invalidDir);
+  assert.equal(invalidService.getConfig().ankiConnect.lapisKiku.wordCardKind, 'word-and-sentence');
+  assert.ok(
+    invalidService
+      .getWarnings()
+      .some((warning) => warning.path === 'ankiConnect.lapisKiku.wordCardKind'),
+  );
+});
+
 test('accepts valid ankiConnect knownWords deck object', () => {
  const dir = makeTempDir();
  fs.writeFileSync(
@@ -91,6 +91,9 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
      fieldGrouping: 'disabled',
      deleteDuplicateInAuto: true,
    },
+    lapisKiku: {
+      wordCardKind: 'word-and-sentence',
+    },
  },
  jimaku: {
    apiBaseUrl: 'https://jimaku.cc',
@@ -1,4 +1,5 @@
 import { ResolvedConfig } from '../../types/config';
+import { WORD_CARD_KINDS } from '../../anki-integration/card-kinds';
 import { MPV_LAUNCH_MODE_VALUES } from '../../shared/mpv-launch-mode';
 import {
  NOTIFICATION_TYPE_VALUES,
@@ -374,6 +375,21 @@ export function buildIntegrationConfigOptionRegistry(
      defaultValue: defaultConfig.ankiConnect.isLapis.sentenceCardModel,
      description: 'Note type name used by Lapis sentence cards.',
    },
+    {
+      path: 'ankiConnect.lapisKiku.wordCardKind',
+      kind: 'enum',
+      enumValues: WORD_CARD_KINDS,
+      enumLabels: {
+        'word-and-sentence': 'Word and sentence card (IsWordAndSentenceCard)',
+        click: 'Click card (IsClickCard)',
+        sentence: 'Sentence card (IsSentenceCard)',
+        audio: 'Audio card (IsAudioCard)',
+        none: 'Leave card type flags untouched',
+      },
+      defaultValue: defaultConfig.ankiConnect.lapisKiku.wordCardKind,
+      description:
+        'Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled.',
+    },
    {
      path: 'ankiConnect.metadata.pattern',
      kind: 'string',
@@ -135,7 +135,7 @@ const INTEGRATION_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
    title: 'AnkiConnect Integration',
    description: ['Automatic Anki updates and media generation options.'],
    notes: [
-      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.',
+      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.',
      'Shared AI provider transport settings are read from top-level ai and typically require restart.',
      'Most other AnkiConnect settings still require restart.',
    ],
@@ -1,6 +1,7 @@
 import type { ResolveContext } from './context';
 import { initializeAnkiConnectResolution } from './anki-connect/initialize';
 import { applyAnkiKikuResolution } from './anki-connect/kiku';
+import { applyAnkiLapisKikuResolution } from './anki-connect/lapis-kiku';
 import { applyAnkiKnownWordsResolution } from './anki-connect/known-words';
 import { applyAnkiLegacyResolution } from './anki-connect/legacy';
 import { applyAnkiModernResolution } from './anki-connect/modern';
@@ -22,4 +23,5 @@ export function applyAnkiConnectResolution(context: ResolveContext): void {
  applyAnkiLegacyResolution(context, ankiConnect, behavior, fields, media, metadata);
  applyAnkiKnownWordsResolution(context, ankiConnect, behavior);
  applyAnkiKikuResolution(context);
+  applyAnkiLapisKikuResolution(context, ankiConnect);
 }
@@ -77,5 +77,8 @@ export function initializeAnkiConnectResolution(
        ? (ankiConnect.isKiku as (typeof context.resolved)['ankiConnect']['isKiku'])
        : {}),
    },
+    lapisKiku: {
+      ...context.resolved.ankiConnect.lapisKiku,
+    },
  };
 }
@@ -0,0 +1,39 @@
+import { isWordCardKind, WORD_CARD_KINDS } from '../../../anki-integration/card-kinds';
+import { DEFAULT_CONFIG } from '../../definitions';
+import type { ResolveContext } from '../context';
+import { isObject } from '../shared';
+
+export function applyAnkiLapisKikuResolution(
+  context: ResolveContext,
+  ankiConnect: Record<string, unknown>,
+): void {
+  if (!isObject(ankiConnect.lapisKiku)) {
+    if (ankiConnect.lapisKiku !== undefined) {
+      context.warn(
+        'ankiConnect.lapisKiku',
+        ankiConnect.lapisKiku,
+        context.resolved.ankiConnect.lapisKiku,
+        'Expected object.',
+      );
+    }
+    return;
+  }
+
+  const wordCardKind = ankiConnect.lapisKiku.wordCardKind;
+  if (wordCardKind === undefined) {
+    return;
+  }
+  if (isWordCardKind(wordCardKind)) {
+    context.resolved.ankiConnect.lapisKiku.wordCardKind = wordCardKind;
+    return;
+  }
+
+  context.warn(
+    'ankiConnect.lapisKiku.wordCardKind',
+    wordCardKind,
+    DEFAULT_CONFIG.ankiConnect.lapisKiku.wordCardKind,
+    `Expected one of ${WORD_CARD_KINDS.join(', ')}.`,
+  );
+  context.resolved.ankiConnect.lapisKiku.wordCardKind =
+    DEFAULT_CONFIG.ankiConnect.lapisKiku.wordCardKind;
+}
@@ -221,6 +221,7 @@ const LABEL_OVERRIDES: Record<string, string> = {
  'ankiConnect.nPlusOne.enabled': 'Enabled',
  'ankiConnect.isLapis.enabled': 'Enable Lapis Features',
  'ankiConnect.isKiku.enabled': 'Enable Kiku Features',
+  'ankiConnect.lapisKiku.wordCardKind': 'Word Card Type',
  'stats.toggleKey': 'Toggle Stats Overlay',
  'shortcuts.openCharacterDictionaryManager': 'Open Character Dictionary Manager',
  'subtitleSidebar.pauseVideoOnHover': 'Pause Video On Hover - Sidebar',
@@ -255,6 +256,8 @@ const DESCRIPTION_OVERRIDES: Record<string, string> = {
    'Enable Lapis-specific mining behavior and sentence-card model targeting. When Kiku is enabled, Lapis features still work and Kiku-specific features are added on top.',
  'ankiConnect.isLapis.sentenceCardModel':
    'Anki note type used for Lapis sentence cards. Select from note types reported by AnkiConnect.',
+  'ankiConnect.lapisKiku.wordCardKind':
+    'Card-type flag marked on mined word cards. Only one flag is set at a time; the others are cleared. Requires Kiku or Lapis to be enabled.',
  'subtitleStyle.css':
    'CSS declarations applied to primary subtitles. Includes color, background-color, and all font properties.',
  'subtitleStyle.secondary.css':
@@ -401,7 +404,11 @@ function categoryAndSection(path: string): { category: ConfigSettingsCategory; s
  if (path.startsWith('ankiConnect.media.')) {
    return { category: 'mining-anki', section: 'Media Capture' };
  }
-  if (path.startsWith('ankiConnect.isKiku.') || path.startsWith('ankiConnect.isLapis.')) {
+  if (
+    path.startsWith('ankiConnect.isKiku.') ||
+    path.startsWith('ankiConnect.isLapis.') ||
+    path.startsWith('ankiConnect.lapisKiku.')
+  ) {
    return { category: 'mining-anki', section: 'Kiku/Lapis Features' };
  }
  if (path.startsWith('ankiConnect.ai.')) {
@@ -702,6 +709,7 @@ function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
    path === 'ankiConnect.fields.miscInfo' ||
    path === 'ankiConnect.isLapis.sentenceCardModel' ||
    path === 'ankiConnect.isKiku.fieldGrouping' ||
+    path === 'ankiConnect.lapisKiku.wordCardKind' ||
    path === 'mpv.aniskipEnabled' ||
    path === 'mpv.aniskipButtonKey' ||
    path === 'stats.toggleKey' ||
@@ -0,0 +1,256 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { DatabaseSync } from '../immersion-tracker/sqlite';
+
+type ImmersionTrackerService = import('../immersion-tracker-service').ImmersionTrackerService;
+type ImmersionTrackerServiceCtor =
+  typeof import('../immersion-tracker-service').ImmersionTrackerService;
+
+let trackerCtor: ImmersionTrackerServiceCtor | null = null;
+
+async function loadTrackerCtor(): Promise<ImmersionTrackerServiceCtor> {
+  if (trackerCtor) return trackerCtor;
+  const mod = await import('../immersion-tracker-service');
+  trackerCtor = mod.ImmersionTrackerService;
+  return trackerCtor;
+}
+
+function makeDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-write-queue-test-'));
+  return path.join(dir, 'immersion.sqlite');
+}
+
+function cleanupDbPath(dbPath: string): void {
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) return;
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+interface TrackerInternals {
+  db: DatabaseSync;
+  queue: unknown[];
+  recordWrite: (write: Record<string, unknown>) => void;
+  mergeAnime: (targetAnimeId: number, sourceAnimeIds: number[]) => Promise<unknown>;
+  moveVideoToAnime: (videoId: number, targetAnimeId: number) => Promise<unknown>;
+  rebuildLifetimeSummaries: () => Promise<unknown>;
+  flushNow: () => void;
+}
+
+test('mergeAnime fails closed when queued writes cannot drain', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
+    const internals = tracker as unknown as TrackerInternals;
+    seedTwoEntries(internals.db);
+    queueSubtitleLines(internals, 1);
+    internals.flushNow = () => {};
+
+    await assert.rejects(internals.mergeAnime(1, [2]), /queue did not drain/i);
+
+    assert.deepEqual(
+      internals.db
+        .prepare('SELECT anime_id AS animeId FROM imm_anime ORDER BY anime_id')
+        .all()
+        .map((row) => (row as { animeId: number }).animeId),
+      [1, 2],
+    );
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('moveVideoToAnime fails closed when queued writes cannot drain', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
+    const internals = tracker as unknown as TrackerInternals;
+    seedTwoEntries(internals.db);
+    queueSubtitleLines(internals, 1);
+    internals.flushNow = () => {};
+
+    await assert.rejects(internals.moveVideoToAnime(2, 1), /queue did not drain/i);
+    assert.equal(
+      (
+        internals.db
+          .prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = 2')
+          .get() as {
+          animeId: number;
+        }
+      ).animeId,
+      2,
+    );
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('rebuildLifetimeSummaries fails closed when queued writes cannot drain', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
+    const internals = tracker as unknown as TrackerInternals;
+    seedTwoEntries(internals.db);
+    queueSubtitleLines(internals, 1);
+    internals.flushNow = () => {};
+
+    await assert.rejects(internals.rebuildLifetimeSummaries(), /queue did not drain/i);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+function seedTwoEntries(db: DatabaseSync): void {
+  db.exec(`
+    INSERT INTO imm_anime (anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'show', 'Show', 1000, 1000), (2, 'show season 1', 'Show Season 1', 1000, 1000);
+    INSERT INTO imm_videos (video_id, video_key, canonical_title, anime_id, source_type, watched, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'local:/tmp/a.mkv', 'A', 1, 1, 0, 1440000, 1000, 1000),
+             (2, 'local:/tmp/b.mkv', 'B', 2, 1, 0, 1440000, 1000, 1000);
+    INSERT INTO imm_sessions (session_id, session_uuid, video_id, started_at_ms, ended_at_ms, status, active_watched_ms, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'drain-session', 2, '1000', '2000', 2, 1000, 1000, 2000);
+  `);
+}
+
+function queueSubtitleLines(tracker: TrackerInternals, count: number): void {
+  for (let index = 0; index < count; index += 1) {
+    tracker.recordWrite({
+      kind: 'subtitleLine',
+      sessionId: 1,
+      videoId: 2,
+      lineIndex: index,
+      segmentStartMs: index * 1000,
+      segmentEndMs: index * 1000 + 900,
+      text: `line ${index}`,
+      wordOccurrences: [],
+      kanjiOccurrences: [],
+      firstSeen: 1000,
+      lastSeen: 2000,
+    });
+  }
+}
+
+/**
+ * Queued last so it sits past the first batch. Lifetime `total_lines_seen`
+ * reads this counter, not a COUNT over imm_subtitle_lines, so the rebuilt
+ * summary only reflects the session once the queue is drained all the way.
+ */
+function queueTelemetry(tracker: TrackerInternals, linesSeen: number): void {
+  tracker.recordWrite({
+    kind: 'telemetry',
+    sessionId: 1,
+    sampleMs: 3000,
+    lastMediaMs: 3000,
+    totalWatchedMs: 4000,
+    activeWatchedMs: 3500,
+    linesSeen,
+    tokensSeen: linesSeen * 5,
+    cardsMined: 2,
+    lookupCount: 0,
+    lookupHits: 0,
+    yomitanLookupCount: 0,
+    pauseCount: 0,
+    pauseMs: 0,
+    seekForwardCount: 0,
+    seekBackwardCount: 0,
+    mediaBufferEvents: 0,
+  });
+}
+
+function lifetimeForAnime(
+  db: DatabaseSync,
+  animeId: number,
+): { linesSeen: number; activeMs: number; cards: number } | null {
+  const row = db
+    .prepare(
+      `SELECT total_lines_seen AS linesSeen, total_active_ms AS activeMs, total_cards AS cards
+       FROM imm_lifetime_anime WHERE anime_id = ?`,
+    )
+    .get(animeId) as { linesSeen: number; activeMs: number; cards: number } | undefined;
+  return row
+    ? { linesSeen: Number(row.linesSeen), activeMs: Number(row.activeMs), cards: Number(row.cards) }
+    : null;
+}
+
+function countLinesForAnime(db: DatabaseSync, animeId: number): number {
+  const row = db
+    .prepare('SELECT COUNT(*) AS total FROM imm_subtitle_lines WHERE anime_id = ?')
+    .get(animeId) as { total: number };
+  return Number(row.total);
+}
+
+/**
+ * Both entry points rebuild the lifetime summaries, which recompute from the
+ * database. A single flushNow() only writes one batch off the front of the
+ * queue, so anything past `batchSize` would still be unwritten when the rebuild
+ * reads.
+ */
+test('mergeAnime drains a queue larger than one batch before rebuilding summaries', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
+    const internals = tracker as unknown as TrackerInternals;
+
+    seedTwoEntries(internals.db);
+    queueSubtitleLines(internals, 8);
+    queueTelemetry(internals, 8);
+    assert.ok(internals.queue.length > 2, 'expected more queued writes than one batch');
+
+    await internals.mergeAnime(1, [2]);
+
+    assert.equal(internals.queue.length, 0);
+    assert.equal(countLinesForAnime(internals.db, 1), 8);
+    // The surviving entry's summary was rebuilt from the fully drained queue.
+    const lifetime = lifetimeForAnime(internals.db, 1);
+    assert.equal(lifetime?.linesSeen, 8);
+    assert.equal(lifetime?.activeMs, 3500);
+    assert.equal(lifetime?.cards, 2);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('moveVideoToAnime drains a queue larger than one batch before rebuilding summaries', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
+    const internals = tracker as unknown as TrackerInternals;
+
+    seedTwoEntries(internals.db);
+    queueSubtitleLines(internals, 8);
+    queueTelemetry(internals, 8);
+
+    await internals.moveVideoToAnime(2, 1);
+
+    assert.equal(internals.queue.length, 0);
+    assert.equal(countLinesForAnime(internals.db, 1), 8);
+    const lifetime = lifetimeForAnime(internals.db, 1);
+    assert.equal(lifetime?.linesSeen, 8);
+    assert.equal(lifetime?.activeMs, 3500);
+    assert.equal(lifetime?.cards, 2);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
@@ -1053,6 +1053,55 @@ describe('stats server API routes', () => {
    assert.equal(body[0].canonicalTitle, 'Little Witch Academia');
  });

+  it('GET /api/stats/anime/merge-recommendations returns pending duplicate pairs', async () => {
+    const app = createStatsApp(
+      createMockTracker({
+        getAnimeMergeRecommendations: async () => [{ recommendationId: 4, animeIds: [1, 2] }],
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/merge-recommendations');
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(await res.json(), {
+      recommendations: [{ recommendationId: 4, animeIds: [1, 2] }],
+    });
+  });
+
+  it('DELETE /api/stats/anime/merge-recommendations/:id dismisses a pending pair', async () => {
+    let dismissedId: number | null = null;
+    const app = createStatsApp(
+      createMockTracker({
+        dismissAnimeMergeRecommendation: async (recommendationId: number) => {
+          dismissedId = recommendationId;
+          return true;
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/merge-recommendations/4', {
+      method: 'DELETE',
+    });
+
+    assert.equal(res.status, 200);
+    assert.equal(dismissedId, 4);
+    assert.deepEqual(await res.json(), { ok: true });
+  });
+
+  it('DELETE /api/stats/anime/merge-recommendations/:id reports missing recommendations', async () => {
+    const app = createStatsApp(
+      createMockTracker({
+        dismissAnimeMergeRecommendation: async () => false,
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/merge-recommendations/99', {
+      method: 'DELETE',
+    });
+
+    assert.equal(res.status, 404);
+  });
+
  it('GET /api/stats/anime/:animeId returns anime detail with episodes', async () => {
    const app = createStatsApp(createMockTracker());
    const res = await app.request('/api/stats/anime/1');
@@ -1100,12 +1149,56 @@ describe('stats server API routes', () => {
    assert.deepEqual(assignments, [{ animeId: 1, body }]);
  });

-  it('GET /api/stats/anime/:animeId/cover returns cover art', async () => {
+  it('GET /api/stats/anime/:animeId/cover returns revalidated cover art', async () => {
    const app = createStatsApp(createMockTracker());
    const res = await app.request('/api/stats/anime/1/cover');
    assert.equal(res.status, 200);
    assert.equal(res.headers.get('content-type'), 'image/jpeg');
-    assert.equal(res.headers.get('cache-control'), 'public, max-age=86400');
+    assert.equal(res.headers.get('cache-control'), 'no-cache');
+    assert.ok(res.headers.get('etag'));
+  });
+
+  it('GET /api/stats/anime/:animeId/cover answers 304 for a matching ETag', async () => {
+    const app = createStatsApp(createMockTracker());
+    const first = await app.request('/api/stats/anime/1/cover');
+    const etag = first.headers.get('etag');
+    assert.ok(etag);
+
+    const cached = await app.request('/api/stats/anime/1/cover', {
+      headers: { 'If-None-Match': `W/${etag}, "other"` },
+    });
+    assert.equal(cached.status, 304);
+    assert.equal(cached.headers.get('etag'), etag);
+  });
+
+  it('GET /api/stats/anime/:animeId/cover resends art when the ETag no longer matches', async () => {
+    // A relinked AniList entry swaps the bytes behind the same cover URL.
+    let coverBlob = Buffer.from([0xff, 0xd8, 0xff, 0xd9]);
+    const app = createStatsApp(
+      createMockTracker({
+        getAnimeCoverArt: async () => ({
+          videoId: 1,
+          anilistId: 21858,
+          coverUrl: 'https://example.com/cover.jpg',
+          coverBlob,
+          titleRomaji: 'Little Witch Academia',
+          titleEnglish: 'Little Witch Academia',
+          episodesTotal: 25,
+          fetchedAtMs: Date.now(),
+        }),
+      }),
+    );
+    const first = await app.request('/api/stats/anime/1/cover');
+    const staleEtag = first.headers.get('etag');
+    assert.ok(staleEtag);
+
+    coverBlob = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const res = await app.request('/api/stats/anime/1/cover', {
+      headers: { 'If-None-Match': staleEtag },
+    });
+    assert.equal(res.status, 200);
+    assert.equal(res.headers.get('content-type'), 'image/png');
+    assert.notEqual(res.headers.get('etag'), staleEtag);
  });

  it('GET /api/stats/anime/:animeId/cover serves detected cover MIME type', async () => {
@@ -2410,6 +2503,80 @@ Aligned English subtitle
    });
  });

+  it('POST /api/stats/mine-card marks the configured Kiku word card kind', async () => {
+    await withTempDir(async (dir) => {
+      const sourcePath = path.join(dir, 'episode.mkv');
+      fs.writeFileSync(sourcePath, 'fake media');
+
+      await withFakeAnkiConnect(
+        async (requests, url) => {
+          const app = createStatsApp(createMockTracker(), {
+            addYomitanNote: async () => 777,
+            createMediaGenerator: () => ({
+              generateAudio: async () => null,
+              generateScreenshot: async () => null,
+              generateAnimatedImage: async () => null,
+            }),
+            ankiConnectConfig: {
+              url,
+              deck: 'Mining',
+              fields: {
+                image: 'Picture',
+                sentence: 'Sentence',
+              },
+              media: {
+                generateAudio: false,
+                generateImage: false,
+              },
+              isKiku: {
+                enabled: true,
+                fieldGrouping: 'disabled',
+                deleteDuplicateInAuto: true,
+              },
+              lapisKiku: {
+                wordCardKind: 'click',
+              },
+            },
+          });
+
+          const res = await app.request('/api/stats/mine-card?mode=word', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              sourcePath,
+              startMs: 1_000,
+              endMs: 2_000,
+              sentence: '猫を見た',
+              word: '猫',
+              videoTitle: 'Episode 1',
+            }),
+          });
+
+          const body = await res.json();
+          assert.equal(res.status, 200, JSON.stringify(body));
+
+          const updateRequest = requests.find((request) => request.action === 'updateNoteFields');
+          const fields = updateRequest?.params?.note?.fields ?? {};
+          assert.equal(fields.IsClickCard, 'x');
+          assert.equal(fields.IsWordAndSentenceCard, '');
+          assert.equal(fields.IsSentenceCard, '');
+          assert.equal(fields.IsAudioCard, '');
+        },
+        {
+          notesInfoFields: {
+            Expression: { value: '猫' },
+            Sentence: { value: '' },
+            Picture: { value: '' },
+            IsWordAndSentenceCard: { value: '' },
+            IsClickCard: { value: '' },
+            IsSentenceCard: { value: '' },
+            IsAudioCard: { value: '' },
+          },
+        },
+      );
+    });
+  });
+
  it('POST /api/stats/mine-card writes word mining sentence audio and image together', async () => {
    await withTempDir(async (dir) => {
      const sourcePath = path.join(dir, 'episode.mkv');
@@ -2873,6 +3040,181 @@ Aligned English subtitle
    assert.equal(deleteCalls, 0);
  });

+  it('DELETE /api/stats/anime/:animeId deletes the whole library entry', async () => {
+    let deletedAnimeId: number | null = null;
+    const app = createStatsApp(
+      createMockTracker({
+        deleteAnime: async (animeId: number) => {
+          deletedAnimeId = animeId;
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/7', { method: 'DELETE' });
+
+    assert.equal(res.status, 200);
+    assert.equal(deletedAnimeId, 7);
+    assert.deepEqual(await res.json(), { ok: true });
+  });
+
+  it('DELETE /api/stats/anime/:animeId rejects non-positive anime ids', async () => {
+    let deleteCalls = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        deleteAnime: async () => {
+          deleteCalls += 1;
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/0', { method: 'DELETE' });
+
+    assert.equal(res.status, 400);
+    assert.equal(deleteCalls, 0);
+  });
+
+  it('POST /api/stats/anime/:animeId/merge folds the given entries into the target', async () => {
+    let merged: { targetAnimeId: number; sourceAnimeIds: number[] } | null = null;
+    const app = createStatsApp(
+      createMockTracker({
+        mergeAnime: async (targetAnimeId: number, sourceAnimeIds: number[]) => {
+          merged = { targetAnimeId, sourceAnimeIds };
+          return {
+            survivingAnimeId: targetAnimeId,
+            mergedAnimeIds: sourceAnimeIds,
+            movedVideos: 3,
+          };
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/7/merge', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      // The target repeated in the sources must not delete the entry we keep.
+      body: '{"sourceAnimeIds":[8,9,8,7]}',
+    });
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(merged, { targetAnimeId: 7, sourceAnimeIds: [8, 9] });
+    assert.deepEqual(await res.json(), {
+      ok: true,
+      animeId: 7,
+      mergedAnimeIds: [8, 9],
+      movedVideos: 3,
+    });
+  });
+
+  it('POST /api/stats/anime/:animeId/merge rejects an empty or malformed source list', async () => {
+    let mergeCalls = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        mergeAnime: async () => {
+          mergeCalls += 1;
+          return { survivingAnimeId: 7, mergedAnimeIds: [], movedVideos: 0 };
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    for (const body of [
+      '{"sourceAnimeIds":[]}',
+      '{"sourceAnimeIds":[7]}',
+      '{"sourceAnimeIds":0}',
+    ]) {
+      const res = await app.request('/api/stats/anime/7/merge', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      });
+      assert.equal(res.status, 400);
+    }
+    assert.equal(mergeCalls, 0);
+  });
+
+  it('PATCH /api/stats/media/:videoId/anime moves the episode to another entry', async () => {
+    let moved: { videoId: number; animeId: number } | null = null;
+    const app = createStatsApp(
+      createMockTracker({
+        moveVideoToAnime: async (videoId: number, animeId: number) => {
+          moved = { videoId, animeId };
+          return { targetAnimeId: animeId, previousAnimeId: 4, removedPreviousAnime: true };
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/media/12/anime', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"animeId":7}',
+    });
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(moved, { videoId: 12, animeId: 7 });
+    assert.deepEqual(await res.json(), {
+      ok: true,
+      animeId: 7,
+      previousAnimeId: 4,
+      removedPreviousAnime: true,
+    });
+  });
+
+  it('POST /api/stats/anime/:animeId/merge reports a merge that folded nothing as 404', async () => {
+    const app = createStatsApp(
+      createMockTracker({
+        mergeAnime: async (targetAnimeId: number) => ({
+          survivingAnimeId: targetAnimeId,
+          mergedAnimeIds: [],
+          movedVideos: 0,
+        }),
+      } 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, 404);
+  });
+
+  it('PATCH /api/stats/media/:videoId/anime reports an unknown target as 404', async () => {
+    const app = createStatsApp(
+      createMockTracker({
+        moveVideoToAnime: async () => {
+          throw new Error('Unknown episode or target library entry');
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/media/12/anime', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"animeId":99}',
+    });
+
+    assert.equal(res.status, 404);
+  });
+
+  it('PATCH /api/stats/media/:videoId/anime does not disguise storage failures as 404', async () => {
+    const app = createStatsApp(
+      createMockTracker({
+        moveVideoToAnime: async () => {
+          throw new Error('database is locked');
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/media/12/anime', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"animeId":7}',
+    });
+
+    assert.notEqual(res.status, 404);
+    assert.equal(res.status >= 500, true);
+  });
+
  it('POST /api/stats/anki/browse returns 400 for missing noteId', async () => {
    const app = createStatsApp(createMockTracker());
    const res = await app.request('/api/stats/anki/browse', { method: 'POST' });
@@ -143,3 +143,50 @@ test('anilist update queue persists and reloads from disk', () => {
  });
  assert.equal(queueB.nextReady(Number.MAX_SAFE_INTEGER)?.title, 'Persist Demo');
 });
+
+test('drops queued items whose persisted mediaId is not a positive integer', () => {
+  const filePath = path.join(
+    fs.mkdtempSync(path.join(os.tmpdir(), 'anilist-queue-mediaid-')),
+    'queue.json',
+  );
+  const base = {
+    episode: 1,
+    createdAt: 1,
+    attemptCount: 0,
+    nextAttemptAt: 0,
+    lastError: null,
+  };
+  fs.writeFileSync(
+    filePath,
+    JSON.stringify({
+      pending: [
+        { ...base, key: 'ok-absent', title: 'A' },
+        { ...base, key: 'ok-null', title: 'B', mediaId: null },
+        { ...base, key: 'ok-valid', title: 'C', mediaId: 108489 },
+        { ...base, key: 'bad-string', title: 'D', mediaId: '108489' },
+        { ...base, key: 'bad-zero', title: 'E', mediaId: 0 },
+        { ...base, key: 'bad-negative', title: 'F', mediaId: -3 },
+        { ...base, key: 'bad-float', title: 'G', mediaId: 1.5 },
+        { ...base, key: 'bad-object', title: 'H', mediaId: { id: 1 } },
+      ],
+      deadLetter: [],
+    }),
+    'utf-8',
+  );
+
+  const queue = createAnilistUpdateQueue(filePath, {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  });
+
+  const keptKeys: string[] = [];
+  for (let i = 0; i < 8; i += 1) {
+    const next = queue.nextReady(1000);
+    if (!next) break;
+    keptKeys.push(next.key);
+    queue.markSuccess(next.key);
+  }
+
+  assert.deepEqual(keptKeys, ['ok-absent', 'ok-null', 'ok-valid']);
+});
@@ -10,6 +10,8 @@ export interface AnilistQueuedUpdate {
  key: string;
  title: string;
  season?: number | null;
+  /** Pinned AniList media id from a manual override, when one applied at enqueue time. */
+  mediaId?: number | null;
  episode: number;
  createdAt: number;
  attemptCount: number;
@@ -29,13 +31,31 @@ export interface AnilistRetryQueueSnapshot {
 }

 export interface AnilistUpdateQueue {
-  enqueue: (key: string, title: string, episode: number, season?: number | null) => void;
+  enqueue: (
+    key: string,
+    title: string,
+    episode: number,
+    season?: number | null,
+    mediaId?: number | null,
+  ) => void;
  nextReady: (nowMs?: number) => AnilistQueuedUpdate | null;
  markSuccess: (key: string) => void;
  markFailure: (key: string, reason: string, nowMs?: number) => void;
  getSnapshot: (nowMs?: number) => AnilistRetryQueueSnapshot;
 }

+/**
+ * A persisted mediaId pins the update to a specific AniList entry, so a corrupted or
+ * hand-edited queue file must not be able to feed a bogus id straight to the mutation.
+ */
+function isValidPersistedMediaId(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === null ||
+    (typeof value === 'number' && Number.isInteger(value) && value > 0)
+  );
+}
+
 function clampBackoffMs(attemptCount: number): number {
  const computed = INITIAL_BACKOFF_MS * Math.pow(2, Math.max(0, attemptCount - 1));
  return Math.min(MAX_BACKOFF_MS, computed);
@@ -82,6 +102,7 @@ export function createAnilistUpdateQueue(
            typeof item.createdAt === 'number' &&
            typeof item.attemptCount === 'number' &&
            typeof item.nextAttemptAt === 'number' &&
+            isValidPersistedMediaId(item.mediaId) &&
            (typeof item.lastError === 'string' || item.lastError === null),
        )
        .slice(0, MAX_ITEMS);
@@ -96,6 +117,7 @@ export function createAnilistUpdateQueue(
            typeof item.createdAt === 'number' &&
            typeof item.attemptCount === 'number' &&
            typeof item.nextAttemptAt === 'number' &&
+            isValidPersistedMediaId(item.mediaId) &&
            (typeof item.lastError === 'string' || item.lastError === null),
        )
        .slice(0, MAX_ITEMS);
@@ -107,7 +129,13 @@ export function createAnilistUpdateQueue(
  load();

  return {
-    enqueue(key: string, title: string, episode: number, season: number | null = null): void {
+    enqueue(
+      key: string,
+      title: string,
+      episode: number,
+      season: number | null = null,
+      mediaId: number | null = null,
+    ): void {
      const existing =
        pending.find((item) => item.key === key) || deadLetter.find((item) => item.key === key);
      if (existing) {
@@ -120,6 +148,7 @@ export function createAnilistUpdateQueue(
        key,
        title,
        season,
+        mediaId,
        episode,
        createdAt: Date.now(),
        attemptCount: 0,
@@ -376,7 +376,7 @@ test('updateAnilistPostWatchProgress returns non-retryable error when media is n
  }
 });

-test('updateAnilistPostWatchProgress prefers season-specific AniList matches', async () => {
+test('updateAnilistPostWatchProgress resolves later seasons through the sequel chain', async () => {
  const originalFetch = globalThis.fetch;
  const searchTerms: string[] = [];
  let call = 0;
@@ -389,21 +389,45 @@ test('updateAnilistPostWatchProgress prefers season-specific AniList matches', a
        data: {
          Page: {
            media: [
-              { id: 202, episodes: 12, title: { english: 'Demo Show Season 2' } },
-              { id: 101, episodes: 12, title: { english: 'Demo Show' } },
+              { id: 101, episodes: 12, format: 'TV', title: { english: 'Demo Show' } },
+              { id: 202, episodes: 12, format: 'TV', title: { english: 'Demo Show Sequel' } },
            ],
          },
        },
      });
    }
    if (call === 2) {
-      assert.equal(body.variables?.mediaId, 202);
+      assert.equal(body.variables?.id, 101);
      return createJsonResponse({
        data: {
-          Media: { id: 202, mediaListEntry: null },
+          Media: {
+            relations: {
+              edges: [
+                {
+                  relationType: 'SEQUEL',
+                  node: {
+                    id: 202,
+                    type: 'ANIME',
+                    episodes: 12,
+                    format: 'TV',
+                    title: { english: 'Demo Show Sequel' },
+                  },
+                },
+              ],
+            },
+          },
        },
      });
    }
+    if (call === 3) {
+      assert.equal(body.variables?.mediaId, 202);
+      return createJsonResponse({
+        data: {
+          Media: { id: 202, mediaListEntry: { progress: 1, status: 'CURRENT' } },
+        },
+      });
+    }
+    assert.equal(body.variables?.mediaId, 202);
    return createJsonResponse({
      data: {
        SaveMediaListEntry: { progress: 2, status: 'CURRENT' },
@@ -415,16 +439,118 @@ test('updateAnilistPostWatchProgress prefers season-specific AniList matches', a
    const result = await updateAnilistPostWatchProgress('token', 'Demo Show', 2, {
      season: 2,
    });
-    assert.deepEqual(searchTerms, ['Demo Show Season 2']);
+    // Searches the bare title: AniList has no "Demo Show Season 2" entry to find.
+    assert.deepEqual(searchTerms, ['Demo Show']);
+    assert.equal(result.status, 'updated');
+    assert.match(result.message, /Demo Show Sequel/);
+    assert.equal(call, 4);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('updateAnilistPostWatchProgress refuses to update season 1 when the season is unresolvable', async () => {
+  const originalFetch = globalThis.fetch;
+  let call = 0;
+  globalThis.fetch = (async () => {
+    call += 1;
+    if (call === 1) {
+      return createJsonResponse({
+        data: {
+          Page: {
+            media: [{ id: 101, episodes: 12, format: 'TV', title: { english: 'Demo Show' } }],
+          },
+        },
+      });
+    }
+    return createJsonResponse({ data: { Media: { relations: { edges: [] } } } });
+  }) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Demo Show', 2, { season: 3 });
    assert.equal(result.status, 'error');
    assert.equal(result.retryable, false);
-    assert.match(result.message, /not in your AniList Planning or Watching list/i);
+    assert.match(result.message, /could not find season 3/i);
+    // Stops after search + relation lookup: no entry lookup, no save.
    assert.equal(call, 2);
  } finally {
    globalThis.fetch = originalFetch;
  }
 });

+test('updateAnilistPostWatchProgress uses a pinned media id without searching', async () => {
+  const originalFetch = globalThis.fetch;
+  let call = 0;
+  globalThis.fetch = (async (_input, init) => {
+    call += 1;
+    const body = JSON.parse(String(init?.body)) as { variables?: Record<string, unknown> };
+    if (call === 1) {
+      assert.equal(body.variables?.mediaId, 108489);
+      return createJsonResponse({
+        data: {
+          Media: {
+            id: 108489,
+            episodes: 12,
+            title: { english: 'Pinned Show' },
+            mediaListEntry: { progress: 4, status: 'CURRENT' },
+          },
+        },
+      });
+    }
+    assert.equal(body.variables?.mediaId, 108489);
+    return createJsonResponse({
+      data: { SaveMediaListEntry: { progress: 5, status: 'CURRENT' } },
+    });
+  }) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Wrong Guess', 5, {
+      season: 3,
+      mediaId: 108489,
+    });
+    assert.equal(result.status, 'updated');
+    assert.match(result.message, /Pinned Show/);
+    assert.equal(call, 2);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('updateAnilistPostWatchProgress marks the final episode completed for a pinned media id', async () => {
+  const originalFetch = globalThis.fetch;
+  let call = 0;
+  globalThis.fetch = (async (_input, init) => {
+    call += 1;
+    const body = JSON.parse(String(init?.body)) as { variables?: Record<string, unknown> };
+    if (call === 1) {
+      return createJsonResponse({
+        data: {
+          Media: {
+            id: 108489,
+            episodes: 12,
+            title: { english: 'Pinned Show' },
+            mediaListEntry: { progress: 11, status: 'CURRENT' },
+          },
+        },
+      });
+    }
+    assert.equal(body.variables?.status, 'COMPLETED');
+    return createJsonResponse({
+      data: { SaveMediaListEntry: { progress: 12, status: 'COMPLETED' } },
+    });
+  }) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Pinned Show', 12, {
+      mediaId: 108489,
+    });
+    assert.equal(result.status, 'updated');
+    assert.match(result.message, /completed/i);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test('updateAnilistPostWatchProgress does not update rewatching entries', async () => {
  const originalFetch = globalThis.fetch;
  let call = 0;
@@ -479,3 +605,33 @@ test('updateAnilistPostWatchProgress returns error when search fails', async ()
    globalThis.fetch = originalFetch;
  }
 });
+
+test('updateAnilistPostWatchProgress does not requeue a search that matched nothing', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    createJsonResponse({ data: { Page: { media: [] } } })) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Unknown Show', 3);
+    assert.equal(result.status, 'error');
+    assert.equal(result.retryable, false);
+    assert.match(result.message, /no matches/i);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('updateAnilistPostWatchProgress still allows retry when the search itself fails', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    createJsonResponse({ errors: [{ message: 'upstream exploded' }] })) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Demo Show', 3);
+    assert.equal(result.status, 'error');
+    assert.notEqual(result.retryable, false);
+    assert.match(result.message, /search failed/i);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
@@ -3,6 +3,7 @@ import * as path from 'path';

 import { parseMediaInfo } from '../../../jimaku/utils';
 import type { AnilistRateLimiter } from './rate-limiter';
+import { resolveAnilistSeasonMedia } from './season-resolver';

 const ANILIST_GRAPHQL_URL = 'https://graphql.anilist.co';

@@ -24,6 +25,12 @@ export interface AnilistPostWatchUpdateResult {
 export interface AnilistPostWatchUpdateOptions {
  rateLimiter?: AnilistRateLimiter;
  season?: number | null;
+  /**
+   * Pinned AniList media id (from a character dictionary manual override). When set,
+   * the search/season resolution is skipped entirely.
+   */
+  mediaId?: number | null;
+  logInfo?: (message: string) => void;
 }

 interface AnilistGraphQlError {
@@ -35,23 +42,15 @@ interface AnilistGraphQlResponse<T> {
  errors?: AnilistGraphQlError[];
 }

-interface AnilistSearchData {
-  Page?: {
-    media?: Array<{
+interface AnilistMediaEntryData {
+  Media?: {
    id: number;
-      episodes: number | null;
+    episodes?: number | null;
    title?: {
      romaji?: string | null;
      english?: string | null;
      native?: string | null;
-      };
-    }>;
-  };
-}
-
-interface AnilistMediaEntryData {
-  Media?: {
-    id: number;
+    } | null;
    mediaListEntry?: {
      progress?: number | null;
      status?: string | null;
@@ -154,32 +153,6 @@ function buildGuessitTitle(title: string, alternativeTitle: string | null): stri
  return title;
 }

-function normalizeTitle(text: string): string {
-  return text.trim().toLowerCase().replace(/\s+/g, ' ');
-}
-
-function titleMentionsSeason(title: string, season: number): boolean {
-  const normalized = normalizeTitle(title);
-  return (
-    normalized.includes(`season ${season}`) ||
-    normalized.includes(`s${String(season).padStart(2, '0')}`) ||
-    normalized.includes(`s${season}`)
-  );
-}
-
-function buildSearchCandidates(title: string, season: number | null | undefined): string[] {
-  const trimmed = title.trim();
-  if (!trimmed) return [];
-  const candidates =
-    typeof season === 'number' &&
-    Number.isInteger(season) &&
-    season > 1 &&
-    !titleMentionsSeason(trimmed, season)
-      ? [`${trimmed} Season ${season}`, trimmed]
-      : [trimmed];
-  return candidates.filter((candidate, index, all) => all.indexOf(candidate) === index);
-}
-
 async function anilistGraphQl<T>(
  accessToken: string,
  query: string,
@@ -216,38 +189,22 @@ function firstErrorMessage<T>(response: AnilistGraphQlResponse<T>): string | nul
  return firstError?.message ?? null;
 }

-function pickBestSearchResult(
-  title: string,
-  episode: number,
-  media: Array<{
-    id: number;
-    episodes: number | null;
-    title?: {
-      romaji?: string | null;
-      english?: string | null;
-      native?: string | null;
+/** The season resolver signals failure by throwing; anilistGraphQl reports it in-band. */
+function createAnilistSeasonQueryExecutor(
+  accessToken: string,
+  options: AnilistPostWatchUpdateOptions,
+) {
+  return async <T>(query: string, variables: Record<string, unknown>): Promise<T> => {
+    const response = await anilistGraphQl<T>(accessToken, query, variables, options);
+    const error = firstErrorMessage(response);
+    if (error) {
+      throw new Error(error);
+    }
+    if (!response.data) {
+      throw new Error('AniList response missing data');
+    }
+    return response.data;
  };
-  }>,
-): { id: number; title: string; episodes: number | null } | null {
-  const filtered = media.filter((item) => {
-    const totalEpisodes = item.episodes;
-    return totalEpisodes === null || totalEpisodes >= episode;
-  });
-  const candidates = filtered.length > 0 ? filtered : media;
-  if (candidates.length === 0) return null;
-
-  const normalizedTarget = normalizeTitle(title);
-  const exact = candidates.find((item) => {
-    const titles = [item.title?.romaji, item.title?.english, item.title?.native]
-      .filter((value): value is string => typeof value === 'string')
-      .map((value) => normalizeTitle(value));
-    return titles.includes(normalizedTarget);
-  });
-
-  const selected = exact ?? candidates[0]!;
-  const selectedTitle =
-    selected.title?.english || selected.title?.romaji || selected.title?.native || title;
-  return { id: selected.id, title: selectedTitle, episodes: selected.episodes };
 }

 function isUpdateableListStatus(status: string | null | undefined): boolean {
@@ -321,52 +278,53 @@ export async function updateAnilistPostWatchProgress(
  episode: number,
  options: AnilistPostWatchUpdateOptions = {},
 ): Promise<AnilistPostWatchUpdateResult> {
-  let media: NonNullable<NonNullable<AnilistSearchData['Page']>['media']> = [];
-  let searchError: string | null = null;
-  let pickTitle = title;
-  const searchCandidates = buildSearchCandidates(title, options.season);
-  for (const search of searchCandidates) {
-    const searchResponse = await anilistGraphQl<AnilistSearchData>(
-      accessToken,
-      `
-        query ($search: String!) {
-          Page(perPage: 5) {
-            media(search: $search, type: ANIME) {
-              id
-              episodes
-              title {
-                romaji
-                english
-                native
-              }
-            }
-          }
-        }
-      `,
-      { search },
-      options,
-    );
-    searchError = firstErrorMessage(searchResponse);
-    if (searchError) {
-      break;
-    }
-    media = searchResponse.data?.Page?.media ?? [];
-    if (media.length > 0) {
-      pickTitle = search;
-      break;
-    }
-  }
+  const pinnedMediaId =
+    typeof options.mediaId === 'number' && Number.isInteger(options.mediaId) && options.mediaId > 0
+      ? options.mediaId
+      : null;

-  if (searchError) {
+  let mediaId = pinnedMediaId;
+  let resolvedTitle: string | null = null;
+  let resolvedEpisodes: number | null = null;
+
+  if (mediaId === null) {
+    let resolution: Awaited<ReturnType<typeof resolveAnilistSeasonMedia>>;
+    try {
+      resolution = await resolveAnilistSeasonMedia(
+        { title, season: options.season, episode },
+        {
+          execute: createAnilistSeasonQueryExecutor(accessToken, options),
+          logInfo: options.logInfo,
+        },
+      );
+    } catch (error) {
      return {
        status: 'error',
-      message: `AniList search failed: ${searchError}`,
+        message: `AniList search failed: ${error instanceof Error ? error.message : String(error)}`,
      };
    }

-  const picked = pickBestSearchResult(pickTitle, episode, media);
-  if (!picked) {
-    return { status: 'error', message: 'AniList search returned no matches.' };
+    if (!resolution) {
+      // A well-formed search that matched nothing is deterministic for this title, so
+      // requeueing it just burns rate limit. Transient failures throw and are caught above.
+      return {
+        status: 'error',
+        retryable: false,
+        message: 'AniList search returned no matches.',
+      };
+    }
+    if (!resolution.seasonResolved) {
+      // Updating the season 1 entry here is worse than not updating at all.
+      return {
+        status: 'error',
+        retryable: false,
+        message: `AniList update skipped: could not find season ${resolution.requestedSeason} of "${title}" (only matched "${resolution.title}"). Pick the right entry with the character dictionary AniList override.`,
+      };
+    }
+
+    mediaId = resolution.id;
+    resolvedTitle = resolution.title;
+    resolvedEpisodes = resolution.episodes;
  }

  const entryResponse = await anilistGraphQl<AnilistMediaEntryData>(
@@ -375,6 +333,12 @@ export async function updateAnilistPostWatchProgress(
      query ($mediaId: Int!) {
        Media(id: $mediaId, type: ANIME) {
          id
+          episodes
+          title {
+            romaji
+            english
+            native
+          }
          mediaListEntry {
            progress
            status
@@ -382,7 +346,7 @@ export async function updateAnilistPostWatchProgress(
        }
      }
    `,
-    { mediaId: picked.id },
+    { mediaId },
    options,
  );
  const entryError = firstErrorMessage(entryResponse);
@@ -393,21 +357,34 @@ export async function updateAnilistPostWatchProgress(
    };
  }

-  const entry = entryResponse.data?.Media?.mediaListEntry ?? null;
+  const entryMedia = entryResponse.data?.Media ?? null;
+  const pickedTitle =
+    resolvedTitle ||
+    entryMedia?.title?.english?.trim() ||
+    entryMedia?.title?.romaji?.trim() ||
+    entryMedia?.title?.native?.trim() ||
+    title;
+  const pickedEpisodes =
+    resolvedEpisodes ??
+    (typeof entryMedia?.episodes === 'number' && entryMedia.episodes > 0
+      ? entryMedia.episodes
+      : null);
+
+  const entry = entryMedia?.mediaListEntry ?? null;
  if (!entry || !isUpdateableListStatus(entry.status)) {
    return {
      status: 'error',
      retryable: false,
-      message: `AniList update not possible: "${picked.title}" is ${formatListStatus(entry?.status)}. Add it to Planning or Watching, then mark watched again.`,
+      message: `AniList update not possible: "${pickedTitle}" is ${formatListStatus(entry?.status)}. Add it to Planning or Watching, then mark watched again.`,
    };
  }

  const currentProgress = entry.progress ?? 0;
-  const shouldMarkCompleted = isKnownFinalEpisode(picked.episodes, episode);
+  const shouldMarkCompleted = isKnownFinalEpisode(pickedEpisodes, episode);
  if (typeof currentProgress === 'number' && currentProgress >= episode && !shouldMarkCompleted) {
    return {
      status: 'skipped',
-      message: `AniList already at episode ${currentProgress} (${picked.title}).`,
+      message: `AniList already at episode ${currentProgress} (${pickedTitle}).`,
    };
  }

@@ -422,7 +399,7 @@ export async function updateAnilistPostWatchProgress(
      }
    `,
    {
-      mediaId: picked.id,
+      mediaId,
      progress: episode,
      status: shouldMarkCompleted ? 'COMPLETED' : 'CURRENT',
    },
@@ -436,7 +413,7 @@ export async function updateAnilistPostWatchProgress(
  return {
    status: 'updated',
    message: shouldMarkCompleted
-      ? `AniList updated "${picked.title}" to episode ${episode} and marked it completed.`
-      : `AniList updated "${picked.title}" to episode ${episode}.`,
+      ? `AniList updated "${pickedTitle}" to episode ${episode} and marked it completed.`
+      : `AniList updated "${pickedTitle}" to episode ${episode}.`,
  };
 }
@@ -201,17 +201,45 @@ test('fetchIfMissing uses guessit primary title and season when available', asyn
  });

  const searchCalls: Array<{ search: string }> = [];
+  const relationCalls: number[] = [];
  const originalFetch = globalThis.fetch;
  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
    const raw = (init?.body as string | undefined) ?? '';
-    const payload = JSON.parse(raw) as { variables: { search: string } };
-    const search = payload.variables.search;
-    searchCalls.push({ search });
+    const payload = JSON.parse(raw) as { variables: { search?: string; id?: number } };

-    if (search.includes('Season 2')) {
-      return Promise.resolve(createJsonResponse({ data: { Page: { media: [] } } }));
+    if (typeof payload.variables.id === 'number') {
+      relationCalls.push(payload.variables.id);
+      return Promise.resolve(
+        createJsonResponse({
+          data: {
+            Media: {
+              relations: {
+                edges: [
+                  {
+                    relationType: 'SEQUEL',
+                    node: {
+                      id: 20,
+                      type: 'ANIME',
+                      episodes: 25,
+                      format: 'TV',
+                      seasonYear: 2017,
+                      coverImage: { large: 'https://images.test/cover-s2.jpg', medium: null },
+                      title: {
+                        romaji: 'Little Witch Academia 2',
+                        english: 'Little Witch Academia 2',
+                        native: null,
+                      },
+                    },
+                  },
+                ],
+              },
+            },
+          },
+        }),
+      );
    }

+    searchCalls.push({ search: String(payload.variables.search) });
    return Promise.resolve(
      createJsonResponse({
        data: {
@@ -220,6 +248,8 @@ test('fetchIfMissing uses guessit primary title and season when available', asyn
              {
                id: 19,
                episodes: 24,
+                format: 'TV',
+                seasonYear: 2013,
                coverImage: { large: 'https://images.test/cover.jpg', medium: null },
                title: {
                  romaji: 'Little Witch Academia',
@@ -251,9 +281,11 @@ test('fetchIfMissing uses guessit primary title and season when available', asyn
    const stored = getCoverArt(db, videoId);

    assert.equal(fetched, true);
-    assert.equal(searchCalls.length, 2);
-    assert.equal(searchCalls[0]!.search, 'Little Witch Academia Season 2');
-    assert.equal(stored?.anilistId, 19);
+    // One search on the bare title, then a sequel hop to reach season 2.
+    assert.equal(searchCalls.length, 1);
+    assert.equal(searchCalls[0]!.search, 'Little Witch Academia');
+    assert.deepEqual(relationCalls, [19]);
+    assert.equal(stored?.anilistId, 20);
  } finally {
    globalThis.fetch = originalFetch;
    db.close();
@@ -324,3 +356,187 @@ test('fetchIfMissing falls back to internal parser when guessit throws', async (
    cleanupDbPath(dbPath);
  }
 });
+
+test('fetchIfMissing caches a no-match when the season cannot be resolved', async () => {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  ensureSchema(db);
+  const videoId = getOrCreateVideoRecord(db, 'local:/tmp/cover-fetcher-unresolved.mkv', {
+    canonicalTitle: 'Unresolved Show (2013) - S03E01 - Something [1080p].mkv',
+    sourcePath: '/tmp/cover-fetcher-unresolved.mkv',
+    sourceType: SOURCE_TYPE_LOCAL,
+    sourceUrl: null,
+  });
+
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    if (!url.includes('graphql')) {
+      return Promise.resolve(
+        new Response(Buffer.from('01020304'), {
+          status: 200,
+          headers: { 'content-type': 'image/png' },
+        }),
+      );
+    }
+
+    const payload = JSON.parse(String(init?.body ?? '{}')) as {
+      variables?: { search?: string; id?: number };
+    };
+    if (typeof payload.variables?.id === 'number') {
+      // No sequel edges, so season 3 cannot be reached from the season 1 anchor.
+      return Promise.resolve(createJsonResponse({ data: { Media: { relations: { edges: [] } } } }));
+    }
+    return Promise.resolve(
+      createJsonResponse({
+        data: {
+          Page: {
+            media: [
+              {
+                id: 55,
+                episodes: 13,
+                format: 'TV',
+                seasonYear: 2013,
+                coverImage: { large: 'https://images.test/s1.jpg', medium: null },
+                title: { romaji: 'Unresolved Show', english: 'Unresolved Show', native: null },
+              },
+            ],
+          },
+        },
+      }),
+    );
+  }) as typeof fetch;
+
+  try {
+    const fetcher = createCoverArtFetcher(
+      { acquire: async () => {}, recordResponse: () => {} },
+      console,
+      {
+        runGuessit: async () =>
+          JSON.stringify({ title: 'Unresolved Show', season: 3, episode: 1, year: 2013 }),
+      },
+    );
+
+    const fetched = await fetcher.fetchIfMissing(db, videoId, 'Unresolved Show');
+    const stored = getCoverArt(db, videoId);
+
+    assert.equal(fetched, false);
+    // Storing the season 1 artwork would leave a blob with no AniList id, which the
+    // `existing.coverBlob` early return serves forever - the season could then never
+    // re-resolve. A plain no-match keeps the existing retry window in play instead.
+    assert.equal(stored?.coverBlob, null);
+    assert.equal(stored?.coverUrl, null);
+    assert.equal(stored?.anilistId, null);
+    assert.equal(stored?.episodesTotal, null);
+  } finally {
+    globalThis.fetch = originalFetch;
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('fetchIfMissing re-resolves an unresolved season once AniList publishes the relation', async () => {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  ensureSchema(db);
+  const videoId = getOrCreateVideoRecord(db, 'local:/tmp/cover-fetcher-recovers.mkv', {
+    canonicalTitle: 'Recovering Show (2013) - S02E01 - Something [1080p].mkv',
+    sourcePath: '/tmp/cover-fetcher-recovers.mkv',
+    sourceType: SOURCE_TYPE_LOCAL,
+    sourceUrl: null,
+  });
+
+  let sequelPublished = false;
+  const originalFetch = globalThis.fetch;
+  const originalNow = Date.now;
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    if (!url.includes('graphql')) {
+      return Promise.resolve(
+        new Response(Buffer.from('01020304'), {
+          status: 200,
+          headers: { 'content-type': 'image/png' },
+        }),
+      );
+    }
+
+    const payload = JSON.parse(String(init?.body ?? '{}')) as {
+      variables?: { search?: string; id?: number };
+    };
+    if (typeof payload.variables?.id === 'number') {
+      return Promise.resolve(
+        createJsonResponse({
+          data: {
+            Media: {
+              relations: {
+                edges: sequelPublished
+                  ? [
+                      {
+                        relationType: 'SEQUEL',
+                        node: {
+                          id: 66,
+                          type: 'ANIME',
+                          episodes: 12,
+                          format: 'TV',
+                          seasonYear: 2015,
+                          coverImage: { large: 'https://images.test/s2.jpg', medium: null },
+                          title: { romaji: 'Recovering Show 2', english: null, native: null },
+                        },
+                      },
+                    ]
+                  : [],
+              },
+            },
+          },
+        }),
+      );
+    }
+    return Promise.resolve(
+      createJsonResponse({
+        data: {
+          Page: {
+            media: [
+              {
+                id: 65,
+                episodes: 13,
+                format: 'TV',
+                seasonYear: 2013,
+                coverImage: { large: 'https://images.test/s1.jpg', medium: null },
+                title: { romaji: 'Recovering Show', english: null, native: null },
+              },
+            ],
+          },
+        },
+      }),
+    );
+  }) as typeof fetch;
+
+  try {
+    const fetcher = createCoverArtFetcher(
+      { acquire: async () => {}, recordResponse: () => {} },
+      console,
+      {
+        runGuessit: async () =>
+          JSON.stringify({ title: 'Recovering Show', season: 2, episode: 1, year: 2013 }),
+      },
+    );
+
+    assert.equal(await fetcher.fetchIfMissing(db, videoId, 'Recovering Show'), false);
+    assert.equal(getCoverArt(db, videoId)?.anilistId, null);
+
+    // AniList publishes the sequel relation, and the no-match retry window elapses.
+    sequelPublished = true;
+    const base = originalNow();
+    Date.now = () => base + 10 * 60 * 1000;
+
+    assert.equal(await fetcher.fetchIfMissing(db, videoId, 'Recovering Show'), true);
+    const recovered = getCoverArt(db, videoId);
+    assert.equal(recovered?.anilistId, 66);
+    assert.equal(recovered?.episodesTotal, 12);
+  } finally {
+    Date.now = originalNow;
+    globalThis.fetch = originalFetch;
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
@@ -11,43 +11,15 @@ import {
  runGuessit,
  type GuessAnilistMediaInfoDeps,
 } from './anilist-updater';
+import {
+  resolveAnilistSeasonMedia,
+  type AnilistQueryExecutor,
+  type AnilistSeasonResolution,
+} from './season-resolver';

 const ANILIST_GRAPHQL_URL = 'https://graphql.anilist.co';
 const NO_MATCH_RETRY_MS = 5 * 60 * 1000;

-const SEARCH_QUERY = `
-query ($search: String!) {
-  Page(perPage: 5) {
-    media(search: $search, type: ANIME) {
-      id
-      episodes
-      season
-      seasonYear
-      coverImage { large medium }
-      title { romaji english native }
-    }
-  }
-}
-`;
-
-interface AnilistMedia {
-  id: number;
-  episodes: number | null;
-  season: string | null;
-  seasonYear: number | null;
-  coverImage: { large: string | null; medium: string | null } | null;
-  title: { romaji: string | null; english: string | null; native: string | null } | null;
-}
-
-interface AnilistSearchResponse {
-  data?: {
-    Page?: {
-      media?: AnilistMedia[];
-    };
-  };
-  errors?: Array<{ message?: string }>;
-}
-
 export interface CoverArtFetcher {
  fetchIfMissing(db: DatabaseSync, videoId: number, canonicalTitle: string): Promise<boolean>;
 }
@@ -99,151 +71,45 @@ export function stripFilenameTags(raw: string): string {
  return title.trim().replace(/\s{2,}/g, ' ');
 }

-function removeSeasonHint(title: string): string {
-  return title
-    .replace(/\bseason\s*\d+\b/gi, '')
-    .replace(/\s{2,}/g, ' ')
-    .trim();
-}
-
-function normalizeTitle(text: string): string {
-  return text.trim().toLowerCase().replace(/\s+/g, ' ');
-}
-
-function extractCandidateSeasonHints(text: string): Set<number> {
-  const normalized = normalizeTitle(text);
-  const matches = [
-    ...normalized.matchAll(/\bseason\s*(\d{1,2})\b/gi),
-    ...normalized.matchAll(/\bs(\d{1,2})(?:\b|\D)/gi),
-  ];
-  const values = new Set<number>();
-  for (const match of matches) {
-    const value = Number.parseInt(match[1]!, 10);
-    if (Number.isInteger(value)) {
-      values.add(value);
-    }
-  }
-  return values;
-}
-
-function isSeasonMentioned(titles: string[], season: number | null): boolean {
-  if (!season) {
-    return false;
-  }
-  const hints = titles.flatMap((title) => [...extractCandidateSeasonHints(title)]);
-  return hints.includes(season);
-}
-
-function pickBestSearchResult(
-  title: string,
-  episode: number | null,
-  season: number | null,
-  media: AnilistMedia[],
-): { id: number; title: string } | null {
-  const cleanedTitle = removeSeasonHint(title);
-  const targets = [title, cleanedTitle]
-    .map(normalizeTitle)
-    .map((value) => value.trim())
-    .filter((value, index, all) => value.length > 0 && all.indexOf(value) === index);
-
-  const filtered =
-    episode === null
-      ? media
-      : media.filter((item) => {
-          const total = item.episodes;
-          return total === null || total >= episode;
-        });
-  const candidates = filtered.length > 0 ? filtered : media;
-  if (candidates.length === 0) {
-    return null;
-  }
-
-  const scored = candidates.map((item) => {
-    const candidateTitles = [item.title?.romaji, item.title?.english, item.title?.native]
-      .filter((value): value is string => typeof value === 'string')
-      .map((value) => normalizeTitle(value));
-
-    let score = 0;
-
-    for (const target of targets) {
-      if (candidateTitles.includes(target)) {
-        score += 120;
-        continue;
-      }
-      if (candidateTitles.some((itemTitle) => itemTitle.includes(target))) {
-        score += 30;
-      }
-      if (candidateTitles.some((itemTitle) => target.includes(itemTitle))) {
-        score += 10;
+class AnilistRateLimitedError extends Error {
+  constructor() {
+    super('Anilist rate limit reached');
+    this.name = 'AnilistRateLimitedError';
  }
 }

-    if (episode !== null && item.episodes === episode) {
-      score += 20;
-    }
-
-    if (season !== null && isSeasonMentioned(candidateTitles, season)) {
-      score += 15;
-    }
-
-    return { item, score };
-  });
-
-  scored.sort((a, b) => {
-    if (b.score !== a.score) return b.score - a.score;
-    return b.item.id - a.item.id;
-  });
-
-  const selected = scored[0]!;
-  const selectedTitle =
-    selected.item.title?.english ??
-    selected.item.title?.romaji ??
-    selected.item.title?.native ??
-    title;
-  return { id: selected.item.id, title: selectedTitle };
-}
-
-function buildSearchCandidates(parsed: CoverArtCandidate): string[] {
-  const candidateTitles = [
-    ...(parsed.source === 'guessit' && parsed.season !== null && parsed.season > 1
-      ? [`${parsed.title} Season ${parsed.season}`]
-      : []),
-    parsed.title,
-  ];
-  return candidateTitles
-    .map((title) => title.trim())
-    .filter((title, index, all) => title.length > 0 && all.indexOf(title) === index);
-}
-
-async function searchAnilist(
+async function executeAnilistQuery<T>(
  rateLimiter: AnilistRateLimiter,
-  title: string,
-): Promise<{ media: AnilistMedia[]; rateLimited: boolean }> {
+  query: string,
+  variables: Record<string, unknown>,
+): Promise<T> {
  await rateLimiter.acquire();

  const res = await fetch(ANILIST_GRAPHQL_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-    body: JSON.stringify({ query: SEARCH_QUERY, variables: { search: title } }),
+    body: JSON.stringify({ query, variables }),
  });

  rateLimiter.recordResponse(res.headers);

  if (res.status === 429) {
-    return { media: [], rateLimited: true };
+    throw new AnilistRateLimitedError();
  }

  if (!res.ok) {
    throw new Error(`Anilist search failed: ${res.status} ${res.statusText}`);
  }

-  const json = (await res.json()) as AnilistSearchResponse;
-  const mediaList = json.data?.Page?.media;
-  if (!mediaList || mediaList.length === 0) {
-    return { media: [], rateLimited: false };
+  const json = (await res.json()) as { data?: T; errors?: Array<{ message?: string }> };
+  const firstError = json.errors?.find((entry) => Boolean(entry?.message));
+  if (firstError?.message) {
+    throw new Error(firstError.message);
  }
-
-  return { media: mediaList, rateLimited: false };
+  if (!json.data) {
+    throw new Error('Anilist response missing data');
+  }
+  return json.data;
 }

 async function downloadImage(url: string): Promise<Buffer | null> {
@@ -376,49 +242,57 @@ export function createCoverArtFetcher(

      const parsedInfo = await resolveMediaInfo(db, videoId, canonicalTitle);
      const searchBase = parsedInfo?.title ?? cleaned;
-      const searchCandidates = parsedInfo ? buildSearchCandidates(parsedInfo) : [cleaned];
+      const searchTitles = searchBase === cleaned ? [searchBase] : ([searchBase, cleaned] as const);

-      const effectiveCandidates = searchCandidates.includes(cleaned)
-        ? searchCandidates
-        : [...searchCandidates, cleaned];
-
-      let selected: AnilistMedia | null = null;
-      let rateLimited = false;
-
-      for (const candidate of effectiveCandidates) {
-        logger.info('cover-art: searching Anilist for "%s" (videoId=%d)', candidate, videoId);
+      const execute: AnilistQueryExecutor = (query, variables) =>
+        executeAnilistQuery(rateLimiter, query, variables);

+      let resolution: AnilistSeasonResolution | null = null;
      try {
-          const result = await searchAnilist(rateLimiter, candidate);
-          rateLimited = result.rateLimited;
-          if (result.media.length === 0) {
-            continue;
-          }
-
-          const picked = pickBestSearchResult(
-            searchBase,
-            parsedInfo?.episode ?? null,
-            parsedInfo?.season ?? null,
-            result.media,
+        for (const searchTitle of searchTitles) {
+          logger.info('cover-art: searching Anilist for "%s" (videoId=%d)', searchTitle, videoId);
+          resolution = await resolveAnilistSeasonMedia(
+            {
+              title: searchTitle,
+              season: parsedInfo?.season ?? null,
+              episode: parsedInfo?.episode ?? null,
+            },
+            { execute, logInfo: (message) => logger.info('%s', message) },
          );
-          if (picked) {
-            const match = result.media.find((media) => media.id === picked.id);
-            if (match) {
-              selected = match;
-              break;
-            }
+          if (resolution) break;
        }
      } catch (err) {
-          logger.error('cover-art: Anilist search error for "%s": %s', candidate, err);
-          return false;
-        }
-      }
-
-      if (rateLimited) {
+        if (err instanceof AnilistRateLimitedError) {
          logger.warn('cover-art: rate-limited by Anilist, skipping videoId=%d', videoId);
          return false;
        }
+        logger.error('cover-art: Anilist search error for "%s": %s', searchBase, err);
+        return false;
+      }

+      if (resolution && !resolution.seasonResolved) {
+        // Only the season 1 entry was found. Storing its artwork would leave a cover with
+        // no AniList id, which the `existing.coverBlob` early return above serves forever,
+        // so the season could never re-resolve once AniList publishes the relation.
+        // Caching a plain no-match instead reuses the NO_MATCH_RETRY_MS retry window.
+        logger.warn(
+          'cover-art: could not find season %d of "%s" (only matched "%s"), caching no-match',
+          resolution.requestedSeason,
+          searchBase,
+          resolution.title,
+        );
+        upsertCoverArt(db, videoId, {
+          anilistId: null,
+          coverUrl: null,
+          coverBlob: null,
+          titleRomaji: null,
+          titleEnglish: null,
+          episodesTotal: null,
+        });
+        return false;
+      }
+
+      const selected = resolution?.media ?? null;
      if (!selected) {
        logger.info('cover-art: no Anilist results for "%s", caching no-match', searchBase);
        upsertCoverArt(db, videoId, {
@@ -453,6 +327,7 @@ export function createCoverArtFetcher(
        titleEnglish: selected.title?.english ?? null,
        titleNative: selected.title?.native ?? null,
        episodesTotal: selected.episodes ?? null,
+        exactTitleMatch: resolution?.exactTitleMatch ?? false,
      });

      logger.info(
@@ -0,0 +1,350 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  ANILIST_SEASON_RELATIONS_QUERY,
+  ANILIST_SEASON_SEARCH_QUERY,
+  pickByAirOrder,
+  resolveAnilistSeasonMedia,
+  stripSeasonSuffix,
+  type AnilistSeasonMedia,
+} from './season-resolver';
+
+/** Real AniList payloads for "My Teen Romantic Comedy SNAFU", trimmed to used fields. */
+const OREGAIRU_SEARCH: AnilistSeasonMedia[] = [
+  {
+    id: 14813,
+    episodes: 13,
+    format: 'TV',
+    seasonYear: 2013,
+    title: {
+      romaji: 'Yahari Ore no Seishun Love Come wa Machigatteiru.',
+      english: 'My Teen Romantic Comedy SNAFU',
+      native: null,
+    },
+  },
+  {
+    id: 18753,
+    episodes: 1,
+    format: 'OVA',
+    seasonYear: 2013,
+    title: { romaji: null, english: 'My Teen Romantic Comedy SNAFU OVA', native: null },
+  },
+  {
+    id: 108489,
+    episodes: 12,
+    format: 'TV',
+    seasonYear: 2020,
+    title: {
+      romaji: 'Yahari Ore no Seishun Love Come wa Machigatteiru. Kan',
+      english: 'My Teen Romantic Comedy SNAFU Climax!',
+      native: null,
+    },
+  },
+  {
+    id: 20698,
+    episodes: 13,
+    format: 'TV',
+    seasonYear: 2015,
+    title: {
+      romaji: 'Yahari Ore no Seishun Love Come wa Machigatteiru. Zoku',
+      english: 'My Teen Romantic Comedy SNAFU TOO!',
+      native: null,
+    },
+  },
+];
+
+const OREGAIRU_RELATIONS: Record<
+  number,
+  Array<{ relationType: string; node: AnilistSeasonMedia }>
+> = {
+  14813: [
+    {
+      relationType: 'SIDE_STORY',
+      node: OREGAIRU_SEARCH[1]!,
+    },
+    {
+      relationType: 'SEQUEL',
+      node: OREGAIRU_SEARCH[3]!,
+    },
+  ],
+  20698: [
+    {
+      relationType: 'PREQUEL',
+      node: OREGAIRU_SEARCH[0]!,
+    },
+    {
+      relationType: 'SEQUEL',
+      node: OREGAIRU_SEARCH[2]!,
+    },
+  ],
+  108489: [
+    {
+      relationType: 'PREQUEL',
+      node: OREGAIRU_SEARCH[3]!,
+    },
+  ],
+};
+
+function createExecutor(
+  search: AnilistSeasonMedia[],
+  relations: Record<number, Array<{ relationType: string; node: AnilistSeasonMedia }>> = {},
+) {
+  const searches: string[] = [];
+  const relationLookups: number[] = [];
+  const execute = async <T>(query: string, variables: Record<string, unknown>): Promise<T> => {
+    if (query === ANILIST_SEASON_SEARCH_QUERY) {
+      searches.push(String(variables.search));
+      return { Page: { media: search } } as T;
+    }
+    if (query === ANILIST_SEASON_RELATIONS_QUERY) {
+      const id = Number(variables.id);
+      relationLookups.push(id);
+      return {
+        Media: {
+          relations: {
+            edges: (relations[id] ?? []).map((edge) => ({
+              relationType: edge.relationType,
+              node: { ...edge.node, type: 'ANIME' },
+            })),
+          },
+        },
+      } as T;
+    }
+    throw new Error(`unexpected query: ${query}`);
+  };
+  return { execute, searches, relationLookups };
+}
+
+test('stripSeasonSuffix drops release-name season markers', () => {
+  assert.equal(stripSeasonSuffix('Some Show Season 3'), 'Some Show');
+  assert.equal(stripSeasonSuffix('Some Show S3'), 'Some Show');
+  assert.equal(stripSeasonSuffix('Some Show 2nd Season'), 'Some Show');
+  assert.equal(stripSeasonSuffix('Some Show'), 'Some Show');
+});
+
+test('resolves season 3 by walking sequel relations', async () => {
+  const { execute, searches, relationLookups } = createExecutor(
+    OREGAIRU_SEARCH,
+    OREGAIRU_RELATIONS,
+  );
+  const result = await resolveAnilistSeasonMedia(
+    { title: 'My Teen Romantic Comedy SNAFU', season: 3, episode: 1 },
+    { execute },
+  );
+
+  assert.equal(result?.id, 108489);
+  assert.equal(result?.title, 'My Teen Romantic Comedy SNAFU Climax!');
+  assert.equal(result?.episodes, 12);
+  assert.equal(result?.seasonResolved, true);
+  assert.equal(result?.via, 'sequel-chain');
+  // Searches the bare title only; "Season 3" returns nothing on AniList.
+  assert.deepEqual(searches, ['My Teen Romantic Comedy SNAFU']);
+  assert.deepEqual(relationLookups, [14813, 20698]);
+});
+
+test('season 1 resolves to the anchor without relation lookups', async () => {
+  const { execute, relationLookups } = createExecutor(OREGAIRU_SEARCH, OREGAIRU_RELATIONS);
+  const result = await resolveAnilistSeasonMedia(
+    { title: 'My Teen Romantic Comedy SNAFU', season: 1, episode: 5 },
+    { execute },
+  );
+
+  assert.equal(result?.id, 14813);
+  assert.equal(result?.seasonResolved, true);
+  assert.equal(result?.via, 'anchor');
+  assert.deepEqual(relationLookups, []);
+});
+
+test('season 2 preserves the anchor exact-title evidence through a sequel resolution', async () => {
+  const { execute } = createExecutor(OREGAIRU_SEARCH, OREGAIRU_RELATIONS);
+  const result = await resolveAnilistSeasonMedia(
+    { title: 'My Teen Romantic Comedy SNAFU', season: 2, episode: 1 },
+    { execute },
+  );
+
+  assert.equal(result?.id, 20698);
+  assert.equal(result?.via, 'sequel-chain');
+  assert.equal(result?.exactTitleMatch, true);
+});
+
+test('reports an exact normalized synonym match as strong evidence', async () => {
+  const { execute } = createExecutor([
+    {
+      id: 1,
+      episodes: 12,
+      format: 'TV',
+      title: { english: 'Hitori Gotoh Story' },
+      synonyms: ['BOCCHI THE ROCK'],
+    },
+  ]);
+
+  const result = await resolveAnilistSeasonMedia({ title: 'Bocchi the Rock!' }, { execute });
+
+  assert.equal(result?.exactTitleMatch, true);
+});
+
+test('reports a fuzzy-only search result as weak evidence', async () => {
+  const { execute } = createExecutor([
+    {
+      id: 1,
+      episodes: 12,
+      format: 'TV',
+      title: { english: 'Actual Show' },
+    },
+  ]);
+
+  const result = await resolveAnilistSeasonMedia({ title: 'Unrelated Release' }, { execute });
+
+  assert.equal(result?.exactTitleMatch, false);
+});
+
+test('strips a season marker already present in the parsed title', async () => {
+  const { execute, searches } = createExecutor(OREGAIRU_SEARCH, OREGAIRU_RELATIONS);
+  const result = await resolveAnilistSeasonMedia(
+    { title: 'My Teen Romantic Comedy SNAFU Season 2', season: 2, episode: 3 },
+    { execute },
+  );
+
+  assert.deepEqual(searches, ['My Teen Romantic Comedy SNAFU']);
+  assert.equal(result?.id, 20698);
+  assert.equal(result?.seasonResolved, true);
+});
+
+test('falls back to air order when the sequel chain is broken', async () => {
+  const { execute } = createExecutor(OREGAIRU_SEARCH, {});
+  const result = await resolveAnilistSeasonMedia(
+    { title: 'My Teen Romantic Comedy SNAFU', season: 3, episode: 1 },
+    { execute },
+  );
+
+  assert.equal(result?.id, 108489);
+  assert.equal(result?.via, 'air-order');
+  assert.equal(result?.seasonResolved, true);
+});
+
+test('reports seasonResolved false rather than silently using season 1', async () => {
+  const { execute } = createExecutor([OREGAIRU_SEARCH[0]!], {});
+  const result = await resolveAnilistSeasonMedia(
+    { title: 'My Teen Romantic Comedy SNAFU', season: 3, episode: 1 },
+    { execute },
+  );
+
+  assert.equal(result?.id, 14813);
+  assert.equal(result?.seasonResolved, false);
+  assert.equal(result?.via, 'anchor');
+  assert.equal(result?.requestedSeason, 3);
+});
+
+test('does not filter the anchor by an episode count the season 1 entry cannot have', async () => {
+  const { execute } = createExecutor(OREGAIRU_SEARCH, OREGAIRU_RELATIONS);
+  // Season 2 episode 13 exceeds nothing, but season 3 episode 13 exceeds Climax!'s 12.
+  const result = await resolveAnilistSeasonMedia(
+    { title: 'My Teen Romantic Comedy SNAFU', season: 2, episode: 13 },
+    { execute },
+  );
+
+  assert.equal(result?.id, 20698);
+  assert.equal(result?.seasonResolved, true);
+});
+
+test('prefers the TV sequel when a franchise branches into other formats', async () => {
+  const branching: Record<number, Array<{ relationType: string; node: AnilistSeasonMedia }>> = {
+    1: [
+      {
+        relationType: 'SEQUEL',
+        node: {
+          id: 3,
+          episodes: 6,
+          format: 'ONA',
+          seasonYear: 2019,
+          title: { english: 'Spinoff' },
+        },
+      },
+      {
+        relationType: 'SEQUEL',
+        node: { id: 2, episodes: 12, format: 'TV', seasonYear: 2020, title: { english: 'Show 2' } },
+      },
+    ],
+  };
+  const { execute } = createExecutor(
+    [{ id: 1, episodes: 12, format: 'TV', seasonYear: 2018, title: { english: 'Show' } }],
+    branching,
+  );
+  const result = await resolveAnilistSeasonMedia({ title: 'Show', season: 2 }, { execute });
+
+  assert.equal(result?.id, 2);
+  assert.equal(result?.via, 'sequel-chain');
+});
+
+test('air-order fallback refuses when the anchor is not the earliest entry', () => {
+  const anchor: AnilistSeasonMedia = {
+    id: 2,
+    format: 'TV',
+    seasonYear: 2020,
+    title: { english: 'Show Later' },
+  };
+  const picked = pickByAirOrder(anchor, 2, [
+    anchor,
+    { id: 1, format: 'TV', seasonYear: 2015, title: { english: 'Show Earlier' } },
+  ]);
+
+  assert.equal(picked, null);
+});
+
+test('returns null when the search yields nothing', async () => {
+  const { execute } = createExecutor([]);
+  const result = await resolveAnilistSeasonMedia({ title: 'Nothing', season: 2 }, { execute });
+
+  assert.equal(result, null);
+});
+
+test('refuses a season beyond the sequel-hop cap instead of returning a partial walk', async () => {
+  // A 30-entry sequel chain: hopping the capped number of times would land on the wrong
+  // season and report it resolved, so the walk must decline outright.
+  const chain: Record<number, Array<{ relationType: string; node: AnilistSeasonMedia }>> = {};
+  for (let id = 1; id < 30; id += 1) {
+    chain[id] = [
+      {
+        relationType: 'SEQUEL',
+        node: {
+          id: id + 1,
+          episodes: 12,
+          format: 'TV',
+          seasonYear: 2000 + id,
+          title: { english: `Show ${id + 1}` },
+        },
+      },
+    ];
+  }
+  const { execute, relationLookups } = createExecutor(
+    [{ id: 1, episodes: 12, format: 'TV', seasonYear: 2000, title: { english: 'Show' } }],
+    chain,
+  );
+
+  const result = await resolveAnilistSeasonMedia({ title: 'Show', season: 25 }, { execute });
+
+  assert.equal(result?.id, 1);
+  assert.equal(result?.seasonResolved, false);
+  assert.equal(result?.via, 'anchor');
+  // Declines before spending any relation requests.
+  assert.deepEqual(relationLookups, []);
+});
+
+test('air-order fallback declines when a franchise entry has no air year', async () => {
+  // The middle season has no year, so ordering it would shift every later season by one.
+  const { execute } = createExecutor(
+    [
+      { id: 1, episodes: 12, format: 'TV', seasonYear: 2013, title: { english: 'Show' } },
+      { id: 2, episodes: 12, format: 'TV', title: { english: 'Show Zoku' } },
+      { id: 3, episodes: 12, format: 'TV', seasonYear: 2020, title: { english: 'Show Kan' } },
+    ],
+    {},
+  );
+
+  const result = await resolveAnilistSeasonMedia({ title: 'Show', season: 2 }, { execute });
+
+  assert.equal(result?.id, 1);
+  assert.equal(result?.seasonResolved, false);
+  assert.equal(result?.via, 'anchor');
+});
@@ -0,0 +1,411 @@
+/**
+ * AniList has no concept of "season N": sequels are separate media with their own
+ * titles (Zoku, Kan, 2nd Season, ...). Searching "<title> Season 3" therefore returns
+ * nothing and callers silently fall back to the season 1 entry.
+ *
+ * This module resolves a parsed (title, season) pair to the right media by locating a
+ * season 1 anchor and then walking AniList SEQUEL relations, with an air-order fallback
+ * when the relation chain is incomplete. When the seasonal entry cannot be located it
+ * reports `seasonResolved: false` so callers can refuse to act instead of guessing.
+ */
+
+import { normalizeTitleIdentity } from '../../utils/title-normalization';
+
+export interface AnilistSeasonMediaTitle {
+  romaji?: string | null;
+  english?: string | null;
+  native?: string | null;
+}
+
+export interface AnilistSeasonMedia {
+  id: number;
+  episodes?: number | null;
+  format?: string | null;
+  seasonYear?: number | null;
+  startDate?: { year?: number | null } | null;
+  synonyms?: Array<string | null> | null;
+  coverImage?: { large?: string | null; medium?: string | null } | null;
+  title?: AnilistSeasonMediaTitle | null;
+}
+
+export type AnilistQueryExecutor = <T>(
+  query: string,
+  variables: Record<string, unknown>,
+) => Promise<T>;
+
+export type AnilistSeasonResolutionVia = 'anchor' | 'sequel-chain' | 'air-order';
+
+export interface AnilistSeasonResolution {
+  id: number;
+  title: string;
+  episodes: number | null;
+  media: AnilistSeasonMedia;
+  /** False when a season >= 2 was requested but no seasonal entry could be located. */
+  seasonResolved: boolean;
+  requestedSeason: number | null;
+  via: AnilistSeasonResolutionVia;
+  /** Exact normalized match against an AniList title or synonym. */
+  exactTitleMatch: boolean;
+}
+
+export interface ResolveAnilistSeasonMediaInput {
+  title: string;
+  season?: number | null;
+  episode?: number | null;
+}
+
+export interface ResolveAnilistSeasonMediaDeps {
+  execute: AnilistQueryExecutor;
+  logInfo?: (message: string) => void;
+}
+
+const MEDIA_FIELDS = `
+  id
+  episodes
+  format
+  seasonYear
+  startDate { year }
+  synonyms
+  coverImage { large medium }
+  title { romaji english native }
+`;
+
+export const ANILIST_SEASON_SEARCH_QUERY = `
+query ($search: String!) {
+  Page(perPage: 10) {
+    media(search: $search, type: ANIME, sort: [SEARCH_MATCH, POPULARITY_DESC]) {
+      ${MEDIA_FIELDS}
+    }
+  }
+}
+`;
+
+export const ANILIST_SEASON_RELATIONS_QUERY = `
+query ($id: Int!) {
+  Media(id: $id, type: ANIME) {
+    id
+    relations {
+      edges {
+        relationType
+        node {
+          type
+          ${MEDIA_FIELDS}
+        }
+      }
+    }
+  }
+}
+`;
+
+interface AnilistSeasonSearchResponse {
+  Page?: {
+    media?: AnilistSeasonMedia[] | null;
+  } | null;
+}
+
+interface AnilistSeasonRelationsResponse {
+  Media?: {
+    relations?: {
+      edges?: Array<{
+        relationType?: string | null;
+        node?: (AnilistSeasonMedia & { type?: string | null }) | null;
+      } | null> | null;
+    } | null;
+  } | null;
+}
+
+/** Formats that can carry a numbered TV season, best first. */
+const SEASONAL_FORMAT_PRIORITY = ['TV', 'TV_SHORT', 'ONA'];
+
+const MAX_SEQUEL_HOPS = 12;
+
+/**
+ * Drops season markers a release name carries but AniList titles never do,
+ * so "Some Show Season 3" and "Some Show S3" both search as "Some Show".
+ */
+export function stripSeasonSuffix(title: string): string {
+  return title
+    .replace(/\bseason\s*\d{1,2}\b/gi, ' ')
+    .replace(/\b\d{1,2}(?:st|nd|rd|th)\s+season\b/gi, ' ')
+    .replace(/\bs\d{1,2}\b/gi, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+function mediaTitles(media: AnilistSeasonMedia): string[] {
+  const synonyms = Array.isArray(media.synonyms) ? media.synonyms : [];
+  return [media.title?.english, media.title?.romaji, media.title?.native, ...synonyms]
+    .filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
+    .map((value) => normalizeTitleIdentity(value));
+}
+
+function displayTitle(media: AnilistSeasonMedia, fallback: string): string {
+  return (
+    media.title?.english?.trim() ||
+    media.title?.romaji?.trim() ||
+    media.title?.native?.trim() ||
+    fallback.trim()
+  );
+}
+
+function episodeCount(media: AnilistSeasonMedia): number | null {
+  return typeof media.episodes === 'number' && media.episodes > 0 ? media.episodes : null;
+}
+
+function airYear(media: AnilistSeasonMedia): number | null {
+  if (typeof media.seasonYear === 'number' && media.seasonYear > 0) {
+    return media.seasonYear;
+  }
+  const startYear = media.startDate?.year;
+  return typeof startYear === 'number' && startYear > 0 ? startYear : null;
+}
+
+function isSeasonalFormat(media: AnilistSeasonMedia): boolean {
+  const format = (media.format || '').toUpperCase();
+  return SEASONAL_FORMAT_PRIORITY.includes(format);
+}
+
+function formatRank(media: AnilistSeasonMedia): number {
+  const index = SEASONAL_FORMAT_PRIORITY.indexOf((media.format || '').toUpperCase());
+  return index < 0 ? SEASONAL_FORMAT_PRIORITY.length : index;
+}
+
+function toResolution(
+  media: AnilistSeasonMedia,
+  fallbackTitle: string,
+  season: number | null,
+  via: AnilistSeasonResolutionVia,
+  seasonResolved: boolean,
+  exactTitleMatch: boolean,
+): AnilistSeasonResolution {
+  return {
+    id: media.id,
+    title: displayTitle(media, fallbackTitle),
+    episodes: episodeCount(media),
+    media,
+    seasonResolved,
+    requestedSeason: season,
+    via,
+    exactTitleMatch,
+  };
+}
+
+/**
+ * Picks the franchise anchor (season 1 entry) for a search result set. The anchor is
+ * matched on title alone - season is handled by walking relations from here.
+ */
+export function pickAnchorMedia(
+  title: string,
+  media: AnilistSeasonMedia[],
+  options: { episode?: number | null } = {},
+): AnilistSeasonMedia | null {
+  if (media.length === 0) return null;
+
+  const episode = options.episode;
+  const episodeFiltered =
+    typeof episode === 'number' && episode > 0
+      ? media.filter((entry) => {
+          const total = episodeCount(entry);
+          return total === null || total >= episode;
+        })
+      : media;
+  const pool = episodeFiltered.length > 0 ? episodeFiltered : media;
+
+  const targets = [
+    normalizeTitleIdentity(title),
+    normalizeTitleIdentity(stripSeasonSuffix(title)),
+  ].filter((value, index, all) => value.length > 0 && all.indexOf(value) === index);
+
+  const scored = pool.map((entry, index) => {
+    const candidateTitles = mediaTitles(entry);
+    let score = 0;
+    for (const target of targets) {
+      if (candidateTitles.includes(target)) {
+        score += 120;
+        continue;
+      }
+      if (candidateTitles.some((candidate) => candidate.startsWith(target))) {
+        score += 40;
+      } else if (candidateTitles.some((candidate) => candidate.includes(target))) {
+        score += 25;
+      }
+      if (candidateTitles.some((candidate) => target.includes(candidate))) {
+        score += 10;
+      }
+    }
+    if (isSeasonalFormat(entry)) {
+      score += 30;
+    }
+    return { entry, score, index };
+  });
+
+  scored.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    if (a.index !== b.index) return a.index - b.index;
+    return a.entry.id - b.entry.id;
+  });
+
+  return scored[0]?.entry ?? null;
+}
+
+async function walkSequelChain(
+  anchor: AnilistSeasonMedia,
+  season: number,
+  deps: ResolveAnilistSeasonMediaDeps,
+): Promise<AnilistSeasonMedia | null> {
+  // Walking fewer hops than requested would land on the wrong season and report it as
+  // resolved, so refuse instead and let the caller fall through to its guarded fallback.
+  const hops = season - 1;
+  if (hops > MAX_SEQUEL_HOPS) {
+    return null;
+  }
+  const visited = new Set<number>([anchor.id]);
+  let current = anchor;
+
+  for (let hop = 0; hop < hops; hop += 1) {
+    // Transport errors propagate: a failed hop must not be mistaken for "no sequel exists".
+    const response = await deps.execute<AnilistSeasonRelationsResponse>(
+      ANILIST_SEASON_RELATIONS_QUERY,
+      { id: current.id },
+    );
+
+    const sequels = (response.Media?.relations?.edges ?? [])
+      .map((edge) => edge ?? null)
+      .filter(
+        (
+          edge,
+        ): edge is {
+          relationType?: string | null;
+          node: AnilistSeasonMedia & { type?: string | null };
+        } =>
+          Boolean(edge?.node) &&
+          (edge?.relationType || '').toUpperCase() === 'SEQUEL' &&
+          (edge?.node?.type || 'ANIME').toUpperCase() === 'ANIME',
+      )
+      .map((edge) => edge.node)
+      .filter((node) => !visited.has(node.id));
+
+    if (sequels.length === 0) {
+      return null;
+    }
+
+    // A franchise can branch (a TV sequel plus an ONA spinoff); prefer the TV line.
+    sequels.sort((a, b) => {
+      const rankDelta = formatRank(a) - formatRank(b);
+      if (rankDelta !== 0) return rankDelta;
+      const yearDelta =
+        (airYear(a) ?? Number.MAX_SAFE_INTEGER) - (airYear(b) ?? Number.MAX_SAFE_INTEGER);
+      if (yearDelta !== 0) return yearDelta;
+      return a.id - b.id;
+    });
+
+    current = sequels[0]!;
+    visited.add(current.id);
+  }
+
+  return current.id === anchor.id ? null : current;
+}
+
+/**
+ * Fallback for franchises whose SEQUEL edges are missing or route through a format we
+ * skipped: order the franchise's seasonal entries by air date and index by season.
+ */
+export function pickByAirOrder(
+  anchor: AnilistSeasonMedia,
+  season: number,
+  media: AnilistSeasonMedia[],
+): AnilistSeasonMedia | null {
+  const anchorTitles = mediaTitles(anchor).map((value) => stripSeasonSuffix(value));
+  const anchorBase = anchorTitles.sort((a, b) => a.length - b.length)[0];
+  if (!anchorBase) return null;
+
+  const franchise = media.filter((entry) => {
+    if (!isSeasonalFormat(entry)) return false;
+    if (entry.id === anchor.id) return true;
+    return mediaTitles(entry).some((candidate) =>
+      stripSeasonSuffix(candidate).includes(anchorBase),
+    );
+  });
+  if (franchise.length < season) return null;
+
+  // Ordering by air date is only meaningful when every entry has one: an unknown year
+  // would sort last and shift the season index while still reporting a resolved match.
+  if (franchise.some((entry) => airYear(entry) === null)) return null;
+
+  const ordered = [...franchise].sort((a, b) => {
+    const yearDelta = (airYear(a) ?? 0) - (airYear(b) ?? 0);
+    if (yearDelta !== 0) return yearDelta;
+    return a.id - b.id;
+  });
+
+  // The anchor has to be the first entry, otherwise this ordering is not a season list.
+  if (ordered[0]?.id !== anchor.id) return null;
+
+  return ordered[season - 1] ?? null;
+}
+
+export async function resolveAnilistSeasonMedia(
+  input: ResolveAnilistSeasonMediaInput,
+  deps: ResolveAnilistSeasonMediaDeps,
+): Promise<AnilistSeasonResolution | null> {
+  const searchTitle = stripSeasonSuffix(input.title).trim() || input.title.trim();
+  if (!searchTitle) return null;
+
+  const season =
+    typeof input.season === 'number' && Number.isInteger(input.season) && input.season > 0
+      ? input.season
+      : null;
+
+  const response = await deps.execute<AnilistSeasonSearchResponse>(ANILIST_SEASON_SEARCH_QUERY, {
+    search: searchTitle,
+  });
+  const media = (response.Page?.media ?? []).filter(
+    (entry): entry is AnilistSeasonMedia => Boolean(entry) && typeof entry.id === 'number',
+  );
+  if (media.length === 0) return null;
+
+  // Season 1 (or unknown) resolves against the episode count; later seasons must not,
+  // because the anchor is season 1 and may be shorter than the requested episode.
+  const anchor = pickAnchorMedia(searchTitle, media, {
+    episode: season === null || season <= 1 ? input.episode : null,
+  });
+  if (!anchor) return null;
+  const exactTitleMatch = mediaTitles(anchor).includes(normalizeTitleIdentity(searchTitle));
+
+  if (season === null || season <= 1) {
+    return toResolution(anchor, searchTitle, season, 'anchor', true, exactTitleMatch);
+  }
+
+  let chainError: unknown = null;
+  let viaChain: AnilistSeasonMedia | null = null;
+  try {
+    viaChain = await walkSequelChain(anchor, season, deps);
+  } catch (error) {
+    chainError = error;
+  }
+  if (viaChain) {
+    deps.logInfo?.(
+      `[anilist] season ${season} of "${searchTitle}" resolved via sequel chain: ${displayTitle(viaChain, searchTitle)} (${viaChain.id})`,
+    );
+    return toResolution(viaChain, searchTitle, season, 'sequel-chain', true, exactTitleMatch);
+  }
+
+  const viaAirOrder = pickByAirOrder(anchor, season, media);
+  if (viaAirOrder) {
+    deps.logInfo?.(
+      `[anilist] season ${season} of "${searchTitle}" resolved via air order: ${displayTitle(viaAirOrder, searchTitle)} (${viaAirOrder.id})`,
+    );
+    return toResolution(viaAirOrder, searchTitle, season, 'air-order', true, exactTitleMatch);
+  }
+
+  // The chain failed for transport reasons rather than because the season is absent;
+  // surface that so callers retry instead of reporting an unresolvable season.
+  if (chainError) {
+    throw chainError;
+  }
+
+  deps.logInfo?.(
+    `[anilist] could not resolve season ${season} of "${searchTitle}"; falling back to ${displayTitle(anchor, searchTitle)} (${anchor.id})`,
+  );
+  return toResolution(anchor, searchTitle, season, 'anchor', false, exactTitleMatch);
+}
@@ -85,6 +85,7 @@ const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
  'ankiConnect.fields.miscInfo',
  'ankiConnect.isLapis.sentenceCardModel',
  'ankiConnect.isKiku.fieldGrouping',
+  'ankiConnect.lapisKiku.wordCardKind',
 ] as const;

 function hotReloadFieldForChangedPath(path: string): string | null {
@@ -1466,6 +1466,190 @@ test('deleteVideo ignores the currently active video and keeps new writes flusha
  }
 });

+/**
+ * Attach the derived rows a real session would produce to every recorded line
+ * of `animeId`: word/kanji entries and their occurrences, monthly rollups, and
+ * cover art backed by a shared blob.
+ */
+function seedDerivedAnimeData(db: DatabaseSync, animeId: number): void {
+  const lines = db
+    .prepare(
+      'SELECT line_id AS lineId, CREATED_DATE AS seenMs FROM imm_subtitle_lines WHERE anime_id = ?',
+    )
+    .all(animeId) as Array<{ lineId: number; seenMs: number }>;
+  assert.ok(lines.length > 0, 'expected recorded subtitle lines to decorate');
+
+  db.prepare(
+    `INSERT INTO imm_words(id, headword, word, reading, part_of_speech, pos1, first_seen, last_seen, frequency)
+     VALUES (9001, '天気', '天気', 'てんき', 'noun', '名詞', 0, 0, 0)`,
+  ).run();
+  db.prepare(
+    `INSERT INTO imm_kanji(id, kanji, first_seen, last_seen, frequency) VALUES (9101, '気', 0, 0, 0)`,
+  ).run();
+
+  const insertWordOccurrence = db.prepare(
+    'INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count, seen_ms) VALUES (?, 9001, 1, ?)',
+  );
+  const insertKanjiOccurrence = db.prepare(
+    'INSERT INTO imm_kanji_line_occurrences(line_id, kanji_id, occurrence_count, seen_ms) VALUES (?, 9101, 1, ?)',
+  );
+  for (const line of lines) {
+    insertWordOccurrence.run(line.lineId, line.seenMs);
+    insertKanjiOccurrence.run(line.lineId, line.seenMs);
+  }
+  db.prepare(
+    `UPDATE imm_words SET frequency = ?, first_seen = ?, last_seen = ? WHERE id = 9001`,
+  ).run(lines.length, 0, 0);
+
+  const videoIds = (
+    db
+      .prepare('SELECT video_id AS videoId FROM imm_videos WHERE anime_id = ?')
+      .all(animeId) as Array<{ videoId: number }>
+  ).map((row) => row.videoId);
+  const insertMonthlyRollup = db.prepare(
+    `INSERT INTO imm_monthly_rollups(rollup_month, video_id, total_sessions, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (202401, ?, 1, '0', '0')`,
+  );
+  const insertArt = db.prepare(
+    `INSERT INTO imm_media_art(video_id, anilist_id, cover_url, cover_blob, cover_blob_hash, fetched_at_ms, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, 4242, 'https://example.test/cover.jpg', NULL, 'deadbeef', '0', '0', '0')`,
+  );
+  db.prepare(
+    `INSERT INTO imm_cover_art_blobs(blob_hash, cover_blob, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES ('deadbeef', X'FFD8FFD9', '0', '0')`,
+  ).run();
+  for (const videoId of videoIds) {
+    insertMonthlyRollup.run(videoId);
+    insertArt.run(videoId);
+  }
+}
+
+test('deleteAnime removes every episode, session and library row for the title', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+
+    for (const episode of ['S02E05', 'S02E06']) {
+      tracker = new Ctor({ dbPath });
+      tracker.handleMediaChange(`/tmp/Little Witch Academia ${episode}.mkv`, `Episode ${episode}`);
+      await waitForPendingAnimeMetadata(tracker);
+      tracker.recordSubtitleLine('今日は晴れです', 0, 1.2);
+      tracker.recordCardsMined(1);
+      tracker.destroy();
+      tracker = null;
+    }
+
+    tracker = new Ctor({ dbPath });
+    const privateApi = tracker as unknown as { db: DatabaseSync };
+    const animeId = (
+      privateApi.db.prepare('SELECT anime_id FROM imm_anime LIMIT 1').get() as {
+        anime_id: number;
+      } | null
+    )?.anime_id;
+    assert.ok(animeId);
+
+    // The tokenizer does not run in this harness, so attach vocabulary, kanji,
+    // rollups and cover art to the recorded lines by hand. Without them the
+    // "everything is gone" assertions below would pass against empty tables.
+    seedDerivedAnimeData(privateApi.db, animeId);
+
+    const countOf = (sql: string): number =>
+      (privateApi.db.prepare(sql).get() as { total: number }).total;
+    for (const table of [
+      'imm_words',
+      'imm_kanji',
+      'imm_word_line_occurrences',
+      'imm_kanji_line_occurrences',
+      'imm_daily_rollups',
+      'imm_monthly_rollups',
+      'imm_media_art',
+      'imm_cover_art_blobs',
+    ]) {
+      assert.ok(
+        countOf(`SELECT COUNT(*) AS total FROM ${table}`) > 0,
+        `precondition: ${table} should hold rows before the delete`,
+      );
+    }
+
+    const libraryBefore = await tracker.getAnimeLibrary();
+    assert.equal(libraryBefore.length, 1);
+    assert.equal(libraryBefore[0]?.episodeCount, 2);
+
+    await tracker.deleteAnime(animeId);
+
+    const libraryAfter = await tracker.getAnimeLibrary();
+    assert.equal(libraryAfter.length, 0);
+
+    for (const table of [
+      'imm_anime',
+      'imm_lifetime_anime',
+      'imm_videos',
+      'imm_sessions',
+      'imm_subtitle_lines',
+      'imm_daily_rollups',
+      'imm_monthly_rollups',
+      'imm_lifetime_media',
+      'imm_words',
+      'imm_kanji',
+      'imm_word_line_occurrences',
+      'imm_kanji_line_occurrences',
+      'imm_media_art',
+      'imm_cover_art_blobs',
+    ]) {
+      assert.equal(
+        countOf(`SELECT COUNT(*) AS total FROM ${table}`),
+        0,
+        `${table} should be empty after deleting the only title`,
+      );
+    }
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('deleteAnime ignores the title of the currently active session', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath });
+    tracker.handleMediaChange('/tmp/Little Witch Academia S02E05.mkv', 'Episode 5');
+    await waitForPendingAnimeMetadata(tracker);
+
+    const privateApi = tracker as unknown as {
+      db: DatabaseSync;
+      sessionState: { sessionId: number; videoId: number } | null;
+    };
+    const videoId = privateApi.sessionState?.videoId;
+    assert.ok(videoId);
+    const animeId = (
+      privateApi.db.prepare('SELECT anime_id FROM imm_videos WHERE video_id = ?').get(videoId) as {
+        anime_id: number | null;
+      } | null
+    )?.anime_id;
+    assert.ok(animeId);
+
+    await tracker.deleteAnime(animeId);
+
+    const animeCountRow = privateApi.db
+      .prepare('SELECT COUNT(*) AS total FROM imm_anime WHERE anime_id = ?')
+      .get(animeId) as { total: number };
+    const videoCountRow = privateApi.db
+      .prepare('SELECT COUNT(*) AS total FROM imm_videos WHERE video_id = ?')
+      .get(videoId) as { total: number };
+
+    assert.equal(animeCountRow.total, 1);
+    assert.equal(videoCountRow.total, 1);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
 test('handleMediaChange links parsed anime metadata on the active video row', async () => {
  const dbPath = makeDbPath();
  let tracker: ImmersionTrackerService | null = null;
@@ -83,6 +83,7 @@ import {
 } from './immersion-tracker/query-library';
 import {
  cleanupVocabularyStats,
+  deleteAnime as deleteAnimeQuery,
  deleteSession as deleteSessionQuery,
  deleteSessions as deleteSessionsQuery,
  deleteVideo as deleteVideoQuery,
@@ -92,9 +93,18 @@ import {
 } from './immersion-tracker/query-maintenance';
 import { repairJellyfinStreamVideoLinks } from './immersion-tracker/jellyfin-link-repair';
 import {
+  dismissAnimeMergeRecommendation,
+  getAnimeMergeRecommendations,
  repairLegacySeasonlessAnimeRows,
  resolveAnimeAnilistConflict,
+  type AnimeMergeRecommendation,
 } from './immersion-tracker/anime-season-repair';
+import {
+  mergeAnimeRecords,
+  moveVideoToAnime as moveVideoToAnimeQuery,
+  type AnimeMergeSummary,
+  type VideoMoveSummary,
+} from './immersion-tracker/anime-merge';
 import {
  buildVideoKey,
  deriveCanonicalTitle,
@@ -595,8 +605,7 @@ export class ImmersionTrackerService {
  }

  async rebuildLifetimeSummaries(): Promise<LifetimeRebuildSummary> {
-    this.flushTelemetry(true);
-    this.flushNow();
+    this.requireWriteQueueDrained('rebuilding lifetime summaries');
    return rebuildLifetimeSummaryTables(this.db);
  }

@@ -663,6 +672,14 @@ export class ImmersionTrackerService {
    return getAnimeLibrary(this.db);
  }

+  async getAnimeMergeRecommendations(): Promise<AnimeMergeRecommendation[]> {
+    return getAnimeMergeRecommendations(this.db);
+  }
+
+  async dismissAnimeMergeRecommendation(recommendationId: number): Promise<boolean> {
+    return dismissAnimeMergeRecommendation(this.db, recommendationId);
+  }
+
  async getAnimeDetail(animeId: number): Promise<AnimeDetailRow | null> {
    this.relinkYoutubeAnimeLibrary();
    return getAnimeDetail(this.db, animeId);
@@ -733,6 +750,85 @@ export class ImmersionTrackerService {
    deleteVideoQuery(this.db, videoId);
  }

+  async deleteAnime(animeId: number): Promise<void> {
+    // The active video's anime link is assigned asynchronously after the title
+    // is parsed, so a guard reading imm_videos too early sees a null and lets
+    // the delete through — then the late update recreates the anime row.
+    const pendingVideoId = this.sessionState?.videoId;
+    if (pendingVideoId !== undefined) {
+      await this.pendingAnimeMetadataUpdates.get(pendingVideoId);
+    }
+
+    const activeVideoId = this.sessionState?.videoId;
+    if (activeVideoId !== undefined) {
+      const activeAnime = this.db
+        .prepare('SELECT anime_id FROM imm_videos WHERE video_id = ?')
+        .get(activeVideoId) as { anime_id: number | null } | null;
+      if (activeAnime?.anime_id === animeId) {
+        this.logger.warn(`Ignoring delete request for active immersion anime ${animeId}`);
+        return;
+      }
+    }
+    deleteAnimeQuery(this.db, animeId);
+  }
+
+  /**
+   * Fold duplicate library entries into one. Sources that hold the currently
+   * playing episode are fine: the videos move, nothing is deleted out from
+   * under the active session.
+   */
+  async mergeAnime(targetAnimeId: number, sourceAnimeIds: number[]): Promise<AnimeMergeSummary> {
+    const pendingVideoId = this.sessionState?.videoId;
+    if (pendingVideoId !== undefined) {
+      await this.pendingAnimeMetadataUpdates.get(pendingVideoId);
+    }
+    // This rebuilds the lifetime summaries, which recompute from the database:
+    // queued writes have to land first or the active session is dropped from
+    // the merged totals.
+    this.requireWriteQueueDrained('merging library entries');
+    return mergeAnimeRecords(this.db, targetAnimeId, sourceAnimeIds);
+  }
+
+  async moveVideoToAnime(videoId: number, targetAnimeId: number): Promise<VideoMoveSummary> {
+    await this.pendingAnimeMetadataUpdates.get(videoId);
+    this.requireWriteQueueDrained('moving an episode');
+    return moveVideoToAnimeQuery(this.db, videoId, targetAnimeId);
+  }
+
+  /**
+   * Persist every queued write before a caller recomputes summaries from the
+   * database.
+   *
+   * A single `flushNow()` is not enough: forced telemetry is appended to the
+   * back of the queue while `flushNow()` writes at most `batchSize` entries off
+   * the front, so a busy session leaves the newest sample unwritten. Stops as
+   * soon as a pass makes no progress — a rolled-back batch is pushed back onto
+   * the queue, and looping on that would spin forever.
+   *
+   * Returns false when the queue could not be emptied. Summary-rebuilding
+   * callers fail closed in that case.
+   */
+  private drainWriteQueue(context: string): boolean {
+    this.flushTelemetry(true);
+    while (this.queue.length > 0) {
+      const pending = this.queue.length;
+      this.flushNow();
+      if (this.queue.length >= pending) {
+        this.logger.warn(
+          `Immersion tracker queue did not drain before ${context}; summaries may lag by ${this.queue.length} writes`,
+        );
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private requireWriteQueueDrained(context: string): void {
+    if (!this.drainWriteQueue(context)) {
+      throw new Error(`Immersion tracker queue did not drain before ${context}`);
+    }
+  }
+
  async reassignAnimeAnilist(
    animeId: number,
    info: {
@@ -745,7 +841,13 @@ export class ImmersionTrackerService {
      coverUrl?: string | null;
    },
  ): Promise<void> {
-    const repair = resolveAnimeAnilistConflict(this.db, animeId, info.anilistId);
+    // The user is acting on this entry, so it is the one that survives when
+    // another row already claims the same AniList id.
+    const repair = resolveAnimeAnilistConflict(this.db, animeId, info.anilistId, {
+      survivor: 'target',
+      matchConfidence: 'manual',
+    });
+    if (repair.anilistAssignmentBlocked) return;
    this.db
      .prepare(
        `
@@ -0,0 +1,700 @@
+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 { mergeAnimeRecords, moveVideoToAnime } from '../anime-merge.js';
+import {
+  dismissAnimeMergeRecommendation,
+  getAnimeMergeRecommendations,
+  resolveAnimeAnilistConflict,
+} from '../anime-season-repair.js';
+import { updateAnimeAnilistInfo } from '../query-maintenance.js';
+
+const BASE_MS = 1_700_000_000_000;
+
+function makeDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-anime-merge-test-'));
+  return path.join(dir, 'immersion.sqlite');
+}
+
+function cleanupDbPath(dbPath: string): void {
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) return;
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function withDb(work: (db: DatabaseSync) => void): void {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  try {
+    applyPragmas(db);
+    ensureSchema(db);
+    work(db);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+}
+
+interface AnimeSeed {
+  animeId: number;
+  key: string;
+  title: string;
+  anilistId?: number | null;
+  titleRomaji?: string | null;
+}
+
+function insertAnime(db: DatabaseSync, seed: AnimeSeed): void {
+  db.prepare(
+    `INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, anilist_id, title_romaji, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    seed.animeId,
+    seed.key,
+    seed.title,
+    seed.anilistId ?? null,
+    seed.titleRomaji ?? null,
+    BASE_MS,
+    BASE_MS,
+  );
+}
+
+interface EpisodeSeed {
+  videoId: number;
+  animeId: number;
+  season?: number | null;
+  episode?: number;
+  activeMs?: number;
+  cards?: number;
+}
+
+/** One episode with one ended session, so lifetime rebuilds have something to sum. */
+function insertEpisode(db: DatabaseSync, seed: EpisodeSeed): void {
+  const activeMs = seed.activeMs ?? 1000;
+  const cards = seed.cards ?? 1;
+  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, 'Show', ?, ?, 1, 1440000, ?, ?)`,
+  ).run(
+    seed.videoId,
+    `local:/tmp/show-${seed.videoId}.mkv`,
+    seed.animeId,
+    `Show ${seed.videoId}`,
+    seed.season ?? null,
+    seed.episode ?? seed.videoId,
+    BASE_MS,
+    BASE_MS,
+  );
+  db.prepare(
+    `INSERT INTO imm_sessions(session_id, session_uuid, video_id, started_at_ms, ended_at_ms, status, active_watched_ms, cards_mined, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?, ?, 2, ?, ?, ?, ?)`,
+  ).run(
+    seed.videoId,
+    `session-${seed.videoId}`,
+    seed.videoId,
+    String(BASE_MS),
+    String(BASE_MS + activeMs),
+    activeMs,
+    cards,
+    BASE_MS,
+    BASE_MS,
+  );
+  db.prepare(
+    `INSERT INTO imm_subtitle_lines(session_id, video_id, anime_id, line_index, text, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, 1, ?, ?, ?)`,
+  ).run(seed.videoId, seed.videoId, seed.animeId, `line ${seed.videoId}`, BASE_MS, BASE_MS);
+}
+
+function animeIds(db: DatabaseSync): number[] {
+  return (
+    db.prepare('SELECT anime_id AS id FROM imm_anime ORDER BY anime_id').all() as Array<{
+      id: number;
+    }>
+  ).map((row) => row.id);
+}
+
+function videoAnimeId(db: DatabaseSync, videoId: number): number | null {
+  return (
+    db.prepare('SELECT anime_id AS id FROM imm_videos WHERE video_id = ?').get(videoId) as {
+      id: number | null;
+    }
+  ).id;
+}
+
+function lineAnimeIds(db: DatabaseSync, animeId: number): number {
+  return Number(
+    (
+      db
+        .prepare('SELECT COUNT(*) AS total FROM imm_subtitle_lines WHERE anime_id = ?')
+        .get(animeId) as { total: number }
+    ).total,
+  );
+}
+
+test('mergeAnimeRecords folds episodes, lines and lifetime totals into the target', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertAnime(db, { animeId: 2, key: 'show season 1', title: 'Show Season 1', anilistId: 555 });
+    insertEpisode(db, { videoId: 1, animeId: 1, activeMs: 1000, cards: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1, activeMs: 2000, cards: 3 });
+
+    const summary = mergeAnimeRecords(db, 1, [2]);
+
+    assert.equal(summary.survivingAnimeId, 1);
+    assert.deepEqual(summary.mergedAnimeIds, [2]);
+    assert.equal(summary.movedVideos, 1);
+    assert.deepEqual(animeIds(db), [1]);
+    assert.equal(videoAnimeId(db, 2), 1);
+    assert.equal(lineAnimeIds(db, 1), 2);
+
+    const lifetime = db
+      .prepare(
+        'SELECT total_active_ms AS activeMs, total_cards AS cards, episodes_started AS episodes FROM imm_lifetime_anime WHERE anime_id = 1',
+      )
+      .get() as { activeMs: number; cards: number; episodes: number };
+    assert.equal(lifetime.activeMs, 3000);
+    assert.equal(lifetime.cards, 4);
+    assert.equal(lifetime.episodes, 2);
+  });
+});
+
+test('mergeAnimeRecords repoints subtitle lines recorded before the anime link landed', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertAnime(db, { animeId: 2, key: 'show season 1', title: 'Show Season 1' });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+    // Lines are written with the video's anime_id at the time, which is NULL
+    // until the async title parse assigns one.
+    db.prepare(
+      `INSERT INTO imm_subtitle_lines(session_id, video_id, anime_id, line_index, text, CREATED_DATE, LAST_UPDATE_DATE)
+       VALUES (2, 2, NULL, 2, 'unlinked line', ?, ?)`,
+    ).run(BASE_MS, BASE_MS);
+
+    mergeAnimeRecords(db, 1, [2]);
+
+    assert.equal(lineAnimeIds(db, 1), 3);
+    const orphaned = Number(
+      (
+        db
+          .prepare('SELECT COUNT(*) AS total FROM imm_subtitle_lines WHERE anime_id IS NULL')
+          .get() as { total: number }
+      ).total,
+    );
+    assert.equal(orphaned, 0);
+  });
+});
+
+test('mergeAnimeRecords inherits metadata the target is missing without clobbering its own', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show', titleRomaji: 'Shou' });
+    insertAnime(db, {
+      animeId: 2,
+      key: 'show season 1',
+      title: 'Show Season 1',
+      anilistId: 555,
+      titleRomaji: 'Show Romaji',
+    });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    mergeAnimeRecords(db, 1, [2]);
+
+    const row = db
+      .prepare(
+        'SELECT canonical_title AS title, anilist_id AS anilistId, title_romaji AS romaji FROM imm_anime WHERE anime_id = 1',
+      )
+      .get() as { title: string; anilistId: number | null; romaji: string | null };
+    assert.equal(row.title, 'Show');
+    // anilist_id is UNIQUE, so inheriting it proves the source row was gone first.
+    assert.equal(row.anilistId, 555);
+    assert.equal(row.romaji, 'Shou');
+  });
+});
+
+test('mergeAnimeRecords preserves source title identities as aliases of the survivor', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertAnime(db, { animeId: 2, key: 'show season 1', title: 'Show Season 1' });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    db.prepare(
+      `INSERT INTO imm_anime_title_aliases(normalized_title_key, anime_id, CREATED_DATE, LAST_UPDATE_DATE)
+       VALUES ('show s01', 2, ?, ?)`,
+    ).run(BASE_MS, BASE_MS);
+
+    mergeAnimeRecords(db, 1, [2]);
+
+    const fromSourceTitle = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Show Season 1',
+      canonicalTitle: 'Show Season 1',
+      seasonScope: 1,
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+    const fromTransferredAlias = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Show S01',
+      canonicalTitle: 'Show S01',
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+
+    assert.equal(fromSourceTitle, 1);
+    assert.equal(fromTransferredAlias, 1);
+    assert.deepEqual(animeIds(db), [1]);
+    assert.equal(
+      (
+        db.prepare('SELECT canonical_title AS title FROM imm_anime WHERE anime_id = 1').get() as {
+          title: string;
+        }
+      ).title,
+      'Show',
+    );
+  });
+});
+
+test('mergeAnimeRecords ignores unknown targets and self-merges', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+
+    assert.deepEqual(mergeAnimeRecords(db, 99, [1]).mergedAnimeIds, []);
+    assert.deepEqual(mergeAnimeRecords(db, 1, [1]).mergedAnimeIds, []);
+    assert.deepEqual(animeIds(db), [1]);
+    assert.equal(videoAnimeId(db, 1), 1);
+  });
+});
+
+test('moveVideoToAnime moves one episode and prunes the emptied entry', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertAnime(db, { animeId: 2, key: 'stray', title: 'Stray Episode Title', anilistId: 777 });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, activeMs: 5000, cards: 2 });
+
+    const summary = moveVideoToAnime(db, 2, 1);
+
+    assert.equal(summary.targetAnimeId, 1);
+    assert.equal(summary.previousAnimeId, 2);
+    assert.equal(summary.removedPreviousAnime, true);
+    assert.deepEqual(animeIds(db), [1]);
+    assert.equal(videoAnimeId(db, 2), 1);
+    assert.equal(lineAnimeIds(db, 1), 2);
+    const lifetime = db
+      .prepare('SELECT total_active_ms AS activeMs FROM imm_lifetime_anime WHERE anime_id = 1')
+      .get() as { activeMs: number };
+    assert.equal(lifetime.activeMs, 6000);
+    // The stray entry's AniList link is dropped, not inherited: a move makes no
+    // claim that the two entries are the same show.
+    const target = db
+      .prepare('SELECT anilist_id AS anilistId FROM imm_anime WHERE anime_id = 1')
+      .get() as { anilistId: number | null };
+    assert.equal(target.anilistId, null);
+  });
+});
+
+test('moveVideoToAnime is a no-op when the episode is already in the target entry', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+
+    const summary = moveVideoToAnime(db, 1, 1);
+
+    assert.equal(summary.targetAnimeId, 1);
+    assert.equal(summary.previousAnimeId, 1);
+    assert.equal(summary.removedPreviousAnime, false);
+    assert.deepEqual(animeIds(db), [1]);
+    assert.equal(videoAnimeId(db, 1), 1);
+  });
+});
+
+test('moveVideoToAnime keeps the source entry when other episodes remain', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertAnime(db, { animeId: 2, key: 'other', title: 'Other' });
+    insertEpisode(db, { videoId: 1, animeId: 2 });
+    insertEpisode(db, { videoId: 2, animeId: 2 });
+
+    const summary = moveVideoToAnime(db, 2, 1);
+
+    assert.equal(summary.removedPreviousAnime, false);
+    assert.deepEqual(animeIds(db), [1, 2]);
+    assert.equal(videoAnimeId(db, 1), 2);
+    assert.equal(videoAnimeId(db, 2), 1);
+  });
+});
+
+test('moveVideoToAnime rejects unknown episodes and targets', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show' });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+
+    assert.throws(() => moveVideoToAnime(db, 99, 1));
+    assert.throws(() => moveVideoToAnime(db, 1, 99));
+    assert.equal(videoAnimeId(db, 1), 1);
+  });
+});
+
+test('resolveAnimeAnilistConflict folds a seasonless duplicate into the entry that owns the id', () => {
+  withDb((db) => {
+    // Same show, split because one release tagged S01 and the other did not.
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show', anilistId: 163132 });
+    insertAnime(db, { animeId: 2, key: 'show season 1', title: 'Show Season 1' });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132);
+
+    assert.equal(summary.survivingAnimeId, 1);
+    assert.equal(summary.movedVideos, 1);
+    assert.equal(summary.deletedAnimeRows, 1);
+    assert.deepEqual(animeIds(db), [1]);
+    assert.equal(videoAnimeId(db, 2), 1);
+  });
+});
+
+test('resolveAnimeAnilistConflict recommends a weak title collision instead of merging it', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'actual show',
+      title: 'Actual Show',
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'unrelated release', title: 'Unrelated Release' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132);
+
+    assert.equal(summary.repaired, 0);
+    assert.deepEqual(animeIds(db), [1, 2]);
+    assert.equal(videoAnimeId(db, 2), 2);
+    assert.deepEqual(getAnimeMergeRecommendations(db), [{ recommendationId: 1, animeIds: [1, 2] }]);
+  });
+});
+
+test('automatic AniList update leaves a weak collision unassigned for user review', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'actual show',
+      title: 'Actual Show',
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'unrelated release', title: 'Unrelated Release' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    updateAnimeAnilistInfo(db, 2, {
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+      titleEnglish: null,
+      titleNative: null,
+      episodesTotal: 12,
+      exactTitleMatch: false,
+    });
+
+    const target = db
+      .prepare('SELECT anilist_id AS anilistId FROM imm_anime WHERE anime_id = 2')
+      .get() as {
+      anilistId: number | null;
+    };
+    assert.equal(target.anilistId, null);
+    assert.deepEqual(getAnimeMergeRecommendations(db), [{ recommendationId: 1, animeIds: [1, 2] }]);
+  });
+});
+
+test('dismissed weak collision stays dismissed when automatic resolution repeats', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'actual show',
+      title: 'Actual Show',
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'unrelated release', title: 'Unrelated Release' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    resolveAnimeAnilistConflict(db, 2, 163132);
+    assert.equal(dismissAnimeMergeRecommendation(db, 1), true);
+    resolveAnimeAnilistConflict(db, 2, 163132);
+
+    assert.deepEqual(getAnimeMergeRecommendations(db), []);
+  });
+});
+
+test('dismissed recommendation prevents a later exact automatic merge of the pair', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'actual show',
+      title: 'Actual Show',
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'unrelated release', title: 'Unrelated Release' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    resolveAnimeAnilistConflict(db, 2, 163132, { matchConfidence: 'weak' });
+    assert.equal(dismissAnimeMergeRecommendation(db, 1), true);
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132, { matchConfidence: 'exact' });
+
+    assert.equal(summary.repaired, 0);
+    assert.deepEqual(animeIds(db), [1, 2]);
+    assert.equal(videoAnimeId(db, 2), 2);
+    assert.deepEqual(getAnimeMergeRecommendations(db), []);
+  });
+});
+
+test('manual merge clears recommendations involving the absorbed entry', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'actual show',
+      title: 'Actual Show',
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'unrelated release', title: 'Unrelated Release' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    resolveAnimeAnilistConflict(db, 2, 163132);
+    mergeAnimeRecords(db, 1, [2]);
+
+    assert.deepEqual(getAnimeMergeRecommendations(db), []);
+  });
+});
+
+test('resolveAnimeAnilistConflict keeps the target entry when the user drove the change', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show', anilistId: 163132 });
+    insertAnime(db, { animeId: 2, key: 'show season 1', title: 'Show Season 1' });
+    insertEpisode(db, { videoId: 1, animeId: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132, { survivor: 'target' });
+
+    assert.equal(summary.survivingAnimeId, 2);
+    assert.deepEqual(animeIds(db), [2]);
+    assert.equal(videoAnimeId(db, 1), 2);
+    const row = db.prepare('SELECT anilist_id AS id FROM imm_anime WHERE anime_id = 2').get() as {
+      id: number | null;
+    };
+    assert.equal(row.id, 163132);
+  });
+});
+
+test('resolveAnimeAnilistConflict falls back to season redistribution for multi-season rows', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show', anilistId: 163132 });
+    insertAnime(db, { animeId: 2, key: 'show season 1', title: 'Show Season 1' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 1, season: 2 });
+    insertEpisode(db, { videoId: 3, animeId: 2, season: 1 });
+
+    resolveAnimeAnilistConflict(db, 2, 163132);
+
+    // The mixed row is split by season instead of being poured onto one card.
+    const titles = (
+      db.prepare('SELECT canonical_title AS title FROM imm_anime ORDER BY title').all() as Array<{
+        title: string;
+      }>
+    ).map((row) => row.title);
+    assert.deepEqual(titles, ['Show Season 1', 'Show Season 2']);
+    assert.equal(videoAnimeId(db, 1), 2);
+    assert.equal(videoAnimeId(db, 3), 2);
+    assert.notEqual(videoAnimeId(db, 2), 2);
+  });
+});
+
+test('resolveAnimeAnilistConflict leaves explicit incompatible seasons and assignments unchanged', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'show season 1',
+      title: 'Show Season 1',
+      anilistId: 163132,
+      titleRomaji: 'Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'show season 2', title: 'Show Season 2' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 2 });
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132, { matchConfidence: 'exact' });
+
+    assert.equal(summary.repaired, 0);
+    assert.equal(summary.movedVideos, 0);
+    assert.equal(summary.deletedAnimeRows, 0);
+    assert.deepEqual(animeIds(db), [1, 2]);
+    assert.equal(videoAnimeId(db, 1), 1);
+    assert.equal(videoAnimeId(db, 2), 2);
+    const assignments = db
+      .prepare(
+        'SELECT anime_id AS animeId, anilist_id AS anilistId FROM imm_anime ORDER BY anime_id',
+      )
+      .all() as Array<{ animeId: number; anilistId: number | null }>;
+    assert.deepEqual(assignments, [
+      { animeId: 1, anilistId: 163132 },
+      { animeId: 2, anilistId: null },
+    ]);
+    assert.deepEqual(getAnimeMergeRecommendations(db), []);
+  });
+});
+
+test('manual AniList resolution reassigns across explicit seasons without merging them', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'show season 1',
+      title: 'Show Season 1',
+      anilistId: 163132,
+      titleRomaji: 'Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'show season 2', title: 'Show Season 2' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 2 });
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132, { survivor: 'target' });
+
+    assert.equal(summary.anilistAssignmentBlocked, false);
+    assert.deepEqual(animeIds(db), [1, 2]);
+    const assignments = db
+      .prepare(
+        'SELECT anime_id AS animeId, anilist_id AS anilistId FROM imm_anime ORDER BY anime_id',
+      )
+      .all() as Array<{ animeId: number; anilistId: number | null }>;
+    assert.deepEqual(assignments, [
+      { animeId: 1, anilistId: null },
+      { animeId: 2, anilistId: 163132 },
+    ]);
+  });
+});
+
+test('automatic AniList update does not transfer an assignment across explicit seasons', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'show season 1',
+      title: 'Show Season 1',
+      anilistId: 163132,
+      titleRomaji: 'Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'show season 2', title: 'Show Season 2' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 2 });
+
+    updateAnimeAnilistInfo(db, 2, {
+      anilistId: 163132,
+      titleRomaji: 'Show',
+      titleEnglish: null,
+      titleNative: null,
+      episodesTotal: 12,
+      exactTitleMatch: true,
+    });
+
+    const assignments = db
+      .prepare(
+        'SELECT anime_id AS animeId, anilist_id AS anilistId FROM imm_anime ORDER BY anime_id',
+      )
+      .all() as Array<{ animeId: number; anilistId: number | null }>;
+    assert.deepEqual(assignments, [
+      { animeId: 1, anilistId: 163132 },
+      { animeId: 2, anilistId: null },
+    ]);
+    assert.equal(videoAnimeId(db, 1), 1);
+    assert.equal(videoAnimeId(db, 2), 2);
+  });
+});
+
+test('automatic AniList update with unknown match confidence validates stored titles', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'actual show',
+      title: 'Actual Show',
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+    });
+    insertAnime(db, { animeId: 2, key: 'unrelated release', title: 'Unrelated Release' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    updateAnimeAnilistInfo(db, 2, {
+      anilistId: 163132,
+      titleRomaji: 'Actual Show',
+      titleEnglish: null,
+      titleNative: null,
+      episodesTotal: 12,
+    });
+
+    assert.deepEqual(animeIds(db), [1, 2]);
+    assert.equal(videoAnimeId(db, 2), 2);
+    assert.deepEqual(getAnimeMergeRecommendations(db), [{ recommendationId: 1, animeIds: [1, 2] }]);
+  });
+});
+
+test('stored AniList titles ignore season suffixes when validating an automatic merge', () => {
+  withDb((db) => {
+    insertAnime(db, {
+      animeId: 1,
+      key: 'legacy show',
+      title: 'Show Season 1',
+      anilistId: 163132,
+      titleRomaji: 'Show Season 1',
+    });
+    insertAnime(db, { animeId: 2, key: 'show season 1', title: 'Show Season 1' });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 1 });
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132);
+
+    assert.equal(summary.deletedAnimeRows, 1);
+    assert.deepEqual(animeIds(db), [1]);
+    assert.equal(videoAnimeId(db, 2), 1);
+    assert.deepEqual(getAnimeMergeRecommendations(db), []);
+  });
+});
+
+test('resolveAnimeAnilistConflict leaves an entry that already links elsewhere alone', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'show', title: 'Show', anilistId: 163132 });
+    insertAnime(db, { animeId: 2, key: 'show s2', title: 'Show Season 2', anilistId: 999 });
+    insertEpisode(db, { videoId: 1, animeId: 1, season: 1 });
+    insertEpisode(db, { videoId: 2, animeId: 2, season: 2 });
+
+    const summary = resolveAnimeAnilistConflict(db, 2, 163132);
+
+    assert.equal(videoAnimeId(db, 2), 2);
+    assert.ok(animeIds(db).includes(2));
+    assert.equal(
+      (
+        db.prepare('SELECT anilist_id AS anilistId FROM imm_anime WHERE anime_id = 2').get() as {
+          anilistId: number;
+        }
+      ).anilistId,
+      999,
+    );
+    assert.equal(summary.repaired, 0);
+    assert.equal(summary.movedVideos, 0);
+    assert.deepEqual(getAnimeMergeRecommendations(db), []);
+  });
+});
@@ -0,0 +1,331 @@
+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 { ensureSchema } from '../storage.js';
+import { deleteSession, deleteSessions, deleteVideo } from '../query-maintenance.js';
+
+const DAY_MS = 86_400_000;
+const BASE_MS = 1_700_000_000_000;
+
+function makeDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-lexical-removal-test-'));
+  return path.join(dir, 'immersion.sqlite');
+}
+
+function cleanupDbPath(dbPath: string): void {
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) return;
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Seed two episodes of one anime, each with one ended session.
+ *
+ * `lines` places a word occurrence on a specific day so tests can control which
+ * session holds a word's first/last occurrence.
+ */
+function seed(
+  db: DatabaseSync,
+  lines: Array<{ session: 1 | 2; wordId: number; dayOffset: number; count?: number }>,
+  options: { legacyRows?: boolean } = {},
+): void {
+  db.exec(`
+    INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'show', 'Show', ${BASE_MS}, ${BASE_MS});
+    INSERT INTO imm_videos(video_id, video_key, anime_id, canonical_title, source_type, watched, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'v1', 1, 'Ep 1', 1, 1, 1440000, ${BASE_MS}, ${BASE_MS}),
+             (2, 'v2', 1, 'Ep 2', 1, 1, 1440000, ${BASE_MS}, ${BASE_MS});
+    INSERT INTO imm_sessions(session_id, session_uuid, video_id, started_at_ms, ended_at_ms, status, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 's1', 1, '${BASE_MS}', '${BASE_MS + 1000}', 2, ${BASE_MS}, ${BASE_MS}),
+             (2, 's2', 2, '${BASE_MS + DAY_MS}', '${BASE_MS + DAY_MS + 1000}', 2, ${BASE_MS}, ${BASE_MS});
+  `);
+
+  const insertLine = db.prepare(
+    `INSERT INTO imm_subtitle_lines(line_id, session_id, video_id, anime_id, line_index, text, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, 1, ?, ?, ?, ?)`,
+  );
+  const insertWord = db.prepare(
+    `INSERT OR IGNORE INTO imm_words(id, headword, word, reading, part_of_speech, pos1, first_seen, last_seen, frequency)
+     VALUES (?, ?, ?, '', 'noun', '名詞', 0, 0, 0)`,
+  );
+  // `legacyRows` reproduces databases written before the seen_ms column existed,
+  // where the timestamp has to be read back off the subtitle line.
+  const insertOccurrence = options.legacyRows
+    ? db.prepare(
+        `INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count) VALUES (?, ?, ?)`,
+      )
+    : db.prepare(
+        `INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count, seen_ms) VALUES (?, ?, ?, ?)`,
+      );
+
+  let lineId = 0;
+  for (const line of lines) {
+    lineId += 1;
+    const seenMs = BASE_MS + line.dayOffset * DAY_MS;
+    insertLine.run(lineId, line.session, line.session, lineId, `line ${lineId}`, seenMs, seenMs);
+    insertWord.run(line.wordId, `語${line.wordId}`, `語${line.wordId}`);
+    if (options.legacyRows) {
+      insertOccurrence.run(lineId, line.wordId, line.count ?? 1);
+    } else {
+      insertOccurrence.run(lineId, line.wordId, line.count ?? 1, seenMs);
+    }
+  }
+
+  // Match what the tracker maintains: aggregates derived from the occurrences.
+  db.exec(`
+    UPDATE imm_words SET
+      frequency = (
+        SELECT COALESCE(SUM(o.occurrence_count), 0)
+        FROM imm_word_line_occurrences o WHERE o.word_id = imm_words.id
+      ),
+      first_seen = (
+        SELECT MIN(sl.CREATED_DATE) / 1000
+        FROM imm_word_line_occurrences o
+        JOIN imm_subtitle_lines sl ON sl.line_id = o.line_id
+        WHERE o.word_id = imm_words.id
+      ),
+      last_seen = (
+        SELECT MAX(sl.LAST_UPDATE_DATE) / 1000
+        FROM imm_word_line_occurrences o
+        JOIN imm_subtitle_lines sl ON sl.line_id = o.line_id
+        WHERE o.word_id = imm_words.id
+      )
+  `);
+}
+
+function createDb(
+  lines: Parameters<typeof seed>[1],
+  options: Parameters<typeof seed>[2] = {},
+): { db: DatabaseSync; dbPath: string } {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  ensureSchema(db);
+  seed(db, lines, options);
+  return { db, dbPath };
+}
+
+function readWord(
+  db: DatabaseSync,
+  wordId: number,
+): { frequency: number; firstSeen: number; lastSeen: number } | null {
+  return (
+    (db
+      .prepare(
+        'SELECT frequency, first_seen AS firstSeen, last_seen AS lastSeen FROM imm_words WHERE id = ?',
+      )
+      .get(wordId) as { frequency: number; firstSeen: number; lastSeen: number } | null) ?? null
+  );
+}
+
+test('deleting a session subtracts only the occurrences it removed', () => {
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 10, dayOffset: 0, count: 3 },
+    { session: 2, wordId: 10, dayOffset: 1, count: 4 },
+  ]);
+
+  try {
+    assert.equal(readWord(db, 10)?.frequency, 7);
+
+    deleteSession(db, 1);
+
+    assert.equal(readWord(db, 10)?.frequency, 4, 'only session 1 occurrences are subtracted');
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('deleting the session that held a word first drops the word entirely', () => {
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 11, dayOffset: 0 },
+    { session: 2, wordId: 12, dayOffset: 1 },
+  ]);
+
+  try {
+    deleteSession(db, 1);
+
+    assert.equal(readWord(db, 11), null, 'word seen only in the deleted session is removed');
+    assert.ok(readWord(db, 12), 'word seen elsewhere survives');
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('deleting the earliest session moves first_seen forward to the surviving line', () => {
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 13, dayOffset: 0 },
+    { session: 2, wordId: 13, dayOffset: 5 },
+  ]);
+
+  try {
+    assert.equal(readWord(db, 13)?.firstSeen, Math.floor(BASE_MS / 1000));
+
+    deleteSession(db, 1);
+
+    const word = readWord(db, 13);
+    assert.equal(word?.frequency, 1);
+    assert.equal(
+      word?.firstSeen,
+      Math.floor((BASE_MS + 5 * DAY_MS) / 1000),
+      'first_seen advances to the remaining occurrence',
+    );
+    assert.equal(word?.lastSeen, Math.floor((BASE_MS + 5 * DAY_MS) / 1000));
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('deleting the latest session moves last_seen back to the surviving line', () => {
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 14, dayOffset: 0 },
+    { session: 2, wordId: 14, dayOffset: 5 },
+  ]);
+
+  try {
+    deleteSession(db, 2);
+
+    const word = readWord(db, 14);
+    assert.equal(word?.frequency, 1);
+    assert.equal(word?.lastSeen, Math.floor(BASE_MS / 1000), 'last_seen falls back to session 1');
+    assert.equal(word?.firstSeen, Math.floor(BASE_MS / 1000));
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('deleting an interior occurrence leaves the surrounding extremes untouched', () => {
+  // Session 2 carries the middle occurrence; sessions bracket it in time.
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 15, dayOffset: 0 },
+    { session: 2, wordId: 15, dayOffset: 3 },
+    { session: 1, wordId: 15, dayOffset: 9 },
+  ]);
+
+  try {
+    deleteSessions(db, [2]);
+
+    const word = readWord(db, 15);
+    assert.equal(word?.frequency, 2);
+    assert.equal(word?.firstSeen, Math.floor(BASE_MS / 1000));
+    assert.equal(word?.lastSeen, Math.floor((BASE_MS + 9 * DAY_MS) / 1000));
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('a stored frequency that has drifted low is repaired instead of dropping a live word', () => {
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 16, dayOffset: 0, count: 5 },
+    { session: 2, wordId: 16, dayOffset: 4, count: 5 },
+  ]);
+
+  try {
+    // Simulate drift: the stored total is lower than the occurrences justify, so
+    // naive subtraction would take the word to zero while rows still reference it.
+    db.prepare('UPDATE imm_words SET frequency = 5 WHERE id = ?').run(16);
+
+    deleteSession(db, 1);
+
+    const word = readWord(db, 16);
+    assert.ok(word, 'word with surviving occurrences is not deleted');
+    assert.equal(word?.frequency, 5, 'frequency is recomputed from the surviving occurrences');
+    assert.equal(word?.firstSeen, Math.floor((BASE_MS + 4 * DAY_MS) / 1000));
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('deleting a video subtracts every occurrence carried by its lines', () => {
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 17, dayOffset: 0, count: 2 },
+    { session: 1, wordId: 17, dayOffset: 1, count: 3 },
+    { session: 2, wordId: 17, dayOffset: 2, count: 4 },
+    { session: 2, wordId: 18, dayOffset: 2, count: 1 },
+  ]);
+
+  try {
+    deleteVideo(db, 1);
+
+    assert.equal(readWord(db, 17)?.frequency, 4, 'both lines from video 1 are subtracted');
+    assert.equal(readWord(db, 18)?.frequency, 1, 'untouched video keeps its counts');
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('occurrence rows written before the seen_ms column still resolve their dates', () => {
+  const { db, dbPath } = createDb(
+    [
+      { session: 1, wordId: 20, dayOffset: 0 },
+      { session: 2, wordId: 20, dayOffset: 6 },
+    ],
+    { legacyRows: true },
+  );
+
+  try {
+    assert.equal(
+      (
+        db
+          .prepare('SELECT COUNT(*) AS total FROM imm_word_line_occurrences WHERE seen_ms IS NULL')
+          .get() as { total: number }
+      ).total,
+      2,
+      'precondition: rows carry no denormalised timestamp',
+    );
+
+    deleteSession(db, 1);
+
+    const word = readWord(db, 20);
+    assert.equal(word?.frequency, 1);
+    assert.equal(
+      word?.firstSeen,
+      Math.floor((BASE_MS + 6 * DAY_MS) / 1000),
+      'falls back to the subtitle line timestamp',
+    );
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('upgrading an older database backfills seen_ms from the subtitle lines', () => {
+  const { db, dbPath } = createDb(
+    [
+      { session: 1, wordId: 21, dayOffset: 0 },
+      { session: 2, wordId: 21, dayOffset: 2 },
+    ],
+    { legacyRows: true },
+  );
+
+  try {
+    // Re-run ensureSchema the way a pre-19 database would be opened.
+    db.exec('DELETE FROM imm_schema_version');
+    db.exec(`INSERT INTO imm_schema_version(schema_version, applied_at_ms) VALUES (18, '0')`);
+    ensureSchema(db);
+
+    const rows = db
+      .prepare('SELECT line_id AS lineId, seen_ms AS seenMs FROM imm_word_line_occurrences')
+      .all() as Array<{ lineId: number; seenMs: number | null }>;
+    assert.equal(rows.length, 2);
+    for (const row of rows) {
+      assert.ok(row.seenMs, `line ${row.lineId} should have a backfilled timestamp`);
+    }
+    assert.deepEqual(
+      rows.map((row) => row.seenMs).sort((a, b) => Number(a) - Number(b)),
+      [BASE_MS, BASE_MS + 2 * DAY_MS],
+    );
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
@@ -5,6 +5,7 @@ import path from 'node:path';
 import test from 'node:test';
 import { Database } from '../sqlite.js';
 import {
+  applyPragmas,
  createTrackerPreparedStatements,
  ensureSchema,
  getOrCreateAnimeRecord,
@@ -57,6 +58,16 @@ function makeDbPath(): string {
  return path.join(dir, 'immersion.sqlite');
 }

+// Match the runtime's SQLite tuning (WAL + synchronous=NORMAL). Without it these
+// tests run at SQLite's defaults, where every statement is its own fsync-ing
+// transaction; on slow CI disks that is enough to push insert-heavy cases past
+// the 5s per-test timeout.
+function openTestDb(dbPath: string) {
+  const db = new Database(dbPath);
+  applyPragmas(db);
+  return db;
+}
+
 function cleanupDbPath(dbPath: string): void {
  const dir = path.dirname(dbPath);
  if (!fs.existsSync(dir)) {
@@ -172,7 +183,7 @@ function withMockNowMs<T>(fixedDateMs: string | number, run: () => T): T {

 test('getSessionSummaries returns sessionId and canonicalTitle', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -231,7 +242,7 @@ test('getSessionSummaries returns sessionId and canonicalTitle', () => {

 test('getAnimeEpisodes prefers the latest session media position when the latest session is still active', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -299,7 +310,7 @@ test('getAnimeEpisodes prefers the latest session media position when the latest

 test('getAnimeEpisodes includes unwatched episodes for the anime', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -397,7 +408,7 @@ test('getAnimeEpisodes includes unwatched episodes for the anime', () => {

 test('getAnimeEpisodes falls back to the latest subtitle segment end when session progress checkpoints are missing', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -469,7 +480,7 @@ test('getAnimeEpisodes falls back to the latest subtitle segment end when sessio

 test('getAnimeEpisodes ignores zero-valued session checkpoints and falls back to subtitle progress', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -541,7 +552,7 @@ test('getAnimeEpisodes ignores zero-valued session checkpoints and falls back to

 test('getSessionTimeline returns the full session when no limit is provided', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -592,7 +603,7 @@ test('getSessionTimeline returns the full session when no limit is provided', ()

 test('getDailyRollups limits by distinct days (not rows)', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -625,7 +636,7 @@ test('getDailyRollups limits by distinct days (not rows)', () => {

 test('getTrendsDashboard returns chart-ready aggregated series', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -779,7 +790,7 @@ test('getTrendsDashboard returns chart-ready aggregated series', () => {

 test('getTrendsDashboard redacts legacy Jellyfin stream titles', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -869,7 +880,7 @@ test('getTrendsDashboard redacts legacy Jellyfin stream titles', () => {

 test('getTrendsDashboard keeps local-midnight session buckets separate', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1005,7 +1016,7 @@ test('getTrendsDashboard keeps local-midnight session buckets separate', () => {

 test('getTrendsDashboard 30d day range zero-fills empty calendar days', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);
  withMockNowMs('1772395200000', () => {
    try {
      ensureSchema(db);
@@ -1069,7 +1080,7 @@ test('getTrendsDashboard 30d day range zero-fills empty calendar days', () => {

 test('getTrendsDashboard skips empty calendar days when zero-fill is disabled', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);
  withMockNowMs('1772395200000', () => {
    try {
      ensureSchema(db);
@@ -1123,7 +1134,7 @@ test(
  { timeout: 20_000 },
  () => {
    const dbPath = makeDbPath();
-    const db = new Database(dbPath);
+    const db = openTestDb(dbPath);
    withMockNowMs('1772395200000', () => {
      try {
        ensureSchema(db);
@@ -1183,7 +1194,7 @@ test(

 test('getTrendsDashboard month grouping spans every touched calendar month and keeps progress monthly', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);
  withMockNowMs('1772395200000', () => {
    try {
      ensureSchema(db);
@@ -1406,7 +1417,7 @@ test('getTrendsDashboard month grouping spans every touched calendar month and k

 test('getQueryHints reads all-time totals from lifetime summary', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1476,7 +1487,7 @@ test('getQueryHints reads all-time totals from lifetime summary', () => {

 test('getQueryHints computes weekly new-word cutoff from calendar midnights', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  withMockNowMs('1773601200000', () => {
    try {
@@ -1528,7 +1539,7 @@ test('getQueryHints computes weekly new-word cutoff from calendar midnights', ()

 test('word-count read models use filtered persisted occurrences with raw fallback', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1611,7 +1622,7 @@ test('word-count read models use filtered persisted occurrences with raw fallbac

 test('rollups keep persisted totals when retained-session word counts are partial', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1672,7 +1683,7 @@ test('rollups keep persisted totals when retained-session word counts are partia

 test('getQueryHints counts new words by distinct headword first-seen time', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1737,7 +1748,7 @@ test('getQueryHints counts new words by distinct headword first-seen time', () =

 test('getSessionSummaries with no telemetry returns zero aggregates', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1771,7 +1782,7 @@ test('getSessionSummaries with no telemetry returns zero aggregates', () => {

 test('getSessionSummaries uses denormalized session metrics for ended sessions without telemetry', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1823,7 +1834,7 @@ test('getSessionSummaries uses denormalized session metrics for ended sessions w

 test('getVocabularyStats returns rows ordered by frequency descending', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1866,7 +1877,7 @@ test('getVocabularyStats returns rows ordered by frequency descending', () => {

 test('getVocabularyStats filters rows that fail tokenizer vocabulary rules', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1921,7 +1932,7 @@ test('getVocabularyStats filters rows that fail tokenizer vocabulary rules', ()

 test('getVocabularyStats pages past hidden rows until enough visible rows are collected', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1956,7 +1967,7 @@ test('getVocabularyStats pages past hidden rows until enough visible rows are co

 test('getVocabularyStats returns empty array when no words exist', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -1970,7 +1981,7 @@ test('getVocabularyStats returns empty array when no words exist', () => {

 test('cleanupVocabularyStats repairs stored POS metadata and removes excluded imm_words rows', async () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2100,7 +2111,7 @@ test('cleanupVocabularyStats repairs stored POS metadata and removes excluded im

 test('getDailyRollups returns all rows for the most recent rollup days', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);
  try {
    ensureSchema(db);
    const insertRollup = db.prepare(
@@ -2136,7 +2147,7 @@ test('getDailyRollups returns all rows for the most recent rollup days', () => {

 test('getMonthlyRollups returns all rows for the most recent rollup months', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);
  try {
    ensureSchema(db);
    const insertRollup = db.prepare(
@@ -2167,7 +2178,7 @@ test('getMonthlyRollups returns all rows for the most recent rollup months', ()

 test('getMonthlyRollups derives rate metrics from stored monthly totals', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);
  try {
    ensureSchema(db);
    const insertRollup = db.prepare(
@@ -2198,7 +2209,7 @@ test('getMonthlyRollups derives rate metrics from stored monthly totals', () =>

 test('getAnimeDailyRollups returns all rows for the most recent rollup days', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);
  try {
    ensureSchema(db);
    const insertRollup = db.prepare(
@@ -2254,7 +2265,7 @@ test('getAnimeDailyRollups returns all rows for the most recent rollup days', ()

 test('cleanupVocabularyStats merges repaired duplicates instead of violating the imm_words unique key', async () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2367,7 +2378,7 @@ test('cleanupVocabularyStats merges repaired duplicates instead of violating the

 test('getKanjiStats returns rows ordered by frequency descending', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2405,7 +2416,7 @@ test('getKanjiStats returns rows ordered by frequency descending', () => {

 test('getKanjiStats returns empty array when no kanji exist', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2419,7 +2430,7 @@ test('getKanjiStats returns empty array when no kanji exist', () => {

 test('getSessionEvents returns events ordered by ts_ms ascending', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2480,7 +2491,7 @@ test('getSessionEvents returns events ordered by ts_ms ascending', () => {

 test('getSessionEvents round-trips wall-clock timestamps written through event inserts', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2524,7 +2535,7 @@ test('getSessionEvents round-trips wall-clock timestamps written through event i

 test('getSessionEvents returns empty array for session with no events', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2547,7 +2558,7 @@ test('getSessionEvents returns empty array for session with no events', () => {

 test('getSessionEvents filters events to the requested session id', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2613,7 +2624,7 @@ test('getSessionEvents filters events to the requested session id', () => {

 test('getSessionEvents respects limit parameter', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2656,7 +2667,7 @@ test('getSessionEvents respects limit parameter', () => {

 test('getSessionEvents filters by event type before applying limit', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2728,7 +2739,7 @@ test('getSessionEvents filters by event type before applying limit', () => {

 test('getSessionWordsByLine joins word occurrences through imm_words.id', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -2803,7 +2814,7 @@ test('getSessionWordsByLine joins word occurrences through imm_words.id', () =>

 test('anime-level queries group by anime_id and preserve episode-level rows', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3083,7 +3094,7 @@ test('anime-level queries group by anime_id and preserve episode-level rows', ()

 test('anime library and detail still return lifetime rows without retained sessions', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3180,7 +3191,7 @@ test('anime library and detail still return lifetime rows without retained sessi

 test('anime and media detail prefer lifetime totals over partial retained sessions', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3270,7 +3281,7 @@ test('anime and media detail prefer lifetime totals over partial retained sessio

 test('media detail resolves retained sessions before lifetime summary exists', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3323,7 +3334,7 @@ test('media detail resolves retained sessions before lifetime summary exists', (

 test('media library and detail queries read lifetime totals', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3415,7 +3426,7 @@ test('media library and detail queries read lifetime totals', () => {

 test('media library and detail queries include joined youtube metadata when present', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3512,7 +3523,7 @@ test('media library and detail queries include joined youtube metadata when pres

 test('cover art queries reuse a shared blob across duplicate anime art rows', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3639,7 +3650,7 @@ test('cover art queries reuse a shared blob across duplicate anime art rows', ()

 test('upsertCoverArt prefers freshly fetched bytes over a reused shared hash', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3685,7 +3696,7 @@ test('upsertCoverArt prefers freshly fetched bytes over a reused shared hash', (

 test('anime/media detail and episode queries use ended-session metrics when telemetry rows are absent', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3827,7 +3838,7 @@ test('anime/media detail and episode queries use ended-session metrics when tele

 test('getWordOccurrences maps a normalized word back to anime, video, and subtitle line context', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3902,7 +3913,7 @@ test('getWordOccurrences maps a normalized word back to anime, video, and subtit

 test('searchSubtitleSentences searches known subtitle lines and returns media context', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -3999,7 +4010,7 @@ test('searchSubtitleSentences searches known subtitle lines and returns media co

 test('searchSubtitleSentences searches subtitle lines by resolved headword candidates', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4083,7 +4094,7 @@ test('searchSubtitleSentences searches subtitle lines by resolved headword candi

 test('getKanjiOccurrences maps a kanji back to anime, video, and subtitle line context', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4158,7 +4169,7 @@ test('getKanjiOccurrences maps a kanji back to anime, video, and subtitle line c

 test('deleteSession removes the session and all associated session-scoped rows', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4306,7 +4317,7 @@ test('deleteSession removes the session and all associated session-scoped rows',

 test('deleteSession rebuilds word and kanji aggregates from retained subtitle lines', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4462,7 +4473,7 @@ test('deleteSession rebuilds word and kanji aggregates from retained subtitle li

 test('deleteSession removes zero-session media from library and trends', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4667,7 +4678,7 @@ test('deleteSession removes zero-session media from library and trends', () => {

 test('getTrendsDashboard builds librarySummary with per-title aggregates', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4774,7 +4785,7 @@ test('getTrendsDashboard builds librarySummary with per-title aggregates', () =>

 test('getTrendsDashboard librarySummary returns null lookupsPerHundred when words is zero', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4856,7 +4867,7 @@ test('getTrendsDashboard librarySummary returns null lookupsPerHundred when word

 test('getTrendsDashboard rollup word metrics keep persisted totals over partial session counts', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4971,7 +4982,7 @@ test('getTrendsDashboard rollup word metrics keep persisted totals over partial

 test('getTrendsDashboard librarySummary is empty when no rollups exist', () => {
  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+  const db = openTestDb(dbPath);

  try {
    ensureSchema(db);
@@ -4982,3 +4993,145 @@ test('getTrendsDashboard librarySummary is empty when no rollups exist', () => {
    cleanupDbPath(dbPath);
  }
 });
+
+test('getVocabularyStats counts the distinct anime each word appeared in', () => {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+
+  try {
+    ensureSchema(db);
+    const startedAtMs = 1_700_000_000_000;
+    db.exec(`
+      INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
+        VALUES (11, 'vocab-a', 'Vocab A', ${startedAtMs}, ${startedAtMs}),
+               (22, 'vocab-b', 'Vocab B', ${startedAtMs}, ${startedAtMs});
+    `);
+    const videoIds = [1, 2].map((n) =>
+      getOrCreateVideoRecord(db, `local:/tmp/vocab-anime-${n}.mkv`, {
+        canonicalTitle: `Vocab Anime ${n}`,
+        sourcePath: `/tmp/vocab-anime-${n}.mkv`,
+        sourceUrl: null,
+        sourceType: SOURCE_TYPE_LOCAL,
+      }),
+    );
+    const sessionIds = videoIds.map(
+      (videoId) => startSessionRecord(db, videoId, startedAtMs).sessionId,
+    );
+
+    // 猫 spans both titles, twice in the first, so the count has to deduplicate
+    // by anime rather than just tallying occurrence rows. 犬 stays in one title.
+    insertFilteredWordOccurrence(db, {
+      sessionId: sessionIds[0]!,
+      videoId: videoIds[0]!,
+      animeId: 11,
+      lineIndex: 1,
+      occurrenceCount: 5,
+      startedAtMs,
+      word: '猫',
+      reading: 'ねこ',
+    });
+    insertFilteredWordOccurrence(db, {
+      sessionId: sessionIds[0]!,
+      videoId: videoIds[0]!,
+      animeId: 11,
+      lineIndex: 2,
+      occurrenceCount: 1,
+      startedAtMs,
+      word: '猫',
+      reading: 'ねこ',
+    });
+    insertFilteredWordOccurrence(db, {
+      sessionId: sessionIds[1]!,
+      videoId: videoIds[1]!,
+      animeId: 22,
+      lineIndex: 3,
+      occurrenceCount: 4,
+      startedAtMs,
+      word: '猫',
+      reading: 'ねこ',
+    });
+    insertFilteredWordOccurrence(db, {
+      sessionId: sessionIds[0]!,
+      videoId: videoIds[0]!,
+      animeId: 11,
+      lineIndex: 4,
+      occurrenceCount: 2,
+      startedAtMs,
+      word: '犬',
+      reading: 'いぬ',
+    });
+
+    const rows = getVocabularyStats(db, 10);
+    const cat = rows.find((row) => row.headword === '猫');
+    const dog = rows.find((row) => row.headword === '犬');
+
+    assert.equal(cat?.animeCount, 2, '猫 was seen in two anime across three lines');
+    assert.equal(dog?.animeCount, 1, '犬 was seen in one');
+    assert.equal(cat?.frequency, 10, 'frequency still aggregates across both titles');
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('getVocabularyStats still applies part-of-speech exclusions', () => {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+
+  try {
+    ensureSchema(db);
+    const startedAtMs = 1_700_000_000_000;
+    db.exec(`
+      INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
+        VALUES (11, 'vocab-a', 'Vocab A', ${startedAtMs}, ${startedAtMs});
+    `);
+    const videoId = getOrCreateVideoRecord(db, 'local:/tmp/vocab-exclude.mkv', {
+      canonicalTitle: 'Vocab Exclude',
+      sourcePath: '/tmp/vocab-exclude.mkv',
+      sourceUrl: null,
+      sourceType: SOURCE_TYPE_LOCAL,
+    });
+    const { sessionId } = startSessionRecord(db, videoId, startedAtMs);
+
+    insertFilteredWordOccurrence(db, {
+      sessionId,
+      videoId,
+      animeId: 11,
+      lineIndex: 1,
+      occurrenceCount: 9,
+      startedAtMs,
+      word: '走る',
+      reading: 'はしる',
+      partOfSpeech: 'verb',
+    });
+    insertFilteredWordOccurrence(db, {
+      sessionId,
+      videoId,
+      animeId: 11,
+      lineIndex: 2,
+      occurrenceCount: 3,
+      startedAtMs,
+      word: '猫',
+      reading: 'ねこ',
+      partOfSpeech: 'noun',
+    });
+
+    const all = getVocabularyStats(db, 10);
+    assert.deepEqual(
+      all.map((row) => row.headword).sort(),
+      ['猫', '走る'],
+      'precondition: both parts of speech are present',
+    );
+
+    const nounsOnly = getVocabularyStats(db, 10, ['verb']);
+    assert.deepEqual(
+      nounsOnly.map((row) => row.headword),
+      ['猫'],
+      'excluded part of speech is filtered out even though it ranks higher',
+    );
+    assert.equal(nounsOnly[0]?.animeCount, 1, 'surviving rows keep their anime count');
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
@@ -0,0 +1,169 @@
+import type { DatabaseSync } from './sqlite';
+import { animeSeasonsAreMergeCompatible, getParsedSeasonsForAnime } from './anime-merge';
+import { toDbTimestamp } from './query-shared';
+import { normalizeAnimeIdentityKey } from './storage';
+import { nowMs } from './time';
+
+export interface AnimeMergeRecommendation {
+  recommendationId: number;
+  animeIds: [number, number];
+}
+
+export interface AnimeConflictRecommendationOptions {
+  survivor?: 'target' | 'existing';
+  /** Automatic matches must be exact; manual assignment is authoritative. */
+  matchConfidence?: 'exact' | 'weak' | 'manual';
+}
+
+interface AnimeTitleRow {
+  canonical_title: string;
+  title_romaji: string | null;
+  title_english: string | null;
+  title_native: string | null;
+}
+
+function getAnimeTitles(db: DatabaseSync, animeId: number): AnimeTitleRow | null {
+  return db
+    .prepare(
+      `SELECT canonical_title, title_romaji, title_english, title_native
+       FROM imm_anime
+       WHERE anime_id = ?`,
+    )
+    .get(animeId) as AnimeTitleRow | null;
+}
+
+function getParsedTitles(db: DatabaseSync, animeId: number): Array<string | null> {
+  return (
+    db.prepare('SELECT parsed_title FROM imm_videos WHERE anime_id = ?').all(animeId) as Array<{
+      parsed_title: string | null;
+    }>
+  ).map((row) => row.parsed_title);
+}
+
+function stripSeasonIdentitySuffix(title: string): string {
+  return title
+    .replace(/\bseason\s*\d{1,2}\b/gi, ' ')
+    .replace(/\b\d{1,2}(?:st|nd|rd|th)\s+season\b/gi, ' ')
+    .replace(/\bs\d{1,2}\b/gi, ' ');
+}
+
+export function hasExactStoredTitleMatch(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  conflictAnimeId: number,
+): boolean {
+  const target = getAnimeTitles(db, targetAnimeId);
+  const conflict = getAnimeTitles(db, conflictAnimeId);
+  if (!target || !conflict) return false;
+  const targetKeys = [target.canonical_title, ...getParsedTitles(db, targetAnimeId)]
+    .filter((title): title is string => Boolean(title?.trim()))
+    .map((title) => normalizeAnimeIdentityKey(stripSeasonIdentitySuffix(title)))
+    .filter(Boolean);
+  const anilistTitleKeys = [
+    conflict.title_romaji,
+    conflict.title_english,
+    conflict.title_native,
+    conflict.canonical_title,
+  ]
+    .filter((title): title is string => Boolean(title?.trim()))
+    .map((title) => normalizeAnimeIdentityKey(stripSeasonIdentitySuffix(title)))
+    .filter(Boolean);
+  return targetKeys.some((key) => anilistTitleKeys.includes(key));
+}
+
+export function shouldRecommendAnilistConflict(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  conflictAnimeId: number,
+  options: AnimeConflictRecommendationOptions,
+): boolean {
+  if (options.survivor === 'target' || options.matchConfidence === 'manual') return false;
+  if (
+    !animeSeasonsAreMergeCompatible(
+      getParsedSeasonsForAnime(db, targetAnimeId),
+      getParsedSeasonsForAnime(db, conflictAnimeId),
+    )
+  ) {
+    return false;
+  }
+  return (
+    options.matchConfidence === 'weak' ||
+    (options.matchConfidence === undefined &&
+      !hasExactStoredTitleMatch(db, targetAnimeId, conflictAnimeId))
+  );
+}
+
+export function recordAnimeMergeRecommendation(
+  db: DatabaseSync,
+  firstCandidateAnimeId: number,
+  secondCandidateAnimeId: number,
+  anilistId: number,
+): void {
+  const firstAnimeId = Math.min(firstCandidateAnimeId, secondCandidateAnimeId);
+  const secondAnimeId = Math.max(firstCandidateAnimeId, secondCandidateAnimeId);
+  const timestamp = toDbTimestamp(nowMs());
+  db.prepare(
+    `INSERT INTO imm_anime_merge_recommendations(
+       first_anime_id, second_anime_id, anilist_id, status, CREATED_DATE, LAST_UPDATE_DATE
+     ) VALUES (?, ?, ?, 'pending', ?, ?)
+     ON CONFLICT(first_anime_id, second_anime_id, anilist_id) DO UPDATE SET
+       LAST_UPDATE_DATE = excluded.LAST_UPDATE_DATE`,
+  ).run(firstAnimeId, secondAnimeId, anilistId, timestamp, timestamp);
+}
+
+export function hasDismissedAnimeMergeRecommendation(
+  db: DatabaseSync,
+  firstCandidateAnimeId: number,
+  secondCandidateAnimeId: number,
+): boolean {
+  const firstAnimeId = Math.min(firstCandidateAnimeId, secondCandidateAnimeId);
+  const secondAnimeId = Math.max(firstCandidateAnimeId, secondCandidateAnimeId);
+  return Boolean(
+    db
+      .prepare(
+        `SELECT 1
+         FROM imm_anime_merge_recommendations
+         WHERE first_anime_id = ?
+           AND second_anime_id = ?
+           AND status = 'dismissed'
+         LIMIT 1`,
+      )
+      .get(firstAnimeId, secondAnimeId),
+  );
+}
+
+export function getAnimeMergeRecommendations(db: DatabaseSync): AnimeMergeRecommendation[] {
+  return (
+    db
+      .prepare(
+        `SELECT recommendation_id AS recommendationId,
+                first_anime_id AS firstAnimeId,
+                second_anime_id AS secondAnimeId
+         FROM imm_anime_merge_recommendations
+         WHERE status = 'pending'
+         ORDER BY recommendation_id ASC`,
+      )
+      .all() as Array<{
+      recommendationId: number;
+      firstAnimeId: number;
+      secondAnimeId: number;
+    }>
+  ).map((row) => ({
+    recommendationId: row.recommendationId,
+    animeIds: [row.firstAnimeId, row.secondAnimeId],
+  }));
+}
+
+export function dismissAnimeMergeRecommendation(
+  db: DatabaseSync,
+  recommendationId: number,
+): boolean {
+  const result = db
+    .prepare(
+      `UPDATE imm_anime_merge_recommendations
+       SET status = 'dismissed', LAST_UPDATE_DATE = ?
+       WHERE recommendation_id = ? AND status = 'pending'`,
+    )
+    .run(toDbTimestamp(nowMs()), recommendationId) as { changes: number };
+  return result.changes > 0;
+}
@@ -0,0 +1,292 @@
+import type { DatabaseSync } from './sqlite';
+import { rebuildLifetimeSummariesInTransaction } from './lifetime';
+import { toDbTimestamp } from './query-shared';
+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';
+
+export interface AnimeMergeSummary {
+  /** Library entry that owns every moved episode once the merge finishes. */
+  survivingAnimeId: number;
+  /** Entries that were folded into the survivor and deleted. */
+  mergedAnimeIds: number[];
+  movedVideos: number;
+}
+
+export interface VideoMoveSummary {
+  targetAnimeId: number;
+  /** Previous owner, or null when the episode had no library entry yet. */
+  previousAnimeId: number | null;
+  /** True when the previous owner was left empty and pruned. */
+  removedPreviousAnime: boolean;
+}
+
+interface AnimeMetadataRow {
+  normalized_title_key: string;
+  anilist_id: number | null;
+  title_romaji: string | null;
+  title_english: string | null;
+  title_native: string | null;
+  episodes_total: number | null;
+  description: string | null;
+}
+
+function emptyMergeSummary(survivingAnimeId: number): AnimeMergeSummary {
+  return { survivingAnimeId, mergedAnimeIds: [], movedVideos: 0 };
+}
+
+function runInTransaction<T>(db: DatabaseSync, work: () => T): T {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const result = work();
+    db.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+function readAnimeMetadata(db: DatabaseSync, animeId: number): AnimeMetadataRow | null {
+  return (db
+    .prepare(
+      `
+        SELECT normalized_title_key, anilist_id, title_romaji, title_english, title_native, episodes_total, description
+        FROM imm_anime
+        WHERE anime_id = ?
+      `,
+    )
+    .get(animeId) ?? null) as AnimeMetadataRow | null;
+}
+
+function animeExists(db: DatabaseSync, animeId: number): boolean {
+  return Boolean(db.prepare('SELECT 1 FROM imm_anime WHERE anime_id = ?').get(animeId));
+}
+
+function hasAnimeReferences(db: DatabaseSync, animeId: number): boolean {
+  const row = db
+    .prepare(
+      `
+        SELECT 1 AS found
+        WHERE EXISTS (SELECT 1 FROM imm_videos WHERE anime_id = ?)
+           OR EXISTS (SELECT 1 FROM imm_subtitle_lines WHERE anime_id = ?)
+      `,
+    )
+    .get(animeId, animeId) as { found: number } | null;
+  return Boolean(row);
+}
+
+/**
+ * Distinct explicit seasons behind a library entry. Videos with no parsed
+ * season are ignored, so an entry built from `Show - 03.mkv` style filenames
+ * reports an empty set rather than a bogus season.
+ */
+export function getParsedSeasonsForAnime(db: DatabaseSync, animeId: number): Set<number> {
+  const rows = db
+    .prepare(
+      `
+        SELECT DISTINCT parsed_season AS season
+        FROM imm_videos
+        WHERE anime_id = ?
+          AND parsed_season IS NOT NULL
+          AND parsed_season > 0
+      `,
+    )
+    .all(animeId) as Array<{ season: number }>;
+  return new Set(rows.map((row) => row.season));
+}
+
+/**
+ * Two entries are safe to fold together when neither spans more than one
+ * explicit season and they do not disagree about which season that is. A
+ * seasonless entry is compatible with anything single-season: those are the
+ * `Show - 03.mkv` vs `Show.S01E03.mkv` splits that produce duplicate cards.
+ */
+export function animeSeasonsAreMergeCompatible(a: Set<number>, b: Set<number>): boolean {
+  if (a.size > 1 || b.size > 1) return false;
+  if (a.size === 0 || b.size === 0) return true;
+  return [...a][0] === [...b][0];
+}
+
+/**
+ * Fill in whatever the target is missing from a source row that is on its way
+ * out. Must run after the source row is deleted: imm_anime.anilist_id is
+ * UNIQUE, so the two rows cannot hold the same id at once.
+ */
+function absorbAnimeMetadata(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  source: AnimeMetadataRow | null,
+  updatedAt: string,
+): void {
+  if (!source) return;
+  db.prepare(
+    `
+      UPDATE imm_anime
+      SET
+        anilist_id = COALESCE(anilist_id, ?),
+        title_romaji = COALESCE(title_romaji, ?),
+        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(
+    source.anilist_id,
+    source.title_romaji,
+    source.title_english,
+    source.title_native,
+    source.episodes_total,
+    source.description,
+    updatedAt,
+    targetAnimeId,
+  );
+}
+
+/**
+ * Fold `sourceAnimeIds` into `targetAnimeId`: every episode and subtitle line
+ * is repointed, metadata the target is missing is inherited from the sources,
+ * and the emptied source rows are deleted.
+ *
+ * Assumes the caller already holds a write transaction and rebuilds the
+ * lifetime summaries afterwards; use {@link mergeAnimeRecords} otherwise.
+ */
+export function mergeAnimeRecordsInTransaction(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  sourceAnimeIds: number[],
+): AnimeMergeSummary {
+  const summary = emptyMergeSummary(targetAnimeId);
+  if (!animeExists(db, targetAnimeId)) {
+    return summary;
+  }
+
+  const updatedAt = toDbTimestamp(nowMs());
+  const sourceVideosStmt = db.prepare(
+    'SELECT video_id AS videoId FROM imm_videos WHERE anime_id = ?',
+  );
+  const moveVideosStmt = db.prepare(
+    'UPDATE imm_videos SET anime_id = ?, LAST_UPDATE_DATE = ? WHERE anime_id = ?',
+  );
+  // Repointed per video rather than by anime_id: lines recorded before the
+  // async title parse assigns the link are stored with a NULL anime_id, and
+  // matching on the source id would strand them unattributed.
+  const moveLinesStmt = db.prepare(
+    'UPDATE imm_subtitle_lines SET anime_id = ?, LAST_UPDATE_DATE = ? WHERE video_id = ?',
+  );
+  const dropLifetimeStmt = db.prepare('DELETE FROM imm_lifetime_anime WHERE anime_id = ?');
+  const sourceAliasesStmt = db.prepare(
+    'SELECT normalized_title_key AS normalizedTitleKey FROM imm_anime_title_aliases WHERE anime_id = ?',
+  );
+  const upsertAliasStmt = db.prepare(
+    `INSERT INTO imm_anime_title_aliases(normalized_title_key, anime_id, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(normalized_title_key) DO UPDATE SET
+       anime_id = excluded.anime_id,
+       LAST_UPDATE_DATE = excluded.LAST_UPDATE_DATE`,
+  );
+  const dropSourceAliasesStmt = db.prepare(
+    'DELETE FROM imm_anime_title_aliases WHERE anime_id = ?',
+  );
+  const dropAnimeStmt = db.prepare('DELETE FROM imm_anime WHERE anime_id = ?');
+
+  for (const sourceAnimeId of new Set(sourceAnimeIds)) {
+    if (sourceAnimeId === targetAnimeId || !animeExists(db, sourceAnimeId)) {
+      continue;
+    }
+
+    const sourceMetadata = readAnimeMetadata(db, sourceAnimeId);
+    const sourceAliases = sourceAliasesStmt.all(sourceAnimeId) as Array<{
+      normalizedTitleKey: string;
+    }>;
+    const sourceVideoIds = (sourceVideosStmt.all(sourceAnimeId) as Array<{ videoId: number }>).map(
+      (row) => row.videoId,
+    );
+    const moved = moveVideosStmt.run(targetAnimeId, updatedAt, sourceAnimeId) as {
+      changes: number;
+    };
+    for (const videoId of sourceVideoIds) {
+      moveLinesStmt.run(targetAnimeId, updatedAt, videoId);
+    }
+    dropSourceAliasesStmt.run(sourceAnimeId);
+    for (const alias of [
+      ...(sourceMetadata ? [sourceMetadata.normalized_title_key] : []),
+      ...sourceAliases.map((row) => row.normalizedTitleKey),
+    ]) {
+      upsertAliasStmt.run(alias, targetAnimeId, updatedAt, updatedAt);
+    }
+    dropLifetimeStmt.run(sourceAnimeId);
+    dropAnimeStmt.run(sourceAnimeId);
+    absorbAnimeMetadata(db, targetAnimeId, sourceMetadata, updatedAt);
+
+    summary.mergedAnimeIds.push(sourceAnimeId);
+    summary.movedVideos += moved.changes;
+  }
+
+  return summary;
+}
+
+export function mergeAnimeRecords(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  sourceAnimeIds: number[],
+): AnimeMergeSummary {
+  return runInTransaction(db, () => {
+    const summary = mergeAnimeRecordsInTransaction(db, targetAnimeId, sourceAnimeIds);
+    if (summary.mergedAnimeIds.length > 0) {
+      rebuildLifetimeSummariesInTransaction(db);
+    }
+    return summary;
+  });
+}
+
+/**
+ * Move a single episode to another library entry, pruning the previous owner
+ * when it is left with nothing.
+ */
+export function moveVideoToAnime(
+  db: DatabaseSync,
+  videoId: number,
+  targetAnimeId: number,
+): VideoMoveSummary {
+  return runInTransaction(db, () => {
+    const videoRow = db
+      .prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = ?')
+      .get(videoId) as { animeId: number | null } | null;
+    if (!videoRow || !animeExists(db, targetAnimeId)) {
+      throw new Error(UNKNOWN_MOVE_TARGET_MESSAGE);
+    }
+
+    const previousAnimeId = videoRow.animeId;
+    if (previousAnimeId === targetAnimeId) {
+      return { targetAnimeId, previousAnimeId, removedPreviousAnime: false };
+    }
+
+    const updatedAt = toDbTimestamp(nowMs());
+    db.prepare('UPDATE imm_videos SET anime_id = ?, LAST_UPDATE_DATE = ? WHERE video_id = ?').run(
+      targetAnimeId,
+      updatedAt,
+      videoId,
+    );
+    db.prepare(
+      'UPDATE imm_subtitle_lines SET anime_id = ?, LAST_UPDATE_DATE = ? WHERE video_id = ?',
+    ).run(targetAnimeId, updatedAt, videoId);
+
+    let removedPreviousAnime = false;
+    if (previousAnimeId !== null && !hasAnimeReferences(db, previousAnimeId)) {
+      // The emptied entry's metadata is deliberately dropped rather than
+      // absorbed. A move says "this episode belongs elsewhere", not "these are
+      // the same show", and the entry being emptied is usually a mis-parse
+      // whose AniList link would be wrong for the target.
+      db.prepare('DELETE FROM imm_lifetime_anime WHERE anime_id = ?').run(previousAnimeId);
+      db.prepare('DELETE FROM imm_anime WHERE anime_id = ?').run(previousAnimeId);
+      removedPreviousAnime = true;
+    }
+
+    rebuildLifetimeSummariesInTransaction(db);
+    return { targetAnimeId, previousAnimeId, removedPreviousAnime };
+  });
+}
@@ -1,4 +1,16 @@
 import type { DatabaseSync } from './sqlite';
+import {
+  animeSeasonsAreMergeCompatible,
+  getParsedSeasonsForAnime,
+  mergeAnimeRecordsInTransaction,
+} from './anime-merge';
+import {
+  hasExactStoredTitleMatch,
+  hasDismissedAnimeMergeRecommendation,
+  recordAnimeMergeRecommendation,
+  shouldRecommendAnilistConflict,
+  type AnimeConflictRecommendationOptions,
+} from './anime-merge-recommendations';
 import { getOrCreateAnimeRecord } from './storage';
 import { toDbTimestamp } from './query-shared';
 import { nowMs } from './time';
@@ -8,8 +20,33 @@ export interface AnimeSeasonRepairSummary {
  repaired: number;
  movedVideos: number;
  deletedAnimeRows: number;
+  /**
+   * Entry that owns the videos afterwards when two rows were folded together,
+   * so callers can keep pointing at a row that still exists.
+   */
+  survivingAnimeId: number | null;
+  /** True when an ambiguous AniList collision was saved for user review. */
+  mergeRecommended: boolean;
+  /** True when automatic metadata must not assign the colliding AniList id. */
+  anilistAssignmentBlocked: boolean;
 }

+export interface AnimeAnilistConflictOptions extends AnimeConflictRecommendationOptions {
+  /**
+   * Which row keeps its identity when two entries claim the same AniList id.
+   * `existing` (the default) keeps the row that already held the id, so
+   * automatic cover-art resolution does not rename a card under the user;
+   * `target` keeps the row the user is acting on.
+   */
+  survivor?: 'target' | 'existing';
+}
+
+export {
+  dismissAnimeMergeRecommendation,
+  getAnimeMergeRecommendations,
+  type AnimeMergeRecommendation,
+} from './anime-merge-recommendations';
+
 interface AnimeRow {
  anime_id: number;
  anilist_id: number | null;
@@ -38,6 +75,9 @@ function emptySummary(scanned = 0): AnimeSeasonRepairSummary {
    repaired: 0,
    movedVideos: 0,
    deletedAnimeRows: 0,
+    survivingAnimeId: null,
+    mergeRecommended: false,
+    anilistAssignmentBlocked: false,
  };
 }

@@ -49,6 +89,9 @@ function mergeSummary(
  target.repaired += source.repaired;
  target.movedVideos += source.movedVideos;
  target.deletedAnimeRows += source.deletedAnimeRows;
+  target.survivingAnimeId = source.survivingAnimeId ?? target.survivingAnimeId;
+  target.mergeRecommended ||= source.mergeRecommended;
+  target.anilistAssignmentBlocked ||= source.anilistAssignmentBlocked;
  return target;
 }

@@ -301,10 +344,18 @@ export function repairLegacySeasonlessAnimeRows(db: DatabaseSync): AnimeSeasonRe
  });
 }

+/**
+ * Two library entries cannot both hold the same AniList id
+ * (`imm_anime.anilist_id` is UNIQUE). Fold an automatic collision only when
+ * exact title evidence and compatible parsed seasons make it safe. Persist a
+ * review recommendation for compatible weak matches. Fall back to legacy
+ * season redistribution when the conflicting row spans several seasons.
+ */
 export function resolveAnimeAnilistConflict(
  db: DatabaseSync,
  targetAnimeId: number,
  anilistId: number,
+  options: AnimeAnilistConflictOptions = {},
 ): AnimeSeasonRepairSummary {
  const conflict = db
    .prepare(
@@ -321,10 +372,96 @@ export function resolveAnimeAnilistConflict(
    return emptySummary();
  }

-  return runInTransaction(db, () =>
-    redistributeAnimeRowByParsedSeasonsInTransaction(db, conflict.animeId, {
+  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.
+      return emptySummary(1);
+    }
+    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;
+      }
+      // 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)) {
+      recordAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId, anilistId);
+      const summary = emptySummary(1);
+      summary.mergeRecommended = true;
+      return summary;
+    }
+
+    return redistributeAnimeRowByParsedSeasonsInTransaction(db, conflict.animeId, {
      transferAnilistToAnimeId: targetAnimeId,
      overwriteTargetAnilist: true,
-    }),
+    });
+  });
+}
+
+function canMergeAnilistConflict(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  conflictAnimeId: number,
+  anilistId: number,
+  options: AnimeAnilistConflictOptions,
+): boolean {
+  const targetRow = getAnimeRow(db, targetAnimeId);
+  if (!targetRow) {
+    // Nothing to merge with a row that no longer exists (a stale id from the
+    // caller); fall through to the redistribution path.
+    return false;
+  }
+  if (options.survivor !== 'target') {
+    // The target is the row about to disappear here, so an existing link of its
+    // own means this is a mis-resolution rather than a duplicate: leave it be.
+    if (targetRow.anilist_id != null && targetRow.anilist_id !== anilistId) {
+      return false;
+    }
+  }
+  if (
+    options.matchConfidence === 'weak' ||
+    (options.matchConfidence === undefined &&
+      !hasExactStoredTitleMatch(db, targetAnimeId, conflictAnimeId))
+  ) {
+    return false;
+  }
+  return animeSeasonsAreMergeCompatible(
+    getParsedSeasonsForAnime(db, targetAnimeId),
+    getParsedSeasonsForAnime(db, conflictAnimeId),
  );
 }
@@ -115,18 +115,29 @@ export function getVocabularyStats(
  const whereClause = hasExclude
    ? `WHERE (part_of_speech IS NULL OR part_of_speech NOT IN (${placeholders}))`
    : '';
+  // The page is selected before the join so `animeCount` is only computed for the
+  // rows being returned. Aggregating first made every request walk each word's
+  // entire occurrence history — seconds of blocked event loop on a large library,
+  // because only the ordering, not the aggregate, decides which rows survive.
  const stmt = db.prepare(`
-    SELECT w.id AS wordId, w.headword, w.word, w.reading,
-      w.part_of_speech AS partOfSpeech, w.pos1, w.pos2, w.pos3,
-      w.frequency, w.frequency_rank AS frequencyRank,
-      w.first_seen AS firstSeen, w.last_seen AS lastSeen,
+    WITH page AS (
+      SELECT id, headword, word, reading, part_of_speech, pos1, pos2, pos3,
+             frequency, frequency_rank, first_seen, last_seen
+      FROM imm_words
+      ${whereClause}
+      ORDER BY frequency DESC, id
+      LIMIT ? OFFSET ?
+    )
+    SELECT p.id AS wordId, p.headword, p.word, p.reading,
+      p.part_of_speech AS partOfSpeech, p.pos1, p.pos2, p.pos3,
+      p.frequency, p.frequency_rank AS frequencyRank,
+      p.first_seen AS firstSeen, p.last_seen AS lastSeen,
      COUNT(DISTINCT sl.anime_id) AS animeCount
-    FROM imm_words w
-    LEFT JOIN imm_word_line_occurrences o ON o.word_id = w.id
+    FROM page p
+    LEFT JOIN imm_word_line_occurrences o ON o.word_id = p.id
    LEFT JOIN imm_subtitle_lines sl ON sl.line_id = o.line_id AND sl.anime_id IS NOT NULL
-    ${whereClause ? whereClause.replace('part_of_speech', 'w.part_of_speech') : ''}
-    GROUP BY w.id
-    ORDER BY w.frequency DESC LIMIT ? OFFSET ?
+    GROUP BY p.id
+    ORDER BY p.frequency DESC, p.id
  `);
  const visibleRows: VocabularyStatsRow[] = [];
  let offset = 0;
@@ -9,14 +9,12 @@ import { PartOfSpeech, type MergedToken } from '../../../types';
 import { shouldExcludeTokenFromVocabularyPersistence } from '../tokenizer/annotation-stage';
 import { deriveStoredPartOfSpeech } from '../tokenizer/part-of-speech';
 import {
+  applyLexicalRemovals,
  cleanupUnusedCoverArtBlobHash,
  deleteSessionsByIds,
  findSharedCoverBlobHash,
-  getAffectedKanjiIdsForSessions,
-  getAffectedKanjiIdsForVideo,
-  getAffectedWordIdsForSessions,
-  getAffectedWordIdsForVideo,
-  refreshLexicalAggregates,
+  planLexicalRemovalsForSessions,
+  planLexicalRemovalsForVideos,
  toDbMs,
  toDbTimestamp,
 } from './query-shared';
@@ -232,12 +230,13 @@ export async function cleanupVocabularyStats(
     WHERE id = ?`,
  );
  const moveOccurrencesStmt = db.prepare(
-    `INSERT INTO imm_word_line_occurrences (line_id, word_id, occurrence_count)
-     SELECT line_id, ?, occurrence_count
+    `INSERT INTO imm_word_line_occurrences (line_id, word_id, occurrence_count, seen_ms)
+     SELECT line_id, ?, occurrence_count, seen_ms
     FROM imm_word_line_occurrences
     WHERE word_id = ?
     ON CONFLICT(line_id, word_id) DO UPDATE SET
-       occurrence_count = imm_word_line_occurrences.occurrence_count + excluded.occurrence_count`,
+       occurrence_count = imm_word_line_occurrences.occurrence_count + excluded.occurrence_count,
+       seen_ms = COALESCE(imm_word_line_occurrences.seen_ms, excluded.seen_ms)`,
  );
  const deleteOccurrencesStmt = db.prepare(
    'DELETE FROM imm_word_line_occurrences WHERE word_id = ?',
@@ -419,6 +418,7 @@ export function updateAnimeAnilistInfo(
    titleEnglish: string | null;
    titleNative: string | null;
    episodesTotal: number | null;
+    exactTitleMatch?: boolean;
  },
 ): void {
  const row = db.prepare('SELECT anime_id FROM imm_videos WHERE video_id = ?').get(videoId) as {
@@ -426,7 +426,11 @@ export function updateAnimeAnilistInfo(
  } | null;
  if (!row?.anime_id) return;

-  const repair = resolveAnimeAnilistConflict(db, row.anime_id, info.anilistId);
+  const repair = resolveAnimeAnilistConflict(db, row.anime_id, info.anilistId, {
+    matchConfidence:
+      info.exactTitleMatch === true ? 'exact' : info.exactTitleMatch === false ? 'weak' : undefined,
+  });
+  if (repair.mergeRecommended || repair.anilistAssignmentBlocked) return;
  const targetRow = db
    .prepare('SELECT anime_id FROM imm_videos WHERE video_id = ?')
    .get(videoId) as {
@@ -484,14 +488,16 @@ export function isVideoWatched(db: DatabaseSync, videoId: number): boolean {

 export function deleteSession(db: DatabaseSync, sessionId: number): void {
  const sessionIds = [sessionId];
-  const affectedWordIds = getAffectedWordIdsForSessions(db, sessionIds);
-  const affectedKanjiIds = getAffectedKanjiIdsForSessions(db, sessionIds);
-  const affectedRollupGroups = getRollupGroupsForSessions(db, sessionIds);

  db.exec('BEGIN IMMEDIATE');
  try {
+    // Measured inside the write lock: the plan records what the delete removes,
+    // and applying a plan taken against a different snapshot would subtract the
+    // wrong totals from imm_words/imm_kanji.
+    const lexicalRemovals = planLexicalRemovalsForSessions(db, sessionIds);
+    const affectedRollupGroups = getRollupGroupsForSessions(db, sessionIds);
    deleteSessionsByIds(db, sessionIds);
-    refreshLexicalAggregates(db, affectedWordIds, affectedKanjiIds);
+    applyLexicalRemovals(db, lexicalRemovals);
    rebuildLifetimeSummariesInTransaction(db);
    refreshRollupsForGroupsInTransaction(db, affectedRollupGroups);
    db.exec('COMMIT');
@@ -503,14 +509,13 @@ export function deleteSession(db: DatabaseSync, sessionId: number): void {

 export function deleteSessions(db: DatabaseSync, sessionIds: number[]): void {
  if (sessionIds.length === 0) return;
-  const affectedWordIds = getAffectedWordIdsForSessions(db, sessionIds);
-  const affectedKanjiIds = getAffectedKanjiIdsForSessions(db, sessionIds);
-  const affectedRollupGroups = getRollupGroupsForSessions(db, sessionIds);

  db.exec('BEGIN IMMEDIATE');
  try {
+    const lexicalRemovals = planLexicalRemovalsForSessions(db, sessionIds);
+    const affectedRollupGroups = getRollupGroupsForSessions(db, sessionIds);
    deleteSessionsByIds(db, sessionIds);
-    refreshLexicalAggregates(db, affectedWordIds, affectedKanjiIds);
+    applyLexicalRemovals(db, lexicalRemovals);
    rebuildLifetimeSummariesInTransaction(db);
    refreshRollupsForGroupsInTransaction(db, affectedRollupGroups);
    db.exec('COMMIT');
@@ -520,7 +525,69 @@ export function deleteSessions(db: DatabaseSync, sessionIds: number[]): void {
  }
 }

+/**
+ * Delete an entire library entry: every episode of the anime, all of their
+ * sessions and derived stats, and the anime row itself.
+ *
+ * Mirrors {@link deleteVideo} per episode, but batches the lexical refresh and
+ * lifetime rebuild into a single transaction so a multi-episode title doesn't
+ * pay for one full rebuild per episode.
+ */
+export function deleteAnime(db: DatabaseSync, animeId: number): void {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const videoIds = (
+      db.prepare('SELECT video_id FROM imm_videos WHERE anime_id = ?').all(animeId) as Array<{
+        video_id: number;
+      }>
+    ).map((row) => row.video_id);
+
+    const lexicalRemovals = planLexicalRemovalsForVideos(db, videoIds);
+    const coverBlobHashes: string[] = [];
+    const sessionIds: number[] = [];
+    for (const videoId of videoIds) {
+      const artRow = db
+        .prepare('SELECT cover_blob_hash AS coverBlobHash FROM imm_media_art WHERE video_id = ?')
+        .get(videoId) as { coverBlobHash: string | null } | undefined;
+      if (artRow?.coverBlobHash) {
+        coverBlobHashes.push(artRow.coverBlobHash);
+      }
+      const sessions = db
+        .prepare('SELECT session_id FROM imm_sessions WHERE video_id = ?')
+        .all(videoId) as Array<{ session_id: number }>;
+      sessionIds.push(...sessions.map((session) => session.session_id));
+    }
+
+    deleteSessionsByIds(db, sessionIds);
+    const deleteLinesStmt = db.prepare('DELETE FROM imm_subtitle_lines WHERE video_id = ?');
+    const deleteDailyStmt = db.prepare('DELETE FROM imm_daily_rollups WHERE video_id = ?');
+    const deleteMonthlyStmt = db.prepare('DELETE FROM imm_monthly_rollups WHERE video_id = ?');
+    const deleteArtStmt = db.prepare('DELETE FROM imm_media_art WHERE video_id = ?');
+    const deleteVideoStmt = db.prepare('DELETE FROM imm_videos WHERE video_id = ?');
+    for (const videoId of videoIds) {
+      deleteLinesStmt.run(videoId);
+      deleteDailyStmt.run(videoId);
+      deleteMonthlyStmt.run(videoId);
+      deleteArtStmt.run(videoId);
+      deleteVideoStmt.run(videoId);
+    }
+    for (const coverBlobHash of new Set(coverBlobHashes)) {
+      cleanupUnusedCoverArtBlobHash(db, coverBlobHash);
+    }
+    db.prepare('DELETE FROM imm_lifetime_anime WHERE anime_id = ?').run(animeId);
+    db.prepare('DELETE FROM imm_anime WHERE anime_id = ?').run(animeId);
+    applyLexicalRemovals(db, lexicalRemovals);
+    rebuildLifetimeSummariesInTransaction(db);
+    db.exec('COMMIT');
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
 export function deleteVideo(db: DatabaseSync, videoId: number): void {
+  db.exec('BEGIN IMMEDIATE');
+  try {
    const artRow = db
      .prepare(
        `
@@ -530,14 +597,11 @@ export function deleteVideo(db: DatabaseSync, videoId: number): void {
      `,
      )
      .get(videoId) as { coverBlobHash: string | null } | undefined;
-  const affectedWordIds = getAffectedWordIdsForVideo(db, videoId);
-  const affectedKanjiIds = getAffectedKanjiIdsForVideo(db, videoId);
+    const lexicalRemovals = planLexicalRemovalsForVideos(db, [videoId]);
    const sessions = db
      .prepare('SELECT session_id FROM imm_sessions WHERE video_id = ?')
      .all(videoId) as Array<{ session_id: number }>;

-  db.exec('BEGIN IMMEDIATE');
-  try {
    deleteSessionsByIds(
      db,
      sessions.map((session) => session.session_id),
@@ -548,7 +612,7 @@ export function deleteVideo(db: DatabaseSync, videoId: number): void {
    db.prepare('DELETE FROM imm_media_art WHERE video_id = ?').run(videoId);
    cleanupUnusedCoverArtBlobHash(db, artRow?.coverBlobHash ?? null);
    db.prepare('DELETE FROM imm_videos WHERE video_id = ?').run(videoId);
-    refreshLexicalAggregates(db, affectedWordIds, affectedKanjiIds);
+    applyLexicalRemovals(db, lexicalRemovals);
    rebuildLifetimeSummariesInTransaction(db);
    db.exec('COMMIT');
  } catch (error) {
@@ -203,6 +203,167 @@ export function getAffectedKanjiIdsForVideo(db: DatabaseSync, videoId: number):
  return getAffectedIdsForVideo(db, 'kanji', videoId);
 }

+/** Per-entity totals that a pending delete is about to remove. */
+interface LexicalRemoval {
+  id: number;
+  removedFrequency: number;
+  removedFirstSeenMs: number | null;
+  removedLastSeenMs: number | null;
+}
+
+/** What a pending delete removes from `imm_words` and `imm_kanji`. */
+export interface LexicalRemovalPlan {
+  words: LexicalRemoval[];
+  kanji: LexicalRemoval[];
+}
+
+export const EMPTY_LEXICAL_REMOVAL_PLAN: LexicalRemovalPlan = { words: [], kanji: [] };
+
+function collectLexicalRemovals(
+  db: DatabaseSync,
+  entity: LexicalEntity,
+  lineScopeSql: string,
+  params: number[],
+): LexicalRemoval[] {
+  const table = entity === 'word' ? 'imm_word_line_occurrences' : 'imm_kanji_line_occurrences';
+  const col = `${entity}_id`;
+  return db
+    .prepare(
+      `SELECT
+         o.${col} AS id,
+         COALESCE(SUM(o.occurrence_count), 0) AS removedFrequency,
+         MIN(COALESCE(o.seen_ms, sl.CREATED_DATE, sl.LAST_UPDATE_DATE)) AS removedFirstSeenMs,
+         MAX(COALESCE(o.seen_ms, sl.LAST_UPDATE_DATE, sl.CREATED_DATE)) AS removedLastSeenMs
+       FROM imm_subtitle_lines sl
+       JOIN ${table} o ON o.line_id = sl.line_id
+       WHERE ${lineScopeSql}
+       GROUP BY o.${col}`,
+    )
+    .all(...params) as LexicalRemoval[];
+}
+
+function planLexicalRemovals(
+  db: DatabaseSync,
+  lineScopeSql: string,
+  params: number[],
+): LexicalRemovalPlan {
+  return {
+    words: collectLexicalRemovals(db, 'word', lineScopeSql, params),
+    kanji: collectLexicalRemovals(db, 'kanji', lineScopeSql, params),
+  };
+}
+
+/**
+ * Measure what deleting these sessions removes from the vocabulary tables.
+ *
+ * Must run before the rows are deleted. Reads only the subtitle lines in scope,
+ * unlike {@link refreshLexicalAggregates}, which re-reads every occurrence of
+ * every affected word across the whole library.
+ */
+export function planLexicalRemovalsForSessions(
+  db: DatabaseSync,
+  sessionIds: number[],
+): LexicalRemovalPlan {
+  if (sessionIds.length === 0) return EMPTY_LEXICAL_REMOVAL_PLAN;
+  return planLexicalRemovals(db, `sl.session_id IN (${makePlaceholders(sessionIds)})`, sessionIds);
+}
+
+/** Measure what deleting these videos removes from the vocabulary tables. */
+export function planLexicalRemovalsForVideos(
+  db: DatabaseSync,
+  videoIds: number[],
+): LexicalRemovalPlan {
+  if (videoIds.length === 0) return EMPTY_LEXICAL_REMOVAL_PLAN;
+  return planLexicalRemovals(db, `sl.video_id IN (${makePlaceholders(videoIds)})`, videoIds);
+}
+
+function toStoredSeenSeconds(ms: number | null): number | null {
+  if (ms === null || !Number.isFinite(ms)) return null;
+  return Math.floor(ms / 1000);
+}
+
+/**
+ * Apply a removal plan to the vocabulary aggregates.
+ *
+ * Frequencies are adjusted by subtraction, which is exact and touches only the
+ * affected rows. `first_seen`/`last_seen` only need a rescan when the removed
+ * lines held the current extreme, and rows whose frequency reaches zero are
+ * verified against the surviving occurrences before deletion — so stored counts
+ * that have drifted still converge on the truth instead of dropping a live row.
+ */
+export function applyLexicalRemovals(db: DatabaseSync, plan: LexicalRemovalPlan): void {
+  applyRemovalsForEntity(db, 'word', plan.words);
+  applyRemovalsForEntity(db, 'kanji', plan.kanji);
+}
+
+function applyRemovalsForEntity(
+  db: DatabaseSync,
+  entity: LexicalEntity,
+  removals: LexicalRemoval[],
+): void {
+  if (removals.length === 0) return;
+
+  const entityTable = entity === 'word' ? 'imm_words' : 'imm_kanji';
+  const occurrenceTable =
+    entity === 'word' ? 'imm_word_line_occurrences' : 'imm_kanji_line_occurrences';
+  const col = `${entity}_id`;
+
+  const selectStmt = db.prepare(
+    `SELECT frequency, first_seen AS firstSeen, last_seen AS lastSeen
+     FROM ${entityTable}
+     WHERE id = ?`,
+  );
+  const updateFrequencyStmt = db.prepare(`UPDATE ${entityTable} SET frequency = ? WHERE id = ?`);
+  const hasOccurrencesStmt = db.prepare(
+    `SELECT 1 AS found FROM ${occurrenceTable} WHERE ${col} = ? LIMIT 1`,
+  );
+  const deleteStmt = db.prepare(`DELETE FROM ${entityTable} WHERE id = ?`);
+
+  const needsExactRefresh: number[] = [];
+
+  for (const removal of removals) {
+    const current = selectStmt.get(removal.id) as {
+      frequency: number | null;
+      firstSeen: number | null;
+      lastSeen: number | null;
+    } | null;
+    if (!current) continue;
+
+    const nextFrequency = (current.frequency ?? 0) - removal.removedFrequency;
+    if (nextFrequency <= 0) {
+      // The rows in scope are already gone by now, so anything still pointing at
+      // this entity means the stored frequency was stale rather than exhausted.
+      if (hasOccurrencesStmt.get(removal.id)) {
+        needsExactRefresh.push(removal.id);
+      } else {
+        deleteStmt.run(removal.id);
+      }
+      continue;
+    }
+
+    const removedFirstSeen = toStoredSeenSeconds(removal.removedFirstSeenMs);
+    const removedLastSeen = toStoredSeenSeconds(removal.removedLastSeenMs);
+    const firstSeenMayHaveMoved =
+      current.firstSeen === null ||
+      (removedFirstSeen !== null && removedFirstSeen <= current.firstSeen);
+    const lastSeenMayHaveMoved =
+      current.lastSeen === null ||
+      (removedLastSeen !== null && removedLastSeen >= current.lastSeen);
+    if (firstSeenMayHaveMoved || lastSeenMayHaveMoved) {
+      needsExactRefresh.push(removal.id);
+      continue;
+    }
+
+    updateFrequencyStmt.run(nextFrequency, removal.id);
+  }
+
+  if (entity === 'word') {
+    refreshWordAggregates(db, needsExactRefresh);
+  } else {
+    refreshKanjiAggregates(db, needsExactRefresh);
+  }
+}
+
 function refreshWordAggregates(db: DatabaseSync, wordIds: number[]): void {
  if (wordIds.length === 0) {
    return;
@@ -214,11 +375,18 @@ function refreshWordAggregates(db: DatabaseSync, wordIds: number[]): void {
        SELECT
          w.id AS wordId,
          COALESCE(SUM(o.occurrence_count), 0) AS frequency,
-          MIN(COALESCE(sl.CREATED_DATE, sl.LAST_UPDATE_DATE)) AS firstSeen,
-          MAX(COALESCE(sl.LAST_UPDATE_DATE, sl.CREATED_DATE)) AS lastSeen
+          MIN(COALESCE(o.seen_ms, (
+            SELECT COALESCE(sl.CREATED_DATE, sl.LAST_UPDATE_DATE)
+            FROM imm_subtitle_lines sl
+            WHERE sl.line_id = o.line_id
+          ))) AS firstSeen,
+          MAX(COALESCE(o.seen_ms, (
+            SELECT COALESCE(sl.CREATED_DATE, sl.LAST_UPDATE_DATE)
+            FROM imm_subtitle_lines sl
+            WHERE sl.line_id = o.line_id
+          ))) AS lastSeen
        FROM imm_words w
        LEFT JOIN imm_word_line_occurrences o ON o.word_id = w.id
-        LEFT JOIN imm_subtitle_lines sl ON sl.line_id = o.line_id
        WHERE w.id IN (${makePlaceholders(wordIds)})
        GROUP BY w.id
      `,
@@ -263,11 +431,18 @@ function refreshKanjiAggregates(db: DatabaseSync, kanjiIds: number[]): void {
        SELECT
          k.id AS kanjiId,
          COALESCE(SUM(o.occurrence_count), 0) AS frequency,
-          MIN(COALESCE(sl.CREATED_DATE, sl.LAST_UPDATE_DATE)) AS firstSeen,
-          MAX(COALESCE(sl.LAST_UPDATE_DATE, sl.CREATED_DATE)) AS lastSeen
+          MIN(COALESCE(o.seen_ms, (
+            SELECT COALESCE(sl.CREATED_DATE, sl.LAST_UPDATE_DATE)
+            FROM imm_subtitle_lines sl
+            WHERE sl.line_id = o.line_id
+          ))) AS firstSeen,
+          MAX(COALESCE(o.seen_ms, (
+            SELECT COALESCE(sl.CREATED_DATE, sl.LAST_UPDATE_DATE)
+            FROM imm_subtitle_lines sl
+            WHERE sl.line_id = o.line_id
+          ))) AS lastSeen
        FROM imm_kanji k
        LEFT JOIN imm_kanji_line_occurrences o ON o.kanji_id = k.id
-        LEFT JOIN imm_subtitle_lines sl ON sl.line_id = o.line_id
        WHERE k.id IN (${makePlaceholders(kanjiIds)})
        GROUP BY k.id
      `,
@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { parseMediaInfo } from '../../../jimaku/utils';
+import { normalizeTitleIdentity } from '../../utils/title-normalization';
 import type { DatabaseSync } from './sqlite';
 import { nowMs } from './time';
 import { SCHEMA_VERSION } from './types';
@@ -192,6 +193,33 @@ function addColumnIfMissing(
  }
 }

+/**
+ * Copy each subtitle line's timestamp onto its word/kanji occurrence rows.
+ *
+ * Vocabulary aggregates used to be recomputed by joining every occurrence back
+ * to `imm_subtitle_lines` just to read two timestamps, which meant one random
+ * read into the widest table per occurrence — the reason deleting a session cost
+ * seconds on a large library. With the timestamp stored alongside the count, the
+ * covering index answers those aggregates on its own.
+ */
+function backfillLexicalOccurrenceSeenMs(db: DatabaseSync): void {
+  for (const table of ['imm_word_line_occurrences', 'imm_kanji_line_occurrences']) {
+    addColumnIfMissing(db, table, 'seen_ms', 'INTEGER');
+    db.exec(`
+      UPDATE ${table}
+      SET seen_ms = (
+        SELECT COALESCE(sl.CREATED_DATE, sl.LAST_UPDATE_DATE)
+        FROM imm_subtitle_lines sl
+        WHERE sl.line_id = ${table}.line_id
+      )
+      WHERE seen_ms IS NULL
+    `);
+  }
+  // Superseded by the covering (entity, seen_ms, occurrence_count, line_id) indexes.
+  db.exec('DROP INDEX IF EXISTS idx_word_line_occurrences_word');
+  db.exec('DROP INDEX IF EXISTS idx_kanji_line_occurrences_kanji');
+}
+
 function dropColumnIfExists(db: DatabaseSync, tableName: string, columnName: string): void {
  if (hasColumn(db, tableName, columnName)) {
    db.exec(`ALTER TABLE ${tableName} DROP COLUMN ${columnName}`);
@@ -292,14 +320,7 @@ export function applyPragmas(db: DatabaseSync): void {
  db.exec(`PRAGMA journal_size_limit = ${WAL_JOURNAL_SIZE_LIMIT_BYTES}`);
 }

-export function normalizeAnimeIdentityKey(title: string): string {
-  return title
-    .normalize('NFKC')
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}]+/gu, ' ')
-    .trim()
-    .replace(/\s+/g, ' ');
-}
+export const normalizeAnimeIdentityKey = normalizeTitleIdentity;

 function normalizeSeasonScope(value: number | null | undefined): number | null {
  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
@@ -503,6 +524,36 @@ function ensureStatsExcludedWordsTable(db: DatabaseSync): void {
  `);
 }

+function ensureAnimeMergeTables(db: DatabaseSync): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS imm_anime_title_aliases(
+      normalized_title_key TEXT PRIMARY KEY,
+      anime_id INTEGER NOT NULL,
+      CREATED_DATE TEXT,
+      LAST_UPDATE_DATE TEXT,
+      FOREIGN KEY(anime_id) REFERENCES imm_anime(anime_id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_anime_title_aliases_anime_id
+    ON imm_anime_title_aliases(anime_id);
+
+    CREATE TABLE IF NOT EXISTS imm_anime_merge_recommendations(
+      recommendation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      first_anime_id INTEGER NOT NULL,
+      second_anime_id INTEGER NOT NULL,
+      anilist_id INTEGER NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'dismissed')),
+      CREATED_DATE TEXT,
+      LAST_UPDATE_DATE TEXT,
+      CHECK(first_anime_id < second_anime_id),
+      UNIQUE(first_anime_id, second_anime_id, anilist_id),
+      FOREIGN KEY(first_anime_id) REFERENCES imm_anime(anime_id) ON DELETE CASCADE,
+      FOREIGN KEY(second_anime_id) REFERENCES imm_anime(anime_id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_anime_merge_recommendations_status
+    ON imm_anime_merge_recommendations(status, recommendation_id);
+  `);
+}
+
 export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput): number {
  const seasonScope = normalizeSeasonScope(input.seasonScope);
  const identityTitle = buildSeasonScopedAnimeTitle(input.parsedTitle, seasonScope);
@@ -523,8 +574,14 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
  const byNormalizedTitle = db
    .prepare('SELECT anime_id FROM imm_anime WHERE normalized_title_key = ?')
    .get(normalizedTitleKey) as { anime_id: number } | null;
-  const existing = byAnilistId ?? byNormalizedTitle;
+  const byTitleAlias = db
+    .prepare('SELECT anime_id FROM imm_anime_title_aliases WHERE normalized_title_key = ?')
+    .get(normalizedTitleKey) as { anime_id: number } | null;
+  const existing = byAnilistId ?? byNormalizedTitle ?? byTitleAlias;
  if (existing?.anime_id) {
+    // An alias remembers an intentionally merged-away spelling. Reusing it
+    // must not rename the survivor back to that discarded display title.
+    const canonicalTitleUpdate = byAnilistId || byNormalizedTitle ? canonicalTitle : null;
    db.prepare(
      `
        UPDATE imm_anime
@@ -539,7 +596,7 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
        WHERE anime_id = ?
      `,
    ).run(
-      canonicalTitle,
+      canonicalTitleUpdate,
      input.anilistId,
      input.titleRomaji,
      input.titleEnglish,
@@ -724,6 +781,7 @@ export function ensureSchema(db: DatabaseSync): void {
  if (currentVersion?.schema_version === SCHEMA_VERSION) {
    ensureLifetimeSummaryTables(db);
    ensureStatsExcludedWordsTable(db);
+    ensureAnimeMergeTables(db);
    return;
  }

@@ -772,6 +830,7 @@ export function ensureSchema(db: DatabaseSync): void {
      FOREIGN KEY(anime_id) REFERENCES imm_anime(anime_id) ON DELETE SET NULL
    );
  `);
+  ensureAnimeMergeTables(db);
  db.exec(`
    CREATE TABLE IF NOT EXISTS imm_sessions(
      session_id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -923,6 +982,7 @@ export function ensureSchema(db: DatabaseSync): void {
      line_id INTEGER NOT NULL,
      word_id INTEGER NOT NULL,
      occurrence_count INTEGER NOT NULL,
+      seen_ms INTEGER,
      PRIMARY KEY(line_id, word_id),
      FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
      FOREIGN KEY(word_id) REFERENCES imm_words(id) ON DELETE CASCADE
@@ -933,6 +993,7 @@ export function ensureSchema(db: DatabaseSync): void {
      line_id INTEGER NOT NULL,
      kanji_id INTEGER NOT NULL,
      occurrence_count INTEGER NOT NULL,
+      seen_ms INTEGER,
      PRIMARY KEY(line_id, kanji_id),
      FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
      FOREIGN KEY(kanji_id) REFERENCES imm_kanji(id) ON DELETE CASCADE
@@ -1093,6 +1154,7 @@ export function ensureSchema(db: DatabaseSync): void {
        line_id INTEGER NOT NULL,
        word_id INTEGER NOT NULL,
        occurrence_count INTEGER NOT NULL,
+        seen_ms INTEGER,
        PRIMARY KEY(line_id, word_id),
        FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
        FOREIGN KEY(word_id) REFERENCES imm_words(id) ON DELETE CASCADE
@@ -1103,6 +1165,7 @@ export function ensureSchema(db: DatabaseSync): void {
        line_id INTEGER NOT NULL,
        kanji_id INTEGER NOT NULL,
        occurrence_count INTEGER NOT NULL,
+        seen_ms INTEGER,
        PRIMARY KEY(line_id, kanji_id),
        FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
        FOREIGN KEY(kanji_id) REFERENCES imm_kanji(id) ON DELETE CASCADE
@@ -1349,13 +1412,19 @@ export function ensureSchema(db: DatabaseSync): void {
    CREATE INDEX IF NOT EXISTS idx_subtitle_lines_anime_line
    ON imm_subtitle_lines(anime_id, line_index)
  `);
+  if (currentVersion?.schema_version && currentVersion.schema_version < 19) {
+    backfillLexicalOccurrenceSeenMs(db);
+  }
+
+  // Covering indexes: vocabulary aggregates (frequency, first/last seen) are
+  // answered from the index alone, without reading the wide subtitle-line rows.
  db.exec(`
-    CREATE INDEX IF NOT EXISTS idx_word_line_occurrences_word
-    ON imm_word_line_occurrences(word_id, line_id)
+    CREATE INDEX IF NOT EXISTS idx_word_line_occurrences_word_seen
+    ON imm_word_line_occurrences(word_id, seen_ms, occurrence_count, line_id)
  `);
  db.exec(`
-    CREATE INDEX IF NOT EXISTS idx_kanji_line_occurrences_kanji
-    ON imm_kanji_line_occurrences(kanji_id, line_id)
+    CREATE INDEX IF NOT EXISTS idx_kanji_line_occurrences_kanji_seen
+    ON imm_kanji_line_occurrences(kanji_id, seen_ms, occurrence_count, line_id)
  `);
  db.exec(`
    CREATE INDEX IF NOT EXISTS idx_media_art_cover_blob_hash
@@ -1475,21 +1544,23 @@ export function createTrackerPreparedStatements(db: DatabaseSync): TrackerPrepar
    `),
    wordLineOccurrenceUpsertStmt: db.prepare(`
      INSERT INTO imm_word_line_occurrences (
-        line_id, word_id, occurrence_count
+        line_id, word_id, occurrence_count, seen_ms
      ) VALUES (
-        ?, ?, ?
+        ?, ?, ?, ?
      )
      ON CONFLICT(line_id, word_id) DO UPDATE SET
-        occurrence_count = imm_word_line_occurrences.occurrence_count + excluded.occurrence_count
+        occurrence_count = imm_word_line_occurrences.occurrence_count + excluded.occurrence_count,
+        seen_ms = COALESCE(imm_word_line_occurrences.seen_ms, excluded.seen_ms)
    `),
    kanjiLineOccurrenceUpsertStmt: db.prepare(`
      INSERT INTO imm_kanji_line_occurrences (
-        line_id, kanji_id, occurrence_count
+        line_id, kanji_id, occurrence_count, seen_ms
      ) VALUES (
-        ?, ?, ?
+        ?, ?, ?, ?
      )
      ON CONFLICT(line_id, kanji_id) DO UPDATE SET
-        occurrence_count = imm_kanji_line_occurrences.occurrence_count + excluded.occurrence_count
+        occurrence_count = imm_kanji_line_occurrences.occurrence_count + excluded.occurrence_count,
+        seen_ms = COALESCE(imm_kanji_line_occurrences.seen_ms, excluded.seen_ms)
    `),
    videoAnimeIdSelectStmt: db.prepare(`
      SELECT anime_id FROM imm_videos
@@ -1630,11 +1701,16 @@ export function executeQueuedWrite(write: QueuedWrite, stmts: TrackerPreparedSta
    const lineId = Number(lineResult.lastInsertRowid);
    for (const occurrence of write.wordOccurrences) {
      const wordId = incrementWordAggregate(stmts, occurrence, write.firstSeen, write.lastSeen);
-      stmts.wordLineOccurrenceUpsertStmt.run(lineId, wordId, occurrence.occurrenceCount);
+      stmts.wordLineOccurrenceUpsertStmt.run(lineId, wordId, occurrence.occurrenceCount, currentMs);
    }
    for (const occurrence of write.kanjiOccurrences) {
      const kanjiId = incrementKanjiAggregate(stmts, occurrence, write.firstSeen, write.lastSeen);
-      stmts.kanjiLineOccurrenceUpsertStmt.run(lineId, kanjiId, occurrence.occurrenceCount);
+      stmts.kanjiLineOccurrenceUpsertStmt.run(
+        lineId,
+        kanjiId,
+        occurrence.occurrenceCount,
+        currentMs,
+      );
    }
    return;
  }
@@ -1,4 +1,4 @@
-export const SCHEMA_VERSION = 18;
+export const SCHEMA_VERSION = 20;
 export const DEFAULT_QUEUE_CAP = 1_000;
 export const DEFAULT_BATCH_SIZE = 25;
 export const DEFAULT_FLUSH_INTERVAL_MS = 500;
@@ -1,5 +1,9 @@
 export { Texthooker } from './texthooker';
-export { hasMpvWebsocketPlugin, SubtitleWebSocket } from './subtitle-ws';
+export {
+  hasMpvWebsocketPlugin,
+  isSubtitleAnnotationUpgrade,
+  SubtitleWebSocket,
+} from './subtitle-ws';
 export { registerGlobalShortcuts } from './shortcut';
 export { createIpcDepsRuntime, registerIpcHandlers } from './ipc';
 export { shortcutMatchesInputForLocalFallback } from './shortcut-fallback';
@@ -1,6 +1,7 @@
 import electron from 'electron';
 import type { BrowserWindow as ElectronBrowserWindow, IpcMainEvent } from 'electron';
 import type {
+  ChangelogSnapshot,
  CompiledSessionBinding,
  ControllerConfigUpdate,
  PlaylistBrowserMutationResult,
@@ -122,6 +123,7 @@ export interface IpcServiceDeps {
  removeCharacterDictionaryManagedEntry?: (mediaId: number) => Promise<unknown>;
  moveCharacterDictionaryManagedEntry?: (mediaId: number, direction: 1 | -1) => Promise<unknown>;
  appendClipboardVideoToQueue: () => { ok: boolean; message: string };
+  getChangelogSnapshot?: (options?: { refresh?: boolean }) => Promise<ChangelogSnapshot>;
  getPlaylistBrowserSnapshot: () => Promise<PlaylistBrowserSnapshot>;
  appendPlaylistBrowserFile: (filePath: string) => Promise<PlaylistBrowserMutationResult>;
  playPlaylistBrowserIndex: (index: number) => Promise<PlaylistBrowserMutationResult>;
@@ -297,6 +299,7 @@ export interface IpcDepsRuntimeOptions {
  removeCharacterDictionaryManagedEntry?: (mediaId: number) => Promise<unknown>;
  moveCharacterDictionaryManagedEntry?: (mediaId: number, direction: 1 | -1) => Promise<unknown>;
  appendClipboardVideoToQueue: () => { ok: boolean; message: string };
+  getChangelogSnapshot?: (options?: { refresh?: boolean }) => Promise<ChangelogSnapshot>;
  getPlaylistBrowserSnapshot: () => Promise<PlaylistBrowserSnapshot>;
  appendPlaylistBrowserFile: (filePath: string) => Promise<PlaylistBrowserMutationResult>;
  playPlaylistBrowserIndex: (index: number) => Promise<PlaylistBrowserMutationResult>;
@@ -418,6 +421,7 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
        entries: [],
      })),
    appendClipboardVideoToQueue: options.appendClipboardVideoToQueue,
+    getChangelogSnapshot: options.getChangelogSnapshot,
    getPlaylistBrowserSnapshot: options.getPlaylistBrowserSnapshot,
    appendPlaylistBrowserFile: options.appendPlaylistBrowserFile,
    playPlaylistBrowserIndex: options.playPlaylistBrowserIndex,
@@ -820,6 +824,17 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
    return deps.appendClipboardVideoToQueue();
  });

+  ipc.handle(IPC_CHANNELS.request.getChangelogSnapshot, async (_event, payload: unknown) => {
+    const refresh =
+      typeof payload === 'object' && payload !== null && 'refresh' in payload
+        ? (payload as { refresh?: unknown }).refresh === true
+        : false;
+    if (!deps.getChangelogSnapshot) {
+      throw new Error('Changelog service is unavailable.');
+    }
+    return await deps.getChangelogSnapshot({ refresh });
+  });
+
  ipc.handle(IPC_CHANNELS.request.getPlaylistBrowserSnapshot, async () => {
    return await deps.getPlaylistBrowserSnapshot();
  });
@@ -205,7 +205,7 @@ test('runStartupBootstrapRuntime skips lifecycle when generate-config flow handl
  assert.deepEqual(calls, ['setLog:warn:cli', 'forceX11', 'enforceWayland']);
 });

-test('runStartupBootstrapRuntime enables quiet background mode by default', () => {
+test('runStartupBootstrapRuntime lets config govern background log level by default', () => {
  const calls: string[] = [];
  const args = makeArgs({ background: true });

@@ -222,7 +222,7 @@ test('runStartupBootstrapRuntime enables quiet background mode by default', () =
  });

  assert.equal(result.backgroundMode, true);
-  assert.deepEqual(calls, ['setLog:warn:cli', 'forceX11', 'enforceWayland', 'startLifecycle']);
+  assert.deepEqual(calls, ['forceX11', 'enforceWayland', 'startLifecycle']);
 });

 test('runStartupBootstrapRuntime enables quiet update mode by default', () => {
@@ -45,7 +45,7 @@ export function runStartupBootstrapRuntime(

  if (initialArgs.logLevel) {
    deps.setLogLevel(initialArgs.logLevel, 'cli');
-  } else if (initialArgs.background || initialArgs.update) {
+  } else if (initialArgs.update) {
    deps.setLogLevel('warn', 'cli');
  }

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import type { Hono } from 'hono';
 import type { ImmersionTrackerService } from './immersion-tracker-service.js';
 import { statsJson, type StatsCoverImagesRequest } from '../../types/stats-http-contract.js';
@@ -74,6 +75,31 @@ function detectImageContentType(bytes: Uint8Array): string {
  return 'application/octet-stream';
 }

+function ifNoneMatchHits(header: string | undefined, etag: string): boolean {
+  if (!header) return false;
+  if (header.trim() === '*') return true;
+  return header
+    .split(',')
+    .map((candidate) => candidate.trim().replace(/^W\//, ''))
+    .some((candidate) => candidate === etag);
+}
+
+// Cover URLs are stable per anime/video, so relinking an AniList entry swaps the
+// bytes behind an unchanged URL. Long max-age would keep serving the old art from
+// the browser cache; revalidate instead and let the ETag skip the transfer.
+function coverResponse(bytes: Uint8Array<ArrayBuffer>, ifNoneMatch: string | undefined): Response {
+  const etag = `"${createHash('sha256').update(bytes).digest('hex')}"`;
+  const headers: Record<string, string> = {
+    'Content-Type': detectImageContentType(bytes),
+    'Cache-Control': 'no-cache',
+    ETag: etag,
+  };
+  if (ifNoneMatchHits(ifNoneMatch, etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(bytes, { headers });
+}
+
 function createLimitedTaskRunner(maxConcurrentTasks: number): (task: () => Promise<void>) => void {
  const queue: Array<() => Promise<void>> = [];
  let activeTasks = 0;
@@ -137,13 +163,7 @@ export function registerStatsCoverRoutes(app: Hono, tracker: ImmersionTrackerSer
      art = await tracker.getAnimeCoverArt(animeId);
    }
    if (!art?.coverBlob) return c.body(null, 404);
-    const bytes = new Uint8Array(art.coverBlob);
-    return new Response(bytes, {
-      headers: {
-        'Content-Type': detectImageContentType(bytes),
-        'Cache-Control': 'public, max-age=86400',
-      },
-    });
+    return coverResponse(new Uint8Array(art.coverBlob), c.req.header('if-none-match'));
  });

  app.get('/api/stats/media/:videoId/cover', async (c) => {
@@ -155,12 +175,6 @@ export function registerStatsCoverRoutes(app: Hono, tracker: ImmersionTrackerSer
      art = await tracker.getCoverArt(videoId);
    }
    if (!art?.coverBlob) return c.body(null, 404);
-    const bytes = new Uint8Array(art.coverBlob);
-    return new Response(bytes, {
-      headers: {
-        'Content-Type': detectImageContentType(bytes),
-        'Cache-Control': 'public, max-age=604800',
-      },
-    });
+    return coverResponse(new Uint8Array(art.coverBlob), c.req.header('if-none-match'));
  });
 }
@@ -1,5 +1,6 @@
 import type { Hono } from 'hono';
 import { statsJson } from '../../../types/stats-http-contract.js';
+import { UNKNOWN_MOVE_TARGET_MESSAGE } from '../immersion-tracker/anime-merge.js';
 import type { ImmersionTrackerService } from '../immersion-tracker-service.js';
 import {
  buildSentenceSearchOptions,
@@ -7,6 +8,7 @@ import {
  parseBooleanQuery,
  parseExcludedWordsBody,
  parseIntQuery,
+  parsePositiveIdList,
 } from './route-support.js';

 export function registerStatsLibraryRoutes(
@@ -130,6 +132,19 @@ export function registerStatsLibraryRoutes(
    return c.json(statsJson('animeLibrary', rows));
  });

+  app.get('/api/stats/anime/merge-recommendations', async (c) => {
+    const recommendations = await tracker.getAnimeMergeRecommendations();
+    return c.json(statsJson('animeMergeRecommendations', { recommendations }));
+  });
+
+  app.delete('/api/stats/anime/merge-recommendations/:recommendationId', async (c) => {
+    const recommendationId = parseIntQuery(c.req.param('recommendationId'), 0);
+    if (recommendationId <= 0) return c.body(null, 400);
+    const dismissed = await tracker.dismissAnimeMergeRecommendation(recommendationId);
+    if (!dismissed) return c.body(null, 404);
+    return c.json(statsJson('dismissAnimeMergeRecommendation', { ok: true }));
+  });
+
  app.get('/api/stats/anime/:animeId', async (c) => {
    const animeId = parseIntQuery(c.req.param('animeId'), 0);
    if (animeId <= 0) return c.body(null, 400);
@@ -190,4 +205,57 @@ export function registerStatsLibraryRoutes(
    await tracker.deleteVideo(videoId);
    return c.json(statsJson('deleteVideo', { ok: true }));
  });
+
+  app.delete('/api/stats/anime/:animeId', async (c) => {
+    const animeId = parseIntQuery(c.req.param('animeId'), 0);
+    if (animeId <= 0) return c.body(null, 400);
+    await tracker.deleteAnime(animeId);
+    return c.json(statsJson('deleteAnime', { ok: true }));
+  });
+
+  app.post('/api/stats/anime/:animeId/merge', async (c) => {
+    const animeId = parseIntQuery(c.req.param('animeId'), 0);
+    if (animeId <= 0) return c.body(null, 400);
+    const body = await c.req.json().catch(() => null);
+    const sourceAnimeIds = parsePositiveIdList(body?.sourceAnimeIds).filter((id) => id !== animeId);
+    if (sourceAnimeIds.length === 0) return c.body(null, 400);
+    const summary = await tracker.mergeAnime(animeId, sourceAnimeIds);
+    // Nothing folded means the target or every source was already gone, so the
+    // caller should not be told the merge succeeded.
+    if (summary.mergedAnimeIds.length === 0) return c.body(null, 404);
+    return c.json(
+      statsJson('mergeAnime', {
+        ok: true,
+        animeId: summary.survivingAnimeId,
+        mergedAnimeIds: summary.mergedAnimeIds,
+        movedVideos: summary.movedVideos,
+      }),
+    );
+  });
+
+  app.patch('/api/stats/media/:videoId/anime', async (c) => {
+    const videoId = parseIntQuery(c.req.param('videoId'), 0);
+    if (videoId <= 0) return c.body(null, 400);
+    const body = await c.req.json().catch(() => null);
+    const animeId = Number.isSafeInteger(body?.animeId) ? (body.animeId as number) : 0;
+    if (animeId <= 0) return c.body(null, 400);
+    try {
+      const summary = await tracker.moveVideoToAnime(videoId, animeId);
+      return c.json(
+        statsJson('moveVideoToAnime', {
+          ok: true,
+          animeId: summary.targetAnimeId,
+          previousAnimeId: summary.previousAnimeId,
+          removedPreviousAnime: summary.removedPreviousAnime,
+        }),
+      );
+    } catch (error) {
+      // Only a missing episode or entry is a 404; storage failures must not be
+      // reported to the caller as "not found".
+      if (error instanceof Error && error.message === UNKNOWN_MOVE_TARGET_MESSAGE) {
+        return c.body(null, 404);
+      }
+      throw error;
+    }
+  });
 }
@@ -11,7 +11,7 @@ import {
  resolveSecondarySubtitleTextFromSidecar,
 } from '../secondary-subtitle-sidecar.js';
 import {
-  applyStatsWordAndSentenceCardFields,
+  applyStatsWordCardFields,
  createStatsMiningContext,
  getStatsDirectMiningAudioFieldNames,
  getStatsWordMiningAudioFieldName,
@@ -272,7 +272,7 @@ export function registerStatsMiningRoutes(app: Hono, options?: StatsMiningRouteO
      const imageFieldName = ankiConfig.fields?.image ?? 'Picture';

      mediaFields[sentenceFieldName] = highlightedSentence;
-      applyStatsWordAndSentenceCardFields(mediaFields, noteInfo, ankiConfig);
+      applyStatsWordCardFields(mediaFields, noteInfo, ankiConfig);

      if (audioBuffer) {
        const audioFilename = `subminer_audio_${timestamp}_${noteId}.mp3`;
@@ -1,5 +1,7 @@
 import type { MediaGenerator } from '../../../media-generator.js';
 import type { AnkiConnectConfig } from '../../../types.js';
+import { applyCardKindFlagFields } from '../../../anki-integration/card-kinds.js';
+import { resolveWordCardKind } from '../../../anki-integration/note-field-utils.js';
 import { createLogger } from '../../../logger.js';
 import type { RetimedSecondarySubtitleInput } from '../secondary-subtitle-sidecar.js';

@@ -94,20 +96,22 @@ export function shouldUseStatsLapisKikuCardFields(ankiConfig: AnkiConnectConfig)
  return ankiConfig.isLapis?.enabled === true || ankiConfig.isKiku?.enabled === true;
 }

-export function applyStatsWordAndSentenceCardFields(
+export function applyStatsWordCardFields(
  fields: Record<string, string>,
  noteInfo: StatsServerNoteInfo | null,
  ankiConfig: AnkiConnectConfig,
 ): void {
-  if (!shouldUseStatsLapisKikuCardFields(ankiConfig) || !noteInfo) return;
-  const wordAndSentenceFlag = resolveStatsNoteFieldName(noteInfo, 'IsWordAndSentenceCard');
-  if (!wordAndSentenceFlag) return;
+  if (!noteInfo) return;
+  const cardKind = resolveWordCardKind(noteInfo, {
+    lapisEnabled: ankiConfig.isLapis?.enabled === true,
+    kikuEnabled: ankiConfig.isKiku?.enabled === true,
+    wordCardKind: ankiConfig.lapisKiku?.wordCardKind,
+  });
+  if (!cardKind) return;

-  fields[wordAndSentenceFlag] = 'x';
-  for (const flagName of ['IsSentenceCard', 'IsAudioCard']) {
-    const resolved = resolveStatsNoteFieldName(noteInfo, flagName);
-    if (resolved && resolved !== wordAndSentenceFlag) fields[resolved] = '';
-  }
+  applyCardKindFlagFields(fields, cardKind, (preferredName) =>
+    resolveStatsNoteFieldName(noteInfo, preferredName),
+  );
 }

 export function getStatsDirectMiningAudioFieldNames(
@@ -170,6 +170,18 @@ export async function enrichSessionsWithKnownWordMetrics<
  );
 }

+/** Deduplicated positive integer ids from an untrusted JSON body field. */
+export function parsePositiveIdList(raw: unknown): number[] {
+  if (!Array.isArray(raw)) return [];
+  const ids = new Set<number>();
+  for (const value of raw) {
+    if (Number.isSafeInteger(value) && (value as number) > 0) {
+      ids.add(value as number);
+    }
+  }
+  return [...ids];
+}
+
 export function parseBooleanQuery(raw: string | undefined, fallback: boolean): boolean {
  if (raw === undefined) return fallback;
  const normalized = raw.trim().toLowerCase();
@@ -0,0 +1,100 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database } from '../immersion-tracker/sqlite';
+import { ensureSchema } from '../immersion-tracker/storage';
+import { mergeSnapshotIntoDb } from './merge';
+
+const BASE_MS = 1_700_000_000_000;
+const DAY_MS = 86_400_000;
+
+/**
+ * Build a database holding one anime, one episode, one ended session and a
+ * single word occurrence.
+ *
+ * `legacyOccurrences` reproduces a peer whose schema predates the denormalised
+ * `seen_ms` column, so the merge has to recover the timestamp from the line.
+ */
+function buildDb(
+  dir: string,
+  name: string,
+  options: { word: string; seenMs: number; legacyOccurrences: boolean },
+): string {
+  const dbPath = path.join(dir, name);
+  const db = new Database(dbPath);
+  ensureSchema(db);
+  db.exec(`
+    INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'key-${name}', 'Show ${name}', ${BASE_MS}, ${BASE_MS});
+    INSERT INTO imm_videos(video_id, video_key, anime_id, canonical_title, source_type, watched, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'video-${name}', 1, 'Episode 1', 1, 1, 1440000, ${BASE_MS}, ${BASE_MS});
+    INSERT INTO imm_sessions(session_id, session_uuid, video_id, started_at_ms, ended_at_ms, status, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'uuid-${name}', 1, '${options.seenMs}', '${options.seenMs + 1000}', 2, ${BASE_MS}, ${BASE_MS});
+    INSERT INTO imm_subtitle_lines(line_id, session_id, video_id, anime_id, line_index, text, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 1, 1, 1, 0, 'line', ${options.seenMs}, ${options.seenMs});
+    INSERT INTO imm_words(id, headword, word, reading, part_of_speech, pos1, first_seen, last_seen, frequency)
+      VALUES (1, '${options.word}', '${options.word}', '', 'noun', '名詞',
+              ${Math.floor(options.seenMs / 1000)}, ${Math.floor(options.seenMs / 1000)}, 1);
+  `);
+  db.exec(
+    options.legacyOccurrences
+      ? 'INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count) VALUES (1, 1, 1)'
+      : `INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count, seen_ms) VALUES (1, 1, 1, ${options.seenMs})`,
+  );
+  db.close();
+  return dbPath;
+}
+
+function mergedOccurrences(dbPath: string): Array<{ word: string; seenMs: number | null }> {
+  const db = new Database(dbPath);
+  try {
+    return db
+      .prepare(
+        `SELECT w.word AS word, o.seen_ms AS seenMs
+         FROM imm_word_line_occurrences o
+         JOIN imm_words w ON w.id = o.word_id
+         ORDER BY w.word`,
+      )
+      .all() as Array<{ word: string; seenMs: number | null }>;
+  } finally {
+    db.close();
+  }
+}
+
+for (const legacyOccurrences of [false, true]) {
+  const label = legacyOccurrences ? 'a peer predating the seen_ms column' : 'a current peer';
+
+  test(`sync merge carries occurrence timestamps in from ${label}`, () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-merge-occurrences-test-'));
+    try {
+      const local = buildDb(dir, 'local.sqlite', {
+        word: '猫',
+        seenMs: BASE_MS,
+        legacyOccurrences: false,
+      });
+      const remoteSeenMs = BASE_MS + 5 * DAY_MS;
+      const remote = buildDb(dir, 'remote.sqlite', {
+        word: '犬',
+        seenMs: remoteSeenMs,
+        legacyOccurrences,
+      });
+
+      mergeSnapshotIntoDb(local, remote);
+
+      const rows = mergedOccurrences(local);
+      assert.equal(rows.length, 2, 'local and remote occurrences both survive the merge');
+      for (const row of rows) {
+        assert.ok(row.seenMs, `${row.word} must carry a timestamp so aggregates stay index-only`);
+      }
+      assert.equal(
+        Number(rows.find((row) => row.word === '犬')?.seenMs),
+        remoteSeenMs,
+        "the remote line's own timestamp is preserved rather than stamped with merge time",
+      );
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+}
@@ -215,12 +215,16 @@ function copySubtitleLines(
    'SELECT kanji_id, occurrence_count FROM imm_kanji_line_occurrences WHERE line_id = ?',
  );
  const insertWordOccurrence = local.query(
-    `INSERT INTO imm_word_line_occurrences (line_id, word_id, occurrence_count) VALUES (?, ?, ?)
-     ON CONFLICT(line_id, word_id) DO UPDATE SET occurrence_count = occurrence_count + excluded.occurrence_count`,
+    `INSERT INTO imm_word_line_occurrences (line_id, word_id, occurrence_count, seen_ms) VALUES (?, ?, ?, ?)
+     ON CONFLICT(line_id, word_id) DO UPDATE SET
+       occurrence_count = occurrence_count + excluded.occurrence_count,
+       seen_ms = COALESCE(seen_ms, excluded.seen_ms)`,
  );
  const insertKanjiOccurrence = local.query(
-    `INSERT INTO imm_kanji_line_occurrences (line_id, kanji_id, occurrence_count) VALUES (?, ?, ?)
-     ON CONFLICT(line_id, kanji_id) DO UPDATE SET occurrence_count = occurrence_count + excluded.occurrence_count`,
+    `INSERT INTO imm_kanji_line_occurrences (line_id, kanji_id, occurrence_count, seen_ms) VALUES (?, ?, ?, ?)
+     ON CONFLICT(line_id, kanji_id) DO UPDATE SET
+       occurrence_count = occurrence_count + excluded.occurrence_count,
+       seen_ms = COALESCE(seen_ms, excluded.seen_ms)`,
  );

  for (const row of rows) {
@@ -241,17 +245,20 @@ function copySubtitleLines(
      ],
    );
    summary.subtitleLinesAdded += 1;
+    // Taken from the line rather than the remote occurrence row so this also
+    // works when the remote database predates the seen_ms column.
+    const seenMs = row.CREATED_DATE ?? row.LAST_UPDATE_DATE ?? null;

    for (const occurrence of wordOccurrences.all(row.line_id) as SqlRow[]) {
      const localWordId = lexicon.resolveWord(Number(occurrence.word_id));
      const count = Number(occurrence.occurrence_count);
-      insertWordOccurrence.run(localLineId, localWordId, count);
+      insertWordOccurrence.run(localLineId, localWordId, count, seenMs);
      lexicon.addWordOccurrences(Number(occurrence.word_id), count);
    }
    for (const occurrence of kanjiOccurrences.all(row.line_id) as SqlRow[]) {
      const localKanjiId = lexicon.resolveKanji(Number(occurrence.kanji_id));
      const count = Number(occurrence.occurrence_count);
-      insertKanjiOccurrence.run(localLineId, localKanjiId, count);
+      insertKanjiOccurrence.run(localLineId, localKanjiId, count, seenMs);
      lexicon.addKanjiOccurrences(Number(occurrence.kanji_id), count);
    }
  }
@@ -8,6 +8,7 @@ import {
  runSubsyncManual,
  triggerSubsyncFromConfig,
 } from './subsync';
+import type { SubsyncManualPayload } from '../../types';

 function makeDeps(
  overrides: Partial<TriggerSubsyncFromConfigDeps> = {},
@@ -76,7 +77,7 @@ test('triggerSubsyncFromConfig opens manual picker', async () => {
  await triggerSubsyncFromConfig(
    makeDeps({
      openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
        ffsubsyncAvailable = payload.ffsubsyncAvailable;
      },
      showMpvOsd: (text) => {
@@ -88,9 +89,9 @@ test('triggerSubsyncFromConfig opens manual picker', async () => {
    }),
  );

-  assert.equal(payloadTrackCount, 1);
+  assert.equal(payloadTrackCount, 2);
  assert.equal(ffsubsyncAvailable, true);
-  assert.ok(osd.includes('Subsync: choose engine and source'));
+  assert.ok(osd.includes('Subsync: choose engine and subtitles'));
  assert.equal(inProgressState, false);
 });

@@ -140,7 +141,7 @@ test('triggerSubsyncFromConfig does not run automatic sync', async () => {
  await triggerSubsyncFromConfig(
    makeDeps({
      openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
      },
      showMpvOsd: (text) => {
        osd.push(text);
@@ -152,9 +153,9 @@ test('triggerSubsyncFromConfig does not run automatic sync', async () => {
    }),
  );

-  assert.equal(payloadTrackCount, 1);
+  assert.equal(payloadTrackCount, 2);
  assert.equal(spinnerRan, false);
-  assert.deepEqual(osd, ['Subsync: choose engine and source']);
+  assert.deepEqual(osd, ['Subsync: choose engine and subtitles']);
 });

 test('triggerSubsyncFromConfig dedupes repeated subtitle source tracks', async () => {
@@ -195,12 +196,71 @@ test('triggerSubsyncFromConfig dedupes repeated subtitle source tracks', async (
        },
      }),
      openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
      },
    }),
  );

-  assert.equal(payloadTrackCount, 1);
+  assert.equal(payloadTrackCount, 2);
+});
+
+test('triggerSubsyncFromConfig keeps both active tracks when they share a file', async () => {
+  let payload: SubsyncManualPayload | null = null;
+
+  await triggerSubsyncFromConfig(
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return '/tmp/video.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return 2;
+          if (name === 'track-list') {
+            // mpv appends a duplicate entry when the same file is re-added, so
+            // the primary and secondary slots can point at one path.
+            return [
+              {
+                id: 1,
+                type: 'sub',
+                selected: true,
+                external: true,
+                'external-filename': '/tmp/ref.srt',
+              },
+              {
+                id: 2,
+                type: 'sub',
+                selected: true,
+                external: true,
+                'external-filename': '/tmp/ref.srt',
+              },
+              {
+                id: 3,
+                type: 'sub',
+                selected: false,
+                external: true,
+                'external-filename': '/tmp/ref.srt',
+              },
+            ];
+          }
+          return null;
+        },
+      }),
+      openManualPicker: (nextPayload) => {
+        payload = nextPayload;
+      },
+    }),
+  );
+
+  assert.ok(payload);
+  const resolved = payload as SubsyncManualPayload;
+  assert.deepEqual(
+    resolved.subtitleTracks.map((track) => track.id),
+    [1, 2],
+  );
+  assert.equal(resolved.defaultReferenceTrackId, 2);
+  assert.equal(resolved.defaultTargetTrackId, 1);
 });

 test('triggerSubsyncFromConfig reports failures to OSD', async () => {
@@ -217,15 +277,157 @@ test('triggerSubsyncFromConfig reports failures to OSD', async () => {
  assert.ok(osd.some((line) => line.startsWith('Subsync failed: MPV not connected')));
 });

-test('runSubsyncManual requires a source track for alass', async () => {
-  const result = await runSubsyncManual({ engine: 'alass', sourceTrackId: null }, makeDeps());
+test('runSubsyncManual requires a reference track for alass', async () => {
+  const result = await runSubsyncManual({ engine: 'alass', referenceTrackId: null }, makeDeps());

  assert.deepEqual(result, {
    ok: false,
-    message: 'Select a subtitle source track for alass',
+    message: 'Select a reference subtitle track for alass',
  });
 });

+test('runSubsyncManual rejects alass when reference and target are the same track', async () => {
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 2, targetTrackId: 2 },
+    makeDeps(),
+  );
+
+  assert.deepEqual(result, {
+    ok: false,
+    message: 'Reference and out-of-sync subtitles must be different tracks',
+  });
+});
+
+test('runSubsyncManual rejects an unknown target track', async () => {
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 2, targetTrackId: 99 },
+    makeDeps(),
+  );
+
+  assert.deepEqual(result, {
+    ok: false,
+    message: 'Select the out-of-sync subtitle track to retime',
+  });
+});
+
+test('runSubsyncManual rejects the video reference for remote media', async () => {
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceMode: 'video' },
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return 'https://jellyfin.example/Videos/movie/stream.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return null;
+          if (name === 'track-list') {
+            return [{ id: 1, type: 'sub', selected: true, lang: 'jpn' }];
+          }
+          return null;
+        },
+      }),
+    }),
+  );
+
+  assert.equal(result.ok, false);
+  assert.match(result.message, /cannot use a stream URL as reference/);
+});
+
+test('openSubsyncManualPicker defaults the reference to the secondary subtitle track', async () => {
+  let payload: SubsyncManualPayload | null = null;
+
+  await triggerSubsyncFromConfig(
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return '/tmp/video.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return 3;
+          if (name === 'track-list') {
+            return [
+              { id: 1, type: 'sub', selected: true, lang: 'jpn' },
+              {
+                id: 2,
+                type: 'sub',
+                selected: false,
+                external: true,
+                lang: 'eng',
+                'external-filename': '/tmp/other.srt',
+              },
+              {
+                id: 3,
+                type: 'sub',
+                selected: true,
+                external: true,
+                lang: 'eng',
+                'external-filename': '/tmp/secondary.srt',
+              },
+            ];
+          }
+          return null;
+        },
+      }),
+      openManualPicker: (nextPayload) => {
+        payload = nextPayload;
+      },
+    }),
+  );
+
+  assert.ok(payload);
+  const resolved = payload as SubsyncManualPayload;
+  assert.deepEqual(
+    resolved.subtitleTracks.map((track) => track.id),
+    [1, 2, 3],
+  );
+  assert.equal(resolved.defaultReferenceTrackId, 3);
+  assert.equal(resolved.defaultTargetTrackId, 1);
+  assert.equal(resolved.videoReferenceAvailable, true);
+});
+
+test('openSubsyncManualPicker never defaults to a reference missing from the track list', async () => {
+  let payload: SubsyncManualPayload | null = null;
+
+  await triggerSubsyncFromConfig(
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return '/tmp/video.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return 2;
+          if (name === 'track-list') {
+            return [
+              { id: 1, type: 'sub', selected: true, lang: 'jpn' },
+              // Secondary track with no usable file path: filtered out of the picker.
+              { id: 2, type: 'sub', selected: true, external: true, 'external-filename': '' },
+              { id: 3, type: 'sub', selected: false, lang: 'eng' },
+            ];
+          }
+          return null;
+        },
+      }),
+      openManualPicker: (nextPayload) => {
+        payload = nextPayload;
+      },
+    }),
+  );
+
+  assert.ok(payload);
+  const resolved = payload as SubsyncManualPayload;
+  assert.deepEqual(
+    resolved.subtitleTracks.map((track) => track.id),
+    [1, 3],
+  );
+  assert.equal(resolved.defaultReferenceTrackId, 3);
+});
+
 test('triggerSubsyncFromConfig does not validate sync tool paths before manual selection', async () => {
  const osd: string[] = [];
  const inProgress: boolean[] = [];
@@ -242,7 +444,7 @@ test('triggerSubsyncFromConfig does not validate sync tool paths before manual s
        inProgress.push(value);
      },
      openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
      },
      showMpvOsd: (text) => {
        osd.push(text);
@@ -251,8 +453,8 @@ test('triggerSubsyncFromConfig does not validate sync tool paths before manual s
  );

  assert.deepEqual(inProgress, [false]);
-  assert.equal(payloadTrackCount, 1);
-  assert.deepEqual(osd, ['Subsync: choose engine and source']);
+  assert.equal(payloadTrackCount, 2);
+  assert.deepEqual(osd, ['Subsync: choose engine and subtitles']);
 });

 function writeExecutableScript(filePath: string, content: string): void {
@@ -333,7 +535,7 @@ test('runSubsyncManual constructs ffsubsync command and returns success', async
    }),
  });

-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);

  assert.equal(result.ok, true);
  assert.equal(result.message, 'Subtitle synchronized with ffsubsync');
@@ -346,7 +548,7 @@ test('runSubsyncManual constructs ffsubsync command and returns success', async
  const ffOutputFlagIndex = ffArgs.indexOf('-o');
  assert.equal(ffOutputFlagIndex >= 0, true);
  assert.equal(ffArgs[ffOutputFlagIndex + 1], toShellPath(primaryPath));
-  assert.equal(sentCommands[0]?.[0], 'sub_add');
+  assert.equal(sentCommands[0]?.[0], 'sub-add');
  assert.deepEqual(sentCommands[1], ['set_property', 'sub-delay', 0]);
 });

@@ -399,7 +601,7 @@ test('runSubsyncManual writes deterministic _retimed filename when replace is fa
    }),
  });

-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);

  assert.equal(result.ok, true);
  const ffArgs = fs.readFileSync(ffsubsyncLogPath, 'utf8').trim().split('\n');
@@ -453,7 +655,7 @@ test('runSubsyncManual reports ffsubsync command failures with details', async (
    }),
  });

-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);

  assert.equal(result.ok, false);
  assert.equal(result.message.startsWith('ffsubsync synchronization failed'), true);
@@ -518,7 +720,7 @@ test('runSubsyncManual constructs alass command and returns failure on non-zero
    }),
  });

-  const result = await runSubsyncManual({ engine: 'alass', sourceTrackId: 2 }, deps);
+  const result = await runSubsyncManual({ engine: 'alass', referenceTrackId: 2 }, deps);

  assert.equal(result.ok, false);
  assert.equal(typeof result.message, 'string');
@@ -528,6 +730,179 @@ test('runSubsyncManual constructs alass command and returns failure on non-zero
  assert.equal(alassArgs[1], toShellPath(primaryPath));
 });

+function makeAlassSelectionDeps(tmpDir: string): {
+  deps: TriggerSubsyncFromConfigDeps;
+  alassLogPath: string;
+  videoPath: string;
+  primaryPath: string;
+  sourcePath: string;
+  sentCommands: Array<Array<string | number>>;
+} {
+  const alassLogPath = path.join(tmpDir, 'alass-args.log');
+  const alassPath = path.join(tmpDir, 'alass.sh');
+  const ffmpegPath = path.join(tmpDir, 'ffmpeg.sh');
+  const ffsubsyncPath = path.join(tmpDir, 'ffsubsync.sh');
+  const videoPath = path.join(tmpDir, 'video.mkv');
+  const primaryPath = path.join(tmpDir, 'primary.srt');
+  const sourcePath = path.join(tmpDir, 'source.srt');
+
+  fs.writeFileSync(videoPath, 'video');
+  fs.writeFileSync(primaryPath, 'sub');
+  fs.writeFileSync(sourcePath, 'sub2');
+  writeExecutableScript(ffmpegPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(ffsubsyncPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(
+    alassPath,
+    `#!/bin/sh\n: > "${toShellPath(alassLogPath)}"\nfor arg in "$@"; do printf '%s\\n' "$arg" >> "${toShellPath(alassLogPath)}"; done\n: > "$3"\nexit 0\n`,
+  );
+
+  const trackList: Array<Record<string, unknown>> = [
+    { id: 1, type: 'sub', selected: true, external: true, 'external-filename': primaryPath },
+    { id: 2, type: 'sub', selected: true, external: true, 'external-filename': sourcePath },
+  ];
+  const sentCommands: Array<Array<string | number>> = [];
+  const deps = makeDeps({
+    getMpvClient: () => ({
+      connected: true,
+      currentAudioStreamIndex: null,
+      send: (payload) => {
+        sentCommands.push(payload.command);
+        if (payload.command[0] === 'sub-add' || payload.command[0] === 'sub_add') {
+          trackList.push({
+            id: trackList.length + 1,
+            type: 'sub',
+            selected: false,
+            external: true,
+            'external-filename': payload.command[1],
+          });
+        }
+      },
+      requestProperty: async (name: string) => {
+        if (name === 'path') return videoPath;
+        if (name === 'sid') return 1;
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return trackList;
+        return null;
+      },
+    }),
+    getResolvedConfig: () => ({
+      alassPath,
+      ffsubsyncPath,
+      ffmpegPath,
+      replace: false,
+    }),
+  });
+
+  return { deps, alassLogPath, videoPath, primaryPath, sourcePath, sentCommands };
+}
+
+test('runSubsyncManual uses the video file as alass reference when requested', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-video-ref-'));
+  const { deps, alassLogPath, videoPath, primaryPath } = makeAlassSelectionDeps(tmpDir);
+
+  const result = await runSubsyncManual({ engine: 'alass', referenceMode: 'video' }, deps);
+
+  assert.equal(result.ok, true);
+  const alassArgs = fs.readFileSync(alassLogPath, 'utf8').trim().split('\n');
+  assert.equal(alassArgs[0], toShellPath(videoPath));
+  assert.equal(alassArgs[1], toShellPath(primaryPath));
+});
+
+test('runSubsyncManual retimes the selected target track instead of the primary', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-target-'));
+  const { deps, alassLogPath, primaryPath, sourcePath, sentCommands } =
+    makeAlassSelectionDeps(tmpDir);
+
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 1, targetTrackId: 2 },
+    deps,
+  );
+
+  assert.equal(result.ok, true);
+  const alassArgs = fs.readFileSync(alassLogPath, 'utf8').trim().split('\n');
+  assert.equal(alassArgs[0], toShellPath(primaryPath));
+  assert.equal(alassArgs[1], toShellPath(sourcePath));
+  assert.equal(sentCommands[0]?.[0], 'sub-add');
+  assert.equal(sentCommands[0]?.[2], 'auto');
+});
+
+test('runSubsyncManual keeps a retimed secondary track in the secondary slot', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-secondary-slot-'));
+  const alassPath = path.join(tmpDir, 'alass.sh');
+  const ffmpegPath = path.join(tmpDir, 'ffmpeg.sh');
+  const ffsubsyncPath = path.join(tmpDir, 'ffsubsync.sh');
+  const videoPath = path.join(tmpDir, 'video.mkv');
+  const primaryPath = path.join(tmpDir, 'ja.srt');
+  const secondaryPath = path.join(tmpDir, 'en.srt');
+  const retimedPath = path.join(tmpDir, 'en_retimed.srt');
+
+  fs.writeFileSync(videoPath, 'video');
+  fs.writeFileSync(primaryPath, 'ja');
+  fs.writeFileSync(secondaryPath, 'en');
+  writeExecutableScript(ffmpegPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(ffsubsyncPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(alassPath, '#!/bin/sh\n: > "$3"\nexit 0\n');
+
+  const trackList: Array<Record<string, unknown>> = [
+    { id: 1, type: 'sub', selected: true, external: true, 'external-filename': primaryPath },
+    { id: 2, type: 'sub', selected: true, external: true, 'external-filename': secondaryPath },
+  ];
+  const sentCommands: Array<Array<string | number>> = [];
+  const deps = makeDeps({
+    getMpvClient: () => ({
+      connected: true,
+      currentAudioStreamIndex: null,
+      send: (payload) => {
+        sentCommands.push(payload.command);
+        if (payload.command[0] === 'sub-add') {
+          trackList.push({
+            id: 3,
+            type: 'sub',
+            selected: false,
+            external: true,
+            'external-filename': payload.command[1],
+          });
+        }
+      },
+      requestProperty: async (name: string) => {
+        if (name === 'path') return videoPath;
+        if (name === 'sid') return 1;
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return trackList;
+        return null;
+      },
+    }),
+    getResolvedConfig: () => ({
+      alassPath,
+      ffsubsyncPath,
+      ffmpegPath,
+      replace: false,
+    }),
+  });
+
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 1, targetTrackId: 2 },
+    deps,
+  );
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(sentCommands[0], ['sub-add', retimedPath, 'auto']);
+  assert.deepEqual(sentCommands[1], ['set_property', 'secondary-sub-delay', 0]);
+  assert.deepEqual(sentCommands[2], ['set_property', 'secondary-sid', 3]);
+  assert.equal(
+    sentCommands.some((command) => command[1] === 'sub-delay'),
+    false,
+  );
+  assert.equal(
+    sentCommands.some((command) => command[1] === 'sid'),
+    false,
+  );
+  assert.equal(
+    sentCommands.some((command) => command[1] === 'sid'),
+    false,
+  );
+});
+
 test('runSubsyncManual keeps internal alass source file alive until sync finishes', async () => {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-internal-source-'));
  const alassPath = path.join(tmpDir, 'alass.sh');
@@ -589,11 +964,11 @@ test('runSubsyncManual keeps internal alass source file alive until sync finishe
    }),
  });

-  const result = await runSubsyncManual({ engine: 'alass', sourceTrackId: 2 }, deps);
+  const result = await runSubsyncManual({ engine: 'alass', referenceTrackId: 2 }, deps);

  assert.equal(result.ok, true);
  assert.equal(result.message, 'Subtitle synchronized with alass');
-  assert.equal(sentCommands[0]?.[0], 'sub_add');
+  assert.equal(sentCommands[0]?.[0], 'sub-add');
  assert.deepEqual(sentCommands[1], ['set_property', 'sub-delay', 0]);
 });

@@ -645,7 +1020,7 @@ test('runSubsyncManual resolves string sid values from mpv stream properties', a
    }),
  });

-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);

  assert.equal(result.ok, true);
  assert.equal(result.message, 'Subtitle synchronized with ffsubsync');
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
sudacode	abbe0ee829	fix(stats): preserve season boundaries during AniList merge resolution - Allow manual cross-season reassignment without merging entries - Require validated title matches for automatic merges - Share title normalization across AniList and stats flows	2026-08-11 23:40:27 -07:00
sudacode	d8c5fc321a	fix(stats): review fuzzy AniList duplicates before merging - Preserve merged title aliases for future episodes - Fail closed when queued writes cannot drain	2026-08-11 23:11:39 -07:00
sudacode	d82a4fd8c6	test(stats): assert lifetime rebuild reflects drained telemetry - queue a telemetry write behind subtitle lines so it lands past the first batch - assert imm_lifetime_anime picks up linesSeen/activeMs/cards only after the full queue drains	2026-08-11 00:04:03 -07:00
sudacode	da80ece9f7	test(stats): move write-queue drain test to its own file - Extract the mergeAnime/moveVideoToAnime queue-drain test into immersion-tracker-write-queue.test.ts - Factor shared setup (seedTwoEntries, queueSubtitleLines, countLinesForAnime) into helpers and add a moveVideoToAnime coverage case	2026-08-10 23:50:37 -07:00
sudacode	73c553c6a1	fix(stats): drain full write queue before anime merge/move rebuilds - Replace single flushNow() with drainWriteQueue loop so forced telemetry appended after a full batch isn't left unwritten before merge/move/rebuild summaries recompute - Add dialog a11y to AnimeMergeDialog/LibraryEntryPicker: aria-modal, labelled headings, alert roles for errors, labelled search input, close button labels	2026-08-10 23:18:02 -07:00
sudacode	d6e6e29b5e	fix(stats): fix data loss and error handling in anime merge/move - flush pending telemetry before merge/move so in-progress session time isn't dropped from lifetime totals - repoint subtitle lines by video_id instead of anime_id so lines recorded before the async title parse assigns a link aren't stranded - stop absorbing metadata into the target when moving an episode out of an emptied entry (a move isn't a same-show claim) - return 404 only for missing episode/target, not storage failures; return 404 when a merge folds nothing - keep AnimeMergeDialog open while a merge is in flight instead of letting dismiss race the request - surface library load failures in LibraryEntryPicker instead of showing an empty list	2026-08-10 23:06:00 -07:00
sudacode	5938095d92	feat(stats): add library entry merge and episode move - Add multi-select "Merge Selected" flow to fold duplicate library cards into one, preserving sessions, mined cards, and watch time - Add per-episode "move to another entry" action for reassigning stray episodes, pruning the source entry when emptied - Auto-merge library entries that resolve to the same AniList id when their parsed seasons are compatible - Add mergeAnime/moveVideoToAnime service methods, stats-server routes, and HTTP contract types	2026-08-10 22:52:34 -07:00
sudacode	2fefc83e3f	fix(playback): stop forcing legacy OpenGL renderer on X11 mpv backend (#188 )	2026-08-06 23:52:35 -07:00
sudacode	dbdf578c68	perf(tokenizer): single-pass Yomitan scan with cross-line caching and prefetch fixes (#185 )	2026-08-06 21:44:09 -07:00
sudacode	441ecf3c04	feat(overlay): add in-app changelog modal (#187 )	2026-08-05 22:19:13 -07:00
sudacode	a0dde4ee3e	chore(release): v0.19.2	2026-08-04 18:51:15 -07:00
sudacode	fe4dacc1e7	fix(overlay): show plain subtitle line immediately on tokenization cache miss (#184 )	2026-08-04 01:55:52 -07:00
sudacode	b08cd0db35	fix(streaming): keep subtitle tokenization prefetch warm for full episodes (#183 )	2026-08-03 21:22:18 -07:00
sudacode	bffb1c5982	fix(logging): surface subtitle processing debug/warn logs (#182 )	2026-08-03 20:44:39 -07:00
sudacode	5b8848518a	feat(subsync): add reference and target subtitle track picker (#181 )	2026-08-03 01:00:14 -07:00
sudacode	176edd67f1	chore(release): v0.19.1	2026-08-01 23:59:20 -07:00
sudacode	4d65dec340	fix(youtube): prevent playlist URLs from stalling yt-dlp probes (#180 )	2026-08-01 22:56:28 -07:00
sudacode	6607c333bc	fix(overlay): strip spinner frame from subsync overlay card - Add overlayBody override to ConfiguredStatusNotificationOptions so overlay/OSD/desktop can diverge - Extract getSubsyncStatusNotificationOptions() to strip the ASCII spinner frame from the overlay card (OSD keeps it since it renders the raw spinner) - Add tests for spinner stripping and subsync result notifications	2026-07-31 18:03:26 -07:00
sudacode	b2bbf1ae12	chore: regenerate config example artifacts	2026-07-31 17:49:02 -07:00
sudacode	b204d4dd6e	feat(anki): add configurable word card type for Kiku/Lapis (#175 )	2026-07-31 17:17:29 -07:00
sudacode	89ed675935	fix(overlay): keep Yomitan popup interactive on macOS/Windows (#177 )	2026-07-30 19:47:08 -07:00
sudacode	1995200e76	chore(release): prepare v0.19.0	2026-07-29 22:26:03 -07:00
sudacode	e876e483d6	chore(release): prepare v0.19.0-beta.5	2026-07-29 02:09:01 -07:00
sudacode	6d2a72e13b	feat(stats): add library entry deletion and app-wide delete progress (#174 )	2026-07-29 02:00:16 -07:00
sudacode	0d7084c8aa	fix(anilist): resolve later seasons via sequel relations, not title guessing (#173 )	2026-07-28 22:56:26 -07:00
sudacode	95e0abc7b7	test(immersion): apply runtime SQLite pragmas in query tests The query test suite opened each temp database with SQLite's defaults (rollback journal, synchronous=FULL) while the runtime opens them via applyPragmas (WAL, synchronous=NORMAL). Every statement therefore ran as its own fsync-ing transaction. That is unnoticeable on a fast local disk but dominates on CI: the file took 40.6s there versus 0.5s locally, and the 106-insert case 'getVocabularyStats pages past hidden rows' crossed the 5s per-test timeout and failed the quality gate. Open test databases through a helper that applies the same pragmas as production, so the tests exercise the runtime's actual SQLite configuration instead of a slower one.	2026-07-28 02:23:16 -07:00
sudacode	d9155ceacb	docs: update requirements table and Windows install instructions - Add TsukiHime and AniSkip to feature table; note xz dependency - Clarify Anki+AnkiConnect is required to mine, not to run - Rework Windows setup with winget/scoop commands and PATH steps - Note ffmpeg has no path-override setting, unlike mpv - Fix screenshot alt text and installation.md anchor link	2026-07-28 02:10:50 -07:00