chore(release): prepare v0.18.0

chore(docs): remove implemented plan docs
- Drop early-managed-overlay-startup and macos-notification-hover design docs (both implemented, no longer needed)
2026-07-27 16:49:51 -07:00 · 2026-07-10 02:03:10 -07:00 · 2026-07-10 01:09:52 -07:00 · 2026-07-10 01:04:01 -07:00 · 2026-07-10 00:54:17 -07:00 · 2026-07-10 00:44:23 -07:00
78 changed files with 1794 additions and 319 deletions
@@ -1,5 +1,36 @@
 # Changelog

+## v0.18.0 (2026-07-10)
+
+### Added
+- Sentence Audio Normalization: Generated sentence audio is now normalized to -23 LUFS by default, and clips mined from playback mirror mpv's software volume curve with a limiter to prevent clipping. Both behaviors are configurable independently.
+- Watch History Command: Added `subminer -H` / `--history` to browse watch history, replay or continue episodes, or pick one via fzf or rofi, with cover art shown in the rofi picker.
+
+### Changed
+- Fzf Preview Layout: Moved fzf previews below launcher menus, giving long titles and metadata more room.
+- Known-Word Highlighting: Now compares subtitle and Anki-card readings, preventing false matches between homographs and unrelated words that share a reading, while still supporting matching across kana and kanji spellings.
+- Annotation Filtering: Standalone suffix tokens (e.g. さん, れる) are now excluded from JLPT/frequency/N+1 highlighting by default, matching how particles and interjections are treated; configurable via the pos2 exclusion setting.
+- App Icon: Replaced the app icon with new pixel-art submarine artwork contributed by the community, used across the app icon, tray, notifications, README, docs site, and Stats page.
+- Stats Trend Charts: Overhauled with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and value-sorted tooltips.
+
+### Fixed
+- Background Stats Server: `subminer app` background launches now auto-start the stats server when enabled, and skip startup if one is already running.
+- Character Name Highlighting: Character dictionaries now split unspaced native names more reliably, and portraits, highlights, and hover lookup survive punctuation, unmatched text, and competing dictionary matches without incorrectly splitting longer words.
+- Highlighting Coverage: Frequency/JLPT highlighting and vocabulary stats now include content adverbs (e.g. 確かに, やはり) and kanji nouns MeCab tags as non-independent (e.g. 日, 点, 以外), while still suppressing interjections, pronouns, and grammar fragments; lexicalized kana expressions like かといって keep their annotations.
+- Cover Art Fetching: Stats now fetches AniList cover art as soon as a new series starts playing, and backfills missing art for existing series on the next Stats visit.
+- Kiku Field Grouping: The manual field-grouping dialog now stays above fullscreen mpv, remains usable across repeated attempts, closes abandoned windows after timeouts, and reports a clear error when the original card can no longer be loaded.
+- Karaoke Subtitle Collapse: Secondary subtitles no longer stack dozens of one-syllable lines during openings and endings; repeated events collapse into one line, capped to a strip at the top.
+- Unparsed Token Hover: Subtitle text Yomitan can't parse (truncated inflections, elongation runs) remains hoverable, while staying excluded from highlighting, N+1 candidate math, and vocabulary stats.
+- YouTube Streaming: Fixed direct YouTube stream extraction that could corrupt signed URLs and cause ffmpeg 403 errors.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Test lanes moved to `scripts/test-lanes.ts` with per-directory discovery and isolated per-file timeouts; CI now covers previously orphaned stats, scripts, plugin process-retry, and runtime-compat suites, plus a new stats lane in the change-verification workflow.
+
+</details>
+
 ## v0.17.2 (2026-06-28)

 ### Fixed
@@ -1,4 +0,0 @@
-type: added
-area: mining
-
- Normalized generated card audio by default during media extraction, with `ankiConnect.media.normalizeAudio` available to keep raw source loudness when needed.
@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
- `subminer app` background launches now start the stats server automatically when `stats.autoStartServer` is enabled, and skip startup when a background stats server is already running.
@@ -1,6 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed character-dictionary surname/given-name splitting for unspaced AniList native names where romanized reading length misled the boundary guess (東紫乃 split as 東紫+乃, 渡辺真奈美 as 渡辺真+奈美), so surnames like 東 and 渡辺 were never highlighted with character portraits and unmatched leading kanji (渡) lost hover lookup entirely. Name parts are now resolved with MeCab person-name POS tags and reading validation when MeCab is available; without MeCab, terms are generated for both plausible boundaries so the real surname still matches. Existing snapshots regenerate automatically (format version bump), and snapshots built without MeCab are upgraded to exact MeCab splits once MeCab is detected.
- Fixed subtitle tokenization dropping a character entirely when Yomitan's greedy scan consumed trailing punctuation/whitespace past the term (e.g. 平 in 「（東）平　（平）え？」 matched across the paren with no exact-source headword). The scanner now retries shorter windows so the prefix term still tokenizes with its name match and portrait.
- Fixed character-name highlights being stripped when MeCab's context-dependent POS tag put the token in the annotation noise filter (e.g. 平 tagged as prefix 接頭詞 in 「あっ 平 これ…」 lost its highlight and portrait even though hover lookup showed the character). Confirmed name matches now survive the POS exclusion filter, and name matching alone keeps the annotation stage active when all other annotations are disabled.
@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
- Cover art is now fetched eagerly when a new series starts playing, instead of waiting for the first visit to its series detail page, so the stats timeline shows the best-guess AniList image right away. The stats covers endpoint also backfills missing series art in the background, so existing series without an image pick one up on the next stats page load.
@@ -1,4 +0,0 @@
-type: changed
-area: launcher
-
- Moved fzf previews below launcher menus so long titles and metadata have more horizontal room.
@@ -1,4 +0,0 @@
-type: added
-area: launcher
-
- Show cover art icons in the rofi watch-history picker, reusing AniList covers already stored in the stats database (extracted to `~/.cache/subminer/covers`).
@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
- Fixed cancelling the Kiku field grouping dialog showing two "Field grouping cancelled" notifications when grouping was started via the trigger shortcut: the manual workflow already notifies about its outcome (cancelled, UI unavailable, failed), and the trigger path re-notified on top of it. The workflow now owns all outcome notifications, and a previously silent failure (the original card no longer loadable) gets its own message.
@@ -1,6 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed Kiku manual field grouping freezing the overlay after adding a duplicate card: the field grouping modal now reliably appears above fullscreen mpv on Hyprland/Wayland by re-asserting window placement until the compositor maps the modal window, instead of a single post-show attempt that raced the async map and left the dialog invisible.
- Fixed manual field grouping staying broken after the first attempt: the request resolver is now always cleared once a choice is made or the request is abandoned, so later grouping attempts no longer short-circuit to an instant "Field grouping cancelled".
- Fixed a timed-out or failed field grouping request leaving an orphaned, invisible modal window covering mpv: abandoned requests now tear down the modal window and close the dialog so the overlay recovers immediately.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed words being highlighted green as known when a same-spelled Anki card taught a different reading (e.g. とこ parsed as 床 "bed" matching a known 床/ゆか "floor" card). The known-word cache now stores each card's word together with its reading and only matches when the token's reading agrees; cards without a reading field keep matching in any reading as before.
@@ -1,4 +0,0 @@
-type: added
-area: launcher
-
- Added `subminer -H` / `--history` to browse local watch history, replay the last watched episode, continue to the next episode, or browse episodes with fzf/rofi.
@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed single-kana grammar tokens counting as known words by borrowing the reading of an unrelated Anki note (よ in 全然いいよ matched a card read よ such as 夜, standalone え matched 絵), which painted them with the known-word highlight. Reading-only known-word matching now requires at least two kana; single-kana cards still match by their word field, and tokens genuinely present in the known-words cache (e.g. です) keep their highlight.
- Standalone suffix tokens (MeCab pos2 接尾, e.g. さん, れる) are now excluded from JLPT/frequency/N+1 annotations by default, matching how particles and interjections are treated. Cache-backed known-word highlighting still applies; override via the pos2 exclusion config if you want them annotated.
@@ -1,4 +0,0 @@
-type: changed
-area: branding
-
- Replaced the SubMiner app icon with new pixel-art submarine artwork contributed by an anonymous community member, used across the app icon, tray, notifications, README, docs site, and stats page.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed secondary subtitles stacking dozens of one-syllable lines down the screen during karaoke-typeset openings/endings, which made the hover-pause band cover the whole video: karaoke-like event spam is now collapsed into a single deduped line, and the secondary subtitle area is height-capped so it always stays a strip at the top.
@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
- Session known-word counts no longer show 0 everywhere. The stats server's known-word cache parser only understood the v1/v2 cache formats, so after the reading-aware v3 cache upgrade it silently treated the cache as missing; it now flattens v3 note entries into the headword set.
@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
- Show all trend chart titles by default, persist hidden-title choices, and add a per-chart top-title limit selector.
@@ -1,7 +0,0 @@
-type: internal
-area: testing
-
- Test lanes are now defined once in `scripts/test-lanes.ts` and discovered by directory instead of hand-maintained file lists in `package.json`; the unused `test:core:*`/`test:config:dist`/`test:full` scripts were removed.
- `scripts/run-test-lane.mjs` runs each test file in an isolated `bun test` process with a wall timeout, so a hanging test or leaked global can no longer cascade failures across the lane.
- Previously orphaned suites now run in CI: the stats dashboard tests (`bun run test:stats`), the `scripts/**` tests (`bun run test:scripts`, including the change-verification skill tests), the `test-plugin-process-start-retries.lua` plugin test, and the runtime-compat dist slice (now part of `bun run test:fast`).
- The change-verification skill gained a `stats` lane for `stats/` edits.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed subtitle text that Yomitan's parser cannot match (e.g. the truncated volitional in とこ戻ろ…) being rendered as plain, non-interactive text: it was invisible to hover/lookup and excluded from the n+1 word count, which could wrongly mark a sentence as n+1. Unparsed runs are now kept as hoverable tokens matching Yomitan's own segmentation; bracketed SFX/speaker captions and punctuation-only runs are still skipped.
@@ -1,4 +0,0 @@
-type: fixed
-area: youtube
-
- Fixed direct YouTube stream media extraction by parsing mpv EDL stream URLs with their byte-length guards, preventing trailing EDL segment options from corrupting signed googlevideo URLs and causing ffmpeg 403 errors.
@@ -515,7 +515,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping 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.
  // ==========================================
@@ -559,7 +559,8 @@
      "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
      "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. 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
      "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.
@@ -162,13 +162,16 @@ Audio is extracted from the video file using the subtitle's start and end timest
  "media": {
    "generateAudio": true,
    "normalizeAudio": true,      // normalize generated clip loudness
+    "mirrorMpvVolume": true,     // apply the current mpv volume level
    "audioPadding": 0,           // optional seconds before and after subtitle timing
    "maxMediaDuration": 30       // cap total duration in seconds
  }
 }
 ```

-Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness.
+Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness. Changing this setting applies to the next extraction without restarting SubMiner.
+
+`mirrorMpvVolume` is also enabled by default. Immediately before extracting each playback-overlay card's audio, SubMiner reads mpv's numeric `volume` and applies mpv's cubic software-volume curve after loudness normalization. For example, mpv volume `50` produces `0.5³ = 0.125` gain. Amplified output above mpv volume `100` is limited to a `-1 dBFS` ceiling before MP3 encoding to prevent clipping. It ignores mpv's separate `mute` state. If the volume property is missing, invalid, or unavailable, extraction continues with unity scaling; disabling this option skips the query and volume filter. Changing this setting applies to the next extraction without restarting SubMiner. YouTube cards queued for a background media-cache download retain the volume captured when the card was mined. Stats-dashboard mining does not currently have access to the active mpv property client, so it does not apply mpv volume scaling.

 The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.

@@ -349,6 +352,7 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
      "imageFormat": "jpg",
      "imageQuality": 92,
      "normalizeAudio": true,
+      "mirrorMpvVolume": true,
      "audioPadding": 0,
      "maxMediaDuration": 30,
    },
@@ -1,12 +1,48 @@
 # Changelog

-## v0.17.2 (2026-06-28)
+## v0.18.0 (2026-07-10)
+
+**Added**
+- Sentence Audio Normalization: Generated sentence audio is now normalized to -23 LUFS by default, and clips mined from playback mirror mpv's software volume curve with a limiter to prevent clipping. Both behaviors are configurable independently.
+- Watch History Command: Added `subminer -H` / `--history` to browse watch history, replay or continue episodes, or pick one via fzf or rofi, with cover art shown in the rofi picker.
+
+**Changed**
+- Fzf Preview Layout: Moved fzf previews below launcher menus, giving long titles and metadata more room.
+- Known-Word Highlighting: Now compares subtitle and Anki-card readings, preventing false matches between homographs and unrelated words that share a reading, while still supporting matching across kana and kanji spellings.
+- Annotation Filtering: Standalone suffix tokens (e.g. さん, れる) are now excluded from JLPT/frequency/N+1 highlighting by default, matching how particles and interjections are treated; configurable via the pos2 exclusion setting.
+- App Icon: Replaced the app icon with new pixel-art submarine artwork contributed by the community, used across the app icon, tray, notifications, README, docs site, and Stats page.
+- Stats Trend Charts: Overhauled with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and value-sorted tooltips.
+
+**Fixed**
+- Background Stats Server: `subminer app` background launches now auto-start the stats server when enabled, and skip startup if one is already running.
+- Character Name Highlighting: Character dictionaries now split unspaced native names more reliably, and portraits, highlights, and hover lookup survive punctuation, unmatched text, and competing dictionary matches without incorrectly splitting longer words.
+- Highlighting Coverage: Frequency/JLPT highlighting and vocabulary stats now include content adverbs (e.g. 確かに, やはり) and kanji nouns MeCab tags as non-independent (e.g. 日, 点, 以外), while still suppressing interjections, pronouns, and grammar fragments; lexicalized kana expressions like かといって keep their annotations.
+- Cover Art Fetching: Stats now fetches AniList cover art as soon as a new series starts playing, and backfills missing art for existing series on the next Stats visit.
+- Kiku Field Grouping: The manual field-grouping dialog now stays above fullscreen mpv, remains usable across repeated attempts, closes abandoned windows after timeouts, and reports a clear error when the original card can no longer be loaded.
+- Karaoke Subtitle Collapse: Secondary subtitles no longer stack dozens of one-syllable lines during openings and endings; repeated events collapse into one line, capped to a strip at the top.
+- Unparsed Token Hover: Subtitle text Yomitan can't parse (truncated inflections, elongation runs) remains hoverable, while staying excluded from highlighting, N+1 candidate math, and vocabulary stats.
+- YouTube Streaming: Fixed direct YouTube stream extraction that could corrupt signed URLs and cause ffmpeg 403 errors.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Test lanes moved to `scripts/test-lanes.ts` with per-directory discovery and isolated per-file timeouts; CI now covers previously orphaned stats, scripts, plugin process-retry, and runtime-compat suites, plus a new stats lane in the change-verification workflow.
+
+</details>
+
+## Previous Versions
+
+<details>
+<summary>v0.17.x</summary>
+
+<h2>v0.17.2 (2026-06-28)</h2>

 **Fixed**
 - YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
 - YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.

-## v0.17.1 (2026-06-27)
+<h2>v0.17.1 (2026-06-27)</h2>

 **Added**
 - YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
@@ -15,7 +51,7 @@
 - Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
 - YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.

-## v0.17.0 (2026-06-15)
+<h2>v0.17.0 (2026-06-15)</h2>

 **Changed**

@@ -50,7 +86,7 @@

 </details>

-## Previous Versions
+</details>

 <details>
 <summary>v0.16.x</summary>
@@ -952,6 +952,7 @@ Enable automatic Anki card creation and updates with media generation:
      "animatedMaxHeight": 0,
      "animatedCrf": 35,
      "normalizeAudio": true,
+      "mirrorMpvVolume": true,
      "audioPadding": 0,
      "fallbackDuration": 3,
      "maxMediaDuration": 30
@@ -1002,7 +1003,8 @@ This example is intentionally compact. The option table below documents availabl
 | `ankiConnect.ai.model`                            | string                                      | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                                               |
 | `ankiConnect.ai.systemPrompt`                     | string                                      | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                                                       |
 | `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.                                                                                              |
+| `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.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"`)                                                                                                                                                                                                 |
@@ -515,7 +515,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping 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.
  // ==========================================
@@ -559,7 +559,8 @@
      "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
      "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. 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
      "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.
@@ -90,7 +90,7 @@ SubMiner looks up each token's `frequencyRank` from `term_meta_bank_*.json` file
 When `sourcePath` is omitted, SubMiner searches default install/runtime locations for `frequency-dictionary` directories automatically.

 ::: info
-Frequency highlighting skips tokens that look like non-lexical noise (kana reduplication, short kana endings like `っ`), even when dictionary ranks exist.
+Frequency highlighting skips tokens that look like non-lexical noise (kana reduplication, short kana endings like `っ`), even when dictionary ranks exist. For merged kana tokens, SubMiner keeps a rank when the dictionary headword reading covers the full token (for example, `かと言って` / `かといって`), while grammar wrapped around a shorter lemma remains unannotated.
 :::

 ::: info
@@ -1,29 +0,0 @@
-<!-- read_when: changing managed mpv startup, pause-until-ready, or visible overlay boot ordering -->
-
-# Early Managed Overlay Startup Design
-
-Status: approved
-Date: 2026-06-06
-
-## Problem
-
-Managed mpv startup can pause playback immediately, then leave SubMiner's tray and visible overlay
-unavailable until Yomitan/tokenization warmups finish. Startup notifications therefore miss the
-overlay surface and fall back to non-overlay status paths.
-
-## Chosen Approach
-
-For cold `--start --background --managed-playback` launches, handle initial args before waiting for
-the deferred overlay warmup. That lets the tray and visible overlay shell initialize immediately
-while the existing tokenization warmups continue in the background.
-
-The mpv plugin pause gate stays armed. Playback release still waits for SubMiner's autoplay-ready
-signal, which is emitted only after tokenization warmup and visible-overlay readiness. Existing
-second-instance attach behavior remains unchanged: when the launcher finds an already-running
-background app, it sends the same control command to that process and reuses its warmups/tokenizer.
-
-## Checks
-
- Add a startup ordering regression test for managed background playback.
- Keep the existing deferred startup ordering for non-managed launches.
- Run the startup/runtime test slice plus SubMiner verification lane.
@@ -1,27 +0,0 @@
-<!-- read_when: changing overlay notification hover, macOS mouse passthrough, or notification actions -->
-
-# macOS Notification Hover Stability Design
-
-Status: approved
-Date: 2026-06-09
-
-## Problem
-
-On macOS, hovering a character dictionary build notification can make the card flicker and slide as
-if it is hiding, then snap back. The likely trigger is the notification stack changing the overlay
-window's mouse-passthrough state for a progress card that has no user action.
-
-## Chosen Approach
-
-Keep non-action overlay notifications visually stable and click-through on hover. Only notifications
-with explicit actions should request interactive overlay input. The notification history panel keeps
-its existing interactive behavior.
-
-This avoids a macOS mouseenter/mouseleave passthrough loop for passive progress cards while
-preserving clickable notification actions.
-
-## Checks
-
- Add a renderer regression test for passive notification hover.
- Keep action-bearing notification cards interactive.
- Run the targeted overlay notification and mouse-ignore tests.
@@ -2,7 +2,7 @@
  "name": "subminer",
  "productName": "SubMiner",
  "desktopName": "SubMiner.desktop",
-  "version": "0.18.0-beta.2",
+  "version": "0.18.0",
  "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
  "packageManager": "bun@1.3.5",
  "main": "dist/main-entry.js",
@@ -21,17 +21,24 @@
 ### Fixed
 - **Character Name Highlighting in Subtitles**
  - Fixed unspaced Japanese names (e.g. 東紫乃, 渡辺真奈美) being split at the wrong point, which left surnames like 東 and 渡辺 without their character portrait or hover lookup.
-  - Fixed names getting cut off or losing their highlight when caught by the subtitle scanner's punctuation handling, or stripped entirely when grammar tagging misclassified the name token.
+  - Fixed names getting cut off or losing their highlight when caught by the subtitle scanner's punctuation handling, misclassified by grammar tagging, or swallowed entirely by a longer generic dictionary match (e.g. ヨータ disappearing inside a false とヨー match).
+  - Fixed a single unrecognized word in a subtitle line (like a stray interjection) causing character-name highlighting to drop for the whole line instead of just that word.
  - No action needed — existing data upgrades automatically the next time a matching name is seen.
 - **Known-Word Highlighting**
  - Words are no longer marked "known" (green) just because they share spelling with a known Anki card that actually teaches a different reading (e.g. 床 read as とこ no longer falsely matches a known 床/ゆか card).
+  - Kanji words are also no longer marked known just because a different mined word happens to share their reading (e.g. 渓谷/けいこく no longer falsely matches a known 警告/けいこく card).
  - Single-kana grammar tokens (particles like よ, え) no longer borrow an unrelated card's reading and get falsely painted as known.
  - Stats sessions now correctly reflect known-word counts again after the reading-aware matching upgrade, instead of showing 0 everywhere.
+- **Annotation Highlighting Refinements**
+  - Restored frequency/JLPT highlighting and vocabulary-stat counting for words like 確かに and やはり, which were wrongly treated as grammar noise.
+  - Kanji nouns that MeCab tags as "non-independent" (e.g. 日, 点, 以外) also keep their highlighting and stats counting again.
+  - Suffix-only tokens (e.g. さん, れる) are now excluded from JLPT/frequency highlighting by default to match how particles and interjections are treated; known-word highlighting for them still works, and this is configurable.
 - **Unparsed Subtitle Text**
  - Subtitle text the dictionary can't recognize (like a truncated verb form) is now still hoverable for lookup and correctly counted toward a sentence's difficulty, instead of showing as dead, non-interactive text.
 - **Kiku Manual Field Grouping**
  - Fixed the field-grouping dialog getting stuck invisible behind fullscreen video on Hyprland/Wayland, and failing silently on repeated attempts after the first use.
-  - Fixed a duplicate "Field grouping cancelled" notification appearing when grouping was cancelled via the trigger shortcut.
+  - Fixed a timed-out or failed grouping request leaving an invisible, stuck dialog covering the video; it now closes automatically so the overlay recovers.
+  - Fixed a duplicate "Field grouping cancelled" notification appearing when grouping was cancelled via the trigger shortcut, and added a proper error message for the previously-silent case where the original card can no longer be loaded.
 - **Secondary Subtitles**
  - Karaoke-style secondary subtitles (common in opening/ending songs) no longer spam dozens of lines down the screen; repeated lines are now collapsed and the subtitle area is capped to a strip at the top.
 - **YouTube Extraction**
@@ -59,7 +66,8 @@
 - fix(overlay): resolve unspaced Japanese name splits and scan recovery by @ksyasuda in #146
 - fix(tokenizer): prevent grammar tokens from borrowing known-word highlight via unrelated readings by @ksyasuda in #147
 - fix(stats): fetch cover art eagerly at session start instead of on series page visit by @ksyasuda in #148
- fix(stats): parse v3 reading-aware known-word cache in stats server by @ksyasuda in #149
+- fix(overlay): keep frequency/JLPT highlight for kanji non-independent nouns by @ksyasuda in #150
+- fix(tokenizer): greedy name pre-pass to prevent generic matches swallowing character names by @ksyasuda in #151

 ## Installation

@@ -0,0 +1,89 @@
+## Highlights
+### Added
+
+- **Sentence Audio Normalization**
+  - Generated sentence audio is now normalized to -23 LUFS by default, giving mined clips consistent volume across shows.
+  - Clips captured from playback can also mirror mpv's software volume curve, with a limiter to prevent clipping when boosted.
+  - Both behaviors are controlled independently and can be turned off in the Anki Connect media settings.
+
+- **Watch History Browser**
+  - Added `subminer -H` / `--history` to browse local watch history, replay the last episode, continue to the next one, or jump to any past episode.
+  - Works with fzf or rofi; the rofi picker shows AniList cover art already stored in the stats database.
+
+### Changed
+
+- **Known-Word Highlighting Accuracy**
+  - Highlighting now compares subtitle and Anki-card readings, so it no longer confuses homographs like 床/とこ vs 床/ゆか or unrelated kanji that happen to share a reading.
+  - Standalone suffix words such as さん or れる are now excluded from JLPT/frequency/N+1 annotations by default, matching how particles and interjections are already treated (configurable if you'd rather keep them annotated).
+  - Cards without readings still fall back to word-only matching; the highlighting cache upgrades automatically with no action needed.
+
+- **Stats Trend Charts**
+  - Overhauled trend charts with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and sortable multi-column tooltips.
+
+- **New App Icon**
+  - Replaced the SubMiner icon with new pixel-art submarine artwork contributed by an anonymous community member, now used across the app icon, tray, notifications, README, docs site, and stats page.
+
+- **Launcher Preview Layout**
+  - fzf previews now sit below the launcher menu instead of beside it, giving long titles and metadata more horizontal room.
+
+### Fixed
+
+- **Character Name Recognition**
+  - Character dictionaries now correctly split unspaced AniList native names and validate readings, so overlay portraits, highlights, and hover lookups work reliably even without MeCab installed.
+  - Name matches survive punctuation and unmatched text and no longer get overridden by generic dictionary matches or wrongly split from longer words like 空気.
+  - Existing installs regenerate automatically and upgrade to exact splits once MeCab is available — no action needed.
+
+- **Frequency & JLPT Highlighting Coverage**
+  - Content adverbs (確かに, やはり) and kanji nouns MeCab tags as non-independent (日, 点, 以外) are now correctly included in frequency/JLPT highlighting and vocabulary stats.
+  - Lexicalized kana expressions like かといって keep their frequency annotations, while interjections, pronouns, and pure grammar fragments are still filtered out as noise.
+
+- **Unparsed Text Hover Lookup**
+  - Subtitle text Yomitan can't fully parse — truncated inflections like とこ戻ろ… or elongation runs like ぅ～ — is hoverable again for dictionary lookup.
+  - These runs stay excluded from frequency/JLPT highlighting and vocabulary stats, same as bracketed captions and punctuation-only text.
+
+- **Karaoke-Style Secondary Subtitles**
+  - Secondary subtitles no longer flood the screen with dozens of one-syllable lines during karaoke-style openings and endings.
+  - Repeated events now collapse into a single line, and the secondary subtitle area stays capped to a strip at the top.
+
+- **Kiku Field Grouping Reliability**
+  - The manual field-grouping dialog now stays above fullscreen mpv on Hyprland/Wayland and keeps working across repeated attempts.
+  - Abandoned grouping windows close automatically after a timeout or failure, and each attempt now reports a clear success or error, including when the original card can no longer be loaded.
+
+- **Background Stats Server Startup**
+  - Background `subminer app` launches now start the stats server automatically when enabled, and skip startup if one is already running.
+
+- **AniList Cover Art Timing**
+  - Stats now fetches the best-match AniList cover as soon as a new series starts playing, so artwork appears in the timeline immediately instead of only after visiting the series page.
+  - Existing series missing art get backfilled automatically on the next Stats page visit.
+
+- **YouTube Direct Stream Playback**
+  - Fixed direct YouTube stream extraction so mpv's EDL stream URLs are parsed correctly, preventing corrupted signed video URLs and the resulting ffmpeg 403 errors.
+
+## What's Changed
+
+- fix(youtube): parse mpv EDL stream URLs with byte-length guards by @ksyasuda in #134
+- Normalize generated Anki audio by default by @ksyasuda in #135
+- feat(launcher): add -H/--history command to browse local watch history by @ksyasuda in #136
+- fix(overlay): prevent field grouping modal from freezing overlay on Hyprland by @ksyasuda in #138
+- fix(overlay): collapse karaoke syllable spam in secondary subtitles by @ksyasuda in #139
+- feat(stats): Trends dashboard overhaul — title visibility, ranking modes, calendar-accurate windows, tooltips by @ksyasuda in #140
+- feat(branding): replace app icon with contributed pixel-art set by @ksyasuda in #141
+- feat(anki): reading-aware known-word matching (cache v3) by @ksyasuda in #142
+- fix(stats): start stats server on background app launch by @ksyasuda in #144
+- fix(tokenizer): keep unparsed Yomitan tokens hoverable by @ksyasuda in #145
+- fix(overlay): resolve unspaced Japanese name splits and scan recovery by @ksyasuda in #146
+- fix(tokenizer): prevent grammar tokens from borrowing known-word highlight via unrelated readings by @ksyasuda in #147
+- fix(stats): fetch cover art eagerly at session start instead of on series page visit by @ksyasuda in #148
+
+## Installation
+
+See the README and docs/installation guide for full setup steps.
+
+## Assets
+
+- Linux: `SubMiner.AppImage`
+- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
+- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
+- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
+
+Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
@@ -1213,6 +1213,102 @@ test('writeChangelogArtifacts appends contributor attribution and a new-contribu
  }
 });

+test('writeChangelogArtifacts skips contributor attribution in GitHub Actions without a token', async () => {
+  const { writeChangelogArtifacts } = await loadModule();
+  const workspace = createWorkspace('release-notes-actions-no-token');
+  const projectRoot = path.join(workspace, 'SubMiner');
+  const originalActions = process.env.GITHUB_ACTIONS;
+  const originalGhToken = process.env.GH_TOKEN;
+  const originalGithubToken = process.env.GITHUB_TOKEN;
+  const originalPath = process.env.PATH;
+  const originalWarn = console.warn;
+  const warnings: string[] = [];
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(path.join(projectRoot, 'CHANGELOG.md'), '# Changelog\n', 'utf8');
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: added', 'area: release', '', '- Added a feature.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    process.env.GITHUB_ACTIONS = 'true';
+    delete process.env.GH_TOKEN;
+    delete process.env.GITHUB_TOKEN;
+    process.env.PATH = workspace;
+    console.warn = (message?: unknown) => {
+      warnings.push(String(message));
+    };
+
+    writeChangelogArtifacts({
+      cwd: projectRoot,
+      version: '0.6.0',
+      date: '2026-05-06',
+      deps: { runClaude: defaultStubClaude().runClaude },
+    });
+
+    assert.deepEqual(warnings, []);
+    const releaseNotes = fs.readFileSync(
+      path.join(projectRoot, 'release', 'release-notes.md'),
+      'utf8',
+    );
+    assert.doesNotMatch(releaseNotes, /## What's Changed/);
+  } finally {
+    console.warn = originalWarn;
+    if (originalActions === undefined) {
+      delete process.env.GITHUB_ACTIONS;
+    } else {
+      process.env.GITHUB_ACTIONS = originalActions;
+    }
+    if (originalGhToken === undefined) {
+      delete process.env.GH_TOKEN;
+    } else {
+      process.env.GH_TOKEN = originalGhToken;
+    }
+    if (originalGithubToken === undefined) {
+      delete process.env.GITHUB_TOKEN;
+    } else {
+      process.env.GITHUB_TOKEN = originalGithubToken;
+    }
+    if (originalPath === undefined) {
+      delete process.env.PATH;
+    } else {
+      process.env.PATH = originalPath;
+    }
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('shouldSkipDefaultContributionLookup skips GitHub Actions without a gh token', async () => {
+  const { shouldSkipDefaultContributionLookup } = await loadModule();
+
+  assert.equal(
+    shouldSkipDefaultContributionLookup({
+      GITHUB_ACTIONS: 'true',
+      GH_TOKEN: undefined,
+      GITHUB_TOKEN: undefined,
+    }),
+    true,
+  );
+  assert.equal(
+    shouldSkipDefaultContributionLookup({
+      GITHUB_ACTIONS: 'true',
+      GH_TOKEN: 'ghs_test',
+      GITHUB_TOKEN: undefined,
+    }),
+    false,
+  );
+  assert.equal(
+    shouldSkipDefaultContributionLookup({
+      GITHUB_ACTIONS: undefined,
+      GH_TOKEN: undefined,
+      GITHUB_TOKEN: undefined,
+    }),
+    false,
+  );
+});
+
 test('writeReleaseNotesForVersion preserves committed contributor attribution before installation', async () => {
  const { writeReleaseNotesForVersion } = await loadModule();
  const workspace = createWorkspace('release-notes-preserve-attribution');
@@ -345,6 +345,12 @@ function resolveFragmentRelativePath(fragmentPath: string, cwd: string): string
  return path.relative(cwd, fragmentPath).split(path.sep).join('/');
 }

+export function shouldSkipDefaultContributionLookup(
+  env: Partial<Record<'GITHUB_ACTIONS' | 'GH_TOKEN' | 'GITHUB_TOKEN', string>> = process.env,
+): boolean {
+  return env.GITHUB_ACTIONS === 'true' && !env.GH_TOKEN && !env.GITHUB_TOKEN;
+}
+
 // Walks git history + the GitHub API to attribute each released fragment to the
 // PR (and author) that introduced it. One git call and one gh call per fragment,
 // plus one gh call per unique author for the first-contribution check. Best
@@ -354,6 +360,9 @@ function defaultResolveContributions(fragmentPaths: string[], cwd: string): Cont
  if (fragmentPaths.length === 0) {
    return [];
  }
+  if (shouldSkipDefaultContributionLookup()) {
+    return [];
+  }

  try {
    const slug = execFileSync(
@@ -573,6 +573,8 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
        endTime: number,
        audioPadding?: number,
        audioStreamIndex?: number,
+        normalizeAudio?: boolean,
+        volumeScale?: number,
      ) => Promise<Buffer>;
      generateScreenshot: (path: MediaInput) => Promise<Buffer>;
    };
@@ -587,6 +589,7 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
      imageFieldName?: string;
      generateAudio: boolean;
      generateImage: boolean;
+      volumeScale?: number;
    }) => void;
  };
  internals.client = {
@@ -606,9 +609,17 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
    },
  };
  internals.mediaGenerator = {
-    generateAudio: async (mediaPath, _startTime, _endTime, _audioPadding, audioStreamIndex) => {
+    generateAudio: async (
+      mediaPath,
+      _startTime,
+      _endTime,
+      _audioPadding,
+      audioStreamIndex,
+      _normalizeAudio,
+      volumeScale,
+    ) => {
      mediaInputs.push(
-        `audio:${describeMediaInputForTest(mediaPath)}:${audioStreamIndex ?? 'auto'}`,
+        `audio:${describeMediaInputForTest(mediaPath)}:${audioStreamIndex ?? 'auto'}:${volumeScale}`,
      );
      return Buffer.from('audio');
    },
@@ -628,6 +639,7 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
    imageFieldName: 'Picture',
    generateAudio: true,
    generateImage: true,
+    volumeScale: 0.25,
  });
  internals.queuePendingYoutubeMediaUpdate({
    sourceUrl: 'https://youtu.be/abc123',
@@ -640,14 +652,15 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
    imageFieldName: 'Picture',
    generateAudio: true,
    generateImage: true,
+    volumeScale: 0.8,
  });

  await integration.handleYoutubeMediaCacheReady('https://youtu.be/abc123', '/tmp/media.mkv');

  assert.deepEqual(mediaInputs, [
-    'audio:/tmp/media.mkv:youtube-cache:auto',
+    'audio:/tmp/media.mkv:youtube-cache:auto:0.25',
    'image:/tmp/media.mkv:youtube-cache',
-    'audio:/tmp/media.mkv:youtube-cache:auto',
+    'audio:/tmp/media.mkv:youtube-cache:auto:0.8',
    'image:/tmp/media.mkv:youtube-cache',
  ]);
  assert.deepEqual(
@@ -771,6 +784,8 @@ test('AnkiIntegration reports partial queued YouTube media updates separately fr
 test('AnkiIntegration queues YouTube media updates against recovered source URLs', async () => {
  const updatedNotes: Array<{ noteId: number; fields: Record<string, string> }> = [];
  const storedMedia: string[] = [];
+  const audioVolumeScales: Array<number | undefined> = [];
+  let mpvVolume = 30;

  const integration = new AnkiIntegration(
    {
@@ -787,6 +802,10 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
      currentSubStart: 10,
      currentSubEnd: 12,
      currentTimePos: 11,
+      requestProperty: async (name: string) => {
+        assert.equal(name, 'volume');
+        return mpvVolume;
+      },
    } as never,
    () => undefined,
    undefined,
@@ -807,7 +826,15 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
      storeMediaFile: (filename: string) => Promise<void>;
    };
    mediaGenerator: {
-      generateAudio: () => Promise<Buffer>;
+      generateAudio: (
+        path: MediaInput,
+        startTime: number,
+        endTime: number,
+        audioPadding?: number,
+        audioStreamIndex?: number,
+        normalizeAudio?: boolean,
+        volumeScale?: number,
+      ) => Promise<Buffer>;
      generateScreenshot: () => Promise<Buffer>;
    };
    queuePendingYoutubeMediaUpdateForNote: (job: {
@@ -834,7 +861,18 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
    },
  };
  internals.mediaGenerator = {
-    generateAudio: async () => Buffer.from('audio'),
+    generateAudio: async (
+      _path,
+      _startTime,
+      _endTime,
+      _audioPadding,
+      _audioStreamIndex,
+      _normalizeAudio,
+      volumeScale,
+    ) => {
+      audioVolumeScales.push(volumeScale);
+      return Buffer.from('audio');
+    },
    generateScreenshot: async () => Buffer.from('image'),
  };
  internals.showNotification = async () => undefined;
@@ -850,6 +888,7 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
    },
    label: 'resolved source',
  });
+  mpvVolume = 90;
  await integration.handleYoutubeMediaCacheReady('https://youtu.be/abc123', '/tmp/media.mkv');

  assert.equal(queued, true);
@@ -858,6 +897,7 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
  assert.match(updatedNotes[0]?.fields.SentenceAudio ?? '', /^\[sound:audio_/);
  assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image_/);
  assert.equal(storedMedia.length, 2);
+  assert.deepEqual(audioVolumeScales, [0.3 ** 3]);
 });

 test('AnkiIntegration passes audio normalization config for ready cached YouTube audio', async () => {
@@ -865,7 +905,9 @@ test('AnkiIntegration passes audio normalization config for ready cached YouTube
    path: string;
    audioStreamIndex?: number;
    normalizeAudio?: boolean;
+    volumeScale?: number;
  }> = [];
+  const requestedProperties: string[] = [];

  const integration = new AnkiIntegration(
    {
@@ -881,6 +923,10 @@ test('AnkiIntegration passes audio normalization config for ready cached YouTube
      currentSubStart: 10,
      currentSubEnd: 12,
      currentTimePos: 11,
+      requestProperty: async (name: string) => {
+        requestedProperties.push(name);
+        return 55;
+      },
    } as never,
    () => undefined,
    undefined,
@@ -902,6 +948,7 @@ test('AnkiIntegration passes audio normalization config for ready cached YouTube
        audioPadding?: number,
        audioStreamIndex?: number,
        normalizeAudio?: boolean,
+        volumeScale?: number,
      ) => Promise<Buffer>;
    };
    generateAudio: () => Promise<Buffer | null>;
@@ -914,19 +961,22 @@ test('AnkiIntegration passes audio normalization config for ready cached YouTube
      _audioPadding,
      audioStreamIndex,
      normalizeAudio,
+      volumeScale,
    ) => {
-      audioCalls.push({ path: path.path, audioStreamIndex, normalizeAudio });
+      audioCalls.push({ path: path.path, audioStreamIndex, normalizeAudio, volumeScale });
      return Buffer.from('audio');
    },
  };

  await internals.generateAudio();

+  assert.deepEqual(requestedProperties, ['volume']);
  assert.deepEqual(audioCalls, [
    {
      path: '/tmp/subminer-youtube-media-cache/media.mkv',
      audioStreamIndex: undefined,
      normalizeAudio: false,
+      volumeScale: 0.55 ** 3,
    },
  ]);
 });
@@ -73,6 +73,7 @@ import type {
  PendingYoutubeMediaQueueFailedOptions,
  PendingYoutubeMediaQueueReadyOptions,
 } from './anki-integration/pending-youtube-media-queue';
+import { resolveMpvVolumeScale } from './anki-integration/mpv-volume';

 const log = createLogger('anki').child('integration');

@@ -341,14 +342,23 @@ export class AnkiIntegration {
        storeMediaFile: (filename, data) => this.client.storeMediaFile(filename, data),
      },
      mediaGenerator: {
-        generateAudio: (videoPath, startTime, endTime, audioPadding, audioStreamIndex) =>
+        generateAudio: (
+          videoPath,
+          startTime,
+          endTime,
+          audioPadding,
+          audioStreamIndex,
+          normalizeAudio,
+          volumeScale,
+        ) =>
          this.mediaGenerator.generateAudio(
            videoPath,
            startTime,
            endTime,
            audioPadding,
            audioStreamIndex,
-            this.config.media?.normalizeAudio !== false,
+            normalizeAudio,
+            volumeScale,
          ),
        generateScreenshot: (videoPath, timestamp, options) =>
          this.mediaGenerator.generateScreenshot(videoPath, timestamp, options),
@@ -373,6 +383,7 @@ export class AnkiIntegration {
      mergeFieldValue: (existing, newValue, overwrite) =>
        this.mergeFieldValue(existing, newValue, overwrite),
      getAnimatedImageLeadInSeconds: (noteInfo) => this.getAnimatedImageLeadInSeconds(noteInfo),
+      getMpvVolumeScale: () => this.getMpvVolumeScale(),
      generateAudioFilename: () => this.generateAudioFilename(),
      generateImageFilename: () => this.generateImageFilename(),
      formatMiscInfoPatternForMediaPath: (
@@ -496,14 +507,23 @@ export class AnkiIntegration {
        retrieveMediaFile: (filename) => this.client.retrieveMediaFile(filename),
      },
      mediaGenerator: {
-        generateAudio: (videoPath, startTime, endTime, audioPadding, audioStreamIndex) =>
+        generateAudio: (
+          videoPath,
+          startTime,
+          endTime,
+          audioPadding,
+          audioStreamIndex,
+          normalizeAudio,
+          volumeScale,
+        ) =>
          this.mediaGenerator.generateAudio(
            videoPath,
            startTime,
            endTime,
            audioPadding,
            audioStreamIndex,
-            this.config.media?.normalizeAudio !== false,
+            normalizeAudio,
+            volumeScale,
          ),
        generateScreenshot: (videoPath, timestamp, options) =>
          this.mediaGenerator.generateScreenshot(videoPath, timestamp, options),
@@ -703,8 +723,12 @@ export class AnkiIntegration {
    });
  }

-  isKnownWord(text: string, reading?: string): boolean {
-    return this.knownWordCache.isKnownWord(text, reading);
+  isKnownWord(
+    text: string,
+    reading?: string,
+    options?: { allowReadingOnlyMatch?: boolean },
+  ): boolean {
+    return this.knownWordCache.isKnownWord(text, reading, options);
  }

  getKnownWordMatchMode(): NPlusOneMatchMode {
@@ -961,6 +985,10 @@ export class AnkiIntegration {
    );
  }

+  private async getMpvVolumeScale(): Promise<number | undefined> {
+    return resolveMpvVolumeScale(this.mpvClient, this.config.media?.mirrorMpvVolume !== false);
+  }
+
  async handleYoutubeMediaCacheReady(
    sourceUrl: string,
    cachedPath: string,
@@ -999,6 +1027,7 @@ export class AnkiIntegration {
      this.config.media?.audioPadding,
      resolveAudioStreamIndexForMediaGeneration(videoPath, this.mpvClient.currentAudioStreamIndex),
      this.config.media?.normalizeAudio !== false,
+      await this.getMpvVolumeScale(),
    );
  }

@@ -10,6 +10,8 @@ test('sentence card writes generated audio only to sentence audio field', async
  const addedFields: Record<string, string>[] = [];
  const updatedFields: Record<string, string>[] = [];
  const storedMedia: string[] = [];
+  const requestedProperties: string[] = [];
+  const audioVolumeScales: Array<number | undefined> = [];

  const deps: CardCreationDeps = {
    getConfig: () =>
@@ -24,6 +26,7 @@ test('sentence card writes generated audio only to sentence audio field', async
        media: {
          generateAudio: true,
          generateImage: false,
+          mirrorMpvVolume: true,
          maxMediaDuration: 30,
        },
        behavior: {},
@@ -39,6 +42,10 @@ test('sentence card writes generated audio only to sentence audio field', async
        currentSubEnd: 14,
        currentTimePos: 13,
        currentAudioStreamIndex: 0,
+        requestProperty: async (name: string) => {
+          requestedProperties.push(name);
+          return 40;
+        },
      }) as never,
    client: {
      addNote: async (_deck, _modelName, fields) => {
@@ -68,7 +75,18 @@ test('sentence card writes generated audio only to sentence audio field', async
      retrieveMediaFile: async () => '',
    },
    mediaGenerator: {
-      generateAudio: async () => Buffer.from('audio'),
+      generateAudio: async (
+        _path,
+        _startTime,
+        _endTime,
+        _audioPadding,
+        _audioStreamIndex,
+        _normalizeAudio,
+        volumeScale,
+      ) => {
+        audioVolumeScales.push(volumeScale);
+        return Buffer.from('audio');
+      },
      generateScreenshot: async () => null,
      generateAnimatedImage: async () => null,
    },
@@ -124,6 +142,8 @@ test('sentence card writes generated audio only to sentence audio field', async
    Expression: '字幕',
  });
  assert.equal(storedMedia.length, 1);
+  assert.deepEqual(requestedProperties, ['volume']);
+  assert.deepEqual(audioVolumeScales, [0.4 ** 3]);
  const mediaUpdate = updatedFields.find((fields) => 'SentenceAudio' in fields);
  assert.equal(mediaUpdate?.SentenceAudio, `[sound:${storedMedia[0]}]`);
  assert.equal('ExpressionAudio' in mediaUpdate!, false);
@@ -525,6 +525,7 @@ test('CardCreationService queues YouTube media when required cache is not ready'
    miscInfoFieldName?: string;
    generateAudio: boolean;
    generateImage: boolean;
+    volumeScale?: number;
  }> = [];
  let streamRequests = 0;

@@ -556,7 +557,10 @@ test('CardCreationService queues YouTube media when required cache is not ready'
        currentSubEnd: 12,
        currentTimePos: 11,
        currentAudioStreamIndex: 2,
-        requestProperty: async () => {
+        requestProperty: async (name: string) => {
+          if (name === 'volume') {
+            return 35;
+          }
          streamRequests += 1;
          return 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123';
        },
@@ -652,6 +656,7 @@ test('CardCreationService queues YouTube media when required cache is not ready'
      miscInfoFieldName: 'MiscInfo',
      generateAudio: true,
      generateImage: true,
+      volumeScale: 0.35 ** 3,
    },
  ]);
  assert.deepEqual(updates, []);
@@ -17,6 +17,7 @@ import {
 } from './media-source';
 import { shouldMarkWordAndSentenceCard } from './note-field-utils';
 import type { PendingYoutubeMediaUpdate } from './pending-youtube-media';
+import { resolveMpvVolumeScale } from './mpv-volume';

 const log = createLogger('anki').child('integration.card-creation');

@@ -66,6 +67,7 @@ interface CardCreationMediaGenerator {
    audioPadding?: number,
    audioStreamIndex?: number,
    normalizeAudio?: boolean,
+    volumeScale?: number,
  ): Promise<Buffer | null>;
  generateScreenshot(
    path: MediaInput,
@@ -714,6 +716,12 @@ export class CardCreationService {

        const label = sentence.length > 30 ? sentence.substring(0, 30) + '...' : sentence;
        if (shouldQueuePendingYoutubeMedia) {
+          const volumeScale = generateAudio
+            ? await resolveMpvVolumeScale(
+                mpvClient,
+                this.deps.getConfig().media?.mirrorMpvVolume !== false,
+              )
+            : undefined;
          this.deps.queuePendingYoutubeMediaUpdate?.({
            sourceUrl:
              trimToNonEmptyString(await this.deps.getYoutubeMediaSourceUrl?.()) ??
@@ -727,6 +735,7 @@ export class CardCreationService {
            miscInfoFieldName: resolvedMiscInfoField ?? undefined,
            generateAudio,
            generateImage,
+            volumeScale,
          });
          await this.deps.showNotification(noteId, label, 'media queued');
          return true;
@@ -844,6 +853,10 @@ export class CardCreationService {
        mpvClient.currentAudioStreamIndex ?? undefined,
      ),
      this.deps.getConfig().media?.normalizeAudio !== false,
+      await resolveMpvVolumeScale(
+        mpvClient,
+        this.deps.getConfig().media?.mirrorMpvVolume !== false,
+      ),
    );
  }

@@ -734,6 +734,42 @@ test('KnownWordCacheManager disambiguates known words by note reading', async ()
  }
 });

+test('KnownWordCacheManager suppresses reading-only matches when disallowed', async () => {
+  const config: AnkiConnectConfig = {
+    fields: {
+      word: 'Word',
+    },
+    knownWords: {
+      highlightEnabled: true,
+    },
+  };
+  const { manager, clientState, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    clientState.findNotesResult = [1];
+    clientState.notesInfoResult = [
+      {
+        noteId: 1,
+        fields: {
+          Word: { value: '警告' },
+          'Word Reading': { value: 'けいこく' },
+        },
+      },
+    ];
+
+    await manager.refresh(true);
+
+    // Reading-only match stays available for kana subtitle text…
+    assert.equal(manager.isKnownWord('けいこく'), true);
+    // …but a kanji token's reading (渓谷/けいこく) must not borrow 警告's.
+    assert.equal(manager.isKnownWord('けいこく', undefined, { allowReadingOnlyMatch: false }), false);
+    // Mined word texts still match regardless of the flag.
+    assert.equal(manager.isKnownWord('警告', undefined, { allowReadingOnlyMatch: false }), true);
+  } finally {
+    cleanup();
+  }
+});
+
 test('KnownWordCacheManager does not match single-kana text by reading alone', async () => {
  const config: AnkiConnectConfig = {
    fields: {
@@ -142,7 +142,11 @@ export class KnownWordCacheManager {
    );
  }

-  isKnownWord(text: string, reading?: string): boolean {
+  isKnownWord(
+    text: string,
+    reading?: string,
+    options?: { allowReadingOnlyMatch?: boolean },
+  ): boolean {
    if (!this.isKnownWordCacheEnabled()) {
      return false;
    }
@@ -163,6 +167,14 @@ export class KnownWordCacheManager {
      );
    }

+    // Callers that look up a kanji token's reading (not subtitle text) must
+    // opt out of the reading-only fallback: readingCounts holds readings of
+    // every note including kanji words, so 渓谷's けいこく would match a
+    // mined 警告/けいこく.
+    if (options?.allowReadingOnlyMatch === false) {
+      return false;
+    }
+
    // Reading-only fallback, except for single-kana text: particles and
    // interjections (よ, ね, え…) would otherwise borrow the reading of an
    // unrelated note (夜「よ」, 絵「え」) and count as known.
@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { resolveMpvVolumeScale } from './mpv-volume';
+
+test('resolveMpvVolumeScale converts numeric mpv volume with mpv software volume curve', async () => {
+  const requested: string[] = [];
+
+  const scale = await resolveMpvVolumeScale(
+    {
+      requestProperty: async (name) => {
+        requested.push(name);
+        return 75;
+      },
+    },
+    true,
+  );
+
+  assert.equal(scale, 0.421875);
+  assert.deepEqual(requested, ['volume']);
+});
+
+test('resolveMpvVolumeScale skips mpv when mirroring is disabled', async () => {
+  let requested = false;
+
+  const scale = await resolveMpvVolumeScale(
+    {
+      requestProperty: async () => {
+        requested = true;
+        return 50;
+      },
+    },
+    false,
+  );
+
+  assert.equal(scale, undefined);
+  assert.equal(requested, false);
+});
+
+test('resolveMpvVolumeScale falls back to unity for missing, failed, or invalid values', async () => {
+  assert.equal(await resolveMpvVolumeScale({}, true), 1);
+  assert.equal(
+    await resolveMpvVolumeScale(
+      {
+        requestProperty: async () => {
+          throw new Error('disconnected');
+        },
+      },
+      true,
+    ),
+    1,
+  );
+  assert.equal(await resolveMpvVolumeScale({ requestProperty: async () => '50' }, true), 1);
+  assert.equal(await resolveMpvVolumeScale({ requestProperty: async () => Number.NaN }, true), 1);
+  assert.equal(await resolveMpvVolumeScale({ requestProperty: async () => -1 }, true), 1);
+});
@@ -0,0 +1,26 @@
+export interface MpvVolumePropertySource {
+  requestProperty?: (name: string) => Promise<unknown>;
+}
+
+export async function resolveMpvVolumeScale(
+  mpvClient: MpvVolumePropertySource,
+  enabled: boolean,
+): Promise<number | undefined> {
+  if (!enabled) {
+    return undefined;
+  }
+
+  if (!mpvClient.requestProperty) {
+    return 1;
+  }
+
+  try {
+    const volume = await mpvClient.requestProperty('volume');
+    if (typeof volume !== 'number' || !Number.isFinite(volume) || volume < 0) {
+      return 1;
+    }
+    return (volume / 100) ** 3;
+  } catch {
+    return 1;
+  }
+}
@@ -35,6 +35,7 @@ function createDeps(
    resolveConfiguredFieldName: () => 'Picture',
    mergeFieldValue: (_existing, newValue) => newValue,
    getAnimatedImageLeadInSeconds: async () => 0,
+    getMpvVolumeScale: async () => 1,
    generateAudioFilename: () => 'audio.mp3',
    generateImageFilename: () => 'image.webp',
    formatMiscInfoPatternForMediaPath: () => '',
@@ -46,6 +46,7 @@ export interface PendingYoutubeMediaQueueDeps {
  ) => string | null;
  mergeFieldValue: (existing: string, newValue: string, overwrite: boolean) => string;
  getAnimatedImageLeadInSeconds: (noteInfo: PendingYoutubeMediaNoteInfo) => Promise<number>;
+  getMpvVolumeScale: () => Promise<number | undefined>;
  generateAudioFilename: () => string;
  generateImageFilename: () => string;
  formatMiscInfoPatternForMediaPath: (
@@ -126,6 +127,9 @@ export class PendingYoutubeMediaQueue {

    const config = this.deps.getConfig();
    const mediaRange = this.deps.getSubtitleMediaRange(job.context);
+    const volumeScale = shouldGenerateAudio(config)
+      ? await this.deps.getMpvVolumeScale()
+      : undefined;
    this.enqueue({
      sourceUrl,
      noteId: job.noteId,
@@ -143,6 +147,7 @@ export class PendingYoutubeMediaQueue {
        this.deps.resolveConfiguredFieldName(job.noteInfo, config.fields?.miscInfo) ?? undefined,
      generateAudio: shouldGenerateAudio(config),
      generateImage: shouldGenerateImage(config),
+      volumeScale,
    });
    return true;
  }
@@ -273,6 +278,7 @@ export class PendingYoutubeMediaQueue {
          config.media?.audioPadding,
          undefined,
          config.media?.normalizeAudio !== false,
+          job.volumeScale,
        );
        if (audioBuffer) {
          await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
@@ -9,6 +9,7 @@ export interface PendingYoutubeMediaUpdate {
  miscInfoFieldName?: string;
  generateAudio: boolean;
  generateImage: boolean;
+  volumeScale?: number;
 }

 function trimToNonEmptyString(value: unknown): string | null {
@@ -93,6 +93,7 @@ test('loads defaults when config is missing', () => {
    systemPrompt: '',
  });
  assert.equal(config.ankiConnect.media.normalizeAudio, true);
+  assert.equal(config.ankiConnect.media.mirrorMpvVolume, true);
  assert.equal(config.startupWarmups.lowPowerMode, false);
  assert.equal(config.startupWarmups.mecab, true);
  assert.equal(config.startupWarmups.yomitanExtension, true);
@@ -168,6 +169,31 @@ test('loads defaults when config is missing', () => {
  assert.equal(config.mpv.aniskipButtonKey, 'TAB');
 });

+test('rejects invalid mpv volume mirroring values', () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "media": {
+          "mirrorMpvVolume": "false"
+        }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const service = new ConfigService(dir);
+
+  assert.equal(
+    service.getConfig().ankiConnect.media.mirrorMpvVolume,
+    DEFAULT_CONFIG.ankiConnect.media.mirrorMpvVolume,
+  );
+  assert.ok(
+    service.getWarnings().some((warning) => warning.path === 'ankiConnect.media.mirrorMpvVolume'),
+  );
+});
+
 test('parses updates config and warns on invalid values', () => {
  const validDir = makeTempDir();
  fs.writeFileSync(
@@ -52,6 +52,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
      animatedCrf: 35,
      syncAnimatedImageToWordAudio: true,
      normalizeAudio: true,
+      mirrorMpvVolume: true,
      audioPadding: 0,
      fallbackDuration: 3.0,
      maxMediaDuration: 30,
@@ -111,6 +111,7 @@ test('config option registry includes critical paths and has unique entries', ()
    'ankiConnect.enabled',
    'subtitleStyle.nameMatchEnabled',
    'ankiConnect.media.normalizeAudio',
+    'ankiConnect.media.mirrorMpvVolume',
    'anilist.characterDictionary.collapsibleSections.description',
    'mpv.executablePath',
    'mpv.launchMode',
@@ -185,7 +185,15 @@ export function buildIntegrationConfigOptionRegistry(
      path: 'ankiConnect.media.normalizeAudio',
      kind: 'boolean',
      defaultValue: defaultConfig.ankiConnect.media.normalizeAudio,
-      description: 'Normalize generated sentence audio loudness during media extraction.',
+      description:
+        'Normalize generated sentence audio loudness during media extraction. Changes apply live.',
+    },
+    {
+      path: 'ankiConnect.media.mirrorMpvVolume',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.mirrorMpvVolume,
+      description:
+        "Apply mpv's current software volume curve to generated sentence audio. Changes apply live.",
    },
    {
      path: 'ankiConnect.media.generateImage',
@@ -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, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.',
+      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping 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.',
    ],
@@ -106,6 +106,22 @@ export function applyAnkiConnectResolution(context: ResolveContext): void {
    },
  };

+  if (hasOwn(media, 'mirrorMpvVolume')) {
+    const parsed = asBoolean(media.mirrorMpvVolume);
+    if (parsed === undefined) {
+      context.resolved.ankiConnect.media.mirrorMpvVolume =
+        DEFAULT_CONFIG.ankiConnect.media.mirrorMpvVolume;
+      context.warn(
+        'ankiConnect.media.mirrorMpvVolume',
+        media.mirrorMpvVolume,
+        context.resolved.ankiConnect.media.mirrorMpvVolume,
+        'Expected boolean.',
+      );
+    } else {
+      context.resolved.ankiConnect.media.mirrorMpvVolume = parsed;
+    }
+  }
+
  if (hasOwn(behavior, 'notificationType')) {
    const parsed = asNotificationType(behavior.notificationType);
    if (parsed === undefined) {
@@ -165,6 +165,15 @@ test('settings registry exposes specialized controls for config-assisted inputs'
  assert.equal(field('discordPresence.presenceStyle').control, 'select');
 });

+test('settings registry exposes mpv volume mirroring as a mining toggle', () => {
+  const volumeField = field('ankiConnect.media.mirrorMpvVolume');
+
+  assert.equal(volumeField.category, 'mining-anki');
+  assert.equal(volumeField.section, 'Media Capture');
+  assert.equal(volumeField.control, 'boolean');
+  assert.equal(volumeField.defaultValue, true);
+});
+
 test('settings registry exposes YouTube media cache mode as a labeled select', () => {
  const mediaCacheMode = field('youtube.mediaCache.mode');
  const mediaCacheMaxHeight = field('youtube.mediaCache.maxHeight');
@@ -313,6 +322,8 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
    'subsync.replace',
    'ankiConnect.behavior.autoUpdateNewCards',
    'ankiConnect.deck',
+    'ankiConnect.media.normalizeAudio',
+    'ankiConnect.media.mirrorMpvVolume',
    'ankiConnect.knownWords.highlightEnabled',
    'ankiConnect.knownWords.refreshMinutes',
    'ankiConnect.knownWords.addMinedWordsImmediately',
@@ -236,6 +236,7 @@ const LABEL_OVERRIDES: Record<string, string> = {
  'mpv.pauseUntilOverlayReady': 'Pause Until Overlay Ready',
  'mpv.aniskipEnabled': 'Enable AniSkip',
  'mpv.aniskipButtonKey': 'AniSkip Button Key',
+  'ankiConnect.media.mirrorMpvVolume': 'Mirror mpv Volume',
  'discordPresence.updateIntervalMs': 'Update Interval (ms)',
 };

@@ -671,6 +672,8 @@ function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
    path === 'secondarySub.defaultMode' ||
    path === 'ankiConnect.deck' ||
    path === 'ankiConnect.ai.enabled' ||
+    path === 'ankiConnect.media.normalizeAudio' ||
+    path === 'ankiConnect.media.mirrorMpvVolume' ||
    path === 'ankiConnect.behavior.autoUpdateNewCards' ||
    path === 'ankiConnect.knownWords.highlightEnabled' ||
    path === 'ankiConnect.knownWords.refreshMinutes' ||
@@ -31,6 +31,8 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
  next.jimaku.maxEntryResults = prev.jimaku.maxEntryResults + 1;
  next.subsync.replace = !prev.subsync.replace;
  next.ankiConnect.deck = 'Mining';
+  next.ankiConnect.media.normalizeAudio = !prev.ankiConnect.media.normalizeAudio;
+  next.ankiConnect.media.mirrorMpvVolume = !prev.ankiConnect.media.mirrorMpvVolume;
  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;
@@ -65,6 +67,8 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
      'jimaku.maxEntryResults',
      'subsync.replace',
      'ankiConnect.deck',
+      'ankiConnect.media.normalizeAudio',
+      'ankiConnect.media.mirrorMpvVolume',
      'ankiConnect.behavior.autoUpdateNewCards',
      'ankiConnect.knownWords.highlightEnabled',
      'ankiConnect.knownWords.refreshMinutes',
@@ -68,6 +68,8 @@ const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
  'jimaku',
  'subsync',
  'ankiConnect.deck',
+  'ankiConnect.media.normalizeAudio',
+  'ankiConnect.media.mirrorMpvVolume',
  'ankiConnect.behavior.autoUpdateNewCards',
  'ankiConnect.knownWords.highlightEnabled',
  'ankiConnect.knownWords.refreshMinutes',
@@ -28,6 +28,7 @@ interface YomitanTokenInput {
  frequencyRank?: number;
  isNameMatch?: boolean;
  wordClasses?: string[];
+  isUnparsedRun?: boolean;
 }

 function makeDepsFromYomitanTokens(
@@ -60,6 +61,7 @@ function makeDepsFromYomitanTokens(
                isNameMatch: token.isNameMatch ?? false,
                frequencyRank: token.frequencyRank,
                wordClasses: token.wordClasses,
+                isUnparsedRun: token.isUnparsedRun,
              };
            });
          },
@@ -3486,8 +3488,8 @@ test('tokenizeSubtitle keeps known-word highlight for exact non-independent kanj
  assert.equal(result.tokens?.[1]?.surface, '点');
  assert.equal(result.tokens?.[1]?.isKnown, true);
  assert.equal(result.tokens?.[1]?.isNPlusOneTarget, false);
-  assert.equal(result.tokens?.[1]?.frequencyRank, undefined);
-  assert.equal(result.tokens?.[1]?.jlptLevel, undefined);
+  assert.equal(result.tokens?.[1]?.frequencyRank, 1384);
+  assert.equal(result.tokens?.[1]?.jlptLevel, 'N3');
 });

 test('tokenizeSubtitle keeps mecab-tagged interjections tokenized while clearing annotation metadata', async () => {
@@ -4223,6 +4225,38 @@ test('tokenizeSubtitle clears all annotations for explanatory pondering endings'
  );
 });

+test('tokenizeSubtitle ignores unparsed-run tokens for annotations and N+1', async () => {
+  // もう いるぅ～！: the ぅ～ elongation has no Yomitan dictionary entry; it must
+  // not become the sole N+1 candidate or receive frequency/JLPT annotations.
+  const result = await tokenizeSubtitle(
+    'もう いるぅ～！',
+    makeDepsFromYomitanTokens(
+      [
+        { surface: 'もう', reading: 'もう', headword: 'もう' },
+        { surface: 'いる', reading: 'いる', headword: 'いる' },
+        { surface: 'ぅ～', reading: '', headword: 'ぅ～', isUnparsedRun: true, frequencyRank: 999 },
+      ],
+      {
+        getFrequencyDictionaryEnabled: () => true,
+        getJlptLevel: (text) => (text === 'ぅ～' ? 'N5' : null),
+        isKnownWord: (text) => text === 'もう' || text === 'いる',
+        getMinSentenceWordsForNPlusOne: () => 2,
+        tokenizeWithMecab: async () => null,
+      },
+    ),
+  );
+
+  const filler = result.tokens?.find((token) => token.surface === 'ぅ～');
+  assert.ok(filler);
+  assert.equal(filler?.isNPlusOneTarget, false);
+  assert.equal(filler?.frequencyRank, undefined);
+  assert.equal(filler?.jlptLevel, undefined);
+  assert.equal(
+    result.tokens?.some((token) => token.isNPlusOneTarget),
+    false,
+  );
+});
+
 test('tokenizeSubtitle keeps frequency for content-led merged token with trailing colloquial suffixes', async () => {
  const result = await tokenizeSubtitle(
    '張り切ってんじゃ',
@@ -33,6 +33,15 @@ type MecabTokenEnrichmentFn = (
  mecabTokens: MergedToken[] | null,
 ) => Promise<MergedToken[]>;

+// allowReadingOnlyMatch: false suppresses the cache's reading-only index for
+// lookups that pass a kanji token's reading as the text (see
+// computeTokenKnownStatus in annotation-stage).
+export type KnownWordLookupFn = (
+  text: string,
+  reading?: string,
+  options?: { allowReadingOnlyMatch?: boolean },
+) => boolean;
+
 export interface TokenizerServiceDeps {
  getYomitanExt: () => Extension | null;
  getYomitanSession?: () => Session | null;
@@ -42,7 +51,7 @@ export interface TokenizerServiceDeps {
  setYomitanParserReadyPromise: (promise: Promise<void> | null) => void;
  getYomitanParserInitPromise: () => Promise<boolean> | null;
  setYomitanParserInitPromise: (promise: Promise<boolean> | null) => void;
-  isKnownWord: (text: string, reading?: string) => boolean;
+  isKnownWord: KnownWordLookupFn;
  getKnownWordMatchMode: () => NPlusOneMatchMode;
  getKnownWordsEnabled?: () => boolean;
  getJlptLevel: (text: string) => JlptLevel | null;
@@ -77,7 +86,7 @@ export interface TokenizerDepsRuntimeOptions {
  setYomitanParserReadyPromise: (promise: Promise<void> | null) => void;
  getYomitanParserInitPromise: () => Promise<boolean> | null;
  setYomitanParserInitPromise: (promise: Promise<boolean> | null) => void;
-  isKnownWord: (text: string, reading?: string) => boolean;
+  isKnownWord: KnownWordLookupFn;
  getKnownWordMatchMode: () => NPlusOneMatchMode;
  getKnownWordsEnabled?: () => boolean;
  getJlptLevel: (text: string) => JlptLevel | null;
@@ -129,7 +138,7 @@ const INVISIBLE_SEPARATOR_PATTERN = /[\u200b\u2060\ufeff]/g;
 function getKnownWordLookup(
  deps: TokenizerServiceDeps,
  options: TokenizerAnnotationOptions,
-): (text: string, reading?: string) => boolean {
+): KnownWordLookupFn {
  if (!options.knownWordsEnabled && !options.nPlusOneEnabled) {
    return () => false;
  }
@@ -734,6 +743,7 @@ async function parseWithYomitanInternalParser(
        isNPlusOneTarget: false,
        isNameMatch: token.isNameMatch ?? false,
        frequencyRank: token.frequencyRank,
+        isUnparsedRun: token.isUnparsedRun === true ? true : undefined,
      };
    }),
  );
@@ -208,6 +208,48 @@ test('annotateTokens hides known-word marks while still using known words for N+
  assert.equal(result[2]?.isNPlusOneTarget, true);
 });

+test('shouldExcludeTokenFromSubtitleAnnotations excludes unparsed-run tokens', () => {
+  // 戻 from 「…とこ戻ろ…」: Yomitan had no dictionary entry, headword falls back
+  // to the surface. Without the flag the token passes every other filter.
+  const unflagged = makeToken({ surface: '戻', headword: '戻', reading: '' });
+  assert.equal(shouldExcludeTokenFromSubtitleAnnotations(unflagged), false);
+
+  const flagged = makeToken({ surface: '戻', headword: '戻', reading: '', isUnparsedRun: true });
+  assert.equal(shouldExcludeTokenFromSubtitleAnnotations(flagged), true);
+  assert.equal(shouldExcludeTokenFromVocabularyPersistence(flagged), true);
+});
+
+test('annotateTokens ignores unparsed-run tokens for annotations and N+1', () => {
+  // もう いるぅ～！-style line: the elongation run is the only unknown token and
+  // used to become the sole N+1 candidate despite having no dictionary entry.
+  const tokens = [
+    makeToken({ surface: 'みんな', headword: '皆', reading: 'みんな', startPos: 0, endPos: 3 }),
+    makeToken({ surface: 'とこ', headword: '所', reading: 'とこ', startPos: 3, endPos: 5 }),
+    makeToken({
+      surface: '戻',
+      headword: '戻',
+      reading: '',
+      startPos: 5,
+      endPos: 6,
+      isUnparsedRun: true,
+      frequencyRank: 12,
+    }),
+  ];
+
+  const result = annotateTokens(
+    tokens,
+    makeDeps({
+      isKnownWord: (text) => text === '皆' || text === '所',
+      getJlptLevel: (text) => (text === '戻' ? 'N5' : null),
+    }),
+    { minSentenceWordsForNPlusOne: 2 },
+  );
+
+  assert.equal(result[2]?.isNPlusOneTarget, false);
+  assert.equal(result[2]?.jlptLevel, undefined);
+  assert.equal(result[2]?.frequencyRank, undefined);
+});
+
 test('annotateTokens falls back to reading for known-word matches when headword lookup misses', () => {
  const tokens = [
    makeToken({
@@ -231,6 +273,29 @@ test('annotateTokens falls back to reading for known-word matches when headword
  assert.equal(result[0]?.frequencyRank, 1895);
 });

+test('annotateTokens reading fallback does not match kanji tokens sharing a mined reading', () => {
+  const tokens = [
+    makeToken({
+      surface: '渓谷',
+      headword: '渓谷',
+      reading: 'けいこく',
+      endPos: 2,
+    }),
+  ];
+
+  const result = annotateTokens(
+    tokens,
+    makeDeps({
+      // Mimics the cache with a mined 警告/けいこく: けいこく matches through
+      // the reading-only index unless the lookup opts out of it.
+      isKnownWord: (text, _reading, options) =>
+        text === '警告' || (options?.allowReadingOnlyMatch !== false && text === 'けいこく'),
+    }),
+  );
+
+  assert.equal(result[0]?.isKnown, false);
+});
+
 test('annotateTokens ignores partial furigana readings for known-word fallback', () => {
  const tokens = [
    makeToken({
@@ -575,7 +640,9 @@ test('shouldExcludeTokenFromSubtitleAnnotations keeps lexical tokens outside exp
  assert.equal(shouldExcludeTokenFromSubtitleAnnotations(token), false);
 });

-test('shouldExcludeTokenFromSubtitleAnnotations still excludes lexical non-independent kanji nouns from non-known annotations', () => {
+test('shouldExcludeTokenFromSubtitleAnnotations keeps lexical non-independent kanji nouns', () => {
+  // Yomitan segments 以外/日/方 as standalone vocabulary tokens; MeCab's
+  // 非自立 tag must only suppress kana grammar nouns (こと, もの, とき).
  const token = makeToken({
    surface: '以外',
    headword: '以外',
@@ -586,6 +653,21 @@ test('shouldExcludeTokenFromSubtitleAnnotations still excludes lexical non-indep
    pos3: '副詞可能',
  });

+  assert.equal(shouldExcludeTokenFromSubtitleAnnotations(token), false);
+  assert.equal(shouldExcludeTokenFromVocabularyPersistence(token), false);
+});
+
+test('shouldExcludeTokenFromSubtitleAnnotations still excludes kana non-independent nouns', () => {
+  const token = makeToken({
+    surface: 'こと',
+    headword: 'こと',
+    reading: 'コト',
+    partOfSpeech: PartOfSpeech.noun,
+    pos1: '名詞',
+    pos2: '非自立',
+    pos3: '一般',
+  });
+
  assert.equal(shouldExcludeTokenFromSubtitleAnnotations(token), true);
  assert.equal(shouldExcludeTokenFromVocabularyPersistence(token), true);
 });
@@ -728,15 +810,6 @@ test('shouldExcludeTokenFromVocabularyPersistence excludes common frequency stop
      pos2: '代名詞|副助詞／並立助詞／終助詞',
      pos3: '一般|*',
    }),
-    makeToken({
-      surface: '確かに',
-      headword: '確かに',
-      reading: 'たしかに',
-      partOfSpeech: PartOfSpeech.other,
-      pos1: '名詞|助詞',
-      pos2: '形容動詞語幹|副詞化',
-      pos3: '*',
-    }),
    makeToken({
      surface: 'あなた',
      headword: '貴方',
@@ -753,6 +826,34 @@ test('shouldExcludeTokenFromVocabularyPersistence excludes common frequency stop
  }
 });

+test('content adverbs are not excluded from annotations or vocabulary persistence', () => {
+  const tokens = [
+    makeToken({
+      surface: '確かに',
+      headword: '確かに',
+      reading: 'たしかに',
+      partOfSpeech: PartOfSpeech.other,
+      pos1: '名詞|助詞',
+      pos2: '形容動詞語幹|副詞化',
+      pos3: '*',
+    }),
+    makeToken({
+      surface: 'やはり',
+      headword: 'やはり',
+      reading: 'ヤハリ',
+      partOfSpeech: PartOfSpeech.other,
+      pos1: '副詞',
+      pos2: '一般',
+      pos3: '*',
+    }),
+  ];
+
+  for (const token of tokens) {
+    assert.equal(shouldExcludeTokenFromSubtitleAnnotations(token), false, token.surface);
+    assert.equal(shouldExcludeTokenFromVocabularyPersistence(token), false, token.surface);
+  }
+});
+
 test('shouldExcludeTokenFromSubtitleAnnotations excludes standalone して grammar helper fragments', () => {
  const token = makeToken({
    surface: 'して',
@@ -1402,8 +1503,8 @@ test('annotateTokens keeps known-word status for non-independent kanji noun toke

  assert.equal(result[0]?.isKnown, true);
  assert.equal(result[0]?.isNPlusOneTarget, false);
-  assert.equal(result[0]?.frequencyRank, undefined);
-  assert.equal(result[0]?.jlptLevel, undefined);
+  assert.equal(result[0]?.frequencyRank, 1384);
+  assert.equal(result[0]?.jlptLevel, 'N3');
 });

 test('annotateTokens keeps known-word status for lexical non-independent kanji nouns', () => {
@@ -1431,23 +1532,54 @@ test('annotateTokens keeps known-word status for lexical non-independent kanji n
  );

  assert.equal(result[0]?.isKnown, true);
-  assert.equal(result[0]?.frequencyRank, undefined);
+  assert.equal(result[0]?.frequencyRank, 437);
  assert.equal(result[0]?.isNPlusOneTarget, false);
 });

-test('annotateTokens clears all annotations for non-independent kanji noun tokens under unified gate', () => {
+test('annotateTokens keeps frequency for unknown non-independent kanji noun tokens', () => {
+  // 日 in いい日だったな: MeCab tags it 名詞/非自立 but Yomitan segments it as
+  // a standalone vocabulary token, so frequency highlighting must survive.
  const tokens = [
    makeToken({
-      surface: '者',
-      reading: 'もの',
-      headword: '者',
+      surface: '日',
+      reading: 'ひ',
+      headword: '日',
+      partOfSpeech: PartOfSpeech.noun,
+      pos1: '名詞',
+      pos2: '非自立',
+      pos3: '副詞可能',
+      startPos: 2,
+      endPos: 3,
+      frequencyRank: 718,
+    }),
+  ];
+
+  const result = annotateTokens(
+    tokens,
+    makeDeps({
+      getJlptLevel: (text) => (text === '日' ? 'N4' : null),
+    }),
+    { minSentenceWordsForNPlusOne: 1 },
+  );
+
+  assert.equal(result[0]?.isKnown, false);
+  assert.equal(result[0]?.frequencyRank, 718);
+  assert.equal(result[0]?.jlptLevel, 'N4');
+});
+
+test('annotateTokens still clears annotations for kana non-independent noun tokens', () => {
+  const tokens = [
+    makeToken({
+      surface: 'こと',
+      reading: 'こと',
+      headword: 'こと',
      partOfSpeech: PartOfSpeech.other,
      pos1: '名詞',
      pos2: '非自立',
      pos3: '一般',
      startPos: 0,
-      endPos: 1,
-      frequencyRank: 475,
+      endPos: 2,
+      frequencyRank: 96,
    }),
  ];

@@ -1581,7 +1713,9 @@ test('annotateTokens excludes kana-only composite function/content tokens from f
  const tokens = [
    makeToken({
      surface: 'になれば',
+      reading: 'になれば',
      headword: 'なる',
+      headwordReading: 'なる',
      pos1: '助詞|動詞',
      pos2: '格助詞|自立|接続助詞',
      startPos: 0,
@@ -1598,6 +1732,28 @@ test('annotateTokens excludes kana-only composite function/content tokens from f
  assert.equal(result[0]?.isNPlusOneTarget, false);
 });

+test('annotateTokens keeps frequency for mixed kana tokens whose headword reading covers the token', () => {
+  const tokens = [
+    makeToken({
+      surface: 'かといって',
+      reading: 'カトイッテ',
+      headword: 'かと言って',
+      headwordReading: 'かといって',
+      pos1: '助詞|助詞|動詞|助詞',
+      pos2: '副助詞|格助詞|自立|接続助詞',
+      startPos: 0,
+      endPos: 5,
+      frequencyRank: 4898,
+    }),
+  ];
+
+  const result = annotateTokens(tokens, makeDeps(), {
+    minSentenceWordsForNPlusOne: 1,
+  });
+
+  assert.equal(result[0]?.frequencyRank, 4898);
+});
+
 test('annotateTokens excludes composite tokens when all component pos tags are excluded', () => {
  const tokens = [
    makeToken({
@@ -10,6 +10,7 @@ import {
 import { JlptLevel, MergedToken, NPlusOneMatchMode, PartOfSpeech } from '../../../types';
 import { shouldIgnoreJlptByTerm, shouldIgnoreJlptForMecabPos1 } from '../jlpt-token-filter';
 import {
+  isKanjiNonIndependentNounToken,
  shouldExcludeTokenFromSubtitleAnnotations as sharedShouldExcludeTokenFromSubtitleAnnotations,
  stripSubtitleAnnotationMetadata as sharedStripSubtitleAnnotationMetadata,
 } from './subtitle-annotation-filter';
@@ -25,7 +26,11 @@ const jlptLevelLookupCaches = new WeakMap<
 >();

 export interface AnnotationStageDeps {
-  isKnownWord: (text: string, reading?: string) => boolean;
+  isKnownWord: (
+    text: string,
+    reading?: string,
+    options?: { allowReadingOnlyMatch?: boolean },
+  ) => boolean;
  knownWordMatchMode: NPlusOneMatchMode;
  getJlptLevel: (text: string) => JlptLevel | null;
 }
@@ -94,23 +99,6 @@ function normalizePos2Tag(pos2: string | undefined): string {
  return typeof pos2 === 'string' ? pos2.trim() : '';
 }

-function hasKanjiChar(text: string): boolean {
-  for (const char of text) {
-    const code = char.codePointAt(0);
-    if (code === undefined) {
-      continue;
-    }
-    if (
-      (code >= 0x3400 && code <= 0x4dbf) ||
-      (code >= 0x4e00 && code <= 0x9fff) ||
-      (code >= 0xf900 && code <= 0xfaff)
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
 function isExcludedComponent(
  pos1: string | undefined,
  pos2: string | undefined,
@@ -283,34 +271,6 @@ function isFrequencyExcludedByPos(
  );
 }

-function shouldKeepFrequencyForNonIndependentKanjiNoun(
-  token: MergedToken,
-  pos1Exclusions: ReadonlySet<string>,
-): boolean {
-  if (pos1Exclusions.has('名詞')) {
-    return false;
-  }
-
-  const rank =
-    typeof token.frequencyRank === 'number' && Number.isFinite(token.frequencyRank)
-      ? Math.max(1, Math.floor(token.frequencyRank))
-      : null;
-  if (rank === null) {
-    return false;
-  }
-
-  const pos1Parts = splitNormalizedTagParts(normalizePos1Tag(token.pos1));
-  const pos2Parts = splitNormalizedTagParts(normalizePos2Tag(token.pos2));
-  if (pos1Parts.length !== 1 || pos2Parts.length !== 1) {
-    return false;
-  }
-  if (pos1Parts[0] !== '名詞' || pos2Parts[0] !== '非自立') {
-    return false;
-  }
-
-  return hasKanjiChar(token.surface) || hasKanjiChar(token.headword);
-}
-
 export function shouldExcludeTokenFromVocabularyPersistence(
  token: MergedToken,
  options: Pick<AnnotationStageOptions, 'pos1Exclusions' | 'pos2Exclusions'> = {},
@@ -320,7 +280,8 @@ export function shouldExcludeTokenFromVocabularyPersistence(

  return (
    sharedShouldExcludeTokenFromSubtitleAnnotations(token, { pos1Exclusions, pos2Exclusions }) ||
-    isFrequencyExcludedByPos(token, pos1Exclusions, pos2Exclusions)
+    (isFrequencyExcludedByPos(token, pos1Exclusions, pos2Exclusions) &&
+      !isKanjiNonIndependentNounToken(token, pos1Exclusions))
  );
 }

@@ -589,10 +550,20 @@ function isKanaOnlyMixedFunctionContentToken(
  }

  const pos1Parts = splitNormalizedTagParts(normalizePos1Tag(token.pos1));
-  return (
+  const hasMixedFunctionContentParts =
    pos1Parts.length >= 2 &&
    pos1Parts.some((part) => pos1Exclusions.has(part)) &&
-    pos1Parts.some((part) => !pos1Exclusions.has(part))
+    pos1Parts.some((part) => !pos1Exclusions.has(part));
+  if (!hasMixedFunctionContentParts) {
+    return false;
+  }
+
+  const normalizedReading = normalizeJlptTextForExclusion(token.reading);
+  const normalizedHeadwordReading = normalizeJlptTextForExclusion(token.headwordReading ?? '');
+  return (
+    !normalizedReading ||
+    !normalizedHeadwordReading ||
+    normalizedReading !== normalizedHeadwordReading
  );
 }

@@ -697,7 +668,7 @@ function resolveKnownWordReadingForMatch(

 function computeTokenKnownStatus(
  token: MergedToken,
-  isKnownWord: (text: string, reading?: string) => boolean,
+  isKnownWord: AnnotationStageDeps['isKnownWord'],
  knownWordMatchMode: NPlusOneMatchMode,
 ): boolean {
  const matchText = resolveKnownWordText(token.surface, token.headword, knownWordMatchMode);
@@ -711,7 +682,14 @@ function computeTokenKnownStatus(
    return false;
  }

-  return fallbackReading !== matchText.trim() && isKnownWord(fallbackReading);
+  // This fallback covers words mined in kana (token 大体, mined word だいたい),
+  // so the reading must only match mined word texts — the cache's reading-only
+  // index would let any kanji token match an unrelated note that shares its
+  // reading (渓谷/けいこく vs a mined 警告/けいこく).
+  return (
+    fallbackReading !== matchText.trim() &&
+    isKnownWord(fallbackReading, undefined, { allowReadingOnlyMatch: false })
+  );
 }

 function filterTokenFrequencyRank(
@@ -721,7 +699,7 @@ function filterTokenFrequencyRank(
 ): number | undefined {
  if (
    isFrequencyExcludedByPos(token, pos1Exclusions, pos2Exclusions) &&
-    !shouldKeepFrequencyForNonIndependentKanjiNoun(token, pos1Exclusions)
+    !isKanjiNonIndependentNounToken(token, pos1Exclusions)
  ) {
    return undefined;
  }
@@ -146,13 +146,17 @@ test('emits unparsed non-caption text as a token with surface headword', () => {

  const tokens = selectYomitanParseTokens(parseResults, () => false, 'headword');
  assert.deepEqual(
-    tokens?.map((token) => ({ surface: token.surface, headword: token.headword })),
+    tokens?.map((token) => ({
+      surface: token.surface,
+      headword: token.headword,
+      isUnparsedRun: token.isUnparsedRun ?? false,
+    })),
    [
-      { surface: 'みんな', headword: '皆' },
-      { surface: 'の', headword: 'の' },
-      { surface: 'とこ', headword: '所' },
-      { surface: '戻', headword: '戻' },
-      { surface: 'ろ', headword: '櫓' },
+      { surface: 'みんな', headword: '皆', isUnparsedRun: false },
+      { surface: 'の', headword: 'の', isUnparsedRun: false },
+      { surface: 'とこ', headword: '所', isUnparsedRun: false },
+      { surface: '戻', headword: '戻', isUnparsedRun: true },
+      { surface: 'ろ', headword: '櫓', isUnparsedRun: false },
    ],
  );
 });
@@ -239,6 +239,7 @@ export function mapYomitanParseResultItemToMergedTokens(
      headword: string,
      start: number,
      end: number,
+      isUnparsedRun = false,
    ): void => {
      tokens.push({
        surface,
@@ -254,6 +255,7 @@ export function mapYomitanParseResultItemToMergedTokens(
          const matchText = resolveKnownWordText(surface, headword, knownWordMatchMode);
          return matchText ? isKnownWord(matchText) : false;
        })(),
+        ...(isUnparsedRun ? { isUnparsedRun: true } : {}),
      });
    };

@@ -275,10 +277,11 @@ export function mapYomitanParseResultItemToMergedTokens(
          previousToken.reading += combinedReading;
          previousToken.endPos = end;
        } else if (shouldEmitUnparsedRunAsToken(combinedSurface)) {
-          // Yomitan couldn't parse this run (e.g. 戻ろ… truncated volitional). Keep it
-          // as a token with its surface as headword so it stays hoverable and counts in
-          // the n+1 math — matching what the embedded Yomitan actually returns.
-          pushToken(combinedSurface, combinedReading, combinedSurface, combinedStart, end);
+          // Yomitan couldn't parse this run (e.g. 戻ろ… truncated volitional, ぅ～
+          // elongations). Keep it as a token with its surface as headword so it stays
+          // hoverable, but flag it so annotation/N+1/vocab logic ignores it — there is
+          // no dictionary entry behind it.
+          pushToken(combinedSurface, combinedReading, combinedSurface, combinedStart, end, true);
        }
      } else {
        hasDictionaryMatch = true;
@@ -47,7 +47,6 @@ export const SUBTITLE_ANNOTATION_EXCLUDED_TERMS = new Set([
  'へえ',
  'ふう',
  'ほう',
-  'やはり',
  '何か',
  '何だ',
  '何も',
@@ -55,7 +54,6 @@ export const SUBTITLE_ANNOTATION_EXCLUDED_TERMS = new Set([
  '有る',
  '在る',
  '様',
-  '確かに',
  '誰も',
  '貴方',
  'もんか',
@@ -139,6 +137,46 @@ function resolvePos2Exclusions(options: SubtitleAnnotationFilterOptions = {}): R
  return resolveAnnotationPos2ExclusionSet(DEFAULT_ANNOTATION_POS2_EXCLUSION_CONFIG);
 }

+function hasKanjiChar(text: string): boolean {
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    if (code === undefined) {
+      continue;
+    }
+    if (
+      (code >= 0x3400 && code <= 0x4dbf) ||
+      (code >= 0x4e00 && code <= 0x9fff) ||
+      (code >= 0xf900 && code <= 0xfaff)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Kanji-bearing non-independent nouns (日, 方, 上, …) are real vocabulary that
+// Yomitan segments as standalone tokens; MeCab's 非自立 tag exists to suppress
+// kana grammar nouns (こと, もの, とき) and must not hide these.
+export function isKanjiNonIndependentNounToken(
+  token: MergedToken,
+  pos1Exclusions: ReadonlySet<string>,
+): boolean {
+  if (pos1Exclusions.has('名詞')) {
+    return false;
+  }
+
+  const pos1Parts = splitNormalizedTagParts(normalizePosTag(token.pos1));
+  const pos2Parts = splitNormalizedTagParts(normalizePosTag(token.pos2));
+  if (pos1Parts.length !== 1 || pos2Parts.length !== 1) {
+    return false;
+  }
+  if (pos1Parts[0] !== '名詞' || pos2Parts[0] !== '非自立') {
+    return false;
+  }
+
+  return hasKanjiChar(token.surface) || hasKanjiChar(token.headword);
+}
+
 function normalizeKana(text: string): string {
  const raw = text.trim();
  if (!raw) {
@@ -436,6 +474,13 @@ export function shouldExcludeTokenFromSubtitleAnnotations(
  token: MergedToken,
  options: SubtitleAnnotationFilterOptions = {},
 ): boolean {
+  // No Yomitan dictionary entry backs this token (ぅ～ elongations, truncated
+  // inflections) — it exists only to stay hoverable and must never receive
+  // annotations or count in the N+1 math.
+  if (token.isUnparsedRun === true) {
+    return true;
+  }
+
  const pos1Exclusions = resolvePos1Exclusions(options);
  const pos2Exclusions = resolvePos2Exclusions(options);
  const normalizedPos1 = normalizePosTag(token.pos1);
@@ -447,7 +492,10 @@ export function shouldExcludeTokenFromSubtitleAnnotations(
    return true;
  }

-  if (isExcludedByTagSet(normalizedPos2, pos2Exclusions)) {
+  if (
+    isExcludedByTagSet(normalizedPos2, pos2Exclusions) &&
+    !isKanjiNonIndependentNounToken(token, pos1Exclusions)
+  ) {
    return true;
  }

@@ -820,6 +820,135 @@ test('requestYomitanScanTokens keeps scanner metadata when parse spans agree', a
  ]);
 });

+test('requestYomitanScanTokens keeps scanner metadata for matching spans when parse segmentation has filler chunks', async () => {
+  const deps = createDeps(async (script) => {
+    if (script.includes('optionsGetFull')) {
+      return {
+        profileCurrent: 0,
+        profiles: [
+          {
+            options: {
+              scanning: { length: 40 },
+            },
+          },
+        ],
+      };
+    }
+    if (script.includes('parseText')) {
+      return [
+        {
+          source: 'scanning-parser',
+          index: 0,
+          content: [
+            [
+              {
+                text: 'や',
+                reading: '',
+                headwords: [[{ term: 'や' }]],
+              },
+            ],
+            [
+              {
+                text: 'ほ',
+                reading: '',
+                headwords: [[{ term: '帆' }]],
+              },
+            ],
+            [
+              {
+                text: 'っ ',
+                reading: '',
+              },
+            ],
+            [
+              {
+                text: 'ミナト',
+                reading: '',
+                headwords: [[{ term: 'ミナト' }]],
+              },
+            ],
+          ],
+        },
+      ];
+    }
+    // The termsFind scanner skips the unmatched っ+space chunk, so its spans
+    // do not line up 1:1 with the parseText segmentation above.
+    return [
+      {
+        surface: 'や',
+        reading: 'や',
+        headword: 'や',
+        headwordReading: 'や',
+        startPos: 0,
+        endPos: 1,
+        frequencyRank: 57,
+      },
+      {
+        surface: 'ほ',
+        reading: 'ほ',
+        headword: '帆',
+        headwordReading: 'ほ',
+        startPos: 1,
+        endPos: 2,
+        frequencyRank: 15414,
+      },
+      {
+        surface: 'ミナト',
+        reading: 'ミナト',
+        headword: 'ミナト',
+        headwordReading: 'みなと',
+        startPos: 4,
+        endPos: 7,
+        isNameMatch: true,
+        frequencyRank: 75133,
+      },
+    ];
+  });
+
+  const result = await requestYomitanScanTokens('やほっ ミナト', deps, {
+    error: () => undefined,
+  });
+
+  assert.deepEqual(result, [
+    {
+      surface: 'や',
+      reading: 'や',
+      headword: 'や',
+      headwordReading: 'や',
+      startPos: 0,
+      endPos: 1,
+      frequencyRank: 57,
+    },
+    {
+      surface: 'ほ',
+      reading: 'ほ',
+      headword: '帆',
+      headwordReading: 'ほ',
+      startPos: 1,
+      endPos: 2,
+      frequencyRank: 15414,
+    },
+    {
+      surface: 'っ ',
+      reading: '',
+      headword: 'っ ',
+      startPos: 2,
+      endPos: 4,
+      isUnparsedRun: true,
+    },
+    {
+      surface: 'ミナト',
+      reading: 'ミナト',
+      headword: 'ミナト',
+      headwordReading: 'みなと',
+      startPos: 4,
+      endPos: 7,
+      isNameMatch: true,
+      frequencyRank: 75133,
+    },
+  ]);
+});
+
 test('requestYomitanScanTokens falls back to left-to-right termsFind scanning', async () => {
  const scripts: string[] = [];
  const deps = createDeps(async (script) => {
@@ -1761,6 +1890,364 @@ test('requestYomitanScanTokens accepts SubMiner character entries with structure
  assert.equal((result as Array<{ isNameMatch?: boolean }>)[0]?.isNameMatch, true);
 });

+test('requestYomitanScanTokens greedily tokenizes character names before longer generic matches', async () => {
+  let scannerScript = '';
+  const deps = createDeps(async (script) => {
+    if (script.includes('termsFind')) {
+      scannerScript = script;
+      return [];
+    }
+    if (script.includes('optionsGetFull')) {
+      return {
+        profileCurrent: 0,
+        profiles: [
+          {
+            options: {
+              scanning: { length: 40 },
+              dictionaries: [
+                { name: 'JMdict', enabled: true },
+                { name: 'SubMiner Character Dictionary (AniList 130298)', enabled: true },
+              ],
+            },
+          },
+        ],
+      };
+    }
+    return null;
+  });
+
+  await requestYomitanScanTokens(
+    '美姫とヨータ',
+    deps,
+    { error: () => undefined },
+    { includeNameMatchMetadata: true },
+  );
+
+  assert.match(scannerScript, /const greedyNameScanEnabled = true;/);
+
+  const nameEntry = (term: string, reading: string) => ({
+    headwords: [
+      {
+        term,
+        reading,
+        sources: [{ originalText: term, isPrimary: true, matchType: 'exact' }],
+      },
+    ],
+    definitions: [
+      {
+        dictionary: 'SubMiner Character Dictionary (AniList 130298)',
+        dictionaryAlias: 'SubMiner Character Dictionary (AniList 130298)',
+      },
+    ],
+  });
+  const jmdictEntry = (term: string, reading: string, originalText: string) => ({
+    headwords: [
+      {
+        term,
+        reading,
+        sources: [{ originalText, isPrimary: true, matchType: 'exact' }],
+      },
+    ],
+    definitions: [{ dictionary: 'JMdict', dictionaryAlias: 'JMdict' }],
+  });
+
+  const result = await runInjectedYomitanScript(scannerScript, (action, params) => {
+    if (action !== 'termsFind') {
+      throw new Error(`unexpected action: ${action}`);
+    }
+    const text = (params as { text?: string } | undefined)?.text ?? '';
+    if (text.startsWith('美姫')) {
+      return { originalTextLength: 2, dictionaryEntries: [nameEntry('美姫', 'みき')] };
+    }
+    if (text.startsWith('とヨータ')) {
+      // Greedy generic match: とヨー normalizes to とよう (渡洋). Without the
+      // name pre-pass this consumes the ヨ of ヨータ.
+      return {
+        originalTextLength: 3,
+        dictionaryEntries: [jmdictEntry('渡洋', 'とよう', 'とヨー'), jmdictEntry('と', 'と', 'と')],
+      };
+    }
+    if (text.startsWith('ヨータ')) {
+      return { originalTextLength: 3, dictionaryEntries: [nameEntry('ヨータ', 'よーた')] };
+    }
+    if (text === 'と') {
+      return { originalTextLength: 1, dictionaryEntries: [jmdictEntry('と', 'と', 'と')] };
+    }
+    return { originalTextLength: 0, dictionaryEntries: [] };
+  });
+
+  assert.equal(Array.isArray(result), true);
+  assert.deepEqual(
+    (result as Array<Record<string, unknown>>).map(
+      ({ surface, headword, startPos, endPos, isNameMatch }) => ({
+        surface,
+        headword,
+        startPos,
+        endPos,
+        isNameMatch,
+      }),
+    ),
+    [
+      { surface: '美姫', headword: '美姫', startPos: 0, endPos: 2, isNameMatch: true },
+      { surface: 'と', headword: 'と', startPos: 2, endPos: 3, isNameMatch: false },
+      { surface: 'ヨータ', headword: 'ヨータ', startPos: 3, endPos: 6, isNameMatch: true },
+    ],
+  );
+});
+
+test('requestYomitanScanTokens lets a longer generic word beat a shorter name at the same position', async () => {
+  let scannerScript = '';
+  const deps = createDeps(async (script) => {
+    if (script.includes('termsFind')) {
+      scannerScript = script;
+      return [];
+    }
+    if (script.includes('optionsGetFull')) {
+      return {
+        profileCurrent: 0,
+        profiles: [
+          {
+            options: {
+              scanning: { length: 40 },
+              dictionaries: [
+                { name: 'JMdict', enabled: true },
+                { name: 'SubMiner Character Dictionary (AniList 130298)', enabled: true },
+              ],
+            },
+          },
+        ],
+      };
+    }
+    return null;
+  });
+
+  await requestYomitanScanTokens(
+    '空気変わって',
+    deps,
+    { error: () => undefined },
+    { includeNameMatchMetadata: true },
+  );
+
+  assert.match(scannerScript, /const greedyNameScanEnabled = true;/);
+
+  const nameEntry = (term: string, reading: string) => ({
+    headwords: [
+      {
+        term,
+        reading,
+        sources: [{ originalText: term, isPrimary: true, matchType: 'exact' }],
+      },
+    ],
+    definitions: [
+      {
+        dictionary: 'SubMiner Character Dictionary (AniList 130298)',
+        dictionaryAlias: 'SubMiner Character Dictionary (AniList 130298)',
+      },
+    ],
+  });
+  const jmdictEntry = (term: string, reading: string, originalText: string) => ({
+    headwords: [
+      {
+        term,
+        reading,
+        sources: [{ originalText, isPrimary: true, matchType: 'exact' }],
+      },
+    ],
+    definitions: [{ dictionary: 'JMdict', dictionaryAlias: 'JMdict' }],
+  });
+
+  const result = await runInjectedYomitanScript(scannerScript, (action, params) => {
+    if (action !== 'termsFind') {
+      throw new Error(`unexpected action: ${action}`);
+    }
+    const text = (params as { text?: string } | undefined)?.text ?? '';
+    if (text.startsWith('空気')) {
+      // A character named 空 matches here, but the generic 空気 is longer and
+      // must win the position.
+      return {
+        originalTextLength: 2,
+        dictionaryEntries: [nameEntry('空', 'くう'), jmdictEntry('空気', 'くうき', '空気')],
+      };
+    }
+    if (text.startsWith('変わって')) {
+      return {
+        originalTextLength: 4,
+        dictionaryEntries: [jmdictEntry('変わる', 'かわる', '変わって')],
+      };
+    }
+    return { originalTextLength: 0, dictionaryEntries: [] };
+  });
+
+  assert.equal(Array.isArray(result), true);
+  assert.deepEqual(
+    (result as Array<Record<string, unknown>>).map(
+      ({ surface, headword, startPos, endPos, isNameMatch }) => ({
+        surface,
+        headword,
+        startPos,
+        endPos,
+        isNameMatch,
+      }),
+    ),
+    [
+      { surface: '空気', headword: '空気', startPos: 0, endPos: 2, isNameMatch: false },
+      { surface: '変わって', headword: '変わる', startPos: 2, endPos: 6, isNameMatch: false },
+    ],
+  );
+});
+
+test('requestYomitanScanTokens skips greedy name scan without an enabled character dictionary', async () => {
+  let scannerScript = '';
+  const deps = createDeps(async (script) => {
+    if (script.includes('termsFind')) {
+      scannerScript = script;
+      return [];
+    }
+    if (script.includes('optionsGetFull')) {
+      return {
+        profileCurrent: 0,
+        profiles: [
+          {
+            options: {
+              scanning: { length: 40 },
+              dictionaries: [{ name: 'JMdict', enabled: true }],
+            },
+          },
+        ],
+      };
+    }
+    return null;
+  });
+
+  await requestYomitanScanTokens(
+    'アクア',
+    deps,
+    { error: () => undefined },
+    { includeNameMatchMetadata: true },
+  );
+
+  assert.match(scannerScript, /const greedyNameScanEnabled = false;/);
+});
+
+test('requestYomitanScanTokens replaces parseText segmentation where greedy name tokens re-segment', async () => {
+  const deps = createDeps(async (script) => {
+    if (script.includes('optionsGetFull')) {
+      return {
+        profileCurrent: 0,
+        profiles: [
+          {
+            options: {
+              scanning: { length: 40 },
+              dictionaries: [
+                { name: 'JMdict', enabled: true },
+                { name: 'SubMiner Character Dictionary (AniList 130298)', enabled: true },
+              ],
+            },
+          },
+        ],
+      };
+    }
+    if (script.includes('parseText')) {
+      // parseText walks greedily too, so it merges と with ヨー into 渡洋 and
+      // strands the タ.
+      return [
+        {
+          source: 'scanning-parser',
+          index: 0,
+          content: [
+            [
+              {
+                text: '美姫',
+                reading: 'みき',
+                headwords: [[{ term: '美姫' }]],
+              },
+            ],
+            [
+              {
+                text: 'とヨー',
+                reading: 'とよう',
+                headwords: [[{ term: '渡洋' }]],
+              },
+            ],
+            [
+              {
+                text: 'タ',
+                reading: '',
+              },
+            ],
+          ],
+        },
+      ];
+    }
+    return [
+      {
+        surface: '美姫',
+        reading: 'みき',
+        headword: '美姫',
+        headwordReading: 'みき',
+        startPos: 0,
+        endPos: 2,
+        isNameMatch: true,
+      },
+      {
+        surface: 'と',
+        reading: 'と',
+        headword: 'と',
+        headwordReading: 'と',
+        startPos: 2,
+        endPos: 3,
+        isNameMatch: false,
+      },
+      {
+        surface: 'ヨータ',
+        reading: 'ヨータ',
+        headword: 'ヨータ',
+        headwordReading: 'よーた',
+        startPos: 3,
+        endPos: 6,
+        isNameMatch: true,
+      },
+    ];
+  });
+
+  const result = await requestYomitanScanTokens(
+    '美姫とヨータ',
+    deps,
+    { error: () => undefined },
+    { includeNameMatchMetadata: true },
+  );
+
+  assert.deepEqual(result, [
+    {
+      surface: '美姫',
+      reading: 'みき',
+      headword: '美姫',
+      headwordReading: 'みき',
+      startPos: 0,
+      endPos: 2,
+      isNameMatch: true,
+    },
+    {
+      surface: 'と',
+      reading: 'と',
+      headword: 'と',
+      headwordReading: 'と',
+      startPos: 2,
+      endPos: 3,
+      isNameMatch: false,
+    },
+    {
+      surface: 'ヨータ',
+      reading: 'ヨータ',
+      headword: 'ヨータ',
+      headwordReading: 'よーた',
+      startPos: 3,
+      endPos: 6,
+      isNameMatch: true,
+    },
+  ]);
+});
+
 test('requestYomitanScanTokens preserves matched headword word classes', async () => {
  let scannerScript = '';
  const deps = createDeps(async (script) => {
@@ -57,6 +57,7 @@ export interface YomitanScanToken {
  isNameMatch?: boolean;
  frequencyRank?: number;
  wordClasses?: string[];
+  isUnparsedRun?: boolean;
 }

 interface YomitanProfileMetadata {
@@ -73,6 +74,7 @@ export interface YomitanAddNoteResult {
 }

 const DEFAULT_YOMITAN_SCAN_LENGTH = 40;
+const CHARACTER_DICTIONARY_TITLE_PREFIX = 'SubMiner Character Dictionary';
 const yomitanProfileMetadataByWindow = new WeakMap<BrowserWindow, YomitanProfileMetadata>();
 const yomitanProfileDiagnosticsLoggedByWindow = new WeakSet<BrowserWindow>();
 const yomitanFrequencyCacheByWindow = new WeakMap<
@@ -105,20 +107,89 @@ function isScanTokenArray(value: unknown): value is YomitanScanToken[] {
  );
 }

-function hasSameTokenSpans(left: YomitanScanToken[], right: YomitanScanToken[]): boolean {
-  if (left.length !== right.length) {
-    return false;
+function scanTokenSpanKey(token: YomitanScanToken): string {
+  return `${token.startPos}:${token.endPos}:${token.surface}`;
+}
+
+// Maps a parse-selected token to the scanner-token shape carried out of the
+// parser runtime. Shared by both selectYomitanParseTokens fallback paths so the
+// projected fields stay in sync as the shape changes.
+function toYomitanScanToken(token: {
+  surface: string;
+  reading: string;
+  headword: string;
+  startPos: number;
+  endPos: number;
+  isUnparsedRun?: boolean;
+}): YomitanScanToken {
+  return {
+    surface: token.surface,
+    reading: token.reading,
+    headword: token.headword,
+    startPos: token.startPos,
+    endPos: token.endPos,
+    ...(token.isUnparsedRun === true ? { isUnparsedRun: true } : {}),
+  };
+}
+
+// parseText segmentation is authoritative (it emits filler chunks for text the
+// termsFind scanner skips), but only the termsFind scanner carries annotation
+// metadata (isNameMatch, frequencyRank, headwordReading, wordClasses). Graft
+// scanner tokens onto the parseText segmentation per matching span so one
+// unmatched chunk degrades only itself instead of dropping the whole line's
+// metadata.
+//
+// Exception: character-name tokens. The greedy name scan can re-segment text
+// around a name (e.g. とヨータ → と + ヨータ instead of とヨー + タ), so
+// parseText segmentation cannot be authoritative there. Each name span is
+// expanded until it aligns with token boundaries in both segmentations, then
+// the parse tokens inside are replaced with the scanner tokens.
+function mergeScannerTokensIntoParseTokens(
+  parseScanTokens: YomitanScanToken[],
+  scannerTokens: YomitanScanToken[],
+): YomitanScanToken[] {
+  const scannerTokensBySpan = new Map<string, YomitanScanToken>();
+  for (const token of scannerTokens) {
+    scannerTokensBySpan.set(scanTokenSpanKey(token), token);
+  }
+  const graftedTokens = parseScanTokens.map(
+    (token) => scannerTokensBySpan.get(scanTokenSpanKey(token)) ?? token,
+  );
+
+  const nameTokens = scannerTokens.filter((token) => token.isNameMatch === true);
+  if (nameTokens.length === 0) {
+    return graftedTokens;
  }

-  return left.every((token, index) => {
-    const other = right[index];
-    return (
-      other !== undefined &&
-      token.surface === other.surface &&
-      token.startPos === other.startPos &&
-      token.endPos === other.endPos
-    );
-  });
+  const regions = nameTokens.map((token) => ({ start: token.startPos, end: token.endPos }));
+  const allTokens = [...parseScanTokens, ...scannerTokens];
+  let expanded = true;
+  while (expanded) {
+    expanded = false;
+    for (const region of regions) {
+      for (const token of allTokens) {
+        const overlaps = token.startPos < region.end && token.endPos > region.start;
+        const extendsBeyond = token.startPos < region.start || token.endPos > region.end;
+        if (overlaps && extendsBeyond) {
+          region.start = Math.min(region.start, token.startPos);
+          region.end = Math.max(region.end, token.endPos);
+          expanded = true;
+        }
+      }
+    }
+  }
+
+  const isInsideNameRegion = (token: YomitanScanToken): boolean =>
+    regions.some((region) => token.startPos >= region.start && token.endPos <= region.end);
+
+  const merged = graftedTokens.filter((token) => !isInsideNameRegion(token));
+  for (const token of scannerTokens) {
+    if (isInsideNameRegion(token)) {
+      merged.push(token);
+    }
+  }
+  merged.sort((a, b) => a.startPos - b.startPos || a.endPos - b.endPos);
+  return merged;
 }

 function makeTermReadingCacheKey(term: string, reading: string | null): string {
@@ -1104,8 +1175,7 @@ const YOMITAN_SCANNING_HELPERS = String.raw`
        }
        return best;
      }
-      function getPreferredHeadword(dictionaryEntries, token, dictionaryPriorityByName, dictionaryFrequencyModeByName) {
-        function normalizeWordClasses(headword) {
+      function normalizeWordClasses(headword) {
          if (!Array.isArray(headword?.wordClasses)) { return undefined; }
          const classes = headword.wordClasses.filter((wordClass) => typeof wordClass === "string" && wordClass.trim().length > 0);
          return classes.length > 0 ? classes : undefined;
@@ -1146,7 +1216,7 @@ const YOMITAN_SCANNING_HELPERS = String.raw`
          if (!includeNameMatchMetadata || !entry || typeof entry !== 'object') {
            return false;
          }
-          return getDictionaryEntryNames(entry).some((name) => name.startsWith("SubMiner Character Dictionary"));
+          return getDictionaryEntryNames(entry).some((name) => name.startsWith(${JSON.stringify(CHARACTER_DICTIONARY_TITLE_PREFIX)}));
        }
        function parseSubMinerMediaIdFromString(value) {
          const imageMatch = value.match(/\bimg\/m(\d+)-/i);
@@ -1154,7 +1224,7 @@ const YOMITAN_SCANNING_HELPERS = String.raw`
            const parsed = Number.parseInt(imageMatch[1], 10);
            if (Number.isSafeInteger(parsed) && parsed > 0) { return parsed; }
          }
-          const titleMatch = value.match(/SubMiner Character Dictionary[^\d]*(?:AniList\s*)?(\d+)/i);
+          const titleMatch = value.match(/${CHARACTER_DICTIONARY_TITLE_PREFIX}[^\d]*(?:AniList\s*)?(\d+)/i);
          if (titleMatch) {
            const parsed = Number.parseInt(titleMatch[1], 10);
            if (Number.isSafeInteger(parsed) && parsed > 0) { return parsed; }
@@ -1214,7 +1284,43 @@ const YOMITAN_SCANNING_HELPERS = String.raw`
          }
          const mediaIds = getSubMinerMediaIds(entry);
          return mediaIds.size === 0 || mediaIds.has(currentCharacterDictionaryMediaId);
+      }
+      function findLongestNameMatch(dictionaryEntries, textWindow) {
+        let best = null;
+        for (const dictionaryEntry of dictionaryEntries || []) {
+          if (!isCurrentMediaNameDictionaryEntry(dictionaryEntry)) { continue; }
+          const headwords = Array.isArray(dictionaryEntry?.headwords) ? dictionaryEntry.headwords : [];
+          for (let headwordIndex = 0; headwordIndex < headwords.length; headwordIndex += 1) {
+            const headword = headwords[headwordIndex];
+            for (const src of headword?.sources || []) {
+              if (src.matchType !== 'exact' || src.isPrimary !== true) { continue; }
+              const originalText = typeof src.originalText === 'string' ? src.originalText : '';
+              if (!originalText || !textWindow.startsWith(originalText)) { continue; }
+              if (best === null || originalText.length > best.sourceLength) {
+                best = { dictionaryEntry, headword, headwordIndex, sourceLength: originalText.length };
+              }
+            }
+          }
        }
+        return best;
+      }
+      function findLongestGenericMatchLength(dictionaryEntries, textWindow) {
+        let best = 0;
+        for (const dictionaryEntry of dictionaryEntries || []) {
+          if (isNameDictionaryEntry(dictionaryEntry)) { continue; }
+          const headwords = Array.isArray(dictionaryEntry?.headwords) ? dictionaryEntry.headwords : [];
+          for (const headword of headwords) {
+            for (const src of headword?.sources || []) {
+              if (src.matchType !== 'exact' || src.isPrimary !== true) { continue; }
+              const originalText = typeof src.originalText === 'string' ? src.originalText : '';
+              if (!originalText || !textWindow.startsWith(originalText)) { continue; }
+              if (originalText.length > best) { best = originalText.length; }
+            }
+          }
+        }
+        return best;
+      }
+      function getPreferredHeadword(dictionaryEntries, token, dictionaryPriorityByName, dictionaryFrequencyModeByName) {
        const currentMediaDictionaryEntries =
          currentCharacterDictionaryMediaId === null
            ? (dictionaryEntries || [])
@@ -1261,6 +1367,7 @@ function buildYomitanScanningScript(
  profileIndex: number,
  scanLength: number,
  includeNameMatchMetadata: boolean,
+  greedyNameScanEnabled: boolean,
  currentCharacterDictionaryMediaId: number | null,
  dictionaryPriorityByName: Record<string, number>,
  dictionaryFrequencyModeByName: Partial<Record<string, YomitanFrequencyMode>>,
@@ -1287,6 +1394,7 @@ function buildYomitanScanningScript(
        });
 ${YOMITAN_SCANNING_HELPERS}
      const includeNameMatchMetadata = ${includeNameMatchMetadata ? 'true' : 'false'};
+      const greedyNameScanEnabled = ${greedyNameScanEnabled ? 'true' : 'false'};
      const currentCharacterDictionaryMediaId = ${
        currentCharacterDictionaryMediaId !== null
          ? String(currentCharacterDictionaryMediaId)
@@ -1297,26 +1405,17 @@ ${YOMITAN_SCANNING_HELPERS}
      const text = ${JSON.stringify(text)};
      const details = {matchType: "exact", deinflect: true};
      const tokens = [];
-      async function findTokenAt(position, windowLength) {
-        const codePoint = text.codePointAt(position);
-        const character = String.fromCodePoint(codePoint);
+      const termsFindCache = new Map();
+      async function termsFindAt(position, windowLength) {
+        const cacheKey = position + ":" + windowLength;
+        const cached = termsFindCache.get(cacheKey);
+        if (cached) { return cached; }
        const substring = text.substring(position, position + windowLength);
        const result = await invoke("termsFind", { text: substring, details, optionsContext: { index: ${profileIndex} } });
-        const dictionaryEntries = Array.isArray(result?.dictionaryEntries) ? result.dictionaryEntries : [];
-        const originalTextLength = typeof result?.originalTextLength === "number" ? result.originalTextLength : 0;
-        if (dictionaryEntries.length === 0 || originalTextLength <= 0 || (originalTextLength === character.length && !isCodePointJapanese(codePoint))) {
-          return { token: null, matchedLength: 0 };
-        }
-        const source = substring.substring(0, originalTextLength);
-        const preferredHeadword = getPreferredHeadword(
-          dictionaryEntries,
-          source,
-          dictionaryPriorityByName,
-          dictionaryFrequencyModeByName
-        );
-        if (!preferredHeadword || typeof preferredHeadword.term !== "string") {
-          return { token: null, matchedLength: originalTextLength };
-        }
+        termsFindCache.set(cacheKey, result);
+        return result;
+      }
+      function buildScanToken(position, source, preferredHeadword) {
        const reading = typeof preferredHeadword.reading === "string" ? preferredHeadword.reading : "";
        const segments = distributeFuriganaInflected(preferredHeadword.term, reading, source);
        const tokenPayload = {
@@ -1325,7 +1424,7 @@ ${YOMITAN_SCANNING_HELPERS}
          headword: preferredHeadword.term,
          headwordReading: reading || undefined,
          startPos: position,
-          endPos: position + originalTextLength,
+          endPos: position + source.length,
          isNameMatch: includeNameMatchMetadata && preferredHeadword.isNameMatch === true,
          frequencyRank:
            typeof preferredHeadword.frequencyRank === "number" && Number.isFinite(preferredHeadword.frequencyRank)
@@ -1335,17 +1434,93 @@ ${YOMITAN_SCANNING_HELPERS}
        if (Array.isArray(preferredHeadword.wordClasses) && preferredHeadword.wordClasses.length > 0) {
          tokenPayload.wordClasses = preferredHeadword.wordClasses;
        }
-        return { token: tokenPayload, matchedLength: originalTextLength };
+        return tokenPayload;
+      }
+      async function findTokenAt(position, windowLength) {
+        const codePoint = text.codePointAt(position);
+        const character = String.fromCodePoint(codePoint);
+        const result = await termsFindAt(position, windowLength);
+        const dictionaryEntries = Array.isArray(result?.dictionaryEntries) ? result.dictionaryEntries : [];
+        const originalTextLength = typeof result?.originalTextLength === "number" ? result.originalTextLength : 0;
+        if (dictionaryEntries.length === 0 || originalTextLength <= 0 || (originalTextLength === character.length && !isCodePointJapanese(codePoint))) {
+          return { token: null, matchedLength: 0 };
+        }
+        const source = text.substring(position, position + originalTextLength);
+        const preferredHeadword = getPreferredHeadword(
+          dictionaryEntries,
+          source,
+          dictionaryPriorityByName,
+          dictionaryFrequencyModeByName
+        );
+        if (!preferredHeadword || typeof preferredHeadword.term !== "string") {
+          return { token: null, matchedLength: originalTextLength };
+        }
+        return { token: buildScanToken(position, source, preferredHeadword), matchedLength: originalTextLength };
+      }
+      // Greedy name pre-pass: character-name matches claim their spans before
+      // the left-to-right walk, so a longer generic match starting earlier
+      // (e.g. とヨー → 渡洋) cannot swallow the start of a name (ヨータ).
+      const nameTokens = [];
+      if (greedyNameScanEnabled) {
+        let namePos = 0;
+        while (namePos < text.length) {
+          const codePoint = text.codePointAt(namePos);
+          if (!isCodePointJapanese(codePoint)) {
+            namePos += String.fromCodePoint(codePoint).length;
+            continue;
+          }
+          const result = await termsFindAt(namePos, ${scanLength});
+          const dictionaryEntries = Array.isArray(result?.dictionaryEntries) ? result.dictionaryEntries : [];
+          const textWindow = text.substring(namePos, namePos + ${scanLength});
+          const nameMatch = findLongestNameMatch(dictionaryEntries, textWindow);
+          // A name only claims its span when no strictly longer generic word
+          // starts at the same position (a character named 空 must not split
+          // 空気). Ties go to the name. Generic matches that start earlier and
+          // overlap the name are still blocked by the reservation.
+          if (
+            !nameMatch ||
+            findLongestGenericMatchLength(dictionaryEntries, textWindow) > nameMatch.sourceLength
+          ) {
+            namePos += String.fromCodePoint(codePoint).length;
+            continue;
+          }
+          const source = text.substring(namePos, namePos + nameMatch.sourceLength);
+          nameTokens.push(buildScanToken(namePos, source, {
+            term: nameMatch.headword.term,
+            reading: nameMatch.headword.reading,
+            wordClasses: normalizeWordClasses(nameMatch.headword),
+            isNameMatch: true,
+            frequencyRank: getBestFrequencyRank(
+              nameMatch.dictionaryEntry,
+              nameMatch.headwordIndex,
+              dictionaryPriorityByName,
+              dictionaryFrequencyModeByName
+            )
+          }));
+          namePos += nameMatch.sourceLength;
+        }
      }
      let i = 0;
+      let nameIndex = 0;
      while (i < text.length) {
-        let attempt = await findTokenAt(i, ${scanLength});
+        while (nameIndex < nameTokens.length && nameTokens[nameIndex].startPos < i) { nameIndex += 1; }
+        const nextNameToken = nameIndex < nameTokens.length ? nameTokens[nameIndex] : null;
+        if (nextNameToken && nextNameToken.startPos === i) {
+          tokens.push(nextNameToken);
+          i = nextNameToken.endPos;
+          nameIndex += 1;
+          continue;
+        }
+        // Cap the window at the next reserved name span so a generic match
+        // cannot consume into it.
+        const windowLength = nextNameToken ? Math.min(${scanLength}, nextNameToken.startPos - i) : ${scanLength};
+        let attempt = await findTokenAt(i, windowLength);
        // Yomitan text normalization can consume characters (whitespace,
        // punctuation) beyond the matched term, leaving no headword whose
        // source equals the consumed text. Retry with shorter windows so a
        // valid prefix term (e.g. a character name before a paren) still
        // tokenizes instead of the position being skipped.
-        let retryLength = Math.min(attempt.matchedLength, ${scanLength}) - 1;
+        let retryLength = Math.min(attempt.matchedLength, windowLength) - 1;
        while (!attempt.token && retryLength >= 1) {
          const retry = await findTokenAt(i, retryLength);
          if (retry.token) {
@@ -1482,18 +1657,17 @@ export async function requestYomitanScanTokens(

  const parseResults = await requestYomitanParseResults(text, deps, logger);
  const selectedParseTokens = selectYomitanParseTokens(parseResults, () => false, 'headword');
-  const parseScanTokens =
-    selectedParseTokens?.map((token) => ({
-      surface: token.surface,
-      reading: token.reading,
-      headword: token.headword,
-      startPos: token.startPos,
-      endPos: token.endPos,
-    })) ?? null;
+  const parseScanTokens = selectedParseTokens?.map(toYomitanScanToken) ?? null;

  const metadata = await requestYomitanProfileMetadata(parserWindow, logger);
  const profileIndex = metadata?.profileIndex ?? 0;
  const scanLength = metadata?.scanLength ?? DEFAULT_YOMITAN_SCAN_LENGTH;
+  const includeNameMatchMetadata = options?.includeNameMatchMetadata === true;
+  const greedyNameScanEnabled =
+    includeNameMatchMetadata &&
+    (metadata?.dictionaries ?? []).some((name) =>
+      name.startsWith(CHARACTER_DICTIONARY_TITLE_PREFIX),
+    );

  try {
    const rawResult = await parserWindow.webContents.executeJavaScript(
@@ -1501,7 +1675,8 @@ export async function requestYomitanScanTokens(
        text,
        profileIndex,
        scanLength,
-        options?.includeNameMatchMetadata === true,
+        includeNameMatchMetadata,
+        greedyNameScanEnabled,
        typeof options?.currentCharacterDictionaryMediaId === 'number' &&
          Number.isFinite(options.currentCharacterDictionaryMediaId) &&
          options.currentCharacterDictionaryMediaId > 0
@@ -1514,21 +1689,13 @@ export async function requestYomitanScanTokens(
    );
    if (isScanTokenArray(rawResult)) {
      if (parseScanTokens && parseScanTokens.length > 0) {
-        return hasSameTokenSpans(parseScanTokens, rawResult) ? rawResult : parseScanTokens;
+        return mergeScannerTokensIntoParseTokens(parseScanTokens, rawResult);
      }
      return rawResult;
    }
    if (Array.isArray(rawResult)) {
      const selectedTokens = selectYomitanParseTokens(rawResult, () => false, 'headword');
-      return (
-        selectedTokens?.map((token) => ({
-          surface: token.surface,
-          reading: token.reading,
-          headword: token.headword,
-          startPos: token.startPos,
-          endPos: token.endPos,
-        })) ?? null
-      );
+      return selectedTokens?.map(toYomitanScanToken) ?? null;
    }
    if (parseScanTokens && parseScanTokens.length > 0) {
      return parseScanTokens;
@@ -4652,7 +4652,8 @@ const {
      setYomitanParserInitPromise: (promise) => {
        appState.yomitanParserInitPromise = promise;
      },
-      isKnownWord: (text, reading) => Boolean(appState.ankiIntegration?.isKnownWord(text, reading)),
+      isKnownWord: (text, reading, options) =>
+        Boolean(appState.ankiIntegration?.isKnownWord(text, reading, options)),
      recordLookup: (hit) => {
        ensureImmersionTrackerStarted();
        appState.immersionTracker?.recordLookup(hit);
@@ -149,6 +149,42 @@ test('createConfigHotReloadAppliedHandler applies safe Anki, annotation, and log
  assert.ok(calls.includes('broadcast:config:hot-reload'));
 });

+test('createConfigHotReloadAppliedHandler applies only changed Anki media options', () => {
+  const config = deepCloneConfig(DEFAULT_CONFIG);
+  config.ankiConnect.media.normalizeAudio = false;
+  config.ankiConnect.media.mirrorMpvVolume = false;
+  const ankiPatches: unknown[] = [];
+
+  const applyHotReload = createConfigHotReloadAppliedHandler({
+    setKeybindings: () => undefined,
+    setSessionBindings: () => undefined,
+    refreshGlobalAndOverlayShortcuts: () => undefined,
+    setSecondarySubMode: () => undefined,
+    broadcastToOverlayWindows: () => undefined,
+    applyAnkiRuntimeConfigPatch: (patch) => ankiPatches.push(patch),
+  });
+
+  applyHotReload(
+    {
+      hotReloadFields: ['ankiConnect.media.normalizeAudio'],
+      restartRequiredFields: [],
+    },
+    config,
+  );
+  applyHotReload(
+    {
+      hotReloadFields: ['ankiConnect.media.mirrorMpvVolume'],
+      restartRequiredFields: [],
+    },
+    config,
+  );
+
+  assert.deepEqual(ankiPatches, [
+    { media: { normalizeAudio: false } },
+    { media: { mirrorMpvVolume: false } },
+  ]);
+});
+
 test('buildConfigHotReloadPayload includes independent primary subtitle mode', () => {
  const config = deepCloneConfig(DEFAULT_CONFIG);
  config.subtitleStyle.primaryDefaultMode = 'hover';
@@ -93,6 +93,16 @@ function buildAnkiRuntimeConfigPatch(
  if (diff.hotReloadFields.includes('ankiConnect.deck')) {
    patch.deck = config.ankiConnect.deck;
  }
+  const mediaPatch: NonNullable<AnkiConnectConfig['media']> = {};
+  if (diff.hotReloadFields.includes('ankiConnect.media.normalizeAudio')) {
+    mediaPatch.normalizeAudio = config.ankiConnect.media.normalizeAudio;
+  }
+  if (diff.hotReloadFields.includes('ankiConnect.media.mirrorMpvVolume')) {
+    mediaPatch.mirrorMpvVolume = config.ankiConnect.media.mirrorMpvVolume;
+  }
+  if (Object.keys(mediaPatch).length > 0) {
+    patch.media = mediaPatch;
+  }
  if (hasAnyHotReloadField(diff, ['ankiConnect.knownWords'])) {
    patch.knownWords = config.ankiConnect.knownWords;
  }
@@ -37,8 +37,8 @@ export function createBuildTokenizerDepsMainHandler(deps: TokenizerMainDeps) {
    getYomitanParserInitPromise: () => deps.getYomitanParserInitPromise(),
    setYomitanParserInitPromise: (promise: Promise<boolean> | null) =>
      deps.setYomitanParserInitPromise(promise),
-    isKnownWord: (text: string, reading?: string) => {
-      const hit = deps.isKnownWord(text, reading);
+    isKnownWord: (text, reading, options) => {
+      const hit = deps.isKnownWord(text, reading, options);
      deps.recordLookup(hit);
      return hit;
    },
@@ -181,6 +181,54 @@ test('generateAudio can preserve raw sentence audio loudness', async () => {
  });
 });

+test('generateAudio applies mpv volume after loudness normalization', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio('/video.mp4', 10, 12, 0, null, true, 0.42);
+
+    const args = readFfmpegArgs(argsPath);
+    assert.equal(args[args.indexOf('-af') + 1], 'loudnorm=I=-23:TP=-2:LRA=11,volume=0.42');
+  });
+});
+
+test('generateAudio limits amplified mpv volume after applying gain', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio('/video.mp4', 10, 12, 0, null, true, 2);
+
+    const args = readFfmpegArgs(argsPath);
+    assert.equal(
+      args[args.indexOf('-af') + 1],
+      'loudnorm=I=-23:TP=-2:LRA=11,volume=2,alimiter=limit=0.891251:level=false',
+    );
+  });
+});
+
+test('generateAudio applies mpv volume without loudness normalization', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio('/video.mp4', 10, 12, 0, null, false, 0.75);
+
+    const args = readFfmpegArgs(argsPath);
+    assert.equal(args[args.indexOf('-af') + 1], 'volume=0.75');
+  });
+});
+
+test('generateAudio omits no-op mpv volume filters', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio('/video.mp4', 10, 12, 0, null, false, 1);
+
+    const args = readFfmpegArgs(argsPath);
+    assert.equal(args.includes('-af'), false);
+  });
+});
+
+test('generateAudio preserves a zero numeric mpv volume', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio('/video.mp4', 10, 12, 0, null, false, 0);
+
+    const args = readFfmpegArgs(argsPath);
+    assert.equal(args[args.indexOf('-af') + 1], 'volume=0');
+  });
+});
+
 test('generateAudio clips leading padding without adding it to trailing duration', async () => {
  await withStubbedFfmpeg(async (generator, argsPath) => {
    await generator.generateAudio('/video.mp4', 0.2, 1.2, 0.5);
@@ -25,6 +25,7 @@ import { normalizeMediaInput, type MediaInput } from './media-input';

 const log = createLogger('media');
 const AUDIO_NORMALIZATION_FILTER = 'loudnorm=I=-23:TP=-2:LRA=11';
+const AUDIO_AMPLIFICATION_LIMITER_FILTER = 'alimiter=limit=0.891251:level=false';

 export type { MediaInput, MediaInputOptions } from './media-input';

@@ -266,6 +267,7 @@ export class MediaGenerator {
    padding: number = 0,
    audioStreamIndex: number | null = null,
    normalizeAudio = true,
+    volumeScale?: number,
  ): Promise<Buffer> {
    const safePadding = Number.isFinite(padding) ? Math.max(0, padding) : 0;
    const start = Math.max(0, startTime - safePadding);
@@ -296,8 +298,23 @@ export class MediaGenerator {
      }

      args.push('-vn');
+      const audioFilters: string[] = [];
      if (normalizeAudio) {
-        args.push('-af', AUDIO_NORMALIZATION_FILTER);
+        audioFilters.push(AUDIO_NORMALIZATION_FILTER);
+      }
+      if (
+        typeof volumeScale === 'number' &&
+        Number.isFinite(volumeScale) &&
+        volumeScale >= 0 &&
+        volumeScale !== 1
+      ) {
+        audioFilters.push(`volume=${volumeScale}`);
+        if (volumeScale > 1) {
+          audioFilters.push(AUDIO_AMPLIFICATION_LIMITER_FILTER);
+        }
+      }
+      if (audioFilters.length > 0) {
+        args.push('-af', audioFilters.join(','));
      }
      args.push('-acodec', 'libmp3lame', '-q:a', '2', '-ar', '44100', '-y', outputPath);

@@ -75,6 +75,7 @@ export interface AnkiConnectConfig {
    animatedCrf?: number;
    syncAnimatedImageToWordAudio?: boolean;
    normalizeAudio?: boolean;
+    mirrorMpvVolume?: boolean;
    audioPadding?: number;
    fallbackDuration?: number;
    maxMediaDuration?: number;
@@ -236,6 +236,7 @@ export interface ResolvedConfig {
      animatedCrf: number;
      syncAnimatedImageToWordAudio: boolean;
      normalizeAudio: boolean;
+      mirrorMpvVolume: boolean;
      audioPadding: number;
      fallbackDuration: number;
      maxMediaDuration: number;
@@ -40,6 +40,12 @@ export interface MergedToken {
  isMerged: boolean;
  isKnown: boolean;
  isNPlusOneTarget: boolean;
+  /**
+   * Text Yomitan had no dictionary entry for (e.g. ぅ～ elongation runs,
+   * truncated inflections). Kept as a token so it stays hoverable, but
+   * ignored by annotation, N+1, and vocabulary-stats logic.
+   */
+  isUnparsedRun?: boolean;
  isNameMatch?: boolean;
  characterImage?: CharacterNameImage;
  jlptLevel?: JlptLevel;
Author	SHA1	Message	Date
sudacode	beeab564b4	chore(release): prepare v0.18.0	2026-07-10 02:03:10 -07:00
sudacode	cab7975a2b	chore(docs): remove implemented plan docs - Drop early-managed-overlay-startup and macos-notification-hover design docs (both implemented, no longer needed)	2026-07-10 01:09:52 -07:00
sudacode	846292809c	docs(changes): consolidate and tighten changelog entries - Merge related fix entries into single files (name-match-span-merge into character-name-split-and-scan-recovery, kanji-non-independent-noun-annotations + lexicalized-expression-frequency into content-adverb-annotation-stop-list, greedy-name-parsing-priority into character-name-split-and-scan-recovery, kiku-field-grouping-cancel-double-toast into kiku-field-grouping-modal-recovery, history-rofi-cover-art into launcher-history-command) - Rewrite remaining entries for brevity and reclassify stats-trend-title-limits as "changed"	2026-07-10 01:04:01 -07:00
sudacode	8712780d08	fix(tokenizer): keep frequency rank for lexicalized kana expressions (#156 )	2026-07-10 00:54:17 -07:00
sudacode	7b1a005a65	feat(anki): mirror mpv software volume into generated sentence audio (#155 )	2026-07-10 00:44:23 -07:00
sudacode	84c75f50aa	fix(release): skip gh attribution without CI token	2026-07-09 02:26:00 -07:00
sudacode	8b838f2c7d	chore(release): prepare 0.18.0-beta.3	2026-07-09 01:20:02 -07:00
sudacode	db4139ba0b	fix(tokenizer): block kanji reading collisions and name/generic length t - Add allowReadingOnlyMatch:false to kanji token known-word lookups so 渓谷/けいこく no longer matches a mined 警告/けいこく card via reading-only index - Greedy name pre-pass yields when a strictly longer generic word starts at the same position (空 no longer splits 空気; ties still go to the name)	2026-07-09 01:03:58 -07:00
sudacode	6c251502b3	fix(tokenizer): exclude unparsed-run tokens from annotations and N+1 (#153 )	2026-07-09 00:28:38 -07:00
sudacode	ae40934d3a	fix(tokenizer): greedy name pre-pass to prevent generic matches swallowing character names (#151 )	2026-07-08 23:53:45 -07:00
sudacode	cdb1475a54	chore(assets): update icons and favicons	2026-07-08 22:35:47 -07:00
sudacode	a2e49b369b	fix(tokenizer): merge scanner metadata per token instead of all-or-nothi - Replace hasSameTokenSpans + full-discard with mergeScannerTokensIntoParseTokens - Grafts isNameMatch/frequencyRank/etc onto matching parse spans; filler chunks degrade only themselves - Fixes name annotations dropping for entire subtitle lines containing unmatched interjections	2026-07-08 22:26:34 -07:00
sudacode	7f13aed50a	fix(overlay): keep frequency/JLPT highlight for kanji non-independent nouns (#150 )	2026-07-08 22:25:32 -07:00
sudacode	8b21a2bca8	fix(overlay): remove content adverbs from annotation stop-word list - 確かに and やはり no longer excluded from frequency/JLPT highlighting and vocab stats - Stop-word list now covers only interjections, pronouns, and grammar fragments	2026-07-08 20:15:45 -07:00