feat(subtitle-sidebar): add sidebar config surface (#28)

2026-03-23 00:11:28 -07:00 · 2026-03-21 23:37:42 -07:00
parent eddf6f0456
commit 3a01cffc6b
66 changed files with 5241 additions and 426 deletions
--- 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/configuration.md
+++ b/docs-site/configuration.md
@@ -59,6 +59,7 @@ SubMiner watches the active config file (`config.jsonc` or `config.json`) while
 Hot-reloadable fields:

 - `subtitleStyle`
+- `subtitleSidebar`
 - `keybindings`
 - `shortcuts`
 - `secondarySub.defaultMode`
@@ -88,6 +89,7 @@ The configuration file includes several main sections:
 **Subtitle Display**

 - [**Subtitle Style**](#subtitle-style) - Appearance customization
+- [**Subtitle Sidebar**](#subtitle-sidebar) - Parsed cue list sidebar modal
 - [**Subtitle Position**](#subtitle-position) - Overlay vertical positioning
 - [**Secondary Subtitles**](#secondary-subtitles) - Dual subtitle track support

@@ -337,6 +339,46 @@ Secondary subtitle defaults: `fontFamily: "Inter, Noto Sans, Helvetica Neue, san

 **See `config.example.jsonc`** for the complete list of subtitle style configuration options.

+### Subtitle Sidebar
+
+Configure the parsed-subtitle sidebar modal.
+
+```json
+{
+  "subtitleSidebar": {
+    "enabled": true,
+    "layout": "overlay",
+    "toggleKey": "Backslash",
+    "pauseVideoOnHover": false,
+    "autoScroll": true,
+    "fontFamily": "\"M PLUS 1\", \"Noto Sans CJK JP\", sans-serif",
+    "fontSize": 16
+  }
+}
+```
+
+| Option                      | Values           | Description                                                                      |
+| --------------------------- | ---------------- | -------------------------------------------------------------------------------- |
+| `enabled`                   | boolean          | Enable subtitle sidebar support (`false` by default)                             |
+| `layout`                    | string           | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space to mimic browser-like layout |
+| `toggleKey`                 | string           | `KeyboardEvent.code` used to open/close the sidebar (default: `"Backslash"`)     |
+| `pauseVideoOnHover`         | boolean          | Pause playback while hovering the sidebar cue list                               |
+| `autoScroll`                | boolean          | Keep the active cue in view while playback advances                              |
+| `maxWidth`                  | number           | Maximum sidebar width in CSS pixels (default: `420`)                             |
+| `opacity`                   | number           | Sidebar opacity between `0` and `1` (default: `0.78`)                            |
+| `backgroundColor`           | string           | Sidebar shell background color                                                   |
+| `textColor`                 | hex color        | Default cue text color                                                           |
+| `fontFamily`                | string           | CSS `font-family` value applied to sidebar cue text                             |
+| `fontSize`                  | number           | Base sidebar cue font size in CSS pixels (default: `16`)                        |
+| `timestampColor`            | hex color        | Cue timestamp color                                                              |
+| `activeLineColor`           | hex color        | Active cue text color                                                            |
+| `activeLineBackgroundColor` | string           | Active cue background color                                                      |
+| `hoverLineBackgroundColor`  | string           | Hovered cue background color                                                     |
+
+The sidebar is only available when the active subtitle source has been parsed into a cue list. Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like an opaque settings dialog.
+
+`embedded` layout is intended to act like a split-pane view: it reserves player space with a right-side video margin and keeps interaction in both the player area and sidebar. If you see unexpected offset behavior in your environment, switch back to `overlay` to isolate sidebar placement.
+
 `jlptColors` keys are:

 | Key  | Default   | Description             |
--- a/docs-site/public/config.example.jsonc
+++ b/docs-site/public/config.example.jsonc
@@ -284,6 +284,30 @@
    } // Secondary setting.
  }, // Primary and secondary subtitle styling.

+  // ==========================================
+  // Subtitle Sidebar
+  // Parsed-subtitle sidebar cue list styling, behavior, and toggle key.
+  // Hot-reload: subtitle sidebar changes apply live without restarting SubMiner.
+  // ==========================================
+  "subtitleSidebar": {
+    "enabled": false, // Enable the subtitle sidebar feature for parsed subtitle sources. Values: true | false
+    "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
+    "maxWidth": 420, // Maximum sidebar width in CSS pixels.
+    "opacity": 0.95, // Base opacity applied to the sidebar shell.
+    "backgroundColor": "rgba(73, 77, 100, 0.9)", // Background color for the subtitle sidebar shell.
+    "textColor": "#cad3f5", // Default cue text color in the subtitle sidebar.
+    "fontFamily": "\"M PLUS 1\", \"Noto Sans CJK JP\", sans-serif", // Font family used for subtitle sidebar cue text.
+    "fontSize": 16, // Base font size for subtitle sidebar cue text in CSS pixels.
+    "timestampColor": "#a5adcb", // Timestamp color in the subtitle sidebar.
+    "activeLineColor": "#f5bde6", // Text color for the active subtitle cue.
+    "activeLineBackgroundColor": "rgba(138, 173, 244, 0.22)", // Background color for the active subtitle cue.
+    "hoverLineBackgroundColor": "rgba(54, 58, 79, 0.84)" // Background color for hovered subtitle cues.
+  }, // Parsed-subtitle sidebar cue list styling, behavior, and toggle key.
+
  // ==========================================
  // Shared AI Provider
  // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
--- a/docs-site/shortcuts.md
+++ b/docs-site/shortcuts.md
@@ -68,10 +68,13 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle
 | `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions` |
 | `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`         |
 | `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`     |
+| `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey`    |
 | `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`              |

 The stats toggle is handled inside the focused visible overlay window. It is configurable through the top-level `stats.toggleKey` setting and defaults to `Backquote`.

+The subtitle sidebar toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source.
+
 ## Controller Shortcuts

 These overlay-local shortcuts are fixed and open controller utilities for the Chrome Gamepad API integration.
@@ -133,4 +136,4 @@ The `keybindings` array overrides or extends the overlay's built-in key handling
 }
 ```

-Both `shortcuts` and `keybindings` are [hot-reloadable](/configuration#hot-reload-behavior) — changes take effect without restarting SubMiner.
+Both `shortcuts`, `keybindings`, and `subtitleSidebar` are [hot-reloadable](/configuration#hot-reload-behavior) — changes take effect without restarting SubMiner.