chore(release): 0.15.0

docs: reconcile docs-site with current config schema and defaults
- sidebar: migrate flat props to css object (font-family, color, bg, custom vars) - frequencyDictionary.topX default: 1000 → 10000 - text-shadow default: updated to outline-style multi-shadow - anki: reset ai model/prompt, imageMaxWidth/Height, animatedMaxHeight to 0; isLapis defaults - troubleshooting: log default warn (not info), css["font-size"] usage - shortcuts: add W markWatchedKey; clarify keybindings vs built-in overlay actions - websocket: clarify all services off by default, fix enabled semantics - usage: --anilist → --anilist-setup - AGENTS.md: add Docs Upkeep trigger map, clarify CLAUDE.md symlink, expand PR notes
2026-05-29 12:55:16 -07:00 · 2026-05-28 19:46:05 -07:00 · 2026-05-28 19:21:58 -07:00 · 2026-05-28 02:16:55 -07:00 · 2026-05-28 02:08:44 -07:00 · 2026-05-28 00:50:41 -07:00
494 changed files with 19613 additions and 2848 deletions
@@ -13,6 +13,8 @@ Start here, then leave this file.

 `docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.

+`CLAUDE.md` is a symlink to this file — there is one project instruction file, not two.
+
 ## Quick Start

 - Init workspace: `git submodule update --init --recursive`
@@ -42,6 +44,20 @@ Start here, then leave this file.
 - Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
 - Docs-only: `bun run docs:test`, then `bun run docs:build`

+## Docs Upkeep
+
+- Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
+- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it — and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
+- Trigger map (touch left → update right):
+  - `src/config/definitions/**` (schema/defaults/template) → `bun run generate:config-example`, then reconcile `docs-site/configuration.md` + any feature doc that cites that default
+  - shortcuts/keybindings (`shortcuts.*`, `keybindings`, `stats.*Key`, `subtitleSidebar.toggleKey`, controller bindings) → `docs-site/shortcuts.md`
+  - CLI flags/subcommands (`src/cli/args.ts`, `launcher/**`) → `docs-site/usage.md` + relevant integration doc
+  - feature behavior (anki / jellyfin / jimaku / anilist / youtube / immersion / stats / websocket / sidebar / character-dictionary / annotations) → matching `docs-site/<feature>.md`
+  - architecture / IPC / workflow / internal process → internal `docs/` (system of record)
+  - feature set / requirements / install flow → `README.md`
+- Removing or renaming a config key: grep `docs-site/` and `docs/` for the old key and any value it documented; legacy/hidden keys (`LEGACY_HIDDEN_CONFIG_PATHS`) should not appear in user docs as current settings.
+- Verify after doc edits: `bun run verify:config-example` (if config touched), `bun run docs:test`, `bun run docs:build`.
+
 ## Sensitive Files

 - Launcher source of truth: `launcher/*.ts`
@@ -52,7 +68,8 @@ Start here, then leave this file.

 ## Release / PR Notes

- User-visible PRs need one fragment in `changes/*.md`
+- User-visible PRs need one fragment in `changes/*.md` — format and rules in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; apply the `skip-changelog` label to opt out)
+- User-visible docs changes get a `type: docs` fragment
 - CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
 - PR review helpers:
  - `gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'`
@@ -63,4 +80,4 @@ Start here, then leave this file.
 - Use Codex background for long jobs; tmux only when persistence/interaction is required
 - CI red: `gh run list/view`, rerun, fix, repeat until green
 - TypeScript: keep files small; follow existing patterns
- Swift: use workspace helper/daemon; validate `swift build` + tests
+- Only Swift is the `scripts/get-mpv-window-macos.swift` helper (macOS mpv window detection); validate via `bun test scripts/get-mpv-window-macos.test.ts`
@@ -1,5 +1,74 @@
 # Changelog

+## v0.15.0 (2026-05-29)
+
+### Breaking Changes
+
+- Subsync: The `subsync.defaultMode` config option has been removed; Subsync now always opens the manual subtitle picker regardless of any previously set default mode.
+
+### Added
+
+- Auto-Updater: Adds tray and `subminer -u` update checks with app update prompts, launcher and Linux rofi theme auto-updates, checksum verification, configurable notifications, and an opt-in prerelease channel via `updates.channel: "prerelease"`.
+- Settings Window: New dedicated Settings window via `subminer --settings` or `subminer settings`, organized into Appearance, Behavior, Anki, Input, and Integration sections; click-to-learn keybinding controls including the AniSkip button key; AnkiConnect-backed deck, field, and note-type pickers that auto-fill from the configured Anki deck; cross-category search; and live save for most options including subtitle CSS, stats keys, logging level, Jimaku, Subsync, and Anki mappings. AI and translation settings remain config-file only.
+- Inline Character Portraits: Optional AniList character portraits appear inline for name-matched subtitle text; manual AniList overrides scoped per parent media directory so separate season folders maintain separate character dictionary selections.
+- Log Export: Sanitized log ZIP export from the tray menu and via `subminer logs -e`, with home-directory usernames redacted from exported contents.
+- Launcher CLI: `subminer --version` / `subminer -v` prints the installed app version; `mpv.profile` config and Settings support passes a named mpv profile to managed launches; bundled mpv plugin startup options are now configurable from SubMiner config.
+- First-Run Setup: Optional installer for Bun and the `subminer` CLI on Linux, macOS, and Windows, including a Windows `subminer.cmd` PATH shim so `subminer` works without manually adding `SubMiner.exe` to PATH; setup recognizes existing Homebrew or user PATH installs and avoids writing into Homebrew-owned paths; includes an Open SubMiner Settings button; standalone setup app quits after completing, returning terminal control.
+- Primary Subtitle Visibility on Yomitan Popup: New `subtitleStyle.primaryVisibleOnYomitanPopup` option keeps hover-mode primary subtitles visible while a Yomitan popup is open.
+
+### Changed
+
+- Subtitle Appearance Config: Primary and secondary subtitle appearance now use color controls plus CSS declaration editors, saved as `subtitleStyle.css`, `subtitleStyle.secondary.css`, and `subtitleSidebar.css`; known-word and N+1 annotation colors moved to `subtitleStyle.knownWordColor` and `subtitleStyle.nPlusOneColor`; subtitle font defaults updated to `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP`. Existing configs migrate automatically; legacy Anki color keys still accepted with deprecation warnings.
+- Subtitle Style Defaults: Stronger outline-style text shadow, thicker JLPT underlines, and frequency `topX` default raised to `10000`.
+- Character Dictionary: Entries scoped to the current AniList media for name matching and inline portraits; generates Japanese-only name aliases so raw romanized/English aliases no longer surface as separate results; new `Ctrl/Cmd+D` manager modal to remove, reorder, or override loaded entries; in-app AniList selector waits for an explicit search with the box prefilled from the current filename; `subtitleStyle.nameMatchEnabled` is now the sole switch for dictionary sync and builds.
+- Electron Runtime: Updated from 39.8.6 to 42.2.0, returning SubMiner to a supported Electron release line.
+- N+1 Highlighting Default: `ankiConnect.nPlusOne.enabled` is no longer implicitly enabled when known-word highlighting is on; existing configs that already had N+1 enabled are unchanged, but new configs must set it explicitly.
+- Linux Auto-Update Flow: Linux tray "Check for Updates" now installs the new AppImage automatically, matching macOS and Windows; AppImages managed by a system package (e.g. AUR) and non-AppImage launches still use the GitHub-asset flow.
+- Jellyfin Setup: Removed the server presets dropdown; setup now shows a single editable server URL field.
+- Jellyfin Cast Identity: Device identity now derived from the OS hostname and always reported as SubMiner; previously configurable identity fields are ignored, preventing multiple installs from sharing a remote-session identity.
+- Startup Defaults: Jellyfin remote-session startup warmup and character-name subtitle highlighting now default to off.
+- Setup Appearance: Removed the bundled mpv runtime plugin readiness card from the setup flow.
+
+### Fixed
+
+- AniList Progress: Progress updates fire correctly when playback reaches or skips past the watched threshold using fresh mpv timing events; season-specific results preferred for multi-season files with a clear message when the matched season is not in Planning or Watching; repeated missing-token checks no longer exhaust retry attempts or duplicate dead-letter entries.
+- Anki Mining: Sentence-audio padding is opt-in by default; animated AVIF freeze-frame duration aligned to word audio length without double-counting; multi-line sentence alignment fixed for repeated subtitle text; Kiku duplicate-card detection, auto-merge, modal acknowledgment race, and field/tag ordering corrected; YouTube playback cards use mpv's resolved stream URLs; sentence cards refresh the secondary subtitle before saving; known-word cache appends correctly with multiple deck field mappings.
+- Jellyfin Discovery: Startup, subtitle track selection, and duplicate ready-signal handling all fixed; paused mpv no longer misreported as playing; startup unpause no longer repeats after a manual pause or `y-t` toggle; delayed Japanese subtitle selection, later-loading foreign track hijacking, and long-lived sidebar ffmpeg extractor leaks fixed; resume corrected when a remote play command sends `StartPositionTicks: 0` despite saved progress; picker library discovery kept working regardless of app log level.
+- Jellyfin Remote: Tray checkbox stays in sync on Linux after tray, CLI, or startup changes; stale discovery sessions restarted when the server no longer lists the SubMiner cast target; remote controller visibility and progress sync fixed for seeks, stops, startup path changes, and Linux websocket reconnect windows; Play and Resume now behave correctly (Play from beginning, Resume from saved position); final progress reports reuse SubMiner's last known position when mpv resets on stop; Windows setup login flow fixed with an IPC bridge, immediate feedback, and a timeout with inline error for unreachable servers.
+- Jellyfin Subtitles and Overlay: Subtitle overlay shown automatically during Jellyfin playback; `y-t` toggle made reliable and sticky across stream redirects; managed subtitle defaults re-armed on redirect; passive Linux/Hyprland overlay shows no longer steal keyboard focus from mpv; subtitle timing improved with preferred embedded streams over external sidecars, correct Japanese-vs-English cue offset handling, per-stream delay shift restoration, and transient track-list read failure tolerance.
+- Overlay (macOS): Overlay hides when mpv loses focus, is minimized, or is no longer the foreground app; stable through transient window geometry disappearances from macOS APIs and when clicking from the overlay back into mpv; stats overlay opened inactive so it appears over fullscreen mpv without switching Spaces; passthrough fixed so mpv controls stay clickable before hovering a subtitle bar; window-tracker polling reduced while mpv is stably focused.
+- Overlay (Linux / Hyprland): Placement refreshes after leaving fullscreen; overlay stays above mpv after focus changes from clicks or movement; Settings and Yomitan windows promoted above the subtitle overlay instead of opening behind it; overlay hides when the character dictionary modal opens, including during AniList lookup.
+- Overlay Lifecycle: First startup subtitle primed before autoplay resumes so the overlay renders text before playback begins; overlay and subtitle stream kept alive after `y-r` restart with correct Linux bounds reapplication; launcher-owned playback quits SubMiner on end while background/tray sessions stay alive; subtitle sync modal fixed on macOS so it no longer flashes on first attempt or leaves stale state; Windows managed mpv launches from a background instance now correctly receive the start command, retarget the new socket, bind to the player window, and receive startup overlay options.
+- Yomitan Sidebar: Playback stays paused for sidebar-opened Yomitan popups when auto-pause is enabled; fixed popups not opening when startup races the Yomitan extension load; sidebar mining cards use audio and images from the clicked sidebar line instead of the current primary subtitle.
+- Launcher: Warm launches reuse a running background instance, reapply preferred subtitles, and close launcher-owned tray apps after playback ends; videos stay paused until subtitle priming and tokenization readiness complete; `subminer settings` on macOS exits cleanly when the window is closed; `subminer app` on Linux returns terminal control immediately; Linux first-run installs build with a valid Bun shebang; `subminer app --setup` opens the setup flow when SubMiner is already running in background.
+- YouTube Playback: Selected subtitles downloaded to local temp files so the primary bar and sidebar read the same source, with cleanup on reload and quit; false load-failure notifications suppressed; tray icon created on launcher-managed playback that attaches to an already-running process; mpv plugin no longer starts a second SubMiner instance for app-owned YouTube playback.
+- Shortcuts: Native mpv menu shortcuts disabled during managed macOS playback so configured SubMiner shortcuts work while mpv has focus; custom session shortcuts including `stats.markWatchedKey` wired through mpv; multi-line copy/mine overlay correctly focused so number keys choose the line count on macOS and Windows.
+- Controller Bindings: Controller config and debug shortcuts stay closed while controller support is disabled; binding learn mode starts from the edit pencil; remaps saved per controller profile; binding badges also start learn mode; row reset buttons restore individual bindings to defaults.
+- Logging: `logging.level` forwarded to launcher-started and Windows shortcut-started mpv sessions covering mpv log verbosity, plugin logging, and plugin-launched app logging; `logging.rotation` (default 7 days) and per-component `logging.files` toggles added with mpv logs disabled by default; repeated IPC socket warning spam suppressed while waiting for mpv to recreate the socket; Windows mpv IPC, subtitle track, and Yomitan diagnostics added.
+- Updater: Linux `subminer -u` performs release updates independently of any running tray app using GitHub release metadata; macOS update dialogs from `subminer -u` reliably appear in the foreground with a manual-install message for builds that cannot apply native updates; macOS and Linux `electron-updater` routes through `/usr/bin/curl` to avoid Electron network crashes; Windows automatic updates keep the native NSIS install path while routing updater HTTP through main-process fetch to avoid delayed exit after launch.
+- In-Player Stats: Layering fixed so delete confirmations, overlay modals, and update-check dialogs appear above the stats window; Jellyfin playback stats grouped by item metadata so watched episodes merge with matching local library titles and keep clean display names.
+- Tray: Tray stays running when Yomitan settings are closed; settings loading no longer blocks other tray actions; Yomitan extension refreshes serialized at startup; embedded popup preview disabled to prevent renderer hangs during sidebar navigation; Windows "Open SubMiner Setup" action opens the setup window correctly after first-run is complete; session help modal close fixed without mpv running.
+- Discord Rich Presence: No longer falls back to Jellyfin stream URLs; Jellyfin playback titles primed before stream loading so presence shows the show/episode title instead of a URL.
+- WebSocket Annotations: Annotation spans and token metadata stay on the annotation WebSocket; the regular subtitle WebSocket is plain-text only.
+- Subtitle Frequency Highlighting: Frequency annotations kept for determiner-led noun compounds like `その場` while still filtering standalone determiners; fixed for Yomitan single-token compounds with internal particles such as `目の前` while keeping pure grammar/kana helper spans unannotated.
+- Subtitle Annotation Prefetching: Cached colored annotations and character images ready sooner for live subtitle changes without delaying raw subtitle display.
+- Packaging: macOS compiled mpv window helper correctly built into `dist/scripts` and bundled, preventing fallback to slow Swift source startup; stale Windows helper resource entry removed; one-shot `make clean build install` AppImage flows fixed so install picks up the AppImage built earlier in the same invocation.
+- Windows Startup Errors: Fatal startup failures now show a native error dialog and write details to the app log instead of exiting silently.
+
+### Docs
+
+- Documentation Site: Published stable docs at the site root with current development docs under `/main/`; fixed versioned docs navigation, archived page link handling, and local dev version routing; documented all previously undocumented config options including `subtitleStyle.primaryDefaultMode`, `stats.markWatchedKey`, `immersionTracking.lifetimeSummaries.*`, and all seven `mpv.*` launcher options; added Playback Startup Flow and Runtime Sockets diagrams to the architecture docs with cross-reference pointers in the MPV Plugin and Troubleshooting pages.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+
+- Release Tooling: Release-note polishing treats pending fragments and reviewed prerelease notes as a cumulative final outcome, collapsing prerelease-only fixes into the final user-facing change; prerelease generation reuses existing reviewed notes and merges only new fragment material; `make clean` preserves `release/prerelease-notes.md`.
+- Tests: Removed stale Yomitan vendor source-inspection assertions for changes that were not shipped.
+
+</details>
+
 ## v0.14.0 (2026-05-12)

 ### Added
@@ -1,4 +0,0 @@
-type: fixed
-area: jellyfin
-
- Fixed the Jellyfin setup popup login path on Windows by using an IPC bridge, showing immediate login progress, and timing out unreachable server login attempts with an inline error.
@@ -34,11 +34,14 @@ 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.
+- GitHub release notes and prerelease notes use short top-level items with nested bullets for the change, user benefit, and any useful action note. The stable `CHANGELOG.md` can stay in compact single-line bullets.
 - `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
@@ -1,5 +0,0 @@
-type: fixed
-area: anki
-
- Made sentence-audio padding opt-in by default, and kept animated AVIF motion aligned when padding is configured by freezing the first frame during leading audio padding.
- Kept multi-line sentence mining aligned when repeated subtitle text appears in the selected history range.
@@ -1,4 +0,0 @@
-type: changed
-area: config
-
- Settings: Changed the AniSkip button key setting to use click-to-learn key capture instead of raw text entry.
@@ -1,4 +0,0 @@
-type: added
-area: updater
-
- Added tray and `subminer -u` update checks for SubMiner releases, including app update prompts, launcher updates, Linux rofi theme updates, checksum verification, configurable update notifications, and an opt-in prerelease update channel for beta/RC testing.
@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
- Reused an already-running background SubMiner app for launcher-opened videos, closed launcher-owned tray apps after playback ends, and reapplied preferred subtitles for warm launches.
@@ -1,4 +0,0 @@
-type: fixed
-area: character-dictionary
-
- Reused cached character-dictionary media matches so loading a title with an existing snapshot no longer sends another AniList search request.
@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
- Updated the generated example config to use the same CSS declaration paths written by the Settings window for subtitle and sidebar appearance.
@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
- Preserved user config files during legacy config compatibility handling.
@@ -1,4 +0,0 @@
-type: changed
-area: config
-
- Reorganized the Settings window into clearer Appearance, Behavior, Anki, input, and integration sections with learned keybinding controls and AnkiConnect-backed deck, field, and note-type pickers.
@@ -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.
@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
- Fixed Settings window search so it searches across all categories, narrows on multi-word terms, hides settings owned by richer editors, and no longer shows the Open File button.
@@ -1,8 +0,0 @@
-type: added
-area: config
-
- Added a dedicated Settings window with launcher entry points via `subminer --settings` and `subminer settings`.
- Fixed the Settings window preload so launcher-opened windows can initialize even when Electron sandboxing is active.
- Kept settings-window startup lightweight by skipping AniList token refresh and automatic update polling.
- Marked safe live config options in the Settings window and expanded hot reload for stats keys, logging level, Jimaku, Subsync, YouTube language defaults, Anki media/sentence/misc field mappings, sentence card model, and selected Anki annotation/runtime options.
- Hid AI and translation fields from the Settings window while keeping them supported in config files.
@@ -1,6 +0,0 @@
-type: fixed
-area: overlay
-
- Controller config and debug shortcuts now stay closed while controller support is disabled and show a notice to enable `controller.enabled` manually.
- Controller binding rows now start learn mode from the edit pencil, so clicking edit and pressing a controller button saves the remap.
- Controller remaps are now saved per controller profile, binding badges also start learn mode, and row reset buttons restore individual bindings to their defaults.
@@ -1,4 +0,0 @@
-type: changed
-area: config
-
- Defaulted Jellyfin remote-session startup warmup and character-name subtitle highlighting to off.
@@ -1,4 +0,0 @@
-type: docs
-area: docs
-
- Published stable docs at the site root with current development docs under `/main/`.
@@ -1,4 +0,0 @@
-type: changed
-area: runtime
-
- Updated the bundled Electron runtime from 39.8.6 to 42.2.0, moving SubMiner back onto a supported Electron release line.
@@ -1,5 +0,0 @@
-type: added
-area: setup
-
- Added optional first-run setup controls to install Bun and the `subminer` command-line launcher on Linux, macOS, and Windows.
- Added a Windows `subminer.cmd` user PATH shim so users can type `subminer` without adding `SubMiner.exe` to PATH.
@@ -1,6 +0,0 @@
-type: fixed
-area: anilist
-
- Used fresh mpv time-position, duration, and subtitle timing events for AniList post-watch threshold checks so progress updates still fire when playback reaches or skips past the watched threshold.
- Prefer season-specific AniList search results for multi-season files before falling back to the base title.
- Show a clear AniList message when the matched season is not in Planning or Watching instead of silently queueing an impossible progress update.
@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
- Fixed animated AVIF word-audio sync so the frozen lead-in matches the word audio duration without adding sentence audio padding a second time.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Primed the first startup subtitle before autoplay resumes so the overlay can render text before video playback begins.
@@ -1,5 +0,0 @@
-type: fixed
-area: launcher
-
- Kept launcher-opened videos paused when attaching to an already-running background app until subtitle priming and tokenization readiness complete.
- Moved mpv plugin subtitle auto-selection to pre-load so launch-time subtitle choices are not reset after the video opens.
@@ -1,4 +0,0 @@
-type: fixed
-area: subtitles
-
- Kept frequency highlighting for determiner-led noun compounds like `その場` while still filtering standalone determiners.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Refreshed Linux overlay placement after leaving mpv fullscreen so Hyprland keeps the visible overlay aligned to the player.
@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
- Kept the Hyprland visible overlay stacked above mpv after mpv receives focus from clicks or overlay movement.
- Suspended the visible overlay while the in-player stats window is open, then restored it mouse-passive after stats closes.
@@ -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.
@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
- Suppressed Electron macOS menu diagnostics from `subminer settings` launcher output.
@@ -1,4 +0,0 @@
-type: fixed
-area: shortcuts
-
- Disabled native mpv menu shortcuts during managed macOS playback so configured SubMiner shortcuts also work while mpv has focus.
@@ -1,10 +0,0 @@
-type: fixed
-area: overlay
-
- Hid the macOS visible overlay when mpv is no longer the foreground target so other apps and Spaces are not covered by SubMiner subtitles.
- Kept the macOS overlay layered above active mpv while stats mouse passthrough is enabled, and treated the frontmost mpv app as the focus signal.
- Opened the stats overlay inactive on macOS so it appears over fullscreen mpv instead of switching back to SubMiner's original desktop.
- Preserved the active mpv focus state through transient macOS helper misses so subtitles do not flicker while mpv remains foreground.
- Kept fullscreen macOS overlays stable when mpv remains frontmost but window geometry temporarily disappears from the macOS window APIs.
- Released the macOS overlay when the helper reports mpv is no longer foreground so other apps are no longer covered.
- Reduced macOS window-tracker background work by preferring the compiled helper and slowing polls while mpv is stably focused.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed macOS overlay tracking so transient mpv window misses no longer hide the overlay; minimizing mpv still hides it.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed macOS overlay passthrough so mpv controls remain clickable before hovering subtitle bars.
@@ -1,4 +0,0 @@
-type: fixed
-area: playback
-
- Fixed managed mpv startup so launcher-owned videos quit SubMiner when playback ends, background/tray sessions stay alive, and pause-until-ready waits for the overlay and tokenization readiness before playback resumes.
@@ -1,4 +0,0 @@
-type: fixed
-area: shortcuts
-
- Focus the visible overlay when entering multi-line copy/mine selection so number keys choose the line count on macOS and Windows.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed subtitle sync modal opens so macOS no longer flashes and hides the first modal attempt or leaves stale modal state after syncing.
@@ -1,4 +0,0 @@
-type: fixed
-area: docs
-
- Fixed versioned docs navigation so archived pages keep local links under the selected version, the version switcher no longer nests targets under the current archive path, local dev version routes serve warmed archive files instead of redirecting to production or falling through to VitePress 404s, and internal README files do not break archived builds.
@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
- Fixed manual clipboard card updates from YouTube playback so generated audio and images use mpv's resolved stream URLs instead of the YouTube page URL.
@@ -1,4 +0,0 @@
-type: fixed
-area: youtube
-
- Downloaded selected YouTube primary subtitles to temporary local files so the primary bar and sidebar read the same subtitle source, with temp-file cleanup on reload and quit. Suppressed stale failure notifications by re-checking live mpv subtitle state before reporting primary subtitle load failures.
@@ -1,4 +0,0 @@
-type: changed
-area: setup
-
- Setup: Removed the bundled mpv runtime plugin readiness card; legacy mpv plugin removal still appears when needed.
@@ -1,4 +0,0 @@
-type: changed
-area: config
-
- Config: Moved known-word and N+1 annotation colors to `subtitleStyle.knownWordColor` and `subtitleStyle.nPlusOneColor`; legacy Anki color keys are still accepted with warnings.
@@ -1,4 +0,0 @@
-type: added
-area: launcher
-
- Added `subminer --version` and `subminer -v` to print the installed SubMiner app version.
@@ -1,5 +0,0 @@
-type: fixed
-area: updater
-
- Made Linux `subminer -u` perform release updates from the launcher, independent of any running tray app instance, while reporting `up to date` without downloading assets when the latest release is not newer.
- Limited support asset updates to the Linux rofi theme.
@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
- Fixed Linux first-run launcher installs by building the packaged launcher with a valid Bun shebang.
@@ -1,5 +0,0 @@
-type: changed
-area: updater
-
- Linux tray "Check for Updates" now installs the new AppImage automatically via `electron-updater`, matching the macOS and Windows tray flow, instead of stopping at a "manual update required" dialog. AppImages managed by a system package (AUR `/opt/SubMiner/SubMiner.AppImage`) and non-AppImage launches (no `APPIMAGE` env) still fall back to the GitHub-asset flow.
- Routed `electron-updater` HTTP through `/usr/bin/curl` on Linux and disabled differential downloads, matching the macOS path, so background update checks stay off Electron's network service.
@@ -1,4 +0,0 @@
-type: fixed
-area: updater
-
- Fixed Linux automatic update checks to avoid Electron networking, preventing native Electron network-service crashes during video startup.
@@ -1,4 +0,0 @@
-type: fixed
-area: updater
-
- Stopped Linux tray update checks from invoking the native Electron updater, using GitHub release metadata/assets instead so checks do not crash the tray app.
@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
- macOS `subminer settings` launches now exit cleanly after the settings window is closed, returning control to the terminal without requiring Ctrl+C.
@@ -1,4 +0,0 @@
-type: fixed
-area: setup
-
- First-run setup now recognizes installed macOS launchers in Homebrew or user PATH dirs, while manual setup installs avoid Homebrew-owned directories.
@@ -1,4 +0,0 @@
-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.
@@ -1,4 +0,0 @@
-type: fixed
-area: updater
-
- macOS update dialogs triggered by `subminer -u` now reliably appear in the foreground. SubMiner now shows the dock icon and activates itself via `osascript` (LaunchServices) before opening the modal alert; `app.focus({ steal: true })` alone was unreliable when SubMiner was reached through single-instance forwarding from the CLI-spawned child, leaving the dialog stranded behind other apps with a bouncing dock icon.
@@ -1,4 +0,0 @@
-type: fixed
-area: updater
-
- Bring macOS update dialogs to the front when `subminer --update` is run from the launcher.
@@ -1,4 +0,0 @@
-type: fixed
-area: updater
-
- Routed macOS supplemental GitHub release lookups through `/usr/bin/curl` instead of Electron `net.fetch`, eliminating the last Electron-networking path from background update checks and avoiding the network-service crashes seen in earlier prereleases.
@@ -1,4 +0,0 @@
-type: fixed
-area: build
-
- Fixed one-shot `make clean build install` flows so install picks up the AppImage built earlier in the same make invocation.
@@ -1,4 +0,0 @@
-type: added
-area: launcher
-
- Managed bundled mpv plugin startup options from SubMiner config.
@@ -1,4 +0,0 @@
-type: added
-area: launcher
-
- Added `mpv.profile` config and settings support for passing an mpv profile to SubMiner-managed mpv launches.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Wired configured session shortcuts, including `stats.markWatchedKey`, through mpv so custom add/remove changes work while mpv has focus.
@@ -1,6 +0,0 @@
-type: fixed
-area: updates
-
- Restored the standard macOS `electron-updater`/Squirrel update path and routed supplemental GitHub updater requests through Electron networking instead of Node fetch.
- macOS update checks now skip local build-output apps outside Applications before touching Squirrel, and macOS tray checks no longer perform the supplemental GitHub asset lookup.
- macOS `electron-updater` metadata and full ZIP downloads now use `/usr/bin/curl` under the hood to avoid the Electron network crash seen during tray update checks while preserving Squirrel installation.
@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
- Defaulted the note-fields note type picker to the configured Anki deck's note type when available, then exact `Kiku`, then exact `Lapis`, otherwise leaving it blank for manual selection.
@@ -1,4 +0,0 @@
-type: changed
-area: config
-
- Config: Preserved N+1 subtitle highlighting for existing configs that already enabled known-word highlighting, while keeping N+1 disabled by default for new configs unless `ankiConnect.nPlusOne.enabled` is set.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Kept the visible overlay and subtitle stream alive after restarting SubMiner from the mpv `y-r` shortcut by transporting Linux AppImage control args safely, restoring mpv subtitle visibility during shutdown, snapshotting subtitles before overlay suppression resumes, reapplying Linux overlay bounds after the restarted window maps, allowing Hyprland to resize the visible overlay window, and preserving user-paused playback while readiness gates clear.
@@ -1,4 +0,0 @@
-type: fixed
-area: websocket
-
- WebSocket: Kept the regular subtitle websocket plain-text only; annotation spans and token metadata now stay on the annotation websocket.
@@ -1,4 +0,0 @@
-type: changed
-area: release
-
- Prerelease note generation now reuses existing reviewed prerelease notes and asks Claude to merge only new fragment material, while `make clean` preserves `release/prerelease-notes.md`.
@@ -1,4 +0,0 @@
-type: changed
-area: jellyfin
-
- Removed the Jellyfin setup server presets dropdown; setup now shows a single editable server URL field.
@@ -1,4 +0,0 @@
-type: internal
-area: tests
-
- Removed stale Yomitan vendor source-inspection assertions for changes that were not shipped.
@@ -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.
@@ -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.
@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
- Fixed `subminer app --setup` so it opens the setup flow when SubMiner is already running in the background.
@@ -1,4 +0,0 @@
-type: fixed
-area: setup
-
- Quit standalone setup app launches after first-run setup finishes, returning the terminal instead of leaving the app process open.
@@ -1,4 +0,0 @@
-type: added
-area: setup
-
- Setup: Added an Open SubMiner Settings button to first-run setup and moved Finish setup to the right-side action slot.
@@ -1,4 +0,0 @@
-type: changed
-area: subtitles
-
- Subsync now always opens the manual picker and the `subsync.defaultMode` config/settings option has been removed.
@@ -1,4 +0,0 @@
-type: changed
-area: config
-
- Config: Primary and secondary subtitle appearance now use color controls plus CSS declaration editors, saved as `subtitleStyle.css` and `subtitleStyle.secondary.css`.
@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
- Migrated legacy subtitle hover token colors into `subtitleStyle.css` instead of leaving `hoverTokenColor` or `hoverTokenBackgroundColor` behind.
@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
- Migrated legacy primary and secondary subtitle appearance options into `subtitleStyle.css` automatically when loading config files.
@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
- Fixed live Settings window saves so primary and secondary subtitle CSS declarations apply immediately to open video overlays.
@@ -1,4 +0,0 @@
-type: changed
-area: config
-
- Added `subtitleSidebar.css`, migrated legacy sidebar appearance fields into it, and updated subtitle font defaults to `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP`.
@@ -1,10 +0,0 @@
-type: fixed
-area: tray
-
- Kept the tray app running when closing tray-launched Yomitan settings.
- Kept tray-launched Yomitan settings loading from blocking other tray actions.
- Replaced the default native Yomitan settings menu with a close-only menu so closing settings does not quit the tray app.
- Added an in-page close button for Yomitan settings on Hyprland, where native window controls are not available.
- Disabled Yomitan's embedded popup preview in the tray-launched settings window to avoid renderer hangs during normal sidebar navigation.
- Serialized copied Yomitan extension refreshes so startup cannot race itself and leave extension loading in an error state.
- Fixed tray-launched session help focus handling so the modal can close without mpv running.
@@ -1,4 +0,0 @@
-type: fixed
-area: windows
-
- Windows startup failures now show a native error dialog and write fatal details to the SubMiner app log instead of exiting silently.
@@ -1,4 +0,0 @@
-type: fixed
-area: updates
-
- Windows automatic updates now 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 without requiring `curl.exe`.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed Yomitan popups not opening when playback/overlay startup races the Yomitan extension load.
@@ -1,7 +0,0 @@
-type: fixed
-area: linux
-
- Suppressed false YouTube primary subtitle failure notifications after SubMiner confirms the selected primary track loaded successfully.
- Ensured launcher-managed playback commands create the tray icon even when they attach to an already-running SubMiner process.
- Prevented app-owned YouTube playback from letting the mpv plugin start a second SubMiner process after the launcher already started one.
- Logged Linux tray registration failures with a StatusNotifier/AppIndicator hint and documented the Hyprland tray-host requirement.
@@ -46,10 +46,16 @@
  // Logging
  // Controls logging verbosity.
  // Set to debug for full runtime diagnostics.
-  // Hot-reload: logging.level applies live while SubMiner is running.
+  // Hot-reload: logging.level and logging.files apply live while SubMiner is running.
  // ==========================================
  "logging": {
-    "level": "info" // Minimum log level for runtime logging. Values: debug | info | warn | error
+    "level": "warn", // Minimum log level for runtime logging. Values: debug | info | warn | error
+    "rotation": 7, // Number of days of app, launcher, and mpv logs to retain.
+    "files": {
+      "app": true, // Write SubMiner app runtime logs. Values: true | false
+      "launcher": true, // Write launcher command logs. Values: true | false
+      "mpv": false // Write mpv player logs. Enable temporarily when debugging mpv/plugin startup. Values: true | false
+    } // Files setting.
  }, // Controls logging verbosity.

  // ==========================================
@@ -83,7 +89,7 @@
      "rightStickPress": 10, // Raw button index used for controller R3 input.
      "leftTrigger": 6, // Raw button index used for controller L2 input.
      "rightTrigger": 7 // Raw button index used for controller R2 input.
-    }, // Semantic button-name reference mapping used for legacy configs and debug output. Updating it does not rewrite existing raw binding descriptors.
+    }, // Semantic button-name reference mapping used for debug output. Updating it does not rewrite existing raw binding descriptors.
    "bindings": {
      "toggleLookup": {
        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
@@ -187,7 +193,7 @@
    "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
    "toggleSecondarySub": "CommandOrControl+Shift+V", // Accelerator that toggles the secondary subtitle bar visibility.
    "markAudioCard": "CommandOrControl+Shift+A", // Accelerator that marks the last mined card as an audio card.
-    "openCharacterDictionary": "CommandOrControl+Alt+A", // Accelerator that opens the character dictionary modal.
+    "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
@@ -374,7 +380,7 @@
      "word-spacing": "0", // Word spacing setting.
      "font-kerning": "normal", // Font kerning setting.
      "text-rendering": "geometricPrecision", // Text rendering setting.
-      "text-shadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)", // Text shadow setting.
+      "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)", // Text shadow setting.
      "backdrop-filter": "blur(6px)", // Backdrop filter setting.
      "--subtitle-hover-token-color": "#f4dbd6", // Subtitle hover token color setting.
      "--subtitle-hover-token-background-color": "transparent" // Subtitle hover token background color setting.
@@ -383,7 +389,9 @@
    "preserveLineBreaks": false, // Preserve line breaks in visible overlay subtitle rendering. When false, line breaks are flattened to spaces for a single-line flow. Values: true | false
    "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
+    "primaryVisibleOnYomitanPopup": true, // Keep the primary subtitle bar visible while a Yomitan popup is open when primary subtitles are in hover mode. Values: true | false
+    "nameMatchEnabled": false, // Enable character dictionary sync and subtitle token coloring for character-name matches. 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.
@@ -397,7 +405,7 @@
    "frequencyDictionary": {
      "enabled": false, // Enable frequency-dictionary-based highlighting based on token rank. Values: true | false
      "sourcePath": "", // Optional absolute path to a frequency dictionary directory. If empty, built-in discovery search paths are used.
-      "topX": 1000, // Only color tokens with frequency rank <= topX (default: 1000).
+      "topX": 10000, // Only color tokens with frequency rank <= topX (default: 10000).
      "mode": "single", // single: use one color for all matching tokens. banded: use color ramp by frequency band. Values: single | banded
      "matchMode": "headword", // headword: frequency lookup uses dictionary form. surface: lookup uses subtitle-visible token text. Values: headword | surface
      "singleColor": "#f5a97f", // Color used when frequencyDictionary.mode is `single`.
@@ -422,7 +430,7 @@
        "word-spacing": "0", // Word spacing setting.
        "font-kerning": "normal", // Font kerning setting.
        "text-rendering": "geometricPrecision", // Text rendering setting.
-        "text-shadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)", // Text shadow setting.
+        "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)", // Text shadow setting.
        "backdrop-filter": "blur(6px)" // Backdrop filter setting.
      } // CSS declaration object applied to secondary subtitles after normal subtitle style defaults.
    } // Secondary setting.
@@ -515,7 +523,7 @@
      "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
      "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
-      "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio.
+      "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
    }, // Media setting.
@@ -523,8 +531,8 @@
      "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
-      "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"] }.
+      "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 expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
    }, // Known words setting.
    "behavior": {
      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
@@ -587,11 +595,8 @@
    "enabled": false, // Enable AniList post-watch progress updates. Values: true | false
    "accessToken": "", // Optional explicit AniList access token override; leave empty to use locally stored token from setup.
    "characterDictionary": {
-      "enabled": false, // Enable automatic Yomitan character dictionary sync for currently watched AniList media. Values: true | false
-      "refreshTtlHours": 168, // Legacy setting; merged character dictionary retention is now usage-based and this value is ignored.
      "maxLoaded": 3, // Maximum number of most-recently-used anime snapshots included in the merged Yomitan character dictionary.
-      "evictionPolicy": "delete", // Legacy setting; merged character dictionary eviction is usage-based and this value is ignored. Values: disable | delete
-      "profileScope": "all", // Yomitan profile scope for dictionary enable/disable updates. Values: all | active
+      "profileScope": "all", // Yomitan profile scope for character dictionary settings updates. Values: all | active
      "collapsibleSections": {
        "description": false, // Open the Description section by default in character dictionary glossary entries. Values: true | false
        "characterInformation": false, // Open the Character Information section by default in character dictionary glossary entries. Values: true | false
@@ -624,7 +629,7 @@
    "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
    "launchMode": "normal", // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
    "profile": "", // Optional mpv profile name passed to SubMiner-managed mpv launches. Leave empty to pass no profile.
-    "socketPath": "/tmp/subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
+    "socketPath": "\\\\.\\pipe\\subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
    "backend": "auto", // Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform. Values: auto | hyprland | sway | x11 | macos | windows
    "autoStartSubMiner": true, // Start SubMiner in the background when SubMiner-managed mpv loads a file. Values: true | false
    "pauseUntilOverlayReady": true, // Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness. Values: true | false
@@ -644,14 +649,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
@@ -19,18 +19,26 @@ type VersionManifest = {
  versions: Array<{ version: string; path: string }>;
 };

-const base = normalizeBase(process.env.SUBMINER_DOCS_BASE ?? '/');
-const outDir = process.env.SUBMINER_DOCS_OUT_DIR;
-const docsSourceDir = process.env.SUBMINER_DOCS_SOURCE_DIR ?? process.cwd();
-const localArchiveDir = resolve(
-  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR ??
-    join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
-);
-const channel = normalizeChannel(process.env.SUBMINER_DOCS_CHANNEL);
-const docsVersion = process.env.SUBMINER_DOCS_VERSION;
-const latestStable = process.env.SUBMINER_DOCS_LATEST_STABLE ?? 'v0.14.0';
+function optionalEnv(value: string | undefined): string | undefined {
+  return value && value !== 'undefined' ? value : undefined;
+}
+
+const base = normalizeBase(optionalEnv(process.env.SUBMINER_DOCS_BASE) ?? '/');
+const outDir = optionalEnv(process.env.SUBMINER_DOCS_OUT_DIR);
+const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? process.cwd();
+const channel = normalizeChannel(optionalEnv(process.env.SUBMINER_DOCS_CHANNEL));
+const docsVersion = optionalEnv(process.env.SUBMINER_DOCS_VERSION);
+const latestStable = optionalEnv(process.env.SUBMINER_DOCS_LATEST_STABLE) ?? 'v0.14.0';
 const versionManifest = parseVersionManifest(process.env.SUBMINER_DOCS_VERSION_MANIFEST);
-const versionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN ?? 'production';
+const versionLinkOrigin =
+  optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? 'production';
+
+function getLocalArchiveDir(): string {
+  return resolve(
+    optionalEnv(process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR) ??
+      join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
+  );
+}

 function normalizeBase(value: string): string {
  if (!value || value === '/') return '/';
@@ -43,7 +51,7 @@ function normalizeChannel(value: string | undefined): DocsChannel {
 }

 function parseVersionManifest(value: string | undefined): VersionManifest {
-  if (!value) {
+  if (!value || value === 'undefined') {
    return {
      latestStable,
      channels: [
@@ -218,6 +226,7 @@ function isFile(path: string): boolean {
 function archiveFileForPathname(pathname: string): string | null {
  if (!shouldHandleLocalVersionRoute(pathname)) return null;

+  const localArchiveDir = getLocalArchiveDir();
  const routePath = decodeURIComponent(pathname).replace(/^\/+/, '');
  const filePath = resolve(localArchiveDir, routePath);
  if (filePath !== localArchiveDir && !filePath.startsWith(`${localArchiveDir}${sep}`)) {
@@ -234,7 +243,11 @@ function archiveFileForPathname(pathname: string): string | null {
 }

 function serveLocalArchiveRoute(pathname: string, response: DevServerResponse): boolean {
-  if (versionLinkOrigin !== 'local') return false;
+  if (
+    (optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? versionLinkOrigin) !== 'local'
+  ) {
+    return false;
+  }

  const filePath = archiveFileForPathname(pathname);
  if (!filePath) return false;
@@ -98,12 +98,11 @@ All AniList API calls go through a shared rate limiter that enforces a sliding w
 | ------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
 | `enabled`                                   | `true`, `false`     | Enable AniList post-watch progress updates (default: `false`)                                                |
 | `accessToken`                               | string              | Explicit AniList access token override; when blank, SubMiner uses the stored encrypted token (default: `""`) |
-| `characterDictionary.enabled`               | `true`, `false`     | Enable auto-sync of the merged character dictionary from AniList (default: `false`)                          |
 | `characterDictionary.maxLoaded`             | number              | Number of recent media snapshots kept in the merged dictionary (default: `3`)                                |
 | `characterDictionary.profileScope`          | `"all"`, `"active"` | Apply dictionary to all Yomitan profiles or only the active one                                              |
 | `characterDictionary.collapsibleSections.*` | `true`, `false`     | Control which dictionary entry sections start expanded                                                       |

-See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format.
+See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format. Character dictionary sync follows `subtitleStyle.nameMatchEnabled`.

 ## CLI Commands

@@ -36,8 +36,8 @@ In both modes, the enrichment workflow is the same:
 4. Fills the translation field from the secondary subtitle or AI.
 5. Writes metadata to the miscInfo field.

-Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it searches all decks.
-Known-word sync scope is controlled by `ankiConnect.knownWords.decks` (object map), with `ankiConnect.deck` used as legacy fallback.
+Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it searches all decks. In Settings, the AnkiConnect deck dropdown auto-fills from Yomitan's current mining deck when available, then falls back to the decks reported by AnkiConnect.
+Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.

 ### Proxy Mode Setup (Yomitan / Texthooker)

@@ -269,6 +269,43 @@ For domains migrated to reducer-style transitions (for example AniList token/que
 - Reducer boundary: when a domain has transition helpers in `src/main/state.ts`, new callsites should route updates through those helpers instead of ad-hoc object mutation in `main.ts` or composers.
 - Tests for migrated domains should assert both the intended field changes and non-targeted field invariants.

+## Playback Startup Flow
+
+Before the app boots, something has to launch mpv, inject the plugin, and bring the overlay up. SubMiner-managed launches own this step — the `subminer` launcher, the app's own playback, and the packaged Windows shortcut all follow the same path. The launcher reads `config.jsonc`, spawns mpv with the IPC socket and the bundled plugin, and passes runtime settings as `--script-opts`. The plugin never reads a config file: the shipped `subminer.conf` is intentionally empty so command-line opts always win.
+
+Once mpv is up, exactly one of two triggers brings up the overlay. On a first launch the plugin's `file-loaded` hook self-starts the app once the socket is ready (because the launcher injected `auto_start=yes`). When the app is already running — or for explicit `--start-overlay` and YouTube flows — the launcher instead attaches over the control socket and suppresses the plugin's auto-start, so the two never fire together. Both converge on the same app bring-up, which then runs the Program Lifecycle below.
+
+```mermaid
+flowchart TB
+  classDef entry fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:2px,font-weight:bold
+  classDef extrt fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef decision fill:#f5a97f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef proc fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef app fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef overlay fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
+
+  Entry["Managed launch<br/>subminer CLI · app · Windows shortcut"]:::entry
+  Entry --> Cfg["Launcher reads config.jsonc<br/>→ plugin runtime config"]:::extrt
+  Cfg --> Spawn["Spawn mpv<br/>--input-ipc-server=/tmp/subminer-socket<br/>--script=plugin/subminer/main.lua<br/>--script-opts=subminer-… (auto_start, backend, …)"]:::proc
+  Spawn --> Boot["Plugin boot · read_options('subminer')<br/>empty subminer.conf; CLI opts win"]:::extrt
+  Boot --> Sock["mpv IPC socket ready"]:::proc
+  Sock --> Who{"Overlay trigger"}:::decision
+
+  Who -->|"app already running, or<br/>--start-overlay / YouTube"| Attach["Launcher startOverlay()<br/>attach via control socket<br/>plugin auto-start suppressed"]:::proc
+  Who -->|"first launch, auto_start=yes"| Self["Plugin file-loaded hook<br/>polls socket → process.start_overlay()"]:::extrt
+
+  Attach --> AppUp
+  Self --> AppUp
+
+  AppUp["Spawn / attach SubMiner app<br/>--start --managed-playback --socket … --backend …"]:::app
+  AppUp --> Ctrl["App control server up<br/>/tmp/subminer-control-* dedupes a 2nd launch"]:::app
+  Ctrl --> Life["app.whenReady → Program Lifecycle (below)"]:::app
+  Life --> Conn["MpvIpcClient connects to /tmp/subminer-socket"]:::overlay
+  Conn --> Show["Transparent overlay over mpv<br/>Yomitan lookup · mine"]:::overlay
+```
+
+The runtime sockets in this flow are detailed in [IPC + Runtime Contracts](./ipc-contracts#runtime-sockets).
+
 ## Program Lifecycle

 - **Module-level init:** Before `app.ready`, the composition root registers protocols, sets platform flags, constructs all services, and wires dependency injection. `runAndApplyStartupState()` parses CLI args and detects the compositor backend.
@@ -1,8 +1,80 @@
 # Changelog

-## v0.14.0 (2026-05-12)
+## v0.15.0 (2026-05-29)

-SubMiner no longer requires a globally-installed mpv plugin. The bundled plugin is injected at runtime only when SubMiner launches mpv — through the `subminer` launcher, the app's managed launch, or the packaged Windows SubMiner mpv shortcut. When you open mpv on its own, SubMiner is not involved and the plugin is never loaded. If you have a legacy global SubMiner plugin under mpv's `scripts` directory, first-run setup detects it and prompts you to remove it before playback starts.
+**Breaking Changes**
+
+- Subsync: The `subsync.defaultMode` config option has been removed; Subsync now always opens the manual subtitle picker regardless of any previously set default mode.
+
+**Added**
+
+- Auto-Updater: Adds tray and `subminer -u` update checks with app update prompts, launcher and Linux rofi theme auto-updates, checksum verification, configurable notifications, and an opt-in prerelease channel via `updates.channel: "prerelease"`.
+- Settings Window: New dedicated Settings window via `subminer --settings` or `subminer settings`, organized into Appearance, Behavior, Anki, Input, and Integration sections; click-to-learn keybinding controls including the AniSkip button key; AnkiConnect-backed deck, field, and note-type pickers that auto-fill from the configured Anki deck; cross-category search; and live save for most options including subtitle CSS, stats keys, logging level, Jimaku, Subsync, and Anki mappings. AI and translation settings remain config-file only.
+- Inline Character Portraits: Optional AniList character portraits appear inline for name-matched subtitle text; manual AniList overrides scoped per parent media directory so separate season folders maintain separate character dictionary selections.
+- Log Export: Sanitized log ZIP export from the tray menu and via `subminer logs -e`, with home-directory usernames redacted from exported contents.
+- Launcher CLI: `subminer --version` / `subminer -v` prints the installed app version; `mpv.profile` config and Settings support passes a named mpv profile to managed launches; bundled mpv plugin startup options are now configurable from SubMiner config.
+- First-Run Setup: Optional installer for Bun and the `subminer` CLI on Linux, macOS, and Windows, including a Windows `subminer.cmd` PATH shim so `subminer` works without manually adding `SubMiner.exe` to PATH; setup recognizes existing Homebrew or user PATH installs and avoids writing into Homebrew-owned paths; includes an Open SubMiner Settings button; standalone setup app quits after completing, returning terminal control.
+- Primary Subtitle Visibility on Yomitan Popup: New `subtitleStyle.primaryVisibleOnYomitanPopup` option keeps hover-mode primary subtitles visible while a Yomitan popup is open.
+
+**Changed**
+
+- Subtitle Appearance Config: Primary and secondary subtitle appearance now use color controls plus CSS declaration editors, saved as `subtitleStyle.css`, `subtitleStyle.secondary.css`, and `subtitleSidebar.css`; known-word and N+1 annotation colors moved to `subtitleStyle.knownWordColor` and `subtitleStyle.nPlusOneColor`; subtitle font defaults updated to `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP`. Existing configs migrate automatically; legacy Anki color keys still accepted with deprecation warnings.
+- Subtitle Style Defaults: Stronger outline-style text shadow, thicker JLPT underlines, and frequency `topX` default raised to `10000`.
+- Character Dictionary: Entries scoped to the current AniList media for name matching and inline portraits; generates Japanese-only name aliases so raw romanized/English aliases no longer surface as separate results; new `Ctrl/Cmd+D` manager modal to remove, reorder, or override loaded entries; in-app AniList selector waits for an explicit search with the box prefilled from the current filename; `subtitleStyle.nameMatchEnabled` is now the sole switch for dictionary sync and builds.
+- Electron Runtime: Updated from 39.8.6 to 42.2.0, returning SubMiner to a supported Electron release line.
+- N+1 Highlighting Default: `ankiConnect.nPlusOne.enabled` is no longer implicitly enabled when known-word highlighting is on; existing configs that already had N+1 enabled are unchanged, but new configs must set it explicitly.
+- Linux Auto-Update Flow: Linux tray "Check for Updates" now installs the new AppImage automatically, matching macOS and Windows; AppImages managed by a system package (e.g. AUR) and non-AppImage launches still use the GitHub-asset flow.
+- Jellyfin Setup: Removed the server presets dropdown; setup now shows a single editable server URL field.
+- Jellyfin Cast Identity: Device identity now derived from the OS hostname and always reported as SubMiner; previously configurable identity fields are ignored, preventing multiple installs from sharing a remote-session identity.
+- Startup Defaults: Jellyfin remote-session startup warmup and character-name subtitle highlighting now default to off.
+- Setup Appearance: Removed the bundled mpv runtime plugin readiness card from the setup flow.
+
+**Fixed**
+
+- AniList Progress: Progress updates fire correctly when playback reaches or skips past the watched threshold using fresh mpv timing events; season-specific results preferred for multi-season files with a clear message when the matched season is not in Planning or Watching; repeated missing-token checks no longer exhaust retry attempts or duplicate dead-letter entries.
+- Anki Mining: Sentence-audio padding is opt-in by default; animated AVIF freeze-frame duration aligned to word audio length without double-counting; multi-line sentence alignment fixed for repeated subtitle text; Kiku duplicate-card detection, auto-merge, modal acknowledgment race, and field/tag ordering corrected; YouTube playback cards use mpv's resolved stream URLs; sentence cards refresh the secondary subtitle before saving; known-word cache appends correctly with multiple deck field mappings.
+- Jellyfin Discovery: Startup, subtitle track selection, and duplicate ready-signal handling all fixed; paused mpv no longer misreported as playing; startup unpause no longer repeats after a manual pause or `y-t` toggle; delayed Japanese subtitle selection, later-loading foreign track hijacking, and long-lived sidebar ffmpeg extractor leaks fixed; resume corrected when a remote play command sends `StartPositionTicks: 0` despite saved progress; picker library discovery kept working regardless of app log level.
+- Jellyfin Remote: Tray checkbox stays in sync on Linux after tray, CLI, or startup changes; stale discovery sessions restarted when the server no longer lists the SubMiner cast target; remote controller visibility and progress sync fixed for seeks, stops, startup path changes, and Linux websocket reconnect windows; Play and Resume now behave correctly (Play from beginning, Resume from saved position); final progress reports reuse SubMiner's last known position when mpv resets on stop; Windows setup login flow fixed with an IPC bridge, immediate feedback, and a timeout with inline error for unreachable servers.
+- Jellyfin Subtitles and Overlay: Subtitle overlay shown automatically during Jellyfin playback; `y-t` toggle made reliable and sticky across stream redirects; managed subtitle defaults re-armed on redirect; passive Linux/Hyprland overlay shows no longer steal keyboard focus from mpv; subtitle timing improved with preferred embedded streams over external sidecars, correct Japanese-vs-English cue offset handling, per-stream delay shift restoration, and transient track-list read failure tolerance.
+- Overlay (macOS): Overlay hides when mpv loses focus, is minimized, or is no longer the foreground app; stable through transient window geometry disappearances from macOS APIs and when clicking from the overlay back into mpv; stats overlay opened inactive so it appears over fullscreen mpv without switching Spaces; passthrough fixed so mpv controls stay clickable before hovering a subtitle bar; window-tracker polling reduced while mpv is stably focused.
+- Overlay (Linux / Hyprland): Placement refreshes after leaving fullscreen; overlay stays above mpv after focus changes from clicks or movement; Settings and Yomitan windows promoted above the subtitle overlay instead of opening behind it; overlay hides when the character dictionary modal opens, including during AniList lookup.
+- Overlay Lifecycle: First startup subtitle primed before autoplay resumes so the overlay renders text before playback begins; overlay and subtitle stream kept alive after `y-r` restart with correct Linux bounds reapplication; launcher-owned playback quits SubMiner on end while background/tray sessions stay alive; subtitle sync modal fixed on macOS so it no longer flashes on first attempt or leaves stale state; Windows managed mpv launches from a background instance now correctly receive the start command, retarget the new socket, bind to the player window, and receive startup overlay options.
+- Yomitan Sidebar: Playback stays paused for sidebar-opened Yomitan popups when auto-pause is enabled; fixed popups not opening when startup races the Yomitan extension load; sidebar mining cards use audio and images from the clicked sidebar line instead of the current primary subtitle.
+- Launcher: Warm launches reuse a running background instance, reapply preferred subtitles, and close launcher-owned tray apps after playback ends; videos stay paused until subtitle priming and tokenization readiness complete; `subminer settings` on macOS exits cleanly when the window is closed; `subminer app` on Linux returns terminal control immediately; Linux first-run installs build with a valid Bun shebang; `subminer app --setup` opens the setup flow when SubMiner is already running in background.
+- YouTube Playback: Selected subtitles downloaded to local temp files so the primary bar and sidebar read the same source, with cleanup on reload and quit; false load-failure notifications suppressed; tray icon created on launcher-managed playback that attaches to an already-running process; mpv plugin no longer starts a second SubMiner instance for app-owned YouTube playback.
+- Shortcuts: Native mpv menu shortcuts disabled during managed macOS playback so configured SubMiner shortcuts work while mpv has focus; custom session shortcuts including `stats.markWatchedKey` wired through mpv; multi-line copy/mine overlay correctly focused so number keys choose the line count on macOS and Windows.
+- Controller Bindings: Controller config and debug shortcuts stay closed while controller support is disabled; binding learn mode starts from the edit pencil; remaps saved per controller profile; binding badges also start learn mode; row reset buttons restore individual bindings to defaults.
+- Logging: `logging.level` forwarded to launcher-started and Windows shortcut-started mpv sessions covering mpv log verbosity, plugin logging, and plugin-launched app logging; `logging.rotation` (default 7 days) and per-component `logging.files` toggles added with mpv logs disabled by default; repeated IPC socket warning spam suppressed while waiting for mpv to recreate the socket; Windows mpv IPC, subtitle track, and Yomitan diagnostics added.
+- Updater: Linux `subminer -u` performs release updates independently of any running tray app using GitHub release metadata; macOS update dialogs from `subminer -u` reliably appear in the foreground with a manual-install message for builds that cannot apply native updates; macOS and Linux `electron-updater` routes through `/usr/bin/curl` to avoid Electron network crashes; Windows automatic updates keep the native NSIS install path while routing updater HTTP through main-process fetch to avoid delayed exit after launch.
+- In-Player Stats: Layering fixed so delete confirmations, overlay modals, and update-check dialogs appear above the stats window; Jellyfin playback stats grouped by item metadata so watched episodes merge with matching local library titles and keep clean display names.
+- Tray: Tray stays running when Yomitan settings are closed; settings loading no longer blocks other tray actions; Yomitan extension refreshes serialized at startup; embedded popup preview disabled to prevent renderer hangs during sidebar navigation; Windows "Open SubMiner Setup" action opens the setup window correctly after first-run is complete; session help modal close fixed without mpv running.
+- Discord Rich Presence: No longer falls back to Jellyfin stream URLs; Jellyfin playback titles primed before stream loading so presence shows the show/episode title instead of a URL.
+- WebSocket Annotations: Annotation spans and token metadata stay on the annotation WebSocket; the regular subtitle WebSocket is plain-text only.
+- Subtitle Frequency Highlighting: Frequency annotations kept for determiner-led noun compounds like `その場` while still filtering standalone determiners; fixed for Yomitan single-token compounds with internal particles such as `目の前` while keeping pure grammar/kana helper spans unannotated.
+- Subtitle Annotation Prefetching: Cached colored annotations and character images ready sooner for live subtitle changes without delaying raw subtitle display.
+- Packaging: macOS compiled mpv window helper correctly built into `dist/scripts` and bundled, preventing fallback to slow Swift source startup; stale Windows helper resource entry removed; one-shot `make clean build install` AppImage flows fixed so install picks up the AppImage built earlier in the same invocation.
+- Windows Startup Errors: Fatal startup failures now show a native error dialog and write details to the app log instead of exiting silently.
+
+**Docs**
+
+- Documentation Site: Published stable docs at the site root with current development docs under `/main/`; fixed versioned docs navigation, archived page link handling, and local dev version routing; documented all previously undocumented config options including `subtitleStyle.primaryDefaultMode`, `stats.markWatchedKey`, `immersionTracking.lifetimeSummaries.*`, and all seven `mpv.*` launcher options; added Playback Startup Flow and Runtime Sockets diagrams to the architecture docs with cross-reference pointers in the MPV Plugin and Troubleshooting pages.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+
+- Release Tooling: Release-note polishing treats pending fragments and reviewed prerelease notes as a cumulative final outcome, collapsing prerelease-only fixes into the final user-facing change; prerelease generation reuses existing reviewed notes and merges only new fragment material; `make clean` preserves `release/prerelease-notes.md`.
+- Tests: Removed stale Yomitan vendor source-inspection assertions for changes that were not shipped.
+
+</details>
+
+## Previous Versions
+
+<details>
+<summary>v0.14.x</summary>
+
+<h2>v0.14.0 (2026-05-12)</h2>

 **Added**

@@ -64,7 +136,7 @@ SubMiner no longer requires a globally-installed mpv plugin. The bundled plugin

 </details>

-## Previous Versions
+</details>

 <details>
 <summary>v0.12.x</summary>
@@ -14,14 +14,14 @@ The feature has three stages: **snapshot**, **merge**, and **match**.

 2. **Merge** — SubMiner maintains a most-recently-used list of media IDs (default: 3). Snapshots from those titles are merged into a single Yomitan ZIP — `character-dictionaries/merged.zip` — which is always named "SubMiner Character Dictionary" so Yomitan treats it as a single stable dictionary across rebuilds.

-3. **Match** — During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. Tokens that match a character entry are flagged with `isNameMatch` and highlighted in the overlay with a distinct color.
+3. **Match** — During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. SubMiner only accepts character entries for the current AniList media when that media ID is known, then flags matching tokens with `isNameMatch` and highlights them in the overlay with a distinct color.

 ## Enabling the Feature

 Character dictionary sync is disabled by default. To turn it on:

 1. Authenticate with AniList (see [AniList Integration](/anilist-integration#setup)).
-2. Set `anilist.characterDictionary.enabled` to `true` in your config.
+2. Set `subtitleStyle.nameMatchEnabled` to `true` in your config or enable **Name Match Enabled** in Settings.
 3. Start watching — SubMiner will generate a snapshot for the current media and import the merged dictionary into Yomitan automatically.

 ```jsonc
@@ -29,9 +29,9 @@ Character dictionary sync is disabled by default. To turn it on:
  "anilist": {
    "enabled": true,
    "accessToken": "your-token",
-    "characterDictionary": {
-      "enabled": true,
-    },
+  },
+  "subtitleStyle": {
+    "nameMatchEnabled": true,
  },
 }
 ```
@@ -89,23 +89,29 @@ Name matching runs inside Yomitan's scanning pipeline during subtitle tokenizati

 1. Yomitan receives subtitle text and scans for dictionary matches.
 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`).
+3. When the current AniList media ID is known, entries whose embedded media ID belongs to a different title are ignored for name matching and inline portraits.
+4. Matched tokens are flagged `isNameMatch: true` and forwarded to the renderer.
+5. If `subtitleStyle.nameMatchEnabled` is enabled, the renderer applies the name-match highlight color (default: `#f5bde6`).
+6. 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`   | Enable dictionary sync and 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)
@@ -130,7 +136,7 @@ The three collapsible sections can be configured to start open or closed:

 ## Auto-Sync Lifecycle

-When `characterDictionary.enabled` is `true`, SubMiner runs an auto-sync routine whenever the active media changes.
+When `subtitleStyle.nameMatchEnabled` is `true`, SubMiner runs an auto-sync routine whenever the active media changes.

 **Phases:**

@@ -169,10 +175,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 manager with `Ctrl/Cmd+D`, use the **Override** tab/button, 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"
@@ -185,10 +194,20 @@ SubMiner.AppImage --dictionary-candidates --dictionary-target "/path/to/episode.
 SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary-target "/path/to/episode.mkv"

 # Open the in-app selector from the running app
-subminer app --open-character-dictionary
+subminer app --session-action '{"actionId":"openCharacterDictionaryManager"}'
 ```

-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.
+
+## Managing Loaded Entries
+
+Open the manager with `Ctrl/Cmd+D` (`shortcuts.openCharacterDictionaryManager`). The manager shows the merged dictionary's active MRU entries, marks the current anime, and lets you adjust eviction priority for the other loaded entries.
+
+- **Remove** drops a non-current entry from the active merged dictionary and rebuilds/imports once.
+- **Up/Down** changes MRU order for future eviction without rebuilding.
+- **Override** opens the AniList selector for that entry's title so you can replace a saved loaded entry.
+
+The current anime cannot be removed while you are watching it; it stays loaded until playback changes.

 ## File Structure

@@ -207,7 +226,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** (v17): 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:

@@ -224,13 +243,13 @@ merged.zip

 | Option                                                                 | Default   | Description                                                     |
 | ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
-| `anilist.characterDictionary.enabled`                                  | `false`   | Enable auto-sync of character dictionary from AniList           |
 | `anilist.characterDictionary.maxLoaded`                                | `3`       | Number of recent media snapshots kept in the merged dictionary  |
 | `anilist.characterDictionary.profileScope`                             | `"all"`   | Apply dictionary to `"all"` Yomitan profiles or `"active"` only |
 | `anilist.characterDictionary.collapsibleSections.description`          | `false`   | Start Description section expanded                              |
 | `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.nameMatchEnabled`                                       | `false`   | Enable character-dictionary sync and name highlighting          |
+| `subtitleStyle.nameMatchImagesEnabled`                                 | `false`   | Show small AniList portraits beside matched names               |
 | `subtitleStyle.nameMatchColor`                                         | `#f5bde6` | Highlight color for character-name matches                      |

 ## Reference Implementation
@@ -252,9 +271,10 @@ 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.
+- **Names not highlighting:** Confirm `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 manager (`Ctrl/Cmd+D`) to remove/reorder loaded titles, then use **Override** to correct the active AniList match. You can also run `--dictionary-candidates`, then save the correct media with `--dictionary-select --dictionary-anilist-id <id>`. SubMiner ignores character entries from other loaded titles for subtitle name matching and inline portraits once the current media ID is known.
 - **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.

@@ -21,7 +21,7 @@ For most users, start with this minimal configuration:
    "deck": "YourDeckName",
    "knownWords": {
      "decks": {
-        "YourDeckName": ["Word", "Word Reading", "Expression"]
+        "YourDeckName": ["Word"]
      }
    },
    "fields": {
@@ -33,7 +33,7 @@ For most users, start with this minimal configuration:
 }
 ```

-`ankiConnect.deck` is still accepted for backward-compatible polling scope and legacy known-word fallback behavior. For known-word cache scope, prefer `ankiConnect.knownWords.decks` with deck-to-fields mapping.
+Use the known-word deck map to choose which Anki decks and note fields feed the known-word cache.

 Then customize as needed using the sections below.

@@ -52,9 +52,9 @@ The Settings window groups options by workflow instead of mirroring the raw conf
 - Tracking & App
 - Advanced

-Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Behavior** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`. Anki-aware fields can query AnkiConnect for deck names, note types, and field names, and keybinding fields use click-to-learn controls instead of raw text boxes.
+Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Behavior** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`. Anki-aware fields can query AnkiConnect for deck names, note types, and field names. The AnkiConnect deck field also reads Yomitan's current mining deck and auto-fills an empty setting when one is found. Keybinding fields use click-to-learn controls instead of raw text boxes.

-The Settings window preserves existing JSONC comments, trailing commas, unrelated keys, and unsupported legacy options. Resetting a field removes the explicit config path so the built-in default applies.
+The Settings window preserves existing JSONC comments, trailing commas, and unrelated keys. Resetting a field removes the explicit config path so the built-in default applies.

 Secret fields do not display stored values. They show whether a value is configured; entering a new value writes it, and reset clears the explicit path. Prefer command-based secret options such as `ai.apiKeyCommand` when available.

@@ -94,35 +94,10 @@ On macOS, these validation warnings also open a native dialog with full details

 SubMiner watches the active config file (`config.jsonc` or `config.json`) while running and applies supported updates automatically.

-Hot-reloadable fields:
-
- `subtitleStyle`
- `subtitleSidebar`
- `keybindings`
- `shortcuts`
- `secondarySub.defaultMode`
- `stats.toggleKey`
- `stats.markWatchedKey`
- `logging.level`
- `youtube.primarySubLanguages`
- `jimaku.*`
- `subsync.*`
- `ankiConnect.ai.enabled`
- `ankiConnect.behavior.autoUpdateNewCards`
- `ankiConnect.knownWords.highlightEnabled`
- `ankiConnect.knownWords.refreshMinutes`
- `ankiConnect.knownWords.addMinedWordsImmediately`
- `ankiConnect.knownWords.matchMode`
- `ankiConnect.knownWords.decks`
- `ankiConnect.nPlusOne.enabled`
- `ankiConnect.nPlusOne.minSentenceWords`
- `ankiConnect.fields.word`
- `ankiConnect.fields.audio`
- `ankiConnect.fields.image`
- `ankiConnect.fields.sentence`
- `ankiConnect.fields.miscInfo`
- `ankiConnect.isLapis.sentenceCardModel`
- `ankiConnect.isKiku.fieldGrouping`
+Hot-reloadable settings include subtitle appearance, sidebar controls, keybindings,
+logging level, selected source-language preferences, Jimaku/Subsync settings, and
+the Anki deck, known-word, N+1, field, sentence-card, and Kiku options listed
+in the reference tables below.

 When these values change, SubMiner applies them live. Invalid config edits are rejected and the previous valid runtime config remains active.

@@ -130,7 +105,7 @@ Restart-required changes:

 - Any other config sections still require restart.
 - Shared top-level `ai` provider settings still require restart.
- AnkiConnect transport/proxy/media/deck/tag fields still require restart unless listed above.
+- AnkiConnect transport/proxy/media/tag fields still require restart unless listed above.
 - SubMiner shows an on-screen/system notification listing restart-required sections when they change.

 ### Configuration Options Overview
@@ -175,7 +150,7 @@ The configuration file includes several main sections:
 - [**Jimaku**](#jimaku) - Jimaku API configuration and defaults
 - [**Subtitle Sync**](#subtitle-sync) - Sync current subtitle with `alass`/`ffsubsync`
 - [**AniList**](#anilist) - Optional post-watch progress updates
- [**Yomitan**](#yomitan) - Reuse an external read-only Yomitan profile via `yomitan.externalProfilePath`
+- [**Yomitan**](#yomitan) - Reuse an external read-only Yomitan profile
 - [**Jellyfin**](#jellyfin) - Optional Jellyfin auth, library listing, and playback launch
 - [**Discord Rich Presence**](#discord-rich-presence) - Optional Discord activity card updates
 - [**Immersion Tracking**](#immersion-tracking) - Track subtitle sessions and mining activity in SQLite
@@ -193,14 +168,24 @@ Control the minimum log level for runtime output:
 ```json
 {
  "logging": {
-    "level": "info"
+    "level": "warn",
+    "rotation": 7,
+    "files": {
+      "app": true,
+      "launcher": true,
+      "mpv": false
+    }
  }
 }
 ```

-| Option  | Values                                   | Description                                               |
-| ------- | ---------------------------------------- | --------------------------------------------------------- |
-| `level` | `"debug"`, `"info"`, `"warn"`, `"error"` | Minimum log level for runtime logging (default: `"info"`) |
+| Option           | Values                                   | Description                                                          |
+| ---------------- | ---------------------------------------- | -------------------------------------------------------------------- |
+| `level`          | `"debug"`, `"info"`, `"warn"`, `"error"` | Minimum log level for runtime logging (default: `"warn"`)            |
+| `rotation`       | positive integer                         | Number of days of app, launcher, and mpv logs to retain (default: 7) |
+| `files.app`      | boolean                                  | Write SubMiner app runtime logs (default: `true`)                    |
+| `files.launcher` | boolean                                  | Write launcher command logs (default: `true`)                        |
+| `files.mpv`      | boolean                                  | Write mpv player logs. Enable temporarily for mpv/plugin debugging.  |

 ### Updates

@@ -219,7 +204,7 @@ Configure automatic update checks and update notifications:

 | Option               | Values                                        | Description                                                                                         |
 | -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `enabled`            | `true`, `false`                               | Enable automatic background update checks. Manual tray and `subminer -u` checks are always allowed. |
+| `updates.enabled`    | `true`, `false`                               | Enable automatic background update checks. Manual tray and `subminer -u` checks are always allowed. |
 | `checkIntervalHours` | number                                        | Minimum hours between automatic update checks. Default `24`.                                        |
 | `notificationType`   | `"system"` \| `"osd"` \| `"both"` \| `"none"` | How SubMiner announces available updates. Default `"system"`.                                       |
 | `channel`            | `"stable"` \| `"prerelease"`                  | Release channel used for update checks. Use `"prerelease"` to test beta/RC releases.                |
@@ -287,10 +272,10 @@ See `config.example.jsonc` for detailed configuration options.
 }
 ```

-| Option    | Values                    | Description                                         |
-| --------- | ------------------------- | --------------------------------------------------- |
-| `enabled` | `true`, `false`, `"auto"` | Built-in subtitle websocket mode (default: `false`) |
-| `port`    | number                    | WebSocket server port (default: 6677)               |
+| Option              | Values                    | Description                                         |
+| ------------------- | ------------------------- | --------------------------------------------------- |
+| `websocket.enabled` | `true`, `false`, `"auto"` | Built-in subtitle websocket mode (default: `false`) |
+| `websocket.port`    | number                    | WebSocket server port (default: 6677)               |

 ### Annotation WebSocket

@@ -307,10 +292,10 @@ This stream includes subtitle text plus token metadata (N+1, known-word, frequen
 }
 ```

-| Option    | Values          | Description                                                    |
-| --------- | --------------- | -------------------------------------------------------------- |
-| `enabled` | `true`, `false` | Toggle annotated websocket stream (independent of `websocket`) |
-| `port`    | number          | Annotation websocket port (default: 6678)                      |
+| Option                        | Values          | Description                                                    |
+| ----------------------------- | --------------- | -------------------------------------------------------------- |
+| `annotationWebsocket.enabled` | `true`, `false` | Toggle annotated websocket stream (independent of `websocket`) |
+| `annotationWebsocket.port`    | number          | Annotation websocket port (default: 6678)                      |

 ### Texthooker

@@ -343,10 +328,10 @@ See `config.example.jsonc` for detailed configuration options.
 ```json
 {
  "subtitleStyle": {
-    "fontColor": "#cad3f5",
-    "backgroundColor": "transparent",
    "css": {
      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
+      "color": "#cad3f5",
+      "background-color": "transparent",
      "font-size": "35px",
      "font-weight": "600",
      "line-height": "1.35",
@@ -354,76 +339,80 @@ See `config.example.jsonc` for detailed configuration options.
      "word-spacing": "0",
      "font-kerning": "normal",
      "text-rendering": "geometricPrecision",
-      "text-shadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)",
+      "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)",
      "font-style": "normal",
-      "backdrop-filter": "blur(6px)"
+      "backdrop-filter": "blur(6px)",
+      "--subtitle-hover-token-color": "#f4dbd6",
+      "--subtitle-hover-token-background-color": "transparent"
    },
    "secondary": {
-      "fontColor": "#cad3f5",
-      "backgroundColor": "transparent",
      "css": {
        "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
+        "color": "#cad3f5",
+        "background-color": "transparent",
        "font-size": "24px",
-        "text-shadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)"
+        "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)"
      }
    }
  }
 }
 ```

-| 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                       |
+| Option                             | Values   | Description                                                                                                                  |
+| ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `primaryDefaultMode`               | string   | Default primary subtitle bar visibility mode: `"hidden"`, `"visible"`, or `"hover"` (default: `"visible"`)                 |
+| `subtitleStyle.css`                | object   | CSS declaration object applied to primary subtitles after normal style defaults. Use CSS property names such as `font-size`. |
+| `secondary.css`                    | object   | CSS declaration object applied to secondary subtitles after normal secondary style defaults.                                 |
+| `enableJlpt`                       | boolean  | Enable JLPT level underline styling (`false` by default)                                                                     |
+| `preserveLineBreaks`               | boolean  | Preserve line breaks in visible overlay subtitle rendering (`false` by default). Enable to mirror mpv line layout.           |
+| `autoPauseVideoOnHover`            | boolean  | Pause playback while mouse hovers subtitle text, then resume on leave (`true` by default).                                   |
+| `autoPauseVideoOnYomitanPopup`     | boolean  | Pause playback while the Yomitan popup is open, then resume when the popup closes (`true` by default).                       |
+| `primaryVisibleOnYomitanPopup`     | boolean  | Keep hover-mode primary subtitles visible while the Yomitan popup is open (`true` by default).                               |
+| `nameMatchEnabled`                 | boolean  | Enable character dictionary sync and subtitle token coloring for character-name matches (`false` by default)                 |
+| `nameMatchImagesEnabled`           | boolean  | Show small cached AniList character portraits beside matched character-name tokens (`false` by default)                      |
+| `nameMatchColor`                   | string   | Hex color used for subtitle tokens matched from the SubMiner character dictionary (default: `#f5bde6`)                       |
+| `knownWordColor`                   | string   | Hex color used for known-word subtitle highlights (default: `#a6da95`)                                                       |
+| `nPlusOneColor`                    | string   | Hex color used for the single N+1 target subtitle highlight (default: `#c6a0f6`)                                             |
+| `frequencyDictionary.enabled`      | boolean  | Enable frequency highlighting from dictionary lookups (`false` by default)                                                   |
+| `frequencyDictionary.sourcePath`   | string   | Path to a local frequency dictionary root. Leave empty or omit to use installed/default frequency-dictionary search paths.   |
+| `frequencyDictionary.topX`         | number   | Only color tokens whose frequency rank is `<= topX` (`10000` by default)                                                     |
+| `frequencyDictionary.mode`         | string   | `"single"` or `"banded"` (`"single"` by default)                                                                             |
+| `frequencyDictionary.matchMode`    | string   | `"headword"` or `"surface"` (`"headword"` by default)                                                                        |
+| `frequencyDictionary.singleColor`  | string   | Color used for all highlighted tokens in single mode                                                                         |
+| `frequencyDictionary.bandedColors` | string[] | Array of five hex colors used for ranked bands in banded mode                                                                |
+| `jlptColors`                       | object   | JLPT level underline colors object (`N1`..`N5`)                                                                              |
+
+Subtitle CSS custom properties:
+
+| CSS Property                              | Default       | Description                             |
+| ----------------------------------------- | ------------- | --------------------------------------- |
+| `--subtitle-hover-token-color`            | `#f4dbd6`     | Hovered subtitle token text color       |
+| `--subtitle-hover-token-background-color` | `transparent` | Hovered subtitle token background color |

 The Settings window keeps subtitle color controls separate, then saves CSS textboxes to
-`subtitleStyle.css`, `subtitleStyle.secondary.css`, and `subtitleSidebar.css`. The generated example
-uses that same CSS declaration shape; existing top-level style keys such as `fontSize` and
-`textShadow` remain supported for hand-written or older configs.
+the primary subtitle, secondary subtitle, and sidebar CSS objects. The generated example
+uses that same CSS declaration shape.

 Frequency dictionary highlighting uses the same dictionary file format as JLPT bundle lookups (`term_meta_bank_*.json` under discovered dictionary directories). A token is highlighted when it has a positive integer `frequencyRank` (lower is more common) and the rank is within `topX`.

 Lookup behavior:

- Set `frequencyDictionary.sourcePath` to a directory containing `term_meta_bank_*.json` for a fully custom source.
+- Point the source path at a directory containing `term_meta_bank_*.json` for a fully custom source.
 - If `sourcePath` is missing or empty, SubMiner searches default install/runtime locations for `frequency-dictionary` directories (for example app resources, user data paths, and current working directory).
 - In both cases, only terms with a valid `frequencyRank` are used; everything else falls back to no highlighting.
- `frequencyDictionary.matchMode` controls which token text is used for frequency lookups: `headword` (dictionary form) or `surface` (visible subtitle text).
+- Match mode controls which token text is used for frequency lookups: `headword` (dictionary form) or `surface` (visible subtitle text).
 - Frequency highlighting skips tokens that look like non-lexical SFX/interjection noise (for example kana reduplication or short kana endings like `っ`), even when dictionary ranks exist.

 In `single` mode all highlights use `singleColor`; in `banded` mode tokens map to five ascending color bands from most common to least common inside the topX window.

 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.
+- `nameMatchEnabled` controls whether SubMiner syncs the character dictionary and 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.
+- Matches come from the bundled SubMiner character dictionary, including AniList-synced merged dictionaries when name matching is enabled.

-Secondary subtitle defaults: `fontFamily: "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP"`, `fontSize: 24`, `fontColor: "#cad3f5"`, `textShadow: "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)"`, `backgroundColor: "transparent"`, `fontWeight: "600"`. Any property not set in `secondary` falls back to the CSS defaults.
+Secondary subtitle styling lives in the secondary subtitle CSS object. Any CSS property not set there falls back to the secondary subtitle defaults, then the normal renderer defaults.

 **See `config.example.jsonc`** for the complete list of subtitle style configuration options.

@@ -440,30 +429,36 @@ Configure the parsed-subtitle sidebar modal.
    "toggleKey": "Backslash",
    "pauseVideoOnHover": true,
    "autoScroll": true,
-    "fontFamily": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
-    "fontSize": 16
+    "css": {
+      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
+      "font-size": "16px",
+      "color": "#cad3f5",
+      "background-color": "rgba(73, 77, 100, 0.9)",
+      "--subtitle-sidebar-max-width": "420px"
+    }
  }
 }
 ```

-| Option                      | Values    | Description                                                                                             |
-| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
-| `enabled`                   | boolean   | Enable subtitle sidebar support (`true` by default)                                                     |
-| `autoOpen`                  | boolean   | Open sidebar automatically on overlay startup (`false` by default)                                      |
-| `layout`                    | string    | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space to mimic browser-like layout |
-| `toggleKey`                 | string    | `KeyboardEvent.code` used to open/close the sidebar (default: `"Backslash"`)                            |
-| `pauseVideoOnHover`         | boolean   | Pause playback while hovering the sidebar cue list (`true` by default)                                  |
-| `autoScroll`                | boolean   | Keep the active cue in view while playback advances                                                     |
-| `maxWidth`                  | number    | Maximum sidebar width in CSS pixels (default: `420`)                                                    |
-| `opacity`                   | number    | Sidebar opacity between `0` and `1` (default: `0.95`)                                                   |
-| `backgroundColor`           | string    | Sidebar shell background color                                                                          |
-| `textColor`                 | hex color | Default cue text color                                                                                  |
-| `fontFamily`                | string    | CSS `font-family` value applied to sidebar cue text                                                     |
-| `fontSize`                  | number    | Base sidebar cue font size in CSS pixels (default: `16`)                                                |
-| `timestampColor`            | hex color | Cue timestamp color                                                                                     |
-| `activeLineColor`           | hex color | Active cue text color                                                                                   |
-| `activeLineBackgroundColor` | string    | Active cue background color                                                                             |
-| `hoverLineBackgroundColor`  | string    | Hovered cue background color                                                                            |
+| Option                      | Values  | Description                                                                                             |
+| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `subtitleSidebar.enabled`   | boolean | Enable subtitle sidebar support (`true` by default)                                                     |
+| `autoOpen`                  | boolean | Open sidebar automatically on overlay startup (`false` by default)                                      |
+| `layout`                    | string  | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space to mimic browser-like layout |
+| `subtitleSidebar.toggleKey` | string  | `KeyboardEvent.code` used to open/close the sidebar (default: `"Backslash"`)                            |
+| `pauseVideoOnHover`         | boolean | Pause playback while hovering the sidebar cue list (`true` by default)                                  |
+| `autoScroll`                | boolean | Keep the active cue in view while playback advances                                                     |
+| `subtitleSidebar.css`       | object  | CSS declaration object applied to the sidebar. Use CSS properties plus sidebar custom properties below. |
+
+Sidebar CSS custom properties:
+
+| CSS Property                                 | Default                     | Description                  |
+| -------------------------------------------- | --------------------------- | ---------------------------- |
+| `--subtitle-sidebar-max-width`               | `420px`                     | Maximum sidebar width        |
+| `--subtitle-sidebar-timestamp-color`         | `#a5adcb`                   | Cue timestamp color          |
+| `--subtitle-sidebar-active-line-color`       | `#f5bde6`                   | Active cue text color        |
+| `--subtitle-sidebar-active-background-color` | `rgba(138, 173, 244, 0.22)` | Active cue background color  |
+| `--subtitle-sidebar-hover-background-color`  | `rgba(54, 58, 79, 0.84)`    | Hovered cue background color |

 The sidebar is only available when the active subtitle source has been parsed into a cue list. Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like an opaque settings dialog.

@@ -527,7 +522,7 @@ See `config.example.jsonc` for detailed configuration options.
 | `autoLoadSecondarySub`  | `true`, `false`                    | Auto-detect and load matching secondary subtitle track |
 | `defaultMode`           | `"hidden"`, `"visible"`, `"hover"` | Initial display mode (default: `"hover"`)              |

-`secondarySub.secondarySubLanguages` also acts as the fallback secondary-language priority for managed startup subtitle selection on local playback and YouTube playback.
+The secondary-subtitle language list also acts as the fallback secondary-language priority for managed startup subtitle selection on local playback and YouTube playback.

 **Display modes:**

@@ -616,7 +611,7 @@ See `config.example.jsonc` for detailed configuration options.
    "mineSentence": "CommandOrControl+S",
    "mineSentenceMultiple": "CommandOrControl+Shift+S",
    "markAudioCard": "CommandOrControl+Shift+A",
-    "openCharacterDictionary": "CommandOrControl+Alt+A",
+    "openCharacterDictionaryManager": "CommandOrControl+D",
    "openRuntimeOptions": "CommandOrControl+Shift+O",
    "openSessionHelp": "CommandOrControl+Slash",
    "openControllerSelect": "Alt+C",
@@ -628,26 +623,26 @@ See `config.example.jsonc` for detailed configuration options.
 }
 ```

-| Option                        | Values           | Description                                                                                                                                   |
-| ----------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `toggleVisibleOverlayGlobal`  | string \| `null` | Global accelerator for toggling visible subtitle overlay (default: `"Alt+Shift+O"`)                                                           |
-| `copySubtitle`                | string \| `null` | Accelerator for copying current subtitle (default: `"CommandOrControl+C"`)                                                                    |
-| `copySubtitleMultiple`        | string \| `null` | Accelerator for multi-copy mode (default: `"CommandOrControl+Shift+C"`)                                                                       |
-| `updateLastCardFromClipboard` | string \| `null` | Accelerator for updating card from clipboard (default: `"CommandOrControl+V"`)                                                                |
-| `triggerFieldGrouping`        | string \| `null` | Accelerator for Kiku field grouping on last card (default: `"CommandOrControl+G"`; only active when `behavior.autoUpdateNewCards` is `false`) |
-| `triggerSubsync`              | string \| `null` | Accelerator for running Subsync (default: `"Ctrl+Alt+S"`)                                                                                     |
-| `mineSentence`                | string \| `null` | Accelerator for creating sentence card from current subtitle (default: `"CommandOrControl+S"`)                                                |
-| `mineSentenceMultiple`        | string \| `null` | Accelerator for multi-mine sentence card mode (default: `"CommandOrControl+Shift+S"`)                                                         |
-| `multiCopyTimeoutMs`          | number           | Timeout in ms for multi-copy/mine digit input (default: `3000`)                                                                               |
-| `toggleSecondarySub`          | string \| `null` | Accelerator for cycling secondary subtitle mode (default: `"CommandOrControl+Shift+V"`)                                                       |
-| `markAudioCard`               | string \| `null` | Accelerator for marking last card as audio card (default: `"CommandOrControl+Shift+A"`)                                                       |
-| `openCharacterDictionary`     | string \| `null` | Opens the character dictionary AniList selector (default: `"CommandOrControl+Alt+A"`)                                                         |
-| `openRuntimeOptions`          | string \| `null` | Opens runtime options palette for live session-only toggles (default: `"CommandOrControl+Shift+O"`)                                           |
-| `openSessionHelp`             | string \| `null` | Opens the in-overlay session help modal (default: `"CommandOrControl+Slash"`)                                                                 |
-| `openControllerSelect`        | string \| `null` | Opens the controller config/remap modal (default: `"Alt+C"`)                                                                                  |
-| `openControllerDebug`         | string \| `null` | Opens the controller debug modal (default: `"Alt+Shift+C"`)                                                                                   |
-| `openJimaku`                  | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`)                                                                                     |
-| `toggleSubtitleSidebar`       | string \| `null` | Dispatches the subtitle sidebar toggle action (default: `"Backslash"`). `subtitleSidebar.toggleKey` remains the primary bare-key setting.     |
+| Option                           | Values           | Description                                                                                                                               |
+| -------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `toggleVisibleOverlayGlobal`     | string \| `null` | Global accelerator for toggling visible subtitle overlay (default: `"Alt+Shift+O"`)                                                       |
+| `copySubtitle`                   | string \| `null` | Accelerator for copying current subtitle (default: `"CommandOrControl+C"`)                                                                |
+| `copySubtitleMultiple`           | string \| `null` | Accelerator for multi-copy mode (default: `"CommandOrControl+Shift+C"`)                                                                   |
+| `updateLastCardFromClipboard`    | string \| `null` | Accelerator for updating card from clipboard (default: `"CommandOrControl+V"`)                                                            |
+| `triggerFieldGrouping`           | string \| `null` | Accelerator for Kiku field grouping on last card (default: `"CommandOrControl+G"`; only active when automatic card updates are disabled)  |
+| `triggerSubsync`                 | string \| `null` | Accelerator for running Subsync (default: `"Ctrl+Alt+S"`)                                                                                 |
+| `mineSentence`                   | string \| `null` | Accelerator for creating sentence card from current subtitle (default: `"CommandOrControl+S"`)                                            |
+| `mineSentenceMultiple`           | string \| `null` | Accelerator for multi-mine sentence card mode (default: `"CommandOrControl+Shift+S"`)                                                     |
+| `multiCopyTimeoutMs`             | number           | Timeout in ms for multi-copy/mine digit input (default: `3000`)                                                                           |
+| `toggleSecondarySub`             | string \| `null` | Accelerator for cycling secondary subtitle mode (default: `"CommandOrControl+Shift+V"`)                                                   |
+| `markAudioCard`                  | string \| `null` | Accelerator for marking last card as audio card (default: `"CommandOrControl+Shift+A"`)                                                   |
+| `openCharacterDictionaryManager` | string \| `null` | Opens the loaded character dictionary manager (default: `"CommandOrControl+D"`)                                                           |
+| `openRuntimeOptions`             | string \| `null` | Opens runtime options palette for live session-only toggles (default: `"CommandOrControl+Shift+O"`)                                       |
+| `openSessionHelp`                | string \| `null` | Opens the in-overlay session help modal (default: `"CommandOrControl+Slash"`)                                                             |
+| `openControllerSelect`           | string \| `null` | Opens the controller config/remap modal (default: `"Alt+C"`)                                                                              |
+| `openControllerDebug`            | string \| `null` | Opens the controller debug modal (default: `"Alt+Shift+C"`)                                                                               |
+| `openJimaku`                     | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`)                                                                                 |
+| `toggleSubtitleSidebar`          | string \| `null` | Dispatches the subtitle sidebar toggle action (default: `"Backslash"`). `subtitleSidebar.toggleKey` remains the primary bare-key setting. |

 **See `config.example.jsonc`** for the complete list of shortcut configuration options.

@@ -672,7 +667,7 @@ Important behavior:
 - Learned bindings are saved under `controller.profiles` for the selected controller id. Global `controller.bindings` remains the fallback for controllers without a profile.
 - `Alt+Shift+C` opens the debug modal by default, and you can remap that shortcut through `shortcuts.openControllerDebug`.
 - The debug modal shows raw axes/button values plus a ready-to-copy `buttonIndices` config block.
- `controller.buttonIndices` is a semantic reference/legacy mapping. Changing it does not rewrite the raw numeric descriptor values already stored under `controller.bindings`.
+- The button-index map is a semantic reference mapping. Changing it does not rewrite the raw numeric descriptor values already stored under controller bindings.
 - Turning keyboard-only mode off clears the keyboard-only token highlight state.
 - Closing the Yomitan popup clears the temporary native text-selection fill, but keeps controller token selection active.

@@ -761,11 +756,11 @@ If you bind a discrete action to an axis manually, include `direction`:
 }
 ```

-Treat `controller.buttonIndices` as reference-only unless you are still using legacy semantic bindings or copying values from the debug modal. Updating `controller.buttonIndices` alone does not rewrite the hardcoded raw numeric values already present in `controller.bindings` or `controller.profiles.*.bindings`. If you need a real remap, prefer the `Alt+C` learn flow so both the source and the descriptor shape stay correct.
+Treat the button-index map as reference-only unless you are copying values from the debug modal. Updating it alone does not rewrite the hardcoded raw numeric values already present in controller bindings or controller profiles. If you need a real remap, prefer the `Alt+C` learn flow so both the source and the descriptor shape stay correct.

 If you choose to bind `L2` or `R2` manually, set `triggerInputMode` to `analog` and tune `triggerDeadzone` when your controller reports triggers as analog values instead of digital pressed/not-pressed buttons. `auto` accepts either style and remains the default.

-If one controller reports non-standard raw button numbers, override `controller.profiles["<controller id>"].buttonIndices` using values from the `Alt+Shift+C` debug modal. Use global `controller.buttonIndices` only when the mapping should apply to every controller without a profile.
+If one controller reports non-standard raw button numbers, override that controller profile's button-index map using values from the `Alt+Shift+C` debug modal. Use the global button-index map only when the mapping should apply to every controller without a profile.

 If you update this controller documentation or the generated controller examples, run `bun run docs:test` and `bun run docs:build` before merging.

@@ -773,21 +768,21 @@ Tune `scrollPixelsPerSecond`, `horizontalJumpPixels`, deadzones, repeat timing,

 ### Manual Card Update Shortcuts

-When `behavior.autoUpdateNewCards` is set to `false`, new cards are detected but not automatically updated. Use these keyboard shortcuts for manual control:
+When automatic card updates are disabled, new cards are detected but not automatically updated. Use these keyboard shortcuts for manual control:

-| Shortcut       | Action                                                                                                             |
-| -------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `Ctrl+C`       | Copy the current subtitle line to clipboard (preserves line breaks)                                                |
-| `Ctrl+Shift+C` | Enter multi-copy mode. Press `1-9` to copy that many recent lines, or `Esc` to cancel. Timeout: 3 seconds          |
-| `Ctrl+V`       | Update the last added Anki card using subtitles from clipboard                                                     |
-| `Ctrl+G`       | Trigger Kiku duplicate field grouping for the last added card (only when `behavior.autoUpdateNewCards` is `false`) |
-| `Ctrl+S`       | Create a sentence card from the current subtitle line                                                              |
-| `Ctrl+Shift+S` | Enter multi-mine mode. Press `1-9` to create a sentence card from that many recent lines, or `Esc` to cancel       |
-| `Ctrl+Shift+V` | Cycle secondary subtitle display mode (hidden → visible → hover)                                                   |
-| `Ctrl+Shift+A` | Mark the last added Anki card as an audio card (sets IsAudioCard, SentenceAudio, Sentence, Picture)                |
-| `Ctrl+Alt+A`   | Open character dictionary AniList selector                                                                         |
-| `Ctrl+Shift+O` | Open runtime options palette (session-only live toggles)                                                           |
-| `Ctrl/Cmd+A`   | Append clipboard video path to MPV playlist (fixed, not currently configurable)                                    |
+| Shortcut       | Action                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------- |
+| `Ctrl+C`       | Copy the current subtitle line to clipboard (preserves line breaks)                                           |
+| `Ctrl+Shift+C` | Enter multi-copy mode. Press `1-9` to copy that many recent lines, or `Esc` to cancel. Timeout: 3 seconds     |
+| `Ctrl+V`       | Update the last added Anki card using subtitles from clipboard                                                |
+| `Ctrl+G`       | Trigger Kiku duplicate field grouping for the last added card (only when automatic card updates are disabled) |
+| `Ctrl+S`       | Create a sentence card from the current subtitle line                                                         |
+| `Ctrl+Shift+S` | Enter multi-mine mode. Press `1-9` to create a sentence card from that many recent lines, or `Esc` to cancel  |
+| `Ctrl+Shift+V` | Cycle secondary subtitle display mode (hidden → visible → hover)                                              |
+| `Ctrl+Shift+A` | Mark the last added Anki card as an audio card (sets IsAudioCard, SentenceAudio, Sentence, Picture)           |
+| `Ctrl+D`       | Open loaded character dictionary manager                                                                      |
+| `Ctrl+Shift+O` | Open runtime options palette (session-only live toggles)                                                      |
+| `Ctrl/Cmd+A`   | Append clipboard video path to MPV playlist (fixed, not currently configurable)                               |

 **Multi-line copy workflow:**

@@ -826,16 +821,11 @@ When config hot-reload updates shortcut/keybinding/style values, close and reope

 Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.

-Current runtime options:
+Current runtime options cover automatic card updates, known-word highlighting,
+JLPT underlines, frequency highlighting, known-word match mode, and Kiku field
+grouping mode.

- `ankiConnect.behavior.autoUpdateNewCards` (`On` / `Off`)
- `ankiConnect.knownWords.highlightEnabled` (`On` / `Off`)
- `subtitleStyle.enableJlpt` (`On` / `Off`)
- `subtitleStyle.frequencyDictionary.enabled` (`On` / `Off`)
- `ankiConnect.knownWords.matchMode` (`headword` / `surface`)
- `ankiConnect.isKiku.fieldGrouping` (`auto` / `manual` / `disabled`)
-
-Annotation toggles (`nPlusOne`, `enableJlpt`, `frequencyDictionary.enabled`) only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.
+Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.

 Default shortcut: `Ctrl+Shift+O`

@@ -865,19 +855,19 @@ 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                                                                          |
+| ------------------ | -------------------- | ------------------------------------------------------------------------------------ |
+| `ai.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:

- Anki translation/enrichment when `ankiConnect.ai.enabled` is `true`
+- Anki translation/enrichment when Anki AI is enabled

 ### AnkiConnect

@@ -907,8 +897,8 @@ Enable automatic Anki card creation and updates with media generation:
    },
    "ai": {
      "enabled": false,
-      "model": "openai/gpt-4o-mini",
-      "systemPrompt": "Translate mined sentence text only."
+      "model": "",
+      "systemPrompt": ""
    },
    "media": {
      "generateAudio": true,
@@ -916,11 +906,11 @@ Enable automatic Anki card creation and updates with media generation:
      "imageType": "static",
      "imageFormat": "jpg",
      "imageQuality": 92,
-      "imageMaxWidth": 1280,
-      "imageMaxHeight": 720,
+      "imageMaxWidth": 0,
+      "imageMaxHeight": 0,
      "animatedFps": 10,
      "animatedMaxWidth": 640,
-      "animatedMaxHeight": 360,
+      "animatedMaxHeight": 0,
      "animatedCrf": 35,
      "audioPadding": 0,
      "fallbackDuration": 3,
@@ -935,8 +925,8 @@ Enable automatic Anki card creation and updates with media generation:
      "pattern": "[SubMiner] %f (%t)"
    },
    "isLapis": {
-      "enabled": true,
-      "sentenceCardModel": "Japanese sentences"
+      "enabled": false,
+      "sentenceCardModel": "Lapis"
    },
    "isKiku": {
      "enabled": false,
@@ -951,58 +941,57 @@ This example is intentionally compact. The option table below documents availabl

 **Requirements:** [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin must be installed and running in Anki. ffmpeg must be installed for media generation.

-| Option                                            | Values                                  | Description                                                                                                                                                                                         |
-| ------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`                                         | `true`, `false`                         | Enable AnkiConnect integration (default: `true`)                                                                                                                                                    |
-| `url`                                             | string (URL)                            | AnkiConnect API URL (default: `http://127.0.0.1:8765`)                                                                                                                                              |
-| `pollingRate`                                     | number (ms)                             | How often to check for new cards in polling mode (default: `3000`; ignored for direct proxy `addNote`/`addNotes` updates)                                                                           |
-| `proxy.enabled`                                   | `true`, `false`                         | Enable local AnkiConnect-compatible proxy for push-based auto-enrichment (default: `true`)                                                                                                          |
-| `proxy.host`                                      | string                                  | Bind host for local AnkiConnect proxy (default: `127.0.0.1`)                                                                                                                                        |
-| `proxy.port`                                      | number                                  | Bind port for local AnkiConnect proxy (default: `8766`)                                                                                                                                             |
-| `proxy.upstreamUrl`                               | string (URL)                            | Upstream AnkiConnect URL that proxy forwards to (default: `http://127.0.0.1:8765`)                                                                                                                  |
-| `tags`                                            | array of strings                        | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                                                                       |
-| `ankiConnect.deck`                                | string                                  | Legacy Anki polling/compatibility scope. Newer known-word cache scoping should use `ankiConnect.knownWords.decks`.                                                                                  |
-| `ankiConnect.knownWords.decks`                    | object                                  | Deck→fields mapping for known-word cache queries (for example `{ "Kaishi 1.5k": ["Word", "Word Reading"] }`).                                                                                       |
-| `fields.word`                                     | string                                  | Card field for mined word / expression text (default: `Expression`)                                                                                                                                 |
-| `fields.audio`                                    | string                                  | Card field for audio files (default: `ExpressionAudio`)                                                                                                                                             |
-| `fields.image`                                    | string                                  | Card field for images (default: `Picture`)                                                                                                                                                          |
-| `fields.sentence`                                 | string                                  | Card field for sentences (default: `Sentence`)                                                                                                                                                      |
-| `fields.miscInfo`                                 | string                                  | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                                                                           |
-| `fields.translation`                              | string                                  | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                                                                       |
-| `ankiConnect.ai.enabled`                          | `true`, `false`                         | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                                                                      |
-| `ankiConnect.ai.model`                            | string                                  | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                   |
-| `ankiConnect.ai.systemPrompt`                     | string                                  | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                           |
-| `media.generateAudio`                             | `true`, `false`                         | Generate audio clips from video (default: `true`)                                                                                                                                                   |
-| `media.generateImage`                             | `true`, `false`                         | Generate image/animation screenshots (default: `true`)                                                                                                                                              |
-| `media.imageType`                                 | `"static"`, `"avif"`                    | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                |
-| `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`              | Image format (default: `"jpg"`)                                                                                                                                                                     |
-| `media.imageQuality`                              | number (1-100)                          | Image quality for JPG/WebP; PNG ignores this (default: `92`)                                                                                                                                        |
-| `media.imageMaxWidth`                             | number (px)                             | Optional max width for static screenshots. Unset keeps source width.                                                                                                                                |
-| `media.imageMaxHeight`                            | number (px)                             | Optional max height for static screenshots. Unset keeps source height.                                                                                                                              |
-| `media.animatedFps`                               | number (1-60)                           | FPS for animated AVIF (default: `10`)                                                                                                                                                               |
-| `media.animatedMaxWidth`                          | number (px)                             | Max width for animated AVIF (default: `640`)                                                                                                                                                        |
-| `media.animatedMaxHeight`                         | number (px)                             | Optional max height for animated AVIF. Unset keeps source aspect-constrained height.                                                                                                                |
-| `media.animatedCrf`                               | number (0-63)                           | CRF quality for AVIF; lower = higher quality (default: `35`)                                                                                                                                        |
-| `media.syncAnimatedImageToWordAudio`              | `true`, `false`                         | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`).                                                                                             |
-| `media.audioPadding`                              | number (seconds)                        | Optional padding around audio clip timing (default: `0`). Animated AVIF clips freeze the first frame during leading audio padding.                                                                  |
-| `media.fallbackDuration`                          | number (seconds)                        | Default duration if timing unavailable (default: `3.0`)                                                                                                                                             |
-| `media.maxMediaDuration`                          | number (seconds)                        | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                                                                               |
-| `behavior.overwriteAudio`                         | `true`, `false`                         | Replace existing audio on updates; when `false`, new audio is appended/prepended per `behavior.mediaInsertMode`; manual clipboard updates always replace generated sentence audio (default: `true`) |
-| `behavior.overwriteImage`                         | `true`, `false`                         | Replace existing images on updates; when `false`, new images are appended/prepended per `behavior.mediaInsertMode` (default: `true`)                                                                |
-| `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                 | Where to insert new media when overwrite is off (default: `"append"`)                                                                                                                               |
-| `behavior.highlightWord`                          | `true`, `false`                         | Highlight the word in sentence context (default: `true`)                                                                                                                                            |
-| `ankiConnect.knownWords.highlightEnabled`         | `true`, `false`                         | Enable fast local highlighting for words already known in Anki (default: `false`)                                                                                                                   |
-| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`, `false`                         | Add words from successful mines into the local known-word cache immediately (default: `true`)                                                                                                       |
-| `ankiConnect.knownWords.matchMode`                | `"headword"`, `"surface"`               | Matching strategy for known-word highlighting (default: `"headword"`). `headword` uses token headwords; `surface` uses visible subtitle text.                                                       |
-| `ankiConnect.knownWords.refreshMinutes`           | number                                  | Minutes between known-word cache refreshes (default: `1440`)                                                                                                                                        |
-| `ankiConnect.knownWords.decks`                    | object                                  | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word", "Word Reading"] }`).                                                                                     |
-| `ankiConnect.nPlusOne.enabled`                    | `true`, `false`                         | Enable N+1 subtitle highlighting (highlights the one unknown word in a sentence). Independent from `knownWords.highlightEnabled`. Requires known-word cache data (default: `false`).                |
-| `ankiConnect.nPlusOne.minSentenceWords`           | number                                  | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                                                                              |
-| `behavior.notificationType`                       | `"osd"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"osd"`)                                                                                                                                                 |
-| `behavior.autoUpdateNewCards`                     | `true`, `false`                         | Automatically update cards on creation (default: `true`)                                                                                                                                            |
-| `metadata.pattern`                                | string                                  | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time                                                                                                                            |
-| `isLapis`                                         | object                                  | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                        |
-| `isKiku`                                          | object                                  | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                           |
+| Option                                            | Values                                  | Description                                                                                                                                                                                                 |
+| ------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ankiConnect.enabled`                             | `true`, `false`                         | Enable AnkiConnect integration (default: `true`)                                                                                                                                                            |
+| `url`                                             | string (URL)                            | AnkiConnect API URL (default: `http://127.0.0.1:8765`)                                                                                                                                                      |
+| `pollingRate`                                     | number (ms)                             | How often to check for new cards in polling mode (default: `3000`; ignored for direct proxy `addNote`/`addNotes` updates)                                                                                   |
+| `proxy.enabled`                                   | `true`, `false`                         | Enable local AnkiConnect-compatible proxy for push-based auto-enrichment (default: `true`)                                                                                                                  |
+| `proxy.host`                                      | string                                  | Bind host for local AnkiConnect proxy (default: `127.0.0.1`)                                                                                                                                                |
+| `proxy.port`                                      | number                                  | Bind port for local AnkiConnect proxy (default: `8766`)                                                                                                                                                     |
+| `proxy.upstreamUrl`                               | string (URL)                            | Upstream AnkiConnect URL that proxy forwards to (default: `http://127.0.0.1:8765`)                                                                                                                          |
+| `tags`                                            | array of strings                        | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                                                                               |
+| `ankiConnect.deck`                                | string                                  | Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to search all decks. In Settings, this dropdown auto-fills from Yomitan's current mining deck when available.               |
+| `fields.word`                                     | string                                  | Card field for mined word / expression text (default: `Expression`)                                                                                                                                         |
+| `fields.audio`                                    | string                                  | Card field for audio files (default: `ExpressionAudio`)                                                                                                                                                     |
+| `fields.image`                                    | string                                  | Card field for images (default: `Picture`)                                                                                                                                                                  |
+| `fields.sentence`                                 | string                                  | Card field for sentences (default: `Sentence`)                                                                                                                                                              |
+| `fields.miscInfo`                                 | string                                  | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                                                                                   |
+| `fields.translation`                              | string                                  | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                                                                               |
+| `ankiConnect.ai.enabled`                          | `true`, `false`                         | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                                                                              |
+| `ankiConnect.ai.model`                            | string                                  | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                           |
+| `ankiConnect.ai.systemPrompt`                     | string                                  | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                                   |
+| `media.generateAudio`                             | `true`, `false`                         | Generate audio clips from video (default: `true`)                                                                                                                                                           |
+| `media.generateImage`                             | `true`, `false`                         | Generate image/animation screenshots (default: `true`)                                                                                                                                                      |
+| `media.imageType`                                 | `"static"`, `"avif"`                    | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                        |
+| `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`              | Image format (default: `"jpg"`)                                                                                                                                                                             |
+| `media.imageQuality`                              | number (1-100)                          | Image quality for JPG/WebP; PNG ignores this (default: `92`)                                                                                                                                                |
+| `media.imageMaxWidth`                             | number (px)                             | Optional max width for static screenshots. Unset keeps source width.                                                                                                                                        |
+| `media.imageMaxHeight`                            | number (px)                             | Optional max height for static screenshots. Unset keeps source height.                                                                                                                                      |
+| `media.animatedFps`                               | number (1-60)                           | FPS for animated AVIF (default: `10`)                                                                                                                                                                       |
+| `media.animatedMaxWidth`                          | number (px)                             | Max width for animated AVIF (default: `640`)                                                                                                                                                                |
+| `media.animatedMaxHeight`                         | number (px)                             | Optional max height for animated AVIF. Unset keeps source aspect-constrained height.                                                                                                                        |
+| `media.animatedCrf`                               | number (0-63)                           | CRF quality for AVIF; lower = higher quality (default: `35`)                                                                                                                                                |
+| `media.syncAnimatedImageToWordAudio`              | `true`, `false`                         | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`).                                                                                                     |
+| `media.audioPadding`                              | number (seconds)                        | Optional padding around generated sentence media timing (default: `0`). Animated AVIF clips include the same padded source range as sentence audio.                                                         |
+| `media.fallbackDuration`                          | number (seconds)                        | Default duration if timing unavailable (default: `3.0`)                                                                                                                                                     |
+| `media.maxMediaDuration`                          | number (seconds)                        | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                                                                                       |
+| `behavior.overwriteAudio`                         | `true`, `false`                         | Replace existing audio on updates; when `false`, new audio is appended/prepended using the configured media insert mode; manual clipboard updates always replace generated sentence audio (default: `true`) |
+| `behavior.overwriteImage`                         | `true`, `false`                         | Replace existing images on updates; when `false`, new images are appended/prepended using the configured media insert mode (default: `true`)                                                                |
+| `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                 | Where to insert new media when overwrite is off (default: `"append"`)                                                                                                                                       |
+| `behavior.highlightWord`                          | `true`, `false`                         | Highlight the word in sentence context (default: `true`)                                                                                                                                                    |
+| `ankiConnect.knownWords.highlightEnabled`         | `true`, `false`                         | Enable fast local highlighting for words already known in Anki (default: `false`)                                                                                                                           |
+| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`, `false`                         | Add words from successful mines into the local known-word cache immediately (default: `true`)                                                                                                               |
+| `ankiConnect.knownWords.matchMode`                | `"headword"`, `"surface"`               | Matching strategy for known-word highlighting (default: `"headword"`). `headword` uses token headwords; `surface` uses visible subtitle text.                                                               |
+| `ankiConnect.knownWords.refreshMinutes`           | number                                  | Minutes between known-word cache refreshes (default: `1440`)                                                                                                                                                |
+| `ankiConnect.knownWords.decks`                    | object                                  | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word"] }`).                                                                                                             |
+| `ankiConnect.nPlusOne.enabled`                    | `true`, `false`                         | Enable N+1 subtitle highlighting (highlights the one unknown word in a sentence). Independent from `knownWords.highlightEnabled`. Requires known-word cache data (default: `false`).                        |
+| `ankiConnect.nPlusOne.minSentenceWords`           | number                                  | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                                                                                      |
+| `behavior.notificationType`                       | `"osd"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"osd"`)                                                                                                                                                         |
+| `behavior.autoUpdateNewCards`                     | `true`, `false`                         | Automatically update cards on creation (default: `true`)                                                                                                                                                    |
+| `metadata.pattern`                                | string                                  | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time                                                                                                                                    |
+| `isLapis`                                         | object                                  | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                                |
+| `isKiku`                                          | object                                  | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                                   |

 `ankiConnect.ai` only controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
 API key resolution, base URL, and timeout live under the shared top-level [`ai`](#shared-ai-provider) config.
@@ -1032,21 +1021,21 @@ SubMiner is intentionally built for [Kiku](https://kiku.youyoumu.my.id/) and [La

 ### N+1 Word Highlighting

-When `ankiConnect.knownWords.highlightEnabled` is enabled, SubMiner builds a local cache of known words from Anki to highlight already learned tokens in subtitle rendering.
+When known-word highlighting is enabled, SubMiner builds a local cache of known words from Anki to highlight already learned tokens in subtitle rendering.

 Known-word cache policy:

 - Initial sync runs when the integration starts if the cache is missing or stale.
- `ankiConnect.knownWords.refreshMinutes` controls the minimum time between refreshes; between refreshes, cached words are reused without querying Anki.
+- The refresh interval controls the minimum time between syncs; between refreshes, cached words are reused without querying Anki.
 - `subtitleStyle.nPlusOneColor` sets the color for the single target token when exactly one eligible unknown word exists.
- `ankiConnect.nPlusOne.minSentenceWords` sets the minimum token count required in a sentence for N+1 highlighting (default: `3`).
+- The N+1 minimum sentence-word setting controls the token count required before N+1 highlighting can trigger.
 - `subtitleStyle.knownWordColor` sets the known-word highlight color for tokens already in Anki.
- `ankiConnect.knownWords.decks` accepts an object keyed by deck name. If omitted or empty, it falls back to the legacy `ankiConnect.deck` single-deck scope.
+- The known-word deck map accepts an object keyed by deck name.
+- Prefer expression/word fields such as `Expression` or `Word`. Avoid reading-only fields unless you intentionally want homophone readings to count as known words.
 - 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.
- 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.
+- Cache lookups are in-memory. By default, token headwords are matched against cached `Expression` / `Word` values; set known-word matching 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.
 - If AnkiConnect is unreachable, the cache remains in its previous state and an on-screen/system status message is shown.
 - Known-word sync activity is logged at `INFO`/`DEBUG` level with the `anki` logger scope and includes scope, notes returned, and word counts.

@@ -1124,12 +1113,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.
@@ -1144,10 +1133,7 @@ AniList integration is opt-in and disabled by default. Enable it to allow SubMin
    "enabled": true,
    "accessToken": "",
    "characterDictionary": {
-      "enabled": false,
-      "refreshTtlHours": 168,
      "maxLoaded": 3,
-      "evictionPolicy": "delete",
      "profileScope": "all",
      "collapsibleSections": {
        "description": false,
@@ -1159,18 +1145,15 @@ AniList integration is opt-in and disabled by default. Enable it to allow SubMin
 }
 ```

-| Option                                                         | Values                  | Description                                                                                                   |
-| -------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `enabled`                                                      | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                                 |
-| `accessToken`                                                  | string                  | Optional explicit AniList access token override (default: empty string)                                       |
-| `characterDictionary.enabled`                                  | `true`, `false`         | Enable automatic import/update of the merged SubMiner character dictionary for recent AniList media           |
-| `characterDictionary.refreshTtlHours`                          | number                  | Legacy compatibility setting. Parsed and preserved, but merged dictionary retention is now usage-based        |
-| `characterDictionary.maxLoaded`                                | number                  | Maximum number of most-recently-used AniList media snapshots included in the merged dictionary (default: `3`) |
-| `characterDictionary.evictionPolicy`                           | `"delete"`, `"disable"` | Legacy compatibility setting. Parsed and preserved, but merged dictionary eviction is now usage-based         |
-| `characterDictionary.collapsibleSections.description`          | `true`, `false`         | Open the Description section by default in generated dictionary entries                                       |
-| `characterDictionary.collapsibleSections.characterInformation` | `true`, `false`         | Open the Character Information section by default in generated dictionary entries                             |
-| `characterDictionary.collapsibleSections.voicedBy`             | `true`, `false`         | Open the Voiced by section by default in generated dictionary entries                                         |
-| `characterDictionary.profileScope`                             | `"all"`, `"active"`     | Apply dictionary settings updates to all Yomitan profiles or only active profile                              |
+| Option                                                         | Values              | Description                                                                                                   |
+| -------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `anilist.enabled`                                              | `true`, `false`     | Enable AniList post-watch progress updates (default: `false`)                                                 |
+| `accessToken`                                                  | string              | Optional explicit AniList access token override (default: empty string)                                       |
+| `characterDictionary.maxLoaded`                                | number              | Maximum number of most-recently-used AniList media snapshots included in the merged dictionary (default: `3`) |
+| `characterDictionary.collapsibleSections.description`          | `true`, `false`     | Open the Description section by default in generated dictionary entries                                       |
+| `characterDictionary.collapsibleSections.characterInformation` | `true`, `false`     | Open the Character Information section by default in generated dictionary entries                             |
+| `characterDictionary.collapsibleSections.voicedBy`             | `true`, `false`     | Open the Voiced by section by default in generated dictionary entries                                         |
+| `characterDictionary.profileScope`                             | `"all"`, `"active"` | Apply dictionary settings updates to all Yomitan profiles or only active profile                              |

 When `enabled` is `true` and `accessToken` is empty, SubMiner opens an AniList setup helper window. Keep `enabled` as `false` to disable all AniList setup/update behavior.

@@ -1193,7 +1176,7 @@ Current post-watch behavior:
 Setup flow details:

 1. Set `anilist.enabled` to `true`.
-2. Leave `anilist.accessToken` empty and restart SubMiner (or run `--anilist-setup`) to trigger setup.
+2. Leave the AniList access-token field empty and restart SubMiner (or run `--anilist-setup`) to trigger setup.
 3. Approve access in AniList.
 4. Callback flow returns to SubMiner via `subminer://anilist-setup?...`, and SubMiner stores the token automatically.
   - Encryption backend: Linux defaults to `gnome-libsecret`.
@@ -1201,7 +1184,7 @@ Setup flow details:

 Token + detection notes:

- `anilist.accessToken` can be set directly in config; when blank, SubMiner uses the locally stored encrypted token from setup.
+- The AniList access token can be set directly in config; when blank, SubMiner uses the locally stored encrypted token from setup.
 - Detection quality is best when `guessit` is installed and available on `PATH`.
 - When `guessit` cannot parse or is missing, SubMiner falls back automatically to internal filename parsing.

@@ -1237,7 +1220,7 @@ External-profile mode behavior:
 - SubMiner does not open its own Yomitan settings window in this mode.
 - SubMiner does not import, delete, or update dictionaries/settings in the external profile.
 - SubMiner character-dictionary features are fully disabled in this mode, including auto-sync, manual generation, and subtitle-side character-dictionary annotations.
- First-run setup does not require any internal dictionaries while this mode is configured. If you later launch without `yomitan.externalProfilePath`, setup will require at least one internal Yomitan dictionary unless SubMiner already finds one.
+- First-run setup does not require any internal dictionaries while this mode is configured. If you later launch without an external Yomitan profile, setup will require at least one internal Yomitan dictionary unless SubMiner already finds one.

 ### Jellyfin

@@ -1253,7 +1236,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"],
@@ -1262,27 +1244,23 @@ Jellyfin integration is optional and disabled by default. When enabled, SubMiner
 }
 ```

-| Option                     | Values          | Description                                                                                                  |
-| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
-| `enabled`                  | `true`, `false` | Enable Jellyfin integration and CLI commands (default: `false`)                                              |
-| `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`)                                                   |
+| Option                     | Values          | Description                                                                                            |
+| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------ |
+| `jellyfin.enabled`         | `true`, `false` | Enable Jellyfin integration and CLI commands (default: `false`)                                        |
+| `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`                                                            |
+| `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 integration and remote control) |
+| `autoAnnounce`             | `true`, `false` | Auto-run cast-target visibility announce check on connect (default: `false`)                           |
+| `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. 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.

@@ -1297,7 +1275,9 @@ Launcher subcommands:

 See [Jellyfin Integration](/jellyfin-integration) for the full setup and cast-to-device guide.

-Jellyfin remote auto-connect runs only when all three are `true`: `jellyfin.enabled`, `jellyfin.remoteControlEnabled`, and `jellyfin.remoteControlAutoConnect`.
+Jellyfin remote auto-connect runs only when Jellyfin integration, remote control, and remote auto-connect are all enabled.
+
+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.

@@ -1316,12 +1296,12 @@ Discord Rich Presence is enabled by default. SubMiner publishes a polished activ
 }
 ```

-| Option             | Values                                           | Description                                                |
-| ------------------ | ------------------------------------------------ | ---------------------------------------------------------- |
-| `enabled`          | `true`, `false`                                  | Enable Discord Rich Presence updates (default: `true`)     |
-| `presenceStyle`    | `"default"`, `"meme"`, `"japanese"`, `"minimal"` | Card text preset (default: `"default"`)                    |
-| `updateIntervalMs` | number                                           | Minimum interval between activity updates in milliseconds  |
-| `debounceMs`       | number                                           | Debounce window for bursty playback events in milliseconds |
+| Option                    | Values                                           | Description                                                |
+| ------------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
+| `discordPresence.enabled` | `true`, `false`                                  | Enable Discord Rich Presence updates (default: `true`)     |
+| `presenceStyle`           | `"default"`, `"meme"`, `"japanese"`, `"minimal"` | Card text preset (default: `"default"`)                    |
+| `updateIntervalMs`        | number                                           | Minimum interval between activity updates in milliseconds  |
+| `debounceMs`              | number                                           | Debounce window for bursty playback events in milliseconds |

 Setup steps:

@@ -1383,7 +1363,7 @@ Enable or disable local immersion analytics stored in SQLite for mined subtitles

 | Option                         | Values                              | Description                                                                                                 |
 | ------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `enabled`                      | `true`, `false`                     | Enable immersion tracking. Defaults to `true`.                                                              |
+| `immersionTracking.enabled`    | `true`, `false`                     | Enable immersion tracking. Defaults to `true`.                                                              |
 | `dbPath`                       | string                              | Optional SQLite database path. Leave empty to use default app-data path at `<config dir>/immersion.sqlite`. |
 | `batchSize`                    | integer (`1`-`10000`)               | Buffered writes per transaction. Default `25`.                                                              |
 | `flushIntervalMs`              | integer (`50`-`60000`)              | Maximum queue delay before flush. Default `500ms`.                                                          |
@@ -1398,6 +1378,9 @@ Enable or disable local immersion analytics stored in SQLite for mined subtitles
 | `retention.dailyRollupsDays`   | integer (`0`-`36500`)               | Daily rollup retention window. Default `0` (keep all).                                                      |
 | `retention.monthlyRollupsDays` | integer (`0`-`36500`)               | Monthly rollup retention window. Default `0` (keep all).                                                    |
 | `retention.vacuumIntervalDays` | integer (`0`-`3650`)                | Minimum spacing between `VACUUM` passes. `0` disables vacuum. Default `0` (disabled).                       |
+| `lifetimeSummaries.global`     | `true`, `false`                     | Maintain global lifetime stats rows (default: `true`).                                                              |
+| `lifetimeSummaries.anime`      | `true`, `false`                     | Maintain per-anime lifetime stats rows (default: `true`).                                                           |
+| `lifetimeSummaries.media`      | `true`, `false`                     | Maintain per-media lifetime stats rows (default: `true`).                                                           |

 You can also disable immersion tracking for a single session using:

@@ -1427,6 +1410,7 @@ Configure the local stats UI served from SubMiner and the in-app stats overlay t
 {
  "stats": {
    "toggleKey": "Backquote",
+    "markWatchedKey": "KeyW",
    "serverPort": 6969,
    "autoStartServer": true,
    "autoOpenBrowser": false
@@ -1436,7 +1420,8 @@ Configure the local stats UI served from SubMiner and the in-app stats overlay t

 | Option            | Values            | Description                                                                                                          |
 | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `toggleKey`       | Electron key code | Overlay-local key code used to toggle the stats overlay. Default `Backquote`.                                        |
+| `stats.toggleKey` | Electron key code | Overlay-local key code used to toggle the stats overlay. Default `Backquote`.                                        |
+| `markWatchedKey`  | Electron key code | Key code to mark the current video as watched and advance to the next playlist entry. Default `KeyW`.                |
 | `serverPort`      | integer           | Localhost port for the browser stats UI. Default `6969`.                                                             |
 | `autoStartServer` | `true`, `false`   | Start the local stats HTTP server automatically once immersion tracking is active. Default `true`.                   |
 | `autoOpenBrowser` | `true`, `false`   | When `subminer stats` starts the server on demand, also open the dashboard in your default browser. Default `false`. |
@@ -1456,17 +1441,31 @@ Configure the mpv executable, profile, and window state for SubMiner-managed mpv
 {
  "mpv": {
    "executablePath": "",
+    "launchMode": "normal",
    "profile": "",
-    "launchMode": "normal"
+    "socketPath": "\\\\.\\pipe\\subminer-socket",
+    "backend": "auto",
+    "autoStartSubMiner": true,
+    "pauseUntilOverlayReady": true,
+    "subminerBinaryPath": "",
+    "aniskipEnabled": true,
+    "aniskipButtonKey": "TAB"
  }
 }
 ```

-| Option           | Values                                        | Description                                                                                                                         |
-| ---------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `executablePath` | string                                        | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`) |
-| `profile`        | string                                        | mpv profile name passed as `--profile=<name>`. Leave empty to pass no profile (default `""`)                                        |
-| `launchMode`     | `"normal"` \| `"maximized"` \| `"fullscreen"` | Window state when SubMiner spawns mpv (default `"normal"`)                                                                          |
+| Option                  | Values                                                              | Description                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `executablePath`        | string                                                              | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`) |
+| `profile`               | string                                                              | mpv profile name passed as `--profile=<name>`. Leave empty to pass no profile (default `""`)                                        |
+| `launchMode`            | `"normal"` \| `"maximized"` \| `"fullscreen"`                       | Window state when SubMiner spawns mpv (default `"normal"`)                                                                          |
+| `socketPath`            | string                                                              | mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin (default: `\\\\.\\pipe\\subminer-socket`)          |
+| `backend`               | `"auto"` \| `"hyprland"` \| `"sway"` \| `"x11"` \| `"macos"` \| `"windows"` | Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform (default: `"auto"`)                     |
+| `autoStartSubMiner`     | `true`, `false`                                                     | Start SubMiner in the background when SubMiner-managed mpv loads a file (default: `true`)                                           |
+| `pauseUntilOverlayReady`| `true`, `false`                                                     | Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness (default: `true`)                    |
+| `subminerBinaryPath`    | string                                                              | SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path (default: `""`)        |
+| `aniskipEnabled`        | `true`, `false`                                                     | Enable AniSkip intro detection and skip markers in the bundled mpv plugin (default: `true`)                                         |
+| `aniskipButtonKey`      | string                                                              | mpv key used to trigger the AniSkip button while the skip marker is visible (default: `"TAB"`)                                      |

 If `mpv.profile` is configured and the launcher also receives `--profile`, SubMiner passes both as a comma-separated mpv profile list.

@@ -1498,14 +1497,14 @@ Current launcher behavior:
 - If YouTube/mpv already exposes an authoritative matching subtitle track, SubMiner reuses it; otherwise it downloads and injects only the missing side.
 - SubMiner loads the primary subtitle plus a best-effort secondary subtitle.
 - Playback waits only for primary subtitle readiness; secondary failures do not block playback.
- English secondary subtitles are selected from `secondarySub.secondarySubLanguages` when primary language matches are unavailable.
+- English secondary subtitles are selected from the secondary-subtitle language list when primary language matches are unavailable.
 - Native mpv secondary subtitle rendering stays hidden during this flow so the SubMiner overlay remains the visible secondary subtitle surface.
 - If primary subtitle loading fails, use `Ctrl+Alt+C` to open the subtitle modal and pick a track.

 Language targets are derived from subtitle config:

 - primary track: `youtube.primarySubLanguages` (falls back to `["ja","jpn"]`)
- secondary track: `secondarySub.secondarySubLanguages` (falls back to English when empty)
+- secondary track: secondary-subtitle language list (falls back to English when empty)
 - Local playback uses the same priorities after mpv reports subtitle track metadata, so sidecar/internal mixed sets can override an incorrect initial `sid=auto` pick.
 - Tracks are resolved and loaded before mpv starts; the older launcher mode switch has been removed.

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

@@ -36,6 +36,37 @@ flowchart TB
  style E fill:#ed8796,stroke:#494d64,color:#24273a,stroke-width:1.5px
 ```

+## Runtime Sockets
+
+The renderer↔main bridge above lives *inside* the Electron app. A separate set of OS sockets connects the app to the other runtimes — mpv and the launcher/plugin. These carry no renderer payloads and bypass the contract/validator layer; they are command and property channels between processes.
+
+- **mpv IPC socket** (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows): the `MpvIpcClient` in the main process connects here to send JSON commands and subscribe to playback/subtitle properties via `observe_property`. Created by mpv's `--input-ipc-server`.
+- **App control socket** (`/tmp/subminer-control-<uid>-<hash>.sock`, or a named pipe on Windows): the launcher and the mpv plugin send CLI-style commands (`--start`, `--show-visible-overlay`, `--texthooker`) to a running app here. It also dedupes a second `subminer` invocation into the existing instance instead of launching twice.
+
+```mermaid
+flowchart LR
+  classDef extrt fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef app fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef ext fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
+
+  subgraph MpvProc["mpv process"]
+    direction TB
+    Mpv["mpv core"]:::ext
+    Plugin["SubMiner plugin (Lua)"]:::extrt
+  end
+
+  Launcher["Launcher CLI"]:::extrt
+  App["SubMiner app (Electron main)"]:::app
+
+  App <-->|"mpv IPC socket · /tmp/subminer-socket<br/>JSON commands + property observe"| Mpv
+  Launcher -->|"app control socket · /tmp/subminer-control-*<br/>--start, --show-visible-overlay, …"| App
+  Plugin -->|"app control socket<br/>spawn / attach"| App
+
+  style MpvProc fill:#363a4f,stroke:#494d64,color:#cad3f5
+```
+
+How these sockets are established during launch is covered in [Playback Startup Flow](./architecture#playback-startup-flow).
+
 ## Core Surfaces

 | File | Role |
@@ -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.
@@ -64,6 +64,7 @@ subminer video.mkv                      # play a specific file (default plugin c
 subminer https://youtu.be/...           # YouTube playback (requires yt-dlp)
 subminer --backend x11 video.mkv        # Force x11 backend for a specific file
 subminer -u                             # check for SubMiner updates
+subminer logs -e                        # export sanitized log ZIP
 subminer stats                          # open immersion dashboard
 subminer stats -b                       # start background stats daemon
 ```
@@ -78,6 +79,7 @@ subminer stats -b                       # start background stats daemon
 | `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows                  |
 | `subminer doctor`                          | Dependency + config + socket diagnostics                           |
 | `subminer settings`                        | Open the SubMiner settings window                                  |
+| `subminer logs -e`                         | Export a sanitized log ZIP and print its path                      |
 | `subminer config path`                     | Print active config file path                                      |
 | `subminer config show`                     | Print active config contents                                       |
 | `subminer mpv status`                      | Check mpv socket readiness                                         |
@@ -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
@@ -163,6 +163,8 @@ script-message subminer-start backend=hyprland socket=/custom/path texthooker=no

 ## Lifecycle

+For how the plugin's auto-start fits into the full launch sequence — including when the launcher starts the overlay instead of the plugin — see [Playback Startup Flow](./architecture#playback-startup-flow).
+
 - **File loaded**: If `auto_start=yes`, the plugin starts the overlay, then defers AniSkip lookup until after startup delay.
 - **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused and the plugin resumes playback after SubMiner reports tokenization-ready (with timeout fallback).
 - **Duplicate auto-start events**: Repeated `file-loaded` hooks while overlay is already running are ignored for auto-start triggers (prevents duplicate start attempts).
@@ -46,10 +46,16 @@
  // Logging
  // Controls logging verbosity.
  // Set to debug for full runtime diagnostics.
-  // Hot-reload: logging.level applies live while SubMiner is running.
+  // Hot-reload: logging.level and logging.files apply live while SubMiner is running.
  // ==========================================
  "logging": {
-    "level": "info" // Minimum log level for runtime logging. Values: debug | info | warn | error
+    "level": "warn", // Minimum log level for runtime logging. Values: debug | info | warn | error
+    "rotation": 7, // Number of days of app, launcher, and mpv logs to retain.
+    "files": {
+      "app": true, // Write SubMiner app runtime logs. Values: true | false
+      "launcher": true, // Write launcher command logs. Values: true | false
+      "mpv": false // Write mpv player logs. Enable temporarily when debugging mpv/plugin startup. Values: true | false
+    } // Files setting.
  }, // Controls logging verbosity.

  // ==========================================
@@ -83,7 +89,7 @@
      "rightStickPress": 10, // Raw button index used for controller R3 input.
      "leftTrigger": 6, // Raw button index used for controller L2 input.
      "rightTrigger": 7 // Raw button index used for controller R2 input.
-    }, // Semantic button-name reference mapping used for legacy configs and debug output. Updating it does not rewrite existing raw binding descriptors.
+    }, // Semantic button-name reference mapping used for debug output. Updating it does not rewrite existing raw binding descriptors.
    "bindings": {
      "toggleLookup": {
        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
@@ -187,7 +193,7 @@
    "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
    "toggleSecondarySub": "CommandOrControl+Shift+V", // Accelerator that toggles the secondary subtitle bar visibility.
    "markAudioCard": "CommandOrControl+Shift+A", // Accelerator that marks the last mined card as an audio card.
-    "openCharacterDictionary": "CommandOrControl+Alt+A", // Accelerator that opens the character dictionary modal.
+    "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
@@ -374,7 +380,7 @@
      "word-spacing": "0", // Word spacing setting.
      "font-kerning": "normal", // Font kerning setting.
      "text-rendering": "geometricPrecision", // Text rendering setting.
-      "text-shadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)", // Text shadow setting.
+      "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)", // Text shadow setting.
      "backdrop-filter": "blur(6px)", // Backdrop filter setting.
      "--subtitle-hover-token-color": "#f4dbd6", // Subtitle hover token color setting.
      "--subtitle-hover-token-background-color": "transparent" // Subtitle hover token background color setting.
@@ -383,7 +389,9 @@
    "preserveLineBreaks": false, // Preserve line breaks in visible overlay subtitle rendering. When false, line breaks are flattened to spaces for a single-line flow. Values: true | false
    "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
+    "primaryVisibleOnYomitanPopup": true, // Keep the primary subtitle bar visible while a Yomitan popup is open when primary subtitles are in hover mode. Values: true | false
+    "nameMatchEnabled": false, // Enable character dictionary sync and subtitle token coloring for character-name matches. 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.
@@ -397,7 +405,7 @@
    "frequencyDictionary": {
      "enabled": false, // Enable frequency-dictionary-based highlighting based on token rank. Values: true | false
      "sourcePath": "", // Optional absolute path to a frequency dictionary directory. If empty, built-in discovery search paths are used.
-      "topX": 1000, // Only color tokens with frequency rank <= topX (default: 1000).
+      "topX": 10000, // Only color tokens with frequency rank <= topX (default: 10000).
      "mode": "single", // single: use one color for all matching tokens. banded: use color ramp by frequency band. Values: single | banded
      "matchMode": "headword", // headword: frequency lookup uses dictionary form. surface: lookup uses subtitle-visible token text. Values: headword | surface
      "singleColor": "#f5a97f", // Color used when frequencyDictionary.mode is `single`.
@@ -422,7 +430,7 @@
        "word-spacing": "0", // Word spacing setting.
        "font-kerning": "normal", // Font kerning setting.
        "text-rendering": "geometricPrecision", // Text rendering setting.
-        "text-shadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)", // Text shadow setting.
+        "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)", // Text shadow setting.
        "backdrop-filter": "blur(6px)" // Backdrop filter setting.
      } // CSS declaration object applied to secondary subtitles after normal subtitle style defaults.
    } // Secondary setting.
@@ -515,7 +523,7 @@
      "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
      "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
-      "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio.
+      "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
    }, // Media setting.
@@ -523,8 +531,8 @@
      "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
-      "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"] }.
+      "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 expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
    }, // Known words setting.
    "behavior": {
      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
@@ -587,11 +595,8 @@
    "enabled": false, // Enable AniList post-watch progress updates. Values: true | false
    "accessToken": "", // Optional explicit AniList access token override; leave empty to use locally stored token from setup.
    "characterDictionary": {
-      "enabled": false, // Enable automatic Yomitan character dictionary sync for currently watched AniList media. Values: true | false
-      "refreshTtlHours": 168, // Legacy setting; merged character dictionary retention is now usage-based and this value is ignored.
      "maxLoaded": 3, // Maximum number of most-recently-used anime snapshots included in the merged Yomitan character dictionary.
-      "evictionPolicy": "delete", // Legacy setting; merged character dictionary eviction is usage-based and this value is ignored. Values: disable | delete
-      "profileScope": "all", // Yomitan profile scope for dictionary enable/disable updates. Values: all | active
+      "profileScope": "all", // Yomitan profile scope for character dictionary settings updates. Values: all | active
      "collapsibleSections": {
        "description": false, // Open the Description section by default in character dictionary glossary entries. Values: true | false
        "characterInformation": false, // Open the Character Information section by default in character dictionary glossary entries. Values: true | false
@@ -624,7 +629,7 @@
    "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
    "launchMode": "normal", // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
    "profile": "", // Optional mpv profile name passed to SubMiner-managed mpv launches. Leave empty to pass no profile.
-    "socketPath": "/tmp/subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
+    "socketPath": "\\\\.\\pipe\\subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
    "backend": "auto", // Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform. Values: auto | hyprland | sway | x11 | macos | windows
    "autoStartSubMiner": true, // Start SubMiner in the background when SubMiner-managed mpv loads a file. Values: true | false
    "pauseUntilOverlayReady": true, // Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness. Values: true | false
@@ -644,14 +649,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
@@ -362,7 +362,9 @@ test('dev server serves local archive files for local version links', async () =
  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = archiveDir;
  try {
-    const { default: localDevConfig } = await import('./.vitepress/config?local-dev-redirects');
+    const { default: localDevConfig } = await import(
+      `./.vitepress/config?local-dev-redirects-${Date.now()}`
+    );
    let routeHandler:
      | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
      | undefined;
@@ -67,7 +67,7 @@ These control playback and subtitle display. They require overlay window focus.
 | `Right-click + drag` | Reposition subtitles (on subtitle area)             |
 | `Ctrl/Cmd+A`         | Append clipboard video path to mpv playlist         |

-These keybindings can be overridden or disabled via the `keybindings` config array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.
+The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V`, `Ctrl/Cmd+A`, and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.

 On macOS managed playback, SubMiner disables mpv's menu-bar shortcuts so configured SubMiner shortcuts like `Cmd+Shift+O` reach the mpv plugin instead of opening native mpv menu actions.

@@ -75,17 +75,18 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle

 ## Subtitle & Feature Shortcuts

-| Shortcut           | Action                                                   | Config key                          |
-| ------------------ | -------------------------------------------------------- | ----------------------------------- |
-| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`      |
-| `Ctrl/Cmd+Alt+A`   | Open character dictionary AniList selector               | `shortcuts.openCharacterDictionary` |
-| `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`      |
-| `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`         |
-| `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`              |
-| `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                       |
-| `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`          |
-| `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey`         |
-| `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`                   |
+| Shortcut           | Action                                                   | Config key                                      |
+| ------------------ | -------------------------------------------------------- | ----------------------------------------------- |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`                  |
+| `Ctrl/Cmd+D`       | Open loaded character dictionary manager                 | `shortcuts.openCharacterDictionaryManager`      |
+| `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`                  |
+| `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                     |
+| `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                          |
+| `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                                   |
+| `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                      |
+| `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey`                     |
+| `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`                               |
+| `W`                | Mark current video watched and advance to next in queue  | `stats.markWatchedKey`                          |

 The stats toggle is handled inside the focused visible overlay window. It is configurable through the top-level `stats.toggleKey` setting and defaults to `Backquote`.

@@ -131,7 +132,7 @@ When the overlay has focus, press `y` then `d` to toggle DevTools (debugging hel

 ## Customizing Shortcuts

-All `shortcuts.*` keys accept [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts), for example `"CommandOrControl+Alt+A"`. Use `null` to disable a shortcut.
+All `shortcuts.*` keys accept [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts), for example `"CommandOrControl+D"`. Use `null` to disable a shortcut.

 ```jsonc
 {
@@ -12,7 +12,7 @@ N+1 highlighting identifies sentences where you know every word except one, maki

 **How it works:**

-1. SubMiner queries your Anki decks for existing `Expression` / `Word` field values.
+1. SubMiner queries your configured Anki decks for expression/word fields such as `Expression` or `Word`.
 2. The results are cached locally (`known-words-cache.json`) and refreshed on a configurable interval.
 3. When a subtitle line appears, each token is checked against the cache.
 4. If exactly one unknown word remains in the sentence, it is highlighted with `subtitleStyle.nPlusOneColor` (default: `#c6a0f6`).
@@ -24,33 +24,37 @@ N+1 highlighting identifies sentences where you know every word except one, maki
 | ----------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ankiConnect.knownWords.highlightEnabled` | `false`      | Enable known-word cache lookups used by N+1 highlighting                                                                                                      |
 | `ankiConnect.knownWords.refreshMinutes`   | `1440`       | Minutes between Anki cache refreshes                                                                                                                          |
-| `ankiConnect.knownWords.decks`            | `{}`         | Deck→fields map for known-word cache queries (legacy fallback: `ankiConnect.deck`)                                                                            |
+| `ankiConnect.knownWords.decks`            | `{}`         | Deck→fields map for known-word cache queries                                                                                                                  |
 | `ankiConnect.knownWords.matchMode`        | `"headword"` | `"headword"` (dictionary form) or `"surface"` (raw text)                                                                                                      |
-| `ankiConnect.nPlusOne.enabled`            | `false`      | Enable N+1 target highlighting. Existing configs with known-word highlighting enabled are treated as enabled for compatibility unless this is explicitly set. |
+| `ankiConnect.nPlusOne.enabled`            | `false`      | Enable N+1 target highlighting                                                                                                                               |
 | `ankiConnect.nPlusOne.minSentenceWords`   | `3`          | Minimum tokens in a sentence for N+1 to trigger                                                                                                               |
 | `subtitleStyle.nPlusOneColor`             | `#c6a0f6`    | Color for the single unknown target word                                                                                                                      |
 | `subtitleStyle.knownWordColor`            | `#a6da95`    | Color for already-known tokens                                                                                                                                |

+Prefer expression/word fields for `ankiConnect.knownWords.decks`. Reading-only fields can mark unrelated homophones as known, so only include them when that tradeoff is intentional.
+
 ::: tip
 Set `refreshMinutes` to `1440` (24 hours) for daily sync if your Anki collection is large.
 :::

 ## Character-Name Highlighting

-Character-name matches are built from the active merged SubMiner character dictionary, which auto-syncs character data from AniList for your recently-watched titles. Matching names are highlighted in subtitles and become available for hover-driven Yomitan character profiles — portraits, roles, voice actors, and biographical detail.
+Character-name matches are built from the active merged SubMiner character dictionary, which auto-syncs character data from AniList for your recently-watched titles. When the current AniList media ID is known, SubMiner ignores loaded entries from other titles for subtitle name matching and inline portraits. Matching names are highlighted in subtitles and become available for hover-driven Yomitan character profiles — portraits, roles, voice actors, and biographical detail.

 **How it works:**

 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 +71,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`         | `10000`      | 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 +126,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`)

@@ -35,30 +35,45 @@ Enable and configure the sidebar under `subtitleSidebar` in your config file:
    "toggleKey": "Backslash",
    "pauseVideoOnHover": true,
    "autoScroll": true,
-    "fontFamily": "\"M PLUS 1\", \"Noto Sans CJK JP\", sans-serif",
-    "fontSize": 16
+    "css": {
+      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
+      "color": "#cad3f5",
+      "background-color": "rgba(73, 77, 100, 0.9)",
+      "font-size": "16px",
+      "opacity": "0.95",
+      "--subtitle-sidebar-max-width": "420px",
+      "--subtitle-sidebar-timestamp-color": "#a5adcb",
+      "--subtitle-sidebar-active-line-color": "#f5bde6",
+      "--subtitle-sidebar-active-background-color": "rgba(138, 173, 244, 0.22)",
+      "--subtitle-sidebar-hover-background-color": "rgba(54, 58, 79, 0.84)"
+    }
  }
 }
 ```

-| Option                      | Type    | Default      | Description                                                                                        |
-| --------------------------- | ------- | ------------ | -------------------------------------------------------------------------------------------------- |
-| `enabled`                   | boolean | `true`       | Enable subtitle sidebar support                                                                    |
-| `autoOpen`                  | boolean | `false`      | Open the sidebar automatically on overlay startup                                                  |
-| `layout`                    | string  | `"overlay"`  | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space                        |
-| `toggleKey`                 | string  | `"Backslash"` | `KeyboardEvent.code` for the toggle shortcut                                                      |
-| `pauseVideoOnHover`         | boolean | `true`       | Pause playback while hovering the cue list                                                         |
-| `autoScroll`                | boolean | `true`       | Keep the active cue in view during playback                                                        |
-| `maxWidth`                  | number  | `420`        | Maximum sidebar width in CSS pixels                                                                |
-| `opacity`                   | number  | `0.95`       | Sidebar opacity between `0` and `1`                                                                |
-| `backgroundColor`           | string  | `rgba(73, 77, 100, 0.9)`  | Sidebar shell background color                                                        |
-| `textColor`                 | string  | `#cad3f5`    | Default cue text color                                                                             |
-| `fontFamily`                | string  | `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP` | CSS `font-family` applied to cue text          |
-| `fontSize`                  | number  | `16`         | Base cue font size in CSS pixels                                                                   |
-| `timestampColor`            | string  | `#a5adcb`    | Cue timestamp color                                                                                |
-| `activeLineColor`           | string  | `#f5bde6`    | Active cue text color                                                                              |
-| `activeLineBackgroundColor` | string  | `rgba(138, 173, 244, 0.22)` | Active cue background color                                                         |
-| `hoverLineBackgroundColor`  | string  | `rgba(54, 58, 79, 0.84)`    | Hovered cue background color                                                        |
+Styling lives under the `css` object, using CSS property names and CSS custom properties (the same pattern as `subtitleStyle.css`).
+
+| Option              | Type    | Default       | Description                                                                |
+| ------------------- | ------- | ------------- | -------------------------------------------------------------------------- |
+| `enabled`           | boolean | `true`        | Enable subtitle sidebar support                                            |
+| `autoOpen`          | boolean | `false`       | Open the sidebar automatically on overlay startup                          |
+| `layout`            | string  | `"overlay"`   | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space |
+| `toggleKey`         | string  | `"Backslash"` | `KeyboardEvent.code` for the toggle shortcut                               |
+| `pauseVideoOnHover` | boolean | `true`        | Pause playback while hovering the cue list                                 |
+| `autoScroll`        | boolean | `true`        | Keep the active cue in view during playback                                |
+
+| `css` property                              | Default                     | Description                  |
+| ------------------------------------------- | --------------------------- | ---------------------------- |
+| `font-family`                               | `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP` | Cue text font family |
+| `color`                                     | `#cad3f5`                   | Default cue text color       |
+| `background-color`                          | `rgba(73, 77, 100, 0.9)`    | Sidebar shell background color |
+| `font-size`                                 | `16px`                      | Base cue font size           |
+| `opacity`                                   | `0.95`                      | Sidebar opacity between `0` and `1` |
+| `--subtitle-sidebar-max-width`              | `420px`                     | Maximum sidebar width        |
+| `--subtitle-sidebar-timestamp-color`        | `#a5adcb`                   | Cue timestamp color          |
+| `--subtitle-sidebar-active-line-color`      | `#f5bde6`                   | Active cue text color        |
+| `--subtitle-sidebar-active-background-color`| `rgba(138, 173, 244, 0.22)` | Active cue background color  |
+| `--subtitle-sidebar-hover-background-color` | `rgba(54, 58, 79, 0.84)`    | Hovered cue background color |

 ## Keyboard Shortcut

--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
sudacode	38dbce517c	chore(release): 0.15.0	2026-05-28 19:46:05 -07:00
sudacode	889dc9c009	docs: reconcile docs-site with current config schema and defaults - sidebar: migrate flat props to css object (font-family, color, bg, custom vars) - frequencyDictionary.topX default: 1000 → 10000 - text-shadow default: updated to outline-style multi-shadow - anki: reset ai model/prompt, imageMaxWidth/Height, animatedMaxHeight to 0; isLapis defaults - troubleshooting: log default warn (not info), css["font-size"] usage - shortcuts: add W markWatchedKey; clarify keybindings vs built-in overlay actions - websocket: clarify all services off by default, fix enabled semantics - usage: --anilist → --anilist-setup - AGENTS.md: add Docs Upkeep trigger map, clarify CLAUDE.md symlink, expand PR notes	2026-05-28 19:21:58 -07:00
sudacode	097021072d	chore(release): 0.15.0-beta.12	2026-05-28 02:16:55 -07:00
sudacode	91c8eb8faf	feat(changelog): add nested bullet format for release notes - Prompt now requests short top-level bullets with nested change/benefit/action sub-bullets in release-notes mode - CHANGELOG mode keeps single-line bullets unchanged - Tests assert new prompt constraints are present	2026-05-28 02:08:44 -07:00
sudacode	eed0a6a243	feat: use cached annotations on subtitle change and skip pre-warmed cues (#97 )	2026-05-28 00:50:41 -07:00
sudacode	d33009d4a3	style: update subtitle text shadow, JLPT underlines, and frequency topX default (#96 ) * style: update subtitle text shadow, JLPT underlines, and frequency topX - Replace directional text-shadow with 4-corner outline shadow for sharper readability - Increase JLPT level border-bottom from 2px to 3px; add drop-shadow filter - Add margin-left 0.18em to character image token - Raise frequencyDictionary topX default from 1000 to 10000 * docs: add subtitle style changelog fragment * docs: update generated config examples * style: wrap long textShadow strings and add blank line in CSS	2026-05-28 00:18:39 -07:00
sudacode	8d0535f3ca	feat: add Anki deck dropdown with Yomitan auto-fill in settings (#95 )	2026-05-27 23:13:43 -07:00
sudacode	75f9b8a803	chore: prepare 0.15.0-beta.11 prerelease	2026-05-27 16:42:04 -07:00
sudacode	c30cce0a14	chore: consolidate changelog fragments for release - Merge per-fix fragments into grouped topic files (jellyfin, overlay, anki, character-dictionary, etc.) - Improve auto-update fragment wording for clarity	2026-05-27 14:56:49 -07:00
sudacode	3e6591e390	fix: include audio padding in animated AVIF source range (#94 )	2026-05-27 14:06:48 -07:00
sudacode	f033f87329	fix: ensure macOS mpv window helper is built and bundled correctly (#93 )	2026-05-27 13:34:51 -07:00
sudacode	29cb8c7fb4	chore: release 0.15.0-beta.10	2026-05-27 01:54:52 -07:00
sudacode	1dcfed86ab	fix: Kiku field grouping, frequency particles, sidebar media, Yomitan popup visibility (#91 )	2026-05-27 01:40:48 -07:00
sudacode	efe50ed1e4	docs: add startup flow diagram and document new config options (#90 )	2026-05-26 23:51:36 -07:00
sudacode	5b44981688	docs: remove legacy option refs and modernize config docs (#89 )	2026-05-26 18:15:23 -07:00
sudacode	2add95d541	fix(anilist): dedupe failures during retry cooldown and block dead-lette - Ignore markFailure calls while an item is still within its retry backoff window - Prevent enqueue from re-adding keys already in the dead-letter queue	2026-05-26 01:57:25 -07:00
sudacode	f62fff2585	chore(release): 0.15.0-beta.9	2026-05-26 00:55:34 -07:00
sudacode	11c196821d	Fix Windows mpv logging and add log export (#88 )	2026-05-26 00:31:38 -07:00
sudacode	43ebc7d371	chore: prepare 0.15.0-beta.8 prerelease	2026-05-25 20:34:56 -07:00
sudacode	639e331f24	fix(character-dictionary): add surname honorifics for Japanese localized aliases (#87 )	2026-05-25 20:12:27 -07:00
sudacode	78be72e32f	chore: prepare 0.15.0-beta.7 prerelease	2026-05-25 18:37:03 -07:00
sudacode	3932e53ced	feat(character-dictionary): add manager modal and scope name matching to current media (#86 )	2026-05-25 18:29:20 -07:00
sudacode	097b619d71	fix: settings window z-order on Hyprland and Linux app detach (#85 )	2026-05-25 13:21:38 -07:00
sudacode	f7abcedd75	chore: prepare 0.15.0-beta.6 prerelease	2026-05-25 03:25:34 -07:00
sudacode	807c0ff3db	Add inline character portraits and dictionary search workflow (#83 )	2026-05-25 03:16:25 -07:00
sudacode	7e6f9672cf	fix: suppress overlay subtitle immediately when character dictionary modal opens (#84 )	2026-05-25 02:30:33 -07:00
sudacode	9fe13601fb	Launch macOS app background-detached when no args passed - 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	2026-05-25 02:12:41 -07:00
sudacode	920cbab1bc	Fix Windows mpv handoff and tray setup (#82 )	2026-05-25 01:34:01 -07:00
sudacode	17d97f0b7e	fix: rename Windows ZIPs and fix macOS manual update checks (#81 )	2026-05-24 23:47:02 -07:00
sudacode	10463e7348	chore: prepare 0.15.0-beta.5 prerelease	2026-05-24 19:11:02 -07:00
sudacode	e9abbd5f05	style: format youtube runtime files	2026-05-24 19:10:58 -07:00
sudacode	d6ff50455a	fix(changelog): summarize prerelease notes as net outcome	2026-05-24 19:10:53 -07:00
sudacode	b1bdeabca8	fix(jellyfin): show overlay, inject plugin, and fix stats title on playback (#77 ) * fix(jellyfin): show overlay, inject plugin, and fix stats title on playb - Show visible overlay automatically during Jellyfin playback so subtitleStyle applies - Inject bundled mpv plugin on auto-launch so keybindings work without overlay focus - Group Jellyfin playback stats under item metadata (jellyfin://host/item/id) instead of stream URLs so episodes merge with matching local titles - Mark ffsubsync unavailable in subsync modal for remote media paths - Drain queued second-instance commands even when onReady throws * fix(overlay): stabilize macOS focus handoff and sidebar Yomitan pause - Keep overlay visible during macOS foreground probe after overlay blur - Hold sidebar hover-pause while a Yomitan lookup popup remains open * fix(jellyfin): fix discovery loop, device identity, tray state, and Disc - Derive device identity from OS hostname; remove legacy configurable client/device fields - Prevent discovery playback from reloading active item, misreporting pause state, and duplicate overlay restores - Restart stale tray discovery sessions without re-login when server drops SubMiner cast target - Sync tray discovery checkbox state on Linux after CLI/startup/remote-session changes - Stop Discord presence falling back to stream URLs; prime title before tokenized stream loads - Fix picker library discovery when log level is above info - Fix config.example.jsonc trailing commas and array formatting * docs(release): trim and consolidate prerelease notes for 0.15.0 - Remove breaking changes section and several redundant bullet points - Consolidate per-platform updater notes into a single entry - Normalize em-dash separators to hyphens in section headers * fix(config): remove trailing commas from config.example.jsonc - Strip trailing commas throughout both config.example.jsonc copies - Reformat inline arrays to multi-line for JSON strictness - Update Jellyfin subtitle preload and playback launch tests and impl * fix(tokenizer): preserve known-word highlight when POS filters suppress - Known-word cache matches now set isKnown=true even for tokens excluded by POS filters - POS exclusion gate suppresses N+1, frequency, and JLPT only; known status is computed before the gate - Jellyfin subtitle preload continues after cleanup failures instead of aborting - Update config docs and option description to document the known-word bypass behavior * fix(jellyfin): send explicit hide/show overlay instead of toggle - Track overlay visibility in plugin state; y-t uses explicit hide/show commands when state is known - Prevent paused Jellyfin playback from resuming on overlay hide - Fix subtitle cache cleanup to only remove dirs after successful cleanup * fix(jellyfin): fix remote progress sync, seek reporting, and startup sto - arm active playback before loadfile with loadedMediaPath: null to suppress premature stop events - force immediate progress report on seek-like position jumps at the mpv time-pos level - send positionTicks and failed=false in reportStopped payload - remove EventName from HTTP timeline payloads (websocket-only field) - add startup grace window to drop stop events before media finishes loading * fix(jellyfin): fix overlay toggle sync, redirect reload, and AppImage bi - Sync visible-overlay state back to plugin via script messages to avoid toggle/hide drift - Collapse duplicate toggle events within 250ms to prevent hide-then-show on single keypress - Preserve manual hide across Jellyfin path-changing redirects even when media-title drops - Rearm managed subtitle defaults on path-changing redirects - Route toggleVisibleOverlay session binding through plugin toggle instead of app-side IPC - Show Linux/Hyprland overlay passively (showInactive) to avoid stealing mpv keyboard focus - Fix AppImage binary resolution to prefer $APPIMAGE env over mounted inner binary - Add stats window layer management so delete/update dialogs appear above stats window - Fix Jellyfin remote progress sync during Linux websocket reconnect windows * Fix CodeRabbit review feedback * fix(jellyfin): subtitle timing, resume progress, and overlay sync - Add per-stream subtitle delay persistence and auto timeline-offset correction - Strip server-selected subtitle stream from mpv load URL; suppress plugin subtitle rearm and auto-start during app-managed preload - Fix resume position lost when mpv resets on stop; use last known position for final progress/stopped reports - Keep Play vs Resume distinct to avoid early seek race on normal play - Fix discovery resume when remote play sends StartPositionTicks=0 despite saved progress - Deduplicate show/hide overlay commands using recorded visibility state - Rewrite docs-site Jellyfin page around cast-to-device UX * test: update lifecycle cleanup assertion * fix: clear aborted playback state, fix overlay passthrough, and guard du - Reset app_managed_playback_pending on lifecycle cleanup to prevent state leak into next item - Record visible overlay action only after command succeeds, not before - Non-native passive overlay now always click-through on re-show (fix isNonNativePassiveOverlay ordering) - Defer activeParsedSubtitleMediaPath assignment until after prefetch completes - Move autoplay gate release into the hide branch of toggleVisibleOverlay - Clear active Jellyfin playback when stopping media that never loaded - Reset managed subtitle delay and delay key when no external tracks are available - Await async removeDir in subtitle cache cleanup - Guard duplicate delete clicks in MediaDetailView and SessionsTab with refs - Escape key in DeleteConfirmDialog now calls stopPropagation and stopImmediatePropagation	2026-05-24 18:40:56 -07:00