fix: address fullscreen and n-plus-one review notes

fix: refresh overlay on Hyprland fullscreen
fix: exclude kana-only n+1 targets
2026-05-28 12:55:17 -07:00 · 2026-04-27 01:34:41 -07:00 · 2026-04-27 01:34:41 -07:00 · 2026-04-27 01:34:41 -07:00 · 2026-04-27 01:34:41 -07:00 · 2026-04-27 01:34:41 -07:00
43 changed files with 1036 additions and 101 deletions
@@ -0,0 +1,33 @@
+---
+id: TASK-306
+title: Fix Hyprland fullscreen overlay geometry and hover pause
+status: Done
+assignee: []
+created_date: '2026-04-27 01:44'
+labels:
+  - linux
+  - hyprland
+  - overlay
+  - bug
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+Overlay should track mpv geometry through Hyprland fullscreen transitions, stay above fullscreen video, and keep primary subtitle hover pause working after fullscreen/toggle cycles.
+
+Implemented by observing mpv fullscreen property changes in addition to Hyprland geometry events, then refreshing visible overlay bounds/layering on Linux.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [x] #1 Hyprland tracker reacts to fullscreen/window state changes with updated geometry.
+- [x] #2 Visible overlay is re-layered above mpv after Hyprland fullscreen geometry updates.
+- [x] #3 Primary subtitle hover pause remains active after overlay geometry changes or visible overlay toggle cycles.
+<!-- AC:END -->
@@ -0,0 +1,54 @@
+---
+id: TASK-306
+title: Separate background stats daemon from regular SubMiner app
+status: Done
+assignee: []
+created_date: '2026-04-27 00:56'
+updated_date: '2026-04-27 01:00'
+labels:
+  - stats
+  - runtime
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Background stats mode should run only the stats data/server pieces. It must not bring up tray UI or expose the regular mpv connection surface, and stopping should remain CLI-only.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Launching stats background mode starts a separate stats daemon process rather than booting the regular SubMiner runtime.
+- [x] #2 Background stats mode does not create or keep a tray icon.
+- [x] #3 Background stats mode does not start mpv IPC/client surfaces that let mpv connect to the app.
+- [x] #4 Background stats mode remains stoppable through the stats stop command line path.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add entry-runtime tests for public stats background/stop daemon detection.
+2. Implement early public stats daemon command detection and route it before regular app boot.
+3. Run targeted tests and update task status/criteria.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented early public stats daemon routing in main-entry runtime. Direct `--stats-background` and `--stats-stop` now resolve to daemon control before single-instance lock and before loading `main.js`, matching the existing internal launcher daemon flags. Installed missing Bun dependencies to run targeted tests.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Summary:
+- Added `resolveStatsDaemonCommandAction` and updated entry detection so public `--stats-background` / `--stats-stop` invocations route through the isolated stats daemon control path.
+- Reused that action resolution in `stats-daemon-entry` so public stop commands map to stop instead of the default start path.
+- Added regression coverage for public daemon detection/action resolution.
+
+Verification:
+- `bun test src/main-entry-runtime.test.ts launcher/commands/command-modules.test.ts src/main/runtime/stats-cli-command.test.ts src/stats-daemon-control.test.ts`
+- `bun run typecheck`
+<!-- SECTION:FINAL_SUMMARY:END -->
@@ -0,0 +1,58 @@
+---
+id: TASK-307
+title: Defer in-app stats server to running background stats daemon
+status: Done
+assignee: []
+created_date: '2026-04-27 01:57'
+updated_date: '2026-04-27 02:02'
+labels:
+  - stats
+  - runtime
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+When normal SubMiner app startup has stats auto-start enabled, it should detect an already-running background stats daemon and avoid starting a second in-app stats server. Stats overlay/dashboard URL resolution should point at the background daemon.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 If a live background stats daemon state exists for another process, in-app stats auto-start does not start a local stats server.
+- [x] #2 Stats URL resolution returns the background daemon URL when the background daemon is live.
+- [x] #3 Stale or dead background daemon state is cleared and normal in-app stats startup still works.
+- [x] #4 Regression tests cover the deferral behavior.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add unit tests for stats server routing decisions around live/stale background daemon state.
+2. Implement a small routing helper used by main stats startup.
+3. Wire `ensureStatsServerStarted()` through the helper.
+4. Run targeted tests/typecheck/changelog lint and finalize the task.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Extracted stats server URL routing into `src/main/runtime/stats-server-routing.ts` and wired `main.ts` through it. The helper returns the background daemon URL without calling local server startup when a live external daemon exists; dead/self-owned stale state is removed before falling back to local startup. Added the new test to `test:core:src`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Summary:
+- Added a pure stats server routing helper that chooses between a live background daemon and local in-app stats server startup.
+- Updated main stats URL resolution to defer to another process's background daemon and only start the in-app server when no live daemon is available.
+- Added regression tests for live daemon deferral, dead daemon cleanup, self-owned stale state cleanup, and local server reuse.
+- Added the routing test to the core source test lane and added a changelog fragment.
+
+Verification:
+- `bun test src/main/runtime/stats-server-routing.test.ts src/main-entry-runtime.test.ts src/main/runtime/stats-cli-command.test.ts src/stats-daemon-control.test.ts`
+- `bun run test:core:src`
+- `bun run typecheck`
+- `bun run changelog:lint`
+<!-- SECTION:FINAL_SUMMARY:END -->
@@ -0,0 +1,58 @@
+---
+id: TASK-307
+title: Exclude kana-only words from N+1 subtitle targets
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-27 01:52'
+updated_date: '2026-04-27 01:57'
+labels:
+  - tokenizer
+  - annotations
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Subtitle N+1 annotation is over-targeting kana-only or hiragana/katakana tokens that collapse to dictionary words. Adjust targeting so kana-only tokens are not selected as N+1 candidates, while preserving tokenization/hover behavior and other annotation metadata where existing filters allow it.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Kana-only subtitle tokens are not marked as N+1 targets.
+- [x] #2 Kanji or mixed lexical tokens can still be marked as N+1 targets when they are the single unknown candidate in a sentence.
+- [x] #3 Regression coverage demonstrates the kana-only N+1 exclusion.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing regression in `src/core/services/tokenizer.test.ts` showing a kana-only Yomitan token is not selected as the single N+1 target, while a mixed lexical token in the same style still can be targeted.
+2. Implement the smallest filter in `src/token-merger.ts`: N+1 candidate selection rejects tokens whose surface is entirely kana; word-count behavior remains governed by existing annotation/POS filters.
+3. Run the focused tokenizer tests, then update task acceptance criteria/final summary.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented a surface-level kana-only guard in N+1 candidate selection. Kept existing word-count/POS filtering behavior intact; updated tokenizer and annotation-stage expectations where old tests intentionally allowed kana-only N+1 targets.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Summary:
+- Added kana-only surface detection to `isNPlusOneCandidateToken` so hiragana/katakana-only subtitle tokens are not selected as N+1 targets.
+- Added/updated tokenizer and annotation-stage regressions for kana-only targets while preserving non-kana N+1 behavior.
+- Added changelog fragment `changes/307-kana-nplusone-targets.md`.
+
+Verification:
+- `bun test src/core/services/tokenizer.test.ts --test-name-pattern "kana-only N\+1"` failed before the fix with `true !== false`.
+- `bun test src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer.test.ts` passed.
+- `bun run typecheck` passed.
+- `bun run test:fast` passed.
+- `bun run changelog:lint` passed.
+- `bunx prettier --check src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/token-merger.ts changes/307-kana-nplusone-targets.md` passed.
+<!-- SECTION:FINAL_SUMMARY:END -->
@@ -0,0 +1,54 @@
+---
+id: TASK-308
+title: Restore persistent JLPT subtitle underlines
+status: Done
+assignee:
+  - Codex
+created_date: '2026-04-27 02:03'
+updated_date: '2026-04-27 02:07'
+labels:
+  - overlay
+  - jlpt
+  - renderer
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+JLPT tagging currently exposes the JLPT level on hover, but the persistent subtitle underline is missing. When JLPT annotation is enabled and a rendered subtitle token has a JLPT level, users should see the configured JLPT color underline without needing to hover.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 JLPT-tagged subtitle tokens render a persistent underline for N1-N5 levels when JLPT tagging is enabled.
+- [x] #2 Hover and keyboard-selected JLPT labels continue to appear for tagged tokens.
+- [x] #3 Higher-priority annotation colors such as known words, N+1, names, and frequency styling are not overridden by JLPT text color.
+- [x] #4 Regression coverage verifies the CSS contract for persistent JLPT underlines.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a focused renderer CSS regression asserting each `word-jlpt-n*` class provides persistent underline decoration while preserving existing typography constraints.
+2. Run the focused renderer test to confirm the regression fails before production changes.
+3. Restore underline CSS for JLPT classes without broadening JLPT text-color precedence over known/N+1/name/frequency tokens.
+4. Re-run the focused renderer test and update acceptance criteria/task notes.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Verified red/green regression: tightened `src/renderer/subtitle-render.test.ts` first failed because base `word-jlpt-n*` selectors had no underline decoration, then passed after moving JLPT underline decoration to unconditional base selectors while leaving JLPT text color priority-scoped.
+
+Checks: `bun test src/renderer/subtitle-render.test.ts`; `bun run changelog:lint`; `bun run typecheck`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Restored persistent JLPT subtitle underlines by adding underline decoration to each base `word-jlpt-n*` renderer CSS class. JLPT text color remains in the existing priority-scoped selectors, so known/N+1/name/frequency coloring is not overridden while the underline still appears on any JLPT-tagged token.
+
+Updated renderer CSS regression coverage to assert underline decoration for N1-N5 and added a fixed changelog fragment. Verified with `bun test src/renderer/subtitle-render.test.ts`, `bun run changelog:lint`, and `bun run typecheck`.
+<!-- SECTION:FINAL_SUMMARY:END -->
@@ -0,0 +1,6 @@
+type: fixed
+area: tokenizer
+
+- Use Yomitan `wordClasses` metadata for subtitle POS filtering.
+- Backfill blank MeCab POS detail fields during parser enrichment.
+- Keep subtitle annotation metadata stripped from token results.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed Hyprland fullscreen transitions so mpv fullscreen changes refresh visible overlay geometry, reassert topmost stacking, and keep primary subtitle hover pause working after resize/toggle cycles.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Stats background mode now routes through the isolated stats daemon instead of starting the regular SubMiner app runtime.
@@ -0,0 +1,4 @@
+type: fixed
+area: tokenizer
+
+- Stopped kana-only subtitle tokens from being selected as N+1 targets.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- In-app stats startup now defers to an already-running background stats daemon instead of starting a second stats server.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Overlay: Restored persistent JLPT subtitle underlines while keeping hover JLPT labels and annotation color priority intact.
@@ -324,6 +324,10 @@ Add a `pass` rule for each global shortcut you configure. The defaults are `Alt+

 Without these rules, Hyprland intercepts the keypresses before they reach SubMiner, and the shortcuts silently do nothing.

+**Overlay stays behind mpv after fullscreen**
+
+SubMiner watches mpv's `fullscreen` property and refreshes the overlay geometry when it changes. If the overlay still does not move or rise above fullscreen mpv, confirm that the mpv IPC socket is connected and that `hyprctl -j clients` and `hyprctl -j monitors` work from the same environment that launched SubMiner.
+
 For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.land/Configuring/Binds/#global-keybinds) and [window rules](https://wiki.hypr.land/Configuring/Window-Rules/).

 ### macOS
@@ -48,7 +48,7 @@
    "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-binary-windows.lua",
    "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
    "test:launcher:src": "bun test launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/mpv.test.ts launcher/picker.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/smoke.e2e.test.ts && bun run test:plugin:src",
-    "test:core:src": "bun test src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts",
+    "test:core:src": "bun test src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts",
    "test:core:dist": "bun test dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command.test.js dist/core/services/ipc.test.js dist/core/services/anki-jimaku-ipc.test.js dist/core/services/field-grouping-overlay.test.js dist/core/services/numeric-shortcut-session.test.js dist/core/services/secondary-subtitle.test.js dist/core/services/mpv-render-metrics.test.js dist/core/services/overlay-content-measurement.test.js dist/core/services/mpv-control.test.js dist/core/services/mpv.test.js dist/core/services/runtime-options-ipc.test.js dist/core/services/runtime-config.test.js dist/core/services/yomitan-extension-paths.test.js dist/core/services/config-hot-reload.test.js dist/core/services/discord-presence.test.js dist/core/services/tokenizer.test.js dist/core/services/tokenizer/annotation-stage.test.js dist/core/services/tokenizer/parser-selection-stage.test.js dist/core/services/tokenizer/parser-enrichment-stage.test.js dist/core/services/subsync.test.js dist/core/services/overlay-bridge.test.js dist/core/services/overlay-manager.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/mining.test.js dist/core/services/anki-jimaku.test.js dist/core/services/jimaku-download-path.test.js dist/core/services/jellyfin.test.js dist/core/services/jellyfin-remote.test.js dist/core/services/immersion-tracker-service.test.js dist/core/services/overlay-runtime-init.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js dist/core/services/subtitle-processing-controller.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/anilist/anilist-update-queue.test.js dist/core/services/anilist/rate-limiter.test.js dist/core/services/jlpt-token-filter.test.js dist/core/services/subtitle-position.test.js dist/renderer/error-recovery.test.js dist/renderer/subtitle-render.test.js dist/renderer/handlers/mouse.test.js dist/renderer/handlers/keyboard.test.js dist/renderer/modals/jimaku.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/hyprland-tracker.test.js dist/window-trackers/x11-tracker.test.js dist/window-trackers/windows-helper.test.js dist/window-trackers/windows-tracker.test.js",
    "test:core:smoke:dist": "bun test dist/cli/help.test.js dist/core/services/runtime-config.test.js dist/core/services/ipc.test.js dist/core/services/overlay-manager.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/startup-bootstrap.test.js dist/renderer/error-recovery.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/x11-tracker.test.js",
    "test:smoke:dist": "bun run test:config:smoke:dist && bun run test:core:smoke:dist",
@@ -59,6 +59,7 @@ const MPV_SUBTITLE_PROPERTY_OBSERVATIONS: string[] = [
  'sub-ass-override',
  'sub-use-margins',
  'pause',
+  'fullscreen',
  'duration',
  'media-title',
  'secondary-sub-visibility',
@@ -93,6 +93,7 @@ function createDeps(overrides: Partial<MpvProtocolHandleMessageDeps> = {}): {
      emitTimePosChange: () => {},
      emitDurationChange: () => {},
      emitPauseChange: () => {},
+      emitFullscreenChange: (payload) => state.events.push(payload),
      autoLoadSecondarySubTrack: () => {},
      setCurrentVideoPath: () => {},
      emitSecondarySubtitleVisibility: (payload) => state.events.push(payload),
@@ -160,6 +161,17 @@ test('dispatchMpvProtocolMessage enforces sub-visibility hidden when overlay sup
  ]);
 });

+test('dispatchMpvProtocolMessage emits fullscreen changes', async () => {
+  const { deps, state } = createDeps();
+
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'fullscreen', data: true },
+    deps,
+  );
+
+  assert.deepEqual(state.events, [{ fullscreen: true }]);
+});
+
 test('dispatchMpvProtocolMessage skips sub-visibility suppression when overlay is hidden', async () => {
  const { deps, state } = createDeps({
    isVisibleOverlayVisible: () => false,
@@ -65,6 +65,7 @@ export interface MpvProtocolHandleMessageDeps {
  emitTimePosChange: (payload: { time: number }) => void;
  emitDurationChange: (payload: { duration: number }) => void;
  emitPauseChange: (payload: { paused: boolean }) => void;
+  emitFullscreenChange: (payload: { fullscreen: boolean }) => void;
  emitSubtitleMetricsChange: (payload: Partial<MpvSubtitleRenderMetrics>) => void;
  setCurrentSecondarySubText: (text: string) => void;
  resolvePendingRequest: (requestId: number, message: MpvMessage) => boolean;
@@ -291,6 +292,8 @@ export async function dispatchMpvProtocolMessage(
      }
    } else if (msg.name === 'pause') {
      deps.emitPauseChange({ paused: asBoolean(msg.data, false) });
+    } else if (msg.name === 'fullscreen') {
+      deps.emitFullscreenChange({ fullscreen: asBoolean(msg.data, false) });
    } else if (msg.name === 'media-title') {
      deps.emitMediaTitleChange({
        title: typeof msg.data === 'string' ? msg.data.trim() : null,
@@ -57,6 +57,22 @@ test('MpvIpcClient handles sub-text property change and broadcasts tokenized sub
  assert.equal(events[0]!.isOverlayVisible, false);
 });

+test('MpvIpcClient emits fullscreen property changes', async () => {
+  const events: Array<{ fullscreen: boolean }> = [];
+  const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
+  client.on('fullscreen-change', (payload) => {
+    events.push(payload);
+  });
+
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'fullscreen',
+    data: true,
+  });
+
+  assert.deepEqual(events, [{ fullscreen: true }]);
+});
+
 test('MpvIpcClient clears cached media title when media path changes', async () => {
  const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());

@@ -119,6 +119,7 @@ export interface MpvIpcClientEventMap {
  'time-pos-change': { time: number };
  'duration-change': { duration: number };
  'pause-change': { paused: boolean };
+  'fullscreen-change': { fullscreen: boolean };
  'secondary-subtitle-change': { text: string };
  'subtitle-track-change': { sid: number | null };
  'subtitle-track-list-change': { trackList: unknown[] | null };
@@ -330,6 +331,9 @@ export class MpvIpcClient implements MpvClient {
        this.playbackPaused = payload.paused;
        this.emit('pause-change', payload);
      },
+      emitFullscreenChange: (payload) => {
+        this.emit('fullscreen-change', payload);
+      },
      emitSecondarySubtitleChange: (payload) => {
        this.emit('secondary-subtitle-change', payload);
      },
@@ -67,6 +67,8 @@ export function ensureOverlayWindowLevel(window: BrowserWindow): void {
    return;
  }
  window.setAlwaysOnTop(true);
+  window.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+  window.moveTop();
 }

 export function enforceOverlayLayerOrder(options: {
@@ -2306,6 +2306,29 @@ test('tokenizeSubtitle selects one N+1 target token', async () => {
  assert.equal(targets[0]?.surface, '犬');
 });

+test('tokenizeSubtitle does not select kana-only N+1 target tokens', async () => {
+  const result = await tokenizeSubtitle(
+    '私のばあい',
+    makeDepsFromYomitanTokens(
+      [
+        { surface: '私', reading: 'わたし', headword: '私' },
+        { surface: 'の', reading: 'の', headword: 'の' },
+        { surface: 'ばあい', reading: 'ばあい', headword: '場合' },
+      ],
+      {
+        getMinSentenceWordsForNPlusOne: () => 2,
+        isKnownWord: (text) => text === '私',
+      },
+    ),
+  );
+
+  assert.equal(result.tokens?.length, 3);
+  assert.equal(
+    result.tokens?.some((token) => token.isNPlusOneTarget),
+    false,
+  );
+});
+
 test('tokenizeSubtitle does not mark target when sentence has multiple candidates', async () => {
  const result = await tokenizeSubtitle(
    '猫犬',
@@ -3040,7 +3063,9 @@ test('tokenizeSubtitle uses Yomitan word classes to classify standalone particle
  let mecabCalls = 0;
  const result = await tokenizeSubtitle(
    'は',
-    makeDepsFromYomitanTokens([{ surface: 'は', reading: 'は', headword: 'は', wordClasses: ['prt'] }], {
+    makeDepsFromYomitanTokens(
+      [{ surface: 'は', reading: 'は', headword: 'は', wordClasses: ['prt'] }],
+      {
        getFrequencyDictionaryEnabled: () => true,
        getFrequencyRank: (text) => (text === 'は' ? 10 : null),
        getJlptLevel: (text) => (text === 'は' ? 'N5' : null),
@@ -3048,7 +3073,8 @@ test('tokenizeSubtitle uses Yomitan word classes to classify standalone particle
          mecabCalls += 1;
          return null;
        },
-    }),
+      },
+    ),
  );

  assert.equal(mecabCalls, 1);
@@ -3063,7 +3089,9 @@ test('tokenizeSubtitle uses Yomitan word classes to classify standalone particle
 test('tokenizeSubtitle fills detailed MeCab POS when Yomitan word class supplies coarse POS', async () => {
  const result = await tokenizeSubtitle(
    'は',
-    makeDepsFromYomitanTokens([{ surface: 'は', reading: 'は', headword: 'は', wordClasses: ['prt'] }], {
+    makeDepsFromYomitanTokens(
+      [{ surface: 'は', reading: 'は', headword: 'は', wordClasses: ['prt'] }],
+      {
        tokenizeWithMecab: async () => [
          {
            headword: 'は',
@@ -3080,7 +3108,8 @@ test('tokenizeSubtitle fills detailed MeCab POS when Yomitan word class supplies
            isNPlusOneTarget: false,
          },
        ],
-    }),
+      },
+    ),
  );

  assert.equal(result.tokens?.[0]?.partOfSpeech, PartOfSpeech.particle);
@@ -3682,7 +3711,7 @@ test('tokenizeSubtitle excludes single-kana merged tokens from frequency highlig
  assert.equal(result.tokens?.[0]?.frequencyRank, undefined);
 });

-test('tokenizeSubtitle excludes merged function/content token from frequency highlighting but keeps N+1', async () => {
+test('tokenizeSubtitle excludes merged kana-only function/content token from frequency and N+1', async () => {
  const result = await tokenizeSubtitle(
    'になれば',
    makeDepsFromYomitanTokens([{ surface: 'になれば', reading: 'になれば', headword: 'なる' }], {
@@ -3736,7 +3765,7 @@ test('tokenizeSubtitle excludes merged function/content token from frequency hig
  assert.equal(result.tokens?.length, 1);
  assert.equal(result.tokens?.[0]?.pos1, '助詞|動詞');
  assert.equal(result.tokens?.[0]?.frequencyRank, undefined);
-  assert.equal(result.tokens?.[0]?.isNPlusOneTarget, true);
+  assert.equal(result.tokens?.[0]?.isNPlusOneTarget, false);
 });

 test('tokenizeSubtitle clears all annotations for kana-only demonstrative helper merges', async () => {
@@ -3935,7 +3964,7 @@ test('tokenizeSubtitle clears all annotations for explanatory pondering endings'
        surface: 'どうかしちゃった',
        headword: 'どうかしちゃう',
        isKnown: false,
-        isNPlusOneTarget: true,
+        isNPlusOneTarget: false,
        frequencyRank: 3200,
        jlptLevel: 'N3',
      },
@@ -160,7 +160,7 @@ async function applyAnnotationStage(
  options: TokenizerAnnotationOptions,
 ): Promise<MergedToken[]> {
  if (!hasAnyAnnotationEnabled(options)) {
-    return tokens;
+    return stripSubtitleAnnotationMetadata(tokens);
  }

  if (!annotationStageModulePromise) {
@@ -570,13 +570,13 @@ test('annotateTokens keeps other annotations for name matches when name highligh
  let jlptLookupCalls = 0;
  const tokens = [
    makeToken({
-      surface: 'オリヴィア',
-      reading: 'オリヴィア',
-      headword: 'オリヴィア',
+      surface: '山田',
+      reading: 'ヤマダ',
+      headword: '山田',
      isNameMatch: true,
      frequencyRank: 42,
      startPos: 0,
-      endPos: 5,
+      endPos: 2,
    }),
  ];

@@ -770,7 +770,7 @@ test('annotateTokens allows previously default-excluded pos1 when removed from e
  });

  assert.equal(result[0]?.frequencyRank, 8);
-  assert.equal(result[0]?.isNPlusOneTarget, true);
+  assert.equal(result[0]?.isNPlusOneTarget, false);
 });

 test('annotateTokens excludes default non-independent pos2 from frequency and N+1', () => {
@@ -787,16 +787,9 @@ test('annotateTokens excludes default non-independent pos2 from frequency and N+
    }),
  ];

-  const result = annotateTokens(
-    tokens,
-    makeDeps({
-      isKnownWord: (text) => text === 'た' || text === '負',
-      getJlptLevel: (text) => (text === 'た' || text === '負' ? 'N3' : null),
-    }),
-    {
+  const result = annotateTokens(tokens, makeDeps(), {
    minSentenceWordsForNPlusOne: 1,
-    },
-  );
+  });

  assert.equal(result[0]?.frequencyRank, undefined);
  assert.equal(result[0]?.isNPlusOneTarget, false);
@@ -972,10 +965,10 @@ test('annotateTokens allows previously default-excluded pos2 when removed from e
  });

  assert.equal(result[0]?.frequencyRank, 9);
-  assert.equal(result[0]?.isNPlusOneTarget, true);
+  assert.equal(result[0]?.isNPlusOneTarget, false);
 });

-test('annotateTokens excludes composite function/content tokens from frequency but keeps N+1 eligible', () => {
+test('annotateTokens excludes kana-only composite function/content tokens from frequency and N+1', () => {
  const tokens = [
    makeToken({
      surface: 'になれば',
@@ -993,7 +986,7 @@ test('annotateTokens excludes composite function/content tokens from frequency b
  });

  assert.equal(result[0]?.frequencyRank, undefined);
-  assert.equal(result[0]?.isNPlusOneTarget, true);
+  assert.equal(result[0]?.isNPlusOneTarget, false);
 });

 test('annotateTokens excludes composite tokens when all component pos tags are excluded', () => {
@@ -39,6 +39,33 @@ test('enrichTokensWithMecabPos1 fills missing pos1 using surface-sequence fallba
  assert.equal(enriched[0]?.pos1, '助詞');
 });

+test('enrichTokensWithMecabPos1 backfills blank pos2 and pos3 fields', () => {
+  const tokens = [
+    makeToken({
+      surface: 'は',
+      startPos: 0,
+      endPos: 1,
+      pos1: '助詞',
+      pos2: '',
+      pos3: ' ',
+    }),
+  ];
+  const mecabTokens = [
+    makeToken({
+      surface: 'は',
+      startPos: 0,
+      endPos: 1,
+      pos1: '助詞',
+      pos2: '係助詞',
+      pos3: '一般',
+    }),
+  ];
+
+  const enriched = enrichTokensWithMecabPos1(tokens, mecabTokens);
+  assert.equal(enriched[0]?.pos2, '係助詞');
+  assert.equal(enriched[0]?.pos3, '一般');
+});
+
 test('enrichTokensWithMecabPos1 keeps partOfSpeech unchanged and only enriches POS tags', () => {
  const tokens = [makeToken({ surface: 'これは', startPos: 0, endPos: 3 })];
  const mecabTokens = [
@@ -120,6 +120,13 @@ function lowerBoundByIndex(candidates: IndexedMecabToken[], targetIndex: number)
  return low;
 }

+function coalesceMissingPosField(
+  current: string | undefined,
+  fallback: string | undefined,
+): string | undefined {
+  return typeof current === 'string' && current.trim().length > 0 ? current : fallback;
+}
+
 function joinUniqueTags(values: Array<string | undefined>): string | undefined {
  const unique: string[] = [];
  for (const value of values) {
@@ -329,9 +336,9 @@ function fillMissingPos1BySurfaceSequence(
    cursor = best.index + 1;
    return {
      ...token,
-      pos1: token.pos1 ?? best.pos1,
-      pos2: token.pos2 ?? best.pos2,
-      pos3: token.pos3 ?? best.pos3,
+      pos1: coalesceMissingPosField(token.pos1, best.pos1),
+      pos2: coalesceMissingPosField(token.pos2, best.pos2),
+      pos3: coalesceMissingPosField(token.pos3, best.pos3),
    };
  });
 }
@@ -412,9 +419,9 @@ export function enrichTokensWithMecabPos1(

    return {
      ...token,
-      pos1: token.pos1 ?? metadata.pos1,
-      pos2: token.pos2 ?? metadata.pos2,
-      pos3: token.pos3 ?? metadata.pos3,
+      pos1: coalesceMissingPosField(token.pos1, metadata.pos1),
+      pos2: coalesceMissingPosField(token.pos2, metadata.pos2),
+      pos3: coalesceMissingPosField(token.pos3, metadata.pos3),
    };
  });

@@ -13,6 +13,11 @@ const KATAKANA_TO_HIRAGANA_OFFSET = 0x60;
 const KATAKANA_CODEPOINT_START = 0x30a1;
 const KATAKANA_CODEPOINT_END = 0x30f6;

+const STANDALONE_GRAMMAR_PARTICLE_PHRASES = ['たって', 'だって'] as const;
+const STANDALONE_GRAMMAR_PARTICLE_PHRASES_SET: ReadonlySet<string> = new Set(
+  STANDALONE_GRAMMAR_PARTICLE_PHRASES,
+);
+
 const SUBTITLE_ANNOTATION_EXCLUDED_TERMS = new Set([
  'あ',
  'ああ',
@@ -20,9 +25,7 @@ const SUBTITLE_ANNOTATION_EXCLUDED_TERMS = new Set([
  'うう',
  'おお',
  'くれ',
-  'たって',
  'って',
-  'だって',
  'はあ',
  'はは',
  'べき',
@@ -31,6 +34,7 @@ const SUBTITLE_ANNOTATION_EXCLUDED_TERMS = new Set([
  'ほう',
  'もんか',
  'ものか',
+  ...STANDALONE_GRAMMAR_PARTICLE_PHRASES,
 ]);
 const SUBTITLE_ANNOTATION_EXCLUDED_EXPLANATORY_ENDING_PREFIXES = ['ん', 'の', 'なん', 'なの'];
 const SUBTITLE_ANNOTATION_EXCLUDED_EXPLANATORY_ENDING_CORES = [
@@ -98,8 +102,6 @@ const STANDALONE_GRAMMAR_PARTICLE_SURFACES = new Set([
  'よ',
  'を',
 ]);
-const STANDALONE_GRAMMAR_PARTICLE_PHRASES = new Set(['たって', 'だって']);
-
 export interface SubtitleAnnotationFilterOptions {
  pos1Exclusions?: ReadonlySet<string>;
  pos2Exclusions?: ReadonlySet<string>;
@@ -327,7 +329,7 @@ function isStandaloneGrammarParticle(token: MergedToken): boolean {
  return (
    normalizedSurface === normalizedHeadword &&
    (STANDALONE_GRAMMAR_PARTICLE_SURFACES.has(normalizedSurface) ||
-      STANDALONE_GRAMMAR_PARTICLE_PHRASES.has(normalizedSurface))
+      STANDALONE_GRAMMAR_PARTICLE_PHRASES_SET.has(normalizedSurface))
  );
 }

@@ -5,6 +5,7 @@ import {
  normalizeLaunchMpvExtraArgs,
  normalizeStartupArgv,
  normalizeLaunchMpvTargets,
+  resolveStatsDaemonCommandAction,
  sanitizeHelpEnv,
  sanitizeLaunchMpvEnv,
  sanitizeStartupEnv,
@@ -164,6 +165,51 @@ test('stats-daemon entry helper detects internal daemon commands', () => {
  assert.equal(shouldHandleStatsDaemonCommandAtEntry(['SubMiner.AppImage', '--start'], {}), false);
 });

+test('stats-daemon entry helper detects public background stats commands', () => {
+  assert.equal(
+    shouldHandleStatsDaemonCommandAtEntry(
+      ['SubMiner.AppImage', '--stats', '--stats-background'],
+      {},
+    ),
+    true,
+  );
+  assert.equal(
+    shouldHandleStatsDaemonCommandAtEntry(['SubMiner.AppImage', '--stats', '--stats-stop'], {}),
+    true,
+  );
+  assert.equal(
+    shouldHandleStatsDaemonCommandAtEntry(['SubMiner.AppImage', '--stats-background'], {}),
+    true,
+  );
+  assert.equal(
+    shouldHandleStatsDaemonCommandAtEntry(['SubMiner.AppImage', '--stats-background'], {
+      ELECTRON_RUN_AS_NODE: '1',
+    }),
+    false,
+  );
+  assert.equal(shouldHandleStatsDaemonCommandAtEntry(['SubMiner.AppImage', '--stats'], {}), false);
+});
+
+test('stats-daemon entry helper resolves daemon action for public and internal commands', () => {
+  assert.equal(
+    resolveStatsDaemonCommandAction(['SubMiner.AppImage', '--stats-daemon-start']),
+    'start',
+  );
+  assert.equal(
+    resolveStatsDaemonCommandAction(['SubMiner.AppImage', '--stats-daemon-stop']),
+    'stop',
+  );
+  assert.equal(
+    resolveStatsDaemonCommandAction(['SubMiner.AppImage', '--stats', '--stats-background']),
+    'start',
+  );
+  assert.equal(
+    resolveStatsDaemonCommandAction(['SubMiner.AppImage', '--stats', '--stats-stop']),
+    'stop',
+  );
+  assert.equal(resolveStatsDaemonCommandAction(['SubMiner.AppImage', '--stats']), null);
+});
+
 test('sanitizeStartupEnv suppresses warnings and lsfg layer', () => {
  const env = sanitizeStartupEnv({
    VK_INSTANCE_LAYERS: 'foo:lsfg-vk:bar',
@@ -143,7 +143,17 @@ export function shouldHandleStatsDaemonCommandAtEntry(
  env: NodeJS.ProcessEnv,
 ): boolean {
  if (env.ELECTRON_RUN_AS_NODE === '1') return false;
-  return argv.includes('--stats-daemon-start') || argv.includes('--stats-daemon-stop');
+  return resolveStatsDaemonCommandAction(argv) !== null;
+}
+
+export function resolveStatsDaemonCommandAction(argv: string[]): 'start' | 'stop' | null {
+  if (argv.includes('--stats-daemon-stop') || argv.includes('--stats-stop')) {
+    return 'stop';
+  }
+  if (argv.includes('--stats-daemon-start') || argv.includes('--stats-background')) {
+    return 'start';
+  }
+  return null;
 }

 export function normalizeLaunchMpvTargets(argv: string[]): string[] {
@@ -404,6 +404,7 @@ import {
  resolveBackgroundStatsServerUrl,
  writeBackgroundStatsServerState,
 } from './main/runtime/stats-daemon';
+import { createEnsureStatsServerUrlHandler } from './main/runtime/stats-server-routing';
 import { resolveLegacyVocabularyPosFromTokens } from './core/services/immersion-tracker/legacy-vocabulary-pos';
 import { createAnilistUpdateQueue } from './core/services/anilist/anilist-update-queue';
 import {
@@ -1910,6 +1911,7 @@ const WINDOWS_VISIBLE_OVERLAY_BLUR_REFRESH_DELAYS_MS = [0, 25, 100, 250] as cons
 const WINDOWS_VISIBLE_OVERLAY_Z_ORDER_RETRY_DELAYS_MS = [0, 48, 120, 240, 480] as const;
 const WINDOWS_VISIBLE_OVERLAY_FOREGROUND_POLL_INTERVAL_MS = 75;
 const WINDOWS_VISIBLE_OVERLAY_FOCUS_HANDOFF_GRACE_MS = 200;
+const LINUX_MPV_FULLSCREEN_OVERLAY_REFRESH_DELAYS_MS = [0, 50, 150, 300, 600] as const;
 let windowsVisibleOverlayBlurRefreshTimeouts: Array<ReturnType<typeof setTimeout>> = [];
 let windowsVisibleOverlayZOrderRetryTimeouts: Array<ReturnType<typeof setTimeout>> = [];
 let windowsVisibleOverlayZOrderSyncInFlight = false;
@@ -1917,6 +1919,7 @@ let windowsVisibleOverlayZOrderSyncQueued = false;
 let windowsVisibleOverlayForegroundPollInterval: ReturnType<typeof setInterval> | null = null;
 let lastWindowsVisibleOverlayForegroundProcessName: string | null = null;
 let lastWindowsVisibleOverlayBlurredAtMs = 0;
+let linuxMpvFullscreenOverlayRefreshTimeouts: Array<ReturnType<typeof setTimeout>> = [];

 function clearWindowsVisibleOverlayBlurRefreshTimeouts(): void {
  for (const timeout of windowsVisibleOverlayBlurRefreshTimeouts) {
@@ -1932,6 +1935,48 @@ function clearWindowsVisibleOverlayZOrderRetryTimeouts(): void {
  windowsVisibleOverlayZOrderRetryTimeouts = [];
 }

+function clearLinuxMpvFullscreenOverlayRefreshTimeouts(): void {
+  for (const timeout of linuxMpvFullscreenOverlayRefreshTimeouts) {
+    clearTimeout(timeout);
+  }
+  linuxMpvFullscreenOverlayRefreshTimeouts = [];
+}
+
+function refreshLinuxVisibleOverlayAfterMpvFullscreenChange(): void {
+  if (process.platform !== 'linux' || !overlayManager.getVisibleOverlayVisible()) {
+    return;
+  }
+
+  overlayVisibilityRuntime.updateVisibleOverlayVisibility();
+
+  const mainWindow = overlayManager.getMainWindow();
+  if (!mainWindow || mainWindow.isDestroyed() || !mainWindow.isVisible()) {
+    return;
+  }
+
+  mainWindow.hide();
+  mainWindow.showInactive();
+  ensureOverlayWindowLevel(mainWindow);
+}
+
+function scheduleLinuxVisibleOverlayFullscreenRefreshBurst(): void {
+  if (process.platform !== 'linux') {
+    return;
+  }
+
+  clearLinuxMpvFullscreenOverlayRefreshTimeouts();
+  for (const delayMs of LINUX_MPV_FULLSCREEN_OVERLAY_REFRESH_DELAYS_MS) {
+    const refreshTimeout = setTimeout(() => {
+      linuxMpvFullscreenOverlayRefreshTimeouts = linuxMpvFullscreenOverlayRefreshTimeouts.filter(
+        (timeout) => timeout !== refreshTimeout,
+      );
+      refreshLinuxVisibleOverlayAfterMpvFullscreenChange();
+    }, delayMs);
+    refreshTimeout.unref?.();
+    linuxMpvFullscreenOverlayRefreshTimeouts.push(refreshTimeout);
+  }
+}
+
 function getWindowsNativeWindowHandle(window: BrowserWindow): string {
  const handle = window.getNativeWindowHandle();
  return handle.length >= 8
@@ -3170,11 +3215,7 @@ registerProtocolUrlHandlersHandler();
 const statsDistPath = path.join(__dirname, '..', 'stats', 'dist');
 const statsPreloadPath = path.join(__dirname, 'preload-stats.js');

-const ensureStatsServerStarted = (): string => {
-  const liveDaemon = readLiveBackgroundStatsDaemonState();
-  if (liveDaemon && liveDaemon.pid !== process.pid) {
-    return resolveBackgroundStatsServerUrl(liveDaemon);
-  }
+const startLocalStatsServer = (): void => {
  const tracker = appState.immersionTracker;
  if (!tracker) {
    throw new Error('Immersion tracker failed to initialize.');
@@ -3224,9 +3265,20 @@ const ensureStatsServerStarted = (): string => {
    appState.statsServer = statsServer;
  }
  appState.statsServer = statsServer;
-  return `http://127.0.0.1:${getResolvedConfig().stats.serverPort}`;
 };

+const ensureStatsServerStarted = createEnsureStatsServerUrlHandler({
+  currentPid: process.pid,
+  readBackgroundState: () => readBackgroundStatsServerState(statsDaemonStatePath),
+  removeBackgroundState: () => {
+    removeBackgroundStatsServerState(statsDaemonStatePath);
+  },
+  isProcessAlive: (pid) => isBackgroundStatsServerProcessAlive(pid),
+  hasLocalStatsServer: () => statsServer !== null,
+  startLocalStatsServer,
+  getConfiguredPort: () => getResolvedConfig().stats.serverPort,
+});
+
 const ensureBackgroundStatsServerStarted = (): {
  url: string;
  runningInCurrentProcess: boolean;
@@ -3247,13 +3299,15 @@ const ensureBackgroundStatsServerStarted = (): {
  }

  const port = getResolvedConfig().stats.serverPort;
-  const url = ensureStatsServerStarted();
+  const result = ensureStatsServerStarted();
+  if (result.source === 'local') {
    writeBackgroundStatsServerState(statsDaemonStatePath, {
      pid: process.pid,
      port,
      startedAtMs: Date.now(),
    });
-  return { url, runningInCurrentProcess: true };
+  }
+  return { url: result.url, runningInCurrentProcess: result.source === 'local' };
 };

 const stopBackgroundStatsServer = async (): Promise<{ ok: boolean; stale: boolean }> => {
@@ -3352,7 +3406,7 @@ const immersionTrackerStartupMainDeps: Parameters<
      registerStatsOverlayToggle({
        staticDir: statsDistPath,
        preloadPath: statsPreloadPath,
-        getApiBaseUrl: () => ensureStatsServerStarted(),
+        getApiBaseUrl: () => ensureStatsServerStarted().url,
        getToggleKey: () => getResolvedConfig().stats.toggleKey,
        resolveBounds: () => getCurrentOverlayGeometry(),
        onVisibilityChanged: (visible) => {
@@ -3407,7 +3461,7 @@ const runStatsCliCommand = createRunStatsCliCommandHandler({
    await createMecabTokenizerAndCheck();
  },
  getImmersionTracker: () => appState.immersionTracker,
-  ensureStatsServerStarted: () => statsStartupRuntime.ensureStatsServerStarted(),
+  ensureStatsServerStarted: () => statsStartupRuntime.ensureStatsServerStarted().url,
  ensureBackgroundStatsServerStarted: () =>
    statsStartupRuntime.ensureBackgroundStatsServerStarted(),
  stopBackgroundStatsServer: () => statsStartupRuntime.stopBackgroundStatsServer(),
@@ -3796,6 +3850,9 @@ const {
      }
      lastObservedTimePos = time;
    },
+    onFullscreenChange: () => {
+      scheduleLinuxVisibleOverlayFullscreenRefreshBurst();
+    },
    onSubtitleTrackChange: (sid) => {
      scheduleSubtitlePrefetchRefresh();
      youtubePrimarySubtitleNotificationRuntime.handleSubtitleTrackChange(sid);
@@ -4036,10 +4093,18 @@ const buildUpdateVisibleOverlayBoundsMainDepsHandler =
  createBuildUpdateVisibleOverlayBoundsMainDepsHandler({
    setOverlayWindowBounds: (geometry) => applyOverlayRegions(geometry),
    afterSetOverlayWindowBounds: () => {
-      if (process.platform !== 'win32' || !overlayManager.getVisibleOverlayVisible()) {
+      if (!overlayManager.getVisibleOverlayVisible()) {
        return;
      }
+      if (process.platform === 'win32') {
        scheduleWindowsVisibleOverlayZOrderSyncBurst();
+        return;
+      }
+      const mainWindow = overlayManager.getMainWindow();
+      if (!mainWindow || mainWindow.isDestroyed()) {
+        return;
+      }
+      ensureOverlayWindowLevel(mainWindow);
    },
  });
 const updateVisibleOverlayBoundsMainDeps = buildUpdateVisibleOverlayBoundsMainDepsHandler();
@@ -4619,7 +4684,7 @@ async function dispatchSessionAction(request: SessionActionDispatchRequest): Pro
      toggleStatsOverlayWindow({
        staticDir: statsDistPath,
        preloadPath: statsPreloadPath,
-        getApiBaseUrl: () => ensureStatsServerStarted(),
+        getApiBaseUrl: () => ensureStatsServerStarted().url,
        getToggleKey: () => getResolvedConfig().stats.toggleKey,
        resolveBounds: () => getCurrentOverlayGeometry(),
        onVisibilityChanged: (visible) => {
@@ -128,6 +128,7 @@ test('mpv event bindings register all expected events', () => {
    onTimePosChange: () => {},
    onDurationChange: () => {},
    onPauseChange: () => {},
+    onFullscreenChange: () => {},
    onSubtitleMetricsChange: () => {},
    onSecondarySubtitleVisibility: () => {},
  });
@@ -151,6 +152,7 @@ test('mpv event bindings register all expected events', () => {
    'time-pos-change',
    'duration-change',
    'pause-change',
+    'fullscreen-change',
    'subtitle-metrics-change',
    'secondary-subtitle-visibility',
  ]);
@@ -11,6 +11,7 @@ type MpvBindingEventName =
  | 'time-pos-change'
  | 'duration-change'
  | 'pause-change'
+  | 'fullscreen-change'
  | 'subtitle-metrics-change'
  | 'secondary-subtitle-visibility';

@@ -83,6 +84,7 @@ export function createBindMpvClientEventHandlers(deps: {
  onTimePosChange: (payload: { time: number }) => void;
  onDurationChange: (payload: { duration: number }) => void;
  onPauseChange: (payload: { paused: boolean }) => void;
+  onFullscreenChange: (payload: { fullscreen: boolean }) => void;
  onSubtitleMetricsChange: (payload: { patch: Record<string, unknown> }) => void;
  onSecondarySubtitleVisibility: (payload: { visible: boolean }) => void;
 }) {
@@ -99,6 +101,7 @@ export function createBindMpvClientEventHandlers(deps: {
    mpvClient.on('time-pos-change', deps.onTimePosChange);
    mpvClient.on('duration-change', deps.onDurationChange);
    mpvClient.on('pause-change', deps.onPauseChange);
+    mpvClient.on('fullscreen-change', deps.onFullscreenChange);
    mpvClient.on('subtitle-metrics-change', deps.onSubtitleMetricsChange);
    mpvClient.on('secondary-subtitle-visibility', deps.onSecondarySubtitleVisibility);
  };
@@ -68,6 +68,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
  recordMediaDuration: (durationSec: number) => void;
  reportJellyfinRemoteProgress: (forceImmediate: boolean) => void;
  onTimePosUpdate?: (time: number) => void;
+  onFullscreenChange?: (fullscreen: boolean) => void;
  recordPauseState: (paused: boolean) => void;

  updateSubtitleRenderMetrics: (patch: Record<string, unknown>) => void;
@@ -177,6 +178,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
      onTimePosChange: handleMpvTimePosChange,
      onDurationChange: ({ duration }) => deps.recordMediaDuration(duration),
      onPauseChange: handleMpvPauseChange,
+      onFullscreenChange: ({ fullscreen }) => deps.onFullscreenChange?.(fullscreen),
      onSubtitleMetricsChange: handleMpvSubtitleMetricsChange,
      onSecondarySubtitleVisibility: handleMpvSecondarySubtitleVisibility,
    })(mpvClient);
@@ -57,6 +57,7 @@ test('mpv main event main deps map app state updates and delegate callbacks', as
    updateCurrentMediaTitle: (title) => calls.push(`title:${title}`),
    resetAnilistMediaGuessState: () => calls.push('reset-guess'),
    reportJellyfinRemoteProgress: (forceImmediate) => calls.push(`progress:${forceImmediate}`),
+    onFullscreenChange: (fullscreen) => calls.push(`fullscreen:${fullscreen}`),
    updateSubtitleRenderMetrics: () => calls.push('metrics'),
    refreshDiscordPresence: () => calls.push('presence-refresh'),
  })();
@@ -95,6 +96,7 @@ test('mpv main event main deps map app state updates and delegate callbacks', as
  deps.notifyImmersionTitleUpdate('title');
  deps.recordPlaybackPosition(10);
  deps.reportJellyfinRemoteProgress(true);
+  deps.onFullscreenChange?.(true);
  deps.recordPauseState(true);
  deps.updateSubtitleRenderMetrics({});
  deps.setPreviousSecondarySubVisibility(true);
@@ -112,6 +114,7 @@ test('mpv main event main deps map app state updates and delegate callbacks', as
  assert.ok(calls.includes('sync-immersion'));
  assert.ok(calls.includes('autoplay:/tmp/video'));
  assert.ok(calls.includes('metrics'));
+  assert.ok(calls.includes('fullscreen:true'));
  assert.ok(calls.includes('presence-refresh'));
  assert.ok(calls.includes('restore-mpv-sub'));
  assert.ok(calls.includes('reset-sidebar-layout'));
@@ -60,6 +60,7 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
  resetAnilistMediaGuessState: () => void;
  reportJellyfinRemoteProgress: (forceImmediate: boolean) => void;
  onTimePosUpdate?: (time: number) => void;
+  onFullscreenChange?: (fullscreen: boolean) => void;
  updateSubtitleRenderMetrics: (patch: Record<string, unknown>) => void;
  refreshDiscordPresence: () => void;
  ensureImmersionTrackerInitialized: () => void;
@@ -176,6 +177,9 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
    onTimePosUpdate: deps.onTimePosUpdate
      ? (time: number) => deps.onTimePosUpdate!(time)
      : undefined,
+    onFullscreenChange: deps.onFullscreenChange
+      ? (fullscreen: boolean) => deps.onFullscreenChange!(fullscreen)
+      : undefined,
    recordPauseState: (paused: boolean) => {
      deps.appState.playbackPaused = paused;
      deps.ensureImmersionTrackerInitialized();
@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createEnsureStatsServerUrlHandler } from './stats-server-routing';
+
+function createHarness(options?: {
+  state?: { pid: number; port: number; startedAtMs: number } | null;
+  processAlive?: boolean;
+  localServerStarted?: boolean;
+}) {
+  const calls: string[] = [];
+  let localServerStarted = options?.localServerStarted ?? false;
+  const handler = createEnsureStatsServerUrlHandler({
+    currentPid: 100,
+    readBackgroundState: () => {
+      calls.push('readBackgroundState');
+      return options?.state ?? null;
+    },
+    removeBackgroundState: () => {
+      calls.push('removeBackgroundState');
+    },
+    isProcessAlive: () => {
+      calls.push('isProcessAlive');
+      return options?.processAlive ?? true;
+    },
+    hasLocalStatsServer: () => localServerStarted,
+    startLocalStatsServer: () => {
+      calls.push('startLocalStatsServer');
+      localServerStarted = true;
+    },
+    getConfiguredPort: () => 6969,
+  });
+
+  return {
+    calls,
+    handler,
+  };
+}
+
+test('stats server routing defers to a live background daemon from another process', () => {
+  const { calls, handler } = createHarness({
+    state: { pid: 200, port: 7979, startedAtMs: 1 },
+    processAlive: true,
+  });
+
+  assert.deepEqual(handler(), { url: 'http://127.0.0.1:7979', source: 'foreign' });
+  assert.deepEqual(calls, ['readBackgroundState', 'isProcessAlive']);
+});
+
+test('stats server routing clears dead daemon state and starts local server', () => {
+  const { calls, handler } = createHarness({
+    state: { pid: 200, port: 7979, startedAtMs: 1 },
+    processAlive: false,
+  });
+
+  assert.deepEqual(handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
+  assert.deepEqual(calls, [
+    'readBackgroundState',
+    'isProcessAlive',
+    'removeBackgroundState',
+    'startLocalStatsServer',
+  ]);
+});
+
+test('stats server routing clears self-owned stale state and starts local server', () => {
+  const { calls, handler } = createHarness({
+    state: { pid: 100, port: 7979, startedAtMs: 1 },
+    processAlive: true,
+  });
+
+  assert.deepEqual(handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
+  assert.deepEqual(calls, [
+    'readBackgroundState',
+    'removeBackgroundState',
+    'startLocalStatsServer',
+  ]);
+});
+
+test('stats server routing reuses a started local stats server', () => {
+  const { calls, handler } = createHarness({
+    state: null,
+    localServerStarted: true,
+  });
+
+  assert.deepEqual(handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
+  assert.deepEqual(calls, ['readBackgroundState', 'removeBackgroundState']);
+});
@@ -0,0 +1,41 @@
+import type { BackgroundStatsServerState } from './stats-daemon';
+
+type EnsureStatsServerUrlDeps = {
+  currentPid: number;
+  readBackgroundState: () => BackgroundStatsServerState | null;
+  removeBackgroundState: () => void;
+  isProcessAlive: (pid: number) => boolean;
+  hasLocalStatsServer: () => boolean;
+  startLocalStatsServer: () => void;
+  getConfiguredPort: () => number;
+};
+
+function formatStatsServerUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+export type EnsureStatsServerUrlResult =
+  | { url: string; source: 'foreign' }
+  | { url: string; source: 'local' };
+
+export function createEnsureStatsServerUrlHandler(
+  deps: EnsureStatsServerUrlDeps,
+): () => EnsureStatsServerUrlResult {
+  return () => {
+    const state = deps.readBackgroundState();
+    if (!state) {
+      deps.removeBackgroundState();
+    } else if (state.pid === deps.currentPid && !deps.hasLocalStatsServer()) {
+      deps.removeBackgroundState();
+    } else if (!deps.isProcessAlive(state.pid)) {
+      deps.removeBackgroundState();
+    } else if (state.pid !== deps.currentPid) {
+      return { url: formatStatsServerUrl(state.port), source: 'foreign' };
+    }
+
+    if (!deps.hasLocalStatsServer()) {
+      deps.startLocalStatsServer();
+    }
+    return { url: formatStatsServerUrl(deps.getConfiguredPort()), source: 'local' };
+  };
+}
@@ -1315,6 +1315,74 @@ test('window resize ignores synthetic subtitle enter until the pointer moves aga
  }
 });

+test('window resize allows primary hover pause from a real mouseenter over subtitles', async () => {
+  const ctx = createMouseTestContext();
+  const originalWindow = globalThis.window;
+  const originalDocument = globalThis.document;
+  const mpvCommands: Array<(string | number)[]> = [];
+  const windowListeners = new Map<string, Array<() => void>>();
+  ctx.platform.shouldToggleMouseIgnore = true;
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: {
+      electronAPI: {
+        setIgnoreMouseEvents: () => {},
+      },
+      addEventListener: (type: string, listener: () => void) => {
+        const bucket = windowListeners.get(type) ?? [];
+        bucket.push(listener);
+        windowListeners.set(type, bucket);
+      },
+      getComputedStyle: () => ({
+        visibility: 'hidden',
+        display: 'none',
+        opacity: '0',
+      }),
+      focus: () => {},
+      innerHeight: 1000,
+    },
+  });
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: {
+      addEventListener: () => {},
+      elementFromPoint: () => ctx.dom.subtitleContainer,
+      querySelectorAll: () => [],
+      body: {},
+    },
+  });
+
+  try {
+    const handlers = createMouseHandlers(ctx as never, {
+      modalStateReader: {
+        isAnySettingsModalOpen: () => false,
+        isAnyModalOpen: () => false,
+      },
+      applyYPercent: () => {},
+      getCurrentYPercent: () => 10,
+      persistSubtitlePositionPatch: () => {},
+      getSubtitleHoverAutoPauseEnabled: () => true,
+      getYomitanPopupAutoPauseEnabled: () => false,
+      getPlaybackPaused: async () => false,
+      sendMpvCommand: (command) => {
+        mpvCommands.push(command);
+      },
+    });
+
+    handlers.setupResizeHandler();
+    for (const listener of windowListeners.get('resize') ?? []) {
+      listener();
+    }
+
+    await handlers.handlePrimaryMouseEnter({ clientX: 120, clientY: 240 } as MouseEvent);
+    assert.deepEqual(mpvCommands, [['set_property', 'pause', 'yes']]);
+  } finally {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: originalWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: originalDocument });
+  }
+});
+
 test('visibility recovery keeps overlay click-through when pointer is not over subtitles', () => {
  const ctx = createMouseTestContext();
  const originalWindow = globalThis.window;
@@ -300,13 +300,16 @@ export function createMouseHandlers(
  }

  async function handleMouseEnter(
-    _event?: MouseEvent,
+    event?: MouseEvent,
    showSecondaryHover = false,
    source: 'direct' | 'tracked-pointer' = 'direct',
  ): Promise<void> {
    if (source === 'direct' && suppressDirectHoverEnterSource !== null) {
+      if (!event || !syncHoverStateFromPoint(event.clientX, event.clientY).isOverSubtitle) {
        return;
      }
+      suppressDirectHoverEnterSource = null;
+    }

    ctx.state.isOverSubtitle = true;
    if (showSecondaryHover) {
@@ -793,6 +793,14 @@ body.settings-modal-open [data-subminer-yomitan-popup-host='true'] {
  color: var(--subtitle-name-match-color, #f5bde6);
 }

+#subtitleRoot .word.word-jlpt-n1 {
+  text-decoration-line: underline;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 4px;
+  text-decoration-color: var(--subtitle-jlpt-n1-color, #ed8796);
+  text-decoration-style: solid;
+}
+
 #subtitleRoot
  .word.word-jlpt-n1:not(
    :is(
@@ -814,6 +822,14 @@ body.settings-modal-open [data-subminer-yomitan-popup-host='true'] {
  color: var(--subtitle-jlpt-n1-color, #ed8796);
 }

+#subtitleRoot .word.word-jlpt-n2 {
+  text-decoration-line: underline;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 4px;
+  text-decoration-color: var(--subtitle-jlpt-n2-color, #f5a97f);
+  text-decoration-style: solid;
+}
+
 #subtitleRoot
  .word.word-jlpt-n2:not(
    :is(
@@ -835,6 +851,14 @@ body.settings-modal-open [data-subminer-yomitan-popup-host='true'] {
  color: var(--subtitle-jlpt-n2-color, #f5a97f);
 }

+#subtitleRoot .word.word-jlpt-n3 {
+  text-decoration-line: underline;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 4px;
+  text-decoration-color: var(--subtitle-jlpt-n3-color, #f9e2af);
+  text-decoration-style: solid;
+}
+
 #subtitleRoot
  .word.word-jlpt-n3:not(
    :is(
@@ -856,6 +880,14 @@ body.settings-modal-open [data-subminer-yomitan-popup-host='true'] {
  color: var(--subtitle-jlpt-n3-color, #f9e2af);
 }

+#subtitleRoot .word.word-jlpt-n4 {
+  text-decoration-line: underline;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 4px;
+  text-decoration-color: var(--subtitle-jlpt-n4-color, #a6e3a1);
+  text-decoration-style: solid;
+}
+
 #subtitleRoot
  .word.word-jlpt-n4:not(
    :is(
@@ -877,6 +909,14 @@ body.settings-modal-open [data-subminer-yomitan-popup-host='true'] {
  color: var(--subtitle-jlpt-n4-color, #a6e3a1);
 }

+#subtitleRoot .word.word-jlpt-n5 {
+  text-decoration-line: underline;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 4px;
+  text-decoration-color: var(--subtitle-jlpt-n5-color, #8aadf4);
+  text-decoration-style: solid;
+}
+
 #subtitleRoot
  .word.word-jlpt-n5:not(
    :is(
@@ -901,6 +901,14 @@ test('subtitle annotation CSS changes token color without overriding typography'
  for (let level = 1; level <= 5; level += 1) {
    const plainJlptBlock = extractClassBlock(cssText, `#subtitleRoot .word.word-jlpt-n${level}`);
    assert.doesNotMatch(plainJlptBlock, /(?:^|\n)\s*color\s*:/m);
+    assert.match(plainJlptBlock, /text-decoration-line:\s*underline;/);
+    assert.match(plainJlptBlock, /text-decoration-thickness:\s*2px;/);
+    assert.match(plainJlptBlock, /text-underline-offset:\s*4px;/);
+    assert.match(
+      plainJlptBlock,
+      new RegExp(`text-decoration-color:\\s*var\\(--subtitle-jlpt-n${level}-color,`),
+    );
+    assert.match(plainJlptBlock, /text-decoration-style:\s*solid;/);

    const block = extractClassBlock(cssText, buildJlptColorSelector(level));
    assert.ok(block.length > 0, `word-jlpt-n${level} class should exist`);
@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { shell } from 'electron';
-import { sanitizeStartupEnv } from './main-entry-runtime';
+import { resolveStatsDaemonCommandAction, sanitizeStartupEnv } from './main-entry-runtime';
 import {
  isBackgroundStatsServerProcessAlive,
  readBackgroundStatsServerState,
@@ -44,7 +44,7 @@ function hasFlag(argv: string[], flag: string): boolean {

 function parseControlArgs(argv: string[], userDataPath: string): StatsDaemonControlArgs {
  return {
-    action: hasFlag(argv, '--stats-daemon-stop') ? 'stop' : 'start',
+    action: resolveStatsDaemonCommandAction(argv) ?? 'start',
    responsePath: readFlagValue(argv, '--stats-response-path'),
    openBrowser: hasFlag(argv, '--stats-daemon-open-browser'),
    daemonScriptPath: path.join(__dirname, 'stats-daemon-runner.js'),
@@ -282,6 +282,26 @@ function isExcludedByTagSet(normalizedTag: string, exclusions: ReadonlySet<strin
  return parts.every((part) => exclusions.has(part));
 }

+function isKanaChar(char: string): boolean {
+  const code = char.codePointAt(0);
+  if (code === undefined) {
+    return false;
+  }
+
+  return (
+    (code >= 0x3041 && code <= 0x3096) ||
+    (code >= 0x309b && code <= 0x309f) ||
+    code === 0x30fc ||
+    (code >= 0x30a0 && code <= 0x30fa) ||
+    (code >= 0x30fd && code <= 0x30ff)
+  );
+}
+
+function isKanaOnlyText(text: string): boolean {
+  const normalized = text.trim();
+  return normalized.length > 0 && Array.from(normalized).every((char) => isKanaChar(char));
+}
+
 export function isNPlusOneCandidateToken(
  token: MergedToken,
  pos1Exclusions: ReadonlySet<string> = N_PLUS_ONE_IGNORED_POS1,
@@ -290,6 +310,9 @@ export function isNPlusOneCandidateToken(
  if (token.isKnown) {
    return false;
  }
+  if (isKanaOnlyText(token.surface)) {
+    return false;
+  }
  return isNPlusOneWordCountToken(token, pos1Exclusions, pos2Exclusions);
 }

@@ -371,6 +394,9 @@ export function markNPlusOneTargets(
    return [];
  }

+  const normalizedSourceText =
+    typeof sourceText === 'string' ? sourceText.replace(/\r?\n/g, ' ').trim() : undefined;
+
  const markedTokens = tokens.map((token) => ({
    ...token,
    isNPlusOneTarget: false,
@@ -408,7 +434,7 @@ export function markNPlusOneTargets(
  for (let i = 0; i < markedTokens.length; i++) {
    const token = markedTokens[i];
    if (!token) continue;
-    if (hasSentenceBoundaryInSourceGap(sourceText, previousTokenEnd, token.startPos)) {
+    if (hasSentenceBoundaryInSourceGap(normalizedSourceText, previousTokenEnd, token.startPos)) {
      markSentence(sentenceStart, i);
      sentenceStart = i;
    }
@@ -1,9 +1,12 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  isHyprlandGeometryEvent,
  parseHyprctlClients,
+  resolveHyprlandWindowGeometry,
  selectHyprlandMpvWindow,
  type HyprlandClient,
+  type HyprlandMonitor,
 } from './hyprland-tracker';

 function makeClient(overrides: Partial<HyprlandClient> = {}): HyprlandClient {
@@ -19,6 +22,17 @@ function makeClient(overrides: Partial<HyprlandClient> = {}): HyprlandClient {
  };
 }

+function makeMonitor(overrides: Partial<HyprlandMonitor> = {}): HyprlandMonitor {
+  return {
+    id: 0,
+    x: 0,
+    y: 0,
+    width: 1920,
+    height: 1080,
+    ...overrides,
+  };
+}
+
 test('selectHyprlandMpvWindow ignores hidden and unmapped mpv clients', () => {
  const selected = selectHyprlandMpvWindow(
    [
@@ -106,3 +120,32 @@ test('parseHyprctlClients tolerates non-json prefix output', () => {
    },
  ]);
 });
+
+test('isHyprlandGeometryEvent treats fullscreenv2 as a geometry-changing event', () => {
+  assert.equal(isHyprlandGeometryEvent('fullscreenv2'), true);
+  assert.equal(isHyprlandGeometryEvent('workspacev2'), true);
+  assert.equal(isHyprlandGeometryEvent('activewindowv2'), false);
+});
+
+test('resolveHyprlandWindowGeometry uses monitor bounds for fullscreen clients', () => {
+  const geometry = resolveHyprlandWindowGeometry(
+    makeClient({
+      at: [60, 80],
+      size: [1280, 720],
+      monitor: 1,
+      fullscreen: 2,
+      fullscreenClient: 2,
+    }),
+    [
+      makeMonitor({ id: 0, x: 0, y: 0, width: 1920, height: 1080 }),
+      makeMonitor({ id: 1, x: 1920, y: 0, width: 2560, height: 1440 }),
+    ],
+  );
+
+  assert.deepEqual(geometry, {
+    x: 1920,
+    y: 0,
+    width: 2560,
+    height: 1440,
+  });
+});
@@ -20,6 +20,7 @@ import * as net from 'net';
 import { execSync } from 'child_process';
 import { BaseWindowTracker } from './base-tracker';
 import { createLogger } from '../logger';
+import type { WindowGeometry } from '../types';

 const log = createLogger('tracker').child('hyprland');

@@ -29,11 +30,22 @@ export interface HyprlandClient {
  initialClass?: string;
  at: [number, number];
  size: [number, number];
+  monitor?: number;
+  fullscreen?: number;
+  fullscreenClient?: number;
  pid?: number;
  mapped?: boolean;
  hidden?: boolean;
 }

+export interface HyprlandMonitor {
+  id: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
 interface SelectHyprlandMpvWindowOptions {
  targetMpvSocketPath: string | null;
  activeWindowAddress: string | null;
@@ -132,8 +144,73 @@ export function parseHyprctlClients(output: string): HyprlandClient[] | null {
  return parsed as HyprlandClient[];
 }

+export function parseHyprctlMonitors(output: string): HyprlandMonitor[] | null {
+  const jsonPayload = extractHyprctlJsonPayload(output);
+  if (!jsonPayload) {
+    return null;
+  }
+
+  const parsed = JSON.parse(jsonPayload) as unknown;
+  if (!Array.isArray(parsed)) {
+    return null;
+  }
+
+  return parsed as HyprlandMonitor[];
+}
+
+function isHyprlandFullscreenClient(client: HyprlandClient): boolean {
+  return (client.fullscreen ?? 0) > 0;
+}
+
+export function resolveHyprlandWindowGeometry(
+  client: HyprlandClient,
+  monitors: HyprlandMonitor[] | null,
+): WindowGeometry {
+  if (isHyprlandFullscreenClient(client) && typeof client.monitor === 'number') {
+    const monitor = monitors?.find((candidate) => candidate.id === client.monitor);
+    if (monitor) {
+      return {
+        x: monitor.x,
+        y: monitor.y,
+        width: monitor.width,
+        height: monitor.height,
+      };
+    }
+  }
+
+  return {
+    x: client.at[0],
+    y: client.at[1],
+    width: client.size[0],
+    height: client.size[1],
+  };
+}
+
+export function isHyprlandGeometryEvent(name: string): boolean {
+  return (
+    name === 'movewindow' ||
+    name === 'movewindowv2' ||
+    name === 'resizewindow' ||
+    name === 'resizewindowv2' ||
+    name === 'windowtitle' ||
+    name === 'windowtitlev2' ||
+    name === 'openwindow' ||
+    name === 'closewindow' ||
+    name === 'fullscreen' ||
+    name === 'fullscreenv2' ||
+    name === 'changefloatingmode' ||
+    name === 'workspace' ||
+    name === 'workspacev2' ||
+    name === 'focusedmon' ||
+    name === 'monitoradded' ||
+    name === 'monitoraddedv2' ||
+    name === 'monitorremoved'
+  );
+}
+
 export class HyprlandWindowTracker extends BaseWindowTracker {
  private pollInterval: ReturnType<typeof setInterval> | null = null;
+  private pollTimeouts: Array<ReturnType<typeof setTimeout>> = [];
  private eventSocket: net.Socket | null = null;
  private readonly targetMpvSocketPath: string | null;
  private activeWindowAddress: string | null = null;
@@ -154,6 +231,10 @@ export class HyprlandWindowTracker extends BaseWindowTracker {
      clearInterval(this.pollInterval);
      this.pollInterval = null;
    }
+    for (const timeout of this.pollTimeouts) {
+      clearTimeout(timeout);
+    }
+    this.pollTimeouts = [];
    if (this.eventSocket) {
      this.eventSocket.destroy();
      this.eventSocket = null;
@@ -200,6 +281,9 @@ export class HyprlandWindowTracker extends BaseWindowTracker {
    }

    const [name, rawData = ''] = trimmedEvent.split('>>', 2);
+    if (!name) {
+      return;
+    }
    const data = rawData.trim();

    if (name === 'activewindowv2') {
@@ -212,17 +296,25 @@ export class HyprlandWindowTracker extends BaseWindowTracker {
      this.activeWindowAddress = null;
    }

-    if (
-      name === 'movewindow' ||
-      name === 'movewindowv2' ||
-      name === 'windowtitle' ||
-      name === 'windowtitlev2' ||
-      name === 'openwindow' ||
-      name === 'closewindow' ||
-      name === 'fullscreen' ||
-      name === 'changefloatingmode'
-    ) {
+    if (isHyprlandGeometryEvent(name)) {
+      this.scheduleGeometryPollBurst();
+    }
+  }
+
+  private scheduleGeometryPollBurst(): void {
    this.pollGeometry();
+    for (const timeout of this.pollTimeouts) {
+      clearTimeout(timeout);
+    }
+    this.pollTimeouts = [50, 150, 300].map((delayMs) => {
+      const pollTimeout = setTimeout(() => {
+        this.pollTimeouts = this.pollTimeouts.filter((timeout) => timeout !== pollTimeout);
+        this.pollGeometry();
+      }, delayMs);
+      return pollTimeout;
+    });
+    for (const pollTimeout of this.pollTimeouts) {
+      pollTimeout.unref?.();
    }
  }

@@ -237,12 +329,9 @@ export class HyprlandWindowTracker extends BaseWindowTracker {
      const mpvWindow = this.findTargetWindow(clients);

      if (mpvWindow) {
-        this.updateGeometry({
-          x: mpvWindow.at[0],
-          y: mpvWindow.at[1],
-          width: mpvWindow.size[0],
-          height: mpvWindow.size[1],
-        });
+        this.updateGeometry(
+          resolveHyprlandWindowGeometry(mpvWindow, this.getHyprlandMonitors(mpvWindow)),
+        );
      } else {
        this.updateGeometry(null);
      }
@@ -259,6 +348,19 @@ export class HyprlandWindowTracker extends BaseWindowTracker {
    });
  }

+  private getHyprlandMonitors(client: HyprlandClient): HyprlandMonitor[] | null {
+    if (!isHyprlandFullscreenClient(client)) {
+      return null;
+    }
+
+    try {
+      const output = execSync('hyprctl -j monitors', { encoding: 'utf-8' });
+      return parseHyprctlMonitors(output);
+    } catch {
+      return null;
+    }
+  }
+
  private getWindowCommandLine(pid: number): string | null {
    const commandLine = execSync(`ps -p ${pid} -o args=`, {
      encoding: 'utf-8',
Author	SHA1	Message	Date
sudacode	c150fce782	fix: address fullscreen and n-plus-one review notes	2026-04-27 01:34:41 -07:00
sudacode	ab41837d3d	fix: refresh overlay on Hyprland fullscreen	2026-04-27 01:34:41 -07:00
sudacode	9e4ad907fe	fix: exclude kana-only n+1 targets	2026-04-27 01:34:41 -07:00
sudacode	af86ce2341	fix: restore jlpt subtitle underlines	2026-04-27 01:34:41 -07:00
sudacode	b10a7b3e98	fix(tokenizer): preserve annotation and enrichment behavior	2026-04-27 01:34:41 -07:00
sudacode	96894ff85c	feat(tokenizer): use Yomitan word classes for subtitle POS filtering - Carry matched headword wordClasses from termsFind into YomitanScanToken - Map recognized Yomitan wordClasses to SubMiner coarse POS before annotation - MeCab enrichment now fills only missing POS fields, preserving existing coarse pos1 - Exclude standalone grammar particles, して helper fragments, and single-kana surfaces from annotations - Respect source-text punctuation gaps when counting N+1 sentence words - Preserve known-word highlight on excluded kanji-containing tokens - Add backlog tasks 304 (N+1 boundary bug) and 305 (wordClasses POS, done)	2026-04-27 01:34:41 -07:00
sudacode	53aa58d044	Route stats background mode through isolated daemon and defer in-app startup to live daemon (#58 )	2026-04-26 19:26:01 -07:00