chore: bump version to 0.3.0

docs: capture anki proxy notes and codebase health backlog
docs: update keyboard-driven yomitan workflow
2026-04-10 04:19:25 -07:00 · 2026-03-05 20:21:03 -08:00 · 2026-03-05 20:14:58 -08:00 · 2026-03-05 20:13:38 -08:00 · 2026-03-05 19:20:55 -08:00 · 2026-03-05 18:39:40 -08:00
33 changed files with 1643 additions and 106 deletions
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@
 SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation:

 - **Hover to look up** — Yomitan dictionary popups directly on subtitles
+- **Keyboard-driven lookup mode** — Navigate token-by-token, keep lookup open across tokens, and control popup scrolling/audio/mining without leaving the overlay
 - **One-key mining** — Creates Anki cards with sentence, audio, screenshot, and translation
 - **Instant auto-enrichment** — Optional local AnkiConnect proxy enriches new Yomitan cards immediately
 - **Reading annotations** — Combines N+1 targeting, frequency-dictionary highlighting, and JLPT underlining while you read
--- a/codebase-health-remediation.md
+++ b/codebase-health-remediation.md
@@ -0,0 +1,8 @@
+---
+id: m-0
+title: 'Codebase Health Remediation'
+---
+
+## Description
+
+Follow-up work from the March 6, 2026 codebase review: strengthen the runnable test gate, remove confirmed dead architecture, and continue decomposition of oversized runtime entrypoints.
--- a/Anki-integration-add-local-AnkiConnect-proxy-transport-for-push-based-auto-enrichment.md
+++ b/Anki-integration-add-local-AnkiConnect-proxy-transport-for-push-based-auto-enrichment.md
@@ -6,7 +6,7 @@ title: >-
 status: Done
 assignee: []
 created_date: '2026-02-28 02:38'
-updated_date: '2026-02-28 22:36'
+updated_date: '2026-03-04 13:55'
 labels: []
 dependencies: []
 references:
@@ -49,4 +49,10 @@ Risk/impact context:

 Completed implementation in branch working tree; ready to merge once local changes are committed and test gate passes.

+Follow-up fix (2026-03-04):
+
+- Updated bundled Yomitan server-sync behavior to target `profileCurrent` instead of hardcoded `profiles[0]`.
+- Added proxy-mode force override so bundled Yomitan always points at SubMiner proxy URL when `ankiConnect.proxy.enabled=true`; this ensures mined cards pass through proxy and trigger auto-enrichment.
+- Added regression tests for blocked existing-server case and force-override injection path.
+
 <!-- SECTION:FINAL_SUMMARY:END -->
--- a/Migrate-AniSkip-metadatalookup-orchestration-to-launcher-Electron.md
+++ b/Migrate-AniSkip-metadatalookup-orchestration-to-launcher-Electron.md
@@ -33,11 +33,15 @@ priority: medium
 ## Description

 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Move AniSkip MAL/title-to-MAL lookup and intro payload resolution from mpv Lua to launcher Electron flow, while keeping mpv-side intro skip UX and chapter/chapter prompt behavior in plugin. Launcher should infer/analyze file metadata, fetch AniSkip payload when launching files, and pass resolved skip window via script options; plugin should trust launcher payload and fall back only when absent.
+
 <!-- SECTION:DESCRIPTION:END -->

 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [x] #1 Launcher infers AniSkip metadata for file targets using existing guessit/fallback logic and performs AniSkip MAL + payload resolution during mpv startup.
 - [x] #2 Launcher injects script options containing resolved MAL id and intro window fields (or explicit lookup-failure status) into mpv startup.
 - [x] #3 Lua plugin consumes launcher-provided AniSkip intro data and skips all network lookups when payload is present.
@@ -49,15 +53,18 @@ Move AniSkip MAL/title-to-MAL lookup and intro payload resolution from mpv Lua t
 ## Implementation Plan

 <!-- SECTION:PLAN:BEGIN -->
-1) Add launcher-side AniSkip payload resolution helpers in launcher/aniskip-metadata.ts (MAL prefix lookup + AniSkip payload fetch + result normalization).
-2) Wire launcher/mpv.ts + buildSubminerScriptOpts to pass resolved AniSkip fields/mode in --script-opts for file playback.
-3) Update plugin/subminer/aniskip.lua plus options/state to consume injected payload: if intro_start/end present, apply immediately and skip network lookup; otherwise retain existing async behavior.
-4) Ensure fallback for standalone mpv usage remains intact for no-launcher/manual refresh.
-5) Add/update tests/docs/config references for new script-opt contract and edge cases.
+
+1. Add launcher-side AniSkip payload resolution helpers in launcher/aniskip-metadata.ts (MAL prefix lookup + AniSkip payload fetch + result normalization).
+2. Wire launcher/mpv.ts + buildSubminerScriptOpts to pass resolved AniSkip fields/mode in --script-opts for file playback.
+3. Update plugin/subminer/aniskip.lua plus options/state to consume injected payload: if intro_start/end present, apply immediately and skip network lookup; otherwise retain existing async behavior.
+4. Ensure fallback for standalone mpv usage remains intact for no-launcher/manual refresh.
+5. Add/update tests/docs/config references for new script-opt contract and edge cases.
 <!-- SECTION:PLAN:END -->

 ## Final Summary

 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
 Executed end-to-end migration so launcher resolves AniSkip title/MAL/payload before mpv start and injects it via --script-opts. Plugin now parses and consumes launcher payload (JSON/url/base64), applies OP intro from payload, tracks payload metadata in state, and keeps legacy async lookup path for non-launcher/absent payload playback. Added launcher config key aniskip_payload and updated launcher/aniskip-metadata tests for resolve/payload behavior and contract validation.
+
 <!-- SECTION:FINAL_SUMMARY:END -->
--- a/Renderer-keyboard-driven-Yomitan-lookup-mode-and-popup-key-forwarding.md
+++ b/Renderer-keyboard-driven-Yomitan-lookup-mode-and-popup-key-forwarding.md
@@ -0,0 +1,68 @@
+---
+id: TASK-86
+title: 'Renderer: keyboard-driven Yomitan lookup mode and popup key forwarding'
+status: Done
+assignee:
+  - Codex
+created_date: '2026-03-04 13:40'
+updated_date: '2026-03-05 11:30'
+labels:
+  - enhancement
+  - renderer
+  - yomitan
+dependencies:
+  - TASK-77
+references:
+  - src/renderer/handlers/keyboard.ts
+  - src/renderer/handlers/mouse.ts
+  - src/renderer/renderer.ts
+  - src/renderer/state.ts
+  - src/renderer/yomitan-popup.ts
+  - src/core/services/overlay-window.ts
+  - src/preload.ts
+  - src/shared/ipc/contracts.ts
+  - src/types.ts
+  - vendor/yomitan/js/app/frontend.js
+  - vendor/yomitan/js/app/popup.js
+  - vendor/yomitan/js/display/display.js
+  - vendor/yomitan/js/display/popup-main.js
+  - vendor/yomitan/js/display/display-audio.js
+documentation:
+  - README.md
+  - docs/usage.md
+  - docs/shortcuts.md
+priority: medium
+ordinal: 13000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+Add true keyboard-driven token lookup flow in overlay:
+
+- Toggle keyboard token-selection mode and navigate tokens by keyboard (`Arrow` + `HJKL`).
+- Toggle Yomitan lookup window for selected token via fixed accelerator (`Ctrl/Cmd+Y`) without requiring mouse click.
+- Preserve keyboard-only workflow while popup is open by forwarding popup keys (`J/K`, `M`, `P`, `[`, `]`) and restoring overlay focus on popup close.
+- Ensure selection styling and hover metadata tooltips (frequency/JLPT) work for keyboard-selected token.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [x] #1 Keyboard mode toggle exists and shows visual selection outline for active token.
+- [x] #2 Navigation works via arrows and vim keys while keyboard mode is enabled.
+- [x] #3 Lookup window toggles from selected token with `Ctrl/Cmd+Y`; close path restores overlay keyboard focus.
+- [x] #4 Popup-local controls work via keyboard forwarding (`J/K`, `M`, `P`, `[`, `]`), including mine action.
+- [x] #5 Frequency/JLPT hover tags render for keyboard-selected token.
+- [x] #6 Renderer/runtime tests cover new visibility/selection behavior, and docs are updated.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
+Implemented keyboard-driven Yomitan workflow end-to-end in renderer + bundled Yomitan runtime bridge. Added overlay-level keyboard mode state, token selection sync, lookup toggle routing, popup command forwarding, and focus recovery after popup close. Follow-up fixes kept lookup open while moving between tokens, made popup-local `J/K` and `ArrowUp/ArrowDown` scroll work from overlay-owned focus with key repeat, skipped keyboard/token annotation flow for parser groups that have no dictionary-backed headword, and preserved paused playback when token navigation jumps across subtitle lines. Updated user docs/README to document the final shortcut behavior.
+
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Codebase-health-harden-verification-and-retire-dead-architecture-identified-in-the-March-2026-review.md
+++ b/Codebase-health-harden-verification-and-retire-dead-architecture-identified-in-the-March-2026-review.md
@@ -0,0 +1,71 @@
+---
+id: TASK-87
+title: >-
+  Codebase health: harden verification and retire dead architecture identified
+  in the March 2026 review
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:19'
+updated_date: '2026-03-06 03:20'
+labels:
+  - tech-debt
+  - tests
+  - maintainability
+milestone: m-0
+dependencies: []
+references:
+  - package.json
+  - README.md
+  - src/main.ts
+  - src/anki-integration.ts
+  - src/core/services/immersion-tracker-service.test.ts
+  - src/translators/index.ts
+  - src/subsync/engines.ts
+  - src/subtitle/pipeline.ts
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+Track the remediation work from the March 6, 2026 code review. The review found that the default test gate only exercises 53 of 241 test files, the dedicated subtitle test lane is a no-op, SQLite-backed immersion tracking tests are conditionally skipped in the standard Bun run, src/main.ts still contains a large dead-symbol backlog, several registry/pipeline modules appear unreferenced from live execution paths, and src/anki-integration.ts remains an oversized orchestration file. This parent task should coordinate a safe sequence: improve verification first, then remove dead code and continue decomposition with good test coverage in place.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 Child tasks are created for each remediation workstream with explicit dependencies and enough context for an isolated agent to execute them.
+- [ ] #2 The parent task records the recommended sequencing and parallelization strategy so replacement agents can resume without conversation history.
+- [ ] #3 Completion of the parent task leaves the repository with a materially more trustworthy test gate, less dead architecture, and clearer ownership boundaries for the main runtime and Anki integration surfaces.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+Recommended sequencing:
+
+1. Run TASK-87.1, TASK-87.2, TASK-87.3, and TASK-87.7 first. These are the safety-net and tooling tasks and can largely proceed in parallel.
+2. Start TASK-87.4 once TASK-87.1 lands so src/main.ts cleanup happens under a more trustworthy test matrix.
+3. Start TASK-87.5 after TASK-87.1 and TASK-87.2 so dead subsync/pipeline cleanup happens with stronger subtitle and runtime verification.
+4. Start TASK-87.6 after TASK-87.1 so Anki refactors happen with broader default coverage in place.
+5. Keep PRs focused: do not combine verification work with architectural cleanup unless a narrow dependency requires it.
+
+Parallelization guidance:
+
+- Wave 1 parallel: TASK-87.1, TASK-87.2, TASK-87.3, TASK-87.7
+- Wave 2 parallel: TASK-87.4, TASK-87.5, TASK-87.6
+
+Shared review context to restate in child tasks:
+
+- Standard test scripts currently reference only 53 unique test files out of 241 discovered test and type-test files under src/ and launcher/.
+- test:subtitle is currently a placeholder echo even though subtitle sync is a user-facing feature.
+- SQLite-backed immersion tracker tests are conditionally skipped in the standard Bun run.
+- src/main.ts trips many noUnusedLocals/noUnusedParameters diagnostics.
+- src/translators/index.ts, src/subsync/engines.ts, src/subtitle/pipeline.ts, src/tokenizers/index.ts, and src/token-mergers/index.ts appeared unreferenced during review and must be re-verified before deletion.
+<!-- SECTION:PLAN:END -->
--- a/Testing-workflow-make-standard-test-commands-reflect-the-maintained-test-surface.md
+++ b/Testing-workflow-make-standard-test-commands-reflect-the-maintained-test-surface.md
@@ -0,0 +1,53 @@
+---
+id: TASK-87.1
+title: >-
+  Testing workflow: make standard test commands reflect the maintained test
+  surface
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:19'
+updated_date: '2026-03-06 03:21'
+labels:
+  - tests
+  - maintainability
+milestone: m-0
+dependencies: []
+references:
+  - package.json
+  - src/main-entry-runtime.test.ts
+  - src/anki-integration/anki-connect-proxy.test.ts
+  - src/main/runtime/jellyfin-remote-playback.test.ts
+  - src/main/runtime/registry.test.ts
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+parent_task_id: TASK-87
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+The current package scripts hand-enumerate a small subset of test files, which leaves the standard green signal misleading. A local audit found 241 test/type-test files under src/ and launcher/, but only 53 unique files referenced by the standard package.json test scripts. This task should redesign the runnable test matrix so maintained tests are either executed by the standard commands or intentionally excluded through a documented rule, instead of silently drifting out of coverage.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 The repository has a documented and reproducible test matrix for standard development commands, including which suites belong in the default lane versus slower or environment-specific lanes.
+- [ ] #2 The standard test entrypoints stop relying on a brittle hand-maintained allowlist for the currently covered unit and integration suites, or an explicit documented mechanism exists that prevents silent omission of new tests.
+- [ ] #3 Representative tests that were previously outside the standard lane from src/main/runtime, src/anki-integration, and entry/runtime surfaces are executed by an automated command and included in the documented matrix.
+- [ ] #4 Documentation for contributors explains which command to run for fast verification, full verification, and environment-specific verification.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Inventory the current test surface under src/ and launcher/ and compare it to package.json scripts to classify fast, full, slow, and environment-specific suites.
+2. Replace or reduce the brittle hand-maintained allowlist so new maintained tests do not silently miss the standard matrix.
+3. Update contributor docs with the intended fast/full/environment-specific commands.
+4. Verify the new matrix by running the relevant commands and by demonstrating at least one previously omitted runtime/Anki/entry test now belongs to an automated lane.
+<!-- SECTION:PLAN:END -->
--- a/Subtitle-sync-verification-replace-the-no-op-subtitle-lane-with-real-automated-coverage.md
+++ b/Subtitle-sync-verification-replace-the-no-op-subtitle-lane-with-real-automated-coverage.md
@@ -0,0 +1,53 @@
+---
+id: TASK-87.2
+title: >-
+  Subtitle sync verification: replace the no-op subtitle lane with real
+  automated coverage
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:19'
+updated_date: '2026-03-06 03:21'
+labels:
+  - tests
+  - subsync
+milestone: m-0
+dependencies: []
+references:
+  - package.json
+  - README.md
+  - src/core/services/subsync.ts
+  - src/core/services/subsync.test.ts
+  - src/subsync/utils.ts
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+parent_task_id: TASK-87
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+SubMiner advertises subtitle syncing with alass and ffsubsync, but the dedicated test:subtitle command currently does not run any tests. There is already lower-level coverage in src/core/services/subsync.test.ts, but the test matrix and contributor-facing commands do not reflect that reality. This task should replace the no-op lane with real verification, align scripts with the existing subsync test surface, and make the user-facing docs honest about how subtitle sync is verified.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 The test:subtitle entrypoint runs real automated verification instead of echoing a placeholder message.
+- [ ] #2 The subtitle verification lane covers both alass and ffsubsync behavior, including at least one non-happy-path scenario relevant to current functionality.
+- [ ] #3 Contributor-facing documentation points to the real subtitle verification command and no longer implies a dedicated test lane exists when it does not.
+- [ ] #4 The resulting verification strategy integrates cleanly with the repository-wide test matrix without duplicating or hiding existing subsync coverage.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Audit the existing subtitle-sync test surface, especially src/core/services/subsync.test.ts, and decide whether test:subtitle should reuse or regroup that coverage.
+2. Replace the placeholder script with a real automated command and keep the matrix legible alongside TASK-87.1 work.
+3. Update README or related docs so the advertised subtitle verification path matches reality.
+4. Verify both alass and ffsubsync behavior remain covered by the resulting lane.
+<!-- SECTION:PLAN:END -->
--- a/Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md
+++ b/Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md
@@ -0,0 +1,52 @@
+---
+id: TASK-87.3
+title: >-
+  Immersion tracking verification: make SQLite-backed persistence tests visible
+  and reproducible
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:19'
+updated_date: '2026-03-06 03:21'
+labels:
+  - tests
+  - immersion-tracking
+milestone: m-0
+dependencies: []
+references:
+  - src/core/services/immersion-tracker-service.test.ts
+  - src/core/services/immersion-tracker/storage-session.test.ts
+  - src/core/services/immersion-tracker-service.ts
+  - package.json
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+parent_task_id: TASK-87
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+The immersion tracker is persistence-heavy, but its SQLite-backed tests are conditionally skipped in the standard Bun run when node:sqlite support is unavailable. That creates a blind spot around session finalization, telemetry persistence, and retention behavior. This task should establish a reliable automated verification path for the database-backed cases and make the prerequisite/runtime behavior explicit to contributors and CI.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute.
+- [ ] #2 If the current runtime cannot execute the SQLite-backed tests, the repository exposes that limitation clearly instead of silently reporting a misleading green result.
+- [ ] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on.
+- [ ] #4 The resulting verification covers session persistence or finalization behavior that is not exercised by the pure seam tests alone.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Confirm which SQLite-backed immersion tests are currently skipped and why in the standard Bun environment.
+2. Establish a reproducible command or lane for the DB-backed cases, or make the unsupported-runtime limitation explicit and actionable.
+3. Document prerequisites and expected behavior for contributors and CI.
+4. Verify at least one persistence/finalization path beyond the seam tests is exercised by the new lane.
+<!-- SECTION:PLAN:END -->
--- a/Runtime-composition-root-remove-dead-symbols-and-tighten-module-boundaries-in-src-main.ts.md
+++ b/Runtime-composition-root-remove-dead-symbols-and-tighten-module-boundaries-in-src-main.ts.md
@@ -0,0 +1,53 @@
+---
+id: TASK-87.4
+title: >-
+  Runtime composition root: remove dead symbols and tighten module boundaries in
+  src/main.ts
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:19'
+updated_date: '2026-03-06 03:21'
+labels:
+  - tech-debt
+  - runtime
+  - maintainability
+milestone: m-0
+dependencies:
+  - TASK-87.1
+references:
+  - src/main.ts
+  - src/main/runtime
+  - package.json
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+parent_task_id: TASK-87
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+A noUnusedLocals/noUnusedParameters compile pass reports a large concentration of dead imports and dead locals in src/main.ts. The file is also far beyond the repo’s preferred size guideline, which makes the runtime composition root difficult to review and easy to break. This task should remove confirmed dead symbols, continue extracting coherent slices where that improves readability, and leave the entrypoint materially easier to understand without changing behavior.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 src/main.ts no longer emits dead-symbol diagnostics under a noUnusedLocals/noUnusedParameters compile pass for the areas touched by this cleanup.
+- [ ] #2 Unused imports, destructured values, and stale locals identified in the current composition root are removed or relocated without behavior changes.
+- [ ] #3 The resulting composition root has clearer ownership boundaries for at least one runtime slice that is currently buried in the monolith.
+- [ ] #4 Relevant runtime and startup verification commands pass after the cleanup, and any command changes are documented if needed.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Re-run the noUnusedLocals/noUnusedParameters compile pass and capture the src/main.ts diagnostics cluster before editing.
+2. Remove dead imports, destructured values, and stale locals in small reviewable slices; extract a coherent helper/module only where that materially reduces coupling.
+3. Keep changes behavior-preserving and avoid mixing unrelated cleanup outside src/main.ts unless required to compile.
+4. Verify with the updated runtime/startup test commands from TASK-87.1 plus a noUnused compile pass.
+<!-- SECTION:PLAN:END -->
--- a/Dead-architecture-cleanup-delete-unused-registry-and-pipeline-modules-that-are-off-the-live-path.md
+++ b/Dead-architecture-cleanup-delete-unused-registry-and-pipeline-modules-that-are-off-the-live-path.md
@@ -0,0 +1,57 @@
+---
+id: TASK-87.5
+title: >-
+  Dead architecture cleanup: delete unused registry and pipeline modules that
+  are off the live path
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:20'
+updated_date: '2026-03-06 03:21'
+labels:
+  - tech-debt
+  - dead-code
+milestone: m-0
+dependencies:
+  - TASK-87.1
+  - TASK-87.2
+references:
+  - src/translators/index.ts
+  - src/subsync/engines.ts
+  - src/subtitle/pipeline.ts
+  - src/tokenizers/index.ts
+  - src/token-mergers/index.ts
+  - src/core/services/subsync.ts
+  - src/core/services/tokenizer.ts
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+parent_task_id: TASK-87
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+The review found several modules that appear self-contained but unused from the application’s live execution paths: src/translators/index.ts, src/subsync/engines.ts, src/subtitle/pipeline.ts, src/tokenizers/index.ts, and src/token-mergers/index.ts. At the same time, the real runtime behavior is implemented elsewhere. This task should verify those modules are truly unused, remove or consolidate them, and clean up any stale exports, docs, or tests so contributors are not misled by duplicate architecture.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 Each candidate module identified in the review is either removed as dead code or justified and reconnected to a real supported execution path.
+- [ ] #2 Any stale exports, imports, or tests associated with the removed or consolidated modules are cleaned up so the codebase has a single obvious path for the affected behavior.
+- [ ] #3 The cleanup does not regress live tokenization or subtitle sync behavior and the relevant verification commands remain green.
+- [ ] #4 Contributor-facing documentation or internal notes no longer imply that removed duplicate architecture is part of the current design.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Re-verify each candidate module is off the live path by tracing imports from current runtime entrypoints before deleting anything.
+2. Remove or consolidate truly dead modules and clean associated exports/imports/tests so only the supported path remains obvious.
+3. Pay special attention to subtitle sync and tokenization surfaces, since duplicate architecture exists near active code.
+4. Verify the relevant tokenization and subsync commands/tests still pass and update any stale docs or notes.
+<!-- SECTION:PLAN:END -->
--- a/Anki-integration-maintainability-continue-decomposing-the-oversized-orchestration-layer.md
+++ b/Anki-integration-maintainability-continue-decomposing-the-oversized-orchestration-layer.md
@@ -0,0 +1,57 @@
+---
+id: TASK-87.6
+title: >-
+  Anki integration maintainability: continue decomposing the oversized
+  orchestration layer
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:20'
+updated_date: '2026-03-06 03:21'
+labels:
+  - tech-debt
+  - anki
+  - maintainability
+milestone: m-0
+dependencies:
+  - TASK-87.1
+references:
+  - src/anki-integration.ts
+  - src/anki-integration/field-grouping-workflow.ts
+  - src/anki-integration/note-update-workflow.ts
+  - src/anki-integration/card-creation.ts
+  - src/anki-integration/anki-connect-proxy.ts
+  - src/anki-integration.test.ts
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+  - docs/anki-integration.md
+parent_task_id: TASK-87
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+src/anki-integration.ts remains an oversized orchestration file even after earlier extractions. It still mixes config normalization, polling setup, media generation, duplicate resolution, field grouping workflows, and user feedback coordination in one class. This task should continue the decomposition so the remaining orchestration surface is smaller and easier to reason about, while preserving existing Anki, proxy, field grouping, and note update behavior.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 The responsibilities currently concentrated in src/anki-integration.ts are split into clearer modules or services with narrow ownership boundaries.
+- [ ] #2 The resulting orchestration surface is materially smaller and easier to review, with at least one mixed-responsibility cluster extracted behind a well-named interface.
+- [ ] #3 Existing Anki integration behavior remains covered by automated verification, including note update, field grouping, and proxy-related flows that the refactor touches.
+- [ ] #4 Any developer-facing docs or notes needed to understand the new structure are updated in the same task.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Map the remaining responsibility clusters inside src/anki-integration.ts and choose one or more extraction seams that reduce mixed concerns without changing behavior.
+2. Move logic behind narrow interfaces/modules rather than creating another giant helper; keep orchestration readable.
+3. Preserve coverage for field grouping, note update, proxy, and card creation flows touched by the refactor.
+4. Update docs or internal notes if the new structure changes where contributors should look for a given behavior.
+<!-- SECTION:PLAN:END -->
--- a/Developer-workflow-hygiene-make-docs-watch-reproducible-and-remove-stale-small-surface-drift.md
+++ b/Developer-workflow-hygiene-make-docs-watch-reproducible-and-remove-stale-small-surface-drift.md
@@ -0,0 +1,51 @@
+---
+id: TASK-87.7
+title: >-
+  Developer workflow hygiene: make docs watch reproducible and remove stale
+  small-surface drift
+status: To Do
+assignee: []
+created_date: '2026-03-06 03:20'
+updated_date: '2026-03-06 03:21'
+labels:
+  - tooling
+  - tech-debt
+milestone: m-0
+dependencies: []
+references:
+  - package.json
+  - bun.lock
+  - src/anki-integration/field-grouping-workflow.ts
+documentation:
+  - docs/reports/2026-02-22-task-100-dead-code-report.md
+parent_task_id: TASK-87
+priority: low
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+The review found a few low-risk but recurring hygiene issues: docs:watch depends on bunx concurrently even though concurrently is not declared in package metadata, and small stale API surface remains after recent refactors, such as unused parameters in field-grouping workflow code. This task should make the developer workflow reproducible and clean up low-risk stale symbols that do not warrant a dedicated architecture task.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [ ] #1 The docs:watch workflow runs through declared project tooling or is rewritten to avoid undeclared dependencies.
+- [ ] #2 Small stale symbols or parameters identified during the review outside the main composition-root cleanup are removed without behavior changes.
+- [ ] #3 Any contributor-facing command changes are reflected in repository documentation.
+- [ ] #4 The cleanup remains scoped to low-risk workflow and hygiene fixes rather than expanding into large architectural refactors.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Fix the docs:watch workflow so it relies on declared project tooling or an equivalent checked-in command path.
+2. Clean up low-risk stale symbols surfaced by the review outside the main.ts architecture task, such as unused parameters left behind by refactors.
+3. Keep the task scoped: avoid pulling in main composition-root cleanup or larger Anki/runtime refactors.
+4. Verify the affected developer commands still work and document any usage changes.
+<!-- SECTION:PLAN:END -->
--- a/docs/anki-integration.md
+++ b/docs/anki-integration.md
@@ -44,12 +44,15 @@ Polling mode uses the query `"deck:<your-deck>" added:1` to find recently added

 Then point Yomitan/clients to `http://127.0.0.1:8766` instead of `8765`.

-When SubMiner loads the bundled Yomitan extension, it also attempts to update the **default Yomitan profile** (`profiles[0].options.anki.server`) to the active SubMiner endpoint:
+When SubMiner loads the bundled Yomitan extension, it also attempts to update the **active bundled Yomitan profile** (`profiles[profileCurrent].options.anki.server`) to the active SubMiner endpoint:

 - proxy URL when `ankiConnect.proxy.enabled` is `true`
 - direct `ankiConnect.url` when proxy mode is disabled

-To avoid clobbering custom setups, this auto-update only changes the default profile when its current server is blank or the stock Yomitan default (`http://127.0.0.1:8765`).
+Server update behavior differs by mode:
+
+- Proxy mode (`ankiConnect.proxy.enabled: true`): SubMiner force-syncs the bundled active profile to the proxy URL so `addNote` traffic goes through the local proxy and auto-enrichment can trigger.
+- Direct mode (`ankiConnect.proxy.enabled: false`): SubMiner only replaces blank/default server values (`http://127.0.0.1:8765`) to avoid overwriting custom direct-server setups.

 For browser-based Yomitan or other external clients (for example Texthooker in a normal browser profile), set their Anki server to the same proxy URL separately: `http://127.0.0.1:8766` (or your configured `proxy.host` + `proxy.port`).

@@ -69,7 +72,7 @@ In Yomitan, go to Settings → Profile and:
 3. Set server to `http://127.0.0.1:8766` (or your configured proxy URL).
 4. Save and make that profile active when using SubMiner.

-This is only for non-bundled, external/browser Yomitan or other clients. The bundled profile auto-update logic only targets `profiles[0]` when it is blank or still default.
+This is only for non-bundled, external/browser Yomitan or other clients. Bundled Yomitan profile sync behavior is described above (force-sync in proxy mode, conservative sync in direct mode).

 ### Proxy Troubleshooting (quick checks)

--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -258,8 +258,8 @@ See `config.example.jsonc` for detailed configuration options.
 | `backgroundColor`                  | string      | Any CSS color, including `"transparent"` (default: `"rgb(30, 32, 48, 0.88)"`)                                              |
 | `enableJlpt`                       | boolean     | Enable JLPT level underline styling (`false` by default)                                                                   |
 | `preserveLineBreaks`               | boolean     | Preserve line breaks in visible overlay subtitle rendering (`false` by default). Enable to mirror mpv line layout.         |
-| `autoPauseVideoOnHover`            | boolean     | Pause playback while mouse hovers subtitle text; resume after leaving subtitle area (`true` by default).                    |
-| `autoPauseVideoOnYomitanPopup`     | boolean     | Pause playback while Yomitan popup is open; resume when popup closes (`false` by default).                                   |
+| `autoPauseVideoOnHover`            | boolean     | Pause playback while mouse hovers subtitle text; resume after leaving subtitle area (`true` by default).                   |
+| `autoPauseVideoOnYomitanPopup`     | boolean     | Pause playback while Yomitan popup is open; resume when popup closes (`false` by default).                                 |
 | `hoverTokenColor`                  | string      | Hex color used for hovered subtitle token highlight in mpv (default: catppuccin mauve)                                     |
 | `hoverTokenBackgroundColor`        | string      | CSS color used for hovered subtitle token background highlight (default: semi-transparent dark)                            |
 | `frequencyDictionary.enabled`      | boolean     | Enable frequency highlighting from dictionary lookups (`false` by default)                                                 |
@@ -778,12 +778,12 @@ Sync the active subtitle track using `alass` (preferred) or `ffsubsync`:
 }
 ```

-| Option           | Values               | Description                                                                                                 |
-| ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `defaultMode`    | `"auto"`, `"manual"` | `auto`: try `alass` against secondary subtitle, then fallback to `ffsubsync`; `manual`: open overlay picker |
-| `alass_path`     | string path          | Path to `alass` executable. Empty or `null` falls back to `/usr/bin/alass`.                                 |
-| `ffsubsync_path` | string path          | Path to `ffsubsync` executable. Empty or `null` falls back to `/usr/bin/ffsubsync`.                         |
-| `ffmpeg_path`    | string path          | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.  |
+| Option           | Values               | Description                                                                                                               |
+| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `defaultMode`    | `"auto"`, `"manual"` | `auto`: try `alass` against secondary subtitle, then fallback to `ffsubsync`; `manual`: open overlay picker               |
+| `alass_path`     | string path          | Path to `alass` executable. Empty or `null` falls back to `/usr/bin/alass`.                                               |
+| `ffsubsync_path` | string path          | Path to `ffsubsync` executable. Empty or `null` falls back to `/usr/bin/ffsubsync`.                                       |
+| `ffmpeg_path`    | string path          | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
 | `replace`        | `true`, `false`      | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |

 Default trigger is `Ctrl+Alt+S` via `shortcuts.triggerSubsync`.
--- a/docs/mpv-plugin.md
+++ b/docs/mpv-plugin.md
@@ -120,28 +120,28 @@ aniskip_button_duration=3

 ### Option Reference

-| Option                         | Default                       | Values                                     | Description                                                                      |
-| ------------------------------ | ----------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------- |
-| `binary_path`                  | `""` (auto-detect)            | file path                                  | Path to SubMiner binary                                                          |
-| `socket_path`                  | `/tmp/subminer-socket`        | file path                                  | MPV IPC socket path                                                              |
-| `texthooker_enabled`           | `yes`                         | `yes` / `no`                               | Enable texthooker server                                                         |
-| `texthooker_port`              | `5174`                        | 1–65535                                    | Texthooker server port                                                           |
-| `backend`                      | `auto`                        | `auto`, `hyprland`, `sway`, `x11`, `macos` | Window manager backend                                                           |
-| `auto_start`                   | `yes`                         | `yes` / `no`                               | Auto-start overlay on file load when mpv socket matches `socket_path`            |
-| `auto_start_visible_overlay`   | `yes`                         | `yes` / `no`                               | Show visible layer on auto-start when mpv socket matches `socket_path`           |
-| `auto_start_pause_until_ready` | `yes`                         | `yes` / `no`                               | Pause mpv on visible auto-start; resume when SubMiner signals tokenization-ready |
-| `osd_messages`                 | `yes`                         | `yes` / `no`                               | Show OSD status messages                                                         |
-| `log_level`                    | `info`                        | `debug`, `info`, `warn`, `error`           | Log verbosity                                                                    |
-| `aniskip_enabled`              | `yes`                         | `yes` / `no`                               | Enable AniSkip intro detection                                                   |
-| `aniskip_title`                | `""`                          | string                                     | Override title used for lookup                                                   |
-| `aniskip_season`               | `""`                          | numeric season                             | Optional season hint                                                             |
-| `aniskip_mal_id`               | `""`                          | numeric MAL id                             | Skip title lookup; use fixed id                                                  |
-| `aniskip_episode`              | `""`                          | numeric episode                            | Skip episode parsing; use fixed                                                  |
+| Option                         | Default                       | Values                                     | Description                                                                                |
+| ------------------------------ | ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `binary_path`                  | `""` (auto-detect)            | file path                                  | Path to SubMiner binary                                                                    |
+| `socket_path`                  | `/tmp/subminer-socket`        | file path                                  | MPV IPC socket path                                                                        |
+| `texthooker_enabled`           | `yes`                         | `yes` / `no`                               | Enable texthooker server                                                                   |
+| `texthooker_port`              | `5174`                        | 1–65535                                    | Texthooker server port                                                                     |
+| `backend`                      | `auto`                        | `auto`, `hyprland`, `sway`, `x11`, `macos` | Window manager backend                                                                     |
+| `auto_start`                   | `yes`                         | `yes` / `no`                               | Auto-start overlay on file load when mpv socket matches `socket_path`                      |
+| `auto_start_visible_overlay`   | `yes`                         | `yes` / `no`                               | Show visible layer on auto-start when mpv socket matches `socket_path`                     |
+| `auto_start_pause_until_ready` | `yes`                         | `yes` / `no`                               | Pause mpv on visible auto-start; resume when SubMiner signals tokenization-ready           |
+| `osd_messages`                 | `yes`                         | `yes` / `no`                               | Show OSD status messages                                                                   |
+| `log_level`                    | `info`                        | `debug`, `info`, `warn`, `error`           | Log verbosity                                                                              |
+| `aniskip_enabled`              | `yes`                         | `yes` / `no`                               | Enable AniSkip intro detection                                                             |
+| `aniskip_title`                | `""`                          | string                                     | Override title used for lookup                                                             |
+| `aniskip_season`               | `""`                          | numeric season                             | Optional season hint                                                                       |
+| `aniskip_mal_id`               | `""`                          | numeric MAL id                             | Skip title lookup; use fixed id                                                            |
+| `aniskip_episode`              | `""`                          | numeric episode                            | Skip episode parsing; use fixed                                                            |
 | `aniskip_payload`              | `""`                          | JSON / base64-encoded JSON                 | Optional pre-fetched AniSkip payload for this media. When set, plugin skips network lookup |
-| `aniskip_show_button`          | `yes`                         | `yes` / `no`                               | Show in-range intro skip prompt                                                  |
-| `aniskip_button_text`          | `You can skip by pressing %s` | string                                     | OSD prompt format (`%s`=key)                                                     |
-| `aniskip_button_key`           | `y-k`                         | mpv key chord                              | Primary key for intro skip action (`y-k` always works as fallback)               |
-| `aniskip_button_duration`      | `3`                           | float seconds                              | OSD hint duration                                                                |
+| `aniskip_show_button`          | `yes`                         | `yes` / `no`                               | Show in-range intro skip prompt                                                            |
+| `aniskip_button_text`          | `You can skip by pressing %s` | string                                     | OSD prompt format (`%s`=key)                                                               |
+| `aniskip_button_key`           | `y-k`                         | mpv key chord                              | Primary key for intro skip action (`y-k` always works as fallback)                         |
+| `aniskip_button_duration`      | `3`                           | float seconds                              | OSD hint duration                                                                          |

 ## Binary Auto-Detection

--- a/docs/shortcuts.md
+++ b/docs/shortcuts.md
@@ -62,14 +62,28 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle

 When a Yomitan popup is open, SubMiner also provides popup control shortcuts:

-| Shortcut      | Action                                 |
-| ------------- | -------------------------------------- |
-| `J`           | Scroll definitions down                |
-| `K`           | Scroll definitions up                  |
-| `M`           | Mine/add selected term                 |
-| `P`           | Play selected term audio               |
-| `[`           | Play previous available audio (selected source) |
-| `]`           | Play next available audio (selected source)     |
+| Shortcut    | Action                                          |
+| ----------- | ----------------------------------------------- |
+| `J`         | Scroll definitions down                         |
+| `K`         | Scroll definitions up                           |
+| `ArrowDown` | Scroll definitions down                         |
+| `ArrowUp`   | Scroll definitions up                           |
+| `M`         | Mine/add selected term                          |
+| `P`         | Play selected term audio                        |
+| `[`         | Play previous available audio (selected source) |
+| `]`         | Play next available audio (selected source)     |
+
+## Keyboard-Driven Lookup Mode
+
+These shortcuts are fixed (not configurable) and require overlay focus.
+
+| Shortcut                       | Action                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------- |
+| `Ctrl/Cmd+Shift+Y`             | Toggle keyboard-driven token selection mode on/off                                           |
+| `Ctrl/Cmd+Y`                   | Toggle lookup popup for selected token (open when closed, close when open)                   |
+| `ArrowLeft/Right`, `H`, or `L` | Move selected token (previous/next); if lookup is open, refresh definition for the new token |
+
+Keyboard-driven mode draws a selection outline around the active token. Use `Ctrl/Cmd+Y` to open or close lookup for that token. While the popup is open, popup-local controls still work from the overlay (`J/K`, `ArrowUp/ArrowDown`, `M`, `P`, `[`, `]`) and focus is forced back to the overlay so token navigation can continue without clicking subtitle text again. Moving left/right past the start or end of the line jumps to the previous or next subtitle line and keeps playback paused if it was already paused.

 ## Subtitle & Feature Shortcuts

--- a/docs/usage.md
+++ b/docs/usage.md
@@ -213,7 +213,9 @@ By default, hovering over subtitle text pauses mpv playback. Playback resumes as

 If you want playback to stay paused while a Yomitan popup is open, set `subtitleStyle.autoPauseVideoOnYomitanPopup` to `true`. When enabled, SubMiner auto-resumes on popup close only if SubMiner paused playback for that popup.

-If the Yomitan popup is open, you can control it directly from the overlay: `J/K` scroll definitions, `M` mines/adds the selected term, `P` plays term audio, `[` plays the previous available audio, and `]` plays the next available audio in the selected source.
+Keyboard-driven lookup mode is available with fixed shortcuts: `Ctrl/Cmd+Shift+Y` toggles token-selection mode, `ArrowLeft/Right` (or `H/L`) moves the selected token, and `Ctrl/Cmd+Y` opens or closes lookup for that token.
+
+If the Yomitan popup is open, you can control it directly from the overlay without moving focus into the popup: `J/K` or `ArrowUp/ArrowDown` scroll definitions, `M` mines/adds the selected term, `P` plays term audio, `[` plays the previous available audio, and `]` plays the next available audio in the selected source. While lookup stays open, `ArrowLeft/Right` (or `H/L`) moves to the previous or next token and refreshes the definition for the new token. If you move past the start or end of the current subtitle line, SubMiner jumps to the previous or next subtitle line, moves the selector to the edge token on that line, and keeps playback paused if it was already paused.

 ### Drag-and-drop Queueing

--- a/launcher/aniskip-metadata.test.ts
+++ b/launcher/aniskip-metadata.test.ts
@@ -166,7 +166,9 @@ test('buildSubminerScriptOpts includes aniskip payload fields', () => {
  assert.match(opts, /subminer-aniskip_intro_end=62/);
  assert.match(opts, /subminer-aniskip_lookup_status=ready/);
  assert.ok(payloadMatch !== null);
-  const payload = JSON.parse(decodeURIComponent(payloadMatch[1]));
+  assert.equal(payloadMatch[1].includes('%'), false);
+  const payloadJson = Buffer.from(payloadMatch[1], 'base64url').toString('utf-8');
+  const payload = JSON.parse(payloadJson);
  assert.equal(payload.found, true);
  const first = payload.results?.[0];
  assert.equal(first.skip_type, 'op');
--- a/launcher/aniskip-metadata.ts
+++ b/launcher/aniskip-metadata.ts
@@ -196,7 +196,11 @@ function seasonSignalScore(requestedSeason: number | null, candidateTitle: strin
  } as const;

  const aliases = romanAliases[season] ?? [];
-  return aliases.some((alias) => normalized.includes(alias)) ? 40 : hasAnySequelMarker(candidateTitle) ? -20 : 5;
+  return aliases.some((alias) => normalized.includes(alias))
+    ? 40
+    : hasAnySequelMarker(candidateTitle)
+      ? -20
+      : 5;
 }

 function toMalSearchItems(payload: unknown): MalSearchResult[] {
@@ -230,7 +234,11 @@ function parseAniSkipPayload(payload: unknown): { start: number; end: number } |

  for (const rawResult of results) {
    const result = rawResult as AniSkipSkipItemPayload;
-    if (result.skip_type !== 'op' || typeof result.interval !== 'object' || result.interval === null) {
+    if (
+      result.skip_type !== 'op' ||
+      typeof result.interval !== 'object' ||
+      result.interval === null
+    ) {
      continue;
    }
    const interval = result.interval as AniSkipIntervalPayload;
@@ -287,7 +295,9 @@ async function fetchAniSkipPayload(
  malId: number,
  episode: number,
 ): Promise<{ start: number; end: number } | null> {
-  const payload = await fetchJson<unknown>(`${ANISKIP_PAYLOAD_API}${malId}/${episode}?types=op&types=ed`);
+  const payload = await fetchJson<unknown>(
+    `${ANISKIP_PAYLOAD_API}${malId}/${episode}?types=op&types=ed`,
+  );
  const parsed = payload as AniSkipPayloadResponse;
  if (!parsed || parsed.found !== true) return null;
  return parseAniSkipPayload(parsed);
@@ -532,7 +542,9 @@ function buildLauncherAniSkipPayload(aniSkipMetadata: AniSkipMetadata): string |
      },
    ],
  };
-  return encodeURIComponent(JSON.stringify(payload));
+  // mpv --script-opts treats `%` as an escape prefix, so URL-encoding can break parsing.
+  // Base64url stays script-opts-safe and is decoded by the plugin launcher payload parser.
+  return Buffer.from(JSON.stringify(payload), 'utf-8').toString('base64url');
 }

 export function buildSubminerScriptOpts(
@@ -563,7 +575,9 @@ export function buildSubminerScriptOpts(
    parts.push(`subminer-aniskip_intro_end=${aniSkipMetadata.introEnd}`);
  }
  if (aniSkipMetadata?.lookupStatus) {
-    parts.push(`subminer-aniskip_lookup_status=${sanitizeScriptOptValue(aniSkipMetadata.lookupStatus)}`);
+    parts.push(
+      `subminer-aniskip_lookup_status=${sanitizeScriptOptValue(aniSkipMetadata.lookupStatus)}`,
+    );
  }
  const aniskipPayload = aniSkipMetadata ? buildLauncherAniSkipPayload(aniSkipMetadata) : null;
  if (aniskipPayload) {
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "subminer",
-  "version": "0.2.3",
+  "version": "0.3.0",
  "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
  "packageManager": "bun@1.3.5",
  "main": "dist/main-entry.js",
@@ -23,8 +23,8 @@
    "test:plugin:src": "lua scripts/test-plugin-start-gate.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/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/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/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/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/utils/shortcut-config.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/x11-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.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/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/renderer/error-recovery.test.js dist/renderer/subtitle-render.test.js dist/renderer/handlers/mouse.test.js dist/renderer/modals/jimaku.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/x11-tracker.test.js",
+    "test:core:src": "bun test src/cli/args.test.ts src/cli/help.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/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/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/utils/shortcut-config.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/x11-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.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/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/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/x11-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",
    "test:subtitle:dist": "echo \"Subtitle tests are currently not configured\"",
--- a/plugin/subminer/process.lua
+++ b/plugin/subminer/process.lua
@@ -16,6 +16,7 @@ function M.create(ctx)
 	local subminer_log = ctx.log.subminer_log
 	local show_osd = ctx.log.show_osd
 	local normalize_log_level = ctx.log.normalize_log_level
+	local run_control_command_async

 	local function resolve_visible_overlay_startup()
 		local raw_visible_overlay = opts.auto_start_visible_overlay
@@ -132,6 +133,11 @@ function M.create(ctx)

 	local function notify_auto_play_ready()
 		release_auto_play_ready_gate("tokenization-ready")
+		if state.overlay_running and resolve_visible_overlay_startup() then
+			run_control_command_async("show-visible-overlay", {
+				socket_path = opts.socket_path,
+			})
+		end
 	end

 	local function build_command_args(action, overrides)
@@ -156,22 +162,18 @@ function M.create(ctx)
 			table.insert(args, "--socket")
 			table.insert(args, socket_path)

-			-- Keep auto-start --start requests idempotent for second-instance handling.
-			-- Visibility is applied as a separate control command after startup.
-			if overrides.auto_start_trigger ~= true then
-				local should_show_visible = resolve_visible_overlay_startup()
-				if should_show_visible then
-					table.insert(args, "--show-visible-overlay")
-				else
-					table.insert(args, "--hide-visible-overlay")
-				end
+			local should_show_visible = resolve_visible_overlay_startup()
+			if should_show_visible then
+				table.insert(args, "--show-visible-overlay")
+			else
+				table.insert(args, "--hide-visible-overlay")
 			end
 		end

 		return args
 	end

-	local function run_control_command_async(action, overrides, callback)
+	run_control_command_async = function(action, overrides, callback)
 		local args = build_command_args(action, overrides)
 		subminer_log("debug", "process", "Control command: " .. table.concat(args, " "))
 		mp.command_native_async({
@@ -290,6 +292,7 @@ function M.create(ctx)
 						and "show-visible-overlay"
 					or "hide-visible-overlay"
 				run_control_command_async(visibility_action, {
+					socket_path = socket_path,
 					log_level = overrides.log_level,
 				})
 				return
@@ -360,9 +363,10 @@ function M.create(ctx)
 					local visibility_action = resolve_visible_overlay_startup()
 							and "show-visible-overlay"
 						or "hide-visible-overlay"
-					run_control_command_async(visibility_action, {
-						log_level = overrides.log_level,
-					})
+						run_control_command_async(visibility_action, {
+							socket_path = socket_path,
+							log_level = overrides.log_level,
+						})
 				end

 			end)
--- a/scripts/test-plugin-start-gate.lua
+++ b/scripts/test-plugin-start-gate.lua
@@ -507,12 +507,12 @@ do
 	local start_call = find_start_call(recorded.async_calls)
 	assert_true(start_call ~= nil, "auto-start should issue --start command")
 	assert_true(
-		not call_has_arg(start_call, "--show-visible-overlay"),
-		"auto-start should keep --start command free of --show-visible-overlay"
+		call_has_arg(start_call, "--show-visible-overlay"),
+		"auto-start with visible overlay enabled should include --show-visible-overlay on --start"
 	)
 	assert_true(
 		not call_has_arg(start_call, "--hide-visible-overlay"),
-		"auto-start should keep --start command free of --hide-visible-overlay"
+		"auto-start with visible overlay enabled should not include --hide-visible-overlay on --start"
 	)
 	assert_true(
 		find_control_call(recorded.async_calls, "--show-visible-overlay") ~= nil,
@@ -583,8 +583,8 @@ do
 		"duplicate pause-until-ready auto-start should not issue duplicate --start commands while overlay is already running"
 	)
 	assert_true(
-		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 2,
-		"duplicate pause-until-ready auto-start should still re-assert visible overlay state"
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 4,
+		"duplicate pause-until-ready auto-start should re-assert visible overlay on both start and ready events"
 	)
 	assert_true(
 		count_osd_message(recorded.osd, "SubMiner: Loading subtitle tokenization...") == 2,
@@ -644,6 +644,10 @@ do
 		has_osd_message(recorded.osd, "SubMiner: Subtitle tokenization ready"),
 		"autoplay-ready should show loaded OSD message"
 	)
+	assert_true(
+		count_control_calls(recorded.async_calls, "--show-visible-overlay") == 2,
+		"autoplay-ready should re-assert visible overlay state"
+	)
 	assert_true(
 		#recorded.periodic_timers == 1,
 		"pause-until-ready auto-start should create periodic loading OSD refresher"
@@ -703,12 +707,12 @@ do
 	local start_call = find_start_call(recorded.async_calls)
 	assert_true(start_call ~= nil, "auto-start should issue --start command")
 	assert_true(
-		not call_has_arg(start_call, "--hide-visible-overlay"),
-		"auto-start should keep --start command free of --hide-visible-overlay"
+		call_has_arg(start_call, "--hide-visible-overlay"),
+		"auto-start with visible overlay disabled should include --hide-visible-overlay on --start"
 	)
 	assert_true(
 		not call_has_arg(start_call, "--show-visible-overlay"),
-		"auto-start should keep --start command free of --show-visible-overlay"
+		"auto-start with visible overlay disabled should not include --show-visible-overlay on --start"
 	)
 	assert_true(
 		find_control_call(recorded.async_calls, "--hide-visible-overlay") ~= nil,
--- a/src/config/resolve/subtitle-domains.ts
+++ b/src/config/resolve/subtitle-domains.ts
@@ -174,7 +174,8 @@ export function applySubtitleDomainConfig(context: ResolveContext): void {
    }

    const autoPauseVideoOnYomitanPopup = asBoolean(
-      (src.subtitleStyle as { autoPauseVideoOnYomitanPopup?: unknown }).autoPauseVideoOnYomitanPopup,
+      (src.subtitleStyle as { autoPauseVideoOnYomitanPopup?: unknown })
+        .autoPauseVideoOnYomitanPopup,
    );
    if (autoPauseVideoOnYomitanPopup !== undefined) {
      resolved.subtitleStyle.autoPauseVideoOnYomitanPopup = autoPauseVideoOnYomitanPopup;
--- a/src/core/services/tokenizer.test.ts
+++ b/src/core/services/tokenizer.test.ts
@@ -1171,6 +1171,106 @@ test('tokenizeSubtitle returns null tokens when Yomitan parsing is unavailable',
  assert.deepEqual(result, { text: '猫です', tokens: null });
 });

+test('tokenizeSubtitle skips token payload and annotations when Yomitan parse has no dictionary matches', async () => {
+  let frequencyRequested = false;
+  let jlptLookupCalls = 0;
+  let mecabCalls = 0;
+
+  const result = await tokenizeSubtitle(
+    'これはテスト',
+    makeDeps({
+      getFrequencyDictionaryEnabled: () => true,
+      getYomitanExt: () => ({ id: 'dummy-ext' }) as any,
+      getYomitanParserWindow: () =>
+        ({
+          isDestroyed: () => false,
+          webContents: {
+            executeJavaScript: async (script: string) => {
+              if (script.includes('getTermFrequencies')) {
+                frequencyRequested = true;
+                return [];
+              }
+
+              return [
+                {
+                  source: 'scanning-parser',
+                  index: 0,
+                  content: [
+                    [{ text: 'これは', reading: 'これは' }],
+                    [{ text: 'テスト', reading: 'てすと' }],
+                  ],
+                },
+              ];
+            },
+          },
+        }) as unknown as Electron.BrowserWindow,
+      tokenizeWithMecab: async () => {
+        mecabCalls += 1;
+        return null;
+      },
+      getJlptLevel: () => {
+        jlptLookupCalls += 1;
+        return 'N5';
+      },
+    }),
+  );
+
+  assert.deepEqual(result, { text: 'これはテスト', tokens: null });
+  assert.equal(frequencyRequested, false);
+  assert.equal(jlptLookupCalls, 0);
+  assert.equal(mecabCalls, 0);
+});
+
+test('tokenizeSubtitle excludes Yomitan token groups without dictionary headwords from annotation paths', async () => {
+  let jlptLookupCalls = 0;
+  let frequencyLookupCalls = 0;
+
+  const result = await tokenizeSubtitle(
+    '(ダクネスの荒い息) 猫',
+    makeDeps({
+      getFrequencyDictionaryEnabled: () => true,
+      getYomitanExt: () => ({ id: 'dummy-ext' }) as any,
+      getYomitanParserWindow: () =>
+        ({
+          isDestroyed: () => false,
+          webContents: {
+            executeJavaScript: async (script: string) => {
+              if (script.includes('getTermFrequencies')) {
+                return [];
+              }
+
+              return [
+                {
+                  source: 'scanning-parser',
+                  index: 0,
+                  content: [
+                    [{ text: '(ダクネスの荒い息)', reading: 'だくねすのあらいいき' }],
+                    [{ text: '猫', reading: 'ねこ', headwords: [[{ term: '猫' }]] }],
+                  ],
+                },
+              ];
+            },
+          },
+        }) as unknown as Electron.BrowserWindow,
+      getJlptLevel: (text) => {
+        jlptLookupCalls += 1;
+        return text === '猫' ? 'N5' : null;
+      },
+      getFrequencyRank: () => {
+        frequencyLookupCalls += 1;
+        return 12;
+      },
+      tokenizeWithMecab: async () => null,
+    }),
+  );
+
+  assert.equal(result.tokens?.length, 1);
+  assert.equal(result.tokens?.[0]?.surface, '猫');
+  assert.equal(result.tokens?.[0]?.headword, '猫');
+  assert.equal(jlptLookupCalls, 1);
+  assert.equal(frequencyLookupCalls, 1);
+});
+
 test('tokenizeSubtitle returns null tokens when mecab throws', async () => {
  const result = await tokenizeSubtitle(
    '猫です',
@@ -1184,7 +1284,7 @@ test('tokenizeSubtitle returns null tokens when mecab throws', async () => {
  assert.deepEqual(result, { text: '猫です', tokens: null });
 });

-test('tokenizeSubtitle uses Yomitan parser result when available', async () => {
+test('tokenizeSubtitle uses Yomitan parser result when available and drops no-headword groups', async () => {
  const parserWindow = {
    isDestroyed: () => false,
    webContents: {
@@ -1222,13 +1322,10 @@ test('tokenizeSubtitle uses Yomitan parser result when available', async () => {
  );

  assert.equal(result.text, '猫です');
-  assert.equal(result.tokens?.length, 2);
+  assert.equal(result.tokens?.length, 1);
  assert.equal(result.tokens?.[0]?.surface, '猫');
  assert.equal(result.tokens?.[0]?.reading, 'ねこ');
  assert.equal(result.tokens?.[0]?.isKnown, false);
-  assert.equal(result.tokens?.[1]?.surface, 'です');
-  assert.equal(result.tokens?.[1]?.reading, 'です');
-  assert.equal(result.tokens?.[1]?.isKnown, false);
 });

 test('tokenizeSubtitle logs selected Yomitan groups when debug toggle is enabled', async () => {
--- a/src/core/services/tokenizer/parser-selection-stage.test.ts
+++ b/src/core/services/tokenizer/parser-selection-stage.test.ts
@@ -51,7 +51,7 @@ test('prefers scanning parser when scanning candidate has more than one token',
 test('keeps scanning parser candidate when scanning candidate is single token', () => {
  const parseResults = [
    makeParseItem('scanning-parser', [
-      [{ text: '俺は公園にいきたい', reading: 'おれはこうえんにいきたい' }],
+      [{ text: '俺は公園にいきたい', reading: 'おれはこうえんにいきたい', headword: '行きたい' }],
    ]),
    makeParseItem('mecab', [
      [{ text: '俺', reading: 'おれ', headword: '俺' }],
@@ -96,3 +96,34 @@ test('returns null when only mecab-source candidates are present', () => {
  const tokens = selectYomitanParseTokens(parseResults, () => false, 'headword');
  assert.equal(tokens, null);
 });
+
+test('returns null when scanning parser candidates have no dictionary headwords', () => {
+  const parseResults = [
+    makeParseItem('scanning-parser', [
+      [{ text: 'これは', reading: 'これは' }],
+      [{ text: 'テスト', reading: 'てすと' }],
+    ]),
+  ];
+
+  const tokens = selectYomitanParseTokens(parseResults, () => false, 'headword');
+  assert.equal(tokens, null);
+});
+
+test('drops scanning parser tokens which have no dictionary headword', () => {
+  const parseResults = [
+    makeParseItem('scanning-parser', [
+      [{ text: '(ダクネスの荒い息)', reading: 'だくねすのあらいいき' }],
+      [{ text: 'アクア', reading: 'あくあ', headword: 'アクア' }],
+      [{ text: 'トラウマ', reading: 'とらうま', headword: 'トラウマ' }],
+    ]),
+  ];
+
+  const tokens = selectYomitanParseTokens(parseResults, () => false, 'headword');
+  assert.deepEqual(
+    tokens?.map((token) => ({ surface: token.surface, headword: token.headword })),
+    [
+      { surface: 'アクア', headword: 'アクア' },
+      { surface: 'トラウマ', headword: 'トラウマ' },
+    ],
+  );
+});
--- a/src/core/services/tokenizer/parser-selection-stage.ts
+++ b/src/core/services/tokenizer/parser-selection-stage.ts
@@ -130,6 +130,7 @@ export function mapYomitanParseResultItemToMergedTokens(
  const tokens: MergedToken[] = [];
  let charOffset = 0;
  let validLineCount = 0;
+  let hasDictionaryMatch = false;

  for (const line of content) {
    if (!isYomitanParseLine(line)) {
@@ -163,7 +164,13 @@ export function mapYomitanParseResultItemToMergedTokens(
    const start = charOffset;
    const end = start + combinedSurface.length;
    charOffset = end;
-    const headword = combinedHeadword || combinedSurface;
+    if (!combinedHeadword) {
+      // No dictionary-backed headword for this merged unit; skip it entirely so
+      // downstream keyboard/frequency/JLPT flows only operate on lookup-backed tokens.
+      continue;
+    }
+    hasDictionaryMatch = true;
+    const headword = combinedHeadword;

    tokens.push({
      surface: combinedSurface,
@@ -182,7 +189,7 @@ export function mapYomitanParseResultItemToMergedTokens(
    });
  }

-  if (validLineCount === 0 || tokens.length === 0) {
+  if (validLineCount === 0 || tokens.length === 0 || !hasDictionaryMatch) {
    return null;
  }

--- a/src/main.ts
+++ b/src/main.ts
@@ -871,12 +871,18 @@ function maybeSignalPluginAutoplayReady(
  if (duplicateMediaSignal && !allowDuplicateWhilePaused) {
    return;
  }
-  autoPlayReadySignalMediaPath = mediaPath;
-  const playbackGeneration = ++autoPlayReadySignalGeneration;
  const signalPluginAutoplayReady = (): void => {
    logger.debug(`[autoplay-ready] signaling mpv for media: ${mediaPath}`);
    sendMpvCommandRuntime(appState.mpvClient, ['script-message', 'subminer-autoplay-ready']);
  };
+  if (duplicateMediaSignal && allowDuplicateWhilePaused) {
+    // Keep re-notifying the plugin while paused (for startup visibility sync), but
+    // do not run local unpause fallback on duplicates to avoid resuming user-paused playback.
+    signalPluginAutoplayReady();
+    return;
+  }
+  autoPlayReadySignalMediaPath = mediaPath;
+  const playbackGeneration = ++autoPlayReadySignalGeneration;
  signalPluginAutoplayReady();
  const isPlaybackPaused = async (client: {
    requestProperty: (property: string) => Promise<unknown>;
--- a/src/renderer/handlers/keyboard.test.ts
+++ b/src/renderer/handlers/keyboard.test.ts
@@ -0,0 +1,642 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createKeyboardHandlers } from './keyboard.js';
+import { createRendererState } from '../state.js';
+import { YOMITAN_POPUP_COMMAND_EVENT } from '../yomitan-popup.js';
+
+type CommandEventDetail = {
+  type?: string;
+  visible?: boolean;
+  key?: string;
+  code?: string;
+  repeat?: boolean;
+};
+
+function createClassList() {
+  const classes = new Set<string>();
+  return {
+    add: (...tokens: string[]) => {
+      for (const token of tokens) {
+        classes.add(token);
+      }
+    },
+    remove: (...tokens: string[]) => {
+      for (const token of tokens) {
+        classes.delete(token);
+      }
+    },
+    contains: (token: string) => classes.has(token),
+  };
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function installKeyboardTestGlobals() {
+  const previousWindow = (globalThis as { window?: unknown }).window;
+  const previousDocument = (globalThis as { document?: unknown }).document;
+  const previousMutationObserver = (globalThis as { MutationObserver?: unknown }).MutationObserver;
+  const previousCustomEvent = (globalThis as { CustomEvent?: unknown }).CustomEvent;
+  const previousMouseEvent = (globalThis as { MouseEvent?: unknown }).MouseEvent;
+
+  const documentListeners = new Map<string, Array<(event: unknown) => void>>();
+  const commandEvents: CommandEventDetail[] = [];
+  const mpvCommands: Array<Array<string | number>> = [];
+  let playbackPausedResponse: boolean | null = false;
+
+  let popupVisible = false;
+
+  const popupIframe = {
+    tagName: 'IFRAME',
+    classList: {
+      contains: (token: string) => token === 'yomitan-popup',
+    },
+    id: 'yomitan-popup-1',
+    getBoundingClientRect: () => ({ left: 0, top: 0, width: 100, height: 100 }),
+  };
+
+  const selection = {
+    removeAllRanges: () => {},
+    addRange: () => {},
+  };
+
+  const overlayFocusCalls: Array<{ preventScroll?: boolean }> = [];
+  let focusMainWindowCalls = 0;
+  let windowFocusCalls = 0;
+
+  class TestCustomEvent extends Event {
+    detail: unknown;
+
+    constructor(type: string, init?: { detail?: unknown }) {
+      super(type);
+      this.detail = init?.detail;
+    }
+  }
+
+  class TestMouseEvent extends Event {
+    constructor(type: string) {
+      super(type);
+    }
+  }
+
+  Object.defineProperty(globalThis, 'CustomEvent', {
+    configurable: true,
+    value: TestCustomEvent,
+  });
+
+  Object.defineProperty(globalThis, 'MouseEvent', {
+    configurable: true,
+    value: TestMouseEvent,
+  });
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: {
+      addEventListener: () => {},
+      dispatchEvent: (event: Event) => {
+        if (event.type === YOMITAN_POPUP_COMMAND_EVENT) {
+          const detail = (event as Event & { detail?: CommandEventDetail }).detail;
+          commandEvents.push(detail ?? {});
+        }
+        return true;
+      },
+      getComputedStyle: () => ({
+        visibility: 'visible',
+        display: 'block',
+        opacity: '1',
+      }),
+      getSelection: () => selection,
+      focus: () => {
+        windowFocusCalls += 1;
+      },
+      electronAPI: {
+        getKeybindings: async () => [],
+        sendMpvCommand: (command: Array<string | number>) => {
+          mpvCommands.push(command);
+        },
+        getPlaybackPaused: async () => playbackPausedResponse,
+        toggleDevTools: () => {},
+        focusMainWindow: () => {
+          focusMainWindowCalls += 1;
+          return Promise.resolve();
+        },
+      },
+    },
+  });
+
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: {
+      addEventListener: (type: string, listener: (event: unknown) => void) => {
+        const listeners = documentListeners.get(type) ?? [];
+        listeners.push(listener);
+        documentListeners.set(type, listeners);
+      },
+      querySelectorAll: () => {
+        if (popupVisible) {
+          return [popupIframe];
+        }
+        return [];
+      },
+      createRange: () => ({
+        selectNodeContents: () => {},
+      }),
+      body: {},
+    },
+  });
+
+  Object.defineProperty(globalThis, 'MutationObserver', {
+    configurable: true,
+    value: class {
+      observe() {}
+    },
+  });
+
+  function dispatchKeydown(event: {
+    key: string;
+    code: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+    repeat?: boolean;
+  }): void {
+    const listeners = documentListeners.get('keydown') ?? [];
+    const keyboardEvent = {
+      key: event.key,
+      code: event.code,
+      ctrlKey: event.ctrlKey ?? false,
+      metaKey: event.metaKey ?? false,
+      altKey: event.altKey ?? false,
+      shiftKey: event.shiftKey ?? false,
+      repeat: event.repeat ?? false,
+      preventDefault: () => {},
+      target: null,
+    };
+    for (const listener of listeners) {
+      listener(keyboardEvent);
+    }
+  }
+
+  function dispatchFocusInOnPopup(): void {
+    const listeners = documentListeners.get('focusin') ?? [];
+    const focusEvent = {
+      target: popupIframe,
+    };
+    for (const listener of listeners) {
+      listener(focusEvent);
+    }
+  }
+
+  function restore() {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+    Object.defineProperty(globalThis, 'MutationObserver', {
+      configurable: true,
+      value: previousMutationObserver,
+    });
+    Object.defineProperty(globalThis, 'CustomEvent', {
+      configurable: true,
+      value: previousCustomEvent,
+    });
+    Object.defineProperty(globalThis, 'MouseEvent', {
+      configurable: true,
+      value: previousMouseEvent,
+    });
+  }
+
+  const overlay = {
+    focus: (options?: { preventScroll?: boolean }) => {
+      overlayFocusCalls.push(options ?? {});
+    },
+  };
+
+  return {
+    commandEvents,
+    mpvCommands,
+    overlay,
+    overlayFocusCalls,
+    focusMainWindowCalls: () => focusMainWindowCalls,
+    windowFocusCalls: () => windowFocusCalls,
+    dispatchKeydown,
+    dispatchFocusInOnPopup,
+    setPopupVisible: (value: boolean) => {
+      popupVisible = value;
+    },
+    getPlaybackPaused: async () => playbackPausedResponse,
+    setPlaybackPausedResponse: (value: boolean | null) => {
+      playbackPausedResponse = value;
+    },
+    restore,
+  };
+}
+
+function createKeyboardHandlerHarness() {
+  const testGlobals = installKeyboardTestGlobals();
+  const subtitleRootClassList = createClassList();
+
+  const createWordNode = (left: number) => ({
+    classList: createClassList(),
+    getBoundingClientRect: () => ({ left, top: 10, width: 30, height: 20 }),
+    dispatchEvent: () => true,
+  });
+  let wordNodes = [createWordNode(10), createWordNode(80), createWordNode(150)];
+
+  const ctx = {
+    dom: {
+      subtitleRoot: {
+        classList: subtitleRootClassList,
+        querySelectorAll: () => wordNodes,
+      },
+      subtitleContainer: {
+        contains: () => false,
+      },
+      overlay: testGlobals.overlay,
+    },
+    platform: {
+      shouldToggleMouseIgnore: false,
+      isMacOSPlatform: false,
+      overlayLayer: 'always-on-top',
+    },
+    state: createRendererState(),
+  };
+
+  const handlers = createKeyboardHandlers(ctx as never, {
+    handleRuntimeOptionsKeydown: () => false,
+    handleSubsyncKeydown: () => false,
+    handleKikuKeydown: () => false,
+    handleJimakuKeydown: () => false,
+    handleSessionHelpKeydown: () => false,
+    openSessionHelpModal: () => {},
+    appendClipboardVideoToQueue: () => {},
+    getPlaybackPaused: () => testGlobals.getPlaybackPaused(),
+  });
+
+  return {
+    ctx,
+    handlers,
+    testGlobals,
+    setWordCount: (count: number) => {
+      wordNodes = Array.from({ length: count }, (_, index) => createWordNode(10 + index * 70));
+    },
+  };
+}
+
+test('keyboard mode: left and right move token selection while popup remains open', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    ctx.state.keyboardSelectedWordIndex = 1;
+    ctx.state.yomitanPopupVisible = true;
+    testGlobals.setPopupVisible(true);
+
+    testGlobals.dispatchKeydown({ key: 'ArrowRight', code: 'ArrowRight' });
+    assert.equal(ctx.state.keyboardSelectedWordIndex, 2);
+
+    testGlobals.dispatchKeydown({ key: 'ArrowLeft', code: 'ArrowLeft' });
+    assert.equal(ctx.state.keyboardSelectedWordIndex, 1);
+    await wait(0);
+
+    const closeEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'setVisible' && event.visible === false,
+    );
+    assert.equal(closeEvents.length, 0);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: up/down/j/k do not open or close lookup when popup is closed', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    testGlobals.dispatchKeydown({ key: 'ArrowUp', code: 'ArrowUp' });
+    testGlobals.dispatchKeydown({ key: 'ArrowDown', code: 'ArrowDown' });
+    testGlobals.dispatchKeydown({ key: 'j', code: 'KeyJ' });
+    testGlobals.dispatchKeydown({ key: 'k', code: 'KeyK' });
+
+    await wait(0);
+
+    const openEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'scanSelectedText',
+    );
+    assert.equal(openEvents.length, 0);
+    const closeEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'setVisible' && event.visible === false,
+    );
+    assert.equal(closeEvents.length, 0);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: up/down/j/k forward keydown to yomitan popup when open', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    ctx.state.yomitanPopupVisible = true;
+    testGlobals.setPopupVisible(true);
+
+    testGlobals.dispatchKeydown({ key: 'ArrowUp', code: 'ArrowUp' });
+    testGlobals.dispatchKeydown({ key: 'ArrowDown', code: 'ArrowDown' });
+    testGlobals.dispatchKeydown({ key: 'j', code: 'KeyJ' });
+    testGlobals.dispatchKeydown({ key: 'k', code: 'KeyK' });
+
+    const forwarded = testGlobals.commandEvents.filter((event) => event.type === 'forwardKeyDown');
+    assert.equal(forwarded.length, 4);
+    assert.equal(
+      forwarded.some((event) => event.code === 'ArrowUp'),
+      true,
+    );
+    assert.equal(
+      forwarded.some((event) => event.code === 'ArrowDown'),
+      true,
+    );
+    assert.equal(
+      forwarded.some((event) => event.code === 'KeyJ'),
+      true,
+    );
+    assert.equal(
+      forwarded.some((event) => event.code === 'KeyK'),
+      true,
+    );
+
+    const openEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'scanSelectedText',
+    );
+    assert.equal(openEvents.length, 0);
+    const closeEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'setVisible' && event.visible === false,
+    );
+    assert.equal(closeEvents.length, 0);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: repeated popup navigation keys are forwarded while popup is open', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    ctx.state.yomitanPopupVisible = true;
+    testGlobals.setPopupVisible(true);
+
+    testGlobals.dispatchKeydown({ key: 'j', code: 'KeyJ', repeat: true });
+    testGlobals.dispatchKeydown({ key: 'ArrowDown', code: 'ArrowDown', repeat: true });
+
+    const forwarded = testGlobals.commandEvents.filter((event) => event.type === 'forwardKeyDown');
+    assert.equal(forwarded.length, 2);
+    assert.deepEqual(
+      forwarded.map((event) => ({ code: event.code, repeat: event.repeat })),
+      [
+        { code: 'KeyJ', repeat: true },
+        { code: 'ArrowDown', repeat: true },
+      ],
+    );
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: h moves left when popup is closed', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    ctx.state.keyboardSelectedWordIndex = 2;
+    ctx.state.yomitanPopupVisible = false;
+    testGlobals.setPopupVisible(false);
+
+    testGlobals.dispatchKeydown({ key: 'h', code: 'KeyH' });
+    assert.equal(ctx.state.keyboardSelectedWordIndex, 1);
+
+    const closeEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'setVisible' && event.visible === false,
+    );
+    assert.equal(closeEvents.length, 0);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: h moves left while popup is open and keeps lookup active', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    ctx.state.keyboardSelectedWordIndex = 2;
+    ctx.state.yomitanPopupVisible = true;
+    testGlobals.setPopupVisible(true);
+
+    testGlobals.dispatchKeydown({ key: 'h', code: 'KeyH' });
+    await wait(80);
+
+    assert.equal(ctx.state.keyboardSelectedWordIndex, 1);
+    const openEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'scanSelectedText',
+    );
+    assert.equal(openEvents.length > 0, true);
+    const closeEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'setVisible' && event.visible === false,
+    );
+    assert.equal(closeEvents.length, 0);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: opening lookup restores overlay keyboard focus', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    testGlobals.dispatchKeydown({ key: 'y', code: 'KeyY', ctrlKey: true });
+    await wait(0);
+
+    assert.equal(testGlobals.focusMainWindowCalls() > 0, true);
+    assert.equal(testGlobals.windowFocusCalls() > 0, true);
+    assert.equal(testGlobals.overlayFocusCalls.length > 0, true);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: moving right beyond end jumps next subtitle and resets selector to start', async () => {
+  const { ctx, handlers, testGlobals, setWordCount } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    setWordCount(3);
+    ctx.state.keyboardSelectedWordIndex = 2;
+    handlers.syncKeyboardTokenSelection();
+
+    testGlobals.dispatchKeydown({ key: 'ArrowRight', code: 'ArrowRight' });
+    await wait(0);
+    assert.deepEqual(testGlobals.mpvCommands.at(-1), ['sub-seek', 1]);
+
+    setWordCount(2);
+    handlers.syncKeyboardTokenSelection();
+    assert.equal(ctx.state.keyboardSelectedWordIndex, 0);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: moving left beyond start jumps previous subtitle and sets selector to end', async () => {
+  const { ctx, handlers, testGlobals, setWordCount } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    setWordCount(3);
+    ctx.state.keyboardSelectedWordIndex = 0;
+    handlers.syncKeyboardTokenSelection();
+
+    testGlobals.dispatchKeydown({ key: 'ArrowLeft', code: 'ArrowLeft' });
+    await wait(0);
+    assert.deepEqual(testGlobals.mpvCommands.at(-1), ['sub-seek', -1]);
+
+    setWordCount(4);
+    handlers.syncKeyboardTokenSelection();
+    assert.equal(ctx.state.keyboardSelectedWordIndex, 3);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: popup-open edge jump refreshes lookup on the new subtitle selection', async () => {
+  const { ctx, handlers, testGlobals, setWordCount } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    setWordCount(2);
+    ctx.state.keyboardSelectedWordIndex = 1;
+    ctx.state.yomitanPopupVisible = true;
+    testGlobals.setPopupVisible(true);
+    handlers.syncKeyboardTokenSelection();
+
+    testGlobals.dispatchKeydown({ key: 'ArrowRight', code: 'ArrowRight' });
+    await wait(0);
+    assert.deepEqual(testGlobals.mpvCommands.at(-1), ['sub-seek', 1]);
+
+    setWordCount(3);
+    handlers.syncKeyboardTokenSelection();
+    await wait(80);
+
+    assert.equal(ctx.state.keyboardSelectedWordIndex, 0);
+    const openEvents = testGlobals.commandEvents.filter(
+      (event) => event.type === 'scanSelectedText',
+    );
+    assert.equal(openEvents.length > 0, true);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: edge jump while paused re-applies paused state after subtitle seek', async () => {
+  const { ctx, handlers, testGlobals, setWordCount } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    setWordCount(2);
+    ctx.state.keyboardSelectedWordIndex = 1;
+    handlers.syncKeyboardTokenSelection();
+    testGlobals.setPlaybackPausedResponse(true);
+
+    testGlobals.dispatchKeydown({ key: 'ArrowRight', code: 'ArrowRight' });
+    await wait(0);
+
+    assert.deepEqual(testGlobals.mpvCommands.slice(-2), [
+      ['sub-seek', 1],
+      ['set_property', 'pause', 'yes'],
+    ]);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: edge jump with unknown pause state re-applies pause conservatively', async () => {
+  const { ctx, handlers, testGlobals, setWordCount } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+
+    setWordCount(2);
+    ctx.state.keyboardSelectedWordIndex = 1;
+    handlers.syncKeyboardTokenSelection();
+    testGlobals.setPlaybackPausedResponse(null);
+
+    testGlobals.dispatchKeydown({ key: 'ArrowRight', code: 'ArrowRight' });
+    await wait(0);
+
+    assert.deepEqual(testGlobals.mpvCommands.slice(-2), [
+      ['sub-seek', 1],
+      ['set_property', 'pause', 'yes'],
+    ]);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
+
+test('keyboard mode: popup iframe focusin reclaims overlay keyboard focus', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.handleKeyboardModeToggleRequested();
+    testGlobals.setPopupVisible(true);
+
+    const before = testGlobals.focusMainWindowCalls();
+    testGlobals.dispatchFocusInOnPopup();
+    await wait(260);
+
+    assert.equal(testGlobals.focusMainWindowCalls() > before, true);
+    assert.equal(testGlobals.windowFocusCalls() > 0, true);
+    assert.equal(testGlobals.overlayFocusCalls.length > 0, true);
+  } finally {
+    ctx.state.keyboardDrivenModeEnabled = false;
+    testGlobals.restore();
+  }
+});
--- a/src/renderer/handlers/keyboard.ts
+++ b/src/renderer/handlers/keyboard.ts
@@ -2,6 +2,7 @@ import type { Keybinding } from '../../types';
 import type { RendererContext } from '../context';
 import {
  YOMITAN_POPUP_HIDDEN_EVENT,
+  YOMITAN_POPUP_SHOWN_EVENT,
  YOMITAN_POPUP_COMMAND_EVENT,
  isYomitanPopupVisible,
  isYomitanPopupIframe,
@@ -21,11 +22,14 @@ export function createKeyboardHandlers(
      fallbackUnavailable: boolean;
    }) => void;
    appendClipboardVideoToQueue: () => void;
+    getPlaybackPaused: () => Promise<boolean | null>;
  },
 ) {
  // Timeout for the modal chord capture window (e.g. Y followed by H/K).
  const CHORD_TIMEOUT_MS = 1000;
  const KEYBOARD_SELECTED_WORD_CLASS = 'keyboard-selected';
+  let pendingSelectionAnchorAfterSubtitleSeek: 'start' | 'end' | null = null;
+  let pendingLookupRefreshAfterSubtitleSeek = false;

  const CHORD_MAP = new Map<
    string,
@@ -126,7 +130,9 @@ export function createKeyboardHandlers(
  }

  function getSubtitleWordNodes(): HTMLElement[] {
-    return Array.from(ctx.dom.subtitleRoot.querySelectorAll<HTMLElement>('.word[data-token-index]'));
+    return Array.from(
+      ctx.dom.subtitleRoot.querySelectorAll<HTMLElement>('.word[data-token-index]'),
+    );
  }

  function syncKeyboardTokenSelection(): void {
@@ -137,9 +143,28 @@ export function createKeyboardHandlers(

    if (!ctx.state.keyboardDrivenModeEnabled || wordNodes.length === 0) {
      ctx.state.keyboardSelectedWordIndex = null;
+      if (!ctx.state.keyboardDrivenModeEnabled) {
+        pendingSelectionAnchorAfterSubtitleSeek = null;
+        pendingLookupRefreshAfterSubtitleSeek = false;
+      }
      return;
    }

+    if (pendingSelectionAnchorAfterSubtitleSeek) {
+      ctx.state.keyboardSelectedWordIndex =
+        pendingSelectionAnchorAfterSubtitleSeek === 'start' ? 0 : wordNodes.length - 1;
+      pendingSelectionAnchorAfterSubtitleSeek = null;
+      const shouldRefreshLookup =
+        pendingLookupRefreshAfterSubtitleSeek &&
+        (ctx.state.yomitanPopupVisible || isYomitanPopupVisible(document));
+      pendingLookupRefreshAfterSubtitleSeek = false;
+      if (shouldRefreshLookup) {
+        queueMicrotask(() => {
+          triggerLookupForSelectedWord();
+        });
+      }
+    }
+
    const selectedIndex = Math.min(
      Math.max(ctx.state.keyboardSelectedWordIndex ?? 0, 0),
      wordNodes.length - 1,
@@ -155,6 +180,8 @@ export function createKeyboardHandlers(
    ctx.state.keyboardDrivenModeEnabled = enabled;
    if (!enabled) {
      ctx.state.keyboardSelectedWordIndex = null;
+      pendingSelectionAnchorAfterSubtitleSeek = null;
+      pendingLookupRefreshAfterSubtitleSeek = false;
    }
    syncKeyboardTokenSelection();
  }
@@ -163,19 +190,47 @@ export function createKeyboardHandlers(
    setKeyboardDrivenModeEnabled(!ctx.state.keyboardDrivenModeEnabled);
  }

-  function moveKeyboardSelection(delta: -1 | 1): boolean {
+  function moveKeyboardSelection(
+    delta: -1 | 1,
+  ): 'moved' | 'start-boundary' | 'end-boundary' | 'no-words' {
    const wordNodes = getSubtitleWordNodes();
    if (wordNodes.length === 0) {
      ctx.state.keyboardSelectedWordIndex = null;
      syncKeyboardTokenSelection();
-      return true;
+      return 'no-words';
    }

-    const currentIndex = ctx.state.keyboardSelectedWordIndex ?? 0;
-    const nextIndex = Math.min(Math.max(currentIndex + delta, 0), wordNodes.length - 1);
+    const currentIndex = Math.min(
+      Math.max(ctx.state.keyboardSelectedWordIndex ?? 0, 0),
+      wordNodes.length - 1,
+    );
+    if (delta < 0 && currentIndex <= 0) {
+      return 'start-boundary';
+    }
+    if (delta > 0 && currentIndex >= wordNodes.length - 1) {
+      return 'end-boundary';
+    }
+
+    const nextIndex = currentIndex + delta;
    ctx.state.keyboardSelectedWordIndex = nextIndex;
    syncKeyboardTokenSelection();
-    return true;
+    return 'moved';
+  }
+
+  function seekAdjacentSubtitleAndQueueSelection(delta: -1 | 1, popupVisible: boolean): void {
+    pendingSelectionAnchorAfterSubtitleSeek = delta > 0 ? 'start' : 'end';
+    pendingLookupRefreshAfterSubtitleSeek = popupVisible;
+    void options
+      .getPlaybackPaused()
+      .then((paused) => {
+        window.electronAPI.sendMpvCommand(['sub-seek', delta]);
+        if (paused !== false) {
+          window.electronAPI.sendMpvCommand(['set_property', 'pause', 'yes']);
+        }
+      })
+      .catch(() => {
+        window.electronAPI.sendMpvCommand(['sub-seek', delta]);
+      });
  }

  type ScanModifierState = {
@@ -269,6 +324,13 @@ export function createKeyboardHandlers(
    const clientY = rect.top + rect.height / 2;

    dispatchYomitanFrontendScanSelectedText();
+    if (ctx.state.keyboardDrivenModeEnabled) {
+      // Keep overlay as the keyboard focus owner so token navigation can continue
+      // while the popup is visible.
+      queueMicrotask(() => {
+        scheduleOverlayFocusReclaim(8);
+      });
+    }
    // Fallback only if the explicit scan path did not open popup quickly.
    setTimeout(() => {
      if (ctx.state.yomitanPopupVisible || isYomitanPopupVisible(document)) {
@@ -304,23 +366,90 @@ export function createKeyboardHandlers(
    ctx.dom.overlay.focus({ preventScroll: true });
  }

+  function scheduleOverlayFocusReclaim(attempts: number = 0): void {
+    if (!ctx.state.keyboardDrivenModeEnabled) {
+      return;
+    }
+    restoreOverlayKeyboardFocus();
+    if (attempts <= 0) {
+      return;
+    }
+
+    let remaining = attempts;
+    const reclaim = () => {
+      if (!ctx.state.keyboardDrivenModeEnabled) {
+        return;
+      }
+      if (!ctx.state.yomitanPopupVisible && !isYomitanPopupVisible(document)) {
+        return;
+      }
+      restoreOverlayKeyboardFocus();
+      remaining -= 1;
+      if (remaining > 0) {
+        setTimeout(reclaim, 25);
+      }
+    };
+
+    setTimeout(reclaim, 25);
+  }
+
  function handleKeyboardDrivenModeNavigation(e: KeyboardEvent): boolean {
    if (e.ctrlKey || e.metaKey || e.altKey || e.shiftKey) {
      return false;
    }

    const key = e.code;
-    if (key === 'ArrowLeft' || key === 'ArrowUp' || key === 'KeyH' || key === 'KeyK') {
-      return moveKeyboardSelection(-1);
+    if (key === 'ArrowLeft') {
+      const result = moveKeyboardSelection(-1);
+      if (result === 'start-boundary') {
+        seekAdjacentSubtitleAndQueueSelection(-1, false);
+      }
+      return result !== 'no-words';
    }
-    if (key === 'ArrowRight' || key === 'ArrowDown' || key === 'KeyL' || key === 'KeyJ') {
-      return moveKeyboardSelection(1);
+    if (key === 'ArrowRight' || key === 'KeyL') {
+      const result = moveKeyboardSelection(1);
+      if (result === 'end-boundary') {
+        seekAdjacentSubtitleAndQueueSelection(1, false);
+      }
+      return result !== 'no-words';
    }
    return false;
  }

+  function handleKeyboardDrivenModeLookupControls(e: KeyboardEvent): boolean {
+    if (!ctx.state.keyboardDrivenModeEnabled) {
+      return false;
+    }
+    if (e.ctrlKey || e.metaKey || e.altKey || e.shiftKey) {
+      return false;
+    }
+
+    const key = e.code;
+    const popupVisible = ctx.state.yomitanPopupVisible || isYomitanPopupVisible(document);
+    if (key === 'ArrowLeft' || key === 'KeyH') {
+      const result = moveKeyboardSelection(-1);
+      if (result === 'start-boundary') {
+        seekAdjacentSubtitleAndQueueSelection(-1, popupVisible);
+      } else if (popupVisible && result === 'moved') {
+        triggerLookupForSelectedWord();
+      }
+      return true;
+    }
+
+    if (key === 'ArrowRight' || key === 'KeyL') {
+      const result = moveKeyboardSelection(1);
+      if (result === 'end-boundary') {
+        seekAdjacentSubtitleAndQueueSelection(1, popupVisible);
+      } else if (popupVisible && result === 'moved') {
+        triggerLookupForSelectedWord();
+      }
+      return true;
+    }
+
+    return false;
+  }
+
  function handleYomitanPopupKeybind(e: KeyboardEvent): boolean {
-    if (e.repeat) return false;
    const modifierOnlyCodes = new Set([
      'ShiftLeft',
      'ShiftRight',
@@ -334,6 +463,7 @@ export function createKeyboardHandlers(
    if (modifierOnlyCodes.has(e.code)) return false;

    if (!e.ctrlKey && !e.metaKey && !e.altKey && e.code === 'KeyM') {
+      if (e.repeat) return false;
      dispatchYomitanPopupMineSelected();
      return true;
    }
@@ -415,6 +545,35 @@ export function createKeyboardHandlers(
      }
      restoreOverlayKeyboardFocus();
    });
+    window.addEventListener(YOMITAN_POPUP_SHOWN_EVENT, () => {
+      if (!ctx.state.keyboardDrivenModeEnabled) {
+        return;
+      }
+      queueMicrotask(() => {
+        scheduleOverlayFocusReclaim(8);
+      });
+    });
+
+    document.addEventListener(
+      'focusin',
+      (e: FocusEvent) => {
+        if (!ctx.state.keyboardDrivenModeEnabled) {
+          return;
+        }
+        const target = e.target;
+        if (
+          target &&
+          typeof target === 'object' &&
+          'tagName' in target &&
+          isYomitanPopupIframe(target as Element)
+        ) {
+          queueMicrotask(() => {
+            scheduleOverlayFocusReclaim(8);
+          });
+        }
+      },
+      true,
+    );

    document.addEventListener('keydown', (e: KeyboardEvent) => {
      if (isKeyboardDrivenModeToggle(e)) {
@@ -429,6 +588,11 @@ export function createKeyboardHandlers(
        return;
      }

+      if (handleKeyboardDrivenModeLookupControls(e)) {
+        e.preventDefault();
+        return;
+      }
+
      if (ctx.state.yomitanPopupVisible || isYomitanPopupVisible(document)) {
        if (handleYomitanPopupKeybind(e)) {
          e.preventDefault();
--- a/src/renderer/handlers/mouse.test.ts
+++ b/src/renderer/handlers/mouse.test.ts
@@ -2,10 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';

 import { createMouseHandlers } from './mouse.js';
-import {
-  YOMITAN_POPUP_HIDDEN_EVENT,
-  YOMITAN_POPUP_SHOWN_EVENT,
-} from '../yomitan-popup.js';
+import { YOMITAN_POPUP_HIDDEN_EVENT, YOMITAN_POPUP_SHOWN_EVENT } from '../yomitan-popup.js';

 function createClassList() {
  const classes = new Set<string>();
--- a/src/renderer/renderer.ts
+++ b/src/renderer/renderer.ts
@@ -114,6 +114,7 @@ const keyboardHandlers = createKeyboardHandlers(ctx, {
  appendClipboardVideoToQueue: () => {
    void window.electronAPI.appendClipboardVideoToQueue();
  },
+  getPlaybackPaused: () => window.electronAPI.getPlaybackPaused(),
 });
 const mouseHandlers = createMouseHandlers(ctx, {
  modalStateReader: { isAnySettingsModalOpen, isAnyModalOpen },
--- a/vendor/yomitan/js/display/popup-main.js
+++ b/vendor/yomitan/js/display/popup-main.js
@@ -48,7 +48,7 @@ await Application.main(true, async (application) => {
    displayResizer.prepare();

    document.addEventListener('keydown', (event) => {
-        if (event.defaultPrevented || event.repeat) { return; }
+        if (event.defaultPrevented) { return; }
        if (event.ctrlKey || event.metaKey || event.altKey) { return; }

        const target = /** @type {?Element} */ (event.target instanceof Element ? event.target : null);
@@ -59,29 +59,40 @@ await Application.main(true, async (application) => {
        }

        const code = event.code;
-        if (code === 'KeyJ' || code === 'KeyK') {
+        const isPopupScrollKey =
+            code === 'KeyJ' ||
+            code === 'KeyK' ||
+            code === 'ArrowDown' ||
+            code === 'ArrowUp';
+        if (isPopupScrollKey) {
            const scanningOptions = display.getOptions()?.scanning;
            const scale = Number.isFinite(scanningOptions?.reducedMotionScrollingScale)
                ? scanningOptions.reducedMotionScrollingScale
                : 1;
-            display._scrollByPopupHeight(code === 'KeyJ' ? 1 : -1, scale);
+            display._scrollByPopupHeight(
+                code === 'KeyJ' || code === 'ArrowDown' ? 1 : -1,
+                scale,
+            );
            event.preventDefault();
            return;
        }

        if (code === 'KeyM') {
+            if (event.repeat) { return; }
            displayAnki._hotkeySaveAnkiNoteForSelectedEntry('0');
            event.preventDefault();
            return;
        }

        if (code === 'KeyP') {
+            if (event.repeat) { return; }
            void displayAudio.playAudio(display.selectedIndex, 0);
            event.preventDefault();
            return;
        }

        if (code === 'BracketLeft' || code === 'BracketRight') {
+            if (event.repeat) { return; }
            displayAudio._onMessageCycleAudioSource({direction: code === 'BracketLeft' ? 1 : -1});
            event.preventDefault();
        }
Author	SHA1	Message	Date
sudacode	2f07c3407a	chore: bump version to 0.3.0	2026-03-05 20:21:03 -08:00
sudacode	a5554ec530	docs: capture anki proxy notes and codebase health backlog	2026-03-05 20:14:58 -08:00
sudacode	f9f2fe6e87	docs: update keyboard-driven yomitan workflow	2026-03-05 20:13:38 -08:00
sudacode	8ca05859a9	fix: support repeated popup scroll keys	2026-03-05 19:20:55 -08:00
sudacode	0cac446725	fix: preserve keyboard subtitle navigation state	2026-03-05 18:39:40 -08:00
sudacode	23623ad1e1	docs(backlog): add keyboard-driven yomitan task record	2026-03-05 01:29:13 -08:00
sudacode	b623c5e160	fix: improve yomitan keyboard navigation and payload handling	2026-03-05 01:28:54 -08:00