feat: add app-owned YouTube subtitle flow with absPlayer-style parsing (#31)

* fix: harden preload argv parsing for popup windows

* fix: align youtube playback with shared overlay startup

* fix: unwrap mpv youtube streams for anki media mining

* docs: update docs for youtube subtitle and mining flow

* refactor: unify cli and runtime wiring for startup and youtube flow

* feat: update subtitle sidebar overlay behavior

* chore: add shared log-file source for diagnostics

* fix(ci): add changelog fragment for immersion changes

* fix: address CodeRabbit review feedback

* fix: persist canonical title from youtube metadata

* style: format stats library tab

* fix: address latest review feedback

* style: format stats library files

* test: stub launcher youtube deps in CI

* test: isolate launcher youtube flow deps

* test: stub launcher youtube deps in failing case

* test: force x11 backend in launcher ci harness

* test: address latest review feedback

* fix(launcher): preserve user YouTube ytdl raw options

* docs(backlog): update task tracking notes

* fix(immersion): special-case youtube media paths in runtime and tracking

* feat(stats): improve YouTube media metadata and picker key handling

* fix(ci): format stats media library hook

* fix: address latest CodeRabbit review items

* docs: update youtube release notes and docs

* feat: auto-load youtube subtitles before manual picker

* fix: restore app-owned youtube subtitle flow

* docs: update youtube playback docs and config copy

* refactor: remove legacy youtube launcher mode plumbing

* fix: refine youtube subtitle startup binding

* docs: clarify youtube subtitle startup behavior

* fix: address PR #31 latest review follow-ups

* fix: address PR #31 follow-up review comments

* test: harden youtube picker test harness

* udpate backlog

* fix: add timeout to youtube metadata probe

* docs: refresh youtube and stats docs

* update backlog

* update backlog

* chore: release v0.9.0

src/main/overlay-runtime.ts

@@ -16,11 +16,15 @@ export interface OverlayModalRuntime {
   sendToActiveOverlayWindow: (
     channel: string,
     payload?: unknown,
-    runtimeOptions?: { restoreOnModalClose?: OverlayHostedModal },
+    runtimeOptions?: {
+      restoreOnModalClose?: OverlayHostedModal;
+      preferModalWindow?: boolean;
+    },
   ) => boolean;
   openRuntimeOptionsPalette: () => void;
   handleOverlayModalClosed: (modal: OverlayHostedModal) => void;
   notifyOverlayModalOpened: (modal: OverlayHostedModal) => void;
+  waitForModalOpen: (modal: OverlayHostedModal, timeoutMs: number) => Promise<boolean>;
   getRestoreVisibleOverlayOnModalClose: () => Set<OverlayHostedModal>;
 }
 
@@ -33,7 +37,10 @@ export function createOverlayModalRuntimeService(
   options: OverlayModalRuntimeOptions = {},
 ): OverlayModalRuntime {
   const restoreVisibleOverlayOnModalClose = new Set<OverlayHostedModal>();
+  const modalOpenWaiters = new Map<OverlayHostedModal, Array<(opened: boolean) => void>>();
   let modalActive = false;
+  let mainWindowMousePassthroughForcedByModal = false;
+  let mainWindowHiddenByModal = false;
   let pendingModalWindowReveal: BrowserWindow | null = null;
   let pendingModalWindowRevealTimeout: ReturnType<typeof setTimeout> | null = null;
 
@@ -163,6 +170,54 @@ export function createOverlayModalRuntimeService(
     pendingModalWindowReveal = null;
   };
 
+  const setMainWindowMousePassthroughForModal = (enabled: boolean): void => {
+    const mainWindow = deps.getMainWindow();
+    if (!mainWindow || mainWindow.isDestroyed()) {
+      mainWindowMousePassthroughForcedByModal = false;
+      return;
+    }
+
+    if (enabled) {
+      if (!mainWindow.isVisible()) {
+        mainWindowMousePassthroughForcedByModal = false;
+        return;
+      }
+      mainWindow.setIgnoreMouseEvents(true, { forward: true });
+      mainWindowMousePassthroughForcedByModal = true;
+      return;
+    }
+
+    if (!mainWindowMousePassthroughForcedByModal) {
+      return;
+    }
+    mainWindow.setIgnoreMouseEvents(false);
+    mainWindowMousePassthroughForcedByModal = false;
+  };
+
+  const setMainWindowVisibilityForModal = (hidden: boolean): void => {
+    const mainWindow = deps.getMainWindow();
+    if (!mainWindow || mainWindow.isDestroyed()) {
+      mainWindowHiddenByModal = false;
+      return;
+    }
+
+    if (hidden) {
+      if (!mainWindow.isVisible()) {
+        mainWindowHiddenByModal = false;
+        return;
+      }
+      mainWindow.hide();
+      mainWindowHiddenByModal = true;
+      return;
+    }
+
+    if (!mainWindowHiddenByModal) {
+      return;
+    }
+    mainWindow.show();
+    mainWindowHiddenByModal = false;
+  };
+
   const scheduleModalWindowReveal = (window: BrowserWindow): void => {
     pendingModalWindowReveal = window;
     if (pendingModalWindowRevealTimeout !== null) {
@@ -182,9 +237,13 @@ export function createOverlayModalRuntimeService(
   const sendToActiveOverlayWindow = (
     channel: string,
     payload?: unknown,
-    runtimeOptions?: { restoreOnModalClose?: OverlayHostedModal },
+    runtimeOptions?: {
+      restoreOnModalClose?: OverlayHostedModal;
+      preferModalWindow?: boolean;
+    },
   ): boolean => {
     const restoreOnModalClose = runtimeOptions?.restoreOnModalClose;
+    const preferModalWindow = runtimeOptions?.preferModalWindow === true;
 
     const sendNow = (window: BrowserWindow): void => {
       ensureModalWindowInteractive(window);
@@ -198,7 +257,7 @@ export function createOverlayModalRuntimeService(
     if (restoreOnModalClose) {
       restoreVisibleOverlayOnModalClose.add(restoreOnModalClose);
       const mainWindow = getTargetOverlayWindow();
-      if (mainWindow && !mainWindow.isDestroyed() && mainWindow.isVisible()) {
+      if (!preferModalWindow && mainWindow && !mainWindow.isDestroyed() && mainWindow.isVisible()) {
         sendOrQueueForWindow(mainWindow, (window) => {
           if (payload === undefined) {
             window.webContents.send(channel);
@@ -255,6 +314,8 @@ export function createOverlayModalRuntimeService(
     if (restoreVisibleOverlayOnModalClose.size === 0) {
       clearPendingModalWindowReveal();
       notifyModalStateChange(false);
+      setMainWindowMousePassthroughForModal(false);
+      setMainWindowVisibilityForModal(false);
       if (modalWindow && !modalWindow.isDestroyed()) {
         modalWindow.hide();
       }
@@ -263,6 +324,11 @@ export function createOverlayModalRuntimeService(
 
   const notifyOverlayModalOpened = (modal: OverlayHostedModal): void => {
     if (!restoreVisibleOverlayOnModalClose.has(modal)) return;
+    const waiters = modalOpenWaiters.get(modal) ?? [];
+    modalOpenWaiters.delete(modal);
+    for (const resolve of waiters) {
+      resolve(true);
+    }
     notifyModalStateChange(true);
     const targetWindow = getActiveOverlayWindowForModalInput();
     clearPendingModalWindowReveal();
@@ -270,6 +336,12 @@ export function createOverlayModalRuntimeService(
       return;
     }
 
+    const modalWindow = deps.getModalWindow();
+    if (modalWindow && !modalWindow.isDestroyed() && targetWindow === modalWindow) {
+      setMainWindowMousePassthroughForModal(true);
+      setMainWindowVisibilityForModal(true);
+    }
+
     if (targetWindow.isVisible()) {
       targetWindow.setIgnoreMouseEvents(false);
       elevateModalWindow(targetWindow);
@@ -285,11 +357,34 @@ export function createOverlayModalRuntimeService(
     showModalWindow(targetWindow);
   };
 
+  const waitForModalOpen = async (
+    modal: OverlayHostedModal,
+    timeoutMs: number,
+  ): Promise<boolean> =>
+    await new Promise<boolean>((resolve) => {
+      const waiters = modalOpenWaiters.get(modal) ?? [];
+      const finish = (opened: boolean): void => {
+        clearTimeout(timeout);
+        resolve(opened);
+      };
+      waiters.push(finish);
+      modalOpenWaiters.set(modal, waiters);
+      const timeout = setTimeout(() => {
+        const current = modalOpenWaiters.get(modal) ?? [];
+        modalOpenWaiters.set(
+          modal,
+          current.filter((candidate) => candidate !== finish),
+        );
+        resolve(false);
+      }, timeoutMs);
+    });
+
   return {
     sendToActiveOverlayWindow,
     openRuntimeOptionsPalette,
     handleOverlayModalClosed,
     notifyOverlayModalOpened,
+    waitForModalOpen,
     getRestoreVisibleOverlayOnModalClose: () => restoreVisibleOverlayOnModalClose,
   };
 }