fix(overlay): use Lua dispatch syntax for Hyprland 0.55+ Lua configs (#99)

Rewrite Hyprland overlay window-rule guidance with current Lua (hl.window_rule)
config and legacy hyprland.conf syntax, and note SubMiner's automatic hyprctl
placement. Add a Character Dictionary troubleshooting section (no AniList auth
required) and a See Also index linking each feature's own troubleshooting page.

.github/workflows/prerelease.yml

@@ -148,7 +148,7 @@ jobs:
           name: appimage
           path: |
             release/*.AppImage
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
           if-no-files-found: error
 
@@ -226,7 +226,7 @@ jobs:
           path: |
             release/*.dmg
             release/*.zip
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
           if-no-files-found: error
 
@@ -279,7 +279,7 @@ jobs:
           path: |
             release/*.exe
             release/*.zip
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
           if-no-files-found: error
 
@@ -353,7 +353,7 @@ jobs:
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/*.yml release/*.blockmap dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -389,7 +389,7 @@ jobs:
             release/*.exe
             release/*.zip
             release/*.tar.gz
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
             dist/launcher/subminer

.github/workflows/release.yml

@@ -139,7 +139,7 @@ jobs:
           name: appimage
           path: |
             release/*.AppImage
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
 
   build-macos:
@@ -216,7 +216,7 @@ jobs:
           path: |
             release/*.dmg
             release/*.zip
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
 
   build-windows:
@@ -268,7 +268,7 @@ jobs:
           path: |
             release/*.exe
             release/*.zip
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
           if-no-files-found: error
 
@@ -342,7 +342,7 @@ jobs:
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/*.yml release/*.blockmap dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -396,7 +396,7 @@ jobs:
             release/*.exe
             release/*.zip
             release/*.tar.gz
-            release/*.yml
+            release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
             dist/launcher/subminer

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,157 @@
 # 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
+- **N+1 Highlighting:**
+  - N+1 highlighting now has its own dedicated `ankiConnect.nPlusOne.enabled` option, separate from known-word highlighting
+  - It is no longer enabled automatically when known-word highlighting is on — enable it explicitly to keep N+1 annotations
+
+### Added
+
+- **Auto-Updater:**
+  - Tray and `subminer -u` update checks with app update prompts
+  - Launcher and Linux rofi theme auto-updates
+  - Checksum verification and configurable notifications
+  - 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
+  - AnkiConnect-backed deck, field, and note-type pickers that auto-fill from the configured Anki deck
+  - Cross-category search
+  - 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
+- **Character Dictionary Manager:** New `Ctrl/Cmd+D` manager modal to remove, reorder, or override loaded entries.
+- **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
+  - 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
+  - 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
+  - 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.
+- **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
+- **Jellyfin Discovery:**
+  - Startup, subtitle track selection, and duplicate ready-signal handling all fixed
+  - Paused mpv no longer misreported as playing
+  - Resume corrected when a remote play command sends `StartPositionTicks: 0` despite saved progress
+- **Jellyfin Remote:**
+  - Tray checkbox stays in sync on Linux after tray, CLI, or startup changes
+  - 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
+- **Overlay (macOS):**
+  - Overlay hides when mpv loses focus, is minimized, or is no longer the foreground app
+  - Stays 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
+- **Yomitan Sidebar:**
+  - Playback stays paused for sidebar-opened Yomitan popups when auto-pause is enabled
+  - Popups now open 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:**
+  - `subminer app` on Linux returns terminal control immediately
+  - `subminer app --setup` opens the setup flow when SubMiner is already running in the 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
+- **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
+- **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
+- **WebSocket Annotations:**
+  - Annotation spans and token metadata stay on the annotation WebSocket
+  - The regular subtitle WebSocket is plain-text only
+- **Subtitle Annotation Prefetching:** Cached colored annotations and character images ready sooner for live subtitle changes without delaying raw subtitle display.
+- **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/anilist-retry-dedupe.md

@@ -1,4 +0,0 @@
-type: fixed
-area: anilist
-
-- Prevent repeated missing-token checks from rapidly exhausting AniList retry attempts or duplicating dead-letter entries for the same episode.

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-docs.md

@@ -0,0 +1,6 @@
+type: docs
+area: character-dictionary
+
+- Corrected character dictionary setup docs: AniList authentication is not required; the feature uses public GraphQL queries and only needs `subtitleStyle.nameMatchEnabled`.
+- Added documentation for inline character portraits (`subtitleStyle.nameMatchImagesEnabled`).
+- Clarified that AniList authentication is only needed for watch-progress sync, not the character dictionary.

changes/character-dictionary-known-names.md

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

changes/character-dictionary-manager-gate.md

@@ -1,4 +0,0 @@
-type: fixed
-area: character-dictionary
-
-- Block the character dictionary manager when character dictionary annotations are disabled, and notify through the configured OSD/system notification surfaces.

changes/character-dictionary-manager.md

@@ -1,4 +0,0 @@
-type: changed
-area: character-dictionary
-
-- Character dictionary entries are now scoped to the current AniList media for name matching and inline portraits, and a new `Ctrl/Cmd+D` manager modal can remove, reorder, or override loaded dictionary entries.

changes/character-dictionary-manual-search.md

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

changes/character-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/character-name-inline-images.md

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

changes/config-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-startup-flow-config-options.md

@@ -1,7 +0,0 @@
-type: changed
-area: docs
-
-- Documented all config options that were present in `config.example.jsonc` but missing from the configuration reference: `subtitleStyle.primaryDefaultMode`, `stats.markWatchedKey`, `immersionTracking.lifetimeSummaries.*`, and all seven `mpv.*` launcher options (`socketPath`, `backend`, `autoStartSubMiner`, `pauseUntilOverlayReady`, `subminerBinaryPath`, `aniskipEnabled`, `aniskipButtonKey`).
-- Added a **Playback Startup Flow** diagram to the Architecture page showing how the managed launch (`subminer` CLI, app, Windows shortcut) injects the plugin, establishes the IPC socket, and brings up the overlay via the two convergent triggers.
-- Added a **Runtime Sockets** section and diagram to the IPC + Runtime Contracts page showing the mpv IPC socket and app control socket topology.
-- Added cross-reference pointers in the MPV Plugin and Troubleshooting pages.

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-character-dictionary-localized-alias-surnames.md

@@ -1,4 +0,0 @@
-type: fixed
-area: character-dictionary
-
-- Added surname honorific matches for Japanese localized character aliases embedded in AniList alternative names, such as Korean-source characters with Japanese names in parentheses, and refresh cached snapshots so those aliases are regenerated.

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

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

changes/fix-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-hyprland-settings-window-z-order.md

@@ -1,4 +0,0 @@
-type: fixed
-area: desktop
-
-- Fixed Hyprland settings windows opening behind the subtitle overlay by promoting SubMiner and Yomitan settings above the overlay without hiding subtitles.

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-kiku-duplicate-modal-open.md

@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
-- Fixed Kiku duplicate-card field grouping so local duplicate sentence cards trigger the manual modal or auto merge, modal-open acknowledgement races no longer cancel the flow, and merged card fields follow Kiku's group ordering, sentence-audio, furigana, and tag semantics.

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-linux-app-command-detach.md

@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
-- Fixed `subminer app` on Linux so launching the tray app returns control to the terminal immediately instead of waiting for the tray process to exit.

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-mpv-character-dictionary-manager-bindings.md

@@ -1,4 +0,0 @@
-type: fixed
-area: mpv
-
-- Pass generated session-action CLI args to the mpv plugin.

changes/fix-mpv-logging-config-forwarding.md

@@ -1,7 +0,0 @@
-type: fixed
-area: logging
-
-- Forward SubMiner `logging.level` into launcher-started and Windows shortcut-started mpv sessions, including mpv log verbosity, plugin script logging, and plugin-launched app logging.
-- Add numeric `logging.rotation`, defaulting to 7 days of retained daily app, launcher, and mpv logs.
-- Log Windows mpv launch diagnostics, IPC socket connection state, subtitle track summaries, Yomitan extension load state, dictionary counts, and expected/active IPC socket values when plugin auto-start skips due to a socket mismatch.
-- Add `logging.files` toggles for app, launcher, and mpv logs, with mpv logs disabled by default unless explicitly enabled for debugging.

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-windows-background-mpv-overlay.md

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

changes/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/frequency-compound-particles.md

@@ -1,4 +0,0 @@
-type: fixed
-area: subtitles
-
-- Fixed frequency annotations for Yomitan single-token compounds with internal particles, such as `目の前`, while keeping pure grammar/kana helper spans unannotated.

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/hyprland-lua-dispatch.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed Hyprland overlay placement on Hyprland 0.55+ Lua configs by using Lua dispatcher syntax when Hyprland reports `configProvider: "lua"`.

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-cache-field-docs.md

@@ -1,5 +0,0 @@
-type: changed
-area: anki
-
-- `ankiConnect.nPlusOne.enabled` is no longer implicitly set to `true` when `ankiConnect.knownWords.highlightEnabled` is `true`. Users who rely on known-word highlighting and want N+1 target highlighting must now set `ankiConnect.nPlusOne.enabled: true` explicitly.
-- Updated known-word cache docs and examples to recommend expression/word fields and removed legacy-option references from user-facing config docs.

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/log-export.md

@@ -1,4 +0,0 @@
-type: added
-area: logs
-
-- Add sanitized log ZIP exports from the tray menu and `subminer logs -e`, with home-directory usernames redacted from exported log contents.

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-ipc-background-log-throttle.md

@@ -1,4 +0,0 @@
-type: fixed
-area: logging
-
-- Stop repeated MPV IPC socket warning spam while the app waits in the background for mpv to recreate the IPC socket.

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/name-match-controls-character-dictionary.md

@@ -1,4 +0,0 @@
-type: fixed
-area: character-dictionary
-
-- Use `subtitleStyle.nameMatchEnabled` as the only switch for character-dictionary sync/builds and hide the legacy `anilist.characterDictionary.enabled` option.

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.