feat(tokenizer): use Yomitan word classes for subtitle POS filtering

- Carry matched headword wordClasses from termsFind into YomitanScanToken
- Map recognized Yomitan wordClasses to SubMiner coarse POS before annotation
- MeCab enrichment now fills only missing POS fields, preserving existing coarse pos1
- Exclude standalone grammar particles, して helper fragments, and single-kana surfaces from annotations
- Respect source-text punctuation gaps when counting N+1 sentence words
- Preserve known-word highlight on excluded kanji-containing tokens
- Add backlog tasks 304 (N+1 boundary bug) and 305 (wordClasses POS, done)

.github/workflows/prerelease.yml

@@ -0,0 +1,406 @@
+name: Prerelease
+
+on:
+  push:
+    tags:
+      - 'v*-beta.*'
+      - 'v*-rc.*'
+
+concurrency:
+  group: prerelease-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats
+
+      - name: Build (TypeScript check)
+        run: bun run typecheck
+
+      - name: Test suite (source)
+        run: bun run test:fast
+
+      - name: Environment suite
+        run: bun run test:env
+
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
+      - name: Launcher smoke suite (source)
+        run: bun run test:launcher:smoke:src
+
+      - name: Upload launcher smoke artifacts (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
+          if-no-files-found: ignore
+
+      - name: Build (bundle)
+        run: bun run build
+
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
+      - name: Dist smoke suite
+        run: bun run test:smoke:dist
+
+  build-linux:
+    needs: [quality-gate]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build AppImage
+        run: bun run build:appimage
+
+      - name: Build unversioned AppImage
+        run: |
+          shopt -s nullglob
+          appimages=(release/SubMiner-*.AppImage)
+          if [ "${#appimages[@]}" -eq 0 ]; then
+            echo "No versioned AppImage found to create unversioned artifact."
+            ls -la release
+            exit 1
+          fi
+          cp "${appimages[0]}" release/SubMiner.AppImage
+
+      - name: Upload AppImage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: appimage
+          path: release/*.AppImage
+          if-no-files-found: error
+
+  build-macos:
+    needs: [quality-gate]
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Validate macOS signing/notarization secrets
+        run: |
+          missing=0
+          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
+            if [ -z "${!name}" ]; then
+              echo "Missing required secret: $name"
+              missing=1
+            fi
+          done
+          if [ "$missing" -ne 0 ]; then
+            echo "Set all required macOS signing/notarization secrets and rerun."
+            exit 1
+          fi
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build signed + notarized macOS artifacts
+        run: bun run build:mac
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Upload macOS artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos
+          path: |
+            release/*.dmg
+            release/*.zip
+          if-no-files-found: error
+
+  build-windows:
+    needs: [quality-gate]
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        shell: powershell
+        run: |
+          Set-Location vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build unsigned Windows artifacts
+        run: bun run build:win:unsigned
+
+      - name: Upload Windows artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows
+          path: |
+            release/*.exe
+            release/*.zip
+          if-no-files-found: error
+
+  release:
+    needs: [build-linux, build-macos, build-windows]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download AppImage
+        uses: actions/download-artifact@v4
+        with:
+          name: appimage
+          path: release
+
+      - name: Download macOS artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: macos
+          path: release
+
+      - name: Download Windows artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: windows
+          path: release
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build Bun subminer wrapper
+        run: make build-launcher
+
+      - name: Verify Bun subminer wrapper
+        run: dist/launcher/subminer --help >/dev/null
+
+      - name: Enforce generated launcher workflow
+        run: bash scripts/verify-generated-launcher.sh
+
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
+      - name: Package optional assets bundle
+        run: |
+          tar -czf "release/subminer-assets.tar.gz" \
+            config.example.jsonc \
+            plugin/subminer \
+            plugin/subminer.conf \
+            assets/themes/subminer.rasi
+
+      - name: Generate checksums
+        run: |
+          shopt -s nullglob
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz dist/launcher/subminer)
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No release artifacts found for checksum generation."
+            exit 1
+          fi
+          : > release/SHA256SUMS.txt
+          for file in "${files[@]}"; do
+            printf '%s  %s\n' \
+              "$(sha256sum "$file" | awk '{print $1}')" \
+              "${file##*/}" >> release/SHA256SUMS.txt
+          done
+
+      - name: Get version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate prerelease notes from pending fragments
+        run: bun run changelog:prerelease-notes --version "${{ steps.version.outputs.VERSION }}"
+
+      - name: Publish Prerelease
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          shopt -s nullglob
+          artifacts=(
+            release/*.AppImage
+            release/*.dmg
+            release/*.exe
+            release/*.zip
+            release/*.tar.gz
+            release/SHA256SUMS.txt
+            dist/launcher/subminer
+          )
+
+          if [ "${#artifacts[@]}" -eq 0 ]; then
+            echo "No release artifacts found for upload."
+            exit 1
+          fi
+
+          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
+            gh release edit "${{ steps.version.outputs.VERSION }}" \
+              --draft \
+              --prerelease \
+              --title "${{ steps.version.outputs.VERSION }}" \
+              --notes-file release/prerelease-notes.md
+          else
+            gh release create "${{ steps.version.outputs.VERSION }}" \
+              --draft \
+              --latest=false \
+              --prerelease \
+              --title "${{ steps.version.outputs.VERSION }}" \
+              --notes-file release/prerelease-notes.md
+          fi
+
+          for asset in "${artifacts[@]}"; do
+            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+          done
+
+          gh release edit "${{ steps.version.outputs.VERSION }}" \
+            --draft=false \
+            --prerelease \
+            --title "${{ steps.version.outputs.VERSION }}" \
+            --notes-file release/prerelease-notes.md

.github/workflows/release.yml

@@ -4,6 +4,8 @@ on:
   push:
     tags:
       - 'v*'
+      - '!v*-beta.*'
+      - '!v*-rc.*'
 
 concurrency:
   group: release-${{ github.ref }}
@@ -338,7 +340,12 @@ jobs:
             echo "No release artifacts found for checksum generation."
             exit 1
           fi
-          sha256sum "${files[@]}" > release/SHA256SUMS.txt
+          : > release/SHA256SUMS.txt
+          for file in "${files[@]}"; do
+            printf '%s  %s\n' \
+              "$(sha256sum "$file" | awk '{print $1}')" \
+              "${file##*/}" >> release/SHA256SUMS.txt
+          done
 
       - name: Get version from tag
         id: version

CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## v0.12.0 (2026-04-11)
+
+### Changed
+- Overlay: Added configurable overlay shortcuts for session help, controller select, and controller debug actions.
+- Overlay: Added mpv/plugin and CLI routing for session help, controller utilities, and subtitle sidebar toggling through the shared session-action path.
+- Overlay: Improved dedicated overlay modal retry and focus handling for runtime options, Jimaku, session help, controller tools, and the playlist browser.
+- Overlay: Fixed controller configuration and controller debug shortcut opens so configured bindings bring up their modals again instead of tripping renderer recovery.
+- Stats: Sessions are rolled up per episode within each day, with a bulk delete that wipes every session in the group.
+- Stats: Trends add a 365-day range next to the existing 7d/30d/90d/all options.
+- Stats: Library detail view gets a delete-episode action that removes the video and all its sessions.
+- Stats: Vocabulary Top 50 tightens the word/reading column so katakana entries no longer push the scores off screen.
+- Stats: Episode detail hides card events whose Anki notes have been deleted, instead of showing phantom mining activity.
+- Stats: Trend and watch-time charts share a unified theme with horizontal gridlines and larger ticks for legibility.
+- Stats: Overview, Library, Trends, Sessions, and Vocabulary now use generic "title" wording so YouTube videos and anime live comfortably side by side in the dashboard.
+- Stats: Session timeline no longer plots seek-forward/seek-backward markers — they were too noisy on sessions with lots of rewinds.
+- Stats: Replaced the "Library — Per Day" section on the Stats → Trends page with a "Library — Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.
+
+### Fixed
+- Overlay: Fixed overlay drag-and-drop routing so dropping external subtitle files like `.ass` onto mpv still loads them when the overlay is visible.
+- Overlay: Addressed the latest CodeRabbit follow-ups on PR #49, including generation-scoped Lua session binding names, stricter session command validation, session-help shortcut visibility, the numeric-selection key guard, stats-overlay startup classification, and safer session-binding persistence.
+- Overlay: Addressed the latest CodeRabbit follow-ups on the Windows overlay flow, including exact mpv target resolution, lower-overlay helper arguments, Win32 failure detection, and overlay cleanup on tracker loss.
+- Overlay: Fixed Windows overlay z-order so the visible subtitle overlay stops staying above unrelated apps after mpv loses focus.
+- Overlay: Fixed Windows overlay tracking to use native window polling and owner/z-order binding, which keeps the subtitle overlay aligned to the active mpv window more reliably.
+- Overlay: Fixed Windows overlay hide/restore behavior so minimizing mpv immediately hides the overlay and restoring mpv brings it back on top of the mpv window without requiring a click.
+- Overlay: Fixed stats overlay layering so the in-player stats page now stays above mpv and the subtitle overlay while it is open.
+- Overlay: Fixed Windows subtitle overlay stability so transient tracker misses and restore events keep the current subtitle visible instead of waiting for the next subtitle line.
+- Overlay: Fixed Windows focus handoff from the interactive subtitle overlay back to mpv so the overlay no longer drops behind mpv and briefly disappears.
+- Overlay: Fixed Windows visible-overlay startup so it no longer briefly opens as an interactive or opaque surface before the tracked transparent overlay state settles.
+- Overlay: Fixed spurious auto-pause after overlay visibility recovery and window resize so the overlay no longer pauses mpv until the pointer genuinely re-enters the subtitle area.
+- Overlay: Fixed Windows secondary subtitle hover mode so the expanded hover hit area no longer blocks the native minimize, maximize, and close buttons.
+- Overlay: Fixed Windows Yomitan popup focus loss after closing nested lookups so the original popup stays interactive instead of falling through to mpv.
+- Stats: Fixed immersion-tracker timestamp handling under Bun/libsql so library rows, session timelines, and lifetime summaries keep real wall-clock millisecond values instead of truncating to invalid negative timestamps.
+- Mpv Plugin: Fixed the mpv Lua plugin so hover and environment modules no longer use the `goto continue` pattern that can fail to parse on some user Lua runtimes.
+
+### Internal
+- Release: Added a dedicated beta/rc prerelease GitHub Actions workflow that publishes GitHub prereleases without consuming pending changelog fragments or updating AUR.
+- Release: Added prerelease note generation so beta and release-candidate tags can reuse the current pending `changes/*.md` fragments while leaving stable changelog publication for the final release cut.
+
 ## v0.11.2 (2026-04-07)
 
 ### Changed

backlog/tasks/task-285 - Investigate-inconsistent-mpv-y-t-overlay-toggle-after-menu-toggle.md

@@ -0,0 +1,54 @@
+---
+id: TASK-285
+title: Investigate inconsistent mpv y-t overlay toggle after menu toggle
+status: To Do
+assignee: []
+created_date: '2026-04-07 22:55'
+updated_date: '2026-04-07 22:55'
+labels:
+  - bug
+  - overlay
+  - keyboard
+  - mpv
+dependencies: []
+references:
+  - plugin/subminer/process.lua
+  - plugin/subminer/ui.lua
+  - src/renderer/handlers/keyboard.ts
+  - src/main/runtime/autoplay-ready-gate.ts
+  - src/core/services/overlay-window-input.ts
+  - backlog/tasks/task-248 - Fix-macOS-visible-overlay-toggle-getting-immediately-restored.md
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+User report: toggling the visible overlay with mpv `y-t` is inconsistent. After manually toggling through the `y-y` menu, `y-t` may allow one hide, but after toggling back on it can stop hiding the overlay again, forcing the user back into the menu path.
+
+Initial assessment:
+
+- no active backlog item currently tracks this exact report
+- nearest prior work is `TASK-248`, which fixed a macOS-specific visible-overlay restore bug and is marked done
+- current targeted regressions for the old fix surface pass, including plugin ready-signal suppression, focused-overlay `y-t` proxy dispatch, autoplay-ready gate deduplication, and blur-path restacking guards
+
+This should be treated as a fresh investigation unless reproduction proves it is the same closed macOS issue resurfacing on the current build.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Reproduce the reported `y-t` / `y-y` inconsistency on the affected platform and identify the exact event sequence
+- [ ] #2 Determine whether the failure is in mpv plugin command dispatch, focused-overlay key forwarding, or main-process visible-overlay state transitions
+- [ ] #3 Fix the inconsistency so repeated hide/show/hide cycles work from `y-t` without requiring menu recovery
+- [ ] #4 Add regression coverage for the reproduced failing sequence
+- [ ] #5 Record whether this is a regression of `TASK-248` or a distinct bug
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Reproduce the report with platform/build details and capture whether the failing `y-t` press originates in raw mpv or the focused overlay y-chord proxy path.
+2. Trace visible-overlay state mutations across plugin toggle commands, autoplay-ready callbacks, and main-process visibility/window blur handling.
+3. Patch the narrowest failing path and add regression coverage for the exact hide/show/hide sequence.
+4. Re-run targeted plugin, overlay visibility, overlay window, and renderer keyboard suites before broader verification.
+<!-- SECTION:PLAN:END -->

backlog/tasks/task-286 - Assess-and-address-PR-49-CodeRabbit-review-follow-ups.md

@@ -0,0 +1,63 @@
+---
+id: TASK-286
+title: 'Assess and address PR #49 CodeRabbit review follow-ups'
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-11 18:55'
+updated_date: '2026-04-11 22:40'
+labels:
+  - bug
+  - code-review
+  - windows
+  - overlay
+dependencies: []
+references:
+  - src/main/runtime/config-hot-reload-handlers.ts
+  - src/renderer/handlers/keyboard.ts
+  - src/renderer/handlers/mouse.ts
+  - vendor/subminer-yomitan
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Track the current PR #49 review round and resolve the actionable CodeRabbit findings on the Windows update branch.
+
+Focus areas include the renderer mouse interaction fix, config hot-reload keyboard state, and any other review items that still apply after verifying the current branch state.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 All actionable CodeRabbit comments on PR #49 are either fixed or shown to be obsolete with evidence.
+- [x] #2 Regression tests are added or updated for any behavior change that could regress.
+- [x] #3 The branch passes the repo's relevant verification checks for the touched areas.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Pull the current unresolved CodeRabbit review threads for PR #49 and cluster them into still-actionable fixes versus obsolete/nit-only items.
+2. For each still-actionable behavior bug, add or extend the narrowest failing test first in the touched suite before changing production code.
+3. Implement the minimal fixes across the affected runtime, renderer, plugin, IPC, and Windows tracker files, keeping each change traceable to the review thread.
+4. Run targeted verification for the touched areas, update task notes with assessment results, and capture which review comments were fixed versus assessed as obsolete or deferred nitpicks.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Assessed PR #49 CodeRabbit threads. Fixed the real regressions in first-run CLI gating, IPC session-action validation, renderer controller-modal lifecycle notifications, async subtitle-sidebar toggle guarding, plugin config-dir resolution priority, prerelease artifact upload failure handling, immersion tracker lazy startup, win32 z-order error handling, and Windows socket-aware mpv matching.
+
+Review assessment: the overlay-shortcut lifecycle comment is obsolete for the current architecture because overlay-local shortcuts are intentionally handled through the local fallback path and the runtime only tracks configured-state/cleanup. Refactor-only nit comments for splitting `scripts/build-changelog.ts` and `src/core/services/session-bindings.ts` were left as follow-up quality work, not behavior bugs in this PR round.
+
+Verification: `bun test src/main/runtime/first-run-setup-service.test.ts src/core/services/session-bindings.test.ts src/core/services/app-ready.test.ts src/core/services/ipc.test.ts src/renderer/handlers/keyboard.test.ts src/main/overlay-runtime.test.ts src/window-trackers/mpv-socket-match.test.ts`, `bun test src/window-trackers/windows-tracker.test.ts`, `bun run typecheck`, `lua scripts/test-plugin-lua-compat.lua`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Assessed the current CodeRabbit round on PR #49 and addressed the still-valid behavior issues rather than blanket-applying every bot suggestion. The branch now treats the new session/stats CLI flags as explicit startup commands during first-run setup, validates the new session actions through IPC, points session-binding command diagnostics at the correct config field, keeps immersion tracker startup lazy until later runtime triggers, and notifies overlay modal lifecycle state when controller-select/debug are opened from local keyboard bindings. I also switched the subtitle-sidebar IPC callback to the async guarded path so promise rejections feed renderer recovery instead of being dropped.
+
+On the Windows/plugin side, the mpv plugin now prefers config-file matches before falling back to an existing config directory, prerelease workflow uploads fail if expected Linux/macOS artifacts are missing, the Win32 z-order bind path now validates the `GetWindowLongW` call for the window above mpv, and the Windows tracker now passes the target socket path into native polling and filters mpv instances by command line so multiple sockets can be distinguished on Windows. Added/updated regression coverage for first-run gating, IPC validation, session-binding diagnostics, controller modal lifecycle notifications, modal ready-listener dispatch, and socket-path matching. Verification run: `bun run typecheck`, the targeted Bun test suites for the touched areas, `bun test src/window-trackers/windows-tracker.test.ts`, and `lua scripts/test-plugin-lua-compat.lua`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-286.1 - Assess-and-address-PR-49-subsequent-CodeRabbit-review-round.md

@@ -0,0 +1,61 @@
+---
+id: TASK-286.1
+title: 'Assess and address PR #49 subsequent CodeRabbit review round'
+status: Done
+assignee: []
+created_date: '2026-04-11 23:14'
+updated_date: '2026-04-11 23:16'
+labels:
+  - bug
+  - code-review
+  - windows
+  - release
+dependencies: []
+references:
+  - .github/workflows/prerelease.yml
+  - src/window-trackers/mpv-socket-match.ts
+  - src/window-trackers/win32.ts
+  - src/core/services/overlay-shortcut.ts
+parent_task_id: TASK-286
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Track the next unresolved CodeRabbit review threads on PR #49 after commit 9ce5de2f and resolve the still-valid follow-up issues without reopening already-assessed stale comments.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 All still-actionable CodeRabbit comments in the latest PR #49 round are fixed or explicitly shown stale with evidence.
+- [x] #2 Regression coverage is added or updated for any behavior-sensitive fix in workflow or Windows socket matching.
+- [x] #3 Relevant verification passes for the touched workflow, tracker, and shared matcher changes.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Verify the five unresolved CodeRabbit threads against current branch state and separate still-valid bugs from stale comments.
+2. Add or extend the narrowest failing tests for exact socket-path matching and prerelease workflow invariants before changing production code.
+3. Implement minimal fixes in the prerelease workflow and Windows socket matching/cache path, leaving stale comments documented with evidence instead of forcing no-op changes.
+4. Run targeted verification, then record the fixed-vs-stale assessment and close the subtask.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Assessed five unresolved PR #49 threads after 9ce5de2f. Fixed prerelease workflow cache keys to include `runner.arch`, changed prerelease publishing to validate artifacts before release creation/edit and only undraft after uploads complete, tightened Windows socket matching to require exact argument boundaries, and stopped memoizing null command-line lookup misses in the Win32 cache path.
+
+Stale assessment: the `src/core/services/overlay-shortcut.ts` thread is still obsolete. Current code at `registerOverlayShortcuts()` returns `hasConfiguredOverlayShortcuts(shortcuts)`, not `false`, and the overlay-local handling remains intentionally driven by local fallback dispatch rather than global registration in this runtime path.
+
+Verification: `bun test src/prerelease-workflow.test.ts src/window-trackers/mpv-socket-match.test.ts`, `bun test src/window-trackers/windows-tracker.test.ts src/prerelease-workflow.test.ts src/window-trackers/mpv-socket-match.test.ts`, `bun run typecheck`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Handled the next CodeRabbit round on PR #49 by fixing the still-valid prerelease workflow and Windows socket-matching issues while documenting the stale overlay-shortcut comment instead of forcing a no-op code change. The prerelease workflow now scopes all dependency caches by `runner.arch`, validates the final artifact set before touching the GitHub release, creates/edits the prerelease as a draft during uploads, and only flips `--draft=false` after all assets succeed. On Windows, socket matching now requires an exact `--input-ipc-server` argument boundary so `subminer-1` no longer matches `subminer-10`, and transient PowerShell/CIM misses no longer get cached forever as null command lines.
+
+Regression coverage was added for the workflow invariants and exact socket matching. Verification passed with targeted prerelease workflow tests, Windows tracker tests, socket-matcher tests, and `bun run typecheck`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-286.2 - Assess-and-address-PR-49-next-CodeRabbit-review-round.md

@@ -0,0 +1,49 @@
+---
+id: TASK-286.2
+title: 'Assess and address PR #49 next CodeRabbit review round'
+status: Done
+assignee: []
+created_date: '2026-04-12 02:50'
+updated_date: '2026-04-12 02:52'
+labels:
+  - bug
+  - code-review
+  - release
+  - testing
+dependencies: []
+references:
+  - .github/workflows/prerelease.yml
+  - src/prerelease-workflow.test.ts
+  - src/core/services/overlay-shortcut.ts
+parent_task_id: TASK-286
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Track the next unresolved CodeRabbit review threads on PR #49 after commit 62ad77dc and resolve the still-valid follow-up issues while documenting stale repeats.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 All still-actionable CodeRabbit comments in the latest PR #49 round are fixed or explicitly shown stale with evidence.
+- [x] #2 Regression coverage is updated for any workflow or test changes made in this round.
+- [x] #3 Relevant verification passes for the touched workflow and prerelease test changes.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Assessed latest unresolved CodeRabbit round on PR #49. `src/core/services/overlay-shortcut.ts` comment is stale: `registerOverlayShortcuts()` returns `hasConfiguredOverlayShortcuts(shortcuts)`, so runtime registration is not hard-coded false.
+
+Added exact, line-ending-agnostic prerelease tag trigger assertions in `src/prerelease-workflow.test.ts` and a regression asserting `bun run test:env` sits in the prerelease quality gate before source coverage.
+
+Updated `.github/workflows/prerelease.yml` quality-gate to run `bun run test:env` after `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Assessed the latest CodeRabbit round for PR #49. Left the `overlay-shortcut.ts` thread open as stale with code evidence, tightened prerelease workflow trigger coverage, and added the missing `test:env` step to the prerelease quality gate. Verification: `bun test src/prerelease-workflow.test.ts`; `bun run typecheck`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-286.3 - Assess-and-address-PR-49-latest-CodeRabbit-review-round.md

@@ -0,0 +1,48 @@
+---
+id: TASK-286.3
+title: 'Assess and address PR #49 latest CodeRabbit review round'
+status: Done
+assignee: []
+created_date: '2026-04-12 03:08'
+updated_date: '2026-04-12 03:09'
+labels:
+  - bug
+  - code-review
+  - testing
+dependencies: []
+references:
+  - 'PR #49'
+  - .github/workflows/prerelease.yml
+  - src
+parent_task_id: TASK-286
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Track the newest unresolved CodeRabbit review threads on PR #49 after commit 942c1649, fix the still-valid issues, verify them, and push the branch update.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 All still-actionable CodeRabbit comments in the newest PR #49 round are fixed or explicitly identified stale with evidence.
+- [x] #2 Regression coverage is added or updated for behavior touched in this round.
+- [x] #3 Relevant verification passes before commit and push.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Fetched the newest unresolved CodeRabbit threads for PR #49 after commit `942c1649`; only one unresolved actionable thread remained, on prerelease checksum output using repo-relative paths instead of asset basenames.
+
+Added regression coverage in `src/prerelease-workflow.test.ts` and `src/release-workflow.test.ts` asserting checksum generation truncates to asset basenames and no longer writes the raw `sha256sum "${files[@]}" > release/SHA256SUMS.txt` form.
+
+Updated both `.github/workflows/prerelease.yml` and `.github/workflows/release.yml` checksum generation steps to iterate over the `files` array and write `SHA256  basename` lines into `release/SHA256SUMS.txt`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Resolved the latest CodeRabbit round for PR #49 by fixing checksum generation to emit basename-oriented `SHA256SUMS.txt` entries in both prerelease and release workflows, with matching regression coverage. Verification: `bun test src/prerelease-workflow.test.ts src/release-workflow.test.ts`; `bun run typecheck`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-287 - Restore-Lua-parser-compatibility-for-mpv-plugin-modules.md

@@ -0,0 +1,44 @@
+---
+id: TASK-287
+title: Restore Lua parser compatibility for mpv plugin modules
+status: Done
+assignee: []
+created_date: '2026-04-11 21:25'
+updated_date: '2026-04-11 21:29'
+labels:
+  - bug
+  - mpv-plugin
+  - lua
+dependencies: []
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Users with Lua runtimes that do not accept the current `goto continue` pattern in the mpv plugin should be able to load the plugin without syntax errors. Remove the parser-incompatible control-flow usage from the affected plugin modules without changing plugin behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The mpv plugin source no longer relies on parser-incompatible `goto continue` labels in the affected Lua modules.
+- [x] #2 Automated coverage fails on the old parser-incompatible source and passes once the compatibility fix is in place.
+- [x] #3 Existing plugin start/gate verification still passes after the compatibility fix.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Reused existing local cleanups in `plugin/subminer/hover.lua` and `plugin/subminer/environment.lua` to remove `goto continue` / `::continue::` control flow without behavior changes.
+
+Added `scripts/test-plugin-lua-compat.lua` and wired it into `test:plugin:src`; the regression checks reject the legacy pattern structurally and verify parse success with `luajit` when available.
+
+Verification run on 2026-04-11: `lua scripts/test-plugin-lua-compat.lua` ✅, `bun run test:plugin:src` ✅, `bun run changelog:lint` ✅, `bun run typecheck` ✅, `bun run test:env` ✅, `bun run build` ✅, `bun run test:smoke:dist` ✅.
+
+`bun run test:fast` remains red for unrelated existing immersion-tracker assertions in `src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts` and `src/core/services/immersion-tracker/__tests__/query.test.ts` (`tsMs`/`lastWatchedMs` observed as `-2147483648`).
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Removed parser-incompatible `goto continue` usage from the affected mpv Lua plugin modules, added a dedicated Lua compatibility regression script to the plugin test lane, and added a changelog fragment for the user-visible fix. Requested plugin verification is green; unrelated existing `test:fast` immersion-tracker failures remain outside this task.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-288 - Stabilize-immersion-tracker-CI-timestamp-handling-under-libsql-Bun.md

@@ -0,0 +1,42 @@
+---
+id: TASK-288
+title: Stabilize immersion-tracker CI timestamp handling under libsql/Bun
+status: Done
+assignee: []
+created_date: '2026-04-11 21:34'
+updated_date: '2026-04-11 21:43'
+labels:
+  - bug
+  - ci
+  - immersion-tracker
+dependencies: []
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+`bun run test:fast` is currently failing because large millisecond timestamps are not handled safely through the libsql/Bun path. Fix timestamp parsing/storage so lifetime/library and session-event queries return correct wall-clock values in CI and runtime.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Large wall-clock timestamps round-trip correctly through immersion-tracker lifetime/library queries under the repo's Bun/libsql runtime.
+- [x] #2 Session-event timestamps round-trip correctly for real wall-clock values used by runtime event inserts.
+- [x] #3 Targeted immersion-tracker regression coverage passes, and the previously failing `test:fast` lane no longer fails on these timestamp assertions.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Root cause split in two places: Bun/libsql corrupts large millisecond timestamp strings when coerced through `Number(...)`, and `imm_session_events.ts_ms` being `INTEGER` let runtime event inserts/readbacks return `-2147483648` on CI/runtime.
+
+Fix shipped by parsing timestamp strings without the broken `Number(largeString)` path, migrating `imm_session_events.ts_ms` to `TEXT`, ordering/retention queries via `CAST(ts_ms AS REAL)`, and avoiding `Number(currentMs)` when reusing already-normalized timestamp strings.
+
+Added regression coverage for both real runtime event inserts and schema migration/repair of previously truncated session-event rows.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed immersion-tracker timestamp handling under Bun/libsql so large wall-clock millisecond values survive runtime writes, query reads, and schema migration. `bun run test:fast`, `bun run typecheck`, `bun run test:env`, `bun run build`, `bun run test:smoke:dist`, and `bun run changelog:lint` all pass after the patch.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-289 - Finish-current-windows-qol-rebase.md

@@ -0,0 +1,33 @@
+---
+id: TASK-289
+title: Finish current windows-qol rebase
+status: Done
+assignee: []
+created_date: '2026-04-11 22:07'
+updated_date: '2026-04-11 22:08'
+labels:
+  - maintenance
+  - rebase
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Resolve the in-progress rebase on `windows-qol` and ensure the branch lands cleanly.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Interactive rebase completes without conflicts.
+- [x] #2 Working tree is clean after the rebase finishes.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Completed the interactive rebase on `windows-qol` and resolved the transient editor-blocked `git rebase --continue` step. Branch now rebased cleanly onto `49e46e6b`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-290 - Cut-stable-release-v0.12.0-on-main.md

@@ -0,0 +1,56 @@
+---
+id: TASK-290
+title: Cut stable release v0.12.0 on main
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-12 04:47'
+updated_date: '2026-04-12 04:51'
+labels: []
+dependencies: []
+documentation:
+  - docs/RELEASING.md
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Prepare the main branch for the stable SubMiner v0.12.0 release by applying the release-version updates, formatting changes required by the branch state, and rerunning the full release verification gate.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Main branch version and stable release metadata are updated for v0.12.0.
+- [x] #2 Required formatting changes for the release candidate tree are applied and verified.
+- [x] #3 The documented release verification gate passes locally and any remaining push or tag prerequisites are documented.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Audit main-branch release state: package version, release artifacts, current CI status, and current formatting debt.
+2. Apply required formatting fixes to the files reported by `bun run format:check:src` and verify the formatting lane passes.
+3. Update the package version to 0.12.0 and generate stable release metadata (`CHANGELOG.md`, `release/release-notes.md`, `docs-site/changelog.md`) using the documented release workflow.
+4. Run the full local release gate on main (`changelog:lint`, `changelog:check --version 0.12.0`, `verify:config-example`, `typecheck`, `test:fast`, `test:env`, `build`, `docs:test`, `docs:build`, plus dist smoke) and document any remaining tag/push prerequisites.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Applied Prettier to all 39 files reported by `bun run format:check:src` on main and verified the formatting lane now passes.
+
+Reapplied the stable changelog build entrypoint fix on main: added `writeStableReleaseArtifacts`, covered it with a focused regression test, and updated `package.json` so `changelog:build` forwards `--version` and `--date` through a single `build-release` command.
+
+Verified the formatted mainline release tree with `bun run changelog:lint`, `bun run changelog:check --version 0.12.0`, `bun run verify:config-example`, `bun run typecheck`, `bun run test:fast`, `bun run test:env`, `bun run build`, `bun run docs:test`, `bun run docs:build`, and `bun run test:smoke:dist`; all passed.
+
+Remote main CI also completed successfully for `Windows update (#49)` after the local release-prep pass. Remaining operational steps are commit/tag/push only.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared `main` for the stable `v0.12.0` cut. Formatted the previously failing source files so `bun run format:check:src` is now clean, bumped `package.json` from `0.12.0-beta.3` to `0.12.0`, and generated the stable release artifacts with the explicit local cut date `2026-04-11`, which consumed the pending changelog fragments into `CHANGELOG.md`, `docs-site/changelog.md`, and `release/release-notes.md`.
+
+Also reintroduced the release-script fix on main: the old `changelog:build` package script still used `build && docs`, which can drop `--version/--date` on the first step. Added a focused regression test in `scripts/build-changelog.test.ts`, implemented `writeStableReleaseArtifacts` in `scripts/build-changelog.ts`, and switched `package.json` to `build-release` so release flags propagate correctly. Verification on the final tree passed for formatting, changelog lint/check, config example verification, typecheck, fast tests, env tests, build, docs tests/build, dist smoke, and remote main CI. The branch is release-ready pending commit, tag, and push.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-291 - Add-manual-AniList-selection-for-character-dictionary-resolution.md

@@ -0,0 +1,43 @@
+---
+id: TASK-291
+title: Add manual AniList selection for character dictionary resolution
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-04-25 21:29'
+updated_date: '2026-04-25 22:51'
+labels:
+  - dictionary
+  - anilist
+  - cli
+  - ui
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add CLI and in-app UI support for correcting character dictionary anime resolution when guessit or AniList search picks the wrong series. Manual selections must apply to the whole detected series, persist across episodes, and replace stale incorrect entries in the auto-sync merged character dictionary state. Do not add tray UI. Known regression case: `Re - ZERO, Starting Life in Another World (2016) - S01E01 - - The End of the Beginning and the Beginning of the End [v2 Bluray-1080p Proper][10bit][x265][FLAC 2.0][EN+JA]-SCY.mkv` previously resolved to `10607 - Rerere no Tensai Bakabon`; it should be correctable to the chosen Re:ZERO AniList media and then reused for later files in that series.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 CLI can show AniList candidate matches for the current/target media and set a manual character-dictionary AniList override.
+- [x] #2 In-app UI can show the current character-dictionary match, candidate matches, and apply an override without adding tray controls.
+- [x] #3 Persisted overrides are keyed at series scope so all later episodes in the same series reuse the selected AniList media.
+- [x] #4 Applying an override clears stale guess state, replaces the old incorrect active media entry in auto-sync state, rebuilds/imports the merged character dictionary, and refreshes subtitle dictionary usage.
+- [x] #5 Regression tests cover the Re:ZERO filename, override reuse, stale active-media replacement, CLI handling, and IPC/UI contract behavior.
+- [x] #6 Docs are updated for manual character dictionary anime selection.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a focused override/resolution layer for character dictionary media selection: derive a stable series key from filename/guessit data, persist manual AniList media overrides under user data, and expose AniList candidate search helpers.
+2. Update character dictionary snapshot resolution to check manual overrides before guessit-derived AniList search, and update auto-sync so applying an override removes stale incorrect media IDs and rebuilds/imports the merged dictionary.
+3. Extend CLI with commands to list candidates and set an override for current or target media.
+4. Extend existing in-app settings UI via IPC/preload contracts: show current match/candidates and let user apply an override. No tray controls.
+5. Use TDD: add failing regressions first for Re:ZERO parsing/override behavior, auto-sync replacement, CLI handling, IPC contract, and UI state; then implement.
+6. Update docs-site/manual docs for manual character dictionary anime selection, launcher usage, and the default `Ctrl+Alt+A` modal shortcut, then run focused tests and broader gates as time permits.
+<!-- SECTION:PLAN:END -->

backlog/tasks/task-292 - Restore-Linux-multi-subtitle-copy-digit-capture.md

@@ -0,0 +1,52 @@
+---
+id: TASK-292
+title: Restore Linux multi-subtitle copy digit capture
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-04-25 21:31'
+updated_date: '2026-04-25 21:36'
+labels:
+  - bug
+  - linux
+  - shortcuts
+  - clipboard
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+On Linux, the copy-subtitle-multiple shortcut opens the numeric prompt but the follow-up digit is not captured, so the flow times out. User confirmed `wl-copy` itself is installed and working, so investigate the shortcut/digit capture path and restore multi-line subtitle copy without regressing existing session action behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Linux copy-subtitle-multiple shortcut accepts a follow-up digit and copies that number of recent subtitle lines instead of timing out.
+- [x] #2 The fix avoids depending on Linux Electron global shortcut digit registration for the follow-up numeric selection when a renderer-visible session can handle it.
+- [x] #3 Regression tests cover the Linux multi-copy shortcut/digit flow and existing non-Linux/global shortcut behavior remains intact.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add failing regression coverage for Linux copy-subtitle-multiple local shortcut fallback starting renderer/session numeric selection instead of main-process digit globalShortcut capture.
+2. Patch the overlay shortcut fallback/runtime path so Linux visible-overlay multi-copy and mine-sentence-multiple can dispatch session-action numeric selection when renderer handling is available, while preserving main-process numeric sessions for CLI/non-renderer paths.
+3. Run targeted tests for shortcut fallback, overlay runtime, and renderer keyboard numeric selection; then run typecheck or a wider focused gate if needed.
+4. Update task acceptance criteria/final notes after verification.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented the approved path by keeping multi-step numeric overlay shortcuts out of the main-process local fallback. The visible overlay now receives the original keydown and uses the existing renderer/session-action numeric selection flow for follow-up digits, avoiding Linux Electron globalShortcut digit capture for multi-copy and mine-sentence-multiple. Verification: targeted shortcut/renderer tests and changelog lint pass. `bun run typecheck` is currently blocked by unrelated existing errors in CLI/AniList dictionary-candidate work and `src/main/dependencies.ts` manual-selection API shape.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Restored Linux multi-line subtitle copy by preventing main-process overlay shortcut fallback from consuming multi-step numeric shortcuts (`copySubtitleMultiple` and `mineSentenceMultiple`). Those shortcuts now fall through to the visible overlay renderer, where the existing session binding flow prompts for a digit and dispatches the counted session action locally instead of relying on Electron globalShortcut digit registration. Added regression coverage for the fallback behavior and renderer follow-up digit dispatch, plus a changelog fragment.
+
+Verification: `bun test src/core/services/overlay-shortcut-handler.test.ts src/renderer/handlers/keyboard.test.ts`; `bun run changelog:lint`. Full `bun run typecheck` was attempted but is blocked by unrelated current worktree errors in CLI/AniList dictionary-candidate tests/types and `src/main/dependencies.ts`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-293 - Fix-interjection-tokens-receiving-subtitle-annotations.md

@@ -0,0 +1,25 @@
+---
+id: TASK-293
+title: Fix interjection tokens receiving subtitle annotations
+status: In Progress
+assignee: []
+created_date: '2026-04-25 22:50'
+labels:
+  - tokenizer
+  - bug
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Standalone interjections such as あ should remain hoverable dictionary tokens but must not receive N+1, frequency, JLPT, or known-word subtitle annotation metadata.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 A MeCab 感動詞 token like あ is excluded by the shared subtitle annotation gate.
+- [ ] #2 annotateTokens strips N+1/frequency/JLPT/known metadata from the interjection while preserving token lookup fields.
+- [ ] #3 Focused tokenizer regression passes.
+<!-- AC:END -->

backlog/tasks/task-294 - Fix-annotated-subtitle-tokens-to-honor-subtitleStyle.md

@@ -0,0 +1,32 @@
+---
+id: TASK-294
+title: Fix annotated subtitle tokens to honor subtitleStyle
+status: Done
+assignee: []
+created_date: '2026-04-25 23:04'
+updated_date: '2026-04-25 23:07'
+labels:
+  - subtitles
+  - renderer
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Annotated token spans should inherit the configured subtitleStyle typography and only use annotation metadata to change token color.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Tokenized/annotated subtitles preserve configured base subtitle typography such as font family, size, weight, line height, letter spacing, text rendering, and text shadow.
+- [x] #2 Known/N+1/JLPT/frequency/name-match annotations affect token color only, plus existing token metadata/hover affordances.
+- [x] #3 A renderer regression test covers annotated token rendering with custom subtitleStyle.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated renderer subtitle annotation CSS so known/N+1/name/JLPT/frequency classes no longer override typography with token-specific shadows, underlines, padding, or hover font-weight. Added regression coverage using the user's custom subtitleStyle shape to verify annotated token spans inherit base typography and annotation CSS changes token color only. Verified with `bun test src/renderer/subtitle-render.test.ts`, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-295 - Add-primary-subtitle-visibility-keybinding.md

@@ -0,0 +1,66 @@
+---
+id: TASK-295
+title: Add primary subtitle visibility keybinding
+status: Done
+assignee:
+  - Codex
+created_date: '2026-04-25 23:09'
+updated_date: '2026-04-25 23:45'
+labels:
+  - renderer
+  - keybindings
+  - subtitles
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add a `v` keybinding that overrides mpv's default `v` subtitle visibility toggle and instead toggles SubMiner's primary subtitle bar visibility on and off. Secondary subtitle hover behavior is out of scope.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Pressing `v` toggles the primary subtitle bar from visible to hidden.
+- [x] #2 Pressing `v` again restores the primary subtitle bar visibility.
+- [x] #3 The keybinding does not add or change secondary subtitle hover behavior.
+- [x] #4 Relevant automated coverage verifies the toggle behavior.
+- [x] #5 Pressing `v` in the mpv/plugin keybinding path also toggles the primary subtitle bar visibility instead of mpv native subtitle visibility.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Inspect existing renderer keybinding and subtitle bar visibility code, including current local edits in touched files.
+2. Add a focused failing test for `v` toggling primary subtitle bar visibility without changing secondary hover behavior.
+3. Implement the minimal renderer/keybinding change.
+4. Run targeted tests and update acceptance criteria/final notes.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented renderer-local `KeyV` handling before session/mpv binding dispatch so mpv `sub-visibility` is not touched. Visibility state is stored in renderer state and applied via `primary-sub-hidden` class on the primary subtitle container.
+
+Scope updated after user clarified the toggle must work when focus is in mpv as well as in the overlay renderer. Added a forced mpv plugin binding for `v` that runs `--toggle-primary-subtitle-bar`, then broadcasts a renderer IPC toggle event and reuses the same primary subtitle bar toggle path.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Summary:
+- Added a renderer-local `v` key handler that toggles primary subtitle bar visibility by adding/removing `primary-sub-hidden` on the primary subtitle container.
+- Added renderer state for the toggle so repeated presses restore the bar without issuing mpv `sub-visibility` commands.
+- Added a forced mpv plugin `v` binding that invokes `--toggle-primary-subtitle-bar` and broadcasts the same renderer toggle event.
+- Added CSS for the hidden primary subtitle bar state and regression coverage for both overlay and mpv/plugin entry points.
+
+Tests:
+- `bun test src/renderer/handlers/keyboard.test.ts --test-name-pattern "primary subtitle visibility key"`
+- `bun test src/cli/args.test.ts --test-name-pattern "session action"`
+- `bun test src/core/services/cli-command.test.ts --test-name-pattern "visibility and utility"`
+- `bun test src/cli/args.test.ts src/cli/help.test.ts src/core/services/cli-command.test.ts src/main/runtime/cli-command-context.test.ts src/main/runtime/cli-command-context-deps.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/cli-command-context-factory.test.ts src/main/runtime/composers/cli-startup-composer.test.ts src/main/runtime/first-run-setup-service.test.ts`
+- `lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-lua-compat.lua`
+- `bun run typecheck`
+- `bun run test:fast`
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-296 - Suppress-crash-notification-when-closing-launcher-managed-video.md

@@ -0,0 +1,54 @@
+---
+id: TASK-296
+title: Suppress crash notification when closing launcher-managed video
+status: Done
+assignee: []
+created_date: '2026-04-25 23:12'
+updated_date: '2026-04-26 02:44'
+labels:
+  - bug
+  - launcher
+  - mpv
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Investigate and fix regression where closing a running mpv video causes SubMiner/Electron service crash notification (`<html><tt>/SubMiner</tt> has encountered a fatal error and was closed.</html>`). Not present on origin/main/v0.12.0 path.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Closing a launcher-managed video stops the overlay/app without desktop crash notification.
+- [x] #2 Regression test covers the shutdown path that caused the notification.
+- [x] #3 Relevant launcher/app tests pass.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Confirm notification source from local crash metadata and mpv/app logs.
+2. Add regression coverage for mpv quit/shutdown lifecycle helper spawning.
+3. Update mpv Lua lifecycle to avoid Electron helper subprocesses during quit/shutdown while preserving normal end-file hide behavior.
+4. Run plugin tests and changelog lint.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Crash records in ~/.cache/drkonqi show SIGBUS in Electron NetworkService utility process for SubMiner AppImage. mpv log shows shutdown starts two `/home/sudacode/.local/bin/SubMiner.AppImage --hide-visible-overlay` subprocesses and kills them during close. Root cause is mpv plugin spawning Electron control helpers during quit/shutdown.
+
+Follow-up after retest: installed plugin matched source patch and no close-time hide command was spawned. New mpv log shows the initial `/home/sudacode/.local/bin/SubMiner.AppImage --start ...` subprocess remains owned by mpv for the whole playback and is killed when mpv quits. New DrKonqi crash at 2026-04-25 16:44 again shows SIGBUS in Electron NetworkService from that AppImage mount. Need detach the long-lived plugin-launched `--start` app process from mpv.
+
+Second fix: plugin-launched `--start` now includes `--background`, using SubMiner's existing background relaunch path so mpv owns only a short-lived starter process rather than the long-running Electron app. Ran `make install-plugin` so ~/.config/mpv/scripts/subminer now contains both lifecycle and background-start fixes. Full `scripts/test-plugin-start-gate.lua` is currently blocked by an unrelated dirty-worktree primary subtitle bar binding test from TASK-297.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Changed the mpv Lua lifecycle so `shutdown` no longer spawns a `--hide-visible-overlay` helper, and `end-file` skips that helper when mpv reports `reason = "quit"`. Also changed plugin-launched `--start` to include `--background`, so mpv owns only SubMiner's short background launcher process instead of the long-running Electron/AppImage process. This addresses both observed crash sources: close-time helper commands and mpv killing the main SubMiner child process at quit. Installed the updated plugin into `~/.config/mpv/scripts/subminer` with `make install-plugin`, and the user confirmed the latest close no longer produced the notification.
+
+Tests: `lua scripts/test-plugin-start-gate.lua` initially proved the shutdown regression failed before the lifecycle fix; full start-gate is currently affected by other dirty work in this file. Passing checks for this commit: `lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-binary-windows.lua`; `bun run changelog:lint`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-297 - Fix-subtitle-annotation-color-priority-after-typography-cleanup.md

@@ -0,0 +1,32 @@
+---
+id: TASK-297
+title: Fix subtitle annotation color priority after typography cleanup
+status: Done
+assignee: []
+created_date: '2026-04-25 23:44'
+updated_date: '2026-04-25 23:46'
+labels:
+  - subtitles
+  - renderer
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Known-word and frequency subtitle token colors should keep their configured priority after annotation CSS stopped using JLPT underlines.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Known-word token color takes priority over JLPT and frequency color classes.
+- [x] #2 Frequency single-mode token color takes priority over JLPT color classes when frequency annotation is active.
+- [x] #3 Regression coverage verifies CSS selectors do not allow JLPT color rules to override higher-priority annotation colors.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Scoped JLPT token color selectors so they only apply when no higher-priority known-word, N+1, name-match, or frequency class is present. This keeps known words green and frequency single-mode tokens using the single frequency color instead of being visually overridden by JLPT colors. Added CSS regression assertions for this priority behavior. Verified with `bun test src/renderer/subtitle-render.test.ts`, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-298 - Exclude-kana-grammar-helper-merges-like-ことに-from-subtitle-annotations.md

@@ -0,0 +1,54 @@
+---
+id: TASK-298
+title: Exclude kana grammar-helper merges like ことに from subtitle annotations
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-26 00:08'
+updated_date: '2026-04-26 00:15'
+labels:
+  - tokenizer
+  - annotations
+  - bug
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Investigate and fix subtitle tokenizer annotation behavior where all-hiragana grammar-helper merged tokens such as `ことに` can be marked as N+1. Current likely path: Yomitan emits `ことに` with headword `こと`; MeCab enrichment supplies content-led POS (`名詞|助詞`, likely `非自立|格助詞`); shared subtitle annotation filter does not exclude this family unless it matches narrower rules such as `これで` or explanatory endings.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `ことに`-style kana grammar-helper merges are not marked known, N+1, JLPT, or frequency-highlighted when their MeCab metadata indicates a non-independent noun plus helper particle.
+- [x] #2 Regression coverage demonstrates the reported subtitle phrase does not mark `ことに` as N+1 while preserving annotation for real lexical content tokens.
+- [x] #3 Existing tokenizer annotation tests pass.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+Approved approach (user: "let's do it"):
+1. Add a regression test for the reported `ことに` case using Yomitan token `ことに` -> headword `こと` and MeCab metadata `名詞|助詞` / `非自立|格助詞`; assert all annotation fields are stripped while nearby lexical content can still be N+1.
+2. Verify the new test fails before production changes.
+3. Update the shared subtitle annotation filter to exclude conservative kana-only grammar-helper merges: merged surface differs from headword, surface is kana-only, first POS component is `名詞`, first POS2 component is `非自立`, and remaining POS components are grammar helpers (`助詞`/`助動詞`).
+4. Run targeted tokenizer/annotation tests and update the task acceptance criteria/final notes.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Red test initially passed with headword `こと` because `こと` is already in `JLPT_EXCLUDED_TERMS` and the shared subtitle annotation filter checks that set. Updated regression to the live-risk shape `surface=ことに`, `headword=事`, with MeCab POS `名詞|助詞` / `非自立|格助詞`; this failed before the filter change and passed after.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented a conservative shared subtitle annotation filter for kana-only non-independent noun helper merges. Tokens such as `ことに` with a kanji dictionary headword like `事` are now stripped of known-word, N+1, JLPT, and frequency metadata when MeCab shows the first component as `名詞/非自立` and trailing components as grammar helpers.
+
+Added unit coverage in `src/core/services/tokenizer/annotation-stage.test.ts` and an integration-style tokenizer regression for the reported phrase shape in `src/core/services/tokenizer.test.ts`, verifying `ことに` stays plain while a real lexical token can still become the N+1 target.
+
+Validation: `bun test src/core/services/tokenizer/annotation-stage.test.ts`; `bun test src/core/services/tokenizer.test.ts`; `bun run test:fast`; `bun run changelog:lint`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-299 - Force-audio-replacement-during-manual-subtitle-mining.md

@@ -0,0 +1,66 @@
+---
+id: TASK-299
+title: Force audio replacement during manual subtitle mining
+status: Done
+assignee:
+  - Codex
+created_date: '2026-04-26 00:10'
+updated_date: '2026-04-26 02:42'
+labels:
+  - anki
+  - mining
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Manual subtitle mining via the Ctrl+C/Ctrl+V flow should replace expression and sentence audio fields even when the user has configured media overwrite fields to false. These fields can already contain proxy-inserted SubMiner audio on a new card, and manual update intent is to replace that generated content.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Manual subtitle mining replaces existing expression audio content regardless of configured audio overwrite settings.
+- [x] #2 Manual subtitle mining replaces existing sentence audio content regardless of configured audio overwrite settings.
+- [x] #3 Non-manual mining/update flows continue to respect configured audio overwrite settings.
+- [x] #4 A regression test covers manual audio replacement when overwrite settings are disabled.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Locate the manual subtitle mining Ctrl+C/Ctrl+V flow and the Anki media field overwrite gate.
+2. Add a failing regression test showing manual mining overwrites expression and sentence audio when configured audio overwrite is disabled.
+3. Implement the smallest path-specific override so only manual subtitle mining forces audio replacement.
+4. Run the focused mining test and update task acceptance criteria/final notes.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented focused manual clipboard update behavior in CardCreationService.updateLastAddedFromClipboard: generated manual audio is written to both resolved sentence audio and expression audio fields with forced overwrite. Other update flows still use existing overwrite config paths.
+
+Verification: focused Anki tests passed; typecheck passed; changelog lint and diff check passed. Full bun run test:fast was attempted but is blocked by unrelated existing tokenizer annotation-stage failures tied to dirty task 298 worktree changes.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Summary:
+- Manual clipboard subtitle updates now resolve both sentence audio and expression audio fields and replace both with the newly generated audio regardless of ankiConnect.behavior.overwriteAudio.
+- Added a regression test for the Ctrl+C/Ctrl+V manual update path with existing proxy-inserted audio and overwriteAudio disabled.
+- Registered the regression test in test:fast, documented the overwrite exception in user docs, and added a changelog fragment.
+
+Verification:
+- bun test src/anki-integration/card-creation-manual-update.test.ts src/anki-integration/card-creation.test.ts
+- bun run tsc --noEmit
+- bun test src/main-entry-runtime.test.ts src/anki-integration.test.ts src/anki-integration/card-creation-manual-update.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/prerelease-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 run changelog:lint
+- bun run docs:test
+- bun run docs:build
+- git diff --check
+
+Blocked gate:
+- bun run test:fast currently fails in unrelated src/core/services/tokenizer/annotation-stage.test.ts tests for kana-only non-independent noun helper merges; those files have pre-existing dirty changes outside this task.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-300 - Fix-transparent-subtitle-hover-background-config.md

@@ -0,0 +1,51 @@
+---
+id: TASK-300
+title: Fix transparent subtitle hover background config
+status: Done
+assignee: []
+created_date: '2026-04-26 03:23'
+updated_date: '2026-04-26 03:26'
+labels:
+  - bug
+  - overlay
+  - config
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+User reports setting subtitleStyle.hoverTokenBackgroundColor to transparent still renders default hover background in overlay subtitles.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Transparent hoverTokenBackgroundColor is accepted by config resolution.
+- [x] #2 Renderer applies transparent hover token background instead of falling back to default.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Reproduce config alias behavior with a failing config test.
+2. Map subtitleStyle.hoverBackground to hoverTokenBackgroundColor in config resolution while keeping canonical key precedence.
+3. Add renderer regression for transparent hover token background CSS variable.
+4. Update docs and changelog fragment; run focused verification.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Local user config used subtitleStyle.hoverBackground, which was ignored because only subtitleStyle.hoverTokenBackgroundColor was recognized. Canonical key still takes precedence when both are present.
+
+Verification passed: bun run test:config:src; bun test src/renderer/subtitle-render.test.ts; bun run changelog:lint; bun run docs:test; bun run docs:build.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented config compatibility for transparent hover token backgrounds. `subtitleStyle.hoverBackground` now maps to the canonical `subtitleStyle.hoverTokenBackgroundColor` during resolution, preserving canonical key precedence. Added regression coverage for the alias and renderer handling of `transparent`, documented the alias, and added a changelog fragment.
+
+Verification: `bun run test:config:src`; `bun test src/renderer/subtitle-render.test.ts`; `bun run changelog:lint`; `bun run docs:test`; `bun run docs:build`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-301 - Fix-launcher-managed-video-close-leaving-background-app-alive.md

@@ -0,0 +1,55 @@
+---
+id: TASK-301
+title: Fix launcher-managed video close leaving background app alive
+status: Done
+assignee:
+  - Codex
+created_date: '2026-04-26 03:29'
+updated_date: '2026-04-26 03:44'
+labels:
+  - bug
+  - launcher
+  - mpv
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Launcher/plugin-managed video playback should not leave the SubMiner background app or tray icon running after the video closes unless the user explicitly launched SubMiner in background mode via --background or by starting with no app arguments. This is a regression after crash-avoidance work that added background startup for launcher-managed playback.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Closing a launcher-managed video exits the launcher-started SubMiner app/tray instead of leaving it alive.
+- [x] #2 Explicit background launches still keep SubMiner alive after windows close.
+- [x] #3 No-argument app startup behavior remains unchanged.
+- [x] #4 Regression coverage exercises the launcher-managed playback shutdown lifecycle.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add regression coverage first: plugin auto-start should tag launcher-managed playback, and app mpv shutdown handling should quit only when started in that managed playback mode.
+2. Add a narrow CLI flag/state field for launcher-managed playback, separate from explicit persistent background mode.
+3. Have plugin pass the new flag with its background start command.
+4. On mpv shutdown/disconnect, request app quit only when managed playback mode is active; preserve explicit --background and no-arg startup persistence.
+5. Run focused plugin/app tests, then relevant launcher/core gates if feasible.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented managed playback shutdown by adding a `--managed-playback` app flag that the mpv plugin passes only for launcher-managed starts. The main mpv shutdown path now quits the app when initial args indicate managed playback, while explicit background/no-arg startup remains persistent. Added plugin start-gate and mpv protocol regression coverage.
+
+Implemented managed playback lifecycle: mpv plugin auto-start passes --background --managed-playback; app quits on mpv shutdown only when initial args include managedPlayback. Explicit --background and no-arg startup remain persistent. Installed updated mpv plugin to ~/.config/mpv/scripts/subminer via make install-plugin.
+
+Retest showed tray still remained. Root cause: relying on mpv's JSON IPC shutdown event was insufficient; the app may only see the socket close. Added managed-playback quit on MpvIpcClient onClose before reconnect scheduling, with regression coverage.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Launcher-managed playback now starts SubMiner with an internal --managed-playback marker alongside --background. The app requests quit either when mpv sends shutdown or when the mpv IPC socket closes, but only for managed playback mode; explicit background/no-arg startup remains persistent. Added CLI, mpv protocol, mpv socket-close, and plugin regression coverage plus a launcher changelog fragment. Rebuilt the app/launcher and confirmed focused checks, typecheck, build, plugin tests, dist smoke, and formatting.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-302 - Add-visible-hover-affordance-for-annotated-subtitle-tokens.md

@@ -0,0 +1,53 @@
+---
+id: TASK-302
+title: Add visible hover affordance for annotated subtitle tokens
+status: Done
+assignee: []
+created_date: '2026-04-26 03:39'
+updated_date: '2026-04-26 03:40'
+labels:
+  - overlay
+  - subtitle
+  - ux
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Annotated subtitle tokens keep annotation colors on hover, but with transparent hover backgrounds there is no visible hover indication. Add a subtle affordance that preserves annotation color semantics.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Annotated token hover keeps annotation color instead of switching to hover text color.
+- [x] #2 Annotated token hover has a visible indication when hover background is transparent.
+- [x] #3 Regression tests cover the hover CSS contract.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add failing CSS contract test for annotated token hover affordance.
+2. Add brightness/saturation filter to annotated token hover CSS without changing annotation color.
+3. Add changelog fragment and run focused verification.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented option 1 from approved design: annotated subtitle word hover keeps annotation color and adds `filter: brightness(1.18) saturate(1.08)` for visible affordance when the hover background is transparent.
+
+Verification passed: `bun test src/renderer/subtitle-render.test.ts`; `bun run changelog:lint`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added a visible hover affordance for annotated subtitle tokens without changing annotation color semantics. Annotated word hover now applies a small brightness/saturation lift while retaining the existing background behavior, so transparent hover backgrounds still show feedback.
+
+Regression coverage updated in `src/renderer/subtitle-render.test.ts` to assert the hover filter is present and that hover color overrides are still absent for annotated tokens. Added changelog fragment `changes/302-annotated-hover-affordance.md`.
+
+Verification: `bun test src/renderer/subtitle-render.test.ts`; `bun run changelog:lint`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-303 - Update-tray-menu-help-action.md

@@ -0,0 +1,57 @@
+---
+id: TASK-303
+title: Update tray menu help action
+status: Done
+assignee:
+  - Codex
+created_date: '2026-04-26 03:54'
+updated_date: '2026-04-26 04:12'
+labels:
+  - tray
+  - overlay
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Replace the tray menu's direct visible-overlay open action with an action that opens the existing in-session help modal. The tray should no longer expose an "Open Overlay" menu item; users should be able to open help from the tray instead.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Tray menu no longer includes an "Open Overlay" option.
+- [x] #2 Tray menu includes an option to open the session help modal.
+- [x] #3 Selecting the new tray help option initializes overlay runtime if needed and invokes the existing session help modal path.
+- [x] #4 Focused regression tests cover the menu label and action wiring.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add focused regression coverage for tray menu template labels and main-process action wiring: assert Open Overlay is absent, Open Help is present, and clicking help initializes overlay runtime if needed before opening the existing session help modal path.
+2. Update tray runtime action types/template to replace openOverlay with openSessionHelp.
+3. Update tray main action builder dependencies to call the existing openSessionHelpModal function after overlay runtime initialization.
+4. Run targeted tray tests, then broader relevant fast tests if needed.
+5. Check acceptance criteria and finalize backlog notes.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented tray menu replacement via existing session help overlay path. Verification passed: targeted tray tests (`bun test src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts`), SubMiner verifier lanes `runtime-compat` and `docs`, and `bun run changelog:lint`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Replaced the tray menu's `Open Overlay` item with `Open Help`, wired it to initialize overlay runtime when needed, and then open the existing session help modal path. Updated tray runtime/main-deps/action tests to assert the old label is absent, the new label is present, and the new action calls the help modal. Added changelog fragment `changes/303-tray-help-menu.md`.
+
+Verification:
+- `bun test src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts`
+- `bash plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane runtime-compat --lane docs src/main/runtime/tray-runtime.ts src/main/runtime/tray-main-actions.ts src/main/runtime/tray-main-deps.ts src/main.ts changes/303-tray-help-menu.md`
+- `bun run changelog:lint`
+
+Verifier artifacts: `.tmp/skill-verification/subminer-verify-20260425-211156-9fkdDf/`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-304 - Fix-N1-sentence-boundary-counting-across-Yomitan-punctuation-gaps.md

@@ -0,0 +1,27 @@
+---
+id: TASK-304
+title: Fix N+1 sentence boundary counting across Yomitan punctuation gaps
+status: In Progress
+assignee: []
+created_date: '2026-04-26 05:33'
+labels:
+  - bug
+  - tokenizer
+  - annotations
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+N+1 target selection should respect sentence-ending punctuation from the original subtitle text even when Yomitan token output omits punctuation tokens. Current behavior can treat multiple subtitle sentences as one token span and incorrectly satisfy the minimum content-token threshold.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 A subtitle like `てんめ！ふざけんなよ！` does not mark `ふざけん`/similar single-content-token second sentence as N+1 when the minimum sentence word count is 3.
+- [ ] #2 N+1 sentence segmentation uses original subtitle text offsets or equivalent source-boundary data, not only punctuation tokens returned by Yomitan.
+- [ ] #3 Existing annotation exclusion behavior for particles/grammar tokens remains unchanged.
+- [ ] #4 Regression tests cover Yomitan-style token streams where punctuation is absent from the token list.
+<!-- AC:END -->

backlog/tasks/task-305 - Use-Yomitan-word-classes-for-subtitle-token-POS-filtering.md

@@ -0,0 +1,55 @@
+---
+id: TASK-305
+title: Use Yomitan word classes for subtitle token POS filtering
+status: Done
+assignee: []
+created_date: '2026-04-26 05:56'
+updated_date: '2026-04-26 05:59'
+labels:
+  - tokenizer
+  - yomitan
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Subtitle annotation filtering currently uses Yomitan token spans, then enriches those spans by running MeCab over the full normalized subtitle line. Add support for carrying Yomitan headword wordClasses from termsFind into SubMiner tokens so dictionary-backed tokens can provide coarse POS/tag metadata without vendored Yomitan changes. MeCab whole-line enrichment should remain a fallback/source of detailed POS data when Yomitan classes are absent.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Yomitan scanner tokens preserve matched headword wordClasses when termsFind returns them.
+- [x] #2 Subtitle tokenization maps recognized Yomitan wordClasses to coarse PartOfSpeech/POS metadata before annotation filtering.
+- [x] #3 Whole-line MeCab enrichment remains available for missing or more detailed POS metadata and does not break existing subtitle annotation behavior.
+- [x] #4 Focused tokenizer tests cover wordClasses extraction and POS mapping.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add focused regression coverage for Yomitan scanner wordClasses payload and subtitle POS mapping.
+2. Extend the app-owned Yomitan scanner payload to carry matched headword wordClasses when present.
+3. Map recognized Yomitan wordClasses to SubMiner coarse PartOfSpeech/POS metadata before annotation filtering.
+4. Keep MeCab whole-line enrichment as fallback/detail-fill for missing POS fields.
+5. Run focused tokenizer tests and typecheck.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented app-only wordClasses extraction from termsFind results; no vendored Yomitan changes required. Recognized classes currently map prt, aux, v*, adj-i/adj-ix, adj-na, and noun-like classes to SubMiner POS metadata. MeCab enrichment now skips only tokens with complete pos1/pos2/pos3 and otherwise fills missing fields while preserving existing coarse pos1. Verification: bun test src/core/services/tokenizer/yomitan-parser-runtime.test.ts src/core/services/tokenizer.test.ts; bun run typecheck.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented app-only Yomitan wordClasses support for subtitle token annotation filtering. The scanner now carries matched headword wordClasses from termsFind results, tokenizer maps recognized classes into SubMiner coarse POS metadata before annotation, and MeCab whole-line enrichment continues to fill missing detailed POS fields without requiring vendored Yomitan changes.
+
+Tests run:
+- bun test src/core/services/tokenizer/yomitan-parser-runtime.test.ts src/core/services/tokenizer.test.ts
+- bun run typecheck
+
+Note: the working tree already had unrelated tokenizer/annotation edits and task-304 before this work; those were left intact.
+<!-- SECTION:FINAL_SUMMARY:END -->

bun.lock

@@ -12,6 +12,7 @@
         "commander": "^14.0.3",
         "hono": "^4.12.7",
         "jsonc-parser": "^3.3.1",
+        "koffi": "^2.15.6",
         "libsql": "^0.5.22",
         "ws": "^8.19.0",
       },
@@ -478,6 +479,8 @@
 
     "keyv": ["keyv@4.5.4", "", { "dependencies": { "json-buffer": "3.0.1" } }, "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw=="],
 
+    "koffi": ["koffi@2.15.6", "", {}, "sha512-WQBpM5uo74UQ17UpsFN+PUOrQQg4/nYdey4SGVluQun2drYYfePziLLWdSmFb4wSdWlJC1aimXQnjhPCheRKuw=="],
+
     "lazy-val": ["lazy-val@1.0.5", "", {}, "sha512-0/BnGCCfyUMkBpeDgWihanIAF9JmZhHBgUhEqzvf+adhNGLoP6TaiI5oF8oyb3I45P+PcnrqihSf01M0l0G5+Q=="],
 
     "libsql": ["libsql@0.5.28", "", { "dependencies": { "@neon-rs/load": "^0.0.4", "detect-libc": "2.0.2" }, "optionalDependencies": { "@libsql/darwin-arm64": "0.5.28", "@libsql/darwin-x64": "0.5.28", "@libsql/linux-arm-gnueabihf": "0.5.28", "@libsql/linux-arm-musleabihf": "0.5.28", "@libsql/linux-arm64-gnu": "0.5.28", "@libsql/linux-arm64-musl": "0.5.28", "@libsql/linux-x64-gnu": "0.5.28", "@libsql/linux-x64-musl": "0.5.28", "@libsql/win32-x64-msvc": "0.5.28" }, "os": [ "linux", "win32", "darwin", ], "cpu": [ "arm", "x64", "arm64", ] }, "sha512-wKqx9FgtPcKHdPfR/Kfm0gejsnbuf8zV+ESPmltFvsq5uXwdeN9fsWn611DmqrdXj1e94NkARcMA2f1syiAqOg=="],

changes/291-character-dictionary-selection.md

@@ -0,0 +1,5 @@
+type: added
+area: dictionary
+
+- Added CLI and in-app AniList selection for character dictionary mismatches, with series-scoped overrides that replace stale wrong-title entries in the merged dictionary.
+- Added launcher support through `subminer dictionary --candidates` and `subminer dictionary --select`, plus a default `Ctrl+Alt+A` shortcut for the in-app selector.

changes/292-linux-multi-copy.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed Linux multi-line subtitle copy timing out after the prompt by letting the overlay handle the follow-up digit locally.

changes/293-interjection-annotation-filter.md

@@ -0,0 +1,4 @@
+type: fixed
+area: tokenizer
+
+- Stopped standalone `あ` interjections from receiving subtitle annotation metadata such as N+1, JLPT, and frequency highlighting when POS tags are unavailable.

changes/295-primary-subtitle-bar-toggle.md

@@ -0,0 +1,4 @@
+type: added
+area: overlay
+
+- Added a `V` shortcut and mpv plugin binding to toggle the SubMiner primary subtitle bar without changing mpv native subtitle visibility.

changes/296-mpv-close-crash-notification.md

@@ -0,0 +1,4 @@
+type: fixed
+area: mpv
+
+- Stopped mpv from owning long-running SubMiner AppImage subprocesses during playback shutdown, preventing desktop crash notifications when closing video.

changes/297-subtitle-annotation-colors.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed annotated subtitle token colors so `subtitleStyle` typography is preserved and higher-priority known-word/frequency colors are not overridden by JLPT colors.

changes/298-kana-grammar-helper-annotations.md

@@ -0,0 +1,4 @@
+type: fixed
+area: tokenizer
+
+- Stopped kana-only grammar-helper merges such as `ことに` from receiving subtitle annotation metadata like N+1, JLPT, known-word, or frequency highlighting.

changes/299-manual-subtitle-audio-overwrite.md

@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Anki: Manual clipboard subtitle updates now replace both expression and sentence audio fields even when configured audio overwrite is disabled.

changes/300-transparent-hover-background.md

@@ -0,0 +1,4 @@
+type: fixed
+area: config
+
+- Accepted `subtitleStyle.hoverBackground` as an alias for `subtitleStyle.hoverTokenBackgroundColor`, so setting it to `transparent` removes hover token backgrounds.

changes/301-managed-playback-exit.md

@@ -0,0 +1,4 @@
+type: fixed
+area: launcher
+
+- Launcher-managed playback now exits the background SubMiner app when the video closes, while explicit background launches stay persistent.

changes/302-annotated-hover-affordance.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Added a subtle brightness lift for annotated subtitle token hover states so transparent hover backgrounds still show a visible hover affordance.

changes/303-tray-help-menu.md

@@ -0,0 +1,4 @@
+type: changed
+area: tray
+
+- Tray: Replaced the Open Overlay tray menu item with Open Help, which opens the session help modal.

changes/README.md

@@ -30,3 +30,9 @@ Rules:
 - 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
+
+Prerelease notes:
+
+- prerelease tags like `v0.11.3-beta.1` and `v0.11.3-rc.1` reuse the current pending fragments to generate `release/prerelease-notes.md`
+- prerelease note generation does not consume fragments and does not update `CHANGELOG.md` or `docs-site/changelog.md`
+- the final stable release is the point where `bun run changelog:build` consumes fragments into the stable changelog and release notes

changes/stats-dashboard-feedback-pass.md

@@ -1,11 +0,0 @@
-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.
-- Session timeline no longer plots seek-forward/seek-backward markers — they were too noisy on sessions with lots of rewinds.

changes/stats-library-summary.md

@@ -1,4 +0,0 @@
-type: changed
-area: stats
-
-- Replaced the "Library — Per Day" section on the Stats → Trends page with a "Library — Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.

config.example.jsonc

@@ -172,8 +172,13 @@
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
     "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
     "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
+    "openCharacterDictionary": "CommandOrControl+Alt+A", // Open character dictionary setting.
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J" // Open jimaku setting.
+    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
+    "openSessionHelp": "CommandOrControl+Shift+H", // Open session help setting.
+    "openControllerSelect": "Alt+C", // Open controller select setting.
+    "openControllerDebug": "Alt+Shift+C", // Open controller debug setting.
+    "toggleSubtitleSidebar": "Backslash" // Toggle subtitle sidebar setting.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================

docs-site/anki-integration.md

@@ -213,6 +213,8 @@ Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`)
 }
 ```
 
+`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated audio in both the expression audio field and sentence audio field.
+
 ## AI Translation
 
 SubMiner can auto-translate the mined sentence and fill the translation field.

docs-site/changelog.md

@@ -1,6 +1,50 @@
 # Changelog
 
-## v0.11.2 (2026-04-07)
+## v0.12.0 (2026-04-11)
+
+**Changed**
+- Overlay: Added configurable overlay shortcuts for session help, controller select, and controller debug actions.
+- Overlay: Added mpv/plugin and CLI routing for session help, controller utilities, and subtitle sidebar toggling through the shared session-action path.
+- Overlay: Added a `V` shortcut and mpv plugin binding to toggle the SubMiner primary subtitle bar instead of mpv's native primary subtitle visibility.
+- Overlay: Improved dedicated overlay modal retry and focus handling for runtime options, Jimaku, session help, controller tools, and the playlist browser.
+- Overlay: Fixed controller configuration and controller debug shortcut opens so configured bindings bring up their modals again instead of tripping renderer recovery.
+- Stats: Sessions are rolled up per episode within each day, with a bulk delete that wipes every session in the group.
+- Stats: Trends add a 365-day range next to the existing 7d/30d/90d/all options.
+- Stats: Library detail view gets a delete-episode action that removes the video and all its sessions.
+- Stats: Vocabulary Top 50 tightens the word/reading column so katakana entries no longer push the scores off screen.
+- Stats: Episode detail hides card events whose Anki notes have been deleted, instead of showing phantom mining activity.
+- Stats: Trend and watch-time charts share a unified theme with horizontal gridlines and larger ticks for legibility.
+- Stats: Overview, Library, Trends, Sessions, and Vocabulary now use generic "title" wording so YouTube videos and anime live comfortably side by side in the dashboard.
+- Stats: Session timeline no longer plots seek-forward/seek-backward markers — they were too noisy on sessions with lots of rewinds.
+- Stats: Replaced the "Library — Per Day" section on the Stats → Trends page with a "Library — Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.
+
+**Fixed**
+- Overlay: Fixed overlay drag-and-drop routing so dropping external subtitle files like `.ass` onto mpv still loads them when the overlay is visible.
+- Overlay: Addressed the latest CodeRabbit follow-ups on PR #49, including generation-scoped Lua session binding names, stricter session command validation, session-help shortcut visibility, the numeric-selection key guard, stats-overlay startup classification, and safer session-binding persistence.
+- Overlay: Addressed the latest CodeRabbit follow-ups on the Windows overlay flow, including exact mpv target resolution, lower-overlay helper arguments, Win32 failure detection, and overlay cleanup on tracker loss.
+- Overlay: Fixed Windows overlay z-order so the visible subtitle overlay stops staying above unrelated apps after mpv loses focus.
+- Overlay: Fixed Windows overlay tracking to use native window polling and owner/z-order binding, which keeps the subtitle overlay aligned to the active mpv window more reliably.
+- Overlay: Fixed Windows overlay hide/restore behavior so minimizing mpv immediately hides the overlay and restoring mpv brings it back on top of the mpv window without requiring a click.
+- Overlay: Fixed stats overlay layering so the in-player stats page now stays above mpv and the subtitle overlay while it is open.
+- Overlay: Fixed Windows subtitle overlay stability so transient tracker misses and restore events keep the current subtitle visible instead of waiting for the next subtitle line.
+- Overlay: Fixed Windows focus handoff from the interactive subtitle overlay back to mpv so the overlay no longer drops behind mpv and briefly disappears.
+- Overlay: Fixed Windows visible-overlay startup so it no longer briefly opens as an interactive or opaque surface before the tracked transparent overlay state settles.
+- Overlay: Fixed spurious auto-pause after overlay visibility recovery and window resize so the overlay no longer pauses mpv until the pointer genuinely re-enters the subtitle area.
+- Overlay: Fixed Windows secondary subtitle hover mode so the expanded hover hit area no longer blocks the native minimize, maximize, and close buttons.
+- Overlay: Fixed Windows Yomitan popup focus loss after closing nested lookups so the original popup stays interactive instead of falling through to mpv.
+- Stats: Fixed immersion-tracker timestamp handling under Bun/libsql so library rows, session timelines, and lifetime summaries keep real wall-clock millisecond values instead of truncating to invalid negative timestamps.
+- Mpv Plugin: Fixed the mpv Lua plugin so hover and environment modules no longer use the `goto continue` pattern that can fail to parse on some user Lua runtimes.
+
+**Internal**
+- Release: Added a dedicated beta/rc prerelease GitHub Actions workflow that publishes GitHub prereleases without consuming pending changelog fragments or updating AUR.
+- Release: Added prerelease note generation so beta and release-candidate tags can reuse the current pending `changes/*.md` fragments while leaving stable changelog publication for the final release cut.
+
+## Previous Versions
+
+<details>
+<summary>v0.11.x</summary>
+
+<h2>v0.11.2 (2026-04-07)</h2>
 
 **Changed**
 - Launcher: Replaced the launcher-only fullscreen toggle with `mpv.launchMode` so SubMiner-managed mpv playback can start in normal, maximized, or fullscreen mode.
@@ -10,13 +54,13 @@
 - 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)
+<h2>v0.11.1 (2026-04-04)</h2>
 
 **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)
+<h2>v0.11.0 (2026-04-03)</h2>
 
 **Added**
 - Overlay: Added a playlist browser overlay modal for browsing sibling video files and the live mpv queue during playback.
@@ -69,7 +113,7 @@
 - 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.
 
-## Previous Versions
+</details>
 
 <details>
 <summary>v0.10.x</summary>

docs-site/character-dictionary.md

@@ -28,9 +28,9 @@ Character dictionary sync is disabled by default. To turn it on:
     "enabled": true,
     "accessToken": "your-token",
     "characterDictionary": {
-      "enabled": true
-    }
-  }
+      "enabled": true,
+    },
+  },
 }
 ```
 
@@ -47,18 +47,20 @@ If `yomitan.externalProfilePath` is set, SubMiner switches to read-only external
 A single character produces many searchable terms so that names are recognized regardless of how they appear in dialogue. SubMiner generates variants for:
 
 **Spacing and combination:**
+
 - Full name with space: 須々木 心一
 - Combined form: 須々木心一
 - Family name alone: 須々木
 - Given name alone: 心一
 
 **Middle-dot removal** (common in katakana foreign names):
+
 - ア・リ・ス → アリス (combined), plus individual segments
 
 **Honorific suffixes** — each base name is expanded with 15 common suffixes:
 
 | Honorific | Reading    |
-| --- | --- |
+| --------- | ---------- |
 | さん      | さん       |
 | 様        | さま       |
 | 先生      | せんせい   |
@@ -93,7 +95,7 @@ Name matches are visually distinct from [N+1 targeting, frequency highlighting,
 **Key settings:**
 
 | Option                           | Default   | Description                        |
-| --- | --- | --- |
+| -------------------------------- | --------- | ---------------------------------- |
 | `subtitleStyle.nameMatchEnabled` | `true`    | Toggle character-name highlighting |
 | `subtitleStyle.nameMatchColor`   | `#f5bde6` | Highlight color for matched names  |
 
@@ -117,10 +119,10 @@ The three collapsible sections can be configured to start open or closed:
       "collapsibleSections": {
         "description": false,
         "characterInformation": false,
-        "voicedBy": false
-      }
-    }
-  }
+        "voicedBy": false,
+      },
+    },
+  },
 }
 ```
 
@@ -143,7 +145,7 @@ When `characterDictionary.enabled` is `true`, SubMiner runs an auto-sync routine
 {
   "activeMediaIds": [170942, 163134, 154587],
   "mergedRevision": "a1b2c3d4e5f6",
-  "mergedDictionaryTitle": "SubMiner Character Dictionary"
+  "mergedDictionaryTitle": "SubMiner Character Dictionary",
 }
 ```
 
@@ -163,6 +165,29 @@ SubMiner.AppImage --dictionary
 
 This creates a standalone dictionary ZIP for the target media and saves it alongside the snapshots.
 
+## Correcting AniList Matches
+
+SubMiner uses `guessit` to infer the anime title from the active filename, then searches AniList. Some filenames can still resolve to the wrong title. For example, `Re - ZERO, Starting Life in Another World (2016)` can be misread as a different `Re...` series.
+
+Use the in-app selector or CLI to pin the correct AniList media for the whole series:
+
+```bash
+# List candidate AniList matches for a file
+subminer dictionary --candidates "/path/to/episode.mkv"
+
+# Save the correct AniList media ID for that series
+subminer dictionary --select 21355 "/path/to/episode.mkv"
+
+# Equivalent direct app flags
+SubMiner.AppImage --dictionary-candidates --dictionary-target "/path/to/episode.mkv"
+SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary-target "/path/to/episode.mkv"
+
+# Open the in-app selector from the running app
+subminer app --open-character-dictionary
+```
+
+Manual selections are stored in `character-dictionaries/anilist-overrides.json` using a series key derived from the filename guess. Later episodes with the same series key use the selected AniList ID automatically. When the override replaces a previous wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+
 ## File Structure
 
 All character dictionary data lives under `{userData}/character-dictionaries/`:
@@ -174,6 +199,7 @@ character-dictionaries/
     anilist-163134.json
   merged.zip                  # Active merged dictionary (imported into Yomitan)
   auto-sync-state.json        # Tracks active media IDs and revision
+  anilist-overrides.json      # Manual series-to-AniList overrides
   img/
     m170942-c12345.jpg        # Character portrait
     m170942-va67890.jpg       # Voice actor portrait
@@ -195,7 +221,7 @@ merged.zip
 ## Configuration Reference
 
 | Option                                                                 | Default   | Description                                                     |
-| --- | --- | --- |
+| ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
 | `anilist.characterDictionary.enabled`                                  | `false`   | Enable auto-sync of character dictionary from AniList           |
 | `anilist.characterDictionary.maxLoaded`                                | `3`       | Number of recent media snapshots kept in the merged dictionary  |
 | `anilist.characterDictionary.profileScope`                             | `"all"`   | Apply dictionary to `"all"` Yomitan profiles or `"active"` only |
@@ -212,7 +238,7 @@ SubMiner's character dictionary builder is inspired by the [Japanese Character N
 The reference implementation covers similar ground — name variant generation, honorific expansion, structured Yomitan content, portrait embedding — and additionally supports VNDB as a data source for visual novel characters. Key differences:
 
 |                        | SubMiner                                     | Reference Implementation              |
-| --- | --- | --- |
+| ---------------------- | -------------------------------------------- | ------------------------------------- |
 | **Runtime**            | TypeScript, runs inside Electron             | Rust, standalone web service          |
 | **Data sources**       | AniList only                                 | AniList + VNDB                        |
 | **Delivery**           | Auto-synced into bundled Yomitan             | ZIP download via web UI               |
@@ -226,7 +252,7 @@ If you work with visual novels or want a standalone dictionary generator indepen
 
 - **Names not highlighting:** Confirm `anilist.characterDictionary.enabled` is `true` and `subtitleStyle.nameMatchEnabled` is `true`. Check that the current media has an AniList entry — SubMiner needs a media ID to fetch characters.
 - **Sync seems stuck:** The auto-sync debounces for 800ms after media changes and throttles image downloads at 250ms per image. Large casts (50+ characters) take longer. Check the status bar for the current sync phase.
-- **Wrong characters showing:** The merged dictionary includes your `maxLoaded` most recent titles. If you're seeing names from a previous show, they'll rotate out once you watch enough new titles to push it past the limit.
+- **Wrong characters showing:** Open the in-app character dictionary selector (`--open-character-dictionary`) or run `--dictionary-candidates`, then save the correct media with `--dictionary-select --dictionary-anilist-id <id>`. This replaces stale wrong-title entries for that series. If names are only from an older unrelated show, they'll rotate out once you watch enough new titles to push it past `maxLoaded`.
 - **Yomitan import fails:** SubMiner waits up to 7 seconds for Yomitan to be ready for mutations. If Yomitan is still loading dictionaries or performing another import, the operation may time out. Restarting the overlay typically resolves this.
 - **Portraits missing:** Images are downloaded from AniList CDN during snapshot generation. If the network was unavailable during the initial sync, delete the snapshot file from `character-dictionaries/snapshots/` and let it regenerate.
 

docs-site/configuration.md

@@ -310,7 +310,7 @@ See `config.example.jsonc` for detailed configuration options.
 | `autoPauseVideoOnHover`            | boolean     | Pause playback while mouse hovers subtitle text, then resume on leave (`true` by default).                                 |
 | `autoPauseVideoOnYomitanPopup`     | boolean     | Pause playback while the Yomitan popup is open, then resume when the popup closes (`true` by default).                     |
 | `hoverTokenColor`                  | string      | Hex color used for hovered subtitle token highlight in mpv (default: catppuccin mauve)                                     |
-| `hoverTokenBackgroundColor`        | string      | CSS color used for hovered subtitle token background highlight (default: semi-transparent dark)                            |
+| `hoverTokenBackgroundColor`        | string      | CSS color used for hovered subtitle token background highlight; `hoverBackground` is accepted as an alias                  |
 | `nameMatchEnabled`                 | boolean     | Enable subtitle token coloring for matches from the SubMiner character dictionary (`true` by default)                      |
 | `nameMatchColor`                   | string      | Hex color used for subtitle tokens matched from the SubMiner character dictionary (default: `#f5bde6`)                     |
 | `frequencyDictionary.enabled`      | boolean     | Enable frequency highlighting from dictionary lookups (`false` by default)                                                 |
@@ -535,8 +535,13 @@ See `config.example.jsonc` for detailed configuration options.
     "mineSentence": "CommandOrControl+S",
     "mineSentenceMultiple": "CommandOrControl+Shift+S",
     "markAudioCard": "CommandOrControl+Shift+A",
+    "openCharacterDictionary": "CommandOrControl+Alt+A",
     "openRuntimeOptions": "CommandOrControl+Shift+O",
+    "openSessionHelp": "CommandOrControl+Shift+H",
+    "openControllerSelect": "Alt+C",
+    "openControllerDebug": "Alt+Shift+C",
     "openJimaku": "Ctrl+Shift+J",
+    "toggleSubtitleSidebar": "Backslash",
     "multiCopyTimeoutMs": 3000
   }
 }
@@ -555,8 +560,13 @@ See `config.example.jsonc` for detailed configuration options.
 | `multiCopyTimeoutMs`          | number           | Timeout in ms for multi-copy/mine digit input (default: `3000`)                                                                               |
 | `toggleSecondarySub`          | string \| `null` | Accelerator for cycling secondary subtitle mode (default: `"CommandOrControl+Shift+V"`)                                                       |
 | `markAudioCard`               | string \| `null` | Accelerator for marking last card as audio card (default: `"CommandOrControl+Shift+A"`)                                                       |
+| `openCharacterDictionary`     | string \| `null` | Opens the character dictionary AniList selector (default: `"CommandOrControl+Alt+A"`)                                                         |
 | `openRuntimeOptions`          | string \| `null` | Opens runtime options palette for live session-only toggles (default: `"CommandOrControl+Shift+O"`)                                           |
+| `openSessionHelp`             | string \| `null` | Opens the in-overlay session help modal (default: `"CommandOrControl+Shift+H"`)                                                               |
+| `openControllerSelect`        | string \| `null` | Opens the controller config/remap modal (default: `"Alt+C"`)                                                                                  |
+| `openControllerDebug`         | string \| `null` | Opens the controller debug modal (default: `"Alt+Shift+C"`)                                                                                   |
 | `openJimaku`                  | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`)                                                                                     |
+| `toggleSubtitleSidebar`       | string \| `null` | Dispatches the subtitle sidebar toggle action (default: `"Backslash"`). `subtitleSidebar.toggleKey` remains the primary bare-key setting.     |
 
 **See `config.example.jsonc`** for the complete list of shortcut configuration options.
 
@@ -573,9 +583,10 @@ Important behavior:
 - Controller input is only active while keyboard-only mode is enabled.
 - Keyboard-only mode continues to work normally without a controller.
 - By default SubMiner uses the first connected controller.
-- `Alt+C` opens the controller config modal, where you can save the selected controller and remap actions inline.
+- `Alt+C` opens the controller config modal by default, and you can remap that shortcut through `shortcuts.openControllerSelect`.
 - Click `Learn`, then press the next fresh button, trigger, or stick direction you want to bind for that overlay action.
-- `Alt+Shift+C` opens a live debug modal showing raw axes/button values plus a ready-to-copy `buttonIndices` config block.
+- `Alt+Shift+C` opens the debug modal by default, and you can remap that shortcut through `shortcuts.openControllerDebug`.
+- The debug modal shows raw axes/button values plus a ready-to-copy `buttonIndices` config block.
 - `controller.buttonIndices` is a semantic reference/legacy mapping. Changing it does not rewrite the raw numeric descriptor values already stored under `controller.bindings`.
 - Turning keyboard-only mode off clears the keyboard-only token highlight state.
 - Closing the Yomitan popup clears the temporary native text-selection fill, but keeps controller token selection active.
@@ -680,6 +691,7 @@ When `behavior.autoUpdateNewCards` is set to `false`, new cards are detected but
 | `Ctrl+Shift+S` | Enter multi-mine mode. Press `1-9` to create a sentence card from that many recent lines, or `Esc` to cancel       |
 | `Ctrl+Shift+V` | Cycle secondary subtitle display mode (hidden → visible → hover)                                                   |
 | `Ctrl+Shift+A` | Mark the last added Anki card as an audio card (sets IsAudioCard, SentenceAudio, Sentence, Picture)                |
+| `Ctrl+Alt+A`   | Open character dictionary AniList selector                                                                         |
 | `Ctrl+Shift+O` | Open runtime options palette (session-only live toggles)                                                           |
 | `Ctrl/Cmd+A`   | Append clipboard video path to MPV playlist (fixed, not currently configurable)                                    |
 
@@ -694,7 +706,7 @@ These shortcuts are only active when the overlay window is visible and automatic
 
 ### Session Help Modal
 
-The session help modal is opened with `Y-H` by default (falls back to `Y-K` if needed) and shows the current session keybindings and color legend.
+The session help modal opens from the overlay with `Ctrl/Cmd+Shift+H` by default. The mpv plugin also exposes it through the `Y-H` chord (falling back to `Y-K` if needed). It shows the current session keybindings and color legend.
 
 You can filter the modal quickly with `/`:
 
@@ -846,7 +858,7 @@ 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)                                                                  |
@@ -881,7 +893,7 @@ This example is intentionally compact. The option table below documents availabl
 | `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.overwriteAudio`                         | `true`, `false`                         | Replace existing audio on updates; when `false`, new audio is appended/prepended per `behavior.mediaInsertMode`; manual clipboard updates always replace generated audio (default: `true`) |
 | `behavior.overwriteImage`                         | `true`, `false`                         | Replace existing images on updates; when `false`, new images are appended/prepended per `behavior.mediaInsertMode` (default: `true`)                                                       |
 | `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                 | Where to insert new media when overwrite is off (default: `"append"`)                                                                                                                      |
 | `behavior.highlightWord`                          | `true`, `false`                         | Highlight the word in sentence context (default: `true`)                                                                                                                                   |

docs-site/launcher-script.md

@@ -70,7 +70,7 @@ subminer stats -b                       # start background stats daemon
 ## Subcommands
 
 | Subcommand                                 | Purpose                                                            |
-| ---------------------------- | ---------------------------------------------------------- |
+| ------------------------------------------ | ------------------------------------------------------------------ |
 | `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)              |
@@ -82,6 +82,8 @@ subminer stats -b                       # start background stats daemon
 | `subminer mpv socket`                      | Print active socket path                                           |
 | `subminer mpv idle`                        | Launch detached idle mpv instance                                  |
 | `subminer dictionary <path>`               | Generate character dictionary ZIP from file/dir target             |
+| `subminer dictionary --candidates <path>`  | List AniList candidate matches for character dictionary correction |
+| `subminer dictionary --select <id> <path>` | Pin an AniList media ID for that target series                     |
 | `subminer texthooker`                      | Launch texthooker-only mode                                        |
 | `subminer app`                             | Pass arguments directly to SubMiner binary                         |
 
@@ -90,7 +92,7 @@ Use `subminer <subcommand> -h` for command-specific help.
 ## Options
 
 | Flag                  | Description                                                          |
-| --------------------- | --------------------------------------------------- |
+| --------------------- | -------------------------------------------------------------------- |
 | `-d, --directory`     | Video search directory (default: cwd)                                |
 | `-r, --recursive`     | Search directories recursively                                       |
 | `-R, --rofi`          | Use rofi instead of fzf                                              |

docs-site/mining-workflow.md

@@ -100,6 +100,8 @@ If you prefer a hands-on approach (animecards-style), you can copy the current s
    - For multiple lines: press `Ctrl/Cmd+Shift+C`, then a digit `1`–`9` to select how many recent subtitle lines to combine. The combined text is copied to the clipboard.
 3. Press `Ctrl/Cmd+V` to update the last-added card with the clipboard contents plus audio, image, and translation — the same fields auto-update would fill.
 
+Manual clipboard updates always replace generated audio in both the expression audio field and sentence audio field, even when `ankiConnect.behavior.overwriteAudio` is disabled. The manual flow assumes you are intentionally replacing the proxy-generated clip on the newest card.
+
 This is useful when auto-update is disabled or when you want explicit control over which subtitle line gets attached to the card.
 
 | Shortcut                   | Action                          | Config key                              |

docs-site/mpv-plugin.md

@@ -41,11 +41,14 @@ All keybindings use a `y` chord prefix — press `y`, then the second key:
 | `y-s` | Start overlay          |
 | `y-S` | Stop overlay           |
 | `y-t` | Toggle visible overlay |
+| `v`   | Toggle primary subtitle bar visibility |
 | `y-o` | Open settings window   |
 | `y-r` | Restart overlay        |
 | `y-c` | Check status           |
 | `y-k` | Skip intro (AniSkip)   |
 
+The bare `v` binding is a forced mpv binding. It overrides mpv's default primary subtitle visibility toggle and routes the action to SubMiner's primary subtitle bar instead.
+
 ## Menu
 
 Press `y-y` to open an interactive menu in mpv's OSD:

docs-site/public/config.example.jsonc

@@ -172,8 +172,13 @@
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
     "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
     "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
+    "openCharacterDictionary": "CommandOrControl+Alt+A", // Open character dictionary setting.
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J" // Open jimaku setting.
+    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
+    "openSessionHelp": "CommandOrControl+Shift+H", // Open session help setting.
+    "openControllerSelect": "Alt+C", // Open controller select setting.
+    "openControllerDebug": "Alt+Shift+C", // Open controller debug setting.
+    "toggleSubtitleSidebar": "Backslash" // Toggle subtitle sidebar setting.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================

docs-site/shortcuts.md

@@ -36,8 +36,9 @@ The multi-line shortcuts open a digit selector with a 3-second timeout (`shortcu
 These control playback and subtitle display. They require overlay window focus.
 
 | Shortcut             | Action                                              |
-| -------------------- | -------------------------------------------------- |
+| -------------------- | --------------------------------------------------- |
 | `Space`              | Toggle mpv pause                                    |
+| `V`                  | Toggle primary subtitle bar visibility              |
 | `J`                  | Cycle primary subtitle track                        |
 | `Shift+J`            | Cycle secondary subtitle track                      |
 | `Ctrl+Alt+P`         | Open playlist browser for current directory + queue |
@@ -64,9 +65,11 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle
 ## Subtitle & Feature Shortcuts
 
 | Shortcut           | Action                                                   | Config key                          |
-| ------------------ | -------------------------------------------------------- | ------------------------------ |
+| ------------------ | -------------------------------------------------------- | ----------------------------------- |
 | `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`      |
+| `Ctrl/Cmd+Alt+A` | Open character dictionary AniList selector                 | `shortcuts.openCharacterDictionary` |
 | `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`      |
+| `Ctrl/Cmd+Shift+H` | Open session help modal                                  | `shortcuts.openSessionHelp`         |
 | `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`              |
 | `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                       |
 | `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`          |
@@ -79,12 +82,12 @@ The subtitle sidebar toggle is overlay-local and only opens when SubMiner has a
 
 ## Controller Shortcuts
 
-These overlay-local shortcuts are fixed and open controller utilities for the Chrome Gamepad API integration.
+These overlay-local shortcuts open controller utilities for the Chrome Gamepad API integration.
 
 | Shortcut      | Action                               | Configurable                     |
-| ------------- | ------------------------------ | ------------ |
-| `Alt+C`       | Open controller config + remap modal | Fixed        |
-| `Alt+Shift+C` | Open controller debug modal          | Fixed        |
+| ------------- | ------------------------------------ | -------------------------------- |
+| `Alt+C`       | Open controller config + remap modal | `shortcuts.openControllerSelect` |
+| `Alt+Shift+C` | Open controller debug modal          | `shortcuts.openControllerDebug`  |
 
 Controller input only drives the overlay while keyboard-only mode is enabled. The controller mapping and tuning live under the top-level `controller` config block; keyboard-only mode still works normally without a controller.
 
@@ -98,9 +101,13 @@ When the mpv plugin is installed, all commands use a `y` chord prefix — press
 | `y-s` | Start overlay            |
 | `y-S` | Stop overlay             |
 | `y-t` | Toggle visible overlay   |
+| `v`   | Toggle primary subtitle bar visibility |
 | `y-o` | Open Yomitan settings    |
 | `y-r` | Restart overlay          |
 | `y-c` | Check overlay status     |
+| `y-h` | Open session help        |
+
+The bare `v` plugin binding intentionally overrides mpv's native primary subtitle visibility toggle so the SubMiner primary subtitle bar is hidden or restored instead.
 
 When the overlay has focus, press `y` then `d` to toggle DevTools (debugging helper).
 
@@ -113,7 +120,7 @@ When the overlay has focus, press `y` then `d` to toggle DevTools (debugging hel
 
 ## Customizing Shortcuts
 
-All `shortcuts.*` keys accept [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts), for example `"CommandOrControl+Shift+M"`. Use `null` to disable a shortcut.
+All `shortcuts.*` keys accept [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts), for example `"CommandOrControl+Alt+A"`. Use `null` to disable a shortcut.
 
 ```jsonc
 {

docs-site/usage.md

@@ -100,6 +100,8 @@ subminer mpv socket               # Print active mpv socket path
 subminer mpv status               # Exit 0 if socket is ready, else exit 1
 subminer mpv idle                 # Launch detached idle mpv with SubMiner defaults
 subminer dictionary /path/to/file-or-directory  # Generate character dictionary ZIP from target (manual Yomitan import)
+subminer dictionary --candidates /path/to/file.mkv
+subminer dictionary --select 21355 /path/to/file.mkv
 subminer texthooker               # Launch texthooker-only mode
 subminer app --anilist            # Pass args directly to SubMiner binary (example: AniList login flow)
 
@@ -112,6 +114,7 @@ SubMiner.AppImage --stop                  # Stop overlay
 SubMiner.AppImage --start --toggle        # Start MPV IPC + toggle visibility
 SubMiner.AppImage --show-visible-overlay              # Force show visible overlay
 SubMiner.AppImage --hide-visible-overlay              # Force hide visible overlay
+SubMiner.AppImage --toggle-primary-subtitle-bar       # Toggle primary subtitle bar visibility
 SubMiner.AppImage --start --dev                         # Enable app/dev mode only
 SubMiner.AppImage --start --debug                       # Alias for --dev
 SubMiner.AppImage --start --log-level debug             # Force verbose logging without app/dev mode
@@ -124,6 +127,9 @@ SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-s
 SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID --jellyfin-audio-stream-index 1 --jellyfin-subtitle-stream-index 2  # Requires connected mpv IPC (--start or plugin workflow)
 SubMiner.AppImage --jellyfin-remote-announce  # Force cast-target capability announce + visibility check
 SubMiner.AppImage --dictionary             # Generate character dictionary ZIP for current anime
+SubMiner.AppImage --dictionary-candidates  # List AniList candidates for current character dictionary series
+SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355  # Pin correct AniList media for series
+SubMiner.AppImage --open-character-dictionary  # Open in-app AniList selector
 SubMiner.AppImage --help                  # Show all options
 ```
 
@@ -166,6 +172,7 @@ This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blan
 - `subminer config`: config helpers (`path`, `show`).
 - `subminer mpv`: mpv helpers (`status`, `socket`, `idle`).
 - `subminer dictionary <path>`: generates a Yomitan-importable character dictionary ZIP from a file/directory target.
+- Use `subminer dictionary --candidates <path>` and `subminer dictionary --select <id> <path>` to correct AniList character-dictionary matches for a whole series.
 - `subminer texthooker`: texthooker-only shortcut (same behavior as `--texthooker`).
 - `subminer app` / `subminer bin`: direct passthrough to the SubMiner binary/AppImage.
 - Subcommand help pages are available (for example `subminer jellyfin -h`).
@@ -272,12 +279,12 @@ SubMiner supports gamepad/controller input for couch-friendly usage via the Chro
 
 1. Connect a controller before or after launching SubMiner.
 2. Enable keyboard-only mode — press `Y` on the controller (default binding) or use the overlay keybinding.
-3. Press `Alt+C` in the overlay to pick the controller you want to save and remap any action inline.
+3. Press `Alt+C` in the overlay by default to pick the controller you want to save and remap any action inline.
 4. Click `Learn` on the overlay action you want, then press the matching button, trigger, or stick direction on the controller.
 5. Use the left stick to navigate subtitle tokens and scroll the popup; use the right stick vertically for popup page jumps.
 6. Press `A` to look up the selected word, `X` to mine a card, `B` to close the popup.
 
-By default SubMiner uses the first connected controller. `Alt+C` opens the controller config modal, where you can save the preferred controller and remap bindings inline. `Alt+Shift+C` still opens the live debug modal with raw axes/button values for non-standard pads.
+By default SubMiner uses the first connected controller. `Alt+C` opens the controller config modal, where you can save the preferred controller and remap bindings inline, and `Alt+Shift+C` opens the live debug modal with raw axes/button values for non-standard pads. Both shortcuts can be changed through `shortcuts.openControllerSelect` and `shortcuts.openControllerDebug`.
 
 ### Default Button Mapping
 
@@ -321,6 +328,10 @@ See [Keyboard Shortcuts](/shortcuts) for the full reference, including mining sh
 
 Useful overlay-local default keybinding: `Ctrl+Alt+P` opens the playlist browser for the current video's parent directory and the live mpv queue so you can append, reorder, remove, or jump between episodes without leaving playback.
 
+Press `V` to hide or restore the primary SubMiner subtitle bar. The mpv plugin also binds bare `v` to the same action, overriding mpv's native primary subtitle visibility toggle.
+
+`Ctrl/Cmd+Shift+H` opens the session help modal with the current overlay and mpv keybindings. If you use the mpv plugin, the same help view is also available through the `y-h` chord.
+
 Hovering over subtitle text pauses mpv by default; leaving resumes it. Yomitan popups also pause playback by default. Set `subtitleStyle.autoPauseVideoOnHover: false` or `subtitleStyle.autoPauseVideoOnYomitanPopup: false` to disable either behavior.
 
 ### Drag-and-Drop

docs/RELEASING.md

@@ -2,6 +2,8 @@
 
 # Releasing
 
+## Stable Release
+
 1. Confirm `main` is green: `gh run list --workflow CI --limit 5`.
 2. Confirm release-facing docs are current: `README.md`, `changes/*.md`, and any touched `docs-site/` pages/config examples.
 3. Run `bun run changelog:lint`.
@@ -24,15 +26,37 @@
 10. Tag the commit: `git tag v<version>`.
 11. Push commit + tag.
 
+## Prerelease
+
+1. Confirm release-facing docs and pending `changes/*.md` fragments are current.
+2. Run `bun run changelog:lint`.
+3. Bump `package.json` to the prerelease version, for example `0.11.3-beta.1` or `0.11.3-rc.1`.
+4. Run the prerelease gate locally:
+   `bun run changelog:prerelease-notes --version <version>`
+   `bun run verify:config-example`
+   `bun run typecheck`
+   `bun run test:fast`
+   `bun run test:env`
+   `bun run build`
+5. Commit the prerelease prep. Do not run `bun run changelog:build`.
+6. Tag the commit: `git tag v<version>`.
+7. Push commit + tag.
+
+Prerelease tags publish a GitHub prerelease only. They do not update `CHANGELOG.md`, `docs-site/changelog.md`, or the AUR package, and they do not consume `changes/*.md` fragments. The final stable release is still the point where `bun run changelog:build` consumes fragments into `CHANGELOG.md` and regenerates stable release notes.
+
 Notes:
 
 - Versioning policy: SubMiner stays 0-ver. Large or breaking release lines still bump the minor number (`0.x.0`), not `1.0.0`. Example: the next major line after `0.6.5` is `0.7.0`.
+- Supported prerelease channels are `beta` and `rc`, with versions like `0.11.3-beta.1` and `0.11.3-rc.1`.
 - Pass `--date` explicitly when you want the release stamped with the local cut date; otherwise the generator uses the current ISO date, which can roll over to the next UTC day late at night.
 - `changelog:check` now rejects tag/package version mismatches.
+- `changelog:prerelease-notes` also rejects tag/package version mismatches and writes `release/prerelease-notes.md` without mutating tracked changelog files.
 - `changelog:build` generates `CHANGELOG.md` + `release/release-notes.md` and removes the released `changes/*.md` fragments.
 - In the same way, the release workflow now auto-runs `changelog:build` when it detects unreleased `changes/*.md` on a tag-based run, then verifies and publishes.
 - Do not tag while `changes/*.md` fragments still exist.
+- Prerelease tags intentionally keep `changes/*.md` fragments in place so multiple prereleases can reuse the same cumulative pending notes until the final stable cut.
 - If you need to repair a published release body (for example, a prior version’s section was omitted), regenerate notes from `CHANGELOG.md` and re-edit the release with `gh release edit --notes-file`.
+- Prerelease tags are handled by `.github/workflows/prerelease.yml`, which always publishes a GitHub prerelease with all current release platforms and never runs the AUR sync job.
 - Tagged release workflow now also attempts to update `subminer-bin` on the AUR after GitHub Release publication.
 - AUR publish is best-effort: the workflow retries transient SSH clone/push failures, then warns and leaves the GitHub Release green if AUR still fails. Follow up with a manual `git push aur master` from the AUR checkout when needed.
 - Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.

launcher/commands/command-modules.test.ts

@@ -190,7 +190,43 @@ test('dictionary command forwards --dictionary and target path to app binary', (
   });
 
   assert.equal(handled, true);
-  assert.deepEqual(forwarded, [['--dictionary', '--dictionary-target', '/tmp/anime']]);
+  assert.deepEqual(forwarded, [['--start', '--dictionary', '--dictionary-target', '/tmp/anime']]);
+});
+
+test('dictionary command forwards candidate and selection modes to app binary', () => {
+  const candidatesContext = createContext();
+  candidatesContext.args.dictionary = true;
+  candidatesContext.args.dictionaryCandidates = true;
+  candidatesContext.args.dictionaryTarget = '/tmp/anime.mkv';
+  const selectContext = createContext();
+  selectContext.args.dictionary = true;
+  selectContext.args.dictionarySelect = true;
+  selectContext.args.dictionaryAnilistId = 21355;
+  selectContext.args.dictionaryTarget = '/tmp/anime.mkv';
+  const forwarded: string[][] = [];
+
+  runDictionaryCommand(candidatesContext, {
+    runAppCommandWithInherit: (_appPath, appArgs) => {
+      forwarded.push(appArgs);
+    },
+  });
+  runDictionaryCommand(selectContext, {
+    runAppCommandWithInherit: (_appPath, appArgs) => {
+      forwarded.push(appArgs);
+    },
+  });
+
+  assert.deepEqual(forwarded, [
+    ['--start', '--dictionary-candidates', '--dictionary-target', '/tmp/anime.mkv'],
+    [
+      '--start',
+      '--dictionary-select',
+      '--dictionary-anilist-id',
+      '21355',
+      '--dictionary-target',
+      '/tmp/anime.mkv',
+    ],
+  ]);
 });
 
 test('dictionary command returns after app handoff starts', () => {

launcher/commands/dictionary-command.ts

@@ -18,7 +18,20 @@ export function runDictionaryCommand(
     return false;
   }
 
-  const forwarded = ['--dictionary'];
+  const forwarded = [
+    '--start',
+    args.dictionaryCandidates
+      ? '--dictionary-candidates'
+      : args.dictionarySelect
+        ? '--dictionary-select'
+        : '--dictionary',
+  ];
+  if (args.dictionarySelect) {
+    if (!args.dictionaryAnilistId) {
+      throw new Error('Dictionary selection requires an AniList media ID.');
+    }
+    forwarded.push('--dictionary-anilist-id', String(args.dictionaryAnilistId));
+  }
   if (typeof args.dictionaryTarget === 'string' && args.dictionaryTarget.trim()) {
     forwarded.push('--dictionary-target', args.dictionaryTarget);
   }

launcher/commands/playback-command.test.ts

@@ -44,6 +44,8 @@ function createContext(): LauncherCommandContext {
       jellyfinPlay: false,
       jellyfinDiscovery: false,
       dictionary: false,
+      dictionaryCandidates: false,
+      dictionarySelect: false,
       stats: false,
       doctor: false,
       doctorRefreshKnownWords: false,

launcher/config/args-normalizer.test.ts

@@ -129,6 +129,9 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
     dictionaryTriggered: false,
     dictionaryTarget: null,
     dictionaryLogLevel: null,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
+    dictionaryAnilistId: null,
     statsTriggered: false,
     statsBackground: false,
     statsStop: false,

launcher/config/args-normalizer.ts

@@ -89,6 +89,14 @@ function parseDictionaryTarget(value: string): string {
   return resolved;
 }
 
+function parseDictionaryAnilistId(value: string): number {
+  const id = Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(id) || id <= 0 || String(id) !== value.trim()) {
+    fail(`Invalid AniList media ID: ${value}`);
+  }
+  return id;
+}
+
 export function createDefaultArgs(
   launcherConfig: LauncherYoutubeSubgenConfig,
   mpvConfig: LauncherMpvConfig = {},
@@ -138,6 +146,8 @@ export function createDefaultArgs(
     jellyfinPlay: false,
     jellyfinDiscovery: false,
     dictionary: false,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
     stats: false,
     statsBackground: false,
     statsStop: false,
@@ -214,6 +224,11 @@ export function applyRootOptionsToArgs(
 
 export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations): void {
   if (invocations.dictionaryTriggered) parsed.dictionary = true;
+  if (invocations.dictionaryCandidates) parsed.dictionaryCandidates = true;
+  if (invocations.dictionarySelect) parsed.dictionarySelect = true;
+  if (invocations.dictionaryAnilistId) {
+    parsed.dictionaryAnilistId = parseDictionaryAnilistId(invocations.dictionaryAnilistId);
+  }
   if (invocations.statsTriggered) parsed.stats = true;
   if (invocations.statsBackground) parsed.statsBackground = true;
   if (invocations.statsStop) parsed.statsStop = true;
@@ -222,6 +237,12 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
   if (invocations.statsCleanupLifetime) parsed.statsCleanupLifetime = true;
   if (invocations.dictionaryTarget) {
     parsed.dictionaryTarget = parseDictionaryTarget(invocations.dictionaryTarget);
+  } else if (
+    invocations.dictionaryTriggered &&
+    !invocations.dictionaryCandidates &&
+    !invocations.dictionarySelect
+  ) {
+    fail('Dictionary target path is required.');
   }
   if (invocations.doctorTriggered) parsed.doctor = true;
   if (invocations.doctorRefreshKnownWords) parsed.doctorRefreshKnownWords = true;

launcher/config/cli-parser-builder.ts

@@ -27,6 +27,9 @@ export interface CliInvocations {
   dictionaryTriggered: boolean;
   dictionaryTarget: string | null;
   dictionaryLogLevel: string | null;
+  dictionaryCandidates: boolean;
+  dictionarySelect: boolean;
+  dictionaryAnilistId: string | null;
   statsTriggered: boolean;
   statsBackground: boolean;
   statsStop: boolean;
@@ -136,6 +139,9 @@ export function parseCliPrograms(
   let dictionaryTriggered = false;
   let dictionaryTarget: string | null = null;
   let dictionaryLogLevel: string | null = null;
+  let dictionaryCandidates = false;
+  let dictionarySelect = false;
+  let dictionaryAnilistId: string | null = null;
   let statsTriggered = false;
   let statsBackground = false;
   let statsStop = false;
@@ -207,13 +213,23 @@ export function parseCliPrograms(
   commandProgram
     .command('dictionary')
     .alias('dict')
-    .description('Generate character dictionary ZIP from a file or directory target')
-    .argument('<target>', 'Video file path or anime directory path')
+    .description('Generate or correct character dictionary AniList matches')
+    .argument('[target]', 'Video file path or anime directory path')
+    .option('--candidates', 'List AniList candidates for a character dictionary target')
+    .option('--select <id>', 'Pin an AniList media ID for the target series')
     .option('--log-level <level>', 'Log level')
-    .action((target: string, options: Record<string, unknown>) => {
+    .action((target: string | undefined, options: Record<string, unknown>) => {
+      const selectValue = typeof options.select === 'string' ? options.select.trim() : '';
+      const hasSelect = selectValue.length > 0;
+      if (options.candidates === true && hasSelect) {
+        throw new Error('Dictionary --candidates and --select cannot be combined.');
+      }
       dictionaryTriggered = true;
-      dictionaryTarget = target;
+      dictionaryTarget = target ?? null;
       dictionaryLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
+      dictionaryCandidates = options.candidates === true;
+      dictionarySelect = hasSelect;
+      dictionaryAnilistId = hasSelect ? selectValue : null;
     });
 
   commandProgram
@@ -338,6 +354,9 @@ export function parseCliPrograms(
       dictionaryTriggered,
       dictionaryTarget,
       dictionaryLogLevel,
+      dictionaryCandidates,
+      dictionarySelect,
+      dictionaryAnilistId,
       statsTriggered,
       statsBackground,
       statsStop,

launcher/main.test.ts

@@ -464,7 +464,40 @@ test('dictionary command forwards --dictionary and --dictionary-target to app co
     assert.equal(result.status, 0);
     assert.equal(
       fs.readFileSync(capturePath, 'utf8'),
-      `--dictionary\n--dictionary-target\n${targetPath}\n`,
+      `--start\n--dictionary\n--dictionary-target\n${targetPath}\n`,
+    );
+  });
+});
+
+test('dictionary command forwards manual AniList selection modes to app command path', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const appPath = path.join(root, 'fake-subminer.sh');
+    const capturePath = path.join(root, 'captured-args.txt');
+    fs.writeFileSync(
+      appPath,
+      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+    );
+    fs.chmodSync(appPath, 0o755);
+
+    const env = {
+      ...makeTestEnv(homeDir, xdgConfigHome),
+      SUBMINER_APPIMAGE_PATH: appPath,
+      SUBMINER_TEST_CAPTURE: capturePath,
+    };
+    const targetPath = path.join(root, 'anime.mkv');
+    fs.writeFileSync(targetPath, '');
+
+    assert.equal(runLauncher(['dictionary', '--candidates', targetPath], env).status, 0);
+    assert.equal(
+      fs.readFileSync(capturePath, 'utf8'),
+      `--start\n--dictionary-candidates\n--dictionary-target\n${targetPath}\n`,
+    );
+    assert.equal(runLauncher(['dictionary', '--select', '21355', targetPath], env).status, 0);
+    assert.equal(
+      fs.readFileSync(capturePath, 'utf8'),
+      `--start\n--dictionary-select\n--dictionary-anilist-id\n21355\n--dictionary-target\n${targetPath}\n`,
     );
   });
 });

launcher/mpv.test.ts

@@ -415,6 +415,8 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
     jellyfinPlay: false,
     jellyfinDiscovery: false,
     dictionary: false,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
     stats: false,
     doctor: false,
     doctorRefreshKnownWords: false,

launcher/parse-args.test.ts

@@ -99,6 +99,25 @@ test('parseArgs maps dictionary command and log-level override', () => {
   assert.equal(parsed.logLevel, 'debug');
 });
 
+test('parseArgs maps dictionary candidate lookup and manual selection', () => {
+  const candidateParsed = parseArgs(['dictionary', '--candidates', '.'], 'subminer', {});
+  assert.equal(candidateParsed.dictionaryCandidates, true);
+  assert.equal(candidateParsed.dictionaryTarget, process.cwd());
+
+  const selectParsed = parseArgs(['dictionary', '--select', '21355', '.'], 'subminer', {});
+  assert.equal(selectParsed.dictionarySelect, true);
+  assert.equal(selectParsed.dictionaryAnilistId, 21355);
+  assert.equal(selectParsed.dictionaryTarget, process.cwd());
+});
+
+test('parseArgs rejects conflicting dictionary candidate and selection modes', () => {
+  const exit = withProcessExitIntercept(() => {
+    parseArgs(['dictionary', '--candidates', '--select', '21355', '.'], 'subminer', {});
+  });
+
+  assert.equal(exit.code, 1);
+});
+
 test('parseArgs maps stats command and log-level override', () => {
   const parsed = parseArgs(['stats', '--log-level', 'debug'], 'subminer', {});
 

launcher/types.ts

@@ -121,6 +121,9 @@ export interface Args {
   jellyfinPlay: boolean;
   jellyfinDiscovery: boolean;
   dictionary: boolean;
+  dictionaryCandidates: boolean;
+  dictionarySelect: boolean;
+  dictionaryAnilistId?: number;
   stats: boolean;
   statsBackground?: boolean;
   statsStop?: boolean;

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",
@@ -20,12 +20,13 @@
     "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 && bun run changelog:docs",
+    "changelog:build": "bun run scripts/build-changelog.ts build-release",
     "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",
+    "changelog:prerelease-notes": "bun run scripts/build-changelog.ts prerelease-notes",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "format:src": "bash scripts/prettier-scope.sh --write",
@@ -44,7 +45,7 @@
     "test:config:src": "bun test src/config/config.test.ts src/config/path-resolution.test.ts src/config/resolve/anki-connect.test.ts src/config/resolve/integrations.test.ts src/config/resolve/subtitle-style.test.ts src/config/resolve/jellyfin.test.ts src/config/definitions/domain-registry.test.ts src/generate-config-example.test.ts src/verify-config-example.test.ts",
     "test:config:dist": "bun test dist/config/config.test.js dist/config/path-resolution.test.js dist/config/resolve/anki-connect.test.js dist/config/resolve/integrations.test.js dist/config/resolve/subtitle-style.test.js dist/config/resolve/jellyfin.test.js dist/config/definitions/domain-registry.test.js dist/generate-config-example.test.js dist/verify-config-example.test.js",
     "test:config:smoke:dist": "bun test dist/config/path-resolution.test.js",
-    "test:plugin:src": "lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-binary-windows.lua",
+    "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-binary-windows.lua",
     "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
     "test:launcher:src": "bun test launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/mpv.test.ts launcher/picker.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/smoke.e2e.test.ts && bun run test:plugin:src",
     "test:core:src": "bun test src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts",
@@ -69,7 +70,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/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",
+    "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/card-creation-manual-update.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/prerelease-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",
@@ -112,6 +113,7 @@
     "commander": "^14.0.3",
     "hono": "^4.12.7",
     "jsonc-parser": "^3.3.1",
+    "koffi": "^2.15.6",
     "libsql": "^0.5.22",
     "ws": "^8.19.0"
   },

plugin/subminer/bootstrap.lua

@@ -14,7 +14,7 @@ function M.init()
 	local utils = require("mp.utils")
 
 	local options_helper = require("options")
-	local environment = require("environment").create({ mp = mp })
+	local environment = require("environment").create({ mp = mp, utils = utils })
 	local opts = options_helper.load(options_lib, environment.default_socket_path())
 	local state = require("state").new()
 
@@ -61,6 +61,9 @@ function M.init()
 	ctx.process = make_lazy_proxy("process", function()
 		return require("process").create(ctx)
 	end)
+	ctx.session_bindings = make_lazy_proxy("session_bindings", function()
+		return require("session_bindings").create(ctx)
+	end)
 	ctx.ui = make_lazy_proxy("ui", function()
 		return require("ui").create(ctx)
 	end)
@@ -72,6 +75,7 @@ function M.init()
 	end)
 
 	ctx.ui.register_keybindings()
+	ctx.session_bindings.register_bindings()
 	ctx.messages.register_script_messages()
 	ctx.lifecycle.register_lifecycle_hooks()
 	ctx.log.subminer_log("info", "lifecycle", "SubMiner plugin loaded")

plugin/subminer/environment.lua

@@ -1,7 +1,9 @@
 local M = {}
+local unpack_fn = table.unpack or unpack
 
 function M.create(ctx)
 	local mp = ctx.mp
+	local utils = ctx.utils
 
 	local detected_backend = nil
 	local app_running_cache_value = nil
@@ -30,6 +32,63 @@ function M.create(ctx)
 		return "/tmp/subminer-socket"
 	end
 
+	local function path_separator()
+		return is_windows() and "\\" or "/"
+	end
+
+	local function join_path(...)
+		local parts = { ... }
+		if utils and type(utils.join_path) == "function" then
+			return utils.join_path(unpack_fn(parts))
+		end
+		return table.concat(parts, path_separator())
+	end
+
+	local function file_exists(path)
+		if not utils or type(utils.file_info) ~= "function" then
+			return false
+		end
+		return utils.file_info(path) ~= nil
+	end
+
+	local function resolve_subminer_config_dir()
+		local home = os.getenv("HOME") or os.getenv("USERPROFILE") or ""
+		local candidates = {}
+		if is_windows() then
+			local app_data = os.getenv("APPDATA") or join_path(home, "AppData", "Roaming")
+			candidates = {
+				join_path(app_data, "SubMiner"),
+			}
+		else
+			local xdg_config_home = os.getenv("XDG_CONFIG_HOME")
+			local primary_base = (type(xdg_config_home) == "string" and xdg_config_home ~= "")
+					and xdg_config_home
+				or join_path(home, ".config")
+			candidates = {
+				join_path(primary_base, "SubMiner"),
+				join_path(home, ".config", "SubMiner"),
+			}
+		end
+
+		for _, dir in ipairs(candidates) do
+			if file_exists(join_path(dir, "config.jsonc")) or file_exists(join_path(dir, "config.json")) then
+				return dir
+			end
+		end
+
+		for _, dir in ipairs(candidates) do
+			if file_exists(dir) then
+				return dir
+			end
+		end
+
+		return candidates[1]
+	end
+
+	local function resolve_session_bindings_artifact_path()
+		return join_path(resolve_subminer_config_dir(), "session-bindings.json")
+	end
+
 	local function is_linux()
 		return not is_windows() and not is_macos()
 	end
@@ -55,23 +114,17 @@ function M.create(ctx)
 				if not image then
 					image = line:match('^"([^"]+)"')
 				end
-				if not image then
-					goto continue
-				end
+				if image then
 					if image == "subminer" or image == "subminer.exe" or image == "subminer.appimage" or image == "subminer.app" then
 						return true
 					end
 					if image:find("subminer", 1, true) and not image:find(".lua", 1, true) then
 						return true
 					end
+				end
 			else
 				local argv0 = line:match('^"([^"]+)"') or line:match("^%s*([^%s]+)")
-				if not argv0 then
-					goto continue
-				end
-				if argv0:find("subminer.lua", 1, true) or argv0:find("subminer.conf", 1, true) then
-					goto continue
-				end
+				if argv0 and not argv0:find("subminer.lua", 1, true) and not argv0:find("subminer.conf", 1, true) then
 					local exe = argv0:match("([^/\\]+)$") or argv0
 					if exe == "SubMiner" or exe == "SubMiner.AppImage" or exe == "SubMiner.exe" or exe == "subminer" or exe == "subminer.appimage" or exe == "subminer.exe" then
 						return true
@@ -80,8 +133,7 @@ function M.create(ctx)
 						return true
 					end
 				end
-
-			::continue::
+			end
 		end
 		return false
 	end
@@ -198,7 +250,10 @@ function M.create(ctx)
 		is_windows = is_windows,
 		is_macos = is_macos,
 		is_linux = is_linux,
+		join_path = join_path,
 		default_socket_path = default_socket_path,
+		resolve_subminer_config_dir = resolve_subminer_config_dir,
+		resolve_session_bindings_artifact_path = resolve_session_bindings_artifact_path,
 		is_subminer_process_running = is_subminer_process_running,
 		is_subminer_app_running = is_subminer_app_running,
 		is_subminer_app_running_async = is_subminer_app_running_async,

plugin/subminer/hover.lua

@@ -189,10 +189,7 @@ function M.create(ctx)
 		local source_len = #plain
 		local cursor = 1
 		for _, token in ipairs(payload.tokens or {}) do
-			if type(token) ~= "table" or type(token.text) ~= "string" or token.text == "" then
-				goto continue
-			end
-
+			if type(token) == "table" and type(token.text) == "string" and token.text ~= "" then
 				local token_text = token.text
 				local start_pos = nil
 				local end_pos = nil
@@ -222,8 +219,7 @@ function M.create(ctx)
 					end
 					cursor = end_pos + 1
 				end
-
-			::continue::
+			end
 		end
 
 		return nil

plugin/subminer/lifecycle.lua

@@ -73,10 +73,6 @@ function M.create(ctx)
 		aniskip.clear_aniskip_state()
 		hover.clear_hover_overlay()
 		process.disarm_auto_play_ready_gate()
-		if state.overlay_running then
-			subminer_log("info", "lifecycle", "mpv shutting down, hiding SubMiner overlay")
-			process.hide_visible_overlay()
-		end
 	end
 
 	local function register_lifecycle_hooks()
@@ -85,10 +81,11 @@ function M.create(ctx)
 		mp.register_event("file-loaded", function()
 			hover.clear_hover_overlay()
 		end)
-		mp.register_event("end-file", function()
+		mp.register_event("end-file", function(event)
 			process.disarm_auto_play_ready_gate()
 			hover.clear_hover_overlay()
-			if state.overlay_running then
+			local reason = type(event) == "table" and event.reason or nil
+			if state.overlay_running and reason ~= "quit" then
 				process.hide_visible_overlay()
 			end
 		end)

plugin/subminer/messages.lua

@@ -47,6 +47,9 @@ function M.create(ctx)
 		mp.register_script_message("subminer-stats-toggle", function()
 			mp.osd_message("Stats: press ` (backtick) in overlay", 3)
 		end)
+		mp.register_script_message("subminer-reload-session-bindings", function()
+			ctx.session_bindings.reload_bindings()
+		end)
 	end
 
 	return {

plugin/subminer/process.lua

@@ -186,6 +186,9 @@ function M.create(ctx)
 		end
 
 		if action == "start" then
+			table.insert(args, "--background")
+			table.insert(args, "--managed-playback")
+
 			local backend = resolve_backend(overrides.backend)
 			if backend and backend ~= "" then
 				table.insert(args, "--backend")
@@ -229,6 +232,22 @@ function M.create(ctx)
 		end)
 	end
 
+	local function run_binary_command_async(args, callback)
+		subminer_log("debug", "process", "Binary command: " .. table.concat(args, " "))
+		mp.command_native_async({
+			name = "subprocess",
+			args = args,
+			playback_only = false,
+			capture_stdout = true,
+			capture_stderr = true,
+		}, function(success, result, error)
+			local ok = success and (result == nil or result.status == 0)
+			if callback then
+				callback(ok, result, error)
+			end
+		end)
+	end
+
 	local function parse_start_script_message_overrides(...)
 		local overrides = {}
 		for i = 1, select("#", ...) do
@@ -446,6 +465,21 @@ function M.create(ctx)
 		end)
 	end
 
+	local function toggle_primary_subtitle_bar()
+		if not binary.ensure_binary_available() then
+			subminer_log("error", "binary", "SubMiner binary not found")
+			show_osd("Error: binary not found")
+			return
+		end
+
+		run_control_command_async("toggle-primary-subtitle-bar", nil, function(ok)
+			if not ok then
+				subminer_log("warn", "process", "Primary subtitle bar toggle command failed")
+				show_osd("Primary subtitle toggle failed")
+			end
+		end)
+	end
+
 	local function open_options()
 		if not binary.ensure_binary_available() then
 			subminer_log("error", "binary", "SubMiner binary not found")
@@ -528,6 +562,7 @@ function M.create(ctx)
 		build_command_args = build_command_args,
 		has_matching_mpv_ipc_socket = has_matching_mpv_ipc_socket,
 		run_control_command_async = run_control_command_async,
+		run_binary_command_async = run_binary_command_async,
 		parse_start_script_message_overrides = parse_start_script_message_overrides,
 		ensure_texthooker_running = ensure_texthooker_running,
 		start_overlay = start_overlay,
@@ -535,6 +570,7 @@ function M.create(ctx)
 		stop_overlay = stop_overlay,
 		hide_visible_overlay = hide_visible_overlay,
 		toggle_overlay = toggle_overlay,
+		toggle_primary_subtitle_bar = toggle_primary_subtitle_bar,
 		open_options = open_options,
 		restart_overlay = restart_overlay,
 		check_status = check_status,

plugin/subminer/session_bindings.lua

@@ -0,0 +1,359 @@
+local M = {}
+
+local unpack_fn = table.unpack or unpack
+
+local KEY_NAME_MAP = {
+	Space = "SPACE",
+	Tab = "TAB",
+	Enter = "ENTER",
+	Escape = "ESC",
+	Backspace = "BS",
+	Delete = "DEL",
+	ArrowUp = "UP",
+	ArrowDown = "DOWN",
+	ArrowLeft = "LEFT",
+	ArrowRight = "RIGHT",
+	Slash = "/",
+	Backslash = "\\",
+	Minus = "-",
+	Equal = "=",
+	Comma = ",",
+	Period = ".",
+	Quote = "'",
+	Semicolon = ";",
+	BracketLeft = "[",
+	BracketRight = "]",
+	Backquote = "`",
+}
+
+local MODIFIER_MAP = {
+	ctrl = "Ctrl",
+	alt = "Alt",
+	shift = "Shift",
+	meta = "Meta",
+}
+
+function M.create(ctx)
+	local mp = ctx.mp
+	local utils = ctx.utils
+	local state = ctx.state
+	local process = ctx.process
+	local environment = ctx.environment
+	local subminer_log = ctx.log.subminer_log
+	local show_osd = ctx.log.show_osd
+
+	local function read_file(path)
+		local handle = io.open(path, "r")
+		if not handle then
+			return nil
+		end
+		local content = handle:read("*a")
+		handle:close()
+		return content
+	end
+
+	local function remove_binding_names(names)
+		for _, name in ipairs(names) do
+			mp.remove_key_binding(name)
+		end
+		for index = #names, 1, -1 do
+			names[index] = nil
+		end
+	end
+
+	local function key_code_to_mpv_name(code)
+		if KEY_NAME_MAP[code] then
+			return KEY_NAME_MAP[code]
+		end
+
+		local letter = code:match("^Key([A-Z])$")
+		if letter then
+			return string.lower(letter)
+		end
+
+		local digit = code:match("^Digit([0-9])$")
+		if digit then
+			return digit
+		end
+
+		local function_key = code:match("^(F%d+)$")
+		if function_key then
+			return function_key
+		end
+
+		return nil
+	end
+
+	local function key_spec_to_mpv_binding(key)
+		if type(key) ~= "table" then
+			return nil
+		end
+
+		if type(key.code) ~= "string" then
+			return nil
+		end
+		if type(key.modifiers) ~= "table" then
+			return nil
+		end
+
+		local key_name = key_code_to_mpv_name(key.code)
+		if not key_name then
+			return nil
+		end
+
+		local parts = {}
+		for _, modifier in ipairs(key.modifiers) do
+			local mapped = MODIFIER_MAP[modifier]
+			if mapped then
+				parts[#parts + 1] = mapped
+			end
+		end
+		parts[#parts + 1] = key_name
+		return table.concat(parts, "+")
+	end
+
+	local function build_cli_args(action_id, payload)
+		if action_id == "toggleVisibleOverlay" then
+			return { "--toggle-visible-overlay" }
+		elseif action_id == "toggleStatsOverlay" then
+			return { "--toggle-stats-overlay" }
+		elseif action_id == "copySubtitle" then
+			return { "--copy-subtitle" }
+		elseif action_id == "copySubtitleMultiple" then
+			return { "--copy-subtitle-count", tostring(payload and payload.count or 1) }
+		elseif action_id == "updateLastCardFromClipboard" then
+			return { "--update-last-card-from-clipboard" }
+		elseif action_id == "triggerFieldGrouping" then
+			return { "--trigger-field-grouping" }
+		elseif action_id == "triggerSubsync" then
+			return { "--trigger-subsync" }
+		elseif action_id == "mineSentence" then
+			return { "--mine-sentence" }
+		elseif action_id == "mineSentenceMultiple" then
+			return { "--mine-sentence-count", tostring(payload and payload.count or 1) }
+		elseif action_id == "toggleSecondarySub" then
+			return { "--toggle-secondary-sub" }
+		elseif action_id == "toggleSubtitleSidebar" then
+			return { "--toggle-subtitle-sidebar" }
+		elseif action_id == "markAudioCard" then
+			return { "--mark-audio-card" }
+		elseif action_id == "openRuntimeOptions" then
+			return { "--open-runtime-options" }
+		elseif action_id == "openJimaku" then
+			return { "--open-jimaku" }
+		elseif action_id == "openYoutubePicker" then
+			return { "--open-youtube-picker" }
+		elseif action_id == "openSessionHelp" then
+			return { "--open-session-help" }
+		elseif action_id == "openControllerSelect" then
+			return { "--open-controller-select" }
+		elseif action_id == "openControllerDebug" then
+			return { "--open-controller-debug" }
+		elseif action_id == "openPlaylistBrowser" then
+			return { "--open-playlist-browser" }
+		elseif action_id == "replayCurrentSubtitle" then
+			return { "--replay-current-subtitle" }
+		elseif action_id == "playNextSubtitle" then
+			return { "--play-next-subtitle" }
+		elseif action_id == "shiftSubDelayPrevLine" then
+			return { "--shift-sub-delay-prev-line" }
+		elseif action_id == "shiftSubDelayNextLine" then
+			return { "--shift-sub-delay-next-line" }
+		elseif action_id == "cycleRuntimeOption" then
+			local runtime_option_id = payload and payload.runtimeOptionId or nil
+			if type(runtime_option_id) ~= "string" or runtime_option_id == "" then
+				return nil
+			end
+			local direction = payload and payload.direction == -1 and "prev" or "next"
+			return { "--cycle-runtime-option", runtime_option_id .. ":" .. direction }
+		end
+
+		return nil
+	end
+
+	local function invoke_cli_action(action_id, payload)
+		if not process.check_binary_available() then
+			show_osd("Error: binary not found")
+			return
+		end
+
+		local cli_args = build_cli_args(action_id, payload)
+		if not cli_args then
+			subminer_log("warn", "session-bindings", "No CLI mapping for action: " .. tostring(action_id))
+			return
+		end
+
+		local args = { state.binary_path }
+		for _, arg in ipairs(cli_args) do
+			args[#args + 1] = arg
+		end
+		local runner = process.run_binary_command_async
+		if type(runner) ~= "function" then
+			runner = function(binary_args, callback)
+				mp.command_native_async({
+					name = "subprocess",
+					args = binary_args,
+					playback_only = false,
+					capture_stdout = true,
+					capture_stderr = true,
+				}, function(success, result, error)
+					local ok = success and (result == nil or result.status == 0)
+					if callback then
+						callback(ok, result, error)
+					end
+				end)
+			end
+		end
+		runner(args, function(ok, result, error)
+			if ok then
+				return
+			end
+			local reason = error or (result and result.stderr) or "unknown error"
+			subminer_log("warn", "session-bindings", "Session action failed: " .. tostring(reason))
+			show_osd("Session action failed")
+		end)
+	end
+
+	local function clear_numeric_selection(show_cancelled)
+		if state.session_numeric_selection and state.session_numeric_selection.timeout then
+			state.session_numeric_selection.timeout:kill()
+		end
+		state.session_numeric_selection = nil
+		remove_binding_names(state.session_numeric_binding_names)
+		if show_cancelled then
+			show_osd("Cancelled")
+		end
+	end
+
+	local function start_numeric_selection(action_id, timeout_ms)
+		clear_numeric_selection(false)
+		for digit = 1, 9 do
+			local digit_string = tostring(digit)
+			local name = "subminer-session-digit-" .. digit_string
+			state.session_numeric_binding_names[#state.session_numeric_binding_names + 1] = name
+			mp.add_forced_key_binding(digit_string, name, function()
+				clear_numeric_selection(false)
+				invoke_cli_action(action_id, { count = digit })
+			end)
+		end
+
+		state.session_numeric_binding_names[#state.session_numeric_binding_names + 1] =
+			"subminer-session-digit-cancel"
+		mp.add_forced_key_binding("ESC", "subminer-session-digit-cancel", function()
+			clear_numeric_selection(true)
+		end)
+
+		state.session_numeric_selection = {
+			action_id = action_id,
+			timeout = mp.add_timeout((timeout_ms or 3000) / 1000, function()
+				clear_numeric_selection(false)
+				show_osd(action_id == "copySubtitleMultiple" and "Copy timeout" or "Mine timeout")
+			end),
+		}
+
+		show_osd(
+			action_id == "copySubtitleMultiple"
+					and "Copy how many lines? Press 1-9 (Esc to cancel)"
+				or "Mine how many lines? Press 1-9 (Esc to cancel)"
+		)
+	end
+
+	local function execute_mpv_command(command)
+		if type(command) ~= "table" or command[1] == nil then
+			return
+		end
+		mp.commandv(unpack_fn(command))
+	end
+
+	local function handle_binding(binding, numeric_selection_timeout_ms)
+		if binding.actionType == "mpv-command" then
+			execute_mpv_command(binding.command)
+			return
+		end
+
+		if binding.actionId == "copySubtitleMultiple" or binding.actionId == "mineSentenceMultiple" then
+			start_numeric_selection(binding.actionId, numeric_selection_timeout_ms)
+			return
+		end
+
+		invoke_cli_action(binding.actionId, binding.payload)
+	end
+
+	local function load_artifact()
+		local artifact_path = environment.resolve_session_bindings_artifact_path()
+		local raw = read_file(artifact_path)
+		if not raw or raw == "" then
+			return nil, "Missing session binding artifact: " .. tostring(artifact_path)
+		end
+
+		local parsed, parse_error = utils.parse_json(raw)
+		if not parsed then
+			return nil, "Failed to parse session binding artifact: " .. tostring(parse_error)
+		end
+		if type(parsed) ~= "table" or type(parsed.bindings) ~= "table" then
+			return nil, "Invalid session binding artifact"
+		end
+
+		return parsed, nil
+	end
+
+	local function clear_bindings()
+		clear_numeric_selection(false)
+		remove_binding_names(state.session_binding_names)
+	end
+
+	local function register_bindings()
+		local artifact, load_error = load_artifact()
+		if not artifact then
+			subminer_log("warn", "session-bindings", load_error)
+			return false
+		end
+
+		clear_numeric_selection(false)
+
+		local previous_binding_names = state.session_binding_names
+		local next_binding_names = {}
+		state.session_binding_generation = (state.session_binding_generation or 0) + 1
+		local generation = state.session_binding_generation
+
+		local timeout_ms = tonumber(artifact.numericSelectionTimeoutMs) or 3000
+		for index, binding in ipairs(artifact.bindings) do
+			local key_name = key_spec_to_mpv_binding(binding.key)
+			if key_name then
+				local name = "subminer-session-binding-" .. tostring(generation) .. "-" .. tostring(index)
+				next_binding_names[#next_binding_names + 1] = name
+				mp.add_forced_key_binding(key_name, name, function()
+					handle_binding(binding, timeout_ms)
+				end)
+			else
+				subminer_log(
+					"warn",
+					"session-bindings",
+					"Skipped unsupported key code from artifact: " .. tostring(binding.key and binding.key.code or "unknown")
+				)
+			end
+		end
+
+		remove_binding_names(previous_binding_names)
+		state.session_binding_names = next_binding_names
+
+		subminer_log(
+			"info",
+			"session-bindings",
+			"Registered " .. tostring(#next_binding_names) .. " shared session bindings"
+		)
+		return true
+	end
+
+	local function reload_bindings()
+		return register_bindings()
+	end
+
+	return {
+		register_bindings = register_bindings,
+		reload_bindings = reload_bindings,
+		clear_bindings = clear_bindings,
+	}
+end
+
+return M

plugin/subminer/state.lua

@@ -33,6 +33,10 @@ function M.new()
 		auto_play_ready_timeout = nil,
 		auto_play_ready_osd_timer = nil,
 		suppress_ready_overlay_restore = false,
+		session_binding_generation = 0,
+		session_binding_names = {},
+		session_numeric_binding_names = {},
+		session_numeric_selection = nil,
 	}
 end
 

plugin/subminer/ui.lua

@@ -80,6 +80,9 @@ function M.create(ctx)
 		mp.add_key_binding("y-t", "subminer-toggle", function()
 			process.toggle_overlay()
 		end)
+		mp.add_forced_key_binding("v", "subminer-toggle-primary-subtitle-bar", function()
+			process.toggle_primary_subtitle_bar()
+		end)
 		mp.add_key_binding("y-y", "subminer-menu", show_menu)
 		mp.add_key_binding("y-o", "subminer-options", function()
 			process.open_options()
@@ -90,6 +93,12 @@ function M.create(ctx)
 		mp.add_key_binding("y-c", "subminer-status", function()
 			process.check_status()
 		end)
+		mp.add_key_binding("y-h", "subminer-session-help", function()
+			if not ensure_binary_for_menu() then
+				return
+			end
+			process.run_control_command_async("open-session-help")
+		end)
 		if type(opts.aniskip_button_key) == "string" and opts.aniskip_button_key ~= "" then
 			mp.add_key_binding(opts.aniskip_button_key, "subminer-skip-intro", function()
 				aniskip.skip_intro_now()

scripts/build-changelog.test.ts

@@ -139,6 +139,49 @@ test('writeChangelogArtifacts skips changelog prepend when release section alrea
   }
 });
 
+test('writeStableReleaseArtifacts reuses the requested version and date for changelog, release notes, and docs-site output', async () => {
+  const { writeStableReleaseArtifacts } = await loadModule();
+  const workspace = createWorkspace('write-stable-release-artifacts');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, 'docs-site'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.4.1' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(path.join(projectRoot, 'CHANGELOG.md'), '# Changelog\n', 'utf8');
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: fixed', 'area: release', '', '- Reused explicit stable release date.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const result = writeStableReleaseArtifacts({
+      cwd: projectRoot,
+      version: '0.4.1',
+      date: '2026-03-07',
+    });
+
+    assert.deepEqual(result.outputPaths, [path.join(projectRoot, 'CHANGELOG.md')]);
+    assert.equal(result.releaseNotesPath, path.join(projectRoot, 'release', 'release-notes.md'));
+    assert.equal(result.docsChangelogPath, path.join(projectRoot, 'docs-site', 'changelog.md'));
+
+    const changelog = fs.readFileSync(path.join(projectRoot, 'CHANGELOG.md'), 'utf8');
+    const docsChangelog = fs.readFileSync(
+      path.join(projectRoot, 'docs-site', 'changelog.md'),
+      'utf8',
+    );
+
+    assert.match(changelog, /## v0\.4\.1 \(2026-03-07\)/);
+    assert.match(docsChangelog, /## v0\.4\.1 \(2026-03-07\)/);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
 test('verifyChangelogReadyForRelease ignores README but rejects pending fragments and missing version sections', async () => {
   const { verifyChangelogReadyForRelease } = await loadModule();
   const workspace = createWorkspace('verify-release');
@@ -310,3 +353,186 @@ test('verifyPullRequestChangelog requires fragments for user-facing changes and
     }),
   );
 });
+
+test('writePrereleaseNotesForVersion writes cumulative beta notes without mutating stable changelog artifacts', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-beta-notes');
+  const projectRoot = path.join(workspace, 'SubMiner');
+  const changelogPath = path.join(projectRoot, 'CHANGELOG.md');
+  const docsChangelogPath = path.join(projectRoot, 'docs-site', 'changelog.md');
+  const existingChangelog = '# Changelog\n\n## v0.11.2 (2026-04-07)\n- Stable release.\n';
+  const existingDocsChangelog = '# Changelog\n\n## v0.11.2 (2026-04-07)\n- Stable docs release.\n';
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, 'docs-site'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.11.3-beta.1' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(changelogPath, existingChangelog, 'utf8');
+  fs.writeFileSync(docsChangelogPath, existingDocsChangelog, 'utf8');
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: added', 'area: overlay', '', '- Added prerelease coverage.'].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '002.md'),
+    ['type: fixed', 'area: launcher', '', '- Fixed prerelease packaging checks.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const outputPath = writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.11.3-beta.1',
+    });
+
+    assert.equal(outputPath, path.join(projectRoot, 'release', 'prerelease-notes.md'));
+    assert.equal(
+      fs.readFileSync(changelogPath, 'utf8'),
+      existingChangelog,
+      'stable CHANGELOG.md should remain unchanged',
+    );
+    assert.equal(
+      fs.readFileSync(docsChangelogPath, 'utf8'),
+      existingDocsChangelog,
+      'docs-site changelog should remain unchanged',
+    );
+    assert.equal(fs.existsSync(path.join(projectRoot, 'changes', '001.md')), true);
+    assert.equal(fs.existsSync(path.join(projectRoot, 'changes', '002.md')), true);
+
+    const prereleaseNotes = fs.readFileSync(outputPath, 'utf8');
+    assert.match(prereleaseNotes, /^> This is a prerelease build for testing\./m);
+    assert.match(
+      prereleaseNotes,
+      /## Highlights\n### Added\n- Overlay: Added prerelease coverage\./,
+    );
+    assert.match(prereleaseNotes, /### Fixed\n- Launcher: Fixed prerelease packaging checks\./);
+    assert.match(prereleaseNotes, /## Installation\n\nSee the README and docs\/installation guide/);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('writePrereleaseNotesForVersion supports rc prereleases', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-rc-notes');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.11.3-rc.1' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: changed', 'area: release', '', '- Prepared release candidate notes.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const outputPath = writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.11.3-rc.1',
+    });
+
+    const prereleaseNotes = fs.readFileSync(outputPath, 'utf8');
+    assert.match(
+      prereleaseNotes,
+      /## Highlights\n### Changed\n- Release: Prepared release candidate notes\./,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('writePrereleaseNotesForVersion rejects unsupported prerelease identifiers', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-alpha-reject');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.11.3-alpha.1' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: added', 'area: overlay', '', '- Unsupported alpha prerelease.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    assert.throws(
+      () =>
+        writePrereleaseNotesForVersion({
+          cwd: projectRoot,
+          version: '0.11.3-alpha.1',
+        }),
+      /Unsupported prerelease version \(0\.11\.3-alpha\.1\)/,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('writePrereleaseNotesForVersion rejects mismatched package versions', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-version-mismatch');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.11.3-beta.1' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: added', 'area: overlay', '', '- Mismatched prerelease.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    assert.throws(
+      () =>
+        writePrereleaseNotesForVersion({
+          cwd: projectRoot,
+          version: '0.11.3-beta.2',
+        }),
+      /package\.json version \(0\.11\.3-beta\.1\) does not match requested release version \(0\.11\.3-beta\.2\)/,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('writePrereleaseNotesForVersion rejects empty prerelease note generation when no fragments exist', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-no-fragments');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.11.3-beta.1' }, null, 2),
+    'utf8',
+  );
+
+  try {
+    assert.throws(
+      () =>
+        writePrereleaseNotesForVersion({
+          cwd: projectRoot,
+          version: '0.11.3-beta.1',
+        }),
+      /No changelog fragments found in changes\//,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});

scripts/build-changelog.ts

@@ -38,6 +38,7 @@ type PullRequestChangelogOptions = {
 };
 
 const RELEASE_NOTES_PATH = path.join('release', 'release-notes.md');
+const PRERELEASE_NOTES_PATH = path.join('release', 'prerelease-notes.md');
 const CHANGELOG_HEADER = '# Changelog';
 const CHANGE_TYPES: FragmentType[] = ['added', 'changed', 'fixed', 'docs', 'internal'];
 const CHANGE_TYPE_HEADINGS: Record<FragmentType, string> = {
@@ -75,6 +76,10 @@ function resolveVersion(options: Pick<ChangelogOptions, 'cwd' | 'version' | 'dep
   return normalizeVersion(options.version ?? resolvePackageVersion(cwd, readFileSync));
 }
 
+function isSupportedPrereleaseVersion(version: string): boolean {
+  return /^\d+\.\d+\.\d+-(beta|rc)\.\d+$/u.test(normalizeVersion(version));
+}
+
 function verifyRequestedVersionMatchesPackageVersion(
   options: Pick<ChangelogOptions, 'cwd' | 'version' | 'deps'>,
 ): void {
@@ -314,8 +319,15 @@ export function resolveChangelogOutputPaths(options?: { cwd?: string }): string[
   return [path.join(cwd, 'CHANGELOG.md')];
 }
 
-function renderReleaseNotes(changes: string): string {
+function renderReleaseNotes(
+  changes: string,
+  options?: {
+    disclaimer?: string;
+  },
+): string {
+  const prefix = options?.disclaimer ? [options.disclaimer, ''] : [];
   return [
+    ...prefix,
     '## Highlights',
     changes,
     '',
@@ -334,13 +346,21 @@ function renderReleaseNotes(changes: string): string {
   ].join('\n');
 }
 
-function writeReleaseNotesFile(cwd: string, changes: string, deps?: ChangelogFsDeps): string {
+function writeReleaseNotesFile(
+  cwd: string,
+  changes: string,
+  deps?: ChangelogFsDeps,
+  options?: {
+    disclaimer?: string;
+    outputPath?: string;
+  },
+): string {
   const mkdirSync = deps?.mkdirSync ?? fs.mkdirSync;
   const writeFileSync = deps?.writeFileSync ?? fs.writeFileSync;
-  const releaseNotesPath = path.join(cwd, RELEASE_NOTES_PATH);
+  const releaseNotesPath = path.join(cwd, options?.outputPath ?? RELEASE_NOTES_PATH);
 
   mkdirSync(path.dirname(releaseNotesPath), { recursive: true });
-  writeFileSync(releaseNotesPath, renderReleaseNotes(changes), 'utf8');
+  writeFileSync(releaseNotesPath, renderReleaseNotes(changes, options), 'utf8');
   return releaseNotesPath;
 }
 
@@ -410,6 +430,21 @@ export function writeChangelogArtifacts(options?: ChangelogOptions): {
   };
 }
 
+export function writeStableReleaseArtifacts(options?: ChangelogOptions): {
+  deletedFragmentPaths: string[];
+  docsChangelogPath: string;
+  outputPaths: string[];
+  releaseNotesPath: string;
+} {
+  const changelogResult = writeChangelogArtifacts(options);
+  const docsChangelogPath = generateDocsChangelog(options);
+
+  return {
+    ...changelogResult,
+    docsChangelogPath,
+  };
+}
+
 export function verifyChangelogFragments(options?: ChangelogOptions): void {
   readChangeFragments(options?.cwd ?? process.cwd(), options?.deps);
 }
@@ -613,6 +648,30 @@ export function writeReleaseNotesForVersion(options?: ChangelogOptions): string
   return writeReleaseNotesFile(cwd, changes, options?.deps);
 }
 
+export function writePrereleaseNotesForVersion(options?: ChangelogOptions): string {
+  verifyRequestedVersionMatchesPackageVersion(options ?? {});
+
+  const cwd = options?.cwd ?? process.cwd();
+  const version = resolveVersion(options ?? {});
+  if (!isSupportedPrereleaseVersion(version)) {
+    throw new Error(
+      `Unsupported prerelease version (${version}). Expected x.y.z-beta.N or x.y.z-rc.N.`,
+    );
+  }
+
+  const fragments = readChangeFragments(cwd, options?.deps);
+  if (fragments.length === 0) {
+    throw new Error('No changelog fragments found in changes/.');
+  }
+
+  const changes = renderGroupedChanges(fragments);
+  return writeReleaseNotesFile(cwd, changes, options?.deps, {
+    disclaimer:
+      '> This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.',
+    outputPath: PRERELEASE_NOTES_PATH,
+  });
+}
+
 function parseCliArgs(argv: string[]): {
   baseRef?: string;
   cwd?: string;
@@ -682,6 +741,11 @@ function main(): void {
     return;
   }
 
+  if (command === 'build-release') {
+    writeStableReleaseArtifacts(options);
+    return;
+  }
+
   if (command === 'check') {
     verifyChangelogReadyForRelease(options);
     return;
@@ -710,6 +774,11 @@ function main(): void {
     return;
   }
 
+  if (command === 'prerelease-notes') {
+    writePrereleaseNotesForVersion(options);
+    return;
+  }
+
   if (command === 'docs') {
     generateDocsChangelog(options);
     return;

scripts/get-mpv-window-windows.ps1

@@ -1,175 +0,0 @@
-param(
-  [ValidateSet('geometry')]
-  [string]$Mode = 'geometry',
-  [string]$SocketPath
-)
-
-$ErrorActionPreference = 'Stop'
-
-try {
-  Add-Type -TypeDefinition @"
-using System;
-using System.Runtime.InteropServices;
-
-public static class SubMinerWindowsHelper {
-  public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
-
-  [StructLayout(LayoutKind.Sequential)]
-  public struct RECT {
-    public int Left;
-    public int Top;
-    public int Right;
-    public int Bottom;
-  }
-
-  [DllImport("user32.dll")]
-  public static extern bool EnumWindows(EnumWindowsProc lpEnumFunc, IntPtr lParam);
-
-  [DllImport("user32.dll")]
-  [return: MarshalAs(UnmanagedType.Bool)]
-  public static extern bool IsWindowVisible(IntPtr hWnd);
-
-  [DllImport("user32.dll")]
-  public static extern bool IsIconic(IntPtr hWnd);
-
-  [DllImport("user32.dll")]
-  public static extern IntPtr GetForegroundWindow();
-
-  [DllImport("user32.dll", SetLastError = true)]
-  public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint processId);
-
-  [DllImport("user32.dll", SetLastError = true)]
-  [return: MarshalAs(UnmanagedType.Bool)]
-  public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
-
-  [DllImport("dwmapi.dll")]
-  public static extern int DwmGetWindowAttribute(IntPtr hwnd, int dwAttribute, out RECT pvAttribute, int cbAttribute);
-}
-"@
-
-  $DWMWA_EXTENDED_FRAME_BOUNDS = 9
-
-  function Get-WindowBounds {
-    param([IntPtr]$hWnd)
-
-    $rect = New-Object SubMinerWindowsHelper+RECT
-    $size = [System.Runtime.InteropServices.Marshal]::SizeOf($rect)
-    $dwmResult = [SubMinerWindowsHelper]::DwmGetWindowAttribute(
-      $hWnd,
-      $DWMWA_EXTENDED_FRAME_BOUNDS,
-      [ref]$rect,
-      $size
-    )
-
-    if ($dwmResult -ne 0) {
-      if (-not [SubMinerWindowsHelper]::GetWindowRect($hWnd, [ref]$rect)) {
-        return $null
-      }
-    }
-
-    $width = $rect.Right - $rect.Left
-    $height = $rect.Bottom - $rect.Top
-    if ($width -le 0 -or $height -le 0) {
-      return $null
-    }
-
-    return [PSCustomObject]@{
-      X = $rect.Left
-      Y = $rect.Top
-      Width = $width
-      Height = $height
-      Area = $width * $height
-    }
-  }
-
-  $commandLineByPid = @{}
-  if (-not [string]::IsNullOrWhiteSpace($SocketPath)) {
-    foreach ($process in Get-CimInstance Win32_Process) {
-      $commandLineByPid[[uint32]$process.ProcessId] = $process.CommandLine
-    }
-  }
-
-  $mpvMatches = New-Object System.Collections.Generic.List[object]
-  $foregroundWindow = [SubMinerWindowsHelper]::GetForegroundWindow()
-  $callback = [SubMinerWindowsHelper+EnumWindowsProc]{
-    param([IntPtr]$hWnd, [IntPtr]$lParam)
-
-    if (-not [SubMinerWindowsHelper]::IsWindowVisible($hWnd)) {
-      return $true
-    }
-
-    if ([SubMinerWindowsHelper]::IsIconic($hWnd)) {
-      return $true
-    }
-
-    [uint32]$windowProcessId = 0
-    [void][SubMinerWindowsHelper]::GetWindowThreadProcessId($hWnd, [ref]$windowProcessId)
-    if ($windowProcessId -eq 0) {
-      return $true
-    }
-
-    try {
-      $process = Get-Process -Id $windowProcessId -ErrorAction Stop
-    } catch {
-      return $true
-    }
-
-    if ($process.ProcessName -ine 'mpv') {
-      return $true
-    }
-
-    if (-not [string]::IsNullOrWhiteSpace($SocketPath)) {
-      $commandLine = $commandLineByPid[[uint32]$windowProcessId]
-      if ([string]::IsNullOrWhiteSpace($commandLine)) {
-        return $true
-      }
-      if (
-        ($commandLine -notlike "*--input-ipc-server=$SocketPath*") -and
-        ($commandLine -notlike "*--input-ipc-server $SocketPath*")
-      ) {
-        return $true
-      }
-    }
-
-    $bounds = Get-WindowBounds -hWnd $hWnd
-    if ($null -eq $bounds) {
-      return $true
-    }
-
-    $mpvMatches.Add([PSCustomObject]@{
-      HWnd = $hWnd
-      X = $bounds.X
-      Y = $bounds.Y
-      Width = $bounds.Width
-      Height = $bounds.Height
-      Area = $bounds.Area
-      IsForeground = ($foregroundWindow -ne [IntPtr]::Zero -and $hWnd -eq $foregroundWindow)
-    })
-
-    return $true
-  }
-
-  [void][SubMinerWindowsHelper]::EnumWindows($callback, [IntPtr]::Zero)
-
-  $focusedMatch = $mpvMatches | Where-Object { $_.IsForeground } | Select-Object -First 1
-  if ($null -ne $focusedMatch) {
-    [Console]::Error.WriteLine('focus=focused')
-  } else {
-    [Console]::Error.WriteLine('focus=not-focused')
-  }
-
-  if ($mpvMatches.Count -eq 0) {
-    Write-Output 'not-found'
-    exit 0
-  }
-
-  $bestMatch = if ($null -ne $focusedMatch) {
-    $focusedMatch
-  } else {
-    $mpvMatches | Sort-Object -Property Area, Width, Height -Descending | Select-Object -First 1
-  }
-  Write-Output "$($bestMatch.X),$($bestMatch.Y),$($bestMatch.Width),$($bestMatch.Height)"
-} catch {
-  [Console]::Error.WriteLine($_.Exception.Message)
-  exit 1
-}

scripts/mkv-to-readme-video.sh

@@ -28,6 +28,27 @@ USAGE
 force=0
 generate_webp=0
 input=""
+ffmpeg_bin="${FFMPEG_BIN:-ffmpeg}"
+
+normalize_path() {
+	local value="$1"
+	if command -v cygpath > /dev/null 2>&1; then
+		case "$value" in
+			[A-Za-z]:\\* | [A-Za-z]:/*)
+				cygpath -u "$value"
+				return 0
+				;;
+		esac
+	fi
+	if [[ "$value" =~ ^([A-Za-z]):[\\/](.*)$ ]]; then
+		local drive="${BASH_REMATCH[1],,}"
+		local rest="${BASH_REMATCH[2]}"
+		rest="${rest//\\//}"
+		printf '/mnt/%s/%s\n' "$drive" "$rest"
+		return 0
+	fi
+	printf '%s\n' "$value"
+}
 
 while [[ $# -gt 0 ]]; do
 	case "$1" in
@@ -63,9 +84,19 @@ if [[ -z "$input" ]]; then
 	exit 1
 fi
 
-if ! command -v ffmpeg > /dev/null 2>&1; then
+input="$(normalize_path "$input")"
+ffmpeg_bin="$(normalize_path "$ffmpeg_bin")"
+
+if [[ "$ffmpeg_bin" == */* ]]; then
+	if [[ ! -x "$ffmpeg_bin" ]]; then
+		echo "Error: ffmpeg binary is not executable: $ffmpeg_bin" >&2
+		exit 1
+	fi
+else
+	if ! command -v "$ffmpeg_bin" > /dev/null 2>&1; then
 		echo "Error: ffmpeg is not installed or not in PATH." >&2
 		exit 1
+	fi
 fi
 
 if [[ ! -f "$input" ]]; then
@@ -102,7 +133,7 @@ fi
 
 has_encoder() {
 	local encoder="$1"
-	ffmpeg -hide_banner -encoders 2> /dev/null | awk -v encoder="$encoder" '$2 == encoder { found = 1 } END { exit(found ? 0 : 1) }'
+	"$ffmpeg_bin" -hide_banner -encoders 2> /dev/null | awk -v encoder="$encoder" '$2 == encoder { found = 1 } END { exit(found ? 0 : 1) }'
 }
 
 pick_webp_encoder() {
@@ -123,7 +154,7 @@ webm_vf="${crop_vf},fps=30"
 echo "Generating MP4: $mp4_out"
 if has_encoder "h264_nvenc"; then
 	echo "Trying GPU encoder for MP4: h264_nvenc"
-	if ffmpeg "$overwrite_flag" -i "$input" \
+	if "$ffmpeg_bin" "$overwrite_flag" -i "$input" \
 		-vf "$crop_vf" \
 		-c:v h264_nvenc -preset p6 -rc:v vbr -cq:v 20 -b:v 0 \
 		-pix_fmt yuv420p -movflags +faststart \
@@ -132,7 +163,7 @@ if has_encoder "h264_nvenc"; then
 		:
 	else
 		echo "GPU MP4 encode failed; retrying with CPU encoder: libx264"
-		ffmpeg "$overwrite_flag" -i "$input" \
+		"$ffmpeg_bin" "$overwrite_flag" -i "$input" \
 			-vf "$crop_vf" \
 			-c:v libx264 -preset slow -crf 20 \
 			-profile:v high -level 4.1 -pix_fmt yuv420p \
@@ -142,7 +173,7 @@ if has_encoder "h264_nvenc"; then
 	fi
 else
 	echo "Using CPU encoder for MP4: libx264"
-	ffmpeg "$overwrite_flag" -i "$input" \
+	"$ffmpeg_bin" "$overwrite_flag" -i "$input" \
 		-vf "$crop_vf" \
 		-c:v libx264 -preset slow -crf 20 \
 		-profile:v high -level 4.1 -pix_fmt yuv420p \
@@ -154,7 +185,7 @@ fi
 echo "Generating WebM: $webm_out"
 if has_encoder "av1_nvenc"; then
 	echo "Trying GPU encoder for WebM: av1_nvenc"
-	if ffmpeg "$overwrite_flag" -i "$input" \
+	if "$ffmpeg_bin" "$overwrite_flag" -i "$input" \
 		-vf "$webm_vf" \
 		-c:v av1_nvenc -preset p6 -cq:v 34 -b:v 0 \
 		-c:a libopus -b:a 96k \
@@ -162,7 +193,7 @@ if has_encoder "av1_nvenc"; then
 		:
 	else
 		echo "GPU WebM encode failed; retrying with CPU encoder: libvpx-vp9"
-		ffmpeg "$overwrite_flag" -i "$input" \
+		"$ffmpeg_bin" "$overwrite_flag" -i "$input" \
 			-vf "$webm_vf" \
 			-c:v libvpx-vp9 -crf 34 -b:v 0 \
 			-row-mt 1 -threads 8 \
@@ -171,7 +202,7 @@ if has_encoder "av1_nvenc"; then
 	fi
 else
 	echo "Using CPU encoder for WebM: libvpx-vp9"
-	ffmpeg "$overwrite_flag" -i "$input" \
+	"$ffmpeg_bin" "$overwrite_flag" -i "$input" \
 		-vf "$webm_vf" \
 		-c:v libvpx-vp9 -crf 34 -b:v 0 \
 		-row-mt 1 -threads 8 \
@@ -185,7 +216,7 @@ if [[ "$generate_webp" -eq 1 ]]; then
 		exit 1
 	fi
 	echo "Generating animated WebP with $webp_encoder: $webp_out"
-	ffmpeg "$overwrite_flag" -i "$input" \
+	"$ffmpeg_bin" "$overwrite_flag" -i "$input" \
 		-vf "${crop_vf},fps=24,scale=960:-1:flags=lanczos" \
 		-c:v "$webp_encoder" \
 		-q:v 80 \
@@ -195,7 +226,7 @@ if [[ "$generate_webp" -eq 1 ]]; then
 fi
 
 echo "Generating poster: $poster_out"
-ffmpeg "$overwrite_flag" -ss 00:00:05 -i "$input" \
+"$ffmpeg_bin" "$overwrite_flag" -ss 00:00:05 -i "$input" \
 	-vf "$crop_vf" \
 	-vframes 1 \
 	-q:v 2 \

scripts/mkv-to-readme-video.test.ts

@@ -19,11 +19,33 @@ function writeExecutable(filePath: string, contents: string): void {
   fs.chmodSync(filePath, 0o755);
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function toBashPath(filePath: string): string {
+  if (process.platform !== 'win32') return filePath;
+
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
+  if (!match) return normalized;
+
+  const drive = match[1]!;
+  const rest = match[2]!;
+  const probe = spawnSync('bash', ['-c', 'uname -s'], { encoding: 'utf8' });
+  if (probe.status === 0 && /linux/i.test(probe.stdout)) {
+    return `/mnt/${drive.toLowerCase()}/${rest}`;
+  }
+
+  return `${drive.toUpperCase()}:/${rest}`;
+}
+
 test('mkv-to-readme-video accepts libwebp_anim when libwebp is unavailable', () => {
   withTempDir((root) => {
     const binDir = path.join(root, 'bin');
     const inputPath = path.join(root, 'sample.mkv');
     const ffmpegLogPath = path.join(root, 'ffmpeg-args.log');
+    const ffmpegLogPathBash = toBashPath(ffmpegLogPath);
 
     fs.mkdirSync(binDir, { recursive: true });
     fs.writeFileSync(inputPath, 'fake-video', 'utf8');
@@ -44,22 +66,33 @@ EOF
   exit 0
 fi
 
-printf '%s\\n' "$*" >> "${ffmpegLogPath}"
+if [[ "$#" -eq 0 ]]; then
+  exit 0
+fi
+
+printf '%s\\n' "$*" >> "${ffmpegLogPathBash}"
 output=""
 for arg in "$@"; do
   output="$arg"
 done
+if [[ -z "$output" ]]; then
+  exit 0
+fi
 mkdir -p "$(dirname "$output")"
 touch "$output"
 `,
     );
 
-    const result = spawnSync('bash', ['scripts/mkv-to-readme-video.sh', '--webp', inputPath], {
+    const ffmpegShimPath = toBashPath(path.join(binDir, 'ffmpeg'));
+    const ffmpegShimDir = toBashPath(binDir);
+    const inputBashPath = toBashPath(inputPath);
+    const command = [
+      `chmod +x ${shellQuote(ffmpegShimPath)}`,
+      `PATH=${shellQuote(`${ffmpegShimDir}:`)}"$PATH"`,
+      `scripts/mkv-to-readme-video.sh --webp ${shellQuote(inputBashPath)}`,
+    ].join('; ');
+    const result = spawnSync('bash', ['-lc', command], {
       cwd: process.cwd(),
-      env: {
-        ...process.env,
-        PATH: `${binDir}:${process.env.PATH || ''}`,
-      },
       encoding: 'utf8',
     });
 

scripts/prepare-build-assets.mjs

@@ -8,8 +8,6 @@ const repoRoot = path.resolve(scriptDir, '..');
 const rendererSourceDir = path.join(repoRoot, 'src', 'renderer');
 const rendererOutputDir = path.join(repoRoot, 'dist', 'renderer');
 const scriptsOutputDir = path.join(repoRoot, 'dist', 'scripts');
-const windowsHelperSourcePath = path.join(scriptDir, 'get-mpv-window-windows.ps1');
-const windowsHelperOutputPath = path.join(scriptsOutputDir, 'get-mpv-window-windows.ps1');
 const macosHelperSourcePath = path.join(scriptDir, 'get-mpv-window-macos.swift');
 const macosHelperBinaryPath = path.join(scriptsOutputDir, 'get-mpv-window-macos');
 const macosHelperSourceCopyPath = path.join(scriptsOutputDir, 'get-mpv-window-macos.swift');
@@ -33,11 +31,6 @@ function copyRendererAssets() {
   process.stdout.write(`Staged renderer assets in ${rendererOutputDir}\n`);
 }
 
-function stageWindowsHelper() {
-  copyFile(windowsHelperSourcePath, windowsHelperOutputPath);
-  process.stdout.write(`Staged Windows helper: ${windowsHelperOutputPath}\n`);
-}
-
 function fallbackToMacosSource() {
   copyFile(macosHelperSourcePath, macosHelperSourceCopyPath);
   process.stdout.write(`Staged macOS helper source fallback: ${macosHelperSourceCopyPath}\n`);
@@ -77,7 +70,6 @@ function buildMacosHelper() {
 
 function main() {
   copyRendererAssets();
-  stageWindowsHelper();
   buildMacosHelper();
 }
 

scripts/test-plugin-lua-compat.lua

@@ -0,0 +1,141 @@
+local MODULE_PATHS = {
+	"plugin/subminer/hover.lua",
+	"plugin/subminer/environment.lua",
+}
+
+local LEGACY_PARSER_CANDIDATES = {
+	"luajit",
+	"lua5.1",
+	"lua51",
+}
+
+local function assert_true(condition, message)
+	if condition then
+		return
+	end
+	error(message or "assert_true failed")
+end
+
+local function read_file(path)
+	local file = assert(io.open(path, "r"), "failed to open " .. path)
+	local content = file:read("*a")
+	file:close()
+	return content
+end
+
+local function find_legacy_incompatible_continue(source)
+	local goto_start, goto_end = source:find("%f[%a]goto%s+continue%f[%A]")
+	if goto_start then
+		return "goto continue", goto_start, goto_end
+	end
+
+	local label_start, label_end = source:find("::continue::", 1, true)
+	if label_start then
+		return "::continue::", label_start, label_end
+	end
+
+	return nil
+end
+
+local function assert_no_legacy_incompatible_continue(path)
+	local source = read_file(path)
+	local match = find_legacy_incompatible_continue(source)
+	assert_true(match == nil, path .. " still contains legacy-incompatible continue control flow: " .. tostring(match))
+end
+
+local function assert_loadfile_ok(path)
+	local chunk, err = loadfile(path)
+	assert_true(chunk ~= nil, "loadfile failed for " .. path .. ": " .. tostring(err))
+end
+
+local function normalize_execute_result(ok, why, code)
+	if type(ok) == "number" then
+		return ok == 0, ok
+	end
+	if type(ok) == "boolean" then
+		if ok then
+			return true, code or 0
+		end
+		return false, code or 1
+	end
+	return false, code or 1
+end
+
+local function command_succeeds(command)
+	local ok, why, code = os.execute(command)
+	return normalize_execute_result(ok, why, code)
+end
+
+local function command_exists(command)
+	local shell = package.config:sub(1, 1) == "\\" and "where " or "command -v "
+	local redirect = package.config:sub(1, 1) == "\\" and " >NUL 2>NUL" or " >/dev/null 2>&1"
+	local escaped = command
+	local success = command_succeeds(shell .. escaped .. redirect)
+	return success
+end
+
+local function find_legacy_parser()
+	for _, command in ipairs(LEGACY_PARSER_CANDIDATES) do
+		if command_exists(command) then
+			return command
+		end
+	end
+	return nil
+end
+
+local function shell_redirect()
+	if package.config:sub(1, 1) == "\\" then
+		return " >NUL 2>NUL"
+	end
+	return " >/dev/null 2>&1"
+end
+
+local function assert_parser_accepts_file(parser, path)
+	local command = string.format("%s -e %q%s", parser, "assert(loadfile(" .. string.format("%q", path) .. "))", shell_redirect())
+	local success = command_succeeds(command)
+	assert_true(success, parser .. " failed to parse " .. path)
+end
+
+local function assert_parser_rejects_legacy_fixture(parser)
+	local legacy_fixture = [[
+local tokens = {}
+for _, token in ipairs(tokens or {}) do
+	if type(token) ~= "table" then
+		goto continue
+	end
+	::continue::
+end
+]]
+	local command = string.format("%s -e %q%s", parser, legacy_fixture, shell_redirect())
+	local success = command_succeeds(command)
+	assert_true(not success, parser .. " unexpectedly accepted legacy goto/label continue fixture")
+end
+
+do
+	local legacy_fixture = [[
+for _, token in ipairs(tokens or {}) do
+	if type(token) ~= "table" then
+		goto continue
+	end
+	::continue::
+end
+]]
+	local match = find_legacy_incompatible_continue(legacy_fixture)
+	assert_true(match ~= nil, "legacy fixture should trigger incompatible continue detector")
+end
+
+for _, path in ipairs(MODULE_PATHS) do
+	assert_no_legacy_incompatible_continue(path)
+	assert_loadfile_ok(path)
+end
+
+local parser = find_legacy_parser()
+if parser then
+	assert_parser_rejects_legacy_fixture(parser)
+	for _, path in ipairs(MODULE_PATHS) do
+		assert_parser_accepts_file(parser, path)
+	end
+	print("plugin lua compatibility regression tests: OK (" .. parser .. ")")
+else
+	print("plugin lua compatibility regression tests: OK (legacy parser unavailable; structural checks only)")
+end

scripts/test-plugin-start-gate.lua

@@ -151,6 +151,14 @@ local function run_plugin_scenario(config)
 				fn = fn,
 			}
 		end
+		function mp.add_forced_key_binding(keys, name, fn)
+			recorded.key_bindings[#recorded.key_bindings + 1] = {
+				keys = keys,
+				name = name,
+				fn = fn,
+				forced = true,
+			}
+		end
 		function mp.register_event(name, fn)
 			if recorded.events[name] == nil then
 				recorded.events[name] = {}
@@ -491,10 +499,10 @@ local function count_property_set(property_sets, name, value)
 	return count
 end
 
-local function fire_event(recorded, name)
+local function fire_event(recorded, name, ...)
 	local listeners = recorded.events[name] or {}
 	for _, listener in ipairs(listeners) do
-		listener()
+		listener(...)
 	end
 end
 
@@ -537,6 +545,39 @@ do
 	)
 end
 
+do
+	local recorded, err = run_plugin_scenario({
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "no",
+		},
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for primary subtitle bar binding scenario: " .. tostring(err))
+	local binding = nil
+	for _, candidate in ipairs(recorded.key_bindings) do
+		if candidate.name == "subminer-toggle-primary-subtitle-bar" then
+			binding = candidate
+			break
+		end
+	end
+	assert_true(binding ~= nil, "primary subtitle bar v binding should be registered")
+	assert_true(binding.keys == "v", "primary subtitle bar binding should use bare v")
+	assert_true(binding.forced == true, "primary subtitle bar binding should override mpv's built-in v binding")
+	binding.fn()
+	assert_true(
+		count_control_calls(recorded.async_calls, "--toggle-primary-subtitle-bar") == 1,
+		"primary subtitle bar binding should issue primary subtitle toggle command"
+	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--toggle-visible-overlay") == 0,
+		"primary subtitle bar binding should not toggle the whole visible overlay"
+	)
+end
+
 do
 	local recorded, err = run_plugin_scenario({
 		process_list = "",
@@ -727,6 +768,11 @@ do
 	fire_event(recorded, "file-loaded")
 	local start_call = find_start_call(recorded.async_calls)
 	assert_true(start_call ~= nil, "auto-start should issue --start command")
+	assert_true(call_has_arg(start_call, "--background"), "auto-start should launch SubMiner in background mode")
+	assert_true(
+		call_has_arg(start_call, "--managed-playback"),
+		"auto-start should mark SubMiner as launcher-managed playback"
+	)
 	assert_true(call_has_arg(start_call, "--texthooker"), "auto-start should include --texthooker on the main --start command when enabled")
 	assert_true(find_control_call(recorded.async_calls, "--texthooker") == nil, "auto-start should not issue a separate texthooker helper command")
 	assert_true(
@@ -1013,11 +1059,20 @@ do
 	})
 	assert_true(recorded ~= nil, "plugin failed to load for shutdown-preserve-background scenario: " .. tostring(err))
 	fire_event(recorded, "file-loaded")
+	fire_event(recorded, "end-file", { reason = "quit" })
+	assert_true(
+		find_control_call(recorded.async_calls, "--hide-visible-overlay") == nil,
+		"mpv quit end-file should not spawn hide-visible-overlay helper commands"
+	)
 	fire_event(recorded, "shutdown")
 	assert_true(
 		find_control_call(recorded.async_calls, "--stop") == nil,
 		"mpv shutdown should not stop the background SubMiner process"
 	)
+	assert_true(
+		find_control_call(recorded.async_calls, "--hide-visible-overlay") == nil,
+		"mpv shutdown should not spawn hide-visible-overlay helper commands"
+	)
 end
 
 do

scripts/update-aur-package.sh

@@ -13,6 +13,26 @@ appimage=
 wrapper=
 assets=
 
+normalize_path() {
+  local value="$1"
+  if command -v cygpath >/dev/null 2>&1; then
+    case "$value" in
+      [A-Za-z]:\\* | [A-Za-z]:/*)
+        cygpath -u "$value"
+        return 0
+        ;;
+    esac
+  fi
+  if [[ "$value" =~ ^([A-Za-z]):[\\/](.*)$ ]]; then
+    local drive="${BASH_REMATCH[1],,}"
+    local rest="${BASH_REMATCH[2]}"
+    rest="${rest//\\//}"
+    printf '/mnt/%s/%s\n' "$drive" "$rest"
+    return 0
+  fi
+  printf '%s\n' "$value"
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --pkg-dir)
@@ -53,6 +73,10 @@ if [[ -z "$pkg_dir" || -z "$version" || -z "$appimage" || -z "$wrapper" || -z "$
 fi
 
 version="${version#v}"
+pkg_dir="$(normalize_path "$pkg_dir")"
+appimage="$(normalize_path "$appimage")"
+wrapper="$(normalize_path "$wrapper")"
+assets="$(normalize_path "$assets")"
 pkgbuild="${pkg_dir}/PKGBUILD"
 srcinfo="${pkg_dir}/.SRCINFO"
 
@@ -82,6 +106,9 @@ awk \
     found_pkgver = 0
     found_sha_block = 0
   }
+  {
+    sub(/\r$/, "")
+  }
   /^pkgver=/ {
     print "pkgver=" version
     found_pkgver = 1
@@ -140,6 +167,9 @@ awk \
     found_source_wrapper = 0
     found_source_assets = 0
   }
+  {
+    sub(/\r$/, "")
+  }
   /^\tpkgver = / {
     print "\tpkgver = " version
     found_pkgver = 1

scripts/update-aur-package.test.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -9,6 +10,23 @@ function createWorkspace(name: string): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), `${name}-`));
 }
 
+function toBashPath(filePath: string): string {
+  if (process.platform !== 'win32') return filePath;
+
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
+  if (!match) return normalized;
+
+  const drive = match[1]!;
+  const rest = match[2]!;
+  const probe = spawnSync('bash', ['-c', 'uname -s'], { encoding: 'utf8' });
+  if (probe.status === 0 && /linux/i.test(probe.stdout)) {
+    return `/mnt/${drive.toLowerCase()}/${rest}`;
+  }
+
+  return `${drive.toUpperCase()}:/${rest}`;
+}
+
 test('update-aur-package updates PKGBUILD and .SRCINFO without makepkg', () => {
   const workspace = createWorkspace('subminer-aur-package');
   const pkgDir = path.join(workspace, 'aur-subminer-bin');
@@ -29,15 +47,15 @@ test('update-aur-package updates PKGBUILD and .SRCINFO without makepkg', () => {
       [
         'scripts/update-aur-package.sh',
         '--pkg-dir',
-        pkgDir,
+        toBashPath(pkgDir),
         '--version',
         'v0.6.3',
         '--appimage',
-        appImagePath,
+        toBashPath(appImagePath),
         '--wrapper',
-        wrapperPath,
+        toBashPath(wrapperPath),
         '--assets',
-        assetsPath,
+        toBashPath(assetsPath),
       ],
       {
         cwd: process.cwd(),
@@ -47,8 +65,8 @@ test('update-aur-package updates PKGBUILD and .SRCINFO without makepkg', () => {
 
     const pkgbuild = fs.readFileSync(path.join(pkgDir, 'PKGBUILD'), 'utf8');
     const srcinfo = fs.readFileSync(path.join(pkgDir, '.SRCINFO'), 'utf8');
-    const expectedSums = [appImagePath, wrapperPath, assetsPath].map(
-      (filePath) => execFileSync('sha256sum', [filePath], { encoding: 'utf8' }).split(/\s+/)[0],
+    const expectedSums = [appImagePath, wrapperPath, assetsPath].map((filePath) =>
+      crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex'),
     );
 
     assert.match(pkgbuild, /^pkgver=0\.6\.3$/m);

src/anki-integration/card-creation-manual-update.test.ts

@@ -0,0 +1,143 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { CardCreationService } from './card-creation';
+import type { AnkiConnectConfig } from '../types/anki';
+
+type CardCreationDeps = ConstructorParameters<typeof CardCreationService>[0];
+
+function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
+  service: CardCreationService;
+  updatedFields: Record<string, string>[];
+  mergeCalls: Array<{ existing: string; newValue: string; overwrite: boolean }>;
+  storedMedia: string[];
+} {
+  const updatedFields: Record<string, string>[] = [];
+  const mergeCalls: Array<{ existing: string; newValue: string; overwrite: boolean }> = [];
+  const storedMedia: string[] = [];
+
+  const deps: CardCreationDeps = {
+    getConfig: () =>
+      ({
+        deck: 'Mining',
+        fields: {
+          word: 'Expression',
+          sentence: 'Sentence',
+          audio: 'ExpressionAudio',
+        },
+        media: {
+          generateAudio: true,
+          generateImage: false,
+          maxMediaDuration: 30,
+        },
+        behavior: {
+          overwriteAudio: false,
+          overwriteImage: false,
+        },
+        ai: false,
+      }) as AnkiConnectConfig,
+    getAiConfig: () => ({}),
+    getTimingTracker: () =>
+      ({
+        findTiming: (text: string) => (text === '字幕' ? { startTime: 12, endTime: 14 } : null),
+      }) as never,
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentAudioStreamIndex: 0,
+      }) as never,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: {
+            Expression: { value: '単語' },
+            Sentence: { value: '' },
+            ExpressionAudio: { value: '[sound:auto-expression.mp3]' },
+            SentenceAudio: { value: '[sound:auto-sentence.mp3]' },
+          },
+        },
+      ],
+      updateNoteFields: async (_noteId, fields) => {
+        updatedFields.push(fields);
+      },
+      storeMediaFile: async (filename) => {
+        storedMedia.push(filename);
+      },
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+    },
+    mediaGenerator: {
+      generateAudio: async () => Buffer.from('audio'),
+      generateScreenshot: async () => null,
+      generateAnimatedImage: async () => null,
+    },
+    showOsdNotification: () => undefined,
+    showUpdateResult: () => undefined,
+    showStatusNotification: () => undefined,
+    showNotification: async () => undefined,
+    beginUpdateProgress: () => undefined,
+    endUpdateProgress: () => undefined,
+    withUpdateProgress: async (_message, action) => action(),
+    resolveConfiguredFieldName: (noteInfo, ...preferredNames) => {
+      for (const preferredName of preferredNames) {
+        if (preferredName && preferredName in noteInfo.fields) return preferredName;
+      }
+      return null;
+    },
+    resolveNoteFieldName: (noteInfo, preferredName) =>
+      preferredName && preferredName in noteInfo.fields ? preferredName : null,
+    getAnimatedImageLeadInSeconds: async () => 0,
+    extractFields: (fields) =>
+      Object.fromEntries(
+        Object.entries(fields).map(([name, field]) => [name.toLowerCase(), field.value]),
+      ),
+    processSentence: (sentence) => sentence,
+    setCardTypeFields: () => undefined,
+    mergeFieldValue: (existing, newValue, overwrite) => {
+      mergeCalls.push({ existing, newValue, overwrite });
+      return overwrite || !existing.trim() ? newValue : existing;
+    },
+    formatMiscInfoPattern: () => '',
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: false,
+      kikuEnabled: false,
+      kikuFieldGrouping: 'disabled',
+      kikuDeleteDuplicateInAuto: false,
+    }),
+    getFallbackDurationSeconds: () => 10,
+    appendKnownWordsFromNoteInfo: () => undefined,
+    isUpdateInProgress: () => false,
+    setUpdateInProgress: () => undefined,
+    trackLastAddedNoteId: () => undefined,
+    ...overrides,
+  };
+
+  return {
+    service: new CardCreationService(deps),
+    updatedFields,
+    mergeCalls,
+    storedMedia,
+  };
+}
+
+test('manual clipboard subtitle update replaces expression and sentence audio even when overwriteAudio is disabled', async () => {
+  const { service, updatedFields, mergeCalls, storedMedia } = createManualUpdateService();
+
+  await service.updateLastAddedFromClipboard('字幕');
+
+  assert.equal(updatedFields.length, 1);
+  assert.equal(storedMedia.length, 1);
+  const audioValue = `[sound:${storedMedia[0]}]`;
+  assert.equal(updatedFields[0]?.ExpressionAudio, audioValue);
+  assert.equal(updatedFields[0]?.SentenceAudio, audioValue);
+  assert.deepEqual(
+    mergeCalls.map((call) => call.overwrite),
+    [true, true],
+  );
+});

src/anki-integration/card-creation.ts

@@ -219,6 +219,10 @@ export class CardCreationService {
           this.deps.getConfig(),
         );
         const sentenceAudioField = this.getResolvedSentenceAudioFieldName(noteInfo);
+        const expressionAudioField = this.deps.resolveConfiguredFieldName(
+          noteInfo,
+          this.deps.getConfig().fields?.audio || 'ExpressionAudio',
+        );
         const sentenceField = this.deps.getEffectiveSentenceCardConfig().sentenceField;
 
         const sentence = blocks.join(' ');
@@ -248,13 +252,22 @@ export class CardCreationService {
 
             if (audioBuffer) {
               await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
-              if (sentenceAudioField) {
-                const existingAudio = noteInfo.fields[sentenceAudioField]?.value || '';
-                updatedFields[sentenceAudioField] = this.deps.mergeFieldValue(
-                  existingAudio,
-                  `[sound:${audioFilename}]`,
-                  this.deps.getConfig().behavior?.overwriteAudio !== false,
+              if (sentenceAudioField || expressionAudioField) {
+                const audioValue = `[sound:${audioFilename}]`;
+                const audioFields = new Set(
+                  [sentenceAudioField, expressionAudioField].filter(
+                    (fieldName): fieldName is string => Boolean(fieldName),
+                  ),
                 );
+                for (const audioField of audioFields) {
+                  const existingAudio = noteInfo.fields[audioField]?.value || '';
+                  // Manual clipboard updates intentionally replace old captured audio.
+                  updatedFields[audioField] = this.deps.mergeFieldValue(
+                    existingAudio,
+                    audioValue,
+                    true,
+                  );
+                }
               }
               miscInfoFilename = audioFilename;
               updatePerformed = true;

src/cli/args.test.ts

@@ -73,6 +73,48 @@ test('parseArgs captures youtube startup forwarding flags', () => {
   assert.equal(shouldStartApp(args), true);
 });
 
+test('parseArgs captures session action forwarding flags', () => {
+  const args = parseArgs([
+    '--toggle-stats-overlay',
+    '--open-jimaku',
+    '--open-youtube-picker',
+    '--open-playlist-browser',
+    '--toggle-primary-subtitle-bar',
+    '--replay-current-subtitle',
+    '--play-next-subtitle',
+    '--shift-sub-delay-prev-line',
+    '--shift-sub-delay-next-line',
+    '--cycle-runtime-option',
+    'anki.autoUpdateNewCards:prev',
+    '--copy-subtitle-count',
+    '3',
+    '--mine-sentence-count=2',
+  ]);
+
+  assert.equal(args.toggleStatsOverlay, true);
+  assert.equal(args.openJimaku, true);
+  assert.equal(args.openYoutubePicker, true);
+  assert.equal(args.openPlaylistBrowser, true);
+  assert.equal(args.togglePrimarySubtitleBar, true);
+  assert.equal(args.replayCurrentSubtitle, true);
+  assert.equal(args.playNextSubtitle, true);
+  assert.equal(args.shiftSubDelayPrevLine, true);
+  assert.equal(args.shiftSubDelayNextLine, true);
+  assert.equal(args.cycleRuntimeOptionId, 'anki.autoUpdateNewCards');
+  assert.equal(args.cycleRuntimeOptionDirection, -1);
+  assert.equal(args.copySubtitleCount, 3);
+  assert.equal(args.mineSentenceCount, 2);
+  assert.equal(hasExplicitCommand(args), true);
+  assert.equal(shouldStartApp(args), true);
+});
+
+test('parseArgs ignores non-positive numeric session action counts', () => {
+  const args = parseArgs(['--copy-subtitle-count=0', '--mine-sentence-count', '-1']);
+
+  assert.equal(args.copySubtitleCount, undefined);
+  assert.equal(args.mineSentenceCount, undefined);
+});
+
 test('youtube playback does not use generic overlay-runtime bootstrap classification', () => {
   const args = parseArgs(['--youtube-play', 'https://youtube.com/watch?v=abc']);
 
@@ -172,6 +214,37 @@ test('hasExplicitCommand and shouldStartApp preserve command intent', () => {
   assert.equal(hasExplicitCommand(anilistRetryQueue), true);
   assert.equal(shouldStartApp(anilistRetryQueue), false);
 
+  const dictionaryCandidates = parseArgs([
+    '--dictionary-candidates',
+    '--dictionary-target',
+    '/tmp/a.mkv',
+  ]);
+  assert.equal(dictionaryCandidates.dictionaryCandidates, true);
+  assert.equal(dictionaryCandidates.dictionaryTarget, '/tmp/a.mkv');
+  assert.equal(hasExplicitCommand(dictionaryCandidates), true);
+  assert.equal(shouldStartApp(dictionaryCandidates), true);
+
+  const dictionarySelect = parseArgs(['--dictionary-select', '--dictionary-anilist-id', '21355']);
+  assert.equal(dictionarySelect.dictionarySelect, true);
+  assert.equal(dictionarySelect.dictionaryAnilistId, 21355);
+  assert.equal(hasExplicitCommand(dictionarySelect), true);
+  assert.equal(shouldStartApp(dictionarySelect), true);
+
+  const toggleStatsOverlay = parseArgs(['--toggle-stats-overlay']);
+  assert.equal(toggleStatsOverlay.toggleStatsOverlay, true);
+  assert.equal(hasExplicitCommand(toggleStatsOverlay), true);
+  assert.equal(shouldStartApp(toggleStatsOverlay), true);
+
+  const cycleRuntimeOption = parseArgs(['--cycle-runtime-option', 'anki.autoUpdateNewCards:next']);
+  assert.equal(cycleRuntimeOption.cycleRuntimeOptionId, 'anki.autoUpdateNewCards');
+  assert.equal(cycleRuntimeOption.cycleRuntimeOptionDirection, 1);
+  assert.equal(hasExplicitCommand(cycleRuntimeOption), true);
+  assert.equal(shouldStartApp(cycleRuntimeOption), true);
+  assert.equal(commandNeedsOverlayRuntime(cycleRuntimeOption), true);
+
+  const toggleStatsOverlayRuntime = parseArgs(['--toggle-stats-overlay']);
+  assert.equal(commandNeedsOverlayRuntime(toggleStatsOverlayRuntime), true);
+
   const dictionary = parseArgs(['--dictionary']);
   assert.equal(dictionary.dictionary, true);
   assert.equal(hasExplicitCommand(dictionary), true);
@@ -265,6 +338,12 @@ test('hasExplicitCommand and shouldStartApp preserve command intent', () => {
   assert.equal(hasExplicitCommand(background), true);
   assert.equal(shouldStartApp(background), true);
 
+  const managedPlayback = parseArgs(['--background', '--managed-playback']);
+  assert.equal(managedPlayback.background, true);
+  assert.equal(managedPlayback.managedPlayback, true);
+  assert.equal(hasExplicitCommand(managedPlayback), true);
+  assert.equal(shouldStartApp(managedPlayback), true);
+
   const setup = parseArgs(['--setup']);
   assert.equal((setup as typeof setup & { setup?: boolean }).setup, true);
   assert.equal(hasExplicitCommand(setup), true);

src/cli/args.ts

@@ -1,5 +1,6 @@
 export interface CliArgs {
   background: boolean;
+  managedPlayback: boolean;
   start: boolean;
   launchMpv: boolean;
   launchMpvTargets: string[];
@@ -8,6 +9,7 @@ export interface CliArgs {
   stop: boolean;
   toggle: boolean;
   toggleVisibleOverlay: boolean;
+  togglePrimarySubtitleBar: boolean;
   settings: boolean;
   setup: boolean;
   show: boolean;
@@ -24,12 +26,32 @@ export interface CliArgs {
   triggerFieldGrouping: boolean;
   triggerSubsync: boolean;
   markAudioCard: boolean;
+  toggleStatsOverlay: boolean;
+  toggleSubtitleSidebar: boolean;
   openRuntimeOptions: boolean;
+  openSessionHelp: boolean;
+  openCharacterDictionary: boolean;
+  openControllerSelect: boolean;
+  openControllerDebug: boolean;
+  openJimaku: boolean;
+  openYoutubePicker: boolean;
+  openPlaylistBrowser: boolean;
+  replayCurrentSubtitle: boolean;
+  playNextSubtitle: boolean;
+  shiftSubDelayPrevLine: boolean;
+  shiftSubDelayNextLine: boolean;
+  cycleRuntimeOptionId?: string;
+  cycleRuntimeOptionDirection?: 1 | -1;
+  copySubtitleCount?: number;
+  mineSentenceCount?: number;
   anilistStatus: boolean;
   anilistLogout: boolean;
   anilistSetup: boolean;
   anilistRetryQueue: boolean;
   dictionary: boolean;
+  dictionaryCandidates: boolean;
+  dictionarySelect: boolean;
+  dictionaryAnilistId?: number;
   dictionaryTarget?: string;
   stats: boolean;
   statsBackground?: boolean;
@@ -78,6 +100,7 @@ export type CliCommandSource = 'initial' | 'second-instance';
 export function parseArgs(argv: string[]): CliArgs {
   const args: CliArgs = {
     background: false,
+    managedPlayback: false,
     start: false,
     launchMpv: false,
     launchMpvTargets: [],
@@ -86,6 +109,7 @@ export function parseArgs(argv: string[]): CliArgs {
     stop: false,
     toggle: false,
     toggleVisibleOverlay: false,
+    togglePrimarySubtitleBar: false,
     settings: false,
     setup: false,
     show: false,
@@ -102,12 +126,27 @@ export function parseArgs(argv: string[]): CliArgs {
     triggerFieldGrouping: false,
     triggerSubsync: false,
     markAudioCard: false,
+    toggleStatsOverlay: false,
+    toggleSubtitleSidebar: false,
     openRuntimeOptions: false,
+    openSessionHelp: false,
+    openCharacterDictionary: false,
+    openControllerSelect: false,
+    openControllerDebug: false,
+    openJimaku: false,
+    openYoutubePicker: false,
+    openPlaylistBrowser: false,
+    replayCurrentSubtitle: false,
+    playNextSubtitle: false,
+    shiftSubDelayPrevLine: false,
+    shiftSubDelayNextLine: false,
     anilistStatus: false,
     anilistLogout: false,
     anilistSetup: false,
     anilistRetryQueue: false,
     dictionary: false,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
     stats: false,
     statsBackground: false,
     statsStop: false,
@@ -138,11 +177,33 @@ export function parseArgs(argv: string[]): CliArgs {
     return value;
   };
 
+  const parseCycleRuntimeOption = (
+    value: string | undefined,
+  ): { id: string; direction: 1 | -1 } | null => {
+    if (!value) return null;
+    const separatorIndex = value.lastIndexOf(':');
+    if (separatorIndex <= 0 || separatorIndex === value.length - 1) return null;
+    const id = value.slice(0, separatorIndex).trim();
+    const rawDirection = value
+      .slice(separatorIndex + 1)
+      .trim()
+      .toLowerCase();
+    if (!id) return null;
+    if (rawDirection === 'next' || rawDirection === '1') {
+      return { id, direction: 1 };
+    }
+    if (rawDirection === 'prev' || rawDirection === '-1') {
+      return { id, direction: -1 };
+    }
+    return null;
+  };
+
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (!arg || !arg.startsWith('--')) continue;
 
     if (arg === '--background') args.background = true;
+    else if (arg === '--managed-playback') args.managedPlayback = true;
     else if (arg === '--start') args.start = true;
     else if (arg.startsWith('--youtube-play=')) {
       const value = arg.split('=', 2)[1];
@@ -163,6 +224,7 @@ export function parseArgs(argv: string[]): CliArgs {
     } else if (arg === '--stop') args.stop = true;
     else if (arg === '--toggle') args.toggle = true;
     else if (arg === '--toggle-visible-overlay') args.toggleVisibleOverlay = true;
+    else if (arg === '--toggle-primary-subtitle-bar') args.togglePrimarySubtitleBar = true;
     else if (arg === '--settings' || arg === '--yomitan') args.settings = true;
     else if (arg === '--setup') args.setup = true;
     else if (arg === '--show') args.show = true;
@@ -179,13 +241,58 @@ export function parseArgs(argv: string[]): CliArgs {
     else if (arg === '--trigger-field-grouping') args.triggerFieldGrouping = true;
     else if (arg === '--trigger-subsync') args.triggerSubsync = true;
     else if (arg === '--mark-audio-card') args.markAudioCard = true;
+    else if (arg === '--toggle-stats-overlay') args.toggleStatsOverlay = true;
+    else if (arg === '--toggle-subtitle-sidebar') args.toggleSubtitleSidebar = true;
     else if (arg === '--open-runtime-options') args.openRuntimeOptions = true;
-    else if (arg === '--anilist-status') args.anilistStatus = true;
+    else if (arg === '--open-session-help') args.openSessionHelp = true;
+    else if (arg === '--open-character-dictionary') args.openCharacterDictionary = true;
+    else if (arg === '--open-controller-select') args.openControllerSelect = true;
+    else if (arg === '--open-controller-debug') args.openControllerDebug = true;
+    else if (arg === '--open-jimaku') args.openJimaku = true;
+    else if (arg === '--open-youtube-picker') args.openYoutubePicker = true;
+    else if (arg === '--open-playlist-browser') args.openPlaylistBrowser = true;
+    else if (arg === '--replay-current-subtitle') args.replayCurrentSubtitle = true;
+    else if (arg === '--play-next-subtitle') args.playNextSubtitle = true;
+    else if (arg === '--shift-sub-delay-prev-line') args.shiftSubDelayPrevLine = true;
+    else if (arg === '--shift-sub-delay-next-line') args.shiftSubDelayNextLine = true;
+    else if (arg.startsWith('--cycle-runtime-option=')) {
+      const parsed = parseCycleRuntimeOption(arg.split('=', 2)[1]);
+      if (parsed) {
+        args.cycleRuntimeOptionId = parsed.id;
+        args.cycleRuntimeOptionDirection = parsed.direction;
+      }
+    } else if (arg === '--cycle-runtime-option') {
+      const parsed = parseCycleRuntimeOption(readValue(argv[i + 1]));
+      if (parsed) {
+        args.cycleRuntimeOptionId = parsed.id;
+        args.cycleRuntimeOptionDirection = parsed.direction;
+      }
+    } else if (arg.startsWith('--copy-subtitle-count=')) {
+      const value = Number(arg.split('=', 2)[1]);
+      if (Number.isInteger(value) && value > 0) args.copySubtitleCount = value;
+    } else if (arg === '--copy-subtitle-count') {
+      const value = Number(readValue(argv[i + 1]));
+      if (Number.isInteger(value) && value > 0) args.copySubtitleCount = value;
+    } else if (arg.startsWith('--mine-sentence-count=')) {
+      const value = Number(arg.split('=', 2)[1]);
+      if (Number.isInteger(value) && value > 0) args.mineSentenceCount = value;
+    } else if (arg === '--mine-sentence-count') {
+      const value = Number(readValue(argv[i + 1]));
+      if (Number.isInteger(value) && value > 0) args.mineSentenceCount = value;
+    } else if (arg === '--anilist-status') args.anilistStatus = true;
     else if (arg === '--anilist-logout') args.anilistLogout = true;
     else if (arg === '--anilist-setup') args.anilistSetup = true;
     else if (arg === '--anilist-retry-queue') args.anilistRetryQueue = true;
     else if (arg === '--dictionary') args.dictionary = true;
-    else if (arg.startsWith('--dictionary-target=')) {
+    else if (arg === '--dictionary-candidates') args.dictionaryCandidates = true;
+    else if (arg === '--dictionary-select') args.dictionarySelect = true;
+    else if (arg.startsWith('--dictionary-anilist-id=')) {
+      const value = Number(arg.split('=', 2)[1]);
+      if (Number.isInteger(value) && value > 0) args.dictionaryAnilistId = value;
+    } else if (arg === '--dictionary-anilist-id') {
+      const value = Number(readValue(argv[i + 1]));
+      if (Number.isInteger(value) && value > 0) args.dictionaryAnilistId = value;
+    } else if (arg.startsWith('--dictionary-target=')) {
       const value = arg.split('=', 2)[1];
       if (value) args.dictionaryTarget = value;
     } else if (arg === '--dictionary-target') {
@@ -355,6 +462,7 @@ export function hasExplicitCommand(args: CliArgs): boolean {
     args.stop ||
     args.toggle ||
     args.toggleVisibleOverlay ||
+    args.togglePrimarySubtitleBar ||
     args.settings ||
     args.setup ||
     args.show ||
@@ -371,12 +479,30 @@ export function hasExplicitCommand(args: CliArgs): boolean {
     args.triggerFieldGrouping ||
     args.triggerSubsync ||
     args.markAudioCard ||
+    args.toggleStatsOverlay ||
+    args.toggleSubtitleSidebar ||
     args.openRuntimeOptions ||
+    args.openSessionHelp ||
+    args.openCharacterDictionary ||
+    args.openControllerSelect ||
+    args.openControllerDebug ||
+    args.openJimaku ||
+    args.openYoutubePicker ||
+    args.openPlaylistBrowser ||
+    args.replayCurrentSubtitle ||
+    args.playNextSubtitle ||
+    args.shiftSubDelayPrevLine ||
+    args.shiftSubDelayNextLine ||
+    args.cycleRuntimeOptionId !== undefined ||
+    args.copySubtitleCount !== undefined ||
+    args.mineSentenceCount !== undefined ||
     args.anilistStatus ||
     args.anilistLogout ||
     args.anilistSetup ||
     args.anilistRetryQueue ||
     args.dictionary ||
+    args.dictionaryCandidates ||
+    args.dictionarySelect ||
     args.stats ||
     args.jellyfin ||
     args.jellyfinLogin ||
@@ -407,6 +533,7 @@ export function isStandaloneTexthookerCommand(args: CliArgs): boolean {
     !args.stop &&
     !args.toggle &&
     !args.toggleVisibleOverlay &&
+    !args.togglePrimarySubtitleBar &&
     !args.settings &&
     !args.setup &&
     !args.show &&
@@ -423,12 +550,30 @@ export function isStandaloneTexthookerCommand(args: CliArgs): boolean {
     !args.triggerFieldGrouping &&
     !args.triggerSubsync &&
     !args.markAudioCard &&
+    !args.toggleStatsOverlay &&
+    !args.toggleSubtitleSidebar &&
     !args.openRuntimeOptions &&
+    !args.openSessionHelp &&
+    !args.openCharacterDictionary &&
+    !args.openControllerSelect &&
+    !args.openControllerDebug &&
+    !args.openJimaku &&
+    !args.openYoutubePicker &&
+    !args.openPlaylistBrowser &&
+    !args.replayCurrentSubtitle &&
+    !args.playNextSubtitle &&
+    !args.shiftSubDelayPrevLine &&
+    !args.shiftSubDelayNextLine &&
+    args.cycleRuntimeOptionId === undefined &&
+    args.copySubtitleCount === undefined &&
+    args.mineSentenceCount === undefined &&
     !args.anilistStatus &&
     !args.anilistLogout &&
     !args.anilistSetup &&
     !args.anilistRetryQueue &&
     !args.dictionary &&
+    !args.dictionaryCandidates &&
+    !args.dictionarySelect &&
     !args.stats &&
     !args.jellyfin &&
     !args.jellyfinLogin &&
@@ -454,6 +599,7 @@ export function shouldStartApp(args: CliArgs): boolean {
     args.launchMpv ||
     args.toggle ||
     args.toggleVisibleOverlay ||
+    args.togglePrimarySubtitleBar ||
     args.settings ||
     args.setup ||
     args.copySubtitle ||
@@ -466,8 +612,26 @@ export function shouldStartApp(args: CliArgs): boolean {
     args.triggerFieldGrouping ||
     args.triggerSubsync ||
     args.markAudioCard ||
+    args.toggleStatsOverlay ||
+    args.toggleSubtitleSidebar ||
     args.openRuntimeOptions ||
+    args.openSessionHelp ||
+    args.openCharacterDictionary ||
+    args.openControllerSelect ||
+    args.openControllerDebug ||
+    args.openJimaku ||
+    args.openYoutubePicker ||
+    args.openPlaylistBrowser ||
+    args.replayCurrentSubtitle ||
+    args.playNextSubtitle ||
+    args.shiftSubDelayPrevLine ||
+    args.shiftSubDelayNextLine ||
+    args.cycleRuntimeOptionId !== undefined ||
+    args.copySubtitleCount !== undefined ||
+    args.mineSentenceCount !== undefined ||
     args.dictionary ||
+    args.dictionaryCandidates ||
+    args.dictionarySelect ||
     args.stats ||
     args.jellyfin ||
     args.jellyfinPlay ||
@@ -489,6 +653,7 @@ export function shouldRunSettingsOnlyStartup(args: CliArgs): boolean {
     !args.stop &&
     !args.toggle &&
     !args.toggleVisibleOverlay &&
+    !args.togglePrimarySubtitleBar &&
     !args.show &&
     !args.hide &&
     !args.setup &&
@@ -504,12 +669,30 @@ export function shouldRunSettingsOnlyStartup(args: CliArgs): boolean {
     !args.triggerFieldGrouping &&
     !args.triggerSubsync &&
     !args.markAudioCard &&
+    !args.toggleStatsOverlay &&
+    !args.toggleSubtitleSidebar &&
     !args.openRuntimeOptions &&
+    !args.openSessionHelp &&
+    !args.openCharacterDictionary &&
+    !args.openControllerSelect &&
+    !args.openControllerDebug &&
+    !args.openJimaku &&
+    !args.openYoutubePicker &&
+    !args.openPlaylistBrowser &&
+    !args.replayCurrentSubtitle &&
+    !args.playNextSubtitle &&
+    !args.shiftSubDelayPrevLine &&
+    !args.shiftSubDelayNextLine &&
+    args.cycleRuntimeOptionId === undefined &&
+    args.copySubtitleCount === undefined &&
+    args.mineSentenceCount === undefined &&
     !args.anilistStatus &&
     !args.anilistLogout &&
     !args.anilistSetup &&
     !args.anilistRetryQueue &&
     !args.dictionary &&
+    !args.dictionaryCandidates &&
+    !args.dictionarySelect &&
     !args.stats &&
     !args.jellyfin &&
     !args.jellyfinLogin &&
@@ -534,6 +717,7 @@ export function commandNeedsOverlayRuntime(args: CliArgs): boolean {
   return (
     args.toggle ||
     args.toggleVisibleOverlay ||
+    args.togglePrimarySubtitleBar ||
     args.show ||
     args.hide ||
     args.showVisibleOverlay ||
@@ -544,10 +728,26 @@ export function commandNeedsOverlayRuntime(args: CliArgs): boolean {
     args.mineSentenceMultiple ||
     args.updateLastCardFromClipboard ||
     args.toggleSecondarySub ||
+    args.toggleStatsOverlay ||
+    args.toggleSubtitleSidebar ||
     args.triggerFieldGrouping ||
     args.triggerSubsync ||
     args.markAudioCard ||
-    args.openRuntimeOptions
+    args.openRuntimeOptions ||
+    args.openSessionHelp ||
+    args.openCharacterDictionary ||
+    args.openControllerSelect ||
+    args.openControllerDebug ||
+    args.openJimaku ||
+    args.openYoutubePicker ||
+    args.openPlaylistBrowser ||
+    args.replayCurrentSubtitle ||
+    args.playNextSubtitle ||
+    args.shiftSubDelayPrevLine ||
+    args.shiftSubDelayNextLine ||
+    args.cycleRuntimeOptionId !== undefined ||
+    args.copySubtitleCount !== undefined ||
+    args.mineSentenceCount !== undefined
   );
 }
 

src/cli/help.ts

@@ -19,6 +19,7 @@ ${B}Session${R}
 
 ${B}Overlay${R}
   --toggle-visible-overlay       Toggle subtitle overlay
+  --toggle-primary-subtitle-bar  Toggle primary subtitle bar
   --show-visible-overlay         Show subtitle overlay
   --hide-visible-overlay         Hide subtitle overlay
   --settings                     Open Yomitan settings window
@@ -35,7 +36,12 @@ ${B}Mining${R}
   --trigger-field-grouping       Run Kiku field grouping
   --trigger-subsync              Run subtitle sync
   --toggle-secondary-sub         Cycle secondary subtitle mode
+  --toggle-subtitle-sidebar      Toggle subtitle sidebar panel
   --open-runtime-options         Open runtime options palette
+  --open-session-help            Open session help modal
+  --open-character-dictionary    Open character dictionary anime selection modal
+  --open-controller-select       Open controller select modal
+  --open-controller-debug        Open controller debug modal
 
 ${B}AniList${R}
   --anilist-setup                Open AniList authentication flow
@@ -43,6 +49,9 @@ ${B}AniList${R}
   --anilist-logout               Clear stored AniList token
   --anilist-retry-queue          Retry next queued update
   --dictionary                   Generate character dictionary ZIP for current anime
+  --dictionary-candidates        Show character dictionary AniList candidates
+  --dictionary-select            Save manual character dictionary AniList selection
+  --dictionary-anilist-id ${D}ID${R}      AniList media ID for --dictionary-select
   --dictionary-target ${D}PATH${R}         Override dictionary source path (file or directory)
 
 ${B}Jellyfin${R}

src/config/config.test.ts

@@ -50,6 +50,9 @@ test('loads defaults when config is missing', () => {
   assert.equal(config.startupWarmups.yomitanExtension, true);
   assert.equal(config.startupWarmups.subtitleDictionaries, true);
   assert.equal(config.startupWarmups.jellyfinRemoteSession, true);
+  assert.equal(config.shortcuts.markAudioCard, 'CommandOrControl+Shift+A');
+  assert.equal(config.shortcuts.openCharacterDictionary, 'CommandOrControl+Alt+A');
+  assert.equal(config.shortcuts.toggleSubtitleSidebar, 'Backslash');
   assert.equal(config.discordPresence.enabled, true);
   assert.equal(config.discordPresence.updateIntervalMs, 3_000);
   assert.equal(config.subtitleStyle.backgroundColor, 'rgb(30, 32, 48, 0.88)');
@@ -434,6 +437,46 @@ test('parses subtitleStyle.hoverTokenBackgroundColor and warns on invalid values
   );
 });
 
+test('parses subtitleStyle.hoverBackground as a hoverTokenBackgroundColor alias', () => {
+  const validDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(validDir, 'config.jsonc'),
+    `{
+      "subtitleStyle": {
+        "hoverBackground": "transparent"
+      }
+    }`,
+    'utf-8',
+  );
+
+  const validService = new ConfigService(validDir);
+  assert.equal(validService.getConfig().subtitleStyle.hoverTokenBackgroundColor, 'transparent');
+});
+
+test('parses subtitleStyle.hoverTokenBackgroundColor null as invalid instead of missing', () => {
+  const invalidDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(invalidDir, 'config.jsonc'),
+    `{
+      "subtitleStyle": {
+        "hoverTokenBackgroundColor": null
+      }
+    }`,
+    'utf-8',
+  );
+
+  const invalidService = new ConfigService(invalidDir);
+  assert.equal(
+    invalidService.getConfig().subtitleStyle.hoverTokenBackgroundColor,
+    DEFAULT_CONFIG.subtitleStyle.hoverTokenBackgroundColor,
+  );
+  assert.ok(
+    invalidService
+      .getWarnings()
+      .some((warning) => warning.path === 'subtitleStyle.hoverTokenBackgroundColor'),
+  );
+});
+
 test('parses subtitleStyle.nameMatchEnabled and warns on invalid values', () => {
   const validDir = makeTempDir();
   fs.writeFileSync(

src/config/definitions/defaults-core.ts

@@ -86,8 +86,13 @@ export const CORE_DEFAULT_CONFIG: Pick<
     multiCopyTimeoutMs: 3000,
     toggleSecondarySub: 'CommandOrControl+Shift+V',
     markAudioCard: 'CommandOrControl+Shift+A',
+    openCharacterDictionary: 'CommandOrControl+Alt+A',
     openRuntimeOptions: 'CommandOrControl+Shift+O',
     openJimaku: 'Ctrl+Shift+J',
+    openSessionHelp: 'CommandOrControl+Shift+H',
+    openControllerSelect: 'Alt+C',
+    openControllerDebug: 'Alt+Shift+C',
+    toggleSubtitleSidebar: 'Backslash',
   },
   secondarySub: {
     secondarySubLanguages: [],

src/config/resolve/core-domains.ts

@@ -490,6 +490,7 @@ export function applyCoreDomainConfig(context: ResolveContext): void {
       'mineSentenceMultiple',
       'toggleSecondarySub',
       'markAudioCard',
+      'openCharacterDictionary',
       'openRuntimeOptions',
       'openJimaku',
     ] as const;

src/config/resolve/subtitle-domains.ts

@@ -260,20 +260,23 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
       );
     }
 
-    const hoverTokenBackgroundColor = asString(
-      (src.subtitleStyle as { hoverTokenBackgroundColor?: unknown }).hoverTokenBackgroundColor,
-    );
+    const subtitleStyleSource = src.subtitleStyle as {
+      hoverBackground?: unknown;
+      hoverTokenBackgroundColor?: unknown;
+    };
+    const rawHoverTokenBackgroundColor =
+      subtitleStyleSource.hoverTokenBackgroundColor !== undefined
+        ? subtitleStyleSource.hoverTokenBackgroundColor
+        : subtitleStyleSource.hoverBackground;
+    const hoverTokenBackgroundColor = asString(rawHoverTokenBackgroundColor);
     if (hoverTokenBackgroundColor !== undefined) {
       resolved.subtitleStyle.hoverTokenBackgroundColor = hoverTokenBackgroundColor;
-    } else if (
-      (src.subtitleStyle as { hoverTokenBackgroundColor?: unknown }).hoverTokenBackgroundColor !==
-      undefined
-    ) {
+    } else if (rawHoverTokenBackgroundColor !== undefined) {
       resolved.subtitleStyle.hoverTokenBackgroundColor =
         fallbackSubtitleStyleHoverTokenBackgroundColor;
       warn(
         'subtitleStyle.hoverTokenBackgroundColor',
-        (src.subtitleStyle as { hoverTokenBackgroundColor?: unknown }).hoverTokenBackgroundColor,
+        rawHoverTokenBackgroundColor,
         resolved.subtitleStyle.hoverTokenBackgroundColor,
         'Expected a CSS color value (hex, rgba/hsl/hsla, named color, or var()).',
       );

src/core/services/anilist/anilist-updater.test.ts

@@ -76,6 +76,32 @@ test('guessAnilistMediaInfo joins multi-part guessit titles', async () => {
   });
 });
 
+test('guessAnilistMediaInfo preserves useful guessit alternative title for ambiguous Re ZERO filenames', async () => {
+  const result = await guessAnilistMediaInfo(
+    '/tmp/Re - ZERO, Starting Life in Another World (2016) - S01E01 - - The End of the Beginning and the Beginning of the End [v2 Bluray-1080p Proper][10bit][x265][FLAC 2.0][EN+JA]-SCY.mkv',
+    null,
+    {
+      runGuessit: async () =>
+        JSON.stringify({
+          title: 'Re',
+          alternative_title: 'ZERO, Starting Life in Another World',
+          year: 2016,
+          season: 1,
+          episode: 1,
+        }),
+    },
+  );
+
+  assert.deepEqual(result, {
+    title: 'Re ZERO, Starting Life in Another World',
+    alternativeTitle: 'ZERO, Starting Life in Another World',
+    year: 2016,
+    season: 1,
+    episode: 1,
+    source: 'guessit',
+  });
+});
+
 test('updateAnilistPostWatchProgress updates progress when behind', async () => {
   const originalFetch = globalThis.fetch;
   let call = 0;

src/core/services/anilist/anilist-updater.ts

@@ -7,6 +7,8 @@ const ANILIST_GRAPHQL_URL = 'https://graphql.anilist.co';
 
 export interface AnilistMediaGuess {
   title: string;
+  alternativeTitle?: string;
+  year?: number;
   season: number | null;
   episode: number | null;
   source: 'guessit' | 'fallback';
@@ -131,6 +133,20 @@ function firstPositiveInteger(value: unknown): number | null {
   return null;
 }
 
+function firstYear(value: unknown): number | undefined {
+  const candidate = firstPositiveInteger(value);
+  if (candidate === null) return undefined;
+  return candidate >= 1900 && candidate <= 2200 ? candidate : undefined;
+}
+
+function buildGuessitTitle(title: string, alternativeTitle: string | null): string {
+  if (!alternativeTitle) return title;
+  if (title.length <= 3) {
+    return `${title} ${alternativeTitle}`.replace(/\s+/g, ' ').trim();
+  }
+  return title;
+}
+
 function normalizeTitle(text: string): string {
   return text.trim().toLowerCase().replace(/\s+/g, ' ');
 }
@@ -215,10 +231,19 @@ export async function guessAnilistMediaInfo(
       const stdout = await deps.runGuessit(guessitTarget);
       const parsed = JSON.parse(stdout) as Record<string, unknown>;
       const title = readGuessitTitle(parsed.title);
+      const alternativeTitle = readGuessitTitle(parsed.alternative_title);
       const episode = firstPositiveInteger(parsed.episode);
       const season = firstPositiveInteger(parsed.season);
+      const year = firstYear(parsed.year);
       if (title) {
-        return { title, season, episode, source: 'guessit' };
+        return {
+          title: buildGuessitTitle(title, alternativeTitle),
+          ...(alternativeTitle ? { alternativeTitle } : {}),
+          ...(year ? { year } : {}),
+          season,
+          episode,
+          source: 'guessit',
+        };
       }
     } catch {
       // Ignore guessit failures and fall back to internal parser.

src/core/services/app-lifecycle.test.ts

@@ -6,12 +6,14 @@ import { AppLifecycleServiceDeps, startAppLifecycle } from './app-lifecycle';
 function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
   return {
     background: false,
+    managedPlayback: false,
     start: false,
     launchMpv: false,
     launchMpvTargets: [],
     stop: false,
     toggle: false,
     toggleVisibleOverlay: false,
+    togglePrimarySubtitleBar: false,
     settings: false,
     setup: false,
     show: false,
@@ -28,12 +30,30 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     triggerFieldGrouping: false,
     triggerSubsync: false,
     markAudioCard: false,
+    toggleStatsOverlay: false,
+    toggleSubtitleSidebar: false,
     openRuntimeOptions: false,
+    openSessionHelp: false,
+    openControllerSelect: false,
+    openControllerDebug: false,
+    openJimaku: false,
+    openYoutubePicker: false,
+    openPlaylistBrowser: false,
+    openCharacterDictionary: false,
+    replayCurrentSubtitle: false,
+    playNextSubtitle: false,
+    shiftSubDelayPrevLine: false,
+    shiftSubDelayNextLine: false,
+    cycleRuntimeOptionId: undefined,
+    cycleRuntimeOptionDirection: undefined,
     anilistStatus: false,
     anilistLogout: false,
     anilistSetup: false,
     anilistRetryQueue: false,
     dictionary: false,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
+    dictionaryAnilistId: undefined,
     stats: false,
     jellyfin: false,
     jellyfinLogin: false,

src/core/services/app-ready.test.ts

@@ -75,11 +75,7 @@ test('runAppReadyRuntime starts websocket in auto mode when plugin missing', asy
     calls.indexOf('setVisibleOverlayVisible:true') < calls.indexOf('initializeOverlayRuntime'),
   );
   assert.ok(calls.includes('startBackgroundWarmups'));
-  assert.ok(
-    calls.includes(
-      'log:Runtime ready: immersion tracker startup deferred until first media activity.',
-    ),
-  );
+  assert.ok(calls.includes('log:Runtime ready: immersion tracker startup requested.'));
 });
 
 test('runAppReadyRuntime starts texthooker on startup when enabled in config', async () => {
@@ -103,6 +99,17 @@ test('runAppReadyRuntime starts texthooker on startup when enabled in config', a
   );
 });
 
+test('runAppReadyRuntime creates immersion tracker during heavy startup', async () => {
+  const { deps, calls } = makeDeps({
+    shouldAutoInitializeOverlayRuntimeFromConfig: () => false,
+  });
+
+  await runAppReadyRuntime(deps);
+
+  assert.equal(calls.includes('createImmersionTracker'), false);
+  assert.ok(calls.includes('log:Runtime ready: immersion tracker startup requested.'));
+});
+
 test('runAppReadyRuntime keeps annotation websocket enabled when regular websocket auto-skips', async () => {
   const { deps, calls } = makeDeps({
     getResolvedConfig: () => ({

src/core/services/cli-command.test.ts

@@ -6,6 +6,7 @@ import { CliCommandServiceDeps, handleCliCommand } from './cli-command';
 function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
   return {
     background: false,
+    managedPlayback: false,
     start: false,
     launchMpv: false,
     launchMpvTargets: [],
@@ -29,13 +30,32 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     triggerFieldGrouping: false,
     triggerSubsync: false,
     markAudioCard: false,
+    toggleStatsOverlay: false,
+    toggleSubtitleSidebar: false,
     refreshKnownWords: false,
     openRuntimeOptions: false,
+    openSessionHelp: false,
+    openCharacterDictionary: false,
+    openControllerSelect: false,
+    openControllerDebug: false,
+    openJimaku: false,
+    openYoutubePicker: false,
+    openPlaylistBrowser: false,
+    togglePrimarySubtitleBar: false,
+    replayCurrentSubtitle: false,
+    playNextSubtitle: false,
+    shiftSubDelayPrevLine: false,
+    shiftSubDelayNextLine: false,
+    cycleRuntimeOptionId: undefined,
+    cycleRuntimeOptionDirection: undefined,
     anilistStatus: false,
     anilistLogout: false,
     anilistSetup: false,
     anilistRetryQueue: false,
     dictionary: false,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
+    dictionaryAnilistId: undefined,
     stats: false,
     jellyfin: false,
     jellyfinLogin: false,
@@ -101,6 +121,9 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     toggleVisibleOverlay: () => {
       calls.push('toggleVisibleOverlay');
     },
+    togglePrimarySubtitleBar: () => {
+      calls.push('togglePrimarySubtitleBar');
+    },
     openYomitanSettingsDelayed: (delayMs) => {
       calls.push(`openYomitanSettingsDelayed:${delayMs}`);
     },
@@ -143,6 +166,9 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     openRuntimeOptionsPalette: () => {
       calls.push('openRuntimeOptionsPalette');
     },
+    dispatchSessionAction: async () => {
+      calls.push('dispatchSessionAction');
+    },
     getAnilistStatus: () => ({
       tokenStatus: 'resolved',
       tokenSource: 'stored',
@@ -182,6 +208,19 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
       mediaTitle: 'Test',
       entryCount: 10,
     }),
+    getCharacterDictionarySelection: async () => ({
+      seriesKey: 'test',
+      guessTitle: 'Test',
+      current: { id: 1, title: 'Test', episodes: 12 },
+      override: null,
+      candidates: [{ id: 1, title: 'Test', episodes: 12 }],
+    }),
+    setCharacterDictionarySelection: async () => ({
+      ok: true,
+      seriesKey: 'test',
+      selected: { id: 1, title: 'Test', episodes: 12 },
+      staleMediaIds: [],
+    }),
     runStatsCommand: async () => {
       calls.push('runStatsCommand');
     },
@@ -499,6 +538,8 @@ test('handleCliCommand handles visibility and utility command dispatches', () =>
       expected: 'startPendingMineSentenceMultiple:2500',
     },
     { args: { toggleSecondarySub: true }, expected: 'cycleSecondarySubMode' },
+    { args: { togglePrimarySubtitleBar: true }, expected: 'togglePrimarySubtitleBar' },
+    { args: { toggleStatsOverlay: true }, expected: 'dispatchSessionAction' },
     {
       args: { openRuntimeOptions: true },
       expected: 'openRuntimeOptionsPalette',
@@ -518,6 +559,33 @@ test('handleCliCommand handles visibility and utility command dispatches', () =>
   }
 });
 
+test('handleCliCommand dispatches cycle-runtime-option session action', async () => {
+  let request: unknown = null;
+  const { deps } = createDeps({
+    dispatchSessionAction: async (nextRequest) => {
+      request = nextRequest;
+    },
+  });
+
+  handleCliCommand(
+    makeArgs({
+      cycleRuntimeOptionId: 'anki.autoUpdateNewCards',
+      cycleRuntimeOptionDirection: -1,
+    }),
+    'initial',
+    deps,
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.deepEqual(request, {
+    actionId: 'cycleRuntimeOption',
+    payload: {
+      runtimeOptionId: 'anki.autoUpdateNewCards',
+      direction: -1,
+    },
+  });
+});
+
 test('handleCliCommand logs AniList status details', () => {
   const { deps, calls } = createDeps();
   handleCliCommand(makeArgs({ anilistStatus: true }), 'initial', deps);
@@ -579,6 +647,105 @@ test('handleCliCommand forwards --dictionary-target to dictionary runtime', asyn
   assert.equal(receivedTarget, '/tmp/example-video.mkv');
 });
 
+test('handleCliCommand lists character dictionary AniList candidates', async () => {
+  const { calls, deps } = createDeps({
+    getCharacterDictionarySelection: async (targetPath?: string) => {
+      calls.push(`getCharacterDictionarySelection:${targetPath ?? ''}`);
+      return {
+        seriesKey: 're-zero-starting-life-in-another-world-2016',
+        guessTitle: 'Re ZERO, Starting Life in Another World',
+        current: { id: 10607, title: 'Rerere no Tensai Bakabon', episodes: null },
+        override: null,
+        candidates: [
+          { id: 21355, title: 'Re:ZERO -Starting Life in Another World-', episodes: 25 },
+          { id: 10607, title: 'Rerere no Tensai Bakabon', episodes: 24 },
+        ],
+      };
+    },
+  });
+
+  handleCliCommand(
+    makeArgs({ dictionaryCandidates: true, dictionaryTarget: '/tmp/re-zero.mkv' }),
+    'initial',
+    deps,
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.ok(calls.includes('getCharacterDictionarySelection:/tmp/re-zero.mkv'));
+  assert.ok(
+    calls.includes(
+      'log:Character dictionary series key: re-zero-starting-life-in-another-world-2016',
+    ),
+  );
+  assert.ok(
+    calls.includes('log:Candidate: 21355 - Re:ZERO -Starting Life in Another World- (25 episodes)'),
+  );
+});
+
+test('handleCliCommand sets character dictionary manual AniList selection', async () => {
+  const { calls, deps } = createDeps({
+    setCharacterDictionarySelection: async (request) => {
+      calls.push(`setCharacterDictionarySelection:${request.mediaId}:${request.targetPath ?? ''}`);
+      return {
+        ok: true,
+        seriesKey: 're-zero-starting-life-in-another-world-2016',
+        selected: {
+          id: request.mediaId,
+          title: 'Re:ZERO -Starting Life in Another World-',
+          episodes: 25,
+        },
+        staleMediaIds: [10607],
+      };
+    },
+  });
+
+  handleCliCommand(
+    makeArgs({
+      dictionarySelect: true,
+      dictionaryAnilistId: 21355,
+      dictionaryTarget: '/tmp/re-zero.mkv',
+    }),
+    'initial',
+    deps,
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.ok(calls.includes('setCharacterDictionarySelection:21355:/tmp/re-zero.mkv'));
+  assert.ok(
+    calls.includes(
+      'log:Character dictionary override saved: re-zero-starting-life-in-another-world-2016 -> 21355 - Re:ZERO -Starting Life in Another World-',
+    ),
+  );
+});
+
+test('handleCliCommand does not log character dictionary selection success when result is not ok', async () => {
+  const { calls, deps } = createDeps({
+    setCharacterDictionarySelection: async () => ({
+      ok: false,
+      seriesKey: 'test',
+      selected: { id: 0, title: '', episodes: null },
+      staleMediaIds: [],
+    }),
+  });
+
+  handleCliCommand(
+    makeArgs({
+      dictionarySelect: true,
+      dictionaryAnilistId: 21355,
+      dictionaryTarget: '/tmp/re-zero.mkv',
+    }),
+    'initial',
+    deps,
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.ok(calls.includes('warn:Character dictionary override was not saved.'));
+  assert.equal(
+    calls.some((call) => call.startsWith('log:Character dictionary override saved:')),
+    false,
+  );
+});
+
 test('handleCliCommand does not dispatch runJellyfinCommand for non-Jellyfin commands', () => {
   const nonJellyfinArgs: Array<Partial<CliArgs>> = [
     { start: true },

src/core/services/cli-command.ts

@@ -1,4 +1,26 @@
 import { CliArgs, CliCommandSource, commandNeedsOverlayRuntime } from '../../cli/args';
+import type { SessionActionDispatchRequest } from '../../types/runtime';
+
+export type CharacterDictionaryCandidate = {
+  id: number;
+  title: string;
+  episodes: number | null;
+};
+
+export type CharacterDictionarySelectionSnapshot = {
+  seriesKey: string;
+  guessTitle: string | null;
+  current: CharacterDictionaryCandidate | null;
+  override: CharacterDictionaryCandidate | null;
+  candidates: CharacterDictionaryCandidate[];
+};
+
+export type CharacterDictionarySelectionResult = {
+  ok: boolean;
+  seriesKey: string;
+  selected: CharacterDictionaryCandidate;
+  staleMediaIds: number[];
+};
 
 export interface CliCommandServiceDeps {
   setLogLevel?: (level: NonNullable<CliArgs['logLevel']>) => void;
@@ -18,6 +40,7 @@ export interface CliCommandServiceDeps {
   isOverlayRuntimeInitialized: () => boolean;
   initializeOverlayRuntime: () => void;
   toggleVisibleOverlay: () => void;
+  togglePrimarySubtitleBar: () => void;
   openFirstRunSetup: () => void;
   openYomitanSettingsDelayed: (delayMs: number) => void;
   setVisibleOverlayVisible: (visible: boolean) => void;
@@ -32,6 +55,7 @@ export interface CliCommandServiceDeps {
   triggerSubsyncFromConfig: () => Promise<void>;
   markLastCardAsAudioCard: () => Promise<void>;
   openRuntimeOptionsPalette: () => void;
+  dispatchSessionAction: (request: SessionActionDispatchRequest) => Promise<void>;
   getAnilistStatus: () => {
     tokenStatus: 'not_checked' | 'resolved' | 'error';
     tokenSource: 'none' | 'literal' | 'stored';
@@ -62,6 +86,13 @@ export interface CliCommandServiceDeps {
     mediaTitle: string;
     entryCount: number;
   }>;
+  getCharacterDictionarySelection: (
+    targetPath?: string,
+  ) => Promise<CharacterDictionarySelectionSnapshot>;
+  setCharacterDictionarySelection: (request: {
+    targetPath?: string;
+    mediaId: number;
+  }) => Promise<CharacterDictionarySelectionResult>;
   runStatsCommand: (args: CliArgs, source: CliCommandSource) => Promise<void>;
   runJellyfinCommand: (args: CliArgs) => Promise<void>;
   runYoutubePlaybackFlow: (request: {
@@ -108,6 +139,7 @@ interface OverlayCliRuntime {
   isInitialized: () => boolean;
   initialize: () => void;
   toggleVisible: () => void;
+  togglePrimarySubtitleBar: () => void;
   setVisible: (visible: boolean) => void;
 }
 
@@ -160,6 +192,11 @@ export interface CliCommandDepsRuntimeOptions {
       mediaTitle: string;
       entryCount: number;
     }>;
+    getSelection: (targetPath?: string) => Promise<CharacterDictionarySelectionSnapshot>;
+    setSelection: (request: {
+      targetPath?: string;
+      mediaId: number;
+    }) => Promise<CharacterDictionarySelectionResult>;
   };
   jellyfin: {
     openSetup: () => void;
@@ -168,6 +205,7 @@ export interface CliCommandDepsRuntimeOptions {
   };
   ui: UiCliRuntime;
   app: AppCliRuntime;
+  dispatchSessionAction: (request: SessionActionDispatchRequest) => Promise<void>;
   getMultiCopyTimeoutMs: () => number;
   schedule: (fn: () => void, delayMs: number) => unknown;
   log: (message: string) => void;
@@ -208,6 +246,7 @@ export function createCliCommandDepsRuntime(
     isOverlayRuntimeInitialized: options.overlay.isInitialized,
     initializeOverlayRuntime: options.overlay.initialize,
     toggleVisibleOverlay: options.overlay.toggleVisible,
+    togglePrimarySubtitleBar: options.overlay.togglePrimarySubtitleBar,
     openFirstRunSetup: options.ui.openFirstRunSetup,
     openYomitanSettingsDelayed: (delayMs) => {
       options.schedule(() => {
@@ -226,6 +265,7 @@ export function createCliCommandDepsRuntime(
     triggerSubsyncFromConfig: options.mining.triggerSubsyncFromConfig,
     markLastCardAsAudioCard: options.mining.markLastCardAsAudioCard,
     openRuntimeOptionsPalette: options.ui.openRuntimeOptionsPalette,
+    dispatchSessionAction: options.dispatchSessionAction,
     getAnilistStatus: options.anilist.getStatus,
     clearAnilistToken: options.anilist.clearToken,
     openAnilistSetup: options.anilist.openSetup,
@@ -233,6 +273,8 @@ export function createCliCommandDepsRuntime(
     getAnilistQueueStatus: options.anilist.getQueueStatus,
     retryAnilistQueue: options.anilist.retryQueueNow,
     generateCharacterDictionary: options.dictionary.generate,
+    getCharacterDictionarySelection: options.dictionary.getSelection,
+    setCharacterDictionarySelection: options.dictionary.setSelection,
     runStatsCommand: options.jellyfin.runStatsCommand,
     runJellyfinCommand: options.jellyfin.runCommand,
     runYoutubePlaybackFlow: options.app.runYoutubePlaybackFlow,
@@ -263,11 +305,27 @@ function runAsyncWithOsd(
   });
 }
 
+function formatCandidate(candidate: CharacterDictionaryCandidate): string {
+  const episodeLabel =
+    typeof candidate.episodes === 'number' && candidate.episodes > 0
+      ? `${candidate.episodes} episodes`
+      : 'episodes unknown';
+  return `${candidate.id} - ${candidate.title} (${episodeLabel})`;
+}
+
 export function handleCliCommand(
   args: CliArgs,
   source: CliCommandSource = 'initial',
   deps: CliCommandServiceDeps,
 ): void {
+  const dispatchCliSessionAction = (
+    request: SessionActionDispatchRequest,
+    logLabel: string,
+    osdLabel: string,
+  ): void => {
+    runAsyncWithOsd(() => deps.dispatchSessionAction(request), deps, logLabel, osdLabel);
+  };
+
   if (args.logLevel) {
     deps.setLogLevel?.(args.logLevel);
   }
@@ -314,6 +372,8 @@ export function handleCliCommand(
 
   if (args.toggle || args.toggleVisibleOverlay) {
     deps.toggleVisibleOverlay();
+  } else if (args.togglePrimarySubtitleBar) {
+    deps.togglePrimarySubtitleBar();
   } else if (args.setup) {
     deps.openFirstRunSetup();
     deps.log('Opened first-run setup flow.');
@@ -379,8 +439,106 @@ export function handleCliCommand(
       'markLastCardAsAudioCard',
       'Audio card failed',
     );
+  } else if (args.toggleStatsOverlay) {
+    dispatchCliSessionAction(
+      { actionId: 'toggleStatsOverlay' },
+      'toggleStatsOverlay',
+      'Stats toggle failed',
+    );
+  } else if (args.toggleSubtitleSidebar) {
+    dispatchCliSessionAction(
+      { actionId: 'toggleSubtitleSidebar' },
+      'toggleSubtitleSidebar',
+      'Subtitle sidebar toggle failed',
+    );
   } else if (args.openRuntimeOptions) {
     deps.openRuntimeOptionsPalette();
+  } else if (args.openSessionHelp) {
+    dispatchCliSessionAction(
+      { actionId: 'openSessionHelp' },
+      'openSessionHelp',
+      'Open session help failed',
+    );
+  } else if (args.openCharacterDictionary) {
+    dispatchCliSessionAction(
+      { actionId: 'openCharacterDictionary' },
+      'openCharacterDictionary',
+      'Open character dictionary failed',
+    );
+  } else if (args.openControllerSelect) {
+    dispatchCliSessionAction(
+      { actionId: 'openControllerSelect' },
+      'openControllerSelect',
+      'Open controller select failed',
+    );
+  } else if (args.openControllerDebug) {
+    dispatchCliSessionAction(
+      { actionId: 'openControllerDebug' },
+      'openControllerDebug',
+      'Open controller debug failed',
+    );
+  } else if (args.openJimaku) {
+    dispatchCliSessionAction({ actionId: 'openJimaku' }, 'openJimaku', 'Open jimaku failed');
+  } else if (args.openYoutubePicker) {
+    dispatchCliSessionAction(
+      { actionId: 'openYoutubePicker' },
+      'openYoutubePicker',
+      'Open YouTube picker failed',
+    );
+  } else if (args.openPlaylistBrowser) {
+    dispatchCliSessionAction(
+      { actionId: 'openPlaylistBrowser' },
+      'openPlaylistBrowser',
+      'Open playlist browser failed',
+    );
+  } else if (args.replayCurrentSubtitle) {
+    dispatchCliSessionAction(
+      { actionId: 'replayCurrentSubtitle' },
+      'replayCurrentSubtitle',
+      'Replay subtitle failed',
+    );
+  } else if (args.playNextSubtitle) {
+    dispatchCliSessionAction(
+      { actionId: 'playNextSubtitle' },
+      'playNextSubtitle',
+      'Play next subtitle failed',
+    );
+  } else if (args.shiftSubDelayPrevLine) {
+    dispatchCliSessionAction(
+      { actionId: 'shiftSubDelayPrevLine' },
+      'shiftSubDelayPrevLine',
+      'Shift subtitle delay failed',
+    );
+  } else if (args.shiftSubDelayNextLine) {
+    dispatchCliSessionAction(
+      { actionId: 'shiftSubDelayNextLine' },
+      'shiftSubDelayNextLine',
+      'Shift subtitle delay failed',
+    );
+  } else if (args.cycleRuntimeOptionId !== undefined) {
+    dispatchCliSessionAction(
+      {
+        actionId: 'cycleRuntimeOption',
+        payload: {
+          runtimeOptionId: args.cycleRuntimeOptionId,
+          direction: args.cycleRuntimeOptionDirection ?? 1,
+        },
+      },
+      'cycleRuntimeOption',
+      'Runtime option change failed',
+    );
+  } else if (args.copySubtitleCount !== undefined) {
+    dispatchCliSessionAction(
+      { actionId: 'copySubtitleMultiple', payload: { count: args.copySubtitleCount } },
+      'copySubtitleMultiple',
+      'Copy failed',
+    );
+  } else if (args.mineSentenceCount !== undefined) {
+    dispatchCliSessionAction(
+      { actionId: 'mineSentenceMultiple', payload: { count: args.mineSentenceCount } },
+      'mineSentenceMultiple',
+      'Mine sentence failed',
+    );
   } else if (args.anilistStatus) {
     const status = deps.getAnilistStatus();
     deps.log(`AniList token status: ${status.tokenStatus} (source=${status.tokenSource})`);
@@ -442,6 +600,75 @@ export function handleCliCommand(
           deps.stopApp();
         }
       });
+  } else if (args.dictionaryCandidates) {
+    const shouldStopAfterRun = source === 'initial' && !deps.hasMainWindow();
+    deps
+      .getCharacterDictionarySelection(args.dictionaryTarget)
+      .then((selection) => {
+        deps.log(`Character dictionary series key: ${selection.seriesKey}`);
+        if (selection.guessTitle) {
+          deps.log(`Guess: ${selection.guessTitle}`);
+        }
+        if (selection.current) {
+          deps.log(`Current match: ${formatCandidate(selection.current)}`);
+        }
+        if (selection.override) {
+          deps.log(`Manual override: ${formatCandidate(selection.override)}`);
+        }
+        for (const candidate of selection.candidates) {
+          deps.log(`Candidate: ${formatCandidate(candidate)}`);
+        }
+      })
+      .catch((error) => {
+        deps.error('getCharacterDictionarySelection failed:', error);
+        deps.warn(
+          `Character dictionary candidate lookup failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      })
+      .finally(() => {
+        if (shouldStopAfterRun) {
+          deps.stopApp();
+        }
+      });
+  } else if (args.dictionarySelect) {
+    const shouldStopAfterRun = source === 'initial' && !deps.hasMainWindow();
+    if (!args.dictionaryAnilistId) {
+      deps.warn('--dictionary-select requires --dictionary-anilist-id <ID>.');
+      if (shouldStopAfterRun) deps.stopApp();
+      return;
+    }
+    deps
+      .setCharacterDictionarySelection({
+        targetPath: args.dictionaryTarget,
+        mediaId: args.dictionaryAnilistId,
+      })
+      .then((result) => {
+        if (!result.ok) {
+          deps.warn('Character dictionary override was not saved.');
+          return;
+        }
+        deps.log(
+          `Character dictionary override saved: ${result.seriesKey} -> ${result.selected.id} - ${result.selected.title}`,
+        );
+        if (result.staleMediaIds.length > 0) {
+          deps.log(`Removed stale AniList IDs: ${result.staleMediaIds.join(', ')}`);
+        }
+      })
+      .catch((error) => {
+        deps.error('setCharacterDictionarySelection failed:', error);
+        deps.warn(
+          `Character dictionary override failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      })
+      .finally(() => {
+        if (shouldStopAfterRun) {
+          deps.stopApp();
+        }
+      });
   } else if (args.stats) {
     void deps.runStatsCommand(args, source);
   } else if (args.anilistRetryQueue) {