fix(macos): preserve overlay on transient tracker loss and fix subsync m

- macOS tracker now reports minimized vs not-found so transient helper misses no longer hide the overlay; minimizing mpv still triggers hide - overlay-runtime-init skips hide on non-minimized window-lost and calls updateVisibleOverlayVisibility instead - overlay-visibility preserves window level and passthrough state during transient tracker loss - subsync modal open uses dedicated modal window with retry logic to fix first-attempt flash and stale modal state on macOS
docs: simplify Windows setup instructions and remove experimental warnin
2026-05-15 08:12:53 -07:00 · 2026-05-15 02:31:23 -07:00 · 2026-05-13 00:30:55 -07:00 · 2026-05-13 00:11:18 -07:00
18 changed files with 396 additions and 105 deletions
@@ -229,11 +229,9 @@ sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/sub
 <details>
 <summary><b>Windows</b></summary>

-Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`.
+Download the latest installer (`.exe`) [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`.

-**Windows support is experimental.** Core features such as mining, annotations, and dictionary lookups work, but some functionality may be missing or unstable. Bug reports welcome.
-
-**Note:** On Windows the `subminer` launcher requires [`bun`](https://bun.sh) and must be invoked with `bun run subminer` instead of running the script directly. The recommended alternative is the **SubMiner mpv** shortcut created during first-run setup — double-click it, drag files onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See the [Windows mpv Shortcut](https://docs.subminer.moe/usage#windows-mpv-shortcut) section for details.
+**Note:** On Windows the recommended way to run SubMiner is with the **SubMiner mpv** shortcut created during first-run setup — double-click it, drag files onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See the [Windows mpv Shortcut](https://docs.subminer.moe/usage#windows-mpv-shortcut) section for details.

 </details>

@@ -250,23 +248,12 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 subminer app --setup            # launch the first-run setup wizard
 ```

-SubMiner creates a default config, starts in the system tray, and opens a setup popup that walks you through installing the mpv plugin and configuring Yomitan dictionaries. Follow the on-screen steps to complete setup.
-
-Jellyfin setup is available from the tray or `subminer jellyfin`; once Jellyfin is enabled with a server URL, the tray can toggle Jellyfin Discovery for the current app session.
+SubMiner creates a default config, starts in the system tray, and opens a setup popup that walks you through installing Yomitan dictionaries. Follow the on-screen steps to complete setup.

 > [!NOTE]
 > On Windows, run `SubMiner.exe` directly — it opens the setup wizard automatically on first launch.

-### 3. Verify Setup
-
-```bash
-subminer doctor                 # verify mpv, ffmpeg, config, and socket
-```
-
-> [!NOTE]
-> On Windows, use `bun run subminer doctor` or run `SubMiner.exe` directly — first-run setup will guide you through dependency checks.
-
-### 4. Mine
+### 3. Mine

 ```bash
 subminer video.mkv          # play video with overlay
@@ -276,7 +263,7 @@ subminer stats -b           # stats daemon in background
 subminer stats -s           # stop background stats daemon
 ```

-On **Windows**, the `subminer` script must be run with `bun run subminer` (e.g. `bun run subminer video.mkv`). The recommended alternative is the **SubMiner mpv** shortcut (created during setup) or `SubMiner.exe --launch-mpv`. Drag a video file onto the shortcut to play it, or double-click it to open mpv with SubMiner's defaults.
+On **Windows**, use the **SubMiner mpv** shortcut created during first-run setup — double-click it to open mpv, or drag a video file onto it. You can also run `SubMiner.exe --launch-mpv` from a terminal.

 ## Documentation

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed macOS overlay tracking so transient mpv window misses no longer hide the overlay; minimizing mpv still hides it.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed subtitle sync modal opens so macOS no longer flashes and hides the first modal attempt or leaves stale modal state after syncing.
@@ -2,6 +2,8 @@

 ## v0.14.0 (2026-05-12)

+SubMiner no longer requires a globally-installed mpv plugin. The bundled plugin is injected at runtime only when SubMiner launches mpv — through the `subminer` launcher, the app's managed launch, or the packaged Windows SubMiner mpv shortcut. When you open mpv on its own, SubMiner is not involved and the plugin is never loaded. If you have a legacy global SubMiner plugin under mpv's `scripts` directory, first-run setup detects it and prompts you to remove it before playback starts.
+
 **Added**

 - **Character Dictionary:** Added AniList-based character dictionary selection for resolving title mismatches — open it in-app with the new `Ctrl+Alt+A` shortcut or from the CLI with `subminer dictionary --candidates` / `--select`. Series-scoped overrides replace stale entries in the merged dictionary.
@@ -301,9 +301,6 @@ binary_path=/Applications/SubMiner.app/Contents/MacOS/subminer

 ## Windows

-> [!WARNING]
-> **Windows support is experimental.** Core features — mining, annotations, and dictionary lookups — work, but some functionality may be missing or unstable. Bug reports welcome.
-
 ### Prerequisites

 1. Install [`mpv`](https://mpv.io/installation/) and ensure `mpv.exe` is on `PATH`. If mpv is installed elsewhere, you can set `mpv.executablePath` in `config.jsonc` or use the first-run setup field to point at the executable.
@@ -333,7 +330,7 @@ The shortcut and `--launch-mpv` pass SubMiner's default IPC socket, subtitle arg

 ### Windows-Specific Notes

- The `subminer` launcher script requires [Bun](https://bun.sh) and must be invoked with `bun run subminer` on Windows since the shebang is not supported. The **SubMiner mpv** shortcut or `SubMiner.exe --launch-mpv` is the simpler alternative.
+- The **SubMiner mpv** shortcut created during first-run setup is the recommended way to launch playback on Windows. The `subminer` launcher script is primarily for Linux and macOS.
 - First-run plugin installs pin `binary_path` to the current `SubMiner.exe` automatically. Manual plugin configs can leave `binary_path` empty unless SubMiner is in a non-standard location.
 - Plugin installs rewrite `socket_path` to `\\.\pipe\subminer-socket` — do not keep `/tmp/subminer-socket` on Windows.
 - Config is stored at `%APPDATA%\SubMiner\config.jsonc`.
@@ -442,7 +439,7 @@ subminer doctor
 This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix any failures before continuing.

 > [!NOTE]
-> On Windows, use `bun run subminer doctor` or run `SubMiner.exe` directly. Replace `SubMiner.AppImage` with `SubMiner.exe` in the direct app commands below.
+> On Windows, run `SubMiner.exe` directly. Replace `SubMiner.AppImage` with `SubMiner.exe` in the direct app commands below.

 ## Optional Extras

@@ -3,7 +3,7 @@
 The `subminer` launcher is an all-in-one script that handles video selection, mpv startup, and overlay management. It is the recommended way to use SubMiner on Linux and macOS because it guarantees mpv is launched with the correct IPC socket and SubMiner defaults. It's a Bun script distributed as a release asset alongside the AppImage and DMG.

 ::: tip Windows users
-On Windows the `subminer` script cannot run directly via shebang — use `bun run subminer` instead (e.g. `bun run subminer video.mkv`). The recommended alternative is the **SubMiner mpv** shortcut created during first-run setup, or `SubMiner.exe --launch-mpv`. See [Windows mpv Shortcut](/usage#windows-mpv-shortcut) for details.
+On Windows, the recommended way to launch playback is the **SubMiner mpv** shortcut created during first-run setup — double-click it, drag a file onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See [Windows mpv Shortcut](/usage#windows-mpv-shortcut) for details.
 :::

 ## Video Picker
@@ -37,7 +37,7 @@ Field names must match your Anki note type exactly (case-sensitive). See [Anki I
 There are several ways to use SubMiner:

 > [!TIP]
-> **New users: start with the `subminer` wrapper script** (or the **SubMiner mpv** shortcut on Windows). It handles mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`.
+> **New users on Linux/macOS: start with the `subminer` wrapper script.** On Windows, use the **SubMiner mpv** shortcut created during first-run setup. Both handle mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`.

 | Approach                            | Use when                                                                                                                                            | How                                                                   |
 | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
@@ -45,7 +45,7 @@ There are several ways to use SubMiner:
 | **SubMiner mpv shortcut** (Windows) | The recommended Windows entry point. Created during first-run setup, launches mpv with SubMiner's defaults directly.                                | Double-click, drag a file onto it, or run `SubMiner.exe --launch-mpv` |
 | **MPV plugin** (all platforms)      | You launch mpv yourself or from another tool (file manager, Jellyfin, etc.). Requires `--input-ipc-server=/tmp/subminer-socket` in your mpv config. | Use `y` chord keybindings inside mpv                                  |

-You can use both — the plugin provides in-player controls, while the `subminer` script (or the Windows shortcut) is convenient for direct playback. The `subminer` script runs directly via shebang on Linux and macOS (no `bun run` needed); on Windows it must be invoked with `bun run subminer` since the shebang is not supported.
+You can use both — the plugin provides in-player controls, while the `subminer` script (Linux/macOS) or the SubMiner mpv shortcut (Windows) is convenient for direct playback.

 ## Live Config Reload

@@ -1,50 +0,0 @@
-## Highlights
-### Added
-
- **Character Dictionary:** Added AniList-based selection to resolve character dictionary mismatches, with series-scoped overrides that replace stale entries. Available via `subminer dictionary --candidates` / `--select` and a default `Ctrl+Alt+A` in-app shortcut.
- **Subtitle Bar Toggle:** Added a `V` shortcut and mpv binding to toggle the primary subtitle bar independently of mpv's native subtitle display.
- **Texthooker:** Added `subminer texthooker -o` and a tray menu item to open the local texthooker page in the default browser.
-
-### Changed
-
- **mpv Plugin Setup:** Managed launches now inject the bundled plugin automatically. The setup flow can trash detected legacy global plugin files before launch, and legacy global install entrypoints have been removed so regular mpv playback is unaffected.
- **Tray Menu:** Replaced "Open Overlay" with "Open Help," which opens the session help modal.
- **Stats Exclusions:** Vocabulary exclusions now persist in the immersion database and migrate existing browser-local exclusions on first load.
- **Config Defaults:** Disabled texthooker startup, subtitle, and annotation websocket servers by default. Fresh installs now use a Japanese font stack, transparent subtitle backgrounds, stronger text shadows, and teal N4/fourth-band coloring for primary subtitles. Yomitan popup auto-pause remains enabled.
- **Config Example:** The generated example config now lists every built-in keybinding default.
-
-### Fixed
-
- **Subtitle Annotations — Grammar Filtering:** Suppressed N+1, JLPT, frequency, and name styling on grammar-only tokens: standalone interjections (`あ`, katakana variants), kana grammar helpers (`ことに`), auxiliary inflection fragments (`れる`, `れた`), polite copula tails (`です`, `じゃないですか`), standalone particles matched by known-word decks, and existence verbs (`ある`/`有る`). Known-word highlighting is preserved where applicable.
- **Subtitle Annotations — Color Priority:** Fixed token color priority so typography settings are preserved, JLPT colors no longer override higher-priority known-word or frequency colors, JLPT underlines persist at their correct color after dictionary lookups and when a token also carries known-word or frequency annotations, and frequency highlighting works correctly for ordinal prefix-noun tokens like `第二`.
- **Subtitle Annotations — Other:** Stopped kana-only tokens from being selected as N+1 targets; preserved Yomitan compound tokens so known component words no longer color a larger unknown word green; kept annotation prefetch running after immediate cache-hit renders; added a brightness lift for annotated token hover states when hover backgrounds are transparent; accepted `subtitleStyle.hoverBackground` as an alias for `subtitleStyle.hoverTokenBackgroundColor`; refreshed the current subtitle after successful card mining so newly known words recolor immediately.
- **Subtitle Bar:** Changed `v` to cycle the primary subtitle bar through visible, hover, and hidden modes with OSD feedback. Added `subtitleStyle.primaryDefaultMode` to set the startup visibility default independently from secondary subtitles.
- **Tokenizer:** Now uses Yomitan `wordClasses` metadata for part-of-speech filtering, and backfills blank MeCab POS fields during parser enrichment.
- **Overlay (Linux):** Fixed multi-line subtitle copy timing out after the prompt; follow-up number-row digits are now accepted for multi-line mining even when the original shortcut modifiers are still held.
- **Overlay (Hyprland):** Fixed fullscreen transitions so overlay geometry refreshes on mpv fullscreen changes, topmost stacking is reasserted, and hover pause works correctly after resize/toggle cycles. Overlay windows now align precisely to mpv bounds with floating decoration disabled; the stats overlay is opaque to prevent mpv bleed-through at the top edge; overlay windows no longer pin across workspaces.
- **Overlay (macOS):** Kept the overlay visible and interactive during transient tracker refreshes while mpv is the active tracked window, and kept it behind unrelated foreground windows while remaining above mpv.
- **Overlay:** Keyboard-only Yomitan popup shortcuts now take precedence over overlay keybindings like `j`; the browser focus outline is hidden so focused overlays no longer show a yellow/orange viewport border.
- **Default Keybindings:** Fixed replay/next subtitle keybindings — session help moved to `Ctrl/Cmd+/`, freeing `Ctrl+Shift+H` and `Ctrl+Shift+L` for subtitle playback controls. `Ctrl+Shift+L` now correctly reaches play-next-subtitle, and play-next resumes from a paused state before pausing again at the subtitle end.
- **Anki:** Manual clipboard subtitle updates preserve existing word audio while replacing sentence audio, animated-image media, and expression fields — even when audio overwrite is configured off.
- **AniList:** Post-watch progress checks now run on time-position updates using the fresh mpv position; manual mark-watched forces a progress sync; missing episode metadata is filled from the filename parser. Duplicate writes during concurrent checks are prevented, and manual watched marks are preserved when sync fails.
- **AniList (Linux):** Retried safeStorage availability after transient keyring failures so tokens can load and save once the keyring becomes available. Prevented config reload from opening the setup window during playback when token storage cannot be resolved, and stopped the setup flow from reporting success when token persistence fails.
- **mpv:** Stopped mpv from holding SubMiner subprocesses during shutdown, preventing desktop crash notifications on video close. Kept the overlay alive across same-media buffering reloads to avoid duplicate startup gates and AniSkip lookups; playlist navigation now reuses the running overlay without repeating the pause-until-ready warmup gate.
- **Launcher:** Managed playback now exits the background SubMiner app when the video closes; explicit background launches remain persistent.
- **Stats:** Background mode routes through the isolated stats daemon; app startup defers to an already-running daemon instead of failing when the port is already in use. Fixed recent session detail pages showing "Media not found" before lifetime media summaries are available.
- **Jellyfin:** Improved setup with recent server selection and inline authentication feedback. Added a tray toggle for runtime-only cast discovery.
-
-### Docs
-
- Improved the docs homepage with canonical URLs and a cleaner sitemap.
-
-## Installation
-
-See the README and docs/installation guide for full setup steps.
-
-## Assets
-
- Linux: `SubMiner.AppImage`
- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
-
-Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
@@ -25,6 +25,11 @@ private struct WindowState {
    let focused: Bool
 }

+private enum WindowLookupResult {
+    case visible(WindowState)
+    case minimized
+}
+
 private let targetMpvSocketPath: String? = {
    guard CommandLine.arguments.count > 1 else {
        return nil
@@ -145,7 +150,7 @@ private func frontmostApplicationPid() -> pid_t? {
    NSWorkspace.shared.frontmostApplication?.processIdentifier
 }

-private func windowStateFromAccessibilityAPI() -> WindowState? {
+private func windowStateFromAccessibilityAPI() -> WindowLookupResult? {
    let runningApps = NSWorkspace.shared.runningApplications.filter { app in
        guard let name = app.localizedName else {
            return false
@@ -154,6 +159,7 @@ private func windowStateFromAccessibilityAPI() -> WindowState? {
    }

    let frontmostPid = frontmostApplicationPid()
+    var foundMinimizedTargetWindow = false

    for app in runningApps {
        let appElement = AXUIElementCreateApplication(app.processIdentifier)
@@ -171,6 +177,7 @@ private func windowStateFromAccessibilityAPI() -> WindowState? {
            var minimizedRef: CFTypeRef?
            let minimizedStatus = AXUIElementCopyAttributeValue(window, kAXMinimizedAttribute as CFString, &minimizedRef)
            if minimizedStatus == .success, let minimized = minimizedRef as? Bool, minimized {
+                foundMinimizedTargetWindow = true
                continue
            }

@@ -184,14 +191,20 @@ private func windowStateFromAccessibilityAPI() -> WindowState? {
            }

            if let geometry = geometryFromAXWindow(window) {
-                return WindowState(
-                    geometry: geometry,
-                    focused: frontmostPid == windowPid
+                return .visible(
+                    WindowState(
+                        geometry: geometry,
+                        focused: frontmostPid == windowPid
+                    )
                )
            }
        }
    }

+    if foundMinimizedTargetWindow {
+        return .minimized
+    }
+
    return nil
 }

@@ -250,10 +263,25 @@ private func windowStateFromCoreGraphics() -> WindowState? {
    return nil
 }

-if let window = windowStateFromAccessibilityAPI() ?? windowStateFromCoreGraphics() {
-    print(
-        "\(window.geometry.x),\(window.geometry.y),\(window.geometry.width),\(window.geometry.height),\(window.focused ? 1 : 0)"
-    )
+private let lookupResult: WindowLookupResult? = {
+    if let axResult = windowStateFromAccessibilityAPI() {
+        return axResult
+    }
+    if let cgWindow = windowStateFromCoreGraphics() {
+        return .visible(cgWindow)
+    }
+    return nil
+}()
+
+if let result = lookupResult {
+    switch result {
+    case .visible(let window):
+        print(
+            "\(window.geometry.x),\(window.geometry.y),\(window.geometry.width),\(window.geometry.height),\(window.focused ? 1 : 0)"
+        )
+    case .minimized:
+        print("minimized")
+    }
 } else {
    print("not-found")
 }
@@ -547,7 +547,7 @@ test('initializeOverlayRuntime hides overlay windows when tracker loses the targ
  assert.deepEqual(calls, ['hide-visible', 'hide-modal', 'sync-shortcuts']);
 });

-test('initializeOverlayRuntime hides visible overlay on Windows tracker loss when target is not minimized', () => {
+test('initializeOverlayRuntime refreshes visible overlay on tracker loss when target is not minimized', () => {
  const calls: string[] = [];
  const tracker = {
    onGeometryChange: null as ((...args: unknown[]) => void) | null,
@@ -600,7 +600,7 @@ test('initializeOverlayRuntime hides visible overlay on Windows tracker loss whe
  calls.length = 0;
  tracker.onWindowLost?.();

-  assert.deepEqual(calls, ['hide-visible', 'sync-shortcuts']);
+  assert.deepEqual(calls, ['update-visible']);
 });

 test('initializeOverlayRuntime restores overlay bounds and visibility when tracker finds the target window again', () => {
@@ -105,10 +105,14 @@ export function initializeOverlayRuntime(options: {
    };
    windowTracker.onWindowLost = () => {
      options.releaseOverlayOwner?.();
-      for (const window of options.getOverlayWindows()) {
-        window.hide();
+      if (windowTracker.isTargetWindowMinimized()) {
+        for (const window of options.getOverlayWindows()) {
+          window.hide();
+        }
+        options.syncOverlayShortcuts();
+        return;
      }
-      options.syncOverlayShortcuts();
+      options.updateVisibleOverlayVisibility();
    };
    windowTracker.onWindowFocusChange = () => {
      if (options.isVisibleOverlayVisible()) {
@@ -1398,6 +1398,55 @@ test('macOS preserves visible overlay during transient tracker loss with retaine
  assert.ok(!calls.includes('show'));
 });

+test('macOS preserves visible overlay level during non-minimized tracker loss', () => {
+  const { window, calls } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => false,
+    getGeometry: () => null,
+    isTargetWindowFocused: () => false,
+    isTargetWindowMinimized: () => false,
+  };
+
+  window.show();
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    showOverlayLoadingOsd: () => {
+      calls.push('loading-osd');
+    },
+  } as never);
+
+  assert.ok(calls.includes('sync-layer'));
+  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(calls.includes('enforce-order'));
+  assert.ok(calls.includes('sync-shortcuts'));
+  assert.ok(!calls.includes('hide'));
+  assert.ok(!calls.includes('always-on-top:false'));
+  assert.ok(!calls.includes('loading-osd'));
+});
+
 test('macOS suppresses immediate repeat loading OSD after tracker recovery until cooldown expires', () => {
  const { window } = createMainWindowRecorder();
  const osdMessages: string[] = [];
@@ -94,13 +94,27 @@ export function updateVisibleOverlayVisibility(args: {
    const wasVisible = mainWindow.isVisible();
    const isVisibleOverlayFocused =
      typeof mainWindow.isFocused === 'function' && mainWindow.isFocused();
+    const windowTracker = args.windowTracker;
+    const canReportMacOSTargetMinimized =
+      args.isMacOSPlatform && typeof windowTracker?.isTargetWindowMinimized === 'function';
+    const isTrackedMacOSTargetMinimized =
+      canReportMacOSTargetMinimized &&
+      windowTracker?.isTargetWindowMinimized() === true;
+    const hasTransientMacOSTrackerLoss =
+      args.isMacOSPlatform &&
+      canReportMacOSTargetMinimized &&
+      !!windowTracker &&
+      !windowTracker.isTracking() &&
+      !isTrackedMacOSTargetMinimized &&
+      mainWindow.isVisible();
    const isTrackedMacOSTargetFocused =
-      !args.isMacOSPlatform || !args.windowTracker
+      hasTransientMacOSTrackerLoss || !args.isMacOSPlatform || !args.windowTracker
        ? true
        : (args.windowTracker.isTargetWindowFocused?.() ?? true);
    const shouldReleaseMacOSOverlayLevel =
      args.isMacOSPlatform &&
      !!args.windowTracker &&
+      !hasTransientMacOSTrackerLoss &&
      !isVisibleOverlayFocused &&
      !isTrackedMacOSTargetFocused;
    const shouldDefaultToPassthrough =
@@ -274,9 +288,17 @@ export function updateVisibleOverlayVisibility(args: {
  const hasRetainedTrackedGeometry = args.windowTracker.getGeometry() !== null;
  const hasActiveMacOSTargetSignal =
    args.isMacOSPlatform && (args.windowTracker.isTargetWindowFocused?.() ?? false);
+  const canReportMacOSTargetMinimized =
+    args.isMacOSPlatform && typeof args.windowTracker.isTargetWindowMinimized === 'function';
+  const isTrackedMacOSTargetMinimized =
+    canReportMacOSTargetMinimized &&
+    args.windowTracker.isTargetWindowMinimized();
  const shouldPreserveTransientTrackedOverlay =
    (args.isMacOSPlatform &&
-      (hasRetainedTrackedGeometry || (mainWindow.isVisible() && hasActiveMacOSTargetSignal))) ||
+      !isTrackedMacOSTargetMinimized &&
+      (hasRetainedTrackedGeometry ||
+        (mainWindow.isVisible() && hasActiveMacOSTargetSignal) ||
+        (canReportMacOSTargetMinimized && mainWindow.isVisible()))) ||
    (args.isWindowsPlatform &&
      typeof args.windowTracker.isTargetWindowMinimized === 'function' &&
      !args.windowTracker.isTargetWindowMinimized());
@@ -473,13 +473,13 @@ import { createOverlayModalInputState } from './main/runtime/overlay-modal-input
 import { openYoutubeTrackPicker } from './main/runtime/youtube-picker-open';
 import { openRuntimeOptionsModal as openRuntimeOptionsModalRuntime } from './main/runtime/runtime-options-open';
 import { openJimakuModal as openJimakuModalRuntime } from './main/runtime/jimaku-open';
+import { openSubsyncManualModal as openSubsyncManualModalRuntime } from './main/runtime/subsync-open';
 import { openSessionHelpModal as openSessionHelpModalRuntime } from './main/runtime/session-help-open';
 import { openCharacterDictionaryModal as openCharacterDictionaryModalRuntime } from './main/runtime/character-dictionary-open';
 import { openControllerSelectModal as openControllerSelectModalRuntime } from './main/runtime/controller-select-open';
 import { openControllerDebugModal as openControllerDebugModalRuntime } from './main/runtime/controller-debug-open';
 import { createPlaylistBrowserIpcRuntime } from './main/runtime/playlist-browser-ipc';
 import { writeSessionBindingsArtifact } from './main/runtime/session-bindings-artifact';
-import { openOverlayHostedModal } from './main/runtime/overlay-hosted-modal-open';
 import { createOverlayShortcutsRuntimeService } from './main/overlay-shortcuts-runtime';
 import {
  createFrequencyDictionaryRuntimeService,
@@ -1406,9 +1406,11 @@ const buildMainSubsyncRuntimeMainDepsHandler = createBuildMainSubsyncRuntimeMain
  },
  showMpvOsd: (text) => showMpvOsd(text),
  openManualPicker: (payload) => {
-    sendToActiveOverlayWindow('subsync:open-manual', payload, {
-      restoreOnModalClose: 'subsync',
-    });
+    openOverlayHostedModalWithOsd(
+      (deps) => openSubsyncManualModalRuntime(deps, payload),
+      'Subsync overlay unavailable.',
+      'Failed to open subsync overlay.',
+    );
  },
 });
 const immersionMediaRuntime = createImmersionMediaRuntime(
@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { openSubsyncManualModal } from './subsync-open';
+import type { SubsyncManualPayload } from '../../types';
+
+const payload: SubsyncManualPayload = {
+  sourceTracks: [{ id: 2, label: 'External #2 - eng' }],
+};
+
+test('subsync manual open prefers dedicated modal window on first attempt', async () => {
+  const sends: Array<{
+    channel: string;
+    payload: SubsyncManualPayload;
+    options: {
+      restoreOnModalClose: 'subsync';
+      preferModalWindow: boolean;
+    };
+  }> = [];
+
+  const opened = await openSubsyncManualModal(
+    {
+      ensureOverlayStartupPrereqs: () => {},
+      ensureOverlayWindowsReadyForVisibilityActions: () => {},
+      sendToActiveOverlayWindow: (channel, nextPayload, options) => {
+        sends.push({
+          channel,
+          payload: nextPayload as SubsyncManualPayload,
+          options: options as {
+            restoreOnModalClose: 'subsync';
+            preferModalWindow: boolean;
+          },
+        });
+        return true;
+      },
+      waitForModalOpen: async (modal, timeoutMs) => {
+        assert.equal(modal, 'subsync');
+        assert.equal(timeoutMs, 1500);
+        return true;
+      },
+      logWarn: () => {
+        throw new Error('should not warn on first-attempt success');
+      },
+    },
+    payload,
+  );
+
+  assert.equal(opened, true);
+  assert.deepEqual(sends, [
+    {
+      channel: 'subsync:open-manual',
+      payload,
+      options: {
+        restoreOnModalClose: 'subsync',
+        preferModalWindow: true,
+      },
+    },
+  ]);
+});
+
+test('subsync manual open retries on the dedicated modal window after open timeout', async () => {
+  const preferModalWindowValues: boolean[] = [];
+  const warnings: string[] = [];
+  let waitCalls = 0;
+
+  const opened = await openSubsyncManualModal(
+    {
+      ensureOverlayStartupPrereqs: () => {},
+      ensureOverlayWindowsReadyForVisibilityActions: () => {},
+      sendToActiveOverlayWindow: (_channel, _payload, options) => {
+        preferModalWindowValues.push(Boolean(options?.preferModalWindow));
+        return true;
+      },
+      waitForModalOpen: async () => {
+        waitCalls += 1;
+        return waitCalls === 2;
+      },
+      logWarn: (message) => {
+        warnings.push(message);
+      },
+    },
+    payload,
+  );
+
+  assert.equal(opened, true);
+  assert.deepEqual(preferModalWindowValues, [true, true]);
+  assert.deepEqual(warnings, [
+    'Subsync modal did not acknowledge modal open on first attempt; retrying dedicated modal window.',
+  ]);
+});
+
+test('subsync manual open fails when the dedicated modal window cannot be targeted', async () => {
+  let waitCalls = 0;
+
+  const opened = await openSubsyncManualModal(
+    {
+      ensureOverlayStartupPrereqs: () => {},
+      ensureOverlayWindowsReadyForVisibilityActions: () => {},
+      sendToActiveOverlayWindow: () => false,
+      waitForModalOpen: async () => {
+        waitCalls += 1;
+        return true;
+      },
+      logWarn: () => {},
+    },
+    payload,
+  );
+
+  assert.equal(opened, false);
+  assert.equal(waitCalls, 0);
+});
@@ -0,0 +1,53 @@
+import type { OverlayHostedModal } from '../../shared/ipc/contracts';
+import { IPC_CHANNELS } from '../../shared/ipc/contracts';
+import type { SubsyncManualPayload } from '../../types';
+import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
+
+const SUBSYNC_MODAL: OverlayHostedModal = 'subsync';
+const SUBSYNC_OPEN_TIMEOUT_MS = 1500;
+
+export async function openSubsyncManualModal(
+  deps: {
+    ensureOverlayStartupPrereqs: () => void;
+    ensureOverlayWindowsReadyForVisibilityActions: () => void;
+    sendToActiveOverlayWindow: (
+      channel: string,
+      payload?: unknown,
+      runtimeOptions?: {
+        restoreOnModalClose?: OverlayHostedModal;
+        preferModalWindow?: boolean;
+      },
+    ) => boolean;
+    waitForModalOpen: (modal: OverlayHostedModal, timeoutMs: number) => Promise<boolean>;
+    logWarn: (message: string) => void;
+  },
+  payload: SubsyncManualPayload,
+): Promise<boolean> {
+  return await retryOverlayModalOpen(
+    {
+      waitForModalOpen: deps.waitForModalOpen,
+      logWarn: deps.logWarn,
+    },
+    {
+      modal: SUBSYNC_MODAL,
+      timeoutMs: SUBSYNC_OPEN_TIMEOUT_MS,
+      retryWarning:
+        'Subsync modal did not acknowledge modal open on first attempt; retrying dedicated modal window.',
+      sendOpen: () =>
+        openOverlayHostedModal(
+          {
+            ensureOverlayStartupPrereqs: deps.ensureOverlayStartupPrereqs,
+            ensureOverlayWindowsReadyForVisibilityActions:
+              deps.ensureOverlayWindowsReadyForVisibilityActions,
+            sendToActiveOverlayWindow: deps.sendToActiveOverlayWindow,
+          },
+          {
+            channel: IPC_CHANNELS.event.subsyncOpenManual,
+            modal: SUBSYNC_MODAL,
+            payload,
+            preferModalWindow: true,
+          },
+        ),
+    },
+  );
+}
@@ -1,6 +1,14 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { MacOSWindowTracker } from './macos-tracker';
+import { MacOSWindowTracker, parseMacOSHelperOutput } from './macos-tracker';
+
+test('parseMacOSHelperOutput parses minimized state', () => {
+  assert.deepEqual(parseMacOSHelperOutput('minimized'), {
+    geometry: null,
+    focused: false,
+    minimized: true,
+  });
+});

 test('MacOSWindowTracker keeps the last geometry through a single helper miss', async () => {
  let callIndex = 0;
@@ -170,3 +178,40 @@ test('MacOSWindowTracker drops tracking after grace window expires', async () =>
  assert.equal(tracker.isTracking(), false);
  assert.equal(tracker.getGeometry(), null);
 });
+
+test('MacOSWindowTracker reports minimized target when helper reports minimized', async () => {
+  let callIndex = 0;
+  let now = 1_000;
+  const outputs = [
+    { stdout: '10,20,1280,720,1', stderr: '' },
+    { stdout: 'minimized', stderr: '' },
+    { stdout: 'minimized', stderr: '' },
+  ];
+
+  const tracker = new MacOSWindowTracker('/tmp/mpv.sock', {
+    resolveHelper: () => ({
+      helperPath: 'helper.swift',
+      helperType: 'swift',
+    }),
+    runHelper: async () => outputs[callIndex++] ?? outputs.at(-1)!,
+    now: () => now,
+    minimizedTrackingLossGraceMs: 200,
+  });
+
+  (tracker as unknown as { pollGeometry: () => void }).pollGeometry();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(tracker.isTracking(), true);
+  assert.equal(tracker.isTargetWindowMinimized(), false);
+
+  now += 250;
+  (tracker as unknown as { pollGeometry: () => void }).pollGeometry();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(tracker.isTargetWindowMinimized(), true);
+  assert.equal(tracker.isTracking(), true);
+
+  now += 250;
+  (tracker as unknown as { pollGeometry: () => void }).pollGeometry();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(tracker.isTargetWindowMinimized(), true);
+  assert.equal(tracker.isTracking(), false);
+});
@@ -40,13 +40,21 @@ type MacOSTrackerDeps = {
  ) => Promise<MacOSTrackerRunnerResult>;
  maxConsecutiveMisses?: number;
  trackingLossGraceMs?: number;
+  minimizedTrackingLossGraceMs?: number;
  now?: () => number;
 };

-export interface MacOSHelperWindowState {
-  geometry: WindowGeometry;
-  focused: boolean;
-}
+export type MacOSHelperWindowState =
+  | {
+      geometry: WindowGeometry;
+      focused: boolean;
+      minimized?: false;
+    }
+  | {
+      geometry: null;
+      focused: false;
+      minimized: true;
+    };

 function runHelperWithExecFile(
  helperPath: string,
@@ -84,6 +92,13 @@ function runHelperWithExecFile(

 export function parseMacOSHelperOutput(result: string): MacOSHelperWindowState | null {
  const trimmed = result.trim();
+  if (trimmed === 'minimized') {
+    return {
+      geometry: null,
+      focused: false,
+      minimized: true,
+    };
+  }
  if (!trimmed || trimmed === 'not-found') {
    return null;
  }
@@ -137,9 +152,11 @@ export class MacOSWindowTracker extends BaseWindowTracker {
  ) => Promise<MacOSTrackerRunnerResult>;
  private readonly maxConsecutiveMisses: number;
  private readonly trackingLossGraceMs: number;
+  private readonly minimizedTrackingLossGraceMs: number;
  private readonly now: () => number;
  private consecutiveMisses = 0;
  private trackingLossStartedAtMs: number | null = null;
+  private targetWindowMinimized = false;

  constructor(targetMpvSocketPath?: string, deps: MacOSTrackerDeps = {}) {
    super();
@@ -147,6 +164,10 @@ export class MacOSWindowTracker extends BaseWindowTracker {
    this.runHelper = deps.runHelper ?? runHelperWithExecFile;
    this.maxConsecutiveMisses = Math.max(1, Math.floor(deps.maxConsecutiveMisses ?? 2));
    this.trackingLossGraceMs = Math.max(0, Math.floor(deps.trackingLossGraceMs ?? 1_500));
+    this.minimizedTrackingLossGraceMs = Math.max(
+      0,
+      Math.floor(deps.minimizedTrackingLossGraceMs ?? 500),
+    );
    this.now = deps.now ?? (() => Date.now());
    const resolvedHelper = deps.resolveHelper?.() ?? null;
    if (resolvedHelper) {
@@ -259,28 +280,32 @@ export class MacOSWindowTracker extends BaseWindowTracker {
    }
  }

+  override isTargetWindowMinimized(): boolean {
+    return this.targetWindowMinimized;
+  }
+
  private resetTrackingLossState(): void {
    this.consecutiveMisses = 0;
    this.trackingLossStartedAtMs = null;
  }

-  private shouldDropTracking(): boolean {
+  private shouldDropTracking(graceMs = this.trackingLossGraceMs): boolean {
    if (!this.isTracking()) {
      return true;
    }
-    if (this.trackingLossGraceMs === 0) {
+    if (graceMs === 0) {
      return this.consecutiveMisses >= this.maxConsecutiveMisses;
    }
    if (this.trackingLossStartedAtMs === null) {
      this.trackingLossStartedAtMs = this.now();
      return false;
    }
-    return this.now() - this.trackingLossStartedAtMs > this.trackingLossGraceMs;
+    return this.now() - this.trackingLossStartedAtMs > graceMs;
  }

-  private registerTrackingMiss(): void {
+  private registerTrackingMiss(graceMs = this.trackingLossGraceMs): void {
    this.consecutiveMisses += 1;
-    if (this.shouldDropTracking()) {
+    if (this.shouldDropTracking(graceMs)) {
      this.updateGeometry(null);
      this.resetTrackingLossState();
    }
@@ -296,12 +321,20 @@ export class MacOSWindowTracker extends BaseWindowTracker {
      .then(({ stdout }) => {
        const parsed = parseMacOSHelperOutput(stdout || '');
        if (parsed) {
+          if (parsed.minimized) {
+            this.targetWindowMinimized = true;
+            this.updateTargetWindowFocused(false);
+            this.registerTrackingMiss(this.minimizedTrackingLossGraceMs);
+            return;
+          }
          this.resetTrackingLossState();
+          this.targetWindowMinimized = false;
          this.updateFocus(parsed.focused);
          this.updateGeometry(parsed.geometry);
          return;
        }

+        this.targetWindowMinimized = false;
        this.registerTrackingMiss();
      })
      .catch((error: unknown) => {
@@ -314,6 +347,7 @@ export class MacOSWindowTracker extends BaseWindowTracker {
            ? (error as { stderr: string }).stderr
            : '';
        this.maybeLogExecError(err, stderr);
+        this.targetWindowMinimized = false;
        this.registerTrackingMiss();
      })
      .finally(() => {