add app control server for launcher-to-app attachment

- Launcher detects a running app via control socket and attaches without spawning a new process
- Own-lifecycle app launches now pass --background --managed-playback; borrowed apps skip --background
- Separate plain subtitle websocket (tokens: []) from annotation websocket
- Default pauseVideoOnHover to true; update docs and config.example.jsonc
- Setup: remove plugin readiness card, add Open SubMiner Settings button

launcher/commands/playback-command.test.ts

@@ -206,3 +206,65 @@ test('plugin auto-start playback leaves app lifetime to managed-playback owner',
     state.overlayManagedByLauncher = false;
   }
 });
+
+test('plugin auto-start playback attaches a warm background app through the launcher', async () => {
+  const context = createContext();
+  context.args = {
+    ...context.args,
+    target: '/tmp/movie.mkv',
+    targetKind: 'file',
+  };
+  context.pluginRuntimeConfig = {
+    socketPath: '/tmp/subminer.sock',
+    binaryPath: '',
+    backend: 'auto',
+    autoStart: true,
+    autoStartVisibleOverlay: true,
+    autoStartPauseUntilReady: true,
+    texthookerEnabled: true,
+    aniskipEnabled: true,
+    aniskipButtonKey: 'TAB',
+  };
+  const calls: string[] = [];
+  const receivedStartMpvOptions: Record<string, unknown>[] = [];
+
+  await runPlaybackCommandWithDeps(context, {
+    ensurePlaybackSetupReady: async () => {},
+    chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
+    checkDependencies: () => {},
+    registerCleanup: () => {},
+    startMpv: async (
+      _target,
+      _targetKind,
+      _args,
+      _socketPath,
+      _appPath,
+      _preloadedSubtitles,
+      options,
+    ) => {
+      calls.push('startMpv');
+      if (options) {
+        receivedStartMpvOptions.push(options as Record<string, unknown>);
+      }
+    },
+    waitForUnixSocketReady: async () => true,
+    startOverlay: async (_appPath, _args, _socketPath, extraAppArgs = []) => {
+      calls.push(`startOverlay:${extraAppArgs.join(' ')}`);
+    },
+    launchAppCommandDetached: () => {},
+    log: () => {},
+    cleanupPlaybackSession: async () => {},
+    getMpvProc: () => null,
+    isAppControlServerAvailable: async () => true,
+  } as Parameters<typeof runPlaybackCommandWithDeps>[1] & {
+    isAppControlServerAvailable: () => Promise<boolean>;
+  });
+
+  assert.deepEqual(calls, ['startMpv', 'startOverlay:--show-visible-overlay --texthooker']);
+  assert.equal(receivedStartMpvOptions[0]?.startPaused, false);
+  assert.equal(
+    (receivedStartMpvOptions[0]?.runtimePluginConfig as { autoStart?: boolean } | undefined)
+      ?.autoStart,
+    false,
+  );
+});

launcher/commands/playback-command.ts

@@ -8,6 +8,7 @@ import {
   cleanupPlaybackSession,
   launchAppCommandDetached,
   resolveLauncherRuntimePluginPath,
+  isRunningAppControlServerAvailable,
   startMpv,
   startOverlay,
   state,
@@ -146,6 +147,7 @@ export async function runPlaybackCommand(context: LauncherCommandContext): Promi
     waitForUnixSocketReady,
     startOverlay,
     launchAppCommandDetached,
+    isAppControlServerAvailable: isRunningAppControlServerAvailable,
     log,
     cleanupPlaybackSession,
     getMpvProc: () => state.mpvProc,
@@ -164,6 +166,7 @@ type PlaybackCommandDeps = {
   waitForUnixSocketReady: typeof waitForUnixSocketReady;
   startOverlay: typeof startOverlay;
   launchAppCommandDetached: typeof launchAppCommandDetached;
+  isAppControlServerAvailable?: (logLevel: Args['logLevel']) => Promise<boolean>;
   log: typeof log;
   cleanupPlaybackSession: typeof cleanupPlaybackSession;
   getMpvProc: () => typeof state.mpvProc;
@@ -213,8 +216,19 @@ export async function runPlaybackCommandWithDeps(
     deps.log('info', args.logLevel, 'YouTube subtitle flow: app-owned picker after mpv bootstrap');
   }
 
+  const pluginAutoStartEnabled = pluginRuntimeConfig.autoStart;
+  const shouldLauncherAttachRunningApp =
+    pluginAutoStartEnabled &&
+    !args.startOverlay &&
+    !args.autoStartOverlay &&
+    !isAppOwnedYoutubeFlow &&
+    ((await deps.isAppControlServerAvailable?.(args.logLevel)) ?? false);
+  const effectivePluginRuntimeConfig = shouldLauncherAttachRunningApp
+    ? { ...pluginRuntimeConfig, autoStart: false }
+    : pluginRuntimeConfig;
+
   const shouldPauseUntilOverlayReady =
-    pluginRuntimeConfig.autoStart &&
+    effectivePluginRuntimeConfig.autoStart &&
     pluginRuntimeConfig.autoStartVisibleOverlay &&
     pluginRuntimeConfig.autoStartPauseUntilReady;
 
@@ -238,16 +252,19 @@ export async function runPlaybackCommandWithDeps(
       disableYoutubeSubtitleAutoLoad: isAppOwnedYoutubeFlow,
       runtimePluginPath: resolveLauncherRuntimePluginPath({ appPath, scriptPath }),
       runtimePluginConfig: {
-        ...pluginRuntimeConfig,
+        ...effectivePluginRuntimeConfig,
         backend: args.backend,
-        texthookerEnabled: args.useTexthooker && pluginRuntimeConfig.texthookerEnabled,
+        texthookerEnabled: args.useTexthooker && effectivePluginRuntimeConfig.texthookerEnabled,
       },
     },
   );
 
   const ready = await deps.waitForUnixSocketReady(mpvSocketPath, 10000);
-  const pluginAutoStartEnabled = pluginRuntimeConfig.autoStart;
-  const shouldStartOverlay = args.startOverlay || args.autoStartOverlay || isAppOwnedYoutubeFlow;
+  const shouldStartOverlay =
+    args.startOverlay ||
+    args.autoStartOverlay ||
+    isAppOwnedYoutubeFlow ||
+    shouldLauncherAttachRunningApp;
   if (shouldStartOverlay) {
     if (ready) {
       deps.log('info', args.logLevel, 'MPV IPC socket ready, starting SubMiner overlay');
@@ -258,14 +275,17 @@ export async function runPlaybackCommandWithDeps(
         'MPV IPC socket not ready after timeout, starting SubMiner overlay anyway',
       );
     }
-    await deps.startOverlay(
-      appPath,
-      args,
-      mpvSocketPath,
-      isAppOwnedYoutubeFlow
-        ? ['--youtube-play', selectedTarget.target, '--youtube-mode', youtubeMode]
-        : [],
-    );
+    const extraAppArgs = isAppOwnedYoutubeFlow
+      ? ['--youtube-play', selectedTarget.target, '--youtube-mode', youtubeMode]
+      : shouldLauncherAttachRunningApp
+        ? [
+            pluginRuntimeConfig.autoStartVisibleOverlay
+              ? '--show-visible-overlay'
+              : '--hide-visible-overlay',
+            ...(pluginRuntimeConfig.texthookerEnabled ? ['--texthooker'] : []),
+          ]
+        : [];
+    await deps.startOverlay(appPath, args, mpvSocketPath, extraAppArgs);
   } else if (pluginAutoStartEnabled) {
     if (ready) {
       deps.log('info', args.logLevel, 'MPV IPC socket ready, relying on mpv plugin auto-start');