Refactor startup, queries, and workflow into focused modules (#36)

* chore(backlog): add mining workflow milestone and tasks * refactor: split character dictionary runtime modules * refactor: split shared type entrypoints * refactor: use bun serve for stats server * feat: add repo-local subminer workflow plugin * fix: add stats server node fallback * refactor: split immersion tracker query modules * chore: update backlog task records * refactor: migrate shared type imports * refactor: compose startup and setup window wiring * Add backlog tasks and launcher time helper tests - Track follow-up cleanup work in Backlog.md - Replace Date.now usage with shared nowMs helper - Add launcher args/parser and core regression tests * test: increase launcher test timeout for CI stability * fix: address CodeRabbit review feedback * refactor(main): extract remaining inline runtime logic from main * chore(backlog): update task notes and changelog fragment * refactor: split main boot phases * test: stabilize bun coverage reporting * Switch plausible endpoint and harden coverage lane parsing - update docs-site tracking to use the Plausible capture endpoint - tighten coverage lane argument and LCOV parsing checks - make script entrypoint use CommonJS main guard * Restrict docs analytics and build coverage input - limit Plausible init to docs.subminer.moe - build Yomitan before src coverage lane * fix(ci): normalize Windows shortcut paths for cross-platform tests * Fix verification and immersion-tracker grouping - isolate verifier artifacts and lease handling - switch weekly/monthly tracker cutoffs to calendar boundaries - tighten boot lifecycle and zip writer tests * fix: resolve CI type failures in boot and immersion query tests * fix: remove strict spread usage in Date mocks * fix: use explicit super args for MockDate constructors * Factor out mock date helper in tracker tests - reuse a shared `withMockDate` helper for date-sensitive query tests - make monthly rollup assertions key off `videoId` instead of row order * fix: use variadic array type for MockDate constructor args TS2367: fixed-length tuple made args.length === 0 unreachable. * refactor: remove unused createMainBootRuntimes/Handlers aggregate functions These functions were never called by production code — main.ts imports the individual composeBoot* re-exports directly. * refactor: remove boot re-export alias layer main.ts now imports directly from the runtime/composers and runtime/domains modules, eliminating the intermediate boot/ indirection. * refactor: consolidate 3 near-identical setup window factories Extract shared createSetupWindowHandler with a config parameter. Public API unchanged. * refactor: parameterize duplicated getAffected*Ids query helpers Four structurally identical functions collapsed into two parameterized helpers while preserving the existing public API. * refactor: inline identity composers (stats-startup, overlay-window) composeStatsStartupRuntime was a no-op that returned its input. composeOverlayWindowHandlers was a 1-line delegation. Both removed in favor of direct usage. * chore: remove unused token/queue file path constants from main.ts * fix: replace any types in boot services with proper signatures * refactor: deduplicate ensureDir into shared/fs-utils 5 copies of mkdir-p-if-not-exists consolidated into one shared module with ensureDir (directory path) and ensureDirForFile (file path) variants. * fix: tighten type safety in boot services - Add AppLifecycleShape and OverlayModalInputStateShape constraints so TAppLifecycleApp and TOverlayModalInputState generics are bounded - Remove unsafe `as { handleModalInputStateChange? }` cast — now directly callable via the constraint - Use `satisfies AppLifecycleShape` for structural validation on the appLifecycleApp object literal - Document Electron App.on incompatibility with simple signatures * refactor: inline subtitle-prefetch-runtime-composer The composer was a pure pass-through that destructured an object and reassembled it with the same fields. Inlined at the call site. * chore: consolidate duplicate import paths in main.ts * test: extract mpv composer test fixture factory to reduce duplication * test: add behavioral assertions to composer tests Upgrade 8 composer test files from shape-only typeof checks to behavioral assertions that invoke returned handlers and verify injected dependencies are actually called, following the mpv-runtime-composer pattern. * refactor: normalize import extensions in query modules * refactor: consolidate toDbMs into query-shared.ts * refactor: remove Node.js fallback from stats-server, use Bun only * Fix monthly rollup test expectations - Preserve multi-arg Date construction in mock helper - Align rollup assertions with the correct videoId * fix: address PR 36 CodeRabbit follow-ups * fix: harden coverage lane cleanup * fix(stats): fallback to node server when Bun.serve unavailable * fix(ci): restore coverage lane compatibility * chore(backlog): close TASK-242 * fix: address latest CodeRabbit review round * fix: guard disabled immersion retention windows * fix: migrate discord rpc wrapper * fix(ci): add changelog fragment for PR 36 * fix: stabilize macOS visible overlay toggle * fix: pin installed mpv plugin to current binary * fix: strip inline subtitle markup from sidebar cues * fix(renderer): restore subtitle sidebar mpv passthrough * feat(discord): add configurable presence style presets Replace the hardcoded "Mining and crafting (Anki cards)" meme message with a preset system. New `discordPresence.presenceStyle` option supports four presets: "default" (clean bilingual), "meme" (the OG Minecraft joke), "japanese" (fully JP), and "minimal". The default preset shows "Sentence Mining" with 日本語学習中 as the small image tooltip. Existing users can set presenceStyle to "meme" to keep the old behavior. * fix: finalize v0.10.0 release prep * docs: add subtitle sidebar guide and release note * chore(backlog): mark docs task done * fix: lazily resolve youtube playback socket path * chore(release): build v0.10.0 changelog * Revert "chore(release): build v0.10.0 changelog" This reverts commit 9741c0f020.
2026-03-30 06:12:06 -07:00 · 2026-03-29 16:16:29 -07:00
parent 2d4f2d1139
commit 35adf8299c
297 changed files with 17713 additions and 9147 deletions
--- a/docs-site/.vitepress/config.ts
+++ b/docs-site/.vitepress/config.ts
@@ -74,7 +74,9 @@ export default {
          { text: 'Configuration', link: '/configuration' },
          { text: 'Keyboard Shortcuts', link: '/shortcuts' },
          { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
+          { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
          { text: 'Immersion Tracking', link: '/immersion-tracking' },
+          { text: 'JLPT Vocabulary Bundle', link: '/jlpt-vocab-bundle' },
          { text: 'Troubleshooting', link: '/troubleshooting' },
        ],
      },
--- a/docs-site/.vitepress/theme/index.ts
+++ b/docs-site/.vitepress/theme/index.ts
@@ -10,13 +10,18 @@ let mermaidLoader: Promise<any> | null = null;
 let plausibleTrackerInitialized = false;
 const MERMAID_MODAL_ID = 'mermaid-diagram-modal';
 const PLAUSIBLE_DOMAIN = 'subminer.moe';
-const PLAUSIBLE_ENDPOINT = 'https://worker.subminer.moe/api/event';
+const PLAUSIBLE_ENABLED_HOSTNAMES = new Set(['docs.subminer.moe']);
+const PLAUSIBLE_ENDPOINT = 'https://worker.subminer.moe/api/capture';

 async function initPlausibleTracker() {
  if (typeof window === 'undefined' || plausibleTrackerInitialized) {
    return;
  }

+  if (!PLAUSIBLE_ENABLED_HOSTNAMES.has(window.location.hostname)) {
+    return;
+  }
+
  const { init } = await import('@plausible-analytics/tracker');
  init({
    domain: PLAUSIBLE_DOMAIN,
--- a/docs-site/.vitepress/theme/tui-theme.css
+++ b/docs-site/.vitepress/theme/tui-theme.css
@@ -34,6 +34,25 @@
    system-ui,
    sans-serif;
  --tui-transition: 180ms ease;
+
+  /* Theme-specific values — overridden in .dark below */
+  --tui-nav-bg: color-mix(in srgb, var(--vp-c-bg-alt) 88%, transparent);
+  --tui-table-hover-bg: color-mix(in srgb, var(--vp-c-bg-soft) 80%, transparent);
+  --tui-link-underline: color-mix(in srgb, var(--vp-c-brand-1) 40%, transparent);
+  --tui-selection-bg: hsla(267, 83%, 45%, 0.14);
+  --tui-hero-glow: hsla(267, 83%, 45%, 0.05);
+  --tui-step-hover-bg: var(--vp-c-bg-alt);
+  --tui-step-hover-glow: color-mix(in srgb, var(--vp-c-brand-1) 30%, transparent);
+}
+
+.dark {
+  --tui-nav-bg: hsla(232, 23%, 18%, 0.82);
+  --tui-table-hover-bg: hsla(232, 23%, 18%, 0.4);
+  --tui-link-underline: hsla(267, 83%, 80%, 0.3);
+  --tui-selection-bg: hsla(267, 83%, 80%, 0.22);
+  --tui-hero-glow: hsla(267, 83%, 80%, 0.06);
+  --tui-step-hover-bg: hsla(232, 23%, 18%, 0.6);
+  --tui-step-hover-glow: hsla(267, 83%, 80%, 0.3);
 }

 :root {
@@ -48,7 +67,7 @@

 /* === Selection === */
 ::selection {
-  background: hsla(267, 83%, 80%, 0.22);
+  background: var(--tui-selection-bg);
  color: var(--vp-c-text-1);
 }

@@ -102,7 +121,7 @@ button,
 }

 .VPNav .VPNavBar:not(.has-sidebar) {
-  background: hsla(232, 23%, 18%, 0.82);
+  background: var(--tui-nav-bg);
 }

 .VPNav .VPNavBar.has-sidebar .content {
@@ -245,13 +264,13 @@ button,
 }

 .vp-doc table tr:hover td {
-  background: hsla(232, 23%, 18%, 0.4);
+  background: var(--tui-table-hover-bg);
 }

 /* === Links === */
 .vp-doc a {
  text-decoration: none;
-  border-bottom: 1px solid hsla(267, 83%, 80%, 0.3);
+  border-bottom: 1px solid var(--tui-link-underline);
  transition: border-color var(--tui-transition), color var(--tui-transition);
 }

@@ -653,7 +672,7 @@ body {
  height: 400px;
  background: radial-gradient(
    ellipse at center,
-    hsla(267, 83%, 80%, 0.06) 0%,
+    var(--tui-hero-glow) 0%,
    transparent 70%
  );
  pointer-events: none;
--- a/docs-site/architecture.md
+++ b/docs-site/architecture.md
@@ -39,6 +39,7 @@ src/
  types.ts                 # Shared type definitions
  main/                    # Main-process composition/runtime adapters
    app-lifecycle.ts       # App lifecycle + app-ready runtime runner factories
+    character-dictionary-runtime.ts # Character-dictionary orchestration/public runtime API
    cli-runtime.ts         # CLI command runtime service adapters
    config-validation.ts   # Startup/hot-reload config error formatting and fail-fast helpers
    dependencies.ts        # Shared dependency builders for IPC/runtime services
@@ -53,6 +54,7 @@ src/
    startup-lifecycle.ts    # Lifecycle runtime runner adapter
    state.ts                # Application runtime state container + reducer transitions
    subsync-runtime.ts      # Subsync command runtime adapter
+    character-dictionary-runtime/ # Character-dictionary fetch/build/cache modules + focused tests
    runtime/
      composers/            # High-level composition clusters used by main.ts
      domains/              # Domain barrel exports (startup/overlay/mpv/jellyfin/...)
--- a/docs-site/changelog.md
+++ b/docs-site/changelog.md
@@ -1,5 +1,19 @@
 # Changelog

+## v0.10.0 (2026-03-29)
+- Fixed stats startup so the immersion tracker can run when `Bun.serve` is unavailable.
+- Added a Node `http` fallback for Electron/runtime paths that do not expose Bun, so stats keeps working there too.
+- Updated Discord Rich Presence to the maintained `@xhayper/discord-rpc` wrapper.
+- Fixed the macOS visible-overlay toggle path so manual hides stay hidden and the plugin uses the explicit visible-overlay toggle command.
+- Restored macOS mpv passthrough while the overlay subtitle sidebar is open so clicks outside the sidebar can refocus mpv and keep native keybindings working.
+
+## v0.9.3 (2026-03-25)
+- Moved YouTube primary subtitle language defaults to `youtube.primarySubLanguages`.
+- Removed the placeholder YouTube subtitle retime step; downloaded primary subtitle tracks are now used directly.
+- Removed the old internal YouTube retime helper and its tests.
+- Clarified optional `alass` / `ffsubsync` subtitle-sync setup and fallback behavior in the docs.
+- Removed the legacy `youtubeSubgen.primarySubLanguages` config path from generated config and docs.
+
 ## v0.9.2 (2026-03-25)
 - Fixed overlay pointer tracking so Windows click-through toggles immediately when the cursor enters or leaves subtitle regions.
 - Fixed Windows overlay window tracking on scaled displays by converting native tracked window bounds to Electron DIP coordinates.
--- a/docs-site/configuration.md
+++ b/docs-site/configuration.md
@@ -390,6 +390,8 @@ The sidebar is only available when the active subtitle source has been parsed in

 `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.

+For full details on layout modes, behavior, and the keyboard shortcut, see the [Subtitle Sidebar](/subtitle-sidebar) page.
+
 `jlptColors` keys are:

 | Key  | Default   | Description             |
@@ -1197,30 +1199,38 @@ Discord Rich Presence is optional and disabled by default. When enabled, SubMine
 {
  "discordPresence": {
    "enabled": true,
+    "presenceStyle": "default",
    "updateIntervalMs": 3000,
    "debounceMs": 750
  }
 }
 ```

-| Option             | Values          | Description                                                |
-| ------------------ | --------------- | ---------------------------------------------------------- |
-| `enabled`          | `true`, `false` | Enable Discord Rich Presence updates (default: `false`)    |
-| `updateIntervalMs` | number          | Minimum interval between activity updates in milliseconds  |
-| `debounceMs`       | number          | Debounce window for bursty playback events in milliseconds |
+| Option             | Values                                            | Description                                                |
+| ------------------ | ------------------------------------------------- | ---------------------------------------------------------- |
+| `enabled`          | `true`, `false`                                   | Enable Discord Rich Presence updates (default: `false`)    |
+| `presenceStyle`    | `"default"`, `"meme"`, `"japanese"`, `"minimal"`  | Card text preset (default: `"default"`)                    |
+| `updateIntervalMs` | number                                            | Minimum interval between activity updates in milliseconds  |
+| `debounceMs`       | number                                            | Debounce window for bursty playback events in milliseconds |

 Setup steps:

 1. Set `discordPresence.enabled` to `true`.
-2. Restart SubMiner.
+2. Optionally set `discordPresence.presenceStyle` to choose a card text preset.
+3. Restart SubMiner.

-SubMiner uses a fixed official activity card style for all users:
+#### Presence style presets

- Details: current media title while playing (fallback: `Mining and crafting (Anki cards)` when idle/disconnected)
- State: `Playing mm:ss / mm:ss` or `Paused mm:ss / mm:ss` (fallback: `Idle`)
- Large image key/text: `subminer-logo` / `SubMiner`
- Small image key/text: `study` / `Sentence Mining`
- No activity button by default
+While playing media, the **Details** line always shows the current media title and **State** shows `Playing mm:ss / mm:ss` or `Paused mm:ss / mm:ss`. The preset controls what appears when idle and the tooltip text on images.
+
+| Preset       | Idle details                        | Small image text   | Vibe                                    |
+| ------------ | ----------------------------------- | ------------------ | --------------------------------------- |
+| **`default`**| `Sentence Mining`                   | `日本語学習中`      | Clean, bilingual flair                  |
+| `meme`       | `Mining and crafting (Anki cards)`  | `Sentence Mining`  | Minecraft-inspired joke                 |
+| `japanese`   | `文の採掘中`                         | `イマージョン学習`  | Fully Japanese                          |
+| `minimal`    | `SubMiner`                          | *(none)*           | Bare essentials, no small image overlay |
+
+All presets use the `subminer-logo` large image with `SubMiner` tooltip. No activity button is shown by default.

 Troubleshooting:

--- a/docs-site/index.md
+++ b/docs-site/index.md
@@ -67,7 +67,7 @@ features:
      alt: Subtitle download icon
    title: Subtitle Download & Sync
    details: Search and pull subtitles from Jimaku, then auto-sync timing with alass or ffsubsync — all from the overlay.
-    link: /configuration#jimaku
+    link: /jimaku-integration
    linkText: Jimaku integration
  - icon:
      src: /assets/tokenization.svg
@@ -223,12 +223,12 @@ const demoAssetVersion = '20260223-2';
 }

 .workflow-step:hover {
-  background: hsla(232, 23%, 18%, 0.6);
+  background: var(--tui-step-hover-bg);
 }

 .workflow-step:hover .step-number {
  color: var(--vp-c-brand-1);
-  text-shadow: 0 0 12px hsla(267, 83%, 80%, 0.3);
+  text-shadow: 0 0 12px var(--tui-step-hover-glow);
 }

 .workflow-connector {
--- a/docs-site/installation.md
+++ b/docs-site/installation.md
@@ -172,7 +172,7 @@ Install `mpv` separately and ensure `mpv.exe` is on `PATH`. `ffmpeg` is still re
 ### Windows Usage Notes

 - Launch `SubMiner.exe` once to let the first-run setup flow seed `%APPDATA%\\SubMiner\\config.jsonc`, offer mpv plugin installation, open bundled Yomitan settings, and optionally create `SubMiner mpv` Start Menu/Desktop shortcuts.
- If you use the mpv plugin, leave `binary_path` empty unless SubMiner is installed in a non-standard location.
+- First-run mpv plugin installs pin `binary_path` to the current `SubMiner.exe` automatically. Manual plugin configs can leave `binary_path` empty unless SubMiner is installed in a non-standard location.
 - Windows plugin installs rewrite `socket_path` to `\\.\pipe\subminer-socket`; do not keep `/tmp/subminer-socket` on Windows.
 - Native window tracking is built in on Windows; no `xdotool`, `xwininfo`, or compositor-specific helper is required.

@@ -201,6 +201,7 @@ mpv must be launched with `--input-ipc-server=/tmp/subminer-socket` for SubMiner
 :::

 On Windows, the packaged plugin config is rewritten to `socket_path=\\.\pipe\subminer-socket`.
+First-run setup also pins `binary_path` to the current app binary so mpv launches the same SubMiner build that installed the plugin.

 ```bash
 # Option 1: install from release assets bundle
--- a/docs-site/jimaku-integration.md
+++ b/docs-site/jimaku-integration.md
@@ -131,6 +131,6 @@ Verify mpv is running and connected via IPC. SubMiner loads the subtitle by issu

 ## Related

- [Configuration Reference](/configuration#jimaku) — full config section
+- [Configuration Reference](/configuration#jimaku) — full config options
 - [Mining Workflow](/mining-workflow#jimaku-subtitle-search) — how Jimaku fits into the sentence mining loop
 - [Troubleshooting](/troubleshooting#jimaku) — additional error guidance
--- a/docs-site/plausible.test.ts
+++ b/docs-site/plausible.test.ts
@@ -6,14 +6,17 @@ const docsThemePath = new URL('./.vitepress/theme/index.ts', import.meta.url);
 const docsConfigContents = readFileSync(docsConfigPath, 'utf8');
 const docsThemeContents = readFileSync(docsThemePath, 'utf8');

-test('docs site keeps docs hostname while sending plausible events to subminer.moe via worker.subminer.moe', () => {
+test('docs site keeps docs hostname while sending plausible events to subminer.moe via worker.subminer.moe capture endpoint', () => {
  expect(docsConfigContents).toContain("hostname: 'https://docs.subminer.moe'");
  expect(docsThemeContents).toContain("const PLAUSIBLE_DOMAIN = 'subminer.moe'");
+  expect(docsThemeContents).toContain('const PLAUSIBLE_ENABLED_HOSTNAMES = new Set([');
+  expect(docsThemeContents).toContain("'docs.subminer.moe'");
  expect(docsThemeContents).toContain(
-    "const PLAUSIBLE_ENDPOINT = 'https://worker.subminer.moe/api/event'",
+    "const PLAUSIBLE_ENDPOINT = 'https://worker.subminer.moe/api/capture'",
  );
  expect(docsThemeContents).toContain('@plausible-analytics/tracker');
  expect(docsThemeContents).toContain('const { init } = await import');
+  expect(docsThemeContents).toContain('!PLAUSIBLE_ENABLED_HOSTNAMES.has(window.location.hostname)');
  expect(docsThemeContents).toContain('domain: PLAUSIBLE_DOMAIN');
  expect(docsThemeContents).toContain('endpoint: PLAUSIBLE_ENDPOINT');
  expect(docsThemeContents).toContain('outboundLinks: true');
--- a/docs-site/public/config.example.jsonc
+++ b/docs-site/public/config.example.jsonc
@@ -498,6 +498,7 @@
  // ==========================================
  "discordPresence": {
    "enabled": false, // Enable optional Discord Rich Presence updates. Values: true | false
+    "presenceStyle": "default", // Presence card text preset: "default" (clean bilingual), "meme" (Mining and crafting), "japanese" (fully JP), or "minimal".
    "updateIntervalMs": 3000, // Minimum interval between presence payload updates.
    "debounceMs": 750 // Debounce delay used to collapse bursty presence updates.
  }, // Optional Discord Rich Presence activity card updates for current playback/study session.
--- a/docs-site/subtitle-sidebar.md
+++ b/docs-site/subtitle-sidebar.md
@@ -0,0 +1,71 @@
+# Subtitle Sidebar
+
+The subtitle sidebar displays the full parsed cue list for the active subtitle file as a scrollable panel alongside mpv. It lets you review past and upcoming lines, click any cue to seek directly to that moment, and follow along without depending on the transient overlay subtitles.
+
+The sidebar is opt-in and disabled by default. Enable it under `subtitleSidebar.enabled` in your config.
+
+## How It Works
+
+When SubMiner parses the active subtitle source into a cue list, the sidebar becomes available. Toggle it with the `\` key (configurable via `subtitleSidebar.toggleKey`). While open:
+
+- The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`).
+- Clicking any cue seeks mpv to that timestamp.
+- The sidebar stays synchronized with the overlay — media transitions and subtitle source changes update both simultaneously.
+
+The sidebar only appears when a parsed cue list is available. External subtitle sources that SubMiner cannot parse (for example, embedded ASS tracks rendered directly by mpv) will not populate the sidebar.
+
+## Layout Modes
+
+Two layout modes are available via `subtitleSidebar.layout`:
+
+**`overlay`** (default) — The sidebar floats over mpv as a panel. It does not affect the player window size or position.
+
+**`embedded`** — Reserves space on the right side of the player and shifts the video area to mimic a split-pane layout. Useful if you want the cue list visible without it covering the video. If you see unexpected positioning in your environment, switch back to `overlay` to isolate the issue.
+
+## Configuration
+
+Enable and configure the sidebar under `subtitleSidebar` in your config file:
+
+```json
+{
+  "subtitleSidebar": {
+    "enabled": false,
+    "autoOpen": false,
+    "layout": "overlay",
+    "toggleKey": "Backslash",
+    "pauseVideoOnHover": false,
+    "autoScroll": true,
+    "fontFamily": "\"M PLUS 1\", \"Noto Sans CJK JP\", sans-serif",
+    "fontSize": 16
+  }
+}
+```
+
+| Option                      | Type    | Default      | Description                                                                                        |
+| --------------------------- | ------- | ------------ | -------------------------------------------------------------------------------------------------- |
+| `enabled`                   | boolean | `false`      | Enable subtitle sidebar support                                                                    |
+| `autoOpen`                  | boolean | `false`      | Open the sidebar automatically on overlay startup                                                  |
+| `layout`                    | string  | `"overlay"`  | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space                        |
+| `toggleKey`                 | string  | `"Backslash"` | `KeyboardEvent.code` for the toggle shortcut                                                      |
+| `pauseVideoOnHover`         | boolean | `false`      | Pause playback while hovering the cue list                                                         |
+| `autoScroll`                | boolean | `true`       | Keep the active cue in view during playback                                                        |
+| `maxWidth`                  | number  | `420`        | Maximum sidebar width in CSS pixels                                                                |
+| `opacity`                   | number  | `0.95`       | Sidebar opacity between `0` and `1`                                                                |
+| `backgroundColor`           | string  | —            | Sidebar shell background color                                                                     |
+| `textColor`                 | string  | —            | Default cue text color                                                                             |
+| `fontFamily`                | string  | —            | CSS `font-family` applied to cue text                                                              |
+| `fontSize`                  | number  | `16`         | Base cue font size in CSS pixels                                                                   |
+| `timestampColor`            | string  | —            | Cue timestamp color                                                                                |
+| `activeLineColor`           | string  | —            | Active cue text color                                                                              |
+| `activeLineBackgroundColor` | string  | —            | Active cue background color                                                                        |
+| `hoverLineBackgroundColor`  | string  | —            | Hovered cue background color                                                                       |
+
+Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like a solid overlay.
+
+## Keyboard Shortcut
+
+| Key | Action                  | Config key                     |
+| --- | ----------------------- | ------------------------------ |
+| `\` | Toggle subtitle sidebar | `subtitleSidebar.toggleKey`    |
+
+The toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source. See [Keyboard Shortcuts](/shortcuts) for the full shortcut reference.