feat(stats): use generic title wording for mixed-source library

The stats dashboard now supports both anime series and YouTube videos
in the same library, so the anime-only copy no longer fits. Rename
user-visible labels ("Active Anime", "Search anime…", "Anime — Per
Day", "Episodes per Anime", "Words In Multiple Anime", etc.) to use
"Title"/"Library" wording that covers either source.

Data-model names (animeId, animeCount, useAnimeLibrary) stay as-is;
this pass only touches strings the user actually reads.

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v0.11.2 (2026-04-07)
+
+### Changed
+- Launcher: Replaced the launcher-only fullscreen toggle with `mpv.launchMode` so SubMiner-managed mpv playback can start in normal, maximized, or fullscreen mode.
+
+### Fixed
+- Launcher: Fixed launcher-managed mpv spawning to force an explicit X11 GPU path when Wayland trackers are unavailable.
+- Launcher: Local playback now promotes a single unlabeled external subtitle sidecar to the primary slot instead of leaving mpv's embedded English auto-selection in place.
+- Release: Fixed Linux AppImage startup packaging so Chromium child relaunches can resolve the bundled `libffmpeg.so` instead of crash-looping on startup.
+
 ## v0.11.1 (2026-04-04)
 
 ### Fixed

README.md

@@ -65,6 +65,10 @@ Local stats dashboard — watch time, anime library, vocabulary growth, mining t
 
 Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.
 
+<div align="center">
+  <img src="docs-site/public/screenshots/playlist-browser.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
+</div>
+
 <br>
 
 ### Integrations
@@ -106,12 +110,12 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
 
 ## Requirements
 
-|                | Required                                | Recommended                              | Optional                                                    |
-| -------------- | --------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
-| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                        | —                                                           |
-| **Processing** | —                                       | `ffmpeg` (audio clips & screenshots)     | `mecab` + `mecab-ipadic` (annotation POS filtering), `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
-| **Media**      | —                                       | —                                        | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                      |
-| **Selection**  | —                                       | —                                        | `fzf` / `rofi`                                              |
+|                | Required                                | Recommended                          | Optional                                                                                                        |
+| -------------- | --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                    | —                                                                                                               |
+| **Processing** | —                                       | `ffmpeg` (audio clips & screenshots) | `mecab` + `mecab-ipadic` (annotation POS filtering), `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
+| **Media**      | —                                       | —                                    | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                                                                          |
+| **Selection**  | —                                       | —                                    | `fzf` / `rofi`                                                                                                  |
 
 > [!TIP]
 > `ffmpeg` is not strictly required to run SubMiner, but without it audio clips and screenshots will not be attached to Anki cards. Most users will want it installed.
@@ -121,9 +125,12 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
 
 **Platform-specific:**
 
-| Linux                               | macOS                    | Windows       |
-| ----------------------------------- | ------------------------ | ------------- |
-| `hyprctl` or `xdotool` + `xwininfo` | Accessibility permission | No extra deps |
+| Linux                                                        | macOS                    | Windows       |
+| ------------------------------------------------------------ | ------------------------ | ------------- |
+| Hyprland (`hyprctl`) · X11/Xwayland (`xdotool` + `xwininfo`) | Accessibility permission | No extra deps |
+
+> [!NOTE]
+> **Wayland support is compositor-specific.** Wayland has no universal API for window positioning and each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Hyprland is the only native Wayland backend supported currenlty. All other Linux compositors require both mpv and SubMiner to run under X11 or Xwayland. The launcher detects your compositor and configures this automatically.
 
 <details>
 <summary><b>Arch Linux</b></summary>
@@ -134,7 +141,7 @@ paru -S --needed mpv ffmpeg
 paru -S --needed mecab-git mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo
 # Optional: subtitle sync (install at least one for subtitle syncing to work)
 paru -S --needed alass python-ffsubsync
-# X11 / XWAYLAND
+# X11 / Xwayland (required for non-Hyprland compositors)
 paru -S --needed xdotool xorg-xwininfo
 ```
 
@@ -237,7 +244,18 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 
 </details>
 
-### 2. Check Dependencies
+### 2. First Launch
+
+```bash
+subminer app --setup            # launch the first-run setup wizard
+```
+
+SubMiner creates a default config, starts in the system tray, and opens a setup popup that walks you through installing the mpv plugin and configuring Yomitan dictionaries. Follow the on-screen steps to complete setup.
+
+> [!NOTE]
+> On Windows, run `SubMiner.exe` directly — it opens the setup wizard automatically on first launch.
+
+### 3. Verify Setup
 
 ```bash
 subminer doctor                 # verify mpv, ffmpeg, config, and socket
@@ -246,10 +264,6 @@ subminer doctor                 # verify mpv, ffmpeg, config, and socket
 > [!NOTE]
 > On Windows, use `bun run subminer doctor` or run `SubMiner.exe` directly — first-run setup will guide you through dependency checks.
 
-### 3. First Launch
-
-Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to finish config, install the mpv plugin, and configure Yomitan dictionaries.
-
 ### 4. Mine
 
 ```bash
@@ -260,7 +274,7 @@ subminer stats -b           # stats daemon in background
 subminer stats -s           # stop background stats daemon
 ```
 
-On **Windows**, the `subminer` script must be run with `bun run subminer` (e.g. `bun run subminer video.mkv`). The recommended alternative is the **SubMiner mpv** shortcut (created during setup) or `SubMiner.exe --launch-mpv`.  Drag a video file onto the shortcut to play it, or double-click it to open mpv with SubMiner's defaults.
+On **Windows**, the `subminer` script must be run with `bun run subminer` (e.g. `bun run subminer video.mkv`). The recommended alternative is the **SubMiner mpv** shortcut (created during setup) or `SubMiner.exe --launch-mpv`. Drag a video file onto the shortcut to play it, or double-click it to open mpv with SubMiner's defaults.
 
 ## Documentation
 

backlog/tasks/task-279 - Fix-Linux-AppImage-child-process-libffmpeg-resolution.md

@@ -0,0 +1,62 @@
+---
+id: TASK-279
+title: Fix Linux AppImage child-process libffmpeg resolution
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-04-05 17:17'
+updated_date: '2026-04-05 17:56'
+labels: []
+dependencies: []
+references:
+  - 'https://github.com/ksyasuda/SubMiner/issues/41'
+documentation:
+  - docs/workflow/verification.md
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the Linux AppImage packaging so Chromium child processes relaunched from the bundled binary can resolve the packaged libffmpeg shared library and SubMiner starts cleanly instead of crash-looping on network-service restarts.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Linux AppImage packaging ensures bundled Chromium child processes can resolve the packaged libffmpeg shared library during relaunch.
+- [x] #2 Regression coverage exercises the Linux packaging/build configuration that provides the AppImage shared-library path.
+- [x] #3 Release notes/changelog reflect the Linux AppImage startup fix.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add focused regression tests for Linux release packaging that assert the build config invokes an `afterPack` hook and that the hook stages bundled `libffmpeg.so` into `usr/lib` for AppImage runtime lookup.
+2. Implement a small electron-builder `afterPack` hook that runs only for Linux, copies `libffmpeg.so` from the packaged app root into `usr/lib`, and no-ops when the source library is absent.
+3. Wire the hook into `package.json` build config and add a changelog fragment for the Linux AppImage startup fix.
+4. Run the focused test lane first, then the default handoff gate because the change touches release-sensitive packaging behavior.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Chose a repo-local electron-builder `afterPack` hook instead of patching/forking `electron-builder`. The hook copies bundled `libffmpeg.so` from the packaged Linux app root into `usr/lib`, matching the AppImage runtime's existing `LD_LIBRARY_PATH` search path.
+
+Added regression coverage for both config wiring (`src/release-workflow.test.ts`) and the hook behavior (`scripts/electron-builder-after-pack.test.ts`), then wired the new script test into `test:fast` so the maintained lane keeps exercising the fix.
+
+Verification passed: `bun test scripts/electron-builder-after-pack.test.ts src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`, `bun run test:env`, `bun run build`, `bun run test:smoke:dist`.
+
+Addressed PR #45 CodeRabbit review thread: Linux `afterPack` staging now hard-fails when `libffmpeg.so` is missing instead of silently no-oping. Updated focused hook tests to assert the new failure contract and that `afterPack` propagates Linux staging errors.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added a shared electron-builder `afterPack` hook at `scripts/electron-builder-after-pack.cjs` and wired it into `package.json` so Linux packaging stages the bundled `libffmpeg.so` into `usr/lib` inside the packaged app. This keeps Chromium child relaunches compatible with the AppImage runtime's existing `LD_LIBRARY_PATH` layout without forking or patching upstream `electron-builder`.
+
+Regression coverage now checks both the packaging config and the hook behavior: `src/release-workflow.test.ts` asserts the hook stays wired into release config, and `scripts/electron-builder-after-pack.test.ts` verifies Linux copies `libffmpeg.so` into `usr/lib` while non-Linux and missing-library cases no-op safely. The new script test is included in `test:fast`, and a changelog fragment was added under `changes/fix-appimage-libffmpeg-path.md`.
+
+Verification passed with `bun test scripts/electron-builder-after-pack.test.ts src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
+
+Follow-up review fix on PR #45: Linux packaging now throws when `libffmpeg.so` is missing from the packaged app root, preventing silent shipment of a broken AppImage. Focused regression coverage was updated so the missing-library case rejects and `afterPack` propagates the failure.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-280 - Force-launcher-spawned-mpv-onto-X11-when-backend-resolves-to-x11-or-no-supported-Wayland-tracker-is-available.md

@@ -0,0 +1,59 @@
+---
+id: TASK-280
+title: >-
+  Force launcher-spawned mpv onto X11 when backend resolves to x11 or no
+  supported Wayland tracker is available
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-05 21:01'
+updated_date: '2026-04-05 21:05'
+labels:
+  - bug
+  - linux
+  - launcher
+  - overlay
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+On Linux Plasma Wayland and similar sessions, `subminer --backend=x11` currently only changes SubMiner's window-tracker override. The launcher still spawns mpv without forcing an X11/XWayland backend, so the X11 tracker cannot find the mpv window and the overlay remains hidden. Update launcher-side mpv spawn behavior so launcher-managed mpv runs under X11 when backend resolves to `x11`, and also when auto detection cannot resolve to a supported Wayland tracker. Preserve existing Hyprland/Sway behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Launcher-managed mpv is spawned with X11/XWayland-forcing environment/config when backend resolves to `x11`.
+- [x] #2 Linux auto mode falls back to X11/XWayland-forced mpv when no supported Wayland tracker backend is detected.
+- [x] #3 Hyprland and Sway launcher flows do not regress to forced X11 mpv.
+- [x] #4 Regression tests cover launcher env/backend selection for these Linux cases.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add focused launcher tests that assert the mpv spawn environment forces X11 when backend resolves to `x11`, and when Linux auto mode cannot use a supported Wayland tracker.
+2. Refactor launcher mpv spawn code to compute an mpv-specific environment without changing existing Hyprland/Sway flows.
+3. Route all launcher-managed mpv spawns through the new environment helper.
+4. Run focused launcher tests, then summarize behavior and any remaining verification gaps.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+User approved scope: force launcher-managed mpv to X11 for explicit `--backend=x11` and for unsupported Linux Wayland auto-detect fallback; preserve Hyprland/Sway behavior.
+
+Implemented launcher-side `buildMpvEnv` to strip Wayland hints and force X11/XWayland for launcher-managed mpv when `--backend=x11`, and for Linux auto mode on unsupported Wayland desktops with an X11 display available. Wired both normal mpv launches and idle detached mpv launches through the helper.
+
+Verification: `bun test launcher/mpv.test.ts --test-name-pattern "buildMpvEnv"` passed; `bun run tsc --noEmit` passed. A broader `bun test launcher/mpv.test.ts` run still hits a pre-existing sandbox-specific failure in `launchAppCommandDetached handles child process spawn errors` because this environment cannot write the default app log path under `/home/sudacode/.config/SubMiner/logs`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated the launcher so mpv gets an X11/XWayland-oriented spawn environment whenever the user explicitly requests `--backend=x11`, and when Linux auto mode is running under an unsupported Wayland desktop that still exposes an X11 display. The new helper reuses the launcher child-process base environment, strips Wayland-specific hints (`WAYLAND_DISPLAY`, Hyprland/Sway markers), and flips `XDG_SESSION_TYPE` to `x11` only for those fallback cases. Both foreground mpv launches and detached idle mpv launches now use the same helper so overlay-tracked playback stays consistent.
+
+Added focused regression coverage in `launcher/mpv.test.ts` for three cases: explicit `x11` forcing, unsupported Wayland auto fallback (for example KDE Plasma Wayland), and preserving native Wayland env for supported Hyprland/Sway auto backends. Verification completed with `bun test launcher/mpv.test.ts --test-name-pattern "buildMpvEnv"` and `bun run tsc --noEmit`. A broader launcher mpv test run still shows an unrelated sandbox write failure for the default app log path in this environment.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-281 - Prevent-Windows-launcher-tests-from-leaking-backslash-temp-files-on-POSIX.md

@@ -0,0 +1,62 @@
+---
+id: TASK-281
+title: Prevent Windows launcher tests from leaking backslash temp files on POSIX
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-05 21:13'
+updated_date: '2026-04-05 21:20'
+labels:
+  - tests
+  - launcher
+  - bug
+dependencies: []
+documentation:
+  - /home/sudacode/github/SubMiner2/AGENTS.md
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Windows-specific launcher tests in launcher/mpv.test.ts currently create real filesystem entries using path.win32.join(...) with a POSIX mkdtemp base. On Linux/macOS this produces literal backslash-named paths like \\tmp\\subminer-test-win-dir-* inside the repo/worktree, and the existing cleanup only removes the POSIX /tmp base directory. Fix the tests so they still cover Windows path resolution behavior without leaking stray files into the working tree.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Running the Windows findAppBinary tests on a POSIX host does not create new untracked \\tmp\\subminer-test-win-* files in the repository root.
+- [x] #2 The Windows launcher tests still validate PATH and install-directory resolution behavior.
+- [x] #3 Relevant launcher tests pass after the change.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a regression test in launcher/mpv.test.ts that exercises the Windows findAppBinary cases on a POSIX host and asserts they do not leave new backslash-named temp artifacts in the repository root.
+2. Refactor the Windows launcher tests to avoid creating real filesystem paths from path.win32.join(...) on POSIX; keep Windows path assertions via stubs and only create real files with native POSIX paths where needed.
+3. Run the targeted launcher tests and confirm no new \\tmp\\subminer-test-win-* artifacts appear in git status.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Investigation: reproduced the leak locally. The source is launcher/mpv.test.ts Windows findAppBinary tests that combine a POSIX mkdtemp base with path.win32.join(...), creating literal backslash-named entries like \\tmp\\subminer-test-win-dir-* in the repo root. Existing cleanup only removes the POSIX /tmp base directory.
+
+User approved implementation plan on 2026-04-05.
+
+Implemented in launcher/mpv.test.ts by replacing the leaky Windows PATH/install-directory helpers with pure fs stubs (access/exists/stat) and fixed Windows path strings instead of creating real path.win32 filesystem entries on POSIX. Added a regression test that snapshots repo-root \\tmp\\subminer-test-win-* artifacts before/after running the Windows cases and asserts no new entries are created.
+
+Verification: `bun test launcher/mpv.test.ts --test-name-pattern 'findAppBinary Windows cases do not leak backslash temp artifacts on POSIX|findAppBinary resolves SubMiner.exe on PATH on Windows|findAppBinary resolves a Windows install directory to SubMiner.exe'` passed (3/3). `bun test launcher/mpv.test.ts` still has one unrelated pre-existing sandbox failure in `launchAppCommandDetached handles child process spawn errors` because the test opens `~/.config/SubMiner/logs/app-2026-04-05.log` and hits `EROFS` in this environment.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Reworked the Windows `findAppBinary` tests in `launcher/mpv.test.ts` so they no longer create real backslash-named temp files on POSIX hosts. The PATH and install-directory cases now use synthetic Windows path strings plus `fs.accessSync` / `fs.existsSync` / `fs.statSync` stubs to exercise the same resolver behavior without writing `\\tmp\\subminer-test-win-*` entries into the repository root.
+
+Added a POSIX regression test that snapshots existing repo-root `\\tmp\\subminer-test-win-*` artifacts, runs the Windows path-resolution cases, and asserts the artifact set is unchanged. This catches future regressions where a Windows-path test accidentally writes literal backslash paths on Linux/macOS.
+
+Tests run:
+- `bun test launcher/mpv.test.ts --test-name-pattern 'findAppBinary Windows cases do not leak backslash temp artifacts on POSIX|findAppBinary resolves SubMiner.exe on PATH on Windows|findAppBinary resolves a Windows install directory to SubMiner.exe'`
+- `bun test launcher/mpv.test.ts` (all relevant `findAppBinary` tests passed; one unrelated existing sandbox failure remains in `launchAppCommandDetached handles child process spawn errors` due `EROFS` opening `~/.config/SubMiner/logs/...`)
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-282 - Force-launcher-managed-mpv-to-an-explicit-X11-GPU-context-when-X11-fallback-is-active.md

@@ -0,0 +1,58 @@
+---
+id: TASK-282
+title: >-
+  Force launcher-managed mpv to an explicit X11 GPU context when X11 fallback is
+  active
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-05 21:14'
+updated_date: '2026-04-05 21:15'
+labels:
+  - bug
+  - linux
+  - launcher
+  - mpv
+  - overlay
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Follow-up to the launcher X11 fallback work: on Plasma Wayland, stripping Wayland env vars alone is not sufficient for launcher-managed mpv. mpv can still fail GPU initialization under the default video output path (`vo/gpu-next`) unless an explicit X11 GPU context is selected. Update launcher-managed mpv startup so X11 fallback mode also appends explicit mpv options for an X11 GPU context, while preserving supported Hyprland/Sway Wayland flows.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Launcher-managed mpv appends explicit X11 GPU context args when explicit `--backend=x11` is used on Linux.
+- [x] #2 Launcher-managed mpv appends the same explicit X11 GPU context args for Linux auto-mode fallback on unsupported Wayland desktops.
+- [x] #3 Supported Hyprland/Sway Wayland flows do not receive the forced X11 GPU context args.
+- [x] #4 Regression tests cover the forced-X11 mpv arg selection.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add focused launcher tests for explicit X11 GPU-context arg selection, unsupported Wayland auto fallback, and Hyprland/Sway no-regression cases.
+2. Introduce a shared launcher helper that decides when mpv should be forced onto X11 fallback mode.
+3. Use that helper to append explicit mpv X11 GPU-context args in both normal and detached idle mpv launch paths.
+4. Run focused launcher tests plus TypeScript verification, then record remaining runtime follow-up guidance.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+User runtime log showed `vo/gpu-next` failing with `Failed initializing any suitable GPU context!` under forced-X11 playback, which indicates env forcing alone was insufficient. Selected `--gpu-context=x11egl,x11` as the explicit mpv fallback: prefer X11/EGL, with GLX as a compatibility fallback.
+
+Verification: `bun test launcher/mpv.test.ts --test-name-pattern "buildMpv(Env|BackendArgs)"` passed. `bun run tsc --noEmit` passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added explicit mpv backend args for launcher-managed X11 fallback mode. The launcher now uses a shared `shouldForceX11MpvBackend` decision for both env rewriting and mpv arg selection, so explicit `--backend=x11` and unsupported Linux Wayland auto fallback both append `--gpu-context=x11egl,x11` while still stripping Wayland env hints. This preserves supported Hyprland/Sway native Wayland flows and makes the X11 fallback more explicit for mpv's GPU initialization path.
+
+Wired the new X11 GPU-context args into both the normal playback launch path and the detached idle mpv launch path. Added focused regression coverage for explicit `x11`, Plasma-style unsupported Wayland auto fallback, and Hyprland/Sway no-regression behavior. Verification completed with `bun test launcher/mpv.test.ts --test-name-pattern "buildMpv(Env|BackendArgs)"` and `bun run tsc --noEmit`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-283 - Force-launcher-managed-X11-fallback-to-mpv-vogpu-with-OpenGL-on-Linux.md

@@ -0,0 +1,56 @@
+---
+id: TASK-283
+title: Force launcher-managed X11 fallback to mpv vo=gpu with OpenGL on Linux
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-05 21:19'
+updated_date: '2026-04-05 21:20'
+labels:
+  - bug
+  - linux
+  - launcher
+  - mpv
+  - overlay
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Follow-up to explicit X11 gpu-context forcing: Plasma Wayland runtime logs still show mpv using `vo/gpu-next` and failing to initialize any suitable GPU context under launcher-managed X11 fallback. Update launcher-managed mpv X11 fallback mode to force a more compatible renderer stack: `--vo=gpu`, `--gpu-api=opengl`, and `--gpu-context=x11egl,x11`, while preserving supported native Wayland flows and allowing explicit user mpv args to override later on the command line.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Launcher-managed mpv appends `--vo=gpu`, `--gpu-api=opengl`, and `--gpu-context=x11egl,x11` when explicit `--backend=x11` is used on Linux.
+- [x] #2 Launcher-managed mpv appends the same renderer args for Linux auto-mode fallback on unsupported Wayland desktops.
+- [x] #3 Supported Hyprland/Sway Wayland flows do not receive the forced X11 renderer args.
+- [x] #4 Regression tests cover the forced-X11 renderer arg selection.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Tighten launcher tests so forced-X11 renderer args require `--vo=gpu`, `--gpu-api=opengl`, and `--gpu-context=x11egl,x11`.
+2. Update the shared launcher X11-fallback helper to return the full renderer arg stack for explicit `x11` and unsupported Wayland auto fallback.
+3. Re-run focused launcher env/backend tests and TypeScript verification.
+4. Hand back with retry instructions and next debugging branch if runtime still fails.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Runtime log still showed `[vo/gpu-next] Failed initializing any suitable GPU context!`, which meant forcing only the context was not enough. Updated the fallback to force the classic OpenGL renderer path too: `--vo=gpu --gpu-api=opengl --gpu-context=x11egl,x11`.
+
+Verification: `bun test launcher/mpv.test.ts --test-name-pattern "buildMpv(Env|BackendArgs)"` passed. `bun run tsc --noEmit` passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated launcher-managed X11 fallback mode to force a more compatible mpv renderer stack on Linux: `--vo=gpu`, `--gpu-api=opengl`, and `--gpu-context=x11egl,x11`. This applies both to explicit `--backend=x11` and to unsupported Wayland auto fallback, while supported Hyprland/Sway Wayland sessions still keep their native path. The renderer args are still inserted before user-supplied `--args`, so an explicit user override can win later on the command line if needed.
+
+Adjusted regression coverage to require the full renderer stack for forced-X11 mode and verified the helper behavior with focused launcher tests plus TypeScript compilation. Verification completed with `bun test launcher/mpv.test.ts --test-name-pattern "buildMpv(Env|BackendArgs)"` and `bun run tsc --noEmit`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-284 - Fix-CI-changelog-fragment-requirement-for-launcher-X11-MPV-fallback-change.md

@@ -0,0 +1,32 @@
+---
+id: TASK-284
+title: Fix CI changelog fragment requirement for launcher X11 MPV fallback change
+status: Done
+assignee: []
+created_date: '2026-04-05 22:21'
+updated_date: '2026-04-05 22:22'
+labels:
+  - ci
+  - changelog
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Current CI is failing in `changelog:pr-check` because PR changes release-relevant files but does not include a required entry under `changes/` and lacks `skip-changelog` label. Add a release fragment describing the behavioral change and verify the CI gate passes.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Add a correctly formatted changelog fragment under `changes/` for the current change
+- [x] #2 Run the local changelog PR check (or equivalent) with passing result
+- [x] #3 Run required CI gate commands after change and confirm no regressions
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added `changes/2026.04.05-mpv-x11-fallback.md` with launcher release-note metadata so `changelog:pr-check` can pass. Verified local CI gate commands: `bun run typecheck`, `bun run test:fast`, `bun run test:env`, `bun run build`, `bun run test:smoke:dist` all passed. Ran manual PR changelog verification by invoking `verifyPullRequestChangelog` with current git diff plus the new fragment and confirmed it passes.
+<!-- SECTION:FINAL_SUMMARY:END -->

changes/README.md

@@ -12,10 +12,21 @@ area: overlay
 - Added auto-pause toggle when opening the popup.
 ```
 
+For breaking changes, add `breaking: true`:
+
+```md
+type: changed
+area: config
+breaking: true
+
+- Renamed `foo.bar` to `foo.baz`.
+```
+
 Rules:
 
 - `type` required: `added`, `changed`, `fixed`, `docs`, or `internal`
 - `area` required: short product area like `overlay`, `launcher`, `release`
+- `breaking` optional: set to `true` to flag as a breaking change
 - each non-empty body line becomes a bullet
 - `README.md` is ignored by the generator
 - if a PR should not produce release notes, apply the `skip-changelog` label instead of adding a fragment

changes/stats-dashboard-feedback-pass.md

@@ -0,0 +1,10 @@
+type: changed
+area: stats
+
+- Sessions are rolled up per episode within each day, with a bulk delete that wipes every session in the group.
+- Trends add a 365-day range next to the existing 7d/30d/90d/all options.
+- Library detail view gets a delete-episode action that removes the video and all its sessions.
+- Vocabulary Top 50 tightens the word/reading column so katakana entries no longer push the scores off screen.
+- Episode detail hides card events whose Anki notes have been deleted, instead of showing phantom mining activity.
+- Trend and watch-time charts share a unified theme with horizontal gridlines and larger ticks for legibility.
+- Overview, Library, Trends, Sessions, and Vocabulary now use generic "title" wording so YouTube videos and anime live comfortably side by side in the dashboard.

config.example.jsonc

@@ -461,10 +461,12 @@
   // ==========================================
   // MPV Launcher
   // Optional mpv.exe override for Windows playback entry points.
+  // Set mpv.launchMode to choose normal, maximized, or fullscreen SubMiner-managed mpv playback.
   // Leave mpv.executablePath blank to auto-discover mpv.exe from SUBMINER_MPV_PATH or PATH.
   // ==========================================
   "mpv": {
-    "executablePath": "" // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
+    "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
+    "launchMode": "normal" // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
   }, // Optional mpv.exe override for Windows playback entry points.
 
   // ==========================================

docs-site/.vitepress/config.ts

@@ -76,7 +76,6 @@ export default {
           { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
           { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
           { text: 'Immersion Tracking', link: '/immersion-tracking' },
-          { text: 'JLPT Vocabulary Bundle', link: '/jlpt-vocab-bundle' },
           { text: 'Troubleshooting', link: '/troubleshooting' },
         ],
       },

docs-site/.vitepress/theme/tui-theme.css

@@ -220,6 +220,7 @@ button,
   color: var(--vp-c-brand-1);
   font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
     monospace;
+  font-variant-ligatures: none;
 }
 
 /* === Code blocks === */
@@ -229,6 +230,7 @@ button,
   background: var(--vp-c-bg-alt) !important;
   font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
     monospace;
+  font-variant-ligatures: none;
 }
 
 .vp-doc div[class*='language-']::before {

docs-site/anilist-integration.md

@@ -41,28 +41,6 @@ The update flow:
 3. **Progress check** -- SubMiner fetches your current list entry for the matched media. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
 4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`.
 
-```mermaid
-flowchart TB
-  classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef ext fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  Play["Media Plays"]:::step
-  Detect["Episode Detected"]:::action
-  Queue["Update Queue"]:::action
-  Rate["Rate Limiter"]:::enrich
-  GQL["GraphQL Mutation"]:::ext
-  Done["Progress Updated"]:::result
-
-  Play --> Detect
-  Detect --> Queue
-  Queue --> Rate
-  Rate --> GQL
-  GQL --> Done
-```
-
 ## Update Queue and Retry
 
 Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.

docs-site/anki-integration.md

@@ -250,6 +250,10 @@ The built-in translation request asks for English output by default. Customize t
 
 SubMiner can create standalone sentence cards (without a word/expression) using a separate note type. This is designed for use with [Lapis](https://github.com/donkuri/Lapis) and similar sentence-focused note types.
 
+::: warning Required config
+Sentence card creation and audio card marking both require `ankiConnect.isLapis.enabled: true` and a valid `sentenceCardModel` pointing to your Lapis/Kiku note type. Without this, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
+:::
+
 ```jsonc
 "ankiConnect": {
   "isLapis": {

docs-site/changelog.md

@@ -1,148 +1,364 @@
 # Changelog
 
+## v0.11.2 (2026-04-07)
+
+**Changed**
+- Launcher: Replaced the launcher-only fullscreen toggle with `mpv.launchMode` so SubMiner-managed mpv playback can start in normal, maximized, or fullscreen mode.
+
+**Fixed**
+- Launcher: Fixed launcher-managed mpv spawning to force an explicit X11 GPU path when Wayland trackers are unavailable.
+- Launcher: Local playback now promotes a single unlabeled external subtitle sidecar to the primary slot instead of leaving mpv's embedded English auto-selection in place.
+- Release: Fixed Linux AppImage startup packaging so Chromium child relaunches can resolve the bundled `libffmpeg.so` instead of crash-looping on startup.
+
 ## v0.11.1 (2026-04-04)
 
-- Fixed Linux packaged builds to expose the canonical `SubMiner` app identity to Electron's startup metadata so native Wayland compositors stop reporting the window class/app-id as lowercase `subminer`.
-- Fixed Linux to restore the runtime options, Jimaku, and Subsync shortcuts after the Electron 39 regression by routing those actions through the overlay's mpv/IPC shortcut path.
+**Fixed**
+- Release: Linux packaged builds now expose the canonical `SubMiner` app identity to Electron's startup metadata so native Wayland compositors stop reporting the window class/app-id as lowercase `subminer`.
+- Linux: Linux now restores the runtime options, Jimaku, and Subsync shortcuts after the Electron 39 regression by routing those actions through the overlay's mpv/IPC shortcut path.
 
 ## v0.11.0 (2026-04-03)
 
-- Added a playlist browser overlay modal for browsing sibling video files and the live mpv queue during playback, with a default `Ctrl+Alt+P` keybinding.
-- Made mpv plugin installation mandatory in first-run setup (removed skip path); Finish stays disabled until the plugin is installed.
-- Fixed the Windows `SubMiner mpv` shortcut to launch mpv with required default args directly instead of requiring an `mpv.conf` profile named `subminer`.
-- Fixed the Windows mpv idle launch so loading a video after opening the shortcut keeps mpv in the SubMiner-managed session and auto-starts the overlay.
-- Added a blank-by-default `mpv.executablePath` config override for Windows playback when mpv is not on `PATH`, exposed in first-run setup.
-- Fixed Kiku duplicate grouping to reuse duplicate note IDs from both sentence-card creation and Yomitan popup mining, with background card addition and proper merge-modal sequencing.
-- Fixed configured subtitle-jump keybindings to keep playback paused when invoked from a paused state.
-- Fixed managed local subtitle auto-selection to reuse configured language priorities instead of staying on mpv's initial `sid=auto` guess.
-- Kept tracked macOS visible overlays click-through by default so subtitle sidebar passthrough works immediately.
-- Stopped AniList post-watch from sending duplicate progress updates when already satisfied by a retry item.
-- Kept integrated `--start --texthooker` launches on the full app-ready startup path.
-- Honored `SUBMINER_YTDLP_BIN` consistently across all YouTube flows (playback URL resolution, track probing, subtitle downloads, metadata probing).
-- Added `windows` as a recognized launcher backend option and auto-detection target.
-- Added a dedicated Subtitle Sidebar guide to the docs site with links from homepage and configuration docs.
+**Added**
+- Overlay: Added a playlist browser overlay modal for browsing sibling video files and the live mpv queue during playback.
+- Overlay: Added the default `Ctrl+Alt+P` keybinding to open the playlist browser and manage queue order without leaving playback.
 
-## v0.10.0 (2026-03-29)
+**Changed**
+- Setup: Made mpv plugin installation mandatory in the first-run setup flow, removed the skip path, and kept Finish disabled until the plugin is installed.
+- Setup: Clarified that the mpv plugin requirement applies to setup on every platform, while the optional `SubMiner mpv` shortcut remains the recommended Windows playback entry point.
+- Launcher: Streamlined Windows setup and config by making the `SubMiner mpv` shortcut self-contained and keeping `mpv.executablePath` as the simple fallback when `mpv.exe` is not on `PATH`.
+- Overlay: Changed fresh-install default config to keep texthooker and stats from auto-opening browser tabs.
+- Overlay: Changed fresh-install default config to enable AnkiConnect, Discord Rich Presence, subtitle-sidebar, and Yomitan-popup auto-pause by default, while disabling controller input by default.
 
-- Fixed stats startup so the immersion tracker can run when `Bun.serve` is unavailable.
-- Added a Node `http` fallback for Electron/runtime paths that do not expose Bun, so stats keeps working there too.
-- Updated Discord Rich Presence to the maintained `@xhayper/discord-rpc` wrapper.
-- Fixed the macOS visible-overlay toggle path so manual hides stay hidden and the plugin uses the explicit visible-overlay toggle command.
-- Restored macOS mpv passthrough while the overlay subtitle sidebar is open so clicks outside the sidebar can refocus mpv and keep native keybindings working.
+**Fixed**
+- Main: Resolve the YouTube playback socket path lazily so startup honors CLI and config overrides.
+- Main: Add regression coverage for the lazy socket-path lookup during Windows mpv startup.
+- Main: Keep integrated `--start --texthooker` launches on the full app-ready startup path so the texthooker page and websocket servers start together during normal playback startup.
+- Main: Stop the mpv/plugin auto-start flow from spawning a separate standalone texthooker helper during normal `subminer <video>` launches.
+- Overlay: Keep tracked macOS visible overlays click-through by default so subtitle sidebar passthrough works immediately without requiring a subtitle hover cycle first.
+- Overlay: Add regression coverage for the macOS visible-overlay passthrough default.
+- Anilist: Stop AniList post-watch from sending a second progress update when the current episode was already satisfied by a ready retry item in the same watch-completion pass.
+- Anilist: Add regression coverage for the retry-queue plus live-update duplicate path.
+- Overlay: Fixed Kiku duplicate grouping to reuse duplicate note IDs from both generic sentence-card creation and Yomitan popup mining instead of running extra duplicate scans after add.
+- Overlay: Fixed the Yomitan popup mining flow to add cards in the background while keeping the stock popup progress feedback, then pause playback and close the lookup popup before the Kiku merge modal opens.
+- Overlay: Fixed configured subtitle-jump keybindings so backward and forward subtitle seeks keep playback paused when invoked from a paused state.
+- Launcher: Fixed the Windows `SubMiner mpv` shortcut and `SubMiner.exe --launch-mpv` flow to launch mpv with SubMiner's required default args directly instead of requiring an `mpv.conf` profile named `subminer`.
+- Launcher: Clarified the Windows install and usage docs so the shortcut path is documented as self-contained, while the optional `subminer` mpv profile remains available for manual mpv launches.
+- Launcher: Hardened the first-run setup blocker copy and stale custom-scheme handling so setup messages stay aligned with config, plugin, and dictionary readiness.
+- Launcher: Fixed the Windows `SubMiner mpv` shortcut idle launch so loading a video after opening the shortcut keeps mpv in the expected SubMiner-managed session, auto-starts the overlay, and re-arms subtitle auto-selection for the newly opened file.
+- Launcher: Removed the redundant `.` subtitle search path from the Windows shortcut launch args and deduped repeated subtitle source tracks in the manual sync picker so duplicate external subtitle entries no longer appear from the shortcut path.
+- Playback: Fixed managed local playback so duplicate startup-ready retries no longer unpause media after a later manual pause on the same file.
+- Playback: Fixed managed local subtitle auto-selection so local files reuse configured primary and secondary subtitle language priorities instead of staying on mpv's initial `sid=auto` guess.
+- Launcher: Added a blank-by-default `mpv.executablePath` override for Windows playback so users can point SubMiner at `mpv.exe` when it is not on `PATH`.
+- Launcher: Kept the Windows shortcut and `--launch-mpv` flow simple by preserving PATH auto-discovery as the default and exposing the override in first-run setup.
+- Launcher: Added `windows` as a recognized launcher backend option and auto-detection target on Windows.
+- Launcher: Honored `SUBMINER_YTDLP_BIN` consistently across YouTube playback URL resolution, track probing, subtitle downloads, and metadata probing.
+- Launcher: Kept the first-run setup window from navigating away on unexpected URLs.
+- Launcher: Made Windows mpv honor an explicitly configured executable path instead of silently falling back to PATH.
+- Launcher: Hardened `--launch-mpv` parsing and Windows binary resolution so valueless flags do not swallow media targets and symlinked launcher installs do not short-circuit PATH lookup.
+- Launcher: Fixed first-run setup blocking playback on macOS when the SubMiner mpv plugin was already installed at the canonical `~/.config/mpv` path.
+- Launcher: Fixed setup gating so stale cancelled setup state no longer prevents playback when the canonical mpv plugin entrypoint already exists.
+- Playback: Prevented stale async playlist-browser subtitle rearm callbacks from overriding newer subtitle selections during rapid file changes.
 
-## v0.9.3 (2026-03-25)
+**Docs**
+- Docs Site: Added a dedicated Subtitle Sidebar guide and linked it from the homepage and configuration docs.
+- Docs Site: Linked Jimaku integration from the homepage to its dedicated docs page.
+- Docs Site: Refreshed docs-site theme tokens and hover/selection styling for the updated pages.
 
-- Moved YouTube primary subtitle language defaults to `youtube.primarySubLanguages`.
-- Removed the placeholder YouTube subtitle retime step; downloaded primary subtitle tracks are now used directly.
-- Removed the old internal YouTube retime helper and its tests.
-- Clarified optional `alass` / `ffsubsync` subtitle-sync setup and fallback behavior in the docs.
-- Removed the legacy `youtubeSubgen.primarySubLanguages` config path from generated config and docs.
+**Internal**
+- Release: Retried AUR clone and push operations in the tagged release workflow.
+- Release: Kept GitHub Releases green when AUR publish flakes and needs manual follow-up.
+- Release: Updated Electron to 39.8.6 and pinned patched transitive build dependencies to clear the reported high-severity audit findings.
 
-## v0.9.2 (2026-03-25)
+## Previous Versions
 
-- Fixed overlay pointer tracking so Windows click-through toggles immediately when the cursor enters or leaves subtitle regions.
-- Fixed Windows overlay window tracking on scaled displays by converting native tracked window bounds to Electron DIP coordinates.
-- Fixed Windows direct `--youtube-play` startup so MPV boots reliably, stays paused until the app-owned subtitle flow is ready, and reuses an already-running SubMiner instance.
-- Fixed standalone Windows `--youtube-play` sessions so closing MPV fully exits SubMiner instead of leaving hidden overlay windows behind.
-- Fixed `subminer <youtube-url>` on Linux so the YouTube playback flow waits for Yomitan to load before creating the overlay window.
+<details>
+<summary>v0.10.x</summary>
 
-## v0.9.1 (2026-03-24)
+<h2>v0.10.0 (2026-03-29)</h2>
 
-- Reduced packaged release size by excluding duplicate `extraResources` payload and pruning docs, tests, sourcemaps, and other source-only files from Electron bundles.
-- Restored controller navigation and lookup/mining controls while the subtitle sidebar is open, while keeping true modal dialogs blocking controller actions.
-- Fixed subtitle annotation clearing so explanatory contrast endings like `んですけど` are excluded consistently across the shared tokenizer filter and annotation stage.
+**Changed**
+- Integrations: Replaced the deprecated Discord Rich Presence wrapper with the maintained `@xhayper/discord-rpc` package.
 
-## v0.9.0 (2026-03-23)
+**Fixed**
+- Stats: Fixed stats startup so the immersion tracker can run when `Bun.serve` is unavailable.
+- Stats: Stats server now falls back to a Node `http` listener in Electron/runtime paths that do not expose Bun.
+- Overlay: Fixed the macOS visible-overlay toggle path so manual hides stay hidden and the plugin uses the explicit visible-overlay toggle command.
+- Subtitle Sidebar: Restored macOS mpv passthrough while the overlay subtitle sidebar is open so clicks outside the sidebar can refocus mpv and keep native keybindings working.
 
-- Added an app-owned YouTube subtitle flow with absPlayer-style timedtext parsing that auto-loads the default primary subtitle plus a best-effort secondary at startup and resumes once the primary is ready.
-- Added a manual YouTube subtitle picker on `Ctrl+Alt+C` so subtitle selection can be retried on demand during active YouTube playback.
-- Added yt-dlp metadata probing so YouTube playback and immersion tracking record canonical video title and channel metadata.
-- Disabled conflicting mpv native subtitle auto-selection for the app-owned flow so injected explicit tracks stay authoritative.
-- Added OSD status updates covering YouTube playback startup, subtitle acquisition, and subtitle loading.
-- Stopped forcing `--ytdl-raw-options=` before user-provided mpv options so existing YouTube cookie integrations are preserved.
-- Improved sidebar startup/resume behavior, scroll handling, and overlay/sidebar subtitle synchronization.
-- Stats Library tab now shows YouTube video title, channel name, and thumbnail for YouTube media entries.
-- Added a new WebSocket / Texthooker API integration guide covering payload formats, custom client patterns, and mpv plugin automation.
-- Fixed Anki media mining for mpv YouTube streams so audio and screenshot capture work correctly during YouTube playback sessions.
-- Fixed YouTube media path handling in immersion tracking so YouTube sessions record correct media references and AniList state transitions do not fire for YouTube media.
-- Reused existing authoritative YouTube subtitle tracks when present, fell back only for missing sides, and kept native mpv secondary subtitle rendering hidden so the overlay remains the visible secondary subtitle surface.
+**Internal**
+- Release: Added a maintained source coverage lane that shards Bun coverage one test file at a time and merges LCOV output into `coverage/test-src/lcov.info`.
+- Release: CI and release quality-gate now upload the merged source-lane LCOV artifact for inspection.
+- Runtime: Extracted remaining inline runtime logic from `src/main.ts` into dedicated runtime modules and composer helpers.
+- Runtime: Added focused regression tests for the extracted runtime/composer boundaries.
+- Runtime: Updated task tracking notes to mark TASK-238.6 complete and confirm follow-on boot-phase split can be deferred.
+- Runtime: Split `src/main.ts` boot wiring into dedicated `src/main/boot/services.ts`, `src/main/boot/runtimes.ts`, and `src/main/boot/handlers.ts` modules.
+- Runtime: Added focused tests for the new boot-phase seams and kept the startup/typecheck/build verification lanes green.
+- Runtime: Updated internal architecture/task docs to record the boot-phase split and new ownership boundary.
 
-## v0.8.0 (2026-03-22)
+</details>
 
-- Added a configurable subtitle sidebar feature (`subtitleSidebar`) with overlay/embedded rendering, click-to-seek cue list, and hot-reloadable visibility and behavior controls.
-- Added a rendered sidebar modal with cue list display, click-to-seek, active-cue highlighting, and embedded layout support.
-- Added sidebar snapshot plumbing between main and renderer for overlay/sidebar synchronization.
-- Added sidebar configuration options for visibility and behavior (enabled, layout, toggle key, autoOpen, pauseOnHover, autoScroll) plus typography and sizing controls.
-- Documented `subtitleSidebar` configuration and behavior in user-facing docs (configuration.md, shortcuts.md, config.example.jsonc).
-- Updated subtitle prefetch/rendering flow to keep overlay and sidebar state in sync through media transitions.
-- Kept sidebar cue tracking stable across playback transitions and timing edge cases.
-- Fixed sidebar startup/resume positioning to jump directly to the first resolved active cue.
-- Prevented stale subtitle refreshes from regressing active-cue state.
+<details>
+<summary>v0.9.x</summary>
 
-## v0.7.0 (2026-03-19)
+<h2>v0.9.3 (2026-03-25)</h2>
 
-- Added a full local immersion dashboard release line with Overview, Library, Trends, Vocabulary, and Sessions drill-down views backed by SQLite tracking data.
-- Added browser-first stats workflows: `subminer stats`, background stats daemon controls (`-b` / `-s`), stats cleanup, and dashboard-side mining actions with media enrichment.
-- Improved stats accuracy and scale handling with Yomitan token counts, full session timelines, known-word timeline fixes, cross-media vocabulary fixes, and clearer session charts.
-- Improved overlay/runtime stability with quieter macOS fullscreen recovery, reduced repeated loading OSD popups, and better frequency/noise handling for subtitle annotations.
-- Added launcher mpv-args passthrough plus Linux plugin wrapper-name fallback for packaged installs.
-- Added a hover-revealed ↗ button on Sessions tab rows to navigate directly to the anime media-detail view, with correct "Back to Sessions" back-navigation.
-- Excluded auxiliary-stem `そうだ` grammar tails (MeCab POS3 `助動詞語幹`) from subtitle annotation metadata so frequency, JLPT, and N+1 styling no longer bleed onto grammar-tail tokens.
+**Changed**
+- Launcher: Moved YouTube primary subtitle language defaults to `youtube.primarySubLanguages`.
+- Launcher: Removed the placeholder YouTube subtitle retime step and now uses downloaded primary subtitle tracks directly, so there is no fake path rewrite before playback/sidebar loading.
+- YouTube: Removed the `src/core/services/youtube/retime` helper and its tests after retiring the internal retime strategy.
+- Docs: Clarified optional `alass` / `ffsubsync` subtitle-sync requirements and setup steps, including fallback behavior when sync tools are absent.
+- Launcher: Removed the old `youtubeSubgen.primarySubLanguages` config path from the generated config and docs.
 
-## v0.6.5 (2026-03-15)
+<h2>v0.9.2 (2026-03-25)</h2>
 
-- Seeded the AUR checkout with the repo `.SRCINFO` template before rewriting metadata so tagged releases do not depend on prior AUR state.
+**Fixed**
+- Overlay: Fixed overlay pointer tracking so Windows click-through toggles immediately when the cursor enters or leaves subtitle regions, without waiting for a later hover resync.
+- Overlay: Fixed Windows overlay window tracking on scaled displays by converting native tracked window bounds to Electron DIP coordinates before applying overlay bounds.
+- Launcher: Fixed Windows direct `--youtube-play` startup so MPV boots reliably, stays paused until the app-owned subtitle flow is ready, and reuses an already-running SubMiner instance when available.
+- Launcher: Fixed standalone Windows `--youtube-play` sessions so closing MPV fully exits SubMiner instead of leaving hidden overlay windows or a background process behind.
+- Overlay: Fixed `subminer <youtube-url>` on Linux so the YouTube playback flow waits for Yomitan to load before creating the overlay window, avoiding the broken lookup popup state that previously required a manual overlay refresh.
 
-## v0.6.4 (2026-03-15)
+<h2>v0.9.1 (2026-03-24)</h2>
 
-- Reworked AUR metadata generation to update `.SRCINFO` directly instead of depending on runner `makepkg`, fixing tagged release publishing for `subminer-bin`.
+**Changed**
+- Release: Reduced packaged release size by excluding duplicate `extraResources` payload and pruning docs, tests, sourcemaps, and other source-only files from Electron bundles.
 
-## v0.6.3 (2026-03-15)
+**Fixed**
+- Overlay: Restored controller navigation and lookup/mining controls while the subtitle sidebar is open, while keeping true modal dialogs blocking controller actions.
+- Tokenizer: Fixed subtitle annotation clearing so explanatory contrast endings like `んですけど` are excluded consistently across the shared tokenizer filter and annotation stage.
 
-- Expanded `Alt+C` into an inline controller config/remap flow with preferred-controller saving and per-action learn mode for buttons, triggers, and stick directions.
-- Automated `subminer-bin` AUR package updates from the tagged release workflow.
+<h2>v0.9.0 (2026-03-23)</h2>
 
-## v0.6.2 (2026-03-12)
+**Added**
+- Docs: Added a new WebSocket / Texthooker API and integration guide covering WebSocket payloads, custom client patterns, mpv plugin automation, and webhook-style relay examples. Linked from configuration and mining workflow docs for easier discovery.
 
-- Added `yomitan.externalProfilePath` so SubMiner can reuse another Electron app's Yomitan profile in read-only mode.
-- Reused external Yomitan dictionaries/settings without writing back to that profile.
-- Let launcher-managed playback honor external Yomitan config instead of forcing first-run setup.
-- Seeded `config.jsonc` even when the default config directory already exists.
-- Let first-run setup complete without internal dictionaries while external Yomitan is configured, then require an internal dictionary again only if that external profile is later removed.
+**Changed**
+- Launcher: Added an app-owned YouTube subtitle flow that pauses mpv, uses absPlayer-style YouTube timedtext parsing/conversion to download subtitle tracks, and injects them as external files before playback resumes.
+- Launcher: Changed YouTube subtitle startup to auto-load the best-available primary and secondary subtitle tracks at launch instead of forcing the picker modal first. Secondary subtitle failures no longer block playback resume.
+- Launcher: Added `Ctrl+Alt+C` as the default keybinding to manually open the YouTube subtitle picker during active YouTube playback.
+- Launcher: Added yt-dlp metadata probing so YouTube playback and immersion tracking record canonical video title and channel metadata.
+- Launcher: Stopped forcing `--ytdl-raw-options=` before user-provided mpv options so existing YouTube cookie integrations in user `--args` are no longer clobbered.
+- Launcher: Disabled mpv native YouTube subtitle auto-loading for the app-owned flow so injected external subtitle files remain authoritative.
+- Launcher: Added OSD status messages for YouTube playback startup, subtitle acquisition, and subtitle loading so the flow stays visible before and during the picker.
+- Subtitle Sidebar: Added startup-auto-open controls and resume positioning improvements so the sidebar jumps directly to the first resolved active cue.
+- Subtitle Sidebar: Improved subtitle prefetch and embedded overlay passthrough sync so sidebar and overlay subtitle states stay consistent across media transitions.
+- Subtitle Sidebar: Updated scroll handling, embedded layout styling, and active-cue visual behavior.
+- Stats: Stats Library tab now displays YouTube video title, channel name, and channel thumbnail for YouTube media entries, with retry logic to fill in metadata that arrives after initial load.
 
-## v0.6.1 (2026-03-12)
+**Fixed**
+- Launcher: Fixed Anki media mining for mpv YouTube streams by unwrapping the stream URL so audio and screenshot capture work correctly for YouTube playback sessions.
+- Immersion: Fixed YouTube media path handling in the immersion runtime and tracking so YouTube sessions record correct media references, AniList guessing skips YouTube URLs, and post-watch state transitions do not fire for YouTube media.
+- Launcher: Fixed startup-launched YouTube playback so primary subtitle overlay updates continue after auto-load completes.
+- Launcher: Fixed auto-loaded YouTube primary subtitles so parsed cues appear in the subtitle sidebar without needing a manual picker retry.
+- Launcher: Fixed the YouTube picker to guard against duplicate subtitle submissions and tightened YouTube URL detection so follow-up runtime flows only treat real YouTube hosts as YouTube playback.
+- Launcher: Fixed primary subtitle failure notifications being shown while app-owned YouTube subtitle probing and downloads are still in flight.
+- Launcher: Preserved existing authoritative YouTube subtitle tracks when available; downloaded tracks are used only to fill missing sides, and native mpv secondary subtitle rendering is hidden so the overlay remains the sole secondary display.
 
-- Added Chrome Gamepad API controller support for keyboard-only overlay mode.
-- Added configurable controller bindings for lookup, mining, popup navigation, Yomitan audio, mpv pause, and d-pad fallback navigation.
-- Added smooth, slower popup scrolling for controller navigation.
-- Expanded `Alt+C` into a controller config/remap modal with preferred-controller saving, inline learn mode, and kept `Alt+Shift+C` for raw input debugging.
-- Added a transient in-overlay controller-detected indicator when a controller is first found.
-- Fixed cleanup of stale keyboard-only token highlights when keyboard-only mode is disabled or when the Yomitan popup closes.
-- Added an enforced `verify:config-example` gate so checked-in example config artifacts cannot drift silently.
+</details>
 
-## v0.5.6 (2026-03-10)
+<details>
+<summary>v0.8.x</summary>
 
-- Persisted merged character-dictionary MRU state as soon as a new retained set is built so revisits do not get dropped if later Yomitan import work fails.
-- Fixed early Electron startup writing config and user data under a lowercase `~/.config/subminer` path instead of canonical `~/.config/SubMiner`.
-- Kept JLPT underline colors stable during Yomitan hover and selection states, even when tokens also use known, N+1, name-match, or frequency styling.
+<h2>v0.8.0 (2026-03-22)</h2>
 
-## v0.5.1 (2026-03-09)
+**Added**
+- Overlay: Added the subtitle sidebar feature with a new `subtitleSidebar` configuration surface and rendered sidebar modal with cue list rendering, click-to-seek, active-cue highlighting, and embedded layout support.
+- IPC: Added sidebar snapshot plumbing between renderer and main process for overlay/sidebar synchronization.
 
-- Removed the old YouTube subtitle-generation mode switch; YouTube playback now resolves subtitles before mpv starts.
-- Hardened YouTube AI subtitle fixing so fenced/text-only responses keep original cue timing.
-- Skipped AniSkip during URL/YouTube playback where anime metadata cannot be resolved reliably.
-- Kept the background SubMiner process warm across launcher-managed mpv exits so reconnects do not repeat startup pause/warmup work.
-- Fixed Windows single-instance reuse so overlay and video launches reuse the running background app instead of booting a second full app.
-- Hardened the Windows signing/release workflow with SignPath retry handling for signed `.exe` and `.zip` artifacts.
+**Changed**
+- Config: Added hot-reloadable sidebar options for enablement, layout, visibility, typography, opacity, sizing, and interaction behavior (`autoOpen`, `pauseOnHover`, `autoScroll`, toggle key).
+- Docs: Added full `subtitleSidebar` documentation coverage, including sample config, option table, and toggle shortcut notes.
+- Runtime: Improved subtitle prefetch/rendering flow so sidebar and overlay subtitle states stay in sync across media transitions.
 
-## v0.5.0 (2026-03-08)
+**Fixed**
+- Overlay: Kept sidebar cue tracking stable across playback transitions and timing edge cases.
+- Overlay: Improved sidebar resume/start behavior to jump directly to the first resolved active cue.
+- Overlay: Stopped stale subtitle refreshes from regressing active-cue and text state.
 
-- Added the initial packaged Windows release.
-- Added Windows-native mpv window tracking, launcher/runtime plumbing, and packaged helper assets.
-- Improved close behavior so ending playback hides the visible overlay while the background app stays running.
-- Limited the native overlay outline/debug frame to debug mode on Windows.
+</details>
 
-## v0.3.0 (2026-03-05)
+<details>
+<summary>v0.7.x</summary>
+
+<h2>v0.7.0 (2026-03-19)</h2>
+
+**Added**
+- Immersion: Added Mine Word, Mine Sentence, and Mine Audio buttons to word detail example lines in the stats dashboard.
+- Immersion: Mine Word creates a full Yomitan card (definition, reading, pitch accent) via the hidden search page bridge, then enriches with sentence audio, screenshot, and metadata extracted from the source video.
+- Immersion: Mine Sentence and Mine Audio create cards directly with appropriate Lapis/Kiku flags, sentence highlighting, and media from the source file.
+- Immersion: Media generation (audio + image/AVIF) runs in parallel and respects all AnkiConnect config options.
+- Immersion: Added word exclusion list to the Vocabulary tab with localStorage persistence and a management modal.
+- Immersion: Fixed truncated readings in the frequency rank table (e.g. お前 now shows おまえ instead of まえ).
+- Immersion: Clicking a bar in the Top Repeated Words chart now opens the word detail panel.
+- Immersion: Secondary subtitle text is now stored alongside primary subtitle lines for use as translation when mining cards from the stats page.
+- Stats: Added `subminer stats -b` to start or reuse a dedicated background stats server without blocking normal SubMiner instances.
+- Stats: Added `subminer stats -s` to stop the dedicated background stats server without closing browser tabs.
+- Stats: Stats server startup now reuses a running background stats daemon instead of trying to bind a second local server in another SubMiner instance.
+- Launcher: Added launcher passthrough for `-a/--args` so mpv receives raw extra launch flags (`--fs`, `--ytdl-format`, custom audio/video settings, etc.) from the `subminer` command.
+- Launcher: Added `subminer stats` to launch the local stats dashboard, force-start the stats server on demand, and open the dashboard in your browser.
+- Launcher: Added `subminer stats cleanup` to backfill vocabulary metadata and prune stale or excluded immersion rows on demand.
+- Launcher: Added `stats.autoOpenBrowser` so browser launch after `subminer stats` can be enabled or disabled explicitly.
+- Immersion: Added a local stats dashboard for immersion tracking with Overview, Anime, Trends, Vocabulary, and Sessions views.
+- Immersion: Added anime progress, episode completion, Anki card links, and occurrence drill-down across the stats dashboard.
+- Immersion: Added richer session timelines with new-word activity, cumulative totals, and pause/seek/card event markers.
+- Immersion: Added completed-episodes and completed-anime totals to the Overview tracking snapshot.
+
+**Changed**
+- Anki: Changed known-word cache settings to live under `ankiConnect.knownWords` instead of mixing them into `ankiConnect.nPlusOne`.
+- Anki: Kept legacy `ankiConnect.nPlusOne` known-word keys and older `ankiConnect.behavior.nPlusOne*` keys as deprecated compatibility fallbacks.
+- Stats: Added session deletion to the Sessions tab with the same confirmation prompt used by anime episode/session deletes, and removed all associated session rows from the stats database.
+- Immersion: Kept immersion tracking history by default while preserving daily/monthly rollup maintenance.
+- Immersion: Added exact lifetime summary reads for overview/anime/media stats so dashboard totals no longer depend on rescanning raw telemetry.
+- Immersion: Reduced tracker storage overhead by removing duplicated subtitle text from subtitle-line event payloads.
+- Immersion: Deduplicated episode cover-art blobs through a shared blob store and updated cover-art reads/writes to resolve shared images correctly.
+- Immersion: Added indexes for large-history session, telemetry, vocabulary, kanji, and cover-art queries to keep dashboard reads fast as the SQLite database grows.
+- Immersion: Renamed the stats dashboard's Anime tab to Library so the media browser label matches non-anime sources like YouTube and other yt-dlp-backed content.
+- Anilist: Standardized episode completion threshold by introducing `DEFAULT_MIN_WATCH_RATIO` and using it for both local watched state transitions and AniList post-watch progress updates.
+- Anilist: Episode auto-marking now uses the same threshold as AniList (`85%`), removing divergent completion behavior.
+- Overlay: Excluded interjections and sound-effect tokens from subtitle annotation styling so they no longer inherit misleading lexical highlight treatment while still remaining visible and hoverable as plain subtitle tokens.
+- Overlay: Expanded subtitle annotation noise filtering to also strip annotation metadata from standalone grammar-only helper tokens such as particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, and merged trailing quote-particle forms like `...って` while keeping them tokenized for hover lookup.
+
+**Fixed**
+- Launcher: Fixed mpv Lua plugin binary auto-detection on Linux to also search `/usr/bin/subminer` and `/usr/local/bin/subminer` (lowercase), matching the conventional Unix wrapper name used by packaged installs such as the AUR package.
+- Stats: Fixed the in-app stats overlay so it connects to the configured `stats.serverPort` instead of falling back to the default port.
+- Overlay: Fixed subtitle frequency tagging for merged lookup-backed tokens like `陰に` by falling back to exact surface-form Yomitan frequencies when the normalized headword lookup misses.
+- Overlay: Fixed MeCab merged-token position mapping across line breaks so merged content-plus-particle tokens like `陰に` keep their matched Yomitan frequency instead of inheriting shifted POS tags.
+- Overlay: Fixed grouped frequency parsing in both Yomitan and fallback frequency-dictionary lookups so display values like `118,121` use the leading rank instead of collapsing the rank and occurrence count into `118121`.
+- Overlay: Fixed frequency-rank ingestion to ignore Yomitan dictionaries explicitly marked `occurrence-based`, so raw occurrence counts are no longer treated as subtitle rank values.
+- Overlay: Fixed inflected headword frequency tagging to prefer ranks from the selected Yomitan `termsFind` popup entry itself, ordered by configured dictionary priority, so forms like `潜み` use primary-dictionary ranks like `4073` before falling back to lower-priority raw lemma metadata such as `CC100`.
+- Overlay: Fixed annotation-stage frequency filtering so exact kanji noun tokens like `者` keep their matched rank even when MeCab labels them `名詞/非自立`, instead of dropping the highlight after scan-time frequency lookup succeeds.
+- Anki: Fixed repeated character-dictionary startup work by scheduling auto-sync only from mpv media-path changes instead of also re-triggering it from connection and media-title events for the same title.
+- Overlay: Fixed macOS fullscreen overlay stability by keeping the passive visible overlay from stealing focus, re-raising the overlay window when reasserting its macOS topmost level, and tolerating one transient macOS tracker/helper miss before hiding the overlay.
+- Overlay: Kept subtitle tokenization warmup one-shot for the lifetime of the app so later fullscreen/media churn on macOS does not replay the startup warmup gate after the first file is ready.
+- Overlay: Added a bounded macOS tracker loss-grace window so fullscreen enter/leave transitions do not immediately hide and reload the overlay when the helper briefly loses the mpv window.
+- Overlay: Skipped subtitle/tokenization refresh invalidation on character-dictionary auto-sync completion when the dictionary was already current, preventing startup flash/reload loops on unchanged media.
+- Stats: Fixed session stats so known-word counts track real known-word occurrences without collapsing subtitle-line gaps.
+- Stats: Fixed session word totals in session-facing stats views to prefer token counts when available, preventing known words from exceeding total words in the session chart.
+- Stats: Fixed the stats Vocabulary tab blank-screen regression caused by a hook-order crash after vocabulary data finished loading.
+- Anki: Fixed card-mine OSD feedback so the final mine result stops the Anki spinner first, then shows a single-line `✓`/`x` status without being overwritten by a later spinner tick.
+- Stats: Removed the misleading `New words` series from expanded session charts; session detail now shows only the real total-word and known-word lines.
+- Stats: Restored the cross-anime word table behavior in stats vocabulary surfaces so shared vocabulary entries no longer disappear or merge incorrectly across related media.
+- Stats: `subminer stats -b` now runs as a standalone background stats daemon instead of reusing the main SubMiner app process, so the overlay app can still be launched separately for normal video watching.
+- Stats: Dashboard word mining still works against the background daemon by using a short-lived hidden helper for the Yomitan add-note flow.
+- Stats: Load full session timelines by default in stats session detail views so long sessions preserve complete telemetry history instead of being truncated by a fixed sample limit.
+- Stats: Replaced heuristic stats word counts with Yomitan token counts, so session, media, anime, and trend subtitle totals now come directly from parsed subtitle tokens.
+- Stats: Updated stats UI labels and lookup-rate copy to refer to tokens instead of words where those counts are shown.
+- Overlay: Reduced repeated `Overlay loading...` popups on macOS when fullscreen tracker flaps briefly hide and recover the visible overlay.
+- Stats: Scaled expanded session-detail known-word charts to the session's actual percentage range so small changes no longer render as a nearly flat line.
+- Jlpt: Reduced JLPT dictionary startup log noise by summarizing duplicate surface-form collisions instead of logging one line per duplicate entry.
+
+</details>
+
+<details>
+<summary>v0.6.x</summary>
+
+<h2>v0.6.5 (2026-03-15)</h2>
+
+**Internal**
+- Release: Seed the AUR checkout with the repo `.SRCINFO` template before rewriting metadata so tagged releases do not depend on prior AUR state.
+
+<h2>v0.6.4 (2026-03-15)</h2>
+
+**Internal**
+- Release: Reworked AUR metadata generation to update `.SRCINFO` directly instead of depending on runner `makepkg`, fixing tagged release publishing for `subminer-bin`.
+
+<h2>v0.6.3 (2026-03-15)</h2>
+
+**Changed**
+- Overlay: Expanded the `Alt+C` controller modal into an inline config/remap flow with preferred-controller saving and per-action learn mode for buttons, triggers, and stick directions.
+
+**Internal**
+- Workflow: Hardened the `subminer-scrum-master` skill to explicitly answer whether docs updates and changelog fragments are required before handoff.
+- Release: Automate `subminer-bin` AUR package updates from the tagged release workflow.
+
+<h2>v0.6.2 (2026-03-12)</h2>
+
+**Changed**
+- Config: Added `yomitan.externalProfilePath` to reuse another Electron app's Yomitan profile in read-only mode.
+- Config: SubMiner now reuses external Yomitan dictionaries/settings without writing back to that profile.
+- Config: Launcher-managed playback now respects `yomitan.externalProfilePath` and no longer forces first-run setup when external Yomitan is configured.
+- Config: SubMiner now seeds `config.jsonc` even when the default config directory already exists.
+- Config: First-run setup now allows zero internal dictionaries when `yomitan.externalProfilePath` is configured, and falls back to requiring at least one internal dictionary if that external profile is later removed.
+
+<h2>v0.6.1 (2026-03-12)</h2>
+
+**Added**
+- Overlay: Added Chrome Gamepad API controller support for keyboard-only overlay mode, including configurable logical bindings for lookup, mining, popup navigation, Yomitan audio, mpv pause, d-pad fallback navigation, and slower smooth popup scrolling.
+- Overlay: Added `Alt+C` controller selection and `Alt+Shift+C` controller debug modals, with preferred controller persistence and live raw input inspection.
+- Overlay: Added a transient in-overlay controller-detected indicator when a controller is first found.
+- Overlay: Fixed stale keyboard-only token highlight cleanup when keyboard-only mode turns off or the Yomitan popup closes.
+
+**Docs**
+- Install: Added Arch Linux AUR install docs for `subminer-bin` in the README and installation guide.
+
+**Internal**
+- Config: add an enforced `verify:config-example` gate so checked-in example config artifacts cannot drift silently
+- Release: Fixed the release workflow token permissions so tagged builds can download `oven-sh/setup-bun` and publish artifacts again.
+
+</details>
+
+<details>
+<summary>v0.5.x</summary>
+
+<h2>v0.5.6 (2026-03-10)</h2>
+
+**Fixed**
+
+- Dictionary: Persist merged character-dictionary MRU state as soon as a new retained set is built so revisits do not get dropped if later Yomitan import work fails, and skip merged dictionary rebuilds for reorder-only revisits when the retained anime set itself has not changed.
+- Startup: Fixed early Electron startup writing config and user data under a lowercase `~/.config/subminer` path instead of the canonical `~/.config/SubMiner` directory.
+- Overlay: Kept JLPT underline colors stable during Yomitan hover and selection states, even when tokens also use known, N+1, name-match, or frequency styling.
+
+<h2>v0.5.5 (2026-03-09)</h2>
+
+**Changed**
+
+- Overlay: Added `f` as the default overlay fullscreen toggle and changed the default AniSkip intro-jump key to `Tab`.
+- Dictionary: Aligned AniList character dictionary generation more closely with the upstream reference by preserving duplicate shared names across characters, skipping characters without native Japanese names, restoring richer character info fields, and using upstream-style role mapping plus hint-aware kanji readings.
+- Startup: Ordered startup OSD messages so tokenization loads first, annotation loading appears next if still pending, and character dictionary sync progress waits until annotation loading finishes.
+- Dictionary: Added a visible startup OSD step for merged character-dictionary building so long rebuilds show progress before the later import/upload phase.
+
+**Fixed**
+
+- Dictionary: Fixed AniList media guessing for character dictionary auto-sync by using filename-only `guessit` input and preserving multi-part guessit titles instead of truncating them to the first segment.
+- Dictionary: Refresh the current subtitle after character dictionary auto-sync completes so newly imported character names highlight on the active line instead of waiting for the next subtitle change.
+- Dictionary: Show character dictionary auto-sync progress on the mpv OSD without sending desktop notifications.
+- Dictionary: Keep character dictionary auto-sync non-blocking during startup by letting snapshot/build work run in parallel and delaying only the Yomitan import/settings phase until current-media tokenization is already ready.
+- Overlay: Fixed visible overlay keyboard handling so pressing `Tab` still reaches mpv and triggers the default AniSkip skip-intro binding while the overlay has focus.
+- Plugin: Fix Windows mpv plugin binary override lookup so `SUBMINER_BINARY_PATH` still resolves to `SubMiner.exe` when no AppImage override is set.
+
+<h2>v0.5.3 (2026-03-09)</h2>
+
+**Changed**
+
+- Release: Publish unsigned Windows `.exe` and `.zip` artifacts directly from release CI instead of routing them through SignPath.
+- Release: Added `bun run build:win:unsigned` for explicit local unsigned Windows packaging.
+
+<h2>v0.5.2 (2026-03-09)</h2>
+
+**Internal**
+
+- Release: Pinned the Windows SignPath submission workflow to an explicit artifact-configuration slug instead of relying on the SignPath project's default configuration.
+
+<h2>v0.5.1 (2026-03-09)</h2>
+
+**Changed**
+
+- Launcher: Removed the YouTube subtitle generation mode switch so YouTube playback always preloads subtitles before mpv starts.
+
+**Fixed**
+
+- Launcher: Hardened YouTube AI subtitle fixing so fenced SRT output and text-only one-cue-per-block responses can still be applied without losing original cue timing.
+- Launcher: Skipped AniSkip lookup during URL playback and YouTube subtitle-preload playback, limiting AniSkip to local file targets where it can actually resolve anime metadata.
+- Launcher: Keep the background SubMiner process running after a launcher-managed mpv session exits so the next mpv instance can reconnect without restarting the app.
+- Launcher: Reuse prior tokenization readiness after the background app is already warm so reopening a video does not pause again waiting for duplicate warmup completion.
+- Windows: Acquire the app single-instance lock earlier so Windows overlay/video launches reuse the running background SubMiner process instead of booting a second full app and repeating startup warmups.
+
+</details>
+
+<details>
+<summary>v0.3.x</summary>
+
+<h2>v0.3.0 (2026-03-05)</h2>
 
 - Added keyboard-driven Yomitan navigation and popup controls, including optional auto-pause.
 - Added subtitle/jump keyboard handling fixes for smoother subtitle playback control.
@@ -153,7 +369,12 @@
 - Added release build quality-of-life for CLI publish (`gh`-based clobber upload).
 - Removed docs Plausible integration and cleaned associated tracker settings.
 
-## v0.2.3 (2026-03-02)
+</details>
+
+<details>
+<summary>v0.2.x</summary>
+
+<h2>v0.2.3 (2026-03-02)</h2>
 
 - Added performance and tokenization optimizations (faster warmup, persistent MeCab usage, reduced enrichment lookups).
 - Added subtitle controls for no-jump delay shifts.
@@ -162,38 +383,45 @@
 - Fixed Jellyfin remote resume behavior and improved autoplay/tokenization interaction.
 - Updated startup flow to load dictionaries asynchronously and unblock first tokenization sooner.
 
-## v0.2.2 (2026-03-01)
+<h2>v0.2.2 (2026-03-01)</h2>
 
 - Improved subtitle highlighting reliability for frequency modes.
 - Fixed Jellyfin misc info formatting cleanup.
 - Version bump maintenance for 0.2.2.
 
-## v0.2.1 (2026-03-01)
+<h2>v0.2.1 (2026-03-01)</h2>
 
 - Delivered Jellyfin and Subsync fixes from release patch cycle.
 - Version bump maintenance for 0.2.1.
 
-## v0.2.0 (2026-03-01)
+<h2>v0.2.0 (2026-03-01)</h2>
 
 - Added task-related release work for the overlay 2.0 cycle.
 - Introduced Overlay 2.0.
 - Improved release automation reliability.
 
-## v0.1.2 (2026-02-24)
+</details>
+
+<details>
+<summary>v0.1.x</summary>
+
+<h2>v0.1.2 (2026-02-24)</h2>
 
 - Added encrypted AniList token handling and default GNOME keyring support.
 - Added launcher passthrough for password-store flows (Jellyfin path).
 - Updated docs for auth and integration behavior.
 - Version bump maintenance for 0.1.2.
 
-## v0.1.1 (2026-02-23)
+<h2>v0.1.1 (2026-02-23)</h2>
 
 - Fixed overlay modal focus handling (`grab input`) behavior.
 - Version bump maintenance for 0.1.1.
 
-## v0.1.0 (2026-02-23)
+<h2>v0.1.0 (2026-02-23)</h2>
 
 - Bootstrapped Electron runtime, services, and composition model.
 - Added runtime asset packaging and dependency vendoring.
 - Added project docs baseline, setup guides, architecture notes, and submodule/runtime assets.
 - Added CI release job dependency ordering fixes before launcher build.
+
+</details>

docs-site/character-dictionary.md

@@ -4,23 +4,6 @@ SubMiner can build a Yomitan-compatible character dictionary from AniList metada
 
 The dictionary is generated per-media, merged across your recently-watched titles, and auto-imported into Yomitan. When a character name appears in a subtitle line, it gets highlighted and becomes available for hover-driven Yomitan profile lookup.
 
-## Stats Dashboard
-
-The character dictionary and stats dashboard both read from the same local immersion data.
-
-- Open the dashboard from overlay: press your configured `stats.toggleKey` (default: `` ` `` / `Backquote`).
-- Open from launcher/CLI: run `subminer stats`.
-- Open directly: visit `http://127.0.0.1:<stats.serverPort>` when the local server is running.
-
-Useful config keys:
-
-- `stats.autoStartServer` — start the local stats server automatically once immersion tracking starts.
-- `stats.serverPort` — local HTTP port for dashboard and API.
-- `stats.toggleKey` — key binding for overlay dashboard toggle.
-- `stats.autoOpenBrowser` — auto-open dashboard browser for `subminer stats`.
-
-The dashboard gives quick visibility into episode summaries, watch-time rollups, session timelines, and vocabulary/kanji drill-down from the same DB used by character matching.
-
 ## How It Works
 
 The feature has three stages: **snapshot**, **merge**, and **match**.
@@ -31,30 +14,6 @@ The feature has three stages: **snapshot**, **merge**, and **match**.
 
 3. **Match** — During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. Tokens that match a character entry are flagged with `isNameMatch` and highlighted in the overlay with a distinct color.
 
-```mermaid
-flowchart TB
-  classDef api fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef store fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef build fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef dict fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef render fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  AL["AniList API"]:::api
-  Snap["Snapshot JSON"]:::store
-  Merge["Merge"]:::build
-  ZIP["Yomitan ZIP"]:::dict
-  Yomi["Yomitan Import"]:::dict
-  Sub["Subtitle Scan"]:::render
-  HL["Name Highlight"]:::render
-
-  AL -->|"GraphQL"| Snap
-  Snap --> Merge
-  Merge --> ZIP
-  ZIP --> Yomi
-  Yomi --> Sub
-  Sub --> HL
-```
-
 ## Enabling the Feature
 
 Character dictionary sync is disabled by default. To turn it on:

docs-site/configuration.md

@@ -127,6 +127,7 @@ The configuration file includes several main sections:
 - [**Discord Rich Presence**](#discord-rich-presence) - Optional Discord activity card updates
 - [**Immersion Tracking**](#immersion-tracking) - Track subtitle sessions and mining activity in SQLite
 - [**Stats Dashboard**](#stats-dashboard) - Local dashboard and overlay for immersion progress
+- [**MPV Launcher**](#mpv-launcher) - mpv executable path and window launch mode
 - [**YouTube Playback Settings**](#youtube-playback-settings) - Defaults for YouTube subtitle loading
 
 ## Core Settings
@@ -237,10 +238,10 @@ This stream includes subtitle text plus token metadata (N+1, known-word, frequen
 }
 ```
 
-| Option    | Values             | Description                                              |
-| --------- | ------------------ | -------------------------------------------------------- |
-| `enabled` | `true`, `false`    | Toggle annotated websocket stream (independent of `websocket`) |
-| `port`    | number             | Annotation websocket port (default: 6678)                 |
+| Option    | Values          | Description                                                    |
+| --------- | --------------- | -------------------------------------------------------------- |
+| `enabled` | `true`, `false` | Toggle annotated websocket stream (independent of `websocket`) |
+| `port`    | number          | Annotation websocket port (default: 6678)                      |
 
 ### Texthooker
 
@@ -257,10 +258,10 @@ See `config.example.jsonc` for detailed configuration options.
 }
 ```
 
-| Option           | Values          | Description                                                                                      |
-| ---------------- | --------------- | ------------------------------------------------------------------------------------------------ |
-| `launchAtStartup`| `true`, `false` | Start texthooker automatically with SubMiner startup (default: `true`)                            |
-| `openBrowser`    | `true`, `false` | Open browser tab when texthooker starts (default: `false`)                                         |
+| Option            | Values          | Description                                                            |
+| ----------------- | --------------- | ---------------------------------------------------------------------- |
+| `launchAtStartup` | `true`, `false` | Start texthooker automatically with SubMiner startup (default: `true`) |
+| `openBrowser`     | `true`, `false` | Open browser tab when texthooker starts (default: `false`)             |
 
 ## Subtitle Display
 
@@ -324,8 +325,6 @@ See `config.example.jsonc` for detailed configuration options.
 | `jlptColors`                       | object      | JLPT level underline colors object (`N1`..`N5`)                                                                            |
 | `secondary`                        | object      | Override any of the above for secondary subtitles (optional)                                                               |
 
-JLPT underlining is powered by offline term-meta bank files at runtime. See [`docs/jlpt-vocab-bundle.md`](jlpt-vocab-bundle.md) for required files, source/version refresh steps, and deterministic fallback behavior.
-
 Frequency dictionary highlighting uses the same dictionary file format as JLPT bundle lookups (`term_meta_bank_*.json` under discovered dictionary directories). A token is highlighted when it has a positive integer `frequencyRank` (lower is more common) and the rank is within `topX`.
 
 Lookup behavior:
@@ -367,24 +366,24 @@ Configure the parsed-subtitle sidebar modal.
 }
 ```
 
-| Option                      | Values           | Description                                                                      |
-| --------------------------- | ---------------- | -------------------------------------------------------------------------------- |
-| `enabled`                   | boolean          | Enable subtitle sidebar support (`true` by default)                              |
-| `autoOpen`                  | boolean          | Open sidebar automatically on overlay startup (`false` by default)                |
-| `layout`                    | string           | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space to mimic browser-like layout |
-| `toggleKey`                 | string           | `KeyboardEvent.code` used to open/close the sidebar (default: `"Backslash"`)     |
-| `pauseVideoOnHover`         | boolean          | Pause playback while hovering the sidebar cue list                               |
-| `autoScroll`                | boolean          | Keep the active cue in view while playback advances                              |
-| `maxWidth`                  | number           | Maximum sidebar width in CSS pixels (default: `420`)                             |
-| `opacity`                   | number           | Sidebar opacity between `0` and `1` (default: `0.95`)                            |
-| `backgroundColor`           | string           | Sidebar shell background color                                                   |
-| `textColor`                 | hex color        | Default cue text color                                                           |
-| `fontFamily`                | string           | CSS `font-family` value applied to sidebar cue text                             |
-| `fontSize`                  | number           | Base sidebar cue font size in CSS pixels (default: `16`)                        |
-| `timestampColor`            | hex color        | Cue timestamp color                                                              |
-| `activeLineColor`           | hex color        | Active cue text color                                                            |
-| `activeLineBackgroundColor` | string           | Active cue background color                                                      |
-| `hoverLineBackgroundColor`  | string           | Hovered cue background color                                                     |
+| Option                      | Values    | Description                                                                                             |
+| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
+| `enabled`                   | boolean   | Enable subtitle sidebar support (`true` by default)                                                     |
+| `autoOpen`                  | boolean   | Open sidebar automatically on overlay startup (`false` by default)                                      |
+| `layout`                    | string    | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space to mimic browser-like layout |
+| `toggleKey`                 | string    | `KeyboardEvent.code` used to open/close the sidebar (default: `"Backslash"`)                            |
+| `pauseVideoOnHover`         | boolean   | Pause playback while hovering the sidebar cue list                                                      |
+| `autoScroll`                | boolean   | Keep the active cue in view while playback advances                                                     |
+| `maxWidth`                  | number    | Maximum sidebar width in CSS pixels (default: `420`)                                                    |
+| `opacity`                   | number    | Sidebar opacity between `0` and `1` (default: `0.95`)                                                   |
+| `backgroundColor`           | string    | Sidebar shell background color                                                                          |
+| `textColor`                 | hex color | Default cue text color                                                                                  |
+| `fontFamily`                | string    | CSS `font-family` value applied to sidebar cue text                                                     |
+| `fontSize`                  | number    | Base sidebar cue font size in CSS pixels (default: `16`)                                                |
+| `timestampColor`            | hex color | Cue timestamp color                                                                                     |
+| `activeLineColor`           | hex color | Active cue text color                                                                                   |
+| `activeLineBackgroundColor` | string    | Active cue background color                                                                             |
+| `hoverLineBackgroundColor`  | string    | Hovered cue background color                                                                            |
 
 The sidebar is only available when the active subtitle source has been parsed into a cue list. Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like an opaque settings dialog.
 
@@ -468,25 +467,25 @@ See `config.example.jsonc` for detailed configuration options and more examples.
 
 **Default keybindings:**
 
-| Key                  | Command                      | Description                           |
-| -------------------- | ---------------------------- | ------------------------------------- |
-| `Space`              | `["cycle", "pause"]`         | Toggle pause                          |
-| `KeyJ`               | `["cycle", "sid"]`           | Cycle primary subtitle track          |
-| `Shift+KeyJ`         | `["cycle", "secondary-sid"]` | Cycle secondary subtitle track        |
-| `Ctrl+Alt+KeyP`      | `["__playlist-browser-open"]` | Open playlist browser                 |
-| `Ctrl+Alt+KeyC`    | `["__youtube-picker-open"]`     | Open the manual YouTube subtitle picker |
-| `ArrowRight`         | `["seek", 5]`                | Seek forward 5 seconds                |
-| `ArrowLeft`          | `["seek", -5]`               | Seek backward 5 seconds               |
-| `ArrowUp`            | `["seek", 60]`               | Seek forward 60 seconds               |
-| `ArrowDown`          | `["seek", -60]`              | Seek backward 60 seconds              |
-| `Shift+KeyH`         | `["sub-seek", -1]`           | Jump to previous subtitle             |
-| `Shift+KeyL`         | `["sub-seek", 1]`            | Jump to next subtitle                 |
-| `Shift+BracketLeft`  | `["__sub-delay-prev-line"]`  | Shift subtitle delay to previous cue  |
-| `Shift+BracketRight` | `["__sub-delay-next-line"]`  | Shift subtitle delay to next cue      |
-| `Ctrl+Shift+KeyH`    | `["__replay-subtitle"]`      | Replay current subtitle, pause at end |
-| `Ctrl+Shift+KeyL`    | `["__play-next-subtitle"]`   | Play next subtitle, pause at end      |
-| `KeyQ`               | `["quit"]`                   | Quit mpv                              |
-| `Ctrl+KeyW`          | `["quit"]`                   | Quit mpv                              |
+| Key                  | Command                       | Description                             |
+| -------------------- | ----------------------------- | --------------------------------------- |
+| `Space`              | `["cycle", "pause"]`          | Toggle pause                            |
+| `KeyJ`               | `["cycle", "sid"]`            | Cycle primary subtitle track            |
+| `Shift+KeyJ`         | `["cycle", "secondary-sid"]`  | Cycle secondary subtitle track          |
+| `Ctrl+Alt+KeyP`      | `["__playlist-browser-open"]` | Open playlist browser                   |
+| `Ctrl+Alt+KeyC`      | `["__youtube-picker-open"]`   | Open the manual YouTube subtitle picker |
+| `ArrowRight`         | `["seek", 5]`                 | Seek forward 5 seconds                  |
+| `ArrowLeft`          | `["seek", -5]`                | Seek backward 5 seconds                 |
+| `ArrowUp`            | `["seek", 60]`                | Seek forward 60 seconds                 |
+| `ArrowDown`          | `["seek", -60]`               | Seek backward 60 seconds                |
+| `Shift+KeyH`         | `["sub-seek", -1]`            | Jump to previous subtitle               |
+| `Shift+KeyL`         | `["sub-seek", 1]`             | Jump to next subtitle                   |
+| `Shift+BracketLeft`  | `["__sub-delay-prev-line"]`   | Shift subtitle delay to previous cue    |
+| `Shift+BracketRight` | `["__sub-delay-next-line"]`   | Shift subtitle delay to next cue        |
+| `Ctrl+Shift+KeyH`    | `["__replay-subtitle"]`       | Replay current subtitle, pause at end   |
+| `Ctrl+Shift+KeyL`    | `["__play-next-subtitle"]`    | Play next subtitle, pause at end        |
+| `KeyQ`               | `["quit"]`                    | Quit mpv                                |
+| `Ctrl+KeyW`          | `["quit"]`                    | Quit mpv                                |
 
 **Custom keybindings example:**
 
@@ -606,7 +605,7 @@ Important behavior:
       "leftStickPress": 9,
       "rightStickPress": 10,
       "leftTrigger": 6,
-      "rightTrigger": 7
+      "rightTrigger": 7,
     },
     "bindings": {
       "toggleLookup": { "kind": "button", "buttonIndex": 0 },
@@ -621,9 +620,9 @@ Important behavior:
       "leftStickHorizontal": { "kind": "axis", "axisIndex": 0, "dpadFallback": "horizontal" },
       "leftStickVertical": { "kind": "axis", "axisIndex": 1, "dpadFallback": "vertical" },
       "rightStickHorizontal": { "kind": "axis", "axisIndex": 3, "dpadFallback": "none" },
-      "rightStickVertical": { "kind": "axis", "axisIndex": 4, "dpadFallback": "none" }
-    }
-  }
+      "rightStickVertical": { "kind": "axis", "axisIndex": 4, "dpadFallback": "none" },
+    },
+  },
 }
 ```
 
@@ -651,9 +650,9 @@ If you bind a discrete action to an axis manually, include `direction`:
 {
   "controller": {
     "bindings": {
-      "toggleLookup": { "kind": "axis", "axisIndex": 5, "direction": "positive" }
-    }
-  }
+      "toggleLookup": { "kind": "axis", "axisIndex": 5, "direction": "positive" },
+    },
+  },
 }
 ```
 
@@ -760,15 +759,15 @@ Anki reads this provider directly. Legacy subtitle fallback keeps the same provi
 }
 ```
 
-| Option             | Values                | Description                                          |
-| ------------------ | --------------------- | ---------------------------------------------------- |
-| `enabled`          | `true`, `false`       | Enable shared AI provider features                   |
-| `apiKey`           | string                | Static API key for the shared provider               |
-| `apiKeyCommand`    | string                | Shell command used to resolve the API key            |
-| `baseUrl`          | string (URL)          | OpenAI-compatible base URL                           |
-| `model`            | string                | Optional model override for shared provider workflows   |
-| `systemPrompt`     | string                | Optional system prompt override for shared provider workflows |
-| `requestTimeoutMs` | integer milliseconds  | Shared request timeout (default: `15000`)            |
+| Option             | Values               | Description                                                   |
+| ------------------ | -------------------- | ------------------------------------------------------------- |
+| `enabled`          | `true`, `false`      | Enable shared AI provider features                            |
+| `apiKey`           | string               | Static API key for the shared provider                        |
+| `apiKeyCommand`    | string               | Shell command used to resolve the API key                     |
+| `baseUrl`          | string (URL)         | OpenAI-compatible base URL                                    |
+| `model`            | string               | Optional model override for shared provider workflows         |
+| `systemPrompt`     | string               | Optional system prompt override for shared provider workflows |
+| `requestTimeoutMs` | integer milliseconds | Shared request timeout (default: `15000`)                     |
 
 SubMiner uses the shared provider for:
 
@@ -846,59 +845,59 @@ This example is intentionally compact. The option table below documents availabl
 
 **Requirements:** [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin must be installed and running in Anki. ffmpeg must be installed for media generation.
 
-| Option                                  | Values                                  | Description                                                                                                                                   |
-| --------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`                               | `true`, `false`                         | Enable AnkiConnect integration (default: `true`)                                                                                              |
-| `url`                                   | string (URL)                            | AnkiConnect API URL (default: `http://127.0.0.1:8765`)                                                                                        |
-| `pollingRate`                           | number (ms)                             | How often to check for new cards in polling mode (default: `3000`; ignored for direct proxy `addNote`/`addNotes` updates)                     |
-| `proxy.enabled`                         | `true`, `false`                         | Enable local AnkiConnect-compatible proxy for push-based auto-enrichment (default: `true`)                                                    |
-| `proxy.host`                            | string                                  | Bind host for local AnkiConnect proxy (default: `127.0.0.1`)                                                                                  |
-| `proxy.port`                            | number                                  | Bind port for local AnkiConnect proxy (default: `8766`)                                                                                       |
-| `proxy.upstreamUrl`                     | string (URL)                            | Upstream AnkiConnect URL that proxy forwards to (default: `http://127.0.0.1:8765`)                                                            |
-| `tags`                                  | array of strings                        | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                 |
-| `ankiConnect.deck`                      | string                                  | Legacy Anki polling/compatibility scope. Newer known-word cache scoping should use `ankiConnect.knownWords.decks`.                               |
-| `ankiConnect.knownWords.decks`          | object                                  | Deck→fields mapping for known-word cache queries (for example `{ "Kaishi 1.5k": ["Word", "Word Reading"] }`).                                  |
-| `fields.word`                           | string                                  | Card field for mined word / expression text (default: `Expression`)                                                                            |
-| `fields.audio`                          | string                                  | Card field for audio files (default: `ExpressionAudio`)                                                                                       |
-| `fields.image`                          | string                                  | Card field for images (default: `Picture`)                                                                                                    |
-| `fields.sentence`                       | string                                  | Card field for sentences (default: `Sentence`)                                                                                                |
-| `fields.miscInfo`                       | string                                  | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                     |
-| `fields.translation`                    | string                                  | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                 |
-| `ankiConnect.ai.enabled`                | `true`, `false`                         | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                |
-| `ankiConnect.ai.model`                  | string                                  | Optional model override for Anki AI translation/enrichment flows.                                                                              |
-| `ankiConnect.ai.systemPrompt`           | string                                  | Optional system prompt override for Anki AI translation/enrichment flows.                                                                      |
-| `media.generateAudio`                   | `true`, `false`                         | Generate audio clips from video (default: `true`)                                                                                             |
-| `media.generateImage`                   | `true`, `false`                         | Generate image/animation screenshots (default: `true`)                                                                                        |
-| `media.imageType`                       | `"static"`, `"avif"`                    | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                          |
-| `media.imageFormat`                     | `"jpg"`, `"png"`, `"webp"`              | Image format (default: `"jpg"`)                                                                                                               |
-| `media.imageQuality`                    | number (1-100)                          | Image quality for JPG/WebP; PNG ignores this (default: `92`)                                                                                  |
-| `media.imageMaxWidth`                   | number (px)                             | Optional max width for static screenshots. Unset keeps source width.                                                                          |
-| `media.imageMaxHeight`                  | number (px)                             | Optional max height for static screenshots. Unset keeps source height.                                                                        |
-| `media.animatedFps`                     | number (1-60)                           | FPS for animated AVIF (default: `10`)                                                                                                         |
-| `media.animatedMaxWidth`                | number (px)                             | Max width for animated AVIF (default: `640`)                                                                                                  |
-| `media.animatedMaxHeight`               | number (px)                             | Optional max height for animated AVIF. Unset keeps source aspect-constrained height.                                                          |
-| `media.animatedCrf`                     | number (0-63)                           | CRF quality for AVIF; lower = higher quality (default: `35`)                                                                                  |
-| `media.syncAnimatedImageToWordAudio`    | `true`, `false`                         | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`). |
-| `media.audioPadding`                    | number (seconds)                        | Padding around audio clip timing (default: `0.5`)                                                                                             |
-| `media.fallbackDuration`                | number (seconds)                        | Default duration if timing unavailable (default: `3.0`)                                                                                       |
-| `media.maxMediaDuration`                | number (seconds)                        | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                         |
-| `behavior.overwriteAudio`               | `true`, `false`                         | Replace existing audio on updates; when `false`, new audio is appended/prepended per `behavior.mediaInsertMode` (default: `true`)             |
-| `behavior.overwriteImage`               | `true`, `false`                         | Replace existing images on updates; when `false`, new images are appended/prepended per `behavior.mediaInsertMode` (default: `true`)          |
-| `behavior.mediaInsertMode`              | `"append"`, `"prepend"`                 | Where to insert new media when overwrite is off (default: `"append"`)                                                                         |
-| `behavior.highlightWord`                | `true`, `false`                         | Highlight the word in sentence context (default: `true`)                                                                                      |
-| `ankiConnect.knownWords.highlightEnabled` | `true`, `false`                       | Enable fast local highlighting for words already known in Anki (default: `false`)                                                             |
-| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`, `false`                         | Add words from successful mines into the local known-word cache immediately (default: `true`)                                                   |
-| `ankiConnect.knownWords.color`          | hex color string                        | Text color for tokens already found in the local known-word cache (default: `"#a6da95"`).                                                     |
-| `ankiConnect.knownWords.matchMode`      | `"headword"`, `"surface"`               | Matching strategy for known-word highlighting (default: `"headword"`). `headword` uses token headwords; `surface` uses visible subtitle text. |
-| `ankiConnect.knownWords.refreshMinutes` | number                                  | Minutes between known-word cache refreshes (default: `1440`)                                                                                  |
-| `ankiConnect.knownWords.decks`          | object                                  | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word", "Word Reading"] }`).                              |
-| `ankiConnect.nPlusOne.nPlusOne`         | hex color string                        | Text color for the single target token to study when exactly one unknown candidate exists in a sentence (default: `"#c6a0f6"`).               |
-| `ankiConnect.nPlusOne.minSentenceWords` | number                                  | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                        |
-| `behavior.notificationType`             | `"osd"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"osd"`)                                                                                           |
-| `behavior.autoUpdateNewCards`           | `true`, `false`                         | Automatically update cards on creation (default: `true`)                                                                                      |
-| `metadata.pattern`                      | string                                  | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time                                                                      |
-| `isLapis`                               | object                                  | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.  |
-| `isKiku`                                | object                                  | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)     |
+| Option                                            | Values                                  | Description                                                                                                                                   |
+| ------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`                                         | `true`, `false`                         | Enable AnkiConnect integration (default: `true`)                                                                                              |
+| `url`                                             | string (URL)                            | AnkiConnect API URL (default: `http://127.0.0.1:8765`)                                                                                        |
+| `pollingRate`                                     | number (ms)                             | How often to check for new cards in polling mode (default: `3000`; ignored for direct proxy `addNote`/`addNotes` updates)                     |
+| `proxy.enabled`                                   | `true`, `false`                         | Enable local AnkiConnect-compatible proxy for push-based auto-enrichment (default: `true`)                                                    |
+| `proxy.host`                                      | string                                  | Bind host for local AnkiConnect proxy (default: `127.0.0.1`)                                                                                  |
+| `proxy.port`                                      | number                                  | Bind port for local AnkiConnect proxy (default: `8766`)                                                                                       |
+| `proxy.upstreamUrl`                               | string (URL)                            | Upstream AnkiConnect URL that proxy forwards to (default: `http://127.0.0.1:8765`)                                                            |
+| `tags`                                            | array of strings                        | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                 |
+| `ankiConnect.deck`                                | string                                  | Legacy Anki polling/compatibility scope. Newer known-word cache scoping should use `ankiConnect.knownWords.decks`.                            |
+| `ankiConnect.knownWords.decks`                    | object                                  | Deck→fields mapping for known-word cache queries (for example `{ "Kaishi 1.5k": ["Word", "Word Reading"] }`).                                 |
+| `fields.word`                                     | string                                  | Card field for mined word / expression text (default: `Expression`)                                                                           |
+| `fields.audio`                                    | string                                  | Card field for audio files (default: `ExpressionAudio`)                                                                                       |
+| `fields.image`                                    | string                                  | Card field for images (default: `Picture`)                                                                                                    |
+| `fields.sentence`                                 | string                                  | Card field for sentences (default: `Sentence`)                                                                                                |
+| `fields.miscInfo`                                 | string                                  | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                     |
+| `fields.translation`                              | string                                  | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                 |
+| `ankiConnect.ai.enabled`                          | `true`, `false`                         | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                |
+| `ankiConnect.ai.model`                            | string                                  | Optional model override for Anki AI translation/enrichment flows.                                                                             |
+| `ankiConnect.ai.systemPrompt`                     | string                                  | Optional system prompt override for Anki AI translation/enrichment flows.                                                                     |
+| `media.generateAudio`                             | `true`, `false`                         | Generate audio clips from video (default: `true`)                                                                                             |
+| `media.generateImage`                             | `true`, `false`                         | Generate image/animation screenshots (default: `true`)                                                                                        |
+| `media.imageType`                                 | `"static"`, `"avif"`                    | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                          |
+| `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`              | Image format (default: `"jpg"`)                                                                                                               |
+| `media.imageQuality`                              | number (1-100)                          | Image quality for JPG/WebP; PNG ignores this (default: `92`)                                                                                  |
+| `media.imageMaxWidth`                             | number (px)                             | Optional max width for static screenshots. Unset keeps source width.                                                                          |
+| `media.imageMaxHeight`                            | number (px)                             | Optional max height for static screenshots. Unset keeps source height.                                                                        |
+| `media.animatedFps`                               | number (1-60)                           | FPS for animated AVIF (default: `10`)                                                                                                         |
+| `media.animatedMaxWidth`                          | number (px)                             | Max width for animated AVIF (default: `640`)                                                                                                  |
+| `media.animatedMaxHeight`                         | number (px)                             | Optional max height for animated AVIF. Unset keeps source aspect-constrained height.                                                          |
+| `media.animatedCrf`                               | number (0-63)                           | CRF quality for AVIF; lower = higher quality (default: `35`)                                                                                  |
+| `media.syncAnimatedImageToWordAudio`              | `true`, `false`                         | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`).                                       |
+| `media.audioPadding`                              | number (seconds)                        | Padding around audio clip timing (default: `0.5`)                                                                                             |
+| `media.fallbackDuration`                          | number (seconds)                        | Default duration if timing unavailable (default: `3.0`)                                                                                       |
+| `media.maxMediaDuration`                          | number (seconds)                        | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                         |
+| `behavior.overwriteAudio`                         | `true`, `false`                         | Replace existing audio on updates; when `false`, new audio is appended/prepended per `behavior.mediaInsertMode` (default: `true`)             |
+| `behavior.overwriteImage`                         | `true`, `false`                         | Replace existing images on updates; when `false`, new images are appended/prepended per `behavior.mediaInsertMode` (default: `true`)          |
+| `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                 | Where to insert new media when overwrite is off (default: `"append"`)                                                                         |
+| `behavior.highlightWord`                          | `true`, `false`                         | Highlight the word in sentence context (default: `true`)                                                                                      |
+| `ankiConnect.knownWords.highlightEnabled`         | `true`, `false`                         | Enable fast local highlighting for words already known in Anki (default: `false`)                                                             |
+| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`, `false`                         | Add words from successful mines into the local known-word cache immediately (default: `true`)                                                 |
+| `ankiConnect.knownWords.color`                    | hex color string                        | Text color for tokens already found in the local known-word cache (default: `"#a6da95"`).                                                     |
+| `ankiConnect.knownWords.matchMode`                | `"headword"`, `"surface"`               | Matching strategy for known-word highlighting (default: `"headword"`). `headword` uses token headwords; `surface` uses visible subtitle text. |
+| `ankiConnect.knownWords.refreshMinutes`           | number                                  | Minutes between known-word cache refreshes (default: `1440`)                                                                                  |
+| `ankiConnect.knownWords.decks`                    | object                                  | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word", "Word Reading"] }`).                               |
+| `ankiConnect.nPlusOne.nPlusOne`                   | hex color string                        | Text color for the single target token to study when exactly one unknown candidate exists in a sentence (default: `"#c6a0f6"`).               |
+| `ankiConnect.nPlusOne.minSentenceWords`           | number                                  | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                        |
+| `behavior.notificationType`                       | `"osd"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"osd"`)                                                                                           |
+| `behavior.autoUpdateNewCards`                     | `true`, `false`                         | Automatically update cards on creation (default: `true`)                                                                                      |
+| `metadata.pattern`                                | string                                  | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time                                                                      |
+| `isLapis`                                         | object                                  | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.  |
+| `isKiku`                                          | object                                  | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)     |
 
 `ankiConnect.ai` only controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
 API key resolution, base URL, and timeout live under the shared top-level [`ai`](#shared-ai-provider) config.
@@ -1024,8 +1023,8 @@ Sync the active subtitle track using `alass` (preferred) or `ffsubsync`. Both ar
 | Option           | Values               | Description                                                                                                               |
 | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `defaultMode`    | `"auto"`, `"manual"` | `auto`: try `alass` against secondary subtitle, then fallback to `ffsubsync`; `manual`: open overlay picker               |
-| `alass_path`     | string path          | Path to `alass` executable. Empty or `null` resolves from `PATH`. `alass` must be installed separately.                  |
-| `ffsubsync_path` | string path          | Path to `ffsubsync` executable. Empty or `null` resolves from `PATH`. `ffsubsync` must be installed separately.          |
+| `alass_path`     | string path          | Path to `alass` executable. Empty or `null` resolves from `PATH`. `alass` must be installed separately.                   |
+| `ffsubsync_path` | string path          | Path to `ffsubsync` executable. Empty or `null` resolves from `PATH`. `ffsubsync` must be installed separately.           |
 | `ffmpeg_path`    | string path          | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
 | `replace`        | `true`, `false`      | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |
 
@@ -1057,18 +1056,18 @@ AniList integration is opt-in and disabled by default. Enable it to allow SubMin
 }
 ```
 
-| Option                                | Values                  | Description                                                                                      |
-| ------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
-| `enabled`                             | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                    |
-| `accessToken`                         | string                  | Optional explicit AniList access token override (default: empty string)                          |
-| `characterDictionary.enabled`         | `true`, `false`         | Enable automatic import/update of the merged SubMiner character dictionary for recent AniList media |
-| `characterDictionary.refreshTtlHours` | number                  | Legacy compatibility setting. Parsed and preserved, but merged dictionary retention is now usage-based |
-| `characterDictionary.maxLoaded`       | number                  | Maximum number of most-recently-used AniList media snapshots included in the merged dictionary (default: `3`) |
-| `characterDictionary.evictionPolicy`  | `"delete"`, `"disable"` | Legacy compatibility setting. Parsed and preserved, but merged dictionary eviction is now usage-based |
-| `characterDictionary.collapsibleSections.description` | `true`, `false` | Open the Description section by default in generated dictionary entries |
-| `characterDictionary.collapsibleSections.characterInformation` | `true`, `false` | Open the Character Information section by default in generated dictionary entries |
-| `characterDictionary.collapsibleSections.voicedBy` | `true`, `false` | Open the Voiced by section by default in generated dictionary entries |
-| `characterDictionary.profileScope`    | `"all"`, `"active"`     | Apply dictionary settings updates to all Yomitan profiles or only active profile                 |
+| Option                                                         | Values                  | Description                                                                                                   |
+| -------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `enabled`                                                      | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                                 |
+| `accessToken`                                                  | string                  | Optional explicit AniList access token override (default: empty string)                                       |
+| `characterDictionary.enabled`                                  | `true`, `false`         | Enable automatic import/update of the merged SubMiner character dictionary for recent AniList media           |
+| `characterDictionary.refreshTtlHours`                          | number                  | Legacy compatibility setting. Parsed and preserved, but merged dictionary retention is now usage-based        |
+| `characterDictionary.maxLoaded`                                | number                  | Maximum number of most-recently-used AniList media snapshots included in the merged dictionary (default: `3`) |
+| `characterDictionary.evictionPolicy`                           | `"delete"`, `"disable"` | Legacy compatibility setting. Parsed and preserved, but merged dictionary eviction is now usage-based         |
+| `characterDictionary.collapsibleSections.description`          | `true`, `false`         | Open the Description section by default in generated dictionary entries                                       |
+| `characterDictionary.collapsibleSections.characterInformation` | `true`, `false`         | Open the Character Information section by default in generated dictionary entries                             |
+| `characterDictionary.collapsibleSections.voicedBy`             | `true`, `false`         | Open the Voiced by section by default in generated dictionary entries                                         |
+| `characterDictionary.profileScope`                             | `"all"`, `"active"`     | Apply dictionary settings updates to all Yomitan profiles or only active profile                              |
 
 When `enabled` is `true` and `accessToken` is empty, SubMiner opens an AniList setup helper window. Keep `enabled` as `false` to disable all AniList setup/update behavior.
 
@@ -1124,8 +1123,8 @@ For GameSentenceMiner on Linux, the default overlay profile path is typically `~
 }
 ```
 
-| Option                | Values      | Description                                                                                                                           |
-| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Option                | Values      | Description                                                                                                                                                                                                    |
+| --------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `externalProfilePath` | string path | Optional absolute path, or a path beginning with `~` (expanded to your home directory), to another app's Yomitan Electron profile. SubMiner loads that profile read-only and reuses its dictionaries/settings. |
 
 External-profile mode behavior:
@@ -1210,12 +1209,12 @@ Discord Rich Presence is enabled by default. SubMiner publishes a polished activ
 }
 ```
 
-| Option             | Values                                            | Description                                                |
-| ------------------ | ------------------------------------------------- | ---------------------------------------------------------- |
-| `enabled`          | `true`, `false`                                   | Enable Discord Rich Presence updates (default: `true`)     |
-| `presenceStyle`    | `"default"`, `"meme"`, `"japanese"`, `"minimal"`  | Card text preset (default: `"default"`)                    |
-| `updateIntervalMs` | number                                            | Minimum interval between activity updates in milliseconds  |
-| `debounceMs`       | number                                            | Debounce window for bursty playback events in milliseconds |
+| Option             | Values                                           | Description                                                |
+| ------------------ | ------------------------------------------------ | ---------------------------------------------------------- |
+| `enabled`          | `true`, `false`                                  | Enable Discord Rich Presence updates (default: `true`)     |
+| `presenceStyle`    | `"default"`, `"meme"`, `"japanese"`, `"minimal"` | Card text preset (default: `"default"`)                    |
+| `updateIntervalMs` | number                                           | Minimum interval between activity updates in milliseconds  |
+| `debounceMs`       | number                                           | Debounce window for bursty playback events in milliseconds |
 
 Setup steps:
 
@@ -1227,12 +1226,12 @@ Setup steps:
 
 While playing media, the **Details** line always shows the current media title and **State** shows `Playing mm:ss / mm:ss` or `Paused mm:ss / mm:ss`. The preset controls what appears when idle and the tooltip text on images.
 
-| Preset       | Idle details                        | Small image text   | Vibe                                    |
-| ------------ | ----------------------------------- | ------------------ | --------------------------------------- |
-| **`default`**| `Sentence Mining`                   | `日本語学習中`      | Clean, bilingual flair                  |
-| `meme`       | `Mining and crafting (Anki cards)`  | `Sentence Mining`  | Minecraft-inspired joke                 |
-| `japanese`   | `文の採掘中`                         | `イマージョン学習`  | Fully Japanese                          |
-| `minimal`    | `SubMiner`                          | *(none)*           | Bare essentials, no small image overlay |
+| Preset        | Idle details                       | Small image text   | Vibe                                    |
+| ------------- | ---------------------------------- | ------------------ | --------------------------------------- |
+| **`default`** | `Sentence Mining`                  | `日本語学習中`     | Clean, bilingual flair                  |
+| `meme`        | `Mining and crafting (Anki cards)` | `Sentence Mining`  | Minecraft-inspired joke                 |
+| `japanese`    | `文の採掘中`                       | `イマージョン学習` | Fully Japanese                          |
+| `minimal`     | `SubMiner`                         | _(none)_           | Bare essentials, no small image overlay |
 
 All presets use the `subminer-logo` large image with `SubMiner` tooltip. No activity button is shown by default.
 
@@ -1275,23 +1274,23 @@ Enable or disable local immersion analytics stored in SQLite for mined subtitles
 }
 ```
 
-| Option                         | Values                        | Description                                                                                                 |
-| ------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `enabled`                      | `true`, `false`               | Enable immersion tracking. Defaults to `true`.                                                              |
-| `dbPath`                       | string                        | Optional SQLite database path. Leave empty to use default app-data path at `<config dir>/immersion.sqlite`. |
-| `batchSize`                    | integer (`1`-`10000`)         | Buffered writes per transaction. Default `25`.                                                              |
-| `flushIntervalMs`              | integer (`50`-`60000`)        | Maximum queue delay before flush. Default `500ms`.                                                          |
-| `queueCap`                     | integer (`100`-`100000`)      | In-memory queue cap. Overflow drops oldest writes. Default `1000`.                                          |
-| `payloadCapBytes`              | integer (`64`-`8192`)         | Event payload byte cap before truncation marker. Default `256`.                                             |
-| `maintenanceIntervalMs`        | integer (`60000`-`604800000`) | Prune + rollup maintenance cadence. Default `86400000` (24h).                                               |
-| `retentionMode`                | `preset`,`advanced`           | Retention mode. `preset` applies `retentionPreset`, `advanced` uses explicit values only. Default `preset`. |
-| `retentionPreset`              | `minimal`,`balanced`,`deep-history` | Retention preset used when `retentionMode = "preset"`. Default `balanced`.                              |
-| `retention.eventsDays`         | integer (`0`-`3650`)          | Raw event retention window in days. Default `0` (keep all).                                                  |
-| `retention.telemetryDays`      | integer (`0`-`3650`)          | Telemetry retention window in days. Default `0` (keep all).                                                  |
-| `retention.sessionsDays`       | integer (`0`-`3650`)          | Session retention window in days. Default `0` (keep all).                                                    |
-| `retention.dailyRollupsDays`   | integer (`0`-`36500`)         | Daily rollup retention window. Default `0` (keep all).                                                      |
-| `retention.monthlyRollupsDays` | integer (`0`-`36500`)         | Monthly rollup retention window. Default `0` (keep all).                                                    |
-| `retention.vacuumIntervalDays` | integer (`0`-`3650`)          | Minimum spacing between `VACUUM` passes. `0` disables vacuum. Default `0` (disabled).                         |
+| Option                         | Values                              | Description                                                                                                 |
+| ------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `enabled`                      | `true`, `false`                     | Enable immersion tracking. Defaults to `true`.                                                              |
+| `dbPath`                       | string                              | Optional SQLite database path. Leave empty to use default app-data path at `<config dir>/immersion.sqlite`. |
+| `batchSize`                    | integer (`1`-`10000`)               | Buffered writes per transaction. Default `25`.                                                              |
+| `flushIntervalMs`              | integer (`50`-`60000`)              | Maximum queue delay before flush. Default `500ms`.                                                          |
+| `queueCap`                     | integer (`100`-`100000`)            | In-memory queue cap. Overflow drops oldest writes. Default `1000`.                                          |
+| `payloadCapBytes`              | integer (`64`-`8192`)               | Event payload byte cap before truncation marker. Default `256`.                                             |
+| `maintenanceIntervalMs`        | integer (`60000`-`604800000`)       | Prune + rollup maintenance cadence. Default `86400000` (24h).                                               |
+| `retentionMode`                | `preset`,`advanced`                 | Retention mode. `preset` applies `retentionPreset`, `advanced` uses explicit values only. Default `preset`. |
+| `retentionPreset`              | `minimal`,`balanced`,`deep-history` | Retention preset used when `retentionMode = "preset"`. Default `balanced`.                                  |
+| `retention.eventsDays`         | integer (`0`-`3650`)                | Raw event retention window in days. Default `0` (keep all).                                                 |
+| `retention.telemetryDays`      | integer (`0`-`3650`)                | Telemetry retention window in days. Default `0` (keep all).                                                 |
+| `retention.sessionsDays`       | integer (`0`-`3650`)                | Session retention window in days. Default `0` (keep all).                                                   |
+| `retention.dailyRollupsDays`   | integer (`0`-`36500`)               | Daily rollup retention window. Default `0` (keep all).                                                      |
+| `retention.monthlyRollupsDays` | integer (`0`-`36500`)               | Monthly rollup retention window. Default `0` (keep all).                                                    |
+| `retention.vacuumIntervalDays` | integer (`0`-`3650`)                | Minimum spacing between `VACUUM` passes. `0` disables vacuum. Default `0` (disabled).                       |
 
 You can also disable immersion tracking for a single session using:
 
@@ -1328,11 +1327,11 @@ Configure the local stats UI served from SubMiner and the in-app stats overlay t
 }
 ```
 
-| Option            | Values            | Description                                                                 |
-| ----------------- | ----------------- | --------------------------------------------------------------------------- |
-| `toggleKey`       | Electron key code | Overlay-local key code used to toggle the stats overlay. Default `Backquote`. |
-| `serverPort`      | integer           | Localhost port for the browser stats UI. Default `6969`.                    |
-| `autoStartServer` | `true`, `false`   | Start the local stats HTTP server automatically once immersion tracking is active. Default `true`. |
+| Option            | Values            | Description                                                                                                          |
+| ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `toggleKey`       | Electron key code | Overlay-local key code used to toggle the stats overlay. Default `Backquote`.                                        |
+| `serverPort`      | integer           | Localhost port for the browser stats UI. Default `6969`.                                                             |
+| `autoStartServer` | `true`, `false`   | Start the local stats HTTP server automatically once immersion tracking is active. Default `true`.                   |
 | `autoOpenBrowser` | `true`, `false`   | When `subminer stats` starts the server on demand, also open the dashboard in your default browser. Default `false`. |
 
 Usage notes:
@@ -1342,6 +1341,30 @@ Usage notes:
 - The dashboard reads from the same immersion-tracking database, so keep `immersionTracking.enabled` on if you want data to appear.
 - The UI includes Overview, Library, Trends, Vocabulary, and Sessions tabs.
 
+### MPV Launcher
+
+Configure the mpv executable and window state for SubMiner-managed mpv launches (launcher playback, Windows `--launch-mpv`, and Jellyfin idle mpv startup):
+
+```json
+{
+  "mpv": {
+    "executablePath": "",
+    "launchMode": "normal"
+  }
+}
+```
+
+| Option           | Values                                        | Description                                                                                                                         |
+| ---------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `executablePath` | string                                        | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`) |
+| `launchMode`     | `"normal"` \| `"maximized"` \| `"fullscreen"` | Window state when SubMiner spawns mpv (default `"normal"`)                                                                          |
+
+Launch mode behavior:
+
+- **`normal`** — mpv opens at its default window size with no extra flags.
+- **`maximized`** — mpv starts maximized via `--window-maximized=yes`, keeping taskbar access.
+- **`fullscreen`** — mpv starts in true fullscreen via `--fullscreen`.
+
 ### YouTube Playback Settings
 
 Set defaults used by managed subtitle auto-selection and the `subminer` launcher YouTube flow:
@@ -1354,9 +1377,9 @@ Set defaults used by managed subtitle auto-selection and the `subminer` launcher
 }
 ```
 
-| Option                | Values               | Description                                                                                    |
-| --------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |
-| `primarySubLanguages` | string[]             | Primary subtitle language priority for managed subtitle auto-selection (default `["ja", "jpn"]`) |
+| Option                | Values   | Description                                                                                      |
+| --------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `primarySubLanguages` | string[] | Primary subtitle language priority for managed subtitle auto-selection (default `["ja", "jpn"]`) |
 
 Current launcher behavior:
 

docs-site/docs-sync.test.ts

@@ -8,7 +8,10 @@ const installationContents = readFileSync(new URL('./installation.md', import.me
 const mpvPluginContents = readFileSync(new URL('./mpv-plugin.md', import.meta.url), 'utf8');
 const developmentContents = readFileSync(new URL('./development.md', import.meta.url), 'utf8');
 const changelogContents = readFileSync(new URL('./changelog.md', import.meta.url), 'utf8');
-const ankiIntegrationContents = readFileSync(new URL('./anki-integration.md', import.meta.url), 'utf8');
+const ankiIntegrationContents = readFileSync(
+  new URL('./anki-integration.md', import.meta.url),
+  'utf8',
+);
 const configurationContents = readFileSync(new URL('./configuration.md', import.meta.url), 'utf8');
 
 function extractReleaseHeadings(content: string, count: number): string[] {
@@ -17,6 +20,13 @@ function extractReleaseHeadings(content: string, count: number): string[] {
     .slice(0, count);
 }
 
+function extractCurrentMinorHeadings(content: string): string[] {
+  const allHeadings = Array.from(content.matchAll(/^## v(\d+\.\d+)\.\d+[^\n]*$/gm));
+  if (allHeadings.length === 0) return [];
+  const currentMinor = allHeadings[0]![1];
+  return allHeadings.filter(([, minor]) => minor === currentMinor).map(([heading]) => heading);
+}
+
 test('docs reflect current launcher and release surfaces', () => {
   expect(usageContents).not.toContain('--mode preprocess');
   expect(usageContents).not.toContain('"automatic" (default)');
@@ -44,9 +54,11 @@ test('docs reflect current launcher and release surfaces', () => {
   expect(configurationContents).toContain('youtube.primarySubLanguages');
   expect(configurationContents).toContain('### Shared AI Provider');
 
-  expect(changelogContents).toContain('## v0.5.1 (2026-03-09)');
+  expect(changelogContents).toContain('v0.5.1 (2026-03-09)');
 });
 
-test('docs changelog keeps the newest release headings aligned with the root changelog', () => {
-  expect(extractReleaseHeadings(changelogContents, 3)).toEqual(extractReleaseHeadings(rootChangelogContents, 3));
+test('docs changelog keeps the current minor release headings aligned with the root changelog', () => {
+  const docsHeadings = extractCurrentMinorHeadings(changelogContents);
+  expect(docsHeadings.length).toBeGreaterThan(0);
+  expect(docsHeadings).toEqual(extractReleaseHeadings(rootChangelogContents, docsHeadings.length));
 });

docs-site/installation.md

@@ -28,11 +28,15 @@ The `subminer` launcher script handles step 1 automatically. If you launch mpv y
 
 ### Platform-Specific
 
-**Linux** — one of the following compositors:
+**Linux** — one of the following window backends:
 
-- Hyprland (uses `hyprctl`)
-- Sway (uses `swaymsg`)
-- X11 (uses `xdotool` and `xwininfo`)
+- **Hyprland** — native Wayland support (uses `hyprctl`)
+- **Sway** — native Wayland support (uses `swaymsg`)
+- **X11 / Xwayland** — for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)
+
+::: warning Wayland support is compositor-specific
+Wayland has no universal API for window positioning — each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
+:::
 
 <details>
 <summary><b>Arch Linux</b></summary>
@@ -43,7 +47,7 @@ sudo pacman -S --needed mpv ffmpeg
 sudo pacman -S --needed mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
 # Optional: subtitle sync (at least one needed for subtitle syncing)
 paru -S --needed alass python-ffsubsync
-# X11 / XWAYLAND
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
 sudo pacman -S --needed xdotool xorg-xwininfo
 ```
 
@@ -56,7 +60,7 @@ sudo pacman -S --needed xdotool xorg-xwininfo
 sudo apt install mpv ffmpeg
 # Optional
 sudo apt install mecab libmecab-dev mecab-ipadic-utf8 fzf rofi chafa ffmpegthumbnailer yt-dlp
-# X11
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
 sudo apt install xdotool x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
@@ -72,7 +76,7 @@ pip install ffsubsync
 sudo dnf install mpv ffmpeg
 # Optional
 sudo dnf install mecab mecab-ipadic fzf rofi chafa ffmpegthumbnailer yt-dlp
-# X11
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
 sudo dnf install xdotool xorg-x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
@@ -388,23 +392,41 @@ AnkiConnect listens on `http://127.0.0.1:8765` by default. SubMiner will connect
 
 For enrichment configuration (sentence, audio, screenshot fields), see [Anki Integration](/anki-integration).
 
-## Verify Installation
+## First-Run Setup
 
-After installing, run the built-in diagnostic to confirm dependencies are in place:
+Run the setup wizard to create a default config and finish initial configuration. You do **not** need to create the config manually — SubMiner handles it.
 
 ```bash
-subminer doctor
+subminer app --setup
 ```
 
-This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix any failures before continuing.
-
 > [!NOTE]
-> On Windows, use `bun run subminer doctor` or run `SubMiner.exe` directly. Replace `SubMiner.AppImage` with `SubMiner.exe` in the direct app commands below.
+> On Windows, run `SubMiner.exe` directly — it opens the setup wizard automatically on first launch.
+
+The setup popup walks you through:
+
+- **Config file**: auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows)
+- **mpv plugin**: install the bundled Lua plugin for in-player keybindings
+- **Yomitan dictionaries**: import at least one dictionary so lookups work
+- **Windows shortcut** _(Windows only)_: optionally create a `SubMiner mpv` Start Menu/Desktop shortcut
+
+The `Finish setup` button stays disabled until the plugin is installed and at least one dictionary is imported. Once you finish, SubMiner will not show the popup again.
+
+> [!TIP]
+> You can re-open the setup popup at any time with `subminer app --setup` or `SubMiner.AppImage --setup`.
+
+Once setup is complete, play a video to verify everything works:
 
 ```bash
-# Play a file (default plugin config auto-starts visible overlay and waits for annotation readiness; first launch may open first-run setup popup)
 subminer video.mkv
+```
 
+You should see the overlay appear over mpv. If subtitles are loaded in the video, they will appear as interactive text in the overlay.
+
+<details>
+<summary><b>More launch examples</b></summary>
+
+```bash
 # Optional explicit overlay start for setups with plugin auto_start=no
 subminer --start video.mkv
 
@@ -419,29 +441,26 @@ SubMiner.AppImage --start --dev
 SubMiner.AppImage --help    # Show all CLI options
 ```
 
-You should see the overlay appear over mpv. If subtitles are loaded in the video, they will appear as interactive text in the overlay.
+</details>
 
-## First-Run Setup
+## Verify Setup
 
-On first launch SubMiner creates a default config file automatically and opens a setup popup. You do **not** need to create the config manually — SubMiner handles it.
+After completing first-run setup, run the built-in diagnostic to confirm everything is in place:
 
-The setup popup walks you through:
+```bash
+subminer doctor
+```
 
-- **Config file**: auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows)
-- **mpv plugin**: install the bundled Lua plugin for in-player keybindings
-- **Yomitan dictionaries**: import at least one dictionary so lookups work
-- **Windows shortcut** _(Windows only)_: optionally create a `SubMiner mpv` Start Menu/Desktop shortcut
+This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix any failures before continuing.
 
-The `Finish setup` button stays disabled until the plugin is installed and at least one dictionary is imported. Once you finish, SubMiner will not show the popup again.
-
-> [!TIP]
-> You can re-open the setup popup at any time with `subminer --setup` or `SubMiner.AppImage --setup`.
+> [!NOTE]
+> On Windows, use `bun run subminer doctor` or run `SubMiner.exe` directly. Replace `SubMiner.AppImage` with `SubMiner.exe` in the direct app commands below.
 
 ## Optional Extras
 
 ### Rofi Theme (Linux Only)
 
-SubMiner ships a default rofi theme at `assets/themes/subminer.rasi`.
+SubMiner ships a custom rofi theme bundled in the release assets tarball.
 
 Install path (default auto-detected by `subminer`):
 
@@ -449,6 +468,8 @@ Install path (default auto-detected by `subminer`):
 - macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
 
 ```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
+tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
 ```

docs-site/jimaku-integration.md

@@ -26,31 +26,6 @@ If no files match the current episode filter, a "Show all files" button lets you
 | `Arrow Up` / `Arrow Down` | Navigate entries or files |
 | `Escape` | Close modal |
 
-### Flow
-
-```mermaid
-flowchart TD
-  classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  Open["Open Jimaku modal (Ctrl+Shift+J)"]:::step
-  Parse["Auto-fill title, season, episode from filename"]:::enrich
-  Search["Search Jimaku API"]:::action
-  Entries["Browse matching entries"]:::action
-  Files["Browse subtitle files"]:::action
-  Download["Download selected file"]:::action
-  Load["Load subtitle into mpv"]:::result
-
-  Open --> Parse
-  Parse --> Search
-  Search --> Entries
-  Entries --> Files
-  Files --> Download
-  Download --> Load
-```
-
 ## Configuration
 
 Add a `jimaku` section to your `config.jsonc`:

docs-site/jlpt-vocab-bundle.md

@@ -1,45 +0,0 @@
-# JLPT Vocabulary Bundle (Offline)
-
-## Bundle location
-
-SubMiner expects the JLPT term-meta bank files to be available locally at:
-
-- `vendor/yomitan-jlpt-vocab`
-
-At runtime, SubMiner also searches these derived locations:
-
-- `vendor/yomitan-jlpt-vocab`
-- `vendor/yomitan-jlpt-vocab/vendor/yomitan-jlpt-vocab`
-- `vendor/yomitan-jlpt-vocab/yomitan-jlpt-vocab`
-
-and user-data/config fallback paths (see `getJlptDictionarySearchPaths` in `src/main.ts`).
-
-## Required files
-
-The expected files are:
-
-- `term_meta_bank_1.json`
-- `term_meta_bank_2.json`
-- `term_meta_bank_3.json`
-- `term_meta_bank_4.json`
-- `term_meta_bank_5.json`
-
-Each bank maps terms to frequency metadata; only entries with a `frequency.displayValue` are considered for JLPT tagging.
-
-SubMiner also reuses the same `term_meta_bank_*.json` format for frequency-based subtitle highlighting, using installed/default `frequency-dictionary` locations or an explicit `subtitleStyle.frequencyDictionary.sourcePath`.
-
-## Source and update process
-
-For reproducible updates:
-
-1. Obtain the JLPT term-meta bank archive from the same upstream source that supplies the bundled Yomitan dictionary data.
-2. Extract the five `term_meta_bank_*.json` files.
-3. Place them into `vendor/yomitan-jlpt-vocab/`.
-4. Commit the update with the source URL/version in the task notes.
-
-This repository currently ships the folder path in `electron-builder` `extraResources` as:
-`vendor/yomitan-jlpt-vocab -> yomitan-jlpt-vocab`.
-
-## Fallback Behavior
-
-If bank files are missing, malformed, or lack expected metadata, SubMiner skips them gracefully. When no usable entries are found, JLPT underlining is silently disabled and subtitle rendering remains unchanged.

docs-site/launcher-script.md

@@ -13,9 +13,9 @@ When you run `subminer` without specifying a file, it opens an interactive video
 ### fzf (default)
 
 ```bash
-subminer                        # pick from current directory
-subminer -d ~/Videos            # pick from a specific directory
-subminer -r -d ~/Anime          # recursive search
+subminer                               # pick from current directory
+subminer -d ~/Videos                   # pick from a specific directory
+subminer -r -d ~/Anime                 # recursive search
 ```
 
 fzf shows video files in a fuzzy-searchable list. If `chafa` is installed, you get thumbnail previews in the right pane. Thumbnails are sourced from the freedesktop thumbnail cache first, then generated on the fly with `ffmpegthumbnailer` or `ffmpeg` as fallback.
@@ -28,14 +28,17 @@ fzf shows video files in a fuzzy-searchable list. If `chafa` is installed, you g
 ### rofi
 
 ```bash
-subminer -R                     # rofi picker, current directory
-subminer -R -d ~/Videos         # rofi picker, specific directory
-subminer -R -r -d ~/Anime       # rofi picker, recursive
+subminer -R                            # rofi picker, current directory
+subminer -R -d ~/Videos                # rofi picker, specific directory
+subminer -R -r -d ~/Anime              # rofi picker, recursive
+subminer -R /directory                 # rofi picker, directory shortcut
 ```
 
-rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme that can be installed from the release assets:
+rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme bundled in the release assets tarball:
 
 ```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
+tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
 ```
@@ -57,15 +60,11 @@ SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
 ## Common Commands
 
 ```bash
-subminer video.mkv              # play a specific file (default plugin config auto-starts visible overlay)
-subminer --start video.mkv      # optional explicit overlay start when plugin auto_start=no
-subminer -S video.mkv           # same as above via --start-overlay
-subminer https://youtu.be/...   # YouTube playback (requires yt-dlp)
-subminer ytsearch:"jp news"     # YouTube search
-subminer stats                  # open immersion dashboard
-subminer stats -b               # start background stats daemon
-subminer stats -s               # stop background stats daemon
-subminer --setup                # Open first-run setup popup
+subminer video.mkv                      # play a specific file (default plugin config auto-starts visible overlay)
+subminer https://youtu.be/...           # YouTube playback (requires yt-dlp)
+subminer --backend x11 video.mkv        # Force x11 backend for a specific file
+subminer stats                          # open immersion dashboard
+subminer stats -b                       # start background stats daemon
 ```
 
 ## Subcommands
@@ -75,7 +74,6 @@ subminer --setup                # Open first-run setup popup
 | `subminer jellyfin` / `jf`   | Jellyfin workflows (`-d` discovery, `-p` play, `-l` login) |
 | `subminer stats`             | Start stats server and open immersion dashboard in browser |
 | `subminer stats -b`          | Start or reuse background stats daemon (non-blocking)      |
-| `subminer stats -s`          | Stop the background stats daemon                           |
 | `subminer stats cleanup`     | Backfill vocabulary metadata and prune stale rows          |
 | `subminer doctor`            | Dependency + config + socket diagnostics                   |
 | `subminer config path`       | Print active config file path                              |
@@ -100,7 +98,7 @@ Use `subminer <subcommand> -h` for command-specific help.
 | `--start`             | Explicitly start overlay after mpv launches         |
 | `-S, --start-overlay` | Explicitly start overlay after mpv launches         |
 | `-T, --no-texthooker` | Disable texthooker server                           |
-| `-p, --profile`       | mpv profile name (default: `subminer`)              |
+| `-p, --profile`       | mpv profile name (no default; omitted unless set)   |
 | `-a, --args`          | Pass additional mpv arguments as a quoted string      |
 | `-b, --backend`       | Force window backend (`hyprland`, `sway`, `x11`, `macos`, `windows`)    |
 | `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`) |

docs-site/mining-workflow.md

@@ -6,30 +6,6 @@ This guide walks through the sentence mining loop — from watching a video to c
 
 SubMiner runs as a transparent overlay on top of mpv. As subtitles play, the overlay displays them as interactive text. You hover a word, trigger Yomitan lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, audio clip, and screenshot.
 
-```mermaid
-flowchart TB
-  classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  Watch["Watch Video"]:::step
-  Sub["Subtitle Appears"]:::step
-  Hover["Hover Word"]:::action
-  Lookup["Trigger Lookup"]:::action
-  Yomi["Yomitan Popup"]:::result
-  Add["Add to Anki"]:::result
-
-  Watch --> Sub --> Hover --> Lookup --> Yomi --> Add
-
-  Add --> Enrich["SubMiner Enriches"]:::enrich
-
-  Enrich --> S["Sentence"]:::enrich
-  Enrich --> A["Audio Clip"]:::enrich
-  Enrich --> I["Screenshot"]:::enrich
-  Enrich --> T["Translation"]:::enrich
-```
-
 ## Subtitle Delivery Path (Startup + Runtime)
 
 SubMiner prioritizes subtitle responsiveness over heavy initialization:
@@ -141,10 +117,18 @@ Create a standalone sentence card without going through Yomitan:
 
 The sentence card uses the note type configured in `isLapis.sentenceCardModel` and always maps sentence/audio to `Sentence` and `SentenceAudio`.
 
+::: warning Requires Lapis/Kiku note type
+Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+:::
+
 ### 4. Mark as Audio Card
 
 After adding a word via Yomitan, press the audio card shortcut to overwrite the audio with a longer clip spanning the full subtitle timing.
 
+::: warning Requires Lapis/Kiku note type
+Audio card marking requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+:::
+
 ## Secondary Subtitles
 
 SubMiner can display a secondary subtitle track (typically English) alongside the primary Japanese subtitles. This is useful for:

docs-site/mpv-plugin.md

@@ -183,6 +183,10 @@ When `backend=auto`, the plugin detects the window manager:
 4. **X11** — detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
 5. **Fallback** — defaults to X11 with a warning.
 
+::: tip Wayland is compositor-specific
+Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 — both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
+:::
+
 ## Script Messages
 
 The plugin can be controlled from other mpv scripts or the mpv command line using script messages:

docs-site/public/config.example.jsonc

@@ -461,10 +461,12 @@
   // ==========================================
   // MPV Launcher
   // Optional mpv.exe override for Windows playback entry points.
+  // Set mpv.launchMode to choose normal, maximized, or fullscreen SubMiner-managed mpv playback.
   // Leave mpv.executablePath blank to auto-discover mpv.exe from SUBMINER_MPV_PATH or PATH.
   // ==========================================
   "mpv": {
-    "executablePath": "" // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
+    "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
+    "launchMode": "normal" // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
   }, // Optional mpv.exe override for Windows playback entry points.
 
   // ==========================================

docs-site/subtitle-annotations.md

@@ -113,10 +113,6 @@ All colors are customizable via the `subtitleStyle.jlptColors` object.
 | `subtitleStyle.enableJlpt` | `false` | Enable JLPT underline styling |
 | `subtitleStyle.jlptColors.N1`–`N5` | see above | Per-level underline colors |
 
-::: tip
-JLPT tagging requires the offline vocabulary bundle. See [JLPT Vocabulary Bundle](jlpt-vocab-bundle) for setup instructions and file locations.
-:::
-
 ## Runtime Toggles
 
 All annotation layers can be toggled at runtime via the mpv command menu without restarting:

docs-site/subtitle-sidebar.md

@@ -60,8 +60,6 @@ Enable and configure the sidebar under `subtitleSidebar` in your config file:
 | `activeLineBackgroundColor` | string  | —            | Active cue background color                                                                        |
 | `hoverLineBackgroundColor`  | string  | —            | Hovered cue background color                                                                       |
 
-Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like a solid overlay.
-
 ## Keyboard Shortcut
 
 | Key | Action                  | Config key                     |

docs-site/troubleshooting.md

@@ -136,7 +136,7 @@ Shown when SubMiner tries to update a card that no longer exists, or when AnkiCo
 **Overlay does not appear**
 
 - Confirm SubMiner is running: `SubMiner.AppImage --start` or check for the process.
-- On Linux, the overlay requires a compositor. Hyprland and Sway are supported natively; X11 requires `xdotool` and `xwininfo`.
+- On Linux, the overlay requires a supported window backend. Hyprland and Sway have native Wayland support; all other compositors require both mpv and SubMiner to run under X11 or Xwayland (`xdotool` and `xwininfo` must be installed).
 - On macOS, grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.
 
 **Overlay appears but clicks pass through / cannot interact**
@@ -232,7 +232,7 @@ Global shortcuts (`Alt+Shift+O`, `Alt+Shift+Y`) may conflict with other applicat
 
 - Check your DE/WM keybinding settings for conflicts.
 - Change the shortcut in your config under `shortcuts.toggleVisibleOverlayGlobal`.
-- On Wayland, global shortcut registration has limitations depending on the compositor.
+- On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively — see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.
 
 **Overlay keybindings not working**
 
@@ -289,8 +289,8 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
 
 ### Linux
 
-- **Wayland (Hyprland/Sway)**: Window tracking uses compositor-specific commands. If `hyprctl` or `swaymsg` are not on `PATH`, tracking will fail silently.
-- **X11**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position.
+- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors are not supported — both mpv and SubMiner must run under X11 or Xwayland instead.
+- **X11 / Xwayland**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway — both mpv and SubMiner must be running under X11/Xwayland for window tracking to work.
 - **Mouse passthrough**: On Linux, Electron's mouse passthrough is unreliable. SubMiner keeps pointer events enabled, meaning you may need to toggle the overlay off to interact with mpv controls underneath.
 
 ### Hyprland
@@ -329,5 +329,4 @@ For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.l
 ### macOS
 
 - **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.
-- **Font rendering**: macOS uses a 0.87x font compensation factor for subtitle alignment between mpv and the overlay. If text alignment looks off, adjust subtitle offset by right-click dragging subtitle text.
 - **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`

docs-site/usage.md

@@ -37,7 +37,7 @@ Field names must match your Anki note type exactly (case-sensitive). See [Anki I
 There are several ways to use SubMiner:
 
 > [!TIP]
-> **New users: start with the `subminer` wrapper script** (or the **SubMiner mpv** shortcut on Windows). It handles mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`. You can add the mpv plugin later for in-player keybindings.
+> **New users: start with the `subminer` wrapper script** (or the **SubMiner mpv** shortcut on Windows). It handles mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`.
 
 | Approach                            | Use when                                                                                                                                            | How                                                                   |
 | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
@@ -85,8 +85,8 @@ subminer --args '--fs=opengl-hq --ytdl-format=bestvideo*+bestaudio/best' video.m
 # Options
 subminer -T video.mkv             # Disable texthooker server
 subminer -b x11 video.mkv         # Force X11 backend
-subminer video.mkv                # Uses mpv profile "subminer" by default
-subminer -p gpu-hq video.mkv      # Override mpv profile
+subminer video.mkv                # No mpv profile passed by default
+subminer -p gpu-hq video.mkv      # Use a specific mpv profile
 subminer jellyfin                 # Open Jellyfin setup window (subcommand form)
 subminer jellyfin -l --server http://127.0.0.1:8096 --username me --password 'secret'
 subminer jellyfin --logout        # Clear stored Jellyfin token/session data
@@ -157,7 +157,7 @@ You can use it three ways:
 & "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"
 ```
 
-This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback. On Windows, `--launch-mpv` does not require an `mpv.conf` profile named `subminer`.
+This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback.
 
 ### Launcher Subcommands
 
@@ -172,7 +172,7 @@ This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blan
 
 ### First-Run Setup
 
-SubMiner auto-opens the setup popup on fresh installs when launched with `--start` or `--background` and setup is incomplete.
+Setup popup appears on first launch, or when setup has not been completed.
 
 You can also open it manually:
 
@@ -262,7 +262,7 @@ Notes:
 - Secondary target languages come from `secondarySub.secondarySubLanguages` (defaults to English if unset).
 - Configure defaults in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`) under `youtube` and `secondarySub`.
 
-For local video files, SubMiner now uses those same config-driven language priorities after mpv finishes reporting subtitle tracks. That means mixed internal/external subtitle sets can correct an initial `sid=auto` guess and settle onto the expected primary and secondary tracks without manual cycling.
+For local video files, SubMiner uses the same config-driven language priorities to auto-select the primary and secondary subtitle tracks from internal and external subtitle sources.
 
 ## Controller Support
 

docs/superpowers/specs/2026-04-09-stats-dashboard-feedback-pass-design.md

@@ -0,0 +1,347 @@
+# Stats Dashboard Feedback Pass — Design
+
+Date: 2026-04-09
+Scope: Stats dashboard UX follow-ups from user feedback (items 1–7).
+Delivery: **Single PR**, broken into logically scoped commits.
+
+## Goals
+
+Address seven concrete pieces of feedback against the Statistics menu:
+
+1. Library — collapse episodes behind a per-series dropdown.
+2. Sessions — roll up multiple sessions of the same episode within a day.
+3. Trends — add a 365d range option.
+4. Library — delete an episode (video) from its detail view.
+5. Vocabulary — tighten spacing between word and reading in the Top 50 table.
+6. Episode detail — hide cards whose Anki notes have been deleted.
+7. Trend/watch charts — add gridlines, fix tick legibility, unify theming.
+
+Out of scope for this pass: English-token ingestion cleanup and Overview stat-card drill-downs (feedback items 8 and 9). Those require a larger design decision and a migration respectively.
+
+## Files touched (inventory)
+
+Dashboard (`stats/src/`):
+- `components/library/LibraryTab.tsx` — collapsible groups (item 1).
+- `components/library/MediaDetailView.tsx`, `components/library/MediaHeader.tsx` — delete-episode action (item 4).
+- `components/sessions/SessionsTab.tsx`, `components/library/MediaSessionList.tsx` — episode rollup (item 2).
+- `components/trends/DateRangeSelector.tsx`, `hooks/useTrends.ts`, `lib/api-client.ts`, `lib/api-client.test.ts` — 365d (item 3).
+- `components/vocabulary/FrequencyRankTable.tsx` — word/reading column collapse (item 5).
+- `components/anime/EpisodeDetail.tsx` — filter deleted Anki cards (item 6).
+- `components/trends/TrendChart.tsx`, `components/trends/StackedTrendChart.tsx`, `components/overview/WatchTimeChart.tsx`, `lib/chart-theme.ts` — chart clarity (item 7).
+- New file: `stats/src/lib/session-grouping.ts` + `session-grouping.test.ts`.
+
+Backend (`src/core/services/`):
+- `immersion-tracker/query-trends.ts` — extend `TrendRange` and `TREND_DAY_LIMITS` (item 3).
+- `immersion-tracker/__tests__/query.test.ts` — 365d coverage (item 3).
+- `stats-server.ts` — passthrough if range validation lives here (check before editing).
+- `__tests__/stats-server.test.ts` — 365d coverage (item 3).
+
+## Commit plan
+
+One PR, one feature per commit. Order picks low-risk mechanical changes first so failures in later commits don't block merging of earlier ones.
+
+1. `feat(stats): add 365d range to trends dashboard` (item 3)
+2. `fix(stats): tighten word/reading column in Top 50 table` (item 5)
+3. `fix(stats): hide cards deleted from Anki in episode detail` (item 6)
+4. `feat(stats): delete episode from library detail view` (item 4)
+5. `feat(stats): collapsible series groups in library` (item 1)
+6. `feat(stats): roll up same-episode sessions within a day` (item 2)
+7. `feat(stats): gridlines and unified theme for trend charts` (item 7)
+
+Each commit must pass `bun run typecheck`, `bun run test:fast`, and any change-specific checks listed below.
+
+---
+
+## Item 1 — Library collapsible series groups
+
+### Current behavior
+
+`LibraryTab.tsx` groups media via `groupMediaLibraryItems` and always renders the full grid of `MediaCard`s beneath each group header.
+
+### Target behavior
+
+Each group header becomes clickable. Groups with `items.length > 1` default to **collapsed**; single-video groups stay expanded (collapsing them would be visual noise).
+
+### Implementation
+
+- State: `const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(...)`. Initialize from `grouped` where `items.length > 1`.
+- Toggle helper: `toggleGroup(key: string)` adds/removes from the set.
+- Group header: wrap in a `<button>` with `aria-expanded` and a chevron icon (`▶`/`▼`). Keep the existing cover + title + subtitle layout inside the button.
+- Children grid is conditionally rendered on `!collapsedGroups.has(group.key)`.
+- Header summary (`N videos · duration · cards`) stays visible in both states so collapsed groups remain informative.
+
+### Tests
+
+- New `LibraryTab.test.tsx` (if not already present — check first) covering:
+  - Multi-video group renders collapsed on first mount.
+  - Single-video group renders expanded on first mount.
+  - Clicking the header toggles visibility.
+  - Header summary is visible in both states.
+
+---
+
+## Item 2 — Sessions episode rollup within a day
+
+### Current behavior
+
+`SessionsTab.tsx:10-24` groups sessions by day label only (`formatSessionDayLabel(startedAtMs)`). Multiple sessions of the same episode on the same day show as independent rows. `MediaSessionList.tsx` has the same problem inside the library detail view.
+
+### Target behavior
+
+Within each day, sessions with the same `videoId` collapse into one parent row showing combined totals. A chevron reveals the individual sessions. Single-session buckets render flat (no pointless nesting).
+
+### Implementation
+
+- New helper in `stats/src/lib/session-grouping.ts`:
+  ```ts
+  export interface SessionBucket {
+    key: string;              // videoId as string, or `s-${sessionId}` for singletons
+    videoId: number | null;
+    sessions: SessionSummary[];
+    totalActiveMs: number;
+    totalCardsMined: number;
+    representativeSession: SessionSummary; // most recent, for header display
+  }
+  export function groupSessionsByVideo(sessions: SessionSummary[]): SessionBucket[];
+  ```
+  Sessions missing a `videoId` become singleton buckets.
+
+- `SessionsTab.tsx`: after day grouping, pipe each `daySessions` through `groupSessionsByVideo`. Render each bucket:
+  - `sessions.length === 1`: existing `SessionRow` behavior, unchanged.
+  - `sessions.length >= 2`: render a **bucket row** that looks like `SessionRow` but shows combined totals and session count (e.g. `3 sessions · 1h 24m · 12 cards`). Chevron state stored in a second `Set<string>` on bucket key. Expanded buckets render the child `SessionRow`s indented (`pl-8`) beneath the header.
+- `MediaSessionList.tsx`: within the media detail view, a single video's sessions are all the same `videoId` by definition — grouping here is by day only, and within a day multiple sessions render nested under a day header. Re-use the same visual pattern; factor the bucket row into a shared `SessionBucketRow` component.
+
+### Delete semantics
+
+- Deleting a bucket header offers "Delete all N sessions in this group" (reuse `confirmDayGroupDelete` pattern with a bucket-specific message, or add `confirmBucketDelete`).
+- Deleting an individual session from inside an expanded bucket keeps the existing single-delete flow.
+
+### Tests
+
+- `session-grouping.test.ts`:
+  - Empty input → empty output.
+  - All unique videos → N singleton buckets.
+  - Two sessions same videoId → one bucket with correct totals and representative (most recent start time).
+  - Missing videoId → singleton bucket keyed by sessionId.
+- `SessionsTab.test.tsx` (extend or add) verifying the rendered bucket rows expand/collapse and delete hooks fire with the right ID set.
+
+---
+
+## Item 3 — 365d trends range
+
+### Backend
+
+`src/core/services/immersion-tracker/query-trends.ts`:
+- `type TrendRange = '7d' | '30d' | '90d' | '365d' | 'all';`
+- Add `'365d': 365` to `TREND_DAY_LIMITS`.
+- `getTrendDayLimit` picks up the new key automatically because of the `Exclude<TrendRange, 'all'>` generic.
+
+`src/core/services/stats-server.ts`:
+- Search for any hardcoded range validation (e.g. allow-list in the trends route handler) and extend it.
+
+### Frontend
+
+- `hooks/useTrends.ts`: widen the `TimeRange` union.
+- `components/trends/DateRangeSelector.tsx`: add `'365d'` to the options list. Display label stays as `365d`.
+- `lib/api-client.ts` / `api-client.test.ts`: if the client validates ranges, add `365d`.
+
+### Tests
+
+- `query.test.ts`: extend the existing range table to cover `365d` returning 365 days of data.
+- `stats-server.test.ts`: ensure the route accepts `range=365d`.
+- `api-client.test.ts`: ensure the client emits the new range.
+
+### Change-specific checks
+
+- `bun run test:config` is not required here (no schema/defaults change).
+- Run `bun run typecheck` + `bun run test:fast`.
+
+---
+
+## Item 4 — Delete episode from library detail
+
+### Current behavior
+
+`MediaDetailView.tsx` provides session-level delete only. The backend `deleteVideo` exists (`query-maintenance.ts:509`), the API is exposed at `stats-server.ts:559`, and `api-client.deleteVideo` is already wired (`stats/src/lib/api-client.ts:146`). `EpisodeList.tsx:46` already uses it from the anime tab.
+
+### Target behavior
+
+A "Delete Episode" action in `MediaHeader` (top-right, small, `text-ctp-red`), gated by `confirmEpisodeDelete(title)`. On success, call `onBack()` and make sure the parent `LibraryTab` refetches.
+
+### Implementation
+
+- Add an `onDeleteEpisode?: () => void` prop to `MediaHeader` and render the button only if provided.
+- In `MediaDetailView`:
+  - New handler `handleDeleteEpisode` that calls `apiClient.deleteVideo(videoId)`, then `onBack()`.
+  - Reuse `confirmEpisodeDelete` from `stats/src/lib/delete-confirm.ts`.
+- In `LibraryTab`:
+  - `useMediaLibrary` returns fresh data on mount. The simplest fix: pass a `refresh` function from the hook (extend the hook if it doesn't already expose one) and call it when the detail view signals back.
+  - Alternative: force a remount by incrementing a `libraryVersion` key on the library list. Prefer `refresh` for clarity.
+
+### Tests
+
+- Extend the existing `MediaDetailView.test.tsx`: mock `apiClient.deleteVideo`, click the new button, confirm `onBack` fires after success.
+- `useMediaLibrary.test.ts`: if we add a `refresh` method, cover it.
+
+---
+
+## Item 5 — Vocabulary word/reading column collapse
+
+### Current behavior
+
+`FrequencyRankTable.tsx:110-144` uses a 5-column table: `Rank | Word | Reading | POS | Seen`. Word and Reading are auto-sized, producing a large gap.
+
+### Target behavior
+
+Merge Word + Reading into a single column titled "Word". Reading sits immediately after the headword in a muted, smaller style.
+
+### Implementation
+
+- Drop the `<th>Reading</th>` header and cell.
+- Word cell becomes:
+  ```tsx
+  <td className="py-1.5 pr-3">
+    <span className="text-ctp-text font-medium">{w.headword}</span>
+    {reading && (
+      <span className="text-ctp-subtext0 text-xs ml-1.5">
+        【{reading}】
+      </span>
+    )}
+  </td>
+  ```
+  where `reading = fullReading(w.headword, w.reading)` and differs from `headword`.
+- Keep `fullReading` import from `reading-utils`.
+
+### Tests
+
+- Extend `FrequencyRankTable.test.tsx` (if present — otherwise add a focused test) to assert:
+  - Headword renders.
+  - Reading renders when different from headword.
+  - Reading does not render when equal to headword.
+
+---
+
+## Item 6 — Hide Anki-deleted cards in Cards Mined
+
+### Current behavior
+
+`EpisodeDetail.tsx:109-147` iterates `cardEvents`, fetches note info via `ankiNotesInfo(allNoteIds)`, and for each `noteId` renders a row even if no matching `info` came back — the user sees an empty word with an "Open in Anki" button that leads nowhere.
+
+### Target behavior
+
+After `ankiNotesInfo` resolves:
+- Drop `noteId`s that are not in the resolved map.
+- Drop `cardEvents` whose `noteIds` list was non-empty but is now empty after filtering.
+- Card events with a positive `cardsDelta` but no `noteIds` (legacy rollup path) still render as `+N cards` — we have no way to cross-reference them, so leave them alone.
+
+### Implementation
+
+- Compute `filteredCardEvents` as a `useMemo` depending on `data.cardEvents` and `noteInfos`.
+- Iterate `filteredCardEvents` instead of `cardEvents` in the render.
+- Surface a subtle note (optional, muted) "N cards hidden (deleted from Anki)" at the end of the list if any were filtered — helps the user understand why counts here diverge from session totals. Final decision on the note can be made at PR review; default: **show it**.
+
+### Tests
+
+- Add a test in `EpisodeDetail.test.tsx` (add the file if not present) that stubs `ankiNotesInfo` to return only a subset of notes and verifies the missing ones are not rendered.
+
+### Other call sites
+
+- Grep so far shows `ankiNotesInfo` is only used in `EpisodeDetail.tsx`. Re-verify before landing the commit; if another call site appears, apply the same filter.
+
+---
+
+## Item 7 — Trend/watch chart clarity pass
+
+### Current behavior
+
+`TrendChart.tsx`, `StackedTrendChart.tsx`, and `WatchTimeChart.tsx` render Recharts components with:
+- No `CartesianGrid` → no horizontal reference lines.
+- 9px axis ticks → borderline unreadable.
+- Height 120 → cramped.
+- Tooltip uses raw labels (`04/04` etc.).
+- No shared theme object; each chart redefines colors and tooltip styles inline.
+
+`stats/src/lib/chart-theme.ts` already exists and currently exports a single `CHART_THEME` constant with tick/tooltip colors and `barFill`. It will be extended, not replaced, to preserve existing consumers.
+
+### Target behavior
+
+All three charts share a theme, have horizontal gridlines, readable ticks, and sensible tooltips.
+
+### Implementation
+
+Extend `stats/src/lib/chart-theme.ts` with the additional shared defaults (keeping the existing `CHART_THEME` export intact so current consumers don't break):
+```ts
+export const CHART_THEME = {
+  tick: '#a5adcb',
+  tooltipBg: '#363a4f',
+  tooltipBorder: '#494d64',
+  tooltipText: '#cad3f5',
+  tooltipLabel: '#b8c0e0',
+  barFill: '#8aadf4',
+  grid: '#494d64',
+  axisLine: '#494d64',
+} as const;
+
+export const CHART_DEFAULTS = {
+  height: 160,
+  tickFontSize: 11,
+  margin: { top: 8, right: 8, bottom: 0, left: 0 },
+  grid: { strokeDasharray: '3 3', vertical: false },
+} as const;
+
+export const TOOLTIP_CONTENT_STYLE = {
+  background: CHART_THEME.tooltipBg,
+  border: `1px solid ${CHART_THEME.tooltipBorder}`,
+  borderRadius: 6,
+  color: CHART_THEME.tooltipText,
+  fontSize: 12,
+};
+```
+
+Apply to each chart:
+- Import `CartesianGrid` from recharts.
+- Insert `<CartesianGrid stroke={CHART_THEME.grid} {...CHART_DEFAULTS.grid} />` inside each chart container.
+- `<XAxis tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }} />` and equivalent `YAxis`.
+- `YAxis` gains `axisLine={{ stroke: CHART_THEME.axisLine }}`.
+- `ResponsiveContainer` height changes from 120 → `CHART_DEFAULTS.height`.
+- `Tooltip` `contentStyle` uses `TOOLTIP_CONTENT_STYLE`, and charts pass a `labelFormatter` when the label is a date key (e.g. show `Fri Apr 4`).
+
+### Unit formatters
+
+- `TrendChart` already accepts a `formatter` prop — extend usage sites to pass unit-aware formatters where they aren't already (`formatDuration`, `formatNumber`, etc.).
+
+### Tests
+
+- `chart-theme.test.ts` (if present — otherwise add a trivial snapshot to keep the shape stable).
+- `TrendChart` snapshot/render tests: no regression, gridline element present.
+
+---
+
+## Verification gate
+
+Before requesting code review, run:
+
+```
+bun run typecheck
+bun run test:fast
+bun run test:env
+bun run test:runtime:compat   # dist-sensitive check for the charts
+bun run build
+bun run test:smoke:dist
+```
+
+No docs-site changes are planned in this spec; if `docs-site/` ends up touched (e.g. screenshots), also run `bun run docs:test` and `bun run docs:build`.
+
+No config schema changes → `bun run test:config` and `bun run generate:config-example` are not required.
+
+## Risks and open questions
+
+- **MediaDetailView refresh**: `useMediaLibrary` may not expose a `refresh` function. If it doesn't, the simplest path is adding one; the alternative (keying a remount) works but is harder to test. Decide during implementation.
+- **Session bucket delete UX**: "Delete all N sessions in this group" is powerful. The copy must make it clear the underlying sessions are being removed, not just the grouping. Reuse `confirmBucketDelete` wording from existing confirm helpers if possible.
+- **Anki-deleted-cards hidden notice**: Showing a subtle "N cards hidden" footer is a call that can be made at PR review.
+- **Bucket delete helper**: `confirmBucketDelete` does not currently exist in `delete-confirm.ts`. Implementation either adds it or reuses `confirmDayGroupDelete` with bucket-specific wording — decide during the session-rollup commit.
+
+## Changelog entry
+
+User-visible PR → needs a fragment under `changes/*.md`. Suggested title:
+`Stats dashboard: collapsible series, session rollups, 365d trends, chart polish, episode delete.`

launcher/aniskip-metadata.ts

@@ -125,10 +125,7 @@ function titleOverlapScore(expectedTitle: string, candidateTitle: string): numbe
   if (!expected || !candidate) return 0;
 
   if (candidate.includes(expected)) return 120;
-  if (
-    candidate.split(' ').length >= 2 &&
-    ` ${expected} `.includes(` ${candidate} `)
-  ) {
+  if (candidate.split(' ').length >= 2 && ` ${expected} `.includes(` ${candidate} `)) {
     return 90;
   }
 

launcher/commands/playback-command.test.ts

@@ -58,6 +58,7 @@ function createContext(): LauncherCommandContext {
       jellyfinServer: '',
       jellyfinUsername: '',
       jellyfinPassword: '',
+      launchMode: 'normal',
     },
     scriptPath: '/tmp/subminer',
     scriptName: 'subminer',

launcher/config-domain-parsers.test.ts

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { parseLauncherYoutubeSubgenConfig } from './config/youtube-subgen-config.js';
 import { parseLauncherJellyfinConfig } from './config/jellyfin-config.js';
+import { parseLauncherMpvConfig } from './config/mpv-config.js';
 import { readExternalYomitanProfilePath } from './config.js';
 import {
   getPluginConfigCandidates,
@@ -80,6 +81,27 @@ test('parseLauncherJellyfinConfig omits legacy token and user id fields', () =>
   assert.equal('userId' in parsed, false);
 });
 
+test('parseLauncherMpvConfig reads launch mode preference', () => {
+  const parsed = parseLauncherMpvConfig({
+    mpv: {
+      launchMode: ' maximized ',
+      executablePath: 'ignored-here',
+    },
+  });
+
+  assert.equal(parsed.launchMode, 'maximized');
+});
+
+test('parseLauncherMpvConfig ignores invalid launch mode values', () => {
+  const parsed = parseLauncherMpvConfig({
+    mpv: {
+      launchMode: 'wide',
+    },
+  });
+
+  assert.equal(parsed.launchMode, undefined);
+});
+
 test('parsePluginRuntimeConfigContent reads socket path and startup gate options', () => {
   const parsed = parsePluginRuntimeConfigContent(`
 # comment

launcher/config.ts

@@ -2,6 +2,7 @@ import { fail } from './log.js';
 import type {
   Args,
   LauncherJellyfinConfig,
+  LauncherMpvConfig,
   LauncherYoutubeSubgenConfig,
   LogLevel,
   PluginRuntimeConfig,
@@ -13,6 +14,7 @@ import {
 } from './config/args-normalizer.js';
 import { parseCliPrograms, resolveTopLevelCommand } from './config/cli-parser-builder.js';
 import { parseLauncherJellyfinConfig } from './config/jellyfin-config.js';
+import { parseLauncherMpvConfig } from './config/mpv-config.js';
 import { readPluginRuntimeConfig as readPluginRuntimeConfigValue } from './config/plugin-runtime-config.js';
 import { readLauncherMainConfigObject } from './config/shared-config-reader.js';
 import { parseLauncherYoutubeSubgenConfig } from './config/youtube-subgen-config.js';
@@ -44,6 +46,12 @@ export function loadLauncherJellyfinConfig(): LauncherJellyfinConfig {
   return parseLauncherJellyfinConfig(root);
 }
 
+export function loadLauncherMpvConfig(): LauncherMpvConfig {
+  const root = readLauncherMainConfigObject();
+  if (!root) return {};
+  return parseLauncherMpvConfig(root);
+}
+
 export function hasLauncherExternalYomitanProfileConfig(): boolean {
   return readExternalYomitanProfilePath(readLauncherMainConfigObject()) !== null;
 }
@@ -56,9 +64,10 @@ export function parseArgs(
   argv: string[],
   scriptName: string,
   launcherConfig: LauncherYoutubeSubgenConfig,
+  launcherMpvConfig: LauncherMpvConfig = {},
 ): Args {
   const topLevelCommand = resolveTopLevelCommand(argv);
-  const parsed = createDefaultArgs(launcherConfig);
+  const parsed = createDefaultArgs(launcherConfig, launcherMpvConfig);
 
   if (topLevelCommand && (topLevelCommand.name === 'app' || topLevelCommand.name === 'bin')) {
     parsed.appPassthrough = true;

launcher/config/args-normalizer.ts

@@ -1,7 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fail } from '../log.js';
-import type { Args, Backend, LauncherYoutubeSubgenConfig, LogLevel } from '../types.js';
+import type {
+  Args,
+  Backend,
+  LauncherMpvConfig,
+  LauncherYoutubeSubgenConfig,
+  LogLevel,
+} from '../types.js';
 import {
   DEFAULT_JIMAKU_API_BASE_URL,
   DEFAULT_YOUTUBE_PRIMARY_SUB_LANGS,
@@ -83,7 +89,10 @@ function parseDictionaryTarget(value: string): string {
   return resolved;
 }
 
-export function createDefaultArgs(launcherConfig: LauncherYoutubeSubgenConfig): Args {
+export function createDefaultArgs(
+  launcherConfig: LauncherYoutubeSubgenConfig,
+  mpvConfig: LauncherMpvConfig = {},
+): Args {
   const configuredSecondaryLangs = uniqueNormalizedLangCodes(
     launcherConfig.secondarySubLanguages ?? [],
   );
@@ -148,6 +157,7 @@ export function createDefaultArgs(launcherConfig: LauncherYoutubeSubgenConfig):
     jellyfinServer: '',
     jellyfinUsername: '',
     jellyfinPassword: '',
+    launchMode: mpvConfig.launchMode ?? 'normal',
     youtubePrimarySubLangs: primarySubLangs,
     youtubeSecondarySubLangs: secondarySubLangs,
     youtubeAudioLangs,

launcher/config/mpv-config.ts

@@ -0,0 +1,12 @@
+import { parseMpvLaunchMode } from '../../src/shared/mpv-launch-mode.js';
+import type { LauncherMpvConfig } from '../types.js';
+
+export function parseLauncherMpvConfig(root: Record<string, unknown>): LauncherMpvConfig {
+  const mpvRaw = root.mpv;
+  if (!mpvRaw || typeof mpvRaw !== 'object') return {};
+  const mpv = mpvRaw as Record<string, unknown>;
+
+  return {
+    launchMode: parseMpvLaunchMode(mpv.launchMode),
+  };
+}

launcher/main.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import {
   loadLauncherJellyfinConfig,
+  loadLauncherMpvConfig,
   loadLauncherYoutubeSubgenConfig,
   parseArgs,
   readPluginRuntimeConfig,
@@ -52,7 +53,8 @@ async function main(): Promise<void> {
   const scriptPath = process.argv[1] || 'subminer';
   const scriptName = path.basename(scriptPath);
   const launcherConfig = loadLauncherYoutubeSubgenConfig();
-  const args = parseArgs(process.argv.slice(2), scriptName, launcherConfig);
+  const launcherMpvConfig = loadLauncherMpvConfig();
+  const args = parseArgs(process.argv.slice(2), scriptName, launcherConfig, launcherMpvConfig);
   const pluginRuntimeConfig = readPluginRuntimeConfig(args.logLevel);
   const appPath = findAppBinary(scriptPath);
 

launcher/mpv.test.ts

@@ -7,6 +7,9 @@ import net from 'node:net';
 import { EventEmitter } from 'node:events';
 import type { Args } from './types';
 import {
+  buildConfiguredMpvDefaultArgs,
+  buildMpvBackendArgs,
+  buildMpvEnv,
   cleanupPlaybackSession,
   detectBackend,
   findAppBinary,
@@ -125,6 +128,140 @@ test('detectBackend resolves windows on win32 auto mode', () => {
   });
 });
 
+test('buildMpvEnv forces X11 by dropping Wayland hints when backend resolves to x11', () => {
+  withPlatform('linux', () => {
+    const env = buildMpvEnv(makeArgs({ backend: 'x11' }), {
+      DISPLAY: ':1',
+      WAYLAND_DISPLAY: 'wayland-0',
+      XDG_SESSION_TYPE: 'wayland',
+      HYPRLAND_INSTANCE_SIGNATURE: 'hypr',
+      SWAYSOCK: '/tmp/sway.sock',
+    });
+
+    assert.equal(env.DISPLAY, ':1');
+    assert.equal(env.WAYLAND_DISPLAY, undefined);
+    assert.equal(env.XDG_SESSION_TYPE, 'x11');
+    assert.equal(env.HYPRLAND_INSTANCE_SIGNATURE, undefined);
+    assert.equal(env.SWAYSOCK, undefined);
+  });
+});
+
+test('buildMpvEnv auto mode falls back to X11 when no supported Wayland tracker backend is detected', () => {
+  withPlatform('linux', () => {
+    const env = buildMpvEnv(makeArgs({ backend: 'auto' }), {
+      DISPLAY: ':1',
+      WAYLAND_DISPLAY: 'wayland-0',
+      XDG_SESSION_TYPE: 'wayland',
+      XDG_CURRENT_DESKTOP: 'KDE',
+      XDG_SESSION_DESKTOP: 'plasma',
+    });
+
+    assert.equal(env.DISPLAY, ':1');
+    assert.equal(env.WAYLAND_DISPLAY, undefined);
+    assert.equal(env.XDG_SESSION_TYPE, 'x11');
+  });
+});
+
+test('buildMpvEnv preserves native Wayland env for supported Hyprland and Sway auto backends', () => {
+  withPlatform('linux', () => {
+    const hyprEnv = buildMpvEnv(makeArgs({ backend: 'auto' }), {
+      DISPLAY: ':1',
+      WAYLAND_DISPLAY: 'wayland-0',
+      XDG_SESSION_TYPE: 'wayland',
+      HYPRLAND_INSTANCE_SIGNATURE: 'hypr',
+    });
+    assert.equal(hyprEnv.WAYLAND_DISPLAY, 'wayland-0');
+    assert.equal(hyprEnv.XDG_SESSION_TYPE, 'wayland');
+
+    const swayEnv = buildMpvEnv(makeArgs({ backend: 'auto' }), {
+      DISPLAY: ':1',
+      WAYLAND_DISPLAY: 'wayland-0',
+      XDG_SESSION_TYPE: 'wayland',
+      SWAYSOCK: '/tmp/sway.sock',
+    });
+    assert.equal(swayEnv.WAYLAND_DISPLAY, 'wayland-0');
+    assert.equal(swayEnv.XDG_SESSION_TYPE, 'wayland');
+  });
+});
+
+test('buildMpvBackendArgs forces an explicit X11 renderer stack when backend resolves to x11', () => {
+  withPlatform('linux', () => {
+    assert.deepEqual(
+      buildMpvBackendArgs(makeArgs({ backend: 'x11' }), {
+        DISPLAY: ':1',
+        WAYLAND_DISPLAY: 'wayland-0',
+        XDG_SESSION_TYPE: 'wayland',
+      }),
+      ['--vo=gpu', '--gpu-api=opengl', '--gpu-context=x11egl,x11'],
+    );
+  });
+});
+
+test('buildMpvBackendArgs forces the same X11 renderer stack for unsupported Wayland auto fallback', () => {
+  withPlatform('linux', () => {
+    assert.deepEqual(
+      buildMpvBackendArgs(makeArgs({ backend: 'auto' }), {
+        DISPLAY: ':1',
+        WAYLAND_DISPLAY: 'wayland-0',
+        XDG_SESSION_TYPE: 'wayland',
+        XDG_CURRENT_DESKTOP: 'KDE',
+        XDG_SESSION_DESKTOP: 'plasma',
+      }),
+      ['--vo=gpu', '--gpu-api=opengl', '--gpu-context=x11egl,x11'],
+    );
+  });
+});
+
+test('buildMpvBackendArgs keeps supported Hyprland and Sway auto backends unchanged', () => {
+  withPlatform('linux', () => {
+    assert.deepEqual(
+      buildMpvBackendArgs(makeArgs({ backend: 'auto' }), {
+        DISPLAY: ':1',
+        WAYLAND_DISPLAY: 'wayland-0',
+        XDG_SESSION_TYPE: 'wayland',
+        HYPRLAND_INSTANCE_SIGNATURE: 'hypr',
+      }),
+      [],
+    );
+    assert.deepEqual(
+      buildMpvBackendArgs(makeArgs({ backend: 'auto' }), {
+        DISPLAY: ':1',
+        WAYLAND_DISPLAY: 'wayland-0',
+        XDG_SESSION_TYPE: 'wayland',
+        SWAYSOCK: '/tmp/sway.sock',
+      }),
+      [],
+    );
+  });
+});
+
+test('buildConfiguredMpvDefaultArgs appends maximized launch mode to configured defaults', () => {
+  withPlatform('linux', () => {
+    assert.deepEqual(
+      buildConfiguredMpvDefaultArgs(makeArgs({ launchMode: 'maximized' }), {
+        DISPLAY: ':1',
+        WAYLAND_DISPLAY: 'wayland-0',
+        XDG_SESSION_TYPE: 'wayland',
+        XDG_CURRENT_DESKTOP: 'KDE',
+        XDG_SESSION_DESKTOP: 'plasma',
+      }),
+      [
+        '--sub-auto=fuzzy',
+        '--sub-file-paths=.;subs;subtitles',
+        '--sid=auto',
+        '--secondary-sid=auto',
+        '--secondary-sub-visibility=no',
+        '--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
+        '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
+        '--vo=gpu',
+        '--gpu-api=opengl',
+        '--gpu-context=x11egl,x11',
+        '--window-maximized=yes',
+      ],
+    );
+  });
+});
+
 test('launchTexthookerOnly exits non-zero when app binary cannot be spawned', () => {
   const error = withProcessExitIntercept(() => {
     launchTexthookerOnly('/definitely-missing-subminer-binary', makeArgs());
@@ -292,6 +429,7 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
     jellyfinServer: '',
     jellyfinUsername: '',
     jellyfinPassword: '',
+    launchMode: 'normal',
     ...overrides,
   };
 }
@@ -485,6 +623,40 @@ function withAccessSyncStub(
   }
 }
 
+function withExistsAndStatSyncStubs(
+  options: {
+    existingPaths?: string[];
+    directoryPaths?: string[];
+  },
+  run: () => void,
+): void {
+  const existingPaths = new Set(options.existingPaths ?? []);
+  const directoryPaths = new Set(options.directoryPaths ?? []);
+  const originalExistsSync = fs.existsSync;
+  const originalStatSync = fs.statSync;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (fs as any).existsSync = (filePath: string): boolean =>
+      existingPaths.has(filePath) || directoryPaths.has(filePath);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (fs as any).statSync = (filePath: string) => {
+      if (directoryPaths.has(filePath)) {
+        return { isDirectory: () => true };
+      }
+      if (existingPaths.has(filePath)) {
+        return { isDirectory: () => false };
+      }
+      throw Object.assign(new Error(`ENOENT: ${filePath}`), { code: 'ENOENT' });
+    };
+    run();
+  } finally {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (fs as any).existsSync = originalExistsSync;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (fs as any).statSync = originalStatSync;
+  }
+}
+
 function withRealpathSyncStub(resolvePath: (filePath: string) => string, run: () => void): void {
   const originalRealpathSync = fs.realpathSync;
   try {
@@ -497,6 +669,75 @@ function withRealpathSyncStub(resolvePath: (filePath: string) => string, run: ()
   }
 }
 
+function listRepoRootWindowsTempArtifacts(): string[] {
+  return fs
+    .readdirSync(process.cwd())
+    .filter((entry) => /^\\tmp\\subminer-test-win-/.test(entry))
+    .sort();
+}
+
+function runFindAppBinaryWindowsPathCase(): void {
+  const baseDir = 'C:\\Users\\tester\\subminer-test-win-path';
+  const originalHomedir = os.homedir;
+  const originalPath = process.env.PATH;
+  try {
+    os.homedir = () => baseDir;
+    const binDir = path.win32.join(baseDir, 'bin');
+    const wrapperPath = path.win32.join(binDir, 'SubMiner.exe');
+    process.env.PATH = `${binDir}${path.win32.delimiter}${originalPath ?? ''}`;
+
+    withFindAppBinaryPlatformSandbox('win32', (pathModule) => {
+      withAccessSyncStub(
+        (filePath) => filePath === wrapperPath,
+        () => {
+          const result = findAppBinary(
+            pathModule.join(baseDir, 'launcher', 'SubMiner.exe'),
+            pathModule,
+          );
+          assert.equal(result, wrapperPath);
+        },
+      );
+    });
+  } finally {
+    os.homedir = originalHomedir;
+    process.env.PATH = originalPath;
+  }
+}
+
+function runFindAppBinaryWindowsInstallDirCase(): void {
+  const baseDir = 'C:\\Users\\tester\\subminer-test-win-dir';
+  const originalHomedir = os.homedir;
+  const originalSubminerBinaryPath = process.env.SUBMINER_BINARY_PATH;
+  try {
+    os.homedir = () => baseDir;
+    const installDir = path.win32.join(baseDir, 'Programs', 'SubMiner');
+    const appExe = path.win32.join(installDir, 'SubMiner.exe');
+    process.env.SUBMINER_BINARY_PATH = installDir;
+
+    withPlatform('win32', () => {
+      withExistsAndStatSyncStubs({ existingPaths: [appExe], directoryPaths: [installDir] }, () => {
+        withAccessSyncStub(
+          (filePath) => filePath === appExe,
+          () => {
+            const result = findAppBinary(
+              path.win32.join(baseDir, 'launcher', 'SubMiner.exe'),
+              path.win32,
+            );
+            assert.equal(result, appExe);
+          },
+        );
+      });
+    });
+  } finally {
+    os.homedir = originalHomedir;
+    if (originalSubminerBinaryPath === undefined) {
+      delete process.env.SUBMINER_BINARY_PATH;
+    } else {
+      process.env.SUBMINER_BINARY_PATH = originalSubminerBinaryPath;
+    }
+  }
+}
+
 test(
   'findAppBinary resolves ~/.local/bin/SubMiner.AppImage when it exists',
   { concurrency: false },
@@ -657,71 +898,31 @@ test('findAppBinary resolves Windows install paths when present', { concurrency:
   }
 });
 
-test('findAppBinary resolves SubMiner.exe on PATH on Windows', { concurrency: false }, () => {
-  const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-test-win-path-'));
-  const originalHomedir = os.homedir;
-  const originalPath = process.env.PATH;
-  try {
-    os.homedir = () => baseDir;
-    const binDir = path.win32.join(baseDir, 'bin');
-    const wrapperPath = path.win32.join(binDir, 'SubMiner.exe');
-    makeExecutable(wrapperPath);
-    process.env.PATH = `${binDir}${path.win32.delimiter}${originalPath ?? ''}`;
+test(
+  'findAppBinary Windows cases do not leak backslash temp artifacts on POSIX',
+  { concurrency: false },
+  () => {
+    if (path.sep === '\\') {
+      return;
+    }
 
-    withFindAppBinaryPlatformSandbox('win32', (pathModule) => {
-      withAccessSyncStub(
-        (filePath) => filePath === wrapperPath,
-        () => {
-          const result = findAppBinary(
-            pathModule.join(baseDir, 'launcher', 'SubMiner.exe'),
-            pathModule,
-          );
-          assert.equal(result, wrapperPath);
-        },
-      );
-    });
-  } finally {
-    os.homedir = originalHomedir;
-    process.env.PATH = originalPath;
-    fs.rmSync(baseDir, { recursive: true, force: true });
-  }
+    const before = listRepoRootWindowsTempArtifacts();
+    runFindAppBinaryWindowsPathCase();
+    runFindAppBinaryWindowsInstallDirCase();
+    const after = listRepoRootWindowsTempArtifacts();
+
+    assert.deepEqual(after, before);
+  },
+);
+
+test('findAppBinary resolves SubMiner.exe on PATH on Windows', { concurrency: false }, () => {
+  runFindAppBinaryWindowsPathCase();
 });
 
 test(
   'findAppBinary resolves a Windows install directory to SubMiner.exe',
   { concurrency: false },
   () => {
-    const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-test-win-dir-'));
-    const originalHomedir = os.homedir;
-    const originalSubminerBinaryPath = process.env.SUBMINER_BINARY_PATH;
-    try {
-      os.homedir = () => baseDir;
-      const installDir = path.win32.join(baseDir, 'Programs', 'SubMiner');
-      const appExe = path.win32.join(installDir, 'SubMiner.exe');
-      process.env.SUBMINER_BINARY_PATH = installDir;
-      fs.mkdirSync(installDir, { recursive: true });
-      fs.writeFileSync(appExe, '#!/bin/sh\nexit 0\n');
-      fs.chmodSync(appExe, 0o755);
-
-      const originalPlatform = process.platform;
-      try {
-        Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
-        const result = findAppBinary(
-          path.win32.join(baseDir, 'launcher', 'SubMiner.exe'),
-          path.win32,
-        );
-        assert.equal(result, appExe);
-      } finally {
-        Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
-      }
-    } finally {
-      os.homedir = originalHomedir;
-      if (originalSubminerBinaryPath === undefined) {
-        delete process.env.SUBMINER_BINARY_PATH;
-      } else {
-        process.env.SUBMINER_BINARY_PATH = originalSubminerBinaryPath;
-      }
-      fs.rmSync(baseDir, { recursive: true, force: true });
-    }
+    runFindAppBinaryWindowsInstallDirCase();
   },
 );

launcher/mpv.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import net from 'node:net';
 import { spawn, spawnSync } from 'node:child_process';
+import { buildMpvLaunchModeArgs } from '../src/shared/mpv-launch-mode.js';
 import type { LogLevel, Backend, Args, MpvTrack } from './types.js';
 import { DEFAULT_MPV_SUBMINER_ARGS, DEFAULT_YOUTUBE_YTDL_FORMAT } from './types.js';
 import { appendToAppLog, getAppLogPath, log, fail, getMpvLogPath } from './log.js';
@@ -225,27 +226,62 @@ export function makeTempDir(prefix: string): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
 }
 
-export function detectBackend(backend: Backend): Exclude<Backend, 'auto'> {
+export function detectBackend(
+  backend: Backend,
+  env: NodeJS.ProcessEnv = process.env,
+): Exclude<Backend, 'auto'> {
   if (backend !== 'auto') return backend;
   if (process.platform === 'win32') return 'windows';
   if (process.platform === 'darwin') return 'macos';
-  const xdgCurrentDesktop = (process.env.XDG_CURRENT_DESKTOP || '').toLowerCase();
-  const xdgSessionDesktop = (process.env.XDG_SESSION_DESKTOP || '').toLowerCase();
-  const xdgSessionType = (process.env.XDG_SESSION_TYPE || '').toLowerCase();
-  const hasWayland = Boolean(process.env.WAYLAND_DISPLAY) || xdgSessionType === 'wayland';
+  const linuxDesktopEnv = getLinuxDesktopEnv(env);
 
   if (
-    process.env.HYPRLAND_INSTANCE_SIGNATURE ||
-    xdgCurrentDesktop.includes('hyprland') ||
-    xdgSessionDesktop.includes('hyprland')
+    env.HYPRLAND_INSTANCE_SIGNATURE ||
+    linuxDesktopEnv.xdgCurrentDesktop.includes('hyprland') ||
+    linuxDesktopEnv.xdgSessionDesktop.includes('hyprland')
   ) {
     return 'hyprland';
   }
-  if (hasWayland && commandExists('hyprctl')) return 'hyprland';
-  if (process.env.DISPLAY) return 'x11';
+  if (linuxDesktopEnv.hasWayland && commandExists('hyprctl')) return 'hyprland';
+  if (env.DISPLAY) return 'x11';
   fail('Could not detect display backend');
 }
 
+type LinuxDesktopEnv = {
+  xdgCurrentDesktop: string;
+  xdgSessionDesktop: string;
+  hasWayland: boolean;
+};
+
+function getLinuxDesktopEnv(env: NodeJS.ProcessEnv): LinuxDesktopEnv {
+  const xdgCurrentDesktop = (env.XDG_CURRENT_DESKTOP || '').toLowerCase();
+  const xdgSessionDesktop = (env.XDG_SESSION_DESKTOP || '').toLowerCase();
+  const xdgSessionType = (env.XDG_SESSION_TYPE || '').toLowerCase();
+  return {
+    xdgCurrentDesktop,
+    xdgSessionDesktop,
+    hasWayland: Boolean(env.WAYLAND_DISPLAY) || xdgSessionType === 'wayland',
+  };
+}
+
+function shouldForceX11MpvBackend(args: Pick<Args, 'backend'>, env: NodeJS.ProcessEnv): boolean {
+  if (process.platform !== 'linux' || !env.DISPLAY?.trim()) {
+    return false;
+  }
+
+  const linuxDesktopEnv = getLinuxDesktopEnv(env);
+  const supportedWaylandBackend =
+    Boolean(env.HYPRLAND_INSTANCE_SIGNATURE || env.SWAYSOCK) ||
+    linuxDesktopEnv.xdgCurrentDesktop.includes('hyprland') ||
+    linuxDesktopEnv.xdgCurrentDesktop.includes('sway') ||
+    linuxDesktopEnv.xdgSessionDesktop.includes('hyprland') ||
+    linuxDesktopEnv.xdgSessionDesktop.includes('sway');
+  return (
+    args.backend === 'x11' ||
+    (args.backend === 'auto' && linuxDesktopEnv.hasWayland && !supportedWaylandBackend)
+  );
+}
+
 function resolveAppBinaryCandidate(candidate: string, pathModule: PathModule = path): string {
   const direct = resolveBinaryPathCandidate(candidate);
   if (!direct) return '';
@@ -635,8 +671,7 @@ export async function startMpv(
   }
 
   const mpvArgs: string[] = [];
-  if (args.profile) mpvArgs.push(`--profile=${args.profile}`);
-  mpvArgs.push(...DEFAULT_MPV_SUBMINER_ARGS);
+  mpvArgs.push(...buildConfiguredMpvDefaultArgs(args));
   if (targetKind === 'url' && isYoutubeTarget(target)) {
     log('info', args.logLevel, 'Applying URL playback options');
     mpvArgs.push('--ytdl=yes');
@@ -664,7 +699,6 @@ export async function startMpv(
   if (args.mpvArgs) {
     mpvArgs.push(...parseMpvArgString(args.mpvArgs));
   }
-
   if (preloadedSubtitles?.primaryPath) {
     mpvArgs.push(`--sub-file=${preloadedSubtitles.primaryPath}`);
   }
@@ -712,7 +746,10 @@ export async function startMpv(
   const mpvTarget = resolveCommandInvocation('mpv', mpvArgs, {
     normalizeWindowsShellArgs: false,
   });
-  state.mpvProc = spawn(mpvTarget.command, mpvTarget.args, { stdio: 'inherit' });
+  state.mpvProc = spawn(mpvTarget.command, mpvTarget.args, {
+    stdio: 'inherit',
+    env: buildMpvEnv(args),
+  });
 }
 
 async function waitForOverlayStartCommandSettled(
@@ -889,9 +926,9 @@ function stopManagedOverlayApp(args: Args): void {
   }
 }
 
-function buildAppEnv(): NodeJS.ProcessEnv {
+function buildAppEnv(baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   const env: Record<string, string | undefined> = {
-    ...process.env,
+    ...baseEnv,
     SUBMINER_APP_LOG: getAppLogPath(),
     SUBMINER_MPV_LOG: getMpvLogPath(),
   };
@@ -911,6 +948,44 @@ function buildAppEnv(): NodeJS.ProcessEnv {
   return env;
 }
 
+export function buildMpvEnv(
+  args: Pick<Args, 'backend'>,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const env = buildAppEnv(baseEnv);
+  if (!shouldForceX11MpvBackend(args, env)) {
+    return env;
+  }
+
+  delete env.WAYLAND_DISPLAY;
+  delete env.HYPRLAND_INSTANCE_SIGNATURE;
+  delete env.SWAYSOCK;
+  env.XDG_SESSION_TYPE = 'x11';
+  return env;
+}
+
+export function buildMpvBackendArgs(
+  args: Pick<Args, 'backend'>,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): string[] {
+  if (!shouldForceX11MpvBackend(args, baseEnv)) {
+    return [];
+  }
+  return ['--vo=gpu', '--gpu-api=opengl', '--gpu-context=x11egl,x11'];
+}
+
+export function buildConfiguredMpvDefaultArgs(
+  args: Pick<Args, 'profile' | 'backend' | 'launchMode'>,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): string[] {
+  const mpvArgs: string[] = [];
+  if (args.profile) mpvArgs.push(`--profile=${args.profile}`);
+  mpvArgs.push(...DEFAULT_MPV_SUBMINER_ARGS);
+  mpvArgs.push(...buildMpvBackendArgs(args, baseEnv));
+  mpvArgs.push(...buildMpvLaunchModeArgs(args.launchMode));
+  return mpvArgs;
+}
+
 function appendCapturedAppOutput(kind: 'STDOUT' | 'STDERR', chunk: string): void {
   const normalized = chunk.replace(/\r\n/g, '\n');
   for (const line of normalized.split('\n')) {
@@ -1141,9 +1216,7 @@ export function launchMpvIdleDetached(
       // ignore
     }
 
-    const mpvArgs: string[] = [];
-    if (args.profile) mpvArgs.push(`--profile=${args.profile}`);
-    mpvArgs.push(...DEFAULT_MPV_SUBMINER_ARGS);
+    const mpvArgs: string[] = buildConfiguredMpvDefaultArgs(args);
     if (args.mpvArgs) {
       mpvArgs.push(...parseMpvArgString(args.mpvArgs));
     }
@@ -1159,6 +1232,7 @@ export function launchMpvIdleDetached(
     const proc = spawn(mpvTarget.command, mpvTarget.args, {
       stdio: 'ignore',
       detached: true,
+      env: buildMpvEnv(args),
     });
     if (typeof proc.pid === 'number' && proc.pid > 0) {
       trackDetachedMpvPid(proc.pid);

launcher/parse-args.test.ts

@@ -85,6 +85,12 @@ test('parseArgs maps mpv idle action', () => {
   assert.equal(parsed.mpvStatus, false);
 });
 
+test('parseArgs applies configured mpv launch mode default', () => {
+  const parsed = parseArgs([], 'subminer', {}, { launchMode: 'maximized' });
+
+  assert.equal(parsed.launchMode, 'maximized');
+});
+
 test('parseArgs maps dictionary command and log-level override', () => {
   const parsed = parseArgs(['dictionary', '.', '--log-level', 'debug'], 'subminer', {});
 

launcher/types.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import os from 'node:os';
+import type { MpvLaunchMode } from '../src/types/config.js';
 import { resolveDefaultLogFilePath } from '../src/shared/log-files.js';
 export { VIDEO_EXTENSIONS } from '../src/shared/video-extensions.js';
 
@@ -140,6 +141,7 @@ export interface Args {
   jellyfinServer: string;
   jellyfinUsername: string;
   jellyfinPassword: string;
+  launchMode: MpvLaunchMode;
 }
 
 export interface LauncherYoutubeSubgenConfig {
@@ -167,6 +169,10 @@ export interface LauncherJellyfinConfig {
   iconCacheDir?: string;
 }
 
+export interface LauncherMpvConfig {
+  launchMode?: MpvLaunchMode;
+}
+
 export interface PluginRuntimeConfig {
   socketPath: string;
   autoStart: boolean;

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",
@@ -20,8 +20,9 @@
     "dev:stats": "cd stats && bun run dev",
     "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:launcher && bun run build:assets",
     "build:renderer": "esbuild src/renderer/renderer.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/renderer/renderer.js --sourcemap",
-    "changelog:build": "bun run scripts/build-changelog.ts build",
+    "changelog:build": "bun run scripts/build-changelog.ts build && bun run changelog:docs",
     "changelog:check": "bun run scripts/build-changelog.ts check",
+    "changelog:docs": "bun run scripts/build-changelog.ts docs",
     "changelog:lint": "bun run scripts/build-changelog.ts lint",
     "changelog:pr-check": "bun run scripts/build-changelog.ts pr-check",
     "changelog:release-notes": "bun run scripts/build-changelog.ts release-notes",
@@ -68,7 +69,7 @@
     "test:launcher": "bun run test:launcher:src",
     "test:core": "bun run test:core:src",
     "test:subtitle": "bun run test:subtitle:src",
-    "test:fast": "bun run test:config:src && bun run test:core:src && bun run test:docs:kb && bun test src/main-entry-runtime.test.ts src/anki-integration.test.ts src/anki-integration/anki-connect-proxy.test.ts src/anki-integration/field-grouping-workflow.test.ts src/anki-integration/field-grouping.test.ts src/anki-integration/field-grouping-merge.test.ts src/release-workflow.test.ts src/ci-workflow.test.ts scripts/build-changelog.test.ts scripts/mkv-to-readme-video.test.ts scripts/run-coverage-lane.test.ts scripts/update-aur-package.test.ts && bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts && bun run tsc && bun test dist/main/runtime/registry.test.js",
+    "test:fast": "bun run test:config:src && bun run test:core:src && bun run test:docs:kb && bun test src/main-entry-runtime.test.ts src/anki-integration.test.ts src/anki-integration/anki-connect-proxy.test.ts src/anki-integration/field-grouping-workflow.test.ts src/anki-integration/field-grouping.test.ts src/anki-integration/field-grouping-merge.test.ts src/release-workflow.test.ts src/ci-workflow.test.ts scripts/build-changelog.test.ts scripts/electron-builder-after-pack.test.ts scripts/mkv-to-readme-video.test.ts scripts/run-coverage-lane.test.ts scripts/update-aur-package.test.ts && bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts && bun run tsc && bun test dist/main/runtime/registry.test.js",
     "generate:config-example": "bun run src/generate-config-example.ts",
     "verify:config-example": "bun run src/verify-config-example.ts",
     "start": "bun run build && electron . --start",
@@ -128,6 +129,7 @@
     "productName": "SubMiner",
     "executableName": "SubMiner",
     "artifactName": "SubMiner-${version}.${ext}",
+    "afterPack": "scripts/electron-builder-after-pack.cjs",
     "icon": "assets/SubMiner-square.png",
     "directories": {
       "output": "release"

scripts/build-changelog.test.ts

@@ -197,6 +197,49 @@ test('verifyChangelogReadyForRelease rejects explicit release versions that do n
   }
 });
 
+test('writeChangelogArtifacts renders breaking changes section above type sections', async () => {
+  const { writeChangelogArtifacts } = await loadModule();
+  const workspace = createWorkspace('breaking-changes');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(projectRoot, { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(path.join(projectRoot, 'CHANGELOG.md'), '# Changelog\n', 'utf8');
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: changed', 'area: config', 'breaking: true', '', '- Renamed `foo` to `bar`.'].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '002.md'),
+    ['type: fixed', 'area: overlay', '', '- Fixed subtitle rendering.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    writeChangelogArtifacts({
+      cwd: projectRoot,
+      version: '0.5.0',
+      date: '2026-04-06',
+    });
+
+    const changelog = fs.readFileSync(path.join(projectRoot, 'CHANGELOG.md'), 'utf8');
+    const breakingIndex = changelog.indexOf('### Breaking Changes');
+    const changedIndex = changelog.indexOf('### Changed');
+    const fixedIndex = changelog.indexOf('### Fixed');
+
+    assert.notEqual(breakingIndex, -1, 'Breaking Changes section should exist');
+    assert.notEqual(changedIndex, -1, 'Changed section should exist');
+    assert.notEqual(fixedIndex, -1, 'Fixed section should exist');
+    assert.ok(breakingIndex < changedIndex, 'Breaking Changes should appear before Changed');
+    assert.ok(changedIndex < fixedIndex, 'Changed should appear before Fixed');
+    assert.match(changelog, /### Breaking Changes\n- Config: Renamed `foo` to `bar`\./);
+    assert.match(changelog, /### Changed\n- Config: Renamed `foo` to `bar`\./);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
 test('verifyChangelogFragments rejects invalid metadata', async () => {
   const { verifyChangelogFragments } = await loadModule();
   const workspace = createWorkspace('lint-invalid');

scripts/build-changelog.ts

@@ -23,6 +23,7 @@ type FragmentType = 'added' | 'changed' | 'fixed' | 'docs' | 'internal';
 
 type ChangeFragment = {
   area: string;
+  breaking: boolean;
   bullets: string[];
   path: string;
   type: FragmentType;
@@ -144,6 +145,7 @@ function parseFragmentMetadata(
 ): {
   area: string;
   body: string;
+  breaking: boolean;
   type: FragmentType;
 } {
   const lines = content.split(/\r?\n/);
@@ -186,9 +188,12 @@ function parseFragmentMetadata(
     throw new Error(`${fragmentPath} must include at least one changelog bullet.`);
   }
 
+  const breaking = metadata.get('breaking')?.toLowerCase() === 'true';
+
   return {
     area,
     body,
+    breaking,
     type: type as FragmentType,
   };
 }
@@ -199,6 +204,7 @@ function readChangeFragments(cwd: string, deps?: ChangelogFsDeps): ChangeFragmen
     const parsed = parseFragmentMetadata(readFileSync(fragmentPath, 'utf8'), fragmentPath);
     return {
       area: parsed.area,
+      breaking: parsed.breaking,
       bullets: normalizeFragmentBullets(parsed.body),
       path: fragmentPath,
       type: parsed.type,
@@ -219,10 +225,22 @@ function renderFragmentBullet(fragment: ChangeFragment, bullet: string): string
 }
 
 function renderGroupedChanges(fragments: ChangeFragment[]): string {
-  const sections = CHANGE_TYPES.flatMap((type) => {
+  const sections: string[] = [];
+
+  const breakingFragments = fragments.filter((fragment) => fragment.breaking);
+  if (breakingFragments.length > 0) {
+    const bullets = breakingFragments
+      .flatMap((fragment) =>
+        fragment.bullets.map((bullet) => renderFragmentBullet(fragment, bullet)),
+      )
+      .join('\n');
+    sections.push(`### Breaking Changes\n${bullets}`);
+  }
+
+  for (const type of CHANGE_TYPES) {
     const typeFragments = fragments.filter((fragment) => fragment.type === type);
     if (typeFragments.length === 0) {
-      return [];
+      continue;
     }
 
     const bullets = typeFragments
@@ -230,8 +248,8 @@ function renderGroupedChanges(fragments: ChangeFragment[]): string {
         fragment.bullets.map((bullet) => renderFragmentBullet(fragment, bullet)),
       )
       .join('\n');
-    return [`### ${CHANGE_TYPE_HEADINGS[type]}\n${bullets}`];
-  });
+    sections.push(`### ${CHANGE_TYPE_HEADINGS[type]}\n${bullets}`);
+  }
 
   return sections.join('\n\n');
 }
@@ -487,6 +505,99 @@ function resolveChangedPathsFromGit(
     .filter((entry) => entry.path);
 }
 
+const DOCS_CHANGELOG_PATH = path.join('docs-site', 'changelog.md');
+
+type VersionSection = {
+  version: string;
+  date: string;
+  minor: string;
+  body: string;
+};
+
+function parseVersionSections(changelog: string): VersionSection[] {
+  const sectionPattern = /^## v(\d+\.\d+\.\d+) \((\d{4}-\d{2}-\d{2})\)$/gm;
+  const sections: VersionSection[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = sectionPattern.exec(changelog)) !== null) {
+    const version = match[1]!;
+    const date = match[2]!;
+    const minor = version.replace(/\.\d+$/, '');
+    const headingEnd = match.index + match[0].length;
+    sections.push({ version, date, minor, body: '' });
+
+    if (sections.length > 1) {
+      const prev = sections[sections.length - 2]!;
+      prev.body = changelog.slice(prev.body as unknown as number, match.index).trim();
+    }
+    (sections[sections.length - 1] as { body: unknown }).body = headingEnd;
+  }
+
+  if (sections.length > 0) {
+    const last = sections[sections.length - 1]!;
+    last.body = changelog.slice(last.body as unknown as number).trim();
+  }
+
+  return sections;
+}
+
+export function generateDocsChangelog(options?: Pick<ChangelogOptions, 'cwd' | 'deps'>): string {
+  const cwd = options?.cwd ?? process.cwd();
+  const readFileSync = options?.deps?.readFileSync ?? fs.readFileSync;
+  const writeFileSync = options?.deps?.writeFileSync ?? fs.writeFileSync;
+  const log = options?.deps?.log ?? console.log;
+
+  const changelogPath = path.join(cwd, 'CHANGELOG.md');
+  const changelog = readFileSync(changelogPath, 'utf8');
+  const sections = parseVersionSections(changelog);
+
+  if (sections.length === 0) {
+    throw new Error('No version sections found in CHANGELOG.md');
+  }
+
+  const currentMinor = sections[0]!.minor;
+  const currentSections = sections.filter((s) => s.minor === currentMinor);
+  const olderSections = sections.filter((s) => s.minor !== currentMinor);
+
+  const lines: string[] = ['# Changelog', ''];
+
+  for (const section of currentSections) {
+    const body = section.body.replace(/^### (.+)$/gm, '**$1**');
+    lines.push(`## v${section.version} (${section.date})`, '', body, '');
+  }
+
+  if (olderSections.length > 0) {
+    lines.push('## Previous Versions', '');
+
+    const minorGroups = new Map<string, VersionSection[]>();
+    for (const section of olderSections) {
+      const group = minorGroups.get(section.minor) ?? [];
+      group.push(section);
+      minorGroups.set(section.minor, group);
+    }
+
+    for (const [minor, group] of minorGroups) {
+      lines.push('<details>', `<summary>v${minor}.x</summary>`, '');
+      for (const section of group) {
+        const htmlBody = section.body.replace(/^### (.+)$/gm, '**$1**');
+        lines.push(`<h2>v${section.version} (${section.date})</h2>`, '', htmlBody, '');
+      }
+      lines.push('</details>', '');
+    }
+  }
+
+  const output =
+    lines
+      .join('\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd() + '\n';
+  const outputPath = path.join(cwd, DOCS_CHANGELOG_PATH);
+  writeFileSync(outputPath, output, 'utf8');
+  log(`Generated ${outputPath}`);
+
+  return outputPath;
+}
+
 export function writeReleaseNotesForVersion(options?: ChangelogOptions): string {
   const cwd = options?.cwd ?? process.cwd();
   const readFileSync = options?.deps?.readFileSync ?? fs.readFileSync;
@@ -599,6 +710,11 @@ function main(): void {
     return;
   }
 
+  if (command === 'docs') {
+    generateDocsChangelog(options);
+    return;
+  }
+
   throw new Error(`Unknown changelog command: ${command}`);
 }
 

scripts/electron-builder-after-pack.cjs

@@ -0,0 +1,46 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const LINUX_FFMPEG_LIBRARY = 'libffmpeg.so';
+
+async function stageLinuxAppImageSharedLibrary(
+  context,
+  deps = {
+    access: (filePath) => fs.access(filePath),
+    mkdir: (dirPath) => fs.mkdir(dirPath, { recursive: true }),
+    copyFile: (from, to) => fs.copyFile(from, to),
+  },
+) {
+  if (context.electronPlatformName !== 'linux') return false;
+
+  const sourceLibraryPath = path.join(context.appOutDir, LINUX_FFMPEG_LIBRARY);
+
+  try {
+    await deps.access(sourceLibraryPath);
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      throw new Error(
+        `Linux packaging requires ${LINUX_FFMPEG_LIBRARY} at ${sourceLibraryPath} so AppImage child processes can resolve it.`,
+      );
+    }
+    throw error;
+  }
+
+  const targetLibraryDir = path.join(context.appOutDir, 'usr', 'lib');
+  const targetLibraryPath = path.join(targetLibraryDir, LINUX_FFMPEG_LIBRARY);
+
+  await deps.mkdir(targetLibraryDir);
+  await deps.copyFile(sourceLibraryPath, targetLibraryPath);
+
+  return true;
+}
+
+async function afterPack(context) {
+  await stageLinuxAppImageSharedLibrary(context);
+}
+
+module.exports = {
+  LINUX_FFMPEG_LIBRARY,
+  stageLinuxAppImageSharedLibrary,
+  default: afterPack,
+};

scripts/electron-builder-after-pack.test.ts

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+const {
+  LINUX_FFMPEG_LIBRARY,
+  default: afterPack,
+  stageLinuxAppImageSharedLibrary,
+} = require('./electron-builder-after-pack.cjs') as {
+  LINUX_FFMPEG_LIBRARY: string;
+  default: (context: { appOutDir: string; electronPlatformName: string }) => Promise<void>;
+  stageLinuxAppImageSharedLibrary: (context: {
+    appOutDir: string;
+    electronPlatformName: string;
+  }) => Promise<boolean>;
+};
+
+function createWorkspace(name: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `${name}-`));
+}
+
+test('stageLinuxAppImageSharedLibrary copies libffmpeg.so into usr/lib for Linux packaging', async () => {
+  const workspace = createWorkspace('subminer-after-pack-linux');
+  const appOutDir = path.join(workspace, 'SubMiner-linux-x64');
+  const sourceLibraryPath = path.join(appOutDir, LINUX_FFMPEG_LIBRARY);
+  const targetLibraryPath = path.join(appOutDir, 'usr', 'lib', LINUX_FFMPEG_LIBRARY);
+
+  fs.mkdirSync(appOutDir, { recursive: true });
+  fs.writeFileSync(sourceLibraryPath, 'bundled ffmpeg', 'utf8');
+
+  try {
+    const staged = await stageLinuxAppImageSharedLibrary({
+      appOutDir,
+      electronPlatformName: 'linux',
+    });
+
+    assert.equal(staged, true);
+    assert.equal(fs.readFileSync(targetLibraryPath, 'utf8'), 'bundled ffmpeg');
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('stageLinuxAppImageSharedLibrary skips non-Linux packaging contexts', async () => {
+  const workspace = createWorkspace('subminer-after-pack-non-linux');
+  const appOutDir = path.join(workspace, 'SubMiner-darwin-arm64');
+  const sourceLibraryPath = path.join(appOutDir, LINUX_FFMPEG_LIBRARY);
+  const targetLibraryPath = path.join(appOutDir, 'usr', 'lib', LINUX_FFMPEG_LIBRARY);
+
+  fs.mkdirSync(appOutDir, { recursive: true });
+  fs.writeFileSync(sourceLibraryPath, 'bundled ffmpeg', 'utf8');
+
+  try {
+    const staged = await stageLinuxAppImageSharedLibrary({
+      appOutDir,
+      electronPlatformName: 'darwin',
+    });
+
+    assert.equal(staged, false);
+    assert.equal(fs.existsSync(targetLibraryPath), false);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('stageLinuxAppImageSharedLibrary throws when Linux packaging is missing libffmpeg.so', async () => {
+  const workspace = createWorkspace('subminer-after-pack-missing-library');
+  const appOutDir = path.join(workspace, 'SubMiner-linux-x64');
+
+  fs.mkdirSync(appOutDir, { recursive: true });
+
+  try {
+    await assert.rejects(
+      stageLinuxAppImageSharedLibrary({
+        appOutDir,
+        electronPlatformName: 'linux',
+      }),
+      new RegExp(`Linux packaging requires ${LINUX_FFMPEG_LIBRARY} at .*${LINUX_FFMPEG_LIBRARY}`),
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('afterPack propagates Linux staging failures', async () => {
+  const workspace = createWorkspace('subminer-after-pack-propagates-linux-failure');
+  const appOutDir = path.join(workspace, 'SubMiner-linux-x64');
+
+  fs.mkdirSync(appOutDir, { recursive: true });
+
+  try {
+    await assert.rejects(
+      afterPack({
+        appOutDir,
+        electronPlatformName: 'linux',
+      }),
+      /Linux packaging requires libffmpeg\.so/,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});

src/config/config.test.ts

@@ -2125,10 +2125,7 @@ test('template generator includes known keys', () => {
     /"dpadFallback": "horizontal",? \/\/ Optional D-pad fallback used when this analog controller action should also read D-pad input\. Values: none \| horizontal \| vertical/,
   );
   assert.match(output, /"port": 6678,? \/\/ Annotated subtitle websocket server port\./);
-  assert.match(
-    output,
-    /"openBrowser": false,? \/\/ Open browser setting\. Values: true \| false/,
-  );
+  assert.match(output, /"openBrowser": false,? \/\/ Open browser setting\. Values: true \| false/);
   assert.match(
     output,
     /"enabled": false,? \/\/ Enable overlay controller support through the Chrome Gamepad API\. Values: true \| false/,

src/config/definitions/defaults-integrations.ts

@@ -93,6 +93,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
   },
   mpv: {
     executablePath: '',
+    launchMode: 'normal',
   },
   anilist: {
     enabled: false,

src/config/definitions/domain-registry.test.ts

@@ -29,6 +29,7 @@ test('config option registry includes critical paths and has unique entries', ()
     'anilist.characterDictionary.enabled',
     'anilist.characterDictionary.collapsibleSections.description',
     'mpv.executablePath',
+    'mpv.launchMode',
     'yomitan.externalProfilePath',
     'immersionTracking.enabled',
   ]) {

src/config/definitions/options-integrations.ts

@@ -1,4 +1,5 @@
 import { ResolvedConfig } from '../../types/config';
+import { MPV_LAUNCH_MODE_VALUES } from '../../shared/mpv-launch-mode';
 import { ConfigOptionRegistryEntry, RuntimeOptionRegistryEntry } from './shared';
 
 export function buildIntegrationConfigOptionRegistry(
@@ -245,6 +246,13 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         'Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.',
     },
+    {
+      path: 'mpv.launchMode',
+      kind: 'enum',
+      enumValues: MPV_LAUNCH_MODE_VALUES,
+      defaultValue: defaultConfig.mpv.launchMode,
+      description: 'Default window state for SubMiner-managed mpv launches.',
+    },
     {
       path: 'jellyfin.enabled',
       kind: 'boolean',

src/config/definitions/template-sections.ts

@@ -159,6 +159,7 @@ const INTEGRATION_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
     title: 'MPV Launcher',
     description: [
       'Optional mpv.exe override for Windows playback entry points.',
+      'Set mpv.launchMode to choose normal, maximized, or fullscreen SubMiner-managed mpv playback.',
       'Leave mpv.executablePath blank to auto-discover mpv.exe from SUBMINER_MPV_PATH or PATH.',
     ],
     key: 'mpv',

src/config/resolve/integrations.test.ts

@@ -13,6 +13,17 @@ test('resolveConfig trims configured mpv executable path', () => {
   assert.deepEqual(warnings, []);
 });
 
+test('resolveConfig parses configured mpv launch mode', () => {
+  const { resolved, warnings } = resolveConfig({
+    mpv: {
+      launchMode: 'maximized',
+    },
+  });
+
+  assert.equal(resolved.mpv.launchMode, 'maximized');
+  assert.deepEqual(warnings, []);
+});
+
 test('resolveConfig warns for invalid mpv executable path type', () => {
   const { resolved, warnings } = resolveConfig({
     mpv: {
@@ -29,3 +40,20 @@ test('resolveConfig warns for invalid mpv executable path type', () => {
     message: 'Expected string.',
   });
 });
+
+test('resolveConfig warns for invalid mpv launch mode', () => {
+  const { resolved, warnings } = resolveConfig({
+    mpv: {
+      launchMode: 'cinema' as never,
+    },
+  });
+
+  assert.equal(resolved.mpv.launchMode, 'normal');
+  assert.equal(warnings.length, 1);
+  assert.deepEqual(warnings[0], {
+    path: 'mpv.launchMode',
+    value: 'cinema',
+    fallback: 'normal',
+    message: "Expected one of: 'normal', 'maximized', 'fullscreen'.",
+  });
+});

src/config/resolve/integrations.ts

@@ -1,5 +1,6 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { MPV_LAUNCH_MODE_VALUES, parseMpvLaunchMode } from '../../shared/mpv-launch-mode';
 import { ResolveContext } from './context';
 import { asBoolean, asNumber, asString, isObject } from './shared';
 
@@ -240,6 +241,18 @@ export function applyIntegrationConfig(context: ResolveContext): void {
         'Expected string.',
       );
     }
+
+    const launchMode = parseMpvLaunchMode(src.mpv.launchMode);
+    if (launchMode !== undefined) {
+      resolved.mpv.launchMode = launchMode;
+    } else if (src.mpv.launchMode !== undefined) {
+      warn(
+        'mpv.launchMode',
+        src.mpv.launchMode,
+        resolved.mpv.launchMode,
+        `Expected one of: ${MPV_LAUNCH_MODE_VALUES.map((value) => `'${value}'`).join(', ')}.`,
+      );
+    }
   } else if (src.mpv !== undefined) {
     warn('mpv', src.mpv, resolved.mpv, 'Expected object.');
   }

src/core/services/__tests__/stats-server.test.ts

@@ -601,6 +601,22 @@ describe('stats server API routes', () => {
     assert.deepEqual(body.animePerDay.watchTime, TRENDS_DASHBOARD.animePerDay.watchTime);
   });
 
+  it('GET /api/stats/trends/dashboard accepts 365d range', async () => {
+    let seenArgs: unknown[] = [];
+    const app = createStatsApp(
+      createMockTracker({
+        getTrendsDashboard: async (...args: unknown[]) => {
+          seenArgs = args;
+          return TRENDS_DASHBOARD;
+        },
+      }),
+    );
+
+    const res = await app.request('/api/stats/trends/dashboard?range=365d&groupBy=month');
+    assert.equal(res.status, 200);
+    assert.deepEqual(seenArgs, ['365d', 'month']);
+  });
+
   it('GET /api/stats/trends/dashboard falls back to safe defaults for invalid params', async () => {
     let seenArgs: unknown[] = [];
     const app = createStatsApp(

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

@@ -488,7 +488,7 @@ export class ImmersionTrackerService {
   }
 
   async getTrendsDashboard(
-    range: '7d' | '30d' | '90d' | 'all' = '30d',
+    range: '7d' | '30d' | '90d' | '365d' | 'all' = '30d',
     groupBy: 'day' | 'month' = 'day',
   ): Promise<unknown> {
     return getTrendsDashboard(this.db, range, groupBy);

src/core/services/immersion-tracker/__tests__/query.test.ts

@@ -835,6 +835,65 @@ test('getTrendsDashboard keeps local-midnight session buckets separate', () => {
   }
 });
 
+test('getTrendsDashboard supports 365d range and caps day buckets at 365', () => {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  withMockNowMs('1772395200000', () => {
+    try {
+      ensureSchema(db);
+
+      const videoId = getOrCreateVideoRecord(db, 'local:/tmp/365d-trends.mkv', {
+        canonicalTitle: '365d Trends',
+        sourcePath: '/tmp/365d-trends.mkv',
+        sourceUrl: null,
+        sourceType: SOURCE_TYPE_LOCAL,
+      });
+      const animeId = getOrCreateAnimeRecord(db, {
+        parsedTitle: '365d Trends',
+        canonicalTitle: '365d Trends',
+        anilistId: null,
+        titleRomaji: null,
+        titleEnglish: null,
+        titleNative: null,
+        metadataJson: null,
+      });
+      linkVideoToAnimeRecord(db, videoId, {
+        animeId,
+        parsedBasename: '365d-trends.mkv',
+        parsedTitle: '365d Trends',
+        parsedSeason: 1,
+        parsedEpisode: 1,
+        parserSource: 'test',
+        parserConfidence: 1,
+        parseMetadataJson: null,
+      });
+
+      const insertDailyRollup = db.prepare(
+        `
+          INSERT INTO imm_daily_rollups (
+            rollup_day, video_id, total_sessions, total_active_min, total_lines_seen,
+            total_tokens_seen, total_cards, CREATED_DATE, LAST_UPDATE_DATE
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `,
+      );
+      // Seed 400 distinct rollup days so we can prove the 365d range caps at 365.
+      const latestRollupDay = 20513;
+      const createdAtMs = '1772395200000';
+      for (let offset = 0; offset < 400; offset += 1) {
+        const rollupDay = latestRollupDay - offset;
+        insertDailyRollup.run(rollupDay, videoId, 1, 30, 4, 100, 2, createdAtMs, createdAtMs);
+      }
+
+      const dashboard = getTrendsDashboard(db, '365d', 'day');
+
+      assert.equal(dashboard.activity.watchTime.length, 365);
+    } finally {
+      db.close();
+      cleanupDbPath(dbPath);
+    }
+  });
+});
+
 test('getTrendsDashboard month grouping spans every touched calendar month and keeps progress monthly', () => {
   const dbPath = makeDbPath();
   const db = new Database(dbPath);

src/core/services/immersion-tracker/query-trends.ts

@@ -13,7 +13,7 @@ import {
 } from './query-shared';
 import { getDailyRollups, getMonthlyRollups } from './query-sessions';
 
-type TrendRange = '7d' | '30d' | '90d' | 'all';
+type TrendRange = '7d' | '30d' | '90d' | '365d' | 'all';
 type TrendGroupBy = 'day' | 'month';
 
 interface TrendChartPoint {
@@ -85,6 +85,7 @@ const TREND_DAY_LIMITS: Record<Exclude<TrendRange, 'all'>, number> = {
   '7d': 7,
   '30d': 30,
   '90d': 90,
+  '365d': 365,
 };
 
 const MONTH_NAMES = [

src/core/services/stats-server.ts

@@ -30,8 +30,10 @@ function parseIntQuery(raw: string | undefined, fallback: number, maxLimit?: num
   return maxLimit === undefined ? parsed : Math.min(parsed, maxLimit);
 }
 
-function parseTrendRange(raw: string | undefined): '7d' | '30d' | '90d' | 'all' {
-  return raw === '7d' || raw === '30d' || raw === '90d' || raw === 'all' ? raw : '30d';
+function parseTrendRange(raw: string | undefined): '7d' | '30d' | '90d' | '365d' | 'all' {
+  return raw === '7d' || raw === '30d' || raw === '90d' || raw === '365d' || raw === 'all'
+    ? raw
+    : '30d';
 }
 
 function parseTrendGroupBy(raw: string | undefined): 'day' | 'month' {

src/main-entry.ts

@@ -20,6 +20,7 @@ import {
 import { requestSingleInstanceLockEarly } from './main/early-single-instance';
 import { resolvePackagedFirstRunPluginAssets } from './main/runtime/first-run-setup-plugin';
 import { createWindowsMpvLaunchDeps, launchWindowsMpv } from './main/runtime/windows-mpv-launch';
+import { parseMpvLaunchMode } from './shared/mpv-launch-mode';
 import { runStatsDaemonControlFromProcess } from './stats-daemon-entry';
 
 const DEFAULT_TEXTHOOKER_PORT = 5174;
@@ -36,21 +37,6 @@ function applySanitizedEnv(sanitizedEnv: NodeJS.ProcessEnv): void {
   }
 }
 
-function readConfiguredWindowsMpvExecutablePath(configDir: string): string {
-  const loadResult = loadRawConfigStrict({
-    configDir,
-    configFileJsonc: path.join(configDir, 'config.jsonc'),
-    configFileJson: path.join(configDir, 'config.json'),
-  });
-  if (!loadResult.ok) {
-    return '';
-  }
-
-  return typeof loadResult.config.mpv?.executablePath === 'string'
-    ? loadResult.config.mpv.executablePath.trim()
-    : '';
-}
-
 function resolveBundledWindowsMpvPluginEntrypoint(): string | undefined {
   const assets = resolvePackagedFirstRunPluginAssets({
     dirname: __dirname,
@@ -64,6 +50,31 @@ function resolveBundledWindowsMpvPluginEntrypoint(): string | undefined {
   return path.join(assets.pluginDirSource, 'main.lua');
 }
 
+function readConfiguredWindowsMpvLaunch(configDir: string): {
+  executablePath: string;
+  launchMode: 'normal' | 'maximized' | 'fullscreen';
+} {
+  const loadResult = loadRawConfigStrict({
+    configDir,
+    configFileJsonc: path.join(configDir, 'config.jsonc'),
+    configFileJson: path.join(configDir, 'config.json'),
+  });
+  if (!loadResult.ok) {
+    return {
+      executablePath: '',
+      launchMode: 'normal',
+    };
+  }
+
+  return {
+    executablePath:
+      typeof loadResult.config.mpv?.executablePath === 'string'
+        ? loadResult.config.mpv.executablePath.trim()
+        : '',
+    launchMode: parseMpvLaunchMode(loadResult.config.mpv?.launchMode) ?? 'normal',
+  };
+}
+
 process.argv = normalizeStartupArgv(process.argv, process.env);
 applySanitizedEnv(sanitizeStartupEnv(process.env));
 const userDataPath = configureEarlyAppPaths(app);
@@ -92,6 +103,7 @@ if (shouldHandleLaunchMpvAtEntry(process.argv, process.env)) {
   const sanitizedEnv = sanitizeLaunchMpvEnv(process.env);
   applySanitizedEnv(sanitizedEnv);
   void app.whenReady().then(async () => {
+    const configuredMpvLaunch = readConfiguredWindowsMpvLaunch(userDataPath);
     const result = await launchWindowsMpv(
       normalizeLaunchMpvTargets(process.argv),
       createWindowsMpvLaunchDeps({
@@ -103,7 +115,8 @@ if (shouldHandleLaunchMpvAtEntry(process.argv, process.env)) {
       normalizeLaunchMpvExtraArgs(process.argv),
       process.execPath,
       resolveBundledWindowsMpvPluginEntrypoint(),
-      readConfiguredWindowsMpvExecutablePath(userDataPath),
+      configuredMpvLaunch.executablePath,
+      configuredMpvLaunch.launchMode,
     );
     app.exit(result.ok ? 0 : 1);
   });

src/main.ts

@@ -1052,6 +1052,7 @@ const youtubePlaybackRuntime = createYoutubePlaybackRuntime({
       undefined,
       undefined,
       getResolvedConfig().mpv.executablePath,
+      getResolvedConfig().mpv.launchMode,
     ),
   waitForYoutubeMpvConnected: (timeoutMs) => waitForYoutubeMpvConnected(timeoutMs),
   prepareYoutubePlaybackInMpv: (request) => prepareYoutubePlaybackInMpv(request),
@@ -2031,6 +2032,7 @@ const {
   },
   launchMpvIdleForJellyfinPlaybackMainDeps: {
     getSocketPath: () => appState.mpvSocketPath,
+    getLaunchMode: () => getResolvedConfig().mpv.launchMode,
     platform: process.platform,
     execPath: process.execPath,
     defaultMpvLogPath: DEFAULT_MPV_LOG_PATH,
@@ -2318,8 +2320,8 @@ const openFirstRunSetupWindowHandler = createOpenFirstRunSetupWindowHandler({
   logError: (message, error) => logger.error(message, error),
 });
 
-function openFirstRunSetupWindow(): void {
-  if (firstRunSetupService.isSetupCompleted()) {
+function openFirstRunSetupWindow(force = false): void {
+  if (!force && firstRunSetupService.isSetupCompleted()) {
     return;
   }
   openFirstRunSetupWindowHandler();
@@ -3238,12 +3240,12 @@ const { appReadyRuntimeRunner } = composeAppReadyRuntime({
     handleFirstRunSetup: async () => {
       const snapshot = await firstRunSetupService.ensureSetupStateInitialized();
       appState.firstRunSetupCompleted = snapshot.state.status === 'completed';
-      if (
-        appState.initialArgs &&
-        shouldAutoOpenFirstRunSetup(appState.initialArgs) &&
-        snapshot.state.status !== 'completed'
-      ) {
-        openFirstRunSetupWindow();
+      const args = appState.initialArgs;
+      if (args && shouldAutoOpenFirstRunSetup(args)) {
+        const force = Boolean(args.setup);
+        if (force || snapshot.state.status !== 'completed') {
+          openFirstRunSetupWindow(force);
+        }
       }
     },
     startJellyfinRemoteSession: async () => {

src/main/runtime/composers/jellyfin-runtime-composer.test.ts

@@ -26,6 +26,7 @@ test('composeJellyfinRuntimeHandlers returns callable jellyfin runtime handlers'
     },
     launchMpvIdleForJellyfinPlaybackMainDeps: {
       getSocketPath: () => '/tmp/test-mpv.sock',
+      getLaunchMode: () => 'normal',
       platform: 'linux',
       execPath: process.execPath,
       defaultMpvLogPath: '/tmp/test-mpv.log',

src/main/runtime/first-run-setup-plugin.test.ts

@@ -237,10 +237,7 @@ test('detectInstalledFirstRunPlugin detects plugin installed in canonical mpv co
     fs.mkdirSync(path.dirname(pluginEntrypointPath), { recursive: true });
     fs.writeFileSync(pluginEntrypointPath, '-- plugin');
 
-    assert.equal(
-      detectInstalledFirstRunPlugin(installPaths),
-      true,
-    );
+    assert.equal(detectInstalledFirstRunPlugin(installPaths), true);
   });
 });
 
@@ -256,10 +253,7 @@ test('detectInstalledFirstRunPlugin ignores scoped plugin layout path', () => {
     fs.mkdirSync(path.dirname(pluginEntrypointPath), { recursive: true });
     fs.writeFileSync(pluginEntrypointPath, '-- plugin');
 
-    assert.equal(
-      detectInstalledFirstRunPlugin(installPaths),
-      false,
-    );
+    assert.equal(detectInstalledFirstRunPlugin(installPaths), false);
   });
 });
 
@@ -272,10 +266,7 @@ test('detectInstalledFirstRunPlugin ignores legacy loader file', () => {
     fs.mkdirSync(path.dirname(legacyLoaderPath), { recursive: true });
     fs.writeFileSync(legacyLoaderPath, '-- plugin');
 
-    assert.equal(
-      detectInstalledFirstRunPlugin(installPaths),
-      false,
-    );
+    assert.equal(detectInstalledFirstRunPlugin(installPaths), false);
   });
 });
 
@@ -288,9 +279,6 @@ test('detectInstalledFirstRunPlugin requires main.lua in subminer directory', ()
     fs.mkdirSync(pluginDir, { recursive: true });
     fs.writeFileSync(path.join(pluginDir, 'not_main.lua'), '-- plugin');
 
-    assert.equal(
-      detectInstalledFirstRunPlugin(installPaths),
-      false,
-    );
+    assert.equal(detectInstalledFirstRunPlugin(installPaths), false);
   });
 });

src/main/runtime/jellyfin-remote-connection-main-deps.test.ts

@@ -33,6 +33,7 @@ test('launch mpv for jellyfin main deps builder maps callbacks', () => {
   };
   const deps = createBuildLaunchMpvIdleForJellyfinPlaybackMainDepsHandler({
     getSocketPath: () => '/tmp/mpv.sock',
+    getLaunchMode: () => 'fullscreen',
     platform: 'darwin',
     execPath: '/tmp/subminer',
     defaultMpvLogPath: '/tmp/mpv.log',
@@ -47,6 +48,7 @@ test('launch mpv for jellyfin main deps builder maps callbacks', () => {
   })();
 
   assert.equal(deps.getSocketPath(), '/tmp/mpv.sock');
+  assert.equal(deps.getLaunchMode(), 'fullscreen');
   assert.equal(deps.platform, 'darwin');
   assert.equal(deps.execPath, '/tmp/subminer');
   assert.equal(deps.defaultMpvLogPath, '/tmp/mpv.log');

src/main/runtime/jellyfin-remote-connection-main-deps.ts

@@ -17,6 +17,7 @@ export function createBuildLaunchMpvIdleForJellyfinPlaybackMainDepsHandler(
 ) {
   return (): LaunchMpvForJellyfinDeps => ({
     getSocketPath: () => deps.getSocketPath(),
+    getLaunchMode: () => deps.getLaunchMode(),
     platform: deps.platform,
     execPath: deps.execPath,
     defaultMpvLogPath: deps.defaultMpvLogPath,

src/main/runtime/jellyfin-remote-connection.test.ts

@@ -31,6 +31,7 @@ test('createLaunchMpvIdleForJellyfinPlaybackHandler builds expected mpv args', (
   const logs: string[] = [];
   const launch = createLaunchMpvIdleForJellyfinPlaybackHandler({
     getSocketPath: () => '/tmp/subminer.sock',
+    getLaunchMode: () => 'maximized',
     platform: 'darwin',
     execPath: '/Applications/SubMiner.app/Contents/MacOS/SubMiner',
     defaultMpvLogPath: '/tmp/mp.log',
@@ -49,6 +50,7 @@ test('createLaunchMpvIdleForJellyfinPlaybackHandler builds expected mpv args', (
 
   launch();
   assert.equal(spawnedArgs.length, 1);
+  assert.ok(spawnedArgs[0]!.includes('--window-maximized=yes'));
   assert.ok(spawnedArgs[0]!.includes('--idle=yes'));
   assert.ok(spawnedArgs[0]!.some((arg) => arg.includes('--input-ipc-server=/tmp/subminer.sock')));
   assert.ok(logs.some((entry) => entry.includes('Launched mpv for Jellyfin playback')));

src/main/runtime/jellyfin-remote-connection.ts

@@ -1,3 +1,6 @@
+import { buildMpvLaunchModeArgs } from '../../shared/mpv-launch-mode';
+import type { MpvLaunchMode } from '../../types/config';
+
 type MpvClientLike = {
   connected: boolean;
   connect: () => void;
@@ -34,6 +37,7 @@ export function createWaitForMpvConnectedHandler(deps: WaitForMpvConnectedDeps)
 
 export type LaunchMpvForJellyfinDeps = {
   getSocketPath: () => string;
+  getLaunchMode: () => MpvLaunchMode;
   platform: NodeJS.Platform;
   execPath: string;
   defaultMpvLogPath: string;
@@ -58,6 +62,7 @@ export function createLaunchMpvIdleForJellyfinPlaybackHandler(deps: LaunchMpvFor
     const scriptOpts = `--script-opts=subminer-binary_path=${deps.execPath},subminer-socket_path=${socketPath}`;
     const mpvArgs = [
       ...deps.defaultMpvArgs,
+      ...buildMpvLaunchModeArgs(deps.getLaunchMode()),
       '--idle=yes',
       scriptOpts,
       `--log-file=${deps.defaultMpvLogPath}`,

src/main/runtime/local-subtitle-selection.test.ts

@@ -15,6 +15,11 @@ const mixedLanguageTrackList = [
   { type: 'sub', id: 12, lang: 'ja', title: 'ja.srt', external: true },
 ];
 
+const unlabeledExternalSidecarTrackList = [
+  { type: 'sub', id: 1, lang: 'eng', title: 'English ASS', external: false, selected: true },
+  { type: 'sub', id: 2, title: 'srt', external: true },
+];
+
 test('resolveManagedLocalSubtitleSelection prefers default Japanese primary and English secondary tracks', () => {
   const result = resolveManagedLocalSubtitleSelection({
     trackList: mixedLanguageTrackList,
@@ -37,6 +42,31 @@ test('resolveManagedLocalSubtitleSelection respects configured language override
   assert.equal(result.secondaryTrackId, 12);
 });
 
+test('resolveManagedLocalSubtitleSelection promotes a single unlabeled external sidecar to primary', () => {
+  const result = resolveManagedLocalSubtitleSelection({
+    trackList: unlabeledExternalSidecarTrackList,
+    primaryLanguages: [],
+    secondaryLanguages: [],
+  });
+
+  assert.equal(result.primaryTrackId, 2);
+  assert.equal(result.secondaryTrackId, 1);
+});
+
+test('resolveManagedLocalSubtitleSelection does not guess between multiple unlabeled external sidecars', () => {
+  const result = resolveManagedLocalSubtitleSelection({
+    trackList: [
+      ...unlabeledExternalSidecarTrackList,
+      { type: 'sub', id: 3, title: 'subrip', external: true },
+    ],
+    primaryLanguages: [],
+    secondaryLanguages: [],
+  });
+
+  assert.equal(result.primaryTrackId, null);
+  assert.equal(result.secondaryTrackId, 1);
+});
+
 test('managed local subtitle selection runtime applies preferred tracks once for a local media path', async () => {
   const commands: Array<Array<string | number>> = [];
   const scheduled: Array<() => void> = [];
@@ -75,3 +105,42 @@ test('managed local subtitle selection runtime applies preferred tracks once for
     ['set_property', 'secondary-sid', 11],
   ]);
 });
+
+test('managed local subtitle selection runtime promotes a single unlabeled external sidecar over embedded english', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const scheduled: Array<() => void> = [];
+
+  const runtime = createManagedLocalSubtitleSelectionRuntime({
+    getCurrentMediaPath: () => '/videos/example.mkv',
+    getMpvClient: () =>
+      ({
+        connected: true,
+        requestProperty: async (name: string) => {
+          if (name === 'track-list') {
+            return unlabeledExternalSidecarTrackList;
+          }
+          throw new Error(`Unexpected property: ${name}`);
+        },
+      }) as never,
+    getPrimarySubtitleLanguages: () => [],
+    getSecondarySubtitleLanguages: () => [],
+    sendMpvCommand: (command) => {
+      commands.push(command);
+    },
+    schedule: (callback) => {
+      scheduled.push(callback);
+      return 1 as never;
+    },
+    clearScheduled: () => {},
+  });
+
+  runtime.handleMediaPathChange('/videos/example.mkv');
+  scheduled.shift()?.();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  runtime.handleSubtitleTrackListChange(unlabeledExternalSidecarTrackList);
+
+  assert.deepEqual(commands, [
+    ['set_property', 'sid', 2],
+    ['set_property', 'secondary-sid', 1],
+  ]);
+});

src/main/runtime/local-subtitle-selection.ts

@@ -90,6 +90,10 @@ function isLikelyHearingImpaired(title: string): boolean {
   return HEARING_IMPAIRED_PATTERN.test(title);
 }
 
+function isUnlabeledExternalTrack(track: NormalizedSubtitleTrack): boolean {
+  return track.external && normalizeYoutubeLangCode(track.lang).length === 0;
+}
+
 function pickBestTrackId(
   tracks: NormalizedSubtitleTrack[],
   preferredLanguages: string[],
@@ -126,6 +130,19 @@ function pickBestTrackId(
   };
 }
 
+function pickSingleUnlabeledExternalTrackId(
+  tracks: NormalizedSubtitleTrack[],
+  excludeId: number | null = null,
+): number | null {
+  const fallbackCandidates = tracks.filter(
+    (track) => track.id !== excludeId && isUnlabeledExternalTrack(track),
+  );
+  if (fallbackCandidates.length !== 1) {
+    return null;
+  }
+  return fallbackCandidates[0]?.id ?? null;
+}
+
 export function resolveManagedLocalSubtitleSelection(input: {
   trackList: unknown[] | null;
   primaryLanguages: string[];
@@ -146,12 +163,13 @@ export function resolveManagedLocalSubtitleSelection(input: {
   );
 
   const primary = pickBestTrackId(tracks, preferredPrimaryLanguages);
-  const secondary = pickBestTrackId(tracks, preferredSecondaryLanguages, primary.trackId);
+  const primaryTrackId = primary.trackId ?? pickSingleUnlabeledExternalTrackId(tracks);
+  const secondary = pickBestTrackId(tracks, preferredSecondaryLanguages, primaryTrackId);
 
   return {
-    primaryTrackId: primary.trackId,
+    primaryTrackId,
     secondaryTrackId: secondary.trackId,
-    hasPrimaryMatch: primary.hasMatch,
+    hasPrimaryMatch: primary.hasMatch || primaryTrackId !== null,
     hasSecondaryMatch: secondary.hasMatch,
   };
 }

src/main/runtime/windows-mpv-launch.test.ts

@@ -80,6 +80,35 @@ test('buildWindowsMpvLaunchArgs uses explicit SubMiner defaults and targets', ()
   );
 });
 
+test('buildWindowsMpvLaunchArgs inserts maximized launch mode before explicit extra args when configured', () => {
+  assert.deepEqual(
+    buildWindowsMpvLaunchArgs(
+      ['C:\\video.mkv'],
+      ['--window-maximized=no'],
+      'C:\\SubMiner\\SubMiner.exe',
+      'C:\\Program Files\\SubMiner\\resources\\plugin\\subminer\\main.lua',
+      'maximized',
+    ),
+    [
+      '--player-operation-mode=pseudo-gui',
+      '--force-window=immediate',
+      '--script=C:\\Program Files\\SubMiner\\resources\\plugin\\subminer\\main.lua',
+      '--input-ipc-server=\\\\.\\pipe\\subminer-socket',
+      '--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
+      '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
+      '--sub-auto=fuzzy',
+      '--sub-file-paths=subs;subtitles',
+      '--sid=auto',
+      '--secondary-sid=auto',
+      '--secondary-sub-visibility=no',
+      '--script-opts=subminer-binary_path=C:\\SubMiner\\SubMiner.exe,subminer-socket_path=\\\\.\\pipe\\subminer-socket',
+      '--window-maximized=yes',
+      '--window-maximized=no',
+      'C:\\video.mkv',
+    ],
+  );
+});
+
 test('buildWindowsMpvLaunchArgs keeps shortcut-only launches in idle mode', () => {
   assert.deepEqual(
     buildWindowsMpvLaunchArgs(

src/main/runtime/windows-mpv-launch.ts

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import { spawn, spawnSync } from 'node:child_process';
+import { buildMpvLaunchModeArgs } from '../../shared/mpv-launch-mode';
+import type { MpvLaunchMode } from '../../types/config';
 
 export interface WindowsMpvLaunchDeps {
   getEnv: (name: string) => string | undefined;
@@ -89,6 +91,7 @@ export function buildWindowsMpvLaunchArgs(
   extraArgs: string[] = [],
   binaryPath?: string,
   pluginEntrypointPath?: string,
+  launchMode: MpvLaunchMode = 'normal',
 ): string[] {
   const launchIdle = targets.length === 0;
   const inputIpcServer =
@@ -119,6 +122,7 @@ export function buildWindowsMpvLaunchArgs(
     '--secondary-sid=auto',
     '--secondary-sub-visibility=no',
     ...(scriptOpts ? [scriptOpts] : []),
+    ...buildMpvLaunchModeArgs(launchMode),
     ...extraArgs,
     ...targets,
   ];
@@ -131,6 +135,7 @@ export async function launchWindowsMpv(
   binaryPath?: string,
   pluginEntrypointPath?: string,
   configuredMpvPath?: string,
+  launchMode: MpvLaunchMode = 'normal',
 ): Promise<{ ok: boolean; mpvPath: string }> {
   const normalizedConfiguredPath = normalizeCandidate(configuredMpvPath);
   const mpvPath = resolveWindowsMpvPath(deps, normalizedConfiguredPath);
@@ -147,7 +152,7 @@ export async function launchWindowsMpv(
   try {
     await deps.spawnDetached(
       mpvPath,
-      buildWindowsMpvLaunchArgs(targets, extraArgs, binaryPath, pluginEntrypointPath),
+      buildWindowsMpvLaunchArgs(targets, extraArgs, binaryPath, pluginEntrypointPath, launchMode),
     );
     return { ok: true, mpvPath };
   } catch (error) {

src/release-workflow.test.ts

@@ -13,6 +13,7 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
   productName?: string;
   scripts: Record<string, string>;
   build?: {
+    afterPack?: string;
     files?: string[];
   };
 };
@@ -77,6 +78,10 @@ test('release package scripts disable implicit electron-builder publishing', ()
   assert.match(packageJson.scripts['build:win:unsigned'] ?? '', /build-win-unsigned\.mjs/);
 });
 
+test('release packaging wires a shared afterPack hook for Linux AppImage library staging', () => {
+  assert.equal(packageJson.build?.afterPack, 'scripts/electron-builder-after-pack.cjs');
+});
+
 test('top-level package metadata keeps Linux Electron runtime app identity canonical', () => {
   assert.equal(packageJson.productName, 'SubMiner');
   assert.equal(packageJson.desktopName, 'SubMiner.desktop');

src/renderer/handlers/keyboard.ts

@@ -126,9 +126,7 @@ export function createKeyboardHandlers(
   }
 
   function acceleratorToKeyString(accelerator: string): string | null {
-    const normalized = accelerator
-      .replace(/\s+/g, '')
-      .replace(/cmdorctrl/gi, 'CommandOrControl');
+    const normalized = accelerator.replace(/\s+/g, '').replace(/cmdorctrl/gi, 'CommandOrControl');
     if (!normalized) return null;
     const parts = normalized.split('+').filter(Boolean);
     const keyToken = parts.pop();

src/renderer/modals/subtitle-sidebar.test.ts

@@ -75,7 +75,10 @@ function createListStub() {
 }
 
 test.afterEach(() => {
-  if (Object.prototype.hasOwnProperty.call(globalThis, 'window') && globalThis.window === undefined) {
+  if (
+    Object.prototype.hasOwnProperty.call(globalThis, 'window') &&
+    globalThis.window === undefined
+  ) {
     Reflect.deleteProperty(globalThis, 'window');
   }
   if (

src/shared/log-files.ts

@@ -22,17 +22,12 @@ function daysFromCivil(year: number, month: number, day: number): bigint {
   const yearOfEra = adjustedYear - era * 400;
   const monthIndex = month + (month > 2 ? -3 : 9);
   const dayOfYear = floorDiv(153 * monthIndex + 2, 5) + day - 1;
-  const dayOfEra =
-    yearOfEra * 365 + floorDiv(yearOfEra, 4) - floorDiv(yearOfEra, 100) + dayOfYear;
+  const dayOfEra = yearOfEra * 365 + floorDiv(yearOfEra, 4) - floorDiv(yearOfEra, 100) + dayOfYear;
   return BigInt(era * 146097 + dayOfEra - 719468);
 }
 
 function dateToEpochMs(date: Date): bigint {
-  const dayCount = daysFromCivil(
-    date.getUTCFullYear(),
-    date.getUTCMonth() + 1,
-    date.getUTCDate(),
-  );
+  const dayCount = daysFromCivil(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate());
   const timeOfDayMs = BigInt(
     ((date.getUTCHours() * 60 + date.getUTCMinutes()) * 60 + date.getUTCSeconds()) * 1000 +
       date.getUTCMilliseconds(),

src/shared/mpv-launch-mode.test.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildMpvLaunchModeArgs, parseMpvLaunchMode } from './mpv-launch-mode';
+
+test('parseMpvLaunchMode normalizes valid string values', () => {
+  assert.equal(parseMpvLaunchMode(' fullscreen '), 'fullscreen');
+  assert.equal(parseMpvLaunchMode('MAXIMIZED'), 'maximized');
+  assert.equal(parseMpvLaunchMode('normal'), 'normal');
+});
+
+test('buildMpvLaunchModeArgs returns the expected mpv flags', () => {
+  assert.deepEqual(buildMpvLaunchModeArgs('normal'), []);
+  assert.deepEqual(buildMpvLaunchModeArgs('maximized'), ['--window-maximized=yes']);
+  assert.deepEqual(buildMpvLaunchModeArgs('fullscreen'), ['--fullscreen']);
+});

src/shared/mpv-launch-mode.ts

@@ -0,0 +1,27 @@
+import type { MpvLaunchMode } from '../types/config';
+
+export const MPV_LAUNCH_MODE_VALUES = [
+  'normal',
+  'maximized',
+  'fullscreen',
+] as const satisfies readonly MpvLaunchMode[];
+
+export function parseMpvLaunchMode(value: unknown): MpvLaunchMode | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  return MPV_LAUNCH_MODE_VALUES.find((candidate) => candidate === normalized);
+}
+
+export function buildMpvLaunchModeArgs(launchMode: MpvLaunchMode): string[] {
+  switch (launchMode) {
+    case 'fullscreen':
+      return ['--fullscreen'];
+    case 'maximized':
+      return ['--window-maximized=yes'];
+    default:
+      return [];
+  }
+}

src/shared/setup-state.test.ts

@@ -203,13 +203,7 @@ test('resolveDefaultMpvInstallPaths resolves linux, macOS, and Windows defaults'
       'main.lua',
     ),
     pluginDir: path.posix.join(macHomeDir, '.config', 'mpv', 'scripts', 'subminer'),
-    pluginConfigPath: path.posix.join(
-      macHomeDir,
-      '.config',
-      'mpv',
-      'script-opts',
-      'subminer.conf',
-    ),
+    pluginConfigPath: path.posix.join(macHomeDir, '.config', 'mpv', 'script-opts', 'subminer.conf'),
   });
 
   assert.deepEqual(resolveDefaultMpvInstallPaths('win32', 'C:\\Users\\tester', undefined), {

src/shared/setup-state.ts

@@ -242,8 +242,8 @@ export function resolveDefaultMpvInstallPaths(
   const platformPath = getPlatformPath(platform);
   const mpvConfigDir =
     platform === 'linux' || platform === 'darwin'
-        ? platformPath.join(xdgConfigHome?.trim() || platformPath.join(homeDir, '.config'), 'mpv')
-        : platformPath.join(homeDir, 'AppData', 'Roaming', 'mpv');
+      ? platformPath.join(xdgConfigHome?.trim() || platformPath.join(homeDir, '.config'), 'mpv')
+      : platformPath.join(homeDir, 'AppData', 'Roaming', 'mpv');
 
   return {
     supported: platform === 'linux' || platform === 'darwin' || platform === 'win32',

src/types/config.ts

@@ -50,8 +50,11 @@ export interface TexthookerConfig {
   openBrowser?: boolean;
 }
 
+export type MpvLaunchMode = 'normal' | 'maximized' | 'fullscreen';
+
 export interface MpvConfig {
   executablePath?: string;
+  launchMode?: MpvLaunchMode;
 }
 
 export type SubsyncMode = 'auto' | 'manual';
@@ -129,6 +132,7 @@ export interface ResolvedConfig {
   texthooker: Required<TexthookerConfig>;
   mpv: {
     executablePath: string;
+    launchMode: MpvLaunchMode;
   };
   controller: {
     enabled: boolean;

stats/src/components/anime/AnimeTab.tsx

@@ -93,7 +93,7 @@ export function AnimeTab({
       <div className="flex items-center gap-3">
         <input
           type="text"
-          placeholder="Search anime..."
+          placeholder="Search library..."
           value={search}
           onChange={(e) => setSearch(e.target.value)}
           className="flex-1 bg-ctp-surface0 border border-ctp-surface1 rounded-lg px-3 py-2 text-sm text-ctp-text placeholder:text-ctp-overlay2 focus:outline-none focus:border-ctp-blue"
@@ -125,12 +125,12 @@ export function AnimeTab({
           ))}
         </div>
         <div className="text-xs text-ctp-overlay2 shrink-0">
-          {filtered.length} anime · {formatDuration(totalMs)}
+          {filtered.length} titles · {formatDuration(totalMs)}
         </div>
       </div>
 
       {filtered.length === 0 ? (
-        <div className="text-sm text-ctp-overlay2 p-4">No anime found</div>
+        <div className="text-sm text-ctp-overlay2 p-4">No titles found</div>
       ) : (
         <div className={`grid ${GRID_CLASSES[cardSize]} gap-4`}>
           {filtered.map((item) => (

stats/src/components/anime/EpisodeDetail.test.tsx

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { filterCardEvents } from './EpisodeDetail';
+import type { EpisodeCardEvent } from '../../types/stats';
+
+function makeEvent(over: Partial<EpisodeCardEvent> & { eventId: number }): EpisodeCardEvent {
+  return {
+    sessionId: 1,
+    tsMs: 0,
+    cardsDelta: 1,
+    noteIds: [],
+    ...over,
+  };
+}
+
+test('filterCardEvents: before load, returns all events unchanged', () => {
+  const ev1 = makeEvent({ eventId: 1, noteIds: [101] });
+  const ev2 = makeEvent({ eventId: 2, noteIds: [102] });
+  const noteInfos = new Map(); // empty — simulates pre-load state
+  const result = filterCardEvents([ev1, ev2], noteInfos, /* noteInfosLoaded */ false);
+  assert.equal(result.length, 2, 'should return both events before load');
+  assert.deepEqual(result[0]?.noteIds, [101]);
+  assert.deepEqual(result[1]?.noteIds, [102]);
+});
+
+test('filterCardEvents: after load, drops noteIds not in noteInfos', () => {
+  const ev1 = makeEvent({ eventId: 1, noteIds: [101] }); // survives
+  const ev2 = makeEvent({ eventId: 2, noteIds: [102] }); // deleted from Anki
+  const noteInfos = new Map([[101, { noteId: 101, expression: '食べる' }]]);
+  const result = filterCardEvents([ev1, ev2], noteInfos, /* noteInfosLoaded */ true);
+  assert.equal(result.length, 1, 'should drop event whose noteId was deleted from Anki');
+  assert.equal(result[0]?.eventId, 1);
+  assert.deepEqual(result[0]?.noteIds, [101]);
+});
+
+test('filterCardEvents: after load, legacy rollup events (empty noteIds, positive cardsDelta) are kept', () => {
+  const rollup = makeEvent({ eventId: 3, noteIds: [], cardsDelta: 5 });
+  const noteInfos = new Map<number, { noteId: number; expression: string }>();
+  const result = filterCardEvents([rollup], noteInfos, true);
+  assert.equal(result.length, 1, 'legacy rollup event should survive filtering');
+  assert.equal(result[0]?.cardsDelta, 5);
+});
+
+test('filterCardEvents: after load, event with multiple noteIds keeps surviving ones', () => {
+  const ev = makeEvent({ eventId: 4, noteIds: [201, 202, 203] });
+  const noteInfos = new Map([
+    [201, { noteId: 201, expression: 'A' }],
+    [203, { noteId: 203, expression: 'C' }],
+  ]);
+  const result = filterCardEvents([ev], noteInfos, true);
+  assert.equal(result.length, 1, 'event with surviving noteIds should be kept');
+  assert.deepEqual(result[0]?.noteIds, [201, 203], 'only surviving noteIds should remain');
+});
+
+test('filterCardEvents: after load, event where all noteIds deleted is dropped', () => {
+  const ev = makeEvent({ eventId: 5, noteIds: [301, 302] });
+  const noteInfos = new Map<number, { noteId: number; expression: string }>();
+  const result = filterCardEvents([ev], noteInfos, true);
+  assert.equal(result.length, 0, 'event with all noteIds deleted should be dropped');
+});

stats/src/components/anime/EpisodeDetail.tsx

@@ -16,10 +16,32 @@ interface NoteInfo {
   expression: string;
 }
 
+export function filterCardEvents(
+  cardEvents: EpisodeDetailData['cardEvents'],
+  noteInfos: Map<number, NoteInfo>,
+  noteInfosLoaded: boolean,
+): EpisodeDetailData['cardEvents'] {
+  if (!noteInfosLoaded) return cardEvents;
+  return cardEvents
+    .map((ev) => {
+      // Legacy rollup events: no noteIds, just a cardsDelta count — keep as-is.
+      if (ev.noteIds.length === 0) return ev;
+      const survivingNoteIds = ev.noteIds.filter((id) => noteInfos.has(id));
+      return { ...ev, noteIds: survivingNoteIds };
+    })
+    .filter((ev, i) => {
+      // If the event originally had noteIds, only keep it if some survived.
+      if ((cardEvents[i]?.noteIds.length ?? 0) > 0) return ev.noteIds.length > 0;
+      // Legacy rollup event (originally no noteIds): keep if it has a positive delta.
+      return ev.cardsDelta > 0;
+    });
+}
+
 export function EpisodeDetail({ videoId, onSessionDeleted }: EpisodeDetailProps) {
   const [data, setData] = useState<EpisodeDetailData | null>(null);
   const [loading, setLoading] = useState(true);
   const [noteInfos, setNoteInfos] = useState<Map<number, NoteInfo>>(new Map());
+  const [noteInfosLoaded, setNoteInfosLoaded] = useState(false);
 
   useEffect(() => {
     let cancelled = false;
@@ -41,8 +63,14 @@ export function EpisodeDetail({ videoId, onSessionDeleted }: EpisodeDetailProps)
                 map.set(note.noteId, { noteId: note.noteId, expression: expr });
               }
               setNoteInfos(map);
+              setNoteInfosLoaded(true);
             })
-            .catch((err) => console.warn('Failed to fetch Anki note info:', err));
+            .catch((err) => {
+              console.warn('Failed to fetch Anki note info:', err);
+              if (!cancelled) setNoteInfosLoaded(true);
+            });
+        } else {
+          if (!cancelled) setNoteInfosLoaded(true);
         }
       })
       .catch(() => {
@@ -72,6 +100,16 @@ export function EpisodeDetail({ videoId, onSessionDeleted }: EpisodeDetailProps)
 
   const { sessions, cardEvents } = data;
 
+  const filteredCardEvents = filterCardEvents(cardEvents, noteInfos, noteInfosLoaded);
+
+  const hiddenCardCount = noteInfosLoaded
+    ? cardEvents.reduce((sum, ev) => {
+        if (ev.noteIds.length === 0) return sum;
+        const surviving = ev.noteIds.filter((id) => noteInfos.has(id));
+        return sum + (ev.noteIds.length - surviving.length);
+      }, 0)
+    : 0;
+
   return (
     <div className="bg-ctp-mantle border border-ctp-surface1 rounded-lg">
       {sessions.length > 0 && (
@@ -106,11 +144,11 @@ export function EpisodeDetail({ videoId, onSessionDeleted }: EpisodeDetailProps)
         </div>
       )}
 
-      {cardEvents.length > 0 && (
+      {filteredCardEvents.length > 0 && (
         <div className="p-3 border-b border-ctp-surface1">
           <h4 className="text-xs font-semibold text-ctp-subtext0 mb-2">Cards Mined</h4>
           <div className="space-y-1.5">
-            {cardEvents.map((ev) => (
+            {filteredCardEvents.map((ev) => (
               <div key={ev.eventId} className="flex items-center gap-2 text-xs">
                 <span className="text-ctp-overlay2 shrink-0">{formatRelativeDate(ev.tsMs)}</span>
                 {ev.noteIds.length > 0 ? (
@@ -144,6 +182,11 @@ export function EpisodeDetail({ videoId, onSessionDeleted }: EpisodeDetailProps)
               </div>
             ))}
           </div>
+          {hiddenCardCount > 0 && (
+            <div className="px-3 pb-3 -mt-1 text-[10px] text-ctp-overlay2 italic">
+              {hiddenCardCount} {hiddenCardCount === 1 ? 'card' : 'cards'} hidden (deleted from Anki)
+            </div>
+          )}
         </div>
       )}
 

stats/src/components/library/LibraryTab.tsx

@@ -1,120 +0,0 @@
-import { useState, useMemo } from 'react';
-import { useMediaLibrary } from '../../hooks/useMediaLibrary';
-import { formatDuration, formatNumber } from '../../lib/formatters';
-import {
-  groupMediaLibraryItems,
-  summarizeMediaLibraryGroups,
-} from '../../lib/media-library-grouping';
-import { CoverImage } from './CoverImage';
-import { MediaCard } from './MediaCard';
-import { MediaDetailView } from './MediaDetailView';
-
-interface LibraryTabProps {
-  onNavigateToSession: (sessionId: number) => void;
-}
-
-export function LibraryTab({ onNavigateToSession }: LibraryTabProps) {
-  const { media, loading, error } = useMediaLibrary();
-  const [search, setSearch] = useState('');
-  const [selectedVideoId, setSelectedVideoId] = useState<number | null>(null);
-
-  const filtered = useMemo(() => {
-    if (!search.trim()) return media;
-    const q = search.toLowerCase();
-    return media.filter((m) => {
-      const haystacks = [
-        m.canonicalTitle,
-        m.videoTitle,
-        m.channelName,
-        m.uploaderId,
-        m.channelId,
-      ].filter(Boolean);
-      return haystacks.some((value) => value!.toLowerCase().includes(q));
-    });
-  }, [media, search]);
-  const grouped = useMemo(() => groupMediaLibraryItems(filtered), [filtered]);
-  const summary = useMemo(() => summarizeMediaLibraryGroups(grouped), [grouped]);
-
-  if (selectedVideoId !== null) {
-    return <MediaDetailView videoId={selectedVideoId} onBack={() => setSelectedVideoId(null)} />;
-  }
-
-  if (loading) return <div className="text-ctp-overlay2 p-4">Loading...</div>;
-  if (error) return <div className="text-ctp-red p-4">Error: {error}</div>;
-
-  return (
-    <div className="space-y-4">
-      <div className="flex items-center gap-3">
-        <input
-          type="text"
-          placeholder="Search titles..."
-          value={search}
-          onChange={(e) => setSearch(e.target.value)}
-          className="flex-1 bg-ctp-surface0 border border-ctp-surface1 rounded-lg px-3 py-2 text-sm text-ctp-text placeholder:text-ctp-overlay2 focus:outline-none focus:border-ctp-blue"
-        />
-        <div className="text-xs text-ctp-overlay2 shrink-0">
-          {grouped.length} group{grouped.length !== 1 ? 's' : ''} · {summary.totalVideos} video
-          {summary.totalVideos !== 1 ? 's' : ''} · {formatDuration(summary.totalMs)}
-        </div>
-      </div>
-
-      {filtered.length === 0 ? (
-        <div className="text-sm text-ctp-overlay2 p-4">No media found</div>
-      ) : (
-        <div className="space-y-6">
-          {grouped.map((group) => (
-            <section
-              key={group.key}
-              className="rounded-2xl border border-ctp-surface1 bg-ctp-surface0/70 overflow-hidden"
-            >
-              <div className="flex items-center gap-4 p-4 border-b border-ctp-surface1 bg-ctp-base/40">
-                <CoverImage
-                  videoId={group.items[0]!.videoId}
-                  title={group.title}
-                  src={group.imageUrl}
-                  className="w-16 h-16 rounded-2xl shrink-0"
-                />
-                <div className="min-w-0 flex-1">
-                  <div className="flex items-center gap-2">
-                    {group.channelUrl ? (
-                      <a
-                        href={group.channelUrl}
-                        target="_blank"
-                        rel="noreferrer"
-                        className="text-base font-semibold text-ctp-text truncate hover:text-ctp-blue transition-colors"
-                      >
-                        {group.title}
-                      </a>
-                    ) : (
-                      <h3 className="text-base font-semibold text-ctp-text truncate">
-                        {group.title}
-                      </h3>
-                    )}
-                  </div>
-                  {group.subtitle ? (
-                    <div className="text-xs text-ctp-overlay1 truncate mt-1">{group.subtitle}</div>
-                  ) : null}
-                  <div className="text-xs text-ctp-overlay2 mt-2">
-                    {group.items.length} video{group.items.length !== 1 ? 's' : ''} ·{' '}
-                    {formatDuration(group.totalActiveMs)} · {formatNumber(group.totalCards)} cards
-                  </div>
-                </div>
-              </div>
-              <div className="p-4">
-                <div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 gap-4">
-                  {group.items.map((item) => (
-                    <MediaCard
-                      key={item.videoId}
-                      item={item}
-                      onClick={() => setSelectedVideoId(item.videoId)}
-                    />
-                  ))}
-                </div>
-              </div>
-            </section>
-          ))}
-        </div>
-      )}
-    </div>
-  );
-}

stats/src/components/library/MediaDetailView.test.tsx

@@ -1,6 +1,8 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { getRelatedCollectionLabel } from './MediaDetailView';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { createElement } from 'react';
+import { getRelatedCollectionLabel, buildDeleteEpisodeHandler } from './MediaDetailView';
 
 test('getRelatedCollectionLabel returns View Channel for youtube-backed media', () => {
   assert.equal(
@@ -41,3 +43,85 @@ test('getRelatedCollectionLabel returns View Anime for non-youtube media', () =>
     'View Anime',
   );
 });
+
+test('buildDeleteEpisodeHandler calls deleteVideo then onBack when confirm returns true', async () => {
+  let deletedVideoId: number | null = null;
+  let onBackCalled = false;
+
+  const fakeApiClient = {
+    deleteVideo: async (id: number) => {
+      deletedVideoId = id;
+    },
+  };
+
+  const fakeConfirm = (_title: string) => true;
+
+  const handler = buildDeleteEpisodeHandler({
+    videoId: 42,
+    title: 'Test Episode',
+    apiClient: fakeApiClient as { deleteVideo: (id: number) => Promise<void> },
+    confirmFn: fakeConfirm,
+    onBack: () => {
+      onBackCalled = true;
+    },
+    setDeleteError: () => {},
+  });
+
+  await handler();
+  assert.equal(deletedVideoId, 42);
+  assert.equal(onBackCalled, true);
+});
+
+test('buildDeleteEpisodeHandler does nothing when confirm returns false', async () => {
+  let deletedVideoId: number | null = null;
+  let onBackCalled = false;
+
+  const fakeApiClient = {
+    deleteVideo: async (id: number) => {
+      deletedVideoId = id;
+    },
+  };
+
+  const fakeConfirm = (_title: string) => false;
+
+  const handler = buildDeleteEpisodeHandler({
+    videoId: 42,
+    title: 'Test Episode',
+    apiClient: fakeApiClient as { deleteVideo: (id: number) => Promise<void> },
+    confirmFn: fakeConfirm,
+    onBack: () => {
+      onBackCalled = true;
+    },
+    setDeleteError: () => {},
+  });
+
+  await handler();
+  assert.equal(deletedVideoId, null);
+  assert.equal(onBackCalled, false);
+});
+
+test('buildDeleteEpisodeHandler sets error when deleteVideo throws', async () => {
+  let capturedError: string | null = null;
+
+  const fakeApiClient = {
+    deleteVideo: async (_id: number) => {
+      throw new Error('Network failure');
+    },
+  };
+
+  const fakeConfirm = (_title: string) => true;
+
+  const handler = buildDeleteEpisodeHandler({
+    videoId: 42,
+    title: 'Test Episode',
+    apiClient: fakeApiClient as { deleteVideo: (id: number) => Promise<void> },
+    confirmFn: fakeConfirm,
+    onBack: () => {},
+    setDeleteError: (msg) => {
+      capturedError = msg;
+    },
+  });
+
+  await handler();
+  assert.equal(capturedError, 'Network failure');
+});

stats/src/components/library/MediaDetailView.tsx

@@ -1,12 +1,34 @@
 import { useEffect, useState } from 'react';
 import { useMediaDetail } from '../../hooks/useMediaDetail';
 import { apiClient } from '../../lib/api-client';
-import { confirmSessionDelete } from '../../lib/delete-confirm';
+import { confirmSessionDelete, confirmEpisodeDelete } from '../../lib/delete-confirm';
 import { getSessionDisplayWordCount } from '../../lib/session-word-count';
 import { MediaHeader } from './MediaHeader';
 import { MediaSessionList } from './MediaSessionList';
 import type { MediaDetailData, SessionSummary } from '../../types/stats';
 
+interface DeleteEpisodeHandlerOptions {
+  videoId: number;
+  title: string;
+  apiClient: { deleteVideo: (id: number) => Promise<void> };
+  confirmFn: (title: string) => boolean;
+  onBack: () => void;
+  setDeleteError: (msg: string | null) => void;
+}
+
+export function buildDeleteEpisodeHandler(opts: DeleteEpisodeHandlerOptions): () => Promise<void> {
+  return async () => {
+    if (!opts.confirmFn(opts.title)) return;
+    opts.setDeleteError(null);
+    try {
+      await opts.apiClient.deleteVideo(opts.videoId);
+      opts.onBack();
+    } catch (err) {
+      opts.setDeleteError(err instanceof Error ? err.message : 'Failed to delete episode.');
+    }
+  };
+}
+
 export function getRelatedCollectionLabel(detail: MediaDetailData['detail']): string {
   if (detail?.channelName?.trim()) {
     return 'View Channel';
@@ -79,6 +101,15 @@ export function MediaDetailView({
     }
   };
 
+  const handleDeleteEpisode = buildDeleteEpisodeHandler({
+    videoId,
+    title: detail.canonicalTitle,
+    apiClient,
+    confirmFn: confirmEpisodeDelete,
+    onBack,
+    setDeleteError,
+  });
+
   return (
     <div className="space-y-4">
       <div className="flex items-center justify-between">
@@ -99,7 +130,7 @@ export function MediaDetailView({
           </button>
         ) : null}
       </div>
-      <MediaHeader detail={detail} />
+      <MediaHeader detail={detail} onDeleteEpisode={handleDeleteEpisode} />
       {deleteError ? <div className="text-sm text-ctp-red">{deleteError}</div> : null}
       <MediaSessionList
         sessions={sessions}

stats/src/components/library/MediaHeader.tsx

@@ -12,9 +12,14 @@ interface MediaHeaderProps {
     totalUniqueWords: number;
     knownWordCount: number;
   } | null;
+  onDeleteEpisode?: () => void;
 }
 
-export function MediaHeader({ detail, initialKnownWordsSummary = null }: MediaHeaderProps) {
+export function MediaHeader({
+  detail,
+  initialKnownWordsSummary = null,
+  onDeleteEpisode,
+}: MediaHeaderProps) {
   const knownTokenRate =
     detail.totalLookupCount > 0 ? detail.totalLookupHits / detail.totalLookupCount : null;
   const avgSessionMs =
@@ -50,7 +55,18 @@ export function MediaHeader({ detail, initialKnownWordsSummary = null }: MediaHe
         className="w-32 h-44 rounded-lg shrink-0"
       />
       <div className="flex-1 min-w-0">
-        <h2 className="text-lg font-bold text-ctp-text truncate">{detail.canonicalTitle}</h2>
+        <div className="flex items-start justify-between gap-2">
+          <h2 className="text-lg font-bold text-ctp-text truncate">{detail.canonicalTitle}</h2>
+          {onDeleteEpisode != null ? (
+            <button
+              type="button"
+              onClick={onDeleteEpisode}
+              className="shrink-0 text-xs text-ctp-red hover:opacity-75 transition-opacity"
+            >
+              Delete Episode
+            </button>
+          ) : null}
+        </div>
         {detail.channelName ? (
           <div className="mt-1 text-sm text-ctp-subtext1 truncate">
             {detail.channelUrl ? (

stats/src/components/overview/HeroStats.tsx

@@ -36,7 +36,7 @@ export function HeroStats({ summary, sessions }: HeroStatsProps) {
       />
       <StatCard label="Current Streak" value={`${summary.streakDays}d`} color="text-ctp-peach" />
       <StatCard
-        label="Active Anime"
+        label="Active Titles"
         value={formatNumber(summary.activeAnimeCount)}
         color="text-ctp-mauve"
       />

stats/src/components/overview/TrackingSnapshot.tsx

@@ -71,7 +71,7 @@ export function TrackingSnapshot({
             </div>
           </div>
         </Tooltip>
-        <Tooltip text="Total unique episodes (videos) watched across all anime">
+        <Tooltip text="Total unique videos watched across all titles in your library">
           <div className="rounded-lg bg-ctp-surface1/60 p-3">
             <div className="text-xs uppercase tracking-wide text-ctp-overlay2">Episodes</div>
             <div className="mt-1 text-xl font-semibold font-mono tabular-nums text-ctp-blue">
@@ -79,9 +79,9 @@ export function TrackingSnapshot({
             </div>
           </div>
         </Tooltip>
-        <Tooltip text="Number of anime series fully completed">
+        <Tooltip text="Number of titles fully completed">
           <div className="rounded-lg bg-ctp-surface1/60 p-3">
-            <div className="text-xs uppercase tracking-wide text-ctp-overlay2">Anime</div>
+            <div className="text-xs uppercase tracking-wide text-ctp-overlay2">Titles</div>
             <div className="mt-1 text-xl font-semibold font-mono tabular-nums text-ctp-sapphire">
               {formatNumber(summary.totalAnimeCompleted)}
             </div>

stats/src/components/overview/WatchTimeChart.tsx

@@ -1,7 +1,15 @@
 import { useState } from 'react';
-import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer } from 'recharts';
+import {
+  BarChart,
+  Bar,
+  CartesianGrid,
+  XAxis,
+  YAxis,
+  Tooltip,
+  ResponsiveContainer,
+} from 'recharts';
 import { epochDayToDate } from '../../lib/formatters';
-import { CHART_THEME } from '../../lib/chart-theme';
+import { CHART_DEFAULTS, CHART_THEME, TOOLTIP_CONTENT_STYLE } from '../../lib/chart-theme';
 import type { DailyRollup } from '../../types/stats';
 
 interface WatchTimeChartProps {
@@ -52,28 +60,23 @@ export function WatchTimeChart({ rollups }: WatchTimeChartProps) {
           ))}
         </div>
       </div>
-      <ResponsiveContainer width="100%" height={160}>
-        <BarChart data={chartData}>
+      <ResponsiveContainer width="100%" height={CHART_DEFAULTS.height}>
+        <BarChart data={chartData} margin={CHART_DEFAULTS.margin}>
+          <CartesianGrid stroke={CHART_THEME.grid} {...CHART_DEFAULTS.grid} />
           <XAxis
             dataKey="date"
-            tick={{ fontSize: 10, fill: CHART_THEME.tick }}
-            axisLine={false}
+            tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+            axisLine={{ stroke: CHART_THEME.axisLine }}
             tickLine={false}
           />
           <YAxis
-            tick={{ fontSize: 10, fill: CHART_THEME.tick }}
-            axisLine={false}
+            tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+            axisLine={{ stroke: CHART_THEME.axisLine }}
             tickLine={false}
-            width={30}
+            width={32}
           />
           <Tooltip
-            contentStyle={{
-              background: CHART_THEME.tooltipBg,
-              border: `1px solid ${CHART_THEME.tooltipBorder}`,
-              borderRadius: 6,
-              color: CHART_THEME.tooltipText,
-              fontSize: 12,
-            }}
+            contentStyle={TOOLTIP_CONTENT_STYLE}
             labelStyle={{ color: CHART_THEME.tooltipLabel }}
             formatter={formatActiveMinutes}
           />

stats/src/components/sessions/SessionRow.tsx

@@ -120,7 +120,7 @@ export function SessionRow({
           }}
           aria-label={`View overview for ${session.canonicalTitle ?? 'Unknown Media'}`}
           className="absolute right-10 top-1/2 -translate-y-1/2 w-5 h-5 rounded border border-ctp-surface2 text-transparent hover:border-ctp-blue/50 hover:text-ctp-blue hover:bg-ctp-blue/10 transition-colors opacity-0 group-hover:opacity-100 focus:opacity-100 flex items-center justify-center"
-          title="View anime overview"
+          title="View in Library"
         >
           {'\u2197'}
         </button>

stats/src/components/sessions/SessionsTab.test.tsx

@@ -0,0 +1,156 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { SessionBucket } from '../../lib/session-grouping';
+import type { SessionSummary } from '../../types/stats';
+import { buildBucketDeleteHandler } from './SessionsTab';
+
+function makeSession(over: Partial<SessionSummary>): SessionSummary {
+  return {
+    sessionId: 1,
+    videoId: 100,
+    canonicalTitle: 'Episode 1',
+    startedAtMs: 1_000_000,
+    endedAtMs: 1_060_000,
+    activeWatchedMs: 60_000,
+    cardsMined: 1,
+    linesSeen: 10,
+    lookupCount: 5,
+    lookupHits: 3,
+    knownWordsSeen: 5,
+    ...over,
+  } as SessionSummary;
+}
+
+function makeBucket(sessions: SessionSummary[]): SessionBucket {
+  const sorted = [...sessions].sort((a, b) => b.startedAtMs - a.startedAtMs);
+  return {
+    key: `v-${sorted[0]!.videoId}`,
+    videoId: sorted[0]!.videoId ?? null,
+    sessions: sorted,
+    totalActiveMs: sorted.reduce((s, x) => s + x.activeWatchedMs, 0),
+    totalCardsMined: sorted.reduce((s, x) => s + x.cardsMined, 0),
+    representativeSession: sorted[0]!,
+  };
+}
+
+test('buildBucketDeleteHandler deletes every session in the bucket when confirm returns true', async () => {
+  let deleted: number[] | null = null;
+  let onSuccessCalledWith: number[] | null = null;
+  let onErrorCalled = false;
+
+  const bucket = makeBucket([
+    makeSession({ sessionId: 11, startedAtMs: 2_000_000 }),
+    makeSession({ sessionId: 22, startedAtMs: 3_000_000 }),
+    makeSession({ sessionId: 33, startedAtMs: 4_000_000 }),
+  ]);
+
+  const handler = buildBucketDeleteHandler({
+    bucket,
+    apiClient: {
+      deleteSessions: async (ids: number[]) => {
+        deleted = ids;
+      },
+    },
+    confirm: (title, count) => {
+      assert.equal(title, 'Episode 1');
+      assert.equal(count, 3);
+      return true;
+    },
+    onSuccess: (ids) => {
+      onSuccessCalledWith = ids;
+    },
+    onError: () => {
+      onErrorCalled = true;
+    },
+  });
+
+  await handler();
+
+  assert.deepEqual(deleted, [33, 22, 11]);
+  assert.deepEqual(onSuccessCalledWith, [33, 22, 11]);
+  assert.equal(onErrorCalled, false);
+});
+
+test('buildBucketDeleteHandler is a no-op when confirm returns false', async () => {
+  let deleteCalled = false;
+  let successCalled = false;
+
+  const bucket = makeBucket([
+    makeSession({ sessionId: 1 }),
+    makeSession({ sessionId: 2 }),
+  ]);
+
+  const handler = buildBucketDeleteHandler({
+    bucket,
+    apiClient: {
+      deleteSessions: async () => {
+        deleteCalled = true;
+      },
+    },
+    confirm: () => false,
+    onSuccess: () => {
+      successCalled = true;
+    },
+    onError: () => {},
+  });
+
+  await handler();
+
+  assert.equal(deleteCalled, false);
+  assert.equal(successCalled, false);
+});
+
+test('buildBucketDeleteHandler reports errors via onError without calling onSuccess', async () => {
+  let errorMessage: string | null = null;
+  let successCalled = false;
+
+  const bucket = makeBucket([
+    makeSession({ sessionId: 1 }),
+    makeSession({ sessionId: 2 }),
+  ]);
+
+  const handler = buildBucketDeleteHandler({
+    bucket,
+    apiClient: {
+      deleteSessions: async () => {
+        throw new Error('boom');
+      },
+    },
+    confirm: () => true,
+    onSuccess: () => {
+      successCalled = true;
+    },
+    onError: (message) => {
+      errorMessage = message;
+    },
+  });
+
+  await handler();
+
+  assert.equal(errorMessage, 'boom');
+  assert.equal(successCalled, false);
+});
+
+test('buildBucketDeleteHandler falls back to a generic title when canonicalTitle is null', async () => {
+  let seenTitle: string | null = null;
+
+  const bucket = makeBucket([
+    makeSession({ sessionId: 1, canonicalTitle: null }),
+    makeSession({ sessionId: 2, canonicalTitle: null }),
+  ]);
+
+  const handler = buildBucketDeleteHandler({
+    bucket,
+    apiClient: { deleteSessions: async () => {} },
+    confirm: (title) => {
+      seenTitle = title;
+      return false;
+    },
+    onSuccess: () => {},
+    onError: () => {},
+  });
+
+  await handler();
+
+  assert.equal(seenTitle, 'this episode');
+});

stats/src/components/sessions/SessionsTab.tsx

@@ -3,8 +3,9 @@ import { useSessions } from '../../hooks/useSessions';
 import { SessionRow } from './SessionRow';
 import { SessionDetail } from './SessionDetail';
 import { apiClient } from '../../lib/api-client';
-import { confirmSessionDelete } from '../../lib/delete-confirm';
-import { formatSessionDayLabel } from '../../lib/formatters';
+import { confirmBucketDelete, confirmSessionDelete } from '../../lib/delete-confirm';
+import { formatDuration, formatNumber, formatSessionDayLabel } from '../../lib/formatters';
+import { groupSessionsByVideo, type SessionBucket } from '../../lib/session-grouping';
 import type { SessionSummary } from '../../types/stats';
 
 function groupSessionsByDay(sessions: SessionSummary[]): Map<string, SessionSummary[]> {
@@ -23,6 +24,35 @@ function groupSessionsByDay(sessions: SessionSummary[]): Map<string, SessionSumm
   return groups;
 }
 
+export interface BucketDeleteDeps {
+  bucket: SessionBucket;
+  apiClient: { deleteSessions: (ids: number[]) => Promise<void> };
+  confirm: (title: string, count: number) => boolean;
+  onSuccess: (deletedIds: number[]) => void;
+  onError: (message: string) => void;
+}
+
+/**
+ * Build a handler that deletes every session in a bucket after confirmation.
+ *
+ * Extracted as a pure factory so the deletion flow can be unit-tested without
+ * rendering the full SessionsTab or mocking React state.
+ */
+export function buildBucketDeleteHandler(deps: BucketDeleteDeps): () => Promise<void> {
+  const { bucket, apiClient: client, confirm, onSuccess, onError } = deps;
+  return async () => {
+    const title = bucket.representativeSession.canonicalTitle ?? 'this episode';
+    const ids = bucket.sessions.map((s) => s.sessionId);
+    if (!confirm(title, ids.length)) return;
+    try {
+      await client.deleteSessions(ids);
+      onSuccess(ids);
+    } catch (err) {
+      onError(err instanceof Error ? err.message : 'Failed to delete sessions.');
+    }
+  };
+}
+
 interface SessionsTabProps {
   initialSessionId?: number | null;
   onClearInitialSession?: () => void;
@@ -36,10 +66,12 @@ export function SessionsTab({
 }: SessionsTabProps = {}) {
   const { sessions, loading, error } = useSessions();
   const [expandedId, setExpandedId] = useState<number | null>(null);
+  const [expandedBuckets, setExpandedBuckets] = useState<Set<string>>(() => new Set());
   const [search, setSearch] = useState('');
   const [visibleSessions, setVisibleSessions] = useState<SessionSummary[]>([]);
   const [deleteError, setDeleteError] = useState<string | null>(null);
   const [deletingSessionId, setDeletingSessionId] = useState<number | null>(null);
+  const [deletingBucketKey, setDeletingBucketKey] = useState<string | null>(null);
 
   useEffect(() => {
     setVisibleSessions(sessions);
@@ -76,7 +108,16 @@ export function SessionsTab({
     return visibleSessions.filter((s) => s.canonicalTitle?.toLowerCase().includes(q));
   }, [visibleSessions, search]);
 
-  const groups = useMemo(() => groupSessionsByDay(filtered), [filtered]);
+  const dayGroups = useMemo(() => groupSessionsByDay(filtered), [filtered]);
+
+  const toggleBucket = (key: string) => {
+    setExpandedBuckets((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  };
 
   const handleDeleteSession = async (session: SessionSummary) => {
     if (!confirmSessionDelete()) return;
@@ -94,6 +135,33 @@ export function SessionsTab({
     }
   };
 
+  const handleDeleteBucket = async (bucket: SessionBucket) => {
+    setDeleteError(null);
+    setDeletingBucketKey(bucket.key);
+    const handler = buildBucketDeleteHandler({
+      bucket,
+      apiClient,
+      confirm: confirmBucketDelete,
+      onSuccess: (ids) => {
+        const deleted = new Set(ids);
+        setVisibleSessions((prev) => prev.filter((s) => !deleted.has(s.sessionId)));
+        setExpandedId((prev) => (prev != null && deleted.has(prev) ? null : prev));
+        setExpandedBuckets((prev) => {
+          if (!prev.has(bucket.key)) return prev;
+          const next = new Set(prev);
+          next.delete(bucket.key);
+          return next;
+        });
+      },
+      onError: (message) => setDeleteError(message),
+    });
+    try {
+      await handler();
+    } finally {
+      setDeletingBucketKey(null);
+    }
+  };
+
   if (loading) return <div className="text-ctp-overlay2 p-4">Loading...</div>;
   if (error) return <div className="text-ctp-red p-4">Error: {error}</div>;
 
@@ -110,39 +178,122 @@ export function SessionsTab({
 
       {deleteError ? <div className="text-sm text-ctp-red">{deleteError}</div> : null}
 
-      {Array.from(groups.entries()).map(([dayLabel, daySessions]) => (
-        <div key={dayLabel}>
-          <div className="flex items-center gap-3 mb-2">
-            <h3 className="text-xs font-semibold text-ctp-overlay2 uppercase tracking-widest shrink-0">
-              {dayLabel}
-            </h3>
-            <div className="flex-1 h-px bg-gradient-to-r from-ctp-surface1 to-transparent" />
-          </div>
-          <div className="space-y-2">
-            {daySessions.map((s) => {
-              const detailsId = `session-details-${s.sessionId}`;
-              return (
-                <div key={s.sessionId}>
-                  <SessionRow
-                    session={s}
-                    isExpanded={expandedId === s.sessionId}
-                    detailsId={detailsId}
-                    onToggle={() => setExpandedId(expandedId === s.sessionId ? null : s.sessionId)}
-                    onDelete={() => void handleDeleteSession(s)}
-                    deleteDisabled={deletingSessionId === s.sessionId}
-                    onNavigateToMediaDetail={onNavigateToMediaDetail}
-                  />
-                  {expandedId === s.sessionId && (
-                    <div id={detailsId}>
-                      <SessionDetail session={s} />
+      {Array.from(dayGroups.entries()).map(([dayLabel, daySessions]) => {
+        const buckets = groupSessionsByVideo(daySessions);
+        return (
+          <div key={dayLabel}>
+            <div className="flex items-center gap-3 mb-2">
+              <h3 className="text-xs font-semibold text-ctp-overlay2 uppercase tracking-widest shrink-0">
+                {dayLabel}
+              </h3>
+              <div className="flex-1 h-px bg-gradient-to-r from-ctp-surface1 to-transparent" />
+            </div>
+            <div className="space-y-2">
+              {buckets.map((bucket) => {
+                if (bucket.sessions.length === 1) {
+                  const s = bucket.sessions[0]!;
+                  const detailsId = `session-details-${s.sessionId}`;
+                  return (
+                    <div key={bucket.key}>
+                      <SessionRow
+                        session={s}
+                        isExpanded={expandedId === s.sessionId}
+                        detailsId={detailsId}
+                        onToggle={() =>
+                          setExpandedId(expandedId === s.sessionId ? null : s.sessionId)
+                        }
+                        onDelete={() => void handleDeleteSession(s)}
+                        deleteDisabled={deletingSessionId === s.sessionId}
+                        onNavigateToMediaDetail={onNavigateToMediaDetail}
+                      />
+                      {expandedId === s.sessionId && (
+                        <div id={detailsId}>
+                          <SessionDetail session={s} />
+                        </div>
+                      )}
                     </div>
-                  )}
-                </div>
-              );
-            })}
+                  );
+                }
+
+                const bucketBodyId = `session-bucket-${bucket.key}`;
+                const isExpanded = expandedBuckets.has(bucket.key);
+                const title = bucket.representativeSession.canonicalTitle ?? 'Unknown Media';
+                const deleteDisabled = deletingBucketKey === bucket.key;
+                return (
+                  <div key={bucket.key}>
+                    <div className="relative group flex items-stretch gap-2">
+                      <button
+                        type="button"
+                        onClick={() => toggleBucket(bucket.key)}
+                        aria-expanded={isExpanded}
+                        aria-controls={bucketBodyId}
+                        className="flex-1 bg-ctp-surface0 border border-ctp-surface1 rounded-lg p-3 flex items-center gap-3 hover:border-ctp-surface2 transition-colors text-left"
+                      >
+                        <div
+                          aria-hidden="true"
+                          className={`text-ctp-overlay2 text-xs shrink-0 transition-transform ${
+                            isExpanded ? 'rotate-90' : ''
+                          }`}
+                        >
+                          {'\u25B6'}
+                        </div>
+                        <div className="min-w-0 flex-1">
+                          <div className="text-sm font-medium text-ctp-text truncate">{title}</div>
+                          <div className="text-xs text-ctp-overlay2">
+                            {bucket.sessions.length} session
+                            {bucket.sessions.length === 1 ? '' : 's'} ·{' '}
+                            {formatDuration(bucket.totalActiveMs)} active ·{' '}
+                            {formatNumber(bucket.totalCardsMined)} cards
+                          </div>
+                        </div>
+                      </button>
+                      <button
+                        type="button"
+                        onClick={() => void handleDeleteBucket(bucket)}
+                        disabled={deleteDisabled}
+                        aria-label={`Delete all ${bucket.sessions.length} sessions of ${title}`}
+                        title="Delete all sessions in this group"
+                        className="shrink-0 w-8 rounded-lg border border-ctp-surface1 bg-ctp-surface0 text-ctp-overlay2 hover:border-ctp-red/50 hover:text-ctp-red hover:bg-ctp-red/10 transition-colors flex items-center justify-center disabled:opacity-40 disabled:cursor-not-allowed opacity-0 group-hover:opacity-100 focus:opacity-100"
+                      >
+                        {'\u2715'}
+                      </button>
+                    </div>
+                    {isExpanded && (
+                      <div id={bucketBodyId} className="mt-2 ml-6 space-y-2">
+                        {bucket.sessions.map((s) => {
+                          const detailsId = `session-details-${s.sessionId}`;
+                          return (
+                            <div key={s.sessionId}>
+                              <SessionRow
+                                session={s}
+                                isExpanded={expandedId === s.sessionId}
+                                detailsId={detailsId}
+                                onToggle={() =>
+                                  setExpandedId(
+                                    expandedId === s.sessionId ? null : s.sessionId,
+                                  )
+                                }
+                                onDelete={() => void handleDeleteSession(s)}
+                                deleteDisabled={deletingSessionId === s.sessionId}
+                                onNavigateToMediaDetail={onNavigateToMediaDetail}
+                              />
+                              {expandedId === s.sessionId && (
+                                <div id={detailsId}>
+                                  <SessionDetail session={s} />
+                                </div>
+                              )}
+                            </div>
+                          );
+                        })}
+                      </div>
+                    )}
+                  </div>
+                );
+              })}
+            </div>
           </div>
-        </div>
-      ))}
+        );
+      })}
 
       {filtered.length === 0 && (
         <div className="text-ctp-overlay2 text-sm">

stats/src/components/trends/DateRangeSelector.tsx

@@ -53,7 +53,7 @@ export function DateRangeSelector({
     <div className="flex items-center gap-4 text-sm">
       <SegmentedControl
         label="Range"
-        options={['7d', '30d', '90d', 'all'] as TimeRange[]}
+        options={['7d', '30d', '90d', '365d', 'all'] as TimeRange[]}
         value={range}
         onChange={onRangeChange}
         formatLabel={(r) => (r === 'all' ? 'All' : r)}

stats/src/components/trends/StackedTrendChart.tsx

@@ -1,4 +1,13 @@
-import { AreaChart, Area, XAxis, YAxis, Tooltip, ResponsiveContainer } from 'recharts';
+import {
+  AreaChart,
+  Area,
+  CartesianGrid,
+  XAxis,
+  YAxis,
+  Tooltip,
+  ResponsiveContainer,
+} from 'recharts';
+import { CHART_DEFAULTS, CHART_THEME, TOOLTIP_CONTENT_STYLE } from '../../lib/chart-theme';
 import { epochDayToDate } from '../../lib/formatters';
 
 export interface PerAnimeDataPoint {
@@ -64,14 +73,6 @@ export function StackedTrendChart({ title, data, colorPalette }: StackedTrendCha
   const { points, seriesKeys } = buildLineData(data);
   const colors = colorPalette ?? DEFAULT_LINE_COLORS;
 
-  const tooltipStyle = {
-    background: '#363a4f',
-    border: '1px solid #494d64',
-    borderRadius: 6,
-    color: '#cad3f5',
-    fontSize: 12,
-  };
-
   if (points.length === 0) {
     return (
       <div className="bg-ctp-surface0 border border-ctp-surface1 rounded-lg p-4">
@@ -84,21 +85,22 @@ export function StackedTrendChart({ title, data, colorPalette }: StackedTrendCha
   return (
     <div className="bg-ctp-surface0 border border-ctp-surface1 rounded-lg p-4">
       <h3 className="text-xs font-semibold text-ctp-text mb-2">{title}</h3>
-      <ResponsiveContainer width="100%" height={120}>
-        <AreaChart data={points}>
+      <ResponsiveContainer width="100%" height={CHART_DEFAULTS.height}>
+        <AreaChart data={points} margin={CHART_DEFAULTS.margin}>
+          <CartesianGrid stroke={CHART_THEME.grid} {...CHART_DEFAULTS.grid} />
           <XAxis
             dataKey="label"
-            tick={{ fontSize: 9, fill: '#a5adcb' }}
-            axisLine={false}
+            tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+            axisLine={{ stroke: CHART_THEME.axisLine }}
             tickLine={false}
           />
           <YAxis
-            tick={{ fontSize: 9, fill: '#a5adcb' }}
-            axisLine={false}
+            tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+            axisLine={{ stroke: CHART_THEME.axisLine }}
             tickLine={false}
-            width={28}
+            width={32}
           />
-          <Tooltip contentStyle={tooltipStyle} />
+          <Tooltip contentStyle={TOOLTIP_CONTENT_STYLE} />
           {seriesKeys.map((key, i) => (
             <Area
               key={key}

stats/src/components/trends/TrendChart.tsx

@@ -6,8 +6,10 @@ import {
   XAxis,
   YAxis,
   Tooltip,
+  CartesianGrid,
   ResponsiveContainer,
 } from 'recharts';
+import { CHART_DEFAULTS, CHART_THEME, TOOLTIP_CONTENT_STYLE } from '../../lib/chart-theme';
 
 interface TrendChartProps {
   title: string;
@@ -19,35 +21,29 @@ interface TrendChartProps {
 }
 
 export function TrendChart({ title, data, color, type, formatter, onBarClick }: TrendChartProps) {
-  const tooltipStyle = {
-    background: '#363a4f',
-    border: '1px solid #494d64',
-    borderRadius: 6,
-    color: '#cad3f5',
-    fontSize: 12,
-  };
-
   const formatValue = (v: number) => (formatter ? [formatter(v), title] : [String(v), title]);
 
   return (
     <div className="bg-ctp-surface0 border border-ctp-surface1 rounded-lg p-4">
       <h3 className="text-xs font-semibold text-ctp-text mb-2">{title}</h3>
-      <ResponsiveContainer width="100%" height={120}>
+      <ResponsiveContainer width="100%" height={CHART_DEFAULTS.height}>
         {type === 'bar' ? (
-          <BarChart data={data}>
+          <BarChart data={data} margin={CHART_DEFAULTS.margin}>
+            <CartesianGrid stroke={CHART_THEME.grid} {...CHART_DEFAULTS.grid} />
             <XAxis
               dataKey="label"
-              tick={{ fontSize: 9, fill: '#a5adcb' }}
-              axisLine={false}
+              tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+              axisLine={{ stroke: CHART_THEME.axisLine }}
               tickLine={false}
             />
             <YAxis
-              tick={{ fontSize: 9, fill: '#a5adcb' }}
-              axisLine={false}
+              tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+              axisLine={{ stroke: CHART_THEME.axisLine }}
               tickLine={false}
-              width={28}
+              width={32}
+              tickFormatter={formatter}
             />
-            <Tooltip contentStyle={tooltipStyle} formatter={formatValue} />
+            <Tooltip contentStyle={TOOLTIP_CONTENT_STYLE} formatter={formatValue} />
             <Bar
               dataKey="value"
               fill={color}
@@ -59,20 +55,22 @@ export function TrendChart({ title, data, color, type, formatter, onBarClick }:
             />
           </BarChart>
         ) : (
-          <LineChart data={data}>
+          <LineChart data={data} margin={CHART_DEFAULTS.margin}>
+            <CartesianGrid stroke={CHART_THEME.grid} {...CHART_DEFAULTS.grid} />
             <XAxis
               dataKey="label"
-              tick={{ fontSize: 9, fill: '#a5adcb' }}
-              axisLine={false}
+              tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+              axisLine={{ stroke: CHART_THEME.axisLine }}
               tickLine={false}
             />
             <YAxis
-              tick={{ fontSize: 9, fill: '#a5adcb' }}
-              axisLine={false}
+              tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }}
+              axisLine={{ stroke: CHART_THEME.axisLine }}
               tickLine={false}
-              width={28}
+              width={32}
+              tickFormatter={formatter}
             />
-            <Tooltip contentStyle={tooltipStyle} formatter={formatValue} />
+            <Tooltip contentStyle={TOOLTIP_CONTENT_STYLE} formatter={formatValue} />
             <Line dataKey="value" stroke={color} strokeWidth={2} dot={false} />
           </LineChart>
         )}

stats/src/components/trends/TrendsTab.tsx

@@ -221,7 +221,7 @@ export function TrendsTab() {
           type="line"
         />
 
-        <SectionHeader>Anime — Per Day</SectionHeader>
+        <SectionHeader>Library — Per Day</SectionHeader>
         <AnimeVisibilityFilter
           animeTitles={animeTitles}
           hiddenAnime={activeHiddenAnime}
@@ -239,21 +239,21 @@ export function TrendsTab() {
             })
           }
         />
-        <StackedTrendChart title="Episodes per Anime" data={filteredEpisodesPerAnime} />
-        <StackedTrendChart title="Watch Time per Anime (min)" data={filteredWatchTimePerAnime} />
+        <StackedTrendChart title="Videos per Title" data={filteredEpisodesPerAnime} />
+        <StackedTrendChart title="Watch Time per Title (min)" data={filteredWatchTimePerAnime} />
         <StackedTrendChart
-          title="Cards Mined per Anime"
+          title="Cards Mined per Title"
           data={filteredCardsPerAnime}
           colorPalette={cardsMinedStackedColors}
         />
-        <StackedTrendChart title="Words Seen per Anime" data={filteredWordsPerAnime} />
-        <StackedTrendChart title="Lookups per Anime" data={filteredLookupsPerAnime} />
+        <StackedTrendChart title="Words Seen per Title" data={filteredWordsPerAnime} />
+        <StackedTrendChart title="Lookups per Title" data={filteredLookupsPerAnime} />
         <StackedTrendChart
-          title="Lookups/100w per Anime"
+          title="Lookups/100w per Title"
           data={filteredLookupsPerHundredPerAnime}
         />
 
-        <SectionHeader>Anime — Cumulative</SectionHeader>
+        <SectionHeader>Library — Cumulative</SectionHeader>
         <StackedTrendChart title="Watch Time Progress (min)" data={filteredWatchTimeProgress} />
         <StackedTrendChart title="Episodes Progress" data={filteredAnimeProgress} />
         <StackedTrendChart