fix: macOS overlay z-order and Yomitan compound token known highlighting

- Release always-on-top when tracked mpv loses foreground on macOS - Skip visible overlay blur restacking on macOS to avoid covering unrelated windows - Prefer Yomitan internal parse tokens over fragmented scanner output for known-word decisions - Add regression tests for both behaviors
2026-05-13 20:12:54 -07:00 · 2026-05-12 02:34:28 -07:00
parent 6bf905140c
commit ca796bfe6a
11 changed files with 534 additions and 13 deletions
@@ -969,6 +969,51 @@ test('macOS keeps active mpv overlay visible and interactive during tracker refr
  assert.deepEqual(osdMessages, []);
 });

+test('macOS tracked overlay releases topmost level when mpv loses foreground', () => {
+  const { window, calls } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => false,
+  };
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    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,
+    isWindowsPlatform: false,
+  } as never);
+
+  assert.ok(calls.includes('update-bounds'));
+  assert.ok(calls.includes('sync-layer'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('always-on-top:false'));
+  assert.ok(calls.includes('show'));
+  assert.ok(calls.includes('sync-shortcuts'));
+  assert.ok(!calls.includes('ensure-level'));
+  assert.ok(!calls.includes('enforce-order'));
+  assert.ok(!calls.includes('focus'));
+  assert.ok(!calls.includes('hide'));
+});
+
 test('macOS preserves an already visible active mpv overlay while tracker is temporarily not ready', () => {
  const { window, calls } = createMainWindowRecorder();
  const osdMessages: string[] = [];
@@ -89,17 +89,22 @@ export function updateVisibleOverlayVisibility(args: {
    return;
  }

-  const showPassiveVisibleOverlay = (): void => {
+  const showPassiveVisibleOverlay = (): boolean => {
    const forceMousePassthrough = args.forceMousePassthrough === true;
    const wasVisible = mainWindow.isVisible();
    const isVisibleOverlayFocused =
      typeof mainWindow.isFocused === 'function' && mainWindow.isFocused();
+    const isTrackedMacOSTargetFocused =
+      !args.isMacOSPlatform || !args.windowTracker
+        ? true
+        : (args.windowTracker.isTargetWindowFocused?.() ?? true);
+    const shouldReleaseMacOSOverlayLevel =
+      args.isMacOSPlatform &&
+      !!args.windowTracker &&
+      !isVisibleOverlayFocused &&
+      !isTrackedMacOSTargetFocused;
    const shouldDefaultToPassthrough =
-      args.isWindowsPlatform ||
-      forceMousePassthrough ||
-      (args.isMacOSPlatform &&
-        !isVisibleOverlayFocused &&
-        !(args.windowTracker?.isTargetWindowFocused?.() ?? true));
+      args.isWindowsPlatform || forceMousePassthrough || shouldReleaseMacOSOverlayLevel;
    const windowsForegroundProcessName =
      args.lastKnownWindowsForegroundProcessName?.trim().toLowerCase() ?? null;
    const windowsOverlayProcessName = args.windowsOverlayProcessName?.trim().toLowerCase() ?? null;
@@ -142,7 +147,7 @@ export function updateVisibleOverlayVisibility(args: {
      // On Windows, z-order is enforced by the OS via the owner window mechanism
      // (SetWindowLongPtr GWLP_HWNDPARENT). The overlay is always above mpv
      // without any manual z-order management.
-    } else if (!forceMousePassthrough) {
+    } else if (!forceMousePassthrough && !shouldReleaseMacOSOverlayLevel) {
      args.ensureOverlayWindowLevel(mainWindow);
    } else {
      mainWindow.setAlwaysOnTop(false);
@@ -191,6 +196,8 @@ export function updateVisibleOverlayVisibility(args: {
    if (!args.isWindowsPlatform && !args.isMacOSPlatform && !forceMousePassthrough) {
      mainWindow.focus();
    }
+
+    return !shouldReleaseMacOSOverlayLevel;
  };

  const maybeShowOverlayLoadingOsd = (): void => {
@@ -234,8 +241,8 @@ export function updateVisibleOverlayVisibility(args: {
      args.updateVisibleOverlayBounds(geometry);
    }
    args.syncPrimaryOverlayWindowLayer('visible');
-    showPassiveVisibleOverlay();
-    if (!args.forceMousePassthrough && !args.isWindowsPlatform) {
+    const shouldEnforceLayerOrder = showPassiveVisibleOverlay();
+    if (shouldEnforceLayerOrder && !args.forceMousePassthrough && !args.isWindowsPlatform) {
      args.enforceOverlayLayerOrder();
    }
    args.syncOverlayShortcuts();
@@ -284,8 +291,8 @@ export function updateVisibleOverlayVisibility(args: {
      args.updateVisibleOverlayBounds(geometry);
    }
    args.syncPrimaryOverlayWindowLayer('visible');
-    showPassiveVisibleOverlay();
-    if (!args.forceMousePassthrough && !args.isWindowsPlatform) {
+    const shouldEnforceLayerOrder = showPassiveVisibleOverlay();
+    if (shouldEnforceLayerOrder && !args.forceMousePassthrough && !args.isWindowsPlatform) {
      args.enforceOverlayLayerOrder();
    }
    args.syncOverlayShortcuts();
@@ -69,7 +69,8 @@ export function handleOverlayWindowBlurred(options: {
  onWindowsVisibleOverlayBlur?: () => void;
  platform?: NodeJS.Platform;
 }): boolean {
-  if ((options.platform ?? process.platform) === 'win32' && options.kind === 'visible') {
+  const platform = options.platform ?? process.platform;
+  if ((platform === 'win32' || platform === 'darwin') && options.kind === 'visible') {
    options.onWindowsVisibleOverlayBlur?.();
    return false;
  }
@@ -146,6 +146,26 @@ test('handleOverlayWindowBlurred notifies Windows visible overlay blur callback
  assert.deepEqual(calls, ['windows-visible-blur']);
 });

+test('handleOverlayWindowBlurred skips macOS visible overlay restacking after focus loss', () => {
+  const calls: string[] = [];
+
+  const handled = handleOverlayWindowBlurred({
+    kind: 'visible',
+    windowVisible: true,
+    isOverlayVisible: () => true,
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    moveWindowTop: () => {
+      calls.push('move-top');
+    },
+    platform: 'darwin',
+  });
+
+  assert.equal(handled, false);
+  assert.deepEqual(calls, []);
+});
+
 test('handleOverlayWindowBlurred preserves active visible/modal window stacking', () => {
  const calls: string[] = [];

@@ -2846,6 +2846,141 @@ test('tokenizeSubtitle checks known words by surface when configured', async ()
  assert.equal(result.tokens?.[0]?.isKnown, true);
 });

+test('tokenizeSubtitle preserves Yomitan compound token when MeCab components are known', async () => {
+  const text = '取り組んでもらいます';
+  const result = await tokenizeSubtitle(
+    text,
+    makeDeps({
+      getYomitanExt: () => ({ id: 'dummy-ext' }) as any,
+      getYomitanParserWindow: () =>
+        ({
+          isDestroyed: () => false,
+          webContents: {
+            executeJavaScript: async (script: string) => {
+              if (script.includes('getTermFrequencies')) {
+                return [];
+              }
+
+              if (script.includes('parseText')) {
+                return [
+                  {
+                    source: 'scanning-parser',
+                    index: 0,
+                    content: [
+                      [
+                        {
+                          text: '取り組んで',
+                          reading: 'とりくんで',
+                          headwords: [[{ term: '取り組む' }]],
+                        },
+                      ],
+                      [
+                        {
+                          text: 'もらいます',
+                          reading: 'もらいます',
+                          headwords: [[{ term: 'もらう' }]],
+                        },
+                      ],
+                    ],
+                  },
+                ];
+              }
+
+              return [
+                {
+                  surface: '取り',
+                  reading: 'とり',
+                  headword: '取る',
+                  startPos: 0,
+                  endPos: 2,
+                },
+                {
+                  surface: '組んで',
+                  reading: 'くんで',
+                  headword: '組む',
+                  startPos: 2,
+                  endPos: 5,
+                },
+                {
+                  surface: 'もらいます',
+                  reading: 'もらいます',
+                  headword: 'もらう',
+                  startPos: 5,
+                  endPos: 10,
+                },
+              ];
+            },
+          },
+        }) as unknown as Electron.BrowserWindow,
+      isKnownWord: (word) => word === '取る' || word === '組む' || word === 'もらう',
+      tokenizeWithMecab: async () => [
+        {
+          headword: '取り組む',
+          surface: '取り組ん',
+          reading: 'トリクン',
+          startPos: 0,
+          endPos: 4,
+          partOfSpeech: PartOfSpeech.verb,
+          pos1: '動詞',
+          pos2: '自立',
+          pos3: '*',
+          isMerged: false,
+          isKnown: false,
+          isNPlusOneTarget: false,
+        },
+        {
+          headword: 'で',
+          surface: 'で',
+          reading: 'デ',
+          startPos: 4,
+          endPos: 5,
+          partOfSpeech: PartOfSpeech.particle,
+          pos1: '助詞',
+          pos2: '接続助詞',
+          pos3: '*',
+          isMerged: false,
+          isKnown: false,
+          isNPlusOneTarget: false,
+        },
+        {
+          headword: 'もらう',
+          surface: 'もらい',
+          reading: 'モライ',
+          startPos: 5,
+          endPos: 8,
+          partOfSpeech: PartOfSpeech.verb,
+          pos1: '動詞',
+          pos2: '非自立',
+          pos3: '*',
+          isMerged: false,
+          isKnown: false,
+          isNPlusOneTarget: false,
+        },
+        {
+          headword: 'ます',
+          surface: 'ます',
+          reading: 'マス',
+          startPos: 8,
+          endPos: 10,
+          partOfSpeech: PartOfSpeech.bound_auxiliary,
+          pos1: '助動詞',
+          pos2: '*',
+          pos3: '*',
+          isMerged: false,
+          isKnown: false,
+          isNPlusOneTarget: false,
+        },
+      ],
+    }),
+  );
+
+  assert.equal(result.text, text);
+  assert.equal(result.tokens?.[0]?.surface, '取り組んで');
+  assert.equal(result.tokens?.[0]?.headword, '取り組む');
+  assert.equal(result.tokens?.[0]?.isKnown, false);
+  assert.equal(result.tokens?.[0]?.pos1, '動詞|助詞');
+});
+
 test('tokenizeSubtitle uses frequency surface match mode when configured', async () => {
  const result = await tokenizeSubtitle(
    '鍛えた',
@@ -533,7 +533,7 @@ test('requestYomitanTermFrequencies caches repeated term+reading lookups', async
  assert.equal(frequencyCalls, 1);
 });

-test('requestYomitanScanTokens uses left-to-right termsFind scanning instead of parseText', async () => {
+test('requestYomitanScanTokens prefers parseText tokenization over termsFind fragments', async () => {
  const scripts: string[] = [];
  const deps = createDeps(async (script) => {
    scripts.push(script);
@@ -549,6 +549,138 @@ test('requestYomitanScanTokens uses left-to-right termsFind scanning instead of
        ],
      };
    }
+    if (script.includes('parseText')) {
+      return [
+        {
+          source: 'scanning-parser',
+          index: 0,
+          content: [
+            [
+              {
+                text: '取り組んで',
+                reading: 'とりくんで',
+                headwords: [[{ term: '取り組む' }]],
+              },
+            ],
+          ],
+        },
+      ];
+    }
+    return [
+      {
+        surface: '取り',
+        reading: 'とり',
+        headword: '取る',
+        startPos: 0,
+        endPos: 2,
+      },
+      {
+        surface: '組んで',
+        reading: 'くんで',
+        headword: '組む',
+        startPos: 2,
+        endPos: 5,
+      },
+    ];
+  });
+
+  const result = await requestYomitanScanTokens('取り組んで', deps, {
+    error: () => undefined,
+  });
+
+  assert.deepEqual(result, [
+    {
+      surface: '取り組んで',
+      reading: 'とりくんで',
+      headword: '取り組む',
+      startPos: 0,
+      endPos: 5,
+    },
+  ]);
+  assert.ok(scripts.some((script) => script.includes('parseText')));
+  assert.ok(scripts.some((script) => script.includes('termsFind')));
+});
+
+test('requestYomitanScanTokens keeps scanner metadata when parse spans agree', async () => {
+  const deps = createDeps(async (script) => {
+    if (script.includes('optionsGetFull')) {
+      return {
+        profileCurrent: 0,
+        profiles: [
+          {
+            options: {
+              scanning: { length: 40 },
+            },
+          },
+        ],
+      };
+    }
+    if (script.includes('parseText')) {
+      return [
+        {
+          source: 'scanning-parser',
+          index: 0,
+          content: [
+            [
+              {
+                text: 'アクア',
+                reading: 'あくあ',
+                headwords: [[{ term: 'アクア' }]],
+              },
+            ],
+          ],
+        },
+      ];
+    }
+    return [
+      {
+        surface: 'アクア',
+        reading: 'あくあ',
+        headword: 'アクア',
+        startPos: 0,
+        endPos: 3,
+        isNameMatch: true,
+        wordClasses: ['n'],
+      },
+    ];
+  });
+
+  const result = await requestYomitanScanTokens('アクア', deps, {
+    error: () => undefined,
+  });
+
+  assert.deepEqual(result, [
+    {
+      surface: 'アクア',
+      reading: 'あくあ',
+      headword: 'アクア',
+      startPos: 0,
+      endPos: 3,
+      isNameMatch: true,
+      wordClasses: ['n'],
+    },
+  ]);
+});
+
+test('requestYomitanScanTokens falls back to left-to-right termsFind scanning', async () => {
+  const scripts: string[] = [];
+  const deps = createDeps(async (script) => {
+    scripts.push(script);
+    if (script.includes('optionsGetFull')) {
+      return {
+        profileCurrent: 0,
+        profiles: [
+          {
+            options: {
+              scanning: { length: 40 },
+            },
+          },
+        ],
+      };
+    }
+    if (script.includes('parseText')) {
+      return [];
+    }
    return [
      {
        surface: 'カズマ',
@@ -573,6 +705,7 @@ test('requestYomitanScanTokens uses left-to-right termsFind scanning instead of
      endPos: 3,
    },
  ]);
+  assert.ok(scripts.some((script) => script.includes('parseText')));
  const scannerScript = scripts.find((script) => script.includes('termsFind'));
  assert.ok(scannerScript, 'expected termsFind scanning request script');
  assert.doesNotMatch(scannerScript ?? '', /parseText/);
@@ -100,6 +100,22 @@ function isScanTokenArray(value: unknown): value is YomitanScanToken[] {
  );
 }

+function hasSameTokenSpans(left: YomitanScanToken[], right: YomitanScanToken[]): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+
+  return left.every((token, index) => {
+    const other = right[index];
+    return (
+      other !== undefined &&
+      token.surface === other.surface &&
+      token.startPos === other.startPos &&
+      token.endPos === other.endPos
+    );
+  });
+}
+
 function makeTermReadingCacheKey(term: string, reading: string | null): string {
  return `${term}\u0000${reading ?? ''}`;
 }
@@ -1252,6 +1268,17 @@ export async function requestYomitanScanTokens(
    return null;
  }

+  const parseResults = await requestYomitanParseResults(text, deps, logger);
+  const selectedParseTokens = selectYomitanParseTokens(parseResults, () => false, 'headword');
+  const parseScanTokens =
+    selectedParseTokens?.map((token) => ({
+      surface: token.surface,
+      reading: token.reading,
+      headword: token.headword,
+      startPos: token.startPos,
+      endPos: token.endPos,
+    })) ?? null;
+
  const metadata = await requestYomitanProfileMetadata(parserWindow, logger);
  const profileIndex = metadata?.profileIndex ?? 0;
  const scanLength = metadata?.scanLength ?? DEFAULT_YOMITAN_SCAN_LENGTH;
@@ -1269,6 +1296,9 @@ export async function requestYomitanScanTokens(
      true,
    );
    if (isScanTokenArray(rawResult)) {
+      if (parseScanTokens && parseScanTokens.length > 0) {
+        return hasSameTokenSpans(parseScanTokens, rawResult) ? rawResult : parseScanTokens;
+      }
      return rawResult;
    }
    if (Array.isArray(rawResult)) {
@@ -1283,8 +1313,14 @@ export async function requestYomitanScanTokens(
        })) ?? null
      );
    }
+    if (parseScanTokens && parseScanTokens.length > 0) {
+      return parseScanTokens;
+    }
    return null;
  } catch (err) {
+    if (parseScanTokens && parseScanTokens.length > 0) {
+      return parseScanTokens;
+    }
    logger.error('Yomitan scanner request failed:', (err as Error).message);
    return null;
  }