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

CHANGELOG.md

@@ -4,68 +4,151 @@
 
 ### 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.
+- **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: 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.
+- **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, 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.
+- **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; 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.
+- **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.
+- **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.
+- **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>
 

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

@@ -0,0 +1,6 @@
+type: docs
+area: troubleshooting
+
+- Updated the Hyprland overlay troubleshooting with current Lua (`hl.window_rule`) config and the legacy `hyprland.conf` window rules, and noted SubMiner attempts automatic placement via `hyprctl`.
+- Added a Character Dictionary troubleshooting section covering name matching, inline portraits, and external-profile mode (no AniList auth required).
+- Added a "See Also" index linking each feature's own troubleshooting page.

docs-site/changelog.md

@@ -4,68 +4,151 @@
 
 **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.
+- **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: 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.
+- **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, 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.
+- **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; 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.
+- **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.
+- **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.
+- **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>
 

docs-site/character-dictionary.md

@@ -20,18 +20,15 @@ The feature has three stages: **snapshot**, **merge**, and **match**.
 
 Character dictionary sync is disabled by default. To turn it on:
 
-1. Authenticate with AniList (see [AniList Integration](/anilist-integration#setup)).
-2. Set `subtitleStyle.nameMatchEnabled` to `true` in your config or enable **Name Match Enabled** in Settings.
-3. Start watching — SubMiner will generate a snapshot for the current media and import the merged dictionary into Yomitan automatically.
+1. Enable **Name Match** in Settings → Subtitle Style, or set `subtitleStyle.nameMatchEnabled: true` in your config.
+2. Start watching — SubMiner queries AniList's public GraphQL API (no authentication required) and imports the merged dictionary into Yomitan automatically.
+3. Optionally enable **Name Match Images** (Settings → Subtitle Style) to show inline circular character portraits next to matched names in subtitles.
 
 ```jsonc
 {
-  "anilist": {
-    "enabled": true,
-    "accessToken": "your-token",
-  },
   "subtitleStyle": {
     "nameMatchEnabled": true,
+    "nameMatchImagesEnabled": true, // optional — inline portraits
   },
 }
 ```
@@ -40,6 +37,10 @@ Character dictionary sync is disabled by default. To turn it on:
 The first sync for a media title takes a few seconds while character data and portraits are fetched from AniList. Subsequent launches reuse the cached media match and snapshot without a fresh AniList lookup.
 :::
 
+::: info
+AniList character data is fetched via public GraphQL queries — no account or access token is needed. AniList authentication is only required for the separate [watch-progress sync](/anilist-integration) feature.
+:::
+
 ::: warning
 If `yomitan.externalProfilePath` is set, SubMiner switches to read-only external-profile mode. In that mode SubMiner can reuse another app's installed Yomitan dictionaries/settings, but SubMiner's own character-dictionary features are fully disabled.
 :::
@@ -106,6 +107,25 @@ Name matches are visually distinct from [N+1 targeting, frequency highlighting,
 | `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits beside names |
 | `subtitleStyle.nameMatchColor`         | `#f5bde6` | Highlight color for matched names         |
 
+## Inline Character Portraits
+
+When `subtitleStyle.nameMatchImagesEnabled` is enabled, SubMiner injects a small circular portrait image directly into the subtitle line next to each matched character name.
+
+Portraits are sourced from the local snapshot — they are embedded at snapshot-generation time and served from the cached ZIP, so no network request happens during playback. Images are downloaded from AniList CDN once per character and stored in `character-dictionaries/img/`.
+
+If a snapshot was generated before portrait data was available (e.g. during an earlier version or offline sync), SubMiner detects the missing image data on the next media match and automatically refreshes the snapshot so portraits are included in the next merged dictionary build.
+
+**To enable:**
+
+- Settings → Subtitle Style → **Name Match Images**, or
+- `subtitleStyle.nameMatchImagesEnabled: true` in config.
+
+The portrait size is controlled by the surrounding subtitle font size and renders as a circle clipped from the character's AniList cover image.
+
+::: tip
+Inline portraits help you quickly associate names with faces while building vocabulary — especially useful for shows with large casts where you're still learning who's who.
+:::
+
 ## Dictionary Entries
 
 Each character entry in the Yomitan dictionary includes structured content:
@@ -281,5 +301,5 @@ If you work with visual novels or want a standalone dictionary generator indepen
 ## Related
 
 - [Subtitle Annotations](/subtitle-annotations) — how name matches interact with N+1, frequency, and JLPT layers
-- [AniList Integration](/anilist-integration) — authentication, episode tracking, and AniList settings
+- [AniList Integration](/anilist-integration) — watch-progress sync and AniList authentication (separate from character dictionary)
 - [Configuration Reference](/configuration) — full config options

docs-site/troubleshooting.md

@@ -232,6 +232,15 @@ Japanese word boundaries depend on Yomitan parser output. If segmentation seems
 - Verify Yomitan dictionaries are installed and active.
 - Note that CJK characters without spaces are segmented using parser heuristics, which is not always perfect.
 
+## Character Dictionary
+
+Character names from AniList are matched and highlighted in subtitles via the bundled Yomitan. See [Character Dictionary](/character-dictionary) for setup and the full troubleshooting list — the most common issues:
+
+- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`, and that the current media resolved to an AniList entry (SubMiner needs a media ID to fetch characters). No AniList account or token is required — character data uses public GraphQL queries.
+- **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. Portraits also require AniList to return an image and the download to succeed during snapshot generation.
+- **Wrong characters showing:** Open the in-app manager (`Ctrl/Cmd+D`) and use **Override** to pin the correct AniList match for the series.
+- **Feature unavailable:** If `yomitan.externalProfilePath` is set, SubMiner runs in read-only external-profile mode and its character-dictionary features are disabled.
+
 ## Media Generation
 
 **"FFmpeg not found"**
@@ -324,11 +333,28 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
 
 ### Hyprland
 
-SubMiner's overlay is a transparent, frameless, always-on-top Electron window. Hyprland needs window rules to keep it transparent and borderless, and `pass` bindings to forward global shortcuts to SubMiner.
+SubMiner's overlay is a transparent, frameless, always-on-top Electron window. SubMiner tries to apply the floating, borderless, no-shadow, and no-blur properties itself each time it places the overlay. It detects Hyprland's active config provider and uses Lua `hl.dsp.window.*` dispatchers for recent Hyprland Lua configs, or the legacy dispatcher syntax for older hyprlang configs. On many configurations that is enough, but if your Hyprland version doesn't honor those runtime dispatches — or a broad rule in your config forces opacity/blur on every window — add explicit window rules so the overlay is exempt. You also need `pass` bindings to forward global shortcuts to SubMiner (see below).
 
 **Overlay is not transparent or has a visible border**
 
-Add these window rules to your `hyprland.conf`:
+Add a window rule matching SubMiner's window class. Recent Hyprland uses the Lua config format:
+
+```lua
+hl.window_rule({
+  match = { class = "^SubMiner$" },
+  float = true,
+  border_size = 0,
+  xray = false,
+  no_shadow = true,
+  no_blur = true,
+  no_dim = true,
+  opaque = true,
+  dim_around = false,
+  opacity = "1.0 override 1.0 override",
+})
+```
+
+On older Hyprland releases that still use the hyprlang config (`hyprland.conf`), use the equivalent `windowrule` lines:
 
 ```ini
 windowrule = float on, match:class SubMiner
@@ -338,7 +364,7 @@ windowrule = no_shadow on, match:class SubMiner
 windowrule = no_blur on, match:class SubMiner
 ```
 
-Without `xray off override`, the compositor may render the transparent overlay incorrectly — you might see a solid background or visual artifacts instead of the mpv video underneath.
+If you still see a solid background or visual artifacts instead of the mpv video underneath, the culprit is almost always a global opacity/blur rule applying to the overlay — the `opaque`/`opacity` and `no_blur` fields above override it.
 
 **Global shortcuts not working**
 
@@ -363,3 +389,20 @@ For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.l
 
 - **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.
 - **Gatekeeper**: If macOS blocks SubMiner, right-click the app and select "Open" to bypass the warning, or remove the quarantine attribute: `xattr -d com.apple.quarantine /path/to/SubMiner.app`
+
+## See Also
+
+Feature-specific issues are covered in each feature's own page:
+
+- [Anki Integration](/anki-integration) — card creation, field mapping, and AnkiConnect setup
+- [AniList Integration](/anilist-integration) — watch-progress sync and authentication
+- [Character Dictionary](/character-dictionary) — AniList character name matching and inline portraits
+- [Jellyfin Integration](/jellyfin-integration) — remote playback and library connection
+- [Jimaku Integration](/jimaku-integration) — subtitle fetching and API rate limits
+- [YouTube Integration](/youtube-integration) — subtitle generation and playback
+- [Immersion Tracking](/immersion-tracking) — telemetry and session logging
+- [WebSocket / Texthooker API](/websocket-texthooker-api) — external texthooker clients
+- [Subtitle Annotations](/subtitle-annotations) — N+1, frequency, JLPT, and name-match layers
+- [Subtitle Sidebar](/subtitle-sidebar) — sidebar navigation and behavior
+- [Configuration Reference](/configuration) — full config options
+- [Shortcuts](/shortcuts) — keybinding reference

docs/RELEASING.md

@@ -33,7 +33,7 @@
    `bun run build`
    When validating auto-update metadata, also run the relevant platform package
    build and confirm `release/` contains the generated updater metadata
-   (`*.yml`) and blockmaps (`*.blockmap`).
+   (`latest*.yml`) and blockmaps (`*.blockmap`).
 8. If `docs-site/` changed, also run:
    `bun run docs:test`
    `bun run docs:build`
@@ -55,7 +55,7 @@
    `bun run test:env`
    `bun run build`
    When validating packaged updater output, confirm the platform build writes
-   `*.yml` and `*.blockmap` files under `release/`.
+   `latest*.yml` and `*.blockmap` files under `release/`.
 5. Commit the prerelease prep (package.json version bump + the generated
    `release/prerelease-notes.md`). CI does not regenerate notes — it uses the
    committed file — so review it before committing. If you add more
@@ -87,7 +87,7 @@ Notes:
 - Keep Cloudflare Pages Git auto-deploy disabled for `docs.subminer.moe`. Production docs are direct-uploaded by Wrangler from GitHub Actions with `--branch main`.
 - AUR publish is best-effort: the workflow retries transient SSH clone/push failures, then warns and leaves the GitHub Release green if AUR still fails. Follow up with a manual `git push aur master` from the AUR checkout when needed.
 - Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.
-- Release and prerelease workflows upload updater metadata (`*.yml`) and blockmaps (`*.blockmap`) alongside platform artifacts. Do not remove those files while `electron-updater` is enabled.
+- Release and prerelease workflows upload updater metadata (`latest*.yml`) and blockmaps (`*.blockmap`) alongside platform artifacts. Do not remove those files while `electron-updater` is enabled.
 - macOS tray app updates use the standard `electron-updater`/Squirrel path. Keep `latest-mac.yml`, the macOS `SubMiner-<version>-mac.zip`, and ZIP blockmap published; Squirrel uses the ZIP payload even when the DMG remains the user-facing installer.
 - macOS update metadata and full ZIP downloads are routed through `/usr/bin/curl` before Squirrel installation to avoid Electron main-process network crashes on update checks.
 - Windows tray app updates use the standard `electron-updater`/NSIS path. Keep `latest.yml`, the Windows NSIS installer, and installer blockmap published; updater HTTP is routed through main-process fetch to avoid Electron main-process network crashes during update checks.

release/release-notes.md

@@ -1,70 +0,0 @@
-## Highlights
-### 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.
-
-## Installation
-
-See the README and docs/installation guide for full setup steps.
-
-## Assets
-
-- Linux: `SubMiner.AppImage`
-- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
-- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
-- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
-
-Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.

src/core/services/hyprland-window-placement.test.ts

@@ -95,6 +95,54 @@ test('buildHyprlandPlacementDispatches force-aligns floating overlay windows to
   );
 });
 
+test('buildHyprlandPlacementDispatches emits Lua dispatchers for Lua-config Hyprland sessions', () => {
+  assert.deepEqual(
+    buildHyprlandPlacementDispatches(
+      {
+        address: '0xabc',
+        floating: false,
+        pinned: true,
+      },
+      {
+        x: 0,
+        y: 0,
+        width: 1920,
+        height: 1080,
+      },
+      {
+        configProvider: 'lua',
+      },
+    ),
+    [
+      ['dispatch', 'hl.dsp.window.float({ action = "on", window = "address:0xabc" })'],
+      ['dispatch', 'hl.dsp.window.pin({ action = "off", window = "address:0xabc" })'],
+      ['dispatch', 'hl.dsp.window.move({ x = 0, y = 0, window = "address:0xabc" })'],
+      ['dispatch', 'hl.dsp.window.resize({ x = 1920, y = 1080, window = "address:0xabc" })'],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "rounding", value = "0", window = "address:0xabc" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "border_size", value = "0", window = "address:0xabc" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "no_shadow", value = "1", window = "address:0xabc" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "no_blur", value = "1", window = "address:0xabc" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "decorate", value = "0", window = "address:0xabc" })',
+      ],
+      ['dispatch', 'hl.dsp.window.alter_zorder({ mode = "top", window = "address:0xabc" })'],
+    ],
+  );
+});
+
 test('buildHyprlandPlacementDispatches does not pin already floating overlay windows', () => {
   assert.deepEqual(
     buildHyprlandPlacementDispatches({
@@ -177,6 +225,9 @@ test('ensureHyprlandWindowFloatingByTitle dispatches float-only placement for ma
           },
         ]);
       }
+      if (args.join(' ') === '-j status') {
+        return JSON.stringify({ configProvider: 'hyprlang' });
+      }
       return '';
     }) as never,
   });
@@ -186,6 +237,7 @@ test('ensureHyprlandWindowFloatingByTitle dispatches float-only placement for ma
     calls.map(([, args]) => args),
     [
       ['-j', 'clients'],
+      ['-j', 'status'],
       ['dispatch', 'setfloating', 'address:0xmatch'],
       ['dispatch', 'alterzorder', 'top,address:0xmatch'],
     ],
@@ -221,6 +273,9 @@ test('ensureHyprlandWindowFloatingByTitle dispatches exact Hyprland geometry whe
           },
         ]);
       }
+      if (args.join(' ') === '-j status') {
+        return JSON.stringify({ configProvider: 'hyprlang' });
+      }
       return '';
     }) as never,
   });
@@ -230,6 +285,7 @@ test('ensureHyprlandWindowFloatingByTitle dispatches exact Hyprland geometry whe
     calls.map(([, args]) => args),
     [
       ['-j', 'clients'],
+      ['-j', 'status'],
       ['dispatch', 'movewindowpixel', 'exact 0 0,address:0xmatch'],
       ['dispatch', 'resizewindowpixel', 'exact 1920 1080,address:0xmatch'],
       ['dispatch', 'setprop', 'address:0xmatch rounding 0'],
@@ -241,3 +297,72 @@ test('ensureHyprlandWindowFloatingByTitle dispatches exact Hyprland geometry whe
     ],
   );
 });
+
+test('ensureHyprlandWindowFloatingByTitle dispatches Lua syntax for Lua-config Hyprland sessions', () => {
+  const calls: unknown[][] = [];
+  const placed = ensureHyprlandWindowFloatingByTitle({
+    title: 'SubMiner Stats',
+    platform: 'linux',
+    env: {
+      HYPRLAND_INSTANCE_SIGNATURE: 'abc',
+    },
+    pid: 456,
+    bounds: {
+      x: 0,
+      y: 0,
+      width: 1920,
+      height: 1080,
+    },
+    execFileSync: ((command: string, args: string[], options: unknown) => {
+      calls.push([command, args, options]);
+      if (args.join(' ') === '-j clients') {
+        return JSON.stringify([
+          {
+            address: '0xmatch',
+            pid: 456,
+            title: 'SubMiner Stats',
+            mapped: true,
+            floating: true,
+            pinned: false,
+          },
+        ]);
+      }
+      if (args.join(' ') === '-j status') {
+        return JSON.stringify({ configProvider: 'lua' });
+      }
+      return '';
+    }) as never,
+  });
+
+  assert.equal(placed, true);
+  assert.deepEqual(
+    calls.map(([, args]) => args),
+    [
+      ['-j', 'clients'],
+      ['-j', 'status'],
+      ['dispatch', 'hl.dsp.window.move({ x = 0, y = 0, window = "address:0xmatch" })'],
+      ['dispatch', 'hl.dsp.window.resize({ x = 1920, y = 1080, window = "address:0xmatch" })'],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "rounding", value = "0", window = "address:0xmatch" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "border_size", value = "0", window = "address:0xmatch" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "no_shadow", value = "1", window = "address:0xmatch" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "no_blur", value = "1", window = "address:0xmatch" })',
+      ],
+      [
+        'dispatch',
+        'hl.dsp.window.set_prop({ prop = "decorate", value = "0", window = "address:0xmatch" })',
+      ],
+      ['dispatch', 'hl.dsp.window.alter_zorder({ mode = "top", window = "address:0xmatch" })'],
+    ],
+  );
+});

src/core/services/hyprland-window-placement.ts

@@ -19,10 +19,12 @@ export interface HyprlandPlacementBounds {
 }
 
 export interface HyprlandPlacementDispatchOptions {
+  configProvider?: HyprlandConfigProvider;
   promote?: boolean;
 }
 
 type ExecFileSync = typeof execFileSync;
+export type HyprlandConfigProvider = 'hyprlang' | 'lua';
 
 export function shouldAttemptHyprlandWindowPlacement(
   platform: NodeJS.Platform = process.platform,
@@ -75,15 +77,43 @@ export function buildHyprlandPlacementDispatches(
   }
 
   const windowAddress = `address:${client.address}`;
+  const configProvider = options.configProvider ?? 'hyprlang';
   const dispatches: string[][] = [];
   if (client.floating !== true) {
-    dispatches.push(['dispatch', 'setfloating', windowAddress]);
+    dispatches.push(
+      configProvider === 'lua'
+        ? luaWindowDispatch('float', windowAddress, ['action = "on"'])
+        : ['dispatch', 'setfloating', windowAddress],
+    );
   }
   if (client.pinned === true) {
-    dispatches.push(['dispatch', 'pin', windowAddress]);
+    dispatches.push(
+      configProvider === 'lua'
+        ? luaWindowDispatch('pin', windowAddress, ['action = "off"'])
+        : ['dispatch', 'pin', windowAddress],
+    );
   }
   const roundedBounds = roundPlacementBounds(bounds);
   if (roundedBounds) {
+    if (configProvider === 'lua') {
+      dispatches.push(
+        luaWindowDispatch('move', windowAddress, [
+          `x = ${roundedBounds.x}`,
+          `y = ${roundedBounds.y}`,
+        ]),
+      );
+      dispatches.push(
+        luaWindowDispatch('resize', windowAddress, [
+          `x = ${roundedBounds.width}`,
+          `y = ${roundedBounds.height}`,
+        ]),
+      );
+      dispatches.push(luaWindowSetProp(windowAddress, 'rounding', '0'));
+      dispatches.push(luaWindowSetProp(windowAddress, 'border_size', '0'));
+      dispatches.push(luaWindowSetProp(windowAddress, 'no_shadow', '1'));
+      dispatches.push(luaWindowSetProp(windowAddress, 'no_blur', '1'));
+      dispatches.push(luaWindowSetProp(windowAddress, 'decorate', '0'));
+    } else {
       dispatches.push([
         'dispatch',
         'movewindowpixel',
@@ -100,12 +130,35 @@ export function buildHyprlandPlacementDispatches(
       dispatches.push(['dispatch', 'setprop', `${windowAddress} no_blur 1`]);
       dispatches.push(['dispatch', 'setprop', `${windowAddress} decorate 0`]);
     }
+  }
   if (options.promote !== false) {
-    dispatches.push(['dispatch', 'alterzorder', `top,${windowAddress}`]);
+    dispatches.push(
+      configProvider === 'lua'
+        ? luaWindowDispatch('alter_zorder', windowAddress, ['mode = "top"'])
+        : ['dispatch', 'alterzorder', `top,${windowAddress}`],
+    );
   }
   return dispatches;
 }
 
+function luaWindowDispatch(name: string, windowAddress: string, fields: string[]): string[] {
+  return [
+    'dispatch',
+    `hl.dsp.window.${name}({ ${[...fields, `window = ${luaString(windowAddress)}`].join(', ')} })`,
+  ];
+}
+
+function luaWindowSetProp(windowAddress: string, prop: string, value: string): string[] {
+  return luaWindowDispatch('set_prop', windowAddress, [
+    `prop = ${luaString(prop)}`,
+    `value = ${luaString(value)}`,
+  ]);
+}
+
+function luaString(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
 function roundPlacementBounds(
   bounds?: HyprlandPlacementBounds | null,
 ): HyprlandPlacementBounds | null {
@@ -154,7 +207,9 @@ export function ensureHyprlandWindowFloatingByTitle(options: {
       return false;
     }
 
+    const configProvider = detectHyprlandConfigProvider(run);
     const dispatches = buildHyprlandPlacementDispatches(client, options.bounds, {
+      configProvider,
       promote: options.promote,
     });
     for (const args of dispatches) {
@@ -165,3 +220,27 @@ export function ensureHyprlandWindowFloatingByTitle(options: {
     return false;
   }
 }
+
+function detectHyprlandConfigProvider(run: ExecFileSync): HyprlandConfigProvider {
+  try {
+    return parseHyprlandConfigProvider(
+      String(run('hyprctl', ['-j', 'status'], { encoding: 'utf-8' })),
+    );
+  } catch {
+    return 'hyprlang';
+  }
+}
+
+function parseHyprlandConfigProvider(output: string): HyprlandConfigProvider {
+  const payloadStart = output.indexOf('{');
+  if (payloadStart < 0) {
+    return 'hyprlang';
+  }
+
+  const parsed = JSON.parse(output.slice(payloadStart)) as unknown;
+  return isHyprlandStatusPayload(parsed) && parsed.configProvider === 'lua' ? 'lua' : 'hyprlang';
+}
+
+function isHyprlandStatusPayload(value: unknown): value is { configProvider?: unknown } {
+  return Boolean(value) && typeof value === 'object';
+}

src/prerelease-workflow.test.ts

@@ -69,14 +69,19 @@ test('prerelease workflow builds and uploads all release platforms', () => {
 test('prerelease workflow publishes the same release assets as the stable workflow', () => {
   assert.match(
     prereleaseWorkflow,
-    /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\)/,
   );
   assert.match(
     prereleaseWorkflow,
-    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*\)/,
+    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/latest\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*\)/,
   );
 });
 
+test('prerelease workflow uploads updater metadata without builder debug YAML files', () => {
+  assert.match(prereleaseWorkflow, /release\/latest\*\.yml/);
+  assert.doesNotMatch(prereleaseWorkflow, /release\/\*\.yml/);
+});
+
 test('prerelease workflow writes checksum entries using release asset basenames', () => {
   assert.match(prereleaseWorkflow, /: > release\/SHA256SUMS\.txt/);
   assert.match(prereleaseWorkflow, /for file in "\$\{files\[@\]\}"; do/);

src/release-workflow.test.ts

@@ -105,14 +105,19 @@ test('release workflow generates release notes from committed changelog output',
 test('release workflow includes the Windows installer in checksums and uploaded assets', () => {
   assert.match(
     releaseWorkflow,
-    /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\)/,
   );
   assert.match(
     releaseWorkflow,
-    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*\)/,
+    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/latest\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*\)/,
   );
 });
 
+test('release workflow uploads updater metadata without builder debug YAML files', () => {
+  assert.match(releaseWorkflow, /release\/latest\*\.yml/);
+  assert.doesNotMatch(releaseWorkflow, /release\/\*\.yml/);
+});
+
 test('release package metadata enables GitHub updater metadata without builder uploads', () => {
   assert.equal(packageJson.build?.publish?.[0]?.provider, 'github');
   assert.equal(packageJson.build?.publish?.[0]?.owner, 'ksyasuda');