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

src/main/runtime/subsync-open.test.ts

@@ -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);
+});

src/main/runtime/subsync-open.ts

@@ -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,
+          },
+        ),
+    },
+  );
+}