chore(release): 0.15.0

- 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

AGENTS.md

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

CHANGELOG.md

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

changes/358-jellyfin-setup-feedback.md

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

changes/README.md

@@ -35,6 +35,7 @@ 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.
 

changes/animated-avif-padding-freeze.md

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

changes/aniskip-key-learn.md

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

changes/auto-update.md

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

changes/background-launcher-reuse.md

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

changes/changelog-net-release-outcome.md

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

changes/character-dictionary-resolution-cache.md

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

changes/config-example-settings-css.md

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

changes/config-load-preserves-user-files.md

@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
-- Preserved user config files during legacy config compatibility handling.

changes/config-settings-controls.md

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

changes/config-settings-search.md

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

changes/config-settings-window.md

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

changes/controller-config-enables-input.md

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

changes/default-opt-in-warmup-name-highlighting.md

@@ -1,4 +0,0 @@
-type: changed
-area: config
-
-- Defaulted Jellyfin remote-session startup warmup and character-name subtitle highlighting to off.

changes/docs-versioning.md

@@ -1,4 +0,0 @@
-type: docs
-area: docs
-
-- Published stable docs at the site root with current development docs under `/main/`.

changes/electron-42-runtime.md

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

changes/first-run-command-line-launcher.md

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

changes/fix-anilist-timepos-threshold.md

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

changes/fix-animated-avif-word-audio-sync.md

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

changes/fix-autoplay-subtitle-prime.md

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

changes/fix-background-attach-autoplay-gate.md

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

changes/fix-determiner-noun-frequency.md

@@ -1,4 +0,0 @@
-type: fixed
-area: subtitles
-
-- Kept frequency highlighting for determiner-led noun compounds like `その場` while still filtering standalone determiners.

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

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

changes/fix-hyprland-overlay-unfullscreen.md

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

changes/fix-hyprland-overlay-zorder.md

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

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

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

changes/fix-jellyfin-discovery-resume.md

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

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

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

changes/fix-jellyfin-overlay-toggle.md

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

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

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

changes/fix-jellyfin-stats-title.md

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

changes/fix-jellyfin-subtitle-timing.md

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

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

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

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

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

changes/fix-jellyfin-visible-progress.md

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

changes/fix-launcher-electron-menu-diagnostic.md

@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
-- Suppressed Electron macOS menu diagnostics from `subminer settings` launcher output.

changes/fix-macos-mpv-shortcuts.md

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

changes/fix-macos-overlay-layering.md

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

changes/fix-macos-overlay-minimize-tracking.md

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

changes/fix-macos-overlay-passthrough.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed macOS overlay passthrough so mpv controls remain clickable before hovering subtitle bars.

changes/fix-managed-playback-overlay-lifecycle.md

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

changes/fix-multiline-copy-overlay-focus.md

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

changes/fix-prerelease-update-channel.md

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

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

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

changes/fix-stats-dialog-layering.md

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

changes/fix-subsync-modal-window.md

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

changes/fix-versioned-doc-links.md

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

changes/fix-youtube-manual-card-update-media.md

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

changes/fix-youtube-sidebar-primary-cues.md

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

changes/hide-setup-runtime-plugin.md

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

changes/jellyfin-picker-log-level.md

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

changes/jellyfin-visible-overlay.md

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

changes/known-word-color-config.md

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

changes/launcher-version-flag.md

@@ -1,4 +0,0 @@
-type: added
-area: launcher
-
-- Added `subminer --version` and `subminer -v` to print the installed SubMiner app version.

changes/linux-direct-launcher-update.md

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

changes/linux-launcher-shim.md

@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
-- Fixed Linux first-run launcher installs by building the packaged launcher with a valid Bun shebang.

changes/linux-tray-appimage-update.md

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

changes/linux-updater-curl-fetch.md

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

changes/linux-updater-error-event.md

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

changes/macos-config-window-exit.md

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

changes/macos-local-bin-launcher.md

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

changes/macos-manual-update-required.md

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

changes/macos-overlay-focus-handoff.md

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

changes/macos-update-dialog-activation.md

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

changes/macos-update-dialog-focus.md

@@ -1,4 +0,0 @@
-type: fixed
-area: updater
-
-- Bring macOS update dialogs to the front when `subminer --update` is run from the launcher.

changes/macos-updater-curl-fetch.md

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

changes/macos-updater-zip-collision.md

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

changes/make-install-fresh-appimage.md

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

changes/mpv-config-unified.md

@@ -1,4 +0,0 @@
-type: added
-area: launcher
-
-- Managed bundled mpv plugin startup options from SubMiner config.

changes/mpv-profile-config.md

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

changes/mpv-session-shortcuts.md

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

changes/native-updater-crash.md

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

changes/note-fields-default-note-type.md

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

changes/nplusone-known-word-compat.md

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

changes/overlay-restart-visible.md

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

changes/plain-websocket-annotations.md

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

changes/prerelease-notes-reuse.md

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

changes/remove-jellyfin-server-presets.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.

changes/remove-yomitan-vendor-test-assertions.md

@@ -1,4 +0,0 @@
-type: internal
-area: tests
-
-- Removed stale Yomitan vendor source-inspection assertions for changes that were not shipped.

changes/setup-background-command.md

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

changes/setup-finish-quit.md

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

changes/setup-subminer-settings-button.md

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

changes/subsync-manual-only.md

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

changes/subtitle-css-appearance-editor.md

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

changes/subtitle-css-hover-migration.md

@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
-- Migrated legacy subtitle hover token colors into `subtitleStyle.css` instead of leaving `hoverTokenColor` or `hoverTokenBackgroundColor` behind.

changes/subtitle-css-legacy-migration.md

@@ -1,4 +0,0 @@
-type: fixed
-area: config
-
-- Migrated legacy primary and secondary subtitle appearance options into `subtitleStyle.css` automatically when loading config files.

changes/subtitle-css-live-settings.md

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

changes/subtitle-sidebar-css.md

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

changes/tray-modal-lifecycle.md

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

changes/windows-startup-fatal-errors.md

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

changes/windows-update-check-crash.md

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

changes/yomitan-popup-late-load.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed Yomitan popups not opening when playback/overlay startup races the Yomitan extension load.

changes/youtube-hyprland-tray.md

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

config.example.jsonc

@@ -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.
@@ -524,7 +532,7 @@
       "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. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
-      "decks": {} // Decks and fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word", "Word Reading"] }.
+      "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 character dictionary settings updates. Values: all | active
-      "profileScope": "all", // Yomitan profile scope for dictionary enable/disable 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

docs-site/.vitepress/config.ts

@@ -19,18 +19,26 @@ type VersionManifest = {
   versions: Array<{ version: string; path: string }>;
 };
 
-const base = normalizeBase(process.env.SUBMINER_DOCS_BASE ?? '/');
+function optionalEnv(value: string | undefined): string | undefined {
-const outDir = process.env.SUBMINER_DOCS_OUT_DIR;
+  return value && value !== 'undefined' ? value : undefined;
-const docsSourceDir = process.env.SUBMINER_DOCS_SOURCE_DIR ?? process.cwd();
+}
-const localArchiveDir = resolve(
+
-  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR ??
+const base = normalizeBase(optionalEnv(process.env.SUBMINER_DOCS_BASE) ?? '/');
-    join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
+const outDir = optionalEnv(process.env.SUBMINER_DOCS_OUT_DIR);
-);
+const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? process.cwd();
-const channel = normalizeChannel(process.env.SUBMINER_DOCS_CHANNEL);
+const channel = normalizeChannel(optionalEnv(process.env.SUBMINER_DOCS_CHANNEL));
-const docsVersion = process.env.SUBMINER_DOCS_VERSION;
+const docsVersion = optionalEnv(process.env.SUBMINER_DOCS_VERSION);
-const latestStable = process.env.SUBMINER_DOCS_LATEST_STABLE ?? 'v0.14.0';
+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;

docs-site/anilist-integration.md

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

docs-site/anki-integration.md

@@ -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.
+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` (object map), with `ankiConnect.deck` used as legacy fallback.
+Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.
 
 ### Proxy Mode Setup (Yomitan / Texthooker)