Refactor startup, queries, and workflow into focused modules (#36)

* chore(backlog): add mining workflow milestone and tasks * refactor: split character dictionary runtime modules * refactor: split shared type entrypoints * refactor: use bun serve for stats server * feat: add repo-local subminer workflow plugin * fix: add stats server node fallback * refactor: split immersion tracker query modules * chore: update backlog task records * refactor: migrate shared type imports * refactor: compose startup and setup window wiring * Add backlog tasks and launcher time helper tests - Track follow-up cleanup work in Backlog.md - Replace Date.now usage with shared nowMs helper - Add launcher args/parser and core regression tests * test: increase launcher test timeout for CI stability * fix: address CodeRabbit review feedback * refactor(main): extract remaining inline runtime logic from main * chore(backlog): update task notes and changelog fragment * refactor: split main boot phases * test: stabilize bun coverage reporting * Switch plausible endpoint and harden coverage lane parsing - update docs-site tracking to use the Plausible capture endpoint - tighten coverage lane argument and LCOV parsing checks - make script entrypoint use CommonJS main guard * Restrict docs analytics and build coverage input - limit Plausible init to docs.subminer.moe - build Yomitan before src coverage lane * fix(ci): normalize Windows shortcut paths for cross-platform tests * Fix verification and immersion-tracker grouping - isolate verifier artifacts and lease handling - switch weekly/monthly tracker cutoffs to calendar boundaries - tighten boot lifecycle and zip writer tests * fix: resolve CI type failures in boot and immersion query tests * fix: remove strict spread usage in Date mocks * fix: use explicit super args for MockDate constructors * Factor out mock date helper in tracker tests - reuse a shared `withMockDate` helper for date-sensitive query tests - make monthly rollup assertions key off `videoId` instead of row order * fix: use variadic array type for MockDate constructor args TS2367: fixed-length tuple made args.length === 0 unreachable. * refactor: remove unused createMainBootRuntimes/Handlers aggregate functions These functions were never called by production code — main.ts imports the individual composeBoot* re-exports directly. * refactor: remove boot re-export alias layer main.ts now imports directly from the runtime/composers and runtime/domains modules, eliminating the intermediate boot/ indirection. * refactor: consolidate 3 near-identical setup window factories Extract shared createSetupWindowHandler with a config parameter. Public API unchanged. * refactor: parameterize duplicated getAffected*Ids query helpers Four structurally identical functions collapsed into two parameterized helpers while preserving the existing public API. * refactor: inline identity composers (stats-startup, overlay-window) composeStatsStartupRuntime was a no-op that returned its input. composeOverlayWindowHandlers was a 1-line delegation. Both removed in favor of direct usage. * chore: remove unused token/queue file path constants from main.ts * fix: replace any types in boot services with proper signatures * refactor: deduplicate ensureDir into shared/fs-utils 5 copies of mkdir-p-if-not-exists consolidated into one shared module with ensureDir (directory path) and ensureDirForFile (file path) variants. * fix: tighten type safety in boot services - Add AppLifecycleShape and OverlayModalInputStateShape constraints so TAppLifecycleApp and TOverlayModalInputState generics are bounded - Remove unsafe `as { handleModalInputStateChange? }` cast — now directly callable via the constraint - Use `satisfies AppLifecycleShape` for structural validation on the appLifecycleApp object literal - Document Electron App.on incompatibility with simple signatures * refactor: inline subtitle-prefetch-runtime-composer The composer was a pure pass-through that destructured an object and reassembled it with the same fields. Inlined at the call site. * chore: consolidate duplicate import paths in main.ts * test: extract mpv composer test fixture factory to reduce duplication * test: add behavioral assertions to composer tests Upgrade 8 composer test files from shape-only typeof checks to behavioral assertions that invoke returned handlers and verify injected dependencies are actually called, following the mpv-runtime-composer pattern. * refactor: normalize import extensions in query modules * refactor: consolidate toDbMs into query-shared.ts * refactor: remove Node.js fallback from stats-server, use Bun only * Fix monthly rollup test expectations - Preserve multi-arg Date construction in mock helper - Align rollup assertions with the correct videoId * fix: address PR 36 CodeRabbit follow-ups * fix: harden coverage lane cleanup * fix(stats): fallback to node server when Bun.serve unavailable * fix(ci): restore coverage lane compatibility * chore(backlog): close TASK-242 * fix: address latest CodeRabbit review round * fix: guard disabled immersion retention windows * fix: migrate discord rpc wrapper * fix(ci): add changelog fragment for PR 36 * fix: stabilize macOS visible overlay toggle * fix: pin installed mpv plugin to current binary * fix: strip inline subtitle markup from sidebar cues * fix(renderer): restore subtitle sidebar mpv passthrough * feat(discord): add configurable presence style presets Replace the hardcoded "Mining and crafting (Anki cards)" meme message with a preset system. New `discordPresence.presenceStyle` option supports four presets: "default" (clean bilingual), "meme" (the OG Minecraft joke), "japanese" (fully JP), and "minimal". The default preset shows "Sentence Mining" with 日本語学習中 as the small image tooltip. Existing users can set presenceStyle to "meme" to keep the old behavior. * fix: finalize v0.10.0 release prep * docs: add subtitle sidebar guide and release note * chore(backlog): mark docs task done * fix: lazily resolve youtube playback socket path * chore(release): build v0.10.0 changelog * Revert "chore(release): build v0.10.0 changelog" This reverts commit 9741c0f020.
2026-04-03 06:12:07 -07:00 · 2026-03-29 16:16:29 -07:00
parent 2d4f2d1139
commit 35adf8299c
297 changed files with 17713 additions and 9147 deletions
--- a/src/main/runtime/anilist-post-watch-main-deps.test.ts
+++ b/src/main/runtime/anilist-post-watch-main-deps.test.ts
@@ -21,7 +21,7 @@ test('process next anilist retry update main deps builder maps callbacks', async
    now: () => 7,
  })();

-  assert.deepEqual(deps.nextReady(), { key: 'k', title: 't', episode: 1 });
+  assert.deepEqual(deps.nextReady(), { key: 'k', title: 't', season: null, episode: 1 });
  deps.refreshRetryQueueState();
  deps.setLastAttemptAt(1);
  deps.setLastError('x');
--- a/src/main/runtime/anilist-setup.test.ts
+++ b/src/main/runtime/anilist-setup.test.ts
@@ -84,51 +84,63 @@ test('findAnilistSetupDeepLinkArgvUrl returns null when missing', () => {
 });

 test('consumeAnilistSetupCallbackUrl persists token and closes window for callback URL', () => {
+  const originalDateNow = Date.now;
  const events: string[] = [];
-  const handled = consumeAnilistSetupCallbackUrl({
-    rawUrl: 'https://anilist.subminer.moe/#access_token=saved-token',
-    saveToken: (value: string) => events.push(`save:${value}`),
-    setCachedToken: (value: string) => events.push(`cache:${value}`),
-    setResolvedState: (timestampMs: number) =>
-      events.push(`state:${timestampMs > 0 ? 'ok' : 'bad'}`),
-    setSetupPageOpened: (opened: boolean) => events.push(`opened:${opened}`),
-    onSuccess: () => events.push('success'),
-    closeWindow: () => events.push('close'),
-  });
+  try {
+    Date.now = () => 120_000;
+    const handled = consumeAnilistSetupCallbackUrl({
+      rawUrl: 'https://anilist.subminer.moe/#access_token=saved-token',
+      saveToken: (value: string) => events.push(`save:${value}`),
+      setCachedToken: (value: string) => events.push(`cache:${value}`),
+      setResolvedState: (timestampMs: number) =>
+        events.push(`state:${timestampMs > 0 ? 'ok' : 'bad'}`),
+      setSetupPageOpened: (opened: boolean) => events.push(`opened:${opened}`),
+      onSuccess: () => events.push('success'),
+      closeWindow: () => events.push('close'),
+    });

-  assert.equal(handled, true);
-  assert.deepEqual(events, [
-    'save:saved-token',
-    'cache:saved-token',
-    'state:ok',
-    'opened:false',
-    'success',
-    'close',
-  ]);
+    assert.equal(handled, true);
+    assert.deepEqual(events, [
+      'save:saved-token',
+      'cache:saved-token',
+      'state:ok',
+      'opened:false',
+      'success',
+      'close',
+    ]);
+  } finally {
+    Date.now = originalDateNow;
+  }
 });

 test('consumeAnilistSetupCallbackUrl persists token for subminer deep link URL', () => {
+  const originalDateNow = Date.now;
  const events: string[] = [];
-  const handled = consumeAnilistSetupCallbackUrl({
-    rawUrl: 'subminer://anilist-setup?access_token=saved-token',
-    saveToken: (value: string) => events.push(`save:${value}`),
-    setCachedToken: (value: string) => events.push(`cache:${value}`),
-    setResolvedState: (timestampMs: number) =>
-      events.push(`state:${timestampMs > 0 ? 'ok' : 'bad'}`),
-    setSetupPageOpened: (opened: boolean) => events.push(`opened:${opened}`),
-    onSuccess: () => events.push('success'),
-    closeWindow: () => events.push('close'),
-  });
+  try {
+    Date.now = () => 120_000;
+    const handled = consumeAnilistSetupCallbackUrl({
+      rawUrl: 'subminer://anilist-setup?access_token=saved-token',
+      saveToken: (value: string) => events.push(`save:${value}`),
+      setCachedToken: (value: string) => events.push(`cache:${value}`),
+      setResolvedState: (timestampMs: number) =>
+        events.push(`state:${timestampMs > 0 ? 'ok' : 'bad'}`),
+      setSetupPageOpened: (opened: boolean) => events.push(`opened:${opened}`),
+      onSuccess: () => events.push('success'),
+      closeWindow: () => events.push('close'),
+    });

-  assert.equal(handled, true);
-  assert.deepEqual(events, [
-    'save:saved-token',
-    'cache:saved-token',
-    'state:ok',
-    'opened:false',
-    'success',
-    'close',
-  ]);
+    assert.equal(handled, true);
+    assert.deepEqual(events, [
+      'save:saved-token',
+      'cache:saved-token',
+      'state:ok',
+      'opened:false',
+      'success',
+      'close',
+    ]);
+  } finally {
+    Date.now = originalDateNow;
+  }
 });

 test('consumeAnilistSetupCallbackUrl ignores non-callback URLs', () => {
--- a/src/main/runtime/autoplay-ready-gate.test.ts
+++ b/src/main/runtime/autoplay-ready-gate.test.ts
@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAutoplayReadyGate } from './autoplay-ready-gate';
+
+test('autoplay ready gate suppresses duplicate media signals unless forced while paused', async () => {
+  const commands: Array<Array<string | boolean>> = [];
+  const scheduled: Array<() => void> = [];
+
+  const gate = createAutoplayReadyGate({
+    isAppOwnedFlowInFlight: () => false,
+    getCurrentMediaPath: () => '/media/video.mkv',
+    getCurrentVideoPath: () => null,
+    getPlaybackPaused: () => true,
+    getMpvClient: () =>
+      ({
+        connected: true,
+        requestProperty: async () => true,
+        send: ({ command }: { command: Array<string | boolean> }) => {
+          commands.push(command);
+        },
+      }) as never,
+    signalPluginAutoplayReady: () => {
+      commands.push(['script-message', 'subminer-autoplay-ready']);
+    },
+    schedule: (callback) => {
+      scheduled.push(callback);
+      return 1 as never;
+    },
+    logDebug: () => {},
+  });
+
+  gate.maybeSignalPluginAutoplayReady({ text: '字幕', tokens: null });
+  gate.maybeSignalPluginAutoplayReady({ text: '字幕', tokens: null });
+  gate.maybeSignalPluginAutoplayReady({ text: '字幕', tokens: null }, { forceWhilePaused: true });
+
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  const firstScheduled = scheduled.shift();
+  firstScheduled?.();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  assert.deepEqual(commands.filter((command) => command[0] === 'script-message'), [
+    ['script-message', 'subminer-autoplay-ready'],
+  ]);
+  assert.ok(
+    commands.some(
+      (command) =>
+        command[0] === 'set_property' && command[1] === 'pause' && command[2] === false,
+    ),
+  );
+  assert.equal(scheduled.length > 0, true);
+});
+
+test('autoplay ready gate retry loop does not re-signal plugin readiness', async () => {
+  const commands: Array<Array<string | boolean>> = [];
+  const scheduled: Array<() => void> = [];
+
+  const gate = createAutoplayReadyGate({
+    isAppOwnedFlowInFlight: () => false,
+    getCurrentMediaPath: () => '/media/video.mkv',
+    getCurrentVideoPath: () => null,
+    getPlaybackPaused: () => true,
+    getMpvClient: () =>
+      ({
+        connected: true,
+        requestProperty: async () => true,
+        send: ({ command }: { command: Array<string | boolean> }) => {
+          commands.push(command);
+        },
+      }) as never,
+    signalPluginAutoplayReady: () => {
+      commands.push(['script-message', 'subminer-autoplay-ready']);
+    },
+    schedule: (callback) => {
+      scheduled.push(callback);
+      return 1 as never;
+    },
+    logDebug: () => {},
+  });
+
+  gate.maybeSignalPluginAutoplayReady({ text: '字幕', tokens: null }, { forceWhilePaused: true });
+
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  for (const callback of scheduled.splice(0, 3)) {
+    callback();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+
+  assert.deepEqual(commands.filter((command) => command[0] === 'script-message'), [
+    ['script-message', 'subminer-autoplay-ready'],
+  ]);
+  assert.equal(
+    commands.filter(
+      (command) =>
+        command[0] === 'set_property' && command[1] === 'pause' && command[2] === false,
+    ).length > 0,
+    true,
+  );
+});
--- a/src/main/runtime/autoplay-ready-gate.ts
+++ b/src/main/runtime/autoplay-ready-gate.ts
@@ -0,0 +1,128 @@
+import type { SubtitleData } from '../../types';
+import { resolveAutoplayReadyMaxReleaseAttempts } from './startup-autoplay-release-policy';
+
+type MpvClientLike = {
+  connected?: boolean;
+  requestProperty: (property: string) => Promise<unknown>;
+  send: (payload: { command: Array<string | boolean> }) => void;
+};
+
+export type AutoplayReadyGateDeps = {
+  isAppOwnedFlowInFlight: () => boolean;
+  getCurrentMediaPath: () => string | null;
+  getCurrentVideoPath: () => string | null;
+  getPlaybackPaused: () => boolean | null;
+  getMpvClient: () => MpvClientLike | null;
+  signalPluginAutoplayReady: () => void;
+  schedule: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+  logDebug: (message: string) => void;
+};
+
+export function createAutoplayReadyGate(deps: AutoplayReadyGateDeps) {
+  let autoPlayReadySignalMediaPath: string | null = null;
+  let autoPlayReadySignalGeneration = 0;
+
+  const invalidatePendingAutoplayReadyFallbacks = (): void => {
+    autoPlayReadySignalMediaPath = null;
+    autoPlayReadySignalGeneration += 1;
+  };
+
+  const maybeSignalPluginAutoplayReady = (
+    payload: SubtitleData,
+    options?: { forceWhilePaused?: boolean },
+  ): void => {
+    if (deps.isAppOwnedFlowInFlight()) {
+      deps.logDebug('[autoplay-ready] suppressed while app-owned YouTube flow is active');
+      return;
+    }
+    if (!payload.text.trim()) {
+      return;
+    }
+
+    const mediaPath =
+      deps.getCurrentMediaPath()?.trim() ||
+      deps.getCurrentVideoPath()?.trim() ||
+      '__unknown__';
+    const duplicateMediaSignal = autoPlayReadySignalMediaPath === mediaPath;
+    const allowDuplicateWhilePaused =
+      options?.forceWhilePaused === true && deps.getPlaybackPaused() !== false;
+    const releaseRetryDelayMs = 200;
+    const maxReleaseAttempts = resolveAutoplayReadyMaxReleaseAttempts({
+      forceWhilePaused: options?.forceWhilePaused === true,
+      retryDelayMs: releaseRetryDelayMs,
+    });
+
+    const isPlaybackPaused = async (client: MpvClientLike): Promise<boolean> => {
+      try {
+        const pauseProperty = await client.requestProperty('pause');
+        if (typeof pauseProperty === 'boolean') {
+          return pauseProperty;
+        }
+        if (typeof pauseProperty === 'string') {
+          return pauseProperty.toLowerCase() !== 'no' && pauseProperty !== '0';
+        }
+        if (typeof pauseProperty === 'number') {
+          return pauseProperty !== 0;
+        }
+      } catch (error) {
+        deps.logDebug(
+          `[autoplay-ready] failed to read pause property for media ${mediaPath}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+
+      return true;
+    };
+
+    const attemptRelease = (playbackGeneration: number, attempt: number): void => {
+      void (async () => {
+        if (
+          autoPlayReadySignalMediaPath !== mediaPath ||
+          playbackGeneration !== autoPlayReadySignalGeneration
+        ) {
+          return;
+        }
+
+        const mpvClient = deps.getMpvClient();
+        if (!mpvClient?.connected) {
+          if (attempt < maxReleaseAttempts) {
+            deps.schedule(() => attemptRelease(playbackGeneration, attempt + 1), releaseRetryDelayMs);
+          }
+          return;
+        }
+
+        const shouldUnpause = await isPlaybackPaused(mpvClient);
+        if (!shouldUnpause) {
+          return;
+        }
+
+        mpvClient.send({ command: ['set_property', 'pause', false] });
+        if (attempt < maxReleaseAttempts) {
+          deps.schedule(() => attemptRelease(playbackGeneration, attempt + 1), releaseRetryDelayMs);
+        }
+      })();
+    };
+
+    if (duplicateMediaSignal && !allowDuplicateWhilePaused) {
+      return;
+    }
+
+    if (!duplicateMediaSignal) {
+      autoPlayReadySignalMediaPath = mediaPath;
+      const playbackGeneration = ++autoPlayReadySignalGeneration;
+      deps.signalPluginAutoplayReady();
+      attemptRelease(playbackGeneration, 0);
+      return;
+    }
+
+    const playbackGeneration = ++autoPlayReadySignalGeneration;
+    attemptRelease(playbackGeneration, 0);
+  };
+
+  return {
+    getAutoPlayReadySignalMediaPath: (): string | null => autoPlayReadySignalMediaPath,
+    invalidatePendingAutoplayReadyFallbacks,
+    maybeSignalPluginAutoplayReady,
+  };
+}
--- a/src/main/runtime/character-dictionary-auto-sync.ts
+++ b/src/main/runtime/character-dictionary-auto-sync.ts
@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { ensureDir } from '../../shared/fs-utils';
 import type { AnilistCharacterDictionaryProfileScope } from '../../types';
 import type {
  CharacterDictionarySnapshotProgressCallbacks,
@@ -63,12 +64,6 @@ export interface CharacterDictionaryAutoSyncRuntimeDeps {
  onSyncComplete?: (result: { mediaId: number; mediaTitle: string; changed: boolean }) => void;
 }

-function ensureDir(dirPath: string): void {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-}
-
 function normalizeMediaId(rawMediaId: number): number | null {
  const mediaId = Math.max(1, Math.floor(rawMediaId));
  return Number.isFinite(mediaId) ? mediaId : null;
--- a/src/main/runtime/composers/anilist-setup-composer.test.ts
+++ b/src/main/runtime/composers/anilist-setup-composer.test.ts
@@ -3,11 +3,14 @@ import assert from 'node:assert/strict';
 import { composeAnilistSetupHandlers } from './anilist-setup-composer';

 test('composeAnilistSetupHandlers returns callable setup handlers', () => {
+  const calls: string[] = [];
  const composed = composeAnilistSetupHandlers({
    notifyDeps: {
      hasMpvClient: () => false,
      showMpvOsd: () => {},
-      showDesktopNotification: () => {},
+      showDesktopNotification: (title, opts) => {
+        calls.push(`notify:${opts.body}`);
+      },
      logInfo: () => {},
    },
    consumeTokenDeps: {
@@ -37,4 +40,16 @@ test('composeAnilistSetupHandlers returns callable setup handlers', () => {
  assert.equal(typeof composed.consumeAnilistSetupTokenFromUrl, 'function');
  assert.equal(typeof composed.handleAnilistSetupProtocolUrl, 'function');
  assert.equal(typeof composed.registerSubminerProtocolClient, 'function');
+
+  // notifyAnilistSetup forwards to showDesktopNotification when no MPV client
+  composed.notifyAnilistSetup('Setup complete');
+  assert.deepEqual(calls, ['notify:Setup complete']);
+
+  // handleAnilistSetupProtocolUrl returns false for non-subminer URLs
+  const handled = composed.handleAnilistSetupProtocolUrl('https://other.example.com/');
+  assert.equal(handled, false);
+
+  // handleAnilistSetupProtocolUrl returns true for subminer:// URLs
+  const handledProtocol = composed.handleAnilistSetupProtocolUrl('subminer://anilist-setup?code=abc');
+  assert.equal(handledProtocol, true);
 });
--- a/src/main/runtime/composers/app-ready-composer.test.ts
+++ b/src/main/runtime/composers/app-ready-composer.test.ts
@@ -3,9 +3,13 @@ import test from 'node:test';
 import { composeAppReadyRuntime } from './app-ready-composer';

 test('composeAppReadyRuntime returns reload/critical/app-ready handlers', () => {
+  const calls: string[] = [];
  const composed = composeAppReadyRuntime({
    reloadConfigMainDeps: {
-      reloadConfigStrict: () => ({ ok: true, path: '/tmp/config.jsonc', warnings: [] }),
+      reloadConfigStrict: () => {
+        calls.push('reloadConfigStrict');
+        return { ok: true, path: '/tmp/config.jsonc', warnings: [] };
+      },
      logInfo: () => {},
      logWarning: () => {},
      showDesktopNotification: () => {},
@@ -79,4 +83,8 @@ test('composeAppReadyRuntime returns reload/critical/app-ready handlers', () =>
  assert.equal(typeof composed.reloadConfig, 'function');
  assert.equal(typeof composed.criticalConfigError, 'function');
  assert.equal(typeof composed.appReadyRuntimeRunner, 'function');
+
+  // reloadConfig invokes the injected reloadConfigStrict dep
+  composed.reloadConfig();
+  assert.deepEqual(calls, ['reloadConfigStrict']);
 });
--- a/src/main/runtime/composers/cli-startup-composer.test.ts
+++ b/src/main/runtime/composers/cli-startup-composer.test.ts
@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { CliArgs } from '../../../cli/args';
+import { composeCliStartupHandlers } from './cli-startup-composer';
+
+test('composeCliStartupHandlers returns callable CLI startup handlers', () => {
+  const calls: string[] = [];
+  const handlers = composeCliStartupHandlers({
+    cliCommandContextMainDeps: {
+      appState: {} as never,
+      setLogLevel: () => {},
+      texthookerService: {} as never,
+      getResolvedConfig: () => ({}) as never,
+      openExternal: async () => {},
+      logBrowserOpenError: () => {},
+      showMpvOsd: () => {},
+      initializeOverlayRuntime: () => {},
+      toggleVisibleOverlay: () => {},
+      openFirstRunSetupWindow: () => {},
+      setVisibleOverlayVisible: () => {},
+      copyCurrentSubtitle: () => {},
+      startPendingMultiCopy: () => {},
+      mineSentenceCard: async () => {},
+      startPendingMineSentenceMultiple: () => {},
+      updateLastCardFromClipboard: async () => {},
+      refreshKnownWordCache: async () => {},
+      triggerFieldGrouping: async () => {},
+      triggerSubsyncFromConfig: async () => {},
+      markLastCardAsAudioCard: async () => {},
+      getAnilistStatus: () => ({}) as never,
+      clearAnilistToken: () => {},
+      openAnilistSetupWindow: () => {},
+      openJellyfinSetupWindow: () => {},
+      getAnilistQueueStatus: () => ({}) as never,
+      processNextAnilistRetryUpdate: async () => ({ ok: true, message: 'done' }),
+      generateCharacterDictionary: async () =>
+        ({ zipPath: '/tmp/test.zip', fromCache: false, mediaId: 1, mediaTitle: 'Test', entryCount: 1 }),
+      runJellyfinCommand: async () => {},
+      runStatsCommand: async () => {},
+      runYoutubePlaybackFlow: async () => {},
+      openYomitanSettings: () => {},
+      cycleSecondarySubMode: () => {},
+      openRuntimeOptionsPalette: () => {},
+      printHelp: () => {},
+      stopApp: () => {},
+      hasMainWindow: () => false,
+      getMultiCopyTimeoutMs: () => 0,
+      schedule: () => 0 as never,
+      logInfo: () => {},
+      logWarn: () => {},
+      logError: () => {},
+    },
+    cliCommandRuntimeHandlerMainDeps: {
+      handleTexthookerOnlyModeTransitionMainDeps: {
+        isTexthookerOnlyMode: () => false,
+        ensureOverlayStartupPrereqs: () => {},
+        setTexthookerOnlyMode: () => {},
+        commandNeedsOverlayStartupPrereqs: () => false,
+        startBackgroundWarmups: () => {},
+        logInfo: () => {},
+      },
+      handleCliCommandRuntimeServiceWithContext: (args, _source, _ctx) => {
+        calls.push(`handleCommand:${(args as { command?: string }).command ?? 'unknown'}`);
+      },
+    },
+    initialArgsRuntimeHandlerMainDeps: {
+      getInitialArgs: () => null,
+      isBackgroundMode: () => false,
+      shouldEnsureTrayOnStartup: () => false,
+      shouldRunHeadlessInitialCommand: () => false,
+      ensureTray: () => {},
+      isTexthookerOnlyMode: () => false,
+      hasImmersionTracker: () => false,
+      getMpvClient: () => null,
+      commandNeedsOverlayStartupPrereqs: () => false,
+      commandNeedsOverlayRuntime: () => false,
+      ensureOverlayStartupPrereqs: () => {},
+      isOverlayRuntimeInitialized: () => false,
+      initializeOverlayRuntime: () => {},
+      logInfo: () => {},
+    },
+  });
+
+  assert.equal(typeof handlers.createCliCommandContext, 'function');
+  assert.equal(typeof handlers.handleCliCommand, 'function');
+  assert.equal(typeof handlers.handleInitialArgs, 'function');
+
+  // handleCliCommand routes to the injected handleCliCommandRuntimeServiceWithContext dep
+  handlers.handleCliCommand({ command: 'start' } as unknown as CliArgs);
+  assert.deepEqual(calls, ['handleCommand:start']);
+});
--- a/src/main/runtime/composers/cli-startup-composer.ts
+++ b/src/main/runtime/composers/cli-startup-composer.ts
@@ -0,0 +1,50 @@
+import type { CliArgs, CliCommandSource } from '../../../cli/args';
+import { createCliCommandContextFactory } from '../cli-command-context-factory';
+import { createCliCommandRuntimeHandler } from '../cli-command-runtime-handler';
+import { createInitialArgsRuntimeHandler } from '../initial-args-runtime-handler';
+import type { ComposerInputs, ComposerOutputs } from './contracts';
+
+type CliCommandContextMainDeps = Parameters<typeof createCliCommandContextFactory>[0];
+type CliCommandContext = ReturnType<ReturnType<typeof createCliCommandContextFactory>>;
+type CliCommandRuntimeHandlerMainDeps = Omit<
+  Parameters<typeof createCliCommandRuntimeHandler<CliCommandContext>>[0],
+  'createCliCommandContext'
+>;
+type InitialArgsRuntimeHandlerMainDeps = Omit<
+  Parameters<typeof createInitialArgsRuntimeHandler>[0],
+  'handleCliCommand'
+>;
+
+export type CliStartupComposerOptions = ComposerInputs<{
+  cliCommandContextMainDeps: CliCommandContextMainDeps;
+  cliCommandRuntimeHandlerMainDeps: CliCommandRuntimeHandlerMainDeps;
+  initialArgsRuntimeHandlerMainDeps: InitialArgsRuntimeHandlerMainDeps;
+}>;
+
+export type CliStartupComposerResult = ComposerOutputs<{
+  createCliCommandContext: () => CliCommandContext;
+  handleCliCommand: (args: CliArgs, source?: CliCommandSource) => void;
+  handleInitialArgs: () => void;
+}>;
+
+export function composeCliStartupHandlers(
+  options: CliStartupComposerOptions,
+): CliStartupComposerResult {
+  const createCliCommandContext = createCliCommandContextFactory(
+    options.cliCommandContextMainDeps,
+  );
+  const handleCliCommand = createCliCommandRuntimeHandler({
+    ...options.cliCommandRuntimeHandlerMainDeps,
+    createCliCommandContext: () => createCliCommandContext(),
+  });
+  const handleInitialArgs = createInitialArgsRuntimeHandler({
+    ...options.initialArgsRuntimeHandlerMainDeps,
+    handleCliCommand: (args, source) => handleCliCommand(args, source),
+  });
+
+  return {
+    createCliCommandContext,
+    handleCliCommand,
+    handleInitialArgs,
+  };
+}
--- a/src/main/runtime/composers/headless-startup-composer.test.ts
+++ b/src/main/runtime/composers/headless-startup-composer.test.ts
@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { CliArgs } from '../../../cli/args';
+import { composeHeadlessStartupHandlers } from './headless-startup-composer';
+
+test('composeHeadlessStartupHandlers returns startup bootstrap handlers', () => {
+  const calls: string[] = [];
+
+  const handlers = composeHeadlessStartupHandlers<
+    CliArgs,
+    { mode: string },
+    { startAppLifecycle: (args: CliArgs) => void }
+  >({
+    startupRuntimeHandlersDeps: {
+      appLifecycleRuntimeRunnerMainDeps: {
+        app: { on: () => {} } as never,
+        platform: 'darwin',
+        shouldStartApp: () => true,
+        parseArgs: () => ({}) as never,
+        handleCliCommand: () => {},
+        printHelp: () => {},
+        logNoRunningInstance: () => {},
+        onReady: async () => {},
+        onWillQuitCleanup: () => {},
+        shouldRestoreWindowsOnActivate: () => false,
+        restoreWindowsOnActivate: () => {},
+        shouldQuitOnWindowAllClosed: () => false,
+      },
+      createAppLifecycleRuntimeRunner: () => (args) => {
+        calls.push(`lifecycle:${(args as { command?: string }).command ?? 'unknown'}`);
+      },
+      buildStartupBootstrapMainDeps: (startAppLifecycle) => ({
+        argv: ['node', 'main.js'],
+        parseArgs: () => ({ command: 'start' }) as never,
+        setLogLevel: () => {},
+        forceX11Backend: () => {},
+        enforceUnsupportedWaylandMode: () => {},
+        shouldStartApp: () => true,
+        getDefaultSocketPath: () => '/tmp/mpv.sock',
+        defaultTexthookerPort: 5174,
+        configDir: '/tmp/config',
+        defaultConfig: {} as never,
+        generateConfigTemplate: () => 'template',
+        generateDefaultConfigFile: async () => 0,
+        setExitCode: () => {},
+        quitApp: () => {},
+        logGenerateConfigError: () => {},
+        startAppLifecycle: (args) => startAppLifecycle(args as never),
+      }),
+      createStartupBootstrapRuntimeDeps: (deps) => ({
+        startAppLifecycle: deps.startAppLifecycle,
+      }),
+      runStartupBootstrapRuntime: (deps) => {
+        deps.startAppLifecycle({ command: 'start' } as unknown as CliArgs);
+        return { mode: 'started' };
+      },
+      applyStartupState: (state) => {
+        calls.push(`apply:${state.mode}`);
+      },
+    },
+  });
+
+  assert.equal(typeof handlers.runAndApplyStartupState, 'function');
+  assert.deepEqual(handlers.runAndApplyStartupState(), { mode: 'started' });
+  assert.deepEqual(calls, ['lifecycle:start', 'apply:started']);
+});
--- a/src/main/runtime/composers/headless-startup-composer.ts
+++ b/src/main/runtime/composers/headless-startup-composer.ts
@@ -0,0 +1,49 @@
+import { createStartupRuntimeHandlers } from '../startup-runtime-handlers';
+import type { ComposerInputs, ComposerOutputs } from './contracts';
+
+type StartupRuntimeHandlersDeps<TCliArgs, TStartupState, TStartupBootstrapRuntimeDeps> = Parameters<
+  typeof createStartupRuntimeHandlers<TCliArgs, TStartupState, TStartupBootstrapRuntimeDeps>
+>[0];
+type StartupRuntimeHandlers<TCliArgs, TStartupState, TStartupBootstrapRuntimeDeps> = ReturnType<
+  typeof createStartupRuntimeHandlers<TCliArgs, TStartupState, TStartupBootstrapRuntimeDeps>
+>;
+
+export type HeadlessStartupComposerOptions<
+  TCliArgs,
+  TStartupState,
+  TStartupBootstrapRuntimeDeps,
+> = ComposerInputs<{
+  startupRuntimeHandlersDeps: StartupRuntimeHandlersDeps<
+    TCliArgs,
+    TStartupState,
+    TStartupBootstrapRuntimeDeps
+  >;
+}>;
+
+export type HeadlessStartupComposerResult<
+  TCliArgs,
+  TStartupState,
+  TStartupBootstrapRuntimeDeps,
+> = ComposerOutputs<
+  Pick<
+    StartupRuntimeHandlers<TCliArgs, TStartupState, TStartupBootstrapRuntimeDeps>,
+    'appLifecycleRuntimeRunner' | 'runAndApplyStartupState'
+  >
+>;
+
+export function composeHeadlessStartupHandlers<
+  TCliArgs,
+  TStartupState,
+  TStartupBootstrapRuntimeDeps,
+>(
+  options: HeadlessStartupComposerOptions<TCliArgs, TStartupState, TStartupBootstrapRuntimeDeps>,
+): HeadlessStartupComposerResult<TCliArgs, TStartupState, TStartupBootstrapRuntimeDeps> {
+  const { appLifecycleRuntimeRunner, runAndApplyStartupState } = createStartupRuntimeHandlers(
+    options.startupRuntimeHandlersDeps,
+  );
+
+  return {
+    appLifecycleRuntimeRunner,
+    runAndApplyStartupState,
+  };
+}
--- a/src/main/runtime/composers/index.ts
+++ b/src/main/runtime/composers/index.ts
@@ -1,10 +1,13 @@
 export * from './anilist-setup-composer';
 export * from './anilist-tracking-composer';
 export * from './app-ready-composer';
+export * from './cli-startup-composer';
 export * from './contracts';
+export * from './headless-startup-composer';
 export * from './ipc-runtime-composer';
 export * from './jellyfin-remote-composer';
 export * from './jellyfin-runtime-composer';
 export * from './mpv-runtime-composer';
+export * from './overlay-visibility-runtime-composer';
 export * from './shortcuts-runtime-composer';
 export * from './startup-lifecycle-composer';
--- a/src/main/runtime/composers/jellyfin-remote-composer.test.ts
+++ b/src/main/runtime/composers/jellyfin-remote-composer.test.ts
@@ -2,8 +2,11 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { composeJellyfinRemoteHandlers } from './jellyfin-remote-composer';

-test('composeJellyfinRemoteHandlers returns callable jellyfin remote handlers', () => {
+test('composeJellyfinRemoteHandlers returns callable jellyfin remote handlers', async () => {
  let lastProgressAt = 0;
+  let activePlayback: unknown = { itemId: 'item-1', mediaSourceId: 'src-1', playMethod: 'DirectPlay', audioStreamIndex: null, subtitleStreamIndex: null };
+  const calls: string[] = [];
+
  const composed = composeJellyfinRemoteHandlers({
    getConfiguredSession: () => null,
    getClientInfo: () =>
@@ -14,8 +17,11 @@ test('composeJellyfinRemoteHandlers returns callable jellyfin remote handlers',
    getMpvClient: () => null,
    sendMpvCommand: () => {},
    jellyfinTicksToSeconds: () => 0,
-    getActivePlayback: () => null,
-    clearActivePlayback: () => {},
+    getActivePlayback: () => activePlayback as never,
+    clearActivePlayback: () => {
+      activePlayback = null;
+      calls.push('clearActivePlayback');
+    },
    getSession: () => null,
    getNow: () => 0,
    getLastProgressAtMs: () => lastProgressAt,
@@ -32,4 +38,9 @@ test('composeJellyfinRemoteHandlers returns callable jellyfin remote handlers',
  assert.equal(typeof composed.handleJellyfinRemotePlay, 'function');
  assert.equal(typeof composed.handleJellyfinRemotePlaystate, 'function');
  assert.equal(typeof composed.handleJellyfinRemoteGeneralCommand, 'function');
+
+  // reportJellyfinRemoteStopped clears active playback when there is no connected session
+  await composed.reportJellyfinRemoteStopped();
+  assert.equal(activePlayback, null);
+  assert.deepEqual(calls, ['clearActivePlayback']);
 });
--- a/src/main/runtime/composers/jellyfin-runtime-composer.test.ts
+++ b/src/main/runtime/composers/jellyfin-runtime-composer.test.ts
@@ -190,4 +190,9 @@ test('composeJellyfinRuntimeHandlers returns callable jellyfin runtime handlers'
  assert.equal(typeof composed.stopJellyfinRemoteSession, 'function');
  assert.equal(typeof composed.runJellyfinCommand, 'function');
  assert.equal(typeof composed.openJellyfinSetupWindow, 'function');
+
+  // getResolvedJellyfinConfig forwards to the injected getResolvedConfig dep
+  const jellyfinConfig = composed.getResolvedJellyfinConfig();
+  assert.equal(jellyfinConfig.enabled, false);
+  assert.equal(jellyfinConfig.serverUrl, '');
 });
--- a/src/main/runtime/composers/mpv-runtime-composer.test.ts
+++ b/src/main/runtime/composers/mpv-runtime-composer.test.ts
@@ -30,37 +30,13 @@ function createDeferred(): { promise: Promise<void>; resolve: () => void } {
  return { promise, resolve };
 }

-test('composeMpvRuntimeHandlers returns callable handlers and forwards to injected deps', async () => {
-  const calls: string[] = [];
-  let started = false;
-  let metrics = BASE_METRICS;
-  let mecabTokenizer: { id: string } | null = null;
+class DefaultFakeMpvClient {
+  connect(): void {}
+  on(): void {}
+}

-  class FakeMpvClient {
-    connected = false;
-
-    constructor(
-      public socketPath: string,
-      public options: unknown,
-    ) {
-      const autoStartOverlay = (options as { autoStartOverlay: boolean }).autoStartOverlay;
-      calls.push(`create-client:${socketPath}`);
-      calls.push(`auto-start:${String(autoStartOverlay)}`);
-    }
-
-    on(): void {}
-
-    connect(): void {
-      this.connected = true;
-      calls.push('client-connect');
-    }
-  }
-
-  const composed = composeMpvRuntimeHandlers<
-    FakeMpvClient,
-    { isKnownWord: (text: string) => boolean },
-    { text: string }
-  >({
+function createDefaultMpvFixture() {
+  return {
    bindMpvMainEventHandlersMainDeps: {
      appState: {
        initialArgs: null,
@@ -97,15 +73,119 @@ test('composeMpvRuntimeHandlers returns callable handlers and forwards to inject
      updateSubtitleRenderMetrics: () => {},
    },
    mpvClientRuntimeServiceFactoryMainDeps: {
-      createClient: FakeMpvClient,
+      createClient: DefaultFakeMpvClient,
      getSocketPath: () => '/tmp/mpv.sock',
      getResolvedConfig: () => ({ auto_start_overlay: false }),
-      isAutoStartOverlayEnabled: () => true,
+      isAutoStartOverlayEnabled: () => false,
      setOverlayVisible: () => {},
      isVisibleOverlayVisible: () => false,
      getReconnectTimer: () => null,
      setReconnectTimer: () => {},
    },
+    updateMpvSubtitleRenderMetricsMainDeps: {
+      getCurrentMetrics: () => BASE_METRICS,
+      setCurrentMetrics: () => {},
+      applyPatch: (current: MpvSubtitleRenderMetrics, patch: Partial<MpvSubtitleRenderMetrics>) => ({
+        next: { ...current, ...patch },
+        changed: true,
+      }),
+      broadcastMetrics: () => {},
+    },
+    tokenizer: {
+      buildTokenizerDepsMainDeps: {
+        getYomitanExt: () => null,
+        getYomitanParserWindow: () => null,
+        setYomitanParserWindow: () => {},
+        getYomitanParserReadyPromise: () => null,
+        setYomitanParserReadyPromise: () => {},
+        getYomitanParserInitPromise: () => null,
+        setYomitanParserInitPromise: () => {},
+        isKnownWord: () => false,
+        recordLookup: () => {},
+        getKnownWordMatchMode: () => 'headword' as const,
+        getNPlusOneEnabled: () => false,
+        getMinSentenceWordsForNPlusOne: () => 3,
+        getJlptLevel: () => null,
+        getJlptEnabled: () => false,
+        getFrequencyDictionaryEnabled: () => false,
+        getFrequencyDictionaryMatchMode: () => 'headword' as const,
+        getFrequencyRank: () => null,
+        getYomitanGroupDebugEnabled: () => false,
+        getMecabTokenizer: () => null,
+      },
+      createTokenizerRuntimeDeps: () => ({ isKnownWord: () => false }),
+      tokenizeSubtitle: async (text: string) => ({ text }),
+      createMecabTokenizerAndCheckMainDeps: {
+        getMecabTokenizer: () => null,
+        setMecabTokenizer: () => {},
+        createMecabTokenizer: () => ({ id: 'mecab' }),
+        checkAvailability: async () => {},
+      },
+      prewarmSubtitleDictionariesMainDeps: {
+        ensureJlptDictionaryLookup: async () => {},
+        ensureFrequencyDictionaryLookup: async () => {},
+      },
+    },
+    warmups: {
+      launchBackgroundWarmupTaskMainDeps: {
+        now: () => 0,
+        logDebug: () => {},
+        logWarn: () => {},
+      },
+      startBackgroundWarmupsMainDeps: {
+        getStarted: () => false,
+        setStarted: () => {},
+        isTexthookerOnlyMode: () => false,
+        ensureYomitanExtensionLoaded: async () => {},
+        shouldWarmupMecab: () => false,
+        shouldWarmupYomitanExtension: () => false,
+        shouldWarmupSubtitleDictionaries: () => false,
+        shouldWarmupJellyfinRemoteSession: () => false,
+        shouldAutoConnectJellyfinRemote: () => false,
+        startJellyfinRemoteSession: async () => {},
+      },
+    },
+  };
+}
+
+test('composeMpvRuntimeHandlers returns callable handlers and forwards to injected deps', async () => {
+  const calls: string[] = [];
+  let started = false;
+  let metrics = BASE_METRICS;
+  let mecabTokenizer: { id: string } | null = null;
+
+  class FakeMpvClient {
+    connected = false;
+
+    constructor(
+      public socketPath: string,
+      public options: unknown,
+    ) {
+      const autoStartOverlay = (options as { autoStartOverlay: boolean }).autoStartOverlay;
+      calls.push(`create-client:${socketPath}`);
+      calls.push(`auto-start:${String(autoStartOverlay)}`);
+    }
+
+    on(): void {}
+
+    connect(): void {
+      this.connected = true;
+      calls.push('client-connect');
+    }
+  }
+
+  const fixture = createDefaultMpvFixture();
+  const composed = composeMpvRuntimeHandlers<
+    FakeMpvClient,
+    { isKnownWord: (text: string) => boolean },
+    { text: string }
+  >({
+    ...fixture,
+    mpvClientRuntimeServiceFactoryMainDeps: {
+      ...fixture.mpvClientRuntimeServiceFactoryMainDeps,
+      createClient: FakeMpvClient,
+      isAutoStartOverlayEnabled: () => true,
+    },
    updateMpvSubtitleRenderMetricsMainDeps: {
      getCurrentMetrics: () => metrics,
      setCurrentMetrics: (next) => {
@@ -121,25 +201,12 @@ test('composeMpvRuntimeHandlers returns callable handlers and forwards to inject
      },
    },
    tokenizer: {
+      ...fixture.tokenizer,
      buildTokenizerDepsMainDeps: {
-        getYomitanExt: () => null,
-        getYomitanParserWindow: () => null,
-        setYomitanParserWindow: () => {},
-        getYomitanParserReadyPromise: () => null,
-        setYomitanParserReadyPromise: () => {},
-        getYomitanParserInitPromise: () => null,
-        setYomitanParserInitPromise: () => {},
+        ...fixture.tokenizer.buildTokenizerDepsMainDeps,
        isKnownWord: (text) => text === 'known',
-        recordLookup: () => {},
-        getKnownWordMatchMode: () => 'headword',
-        getMinSentenceWordsForNPlusOne: () => 3,
-        getJlptLevel: () => null,
        getJlptEnabled: () => true,
        getFrequencyDictionaryEnabled: () => true,
-        getFrequencyDictionaryMatchMode: () => 'headword',
-        getFrequencyRank: () => null,
-        getYomitanGroupDebugEnabled: () => false,
-        getMecabTokenizer: () => null,
      },
      createTokenizerRuntimeDeps: (deps) => {
        calls.push('create-tokenizer-runtime-deps');
@@ -184,12 +251,12 @@ test('composeMpvRuntimeHandlers returns callable handlers and forwards to inject
        },
      },
      startBackgroundWarmupsMainDeps: {
+        ...fixture.warmups.startBackgroundWarmupsMainDeps,
        getStarted: () => started,
        setStarted: (next) => {
          started = next;
          calls.push(`set-started:${String(next)}`);
        },
-        isTexthookerOnlyMode: () => false,
        ensureYomitanExtensionLoaded: async () => {
          calls.push('warmup-yomitan');
        },
@@ -197,7 +264,6 @@ test('composeMpvRuntimeHandlers returns callable handlers and forwards to inject
        shouldWarmupYomitanExtension: () => true,
        shouldWarmupSubtitleDictionaries: () => true,
        shouldWarmupJellyfinRemoteSession: () => true,
-        shouldAutoConnectJellyfinRemote: () => false,
        startJellyfinRemoteSession: async () => {
          calls.push('warmup-jellyfin');
        },
@@ -264,86 +330,20 @@ test('composeMpvRuntimeHandlers skips MeCab warmup when all POS-dependent annota
    }
  }

+  const fixture = createDefaultMpvFixture();
  const composed = composeMpvRuntimeHandlers<
    FakeMpvClient,
    { isKnownWord: (text: string) => boolean },
    { text: string }
  >({
-    bindMpvMainEventHandlersMainDeps: {
-      appState: {
-        initialArgs: null,
-        overlayRuntimeInitialized: true,
-        mpvClient: null,
-        immersionTracker: null,
-        subtitleTimingTracker: null,
-        currentSubText: '',
-        currentSubAssText: '',
-        playbackPaused: null,
-        previousSecondarySubVisibility: null,
-      },
-      getQuitOnDisconnectArmed: () => false,
-      scheduleQuitCheck: () => {},
-      quitApp: () => {},
-      reportJellyfinRemoteStopped: () => {},
-      syncOverlayMpvSubtitleSuppression: () => {},
-      maybeRunAnilistPostWatchUpdate: async () => {},
-      logSubtitleTimingError: () => {},
-      broadcastToOverlayWindows: () => {},
-      onSubtitleChange: () => {},
-      refreshDiscordPresence: () => {},
-      ensureImmersionTrackerInitialized: () => {},
-      updateCurrentMediaPath: () => {},
-      restoreMpvSubVisibility: () => {},
-      getCurrentAnilistMediaKey: () => null,
-      resetAnilistMediaTracking: () => {},
-      maybeProbeAnilistDuration: () => {},
-      ensureAnilistMediaGuess: () => {},
-      syncImmersionMediaState: () => {},
-      updateCurrentMediaTitle: () => {},
-      resetAnilistMediaGuessState: () => {},
-      reportJellyfinRemoteProgress: () => {},
-      updateSubtitleRenderMetrics: () => {},
-    },
+    ...fixture,
    mpvClientRuntimeServiceFactoryMainDeps: {
+      ...fixture.mpvClientRuntimeServiceFactoryMainDeps,
      createClient: FakeMpvClient,
-      getSocketPath: () => '/tmp/mpv.sock',
-      getResolvedConfig: () => ({ auto_start_overlay: false }),
      isAutoStartOverlayEnabled: () => true,
-      setOverlayVisible: () => {},
-      isVisibleOverlayVisible: () => false,
-      getReconnectTimer: () => null,
-      setReconnectTimer: () => {},
-    },
-    updateMpvSubtitleRenderMetricsMainDeps: {
-      getCurrentMetrics: () => BASE_METRICS,
-      setCurrentMetrics: () => {},
-      applyPatch: (current, patch) => ({ next: { ...current, ...patch }, changed: true }),
-      broadcastMetrics: () => {},
    },
    tokenizer: {
-      buildTokenizerDepsMainDeps: {
-        getYomitanExt: () => null,
-        getYomitanParserWindow: () => null,
-        setYomitanParserWindow: () => {},
-        getYomitanParserReadyPromise: () => null,
-        setYomitanParserReadyPromise: () => {},
-        getYomitanParserInitPromise: () => null,
-        setYomitanParserInitPromise: () => {},
-        isKnownWord: () => false,
-        recordLookup: () => {},
-        getKnownWordMatchMode: () => 'headword',
-        getNPlusOneEnabled: () => false,
-        getMinSentenceWordsForNPlusOne: () => 3,
-        getJlptLevel: () => null,
-        getJlptEnabled: () => false,
-        getFrequencyDictionaryEnabled: () => false,
-        getFrequencyDictionaryMatchMode: () => 'headword',
-        getFrequencyRank: () => null,
-        getYomitanGroupDebugEnabled: () => false,
-        getMecabTokenizer: () => null,
-      },
-      createTokenizerRuntimeDeps: () => ({ isKnownWord: () => false }),
-      tokenizeSubtitle: async (text) => ({ text }),
+      ...fixture.tokenizer,
      createMecabTokenizerAndCheckMainDeps: {
        getMecabTokenizer: () => mecabTokenizer,
        setMecabTokenizer: (next) => {
@@ -358,29 +358,6 @@ test('composeMpvRuntimeHandlers skips MeCab warmup when all POS-dependent annota
          calls.push('check-mecab');
        },
      },
-      prewarmSubtitleDictionariesMainDeps: {
-        ensureJlptDictionaryLookup: async () => {},
-        ensureFrequencyDictionaryLookup: async () => {},
-      },
-    },
-    warmups: {
-      launchBackgroundWarmupTaskMainDeps: {
-        now: () => 0,
-        logDebug: () => {},
-        logWarn: () => {},
-      },
-      startBackgroundWarmupsMainDeps: {
-        getStarted: () => false,
-        setStarted: () => {},
-        isTexthookerOnlyMode: () => false,
-        ensureYomitanExtensionLoaded: async () => {},
-        shouldWarmupMecab: () => false,
-        shouldWarmupYomitanExtension: () => false,
-        shouldWarmupSubtitleDictionaries: () => false,
-        shouldWarmupJellyfinRemoteSession: () => false,
-        shouldAutoConnectJellyfinRemote: () => false,
-        startJellyfinRemoteSession: async () => {},
-      },
    },
  });

@@ -395,98 +372,19 @@ test('composeMpvRuntimeHandlers runs tokenization warmup once across sequential
  let prewarmFrequencyCalls = 0;
  const tokenizeCalls: string[] = [];

+  const fixture = createDefaultMpvFixture();
  const composed = composeMpvRuntimeHandlers<
    { connect: () => void; on: () => void },
    { isKnownWord: () => boolean },
    { text: string }
  >({
-    bindMpvMainEventHandlersMainDeps: {
-      appState: {
-        initialArgs: null,
-        overlayRuntimeInitialized: true,
-        mpvClient: null,
-        immersionTracker: null,
-        subtitleTimingTracker: null,
-        currentSubText: '',
-        currentSubAssText: '',
-        playbackPaused: null,
-        previousSecondarySubVisibility: null,
-      },
-      getQuitOnDisconnectArmed: () => false,
-      scheduleQuitCheck: () => {},
-      quitApp: () => {},
-      reportJellyfinRemoteStopped: () => {},
-      syncOverlayMpvSubtitleSuppression: () => {},
-      maybeRunAnilistPostWatchUpdate: async () => {},
-      logSubtitleTimingError: () => {},
-      broadcastToOverlayWindows: () => {},
-      onSubtitleChange: () => {},
-      refreshDiscordPresence: () => {},
-      ensureImmersionTrackerInitialized: () => {},
-      updateCurrentMediaPath: () => {},
-      restoreMpvSubVisibility: () => {},
-      getCurrentAnilistMediaKey: () => null,
-      resetAnilistMediaTracking: () => {},
-      maybeProbeAnilistDuration: () => {},
-      ensureAnilistMediaGuess: () => {},
-      syncImmersionMediaState: () => {},
-      updateCurrentMediaTitle: () => {},
-      resetAnilistMediaGuessState: () => {},
-      reportJellyfinRemoteProgress: () => {},
-      updateSubtitleRenderMetrics: () => {},
-    },
-    mpvClientRuntimeServiceFactoryMainDeps: {
-      createClient: class {
-        connect(): void {}
-        on(): void {}
-      },
-      getSocketPath: () => '/tmp/mpv.sock',
-      getResolvedConfig: () => ({ auto_start_overlay: false }),
-      isAutoStartOverlayEnabled: () => false,
-      setOverlayVisible: () => {},
-      isVisibleOverlayVisible: () => false,
-      getReconnectTimer: () => null,
-      setReconnectTimer: () => {},
-    },
-    updateMpvSubtitleRenderMetricsMainDeps: {
-      getCurrentMetrics: () => BASE_METRICS,
-      setCurrentMetrics: () => {},
-      applyPatch: (current, patch) => ({ next: { ...current, ...patch }, changed: true }),
-      broadcastMetrics: () => {},
-    },
+    ...fixture,
    tokenizer: {
-      buildTokenizerDepsMainDeps: {
-        getYomitanExt: () => null,
-        getYomitanParserWindow: () => null,
-        setYomitanParserWindow: () => {},
-        getYomitanParserReadyPromise: () => null,
-        setYomitanParserReadyPromise: () => {},
-        getYomitanParserInitPromise: () => null,
-        setYomitanParserInitPromise: () => {},
-        isKnownWord: () => false,
-        recordLookup: () => {},
-        getKnownWordMatchMode: () => 'headword',
-        getNPlusOneEnabled: () => false,
-        getMinSentenceWordsForNPlusOne: () => 3,
-        getJlptLevel: () => null,
-        getJlptEnabled: () => false,
-        getFrequencyDictionaryEnabled: () => false,
-        getFrequencyDictionaryMatchMode: () => 'headword',
-        getFrequencyRank: () => null,
-        getYomitanGroupDebugEnabled: () => false,
-        getMecabTokenizer: () => null,
-      },
-      createTokenizerRuntimeDeps: () => ({ isKnownWord: () => false }),
+      ...fixture.tokenizer,
      tokenizeSubtitle: async (text) => {
        tokenizeCalls.push(text);
        return { text };
      },
-      createMecabTokenizerAndCheckMainDeps: {
-        getMecabTokenizer: () => null,
-        setMecabTokenizer: () => {},
-        createMecabTokenizer: () => ({ id: 'mecab' }),
-        checkAvailability: async () => {},
-      },
      prewarmSubtitleDictionariesMainDeps: {
        ensureJlptDictionaryLookup: async () => {
          prewarmJlptCalls += 1;
@@ -497,24 +395,12 @@ test('composeMpvRuntimeHandlers runs tokenization warmup once across sequential
      },
    },
    warmups: {
-      launchBackgroundWarmupTaskMainDeps: {
-        now: () => 0,
-        logDebug: () => {},
-        logWarn: () => {},
-      },
+      ...fixture.warmups,
      startBackgroundWarmupsMainDeps: {
-        getStarted: () => false,
-        setStarted: () => {},
-        isTexthookerOnlyMode: () => false,
+        ...fixture.warmups.startBackgroundWarmupsMainDeps,
        ensureYomitanExtensionLoaded: async () => {
          yomitanWarmupCalls += 1;
        },
-        shouldWarmupMecab: () => false,
-        shouldWarmupYomitanExtension: () => false,
-        shouldWarmupSubtitleDictionaries: () => false,
-        shouldWarmupJellyfinRemoteSession: () => false,
-        shouldAutoConnectJellyfinRemote: () => false,
-        startJellyfinRemoteSession: async () => {},
      },
    },
  });
@@ -534,93 +420,23 @@ test('composeMpvRuntimeHandlers does not block first tokenization on dictionary
  const mecabDeferred = createDeferred();
  let tokenizeResolved = false;

+  const fixture = createDefaultMpvFixture();
  const composed = composeMpvRuntimeHandlers<
    { connect: () => void; on: () => void },
    { isKnownWord: () => boolean },
    { text: string }
  >({
-    bindMpvMainEventHandlersMainDeps: {
-      appState: {
-        initialArgs: null,
-        overlayRuntimeInitialized: true,
-        mpvClient: null,
-        immersionTracker: null,
-        subtitleTimingTracker: null,
-        currentSubText: '',
-        currentSubAssText: '',
-        playbackPaused: null,
-        previousSecondarySubVisibility: null,
-      },
-      getQuitOnDisconnectArmed: () => false,
-      scheduleQuitCheck: () => {},
-      quitApp: () => {},
-      reportJellyfinRemoteStopped: () => {},
-      syncOverlayMpvSubtitleSuppression: () => {},
-      maybeRunAnilistPostWatchUpdate: async () => {},
-      logSubtitleTimingError: () => {},
-      broadcastToOverlayWindows: () => {},
-      onSubtitleChange: () => {},
-      refreshDiscordPresence: () => {},
-      ensureImmersionTrackerInitialized: () => {},
-      updateCurrentMediaPath: () => {},
-      restoreMpvSubVisibility: () => {},
-      getCurrentAnilistMediaKey: () => null,
-      resetAnilistMediaTracking: () => {},
-      maybeProbeAnilistDuration: () => {},
-      ensureAnilistMediaGuess: () => {},
-      syncImmersionMediaState: () => {},
-      updateCurrentMediaTitle: () => {},
-      resetAnilistMediaGuessState: () => {},
-      reportJellyfinRemoteProgress: () => {},
-      updateSubtitleRenderMetrics: () => {},
-    },
-    mpvClientRuntimeServiceFactoryMainDeps: {
-      createClient: class {
-        connect(): void {}
-        on(): void {}
-      },
-      getSocketPath: () => '/tmp/mpv.sock',
-      getResolvedConfig: () => ({ auto_start_overlay: false }),
-      isAutoStartOverlayEnabled: () => false,
-      setOverlayVisible: () => {},
-      isVisibleOverlayVisible: () => false,
-      getReconnectTimer: () => null,
-      setReconnectTimer: () => {},
-    },
-    updateMpvSubtitleRenderMetricsMainDeps: {
-      getCurrentMetrics: () => BASE_METRICS,
-      setCurrentMetrics: () => {},
-      applyPatch: (current, patch) => ({ next: { ...current, ...patch }, changed: true }),
-      broadcastMetrics: () => {},
-    },
+    ...fixture,
    tokenizer: {
+      ...fixture.tokenizer,
      buildTokenizerDepsMainDeps: {
-        getYomitanExt: () => null,
-        getYomitanParserWindow: () => null,
-        setYomitanParserWindow: () => {},
-        getYomitanParserReadyPromise: () => null,
-        setYomitanParserReadyPromise: () => {},
-        getYomitanParserInitPromise: () => null,
-        setYomitanParserInitPromise: () => {},
-        isKnownWord: () => false,
-        recordLookup: () => {},
-        getKnownWordMatchMode: () => 'headword',
+        ...fixture.tokenizer.buildTokenizerDepsMainDeps,
        getNPlusOneEnabled: () => true,
-        getMinSentenceWordsForNPlusOne: () => 3,
-        getJlptLevel: () => null,
        getJlptEnabled: () => true,
        getFrequencyDictionaryEnabled: () => true,
-        getFrequencyDictionaryMatchMode: () => 'headword',
-        getFrequencyRank: () => null,
-        getYomitanGroupDebugEnabled: () => false,
-        getMecabTokenizer: () => null,
      },
-      createTokenizerRuntimeDeps: () => ({ isKnownWord: () => false }),
-      tokenizeSubtitle: async (text) => ({ text }),
      createMecabTokenizerAndCheckMainDeps: {
-        getMecabTokenizer: () => null,
-        setMecabTokenizer: () => {},
-        createMecabTokenizer: () => ({ id: 'mecab' }),
+        ...fixture.tokenizer.createMecabTokenizerAndCheckMainDeps,
        checkAvailability: async () => mecabDeferred.promise,
      },
      prewarmSubtitleDictionariesMainDeps: {
@@ -628,25 +444,6 @@ test('composeMpvRuntimeHandlers does not block first tokenization on dictionary
        ensureFrequencyDictionaryLookup: async () => frequencyDeferred.promise,
      },
    },
-    warmups: {
-      launchBackgroundWarmupTaskMainDeps: {
-        now: () => 0,
-        logDebug: () => {},
-        logWarn: () => {},
-      },
-      startBackgroundWarmupsMainDeps: {
-        getStarted: () => false,
-        setStarted: () => {},
-        isTexthookerOnlyMode: () => false,
-        ensureYomitanExtensionLoaded: async () => undefined,
-        shouldWarmupMecab: () => false,
-        shouldWarmupYomitanExtension: () => false,
-        shouldWarmupSubtitleDictionaries: () => false,
-        shouldWarmupJellyfinRemoteSession: () => false,
-        shouldAutoConnectJellyfinRemote: () => false,
-        startJellyfinRemoteSession: async () => {},
-      },
-    },
  });

  const tokenizePromise = composed.tokenizeSubtitle('first line').then(() => {
@@ -667,86 +464,19 @@ test('composeMpvRuntimeHandlers shows annotation loading OSD after tokenization-
  const frequencyDeferred = createDeferred();
  const osdMessages: string[] = [];

+  const fixture = createDefaultMpvFixture();
  const composed = composeMpvRuntimeHandlers<
    { connect: () => void; on: () => void },
    { onTokenizationReady?: (text: string) => void },
    { text: string }
  >({
-    bindMpvMainEventHandlersMainDeps: {
-      appState: {
-        initialArgs: null,
-        overlayRuntimeInitialized: true,
-        mpvClient: null,
-        immersionTracker: null,
-        subtitleTimingTracker: null,
-        currentSubText: '',
-        currentSubAssText: '',
-        playbackPaused: null,
-        previousSecondarySubVisibility: null,
-      },
-      getQuitOnDisconnectArmed: () => false,
-      scheduleQuitCheck: () => {},
-      quitApp: () => {},
-      reportJellyfinRemoteStopped: () => {},
-      syncOverlayMpvSubtitleSuppression: () => {},
-      maybeRunAnilistPostWatchUpdate: async () => {},
-      logSubtitleTimingError: () => {},
-      broadcastToOverlayWindows: () => {},
-      onSubtitleChange: () => {},
-      refreshDiscordPresence: () => {},
-      ensureImmersionTrackerInitialized: () => {},
-      updateCurrentMediaPath: () => {},
-      restoreMpvSubVisibility: () => {},
-      getCurrentAnilistMediaKey: () => null,
-      resetAnilistMediaTracking: () => {},
-      maybeProbeAnilistDuration: () => {},
-      ensureAnilistMediaGuess: () => {},
-      syncImmersionMediaState: () => {},
-      updateCurrentMediaTitle: () => {},
-      resetAnilistMediaGuessState: () => {},
-      reportJellyfinRemoteProgress: () => {},
-      updateSubtitleRenderMetrics: () => {},
-    },
-    mpvClientRuntimeServiceFactoryMainDeps: {
-      createClient: class {
-        connect(): void {}
-        on(): void {}
-      },
-      getSocketPath: () => '/tmp/mpv.sock',
-      getResolvedConfig: () => ({ auto_start_overlay: false }),
-      isAutoStartOverlayEnabled: () => false,
-      setOverlayVisible: () => {},
-      isVisibleOverlayVisible: () => false,
-      getReconnectTimer: () => null,
-      setReconnectTimer: () => {},
-    },
-    updateMpvSubtitleRenderMetricsMainDeps: {
-      getCurrentMetrics: () => BASE_METRICS,
-      setCurrentMetrics: () => {},
-      applyPatch: (current, patch) => ({ next: { ...current, ...patch }, changed: true }),
-      broadcastMetrics: () => {},
-    },
+    ...fixture,
    tokenizer: {
+      ...fixture.tokenizer,
      buildTokenizerDepsMainDeps: {
-        getYomitanExt: () => null,
-        getYomitanParserWindow: () => null,
-        setYomitanParserWindow: () => {},
-        getYomitanParserReadyPromise: () => null,
-        setYomitanParserReadyPromise: () => {},
-        getYomitanParserInitPromise: () => null,
-        setYomitanParserInitPromise: () => {},
-        isKnownWord: () => false,
-        recordLookup: () => {},
-        getKnownWordMatchMode: () => 'headword',
-        getNPlusOneEnabled: () => false,
-        getMinSentenceWordsForNPlusOne: () => 3,
-        getJlptLevel: () => null,
+        ...fixture.tokenizer.buildTokenizerDepsMainDeps,
        getJlptEnabled: () => true,
        getFrequencyDictionaryEnabled: () => true,
-        getFrequencyDictionaryMatchMode: () => 'headword',
-        getFrequencyRank: () => null,
-        getYomitanGroupDebugEnabled: () => false,
-        getMecabTokenizer: () => null,
      },
      createTokenizerRuntimeDeps: (deps) =>
        deps as unknown as { onTokenizationReady?: (text: string) => void },
@@ -754,12 +484,6 @@ test('composeMpvRuntimeHandlers shows annotation loading OSD after tokenization-
        deps.onTokenizationReady?.(text);
        return { text };
      },
-      createMecabTokenizerAndCheckMainDeps: {
-        getMecabTokenizer: () => null,
-        setMecabTokenizer: () => {},
-        createMecabTokenizer: () => ({ id: 'mecab' }),
-        checkAvailability: async () => {},
-      },
      prewarmSubtitleDictionariesMainDeps: {
        ensureJlptDictionaryLookup: async () => jlptDeferred.promise,
        ensureFrequencyDictionaryLookup: async () => frequencyDeferred.promise,
@@ -768,25 +492,6 @@ test('composeMpvRuntimeHandlers shows annotation loading OSD after tokenization-
        },
      },
    },
-    warmups: {
-      launchBackgroundWarmupTaskMainDeps: {
-        now: () => 0,
-        logDebug: () => {},
-        logWarn: () => {},
-      },
-      startBackgroundWarmupsMainDeps: {
-        getStarted: () => false,
-        setStarted: () => {},
-        isTexthookerOnlyMode: () => false,
-        ensureYomitanExtensionLoaded: async () => undefined,
-        shouldWarmupMecab: () => false,
-        shouldWarmupYomitanExtension: () => false,
-        shouldWarmupSubtitleDictionaries: () => false,
-        shouldWarmupJellyfinRemoteSession: () => false,
-        shouldAutoConnectJellyfinRemote: () => false,
-        startJellyfinRemoteSession: async () => {},
-      },
-    },
  });

  const warmupPromise = composed.startTokenizationWarmups();
@@ -814,89 +519,22 @@ test('composeMpvRuntimeHandlers reuses completed background tokenization warmups
  let frequencyWarmupCalls = 0;
  let mecabTokenizer: { tokenize: () => Promise<never[]> } | null = null;

+  const fixture = createDefaultMpvFixture();
  const composed = composeMpvRuntimeHandlers<
    { connect: () => void; on: () => void },
    { isKnownWord: () => boolean },
    { text: string }
  >({
-    bindMpvMainEventHandlersMainDeps: {
-      appState: {
-        initialArgs: null,
-        overlayRuntimeInitialized: true,
-        mpvClient: null,
-        immersionTracker: null,
-        subtitleTimingTracker: null,
-        currentSubText: '',
-        currentSubAssText: '',
-        playbackPaused: null,
-        previousSecondarySubVisibility: null,
-      },
-      getQuitOnDisconnectArmed: () => false,
-      scheduleQuitCheck: () => {},
-      quitApp: () => {},
-      reportJellyfinRemoteStopped: () => {},
-      syncOverlayMpvSubtitleSuppression: () => {},
-      maybeRunAnilistPostWatchUpdate: async () => {},
-      logSubtitleTimingError: () => {},
-      broadcastToOverlayWindows: () => {},
-      onSubtitleChange: () => {},
-      refreshDiscordPresence: () => {},
-      ensureImmersionTrackerInitialized: () => {},
-      updateCurrentMediaPath: () => {},
-      restoreMpvSubVisibility: () => {},
-      getCurrentAnilistMediaKey: () => null,
-      resetAnilistMediaTracking: () => {},
-      maybeProbeAnilistDuration: () => {},
-      ensureAnilistMediaGuess: () => {},
-      syncImmersionMediaState: () => {},
-      updateCurrentMediaTitle: () => {},
-      resetAnilistMediaGuessState: () => {},
-      reportJellyfinRemoteProgress: () => {},
-      updateSubtitleRenderMetrics: () => {},
-    },
-    mpvClientRuntimeServiceFactoryMainDeps: {
-      createClient: class {
-        connect(): void {}
-        on(): void {}
-      },
-      getSocketPath: () => '/tmp/mpv.sock',
-      getResolvedConfig: () => ({ auto_start_overlay: false }),
-      isAutoStartOverlayEnabled: () => false,
-      setOverlayVisible: () => {},
-      isVisibleOverlayVisible: () => false,
-      getReconnectTimer: () => null,
-      setReconnectTimer: () => {},
-    },
-    updateMpvSubtitleRenderMetricsMainDeps: {
-      getCurrentMetrics: () => BASE_METRICS,
-      setCurrentMetrics: () => {},
-      applyPatch: (current, patch) => ({ next: { ...current, ...patch }, changed: true }),
-      broadcastMetrics: () => {},
-    },
+    ...fixture,
    tokenizer: {
+      ...fixture.tokenizer,
      buildTokenizerDepsMainDeps: {
-        getYomitanExt: () => null,
-        getYomitanParserWindow: () => null,
-        setYomitanParserWindow: () => {},
-        getYomitanParserReadyPromise: () => null,
-        setYomitanParserReadyPromise: () => {},
-        getYomitanParserInitPromise: () => null,
-        setYomitanParserInitPromise: () => {},
-        isKnownWord: () => false,
-        recordLookup: () => {},
-        getKnownWordMatchMode: () => 'headword',
+        ...fixture.tokenizer.buildTokenizerDepsMainDeps,
        getNPlusOneEnabled: () => true,
-        getMinSentenceWordsForNPlusOne: () => 3,
-        getJlptLevel: () => null,
        getJlptEnabled: () => true,
        getFrequencyDictionaryEnabled: () => true,
-        getFrequencyDictionaryMatchMode: () => 'headword',
-        getFrequencyRank: () => null,
-        getYomitanGroupDebugEnabled: () => false,
        getMecabTokenizer: () => mecabTokenizer,
      },
-      createTokenizerRuntimeDeps: () => ({ isKnownWord: () => false }),
-      tokenizeSubtitle: async (text) => ({ text }),
      createMecabTokenizerAndCheckMainDeps: {
        getMecabTokenizer: () => mecabTokenizer,
        setMecabTokenizer: (next) => {
@@ -917,26 +555,19 @@ test('composeMpvRuntimeHandlers reuses completed background tokenization warmups
      },
    },
    warmups: {
-      launchBackgroundWarmupTaskMainDeps: {
-        now: () => 0,
-        logDebug: () => {},
-        logWarn: () => {},
-      },
+      ...fixture.warmups,
      startBackgroundWarmupsMainDeps: {
+        ...fixture.warmups.startBackgroundWarmupsMainDeps,
        getStarted: () => started,
        setStarted: (next) => {
          started = next;
        },
-        isTexthookerOnlyMode: () => false,
        ensureYomitanExtensionLoaded: async () => {
          yomitanWarmupCalls += 1;
        },
        shouldWarmupMecab: () => true,
        shouldWarmupYomitanExtension: () => true,
        shouldWarmupSubtitleDictionaries: () => true,
-        shouldWarmupJellyfinRemoteSession: () => false,
-        shouldAutoConnectJellyfinRemote: () => false,
-        startJellyfinRemoteSession: async () => {},
      },
    },
  });
--- a/src/main/runtime/composers/overlay-visibility-runtime-composer.test.ts
+++ b/src/main/runtime/composers/overlay-visibility-runtime-composer.test.ts
@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { composeOverlayVisibilityRuntime } from './overlay-visibility-runtime-composer';
+
+test('composeOverlayVisibilityRuntime returns overlay visibility handlers', () => {
+  const calls: string[] = [];
+  const composed = composeOverlayVisibilityRuntime({
+    overlayVisibilityRuntime: {
+      updateVisibleOverlayVisibility: () => {
+        calls.push('updateVisibleOverlayVisibility');
+      },
+    },
+    restorePreviousSecondarySubVisibilityMainDeps: {
+      getMpvClient: () => null,
+    },
+    broadcastRuntimeOptionsChangedMainDeps: {
+      broadcastRuntimeOptionsChangedRuntime: () => {
+        calls.push('broadcastRuntimeOptionsChangedRuntime');
+      },
+      getRuntimeOptionsState: () => [],
+      broadcastToOverlayWindows: () => {},
+    },
+    sendToActiveOverlayWindowMainDeps: {
+      sendToActiveOverlayWindowRuntime: () => true,
+    },
+    setOverlayDebugVisualizationEnabledMainDeps: {
+      setOverlayDebugVisualizationEnabledRuntime: () => {},
+      getCurrentEnabled: () => false,
+      setCurrentEnabled: () => {},
+    },
+    openRuntimeOptionsPaletteMainDeps: {
+      openRuntimeOptionsPaletteRuntime: () => {
+        calls.push('openRuntimeOptionsPaletteRuntime');
+      },
+    },
+  });
+
+  assert.equal(typeof composed.updateVisibleOverlayVisibility, 'function');
+  assert.equal(typeof composed.restorePreviousSecondarySubVisibility, 'function');
+  assert.equal(typeof composed.broadcastRuntimeOptionsChanged, 'function');
+  assert.equal(typeof composed.sendToActiveOverlayWindow, 'function');
+  assert.equal(typeof composed.setOverlayDebugVisualizationEnabled, 'function');
+  assert.equal(typeof composed.openRuntimeOptionsPalette, 'function');
+
+  // updateVisibleOverlayVisibility passes through to the injected runtime dep
+  composed.updateVisibleOverlayVisibility();
+  assert.deepEqual(calls, ['updateVisibleOverlayVisibility']);
+
+  // openRuntimeOptionsPalette forwards to the injected runtime dep
+  composed.openRuntimeOptionsPalette();
+  assert.deepEqual(calls, ['updateVisibleOverlayVisibility', 'openRuntimeOptionsPaletteRuntime']);
+
+  // broadcastRuntimeOptionsChanged forwards to the injected runtime dep
+  composed.broadcastRuntimeOptionsChanged();
+  assert.ok(calls.includes('broadcastRuntimeOptionsChangedRuntime'));
+});
--- a/src/main/runtime/composers/overlay-visibility-runtime-composer.ts
+++ b/src/main/runtime/composers/overlay-visibility-runtime-composer.ts
@@ -0,0 +1,88 @@
+import {
+  createBroadcastRuntimeOptionsChangedHandler,
+  createOpenRuntimeOptionsPaletteHandler,
+  createRestorePreviousSecondarySubVisibilityHandler,
+  createSendToActiveOverlayWindowHandler,
+  createSetOverlayDebugVisualizationEnabledHandler,
+} from '../overlay-runtime-main-actions';
+import {
+  createBuildBroadcastRuntimeOptionsChangedMainDepsHandler,
+  createBuildOpenRuntimeOptionsPaletteMainDepsHandler,
+  createBuildRestorePreviousSecondarySubVisibilityMainDepsHandler,
+  createBuildSendToActiveOverlayWindowMainDepsHandler,
+  createBuildSetOverlayDebugVisualizationEnabledMainDepsHandler,
+} from '../overlay-runtime-main-actions-main-deps';
+import type { ComposerInputs, ComposerOutputs } from './contracts';
+
+type RestorePreviousSecondarySubVisibilityMainDeps = Parameters<
+  typeof createBuildRestorePreviousSecondarySubVisibilityMainDepsHandler
+>[0];
+type BroadcastRuntimeOptionsChangedMainDeps = Parameters<
+  typeof createBuildBroadcastRuntimeOptionsChangedMainDepsHandler
+>[0];
+type SendToActiveOverlayWindowMainDeps = Parameters<
+  typeof createBuildSendToActiveOverlayWindowMainDepsHandler
+>[0];
+type SetOverlayDebugVisualizationEnabledMainDeps = Parameters<
+  typeof createBuildSetOverlayDebugVisualizationEnabledMainDepsHandler
+>[0];
+type OpenRuntimeOptionsPaletteMainDeps = Parameters<
+  typeof createBuildOpenRuntimeOptionsPaletteMainDepsHandler
+>[0];
+
+export type OverlayVisibilityRuntimeComposerOptions = ComposerInputs<{
+  overlayVisibilityRuntime: {
+    updateVisibleOverlayVisibility: () => void;
+  };
+  restorePreviousSecondarySubVisibilityMainDeps: RestorePreviousSecondarySubVisibilityMainDeps;
+  broadcastRuntimeOptionsChangedMainDeps: BroadcastRuntimeOptionsChangedMainDeps;
+  sendToActiveOverlayWindowMainDeps: SendToActiveOverlayWindowMainDeps;
+  setOverlayDebugVisualizationEnabledMainDeps: SetOverlayDebugVisualizationEnabledMainDeps;
+  openRuntimeOptionsPaletteMainDeps: OpenRuntimeOptionsPaletteMainDeps;
+}>;
+
+export type OverlayVisibilityRuntimeComposerResult = ComposerOutputs<{
+  updateVisibleOverlayVisibility: () => void;
+  restorePreviousSecondarySubVisibility: ReturnType<
+    typeof createRestorePreviousSecondarySubVisibilityHandler
+  >;
+  broadcastRuntimeOptionsChanged: ReturnType<typeof createBroadcastRuntimeOptionsChangedHandler>;
+  sendToActiveOverlayWindow: ReturnType<typeof createSendToActiveOverlayWindowHandler>;
+  setOverlayDebugVisualizationEnabled: ReturnType<
+    typeof createSetOverlayDebugVisualizationEnabledHandler
+  >;
+  openRuntimeOptionsPalette: ReturnType<typeof createOpenRuntimeOptionsPaletteHandler>;
+}>;
+
+export function composeOverlayVisibilityRuntime(
+  options: OverlayVisibilityRuntimeComposerOptions,
+): OverlayVisibilityRuntimeComposerResult {
+  return {
+    updateVisibleOverlayVisibility: () => options.overlayVisibilityRuntime.updateVisibleOverlayVisibility(),
+    restorePreviousSecondarySubVisibility: createRestorePreviousSecondarySubVisibilityHandler(
+      createBuildRestorePreviousSecondarySubVisibilityMainDepsHandler(
+        options.restorePreviousSecondarySubVisibilityMainDeps,
+      )(),
+    ),
+    broadcastRuntimeOptionsChanged: createBroadcastRuntimeOptionsChangedHandler(
+      createBuildBroadcastRuntimeOptionsChangedMainDepsHandler(
+        options.broadcastRuntimeOptionsChangedMainDeps,
+      )(),
+    ),
+    sendToActiveOverlayWindow: createSendToActiveOverlayWindowHandler(
+      createBuildSendToActiveOverlayWindowMainDepsHandler(
+        options.sendToActiveOverlayWindowMainDeps,
+      )(),
+    ),
+    setOverlayDebugVisualizationEnabled: createSetOverlayDebugVisualizationEnabledHandler(
+      createBuildSetOverlayDebugVisualizationEnabledMainDepsHandler(
+        options.setOverlayDebugVisualizationEnabledMainDeps,
+      )(),
+    ),
+    openRuntimeOptionsPalette: createOpenRuntimeOptionsPaletteHandler(
+      createBuildOpenRuntimeOptionsPaletteMainDepsHandler(
+        options.openRuntimeOptionsPaletteMainDeps,
+      )(),
+    ),
+  };
+}
--- a/src/main/runtime/composers/shortcuts-runtime-composer.test.ts
+++ b/src/main/runtime/composers/shortcuts-runtime-composer.test.ts
@@ -3,6 +3,7 @@ import test from 'node:test';
 import { composeShortcutRuntimes } from './shortcuts-runtime-composer';

 test('composeShortcutRuntimes returns callable shortcut runtime handlers', () => {
+  const calls: string[] = [];
  const composed = composeShortcutRuntimes({
    globalShortcuts: {
      getConfiguredShortcutsMainDeps: {
@@ -39,9 +40,13 @@ test('composeShortcutRuntimes returns callable shortcut runtime handlers', () =>
    },
    overlayShortcutsRuntimeMainDeps: {
      overlayShortcutsRuntime: {
-        registerOverlayShortcuts: () => {},
+        registerOverlayShortcuts: () => {
+          calls.push('registerOverlayShortcuts');
+        },
        unregisterOverlayShortcuts: () => {},
-        syncOverlayShortcuts: () => {},
+        syncOverlayShortcuts: () => {
+          calls.push('syncOverlayShortcuts');
+        },
        refreshOverlayShortcuts: () => {},
      },
    },
@@ -58,4 +63,12 @@ test('composeShortcutRuntimes returns callable shortcut runtime handlers', () =>
  assert.equal(typeof composed.unregisterOverlayShortcuts, 'function');
  assert.equal(typeof composed.syncOverlayShortcuts, 'function');
  assert.equal(typeof composed.refreshOverlayShortcuts, 'function');
+
+  // registerOverlayShortcuts forwards to the injected overlayShortcutsRuntime dep
+  composed.registerOverlayShortcuts();
+  assert.deepEqual(calls, ['registerOverlayShortcuts']);
+
+  // syncOverlayShortcuts forwards to the injected overlayShortcutsRuntime dep
+  composed.syncOverlayShortcuts();
+  assert.deepEqual(calls, ['registerOverlayShortcuts', 'syncOverlayShortcuts']);
 });
--- a/src/main/runtime/composers/startup-lifecycle-composer.test.ts
+++ b/src/main/runtime/composers/startup-lifecycle-composer.test.ts
@@ -3,6 +3,7 @@ import test from 'node:test';
 import { composeStartupLifecycleHandlers } from './startup-lifecycle-composer';

 test('composeStartupLifecycleHandlers returns callable startup lifecycle handlers', () => {
+  const calls: string[] = [];
  const composed = composeStartupLifecycleHandlers({
    registerProtocolUrlHandlersMainDeps: {
      registerOpenUrl: () => {},
@@ -51,7 +52,9 @@ test('composeStartupLifecycleHandlers returns callable startup lifecycle handler
      getAllWindowCount: () => 0,
    },
    restoreWindowsOnActivateMainDeps: {
-      createMainWindow: () => {},
+      createMainWindow: () => {
+        calls.push('createMainWindow');
+      },
      updateVisibleOverlayVisibility: () => {},
      syncOverlayMpvSubtitleSuppression: () => {},
    },
@@ -61,4 +64,11 @@ test('composeStartupLifecycleHandlers returns callable startup lifecycle handler
  assert.equal(typeof composed.onWillQuitCleanup, 'function');
  assert.equal(typeof composed.shouldRestoreWindowsOnActivate, 'function');
  assert.equal(typeof composed.restoreWindowsOnActivate, 'function');
+
+  // shouldRestoreWindowsOnActivate returns false when overlay runtime is not initialized
+  assert.equal(composed.shouldRestoreWindowsOnActivate(), false);
+
+  // restoreWindowsOnActivate invokes the injected createMainWindow dep
+  composed.restoreWindowsOnActivate();
+  assert.deepEqual(calls, ['createMainWindow']);
 });
--- a/src/main/runtime/discord-presence-runtime.test.ts
+++ b/src/main/runtime/discord-presence-runtime.test.ts
@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createDiscordPresenceRuntime } from './discord-presence-runtime';
+
+test('discord presence runtime refreshes duration and publishes the current snapshot', async () => {
+  const snapshots: Array<Record<string, unknown>> = [];
+  let mediaDurationSec: number | null = null;
+
+  const runtime = createDiscordPresenceRuntime({
+    getDiscordPresenceService: () => ({
+      publish: (snapshot: Record<string, unknown>) => {
+        snapshots.push(snapshot);
+      },
+    }),
+    isDiscordPresenceEnabled: () => true,
+    getMpvClient: () =>
+      ({
+        connected: true,
+        currentTimePos: 12,
+        requestProperty: async (name: string) => {
+          assert.equal(name, 'duration');
+          return 42;
+        },
+      }) as never,
+    getCurrentMediaTitle: () => 'Episode 1',
+    getCurrentMediaPath: () => '/media/episode-1.mkv',
+    getCurrentSubtitleText: () => '字幕',
+    getPlaybackPaused: () => false,
+    getFallbackMediaDurationSec: () => 90,
+    getSessionStartedAtMs: () => 1_000,
+    getMediaDurationSec: () => mediaDurationSec,
+    setMediaDurationSec: (next) => {
+      mediaDurationSec = next;
+    },
+  });
+
+  await runtime.refreshDiscordPresenceMediaDuration();
+  runtime.publishDiscordPresence();
+
+  assert.equal(mediaDurationSec, 42);
+  assert.deepEqual(snapshots, [
+    {
+      mediaTitle: 'Episode 1',
+      mediaPath: '/media/episode-1.mkv',
+      subtitleText: '字幕',
+      currentTimeSec: 12,
+      mediaDurationSec: 42,
+      paused: false,
+      connected: true,
+      sessionStartedAtMs: 1_000,
+    },
+  ]);
+});
+
+test('discord presence runtime skips publish when disabled or service missing', () => {
+  let published = false;
+  const runtime = createDiscordPresenceRuntime({
+    getDiscordPresenceService: () => null,
+    isDiscordPresenceEnabled: () => false,
+    getMpvClient: () => null,
+    getCurrentMediaTitle: () => null,
+    getCurrentMediaPath: () => null,
+    getCurrentSubtitleText: () => '',
+    getPlaybackPaused: () => null,
+    getFallbackMediaDurationSec: () => null,
+    getSessionStartedAtMs: () => 0,
+    getMediaDurationSec: () => null,
+    setMediaDurationSec: () => {
+      published = true;
+    },
+  });
+
+  runtime.publishDiscordPresence();
+
+  assert.equal(published, false);
+});
--- a/src/main/runtime/discord-presence-runtime.ts
+++ b/src/main/runtime/discord-presence-runtime.ts
@@ -0,0 +1,74 @@
+type DiscordPresenceServiceLike = {
+  publish: (snapshot: {
+    mediaTitle: string | null;
+    mediaPath: string | null;
+    subtitleText: string;
+    currentTimeSec: number | null;
+    mediaDurationSec: number | null;
+    paused: boolean | null;
+    connected: boolean;
+    sessionStartedAtMs: number;
+  }) => void;
+};
+
+type MpvClientLike = {
+  connected?: boolean;
+  currentTimePos?: number | null;
+  requestProperty: (name: string) => Promise<unknown>;
+};
+
+export type DiscordPresenceRuntimeDeps = {
+  getDiscordPresenceService: () => DiscordPresenceServiceLike | null;
+  isDiscordPresenceEnabled: () => boolean;
+  getMpvClient: () => MpvClientLike | null;
+  getCurrentMediaTitle: () => string | null;
+  getCurrentMediaPath: () => string | null;
+  getCurrentSubtitleText: () => string;
+  getPlaybackPaused: () => boolean | null;
+  getFallbackMediaDurationSec: () => number | null;
+  getSessionStartedAtMs: () => number;
+  getMediaDurationSec: () => number | null;
+  setMediaDurationSec: (durationSec: number | null) => void;
+};
+
+export function createDiscordPresenceRuntime(deps: DiscordPresenceRuntimeDeps) {
+  const refreshDiscordPresenceMediaDuration = async (): Promise<void> => {
+    const client = deps.getMpvClient();
+    if (!client?.connected) {
+      return;
+    }
+
+    try {
+      const value = await client.requestProperty('duration');
+      const numeric = Number(value);
+      deps.setMediaDurationSec(Number.isFinite(numeric) && numeric > 0 ? numeric : null);
+    } catch {
+      deps.setMediaDurationSec(null);
+    }
+  };
+
+  const publishDiscordPresence = (): void => {
+    const discordPresenceService = deps.getDiscordPresenceService();
+    if (!discordPresenceService || deps.isDiscordPresenceEnabled() !== true) {
+      return;
+    }
+
+    void refreshDiscordPresenceMediaDuration();
+    const client = deps.getMpvClient();
+    discordPresenceService.publish({
+      mediaTitle: deps.getCurrentMediaTitle(),
+      mediaPath: deps.getCurrentMediaPath(),
+      subtitleText: deps.getCurrentSubtitleText(),
+      currentTimeSec: client?.currentTimePos ?? null,
+      mediaDurationSec: deps.getMediaDurationSec() ?? deps.getFallbackMediaDurationSec(),
+      paused: deps.getPlaybackPaused(),
+      connected: Boolean(client?.connected),
+      sessionStartedAtMs: deps.getSessionStartedAtMs(),
+    });
+  };
+
+  return {
+    refreshDiscordPresenceMediaDuration,
+    publishDiscordPresence,
+  };
+}
--- a/src/main/runtime/discord-rpc-client.test.ts
+++ b/src/main/runtime/discord-rpc-client.test.ts
@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createDiscordRpcClient } from './discord-rpc-client';
+
+test('createDiscordRpcClient forwards rich presence calls through client.user', async () => {
+  const calls: Array<string> = [];
+  const rpcClient = createDiscordRpcClient('123456789012345678', {
+    createClient: () =>
+      ({
+        login: async () => {
+          calls.push('login');
+        },
+        user: {
+          setActivity: async () => {
+            calls.push('setActivity');
+          },
+          clearActivity: async () => {
+            calls.push('clearActivity');
+          },
+        },
+        destroy: async () => {
+          calls.push('destroy');
+        },
+      }) as never,
+  });
+
+  await rpcClient.login();
+  await rpcClient.setActivity({
+    details: 'Title',
+    state: 'Playing 00:01 / 00:02',
+    startTimestamp: 1_700_000_000,
+  });
+  await rpcClient.clearActivity();
+  await rpcClient.destroy();
+
+  assert.deepEqual(calls, ['login', 'setActivity', 'clearActivity', 'destroy']);
+});
--- a/src/main/runtime/discord-rpc-client.ts
+++ b/src/main/runtime/discord-rpc-client.ts
@@ -0,0 +1,49 @@
+import { Client } from '@xhayper/discord-rpc';
+
+import type { DiscordActivityPayload } from '../../core/services/discord-presence';
+
+type DiscordRpcClientUserLike = {
+  setActivity: (activity: DiscordActivityPayload) => Promise<unknown>;
+  clearActivity: () => Promise<void>;
+};
+
+type DiscordRpcRawClient = {
+  login: () => Promise<void>;
+  destroy: () => Promise<void>;
+  user?: DiscordRpcClientUserLike;
+};
+
+export type DiscordRpcClient = {
+  login: () => Promise<void>;
+  setActivity: (activity: DiscordActivityPayload) => Promise<void>;
+  clearActivity: () => Promise<void>;
+  destroy: () => Promise<void>;
+};
+
+function requireUser(client: DiscordRpcRawClient): DiscordRpcClientUserLike {
+  if (!client.user) {
+    throw new Error('Discord RPC client user is unavailable');
+  }
+
+  return client.user;
+}
+
+export function wrapDiscordRpcClient(client: DiscordRpcRawClient): DiscordRpcClient {
+  return {
+    login: () => client.login(),
+    setActivity: (activity) => requireUser(client).setActivity(activity).then(() => undefined),
+    clearActivity: () => requireUser(client).clearActivity(),
+    destroy: () => client.destroy(),
+  };
+}
+
+export function createDiscordRpcClient(
+  clientId: string,
+  deps?: { createClient?: (options: { clientId: string; transport: { type: 'ipc' } }) => DiscordRpcRawClient },
+): DiscordRpcClient {
+  const client =
+    deps?.createClient?.({ clientId, transport: { type: 'ipc' } }) ??
+    new Client({ clientId, transport: { type: 'ipc' } });
+
+  return wrapDiscordRpcClient(client);
+}
--- a/src/main/runtime/first-run-setup-plugin.test.ts
+++ b/src/main/runtime/first-run-setup-plugin.test.ts
@@ -7,6 +7,7 @@ import {
  detectInstalledFirstRunPlugin,
  installFirstRunPluginToDefaultLocation,
  resolvePackagedFirstRunPluginAssets,
+  syncInstalledFirstRunPluginBinaryPath,
 } from './first-run-setup-plugin';
 import { resolveDefaultMpvInstallPaths } from '../../shared/setup-state';

@@ -68,13 +69,17 @@ test('installFirstRunPluginToDefaultLocation installs plugin and backs up existi
      dirname: path.join(root, 'dist', 'main', 'runtime'),
      appPath: path.join(root, 'app'),
      resourcesPath,
+      binaryPath: '/Applications/SubMiner.app/Contents/MacOS/SubMiner',
    });

    assert.equal(result.ok, true);
    assert.equal(result.pluginInstallStatus, 'installed');
    assert.equal(detectInstalledFirstRunPlugin(installPaths), true);
    assert.equal(fs.readFileSync(installPaths.pluginEntrypointPath, 'utf8'), '-- packaged plugin');
-    assert.equal(fs.readFileSync(installPaths.pluginConfigPath, 'utf8'), 'configured=true\n');
+    assert.equal(
+      fs.readFileSync(installPaths.pluginConfigPath, 'utf8'),
+      'configured=true\nbinary_path=/Applications/SubMiner.app/Contents/MacOS/SubMiner\n',
+    );

    const scriptsDirEntries = fs.readdirSync(installPaths.scriptsDir);
    const scriptOptsEntries = fs.readdirSync(installPaths.scriptOptsDir);
@@ -113,13 +118,17 @@ test('installFirstRunPluginToDefaultLocation installs plugin to Windows mpv defa
      dirname: path.join(root, 'dist', 'main', 'runtime'),
      appPath: path.join(root, 'app'),
      resourcesPath,
+      binaryPath: 'C:\\Program Files\\SubMiner\\SubMiner.exe',
    });

    assert.equal(result.ok, true);
    assert.equal(result.pluginInstallStatus, 'installed');
    assert.equal(detectInstalledFirstRunPlugin(installPaths), true);
    assert.equal(fs.readFileSync(installPaths.pluginEntrypointPath, 'utf8'), '-- packaged plugin');
-    assert.equal(fs.readFileSync(installPaths.pluginConfigPath, 'utf8'), 'configured=true\n');
+    assert.equal(
+      fs.readFileSync(installPaths.pluginConfigPath, 'utf8'),
+      'configured=true\nbinary_path=C:\\Program Files\\SubMiner\\SubMiner.exe\n',
+    );
  });
 });

@@ -146,12 +155,70 @@ test('installFirstRunPluginToDefaultLocation rewrites Windows plugin socket_path
      dirname: path.join(root, 'dist', 'main', 'runtime'),
      appPath: path.join(root, 'app'),
      resourcesPath,
+      binaryPath: 'C:\\Program Files\\SubMiner\\SubMiner.exe',
    });

    assert.equal(result.ok, true);
    assert.equal(
      fs.readFileSync(installPaths.pluginConfigPath, 'utf8'),
-      'binary_path=\nsocket_path=\\\\.\\pipe\\subminer-socket\n',
+      'binary_path=C:\\Program Files\\SubMiner\\SubMiner.exe\nsocket_path=\\\\.\\pipe\\subminer-socket\n',
+    );
+  });
+});
+
+test('syncInstalledFirstRunPluginBinaryPath fills blank binary_path for existing installs', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const installPaths = resolveDefaultMpvInstallPaths('linux', homeDir, xdgConfigHome);
+
+    fs.mkdirSync(path.dirname(installPaths.pluginConfigPath), { recursive: true });
+    fs.writeFileSync(installPaths.pluginConfigPath, 'binary_path=\nsocket_path=/tmp/subminer-socket\n');
+
+    const result = syncInstalledFirstRunPluginBinaryPath({
+      platform: 'linux',
+      homeDir,
+      xdgConfigHome,
+      binaryPath: '/Applications/SubMiner.app/Contents/MacOS/SubMiner',
+    });
+
+    assert.deepEqual(result, {
+      updated: true,
+      configPath: installPaths.pluginConfigPath,
+    });
+    assert.equal(
+      fs.readFileSync(installPaths.pluginConfigPath, 'utf8'),
+      'binary_path=/Applications/SubMiner.app/Contents/MacOS/SubMiner\nsocket_path=/tmp/subminer-socket\n',
+    );
+  });
+});
+
+test('syncInstalledFirstRunPluginBinaryPath preserves explicit binary_path overrides', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const installPaths = resolveDefaultMpvInstallPaths('linux', homeDir, xdgConfigHome);
+
+    fs.mkdirSync(path.dirname(installPaths.pluginConfigPath), { recursive: true });
+    fs.writeFileSync(
+      installPaths.pluginConfigPath,
+      'binary_path=/tmp/SubMiner/scripts/subminer-dev.sh\nsocket_path=/tmp/subminer-socket\n',
+    );
+
+    const result = syncInstalledFirstRunPluginBinaryPath({
+      platform: 'linux',
+      homeDir,
+      xdgConfigHome,
+      binaryPath: '/Applications/SubMiner.app/Contents/MacOS/SubMiner',
+    });
+
+    assert.deepEqual(result, {
+      updated: false,
+      configPath: installPaths.pluginConfigPath,
+    });
+    assert.equal(
+      fs.readFileSync(installPaths.pluginConfigPath, 'utf8'),
+      'binary_path=/tmp/SubMiner/scripts/subminer-dev.sh\nsocket_path=/tmp/subminer-socket\n',
    );
  });
 });
--- a/src/main/runtime/first-run-setup-plugin.ts
+++ b/src/main/runtime/first-run-setup-plugin.ts
@@ -28,6 +28,43 @@ function rewriteInstalledWindowsPluginConfig(configPath: string): void {
  }
 }

+function sanitizePluginConfigValue(value: string): string {
+  return value.replace(/[\r\n]/g, '').trim();
+}
+
+function upsertPluginConfigLine(content: string, key: string, value: string): string {
+  const normalizedValue = sanitizePluginConfigValue(value);
+  const line = `${key}=${normalizedValue}`;
+  const pattern = new RegExp(`^${key}=.*$`, 'm');
+  if (pattern.test(content)) {
+    return content.replace(pattern, line);
+  }
+
+  const suffix = content.endsWith('\n') || content.length === 0 ? '' : '\n';
+  return `${content}${suffix}${line}\n`;
+}
+
+function rewriteInstalledPluginBinaryPath(configPath: string, binaryPath: string): boolean {
+  const content = fs.readFileSync(configPath, 'utf8');
+  const updated = upsertPluginConfigLine(content, 'binary_path', binaryPath);
+  if (updated === content) {
+    return false;
+  }
+  fs.writeFileSync(configPath, updated, 'utf8');
+  return true;
+}
+
+function readInstalledPluginBinaryPath(configPath: string): string | null {
+  const content = fs.readFileSync(configPath, 'utf8');
+  const match = content.match(/^binary_path=(.*)$/m);
+  if (!match) {
+    return null;
+  }
+  const rawValue = match[1] ?? '';
+  const value = sanitizePluginConfigValue(rawValue);
+  return value.length > 0 ? value : null;
+}
+
 export function resolvePackagedFirstRunPluginAssets(deps: {
  dirname: string;
  appPath: string;
@@ -79,6 +116,7 @@ export function installFirstRunPluginToDefaultLocation(options: {
  dirname: string;
  appPath: string;
  resourcesPath: string;
+  binaryPath: string;
 }): PluginInstallResult {
  const installPaths = resolveDefaultMpvInstallPaths(
    options.platform,
@@ -116,6 +154,7 @@ export function installFirstRunPluginToDefaultLocation(options: {
  backupExistingPath(installPaths.pluginConfigPath);
  fs.cpSync(assets.pluginDirSource, installPaths.pluginDir, { recursive: true });
  fs.copyFileSync(assets.pluginConfigSource, installPaths.pluginConfigPath);
+  rewriteInstalledPluginBinaryPath(installPaths.pluginConfigPath, options.binaryPath);
  if (options.platform === 'win32') {
    rewriteInstalledWindowsPluginConfig(installPaths.pluginConfigPath);
  }
@@ -127,3 +166,33 @@ export function installFirstRunPluginToDefaultLocation(options: {
    message: `Installed mpv plugin to ${installPaths.mpvConfigDir}.`,
  };
 }
+
+export function syncInstalledFirstRunPluginBinaryPath(options: {
+  platform: NodeJS.Platform;
+  homeDir: string;
+  xdgConfigHome?: string;
+  binaryPath: string;
+}): { updated: boolean; configPath: string | null } {
+  const installPaths = resolveDefaultMpvInstallPaths(
+    options.platform,
+    options.homeDir,
+    options.xdgConfigHome,
+  );
+  if (!installPaths.supported || !fs.existsSync(installPaths.pluginConfigPath)) {
+    return { updated: false, configPath: null };
+  }
+
+  const configuredBinaryPath = readInstalledPluginBinaryPath(installPaths.pluginConfigPath);
+  if (configuredBinaryPath) {
+    return { updated: false, configPath: installPaths.pluginConfigPath };
+  }
+
+  const updated = rewriteInstalledPluginBinaryPath(installPaths.pluginConfigPath, options.binaryPath);
+  if (options.platform === 'win32') {
+    rewriteInstalledWindowsPluginConfig(installPaths.pluginConfigPath);
+  }
+  return {
+    updated,
+    configPath: installPaths.pluginConfigPath,
+  };
+}
--- a/src/main/runtime/mpv-main-event-bindings.ts
+++ b/src/main/runtime/mpv-main-event-bindings.ts
@@ -78,8 +78,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
      reportJellyfinRemoteStopped: () => deps.reportJellyfinRemoteStopped(),
      refreshDiscordPresence: () => deps.refreshDiscordPresence(),
      syncOverlayMpvSubtitleSuppression: () => deps.syncOverlayMpvSubtitleSuppression(),
-      hasInitialPlaybackQuitOnDisconnectArg: () =>
-        deps.hasInitialPlaybackQuitOnDisconnectArg(),
+      hasInitialPlaybackQuitOnDisconnectArg: () => deps.hasInitialPlaybackQuitOnDisconnectArg(),
      isOverlayRuntimeInitialized: () => deps.isOverlayRuntimeInitialized(),
      shouldQuitOnDisconnectWhenOverlayRuntimeInitialized: () =>
        deps.shouldQuitOnDisconnectWhenOverlayRuntimeInitialized(),
@@ -88,7 +87,11 @@ export function createBindMpvMainEventHandlersHandler(deps: {
      isMpvConnected: () => deps.isMpvConnected(),
      quitApp: () => deps.quitApp(),
    });
-    const handleMpvConnectionChangeWithSidebarReset = ({ connected }: { connected: boolean }): void => {
+    const handleMpvConnectionChangeWithSidebarReset = ({
+      connected,
+    }: {
+      connected: boolean;
+    }): void => {
      if (connected) {
        deps.resetSubtitleSidebarEmbeddedLayout();
      }
--- a/src/main/runtime/mpv-main-event-main-deps.ts
+++ b/src/main/runtime/mpv-main-event-main-deps.ts
@@ -4,14 +4,12 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
  appState: {
    initialArgs?: { jellyfinPlay?: unknown; youtubePlay?: unknown } | null;
    overlayRuntimeInitialized: boolean;
-    mpvClient:
-      | {
-          connected?: boolean;
-          currentSecondarySubText?: string;
-          currentTimePos?: number;
-          requestProperty?: (name: string) => Promise<unknown>;
-        }
-      | null;
+    mpvClient: {
+      connected?: boolean;
+      currentSecondarySubText?: string;
+      currentTimePos?: number;
+      requestProperty?: (name: string) => Promise<unknown>;
+    } | null;
    immersionTracker: {
      recordSubtitleLine?: (
        text: string,
--- a/src/main/runtime/overlay-modal-input-state.test.ts
+++ b/src/main/runtime/overlay-modal-input-state.test.ts
@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createOverlayModalInputState } from './overlay-modal-input-state';
+
+function createModalWindow() {
+  const calls: string[] = [];
+  let destroyed = false;
+  let focused = false;
+  let webContentsFocused = false;
+
+  return {
+    calls,
+    setDestroyed(next: boolean) {
+      destroyed = next;
+    },
+    setFocused(next: boolean) {
+      focused = next;
+    },
+    setWebContentsFocused(next: boolean) {
+      webContentsFocused = next;
+    },
+    isDestroyed: () => destroyed,
+    setIgnoreMouseEvents: (ignore: boolean) => {
+      calls.push(`ignore:${ignore}`);
+    },
+    setAlwaysOnTop: (flag: boolean, level?: string, relativeLevel?: number) => {
+      calls.push(`top:${flag}:${level ?? ''}:${relativeLevel ?? ''}`);
+    },
+    focus: () => {
+      focused = true;
+      calls.push('focus');
+    },
+    isFocused: () => focused,
+    webContents: {
+      isFocused: () => webContentsFocused,
+      focus: () => {
+        webContentsFocused = true;
+        calls.push('web-focus');
+      },
+    },
+  };
+}
+
+test('overlay modal input state activates modal window interactivity and syncs dependents', () => {
+  const modalWindow = createModalWindow();
+  const calls: string[] = [];
+  const state = createOverlayModalInputState({
+    getModalWindow: () => modalWindow as never,
+    syncOverlayShortcutsForModal: (isActive) => {
+      calls.push(`shortcuts:${isActive}`);
+    },
+    syncOverlayVisibilityForModal: () => {
+      calls.push('visibility');
+    },
+  });
+
+  state.handleModalInputStateChange(true);
+
+  assert.equal(state.getModalInputExclusive(), true);
+  assert.deepEqual(modalWindow.calls, [
+    'ignore:false',
+    'top:true:screen-saver:1',
+    'focus',
+    'web-focus',
+  ]);
+  assert.deepEqual(calls, ['shortcuts:true', 'visibility']);
+});
+
+test('overlay modal input state is idempotent for unchanged state', () => {
+  const calls: string[] = [];
+  const state = createOverlayModalInputState({
+    getModalWindow: () => null,
+    syncOverlayShortcutsForModal: (isActive) => {
+      calls.push(`shortcuts:${isActive}`);
+    },
+    syncOverlayVisibilityForModal: () => {
+      calls.push('visibility');
+    },
+  });
+
+  state.handleModalInputStateChange(false);
+  state.handleModalInputStateChange(true);
+  state.handleModalInputStateChange(true);
+
+  assert.equal(state.getModalInputExclusive(), true);
+  assert.deepEqual(calls, ['shortcuts:true', 'visibility']);
+});
--- a/src/main/runtime/overlay-modal-input-state.ts
+++ b/src/main/runtime/overlay-modal-input-state.ts
@@ -0,0 +1,38 @@
+import type { BrowserWindow } from 'electron';
+
+export type OverlayModalInputStateDeps = {
+  getModalWindow: () => BrowserWindow | null;
+  syncOverlayShortcutsForModal: (isActive: boolean) => void;
+  syncOverlayVisibilityForModal: () => void;
+};
+
+export function createOverlayModalInputState(deps: OverlayModalInputStateDeps) {
+  let modalInputExclusive = false;
+
+  const handleModalInputStateChange = (isActive: boolean): void => {
+    if (modalInputExclusive === isActive) {
+      return;
+    }
+
+    modalInputExclusive = isActive;
+    if (isActive) {
+      const modalWindow = deps.getModalWindow();
+      if (modalWindow && !modalWindow.isDestroyed()) {
+        modalWindow.setIgnoreMouseEvents(false);
+        modalWindow.setAlwaysOnTop(true, 'screen-saver', 1);
+        modalWindow.focus();
+        if (!modalWindow.webContents.isFocused()) {
+          modalWindow.webContents.focus();
+        }
+      }
+    }
+
+    deps.syncOverlayShortcutsForModal(isActive);
+    deps.syncOverlayVisibilityForModal();
+  };
+
+  return {
+    getModalInputExclusive: (): boolean => modalInputExclusive,
+    handleModalInputStateChange,
+  };
+}
--- a/src/main/runtime/overlay-runtime-options.ts
+++ b/src/main/runtime/overlay-runtime-options.ts
@@ -2,9 +2,9 @@ import type {
  AnkiConnectConfig,
  KikuFieldGroupingChoice,
  KikuFieldGroupingRequestData,
-  WindowGeometry,
-} from '../../types';
+} from '../../types/anki';
 import type { BrowserWindow } from 'electron';
+import type { WindowGeometry } from '../../types/runtime';
 import type { BaseWindowTracker } from '../../window-trackers';

 type OverlayRuntimeOptions = {
--- a/src/main/runtime/setup-window-factory.test.ts
+++ b/src/main/runtime/setup-window-factory.test.ts
@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  createCreateAnilistSetupWindowHandler,
+  createCreateFirstRunSetupWindowHandler,
+  createCreateJellyfinSetupWindowHandler,
+} from './setup-window-factory';
+
+test('createCreateFirstRunSetupWindowHandler builds first-run setup window', () => {
+  let options: Electron.BrowserWindowConstructorOptions | null = null;
+  const createSetupWindow = createCreateFirstRunSetupWindowHandler({
+    createBrowserWindow: (nextOptions) => {
+      options = nextOptions;
+      return { id: 'first-run' } as never;
+    },
+  });
+
+  assert.deepEqual(createSetupWindow(), { id: 'first-run' });
+  assert.deepEqual(options, {
+    width: 480,
+    height: 460,
+    title: 'SubMiner Setup',
+    show: true,
+    autoHideMenuBar: true,
+    resizable: false,
+    minimizable: false,
+    maximizable: false,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+});
+
+test('createCreateJellyfinSetupWindowHandler builds jellyfin setup window', () => {
+  let options: Electron.BrowserWindowConstructorOptions | null = null;
+  const createSetupWindow = createCreateJellyfinSetupWindowHandler({
+    createBrowserWindow: (nextOptions) => {
+      options = nextOptions;
+      return { id: 'jellyfin' } as never;
+    },
+  });
+
+  assert.deepEqual(createSetupWindow(), { id: 'jellyfin' });
+  assert.deepEqual(options, {
+    width: 520,
+    height: 560,
+    title: 'Jellyfin Setup',
+    show: true,
+    autoHideMenuBar: true,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+});
+
+test('createCreateAnilistSetupWindowHandler builds anilist setup window', () => {
+  let options: Electron.BrowserWindowConstructorOptions | null = null;
+  const createSetupWindow = createCreateAnilistSetupWindowHandler({
+    createBrowserWindow: (nextOptions) => {
+      options = nextOptions;
+      return { id: 'anilist' } as never;
+    },
+  });
+
+  assert.deepEqual(createSetupWindow(), { id: 'anilist' });
+  assert.deepEqual(options, {
+    width: 1000,
+    height: 760,
+    title: 'Anilist Setup',
+    show: true,
+    autoHideMenuBar: true,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+});
--- a/src/main/runtime/setup-window-factory.ts
+++ b/src/main/runtime/setup-window-factory.ts
@@ -0,0 +1,62 @@
+interface SetupWindowConfig {
+  width: number;
+  height: number;
+  title: string;
+  resizable?: boolean;
+  minimizable?: boolean;
+  maximizable?: boolean;
+}
+
+function createSetupWindowHandler<TWindow>(
+  deps: { createBrowserWindow: (options: Electron.BrowserWindowConstructorOptions) => TWindow },
+  config: SetupWindowConfig,
+) {
+  return (): TWindow =>
+    deps.createBrowserWindow({
+      width: config.width,
+      height: config.height,
+      title: config.title,
+      show: true,
+      autoHideMenuBar: true,
+      ...(config.resizable === undefined ? {} : { resizable: config.resizable }),
+      ...(config.minimizable === undefined ? {} : { minimizable: config.minimizable }),
+      ...(config.maximizable === undefined ? {} : { maximizable: config.maximizable }),
+      webPreferences: {
+        nodeIntegration: false,
+        contextIsolation: true,
+      },
+    });
+}
+
+export function createCreateFirstRunSetupWindowHandler<TWindow>(deps: {
+  createBrowserWindow: (options: Electron.BrowserWindowConstructorOptions) => TWindow;
+}) {
+  return createSetupWindowHandler(deps, {
+    width: 480,
+    height: 460,
+    title: 'SubMiner Setup',
+    resizable: false,
+    minimizable: false,
+    maximizable: false,
+  });
+}
+
+export function createCreateJellyfinSetupWindowHandler<TWindow>(deps: {
+  createBrowserWindow: (options: Electron.BrowserWindowConstructorOptions) => TWindow;
+}) {
+  return createSetupWindowHandler(deps, {
+    width: 520,
+    height: 560,
+    title: 'Jellyfin Setup',
+  });
+}
+
+export function createCreateAnilistSetupWindowHandler<TWindow>(deps: {
+  createBrowserWindow: (options: Electron.BrowserWindowConstructorOptions) => TWindow;
+}) {
+  return createSetupWindowHandler(deps, {
+    width: 1000,
+    height: 760,
+    title: 'Anilist Setup',
+  });
+}
--- a/src/main/runtime/startup-autoplay-release-policy.test.ts
+++ b/src/main/runtime/startup-autoplay-release-policy.test.ts
@@ -14,9 +14,7 @@ test('autoplay release keeps the short retry budget for normal playback signals'
 test('autoplay release uses the full startup timeout window while paused', () => {
  assert.equal(
    resolveAutoplayReadyMaxReleaseAttempts({ forceWhilePaused: true }),
-    Math.ceil(
-      STARTUP_AUTOPLAY_RELEASE_TIMEOUT_MS / DEFAULT_AUTOPLAY_RELEASE_RETRY_DELAY_MS,
-    ),
+    Math.ceil(STARTUP_AUTOPLAY_RELEASE_TIMEOUT_MS / DEFAULT_AUTOPLAY_RELEASE_RETRY_DELAY_MS),
  );
 });

--- a/src/main/runtime/startup-autoplay-release-policy.ts
+++ b/src/main/runtime/startup-autoplay-release-policy.ts
@@ -22,7 +22,4 @@ export function resolveAutoplayReadyMaxReleaseAttempts(options?: {
  return Math.max(3, Math.ceil(startupTimeoutMs / retryDelayMs));
 }

-export {
-  DEFAULT_AUTOPLAY_RELEASE_RETRY_DELAY_MS,
-  STARTUP_AUTOPLAY_RELEASE_TIMEOUT_MS,
-};
+export { DEFAULT_AUTOPLAY_RELEASE_RETRY_DELAY_MS, STARTUP_AUTOPLAY_RELEASE_TIMEOUT_MS };
--- a/src/main/runtime/subtitle-prefetch-runtime.test.ts
+++ b/src/main/runtime/subtitle-prefetch-runtime.test.ts
@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createResolveActiveSubtitleSidebarSourceHandler } from './subtitle-prefetch-runtime';
+
+test('subtitle prefetch runtime resolves direct external subtitle sources first', async () => {
+  const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
+    getFfmpegPath: () => 'ffmpeg',
+    extractInternalSubtitleTrack: async () => {
+      throw new Error('should not extract external tracks');
+    },
+  });
+
+  const resolved = await resolveSource({
+    currentExternalFilenameRaw: ' /tmp/current.ass ',
+    currentTrackRaw: null,
+    trackListRaw: null,
+    sidRaw: null,
+    videoPath: '/media/video.mkv',
+  });
+
+  assert.deepEqual(resolved, {
+    path: '/tmp/current.ass',
+    sourceKey: '/tmp/current.ass',
+  });
+});
+
+test('subtitle prefetch runtime extracts internal subtitle tracks into a stable source key', async () => {
+  const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
+    getFfmpegPath: () => 'ffmpeg-custom',
+    extractInternalSubtitleTrack: async (ffmpegPath, videoPath, track) => {
+      assert.equal(ffmpegPath, 'ffmpeg-custom');
+      assert.equal(videoPath, '/media/video.mkv');
+      assert.equal((track as Record<string, unknown>)['ff-index'], 7);
+      return {
+        path: '/tmp/subminer-sidebar-123/track_7.ass',
+        cleanup: async () => {},
+      };
+    },
+  });
+
+  const resolved = await resolveSource({
+    currentExternalFilenameRaw: null,
+    currentTrackRaw: {
+      type: 'sub',
+      id: 3,
+      'ff-index': 7,
+      codec: 'ass',
+    },
+    trackListRaw: [],
+    sidRaw: 3,
+    videoPath: '/media/video.mkv',
+  });
+
+  assert.deepEqual(resolved, {
+    path: '/tmp/subminer-sidebar-123/track_7.ass',
+    sourceKey: 'internal:/media/video.mkv:track:3:ff:7',
+    cleanup: resolved?.cleanup,
+  });
+});
--- a/src/main/runtime/subtitle-prefetch-runtime.ts
+++ b/src/main/runtime/subtitle-prefetch-runtime.ts
@@ -0,0 +1,180 @@
+import type { SubtitlePrefetchInitController } from './subtitle-prefetch-init';
+import { buildSubtitleSidebarSourceKey } from './subtitle-prefetch-source';
+
+type MpvSubtitleTrackLike = {
+  type?: unknown;
+  id?: unknown;
+  selected?: unknown;
+  external?: unknown;
+  codec?: unknown;
+  'ff-index'?: unknown;
+  'external-filename'?: unknown;
+};
+
+type ActiveSubtitleSidebarSource = {
+  path: string;
+  sourceKey: string;
+  cleanup?: () => Promise<void>;
+};
+
+function parseTrackId(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isInteger(value)) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    const parsed = Number(value.trim());
+    return Number.isInteger(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+function getActiveSubtitleTrack(
+  currentTrackRaw: unknown,
+  trackListRaw: unknown,
+  sidRaw: unknown,
+): MpvSubtitleTrackLike | null {
+  if (currentTrackRaw && typeof currentTrackRaw === 'object') {
+    const track = currentTrackRaw as MpvSubtitleTrackLike;
+    if (track.type === undefined || track.type === 'sub') {
+      return track;
+    }
+  }
+
+  const sid = parseTrackId(sidRaw);
+  if (!Array.isArray(trackListRaw)) {
+    return null;
+  }
+
+  const bySid =
+    sid === null
+      ? null
+      : ((trackListRaw.find((entry: unknown) => {
+          if (!entry || typeof entry !== 'object') {
+            return false;
+          }
+          const track = entry as MpvSubtitleTrackLike;
+          return track.type === 'sub' && parseTrackId(track.id) === sid;
+        }) as MpvSubtitleTrackLike | undefined) ?? null);
+  if (bySid) {
+    return bySid;
+  }
+
+  return (
+    (trackListRaw.find((entry: unknown) => {
+      if (!entry || typeof entry !== 'object') {
+        return false;
+      }
+      const track = entry as MpvSubtitleTrackLike;
+      return track.type === 'sub' && track.selected === true;
+    }) as MpvSubtitleTrackLike | undefined) ?? null
+  );
+}
+
+export function createResolveActiveSubtitleSidebarSourceHandler(deps: {
+  getFfmpegPath: () => string;
+  extractInternalSubtitleTrack: (
+    ffmpegPath: string,
+    videoPath: string,
+    track: MpvSubtitleTrackLike,
+  ) => Promise<{ path: string; cleanup: () => Promise<void> } | null>;
+}) {
+  return async (input: {
+    currentExternalFilenameRaw: unknown;
+    currentTrackRaw: unknown;
+    trackListRaw: unknown;
+    sidRaw: unknown;
+    videoPath: string;
+  }): Promise<ActiveSubtitleSidebarSource | null> => {
+    const currentExternalFilename =
+      typeof input.currentExternalFilenameRaw === 'string'
+        ? input.currentExternalFilenameRaw.trim()
+        : '';
+    if (currentExternalFilename) {
+      return { path: currentExternalFilename, sourceKey: currentExternalFilename };
+    }
+
+    const track = getActiveSubtitleTrack(input.currentTrackRaw, input.trackListRaw, input.sidRaw);
+    if (!track) {
+      return null;
+    }
+
+    const externalFilename =
+      typeof track['external-filename'] === 'string' ? track['external-filename'].trim() : '';
+    if (externalFilename) {
+      return { path: externalFilename, sourceKey: externalFilename };
+    }
+
+    const extracted = await deps.extractInternalSubtitleTrack(
+      deps.getFfmpegPath(),
+      input.videoPath,
+      track,
+    );
+    if (!extracted) {
+      return null;
+    }
+
+    return {
+      ...extracted,
+      sourceKey: buildSubtitleSidebarSourceKey(input.videoPath, track, extracted.path),
+    };
+  };
+}
+
+export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
+  getMpvClient: () => {
+    connected?: boolean;
+    requestProperty: (name: string) => Promise<unknown>;
+  } | null;
+  getLastObservedTimePos: () => number;
+  subtitlePrefetchInitController: SubtitlePrefetchInitController;
+  resolveActiveSubtitleSidebarSource: (
+    input: Parameters<ReturnType<typeof createResolveActiveSubtitleSidebarSourceHandler>>[0],
+  ) => Promise<ActiveSubtitleSidebarSource | null>;
+}) {
+  return async (): Promise<void> => {
+    const client = deps.getMpvClient();
+    if (!client?.connected) {
+      return;
+    }
+
+    try {
+      const [currentExternalFilenameRaw, currentTrackRaw, trackListRaw, sidRaw, videoPathRaw] =
+        await Promise.all([
+          client.requestProperty('current-tracks/sub/external-filename').catch(() => null),
+          client.requestProperty('current-tracks/sub').catch(() => null),
+          client.requestProperty('track-list'),
+          client.requestProperty('sid'),
+          client.requestProperty('path'),
+        ]);
+      const videoPath = typeof videoPathRaw === 'string' ? videoPathRaw : '';
+      if (!videoPath) {
+        deps.subtitlePrefetchInitController.cancelPendingInit();
+        return;
+      }
+
+      const resolvedSource = await deps.resolveActiveSubtitleSidebarSource({
+        currentExternalFilenameRaw,
+        currentTrackRaw,
+        trackListRaw,
+        sidRaw,
+        videoPath,
+      });
+      if (!resolvedSource) {
+        deps.subtitlePrefetchInitController.cancelPendingInit();
+        return;
+      }
+
+      try {
+        await deps.subtitlePrefetchInitController.initSubtitlePrefetch(
+          resolvedSource.path,
+          deps.getLastObservedTimePos(),
+          resolvedSource.sourceKey,
+        );
+      } finally {
+        await resolvedSource.cleanup?.();
+      }
+    } catch {
+      // Skip refresh when the track query fails.
+    }
+  };
+}
--- a/src/main/runtime/windows-mpv-launch.ts
+++ b/src/main/runtime/windows-mpv-launch.ts
@@ -33,10 +33,7 @@ export function resolveWindowsMpvPath(deps: WindowsMpvLaunchDeps): string {
  return '';
 }

-export function buildWindowsMpvLaunchArgs(
-  targets: string[],
-  extraArgs: string[] = [],
-): string[] {
+export function buildWindowsMpvLaunchArgs(targets: string[], extraArgs: string[] = []): string[] {
  return ['--player-operation-mode=pseudo-gui', '--profile=subminer', ...extraArgs, ...targets];
 }

--- a/src/main/runtime/windows-mpv-shortcuts.ts
+++ b/src/main/runtime/windows-mpv-shortcuts.ts
@@ -24,7 +24,7 @@ export interface WindowsMpvShortcutInstallResult {
 }

 export function resolveWindowsStartMenuProgramsDir(appDataDir: string): string {
-  return path.join(appDataDir, 'Microsoft', 'Windows', 'Start Menu', 'Programs');
+  return path.win32.join(appDataDir, 'Microsoft', 'Windows', 'Start Menu', 'Programs');
 }

 export function resolveWindowsMpvShortcutPaths(options: {
@@ -32,11 +32,11 @@ export function resolveWindowsMpvShortcutPaths(options: {
  desktopDir: string;
 }): WindowsMpvShortcutPaths {
  return {
-    startMenuPath: path.join(
+    startMenuPath: path.win32.join(
      resolveWindowsStartMenuProgramsDir(options.appDataDir),
      WINDOWS_MPV_SHORTCUT_NAME,
    ),
-    desktopPath: path.join(options.desktopDir, WINDOWS_MPV_SHORTCUT_NAME),
+    desktopPath: path.win32.join(options.desktopDir, WINDOWS_MPV_SHORTCUT_NAME),
  };
 }

@@ -54,7 +54,7 @@ export function buildWindowsMpvShortcutDetails(exePath: string): WindowsShortcut
  return {
    target: exePath,
    args: '--launch-mpv',
-    cwd: path.dirname(exePath),
+    cwd: path.win32.dirname(exePath),
    description: 'Launch mpv with the SubMiner profile',
    icon: exePath,
    iconIndex: 0,
@@ -79,7 +79,7 @@ export function applyWindowsMpvShortcuts(options: {
  const failures: string[] = [];

  const ensureShortcut = (shortcutPath: string): void => {
-    mkdirSync(path.dirname(shortcutPath), { recursive: true });
+    mkdirSync(path.win32.dirname(shortcutPath), { recursive: true });
    const ok = options.writeShortcutLink(shortcutPath, 'replace', details);
    if (!ok) {
      failures.push(shortcutPath);
--- a/src/main/runtime/youtube-flow.test.ts
+++ b/src/main/runtime/youtube-flow.test.ts
@@ -141,9 +141,7 @@ test('youtube flow can open a manual picker session and load the selected subtit
  assert.ok(
    commands.some(
      (command) =>
-        command[0] === 'set_property' &&
-        command[1] === 'sub-visibility' &&
-        command[2] === 'yes',
+        command[0] === 'set_property' && command[1] === 'sub-visibility' && command[2] === 'yes',
    ),
  );
  assert.ok(
@@ -263,9 +261,7 @@ test('youtube flow retries secondary after partial batch subtitle failure', asyn
  assert.ok(
    commands.some(
      (command) =>
-        command[0] === 'sub-add' &&
-        command[1] === '/tmp/manual:en.vtt' &&
-        command[2] === 'cached',
+        command[0] === 'sub-add' && command[1] === '/tmp/manual:en.vtt' && command[2] === 'cached',
    ),
  );
 });
@@ -708,12 +704,54 @@ test('youtube flow leaves non-authoritative youtube subtitle tracks untouched af
        return selectedSecondarySid;
      }
      return [
-        { type: 'sub', id: 1, lang: 'en', title: 'English', external: true, 'external-filename': null },
-        { type: 'sub', id: 2, lang: 'ja', title: 'Japanese', external: true, 'external-filename': null },
-        { type: 'sub', id: 3, lang: 'ja-en', title: 'Japanese from English', external: true, 'external-filename': null },
-        { type: 'sub', id: 4, lang: 'ja-ja', title: 'Japanese from Japanese', external: true, 'external-filename': null },
-        { type: 'sub', id: 5, lang: 'ja-orig', title: 'auto-ja-orig.vtt', external: true, 'external-filename': '/tmp/auto-ja-orig.vtt' },
-        { type: 'sub', id: 6, lang: 'en', title: 'manual-en.en.srt', external: true, 'external-filename': '/tmp/manual-en.en.srt' },
+        {
+          type: 'sub',
+          id: 1,
+          lang: 'en',
+          title: 'English',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 2,
+          lang: 'ja',
+          title: 'Japanese',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 3,
+          lang: 'ja-en',
+          title: 'Japanese from English',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 4,
+          lang: 'ja-ja',
+          title: 'Japanese from Japanese',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 5,
+          lang: 'ja-orig',
+          title: 'auto-ja-orig.vtt',
+          external: true,
+          'external-filename': '/tmp/auto-ja-orig.vtt',
+        },
+        {
+          type: 'sub',
+          id: 6,
+          lang: 'en',
+          title: 'manual-en.en.srt',
+          external: true,
+          'external-filename': '/tmp/manual-en.en.srt',
+        },
      ];
    },
    refreshCurrentSubtitle: () => {},
@@ -737,7 +775,10 @@ test('youtube flow leaves non-authoritative youtube subtitle tracks untouched af

  await runtime.openManualPicker({ url: 'https://example.com' });

-  assert.equal(commands.some((command) => command[0] === 'sub-remove'), false);
+  assert.equal(
+    commands.some((command) => command[0] === 'sub-remove'),
+    false,
+  );
 });

 test('youtube flow reuses existing manual youtube subtitle tracks when both requested languages already exist', async () => {
@@ -751,8 +792,20 @@ test('youtube flow reuses existing manual youtube subtitle tracks when both requ
      videoId: 'video123',
      title: 'Video 123',
      tracks: [
-        { ...primaryTrack, id: 'manual:ja', sourceLanguage: 'ja', kind: 'manual', title: 'Japanese' },
-        { ...secondaryTrack, id: 'manual:en', sourceLanguage: 'en', kind: 'manual', title: 'English' },
+        {
+          ...primaryTrack,
+          id: 'manual:ja',
+          sourceLanguage: 'ja',
+          kind: 'manual',
+          title: 'Japanese',
+        },
+        {
+          ...secondaryTrack,
+          id: 'manual:en',
+          sourceLanguage: 'en',
+          kind: 'manual',
+          title: 'English',
+        },
      ],
    }),
    acquireYoutubeSubtitleTracks: async () => {
@@ -801,10 +854,38 @@ test('youtube flow reuses existing manual youtube subtitle tracks when both requ
        return selectedSecondarySid;
      }
      return [
-        { type: 'sub', id: 1, lang: 'en', title: 'English', external: true, 'external-filename': null },
-        { type: 'sub', id: 2, lang: 'ja', title: 'Japanese', external: true, 'external-filename': null },
-        { type: 'sub', id: 3, lang: 'ja-en', title: 'Japanese from English', external: true, 'external-filename': null },
-        { type: 'sub', id: 4, lang: 'ja-ja', title: 'Japanese from Japanese', external: true, 'external-filename': null },
+        {
+          type: 'sub',
+          id: 1,
+          lang: 'en',
+          title: 'English',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 2,
+          lang: 'ja',
+          title: 'Japanese',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 3,
+          lang: 'ja-en',
+          title: 'Japanese from English',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 4,
+          lang: 'ja-ja',
+          title: 'Japanese from Japanese',
+          external: true,
+          'external-filename': null,
+        },
      ];
    },
    refreshCurrentSubtitle: () => {},
@@ -833,9 +914,15 @@ test('youtube flow reuses existing manual youtube subtitle tracks when both requ

  assert.equal(selectedPrimarySid, 2);
  assert.equal(selectedSecondarySid, 1);
-  assert.equal(commands.some((command) => command[0] === 'sub-add'), false);
+  assert.equal(
+    commands.some((command) => command[0] === 'sub-add'),
+    false,
+  );
  assert.deepEqual(refreshedSidebarSources, ['/tmp/manual-ja.ja.srt']);
-  assert.equal(commands.some((command) => command[0] === 'sub-remove'), false);
+  assert.equal(
+    commands.some((command) => command[0] === 'sub-remove'),
+    false,
+  );
 });

 test('youtube flow waits for manual youtube tracks to appear before falling back to injected copies', async () => {
@@ -849,8 +936,20 @@ test('youtube flow waits for manual youtube tracks to appear before falling back
      videoId: 'video123',
      title: 'Video 123',
      tracks: [
-        { ...primaryTrack, id: 'manual:ja', sourceLanguage: 'ja', kind: 'manual', title: 'Japanese' },
-        { ...secondaryTrack, id: 'manual:en', sourceLanguage: 'en', kind: 'manual', title: 'English' },
+        {
+          ...primaryTrack,
+          id: 'manual:ja',
+          sourceLanguage: 'ja',
+          kind: 'manual',
+          title: 'Japanese',
+        },
+        {
+          ...secondaryTrack,
+          id: 'manual:en',
+          sourceLanguage: 'en',
+          kind: 'manual',
+          title: 'English',
+        },
      ],
    }),
    acquireYoutubeSubtitleTracks: async () => {
@@ -903,10 +1002,38 @@ test('youtube flow waits for manual youtube tracks to appear before falling back
        return [];
      }
      return [
-        { type: 'sub', id: 1, lang: 'en', title: 'English', external: true, 'external-filename': null },
-        { type: 'sub', id: 2, lang: 'ja', title: 'Japanese', external: true, 'external-filename': null },
-        { type: 'sub', id: 3, lang: 'ja-en', title: 'Japanese from English', external: true, 'external-filename': null },
-        { type: 'sub', id: 4, lang: 'ja-ja', title: 'Japanese from Japanese', external: true, 'external-filename': null },
+        {
+          type: 'sub',
+          id: 1,
+          lang: 'en',
+          title: 'English',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 2,
+          lang: 'ja',
+          title: 'Japanese',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 3,
+          lang: 'ja-en',
+          title: 'Japanese from English',
+          external: true,
+          'external-filename': null,
+        },
+        {
+          type: 'sub',
+          id: 4,
+          lang: 'ja-ja',
+          title: 'Japanese from Japanese',
+          external: true,
+          'external-filename': null,
+        },
      ];
    },
    refreshCurrentSubtitle: () => {},
@@ -932,7 +1059,10 @@ test('youtube flow waits for manual youtube tracks to appear before falling back

  assert.equal(selectedPrimarySid, 2);
  assert.equal(selectedSecondarySid, 1);
-  assert.equal(commands.some((command) => command[0] === 'sub-add'), false);
+  assert.equal(
+    commands.some((command) => command[0] === 'sub-add'),
+    false,
+  );
 });

 test('youtube flow reuses manual youtube tracks even when mpv exposes external filenames', async () => {
@@ -970,7 +1100,9 @@ test('youtube flow reuses manual youtube tracks even when mpv exposes external f
      if (track.id === 'manual:ja') {
        return { path: '/tmp/manual-ja.ja.srt' };
      }
-      throw new Error('should not download secondary track when existing manual english track is reusable');
+      throw new Error(
+        'should not download secondary track when existing manual english track is reusable',
+      );
    },
    openPicker: async () => false,
    pauseMpv: () => {},
@@ -1051,7 +1183,10 @@ test('youtube flow reuses manual youtube tracks even when mpv exposes external f

  assert.equal(selectedPrimarySid, 2);
  assert.equal(selectedSecondarySid, 1);
-  assert.equal(commands.some((command) => command[0] === 'sub-add'), false);
+  assert.equal(
+    commands.some((command) => command[0] === 'sub-add'),
+    false,
+  );
 });

 test('youtube flow falls back to existing auto secondary track when auto secondary download fails', async () => {
--- a/src/main/runtime/youtube-flow.ts
+++ b/src/main/runtime/youtube-flow.ts
@@ -384,7 +384,9 @@ async function injectDownloadedSubtitles(
  } else {
    deps.warn(
      `Unable to bind downloaded primary subtitle track in mpv: ${
-        primarySelection.injectedPath ? path.basename(primarySelection.injectedPath) : primarySelection.track.label
+        primarySelection.injectedPath
+          ? path.basename(primarySelection.injectedPath)
+          : primarySelection.track.label
      }`,
    );
  }
@@ -415,9 +417,7 @@ async function injectDownloadedSubtitles(
    deps.refreshCurrentSubtitle(currentSubText);
  }

-  deps.showMpvOsd(
-    secondaryTrack ? 'Primary and secondary subtitles loaded.' : 'Subtitles loaded.',
-  );
+  deps.showMpvOsd(secondaryTrack ? 'Primary and secondary subtitles loaded.' : 'Subtitles loaded.');
  return true;
 }

@@ -587,7 +587,8 @@ export function createYoutubeFlowRuntime(deps: YoutubeFlowDeps) {
                existingPrimaryTrackId,
              )
            : null;
-        const primaryReady = input.primaryTrack.kind !== 'manual' || existingPrimaryTrackId !== null;
+        const primaryReady =
+          input.primaryTrack.kind !== 'manual' || existingPrimaryTrackId !== null;
        const secondaryReady =
          !input.secondaryTrack ||
          input.secondaryTrack.kind !== 'manual' ||
@@ -631,7 +632,11 @@ export function createYoutubeFlowRuntime(deps: YoutubeFlowDeps) {
        secondaryInjectedPath = acquired.secondaryPath;
      }

-      if (input.secondaryTrack && existingSecondaryTrackId === null && secondaryInjectedPath === null) {
+      if (
+        input.secondaryTrack &&
+        existingSecondaryTrackId === null &&
+        secondaryInjectedPath === null
+      ) {
        try {
          secondaryInjectedPath = (
            await deps.acquireYoutubeSubtitleTrack({
--- a/src/main/runtime/youtube-playback-launch.test.ts
+++ b/src/main/runtime/youtube-playback-launch.test.ts
@@ -183,7 +183,13 @@ test('prepare youtube playback accepts a non-youtube resolved path once playable
    '/videos/episode01.mkv',
    'https://rr16---sn.example.googlevideo.com/videoplayback?id=abc',
  ];
-  const observedTrackLists = [[], [{ type: 'video', id: 1 }, { type: 'audio', id: 2 }]];
+  const observedTrackLists = [
+    [],
+    [
+      { type: 'video', id: 1 },
+      { type: 'audio', id: 2 },
+    ],
+  ];
  let requestCount = 0;
  const prepare = createPrepareYoutubePlaybackInMpvHandler({
    requestPath: async () => {
@@ -256,11 +262,14 @@ test('prepare youtube playback does not accept a different youtube video after p

 test('prepare youtube playback accepts a fresh-start path change when the direct target matches exactly', async () => {
  const commands: Array<Array<string>> = [];
-  const observedPaths = [
-    '',
-    'https://rr16---sn.example.googlevideo.com/videoplayback?id=abc',
+  const observedPaths = ['', 'https://rr16---sn.example.googlevideo.com/videoplayback?id=abc'];
+  const observedTrackLists = [
+    [],
+    [
+      { type: 'video', id: 1 },
+      { type: 'audio', id: 2 },
+    ],
  ];
-  const observedTrackLists = [[], [{ type: 'video', id: 1 }, { type: 'audio', id: 2 }]];
  let requestCount = 0;
  const prepare = createPrepareYoutubePlaybackInMpvHandler({
    requestPath: async () => {
--- a/src/main/runtime/youtube-playback-launch.ts
+++ b/src/main/runtime/youtube-playback-launch.ts
@@ -74,7 +74,9 @@ function hasPlayableMediaTracks(trackListRaw: unknown): boolean {
  if (!Array.isArray(trackListRaw)) return false;
  return trackListRaw.some((track) => {
    if (!track || typeof track !== 'object') return false;
-    const type = String((track as Record<string, unknown>).type || '').trim().toLowerCase();
+    const type = String((track as Record<string, unknown>).type || '')
+      .trim()
+      .toLowerCase();
    return type === 'video' || type === 'audio';
  });
 }
--- a/src/main/runtime/youtube-playback-runtime.test.ts
+++ b/src/main/runtime/youtube-playback-runtime.test.ts
@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createYoutubePlaybackRuntime } from './youtube-playback-runtime';
+
+test('youtube playback runtime resets flow ownership after a successful run', async () => {
+  const calls: string[] = [];
+  let appOwnedFlowInFlight = false;
+  let timeoutCallback: (() => void) | null = null;
+  let socketPath = '/tmp/mpv.sock';
+
+  const runtime = createYoutubePlaybackRuntime({
+    platform: 'linux',
+    directPlaybackFormat: 'best',
+    mpvYtdlFormat: 'bestvideo+bestaudio',
+    autoLaunchTimeoutMs: 2_000,
+    connectTimeoutMs: 1_000,
+    getSocketPath: () => socketPath,
+    getMpvConnected: () => true,
+    invalidatePendingAutoplayReadyFallbacks: () => {
+      calls.push('invalidate-autoplay');
+    },
+    setAppOwnedFlowInFlight: (next) => {
+      appOwnedFlowInFlight = next;
+      calls.push(`app-owned:${next}`);
+    },
+    ensureYoutubePlaybackRuntimeReady: async () => {
+      calls.push('ensure-runtime-ready');
+    },
+    resolveYoutubePlaybackUrl: async () => {
+      throw new Error('linux path should not resolve direct playback url');
+    },
+    launchWindowsMpv: () => ({ ok: false }),
+    waitForYoutubeMpvConnected: async (timeoutMs) => {
+      calls.push(`wait-connected:${timeoutMs}`);
+      return true;
+    },
+    prepareYoutubePlaybackInMpv: async ({ url }) => {
+      calls.push(`prepare:${url}`);
+      return true;
+    },
+    runYoutubePlaybackFlow: async ({ url, mode }) => {
+      calls.push(`run-flow:${url}:${mode}`);
+    },
+    logInfo: (message) => {
+      calls.push(`info:${message}`);
+    },
+    logWarn: (message) => {
+      calls.push(`warn:${message}`);
+    },
+    schedule: (callback) => {
+      timeoutCallback = callback;
+      calls.push('schedule-arm');
+      return 1 as never;
+    },
+    clearScheduled: () => {
+      calls.push('clear-scheduled');
+    },
+  });
+
+  await runtime.runYoutubePlaybackFlow({
+    url: 'https://youtu.be/demo',
+    mode: 'download',
+    source: 'initial',
+  });
+
+  assert.equal(appOwnedFlowInFlight, false);
+  assert.equal(runtime.getQuitOnDisconnectArmed(), false);
+  assert.deepEqual(calls.slice(0, 6), [
+    'invalidate-autoplay',
+    'app-owned:true',
+    'ensure-runtime-ready',
+    'wait-connected:1000',
+    'schedule-arm',
+    'prepare:https://youtu.be/demo',
+  ]);
+
+  assert.ok(timeoutCallback);
+  const scheduledCallback = timeoutCallback as () => void;
+  scheduledCallback();
+  assert.equal(runtime.getQuitOnDisconnectArmed(), true);
+});
+
+test('youtube playback runtime resolves the socket path lazily for windows startup', async () => {
+  const calls: string[] = [];
+  let socketPath = '/tmp/initial.sock';
+
+  const runtime = createYoutubePlaybackRuntime({
+    platform: 'win32',
+    directPlaybackFormat: 'best',
+    mpvYtdlFormat: 'bestvideo+bestaudio',
+    autoLaunchTimeoutMs: 2_000,
+    connectTimeoutMs: 1_000,
+    getSocketPath: () => socketPath,
+    getMpvConnected: () => false,
+    invalidatePendingAutoplayReadyFallbacks: () => {
+      calls.push('invalidate-autoplay');
+    },
+    setAppOwnedFlowInFlight: (next) => {
+      calls.push(`app-owned:${next}`);
+    },
+    ensureYoutubePlaybackRuntimeReady: async () => {
+      calls.push('ensure-runtime-ready');
+    },
+    resolveYoutubePlaybackUrl: async (url, format) => {
+      calls.push(`resolve:${url}:${format}`);
+      return 'https://example.com/direct';
+    },
+    launchWindowsMpv: (_playbackUrl, args) => {
+      calls.push(`launch:${args.join(' ')}`);
+      return { ok: true, mpvPath: '/usr/bin/mpv' };
+    },
+    waitForYoutubeMpvConnected: async (timeoutMs) => {
+      calls.push(`wait-connected:${timeoutMs}`);
+      return true;
+    },
+    prepareYoutubePlaybackInMpv: async ({ url }) => {
+      calls.push(`prepare:${url}`);
+      return true;
+    },
+    runYoutubePlaybackFlow: async ({ url, mode }) => {
+      calls.push(`run-flow:${url}:${mode}`);
+    },
+    logInfo: (message) => {
+      calls.push(`info:${message}`);
+    },
+    logWarn: (message) => {
+      calls.push(`warn:${message}`);
+    },
+    schedule: (callback) => {
+      calls.push('schedule-arm');
+      callback();
+      return 1 as never;
+    },
+    clearScheduled: () => {
+      calls.push('clear-scheduled');
+    },
+  });
+
+  socketPath = '/tmp/updated.sock';
+
+  await runtime.runYoutubePlaybackFlow({
+    url: 'https://youtu.be/demo',
+    mode: 'download',
+    source: 'initial',
+  });
+
+  assert.ok(calls.some((entry) => entry.includes('--input-ipc-server=/tmp/updated.sock')));
+});
--- a/src/main/runtime/youtube-playback-runtime.ts
+++ b/src/main/runtime/youtube-playback-runtime.ts
@@ -0,0 +1,150 @@
+import type { CliArgs, CliCommandSource } from '../../cli/args';
+
+type LaunchResult = {
+  ok: boolean;
+  mpvPath?: string;
+};
+
+export type YoutubePlaybackRuntimeDeps = {
+  platform: NodeJS.Platform;
+  directPlaybackFormat: string;
+  mpvYtdlFormat: string;
+  autoLaunchTimeoutMs: number;
+  connectTimeoutMs: number;
+  getSocketPath: () => string;
+  getMpvConnected: () => boolean;
+  invalidatePendingAutoplayReadyFallbacks: () => void;
+  setAppOwnedFlowInFlight: (next: boolean) => void;
+  ensureYoutubePlaybackRuntimeReady: () => Promise<void>;
+  resolveYoutubePlaybackUrl: (url: string, format: string) => Promise<string>;
+  launchWindowsMpv: (playbackUrl: string, args: string[]) => LaunchResult;
+  waitForYoutubeMpvConnected: (timeoutMs: number) => Promise<boolean>;
+  prepareYoutubePlaybackInMpv: (request: { url: string }) => Promise<boolean>;
+  runYoutubePlaybackFlow: (request: {
+    url: string;
+    mode: NonNullable<CliArgs['youtubeMode']>;
+  }) => Promise<void>;
+  logInfo: (message: string) => void;
+  logWarn: (message: string) => void;
+  schedule: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+  clearScheduled: (timer: ReturnType<typeof setTimeout>) => void;
+};
+
+export function createYoutubePlaybackRuntime(deps: YoutubePlaybackRuntimeDeps) {
+  let quitOnDisconnectArmed = false;
+  let quitOnDisconnectArmTimer: ReturnType<typeof setTimeout> | null = null;
+  let playbackFlowGeneration = 0;
+
+  const clearYoutubePlayQuitOnDisconnectArmTimer = (): void => {
+    if (quitOnDisconnectArmTimer) {
+      deps.clearScheduled(quitOnDisconnectArmTimer);
+      quitOnDisconnectArmTimer = null;
+    }
+  };
+
+  const runYoutubePlaybackFlow = async (request: {
+    url: string;
+    mode: NonNullable<CliArgs['youtubeMode']>;
+    source: CliCommandSource;
+  }): Promise<void> => {
+    const flowGeneration = ++playbackFlowGeneration;
+    deps.invalidatePendingAutoplayReadyFallbacks();
+    deps.setAppOwnedFlowInFlight(true);
+    let flowCompleted = false;
+
+    try {
+      clearYoutubePlayQuitOnDisconnectArmTimer();
+      quitOnDisconnectArmed = false;
+      await deps.ensureYoutubePlaybackRuntimeReady();
+
+      let playbackUrl = request.url;
+      let launchedWindowsMpv = false;
+      if (deps.platform === 'win32') {
+        try {
+          playbackUrl = await deps.resolveYoutubePlaybackUrl(
+            request.url,
+            deps.directPlaybackFormat,
+          );
+          deps.logInfo('Resolved direct YouTube playback URL for Windows MPV startup.');
+        } catch (error) {
+          deps.logWarn(
+            `Failed to resolve direct YouTube playback URL; falling back to page URL: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+      }
+
+      if (deps.platform === 'win32' && !deps.getMpvConnected()) {
+        const socketPath = deps.getSocketPath();
+        const launchResult = deps.launchWindowsMpv(playbackUrl, [
+          '--pause=yes',
+          '--ytdl=yes',
+          `--ytdl-format=${deps.mpvYtdlFormat}`,
+          '--sub-auto=no',
+          '--sub-file-paths=.;subs;subtitles',
+          '--sid=auto',
+          '--secondary-sid=auto',
+          '--secondary-sub-visibility=no',
+          '--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
+          '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
+          `--input-ipc-server=${socketPath}`,
+        ]);
+        launchedWindowsMpv = launchResult.ok;
+        if (launchResult.ok && launchResult.mpvPath) {
+          deps.logInfo(`Bootstrapping Windows mpv for YouTube playback via ${launchResult.mpvPath}`);
+        }
+        if (!launchResult.ok) {
+          deps.logWarn('Unable to bootstrap Windows mpv for YouTube playback.');
+        }
+      }
+
+      const connected = await deps.waitForYoutubeMpvConnected(
+        launchedWindowsMpv ? deps.autoLaunchTimeoutMs : deps.connectTimeoutMs,
+      );
+      if (!connected) {
+        throw new Error(
+          launchedWindowsMpv
+            ? 'MPV not connected after auto-launch. Ensure mpv is installed and can open the requested YouTube URL.'
+            : 'MPV not connected. Start mpv with the SubMiner profile or retry after mpv finishes starting.',
+        );
+      }
+
+      if (request.source === 'initial') {
+        quitOnDisconnectArmTimer = deps.schedule(() => {
+          if (playbackFlowGeneration !== flowGeneration) {
+            return;
+          }
+          quitOnDisconnectArmed = true;
+          quitOnDisconnectArmTimer = null;
+        }, 3000);
+      }
+
+      const mediaReady = await deps.prepareYoutubePlaybackInMpv({ url: playbackUrl });
+      if (!mediaReady) {
+        throw new Error('Timed out waiting for mpv to load the requested YouTube URL.');
+      }
+
+      await deps.runYoutubePlaybackFlow({
+        url: request.url,
+        mode: request.mode,
+      });
+      flowCompleted = true;
+      deps.logInfo(`YouTube playback flow completed from ${request.source}.`);
+    } finally {
+      if (playbackFlowGeneration === flowGeneration) {
+        if (!flowCompleted) {
+          clearYoutubePlayQuitOnDisconnectArmTimer();
+          quitOnDisconnectArmed = false;
+        }
+        deps.setAppOwnedFlowInFlight(false);
+      }
+    }
+  };
+
+  return {
+    clearYoutubePlayQuitOnDisconnectArmTimer,
+    getQuitOnDisconnectArmed: (): boolean => quitOnDisconnectArmed,
+    runYoutubePlaybackFlow,
+  };
+}
--- a/src/main/runtime/youtube-primary-subtitle-notification.ts
+++ b/src/main/runtime/youtube-primary-subtitle-notification.ts
@@ -1,7 +1,9 @@
 import { isYoutubeMediaPath } from './youtube-playback';
 import { normalizeYoutubeLangCode } from '../../core/services/youtube/labels';

-export type YoutubePrimarySubtitleNotificationTimer = ReturnType<typeof setTimeout> | { id: number };
+export type YoutubePrimarySubtitleNotificationTimer =
+  | ReturnType<typeof setTimeout>
+  | { id: number };

 type SubtitleTrackEntry = {
  id: number | null;
@@ -82,7 +84,9 @@ function hasSelectedPrimarySubtitle(

  const tracks = trackList.map(normalizeTrack);
  const activeTrack =
-    (sid === null ? null : tracks.find((track) => track?.type === 'sub' && track.id === sid) ?? null) ??
+    (sid === null
+      ? null
+      : (tracks.find((track) => track?.type === 'sub' && track.id === sid) ?? null)) ??
    tracks.find((track) => track?.type === 'sub' && track.selected) ??
    null;
  if (!activeTrack) {
@@ -130,7 +134,9 @@ export function createYoutubePrimarySubtitleNotificationRuntime(deps: {
      return;
    }
    lastReportedMediaPath = mediaPath;
-    deps.notifyFailure('Primary subtitle failed to download or load. Try again from the subtitle modal.');
+    deps.notifyFailure(
+      'Primary subtitle failed to download or load. Try again from the subtitle modal.',
+    );
  };

  const schedulePendingCheck = (): void => {
@@ -150,7 +156,8 @@ export function createYoutubePrimarySubtitleNotificationRuntime(deps: {

  return {
    handleMediaPathChange: (path: string | null): void => {
-      const normalizedPath = typeof path === 'string' && path.trim().length > 0 ? path.trim() : null;
+      const normalizedPath =
+        typeof path === 'string' && path.trim().length > 0 ? path.trim() : null;
      if (currentMediaPath !== normalizedPath) {
        lastReportedMediaPath = null;
      }