feat(overlay): add primary subtitle bar visibility modes

- Cycle `v` through `hidden | visible | hover` instead of a boolean toggle
- Add `subtitleStyle.primaryDefaultMode` config with default `visible`
- Carry primary mode independently from secondary in hot-reload payload
- Add hover CSS: transparent until hovered, then fully visible
- Show primary-specific OSD text on each mode change

backlog/tasks/task-357 - Add-primary-subtitle-bar-visibility-modes.md

@@ -0,0 +1,70 @@
+---
+id: TASK-357
+title: Add primary subtitle bar visibility modes
+status: Done
+assignee:
+  - Codex
+created_date: '2026-05-13 03:17'
+updated_date: '2026-05-13 03:24'
+labels:
+  - overlay
+  - subtitles
+  - config
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Update the primary subtitle bar visibility control so the `v` key cycles through the same mode model used by secondary subtitles: hidden, visible, and hover/auto. The primary and secondary subtitle bars must keep separate visibility state and config defaults, and primary visibility changes must identify the primary bar in OSD feedback.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Pressing `v` cycles primary subtitle bar visibility through hidden, visible, and hover/auto without changing secondary subtitle visibility.
+- [x] #2 In hover/auto mode, the primary subtitle bar is normally hidden but becomes visible and interactable when hovering over its reserved location.
+- [x] #3 Primary and secondary subtitle visibility modes have independent runtime state and config defaults.
+- [x] #4 `subtitleStyle` exposes a primary subtitle visibility default that defaults to visible and validates invalid values with a warning/fallback.
+- [x] #5 OSD feedback is shown when primary visibility mode changes and clearly identifies the primary subtitle bar.
+- [x] #6 Relevant tests and config example/docs are updated.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add failing tests for primary subtitle mode config default/validation and renderer `v` cycling/OSD behavior.
+2. Add primary subtitle mode type/config default under `subtitleStyle`, parse it with warning fallback, include it in generated example config.
+3. Carry primary mode in renderer state/startup/hot-reload payloads independently from secondary mode.
+4. Replace primary boolean toggle with `hidden -> visible -> hover` cycle and OSD text `Primary subtitle: <mode>`.
+5. Add primary hover CSS mirroring secondary hover behavior so hover mode reserves a hit area and becomes interactable on hover.
+6. Run focused tests, then broader relevant checks if time/environment allows.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented primary subtitle visibility as independent `PrimarySubMode` (`hidden | visible | hover`) with renderer state, startup default from `subtitleStyle.primaryDefaultMode`, hot-reload payload propagation, and primary-specific OSD. Focused tests were added before implementation and all focused tests passed. Full relevant gate passed: `bun run typecheck`, `bun run test:config`, `bun run test:fast`, `bun run test:env`, `bun run build`, `bun run test:smoke:dist`, `bun run docs:test`, `bun run docs:build`, `bun run format:check:src`, and `bun run changelog:lint`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Summary:
+- Added `subtitleStyle.primaryDefaultMode` with default `visible`, enum validation, generated config examples, and renderer/hot-reload payload wiring.
+- Changed the primary subtitle bar `v` action from a boolean hide/show toggle to independent `hidden | visible | hover` mode cycling with OSD text that identifies the primary subtitle.
+- Added hover-mode CSS so the primary bar stays invisible until its location is hovered, then becomes visible and interactable.
+
+Tests:
+- `bun test src/config/resolve/subtitle-style.test.ts src/config/config.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/subtitle-render.test.ts src/main/runtime/config-hot-reload-handlers.test.ts`
+- `bun run typecheck`
+- `bun run test:config`
+- `bun run test:fast`
+- `bun run test:env`
+- `bun run build`
+- `bun run test:smoke:dist`
+- `bun run docs:test`
+- `bun run docs:build`
+- `bun run format:check:src`
+- `bun run changelog:lint`
+<!-- SECTION:FINAL_SUMMARY:END -->

changes/357-primary-subtitle-visibility-modes.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Overlay: Changed `v` to cycle the primary subtitle bar through visible, hover, and hidden modes with primary-specific OSD feedback, and added `subtitleStyle.primaryDefaultMode` to configure the startup default independently from secondary subtitles.

config.example.jsonc

@@ -227,6 +227,7 @@
   // Hot-reload: subtitle style changes apply live without restarting SubMiner.
   // ==========================================
   "subtitleStyle": {
+    "primaryDefaultMode": "visible", // Default primary subtitle bar visibility mode. hidden hides it, visible shows it, hover reveals it on hover. Values: hidden | visible | hover
     "enableJlpt": false, // Enable JLPT vocabulary level underlines. When disabled, JLPT tagging lookup and underlines are skipped. Values: true | false
     "preserveLineBreaks": false, // Preserve line breaks in visible overlay subtitle rendering. When false, line breaks are flattened to spaces for a single-line flow. Values: true | false
     "autoPauseVideoOnHover": true, // Automatically pause mpv playback while hovering subtitle text, then resume on leave. Values: true | false

docs-site/public/config.example.jsonc

@@ -227,6 +227,7 @@
   // Hot-reload: subtitle style changes apply live without restarting SubMiner.
   // ==========================================
   "subtitleStyle": {
+    "primaryDefaultMode": "visible", // Default primary subtitle bar visibility mode. hidden hides it, visible shows it, hover reveals it on hover. Values: hidden | visible | hover
     "enableJlpt": false, // Enable JLPT vocabulary level underlines. When disabled, JLPT tagging lookup and underlines are skipped. Values: true | false
     "preserveLineBreaks": false, // Preserve line breaks in visible overlay subtitle rendering. When false, line breaks are flattened to spaces for a single-line flow. Values: true | false
     "autoPauseVideoOnHover": true, // Automatically pause mpv playback while hovering subtitle text, then resume on leave. Values: true | false

src/config/config.test.ts

@@ -56,6 +56,7 @@ test('loads defaults when config is missing', () => {
   assert.equal(config.discordPresence.enabled, true);
   assert.equal(config.discordPresence.updateIntervalMs, 3_000);
   assert.equal(config.subtitleStyle.backgroundColor, 'rgb(30, 32, 48, 0.88)');
+  assert.equal(config.subtitleStyle.primaryDefaultMode, 'visible');
   assert.equal(config.subtitleStyle.preserveLineBreaks, false);
   assert.equal(config.subtitleStyle.autoPauseVideoOnHover, true);
   assert.equal(config.subtitleStyle.autoPauseVideoOnYomitanPopup, true);

src/config/definitions/defaults-subtitle.ts

@@ -2,6 +2,7 @@ import { ResolvedConfig } from '../../types/config';
 
 export const SUBTITLE_DEFAULT_CONFIG: Pick<ResolvedConfig, 'subtitleStyle' | 'subtitleSidebar'> = {
   subtitleStyle: {
+    primaryDefaultMode: 'visible',
     enableJlpt: false,
     preserveLineBreaks: false,
     autoPauseVideoOnHover: true,

src/config/definitions/options-subtitle.ts

@@ -5,6 +5,14 @@ export function buildSubtitleConfigOptionRegistry(
   defaultConfig: ResolvedConfig,
 ): ConfigOptionRegistryEntry[] {
   return [
+    {
+      path: 'subtitleStyle.primaryDefaultMode',
+      kind: 'enum',
+      enumValues: ['hidden', 'visible', 'hover'],
+      defaultValue: defaultConfig.subtitleStyle.primaryDefaultMode,
+      description:
+        'Default primary subtitle bar visibility mode. hidden hides it, visible shows it, hover reveals it on hover.',
+    },
     {
       path: 'subtitleStyle.enableJlpt',
       kind: 'boolean',

src/config/resolve/subtitle-domains.ts

@@ -147,6 +147,7 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
 
   if (isObject(src.subtitleStyle)) {
     const fallbackSubtitleStyleEnableJlpt = resolved.subtitleStyle.enableJlpt;
+    const fallbackSubtitleStylePrimaryDefaultMode = resolved.subtitleStyle.primaryDefaultMode;
     const fallbackSubtitleStylePreserveLineBreaks = resolved.subtitleStyle.preserveLineBreaks;
     const fallbackSubtitleStyleAutoPauseVideoOnHover = resolved.subtitleStyle.autoPauseVideoOnHover;
     const fallbackSubtitleStyleAutoPauseVideoOnYomitanPopup =
@@ -190,6 +191,24 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
       );
     }
 
+    const primaryDefaultMode = (src.subtitleStyle as { primaryDefaultMode?: unknown })
+      .primaryDefaultMode;
+    if (
+      primaryDefaultMode === 'hidden' ||
+      primaryDefaultMode === 'visible' ||
+      primaryDefaultMode === 'hover'
+    ) {
+      resolved.subtitleStyle.primaryDefaultMode = primaryDefaultMode;
+    } else if (primaryDefaultMode !== undefined) {
+      resolved.subtitleStyle.primaryDefaultMode = fallbackSubtitleStylePrimaryDefaultMode;
+      warn(
+        'subtitleStyle.primaryDefaultMode',
+        primaryDefaultMode,
+        resolved.subtitleStyle.primaryDefaultMode,
+        'Expected hidden, visible, or hover.',
+      );
+    }
+
     const preserveLineBreaks = asBoolean(
       (src.subtitleStyle as { preserveLineBreaks?: unknown }).preserveLineBreaks,
     );

src/config/resolve/subtitle-style.test.ts

@@ -66,6 +66,31 @@ test('subtitleStyle autoPauseVideoOnYomitanPopup falls back on invalid value', (
   );
 });
 
+test('subtitleStyle primaryDefaultMode accepts valid values and warns on invalid', () => {
+  const valid = createResolveContext({
+    subtitleStyle: {
+      primaryDefaultMode: 'hover',
+    },
+  });
+  applySubtitleDomainConfig(valid.context);
+  assert.equal(valid.context.resolved.subtitleStyle.primaryDefaultMode, 'hover');
+
+  const invalid = createResolveContext({
+    subtitleStyle: {
+      primaryDefaultMode: 'auto' as never,
+    },
+  });
+  applySubtitleDomainConfig(invalid.context);
+  assert.equal(invalid.context.resolved.subtitleStyle.primaryDefaultMode, 'visible');
+  assert.ok(
+    invalid.warnings.some(
+      (warning) =>
+        warning.path === 'subtitleStyle.primaryDefaultMode' &&
+        warning.message === 'Expected hidden, visible, or hover.',
+    ),
+  );
+});
+
 test('subtitleStyle nameMatchEnabled falls back on invalid value', () => {
   const { context, warnings } = createResolveContext({
     subtitleStyle: {

src/main/runtime/config-hot-reload-handlers.test.ts

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { DEFAULT_CONFIG, deepCloneConfig } from '../../config';
 import {
+  buildConfigHotReloadPayload,
   buildRestartRequiredConfigMessage,
   createConfigHotReloadAppliedHandler,
   createConfigHotReloadMessageHandler,
@@ -56,6 +57,17 @@ test('createConfigHotReloadAppliedHandler runs all hot-reload effects', () => {
   );
 });
 
+test('buildConfigHotReloadPayload includes independent primary subtitle mode', () => {
+  const config = deepCloneConfig(DEFAULT_CONFIG);
+  config.subtitleStyle.primaryDefaultMode = 'hover';
+  config.secondarySub.defaultMode = 'hidden';
+
+  const payload = buildConfigHotReloadPayload(config);
+
+  assert.equal(payload.primarySubMode, 'hover');
+  assert.equal(payload.secondarySubMode, 'hidden');
+});
+
 test('createConfigHotReloadAppliedHandler skips optional effects when no hot fields', () => {
   const config = deepCloneConfig(DEFAULT_CONFIG);
   const calls: string[] = [];

src/main/runtime/config-hot-reload-handlers.ts

@@ -54,6 +54,7 @@ export function buildConfigHotReloadPayload(config: ResolvedConfig): ConfigHotRe
     sessionBindingWarnings,
     subtitleStyle: resolveSubtitleStyleForRenderer(config),
     subtitleSidebar: config.subtitleSidebar,
+    primarySubMode: config.subtitleStyle.primaryDefaultMode,
     secondarySubMode: config.secondarySub.defaultMode,
   };
 }

src/renderer/handlers/keyboard.test.ts

@@ -407,21 +407,37 @@ function createKeyboardHandlerHarness() {
   };
 }
 
-test('primary subtitle visibility key hides and restores the subtitle bar without mpv sub-visibility', async () => {
+test('primary subtitle visibility key cycles modes with primary OSD without mpv sub-visibility', async () => {
   const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
 
   try {
     await handlers.setupMpvInputForwarding();
 
+    testGlobals.dispatchKeydown({ key: 'v', code: 'KeyV' });
+    assert.equal(ctx.dom.subtitleContainer.classList.contains('primary-sub-hidden'), false);
+    assert.equal(ctx.dom.subtitleContainer.classList.contains('primary-sub-hover'), true);
+    assert.equal(ctx.state.primarySubtitleMode, 'hover');
+
     testGlobals.dispatchKeydown({ key: 'v', code: 'KeyV' });
     assert.equal(ctx.dom.subtitleContainer.classList.contains('primary-sub-hidden'), true);
+    assert.equal(ctx.state.primarySubtitleMode, 'hidden');
 
     testGlobals.dispatchKeydown({ key: 'v', code: 'KeyV' });
     assert.equal(ctx.dom.subtitleContainer.classList.contains('primary-sub-hidden'), false);
+    assert.equal(ctx.dom.subtitleContainer.classList.contains('primary-sub-hover'), false);
+    assert.equal(ctx.state.primarySubtitleMode, 'visible');
     assert.equal(
       testGlobals.mpvCommands.some((command) => command.includes('sub-visibility')),
       false,
     );
+    assert.deepEqual(
+      testGlobals.mpvCommands.filter((command) => command[0] === 'show-text'),
+      [
+        ['show-text', 'Primary subtitle: hover', '1500'],
+        ['show-text', 'Primary subtitle: hidden', '1500'],
+        ['show-text', 'Primary subtitle: visible', '1500'],
+      ],
+    );
   } finally {
     testGlobals.restore();
   }

src/renderer/handlers/keyboard.ts

@@ -1,4 +1,4 @@
-import type { CompiledSessionBinding, ShortcutsConfig } from '../../types';
+import type { CompiledSessionBinding, PrimarySubMode, ShortcutsConfig } from '../../types';
 import type { RendererContext } from '../context';
 import {
   YOMITAN_POPUP_HIDDEN_EVENT,
@@ -370,13 +370,17 @@ export function createKeyboardHandlers(
   }
 
   function togglePrimarySubtitleBarVisibility(): void {
-    const visible = !ctx.state.primarySubtitleBarVisible;
-    ctx.state.primarySubtitleBarVisible = visible;
-    if (visible) {
-      ctx.dom.subtitleContainer.classList.remove('primary-sub-hidden');
-    } else {
-      ctx.dom.subtitleContainer.classList.add('primary-sub-hidden');
-    }
+    const modes: PrimarySubMode[] = ['hidden', 'visible', 'hover'];
+    const currentIndex = modes.indexOf(ctx.state.primarySubtitleMode);
+    const nextMode = modes[((currentIndex >= 0 ? currentIndex : 1) + 1) % modes.length]!;
+    ctx.state.primarySubtitleMode = nextMode;
+    ctx.dom.subtitleContainer.classList.remove(
+      'primary-sub-hidden',
+      'primary-sub-visible',
+      'primary-sub-hover',
+    );
+    ctx.dom.subtitleContainer.classList.add(`primary-sub-${nextMode}`);
+    window.electronAPI.sendMpvCommand(['show-text', `Primary subtitle: ${nextMode}`, '1500']);
   }
 
   async function handleMarkWatched(): Promise<void> {

src/renderer/renderer.ts

@@ -672,6 +672,7 @@ async function init(): Promise<void> {
       keyboardHandlers.updateSessionBindings(payload.sessionBindings);
       void keyboardHandlers.refreshConfiguredShortcuts();
       subtitleRenderer.applySubtitleStyle(payload.subtitleStyle);
+      subtitleRenderer.updatePrimarySubMode(payload.primarySubMode);
       subtitleRenderer.updateSecondarySubMode(payload.secondarySubMode);
       ctx.state.subtitleSidebarConfig = payload.subtitleSidebar;
       ctx.state.subtitleSidebarToggleKey = payload.subtitleSidebar.toggleKey;
@@ -694,6 +695,7 @@ async function init(): Promise<void> {
 
   const initialSubtitleStyle = await window.electronAPI.getSubtitleStyle();
   subtitleRenderer.applySubtitleStyle(initialSubtitleStyle);
+  subtitleRenderer.updatePrimarySubMode(initialSubtitleStyle?.primaryDefaultMode ?? 'visible');
   await subtitleSidebarModal.refreshSubtitleSidebarSnapshot();
   await subtitleSidebarModal.autoOpenSubtitleSidebarOnStartup();
 

src/renderer/state.ts

@@ -12,6 +12,7 @@ import type {
   RuntimeOptionState,
   RuntimeOptionValue,
   CharacterDictionarySelectionSnapshot,
+  PrimarySubMode,
   SubtitlePosition,
   SubtitleSidebarConfig,
   SubtitleCue,
@@ -134,7 +135,7 @@ export type RendererState = {
   keyboardSelectionVisible: boolean;
   keyboardSelectedWordIndex: number | null;
   yomitanPopupVisible: boolean;
-  primarySubtitleBarVisible: boolean;
+  primarySubtitleMode: PrimarySubMode;
 };
 
 export function createRendererState(): RendererState {
@@ -245,6 +246,6 @@ export function createRendererState(): RendererState {
     keyboardSelectionVisible: false,
     keyboardSelectedWordIndex: null,
     yomitanPopupVisible: false,
-    primarySubtitleBarVisible: true,
+    primarySubtitleMode: 'visible',
   };
 }

src/renderer/style.css

@@ -684,6 +684,16 @@ body.subtitle-sidebar-embedded-open #subtitleContainer {
   display: none;
 }
 
+#subtitleContainer.primary-sub-hover {
+  opacity: 0;
+  transition: opacity 0.2s ease;
+  pointer-events: auto;
+}
+
+#subtitleContainer.primary-sub-hover:hover {
+  opacity: 1;
+}
+
 #subtitleContainer.primary-sub-hidden {
   display: none;
   pointer-events: none;

src/renderer/subtitle-render.test.ts

@@ -1188,6 +1188,16 @@ test('subtitle annotation CSS underlines JLPT tokens without changing token colo
   );
   assert.match(secondaryHoverBaseBlock, /background:\s*transparent;/);
 
+  const primaryHoverBlock = extractClassBlock(cssText, '#subtitleContainer.primary-sub-hover');
+  assert.match(primaryHoverBlock, /opacity:\s*0;/);
+  assert.match(primaryHoverBlock, /pointer-events:\s*auto;/);
+
+  const primaryHoverVisibleBlock = extractClassBlock(
+    cssText,
+    '#subtitleContainer.primary-sub-hover:hover',
+  );
+  assert.match(primaryHoverVisibleBlock, /opacity:\s*1;/);
+
   const secondaryEmbeddedHoverBlock = extractClassBlock(
     cssText,
     'body.subtitle-sidebar-embedded-open #secondarySubContainer.secondary-sub-hover',

src/renderer/subtitle-render.ts

@@ -1,4 +1,10 @@
-import type { MergedToken, SecondarySubMode, SubtitleData, SubtitleStyleConfig } from '../types';
+import type {
+  MergedToken,
+  PrimarySubMode,
+  SecondarySubMode,
+  SubtitleData,
+  SubtitleStyleConfig,
+} from '../types';
 import type { RendererContext } from './context';
 
 type FrequencyRenderSettings = {
@@ -613,6 +619,16 @@ export function createSubtitleRenderer(ctx: RendererContext) {
     ctx.dom.secondarySubContainer.classList.add(`secondary-sub-${mode}`);
   }
 
+  function updatePrimarySubMode(mode: PrimarySubMode): void {
+    ctx.state.primarySubtitleMode = mode;
+    ctx.dom.subtitleContainer.classList.remove(
+      'primary-sub-hidden',
+      'primary-sub-visible',
+      'primary-sub-hover',
+    );
+    ctx.dom.subtitleContainer.classList.add(`primary-sub-${mode}`);
+  }
+
   function applySubtitleFontSize(fontSize: number): void {
     const clampedSize = Math.max(10, fontSize);
     ctx.dom.subtitleRoot.style.fontSize = `${clampedSize}px`;
@@ -791,6 +807,7 @@ export function createSubtitleRenderer(ctx: RendererContext) {
     applySubtitleStyle,
     renderSecondarySub,
     renderSubtitle,
+    updatePrimarySubMode,
     updateSecondarySubMode,
   };
 }

src/types/runtime.ts

@@ -25,6 +25,7 @@ import type {
   YoutubePickerResolveResult,
 } from './integrations';
 import type {
+  PrimarySubMode,
   SecondarySubMode,
   SubtitleData,
   SubtitlePosition,
@@ -331,6 +332,7 @@ export interface ConfigHotReloadPayload {
   sessionBindingWarnings: SessionBindingWarning[];
   subtitleStyle: SubtitleStyleConfig | null;
   subtitleSidebar: Required<SubtitleSidebarConfig>;
+  primarySubMode: PrimarySubMode;
   secondarySubMode: SecondarySubMode;
 }
 

src/types/subtitle.ts

@@ -55,7 +55,9 @@ export interface SubtitleStyle {
   fontSize: number;
 }
 
-export type SecondarySubMode = 'hidden' | 'visible' | 'hover';
+export type SubtitleBarMode = 'hidden' | 'visible' | 'hover';
+export type PrimarySubMode = SubtitleBarMode;
+export type SecondarySubMode = SubtitleBarMode;
 
 export interface SecondarySubConfig {
   secondarySubLanguages?: string[];
@@ -67,6 +69,7 @@ export type NPlusOneMatchMode = 'headword' | 'surface';
 export type FrequencyDictionaryMatchMode = 'headword' | 'surface';
 
 export interface SubtitleStyleConfig {
+  primaryDefaultMode?: PrimarySubMode;
   enableJlpt?: boolean;
   preserveLineBreaks?: boolean;
   autoPauseVideoOnHover?: boolean;