fix(launcher): restore Matroska thumbnails in Linux rofi picker (#210)

launcher/commands/history-command.ts

@@ -23,6 +23,7 @@ import {
   type HistorySeriesEntry,
 } from '../history.js';
 import type { Args } from '../types.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import type { LauncherCommandContext } from './context.js';
 
 export type HistorySessionAction = 'previous' | 'replay' | 'next' | 'browse' | 'quit';
@@ -333,6 +334,13 @@ export async function runHistoryCommand(
   const { args, scriptPath } = context;
 
   checkPickerDependencies(args);
+  if (args.useRofi) {
+    await ensureLinuxRuntimePluginAvailable({
+      appPath: context.appPath ?? undefined,
+      scriptPath,
+      logLevel: args.logLevel,
+    });
+  }
   const themePath = args.useRofi ? findRofiTheme(scriptPath) : null;
 
   const dbPath = resolveImmersionDbPath();

launcher/commands/jellyfin-command.ts

@@ -2,6 +2,7 @@ import { fail } from '../log.js';
 import { runAppCommandWithInherit } from '../mpv.js';
 import { commandExists } from '../util.js';
 import { runJellyfinPlayMenu } from '../jellyfin.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import { shouldForwardLogLevel } from '../types.js';
 import type { LauncherCommandContext } from './context.js';
 
@@ -64,6 +65,13 @@ export async function runJellyfinCommand(context: LauncherCommandContext): Promi
     if (args.useRofi && !commandExists('rofi')) {
       fail('rofi not found. Install rofi or omit -R for fzf.');
     }
+    if (args.useRofi) {
+      await ensureLinuxRuntimePluginAvailable({
+        appPath,
+        scriptPath,
+        logLevel: args.logLevel,
+      });
+    }
     await runJellyfinPlayMenu(appPath, args, scriptPath, mpvSocketPath);
     return true;
   }

launcher/commands/playback-command.test.ts

@@ -496,3 +496,39 @@ test('playback command ensures Linux runtime plugin before mpv launch', async ()
 
   assert.deepEqual(calls, ['plugin', 'startMpv']);
 });
+
+test('rofi playback repairs support assets before opening the picker', async () => {
+  const context = createContext();
+  context.args = {
+    ...context.args,
+    target: '',
+    targetKind: '',
+    useRofi: true,
+  };
+  const calls: string[] = [];
+
+  await runPlaybackCommandWithDeps(context, {
+    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {
+      calls.push('assets');
+    },
+    chooseTarget: async () => {
+      calls.push('picker');
+      return { target: '/tmp/movie.mkv', kind: 'file' };
+    },
+    checkPickerDependencies: () => {},
+    checkDependencies: () => {},
+    registerCleanup: () => {},
+    startMpv: async () => {
+      calls.push('startMpv');
+    },
+    waitForUnixSocketReady: async () => true,
+    startOverlay: async () => {},
+    launchAppCommandDetached: () => {},
+    log: () => {},
+    cleanupPlaybackSession: async () => {},
+    getMpvProc: () => null,
+  });
+
+  assert.deepEqual(calls, ['assets', 'picker', 'startMpv']);
+});

launcher/commands/playback-command.ts

@@ -157,6 +157,7 @@ export async function runPlaybackCommand(context: LauncherCommandContext): Promi
       });
     },
     chooseTarget,
+    checkPickerDependencies,
     checkDependencies,
     registerCleanup,
     startMpv,
@@ -177,6 +178,7 @@ type PlaybackCommandDeps = {
     args: Args,
     scriptPath: string,
   ) => Promise<{ target: string; kind: 'file' | 'url' } | null>;
+  checkPickerDependencies?: (args: Args) => void;
   checkDependencies: (args: Args) => void;
   registerCleanup: (context: LauncherCommandContext) => void;
   startMpv: typeof startMpv;
@@ -201,7 +203,18 @@ export async function runPlaybackCommandWithDeps(
   await deps.ensurePlaybackSetupReady(context);
 
   if (!args.target) {
-    checkPickerDependencies(args);
+    (deps.checkPickerDependencies ?? checkPickerDependencies)(args);
+  }
+
+  let runtimeAssetsReady = false;
+  const ensureRuntimeAssetsReady = async (): Promise<void> => {
+    if (runtimeAssetsReady) return;
+    await deps.ensureRuntimePluginReady(context);
+    runtimeAssetsReady = true;
+  };
+
+  if (!args.target && args.useRofi) {
+    await ensureRuntimeAssetsReady();
   }
 
   const targetChoice = await deps.chooseTarget(args, scriptPath);
@@ -266,7 +279,7 @@ export async function runPlaybackCommandWithDeps(
     );
   }
 
-  await deps.ensureRuntimePluginReady(context);
+  await ensureRuntimeAssetsReady();
 
   await deps.startMpv(
     selectedTarget.target,

launcher/commands/update-command.test.ts

@@ -36,6 +36,11 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
         launcher: { status: 'updated' },
         supportAssets: [
           { status: 'updated', component: 'theme', message: 'Installed theme.' },
+          {
+            status: 'updated',
+            component: 'thumbnailer',
+            message: 'Installed rofi thumbnailer.',
+          },
           { status: 'skipped', component: 'plugin', message: 'Plugin already up to date.' },
         ],
       };
@@ -52,6 +57,7 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
     'info:AppImage update: updated',
     'info:Launcher update: updated',
     'info:Support assets (theme) update: updated - Installed theme.',
+    'info:Support assets (thumbnailer) update: updated - Installed rofi thumbnailer.',
     'info:Support assets (plugin) update: skipped - Plugin already up to date.',
   ]);
 });

launcher/commands/update-command.ts

@@ -21,7 +21,10 @@ import {
   parseSha256Sums,
   type FetchLike,
 } from '../../src/main/runtime/update/release-assets.js';
-import { updateSupportAssetsFromRelease } from '../../src/main/runtime/update/support-assets.js';
+import {
+  updateSupportAssetsFromRelease,
+  type SupportAssetsUpdateResult,
+} from '../../src/main/runtime/update/support-assets.js';
 
 type UpdateCommandResponse = {
   ok: boolean;
@@ -36,15 +39,14 @@ type DirectReleaseUpdateRequest = {
   channel: UpdateChannel;
 };
 
+type DirectSupportAssetsUpdateResult = Omit<SupportAssetsUpdateResult, 'status'> & {
+  status: string;
+};
+
 type DirectReleaseUpdateResult = {
   appImage: { status: string; command?: string; message?: string };
   launcher: { status: string; command?: string; message?: string };
-  supportAssets: Array<{
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  }>;
+  supportAssets: DirectSupportAssetsUpdateResult[];
 };
 
 type UpdateCommandDeps = {
@@ -129,12 +131,7 @@ function readUpdateChannel(root: Record<string, unknown> | null): UpdateChannel
 
 function logUpdateResult(
   label: string,
-  result: {
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  },
+  result: DirectSupportAssetsUpdateResult,
   configuredLogLevel: NonNullable<LauncherCommandContext['args']['logLevel']>,
   deps: Pick<UpdateCommandDeps, 'log'>,
 ): void {

launcher/main.test.ts

@@ -73,20 +73,21 @@ function makeTestEnv(homeDir: string, xdgConfigHome: string): NodeJS.ProcessEnv
   };
 }
 
-// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which —
-// when the runtime plugin/theme are missing — spawns the app with
-// `--ensure-linux-runtime-plugin-assets` and polls up to 30s
+// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which
+// spawns the app with `--ensure-linux-runtime-plugin-assets` when managed
+// support assets are missing and polls up to 30s
 // (RESPONSE_TIMEOUT_MS) for an install response. A fake app that just exits
 // never writes that response, so the launcher hangs and the test times out on
 // Linux CI (the preflight is a no-op on macOS/Windows). This shell prelude makes
-// the fake app install the managed plugin/theme and write the response, matching
+// the fake app install the managed support assets and write the response, matching
 // launcher/smoke.e2e.test.ts. Prepend it to each fake app that reaches playback.
 const RUNTIME_PLUGIN_PREFLIGHT_SH = `if [ "$1" = "--ensure-linux-runtime-plugin-assets" ]; then
   data="\${XDG_DATA_HOME:-$HOME/.local/share}/SubMiner"
-  mkdir -p "$data/plugin/subminer" "$data/themes"
+  mkdir -p "$data/plugin/subminer" "$data/themes" "$data/thumbnailers"
   printf -- '-- test plugin\\n' > "$data/plugin/subminer/main.lua"
   printf 'test=true\\n' > "$data/plugin/subminer.conf"
   printf '/* test theme */\\n' > "$data/themes/subminer.rasi"
+  printf '[Thumbnailer Entry]\\n' > "$data/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"
   if [ "$2" = "--ensure-linux-runtime-plugin-assets-response-path" ] && [ -n "$3" ]; then
     mkdir -p "$(dirname "$3")"
     printf '{"ok":true,"status":"installed","path":"%s"}' "$data/plugin/subminer/main.lua" > "$3"

launcher/picker.test.ts

@@ -3,7 +3,12 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { findRofiTheme, formatRofiPrompt } from './picker';
+import {
+  findRofiTheme,
+  findRofiThumbnailerDataRoot,
+  formatRofiPrompt,
+  prependXdgDataDir,
+} from './picker';
 
 // ── formatRofiPrompt: spacing between prompt and input field ──────────────────
 
@@ -23,6 +28,7 @@ test('formatRofiPrompt leaves an empty prompt empty', () => {
 // ── findRofiTheme: Linux packaged path discovery ──────────────────────────────
 
 const ROFI_THEME_FILE = 'subminer.rasi';
+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';
 
 function makeFile(filePath: string): void {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -121,3 +127,42 @@ test('findRofiTheme resolves ~/.local/share/SubMiner/themes/subminer.rasi when X
     fs.rmSync(baseDir, { recursive: true, force: true });
   }
 });
+
+test('findRofiThumbnailerDataRoot resolves the managed XDG data root', () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-test-xdg-'));
+  const originalXdgDataHome = process.env.XDG_DATA_HOME;
+  try {
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    const dataRoot = path.join(xdgDataHome, 'SubMiner');
+    makeFile(path.join(dataRoot, 'thumbnailers', ROFI_THUMBNAILER_FILE));
+
+    const result = withPlatform('linux', () => findRofiThumbnailerDataRoot('/usr/bin/subminer'));
+    assert.equal(result, dataRoot);
+  } finally {
+    if (originalXdgDataHome === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = originalXdgDataHome;
+    }
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+  }
+});
+
+test('findRofiThumbnailerDataRoot is Linux-only', () => {
+  assert.equal(
+    withPlatform('darwin', () => findRofiThumbnailerDataRoot('/usr/bin/subminer')),
+    null,
+  );
+});
+
+test('prependXdgDataDir preserves existing roots and avoids duplicates', () => {
+  const root = '/tmp/subminer-data';
+  assert.equal(
+    prependXdgDataDir(root, `/opt/share${path.delimiter}${root}${path.delimiter}/usr/share`),
+    `${root}${path.delimiter}/opt/share${path.delimiter}/usr/share`,
+  );
+  assert.equal(
+    prependXdgDataDir(root),
+    `${root}${path.delimiter}/usr/local/share${path.delimiter}/usr/share`,
+  );
+});

launcher/picker.ts

@@ -159,6 +159,9 @@ interface RofiIconEntry {
   iconPath?: string;
 }
 
+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';
+const DEFAULT_XDG_DATA_DIRS = ['/usr/local/share', '/usr/share'];
+
 function showRofiIconMenu(
   entries: RofiIconEntry[],
   prompt: string,
@@ -389,6 +392,47 @@ export function findRofiTheme(scriptPath: string): string | null {
   return null;
 }
 
+export function findRofiThumbnailerDataRoot(scriptPath: string): string | null {
+  if (process.platform !== 'linux') return null;
+
+  const scriptDir = path.dirname(realpathMaybe(scriptPath));
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local/share');
+  const roots = [
+    path.join(xdgDataHome, 'SubMiner'),
+    path.posix.join('/usr/local/share/SubMiner'),
+    path.posix.join('/usr/share/SubMiner'),
+    path.join(scriptDir, 'assets'),
+    path.join(scriptDir, '..', 'assets'),
+  ];
+
+  for (const root of roots) {
+    if (fs.existsSync(path.join(root, 'thumbnailers', ROFI_THUMBNAILER_FILE))) {
+      return root;
+    }
+  }
+
+  return null;
+}
+
+export function prependXdgDataDir(dataRoot: string, currentValue?: string): string {
+  const currentDirs = currentValue
+    ? currentValue.split(path.delimiter).filter(Boolean)
+    : DEFAULT_XDG_DATA_DIRS;
+  return [dataRoot, ...currentDirs.filter((candidate) => candidate !== dataRoot)].join(
+    path.delimiter,
+  );
+}
+
+function buildRofiThumbnailEnvironment(scriptPath: string): NodeJS.ProcessEnv {
+  if (!commandExists('ffmpegthumbnailer')) return process.env;
+  const dataRoot = findRofiThumbnailerDataRoot(scriptPath);
+  if (!dataRoot) return process.env;
+  return {
+    ...process.env,
+    XDG_DATA_DIRS: prependXdgDataDir(dataRoot, process.env.XDG_DATA_DIRS),
+  };
+}
+
 export function showRofiMenu(
   videos: string[],
   dir: string,
@@ -420,6 +464,7 @@ export function showRofiMenu(
   const result = spawnSync('rofi', args, {
     input: buildRofiMenu(videos, dir, recursive),
     encoding: 'utf8',
+    env: buildRofiThumbnailEnvironment(scriptPath),
     stdio: ['pipe', 'pipe', 'ignore'],
   });
   if (result.error) {

launcher/runtime-plugin-preflight.test.ts

@@ -1,6 +1,8 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import {
   ensureLinuxRuntimePluginAvailable,
   installManagedPluginAssetsViaApp,
@@ -31,7 +33,7 @@ test('ensureLinuxRuntimePluginAvailable is a no-op on non-Linux platforms', asyn
   assert.deepEqual(calls, []);
 });
 
-test('ensureLinuxRuntimePluginAvailable skips install when installed global plugin and managed theme exist', async () => {
+test('ensureLinuxRuntimePluginAvailable skips install when plugin, theme, and thumbnailer exist', async () => {
   const calls: string[] = [];
 
   await ensureLinuxRuntimePluginAvailable({
@@ -52,13 +54,17 @@ test('ensureLinuxRuntimePluginAvailable skips install when installed global plug
       calls.push('theme');
       return true;
     },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
+    },
     log: () => {},
   });
 
-  assert.deepEqual(calls, ['detect', 'theme']);
+  assert.deepEqual(calls, ['detect', 'theme', 'thumbnailer']);
 });
 
-test('ensureLinuxRuntimePluginAvailable skips install when managed runtime path and theme already resolve', async () => {
+test('ensureLinuxRuntimePluginAvailable skips install when all managed assets resolve', async () => {
   const calls: string[] = [];
 
   await ensureLinuxRuntimePluginAvailable({
@@ -80,14 +86,19 @@ test('ensureLinuxRuntimePluginAvailable skips install when managed runtime path
       calls.push('theme');
       return true;
     },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
+    },
     log: () => {},
   });
 
-  assert.deepEqual(calls, ['detect', 'resolve', 'theme']);
+  assert.deepEqual(calls, ['detect', 'resolve', 'theme', 'thumbnailer']);
 });
 
 test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme is missing', async () => {
   const calls: string[] = [];
+  let themeAvailable = false;
 
   await ensureLinuxRuntimePluginAvailable({
     platform: 'linux',
@@ -102,10 +113,15 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme
     },
     isManagedThemeAvailable: () => {
       calls.push('theme');
-      return false;
+      return themeAvailable;
+    },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
     },
     installManagedPluginAssets: async () => {
       calls.push('install');
+      themeAvailable = true;
       return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
     },
     log: (level, _configured, message) => {
@@ -117,13 +133,68 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme
     'detect',
     'resolve',
     'theme',
-    'info:Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
     'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi',
+    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
     'resolve',
+    'theme',
+    'thumbnailer',
   ]);
 });
 
+test('ensureLinuxRuntimePluginAvailable installs managed assets when thumbnailer is missing', async () => {
+  const calls: string[] = [];
+  let thumbnailerAvailable = false;
+
+  await ensureLinuxRuntimePluginAvailable({
+    platform: 'linux',
+    xdgDataHome: '/tmp/xdg-data',
+    detectInstalledPlugin: () => true,
+    resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
+    installManagedPluginAssets: async () => {
+      calls.push('install');
+      thumbnailerAvailable = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
+    log: (_level, _configured, message) => {
+      calls.push(message);
+    },
+  });
+
+  assert.deepEqual(calls, [
+    'Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
+    'install',
+    'Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
+  ]);
+});
+
+test('ensureLinuxRuntimePluginAvailable retains an installed plugin after installing support assets', async () => {
+  const calls: string[] = [];
+  let thumbnailerAvailable = false;
+
+  await ensureLinuxRuntimePluginAvailable({
+    platform: 'linux',
+    xdgDataHome: '/tmp/xdg-data',
+    detectInstalledPlugin: () => true,
+    resolveRuntimePluginPath: () => {
+      calls.push('resolve');
+      return null;
+    },
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
+    installManagedPluginAssets: async () => {
+      calls.push('install');
+      thumbnailerAvailable = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
+    log: () => {},
+  });
+
+  assert.deepEqual(calls, ['install']);
+});
+
 test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves plugin path', async () => {
   const calls: string[] = [];
   let resolveCount = 0;
@@ -137,6 +208,8 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves
       calls.push(`resolve:${resolveCount}`);
       return resolveCount === 1 ? null : '/tmp/plugin/main.lua';
     },
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => true,
     installManagedPluginAssets: async () => {
       calls.push('install');
       return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
@@ -148,9 +221,9 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves
 
   assert.deepEqual(calls, [
     'resolve:1',
-    'info:Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
     'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi',
+    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
     'resolve:2',
   ]);
 });
@@ -191,6 +264,60 @@ test('ensureLinuxRuntimePluginAvailable fails when runtime path remains unresolv
   );
 });
 
+test('ensureLinuxRuntimePluginAvailable fails when thumbnailer remains missing after install', async () => {
+  await assert.rejects(
+    () =>
+      ensureLinuxRuntimePluginAvailable({
+        platform: 'linux',
+        xdgDataHome: '/tmp/xdg-data',
+        detectInstalledPlugin: () => true,
+        resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
+        isManagedThemeAvailable: () => true,
+        isManagedThumbnailerAvailable: () => false,
+        installManagedPluginAssets: async () => ({
+          ok: true,
+          status: 'installed',
+          path: '/tmp/plugin/main.lua',
+        }),
+        log: () => {},
+      }),
+    /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
+  );
+});
+
+test('ensureLinuxRuntimePluginAvailable rejects a thumbnailer directory before and after install', async () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-thumbnailer-directory-'));
+  const thumbnailerPath = path.join(
+    xdgDataHome,
+    'SubMiner',
+    'thumbnailers',
+    'subminer-ffmpegthumbnailer.thumbnailer',
+  );
+  fs.mkdirSync(thumbnailerPath, { recursive: true });
+  const calls: string[] = [];
+
+  try {
+    await assert.rejects(
+      () =>
+        ensureLinuxRuntimePluginAvailable({
+          platform: 'linux',
+          xdgDataHome,
+          detectInstalledPlugin: () => true,
+          isManagedThemeAvailable: () => true,
+          installManagedPluginAssets: async () => {
+            calls.push('install');
+            return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+          },
+          log: () => {},
+        }),
+      /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
+    );
+    assert.deepEqual(calls, ['install']);
+  } finally {
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+  }
+});
+
 test('installManagedPluginAssetsViaApp returns launch errors without waiting for a response file', async () => {
   let waited = false;
 

launcher/runtime-plugin-preflight.ts

@@ -31,6 +31,7 @@ type EnsureLinuxRuntimePluginAvailableOptions = {
   detectInstalledPlugin?: () => boolean;
   resolveRuntimePluginPath?: () => string | null;
   isManagedThemeAvailable?: () => boolean;
+  isManagedThumbnailerAvailable?: () => boolean;
   installManagedPluginAssets?: () => Promise<EnsureLinuxRuntimePluginAssetsResult>;
   log?: PreflightLog;
 };
@@ -48,6 +49,14 @@ function resolveConfiguredLogLevel(
   return logLevel ?? 'warn';
 }
 
+function isRegularFile(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
 async function waitForInstallResponse(
   responsePath: string,
 ): Promise<RuntimePluginPreflightResponse | null> {
@@ -170,15 +179,17 @@ export async function ensureLinuxRuntimePluginAvailable(
     });
   const isManagedThemeAvailable =
     options.isManagedThemeAvailable ?? (() => fs.existsSync(managedPaths.themePath));
+  const isManagedThumbnailerAvailable =
+    options.isManagedThumbnailerAvailable ?? (() => isRegularFile(managedPaths.thumbnailerPath));
   const runtimePluginAvailable = installedPluginAvailable || Boolean(resolveRuntimePluginPath());
-  if (runtimePluginAvailable && isManagedThemeAvailable()) {
+  if (runtimePluginAvailable && isManagedThemeAvailable() && isManagedThumbnailerAvailable()) {
     return;
   }
 
   log(
     'info',
     configuredLogLevel,
-    'Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
   );
   const installManagedPluginAssets =
     options.installManagedPluginAssets ??
@@ -207,16 +218,21 @@ export async function ensureLinuxRuntimePluginAvailable(
   log(
     'info',
     configuredLogLevel,
-    `Managed Linux runtime support assets installed: plugin=${installResult.path ?? 'unknown path'} theme=${managedPaths.themePath}`,
+    `Managed Linux runtime support assets installed: plugin=${installResult.path ?? 'unknown path'} theme=${managedPaths.themePath} thumbnailer=${managedPaths.thumbnailerPath}`,
   );
-  const runtimePluginPath = resolveRuntimePluginPath();
-  if (runtimePluginPath) {
+  const runtimePluginAvailableAfterInstall =
+    installedPluginAvailable || Boolean(resolveRuntimePluginPath());
+  if (
+    runtimePluginAvailableAfterInstall &&
+    isManagedThemeAvailable() &&
+    isManagedThumbnailerAvailable()
+  ) {
     return;
   }
 
   const message =
     `Linux managed runtime plugin assets could not be installed. ` +
-    `Checked path: ${managedPaths.pluginEntrypointPath}. ` +
+    `Checked paths: plugin=${managedPaths.pluginEntrypointPath} theme=${managedPaths.themePath} thumbnailer=${managedPaths.thumbnailerPath}. ` +
     'Launch aborted before starting mpv.';
   log('warn', configuredLogLevel, message);
   throw new Error(message);

launcher/smoke.e2e.test.ts

@@ -165,11 +165,14 @@ if (entry.argv.includes('--ensure-linux-runtime-plugin-assets')) {
   const pluginDir = path.join(dataDir, 'plugin', 'subminer');
   const pluginConfigPath = path.join(dataDir, 'plugin', 'subminer.conf');
   const themePath = path.join(dataDir, 'themes', 'subminer.rasi');
+  const thumbnailerPath = path.join(dataDir, 'thumbnailers', 'subminer-ffmpegthumbnailer.thumbnailer');
   fs.mkdirSync(pluginDir, { recursive: true });
   fs.mkdirSync(path.dirname(themePath), { recursive: true });
+  fs.mkdirSync(path.dirname(thumbnailerPath), { recursive: true });
   fs.writeFileSync(path.join(pluginDir, 'main.lua'), '-- smoke plugin\\n');
   fs.writeFileSync(pluginConfigPath, 'smoke=true\\n');
   fs.writeFileSync(themePath, '/* smoke theme */\\n');
+  fs.writeFileSync(thumbnailerPath, '[Thumbnailer Entry]\\n');
   if (responsePath) {
     fs.mkdirSync(path.dirname(responsePath), { recursive: true });
     fs.writeFileSync(responsePath, JSON.stringify({ ok: true, status: 'installed', path: path.join(pluginDir, 'main.lua') }));
@@ -620,11 +623,22 @@ test(
       );
       assert.match(result.stdout, /pause mpv until overlay and tokenization are ready/i);
       if (process.platform === 'linux') {
-        assert.match(result.stdout, /managed plugin\/theme assets/i);
+        assert.match(result.stdout, /managed plugin\/theme\/thumbnailer assets/i);
         assert.equal(
           fs.existsSync(path.join(smokeCase.xdgDataHome, 'SubMiner', 'themes', 'subminer.rasi')),
           true,
         );
+        assert.equal(
+          fs.existsSync(
+            path.join(
+              smokeCase.xdgDataHome,
+              'SubMiner',
+              'thumbnailers',
+              'subminer-ffmpegthumbnailer.thumbnailer',
+            ),
+          ),
+          true,
+        );
       }
     });
   },