chore: prepare 0.15.0-beta.6 prerelease

- Add `launchAppBackgroundDetached` that spawns with `--start --background` and `SUBMINER_BACKGROUND_CHILD=1`
- On darwin with empty appArgs, use detached background launch instead of inherited process
- Add `extraEnv` param to `launchAppCommandDetached` for env injection
- Inject deps into `runAppPassthroughCommand` for testability
- Bump vendor/subminer-yomitan submodule

changes/README.md

@@ -34,11 +34,13 @@ Rules:
 How fragments turn into a release:
 
 - At release time, `bun run changelog:build` (and `bun run changelog:prerelease-notes`) pipes every pending fragment through `claude -p` to merge related items, drop noise, and rewrite into a clean user-facing release body. Write fragments as raw, informative notes — don't worry about polished prose, deduping across PRs, or line-by-line phrasing. The polish step handles all of that.
+- The polish step treats pending fragments as the final release outcome, not prerelease history. If a feature is added and then renamed or fixed before the stable cut, ship the final feature bullet instead of separate prerelease-only breaking/fix entries.
 - `internal` fragments stay in `CHANGELOG.md` (inside a collapsed `<details>` block) but are dropped from the GitHub release notes entirely.
 - The polished `CHANGELOG.md` and `release/release-notes.md` are committed and reviewed before tagging — edit the Markdown by hand if Claude misses something.
 
 Prerelease notes:
 
 - prerelease tags like `v0.11.3-beta.1` and `v0.11.3-rc.1` reuse the current pending fragments to generate `release/prerelease-notes.md`
+- existing prerelease notes are a reviewed baseline; later prerelease runs should replace stale beta/RC wording with the current outcome instead of appending fix churn
 - prerelease note generation does not consume fragments and does not update `CHANGELOG.md` or `docs-site/changelog.md`
 - the final stable release is the point where `bun run changelog:build` consumes fragments into the stable changelog and release notes

changes/changelog-net-release-outcome.md

@@ -0,0 +1,4 @@
+type: changed
+area: release
+
+- Release-note polishing now treats pending fragments and reviewed prerelease notes as a cumulative final outcome, so prerelease-only fixes or breakages collapse into the final user-facing change.

changes/character-dictionary-known-names.md

@@ -0,0 +1,4 @@
+type: changed
+area: dictionary
+
+- Keep character dictionary lookup entries scoped to generated Japanese name aliases instead of surfacing raw romanized/English aliases as separate results, and refresh cached v15 snapshots so old English-name entries are regenerated.

changes/character-dictionary-manual-search.md

@@ -0,0 +1,4 @@
+type: changed
+area: character-dictionary
+
+- **Character Dictionary:** Changed the in-app AniList selector to wait for an explicit title search. The search box is prefilled from the current filename guess, so you can edit it before choosing an override.

changes/character-name-inline-images.md

@@ -0,0 +1,7 @@
+type: added
+area: subtitles
+
+- Added optional inline AniList portraits for character-name subtitle matches, including automatic refresh of cached character dictionary snapshots that do not contain portrait data.
+- Scoped manual AniList overrides by parent media directory, so separate season folders can keep separate character dictionary selections.
+- Fixed large character dictionary imports by serving the merged ZIP through a local URL when supported, with a base64 fallback for older bundled Yomitan builds.
+- Allowed subtitle overlay data image sources so inline character portraits render instead of showing a broken image icon.

changes/config-settings-option-labels.md

@@ -1,4 +0,0 @@
-type: changed
-area: settings
-
-- Simplified configuration option rows by hiding raw config paths and placing the live/restart status beside each option title.

changes/fix-character-dictionary-modal-hyprland.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Hid the visible subtitle overlay as soon as the character dictionary modal opens, including while AniList lookup is still loading or returns no results.

changes/fix-discord-presence-jellyfin-title.md

@@ -0,0 +1,4 @@
+type: fixed
+area: integrations
+
+- Prevented Discord Rich Presence from falling back to Jellyfin stream URLs, and primed Jellyfin playback titles before loading tokenized streams so presence shows the show/episode title

changes/fix-jellyfin-discovery-playback-loop.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Prevented Jellyfin discovery playback from reloading the active item, misreporting paused mpv playback as still playing, retrying startup unpause after playback is paused again, unpausing after a manual `y-t` overlay toggle during startup, repeatedly restoring the overlay from duplicate ready signals, missing delayed Japanese subtitle selection on startup, letting later German/Russian subtitle loads steal the selected Japanese track, and spawning long-lived sidebar ffmpeg extractors against Jellyfin stream URLs.

changes/fix-jellyfin-discovery-resume.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Fixed Jellyfin discovery resume playback when a remote play command sends `StartPositionTicks: 0` despite saved progress on the item.

changes/fix-jellyfin-host-device-identity.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Derived Jellyfin cast device identity from the OS hostname, always reports the client as SubMiner, and ignores legacy configurable Jellyfin client/device identity fields so multiple SubMiner installs no longer share the same remote-session identity.

changes/fix-jellyfin-overlay-toggle.md

@@ -0,0 +1,11 @@
+type: fixed
+area: jellyfin
+
+- Fixed Jellyfin `y-t` overlay hide so the plugin sends an explicit hide command when it knows the overlay is visible, avoiding overlay reloads and paused playback resumes.
+- Kept that manual hide sticky across Jellyfin stream redirects that change mpv's path, even when the redirected URL drops mpv's media title.
+- Re-armed managed subtitle defaults during those path-changing redirects so Japanese primary subtitles can load on the redirected stream.
+- Routed visible-overlay shortcuts and app-side visibility changes back through the mpv plugin so SubMiner overlay toggling stays independent of Jellyfin playback controls.
+- Collapsed duplicate visible-overlay toggle events so Hyprland does not process one physical shortcut as hide-then-show.
+- Kept passive Linux/Hyprland visible-overlay shows from taking keyboard focus away from mpv/Jellyfin.
+- Made Jellyfin external subtitle selection tolerate transient mpv `track-list` read failures and numeric string track IDs so Japanese subtitles are selected after preload on Linux.
+- Fixed AppImage-launched Jellyfin playback controls so mpv sends overlay commands to the running SubMiner app-control socket instead of the mounted Electron binary.

changes/fix-jellyfin-remote-progress-sync.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Fixed Jellyfin remote controller visibility and progress syncing for mpv/SubMiner seek jumps, stopped sessions, startup path changes, and Linux websocket reconnect windows.

changes/fix-jellyfin-stats-title.md

@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Grouped Jellyfin playback stats under Jellyfin item metadata instead of stream URLs, so watched episodes merge with matching local library titles and keep clean display names.

changes/fix-jellyfin-subtitle-timing.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Improved Jellyfin subtitle timing behavior by preferring default embedded subtitle streams over external sidecars, stripping Jellyfin's server-selected subtitle stream from mpv playback URLs, suppressing mpv's subtitle auto-selection and plugin overlay auto-start while SubMiner stages managed tracks, automatically correcting clear Japanese-vs-English cue timeline offsets, and restoring saved per-stream subtitle delay shifts.

changes/fix-jellyfin-tray-discovery-active-state.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Keep the Jellyfin discovery tray checkbox in sync on Linux after tray, CLI, or startup remote-session changes, with a visible check mark when Linux tray hosts ignore native checkbox rendering.

changes/fix-jellyfin-tray-discovery-stale-session.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Restarted stale Jellyfin tray discovery sessions when the server no longer lists the SubMiner cast target, avoiding a needless Jellyfin re-login.

changes/fix-jellyfin-visible-progress.md

@@ -0,0 +1,5 @@
+type: fixed
+area: jellyfin
+
+- Preserved Jellyfin-visible resume progress when mpv resets its position during playback stop by reusing SubMiner's last known playback position for final progress and stopped reports.
+- Kept Jellyfin remote Play and Resume distinct so normal Play starts from the beginning, while Resume starts at Jellyfin's requested position without an early mpv seek race.

changes/fix-known-words-decks-row-overflow.md

@@ -1,4 +0,0 @@
-type: changed
-area: config
-
-- Reorganized each known-words deck row in the Settings window into a card with the deck name on its own header line so longer deck names stay readable instead of being truncated.

changes/fix-prerelease-update-channel.md

@@ -0,0 +1,4 @@
+type: fixed
+area: updater
+
+- Clarified that beta/RC update checks are controlled by `updates.channel`; set it to `"prerelease"` to receive beta/RC updates.

changes/fix-sidebar-yomitan-popup-pause.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Kept playback paused for Yomitan lookup popups opened from the subtitle sidebar when popup auto-pause is enabled.

changes/fix-stats-dialog-layering.md

@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Stats: Fixed in-player stats layering so delete confirmations, overlay modals, and update-check dialogs appear above the stats window.

changes/fix-windows-background-mpv-overlay.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed Windows managed mpv launches from a background SubMiner instance so the existing warm app receives the start command, retargets the new mpv socket, binds to the player window, and receives startup overlay options.

changes/jellyfin-picker-log-level.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Kept Jellyfin picker library discovery working when the running app log level is above info.

changes/jellyfin-visible-overlay.md

@@ -0,0 +1,5 @@
+type: fixed
+area: jellyfin
+
+- Showed the visible subtitle overlay automatically during Jellyfin playback so configured `subtitleStyle` appearance applies to Jellyfin subtitles.
+- Injected the bundled mpv plugin when SubMiner auto-launches mpv for Jellyfin playback, restoring mpv-side keybindings without needing overlay focus.

changes/macos-manual-update-required.md

@@ -1,4 +1,4 @@
 type: fixed
 area: updater
 
-- Fixed tray update checks for builds that cannot install native app updates, showing a manual install message instead of a restart prompt that cannot apply the update.
+- Fixed macOS tray update checks for builds that cannot install native app updates, so newer stable or prerelease GitHub releases are reported instead of incorrectly saying the current build is up to date.

changes/macos-overlay-focus-handoff.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Kept the macOS visible overlay stable when clicking from the overlay back into mpv.

changes/macos-updater-zip-collision.md

@@ -0,0 +1,4 @@
+type: fixed
+area: release
+
+- Fixed macOS updater metadata mismatches by giving macOS and Windows ZIP release assets distinct build-time filenames.

changes/rename-config-window-to-settings.md

@@ -1,7 +0,0 @@
-type: changed
-area: launcher
-breaking: true
-
-- Renamed the SubMiner Configuration window to the Settings window across the UI, tray menu, docs, and CLI verbiage.
-- Replaced the `--config` flag and `subminer config` (no action) entry points with `--settings` and `subminer settings`. The `subminer config` subcommand now only accepts `path` or `show`.
-- Removed the `--settings` alias that previously opened the bundled Yomitan settings popup. Use `--yomitan` to open Yomitan settings.

changes/settings-modal-layout.md

@@ -1,4 +0,0 @@
-type: changed
-area: config
-
-- Settings: reorganized playback, shortcut, WebSocket, tracking, Jellyfin, character dictionary, and Discord presence controls in the settings modal.

changes/windows-mpv-launcher-tray.md

@@ -0,0 +1,4 @@
+type: fixed
+area: tray
+
+- Fixed the Windows tray "Open SubMiner Setup" action so it opens the setup window after first-run setup is already complete.

config.example.jsonc

@@ -384,6 +384,7 @@
     "autoPauseVideoOnHover": true, // Automatically pause mpv playback while hovering subtitle text, then resume on leave. Values: true | false
     "autoPauseVideoOnYomitanPopup": true, // Automatically pause mpv playback while Yomitan popup is open, then resume when popup closes. Values: true | false
     "nameMatchEnabled": false, // Enable subtitle token coloring for matches from the SubMiner character dictionary. Values: true | false
+    "nameMatchImagesEnabled": false, // Show small character portraits beside subtitle tokens matched from the SubMiner character dictionary. Values: true | false
     "nameMatchColor": "#f5bde6", // Hex color used when a subtitle token matches an entry from the SubMiner character dictionary.
     "nPlusOneColor": "#c6a0f6", // Color used for the single N+1 target token subtitle highlight.
     "knownWordColor": "#a6da95", // Color used for known-word subtitle highlights.
@@ -523,7 +524,7 @@
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
       "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
       "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
-      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Values: headword | surface
+      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
       "decks": {} // Decks and fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word", "Word Reading"] }.
     }, // Known words setting.
     "behavior": {
@@ -644,14 +645,10 @@
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
     "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
-    "deviceId": "subminer", // Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.
-    "clientName": "SubMiner", // Client name sent on the Jellyfin authentication handshake; primarily internal.
-    "clientVersion": "0.1.0", // Client version sent on the Jellyfin authentication handshake; primarily internal.
     "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
     "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
     "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false
     "autoAnnounce": false, // When enabled, automatically trigger remote announce/visibility check on websocket connect. Values: true | false
-    "remoteControlDeviceName": "SubMiner", // Device name reported for Jellyfin remote control sessions.
     "pullPictures": false, // Enable Jellyfin poster/icon fetching for launcher menus. Values: true | false
     "iconCacheDir": "/tmp/subminer-jellyfin-icons", // Directory used by launcher for cached Jellyfin poster icons.
     "directPlayPreferred": true, // Try direct play before server-managed transcoding when possible. Values: true | false

docs-site/character-dictionary.md

@@ -91,21 +91,26 @@ Name matching runs inside Yomitan's scanning pipeline during subtitle tokenizati
 2. Entries from "SubMiner Character Dictionary" are checked with exact primary-source matching — the token must match the entry's `originalText` with `isPrimary: true` and `matchType: 'exact'`.
 3. Matched tokens are flagged `isNameMatch: true` and forwarded to the renderer.
 4. If `subtitleStyle.nameMatchEnabled` is enabled, the renderer applies the name-match highlight color (default: `#f5bde6`).
+5. If `subtitleStyle.nameMatchImagesEnabled` is enabled, the renderer also injects a small circular AniList portrait from the cached snapshot image data.
+
+Older snapshot schema versions are regenerated automatically. Current-version snapshots are normally reused, but when `subtitleStyle.nameMatchImagesEnabled` is enabled SubMiner also checks whether the cached snapshot contains usable character portrait data. If it does not, the snapshot is refreshed so the merged dictionary can include images.
 
 Name matches are visually distinct from [N+1 targeting, frequency highlighting, and JLPT tags](/subtitle-annotations) so you can tell at a glance whether a highlighted word is a character name or a vocabulary target.
 
 **Key settings:**
 
-| Option                           | Default   | Description                        |
-| -------------------------------- | --------- | ---------------------------------- |
-| `subtitleStyle.nameMatchEnabled` | `false`   | Toggle character-name highlighting |
-| `subtitleStyle.nameMatchColor`   | `#f5bde6` | Highlight color for matched names  |
+| Option                                 | Default   | Description                               |
+| -------------------------------------- | --------- | ----------------------------------------- |
+| `subtitleStyle.nameMatchEnabled`       | `false`   | Toggle character-name highlighting        |
+| `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits beside names |
+| `subtitleStyle.nameMatchColor`         | `#f5bde6` | Highlight color for matched names         |
 
 ## Dictionary Entries
 
 Each character entry in the Yomitan dictionary includes structured content:
 
-- **Name** — native (Japanese) and romanized forms
+- **Name** — the matched Japanese name form
+- **Known names** — generated non-honorific Japanese aliases for that character, excluding raw romanized/English aliases from lookup results
 - **Role badge** — color-coded by role: main (score 100), supporting (90), side (80), background (70)
 - **Portrait** — character image from AniList, embedded in the ZIP
 - **Description** — biography text from AniList (collapsible)
@@ -169,10 +174,13 @@ This creates a standalone dictionary ZIP for the target media and saves it along
 
 ## Correcting AniList Matches
 
-SubMiner uses `guessit` to infer the anime title from the active filename, then searches AniList. Some filenames can still resolve to the wrong title. For example, `Re - ZERO, Starting Life in Another World (2016)` can be misread as a different `Re...` series.
+SubMiner uses `guessit` to infer the anime title from the active filename before searching AniList. Some filenames can still resolve to the wrong title. For example, `Re - ZERO, Starting Life in Another World (2016)` can be misread as a different `Re...` series.
 
 Use the in-app selector or CLI to pin the correct AniList media for the whole series:
 
+- In-app: open the selector with `Ctrl/Cmd+Alt+A` or `--open-character-dictionary`, edit the prefilled title if needed, then search and choose the correct result.
+- CLI: `--dictionary-candidates` still lists matches for the current filename guess.
+
 ```bash
 # List candidate AniList matches for a file
 subminer dictionary --candidates "/path/to/episode.mkv"
@@ -188,7 +196,7 @@ SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary
 subminer app --open-character-dictionary
 ```
 
-Manual selections are stored in `character-dictionaries/anilist-overrides.json` using a series key derived from the filename guess. Later episodes with the same series key use the selected AniList ID automatically. When the override replaces a previous wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+Manual selections are stored in `character-dictionaries/anilist-overrides.json` using a series key derived from the episode's parent directory plus the filename guess. Later episodes in the same directory use the selected AniList ID automatically, while separate season directories can keep separate overrides and character dictionaries. When the override replaces a previous wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
 
 ## File Structure
 
@@ -207,7 +215,7 @@ character-dictionaries/
     m170942-va67890.jpg       # Voice actor portrait
 ```
 
-**Snapshot format** (v15): each snapshot contains the media ID, title, entry count, timestamp, an array of Yomitan term entries, and base64-encoded images.
+**Snapshot format** (v16): each snapshot contains the media ID, title, entry count, timestamp, an array of Yomitan term entries, and base64-encoded images.
 
 **ZIP structure** follows the Yomitan dictionary format:
 
@@ -231,6 +239,7 @@ merged.zip
 | `anilist.characterDictionary.collapsibleSections.characterInformation` | `false`   | Start Character Information section expanded                    |
 | `anilist.characterDictionary.collapsibleSections.voicedBy`             | `false`   | Start Voiced By section expanded                                |
 | `subtitleStyle.nameMatchEnabled`                                       | `false`   | Toggle character-name highlighting in subtitles                 |
+| `subtitleStyle.nameMatchImagesEnabled`                                 | `false`   | Show small AniList portraits beside matched names               |
 | `subtitleStyle.nameMatchColor`                                         | `#f5bde6` | Highlight color for character-name matches                      |
 
 ## Reference Implementation
@@ -253,8 +262,9 @@ If you work with visual novels or want a standalone dictionary generator indepen
 ## Troubleshooting
 
 - **Names not highlighting:** Confirm `anilist.characterDictionary.enabled` is `true` and `subtitleStyle.nameMatchEnabled` is `true`. Check that the current media has an AniList entry — SubMiner needs a media ID to fetch characters.
+- **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. On the next character dictionary sync, SubMiner refreshes current-version snapshots that do not contain usable cached character portrait data. Portraits still require AniList to return an image and the image download to succeed.
 - **Sync seems stuck:** The auto-sync debounces for 800ms after media changes and throttles image downloads at 250ms per image. Large casts (50+ characters) take longer. Check the status bar for the current sync phase.
-- **Wrong characters showing:** Open the in-app character dictionary selector (`--open-character-dictionary`) or run `--dictionary-candidates`, then save the correct media with `--dictionary-select --dictionary-anilist-id <id>`. This replaces stale wrong-title entries for that series. If names are only from an older unrelated show, they'll rotate out once you watch enough new titles to push it past `maxLoaded`.
+- **Wrong characters showing:** Open the in-app character dictionary selector (`--open-character-dictionary`), edit the search title, and select the right AniList entry. You can also run `--dictionary-candidates`, then save the correct media with `--dictionary-select --dictionary-anilist-id <id>`. This replaces stale wrong-title entries for that series. If names are only from an older unrelated show, they'll rotate out once you watch enough new titles to push it past `maxLoaded`.
 - **Yomitan import fails:** SubMiner waits up to 7 seconds for Yomitan to be ready for mutations. If Yomitan is still loading dictionaries or performing another import, the operation may time out. Restarting the overlay typically resolves this.
 - **Portraits missing:** Images are downloaded from AniList CDN during snapshot generation. If the network was unavailable during the initial sync, delete the snapshot file from `character-dictionaries/snapshots/` and let it regenerate.
 

docs-site/configuration.md

@@ -371,34 +371,35 @@ See `config.example.jsonc` for detailed configuration options.
 }
 ```
 
-| Option                             | Values      | Description                                                                                                                |
-| ---------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `fontFamily`                       | string      | CSS font-family value (default: `"Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP"`)                         |
-| `fontSize`                         | number (px) | Font size in pixels (default: `35`)                                                                                        |
-| `fontColor`                        | string      | Any CSS color value (default: `"#cad3f5"`)                                                                                 |
-| `css`                              | object      | CSS declarations applied to subtitles after normal style defaults; the settings window writes textbox edits here           |
-| `fontWeight`                       | string      | CSS font-weight, e.g. `"bold"`, `"normal"`, `"600"` (default: `"600"`)                                                     |
-| `fontStyle`                        | string      | `"normal"` or `"italic"` (default: `"normal"`)                                                                             |
-| `backgroundColor`                  | string      | Any CSS color, including `"transparent"` (default: `"transparent"`)                                                        |
-| `enableJlpt`                       | boolean     | Enable JLPT level underline styling (`false` by default)                                                                   |
-| `preserveLineBreaks`               | boolean     | Preserve line breaks in visible overlay subtitle rendering (`false` by default). Enable to mirror mpv line layout.         |
-| `autoPauseVideoOnHover`            | boolean     | Pause playback while mouse hovers subtitle text, then resume on leave (`true` by default).                                 |
-| `autoPauseVideoOnYomitanPopup`     | boolean     | Pause playback while the Yomitan popup is open, then resume when the popup closes (`true` by default).                     |
-| `hoverTokenColor`                  | string      | Hex color used for hovered subtitle token highlight in mpv (default: catppuccin mauve)                                     |
+| Option                             | Values      | Description                                                                                                                          |
+| ---------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `fontFamily`                       | string      | CSS font-family value (default: `"Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP"`)                                   |
+| `fontSize`                         | number (px) | Font size in pixels (default: `35`)                                                                                                  |
+| `fontColor`                        | string      | Any CSS color value (default: `"#cad3f5"`)                                                                                           |
+| `css`                              | object      | CSS declarations applied to subtitles after normal style defaults; the settings window writes textbox edits here                     |
+| `fontWeight`                       | string      | CSS font-weight, e.g. `"bold"`, `"normal"`, `"600"` (default: `"600"`)                                                               |
+| `fontStyle`                        | string      | `"normal"` or `"italic"` (default: `"normal"`)                                                                                       |
+| `backgroundColor`                  | string      | Any CSS color, including `"transparent"` (default: `"transparent"`)                                                                  |
+| `enableJlpt`                       | boolean     | Enable JLPT level underline styling (`false` by default)                                                                             |
+| `preserveLineBreaks`               | boolean     | Preserve line breaks in visible overlay subtitle rendering (`false` by default). Enable to mirror mpv line layout.                   |
+| `autoPauseVideoOnHover`            | boolean     | Pause playback while mouse hovers subtitle text, then resume on leave (`true` by default).                                           |
+| `autoPauseVideoOnYomitanPopup`     | boolean     | Pause playback while the Yomitan popup is open, then resume when the popup closes (`true` by default).                               |
+| `hoverTokenColor`                  | string      | Hex color used for hovered subtitle token highlight in mpv (default: catppuccin mauve)                                               |
 | `hoverTokenBackgroundColor`        | string      | CSS color used for hovered subtitle token background highlight (default: `"transparent"`); `hoverBackground` is accepted as an alias |
-| `nameMatchEnabled`                 | boolean     | Enable subtitle token coloring for matches from the SubMiner character dictionary (`false` by default)                     |
-| `nameMatchColor`                   | string      | Hex color used for subtitle tokens matched from the SubMiner character dictionary (default: `#f5bde6`)                     |
-| `knownWordColor`                   | string      | Hex color used for known-word subtitle highlights (default: `#a6da95`)                                                     |
-| `nPlusOneColor`                    | string      | Hex color used for the single N+1 target subtitle highlight (default: `#c6a0f6`)                                           |
-| `frequencyDictionary.enabled`      | boolean     | Enable frequency highlighting from dictionary lookups (`false` by default)                                                 |
-| `frequencyDictionary.sourcePath`   | string      | Path to a local frequency dictionary root. Leave empty or omit to use installed/default frequency-dictionary search paths. |
-| `frequencyDictionary.topX`         | number      | Only color tokens whose frequency rank is `<= topX` (`1000` by default)                                                    |
-| `frequencyDictionary.mode`         | string      | `"single"` or `"banded"` (`"single"` by default)                                                                           |
-| `frequencyDictionary.matchMode`    | string      | `"headword"` or `"surface"` (`"headword"` by default)                                                                      |
-| `frequencyDictionary.singleColor`  | string      | Color used for all highlighted tokens in single mode                                                                       |
-| `frequencyDictionary.bandedColors` | string[]    | Array of five hex colors used for ranked bands in banded mode                                                              |
-| `jlptColors`                       | object      | JLPT level underline colors object (`N1`..`N5`)                                                                            |
-| `secondary`                        | object      | Override any of the above for secondary subtitles (optional), including `secondary.css` declarations                       |
+| `nameMatchEnabled`                 | boolean     | Enable subtitle token coloring for matches from the SubMiner character dictionary (`false` by default)                               |
+| `nameMatchImagesEnabled`           | boolean     | Show small cached AniList character portraits beside matched character-name tokens (`false` by default)                              |
+| `nameMatchColor`                   | string      | Hex color used for subtitle tokens matched from the SubMiner character dictionary (default: `#f5bde6`)                               |
+| `knownWordColor`                   | string      | Hex color used for known-word subtitle highlights (default: `#a6da95`)                                                               |
+| `nPlusOneColor`                    | string      | Hex color used for the single N+1 target subtitle highlight (default: `#c6a0f6`)                                                     |
+| `frequencyDictionary.enabled`      | boolean     | Enable frequency highlighting from dictionary lookups (`false` by default)                                                           |
+| `frequencyDictionary.sourcePath`   | string      | Path to a local frequency dictionary root. Leave empty or omit to use installed/default frequency-dictionary search paths.           |
+| `frequencyDictionary.topX`         | number      | Only color tokens whose frequency rank is `<= topX` (`1000` by default)                                                              |
+| `frequencyDictionary.mode`         | string      | `"single"` or `"banded"` (`"single"` by default)                                                                                     |
+| `frequencyDictionary.matchMode`    | string      | `"headword"` or `"surface"` (`"headword"` by default)                                                                                |
+| `frequencyDictionary.singleColor`  | string      | Color used for all highlighted tokens in single mode                                                                                 |
+| `frequencyDictionary.bandedColors` | string[]    | Array of five hex colors used for ranked bands in banded mode                                                                        |
+| `jlptColors`                       | object      | JLPT level underline colors object (`N1`..`N5`)                                                                                      |
+| `secondary`                        | object      | Override any of the above for secondary subtitles (optional), including `secondary.css` declarations                                 |
 
 The Settings window keeps subtitle color controls separate, then saves CSS textboxes to
 `subtitleStyle.css`, `subtitleStyle.secondary.css`, and `subtitleSidebar.css`. The generated example
@@ -420,6 +421,7 @@ In `single` mode all highlights use `singleColor`; in `banded` mode tokens map t
 Character-name highlighting is separate from N+1 and frequency highlighting:
 
 - `nameMatchEnabled` controls whether SubMiner includes character-dictionary name matches in subtitle token metadata and renderer styling.
+- `nameMatchImagesEnabled` adds small circular portraits beside matched names using the AniList images already cached with character dictionary snapshots.
 - `nameMatchColor` sets the highlight color for those matched character names.
 - Matches come from the bundled SubMiner character dictionary, including AniList-synced merged dictionaries when enabled.
 
@@ -865,15 +867,15 @@ This is the single, shared connection to an OpenAI-compatible LLM endpoint. Conf
 }
 ```
 
-| Option             | Values               | Description                                                                        |
-| ------------------ | -------------------- | ---------------------------------------------------------------------------------- |
-| `enabled`          | `true`, `false`      | Enable shared AI provider features (default: `false`)                              |
-| `apiKey`           | string               | Static API key for the shared provider                                             |
-| `apiKeyCommand`    | string               | Shell command used to resolve the API key (preferred over a plaintext `apiKey`)    |
+| Option             | Values               | Description                                                                          |
+| ------------------ | -------------------- | ------------------------------------------------------------------------------------ |
+| `enabled`          | `true`, `false`      | Enable shared AI provider features (default: `false`)                                |
+| `apiKey`           | string               | Static API key for the shared provider                                               |
+| `apiKeyCommand`    | string               | Shell command used to resolve the API key (preferred over a plaintext `apiKey`)      |
 | `model`            | string               | Default model identifier requested from the provider (default: `openai/gpt-4o-mini`) |
-| `baseUrl`          | string (URL)         | OpenAI-compatible base URL (default: `https://openrouter.ai/api`)                  |
-| `systemPrompt`     | string               | Default system prompt sent with requests (default: a translation-engine prompt)    |
-| `requestTimeoutMs` | integer milliseconds | Shared request timeout (default: `15000`)                                          |
+| `baseUrl`          | string (URL)         | OpenAI-compatible base URL (default: `https://openrouter.ai/api`)                    |
+| `systemPrompt`     | string               | Default system prompt sent with requests (default: a translation-engine prompt)      |
+| `requestTimeoutMs` | integer milliseconds | Shared request timeout (default: `15000`)                                            |
 
 SubMiner uses the shared provider for:
 
@@ -1045,6 +1047,7 @@ Known-word cache policy:
 - Cache state is persisted to `known-words-cache.json` under the app `userData` directory.
 - The cache is automatically invalidated when the configured scope changes (for example, when deck changes).
 - Cache lookups are in-memory. By default, token headwords are matched against cached `Expression` / `Word` values; set `ankiConnect.knownWords.matchMode` to `"surface"` for raw subtitle text matching.
+- A known-word cache match always receives known-word highlighting, even when part-of-speech filters suppress N+1, frequency, or JLPT annotations for that token.
 - Legacy moved keys under `ankiConnect.nPlusOne` (`highlightEnabled`, `refreshMinutes`, `matchMode`, `decks`, `knownWord`) and older `ankiConnect.behavior.nPlusOne*` keys are deprecated and only kept for backward compatibility.
 - Legacy top-level `ankiConnect` migration keys (for example `audioField`, `generateAudio`, `imageType`) are compatibility-only, validated before mapping, and ignored with a warning when invalid.
 - If AnkiConnect is unreachable, the cache remains in its previous state and an on-screen/system status message is shown.
@@ -1124,12 +1127,12 @@ Sync the active subtitle track from the overlay picker using `alass` or `ffsubsy
 }
 ```
 
-| Option           | Values               | Description                                                                                                               |
-| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `alass_path`     | string path          | Path to `alass` executable. Empty or `null` resolves from `PATH`. `alass` must be installed separately.                   |
-| `ffsubsync_path` | string path          | Path to `ffsubsync` executable. Empty or `null` resolves from `PATH`. `ffsubsync` must be installed separately.           |
-| `ffmpeg_path`    | string path          | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
-| `replace`        | `true`, `false`      | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |
+| Option           | Values          | Description                                                                                                               |
+| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `alass_path`     | string path     | Path to `alass` executable. Empty or `null` resolves from `PATH`. `alass` must be installed separately.                   |
+| `ffsubsync_path` | string path     | Path to `ffsubsync` executable. Empty or `null` resolves from `PATH`. `ffsubsync` must be installed separately.           |
+| `ffmpeg_path`    | string path     | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
+| `replace`        | `true`, `false` | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |
 
 Default trigger is `Ctrl+Alt+S` via `shortcuts.triggerSubsync`.
 Customize it there, or set it to `null` to disable.
@@ -1253,7 +1256,6 @@ Jellyfin integration is optional and disabled by default. When enabled, SubMiner
     "remoteControlEnabled": true,
     "remoteControlAutoConnect": true,
     "autoAnnounce": false,
-    "remoteControlDeviceName": "SubMiner",
     "defaultLibraryId": "",
     "directPlayPreferred": true,
     "directPlayContainers": ["mkv", "mp4", "webm", "mov", "flac", "mp3", "aac"],
@@ -1268,21 +1270,17 @@ Jellyfin integration is optional and disabled by default. When enabled, SubMiner
 | `serverUrl`                | string (URL)    | Jellyfin server base URL                                                                                     |
 | `recentServers`            | string[]        | Recent Jellyfin server URLs shown in setup; entries are trimmed, deduped, and capped at 5                    |
 | `username`                 | string          | Default username used by `--jellyfin-login`                                                                  |
-| `deviceId`                 | string          | Client device id sent in auth headers (default: `subminer`)                                                  |
-| `clientName`               | string          | Client name sent in auth headers (default: `SubMiner`)                                                       |
-| `clientVersion`            | string          | Client version sent in auth headers (default: `0.1.0`)                                                       |
 | `defaultLibraryId`         | string          | Default library id for `--jellyfin-items` when CLI value is omitted                                          |
 | `remoteControlEnabled`     | `true`, `false` | Enable Jellyfin cast/remote-control session support                                                          |
 | `remoteControlAutoConnect` | `true`, `false` | Auto-connect Jellyfin remote session on app startup (requires `jellyfin.enabled` and `remoteControlEnabled`) |
 | `autoAnnounce`             | `true`, `false` | Auto-run cast-target visibility announce check on connect (default: `false`)                                 |
-| `remoteControlDeviceName`  | string          | Device name shown in Jellyfin cast/device lists                                                              |
 | `pullPictures`             | `true`, `false` | Enable poster/icon fetching for launcher Jellyfin pickers                                                    |
 | `iconCacheDir`             | string          | Cache directory for launcher-fetched Jellyfin poster icons                                                   |
 | `directPlayPreferred`      | `true`, `false` | Prefer direct stream URLs before transcoding                                                                 |
 | `directPlayContainers`     | string[]        | Container allowlist for direct play decisions                                                                |
 | `transcodeVideoCodec`      | string          | Preferred transcode video codec fallback (default: `h264`)                                                   |
 
-Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted storage after login/setup. The legacy `jellyfin.accessToken` and `jellyfin.userId` config keys are not resolver-backed settings in the current runtime. The Settings window also hides low-level client identity and default library fields (`deviceId`, `clientName`, `clientVersion`, and `defaultLibraryId`) so normal setup stays focused on server, auth, playback, and remote-control behavior.
+Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted storage after login/setup. The legacy `jellyfin.accessToken`, `jellyfin.userId`, `jellyfin.clientName`, `jellyfin.deviceId`, `jellyfin.clientVersion`, and `jellyfin.remoteControlDeviceName` config keys are not resolver-backed settings in the current runtime. SubMiner reports the Jellyfin client as `SubMiner`, derives the Jellyfin device id and visible device name from the OS hostname, and owns the client version internally. The Settings window also hides low-level default library fields (`defaultLibraryId`) so normal setup stays focused on server, auth, playback, and remote-control behavior.
 
 - On Linux, token storage defaults to `gnome-libsecret` for `safeStorage`. Override with `--password-store=<backend>` on launcher/app invocations when needed.
 
@@ -1299,6 +1297,8 @@ See [Jellyfin Integration](/jellyfin-integration) for the full setup and cast-to
 
 Jellyfin remote auto-connect runs only when all three are `true`: `jellyfin.enabled`, `jellyfin.remoteControlEnabled`, and `jellyfin.remoteControlAutoConnect`.
 
+Jellyfin playback auto-launched through SubMiner loads the mpv plugin the same way regular playback does, and shows the visible subtitle overlay automatically so `subtitleStyle` applies to subtitles selected from Jellyfin.
+
 When Jellyfin is enabled with a server URL and SubMiner is running, the tray menu also shows a `Jellyfin Discovery` checkbox. It starts or stops discovery for the current runtime session only and does not write config. Starting discovery still requires a valid stored or environment-provided Jellyfin auth session.
 
 ### Discord Rich Presence

docs-site/installation.md

@@ -173,7 +173,7 @@ If you prefer to install it manually, see [manual launcher install](#manual-laun
 Download the latest installer from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
 
 - `SubMiner-<version>.exe` — installer (recommended)
-- `SubMiner-<version>.zip` — portable fallback
+- `SubMiner-<version>-win.zip` — portable fallback
 
 Make sure `mpv.exe` is on your `PATH`, or set `mpv.executablePath` in the config during first-run setup.
 

docs-site/jellyfin-integration.md

@@ -1,191 +1,118 @@
 # Jellyfin Integration
 
-[Jellyfin](https://jellyfin.org) is a free, self-hosted media server — think of it as your own private streaming service for video you own. If you keep your anime on a Jellyfin server, SubMiner can log in, browse it, and play episodes through mpv with the full mining overlay.
+[Jellyfin](https://jellyfin.org) is a free, self-hosted media server — think of it as your own private streaming service for video you own. If you keep your anime on a Jellyfin server, SubMiner can play episodes through mpv with the full mining overlay.
 
 ::: tip Who needs this?
-This page is only relevant if you already run (or have access to) a Jellyfin server. If you watch local files or YouTube, you can skip it. Most of this integration is driven from the command line, so it is aimed at slightly more advanced users; the in-app setup window (`subminer jellyfin`) is the easiest starting point.
+This page is only relevant if you already run (or have access to) a Jellyfin server. If you watch local files or YouTube, you can skip it. The in-app setup window (`subminer jellyfin`) is the easiest starting point.
 :::
 
-SubMiner includes an optional Jellyfin CLI integration for:
+SubMiner can act as a **cast-to-device target** for Jellyfin (similar to jellyfin-mpv-shim). Sign in once, turn on discovery, and SubMiner shows up in the "Play on…" / cast menu of any Jellyfin app — web, phone, or TV. Pick an episode, cast it to SubMiner, and it plays in SubMiner's mpv window with the full overlay and Yomitan click-to-lookup.
 
-- authenticating against a server
-- listing libraries and media items
-- launching item playback in the connected mpv instance
-- receiving Jellyfin remote cast-to-device playback events in-app
-- opening an in-app setup window for server URL and authentication
-- toggling Jellyfin cast discovery from the tray once configured
+This is the recommended way to use Jellyfin with SubMiner. A terminal-only option is covered in [Launcher playback](#launcher-playback) at the end.
 
 ## Requirements
 
-- Jellyfin server URL and user credentials
-- For `--jellyfin-play`: connected mpv IPC socket (`--start` or existing mpv plugin workflow)
-- On Linux, token encryption defaults to `gnome-libsecret`; pass `--password-store=<backend>` to override.
+- A Jellyfin server plus your username and password
+- SubMiner installed and running (see [Installation](/installation))
+- On Linux, the session token is stored with `gnome-libsecret` by default
 
-## Setup
+## Quick start
 
-1. Set base config values (`config.jsonc`):
+### 1. Start SubMiner
+
+Launch SubMiner so it's running in the system tray.
+
+### 2. Sign in to your server
+
+Open the tray menu and click **Configure Jellyfin**. In the window that opens, enter your **Server URL** (for example `http://127.0.0.1:8096`), **Username**, and **Password**, then click **Login**.
+
+On success, SubMiner:
+
+- saves an encrypted session token — your password is never stored,
+- turns the Jellyfin integration on, and
+- remembers the server and username for next time.
+
+Reopen this window any time to switch servers or **Logout**.
+
+### 3. Turn on discovery
+
+Discovery is what makes SubMiner appear as a cast target. Two ways to enable it:
+
+- **For the current session** — open the tray menu and tick **Jellyfin Discovery**. (This item appears once you've signed in.)
+- **Automatically on every launch** — already on by default. After your first sign-in, SubMiner auto-connects to Jellyfin at startup, so the cast target is ready without touching the tray. You can change this under [Settings](#settings).
+
+### 4. Cast from any Jellyfin app
+
+In the Jellyfin web UI or mobile app, start playing something, open the **cast / "Play on"** menu, and pick your device — SubMiner appears there named after your computer's hostname. Playback opens in SubMiner.
+
+From then on, pause / resume / seek / stop and audio or subtitle track changes you make in the Jellyfin app are mirrored in SubMiner, and your watch progress syncs back to Jellyfin (now-playing and resume position).
+
+## What happens during playback
+
+- **mpv launches automatically.** If mpv isn't already running when you cast, SubMiner starts it with SubMiner defaults and the bundled mpv plugin, so keybindings work right away.
+- **The overlay is managed by SubMiner,** so your configured `subtitleStyle` controls how subtitles look. Use the [overlay-toggle shortcut](/shortcuts) to hide it for a session.
+- **Resume works.** If Jellyfin has a saved position for the item, SubMiner seeks there on load.
+- **Direct play first.** When the source allows it and the container is in your direct-play allowlist, SubMiner streams the original file; otherwise it requests a transcoded stream from Jellyfin.
+- **Japanese subtitles are auto-selected,** preferring Jellyfin's default and embedded tracks over external sidecar files when several match.
+- **Subtitle timing is corrected when possible.** SubMiner removes Jellyfin's server-selected subtitle stream from the mpv load URL, suppresses the mpv plugin's one-shot subtitle auto-selection and overlay auto-start for managed Jellyfin loads, stages downloaded subtitle tracks without letting mpv auto-switch between tracks, then selects the Japanese track once after applying any saved or inferred timing delay. When Jellyfin provides both Japanese and English subtitle files, SubMiner compares their cue timelines and applies a global delay if one track is clearly offset. Manual delay shifts you make with SubMiner's adjacent-cue controls are saved per item and subtitle track, then restored the next time you select that track.
+
+## Settings
+
+All Jellyfin options live under **Settings → Integrations → Jellyfin** (open settings from the tray's **Open SubMiner Settings**). The ones that matter for casting:
+
+| Setting                         | Default | What it does                                                                                                          |
+| ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Enabled**                     | Off     | Turns the Jellyfin integration on. Switched on for you when you sign in.                                              |
+| **Server Url**                  | —       | Your Jellyfin server. Filled in when you sign in.                                                                     |
+| **Remote Control Enabled**      | On      | Lets SubMiner act as a cast target.                                                                                   |
+| **Remote Control Auto Connect** | On      | Connects to Jellyfin at startup so discovery is automatic. Turn off if you'd rather start it from the tray each time. |
+| **Auto Announce**               | Off     | Re-broadcasts visibility on connect. Enable if your device is slow to appear in the cast menu.                        |
+
+Prefer editing the config file? The same keys live under `jellyfin` in `config.jsonc`:
 
 ```jsonc
 {
   "jellyfin": {
     "enabled": true,
     "serverUrl": "http://127.0.0.1:8096",
-    "recentServers": ["http://127.0.0.1:8096"],
-    "username": "your-user",
     "remoteControlEnabled": true,
     "remoteControlAutoConnect": true,
-    "autoAnnounce": false,
-    "remoteControlDeviceName": "SubMiner",
-    "defaultLibraryId": "",
-    "pullPictures": false,
-    "iconCacheDir": "/tmp/subminer-jellyfin-icons",
-    "directPlayPreferred": true,
-    "directPlayContainers": ["mkv", "mp4", "webm", "mov", "flac", "mp3", "aac"],
-    "transcodeVideoCodec": "h264",
   },
 }
 ```
 
-2. Authenticate:
+See [Configuration](/configuration) for the full list (transcode codec, direct-play containers, default library, and more).
+
+## Troubleshooting
+
+**SubMiner doesn't appear in the cast menu**
+
+- Make sure SubMiner is running.
+- Make sure you're signed in — reopen **Configure Jellyfin** and log in again if your token expired.
+- Make sure discovery is on (tray **Jellyfin Discovery**, or **Remote Control Auto Connect** in settings).
+- Make sure SubMiner and the Jellyfin client point at the same server.
+
+**Casting starts but nothing plays**
+
+- Confirm the item plays normally in another Jellyfin client.
+- If mpv was closed, give it a moment — SubMiner launches it on demand and retries.
+
+**SubMiner keeps disconnecting**
+
+- Check server/network stability and whether the session token has expired.
+
+## Security notes
+
+- The Jellyfin session (access token + user ID) is kept in SubMiner's local encrypted token storage. Your password is used only to log in and is never saved.
+- Treat the token storage and your `config.jsonc` as secrets — don't commit them.
+- Advanced/headless: the `SUBMINER_JELLYFIN_ACCESS_TOKEN` and `SUBMINER_JELLYFIN_USER_ID` environment variables can supply a session without the sign-in window.
+
+## Launcher playback
+
+If you'd rather stay in the terminal, the `subminer` launcher can browse and play Jellyfin media directly, without casting from a Jellyfin app:
 
 ```bash
-subminer jellyfin
-subminer jellyfin -l \
-  --server http://127.0.0.1:8096 \
-  --username your-user \
-  --password 'your-password'
+subminer jellyfin -p      # alias: subminer jf -p
 ```
 
-`subminer jellyfin` opens the setup window. It pre-fills the server URL from the configured server, a recent successful server, or the local default. Successful login keeps the window open, stores the Jellyfin session token in encrypted storage, updates the configured server/username/client metadata, and refreshes recent servers. Passwords are never stored.
-
-3. List libraries:
-
-```bash
-SubMiner.AppImage --jellyfin-libraries
-```
-
-Launcher wrapper equivalent for interactive playback flow:
-
-```bash
-subminer jellyfin -p
-```
-
-Launcher wrapper for Jellyfin cast discovery mode (background app + tray):
-
-```bash
-subminer jellyfin -d
-```
-
-After Jellyfin is enabled with a server URL and SubMiner is already running, the tray menu shows `Jellyfin Discovery`. Use that checkbox to start or stop discovery for the current runtime session without changing config. If the stored login session is missing or expired, starting discovery shows a warning and setup remains the path to refresh credentials. It does not survive app restart.
-
-Stop discovery session/app:
-
-```bash
-subminer app --stop
-```
-
-`subminer jf ...` is an alias for `subminer jellyfin ...`.
-
-To clear saved session credentials:
-
-```bash
-subminer jellyfin --logout
-```
-
-4. List items in a library:
-
-```bash
-SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-search term
-```
-
-Optional listing controls:
-
-- `--jellyfin-recursive=true|false` (default: true)
-- `--jellyfin-include-item-types=Series,Season,Folder,CollectionFolder,Movie,...`
-
-These are used by the launcher picker flow to:
-
-- keep root search focused on shows/folders/movies (exclude episode rows)
-- browse selected anime/show directories as folder-or-file lists
-- recurse for playable files only after selecting a folder
-
-5. Start playback:
-
-```bash
-SubMiner.AppImage --start
-SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID
-```
-
-Optional stream overrides:
-
-- `--jellyfin-audio-stream-index N`
-- `--jellyfin-subtitle-stream-index N`
-
-## Playback Behavior
-
-- Direct play is attempted first when:
-  - `jellyfin.directPlayPreferred=true`
-  - media source supports direct stream
-  - source container matches `jellyfin.directPlayContainers`
-- If direct play is not selected/available, SubMiner requests a Jellyfin transcoded stream (`master.m3u8`) using `jellyfin.transcodeVideoCodec`.
-- Resume position (`PlaybackPositionTicks`) is applied via mpv seek.
-- Media title is set in mpv as `[Jellyfin/<mode>] <title>`.
-
-## Cast To Device Mode (jellyfin-mpv-shim style)
-
-When SubMiner is running with a valid Jellyfin session, it can appear as a
-remote playback target in Jellyfin's cast-to-device menu.
-
-### Requirements
-
-- `jellyfin.enabled=true`
-- valid `jellyfin.serverUrl` and Jellyfin auth session (env override or stored login session)
-- `jellyfin.remoteControlEnabled=true` (default)
-- `jellyfin.remoteControlAutoConnect=true` (default) for startup auto-connect
-- `jellyfin.autoAnnounce=false` by default (`true` enables auto announce/visibility check logs on connect)
-
-### Behavior
-
-- SubMiner connects to Jellyfin remote websocket and posts playback capabilities.
-- Startup auto-connect still requires `remoteControlAutoConnect=true`; the tray `Jellyfin Discovery` checkbox can start discovery later even when startup auto-connect is disabled.
-- `Play` events open media in mpv with the same defaults used by `--jellyfin-play`.
-- If mpv IPC is not connected at cast time, SubMiner auto-launches mpv in idle mode with SubMiner defaults and retries playback.
-- `Playstate` events map to mpv pause/resume/seek/stop controls.
-- Stream selection commands (`SetAudioStreamIndex`, `SetSubtitleStreamIndex`) are mapped to mpv track selection.
-- SubMiner reports start/progress/stop timeline updates back to Jellyfin so now-playing and resume state stay synchronized.
-- `--jellyfin-remote-announce` forces an immediate capability re-broadcast and logs whether server sessions can see the device.
-
-### Troubleshooting
-
-- Device not visible in Jellyfin cast menu:
-  - ensure SubMiner is running
-  - ensure session token is valid (`--jellyfin-login` again if needed)
-  - ensure `remoteControlEnabled` is true
-  - use tray `Jellyfin Discovery` or `subminer jellyfin -d` to start discovery
-- Cast command received but playback does not start:
-  - verify mpv IPC can connect (`--start` flow)
-  - verify item is playable from normal `--jellyfin-play --jellyfin-item-id ...`
-- Frequent reconnects:
-  - check Jellyfin server/network stability and token expiration
-
-## Failure Handling
-
-User-visible errors are shown through CLI logs and mpv OSD for:
-
-- invalid credentials
-- expired/invalid token
-- server/network errors
-- missing library/item identifiers
-- no playable source
-- mpv not connected for playback
-
-## Security Notes and Limitations
-
-- Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted token storage after login/setup.
-- Launcher wrappers support `--password-store=<backend>` and forward it through to the app process.
-- Optional environment overrides are supported: `SUBMINER_JELLYFIN_ACCESS_TOKEN` and `SUBMINER_JELLYFIN_USER_ID`.
-- Treat both token storage and config files as secrets and avoid committing them.
-- Password is used only for login and is not stored.
-- Optional setup UI is available via `--jellyfin`; all actions are also available via CLI flags.
-- `subminer` wrapper uses Jellyfin subcommands (`subminer jellyfin ...`, alias `subminer jf ...`). Use `SubMiner.AppImage` for direct `--jellyfin-libraries` and `--jellyfin-items`.
-- For direct app CLI usage (`SubMiner.AppImage ...`), `--jellyfin-server` can override server URL for login/play flows without editing config.
+This opens an fzf picker (add `-R` for rofi) to browse your libraries and episodes, then plays the selected item in SubMiner's mpv with the same overlay, resume, and subtitle behavior described above. Sign in first (step 2) so the launcher can reach your server. See [Launcher Script](/launcher-script) for the rest of the launcher's features.

docs-site/mining-workflow.md

@@ -164,6 +164,8 @@ If your subtitle file is out of sync with the audio, SubMiner can resynchronize
 3. For alass, select a reference subtitle track from the video.
 4. SubMiner runs the sync and reloads the corrected subtitle.
 
+For remote streams, including Jellyfin playback, the modal only offers alass. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync needs direct access to the local media file and is unavailable for stream URLs.
+
 Install the sync tools separately — see [Troubleshooting](/troubleshooting#subtitle-sync-subsync) if the tools are not found.
 
 ## Texthooker

docs-site/public/config.example.jsonc

@@ -384,6 +384,7 @@
     "autoPauseVideoOnHover": true, // Automatically pause mpv playback while hovering subtitle text, then resume on leave. Values: true | false
     "autoPauseVideoOnYomitanPopup": true, // Automatically pause mpv playback while Yomitan popup is open, then resume when popup closes. Values: true | false
     "nameMatchEnabled": false, // Enable subtitle token coloring for matches from the SubMiner character dictionary. Values: true | false
+    "nameMatchImagesEnabled": false, // Show small character portraits beside subtitle tokens matched from the SubMiner character dictionary. Values: true | false
     "nameMatchColor": "#f5bde6", // Hex color used when a subtitle token matches an entry from the SubMiner character dictionary.
     "nPlusOneColor": "#c6a0f6", // Color used for the single N+1 target token subtitle highlight.
     "knownWordColor": "#a6da95", // Color used for known-word subtitle highlights.
@@ -523,7 +524,7 @@
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
       "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
       "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
-      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Values: headword | surface
+      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
       "decks": {} // Decks and fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word", "Word Reading"] }.
     }, // Known words setting.
     "behavior": {
@@ -644,14 +645,10 @@
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
     "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
-    "deviceId": "subminer", // Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.
-    "clientName": "SubMiner", // Client name sent on the Jellyfin authentication handshake; primarily internal.
-    "clientVersion": "0.1.0", // Client version sent on the Jellyfin authentication handshake; primarily internal.
     "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
     "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
     "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false
     "autoAnnounce": false, // When enabled, automatically trigger remote announce/visibility check on websocket connect. Values: true | false
-    "remoteControlDeviceName": "SubMiner", // Device name reported for Jellyfin remote control sessions.
     "pullPictures": false, // Enable Jellyfin poster/icon fetching for launcher menus. Values: true | false
     "iconCacheDir": "/tmp/subminer-jellyfin-icons", // Directory used by launcher for cached Jellyfin poster icons.
     "directPlayPreferred": true, // Try direct play before server-managed transcoding when possible. Values: true | false

docs-site/subtitle-annotations.md

@@ -44,13 +44,15 @@ Character-name matches are built from the active merged SubMiner character dicti
 1. Subtitles are tokenized, then candidate name tokens are matched against the character dictionary via Yomitan's scanning pipeline.
 2. Matching tokens receive a dedicated style distinct from N+1 and frequency layers.
 3. This layer can be independently toggled with `subtitleStyle.nameMatchEnabled`.
+4. When `subtitleStyle.nameMatchImagesEnabled` is also enabled, SubMiner shows the cached AniList portrait beside matched names.
 
 **Key settings:**
 
-| Option                           | Default   | Description                              |
-| -------------------------------- | --------- | ---------------------------------------- |
-| `subtitleStyle.nameMatchEnabled` | `false`   | Enable character-name token highlighting |
-| `subtitleStyle.nameMatchColor`   | `#f5bde6` | Color used for character-name matches    |
+| Option                                 | Default   | Description                                      |
+| -------------------------------------- | --------- | ------------------------------------------------ |
+| `subtitleStyle.nameMatchEnabled`       | `false`   | Enable character-name token highlighting         |
+| `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits next to name tokens |
+| `subtitleStyle.nameMatchColor`         | `#f5bde6` | Color used for character-name matches            |
 
 For full details on dictionary generation, name variant expansion, auto-sync lifecycle, and configuration, see the dedicated [Character Dictionary](/character-dictionary) page.
 
@@ -67,14 +69,14 @@ SubMiner looks up each token's `frequencyRank` from `term_meta_bank_*.json` file
 
 **Key settings:**
 
-| Option                                           | Default      | Description                              |
-| ------------------------------------------------ | ------------ | ---------------------------------------- |
-| `subtitleStyle.frequencyDictionary.enabled`      | `false`      | Enable frequency highlighting            |
-| `subtitleStyle.frequencyDictionary.topX`         | `1000`       | Max frequency rank to highlight          |
-| `subtitleStyle.frequencyDictionary.mode`         | `"single"`   | `"single"` or `"banded"`                 |
-| `subtitleStyle.frequencyDictionary.matchMode`    | `"headword"` | `"headword"` or `"surface"`              |
-| `subtitleStyle.frequencyDictionary.singleColor`  | `#f5a97f`    | Color for single mode                    |
-| `subtitleStyle.frequencyDictionary.bandedColors` | 5 colors[^1] | Array of five hex colors for banded mode |
+| Option                                           | Default      | Description                                                      |
+| ------------------------------------------------ | ------------ | ---------------------------------------------------------------- |
+| `subtitleStyle.frequencyDictionary.enabled`      | `false`      | Enable frequency highlighting                                    |
+| `subtitleStyle.frequencyDictionary.topX`         | `1000`       | Max frequency rank to highlight                                  |
+| `subtitleStyle.frequencyDictionary.mode`         | `"single"`   | `"single"` or `"banded"`                                         |
+| `subtitleStyle.frequencyDictionary.matchMode`    | `"headword"` | `"headword"` or `"surface"`                                      |
+| `subtitleStyle.frequencyDictionary.singleColor`  | `#f5a97f`    | Color for single mode                                            |
+| `subtitleStyle.frequencyDictionary.bandedColors` | 5 colors[^1] | Array of five hex colors for banded mode                         |
 | `subtitleStyle.frequencyDictionary.sourcePath`   | `""`         | Custom path to frequency dictionary root (empty = auto-discover) |
 
 [^1]: Default banded palette (most common → least common): `#ed8796`, `#f5a97f`, `#f9e2af`, `#8bd5ca`, `#8aadf4`.
@@ -122,6 +124,7 @@ All annotation layers can be toggled at runtime via the mpv command menu without
 
 - `ankiConnect.knownWords.highlightEnabled` (`On` / `Off`)
 - `subtitleStyle.nameMatchEnabled` (`On` / `Off`)
+- `subtitleStyle.nameMatchImagesEnabled` (`On` / `Off`)
 - `subtitleStyle.enableJlpt` (`On` / `Off`)
 - `subtitleStyle.frequencyDictionary.enabled` (`On` / `Off`)
 

docs-site/troubleshooting.md

@@ -114,7 +114,7 @@ Automatic checks log failures quietly so playback is not interrupted.
 
 **"SubMiner is up to date" but a prerelease exists**
 
-SubMiner defaults to stable GitHub releases. Set `updates.channel` to `"prerelease"` in `config.jsonc` when you want update checks to include beta and RC releases.
+SubMiner uses the configured release channel for update checks. Set `updates.channel` to `"prerelease"` in `config.jsonc` when you want update checks to include beta and RC releases.
 
 **Launcher update shows a sudo command**
 

docs/RELEASING.md

@@ -88,10 +88,11 @@ Notes:
 - AUR publish is best-effort: the workflow retries transient SSH clone/push failures, then warns and leaves the GitHub Release green if AUR still fails. Follow up with a manual `git push aur master` from the AUR checkout when needed.
 - Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.
 - Release and prerelease workflows upload updater metadata (`*.yml`) and blockmaps (`*.blockmap`) alongside platform artifacts. Do not remove those files while `electron-updater` is enabled.
-- macOS tray app updates use the standard `electron-updater`/Squirrel path. Keep `latest-mac.yml`, the macOS ZIP, and ZIP blockmap published; Squirrel uses the ZIP payload even when the DMG remains the user-facing installer.
+- macOS tray app updates use the standard `electron-updater`/Squirrel path. Keep `latest-mac.yml`, the macOS `SubMiner-<version>-mac.zip`, and ZIP blockmap published; Squirrel uses the ZIP payload even when the DMG remains the user-facing installer.
 - macOS update metadata and full ZIP downloads are routed through `/usr/bin/curl` before Squirrel installation to avoid Electron main-process network crashes on update checks.
 - Windows tray app updates use the standard `electron-updater`/NSIS path. Keep `latest.yml`, the Windows NSIS installer, and installer blockmap published; updater HTTP is routed through main-process fetch to avoid Electron main-process network crashes during update checks.
+- Build config emits distinct ZIP names: `SubMiner-<version>-mac.zip` for the macOS Squirrel updater payload and `SubMiner-<version>-win.zip` for the Windows portable fallback. The user-facing DMG and Windows installer keep the unqualified `SubMiner-<version>` basename.
 - Linux GitHub release metadata and asset downloads also use `/usr/bin/curl` instead of Electron networking for the same reason.
-- Local macOS build-output apps outside `/Applications` or `~/Applications` skip native update checks. To validate auto-update end to end, install the signed and notarized app bundle into one of those Applications folders and point it at a published updater feed.
+- Local macOS build-output apps outside `/Applications` or `~/Applications` skip native update checks. Manual tray and launcher checks still use GitHub release metadata to report newer releases, but automatic notifications stay quiet when native app installation is unsupported. To validate auto-update end to end, install the signed and notarized app bundle into one of those Applications folders and point it at a published updater feed.
 - The first updater-enabled release cannot update older installs automatically. Users need one manual install to get the updater code.
 - Stable auto-update checks ignore beta/RC prereleases by default. Set `updates.channel` to `"prerelease"` on a test install when validating beta/RC updater behavior.

launcher/commands/app-command.ts

@@ -1,19 +1,45 @@
-import { launchTexthookerOnly, runAppCommandWithInherit } from '../mpv.js';
+import {
+  launchAppBackgroundDetached,
+  launchTexthookerOnly,
+  runAppCommandWithInherit,
+} from '../mpv.js';
 import type { LauncherCommandContext } from './context.js';
 
-export function runAppPassthroughCommand(context: LauncherCommandContext): boolean {
+type AppCommandDeps = {
+  platform: () => NodeJS.Platform;
+  runAppCommandWithInherit: (appPath: string, appArgs: string[]) => void;
+  launchAppBackgroundDetached: (
+    appPath: string,
+    logLevel: LauncherCommandContext['args']['logLevel'],
+  ) => void;
+};
+
+const defaultAppCommandDeps: AppCommandDeps = {
+  platform: () => process.platform,
+  runAppCommandWithInherit,
+  launchAppBackgroundDetached,
+};
+
+export function runAppPassthroughCommand(
+  context: LauncherCommandContext,
+  deps: AppCommandDeps = defaultAppCommandDeps,
+): boolean {
   const { args, appPath } = context;
   if (!appPath) {
     return false;
   }
   if (args.settings) {
-    runAppCommandWithInherit(appPath, ['--settings']);
+    deps.runAppCommandWithInherit(appPath, ['--settings']);
     return true;
   }
   if (!args.appPassthrough) {
     return false;
   }
-  runAppCommandWithInherit(appPath, args.appArgs);
+  if (deps.platform() === 'darwin' && args.appArgs.length === 0) {
+    deps.launchAppBackgroundDetached(appPath, args.logLevel);
+    return true;
+  }
+  deps.runAppCommandWithInherit(appPath, args.appArgs);
   return true;
 }
 

launcher/commands/command-modules.test.ts

@@ -7,6 +7,7 @@ import { runConfigCommand } from './config-command.js';
 import { runDictionaryCommand } from './dictionary-command.js';
 import { runDoctorCommand } from './doctor-command.js';
 import { runMpvPreAppCommand } from './mpv-command.js';
+import { runAppPassthroughCommand } from './app-command.js';
 import { runStatsCommand } from './stats-command.js';
 import { runUpdateCommand } from './update-command.js';
 
@@ -168,6 +169,48 @@ test('doctor command forwards refresh-known-words to app binary', () => {
   assert.deepEqual(forwarded, [['--refresh-known-words']]);
 });
 
+test('app command starts default macOS background app detached from launcher', () => {
+  const context = createContext();
+  context.args.appPassthrough = true;
+  context.args.appArgs = [];
+  const calls: string[] = [];
+
+  const handled = runAppPassthroughCommand(context, {
+    platform: () => 'darwin',
+    runAppCommandWithInherit: () => {
+      calls.push('attached');
+    },
+    launchAppBackgroundDetached: (appPath, logLevel) => {
+      calls.push(`detached:${appPath}:${logLevel}`);
+    },
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(calls, ['detached:/tmp/subminer.app:info']);
+});
+
+test('app command keeps explicit passthrough args attached', () => {
+  const context = createContext();
+  context.args.appPassthrough = true;
+  context.args.appArgs = ['--settings'];
+  const forwarded: string[][] = [];
+  const detached: string[] = [];
+
+  const handled = runAppPassthroughCommand(context, {
+    platform: () => 'darwin',
+    runAppCommandWithInherit: (_appPath, appArgs) => {
+      forwarded.push(appArgs);
+    },
+    launchAppBackgroundDetached: () => {
+      detached.push('detached');
+    },
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(forwarded, [['--settings']]);
+  assert.deepEqual(detached, []);
+});
+
 test('mpv pre-app command exits non-zero when socket is not ready', async () => {
   const context = createContext();
   context.args.mpvStatus = true;

launcher/jellyfin.ts

@@ -361,6 +361,21 @@ export function classifyJellyfinChildSelection(
   fail('Selected Jellyfin item is not playable.');
 }
 
+export function buildForwardedJellyfinAppArgs(args: Args, appArgs: string[]): string[] {
+  const forwarded = [...appArgs];
+  const serverOverride = sanitizeServerUrl(args.jellyfinServer || '');
+  if (serverOverride) {
+    forwarded.push('--jellyfin-server', serverOverride);
+  }
+  if (args.passwordStore) {
+    forwarded.push('--password-store', args.passwordStore);
+  }
+  if (!forwarded.some((arg) => arg === '--log-level' || arg.startsWith('--log-level='))) {
+    forwarded.push('--log-level', args.logLevel);
+  }
+  return forwarded;
+}
+
 async function runAppJellyfinListCommand(
   appPath: string,
   args: Args,
@@ -384,14 +399,7 @@ async function runAppJellyfinCommand(
   appArgs: string[],
   label: string,
 ): Promise<{ status: number; output: string; error: string; logOffset: number }> {
-  const forwardedBase = [...appArgs];
-  const serverOverride = sanitizeServerUrl(args.jellyfinServer || '');
-  if (serverOverride) {
-    forwardedBase.push('--jellyfin-server', serverOverride);
-  }
-  if (args.passwordStore) {
-    forwardedBase.push('--password-store', args.passwordStore);
-  }
+  const forwardedBase = buildForwardedJellyfinAppArgs(args, appArgs);
 
   const readLogAppendedSince = (offset: number): string => {
     const logPath = getMpvLogPath();

launcher/main.test.ts

@@ -17,6 +17,7 @@ import {
   parseEpisodePathFromDisplay,
   buildRootSearchGroups,
   classifyJellyfinChildSelection,
+  buildForwardedJellyfinAppArgs,
 } from './jellyfin.js';
 
 type RunResult = {
@@ -878,6 +879,27 @@ test('parseJellyfinItemsFromAppOutput parses item title/id/type tuples', () => {
   ]);
 });
 
+test('buildForwardedJellyfinAppArgs forces app log level for parseable list output', () => {
+  const forwarded = buildForwardedJellyfinAppArgs(
+    {
+      jellyfinServer: 'https://jf.example.test/',
+      passwordStore: 'gnome-libsecret',
+      logLevel: 'info',
+    } as never,
+    ['--jellyfin-libraries'],
+  );
+
+  assert.deepEqual(forwarded, [
+    '--jellyfin-libraries',
+    '--jellyfin-server',
+    'https://jf.example.test',
+    '--password-store',
+    'gnome-libsecret',
+    '--log-level',
+    'info',
+  ]);
+});
+
 test('parseJellyfinErrorFromAppOutput extracts bracketed error lines', () => {
   const parsed = parseJellyfinErrorFromAppOutput(`
 [subminer] - 2026-03-01 13:10:34 - WARN - [main] test warning

launcher/mpv.test.ts

@@ -14,6 +14,7 @@ import {
   buildMpvEnv,
   cleanupPlaybackSession,
   detectBackend,
+  launchAppBackgroundDetached,
   findAppBinary,
   launchAppCommandDetached,
   launchTexthookerOnly,
@@ -256,6 +257,7 @@ test('buildConfiguredMpvDefaultArgs appends maximized launch mode to configured
         '--sub-file-paths=.;subs;subtitles',
         '--sid=auto',
         '--secondary-sid=auto',
+        '--sub-visibility=no',
         '--secondary-sub-visibility=no',
         '--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
         '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
@@ -424,6 +426,34 @@ test('launchAppCommandDetached handles child process spawn errors', async () =>
   }
 });
 
+test('launchAppBackgroundDetached starts background child directly', async () => {
+  const { dir } = createTempSocketPath();
+  const appPath = path.join(dir, 'fake-subminer.sh');
+  const argsPath = path.join(dir, 'args.txt');
+  const envPath = path.join(dir, 'env.txt');
+  fs.writeFileSync(
+    appPath,
+    [
+      '#!/bin/sh',
+      `printf '%s\\n' "$@" > ${JSON.stringify(argsPath)}`,
+      `printf '%s\\n' "$SUBMINER_BACKGROUND_CHILD" > ${JSON.stringify(envPath)}`,
+      '',
+    ].join('\n'),
+  );
+  fs.chmodSync(appPath, 0o755);
+
+  launchAppBackgroundDetached(appPath, 'info');
+
+  const deadline = Date.now() + 1000;
+  while ((!fs.existsSync(argsPath) || !fs.existsSync(envPath)) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+
+  assert.equal(fs.readFileSync(argsPath, 'utf8').trim(), '--start\n--background');
+  assert.equal(fs.readFileSync(envPath, 'utf8').trim(), '1');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
 test('stopOverlay logs a warning when stop command cannot be spawned', () => {
   const originalWrite = process.stdout.write;
   const writes: string[] = [];
@@ -819,6 +849,7 @@ test('startOverlay uses caller config dir for app control socket discovery', asy
   const { dir, socketPath } = createTempSocketPath();
   const configDir = path.join(dir, 'launcher-config');
   const controlSocketPath = getAppControlSocketPath({ configDir, platform: 'linux' });
+  fs.mkdirSync(configDir, { recursive: true });
   const appPath = path.join(dir, 'fake-subminer.sh');
   const appInvocationsPath = path.join(dir, 'app-invocations.log');
   const receivedControlArgv: string[][] = [];

launcher/mpv.ts

@@ -47,13 +47,17 @@ type SpawnTarget = {
   env?: NodeJS.ProcessEnv;
 };
 
-type PathModule = Pick<typeof path, 'join' | 'extname' | 'delimiter' | 'sep' | 'resolve'>;
+type PathModule = Pick<
+  typeof path,
+  'dirname' | 'join' | 'extname' | 'delimiter' | 'sep' | 'resolve' | 'isAbsolute' | 'normalize'
+>;
 
 const DETACHED_IDLE_MPV_PID_FILE = path.join(os.tmpdir(), 'subminer-idle-mpv.pid');
 const OVERLAY_START_SOCKET_READY_TIMEOUT_MS = 900;
 const OVERLAY_START_COMMAND_SETTLE_TIMEOUT_MS = 700;
 const TRANSPORTED_APP_ARGC_ENV = 'SUBMINER_APP_ARGC';
 const TRANSPORTED_APP_ARG_PREFIX = 'SUBMINER_APP_ARG_';
+const BACKGROUND_CHILD_ENV = 'SUBMINER_BACKGROUND_CHILD';
 
 export interface LauncherRuntimePluginPlan {
   scriptPath: string | null;
@@ -62,6 +66,12 @@ export interface LauncherRuntimePluginPlan {
   errorMessage: string | null;
 }
 
+function resolvePluginCandidatePath(candidate: string, pathModule: PathModule): string {
+  return pathModule.isAbsolute(candidate)
+    ? pathModule.normalize(candidate)
+    : pathModule.resolve(candidate);
+}
+
 export function parseMpvArgString(input: string): string[] {
   const chars = input;
   const args: string[] = [];
@@ -291,12 +301,12 @@ export function resolveLauncherRuntimePluginPath(options: {
   pathModule?: typeof path;
   existsSync?: (candidate: string) => boolean;
 }): string | null {
+  const platform = options.platform ?? process.platform;
   const pathModule = options.pathModule ?? path;
   const existsSync = options.existsSync ?? fs.existsSync;
   const env = options.env ?? process.env;
   const dirname = options.dirname ?? __dirname;
   const cwd = options.cwd ?? process.cwd();
-  const platform = options.platform ?? process.platform;
   const homeDir = options.homeDir ?? os.homedir();
   const candidates: string[] = [];
 
@@ -344,7 +354,7 @@ export function resolveLauncherRuntimePluginPath(options: {
 
   const seen = new Set<string>();
   for (const candidate of candidates) {
-    const resolved = pathModule.resolve(candidate);
+    const resolved = resolvePluginCandidatePath(candidate, pathModule);
     if (seen.has(resolved)) continue;
     seen.add(resolved);
     const entrypoint = normalizeRuntimePluginEntrypoint(resolved, { pathModule, existsSync });
@@ -1580,11 +1590,20 @@ export function launchAppStartDetached(appPath: string, logLevel: LogLevel): voi
   launchAppCommandDetached(appPath, startArgs, logLevel, 'start');
 }
 
+export function launchAppBackgroundDetached(appPath: string, logLevel: LogLevel): void {
+  const startArgs = ['--start', '--background'];
+  if (logLevel !== 'info') startArgs.push('--log-level', logLevel);
+  launchAppCommandDetached(appPath, startArgs, logLevel, 'app', {
+    [BACKGROUND_CHILD_ENV]: '1',
+  });
+}
+
 export function launchAppCommandDetached(
   appPath: string,
   appArgs: string[],
   logLevel: LogLevel,
   label: string,
+  extraEnv: NodeJS.ProcessEnv = {},
 ): void {
   if (maybeCaptureAppArgs(appArgs)) {
     return;
@@ -1603,7 +1622,7 @@ export function launchAppCommandDetached(
     const proc = spawn(target.command, target.args, {
       stdio: ['ignore', stdoutFd, stderrFd],
       detached: true,
-      env: buildAppEnv(process.env, target.env),
+      env: buildAppEnv(process.env, { ...target.env, ...extraEnv }),
     });
     proc.once('error', (error) => {
       log('warn', logLevel, `${label}: failed to launch detached app: ${error.message}`);
@@ -1704,7 +1723,7 @@ export async function waitForUnixSocketReady(
   const deadline = nowMs() + timeoutMs;
   while (nowMs() < deadline) {
     try {
-      if (fs.existsSync(socketPath)) {
+      if (process.platform === 'win32' || fs.existsSync(socketPath)) {
         const ready = await canConnectUnixSocket(socketPath);
         if (ready) return true;
       }

launcher/picker.ts

@@ -365,8 +365,8 @@ export function findRofiTheme(scriptPath: string): string | null {
   } else {
     const xdgDataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local/share');
     candidates.push(path.join(xdgDataHome, 'SubMiner/themes', ROFI_THEME_FILE));
-    candidates.push(path.join('/usr/local/share/SubMiner/themes', ROFI_THEME_FILE));
-    candidates.push(path.join('/usr/share/SubMiner/themes', ROFI_THEME_FILE));
+    candidates.push(path.posix.join('/usr/local/share/SubMiner/themes', ROFI_THEME_FILE));
+    candidates.push(path.posix.join('/usr/share/SubMiner/themes', ROFI_THEME_FILE));
   }
 
   candidates.push(path.join(scriptDir, 'assets', 'themes', ROFI_THEME_FILE));

launcher/smoke.e2e.test.ts

@@ -40,6 +40,19 @@ function writeExecutable(filePath: string, body: string): void {
   fs.chmodSync(filePath, 0o755);
 }
 
+function writeFixtureExecutable(basePath: string, body: string): string {
+  if (process.platform !== 'win32') {
+    writeExecutable(basePath, body);
+    return basePath;
+  }
+
+  const scriptPath = `${basePath}.js`;
+  const commandPath = `${basePath}.cmd`;
+  fs.writeFileSync(scriptPath, body);
+  fs.writeFileSync(commandPath, `@echo off\r\n"${process.execPath}" "${scriptPath}" %*\r\n`);
+  return commandPath;
+}
+
 function createSmokeCase(name: string): SmokeCase {
   const baseDir = path.join(process.cwd(), '.tmp', 'launcher-smoke');
   fs.mkdirSync(baseDir, { recursive: true });
@@ -52,8 +65,8 @@ function createSmokeCase(name: string): SmokeCase {
   const socketDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-smoke-sock-'));
   const socketPath = path.join(socketDir, 'subminer.sock');
   const videoPath = path.join(root, 'video.mkv');
-  const fakeAppPath = path.join(binDir, 'fake-subminer');
-  const fakeMpvPath = path.join(binDir, 'mpv');
+  const fakeAppBasePath = path.join(binDir, 'fake-subminer');
+  const fakeMpvBasePath = path.join(binDir, 'mpv');
   const mpvOverlayLogPath = path.join(artifactsDir, 'mpv-overlay.log');
 
   fs.mkdirSync(artifactsDir, { recursive: true });
@@ -74,8 +87,8 @@ function createSmokeCase(name: string): SmokeCase {
   const fakeAppStartLogPath = path.join(artifactsDir, 'fake-app-start.log');
   const fakeAppStopLogPath = path.join(artifactsDir, 'fake-app-stop.log');
 
-  writeExecutable(
-    fakeMpvPath,
+  const fakeMpvPath = writeFixtureExecutable(
+    fakeMpvBasePath,
     `#!/usr/bin/env bun
 const fs = require('node:fs');
 const net = require('node:net');
@@ -113,8 +126,8 @@ process.on('SIGTERM', closeAndExit);
 `,
   );
 
-  writeExecutable(
-    fakeAppPath,
+  const fakeAppPath = writeFixtureExecutable(
+    fakeAppBasePath,
     `#!/usr/bin/env bun
 const fs = require('node:fs');
 
@@ -157,14 +170,21 @@ process.exit(0);
 }
 
 function makeTestEnv(smokeCase: SmokeCase): NodeJS.ProcessEnv {
-  return {
+  const env: NodeJS.ProcessEnv = {
     ...process.env,
     HOME: smokeCase.homeDir,
     XDG_CONFIG_HOME: smokeCase.xdgConfigHome,
     SUBMINER_APPIMAGE_PATH: smokeCase.fakeAppPath,
     SUBMINER_MPV_LOG: smokeCase.mpvOverlayLogPath,
-    PATH: `${smokeCase.binDir}${path.delimiter}${process.env.PATH || ''}`,
   };
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'PATH';
+  env[pathKey] = `${smokeCase.binDir}${path.delimiter}${env[pathKey] || ''}`;
+  for (const key of Object.keys(env)) {
+    if (key !== pathKey && key.toLowerCase() === 'path') {
+      delete env[key];
+    }
+  }
+  return env;
 }
 
 function runLauncher(

launcher/types.ts

@@ -60,6 +60,7 @@ export const DEFAULT_MPV_SUBMINER_ARGS = [
   '--sub-file-paths=.;subs;subtitles',
   '--sid=auto',
   '--secondary-sid=auto',
+  '--sub-visibility=no',
   '--secondary-sub-visibility=no',
   '--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
   '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "subminer",
-  "version": "0.15.0-beta.3",
+  "version": "0.15.0-beta.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "subminer",
-      "version": "0.15.0-beta.3",
+      "version": "0.15.0-beta.6",
       "license": "GPL-3.0-or-later",
       "dependencies": {
         "@fontsource-variable/geist": "^5.2.8",

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.15.0-beta.4",
+  "version": "0.15.0-beta.6",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",
@@ -50,8 +50,8 @@
     "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-session-bindings.lua && lua scripts/test-plugin-binary-windows.lua",
     "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
     "test:launcher:src": "bun test launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/mpv.test.ts launcher/picker.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/smoke.e2e.test.ts && bun run test:plugin:src",
-    "test:core:src": "bun test src/preload-settings.test.ts src/settings/settings-anki-controls.test.ts src/settings/settings-model.test.ts src/settings/settings-field-layout.test.ts src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/ipc.test.ts src/core/services/anki-jimaku-ipc.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/main/runtime/current-subtitle-snapshot.test.ts src/main/runtime/autoplay-tokenization-warm-release.test.ts src/main/runtime/autoplay-subtitle-primer.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/startup-mode-flags.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/main/runtime/update/appimage-updater.test.ts src/main/runtime/update/fetch-adapter.test.ts src/main/runtime/update/release-metadata-policy.test.ts src/main/runtime/update/update-dialogs.test.ts src/main/runtime/update/support-assets.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/subtitle-render-word-class.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts",
-    "test:core:dist": "bun test dist/preload-settings.test.js dist/settings/settings-anki-controls.test.js dist/settings/settings-model.test.js dist/settings/settings-field-layout.test.js dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command.test.js dist/core/services/ipc.test.js dist/core/services/anki-jimaku-ipc.test.js dist/core/services/field-grouping-overlay.test.js dist/core/services/numeric-shortcut-session.test.js dist/core/services/secondary-subtitle.test.js dist/core/services/mpv-render-metrics.test.js dist/core/services/overlay-content-measurement.test.js dist/core/services/mpv-control.test.js dist/core/services/mpv.test.js dist/core/services/runtime-options-ipc.test.js dist/core/services/runtime-config.test.js dist/core/services/yomitan-extension-paths.test.js dist/core/services/config-hot-reload.test.js dist/core/services/discord-presence.test.js dist/core/services/tokenizer.test.js dist/core/services/tokenizer/annotation-stage.test.js dist/core/services/tokenizer/parser-selection-stage.test.js dist/core/services/tokenizer/parser-enrichment-stage.test.js dist/core/services/subsync.test.js dist/core/services/overlay-bridge.test.js dist/core/services/overlay-manager.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/mining.test.js dist/core/services/anki-jimaku.test.js dist/core/services/jimaku-download-path.test.js dist/core/services/jellyfin.test.js dist/core/services/jellyfin-remote.test.js dist/core/services/immersion-tracker-service.test.js dist/core/services/overlay-runtime-init.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js dist/core/services/subtitle-processing-controller.test.js dist/main/runtime/current-subtitle-snapshot.test.js dist/main/runtime/autoplay-tokenization-warm-release.test.js dist/main/runtime/autoplay-subtitle-primer.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/anilist/anilist-update-queue.test.js dist/core/services/anilist/rate-limiter.test.js dist/core/services/jlpt-token-filter.test.js dist/core/services/subtitle-position.test.js dist/renderer/error-recovery.test.js dist/renderer/subtitle-render.test.js dist/renderer/subtitle-render-word-class.test.js dist/renderer/handlers/mouse.test.js dist/renderer/handlers/keyboard.test.js dist/renderer/modals/jimaku.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/hyprland-tracker.test.js dist/window-trackers/x11-tracker.test.js dist/window-trackers/windows-helper.test.js dist/window-trackers/windows-tracker.test.js",
+    "test:core:src": "bun test src/preload-settings.test.ts src/settings/settings-anki-controls.test.ts src/settings/settings-model.test.ts src/settings/settings-field-layout.test.ts src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/ipc.test.ts src/core/services/anki-jimaku-ipc.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/stats-window-lifecycle.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/main/runtime/current-subtitle-snapshot.test.ts src/main/runtime/autoplay-tokenization-warm-release.test.ts src/main/runtime/autoplay-subtitle-primer.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/startup-mode-flags.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/main/runtime/update/appimage-updater.test.ts src/main/runtime/update/fetch-adapter.test.ts src/main/runtime/update/release-metadata-policy.test.ts src/main/runtime/update/update-dialogs.test.ts src/main/runtime/update/support-assets.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/subtitle-render-word-class.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts",
+    "test:core:dist": "bun test dist/preload-settings.test.js dist/settings/settings-anki-controls.test.js dist/settings/settings-model.test.js dist/settings/settings-field-layout.test.js dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command.test.js dist/core/services/ipc.test.js dist/core/services/anki-jimaku-ipc.test.js dist/core/services/field-grouping-overlay.test.js dist/core/services/numeric-shortcut-session.test.js dist/core/services/secondary-subtitle.test.js dist/core/services/mpv-render-metrics.test.js dist/core/services/overlay-content-measurement.test.js dist/core/services/mpv-control.test.js dist/core/services/mpv.test.js dist/core/services/runtime-options-ipc.test.js dist/core/services/runtime-config.test.js dist/core/services/yomitan-extension-paths.test.js dist/core/services/config-hot-reload.test.js dist/core/services/discord-presence.test.js dist/core/services/tokenizer.test.js dist/core/services/tokenizer/annotation-stage.test.js dist/core/services/tokenizer/parser-selection-stage.test.js dist/core/services/tokenizer/parser-enrichment-stage.test.js dist/core/services/subsync.test.js dist/core/services/overlay-bridge.test.js dist/core/services/overlay-manager.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/stats-window-lifecycle.test.js dist/core/services/mining.test.js dist/core/services/anki-jimaku.test.js dist/core/services/jimaku-download-path.test.js dist/core/services/jellyfin.test.js dist/core/services/jellyfin-remote.test.js dist/core/services/immersion-tracker-service.test.js dist/core/services/overlay-runtime-init.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js dist/core/services/subtitle-processing-controller.test.js dist/main/runtime/current-subtitle-snapshot.test.js dist/main/runtime/autoplay-tokenization-warm-release.test.js dist/main/runtime/autoplay-subtitle-primer.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/anilist/anilist-update-queue.test.js dist/core/services/anilist/rate-limiter.test.js dist/core/services/jlpt-token-filter.test.js dist/core/services/subtitle-position.test.js dist/renderer/error-recovery.test.js dist/renderer/subtitle-render.test.js dist/renderer/subtitle-render-word-class.test.js dist/renderer/handlers/mouse.test.js dist/renderer/handlers/keyboard.test.js dist/renderer/modals/jimaku.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/hyprland-tracker.test.js dist/window-trackers/x11-tracker.test.js dist/window-trackers/windows-helper.test.js dist/window-trackers/windows-tracker.test.js",
     "test:core:smoke:dist": "bun test dist/cli/help.test.js dist/core/services/runtime-config.test.js dist/core/services/ipc.test.js dist/core/services/overlay-manager.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/startup-bootstrap.test.js dist/renderer/error-recovery.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/x11-tracker.test.js",
     "test:smoke:dist": "bun run test:config:smoke:dist && bun run test:core:smoke:dist",
     "test:subtitle:src": "bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts",
@@ -158,6 +158,7 @@
       ]
     },
     "mac": {
+      "artifactName": "SubMiner-${version}-mac.${ext}",
       "target": [
         "dmg",
         "zip"
@@ -174,7 +175,11 @@
         }
       ]
     },
+    "dmg": {
+      "artifactName": "SubMiner-${version}.${ext}"
+    },
     "win": {
+      "artifactName": "SubMiner-${version}-win.${ext}",
       "target": [
         "nsis",
         "zip"
@@ -182,6 +187,7 @@
       "icon": "assets/SubMiner.ico"
     },
     "nsis": {
+      "artifactName": "SubMiner-${version}.${ext}",
       "oneClick": false,
       "perMachine": false,
       "allowToChangeInstallationDirectory": true,

plugin/subminer/binary.lua

@@ -114,6 +114,13 @@ function M.create(ctx)
 			end
 		end
 
+		if not environment.is_windows() then
+			local appimage_path = resolve_binary_candidate(os.getenv("APPIMAGE"))
+			if appimage_path and appimage_path ~= "" then
+				return appimage_path
+			end
+		end
+
 		return nil
 	end
 

plugin/subminer/environment.lua

@@ -13,6 +13,16 @@ function M.create(ctx)
 	local APP_RUNNING_CACHE_TTL_SECONDS = 2
 
 	local function is_windows()
+		local platform = mp.get_property("platform") or ""
+		if platform ~= "" then
+			local normalized = platform:lower()
+			if normalized == "windows" or normalized == "win32" then
+				return true
+			end
+			if normalized == "macos" or normalized == "darwin" or normalized == "osx" or normalized == "linux" then
+				return false
+			end
+		end
 		return package.config:sub(1, 1) == "\\"
 	end
 

plugin/subminer/lifecycle.lua

@@ -33,6 +33,20 @@ function M.create(ctx)
 		return nil
 	end
 
+	local function resolve_media_title()
+		local media_title = mp.get_property("media-title")
+		if type(media_title) == "string" and media_title ~= "" then
+			return media_title
+		end
+
+		local filename = mp.get_property("filename")
+		if type(filename) == "string" and filename ~= "" then
+			return filename
+		end
+
+		return nil
+	end
+
 	local function is_reload_end_file(reason)
 		return reason == "reload" or reason == "redirect"
 	end
@@ -71,6 +85,10 @@ function M.create(ctx)
 		if not has_matching_subminer_socket() then
 			return false
 		end
+		if state.skip_managed_subtitle_rearm_once then
+			state.skip_managed_subtitle_rearm_once = false
+			return true
+		end
 		mp.set_property_native("sub-auto", "fuzzy")
 		mp.set_property_native("sid", "auto")
 		mp.set_property_native("secondary-sid", "auto")
@@ -125,6 +143,10 @@ function M.create(ctx)
 
 	local function on_start_file()
 		if state.pending_reload_media_identity ~= nil then
+			local media_identity = resolve_media_identity()
+			if media_identity ~= nil and media_identity ~= state.pending_reload_media_identity then
+				rearm_managed_subtitle_load_defaults()
+			end
 			return
 		end
 		rearm_managed_subtitle_load_defaults()
@@ -132,24 +154,56 @@ function M.create(ctx)
 
 	local function on_file_loaded()
 		local media_identity = resolve_media_identity()
+		local media_title = resolve_media_title()
 		local retry_generation = next_auto_start_retry_generation()
 		local previous_media_identity = state.current_media_identity
+		local pending_reload_title = state.pending_reload_media_title
+		local pending_reload_reason = state.pending_reload_reason
 		local same_media_reload = (
 			media_identity ~= nil
 			and state.pending_reload_media_identity ~= nil
 			and media_identity == state.pending_reload_media_identity
+		) or (
+			state.pending_reload_media_identity ~= nil
+			and media_title ~= nil
+			and pending_reload_title ~= nil
+			and media_title == pending_reload_title
+		) or (
+			pending_reload_reason == "redirect"
+			and state.pending_reload_media_identity ~= nil
 		)
 		local same_media_loaded = (
 			media_identity ~= nil
 			and previous_media_identity ~= nil
 			and media_identity == previous_media_identity
 		)
+		local new_media_loaded = media_identity ~= nil and not same_media_reload and not same_media_loaded
 		state.pending_reload_media_identity = nil
+		state.pending_reload_media_title = nil
+		state.pending_reload_reason = nil
 		state.current_media_identity = media_identity
+		state.current_media_title = media_title
+		if state.app_managed_playback_pending then
+			state.app_managed_playback_pending = false
+			state.app_managed_playback_active = true
+		elseif new_media_loaded then
+			state.app_managed_playback_active = false
+		end
+		if new_media_loaded then
+			state.suppress_ready_overlay_restore = false
+		end
 
 		if same_media_reload then
 			subminer_log("debug", "lifecycle", "Skipping startup lifecycle for same-media mpv reload")
-			if state.overlay_running and resolve_auto_start_enabled() and process.has_matching_mpv_ipc_socket(opts.socket_path) then
+			if state.app_managed_playback_active then
+				return
+			end
+			if
+				state.overlay_running
+				and not state.suppress_ready_overlay_restore
+				and resolve_auto_start_enabled()
+				and process.has_matching_mpv_ipc_socket(opts.socket_path)
+			then
 				process.run_control_command_async("show-visible-overlay", {
 					socket_path = opts.socket_path,
 				})
@@ -167,6 +221,11 @@ function M.create(ctx)
 			process.disarm_auto_play_ready_gate()
 		end
 
+		if state.app_managed_playback_active then
+			subminer_log("debug", "lifecycle", "Skipping plugin auto-start for app-managed subtitle preload")
+			return
+		end
+
 		if should_auto_start then
 			start_overlay_when_socket_ready(retry_generation, media_identity, same_media_loaded, 1)
 			return
@@ -182,7 +241,12 @@ function M.create(ctx)
 		hover.clear_hover_overlay()
 		process.disarm_auto_play_ready_gate()
 		state.current_media_identity = nil
+		state.current_media_title = nil
 		state.pending_reload_media_identity = nil
+		state.pending_reload_media_title = nil
+		state.pending_reload_reason = nil
+		state.app_managed_playback_pending = false
+		state.app_managed_playback_active = false
 	end
 
 	local function register_lifecycle_hooks()
@@ -198,11 +262,18 @@ function M.create(ctx)
 			local reason = type(event) == "table" and event.reason or nil
 			if is_reload_end_file(reason) then
 				state.pending_reload_media_identity = state.current_media_identity or resolve_media_identity()
+				state.pending_reload_media_title = state.current_media_title or resolve_media_title()
+				state.pending_reload_reason = reason
 				return
 			end
 			next_auto_start_retry_generation()
 			state.current_media_identity = nil
+			state.current_media_title = nil
 			state.pending_reload_media_identity = nil
+			state.pending_reload_media_title = nil
+			state.pending_reload_reason = nil
+			state.app_managed_playback_pending = false
+			state.app_managed_playback_active = false
 			if state.overlay_running and reason ~= "quit" then
 				process.hide_visible_overlay()
 			end

plugin/subminer/messages.lua

@@ -6,6 +6,7 @@ function M.create(ctx)
 	local aniskip = ctx.aniskip
 	local hover = ctx.hover
 	local ui = ctx.ui
+	local state = ctx.state
 
 	local function register_script_messages()
 		mp.register_script_message("subminer-start", function(...)
@@ -17,6 +18,16 @@ function M.create(ctx)
 		mp.register_script_message("subminer-toggle", function()
 			process.toggle_overlay()
 		end)
+		mp.register_script_message("subminer-visible-overlay-hidden", function()
+			process.record_visible_overlay_visibility(false)
+		end)
+		mp.register_script_message("subminer-visible-overlay-shown", function()
+			process.record_visible_overlay_visibility(true)
+		end)
+		mp.register_script_message("subminer-managed-subtitles-loading", function()
+			state.skip_managed_subtitle_rearm_once = true
+			state.app_managed_playback_pending = true
+		end)
 		mp.register_script_message("subminer-menu", function()
 			ui.show_menu()
 		end)

plugin/subminer/process.lua

@@ -7,6 +7,7 @@ local OVERLAY_RESTART_PING_MAX_ATTEMPTS = 20
 local AUTO_PLAY_READY_LOADING_OSD = "Loading subtitle tokenization..."
 local AUTO_PLAY_READY_READY_OSD = "Subtitle tokenization ready"
 local DEFAULT_AUTO_PLAY_READY_TIMEOUT_SECONDS = 15
+local DUPLICATE_VISIBLE_OVERLAY_TOGGLE_SECONDS = 0.25
 
 function M.create(ctx)
 	local mp = ctx.mp
@@ -31,6 +32,16 @@ function M.create(ctx)
 		return options_helper.coerce_bool(raw_visible_overlay, false)
 	end
 
+	local function resolve_auto_start_visibility_action()
+		if resolve_visible_overlay_startup() then
+			if state.suppress_ready_overlay_restore then
+				return nil
+			end
+			return "show-visible-overlay"
+		end
+		return "hide-visible-overlay"
+	end
+
 	local function resolve_pause_until_ready()
 		local raw_pause_until_ready = opts.auto_start_pause_until_ready
 		if raw_pause_until_ready == nil then
@@ -67,6 +78,89 @@ function M.create(ctx)
 		return DEFAULT_AUTO_PLAY_READY_TIMEOUT_SECONDS
 	end
 
+	local function record_visible_overlay_action(action)
+		if action == "show-visible-overlay" then
+			state.visible_overlay_requested = true
+			state.suppress_ready_overlay_restore = false
+		elseif action == "hide-visible-overlay" then
+			state.visible_overlay_requested = false
+		elseif action == "toggle-visible-overlay" and state.visible_overlay_requested ~= nil then
+			state.visible_overlay_requested = not state.visible_overlay_requested
+			if state.visible_overlay_requested then
+				state.suppress_ready_overlay_restore = false
+			end
+		end
+	end
+
+	local function record_visible_overlay_visibility(visible)
+		if visible then
+			state.visible_overlay_requested = true
+			state.suppress_ready_overlay_restore = false
+			return
+		end
+		state.visible_overlay_requested = false
+		state.suppress_ready_overlay_restore = true
+	end
+
+	local function record_start_visibility_args(args)
+		for _, arg in ipairs(args) do
+			if arg == "--show-visible-overlay" then
+				record_visible_overlay_action("show-visible-overlay")
+				return
+			end
+			if arg == "--hide-visible-overlay" then
+				record_visible_overlay_action("hide-visible-overlay")
+				return
+			end
+		end
+	end
+
+	local function should_run_visibility_action(action)
+		if action == "show-visible-overlay" and state.visible_overlay_requested == true then
+			return false
+		end
+		if action == "hide-visible-overlay" and state.visible_overlay_requested == false then
+			return false
+		end
+		return true
+	end
+
+	local function run_visibility_action_if_needed(action, overrides, callback)
+		if action == nil then
+			if callback then
+				callback(true)
+			end
+			return
+		end
+		if not should_run_visibility_action(action) then
+			subminer_log("debug", "process", "Skipping duplicate visible overlay action: " .. tostring(action))
+			if callback then
+				callback(true)
+			end
+			return
+		end
+		run_control_command_async(action, overrides, callback)
+	end
+
+	local function should_ignore_duplicate_visible_overlay_toggle()
+		if type(mp.get_time) ~= "function" then
+			return false
+		end
+		local now = mp.get_time()
+		if type(now) ~= "number" then
+			return false
+		end
+
+		local previous = state.last_visible_overlay_toggle_time
+		state.last_visible_overlay_toggle_time = now
+		if type(previous) ~= "number" then
+			return false
+		end
+
+		local elapsed = now - previous
+		return elapsed >= 0 and elapsed < DUPLICATE_VISIBLE_OVERLAY_TOGGLE_SECONDS
+	end
+
 	local function normalize_socket_path(path)
 		if type(path) ~= "string" then
 			return nil
@@ -129,7 +223,7 @@ function M.create(ctx)
 
 	local function release_auto_play_ready_gate(reason)
 		if not state.auto_play_ready_gate_armed then
-			return
+			return false
 		end
 		local should_resume_playback = state.auto_play_ready_should_resume_playback == true
 		disarm_auto_play_ready_gate({ resume_playback = false })
@@ -140,6 +234,7 @@ function M.create(ctx)
 		else
 			subminer_log("info", "process", "Startup gate ready; leaving playback paused: " .. tostring(reason or "ready"))
 		end
+		return true
 	end
 
 	local function arm_auto_play_ready_gate()
@@ -179,9 +274,12 @@ function M.create(ctx)
 	end
 
 	local function notify_auto_play_ready()
-		release_auto_play_ready_gate("tokenization-ready")
+		local released_ready_gate = release_auto_play_ready_gate("tokenization-ready")
 		local force_ready_overlay_restore = state.force_ready_overlay_restore == true
 		state.force_ready_overlay_restore = false
+		if not released_ready_gate and not force_ready_overlay_restore then
+			return
+		end
 		if state.suppress_ready_overlay_restore and not force_ready_overlay_restore then
 			return
 		end
@@ -189,7 +287,7 @@ function M.create(ctx)
 			state.suppress_ready_overlay_restore = false
 		end
 		if state.overlay_running and (force_ready_overlay_restore or resolve_visible_overlay_startup()) then
-			run_control_command_async("show-visible-overlay", {
+			run_visibility_action_if_needed("show-visible-overlay", {
 				socket_path = opts.socket_path,
 			})
 		end
@@ -224,7 +322,7 @@ function M.create(ctx)
 
 			local should_show_visible = overrides.show_visible_overlay
 			if should_show_visible == nil then
-				should_show_visible = resolve_visible_overlay_startup()
+				should_show_visible = resolve_visible_overlay_startup() and not state.suppress_ready_overlay_restore
 			end
 			if should_show_visible then
 				table.insert(args, "--show-visible-overlay")
@@ -315,6 +413,9 @@ function M.create(ctx)
 			capture_stderr = true,
 		}, function(success, result, error)
 			local ok = success and (result == nil or result.status == 0)
+			if ok then
+				record_visible_overlay_action(action)
+			end
 			if callback then
 				callback(ok, result, error)
 			end
@@ -399,9 +500,6 @@ function M.create(ctx)
 
 	local function start_overlay(overrides)
 		overrides = overrides or {}
-		if overrides.auto_start_trigger == true then
-			state.suppress_ready_overlay_restore = false
-		end
 
 		if not binary.ensure_binary_available() then
 			subminer_log("error", "binary", "SubMiner binary not found")
@@ -424,10 +522,8 @@ function M.create(ctx)
 				elseif not state.auto_play_ready_gate_armed then
 					disarm_auto_play_ready_gate()
 				end
-				local visibility_action = resolve_visible_overlay_startup()
-						and "show-visible-overlay"
-					or "hide-visible-overlay"
-				run_control_command_async(visibility_action, {
+				local visibility_action = resolve_auto_start_visibility_action()
+				run_visibility_action_if_needed(visibility_action, {
 					socket_path = socket_path,
 					log_level = overrides.log_level,
 				})
@@ -470,6 +566,7 @@ function M.create(ctx)
 			state.overlay_running = true
 
 			local command = build_subprocess_command(args)
+			record_start_visibility_args(args)
 			mp.command_native_async({
 				name = "subprocess",
 				args = command.args,
@@ -495,13 +592,11 @@ function M.create(ctx)
 				end
 
 				if overrides.auto_start_trigger == true then
-					local visibility_action = resolve_visible_overlay_startup()
-							and "show-visible-overlay"
-						or "hide-visible-overlay"
-						run_control_command_async(visibility_action, {
-							socket_path = socket_path,
-							log_level = overrides.log_level,
-						})
+					local visibility_action = resolve_auto_start_visibility_action()
+					run_visibility_action_if_needed(visibility_action, {
+						socket_path = socket_path,
+						log_level = overrides.log_level,
+					})
 				end
 
 			end)
@@ -546,7 +641,8 @@ function M.create(ctx)
 		show_osd("Stopped")
 	end
 
-	local function hide_visible_overlay()
+	local function hide_visible_overlay(options)
+		options = options or {}
 		if not binary.ensure_binary_available() then
 			subminer_log("error", "binary", "SubMiner binary not found")
 			return
@@ -566,7 +662,9 @@ function M.create(ctx)
 			end
 		end)
 
-		disarm_auto_play_ready_gate()
+		disarm_auto_play_ready_gate({
+			resume_playback = options.resume_playback ~= false,
+		})
 	end
 
 	local function toggle_overlay()
@@ -575,7 +673,28 @@ function M.create(ctx)
 			show_osd("Error: binary not found")
 			return
 		end
+		if should_ignore_duplicate_visible_overlay_toggle() then
+			subminer_log("debug", "process", "Ignoring duplicate visible overlay toggle")
+			return
+		end
+		if state.visible_overlay_requested == true then
+			state.suppress_ready_overlay_restore = true
+			hide_visible_overlay({ resume_playback = false })
+			return
+		end
+		if state.visible_overlay_requested == false then
+			state.suppress_ready_overlay_restore = false
+			disarm_auto_play_ready_gate({ resume_playback = false })
+			run_control_command_async("show-visible-overlay", nil, function(ok)
+				if not ok then
+					subminer_log("warn", "process", "Show-visible-overlay command failed")
+					show_osd("Toggle failed")
+				end
+			end)
+			return
+		end
 		state.suppress_ready_overlay_restore = true
+		disarm_auto_play_ready_gate({ resume_playback = false })
 
 		run_control_command_async("toggle-visible-overlay", nil, function(ok)
 			if not ok then
@@ -705,6 +824,7 @@ function M.create(ctx)
 		build_command_args = build_command_args,
 		has_matching_mpv_ipc_socket = has_matching_mpv_ipc_socket,
 		run_control_command_async = run_control_command_async,
+		record_visible_overlay_visibility = record_visible_overlay_visibility,
 		run_binary_command_async = run_binary_command_async,
 		parse_start_script_message_overrides = parse_start_script_message_overrides,
 		ensure_texthooker_running = ensure_texthooker_running,

plugin/subminer/session_bindings.lua

@@ -33,6 +33,30 @@ local MODIFIER_MAP = {
 	meta = "Meta",
 }
 
+local SHIFTED_KEY_NAME_MAP = {
+	Digit1 = "!",
+	Digit2 = "@",
+	Digit3 = "SHARP",
+	Digit4 = "$",
+	Digit5 = "%",
+	Digit6 = "^",
+	Digit7 = "&",
+	Digit8 = "*",
+	Digit9 = "(",
+	Digit0 = ")",
+	Minus = "_",
+	Equal = "+",
+	BracketLeft = "{",
+	BracketRight = "}",
+	Backslash = "|",
+	Semicolon = ":",
+	Quote = '"',
+	Comma = "<",
+	Period = ">",
+	Slash = "?",
+	Backquote = "~",
+}
+
 function M.create(ctx)
 	local mp = ctx.mp
 	local utils = ctx.utils
@@ -84,7 +108,22 @@ function M.create(ctx)
 		return nil
 	end
 
-	local function key_spec_to_mpv_binding(key)
+	local function contains_value(values, target)
+		for _, value in ipairs(values) do
+			if value == target then
+				return true
+			end
+		end
+		return false
+	end
+
+	local function append_unique(values, value)
+		if not contains_value(values, value) then
+			values[#values + 1] = value
+		end
+	end
+
+	local function key_spec_to_mpv_bindings(key)
 		if type(key) ~= "table" then
 			return nil
 		end
@@ -123,7 +162,24 @@ function M.create(ctx)
 			end
 		end
 		parts[#parts + 1] = key_name
-		return table.concat(parts, "+")
+		local bindings = { table.concat(parts, "+") }
+
+		local shifted_key_name = SHIFTED_KEY_NAME_MAP[key.code]
+		if has_shift and shifted_key_name then
+			local shifted_parts = {}
+			for _, modifier in ipairs(key.modifiers) do
+				if modifier ~= "shift" then
+					local mapped = MODIFIER_MAP[modifier]
+					if mapped then
+						shifted_parts[#shifted_parts + 1] = mapped
+					end
+				end
+			end
+			shifted_parts[#shifted_parts + 1] = shifted_key_name
+			append_unique(bindings, table.concat(shifted_parts, "+"))
+		end
+
+		return bindings
 	end
 
 	local function build_cli_args(action_id, payload)
@@ -251,6 +307,11 @@ function M.create(ctx)
 			return
 		end
 
+		if binding.actionId == "toggleVisibleOverlay" and type(process.toggle_overlay) == "function" then
+			process.toggle_overlay()
+			return
+		end
+
 		invoke_cli_action(binding.actionId, binding.payload)
 	end
 
@@ -289,13 +350,20 @@ function M.create(ctx)
 		local generation = state.session_binding_generation
 
 		for index, binding in ipairs(artifact.bindings) do
-			local key_name = key_spec_to_mpv_binding(binding.key)
-			if key_name then
-				local name = "subminer-session-binding-" .. tostring(generation) .. "-" .. tostring(index)
-				next_binding_names[#next_binding_names + 1] = name
-				mp.add_forced_key_binding(key_name, name, function()
-					handle_binding(binding)
-				end)
+			local key_names = key_spec_to_mpv_bindings(binding.key)
+			if key_names then
+				for key_index, key_name in ipairs(key_names) do
+					local name = "subminer-session-binding-"
+						.. tostring(generation)
+						.. "-"
+						.. tostring(index)
+						.. "-"
+						.. tostring(key_index)
+					next_binding_names[#next_binding_names + 1] = name
+					mp.add_forced_key_binding(key_name, name, function()
+						handle_binding(binding)
+					end)
+				end
 			else
 				subminer_log(
 					"warn",

plugin/subminer/state.lua

@@ -35,8 +35,15 @@ function M.new()
 		auto_play_ready_osd_timer = nil,
 		suppress_ready_overlay_restore = false,
 		force_ready_overlay_restore = false,
+		visible_overlay_requested = nil,
+		last_visible_overlay_toggle_time = nil,
 		current_media_identity = nil,
+		current_media_title = nil,
 		pending_reload_media_identity = nil,
+		pending_reload_media_title = nil,
+		pending_reload_reason = nil,
+		app_managed_playback_pending = false,
+		app_managed_playback_active = false,
 		auto_start_retry_generation = 0,
 		session_binding_generation = 0,
 		session_binding_names = {},

release/prerelease-notes.md

@@ -1,43 +1,59 @@
 > This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.
 
 ## Highlights
-### Breaking Changes
-
-- **Settings Window:** The Configuration window is now called the Settings window everywhere — UI, tray menu, docs, and CLI. `--config` and `subminer config` (no action) are replaced by `--settings` and `subminer settings`; `subminer config` now only accepts `path` or `show`. The `--settings` alias that previously opened the Yomitan settings popup is removed — use `--yomitan` instead.
-
 ### Added
 
-- **Settings Window:** A dedicated Settings window is now available via `subminer --settings` or `subminer settings`. Options are organized into Appearance, Behavior, Anki, Input, and Integration sections with learned keybinding controls, AnkiConnect-backed deck/field/note-type pickers, and live reload for stats keys, logging level, Jimaku, Subsync, YouTube language defaults, and Anki field mappings. AI and translation fields remain supported in config files only.
+- **Settings Window:** A dedicated Settings window is now available via `subminer --settings` or `subminer settings`, organized into Appearance, Behavior, Anki, Input, and Integration sections. Includes click-to-learn keybinding controls, AnkiConnect-backed deck/field/note-type pickers, and live reload for stats keys, logging level, Jimaku, Subsync, YouTube language defaults, and Anki field mappings. AI and translation settings remain config-file only.
 
-- **Auto-Updater:** SubMiner can now check for and apply updates from the system tray or by running `subminer -u`. Checks include checksum verification, configurable notifications, and an opt-in channel for prerelease builds. The `subminer` launcher and Linux rofi theme are also updated automatically.
+- **Auto-Updater:** SubMiner can now check for and apply updates from the system tray or by running `subminer -u`, with checksum verification, configurable update notifications, and an opt-in prerelease channel. The `subminer` launcher and Linux rofi theme update automatically. Set `updates.channel` to `"prerelease"` to receive beta and RC builds.
 
-- **First-Run Setup:** A new optional setup flow installs Bun and the `subminer` command-line launcher on Linux, macOS, and Windows. Windows users get a `subminer.cmd` PATH shim so `subminer` works in any terminal without manually adding `SubMiner.exe` to PATH. First-run setup also includes an Open SubMiner Settings button.
+- **First-Run Setup:** A new optional setup flow installs Bun and the `subminer` command-line launcher on Linux, macOS, and Windows, with an Open SubMiner Settings button on completion. Windows users get a `subminer.cmd` PATH shim so `subminer` works in any terminal without manually adding `SubMiner.exe` to PATH.
 
-- **Launcher:** `subminer --version` / `subminer -v` now prints the installed SubMiner app version.
+- **Launcher:** `subminer --version` / `subminer -v` now prints the installed app version. The new `mpv.profile` config option passes an mpv profile to SubMiner-managed mpv launches. Bundled mpv plugin startup options are now configurable from SubMiner config.
+
+- **Character Portraits:** Character-name subtitle matches can now show optional inline AniList character portraits. Manual AniList title overrides are scoped per media directory so separate season folders keep independent character dictionary selections.
 
 ### Changed
 
-- **Settings Window:** Option rows no longer display raw config paths; live/restart status is shown inline beside each option title. Known-words deck rows are now cards with the deck name on a separate header line so long names remain readable. Playback, shortcut, WebSocket, tracking, Jellyfin, character dictionary, and Discord presence controls have been reorganized.
+- **Subtitle Appearance:** Primary and secondary subtitle appearance now use color controls plus CSS declaration editors, saved as `subtitleStyle.css` and `subtitleStyle.secondary.css`. Sidebar appearance is configured via `subtitleSidebar.css`. The default subtitle font stack is updated to `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP`. Existing configs are migrated automatically.
 
-- **Subtitle Appearance:** Primary and secondary subtitle appearance now use color controls plus CSS declaration editors, saved as `subtitleStyle.css` and `subtitleStyle.secondary.css`. Existing configs are migrated automatically. Sidebar appearance is now configured via `subtitleSidebar.css`; the default subtitle font is updated to `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP`.
+- **Known-Word Colors:** Known-word and N+1 annotation colors moved to `subtitleStyle.knownWordColor` and `subtitleStyle.nPlusOneColor`. Legacy Anki color keys remain accepted with deprecation warnings. N+1 highlighting is preserved for configs that already had it enabled; new configs leave it disabled unless `ankiConnect.nPlusOne.enabled` is set explicitly.
 
-- **Known-Word Colors:** Known-word and N+1 annotation colors moved to `subtitleStyle.knownWordColor` and `subtitleStyle.nPlusOneColor`. Legacy Anki color keys are still accepted with deprecation warnings. Existing configs that had known-word highlighting enabled retain N+1 highlighting; new configs leave N+1 disabled unless `ankiConnect.nPlusOne.enabled` is explicitly set.
+- **Linux Updater:** Tray "Check for Updates" now installs the new AppImage automatically via `electron-updater`, matching the macOS and Windows update flow. System-package-managed AppImages (e.g. AUR `/opt/SubMiner`) and non-AppImage launches fall back to the GitHub-asset flow.
 
-- **Linux Updater:** Tray "Check for Updates" now automatically installs the new AppImage via `electron-updater`, matching the macOS and Windows tray flow. AppImages managed by a system package (e.g. AUR `/opt/SubMiner`) and non-AppImage launches fall back to the GitHub-asset flow.
+- **Subsync:** The subtitle sync dialog now always opens the manual picker; the `subsync.defaultMode` config option has been removed.
 
-- **Subsync:** Always opens the manual subtitle picker. The `subsync.defaultMode` config option has been removed.
-
-- **Jellyfin:** The server presets dropdown in Jellyfin setup is removed; setup now shows a single editable server URL field.
+- **Jellyfin:** The server presets dropdown in Jellyfin setup is replaced by a single editable server URL field.
 
 - **AniSkip:** The key binding setting now uses click-to-learn key capture instead of raw text entry.
 
+- **Character Dictionary:** The in-app AniList title selector now waits for an explicit search rather than triggering automatically. The search box is prefilled from the current filename guess so it can be edited before confirming an override. Results are scoped to generated Japanese name aliases; raw romanized or English aliases no longer appear as separate entries.
+
 - **Setup:** The bundled mpv runtime plugin readiness card is removed from first-run setup; the legacy mpv plugin removal notice still appears when needed.
 
 - **Defaults:** Jellyfin remote-session startup warmup and character-name subtitle highlighting now default to off.
 
+- **Runtime:** The bundled Electron runtime is updated from 39.8.6 to 42.2.0.
+
 ### Fixed
 
-- **macOS Overlay:** Significantly improved overlay focus and stability: the overlay now hides when mpv loses focus or is minimized, stays stable through transient window-tracking misses, remains correctly layered during stats mouse passthrough, and opens over fullscreen mpv without switching Spaces. Passthrough is fixed so mpv controls stay clickable before hovering a subtitle bar. Background tracking overhead is reduced while mpv is stably focused.
+- **macOS Overlay:** Significantly improved overlay focus and stability: the overlay hides when mpv loses focus, is minimized, or is no longer the foreground target; stays stable through transient window-tracking misses; remains correctly layered during stats mouse passthrough; opens over fullscreen mpv without switching Spaces; and stays stable when mpv remains frontmost but window geometry temporarily disappears from macOS APIs. Passthrough is fixed so mpv controls stay clickable before hovering a subtitle bar. The overlay also stays stable when clicking from the overlay back into mpv. Background tracking overhead is reduced while mpv is stably focused.
+
+- **Linux/Hyprland Overlay:** Overlay placement refreshes after leaving mpv fullscreen so the visible overlay stays aligned to the player. The visible overlay remains stacked above mpv after mpv regains focus from clicks, and is suspended while the in-player stats window is open.
+
+- **Jellyfin Playback:** Resolved a wide range of Jellyfin discovery and playback issues: the active item is no longer reloaded during startup, paused mpv is no longer misreported as playing, startup unpause no longer repeats after a manual pause or `y-t` toggle, duplicate ready signals no longer re-show the overlay, and long-lived sidebar ffmpeg extractors no longer run against stream URLs. Discovery now correctly handles delayed Japanese subtitle selection and prevents later-loading foreign tracks from stealing the active Japanese track. Discovery resume correctly handles `StartPositionTicks: 0` for items with saved progress.
+
+- **Jellyfin Subtitles:** Improved subtitle timing by preferring default embedded streams over external sidecars, stripping Jellyfin's server-selected stream from playback URLs, suppressing mpv auto-selection while SubMiner stages managed tracks, and automatically correcting clear Japanese-vs-English cue timeline offsets. Per-stream subtitle delay shifts are restored on load. Track selection now tolerates transient `track-list` read failures and numeric string track IDs on Linux.
+
+- **Jellyfin Overlay:** The visible subtitle overlay now shows automatically during Jellyfin playback so `subtitleStyle` appearance applies. The bundled mpv plugin is injected when SubMiner auto-launches mpv for Jellyfin so mpv-side keybindings work without overlay focus. The `y-t` overlay toggle is reliable and remains sticky across stream redirects. Passive Linux/Hyprland overlay shows no longer steal keyboard focus from mpv.
+
+- **Jellyfin Remote Progress:** Fixed progress sync for mpv/SubMiner seek jumps, stopped sessions, startup path changes, and Linux websocket reconnect windows. Play and Resume are now distinct: Play starts from the beginning while Resume starts at the saved position. Final progress reports use SubMiner's last known position when mpv resets during stop.
+
+- **Jellyfin Identity:** Cast device identity is now derived from the OS hostname. Multiple SubMiner installs no longer share the same remote-session identity, and SubMiner always reports itself as the client regardless of legacy configurable identity fields.
+
+- **Jellyfin Tray:** The discovery tray checkbox stays in sync on Linux after tray, CLI, or startup remote-session changes. Stale discovery sessions restart automatically when the server no longer lists the SubMiner cast target. Library discovery works correctly when the app log level is set above info.
+
+- **Jellyfin Setup:** Fixed the Jellyfin setup login flow on Windows: login now uses an IPC bridge with immediate progress feedback, and unreachable servers time out with an inline error instead of hanging.
 
 - **Subtitle Sync Modal:** Fixed a macOS issue where opening the subtitle sync modal would flash and disappear on the first attempt, or leave stale state after syncing.
 
@@ -45,43 +61,41 @@
 
 - **AniList Progress:** Progress threshold checks now use fresh playback position data so updates fire correctly when playback reaches or skips past the watched threshold. Season-specific results are preferred for multi-season files, and a clear message is shown when the matched season is not in Planning or Watching status.
 
-- **Character Dictionary:** Cached media matches are reused when loading a title with an existing snapshot, avoiding redundant AniList search requests on repeat visits.
+- **Anki:** Sentence-audio padding is now opt-in by default. When padding is configured, animated AVIF freeze-frame duration is correctly aligned to the word audio length without double-counting sentence padding. Multi-line sentence mining stays aligned when repeated subtitle text appears in the selected history range. Manual clipboard card updates from YouTube playback now use mpv's resolved stream URLs for generated audio and images.
 
-- **Updater — Linux:** The tray app now uses GitHub release metadata for update checks instead of the native Electron updater, preventing crashes. `subminer -u` performs updates independently of any running tray instance and correctly reports "up to date" without downloading assets when no newer release exists. Update check traffic is routed through `/usr/bin/curl` to avoid Electron network-service crashes during video startup.
+- **YouTube:** Primary subtitles are now downloaded to temporary local files so the primary bar and sidebar read the same source, with cleanup on reload and quit. False subtitle load failure notifications are suppressed after SubMiner confirms the selected track loaded. Launcher-managed playback commands create the tray icon even when attaching to an already-running process, and app-owned YouTube playback no longer lets the mpv plugin start a second SubMiner instance.
 
-- **Updater — macOS:** Update dialogs now reliably come to the front when launched from `subminer --update`. Builds that cannot install native updates show a manual-install message instead of an inapplicable restart prompt. Signed macOS builds remain on the native `electron-updater`/Squirrel path; supplemental GitHub release lookups are routed through `/usr/bin/curl`, eliminating the last Electron-networking path from background update checks.
+- **Character Dictionary:** Cached media matches are reused when loading a title with an existing snapshot, avoiding redundant AniList search requests on repeat visits. The visible subtitle overlay is now suppressed as soon as the character dictionary modal opens, including while AniList lookup is loading or returns no results.
 
-- **Updater — Windows:** Automatic updates keep the native `electron-updater`/NSIS install path enabled while routing updater HTTP through main-process fetch, avoiding the delayed app exit seen shortly after launch.
+- **Updater:** Update checks are more stable across platforms: Linux uses GitHub release metadata instead of the native Electron updater; `subminer -u` can update independently of the tray app; macOS update dialogs reliably appear in the foreground; builds that cannot apply native updates show a manual-install message instead of a restart prompt; Windows retains the native NSIS update path while routing updater HTTP through the main process; and macOS updater metadata mismatches from conflicting ZIP filenames are resolved.
 
-- **Setup — macOS:** First-run setup now recognizes existing `subminer` launcher installs in Homebrew or user PATH directories, and manual setup avoids writing into Homebrew-owned paths. `subminer app --setup` opens the setup flow even when SubMiner is already running in the background. The standalone setup app quits after completing first-run setup, and `subminer settings` exits cleanly when the window is closed — both return control to the terminal without requiring Ctrl+C.
+- **Setup - macOS:** First-run setup now recognizes existing `subminer` installs in Homebrew or user PATH directories, and manual setup avoids writing into Homebrew-owned paths. `subminer app --setup` opens the setup flow even when SubMiner is already running in the background. The standalone setup app quits after completing first-run setup, and `subminer settings` exits cleanly when the window is closed.
 
-- **Tray App:** Fixed several lifecycle issues with tray-launched Yomitan settings: the tray stays running when settings are closed; settings loading no longer blocks other tray actions; the settings window uses a close-only menu to prevent accidentally quitting the tray app; an in-page close button is provided on Hyprland where native window controls are unavailable; the embedded popup preview is disabled to prevent renderer hangs during sidebar navigation; extension refreshes at startup are serialized to prevent race conditions; and the session help modal can now close correctly without mpv running.
+- **Tray App:** Fixed several lifecycle issues with tray-launched Yomitan settings: the tray stays running when settings are closed; settings loading no longer blocks other tray actions; a close-only menu prevents accidentally quitting the tray app; an in-page close button is available on Hyprland where native window controls are unavailable; the embedded popup preview is disabled to prevent renderer hangs during sidebar navigation; extension refreshes at startup are serialized to prevent race conditions; and the session help modal can close correctly without mpv running. On Windows, the tray "Open SubMiner Setup" action now correctly opens the setup window after first-run setup is complete.
 
-- **Launcher — Linux:** First-run launcher installs are now built with a valid Bun shebang, fixing installs that previously failed silently.
+- **Launcher:** Launcher-opened videos reuse an already-running background SubMiner instance and correctly reapply preferred subtitles on warm launches. Videos stay paused when attaching to a running background app until subtitle priming and tokenization readiness complete. Launcher-owned tray apps close after playback ends. `subminer settings` on macOS no longer emits Electron menu diagnostics. Linux first-run launcher installs now build with a valid Bun shebang. On Windows, managed mpv launches from a background SubMiner instance correctly retarget the new mpv socket, bind to the player window, and receive startup overlay options.
 
-- **Launcher:** Launcher-opened videos now reuse an already-running background SubMiner instance and correctly reapply preferred subtitles on warm launches. Videos stay paused when attaching to a running background app until subtitle priming and tokenization readiness complete. Launcher-owned tray apps close after playback ends.
-
-- **Playback:** The first subtitle is primed before autoplay resumes so the overlay can render text before video playback begins.
+- **Playback:** The first subtitle is primed before autoplay resumes so the overlay renders text before video playback begins. Launcher-owned videos quit SubMiner when playback ends while background and tray sessions stay alive.
 
 - **Subtitle Frequency:** Frequency highlighting is preserved for determiner-led noun compounds like `その場` while standalone determiners are still filtered.
 
-- **macOS Shortcuts:** Native mpv menu shortcuts are disabled during managed macOS playback so configured SubMiner shortcuts work while mpv has focus. Session shortcuts including `stats.markWatchedKey` are now correctly wired through mpv.
+- **Shortcuts:** Native mpv menu shortcuts are disabled during managed macOS playback so configured SubMiner shortcuts also work while mpv has focus. Session shortcuts including `stats.markWatchedKey` are correctly wired through mpv. The visible overlay receives focus when entering multi-line copy/mine selection so number keys work on macOS and Windows.
 
-- **Overlay Restart:** The visible overlay and subtitle stream now stay alive after restarting SubMiner from the `y-r` shortcut, with correct bounds reapplication on Linux and user-paused playback preserved through readiness gates.
+- **Overlay Restart:** The visible overlay and subtitle stream stay alive after restarting SubMiner from the `y-r` shortcut, with correct bounds reapplication on Linux and user-paused playback preserved through readiness gates.
 
-- **WebSocket:** The subtitle WebSocket is now plain-text only; annotation spans and token metadata are sent exclusively on the annotation WebSocket.
+- **Stats:** In-player stats layering is fixed so delete confirmations, overlay modals, and update-check dialogs appear above the stats window. Jellyfin playback stats are grouped under item metadata instead of stream URLs, so watched episodes merge with matching local library titles and display clean names.
 
-- **Jellyfin:** Fixed the setup popup login path on Windows using an IPC bridge, with immediate login progress feedback and a timeout for unreachable server attempts.
+- **Sidebar:** Yomitan lookup popups opened from the subtitle sidebar now correctly pause playback when popup auto-pause is enabled.
+
+- **Discord Rich Presence:** Presence no longer falls back to Jellyfin stream URLs; Jellyfin playback titles are primed before loading tokenized streams so presence shows the show/episode title.
+
+- **WebSocket:** The regular subtitle WebSocket now sends plain text only; annotation spans and token metadata are sent exclusively on the annotation WebSocket.
 
 - **Windows:** Startup failures now show a native error dialog and write fatal details to the app log instead of exiting silently.
 
 - **Yomitan:** Fixed Yomitan popups not opening when overlay startup races the Yomitan extension load.
 
-- **Settings:** Settings window search now searches across all categories, narrows correctly on multi-word terms, and hides settings with dedicated editors. Live saves for subtitle CSS declarations apply immediately to open overlays. Legacy subtitle appearance options and hover token colors are automatically migrated into `subtitleStyle.css`.
-
-- **Config:** User config files are preserved during legacy compatibility handling. The note-fields note-type picker now defaults to the configured Anki deck's note type, falling back to `Kiku`, then `Lapis`, then blank for manual selection.
-
-- **Build — Linux:** Fixed one-shot `make clean build install` flows so the install step correctly picks up the AppImage produced earlier in the same make invocation.
+- **Settings:** Search now works across all categories, narrows correctly on multi-word terms, and hides settings with dedicated editors. Live saves for subtitle CSS declarations apply immediately to open overlays. Legacy subtitle appearance options and hover token colors are automatically migrated into `subtitleStyle.css`. The note-fields note type picker defaults to the configured Anki deck's note type, then `Kiku`, then `Lapis`, leaving it blank for manual selection otherwise. User config files are preserved during legacy config compatibility handling. The generated example config uses the same CSS declaration paths written by the Settings window.
 
 ### Docs
 

scripts/build-changelog.test.ts

@@ -374,6 +374,74 @@ test('writeChangelogArtifacts renders breaking changes section above type sectio
   }
 });
 
+test('writeChangelogArtifacts prompts Claude to summarize the final stable outcome instead of prerelease churn', async () => {
+  const { writeChangelogArtifacts } = await loadModule();
+  const workspace = createWorkspace('stable-outcome-prompt');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(projectRoot, { recursive: true });
+  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: config',
+      '',
+      '- Added a dedicated Config window with launcher entry points.',
+    ].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '002.md'),
+    [
+      'type: changed',
+      'area: config',
+      'breaking: true',
+      '',
+      '- Renamed the Config window to Settings window and changed the launcher entry point to `subminer settings`.',
+    ].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '003.md'),
+    [
+      'type: fixed',
+      'area: config',
+      '',
+      '- Fixed Settings window search and live subtitle CSS saves.',
+    ].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const stub = defaultStubClaude();
+    writeChangelogArtifacts({
+      cwd: projectRoot,
+      version: '0.12.0',
+      date: '2026-05-24',
+      deps: { runClaude: stub.runClaude },
+    });
+
+    const prompts = stub.calls.map((call) => call.input);
+    assert.equal(prompts.length, 2, 'expected changelog and release-notes prompts');
+    for (const prompt of prompts) {
+      assert.match(prompt, /Treat the fragment list as one cumulative release outcome/);
+      assert.match(
+        prompt,
+        /only if the final release requires action from users upgrading from the previous stable release/,
+      );
+      assert.match(prompt, /Config window.*Settings window/s);
+      assert.match(
+        prompt,
+        /Multiple fixes within the same prerelease cycle should collapse into one current-state bullet/,
+      );
+    }
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
 test('verifyChangelogFragments rejects invalid metadata', async () => {
   const { verifyChangelogFragments } = await loadModule();
   const workspace = createWorkspace('lint-invalid');
@@ -575,6 +643,74 @@ test('writePrereleaseNotesForVersion reuses existing prerelease notes when addin
   }
 });
 
+test('writePrereleaseNotesForVersion prompts Claude to revise stale prerelease bullets instead of appending fix churn', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-net-outcome-prompt');
+  const projectRoot = path.join(workspace, 'SubMiner');
+  const existingNotes = [
+    '> This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.',
+    '',
+    '## Highlights',
+    '### Added',
+    '- Config Window: Previous beta entry.',
+    '',
+    '## Installation',
+    '',
+    'See the README and docs/installation guide for full setup steps.',
+    '',
+    '## Assets',
+    '',
+    '- Linux: `SubMiner.AppImage`',
+    '',
+  ].join('\n');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, 'release'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.12.0-beta.2' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(path.join(projectRoot, 'release', 'prerelease-notes.md'), existingNotes, 'utf8');
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    [
+      'type: changed',
+      'area: config',
+      'breaking: true',
+      '',
+      '- Renamed the Config window to Settings window.',
+    ].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '002.md'),
+    ['type: fixed', 'area: config', '', '- Fixed Settings window search.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const stub = recordingRunClaude(() => '### Added\n- Settings Window: Current beta state.');
+    writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.12.0-beta.2',
+      deps: { runClaude: stub.runClaude },
+    });
+
+    assert.equal(stub.calls.length, 1, 'prerelease should issue exactly one Claude call');
+    const prompt = stub.calls[0]!.input;
+    assert.match(prompt, /EXISTING PRERELEASE NOTES/);
+    assert.match(prompt, /Existing prerelease notes are a baseline, not an immutable changelog/);
+    assert.match(prompt, /replace stale beta or RC wording/);
+    assert.match(
+      prompt,
+      /Multiple fixes within the same prerelease cycle should collapse into one current-state bullet/,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
 test('writePrereleaseNotesForVersion supports rc prereleases', async () => {
   const { writePrereleaseNotesForVersion } = await loadModule();
   const workspace = createWorkspace('prerelease-rc-notes');

scripts/build-changelog.ts

@@ -235,6 +235,13 @@ const POLISH_PROMPT_INSTRUCTIONS = `You are formatting a software release change
 
 You will receive a list of FRAGMENT entries below. Each fragment has metadata (type, area, breaking) and one or more bullet points written by the engineer who shipped that change. Your job is to merge, dedupe, and rewrite these fragments into a polished, user-facing release body.
 
+## Release Outcome Rules
+
+- Treat the fragment list as one cumulative release outcome, not a chronological log of beta/RC churn.
+- Put a fragment in ### Breaking Changes only if the final release requires action from users upgrading from the previous stable release. A breaking: true marker is a warning to preserve and evaluate the substance, not an automatic section choice.
+- If a breaking or fixed fragment only changes behavior introduced by another pending fragment in the same release cycle, merge it into the final Added or Changed bullet. Example: if fragments first add a Config window and later rename or fix it as a Settings window, output one Settings Window bullet under Added, not separate Config window, Breaking Changes, or Fixed bullets.
+- Multiple fixes within the same prerelease cycle should collapse into one current-state bullet that describes the final behavior.
+
 ## Output Rules
 
 1. Output Markdown ONLY. No preamble, no commentary, no closing remarks. Start directly with the first section heading.
@@ -258,7 +265,7 @@ You will receive a list of FRAGMENT entries below. Each fragment has metadata (t
    - Be written in user-facing language. Drop implementation jargon, internal class names, file paths, and PR numbers.
    - Be merged with related bullets when possible. If five fragments all touch Windows overlay z-order/focus/restore, write one or two bullets that summarize the overall improvement instead of five.
    - Drop bullets that only describe PR housekeeping, CodeRabbit follow-ups, or test-only changes that don't affect users.
-   - Preserve the substance of every breaking change in ### Breaking Changes. Do not soften or omit them.
+   - Preserve the substance of breaking changes that remain breaking after applying the Release Outcome Rules. Do not soften or omit them.
 5. Do not invent features. Every bullet must be grounded in the input fragments.
 6. Do not include the version heading (## v...) — that wrapper is added by the caller.
 
@@ -371,7 +378,7 @@ function polishFragmentsWithClaude(
     ? [
         '## Existing Prerelease Notes',
         '',
-        'The input includes EXISTING PRERELEASE NOTES before the fragment list. Reuse those highlight bullets as the baseline, preserve their meaning and wording where possible, then merge in only new or changed fragment material. Deduplicate instead of restating existing bullets. Output only the final highlights body using the section headings above; do not include the prerelease disclaimer, Installation, or Assets sections.',
+        'The input includes EXISTING PRERELEASE NOTES before the fragment list. Existing prerelease notes are a baseline, not an immutable changelog. Reuse reviewed highlight bullets when they still describe the current outcome, but replace stale beta or RC wording when new fragments supersede it. Merge in only new or changed fragment material, and deduplicate instead of restating existing bullets. Output only the final highlights body using the section headings above; do not include the prerelease disclaimer, Installation, or Assets sections.',
         '',
       ].join('\n')
     : '';

scripts/test-plugin-binary-windows.lua

@@ -68,6 +68,31 @@ local function create_binary_module(config)
 	return binary
 end
 
+do
+	local appimage_path = "/home/tester/.local/bin/SubMiner.AppImage"
+	local mounted_binary_path = "/tmp/.mount_SubMiner/SubMiner"
+	local resolved = with_env({
+		APPIMAGE = appimage_path,
+	}, function()
+		local binary = create_binary_module({
+			is_windows = false,
+			binary_path = mounted_binary_path,
+			entries = {
+				[appimage_path] = "file",
+				[mounted_binary_path] = "file",
+			},
+		})
+
+		return binary.find_binary()
+	end)
+
+	assert_equal(
+		resolved,
+		appimage_path,
+		"linux resolver should prefer APPIMAGE over the mounted AppImage inner binary"
+	)
+end
+
 do
 	local binary = create_binary_module({
 		is_windows = true,

scripts/test-plugin-process-start-retries.lua

@@ -83,10 +83,16 @@ local process = process_module.create({
 			return true
 		end,
 	},
-	environment = {
-		detect_backend = function()
-			return "x11"
-		end,
+		environment = {
+			detect_backend = function()
+				return "x11"
+			end,
+			is_linux = function()
+				return false
+			end,
+			is_subminer_app_running_async = function(callback)
+				callback(false)
+			end,
 	},
 	options_helper = {
 		coerce_bool = function(value, default_value)
@@ -125,4 +131,79 @@ for _, timeout_seconds in ipairs(recorded.timeouts) do
 end
 assert_true(retry_timeout_seen, "expected shorter bounded retry timeout")
 
+do
+	local visibility_state = {
+		binary_path = "/tmp/subminer",
+		overlay_running = true,
+		texthooker_running = false,
+		visible_overlay_requested = false,
+	}
+	local visibility_calls = {}
+	local visibility_mp = {}
+
+	function visibility_mp.command_native_async(command, callback)
+		visibility_calls[#visibility_calls + 1] = command
+		if callback then
+			callback(false, { status = 1, stdout = "", stderr = "failed" }, "failed")
+		end
+	end
+
+	local visibility_process = process_module.create({
+		mp = visibility_mp,
+		opts = {
+			backend = "x11",
+			socket_path = "/tmp/subminer.sock",
+			log_level = "debug",
+			texthooker_enabled = true,
+			texthooker_port = 5174,
+			auto_start_visible_overlay = false,
+		},
+		state = visibility_state,
+		binary = {
+			ensure_binary_available = function()
+				return true
+			end,
+		},
+		environment = {
+			detect_backend = function()
+				return "x11"
+			end,
+			is_linux = function()
+				return false
+			end,
+			is_subminer_app_running_async = function(callback)
+				callback(true)
+			end,
+		},
+		options_helper = {
+			coerce_bool = function(value, default_value)
+				if value == true or value == "yes" or value == "true" then
+					return true
+				end
+				if value == false or value == "no" or value == "false" then
+					return false
+				end
+				return default_value
+			end,
+		},
+		log = {
+			subminer_log = function(_level, _scope, line)
+				recorded.logs[#recorded.logs + 1] = line
+			end,
+			show_osd = function(_) end,
+			normalize_log_level = function(value)
+				return value or "info"
+			end,
+		},
+	})
+
+	visibility_process.run_control_command_async("show-visible-overlay")
+
+	assert_true(#visibility_calls == 1, "expected visible overlay command to run")
+	assert_true(
+		visibility_state.visible_overlay_requested == false,
+		"failed visible-overlay command should not update requested visibility state"
+	)
+end
+
 print("plugin process retry regression tests: OK")

scripts/test-plugin-session-bindings.lua

@@ -23,6 +23,7 @@ local recorded = {
 	async_calls = {},
 	mpv_commands = {},
 	osd = {},
+	overlay_toggles = 0,
 }
 
 local mp = {}
@@ -68,6 +69,14 @@ local ctx = {
 			return {
 				numericSelectionTimeoutMs = 3000,
 				bindings = {
+					{
+						key = {
+							code = "KeyO",
+							modifiers = { "alt", "shift" },
+						},
+						actionType = "session-action",
+						actionId = "toggleVisibleOverlay",
+					},
 					{
 						key = {
 							code = "KeyS",
@@ -253,6 +262,9 @@ local ctx = {
 		run_binary_command_async = function(args)
 			recorded.async_calls[#recorded.async_calls + 1] = args
 		end,
+		toggle_overlay = function()
+			recorded.overlay_toggles = recorded.overlay_toggles + 1
+		end,
 	},
 	environment = {
 		resolve_session_bindings_artifact_path = function()
@@ -310,7 +322,9 @@ end
 
 local expected_cli_bindings = {
 	{ keys = "Shift+]", flag = "--shift-sub-delay-next-line" },
+	{ keys = "}", flag = "--shift-sub-delay-next-line" },
 	{ keys = "Shift+[", flag = "--shift-sub-delay-prev-line" },
+	{ keys = "{", flag = "--shift-sub-delay-prev-line" },
 	{ keys = "Ctrl+Alt+c", flag = "--open-youtube-picker" },
 	{ keys = "Ctrl+Alt+p", flag = "--open-playlist-browser" },
 	{ keys = "Ctrl+H", flag = "--replay-current-subtitle" },
@@ -318,6 +332,11 @@ local expected_cli_bindings = {
 	{ keys = "w", flag = "--mark-watched" },
 }
 
+local visible_overlay_toggle = find_binding("Alt+O")
+assert_true(visible_overlay_toggle ~= nil, "visible overlay session binding should register")
+visible_overlay_toggle.fn()
+assert_true(recorded.overlay_toggles == 1, "visible overlay session binding should use plugin toggle")
+
 for _, expected in ipairs(expected_cli_bindings) do
 	local binding = find_binding(expected.keys)
 	assert_true(binding ~= nil, "default session action should register " .. expected.keys)

scripts/test-plugin-start-gate.lua

@@ -201,7 +201,7 @@ local function run_plugin_scenario(config)
 		end
 		function mp.set_osd_ass(...) end
 		function mp.get_time()
-			return 0
+			return config.now or 0
 		end
 		function mp.commandv(...) end
 		function mp.set_property_native(name, value)
@@ -623,16 +623,18 @@ local binary_path = "/tmp/subminer-binary"
 local appimage_path = "/tmp/SubMiner.AppImage"
 
 do
-	local recorded, err = run_plugin_scenario({
+	local scenario = {
 		process_list = "",
 		option_overrides = {
 			binary_path = binary_path,
 			auto_start = "no",
 		},
+		now = 20,
 		files = {
 			[binary_path] = true,
 		},
-	})
+	}
+	local recorded, err = run_plugin_scenario(scenario)
 	assert_true(recorded ~= nil, "plugin failed to load for cold-start scenario: " .. tostring(err))
 	assert_true(recorded.script_messages["subminer-start"] ~= nil, "subminer-start script message not registered")
 	recorded.script_messages["subminer-start"]("texthooker=no")
@@ -643,6 +645,36 @@ do
 	)
 end
 
+do
+	local scenario = {
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		path = "/media/aborted-app-managed.m3u8",
+		media_title = "Aborted App Managed",
+		files = {
+			[binary_path] = true,
+		},
+	}
+	local recorded, err = run_plugin_scenario(scenario)
+	assert_true(recorded ~= nil, "plugin failed to load for aborted app-managed scenario: " .. tostring(err))
+	recorded.script_messages["subminer-managed-subtitles-loading"]()
+	fire_event(recorded, "end-file", { reason = "error" })
+	scenario.path = "/media/next-normal.mkv"
+	scenario.media_title = "Next Normal"
+	fire_event(recorded, "file-loaded")
+	assert_true(
+		count_start_calls(recorded.async_calls) == 1,
+		"aborted app-managed playback should not leak pending state into the next item"
+	)
+end
+
 do
 	local scenario = {
 		process_list = "",
@@ -683,6 +715,236 @@ do
 	)
 end
 
+do
+	local scenario = {
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		path = "/media/jellyfin-app-toggle-initial.m3u8",
+		media_title = "Jellyfin App Toggle",
+		paused = true,
+		files = {
+			[binary_path] = true,
+		},
+	}
+	local recorded, err = run_plugin_scenario(scenario)
+	assert_true(recorded ~= nil, "plugin failed to load for app-side hide Jellyfin redirect: " .. tostring(err))
+	fire_event(recorded, "start-file")
+	fire_event(recorded, "file-loaded")
+	recorded.script_messages["subminer-visible-overlay-hidden"]()
+	fire_event(recorded, "end-file", { reason = "redirect" })
+	scenario.path = "/media/jellyfin-app-toggle-final.m3u8"
+	scenario.media_title = ""
+	fire_event(recorded, "start-file")
+	fire_event(recorded, "file-loaded")
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"app-side hide sync should suppress path-changing Jellyfin redirect visible overlay reassertion"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "pause", false) == 0,
+		"app-side hide sync followed by Jellyfin redirect should keep paused playback paused"
+	)
+end
+
+do
+	local scenario = {
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		path = "/media/jellyfin-duplicate-toggle.m3u8",
+		media_title = "Jellyfin Duplicate Toggle",
+		paused = true,
+		now = 10,
+		files = {
+			[binary_path] = true,
+		},
+	}
+	local recorded, err = run_plugin_scenario(scenario)
+	assert_true(recorded ~= nil, "plugin failed to load for duplicate visible overlay toggle: " .. tostring(err))
+	fire_event(recorded, "file-loaded")
+	recorded.script_messages["subminer-toggle"]()
+	recorded.script_messages["subminer-toggle"]()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--hide-visible-overlay") == 1,
+		"duplicate same-tick visible overlay toggles should hide once"
+	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"duplicate same-tick visible overlay toggles should not immediately show the overlay again"
+	)
+	scenario.now = 10.5
+	recorded.script_messages["subminer-toggle"]()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 1,
+		"later visible overlay toggle should still show after duplicate suppression window"
+	)
+end
+
+do
+	local scenario = {
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "no",
+		},
+		now = 20,
+		files = {
+			[binary_path] = true,
+		},
+	}
+	local recorded, err = run_plugin_scenario(scenario)
+	assert_true(recorded ~= nil, "plugin failed to load for visible overlay state sync scenario: " .. tostring(err))
+	assert_true(
+		recorded.script_messages["subminer-visible-overlay-hidden"] ~= nil,
+		"hidden visibility sync message should be registered"
+	)
+	assert_true(
+		recorded.script_messages["subminer-visible-overlay-shown"] ~= nil,
+		"shown visibility sync message should be registered"
+	)
+	recorded.script_messages["subminer-visible-overlay-hidden"]()
+	recorded.script_messages["subminer-toggle"]()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 1,
+		"toggle after app-side hide should explicitly show SubMiner overlay through plugin state"
+	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--toggle-visible-overlay") == 0,
+		"toggle after app-side hide should avoid app-side visible overlay toggle"
+	)
+	scenario.now = 20.5
+	recorded.script_messages["subminer-visible-overlay-shown"]()
+	recorded.script_messages["subminer-toggle"]()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--hide-visible-overlay") == 1,
+		"toggle after app-side show should explicitly hide SubMiner overlay through plugin state"
+	)
+end
+
+do
+	local recorded, err = run_plugin_scenario({
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		path = "/media/jellyfin-stream.m3u8",
+		media_title = "Jellyfin Episode",
+		paused = true,
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for y-t hide visible overlay scenario: " .. tostring(err))
+	fire_event(recorded, "file-loaded")
+	local toggle_binding = nil
+	for _, candidate in ipairs(recorded.key_bindings) do
+		if candidate.name == "subminer-toggle" then
+			toggle_binding = candidate
+			break
+		end
+	end
+	assert_true(toggle_binding ~= nil, "y-t toggle binding should be registered")
+	toggle_binding.fn()
+	fire_event(recorded, "file-loaded")
+	recorded.script_messages["subminer-autoplay-ready"]()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--hide-visible-overlay") == 1,
+		"y-t should hide the known visible overlay explicitly instead of app-side toggle"
+	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--toggle-visible-overlay") == 0,
+		"y-t should avoid app-side toggle when plugin knows the overlay is visible"
+	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"manual y-t hide should suppress duplicate auto-start and ready-time visible overlay reassertion"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "pause", false) == 0,
+		"manual y-t hide should not resume paused Jellyfin playback"
+	)
+end
+
+do
+	local recorded, err = run_plugin_scenario({
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "no",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		media_title = "Jellyfin Managed Playback",
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for managed Jellyfin subtitle preload scenario: " .. tostring(err))
+	assert_true(
+		recorded.script_messages["subminer-managed-subtitles-loading"] ~= nil,
+		"managed subtitle preload script message should be registered"
+	)
+	recorded.script_messages["subminer-managed-subtitles-loading"]()
+	fire_event(recorded, "start-file")
+	fire_event(recorded, "file-loaded")
+	fire_event(recorded, "file-loaded")
+	assert_true(
+		not has_property_set(recorded.property_sets, "sid", "auto"),
+		"managed Jellyfin preload should not rearm primary subtitle auto-selection before app-selected subtitles load"
+	)
+	assert_true(
+		not has_property_set(recorded.property_sets, "secondary-sid", "auto"),
+		"managed Jellyfin preload should not rearm secondary subtitle auto-selection before app-selected subtitles load"
+	)
+	assert_true(
+		not has_property_set(recorded.property_sets, "sub-auto", "fuzzy"),
+		"managed Jellyfin preload should not re-enable subtitle autoloading before app-selected subtitles load"
+	)
+	assert_true(
+		count_start_calls(recorded.async_calls) == 0,
+		"managed Jellyfin preload should let the app show the overlay after subtitle preload instead of plugin auto-start"
+	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"managed Jellyfin preload should not reassert the visible overlay during duplicate file-loaded events"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "pause", true) == 0,
+		"managed Jellyfin preload should not arm the plugin pause gate before app-selected subtitles load"
+	)
+	fire_event(recorded, "end-file", { reason = "stop" })
+	fire_event(recorded, "start-file")
+	fire_event(recorded, "file-loaded")
+	assert_true(
+		count_property_set(recorded.property_sets, "sid", "auto") == 1,
+		"managed subtitle preload suppression should only apply to one playback lifecycle"
+	)
+	assert_true(
+		count_start_calls(recorded.async_calls) == 1,
+		"plugin auto-start should resume after the managed Jellyfin lifecycle ends"
+	)
+end
+
 do
 	local recorded, err = run_plugin_scenario({
 		process_list = "",
@@ -932,8 +1194,8 @@ do
 	recorded.script_messages["subminer-restart"]()
 	recorded.script_messages["subminer-autoplay-ready"]()
 	assert_true(
-		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 2,
-		"manual restart should re-assert visible overlay after launch and readiness even when auto-start visibility is disabled"
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 1,
+		"manual restart should avoid a second visible overlay restore after launch already requested visibility"
 	)
 end
 
@@ -1328,8 +1590,8 @@ do
 		"auto-start with visible overlay enabled should not include --hide-visible-overlay on --start"
 	)
 	assert_true(
-		find_control_call(recorded.async_calls, "--show-visible-overlay") ~= nil,
-		"auto-start with visible overlay enabled should issue a separate --show-visible-overlay command"
+		find_control_call(recorded.async_calls, "--show-visible-overlay") == nil,
+		"auto-start with visible overlay enabled should rely on the --start visibility flag instead of a separate --show-visible-overlay command"
 	)
 	assert_true(
 		not has_property_set(recorded.property_sets, "pause", true),
@@ -1360,8 +1622,8 @@ do
 		"duplicate file-loaded events should not issue duplicate --start commands while overlay is already running"
 	)
 	assert_true(
-		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 2,
-		"duplicate auto-start should re-assert visible overlay state when overlay is already running"
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"duplicate auto-start should not re-assert visible overlay state when it is already requested"
 	)
 	assert_true(
 		count_osd_message(recorded.osd, "SubMiner: Already running") == 0,
@@ -1396,8 +1658,8 @@ do
 		"duplicate pause-until-ready auto-start should not issue duplicate --start commands while overlay is already running"
 	)
 	assert_true(
-		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 4,
-		"duplicate pause-until-ready auto-start should re-assert visible overlay on initial start, ready, and later file load"
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"duplicate pause-until-ready auto-start should not re-assert visible overlay after the start command already requested it"
 	)
 	assert_true(
 		count_osd_message(recorded.osd, "SubMiner: Loading subtitle tokenization...") == 1,
@@ -1458,8 +1720,8 @@ do
 		"autoplay-ready should show loaded OSD message"
 	)
 	assert_true(
-		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 2,
-		"autoplay-ready should re-assert visible overlay state"
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"autoplay-ready should not re-assert visible overlay state after the start command already requested it"
 	)
 	assert_true(
 		#recorded.periodic_timers == 1,
@@ -1471,6 +1733,33 @@ do
 	)
 end
 
+do
+	local recorded, err = run_plugin_scenario({
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		media_title = "Random Movie",
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for duplicate autoplay-ready scenario: " .. tostring(err))
+	fire_event(recorded, "file-loaded")
+	assert_true(recorded.script_messages["subminer-autoplay-ready"] ~= nil, "subminer-autoplay-ready script message not registered")
+	recorded.script_messages["subminer-autoplay-ready"]()
+	recorded.script_messages["subminer-autoplay-ready"]()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"duplicate autoplay-ready signals should not spawn visible overlay restore commands when start already requested visibility"
+	)
+end
+
 do
 	local recorded, err = run_plugin_scenario({
 		process_list = "",
@@ -1523,14 +1812,22 @@ do
 	assert_true(recorded.script_messages["subminer-toggle"] ~= nil, "subminer-toggle script message not registered")
 	recorded.script_messages["subminer-toggle"]()
 	assert_true(
-		count_control_calls(recorded.async_calls, "--toggle-visible-overlay") == 1,
-		"manual toggle should use explicit visible-overlay toggle command"
+		count_control_calls(recorded.async_calls, "--hide-visible-overlay") == 1,
+		"manual toggle-off should hide a known visible overlay explicitly"
+	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--toggle-visible-overlay") == 0,
+		"manual toggle-off should avoid app-side toggle when plugin knows the overlay is visible"
 	)
 	recorded.script_messages["subminer-autoplay-ready"]()
 	assert_true(
-		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 1,
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
 		"manual toggle-off before readiness should suppress ready-time visible overlay restore"
 	)
+	assert_true(
+		count_property_set(recorded.property_sets, "pause", false) == 0,
+		"manual toggle-off before readiness should not resume playback when readiness arrives"
+	)
 end
 
 do
@@ -1559,11 +1856,127 @@ do
 	recorded.script_messages["subminer-autoplay-ready"]()
 	recorded.script_messages["subminer-autoplay-ready"]()
 	assert_true(
-		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 1,
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
 		"manual toggle-off should suppress repeated ready-time visible overlay restores for the same session"
 	)
 end
 
+do
+	local recorded, err = run_plugin_scenario({
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		path = "/media/jellyfin-stream.m3u8",
+		media_title = "Jellyfin Episode",
+		paused = true,
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for manual hide duplicate auto-start scenario: " .. tostring(err))
+	fire_event(recorded, "file-loaded")
+	assert_true(recorded.script_messages["subminer-toggle"] ~= nil, "subminer-toggle script message not registered")
+	recorded.script_messages["subminer-toggle"]()
+	fire_event(recorded, "file-loaded")
+	recorded.script_messages["subminer-autoplay-ready"]()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"manual toggle-off should suppress duplicate auto-start visible overlay reassertion"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "pause", false) == 0,
+		"manual toggle-off followed by duplicate auto-start should keep paused playback paused"
+	)
+end
+
+do
+	local media_path = "/media/jellyfin-redirect.m3u8"
+	local recorded, err = run_plugin_scenario({
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		path = media_path,
+		media_title = "Jellyfin Redirect",
+		paused = true,
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for manual hide same-media reload scenario: " .. tostring(err))
+	fire_event(recorded, "file-loaded")
+	recorded.script_messages["subminer-autoplay-ready"]()
+	recorded.script_messages["subminer-toggle"]()
+	fire_event(recorded, "end-file", { reason = "redirect" })
+	fire_event(recorded, "file-loaded")
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"manual toggle-off should suppress same-media reload visible overlay reassertion"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "pause", false) == 0,
+		"manual toggle-off followed by same-media reload should keep paused playback paused"
+	)
+end
+
+do
+	local scenario = {
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			auto_start_pause_until_ready = "yes",
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		path = "/media/jellyfin-redirect-initial.m3u8",
+		media_title = "Jellyfin Redirect",
+		paused = true,
+		files = {
+			[binary_path] = true,
+		},
+	}
+	local recorded, err = run_plugin_scenario(scenario)
+	assert_true(recorded ~= nil, "plugin failed to load for manual hide path-changing Jellyfin redirect: " .. tostring(err))
+	fire_event(recorded, "start-file")
+	fire_event(recorded, "file-loaded")
+	recorded.script_messages["subminer-autoplay-ready"]()
+	recorded.script_messages["subminer-toggle"]()
+	fire_event(recorded, "end-file", { reason = "redirect" })
+	scenario.path = "/media/jellyfin-redirect-final.m3u8"
+	scenario.media_title = ""
+	fire_event(recorded, "start-file")
+	fire_event(recorded, "file-loaded")
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 0,
+		"manual toggle-off should suppress path-changing Jellyfin redirect visible overlay reassertion even if media-title drops"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "pause", false) == 0,
+		"manual toggle-off followed by path-changing Jellyfin reload should keep paused playback paused"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "sid", "auto") == 2,
+		"path-changing Jellyfin redirect should rearm primary subtitle selection before mpv loads tracks"
+	)
+	assert_true(
+		count_property_set(recorded.property_sets, "secondary-sid", "auto") == 2,
+		"path-changing Jellyfin redirect should rearm secondary subtitle selection before mpv loads tracks"
+	)
+end
+
 do
 	local recorded, err = run_plugin_scenario({
 		process_list = "",
@@ -1721,8 +2134,8 @@ do
 		"auto-start with visible overlay disabled should not include --show-visible-overlay on --start"
 	)
 	assert_true(
-		find_control_call(recorded.async_calls, "--hide-visible-overlay") ~= nil,
-		"auto-start with visible overlay disabled should issue a separate --hide-visible-overlay command"
+		find_control_call(recorded.async_calls, "--hide-visible-overlay") == nil,
+		"auto-start with visible overlay disabled should rely on the --start visibility flag instead of a separate --hide-visible-overlay command"
 	)
 end
 

src/config/config.test.ts

@@ -64,6 +64,7 @@ test('loads defaults when config is missing', () => {
   assert.equal(config.ankiConnect.media.audioPadding, 0);
   assert.equal(config.anilist.enabled, false);
   assert.equal(config.anilist.characterDictionary.enabled, false);
+  assert.equal(config.subtitleStyle.nameMatchImagesEnabled, false);
   assert.equal(config.anilist.characterDictionary.refreshTtlHours, 168);
   assert.equal(config.anilist.characterDictionary.maxLoaded, 3);
   assert.equal(config.anilist.characterDictionary.evictionPolicy, 'delete');
@@ -75,7 +76,10 @@ test('loads defaults when config is missing', () => {
   assert.equal(config.jellyfin.remoteControlEnabled, true);
   assert.equal(config.jellyfin.remoteControlAutoConnect, true);
   assert.equal(config.jellyfin.autoAnnounce, false);
-  assert.equal(config.jellyfin.remoteControlDeviceName, 'SubMiner');
+  assert.equal('clientName' in config.jellyfin, false);
+  assert.equal('remoteControlDeviceName' in config.jellyfin, false);
+  assert.equal('deviceId' in config.jellyfin, false);
+  assert.equal('clientVersion' in config.jellyfin, false);
   assert.equal(config.ai.enabled, false);
   assert.equal(config.ai.apiKeyCommand, '');
   assert.equal(config.texthooker.openBrowser, false);
@@ -149,7 +153,7 @@ test('loads defaults when config is missing', () => {
   assert.equal(config.updates.checkIntervalHours, 24);
   assert.equal(config.updates.notificationType, 'system');
   assert.equal(config.updates.channel, 'stable');
-  assert.equal(config.mpv.socketPath, '/tmp/subminer-socket');
+  assert.equal(config.mpv.socketPath, DEFAULT_CONFIG.mpv.socketPath);
   assert.equal(config.mpv.backend, 'auto');
   assert.equal(config.mpv.profile, '');
   assert.equal(config.mpv.autoStartSubMiner, true);
@@ -737,6 +741,44 @@ test('parses subtitleStyle.nameMatchEnabled and warns on invalid values', () =>
   );
 });
 
+test('parses subtitleStyle.nameMatchImagesEnabled and warns on invalid values', () => {
+  const validDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(validDir, 'config.jsonc'),
+    `{
+      "subtitleStyle": {
+        "nameMatchImagesEnabled": true
+      }
+    }`,
+    'utf-8',
+  );
+
+  const validService = new ConfigService(validDir);
+  assert.equal(validService.getConfig().subtitleStyle.nameMatchImagesEnabled, true);
+
+  const invalidDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(invalidDir, 'config.jsonc'),
+    `{
+      "subtitleStyle": {
+        "nameMatchImagesEnabled": "yes"
+      }
+    }`,
+    'utf-8',
+  );
+
+  const invalidService = new ConfigService(invalidDir);
+  assert.equal(
+    invalidService.getConfig().subtitleStyle.nameMatchImagesEnabled,
+    DEFAULT_CONFIG.subtitleStyle.nameMatchImagesEnabled,
+  );
+  assert.ok(
+    invalidService
+      .getWarnings()
+      .some((warning) => warning.path === 'subtitleStyle.nameMatchImagesEnabled'),
+  );
+});
+
 test('parses anilist.enabled and warns for invalid value', () => {
   const dir = makeTempDir();
   fs.writeFileSync(
@@ -832,7 +874,7 @@ test('parses anilist.characterDictionary.collapsibleSections booleans and warns
   );
 });
 
-test('parses jellyfin remote control fields', () => {
+test('parses jellyfin remote control fields and ignores legacy identity fields', () => {
   const dir = makeTempDir();
   fs.writeFileSync(
     path.join(dir, 'config.jsonc'),
@@ -843,6 +885,7 @@ test('parses jellyfin remote control fields', () => {
         "remoteControlEnabled": true,
         "remoteControlAutoConnect": true,
         "autoAnnounce": true,
+        "clientName": "Custom Client",
         "remoteControlDeviceName": "SubMiner"
       }
     }`,
@@ -857,7 +900,8 @@ test('parses jellyfin remote control fields', () => {
   assert.equal(config.jellyfin.remoteControlEnabled, true);
   assert.equal(config.jellyfin.remoteControlAutoConnect, true);
   assert.equal(config.jellyfin.autoAnnounce, true);
-  assert.equal(config.jellyfin.remoteControlDeviceName, 'SubMiner');
+  assert.equal('clientName' in config.jellyfin, false);
+  assert.equal('remoteControlDeviceName' in config.jellyfin, false);
 });
 
 test('parses jellyfin.enabled and remoteControlEnabled disabled combinations', () => {
@@ -2469,6 +2513,8 @@ test('template generator includes known keys', () => {
   assert.match(output, /"startupWarmups":/);
   assert.match(output, /"updates":/);
   assert.match(output, /"youtube":/);
+  assert.doesNotMatch(output, /"deviceId":/);
+  assert.doesNotMatch(output, /"clientVersion":/);
   assert.doesNotMatch(output, /"youtubeSubgen":/);
   assert.match(output, /"characterDictionary":\s*\{/);
   assert.match(output, /"preserveLineBreaks": false/);

src/config/definitions/defaults-integrations.ts

@@ -130,14 +130,10 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
     serverUrl: '',
     recentServers: [],
     username: '',
-    deviceId: 'subminer',
-    clientName: 'SubMiner',
-    clientVersion: '0.1.0',
     defaultLibraryId: '',
     remoteControlEnabled: true,
     remoteControlAutoConnect: true,
     autoAnnounce: false,
-    remoteControlDeviceName: 'SubMiner',
     pullPictures: false,
     iconCacheDir: '/tmp/subminer-jellyfin-icons',
     directPlayPreferred: true,

src/config/definitions/defaults-subtitle.ts

@@ -11,6 +11,7 @@ export const SUBTITLE_DEFAULT_CONFIG: Pick<ResolvedConfig, 'subtitleStyle' | 'su
     hoverTokenColor: '#f4dbd6',
     hoverTokenBackgroundColor: 'transparent',
     nameMatchEnabled: false,
+    nameMatchImagesEnabled: false,
     nameMatchColor: '#f5bde6',
     fontFamily: 'Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP',
     fontSize: 35,

src/config/definitions/options-integrations.ts

@@ -265,7 +265,8 @@ export function buildIntegrationConfigOptionRegistry(
       kind: 'enum',
       enumValues: ['headword', 'surface'],
       defaultValue: defaultConfig.ankiConnect.knownWords.matchMode,
-      description: 'Known-word matching strategy for subtitle annotations.',
+      description:
+        'Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types.',
     },
     {
       path: 'ankiConnect.knownWords.highlightEnabled',
@@ -548,26 +549,6 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.jellyfin.username,
       description: 'Default Jellyfin username used during CLI login.',
     },
-    {
-      path: 'jellyfin.deviceId',
-      kind: 'string',
-      defaultValue: defaultConfig.jellyfin.deviceId,
-      description:
-        'Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.',
-    },
-    {
-      path: 'jellyfin.clientName',
-      kind: 'string',
-      defaultValue: defaultConfig.jellyfin.clientName,
-      description: 'Client name sent on the Jellyfin authentication handshake; primarily internal.',
-    },
-    {
-      path: 'jellyfin.clientVersion',
-      kind: 'string',
-      defaultValue: defaultConfig.jellyfin.clientVersion,
-      description:
-        'Client version sent on the Jellyfin authentication handshake; primarily internal.',
-    },
     {
       path: 'jellyfin.defaultLibraryId',
       kind: 'string',
@@ -593,12 +574,6 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         'When enabled, automatically trigger remote announce/visibility check on websocket connect.',
     },
-    {
-      path: 'jellyfin.remoteControlDeviceName',
-      kind: 'string',
-      defaultValue: defaultConfig.jellyfin.remoteControlDeviceName,
-      description: 'Device name reported for Jellyfin remote control sessions.',
-    },
     {
       path: 'jellyfin.pullPictures',
       kind: 'boolean',

src/config/definitions/options-subtitle.ts

@@ -76,6 +76,13 @@ export function buildSubtitleConfigOptionRegistry(
       description:
         'Enable subtitle token coloring for matches from the SubMiner character dictionary.',
     },
+    {
+      path: 'subtitleStyle.nameMatchImagesEnabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.subtitleStyle.nameMatchImagesEnabled,
+      description:
+        'Show small character portraits beside subtitle tokens matched from the SubMiner character dictionary.',
+    },
     {
       path: 'subtitleStyle.nameMatchColor',
       kind: 'string',

src/config/resolve/integrations.ts

@@ -371,9 +371,6 @@ export function applyIntegrationConfig(context: ResolveContext): void {
     const stringKeys = [
       'serverUrl',
       'username',
-      'deviceId',
-      'clientName',
-      'clientVersion',
       'defaultLibraryId',
       'iconCacheDir',
       'transcodeVideoCodec',

src/config/resolve/subtitle-domains.ts

@@ -190,6 +190,8 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
     const fallbackSubtitleStyleHoverTokenBackgroundColor =
       resolved.subtitleStyle.hoverTokenBackgroundColor;
     const fallbackSubtitleStyleNameMatchEnabled = resolved.subtitleStyle.nameMatchEnabled;
+    const fallbackSubtitleStyleNameMatchImagesEnabled =
+      resolved.subtitleStyle.nameMatchImagesEnabled;
     const fallbackSubtitleStyleNameMatchColor = resolved.subtitleStyle.nameMatchColor;
     const fallbackSubtitleStyleKnownWordColor = resolved.subtitleStyle.knownWordColor;
     const fallbackSubtitleStyleNPlusOneColor = resolved.subtitleStyle.nPlusOneColor;
@@ -390,6 +392,24 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
       );
     }
 
+    const nameMatchImagesEnabled = asBoolean(
+      (src.subtitleStyle as { nameMatchImagesEnabled?: unknown }).nameMatchImagesEnabled,
+    );
+    if (nameMatchImagesEnabled !== undefined) {
+      resolved.subtitleStyle.nameMatchImagesEnabled = nameMatchImagesEnabled;
+    } else if (
+      (src.subtitleStyle as { nameMatchImagesEnabled?: unknown }).nameMatchImagesEnabled !==
+      undefined
+    ) {
+      resolved.subtitleStyle.nameMatchImagesEnabled = fallbackSubtitleStyleNameMatchImagesEnabled;
+      warn(
+        'subtitleStyle.nameMatchImagesEnabled',
+        (src.subtitleStyle as { nameMatchImagesEnabled?: unknown }).nameMatchImagesEnabled,
+        resolved.subtitleStyle.nameMatchImagesEnabled,
+        'Expected boolean.',
+      );
+    }
+
     if (nameMatchColor !== undefined) {
       resolved.subtitleStyle.nameMatchColor = nameMatchColor;
     } else if ((src.subtitleStyle as { nameMatchColor?: unknown }).nameMatchColor !== undefined) {

src/config/resolve/subtitle-style.test.ts

@@ -172,6 +172,31 @@ test('subtitleStyle nameMatchEnabled falls back on invalid value', () => {
   );
 });
 
+test('subtitleStyle nameMatchImagesEnabled accepts boolean and warns on invalid', () => {
+  const valid = createResolveContext({
+    subtitleStyle: {
+      nameMatchImagesEnabled: true,
+    },
+  });
+  applySubtitleDomainConfig(valid.context);
+  assert.equal(valid.context.resolved.subtitleStyle.nameMatchImagesEnabled, true);
+
+  const invalid = createResolveContext({
+    subtitleStyle: {
+      nameMatchImagesEnabled: 'yes' as unknown as boolean,
+    },
+  });
+  applySubtitleDomainConfig(invalid.context);
+  assert.equal(invalid.context.resolved.subtitleStyle.nameMatchImagesEnabled, false);
+  assert.ok(
+    invalid.warnings.some(
+      (warning) =>
+        warning.path === 'subtitleStyle.nameMatchImagesEnabled' &&
+        warning.message === 'Expected boolean.',
+    ),
+  );
+});
+
 test('subtitleStyle frequencyDictionary defaults to the teal fourth band color', () => {
   const { context } = createResolveContext({});
 

src/config/settings/registry.test.ts

@@ -59,7 +59,6 @@ test('settings registry hides removed modal-only fields', () => {
     'shortcuts.multiCopyTimeoutMs',
     'anilist.characterDictionary.profileScope',
     'jellyfin.directPlayContainers',
-    'jellyfin.remoteControlDeviceName',
   ]) {
     assert.equal(
       fields.some((candidate) => candidate.configPath === path),
@@ -174,6 +173,7 @@ test('settings registry exposes css declaration editor for primary and secondary
   assert.equal(field('subtitleStyle.WebkitTextStroke').settingsHidden, true);
   assert.equal(field('subtitleStyle.knownWordColor').settingsHidden, false);
   assert.equal(field('subtitleStyle.nPlusOneColor').settingsHidden, false);
+  assert.equal(field('subtitleStyle.nameMatchImagesEnabled').settingsHidden, false);
   assert.equal(field('subtitleStyle.nameMatchColor').settingsHidden, false);
   assert.equal(field('subtitleStyle.jlptColors.N1').settingsHidden, false);
   assert.equal(field('subtitleStyle.frequencyDictionary.singleColor').settingsHidden, false);
@@ -246,10 +246,7 @@ test('settings registry hides app-managed and inactive config surfaces', () => {
     'controller.preferredGamepadLabel',
     'controller.profiles',
     'youtubeSubgen.whisperBin',
-    'jellyfin.clientVersion',
     'jellyfin.defaultLibraryId',
-    'jellyfin.deviceId',
-    'jellyfin.clientName',
     'subtitleSidebar.toggleKey',
     'jellyfin.recentServers',
   ]) {

src/config/settings/registry.ts

@@ -68,12 +68,8 @@ export const LEGACY_HIDDEN_CONFIG_PATHS = [
   'anilist.characterDictionary.profileScope',
   'jellyfin.accessToken',
   'jellyfin.userId',
-  'jellyfin.clientName',
-  'jellyfin.clientVersion',
   'jellyfin.defaultLibraryId',
-  'jellyfin.deviceId',
   'jellyfin.directPlayContainers',
-  'jellyfin.remoteControlDeviceName',
   'controller.buttonIndices',
   'shortcuts.multiCopyTimeoutMs',
   'subtitleSidebar.toggleKey',
@@ -349,6 +345,7 @@ function categoryAndSection(path: string): { category: ConfigSettingsCategory; s
     path === 'subtitleStyle.knownWordColor' ||
     path === 'subtitleStyle.nPlusOneColor' ||
     path === 'subtitleStyle.nameMatchEnabled' ||
+    path === 'subtitleStyle.nameMatchImagesEnabled' ||
     path === 'subtitleStyle.nameMatchColor'
   ) {
     return { category: 'appearance', section: 'Annotation Display' };
@@ -528,7 +525,11 @@ function subsectionForPath(path: string): string | undefined {
   ) {
     return 'Frequency Highlighting';
   }
-  if (path === 'subtitleStyle.nameMatchEnabled' || path === 'subtitleStyle.nameMatchColor') {
+  if (
+    path === 'subtitleStyle.nameMatchEnabled' ||
+    path === 'subtitleStyle.nameMatchImagesEnabled' ||
+    path === 'subtitleStyle.nameMatchColor'
+  ) {
     return 'Character Names';
   }
   if (path === 'anilist.characterDictionary.collapsibleSections.description') {

src/core/services/app-lifecycle.test.ts

@@ -280,6 +280,44 @@ test('startAppLifecycle routes control socket commands through the second-instan
   assert.deepEqual(handled, ['ready', 'second-instance:start', 'control-close']);
 });
 
+test('startAppLifecycle drains queued second-instance commands when app ready runtime fails', async () => {
+  const handled: string[] = [];
+  let controlArgvHandler: ((argv: string[]) => void) | null = null;
+  let readyHandler: (() => Promise<void>) | null = null;
+
+  const { deps } = createDeps({
+    shouldStartApp: () => true,
+    parseArgs: (argv) => makeArgs({ start: argv.includes('--start') }),
+    handleCliCommand: (args, source) => {
+      handled.push(`${source}:${args.start ? 'start' : 'other'}`);
+    },
+    startControlServer: (handler) => {
+      controlArgvHandler = handler;
+    },
+    whenReady: (handler) => {
+      readyHandler = handler;
+    },
+    onReady: async () => {
+      handled.push('ready');
+      throw new Error('ready failed');
+    },
+  });
+
+  startAppLifecycle(makeArgs({ background: true }), deps);
+
+  assert.ok(controlArgvHandler);
+  (controlArgvHandler as (argv: string[]) => void)(['--start']);
+  assert.deepEqual(handled, []);
+
+  assert.ok(readyHandler);
+  await assert.rejects((readyHandler as () => Promise<void>)(), /ready failed/);
+
+  assert.deepEqual(handled, ['ready', 'second-instance:start']);
+
+  (controlArgvHandler as (argv: string[]) => void)(['--start']);
+  assert.deepEqual(handled, ['ready', 'second-instance:start', 'second-instance:start']);
+});
+
 test('startAppLifecycle quits macOS config-only launch when all windows close', () => {
   let windowAllClosedHandler: (() => void) | null = null;
   const { deps, calls } = createDeps({

src/core/services/app-lifecycle.ts

@@ -172,9 +172,12 @@ export function startAppLifecycle(initialArgs: CliArgs, deps: AppLifecycleServic
   }
 
   deps.whenReady(async () => {
-    await deps.onReady();
-    appReadyRuntimeComplete = true;
-    flushPendingSecondInstanceCommands();
+    try {
+      await deps.onReady();
+    } finally {
+      appReadyRuntimeComplete = true;
+      flushPendingSecondInstanceCommands();
+    }
   });
 
   deps.onWindowAllClosed(() => {

src/core/services/discord-presence.test.ts

@@ -91,6 +91,22 @@ test('buildDiscordPresenceActivity shows media title regardless of style', () =>
   }
 });
 
+test('buildDiscordPresenceActivity never falls back to remote stream URLs', () => {
+  const payload = buildDiscordPresenceActivity(baseConfig, {
+    ...baseSnapshot,
+    mediaTitle: null,
+    mediaPath:
+      'http://jellyfin.local/Videos/item-1/stream?static=true&api_key=secret-token&MediaSourceId=ms-1',
+  });
+
+  assert.equal(payload.details, 'Unknown media');
+  assert.equal(payload.state, 'Playing 01:35 / 24:10');
+  const serialized = JSON.stringify(payload);
+  assert.equal(serialized.includes('api_key'), false);
+  assert.equal(serialized.includes('secret-token'), false);
+  assert.equal(serialized.includes('/Videos/item-1/stream'), false);
+});
+
 test('service deduplicates identical updates and sends changed timeline', async () => {
   const sent: DiscordActivityPayload[] = [];
   const timers = new Map<number, () => void>();

src/core/services/discord-presence.ts

@@ -106,6 +106,15 @@ function basename(filePath: string | null): string {
   return parts[parts.length - 1] ?? '';
 }
 
+function fallbackTitleFromMediaPath(mediaPath: string | null): string {
+  const trimmed = mediaPath?.trim();
+  if (!trimmed) return '';
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) && !trimmed.toLowerCase().startsWith('file://')) {
+    return '';
+  }
+  return basename(trimmed).split(/[?#]/)[0] ?? '';
+}
+
 function buildStatus(snapshot: DiscordPresenceSnapshot): string {
   if (!snapshot.connected || !snapshot.mediaPath) return 'Idle';
   if (snapshot.paused) return 'Paused';
@@ -130,7 +139,10 @@ export function buildDiscordPresenceActivity(
 ): DiscordActivityPayload {
   const style = resolvePresenceStyle(config.presenceStyle);
   const status = buildStatus(snapshot);
-  const title = sanitizeText(snapshot.mediaTitle, basename(snapshot.mediaPath) || 'Unknown media');
+  const title = sanitizeText(
+    snapshot.mediaTitle,
+    fallbackTitleFromMediaPath(snapshot.mediaPath) || 'Unknown media',
+  );
   const details =
     snapshot.connected && snapshot.mediaPath ? trimField(title) : style.fallbackDetails;
   const timeline = `${formatClock(snapshot.currentTimeSec)} / ${formatClock(snapshot.mediaDurationSec)}`;

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

@@ -1552,6 +1552,98 @@ test('handleMediaChange reuses the same provisional anime row across matching fi
   }
 });
 
+test('Jellyfin playback metadata links stream videos to existing series title', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath });
+
+    tracker.handleMediaChange('/tmp/The Beginning After the End S02E01.mkv', 'Episode 1');
+    await waitForPendingAnimeMetadata(tracker);
+    tracker.destroy();
+    tracker = null;
+
+    tracker = new Ctor({ dbPath });
+    tracker.recordJellyfinPlaybackMetadata({
+      mediaPath:
+        'http://jellyfin.local/Videos/item-2/stream?static=true&api_key=token&MediaSourceId=ms-1',
+      displayTitle: 'The Beginning After the End S02E02 The Princess Begins Adventuring',
+      itemTitle: 'The Princess Begins Adventuring',
+      seriesTitle: 'The Beginning After the End',
+      seasonNumber: 2,
+      episodeNumber: 2,
+      itemId: 'item-2',
+    });
+    tracker.handleMediaChange(
+      'http://jellyfin.local/Videos/item-2/stream?static=true&api_key=token&MediaSourceId=ms-1',
+      'The Beginning After the End S02E02 The Princess Begins Adventuring',
+    );
+    tracker.handleMediaChange(null, null);
+    tracker.recordJellyfinPlaybackMetadata({
+      mediaPath:
+        'http://jellyfin.local/Videos/item-2/stream?static=true&api_key=token&MediaSourceId=ms-1&StartTimeTicks=12000000',
+      displayTitle: 'The Beginning After the End S02E02 The Princess Begins Adventuring',
+      itemTitle: 'The Princess Begins Adventuring',
+      seriesTitle: 'The Beginning After the End',
+      seasonNumber: 2,
+      episodeNumber: 2,
+      itemId: 'item-2',
+    });
+    tracker.handleMediaChange(
+      'http://jellyfin.local/Videos/item-2/stream?static=true&api_key=token&MediaSourceId=ms-1&StartTimeTicks=12000000',
+      'The Beginning After the End S02E02 The Princess Begins Adventuring',
+    );
+
+    const privateApi = tracker as unknown as { db: DatabaseSync };
+    const rows = privateApi.db
+      .prepare(
+        `
+          SELECT
+            v.source_url,
+            v.canonical_title AS video_title,
+            v.parsed_title,
+            v.parsed_season,
+            v.parsed_episode,
+            v.parser_source,
+            a.canonical_title AS anime_title
+          FROM imm_videos v
+          JOIN imm_anime a ON a.anime_id = v.anime_id
+          ORDER BY v.video_id
+        `,
+      )
+      .all() as Array<{
+      source_url: string | null;
+      video_title: string;
+      parsed_title: string | null;
+      parsed_season: number | null;
+      parsed_episode: number | null;
+      parser_source: string | null;
+      anime_title: string;
+    }>;
+
+    assert.equal(rows.length, 2);
+    assert.equal(new Set(rows.map((row) => row.anime_title)).size, 1);
+    const jellyfinRow = rows.find(
+      (row) => row.source_url === 'jellyfin://jellyfin.local/item/item-2',
+    );
+    assert.ok(jellyfinRow);
+    assert.equal(
+      jellyfinRow.video_title,
+      'The Beginning After the End S02E02 The Princess Begins Adventuring',
+    );
+    assert.equal(jellyfinRow.parsed_title, 'The Beginning After the End');
+    assert.equal(jellyfinRow.parsed_season, 2);
+    assert.equal(jellyfinRow.parsed_episode, 2);
+    assert.equal(jellyfinRow.parser_source, 'jellyfin');
+    assert.equal(jellyfinRow.anime_title, 'The Beginning After the End');
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
 test('applies configurable queue, flush, and retention policy', async () => {
   const dbPath = makeDbPath();
   let tracker: ImmersionTrackerService | null = null;

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

@@ -301,6 +301,33 @@ export type {
   VocabularyStatsRow,
 } from './immersion-tracker/types';
 
+export interface JellyfinPlaybackMetadataInput {
+  mediaPath: string;
+  displayTitle: string;
+  itemTitle: string;
+  seriesTitle: string | null;
+  seasonNumber: number | null;
+  episodeNumber: number | null;
+  itemId: string;
+}
+
+function normalizeMetadataInt(value: number | null | undefined): number | null {
+  return typeof value === 'number' && Number.isSafeInteger(value) ? value : null;
+}
+
+function buildJellyfinStatsMediaPath(mediaPath: string, itemId: string): string {
+  const normalizedItemId = normalizeText(itemId);
+  if (!normalizedItemId) {
+    return mediaPath;
+  }
+  try {
+    const parsed = new URL(mediaPath);
+    return `jellyfin://${parsed.host}/item/${encodeURIComponent(normalizedItemId)}`;
+  } catch {
+    return `jellyfin://item/${encodeURIComponent(normalizedItemId)}`;
+  }
+}
+
 export class ImmersionTrackerService {
   private readonly logger = createLogger('main:immersion-tracker');
   private readonly db: DatabaseSync;
@@ -337,6 +364,7 @@ export class ImmersionTrackerService {
   private readonly pendingYoutubeMetadataFetches = new Map<number, Promise<void>>();
   private readonly recordedSubtitleKeys = new Set<string>();
   private readonly pendingAnimeMetadataUpdates = new Map<number, Promise<void>>();
+  private readonly mediaPathAliases = new Map<string, string>();
   private readonly resolveLegacyVocabularyPos:
     | ((row: LegacyVocabularyPosRow) => Promise<LegacyVocabularyPosResolution | null>)
     | undefined;
@@ -1115,8 +1143,85 @@ export class ImmersionTrackerService {
     rebuildLifetimeSummaryTables(this.db);
   }
 
+  recordJellyfinPlaybackMetadata(metadata: JellyfinPlaybackMetadataInput): void {
+    const rawPath = normalizeMediaPath(metadata.mediaPath);
+    if (!rawPath) {
+      return;
+    }
+    const normalizedPath = buildJellyfinStatsMediaPath(rawPath, metadata.itemId);
+    this.mediaPathAliases.set(rawPath, normalizedPath);
+
+    const displayTitle =
+      normalizeText(metadata.displayTitle) ||
+      normalizeText(metadata.itemTitle) ||
+      deriveCanonicalTitle(normalizedPath);
+    const itemTitle = normalizeText(metadata.itemTitle) || displayTitle;
+    const seriesTitle = normalizeText(metadata.seriesTitle);
+    const libraryTitle = seriesTitle || itemTitle;
+    if (!libraryTitle) {
+      return;
+    }
+
+    const videoId = getOrCreateVideoRecord(
+      this.db,
+      buildVideoKey(normalizedPath, SOURCE_TYPE_REMOTE),
+      {
+        canonicalTitle: displayTitle,
+        sourcePath: null,
+        sourceUrl: normalizedPath,
+        sourceType: SOURCE_TYPE_REMOTE,
+      },
+    );
+    const previousLink = this.db
+      .prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = ?')
+      .get(videoId) as { animeId: number | null } | null;
+    const metadataJson = JSON.stringify({
+      source: 'jellyfin',
+      itemId: normalizeText(metadata.itemId) || null,
+      itemTitle,
+      seriesTitle: seriesTitle || null,
+      displayTitle,
+      seasonNumber: normalizeMetadataInt(metadata.seasonNumber),
+      episodeNumber: normalizeMetadataInt(metadata.episodeNumber),
+    });
+    const animeId = getOrCreateAnimeRecord(this.db, {
+      parsedTitle: libraryTitle,
+      canonicalTitle: libraryTitle,
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson,
+    });
+    linkVideoToAnimeRecord(this.db, videoId, {
+      animeId,
+      parsedBasename: null,
+      parsedTitle: libraryTitle,
+      parsedSeason: normalizeMetadataInt(metadata.seasonNumber),
+      parsedEpisode: normalizeMetadataInt(metadata.episodeNumber),
+      parserSource: 'jellyfin',
+      parserConfidence: 1,
+      parseMetadataJson: metadataJson,
+    });
+
+    const hasLifetimeMedia = Boolean(
+      this.db.prepare('SELECT 1 FROM imm_lifetime_media WHERE video_id = ?').get(videoId),
+    );
+    if (hasLifetimeMedia || (previousLink && previousLink.animeId !== animeId)) {
+      rebuildLifetimeSummaryTables(this.db);
+    }
+  }
+
+  private hasJellyfinMetadata(videoId: number): boolean {
+    const row = this.db
+      .prepare('SELECT parser_source AS parserSource FROM imm_videos WHERE video_id = ?')
+      .get(videoId) as { parserSource: string | null } | null;
+    return row?.parserSource === 'jellyfin';
+  }
+
   handleMediaChange(mediaPath: string | null, mediaTitle: string | null): void {
-    const normalizedPath = normalizeMediaPath(mediaPath);
+    const rawPath = normalizeMediaPath(mediaPath);
+    const normalizedPath = this.mediaPathAliases.get(rawPath) ?? rawPath;
     const normalizedTitle = normalizeText(mediaTitle);
     this.logger.info(
       `handleMediaChange called with path=${normalizedPath || '<empty>'} title=${normalizedTitle || '<empty>'}`,
@@ -1164,7 +1269,7 @@ export class ImmersionTrackerService {
     if (youtubeVideoId) {
       void this.ensureYouTubeCoverArt(sessionInfo.videoId, normalizedPath, youtubeVideoId);
       this.captureYoutubeMetadataAsync(sessionInfo.videoId, normalizedPath);
-    } else {
+    } else if (!this.hasJellyfinMetadata(sessionInfo.videoId)) {
       this.captureAnimeMetadataAsync(sessionInfo.videoId, normalizedPath, normalizedTitle || null);
     }
     this.captureVideoMetadataAsync(sessionInfo.videoId, sourceType, normalizedPath);

src/core/services/index.ts

@@ -80,7 +80,11 @@ export {
   handleOverlayWindowBeforeInputEvent,
   isTabInputForMpvForwarding,
 } from './overlay-window-input';
-export { initializeOverlayAnkiIntegration, initializeOverlayRuntime } from './overlay-runtime-init';
+export {
+  initializeOverlayAnkiIntegration,
+  initializeOverlayRuntime,
+  startOverlayWindowTracker,
+} from './overlay-runtime-init';
 export { setVisibleOverlayVisible, updateVisibleOverlayVisibility } from './overlay-visibility';
 export {
   MPV_REQUEST_ID_SECONDARY_SUB_VISIBILITY,
@@ -116,6 +120,12 @@ export {
   resolvePlaybackPlan as resolveJellyfinPlaybackPlanRuntime,
   ticksToSeconds as jellyfinTicksToSecondsRuntime,
 } from './jellyfin';
+export { loadJellyfinSubtitleDelay, saveJellyfinSubtitleDelay } from './jellyfin-subtitle-delay';
+export {
+  estimateSubtitleTimingOffset,
+  type SubtitleTimingOffsetOptions,
+  type SubtitleTimingOffsetResult,
+} from './subtitle-timing-offset';
 export { buildJellyfinTimelinePayload, JellyfinRemoteSessionService } from './jellyfin-remote';
 export {
   broadcastRuntimeOptionsChangedRuntime,

src/core/services/ipc.test.ts

@@ -1191,18 +1191,22 @@ test('registerIpcHandlers rejects malformed controller preference payloads', asy
 test('registerIpcHandlers exposes character dictionary selection handlers', async () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const calls: number[] = [];
+  const searches: Array<string | undefined> = [];
 
   registerIpcHandlers(
     createRegisterIpcDeps({
-      getCharacterDictionarySelection: async () => ({
-        seriesKey: 're-zero-starting-life-in-another-world-2016',
-        guessTitle: 'Re ZERO, Starting Life in Another World',
-        current: { id: 10607, title: 'Rerere no Tensai Bakabon', episodes: 24 },
-        override: null,
-        candidates: [
-          { id: 21355, title: 'Re:ZERO -Starting Life in Another World-', episodes: 25 },
-        ],
-      }),
+      getCharacterDictionarySelection: async (searchTitle) => {
+        searches.push(searchTitle);
+        return {
+          seriesKey: 're-zero-starting-life-in-another-world-2016',
+          guessTitle: 'Re ZERO, Starting Life in Another World',
+          current: { id: 10607, title: 'Rerere no Tensai Bakabon', episodes: 24 },
+          override: null,
+          candidates: [
+            { id: 21355, title: 'Re:ZERO -Starting Life in Another World-', episodes: 25 },
+          ],
+        };
+      },
       setCharacterDictionarySelection: async (mediaId) => {
         calls.push(mediaId);
         return {
@@ -1223,7 +1227,7 @@ test('registerIpcHandlers exposes character dictionary selection handlers', asyn
   const getHandler = handlers.handle.get(IPC_CHANNELS.request.getCharacterDictionarySelection);
   const setHandler = handlers.handle.get(IPC_CHANNELS.request.setCharacterDictionarySelection);
 
-  assert.deepEqual(await getHandler!({}), {
+  assert.deepEqual(await getHandler!({}, '  Re:ZERO  '), {
     seriesKey: 're-zero-starting-life-in-another-world-2016',
     guessTitle: 'Re ZERO, Starting Life in Another World',
     current: { id: 10607, title: 'Rerere no Tensai Bakabon', episodes: 24 },
@@ -1241,4 +1245,5 @@ test('registerIpcHandlers exposes character dictionary selection handlers', asyn
     staleMediaIds: [10607],
   });
   assert.deepEqual(calls, [21355]);
+  assert.deepEqual(searches, ['Re:ZERO']);
 });

src/core/services/ipc.ts

@@ -95,7 +95,7 @@ export interface IpcServiceDeps {
   getAnilistQueueStatus: () => unknown;
   retryAnilistQueueNow: () => Promise<{ ok: boolean; message: string }>;
   runAnilistPostWatchUpdateOnManualMark?: () => Promise<void>;
-  getCharacterDictionarySelection?: () => Promise<unknown>;
+  getCharacterDictionarySelection?: (searchTitle?: string) => Promise<unknown>;
   setCharacterDictionarySelection?: (mediaId: number) => Promise<unknown>;
   appendClipboardVideoToQueue: () => { ok: boolean; message: string };
   getPlaylistBrowserSnapshot: () => Promise<PlaylistBrowserSnapshot>;
@@ -223,7 +223,7 @@ export interface IpcDepsRuntimeOptions {
   getAnilistQueueStatus: () => unknown;
   retryAnilistQueueNow: () => Promise<{ ok: boolean; message: string }>;
   runAnilistPostWatchUpdateOnManualMark?: () => Promise<void>;
-  getCharacterDictionarySelection?: () => Promise<unknown>;
+  getCharacterDictionarySelection?: (searchTitle?: string) => Promise<unknown>;
   setCharacterDictionarySelection?: (mediaId: number) => Promise<unknown>;
   appendClipboardVideoToQueue: () => { ok: boolean; message: string };
   getPlaylistBrowserSnapshot: () => Promise<PlaylistBrowserSnapshot>;
@@ -615,8 +615,9 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
     return await deps.retryAnilistQueueNow();
   });
 
-  ipc.handle(IPC_CHANNELS.request.getCharacterDictionarySelection, async () => {
-    return await (deps.getCharacterDictionarySelection?.() ??
+  ipc.handle(IPC_CHANNELS.request.getCharacterDictionarySelection, async (_event, searchTitle) => {
+    const normalizedSearchTitle = typeof searchTitle === 'string' ? searchTitle.trim() : undefined;
+    return await (deps.getCharacterDictionarySelection?.(normalizedSearchTitle) ??
       Promise.resolve({
         seriesKey: '',
         guessTitle: null,

src/core/services/jellyfin-remote.test.ts

@@ -289,6 +289,44 @@ test('reportProgress posts timeline payload and treats failure as non-fatal', as
   assert.deepEqual(JSON.parse(String(timelineCall.init.body)), expectedPostedPayload);
 });
 
+test('timeline payload omits websocket-only event names', () => {
+  const payload = buildJellyfinTimelinePayload({
+    itemId: 'movie-2',
+    positionTicks: 123456,
+    eventName: 'TimeUpdate',
+  });
+
+  assert.equal('EventName' in payload, false);
+});
+
+test('reportStopped posts final position and explicit non-failed state', async () => {
+  const fetchCalls: Array<{ input: string; init: RequestInit }> = [];
+  const service = new JellyfinRemoteSessionService({
+    serverUrl: 'http://jellyfin.local',
+    accessToken: 'token-stop-payload',
+    deviceId: 'device-stop-payload',
+    webSocketFactory: () => new FakeWebSocket() as unknown as any,
+    fetchImpl: (async (input, init) => {
+      fetchCalls.push({ input: String(input), init: init ?? {} });
+      return new Response(null, { status: 200 });
+    }) as typeof fetch,
+  });
+
+  const ok = await service.reportStopped({
+    itemId: 'movie-stop',
+    positionTicks: 7654321,
+    failed: false,
+  });
+
+  const stoppedCall = fetchCalls.find((call) => call.input.endsWith('/Sessions/Playing/Stopped'));
+  assert.equal(ok, true);
+  assert.ok(stoppedCall);
+  assert.ok(typeof stoppedCall.init.body === 'string');
+  const posted = JSON.parse(String(stoppedCall.init.body));
+  assert.equal(posted.PositionTicks, 7654321);
+  assert.equal(posted.Failed, false);
+});
+
 test('advertiseNow validates server registration using Sessions endpoint', async () => {
   const sockets: FakeWebSocket[] = [];
   const calls: string[] = [];

src/core/services/jellyfin-remote.ts

@@ -20,6 +20,7 @@ export interface JellyfinTimelinePlaybackState {
   subtitleStreamIndex?: number | null;
   playlistItemId?: string | null;
   eventName?: string;
+  failed?: boolean;
 }
 
 export interface JellyfinTimelinePayload {
@@ -36,7 +37,7 @@ export interface JellyfinTimelinePayload {
   AudioStreamIndex?: number | null;
   SubtitleStreamIndex?: number | null;
   PlaylistItemId?: string | null;
-  EventName: string;
+  Failed?: boolean;
 }
 
 interface JellyfinRemoteSocket {
@@ -168,7 +169,7 @@ export function buildJellyfinTimelinePayload(
     AudioStreamIndex: asNullableInteger(state.audioStreamIndex),
     SubtitleStreamIndex: asNullableInteger(state.subtitleStreamIndex),
     PlaylistItemId: state.playlistItemId,
-    EventName: state.eventName || 'timeupdate',
+    Failed: state.failed,
   };
 }
 
@@ -269,10 +270,7 @@ export class JellyfinRemoteSessionService {
   }
 
   public async reportPlaying(state: JellyfinTimelinePlaybackState): Promise<boolean> {
-    return this.postTimeline('/Sessions/Playing', {
-      ...buildJellyfinTimelinePayload(state),
-      EventName: state.eventName || 'start',
-    });
+    return this.postTimeline('/Sessions/Playing', buildJellyfinTimelinePayload(state));
   }
 
   public async reportProgress(state: JellyfinTimelinePlaybackState): Promise<boolean> {
@@ -282,7 +280,7 @@ export class JellyfinRemoteSessionService {
   public async reportStopped(state: JellyfinTimelinePlaybackState): Promise<boolean> {
     return this.postTimeline('/Sessions/Playing/Stopped', {
       ...buildJellyfinTimelinePayload(state),
-      EventName: state.eventName || 'stop',
+      Failed: state.failed === true,
     });
   }
 

src/core/services/jellyfin-subtitle-delay.test.ts

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import test from 'node:test';
+import { loadJellyfinSubtitleDelay, saveJellyfinSubtitleDelay } from './jellyfin-subtitle-delay';
+
+function statePath(name: string): string {
+  return path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-jellyfin-delay-')), name);
+}
+
+test('jellyfin subtitle delay store saves and loads delay by item and stream', () => {
+  const filePath = statePath('delays.json');
+
+  assert.equal(
+    saveJellyfinSubtitleDelay({
+      filePath,
+      itemId: 'episode-1',
+      streamIndex: 3,
+      delaySeconds: 1.25,
+    }),
+    true,
+  );
+
+  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), 1.25);
+  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4 }), null);
+});
+
+test('jellyfin subtitle delay store preserves other stream delays when updating one stream', () => {
+  const filePath = statePath('delays.json');
+
+  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3, delaySeconds: 1.25 });
+  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4, delaySeconds: -0.5 });
+  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3, delaySeconds: 2 });
+
+  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), 2);
+  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4 }), -0.5);
+});
+
+test('jellyfin subtitle delay store ignores invalid files and values', () => {
+  const filePath = statePath('delays.json');
+  fs.writeFileSync(filePath, '{');
+
+  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), null);
+  assert.equal(
+    saveJellyfinSubtitleDelay({
+      filePath,
+      itemId: 'episode-1',
+      streamIndex: 3,
+      delaySeconds: Number.NaN,
+    }),
+    false,
+  );
+});

src/core/services/jellyfin-subtitle-delay.ts

@@ -0,0 +1,66 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+type JellyfinSubtitleDelayStore = {
+  version?: unknown;
+  delays?: unknown;
+};
+
+type JellyfinSubtitleDelayParams = {
+  filePath: string;
+  itemId: string;
+  streamIndex: number;
+};
+
+type SaveJellyfinSubtitleDelayParams = JellyfinSubtitleDelayParams & {
+  delaySeconds: number;
+};
+
+function storeKey(itemId: string, streamIndex: number): string {
+  return JSON.stringify([itemId, streamIndex]);
+}
+
+function readDelayMap(filePath: string): Record<string, number> {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as JellyfinSubtitleDelayStore;
+    if (
+      !parsed ||
+      typeof parsed !== 'object' ||
+      !parsed.delays ||
+      typeof parsed.delays !== 'object'
+    ) {
+      return {};
+    }
+    const delays: Record<string, number> = {};
+    for (const [key, value] of Object.entries(parsed.delays as Record<string, unknown>)) {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        delays[key] = value;
+      }
+    }
+    return delays;
+  } catch {
+    return {};
+  }
+}
+
+export function loadJellyfinSubtitleDelay(params: JellyfinSubtitleDelayParams): number | null {
+  const delay = readDelayMap(params.filePath)[storeKey(params.itemId, params.streamIndex)];
+  return typeof delay === 'number' && Number.isFinite(delay) ? delay : null;
+}
+
+export function saveJellyfinSubtitleDelay(params: SaveJellyfinSubtitleDelayParams): boolean {
+  if (!Number.isFinite(params.delaySeconds)) return false;
+  try {
+    const delays = readDelayMap(params.filePath);
+    delays[storeKey(params.itemId, params.streamIndex)] = params.delaySeconds;
+    const dir = path.dirname(params.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(params.filePath, JSON.stringify({ version: 1, delays }, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}

src/core/services/jellyfin.test.ts

@@ -229,6 +229,7 @@ test('resolvePlaybackPlan chooses direct play when allowed', async () => {
     assert.equal(plan.mode, 'direct');
     assert.match(plan.url, /Videos\/movie-1\/stream\?/);
     assert.doesNotMatch(plan.url, /SubtitleStreamIndex=/);
+    assert.equal(new URL(plan.url).searchParams.get('StartTimeTicks'), null);
     assert.equal(plan.subtitleStreamIndex, null);
     assert.equal(ticksToSeconds(plan.startTimeTicks), 2);
   } finally {
@@ -560,13 +561,17 @@ test('resolvePlaybackPlan preserves episode metadata, stream selection, and resu
 
     assert.equal(plan.mode, 'direct');
     assert.equal(plan.title, 'Galaxy Quest S02E07 A New Hope');
+    assert.equal(plan.itemTitle, 'A New Hope');
+    assert.equal(plan.seriesTitle, 'Galaxy Quest');
+    assert.equal(plan.seasonNumber, 2);
+    assert.equal(plan.episodeNumber, 7);
     assert.equal(plan.audioStreamIndex, 6);
     assert.equal(plan.subtitleStreamIndex, 9);
     assert.equal(plan.startTimeTicks, 35_000_000);
     const url = new URL(plan.url);
     assert.equal(url.searchParams.get('AudioStreamIndex'), '6');
     assert.equal(url.searchParams.get('SubtitleStreamIndex'), '9');
-    assert.equal(url.searchParams.get('StartTimeTicks'), '35000000');
+    assert.equal(url.searchParams.get('StartTimeTicks'), null);
   } finally {
     globalThis.fetch = originalFetch;
   }

src/core/services/jellyfin.ts

@@ -27,6 +27,10 @@ export interface JellyfinPlaybackPlan {
   mode: 'direct' | 'transcode';
   url: string;
   title: string;
+  itemTitle: string;
+  seriesTitle: string | null;
+  seasonNumber: number | null;
+  episodeNumber: number | null;
   startTimeTicks: number;
   audioStreamIndex: number | null;
   subtitleStreamIndex: number | null;
@@ -229,9 +233,6 @@ function createDirectPlayUrl(
   if (plan.subtitleStreamIndex !== null) {
     query.set('SubtitleStreamIndex', String(plan.subtitleStreamIndex));
   }
-  if (plan.startTimeTicks > 0) {
-    query.set('StartTimeTicks', String(plan.startTimeTicks));
-  }
   return `${session.serverUrl}/Videos/${itemId}/stream?${query.toString()}`;
 }
 
@@ -292,14 +293,24 @@ function getStreamDefaults(source: JellyfinMediaSource): {
   };
 }
 
+function getItemTitle(item: JellyfinItem): string {
+  return ensureString(item.Name).trim() || 'Jellyfin Item';
+}
+
+function getSeriesTitle(item: JellyfinItem): string | null {
+  return ensureString(item.SeriesName).trim() || null;
+}
+
 function getDisplayTitle(item: JellyfinItem): string {
+  const itemTitle = getItemTitle(item);
   if (item.Type === 'Episode') {
     const season = asIntegerOrNull(item.ParentIndexNumber) ?? 0;
     const episode = asIntegerOrNull(item.IndexNumber) ?? 0;
-    const prefix = item.SeriesName ? `${item.SeriesName} ` : '';
-    return `${prefix}S${String(season).padStart(2, '0')}E${String(episode).padStart(2, '0')} ${ensureString(item.Name).trim()}`.trim();
+    const seriesTitle = getSeriesTitle(item);
+    const prefix = seriesTitle ? `${seriesTitle} ` : '';
+    return `${prefix}S${String(season).padStart(2, '0')}E${String(episode).padStart(2, '0')} ${itemTitle}`.trim();
   }
-  return ensureString(item.Name).trim() || 'Jellyfin Item';
+  return itemTitle;
 }
 
 function shouldPreferDirectPlay(source: JellyfinMediaSource, config: JellyfinConfig): boolean {
@@ -521,10 +532,16 @@ export async function resolvePlaybackPlan(
   const audioStreamIndex = selection.audioStreamIndex ?? defaults.audioStreamIndex ?? null;
   const subtitleStreamIndex = selection.subtitleStreamIndex ?? null;
   const startTimeTicks = Math.max(0, asIntegerOrNull(item.UserData?.PlaybackPositionTicks) ?? 0);
+  const itemTitle = getItemTitle(item);
+  const seriesTitle = item.Type === 'Episode' ? getSeriesTitle(item) : null;
   const basePlan: JellyfinPlaybackPlan = {
     mode: 'transcode',
     url: '',
     title: getDisplayTitle(item),
+    itemTitle,
+    seriesTitle,
+    seasonNumber: item.Type === 'Episode' ? asIntegerOrNull(item.ParentIndexNumber) : null,
+    episodeNumber: item.Type === 'Episode' ? asIntegerOrNull(item.IndexNumber) : null,
     startTimeTicks,
     audioStreamIndex,
     subtitleStreamIndex,

src/core/services/mpv-control.test.ts

@@ -10,7 +10,7 @@ import {
 
 test('showMpvOsdRuntime sends show-text when connected', () => {
   const commands: (string | number)[][] = [];
-  showMpvOsdRuntime(
+  const shown = showMpvOsdRuntime(
     {
       connected: true,
       send: ({ command }) => {
@@ -19,12 +19,13 @@ test('showMpvOsdRuntime sends show-text when connected', () => {
     },
     'hello',
   );
+  assert.equal(shown, true);
   assert.deepEqual(commands, [['show-text', 'hello', '3000']]);
 });
 
 test('showMpvOsdRuntime enables property expansion for placeholder-based messages', () => {
   const commands: (string | number)[][] = [];
-  showMpvOsdRuntime(
+  const shown = showMpvOsdRuntime(
     {
       connected: true,
       send: ({ command }) => {
@@ -33,6 +34,7 @@ test('showMpvOsdRuntime enables property expansion for placeholder-based message
     },
     'Subtitle delay: ${sub-delay}',
   );
+  assert.equal(shown, true);
   assert.deepEqual(commands, [
     ['expand-properties', 'show-text', 'Subtitle delay: ${sub-delay}', '3000'],
   ]);
@@ -40,7 +42,7 @@ test('showMpvOsdRuntime enables property expansion for placeholder-based message
 
 test('showMpvOsdRuntime logs fallback when disconnected', () => {
   const logs: string[] = [];
-  showMpvOsdRuntime(
+  const shown = showMpvOsdRuntime(
     {
       connected: false,
       send: () => {},
@@ -50,6 +52,7 @@ test('showMpvOsdRuntime logs fallback when disconnected', () => {
       logs.push(line);
     },
   );
+  assert.equal(shown, false);
   assert.deepEqual(logs, ['OSD (MPV not connected): hello']);
 });
 

src/core/services/mpv-protocol.ts

@@ -78,7 +78,7 @@ export interface MpvProtocolHandleMessageDeps {
   setPendingPauseAtSubEnd: (value: boolean) => void;
   getPauseAtTime: () => number | null;
   setPauseAtTime: (value: number | null) => void;
-  autoLoadSecondarySubTrack: () => void;
+  autoLoadSecondarySubTrack: (path: string) => void;
   setCurrentVideoPath: (value: string) => void;
   emitSecondarySubtitleVisibility: (payload: { visible: boolean }) => void;
   setPreviousSecondarySubVisibility: (visible: boolean) => void;
@@ -303,7 +303,7 @@ export async function dispatchMpvProtocolMessage(
       const path = (msg.data as string) || '';
       deps.setCurrentVideoPath(path);
       deps.emitMediaPathChange({ path });
-      deps.autoLoadSecondarySubTrack();
+      deps.autoLoadSecondarySubTrack(path);
       deps.syncCurrentAudioStreamIndex();
     } else if (msg.name === 'sub-pos') {
       deps.emitSubtitleMetricsChange({ subPos: msg.data as number });

src/core/services/mpv.test.ts

@@ -6,7 +6,10 @@ import {
   MpvIpcClientProtocolDeps,
   MPV_REQUEST_ID_SECONDARY_SUB_VISIBILITY,
 } from './mpv';
-import { MPV_REQUEST_ID_TRACK_LIST_AUDIO } from './mpv-protocol';
+import {
+  MPV_REQUEST_ID_TRACK_LIST_AUDIO,
+  MPV_REQUEST_ID_TRACK_LIST_SECONDARY,
+} from './mpv-protocol';
 
 function makeDeps(overrides: Partial<MpvIpcClientProtocolDeps> = {}): MpvIpcClientDeps {
   return {
@@ -93,6 +96,53 @@ test('MpvIpcClient clears cached media title when media path changes', async ()
   assert.equal(client.currentMediaTitle, null);
 });
 
+test('MpvIpcClient skips secondary subtitle autoload when media path is managed', async () => {
+  const commands: unknown[] = [];
+  const originalSetTimeout = globalThis.setTimeout;
+  const client = new MpvIpcClient(
+    '/tmp/mpv.sock',
+    makeDeps({
+      getResolvedConfig: () =>
+        ({
+          secondarySub: {
+            autoLoadSecondarySub: true,
+            secondarySubLanguages: ['en'],
+          },
+        }) as any,
+      shouldAutoLoadSecondarySubTrack: () => false,
+    } as any),
+  );
+  (client as any).send = (command: unknown) => {
+    commands.push(command);
+    return true;
+  };
+  (globalThis as any).setTimeout = (callback: () => void) => {
+    callback();
+    return 0;
+  };
+
+  try {
+    await invokeHandleMessage(client, {
+      event: 'property-change',
+      name: 'path',
+      data: 'http://pve-main:8096/Videos/item/stream',
+    });
+  } finally {
+    globalThis.setTimeout = originalSetTimeout;
+  }
+
+  assert.equal(
+    commands.some(
+      (command) =>
+        Array.isArray((command as { command?: unknown[] }).command) &&
+        (command as { command: unknown[] }).command[0] === 'get_property' &&
+        (command as { command: unknown[] }).command[1] === 'track-list' &&
+        (command as { request_id?: number }).request_id === MPV_REQUEST_ID_TRACK_LIST_SECONDARY,
+    ),
+    false,
+  );
+});
+
 test('MpvIpcClient parses JSON line protocol in processBuffer', () => {
   const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
   const seen: Array<Record<string, unknown>> = [];

src/core/services/mpv.ts

@@ -51,15 +51,16 @@ export function showMpvOsdRuntime(
   mpvClient: MpvRuntimeClientLike | null,
   text: string,
   fallbackLog: (text: string) => void = (line) => logger.info(line),
-): void {
+): boolean {
   if (mpvClient && mpvClient.connected) {
     const command = text.includes('${')
       ? ['expand-properties', 'show-text', text, '3000']
       : ['show-text', text, '3000'];
     mpvClient.send({ command });
-    return;
+    return true;
   }
   fallbackLog(`OSD (MPV not connected): ${text}`);
+  return false;
 }
 
 export function replayCurrentSubtitleRuntime(mpvClient: MpvRuntimeClientLike | null): void {
@@ -105,6 +106,7 @@ export interface MpvIpcClientProtocolDeps {
   isVisibleOverlayVisible: () => boolean;
   getReconnectTimer: () => ReturnType<typeof setTimeout> | null;
   setReconnectTimer: (timer: ReturnType<typeof setTimeout> | null) => void;
+  shouldAutoLoadSecondarySubTrack?: (path: string) => boolean;
   shouldQuitOnMpvShutdown?: () => boolean;
   requestAppQuit?: () => void;
 }
@@ -404,8 +406,8 @@ export class MpvIpcClient implements MpvClient {
       setPauseAtTime: (value: number | null) => {
         this.pauseAtTime = value;
       },
-      autoLoadSecondarySubTrack: () => {
-        this.autoLoadSecondarySubTrack();
+      autoLoadSecondarySubTrack: (path: string) => {
+        this.autoLoadSecondarySubTrack(path);
       },
       setCurrentVideoPath: (value: string) => {
         this.currentVideoPath = value;
@@ -429,7 +431,12 @@ export class MpvIpcClient implements MpvClient {
     };
   }
 
-  private autoLoadSecondarySubTrack(): void {
+  private autoLoadSecondarySubTrack(path: string): void {
+    const normalizedPath = path.trim();
+    if (!normalizedPath) return;
+    if (this.deps.shouldAutoLoadSecondarySubTrack?.(normalizedPath) === false) {
+      return;
+    }
     const config = this.deps.getResolvedConfig();
     if (!config.secondarySub?.autoLoadSecondarySub) return;
     const languages = config.secondarySub.secondarySubLanguages;

src/core/services/overlay-runtime-init.test.ts

@@ -1,6 +1,65 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { initializeOverlayAnkiIntegration, initializeOverlayRuntime } from './overlay-runtime-init';
+import {
+  initializeOverlayAnkiIntegration,
+  initializeOverlayRuntime,
+  startOverlayWindowTracker,
+} from './overlay-runtime-init';
+
+test('startOverlayWindowTracker starts tracker for the current mpv socket', () => {
+  const calls: string[] = [];
+  const tracker = {
+    onGeometryChange: null as ((...args: unknown[]) => void) | null,
+    onWindowFound: null as ((...args: unknown[]) => void) | null,
+    onWindowLost: null as (() => void) | null,
+    onWindowFocusChange: null as ((focused: boolean) => void) | null,
+    isTargetWindowMinimized: () => false,
+    start: () => {
+      calls.push('start');
+    },
+  };
+
+  const result = startOverlayWindowTracker({
+    backendOverride: 'windows',
+    getMpvSocketPath: () => '\\\\.\\pipe\\subminer-socket',
+    createWindowTracker: (override, socketPath) => {
+      calls.push(`create:${override}:${socketPath}`);
+      return tracker as never;
+    },
+    setWindowTracker: (nextTracker) => {
+      calls.push(nextTracker === tracker ? 'set-tracker' : 'clear-tracker');
+    },
+    updateVisibleOverlayBounds: () => {
+      calls.push('bounds');
+    },
+    isVisibleOverlayVisible: () => true,
+    updateVisibleOverlayVisibility: () => {
+      calls.push('visibility');
+    },
+    refreshCurrentSubtitle: () => {
+      calls.push('refresh-subtitle');
+    },
+    getOverlayWindows: () => [],
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+  });
+
+  assert.equal(result, tracker);
+  tracker.onWindowFound?.({ x: 10, y: 20, width: 300, height: 200 });
+  tracker.onWindowFocusChange?.(true);
+
+  assert.deepEqual(calls, [
+    'create:windows:\\\\.\\pipe\\subminer-socket',
+    'set-tracker',
+    'start',
+    'bounds',
+    'visibility',
+    'refresh-subtitle',
+    'visibility',
+    'sync-shortcuts',
+  ]);
+});
 
 test('initializeOverlayRuntime skips Anki integration when ankiConnect.enabled is false', () => {
   let createdIntegrations = 0;

src/core/services/overlay-runtime-init.ts

@@ -25,6 +25,24 @@ type CreateAnkiIntegrationArgs = {
   knownWordCacheStatePath: string;
 };
 
+export type OverlayWindowTrackerOptions = {
+  backendOverride: string | null;
+  getMpvSocketPath: () => string;
+  updateVisibleOverlayBounds: (geometry: WindowGeometry) => void;
+  isVisibleOverlayVisible: () => boolean;
+  updateVisibleOverlayVisibility: () => void;
+  refreshCurrentSubtitle?: () => void;
+  getOverlayWindows: () => BrowserWindow[];
+  syncOverlayShortcuts: () => void;
+  setWindowTracker: (tracker: BaseWindowTracker | null) => void;
+  createWindowTracker?: (
+    override?: string | null,
+    targetMpvSocketPath?: string | null,
+  ) => BaseWindowTracker | null;
+  bindOverlayOwner?: () => void;
+  releaseOverlayOwner?: () => void;
+};
+
 function createDefaultAnkiIntegration(args: CreateAnkiIntegrationArgs): AnkiIntegrationLike {
   const { AnkiIntegration } =
     require('../../anki-integration') as typeof import('../../anki-integration');
@@ -46,82 +64,80 @@ function createDefaultAnkiIntegration(args: CreateAnkiIntegrationArgs): AnkiInte
   );
 }
 
-export function initializeOverlayRuntime(options: {
-  getMpvSocketPath: () => string;
-  getResolvedConfig: () => { ankiConnect?: AnkiConnectConfig; ai?: AiConfig };
-  getSubtitleTimingTracker: () => unknown | null;
-  getMpvClient: () => {
-    send?: (payload: { command: string[] }) => void;
-  } | null;
-  getRuntimeOptionsManager: () => {
-    getEffectiveAnkiConnectConfig: (config?: AnkiConnectConfig) => AnkiConnectConfig;
-  } | null;
-  getAnkiIntegration?: () => unknown | null;
-  setAnkiIntegration: (integration: unknown | null) => void;
-  showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
-  createFieldGroupingCallback: () => (
-    data: KikuFieldGroupingRequestData,
-  ) => Promise<KikuFieldGroupingChoice>;
-  getKnownWordCacheStatePath: () => string;
-  shouldStartAnkiIntegration?: () => boolean;
-  createAnkiIntegration?: (args: CreateAnkiIntegrationArgs) => AnkiIntegrationLike;
-  backendOverride: string | null;
-  createMainWindow: () => void;
-  registerGlobalShortcuts: () => void;
-  updateVisibleOverlayBounds: (geometry: WindowGeometry) => void;
-  isVisibleOverlayVisible: () => boolean;
-  updateVisibleOverlayVisibility: () => void;
-  refreshCurrentSubtitle?: () => void;
-  getOverlayWindows: () => BrowserWindow[];
-  syncOverlayShortcuts: () => void;
-  setWindowTracker: (tracker: BaseWindowTracker | null) => void;
-  createWindowTracker?: (
-    override?: string | null,
-    targetMpvSocketPath?: string | null,
-  ) => BaseWindowTracker | null;
-  bindOverlayOwner?: () => void;
-  releaseOverlayOwner?: () => void;
-}): void {
-  options.createMainWindow();
-  options.registerGlobalShortcuts();
-
+export function startOverlayWindowTracker(
+  options: OverlayWindowTrackerOptions,
+): BaseWindowTracker | null {
   const createWindowTrackerHandler = options.createWindowTracker ?? createWindowTracker;
   const windowTracker = createWindowTrackerHandler(
     options.backendOverride,
     options.getMpvSocketPath(),
   );
   options.setWindowTracker(windowTracker);
-  if (windowTracker) {
-    windowTracker.onGeometryChange = (geometry: WindowGeometry) => {
-      options.updateVisibleOverlayBounds(geometry);
-    };
-    windowTracker.onWindowFound = (geometry: WindowGeometry) => {
-      options.updateVisibleOverlayBounds(geometry);
-      options.bindOverlayOwner?.();
-      if (options.isVisibleOverlayVisible()) {
-        options.updateVisibleOverlayVisibility();
-        options.refreshCurrentSubtitle?.();
-      }
-    };
-    windowTracker.onWindowLost = () => {
-      options.releaseOverlayOwner?.();
-      if (windowTracker.isTargetWindowMinimized()) {
-        for (const window of options.getOverlayWindows()) {
-          window.hide();
-        }
-        options.syncOverlayShortcuts();
-        return;
-      }
+  if (!windowTracker) {
+    return null;
+  }
+
+  windowTracker.onGeometryChange = (geometry: WindowGeometry) => {
+    options.updateVisibleOverlayBounds(geometry);
+  };
+  windowTracker.onWindowFound = (geometry: WindowGeometry) => {
+    options.updateVisibleOverlayBounds(geometry);
+    options.bindOverlayOwner?.();
+    if (options.isVisibleOverlayVisible()) {
       options.updateVisibleOverlayVisibility();
-    };
-    windowTracker.onWindowFocusChange = () => {
-      if (options.isVisibleOverlayVisible()) {
-        options.updateVisibleOverlayVisibility();
+      options.refreshCurrentSubtitle?.();
+    }
+  };
+  windowTracker.onWindowLost = () => {
+    options.releaseOverlayOwner?.();
+    if (windowTracker.isTargetWindowMinimized()) {
+      for (const window of options.getOverlayWindows()) {
+        window.hide();
       }
       options.syncOverlayShortcuts();
-    };
-    windowTracker.start();
-  }
+      return;
+    }
+    options.updateVisibleOverlayVisibility();
+  };
+  windowTracker.onWindowFocusChange = () => {
+    if (options.isVisibleOverlayVisible()) {
+      options.updateVisibleOverlayVisibility();
+    }
+    options.syncOverlayShortcuts();
+  };
+  windowTracker.start();
+  return windowTracker;
+}
+
+export function initializeOverlayRuntime(
+  options: OverlayWindowTrackerOptions & {
+    getMpvSocketPath: () => string;
+    getResolvedConfig: () => { ankiConnect?: AnkiConnectConfig; ai?: AiConfig };
+    getSubtitleTimingTracker: () => unknown | null;
+    getMpvClient: () => {
+      send?: (payload: { command: string[] }) => void;
+    } | null;
+    getRuntimeOptionsManager: () => {
+      getEffectiveAnkiConnectConfig: (config?: AnkiConnectConfig) => AnkiConnectConfig;
+    } | null;
+    getAnkiIntegration?: () => unknown | null;
+    setAnkiIntegration: (integration: unknown | null) => void;
+    showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
+    createFieldGroupingCallback: () => (
+      data: KikuFieldGroupingRequestData,
+    ) => Promise<KikuFieldGroupingChoice>;
+    getKnownWordCacheStatePath: () => string;
+    shouldStartAnkiIntegration?: () => boolean;
+    createAnkiIntegration?: (args: CreateAnkiIntegrationArgs) => AnkiIntegrationLike;
+    backendOverride: string | null;
+    createMainWindow: () => void;
+    registerGlobalShortcuts: () => void;
+  },
+): void {
+  options.createMainWindow();
+  options.registerGlobalShortcuts();
+
+  startOverlayWindowTracker(options);
 
   initializeOverlayAnkiIntegration(options);
 

src/core/services/overlay-visibility.test.ts

@@ -197,6 +197,68 @@ test('tracked non-macOS overlay stays hidden while tracker is not ready', () =>
   assert.ok(!calls.includes('osd'));
 });
 
+test('non-native passive overlay stays click-through after subsequent visibility updates', () => {
+  const { window, calls } = createMainWindowRecorder();
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: false,
+    isWindowsPlatform: false,
+    overlayInteractionActive: false,
+    showOverlayLoadingOsd: () => {},
+    resolveFallbackBounds: () => ({ x: 12, y: 24, width: 640, height: 360 }),
+  } as never);
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: false,
+    isWindowsPlatform: false,
+    overlayInteractionActive: false,
+    showOverlayLoadingOsd: () => {},
+    resolveFallbackBounds: () => ({ x: 12, y: 24, width: 640, height: 360 }),
+  } as never);
+
+  assert.equal(calls.includes('mouse-ignore:false:plain'), false);
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+});
+
 test('suspended visible overlay hides without refreshing bounds or z-order', () => {
   const { window, calls } = createMainWindowRecorder();
   const tracker: WindowTrackerStub = {
@@ -244,7 +306,7 @@ test('suspended visible overlay hides without refreshing bounds or z-order', ()
   assert.ok(!calls.includes('focus'));
 });
 
-test('untracked non-macOS overlay keeps fallback visible behavior when no tracker exists', () => {
+test('untracked non-macOS overlay shows passively when no tracker exists', () => {
   const { window, calls } = createMainWindowRecorder();
   let trackerWarning = false;
 
@@ -279,11 +341,49 @@ test('untracked non-macOS overlay keeps fallback visible behavior when no tracke
   } as never);
 
   assert.equal(trackerWarning, false);
-  assert.ok(calls.includes('show'));
-  assert.ok(calls.includes('focus'));
+  assert.ok(calls.includes('show-inactive'));
+  assert.ok(!calls.includes('show'));
+  assert.ok(!calls.includes('focus'));
   assert.ok(!calls.includes('osd'));
 });
 
+test('passive Linux visible overlay does not take keyboard focus', () => {
+  const { window, calls } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+  };
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: false,
+    isWindowsPlatform: false,
+  } as never);
+
+  assert.ok(calls.includes('show-inactive'));
+  assert.ok(!calls.includes('show'));
+  assert.ok(!calls.includes('focus'));
+});
+
 test('tracked non-macOS overlay reapplies bounds after first show', () => {
   const { window, calls } = createMainWindowRecorder();
   const tracker: WindowTrackerStub = {
@@ -317,8 +417,8 @@ test('tracked non-macOS overlay reapplies bounds after first show', () => {
   } as never);
 
   assert.deepEqual(
-    calls.filter((call) => call === 'update-bounds' || call === 'show'),
-    ['update-bounds', 'show', 'update-bounds'],
+    calls.filter((call) => call === 'update-bounds' || call === 'show-inactive'),
+    ['update-bounds', 'show-inactive', 'update-bounds'],
   );
 });
 
@@ -1260,6 +1360,54 @@ test('macOS tracked overlay hides when mpv loses foreground', () => {
   assert.ok(!calls.includes('show'));
 });
 
+test('macOS keeps visible overlay stable while probing frontmost app after overlay blur', () => {
+  const { window, calls } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => false,
+    isTargetWindowMinimized: () => false,
+  };
+
+  window.show();
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    isWindowsPlatform: false,
+    macOSForegroundProbeActive: true,
+  } as never);
+
+  assert.ok(calls.includes('update-bounds'));
+  assert.ok(calls.includes('sync-layer'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(calls.includes('enforce-order'));
+  assert.ok(calls.includes('sync-shortcuts'));
+  assert.ok(!calls.includes('always-on-top:false'));
+  assert.ok(!calls.includes('hide'));
+});
+
 test('macOS keeps tracked overlay visible while overlay interaction is active after mpv loses foreground', () => {
   const { window, calls, setFocused } = createMainWindowRecorder();
   const tracker: WindowTrackerStub = {

src/core/services/overlay-visibility.ts

@@ -71,6 +71,7 @@ export function updateVisibleOverlayVisibility(args: {
   lastKnownWindowsForegroundProcessName?: string | null;
   windowsOverlayProcessName?: string | null;
   windowsFocusHandoffGraceActive?: boolean;
+  macOSForegroundProbeActive?: boolean;
   trackerNotReadyWarningShown: boolean;
   setTrackerNotReadyWarningShown: (shown: boolean) => void;
   updateVisibleOverlayBounds: (geometry: WindowGeometry) => void;
@@ -128,6 +129,12 @@ export function updateVisibleOverlayVisibility(args: {
     const isTrackedMacOSTargetMinimized =
       canReportMacOSTargetMinimized && windowTracker?.isTargetWindowMinimized() === true;
     const trackedMacOSTargetFocused = args.windowTracker?.isTargetWindowFocused?.();
+    const shouldPreserveMacOSOverlayDuringForegroundProbe =
+      args.isMacOSPlatform &&
+      args.macOSForegroundProbeActive === true &&
+      !!windowTracker &&
+      !isTrackedMacOSTargetMinimized &&
+      (windowTracker.isTracking() || windowTracker.getGeometry() !== null);
     const hasTransientMacOSTrackerLoss =
       args.isMacOSPlatform &&
       canReportMacOSTargetMinimized &&
@@ -137,7 +144,10 @@ export function updateVisibleOverlayVisibility(args: {
       trackedMacOSTargetFocused !== false &&
       mainWindow.isVisible();
     const isTrackedMacOSTargetFocused =
-      hasTransientMacOSTrackerLoss || !args.isMacOSPlatform || !args.windowTracker
+      hasTransientMacOSTrackerLoss ||
+      shouldPreserveMacOSOverlayDuringForegroundProbe ||
+      !args.isMacOSPlatform ||
+      !args.windowTracker
         ? true
         : (trackedMacOSTargetFocused ?? true);
     const shouldReleaseMacOSOverlayLevel =
@@ -171,9 +181,12 @@ export function updateVisibleOverlayVisibility(args: {
       !isTrackedWindowsTargetMinimized &&
       (args.windowTracker.isTracking() || args.windowTracker.getGeometry() !== null);
     const shouldForcePassiveReshow = args.isWindowsPlatform && !wasVisible;
+    const isNonNativePassiveOverlay =
+      !args.isWindowsPlatform && !args.isMacOSPlatform && !overlayInteractionActive;
     const shouldIgnoreMouseEvents =
       shouldUseMacOSMousePassthrough ||
       forceMousePassthrough ||
+      isNonNativePassiveOverlay ||
       (shouldDefaultToPassthrough && (!isVisibleOverlayFocused || shouldForcePassiveReshow));
     const shouldBindTrackedWindowsOverlay = args.isWindowsPlatform && !!args.windowTracker;
     const shouldKeepTrackedWindowsOverlayTopmost =
@@ -217,7 +230,10 @@ export function updateVisibleOverlayVisibility(args: {
         // skip — ready-to-show hasn't fired yet; the onWindowContentReady
         // callback will trigger another visibility update when the renderer
         // has painted its first frame.
-      } else if ((args.isWindowsPlatform || args.isMacOSPlatform) && shouldIgnoreMouseEvents) {
+      } else if (
+        ((args.isWindowsPlatform || args.isMacOSPlatform) && shouldIgnoreMouseEvents) ||
+        isNonNativePassiveOverlay
+      ) {
         if (args.isWindowsPlatform) {
           setOverlayWindowOpacity(mainWindow, 0);
         }
@@ -261,7 +277,12 @@ export function updateVisibleOverlayVisibility(args: {
       mainWindow.focus();
     }
 
-    if (!args.isWindowsPlatform && !args.isMacOSPlatform && !forceMousePassthrough) {
+    if (
+      !args.isWindowsPlatform &&
+      !args.isMacOSPlatform &&
+      !forceMousePassthrough &&
+      overlayInteractionActive
+    ) {
       mainWindow.focus();
     }
 

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

@@ -0,0 +1,29 @@
+export type StatsWindowLayerSuspensionState = {
+  count: number;
+};
+
+export function createStatsWindowLayerSuspensionState(): StatsWindowLayerSuspensionState {
+  return { count: 0 };
+}
+
+export function isStatsWindowLayerSuspended(state: StatsWindowLayerSuspensionState): boolean {
+  return state.count > 0;
+}
+
+export function suspendStatsWindowLayer(state: StatsWindowLayerSuspensionState): boolean {
+  state.count += 1;
+  return state.count === 1;
+}
+
+export function restoreStatsWindowLayer(state: StatsWindowLayerSuspensionState): boolean {
+  if (state.count <= 0) {
+    return false;
+  }
+
+  state.count -= 1;
+  return state.count === 0;
+}
+
+export function resetStatsWindowLayerSuspension(state: StatsWindowLayerSuspensionState): void {
+  state.count = 0;
+}