feat(notifications): add overlay notifications with position config (#110)

src/core/services/anki-jimaku.ts

@@ -10,6 +10,7 @@ import {
   JimakuMediaInfo,
   KikuFieldGroupingChoice,
   KikuFieldGroupingRequestData,
+  OverlayNotificationPayload,
 } from '../../types';
 import { sortJimakuFiles } from '../../jimaku/utils';
 import type { AnkiJimakuIpcDeps } from './anki-jimaku-ipc';
@@ -40,6 +41,7 @@ export interface AnkiJimakuIpcRuntimeOptions {
   setAnkiIntegration: (integration: AnkiIntegration | null) => void;
   getKnownWordCacheStatePath: () => string;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
+  showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -103,6 +105,8 @@ export function registerAnkiJimakuIpcRuntime(
           options.createFieldGroupingCallback(),
           options.getKnownWordCacheStatePath(),
           mergeAiConfig(config.ai, config.ankiConnect?.ai) as AiConfig,
+          undefined,
+          options.showOverlayNotification,
         );
         integration.start();
         options.setAnkiIntegration(integration);

src/core/services/app-ready.test.ts

@@ -2,6 +2,10 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { AppReadyRuntimeDeps, runAppReadyRuntime } from './startup';
 
+function waitTurn(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
 function makeDeps(overrides: Partial<AppReadyRuntimeDeps> = {}) {
   const calls: string[] = [];
   const deps = {
@@ -277,20 +281,80 @@ test('runAppReadyRuntime does not await background warmups', async () => {
   releaseWarmup();
 });
 
-test('runAppReadyRuntime starts background warmups before core runtime services', async () => {
+test('runAppReadyRuntime handles managed background initial args before deferred Yomitan wait', async () => {
   const calls: string[] = [];
-  const { deps } = makeDeps({
-    startBackgroundWarmups: () => {
-      calls.push('startBackgroundWarmups');
-    },
-    loadSubtitlePosition: () => calls.push('loadSubtitlePosition'),
-    createMpvClient: () => calls.push('createMpvClient'),
+  let releaseYomitan!: () => void;
+  const yomitanGate = new Promise<void>((resolve) => {
+    releaseYomitan = resolve;
   });
+  const { deps } = makeDeps({
+    shouldAutoInitializeOverlayRuntimeFromConfig: () => false,
+    shouldHandleInitialArgsBeforeDeferredOverlayWarmup: () => true,
+    loadYomitanExtension: async () => {
+      calls.push('loadYomitanExtension:start');
+      await yomitanGate;
+      calls.push('loadYomitanExtension:done');
+    },
+    handleFirstRunSetup: async () => {
+      calls.push('handleFirstRunSetup');
+    },
+    handleInitialArgs: () => {
+      calls.push('handleInitialArgs');
+    },
+  } as Partial<AppReadyRuntimeDeps>);
+
+  const readyPromise = runAppReadyRuntime(deps);
+  await waitTurn();
+
+  try {
+    assert.ok(calls.includes('handleFirstRunSetup'));
+    assert.ok(calls.includes('handleInitialArgs'));
+    assert.equal(calls.includes('loadYomitanExtension:done'), false);
+  } finally {
+    releaseYomitan();
+    await readyPromise;
+  }
+});
+
+test('runAppReadyRuntime keeps non-managed deferred overlay startup behind Yomitan readiness', async () => {
+  const calls: string[] = [];
+  let releaseYomitan!: () => void;
+  const yomitanGate = new Promise<void>((resolve) => {
+    releaseYomitan = resolve;
+  });
+  const { deps } = makeDeps({
+    shouldAutoInitializeOverlayRuntimeFromConfig: () => false,
+    shouldHandleInitialArgsBeforeDeferredOverlayWarmup: () => false,
+    loadYomitanExtension: async () => {
+      calls.push('loadYomitanExtension:start');
+      await yomitanGate;
+      calls.push('loadYomitanExtension:done');
+    },
+    handleInitialArgs: () => {
+      calls.push('handleInitialArgs');
+    },
+  } as Partial<AppReadyRuntimeDeps>);
+
+  const readyPromise = runAppReadyRuntime(deps);
+  await waitTurn();
+
+  assert.equal(calls.includes('handleInitialArgs'), false);
+
+  releaseYomitan();
+  await readyPromise;
+
+  assert.ok(calls.indexOf('loadYomitanExtension:done') < calls.indexOf('handleInitialArgs'));
+});
+
+test('runAppReadyRuntime starts background warmups after overlay startup', async () => {
+  const { deps, calls } = makeDeps();
 
   await runAppReadyRuntime(deps);
 
-  assert.ok(calls.indexOf('startBackgroundWarmups') < calls.indexOf('loadSubtitlePosition'));
-  assert.ok(calls.indexOf('startBackgroundWarmups') < calls.indexOf('createMpvClient'));
+  assert.ok(calls.indexOf('loadSubtitlePosition') < calls.indexOf('startBackgroundWarmups'));
+  assert.ok(calls.indexOf('createMpvClient') < calls.indexOf('startBackgroundWarmups'));
+  assert.ok(calls.indexOf('initializeOverlayRuntime') < calls.indexOf('startBackgroundWarmups'));
+  assert.ok(calls.indexOf('startBackgroundWarmups') < calls.indexOf('handleInitialArgs'));
 });
 
 test('runAppReadyRuntime exits before service init when critical anki mappings are invalid', async () => {

src/core/services/cli-command.test.ts

@@ -51,6 +51,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     playNextSubtitle: false,
     shiftSubDelayPrevLine: false,
     shiftSubDelayNextLine: false,
+    playbackFeedback: undefined,
     cycleRuntimeOptionId: undefined,
     cycleRuntimeOptionDirection: undefined,
     anilistStatus: false,
@@ -252,6 +253,9 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     showMpvOsd: (text) => {
       osd.push(text);
     },
+    showPlaybackFeedback: (text) => {
+      calls.push(`feedback:${text}`);
+    },
     log: (message) => {
       calls.push(`log:${message}`);
     },
@@ -493,6 +497,15 @@ test('handleCliCommand reports async mine errors to OSD', async () => {
   assert.ok(osd.some((value) => value.includes('Mine sentence failed: boom')));
 });
 
+test('handleCliCommand routes playback feedback through configured feedback surface', () => {
+  const { deps, calls, osd } = createDeps();
+
+  handleCliCommand(makeArgs({ playbackFeedback: 'You can skip by pressing TAB' }), 'initial', deps);
+
+  assert.deepEqual(calls, ['initializeOverlayRuntime', 'feedback:You can skip by pressing TAB']);
+  assert.deepEqual(osd, []);
+});
+
 test('handleCliCommand applies socket path and connects on start', () => {
   const { deps, calls } = createDeps();
 

src/core/services/cli-command.ts

@@ -106,6 +106,7 @@ export interface CliCommandServiceDeps {
   hasMainWindow: () => boolean;
   getMultiCopyTimeoutMs: () => number;
   showMpvOsd: (text: string) => void;
+  showPlaybackFeedback?: (text: string) => void;
   log: (message: string) => void;
   logDebug: (message: string) => void;
   warn: (message: string) => void;
@@ -128,6 +129,7 @@ interface MpvCliRuntime {
   setSocketPath: (socketPath: string) => void;
   getClient: () => MpvClientLike | null;
   showOsd: (text: string) => void;
+  showPlaybackFeedback?: (text: string) => void;
 }
 
 interface TexthookerCliRuntime {
@@ -295,6 +297,7 @@ export function createCliCommandDepsRuntime(
     hasMainWindow: options.app.hasMainWindow,
     getMultiCopyTimeoutMs: options.getMultiCopyTimeoutMs,
     showMpvOsd: options.mpv.showOsd,
+    showPlaybackFeedback: options.mpv.showPlaybackFeedback,
     log: options.log,
     logDebug: options.logDebug,
     warn: options.warn,
@@ -546,6 +549,9 @@ export function handleCliCommand(
       'shiftSubDelayNextLine',
       'Shift subtitle delay failed',
     );
+  } else if (args.playbackFeedback) {
+    const showFeedback = deps.showPlaybackFeedback ?? deps.showMpvOsd;
+    showFeedback(args.playbackFeedback);
   } else if (args.cycleRuntimeOptionId !== undefined) {
     dispatchCliSessionAction(
       {

src/core/services/ipc-command.test.ts

@@ -6,6 +6,7 @@ function createOptions(overrides: Partial<Parameters<typeof handleMpvCommandFrom
   const calls: string[] = [];
   const sentCommands: (string | number)[][] = [];
   const osd: string[] = [];
+  const playbackFeedback: string[] = [];
   const options: Parameters<typeof handleMpvCommandFromIpc>[1] = {
     specialCommands: {
       SUBSYNC_TRIGGER: '__subsync-trigger',
@@ -38,6 +39,9 @@ function createOptions(overrides: Partial<Parameters<typeof handleMpvCommandFrom
     showMpvOsd: (text) => {
       osd.push(text);
     },
+    showPlaybackFeedback: (text) => {
+      playbackFeedback.push(text);
+    },
     mpvReplaySubtitle: () => {
       calls.push('replay');
     },
@@ -55,7 +59,7 @@ function createOptions(overrides: Partial<Parameters<typeof handleMpvCommandFrom
     hasRuntimeOptionsManager: () => true,
     ...overrides,
   };
-  return { options, calls, sentCommands, osd };
+  return { options, calls, sentCommands, osd, playbackFeedback };
 }
 
 test('handleMpvCommandFromIpc forwards regular mpv commands', () => {
@@ -65,41 +69,53 @@ test('handleMpvCommandFromIpc forwards regular mpv commands', () => {
   assert.deepEqual(osd, []);
 });
 
-test('handleMpvCommandFromIpc emits osd for subtitle position keybinding proxies', async () => {
-  const { options, sentCommands, osd } = createOptions();
+test('handleMpvCommandFromIpc routes show-text through playback feedback', () => {
+  const { options, sentCommands, osd, playbackFeedback } = createOptions();
+  handleMpvCommandFromIpc(['show-text', 'Primary subtitle: hover', '1500'], options);
+  assert.deepEqual(sentCommands, []);
+  assert.deepEqual(osd, []);
+  assert.deepEqual(playbackFeedback, ['Primary subtitle: hover']);
+});
+
+test('handleMpvCommandFromIpc emits feedback for subtitle position keybinding proxies', async () => {
+  const { options, sentCommands, osd, playbackFeedback } = createOptions();
   handleMpvCommandFromIpc(['add', 'sub-pos', 1], options);
   await new Promise((resolve) => setImmediate(resolve));
   assert.deepEqual(sentCommands, [['add', 'sub-pos', 1]]);
-  assert.deepEqual(osd, ['Subtitle position: ${sub-pos}']);
+  assert.deepEqual(osd, []);
+  assert.deepEqual(playbackFeedback, ['Subtitle position: ${sub-pos}']);
 });
 
-test('handleMpvCommandFromIpc emits resolved osd for primary subtitle track keybinding proxies', async () => {
-  const { options, sentCommands, osd } = createOptions({
+test('handleMpvCommandFromIpc emits resolved feedback for primary subtitle track keybinding proxies', async () => {
+  const { options, sentCommands, osd, playbackFeedback } = createOptions({
     resolveProxyCommandOsd: async () => 'Subtitle track: Internal #3 - Japanese (active)',
   });
   handleMpvCommandFromIpc(['cycle', 'sid'], options);
   await new Promise((resolve) => setImmediate(resolve));
   assert.deepEqual(sentCommands, [['cycle', 'sid']]);
-  assert.deepEqual(osd, ['Subtitle track: Internal #3 - Japanese (active)']);
+  assert.deepEqual(osd, []);
+  assert.deepEqual(playbackFeedback, ['Subtitle track: Internal #3 - Japanese (active)']);
 });
 
-test('handleMpvCommandFromIpc emits resolved osd for secondary subtitle track keybinding proxies', async () => {
-  const { options, sentCommands, osd } = createOptions({
+test('handleMpvCommandFromIpc emits resolved feedback for secondary subtitle track keybinding proxies', async () => {
+  const { options, sentCommands, osd, playbackFeedback } = createOptions({
     resolveProxyCommandOsd: async () =>
       'Secondary subtitle track: External #8 - English Commentary',
   });
   handleMpvCommandFromIpc(['set_property', 'secondary-sid', 'auto'], options);
   await new Promise((resolve) => setImmediate(resolve));
   assert.deepEqual(sentCommands, [['set_property', 'secondary-sid', 'auto']]);
-  assert.deepEqual(osd, ['Secondary subtitle track: External #8 - English Commentary']);
+  assert.deepEqual(osd, []);
+  assert.deepEqual(playbackFeedback, ['Secondary subtitle track: External #8 - English Commentary']);
 });
 
-test('handleMpvCommandFromIpc emits osd for subtitle delay keybinding proxies', async () => {
-  const { options, sentCommands, osd } = createOptions();
+test('handleMpvCommandFromIpc emits feedback for subtitle delay keybinding proxies', async () => {
+  const { options, sentCommands, osd, playbackFeedback } = createOptions();
   handleMpvCommandFromIpc(['add', 'sub-delay', 0.1], options);
   await new Promise((resolve) => setImmediate(resolve));
   assert.deepEqual(sentCommands, [['add', 'sub-delay', 0.1]]);
-  assert.deepEqual(osd, ['Subtitle delay: ${sub-delay}']);
+  assert.deepEqual(osd, []);
+  assert.deepEqual(playbackFeedback, ['Subtitle delay: ${sub-delay}']);
 });
 
 test('handleMpvCommandFromIpc dispatches special subtitle-delay shift command', () => {

src/core/services/ipc-command.ts

@@ -25,6 +25,7 @@ export interface HandleMpvCommandFromIpcOptions {
   openPlaylistBrowser: () => void | Promise<void>;
   runtimeOptionsCycle: (id: RuntimeOptionId, direction: 1 | -1) => RuntimeOptionApplyResult;
   showMpvOsd: (text: string) => void;
+  showPlaybackFeedback?: (text: string) => void;
   mpvReplaySubtitle: () => void;
   mpvPlayNextSubtitle: () => void;
   shiftSubDelayToAdjacentSubtitle: (direction: 'next' | 'previous') => Promise<void>;
@@ -68,13 +69,14 @@ function showResolvedProxyCommandOsd(
 ): void {
   const template = resolveProxyCommandOsdTemplate(command);
   if (!template) return;
+  const showFeedback = options.showPlaybackFeedback ?? options.showMpvOsd;
 
   const emit = async () => {
     try {
       const resolved = await options.resolveProxyCommandOsd?.(command);
-      options.showMpvOsd(resolved || template);
+      showFeedback(resolved || template);
     } catch {
-      options.showMpvOsd(template);
+      showFeedback(template);
     }
   };
 
@@ -142,6 +144,15 @@ export function handleMpvCommandFromIpc(
     return;
   }
 
+  if (first === 'show-text') {
+    const message = (typeof command[1] === 'string' ? command[1] : String(command[1] ?? '')).trim();
+    if (message) {
+      const showFeedback = options.showPlaybackFeedback ?? options.showMpvOsd;
+      showFeedback(message);
+    }
+    return;
+  }
+
   if (options.isMpvConnected()) {
     if (first === options.specialCommands.REPLAY_SUBTITLE) {
       options.mpvReplaySubtitle();

src/core/services/ipc.test.ts

@@ -137,6 +137,7 @@ function createRegisterIpcDeps(overrides: Partial<IpcServiceDeps> = {}): IpcServ
     dispatchSessionAction: async () => {},
     getStatsToggleKey: () => 'Backquote',
     getMarkWatchedKey: () => 'KeyW',
+    getOverlayNotificationPosition: () => 'top-right',
     getControllerConfig: () => createControllerConfigFixture(),
     saveControllerConfig: async () => {},
     saveControllerPreference: async () => {},
@@ -242,6 +243,7 @@ test('createIpcDepsRuntime wires AniList handlers', async () => {
     dispatchSessionAction: async () => {},
     getStatsToggleKey: () => 'Backquote',
     getMarkWatchedKey: () => 'KeyW',
+    getOverlayNotificationPosition: () => 'top-right',
     getControllerConfig: () => createControllerConfigFixture(),
     saveControllerConfig: () => {},
     saveControllerPreference: () => {},
@@ -552,6 +554,7 @@ test('registerIpcHandlers rejects malformed runtime-option payloads', async () =
       dispatchSessionAction: async () => {},
       getStatsToggleKey: () => 'Backquote',
       getMarkWatchedKey: () => 'KeyW',
+      getOverlayNotificationPosition: () => 'top-right',
       getControllerConfig: () => createControllerConfigFixture(),
       saveControllerConfig: () => {},
       saveControllerPreference: () => {},
@@ -977,6 +980,7 @@ test('registerIpcHandlers ignores malformed fire-and-forget payloads', () => {
       dispatchSessionAction: async () => {},
       getStatsToggleKey: () => 'Backquote',
       getMarkWatchedKey: () => 'KeyW',
+      getOverlayNotificationPosition: () => 'top-right',
       getControllerConfig: () => createControllerConfigFixture(),
       saveControllerConfig: () => {},
       saveControllerPreference: (update) => {
@@ -1058,6 +1062,7 @@ test('registerIpcHandlers awaits saveControllerPreference through request-respon
       dispatchSessionAction: async () => {},
       getStatsToggleKey: () => 'Backquote',
       getMarkWatchedKey: () => 'KeyW',
+      getOverlayNotificationPosition: () => 'top-right',
       getControllerConfig: () => createControllerConfigFixture(),
       saveControllerConfig: async () => {},
       saveControllerPreference: async (update) => {
@@ -1262,6 +1267,44 @@ test('registerIpcHandlers validates dispatchSessionAction payloads', async () =>
   ]);
 });
 
+test('registerIpcHandlers forwards valid overlay notification actions', () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const actions: Array<{ notificationId: string; actionId: string; noteId?: number }> = [];
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      handleOverlayNotificationAction: ((
+        notificationId: string,
+        actionId: string,
+        noteId?: number,
+      ) => {
+        actions.push({ notificationId, actionId, noteId });
+      }) as IpcServiceDeps['handleOverlayNotificationAction'],
+    } as Partial<IpcServiceDeps>),
+    registrar,
+  );
+
+  const actionHandler = handlers.on.get(IPC_CHANNELS.command.overlayNotificationAction);
+  assert.ok(actionHandler);
+
+  actionHandler({}, null);
+  actionHandler({}, { notificationId: '', actionId: 'install-update' });
+  actionHandler({}, { notificationId: 'subminer-update-available', actionId: 42 });
+  actionHandler(
+    {},
+    { notificationId: 'anki-update-progress', actionId: 'open-anki-card', noteId: -1 },
+  );
+  actionHandler({}, { notificationId: 'subminer-update-available', actionId: 'install-update' });
+  actionHandler(
+    {},
+    { notificationId: 'anki-update-progress', actionId: 'open-anki-card', noteId: 42 },
+  );
+
+  assert.deepEqual(actions, [
+    { notificationId: 'subminer-update-available', actionId: 'install-update', noteId: undefined },
+    { notificationId: 'anki-update-progress', actionId: 'open-anki-card', noteId: 42 },
+  ]);
+});
+
 test('registerIpcHandlers rejects malformed controller preference payloads', async () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   registerIpcHandlers(
@@ -1289,6 +1332,7 @@ test('registerIpcHandlers rejects malformed controller preference payloads', asy
       dispatchSessionAction: async () => {},
       getStatsToggleKey: () => 'Backquote',
       getMarkWatchedKey: () => 'KeyW',
+      getOverlayNotificationPosition: () => 'top-right',
       getControllerConfig: () => createControllerConfigFixture(),
       saveControllerConfig: async () => {},
       saveControllerPreference: async () => {},

src/core/services/ipc.ts

@@ -53,6 +53,11 @@ export interface IpcServiceDeps {
     interactive: boolean,
     senderWindow: ElectronBrowserWindow | null,
   ) => void;
+  handleOverlayNotificationAction?: (
+    notificationId: string,
+    actionId: string,
+    noteId?: number,
+  ) => void | Promise<void>;
   openYomitanSettings: () => void;
   quitApp: () => void;
   toggleDevTools: () => void;
@@ -80,6 +85,7 @@ export interface IpcServiceDeps {
   dispatchSessionAction?: (request: SessionActionDispatchRequest) => void | Promise<void>;
   getStatsToggleKey: () => string;
   getMarkWatchedKey: () => string;
+  getOverlayNotificationPosition: () => string;
   getControllerConfig: () => ResolvedControllerConfig;
   saveControllerConfig: (update: ControllerConfigUpdate) => void | Promise<void>;
   saveControllerPreference: (update: ControllerPreferenceUpdate) => void | Promise<void>;
@@ -223,6 +229,25 @@ function parseSubtitleMiningContext(payload: unknown): SubtitleMiningContext | n
   return parsed;
 }
 
+function parseOverlayNotificationActionPayload(
+  payload: unknown,
+): { notificationId: string; actionId: string; noteId?: number } | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const record = payload as Record<string, unknown>;
+  const notificationId = record.notificationId;
+  const actionId = record.actionId;
+  const noteId = record.noteId;
+  if (typeof notificationId !== 'string' || notificationId.trim().length === 0) return null;
+  if (typeof actionId !== 'string' || actionId.trim().length === 0) return null;
+  if (
+    noteId !== undefined &&
+    (typeof noteId !== 'number' || !Number.isInteger(noteId) || noteId <= 0)
+  ) {
+    return null;
+  }
+  return { notificationId, actionId, ...(typeof noteId === 'number' ? { noteId } : {}) };
+}
+
 export interface IpcDepsRuntimeOptions {
   getMainWindow: () => WindowLike | null;
   getVisibleOverlayVisibility: () => boolean;
@@ -242,6 +267,11 @@ export interface IpcDepsRuntimeOptions {
     interactive: boolean,
     senderWindow: ElectronBrowserWindow | null,
   ) => void;
+  handleOverlayNotificationAction?: (
+    notificationId: string,
+    actionId: string,
+    noteId?: number,
+  ) => void | Promise<void>;
   openYomitanSettings: () => void;
   quitApp: () => void;
   toggleVisibleOverlay: () => void;
@@ -262,6 +292,7 @@ export interface IpcDepsRuntimeOptions {
   dispatchSessionAction?: (request: SessionActionDispatchRequest) => void | Promise<void>;
   getStatsToggleKey: () => string;
   getMarkWatchedKey: () => string;
+  getOverlayNotificationPosition: () => string;
   getControllerConfig: () => ResolvedControllerConfig;
   saveControllerConfig: (update: ControllerConfigUpdate) => void | Promise<void>;
   saveControllerPreference: (update: ControllerPreferenceUpdate) => void | Promise<void>;
@@ -312,6 +343,7 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
     onOverlayModalOpened: options.onOverlayModalOpened,
     onOverlayMouseInteractionChanged: options.onOverlayMouseInteractionChanged,
     onOverlayInteractiveHint: options.onOverlayInteractiveHint,
+    handleOverlayNotificationAction: options.handleOverlayNotificationAction,
     openYomitanSettings: options.openYomitanSettings,
     recordSubtitleMiningContext: options.recordSubtitleMiningContext,
     quitApp: options.quitApp,
@@ -349,6 +381,7 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
     dispatchSessionAction: options.dispatchSessionAction ?? (async () => {}),
     getStatsToggleKey: options.getStatsToggleKey,
     getMarkWatchedKey: options.getMarkWatchedKey,
+    getOverlayNotificationPosition: options.getOverlayNotificationPosition,
     getControllerConfig: options.getControllerConfig,
     saveControllerConfig: options.saveControllerConfig,
     saveControllerPreference: options.saveControllerPreference,
@@ -473,6 +506,22 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
       electron.BrowserWindow?.fromWebContents((event as IpcMainEvent).sender) ?? null;
     deps.onOverlayModalOpened(parsedModal, senderWindow);
   });
+  ipc.on(IPC_CHANNELS.command.overlayNotificationAction, (_event: unknown, payload: unknown) => {
+    const parsedPayload = parseOverlayNotificationActionPayload(payload);
+    if (!parsedPayload) return;
+    void Promise.resolve(
+      deps.handleOverlayNotificationAction?.(
+        parsedPayload.notificationId,
+        parsedPayload.actionId,
+        parsedPayload.noteId,
+      ),
+    ).catch((error) => {
+      console.warn(
+        'Failed to handle overlay notification action:',
+        error instanceof Error ? error.message : String(error),
+      );
+    });
+  });
 
   ipc.handle(
     IPC_CHANNELS.request.youtubePickerResolve,
@@ -641,6 +690,10 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
     return deps.getMarkWatchedKey();
   });
 
+  ipc.handle(IPC_CHANNELS.request.getOverlayNotificationPosition, () => {
+    return deps.getOverlayNotificationPosition();
+  });
+
   ipc.handle(IPC_CHANNELS.request.getControllerConfig, () => {
     return deps.getControllerConfig();
   });

src/core/services/overlay-runtime-init.ts

@@ -6,6 +6,7 @@ import {
   AnkiConnectConfig,
   KikuFieldGroupingChoice,
   KikuFieldGroupingRequestData,
+  OverlayNotificationPayload,
   WindowGeometry,
 } from '../../types';
 
@@ -19,6 +20,7 @@ type CreateAnkiIntegrationArgs = {
   subtitleTimingTracker: unknown;
   mpvClient: { send?: (payload: { command: string[] }) => void };
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
+  showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -61,6 +63,8 @@ function createDefaultAnkiIntegration(args: CreateAnkiIntegrationArgs): AnkiInte
     args.createFieldGroupingCallback(),
     args.knownWordCacheStatePath,
     args.aiConfig,
+    undefined,
+    args.showOverlayNotification,
   );
 }
 
@@ -123,6 +127,7 @@ export function initializeOverlayRuntime(
     getAnkiIntegration?: () => unknown | null;
     setAnkiIntegration: (integration: unknown | null) => void;
     showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
+    showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
     createFieldGroupingCallback: () => (
       data: KikuFieldGroupingRequestData,
     ) => Promise<KikuFieldGroupingChoice>;
@@ -156,6 +161,7 @@ export function initializeOverlayAnkiIntegration(options: {
   getAnkiIntegration?: () => unknown | null;
   setAnkiIntegration: (integration: unknown | null) => void;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
+  showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -191,6 +197,7 @@ export function initializeOverlayAnkiIntegration(options: {
     subtitleTimingTracker,
     mpvClient,
     showDesktopNotification: options.showDesktopNotification,
+    showOverlayNotification: options.showOverlayNotification,
     createFieldGroupingCallback: options.createFieldGroupingCallback,
     knownWordCacheStatePath: options.getKnownWordCacheStatePath(),
   });

src/core/services/overlay-shortcut-handler.test.ts

@@ -32,6 +32,7 @@ function makeShortcuts(overrides: Partial<ConfiguredShortcuts> = {}): Configured
     openControllerSelect: null,
     openControllerDebug: null,
     toggleSubtitleSidebar: null,
+    toggleNotificationHistory: null,
     ...overrides,
   };
 }

src/core/services/overlay-shortcut.test.ts

@@ -27,6 +27,7 @@ function createShortcuts(overrides: Partial<ConfiguredShortcuts> = {}): Configur
     openControllerSelect: null,
     openControllerDebug: null,
     toggleSubtitleSidebar: null,
+    toggleNotificationHistory: null,
     ...overrides,
   };
 }

src/core/services/overlay-visibility.test.ts

@@ -154,7 +154,127 @@ test('macOS keeps visible overlay hidden while tracker is not ready and emits on
   assert.ok(!calls.includes('show'));
 });
 
-test('tracked non-macOS overlay stays hidden while tracker is not ready', () => {
+test('macOS dismisses overlay loading OSD when tracker recovers', () => {
+  const { window, calls } = createMainWindowRecorder();
+  let trackerWarning = false;
+  const osdMessages: string[] = [];
+  const dismissedOsds: string[] = [];
+  let tracking = false;
+  let geometry: WindowTrackerStub['getGeometry'] extends () => infer T ? T : never = null;
+  const tracker: WindowTrackerStub = {
+    isTracking: () => tracking,
+    getGeometry: () => geometry,
+    isTargetWindowFocused: () => tracking,
+  };
+
+  const run = () =>
+    updateVisibleOverlayVisibility({
+      visibleOverlayVisible: true,
+      mainWindow: window as never,
+      windowTracker: tracker as never,
+      trackerNotReadyWarningShown: trackerWarning,
+      setTrackerNotReadyWarningShown: (shown: boolean) => {
+        trackerWarning = shown;
+      },
+      updateVisibleOverlayBounds: () => {
+        calls.push('update-bounds');
+      },
+      ensureOverlayWindowLevel: () => {
+        calls.push('ensure-level');
+      },
+      syncPrimaryOverlayWindowLayer: () => {
+        calls.push('sync-layer');
+      },
+      enforceOverlayLayerOrder: () => {
+        calls.push('enforce-order');
+      },
+      syncOverlayShortcuts: () => {
+        calls.push('sync-shortcuts');
+      },
+      isMacOSPlatform: true,
+      showOverlayLoadingOsd: (message: string) => {
+        osdMessages.push(message);
+      },
+      dismissOverlayLoadingOsd: () => {
+        dismissedOsds.push('dismiss');
+      },
+    } as never);
+
+  run();
+  tracking = true;
+  geometry = { x: 0, y: 0, width: 1280, height: 720 };
+  run();
+
+  assert.deepEqual(osdMessages, ['Overlay loading...']);
+  assert.deepEqual(dismissedOsds, ['dismiss']);
+  assert.equal(trackerWarning, false);
+  assert.ok(calls.includes('show-inactive'));
+});
+
+test('tracked non-native overlay shows loading OSD until renderer content is visible', () => {
+  const { window, calls, setContentReady } = createMainWindowRecorder();
+  let loadingShown = false;
+  const osdMessages: string[] = [];
+  const dismissedOsds: string[] = [];
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => true,
+  };
+
+  const run = () =>
+    updateVisibleOverlayVisibility({
+      visibleOverlayVisible: true,
+      mainWindow: window as never,
+      windowTracker: tracker as never,
+      trackerNotReadyWarningShown: loadingShown,
+      setTrackerNotReadyWarningShown: (shown: boolean) => {
+        loadingShown = shown;
+      },
+      updateVisibleOverlayBounds: () => {
+        calls.push('update-bounds');
+      },
+      ensureOverlayWindowLevel: () => {
+        calls.push('ensure-level');
+      },
+      syncPrimaryOverlayWindowLayer: () => {
+        calls.push('sync-layer');
+      },
+      enforceOverlayLayerOrder: () => {
+        calls.push('enforce-order');
+      },
+      syncOverlayShortcuts: () => {
+        calls.push('sync-shortcuts');
+      },
+      isMacOSPlatform: false,
+      isWindowsPlatform: false,
+      showOverlayLoadingOsd: (message: string) => {
+        osdMessages.push(message);
+      },
+      dismissOverlayLoadingOsd: () => {
+        dismissedOsds.push('dismiss');
+      },
+    } as never);
+
+  setContentReady(false);
+  run();
+  run();
+
+  assert.equal(loadingShown, true);
+  assert.deepEqual(osdMessages, ['Overlay loading...']);
+  assert.deepEqual(dismissedOsds, []);
+  assert.ok(!calls.includes('show'));
+  assert.ok(!calls.includes('show-inactive'));
+
+  setContentReady(true);
+  run();
+
+  assert.equal(loadingShown, false);
+  assert.deepEqual(dismissedOsds, ['dismiss']);
+  assert.ok(calls.includes('show-inactive'));
+});
+
+test('tracked non-macOS overlay stays hidden and emits loading OSD while tracker is not ready', () => {
   const { window, calls } = createMainWindowRecorder();
   let trackerWarning = false;
   const tracker: WindowTrackerStub = {
@@ -197,7 +317,7 @@ test('tracked non-macOS overlay stays hidden while tracker is not ready', () =>
   assert.ok(!calls.includes('update-bounds'));
   assert.ok(!calls.includes('show'));
   assert.ok(!calls.includes('focus'));
-  assert.ok(!calls.includes('osd'));
+  assert.ok(calls.includes('osd'));
 });
 
 test('non-native passive overlay stays click-through after subsequent visibility updates', () => {

src/core/services/overlay-visibility.ts

@@ -88,6 +88,7 @@ export function updateVisibleOverlayVisibility(args: {
   isMacOSPlatform?: boolean;
   isWindowsPlatform?: boolean;
   showOverlayLoadingOsd?: (message: string) => void;
+  dismissOverlayLoadingOsd?: () => void;
   shouldShowOverlayLoadingOsd?: () => boolean;
   markOverlayLoadingOsdShown?: () => void;
   resetOverlayLoadingOsdSuppression?: () => void;
@@ -310,8 +311,18 @@ export function updateVisibleOverlayVisibility(args: {
     !args.isWindowsPlatform &&
     (!args.forceMousePassthrough || args.isMacOSPlatform === true);
 
+  const isWaitingForOverlayContentReady = (): boolean => {
+    const hasWebContents =
+      typeof (mainWindow as unknown as { webContents?: unknown }).webContents === 'object';
+    return (
+      !mainWindow.isVisible() &&
+      hasWebContents &&
+      !isOverlayWindowContentReady(mainWindow as unknown as import('electron').BrowserWindow)
+    );
+  };
+
   const maybeShowOverlayLoadingOsd = (): void => {
-    if (!args.isMacOSPlatform || !args.showOverlayLoadingOsd) {
+    if (!args.showOverlayLoadingOsd) {
       return;
     }
     if (args.shouldShowOverlayLoadingOsd && !args.shouldShowOverlayLoadingOsd()) {
@@ -320,6 +331,9 @@ export function updateVisibleOverlayVisibility(args: {
     args.showOverlayLoadingOsd('Overlay loading...');
     args.markOverlayLoadingOsdShown?.();
   };
+  const maybeDismissOverlayLoadingOsd = (): void => {
+    args.dismissOverlayLoadingOsd?.();
+  };
 
   const refreshNonNativeOverlayBoundsAfterFirstShow = (geometry: WindowGeometry | null): void => {
     if (
@@ -350,6 +364,7 @@ export function updateVisibleOverlayVisibility(args: {
   if (!args.visibleOverlayVisible) {
     args.setTrackerNotReadyWarningShown(false);
     args.resetOverlayLoadingOsdSuppression?.();
+    maybeDismissOverlayLoadingOsd();
     if (args.isWindowsPlatform) {
       clearPendingWindowsOverlayReveal(mainWindow);
       setOverlayWindowOpacity(mainWindow, 0);
@@ -371,7 +386,15 @@ export function updateVisibleOverlayVisibility(args: {
       args.syncOverlayShortcuts();
       return;
     }
-    args.setTrackerNotReadyWarningShown(false);
+    if (isWaitingForOverlayContentReady()) {
+      if (!args.trackerNotReadyWarningShown) {
+        args.setTrackerNotReadyWarningShown(true);
+        maybeShowOverlayLoadingOsd();
+      }
+    } else {
+      args.setTrackerNotReadyWarningShown(false);
+      maybeDismissOverlayLoadingOsd();
+    }
     const geometry = args.windowTracker.getGeometry();
     if (geometry) {
       args.updateVisibleOverlayBounds(geometry);
@@ -432,6 +455,7 @@ export function updateVisibleOverlayVisibility(args: {
     (mainWindow.isVisible() || hasRetainedTrackedGeometry)
   ) {
     args.setTrackerNotReadyWarningShown(false);
+    maybeDismissOverlayLoadingOsd();
     const geometry = args.windowTracker.getGeometry();
     if (geometry) {
       args.updateVisibleOverlayBounds(geometry);

src/core/services/overlay-window.ts

@@ -116,6 +116,7 @@ export function createOverlayWindow(
     linuxX11FullscreenOverlay?: boolean;
     onVisibleWindowBlurred?: () => void;
     onVisibleWindowFocused?: () => void;
+    onWindowDidFinishLoad?: () => void;
     onWindowContentReady?: () => void;
     onWindowClosed: (kind: OverlayWindowKind, window: BrowserWindow) => void;
     yomitanSession?: Session | null;
@@ -139,6 +140,7 @@ export function createOverlayWindow(
   window.webContents.on('did-finish-load', () => {
     window.setTitle(OVERLAY_WINDOW_TITLES[kind]);
     options.onRuntimeOptionsChanged();
+    options.onWindowDidFinishLoad?.();
   });
 
   window.webContents.on('page-title-updated', (event) => {

src/core/services/session-actions.test.ts

@@ -25,6 +25,7 @@ function createDeps(overrides: Partial<SessionActionExecutorDeps> = {}) {
     mineSentenceCount: (count) => calls.push(`mine:${count}`),
     toggleSecondarySub: () => calls.push('secondary'),
     toggleSubtitleSidebar: () => calls.push('sidebar'),
+    toggleNotificationHistory: () => calls.push('notification-history'),
     markLastCardAsAudioCard: async () => {
       calls.push('audio');
     },

src/core/services/session-actions.ts

@@ -14,6 +14,7 @@ export interface SessionActionExecutorDeps {
   mineSentenceCount: (count: number) => void;
   toggleSecondarySub: () => void;
   toggleSubtitleSidebar: () => void;
+  toggleNotificationHistory: () => void;
   markLastCardAsAudioCard: () => Promise<void>;
   markActiveVideoWatched: () => Promise<boolean>;
   openRuntimeOptionsPalette: () => void;
@@ -79,6 +80,9 @@ export async function dispatchSessionAction(
     case 'toggleSubtitleSidebar':
       deps.toggleSubtitleSidebar();
       return;
+    case 'toggleNotificationHistory':
+      deps.toggleNotificationHistory();
+      return;
     case 'markAudioCard':
       await deps.markLastCardAsAudioCard();
       return;

src/core/services/session-bindings.test.ts

@@ -26,6 +26,7 @@ function createShortcuts(overrides: Partial<ConfiguredShortcuts> = {}): Configur
     openControllerSelect: null,
     openControllerDebug: null,
     toggleSubtitleSidebar: null,
+    toggleNotificationHistory: null,
     ...overrides,
   };
 }
@@ -195,7 +196,10 @@ test('compileSessionBindings keeps mouse buttons scoped to keybindings', () => {
     platform: 'win32',
   });
 
-  assert.deepEqual(result.bindings.map((binding) => binding.sourcePath), ['keybindings[0].key']);
+  assert.deepEqual(
+    result.bindings.map((binding) => binding.sourcePath),
+    ['keybindings[0].key'],
+  );
   assert.deepEqual(
     result.warnings.map((warning) => `${warning.kind}:${warning.path}`),
     ['unsupported:shortcuts.openJimaku'],

src/core/services/session-bindings.ts

@@ -59,6 +59,7 @@ const SESSION_SHORTCUT_ACTIONS: Array<{
   { key: 'openControllerSelect', actionId: 'openControllerSelect' },
   { key: 'openControllerDebug', actionId: 'openControllerDebug' },
   { key: 'toggleSubtitleSidebar', actionId: 'toggleSubtitleSidebar' },
+  { key: 'toggleNotificationHistory', actionId: 'toggleNotificationHistory' },
 ];
 
 function normalizeModifiers(modifiers: SessionKeyModifier[]): SessionKeyModifier[] {

src/core/services/startup.test.ts

@@ -269,7 +269,7 @@ test('runAppReadyRuntime loads Yomitan before headless overlay fallback initiali
   ]);
 });
 
-test('runAppReadyRuntime loads Yomitan before auto-initializing overlay runtime', async () => {
+test('runAppReadyRuntime auto-initializes overlay runtime before warmups and Yomitan', async () => {
   const calls: string[] = [];
 
   await runAppReadyRuntime({
@@ -354,9 +354,10 @@ test('runAppReadyRuntime loads Yomitan before auto-initializing overlay runtime'
     shouldSkipHeavyStartup: () => false,
   });
 
-  assert.ok(calls.indexOf('load-yomitan') !== -1);
   assert.ok(calls.indexOf('init-overlay') !== -1);
-  assert.ok(calls.indexOf('load-yomitan') < calls.indexOf('init-overlay'));
+  assert.ok(calls.indexOf('warmups') !== -1);
+  assert.ok(calls.indexOf('init-overlay') < calls.indexOf('warmups'));
+  assert.equal(calls.includes('load-yomitan'), false);
 });
 
 test('runAppReadyRuntime reuses guarded Yomitan loader after scheduling startup warmups', async () => {

src/core/services/startup.ts

@@ -158,6 +158,7 @@ export interface AppReadyRuntimeDeps {
   shouldRunHeadlessInitialCommand?: () => boolean;
   shouldUseMinimalStartup?: () => boolean;
   shouldSkipHeavyStartup?: () => boolean;
+  shouldHandleInitialArgsBeforeDeferredOverlayWarmup?: () => boolean;
 }
 
 const REQUIRED_ANKI_FIELD_MAPPING_KEYS = [
@@ -229,6 +230,31 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
   const startupStartedAtMs = now();
   const ensureYomitanExtensionReady =
     deps.ensureYomitanExtensionLoaded ?? deps.loadYomitanExtension;
+  let firstRunSetupHandled = false;
+  let initialArgsHandled = false;
+  let backgroundWarmupsHandled = false;
+  const handleFirstRunSetupOnce = async (): Promise<void> => {
+    if (firstRunSetupHandled) {
+      return;
+    }
+    firstRunSetupHandled = true;
+    await deps.handleFirstRunSetup();
+  };
+  const handleInitialArgsOnce = (): void => {
+    if (initialArgsHandled) {
+      return;
+    }
+    initialArgsHandled = true;
+    deps.handleInitialArgs();
+  };
+  const startBackgroundWarmupsOnce = (): void => {
+    if (backgroundWarmupsHandled) {
+      return;
+    }
+    backgroundWarmupsHandled = true;
+    deps.startBackgroundWarmups();
+  };
+
   deps.ensureDefaultConfigBootstrap();
   if (deps.shouldRunHeadlessInitialCommand?.()) {
     deps.reloadConfig();
@@ -247,7 +273,7 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
 
   if (deps.shouldUseMinimalStartup?.()) {
     deps.reloadConfig();
-    deps.handleInitialArgs();
+    handleInitialArgsOnce();
     return;
   }
 
@@ -256,8 +282,8 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
   if (deps.shouldSkipHeavyStartup?.()) {
     await ensureYomitanExtensionReady();
     deps.reloadConfig();
-    await deps.handleFirstRunSetup();
-    deps.handleInitialArgs();
+    await handleFirstRunSetupOnce();
+    handleInitialArgsOnce();
     deps.logDebug?.(`App-ready critical path finished in ${now() - startupStartedAtMs}ms.`);
     return;
   }
@@ -279,8 +305,6 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
   for (const warning of deps.getConfigWarnings()) {
     deps.logConfigWarning(warning);
   }
-  deps.startBackgroundWarmups();
-
   deps.loadSubtitlePosition();
   deps.resolveKeybindings();
   deps.createMpvClient();
@@ -326,16 +350,24 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
 
   if (deps.texthookerOnlyMode) {
     deps.log('Texthooker-only mode enabled; skipping overlay window.');
+    startBackgroundWarmupsOnce();
   } else if (deps.shouldAutoInitializeOverlayRuntimeFromConfig()) {
-    await ensureYomitanExtensionReady();
     deps.setVisibleOverlayVisible(true);
     deps.initializeOverlayRuntime();
+    startBackgroundWarmupsOnce();
   } else {
     deps.log('Overlay runtime deferred: waiting for explicit overlay command.');
-    await ensureYomitanExtensionReady();
+    if (deps.shouldHandleInitialArgsBeforeDeferredOverlayWarmup?.()) {
+      await handleFirstRunSetupOnce();
+      handleInitialArgsOnce();
+      startBackgroundWarmupsOnce();
+    } else {
+      startBackgroundWarmupsOnce();
+      await ensureYomitanExtensionReady();
+    }
   }
 
-  await deps.handleFirstRunSetup();
-  deps.handleInitialArgs();
+  await handleFirstRunSetupOnce();
+  handleInitialArgsOnce();
   deps.logDebug?.(`App-ready critical path finished in ${now() - startupStartedAtMs}ms.`);
 }