test(stats): click backdrop, not disabled button, in cleanup close test

- Assert the Close button is disabled while apply is in flight
- Click the always-enabled backdrop instead, since that's the path that actually reaches the close guard

CHANGELOG.md

@@ -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

bun.lock

@@ -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=="],

changes/anki-maturity-known-word-highlighting.md

@@ -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.

changes/annotation-noise-rule-table.md

@@ -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.

changes/changelog-modal.md

@@ -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.

changes/configurable-clipboard-video-shortcut.md

@@ -1,4 +0,0 @@
-type: changed
-area: shortcuts
-
-- Made the clipboard-video playlist shortcut configurable through `shortcuts.appendClipboardVideoToQueue`.

changes/duplicate-line-stats-cleanup.md

@@ -0,0 +1,5 @@
+type: fixed
+area: stats
+
+- Typeset subtitles no longer flood the stats. Karaoke openings and animated signs are authored as one subtitle event per animation frame, and immersion tracking counted every frame, which was enough to put an OP lyric at the top of "Top Repeated Words" for good. Lines are now collapsed on the way in using the same rules the subtitle sidebar already applies: when the active subtitle file has been parsed, stats record exactly the cues the sidebar shows, and for sources with no parsed cue list a run of identical, contiguous, sub-0.1s lines stops counting after a few frames. Ordinary repeated dialogue and rewatches are unaffected.
+- Added a cleanup for stats already affected. The Vocabulary tab has a **Duplicates** button that scans a chosen window (7 days through all time), shows the bursts it found and the word and kanji counts they added, and collapses each run to one line once confirmed. `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>`. Only subtitle lines and the vocabulary counts they feed are touched; watch time and lines-seen totals are left as recorded.

changes/fix-anilist-season-resolution.md

@@ -1,8 +0,0 @@
-type: fixed
-area: anilist
-
-- Season 2 and later files now resolve to the right AniList entry. AniList has no numbered seasons (sequels are separate entries titled `Zoku`, `Kan`, `2nd Season`), so the old `<title> Season N` search returned nothing and silently fell back to the season 1 entry: an Oregairu S03 episode loaded the season 1 character dictionary and pushed watch progress onto season 1. SubMiner now searches the base title and walks AniList `SEQUEL` relations to reach the requested season, ordering the franchise's TV entries by air date when the relation chain is incomplete.
-- When the season still cannot be located, SubMiner no longer writes progress to the season 1 entry; it skips the update and points at the manual AniList override instead. The character dictionary logs the same warning and states which entry it fell back to.
-- Character dictionary overrides are now scoped by detected season as well as directory, so seasons kept in one flat folder no longer share (or overwrite) each other's override, and an override now also pins the entry used for AniList watch progress: correcting a wrong match once fixes both the dictionary and progress tracking.
-- Cover art lookup uses the same season-aware resolution, so per-season art no longer falls back to the season 1 cover.
-- An unresolvable season is no longer cached as if it were a normal match, so the fallback cannot silently stick for every later episode of that series.

changes/fix-anki-proxy-port-reuse.md

@@ -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.

changes/fix-appimage-quit-service-crash.md

@@ -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.

changes/fix-character-dictionary-season-overrides.md

@@ -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.

changes/fix-startup-pause-untokenized-release.md

@@ -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.

changes/fix-stats-known-word-cache-format.md

@@ -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.

changes/fix-stats-library-cover-after-relink.md

@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
-- Relinking a title to a different AniList entry now updates its cover in the stats Library grid too. The detail view picked up the new art immediately while the grid kept the previous entry's image, so several unrelated titles could end up sharing one wrong cover. The library list is refetched after a relink, and cover responses now carry an ETag and revalidate instead of being cached for a day, so a stale image can no longer be served from the browser cache.

changes/golden-tokenizer-corpus.md

@@ -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).

changes/history-post-playback-menu.md

@@ -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.

changes/renderer-modal-registry.md

@@ -1,4 +0,0 @@
-type: internal
-area: overlay
-
-- Consolidated renderer modal state handling into a descriptor registry.

changes/reusable-ci-quality-gate.md

@@ -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.

changes/rofi-prompt-spacing.md

@@ -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.

changes/split-resolvers.md

@@ -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.

changes/stats-delete-library-entry.md

@@ -1,5 +0,0 @@
-type: added
-area: stats
-
-- Added a "Delete Entry" action to the stats Library detail view. It removes the whole title in one step — every episode, session, subtitle line, rollup, cover art and vocabulary counts derived from them — and the title disappears from the Library grid. Previously only individual episodes and sessions could be deleted, so a mistakenly created entry had to be cleared episode by episode and still lingered in the library.
-- Deletion progress is now shown app-wide instead of only on Overview and Sessions. Every delete (session, session group, episode, and library entry) drives a sweeping bar at the top of the window plus a bottom-right status toast, and both stay visible across tab switches, detail views, and the in-app stats overlay window. The per-tab indicators previously went blank the moment you left the tab that started the delete.

changes/stats-delete-performance.md

@@ -1,7 +0,0 @@
-type: fixed
-area: stats
-
-- Made deleting stats data much faster and stopped it stalling playback. Every delete used to recompute each affected word's totals by re-reading that word's whole occurrence history across the library, which meant one random read into the largest table per occurrence. On a 960-session library that cost 3.8s to delete a single session and over a minute to clear a 12-episode title, and because the stats server runs in the app process when the app owns it, that time was spent blocking mpv.
-- Word and kanji occurrences now store the subtitle line's timestamp alongside the count, so those totals are answered from a covering index instead of the subtitle-line table, and a delete only subtracts what it actually removed rather than recomputing untouched entries. Measured on the same 960-session library: deleting one session 3832ms to 190ms, a ten-session day group 6453ms to 433ms, one episode 5437ms to 263ms, and a whole 12-episode title 60556ms to 621ms.
-- Opening the Vocabulary tab no longer stalls either. It was computing "seen in N titles" for every word in the library before ordering by frequency and keeping the top 100, so the whole occurrence history was walked to produce one page. It now picks the page first and counts only those rows: 2136ms to 62ms on the same library.
-- The first launch after upgrading migrates the existing stats database in place (about 3s for a 288k-line library) and it grows roughly 20% from the added index. Vocabulary dates recorded before the upgrade keep working while the migration runs.

changes/styled-subtitle-cue-parsing.md

@@ -0,0 +1,5 @@
+type: fixed
+area: subtitles
+
+- Heavily typeset ASS scripts (karaoke OP/ED, sign work) no longer fill the subtitle sidebar with garbage. Vector drawing runs (`\p1` … `\p0`) are no longer shown as subtitle text (e.g. `m 20 0 b 10 0 0 10 0 20 …`), and duplicate events in a parsed subtitle file collapse into one cue: identical text over an identical span (layered "shadow" copies), and per-frame animation bursts. An ASS burst has to prove itself with authoring evidence — a temporal tag (`\t`, `\move`, karaoke timing), an animated `Effect` column, or override values that change from event to event — plus one shared style and actor, so three rapid `えっ` reactions from three characters, or a sign repeated with the same static `\clip`, stay separate. SRT and VTT carry no such metadata, so there the run has to be at least five contiguous events all shorter than 0.1s, which is where ASS-to-SRT conversion leaves karaoke frames.
+- Subtitle text is now decoded from ASS exactly once, where it enters the app, and matches how mpv renders the same line (including `\N`, `\n`, `\h`, unclosed `{`, and the fact that `\{` is not an escape). Renderer, timing tracker, tokenizer and the tokenization cache take that decoded text as-is instead of each re-deriving it, so one authored line can no longer produce two different cache keys, and a cue that normalizes to nothing is no longer stored as subtitle text or cached under an empty key.

changes/subtitle-tokenization-performance.md

@@ -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.

changes/sync.md

@@ -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).

changes/tsukihime-english-subtitles.md

@@ -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.

changes/unify-stats-transport-types.md

@@ -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.

changes/verify-known-word-highlights-script.md

@@ -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.

changes/x11-backend-keeps-mpv-renderer.md

@@ -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.

config.example.jsonc

@@ -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.
 
   // ==========================================

docs-site/anki-integration.md

@@ -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.
@@ -313,11 +328,11 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
 
 ### What Gets Merged
 
-| Field    | Merge behavior                          |
-| -------- | ---------------------------------------- |
+| Field    | Merge behavior                                |
+| -------- | --------------------------------------------- |
 | Sentence | Both cards' sentences kept as grouped entries |
-| Audio    | Both cards' `[sound:...]` entries kept  |
-| Image    | Both cards' images kept                 |
+| Audio    | Both cards' `[sound:...]` entries kept        |
+| Image    | Both cards' images kept                       |
 
 Identical values from both cards are kept as separate grouped entries; the merge does not deduplicate.
 

docs-site/architecture.md

@@ -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, ...)

docs-site/changelog.md

@@ -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>

docs-site/configuration.md

@@ -398,30 +398,30 @@ 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.                                 |
-| `enableJlpt`                       | boolean  | Enable JLPT level underline styling (`false` by default)                                                                     |
-| `preserveLineBreaks`               | boolean  | Preserve line breaks in visible overlay subtitle rendering (`false` by default). Enable to mirror mpv line layout.           |
-| `autoPauseVideoOnHover`            | boolean  | Pause playback while mouse hovers subtitle text, then resume on leave (`true` by default).                                   |
-| `autoPauseVideoOnYomitanPopup`     | boolean  | Pause playback while the Yomitan popup is open, then resume when the popup closes (`true` by default).                       |
-| `primaryVisibleOnYomitanPopup`     | boolean  | Keep hover-mode primary subtitles visible while the Yomitan popup is open (`true` by default).                               |
-| `nameMatchEnabled`                 | boolean  | Enable character dictionary sync and subtitle token coloring for character-name matches (`false` by default)                 |
-| `nameMatchImagesEnabled`           | boolean  | Show small cached AniList character portraits beside matched character-name tokens (`false` by default)                      |
-| `nameMatchColor`                   | string   | Hex color used for subtitle tokens matched from the SubMiner character dictionary (default: `#f5bde6`)                       |
-| `knownWordColor`                   | string   | Hex color used for known-word subtitle highlights (default: `#a6da95`)                                                       |
+| 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.                                                                              |
+| `enableJlpt`                       | boolean  | Enable JLPT level underline styling (`false` by default)                                                                                                                  |
+| `preserveLineBreaks`               | boolean  | Preserve line breaks in visible overlay subtitle rendering (`false` by default). Enable to mirror mpv line layout.                                                        |
+| `autoPauseVideoOnHover`            | boolean  | Pause playback while mouse hovers subtitle text, then resume on leave (`true` by default).                                                                                |
+| `autoPauseVideoOnYomitanPopup`     | boolean  | Pause playback while the Yomitan popup is open, then resume when the popup closes (`true` by default).                                                                    |
+| `primaryVisibleOnYomitanPopup`     | boolean  | Keep hover-mode primary subtitles visible while the Yomitan popup is open (`true` by default).                                                                            |
+| `nameMatchEnabled`                 | boolean  | Enable character dictionary sync and subtitle token coloring for character-name matches (`false` by default)                                                              |
+| `nameMatchImagesEnabled`           | boolean  | Show small cached AniList character portraits beside matched character-name tokens (`false` by default)                                                                   |
+| `nameMatchColor`                   | string   | Hex color used for subtitle tokens matched from the SubMiner character dictionary (default: `#f5bde6`)                                                                    |
+| `knownWordColor`                   | string   | Hex color used for known-word subtitle highlights (default: `#a6da95`)                                                                                                    |
 | `knownWordMaturityColors`          | object   | Per-tier known-word colors used when `ankiConnect.knownWords.maturityEnabled` is on: `new` (`#ee99a0`), `learning` (`#b7bdf8`), `young` (`#91d7e3`), `mature` (`#a6da95`) |
-| `nPlusOneColor`                    | string   | Hex color used for the single N+1 target subtitle highlight (default: `#c6a0f6`)                                             |
-| `frequencyDictionary.enabled`      | boolean  | Enable frequency highlighting from dictionary lookups (`false` by default)                                                   |
-| `frequencyDictionary.sourcePath`   | string   | Path to a local frequency dictionary root. Leave empty or omit to use installed/default frequency-dictionary search paths.   |
-| `frequencyDictionary.topX`         | number   | Only color tokens whose frequency rank is `<= topX` (`10000` by default)                                                     |
-| `frequencyDictionary.mode`         | string   | `"single"` or `"banded"` (`"single"` by default)                                                                             |
-| `frequencyDictionary.matchMode`    | string   | `"headword"` or `"surface"` (`"headword"` by default)                                                                        |
-| `frequencyDictionary.singleColor`  | string   | Color used for all highlighted tokens in single mode                                                                         |
-| `frequencyDictionary.bandedColors` | string[] | Array of five hex colors used for ranked bands in banded mode                                                                |
-| `jlptColors`                       | object   | JLPT level underline colors object (`N1`..`N5`)                                                                              |
+| `nPlusOneColor`                    | string   | Hex color used for the single N+1 target subtitle highlight (default: `#c6a0f6`)                                                                                          |
+| `frequencyDictionary.enabled`      | boolean  | Enable frequency highlighting from dictionary lookups (`false` by default)                                                                                                |
+| `frequencyDictionary.sourcePath`   | string   | Path to a local frequency dictionary root. Leave empty or omit to use installed/default frequency-dictionary search paths.                                                |
+| `frequencyDictionary.topX`         | number   | Only color tokens whose frequency rank is `<= topX` (`10000` by default)                                                                                                  |
+| `frequencyDictionary.mode`         | string   | `"single"` or `"banded"` (`"single"` by default)                                                                                                                          |
+| `frequencyDictionary.matchMode`    | string   | `"headword"` or `"surface"` (`"headword"` by default)                                                                                                                     |
+| `frequencyDictionary.singleColor`  | string   | Color used for all highlighted tokens in single mode                                                                                                                      |
+| `frequencyDictionary.bandedColors` | string[] | Array of five hex colors used for ranked bands in banded mode                                                                                                             |
+| `jlptColors`                       | object   | JLPT level underline colors object (`N1`..`N5`)                                                                                                                           |
 
 Subtitle CSS custom properties:
 
@@ -555,11 +555,11 @@ 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"`)                                                                                                                               |
+| 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"`)                                                                                                     |
 
 These two settings apply to local and Jellyfin playback only. YouTube secondary selection is fixed to English and ignores them; see [YouTube Integration](/youtube-integration#secondary-subtitle-languages). `defaultMode` still controls how the loaded secondary bar is displayed in every case.
 
@@ -1043,7 +1043,7 @@ This example is intentionally compact. The option table below documents availabl
 | `ankiConnect.knownWords.refreshMinutes`           | number                                      | Minutes between known-word cache refreshes (default: `1440`)                                                                                                                                                                    |
 | `ankiConnect.knownWords.decks`                    | object                                      | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word"] }`).                                                                                                                                 |
 | `ankiConnect.knownWords.maturityEnabled`          | `true`, `false`                             | Color known words by Anki card maturity (new/learning/young/mature) instead of one color. Requires `knownWords.highlightEnabled` (default: `false`). Tier colors come from `subtitleStyle.knownWordMaturityColors`.             |
-| `ankiConnect.knownWords.matureThresholdDays`      | number                                      | Card interval in days at which a known word counts as mature (default: `21`, matching Anki's own convention)                                                                                                                   |
+| `ankiConnect.knownWords.matureThresholdDays`      | number                                      | Card interval in days at which a known word counts as mature (default: `21`, matching Anki's own convention)                                                                                                                    |
 | `ankiConnect.nPlusOne.enabled`                    | `true`, `false`                             | Enable N+1 subtitle highlighting (highlights the one unknown word in a sentence). Independent from `knownWords.highlightEnabled`. Requires known-word cache data (default: `false`).                                            |
 | `ankiConnect.nPlusOne.minSentenceWords`           | number                                      | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                                                                                                          |
 | `behavior.notificationType`                       | `"overlay"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"overlay"`). `"both"` means overlay + system. `osd` and `osd-system` are legacy config-file-only values; use `"osd-system"` to keep the old OSD + system behavior.                  |
@@ -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
 
@@ -1167,10 +1185,10 @@ TsukiHime subtitle search works out of the box and needs no account or API key.
 }
 ```
 
-| Option                       | Values       | Description                                                                                          |
-| ---------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| 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)                       |
+| `tsukihime.maxSearchResults` | number       | Maximum releases returned per search (default: `10`; the API caps this at 100)                        |
 
 The keyboard shortcut lives under `shortcuts.openTsukihime` (default `Ctrl+Shift+T`; set to `null` to disable). The older `animetosho` section and `shortcuts.openAnimetosho` are still accepted as deprecated aliases, with the current names taking precedence when both are set.
 
@@ -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
@@ -1228,17 +1246,17 @@ 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`) |
-| `characterDictionary.refreshTtlHours`                          | number              | Hours before a cached media snapshot is refreshed (default: `168`, clamped to 1–8760)                         |
-| `characterDictionary.evictionPolicy`                           | `"delete"`, `"disable"` | What happens to snapshots evicted beyond `maxLoaded` (default: `"delete"`)                                |
-| `characterDictionary.collapsibleSections.description`          | `true`, `false`     | Open the Description section by default in generated dictionary entries                                       |
-| `characterDictionary.collapsibleSections.characterInformation` | `true`, `false`     | Open the Character Information section by default in generated dictionary entries                             |
-| `characterDictionary.collapsibleSections.voicedBy`             | `true`, `false`     | Open the Voiced by section by default in generated dictionary entries                                         |
-| `characterDictionary.profileScope`                             | `"all"`, `"active"` | Apply dictionary settings updates to all Yomitan profiles or only active profile                              |
+| 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`) |
+| `characterDictionary.refreshTtlHours`                          | number                  | Hours before a cached media snapshot is refreshed (default: `168`, clamped to 1–8760)                         |
+| `characterDictionary.evictionPolicy`                           | `"delete"`, `"disable"` | What happens to snapshots evicted beyond `maxLoaded` (default: `"delete"`)                                    |
+| `characterDictionary.collapsibleSections.description`          | `true`, `false`         | Open the Description section by default in generated dictionary entries                                       |
+| `characterDictionary.collapsibleSections.characterInformation` | `true`, `false`         | Open the Character Information section by default in generated dictionary entries                             |
+| `characterDictionary.collapsibleSections.voicedBy`             | `true`, `false`         | Open the Voiced by section by default in generated dictionary entries                                         |
+| `characterDictionary.profileScope`                             | `"all"`, `"active"`     | Apply dictionary settings updates to all Yomitan profiles or only active profile                              |
 
 When `enabled` is `true` and `accessToken` is empty, SubMiner opens an AniList setup helper window. Keep `enabled` as `false` to disable all AniList setup/update behavior.
 
@@ -1539,18 +1557,18 @@ 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"`)                                                                                  |
+| 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"`)                                                                                                                          |
 | `socketPath`             | string                                                                      | mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin (platform-dependent default: `/tmp/subminer-socket`, or `\\\\.\\pipe\\subminer-socket` on Windows) |
-| `backend`                | `"auto"` \| `"hyprland"` \| `"sway"` \| `"x11"` \| `"macos"` \| `"windows"` | Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform (default: `"auto"`)                             |
-| `autoStartSubMiner`      | `true`, `false`                                                             | Start SubMiner in the background when SubMiner-managed mpv loads a file (default: `true`)                                                   |
-| `pauseUntilOverlayReady` | `true`, `false`                                                             | Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness, with a 30-second fallback (default: `true`) |
-| `subminerBinaryPath`     | string                                                                      | SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path (default: `""`)                |
-| `aniskipEnabled`         | `true`, `false`                                                             | Enable AniSkip intro detection, chapter markers, and the skip-intro key (default: `true`)                                                   |
-| `aniskipButtonKey`       | string                                                                      | mpv key used to skip the detected intro while the skip prompt is visible (default: `"TAB"`)                                                 |
+| `backend`                | `"auto"` \| `"hyprland"` \| `"sway"` \| `"x11"` \| `"macos"` \| `"windows"` | Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform (default: `"auto"`)                                                                     |
+| `autoStartSubMiner`      | `true`, `false`                                                             | Start SubMiner in the background when SubMiner-managed mpv loads a file (default: `true`)                                                                                           |
+| `pauseUntilOverlayReady` | `true`, `false`                                                             | Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness, with a 30-second fallback (default: `true`)                                         |
+| `subminerBinaryPath`     | string                                                                      | SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path (default: `""`)                                                        |
+| `aniskipEnabled`         | `true`, `false`                                                             | Enable AniSkip intro detection, chapter markers, and the skip-intro key (default: `true`)                                                                                           |
+| `aniskipButtonKey`       | string                                                                      | mpv key used to skip the detected intro while the skip prompt is visible (default: `"TAB"`)                                                                                         |
 
 If `mpv.profile` is configured and the launcher also receives `--profile`, SubMiner passes both as a comma-separated mpv profile list.
 

docs-site/immersion-tracking.md

@@ -34,7 +34,7 @@ The same immersion data powers the stats dashboard.
 - In-app overlay: focus the visible overlay, then press the key from `stats.toggleKey` (default: `` ` `` / `Backquote`).
 - Launcher command: run `subminer stats` to start the local stats server on demand (it also opens the dashboard in your browser when `stats.autoOpenBrowser` is enabled; the default is `false`).
 - Background server: run `subminer stats -b` to start or reuse a dedicated background stats daemon without keeping the launcher attached, and `subminer stats -s` to stop that daemon.
-- Maintenance commands: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand; `subminer stats cleanup -l` repairs lifetime summary tables. `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
+- Maintenance commands: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand; `subminer stats cleanup -l` repairs lifetime summary tables; `subminer stats cleanup --duplicate-lines` collapses repeated lines left behind by typeset subtitles (see [Repeated Line Cleanup](#repeated-line-cleanup)). `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
 - Browser page: open `http://127.0.0.1:6969` directly if the local stats server is already running.
 
 ### Dashboard Tabs
@@ -125,6 +125,32 @@ Secondary subtitle text (typically English translations) is stored alongside pri
 
 The Vocabulary tab toolbar includes an **Exclusions** button for hiding words from all vocabulary views. Excluded words are stored in the immersion database, with older browser localStorage exclusions imported on first load after upgrade. They can be managed (restored or cleared) from the exclusion modal. Exclusions affect stat cards, charts, the frequency rank table, and the word list.
 
+### Repeated Line Cleanup
+
+Karaoke openings and animated signs are authored as one subtitle event per animation frame, all carrying the same text. Playback reports every one of those frames, so a single OP lyric could be recorded hundreds of times and dominate "Top Repeated Words".
+
+Recording now collapses those runs as they happen, matching what the subtitle sidebar shows:
+
+- When the active subtitle source has been parsed, its cue list has already had duplicate events and animation bursts merged. A line landing inside a surviving cue but after that cue's start is a frame the sidebar merged away, and is not recorded.
+- Otherwise only timing is available, so the strict metadata-free rule applies: a run of identical, contiguous lines each shorter than 0.1s stops being recorded after a few frames. Ordinary repeated dialogue, and lines held for a normal beat, always record.
+
+For stats recorded before this, the Vocabulary tab toolbar has a **Duplicates** button:
+
+- Pick how far back to look (7 days, 30 days, 90 days, 1 year, or all time). A narrower window does less work and keeps older history untouched.
+- **Scan** reports the bursts found, the lines they added, and the word and kanji counts they inflated, without writing anything.
+- **Clean Up** applies exactly what the scan reported: each run collapses to its first line (extended to cover the run), and the removed lines' word and kanji occurrences are subtracted from the vocabulary aggregates.
+
+The same thing runs from the terminal:
+
+```bash
+subminer stats cleanup --duplicate-lines --dry-run --lookback-days 30
+subminer stats cleanup --duplicate-lines --lookback-days 30
+```
+
+`--duplicate-lines` (short: `-d`) picks the cleanup mode, so it cannot be combined with `--lifetime`, and `--dry-run` and `--lookback-days <days>` only apply to it. Omitting `--lookback-days` scans all history; the value must be at least one day.
+
+Runs never cross a session boundary, so rewatching an episode keeps both watches. Session telemetry (watch time, lines seen, tokens seen) and the rollups derived from it are left as recorded: they are cumulative samples taken during playback, and cannot be recomputed for sessions whose raw rows have since been pruned.
+
 ## Retention Defaults
 
 By default, SubMiner keeps all retention tables and raw data (`0` means keep all) while continuing daily/monthly rollup maintenance:

docs-site/launcher-script.md

@@ -151,6 +151,7 @@ subminer stats -b                       # start background stats daemon
 | `subminer stats`                           | Start the stats server (opens the dashboard when `stats.autoOpenBrowser` is on)                   |
 | `subminer stats -b` / `-s`                 | Start/reuse or stop the background stats daemon                                                   |
 | `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows (`-v` vocab, `-l` lifetime summaries)           |
+| `subminer stats cleanup -d`                | Collapse repeated lines from typeset subs (`--dry-run`, `--lookback-days <n>`)                    |
 | `subminer stats rebuild` / `backfill`      | Rebuild or backfill rollup data                                                                   |
 | `subminer doctor`                          | Dependency + config + socket diagnostics (`--refresh-known-words` refreshes the known-word cache) |
 | `subminer settings`                        | Open the SubMiner settings window                                                                 |

docs-site/mining-workflow.md

@@ -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.
 

docs-site/public/config.example.jsonc

@@ -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.
 
   // ==========================================

docs-site/troubleshooting.md

@@ -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).
 

docs-site/usage.md

@@ -95,6 +95,8 @@ subminer texthooker               # Texthooker-only mode (-o also opens the brow
 subminer stats -b                 # Start/reuse the background stats daemon
 subminer stats -s                 # Stop the background stats daemon
 subminer stats cleanup            # Backfill vocabulary metadata, prune stale rows
+subminer stats cleanup -d --dry-run  # Preview cleanup of repeated typeset subtitle lines
+subminer stats cleanup -d --lookback-days 30  # Clean only lines recorded in the last 30 days
 subminer stats rebuild            # Rebuild rollup data
 subminer doctor --refresh-known-words  # Refresh the known-word cache
 subminer logs -e                  # Export a sanitized log ZIP and print its path
@@ -145,11 +147,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 +372,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

docs-site/websocket-texthooker-api.md

@@ -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

docs-site/youtube-integration.md

@@ -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.

docs/architecture/2026-03-15-renderer-performance-design.md

@@ -64,18 +64,23 @@ External subtitle files only (SRT, VTT, ASS). Embedded subtitle tracks are out o
 A cue parser extracts both timing and text content from subtitle files for prefetching.
 
 **Parsed cue structure:**
+
 ```typescript
 interface SubtitleCue {
-  startTime: number;  // seconds
-  endTime: number;    // seconds
-  text: string;       // raw subtitle text
+  startTime: number; // seconds
+  endTime: number; // seconds
+  text: string; // plain text, decoded from the source format
 }
 ```
 
 **Supported formats:**
+
 - SRT/VTT: Regex-based parsing of timing lines + text content between timing blocks.
-- ASS: Parse `[Events]` section, extract `Dialogue:` lines, split on the first 9 commas only (ASS v4+ has 10 fields; the last field is Text which can itself contain commas). Strip ASS override tags (`{\...}`) from the text before storing.
-  ASS text fields contain inline override tags like `{\b1}`, `{\an8}`, `{\fad(200,300)}`. The cue parser strips these during extraction so the tokenizer receives clean text.
+- ASS: Parse `[Events]` section, extract `Dialogue:` lines, read the field order from the `Format:` row, and take everything after the Text field index as the text (Text can itself contain commas).
+
+**ASS decoding.** The parser is where ASS text is decoded, once, via `assToPlainText()` in `src/core/services/ass-text.ts`. That decoder mirrors mpv's `ass_to_plaintext` so a cue read from a file reads identically to the same line arriving live on `sub-text`: `{...}` override blocks are markup, `\pN … \p0` vector drawing runs are dropped rather than shown as text, `\N`/`\n`/`\h` are the only escapes (`\{`, `\}` and `\\` are not), and an unclosed `{` is rendered verbatim. Every layer downstream — renderer, timing tracker, tokenizer, tokenization cache keys — receives plain text and uses `normalizePlainSubtitleText()` for whitespace only, so nothing decodes the same string twice and one authored line always maps to one cache key.
+
+**Duplicate collapsing.** Typeset scripts emit one `Dialogue:` event per animation frame, plus layered copies of the same line. The parser collapses identical text over an identical span unconditionally, and collapses contiguous same-text runs of at least three events when the run looks like an animation. For ASS that means shared style and actor plus authoring evidence: a temporal tag (`\t`, `\move`, `\k`/`\kf`/`\ko`/`\K`, or anything wrapped in `\t(...)`), an animated `Effect` column (`Karaoke`, `Banner`, `Scroll`), or override values that change across the run. Static tags shared by every event (`\pos`, an identical `\clip`) are not evidence. SRT/VTT carry no such metadata, so there collapsing needs at least five contiguous events all under 0.1s — the frame timing left behind by ASS-to-SRT conversion. The parser keeps this authoring metadata (style, actor, layer, `Effect`, parsed override commands, source order) private; `parseSubtitleCues()` returns only `SubtitleCue`.
 
 #### Prefetch Service Lifecycle
 
@@ -153,6 +158,7 @@ tokens (already have frequencyRank values from parser-level applyFrequencyRanks)
 ### Dependency Analysis
 
 All annotations either depend on MeCab POS data or benefit from running after it:
+
 - **Known word marking:** Needs base tokens (surface/headword). No POS dependency, but no reason to run separately.
 - **Frequency filtering:** Uses `pos1Exclusions` and `pos2Exclusions` to clear frequency ranks on excluded tokens (particles, noise). Depends on MeCab POS data.
 - **JLPT marking:** Uses `shouldIgnoreJlptForMecabPos1` to filter. Depends on MeCab POS data.
@@ -169,18 +175,14 @@ function annotateTokens(tokens, deps, options): MergedToken[] {
 
   // Single pass: known word + frequency filtering + JLPT computed together
   const annotated = tokens.map((token) => {
-    const isKnown = nPlusOneEnabled
-      ? token.isKnown || computeIsKnown(token, deps)
-      : false;
+    const isKnown = nPlusOneEnabled ? token.isKnown || computeIsKnown(token, deps) : false;
 
     // Filter frequency rank using POS exclusions (rank values already set at parser level)
     const frequencyRank = frequencyEnabled
       ? filterFrequencyRank(token, pos1Exclusions, pos2Exclusions)
       : undefined;
 
-    const jlptLevel = jlptEnabled
-      ? computeJlptLevel(token, deps.getJlptLevel)
-      : undefined;
+    const jlptLevel = jlptEnabled ? computeJlptLevel(token, deps.getJlptLevel) : undefined;
 
     return { ...token, isKnown, frequencyRank, jlptLevel };
   });
@@ -221,6 +223,7 @@ Replace `document.createElement('span')` calls in the renderer with `templateSpa
 ### Current Behavior
 
 In `renderWithTokens` (`subtitle-render.ts`), each render cycle:
+
 1. Clears DOM with `innerHTML = ''`
 2. Creates a `DocumentFragment`
 3. Calls `document.createElement('span')` for each token (~10-15 per subtitle)
@@ -256,27 +259,30 @@ Full recycling (collecting old nodes, clearing attributes, reusing them) require
 
 ## Combined Impact Summary
 
-| Scenario | Before | After | Improvement |
-|----------|--------|-------|-------------|
-| Normal playback (prefetch-warmed) | ~200-320ms | ~30-50ms | ~80-85% |
-| Cache hit (repeated subtitle) | ~72ms | ~55-65ms | ~10-20% |
-| Cache miss (immediate seek) | ~200-320ms | ~150-260ms | ~20-25% |
+| Scenario                          | Before     | After      | Improvement |
+| --------------------------------- | ---------- | ---------- | ----------- |
+| Normal playback (prefetch-warmed) | ~200-320ms | ~30-50ms   | ~80-85%     |
+| Cache hit (repeated subtitle)     | ~72ms      | ~55-65ms   | ~10-20%     |
+| Cache miss (immediate seek)       | ~200-320ms | ~150-260ms | ~20-25%     |
 
 ---
 
 ## Files Summary
 
 ### New Files
+
 - `src/core/services/subtitle-prefetch.ts`
 - `src/core/services/subtitle-cue-parser.ts`
 
 ### Modified Files
+
 - `src/core/services/subtitle-processing-controller.ts` (expose `preCacheTokenization`)
 - `src/core/services/tokenizer/annotation-stage.ts` (batched single-pass)
 - `src/renderer/subtitle-render.ts` (template cloneNode)
 - `src/main.ts` (wire up prefetch service)
 
 ### Test Files
+
 - New tests for subtitle cue parser (SRT, VTT, ASS formats)
 - New tests for subtitle prefetch service (priority window, seek, pause/resume)
 - Updated tests for annotation stage (same behavior, new implementation)

docs/architecture/subtitle-overlay-priming.md

@@ -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

launcher/commands/stats-command.ts

@@ -157,6 +157,15 @@ export async function runStatsCommand(
     if (args.statsCleanupLifetime) {
       forwarded.push('--stats-cleanup-lifetime');
     }
+    if (args.statsCleanupDuplicateLines) {
+      forwarded.push('--stats-cleanup-duplicate-lines');
+    }
+    if (args.statsCleanupDryRun) {
+      forwarded.push('--stats-cleanup-dry-run');
+    }
+    if (args.statsCleanupLookbackDays) {
+      forwarded.push('--stats-cleanup-lookback-days', String(args.statsCleanupLookbackDays));
+    }
     if (shouldForwardLogLevel(args.logLevel)) {
       forwarded.push('--log-level', args.logLevel);
     }

launcher/config/args-normalizer.test.ts

@@ -134,6 +134,9 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
     statsLogLevel: null,
     syncTriggered: false,
     syncCliTokens: [],
@@ -185,6 +188,9 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
     statsLogLevel: null,
     syncTriggered: false,
     syncCliTokens: [],
@@ -229,6 +235,9 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
       statsCleanup: false,
       statsCleanupVocab: false,
       statsCleanupLifetime: false,
+      statsCleanupDuplicateLines: false,
+      statsCleanupDryRun: false,
+      statsCleanupLookbackDays: null,
       statsLogLevel: null,
       syncTriggered: false,
       syncCliTokens: [],
@@ -271,6 +280,9 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
     statsLogLevel: null,
     syncTriggered: false,
     syncCliTokens: [],

launcher/config/args-normalizer.ts

@@ -162,6 +162,8 @@ export function createDefaultArgs(
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
     doctor: false,
     doctorRefreshKnownWords: false,
     logsExport: false,
@@ -258,6 +260,11 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
   if (invocations.statsCleanup) parsed.statsCleanup = true;
   if (invocations.statsCleanupVocab) parsed.statsCleanupVocab = true;
   if (invocations.statsCleanupLifetime) parsed.statsCleanupLifetime = true;
+  if (invocations.statsCleanupDuplicateLines) parsed.statsCleanupDuplicateLines = true;
+  if (invocations.statsCleanupDryRun) parsed.statsCleanupDryRun = true;
+  if (invocations.statsCleanupLookbackDays !== null) {
+    parsed.statsCleanupLookbackDays = invocations.statsCleanupLookbackDays;
+  }
   if (invocations.dictionaryTarget) {
     parsed.dictionaryTarget = parseDictionaryTarget(invocations.dictionaryTarget);
   } else if (

launcher/config/cli-parser-builder.ts

@@ -37,6 +37,9 @@ export interface CliInvocations {
   statsCleanup: boolean;
   statsCleanupVocab: boolean;
   statsCleanupLifetime: boolean;
+  statsCleanupDuplicateLines: boolean;
+  statsCleanupDryRun: boolean;
+  statsCleanupLookbackDays: number | null;
   statsLogLevel: string | null;
   syncTriggered: boolean;
   syncCliTokens: string[];
@@ -53,6 +56,16 @@ export interface CliInvocations {
   texthookerOpenBrowser: boolean;
 }
 
+/** `--lookback-days` narrows the duplicate-line cleanup; anything unusable means no limit. */
+function parseStatsLookbackDays(value: unknown): number | null {
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const days = Number(value);
+  if (!Number.isFinite(days) || days <= 0) {
+    throw new Error('Stats --lookback-days must be a positive number of days.');
+  }
+  return Math.floor(days);
+}
+
 function applyRootOptions(program: Command): void {
   program
     .option(
@@ -169,6 +182,9 @@ export function parseCliPrograms(
   let statsCleanup = false;
   let statsCleanupVocab = false;
   let statsCleanupLifetime = false;
+  let statsCleanupDuplicateLines = false;
+  let statsCleanupDryRun = false;
+  let statsCleanupLookbackDays: number | null = null;
   let statsLogLevel: string | null = null;
   let syncTriggered = false;
   let syncCliTokens: string[] = [];
@@ -269,6 +285,9 @@ export function parseCliPrograms(
     .option('-s, --stop', 'Stop the background stats server')
     .option('-v, --vocab', 'Clean vocabulary rows in the stats database')
     .option('-l, --lifetime', 'Rebuild lifetime summary rows from retained data')
+    .option('-d, --duplicate-lines', 'Collapse repeated subtitle lines from typeset animations')
+    .option('--dry-run', 'Report what a cleanup would remove without changing anything')
+    .option('--lookback-days <days>', 'Only clean lines recorded in the last N days')
     .option('--log-level <level>', 'Log level')
     .action((action: string | undefined, options: Record<string, unknown>) => {
       statsTriggered = true;
@@ -289,13 +308,29 @@ export function parseCliPrograms(
       if (normalizedAction && (statsBackground || statsStop)) {
         throw new Error('Stats background and stop flags cannot be combined with stats actions.');
       }
-      if (normalizedAction !== 'cleanup' && (options.vocab === true || options.lifetime === true)) {
-        throw new Error('Stats --vocab and --lifetime flags require the cleanup action.');
+      if (
+        normalizedAction !== 'cleanup' &&
+        (options.vocab === true || options.lifetime === true || options.duplicateLines === true)
+      ) {
+        throw new Error(
+          'Stats --vocab, --lifetime and --duplicate-lines flags require the cleanup action.',
+        );
+      }
+      if (options.duplicateLines !== true && (options.dryRun === true || options.lookbackDays)) {
+        throw new Error('Stats --dry-run and --lookback-days require --duplicate-lines.');
       }
       if (normalizedAction === 'cleanup') {
         statsCleanup = true;
         statsCleanupLifetime = options.lifetime === true;
-        statsCleanupVocab = statsCleanupLifetime ? false : options.vocab !== false;
+        statsCleanupDuplicateLines = options.duplicateLines === true;
+        if (statsCleanupLifetime && statsCleanupDuplicateLines) {
+          throw new Error('Stats cleanup runs one mode at a time.');
+        }
+        // Vocabulary cleanup stays the default so `stats cleanup` keeps its old meaning.
+        statsCleanupVocab =
+          statsCleanupLifetime || statsCleanupDuplicateLines ? false : options.vocab !== false;
+        statsCleanupDryRun = options.dryRun === true;
+        statsCleanupLookbackDays = parseStatsLookbackDays(options.lookbackDays);
       } else if (normalizedAction === 'rebuild' || normalizedAction === 'backfill') {
         statsCleanup = true;
         statsCleanupLifetime = true;
@@ -483,6 +518,9 @@ export function parseCliPrograms(
       statsCleanup,
       statsCleanupVocab,
       statsCleanupLifetime,
+      statsCleanupDuplicateLines,
+      statsCleanupDryRun,
+      statsCleanupLookbackDays,
       statsLogLevel,
       syncTriggered,
       syncCliTokens,

launcher/mpv.test.ts

@@ -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',
       ],
     );

launcher/parse-args.test.ts

@@ -232,6 +232,53 @@ test('parseArgs maps lifetime stats cleanup flag', () => {
   assert.equal(parsed.statsCleanupLifetime, true);
 });
 
+test('parseArgs maps duplicate-line stats cleanup flags', () => {
+  const parsed = parseArgs(
+    ['stats', 'cleanup', '--duplicate-lines', '--dry-run', '--lookback-days', '30'],
+    'subminer',
+    {},
+  );
+
+  assert.equal(parsed.statsCleanup, true);
+  assert.equal(parsed.statsCleanupVocab, false);
+  assert.equal(parsed.statsCleanupDuplicateLines, true);
+  assert.equal(parsed.statsCleanupDryRun, true);
+  assert.equal(parsed.statsCleanupLookbackDays, 30);
+});
+
+test('parseArgs rejects duplicate-line flags without the duplicate-lines mode', () => {
+  const error = withProcessExitIntercept(() => {
+    parseArgs(['stats', 'cleanup', '--dry-run'], 'subminer', {});
+  });
+
+  assert.equal(error.code, 1);
+  assert.match(error.stderr, /--dry-run and --lookback-days require --duplicate-lines/);
+});
+
+test('parseArgs rejects combining lifetime and duplicate-line cleanup modes', () => {
+  const error = withProcessExitIntercept(() => {
+    parseArgs(['stats', 'cleanup', '--lifetime', '--duplicate-lines'], 'subminer', {});
+  });
+
+  assert.equal(error.code, 1);
+  assert.match(error.stderr, /Stats cleanup runs one mode at a time/);
+});
+
+test('parseArgs rejects unusable lookback windows', () => {
+  for (const value of ['0', '-5', 'soon']) {
+    const error = withProcessExitIntercept(() => {
+      parseArgs(
+        ['stats', 'cleanup', '--duplicate-lines', '--lookback-days', value],
+        'subminer',
+        {},
+      );
+    });
+
+    assert.equal(error.code, 1);
+    assert.match(error.stderr, /--lookback-days must be a positive number of days/);
+  }
+});
+
 test('parseArgs rejects cleanup-only stats flags without cleanup action', () => {
   const error = withProcessExitIntercept(() => {
     parseArgs(['stats', '--vocab'], 'subminer', {});
@@ -239,7 +286,10 @@ test('parseArgs rejects cleanup-only stats flags without cleanup action', () =>
 
   assert.equal(error.code, 1);
   assert.match(error.message, /exit:1/);
-  assert.match(error.stderr, /Stats --vocab and --lifetime flags require the cleanup action/);
+  assert.match(
+    error.stderr,
+    /Stats --vocab, --lifetime and --duplicate-lines flags require the cleanup action/,
+  );
 });
 
 test('parseArgs maps stats rebuild action to cleanup lifetime mode', () => {

launcher/types.ts

@@ -142,6 +142,9 @@ export interface Args {
   statsCleanup?: boolean;
   statsCleanupVocab?: boolean;
   statsCleanupLifetime?: boolean;
+  statsCleanupDuplicateLines?: boolean;
+  statsCleanupDryRun?: boolean;
+  statsCleanupLookbackDays?: number;
   dictionaryTarget?: string;
   doctor: boolean;
   doctorRefreshKnownWords: boolean;

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.19.0-beta.5",
+  "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"
       }
     ]
   },

src/anki-integration.ts

@@ -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',
-      );
-      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)),
-      ),
+    applyCardKindFlagFields(updatedFields, cardKind, (preferredName) =>
+      this.resolveFieldName(availableFieldNames, preferredName),
     );
-    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(

src/anki-integration/card-creation-manual-update.test.ts

@@ -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('字幕');

src/anki-integration/card-creation.ts

@@ -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;
         }

src/anki-integration/card-kinds.test.ts

@@ -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' });
+});

src/anki-integration/card-kinds.ts

@@ -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] = '';
+    }
+  }
+}

src/anki-integration/note-field-utils.test.ts

@@ -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',
+  );
+});

src/anki-integration/note-field-utils.ts

@@ -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;
+}

src/anki-integration/note-update-workflow.test.ts

@@ -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 () =>

src/anki-integration/note-update-workflow.ts

@@ -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;
       }

src/anki-integration/runtime.ts

@@ -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);

src/cli/args.ts

@@ -64,6 +64,9 @@ export interface CliArgs {
   statsCleanup?: boolean;
   statsCleanupVocab?: boolean;
   statsCleanupLifetime?: boolean;
+  statsCleanupDuplicateLines?: boolean;
+  statsCleanupDryRun?: boolean;
+  statsCleanupLookbackDays?: number;
   statsResponsePath?: string;
   jellyfin: boolean;
   jellyfinLogin: boolean;
@@ -167,6 +170,8 @@ export function parseArgs(argv: string[]): CliArgs {
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
     jellyfin: false,
     jellyfinLogin: false,
     jellyfinLogout: false,
@@ -368,7 +373,15 @@ export function parseArgs(argv: string[]): CliArgs {
     } else if (arg === '--stats-cleanup') args.statsCleanup = true;
     else if (arg === '--stats-cleanup-vocab') args.statsCleanupVocab = true;
     else if (arg === '--stats-cleanup-lifetime') args.statsCleanupLifetime = true;
-    else if (arg.startsWith('--stats-response-path=')) {
+    else if (arg === '--stats-cleanup-duplicate-lines') args.statsCleanupDuplicateLines = true;
+    else if (arg === '--stats-cleanup-dry-run') args.statsCleanupDryRun = true;
+    else if (arg.startsWith('--stats-cleanup-lookback-days=')) {
+      const value = Number(arg.split('=', 2)[1]);
+      if (Number.isFinite(value) && value > 0) args.statsCleanupLookbackDays = Math.floor(value);
+    } else if (arg === '--stats-cleanup-lookback-days') {
+      const value = Number(readValue(argv[i + 1]));
+      if (Number.isFinite(value) && value > 0) args.statsCleanupLookbackDays = Math.floor(value);
+    } else if (arg.startsWith('--stats-response-path=')) {
       const value = arg.split('=', 2)[1];
       if (value) args.statsResponsePath = value;
     } else if (arg === '--stats-response-path') {

src/config/config.test.ts

@@ -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(

src/config/definitions/defaults-integrations.ts

@@ -91,6 +91,9 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       fieldGrouping: 'disabled',
       deleteDuplicateInAuto: true,
     },
+    lapisKiku: {
+      wordCardKind: 'word-and-sentence',
+    },
   },
   jimaku: {
     apiBaseUrl: 'https://jimaku.cc',

src/config/definitions/options-integrations.ts

@@ -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',

src/config/definitions/template-sections.ts

@@ -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.',
     ],

src/config/resolve/anki-connect.ts

@@ -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);
 }

src/config/resolve/anki-connect/initialize.ts

@@ -77,5 +77,8 @@ export function initializeAnkiConnectResolution(
         ? (ankiConnect.isKiku as (typeof context.resolved)['ankiConnect']['isKiku'])
         : {}),
     },
+    lapisKiku: {
+      ...context.resolved.ankiConnect.lapisKiku,
+    },
   };
 }

src/config/resolve/anki-connect/lapis-kiku.ts

@@ -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;
+}

src/config/settings/registry.ts

@@ -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' ||

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

@@ -1032,6 +1032,95 @@ describe('stats server API routes', () => {
     ]);
   });
 
+  it('POST /api/stats/maintenance/duplicate-lines forwards the window and dry-run flag', async () => {
+    let seenOptions: unknown = null;
+    const summary = {
+      dryRun: true,
+      lookbackDays: 30,
+      scannedLines: 900,
+      burstGroups: 2,
+      removedLines: 180,
+      removedWordOccurrences: 540,
+      removedKanjiOccurrences: 120,
+      samples: [],
+    };
+    const app = createStatsApp(
+      createMockTracker({
+        cleanupDuplicateSubtitleLines: async (options: unknown) => {
+          seenOptions = options;
+          return summary;
+        },
+      }),
+    );
+
+    const res = await app.request('/api/stats/maintenance/duplicate-lines', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ dryRun: true, lookbackDays: 30 }),
+    });
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(await res.json(), summary);
+    assert.deepEqual(seenOptions, { dryRun: true, lookbackDays: 30 });
+  });
+
+  it('POST /api/stats/maintenance/duplicate-lines ignores a window shorter than a day', async () => {
+    let seenOptions: unknown = null;
+    const app = createStatsApp(
+      createMockTracker({
+        cleanupDuplicateSubtitleLines: async (options: unknown) => {
+          seenOptions = options;
+          return {
+            dryRun: true,
+            lookbackDays: null,
+            scannedLines: 0,
+            burstGroups: 0,
+            removedLines: 0,
+            removedWordOccurrences: 0,
+            removedKanjiOccurrences: 0,
+            samples: [],
+          };
+        },
+      }),
+    );
+
+    const res = await app.request('/api/stats/maintenance/duplicate-lines', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ dryRun: true, lookbackDays: 0.5 }),
+    });
+
+    assert.equal(res.status, 200);
+    // Half a day must not floor to a zero-day window; it means no limit.
+    assert.deepEqual(seenOptions, { dryRun: true, lookbackDays: null });
+  });
+
+  it('POST /api/stats/maintenance/duplicate-lines treats a missing body as an apply over all history', async () => {
+    let seenOptions: unknown = null;
+    const app = createStatsApp(
+      createMockTracker({
+        cleanupDuplicateSubtitleLines: async (options: unknown) => {
+          seenOptions = options;
+          return {
+            dryRun: false,
+            lookbackDays: null,
+            scannedLines: 0,
+            burstGroups: 0,
+            removedLines: 0,
+            removedWordOccurrences: 0,
+            removedKanjiOccurrences: 0,
+            samples: [],
+          };
+        },
+      }),
+    );
+
+    const res = await app.request('/api/stats/maintenance/duplicate-lines', { method: 'POST' });
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(seenOptions, { dryRun: false, lookbackDays: null });
+  });
+
   it('PUT /api/stats/excluded-words rejects malformed rows', async () => {
     const app = createStatsApp(createMockTracker());
 
@@ -2454,6 +2543,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');

src/core/services/ass-text.test.ts

@@ -0,0 +1,195 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  assOverrideSignature,
+  assToPlainText,
+  collectAssOverrideCommands,
+  extractAssOverrideBlocks,
+  hasAssTemporalOverride,
+  isAnimatedAssEffectKind,
+  isAssTemporalCommand,
+  normalizePlainSubtitleText,
+  parseAssEffectField,
+} from './ass-text';
+
+test('assToPlainText drops vector drawing runs', () => {
+  assert.equal(
+    assToPlainText(
+      '{\\an5\\pos(730,1042)\\p1\\blur1}m 20 0 b 10 0 0 10 0 20 b 0 31 10 40 20 40 {\\p0}',
+    ),
+    '',
+  );
+});
+
+test('assToPlainText keeps text around drawing runs on the same event', () => {
+  assert.equal(
+    assToPlainText('{\\p1}m 0 0 l 10 10{\\p0}本文{\\p1}m 5 5 l 6 6{\\p0}続き'),
+    '本文続き',
+  );
+});
+
+test('assToPlainText leaves \\pos alone when no drawing mode is active', () => {
+  assert.equal(assToPlainText('{\\pos(960,1068)\\bord3}位置指定'), '位置指定');
+});
+
+test('assToPlainText does not read \\pos as a drawing tag', () => {
+  assert.equal(assToPlainText('{\\p1\\pos(1,2)}m 0 0 l 5 5'), '');
+});
+
+test('assToPlainText resolves line-break and space escapes', () => {
+  assert.equal(assToPlainText('一行目\\N二行目'), '一行目\n二行目');
+  assert.equal(assToPlainText('一行目\\n二行目'), '一行目\n二行目');
+  assert.equal(assToPlainText('一行目\\N二行目', ' '), '一行目 二行目');
+  assert.equal(assToPlainText('間\\h隔'), '間 隔');
+});
+
+test('assToPlainText matches mpv on brace and backslash sequences', () => {
+  // mpv has no `\{` / `\}` / `\\` escapes: the backslashes are literal text and the
+  // braces still open and close an override block.
+  assert.equal(assToPlainText('\\{注\\}'), '\\');
+  assert.equal(assToPlainText('\\\\N'), '\\\n');
+});
+
+test('assToPlainText renders an unclosed override block verbatim', () => {
+  // mpv shows the stray brace; guessing where the block ended can eat a whole line.
+  assert.equal(assToPlainText('本文{\\pos(1,2)'), '本文{\\pos(1,2)');
+});
+
+test('assToPlainText is idempotent', () => {
+  const samples = [
+    '{\\an5\\p1}m 0 0 l 5 5{\\p0}本文',
+    '\\{注\\}',
+    '\\\\N',
+    '本文{\\pos(1,2)',
+    '一行目\\N二行目\\h終わり',
+  ];
+
+  for (const sample of samples) {
+    const once = assToPlainText(sample);
+    assert.equal(assToPlainText(once), once, sample);
+  }
+});
+
+test('assToPlainText normalizes CRLF before converting', () => {
+  assert.equal(assToPlainText('一行目\r\n二行目'), '一行目\n二行目');
+});
+
+test('normalizePlainSubtitleText settles whitespace without decoding ASS', () => {
+  // A brace reaching this layer is literal text mpv chose to show, not markup.
+  assert.equal(normalizePlainSubtitleText('本文{\\pos(1,2)'), '本文{\\pos(1,2)');
+  assert.equal(normalizePlainSubtitleText('一行目\\N二行目'), '一行目\n二行目');
+  assert.equal(
+    normalizePlainSubtitleText('一行目\\N二行目', { collapseLineBreaks: true }),
+    '一行目 二行目',
+  );
+  assert.equal(normalizePlainSubtitleText('  余白  ', { trim: false }), '  余白  ');
+});
+
+test('normalizePlainSubtitleText is idempotent', () => {
+  for (const sample of ['一行目\\N二行目', '間\\h隔', '本文{\\pos(1,2)', '  余白  ']) {
+    const once = normalizePlainSubtitleText(sample);
+    assert.equal(normalizePlainSubtitleText(once), once, sample);
+  }
+});
+
+test('extractAssOverrideBlocks returns block contents', () => {
+  assert.deepEqual(extractAssOverrideBlocks('{\\an8}上{\\fad(200,200)}下'), [
+    '\\an8',
+    '\\fad(200,200)',
+  ]);
+  assert.deepEqual(extractAssOverrideBlocks('括弧なし'), []);
+});
+
+test('collectAssOverrideCommands captures names and arguments from blocks only', () => {
+  const commands = collectAssOverrideCommands('{\\pos(1,2)\\1c&HFFFFFF&\\kf30}歌詞');
+
+  assert.deepEqual(commands, [
+    { name: 'pos', args: '1,2', animated: false },
+    { name: '1c', args: '&HFFFFFF&', animated: false },
+    { name: 'kf', args: '30', animated: false },
+  ]);
+
+  // A `\pos(...)` sitting in visible text is not typesetting markup.
+  assert.deepEqual(collectAssOverrideCommands('\\pos(730,1042) と書いてある'), []);
+});
+
+test('collectAssOverrideCommands marks tags animated by a wrapping \\t', () => {
+  const commands = collectAssOverrideCommands('{\\clip(0,0,10,10)\\t(0,500,\\frz30)}文字');
+
+  assert.deepEqual(
+    commands.map((command) => [command.name, command.animated]),
+    [
+      ['clip', false],
+      ['t', false],
+      ['frz', true],
+    ],
+  );
+  assert.equal(hasAssTemporalOverride(commands), true);
+});
+
+test('collectAssOverrideCommands stops descending into deeply nested \\t tags', () => {
+  // Nested far past the recursion cap. Uncapped, this recurses once per level, and a
+  // pathological line (real files reach one or two levels) overflows the stack.
+  const nesting = 32;
+  const block = `{${'\\t(0,500,'.repeat(nesting)}\\frz30${')'.repeat(nesting)}}文字`;
+
+  const commands = collectAssOverrideCommands(block);
+
+  // The outer `\t` plus one per allowed recursion level, and nothing from below the cap.
+  assert.equal(commands.length, 9);
+  assert.deepEqual(new Set(commands.map((command) => command.name)), new Set(['t']));
+  assert.equal(hasAssTemporalOverride(commands), true);
+});
+
+test('hasAssTemporalOverride ignores static placement and shape tags', () => {
+  assert.equal(
+    hasAssTemporalOverride(collectAssOverrideCommands('{\\pos(1,2)\\clip(m 1 1)\\blur2}文字')),
+    false,
+  );
+  assert.equal(hasAssTemporalOverride(collectAssOverrideCommands('{\\move(1,2,3,4)}文字')), true);
+});
+
+test('isAssTemporalCommand covers only intrinsically animated tags', () => {
+  for (const command of ['t', 'move', 'k', 'kf', 'ko', 'K']) {
+    assert.equal(isAssTemporalCommand(command), true, command);
+  }
+  for (const command of ['clip', 'iclip', 'frz', 'fscx', 'blur', 'be', 'pos', 'fad']) {
+    assert.equal(isAssTemporalCommand(command), false, command);
+  }
+});
+
+test('assOverrideSignature distinguishes events by their override values', () => {
+  const first = assOverrideSignature(collectAssOverrideCommands('{\\clip(m 1 1)}歌詞'));
+  const second = assOverrideSignature(collectAssOverrideCommands('{\\clip(m 2 2)}歌詞'));
+  const repeat = assOverrideSignature(collectAssOverrideCommands('{\\clip(m 1 1)}別の行'));
+
+  assert.notEqual(first, second);
+  assert.equal(first, repeat);
+});
+
+test('parseAssEffectField classifies the event-level Effect column', () => {
+  assert.equal(parseAssEffectField(''), 'none');
+  assert.equal(parseAssEffectField('   '), 'none');
+  assert.equal(parseAssEffectField('Banner;20;1;0'), 'banner');
+  assert.equal(parseAssEffectField('Scroll up;0;0;30;10'), 'scroll');
+  assert.equal(parseAssEffectField('Scroll down;0;0;30;10'), 'scroll');
+  assert.equal(parseAssEffectField('Karaoke'), 'karaoke');
+  assert.equal(parseAssEffectField('fx-template'), 'other');
+});
+
+test('parseAssEffectField matches stock effect names exactly', () => {
+  // Custom effect names that merely start with a stock name are not stock effects.
+  assert.equal(parseAssEffectField('scrolling-credit'), 'other');
+  assert.equal(parseAssEffectField('bannerfx;1'), 'other');
+  assert.equal(parseAssEffectField('karaoke-template'), 'other');
+  assert.equal(parseAssEffectField('Scroll'), 'other');
+});
+
+test('isAnimatedAssEffectKind covers the stock animated effects only', () => {
+  assert.equal(isAnimatedAssEffectKind('karaoke'), true);
+  assert.equal(isAnimatedAssEffectKind('banner'), true);
+  assert.equal(isAnimatedAssEffectKind('scroll'), true);
+  // Typesetting groups put static template names in this column too.
+  assert.equal(isAnimatedAssEffectKind('other'), false);
+  assert.equal(isAnimatedAssEffectKind('none'), false);
+});

src/core/services/ass-text.ts

@@ -0,0 +1,280 @@
+/*
+ * ASS/SSA text handling, split into two deliberately distinct contracts:
+ *
+ *   assToPlainText()             raw ASS event text -> plain text. Ingestion only.
+ *   normalizePlainSubtitleText() already-decoded text -> display/lookup form.
+ *
+ * Subtitle text is decoded from ASS exactly once, at the point it enters the app: the
+ * file cue parser does it for sidecar/embedded scripts, and mpv does it for live text
+ * (`sub-text` is already run through mpv's own `ass_to_plaintext`). Everything
+ * downstream -- renderer, timing tracker, tokenizer, tokenization cache keys -- gets
+ * plain text and only normalizes whitespace, so no layer decodes the same string twice.
+ *
+ * assToPlainText mirrors mpv's `ass_to_plaintext` rather than inventing its own rules,
+ * so a cue parsed from a file reads the same as the same line arriving live:
+ *   - `{...}` override blocks are markup
+ *   - `\pN ... \p0` runs are vector paths, not dialogue
+ *   - `\N`, `\n` and `\h` are the only escapes; `\{`, `\}` and `\\` are NOT escapes,
+ *     so `\{注\}` decodes to a lone backslash exactly as mpv renders it
+ *   - an unclosed `{` is rendered verbatim instead of swallowing the rest of the line
+ * Because the decoder never emits an escape or a closed brace, running it twice is a
+ * no-op -- but downstream code should still use normalizePlainSubtitleText.
+ */
+
+/** What `\N` and `\n` become. */
+export type AssLineBreak = '\n' | ' ';
+
+// `\p<n>` with n > 0 switches libass into vector-drawing mode: everything until the
+// next `\p0` is a path (`m 20 0 b 10 0 ...`), not dialogue. The negative lookahead keeps
+// `\pos(...)` from being read as a drawing tag.
+const ASS_DRAWING_SCALE_PATTERN = /\\p(?![a-zA-Z])(\d*)/g;
+
+function readDrawingScale(block: string): number | null {
+  ASS_DRAWING_SCALE_PATTERN.lastIndex = 0;
+  let scale: number | null = null;
+  let match: RegExpExecArray | null;
+  // Drawing mode is whatever the last `\p` tag in this block set it to.
+  while ((match = ASS_DRAWING_SCALE_PATTERN.exec(block)) !== null) {
+    scale = match[1] ? Number(match[1]) : 0;
+  }
+  return scale;
+}
+
+/** Resolve `\N`, `\n` and `\h`. The only text-level escapes libass recognises. */
+function resolveWhitespaceEscapes(text: string, lineBreak: AssLineBreak): string {
+  return text.replace(/\\([Nnh])/g, (_match, escaped: string) =>
+    escaped === 'h' ? ' ' : lineBreak,
+  );
+}
+
+/** Strip `{...}` override blocks and the drawing runs they enable. */
+function stripAssMarkup(raw: string): string {
+  let out = '';
+  let cursor = 0;
+  let drawing = false;
+
+  while (cursor < raw.length) {
+    if (raw[cursor] !== '{') {
+      if (!drawing) {
+        out += raw[cursor];
+      }
+      cursor += 1;
+      continue;
+    }
+
+    const close = raw.indexOf('}', cursor + 1);
+    if (close === -1) {
+      // mpv shows an unclosed `{` and everything after it. Guessing where the block was
+      // meant to end can eat a whole line of dialogue.
+      if (!drawing) {
+        out += raw.slice(cursor);
+      }
+      break;
+    }
+
+    const scale = readDrawingScale(raw.slice(cursor, close + 1));
+    if (scale !== null) {
+      drawing = scale > 0;
+    }
+    cursor = close + 1;
+  }
+
+  return out;
+}
+
+/**
+ * Decode a raw ASS/SSA event text field. Call this once, where the text enters the app;
+ * downstream layers take the result as plain text.
+ */
+export function assToPlainText(text: string, lineBreak: AssLineBreak = '\n'): string {
+  if (!text) return '';
+  return resolveWhitespaceEscapes(stripAssMarkup(text.replace(/\r\n/g, '\n')), lineBreak);
+}
+
+export interface NormalizePlainSubtitleTextOptions {
+  /** Fold every line break into a single space. */
+  collapseLineBreaks?: boolean;
+  trim?: boolean;
+}
+
+/**
+ * Whitespace normalization for text that has already been decoded -- by mpv for live
+ * subtitles, by the cue parser for files. Override blocks and drawing runs are none of
+ * this function's business; a `{` that reaches here is literal text mpv chose to show.
+ *
+ * `\N`/`\n`/`\h` are still folded, because subtitle sources outside the ASS path (asbplayer
+ * and other websocket clients) forward them raw and the display layer has to cope.
+ */
+export function normalizePlainSubtitleText(
+  text: string,
+  options: NormalizePlainSubtitleTextOptions = {},
+): string {
+  if (!text) return '';
+  const { collapseLineBreaks = false, trim = true } = options;
+
+  let normalized = resolveWhitespaceEscapes(
+    text.replace(/\r\n/g, '\n'),
+    collapseLineBreaks ? ' ' : '\n',
+  );
+  if (collapseLineBreaks) {
+    normalized = normalized.replace(/\n/g, ' ').replace(/\s+/g, ' ');
+  }
+
+  return trim ? normalized.trim() : normalized;
+}
+
+/** The contents of each `{...}` block, without the braces. */
+export function extractAssOverrideBlocks(text: string): string[] {
+  const blocks: string[] = [];
+  let cursor = 0;
+
+  while (cursor < text.length) {
+    const open = text.indexOf('{', cursor);
+    if (open === -1) {
+      break;
+    }
+    const close = text.indexOf('}', open + 1);
+    if (close === -1) {
+      break;
+    }
+    blocks.push(text.slice(open + 1, close));
+    cursor = close + 1;
+  }
+
+  return blocks;
+}
+
+export interface AssOverrideCommand {
+  /** Tag name without the backslash, e.g. `pos`, `kf`, `1c`. */
+  name: string;
+  /** Everything the tag was given, e.g. `960,1068` for `\pos(960,1068)`. */
+  args: string;
+  /** Nested inside a `\t(...)` argument, so its value is animated over the event. */
+  animated: boolean;
+}
+
+const ASS_OVERRIDE_NAME_PATTERN = /[1-4]?[a-zA-Z]+/y;
+
+function readCommandArgs(block: string, start: number): { args: string; next: number } {
+  if (block[start] === '(') {
+    let depth = 0;
+    for (let i = start; i < block.length; i += 1) {
+      if (block[i] === '(') depth += 1;
+      else if (block[i] === ')') {
+        depth -= 1;
+        if (depth === 0) {
+          return { args: block.slice(start + 1, i), next: i + 1 };
+        }
+      }
+    }
+    return { args: block.slice(start + 1), next: block.length };
+  }
+
+  const nextTag = block.indexOf('\\', start);
+  const end = nextTag === -1 ? block.length : nextTag;
+  return { args: block.slice(start, end), next: end };
+}
+
+// `\t(...)` can wrap another `\t(...)`, and nothing in the format stops an author (or a
+// malformed file) from nesting them thousands deep. Real typesetting never goes past one
+// or two levels, so stop recursing well before the call stack is at risk.
+const MAX_ANIMATION_NESTING_DEPTH = 8;
+
+function parseOverrideBlock(
+  block: string,
+  animated: boolean,
+  into: AssOverrideCommand[],
+  depth = 0,
+): void {
+  let cursor = 0;
+
+  while (cursor < block.length) {
+    if (block[cursor] !== '\\') {
+      cursor += 1;
+      continue;
+    }
+
+    ASS_OVERRIDE_NAME_PATTERN.lastIndex = cursor + 1;
+    const nameMatch = ASS_OVERRIDE_NAME_PATTERN.exec(block);
+    if (!nameMatch) {
+      cursor += 1;
+      continue;
+    }
+
+    const name = nameMatch[0];
+    const { args, next } = readCommandArgs(block, cursor + 1 + name.length);
+    into.push({ name, args: args.trim(), animated });
+    // `\t(0,500,\frz30)` animates whatever it wraps, so record the inner tags too.
+    if (name === 't' && args.includes('\\') && depth < MAX_ANIMATION_NESTING_DEPTH) {
+      parseOverrideBlock(args, true, into, depth + 1);
+    }
+    cursor = next;
+  }
+}
+
+/**
+ * Override commands with their arguments, in source order. Only `{...}` blocks are
+ * inspected, so a `\pos(...)` sitting in visible text is never mistaken for markup.
+ */
+export function collectAssOverrideCommands(text: string): AssOverrideCommand[] {
+  const commands: AssOverrideCommand[] = [];
+  for (const block of extractAssOverrideBlocks(text)) {
+    parseOverrideBlock(block, false, commands);
+  }
+  return commands;
+}
+
+// Tags that are animated by definition: `\t` interpolates, `\move` travels, and the
+// karaoke tags advance a highlight across the event's own duration. Everything else --
+// `\pos`, `\clip`, `\frz`, `\blur`, `\fad` -- is a static value for the event, so its
+// presence says nothing about whether neighbouring events form one animation.
+const ASS_TEMPORAL_COMMANDS = new Set(['t', 'move', 'k', 'kf', 'ko', 'K']);
+
+export function isAssTemporalCommand(name: string): boolean {
+  return ASS_TEMPORAL_COMMANDS.has(name);
+}
+
+/** True when the event animates on its own, or animates a static tag through `\t(...)`. */
+export function hasAssTemporalOverride(commands: readonly AssOverrideCommand[]): boolean {
+  return commands.some((command) => command.animated || isAssTemporalCommand(command.name));
+}
+
+/**
+ * Canonical form of an event's override values, for comparing consecutive events. Two
+ * events with the same signature were typeset identically, so neither is a frame of an
+ * animation the other belongs to.
+ */
+export function assOverrideSignature(commands: readonly AssOverrideCommand[]): string {
+  return commands.map((command) => `${command.name}(${command.args})`).join('|');
+}
+
+export type AssEffectKind = 'none' | 'banner' | 'scroll' | 'karaoke' | 'other';
+
+// The stock effects, matched exactly. Typesetting groups put their own template names in
+// this column -- `scrolling-credit` is a static sign, not libass's `Scroll up` -- so a
+// prefix match would hand out animation evidence to arbitrary custom effects.
+const STOCK_ASS_EFFECTS = new Map<string, AssEffectKind>([
+  ['banner', 'banner'],
+  ['scroll up', 'scroll'],
+  ['scroll down', 'scroll'],
+  ['karaoke', 'karaoke'],
+]);
+
+/**
+ * The event-level `Effect` column. The stock values (`Banner;...`, `Scroll up;...`,
+ * `Scroll down;...`, `Karaoke`) all animate; anything else is a custom name and lands in
+ * `other`.
+ */
+export function parseAssEffectField(raw: string): AssEffectKind {
+  const value = raw.trim().toLowerCase();
+  if (!value) return 'none';
+
+  const name = value.split(';', 1)[0]!.trim();
+  return STOCK_ASS_EFFECTS.get(name) ?? 'other';
+}
+
+const ANIMATED_ASS_EFFECT_KINDS = new Set<AssEffectKind>(['banner', 'scroll', 'karaoke']);
+
+export function isAnimatedAssEffectKind(kind: AssEffectKind): boolean {
+  return ANIMATED_ASS_EFFECT_KINDS.has(kind);
+}

src/core/services/config-hot-reload.ts

@@ -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 {

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

@@ -91,6 +91,11 @@ import {
   markVideoWatched,
   upsertCoverArt,
 } from './immersion-tracker/query-maintenance';
+import {
+  cleanupDuplicateSubtitleLines,
+  type DuplicateSubtitleLineCleanupOptions,
+  type DuplicateSubtitleLineCleanupSummary,
+} from './immersion-tracker/duplicate-line-cleanup';
 import { repairJellyfinStreamVideoLinks } from './immersion-tracker/jellyfin-link-repair';
 import {
   repairLegacySeasonlessAnimeRows,
@@ -595,6 +600,18 @@ export class ImmersionTrackerService {
     });
   }
 
+  /**
+   * Collapse animation bursts that earlier versions recorded frame by frame. The whole
+   * queue is drained first so a burst still waiting to be written is scanned as stored
+   * rows rather than surviving the cleanup and landing a moment after it.
+   */
+  async cleanupDuplicateSubtitleLines(
+    options: DuplicateSubtitleLineCleanupOptions = {},
+  ): Promise<DuplicateSubtitleLineCleanupSummary> {
+    this.drainQueue();
+    return cleanupDuplicateSubtitleLines(this.db, options);
+  }
+
   async rebuildLifetimeSummaries(): Promise<LifetimeRebuildSummary> {
     this.flushTelemetry(true);
     this.flushNow();
@@ -1799,6 +1816,24 @@ export class ImmersionTrackerService {
     }
   }
 
+  /**
+   * Write out everything queued, not just the next batch.
+   *
+   * `flushNow` writes at most `batchSize` entries and does nothing at all while the write
+   * lock is held, so a maintenance pass that runs straight after it can still be reading
+   * a database that is missing rows. Each pass has to shrink the queue to continue: a
+   * failed flush puts its batch back, and looping on that would never finish.
+   */
+  private drainQueue(): void {
+    while (this.queue.length > 0) {
+      const pendingBefore = this.queue.length;
+      this.flushNow();
+      if (this.queue.length >= pendingBefore) {
+        return;
+      }
+    }
+  }
+
   private flushSingle(write: QueuedWrite): void {
     executeQueuedWrite(write, this.preparedStatements);
   }

src/core/services/immersion-tracker/__tests__/duplicate-line-cleanup.test.ts

@@ -0,0 +1,312 @@
+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 { cleanupDuplicateSubtitleLines } from '../duplicate-line-cleanup.js';
+
+const DAY_MS = 86_400_000;
+const BASE_MS = 1_700_000_000_000;
+const WORD_ID = 1;
+
+interface SeedLine {
+  session: number;
+  text: string;
+  startMs: number;
+  endMs: number;
+  /** Recording wall-clock, i.e. what the lookback window filters on. */
+  createdMs?: number;
+}
+
+function makeDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-duplicate-line-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 });
+}
+
+/** One episode, two sessions of it, and one word occurrence per seeded line. */
+function seed(db: DatabaseSync, lines: SeedLine[]): 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});
+    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', 1, '${BASE_MS + DAY_MS}', '${BASE_MS + DAY_MS + 1000}', 2, ${BASE_MS}, ${BASE_MS});
+    INSERT INTO imm_words(id, headword, word, reading, part_of_speech, pos1, first_seen, last_seen, frequency)
+      VALUES (${WORD_ID}, '飛び上がる', '飛び上がる', '', 'verb', '動詞', ${Math.floor(BASE_MS / 1000)}, ${Math.floor(BASE_MS / 1000)}, 0);
+  `);
+
+  const insertLine = db.prepare(
+    `INSERT INTO imm_subtitle_lines(
+       line_id, session_id, video_id, anime_id, line_index,
+       segment_start_ms, segment_end_ms, text, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, 1, 1, ?, ?, ?, ?, ?, ?)`,
+  );
+  const insertOccurrence = db.prepare(
+    `INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count, seen_ms)
+     VALUES (?, ?, 1, ?)`,
+  );
+
+  lines.forEach((line, index) => {
+    const lineId = index + 1;
+    const lineIndex = index + 1;
+    const createdMs = line.createdMs ?? BASE_MS;
+    insertLine.run(
+      lineId,
+      line.session,
+      lineIndex,
+      line.startMs,
+      line.endMs,
+      line.text,
+      createdMs,
+      createdMs,
+    );
+    insertOccurrence.run(lineId, WORD_ID, createdMs);
+  });
+
+  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
+    )
+  `);
+}
+
+function createDb(lines: SeedLine[]): { db: DatabaseSync; dbPath: string } {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  ensureSchema(db);
+  seed(db, lines);
+  return { db, dbPath };
+}
+
+/** A typeset line mpv reported once per animation frame. */
+function karaokeFrames(
+  session: number,
+  text: string,
+  startMs: number,
+  frames: number,
+  frameMs: number,
+): SeedLine[] {
+  return Array.from({ length: frames }, (_, index) => ({
+    session,
+    text,
+    startMs: startMs + index * frameMs,
+    endMs: startMs + (index + 1) * frameMs,
+  }));
+}
+
+function countLines(db: DatabaseSync): number {
+  return (db.prepare('SELECT COUNT(*) AS total FROM imm_subtitle_lines').get() as { total: number })
+    .total;
+}
+
+function wordFrequency(db: DatabaseSync): number {
+  const row = db.prepare('SELECT frequency FROM imm_words WHERE id = ?').get(WORD_ID) as {
+    frequency: number;
+  } | null;
+  return row?.frequency ?? 0;
+}
+
+test('a karaoke burst collapses to one line and gives back its word counts', () => {
+  const { db, dbPath } = createDb([
+    ...karaokeFrames(1, '飛び上がる', 10_000, 40, 40),
+    { session: 1, text: 'おはよう', startMs: 20_000, endMs: 22_000 },
+  ]);
+
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db);
+
+    assert.equal(summary.burstGroups, 1);
+    assert.equal(summary.removedLines, 39);
+    assert.equal(summary.removedWordOccurrences, 39);
+    assert.equal(countLines(db), 2);
+    assert.equal(wordFrequency(db), 2);
+
+    // The surviving line covers the whole run, the way the parsed cue would.
+    const kept = db
+      .prepare(
+        'SELECT segment_start_ms AS startMs, segment_end_ms AS endMs FROM imm_subtitle_lines WHERE line_id = 1',
+      )
+      .get() as { startMs: number; endMs: number };
+    assert.equal(kept.startMs, 10_000);
+    assert.equal(kept.endMs, 10_000 + 40 * 40);
+
+    assert.equal(summary.samples.length, 1);
+    assert.equal(summary.samples[0]!.text, '飛び上がる');
+    assert.equal(summary.samples[0]!.frames, 40);
+    assert.equal(summary.samples[0]!.videoTitle, 'Ep 1');
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('ordinary repeated dialogue survives', () => {
+  // Six contiguous `飛び上がる`, each held for a normal beat rather than a frame.
+  const lines = Array.from({ length: 6 }, (_, index) => ({
+    session: 1,
+    text: '飛び上がる',
+    startMs: 5_000 + index * 800,
+    endMs: 5_000 + (index + 1) * 800,
+  }));
+  const { db, dbPath } = createDb(lines);
+
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db);
+
+    assert.equal(summary.burstGroups, 0);
+    assert.equal(summary.removedLines, 0);
+    assert.equal(countLines(db), 6);
+    assert.equal(wordFrequency(db), 6);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('a long run of quarter-second frames is still a burst', () => {
+  // Between the timing-only bound (0.1s) and the animation-frame bound (0.3s): heavier
+  // typesetting lands here, and the run length is what makes it conclusive.
+  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 250));
+
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db);
+
+    assert.equal(summary.burstGroups, 1);
+    assert.equal(summary.removedLines, 5);
+    assert.equal(countLines(db), 1);
+    assert.equal(wordFrequency(db), 1);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('a run of frames longer than the animation bound survives', () => {
+  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 400));
+
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db);
+
+    assert.equal(summary.burstGroups, 0);
+    assert.equal(countLines(db), 6);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('a short run below the threshold survives', () => {
+  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 1_000, 4, 40));
+
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db);
+
+    assert.equal(summary.burstGroups, 0);
+    assert.equal(countLines(db), 4);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('the same line in a rewatch session is never merged into the first watch', () => {
+  const { db, dbPath } = createDb([
+    ...karaokeFrames(1, '飛び上がる', 10_000, 6, 40),
+    ...karaokeFrames(2, '飛び上がる', 10_000, 6, 40),
+  ]);
+
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db);
+
+    assert.equal(summary.burstGroups, 2);
+    assert.equal(summary.removedLines, 10);
+    // One surviving line per session, not one across both.
+    assert.equal(countLines(db), 2);
+    assert.equal(wordFrequency(db), 2);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('a gap between runs splits them', () => {
+  const { db, dbPath } = createDb([
+    ...karaokeFrames(1, '飛び上がる', 10_000, 6, 40),
+    ...karaokeFrames(1, '飛び上がる', 60_000, 6, 40),
+  ]);
+
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db);
+
+    assert.equal(summary.burstGroups, 2);
+    assert.equal(countLines(db), 2);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('a dry run reports what an apply would do and writes nothing', () => {
+  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 40, 40));
+
+  try {
+    const preview = cleanupDuplicateSubtitleLines(db, { dryRun: true });
+
+    assert.equal(preview.dryRun, true);
+    assert.equal(preview.removedLines, 39);
+    assert.equal(countLines(db), 40);
+    assert.equal(wordFrequency(db), 40);
+
+    const applied = cleanupDuplicateSubtitleLines(db);
+    assert.equal(applied.removedLines, preview.removedLines);
+    assert.equal(applied.removedWordOccurrences, preview.removedWordOccurrences);
+    assert.equal(countLines(db), 1);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('the lookback window leaves older bursts alone', () => {
+  const recentMs = BASE_MS;
+  const oldMs = BASE_MS - 40 * DAY_MS;
+  const { db, dbPath } = createDb([
+    ...karaokeFrames(1, '飛び上がる', 10_000, 6, 40).map((line) => ({
+      ...line,
+      createdMs: oldMs,
+    })),
+    ...karaokeFrames(2, '飛び上がる', 10_000, 6, 40).map((line) => ({
+      ...line,
+      createdMs: recentMs,
+    })),
+  ]);
+
+  globalThis.__subminerTestNowMs = BASE_MS;
+  try {
+    const summary = cleanupDuplicateSubtitleLines(db, { lookbackDays: 30 });
+
+    assert.equal(summary.lookbackDays, 30);
+    assert.equal(summary.scannedLines, 6);
+    assert.equal(summary.burstGroups, 1);
+    assert.equal(summary.removedLines, 5);
+    // Six untouched old frames plus the one surviving recent line.
+    assert.equal(countLines(db), 7);
+    assert.equal(wordFrequency(db), 7);
+  } finally {
+    globalThis.__subminerTestNowMs = undefined;
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});

src/core/services/immersion-tracker/duplicate-line-cleanup.ts

@@ -0,0 +1,373 @@
+/*
+ * Retroactive removal of animation-burst subtitle lines from the stats database.
+ *
+ * Before the live ingest gate existed, a karaoke OP recorded one line -- and one count
+ * for every word in it -- per animation frame, which is enough to put an OP lyric at the
+ * top of "Top Repeated Words" for good. This module finds those runs in what is already
+ * stored and takes them back down to one line.
+ *
+ * Only timing is available here: the stored text has been stripped of ASS markup, so the
+ * authoring evidence the file-level parser uses (`\t`, `\move`, karaoke timing, a
+ * changing override signature) is long gone. What is left is a run of identical,
+ * contiguous, short-lived lines inside a single session.
+ *
+ * The run has to be as long as the timing-only rule in `subtitle-cue-dedup` demands, but
+ * each line may be as long as the animation-frame bound rather than the much tighter
+ * timing-only one. Five or more repeats of the same text, each ending where the next
+ * begins, is already conclusive on its own -- no dialogue does that -- and the tighter
+ * bound would walk straight past the heavier typesetting that motivated this, where
+ * frames sit nearer a quarter of a second. Both bounds are options, so a cautious run can
+ * ask for more, and a dry run always reports before anything is removed.
+ *
+ * Scope: subtitle lines, their word/kanji occurrences, and the `imm_words`/`imm_kanji`
+ * aggregates those occurrences feed. Session telemetry (`lines_seen`, `tokens_seen`) and
+ * the rollups derived from it are left alone; they are cumulative samples taken at record
+ * time, and for sessions whose raw rows have since been pruned they cannot be recomputed.
+ */
+
+import type { DatabaseSync } from './sqlite';
+import {
+  ANIMATION_FRAME_MAX_SECONDS,
+  DUPLICATE_CUE_GAP_TOLERANCE_SECONDS,
+  MIN_TIMING_ONLY_FRAMES,
+} from '../subtitle-burst-constants';
+import {
+  applyLexicalRemovals,
+  makePlaceholders,
+  planLexicalRemovalsForLines,
+  toDbTimestamp,
+} from './query-shared';
+import { nowMs } from './time';
+
+const MS_PER_DAY = 86_400_000;
+/** SQLite caps bound parameters per statement; stay well under it. */
+const LINE_ID_BATCH_SIZE = 400;
+const DEFAULT_SAMPLE_LIMIT = 20;
+
+export interface DuplicateSubtitleLineCleanupOptions {
+  /** Only consider lines recorded within this many days. Null or omitted = all history. */
+  lookbackDays?: number | null;
+  /** Measure without writing. */
+  dryRun?: boolean;
+  /** Identical contiguous lines needed before a run counts as an animation. */
+  minRunLength?: number;
+  /** Longest a single event may last and still look like an animation frame. */
+  maxFrameSeconds?: number;
+  /** How many of the largest runs to describe in the summary. */
+  sampleLimit?: number;
+}
+
+export interface DuplicateSubtitleLineBurst {
+  sessionId: number;
+  videoId: number;
+  text: string;
+  /** Kept line, extended to cover the whole run. */
+  keptLineId: number;
+  removedLineIds: number[];
+  startMs: number;
+  endMs: number;
+}
+
+export interface DuplicateSubtitleLineSample {
+  videoId: number;
+  videoTitle: string | null;
+  text: string;
+  frames: number;
+  removedLines: number;
+  startMs: number;
+  endMs: number;
+}
+
+export interface DuplicateSubtitleLineCleanupSummary {
+  dryRun: boolean;
+  lookbackDays: number | null;
+  scannedLines: number;
+  burstGroups: number;
+  removedLines: number;
+  removedWordOccurrences: number;
+  removedKanjiOccurrences: number;
+  samples: DuplicateSubtitleLineSample[];
+}
+
+export interface StoredSubtitleLineRow {
+  lineId: number;
+  sessionId: number;
+  videoId: number;
+  text: string;
+  startMs: number;
+  endMs: number;
+}
+
+interface ResolvedBounds {
+  lookbackDays: number | null;
+  minRunLength: number;
+  maxFrameMs: number;
+  gapToleranceMs: number;
+  sampleLimit: number;
+}
+
+function resolveBounds(options: DuplicateSubtitleLineCleanupOptions): ResolvedBounds {
+  const lookbackDays =
+    typeof options.lookbackDays === 'number' && Number.isFinite(options.lookbackDays)
+      ? Math.max(1, Math.floor(options.lookbackDays))
+      : null;
+  const minRunLength =
+    typeof options.minRunLength === 'number' && Number.isFinite(options.minRunLength)
+      ? Math.max(2, Math.floor(options.minRunLength))
+      : MIN_TIMING_ONLY_FRAMES;
+  const maxFrameSeconds =
+    typeof options.maxFrameSeconds === 'number' && options.maxFrameSeconds > 0
+      ? options.maxFrameSeconds
+      : ANIMATION_FRAME_MAX_SECONDS;
+  const sampleLimit =
+    typeof options.sampleLimit === 'number' && options.sampleLimit >= 0
+      ? Math.floor(options.sampleLimit)
+      : DEFAULT_SAMPLE_LIMIT;
+  return {
+    lookbackDays,
+    minRunLength,
+    maxFrameMs: Math.round(maxFrameSeconds * 1000),
+    gapToleranceMs: Math.round(DUPLICATE_CUE_GAP_TOLERANCE_SECONDS * 1000),
+    sampleLimit,
+  };
+}
+
+/**
+ * `CREATED_DATE` holds epoch milliseconds on rows this app wrote, but older and synced
+ * rows can carry seconds, so normalize before comparing against the cutoff.
+ */
+const CREATED_MS_SQL = `
+  CASE
+    WHEN sl.CREATED_DATE < 10000000000 THEN sl.CREATED_DATE * 1000
+    ELSE sl.CREATED_DATE
+  END`;
+
+function readCandidateLines(db: DatabaseSync, bounds: ResolvedBounds): StoredSubtitleLineRow[] {
+  const scope =
+    bounds.lookbackDays === null
+      ? ''
+      : `AND sl.CREATED_DATE IS NOT NULL AND ${CREATED_MS_SQL} >= ?`;
+  const params = bounds.lookbackDays === null ? [] : [nowMs() - bounds.lookbackDays * MS_PER_DAY];
+  return db
+    .prepare(
+      `SELECT
+         sl.line_id AS lineId,
+         sl.session_id AS sessionId,
+         sl.video_id AS videoId,
+         sl.text AS text,
+         sl.segment_start_ms AS startMs,
+         sl.segment_end_ms AS endMs
+       FROM imm_subtitle_lines sl
+       WHERE sl.segment_start_ms IS NOT NULL
+         AND sl.segment_end_ms IS NOT NULL
+         ${scope}
+       ORDER BY sl.session_id, sl.video_id, sl.segment_start_ms, sl.line_id`,
+    )
+    .all(...params) as StoredSubtitleLineRow[];
+}
+
+function isBurst(run: StoredSubtitleLineRow[], bounds: ResolvedBounds): boolean {
+  if (run.length < bounds.minRunLength) {
+    return false;
+  }
+  return run.every((row) => row.endMs - row.startMs <= bounds.maxFrameMs);
+}
+
+function toBurst(run: StoredSubtitleLineRow[]): DuplicateSubtitleLineBurst {
+  const [first] = run;
+  return {
+    sessionId: first!.sessionId,
+    videoId: first!.videoId,
+    text: first!.text,
+    keptLineId: first!.lineId,
+    removedLineIds: run.slice(1).map((row) => row.lineId),
+    startMs: first!.startMs,
+    endMs: run.reduce((latest, row) => Math.max(latest, row.endMs), first!.endMs),
+  };
+}
+
+/**
+ * Group stored lines into animation runs.
+ *
+ * Runs never cross a session, which is what keeps a rewatch intact: the same episode
+ * watched twice stores the same line twice, and those two belong to different sessions.
+ */
+export function findDuplicateSubtitleLineBursts(
+  rows: readonly StoredSubtitleLineRow[],
+  options: DuplicateSubtitleLineCleanupOptions = {},
+): DuplicateSubtitleLineBurst[] {
+  const bounds = resolveBounds(options);
+  const bursts: DuplicateSubtitleLineBurst[] = [];
+  let run: StoredSubtitleLineRow[] = [];
+  let chainEndMs = 0;
+
+  const closeRun = (): void => {
+    if (run.length > 1 && isBurst(run, bounds)) {
+      bursts.push(toBurst(run));
+    }
+    run = [];
+  };
+
+  for (const row of rows) {
+    const previous = run[run.length - 1];
+    const continuesRun =
+      previous !== undefined &&
+      previous.sessionId === row.sessionId &&
+      previous.videoId === row.videoId &&
+      previous.text === row.text &&
+      row.startMs <= chainEndMs + bounds.gapToleranceMs;
+
+    if (continuesRun) {
+      run.push(row);
+      chainEndMs = Math.max(chainEndMs, row.endMs);
+      continue;
+    }
+
+    closeRun();
+    run = [row];
+    chainEndMs = row.endMs;
+  }
+  closeRun();
+
+  return bursts;
+}
+
+function chunk<T>(values: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < values.length; i += size) {
+    chunks.push(values.slice(i, i + size));
+  }
+  return chunks;
+}
+
+function buildSamples(
+  db: DatabaseSync,
+  bursts: DuplicateSubtitleLineBurst[],
+  sampleLimit: number,
+): DuplicateSubtitleLineSample[] {
+  if (sampleLimit === 0 || bursts.length === 0) {
+    return [];
+  }
+  const largest = [...bursts]
+    .sort((a, b) => b.removedLineIds.length - a.removedLineIds.length)
+    .slice(0, sampleLimit);
+  const videoIds = [...new Set(largest.map((burst) => burst.videoId))];
+  const titles = new Map<number, string>();
+  for (const batch of chunk(videoIds, LINE_ID_BATCH_SIZE)) {
+    const rows = db
+      .prepare(
+        `SELECT video_id AS videoId, canonical_title AS title
+         FROM imm_videos
+         WHERE video_id IN (${makePlaceholders(batch)})`,
+      )
+      .all(...batch) as Array<{ videoId: number; title: string | null }>;
+    for (const row of rows) {
+      if (row.title) titles.set(row.videoId, row.title);
+    }
+  }
+
+  return largest.map((burst) => ({
+    videoId: burst.videoId,
+    videoTitle: titles.get(burst.videoId) ?? null,
+    text: burst.text,
+    frames: burst.removedLineIds.length + 1,
+    removedLines: burst.removedLineIds.length,
+    startMs: burst.startMs,
+    endMs: burst.endMs,
+  }));
+}
+
+function sumRemovedOccurrences(
+  db: DatabaseSync,
+  table: 'imm_word_line_occurrences' | 'imm_kanji_line_occurrences',
+  lineIds: number[],
+): number {
+  let total = 0;
+  for (const batch of chunk(lineIds, LINE_ID_BATCH_SIZE)) {
+    const row = db
+      .prepare(
+        `SELECT COALESCE(SUM(occurrence_count), 0) AS total
+         FROM ${table}
+         WHERE line_id IN (${makePlaceholders(batch)})`,
+      )
+      .get(...batch) as { total: number } | null;
+    total += row?.total ?? 0;
+  }
+  return total;
+}
+
+function applyBursts(db: DatabaseSync, bursts: DuplicateSubtitleLineBurst[]): void {
+  const removedLineIds = bursts.flatMap((burst) => burst.removedLineIds);
+  const currentMs = toDbTimestamp(nowMs());
+
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    for (const batch of chunk(removedLineIds, LINE_ID_BATCH_SIZE)) {
+      const placeholders = makePlaceholders(batch);
+      // Measured before the delete, applied after it: `applyLexicalRemovals` checks the
+      // surviving occurrences to decide whether a zeroed count really means the word is
+      // gone, so the rows it inspects have to be the post-delete ones.
+      const plan = planLexicalRemovalsForLines(db, batch);
+      db.prepare(`DELETE FROM imm_word_line_occurrences WHERE line_id IN (${placeholders})`).run(
+        ...batch,
+      );
+      db.prepare(`DELETE FROM imm_kanji_line_occurrences WHERE line_id IN (${placeholders})`).run(
+        ...batch,
+      );
+      db.prepare(`DELETE FROM imm_subtitle_lines WHERE line_id IN (${placeholders})`).run(...batch);
+      applyLexicalRemovals(db, plan);
+    }
+
+    const extendStmt = db.prepare(
+      `UPDATE imm_subtitle_lines
+       SET segment_end_ms = ?, LAST_UPDATE_DATE = ?
+       WHERE line_id = ? AND (segment_end_ms IS NULL OR segment_end_ms < ?)`,
+    );
+    for (const burst of bursts) {
+      extendStmt.run(burst.endMs, currentMs, burst.keptLineId, burst.endMs);
+    }
+    db.exec('COMMIT');
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+/**
+ * Collapse stored animation bursts down to one line each.
+ *
+ * A dry run measures exactly what an apply would remove, using the same scan, so the
+ * numbers shown in a confirmation prompt are the numbers that will happen.
+ */
+export function cleanupDuplicateSubtitleLines(
+  db: DatabaseSync,
+  options: DuplicateSubtitleLineCleanupOptions = {},
+): DuplicateSubtitleLineCleanupSummary {
+  const bounds = resolveBounds(options);
+  const dryRun = options.dryRun === true;
+  const rows = readCandidateLines(db, bounds);
+  const bursts = findDuplicateSubtitleLineBursts(rows, options);
+  const removedLineIds = bursts.flatMap((burst) => burst.removedLineIds);
+
+  const summary: DuplicateSubtitleLineCleanupSummary = {
+    dryRun,
+    lookbackDays: bounds.lookbackDays,
+    scannedLines: rows.length,
+    burstGroups: bursts.length,
+    removedLines: removedLineIds.length,
+    removedWordOccurrences: sumRemovedOccurrences(db, 'imm_word_line_occurrences', removedLineIds),
+    removedKanjiOccurrences: sumRemovedOccurrences(
+      db,
+      'imm_kanji_line_occurrences',
+      removedLineIds,
+    ),
+    samples: buildSamples(db, bursts, bounds.sampleLimit),
+  };
+
+  if (dryRun || removedLineIds.length === 0) {
+    return summary;
+  }
+
+  applyBursts(db, bursts);
+  return summary;
+}

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

@@ -268,6 +268,19 @@ export function planLexicalRemovalsForSessions(
   return planLexicalRemovals(db, `sl.session_id IN (${makePlaceholders(sessionIds)})`, sessionIds);
 }
 
+/**
+ * Measure what deleting these individual subtitle lines removes from the vocabulary
+ * tables. Used by the duplicate-line cleanup, which drops animation frames out of the
+ * middle of sessions that otherwise stay intact.
+ */
+export function planLexicalRemovalsForLines(
+  db: DatabaseSync,
+  lineIds: number[],
+): LexicalRemovalPlan {
+  if (lineIds.length === 0) return EMPTY_LEXICAL_REMOVAL_PLAN;
+  return planLexicalRemovals(db, `sl.line_id IN (${makePlaceholders(lineIds)})`, lineIds);
+}
+
 /** Measure what deleting these videos removes from the vocabulary tables. */
 export function planLexicalRemovalsForVideos(
   db: DatabaseSync,

src/core/services/index.ts

@@ -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';

src/core/services/ipc.ts

@@ -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();
   });

src/core/services/startup-bootstrap.test.ts

@@ -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', () => {

src/core/services/startup.ts

@@ -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');
   }
 

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

@@ -5,6 +5,7 @@ import {
   buildSentenceSearchOptions,
   enrichSessionsWithKnownWordMetrics,
   parseBooleanQuery,
+  parseDuplicateLineCleanupBody,
   parseExcludedWordsBody,
   parseIntQuery,
 } from './route-support.js';
@@ -40,6 +41,15 @@ export function registerStatsLibraryRoutes(
     return c.json(statsJson('setExcludedWords', { ok: true }));
   });
 
+  // Collapse animation bursts older versions recorded frame by frame. `dryRun` measures
+  // the same scan without writing, so the confirmation the user sees is the real cost.
+  app.post('/api/stats/maintenance/duplicate-lines', async (c) => {
+    const body = await c.req.json().catch(() => null);
+    const { dryRun, lookbackDays } = parseDuplicateLineCleanupBody(body);
+    const result = await tracker.cleanupDuplicateSubtitleLines({ dryRun, lookbackDays });
+    return c.json(statsJson('duplicateLineCleanup', result));
+  });
+
   app.get('/api/stats/vocabulary/occurrences', async (c) => {
     const headword = (c.req.query('headword') ?? '').trim();
     const word = (c.req.query('word') ?? '').trim();

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

@@ -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`;

src/core/services/stats-server/mining-support.ts

@@ -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(

src/core/services/stats-server/route-support.ts

@@ -88,6 +88,25 @@ export function parseExcludedWordsBody(body: unknown): StatsExcludedWord[] | nul
   return words;
 }
 
+/**
+ * Read a duplicate-line cleanup request. An absent or unusable `lookbackDays` scans all
+ * history, which is what the CLI does; only a positive number narrows the window.
+ */
+export function parseDuplicateLineCleanupBody(body: unknown): {
+  dryRun: boolean;
+  lookbackDays: number | null;
+} {
+  const source = body && typeof body === 'object' ? (body as Record<string, unknown>) : {};
+  const rawLookback = source.lookbackDays;
+  // Floor before the bounds check, or a fraction of a day arrives as a zero-day window.
+  const wholeDays =
+    typeof rawLookback === 'number' && Number.isFinite(rawLookback)
+      ? Math.floor(rawLookback)
+      : null;
+  const lookbackDays = wholeDays !== null && wholeDays >= 1 ? wholeDays : null;
+  return { dryRun: source.dryRun === true, lookbackDays };
+}
+
 export function loadKnownWordsSet(cachePath: string | undefined): Set<string> | null {
   if (!cachePath || !existsSync(cachePath)) return null;
   try {

src/core/services/subsync.test.ts

@@ -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');

src/core/services/subsync.ts

@@ -21,6 +21,11 @@ interface FileExtractionResult {
   temporary: boolean;
 }
 
+type SubtitleSlot = 'primary' | 'secondary';
+
+const SYNCED_TRACK_LOOKUP_ATTEMPTS = 5;
+const SYNCED_TRACK_LOOKUP_RETRY_MS = 100;
+
 function summarizeCommandFailure(command: string, result: CommandResult): string {
   const parts = [
     `code=${result.code ?? 'n/a'}`,
@@ -90,16 +95,28 @@ function getSourceTrackIdentity(track: MpvTrack): string {
   return 'unknown';
 }
 
-function dedupeSourceTracks(tracks: MpvTrack[]): MpvTrack[] {
-  const deduped = new Map<string, MpvTrack>();
+function isPinned(track: MpvTrack, pinnedIds: Set<number>): boolean {
+  return typeof track.id === 'number' && pinnedIds.has(track.id);
+}
+
+// Pinned tracks (the active primary/secondary) always survive, even when two of
+// them point at the same file; only unpinned duplicates are collapsed.
+function dedupeSubtitleTracks(tracks: MpvTrack[], pinnedIds: Set<number>): MpvTrack[] {
+  const pinnedIdentities = new Set(
+    tracks.filter((track) => isPinned(track, pinnedIds)).map(getSourceTrackIdentity),
+  );
+  const winners = new Map<string, MpvTrack>();
   for (const track of tracks) {
+    if (isPinned(track, pinnedIds)) continue;
     const identity = getSourceTrackIdentity(track);
-    const existing = deduped.get(identity);
+    if (pinnedIdentities.has(identity)) continue;
+    const existing = winners.get(identity);
     if (!existing || (track.selected && !existing.selected)) {
-      deduped.set(identity, track);
+      winners.set(identity, track);
     }
   }
-  return [...deduped.values()];
+  const kept = new Set(winners.values());
+  return tracks.filter((track) => isPinned(track, pinnedIds) || kept.has(track));
 }
 
 export interface TriggerSubsyncFromConfigDeps extends SubsyncCoreDeps {
@@ -142,20 +159,21 @@ async function gatherSubsyncContext(client: MpvClientLike): Promise<SubsyncConte
   }
 
   const secondaryTrack = subtitleTracks.find((track) => track.id === secondarySid) ?? null;
-  const sourceTracks = subtitleTracks
-    .filter((track) => track.id !== sid)
-    .filter((track) => {
-      if (!track.external) return true;
-      const filename = track['external-filename'];
-      return typeof filename === 'string' && filename.length > 0;
-    });
-  const uniqueSourceTracks = dedupeSourceTracks(sourceTracks);
+  const usableTracks = subtitleTracks.filter((track) => {
+    if (typeof track.id !== 'number') return false;
+    if (!track.external) return true;
+    const filename = track['external-filename'];
+    return typeof filename === 'string' && filename.length > 0;
+  });
 
   return {
     videoPath,
     primaryTrack,
     secondaryTrack,
-    sourceTracks: uniqueSourceTracks,
+    subtitleTracks: dedupeSubtitleTracks(
+      usableTracks,
+      new Set([sid, secondarySid].filter((id): id is number => typeof id === 'number')),
+    ),
     audioStreamIndex: client.currentAudioStreamIndex,
   };
 }
@@ -271,41 +289,104 @@ async function runFfsubsyncSync(
   return runCommand(ffsubsyncPath, args);
 }
 
-function loadSyncedSubtitle(client: MpvClientLike, pathToLoad: string): void {
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// mpv may echo the path back with different separators, and Windows paths are
+// case-insensitive, so compare normalized forms instead of raw strings.
+function normalizeSubtitlePathForCompare(value: string): string {
+  const normalized = value.replace(/\\/g, '/');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+async function findAddedSubtitleTrackId(
+  client: MpvClientLike,
+  pathToLoad: string,
+): Promise<number | null> {
+  const wanted = normalizeSubtitlePathForCompare(pathToLoad);
+  // sub-add is queued, so the track may not appear in the first track-list reply.
+  for (let attempt = 0; attempt < SYNCED_TRACK_LOOKUP_ATTEMPTS; attempt += 1) {
+    let tracks: MpvTrack[] = [];
+    try {
+      const trackListRaw = await client.requestProperty('track-list');
+      tracks = Array.isArray(trackListRaw) ? normalizeTrackIds(trackListRaw as MpvTrack[]) : [];
+    } catch {
+      return null;
+    }
+    // Re-adding a file mpv already knows appends a duplicate entry; the newest
+    // one holds the retimed content, so prefer the last match.
+    const matches = tracks.filter((track) => {
+      if (track.type !== 'sub') return false;
+      const filename = track['external-filename'];
+      return typeof filename === 'string' && normalizeSubtitlePathForCompare(filename) === wanted;
+    });
+    const added = matches[matches.length - 1];
+    if (added && typeof added.id === 'number') {
+      return added.id;
+    }
+    if (attempt < SYNCED_TRACK_LOOKUP_ATTEMPTS - 1) {
+      await delay(SYNCED_TRACK_LOOKUP_RETRY_MS);
+    }
+  }
+  return null;
+}
+
+async function loadSyncedSubtitle(
+  client: MpvClientLike,
+  pathToLoad: string,
+  slot: SubtitleSlot,
+): Promise<void> {
   if (!client.connected) {
     throw new Error('MPV disconnected while loading subtitle');
   }
-  client.send({ command: ['sub_add', pathToLoad] });
+
+  if (slot === 'secondary') {
+    // Keep the primary track untouched: load without selecting, then point
+    // secondary-sid at the freshly added track.
+    client.send({ command: ['sub-add', pathToLoad, 'auto'] });
+    client.send({ command: ['set_property', 'secondary-sub-delay', 0] });
+    const addedTrackId = await findAddedSubtitleTrackId(client, pathToLoad);
+    if (addedTrackId === null) {
+      throw new Error('Synchronized subtitle did not appear in the mpv track list');
+    }
+    client.send({ command: ['set_property', 'secondary-sid', addedTrackId] });
+    return;
+  }
+
+  client.send({ command: ['sub-add', pathToLoad] });
   client.send({ command: ['set_property', 'sub-delay', 0] });
 }
 
 async function subsyncToReference(
   engine: 'alass' | 'ffsubsync',
   referenceFilePath: string,
+  targetTrack: MpvTrack,
   context: SubsyncContext,
   resolved: SubsyncResolvedConfig,
   client: MpvClientLike,
+  slot: SubtitleSlot,
 ): Promise<SubsyncResult> {
   const ffmpegPath = ensureExecutablePath(resolved.ffmpegPath, 'ffmpeg');
-  const primaryExtraction = await extractSubtitleTrackToFile(
+  const targetExtraction = await extractSubtitleTrackToFile(
     ffmpegPath,
     context.videoPath,
-    context.primaryTrack,
+    targetTrack,
   );
-  const replacePrimary = resolved.replace !== false && !primaryExtraction.temporary;
-  const outputPath = buildRetimedPath(primaryExtraction.path, replacePrimary);
+  const replaceTarget = resolved.replace !== false && !targetExtraction.temporary;
+  const outputPath = buildRetimedPath(targetExtraction.path, replaceTarget);
 
   try {
     let result: CommandResult;
     if (engine === 'alass') {
       const alassPath = ensureExecutablePath(resolved.alassPath, 'alass');
-      result = await runAlassSync(alassPath, referenceFilePath, primaryExtraction.path, outputPath);
+      result = await runAlassSync(alassPath, referenceFilePath, targetExtraction.path, outputPath);
     } else {
       const ffsubsyncPath = ensureExecutablePath(resolved.ffsubsyncPath, 'ffsubsync');
       result = await runFfsubsyncSync(
         ffsubsyncPath,
         context.videoPath,
-        primaryExtraction.path,
+        targetExtraction.path,
         outputPath,
         context.audioStreamIndex,
       );
@@ -319,13 +400,13 @@ async function subsyncToReference(
       };
     }
 
-    loadSyncedSubtitle(client, outputPath);
+    await loadSyncedSubtitle(client, outputPath, slot);
     return {
       ok: true,
       message: `Subtitle synchronized with ${engine}`,
     };
   } finally {
-    cleanupTemporaryFile(primaryExtraction);
+    cleanupTemporaryFile(targetExtraction);
   }
 }
 
@@ -337,6 +418,25 @@ function validateFfsubsyncReference(videoPath: string): void {
   }
 }
 
+function resolveTargetTrack(
+  request: SubsyncManualRunRequest,
+  context: SubsyncContext,
+): MpvTrack | null {
+  if (request.targetTrackId === undefined || request.targetTrackId === null) {
+    return context.primaryTrack;
+  }
+  return getTrackById(context.subtitleTracks, request.targetTrackId);
+}
+
+// Retiming the secondary track must not steal the primary slot: the synced file
+// goes back where the out-of-sync one was.
+function resolveTargetSlot(targetTrack: MpvTrack, context: SubsyncContext): SubtitleSlot {
+  if (typeof targetTrack.id !== 'number') return 'primary';
+  if (targetTrack.id === context.primaryTrack.id) return 'primary';
+  if (context.secondaryTrack && targetTrack.id === context.secondaryTrack.id) return 'secondary';
+  return 'primary';
+}
+
 export async function runSubsyncManual(
   request: SubsyncManualRunRequest,
   deps: SubsyncCoreDeps,
@@ -345,6 +445,12 @@ export async function runSubsyncManual(
   const context = await gatherSubsyncContext(client);
   const resolved = deps.getResolvedConfig();
 
+  const targetTrack = resolveTargetTrack(request, context);
+  if (!targetTrack) {
+    return { ok: false, message: 'Select the out-of-sync subtitle track to retime' };
+  }
+  const targetSlot = resolveTargetSlot(targetTrack, context);
+
   if (request.engine === 'ffsubsync') {
     try {
       validateFfsubsyncReference(context.videoPath);
@@ -354,22 +460,64 @@ export async function runSubsyncManual(
         message: `ffsubsync synchronization failed: ${(error as Error).message}`,
       };
     }
-    return subsyncToReference('ffsubsync', context.videoPath, context, resolved, client);
+    return subsyncToReference(
+      'ffsubsync',
+      context.videoPath,
+      targetTrack,
+      context,
+      resolved,
+      client,
+      targetSlot,
+    );
   }
 
-  const sourceTrack = getTrackById(context.sourceTracks, request.sourceTrackId ?? null);
-  if (!sourceTrack) {
-    return { ok: false, message: 'Select a subtitle source track for alass' };
+  if (request.referenceMode === 'video') {
+    if (isRemoteMediaPath(context.videoPath)) {
+      return {
+        ok: false,
+        message:
+          'alass cannot use a stream URL as reference. Pick a reference subtitle track instead.',
+      };
+    }
+    return subsyncToReference(
+      'alass',
+      context.videoPath,
+      targetTrack,
+      context,
+      resolved,
+      client,
+      targetSlot,
+    );
+  }
+
+  const referenceTrack = getTrackById(context.subtitleTracks, request.referenceTrackId ?? null);
+  if (!referenceTrack) {
+    return { ok: false, message: 'Select a reference subtitle track for alass' };
+  }
+  if (referenceTrack.id === targetTrack.id) {
+    return { ok: false, message: 'Reference and out-of-sync subtitles must be different tracks' };
   }
 
   const ffmpegPath = ensureExecutablePath(resolved.ffmpegPath, 'ffmpeg');
-  let sourceExtraction: FileExtractionResult | null = null;
+  let referenceExtraction: FileExtractionResult | null = null;
   try {
-    sourceExtraction = await extractSubtitleTrackToFile(ffmpegPath, context.videoPath, sourceTrack);
-    return await subsyncToReference('alass', sourceExtraction.path, context, resolved, client);
+    referenceExtraction = await extractSubtitleTrackToFile(
+      ffmpegPath,
+      context.videoPath,
+      referenceTrack,
+    );
+    return await subsyncToReference(
+      'alass',
+      referenceExtraction.path,
+      targetTrack,
+      context,
+      resolved,
+      client,
+      targetSlot,
+    );
   } finally {
-    if (sourceExtraction) {
-      cleanupTemporaryFile(sourceExtraction);
+    if (referenceExtraction) {
+      cleanupTemporaryFile(referenceExtraction);
     }
   }
 }
@@ -377,14 +525,27 @@ export async function runSubsyncManual(
 export async function openSubsyncManualPicker(deps: TriggerSubsyncFromConfigDeps): Promise<void> {
   const client = getMpvClientForSubsync(deps);
   const context = await gatherSubsyncContext(client);
+  const subtitleTracks = context.subtitleTracks
+    .filter((track) => typeof track.id === 'number')
+    .map((track) => ({
+      id: track.id as number,
+      label: formatTrackLabel(track),
+    }));
+  const primaryTrackId =
+    typeof context.primaryTrack.id === 'number' ? context.primaryTrack.id : null;
+  const secondaryTrackId =
+    typeof context.secondaryTrack?.id === 'number' ? context.secondaryTrack.id : null;
   const payload: SubsyncManualPayload = {
+    subtitleTracks,
+    // The secondary track can be filtered or deduped out of the emitted list,
+    // so only default to it when the picker actually offers it.
+    defaultReferenceTrackId:
+      subtitleTracks.find((track) => track.id === secondaryTrackId)?.id ??
+      subtitleTracks.find((track) => track.id !== primaryTrackId)?.id ??
+      null,
+    defaultTargetTrackId: primaryTrackId,
+    videoReferenceAvailable: !isRemoteMediaPath(context.videoPath),
     ffsubsyncAvailable: !isRemoteMediaPath(context.videoPath),
-    sourceTracks: context.sourceTracks
-      .filter((track) => typeof track.id === 'number')
-      .map((track) => ({
-        id: track.id as number,
-        label: formatTrackLabel(track),
-      })),
   };
   deps.openManualPicker(payload);
 }
@@ -397,7 +558,7 @@ export async function triggerSubsyncFromConfig(deps: TriggerSubsyncFromConfigDep
 
   try {
     await openSubsyncManualPicker(deps);
-    deps.showMpvOsd('Subsync: choose engine and source');
+    deps.showMpvOsd('Subsync: choose engine and subtitles');
   } catch (error) {
     deps.showMpvOsd(`Subsync failed: ${(error as Error).message}`);
   } finally {

src/core/services/subtitle-burst-constants.ts

@@ -0,0 +1,40 @@
+/*
+ * Thresholds that decide when a run of repeated subtitle events is one animation.
+ *
+ * Three consumers have to agree on these numbers or the same karaoke line is one cue in
+ * the sidebar and two hundred in the stats: the file-level cue dedup
+ * (`subtitle-cue-dedup`), the live gate that decides what immersion stats record
+ * (`subtitle-line-dedup-gate`), and the retroactive database cleanup
+ * (`immersion-tracker/duplicate-line-cleanup`).
+ */
+
+/**
+ * Back-to-back frames of the same animation are authored flush against each other; a
+ * tiny tolerance absorbs the centisecond rounding of the ASS timestamp format.
+ */
+export const DUPLICATE_CUE_GAP_TOLERANCE_SECONDS = 0.05;
+
+/**
+ * A burst is a *sequence*. Two adjacent events are two events, not an animation --
+ * characters do repeat each other, and a repeated line can legitimately be short.
+ */
+export const MIN_BURST_EVENTS = 3;
+
+/**
+ * Real dialogue holds on screen for about a second, so a run with a couple of much
+ * shorter events among them looks like frames. Used only alongside authoring evidence.
+ */
+export const ANIMATION_FRAME_MAX_SECONDS = 0.3;
+
+/** A karaoke run usually ends on a long "hold" frame, so not every event is short. */
+export const MIN_TAGGED_BURST_FRAMES = 2;
+
+/**
+ * SRT and VTT carry no authoring metadata at all, so timing is the only signal available
+ * -- which makes it the easiest one to get wrong. ASS->SRT conversion leaves frames at
+ * ~0.04s, well under any real utterance, and a burst leaves many of them behind. Both
+ * bounds are deliberately far stricter than the ASS path: a run of ordinary short lines
+ * (`えっ` traded between characters) must not clear them.
+ */
+export const TIMING_ONLY_FRAME_MAX_SECONDS = 0.1;
+export const MIN_TIMING_ONLY_FRAMES = 5;

src/core/services/subtitle-cue-dedup.ts

@@ -0,0 +1,180 @@
+/*
+ * Duplicate/animation-burst collapsing for parsed subtitle cues.
+ *
+ * Split out of the cue parser so the parsing rules and the "is this run one animation?"
+ * heuristics can be read -- and tested -- on their own. The parser owns the cue shape;
+ * this module only decides which cues survive.
+ */
+
+import { hasAssTemporalOverride, isAnimatedAssEffectKind } from './ass-text';
+import {
+  ANIMATION_FRAME_MAX_SECONDS,
+  DUPLICATE_CUE_GAP_TOLERANCE_SECONDS,
+  MIN_BURST_EVENTS,
+  MIN_TAGGED_BURST_FRAMES,
+  MIN_TIMING_ONLY_FRAMES,
+  TIMING_ONLY_FRAME_MAX_SECONDS,
+} from './subtitle-burst-constants';
+import type {
+  AnnotatedSubtitleCue,
+  SubtitleCue,
+  SubtitleSourceFormat,
+} from './subtitle-cue-parser';
+
+function cueKey(cue: SubtitleCue): string {
+  return `${cue.startTime}|${cue.endTime}|${cue.text}`;
+}
+
+/**
+ * Identical text over an identical span is redundant however it was authored -- most
+ * often a layered ASS event stacking a shadow copy under the visible one.
+ */
+function collapseExactDuplicates(cues: AnnotatedSubtitleCue[]): AnnotatedSubtitleCue[] {
+  const seen = new Set<string>();
+  return cues.filter((cue) => {
+    const key = cueKey(cue);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+function countFramesShorterThan(run: AnnotatedSubtitleCue[], maxSeconds: number): number {
+  return run.filter((cue) => cue.endTime - cue.startTime < maxSeconds).length;
+}
+
+/**
+ * Evidence that a run of ASS events is one animation rather than several authored lines.
+ * A static tag says nothing on its own -- three events sharing one `\clip(...)` are three
+ * signs -- so the tag has to be temporal by nature (`\t`, `\move`, karaoke timing, or
+ * anything wrapped in `\t(...)`), an animated `Effect` column, or a value that actually
+ * changes from event to event, which is how per-frame typesetting is authored.
+ */
+export function hasAssAnimationEvidence(run: AnnotatedSubtitleCue[]): boolean {
+  if (run.every((cue) => hasAssTemporalOverride(cue.overrides))) {
+    return true;
+  }
+  if (run.every((cue) => isAnimatedAssEffectKind(cue.effectKind))) {
+    return true;
+  }
+
+  const [first] = run;
+  const everyEventTypeset = run.every((cue) => cue.overrides.length > 0);
+  const signatureChanges = run.some((cue) => cue.overrideSignature !== first!.overrideSignature);
+  return everyEventTypeset && signatureChanges;
+}
+
+export function isAnimationBurst(
+  run: AnnotatedSubtitleCue[],
+  format: SubtitleSourceFormat,
+): boolean {
+  if (run.length < MIN_BURST_EVENTS) {
+    return false;
+  }
+
+  if (format === 'srt') {
+    return (
+      run.length >= MIN_TIMING_ONLY_FRAMES &&
+      countFramesShorterThan(run, TIMING_ONLY_FRAME_MAX_SECONDS) === run.length
+    );
+  }
+
+  if (countFramesShorterThan(run, ANIMATION_FRAME_MAX_SECONDS) < MIN_TAGGED_BURST_FRAMES) {
+    return false;
+  }
+
+  // One animation belongs to one styled, one named source line. Two characters trading
+  // the same short word are two styles or two actors, and never merge.
+  const [first] = run;
+  if (run.some((cue) => cue.style !== first!.style || cue.name !== first!.name)) {
+    return false;
+  }
+
+  return hasAssAnimationEvidence(run);
+}
+
+/**
+ * Karaoke and sign typesetting emits one Dialogue event per animation frame, all carrying
+ * the same visible text over a contiguous span. Collapse each such run into a single cue.
+ *
+ * Only runs that look like animation collapse. Two ordinary lines that happen to repeat
+ * -- several characters each saying `おはよう` in turn, a positioned sign redrawn with a
+ * different fade -- stay separate, because merging them would destroy real mineable lines.
+ */
+function collapseAnimationBursts(
+  cues: AnnotatedSubtitleCue[],
+  format: SubtitleSourceFormat,
+): AnnotatedSubtitleCue[] {
+  const indicesByText = new Map<string, number[]>();
+  cues.forEach((cue, index) => {
+    const bucket = indicesByText.get(cue.text);
+    if (bucket) {
+      bucket.push(index);
+    } else {
+      indicesByText.set(cue.text, [index]);
+    }
+  });
+
+  const dropped = new Set<number>();
+  const extendedEnd = new Map<number, number>();
+
+  for (const indices of indicesByText.values()) {
+    if (indices.length < MIN_BURST_EVENTS) {
+      continue;
+    }
+
+    let runStart = 0;
+    while (runStart < indices.length) {
+      let runEnd = runStart;
+      let chainEnd = cues[indices[runStart]!]!.endTime;
+
+      while (runEnd + 1 < indices.length) {
+        const next = cues[indices[runEnd + 1]!]!;
+        if (next.startTime > chainEnd + DUPLICATE_CUE_GAP_TOLERANCE_SECONDS) {
+          break;
+        }
+        chainEnd = Math.max(chainEnd, next.endTime);
+        runEnd += 1;
+      }
+
+      const run = indices.slice(runStart, runEnd + 1).map((index) => cues[index]!);
+      if (isAnimationBurst(run, format)) {
+        for (let i = runStart + 1; i <= runEnd; i += 1) {
+          dropped.add(indices[i]!);
+        }
+        extendedEnd.set(indices[runStart]!, chainEnd);
+      }
+
+      runStart = runEnd + 1;
+    }
+  }
+
+  if (dropped.size === 0) {
+    return cues;
+  }
+
+  const merged: AnnotatedSubtitleCue[] = [];
+  cues.forEach((cue, index) => {
+    if (dropped.has(index)) {
+      return;
+    }
+    const end = extendedEnd.get(index);
+    merged.push(end !== undefined && end > cue.endTime ? { ...cue, endTime: end } : cue);
+  });
+  return merged;
+}
+
+/**
+ * Collapse redundant cues. Input must already be sorted by non-decreasing `startTime`,
+ * ties broken by `endTime` then source `order` -- burst detection chains events by
+ * comparing each one against the running end of the events before it, so an unsorted
+ * list breaks runs apart and leaves the frames behind.
+ */
+export function mergeDuplicateCues(
+  cues: AnnotatedSubtitleCue[],
+  format: SubtitleSourceFormat,
+): AnnotatedSubtitleCue[] {
+  return collapseAnimationBursts(collapseExactDuplicates(cues), format);
+}

src/core/services/subtitle-cue-parser.test.ts

@@ -91,6 +91,17 @@ test('parseSrtCues skips malformed timing lines gracefully', () => {
   assert.equal(cues[0]!.text, '有効');
 });
 
+test('parseSubtitleCues strips complete brace blocks from SRT and VTT text', () => {
+  const content = ['1', '00:00:01,000 --> 00:00:02,000', '彼は{謎}と言った', ''].join('\n');
+
+  for (const filename of ['test.srt', 'test.vtt']) {
+    const cues = parseSubtitleCues(content, filename);
+
+    assert.equal(cues.length, 1, filename);
+    assert.equal(cues[0]!.text, '彼はと言った', filename);
+  }
+});
+
 test('parseAssCues parses basic ASS dialogue lines', () => {
   const content = [
     '[Script Info]',
@@ -137,7 +148,9 @@ test('parseAssCues handles text containing commas', () => {
   assert.equal(cues[0]!.text, 'はい、そうです、ね');
 });
 
-test('parseAssCues handles \\N line breaks', () => {
+test('parseAssCues decodes \\N line breaks into real newlines', () => {
+  // ASS is decoded once, here at ingestion, so cue text matches what mpv hands over for
+  // the same line played live.
   const content = [
     '[Events]',
     'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
@@ -146,7 +159,7 @@ test('parseAssCues handles \\N line breaks', () => {
 
   const cues = parseAssCues(content);
 
-  assert.equal(cues[0]!.text, '一行目\\N二行目');
+  assert.equal(cues[0]!.text, '一行目\n二行目');
 });
 
 test('parseAssCues strips HTML-like markup while preserving ASS line breaks', () => {
@@ -158,7 +171,46 @@ test('parseAssCues strips HTML-like markup while preserving ASS line breaks', ()
 
   const cues = parseAssCues(content);
 
-  assert.equal(cues[0]!.text, '一行目\\N二行目');
+  assert.equal(cues[0]!.text, '一行目\n二行目');
+});
+
+test('parseAssCues drops vector drawing runs enabled by \\p', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\an5\\pos(730,1042)\\p1\\blur1}m 20 0 b 10 0 0 10 0 20 b 0 31 10 40 20 40 {\\p0}',
+    'Dialogue: 0,0:00:05.00,0:00:08.00,Default,,0,0,0,,これは字幕',
+  ].join('\n');
+
+  const cues = parseAssCues(content);
+
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]!.text, 'これは字幕');
+});
+
+test('parseAssCues keeps text that follows a \\p0 reset on the same line', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\p1}m 0 0 l 10 10{\\p0}本文{\\p1}m 5 5 l 6 6{\\p0}続き',
+  ].join('\n');
+
+  const cues = parseAssCues(content);
+
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]!.text, '本文続き');
+});
+
+test('parseAssCues leaves \\pos untouched when no drawing mode is active', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(960,1068)\\bord3}位置指定',
+  ].join('\n');
+
+  const cues = parseAssCues(content);
+
+  assert.equal(cues[0]!.text, '位置指定');
 });
 
 test('parseAssCues returns empty for content without Events section', () => {
@@ -258,6 +310,344 @@ test('parseSubtitleCues returns cues sorted by start time', () => {
   assert.equal(cues[1]!.text, '二番目');
 });
 
+test('parseSubtitleCues collapses per-frame karaoke duplicates into one cue', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.05,OP_JP,,0,0,0,,{\\clip(m 1 1)}過ぎ去ってしまう瞬間を',
+    'Dialogue: 0,0:00:01.05,0:00:01.09,OP_JP,,0,0,0,,{\\clip(m 2 2)}過ぎ去ってしまう瞬間を',
+    'Dialogue: 0,0:00:01.09,0:00:03.55,OP_JP,,0,0,0,,{\\clip(m 3 3)}過ぎ去ってしまう瞬間を',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]!.startTime, 1.0);
+  assert.equal(cues[0]!.endTime, 3.55);
+  assert.equal(cues[0]!.text, '過ぎ去ってしまう瞬間を');
+});
+
+test('parseSubtitleCues keeps back-to-back plain dialogue repeats separate', () => {
+  // Several characters greeting in turn: distinct utterances that happen to abut.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:04:05.67,0:04:06.82,Dial_JP,,0,0,0,,おはよう',
+    'Dialogue: 0,0:04:06.82,0:04:07.56,Dial_JP,,0,0,0,,おはよう',
+    'Dialogue: 0,0:04:07.56,0:04:08.78,Dial_JP,,0,0,0,,おはよう',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 3);
+  assert.equal(cues[0]!.endTime, 246.82);
+  assert.equal(cues[2]!.startTime, 247.56);
+});
+
+test('parseSubtitleCues collapses exact duplicate cues even without effect tags', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,重なった行',
+    'Dialogue: 1,0:00:01.00,0:00:04.00,Default,,0,0,0,,重なった行',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 1);
+});
+
+test('parseSubtitleCues collapses tag-less animation frames in converted SRT', () => {
+  // ASS -> SRT conversion drops override tags, so only the ~0.04s frame timing remains.
+  const lines = ['1', '00:00:07,870 --> 00:00:07,910', 'Kaguya Wants to be Confessed to', ''];
+  for (let i = 1; i < 8; i++) {
+    const start = 7910 + (i - 1) * 40;
+    const end = start + 40;
+    const at = (ms: number) =>
+      `00:00:0${Math.floor(ms / 1000)},${String(ms % 1000).padStart(3, '0')}`;
+    lines.push(String(i + 1), `${at(start)} --> ${at(end)}`, 'Kaguya Wants to be Confessed to', '');
+  }
+
+  const cues = parseSubtitleCues(lines.join('\n'), 'test.srt');
+
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]!.startTime, 7.87);
+});
+
+test('parseSubtitleCues keeps identical lines that recur far apart', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,なんで',
+    'Dialogue: 0,0:05:00.00,0:05:01.00,Default,,0,0,0,,なんで',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 2);
+  assert.equal(cues[0]!.startTime, 1.0);
+  assert.equal(cues[1]!.startTime, 300.0);
+});
+
+test('parseSubtitleCues keeps two positioned signs that repeat the same text', () => {
+  // Both carry override tags, but `\pos` and `\fad` are static placement, not animation.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:01:00.00,0:01:03.00,Sign,,0,0,0,,{\\pos(960,120)\\fad(200,200)}第一話',
+    'Dialogue: 0,0:01:03.00,0:01:06.00,Sign,,0,0,0,,{\\pos(960,900)\\fad(200,200)}第一話',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 2);
+  assert.equal(cues[1]!.startTime, 63.0);
+});
+
+test('parseSubtitleCues keeps a run of ordinary positioned lines separate', () => {
+  // Three events is a sequence, but none of them runs at animation-frame speed.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:01:00.00,0:01:02.00,Sign,,0,0,0,,{\\pos(960,120)\\fad(100,100)}止まれ',
+    'Dialogue: 0,0:01:02.00,0:01:04.00,Sign,,0,0,0,,{\\pos(960,120)\\fad(100,100)}止まれ',
+    'Dialogue: 0,0:01:04.00,0:01:06.00,Sign,,0,0,0,,{\\pos(960,120)\\fad(100,100)}止まれ',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 3);
+});
+
+test('parseSubtitleCues keeps a short repeated SRT pair without burst evidence', () => {
+  const content = [
+    '1',
+    '00:00:01,000 --> 00:00:01,200',
+    'えっ',
+    '',
+    '2',
+    '00:00:01,200 --> 00:00:01,400',
+    'えっ',
+    '',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.srt');
+
+  assert.equal(cues.length, 2);
+});
+
+test('parseSubtitleCues collapses a burst marked only by the Effect column', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.05,OP_JP,,0,0,0,Karaoke,歌詞',
+    'Dialogue: 0,0:00:01.05,0:00:01.09,OP_JP,,0,0,0,Karaoke,歌詞',
+    'Dialogue: 0,0:00:01.09,0:00:03.55,OP_JP,,0,0,0,Karaoke,歌詞',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]!.endTime, 3.55);
+});
+
+test('parseSubtitleCues keeps a second karaoke burst that starts after a gap', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.05,OP_JP,,0,0,0,,{\\clip(m 1 1)}リフレイン',
+    'Dialogue: 0,0:00:01.05,0:00:01.09,OP_JP,,0,0,0,,{\\clip(m 2 2)}リフレイン',
+    'Dialogue: 0,0:00:01.09,0:00:03.00,OP_JP,,0,0,0,,{\\clip(m 3 3)}リフレイン',
+    'Dialogue: 0,0:00:20.00,0:00:20.05,OP_JP,,0,0,0,,{\\clip(m 1 1)}リフレイン',
+    'Dialogue: 0,0:00:20.05,0:00:20.09,OP_JP,,0,0,0,,{\\clip(m 2 2)}リフレイン',
+    'Dialogue: 0,0:00:20.09,0:00:22.00,OP_JP,,0,0,0,,{\\clip(m 3 3)}リフレイン',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 2);
+  assert.equal(cues[0]!.endTime, 3.0);
+  assert.equal(cues[1]!.startTime, 20.0);
+  assert.equal(cues[1]!.endTime, 22.0);
+});
+
+test('parseSubtitleCues does not merge a burst into unrelated dialogue between frames', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.05,OP_JP,,0,0,0,,{\\clip(m 1 1)}歌詞',
+    'Dialogue: 0,0:00:01.02,0:00:03.00,Dial_JP,,0,0,0,,別のセリフ',
+    'Dialogue: 0,0:00:01.05,0:00:01.09,OP_JP,,0,0,0,,{\\clip(m 2 2)}歌詞',
+    'Dialogue: 0,0:00:01.09,0:00:03.55,OP_JP,,0,0,0,,{\\clip(m 3 3)}歌詞',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 2);
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['歌詞', '別のセリフ'],
+  );
+  assert.equal(cues[0]!.endTime, 3.55);
+});
+
+test('parseSubtitleCues keeps rapid ASS lines from different actors separate', () => {
+  // Three 200ms `えっ` reactions traded between characters. Fast, adjacent and identical,
+  // but authored as three lines: different styles and different actors.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.20,Dial_A,アリス,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.20,0:00:01.40,Dial_B,ボブ,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.40,0:00:01.60,Dial_C,キャロル,0,0,0,,えっ',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 3);
+});
+
+test('parseSubtitleCues reads the speaker column when it is spelled Actor', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Actor, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.20,Dial_JP,アリス,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.20,0:00:01.40,Dial_JP,ボブ,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.40,0:00:01.60,Dial_JP,キャロル,0,0,0,,えっ',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 3);
+});
+
+test('parseSubtitleCues does not treat a custom Effect name as animation', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.20,Sign,,0,0,0,scrolling-credit,制作',
+    'Dialogue: 0,0:00:01.20,0:00:01.40,Sign,,0,0,0,scrolling-credit,制作',
+    'Dialogue: 0,0:00:01.40,0:00:01.60,Sign,,0,0,0,scrolling-credit,制作',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 3);
+});
+
+test('parseSubtitleCues keeps rapid ASS lines that share a style but not an actor', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.20,Dial_JP,アリス,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.20,0:00:01.40,Dial_JP,ボブ,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.40,0:00:01.60,Dial_JP,キャロル,0,0,0,,えっ',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 3);
+});
+
+test('parseSubtitleCues keeps untagged rapid ASS repeats separate', () => {
+  // No overrides at all: timing-only evidence is an SRT/VTT fallback and must not apply
+  // to ASS, where the absence of typesetting is itself evidence of plain dialogue.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.05,Dial_JP,,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.05,0:00:01.10,Dial_JP,,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.10,0:00:01.15,Dial_JP,,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.15,0:00:01.20,Dial_JP,,0,0,0,,えっ',
+    'Dialogue: 0,0:00:01.20,0:00:01.25,Dial_JP,,0,0,0,,えっ',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 5);
+});
+
+test('parseSubtitleCues keeps repeated signs sharing one static clip', () => {
+  // `\clip` is a static shape for the event. Three events with the identical clip were
+  // typeset the same way, so none of them is a frame of the others.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.20,Sign,,0,0,0,,{\\clip(0,0,100,100)}注意',
+    'Dialogue: 0,0:00:01.20,0:00:01.40,Sign,,0,0,0,,{\\clip(0,0,100,100)}注意',
+    'Dialogue: 0,0:00:01.40,0:00:01.60,Sign,,0,0,0,,{\\clip(0,0,100,100)}注意',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 3);
+});
+
+test('parseSubtitleCues collapses a sign animated through \\t', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.20,Sign,,0,0,0,,{\\pos(10,10)\\t(0,200,\\frz30)}回る',
+    'Dialogue: 0,0:00:01.20,0:00:01.40,Sign,,0,0,0,,{\\pos(10,10)\\t(0,200,\\frz30)}回る',
+    'Dialogue: 0,0:00:01.40,0:00:03.00,Sign,,0,0,0,,{\\pos(10,10)\\t(0,200,\\frz30)}回る',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]!.endTime, 3.0);
+});
+
+test('parseSubtitleCues keeps a short repeated SRT run above the frame threshold', () => {
+  // Five contiguous 200ms cues: a sequence, but nowhere near animation-frame speed.
+  const lines: string[] = [];
+  for (let i = 0; i < 5; i++) {
+    const start = 1000 + i * 200;
+    const at = (ms: number) =>
+      `00:00:0${Math.floor(ms / 1000)},${String(ms % 1000).padStart(3, '0')}`;
+    lines.push(String(i + 1), `${at(start)} --> ${at(start + 200)}`, 'えっ', '');
+  }
+
+  const cues = parseSubtitleCues(lines.join('\n'), 'test.srt');
+
+  assert.equal(cues.length, 5);
+});
+
+test('parseSubtitleCues keeps a short SRT frame run below the minimum length', () => {
+  // Four 40ms frames: frame-speed, but too few to tell an animation from an artefact.
+  const lines: string[] = [];
+  for (let i = 0; i < 4; i++) {
+    const start = 7870 + i * 40;
+    const at = (ms: number) =>
+      `00:00:0${Math.floor(ms / 1000)},${String(ms % 1000).padStart(3, '0')}`;
+    lines.push(String(i + 1), `${at(start)} --> ${at(start + 40)}`, 'タイトル', '');
+  }
+
+  const cues = parseSubtitleCues(lines.join('\n'), 'test.srt');
+
+  assert.equal(cues.length, 4);
+});
+
+test('parseSubtitleCues applies ASS burst rules to ASS content behind an .srt filename', () => {
+  // The extension lies, so the SRT parser finds nothing and the content-sniffing fallback
+  // takes over -- which has to carry the `ass` source format with it, or the far stricter
+  // timing-only thresholds would let this karaoke burst through as three cues.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:01.20,Karaoke,,0,0,0,,{\\k20}歌詞',
+    'Dialogue: 0,0:00:01.20,0:00:01.40,Karaoke,,0,0,0,,{\\k20}歌詞',
+    'Dialogue: 0,0:00:01.40,0:00:03.00,Karaoke,,0,0,0,,{\\k20}歌詞',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.srt');
+
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]!.startTime, 1.0);
+  assert.equal(cues[0]!.endTime, 3.0);
+  assert.equal(cues[0]!.text, '歌詞');
+});
+
 test('parseSubtitleCues detects subtitle formats from remote URLs', () => {
   const assContent = [
     '[Events]',

src/core/services/subtitle-cue-parser.ts

@@ -1,9 +1,46 @@
+import {
+  assOverrideSignature,
+  assToPlainText,
+  collectAssOverrideCommands,
+  parseAssEffectField,
+  type AssEffectKind,
+  type AssOverrideCommand,
+} from './ass-text';
+import { mergeDuplicateCues } from './subtitle-cue-dedup';
+
 export interface SubtitleCue {
   startTime: number;
   endTime: number;
   text: string;
 }
 
+/**
+ * Everything the parser knows about a source event, shared only with the dedup engine.
+ * Deduplication needs the authoring context -- which style the line belongs to, which
+ * override commands it carries, whether the `Effect` column was set -- to tell a karaoke
+ * burst apart from two characters saying the same word in turn. None of it is meaningful
+ * outside the parser, so the public API stays `{startTime, endTime, text}`.
+ */
+export interface AnnotatedSubtitleCue extends SubtitleCue {
+  /** Text exactly as authored, override blocks and all. */
+  rawText: string;
+  style: string;
+  layer: number;
+  /** ASS `Name`/`Actor` column. */
+  name: string;
+  /** ASS `Effect` column, verbatim. */
+  effect: string;
+  effectKind: AssEffectKind;
+  /** Override commands found in `{...}` blocks, with their arguments. */
+  overrides: readonly AssOverrideCommand[];
+  /** Canonical form of `overrides`, for spotting values that change across a run. */
+  overrideSignature: string;
+  /** Position in the source file, so sorting by time stays deterministic across layers. */
+  order: number;
+}
+
+export type SubtitleSourceFormat = 'ass' | 'srt';
+
 const HTML_SUBTITLE_TAG_PATTERN = /<\/?[A-Za-z][^>\n]*>/g;
 
 const SRT_TIMING_PATTERN =
@@ -23,12 +60,21 @@ function parseTimestamp(
   );
 }
 
+/**
+ * The single ASS decode for the file path: cues leave the parser as plain text with real
+ * line breaks, matching what mpv hands over for the same line played live. No layer
+ * downstream decodes ASS again.
+ */
 function sanitizeSubtitleCueText(text: string): string {
-  return text.replace(ASS_OVERRIDE_TAG_PATTERN, '').replace(HTML_SUBTITLE_TAG_PATTERN, '').trim();
+  return assToPlainText(text, '\n').replace(HTML_SUBTITLE_TAG_PATTERN, '').trim();
 }
 
-export function parseSrtCues(content: string): SubtitleCue[] {
-  const cues: SubtitleCue[] = [];
+function toPublicCues(cues: AnnotatedSubtitleCue[]): SubtitleCue[] {
+  return cues.map(({ startTime, endTime, text }) => ({ startTime, endTime, text }));
+}
+
+function parseAnnotatedSrtCues(content: string): AnnotatedSubtitleCue[] {
+  const cues: AnnotatedSubtitleCue[] = [];
   const lines = content.split(/\r?\n/);
   let i = 0;
 
@@ -60,20 +106,39 @@ export function parseSrtCues(content: string): SubtitleCue[] {
       i += 1;
     }
 
-    const text = sanitizeSubtitleCueText(textLines.join('\n'));
+    const rawText = textLines.join('\n');
+    const text = sanitizeSubtitleCueText(rawText);
     if (text) {
-      cues.push({ startTime, endTime, text });
+      cues.push({
+        startTime,
+        endTime,
+        text,
+        rawText,
+        style: '',
+        layer: 0,
+        name: '',
+        effect: '',
+        effectKind: 'none',
+        // SRT and VTT carry no authoring metadata, and the dedup engine never reads
+        // overrides for those formats -- collecting them would be parsing for nobody.
+        overrides: [],
+        overrideSignature: '',
+        order: cues.length,
+      });
     }
   }
 
   return cues;
 }
 
-const ASS_OVERRIDE_TAG_PATTERN = /\{[^}]*\}/g;
+export function parseSrtCues(content: string): SubtitleCue[] {
+  return toPublicCues(parseAnnotatedSrtCues(content));
+}
 
 const ASS_TIMING_PATTERN = /^(\d+):(\d{2}):(\d{2})\.(\d{1,2})$/;
 const ASS_FORMAT_PREFIX = 'Format:';
 const ASS_DIALOGUE_PREFIX = 'Dialogue:';
+const ASS_NAME_FIELD_ALIASES = ['name', 'actor'];
 
 function parseAssTimestamp(raw: string): number | null {
   const match = ASS_TIMING_PATTERN.exec(raw.trim());
@@ -87,13 +152,43 @@ function parseAssTimestamp(raw: string): number | null {
   return hours * 3600 + minutes * 60 + seconds + centiseconds / 100;
 }
 
-export function parseAssCues(content: string): SubtitleCue[] {
-  const cues: SubtitleCue[] = [];
+function readField(fields: string[], index: number): string {
+  return index >= 0 && index < fields.length ? fields[index]!.trim() : '';
+}
+
+function findFieldIndex(formatFields: string[], aliases: string[]): number {
+  for (const alias of aliases) {
+    const index = formatFields.indexOf(alias);
+    if (index >= 0) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
+  const cues: AnnotatedSubtitleCue[] = [];
   const lines = content.split(/\r?\n/);
   let inEventsSection = false;
-  let startFieldIndex = -1;
-  let endFieldIndex = -1;
-  let textFieldIndex = -1;
+  const fieldIndex = {
+    start: -1,
+    end: -1,
+    text: -1,
+    style: -1,
+    layer: -1,
+    name: -1,
+    effect: -1,
+  };
+
+  const resetFieldIndex = () => {
+    fieldIndex.start = -1;
+    fieldIndex.end = -1;
+    fieldIndex.text = -1;
+    fieldIndex.style = -1;
+    fieldIndex.layer = -1;
+    fieldIndex.name = -1;
+    fieldIndex.effect = -1;
+  };
 
   for (const line of lines) {
     const trimmed = line.trim();
@@ -101,9 +196,7 @@ export function parseAssCues(content: string): SubtitleCue[] {
     if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
       inEventsSection = trimmed.toLowerCase() === '[events]';
       if (!inEventsSection) {
-        startFieldIndex = -1;
-        endFieldIndex = -1;
-        textFieldIndex = -1;
+        resetFieldIndex();
       }
       continue;
     }
@@ -117,9 +210,15 @@ export function parseAssCues(content: string): SubtitleCue[] {
         .slice(ASS_FORMAT_PREFIX.length)
         .split(',')
         .map((field) => field.trim().toLowerCase());
-      startFieldIndex = formatFields.indexOf('start');
-      endFieldIndex = formatFields.indexOf('end');
-      textFieldIndex = formatFields.indexOf('text');
+      fieldIndex.start = formatFields.indexOf('start');
+      fieldIndex.end = formatFields.indexOf('end');
+      fieldIndex.text = formatFields.indexOf('text');
+      fieldIndex.style = formatFields.indexOf('style');
+      fieldIndex.layer = formatFields.indexOf('layer');
+      // Aegisub writes the speaker column as `Actor`; the v4+ spec calls it `Name`.
+      // Missing it costs the burst check its speaker guard, so both spellings count.
+      fieldIndex.name = findFieldIndex(formatFields, ASS_NAME_FIELD_ALIASES);
+      fieldIndex.effect = formatFields.indexOf('effect');
       continue;
     }
 
@@ -127,34 +226,57 @@ export function parseAssCues(content: string): SubtitleCue[] {
       continue;
     }
 
-    if (startFieldIndex < 0 || endFieldIndex < 0 || textFieldIndex < 0) {
+    if (fieldIndex.start < 0 || fieldIndex.end < 0 || fieldIndex.text < 0) {
       continue;
     }
 
     const fields = trimmed.slice(ASS_DIALOGUE_PREFIX.length).split(',');
     if (
-      startFieldIndex >= fields.length ||
-      endFieldIndex >= fields.length ||
-      textFieldIndex >= fields.length
+      fieldIndex.start >= fields.length ||
+      fieldIndex.end >= fields.length ||
+      fieldIndex.text >= fields.length
     ) {
       continue;
     }
 
-    const startTime = parseAssTimestamp(fields[startFieldIndex]!);
-    const endTime = parseAssTimestamp(fields[endFieldIndex]!);
+    const startTime = parseAssTimestamp(fields[fieldIndex.start]!);
+    const endTime = parseAssTimestamp(fields[fieldIndex.end]!);
     if (startTime === null || endTime === null) {
       continue;
     }
 
-    const text = sanitizeSubtitleCueText(fields.slice(textFieldIndex).join(','));
-    if (text) {
-      cues.push({ startTime, endTime, text });
+    const rawText = fields.slice(fieldIndex.text).join(',');
+    const text = sanitizeSubtitleCueText(rawText);
+    if (!text) {
+      continue;
     }
+
+    const effect = readField(fields, fieldIndex.effect);
+    const layer = Number(readField(fields, fieldIndex.layer));
+    const overrides = collectAssOverrideCommands(rawText);
+    cues.push({
+      startTime,
+      endTime,
+      text,
+      rawText,
+      style: readField(fields, fieldIndex.style),
+      layer: Number.isFinite(layer) ? layer : 0,
+      name: readField(fields, fieldIndex.name),
+      effect,
+      effectKind: parseAssEffectField(effect),
+      overrides,
+      overrideSignature: assOverrideSignature(overrides),
+      order: cues.length,
+    });
   }
 
   return cues;
 }
 
+export function parseAssCues(content: string): SubtitleCue[] {
+  return toPublicCues(parseAnnotatedAssCues(content));
+}
+
 function detectSubtitleFormat(source: string): 'srt' | 'vtt' | 'ass' | 'ssa' | null {
   const [normalizedSource = source] =
     (() => {
@@ -173,27 +295,31 @@ function detectSubtitleFormat(source: string): 'srt' | 'vtt' | 'ass' | 'ssa' | n
 
 export function parseSubtitleCues(content: string, filename: string): SubtitleCue[] {
   const format = detectSubtitleFormat(filename);
-  let cues: SubtitleCue[];
+  let cues: AnnotatedSubtitleCue[];
+  let sourceFormat: SubtitleSourceFormat = 'srt';
 
   switch (format) {
     case 'srt':
     case 'vtt':
-      cues = parseSrtCues(content);
+      cues = parseAnnotatedSrtCues(content);
       break;
     case 'ass':
     case 'ssa':
-      cues = parseAssCues(content);
+      cues = parseAnnotatedAssCues(content);
+      sourceFormat = 'ass';
       break;
     default:
       cues = [];
   }
 
   if (cues.length === 0) {
-    const assCues = parseAssCues(content);
-    const srtCues = parseSrtCues(content);
-    cues = assCues.length >= srtCues.length ? assCues : srtCues;
+    const assCues = parseAnnotatedAssCues(content);
+    const srtCues = parseAnnotatedSrtCues(content);
+    const preferAss = assCues.length >= srtCues.length;
+    cues = preferAss ? assCues : srtCues;
+    sourceFormat = preferAss && assCues.length > 0 ? 'ass' : 'srt';
   }
 
-  cues.sort((a, b) => a.startTime - b.startTime);
-  return cues;
+  cues.sort((a, b) => a.startTime - b.startTime || a.endTime - b.endTime || a.order - b.order);
+  return toPublicCues(mergeDuplicateCues(cues, sourceFormat));
 }

src/core/services/subtitle-line-dedup-gate.test.ts

@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createSubtitleLineDedupGate } from './subtitle-line-dedup-gate';
+import type { SubtitleCue } from '../../types';
+
+function karaokeFrames(text: string, start: number, frames: number, frameSeconds: number) {
+  return Array.from({ length: frames }, (_, index) => ({
+    text,
+    startSec: start + index * frameSeconds,
+    endSec: start + (index + 1) * frameSeconds,
+  }));
+}
+
+test('parsed cues drop the frames the sidebar already collapsed', () => {
+  // What `mergeDuplicateCues` leaves behind for a karaoke run: one cue over the run.
+  const cues: SubtitleCue[] = [
+    { startTime: 10, endTime: 14, text: '飛び上がる' },
+    { startTime: 14, endTime: 16, text: 'もしも' },
+  ];
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => cues });
+
+  const recorded = karaokeFrames('飛び上がる', 10, 40, 0.1).filter((sample) =>
+    gate.shouldRecord(sample),
+  );
+
+  assert.equal(recorded.length, 1);
+  assert.equal(recorded[0]!.startSec, 10);
+  assert.equal(gate.shouldRecord({ text: 'もしも', startSec: 14, endSec: 16 }), true);
+});
+
+test('parsed cues keep separate lines that merely repeat', () => {
+  const cues: SubtitleCue[] = [
+    { startTime: 3, endTime: 3.4, text: 'えっ' },
+    { startTime: 3.4, endTime: 3.9, text: 'えっ' },
+    { startTime: 3.9, endTime: 4.5, text: 'えっ' },
+  ];
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => cues });
+
+  const recorded = cues.filter((cue) =>
+    gate.shouldRecord({ text: cue.text, startSec: cue.startTime, endSec: cue.endTime }),
+  );
+
+  assert.equal(recorded.length, 3);
+});
+
+test('parsed cues outrank the streaming heuristic for short repeated cues', () => {
+  // Long enough to trip the timing-only rule, but the parser saw these with full
+  // lookahead and kept them, so every one of them is a line the sidebar shows.
+  const cues: SubtitleCue[] = Array.from({ length: 8 }, (_, index) => ({
+    startTime: 3 + index * 0.08,
+    endTime: 3 + (index + 1) * 0.08,
+    text: 'えっ',
+  }));
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => cues });
+
+  const recorded = cues.filter((cue) =>
+    gate.shouldRecord({ text: cue.text, startSec: cue.startTime, endSec: cue.endTime }),
+  );
+
+  assert.equal(recorded.length, 8);
+});
+
+test('a line whose timing does not match any cue still records', () => {
+  // A shifted track, an embedded sub nobody parsed: no match, no drop.
+  const cues: SubtitleCue[] = [{ startTime: 10, endTime: 14, text: '飛び上がる' }];
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => cues });
+
+  assert.equal(gate.shouldRecord({ text: '飛び上がる', startSec: 42, endSec: 44 }), true);
+});
+
+test('without parsed cues a long run of identical short frames stops recording', () => {
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => null });
+
+  const recorded = karaokeFrames('ひとしずく', 0, 200, 0.04).filter((sample) =>
+    gate.shouldRecord(sample),
+  );
+
+  assert.equal(recorded.length, 4);
+});
+
+test('without parsed cues ordinary repeated dialogue keeps recording', () => {
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => null });
+
+  // Six contiguous `えっ`, each held for a normal beat rather than an animation frame.
+  const recorded = karaokeFrames('えっ', 0, 6, 0.6).filter((sample) => gate.shouldRecord(sample));
+
+  assert.equal(recorded.length, 6);
+});
+
+test('the same event offered twice does not advance the run', () => {
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => null });
+
+  // mpv fires the timing handler once for `sub-start` and once for `sub-end`.
+  for (let i = 0; i < 8; i += 1) {
+    assert.equal(gate.shouldRecord({ text: '待って', startSec: 5, endSec: 5.05 }), true);
+  }
+});
+
+test('a gap between frames starts a new run', () => {
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => null });
+
+  const first = karaokeFrames('もし', 0, 6, 0.04).filter((sample) => gate.shouldRecord(sample));
+  const second = karaokeFrames('もし', 30, 6, 0.04).filter((sample) => gate.shouldRecord(sample));
+
+  assert.equal(first.length, 4);
+  assert.equal(second.length, 4);
+});
+
+test('reset forgets the streaming run', () => {
+  const gate = createSubtitleLineDedupGate({ getParsedCues: () => null });
+
+  karaokeFrames('もし', 0, 20, 0.04).forEach((sample) => gate.shouldRecord(sample));
+  gate.reset();
+
+  assert.equal(gate.shouldRecord({ text: 'もし', startSec: 0.8, endSec: 0.84 }), true);
+});

src/core/services/subtitle-line-dedup-gate.ts

@@ -0,0 +1,188 @@
+/*
+ * Decides which live mpv subtitle lines reach the immersion stats.
+ *
+ * The sidebar reads a parsed subtitle file, so it can collapse an animation burst with
+ * full lookahead (`subtitle-cue-dedup`). Stats are fed from mpv's `sub-start`/`sub-end`
+ * properties instead -- one event per animation frame, each with its own start time --
+ * so without a gate a karaoke OP counts its lyrics once per frame and buries every real
+ * word in the vocabulary charts.
+ *
+ * Two layers, in order:
+ *
+ * 1. When the active source has been parsed, its cue list has *already* been collapsed.
+ *    A live line that lands inside a surviving cue of the same text, but after that
+ *    cue's start, is a frame the sidebar merged away, so stats drop it too. This is the
+ *    layer that keeps the two views consistent by construction.
+ * 2. Otherwise (embedded track nobody parsed, a source whose timings mpv has shifted)
+ *    fall back to timing alone. No authoring metadata is available live -- mpv delivers
+ *    `sub-text-ass` after `sub-start`/`sub-end`, so any ASS text read here belongs to the
+ *    previous event -- which puts this layer in the same position as the SRT path in
+ *    `subtitle-cue-dedup`, and it uses that path's deliberately strict bounds.
+ */
+
+import { normalizePlainSubtitleText } from './ass-text';
+import {
+  DUPLICATE_CUE_GAP_TOLERANCE_SECONDS,
+  MIN_TIMING_ONLY_FRAMES,
+  TIMING_ONLY_FRAME_MAX_SECONDS,
+} from './subtitle-burst-constants';
+import type { SubtitleCue } from './subtitle-cue-parser';
+
+export interface SubtitleLineSample {
+  text: string;
+  startSec: number;
+  endSec: number;
+}
+
+export interface SubtitleLineDedupGateDeps {
+  /** Cues for the active source, already collapsed by the parser. */
+  getParsedCues: () => readonly SubtitleCue[] | null | undefined;
+}
+
+export interface SubtitleLineDedupGate {
+  /** False when this line is an animation frame of a line already recorded. */
+  shouldRecord: (sample: SubtitleLineSample) => boolean;
+  /** Forget the streaming run state, e.g. when playback moves to another file. */
+  reset: () => void;
+}
+
+interface CueSpan {
+  startTime: number;
+  endTime: number;
+}
+
+interface StreamingRunState {
+  text: string;
+  startMs: number;
+  chainEndSec: number;
+  /** Contiguous identical short frames seen so far, including the recorded first one. */
+  frames: number;
+}
+
+function normalizeLineText(text: string): string {
+  return normalizePlainSubtitleText(text, { collapseLineBreaks: true });
+}
+
+function buildSpansByText(cues: readonly SubtitleCue[]): Map<string, CueSpan[]> {
+  const spansByText = new Map<string, CueSpan[]>();
+  for (const cue of cues) {
+    const key = normalizeLineText(cue.text);
+    if (!key) continue;
+    const span = { startTime: cue.startTime, endTime: cue.endTime };
+    const existing = spansByText.get(key);
+    if (existing) {
+      existing.push(span);
+    } else {
+      spansByText.set(key, [span]);
+    }
+  }
+  return spansByText;
+}
+
+/**
+ * A frame the parser merged away: the same text, starting inside a surviving cue but
+ * after it began.
+ *
+ * Starting a cue always wins over falling inside one. The first frame of a collapsed run
+ * starts *at* the merged cue, and a line the parser deliberately kept separate -- three
+ * characters trading `えっ` back to back -- begins exactly where the one before it ends.
+ */
+function isMergedAwayFrame(spans: readonly CueSpan[], startSec: number): boolean {
+  const startsOwnCue = spans.some(
+    (span) => Math.abs(startSec - span.startTime) <= DUPLICATE_CUE_GAP_TOLERANCE_SECONDS,
+  );
+  if (startsOwnCue) {
+    return false;
+  }
+  return spans.some(
+    (span) =>
+      startSec > span.startTime + DUPLICATE_CUE_GAP_TOLERANCE_SECONDS &&
+      startSec <= span.endTime + DUPLICATE_CUE_GAP_TOLERANCE_SECONDS,
+  );
+}
+
+export function createSubtitleLineDedupGate(
+  deps: SubtitleLineDedupGateDeps,
+): SubtitleLineDedupGate {
+  let indexedCues: readonly SubtitleCue[] | null = null;
+  let spansByText: Map<string, CueSpan[]> = new Map();
+  let run: StreamingRunState | null = null;
+
+  const lookupSpans = (text: string): CueSpan[] | null => {
+    const cues = deps.getParsedCues();
+    if (!cues?.length) {
+      indexedCues = null;
+      spansByText = new Map();
+      return null;
+    }
+    if (cues !== indexedCues) {
+      indexedCues = cues;
+      spansByText = buildSpansByText(cues);
+    }
+    return spansByText.get(text) ?? null;
+  };
+
+  /**
+   * Timing-only burst detection over a stream. Without lookahead the run can only be
+   * recognised from the inside, so the first frames of a burst are recorded and the rest
+   * dropped -- an OP costs a handful of counted lines instead of several hundred.
+   */
+  const advanceStreamingRun = (text: string, sample: SubtitleLineSample): boolean => {
+    const startMs = Math.round(sample.startSec * 1000);
+    // mpv reports `sub-start` and `sub-end` separately, so one event can be offered
+    // twice. The same start is the same frame, never the next one in a run.
+    if (run && run.text === text && run.startMs === startMs) {
+      run.chainEndSec = Math.max(run.chainEndSec, sample.endSec);
+      return run.frames < MIN_TIMING_ONLY_FRAMES;
+    }
+
+    const isShortFrame = sample.endSec - sample.startSec < TIMING_ONLY_FRAME_MAX_SECONDS;
+    // Frames are authored flush against each other, but typesetters do overlap them, so
+    // the chain only requires forward progress that stays inside the running end.
+    const continuesRun =
+      run !== null &&
+      run.text === text &&
+      isShortFrame &&
+      startMs > run.startMs &&
+      sample.startSec <= run.chainEndSec + DUPLICATE_CUE_GAP_TOLERANCE_SECONDS;
+
+    if (continuesRun && run) {
+      run.startMs = startMs;
+      run.chainEndSec = Math.max(run.chainEndSec, sample.endSec);
+      run.frames += 1;
+    } else {
+      run = {
+        text,
+        startMs,
+        chainEndSec: sample.endSec,
+        frames: isShortFrame ? 1 : 0,
+      };
+    }
+
+    return run.frames < MIN_TIMING_ONLY_FRAMES;
+  };
+
+  return {
+    shouldRecord: (sample) => {
+      const text = normalizeLineText(sample.text);
+      if (!text) {
+        return true;
+      }
+
+      // The parsed cue list has the final say wherever it covers this line. Falling
+      // through to the streaming heuristic would let it drop cues the parser looked at
+      // with full lookahead and deliberately kept apart, which is the disagreement
+      // between sidebar and stats this gate exists to prevent.
+      const spans = lookupSpans(text);
+      if (spans) {
+        run = null;
+        return !isMergedAwayFrame(spans, sample.startSec);
+      }
+
+      return advanceStreamingRun(text, sample);
+    },
+    reset: () => {
+      run = null;
+    },
+  };
+}

src/core/services/subtitle-prefetch.test.ts

@@ -74,7 +74,6 @@ test('prefetch service tokenizes priority window cues and caches them', async ()
     preCacheTokenization: (text, data) => {
       cached.set(text, data);
     },
-    isCacheFull: () => false,
     priorityWindowSize: 3,
   });
 
@@ -91,32 +90,38 @@ test('prefetch service tokenizes priority window cues and caches them', async ()
   assert.ok(cached.has('line-2'));
 });
 
-test('prefetch service stops when cache is full', async () => {
+test('prefetch service warms every cue even when the cache evicts along the way', async () => {
   const cues = makeCues(20);
-  let tokenizeCalls = 0;
-  let cacheSize = 0;
+  const tokenized: string[] = [];
+  // Stand-in for the LRU: only the last 5 entries survive, so later cues evict earlier ones.
+  const cache = new Set<string>();
 
   const service = createSubtitlePrefetchService({
     cues,
     tokenizeSubtitle: async (text) => {
-      tokenizeCalls += 1;
+      tokenized.push(text);
       return { text, tokens: [] };
     },
-    preCacheTokenization: () => {
-      cacheSize += 1;
+    preCacheTokenization: (text) => {
+      cache.add(text);
+      while (cache.size > 5) {
+        const oldest = cache.values().next().value;
+        if (oldest === undefined) break;
+        cache.delete(oldest);
+      }
     },
-    isCacheFull: () => cacheSize >= 5,
+    hasCachedTokenization: (text) => cache.has(text),
     priorityWindowSize: 3,
   });
 
   service.start(0);
-  for (let i = 0; i < 30; i += 1) {
+  for (let i = 0; i < 60; i += 1) {
     await flushMicrotasks();
   }
   service.stop();
 
-  // Should have stopped at 5 (cache full), not tokenized all 20
-  assert.ok(tokenizeCalls <= 6, `Expected <= 6 tokenize calls, got ${tokenizeCalls}`);
+  assert.equal(tokenized.length, 20, `Expected all 20 cues warmed, got ${tokenized.length}`);
+  assert.equal(new Set(tokenized).size, 20, 'Each cue is tokenized at most once per run');
 });
 
 test('prefetch service can be stopped mid-flight', async () => {
@@ -130,7 +135,6 @@ test('prefetch service can be stopped mid-flight', async () => {
       return { text, tokens: [] };
     },
     preCacheTokenization: () => {},
-    isCacheFull: () => false,
     priorityWindowSize: 3,
   });
 
@@ -159,7 +163,6 @@ test('prefetch service onSeek re-prioritizes from new position', async () => {
     preCacheTokenization: (text) => {
       cachedTexts.push(text);
     },
-    isCacheFull: () => false,
     priorityWindowSize: 3,
   });
 
@@ -183,7 +186,7 @@ test('prefetch service onSeek re-prioritizes from new position', async () => {
   assert.ok(hasPostSeekCue, 'Should have cached cues after seek position');
 });
 
-test('prefetch service still warms the priority window when cache is full', async () => {
+test('prefetch service warms the priority window ahead of the rest of the file', async () => {
   const cues = makeCues(20);
   const cachedTexts: string[] = [];
 
@@ -193,7 +196,6 @@ test('prefetch service still warms the priority window when cache is full', asyn
     preCacheTokenization: (text) => {
       cachedTexts.push(text);
     },
-    isCacheFull: () => true,
     priorityWindowSize: 3,
   });
 
@@ -217,7 +219,6 @@ test('prefetch service pause/resume halts and continues tokenization', async ()
       return { text, tokens: [] };
     },
     preCacheTokenization: () => {},
-    isCacheFull: () => false,
     priorityWindowSize: 3,
   });
 
@@ -255,7 +256,6 @@ test('prefetch service skips cues already present in tokenization cache', async
     },
     preCacheTokenization: () => {},
     hasCachedTokenization: (text) => text === 'line-0' || text === 'line-1',
-    isCacheFull: () => false,
     priorityWindowSize: 3,
   });
 
@@ -285,7 +285,6 @@ test('prefetch service deduplicates repeated cue text within a run', async () =>
       return { text, tokens: [] };
     },
     preCacheTokenization: () => {},
-    isCacheFull: () => false,
     priorityWindowSize: 3,
   });
 

src/core/services/subtitle-prefetch.ts

@@ -7,7 +7,6 @@ export interface SubtitlePrefetchServiceDeps {
   tokenizeSubtitle: (text: string) => Promise<SubtitleData | null>;
   preCacheTokenization: (text: string, data: SubtitleData) => void;
   hasCachedTokenization?: (text: string) => boolean;
-  isCacheFull: () => boolean;
   priorityWindowSize?: number;
 }
 
@@ -57,11 +56,14 @@ export function createSubtitlePrefetchService(
   let paused = false;
   let currentRunId = 0;
 
+  // A run is a single bounded pass over one file's cues, deduped by `warmedKeys` and by
+  // `hasCachedTokenization`, so the worst case is one tokenization per cue. The cache is
+  // an LRU and bounds its own memory, so a full cache is not a reason to stop warming;
+  // stopping there used to leave the tail of longer media permanently uncached.
   async function tokenizeCueList(
     cuesToProcess: SubtitleCue[],
     runId: number,
     warmedKeys: Set<string>,
-    options: { allowWhenCacheFull?: boolean } = {},
   ): Promise<void> {
     for (const cue of cuesToProcess) {
       if (stopped || runId !== currentRunId) {
@@ -77,10 +79,6 @@ export function createSubtitlePrefetchService(
         return;
       }
 
-      if (!options.allowWhenCacheFull && deps.isCacheFull()) {
-        return;
-      }
-
       const cacheKey = normalizeSubtitleCacheKey(cue.text);
       if (!cacheKey || warmedKeys.has(cacheKey) || deps.hasCachedTokenization?.(cue.text)) {
         if (cacheKey) {
@@ -110,7 +108,7 @@ export function createSubtitlePrefetchService(
 
     // Phase 1: Priority window
     const priorityCues = computePriorityWindow(cues, currentTimeSeconds, windowSize);
-    await tokenizeCueList(priorityCues, runId, warmedKeys, { allowWhenCacheFull: true });
+    await tokenizeCueList(priorityCues, runId, warmedKeys);
 
     if (stopped || runId !== currentRunId) {
       return;

src/core/services/subtitle-processing-controller-race.test.ts

@@ -0,0 +1,159 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { SubtitleData } from '../../types';
+import { createSubtitleProcessingController } from './subtitle-processing-controller';
+
+function flushMicrotasks(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+test('new subtitle emits plain immediately without parallel tokenization or a stale overwrite', async () => {
+  const emitted: SubtitleData[] = [];
+  const resolvers = new Map<string, (value: SubtitleData | null) => void>();
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolvers.set(text, resolve);
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('first');
+  controller.onSubtitleChange('second');
+
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+  ]);
+  assert.equal(resolvers.has('second'), false);
+
+  const resolveFirst = resolvers.get('first');
+  assert.ok(resolveFirst);
+  resolveFirst({ text: 'first', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+  ]);
+  assert.equal(resolvers.has('second'), true);
+
+  const resolveSecond = resolvers.get('second');
+  assert.ok(resolveSecond);
+  resolveSecond({ text: 'second', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+    { text: 'second', tokens: [] },
+  ]);
+});
+
+test('subtitle clears immediately while previous tokenization remains pending', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolveTokenization: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async () =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolveTokenization = resolve;
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('first');
+  controller.onSubtitleChange('');
+
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: '', tokens: null },
+  ]);
+
+  assert.ok(resolveTokenization);
+  resolveTokenization({ text: 'first', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: '', tokens: null },
+  ]);
+});
+
+test('returning to an uncached completed line emits it while another line is pending', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolvePending: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      if (text === 'A') {
+        return { text, tokens: [] };
+      }
+      return await new Promise<SubtitleData | null>((resolve) => {
+        resolvePending = resolve;
+      });
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('A');
+  await flushMicrotasks();
+  controller.invalidateTokenizationCache();
+  controller.onSubtitleChange('B');
+  controller.onSubtitleChange('A');
+
+  assert.deepEqual(emitted.at(-1), { text: 'A', tokens: null });
+  assert.ok(resolvePending);
+  resolvePending({ text: 'B', tokens: [] });
+});
+
+test('ABA subtitle changes reuse the matching first tokenization only after A is current again', async () => {
+  const emitted: SubtitleData[] = [];
+  const tokenizeCalls: string[] = [];
+  const resolvers: Array<(value: SubtitleData | null) => void> = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      tokenizeCalls.push(text);
+      return await new Promise<SubtitleData | null>((resolve) => {
+        resolvers.push(resolve);
+      });
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('A');
+  controller.onSubtitleChange('B');
+  controller.onSubtitleChange('A');
+  const resolveFirst = resolvers[0];
+  assert.ok(resolveFirst);
+  resolveFirst({ text: 'A', tokens: [{ value: 1 } as never] });
+  await flushMicrotasks();
+
+  assert.deepEqual(tokenizeCalls, ['A']);
+  assert.deepEqual(emitted, [
+    { text: 'A', tokens: null },
+    { text: 'B', tokens: null },
+    { text: 'A', tokens: null },
+    { text: 'A', tokens: [{ value: 1 } as never] },
+  ]);
+});
+
+test('cached next subtitle does not downgrade to plain while processing is busy', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolveTokenization: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolveTokenization = () => resolve({ text, tokens: [] });
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.preCacheTokenization('cached', { text: 'cached', tokens: [] });
+  controller.onSubtitleChange('pending');
+  controller.onSubtitleChange('cached');
+
+  assert.deepEqual(emitted, [{ text: 'pending', tokens: null }]);
+  assert.ok(resolveTokenization);
+  resolveTokenization({ text: 'pending', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'pending', tokens: null },
+    { text: 'cached', tokens: [] },
+  ]);
+});

src/core/services/subtitle-processing-controller.test.ts

@@ -7,18 +7,153 @@ function flushMicrotasks(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
 
-test('subtitle processing emits tokenized payload when tokenization succeeds', async () => {
+test('subtitle processing emits plain payload immediately on cache miss, then tokenized payload', async () => {
   const emitted: SubtitleData[] = [];
   const controller = createSubtitleProcessingController({
     tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
     emitSubtitle: (payload) => emitted.push(payload),
   });
 
+  controller.onSubtitleChange('字幕');
+  assert.deepEqual(emitted, [{ text: '字幕', tokens: null }]);
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: '字幕', tokens: null },
+    { text: '字幕', tokens: [] },
+  ]);
+});
+
+test('cache invalidation during pending tokenization does not re-emit the plain payload', async () => {
+  const emitted: SubtitleData[] = [];
+  const resolvers: Array<(value: SubtitleData | null) => void> = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolvers.push(() => resolve({ text, tokens: [{ value: resolvers.length } as never] }));
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('行');
+  assert.deepEqual(emitted, [{ text: '行', tokens: null }]);
+
+  controller.invalidateTokenizationCache();
+  resolvers[0]?.({ text: '行', tokens: [] });
+  await flushMicrotasks();
+  // Retry for the new generation is now pending; still no duplicate plain emit.
+  assert.deepEqual(emitted, [{ text: '行', tokens: null }]);
+
+  resolvers[1]?.({ text: '行', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: '行', tokens: null },
+    { text: '行', tokens: [{ value: 2 } as never] },
+  ]);
+});
+
+test('failed refresh does not downgrade an already emitted tokenized subtitle', async () => {
+  const emitted: SubtitleData[] = [];
+  let tokenizeCalls = 0;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      tokenizeCalls += 1;
+      if (tokenizeCalls > 1) {
+        throw new Error('tokenizer gone');
+      }
+      return { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('行');
+  await flushMicrotasks();
+  controller.invalidateTokenizationCache();
+  controller.refreshCurrentSubtitle();
+  await flushMicrotasks();
+
+  assert.equal(tokenizeCalls, 2);
+  assert.deepEqual(emitted, [
+    { text: '行', tokens: null },
+    { text: '行', tokens: [] },
+  ]);
+});
+
+test('null-tokenization refresh does not downgrade an already emitted tokenized subtitle', async () => {
+  const emitted: SubtitleData[] = [];
+  let tokenizeCalls = 0;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      tokenizeCalls += 1;
+      return tokenizeCalls > 1 ? null : { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('行');
+  await flushMicrotasks();
+  controller.invalidateTokenizationCache();
+  controller.refreshCurrentSubtitle();
+  await flushMicrotasks();
+
+  assert.equal(tokenizeCalls, 2);
+  assert.deepEqual(emitted, [
+    { text: '行', tokens: null },
+    { text: '行', tokens: [] },
+  ]);
+});
+
+test('subtitle processing does not emit plain payload for cached lines', async () => {
+  const emitted: SubtitleData[] = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.preCacheTokenization('字幕', { text: '字幕', tokens: [] });
   controller.onSubtitleChange('字幕');
   await flushMicrotasks();
   assert.deepEqual(emitted, [{ text: '字幕', tokens: [] }]);
 });
 
+test('text that normalizes to nothing is never cached', () => {
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: () => {},
+  });
+
+  // Two different inputs both reduce to an empty key; sharing one entry would serve the
+  // first one's tokens for the second.
+  controller.preCacheTokenization('  ', { text: '  ', tokens: [] });
+
+  assert.equal(controller.hasCachedSubtitle('  '), false);
+  assert.equal(controller.hasCachedSubtitle('\\n'), false);
+  assert.equal(controller.consumeCachedSubtitle('\\n'), null);
+});
+
+test('subtitle processing shows plain line while tokenization is still pending', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolveTokenization: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolveTokenization = () => resolve({ text, tokens: [] });
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('遅い行');
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [{ text: '遅い行', tokens: null }]);
+
+  assert.ok(resolveTokenization);
+  resolveTokenization({ text: '遅い行', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: '遅い行', tokens: null },
+    { text: '遅い行', tokens: [] },
+  ]);
+});
+
 test('subtitle processing drops stale tokenization and delivers latest subtitle only once', async () => {
   const emitted: SubtitleData[] = [];
   let firstResolve: ((value: SubtitleData | null) => void) | undefined;
@@ -41,7 +176,11 @@ test('subtitle processing drops stale tokenization and delivers latest subtitle
   await flushMicrotasks();
   await flushMicrotasks();
 
-  assert.deepEqual(emitted, [{ text: 'second', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+    { text: 'second', tokens: [] },
+  ]);
 });
 
 test('subtitle processing skips duplicate subtitle emission', async () => {
@@ -60,7 +199,10 @@ test('subtitle processing skips duplicate subtitle emission', async () => {
   controller.onSubtitleChange('same');
   await flushMicrotasks();
 
-  assert.equal(emitted.length, 1);
+  assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
+    { text: 'same', tokens: [] },
+  ]);
   assert.equal(tokenizeCalls, 1);
 });
 
@@ -84,7 +226,9 @@ test('subtitle processing reuses cached tokenization for repeated subtitle text'
 
   assert.equal(tokenizeCalls, 2);
   assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
     { text: 'first', tokens: [] },
+    { text: 'second', tokens: null },
     { text: 'second', tokens: [] },
     { text: 'first', tokens: [] },
   ]);
@@ -100,7 +244,48 @@ test('subtitle processing falls back to plain subtitle when tokenization returns
   controller.onSubtitleChange('fallback');
   await flushMicrotasks();
 
+  assert.deepEqual(
+    emitted,
+    [{ text: 'fallback', tokens: null }],
+    'plain payload should not be re-emitted when tokenization yields nothing new',
+  );
+});
+
+test('null tokenization is not cached and a later cue retries tokenization', async () => {
+  const emitted: SubtitleData[] = [];
+  const callsByText = new Map<string, number>();
+  let failNext = true;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      callsByText.set(text, (callsByText.get(text) ?? 0) + 1);
+      if (text === 'fallback' && failNext) {
+        failNext = false;
+        return null;
+      }
+      return { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('fallback');
+  await flushMicrotasks();
+
+  assert.equal(callsByText.get('fallback'), 1);
+  assert.equal(
+    controller.hasCachedSubtitle('fallback'),
+    false,
+    'plain fallback must not be cached when tokenization yields nothing',
+  );
   assert.deepEqual(emitted, [{ text: 'fallback', tokens: null }]);
+
+  controller.onSubtitleChange('other');
+  await flushMicrotasks();
+  controller.onSubtitleChange('fallback');
+  await flushMicrotasks();
+
+  assert.equal(callsByText.get('fallback'), 2, 'later cue should retry tokenization');
+  assert.equal(controller.hasCachedSubtitle('fallback'), true);
+  assert.deepEqual(emitted.at(-1), { text: 'fallback', tokens: [] });
 });
 
 test('subtitle processing ignores duplicate current subtitle refresh without cache invalidation', async () => {
@@ -120,7 +305,10 @@ test('subtitle processing ignores duplicate current subtitle refresh without cac
   await flushMicrotasks();
 
   assert.equal(tokenizeCalls, 1);
-  assert.deepEqual(emitted, [{ text: 'same', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
+    { text: 'same', tokens: [] },
+  ]);
 });
 
 test('subtitle processing coalesces refresh requests while current subtitle is processing', async () => {
@@ -146,7 +334,10 @@ test('subtitle processing coalesces refresh requests while current subtitle is p
   await flushMicrotasks();
 
   assert.equal(tokenizeCalls, 1);
-  assert.deepEqual(emitted, [{ text: 'same', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
+    { text: 'same', tokens: [] },
+  ]);
 });
 
 test('subtitle processing refresh re-tokenizes after cache invalidation', async () => {
@@ -168,6 +359,7 @@ test('subtitle processing refresh re-tokenizes after cache invalidation', async
 
   assert.equal(tokenizeCalls, 2);
   assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
     { text: 'same', tokens: [{ value: 1 } as never] },
     { text: 'same', tokens: [{ value: 2 } as never] },
   ]);
@@ -183,7 +375,10 @@ test('subtitle processing refresh can use explicit text override', async () => {
   controller.refreshCurrentSubtitle('initial');
   await flushMicrotasks();
 
-  assert.deepEqual(emitted, [{ text: 'initial', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'initial', tokens: null },
+    { text: 'initial', tokens: [] },
+  ]);
 });
 
 test('subtitle processing cache invalidation only affects future subtitle events', async () => {
@@ -205,10 +400,10 @@ test('subtitle processing cache invalidation only affects future subtitle events
   await flushMicrotasks();
 
   assert.equal(callsByText.get('same'), 1);
-  assert.equal(emitted.length, 3);
+  assert.equal(emitted.length, 5);
 
   controller.invalidateTokenizationCache();
-  assert.equal(emitted.length, 3);
+  assert.equal(emitted.length, 5);
 
   controller.onSubtitleChange('different');
   await flushMicrotasks();
@@ -308,25 +503,176 @@ test('hasCachedSubtitle checks prefetched entries without consuming them', async
   assert.equal(controller.hasCachedSubtitle('猫\nです'), false);
 });
 
-test('isCacheFull returns false when cache is below limit', () => {
+test('cache keeps every entry while below the limit', () => {
   const controller = createSubtitleProcessingController({
-    tokenizeSubtitle: async (text) => ({ text, tokens: null }),
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
     emitSubtitle: () => {},
+    cacheLimit: 8,
   });
 
-  assert.equal(controller.isCacheFull(), false);
+  for (let i = 0; i < 8; i += 1) {
+    controller.preCacheTokenization(`line-${i}`, { text: `line-${i}`, tokens: [] });
+  }
+
+  assert.deepEqual(
+    Array.from({ length: 8 }, (_, i) => controller.hasCachedSubtitle(`line-${i}`)),
+    Array.from({ length: 8 }, () => true),
+  );
 });
 
-test('isCacheFull returns true when cache reaches limit', async () => {
+test('cache evicts least recently used entries once the limit is reached', () => {
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: () => {},
+    cacheLimit: 3,
+  });
+
+  for (const line of ['a', 'b', 'c']) {
+    controller.preCacheTokenization(line, { text: line, tokens: [] });
+  }
+  // Touching 'a' makes 'b' the eviction candidate.
+  controller.consumeCachedSubtitle('a');
+  controller.preCacheTokenization('d', { text: 'd', tokens: [] });
+
+  assert.equal(controller.hasCachedSubtitle('b'), false);
+  assert.deepEqual(
+    ['a', 'c', 'd'].map((line) => controller.hasCachedSubtitle(line)),
+    [true, true, true],
+  );
+});
+
+test('default cache limit covers a full-length title without evicting', () => {
   const controller = createSubtitleProcessingController({
     tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
     emitSubtitle: () => {},
   });
 
-  // Fill cache to the 256 limit
-  for (let i = 0; i < 256; i += 1) {
+  for (let i = 0; i < 2000; i += 1) {
     controller.preCacheTokenization(`line-${i}`, { text: `line-${i}`, tokens: [] });
   }
 
-  assert.equal(controller.isCacheFull(), true);
+  assert.equal(controller.hasCachedSubtitle('line-0'), true);
+  assert.equal(controller.hasCachedSubtitle('line-1999'), true);
+});
+
+test('onSubtitleChange reports whether processing was scheduled', async () => {
+  const emitted: SubtitleData[] = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  // New text schedules work, so an emit (and anything gated on it) will follow.
+  assert.equal(controller.onSubtitleChange('字幕'), true);
+  await flushMicrotasks();
+
+  // A repeat emits nothing, so callers must not wait on an emit that is never
+  // coming (subtitle prefetching would stay paused for the rest of the cue).
+  const emittedCount = emitted.length;
+  assert.equal(controller.onSubtitleChange('字幕'), false);
+  await flushMicrotasks();
+  assert.equal(emitted.length, emittedCount);
+});
+
+test('refreshCurrentSubtitle reports the empty-text emit that an in-flight run will deliver', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolveFirst: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      if (text === '字幕') {
+        return await new Promise<SubtitleData | null>((resolve) => {
+          resolveFirst = resolve;
+        });
+      }
+      return { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('字幕');
+  await flushMicrotasks();
+
+  // Clearing the subtitle while tokenization is in flight: the running loop
+  // picks the empty text up and emits it, so callers gated on that emit (the
+  // prefetch pause) must be told one is coming.
+  assert.equal(controller.refreshCurrentSubtitle(''), true);
+
+  resolveFirst?.({ text: '字幕', tokens: [] });
+  await flushMicrotasks();
+  await flushMicrotasks();
+  // '字幕' is the provisional plain emit the in-flight run already made before
+  // the refresh; '' is the emit the refresh promised.
+  assert.deepEqual(
+    emitted.map((payload) => payload.text),
+    ['字幕', ''],
+  );
+});
+
+test('onProcessingSettled fires once after the queue drains, including runs that emit nothing', async () => {
+  const events: string[] = [];
+  let resolveFirst: ((value: SubtitleData | null) => void) | undefined;
+  let tokenizationFails = false;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      if (tokenizationFails) {
+        return null;
+      }
+      if (text === '一行目') {
+        return await new Promise<SubtitleData | null>((resolve) => {
+          resolveFirst = resolve;
+        });
+      }
+      return { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => events.push(`emit:${payload.text}`),
+    onProcessingSettled: () => events.push('settled'),
+  });
+
+  controller.onSubtitleChange('一行目');
+  await flushMicrotasks();
+  // A second line arrives before the first finishes: the controller still has
+  // work, so it must not report itself settled between the two.
+  controller.onSubtitleChange('二行目');
+  resolveFirst?.({ text: '一行目', tokens: [] });
+  await flushMicrotasks();
+  await flushMicrotasks();
+
+  assert.deepEqual(events, ['emit:一行目', 'emit:二行目', 'emit:二行目', 'settled']);
+
+  // Tokenization failure on a line already shown plain: nothing is emitted, and
+  // the settle signal is the only way a caller learns the work is over.
+  events.length = 0;
+  tokenizationFails = true;
+  controller.invalidateTokenizationCache();
+  assert.equal(controller.refreshCurrentSubtitle('二行目'), true);
+  await flushMicrotasks();
+  await flushMicrotasks();
+  assert.deepEqual(events, ['settled']);
+});
+
+test('notePlainSubtitleEmitted suppresses the controller repeat of a payload already shown', async () => {
+  const emitted: SubtitleData[] = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  // Autoplay priming paints the plain line itself, then asks for tokenization.
+  controller.notePlainSubtitleEmitted('字幕');
+  controller.refreshCurrentSubtitle('字幕');
+  await flushMicrotasks();
+
+  assert.deepEqual(emitted, [{ text: '字幕', tokens: [] }]);
+});
+
+test('refreshCurrentSubtitle reports no emit for empty text when nothing is running', async () => {
+  const emitted: SubtitleData[] = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  assert.equal(controller.refreshCurrentSubtitle(''), false);
+  await flushMicrotasks();
+  assert.deepEqual(emitted, []);
 });

src/core/services/subtitle-processing-controller.ts

@@ -1,32 +1,76 @@
 import type { SubtitleData } from '../../types';
+import { normalizePlainSubtitleText } from './ass-text';
 
 export interface SubtitleProcessingControllerDeps {
   tokenizeSubtitle: (text: string) => Promise<SubtitleData | null>;
   emitSubtitle: (payload: SubtitleData) => void;
+  /**
+   * Fires when the controller runs out of work: every scheduled line has been
+   * processed, whether it ended in an emit, a suppressed duplicate, or a
+   * tokenizer failure. Callers that hold a resource for the duration of
+   * processing (prefetch pausing) release it here rather than on an emit,
+   * which is not guaranteed to happen.
+   */
+  onProcessingSettled?: () => void;
   logDebug?: (message: string) => void;
   now?: () => number;
+  cacheLimit?: number;
 }
 
+/**
+ * Pure memory bound on the LRU, not a coverage limit: prefetching runs to the end of a
+ * file regardless of cache pressure. Sized to hold a feature-length title (a 24-minute
+ * episode runs 300-400 lines, a 2-hour film ~2000) plus room for lines that repeat across
+ * episodes of a series, so openings and endings stay warm between titles.
+ */
+export const DEFAULT_SUBTITLE_TOKENIZATION_CACHE_LIMIT = 2500;
+
 export interface SubtitleProcessingController {
-  onSubtitleChange: (text: string) => void;
-  refreshCurrentSubtitle: (textOverride?: string) => void;
+  /**
+   * Returns whether processing is now scheduled or already in flight for this
+   * event. A false return means the controller is idle and will do nothing, so
+   * onProcessingSettled will not fire; callers that pause work for the duration
+   * of processing (such as subtitle prefetching) must release it themselves.
+   */
+  onSubtitleChange: (text: string) => boolean;
+  /** Same contract as onSubtitleChange: whether processing is pending. */
+  refreshCurrentSubtitle: (textOverride?: string) => boolean;
+  /**
+   * Records that this exact text has already been shown plain by someone else
+   * (autoplay priming paints its first frame before scheduling tokenization),
+   * so the controller does not repeat that payload on its way to the tokenized
+   * one.
+   */
+  notePlainSubtitleEmitted: (text: string) => void;
   invalidateTokenizationCache: () => void;
   preCacheTokenization: (text: string, data: SubtitleData) => void;
   consumeCachedSubtitle: (text: string) => SubtitleData | null;
   hasCachedSubtitle: (text: string) => boolean;
-  isCacheFull: () => boolean;
 }
 
+/**
+ * Prefetched cues and live mpv text are both already decoded from ASS, so the key only
+ * has to settle whitespace for one authored line to resolve to one entry.
+ *
+ * An empty key is not a line: it is whatever normalization reduced to nothing. Callers
+ * must skip the cache for it rather than let every such input share one entry.
+ */
 export function normalizeSubtitleCacheKey(text: string): string {
-  return text.replace(/\r\n/g, '\n').replace(/\\N/g, '\n').replace(/\\n/g, '\n').trim();
+  return normalizePlainSubtitleText(text);
 }
 
 export function createSubtitleProcessingController(
   deps: SubtitleProcessingControllerDeps,
 ): SubtitleProcessingController {
-  const SUBTITLE_TOKENIZATION_CACHE_LIMIT = 256;
+  const SUBTITLE_TOKENIZATION_CACHE_LIMIT =
+    deps.cacheLimit && deps.cacheLimit > 0
+      ? deps.cacheLimit
+      : DEFAULT_SUBTITLE_TOKENIZATION_CACHE_LIMIT;
   let latestText = '';
   let lastEmittedText = '';
+  // Tracks the latest provisional plain emit across rapid changes and loop retries
+  // so the same line is never shown plain twice.
+  let lastPlainEmittedText: string | null = null;
   let cacheGeneration = 0;
   let lastEmittedGeneration = 0;
   let processing = false;
@@ -36,6 +80,9 @@ export function createSubtitleProcessingController(
 
   const getCachedTokenization = (text: string): SubtitleData | null => {
     const cacheKey = normalizeSubtitleCacheKey(text);
+    if (!cacheKey) {
+      return null;
+    }
     const cached = tokenizationCache.get(cacheKey);
     if (!cached) {
       return null;
@@ -47,7 +94,11 @@ export function createSubtitleProcessingController(
   };
 
   const setCachedTokenization = (text: string, payload: SubtitleData): void => {
-    tokenizationCache.set(normalizeSubtitleCacheKey(text), payload);
+    const cacheKey = normalizeSubtitleCacheKey(text);
+    if (!cacheKey) {
+      return;
+    }
+    tokenizationCache.set(cacheKey, payload);
     while (tokenizationCache.size > SUBTITLE_TOKENIZATION_CACHE_LIMIT) {
       const firstKey = tokenizationCache.keys().next().value;
       if (firstKey !== undefined) {
@@ -70,9 +121,12 @@ export function createSubtitleProcessingController(
         const startedAtMs = now();
 
         if (!text.trim()) {
-          deps.emitSubtitle({ text, tokens: null });
+          if (lastPlainEmittedText !== text) {
+            deps.emitSubtitle({ text, tokens: null });
+          }
           lastEmittedText = text;
           lastEmittedGeneration = generation;
+          lastPlainEmittedText = null;
           break;
         }
 
@@ -82,11 +136,25 @@ export function createSubtitleProcessingController(
           if (cachedTokenized) {
             output = cachedTokenized;
           } else {
+            // Cache miss: show the plain line on time; the tokenized payload
+            // upgrades it once ready. Skipped on refreshes of an already
+            // emitted line so downstream consumers never see a downgrade.
+            if (text !== lastEmittedText && text !== lastPlainEmittedText) {
+              deps.emitSubtitle({ text, tokens: null });
+              lastPlainEmittedText = text;
+            }
             const tokenized = await deps.tokenizeSubtitle(text);
+            // A null result is a transient tokenizer failure, not a verdict on
+            // the line: caching the plain fallback would pin it untokenized for
+            // every later occurrence.
             if (tokenized) {
               output = tokenized;
+              // A result computed before an invalidation must not repopulate the
+              // fresh cache, or the retry below would serve the stale entry.
+              if (generation === cacheGeneration) {
+                setCachedTokenization(text, tokenized);
+              }
             }
-            setCachedTokenization(text, output);
           }
         } catch (error) {
           deps.logDebug?.(`Subtitle tokenization failed: ${(error as Error).message}`);
@@ -107,9 +175,16 @@ export function createSubtitleProcessingController(
           continue;
         }
 
-        deps.emitSubtitle(output);
+        // An untokenized result adds nothing when this line was already shown,
+        // either provisionally or as an earlier full emit (failed refresh) —
+        // emitting it would duplicate or downgrade what is on screen.
+        const plainAlreadyShown = lastPlainEmittedText === text || lastEmittedText === text;
+        if (!(output.tokens === null && output.text === text && plainAlreadyShown)) {
+          deps.emitSubtitle(output);
+        }
         lastEmittedText = text;
         lastEmittedGeneration = generation;
+        lastPlainEmittedText = null;
         deps.logDebug?.(
           `Subtitle tokenization delivered; elapsed=${now() - startedAtMs}ms, staleDrops=${staleDropCount}`,
         );
@@ -126,32 +201,53 @@ export function createSubtitleProcessingController(
           (latestText.trim() && cacheGeneration !== lastEmittedGeneration)
         ) {
           processLatest();
+          return;
         }
+        // Nothing left to do: signal completion even when this run emitted
+        // nothing (suppressed duplicate, tokenizer failure), or callers waiting
+        // on the controller would wait forever.
+        deps.onProcessingSettled?.();
       });
   };
 
   return {
     onSubtitleChange: (text: string) => {
       if (text === latestText) {
-        return;
+        // A run already in flight for this text will still emit for it.
+        return processing;
       }
       latestText = text;
+      if (
+        processing &&
+        text !== lastPlainEmittedText &&
+        !tokenizationCache.has(normalizeSubtitleCacheKey(text))
+      ) {
+        deps.emitSubtitle({ text, tokens: null });
+        lastPlainEmittedText = text;
+      }
       processLatest();
+      return true;
     },
     refreshCurrentSubtitle: (textOverride?: string) => {
       if (typeof textOverride === 'string') {
         latestText = textOverride;
       }
       if (!latestText.trim()) {
-        return;
+        // A run in flight will pick this up and emit the empty subtitle, so
+        // the caller is still waiting on an emit.
+        return processing;
       }
-      if (
-        processing ||
-        (latestText === lastEmittedText && cacheGeneration === lastEmittedGeneration)
-      ) {
-        return;
+      if (processing) {
+        return true;
+      }
+      if (latestText === lastEmittedText && cacheGeneration === lastEmittedGeneration) {
+        return false;
       }
       processLatest();
+      return true;
+    },
+    notePlainSubtitleEmitted: (text: string) => {
+      lastPlainEmittedText = text;
     },
     invalidateTokenizationCache: () => {
       tokenizationCache.clear();
@@ -169,13 +265,12 @@ export function createSubtitleProcessingController(
       latestText = text;
       lastEmittedText = text;
       lastEmittedGeneration = cacheGeneration;
+      lastPlainEmittedText = null;
       return cached;
     },
     hasCachedSubtitle: (text: string) => {
-      return tokenizationCache.has(normalizeSubtitleCacheKey(text));
-    },
-    isCacheFull: () => {
-      return tokenizationCache.size >= SUBTITLE_TOKENIZATION_CACHE_LIMIT;
+      const cacheKey = normalizeSubtitleCacheKey(text);
+      return cacheKey.length > 0 && tokenizationCache.has(cacheKey);
     },
   };
 }