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

backlog/tasks/task-349 - Fix-macOS-overlay-window-ordering-behind-foreground-apps.md

@@ -0,0 +1,74 @@
+---
+id: TASK-349
+title: Fix macOS overlay window ordering behind foreground apps
+status: Done
+assignee: []
+created_date: '2026-05-12 08:50'
+updated_date: '2026-05-12 08:58'
+labels:
+  - bug
+  - macos
+  - overlay
+dependencies: []
+references:
+  - src/core/services/overlay-visibility.ts
+  - src/window-trackers
+  - TASK-344
+modified_files:
+  - src/core/services/overlay-visibility.ts
+  - src/core/services/overlay-visibility.test.ts
+  - src/core/services/overlay-window-input.ts
+  - src/core/services/overlay-window.test.ts
+  - changes/349-macos-overlay-z-order.md
+priority: high
+ordinal: 183500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+macOS overlay should stay visually above mpv, but remain grouped with mpv in normal desktop stacking. When another app/window is brought in front of mpv, that window must also appear in front of the overlay, matching Windows behavior. This follows the earlier active-mpv fix that stopped the overlay from hiding while mpv remained foremost.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 When mpv is the foreground playback window on macOS, the overlay remains visible above mpv.
+- [x] #2 When another application or window is brought in front of mpv on macOS, that foreground window appears above both mpv and the overlay.
+- [x] #3 Restoring mpv to the foreground restores the overlay above mpv without requiring a restart.
+- [x] #4 Regression coverage documents the macOS stacking relationship and does not regress the prior active-mpv overlay preservation behavior.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add focused regression coverage for macOS mpv focus loss: the overlay must release its topmost level, remain visible/click-through, and stop enforcing layer order while mpv is behind another window.
+2. Add focused blur-handler coverage so the macOS visible overlay does not restack itself when it loses focus.
+3. Update overlay visibility and blur handling to use tracker focus as the macOS stacking boundary: focused mpv raises overlay; unfocused mpv releases topmost and skips restack.
+4. Run focused overlay tests, formatting, typecheck, changelog lint, env/build/smoke checks; document any blocked broad gate separately.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented macOS stacking boundary using tracker focus. When tracked mpv is unfocused and the overlay itself is not focused, the visible overlay now releases Electron always-on-top, remains visible/click-through, and skips layer-order enforcement. Visible overlay blur restacking is also skipped on macOS, matching the Windows no-restack path for focus loss. `test:fast` remains blocked by existing cross-file pollution: `keyboard.test.ts` leaves `window.electronAPI` undefined for a later `subsync.test.ts`, causing Bun nested `node:test` errors in subsequent files.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Summary:
+- Updated macOS overlay visibility so tracked mpv focus controls stacking: focused mpv keeps the overlay raised; unfocused mpv releases topmost while keeping the overlay visible and click-through.
+- Stopped macOS visible overlay blur handling from immediately restacking the overlay above unrelated foreground windows.
+- Added regression tests for macOS mpv focus loss and macOS blur restacking behavior.
+- Added a changelog fragment for the user-visible overlay z-order fix.
+
+Verification:
+- Passed: `bun test src/core/services/overlay-visibility.test.ts src/core/services/overlay-window.test.ts`
+- Passed: `bunx prettier --check src/core/services/overlay-visibility.ts src/core/services/overlay-visibility.test.ts src/core/services/overlay-window-input.ts src/core/services/overlay-window.test.ts changes/349-macos-overlay-z-order.md`
+- Passed: `bun run typecheck`
+- Passed: `bun run changelog:lint`
+- Passed: `bun run test:env`
+- Passed: `bun run build`
+- Passed: `bun run test:smoke:dist`
+- Blocked: `bun run test:fast` by existing keyboard/subsync cross-file global pollution; focused and environment tests pass.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-350 - Fix-known-highlighting-for-Yomitan-compound-tokens.md

@@ -0,0 +1,62 @@
+---
+id: TASK-350
+title: Fix known highlighting for Yomitan compound tokens
+status: Done
+assignee:
+  - codex
+created_date: '2026-05-12 09:08'
+updated_date: '2026-05-12 09:29'
+labels:
+  - bug
+  - tokenizer
+dependencies: []
+modified_files:
+  - src/core/services/tokenizer/yomitan-parser-runtime.ts
+  - src/core/services/tokenizer/yomitan-parser-runtime.test.ts
+  - src/core/services/tokenizer.test.ts
+  - changes/350-known-yomitan-token-highlighting.md
+priority: high
+ordinal: 184500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Subtitle known-word coloring should respect the lexical token selected by Yomitan. If Yomitan emits a compound or inflected expression as one token, SubMiner must not mark that displayed token known solely because MeCab/POS enrichment can decompose it into known component words.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 A Yomitan token such as `取り組んで` with headword `取り組む` remains not-known when only component words like `取る` or `組む` are known.
+- [x] #2 Frequency/JLPT/POS enrichment still works for the selected Yomitan token without leaking component known-word status into `isKnown`.
+- [x] #3 Regression coverage demonstrates the compound-token case and fails on current behavior before the fix.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a regression in `src/core/services/tokenizer.test.ts` for a Yomitan-selected compound token: Yomitan emits `取り組んで` with headword `取り組む`; MeCab splits the same span into component tokens whose headwords include known component words such as `組む`; expected result is one displayed token with `isKnown === false` when only the components are known.
+2. Verify the regression fails on current code.
+3. Patch MeCab enrichment so it only contributes POS metadata used by annotation filters/exclusions. It must preserve the Yomitan token's `surface`, `headword`, `reading`, offsets, and existing lexical annotation state, especially `isKnown`.
+4. Re-run the targeted tokenizer test, then a relevant fast test lane if practical.
+
+After inspecting code, MeCab enrichment currently only writes POS metadata. The observed component coloring can also come from SubMiner's custom Yomitan scanning path fragmenting a phrase differently than Yomitan's internal parser. Regression should exercise `requestYomitanScanTokens` fallback/parser behavior as seen by `tokenizeSubtitle`, and the fix should prefer Yomitan internal parse token identity while keeping MeCab limited to filtering/POS metadata.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+User clarified MeCab is intended only to help filter unwanted characters/particles/sound effects/etc., not to alter lexical tokenization or known-word decisions.
+
+Implementation settled on parse-first token identity: `requestYomitanScanTokens` now reads Yomitan internal parse tokens first. It still runs the scanner to keep scanner metadata when spans agree, but returns parse tokens when the scanner fragments the parse token. MeCab remains POS/filter enrichment only.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed known-word highlighting for Yomitan compound tokens by preferring Yomitan internal parse token spans over fragmented scanner output. When scanner output agrees with parse spans, scanner metadata such as name-match and word classes is preserved; when it fragments a Yomitan token, the parse token identity wins so known component words do not color the larger unknown token green.
+
+Added regressions for `取り組んで` with known component words (`取る`, `組む`, `もらう`) and for parser-runtime token selection/metadata behavior. Added a changelog fragment.
+
+Validation run: `bun test src/core/services/tokenizer.test.ts src/core/services/tokenizer/yomitan-parser-runtime.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts`; `bun run typecheck`; `bun x prettier --check src/core/services/tokenizer.test.ts src/core/services/tokenizer/yomitan-parser-runtime.ts src/core/services/tokenizer/yomitan-parser-runtime.test.ts changes/350-known-yomitan-token-highlighting.md`; `bun run changelog:lint`; `git diff --check`.
+<!-- SECTION:FINAL_SUMMARY:END -->

changes/349-macos-overlay-z-order.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Overlay: Kept the macOS overlay behind unrelated foreground windows while preserving its position above mpv.

changes/350-known-yomitan-token-highlighting.md

@@ -0,0 +1,4 @@
+type: fixed
+area: tokenizer
+
+- Tokenizer: Preserve Yomitan compound tokens for known-word highlighting so known component words no longer color a larger unknown word green.

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

@@ -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[] = [];

src/core/services/overlay-visibility.ts

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

src/core/services/overlay-window-input.ts

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

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

@@ -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[] = [];
 

src/core/services/tokenizer.test.ts

@@ -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(
     '鍛えた',

src/core/services/tokenizer/yomitan-parser-runtime.test.ts

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

src/core/services/tokenizer/yomitan-parser-runtime.ts

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