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.

src/main/boot/services.test.ts

@@ -0,0 +1,115 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createMainBootServices } from './services';
+
+test('createMainBootServices builds boot-phase service bundle', () => {
+  type MockAppLifecycleApp = {
+    requestSingleInstanceLock: () => boolean;
+    quit: () => void;
+    on: (event: string, listener: (...args: unknown[]) => void) => MockAppLifecycleApp;
+    whenReady: () => Promise<void>;
+  };
+
+  const calls: string[] = [];
+  let setPathValue: string | null = null;
+  const appOnCalls: string[] = [];
+  let secondInstanceHandlerRegistered = false;
+
+  const services = createMainBootServices<
+    { configDir: string },
+    { targetPath: string },
+    { targetPath: string },
+    { targetPath: string },
+    { kind: string },
+    { scope: string; warn: () => void; info: () => void; error: () => void },
+    { registry: boolean },
+    { getModalWindow: () => null },
+    { inputState: boolean; getModalInputExclusive: () => boolean; handleModalInputStateChange: (isActive: boolean) => void },
+    { measurementStore: boolean },
+    { modalRuntime: boolean },
+    { mpvSocketPath: string; texthookerPort: number },
+    MockAppLifecycleApp
+  >({
+    platform: 'linux',
+    argv: ['node', 'main.ts'],
+    appDataDir: undefined,
+    xdgConfigHome: undefined,
+    homeDir: '/home/tester',
+    defaultMpvLogFile: '/tmp/default.log',
+    envMpvLog: ' /tmp/custom.log ',
+    defaultTexthookerPort: 5174,
+    getDefaultSocketPath: () => '/tmp/subminer.sock',
+    resolveConfigDir: () => '/tmp/subminer-config',
+    existsSync: () => false,
+    mkdirSync: (targetPath) => {
+      calls.push(`mkdir:${targetPath}`);
+    },
+    joinPath: (...parts) => parts.join('/'),
+    app: {
+      setPath: (_name, value) => {
+        setPathValue = value;
+      },
+      quit: () => {},
+      on: (event: string) => {
+        appOnCalls.push(event);
+        return {};
+      },
+      whenReady: async () => {},
+    },
+    shouldBypassSingleInstanceLock: () => false,
+    requestSingleInstanceLockEarly: () => true,
+    registerSecondInstanceHandlerEarly: () => {
+      secondInstanceHandlerRegistered = true;
+    },
+    onConfigStartupParseError: () => {
+      throw new Error('unexpected parse failure');
+    },
+    createConfigService: (configDir) => ({ configDir }),
+    createAnilistTokenStore: (targetPath) => ({ targetPath }),
+    createJellyfinTokenStore: (targetPath) => ({ targetPath }),
+    createAnilistUpdateQueue: (targetPath) => ({ targetPath }),
+    createSubtitleWebSocket: () => ({ kind: 'ws' }),
+    createLogger: (scope) =>
+      ({
+        scope,
+        warn: () => {},
+        info: () => {},
+        error: () => {},
+      }) as const,
+    createMainRuntimeRegistry: () => ({ registry: true }),
+    createOverlayManager: () => ({
+      getModalWindow: () => null,
+    }),
+    createOverlayModalInputState: () => ({ inputState: true, getModalInputExclusive: () => false, handleModalInputStateChange: () => {} }),
+    createOverlayContentMeasurementStore: () => ({ measurementStore: true }),
+    getSyncOverlayShortcutsForModal: () => () => {},
+    getSyncOverlayVisibilityForModal: () => () => {},
+    createOverlayModalRuntime: () => ({ modalRuntime: true }),
+    createAppState: (input) => ({ ...input }),
+  });
+
+  assert.equal(services.configDir, '/tmp/subminer-config');
+  assert.equal(services.userDataPath, '/tmp/subminer-config');
+  assert.equal(services.defaultMpvLogPath, '/tmp/custom.log');
+  assert.equal(services.defaultImmersionDbPath, '/tmp/subminer-config/immersion.sqlite');
+  assert.deepEqual(services.configService, { configDir: '/tmp/subminer-config' });
+  assert.deepEqual(services.anilistTokenStore, {
+    targetPath: '/tmp/subminer-config/anilist-token-store.json',
+  });
+  assert.deepEqual(services.jellyfinTokenStore, {
+    targetPath: '/tmp/subminer-config/jellyfin-token-store.json',
+  });
+  assert.deepEqual(services.anilistUpdateQueue, {
+    targetPath: '/tmp/subminer-config/anilist-retry-queue.json',
+  });
+  assert.deepEqual(services.appState, {
+    mpvSocketPath: '/tmp/subminer.sock',
+    texthookerPort: 5174,
+  });
+  assert.equal(services.appLifecycleApp.on('ready', () => {}), services.appLifecycleApp);
+  assert.equal(services.appLifecycleApp.on('second-instance', () => {}), services.appLifecycleApp);
+  assert.deepEqual(appOnCalls, ['ready']);
+  assert.equal(secondInstanceHandlerRegistered, true);
+  assert.deepEqual(calls, ['mkdir:/tmp/subminer-config']);
+  assert.equal(setPathValue, '/tmp/subminer-config');
+});

src/main/boot/services.ts

@@ -0,0 +1,279 @@
+import type { BrowserWindow } from 'electron';
+import { ConfigStartupParseError } from '../../config';
+
+export interface AppLifecycleShape {
+  requestSingleInstanceLock: () => boolean;
+  quit: () => void;
+  on: (event: string, listener: (...args: unknown[]) => void) => unknown;
+  whenReady: () => Promise<void>;
+}
+
+export interface OverlayModalInputStateShape {
+  getModalInputExclusive: () => boolean;
+  handleModalInputStateChange: (isActive: boolean) => void;
+}
+
+export interface MainBootServicesParams<
+  TConfigService,
+  TAnilistTokenStore,
+  TJellyfinTokenStore,
+  TAnilistUpdateQueue,
+  TSubtitleWebSocket,
+  TLogger,
+  TRuntimeRegistry,
+  TOverlayManager,
+  TOverlayModalInputState,
+  TOverlayContentMeasurementStore,
+  TOverlayModalRuntime,
+  TAppState,
+  TAppLifecycleApp,
+> {
+  platform: NodeJS.Platform;
+  argv: string[];
+  appDataDir: string | undefined;
+  xdgConfigHome: string | undefined;
+  homeDir: string;
+  defaultMpvLogFile: string;
+  envMpvLog: string | undefined;
+  defaultTexthookerPort: number;
+  getDefaultSocketPath: () => string;
+  resolveConfigDir: (input: {
+    platform: NodeJS.Platform;
+    appDataDir: string | undefined;
+    xdgConfigHome: string | undefined;
+    homeDir: string;
+    existsSync: (targetPath: string) => boolean;
+  }) => string;
+  existsSync: (targetPath: string) => boolean;
+  mkdirSync: (targetPath: string, options: { recursive: true }) => void;
+  joinPath: (...parts: string[]) => string;
+  app: {
+    setPath: (name: string, value: string) => void;
+    quit: () => void;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type -- Electron App.on has 50+ overloaded signatures
+    on: Function;
+    whenReady: () => Promise<void>;
+  };
+  shouldBypassSingleInstanceLock: () => boolean;
+  requestSingleInstanceLockEarly: () => boolean;
+  registerSecondInstanceHandlerEarly: (
+    listener: (_event: unknown, argv: string[]) => void,
+  ) => void;
+  onConfigStartupParseError: (error: ConfigStartupParseError) => void;
+  createConfigService: (configDir: string) => TConfigService;
+  createAnilistTokenStore: (targetPath: string) => TAnilistTokenStore;
+  createJellyfinTokenStore: (targetPath: string) => TJellyfinTokenStore;
+  createAnilistUpdateQueue: (targetPath: string) => TAnilistUpdateQueue;
+  createSubtitleWebSocket: () => TSubtitleWebSocket;
+  createLogger: (scope: string) => TLogger & {
+    warn: (message: string) => void;
+    info: (message: string) => void;
+    error: (message: string, details?: unknown) => void;
+  };
+  createMainRuntimeRegistry: () => TRuntimeRegistry;
+  createOverlayManager: () => TOverlayManager;
+  createOverlayModalInputState: (params: {
+    getModalWindow: () => BrowserWindow | null;
+    syncOverlayShortcutsForModal: (isActive: boolean) => void;
+    syncOverlayVisibilityForModal: () => void;
+  }) => TOverlayModalInputState;
+  createOverlayContentMeasurementStore: (params: {
+    logger: TLogger;
+  }) => TOverlayContentMeasurementStore;
+  getSyncOverlayShortcutsForModal: () => (isActive: boolean) => void;
+  getSyncOverlayVisibilityForModal: () => () => void;
+  createOverlayModalRuntime: (params: {
+    overlayManager: TOverlayManager;
+    overlayModalInputState: TOverlayModalInputState;
+    onModalStateChange: (isActive: boolean) => void;
+  }) => TOverlayModalRuntime;
+  createAppState: (input: {
+    mpvSocketPath: string;
+    texthookerPort: number;
+  }) => TAppState;
+}
+
+export interface MainBootServicesResult<
+  TConfigService,
+  TAnilistTokenStore,
+  TJellyfinTokenStore,
+  TAnilistUpdateQueue,
+  TSubtitleWebSocket,
+  TLogger,
+  TRuntimeRegistry,
+  TOverlayManager,
+  TOverlayModalInputState,
+  TOverlayContentMeasurementStore,
+  TOverlayModalRuntime,
+  TAppState,
+  TAppLifecycleApp,
+> {
+  configDir: string;
+  userDataPath: string;
+  defaultMpvLogPath: string;
+  defaultImmersionDbPath: string;
+  configService: TConfigService;
+  anilistTokenStore: TAnilistTokenStore;
+  jellyfinTokenStore: TJellyfinTokenStore;
+  anilistUpdateQueue: TAnilistUpdateQueue;
+  subtitleWsService: TSubtitleWebSocket;
+  annotationSubtitleWsService: TSubtitleWebSocket;
+  logger: TLogger;
+  runtimeRegistry: TRuntimeRegistry;
+  overlayManager: TOverlayManager;
+  overlayModalInputState: TOverlayModalInputState;
+  overlayContentMeasurementStore: TOverlayContentMeasurementStore;
+  overlayModalRuntime: TOverlayModalRuntime;
+  appState: TAppState;
+  appLifecycleApp: TAppLifecycleApp;
+}
+
+export function createMainBootServices<
+  TConfigService,
+  TAnilistTokenStore,
+  TJellyfinTokenStore,
+  TAnilistUpdateQueue,
+  TSubtitleWebSocket,
+  TLogger,
+  TRuntimeRegistry,
+  TOverlayManager extends { getModalWindow: () => BrowserWindow | null },
+  TOverlayModalInputState extends OverlayModalInputStateShape,
+  TOverlayContentMeasurementStore,
+  TOverlayModalRuntime,
+  TAppState,
+  TAppLifecycleApp extends AppLifecycleShape,
+>(
+  params: MainBootServicesParams<
+    TConfigService,
+    TAnilistTokenStore,
+    TJellyfinTokenStore,
+    TAnilistUpdateQueue,
+    TSubtitleWebSocket,
+    TLogger,
+    TRuntimeRegistry,
+    TOverlayManager,
+    TOverlayModalInputState,
+    TOverlayContentMeasurementStore,
+    TOverlayModalRuntime,
+    TAppState,
+    TAppLifecycleApp
+  >,
+): MainBootServicesResult<
+  TConfigService,
+  TAnilistTokenStore,
+  TJellyfinTokenStore,
+  TAnilistUpdateQueue,
+  TSubtitleWebSocket,
+  TLogger,
+  TRuntimeRegistry,
+  TOverlayManager,
+  TOverlayModalInputState,
+  TOverlayContentMeasurementStore,
+  TOverlayModalRuntime,
+  TAppState,
+  TAppLifecycleApp
+> {
+  const configDir = params.resolveConfigDir({
+    platform: params.platform,
+    appDataDir: params.appDataDir,
+    xdgConfigHome: params.xdgConfigHome,
+    homeDir: params.homeDir,
+    existsSync: params.existsSync,
+  });
+  const userDataPath = configDir;
+  const defaultMpvLogPath = params.envMpvLog?.trim() || params.defaultMpvLogFile;
+  const defaultImmersionDbPath = params.joinPath(userDataPath, 'immersion.sqlite');
+
+  const configService = (() => {
+    try {
+      return params.createConfigService(configDir);
+    } catch (error) {
+      if (error instanceof ConfigStartupParseError) {
+        params.onConfigStartupParseError(error);
+      }
+      throw error;
+    }
+  })();
+
+  const anilistTokenStore = params.createAnilistTokenStore(
+    params.joinPath(userDataPath, 'anilist-token-store.json'),
+  );
+  const jellyfinTokenStore = params.createJellyfinTokenStore(
+    params.joinPath(userDataPath, 'jellyfin-token-store.json'),
+  );
+  const anilistUpdateQueue = params.createAnilistUpdateQueue(
+    params.joinPath(userDataPath, 'anilist-retry-queue.json'),
+  );
+  const subtitleWsService = params.createSubtitleWebSocket();
+  const annotationSubtitleWsService = params.createSubtitleWebSocket();
+  const logger = params.createLogger('main');
+  const runtimeRegistry = params.createMainRuntimeRegistry();
+  const overlayManager = params.createOverlayManager();
+  const overlayModalInputState = params.createOverlayModalInputState({
+    getModalWindow: () => overlayManager.getModalWindow(),
+    syncOverlayShortcutsForModal: (isActive: boolean) => {
+      params.getSyncOverlayShortcutsForModal()(isActive);
+    },
+    syncOverlayVisibilityForModal: () => {
+      params.getSyncOverlayVisibilityForModal()();
+    },
+  });
+  const overlayContentMeasurementStore = params.createOverlayContentMeasurementStore({
+    logger,
+  });
+  const overlayModalRuntime = params.createOverlayModalRuntime({
+    overlayManager,
+    overlayModalInputState,
+    onModalStateChange: (isActive: boolean) =>
+      overlayModalInputState.handleModalInputStateChange(isActive),
+  });
+  const appState = params.createAppState({
+    mpvSocketPath: params.getDefaultSocketPath(),
+    texthookerPort: params.defaultTexthookerPort,
+  });
+
+  if (!params.existsSync(userDataPath)) {
+    params.mkdirSync(userDataPath, { recursive: true });
+  }
+  params.app.setPath('userData', userDataPath);
+
+  const appLifecycleApp = {
+    requestSingleInstanceLock: () =>
+      params.shouldBypassSingleInstanceLock()
+        ? true
+        : params.requestSingleInstanceLockEarly(),
+    quit: () => params.app.quit(),
+    on: (event: string, listener: (...args: unknown[]) => void) => {
+      if (event === 'second-instance') {
+        params.registerSecondInstanceHandlerEarly(
+          listener as (_event: unknown, argv: string[]) => void,
+        );
+        return appLifecycleApp;
+      }
+      params.app.on(event, listener);
+      return appLifecycleApp;
+    },
+    whenReady: () => params.app.whenReady(),
+  } satisfies AppLifecycleShape as TAppLifecycleApp;
+
+  return {
+    configDir,
+    userDataPath,
+    defaultMpvLogPath,
+    defaultImmersionDbPath,
+    configService,
+    anilistTokenStore,
+    jellyfinTokenStore,
+    anilistUpdateQueue,
+    subtitleWsService,
+    annotationSubtitleWsService,
+    logger,
+    runtimeRegistry,
+    overlayManager,
+    overlayModalInputState,
+    overlayContentMeasurementStore,
+    overlayModalRuntime,
+    appState,
+    appLifecycleApp,
+  };
+}

src/main/character-dictionary-runtime/build.test.ts

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { applyCollapsibleOpenStatesToTermEntries } from './build';
+import type { CharacterDictionaryTermEntry } from './types';
+
+test('applyCollapsibleOpenStatesToTermEntries reapplies configured details open states', () => {
+  const termEntries: CharacterDictionaryTermEntry[] = [
+    [
+      'アルファ',
+      'あるふぁ',
+      '',
+      '',
+      0,
+      [
+        {
+          type: 'structured-content',
+          content: {
+            tag: 'div',
+            content: [
+              {
+                tag: 'details',
+                open: false,
+                content: [
+                  { tag: 'summary', content: 'Description' },
+                  { tag: 'div', content: 'body' },
+                ],
+              },
+              {
+                tag: 'details',
+                open: false,
+                content: [
+                  { tag: 'summary', content: 'Voiced by' },
+                  { tag: 'div', content: 'cv' },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+      0,
+      'name',
+    ],
+  ];
+
+  const [entry] = applyCollapsibleOpenStatesToTermEntries(
+    termEntries,
+    (section) => section === 'description',
+  );
+  assert.ok(entry);
+  const glossaryEntry = entry[5][0] as {
+    content: {
+      content: Array<{ open?: boolean }>;
+    };
+  };
+
+  assert.equal(glossaryEntry.content.content[0]?.open, true);
+  assert.equal(glossaryEntry.content.content[1]?.open, false);
+});

src/main/character-dictionary-runtime/build.ts

@@ -0,0 +1,7 @@
+export {
+  applyCollapsibleOpenStatesToTermEntries,
+  buildSnapshotFromCharacters,
+  buildSnapshotImagePath,
+  buildVaImagePath,
+} from './snapshot';
+export { buildDictionaryTitle, buildDictionaryZip } from './zip';

src/main/character-dictionary-runtime/cache.test.ts

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import test from 'node:test';
+import { getSnapshotPath, readSnapshot, writeSnapshot } from './cache';
+import { CHARACTER_DICTIONARY_FORMAT_VERSION } from './constants';
+import type { CharacterDictionarySnapshot } from './types';
+
+function makeTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-character-dictionary-cache-'));
+}
+
+function createSnapshot(): CharacterDictionarySnapshot {
+  return {
+    formatVersion: CHARACTER_DICTIONARY_FORMAT_VERSION,
+    mediaId: 130298,
+    mediaTitle: 'The Eminence in Shadow',
+    entryCount: 1,
+    updatedAt: 1_700_000_000_000,
+    termEntries: [['アルファ', 'あるふぁ', '', '', 0, ['Alpha'], 0, 'name']],
+    images: [
+      {
+        path: 'img/m130298-c1.png',
+        dataBase64:
+          'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+nmX8AAAAASUVORK5CYII=',
+      },
+    ],
+  };
+}
+
+test('writeSnapshot persists and readSnapshot restores current-format snapshots', () => {
+  const outputDir = makeTempDir();
+  const snapshotPath = getSnapshotPath(outputDir, 130298);
+  const snapshot = createSnapshot();
+
+  writeSnapshot(snapshotPath, snapshot);
+
+  assert.deepEqual(readSnapshot(snapshotPath), snapshot);
+});
+
+test('readSnapshot ignores snapshots written with an older format version', () => {
+  const outputDir = makeTempDir();
+  const snapshotPath = getSnapshotPath(outputDir, 130298);
+  const staleSnapshot = {
+    ...createSnapshot(),
+    formatVersion: CHARACTER_DICTIONARY_FORMAT_VERSION - 1,
+  };
+
+  fs.mkdirSync(path.dirname(snapshotPath), { recursive: true });
+  fs.writeFileSync(snapshotPath, JSON.stringify(staleSnapshot), 'utf8');
+
+  assert.equal(readSnapshot(snapshotPath), null);
+});

src/main/character-dictionary-runtime/cache.ts

@@ -0,0 +1,87 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'node:crypto';
+import { CHARACTER_DICTIONARY_FORMAT_VERSION } from './constants';
+import { ensureDir } from './fs-utils';
+import type {
+  CharacterDictionarySnapshot,
+  CharacterDictionarySnapshotImage,
+  CharacterDictionaryTermEntry,
+} from './types';
+
+function getSnapshotsDir(outputDir: string): string {
+  return path.join(outputDir, 'snapshots');
+}
+
+export function getSnapshotPath(outputDir: string, mediaId: number): string {
+  return path.join(getSnapshotsDir(outputDir), `anilist-${mediaId}.json`);
+}
+
+export function getMergedZipPath(outputDir: string): string {
+  return path.join(outputDir, 'merged.zip');
+}
+
+export function readSnapshot(snapshotPath: string): CharacterDictionarySnapshot | null {
+  try {
+    const raw = fs.readFileSync(snapshotPath, 'utf8');
+    const parsed = JSON.parse(raw) as Partial<CharacterDictionarySnapshot>;
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+    if (
+      parsed.formatVersion !== CHARACTER_DICTIONARY_FORMAT_VERSION ||
+      typeof parsed.mediaId !== 'number' ||
+      typeof parsed.mediaTitle !== 'string' ||
+      typeof parsed.entryCount !== 'number' ||
+      typeof parsed.updatedAt !== 'number' ||
+      !Array.isArray(parsed.termEntries) ||
+      !Array.isArray(parsed.images)
+    ) {
+      return null;
+    }
+    return {
+      formatVersion: parsed.formatVersion,
+      mediaId: parsed.mediaId,
+      mediaTitle: parsed.mediaTitle,
+      entryCount: parsed.entryCount,
+      updatedAt: parsed.updatedAt,
+      termEntries: parsed.termEntries as CharacterDictionaryTermEntry[],
+      images: parsed.images as CharacterDictionarySnapshotImage[],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeSnapshot(snapshotPath: string, snapshot: CharacterDictionarySnapshot): void {
+  ensureDir(path.dirname(snapshotPath));
+  fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf8');
+}
+
+export function buildMergedRevision(
+  mediaIds: number[],
+  snapshots: CharacterDictionarySnapshot[],
+): string {
+  const hash = createHash('sha1');
+  hash.update(
+    JSON.stringify({
+      mediaIds,
+      snapshots: snapshots.map((snapshot) => ({
+        mediaId: snapshot.mediaId,
+        updatedAt: snapshot.updatedAt,
+        entryCount: snapshot.entryCount,
+      })),
+    }),
+  );
+  return hash.digest('hex').slice(0, 12);
+}
+
+export function normalizeMergedMediaIds(mediaIds: number[]): number[] {
+  return [
+    ...new Set(
+      mediaIds
+        .filter((mediaId) => Number.isFinite(mediaId) && mediaId > 0)
+        .map((mediaId) => Math.floor(mediaId)),
+    ),
+  ].sort((left, right) => left - right);
+}

src/main/character-dictionary-runtime/constants.ts

@@ -0,0 +1,23 @@
+export const ANILIST_GRAPHQL_URL = 'https://graphql.anilist.co';
+export const ANILIST_REQUEST_DELAY_MS = 2000;
+export const CHARACTER_IMAGE_DOWNLOAD_DELAY_MS = 250;
+export const CHARACTER_DICTIONARY_FORMAT_VERSION = 15;
+export const CHARACTER_DICTIONARY_MERGED_TITLE = 'SubMiner Character Dictionary';
+
+export const HONORIFIC_SUFFIXES = [
+  { term: 'さん', reading: 'さん' },
+  { term: '様', reading: 'さま' },
+  { term: '先生', reading: 'せんせい' },
+  { term: '先輩', reading: 'せんぱい' },
+  { term: '後輩', reading: 'こうはい' },
+  { term: '氏', reading: 'し' },
+  { term: '君', reading: 'くん' },
+  { term: 'くん', reading: 'くん' },
+  { term: 'ちゃん', reading: 'ちゃん' },
+  { term: 'たん', reading: 'たん' },
+  { term: '坊', reading: 'ぼう' },
+  { term: '殿', reading: 'どの' },
+  { term: '博士', reading: 'はかせ' },
+  { term: '社長', reading: 'しゃちょう' },
+  { term: '部長', reading: 'ぶちょう' },
+] as const;

src/main/character-dictionary-runtime/description.ts

@@ -0,0 +1,82 @@
+import type { CharacterBirthday, CharacterRecord } from './types';
+
+const MONTH_NAMES: ReadonlyArray<[number, string]> = [
+  [1, 'January'],
+  [2, 'February'],
+  [3, 'March'],
+  [4, 'April'],
+  [5, 'May'],
+  [6, 'June'],
+  [7, 'July'],
+  [8, 'August'],
+  [9, 'September'],
+  [10, 'October'],
+  [11, 'November'],
+  [12, 'December'],
+];
+
+const SEX_DISPLAY: ReadonlyArray<[string, string]> = [
+  ['m', '♂ Male'],
+  ['f', '♀ Female'],
+  ['male', '♂ Male'],
+  ['female', '♀ Female'],
+];
+
+function formatBirthday(birthday: CharacterBirthday | null): string {
+  if (!birthday) return '';
+  const [month, day] = birthday;
+  const monthName = MONTH_NAMES.find(([m]) => m === month)?.[1] || 'Unknown';
+  return `${monthName} ${day}`;
+}
+
+export function formatCharacterStats(character: CharacterRecord): string {
+  const parts: string[] = [];
+  const normalizedSex = character.sex.trim().toLowerCase();
+  const sexDisplay = SEX_DISPLAY.find(([key]) => key === normalizedSex)?.[1];
+  if (sexDisplay) parts.push(sexDisplay);
+  if (character.age.trim()) parts.push(`${character.age.trim()} years`);
+  if (character.bloodType.trim()) parts.push(`Blood Type ${character.bloodType.trim()}`);
+  const birthday = formatBirthday(character.birthday);
+  if (birthday) parts.push(`Birthday: ${birthday}`);
+  return parts.join(' • ');
+}
+
+export function parseCharacterDescription(raw: string): {
+  fields: Array<{ key: string; value: string }>;
+  text: string;
+} {
+  const cleaned = raw.replace(/<br\s*\/?>/gi, '\n').replace(/<[^>]+>/g, ' ');
+  const lines = cleaned.split(/\n/);
+  const fields: Array<{ key: string; value: string }> = [];
+  const textLines: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(/^__([^_]+):__\s*(.+)$/);
+    if (match) {
+      const value = match[2]!
+        .replace(/__([^_]+)__/g, '$1')
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/_([^_]+)_/g, '$1')
+        .replace(/\*([^*]+)\*/g, '$1')
+        .trim();
+      fields.push({ key: match[1]!.trim(), value });
+    } else {
+      textLines.push(trimmed);
+    }
+  }
+
+  const text = textLines
+    .join(' ')
+    .replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, '$1')
+    .replace(/https?:\/\/\S+/g, '')
+    .replace(/__([^_]+)__/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/~!/g, '')
+    .replace(/!~/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return { fields, text };
+}

src/main/character-dictionary-runtime/fetch.ts

@@ -0,0 +1,386 @@
+import type { AnilistMediaGuess } from '../../core/services/anilist/anilist-updater';
+import { ANILIST_GRAPHQL_URL } from './constants';
+import type {
+  CharacterDictionaryRole,
+  CharacterRecord,
+  ResolvedAniListMedia,
+  VoiceActorRecord,
+} from './types';
+
+type AniListSearchResponse = {
+  Page?: {
+    media?: Array<{
+      id: number;
+      episodes?: number | null;
+      title?: {
+        romaji?: string | null;
+        english?: string | null;
+        native?: string | null;
+      };
+    }>;
+  };
+};
+
+type AniListCharacterPageResponse = {
+  Media?: {
+    title?: {
+      romaji?: string | null;
+      english?: string | null;
+      native?: string | null;
+    };
+    characters?: {
+      pageInfo?: {
+        hasNextPage?: boolean | null;
+      };
+      edges?: Array<{
+        role?: string | null;
+        voiceActors?: Array<{
+          id: number;
+          name?: {
+            full?: string | null;
+            native?: string | null;
+          } | null;
+          image?: {
+            large?: string | null;
+            medium?: string | null;
+          } | null;
+        }> | null;
+        node?: {
+          id: number;
+          description?: string | null;
+          image?: {
+            large?: string | null;
+            medium?: string | null;
+          } | null;
+          gender?: string | null;
+          age?: string | number | null;
+          dateOfBirth?: {
+            month?: number | null;
+            day?: number | null;
+          } | null;
+          bloodType?: string | null;
+          name?: {
+            first?: string | null;
+            full?: string | null;
+            last?: string | null;
+            native?: string | null;
+            alternative?: Array<string | null> | null;
+          } | null;
+        } | null;
+      } | null>;
+    } | null;
+  } | null;
+};
+
+function normalizeTitle(value: string): string {
+  return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+function pickAniListSearchResult(
+  title: string,
+  episode: number | null,
+  media: Array<{
+    id: number;
+    episodes?: number | null;
+    title?: {
+      romaji?: string | null;
+      english?: string | null;
+      native?: string | null;
+    };
+  }>,
+): ResolvedAniListMedia | null {
+  if (media.length === 0) return null;
+
+  const episodeFiltered =
+    episode && episode > 0
+      ? media.filter((entry) => {
+          const totalEpisodes = entry.episodes;
+          return (
+            typeof totalEpisodes !== 'number' || totalEpisodes <= 0 || episode <= totalEpisodes
+          );
+        })
+      : media;
+  const candidates = episodeFiltered.length > 0 ? episodeFiltered : media;
+  const normalizedTitle = normalizeTitle(title);
+
+  const exact = candidates.find((entry) => {
+    const titles = [entry.title?.english, entry.title?.romaji, entry.title?.native]
+      .filter((value): value is string => typeof value === 'string')
+      .map((value) => normalizeTitle(value));
+    return titles.includes(normalizedTitle);
+  });
+  const selected = exact ?? candidates[0] ?? media[0];
+  if (!selected) return null;
+
+  const selectedTitle =
+    selected.title?.english?.trim() ||
+    selected.title?.romaji?.trim() ||
+    selected.title?.native?.trim() ||
+    title.trim();
+  return {
+    id: selected.id,
+    title: selectedTitle,
+  };
+}
+
+async function fetchAniList<T>(
+  query: string,
+  variables: Record<string, unknown>,
+  beforeRequest?: () => Promise<void>,
+): Promise<T> {
+  if (beforeRequest) {
+    await beforeRequest();
+  }
+  const response = await fetch(ANILIST_GRAPHQL_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      query,
+      variables,
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(`AniList request failed (${response.status})`);
+  }
+  const payload = (await response.json()) as {
+    data?: T;
+    errors?: Array<{ message?: string }>;
+  };
+  const firstError = payload.errors?.find((entry) => entry && typeof entry.message === 'string');
+  if (firstError?.message) {
+    throw new Error(firstError.message);
+  }
+  if (!payload.data) {
+    throw new Error('AniList response missing data');
+  }
+  return payload.data;
+}
+
+function mapRole(input: string | null | undefined): CharacterDictionaryRole {
+  const value = (input || '').trim().toUpperCase();
+  if (value === 'MAIN') return 'main';
+  if (value === 'SUPPORTING') return 'primary';
+  if (value === 'BACKGROUND') return 'side';
+  return 'side';
+}
+
+function inferImageExt(contentType: string | null): string {
+  const normalized = (contentType || '').toLowerCase();
+  if (normalized.includes('png')) return 'png';
+  if (normalized.includes('gif')) return 'gif';
+  if (normalized.includes('webp')) return 'webp';
+  return 'jpg';
+}
+
+export async function resolveAniListMediaIdFromGuess(
+  guess: AnilistMediaGuess,
+  beforeRequest?: () => Promise<void>,
+): Promise<ResolvedAniListMedia> {
+  const data = await fetchAniList<AniListSearchResponse>(
+    `
+      query($search: String!) {
+        Page(perPage: 10) {
+          media(search: $search, type: ANIME, sort: [SEARCH_MATCH, POPULARITY_DESC]) {
+            id
+            episodes
+            title {
+              romaji
+              english
+              native
+            }
+          }
+        }
+      }
+    `,
+    {
+      search: guess.title,
+    },
+    beforeRequest,
+  );
+
+  const media = data.Page?.media ?? [];
+  const resolved = pickAniListSearchResult(guess.title, guess.episode, media);
+  if (!resolved) {
+    throw new Error(`No AniList media match found for "${guess.title}".`);
+  }
+  return resolved;
+}
+
+export async function fetchCharactersForMedia(
+  mediaId: number,
+  beforeRequest?: () => Promise<void>,
+  onPageFetched?: (page: number) => void,
+): Promise<{
+  mediaTitle: string;
+  characters: CharacterRecord[];
+}> {
+  const characters: CharacterRecord[] = [];
+  let page = 1;
+  let mediaTitle = '';
+  for (;;) {
+    const data = await fetchAniList<AniListCharacterPageResponse>(
+      `
+        query($id: Int!, $page: Int!) {
+          Media(id: $id, type: ANIME) {
+            title {
+              romaji
+              english
+              native
+            }
+            characters(page: $page, perPage: 50, sort: [ROLE, RELEVANCE, ID]) {
+              pageInfo {
+                hasNextPage
+              }
+              edges {
+                role
+                voiceActors(language: JAPANESE) {
+                  id
+                  name {
+                    full
+                    native
+                  }
+                  image {
+                    medium
+                  }
+                }
+                node {
+                  id
+                  description(asHtml: false)
+                  gender
+                  age
+                  dateOfBirth {
+                    month
+                    day
+                  }
+                  bloodType
+                  image {
+                    large
+                    medium
+                  }
+                  name {
+                    first
+                    full
+                    last
+                    native
+                    alternative
+                  }
+                }
+              }
+            }
+          }
+        }
+      `,
+      {
+        id: mediaId,
+        page,
+      },
+      beforeRequest,
+    );
+    onPageFetched?.(page);
+
+    const media = data.Media;
+    if (!media) {
+      throw new Error(`AniList media ${mediaId} not found.`);
+    }
+    if (!mediaTitle) {
+      mediaTitle =
+        media.title?.english?.trim() ||
+        media.title?.romaji?.trim() ||
+        media.title?.native?.trim() ||
+        `AniList ${mediaId}`;
+    }
+
+    const edges = media.characters?.edges ?? [];
+    for (const edge of edges) {
+      const node = edge?.node;
+      if (!node || typeof node.id !== 'number') continue;
+      const firstNameHint = node.name?.first?.trim() || '';
+      const fullName = node.name?.full?.trim() || '';
+      const lastNameHint = node.name?.last?.trim() || '';
+      const nativeName = node.name?.native?.trim() || '';
+      const alternativeNames = [
+        ...new Set(
+          (node.name?.alternative ?? [])
+            .filter((value): value is string => typeof value === 'string')
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0),
+        ),
+      ];
+      if (!nativeName) continue;
+      const voiceActors: VoiceActorRecord[] = [];
+      for (const va of edge?.voiceActors ?? []) {
+        if (!va || typeof va.id !== 'number') continue;
+        const vaFull = va.name?.full?.trim() || '';
+        const vaNative = va.name?.native?.trim() || '';
+        if (!vaFull && !vaNative) continue;
+        voiceActors.push({
+          id: va.id,
+          fullName: vaFull,
+          nativeName: vaNative,
+          imageUrl: va.image?.medium || null,
+        });
+      }
+      characters.push({
+        id: node.id,
+        role: mapRole(edge?.role),
+        firstNameHint,
+        fullName,
+        lastNameHint,
+        nativeName,
+        alternativeNames,
+        bloodType: node.bloodType?.trim() || '',
+        birthday:
+          typeof node.dateOfBirth?.month === 'number' && typeof node.dateOfBirth?.day === 'number'
+            ? [node.dateOfBirth.month, node.dateOfBirth.day]
+            : null,
+        description: node.description || '',
+        imageUrl: node.image?.large || node.image?.medium || null,
+        age:
+          typeof node.age === 'string'
+            ? node.age.trim()
+            : typeof node.age === 'number'
+              ? String(node.age)
+              : '',
+        sex: node.gender?.trim() || '',
+        voiceActors,
+      });
+    }
+
+    const hasNextPage = Boolean(media.characters?.pageInfo?.hasNextPage);
+    if (!hasNextPage) {
+      break;
+    }
+    page += 1;
+  }
+
+  return {
+    mediaTitle,
+    characters,
+  };
+}
+
+export async function downloadCharacterImage(
+  imageUrl: string,
+  charId: number,
+): Promise<{
+  filename: string;
+  ext: string;
+  bytes: Buffer;
+} | null> {
+  try {
+    const response = await fetch(imageUrl);
+    if (!response.ok) return null;
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length === 0) return null;
+    const ext = inferImageExt(response.headers.get('content-type'));
+    return {
+      filename: `c${charId}.${ext}`,
+      ext,
+      bytes,
+    };
+  } catch {
+    return null;
+  }
+}

src/main/character-dictionary-runtime/fs-utils.ts

@@ -0,0 +1 @@
+export { ensureDir } from '../../shared/fs-utils';

src/main/character-dictionary-runtime/glossary.ts

@@ -0,0 +1,243 @@
+import type { AnilistCharacterDictionaryCollapsibleSectionKey } from '../../types';
+import { formatCharacterStats, parseCharacterDescription } from './description';
+import type {
+  CharacterDictionaryGlossaryEntry,
+  CharacterDictionaryRole,
+  CharacterRecord,
+  VoiceActorRecord,
+} from './types';
+
+function roleLabel(role: CharacterDictionaryRole): string {
+  if (role === 'main') return 'Protagonist';
+  if (role === 'primary') return 'Main Character';
+  if (role === 'side') return 'Side Character';
+  return 'Minor Role';
+}
+
+function roleBadgeStyle(role: CharacterDictionaryRole): Record<string, string> {
+  const base = {
+    borderRadius: '4px',
+    padding: '0.15em 0.5em',
+    fontSize: '0.8em',
+    fontWeight: 'bold',
+    color: '#fff',
+  };
+  if (role === 'main') return { ...base, backgroundColor: '#4CAF50' };
+  if (role === 'primary') return { ...base, backgroundColor: '#2196F3' };
+  if (role === 'side') return { ...base, backgroundColor: '#FF9800' };
+  return { ...base, backgroundColor: '#9E9E9E' };
+}
+
+function buildCollapsibleSection(
+  title: string,
+  open: boolean,
+  body: Array<string | Record<string, unknown>> | string | Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    tag: 'details',
+    open,
+    style: { marginTop: '0.4em' },
+    content: [
+      {
+        tag: 'summary',
+        style: { fontWeight: 'bold', fontSize: '0.95em', cursor: 'pointer' },
+        content: title,
+      },
+      {
+        tag: 'div',
+        style: { padding: '0.25em 0 0 0.4em', fontSize: '0.9em' },
+        content: body,
+      },
+    ],
+  };
+}
+
+function buildVoicedByContent(
+  voiceActors: VoiceActorRecord[],
+  vaImagePaths: Map<number, string>,
+): Record<string, unknown> {
+  if (voiceActors.length === 1) {
+    const va = voiceActors[0]!;
+    const vaImgPath = vaImagePaths.get(va.id);
+    const vaLabel = va.nativeName
+      ? va.fullName
+        ? `${va.nativeName} (${va.fullName})`
+        : va.nativeName
+      : va.fullName;
+
+    if (vaImgPath) {
+      return {
+        tag: 'table',
+        content: {
+          tag: 'tr',
+          content: [
+            {
+              tag: 'td',
+              style: {
+                verticalAlign: 'top',
+                padding: '0',
+                paddingRight: '0.4em',
+                borderWidth: '0',
+              },
+              content: {
+                tag: 'img',
+                path: vaImgPath,
+                width: 3,
+                height: 3,
+                sizeUnits: 'em',
+                title: vaLabel,
+                alt: vaLabel,
+                collapsed: false,
+                collapsible: false,
+                background: true,
+              },
+            },
+            {
+              tag: 'td',
+              style: { verticalAlign: 'middle', padding: '0', borderWidth: '0' },
+              content: vaLabel,
+            },
+          ],
+        },
+      };
+    }
+
+    return { tag: 'div', content: vaLabel };
+  }
+
+  const items: Array<Record<string, unknown>> = [];
+  for (const va of voiceActors) {
+    const vaLabel = va.nativeName
+      ? va.fullName
+        ? `${va.nativeName} (${va.fullName})`
+        : va.nativeName
+      : va.fullName;
+    items.push({ tag: 'li', content: vaLabel });
+  }
+  return { tag: 'ul', style: { marginTop: '0.15em' }, content: items };
+}
+
+export function createDefinitionGlossary(
+  character: CharacterRecord,
+  mediaTitle: string,
+  imagePath: string | null,
+  vaImagePaths: Map<number, string>,
+  getCollapsibleSectionOpenState: (
+    section: AnilistCharacterDictionaryCollapsibleSectionKey,
+  ) => boolean,
+): CharacterDictionaryGlossaryEntry[] {
+  const displayName = character.nativeName || character.fullName || `Character ${character.id}`;
+  const secondaryName =
+    character.nativeName && character.fullName && character.fullName !== character.nativeName
+      ? character.fullName
+      : null;
+  const { fields, text: descriptionText } = parseCharacterDescription(character.description);
+
+  const content: Array<string | Record<string, unknown>> = [
+    {
+      tag: 'div',
+      style: { fontWeight: 'bold', fontSize: '1.1em', marginBottom: '0.1em' },
+      content: displayName,
+    },
+  ];
+
+  if (secondaryName) {
+    content.push({
+      tag: 'div',
+      style: { fontSize: '0.85em', fontStyle: 'italic', color: '#b0b0b0', marginBottom: '0.2em' },
+      content: secondaryName,
+    });
+  }
+
+  if (imagePath) {
+    content.push({
+      tag: 'div',
+      style: { marginTop: '0.3em', marginBottom: '0.3em' },
+      content: {
+        tag: 'img',
+        path: imagePath,
+        width: 8,
+        height: 11,
+        sizeUnits: 'em',
+        title: displayName,
+        alt: displayName,
+        description: `${displayName} · ${mediaTitle}`,
+        collapsed: false,
+        collapsible: false,
+        background: true,
+      },
+    });
+  }
+
+  content.push({
+    tag: 'div',
+    style: { fontSize: '0.8em', color: '#999', marginBottom: '0.2em' },
+    content: `From: ${mediaTitle}`,
+  });
+
+  content.push({
+    tag: 'div',
+    style: { marginBottom: '0.15em' },
+    content: {
+      tag: 'span',
+      style: roleBadgeStyle(character.role),
+      content: roleLabel(character.role),
+    },
+  });
+
+  const statsLine = formatCharacterStats(character);
+  if (descriptionText) {
+    content.push(
+      buildCollapsibleSection(
+        'Description',
+        getCollapsibleSectionOpenState('description'),
+        descriptionText,
+      ),
+    );
+  }
+
+  const fieldItems: Array<Record<string, unknown>> = [];
+  if (statsLine) {
+    fieldItems.push({
+      tag: 'li',
+      style: { fontWeight: 'bold' },
+      content: statsLine,
+    });
+  }
+  fieldItems.push(
+    ...fields.map((field) => ({
+      tag: 'li',
+      content: `${field.key}: ${field.value}`,
+    })),
+  );
+  if (fieldItems.length > 0) {
+    content.push(
+      buildCollapsibleSection(
+        'Character Information',
+        getCollapsibleSectionOpenState('characterInformation'),
+        {
+          tag: 'ul',
+          style: { marginTop: '0.15em' },
+          content: fieldItems,
+        },
+      ),
+    );
+  }
+
+  if (character.voiceActors.length > 0) {
+    content.push(
+      buildCollapsibleSection(
+        'Voiced by',
+        getCollapsibleSectionOpenState('voicedBy'),
+        buildVoicedByContent(character.voiceActors, vaImagePaths),
+      ),
+    );
+  }
+
+  return [
+    {
+      type: 'structured-content',
+      content: { tag: 'div', content },
+    },
+  ];
+}

src/main/character-dictionary-runtime/name-reading.ts

@@ -0,0 +1,496 @@
+import { HONORIFIC_SUFFIXES } from './constants';
+import type { JapaneseNameParts, NameReadings } from './types';
+
+export function hasKanaOnly(value: string): boolean {
+  return /^[\u3040-\u309f\u30a0-\u30ffー]+$/.test(value);
+}
+
+function katakanaToHiragana(value: string): string {
+  let output = '';
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code >= 0x30a1 && code <= 0x30f6) {
+      output += String.fromCharCode(code - 0x60);
+      continue;
+    }
+    output += char;
+  }
+  return output;
+}
+
+export function buildReading(term: string): string {
+  const compact = term.replace(/\s+/g, '').trim();
+  if (!compact || !hasKanaOnly(compact)) {
+    return '';
+  }
+  return katakanaToHiragana(compact);
+}
+
+export function containsKanji(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if ((code >= 0x4e00 && code <= 0x9fff) || (code >= 0x3400 && code <= 0x4dbf)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function isRomanizedName(value: string): boolean {
+  return /^[A-Za-zĀĪŪĒŌÂÊÎÔÛāīūēōâêîôû'’.\-\s]+$/.test(value);
+}
+
+function normalizeRomanizedName(value: string): string {
+  return value
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/[’']/g, '')
+    .replace(/[.\-]/g, ' ')
+    .replace(/ā|â/g, 'aa')
+    .replace(/ī|î/g, 'ii')
+    .replace(/ū|û/g, 'uu')
+    .replace(/ē|ê/g, 'ei')
+    .replace(/ō|ô/g, 'ou')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+const ROMANIZED_KANA_DIGRAPHS: ReadonlyArray<[string, string]> = [
+  ['kya', 'キャ'],
+  ['kyu', 'キュ'],
+  ['kyo', 'キョ'],
+  ['gya', 'ギャ'],
+  ['gyu', 'ギュ'],
+  ['gyo', 'ギョ'],
+  ['sha', 'シャ'],
+  ['shu', 'シュ'],
+  ['sho', 'ショ'],
+  ['sya', 'シャ'],
+  ['syu', 'シュ'],
+  ['syo', 'ショ'],
+  ['ja', 'ジャ'],
+  ['ju', 'ジュ'],
+  ['jo', 'ジョ'],
+  ['jya', 'ジャ'],
+  ['jyu', 'ジュ'],
+  ['jyo', 'ジョ'],
+  ['cha', 'チャ'],
+  ['chu', 'チュ'],
+  ['cho', 'チョ'],
+  ['tya', 'チャ'],
+  ['tyu', 'チュ'],
+  ['tyo', 'チョ'],
+  ['cya', 'チャ'],
+  ['cyu', 'チュ'],
+  ['cyo', 'チョ'],
+  ['nya', 'ニャ'],
+  ['nyu', 'ニュ'],
+  ['nyo', 'ニョ'],
+  ['hya', 'ヒャ'],
+  ['hyu', 'ヒュ'],
+  ['hyo', 'ヒョ'],
+  ['bya', 'ビャ'],
+  ['byu', 'ビュ'],
+  ['byo', 'ビョ'],
+  ['pya', 'ピャ'],
+  ['pyu', 'ピュ'],
+  ['pyo', 'ピョ'],
+  ['mya', 'ミャ'],
+  ['myu', 'ミュ'],
+  ['myo', 'ミョ'],
+  ['rya', 'リャ'],
+  ['ryu', 'リュ'],
+  ['ryo', 'リョ'],
+  ['fa', 'ファ'],
+  ['fi', 'フィ'],
+  ['fe', 'フェ'],
+  ['fo', 'フォ'],
+  ['fyu', 'フュ'],
+  ['fyo', 'フョ'],
+  ['fya', 'フャ'],
+  ['va', 'ヴァ'],
+  ['vi', 'ヴィ'],
+  ['vu', 'ヴ'],
+  ['ve', 'ヴェ'],
+  ['vo', 'ヴォ'],
+  ['she', 'シェ'],
+  ['che', 'チェ'],
+  ['je', 'ジェ'],
+  ['tsi', 'ツィ'],
+  ['tse', 'ツェ'],
+  ['tsa', 'ツァ'],
+  ['tso', 'ツォ'],
+  ['thi', 'ティ'],
+  ['thu', 'テュ'],
+  ['dhi', 'ディ'],
+  ['dhu', 'デュ'],
+  ['wi', 'ウィ'],
+  ['we', 'ウェ'],
+  ['wo', 'ウォ'],
+];
+
+const ROMANIZED_KANA_MONOGRAPHS: ReadonlyArray<[string, string]> = [
+  ['a', 'ア'],
+  ['i', 'イ'],
+  ['u', 'ウ'],
+  ['e', 'エ'],
+  ['o', 'オ'],
+  ['ka', 'カ'],
+  ['ki', 'キ'],
+  ['ku', 'ク'],
+  ['ke', 'ケ'],
+  ['ko', 'コ'],
+  ['ga', 'ガ'],
+  ['gi', 'ギ'],
+  ['gu', 'グ'],
+  ['ge', 'ゲ'],
+  ['go', 'ゴ'],
+  ['sa', 'サ'],
+  ['shi', 'シ'],
+  ['si', 'シ'],
+  ['su', 'ス'],
+  ['se', 'セ'],
+  ['so', 'ソ'],
+  ['za', 'ザ'],
+  ['ji', 'ジ'],
+  ['zi', 'ジ'],
+  ['zu', 'ズ'],
+  ['ze', 'ゼ'],
+  ['zo', 'ゾ'],
+  ['ta', 'タ'],
+  ['chi', 'チ'],
+  ['ti', 'チ'],
+  ['tsu', 'ツ'],
+  ['tu', 'ツ'],
+  ['te', 'テ'],
+  ['to', 'ト'],
+  ['da', 'ダ'],
+  ['de', 'デ'],
+  ['do', 'ド'],
+  ['na', 'ナ'],
+  ['ni', 'ニ'],
+  ['nu', 'ヌ'],
+  ['ne', 'ネ'],
+  ['no', 'ノ'],
+  ['ha', 'ハ'],
+  ['hi', 'ヒ'],
+  ['fu', 'フ'],
+  ['hu', 'フ'],
+  ['he', 'ヘ'],
+  ['ho', 'ホ'],
+  ['ba', 'バ'],
+  ['bi', 'ビ'],
+  ['bu', 'ブ'],
+  ['be', 'ベ'],
+  ['bo', 'ボ'],
+  ['pa', 'パ'],
+  ['pi', 'ピ'],
+  ['pu', 'プ'],
+  ['pe', 'ペ'],
+  ['po', 'ポ'],
+  ['ma', 'マ'],
+  ['mi', 'ミ'],
+  ['mu', 'ム'],
+  ['me', 'メ'],
+  ['mo', 'モ'],
+  ['ya', 'ヤ'],
+  ['yu', 'ユ'],
+  ['yo', 'ヨ'],
+  ['ra', 'ラ'],
+  ['ri', 'リ'],
+  ['ru', 'ル'],
+  ['re', 'レ'],
+  ['ro', 'ロ'],
+  ['wa', 'ワ'],
+  ['w', 'ウ'],
+  ['wo', 'ヲ'],
+  ['n', 'ン'],
+];
+
+function romanizedTokenToKatakana(token: string): string | null {
+  const normalized = normalizeRomanizedName(token).replace(/\s+/g, '');
+  if (!normalized || !/^[a-z]+$/.test(normalized)) {
+    return null;
+  }
+
+  let output = '';
+  for (let i = 0; i < normalized.length; ) {
+    const current = normalized[i]!;
+    const next = normalized[i + 1] ?? '';
+
+    if (
+      i + 1 < normalized.length &&
+      current === next &&
+      current !== 'n' &&
+      !'aeiou'.includes(current)
+    ) {
+      output += 'ッ';
+      i += 1;
+      continue;
+    }
+
+    if (current === 'n' && next.length > 0 && next !== 'y' && !'aeiou'.includes(next)) {
+      output += 'ン';
+      i += 1;
+      continue;
+    }
+
+    const digraph = ROMANIZED_KANA_DIGRAPHS.find(([romaji]) => normalized.startsWith(romaji, i));
+    if (digraph) {
+      output += digraph[1];
+      i += digraph[0].length;
+      continue;
+    }
+
+    const monograph = ROMANIZED_KANA_MONOGRAPHS.find(([romaji]) =>
+      normalized.startsWith(romaji, i),
+    );
+    if (monograph) {
+      output += monograph[1];
+      i += monograph[0].length;
+      continue;
+    }
+
+    return null;
+  }
+
+  return output.length > 0 ? output : null;
+}
+
+export function buildReadingFromRomanized(value: string): string {
+  const katakana = romanizedTokenToKatakana(value);
+  return katakana ? katakanaToHiragana(katakana) : '';
+}
+
+function buildReadingFromHint(value: string): string {
+  return buildReading(value) || buildReadingFromRomanized(value);
+}
+
+function scoreJapaneseNamePartLength(length: number): number {
+  if (length === 2) return 3;
+  if (length === 1 || length === 3) return 2;
+  if (length === 4) return 1;
+  return 0;
+}
+
+function inferJapaneseNameSplitIndex(
+  nameOriginal: string,
+  firstNameHint: string,
+  lastNameHint: string,
+): number | null {
+  const chars = [...nameOriginal];
+  if (chars.length < 2) return null;
+
+  const familyHintLength = [...buildReadingFromHint(lastNameHint)].length;
+  const givenHintLength = [...buildReadingFromHint(firstNameHint)].length;
+  const totalHintLength = familyHintLength + givenHintLength;
+  const defaultBoundary = Math.round(chars.length / 2);
+  let bestIndex: number | null = null;
+  let bestScore = Number.NEGATIVE_INFINITY;
+
+  for (let index = 1; index < chars.length; index += 1) {
+    const familyLength = index;
+    const givenLength = chars.length - index;
+    let score =
+      scoreJapaneseNamePartLength(familyLength) + scoreJapaneseNamePartLength(givenLength);
+
+    if (chars.length >= 4 && familyLength >= 2 && givenLength >= 2) {
+      score += 1;
+    }
+
+    if (totalHintLength > 0) {
+      const expectedFamilyLength = (chars.length * familyHintLength) / totalHintLength;
+      score -= Math.abs(familyLength - expectedFamilyLength) * 1.5;
+    } else {
+      score -= Math.abs(familyLength - defaultBoundary) * 0.5;
+    }
+
+    if (familyLength === givenLength) {
+      score += 0.25;
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestIndex = index;
+    }
+  }
+
+  return bestIndex;
+}
+
+export function addRomanizedKanaAliases(values: Iterable<string>): string[] {
+  const aliases = new Set<string>();
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (!trimmed || !isRomanizedName(trimmed)) continue;
+    const katakana = romanizedTokenToKatakana(trimmed);
+    if (katakana) {
+      aliases.add(katakana);
+    }
+  }
+  return [...aliases];
+}
+
+export function splitJapaneseName(
+  nameOriginal: string,
+  firstNameHint?: string,
+  lastNameHint?: string,
+): JapaneseNameParts {
+  const trimmed = nameOriginal.trim();
+  if (!trimmed) {
+    return {
+      hasSpace: false,
+      original: '',
+      combined: '',
+      family: null,
+      given: null,
+    };
+  }
+
+  const normalizedSpace = trimmed.replace(/[\s\u3000]+/g, ' ').trim();
+  const spaceParts = normalizedSpace.split(' ').filter((part) => part.length > 0);
+  if (spaceParts.length === 2) {
+    const family = spaceParts[0]!;
+    const given = spaceParts[1]!;
+    return {
+      hasSpace: true,
+      original: normalizedSpace,
+      combined: `${family}${given}`,
+      family,
+      given,
+    };
+  }
+
+  const middleDotParts = trimmed
+    .split(/[・･·•]/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  if (middleDotParts.length === 2) {
+    const family = middleDotParts[0]!;
+    const given = middleDotParts[1]!;
+    return {
+      hasSpace: true,
+      original: trimmed,
+      combined: `${family}${given}`,
+      family,
+      given,
+    };
+  }
+
+  const hintedFirst = firstNameHint?.trim() || '';
+  const hintedLast = lastNameHint?.trim() || '';
+  if (hintedFirst && hintedLast) {
+    const familyGiven = `${hintedLast}${hintedFirst}`;
+    if (trimmed === familyGiven) {
+      return {
+        hasSpace: true,
+        original: trimmed,
+        combined: familyGiven,
+        family: hintedLast,
+        given: hintedFirst,
+      };
+    }
+
+    const givenFamily = `${hintedFirst}${hintedLast}`;
+    if (trimmed === givenFamily) {
+      return {
+        hasSpace: true,
+        original: trimmed,
+        combined: givenFamily,
+        family: hintedFirst,
+        given: hintedLast,
+      };
+    }
+  }
+
+  if (hintedFirst && hintedLast && containsKanji(trimmed)) {
+    const splitIndex = inferJapaneseNameSplitIndex(trimmed, hintedFirst, hintedLast);
+    if (splitIndex != null) {
+      const chars = [...trimmed];
+      const family = chars.slice(0, splitIndex).join('');
+      const given = chars.slice(splitIndex).join('');
+      if (family && given) {
+        return {
+          hasSpace: true,
+          original: trimmed,
+          combined: trimmed,
+          family,
+          given,
+        };
+      }
+    }
+  }
+
+  return {
+    hasSpace: false,
+    original: trimmed,
+    combined: trimmed,
+    family: null,
+    given: null,
+  };
+}
+
+export function generateNameReadings(
+  nameOriginal: string,
+  romanizedName: string,
+  firstNameHint?: string,
+  lastNameHint?: string,
+): NameReadings {
+  const trimmed = nameOriginal.trim();
+  if (!trimmed) {
+    return {
+      hasSpace: false,
+      original: '',
+      full: '',
+      family: '',
+      given: '',
+    };
+  }
+
+  const nameParts = splitJapaneseName(trimmed, firstNameHint, lastNameHint);
+  if (!nameParts.hasSpace || !nameParts.family || !nameParts.given) {
+    const full = containsKanji(trimmed)
+      ? buildReadingFromRomanized(romanizedName)
+      : buildReading(trimmed);
+    return {
+      hasSpace: false,
+      original: trimmed,
+      full,
+      family: full,
+      given: full,
+    };
+  }
+
+  const romanizedParts = romanizedName
+    .trim()
+    .split(/\s+/)
+    .filter((part) => part.length > 0);
+  const familyFromHints = buildReadingFromHint(lastNameHint || '');
+  const givenFromHints = buildReadingFromHint(firstNameHint || '');
+  const familyRomajiFallback = romanizedParts[0] || '';
+  const givenRomajiFallback = romanizedParts.slice(1).join(' ');
+  const family =
+    familyFromHints ||
+    (containsKanji(nameParts.family)
+      ? buildReadingFromRomanized(familyRomajiFallback)
+      : buildReading(nameParts.family));
+  const given =
+    givenFromHints ||
+    (containsKanji(nameParts.given)
+      ? buildReadingFromRomanized(givenRomajiFallback)
+      : buildReading(nameParts.given));
+  const full =
+    `${family}${given}` || buildReading(trimmed) || buildReadingFromRomanized(romanizedName);
+
+  return {
+    hasSpace: true,
+    original: nameParts.original,
+    full,
+    family,
+    given,
+  };
+}
+
+export function buildHonorificAliases(value: string): string[] {
+  return HONORIFIC_SUFFIXES.map((suffix) => `${value}${suffix.term}`);
+}

src/main/character-dictionary-runtime/snapshot.ts

@@ -0,0 +1,144 @@
+import type { AnilistCharacterDictionaryCollapsibleSectionKey } from '../../types';
+import { CHARACTER_DICTIONARY_FORMAT_VERSION } from './constants';
+import { createDefinitionGlossary } from './glossary';
+import { generateNameReadings, splitJapaneseName } from './name-reading';
+import { buildNameTerms, buildReadingForTerm, buildTermEntry } from './term-building';
+import type {
+  CharacterDictionaryGlossaryEntry,
+  CharacterDictionarySnapshot,
+  CharacterDictionarySnapshotImage,
+  CharacterDictionaryTermEntry,
+  CharacterRecord,
+} from './types';
+
+export function buildSnapshotImagePath(mediaId: number, charId: number, ext: string): string {
+  return `img/m${mediaId}-c${charId}.${ext}`;
+}
+
+export function buildVaImagePath(mediaId: number, vaId: number, ext: string): string {
+  return `img/m${mediaId}-va${vaId}.${ext}`;
+}
+
+export function buildSnapshotFromCharacters(
+  mediaId: number,
+  mediaTitle: string,
+  characters: CharacterRecord[],
+  imagesByCharacterId: Map<number, CharacterDictionarySnapshotImage>,
+  imagesByVaId: Map<number, CharacterDictionarySnapshotImage>,
+  updatedAt: number,
+  getCollapsibleSectionOpenState: (
+    section: AnilistCharacterDictionaryCollapsibleSectionKey,
+  ) => boolean,
+): CharacterDictionarySnapshot {
+  const termEntries: CharacterDictionaryTermEntry[] = [];
+
+  for (const character of characters) {
+    const seenTerms = new Set<string>();
+    const imagePath = imagesByCharacterId.get(character.id)?.path ?? null;
+    const vaImagePaths = new Map<number, string>();
+    for (const va of character.voiceActors) {
+      const vaImg = imagesByVaId.get(va.id);
+      if (vaImg) vaImagePaths.set(va.id, vaImg.path);
+    }
+    const glossary = createDefinitionGlossary(
+      character,
+      mediaTitle,
+      imagePath,
+      vaImagePaths,
+      getCollapsibleSectionOpenState,
+    );
+    const candidateTerms = buildNameTerms(character);
+    const nameParts = splitJapaneseName(
+      character.nativeName,
+      character.firstNameHint,
+      character.lastNameHint,
+    );
+    const readings = generateNameReadings(
+      character.nativeName,
+      character.fullName,
+      character.firstNameHint,
+      character.lastNameHint,
+    );
+    for (const term of candidateTerms) {
+      if (seenTerms.has(term)) continue;
+      seenTerms.add(term);
+      const reading = buildReadingForTerm(term, character, readings, nameParts);
+      termEntries.push(buildTermEntry(term, reading, character.role, glossary));
+    }
+  }
+
+  if (termEntries.length === 0) {
+    throw new Error('No dictionary entries generated from AniList character data.');
+  }
+
+  return {
+    formatVersion: CHARACTER_DICTIONARY_FORMAT_VERSION,
+    mediaId,
+    mediaTitle,
+    entryCount: termEntries.length,
+    updatedAt,
+    termEntries,
+    images: [...imagesByCharacterId.values(), ...imagesByVaId.values()],
+  };
+}
+
+function getCollapsibleSectionKeyFromTitle(
+  title: string,
+): AnilistCharacterDictionaryCollapsibleSectionKey | null {
+  if (title === 'Description') return 'description';
+  if (title === 'Character Information') return 'characterInformation';
+  if (title === 'Voiced by') return 'voicedBy';
+  return null;
+}
+
+function applyCollapsibleOpenStatesToStructuredValue(
+  value: unknown,
+  getCollapsibleSectionOpenState: (
+    section: AnilistCharacterDictionaryCollapsibleSectionKey,
+  ) => boolean,
+): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      applyCollapsibleOpenStatesToStructuredValue(item, getCollapsibleSectionOpenState),
+    );
+  }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const record = value as Record<string, unknown>;
+  const next: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(record)) {
+    next[key] = applyCollapsibleOpenStatesToStructuredValue(child, getCollapsibleSectionOpenState);
+  }
+
+  if (record.tag === 'details') {
+    const content = Array.isArray(record.content) ? record.content : [];
+    const summary = content[0];
+    if (summary && typeof summary === 'object' && !Array.isArray(summary)) {
+      const summaryContent = (summary as Record<string, unknown>).content;
+      if (typeof summaryContent === 'string') {
+        const section = getCollapsibleSectionKeyFromTitle(summaryContent);
+        if (section) {
+          next.open = getCollapsibleSectionOpenState(section);
+        }
+      }
+    }
+  }
+
+  return next;
+}
+
+export function applyCollapsibleOpenStatesToTermEntries(
+  termEntries: CharacterDictionaryTermEntry[],
+  getCollapsibleSectionOpenState: (
+    section: AnilistCharacterDictionaryCollapsibleSectionKey,
+  ) => boolean,
+): CharacterDictionaryTermEntry[] {
+  return termEntries.map((entry) => {
+    const glossary = entry[5].map((item) =>
+      applyCollapsibleOpenStatesToStructuredValue(item, getCollapsibleSectionOpenState),
+    ) as CharacterDictionaryGlossaryEntry[];
+    return [...entry.slice(0, 5), glossary, ...entry.slice(6)] as CharacterDictionaryTermEntry;
+  });
+}

src/main/character-dictionary-runtime/term-building.ts

@@ -0,0 +1,170 @@
+import { HONORIFIC_SUFFIXES } from './constants';
+import {
+  addRomanizedKanaAliases,
+  buildReading,
+  buildReadingFromRomanized,
+  hasKanaOnly,
+  isRomanizedName,
+  splitJapaneseName,
+} from './name-reading';
+import type {
+  CharacterDictionaryGlossaryEntry,
+  CharacterDictionaryRole,
+  CharacterDictionaryTermEntry,
+  CharacterRecord,
+  JapaneseNameParts,
+  NameReadings,
+} from './types';
+
+function expandRawNameVariants(rawName: string): string[] {
+  const trimmed = rawName.trim();
+  if (!trimmed) return [];
+
+  const variants = new Set<string>([trimmed]);
+  const outer = trimmed
+    .replace(/[（(][^()（）]+[)）]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (outer && outer !== trimmed) {
+    variants.add(outer);
+  }
+
+  for (const match of trimmed.matchAll(/[（(]([^()（）]+)[)）]/g)) {
+    const inner = match[1]?.trim() || '';
+    if (inner) {
+      variants.add(inner);
+    }
+  }
+
+  return [...variants];
+}
+
+export function buildNameTerms(character: CharacterRecord): string[] {
+  const base = new Set<string>();
+  const rawNames = [character.nativeName, character.fullName, ...character.alternativeNames];
+  for (const rawName of rawNames) {
+    for (const name of expandRawNameVariants(rawName)) {
+      base.add(name);
+
+      const compact = name.replace(/[\s\u3000]+/g, '');
+      if (compact && compact !== name) {
+        base.add(compact);
+      }
+
+      const noMiddleDots = compact.replace(/[・･·•]/g, '');
+      if (noMiddleDots && noMiddleDots !== compact) {
+        base.add(noMiddleDots);
+      }
+
+      const split = name.split(/[\s\u3000]+/).filter((part) => part.trim().length > 0);
+      if (split.length === 2) {
+        base.add(split[0]!);
+        base.add(split[1]!);
+      }
+
+      const splitByMiddleDot = name
+        .split(/[・･·•]/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+      if (splitByMiddleDot.length >= 2) {
+        for (const part of splitByMiddleDot) {
+          base.add(part);
+        }
+      }
+    }
+  }
+
+  const nativeParts = splitJapaneseName(
+    character.nativeName,
+    character.firstNameHint,
+    character.lastNameHint,
+  );
+  if (nativeParts.family) {
+    base.add(nativeParts.family);
+  }
+  if (nativeParts.given) {
+    base.add(nativeParts.given);
+  }
+
+  const withHonorifics = new Set<string>();
+  for (const entry of base) {
+    withHonorifics.add(entry);
+    for (const suffix of HONORIFIC_SUFFIXES) {
+      withHonorifics.add(`${entry}${suffix.term}`);
+    }
+  }
+
+  for (const alias of addRomanizedKanaAliases(withHonorifics)) {
+    withHonorifics.add(alias);
+    for (const suffix of HONORIFIC_SUFFIXES) {
+      withHonorifics.add(`${alias}${suffix.term}`);
+    }
+  }
+
+  return [...withHonorifics].filter((entry) => entry.trim().length > 0);
+}
+
+export function buildReadingForTerm(
+  term: string,
+  character: CharacterRecord,
+  readings: NameReadings,
+  nameParts: JapaneseNameParts,
+): string {
+  for (const suffix of HONORIFIC_SUFFIXES) {
+    if (term.endsWith(suffix.term) && term.length > suffix.term.length) {
+      const baseTerm = term.slice(0, -suffix.term.length);
+      const baseReading = buildReadingForTerm(baseTerm, character, readings, nameParts);
+      return baseReading ? `${baseReading}${suffix.reading}` : '';
+    }
+  }
+
+  const compactNative = character.nativeName.replace(/[\s\u3000]+/g, '');
+  const noMiddleDotsNative = compactNative.replace(/[・･·•]/g, '');
+  if (
+    term === character.nativeName ||
+    term === compactNative ||
+    term === noMiddleDotsNative ||
+    term === nameParts.original ||
+    term === nameParts.combined
+  ) {
+    return readings.full;
+  }
+
+  const familyCompact = nameParts.family?.replace(/[・･·•]/g, '') || '';
+  if (nameParts.family && (term === nameParts.family || term === familyCompact)) {
+    return readings.family;
+  }
+
+  const givenCompact = nameParts.given?.replace(/[・･·•]/g, '') || '';
+  if (nameParts.given && (term === nameParts.given || term === givenCompact)) {
+    return readings.given;
+  }
+
+  const compact = term.replace(/[\s\u3000]+/g, '');
+  if (hasKanaOnly(compact)) {
+    return buildReading(compact);
+  }
+
+  if (isRomanizedName(term)) {
+    return buildReadingFromRomanized(term) || readings.full;
+  }
+
+  return '';
+}
+
+function roleInfo(role: CharacterDictionaryRole): { tag: string; score: number } {
+  if (role === 'main') return { tag: 'main', score: 100 };
+  if (role === 'primary') return { tag: 'primary', score: 75 };
+  if (role === 'side') return { tag: 'side', score: 50 };
+  return { tag: 'appears', score: 25 };
+}
+
+export function buildTermEntry(
+  term: string,
+  reading: string,
+  role: CharacterDictionaryRole,
+  glossary: CharacterDictionaryGlossaryEntry[],
+): CharacterDictionaryTermEntry {
+  const { tag, score } = roleInfo(role);
+  return [term, reading, `name ${tag}`, '', score, glossary, 0, ''];
+}

src/main/character-dictionary-runtime/types.ts

@@ -0,0 +1,136 @@
+import type { AnilistMediaGuess } from '../../core/services/anilist/anilist-updater';
+import type { AnilistCharacterDictionaryCollapsibleSectionKey } from '../../types';
+
+export type CharacterDictionaryRole = 'main' | 'primary' | 'side' | 'appears';
+
+export type CharacterDictionaryGlossaryEntry = string | Record<string, unknown>;
+
+export type CharacterDictionaryTermEntry = [
+  string,
+  string,
+  string,
+  string,
+  number,
+  CharacterDictionaryGlossaryEntry[],
+  number,
+  string,
+];
+
+export type CharacterDictionarySnapshotImage = {
+  path: string;
+  dataBase64: string;
+};
+
+export type CharacterBirthday = [number, number];
+
+export type JapaneseNameParts = {
+  hasSpace: boolean;
+  original: string;
+  combined: string;
+  family: string | null;
+  given: string | null;
+};
+
+export type NameReadings = {
+  hasSpace: boolean;
+  original: string;
+  full: string;
+  family: string;
+  given: string;
+};
+
+export type CharacterDictionarySnapshot = {
+  formatVersion: number;
+  mediaId: number;
+  mediaTitle: string;
+  entryCount: number;
+  updatedAt: number;
+  termEntries: CharacterDictionaryTermEntry[];
+  images: CharacterDictionarySnapshotImage[];
+};
+
+export type VoiceActorRecord = {
+  id: number;
+  fullName: string;
+  nativeName: string;
+  imageUrl: string | null;
+};
+
+export type CharacterRecord = {
+  id: number;
+  role: CharacterDictionaryRole;
+  firstNameHint: string;
+  fullName: string;
+  lastNameHint: string;
+  nativeName: string;
+  alternativeNames: string[];
+  bloodType: string;
+  birthday: CharacterBirthday | null;
+  description: string;
+  imageUrl: string | null;
+  age: string;
+  sex: string;
+  voiceActors: VoiceActorRecord[];
+};
+
+export type CharacterDictionaryBuildResult = {
+  zipPath: string;
+  fromCache: boolean;
+  mediaId: number;
+  mediaTitle: string;
+  entryCount: number;
+  dictionaryTitle?: string;
+  revision?: string;
+};
+
+export type CharacterDictionaryGenerateOptions = {
+  refreshTtlMs?: number;
+};
+
+export type CharacterDictionarySnapshotResult = {
+  mediaId: number;
+  mediaTitle: string;
+  entryCount: number;
+  fromCache: boolean;
+  updatedAt: number;
+};
+
+export type CharacterDictionarySnapshotProgress = {
+  mediaId: number;
+  mediaTitle: string;
+};
+
+export type CharacterDictionarySnapshotProgressCallbacks = {
+  onChecking?: (progress: CharacterDictionarySnapshotProgress) => void;
+  onGenerating?: (progress: CharacterDictionarySnapshotProgress) => void;
+};
+
+export type MergedCharacterDictionaryBuildResult = {
+  zipPath: string;
+  revision: string;
+  dictionaryTitle: string;
+  entryCount: number;
+};
+
+export interface CharacterDictionaryRuntimeDeps {
+  userDataPath: string;
+  getCurrentMediaPath: () => string | null;
+  getCurrentMediaTitle: () => string | null;
+  resolveMediaPathForJimaku: (mediaPath: string | null) => string | null;
+  guessAnilistMediaInfo: (
+    mediaPath: string | null,
+    mediaTitle: string | null,
+  ) => Promise<AnilistMediaGuess | null>;
+  now: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  logInfo?: (message: string) => void;
+  logWarn?: (message: string) => void;
+  getCollapsibleSectionOpenState?: (
+    section: AnilistCharacterDictionaryCollapsibleSectionKey,
+  ) => boolean;
+}
+
+export type ResolvedAniListMedia = {
+  id: number;
+  title: string;
+};

src/main/character-dictionary-runtime/zip.test.ts

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { buildDictionaryZip } from './zip';
+import type { CharacterDictionaryTermEntry } from './types';
+
+function makeTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-character-zip-'));
+}
+
+function cleanupDir(dirPath: string): void {
+  fs.rmSync(dirPath, { recursive: true, force: true });
+}
+
+function readStoredZipEntries(zipPath: string): Map<string, Buffer> {
+  const archive = fs.readFileSync(zipPath);
+  const entries = new Map<string, Buffer>();
+  let cursor = 0;
+
+  while (cursor + 4 <= archive.length) {
+    const signature = archive.readUInt32LE(cursor);
+    if (signature === 0x02014b50 || signature === 0x06054b50) {
+      break;
+    }
+    assert.equal(signature, 0x04034b50, `unexpected local file header at offset ${cursor}`);
+
+    const compressedSize = archive.readUInt32LE(cursor + 18);
+    const fileNameLength = archive.readUInt16LE(cursor + 26);
+    const extraLength = archive.readUInt16LE(cursor + 28);
+    const fileNameStart = cursor + 30;
+    const dataStart = fileNameStart + fileNameLength + extraLength;
+    const fileName = archive.subarray(fileNameStart, fileNameStart + fileNameLength).toString(
+      'utf8',
+    );
+    const data = archive.subarray(dataStart, dataStart + compressedSize);
+    entries.set(fileName, Buffer.from(data));
+    cursor = dataStart + compressedSize;
+  }
+
+  return entries;
+}
+
+test('buildDictionaryZip writes a valid stored zip without fs.writeFileSync', () => {
+  const tempDir = makeTempDir();
+  const outputPath = path.join(tempDir, 'dictionary.zip');
+  const termEntries: CharacterDictionaryTermEntry[] = [
+    ['アルファ', 'あるふぁ', '', '', 0, ['Alpha entry'], 0, 'name'],
+  ];
+  const originalWriteFileSync = fs.writeFileSync;
+  const originalBufferConcat = Buffer.concat;
+
+  try {
+    fs.writeFileSync = ((..._args: unknown[]) => {
+      throw new Error('buildDictionaryZip should not call fs.writeFileSync');
+    }) as typeof fs.writeFileSync;
+
+    Buffer.concat = ((...args: Parameters<typeof Buffer.concat>) => {
+      throw new Error(`buildDictionaryZip should not Buffer.concat the full archive (${args[0].length} chunks)`);
+    }) as typeof Buffer.concat;
+
+    const result = buildDictionaryZip(
+      outputPath,
+      'Dictionary Title',
+      'Dictionary Description',
+      '2026-03-27',
+      termEntries,
+      [{ path: 'images/alpha.bin', dataBase64: Buffer.from([1, 2, 3]).toString('base64') }],
+    );
+
+    assert.equal(result.zipPath, outputPath);
+    assert.equal(result.entryCount, 1);
+
+    const entries = readStoredZipEntries(outputPath);
+    assert.deepEqual([...entries.keys()].sort(), [
+      'images/alpha.bin',
+      'index.json',
+      'tag_bank_1.json',
+      'term_bank_1.json',
+    ]);
+
+    const indexJson = JSON.parse(entries.get('index.json')!.toString('utf8')) as {
+      title: string;
+      description: string;
+      revision: string;
+      format: number;
+    };
+    assert.equal(indexJson.title, 'Dictionary Title');
+    assert.equal(indexJson.description, 'Dictionary Description');
+    assert.equal(indexJson.revision, '2026-03-27');
+    assert.equal(indexJson.format, 3);
+
+    const termBank = JSON.parse(entries.get('term_bank_1.json')!.toString('utf8')) as
+      CharacterDictionaryTermEntry[];
+    assert.equal(termBank.length, 1);
+    assert.equal(termBank[0]?.[0], 'アルファ');
+    assert.deepEqual(entries.get('images/alpha.bin'), Buffer.from([1, 2, 3]));
+  } finally {
+    fs.writeFileSync = originalWriteFileSync;
+    Buffer.concat = originalBufferConcat;
+    cleanupDir(tempDir);
+  }
+});

src/main/character-dictionary-runtime/zip.ts

@@ -0,0 +1,250 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ensureDir } from './fs-utils';
+import type { CharacterDictionarySnapshotImage, CharacterDictionaryTermEntry } from './types';
+
+type ZipEntry = {
+  name: string;
+  crc32: number;
+  size: number;
+  localHeaderOffset: number;
+};
+
+function writeUint32LE(buffer: Buffer, value: number, offset: number): number {
+  const normalized = value >>> 0;
+  buffer[offset] = normalized & 0xff;
+  buffer[offset + 1] = (normalized >>> 8) & 0xff;
+  buffer[offset + 2] = (normalized >>> 16) & 0xff;
+  buffer[offset + 3] = (normalized >>> 24) & 0xff;
+  return offset + 4;
+}
+
+export function buildDictionaryTitle(mediaId: number): string {
+  return `SubMiner Character Dictionary (AniList ${mediaId})`;
+}
+
+function createIndex(
+  dictionaryTitle: string,
+  description: string,
+  revision: string,
+): Record<string, unknown> {
+  return {
+    title: dictionaryTitle,
+    revision,
+    format: 3,
+    author: 'SubMiner',
+    description,
+  };
+}
+
+function createTagBank(): Array<[string, string, number, string, number]> {
+  return [
+    ['name', 'partOfSpeech', 0, 'Character name', 0],
+    ['main', 'name', 0, 'Protagonist', 0],
+    ['primary', 'name', 0, 'Main character', 0],
+    ['side', 'name', 0, 'Side character', 0],
+    ['appears', 'name', 0, 'Minor appearance', 0],
+  ];
+}
+
+const CRC32_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < 256; i += 1) {
+    let crc = i;
+    for (let j = 0; j < 8; j += 1) {
+      crc = (crc & 1) !== 0 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+    }
+    table[i] = crc >>> 0;
+  }
+  return table;
+})();
+
+function crc32(data: Buffer): number {
+  let crc = 0xffffffff;
+  for (const byte of data) {
+    crc = CRC32_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function createLocalFileHeader(fileName: Buffer, fileCrc32: number, fileSize: number): Buffer {
+  const local = Buffer.alloc(30 + fileName.length);
+  let cursor = 0;
+  writeUint32LE(local, 0x04034b50, cursor);
+  cursor += 4;
+  local.writeUInt16LE(20, cursor);
+  cursor += 2;
+  local.writeUInt16LE(0, cursor);
+  cursor += 2;
+  local.writeUInt16LE(0, cursor);
+  cursor += 2;
+  local.writeUInt16LE(0, cursor);
+  cursor += 2;
+  local.writeUInt16LE(0, cursor);
+  cursor += 2;
+  writeUint32LE(local, fileCrc32, cursor);
+  cursor += 4;
+  writeUint32LE(local, fileSize, cursor);
+  cursor += 4;
+  writeUint32LE(local, fileSize, cursor);
+  cursor += 4;
+  local.writeUInt16LE(fileName.length, cursor);
+  cursor += 2;
+  local.writeUInt16LE(0, cursor);
+  cursor += 2;
+  fileName.copy(local, cursor);
+  return local;
+}
+
+function createCentralDirectoryHeader(entry: ZipEntry): Buffer {
+  const fileName = Buffer.from(entry.name, 'utf8');
+  const central = Buffer.alloc(46 + fileName.length);
+  let cursor = 0;
+  writeUint32LE(central, 0x02014b50, cursor);
+  cursor += 4;
+  central.writeUInt16LE(20, cursor);
+  cursor += 2;
+  central.writeUInt16LE(20, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  writeUint32LE(central, entry.crc32, cursor);
+  cursor += 4;
+  writeUint32LE(central, entry.size, cursor);
+  cursor += 4;
+  writeUint32LE(central, entry.size, cursor);
+  cursor += 4;
+  central.writeUInt16LE(fileName.length, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  central.writeUInt16LE(0, cursor);
+  cursor += 2;
+  writeUint32LE(central, 0, cursor);
+  cursor += 4;
+  writeUint32LE(central, entry.localHeaderOffset, cursor);
+  cursor += 4;
+  fileName.copy(central, cursor);
+  return central;
+}
+
+function createEndOfCentralDirectory(entriesLength: number, centralSize: number, centralStart: number): Buffer {
+  const end = Buffer.alloc(22);
+  let cursor = 0;
+  writeUint32LE(end, 0x06054b50, cursor);
+  cursor += 4;
+  end.writeUInt16LE(0, cursor);
+  cursor += 2;
+  end.writeUInt16LE(0, cursor);
+  cursor += 2;
+  end.writeUInt16LE(entriesLength, cursor);
+  cursor += 2;
+  end.writeUInt16LE(entriesLength, cursor);
+  cursor += 2;
+  writeUint32LE(end, centralSize, cursor);
+  cursor += 4;
+  writeUint32LE(end, centralStart, cursor);
+  cursor += 4;
+  end.writeUInt16LE(0, cursor);
+  return end;
+}
+
+function writeBuffer(fd: number, buffer: Buffer): void {
+  let written = 0;
+  while (written < buffer.length) {
+    written += fs.writeSync(fd, buffer, written, buffer.length - written);
+  }
+}
+
+function writeStoredZip(outputPath: string, files: Iterable<{ name: string; data: Buffer }>): void {
+  const entries: ZipEntry[] = [];
+  let offset = 0;
+  const fd = fs.openSync(outputPath, 'w');
+
+  try {
+    for (const file of files) {
+      const fileName = Buffer.from(file.name, 'utf8');
+      const fileSize = file.data.length;
+      const fileCrc32 = crc32(file.data);
+      const localHeader = createLocalFileHeader(fileName, fileCrc32, fileSize);
+      writeBuffer(fd, localHeader);
+      writeBuffer(fd, file.data);
+      entries.push({
+        name: file.name,
+        crc32: fileCrc32,
+        size: fileSize,
+        localHeaderOffset: offset,
+      });
+      offset += localHeader.length + fileSize;
+    }
+
+    const centralStart = offset;
+    for (const entry of entries) {
+      const centralHeader = createCentralDirectoryHeader(entry);
+      writeBuffer(fd, centralHeader);
+      offset += centralHeader.length;
+    }
+
+    const centralSize = offset - centralStart;
+    writeBuffer(fd, createEndOfCentralDirectory(entries.length, centralSize, centralStart));
+  } catch (error) {
+    fs.closeSync(fd);
+    fs.rmSync(outputPath, { force: true });
+    throw error;
+  }
+
+  fs.closeSync(fd);
+}
+
+export function buildDictionaryZip(
+  outputPath: string,
+  dictionaryTitle: string,
+  description: string,
+  revision: string,
+  termEntries: CharacterDictionaryTermEntry[],
+  images: CharacterDictionarySnapshotImage[],
+): { zipPath: string; entryCount: number } {
+  ensureDir(path.dirname(outputPath));
+
+  function* zipFiles(): Iterable<{ name: string; data: Buffer }> {
+    yield {
+      name: 'index.json',
+      data: Buffer.from(
+        JSON.stringify(createIndex(dictionaryTitle, description, revision), null, 2),
+        'utf8',
+      ),
+    };
+    yield {
+      name: 'tag_bank_1.json',
+      data: Buffer.from(JSON.stringify(createTagBank()), 'utf8'),
+    };
+
+    for (const image of images) {
+      yield {
+        name: image.path,
+        data: Buffer.from(image.dataBase64, 'base64'),
+      };
+    }
+
+    const entriesPerBank = 10_000;
+    for (let i = 0; i < termEntries.length; i += entriesPerBank) {
+      yield {
+        name: `term_bank_${Math.floor(i / entriesPerBank) + 1}.json`,
+        data: Buffer.from(JSON.stringify(termEntries.slice(i, i + entriesPerBank)), 'utf8'),
+      };
+    }
+  }
+
+  writeStoredZip(outputPath, zipFiles());
+  return { zipPath: outputPath, entryCount: termEntries.length };
+}

src/main/controller-config-update.test.ts

@@ -1,8 +1,18 @@
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
 import test from 'node:test';
 
 import { applyControllerConfigUpdate } from './controller-config-update.js';
 
+test('SM-012 controller config update path does not use JSON serialize-clone helpers', () => {
+  const source = fs.readFileSync(
+    path.join(process.cwd(), 'src/main/controller-config-update.ts'),
+    'utf-8',
+  );
+  assert.equal(source.includes('JSON.parse(JSON.stringify('), false);
+});
+
 test('applyControllerConfigUpdate replaces binding descriptors instead of deep-merging them', () => {
   const next = applyControllerConfigUpdate(
     {
@@ -52,3 +62,16 @@ test('applyControllerConfigUpdate merges buttonIndices while replacing only upda
   assert.deepEqual(next.bindings?.toggleLookup, { kind: 'button', buttonIndex: 0 });
   assert.deepEqual(next.bindings?.closeLookup, { kind: 'none' });
 });
+
+test('applyControllerConfigUpdate detaches updated binding values from the patch object', () => {
+  const update = {
+    bindings: {
+      toggleLookup: { kind: 'button' as const, buttonIndex: 7 },
+    },
+  };
+
+  const next = applyControllerConfigUpdate(undefined, update);
+  update.bindings.toggleLookup.buttonIndex = 99;
+
+  assert.deepEqual(next.bindings?.toggleLookup, { kind: 'button', buttonIndex: 7 });
+});

src/main/controller-config-update.ts

@@ -28,7 +28,7 @@ export function applyControllerConfigUpdate(
       [keyof RawControllerBindings, RawControllerBindings[keyof RawControllerBindings] | undefined]
     >) {
       if (value === undefined) continue;
-      (nextBindings as Record<string, unknown>)[key] = JSON.parse(JSON.stringify(value));
+      (nextBindings as Record<string, unknown>)[key] = structuredClone(value);
     }
 
     nextController.bindings = nextBindings;

src/main/overlay-runtime.test.ts

@@ -287,10 +287,14 @@ test('sendToActiveOverlayWindow can prefer modal window even when main overlay i
     setModalWindowBounds: () => {},
   });
 
-  const sent = runtime.sendToActiveOverlayWindow('youtube:picker-open', { sessionId: 'yt-1' }, {
-    restoreOnModalClose: 'youtube-track-picker',
-    preferModalWindow: true,
-  });
+  const sent = runtime.sendToActiveOverlayWindow(
+    'youtube:picker-open',
+    { sessionId: 'yt-1' },
+    {
+      restoreOnModalClose: 'youtube-track-picker',
+      preferModalWindow: true,
+    },
+  );
 
   assert.equal(sent, true);
   assert.deepEqual(mainWindow.sent, []);
@@ -309,10 +313,14 @@ test('modal window path makes visible main overlay click-through until modal clo
     setModalWindowBounds: () => {},
   });
 
-  const sent = runtime.sendToActiveOverlayWindow('youtube:picker-open', { sessionId: 'yt-1' }, {
-    restoreOnModalClose: 'youtube-track-picker',
-    preferModalWindow: true,
-  });
+  const sent = runtime.sendToActiveOverlayWindow(
+    'youtube:picker-open',
+    { sessionId: 'yt-1' },
+    {
+      restoreOnModalClose: 'youtube-track-picker',
+      preferModalWindow: true,
+    },
+  );
   runtime.notifyOverlayModalOpened('youtube-track-picker');
 
   assert.equal(sent, true);
@@ -336,10 +344,14 @@ test('modal window path hides visible main overlay until modal closes', () => {
     setModalWindowBounds: () => {},
   });
 
-  runtime.sendToActiveOverlayWindow('youtube:picker-open', { sessionId: 'yt-1' }, {
-    restoreOnModalClose: 'youtube-track-picker',
-    preferModalWindow: true,
-  });
+  runtime.sendToActiveOverlayWindow(
+    'youtube:picker-open',
+    { sessionId: 'yt-1' },
+    {
+      restoreOnModalClose: 'youtube-track-picker',
+      preferModalWindow: true,
+    },
+  );
   runtime.notifyOverlayModalOpened('youtube-track-picker');
 
   assert.equal(mainWindow.getHideCount(), 1);
@@ -516,9 +528,13 @@ test('waitForModalOpen resolves true after modal acknowledgement', async () => {
     setModalWindowBounds: () => {},
   });
 
-  runtime.sendToActiveOverlayWindow('youtube:picker-open', { sessionId: 'yt-1' }, {
-    restoreOnModalClose: 'youtube-track-picker',
-  });
+  runtime.sendToActiveOverlayWindow(
+    'youtube:picker-open',
+    { sessionId: 'yt-1' },
+    {
+      restoreOnModalClose: 'youtube-track-picker',
+    },
+  );
   const pending = runtime.waitForModalOpen('youtube-track-picker', 1000);
   runtime.notifyOverlayModalOpened('youtube-track-picker');
 

src/main/overlay-runtime.ts

@@ -357,10 +357,7 @@ export function createOverlayModalRuntimeService(
     showModalWindow(targetWindow);
   };
 
-  const waitForModalOpen = async (
-    modal: OverlayHostedModal,
-    timeoutMs: number,
-  ): Promise<boolean> =>
+  const waitForModalOpen = async (modal: OverlayHostedModal, timeoutMs: number): Promise<boolean> =>
     await new Promise<boolean>((resolve) => {
       const waiters = modalOpenWaiters.get(modal) ?? [];
       const finish = (opened: boolean): void => {

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');

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', () => {

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

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

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;

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

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']);
 });

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

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

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

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

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';

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']);
 });

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

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 () => {},
       },
     },
   });

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

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

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']);
 });

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']);
 });

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

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

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

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

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

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

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();
       }

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,

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

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

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 = {

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

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

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

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 };

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

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.
+    }
+  };
+}

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];
 }
 

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);

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 () => {

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({

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 () => {

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';
   });
 }

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

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

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;
       }