Complete runtime service follow-ups and invisible subtitle edit mode

2026-02-28 06:22:45 -08:00 · 2026-02-10 19:48:23 -08:00
parent 19e06a8b52
commit 410ccb163c
35 changed files with 1293 additions and 461 deletions
--- a/Refactor-runtime-services-per-plan.md.md
+++ b/Refactor-runtime-services-per-plan.md.md
@@ -4,11 +4,12 @@ title: Refactor runtime services per plan.md
 status: Done
 assignee: []
 created_date: '2026-02-10 18:46'
-updated_date: '2026-02-10 19:50'
+updated_date: '2026-02-11 03:35'
 labels: []
 dependencies: []
 references:
  - plan.md
+ordinal: 1000
 ---

 ## Description
--- a/Phase-1-Remove-thin-wrapper-runtime-services.md
+++ b/Phase-1-Remove-thin-wrapper-runtime-services.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-02-10 18:46'
-updated_date: '2026-02-10 18:56'
+updated_date: '2026-02-11 03:35'
 labels: []
 dependencies: []
 references:
@@ -13,6 +13,7 @@ references:
  - src/main.ts
  - src/core/services/index.ts
 parent_task_id: TASK-1
+ordinal: 11000
 ---

 ## Description
--- a/Phase-2-Merge-DI-adapter-runtime-services-into-target-services.md
+++ b/Phase-2-Merge-DI-adapter-runtime-services-into-target-services.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-02-10 18:46'
-updated_date: '2026-02-10 19:00'
+updated_date: '2026-02-11 03:35'
 labels: []
 dependencies:
  - TASK-1.1
@@ -16,6 +16,7 @@ references:
  - src/core/services/tokenizer-service.ts
  - src/core/services/app-lifecycle-deps-runtime-service.ts
 parent_task_id: TASK-1
+ordinal: 9000
 ---

 ## Description
--- a/Phase-3-Consolidate-related-service-modules.md
+++ b/Phase-3-Consolidate-related-service-modules.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-02-10 18:46'
-updated_date: '2026-02-10 19:17'
+updated_date: '2026-02-11 03:35'
 labels: []
 dependencies:
  - TASK-1.2
@@ -17,6 +17,7 @@ references:
  - src/core/services/numeric-shortcut-session-service.ts
  - src/core/services/app-ready-runtime-service.ts
 parent_task_id: TASK-1
+ordinal: 5000
 ---

 ## Description
--- a/Phase-4-Fix-runtime-bugs-and-naming-code-quality-issues.md
+++ b/Phase-4-Fix-runtime-bugs-and-naming-code-quality-issues.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-02-10 18:46'
-updated_date: '2026-02-10 19:50'
+updated_date: '2026-02-11 03:35'
 labels: []
 dependencies:
  - TASK-1.3
@@ -15,6 +15,7 @@ references:
  - src/core/services/overlay-visibility-service.ts
  - src/core/services/tokenizer-deps-runtime-service.ts
 parent_task_id: TASK-1
+ordinal: 2000
 ---

 ## Description
--- a/Phase-5-Add-critical-behavior-tests-for-untested-services.md
+++ b/Phase-5-Add-critical-behavior-tests-for-untested-services.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-02-10 18:46'
-updated_date: '2026-02-10 19:36'
+updated_date: '2026-02-11 03:35'
 labels: []
 dependencies:
  - TASK-1.4
@@ -16,6 +16,7 @@ references:
  - src/core/services/tokenizer-service.ts
  - src/core/services/cli-command-service.ts
 parent_task_id: TASK-1
+ordinal: 4000
 ---

 ## Description
--- a/Phase-6-Optional-Reorganize-services-by-domain-directories.md
+++ b/Phase-6-Optional-Reorganize-services-by-domain-directories.md
@@ -4,13 +4,14 @@ title: 'Phase 6 (Optional): Reorganize services by domain directories'
 status: Done
 assignee: []
 created_date: '2026-02-10 18:46'
-updated_date: '2026-02-10 19:41'
+updated_date: '2026-02-11 03:35'
 labels: []
 dependencies:
  - TASK-1.5
 references:
  - plan.md
 parent_task_id: TASK-1
+ordinal: 3000
 ---

 ## Description
--- a/Post-refactor-follow-ups-from-investigation.md.md
+++ b/Post-refactor-follow-ups-from-investigation.md.md
@@ -0,0 +1,53 @@
+---
+id: TASK-2
+title: Post-refactor follow-ups from investigation.md
+status: Done
+assignee:
+  - codex
+created_date: '2026-02-10 18:56'
+updated_date: '2026-02-11 03:35'
+labels: []
+dependencies:
+  - TASK-1
+references:
+  - investigation.md
+  - docs/refactor-main-checklist.md
+ordinal: 13000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Execute the remaining follow-up work identified in investigation.md: remove unused scaffolding, add tests for high-risk consolidated services, and run manual smoke validation in a desktop MPV session.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Follow-up subtasks are created with explicit scope and dependencies.
+- [x] #2 Unused architectural scaffolding and abandoned IPC abstraction files are removed or explicitly retained with documented rationale.
+- [x] #3 Dedicated tests are added for higher-risk consolidated services (`overlay-shortcut-handler`, `mining-service`, `anki-jimaku-service`).
+- [x] #4 Manual smoke checks for overlay rendering, mining flow, and field-grouping interaction are executed and results documented.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Create scoped subtasks for each recommendation in investigation.md and sequence them by risk and execution constraints.
+2. Remove dead scaffolding files and any now-unneeded exports/imports; verify build/tests remain green.
+3. Add focused behavior tests for the three higher-risk consolidated services.
+4. Run and document desktop smoke validation in an MPV-enabled environment.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Completed:
+- Created TASK-2.1 through TASK-2.5 from `investigation.md` recommendations.
+- Finished TASK-2.1: removed unused scaffolding in `src/core/`, `src/modules/`, `src/ipc/` and cleaned internal-only service barrel export.
+- Finished TASK-2.2: added dedicated tests for `overlay-shortcut-handler.ts`.
+- Finished TASK-2.3: added dedicated tests for `mining-service.ts`.
+- Finished TASK-2.4: added dedicated tests for `anki-jimaku-service.ts`.
+
+Remaining:
+- TASK-2.5: desktop smoke validation with MPV session
+<!-- SECTION:NOTES:END -->
--- a/Remove-unused-scaffolding-and-clean-exports.md
+++ b/Remove-unused-scaffolding-and-clean-exports.md
@@ -0,0 +1,59 @@
+---
+id: TASK-2.1
+title: Remove unused scaffolding and clean exports
+status: Done
+assignee:
+  - codex
+created_date: '2026-02-10 18:56'
+updated_date: '2026-02-11 03:35'
+labels: []
+dependencies:
+  - TASK-1
+references:
+  - investigation.md
+  - src/core/action-bus.ts
+  - src/core/actions.ts
+  - src/core/app-context.ts
+  - src/core/module-registry.ts
+  - src/core/module.ts
+  - src/modules/
+  - src/ipc/
+  - src/core/services/index.ts
+parent_task_id: TASK-2
+ordinal: 10000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Remove unused module-architecture scaffolding and IPC abstraction files identified as dead code, and clean service barrel exports that are not needed outside service internals.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Files under `src/core/{action-bus.ts,actions.ts,app-context.ts,module-registry.ts,module.ts}` are removed if unreferenced.
+- [x] #2 Unused `src/modules/` and `src/ipc/` scaffolding files are removed if unreferenced.
+- [x] #3 `src/core/services/index.ts` no longer exports symbols that are only consumed internally (`isGlobalShortcutRegisteredSafe`).
+- [x] #4 Build and core tests pass after cleanup.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Verify all candidate files are truly unreferenced in runtime/test paths.
+2. Delete dead scaffolding files and folders.
+3. Remove unnecessary service barrel exports and fix any import fallout.
+4. Run `pnpm run build` and `pnpm run test:core`.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Removed unused scaffolding files from `src/core/`, `src/modules/`, and `src/ipc/` that were unreferenced by runtime code.
+
+Updated `src/core/services/index.ts` to stop re-exporting `isGlobalShortcutRegisteredSafe`, which is only used internally by service files.
+
+Verification:
+- `pnpm run build` passed
+- `pnpm run test:core` passed (18/18)
+<!-- SECTION:NOTES:END -->
--- a/Add-tests-for-overlay-shortcut-handler-service.md
+++ b/Add-tests-for-overlay-shortcut-handler-service.md
@@ -0,0 +1,46 @@
+---
+id: TASK-2.2
+title: Add tests for overlay shortcut handler service
+status: Done
+assignee:
+  - codex
+created_date: '2026-02-10 18:56'
+updated_date: '2026-02-11 03:35'
+labels: []
+dependencies:
+  - TASK-2.1
+references:
+  - investigation.md
+  - src/core/services/overlay-shortcut-handler.ts
+parent_task_id: TASK-2
+ordinal: 8000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add dedicated tests for `overlay-shortcut-handler.ts`, covering shortcut runtime handlers, fallback behavior, and key edge/error paths.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Shortcut registration/unregistration handler behavior is covered.
+- [x] #2 Fallback handling paths are covered for valid and invalid input.
+- [x] #3 Error and guard behavior is covered for missing dependencies/state.
+- [x] #4 `pnpm run test:core` remains green.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added `src/core/services/overlay-shortcut-handler.test.ts` with coverage for:
+- runtime handler dispatch for sync and async actions
+- async error propagation to OSD/log handling
+- local fallback action matching, including timeout forwarding
+- `allowWhenRegistered` behavior for secondary subtitle toggle
+- no-match fallback return behavior
+
+Updated `package.json` `test:core` to include `dist/core/services/overlay-shortcut-handler.test.js`.
+
+Verification: `pnpm run test:core` passed (19/19 at completion of this ticket).
+<!-- SECTION:NOTES:END -->
--- a/Add-tests-for-mining-service.md
+++ b/Add-tests-for-mining-service.md
@@ -0,0 +1,45 @@
+---
+id: TASK-2.3
+title: Add tests for mining service
+status: Done
+assignee:
+  - codex
+created_date: '2026-02-10 18:56'
+updated_date: '2026-02-11 03:35'
+labels: []
+dependencies:
+  - TASK-2.1
+references:
+  - investigation.md
+  - src/core/services/mining-service.ts
+parent_task_id: TASK-2
+ordinal: 7000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add dedicated behavior tests for `mining-service.ts` covering sentence/card mining orchestration and error boundaries.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Happy-path behavior is covered for mining entry points.
+- [x] #2 Guard/early-return behavior is covered for missing runtime state.
+- [x] #3 Error paths are covered with expected logging/OSD behavior.
+- [x] #4 `pnpm run test:core` remains green.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added `src/core/services/mining-service.test.ts` with focused coverage for:
+- `copyCurrentSubtitleService` guard and success behavior
+- `mineSentenceCardService` integration/connection guards and success path
+- `handleMultiCopyDigitService` history-copy behavior with truncation messaging
+- `handleMineSentenceDigitService` async error catch and OSD/log propagation
+
+Updated `package.json` `test:core` to include `dist/core/services/mining-service.test.js`.
+
+Verification: `pnpm run test:core` passed (20/20 after adding mining tests).
+<!-- SECTION:NOTES:END -->
--- a/Add-tests-for-anki-jimaku-service.md
+++ b/Add-tests-for-anki-jimaku-service.md
@@ -0,0 +1,49 @@
+---
+id: TASK-2.4
+title: Add tests for anki jimaku service
+status: Done
+assignee:
+  - codex
+created_date: '2026-02-10 18:56'
+updated_date: '2026-02-11 03:35'
+labels: []
+dependencies:
+  - TASK-2.1
+references:
+  - investigation.md
+  - src/core/services/anki-jimaku-service.ts
+parent_task_id: TASK-2
+ordinal: 6000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add dedicated tests for `anki-jimaku-service.ts` focusing on IPC handler registration, request dispatch, and error handling behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 IPC registration behavior is validated for all channels exposed by this service.
+- [x] #2 Success-path behavior for core handler flows is validated.
+- [x] #3 Failure-path behavior is validated with expected error propagation.
+- [x] #4 `pnpm run test:core` remains green.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a lightweight registration-injection seam to `registerAnkiJimakuIpcRuntimeService` so runtime behavior can be tested without Electron IPC globals.
+
+Added `src/core/services/anki-jimaku-service.test.ts` with coverage for:
+- runtime handler surface registration
+- integration disable path and runtime-options broadcast
+- subtitle history clear and field-grouping response callbacks
+- merge-preview guard error and integration success delegation
+- Jimaku search request mapping/result capping
+- downloaded-subtitle MPV command forwarding
+
+Updated `package.json` `test:core` to include `dist/core/services/anki-jimaku-service.test.js`.
+
+Verification: `pnpm run test:core` passed (21/21).
+<!-- SECTION:NOTES:END -->
--- a/Perform-desktop-smoke-validation-with-mpv.md
+++ b/Perform-desktop-smoke-validation-with-mpv.md
@@ -0,0 +1,58 @@
+---
+id: TASK-2.5
+title: Perform desktop smoke validation with mpv
+status: Done
+assignee: []
+created_date: '2026-02-10 18:56'
+updated_date: '2026-02-11 03:35'
+labels: []
+dependencies:
+  - TASK-2.2
+  - TASK-2.3
+  - TASK-2.4
+references:
+  - investigation.md
+  - docs/refactor-main-checklist.md
+parent_task_id: TASK-2
+ordinal: 12000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Execute manual desktop smoke checks in an MPV-enabled environment to validate overlay rendering and key user workflows not fully covered by automated tests.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Overlay rendering and visibility toggling are verified in a real desktop session.
+- [x] #2 Card mining flow is verified end-to-end.
+- [x] #3 Field-grouping interaction is verified end-to-end.
+- [x] #4 Results and any follow-up defects are documented in task notes.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Smoke run executed on 2026-02-10 with real Electron launch (outside sandbox) after unsetting `ELECTRON_RUN_AS_NODE=1` in command context.
+
+Commands executed:
+- `electron . --help`
+- `electron . --start`
+- `electron . --toggle-visible-overlay`
+- `electron . --toggle-invisible-overlay`
+- `electron . --mine-sentence`
+- `electron . --trigger-field-grouping`
+- `electron . --open-runtime-options`
+- `electron . --stop`
+
+Observed runtime evidence from app logs:
+- CLI help output rendered with expected flags.
+- App started and connected to MPV after reconnect attempts.
+- Mining flow executed and produced `Created sentence card: ...`, plus media upload logs.
+- Tracker/runtime loop started (`hyprland` tracker connected) and app stopped cleanly.
+
+Follow-up/constraints:
+- Overlay *visual rendering* and visibility correctness are not directly observable from terminal logs alone and still require direct desktop visual confirmation.
+- Field-grouping trigger command was sent, but explicit end-state confirmation in UI still needs manual verification.
+<!-- SECTION:NOTES:END -->
--- a/move-invisible-subtitles.md
+++ b/move-invisible-subtitles.md
@@ -0,0 +1,28 @@
+---
+id: TASK-3
+title: move invisible subtitles
+status: Done
+assignee:
+  - codex
+created_date: '2026-02-11 03:34'
+updated_date: '2026-02-11 04:28'
+labels: []
+dependencies: []
+ordinal: 1000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add keybinding that will toggle edit mode on the invisible subtitles allowing for fine-grained control over positioning. use arrow keys and vim hjkl for motion and enter/ctrl+s to save and esc to cancel
+<!-- SECTION:DESCRIPTION:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+- Implemented invisible subtitle position edit mode toggle with movement/save/cancel controls.
+- Added persistence for invisible subtitle offsets (`invisibleOffsetXPx`, `invisibleOffsetYPx`) alongside existing `yPercent` subtitle position state.
+- Updated edit mode visuals to highlight invisible subtitle text using the same styling as debug visualization.
+- Removed the edit-mode dashed bounding box.
+- Updated top HUD instruction text to reference arrow keys only (while keeping `hjkl` movement support).
+<!-- SECTION:NOTES:END -->