chore: add changelog fragment for subtitle sidebar changes

chore: regenerate release config example artifacts
fix: align subtitle sidebar state and behavior updates
2026-04-09 04:19:27 -07:00 · 2026-03-21 23:33:33 -07:00 · 2026-03-21 23:11:21 -07:00 · 2026-03-21 22:24:42 -07:00 · 2026-03-21 22:24:39 -07:00 · 2026-03-21 21:15:41 -07:00
44 changed files with 2810 additions and 414 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,21 @@
 # Changelog

+## v0.8.0 (2026-03-22)
+
+### Changed
+- Docs: Refreshed the vendored Texthooker docs/index.html bundle to match the latest local build artifacts.
+
+### Fixed
+- Anki: Known-word cache refreshes now reconcile Anki changes incrementally instead of wiping and rebuilding on startup, mined cards can append their word into the cache immediately through a new default-enabled config flag, and explicit refreshes now run through `subminer doctor --refresh-known-words`.
+- Subtitle: Restored known-word coloring and JLPT underlines for subtitle tokens like `大体` when the subtitle token is kanji but the known-word cache only matches the kana reading.
+- Stats: Episode progress in the anime page now uses the last ended playback position instead of cumulative active watch time, avoiding distorted percentages after rewatches or repeated sessions.
+- Stats: Anime episode progress now keeps the latest known playback position through active-session checkpoints and stale-session recovery, so recently watched episodes no longer lose their progress percentage.
+- Stats: Anime episode progress now falls back to the latest retained subtitle/event timing when a session is missing a persisted playback-position checkpoint, so older watch sessions no longer get stuck at `0%` progress.
+- Overlay: Kept subtitle sidebar cue tracking stable across transitions by avoiding cue-line regression on subtitle timing edge cases and stale text updates.
+- Overlay: Improved sidebar config by documenting and exposing layout mode and typography options (`layout`, `fontFamily`, `fontSize`) in the generated documentation flow.
+- Overlay: Added `subtitleSidebar.autoOpen` (default `false`) to open the subtitle sidebar once during overlay startup when the sidebar feature is enabled.
+- Overlay: Made subtitle sidebar resume/start positioning jump directly to the first resolved active cue instead of smooth-scrolling through the full list, while keeping smooth auto-follow for later cue changes.
+
 ## v0.7.0 (2026-03-19)

 ### Added
--- a/Jump-subtitle-sidebar-directly-to-resume-position-on-first-resolved-cue.md
+++ b/Jump-subtitle-sidebar-directly-to-resume-position-on-first-resolved-cue.md
@@ -0,0 +1,37 @@
+---
+id: TASK-214
+title: Jump subtitle sidebar directly to resume position on first resolved cue
+status: In Progress
+assignee: []
+created_date: '2026-03-21 11:15'
+updated_date: '2026-03-21 11:15'
+labels:
+  - bug
+  - ux
+  - overlay
+  - subtitles
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/src/renderer/modals/subtitle-sidebar.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/renderer/modals/subtitle-sidebar.test.ts
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+When playback starts from a resumed timestamp while the subtitle sidebar is open, the sidebar currently smooth-scrolls from the top of the cue list to the resumed cue. Change the first resolved active-cue positioning to jump immediately to the resume location while preserving smooth auto-follow for later playback-driven cue advances.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The first active cue resolved after open/resume uses an instant jump instead of smooth-scrolling through the list.
+- [x] #2 Normal subtitle-sidebar auto-follow remains smooth after the first active cue has been positioned.
+- [x] #3 Regression coverage distinguishes the initial jump behavior from later smooth auto-follow updates.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-21: Fixed by treating the first auto-scroll from `previousActiveCueIndex < 0` as `behavior: 'auto'` in the subtitle sidebar scroll helper. Added renderer regression coverage for initial jump plus later smooth follow.
+<!-- SECTION:NOTES:END -->
--- a/Add-startup-auto-open-option-for-subtitle-sidebar.md
+++ b/Add-startup-auto-open-option-for-subtitle-sidebar.md
@@ -0,0 +1,40 @@
+---
+id: TASK-215
+title: Add startup auto-open option for subtitle sidebar
+status: In Progress
+assignee: []
+created_date: '2026-03-21 11:35'
+updated_date: '2026-03-21 11:35'
+labels:
+  - feature
+  - ux
+  - overlay
+  - subtitles
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/src/types.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/config/definitions/defaults-subtitle.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/config/resolve/subtitle-domains.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/renderer/modals/subtitle-sidebar.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/renderer/renderer.ts
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add a subtitle sidebar config option that auto-opens the sidebar once during overlay startup. The option should default to `false`, only apply when the sidebar feature is enabled, and should not force the sidebar back open later in the same session after manual close or later visibility changes.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `subtitleSidebar.autoOpen` is available in config with default `false`.
+- [x] #2 When enabled, overlay startup opens the subtitle sidebar once after initial sidebar config/snapshot load.
+- [x] #3 Regression coverage covers config resolution and startup-only auto-open behavior.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-21: Added `subtitleSidebar.autoOpen` to types/defaults/config registry and resolver. Renderer bootstrap now calls a startup-only subtitle sidebar helper after the initial snapshot refresh. Modal regression coverage verifies startup auto-open requires both `enabled` and `autoOpen`.
+<!-- SECTION:NOTES:END -->
--- a/Address-PR-28-CodeRabbit-follow-ups-on-subtitle-sidebar.md
+++ b/Address-PR-28-CodeRabbit-follow-ups-on-subtitle-sidebar.md
@@ -0,0 +1,79 @@
+---
+id: TASK-216
+title: 'Address PR #28 CodeRabbit follow-ups on subtitle sidebar'
+status: Completed
+assignee:
+  - '@codex'
+created_date: '2026-03-21 00:00'
+updated_date: '2026-03-21 00:00'
+labels:
+  - pr-review
+  - subtitle-sidebar
+  - renderer
+dependencies: []
+references:
+  - src/main/runtime/subtitle-prefetch-init.ts
+  - src/main/runtime/subtitle-prefetch-init.test.ts
+  - src/renderer/handlers/mouse.ts
+  - src/renderer/handlers/mouse.test.ts
+  - src/renderer/modals/subtitle-sidebar.ts
+  - src/renderer/modals/subtitle-sidebar.test.ts
+  - src/renderer/style.css
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Validate the CodeRabbit follow-ups on PR #28 for the subtitle sidebar workstream, implement the confirmed fixes, and verify the touched runtime and renderer paths.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Review comments that described real regressions are fixed in code
+- [x] #2 Focused regression coverage exists for the fixed behaviors
+- [x] #3 Targeted typecheck and runtime-compat verification pass
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Completed follow-up fixes for PR #28:
+- Cleared parsed subtitle cues on subtitle prefetch init failure so stale snapshot cache entries do not survive a failed refresh.
+- Treated primary and secondary subtitle containers as one hover region so moving between them does not resume playback mid-transition.
+- Kept the subtitle sidebar closed when disabled, serialized snapshot polling with timeouts, made cue rows keyboard-activatable, resolved stale cue selection fallback, and resumed hover-paused playback when the modal closes.
+
+Regression coverage added:
+- `src/main/runtime/subtitle-prefetch-init.test.ts`
+- `src/renderer/handlers/mouse.test.ts`
+- `src/renderer/modals/subtitle-sidebar.test.ts`
+
+Verification:
+- `bun test src/main/runtime/subtitle-prefetch-init.test.ts`
+- `bun test src/renderer/handlers/mouse.test.ts`
+- `bun test src/renderer/modals/subtitle-sidebar.test.ts`
+- `bun run typecheck`
+- `bun run test:runtime:compat`
+
+2026-03-21: Reopened to assess a newer CodeRabbit review pass on PR #28 and address any remaining valid action items before push/reply.
+
+2026-03-21: Addressed the latest CodeRabbit follow-up pass in commit d70c6448 after rebasing onto the updated remote branch tip.
+
+2026-03-21: Reopened for the latest CodeRabbit round on commit d70c6448; current actionable item is the invalid ctx.state.isOverSubtitleSidebar assignment in subtitle-sidebar.ts.
+
+2026-03-22: Addressed the live hover-state and startup mouse-ignore follow-ups from the latest CodeRabbit pass. `handleMouseLeave()` now clears `isOverSubtitle` and drops `secondary-sub-hover-active` when leaving the secondary subtitle container toward the primary container, and renderer startup now calls `syncOverlayMouseIgnoreState(ctx)` instead of forcing `setIgnoreMouseEvents(true, { forward: true })`. The sidebar IPC hover catch and CSS spacing comments were already satisfied in the current tree.
+
+2026-03-22: Regenerated `bun.lock` from a clean install so the `electron-builder-squirrel-windows` override now resolves at `26.8.2` in the lockfile alongside `app-builder-lib@26.8.2`.
+
+2026-03-21: Finished the remaining cleanup pass from the latest review. `subtitleSidebar.layout` now uses enum validation, `SubtitleCue` is re-exported from `src/types.ts` as the single public type path, and the subtitle sidebar resize listener now has unload cleanup wired through the renderer.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented the confirmed PR #28 CodeRabbit follow-ups for subtitle sidebar behavior and added regression coverage plus verification for the touched renderer and runtime paths.
+
+Handled the latest CodeRabbit review pass for PR #28: accepted zero sidebar opacity, closed/inerted the sidebar when refresh sees config disabled, moved poll rescheduling out of finally, caught hover pause IPC failures, and fixed the stylelint spacing issue.
+
+Verification: bun test src/config/resolve/subtitle-sidebar.test.ts; bun test src/renderer/modals/subtitle-sidebar.test.ts; bun test src/renderer/handlers/mouse.test.ts; bun run typecheck; bun run test:fast; bun run test:env; bun run build; SubMiner verifier lanes config + runtime-compat (including test:runtime:compat and test:smoke:dist).
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-embedded-overlay-passthrough-sync-between-subtitle-and-sidebar.md
+++ b/Fix-embedded-overlay-passthrough-sync-between-subtitle-and-sidebar.md
@@ -0,0 +1,69 @@
+---
+id: TASK-217
+title: Fix embedded overlay passthrough sync between subtitle and sidebar
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-21 23:16'
+updated_date: '2026-03-21 23:28'
+labels:
+  - bug
+  - overlay
+  - macos
+dependencies: []
+references:
+  - src/renderer/handlers/mouse.ts
+  - src/renderer/modals/subtitle-sidebar.ts
+  - src/renderer/renderer.ts
+documentation:
+  - docs/workflow/verification.md
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+On macOS, when both the subtitle overlay and embedded subtitle sidebar are visible, mouse passthrough to mpv can remain stale until the user hovers the sidebar. After closing the sidebar, passthrough can likewise remain stale until the user hovers the subtitle again. Fix the overlay input-state synchronization so passthrough reflects the current hover/open state immediately instead of relying on the last hover target.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 When the embedded subtitle sidebar is open and the pointer is not over subtitle or sidebar content, the overlay returns to mouse passthrough immediately without requiring a sidebar hover cycle.
+- [x] #2 When transitioning between subtitle hover and sidebar hover states on macOS embedded sidebar mode, mouse ignore state stays in sync with the currently interactive region.
+- [x] #3 Closing the embedded subtitle sidebar restores the correct passthrough state based on remaining subtitle hover/modal state without requiring an additional hover.
+- [x] #4 Regression tests cover the passthrough synchronization behavior.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a shared renderer-side passthrough sync helper that derives whether the overlay should ignore mouse events from subtitle hover, embedded sidebar visibility/hover, popup visibility, and modal state.
+2. Replace direct embedded-sidebar passthrough toggles in subtitle hover/sidebar handlers with calls to the shared sync helper so state is recomputed on every transition.
+3. Add regression tests for macOS embedded sidebar mode covering sidebar-open idle passthrough, subtitle-to-sidebar transitions, and sidebar-close restore behavior.
+4. Run targeted renderer tests for mouse/sidebar passthrough coverage, then summarize any residual risk.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added shared renderer overlay mouse-ignore recompute so subtitle hover, embedded sidebar hover/open/close, and popup idle transitions all derive passthrough from current state instead of last hover target.
+
+Added regression coverage for embedded sidebar idle passthrough on subtitle leave and for sidebar-close recompute behavior.
+
+Verification: `bun run typecheck` passed; `bun test src/renderer/handlers/mouse.test.ts` passed; `bun test src/renderer/modals/subtitle-sidebar.test.ts` passed; core verification wrapper artifact at `.tmp/skill-verification/subminer-verify-20260321-162743-XhSBxw` hit an unrelated `bun run test:fast` failure in `scripts/update-aur-package.test.ts` because macOS system bash lacks `mapfile`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed stale embedded-sidebar passthrough sync on macOS by introducing a shared renderer mouse-ignore recompute path and tracking sidebar-hover state separately from subtitle hover. Subtitle hover leave, sidebar hover enter/leave, sidebar open, and sidebar close now all recompute passthrough from the current overlay state instead of waiting for a later hover event to repair it. Added regression tests covering subtitle-leave passthrough while the embedded sidebar is open but idle, plus sidebar-close restore behavior based on remaining subtitle hover state.
+
+Tests run:
+- `bun run typecheck`
+- `bun test src/renderer/handlers/mouse.test.ts`
+- `bun test src/renderer/modals/subtitle-sidebar.test.ts`
+- `bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh src/renderer/state.ts src/renderer/overlay-mouse-ignore.ts src/renderer/handlers/mouse.ts src/renderer/handlers/mouse.test.ts src/renderer/modals/subtitle-sidebar.ts src/renderer/modals/subtitle-sidebar.test.ts`
+- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/renderer/state.ts src/renderer/overlay-mouse-ignore.ts src/renderer/handlers/mouse.ts src/renderer/handlers/mouse.test.ts src/renderer/modals/subtitle-sidebar.ts src/renderer/modals/subtitle-sidebar.test.ts` (typecheck passed; `test:fast` blocked by unrelated `scripts/update-aur-package.test.ts` failure on macOS Bash 3.2 lacking `mapfile`)
+
+Risk: the classifier flagged this as a real-runtime candidate, so actual Electron/mpv macOS pointer behavior was not exercised in a live runtime during this turn.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/bun.lock
+++ b/bun.lock
--- a/changes/2026-03-19-incremental-known-word-cache.md
+++ b/changes/2026-03-19-incremental-known-word-cache.md
@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
- Known-word cache refreshes now reconcile Anki changes incrementally instead of wiping and rebuilding on startup, mined cards can append their word into the cache immediately through a new default-enabled config flag, and explicit refreshes now run through `subminer doctor --refresh-known-words`.
--- a/changes/2026-03-19-known-jlpt-reading-fallback.md
+++ b/changes/2026-03-19-known-jlpt-reading-fallback.md
@@ -1,4 +0,0 @@
-type: fixed
-area: subtitle
-
- Restored known-word coloring and JLPT underlines for subtitle tokens like `大体` when the subtitle token is kanji but the known-word cache only matches the kana reading.
--- a/changes/2026-03-19-stats-ended-media-progress.md
+++ b/changes/2026-03-19-stats-ended-media-progress.md
@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
- Episode progress in the anime page now uses the last ended playback position instead of cumulative active watch time, avoiding distorted percentages after rewatches or repeated sessions.
--- a/changes/2026-03-19-stats-session-progress-checkpoint.md
+++ b/changes/2026-03-19-stats-session-progress-checkpoint.md
@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
- Anime episode progress now keeps the latest known playback position through active-session checkpoints and stale-session recovery, so recently watched episodes no longer lose their progress percentage.
--- a/changes/2026-03-19-texthooker-docs-bundle-update.md
+++ b/changes/2026-03-19-texthooker-docs-bundle-update.md
@@ -1,4 +0,0 @@
-type: changed
-area: docs
-
- Refreshed the vendored Texthooker docs/index.html bundle to match the latest local build artifacts.
--- a/changes/2026-03-20-stats-episode-progress-subtitle-fallback.md
+++ b/changes/2026-03-20-stats-episode-progress-subtitle-fallback.md
@@ -1,4 +0,0 @@
-type: fixed
-area: stats
-
- Anime episode progress now falls back to the latest retained subtitle/event timing when a session is missing a persisted playback-position checkpoint, so older watch sessions no longer get stuck at `0%` progress.
--- a/changes/2026-03-20-subtitle-sidebar-stability.md
+++ b/changes/2026-03-20-subtitle-sidebar-stability.md
@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
- Kept subtitle sidebar cue tracking stable across transitions by avoiding cue-line regression on subtitle timing edge cases and stale text updates.
- Improved sidebar config by documenting and exposing layout mode and typography options (`layout`, `fontFamily`, `fontSize`) in the generated documentation flow.
--- a/changes/2026-03-22-subtitle-sidebar-config.md
+++ b/changes/2026-03-22-subtitle-sidebar-config.md
@@ -0,0 +1,5 @@
+type: changed
+area: subtitle sidebar
+
+- Added subtitle sidebar state and behavior updates, including startup-auto-open controls and resume positioning improvements.
+- Fixed subtitle prefetch and embedded overlay passthrough sync between sidebar and overlay subtitle rendering.
--- a/config.example.jsonc
+++ b/config.example.jsonc
@@ -291,7 +291,8 @@
  // ==========================================
  "subtitleSidebar": {
    "enabled": false, // Enable the subtitle sidebar feature for parsed subtitle sources. Values: true | false
-    "layout": "overlay", // Render the subtitle sidebar as a floating overlay or reserve space inside mpv.
+    "autoOpen": false, // Automatically open the subtitle sidebar once during overlay startup. Values: true | false
+    "layout": "overlay", // Render the subtitle sidebar as a floating overlay or reserve space inside mpv. Values: overlay | embedded
    "toggleKey": "Backslash", // KeyboardEvent.code used to toggle the subtitle sidebar open and closed.
    "pauseVideoOnHover": false, // Pause mpv while hovering the subtitle sidebar, then resume on leave. Values: true | false
    "autoScroll": true, // Auto-scroll the active subtitle cue into view while playback advances. Values: true | false
--- a/docs-site/changelog.md
+++ b/docs-site/changelog.md
@@ -1,5 +1,14 @@
 # Changelog

+## v0.8.0 (2026-03-22)
+- Refreshed the vendored Texthooker docs/index.html bundle to match the latest local build artifacts.
+- Added incremental known-word cache refresh behavior so mined cards can append cache entries immediately and `subminer doctor --refresh-known-words` is now the explicit full refresh path.
+- Fixed known-word/JLPT subtitle styling so tokens like `大体` keep expected coloring even when only the kana reading is in cache.
+- Fixed anime progress to use last ended playback position and keep latest known checkpoint across sessions, preventing stale or zero percent regressions.
+- Kept subtitle sidebar cue tracking stable across transitions and improved sidebar configuration documentation for `layout`, `fontFamily`, and `fontSize`.
+- Added `subtitleSidebar.autoOpen` to open the subtitle sidebar at startup when enabled.
+- Improved sidebar resume/start behavior to jump directly to the active cue on resume while preserving auto-follow smooth motion.
+
 ## v0.7.0 (2026-03-19)
 - Added a full local immersion dashboard release line with Overview, Library, Trends, Vocabulary, and Sessions drill-down views backed by SQLite tracking data.
 - Added browser-first stats workflows: `subminer stats`, background stats daemon controls (`-b` / `-s`), stats cleanup, and dashboard-side mining actions with media enrichment.
--- a/docs-site/public/config.example.jsonc
+++ b/docs-site/public/config.example.jsonc
@@ -291,7 +291,8 @@
  // ==========================================
  "subtitleSidebar": {
    "enabled": false, // Enable the subtitle sidebar feature for parsed subtitle sources. Values: true | false
-    "layout": "overlay", // Render the subtitle sidebar as a floating overlay or reserve space inside mpv.
+    "autoOpen": false, // Automatically open the subtitle sidebar once during overlay startup. Values: true | false
+    "layout": "overlay", // Render the subtitle sidebar as a floating overlay or reserve space inside mpv. Values: overlay | embedded
    "toggleKey": "Backslash", // KeyboardEvent.code used to toggle the subtitle sidebar open and closed.
    "pauseVideoOnHover": false, // Pause mpv while hovering the subtitle sidebar, then resume on leave. Values: true | false
    "autoScroll": true, // Auto-scroll the active subtitle cue into view while playback advances. Values: true | false
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "subminer",
-  "version": "0.7.1",
+  "version": "0.8.0",
  "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
  "packageManager": "bun@1.3.5",
  "main": "dist/main-entry.js",
@@ -77,6 +77,12 @@
    "build:win": "bun run build && electron-builder --win nsis zip --publish never",
    "build:win:unsigned": "bun run build && node scripts/build-win-unsigned.mjs"
  },
+  "overrides": {
+    "app-builder-lib": "26.8.2",
+    "electron-builder-squirrel-windows": "26.8.2",
+    "minimatch": "10.2.3",
+    "tar": "7.5.11"
+  },
  "keywords": [
    "anki",
    "ankiconnect",
@@ -105,7 +111,7 @@
    "@types/node": "^25.3.0",
    "@types/ws": "^8.18.1",
    "electron": "^37.10.3",
-    "electron-builder": "^26.8.1",
+    "electron-builder": "26.8.2",
    "esbuild": "^0.25.12",
    "prettier": "^3.8.1",
    "typescript": "^5.9.3"
@@ -159,12 +165,21 @@
      "include": "build/installer.nsh"
    },
    "files": [
-      "dist/**/*",
-      "stats/dist/**/*",
-      "vendor/texthooker-ui/docs/**/*",
-      "vendor/texthooker-ui/package.json",
-      "package.json",
-      "scripts/get-mpv-window-macos.swift"
+      "**/*",
+      "!src{,/**/*}",
+      "!launcher{,/**/*}",
+      "!stats/src{,/**/*}",
+      "!stats/index.html",
+      "!docs-site{,/**/*}",
+      "!changes{,/**/*}",
+      "!backlog{,/**/*}",
+      "!.tmp{,/**/*}",
+      "!release-*{,/**/*}",
+      "!vendor/subminer-yomitan{,/**/*}",
+      "!vendor/texthooker-ui/src{,/**/*}",
+      "!vendor/texthooker-ui/node_modules{,/**/*}",
+      "!vendor/texthooker-ui/.svelte-kit{,/**/*}",
+      "!vendor/texthooker-ui/package-lock.json"
    ],
    "extraResources": [
      {
--- a/scripts/patch-modernz.sh
+++ b/scripts/patch-modernz.sh
@@ -0,0 +1,157 @@
+#!/bin/bash
+
+set -euo pipefail
+
+TARGET="${HOME}/.config/mpv/scripts/modernz.lua"
+
+usage() {
+    cat <<'EOF'
+Usage: patch-modernz.sh [--target /path/to/modernz.lua]
+
+Applies the local ModernZ OSC sidebar-resize patch to an existing modernz.lua.
+If the target file does not exist, the script exits without changing anything.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --target)
+            if [[ $# -lt 2 || -z "${2:-}" || "$2" == -* ]]; then
+                echo "patch-modernz: --target requires a non-empty file path" >&2
+                usage >&2
+                exit 1
+            fi
+            TARGET="$2"
+            shift 2
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown argument: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+if [[ ! -f "$TARGET" ]]; then
+    echo "patch-modernz: target missing, skipped: $TARGET"
+    exit 0
+fi
+
+if grep -q 'get_external_video_margin_ratio' "$TARGET" \
+    && grep -q 'observe_cached("video-margin-ratio-right"' "$TARGET"; then
+    echo "patch-modernz: already patched: $TARGET"
+    exit 0
+fi
+
+if ! patch --forward --quiet "$TARGET" <<'PATCH'
+--- a/modernz.lua
+++ b/modernz.lua
+@@ -931,6 +931,26 @@ local function reset_margins()
+     set_margin_offset("osd-margin-y", 0)
+ end
+ 
+local function get_external_video_margin_ratio(prop)
+    local value = mp.get_property_number(prop, 0) or 0
+    if value < 0 then return 0 end
+    if value > 0.95 then return 0.95 end
+    return value
+end
+
+local function get_layout_horizontal_bounds()
+    local margin_l = get_external_video_margin_ratio("video-margin-ratio-left")
+    local margin_r = get_external_video_margin_ratio("video-margin-ratio-right")
+    local width_ratio = math.max(0.05, 1 - margin_l - margin_r)
+    local pos_x = osc_param.playresx * margin_l
+    local width = osc_param.playresx * width_ratio
+
+    osc_param.video_margins.l = margin_l
+    osc_param.video_margins.r = margin_r
+
+    return pos_x, width
+end
+
+ local function update_margins()
+     local use_margins = get_hidetimeout() < 0 or user_opts.dynamic_margins
+     local top_vis    = state.wc_visible
+@@ -1965,8 +1985,9 @@ layouts["modern"] = function ()
+     local chapter_index = user_opts.show_chapter_title and mp.get_property_number("chapter", -1) >= 0
+     local osc_height_offset = (no_title and user_opts.notitle_osc_h_offset or 0) + ((no_chapter or not chapter_index) and user_opts.nochapter_osc_h_offset or 0)
+ 
+    local posX, layout_width = get_layout_horizontal_bounds()
+     local osc_geo = {
+-        w = osc_param.playresx,
+        w = layout_width,
+         h = user_opts.osc_height - osc_height_offset
+     }
+ 
+@@ -1974,7 +1995,6 @@ layouts["modern"] = function ()
+     osc_param.video_margins.b = math.max(user_opts.osc_height, user_opts.fade_alpha) / osc_param.playresy
+ 
+     -- origin of the controllers, left/bottom corner
+-    local posX = 0
+     local posY = osc_param.playresy
+ 
+     osc_param.areas = {} -- delete areas
+@@ -2191,8 +2211,9 @@ layouts["modern-compact"] = function ()
+         ((user_opts.title_mbtn_left_command == "" and user_opts.title_mbtn_right_command == "") and 25 or 0) +
+         (((user_opts.chapter_title_mbtn_left_command == "" and user_opts.chapter_title_mbtn_right_command == "") or not chapter_index) and 10 or 0)
+ 
+    local posX, layout_width = get_layout_horizontal_bounds()
+     local osc_geo = {
+-        w = osc_param.playresx,
+        w = layout_width,
+         h = 145 - osc_height_offset
+     }
+ 
+@@ -2200,7 +2221,6 @@ layouts["modern-compact"] = function ()
+     osc_param.video_margins.b = math.max(osc_geo.h, user_opts.fade_alpha) / osc_param.playresy
+ 
+     -- origin of the controllers, left/bottom corner
+-    local posX = 0
+     local posY = osc_param.playresy
+ 
+     osc_param.areas = {} -- delete areas
+@@ -2370,8 +2390,9 @@ layouts["modern-compact"] = function ()
+ end
+ 
+ layouts["modern-image"] = function ()
+    local posX, layout_width = get_layout_horizontal_bounds()
+     local osc_geo = {
+-        w = osc_param.playresx,
+        w = layout_width,
+         h = 50
+     }
+ 
+@@ -2379,7 +2400,6 @@ layouts["modern-image"] = function ()
+     osc_param.video_margins.b = math.max(50, user_opts.fade_alpha) / osc_param.playresy
+ 
+     -- origin of the controllers, left/bottom corner
+-    local posX = 0
+     local posY = osc_param.playresy
+ 
+     osc_param.areas = {} -- delete areas
+@@ -3718,6 +3738,14 @@ observe_cached("border", request_init_resize)
+ observe_cached("title-bar", request_init_resize)
+ observe_cached("window-maximized", request_init_resize)
+ observe_cached("idle-active", request_tick)
+observe_cached("video-margin-ratio-left", function ()
+    state.marginsREQ = true
+    request_init_resize()
+end)
+observe_cached("video-margin-ratio-right", function ()
+    state.marginsREQ = true
+    request_init_resize()
+end)
+ mp.observe_property("user-data/mpv/console/open", "bool", function(_, val)
+     if val and user_opts.visibility == "auto" and not user_opts.showonselect then
+         osc_visible(false)
+PATCH
+then
+    echo "patch-modernz: failed to apply patch to $TARGET" >&2
+    exit 1
+fi
+
+echo "patch-modernz: patched $TARGET"
--- a/scripts/patch-modernz.test.ts
+++ b/scripts/patch-modernz.test.ts
@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+
+function withTempDir<T>(fn: (dir: string) => T): T {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-patch-modernz-test-'));
+  try {
+    return fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function writeExecutable(filePath: string, contents: string): void {
+  fs.writeFileSync(filePath, contents, 'utf8');
+  fs.chmodSync(filePath, 0o755);
+}
+
+test('patch-modernz rejects a missing --target value', () => {
+  withTempDir((root) => {
+    const result = spawnSync('bash', ['scripts/patch-modernz.sh', '--target'], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        HOME: path.join(root, 'home'),
+      },
+    });
+
+    assert.equal(result.status, 1, result.stderr || result.stdout);
+    assert.match(result.stderr, /--target requires a non-empty file path/);
+    assert.match(result.stderr, /Usage: patch-modernz\.sh/);
+  });
+});
+
+test('patch-modernz reports patch failures explicitly', () => {
+  withTempDir((root) => {
+    const binDir = path.join(root, 'bin');
+    const target = path.join(root, 'modernz.lua');
+    const patchLog = path.join(root, 'patch.log');
+
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, 'original', 'utf8');
+
+    writeExecutable(
+      path.join(binDir, 'patch'),
+      `#!/usr/bin/env bash
+set -euo pipefail
+cat > "${patchLog}"
+exit 1
+`,
+    );
+
+    const result = spawnSync(
+      'bash',
+      ['scripts/patch-modernz.sh', '--target', target],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: {
+          ...process.env,
+          HOME: path.join(root, 'home'),
+          PATH: `${binDir}:${process.env.PATH || ''}`,
+        },
+      },
+    );
+
+    assert.equal(result.status, 1, result.stderr || result.stdout);
+    assert.match(result.stderr, /failed to apply patch to/);
+    assert.equal(fs.readFileSync(patchLog, 'utf8').includes('modernz.lua'), true);
+  });
+});
--- a/src/config/definitions/defaults-subtitle.ts
+++ b/src/config/definitions/defaults-subtitle.ts
@@ -59,6 +59,7 @@ export const SUBTITLE_DEFAULT_CONFIG: Pick<ResolvedConfig, 'subtitleStyle' | 'su
  },
  subtitleSidebar: {
    enabled: false,
+    autoOpen: false,
    layout: 'overlay',
    toggleKey: 'Backslash',
    pauseVideoOnHover: false,
--- a/src/config/definitions/options-subtitle.ts
+++ b/src/config/definitions/options-subtitle.ts
@@ -116,9 +116,16 @@ export function buildSubtitleConfigOptionRegistry(
      defaultValue: defaultConfig.subtitleSidebar.enabled,
      description: 'Enable the subtitle sidebar feature for parsed subtitle sources.',
    },
+    {
+      path: 'subtitleSidebar.autoOpen',
+      kind: 'boolean',
+      defaultValue: defaultConfig.subtitleSidebar.autoOpen,
+      description: 'Automatically open the subtitle sidebar once during overlay startup.',
+    },
    {
      path: 'subtitleSidebar.layout',
-      kind: 'string',
+      kind: 'enum',
+      enumValues: ['overlay', 'embedded'],
      defaultValue: defaultConfig.subtitleSidebar.layout,
      description: 'Render the subtitle sidebar as a floating overlay or reserve space inside mpv.',
    },
--- a/src/config/resolve/shared.ts
+++ b/src/config/resolve/shared.ts
@@ -15,6 +15,22 @@ export function asBoolean(value: unknown): boolean | undefined {
 }

 const hexColorPattern = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const cssColorKeywords = new Set([
+  'transparent',
+  'currentcolor',
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+]);
+const cssColorFunctionPattern = /^(?:rgba?|hsla?)\(\s*[^()]+?\s*\)$/i;
+
+function supportsCssColor(text: string): boolean {
+  const css = (globalThis as { CSS?: { supports?: (property: string, value: string) => boolean } })
+    .CSS;
+  return css?.supports?.('color', text) ?? false;
+}

 export function asColor(value: unknown): string | undefined {
  if (typeof value !== 'string') return undefined;
@@ -22,6 +38,30 @@ export function asColor(value: unknown): string | undefined {
  return hexColorPattern.test(text) ? text : undefined;
 }

+export function asCssColor(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+
+  const text = value.trim();
+  if (text.length === 0) {
+    return undefined;
+  }
+
+  if (supportsCssColor(text)) {
+    return text;
+  }
+
+  const normalized = text.toLowerCase();
+  if (
+    hexColorPattern.test(text) ||
+    cssColorKeywords.has(normalized) ||
+    cssColorFunctionPattern.test(text)
+  ) {
+    return text;
+  }
+
+  return undefined;
+}
+
 export function asFrequencyBandedColors(
  value: unknown,
 ): [string, string, string, string, string] | undefined {
--- a/src/config/resolve/subtitle-domains.ts
+++ b/src/config/resolve/subtitle-domains.ts
@@ -3,6 +3,7 @@ import { ResolveContext } from './context';
 import {
  asBoolean,
  asColor,
+  asCssColor,
  asFrequencyBandedColors,
  asNumber,
  asString,
@@ -439,6 +440,19 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
      );
    }

+    const autoOpen = asBoolean((src.subtitleSidebar as { autoOpen?: unknown }).autoOpen);
+    if (autoOpen !== undefined) {
+      resolved.subtitleSidebar.autoOpen = autoOpen;
+    } else if ((src.subtitleSidebar as { autoOpen?: unknown }).autoOpen !== undefined) {
+      resolved.subtitleSidebar.autoOpen = fallback.autoOpen;
+      warn(
+        'subtitleSidebar.autoOpen',
+        (src.subtitleSidebar as { autoOpen?: unknown }).autoOpen,
+        resolved.subtitleSidebar.autoOpen,
+        'Expected boolean.',
+      );
+    }
+
    const layout = asString((src.subtitleSidebar as { layout?: unknown }).layout);
    if (layout === 'overlay' || layout === 'embedded') {
      resolved.subtitleSidebar.layout = layout;
@@ -507,7 +521,7 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
    }

    const opacity = asNumber((src.subtitleSidebar as { opacity?: unknown }).opacity);
-    if (opacity !== undefined && opacity > 0 && opacity <= 1) {
+    if (opacity !== undefined && opacity >= 0 && opacity <= 1) {
      resolved.subtitleSidebar.opacity = opacity;
    } else if ((src.subtitleSidebar as { opacity?: unknown }).opacity !== undefined) {
      resolved.subtitleSidebar.opacity = fallback.opacity;
@@ -541,16 +555,16 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
      'hoverLineBackgroundColor',
    ] as const;
    for (const field of cssColorFields) {
-      const value = asString((src.subtitleSidebar as Record<string, unknown>)[field]);
-      if (value !== undefined && value.trim().length > 0) {
-        resolved.subtitleSidebar[field] = value.trim();
+      const value = asCssColor((src.subtitleSidebar as Record<string, unknown>)[field]);
+      if (value !== undefined) {
+        resolved.subtitleSidebar[field] = value;
      } else if ((src.subtitleSidebar as Record<string, unknown>)[field] !== undefined) {
        resolved.subtitleSidebar[field] = fallback[field];
        warn(
          `subtitleSidebar.${field}`,
          (src.subtitleSidebar as Record<string, unknown>)[field],
          resolved.subtitleSidebar[field],
-          'Expected string.',
+          'Expected valid CSS color.',
        );
      }
    }
--- a/src/config/resolve/subtitle-sidebar.test.ts
+++ b/src/config/resolve/subtitle-sidebar.test.ts
@@ -7,6 +7,7 @@ test('subtitleSidebar resolves valid values and preserves dedicated defaults', (
  const { context } = createResolveContext({
    subtitleSidebar: {
      enabled: true,
+      autoOpen: true,
      layout: 'embedded',
      toggleKey: 'KeyB',
      pauseVideoOnHover: true,
@@ -27,6 +28,7 @@ test('subtitleSidebar resolves valid values and preserves dedicated defaults', (
  applySubtitleDomainConfig(context);

  assert.equal(context.resolved.subtitleSidebar.enabled, true);
+  assert.equal(context.resolved.subtitleSidebar.autoOpen, true);
  assert.equal(context.resolved.subtitleSidebar.layout, 'embedded');
  assert.equal(context.resolved.subtitleSidebar.toggleKey, 'KeyB');
  assert.equal(context.resolved.subtitleSidebar.pauseVideoOnHover, true);
@@ -37,30 +39,55 @@ test('subtitleSidebar resolves valid values and preserves dedicated defaults', (
  assert.equal(context.resolved.subtitleSidebar.fontSize, 17);
 });

+test('subtitleSidebar accepts zero opacity', () => {
+  const { context, warnings } = createResolveContext({
+    subtitleSidebar: {
+      opacity: 0,
+    },
+  });
+
+  applySubtitleDomainConfig(context);
+
+  assert.equal(context.resolved.subtitleSidebar.opacity, 0);
+  assert.equal(warnings.some((warning) => warning.path === 'subtitleSidebar.opacity'), false);
+});
+
 test('subtitleSidebar falls back and warns on invalid values', () => {
  const { context, warnings } = createResolveContext({
    subtitleSidebar: {
      enabled: 'yes' as never,
+      autoOpen: 'yes' as never,
      layout: 'floating' as never,
      maxWidth: -1,
      opacity: 5,
      fontSize: 0,
      textColor: 'blue',
+      backgroundColor: 'not-a-color',
    },
  });

  applySubtitleDomainConfig(context);

  assert.equal(context.resolved.subtitleSidebar.enabled, false);
+  assert.equal(context.resolved.subtitleSidebar.autoOpen, false);
  assert.equal(context.resolved.subtitleSidebar.layout, 'overlay');
  assert.equal(context.resolved.subtitleSidebar.maxWidth, 420);
  assert.equal(context.resolved.subtitleSidebar.opacity, 0.95);
  assert.equal(context.resolved.subtitleSidebar.fontSize, 16);
  assert.equal(context.resolved.subtitleSidebar.textColor, '#cad3f5');
+  assert.equal(context.resolved.subtitleSidebar.backgroundColor, 'rgba(73, 77, 100, 0.9)');
  assert.ok(warnings.some((warning) => warning.path === 'subtitleSidebar.enabled'));
+  assert.ok(warnings.some((warning) => warning.path === 'subtitleSidebar.autoOpen'));
  assert.ok(warnings.some((warning) => warning.path === 'subtitleSidebar.layout'));
  assert.ok(warnings.some((warning) => warning.path === 'subtitleSidebar.maxWidth'));
  assert.ok(warnings.some((warning) => warning.path === 'subtitleSidebar.opacity'));
  assert.ok(warnings.some((warning) => warning.path === 'subtitleSidebar.fontSize'));
  assert.ok(warnings.some((warning) => warning.path === 'subtitleSidebar.textColor'));
+  assert.ok(
+    warnings.some(
+      (warning) =>
+        warning.path === 'subtitleSidebar.backgroundColor' &&
+        warning.message === 'Expected valid CSS color.',
+    ),
+  );
 });
--- a/src/core/services/ipc.test.ts
+++ b/src/core/services/ipc.test.ts
@@ -84,6 +84,7 @@ function createSubtitleSidebarSnapshotFixture(): SubtitleSidebarSnapshot {
    currentSubtitle: { text: '', startTime: null, endTime: null },
    config: {
      enabled: false,
+      autoOpen: false,
      layout: 'overlay',
      toggleKey: 'Backslash',
      pauseVideoOnHover: false,
--- a/src/core/services/subtitle-cue-parser.test.ts
+++ b/src/core/services/subtitle-cue-parser.test.ts
@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { parseSrtCues, parseAssCues, parseSubtitleCues } from './subtitle-cue-parser';
-import type { SubtitleCue } from './subtitle-cue-parser';
+import type { SubtitleCue } from '../../types';

 test('parseSrtCues parses basic SRT content', () => {
  const content = [
--- a/src/core/services/subtitle-prefetch.test.ts
+++ b/src/core/services/subtitle-prefetch.test.ts
@@ -1,8 +1,8 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { computePriorityWindow, createSubtitlePrefetchService } from './subtitle-prefetch';
-import type { SubtitleCue } from './subtitle-cue-parser';
 import type { SubtitleData } from '../../types';
+import type { SubtitleCue } from '../../types';

 function makeCues(count: number, startOffset = 0): SubtitleCue[] {
  return Array.from({ length: count }, (_, i) => ({
--- a/src/core/services/subtitle-prefetch.ts
+++ b/src/core/services/subtitle-prefetch.ts
@@ -1,5 +1,5 @@
-import type { SubtitleCue } from './subtitle-cue-parser';
 import type { SubtitleData } from '../../types';
+import type { SubtitleCue } from '../../types';

 export interface SubtitlePrefetchServiceDeps {
  cues: SubtitleCue[];
--- a/src/main/runtime/subtitle-prefetch-init.test.ts
+++ b/src/main/runtime/subtitle-prefetch-init.test.ts
@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import type { SubtitleCue } from '../../core/services/subtitle-cue-parser';
 import type { SubtitlePrefetchService } from '../../core/services/subtitle-prefetch';
+import type { SubtitleCue } from '../../types';
 import { createSubtitlePrefetchInitController } from './subtitle-prefetch-init';

 function createDeferred<T>(): {
@@ -199,3 +199,38 @@ test('subtitle prefetch init publishes the provided stable source key instead of

  assert.deepEqual(sourceUpdates, ['internal:/media/episode01.mkv:track:3:ff:7']);
 });
+
+test('subtitle prefetch init clears parsed cues when initialization fails', async () => {
+  const cueUpdates: Array<SubtitleCue[] | null> = [];
+  let currentService: SubtitlePrefetchService | null = null;
+
+  const controller = createSubtitlePrefetchInitController({
+    getCurrentService: () => currentService,
+    setCurrentService: (service) => {
+      currentService = service;
+    },
+    loadSubtitleSourceText: async () => {
+      throw new Error('boom');
+    },
+    parseSubtitleCues: () => [{ startTime: 1, endTime: 2, text: 'first' }],
+    createSubtitlePrefetchService: () => ({
+      start: () => {},
+      stop: () => {},
+      onSeek: () => {},
+      pause: () => {},
+      resume: () => {},
+    }),
+    tokenizeSubtitle: async () => null,
+    preCacheTokenization: () => {},
+    isCacheFull: () => false,
+    logInfo: () => {},
+    logWarn: () => {},
+    onParsedSubtitleCuesChanged: (cues) => {
+      cueUpdates.push(cues);
+    },
+  });
+
+  await controller.initSubtitlePrefetch('episode.ass', 12);
+
+  assert.deepEqual(cueUpdates, [null]);
+});
--- a/src/main/runtime/subtitle-prefetch-init.ts
+++ b/src/main/runtime/subtitle-prefetch-init.ts
@@ -1,9 +1,9 @@
-import type { SubtitleCue } from '../../core/services/subtitle-cue-parser';
 import type {
  SubtitlePrefetchService,
  SubtitlePrefetchServiceDeps,
 } from '../../core/services/subtitle-prefetch';
 import type { SubtitleData } from '../../types';
+import type { SubtitleCue } from '../../types';

 export interface SubtitlePrefetchInitControllerDeps {
  getCurrentService: () => SubtitlePrefetchService | null;
@@ -82,6 +82,7 @@ export function createSubtitlePrefetchInitController(
      );
    } catch (error) {
      if (revision === initRevision) {
+        deps.onParsedSubtitleCuesChanged?.(null, null);
        deps.logWarn(`[subtitle-prefetch] failed to initialize: ${(error as Error).message}`);
      }
    }
--- a/src/main/state.ts
+++ b/src/main/state.ts
@@ -5,11 +5,11 @@ import type {
  MpvSubtitleRenderMetrics,
  SecondarySubMode,
  SubtitleData,
-  SubtitleCue,
  SubtitlePosition,
  KikuFieldGroupingChoice,
  JlptLevel,
  FrequencyDictionaryLookup,
+  SubtitleCue,
 } from '../types';
 import type { CliArgs } from '../cli/args';
 import type { SubtitleTimingTracker } from '../subtitle-timing-tracker';
--- a/src/release-workflow.test.ts
+++ b/src/release-workflow.test.ts
@@ -10,6 +10,9 @@ const makefile = readFileSync(makefilePath, 'utf8');
 const packageJsonPath = resolve(__dirname, '../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
  scripts: Record<string, string>;
+  build?: {
+    files?: string[];
+  };
 };

 test('publish release leaves prerelease unset so gh creates a normal release', () => {
@@ -65,6 +68,18 @@ test('release package scripts disable implicit electron-builder publishing', ()
  assert.match(packageJson.scripts['build:win:unsigned'] ?? '', /build-win-unsigned\.mjs/);
 });

+test('release packaging keeps default file inclusion and excludes large source-only trees explicitly', () => {
+  const files = packageJson.build?.files ?? [];
+  assert.ok(files.includes('**/*'));
+  assert.ok(files.includes('!src{,/**/*}'));
+  assert.ok(files.includes('!launcher{,/**/*}'));
+  assert.ok(files.includes('!stats/src{,/**/*}'));
+  assert.ok(files.includes('!.tmp{,/**/*}'));
+  assert.ok(files.includes('!release-*{,/**/*}'));
+  assert.ok(files.includes('!vendor/subminer-yomitan{,/**/*}'));
+  assert.ok(files.includes('!vendor/texthooker-ui/src{,/**/*}'));
+});
+
 test('config example generation runs directly from source without unrelated bundle prerequisites', () => {
  assert.equal(
    packageJson.scripts['generate:config-example'],
--- a/src/renderer/handlers/mouse.test.ts
+++ b/src/renderer/handlers/mouse.test.ts
@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';

+import type { SubtitleSidebarConfig } from '../../types';
 import { createMouseHandlers } from './mouse.js';
 import { YOMITAN_POPUP_HIDDEN_EVENT, YOMITAN_POPUP_SHOWN_EVENT } from '../yomitan-popup.js';

@@ -39,6 +40,7 @@ function createMouseTestContext() {
  const overlayClassList = createClassList();
  const subtitleRootClassList = createClassList();
  const subtitleContainerClassList = createClassList();
+  const secondarySubContainerClassList = createClassList();

  const ctx = {
    dom: {
@@ -54,6 +56,7 @@ function createMouseTestContext() {
        addEventListener: () => {},
      },
      secondarySubContainer: {
+        classList: secondarySubContainerClassList,
        addEventListener: () => {},
      },
    },
@@ -63,6 +66,9 @@ function createMouseTestContext() {
    },
    state: {
      isOverSubtitle: false,
+      isOverSubtitleSidebar: false,
+      subtitleSidebarModalOpen: false,
+      subtitleSidebarConfig: null as SubtitleSidebarConfig | null,
      isDragging: false,
      dragStartY: 0,
      startYPercent: 0,
@@ -72,7 +78,7 @@ function createMouseTestContext() {
  return ctx;
 }

-test('auto-pause on subtitle hover pauses on enter and resumes on leave when enabled', async () => {
+test('secondary hover pauses on enter, reveals secondary subtitle, and resumes on leave when enabled', async () => {
  const ctx = createMouseTestContext();
  const mpvCommands: Array<(string | number)[]> = [];

@@ -92,8 +98,10 @@ test('auto-pause on subtitle hover pauses on enter and resumes on leave when ena
    },
  });

-  await handlers.handleMouseEnter();
-  await handlers.handleMouseLeave();
+  await handlers.handleSecondaryMouseEnter();
+  assert.equal(ctx.dom.secondarySubContainer.classList.contains('secondary-sub-hover-active'), true);
+  await handlers.handleSecondaryMouseLeave();
+  assert.equal(ctx.dom.secondarySubContainer.classList.contains('secondary-sub-hover-active'), false);

  assert.deepEqual(mpvCommands, [
    ['set_property', 'pause', 'yes'],
@@ -101,6 +109,68 @@ test('auto-pause on subtitle hover pauses on enter and resumes on leave when ena
  ]);
 });

+test('moving between primary and secondary subtitle containers keeps the hover pause active', async () => {
+  const ctx = createMouseTestContext();
+  const mpvCommands: Array<(string | number)[]> = [];
+
+  const handlers = createMouseHandlers(ctx as never, {
+    modalStateReader: {
+      isAnySettingsModalOpen: () => false,
+      isAnyModalOpen: () => false,
+    },
+    applyYPercent: () => {},
+    getCurrentYPercent: () => 10,
+    persistSubtitlePositionPatch: () => {},
+    getSubtitleHoverAutoPauseEnabled: () => true,
+    getYomitanPopupAutoPauseEnabled: () => false,
+    getPlaybackPaused: async () => false,
+    sendMpvCommand: (command) => {
+      mpvCommands.push(command);
+    },
+  });
+
+  await handlers.handleSecondaryMouseEnter();
+  await handlers.handleSecondaryMouseLeave({
+    relatedTarget: ctx.dom.subtitleContainer,
+  } as unknown as MouseEvent);
+  await handlers.handlePrimaryMouseEnter({
+    relatedTarget: ctx.dom.secondarySubContainer,
+  } as unknown as MouseEvent);
+
+  assert.equal(ctx.state.isOverSubtitle, true);
+  assert.deepEqual(mpvCommands, [['set_property', 'pause', 'yes']]);
+});
+
+test('secondary leave toward primary subtitle container clears the secondary hover class', async () => {
+  const ctx = createMouseTestContext();
+  const mpvCommands: Array<(string | number)[]> = [];
+
+  const handlers = createMouseHandlers(ctx as never, {
+    modalStateReader: {
+      isAnySettingsModalOpen: () => false,
+      isAnyModalOpen: () => false,
+    },
+    applyYPercent: () => {},
+    getCurrentYPercent: () => 10,
+    persistSubtitlePositionPatch: () => {},
+    getSubtitleHoverAutoPauseEnabled: () => true,
+    getYomitanPopupAutoPauseEnabled: () => false,
+    getPlaybackPaused: async () => false,
+    sendMpvCommand: (command) => {
+      mpvCommands.push(command);
+    },
+  });
+
+  await handlers.handleSecondaryMouseEnter();
+  await handlers.handleSecondaryMouseLeave({
+    relatedTarget: ctx.dom.subtitleContainer,
+  } as unknown as MouseEvent);
+
+  assert.equal(ctx.state.isOverSubtitle, false);
+  assert.equal(ctx.dom.secondarySubContainer.classList.contains('secondary-sub-hover-active'), false);
+  assert.deepEqual(mpvCommands, [['set_property', 'pause', 'yes']]);
+});
+
 test('auto-pause on subtitle hover skips when playback is already paused', async () => {
  const ctx = createMouseTestContext();
  const mpvCommands: Array<(string | number)[]> = [];
@@ -127,6 +197,36 @@ test('auto-pause on subtitle hover skips when playback is already paused', async
  assert.deepEqual(mpvCommands, []);
 });

+test('primary hover pauses on enter without revealing secondary subtitle', async () => {
+  const ctx = createMouseTestContext();
+  const mpvCommands: Array<(string | number)[]> = [];
+
+  const handlers = createMouseHandlers(ctx as never, {
+    modalStateReader: {
+      isAnySettingsModalOpen: () => false,
+      isAnyModalOpen: () => false,
+    },
+    applyYPercent: () => {},
+    getCurrentYPercent: () => 10,
+    persistSubtitlePositionPatch: () => {},
+    getSubtitleHoverAutoPauseEnabled: () => true,
+    getYomitanPopupAutoPauseEnabled: () => false,
+    getPlaybackPaused: async () => false,
+    sendMpvCommand: (command) => {
+      mpvCommands.push(command);
+    },
+  });
+
+  await handlers.handlePrimaryMouseEnter();
+  assert.equal(ctx.dom.secondarySubContainer.classList.contains('secondary-sub-hover-active'), false);
+  await handlers.handlePrimaryMouseLeave();
+
+  assert.deepEqual(mpvCommands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+});
+
 test('auto-pause on subtitle hover is skipped when disabled in config', async () => {
  const ctx = createMouseTestContext();
  const mpvCommands: Array<(string | number)[]> = [];
@@ -153,6 +253,67 @@ test('auto-pause on subtitle hover is skipped when disabled in config', async ()
  assert.deepEqual(mpvCommands, []);
 });

+test('subtitle leave restores passthrough while embedded sidebar is open but not hovered', async () => {
+  const ctx = createMouseTestContext();
+  const ignoreMouseCalls: Array<[boolean, { forward?: boolean } | undefined]> = [];
+  const previousWindow = (globalThis as { window?: unknown }).window;
+
+  ctx.platform.shouldToggleMouseIgnore = true;
+  ctx.state.isOverSubtitle = true;
+  ctx.state.subtitleSidebarModalOpen = true;
+  ctx.state.subtitleSidebarConfig = {
+    enabled: true,
+    autoOpen: false,
+    layout: 'embedded',
+    toggleKey: 'Backslash',
+    pauseVideoOnHover: false,
+    autoScroll: true,
+    maxWidth: 360,
+    opacity: 0.92,
+    backgroundColor: 'rgba(54, 58, 79, 0.88)',
+    textColor: '#cad3f5',
+    fontFamily: '"Iosevka Aile", sans-serif',
+    fontSize: 17,
+    timestampColor: '#a5adcb',
+    activeLineColor: '#f5bde6',
+    activeLineBackgroundColor: 'rgba(138, 173, 244, 0.22)',
+    hoverLineBackgroundColor: 'rgba(54, 58, 79, 0.84)',
+  };
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: {
+      electronAPI: {
+        setIgnoreMouseEvents: (ignore: boolean, options?: { forward?: boolean }) => {
+          ignoreMouseCalls.push([ignore, options]);
+        },
+      },
+    },
+  });
+
+  try {
+    const handlers = createMouseHandlers(ctx as never, {
+      modalStateReader: {
+        isAnySettingsModalOpen: () => false,
+        isAnyModalOpen: () => true,
+      },
+      applyYPercent: () => {},
+      getCurrentYPercent: () => 10,
+      persistSubtitlePositionPatch: () => {},
+      getSubtitleHoverAutoPauseEnabled: () => false,
+      getYomitanPopupAutoPauseEnabled: () => false,
+      getPlaybackPaused: async () => false,
+      sendMpvCommand: () => {},
+    });
+
+    await handlers.handlePrimaryMouseLeave();
+
+    assert.deepEqual(ignoreMouseCalls.at(-1), [true, { forward: true }]);
+  } finally {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+  }
+});
+
 test('pending hover pause check is ignored when mouse leaves before pause state resolves', async () => {
  const ctx = createMouseTestContext();
  const mpvCommands: Array<(string | number)[]> = [];
--- a/src/renderer/handlers/mouse.ts
+++ b/src/renderer/handlers/mouse.ts
@@ -1,4 +1,5 @@
 import type { ModalStateReader, RendererContext } from '../context';
+import { syncOverlayMouseIgnoreState } from '../overlay-mouse-ignore.js';
 import {
  YOMITAN_POPUP_HIDDEN_EVENT,
  YOMITAN_POPUP_SHOWN_EVENT,
@@ -25,6 +26,19 @@ export function createMouseHandlers(
  let pausedBySubtitleHover = false;
  let pausedByYomitanPopup = false;

+  function isWithinOtherSubtitleContainer(
+    relatedTarget: EventTarget | null,
+    otherContainer: HTMLElement,
+  ): boolean {
+    if (relatedTarget === otherContainer) {
+      return true;
+    }
+    if (typeof Node !== 'undefined' && relatedTarget instanceof Node) {
+      return otherContainer.contains(relatedTarget);
+    }
+    return false;
+  }
+
  function maybeResumeHoverPause(): void {
    if (!pausedBySubtitleHover) return;
    if (pausedByYomitanPopup) return;
@@ -80,10 +94,7 @@ export function createMouseHandlers(
  function enablePopupInteraction(): void {
    yomitanPopupVisible = true;
    ctx.state.yomitanPopupVisible = true;
-    ctx.dom.overlay.classList.add('interactive');
-    if (ctx.platform.shouldToggleMouseIgnore) {
-      window.electronAPI.setIgnoreMouseEvents(false);
-    }
+    syncOverlayMouseIgnoreState(ctx);
    if (ctx.platform.isMacOSPlatform) {
      window.focus();
    }
@@ -101,20 +112,18 @@ export function createMouseHandlers(
    popupPauseRequestId += 1;
    maybeResumeYomitanPopupPause();
    maybeResumeHoverPause();
-    if (!ctx.state.isOverSubtitle && !options.modalStateReader.isAnyModalOpen()) {
-      ctx.dom.overlay.classList.remove('interactive');
-      if (ctx.platform.shouldToggleMouseIgnore) {
-        window.electronAPI.setIgnoreMouseEvents(true, { forward: true });
-      }
-    }
+    syncOverlayMouseIgnoreState(ctx);
  }

-  async function handleMouseEnter(): Promise<void> {
+  async function handleMouseEnter(
+    _event?: MouseEvent,
+    showSecondaryHover = false,
+  ): Promise<void> {
    ctx.state.isOverSubtitle = true;
-    ctx.dom.overlay.classList.add('interactive');
-    if (ctx.platform.shouldToggleMouseIgnore) {
-      window.electronAPI.setIgnoreMouseEvents(false);
+    if (showSecondaryHover) {
+      ctx.dom.secondarySubContainer.classList.add('secondary-sub-hover-active');
    }
+    syncOverlayMouseIgnoreState(ctx);

    if (yomitanPopupVisible && options.getYomitanPopupAutoPauseEnabled()) {
      return;
@@ -124,6 +133,10 @@ export function createMouseHandlers(
      return;
    }

+    if (pausedBySubtitleHover) {
+      return;
+    }
+
    const requestId = ++hoverPauseRequestId;
    let paused: boolean | null = null;
    try {
@@ -141,8 +154,26 @@ export function createMouseHandlers(
    pausedBySubtitleHover = true;
  }

-  async function handleMouseLeave(): Promise<void> {
+  async function handleMouseLeave(
+    _event?: MouseEvent,
+    hideSecondaryHover = false,
+  ): Promise<void> {
+    const relatedTarget = _event?.relatedTarget ?? null;
+    const otherContainer = hideSecondaryHover
+      ? ctx.dom.subtitleContainer
+      : ctx.dom.secondarySubContainer;
+    if (relatedTarget && isWithinOtherSubtitleContainer(relatedTarget, otherContainer)) {
      ctx.state.isOverSubtitle = false;
+      if (hideSecondaryHover) {
+        ctx.dom.secondarySubContainer.classList.remove('secondary-sub-hover-active');
+      }
+      return;
+    }
+
+    ctx.state.isOverSubtitle = false;
+    if (hideSecondaryHover) {
+      ctx.dom.secondarySubContainer.classList.remove('secondary-sub-hover-active');
+    }
    hoverPauseRequestId += 1;
    maybeResumeHoverPause();
    if (yomitanPopupVisible) return;
@@ -246,6 +277,10 @@ export function createMouseHandlers(
  }

  return {
+    handlePrimaryMouseEnter: (event?: MouseEvent) => handleMouseEnter(event, false),
+    handlePrimaryMouseLeave: (event?: MouseEvent) => handleMouseLeave(event, false),
+    handleSecondaryMouseEnter: (event?: MouseEvent) => handleMouseEnter(event, true),
+    handleSecondaryMouseLeave: (event?: MouseEvent) => handleMouseLeave(event, true),
    handleMouseEnter,
    handleMouseLeave,
    setupDragging,
--- a/src/renderer/modals/subtitle-sidebar.test.ts
+++ b/src/renderer/modals/subtitle-sidebar.test.ts
--- a/src/renderer/modals/subtitle-sidebar.ts
+++ b/src/renderer/modals/subtitle-sidebar.ts
@@ -4,6 +4,7 @@ import type {
  SubtitleSidebarSnapshot,
 } from '../../types';
 import type { ModalStateReader, RendererContext } from '../context';
+import { syncOverlayMouseIgnoreState } from '../overlay-mouse-ignore.js';

 const MANUAL_SCROLL_HOLD_MS = 1500;
 const ACTIVE_CUE_LOOKAHEAD_SEC = 0.18;
@@ -11,7 +12,6 @@ const CLICK_SEEK_OFFSET_SEC = 0.08;
 const SNAPSHOT_POLL_INTERVAL_MS = 80;
 const EMBEDDED_SIDEBAR_MIN_WIDTH_PX = 240;
 const EMBEDDED_SIDEBAR_MAX_RATIO = 0.45;
-
 function subtitleCueListsEqual(a: SubtitleCue[], b: SubtitleCue[]): boolean {
  if (a.length !== b.length) {
    return false;
@@ -38,8 +38,16 @@ function normalizeCueText(text: string): string {

 function formatCueTimestamp(seconds: number): string {
  const totalSeconds = Math.max(0, Math.floor(seconds));
-  const mins = Math.floor(totalSeconds / 60);
+  const hours = Math.floor(totalSeconds / 3600);
+  const mins = Math.floor((totalSeconds % 3600) / 60);
  const secs = totalSeconds % 60;
+  if (hours > 0) {
+    return [
+      String(hours).padStart(2, '0'),
+      String(mins).padStart(2, '0'),
+      String(secs).padStart(2, '0'),
+    ].join(':');
+  }
  return `${String(mins).padStart(2, '0')}:${String(secs).padStart(2, '0')}`;
 }

@@ -107,8 +115,11 @@ export function findActiveSubtitleCueIndex(
      if (forwardMatches.length > 0) {
        return forwardMatches[0]!;
      }
+      if (matchingIndices.includes(preferredCueIndex)) {
        return preferredCueIndex;
      }
+      return matchingIndices[matchingIndices.length - 1] ?? -1;
+    }

    let nearestIndex = matchingIndices[0]!;
    let nearestDistance = Math.abs(nearestIndex - preferredCueIndex);
@@ -131,8 +142,14 @@ export function createSubtitleSidebarModal(
    modalStateReader: Pick<ModalStateReader, 'isAnyModalOpen'>;
  },
 ) {
-  let snapshotPollInterval: ReturnType<typeof setInterval> | null = null;
+  let snapshotPollInterval: ReturnType<typeof setTimeout> | null = null;
  let lastAppliedVideoMarginRatio: number | null = null;
+  let subtitleSidebarHoverRequestId = 0;
+  let disposeDomEvents: (() => void) | null = null;
+
+  function restoreEmbeddedSidebarPassthrough(): void {
+    syncOverlayMouseIgnoreState(ctx);
+  }

  function setStatus(message: string): void {
    ctx.dom.subtitleSidebarStatus.textContent = message;
@@ -154,10 +171,11 @@ export function createSubtitleSidebarModal(

  function syncEmbeddedSidebarLayout(): void {
    const config = ctx.state.subtitleSidebarConfig;
-    const reservedWidthPx = getReservedSidebarWidthPx();
-    const embedded = Boolean(config && config.layout === 'embedded' && reservedWidthPx > 0);
+    const wantsEmbedded = Boolean(
+      config && config.layout === 'embedded' && ctx.state.subtitleSidebarModalOpen,
+    );

-    if (embedded) {
+    if (wantsEmbedded) {
      ctx.dom.subtitleSidebarContent.classList.add('subtitle-sidebar-content-embedded');
      ctx.dom.subtitleSidebarModal.classList.add('subtitle-sidebar-modal-embedded');
      document.body.classList.add('subtitle-sidebar-embedded-open');
@@ -166,6 +184,8 @@ export function createSubtitleSidebarModal(
      ctx.dom.subtitleSidebarModal.classList.remove('subtitle-sidebar-modal-embedded');
      document.body.classList.remove('subtitle-sidebar-embedded-open');
    }
+    const reservedWidthPx = wantsEmbedded ? getReservedSidebarWidthPx() : 0;
+    const embedded = wantsEmbedded && reservedWidthPx > 0;
    document.documentElement.style.setProperty(
      '--subtitle-sidebar-reserved-width',
      `${Math.max(0, Math.round(reservedWidthPx))}px`,
@@ -190,6 +210,26 @@ export function createSubtitleSidebarModal(
      'video-margin-ratio-right',
      Number(ratio.toFixed(4)),
    ]);
+    window.electronAPI.sendMpvCommand([
+      'set_property',
+      'osd-align-x',
+      'left',
+    ]);
+    window.electronAPI.sendMpvCommand([
+      'set_property',
+      'osd-align-y',
+      'top',
+    ]);
+    window.electronAPI.sendMpvCommand([
+      'set_property',
+      'user-data/osc/margins',
+      JSON.stringify({
+        l: 0,
+        r: Number(ratio.toFixed(4)),
+        t: 0,
+        b: 0,
+      }),
+    ]);
    if (ratio === 0) {
      window.electronAPI.sendMpvCommand(['set_property', 'video-pan-x', 0]);
    }
@@ -228,6 +268,22 @@ export function createSubtitleSidebarModal(
    ]);
  }

+  function getCueRowLabel(cue: SubtitleCue): string {
+    return `Jump to subtitle at ${formatCueTimestamp(cue.startTime)}`;
+  }
+
+  function resumeSubtitleSidebarHoverPause(): void {
+    subtitleSidebarHoverRequestId += 1;
+    if (!ctx.state.subtitleSidebarPausedByHover) {
+      restoreEmbeddedSidebarPassthrough();
+      return;
+    }
+
+    ctx.state.subtitleSidebarPausedByHover = false;
+    window.electronAPI.sendMpvCommand(['set_property', 'pause', 'no']);
+    restoreEmbeddedSidebarPassthrough();
+  }
+
  function maybeAutoScrollActiveCue(
    previousActiveCueIndex: number,
    behavior: ScrollBehavior = 'smooth',
@@ -250,8 +306,14 @@ export function createSubtitleSidebarModal(

    const targetScrollTop =
      active.offsetTop - (list.clientHeight - active.clientHeight) / 2;
+    const nextScrollTop = Math.max(0, targetScrollTop);
+    if (previousActiveCueIndex < 0) {
+      list.scrollTop = nextScrollTop;
+      return;
+    }
+
    list.scrollTo({
-      top: Math.max(0, targetScrollTop),
+      top: nextScrollTop,
      behavior,
    });
  }
@@ -263,6 +325,16 @@ export function createSubtitleSidebarModal(
      row.className = 'subtitle-sidebar-item';
      row.classList.toggle('active', index === ctx.state.subtitleSidebarActiveCueIndex);
      row.dataset.index = String(index);
+      row.tabIndex = 0;
+      row.setAttribute('role', 'button');
+      row.setAttribute('aria-label', getCueRowLabel(cue));
+      row.addEventListener('keydown', (event: KeyboardEvent) => {
+        if (event.key !== 'Enter' && event.key !== ' ') {
+          return;
+        }
+        event.preventDefault();
+        seekToCue(cue);
+      });

      const timestamp = document.createElement('div');
      timestamp.className = 'subtitle-sidebar-timestamp';
@@ -315,6 +387,23 @@ export function createSubtitleSidebarModal(
  async function refreshSnapshot(): Promise<SubtitleSidebarSnapshot> {
    const snapshot = await window.electronAPI.getSubtitleSidebarSnapshot();
    applyConfig(snapshot);
+    if (!snapshot.config.enabled) {
+      resumeSubtitleSidebarHoverPause();
+      ctx.state.subtitleSidebarCues = [];
+      ctx.state.subtitleSidebarModalOpen = false;
+      ctx.dom.subtitleSidebarModal.classList.add('hidden');
+      ctx.dom.subtitleSidebarModal.setAttribute('aria-hidden', 'true');
+      stopSnapshotPolling();
+      updateActiveCue(null, snapshot.currentTimeSec ?? null);
+      setStatus('Subtitle sidebar disabled in config.');
+      syncEmbeddedSidebarLayout();
+      if (!ctx.state.isOverSubtitle && !options.modalStateReader.isAnyModalOpen()) {
+        ctx.dom.overlay.classList.remove('interactive');
+      }
+      restoreEmbeddedSidebarPassthrough();
+      return snapshot;
+    }
+
    const cuesChanged = !subtitleCueListsEqual(ctx.state.subtitleSidebarCues, snapshot.cues);
    if (cuesChanged) {
      ctx.state.subtitleSidebarCues = snapshot.cues;
@@ -328,34 +417,50 @@ export function createSubtitleSidebarModal(
  }

  function startSnapshotPolling(): void {
-    if (snapshotPollInterval) {
-      clearInterval(snapshotPollInterval);
+    stopSnapshotPolling();
+
+    const pollOnce = async (): Promise<void> => {
+      try {
+        await refreshSnapshot();
+      } catch {
+        // Keep polling; a transient IPC failure should not stop updates.
      }
-    snapshotPollInterval = setInterval(() => {
-      void refreshSnapshot();
-    }, SNAPSHOT_POLL_INTERVAL_MS);
+
+      if (!ctx.state.subtitleSidebarModalOpen) {
+        snapshotPollInterval = null;
+        return;
+      }
+
+      snapshotPollInterval = setTimeout(pollOnce, SNAPSHOT_POLL_INTERVAL_MS);
+    };
+
+    snapshotPollInterval = setTimeout(pollOnce, SNAPSHOT_POLL_INTERVAL_MS);
  }

  function stopSnapshotPolling(): void {
    if (!snapshotPollInterval) {
      return;
    }
-    clearInterval(snapshotPollInterval);
+    clearTimeout(snapshotPollInterval);
    snapshotPollInterval = null;
  }

  async function openSubtitleSidebarModal(): Promise<void> {
    const snapshot = await refreshSnapshot();
-    ctx.dom.subtitleSidebarList.innerHTML = '';
    if (!snapshot.config.enabled) {
      setStatus('Subtitle sidebar disabled in config.');
-    } else if (snapshot.cues.length === 0) {
+      return;
+    }
+
+    ctx.dom.subtitleSidebarList.innerHTML = '';
+    if (snapshot.cues.length === 0) {
      setStatus('No parsed subtitle cues available.');
    } else {
      setStatus(`${snapshot.cues.length} parsed subtitle lines`);
    }

    ctx.state.subtitleSidebarModalOpen = true;
+    ctx.state.isOverSubtitleSidebar = false;
    ctx.dom.subtitleSidebarModal.classList.remove('hidden');
    ctx.dom.subtitleSidebarModal.setAttribute('aria-hidden', 'false');
    renderCueList();
@@ -363,12 +468,23 @@ export function createSubtitleSidebarModal(
    maybeAutoScrollActiveCue(-1, 'auto', true);
    startSnapshotPolling();
    syncEmbeddedSidebarLayout();
+    restoreEmbeddedSidebarPassthrough();
+  }
+
+  async function autoOpenSubtitleSidebarOnStartup(): Promise<void> {
+    const snapshot = await refreshSnapshot();
+    if (!snapshot.config.enabled || !snapshot.config.autoOpen || ctx.state.subtitleSidebarModalOpen) {
+      return;
+    }
+    await openSubtitleSidebarModal();
  }

  function closeSubtitleSidebarModal(): void {
    if (!ctx.state.subtitleSidebarModalOpen) {
      return;
    }
+    resumeSubtitleSidebarHoverPause();
+    ctx.state.isOverSubtitleSidebar = false;
    ctx.state.subtitleSidebarModalOpen = false;
    ctx.dom.subtitleSidebarModal.classList.add('hidden');
    ctx.dom.subtitleSidebarModal.setAttribute('aria-hidden', 'true');
@@ -377,6 +493,7 @@ export function createSubtitleSidebarModal(
    if (!ctx.state.isOverSubtitle && !options.modalStateReader.isAnyModalOpen()) {
      ctx.dom.overlay.classList.remove('interactive');
    }
+    restoreEmbeddedSidebarPassthrough();
  }

  async function toggleSubtitleSidebarModal(): Promise<void> {
@@ -399,6 +516,10 @@ export function createSubtitleSidebarModal(
  }

  function wireDomEvents(): void {
+    if (disposeDomEvents) {
+      return;
+    }
+
    ctx.dom.subtitleSidebarClose.addEventListener('click', () => {
      closeSubtitleSidebarModal();
    });
@@ -425,36 +546,53 @@ export function createSubtitleSidebarModal(
      ctx.state.subtitleSidebarManualScrollUntilMs = Date.now() + MANUAL_SCROLL_HOLD_MS;
    });
    ctx.dom.subtitleSidebarModal.addEventListener('mouseenter', async () => {
+      ctx.state.isOverSubtitleSidebar = true;
+      restoreEmbeddedSidebarPassthrough();
      if (!ctx.state.subtitleSidebarPauseVideoOnHover || ctx.state.subtitleSidebarPausedByHover) {
        return;
      }
-      const paused = await window.electronAPI.getPlaybackPaused();
+      const requestId = ++subtitleSidebarHoverRequestId;
+      let paused: boolean | null | undefined;
+      try {
+        paused = await window.electronAPI.getPlaybackPaused();
+      } catch {
+        paused = undefined;
+      }
+      if (requestId !== subtitleSidebarHoverRequestId) {
+        return;
+      }
      if (paused === false) {
        window.electronAPI.sendMpvCommand(['set_property', 'pause', 'yes']);
        ctx.state.subtitleSidebarPausedByHover = true;
      }
    });
    ctx.dom.subtitleSidebarModal.addEventListener('mouseleave', () => {
-      if (!ctx.state.subtitleSidebarPausedByHover) {
-        return;
-      }
-      ctx.state.subtitleSidebarPausedByHover = false;
-      window.electronAPI.sendMpvCommand(['set_property', 'pause', 'no']);
+      ctx.state.isOverSubtitleSidebar = false;
+      resumeSubtitleSidebarHoverPause();
    });
-    window.addEventListener('resize', () => {
+    const resizeHandler = () => {
      if (!ctx.state.subtitleSidebarModalOpen) {
        return;
      }
      syncEmbeddedSidebarLayout();
-    });
+    };
+    window.addEventListener('resize', resizeHandler);
+    disposeDomEvents = () => {
+      window.removeEventListener('resize', resizeHandler);
+      disposeDomEvents = null;
+    };
  }

  return {
+    autoOpenSubtitleSidebarOnStartup,
    openSubtitleSidebarModal,
    closeSubtitleSidebarModal,
    toggleSubtitleSidebarModal,
    refreshSubtitleSidebarSnapshot: refreshSnapshot,
    wireDomEvents,
+    disposeDomEvents: () => {
+      disposeDomEvents?.();
+    },
    handleSubtitleUpdated,
    seekToCue,
  };
--- a/src/renderer/overlay-mouse-ignore.ts
+++ b/src/renderer/overlay-mouse-ignore.ts
@@ -0,0 +1,42 @@
+import type { RendererContext } from './context';
+import type { RendererState } from './state';
+
+function isBlockingOverlayModalOpen(state: RendererState): boolean {
+  const embeddedSidebarOpen =
+    state.subtitleSidebarModalOpen && state.subtitleSidebarConfig?.layout === 'embedded';
+
+  return Boolean(
+    state.controllerSelectModalOpen ||
+      state.controllerDebugModalOpen ||
+      state.jimakuModalOpen ||
+      state.kikuModalOpen ||
+      state.runtimeOptionsModalOpen ||
+      state.subsyncModalOpen ||
+      state.sessionHelpModalOpen ||
+      (state.subtitleSidebarModalOpen && !embeddedSidebarOpen),
+  );
+}
+
+export function syncOverlayMouseIgnoreState(ctx: RendererContext): void {
+  const shouldStayInteractive =
+    ctx.state.isOverSubtitle ||
+    ctx.state.isOverSubtitleSidebar ||
+    ctx.state.yomitanPopupVisible ||
+    isBlockingOverlayModalOpen(ctx.state);
+
+  if (shouldStayInteractive) {
+    ctx.dom.overlay.classList.add('interactive');
+  } else {
+    ctx.dom.overlay.classList.remove('interactive');
+  }
+  if (!ctx.platform?.shouldToggleMouseIgnore) {
+    return;
+  }
+
+  if (shouldStayInteractive) {
+    window.electronAPI.setIgnoreMouseEvents(false);
+    return;
+  }
+
+  window.electronAPI.setIgnoreMouseEvents(true, { forward: true });
+}
--- a/src/renderer/renderer.ts
+++ b/src/renderer/renderer.ts
@@ -39,6 +39,7 @@ import { createRuntimeOptionsModal } from './modals/runtime-options.js';
 import { createSubsyncModal } from './modals/subsync.js';
 import { createPositioningController } from './positioning.js';
 import { createOverlayContentMeasurementReporter } from './overlay-content-measurement.js';
+import { syncOverlayMouseIgnoreState } from './overlay-mouse-ignore.js';
 import { createRendererState } from './state.js';
 import { createSubtitleRenderer } from './subtitle-render.js';
 import { isYomitanPopupVisible, registerYomitanLookupListener } from './yomitan-popup.js';
@@ -521,10 +522,10 @@ async function init(): Promise<void> {
  subtitleRenderer.renderSecondarySub(await window.electronAPI.getCurrentSecondarySub());
  measurementReporter.schedule();

-  ctx.dom.subtitleContainer.addEventListener('mouseenter', mouseHandlers.handleMouseEnter);
-  ctx.dom.subtitleContainer.addEventListener('mouseleave', mouseHandlers.handleMouseLeave);
-  ctx.dom.secondarySubContainer.addEventListener('mouseenter', mouseHandlers.handleMouseEnter);
-  ctx.dom.secondarySubContainer.addEventListener('mouseleave', mouseHandlers.handleMouseLeave);
+  ctx.dom.subtitleContainer.addEventListener('mouseenter', mouseHandlers.handlePrimaryMouseEnter);
+  ctx.dom.subtitleContainer.addEventListener('mouseleave', mouseHandlers.handlePrimaryMouseLeave);
+  ctx.dom.secondarySubContainer.addEventListener('mouseenter', mouseHandlers.handleSecondaryMouseEnter);
+  ctx.dom.secondarySubContainer.addEventListener('mouseleave', mouseHandlers.handleSecondaryMouseLeave);

  mouseHandlers.setupResizeHandler();
  mouseHandlers.setupSelectionObserver();
@@ -542,6 +543,9 @@ async function init(): Promise<void> {
  controllerDebugModal.wireDomEvents();
  sessionHelpModal.wireDomEvents();
  subtitleSidebarModal.wireDomEvents();
+  window.addEventListener('beforeunload', () => {
+    subtitleSidebarModal.disposeDomEvents();
+  });

  window.electronAPI.onRuntimeOptionsChanged((options: RuntimeOptionState[]) => {
    runGuarded('runtime-options:changed', () => {
@@ -575,6 +579,7 @@ async function init(): Promise<void> {
  const initialSubtitleStyle = await window.electronAPI.getSubtitleStyle();
  subtitleRenderer.applySubtitleStyle(initialSubtitleStyle);
  await subtitleSidebarModal.refreshSubtitleSidebarSnapshot();
+  await subtitleSidebarModal.autoOpenSubtitleSidebarOnStartup();

  positioning.applyStoredSubtitlePosition(
    await window.electronAPI.getSubtitlePosition(),
@@ -583,7 +588,7 @@ async function init(): Promise<void> {
  measurementReporter.schedule();

  if (ctx.platform.shouldToggleMouseIgnore) {
-    window.electronAPI.setIgnoreMouseEvents(true, { forward: true });
+    syncOverlayMouseIgnoreState(ctx);
  }

  measurementReporter.emitNow();
--- a/src/renderer/state.ts
+++ b/src/renderer/state.ts
@@ -10,8 +10,8 @@ import type {
  RuntimeOptionState,
  RuntimeOptionValue,
  SubtitlePosition,
-  SubtitleCue,
  SubtitleSidebarConfig,
+  SubtitleCue,
  SubsyncSourceTrack,
 } from '../types';

@@ -25,6 +25,7 @@ export type ChordAction =

 export type RendererState = {
  isOverSubtitle: boolean;
+  isOverSubtitleSidebar: boolean;
  isDragging: boolean;
  dragStartY: number;
  startYPercent: number;
@@ -115,6 +116,7 @@ export type RendererState = {
 export function createRendererState(): RendererState {
  return {
    isOverSubtitle: false,
+    isOverSubtitleSidebar: false,
    isDragging: false,
    dragStartY: 0,
    startYPercent: 0,
--- a/src/renderer/style.css
+++ b/src/renderer/style.css
@@ -723,6 +723,7 @@ body.subtitle-sidebar-embedded-open #secondarySubContainer {
 #secondarySubContainer {
  --secondary-sub-background-color: transparent;
  --secondary-sub-backdrop-filter: none;
+
  position: absolute;
  top: 40px;
  left: 50%;
@@ -779,7 +780,11 @@ body.settings-modal-open #secondarySubContainer {
 }

 body.subtitle-sidebar-embedded-open #secondarySubContainer.secondary-sub-hover {
-  transform: translateX(calc(var(--subtitle-sidebar-reserved-width) * -0.5));
+  left: 0;
+  right: var(--subtitle-sidebar-reserved-width);
+  max-width: none;
+  padding-right: 0;
+  transform: none;
 }

 #secondarySubContainer.secondary-sub-hover {
@@ -808,11 +813,13 @@ body.subtitle-sidebar-embedded-open #secondarySubContainer.secondary-sub-hover {
  padding: 10px 18px;
 }

-#secondarySubContainer.secondary-sub-hover:hover {
+#secondarySubContainer.secondary-sub-hover:hover,
+#secondarySubContainer.secondary-sub-hover.secondary-sub-hover-active {
  opacity: 1;
 }

-#secondarySubContainer.secondary-sub-hover:hover #secondarySubRoot {
+#secondarySubContainer.secondary-sub-hover:hover #secondarySubRoot,
+#secondarySubContainer.secondary-sub-hover.secondary-sub-hover-active #secondarySubRoot {
  background: var(--secondary-sub-background-color, transparent);
  backdrop-filter: var(--secondary-sub-backdrop-filter, none);
  -webkit-backdrop-filter: var(--secondary-sub-backdrop-filter, none);
@@ -1490,7 +1497,6 @@ body.subtitle-sidebar-embedded-open #subtitleSidebarContent {
  min-height: 0;
  border-radius: 0;
  background: transparent;
-  scroll-behavior: smooth;
 }

 .subtitle-sidebar-list::-webkit-scrollbar {
@@ -1531,6 +1537,12 @@ body.subtitle-sidebar-embedded-open #subtitleSidebarContent {
  background: var(--subtitle-sidebar-hover-background-color, rgba(54, 58, 79, 0.65));
 }

+.subtitle-sidebar-item:focus-visible {
+  outline: 2px solid var(--subtitle-sidebar-active-line-color, #f5bde6);
+  outline-offset: -2px;
+  background: var(--subtitle-sidebar-hover-background-color, rgba(54, 58, 79, 0.65));
+}
+
 .subtitle-sidebar-item.active {
  background: var(--subtitle-sidebar-active-background-color, rgba(138, 173, 244, 0.12));
 }
--- a/src/renderer/subtitle-render.test.ts
+++ b/src/renderer/subtitle-render.test.ts
@@ -977,6 +977,30 @@ test('JLPT CSS rules use underline-only styling in renderer stylesheet', () => {
  );
  assert.match(secondaryHoverBaseBlock, /background:\s*transparent;/);

+  const secondaryEmbeddedHoverBlock = extractClassBlock(
+    cssText,
+    'body.subtitle-sidebar-embedded-open #secondarySubContainer.secondary-sub-hover',
+  );
+  assert.match(
+    secondaryEmbeddedHoverBlock,
+    /right:\s*var\(--subtitle-sidebar-reserved-width\);/,
+  );
+  assert.match(
+    secondaryEmbeddedHoverBlock,
+    /max-width:\s*none;/,
+  );
+  assert.match(
+    secondaryEmbeddedHoverBlock,
+    /transform:\s*none;/,
+  );
+  assert.doesNotMatch(
+    secondaryEmbeddedHoverBlock,
+    /transform:\s*translateX\(calc\(var\(--subtitle-sidebar-reserved-width\)\s*\*\s*-0\.5\)\);/,
+  );
+
+  const subtitleSidebarListBlock = extractClassBlock(cssText, '.subtitle-sidebar-list');
+  assert.doesNotMatch(subtitleSidebarListBlock, /scroll-behavior:\s*smooth;/);
+
  const secondaryHoverVisibleBlock = extractClassBlock(
    cssText,
    '#secondarySubContainer.secondary-sub-hover:hover #secondarySubRoot',
@@ -990,6 +1014,25 @@ test('JLPT CSS rules use underline-only styling in renderer stylesheet', () => {
    /backdrop-filter:\s*var\(--secondary-sub-backdrop-filter,\s*none\);/,
  );

+  const secondaryHoverActiveBlock = extractClassBlock(
+    cssText,
+    '#secondarySubContainer.secondary-sub-hover.secondary-sub-hover-active',
+  );
+  assert.match(secondaryHoverActiveBlock, /opacity:\s*1;/);
+
+  const secondaryHoverActiveRootBlock = extractClassBlock(
+    cssText,
+    '#secondarySubContainer.secondary-sub-hover.secondary-sub-hover-active #secondarySubRoot',
+  );
+  assert.match(
+    secondaryHoverActiveRootBlock,
+    /background:\s*var\(--secondary-sub-background-color,\s*transparent\);/,
+  );
+  assert.match(
+    secondaryHoverActiveRootBlock,
+    /backdrop-filter:\s*var\(--secondary-sub-backdrop-filter,\s*none\);/,
+  );
+
  assert.doesNotMatch(
    cssText,
    /body\.layer-visible\s+#secondarySubContainer\s*\{[^}]*display:\s*none/i,
--- a/src/types.ts
+++ b/src/types.ts
@@ -16,6 +16,8 @@
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

+import type { SubtitleCue } from './core/services/subtitle-cue-parser';
+
 export enum PartOfSpeech {
  noun = 'noun',
  verb = 'verb',
@@ -364,16 +366,13 @@ export interface ResolvedTokenPos2ExclusionConfig {

 export type FrequencyDictionaryMode = 'single' | 'banded';

-export interface SubtitleCue {
-  startTime: number;
-  endTime: number;
-  text: string;
-}
+export type { SubtitleCue } from './core/services/subtitle-cue-parser';

 export type SubtitleSidebarLayout = 'overlay' | 'embedded';

 export interface SubtitleSidebarConfig {
  enabled?: boolean;
+  autoOpen?: boolean;
  layout?: SubtitleSidebarLayout;
  toggleKey?: string;
  pauseVideoOnHover?: boolean;
--- a/vendor/texthooker-ui
+++ b/vendor/texthooker-ui
Author	SHA1	Message	Date
sudacode	81daf79492	chore: add changelog fragment for subtitle sidebar changes	2026-03-21 23:33:33 -07:00
sudacode	5763650036	chore: regenerate release config example artifacts	2026-03-21 23:11:21 -07:00
sudacode	5ea064a446	fix: align subtitle sidebar state and behavior updates	2026-03-21 22:24:42 -07:00
sudacode	4c6e4b9f0b	chore: prepare v0.8.0 release metadata and changelog	2026-03-21 22:24:39 -07:00
sudacode	a9ad268393	fix(scripts): harden patch-modernz handling	2026-03-21 21:15:41 -07:00
sudacode	87f7b87b5a	fix(deps): refresh electron-builder lockfile	2026-03-21 21:08:02 -07:00
sudacode	36e5a07b92	fix: add modernz patch helper	2026-03-21 21:07:18 -07:00
sudacode	45d183d02d	fix(subtitle-sidebar): address CodeRabbit follow-ups	2026-03-21 20:49:44 -07:00
sudacode	a42fe599cb	fix: pin electron-builder and adjust release files patterns	2026-03-21 20:47:30 -07:00
sudacode	76b5ab68ba	Add subtitle sidebar startup auto-open and resume jump - Add `subtitleSidebar.autoOpen` with startup-only open behavior - Jump to the first resolved active cue on initial resume position - Clear parsed cues when subtitle prefetch init fails	2026-03-21 19:58:37 -07:00
sudacode	0c3ec7a567	fix(subtitle-sidebar): address latest CodeRabbit review	2026-03-21 19:58:37 -07:00
sudacode	01c171629a	ci: resolve security audit vulnerabilities in electron-builder dependencies	2026-03-21 19:58:37 -07:00
sudacode	09b112f25f	ci: trigger rerun	2026-03-21 19:58:37 -07:00
sudacode	3df5d4d6a2	fix(ci): export asCssColor and subtitle sidebar autoOpen typing	2026-03-21 19:58:37 -07:00
sudacode	bbdd98cbff	fix(renderer): sync embedded sidebar mouse passthrough	2026-03-21 19:34:00 -07:00
sudacode	b049cf388d	fix(subtitle-sidebar): address latest CodeRabbit review	2026-03-21 16:28:30 -07:00