fix: macOS visible-overlay blur no longer invokes Windows-only blur call

- Split win32/darwin branches in handleOverlayWindowBlurred so darwin visible blur returns early without calling onWindowsVisibleOverlayBlur
- Add regression test asserting Windows callback stays inactive on macOS visible overlay blur
- Close TASK-347

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

@@ -1,70 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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,7 +227,6 @@
   // 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,7 +227,6 @@
   // 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,7 +56,6 @@ 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,7 +2,6 @@ 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,14 +5,6 @@ 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,7 +147,6 @@ 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 =
@@ -191,24 +190,6 @@ 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,31 +66,6 @@ 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,7 +2,6 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { DEFAULT_CONFIG, deepCloneConfig } from '../../config';
 import {
-  buildConfigHotReloadPayload,
   buildRestartRequiredConfigMessage,
   createConfigHotReloadAppliedHandler,
   createConfigHotReloadMessageHandler,
@@ -57,17 +56,6 @@ 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,7 +54,6 @@ 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,37 +407,21 @@ function createKeyboardHandlerHarness() {
   };
 }
 
-test('primary subtitle visibility key cycles modes with primary OSD without mpv sub-visibility', async () => {
+test('primary subtitle visibility key hides and restores the subtitle bar 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, PrimarySubMode, ShortcutsConfig } from '../../types';
+import type { CompiledSessionBinding, ShortcutsConfig } from '../../types';
 import type { RendererContext } from '../context';
 import {
   YOMITAN_POPUP_HIDDEN_EVENT,
@@ -370,17 +370,13 @@ export function createKeyboardHandlers(
   }
 
   function togglePrimarySubtitleBarVisibility(): void {
-    const modes: PrimarySubMode[] = ['hidden', 'visible', 'hover'];
+    const visible = !ctx.state.primarySubtitleBarVisible;
-    const currentIndex = modes.indexOf(ctx.state.primarySubtitleMode);
+    ctx.state.primarySubtitleBarVisible = visible;
-    const nextMode = modes[((currentIndex >= 0 ? currentIndex : 1) + 1) % modes.length]!;
+    if (visible) {
-    ctx.state.primarySubtitleMode = nextMode;
+      ctx.dom.subtitleContainer.classList.remove('primary-sub-hidden');
-    ctx.dom.subtitleContainer.classList.remove(
+    } else {
-      'primary-sub-hidden',
+      ctx.dom.subtitleContainer.classList.add('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,7 +672,6 @@ 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;
@@ -695,7 +694,6 @@ 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,7 +12,6 @@ import type {
   RuntimeOptionState,
   RuntimeOptionValue,
   CharacterDictionarySelectionSnapshot,
-  PrimarySubMode,
   SubtitlePosition,
   SubtitleSidebarConfig,
   SubtitleCue,
@@ -135,7 +134,7 @@ export type RendererState = {
   keyboardSelectionVisible: boolean;
   keyboardSelectedWordIndex: number | null;
   yomitanPopupVisible: boolean;
-  primarySubtitleMode: PrimarySubMode;
+  primarySubtitleBarVisible: boolean;
 };
 
 export function createRendererState(): RendererState {
@@ -246,6 +245,6 @@ export function createRendererState(): RendererState {
     keyboardSelectionVisible: false,
     keyboardSelectedWordIndex: null,
     yomitanPopupVisible: false,
-    primarySubtitleMode: 'visible',
+    primarySubtitleBarVisible: true,
   };
 }

src/renderer/style.css

@@ -684,16 +684,6 @@ 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,16 +1188,6 @@ 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,10 +1,4 @@
-import type {
+import type { MergedToken, SecondarySubMode, SubtitleData, SubtitleStyleConfig } from '../types';
-  MergedToken,
-  PrimarySubMode,
-  SecondarySubMode,
-  SubtitleData,
-  SubtitleStyleConfig,
-} from '../types';
 import type { RendererContext } from './context';
 
 type FrequencyRenderSettings = {
@@ -619,16 +613,6 @@ 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`;
@@ -807,7 +791,6 @@ export function createSubtitleRenderer(ctx: RendererContext) {
     applySubtitleStyle,
     renderSecondarySub,
     renderSubtitle,
-    updatePrimarySubMode,
     updateSecondarySubMode,
   };
 }

src/types/runtime.ts

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

src/types/subtitle.ts

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