chore(release): prepare v0.19.4-beta.2

- Use GitHub-hosted video playback for the README demo
- Document the animated fallback behavior

.github/workflows/prerelease.yml

@@ -274,7 +274,8 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 
       - name: Generate checksums
         run: |

.github/workflows/release.yml

@@ -273,7 +273,8 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 
       - name: Generate checksums
         run: |

Makefile

@@ -2,8 +2,10 @@
 
 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
+THUMBNAILER_SOURCE := assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 LAUNCHER_OUT := dist/launcher/$(APP_NAME)
 THEME_FILE := subminer.rasi
+THUMBNAILER_FILE := subminer-ffmpegthumbnailer.thumbnailer
 
 # Default install prefix for the wrapper script.
 PREFIX ?= $(HOME)/.local
@@ -221,11 +223,13 @@ docs-dev: ensure-bun
 
 
 install-linux: build-launcher
-	@printf '%s\n' "[INFO] Installing Linux wrapper/theme artifacts"
+	@printf '%s\n' "[INFO] Installing Linux wrapper/support artifacts"
 	@install -d "$(BINDIR)"
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(LINUX_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@install -d "$(LINUX_DATA_DIR)/thumbnailers"
+	@install -m 0644 "./$(THUMBNAILER_SOURCE)" "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@install -d "$(LINUX_DATA_DIR)/plugin/subminer"
 	@cp -R ./plugin/subminer/. "$(LINUX_DATA_DIR)/plugin/subminer/"
 	@if [ -n "$(APPIMAGE_SRC)" ]; then \
@@ -234,7 +238,7 @@ install-linux: build-launcher
 		printf '%s\n' "[WARN] No release/SubMiner-*.AppImage found; skipping AppImage install"; \
 		printf '%s\n' "       Build one with: make build"; \
 	fi
-	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 
 install-macos: build-launcher
 	@printf '%s\n' "[INFO] Installing macOS wrapper/theme/app artifacts"
@@ -275,8 +279,9 @@ uninstall:
 uninstall-linux:
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 	@rm -f "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@rm -f "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@rm -rf "$(LINUX_DATA_DIR)/plugin/subminer"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
 
 uninstall-macos:
 	@rm -f "$(BINDIR)/subminer"

README.md

@@ -15,7 +15,7 @@ Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersio
 [![License](https://img.shields.io/github/license/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://www.gnu.org/licenses/gpl-3.0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-1a1a2e?style=flat-square&logo=typescript&logoColor=3178c6)](https://www.typescriptlang.org)
 
-[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/89e61895-e2b7-4b47-8d50-a35afe4132b2)
+[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/7abab8a9-4e4e-4f06-9f3c-9783e15a3807)
 
 </div>
 

assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer

@@ -0,0 +1,4 @@
+[Thumbnailer Entry]
+TryExec=ffmpegthumbnailer
+Exec=ffmpegthumbnailer -i %i -o %o -s %s -f
+MimeType=video/matroska;video/matroska-3d;video/x-matroska;video/x-matroska-3d;

changes/ass-canonical-animation-lines.md

@@ -0,0 +1,5 @@
+type: fixed
+area: subtitles
+
+- Typeset ASS karaoke and animated signs no longer flood the primary overlay, subtitle sidebar, immersion history, or sentence mining with repeated glyph fragments or full-line color phases. Matching timed comments and full-line boundary events recover the complete authored line without merging ordinary repeated dialogue or separately positioned signs, and dialogue spoken while a song's animation is on screen is kept intact instead of being replaced by the lyric. Entrance and exit frames that run past the authored line timing still resolve to the clean line during lyric transitions, and dialogue spoken while a song's animation is on screen enters immersion and subtitle history without the fragment lines beside it.
+- The secondary subtitle overlay drops layered duplicate lines from animated tracks, so a short stack of repeated words collapses to its distinct lines even when the full karaoke heuristic does not apply.

changes/character-dictionary-mecab-cache.md

@@ -0,0 +1,5 @@
+type: fixed
+area: character dictionary
+
+- Reuse character dictionaries after MeCab completes without finding any name splits instead of regenerating character data and portraits on every launch.
+- Restore inline character portraits when a cached portrait index finishes loading after subtitles have already been tokenized.

changes/dictionary-freeze-and-appimage-notifications.md

@@ -0,0 +1,5 @@
+type: fixed
+area: dictionary
+
+- Character dictionary generation, merged rebuilds, and imports no longer freeze the app (and trigger the compositor's "application not responding" dialog) on large dictionaries; snapshot reads/writes, archive building, and the character image/name lookup caches now do their heavy work off the UI's critical path.
+- Desktop progress notifications now update in place on Linux AppImage installs too: the AppImage's bundled libraries broke the system notify-send helper, which silently forced the flickering close-and-reopen notification fallback.

changes/docs-site-index-hygiene.md

@@ -0,0 +1,5 @@
+type: internal
+area: docs
+
+- Excluded the `/main/` and `/v/<version>/` docs trees from search indexing with a self-referential canonical, `noindex,follow`, and a matching `X-Robots-Tag` header, so crawlers spend their budget on the current docs instead of ~30 archived copies of every page.
+- Restored `<lastmod>` dates in the docs sitemap, which were silently dropped because production builds render from an untracked release snapshot.

changes/fix-macos-fullscreen-modal-spaces.md

@@ -0,0 +1,5 @@
+type: fixed
+area: overlay
+
+- Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly on the first press. Windows now refreshes the hidden modal renderer between sessions to keep later modals interactive. On macOS, reused modals and the in-app stats window also open above fullscreen mpv on its current Space instead of appearing on another desktop or forcing a Space change.
+- Updated subtitle ASS observation to mpv's current `sub-text/ass` property, removing its deprecation warning.

changes/fix-mpv-ipc-connect-stall.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed the overlay getting stuck on "Overlay loading" forever when startup stalls: mpv IPC connection attempts now time out and retry, switching sockets aborts obsolete attempts, and the plugin replaces its spinner with an actionable error if overlay content is still not ready after 30 seconds.

changes/fix-primary-ass-layer-duplication.md

@@ -0,0 +1,4 @@
+type: fixed
+area: subtitles
+
+- Primary ASS subtitles now use the active parsed cue when it fully accounts for mpv's live text, preventing fill, border, blur, and shadow copies of the same full-span lyric from appearing repeatedly while preserving unmatched overlapping dialogue and signs.

changes/fix-secondary-subtitle-duplication.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Secondary subtitles now parse the selected ASS/SRT/VTT source with the primary subtitle deduplication pipeline, preventing layered animation text from appearing several times in the overlay, mined cards, and statistics. Live mpv text remains the fallback for unreadable tracks.

changes/fix-windows-system-mouse-lag.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed system-wide mouse lag on Windows while SubMiner is running: the overlay no longer installs Electron's global mouse hook for click-through forwarding, and the mpv window tracker no longer blocks the app on repeated PowerShell command-line lookups.

changes/hide-feature-demos.md

@@ -1,4 +0,0 @@
-type: docs
-area: documentation
-
-- Hid the unfinished feature demos page from the documentation sidebar while keeping its direct URL available.

changes/media-timing-review.md

@@ -1,4 +0,0 @@
-type: added
-area: mining
-
-- Added optional pre-generation timing review for word, sentence, and audio cards with a compact speech-weighted waveform, clearly labeled mined-line boundaries, drag and keyboard adjustments, audio preview with a sweeping playhead, exact screenshot and AVIF timing, cancellation choices that include keeping a card without media, and a session-only runtime toggle.

changes/rofi-matroska-thumbnails.md

@@ -0,0 +1,4 @@
+type: fixed
+area: launcher
+
+- Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.

changes/stats-vocabulary-summary-totals.md

@@ -0,0 +1,8 @@
+type: fixed
+area: stats
+
+- Fixed Vocabulary totals and charts counting only the first browsing page instead of all tracked vocabulary, without delaying the rest of the page.
+- New-word history now uses permanent daily lexical rollups that apply the same vocabulary filters as the totals and normalize legacy second/millisecond timestamps; versioned background rebuilds repair existing history across legacy rollup-state schemas without dropping playback writes or clearing watch-time, activity, efficiency, and library charts.
+- Calendar-day chart labels now preserve the recorded local date in time zones west of UTC.
+- Vocabulary summary cards and charts refresh automatically after the word exclusion list changes, and failed or unfinished loads use bounded retries before showing an inline error with a Retry control.
+- Rapid exclusion edits no longer race each other; writes are sent in order so a slower earlier save cannot overwrite a newer list.

config.example.jsonc

@@ -523,7 +523,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind 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.
   // ==========================================
@@ -569,7 +569,6 @@
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
       "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
-      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
       "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.

docs-site/.vitepress/config.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { extname, join, posix, resolve, sep } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
@@ -26,6 +27,9 @@ function optionalEnv(value: string | undefined): string | undefined {
 const base = normalizeBase(optionalEnv(process.env.SUBMINER_DOCS_BASE) ?? '/');
 const outDir = optionalEnv(process.env.SUBMINER_DOCS_OUT_DIR);
 const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? process.cwd();
+// The tracked `docs-site/` checkout, which stays a git working tree even when
+// `docsSourceDir` points at an untracked release snapshot. Used for git lookups only.
+const repoDocsDir = optionalEnv(process.env.SUBMINER_DOCS_REPO_DIR) ?? process.cwd();
 const channel = normalizeChannel(optionalEnv(process.env.SUBMINER_DOCS_CHANNEL));
 const docsVersion = optionalEnv(process.env.SUBMINER_DOCS_VERSION);
 const latestStable = optionalEnv(process.env.SUBMINER_DOCS_LATEST_STABLE) ?? 'v0.18.0';
@@ -82,15 +86,18 @@ function pageToRoute(page: string): string | null {
   return route ? `/${route}` : '/';
 }
 
+// Only the root channel is indexable. `main` and every /v/<version>/ archive are
+// near-verbatim copies of it, so they own their URL via a self-referential canonical
+// and are excluded from the index instead of being consolidated onto root. Uniform
+// self-canonical plus noindex avoids mixing noindex with a cross-page canonical,
+// which Google treats as a conflicting signal.
+const isIndexableChannel = channel === 'stable-root';
+
 function pageToCanonicalHref(page: string): string | null {
   const route = pageToRoute(page);
   if (!route) return null;
 
-  if (channel === 'main') {
-    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
-  }
-
-  if (channel === 'stable-archive' && docsVersion !== latestStable) {
+  if (!isIndexableChannel) {
     return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
   }
 
@@ -106,7 +113,9 @@ function transformPageHead({ page }: TransformContext): HeadConfig[] {
   const href = pageToCanonicalHref(page);
   const head: HeadConfig[] = href ? [['link', { rel: 'canonical', href }]] : [];
 
-  if (channel === 'main') {
+  // Crawlable so links still pass through, but out of the index: ~30 archived copies
+  // of every page otherwise soak up the crawl budget the current docs need.
+  if (!isIndexableChannel) {
     head.push(['meta', { name: 'robots', content: 'noindex,follow' }]);
   }
 
@@ -287,6 +296,39 @@ const versionItems = [
   })),
 ];
 
+function sitemapUrlToPage(url: string): string {
+  const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+// VitePress derives <lastmod> by running `git log` inside its source dir. Production
+// builds point that at an untracked snapshot of the release tag, so the lookup comes
+// back empty and the sitemap ships with no dates at all. Resolve it from the tracked
+// checkout at the ref being built instead.
+function lastModifiedFor(url: string): string | undefined {
+  const ref = docsVersion && docsVersion !== 'main' ? docsVersion : 'HEAD';
+  const result = spawnSync('git', ['log', '-1', '--format=%cI', ref, '--', sitemapUrlToPage(url)], {
+    cwd: repoDocsDir,
+    encoding: 'utf8',
+  });
+
+  return (result.status === 0 && result.stdout.trim()) || undefined;
+}
+
+// Only the root channel publishes a sitemap. Archived and `main` builds would emit
+// their own copies listing the same canonical URLs, which just advertises the
+// duplicate trees we are trying to keep out of the index.
+const sitemap: UserConfig['sitemap'] = isIndexableChannel
+  ? {
+      hostname: DOCS_HOSTNAME,
+      transformItems(items) {
+        return items
+          .filter((item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`)
+          .map((item) => ({ ...item, lastmod: item.lastmod ?? lastModifiedFor(item.url) }));
+      },
+    }
+  : undefined;
+
 const nav: DefaultTheme.NavItem[] = [
   { text: 'Home', link: '/' },
   { text: 'Get Started', link: '/installation' },
@@ -419,14 +461,7 @@ const config: UserConfig = {
   appearance: 'dark',
   cleanUrls: true,
   metaChunk: true,
-  sitemap: {
-    hostname: DOCS_HOSTNAME,
-    transformItems(items) {
-      return items.filter(
-        (item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`,
-      );
-    },
-  },
+  sitemap,
   transformHead: transformPageHead,
   lastUpdated: true,
   srcExclude: ['subagents/**', 'README.md'],

docs-site/README.md

@@ -38,8 +38,10 @@ bun run docs:dev
 The public docs root is stable-only:
 
 - `/` serves the latest stable release docs.
-- `/main/` serves development docs from `main` and is marked `noindex,follow`.
+- `/main/` serves development docs from `main`.
 - `/v/<version>/` serves stable release archives.
 - Prerelease tags do not update the docs site.
 
+Only `/` is indexable. `/main/` and every `/v/<version>/` page carries a self-referential canonical plus `noindex,follow`, and the generated `_headers` file repeats that as an `X-Robots-Tag`. They stay crawlable so their links still resolve, but ~30 archived copies of every page would otherwise consume the crawl budget the current docs need. Only the root build emits `sitemap.xml`, and its `<lastmod>` dates come from `git log` against the tracked checkout at the released tag, because the build renders from an untracked snapshot that VitePress cannot date itself.
+
 Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.

docs-site/anki-integration.md

@@ -166,7 +166,6 @@ Audio is extracted from the video file using the subtitle's start and end timest
     "generateAudio": true,
     "normalizeAudio": true,      // normalize generated clip loudness
     "mirrorMpvVolume": true,     // apply the current mpv volume level
-    "reviewTiming": false,       // review and adjust timing before media generation
     "audioPadding": 0,           // optional seconds before and after subtitle timing
     "maxMediaDuration": 30       // cap total duration in seconds
   }
@@ -179,10 +178,6 @@ Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMine
 
 The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
 
-Set `media.reviewTiming` to `true` to pause playback and review each word, sentence, or audio card before its media is generated. The review opens with the subtitle range plus configured audio padding. Drag either edge of the clip to trim it, drag the middle to slide it without changing its length, or press anywhere else on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys, by 100 ms alone or 500 ms with Shift, and the 100 ms buttons do the same. Space previews the selection with a playhead that sweeps the clip, Enter confirms, and Escape cancels. The Earlier and Later buttons reveal another two seconds of available timeline without moving the selected clip. A speech-weighted waveform shows the mined subtitle as a tinted band with labeled line-start and line-end rails, making adjacent dialogue easier to distinguish. SubMiner uses a center channel when one carries dialogue, then falls back to a speech-band mono mix. Waveform analysis failure leaves the timing controls available. The confirmed range is exact: SubMiner does not apply audio padding a second time. Static screenshots use its midpoint, and animated AVIF clips use the full confirmed range.
-
-Canceling the review lets you keep editing, finish with the original timing, keep or create the card without audio or an image, or discard the card. Discard deletes an existing Yomitan or audio card and skips creation for a direct sentence card. Clipboard updates and stats-dashboard mining do not open timing review. Audio preview failure does not block confirmation or card creation. The option is disabled by default and hot-reloads. You can also toggle **Review Media Timing** for the current session from the runtime options palette (`Ctrl/Cmd+Shift+O`).
-
 ### Screenshots (Static)
 
 A single frame is captured at the current playback position.

docs-site/configuration.md

@@ -873,10 +873,9 @@ When config hot-reload updates shortcut/keybinding/style values, close and reope
 
 Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.
 
-Current runtime options cover automatic card updates, media timing review,
-known-word highlighting, known-word maturity coloring, N+1 annotation, JLPT
-underlines, frequency highlighting, known-word match mode, and Kiku field
-grouping mode.
+Current runtime options cover automatic card updates, known-word highlighting,
+known-word maturity coloring, N+1 annotation, JLPT underlines, frequency
+highlighting, known-word match mode, and Kiku field grouping mode.
 
 Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.
 
@@ -968,7 +967,6 @@ Enable automatic Anki card creation and updates with media generation:
       "animatedCrf": 35,
       "normalizeAudio": true,
       "mirrorMpvVolume": true,
-      "reviewTiming": false,
       "audioPadding": 0,
       "fallbackDuration": 3,
       "maxMediaDuration": 30
@@ -1021,7 +1019,6 @@ This example is intentionally compact. The option table below documents availabl
 | `media.generateAudio`                             | `true`, `false`                             | Generate audio clips from video (default: `true`)                                                                                                                                                                               |
 | `media.normalizeAudio`                            | `true`, `false`                             | Normalize generated sentence-audio loudness during media extraction (default: `true`). Set to `false` to keep raw source loudness. Changes apply live.                                                                          |
 | `media.mirrorMpvVolume`                           | `true`, `false`                             | Apply mpv's cubic software-volume curve to each generated sentence-audio clip (default: `true`). This ignores mpv's separate mute state, falls back to unity scaling if volume cannot be read, and applies changes live.        |
-| `media.reviewTiming`                              | `true`, `false`                             | Pause playback and review word, sentence, and audio card timing before media generation (default: `false`). Clipboard updates and stats-dashboard mining do not open the review.                                                |
 | `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
 | `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
 | `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |

docs-site/demos.md

@@ -5,7 +5,7 @@ Short recordings of SubMiner's key features and integrations from real playback
 <script setup>
 import { withBase } from 'vitepress';
 
-const v = '20260301-1';
+const v = '20260819-1';
 </script>
 
 ## Anki Card Mining & Enrichment

docs-site/immersion-tracking.md

@@ -82,7 +82,7 @@ Expandable session history with new-word activity, cumulative totals, and pause/
 
 #### Vocabulary
 
-Top repeated words (click a bar to open the word), new-word timeline, cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.
+The summary cards show all unique vocabulary and kanji recorded in the local tracking database; **New This Week** is the only weekly figure and uses a rolling seven-day window. The word and kanji tables load first while those complete totals calculate separately. Top Repeated Words and New Words by Day use complete tracking history rather than the table's browsing page. New-word history is maintained as a permanent daily lexical rollup using the same token-visibility rules as the totals, including normalization of older timestamps stored in either seconds or milliseconds and retroactive corrections when tracked material is removed or reprocessed. On the first launch after an applicable upgrade, that history is version-rebuilt in the background and the chart refreshes when it is ready; if it remains unavailable, polling stops and an inline Retry control appears. The cards and charts also refresh automatically after the word exclusion list changes. The rest of the tab includes cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.
 
 ![Stats Vocabulary](/screenshots/stats-vocabulary.png)
 
@@ -138,6 +138,8 @@ Karaoke openings and animated signs are authored as one subtitle event per anima
 
 Recording now collapses those runs as they happen, matching what the subtitle sidebar shows:
 
+- When a typeset ASS file stores a clean lyric or sign in a timed authoring comment, or in full-line events surrounding generated fragments, the matching complete line is recorded once. The repeated glyph or clip-animation frames are not recorded. Dialogue spoken while such an animation is on screen records as itself, without the fragment lines beside it.
+- When karaoke styling redraws the same complete lyric across consecutive color or highlight phases, those phases are combined into one line with their full timing. Repeated ordinary dialogue remains separate.
 - 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.
 - When no parsed cue covers the live timing, including while a subtitle source is changing or shifted, the strict metadata-free rule applies: a run of identical, contiguous lines each shorter than 0.1s stops being recorded after a few frames. Runs are tracked per line of text, so dual-line karaoke (a kanji and a romaji line frame-flipped together) collapses both lines. Ordinary repeated dialogue, and lines held for a normal beat, always record.
 
@@ -180,6 +182,7 @@ In practice:
 - Anime and episode pages keep lifetime totals from summary tables while session drill-down still reads retained sessions directly. With the current defaults, both are kept forever.
 - Trends can read the full available history because daily/monthly rollups are also kept forever by default.
 - Vocabulary and kanji totals are cumulative and not bounded by the raw session retention knobs.
+- New-word charts use their own permanent lexical daily rollups, which are not pruned by activity-rollup retention.
 
 ## Storage / Performance Model
 
@@ -349,6 +352,7 @@ Rollup tables:
 
 - `imm_daily_rollups`
 - `imm_monthly_rollups`
+- `imm_lexical_daily_rollups` - permanent first-discovery counts for vocabulary and kanji chart history
 - `imm_rollup_state` - incremental rollup progress bookkeeping
 
 Vocabulary tables:

docs-site/index.md

@@ -88,7 +88,7 @@ features:
 <script setup>
 import { withBase } from 'vitepress';
 
-const demoAssetVersion = '20260223-2';
+const demoAssetVersion = '20260819-1';
 </script>
 
 <div class="landing-shell">

docs-site/installation.md

@@ -392,7 +392,7 @@ subminer -u
 subminer --update
 ```
 
-SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer` plus the rofi theme at `SubMiner/themes/subminer.rasi`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
+SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer`, the rofi theme at `SubMiner/themes/subminer.rasi`, and the scoped Matroska thumbnailer registration under `SubMiner/thumbnailers`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
 
 The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. On Linux it replaces the running `.AppImage` in place via `electron-updater` and refreshes the managed support assets from `subminer-assets.tar.gz`; AppImages managed by a system package (for example the AUR `/opt/SubMiner/SubMiner.AppImage`) are skipped so the package manager stays in charge.
 
@@ -404,7 +404,7 @@ SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IP
 
 The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) - without it the overlay starts but subtitles won't appear.
 
-The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. On Linux, the `subminer` launcher now checks for its managed runtime plugin copy and rofi theme before every mpv-managed launch and installs those support assets from the bundled app automatically if either one is missing. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
+The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. On Linux, the `subminer` launcher checks for its managed runtime plugin copy, rofi theme, and scoped thumbnailer registration before every mpv-managed launch and installs those support assets from the bundled app automatically if one is missing. For a rofi picker launch, this check runs before the picker opens. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
 
 ## Platform Notes
 
@@ -456,18 +456,20 @@ sudo chmod +x /usr/local/bin/subminer
 
 ### Linux Support Assets
 
-SubMiner ships the Linux rofi theme plus the launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:
+SubMiner ships the Linux rofi theme, scoped Matroska thumbnailer registration, and launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:
 
 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/thumbnailers
+cp /tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer ~/.local/share/SubMiner/thumbnailers/
 mkdir -p ~/.local/share/SubMiner/plugin
 cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```
 
-`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs the managed runtime plugin copy and rofi theme from the bundled app if either support asset is missing, so manual extraction is mainly useful for pre-seeding or custom setups.
+`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs all three assets from the bundled app if one is missing, so manual extraction is mainly useful for pre-seeding or custom setups. Rofi receives the SubMiner data path through its process-local `XDG_DATA_DIRS`, so the thumbnailer registration does not change the desktop-wide configuration.
 
 Override the theme path with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.
 

docs-site/launcher-script.md

@@ -34,18 +34,22 @@ subminer -R -r -d ~/Anime              # rofi picker, recursive
 subminer -R /directory                 # rofi picker, directory shortcut
 ```
 
-rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme plus the Linux launcher-managed runtime plugin copy in the release assets tarball:
+rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme, a scoped `ffmpegthumbnailer` MIME registration, and the Linux launcher-managed runtime plugin copy in the release assets tarball:
 
 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/thumbnailers
+cp /tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer ~/.local/share/SubMiner/thumbnailers/
 mkdir -p ~/.local/share/SubMiner/plugin
 cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```
 
-Once the `SubMiner` data dir exists, `subminer -u` refreshes both assets automatically. Normal Linux launcher playback also checks for the managed runtime plugin copy and rofi theme before mpv launch and installs them from the bundled app automatically if either one is missing.
+Once the `SubMiner` data dir exists, `subminer -u` refreshes these assets automatically. Normal Linux launcher playback checks for all three assets and installs them from the bundled app when one is missing. For `subminer -R`, this repair runs before rofi opens.
+
+When `ffmpegthumbnailer` is installed, SubMiner prepends its own data directory to `XDG_DATA_DIRS` for the rofi process only. This lets rofi recognize the canonical Matroska MIME types used by newer GLib versions without changing the desktop-wide MIME or thumbnailer configuration. An existing registration in your own `$XDG_DATA_HOME/thumbnailers` still takes priority.
 
 The theme is auto-detected from these paths (first match wins):
 

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/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind 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.
   // ==========================================
@@ -569,7 +569,6 @@
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
       "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
-      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
       "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.

docs-site/seo.test.ts

@@ -56,34 +56,43 @@ test('main docs canonical uses /main/ and emits noindex', async () => {
     { rel: 'canonical', href: 'https://docs.subminer.moe/main/' },
   ]);
   expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+  expect(mainDocsConfig.sitemap).toBeUndefined();
 
   process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
   process.env.SUBMINER_DOCS_BASE = previousBase;
 });
 
-test('latest stable archive canonical points to root equivalent', async () => {
+test.each([
+  ['latest stable', 'v0.14.0', '/v/0.14.0/', 'https://docs.subminer.moe/v/0.14.0/usage'],
+  ['superseded', 'v0.12.0', '/v/0.12.0/', 'https://docs.subminer.moe/v/0.12.0/usage'],
+])(
+  '%s archive keeps a self-referential canonical and stays out of the index',
+  async (_label, version, base, expectedCanonical) => {
     const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
     const previousBase = process.env.SUBMINER_DOCS_BASE;
     const previousVersion = process.env.SUBMINER_DOCS_VERSION;
     const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
     process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
-  process.env.SUBMINER_DOCS_BASE = '/v/0.14.0/';
-  process.env.SUBMINER_DOCS_VERSION = 'v0.14.0';
+    process.env.SUBMINER_DOCS_BASE = base;
+    process.env.SUBMINER_DOCS_VERSION = version;
     process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  const { default: latestArchiveConfig } = await import('./.vitepress/config?latest-archive');
+    try {
+      const { default: archiveConfig } = await import(`./.vitepress/config?archive-${version}`);
 
-  const head = await latestArchiveConfig.transformHead?.(makeTransformContext('usage.md'));
-
-  expect(head).toContainEqual([
-    'link',
-    { rel: 'canonical', href: 'https://docs.subminer.moe/usage' },
-  ]);
+      const head = await archiveConfig.transformHead?.(makeTransformContext('usage.md'));
 
+      expect(head).toContainEqual(['link', { rel: 'canonical', href: expectedCanonical }]);
+      expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+      // A sitemap here would advertise the archive tree we just excluded.
+      expect(archiveConfig.sitemap).toBeUndefined();
+    } finally {
       process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
       process.env.SUBMINER_DOCS_BASE = previousBase;
       process.env.SUBMINER_DOCS_VERSION = previousVersion;
       process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
-});
+    }
+  },
+);
 
 test('stable archive theme links stay on the selected version', async () => {
   const previousCwd = process.cwd();
@@ -433,3 +442,22 @@ test('docs sitemap excludes duplicate README page from indexable URLs', async ()
 
   expect(transformedItems?.map((item) => item.url)).toEqual(['', 'usage']);
 });
+
+test('docs sitemap dates every URL from the tracked checkout', async () => {
+  const previousRepoDir = process.env.SUBMINER_DOCS_REPO_DIR;
+  // Production builds render from an untracked snapshot, so the date has to come from
+  // the real checkout rather than VitePress's own srcDir git lookup.
+  process.env.SUBMINER_DOCS_REPO_DIR = docsSiteDir;
+  try {
+    const { default: sitemapConfig } = await import('./.vitepress/config?sitemap-lastmod');
+
+    const items = await sitemapConfig.sitemap?.transformItems?.([{ url: '' }, { url: 'usage' }]);
+
+    expect(items).toHaveLength(2);
+    for (const item of items ?? []) {
+      expect(item.lastmod).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    }
+  } finally {
+    process.env.SUBMINER_DOCS_REPO_DIR = previousRepoDir;
+  }
+});

docs-site/subtitle-sidebar.md

@@ -12,6 +12,8 @@ When SubMiner parses the active subtitle source into a cue list, the sidebar bec
 - Clicking any cue seeks mpv to that timestamp.
 - The sidebar stays synchronized with the overlay - media transitions and subtitle source changes update both simultaneously.
 
+For typeset ASS karaoke and animated signs, SubMiner collapses generated animation frames and repeated full-line color phases before they reach the sidebar. It recovers a clean complete line from a matching timed authoring comment or from full-line events surrounding generated fragments. Ordinary ASS comments, editor notes, alternate lines, repeated dialogue, and separately positioned signs remain distinct.
+
 The sidebar only appears when a parsed cue list is available. External subtitle sources that SubMiner cannot parse (for example, embedded ASS tracks rendered directly by mpv) will not populate the sidebar.
 
 ## Layout Modes

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

@@ -70,18 +70,25 @@ interface SubtitleCue {
   startTime: number; // seconds
   endTime: number; // seconds
   text: string; // plain text, decoded from the source format
+  source?: 'canonical-ass'; // recovered authored text for generated ASS animation
+  animationStartTime?: number; // full generated-frame envelope; entrance/exit frames
+  animationEndTime?: number; //   run past the authored timing, live matching uses this
 }
 ```
 
 **Supported formats:**
 
 - SRT/VTT: Regex-based parsing of timing lines + text content between timing blocks.
-- 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: Parse the `[Events]` section, read the field order from the `Format:` row, and extract timed `Dialogue:` lines. Timed `Comment:` lines are normally ignored, but can supply canonical authored text when they match a nearby generated animation from the same style and actor. 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`.
 
+ASS scripts can also redraw one complete lyric for two or more long color/highlight phases. Those flush-timed phases collapse separately from short animation frames when they share text, style, actor, and layer and carry direct animation evidence, such as temporal tags or changing non-spatial overrides. Spatial command changes do not prove a phase, so separately positioned signs remain distinct.
+
+**Canonical animation recovery.** Some ASS producers keep the readable lyric or sign as a timed `Comment:` and generate hundreds of `Dialogue:` frames containing repeated glyphs or changing clip regions. Others retain the complete line as brief `Dialogue:` events around the generated fragments. A complete event is promoted only when nearby dialogue from the same style and actor forms a proven animation cluster and reconstructs its entire text in source order. The generated frames are then replaced by one cue marked `source: 'canonical-ass'`. This source marker lets the live primary-subtitle path prefer the clean authored text and timing for display, sidebar history, immersion recording, and mining, while unmatched editor notes and alternative translations remain ignored.
+
 #### Prefetch Service Lifecycle
 
 1. **Activation trigger:** When a subtitle track is activated (or changes), check if it's external via MPV's `track-list` property. If `external === true`, read the file via `external-filename` using the existing `loadSubtitleSourceText` infrastructure.

docs/architecture/stats-trends-data-flow.md

@@ -23,7 +23,9 @@ Trend charts now consume one chart-oriented backend payload from `/api/stats/tre
   - lookup rate trends
   - watch-time by day-of-week/hour
 - vocabulary-backed:
-  - new-words trend
+  - new-words trend reads permanent daily lexical rollups
+  - rollup rows count only vocabulary-visible tokens and normalize mixed legacy timestamp units
+  - a persisted rollup version invalidates stale materializations and triggers an atomic background rebuild
 
 ## Metric Semantics
 

docs/architecture/subtitle-overlay-priming.md

@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming
 
 Status: active
-Last verified: 2026-08-04
+Last verified: 2026-08-18
 Owner: Kyle Yasuda
 Read when: debugging subtitle state or blank Linux/X11 overlay windows when the visible overlay is shown or recreated
 
@@ -69,6 +69,11 @@ coming and prefetching would otherwise idle for the rest of the cue.
 
 ## Live Cue Delivery
 
+- Primary live text first resolves recovered canonical ASS animations. Otherwise, when
+  every live mpv line matches an active parsed cue, it uses the parsed cue text so exact
+  full-span style layers appear once instead of repeating for fill, border, blur, and
+  shadow events. Any unmatched live line keeps the complete live stack, preserving
+  dialogue or signs that overlap a lyric.
 - 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
@@ -77,6 +82,25 @@ coming and prefetching would otherwise idle for the rest of the 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.
 
+## Secondary Subtitle Flow
+
+- `secondary-sub-text` remains the immediate fallback, so unreadable and remote subtitle sources
+  still appear without waiting for file resolution.
+- `secondary-subtitle-track.ts` resolves `secondary-sid` against mpv's track list. External tracks
+  are read directly; supported embedded text tracks are extracted through the same ffmpeg-backed
+  source resolver used by primary subtitle prefetching.
+- The selected source is parsed with `parseSubtitleCues()`, including metadata-aware ASS duplicate
+  and animation collapse. Playback `time-pos` selects the active parsed cue after applying
+  `secondary-sub-delay`.
+- The resolved text is stored in `mpvClient.currentSecondarySubText` before it is broadcast. The
+  overlay, mining, timing tracker, and immersion statistics therefore consume the same secondary
+  text when a readable source is available.
+- Media and `secondary-sid` changes clear the previous parsed state before refreshing the source;
+  track-list changes refresh without discarding an unchanged source. Observed
+  `secondary-sub-delay` changes retime the active parsed cue without rereading the file. If loading,
+  extraction, or parsing fails, the controller returns to live mpv text and the renderer's
+  conservative short stack heuristic remains the final display fallback.
+
 ## Emitted State
 
 - `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`. Overlay windows and annotation
@@ -84,8 +108,8 @@ coming and prefetching would otherwise idle for the rest of the cue.
 - 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.
+- Secondary priming reads mpv `secondary-sub-text` and routes it through the secondary track
+  controller. A parsed active cue replaces the live text when the selected source is readable.
 - If secondary `requestProperty` fails, the primary flow stays complete and only a debug line is
   written.
 
@@ -129,7 +153,11 @@ coming and prefetching would otherwise idle for the rest of the cue.
   path, empty or stale bounding shapes produced invisible or clipped subtitles even though the
   overlay window remained mapped above mpv.
 - Pointer pass-through should continue to use `setIgnoreMouseEvents(true, { forward: true })` and
-  the Linux cursor-poll fallback, not bounding-shape clipping.
+  the Linux cursor-poll fallback, not bounding-shape clipping. Note that on Windows click-through
+  must go through `applyOverlayClickThrough()` (`src/core/services/overlay-click-through.ts`),
+  which omits `forward: true` there: Electron implements forwarding with a global low-level mouse
+  hook that lags mouse input system-wide whenever the main thread stalls; the Windows cursor poll
+  handles overlay wake-up instead.
 - Visible-overlay show/reset marks Linux pointer passthrough state dirty even when the logical
   interaction state is already inactive. The next cursor-poll tick must still reapply
   `setIgnoreMouseEvents(true, { forward: true })`; otherwise a newly shown Electron overlay can keep

launcher/commands/history-command.ts

@@ -23,6 +23,7 @@ import {
   type HistorySeriesEntry,
 } from '../history.js';
 import type { Args } from '../types.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import type { LauncherCommandContext } from './context.js';
 
 export type HistorySessionAction = 'previous' | 'replay' | 'next' | 'browse' | 'quit';
@@ -333,6 +334,13 @@ export async function runHistoryCommand(
   const { args, scriptPath } = context;
 
   checkPickerDependencies(args);
+  if (args.useRofi) {
+    await ensureLinuxRuntimePluginAvailable({
+      appPath: context.appPath ?? undefined,
+      scriptPath,
+      logLevel: args.logLevel,
+    });
+  }
   const themePath = args.useRofi ? findRofiTheme(scriptPath) : null;
 
   const dbPath = resolveImmersionDbPath();

launcher/commands/jellyfin-command.ts

@@ -2,6 +2,7 @@ import { fail } from '../log.js';
 import { runAppCommandWithInherit } from '../mpv.js';
 import { commandExists } from '../util.js';
 import { runJellyfinPlayMenu } from '../jellyfin.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import { shouldForwardLogLevel } from '../types.js';
 import type { LauncherCommandContext } from './context.js';
 
@@ -64,6 +65,13 @@ export async function runJellyfinCommand(context: LauncherCommandContext): Promi
     if (args.useRofi && !commandExists('rofi')) {
       fail('rofi not found. Install rofi or omit -R for fzf.');
     }
+    if (args.useRofi) {
+      await ensureLinuxRuntimePluginAvailable({
+        appPath,
+        scriptPath,
+        logLevel: args.logLevel,
+      });
+    }
     await runJellyfinPlayMenu(appPath, args, scriptPath, mpvSocketPath);
     return true;
   }

launcher/commands/playback-command.test.ts

@@ -496,3 +496,39 @@ test('playback command ensures Linux runtime plugin before mpv launch', async ()
 
   assert.deepEqual(calls, ['plugin', 'startMpv']);
 });
+
+test('rofi playback repairs support assets before opening the picker', async () => {
+  const context = createContext();
+  context.args = {
+    ...context.args,
+    target: '',
+    targetKind: '',
+    useRofi: true,
+  };
+  const calls: string[] = [];
+
+  await runPlaybackCommandWithDeps(context, {
+    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {
+      calls.push('assets');
+    },
+    chooseTarget: async () => {
+      calls.push('picker');
+      return { target: '/tmp/movie.mkv', kind: 'file' };
+    },
+    checkPickerDependencies: () => {},
+    checkDependencies: () => {},
+    registerCleanup: () => {},
+    startMpv: async () => {
+      calls.push('startMpv');
+    },
+    waitForUnixSocketReady: async () => true,
+    startOverlay: async () => {},
+    launchAppCommandDetached: () => {},
+    log: () => {},
+    cleanupPlaybackSession: async () => {},
+    getMpvProc: () => null,
+  });
+
+  assert.deepEqual(calls, ['assets', 'picker', 'startMpv']);
+});

launcher/commands/playback-command.ts

@@ -157,6 +157,7 @@ export async function runPlaybackCommand(context: LauncherCommandContext): Promi
       });
     },
     chooseTarget,
+    checkPickerDependencies,
     checkDependencies,
     registerCleanup,
     startMpv,
@@ -177,6 +178,7 @@ type PlaybackCommandDeps = {
     args: Args,
     scriptPath: string,
   ) => Promise<{ target: string; kind: 'file' | 'url' } | null>;
+  checkPickerDependencies?: (args: Args) => void;
   checkDependencies: (args: Args) => void;
   registerCleanup: (context: LauncherCommandContext) => void;
   startMpv: typeof startMpv;
@@ -201,7 +203,18 @@ export async function runPlaybackCommandWithDeps(
   await deps.ensurePlaybackSetupReady(context);
 
   if (!args.target) {
-    checkPickerDependencies(args);
+    (deps.checkPickerDependencies ?? checkPickerDependencies)(args);
+  }
+
+  let runtimeAssetsReady = false;
+  const ensureRuntimeAssetsReady = async (): Promise<void> => {
+    if (runtimeAssetsReady) return;
+    await deps.ensureRuntimePluginReady(context);
+    runtimeAssetsReady = true;
+  };
+
+  if (!args.target && args.useRofi) {
+    await ensureRuntimeAssetsReady();
   }
 
   const targetChoice = await deps.chooseTarget(args, scriptPath);
@@ -266,7 +279,7 @@ export async function runPlaybackCommandWithDeps(
     );
   }
 
-  await deps.ensureRuntimePluginReady(context);
+  await ensureRuntimeAssetsReady();
 
   await deps.startMpv(
     selectedTarget.target,

launcher/commands/update-command.test.ts

@@ -36,6 +36,11 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
         launcher: { status: 'updated' },
         supportAssets: [
           { status: 'updated', component: 'theme', message: 'Installed theme.' },
+          {
+            status: 'updated',
+            component: 'thumbnailer',
+            message: 'Installed rofi thumbnailer.',
+          },
           { status: 'skipped', component: 'plugin', message: 'Plugin already up to date.' },
         ],
       };
@@ -52,6 +57,7 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
     'info:AppImage update: updated',
     'info:Launcher update: updated',
     'info:Support assets (theme) update: updated - Installed theme.',
+    'info:Support assets (thumbnailer) update: updated - Installed rofi thumbnailer.',
     'info:Support assets (plugin) update: skipped - Plugin already up to date.',
   ]);
 });

launcher/commands/update-command.ts

@@ -21,7 +21,10 @@ import {
   parseSha256Sums,
   type FetchLike,
 } from '../../src/main/runtime/update/release-assets.js';
-import { updateSupportAssetsFromRelease } from '../../src/main/runtime/update/support-assets.js';
+import {
+  updateSupportAssetsFromRelease,
+  type SupportAssetsUpdateResult,
+} from '../../src/main/runtime/update/support-assets.js';
 
 type UpdateCommandResponse = {
   ok: boolean;
@@ -36,15 +39,14 @@ type DirectReleaseUpdateRequest = {
   channel: UpdateChannel;
 };
 
+type DirectSupportAssetsUpdateResult = Omit<SupportAssetsUpdateResult, 'status'> & {
+  status: string;
+};
+
 type DirectReleaseUpdateResult = {
   appImage: { status: string; command?: string; message?: string };
   launcher: { status: string; command?: string; message?: string };
-  supportAssets: Array<{
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  }>;
+  supportAssets: DirectSupportAssetsUpdateResult[];
 };
 
 type UpdateCommandDeps = {
@@ -129,12 +131,7 @@ function readUpdateChannel(root: Record<string, unknown> | null): UpdateChannel
 
 function logUpdateResult(
   label: string,
-  result: {
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  },
+  result: DirectSupportAssetsUpdateResult,
   configuredLogLevel: NonNullable<LauncherCommandContext['args']['logLevel']>,
   deps: Pick<UpdateCommandDeps, 'log'>,
 ): void {

launcher/main.test.ts

@@ -73,20 +73,21 @@ function makeTestEnv(homeDir: string, xdgConfigHome: string): NodeJS.ProcessEnv
   };
 }
 
-// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which —
-// when the runtime plugin/theme are missing — spawns the app with
-// `--ensure-linux-runtime-plugin-assets` and polls up to 30s
+// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which
+// spawns the app with `--ensure-linux-runtime-plugin-assets` when managed
+// support assets are missing and polls up to 30s
 // (RESPONSE_TIMEOUT_MS) for an install response. A fake app that just exits
 // never writes that response, so the launcher hangs and the test times out on
 // Linux CI (the preflight is a no-op on macOS/Windows). This shell prelude makes
-// the fake app install the managed plugin/theme and write the response, matching
+// the fake app install the managed support assets and write the response, matching
 // launcher/smoke.e2e.test.ts. Prepend it to each fake app that reaches playback.
 const RUNTIME_PLUGIN_PREFLIGHT_SH = `if [ "$1" = "--ensure-linux-runtime-plugin-assets" ]; then
   data="\${XDG_DATA_HOME:-$HOME/.local/share}/SubMiner"
-  mkdir -p "$data/plugin/subminer" "$data/themes"
+  mkdir -p "$data/plugin/subminer" "$data/themes" "$data/thumbnailers"
   printf -- '-- test plugin\\n' > "$data/plugin/subminer/main.lua"
   printf 'test=true\\n' > "$data/plugin/subminer.conf"
   printf '/* test theme */\\n' > "$data/themes/subminer.rasi"
+  printf '[Thumbnailer Entry]\\n' > "$data/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"
   if [ "$2" = "--ensure-linux-runtime-plugin-assets-response-path" ] && [ -n "$3" ]; then
     mkdir -p "$(dirname "$3")"
     printf '{"ok":true,"status":"installed","path":"%s"}' "$data/plugin/subminer/main.lua" > "$3"

launcher/picker.test.ts

@@ -3,7 +3,12 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { findRofiTheme, formatRofiPrompt } from './picker';
+import {
+  findRofiTheme,
+  findRofiThumbnailerDataRoot,
+  formatRofiPrompt,
+  prependXdgDataDir,
+} from './picker';
 
 // ── formatRofiPrompt: spacing between prompt and input field ──────────────────
 
@@ -23,6 +28,7 @@ test('formatRofiPrompt leaves an empty prompt empty', () => {
 // ── findRofiTheme: Linux packaged path discovery ──────────────────────────────
 
 const ROFI_THEME_FILE = 'subminer.rasi';
+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';
 
 function makeFile(filePath: string): void {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -121,3 +127,42 @@ test('findRofiTheme resolves ~/.local/share/SubMiner/themes/subminer.rasi when X
     fs.rmSync(baseDir, { recursive: true, force: true });
   }
 });
+
+test('findRofiThumbnailerDataRoot resolves the managed XDG data root', () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-test-xdg-'));
+  const originalXdgDataHome = process.env.XDG_DATA_HOME;
+  try {
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    const dataRoot = path.join(xdgDataHome, 'SubMiner');
+    makeFile(path.join(dataRoot, 'thumbnailers', ROFI_THUMBNAILER_FILE));
+
+    const result = withPlatform('linux', () => findRofiThumbnailerDataRoot('/usr/bin/subminer'));
+    assert.equal(result, dataRoot);
+  } finally {
+    if (originalXdgDataHome === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = originalXdgDataHome;
+    }
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+  }
+});
+
+test('findRofiThumbnailerDataRoot is Linux-only', () => {
+  assert.equal(
+    withPlatform('darwin', () => findRofiThumbnailerDataRoot('/usr/bin/subminer')),
+    null,
+  );
+});
+
+test('prependXdgDataDir preserves existing roots and avoids duplicates', () => {
+  const root = '/tmp/subminer-data';
+  assert.equal(
+    prependXdgDataDir(root, `/opt/share${path.delimiter}${root}${path.delimiter}/usr/share`),
+    `${root}${path.delimiter}/opt/share${path.delimiter}/usr/share`,
+  );
+  assert.equal(
+    prependXdgDataDir(root),
+    `${root}${path.delimiter}/usr/local/share${path.delimiter}/usr/share`,
+  );
+});

launcher/picker.ts

@@ -159,6 +159,9 @@ interface RofiIconEntry {
   iconPath?: string;
 }
 
+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';
+const DEFAULT_XDG_DATA_DIRS = ['/usr/local/share', '/usr/share'];
+
 function showRofiIconMenu(
   entries: RofiIconEntry[],
   prompt: string,
@@ -389,6 +392,47 @@ export function findRofiTheme(scriptPath: string): string | null {
   return null;
 }
 
+export function findRofiThumbnailerDataRoot(scriptPath: string): string | null {
+  if (process.platform !== 'linux') return null;
+
+  const scriptDir = path.dirname(realpathMaybe(scriptPath));
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local/share');
+  const roots = [
+    path.join(xdgDataHome, 'SubMiner'),
+    path.posix.join('/usr/local/share/SubMiner'),
+    path.posix.join('/usr/share/SubMiner'),
+    path.join(scriptDir, 'assets'),
+    path.join(scriptDir, '..', 'assets'),
+  ];
+
+  for (const root of roots) {
+    if (fs.existsSync(path.join(root, 'thumbnailers', ROFI_THUMBNAILER_FILE))) {
+      return root;
+    }
+  }
+
+  return null;
+}
+
+export function prependXdgDataDir(dataRoot: string, currentValue?: string): string {
+  const currentDirs = currentValue
+    ? currentValue.split(path.delimiter).filter(Boolean)
+    : DEFAULT_XDG_DATA_DIRS;
+  return [dataRoot, ...currentDirs.filter((candidate) => candidate !== dataRoot)].join(
+    path.delimiter,
+  );
+}
+
+function buildRofiThumbnailEnvironment(scriptPath: string): NodeJS.ProcessEnv {
+  if (!commandExists('ffmpegthumbnailer')) return process.env;
+  const dataRoot = findRofiThumbnailerDataRoot(scriptPath);
+  if (!dataRoot) return process.env;
+  return {
+    ...process.env,
+    XDG_DATA_DIRS: prependXdgDataDir(dataRoot, process.env.XDG_DATA_DIRS),
+  };
+}
+
 export function showRofiMenu(
   videos: string[],
   dir: string,
@@ -420,6 +464,7 @@ export function showRofiMenu(
   const result = spawnSync('rofi', args, {
     input: buildRofiMenu(videos, dir, recursive),
     encoding: 'utf8',
+    env: buildRofiThumbnailEnvironment(scriptPath),
     stdio: ['pipe', 'pipe', 'ignore'],
   });
   if (result.error) {

launcher/runtime-plugin-preflight.test.ts

@@ -1,6 +1,8 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import {
   ensureLinuxRuntimePluginAvailable,
   installManagedPluginAssetsViaApp,
@@ -31,7 +33,7 @@ test('ensureLinuxRuntimePluginAvailable is a no-op on non-Linux platforms', asyn
   assert.deepEqual(calls, []);
 });
 
-test('ensureLinuxRuntimePluginAvailable skips install when installed global plugin and managed theme exist', async () => {
+test('ensureLinuxRuntimePluginAvailable skips install when plugin, theme, and thumbnailer exist', async () => {
   const calls: string[] = [];
 
   await ensureLinuxRuntimePluginAvailable({
@@ -52,13 +54,17 @@ test('ensureLinuxRuntimePluginAvailable skips install when installed global plug
       calls.push('theme');
       return true;
     },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
+    },
     log: () => {},
   });
 
-  assert.deepEqual(calls, ['detect', 'theme']);
+  assert.deepEqual(calls, ['detect', 'theme', 'thumbnailer']);
 });
 
-test('ensureLinuxRuntimePluginAvailable skips install when managed runtime path and theme already resolve', async () => {
+test('ensureLinuxRuntimePluginAvailable skips install when all managed assets resolve', async () => {
   const calls: string[] = [];
 
   await ensureLinuxRuntimePluginAvailable({
@@ -80,14 +86,19 @@ test('ensureLinuxRuntimePluginAvailable skips install when managed runtime path
       calls.push('theme');
       return true;
     },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
+    },
     log: () => {},
   });
 
-  assert.deepEqual(calls, ['detect', 'resolve', 'theme']);
+  assert.deepEqual(calls, ['detect', 'resolve', 'theme', 'thumbnailer']);
 });
 
 test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme is missing', async () => {
   const calls: string[] = [];
+  let themeAvailable = false;
 
   await ensureLinuxRuntimePluginAvailable({
     platform: 'linux',
@@ -102,10 +113,15 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme
     },
     isManagedThemeAvailable: () => {
       calls.push('theme');
-      return false;
+      return themeAvailable;
+    },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
     },
     installManagedPluginAssets: async () => {
       calls.push('install');
+      themeAvailable = true;
       return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
     },
     log: (level, _configured, message) => {
@@ -117,13 +133,68 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme
     'detect',
     'resolve',
     'theme',
-    'info:Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
     'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi',
+    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
     'resolve',
+    'theme',
+    'thumbnailer',
   ]);
 });
 
+test('ensureLinuxRuntimePluginAvailable installs managed assets when thumbnailer is missing', async () => {
+  const calls: string[] = [];
+  let thumbnailerAvailable = false;
+
+  await ensureLinuxRuntimePluginAvailable({
+    platform: 'linux',
+    xdgDataHome: '/tmp/xdg-data',
+    detectInstalledPlugin: () => true,
+    resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
+    installManagedPluginAssets: async () => {
+      calls.push('install');
+      thumbnailerAvailable = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
+    log: (_level, _configured, message) => {
+      calls.push(message);
+    },
+  });
+
+  assert.deepEqual(calls, [
+    'Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
+    'install',
+    'Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
+  ]);
+});
+
+test('ensureLinuxRuntimePluginAvailable retains an installed plugin after installing support assets', async () => {
+  const calls: string[] = [];
+  let thumbnailerAvailable = false;
+
+  await ensureLinuxRuntimePluginAvailable({
+    platform: 'linux',
+    xdgDataHome: '/tmp/xdg-data',
+    detectInstalledPlugin: () => true,
+    resolveRuntimePluginPath: () => {
+      calls.push('resolve');
+      return null;
+    },
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
+    installManagedPluginAssets: async () => {
+      calls.push('install');
+      thumbnailerAvailable = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
+    log: () => {},
+  });
+
+  assert.deepEqual(calls, ['install']);
+});
+
 test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves plugin path', async () => {
   const calls: string[] = [];
   let resolveCount = 0;
@@ -137,6 +208,8 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves
       calls.push(`resolve:${resolveCount}`);
       return resolveCount === 1 ? null : '/tmp/plugin/main.lua';
     },
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => true,
     installManagedPluginAssets: async () => {
       calls.push('install');
       return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
@@ -148,9 +221,9 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves
 
   assert.deepEqual(calls, [
     'resolve:1',
-    'info:Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
     'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi',
+    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
     'resolve:2',
   ]);
 });
@@ -191,6 +264,60 @@ test('ensureLinuxRuntimePluginAvailable fails when runtime path remains unresolv
   );
 });
 
+test('ensureLinuxRuntimePluginAvailable fails when thumbnailer remains missing after install', async () => {
+  await assert.rejects(
+    () =>
+      ensureLinuxRuntimePluginAvailable({
+        platform: 'linux',
+        xdgDataHome: '/tmp/xdg-data',
+        detectInstalledPlugin: () => true,
+        resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
+        isManagedThemeAvailable: () => true,
+        isManagedThumbnailerAvailable: () => false,
+        installManagedPluginAssets: async () => ({
+          ok: true,
+          status: 'installed',
+          path: '/tmp/plugin/main.lua',
+        }),
+        log: () => {},
+      }),
+    /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
+  );
+});
+
+test('ensureLinuxRuntimePluginAvailable rejects a thumbnailer directory before and after install', async () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-thumbnailer-directory-'));
+  const thumbnailerPath = path.join(
+    xdgDataHome,
+    'SubMiner',
+    'thumbnailers',
+    'subminer-ffmpegthumbnailer.thumbnailer',
+  );
+  fs.mkdirSync(thumbnailerPath, { recursive: true });
+  const calls: string[] = [];
+
+  try {
+    await assert.rejects(
+      () =>
+        ensureLinuxRuntimePluginAvailable({
+          platform: 'linux',
+          xdgDataHome,
+          detectInstalledPlugin: () => true,
+          isManagedThemeAvailable: () => true,
+          installManagedPluginAssets: async () => {
+            calls.push('install');
+            return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+          },
+          log: () => {},
+        }),
+      /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
+    );
+    assert.deepEqual(calls, ['install']);
+  } finally {
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+  }
+});
+
 test('installManagedPluginAssetsViaApp returns launch errors without waiting for a response file', async () => {
   let waited = false;
 

launcher/runtime-plugin-preflight.ts

@@ -31,6 +31,7 @@ type EnsureLinuxRuntimePluginAvailableOptions = {
   detectInstalledPlugin?: () => boolean;
   resolveRuntimePluginPath?: () => string | null;
   isManagedThemeAvailable?: () => boolean;
+  isManagedThumbnailerAvailable?: () => boolean;
   installManagedPluginAssets?: () => Promise<EnsureLinuxRuntimePluginAssetsResult>;
   log?: PreflightLog;
 };
@@ -48,6 +49,14 @@ function resolveConfiguredLogLevel(
   return logLevel ?? 'warn';
 }
 
+function isRegularFile(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
 async function waitForInstallResponse(
   responsePath: string,
 ): Promise<RuntimePluginPreflightResponse | null> {
@@ -170,15 +179,17 @@ export async function ensureLinuxRuntimePluginAvailable(
     });
   const isManagedThemeAvailable =
     options.isManagedThemeAvailable ?? (() => fs.existsSync(managedPaths.themePath));
+  const isManagedThumbnailerAvailable =
+    options.isManagedThumbnailerAvailable ?? (() => isRegularFile(managedPaths.thumbnailerPath));
   const runtimePluginAvailable = installedPluginAvailable || Boolean(resolveRuntimePluginPath());
-  if (runtimePluginAvailable && isManagedThemeAvailable()) {
+  if (runtimePluginAvailable && isManagedThemeAvailable() && isManagedThumbnailerAvailable()) {
     return;
   }
 
   log(
     'info',
     configuredLogLevel,
-    'Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
   );
   const installManagedPluginAssets =
     options.installManagedPluginAssets ??
@@ -207,16 +218,21 @@ export async function ensureLinuxRuntimePluginAvailable(
   log(
     'info',
     configuredLogLevel,
-    `Managed Linux runtime support assets installed: plugin=${installResult.path ?? 'unknown path'} theme=${managedPaths.themePath}`,
+    `Managed Linux runtime support assets installed: plugin=${installResult.path ?? 'unknown path'} theme=${managedPaths.themePath} thumbnailer=${managedPaths.thumbnailerPath}`,
   );
-  const runtimePluginPath = resolveRuntimePluginPath();
-  if (runtimePluginPath) {
+  const runtimePluginAvailableAfterInstall =
+    installedPluginAvailable || Boolean(resolveRuntimePluginPath());
+  if (
+    runtimePluginAvailableAfterInstall &&
+    isManagedThemeAvailable() &&
+    isManagedThumbnailerAvailable()
+  ) {
     return;
   }
 
   const message =
     `Linux managed runtime plugin assets could not be installed. ` +
-    `Checked path: ${managedPaths.pluginEntrypointPath}. ` +
+    `Checked paths: plugin=${managedPaths.pluginEntrypointPath} theme=${managedPaths.themePath} thumbnailer=${managedPaths.thumbnailerPath}. ` +
     'Launch aborted before starting mpv.';
   log('warn', configuredLogLevel, message);
   throw new Error(message);

launcher/smoke.e2e.test.ts

@@ -165,11 +165,14 @@ if (entry.argv.includes('--ensure-linux-runtime-plugin-assets')) {
   const pluginDir = path.join(dataDir, 'plugin', 'subminer');
   const pluginConfigPath = path.join(dataDir, 'plugin', 'subminer.conf');
   const themePath = path.join(dataDir, 'themes', 'subminer.rasi');
+  const thumbnailerPath = path.join(dataDir, 'thumbnailers', 'subminer-ffmpegthumbnailer.thumbnailer');
   fs.mkdirSync(pluginDir, { recursive: true });
   fs.mkdirSync(path.dirname(themePath), { recursive: true });
+  fs.mkdirSync(path.dirname(thumbnailerPath), { recursive: true });
   fs.writeFileSync(path.join(pluginDir, 'main.lua'), '-- smoke plugin\\n');
   fs.writeFileSync(pluginConfigPath, 'smoke=true\\n');
   fs.writeFileSync(themePath, '/* smoke theme */\\n');
+  fs.writeFileSync(thumbnailerPath, '[Thumbnailer Entry]\\n');
   if (responsePath) {
     fs.mkdirSync(path.dirname(responsePath), { recursive: true });
     fs.writeFileSync(responsePath, JSON.stringify({ ok: true, status: 'installed', path: path.join(pluginDir, 'main.lua') }));
@@ -620,11 +623,22 @@ test(
       );
       assert.match(result.stdout, /pause mpv until overlay and tokenization are ready/i);
       if (process.platform === 'linux') {
-        assert.match(result.stdout, /managed plugin\/theme assets/i);
+        assert.match(result.stdout, /managed plugin\/theme\/thumbnailer assets/i);
         assert.equal(
           fs.existsSync(path.join(smokeCase.xdgDataHome, 'SubMiner', 'themes', 'subminer.rasi')),
           true,
         );
+        assert.equal(
+          fs.existsSync(
+            path.join(
+              smokeCase.xdgDataHome,
+              'SubMiner',
+              'thumbnailers',
+              'subminer-ffmpegthumbnailer.thumbnailer',
+            ),
+          ),
+          true,
+        );
       }
     });
   },

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

@@ -18,6 +18,9 @@ export function createImmersionDbFixture(dbPath: string): void {
     db.prepare(
       `INSERT INTO imm_rollup_state(state_key, state_value) VALUES ('last_rollup_sample_ms', 0)`,
     ).run();
+    db.prepare(
+      `INSERT INTO imm_rollup_state(state_key, state_value) VALUES ('lexical_daily_rollups_version', 0)`,
+    ).run();
     db.prepare(
       `INSERT INTO imm_lifetime_global(global_id, CREATED_DATE, LAST_UPDATE_DATE) VALUES (1, ?, ?)`,
     ).run(String(Date.now()), String(Date.now()));

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

@@ -108,6 +108,36 @@ test('fixture schema stays aligned with production sync-touched tables and index
   }
 });
 
+test('fixture leaves lexical rollups pending when their table is absent', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-fixture-rollup-state-'));
+  const fixturePath = path.join(dir, 'fixture.sqlite');
+  try {
+    createImmersionDbFixture(fixturePath);
+    const db = new BunDatabase(fixturePath, { readonly: true });
+    try {
+      const state = db
+        .query<{ state_value: string }>(
+          `SELECT state_value FROM imm_rollup_state
+           WHERE state_key = 'lexical_daily_rollups_version'`,
+        )
+        .get();
+      const rollupTable = db
+        .query<{ name: string }>(
+          `SELECT name FROM sqlite_schema
+           WHERE type = 'table' AND name = 'imm_lexical_daily_rollups'`,
+        )
+        .get();
+
+      assert.equal(state?.state_value, '0');
+      assert.equal(rollupTable, null);
+    } finally {
+      db.close();
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('fixture session inserts enforce foreign keys', () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-fixture-foreign-keys-'));
   const fixturePath = path.join(dir, 'fixture.sqlite');

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

@@ -154,6 +154,7 @@ export const IMMERSION_DB_FIXTURE_DDL = `
     last_seen REAL,
     frequency INTEGER,
     frequency_rank INTEGER,
+    vocabulary_visible INTEGER NOT NULL DEFAULT 1 CHECK(vocabulary_visible IN (0, 1)),
     UNIQUE(headword, word, reading)
   );
   CREATE TABLE imm_kanji(

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.19.3",
+  "version": "0.19.4-beta.2",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",

packaging/aur/subminer-bin/PKGBUILD

@@ -58,6 +58,8 @@ package() {
 		"${pkgdir}/usr/share/SubMiner/plugin/subminer.conf"
 	install -Dm644 "${srcdir}/assets/themes/subminer.rasi" \
 		"${pkgdir}/usr/share/SubMiner/themes/subminer.rasi"
+	install -Dm644 "${srcdir}/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer" \
+		"${pkgdir}/usr/share/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"
 
 	install -dm755 "${pkgdir}/usr/share/SubMiner/plugin/subminer"
 	cp -a "${srcdir}/plugin/subminer/." "${pkgdir}/usr/share/SubMiner/plugin/subminer/"

plugin/subminer/hover.lua

@@ -106,9 +106,12 @@ function M.create(ctx)
 
 	local function get_subtitle_ass_property()
 		local ass_text = mp.get_property("sub-text/ass")
+		if ass_text ~= nil then
 			if type(ass_text) == "string" and ass_text ~= "" then
 				return ass_text
 			end
+			return nil
+		end
 		ass_text = mp.get_property("sub-text-ass")
 		if type(ass_text) == "string" and ass_text ~= "" then
 			return ass_text

plugin/subminer/process.lua

@@ -7,6 +7,8 @@ local OVERLAY_RESTART_PING_MAX_ATTEMPTS = 20
 local OVERLAY_LOADING_OSD_PREFIX = "Overlay loading "
 local OVERLAY_LOADING_OSD_FRAMES = { "|", "/", "-", "\\" }
 local OVERLAY_LOADING_OSD_REFRESH_SECONDS = 0.18
+local OVERLAY_LOADING_OSD_DEADLINE_SECONDS = 30
+local OVERLAY_LOADING_OSD_TIMEOUT_MESSAGE = "Overlay did not become ready; check SubMiner logs"
 local AUTO_PLAY_READY_LOADING_OSD = "Loading subtitle tokenization..."
 local AUTO_PLAY_READY_READY_OSD = "Subtitle tokenization ready"
 local DEFAULT_AUTO_PLAY_READY_TIMEOUT_SECONDS = 30
@@ -265,10 +267,19 @@ function M.create(ctx)
 		state.overlay_loading_osd_timer = nil
 	end
 
+	local function clear_overlay_loading_osd_deadline()
+		local timeout = state.overlay_loading_osd_deadline
+		if timeout and timeout.kill then
+			timeout:kill()
+		end
+		state.overlay_loading_osd_deadline = nil
+	end
+
 	local function stop_overlay_loading_osd()
 		state.overlay_loading_osd_active = false
 		state.overlay_loading_osd_frame = 1
 		clear_overlay_loading_osd_timer()
+		clear_overlay_loading_osd_deadline()
 	end
 
 	local function start_overlay_loading_osd()
@@ -291,6 +302,21 @@ function M.create(ctx)
 				end
 			end)
 		end
+		if type(mp.add_timeout) == "function" then
+			state.overlay_loading_osd_deadline = mp.add_timeout(OVERLAY_LOADING_OSD_DEADLINE_SECONDS, function()
+				if not state.overlay_loading_osd_active then
+					return
+				end
+				state.overlay_loading_osd_deadline = nil
+				stop_overlay_loading_osd()
+				subminer_log(
+					"warn",
+					"process",
+					"Overlay loading deadline expired before the app reported content ready"
+				)
+				show_osd(OVERLAY_LOADING_OSD_TIMEOUT_MESSAGE, { force = true })
+			end)
+		end
 	end
 
 	local function disarm_auto_play_ready_gate(options)

plugin/subminer/session_bindings.lua

@@ -232,7 +232,7 @@ function M.create(ctx)
 		elseif action_id == "triggerFieldGrouping" then
 			return { "--trigger-field-grouping" }
 		elseif action_id == "triggerSubsync" then
-			return { "--trigger-subsync" }
+			return { "--session-action", '{"actionId":"triggerSubsync"}' }
 		elseif action_id == "mineSentence" then
 			return { "--mine-sentence" }
 		elseif action_id == "mineSentenceMultiple" then
@@ -251,7 +251,7 @@ function M.create(ctx)
 		elseif action_id == "markWatched" then
 			return { "--mark-watched" }
 		elseif action_id == "openRuntimeOptions" then
-			return { "--open-runtime-options" }
+			return { "--session-action", '{"actionId":"openRuntimeOptions"}' }
 		elseif action_id == "openJimaku" then
 			return { "--open-jimaku" }
 		elseif action_id == "openTsukihime" or action_id == "openAnimetosho" then
@@ -259,7 +259,7 @@ function M.create(ctx)
 		elseif action_id == "openYoutubePicker" then
 			return { "--open-youtube-picker" }
 		elseif action_id == "openSessionHelp" then
-			return { "--open-session-help" }
+			return { "--session-action", '{"actionId":"openSessionHelp"}' }
 		elseif action_id == "openCharacterDictionaryManager" then
 			return { "--session-action", '{"actionId":"openCharacterDictionaryManager"}' }
 		elseif action_id == "openControllerSelect" then

plugin/subminer/state.lua

@@ -26,6 +26,7 @@ function M.new()
 		auto_play_ready_initial_pause_ownership_consumed = false,
 		overlay_loading_osd_active = false,
 		overlay_loading_osd_timer = nil,
+		overlay_loading_osd_deadline = nil,
 		overlay_loading_osd_frame = 1,
 		pending_visible_overlay_hide_timer = nil,
 		pending_visible_overlay_hide_generation = 0,

plugin/subminer/ui.lua

@@ -4,6 +4,7 @@ function M.create(ctx)
 	local mp = ctx.mp
 	local input = ctx.input
 	local process = ctx.process
+	local state = ctx.state
 	local subminer_log = ctx.log.subminer_log
 	local show_osd = ctx.log.show_osd
 
@@ -93,7 +94,18 @@ function M.create(ctx)
 			if not ensure_binary_for_menu() then
 				return
 			end
-			process.run_control_command_async("open-session-help")
+			process.run_binary_command_async({
+				state.binary_path,
+				"--session-action",
+				'{"actionId":"openSessionHelp"}',
+			}, function(ok, result, error)
+				if ok then
+					return
+				end
+				local reason = error or (result and result.stderr) or "unknown error"
+				subminer_log("warn", "session-bindings", "Session action failed: " .. tostring(reason))
+				show_osd("Session action failed")
+			end)
 		end)
 	end
 

release/prerelease-notes.md

@@ -1,80 +1,65 @@
 > This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.
 
-<!-- prerelease-base-version: 0.19.0 -->
+<!-- prerelease-base-version: 0.19.4 -->
 
 ## Highlights
 ### Added
 
-- **Sync Stats & History**
-  - New **Sync Stats & History** window (tray menu) and `subminer sync <host>` command keep mining stats and watch history in sync between machines over SSH, with saved devices, per-host sync direction, and live stage-by-stage progress.
-  - Merges are safe to repeat: data combines without duplicates, and hosts with auto-sync enabled sync automatically in the background on a schedule, reporting results as overlay notifications.
-  - Manual snapshot tools (create, merge, reveal, delete) and connection testing cover one-off transfers; Windows machines running the built-in OpenSSH Server work as sync remotes too, with no setup needed beyond SSH access. Power users can script transfers directly with `--push`/`--pull`, `--check`, `--snapshot`/`--merge`, and `--json` flags.
+- Library Merge & Reassignment
+  - Duplicate library entries for the same show can now be merged: pick entries in "Select" mode and use "Merge Selected" to combine sessions, mined cards, and watch time onto one card.
+  - Episodes can be moved to a different library entry with a per-episode "→" button, fixing cases where a stray filename split off its own entry; manual assignments now survive later filename parsing, Jellyfin refreshes, and season repair.
+  - Exact AniList matches with compatible seasons now merge automatically, and likely (fuzzy) matches surface as a dismissible "Possible duplicate" suggestion instead of merging silently.
 
-- **TsukiHime Subtitle Downloads**
-  - Download Japanese and secondary-language subtitles for the current video directly from TsukiHime, mirroring the existing Jimaku flow.
-  - Press `Ctrl+Shift+T` to search by tabs for the primary and secondary languages; the matching release is found automatically from the video filename and loads straight into mpv, no API key required.
-
-- **Post-Playback History Menu**
-  - After a watch-history episode ends or mpv closes, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit SubMiner.
-  - Previous/Next continue across season directories, so you can binge a show without manually browsing folders.
-  - The menu shown right after picking a series from `subminer -H` now offers the previous episode too, matching the post-playback menu.
-
-- **Known-Word Highlighting by Anki Maturity**
-  - Subtitle highlights for known words can now be colored by Anki card maturity (new, learning, young, mature), similar to asbplayer. Enable it with `ankiConnect.knownWords.maturityEnabled`, or toggle it live during a session.
-  - The mature-interval threshold and the four tier colors are configurable, and the in-session help legend shows the active tier colors while maturity highlighting is on.
-  - Tiers follow Anki's own card state: a lapsed card correctly shows as learning rather than young, and a note is treated as mature if any of its cards are mature. Stats and other known-word tools stay accurate with this new data.
-
-- **Stats Library Entry Deletion**
-  - Added a "Delete Entry" action in the stats Library detail view that removes an entire title in one step: every episode, session, subtitle line, rollup, cover, and vocabulary count derived from it. Previously a mistaken entry had to be cleared episode by episode and still lingered in the Library.
-  - Delete progress (session, session group, episode, or full entry) now shows app-wide as a progress bar plus a status toast, staying visible across tabs and windows instead of disappearing when you switch away.
-  - Deletes are dramatically faster on large libraries, and opening the Vocabulary tab no longer stalls; the first launch after upgrading migrates the stats database in place to support this.
-
-### Changed
-
-- **Clipboard-Video Shortcut**
-  - The "append clipboard video to queue" shortcut is now configurable via `shortcuts.appendClipboardVideoToQueue` instead of being fixed.
+- Duplicate Line Cleanup
+  - The Vocabulary tab's new **Duplicates** button scans a chosen time window for the repeated-line bursts described under Fixed below and collapses each burst to a single line once you confirm it; a matching `subminer stats cleanup --duplicate-lines` command (with `--dry-run` and `--lookback-days <n>`) is available from the terminal.
+  - Only the affected subtitle lines and the vocabulary counts they inflated are touched; watch time and lines-seen totals are left as recorded.
 
 ### Fixed
 
-- **Word Highlighting Accuracy**
-  - Fixed several incorrect word highlighting and annotation cases: inconsistent part-of-speech exclusions on merged quote-particle tokens, missing annotations for rare kanji, katakana punctuation wrongly treated as non-kana noise, and certain kanji vocabulary skipped for next-level ("N+1") highlighting.
+- Subtitle Duplication from Karaoke & Animated Signs
+  - Typeset ASS karaoke and animated signs no longer flood the overlay, subtitle sidebar, immersion history, mined cards, or stats with repeated glyph fragments or per-frame duplicates; the complete authored line is recovered instead, without merging genuinely repeated dialogue or separately positioned signs.
+  - The secondary overlay now shares the same deduplication logic as the primary overlay, so layered animation text no longer appears multiple times there or in what gets mined.
+  - Vocabulary stats no longer count every animation frame of a karaoke opening as a separate line, which previously could push an OP lyric to the top of "Top Repeated Words."
 
-- **AniList Season Resolution**
-  - Season 2 and later episodes now resolve to the correct AniList entry by walking sequel relations instead of guessing from the title, so watch progress, the character dictionary, and cover art for later seasons no longer silently fall back to season 1.
-  - Manual AniList overrides now stay in effect for every episode in the same season (by folder and detected season), and setting an override now fixes both the character dictionary and AniList watch progress together instead of needing separate corrections.
+- Anki Media Generation
+  - Sentence-audio generation no longer times out on slow network-mounted video files with many subtitle and font streams, and a failed extraction now reports a clear error instead of a raw `ENOENT`.
+  - Mined audio and animated AVIF clips now capture the subtitle line you actually mined, instead of whatever line happened to be on screen once slow audio extraction finished.
 
-- **Startup Playback Pausing Too Early**
-  - Fixed playback resuming before subtitle processing finished warming up, which could briefly show untranslated subtitles right after opening a video.
-  - Most noticeable when resuming mid-episode or when a subtitle cue starts within the first couple of seconds.
+- Character Dictionary Performance & Notifications
+  - Character dictionary generation, merged rebuilds, and imports no longer freeze the app on large dictionaries, and cached results are reused across launches instead of regenerating character data and portraits every time.
+  - Desktop progress notifications, including on Linux AppImage installs, now update in place instead of flickering closed and reopening.
 
-- **Linux AppImage Crash Notification on Quit**
-  - Fixed a spurious "Service Crash" desktop notification appearing after closing a video when running the Linux AppImage.
-  - If needed, the mount-keepalive behavior behind this fix can be disabled with `SUBMINER_NO_APPIMAGE_MOUNT_KEEPALIVE=1`.
+- Overlay Reliability
+  - Overlay modals (settings, stats, etc.) now open promptly on the first shortcut press and appear above fullscreen mpv on macOS instead of switching Spaces or opening off-screen.
+  - The overlay no longer gets stuck on "Overlay loading" indefinitely if mpv's connection stalls; it now retries and shows an actionable error after 30 seconds.
+  - Fixed native Wayland drag-and-drop from file managers like Thunar, so subtitle and video files dropped on the overlay reach mpv.
+  - Fixed system-wide mouse lag on Windows caused by the overlay's click-through handling and repeated mpv window lookups.
 
-- **AnkiConnect Proxy Port Conflict**
-  - Fixed video playback failing to start when another process already held the configured AnkiConnect proxy port; SubMiner now shows a notification explaining how to resolve the conflict instead of crashing.
+- Stats Dashboard
+  - Deletes, library merges, video moves, and AniList reassignments no longer freeze the stats dashboard or rebuild lifetime totals from scratch; large deletes that used to take minutes now finish in milliseconds.
+  - Vocabulary totals and charts now count all tracked vocabulary instead of just the first page, new-word history uses corrected daily rollups, calendar labels respect time zones west of UTC, and vocabulary cards refresh automatically after editing the word exclusion list.
 
-- **Stats & Settings Reliability**
-  - Fixed session stats reporting zero known words after the known-word cache gained maturity tiers.
-  - Hardened the stats server against malformed requests, stalled AniList lookups, media mismatches during word mining, and missing Yomitan connections.
-  - AnkiConnect settings validation now preserves valid custom configurations while safely falling back on invalid values instead of failing.
-
-- **Stats Library Cover After Relink**
-  - Relinking a title to a different AniList entry now updates its cover art in the stats Library grid, not just the detail view, so unrelated titles no longer end up sharing the wrong cover.
-
-- **Rofi Menu Prompt Spacing**
-  - Rofi menu prompts now keep a space between the prompt label and the input field instead of crowding the search placeholder text.
+- Linux Launcher Thumbnails
+  - Fixed missing MKV thumbnails in the Linux rofi picker when the system thumbnailer only registers legacy Matroska MIME aliases.
 
 ## What's Changed
 
-- feat(shortcuts): make clipboard-video-append shortcut configurable by @ksyasuda in #158
-- refactor(tokenizer): extract subtitle annotation filter into rule table by @ksyasuda in #162
-- refactor(tsukihime): swap Animetosho backend for TsukiHime API by @ksyasuda in #165
-- refactor: split anki-connect and stats-server resolvers into modules by @ksyasuda in #169
-- feat(launcher): add post-playback history menu with previous episode by @ksyasuda in #170
-- Anki maturity-based known-word highlighting by @ksyasuda in #172
-- fix(anilist): resolve later seasons via sequel relations, not title guessing by @ksyasuda in #173
-- feat(stats): add library entry deletion and app-wide delete progress by @ksyasuda in #174
+- feat(stats): add library entry merge and episode move by @ksyasuda in #190
+- fix(stats): stop counting duplicate typeset subtitle lines by @ksyasuda in #191
+- fix(media): tolerate slow MKV audio extraction by @ksyasuda in #195
+- fix(stats): subtract lifetime totals incrementally on delete by @ksyasuda in #196
+- fix(anki): snapshot mining media clip timing by @ksyasuda in #197
+- fix(notifications): replace Linux progress updates in place by @ksyasuda in #198
+- fix(overlay): support native Wayland file drag-and-drop by @ksyasuda in #199
+- fix(overlay): keep macOS modal windows on fullscreen Spaces by @ksyasuda in #200
+- fix(overlay): prevent Windows mouse lag during click-through tracking by @ksyasuda in #201
+- fix(stats): report complete vocabulary totals and new-word history by @ksyasuda in #202
+- fix(mpv): recover from stalled IPC connects by @ksyasuda in #204
+- fix(dictionary): prevent freezes and restore AppImage notifications by @ksyasuda in #205
+- fix(subtitles): recover canonical lines from ASS animation by @ksyasuda in #207
+- fix(overlay): deduplicate secondary subtitle rendering by @ksyasuda in #208
+- fix(launcher): restore Matroska thumbnails in Linux rofi picker by @ksyasuda in #210
+- fix(character-dictionary): cache completed MeCab refreshes by @ksyasuda in #212
 
 ## Installation
 

scripts/build-versioned-docs.ts

@@ -35,6 +35,17 @@ const archiveCacheRoot = join(repoRoot, '.tmp/docs-versioned-archive-cache');
 const maxCloudflareFiles = 20_000;
 const maxCloudflareFileBytes = 25 * 1024 * 1024;
 
+// Cloudflare Pages header rules for the whole deployment. Mirrors the `noindex,follow`
+// meta tag the non-root channels emit, so the duplicate trees stay out of the index
+// even for responses a crawler takes without parsing the HTML.
+const deployHeaders = `# Generated by scripts/build-versioned-docs.ts. Do not edit by hand.
+/main/*
+  X-Robots-Tag: noindex, follow
+
+/v/*
+  X-Robots-Tag: noindex, follow
+`;
+
 function run(
   command: string,
   args: string[],
@@ -173,6 +184,7 @@ function buildDocs(options: {
       SUBMINER_DOCS_BASE: options.base,
       SUBMINER_DOCS_OUT_DIR: options.outDir,
       SUBMINER_DOCS_SOURCE_DIR: options.snapshotDocsSite,
+      SUBMINER_DOCS_REPO_DIR: currentDocsSite,
       SUBMINER_DOCS_CHANNEL: options.channel,
       SUBMINER_DOCS_VERSION: options.version ?? '',
       SUBMINER_DOCS_LATEST_STABLE: options.latestStable,
@@ -378,6 +390,7 @@ function main() {
   });
 
   writeFileSync(join(aggregateOutDir, 'versions.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  writeFileSync(join(aggregateOutDir, '_headers'), deployHeaders);
   assertCloudflarePagesLimits(aggregateOutDir);
   const prunedArchives = pruneArchiveCacheGenerations({
     cacheRoot: archiveCacheRoot,

scripts/mkv-to-readme-video.sh

@@ -19,7 +19,8 @@ Options:
   -w, --webp   Generate animated WebP preview
 
 Encoding profile:
-  - Crop: 1920x1080 at x=760 y=200
+  - Crop: mpv region at 1920x1080, x=760 y=205 on a 3440x1440 canvas
+  - Output size: 1920x1080
   - MP4:  H.264 + AAC
   - WebM: AV1/VP9 + Opus at 30 fps
 USAGE
@@ -148,7 +149,8 @@ pick_webp_encoder() {
 	return 1
 }
 
-crop_vf="crop=1920:1080:760:205"
+# OBS may resize the 3440x1440 canvas, so scale the mpv bounds with the input.
+crop_vf="crop=1920*iw/3440:1080*ih/1440:760*iw/3440:205*ih/1440,scale=1920:1080:flags=lanczos"
 webm_vf="${crop_vf},fps=30"
 
 echo "Generating MP4: $mp4_out"

scripts/mkv-to-readme-video.test.ts

@@ -40,7 +40,7 @@ function toBashPath(filePath: string): string {
   return `${drive.toUpperCase()}:/${rest}`;
 }
 
-test('mkv-to-readme-video accepts libwebp_anim when libwebp is unavailable', () => {
+test('mkv-to-readme-video builds every output with the scaled mpv crop', () => {
   withTempDir((root) => {
     const binDir = path.join(root, 'bin');
     const inputPath = path.join(root, 'sample.mkv');
@@ -104,5 +104,9 @@ touch "$output"
 
     const ffmpegLog = fs.readFileSync(ffmpegLogPath, 'utf8');
     assert.match(ffmpegLog, /-c:v libwebp_anim/);
+    const scaledCropUses = ffmpegLog.match(
+      /-vf crop=1920\*iw\/3440:1080\*ih\/1440:760\*iw\/3440:205\*ih\/1440,scale=1920:1080:flags=lanczos/g,
+    );
+    assert.equal(scaledCropUses?.length, 4);
   });
 });

scripts/test-plugin-start-gate.lua

@@ -130,7 +130,9 @@ local function run_plugin_scenario(config)
 
 		function mp.add_timeout(seconds, callback)
 			recorded.timeouts[#recorded.timeouts + 1] = seconds
+			local delay = tonumber(seconds) or 0
 			local timeout = {
+				seconds = delay,
 				killed = false,
 				callback = callback,
 			}
@@ -138,7 +140,6 @@ local function run_plugin_scenario(config)
 				self.killed = true
 			end
 
-			local delay = tonumber(seconds) or 0
 			if callback and delay < 5 and not config.defer_timeouts then
 				callback()
 			end
@@ -514,6 +515,15 @@ local function has_timeout(timeouts, target)
 	return false
 end
 
+local function find_timeout_handle(recorded, target)
+	for _, timeout in ipairs(recorded.timeout_handles) do
+		if math.abs(timeout.seconds - target) < 0.0001 then
+			return timeout
+		end
+	end
+	return nil
+end
+
 local function env_has(call, target)
 	local env = (call and call.env) or {}
 	for _, value in ipairs(env) do
@@ -1636,6 +1646,8 @@ do
 		#recorded.periodic_timers == 1,
 		"auto-start visible overlay should refresh the early overlay loading OSD"
 	)
+	local overlay_loading_deadline = find_timeout_handle(recorded, 30)
+	assert_true(overlay_loading_deadline ~= nil, "overlay loading OSD should have a bounded deadline")
 	local overlay_loading_timer = recorded.periodic_timers[1]
 	recorded.periodic_timers[1].callback()
 	assert_true(
@@ -1670,6 +1682,46 @@ do
 		recorded.periodic_timers[1].killed == true,
 		"overlay loading ready should stop the early overlay loading OSD refresher"
 	)
+	assert_true(
+		overlay_loading_deadline.killed == true,
+		"overlay loading ready should cancel the bounded loading deadline"
+	)
+end
+
+do
+	local recorded, err = run_plugin_scenario({
+		defer_timeouts = true,
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			osd_messages = false,
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		media_title = "Random Movie",
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for overlay loading deadline scenario: " .. tostring(err))
+	fire_event(recorded, "start-file")
+	local overlay_loading_deadline = find_timeout_handle(recorded, 30)
+	assert_true(overlay_loading_deadline ~= nil, "overlay loading deadline should be scheduled")
+	overlay_loading_deadline.callback()
+	assert_true(
+		recorded.periodic_timers[1].killed == true,
+		"overlay loading deadline should stop the loading spinner"
+	)
+	assert_true(
+		has_osd_message(recorded.osd, "SubMiner: Overlay did not become ready; check SubMiner logs"),
+		"overlay loading deadline should replace the spinner with actionable feedback"
+	)
+	assert_true(
+		has_log_containing(recorded.logs, "Overlay loading deadline expired"),
+		"overlay loading deadline should leave a diagnostic log entry"
+	)
 end
 
 do

scripts/update-aur-package.test.ts

@@ -82,6 +82,7 @@ test('update-aur-package updates PKGBUILD and .SRCINFO without makepkg', () => {
       pkgbuild,
       /^\s*install -Dm755 "\$\{srcdir\}\/subminer-\$\{pkgver\}" "\$\{pkgdir\}\/usr\/bin\/subminer"$/m,
     );
+    assert.match(pkgbuild, /assets\/thumbnailers\/subminer-ffmpegthumbnailer\.thumbnailer/);
     assert.match(srcinfo, /^\tpkgver = 0\.6\.3$/m);
     assert.match(srcinfo, /^\tprovides = subminer=0\.6\.3$/m);
     assert.match(

src/anki-integration.ts

@@ -28,8 +28,6 @@ import {
   KikuMergePreviewResponse,
   NotificationOptions,
   type WordCardKind,
-  type MediaTimingReviewDecision,
-  type MediaTimingReviewRequest,
 } from './types/anki';
 import { AiConfig } from './types/integrations';
 import type { KnownWordMaturityTier } from './types/subtitle';
@@ -240,9 +238,6 @@ export class AnkiIntegration {
   private recordCardsMinedCallback: ((count: number, noteIds?: number[]) => void) | null = null;
   private knownWordCacheUpdatedCallback: (() => void) | null = null;
   private consumeSubtitleMiningContextCallback: (() => SubtitleMiningContext | null) | null = null;
-  private mediaTimingReviewCallback:
-    | ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>)
-    | null = null;
   private noteIdRedirects = new Map<number, number>();
   private trackedDuplicateNoteIds = new Map<number, number[]>();
   private getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null =
@@ -514,7 +509,6 @@ export class AnkiIntegration {
         findNotes: async (query, options) =>
           (await this.client.findNotes(query, options)) as number[],
         retrieveMediaFile: (filename) => this.client.retrieveMediaFile(filename),
-        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       mediaGenerator: {
         generateAudio: (
@@ -572,7 +566,6 @@ export class AnkiIntegration {
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       getFallbackDurationSeconds: () => this.getFallbackDurationSeconds(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
-      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       isUpdateInProgress: () => this.updateInProgress,
       setUpdateInProgress: (value) => {
         this.updateInProgress = value;
@@ -588,7 +581,6 @@ export class AnkiIntegration {
       recordCardsMinedCallback: (count, noteIds) => {
         this.recordCardsMinedSafely(count, noteIds, 'card creation');
       },
-      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -645,14 +637,12 @@ export class AnkiIntegration {
         notesInfo: async (noteIds) => (await this.client.notesInfo(noteIds)) as unknown,
         updateNoteFields: (noteId, fields) => this.client.updateNoteFields(noteId, fields),
         storeMediaFile: (filename, data) => this.client.storeMediaFile(filename, data),
-        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       getConfig: () => this.config,
       getCurrentSubtitleText: () => this.mpvClient.currentSubText,
       getCurrentSubtitleStart: () => this.mpvClient.currentSubStart,
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
-      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       extractFields: (fields) => this.extractFields(fields),
       findDuplicateNote: (expression, excludeNoteId, noteInfo) =>
         this.findDuplicateNote(expression, excludeNoteId, noteInfo),
@@ -690,7 +680,6 @@ export class AnkiIntegration {
       logWarn: (...args) => log.warn(args[0] as string, ...args.slice(1)),
       logInfo: (...args) => log.info(args[0] as string, ...args.slice(1)),
       logError: (...args) => log.error(args[0] as string, ...args.slice(1)),
-      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -810,12 +799,6 @@ export class AnkiIntegration {
     }
   }
 
-  private removeKnownWordNote(noteId: number): void {
-    if (this.knownWordCache.removeNote(noteId)) {
-      this.notifyKnownWordCacheUpdated();
-    }
-  }
-
   private notifyKnownWordCacheUpdated(): void {
     if (!this.knownWordCacheUpdatedCallback) {
       return;
@@ -1056,7 +1039,7 @@ export class AnkiIntegration {
       videoPath,
       startTime,
       endTime,
-      context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
+      this.config.media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(videoPath, this.mpvClient.currentAudioStreamIndex),
       this.config.media?.normalizeAudio !== false,
       await this.getMpvVolumeScale(),
@@ -1089,7 +1072,7 @@ export class AnkiIntegration {
         videoPath,
         mediaRange.startTime,
         mediaRange.endTime,
-        context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
+        this.config.media?.audioPadding,
         {
           fps: this.config.media?.animatedFps,
           maxWidth: this.config.media?.animatedMaxWidth,
@@ -1740,25 +1723,6 @@ export class AnkiIntegration {
     this.consumeSubtitleMiningContextCallback = callback;
   }
 
-  setMediaTimingReviewCallback(
-    callback: ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>) | null,
-  ): void {
-    this.mediaTimingReviewCallback = callback;
-  }
-
-  private async reviewMediaTiming(
-    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
-  ): Promise<MediaTimingReviewDecision> {
-    if (this.config.media?.reviewTiming !== true || !this.mediaTimingReviewCallback) {
-      return { action: 'use-original' };
-    }
-    return await this.mediaTimingReviewCallback({
-      ...request,
-      audioPadding: Math.max(0, this.config.media.audioPadding ?? 0),
-      maxMediaDuration: Math.max(0, this.config.media.maxMediaDuration ?? 30),
-    });
-  }
-
   resolveCurrentNoteId(noteId: number): number {
     let resolved = noteId;
     const seen = new Set<number>();

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

@@ -85,7 +85,6 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => Buffer.from('audio'),
@@ -130,7 +129,6 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -203,7 +201,6 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
       storeMediaFile: async () => undefined,
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     getEffectiveSentenceCardConfig: () => ({
       model: 'Sentence',
@@ -251,7 +248,6 @@ test('manual clipboard subtitle update skips audio when sentence audio field is
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
   });
 
@@ -339,7 +335,6 @@ test('manual clipboard subtitle update uses resolved mpv stream URLs for remote
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path) => {
@@ -388,98 +383,3 @@ test('createSentenceCard relies on Anki progress notification without standalone
   assert.deepEqual(progressMessages, ['Creating sentence card']);
   assert.deepEqual(statusMessages, []);
 });
-
-test('discarding an audio-card timing review deletes the note before evicting its cache entry', async () => {
-  const events: string[] = [];
-  const statusMessages: string[] = [];
-  const { service } = createManualUpdateService({
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 4,
-        currentSubEnd: 6,
-        currentTimePos: 5,
-      }) as never,
-    client: {
-      addNote: async () => 0,
-      addTags: async () => undefined,
-      notesInfo: async () => [
-        {
-          noteId: 42,
-          fields: { Expression: { value: '単語' } },
-        },
-      ],
-      updateNoteFields: async () => undefined,
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [42],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async (noteIds) => {
-        events.push(`delete:${noteIds.join(',')}`);
-      },
-    },
-    reviewMediaTiming: async () => ({ action: 'discard' }),
-    removeKnownWordNote: (noteId) => {
-      events.push(`cache:${noteId}`);
-    },
-    showStatusNotification: (message) => {
-      statusMessages.push(message);
-    },
-  });
-
-  await service.markLastCardAsAudioCard();
-
-  assert.deepEqual(events, ['delete:42', 'cache:42']);
-  assert.deepEqual(statusMessages, ['Card deleted.']);
-});
-
-test('keeping an audio card without media skips generation and preserves the note', async () => {
-  let generatedAudio = false;
-  let deleted = false;
-  const updates: Array<{ noteId: number; fields: Record<string, string> }> = [];
-  const { service, storedMedia } = createManualUpdateService({
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 4,
-        currentSubEnd: 6,
-        currentTimePos: 5,
-      }) as never,
-    client: {
-      addNote: async () => 0,
-      addTags: async () => undefined,
-      notesInfo: async () => [
-        {
-          noteId: 42,
-          fields: { Expression: { value: '単語' }, Sentence: { value: '' } },
-        },
-      ],
-      updateNoteFields: async (noteId, fields) => {
-        updates.push({ noteId, fields });
-      },
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [42],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => {
-        deleted = true;
-      },
-    },
-    mediaGenerator: {
-      generateAudio: async () => {
-        generatedAudio = true;
-        return Buffer.from('audio');
-      },
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    reviewMediaTiming: async () => ({ action: 'skip-media' }),
-  });
-
-  await service.markLastCardAsAudioCard();
-
-  assert.equal(generatedAudio, false);
-  assert.equal(deleted, false);
-  assert.deepEqual(storedMedia, []);
-  assert.deepEqual(updates, [{ noteId: 42, fields: { Sentence: '字幕' } }]);
-});

src/anki-integration/card-creation-sentence-media.test.ts

@@ -12,7 +12,6 @@ test('sentence card writes generated audio only to sentence audio field', async
   const storedMedia: string[] = [];
   const requestedProperties: string[] = [];
   const audioVolumeScales: Array<number | undefined> = [];
-  const audioRanges: Array<{ start: number; end: number; padding: number | undefined }> = [];
 
   const deps: CardCreationDeps = {
     getConfig: () =>
@@ -74,19 +73,17 @@ test('sentence card writes generated audio only to sentence audio field', async
       },
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (
         _path,
-        startTime,
-        endTime,
-        audioPadding,
+        _startTime,
+        _endTime,
+        _audioPadding,
         _audioStreamIndex,
         _normalizeAudio,
         volumeScale,
       ) => {
-        audioRanges.push({ start: startTime, end: endTime, padding: audioPadding });
         audioVolumeScales.push(volumeScale);
         return Buffer.from('audio');
       },
@@ -125,15 +122,17 @@ test('sentence card writes generated audio only to sentence audio field', async
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
-    reviewMediaTiming: async () => ({ action: 'confirm', startTime: 11.4, endTime: 14.2 }),
   };
 
-  const service = new CardCreationService(deps);
-  const created = await service.createSentenceCard('字幕', 12, 14, 'Subtitle');
+  const created = await new CardCreationService(deps).createSentenceCard(
+    '字幕',
+    12,
+    14,
+    'Subtitle',
+  );
 
   assert.equal(created, true);
   assert.deepEqual(addedFields[0], {
@@ -145,19 +144,7 @@ test('sentence card writes generated audio only to sentence audio field', async
   assert.equal(storedMedia.length, 1);
   assert.deepEqual(requestedProperties, ['volume']);
   assert.deepEqual(audioVolumeScales, [0.4 ** 3]);
-  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
   const mediaUpdate = updatedFields.find((fields) => 'SentenceAudio' in fields);
   assert.equal(mediaUpdate?.SentenceAudio, `[sound:${storedMedia[0]}]`);
   assert.equal('ExpressionAudio' in mediaUpdate!, false);
-
-  deps.reviewMediaTiming = async () => ({ action: 'discard' });
-  assert.equal(await service.createSentenceCard('作らない', 20, 22), false);
-  assert.equal(addedFields.length, 1);
-
-  deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
-  assert.equal(await service.createSentenceCard('メディアなし', 30, 32), true);
-  assert.equal(addedFields.length, 2);
-  assert.equal(storedMedia.length, 1);
-  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
-  assert.deepEqual(requestedProperties, ['volume']);
 });

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

@@ -42,7 +42,6 @@ test('CardCreationService counts locally created sentence cards', async () => {
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -75,7 +74,6 @@ test('CardCreationService counts locally created sentence cards', async () => {
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -141,7 +139,6 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -176,7 +173,6 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => {
@@ -242,7 +238,6 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -277,7 +272,6 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     recordCardsMinedCallback: () => {
@@ -354,7 +348,6 @@ test('CardCreationService uses stream-open-filename for remote media generation'
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path) => {
@@ -399,7 +392,6 @@ test('CardCreationService uses stream-open-filename for remote media generation'
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -462,7 +454,6 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path, _startTime, _endTime, _padding, audioStreamIndex) => {
@@ -504,7 +495,6 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -600,7 +590,6 @@ test('CardCreationService queues YouTube media when required cache is not ready'
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => {
@@ -645,7 +634,6 @@ test('CardCreationService queues YouTube media when required cache is not ready'
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -713,7 +701,6 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -746,7 +733,6 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -804,7 +790,6 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -837,7 +822,6 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,

src/anki-integration/card-creation.ts

@@ -3,13 +3,7 @@ import {
   getConfiguredWordFieldName,
   getPreferredWordValueFromExtractedFields,
 } from '../anki-field-config';
-import {
-  AnkiConnectConfig,
-  type CardKind,
-  type MediaTimingReviewDecision,
-  type MediaTimingReviewRequest,
-  type WordCardKind,
-} 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';
@@ -61,7 +55,6 @@ interface CardCreationClient {
   storeMediaFile(filename: string, data: Buffer): Promise<void>;
   findNotes(query: string, options?: { maxRetries?: number }): Promise<number[]>;
   retrieveMediaFile(filename: string): Promise<string>;
-  deleteNotes(noteIds: number[]): Promise<void>;
 }
 
 interface CardCreationMediaGenerator {
@@ -145,16 +138,12 @@ interface CardCreationDeps {
   };
   getFallbackDurationSeconds: () => number;
   appendKnownWordsFromNoteInfo: (noteInfo: CardCreationNoteInfo) => void;
-  removeKnownWordNote: (noteId: number) => void;
   isUpdateInProgress: () => boolean;
   setUpdateInProgress: (value: boolean) => void;
   trackLastAddedNoteId?: (noteId: number) => void;
   trackLastAddedDuplicateNoteIds?: (noteId: number, duplicateNoteIds: number[]) => void;
   findDuplicateNoteIds?: (expression: string, noteInfo: CardCreationNoteInfo) => Promise<number[]>;
   recordCardsMinedCallback?: (count: number, noteIds?: number[]) => void;
-  reviewMediaTiming?: (
-    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
-  ) => Promise<MediaTimingReviewDecision>;
 }
 
 export class CardCreationService {
@@ -271,7 +260,6 @@ export class CardCreationService {
           fields,
           this.deps.getConfig(),
         );
-
         const sentenceAudioField = this.getResolvedSentenceOnlyAudioFieldName(noteInfo);
         const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
         const sentenceField = sentenceCardConfig.sentenceField;
@@ -463,28 +451,6 @@ export class CardCreationService {
           this.deps.getConfig(),
         );
 
-        const timingDecision = this.deps.reviewMediaTiming
-          ? await this.deps.reviewMediaTiming({
-              kind: 'audio',
-              text: mpvClient.currentSubText,
-              startTime,
-              endTime,
-              noteId,
-            })
-          : ({ action: 'use-original' } as const);
-        if (timingDecision.action === 'discard') {
-          await this.deps.client.deleteNotes([noteId]);
-          this.deps.removeKnownWordNote(noteId);
-          this.deps.showStatusNotification('Card deleted.');
-          return;
-        }
-        const skipMedia = timingDecision.action === 'skip-media';
-        const exactReviewedRange = timingDecision.action === 'confirm';
-        if (timingDecision.action === 'confirm') {
-          startTime = timingDecision.startTime;
-          endTime = timingDecision.endTime;
-        }
-
         const updatedFields: Record<string, string> = {};
         const errors: string[] = [];
         let miscInfoFilename: string | null = null;
@@ -499,14 +465,12 @@ export class CardCreationService {
 
         const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
         const audioFieldName = sentenceCardConfig.audioField;
-        if (!skipMedia) {
         try {
           const audioFilename = this.generateAudioFilename();
           const audioBuffer = await this.mediaGenerateAudio(
             mpvClient.currentVideoPath,
             startTime,
             endTime,
-              exactReviewedRange ? 0 : undefined,
           );
 
           if (audioBuffer) {
@@ -518,9 +482,8 @@ export class CardCreationService {
           log.error('Failed to generate audio for audio card:', (error as Error).message);
           errors.push('audio');
         }
-        }
 
-        if (!skipMedia && shouldGenerateImage(this.deps.getConfig())) {
+        if (shouldGenerateImage(this.deps.getConfig())) {
           try {
             const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
             const imageFilename = this.generateImageFilename();
@@ -529,7 +492,6 @@ export class CardCreationService {
               startTime,
               endTime,
               animatedLeadInSeconds,
-              exactReviewedRange,
             );
 
             const imageField = this.deps.getConfig().fields?.image;
@@ -602,28 +564,9 @@ export class CardCreationService {
 
     try {
       return await this.deps.withUpdateProgress('Creating sentence card', async () => {
-        const timingDecision = this.deps.reviewMediaTiming
-          ? await this.deps.reviewMediaTiming({
-              kind: 'sentence',
-              text: sentence,
-              startTime,
-              endTime,
-            })
-          : ({ action: 'use-original' } as const);
-        if (timingDecision.action === 'discard') {
-          this.deps.showStatusNotification('Card creation cancelled.');
-          return false;
-        }
-        const skipMedia = timingDecision.action === 'skip-media';
-        const exactReviewedRange = timingDecision.action === 'confirm';
-        if (timingDecision.action === 'confirm') {
-          startTime = timingDecision.startTime;
-          endTime = timingDecision.endTime;
-        }
-
         const config = this.deps.getConfig();
-        const generateAudio = !skipMedia && shouldGenerateAudio(config);
-        const generateImage = !skipMedia && shouldGenerateImage(config);
+        const generateAudio = shouldGenerateAudio(config);
+        const generateImage = shouldGenerateImage(config);
         const mediaResolverOptions = this.getMediaResolverOptions();
         const videoPath = generateImage
           ? await resolveMediaGenerationInput(mpvClient, 'video', mediaResolverOptions)
@@ -789,7 +732,6 @@ export class CardCreationService {
             generateAudio,
             generateImage,
             volumeScale,
-            ...(exactReviewedRange ? { mediaPaddingSeconds: 0 } : {}),
           });
           await this.deps.showNotification(noteId, label, 'media queued');
           return true;
@@ -805,12 +747,7 @@ export class CardCreationService {
           try {
             const audioFilename = this.generateAudioFilename();
             const audioBuffer = audioSourcePath
-              ? await this.mediaGenerateAudio(
-                  audioSourcePath,
-                  startTime,
-                  endTime,
-                  exactReviewedRange ? 0 : undefined,
-                )
+              ? await this.mediaGenerateAudio(audioSourcePath, startTime, endTime)
               : null;
 
             if (audioBuffer) {
@@ -828,13 +765,7 @@ export class CardCreationService {
         if (generateImage) {
           try {
             const imageFilename = this.generateImageFilename();
-            const imageBuffer = await this.generateImageBuffer(
-              videoPath!,
-              startTime,
-              endTime,
-              0,
-              exactReviewedRange,
-            );
+            const imageBuffer = await this.generateImageBuffer(videoPath!, startTime, endTime);
 
             const imageField = config.fields?.image;
             if (imageBuffer && imageField) {
@@ -902,7 +833,6 @@ export class CardCreationService {
     videoPath: MediaInput,
     startTime: number,
     endTime: number,
-    audioPaddingOverride?: number,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
@@ -913,7 +843,7 @@ export class CardCreationService {
       videoPath,
       startTime,
       endTime,
-      audioPaddingOverride ?? this.deps.getConfig().media?.audioPadding,
+      this.deps.getConfig().media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(
         videoPath,
         mpvClient.currentAudioStreamIndex ?? undefined,
@@ -931,16 +861,13 @@ export class CardCreationService {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
-    exactReviewedRange = false,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
       return null;
     }
 
-    const timestamp = exactReviewedRange
-      ? startTime + (endTime - startTime) / 2
-      : mpvClient.currentTimePos || 0;
+    const timestamp = mpvClient.currentTimePos || 0;
 
     if (this.deps.getConfig().media?.imageType === 'avif') {
       let imageStart = startTime;
@@ -956,7 +883,7 @@ export class CardCreationService {
         videoPath,
         imageStart,
         imageEnd,
-        exactReviewedRange ? 0 : this.deps.getConfig().media?.audioPadding,
+        this.deps.getConfig().media?.audioPadding,
         {
           fps: this.deps.getConfig().media?.animatedFps,
           maxWidth: this.deps.getConfig().media?.animatedMaxWidth,

src/anki-integration/known-word-cache.test.ts

@@ -261,32 +261,6 @@ test('KnownWordCacheManager invalidates persisted cache when fields.word changes
   }
 });
 
-test('KnownWordCacheManager removes a deleted note from memory and persisted state', () => {
-  const config: AnkiConnectConfig = {
-    fields: { word: 'Word' },
-    knownWords: { highlightEnabled: true },
-  };
-  const { manager, statePath, cleanup } = createKnownWordCacheHarness(config);
-
-  try {
-    manager.appendFromNoteInfo({
-      noteId: 42,
-      fields: { Word: { value: '猫' } },
-    });
-
-    assert.equal(manager.removeNote(42), true);
-    assert.equal(manager.removeNote(42), false);
-    assert.equal(manager.isKnownWord('猫'), false);
-
-    const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
-      notes?: Record<string, unknown>;
-    };
-    assert.deepEqual(persisted.notes, {});
-  } finally {
-    cleanup();
-  }
-});
-
 test('KnownWordCacheManager refresh incrementally reconciles deleted and edited note words', async () => {
   const config: AnkiConnectConfig = {
     fields: {

src/anki-integration/known-word-cache.ts

@@ -350,17 +350,6 @@ export class KnownWordCacheManager {
     return true;
   }
 
-  removeNote(noteId: number): boolean {
-    if (!this.noteEntriesById.has(noteId)) {
-      return false;
-    }
-
-    this.removeNoteSnapshot(noteId);
-    this.persistKnownWordCacheState();
-    log.info('Known-word cache removed deleted note', `noteId=${noteId}`);
-    return true;
-  }
-
   clearKnownWordCacheState(): void {
     this.clearInMemoryState();
     this.knownWordsStateKey = this.getKnownWordCacheStateKey();

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

@@ -44,7 +44,6 @@ function createWorkflowHarness() {
         updates.push({ noteId, fields });
       },
       storeMediaFile: async () => undefined,
-      deleteNotes: async () => undefined,
     },
     getConfig: () => ({
       fields: {
@@ -62,7 +61,6 @@ function createWorkflowHarness() {
       kikuFieldGrouping: 'disabled' as const,
     }),
     appendKnownWordsFromNoteInfo: (_noteInfo: NoteUpdateWorkflowNoteInfo) => undefined,
-    removeKnownWordNote: (_noteId: number) => undefined,
     extractFields: (fields: Record<string, { value: string }>) => {
       const out: Record<string, string> = {};
       for (const [key, value] of Object.entries(fields)) {
@@ -594,104 +592,3 @@ test('NoteUpdateWorkflow queues media updates when YouTube cache is pending', as
   assert.equal(queuedUpdates[0]?.context, undefined);
   assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
 });
-
-test('NoteUpdateWorkflow deletes an existing word card when timing review discards it', async () => {
-  const harness = createWorkflowHarness();
-  const deletedNoteIds: number[][] = [];
-  const removedKnownWordNoteIds: number[] = [];
-  let appendedKnownWords = false;
-  harness.deps.captureSubtitleMediaContext = () => ({
-    source: 'overlay',
-    text: 'subtitle-text',
-    startTime: 4,
-    endTime: 6,
-  });
-  harness.deps.client.deleteNotes = async (noteIds) => {
-    deletedNoteIds.push(noteIds);
-  };
-  harness.deps.appendKnownWordsFromNoteInfo = () => {
-    appendedKnownWords = true;
-  };
-  harness.deps.removeKnownWordNote = (noteId) => {
-    removedKnownWordNoteIds.push(noteId);
-  };
-  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
-
-  await harness.workflow.execute(42);
-
-  assert.deepEqual(deletedNoteIds, [[42]]);
-  assert.deepEqual(removedKnownWordNoteIds, [42]);
-  assert.equal(appendedKnownWords, false);
-  assert.deepEqual(harness.updates, []);
-  assert.deepEqual(harness.notifications, []);
-});
-
-test('NoteUpdateWorkflow keeps the word card but skips media after timing review', async () => {
-  const harness = createWorkflowHarness();
-  const mediaCalls: string[] = [];
-  const deletedNoteIds: number[][] = [];
-  const queuedUpdates: unknown[] = [];
-  harness.deps.captureSubtitleMediaContext = () => ({
-    source: 'overlay',
-    text: 'subtitle-text',
-    startTime: 4,
-    endTime: 6,
-  });
-  harness.deps.getConfig = () => ({
-    fields: { sentence: 'Sentence', image: 'Picture' },
-    media: { generateAudio: true, generateImage: true },
-    behavior: {},
-  });
-  harness.deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
-  harness.deps.generateAudio = async () => {
-    mediaCalls.push('audio');
-    return Buffer.from('audio');
-  };
-  harness.deps.generateImage = async () => {
-    mediaCalls.push('image');
-    return Buffer.from('image');
-  };
-  harness.deps.queuePendingYoutubeMediaUpdate = async (update) => {
-    queuedUpdates.push(update);
-    return true;
-  };
-  harness.deps.client.deleteNotes = async (noteIds) => {
-    deletedNoteIds.push(noteIds);
-  };
-
-  await harness.workflow.execute(42);
-
-  assert.deepEqual(mediaCalls, []);
-  assert.deepEqual(queuedUpdates, []);
-  assert.deepEqual(deletedNoteIds, []);
-  assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
-  assert.deepEqual(harness.notifications, [{ noteId: 42, label: 'taberu' }]);
-});
-
-test('NoteUpdateWorkflow keeps cache unchanged and reports when deletion fails', async () => {
-  const harness = createWorkflowHarness();
-  const statusMessages: string[] = [];
-  let removedKnownWord = false;
-  harness.deps.captureSubtitleMediaContext = () => ({
-    source: 'overlay',
-    text: 'subtitle-text',
-    startTime: 4,
-    endTime: 6,
-  });
-  harness.deps.client.deleteNotes = async () => {
-    throw new Error('delete failed');
-  };
-  harness.deps.removeKnownWordNote = () => {
-    removedKnownWord = true;
-  };
-  harness.deps.showOsdNotification = (message) => {
-    statusMessages.push(message);
-  };
-  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
-
-  await harness.workflow.execute(42);
-
-  assert.equal(removedKnownWord, false);
-  assert.deepEqual(statusMessages, ['Card deletion failed: delete failed']);
-  assert.ok(harness.warnings.length === 0);
-});

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

@@ -1,12 +1,7 @@
 import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
 import { getPreferredWordValueFromExtractedFields } from '../anki-field-config';
 import type { SubtitleMiningContext } from '../types/subtitle';
-import type {
-  CardKind,
-  MediaTimingReviewDecision,
-  MediaTimingReviewRequest,
-  WordCardKind,
-} from '../types/anki';
+import type { CardKind, WordCardKind } from '../types/anki';
 import { resolveWordCardKind } from './note-field-utils';
 
 export interface NoteUpdateWorkflowNoteInfo {
@@ -19,7 +14,6 @@ export interface NoteUpdateWorkflowDeps {
     notesInfo(noteIds: number[]): Promise<unknown>;
     updateNoteFields(noteId: number, fields: Record<string, string>): Promise<void>;
     storeMediaFile(filename: string, data: Buffer): Promise<void>;
-    deleteNotes(noteIds: number[]): Promise<void>;
   };
   getConfig: () => {
     fields?: {
@@ -49,7 +43,6 @@ export interface NoteUpdateWorkflowDeps {
     wordCardKind?: WordCardKind;
   };
   appendKnownWordsFromNoteInfo: (noteInfo: NoteUpdateWorkflowNoteInfo) => void;
-  removeKnownWordNote: (noteId: number) => void;
   extractFields: (fields: Record<string, { value: string }>) => Record<string, string>;
   findDuplicateNote: (
     expression: string,
@@ -109,9 +102,6 @@ export interface NoteUpdateWorkflowDeps {
   logWarn: (message: string, ...args: unknown[]) => void;
   logInfo: (message: string, ...args: unknown[]) => void;
   logError: (message: string, ...args: unknown[]) => void;
-  reviewMediaTiming?: (
-    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
-  ) => Promise<MediaTimingReviewDecision>;
 }
 
 function normalizeSubtitleContextText(text: string): string {
@@ -181,6 +171,7 @@ export class NoteUpdateWorkflow {
       }
 
       const noteInfo = notesInfo[0]!;
+      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
       const fields = this.deps.extractFields(noteInfo.fields);
       const config = this.deps.getConfig();
 
@@ -216,48 +207,10 @@ export class NoteUpdateWorkflow {
       // Audio and image generation run sequentially and audio extraction can take tens of
       // seconds, so resolve the clip range exactly once up front; reading live mpv sub
       // timings per generator clips whichever line is on screen when each one starts.
-      let mediaTimingContext =
+      const mediaTimingContext =
         subtitleMiningContext ?? this.deps.captureSubtitleMediaContext?.() ?? null;
-      let skipMedia = false;
       const noteLabel = hasExpressionText ? expressionText : noteId;
 
-      if (mediaTimingContext) {
-        const timingDecision = this.deps.reviewMediaTiming
-          ? await this.deps.reviewMediaTiming({
-              kind: 'word',
-              text: mediaTimingContext.text,
-              startTime: mediaTimingContext.startTime,
-              endTime: mediaTimingContext.endTime,
-              noteId,
-            })
-          : ({ action: 'use-original' } as const);
-        if (timingDecision.action === 'discard') {
-          try {
-            await this.deps.client.deleteNotes([noteId]);
-          } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            this.deps.logError('Failed to delete discarded card:', message);
-            this.deps.showOsdNotification(`Card deletion failed: ${message}`);
-            return;
-          }
-          this.deps.removeKnownWordNote(noteId);
-          this.deps.showOsdNotification('Card deleted.');
-          return;
-        }
-        if (timingDecision.action === 'confirm') {
-          mediaTimingContext = {
-            ...mediaTimingContext,
-            startTime: timingDecision.startTime,
-            endTime: timingDecision.endTime,
-            mediaPaddingSeconds: 0,
-          };
-        } else if (timingDecision.action === 'skip-media') {
-          skipMedia = true;
-        }
-      }
-
-      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
-
       const currentSubtitleText = subtitleMiningContext?.text ?? this.deps.getCurrentSubtitleText();
       if (sentenceField && currentSubtitleText) {
         const processedSentence = this.deps.processSentence(currentSubtitleText, fields);
@@ -286,8 +239,8 @@ export class NoteUpdateWorkflow {
         }
       }
 
-      const generateAudio = !skipMedia && config.media?.generateAudio !== false;
-      const generateImage = !skipMedia && config.media?.generateImage !== false;
+      const generateAudio = config.media?.generateAudio !== false;
+      const generateImage = config.media?.generateImage !== false;
       const mediaCacheQueued =
         (generateAudio || generateImage) && this.deps.queuePendingYoutubeMediaUpdate
           ? await this.deps.queuePendingYoutubeMediaUpdate({

src/anki-integration/pending-youtube-media-queue.ts

@@ -148,9 +148,6 @@ export class PendingYoutubeMediaQueue {
       generateAudio: shouldGenerateAudio(config),
       generateImage: shouldGenerateImage(config),
       volumeScale,
-      ...(job.context?.mediaPaddingSeconds !== undefined
-        ? { mediaPaddingSeconds: job.context.mediaPaddingSeconds }
-        : {}),
     });
     return true;
   }
@@ -278,7 +275,7 @@ export class PendingYoutubeMediaQueue {
           cachedMediaInput,
           job.startTime,
           job.endTime,
-          job.mediaPaddingSeconds ?? config.media?.audioPadding,
+          config.media?.audioPadding,
           undefined,
           config.media?.normalizeAudio !== false,
           job.volumeScale,
@@ -312,7 +309,6 @@ export class PendingYoutubeMediaQueue {
           job.startTime,
           job.endTime,
           animatedLeadInSeconds,
-          job.mediaPaddingSeconds,
         );
         if (imageBuffer) {
           await this.deps.client.storeMediaFile(imageFilename, imageBuffer);
@@ -373,7 +369,6 @@ export class PendingYoutubeMediaQueue {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
-    mediaPaddingSeconds?: number,
   ): Promise<Buffer | null> {
     const config = this.deps.getConfig();
     if (config.media?.imageType === 'avif') {
@@ -381,7 +376,7 @@ export class PendingYoutubeMediaQueue {
         videoPath,
         startTime,
         endTime,
-        mediaPaddingSeconds ?? config.media?.audioPadding,
+        config.media?.audioPadding,
         {
           fps: config.media?.animatedFps,
           maxWidth: config.media?.animatedMaxWidth,

src/anki-integration/pending-youtube-media.ts

@@ -10,7 +10,6 @@ export interface PendingYoutubeMediaUpdate {
   generateAudio: boolean;
   generateImage: boolean;
   volumeScale?: number;
-  mediaPaddingSeconds?: number;
 }
 
 function trimToNonEmptyString(value: unknown): string | null {

src/config/config.test.ts

@@ -2181,7 +2181,6 @@ test('runtime options registry is centralized', () => {
   const ids = RUNTIME_OPTION_REGISTRY.map((entry) => entry.id);
   assert.deepEqual(ids, [
     'anki.autoUpdateNewCards',
-    'anki.mediaReviewTiming',
     'subtitle.annotation.knownWords.highlightEnabled',
     'subtitle.annotation.knownWords.maturityEnabled',
     'subtitle.annotation.nPlusOne',

src/config/definitions/defaults-integrations.ts

@@ -54,7 +54,6 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       syncAnimatedImageToWordAudio: true,
       normalizeAudio: true,
       mirrorMpvVolume: true,
-      reviewTiming: false,
       audioPadding: 0,
       fallbackDuration: 3.0,
       maxMediaDuration: 30,

src/config/definitions/options-integrations.ts

@@ -196,14 +196,6 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         "Apply mpv's current software volume curve to generated sentence audio. Changes apply live.",
     },
-    {
-      path: 'ankiConnect.media.reviewTiming',
-      kind: 'boolean',
-      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
-      description:
-        'Review and preview subtitle media timing before SubMiner creates or enriches a mined card.',
-      runtime: runtimeOptionById.get('anki.mediaReviewTiming'),
-    },
     {
       path: 'ankiConnect.media.generateImage',
       kind: 'boolean',

src/config/definitions/runtime-options.ts

@@ -19,20 +19,6 @@ export function buildRuntimeOptionRegistry(
         behavior: { autoUpdateNewCards: value === true },
       }),
     },
-    {
-      id: 'anki.mediaReviewTiming',
-      path: 'ankiConnect.media.reviewTiming',
-      label: 'Review Media Timing',
-      scope: 'ankiConnect',
-      valueType: 'boolean',
-      allowedValues: [true, false],
-      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
-      requiresRestart: false,
-      formatValueForOsd: (value) => (value === true ? 'On' : 'Off'),
-      toAnkiPatch: (value) => ({
-        media: { reviewTiming: value === true },
-      }),
-    },
     {
       id: 'subtitle.annotation.knownWords.highlightEnabled',
       path: 'ankiConnect.knownWords.highlightEnabled',

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/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind 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.test.ts

@@ -21,34 +21,6 @@ function makeContext(ankiConnect: unknown): {
   return { context, warnings };
 }
 
-test('media timing review is disabled by default and accepts a boolean override', () => {
-  const defaultContext = makeContext({});
-  applyAnkiConnectResolution(defaultContext.context);
-  assert.equal(defaultContext.context.resolved.ankiConnect.media.reviewTiming, false);
-
-  const enabledContext = makeContext({ media: { reviewTiming: true } });
-  applyAnkiConnectResolution(enabledContext.context);
-  assert.equal(enabledContext.context.resolved.ankiConnect.media.reviewTiming, true);
-  assert.deepEqual(enabledContext.warnings, []);
-});
-
-test('modern media duration accepts zero as the disabled cap sentinel', () => {
-  const disabledCap = makeContext({ media: { maxMediaDuration: 0 } });
-  applyAnkiConnectResolution(disabledCap.context);
-  assert.equal(disabledCap.context.resolved.ankiConnect.media.maxMediaDuration, 0);
-  assert.deepEqual(disabledCap.warnings, []);
-
-  const invalidCap = makeContext({ media: { maxMediaDuration: -1 } });
-  applyAnkiConnectResolution(invalidCap.context);
-  assert.equal(
-    invalidCap.context.resolved.ankiConnect.media.maxMediaDuration,
-    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
-  );
-  assert.ok(
-    invalidCap.warnings.some((warning) => warning.path === 'ankiConnect.media.maxMediaDuration'),
-  );
-});
-
 test('modern invalid knownWords.highlightEnabled warns modern key and does not fallback to legacy', () => {
   const { context, warnings } = makeContext({
     nPlusOne: { highlightEnabled: true },

src/config/resolve/anki-connect/modern-media.ts

@@ -19,7 +19,6 @@ export function applyModernMediaResolution(
     'syncAnimatedImageToWordAudio',
     'normalizeAudio',
     'mirrorMpvVolume',
-    'reviewTiming',
   ] as const) {
     applyModernValue(
       context,
@@ -129,28 +128,18 @@ export function applyModernMediaResolution(
     'Expected non-negative number.',
   );
 
+  for (const key of ['fallbackDuration', 'maxMediaDuration'] as const) {
     applyModernValue(
       context,
       media,
-    'fallbackDuration',
-    'ankiConnect.media.fallbackDuration',
+      key,
+      `ankiConnect.media.${key}`,
       asPositiveNumber,
-    DEFAULT_CONFIG.ankiConnect.media.fallbackDuration,
+      DEFAULT_CONFIG.ankiConnect.media[key],
       (value) => {
-      context.resolved.ankiConnect.media.fallbackDuration = value;
+        context.resolved.ankiConnect.media[key] = value;
       },
       'Expected positive number.',
     );
-  applyModernValue(
-    context,
-    media,
-    'maxMediaDuration',
-    'ankiConnect.media.maxMediaDuration',
-    asNonNegativeNumber,
-    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
-    (value) => {
-      context.resolved.ankiConnect.media.maxMediaDuration = value;
-    },
-    'Expected non-negative number.',
-  );
+  }
 }

src/config/settings/registry.test.ts

@@ -352,7 +352,6 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
     'ankiConnect.deck',
     'ankiConnect.media.normalizeAudio',
     'ankiConnect.media.mirrorMpvVolume',
-    'ankiConnect.media.reviewTiming',
     'ankiConnect.knownWords.highlightEnabled',
     'ankiConnect.knownWords.refreshMinutes',
     'ankiConnect.knownWords.addMinedWordsImmediately',

src/config/settings/registry.ts

@@ -244,7 +244,6 @@ const LABEL_OVERRIDES: Record<string, string> = {
   'mpv.aniskipEnabled': 'Enable AniSkip',
   'mpv.aniskipButtonKey': 'AniSkip Button Key',
   'ankiConnect.media.mirrorMpvVolume': 'Mirror mpv Volume',
-  'ankiConnect.media.reviewTiming': 'Review Media Timing',
   'discordPresence.updateIntervalMs': 'Update Interval (ms)',
 };
 
@@ -695,7 +694,6 @@ function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
     path === 'ankiConnect.ai.enabled' ||
     path === 'ankiConnect.media.normalizeAudio' ||
     path === 'ankiConnect.media.mirrorMpvVolume' ||
-    path === 'ankiConnect.media.reviewTiming' ||
     path === 'ankiConnect.behavior.autoUpdateNewCards' ||
     path === 'ankiConnect.knownWords.highlightEnabled' ||
     path === 'ankiConnect.knownWords.refreshMinutes' ||

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

@@ -284,6 +284,22 @@ function createMockTracker(
     getSessionTimeline: async () => [],
     getSessionEvents: async () => [],
     getVocabularyStats: async () => VOCABULARY_STATS,
+    getVocabularySummary: async () => ({
+      uniqueWords: 501,
+      uniqueWordsWithoutNames: 500,
+      uniqueKanji: 201,
+      newThisWeek: 7,
+      newThisWeekWithoutNames: 6,
+      knownWordCount: 250,
+      knownWordCountWithoutNames: 249,
+    }),
+    getVocabularyChartData: async () => ({
+      ready: true,
+      topWords: [{ wordId: 1, headword: 'する', frequency: 50 }],
+      topWordsWithoutNames: [{ wordId: 1, headword: 'する', frequency: 50 }],
+      newWordsTimeline: [{ epochDay: 20_000, wordCount: 3 }],
+      newWordsTimelineWithoutNames: [{ epochDay: 20_000, wordCount: 3 }],
+    }),
     getStatsExcludedWords: async () => [],
     replaceStatsExcludedWords: async () => {},
     getKanjiStats: async () => KANJI_STATS,
@@ -711,6 +727,38 @@ describe('stats server API routes', () => {
     assert.equal(body[0].headword, 'する');
   });
 
+  it('GET /api/stats/vocabulary/summary returns database-wide card totals', async () => {
+    const app = createStatsApp(createMockTracker());
+
+    const res = await app.request('/api/stats/vocabulary/summary');
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(await res.json(), {
+      uniqueWords: 501,
+      uniqueWordsWithoutNames: 500,
+      uniqueKanji: 201,
+      newThisWeek: 7,
+      newThisWeekWithoutNames: 6,
+      knownWordCount: 250,
+      knownWordCountWithoutNames: 249,
+    });
+  });
+
+  it('GET /api/stats/vocabulary/charts returns complete chart datasets', async () => {
+    const app = createStatsApp(createMockTracker());
+
+    const res = await app.request('/api/stats/vocabulary/charts');
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(await res.json(), {
+      ready: true,
+      topWords: [{ wordId: 1, headword: 'する', frequency: 50 }],
+      topWordsWithoutNames: [{ wordId: 1, headword: 'する', frequency: 50 }],
+      newWordsTimeline: [{ epochDay: 20_000, wordCount: 3 }],
+      newWordsTimelineWithoutNames: [{ epochDay: 20_000, wordCount: 3 }],
+    });
+  });
+
   it('GET /api/stats/kanji returns kanji frequency data', async () => {
     const app = createStatsApp(createMockTracker());
     const res = await app.request('/api/stats/kanji');

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

@@ -33,7 +33,6 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
   next.ankiConnect.deck = 'Mining';
   next.ankiConnect.media.normalizeAudio = !prev.ankiConnect.media.normalizeAudio;
   next.ankiConnect.media.mirrorMpvVolume = !prev.ankiConnect.media.mirrorMpvVolume;
-  next.ankiConnect.media.reviewTiming = !prev.ankiConnect.media.reviewTiming;
   next.ankiConnect.behavior.autoUpdateNewCards = !prev.ankiConnect.behavior.autoUpdateNewCards;
   next.ankiConnect.knownWords.highlightEnabled = !prev.ankiConnect.knownWords.highlightEnabled;
   next.ankiConnect.knownWords.refreshMinutes = prev.ankiConnect.knownWords.refreshMinutes + 5;
@@ -70,7 +69,6 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
       'ankiConnect.deck',
       'ankiConnect.media.normalizeAudio',
       'ankiConnect.media.mirrorMpvVolume',
-      'ankiConnect.media.reviewTiming',
       'ankiConnect.behavior.autoUpdateNewCards',
       'ankiConnect.knownWords.highlightEnabled',
       'ankiConnect.knownWords.refreshMinutes',

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

@@ -70,7 +70,6 @@ const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
   'ankiConnect.deck',
   'ankiConnect.media.normalizeAudio',
   'ankiConnect.media.mirrorMpvVolume',
-  'ankiConnect.media.reviewTiming',
   'ankiConnect.behavior.autoUpdateNewCards',
   'ankiConnect.knownWords.highlightEnabled',
   'ankiConnect.knownWords.refreshMinutes',

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

@@ -559,6 +559,241 @@ test('fresh tracker DB creates lifetime summary tables', async () => {
   }
 });
 
+test('fresh tracker DB skips lexical rollup backfill work', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  let backfillRuns = 0;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath }, {
+      runLexicalRollupBackfillTask: async () => {
+        backfillRuns += 1;
+      },
+    } as never);
+
+    assert.equal(backfillRuns, 0);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('tracker starts the injected lexical rollup backfill when it is pending', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  let backfillRuns = 0;
+
+  try {
+    const setupDb = new Database(dbPath);
+    const { ensureSchema } = await import('./immersion-tracker/storage');
+    ensureSchema(setupDb);
+    setupDb
+      .prepare(
+        `UPDATE imm_rollup_state SET state_value = '0' WHERE state_key = 'lexical_daily_rollups_version'`,
+      )
+      .run();
+    setupDb.close();
+
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath }, {
+      runLexicalRollupBackfillTask: async () => {
+        backfillRuns += 1;
+      },
+    } as never);
+
+    assert.equal(backfillRuns, 1);
+    await waitForCondition(
+      () => !(tracker as unknown as { writeLock: { locked: boolean } }).writeLock.locked,
+    );
+    assert.equal(
+      (tracker as unknown as { preserveWriteQueueUntilDrained: boolean })
+        .preserveWriteQueueUntilDrained,
+      false,
+    );
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('tracker runs startup session-rollup maintenance before lexical backfill locks writes', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  let releaseBackfill = (): void => {};
+  const heldBackfill = new Promise<void>((resolve) => {
+    releaseBackfill = resolve;
+  });
+
+  try {
+    const startedAtMs = trackerNowMs() - 60_000;
+    const endedAtMs = trackerNowMs();
+    const setupDb = new Database(dbPath);
+    const { ensureSchema } = await import('./immersion-tracker/storage');
+    ensureSchema(setupDb);
+    setupDb.exec(`
+      INSERT INTO imm_videos (
+        video_id, video_key, canonical_title, source_type, duration_ms, CREATED_DATE, LAST_UPDATE_DATE
+      ) VALUES (1, 'local:/tmp/rollup-recovery.mkv', 'Rollup Recovery', 1, 0, '1', '1');
+      INSERT INTO imm_sessions (
+        session_id, session_uuid, video_id, started_at_ms, ended_at_ms, status,
+        active_watched_ms, lines_seen, tokens_seen, cards_mined, CREATED_DATE, LAST_UPDATE_DATE
+      ) VALUES (
+        1, 'rollup-recovery', 1, '${startedAtMs}', '${endedAtMs}', 2,
+        60000, 10, 20, 2, '${startedAtMs}', '${endedAtMs}'
+      );
+      INSERT INTO imm_session_telemetry (
+        session_id, sample_ms, total_watched_ms, active_watched_ms, lines_seen,
+        tokens_seen, cards_mined, lookup_count, lookup_hits, CREATED_DATE, LAST_UPDATE_DATE
+      ) VALUES (
+        1, '${endedAtMs}', 60000, 60000, 10, 20, 2, 0, 0,
+        '${endedAtMs}', '${endedAtMs}'
+      );
+      DELETE FROM imm_daily_rollups;
+      DELETE FROM imm_monthly_rollups;
+      UPDATE imm_rollup_state SET state_value = '0';
+    `);
+    setupDb.close();
+
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath }, {
+      runLexicalRollupBackfillTask: async () => heldBackfill,
+    } as never);
+
+    const privateApi = tracker as unknown as {
+      db: DatabaseSync;
+      writeLock: { locked: boolean };
+    };
+    assert.equal(privateApi.writeLock.locked, true);
+    assert.equal(
+      (
+        privateApi.db.prepare('SELECT COUNT(*) AS total FROM imm_daily_rollups').get() as {
+          total: number;
+        }
+      ).total,
+      1,
+    );
+    assert.equal(
+      (
+        privateApi.db.prepare('SELECT COUNT(*) AS total FROM imm_monthly_rollups').get() as {
+          total: number;
+        }
+      ).total,
+      1,
+    );
+  } finally {
+    releaseBackfill();
+    if (tracker) {
+      await waitForCondition(
+        () => !(tracker as unknown as { writeLock: { locked: boolean } }).writeLock.locked,
+      );
+    }
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('tracker queues playback writes until lexical rollup backfill settles', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  let startBackfill = (): void => {};
+  let releaseBackfill = (): void => {};
+  let markBackfillStarted = (): void => {};
+  const backfillStartGate = new Promise<void>((resolve) => {
+    startBackfill = resolve;
+  });
+  const heldBackfill = new Promise<void>((resolve) => {
+    releaseBackfill = resolve;
+  });
+  const backfillStarted = new Promise<void>((resolve) => {
+    markBackfillStarted = resolve;
+  });
+
+  try {
+    const setupDb = new Database(dbPath);
+    const { ensureSchema } = await import('./immersion-tracker/storage');
+    ensureSchema(setupDb);
+    setupDb
+      .prepare(
+        `UPDATE imm_rollup_state SET state_value = '0' WHERE state_key = 'lexical_daily_rollups_version'`,
+      )
+      .run();
+    setupDb.close();
+
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor(
+      { dbPath, policy: { queueCap: 100 } },
+      {
+        runLexicalRollupBackfillTask: async (workerDbPath) => {
+          await backfillStartGate;
+          const workerDb = new Database(workerDbPath);
+          try {
+            workerDb.exec('BEGIN IMMEDIATE');
+            markBackfillStarted();
+            await heldBackfill;
+            workerDb.exec('COMMIT');
+          } catch (error) {
+            try {
+              workerDb.exec('ROLLBACK');
+            } catch {
+              // Preserve the original worker failure.
+            }
+            throw error;
+          } finally {
+            workerDb.close();
+          }
+        },
+      },
+    );
+    tracker.handleMediaChange('https://example.com/backfill-test.mp4', 'Backfill Test');
+    startBackfill();
+    await backfillStarted;
+    for (let index = 0; index < 125; index += 1) tracker.recordCardsMined(1);
+
+    const privateApi = tracker as unknown as {
+      db: DatabaseSync;
+      queue: unknown[];
+      droppedWriteCount: number;
+      flushNow: () => void;
+      writeLock: { locked: boolean };
+    };
+    assert.equal(privateApi.writeLock.locked, true);
+    privateApi.flushNow();
+
+    assert.ok(privateApi.queue.length > 100, 'the protected queue may grow past its normal cap');
+    assert.equal(privateApi.droppedWriteCount, 0, 'backfill must not discard playback writes');
+    assert.equal(
+      (
+        privateApi.db.prepare('SELECT COUNT(*) AS total FROM imm_session_events').get() as {
+          total: number;
+        }
+      ).total,
+      0,
+    );
+
+    releaseBackfill();
+    await waitForCondition(() => privateApi.queue.length === 0, 5_000);
+    assert.equal(
+      (
+        privateApi.db.prepare('SELECT COUNT(*) AS total FROM imm_session_events').get() as {
+          total: number;
+        }
+      ).total,
+      125,
+    );
+  } finally {
+    releaseBackfill();
+    if (tracker) {
+      await waitForCondition(
+        () => !(tracker as unknown as { writeLock: { locked: boolean } }).writeLock.locked,
+        5_000,
+      );
+    }
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
 test('startup backfills lifetime summaries when retained sessions exist but summary tables are empty', async () => {
   const dbPath = makeDbPath();
   let tracker: ImmersionTrackerService | null = null;
@@ -4909,3 +5144,149 @@ test('ensureAnimeCoverArt fetches art via the latest video of the anime', async
     cleanupDbPath(dbPath);
   }
 });
+
+test('getVocabularySummary coalesces concurrent requests into one worker task', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  let taskRuns = 0;
+  let releaseTask: (() => void) | null = null;
+  const seenKnownWords: Array<ReadonlySet<string> | null> = [];
+  const summary = {
+    uniqueWords: 1,
+    uniqueWordsWithoutNames: 1,
+    uniqueKanji: 0,
+    newThisWeek: 0,
+    newThisWeekWithoutNames: 0,
+    knownWordCount: null,
+    knownWordCountWithoutNames: null,
+  };
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor(
+      { dbPath },
+      {
+        runVocabularySummaryTask: async (_dbPath, knownWords) => {
+          taskRuns += 1;
+          seenKnownWords.push(knownWords);
+          await new Promise<void>((resolve) => {
+            releaseTask = resolve;
+          });
+          return summary;
+        },
+        destroyVocabularySummaryRunner: () => {},
+      },
+    );
+
+    const knownWordsSnapshot = new Set(['猫']);
+    const first = tracker.getVocabularySummary(knownWordsSnapshot);
+    const second = tracker.getVocabularySummary(knownWordsSnapshot);
+    await waitForCondition(() => releaseTask !== null);
+    let release = releaseTask as (() => void) | null;
+    assert.ok(release);
+    release();
+    assert.deepEqual(await first, summary);
+    assert.equal(await second, await first);
+    assert.equal(taskRuns, 1);
+    assert.deepEqual(seenKnownWords, [knownWordsSnapshot]);
+
+    releaseTask = null;
+    const third = tracker.getVocabularySummary(null);
+    await waitForCondition(() => releaseTask !== null);
+    release = releaseTask as (() => void) | null;
+    assert.ok(release);
+    release();
+    assert.deepEqual(await third, summary);
+    assert.equal(taskRuns, 2);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('getVocabularySummary coalesces equivalent known-word snapshots by value', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  let taskRuns = 0;
+  const releases: Array<() => void> = [];
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor(
+      { dbPath },
+      {
+        runVocabularySummaryTask: async () => {
+          taskRuns += 1;
+          await new Promise<void>((resolve) => releases.push(resolve));
+          return {
+            uniqueWords: 2,
+            uniqueWordsWithoutNames: 2,
+            uniqueKanji: 2,
+            newThisWeek: 0,
+            newThisWeekWithoutNames: 0,
+            knownWordCount: 2,
+            knownWordCountWithoutNames: 2,
+          };
+        },
+        destroyVocabularySummaryRunner: () => {},
+      },
+    );
+
+    const first = tracker.getVocabularySummary(new Set(['猫', '犬']));
+    const second = tracker.getVocabularySummary(new Set(['犬', '猫']));
+    await waitForCondition(() => releases.length > 0);
+    const observedTaskRuns = taskRuns;
+    for (const release of releases) release();
+    await Promise.all([first, second]);
+
+    assert.equal(observedTaskRuns, 1);
+
+    const third = tracker.getVocabularySummary(new Set(['猫', '犬']));
+    await waitForCondition(() => releases.length === 2);
+    releases[1]!();
+    await third;
+    assert.equal(taskRuns, 2, 'a settled snapshot must be evicted from the in-flight map');
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('getVocabularySummary keeps different known-word snapshots independent', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  const releases: Array<() => void> = [];
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor(
+      { dbPath },
+      {
+        runVocabularySummaryTask: async (_dbPath, knownWords) => {
+          await new Promise<void>((resolve) => releases.push(resolve));
+          return {
+            uniqueWords: 1,
+            uniqueWordsWithoutNames: 1,
+            uniqueKanji: 0,
+            newThisWeek: 0,
+            newThisWeekWithoutNames: 0,
+            knownWordCount: knownWords?.size ?? null,
+            knownWordCountWithoutNames: knownWords?.size ?? null,
+          };
+        },
+        destroyVocabularySummaryRunner: () => {},
+      },
+    );
+
+    const withoutKnownWords = tracker.getVocabularySummary(null);
+    const withKnownWords = tracker.getVocabularySummary(new Set(['猫']));
+    await waitForCondition(() => releases.length === 2);
+    for (const release of releases) release();
+
+    assert.equal((await withoutKnownWords).knownWordCount, null);
+    assert.equal((await withKnownWords).knownWordCount, 1);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});