sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-03-26 00:26:05 -07:00
Code Issues Packages Projects Releases Wiki Activity

chore(backlog): complete backlog cleanup

Browse Source
This commit is contained in:
Kyle Yasuda
2026-03-25 22:42:21 -07:00
parent 23c54bb01e
commit 508864bcbb
105 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
backlog/tasks/task-100 - Add-configurable-texthooker-startup-launch.md
View File

@@ -1,42 +0,0 @@
---
id: TASK-100
title: Add configurable texthooker startup launch
status: Done
assignee: []
created_date: '2026-03-06 23:30'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
priority: medium
ordinal: 11010
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add a config option under `texthooker` to launch the built-in texthooker server automatically when SubMiner starts.
Scope:
- Add `texthooker.launchAtStartup`.
- Default to `true`.
- Start the existing texthooker server during normal app startup when enabled.
- Keep `texthooker.openBrowser` as separate behavior.
- Add regression coverage and update generated config docs/example.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Default config enables automatic texthooker startup.
- [x] #2 Config parser accepts valid boolean values and warns on invalid values.
- [x] #3 App-ready startup launches texthooker when enabled.
- [x] #4 Generated config template/example documents the new option.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added `texthooker.launchAtStartup` with a default of `true`, wired it through config defaults/validation/template generation, and started the existing texthooker server during app-ready startup without coupling it to browser auto-open behavior.
Also added regression coverage for config parsing/template output and app-ready dependency wiring, then regenerated the checked-in config example artifacts.
<!-- SECTION:FINAL_SUMMARY:END -->

40
backlog/tasks/task-101 - Index-AniList-character-alternative-names-in-the-character-dictionary.md
View File

@@ -1,40 +0,0 @@
---
id: TASK-101
title: Index AniList character alternative names in the character dictionary
status: Done
assignee: []
created_date: '2026-03-07 00:00'
updated_date: '2026-03-16 05:13'
labels:
- dictionary
- anilist
dependencies: []
references:
- src/main/character-dictionary-runtime.ts
- src/main/character-dictionary-runtime.test.ts
priority: high
ordinal: 71500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Index AniList character alternative names in generated character dictionaries so aliases like Shadow resolve during subtitle lookup instead of falling through to unrelated generic dictionary entries.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Character fetch reads AniList alternative character names needed for lookup coverage
- [x] #2 Generated term banks include alias-derived terms for subtitle lookups like シャドウ
- [x] #3 Regression coverage proves alternative-name indexing works end to end
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Character dictionary generation now requests AniList `name.alternative`, indexes those aliases as term candidates, and expands mixed aliases like `Minoru Kagenou (影野ミノル)` into usable outer/inner variants. Also extended kana alias synthesis so the AniList alias `Shadow` emits `シャドウ`, which matches the subtitle token the user hit in The Eminence in Shadow.
Bumped the character-dictionary snapshot format to invalidate stale cached snapshots, and updated merged-dictionary rebuilds to refresh invalid snapshots before composing the ZIP so old cache files do not hard-fail the merge path.
Verified with `bun test src/main/character-dictionary-runtime.test.ts` and `bun run tsc --noEmit`.
<!-- SECTION:FINAL_SUMMARY:END -->

65
backlog/tasks/task-102 - Quiet-default-AppImage-startup-and-implicit-background-launch.md
View File

@@ -1,65 +0,0 @@
---
id: TASK-102
title: Quiet default AppImage startup and implicit background launch
status: Done
assignee:
- codex
created_date: '2026-03-06 21:20'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/main-entry-runtime.ts
- /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts
- /home/sudacode/projects/japanese/SubMiner/src/main.ts
priority: medium
ordinal: 77500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Make the packaged Linux no-arg launch path behave like a quiet background start instead of surfacing startup-only noise.
Scope:
- Treat default background entry launches as implicit `--start --background`.
- Keep the `--password-store` diagnostic out of normal startup output.
- Suppress known startup-only `node:sqlite` and `lsfg-vk` warnings for the entry/background launch path.
- Avoid noisy protocol-registration warnings during normal startup when registration is unsupported.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Initial background launch reaches the start path without logging `No running instance. Use --start to launch the app.`
- [x] #2 Default startup no longer emits the `Applied --password-store gnome-libsecret` line at normal log levels.
- [x] #3 Entry/background launch sanitization suppresses the observed `ExperimentalWarning: SQLite...` and `lsfg-vk ... unsupported configuration version` startup noise.
- [x] #4 Regression coverage documents the new startup behavior.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Normalized no-arg/password-store-only entry launches to append implicit `--start --background`, and upgraded `--background`-only entry launches to include `--start`.
Applied shared entry env sanitization before loading the main process so default startup strips the `lsfg-vk` Vulkan layer and sets `NODE_NO_WARNINGS=1`; background children keep the same sanitized env.
Downgraded startup-only protocol-registration failure logging to debug, and routed the Linux password-store diagnostic through the scoped debug logger instead of raw console output.
Verification:
- `bun test src/main-entry-runtime.test.ts src/main/runtime/anilist-setup-protocol.test.ts src/main/runtime/anilist-setup-protocol-main-deps.test.ts`
- `bun run test:fast`
Note: the final `node --experimental-sqlite --test dist/main/runtime/registry.test.js` step in `bun run test:fast` still prints Node's own experimental SQLite warning because that test command explicitly enables the feature flag outside the app entrypoint.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Default packaged startup is now quiet and behaves like an implicit `--start --background` launch.
- No-arg AppImage entry launches now append `--start --background`, and `--background`-only launches append the missing `--start`.
- Entry/background startup sanitization now suppresses the observed `lsfg-vk` and `node:sqlite` warnings on the app launch path.
- Linux password-store and unsupported protocol-registration diagnostics now stay at debug level instead of normal startup output.
<!-- SECTION:FINAL_SUMMARY:END -->

38
backlog/tasks/task-103 - Add-dedicated-annotation-websocket-for-texthooker.md
View File

@@ -1,38 +0,0 @@
---
id: TASK-103
title: Add dedicated annotation websocket for texthooker
status: Done
assignee:
- codex
created_date: '2026-03-07 02:20'
updated_date: '2026-03-16 05:13'
labels:
- texthooker
- websocket
- subtitle
dependencies: []
priority: medium
ordinal: 73500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add a separate annotated subtitle websocket for bundled texthooker so token/JLPT/frequency markup is available on a stable dedicated port even when the regular websocket is in `auto` mode and skipped because `mpv_websocket` is installed.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Regular `websocket.enabled: "auto"` behavior remains unchanged and still skips the regular websocket when `mpv_websocket` is installed.
- [x] #2 A separate `annotationWebsocket` config controls an independent annotated websocket with default port `6678`.
- [x] #3 Bundled texthooker is pointed at the annotation websocket when it is enabled.
- [x] #4 Focused regression tests cover config parsing, startup wiring, and texthooker bootstrap injection.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added `annotationWebsocket.enabled`/`annotationWebsocket.port` with defaults of `true`/`6678`, started that websocket independently from the regular auto-managed websocket, and injected the bundled texthooker websocket URL so it connects to the annotation feed by default.
Also added focused regression coverage and regenerated the checked-in config examples.
<!-- SECTION:FINAL_SUMMARY:END -->

45
backlog/tasks/task-104 - Mirror-overlay-annotation-hover-behavior-in-vendored-texthooker.md
View File

@@ -1,45 +0,0 @@
---
id: TASK-104
title: Mirror overlay annotation hover behavior in vendored texthooker
status: Done
assignee:
- codex
created_date: '2026-03-06 21:45'
updated_date: '2026-03-16 05:13'
labels:
- texthooker
- subtitle
- websocket
dependencies:
- TASK-103
references:
- /home/sudacode/projects/japanese/SubMiner/src/core/services/subtitle-ws.ts
- >-
/home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/components/App.svelte
- >-
/home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/line-markup.ts
- /home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/app.css
priority: medium
ordinal: 76500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Bring bundled texthooker annotation rendering closer to the visible overlay. Keep the lightweight texthooker UX, but preserve token metadata for hover, match overlay color-precedence rules across known/N+1/name/frequency/JLPT, expose name-match highlighting as a toggle, and emit a structured annotation payload on the dedicated websocket so non-SubMiner clients can treat it as an API.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Annotation websocket payload includes both rendered `sentence` HTML and structured token metadata for generic clients.
- [x] #2 Vendored texthooker preserves annotation metadata attrs needed for hover labels and uses overlay-matching color precedence rules.
- [x] #3 Vendored texthooker supports character-name highlighting with a user-facing toggle and standalone-web note.
- [x] #4 Hovering annotated texthooker tokens reveals JLPT/frequency metadata without adding the full overlay popup workflow.
- [x] #5 Focused serializer, texthooker markup, socket parsing, CSS, and build verification pass.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Extended the dedicated annotation websocket payload to ship `version`, plain `text`, rendered `sentence`, and structured `tokens` metadata while keeping backward-compatible `sentence` consumers working. Updated the vendored texthooker to preserve hover metadata attrs, follow overlay color precedence for known/N+1/name/frequency/JLPT annotations, add a character-name highlight toggle plus standalone-web dictionary note, and render lightweight hover labels for frequency/JLPT metadata. Added focused regression coverage and rebuilt both the vendored texthooker bundle and SubMiner.
<!-- SECTION:FINAL_SUMMARY:END -->

40
backlog/tasks/task-105 - Stop-local-docs-artifact-writes-after-docs-repo-split.md
View File

@@ -1,40 +0,0 @@
---
id: TASK-105
title: Stop local docs artifact writes after docs repo split
status: Done
assignee: []
created_date: '2026-03-07 00:00'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
priority: medium
ordinal: 12010
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Now that user-facing docs live in `../subminer-docs`, first-party scripts in this repo should not keep writing generated artifacts into the local `docs/` tree.
Scope:
- Audit first-party scripts/automation for writes to `docs/`.
- Keep repo-local outputs only where they are still intentionally owned by this repo.
- Repoint generated docs artifacts to `../subminer-docs` when that is the maintained source of truth.
- Add regression coverage for the config-example generation path contract.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The config-example generator no longer writes to `docs/public/config.example.jsonc` inside this repo.
- [x] #2 When `../subminer-docs` exists, the generator updates `../subminer-docs/public/config.example.jsonc`.
- [x] #3 Automated coverage guards the output-path contract so local docs writes do not regress.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Removed the first-party local `docs/public` config-example write path from `src/generate-config-example.ts` and replaced it with sibling-docs-repo detection that targets `../subminer-docs/public/config.example.jsonc` only when that repo exists.
Added a project-local regression suite for output-path resolution and artifact writing, wired that suite into the maintained config test lane, and removed the stale generated `docs/public/config.example.jsonc` artifact from the working tree.
<!-- SECTION:FINAL_SUMMARY:END -->

71
backlog/tasks/task-106 - Add-first-run-setup-gate-and-auto-install-flow.md
View File

@@ -1,71 +0,0 @@
---
id: TASK-106
title: Add first-run setup gate and auto-install flow
status: Done
assignee:
- codex
created_date: '2026-03-07 06:10'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/main.ts
- /home/sudacode/projects/japanese/SubMiner/src/shared/setup-state.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/first-run-setup-service.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/first-run-setup-window.ts
- >-
/home/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
priority: high
ordinal: 13010
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Replace the current manual install flow with a first-run setup gate:
- bootstrap the default config dir/config file automatically
- detect legacy installs and mark them complete when config + Yomitan dictionaries are already present
- open a compact Catppuccin Macchiato setup popup for incomplete installs
- optionally install the mpv plugin into the default mpv location
- block launcher playback until setup completes, then resume the original playback flow
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 First app launch seeds the default config dir/config file without manual copy steps.
- [x] #2 Existing installs with config plus at least one Yomitan dictionary are auto-detected as already complete.
- [x] #3 Incomplete installs get a first-run setup popup with mpv plugin install, Yomitan settings, refresh, skip, and finish actions.
- [x] #4 Launcher playback waits for setup completion and does not start mpv while setup is incomplete.
- [x] #5 Plugin assets are packaged into the Electron bundle and regression tests cover the new flow.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added shared setup-state/config/mpv path helpers so Electron and launcher read the same onboarding state file.
Introduced a first-run setup service plus compact BrowserWindow popup using Catppuccin Macchiato styling. The popup supports optional mpv plugin install, opening Yomitan settings, status refresh, skip-plugin, and gated finish once at least one Yomitan dictionary is installed.
Electron startup now bootstraps a default config file, auto-detects legacy-complete installs, adds `--setup` CLI support, exposes a tray `Complete Setup` action while incomplete, and avoids reopening setup once completion is recorded.
Launcher playback now checks the shared setup-state file before starting mpv. If setup is incomplete, it launches the app with `--background --setup`, waits for completion, and only then proceeds.
Verification:
- `bun run typecheck`
- `bun run test:fast`
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
SubMiner now supports a download-and-launch install flow.
- First launch auto-creates config and opens setup only when needed.
- Existing users with working installs are silently migrated to completed setup.
- The setup popup handles optional mpv plugin install and Yomitan dictionary readiness.
- Launcher playback is gated on setup completion and resumes automatically afterward.
<!-- SECTION:FINAL_SUMMARY:END -->

44
backlog/tasks/task-110 - Replace-vendored-Yomitan-with-submodule-built-Chrome-artifact-workflow.md
View File

@@ -1,44 +0,0 @@
---
id: TASK-110
title: Replace vendored Yomitan with submodule-built Chrome artifact workflow
status: Done
assignee: []
created_date: '2026-03-07 11:05'
updated_date: '2026-03-16 05:13'
labels:
- yomitan
- build
- release
dependencies: []
priority: high
ordinal: 10010
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Replace the checked-in `vendor/yomitan` release tree with a `subminer-yomitan` git submodule. Build Yomitan from source, extract the Chromium zip artifact into a stable local build directory, and make SubMiner dev/runtime/tests/release packaging load that extracted extension instead of the source tree or vendored files.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Repo tracks Yomitan as a git submodule instead of committed extension files under `vendor/yomitan`.
- [x] #2 SubMiner has a reproducible build/extract step that produces a local Chromium extension directory from `subminer-yomitan`.
- [x] #3 Dev/runtime/tests resolve the extracted build output as the default Yomitan extension path.
- [x] #4 Release packaging includes the extracted Chromium extension files instead of the old vendored tree.
- [x] #5 Docs and verification commands reflect the new workflow.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Replaced the checked-in `vendor/yomitan` extension tree with a `vendor/subminer-yomitan` git submodule and added a reproducible `bun run build:yomitan` workflow that builds `yomitan-chrome.zip`, extracts it into `build/yomitan`, and reuses a source-state stamp to skip redundant rebuilds. Runtime path resolution, helper CLIs, Yomitan integration tests, packaging, CI cache keys, and README source-build notes now all target that generated artifact instead of the old vendored files.
Verification:
- `bun run build:yomitan`
- `bun test src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-structured-content-generator.test.ts src/yomitan-translator-sort.test.ts`
- `bun run typecheck`
- `bun run build`
- `bun run test:core:src`
<!-- SECTION:FINAL_SUMMARY:END -->

72
backlog/tasks/task-111 - Fix-subtitle-cycle-OSD-labels-for-J-keybindings.md
View File

@@ -1,72 +0,0 @@
---
id: TASK-111
title: Fix subtitle-cycle OSD labels for J keybindings
status: Done
assignee:
- Codex
created_date: '2026-03-07 23:45'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/src/core/services/ipc-command.ts
- /Users/sudacode/projects/japanese/SubMiner/src/core/services/mpv.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/ipc-command.test.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/mpv-control.test.ts
ordinal: 72500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
When cycling subtitle tracks with the default J/Shift+J keybindings, the mpv OSD currently shows raw template text like `${sid}` instead of a resolved subtitle label. Update the keybinding OSD behavior so users see the active subtitle selection clearly when cycling tracks, and ensure placeholder-based OSD messages sent through the mpv client API render correctly.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Pressing the primary subtitle cycle keybinding shows a resolved subtitle label on the OSD instead of a raw `${sid}` placeholder.
- [x] #2 Pressing the secondary subtitle cycle keybinding shows a resolved subtitle label on the OSD instead of a raw `${secondary-sid}` placeholder.
- [x] #3 Proxy OSD messages that rely on mpv property expansion render resolved values when sent through the mpv client API.
- [x] #4 Regression tests cover the subtitle-cycle OSD behavior and the placeholder-expansion OSD path.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add focused failing tests for subtitle-cycle OSD labels and mpv placeholder-expansion behavior.
2. Update the IPC mpv command handler to resolve primary and secondary subtitle track labels from mpv `track-list` data after cycling subtitle tracks.
3. Update the mpv OSD runtime path so placeholder-based `show-text` messages sent through the client API opt into property expansion.
4. Run focused tests, then the relevant core test lane, and record results in the task notes.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Initial triage: `ipc-command.ts` emits raw `${sid}`/`${secondary-sid}` placeholder strings, and `showMpvOsdRuntime` sends `show-text` via mpv client API without enabling property expansion.
User approved implementation plan on 2026-03-07.
Implementation: proxy mpv command OSD now supports an async resolver so subtitle track cycling can show human-readable labels instead of raw `${sid}` placeholders.
Implementation: `showMpvOsdRuntime` now prefixes placeholder-based messages with mpv client-api `expand-properties`, which fixes raw `${...}` OSD output for subtitle delay/position messages.
Testing: `bun test src/core/services/ipc-command.test.ts src/core/services/mpv-control.test.ts src/main/runtime/mpv-proxy-osd.test.ts src/main/runtime/ipc-mpv-command-main-deps.test.ts src/main/runtime/ipc-bridge-actions.test.ts src/main/runtime/ipc-bridge-actions-main-deps.test.ts src/main/runtime/composers/ipc-runtime-composer.test.ts` passed.
Testing: `bun x tsc --noEmit` passed.
Testing: `bun run test:core:src` passed (423 pass, 6 skip, 0 fail).
Docs: no update required because no checked-in docs or help text describe the J/Shift+J OSD output behavior.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed subtitle-cycle OSD handling for the default J/Shift+J keybindings. The IPC mpv command path now supports resolving proxy OSD text asynchronously, and the main-runtime resolver reads mpv `track-list` state so primary and secondary subtitle cycling show human-readable track labels instead of raw `${sid}` / `${secondary-sid}` placeholders.
Also fixed the lower-level mpv OSD transport so placeholder-based `show-text` messages sent through the client API opt into `expand-properties`. That preserves existing template-based OSD messages like subtitle delay and subtitle position without leaking the raw `${...}` syntax.
Added regression coverage for the async proxy OSD path, the placeholder-expansion `showMpvOsdRuntime` path, and the runtime subtitle-track label resolver. Verification run: `bun x tsc --noEmit`; focused mpv/IPC tests; and the maintained `bun run test:core:src` lane (423 pass, 6 skip, 0 fail).
<!-- SECTION:FINAL_SUMMARY:END -->

62
backlog/tasks/task-112 - Address-Claude-review-items-on-PR-15.md
View File

@@ -1,62 +0,0 @@
---
id: TASK-112
title: Address Claude review items on PR 15
status: Done
assignee:
- codex
created_date: '2026-03-08 00:11'
updated_date: '2026-03-16 05:13'
labels:
- pr-review
- ci
dependencies: []
references:
- .github/workflows/release.yml
- .github/workflows/ci.yml
- .gitmodules
- >-
backlog/tasks/task-101 -
Index-AniList-character-alternative-names-in-the-character-dictionary.md
priority: medium
ordinal: 70500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Review Claude's PR feedback on PR #15, implement only the technically valid fixes on the current branch, and document which comments are non-actionable or already acceptable.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Validated Claude's concrete PR review items against current branch state and repo conventions
- [x] #2 Implemented the accepted fixes with regression coverage or verification where applicable
- [x] #3 Documented which review items are non-blocking or intentionally left unchanged
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Validate each Claude review item against current branch files and repo workflow.
2. Patch release quality-gate to match CI ordering and add explicit typecheck.
3. Remove duplicate .gitmodules stanza and normalize the TASK-101 reference path through Backlog MCP.
4. Run relevant verification for workflow/config metadata changes and record which review items remain non-actionable.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
User asked to address Claude PR comments on PR #15 and assess whether any action items remain. Treat review suggestions skeptically; only fix validated defects.
Validated Claude's five review items. Fixed release workflow ordering/typecheck, removed the duplicate .gitmodules entry, and normalized TASK-101 references to repo-relative paths via Backlog MCP.
Left the vendor/subminer-yomitan branch-pin suggestion unchanged. The committed submodule SHA already controls reproducibility; adding a branch would only affect update ergonomics and was not required to address a concrete defect.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Validated Claude's PR #15 review summary against the current branch and applied the actionable fixes. In `.github/workflows/release.yml`, the release `quality-gate` job now restores the dependency cache before installation, no longer installs twice, and runs `bun run typecheck` before the fast test suite to match CI expectations. In `.gitmodules`, removed the duplicate `vendor/yomitan-jlpt-vocab` stanza with the conflicting duplicate path. Through Backlog MCP, updated `TASK-101` references from an absolute local path to repo-relative paths so the task metadata is portable across contributors.
Verification: `git diff --check`, `git config -f .gitmodules --get-regexp '^submodule\..*\.path$'`, `bun run typecheck`, and `bun run test:fast` all passed. `bun run format:check` still fails on many pre-existing unrelated files already present on the branch, including multiple backlog task files and existing source/docs files; this review patch did not attempt a repo-wide formatting sweep.
<!-- SECTION:FINAL_SUMMARY:END -->

60
backlog/tasks/task-113 - Scope-make-pretty-to-maintained-source-files.md
View File

@@ -1,60 +0,0 @@
---
id: TASK-113
title: Scope make pretty to maintained source files
status: Done
assignee:
- codex
created_date: '2026-03-08 00:20'
updated_date: '2026-03-16 05:13'
labels:
- tooling
- formatting
dependencies: []
references:
- Makefile
- package.json
priority: medium
ordinal: 69500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Change the `make pretty` workflow so it formats only the maintained source/config files we intentionally keep under Prettier, instead of sweeping backlog/docs/generated content across the whole repository.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 `make pretty` formats only the approved maintained source/config paths
- [x] #2 The allowlist is reusable for check/write flows instead of duplicating path logic
- [x] #3 Verification shows the scoped formatting command targets the intended files without touching backlog or vendored content
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Inspect current Prettier config/ignore behavior and keep the broad repo-wide format command unchanged.
2. Add a reusable scoped Prettier script that targets maintained source/config paths only.
3. Update `make pretty` to call the scoped script.
4. Verify the scoped command resolves only intended files and does not traverse backlog or vendor paths.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
User approved the allowlist approach: keep repo-wide `format` intact, make `make pretty` use a maintained-path formatter scope.
Added `scripts/prettier-scope.sh` as the single allowlist for scoped Prettier paths and wired `format:src` / `format:check:src` to it.
Updated `make pretty` to call `bun run format:src`. Verified with `make -n pretty` and shell tracing that the helper only targets the maintained allowlist and does not traverse `backlog/` or `vendor/`.
Excluded `Makefile` and `.prettierignore` from the allowlist after verification showed Prettier cannot infer parsers for them.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Scoped the repo's day-to-day formatting entrypoint without changing the existing broad repo-wide Prettier scripts. Added `scripts/prettier-scope.sh` as the shared allowlist for maintained source/config paths (`.github`, `build`, `launcher`, `scripts`, `src`, plus selected root JSON config files), added `format:src` and `format:check:src` in `package.json`, and updated `make pretty` to run the scoped formatter.
Verification: `make -n pretty` now resolves to `bun run format:src`. `bash -n scripts/prettier-scope.sh` passed, and shell-traced `bash -x scripts/prettier-scope.sh --check` confirmed the exact allowlist passed to Prettier. `bun run format:check:src` fails only because existing files inside the allowed source scope are not currently formatted; it no longer touches `backlog/` or `vendor/`.
<!-- SECTION:FINAL_SUMMARY:END -->

63
backlog/tasks/task-114 - Fix-failing-CI-checks-on-PR-15.md
View File

@@ -1,63 +0,0 @@
---
id: TASK-114
title: Fix failing CI checks on PR 15
status: Done
assignee:
- codex
created_date: '2026-03-08 00:34'
updated_date: '2026-03-16 05:13'
labels:
- ci
- test
dependencies: []
references:
- src/renderer/subtitle-render.test.ts
- src/renderer/style.css
- .github/workflows/ci.yml
priority: high
ordinal: 68500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Investigate the failing GitHub Actions CI run for PR #15 on branch `yomitan-fork`, fix the underlying test or code regression, and verify the affected local test/CI lane passes.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Identified the concrete failing CI job and captured the relevant failure context
- [x] #2 Implemented the minimal code or test change needed to resolve the CI failure
- [x] #3 Verified the affected local test target and the broader fast CI test lane pass
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Inspect the failing GitHub Actions run and confirm the exact failing test/assertion.
2. Reproduce the failing renderer stylesheet test locally and compare the assertion against current CSS.
3. Apply the minimal test or stylesheet fix needed to restore the intended hover/selection behavior.
4. Re-run the targeted renderer test, then re-run `bun run test` to verify the fast CI lane is green.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
GitHub Actions run 22810400921 failed in job build-test-audit, step `Test suite (source)`, with a single failing test: `JLPT CSS rules use underline-only styling in renderer stylesheet` in src/renderer/subtitle-render.test.ts.
Reproduced the failing test locally with `bun test src/renderer/subtitle-render.test.ts`. The failure was a brittle stylesheet assertion, not a renderer behavior regression.
Updated the renderer stylesheet test helper to split selectors safely across `:is(...)` commas and normalize multiline selector whitespace, then switched the failing hover/JLPT assertions to inspect extracted rule blocks instead of matching the entire CSS file text.
Verification passed with `bun test src/renderer/subtitle-render.test.ts` and `bun run test`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Investigated GitHub Actions CI run `22810400921` for PR #15 and confirmed the only failing job was `build-test-audit`, step `Test suite (source)`, with a single failure in `src/renderer/subtitle-render.test.ts` (`JLPT CSS rules use underline-only styling in renderer stylesheet`).
The renderer CSS itself was still correct; the regression was in the test helper. `extractClassBlock` was splitting selector lists on every comma, which breaks selectors containing `:is(...)`, and the affected assertions fell back to brittle whole-file regex matching against a multiline selector. Fixed the test by teaching the helper to split selectors only at top-level commas, normalizing selector whitespace around multiline `:not(...)` / `:is(...)` clauses, and asserting on extracted rule blocks for the plain-word hover and JLPT-only hover/selection rules.
Verification: `bun test src/renderer/subtitle-render.test.ts` passed, and `bun run test` passed end to end (the same fast lane that failed in CI).
<!-- SECTION:FINAL_SUMMARY:END -->

60
backlog/tasks/task-115 - Refresh-subminer-docs-contributor-docs-for-current-repo-workflow.md
View File

@@ -1,60 +0,0 @@
---
id: TASK-115
title: Refresh subminer-docs contributor docs for current repo workflow
status: Done
assignee:
- codex
created_date: '2026-03-08 00:40'
updated_date: '2026-03-16 05:13'
labels:
- docs
dependencies: []
references:
- ../subminer-docs/development.md
- ../subminer-docs/README.md
- Makefile
- package.json
priority: medium
ordinal: 67500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Update the sibling `subminer-docs` repo so contributor/development docs match the current SubMiner repo workflow after the docs split and recent tooling changes, including removing stale in-repo docs build steps and documenting the scoped formatting command.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Contributor docs in `subminer-docs` no longer reference stale in-repo docs build commands for the app repo
- [x] #2 Contributor docs mention the current scoped formatting workflow (`make pretty` / `format:src`) where relevant
- [x] #3 Removed stale or no-longer-needed instructions that no longer match the current repo layout
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Inspect `subminer-docs` for contributor/development instructions that drifted after the docs repo split and recent tooling changes.
2. Update contributor docs to remove stale app-repo docs commands and document the current scoped formatting workflow.
3. Verify the modified docs page and build the docs site from the sibling docs repo when local dependencies are available.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Detected concrete doc drift in `subminer-docs/development.md`: stale in-repo docs build commands and no mention of the scoped `make pretty` formatter.
Updated `../subminer-docs/development.md` to remove stale app-repo docs build steps from the local gate, document `make pretty` / `format:check:src`, and point docs-site work to the sibling docs repo explicitly.
Installed docs repo dependencies locally with `bun install` and verified the docs site with `bun run docs:build` in `../subminer-docs`.
Did not change `../subminer-docs/README.md`; it was already accurate for the docs repo itself.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Refreshed the contributor/development docs in the sibling `subminer-docs` repo to match the current SubMiner workflow. In `development.md`, removed the stale app-repo `bun run docs:build` step from the local CI-equivalent gate, added an explicit note to run docs builds from `../subminer-docs` when docs change, documented the scoped formatting workflow (`make pretty` and `bun run format:check:src`), and replaced the old in-repo `make docs*` instructions with the correct sibling-repo `bun run docs:*` commands. Also updated the Makefile reference to include `make pretty` and removed the obsolete `make docs-dev` entry.
Verification: installed docs repo dependencies with `bun install` in `../subminer-docs` and ran `bun run docs:build` successfully. Left `README.md` unchanged because it was already accurate for the standalone docs repo.
<!-- SECTION:FINAL_SUMMARY:END -->

54
backlog/tasks/task-116 - Audit-branch-commits-for-remaining-subminer-docs-updates.md
View File

@@ -1,54 +0,0 @@
---
id: TASK-116
title: Audit branch commits for remaining subminer-docs updates
status: Done
assignee:
- codex
created_date: '2026-03-08 00:46'
updated_date: '2026-03-16 05:13'
labels:
- docs
dependencies: []
references:
- ../subminer-docs/installation.md
- ../subminer-docs/troubleshooting.md
- src/core/services/yomitan-extension-paths.ts
- scripts/build-yomitan.mjs
priority: medium
ordinal: 66500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Review recent `yomitan-fork` commits against the sibling `subminer-docs` repo, identify any concrete documentation drift that remains after the earlier contributor-doc updates, and patch the docs for behavior/tooling changes that are now outdated or misleading.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Reviewed recent branch commits for user-facing or contributor-facing changes that may require docs updates
- [x] #2 Updated `subminer-docs` pages where branch changes introduced concrete doc drift
- [x] #3 Verified the docs site still builds after the updates
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Review branch commit themes against `subminer-docs` and identify only concrete drift introduced by recent workflow/runtime changes.
2. Patch docs for the Yomitan submodule build workflow, updated source-build prerequisites, and current runtime Yomitan search paths/manual fallback path.
3. Rebuild the docs site to verify the updated pages render cleanly.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Concrete remaining drift after commit audit: installation/development docs still understate the Node/npm + submodule requirements for the Yomitan build flow, and troubleshooting still points at obsolete `vendor/yomitan` / `extensions/yomitan` paths.
Audited branch commits against subminer-docs coverage. Existing docs already cover first-run setup, texthooker startup/annotated websocket config, AniList merged character dictionaries, configurable collapsible sections, and subtitle name highlighting. Patched remaining drift around source-build prerequisites and Yomitan build/install paths in installation.md, development.md, and troubleshooting.md. Verified with `bun run docs:build` in ../subminer-docs.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Audited branch commits for missing documentation updates in ../subminer-docs. Updated installation, development, and troubleshooting docs to match the current Yomitan submodule build flow, source-build prerequisites, and runtime extension search/manual fallback paths. Confirmed other recent branch features were already documented and rebuilt the docs site successfully.
<!-- SECTION:FINAL_SUMMARY:END -->

57
backlog/tasks/task-117.1 - Harden-AI-subtitle-fix-against-non-SRT-model-responses.md
View File

@@ -1,57 +0,0 @@
---
id: TASK-117.1
title: Harden AI subtitle fix against non-SRT model responses
status: Done
assignee:
- '@codex'
created_date: '2026-03-08 08:22'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.ts
- /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/srt.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.test.ts
parent_task_id: TASK-117
ordinal: 59500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Prevent optional YouTube AI subtitle post-processing from bailing out whenever the model returns usable cue text in a non-SRT wrapper or text-only format. The launcher should recover safe cases, preserve original timing, and fall back cleanly when the response cannot be mapped back to the source cues.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 AI subtitle fixing accepts safe AI responses that omit SRT framing but still provide one corrected text payload per original cue while preserving original cue timing.
- [x] #2 AI subtitle fixing still rejects responses that cannot be mapped back to the original cue batch without guessing and falls back to the raw subtitle file with a warning.
- [x] #3 Automated tests cover wrapped-SRT and text-only AI responses plus an unrecoverable invalid response case.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing tests in launcher/youtube/subtitle-fix-ai.test.ts for three cases: wrapped valid SRT, text-only one-block-per-cue output, and unrecoverable invalid output.
2. Extend launcher/youtube/subtitle-fix-ai.ts with a small response-normalization path that first strips markdown/code-fence wrappers, then accepts deterministic text-only cue batches only when they map 1:1 to the original cues without changing timestamps.
3. Keep existing safety rules: preserve cue count and timing, log a warning, and fall back to the raw subtitle file when normalization cannot recover a trustworthy batch.
4. Run focused launcher unit tests for subtitle-fix-ai and SRT parsing; expand only if the change affects adjacent behavior.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Implemented deterministic AI subtitle-response recovery for fenced SRT, embedded SRT payloads, and text-only 1:1 cue batches while preserving original timing and existing fallback behavior.
Verification: bun test launcher/youtube/_.test.ts passed; bun run typecheck passed; repo-wide format check still reports unrelated pre-existing warnings in launcher/youtube/orchestrator.ts and scripts/build-changelog_.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Hardened the launcher AI subtitle-fix path so it can recover deterministic non-SRT model responses instead of immediately falling back. Added `parseAiSubtitleFixResponse` in `launcher/youtube/subtitle-fix-ai.ts` to normalize markdown-fenced or embedded SRT payloads first, then accept text-only responses only when they map 1:1 onto the original cue batch and preserve source timings. Added regression coverage in `launcher/youtube/subtitle-fix-ai.test.ts` for fenced SRT, text-only cue batches, and unrecoverable invalid output, plus a changelog fragment in `changes/task-117.1.md`.
Verification: `bun test launcher/youtube/*.test.ts`, `bun run typecheck`, `bunx prettier --check launcher/youtube/subtitle-fix-ai.ts launcher/youtube/subtitle-fix-ai.test.ts`, and `bun run changelog:lint` passed. Repo-wide `bun run format:check:src` still reports unrelated pre-existing warnings in `launcher/youtube/orchestrator.ts` and `scripts/build-changelog*`.
<!-- SECTION:FINAL_SUMMARY:END -->

36
backlog/tasks/task-120 - Replace-node-sqlite-with-libsql-and-remove-Yomitan-Node-wrapper.md
View File

@@ -1,36 +0,0 @@
---
id: TASK-120
title: 'Replace node:sqlite with libsql and remove Yomitan Node wrapper'
status: Done
assignee: []
created_date: '2026-03-08 04:14'
updated_date: '2026-03-16 05:13'
labels:
- runtime
- bun
- sqlite
- tech-debt
dependencies: []
priority: medium
ordinal: 65500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Remove the remaining root Node requirement caused by immersion tracking SQLite usage and the old Yomitan build wrapper by migrating the local SQLite layer off node:sqlite, running the SQLite-backed verification lanes under Bun, and switching the vendored Yomitan build flow to Bun-native scripts.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Immersion tracker runtime no longer imports or requires node:sqlite
- [x] #2 SQLite-backed immersion tracker tests run under Bun without Node --experimental-sqlite
- [x] #3 Root build/test scripts no longer require the Yomitan Node wrapper or Node-based SQLite verification lanes
- [x] #4 README requirements/testing docs reflect the Bun-native workflow
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Replaced the immersion tracker SQLite dependency with a local libsql-backed wrapper, updated Bun/runtime compatibility tests to avoid process.exitCode side effects, switched Yomitan builds to run directly inside the vendored Bun-native project, deleted scripts/build-yomitan.mjs, and verified typecheck plus Bun build/test lanes (`build:yomitan`, `test:immersion:sqlite`, `test:runtime:compat`, `test:fast`).
<!-- SECTION:FINAL_SUMMARY:END -->

53
backlog/tasks/task-121 - Fix-YouTube-manual-subtitle-selection-regression-when-downloadable-tracks-exist.md
View File

@@ -1,53 +0,0 @@
---
id: TASK-121
title: >-
Fix YouTube manual subtitle selection regression when downloadable tracks
exist
status: Done
assignee:
- '@codex'
created_date: '2026-03-08 05:37'
updated_date: '2026-03-16 05:13'
labels:
- bug
- youtube
- subtitles
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/manual-subs.ts
- /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/orchestrator.ts
- 'https://www.youtube.com/watch?v=MXzQRLmN9hE'
priority: high
ordinal: 64500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Ensure launcher YouTube subtitle generation reuses downloadable manual subtitle tracks when the video already has requested languages available, instead of falling back to whisper generation. Reproduce against videos like MXzQRLmN9hE that expose manual en/ja subtitles via yt-dlp.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 When requested primary/secondary manual YouTube subtitle tracks exist, planning selects them and schedules no whisper generation for those tracks.
- [x] #2 Filename normalization handles manual subtitle outputs produced by yt-dlp for language-tagged downloads.
- [x] #3 Automated tests cover the reproduced manual en/ja selection case.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Reproduced against https://www.youtube.com/watch?v=MXzQRLmN9hE with yt-dlp --list-subs: manual zh/en/ja/ko subtitle tracks are available from YouTube.
Adjusted launcher YouTube orchestration so detected manual subtitle tracks suppress whisper generation but are no longer materialized as external subtitle files. SubMiner now relies on the native YouTube/mpv subtitle tracks for those languages.
Added orchestration tests covering the manual-track reuse plan and ran a direct runtime probe against MXzQRLmN9hE. Probe result: primary/secondary native tracks detected, no external subtitle aliases emitted, output directory remained empty.
Verification: bun test launcher/youtube/orchestrator.test.ts launcher/config-domain-parsers.test.ts launcher/mpv.test.ts passed; bun run typecheck passed.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed the YouTube subtitle regression where videos with real downloadable subtitle tracks still ended up with duplicate external subtitle files. Manual subtitle availability now suppresses whisper generation and external subtitle publication, so videos like MXzQRLmN9hE use the native YouTube/mpv subtitle tracks directly. Launcher preprocess logging was also updated to report native subtitle availability instead of misleading missing statuses.
<!-- SECTION:FINAL_SUMMARY:END -->

72
backlog/tasks/task-122 - Harden-changelog-workflow-and-CI-enforcement.md
View File

@@ -1,72 +0,0 @@
---
id: TASK-122
title: Harden changelog workflow and CI enforcement
status: Done
assignee:
- Codex
created_date: '2026-03-08 06:13'
updated_date: '2026-03-16 05:13'
labels:
- release
- changelog
- ci
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/scripts/build-changelog.ts
- /Users/sudacode/projects/japanese/SubMiner/scripts/build-changelog.test.ts
- /Users/sudacode/projects/japanese/SubMiner/.github/workflows/ci.yml
- /Users/sudacode/projects/japanese/SubMiner/.github/workflows/release.yml
- /Users/sudacode/projects/japanese/SubMiner/docs/RELEASING.md
- /Users/sudacode/projects/japanese/SubMiner/changes/README.md
priority: medium
ordinal: 63500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Improve the release changelog workflow so changelog fragments are reliable, release output is more readable, and pull requests get early feedback when changelog metadata is missing or malformed.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 `scripts/build-changelog.ts` ignores non-fragment files in `changes/` and validates fragment structure before generating changelog output.
- [x] #2 Generated `CHANGELOG.md` and `release/release-notes.md` group public changes into readable sections instead of a flat bullet list.
- [x] #3 CI enforces changelog validation on pull requests and provides an explicit opt-out path for changes that should not produce release notes.
- [x] #4 Contributor docs explain the fragment format and the PR/release workflow for changelog generation.
- [x] #5 Automated tests cover fragment parsing/building behavior and workflow enforcement expectations.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing tests for changelog fragment discovery, structured fragment parsing/rendering, release-note output, and CI workflow expectations.
2. Update scripts/build-changelog.ts to ignore non-fragment files, parse fragment metadata, group generated output by change type, add lint/PR-check commands, and simplify output paths to repo-local artifacts.
3. Update CI and PR workflow files to run changelog validation on pull requests with an explicit skip path, and keep release workflow using committed changelog output.
4. Refresh changes/README.md, docs/RELEASING.md, and any PR template text so contributors know how to write fragments and when opt-out is allowed.
5. Run targeted tests and changelog commands, then record results and finalize the task.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Implemented structured changelog fragments with required `type` and `area` metadata; `changes/README.md` is now ignored by the generator and verified by regression tests.
Added `changelog:lint` and `changelog:pr-check`, plus PR CI enforcement with `skip-changelog` opt-out. PR check now reads git name-status output so deleted fragment files do not satisfy the requirement.
Changed generated changelog/release notes output to grouped sections (`Added`, `Changed`, `Fixed`, etc.) and simplified release notes to highlights + install/assets pointers.
Kept changelog output repo-local. This aligns with existing repo direction where docs updates happen in the sibling docs repo explicitly rather than implicit local writes from app-repo generators.
Verification: `bun test scripts/build-changelog.test.ts src/ci-workflow.test.ts src/release-workflow.test.ts` passed; `bun run typecheck` passed; `bun run changelog:lint` passed. `bun run test:fast` still fails in unrelated existing `src/core/services/subsync.test.ts` cases (`runSubsyncManual keeps internal alass source file alive until sync finishes`, `runSubsyncManual resolves string sid values from mpv stream properties`).
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Hardened the changelog workflow end-to-end. `scripts/build-changelog.ts` now ignores helper files like `changes/README.md`, requires structured fragment metadata (`type` + `area`), groups generated release sections by change type, and emits shorter release notes focused on highlights plus install/assets pointers. Added explicit `changelog:lint` and `changelog:pr-check` commands, with PR validation based on git name-status so deleted fragment files do not satisfy the fragment requirement.
Updated contributor-facing workflow docs in `changes/README.md`, `docs/RELEASING.md`, and a new PR template so authors know to add a fragment or apply the `skip-changelog` label. CI now runs fragment linting on every run and enforces fragment presence on pull requests. Added regression coverage in `scripts/build-changelog.test.ts` and a new `src/ci-workflow.test.ts` to lock the workflow contract.
Verification completed: `bun test scripts/build-changelog.test.ts src/ci-workflow.test.ts src/release-workflow.test.ts`, `bun run typecheck`, and `bun run changelog:lint` all passed. A broader `bun run test:fast` run still fails in unrelated existing `src/core/services/subsync.test.ts` cases outside the changelog/workflow scope.
<!-- SECTION:FINAL_SUMMARY:END -->

53
backlog/tasks/task-123 - Add-progress-logging-for-YouTube-subtitle-generation-phases.md
View File

@@ -1,53 +0,0 @@
---
id: TASK-123
title: Add progress logging for YouTube subtitle generation phases
status: Done
assignee:
- '@codex'
created_date: '2026-03-08 07:07'
updated_date: '2026-03-16 05:13'
labels:
- ux
- logging
- youtube
- subtitles
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/orchestrator.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/youtube/audio-extraction.ts
- /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/whisper.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.ts
priority: medium
ordinal: 62500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Improve launcher YouTube subtitle generation observability so users can tell that work is happening and roughly how long each phase is taking. Cover manual subtitle probe, audio extraction, ffmpeg prep, whisper generation, and optional AI subtitle fix phases without flooding normal logs.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Users see clear info-level phase logs for YouTube subtitle generation work including subtitle probe, fallback audio extraction, whisper, and optional AI fix phases.
- [x] #2 Long-running phases surface elapsed-time progress or explicit start/finish timing so it is obvious the process is still active.
- [x] #3 Automated tests cover the new logging/progress helper behavior where practical.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Implemented a shared timed YouTube phase logger in launcher/youtube/progress.ts with info-level start/finish messages and warn-level failure messages that include elapsed time.
Wired phase logging into YouTube metadata probe, manual subtitle probe, fallback audio extraction, ffmpeg whisper prep, whisper primary/secondary generation, and optional AI subtitle fix phases.
Verification: bun test launcher/youtube/progress.test.ts launcher/youtube/orchestrator.test.ts passed; bun run typecheck passed.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added clear phase-level observability for YouTube subtitle generation without noisy tool output. Users now see start/finish logs with elapsed time for subtitle probe, fallback audio extraction, ffmpeg prep, whisper generation, and optional AI subtitle-fix phases, making it obvious when generation is active and roughly how long each step took.
<!-- SECTION:FINAL_SUMMARY:END -->

77
backlog/tasks/task-124 - Remove-YouTube-subtitle-generation-modes-and-make-YouTube-playback-always-generate-load-subtitles.md
View File

@@ -1,77 +0,0 @@
---
id: TASK-124
title: >-
Remove YouTube subtitle generation modes and make YouTube playback always
generate/load subtitles
status: Done
assignee:
- codex
created_date: '2026-03-08 07:18'
updated_date: '2026-03-16 05:13'
labels:
- launcher
- youtube
- subtitles
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/config/args-normalizer.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/config/youtube-subgen-config.ts
- /Users/sudacode/projects/japanese/SubMiner/launcher/types.ts
- /Users/sudacode/projects/japanese/SubMiner/config.example.jsonc
- >-
/Users/sudacode/projects/japanese/SubMiner/src/config/definitions/options-integrations.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/config/resolve/subtitle-domains.ts
priority: high
ordinal: 61500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Simplify launcher YouTube playback by removing the configurable subtitle generation mode. For YouTube targets, the launcher should treat subtitle generation/loading as the canonical behavior instead of supporting off/preprocess/automatic branches. This change should remove the unreliable automatic/background path and the mode concept from config/CLI/env/docs, while preserving the core YouTube subtitle generation pipeline and mpv loading flow.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Launcher playback no longer supports or branches on a YouTube subtitle generation mode; YouTube URLs follow a single generation-and-load flow.
- [x] #2 Configuration, CLI parsing, and environment handling no longer expose a YouTube subtitle generation mode option, and stale automatic/preprocess/off values are not part of the supported interface.
- [x] #3 Tests cover the new single-flow behavior and the removal of mode parsing/branching.
- [x] #4 User-facing config/docs/examples are updated to reflect the removed mode concept.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Remove the YouTube subtitle generation mode concept from launcher/shared types, config parsing, CLI options, and environment normalization so no supported interface accepts automatic/preprocess/off.
2. Update playback orchestration so YouTube targets always run subtitle generation/loading before mpv startup and delete the background automatic path.
3. Adjust mpv YouTube URL argument construction to no longer branch on mode while preserving subtitle/audio language behavior and preloaded subtitle file injection.
4. Add/modify tests first to cover removed mode parsing and the single YouTube preload flow, then update config/docs/examples to match the simplified interface.
5. Run focused launcher/config tests plus typecheck, then summarize any remaining gaps.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Removed launcher/shared youtubeSubgen.mode handling and collapsed YouTube playback onto a single preload-before-mpv subtitle generation flow.
Added launcher integration coverage proving YouTube subtitle generation runs before mpv startup and that the removed --mode flag now errors.
Verification: bun test launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/mpv.test.ts launcher/main.test.ts src/config/config.test.ts; bun run test:config:src; bun run typecheck.
Broader repo checks still show pre-existing issues outside this change: bun run test:launcher:unit:src fails in launcher/aniskip-metadata.test.ts (MAL id assertion), and format scope check reports unrelated existing files launcher/youtube/orchestrator.ts, scripts/build-changelog.test.ts, scripts/build-changelog.ts.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Removed the launcher YouTube subtitle generation mode surface so YouTube playback now always runs the subtitle generation pipeline before starting mpv. The launcher no longer accepts youtubeSubgen.mode from shared config, CLI, or env normalization, and the old automatic/background loading path has been deleted from playback.
Updated mpv YouTube startup options to keep manual subtitle discovery enabled without requesting auto subtitles, and refreshed user-facing config/docs to describe a single YouTube subtitle generation flow. Added regression coverage for mode removal, config/template cleanup, and launcher ordering so YouTube subtitle work is confirmed to happen before mpv launch.
Verification: bun test launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/mpv.test.ts launcher/main.test.ts src/config/config.test.ts; bun run test:config:src; bun run typecheck. Broader unrelated repo issues remain in launcher/aniskip-metadata.test.ts and existing formatting drift in launcher/youtube/orchestrator.ts plus scripts/build-changelog files.
<!-- SECTION:FINAL_SUMMARY:END -->

44
backlog/tasks/task-126 - Improve-secondary-subtitle-readability-with-hover-only-background-and-stronger-text-separation.md
View File

@@ -1,44 +0,0 @@
---
id: TASK-126
title: >-
Improve secondary subtitle readability with hover-only background and stronger
text separation
status: Done
assignee: []
created_date: '2026-03-08 07:35'
updated_date: '2026-03-16 05:13'
labels:
- overlay
- subtitles
- ui
dependencies: []
priority: medium
ordinal: 60500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Adjust overlay secondary subtitle styling so translation text stays readable on bright video backgrounds. Keep the dark background hidden by default in hover mode and show it only while hovered. Increase secondary subtitle weight to 600 and strengthen edge separation without changing primary subtitle styling.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Secondary subtitles render with stronger edge separation than today.
- [x] #2 Secondary subtitle font weight defaults to 600.
- [x] #3 When secondary subtitle mode is hover, the secondary background appears only while hovered.
- [x] #4 Primary subtitle styling behavior remains unchanged.
- [x] #5 Renderer tests cover the new secondary hover background behavior and default secondary style values.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Adjusted secondary subtitle defaults to use stronger shadowing, 600 font weight, and a translucent dark background. Routed secondary background/backdrop styling through CSS custom properties so hover mode can keep the background hidden until the secondary subtitle is actually hovered. Added renderer and config tests covering default values and hover-only background behavior.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Improved secondary subtitle readability by strengthening default text separation, increasing the default secondary weight to 600, and making the configured dark background appear only while hovered in secondary hover mode. Added config and renderer coverage for the new defaults and hover-aware style routing.
<!-- SECTION:FINAL_SUMMARY:END -->

84
backlog/tasks/task-127 - Skip-AniSkip-lookup-for-YouTube-and-URL-playback-targets.md
View File

@@ -1,84 +0,0 @@
---
id: TASK-127
title: Skip AniSkip lookup for YouTube and URL playback targets
status: Done
assignee:
- '@codex'
created_date: '2026-03-08 08:24'
updated_date: '2026-03-16 05:13'
labels:
- bug
- launcher
- youtube
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/launcher/mpv.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
- /Users/sudacode/projects/japanese/SubMiner/launcher/mpv.test.ts
ordinal: 56500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Prevent launcher playback from attempting AniSkip metadata resolution when the user is playing a YouTube target or any URL target. AniSkip only works for local anime files, so URL-driven playback and YouTube subtitle-generation flows should bypass it entirely.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Launcher playback skips AniSkip metadata resolution for explicit URL targets, including YouTube URLs.
- [x] #2 YouTube subtitle-generation playback does not invoke AniSkip lookup before mpv launch.
- [x] #3 Automated launcher tests cover the URL/YouTube skip behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a launcher mpv unit test that intercepts AniSkip resolution and proves URL/YouTube playback does not call it before spawning mpv.
2. Run the focused launcher mpv test to confirm the new case fails or exposes the current gap.
3. Patch launcher playback/AniSkip gating so URL and YouTube subtitle-generation paths always bypass AniSkip lookup.
4. Re-run focused launcher tests and record the verification results in task notes.
5. Add a Lua plugin regression test covering overlay-start on URL playback so AniSkip never runs after auto-start.
6. Patch plugin/subminer/aniskip.lua to short-circuit all AniSkip lookup triggers for remote URL media paths.
7. Re-run plugin regression plus touched launcher checks and update the task summary with the plugin-side fix.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added explicit AniSkip gating in launcher/mpv.ts via shouldResolveAniSkipMetadata(target, targetKind, preloadedSubtitles).
URL targets now always bypass AniSkip. File targets with preloaded subtitles also bypass AniSkip, covering YouTube subtitle-preload playback.
Added launcher/mpv.test.ts coverage for local-file vs URL vs preloaded-subtitle AniSkip gating.
Verification: bun test launcher/mpv.test.ts passed.
Verification: bun run typecheck passed.
Verification: bunx prettier --check launcher/mpv.ts launcher/mpv.test.ts passed.
Verification: bun run changelog:lint passed.
Verification: bun run test:launcher:unit:src remains blocked by unrelated existing failure in launcher/aniskip-metadata.test.ts (`resolveAniSkipMetadataForFile resolves MAL id and intro payload`: expected malId 1234, got null).
Added plugin regression in scripts/test-plugin-start-gate.lua for URL playback with auto-start/overlay-start; it now asserts no MAL or AniSkip curl requests occur.
Patched plugin/subminer/aniskip.lua to short-circuit AniSkip lookup for remote media paths (`scheme://...`), which covers YouTube URL playback inside the mpv plugin lifecycle.
Verification: lua scripts/test-plugin-start-gate.lua passed.
Verification: bun run test:plugin:src passed.
Verification: bun test launcher/mpv.test.ts passed after plugin-side fix.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed AniSkip suppression end-to-end for URL playback. The launcher now skips AniSkip before mpv launch, and the mpv plugin now also refuses AniSkip lookups for remote URL media during file-loaded, overlay-start, or later refresh triggers. Added regression coverage in both launcher/mpv.test.ts and scripts/test-plugin-start-gate.lua, plus a changelog fragment. Wider `bun run test:launcher:unit:src` is still blocked by the unrelated existing launcher/aniskip-metadata.test.ts MAL-id failure.
<!-- SECTION:FINAL_SUMMARY:END -->

36
backlog/tasks/task-128 - Prevent-AI-subtitle-fix-from-translating-primary-YouTube-subtitles-into-the-wrong-language.md
View File

@@ -1,36 +0,0 @@
---
id: TASK-128
title: >-
Prevent AI subtitle fix from translating primary YouTube subtitles into the
wrong language
status: Done
assignee: []
created_date: '2026-03-08 09:02'
updated_date: '2026-03-16 05:13'
labels:
- bug
- youtube-subgen
- ai
dependencies: []
priority: high
ordinal: 58500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
AI subtitle cleanup can preserve cue structure while changing subtitle language, causing primary Japanese subtitle files to come back in English. Add guards so AI-fixed subtitles preserve expected language and fall back to raw Whisper output when language drifts.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Primary AI subtitle fix rejects output that drifts away from the expected source language.
- [x] #2 Rejected AI fixes fall back to the raw Whisper subtitle without corrupting published subtitle language.
- [x] #3 Regression tests cover a primary Japanese subtitle batch being translated into English by the AI fixer.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added a primary-language guard to AI subtitle fixing so Japanese source subtitles are rejected if the AI rewrites them into English while preserving SRT structure. The fixer now receives the expected source language from the YouTube orchestrator, and regression coverage verifies that language drift falls back to the raw Whisper subtitle path.
<!-- SECTION:FINAL_SUMMARY:END -->

38
backlog/tasks/task-129 - Split-AI-model-and-system-prompt-config-between-Anki-and-YouTube-subtitle-generation.md
View File

@@ -1,38 +0,0 @@
---
id: TASK-129
title: >-
Split AI model and system prompt config between Anki and YouTube subtitle
generation
status: Done
assignee: []
created_date: '2026-03-08 09:40'
updated_date: '2026-03-16 05:13'
labels:
- config
- ai
- anki
- youtube-subgen
dependencies: []
priority: high
ordinal: 57500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
The current top-level shared AI config forces Anki translation and YouTube subtitle fixing to share the same model and system prompt, which caused subtitle-fix requests to inherit a translation prompt and translate Japanese primary subtitles into English. Refactor config so provider credentials stay shared while model and system prompt can be configured per feature.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Anki integration can use its own AI model and system prompt independently of YouTube subtitle generation.
- [x] #2 YouTube subtitle generation can use its own AI model and system prompt independently of Anki integration.
- [x] #3 Existing shared provider credentials remain reusable without duplicating API key/base URL config.
- [x] #4 Config example, defaults, validation, and regression tests cover the new per-feature override shape.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added per-feature AI model/systemPrompt overrides for Anki and YouTube subtitle generation while keeping shared provider transport settings reusable. Anki now accepts `ankiConnect.ai` object config with `enabled`, `model`, and `systemPrompt`; YouTube subtitle generation accepts `youtubeSubgen.ai` overrides and merges them over the shared AI provider config. Updated config resolution, launcher parsing, runtime wiring, hot-reload handling, example config, and regression coverage.
<!-- SECTION:FINAL_SUMMARY:END -->

78
backlog/tasks/task-130 - Keep-background-SubMiner-alive-after-launcher-managed-mpv-exits.md
View File

@@ -1,78 +0,0 @@
---
id: TASK-130
title: Keep background SubMiner alive after launcher-managed mpv exits
status: Done
assignee:
- codex
created_date: '2026-03-08 10:08'
updated_date: '2026-03-16 05:13'
labels:
- bug
- launcher
- mpv
- overlay
dependencies: []
priority: high
ordinal: 55500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
The launcher currently tears down the running SubMiner background process when a launcher-managed mpv session exits. Background SubMiner should remain alive so a later mpv instance can reconnect and request the overlay without restarting the app.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Closing a launcher-managed mpv session does not send `--stop` to the running SubMiner background process.
- [x] #2 Closing a launcher-managed mpv session does not SIGTERM the tracked SubMiner process just because mpv exited.
- [x] #3 Launcher cleanup still terminates mpv and launcher-owned helper children without regressing existing overlay start behavior.
- [x] #4 Automated tests cover the no-stop-on-mpv-exit behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a launcher regression test that proves mpv exit no longer triggers SubMiner `--stop` or launcher SIGTERM of the tracked overlay process.
2. Update launcher teardown so normal mpv-session cleanup only stops mpv/helper children and preserves the background SubMiner process for future reconnects.
3. Run the focused launcher tests and smoke coverage for the affected behavior, then record results in the task.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Split launcher cleanup so normal mpv-session shutdown no longer sends `--stop` to SubMiner or SIGTERM to the tracked overlay process. Added `cleanupPlaybackSession()` for mpv/helper-child cleanup only, and switched playback finalization to use it.
Updated launcher smoke coverage to assert the background app stays alive after mpv exits, and added a focused unit regression for the new cleanup path.
Validation: `bun test launcher/mpv.test.ts launcher/smoke.e2e.test.ts` passed; `bun run typecheck` passed. `bun run test:launcher:unit:src` still reports an unrelated pre-existing failure in `launcher/aniskip-metadata.test.ts`.
Added changelog fragment `changes/task-130.md` for the launcher fix and verified it with `bun run changelog:lint`.
User verified the bug still reproduces when closing playback with `q`. Root cause narrowed further: the mpv plugin `plugin/subminer/lifecycle.lua` calls `process.stop_overlay()` on mpv `shutdown`, which still sends SubMiner `--stop` even after launcher cleanup was fixed.
Patched the remaining stop path in `plugin/subminer/lifecycle.lua`: mpv `shutdown` no longer calls `process.stop_overlay()`. Pressing mpv `q` should now preserve the background app and only tear down the mpv session.
Validation update: `lua scripts/test-plugin-start-gate.lua` passed after adding a shutdown regression, and `bun test launcher/mpv.test.ts launcher/smoke.e2e.test.ts` still passed.
Fixed a second-instance reconnect bug in `src/core/services/cli-command.ts`: `--start` on an already-initialized running instance now still updates the MPV socket path and reconnects the MPV client instead of treating the command as a no-op. This keeps the already-warmed background app reusable for later mpv launches.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Kept the background SubMiner process reusable across both mpv shutdown and later reconnects. The first fix separated launcher playback cleanup from full app shutdown. The second fix removed the mpv plugin `shutdown` stop call so default mpv `q` no longer sends SubMiner `--stop`. The third fix corrected second-instance CLI handling so `--start` on an already-running, already-initialized instance still reconnects MPV instead of being ignored.
Net effect: background SubMiner can stay alive, keep its warm state, and reconnect to later mpv instances without rerunning startup/warmup work in a fresh app instance.
Coverage now includes: launcher playback cleanup (`launcher/mpv.test.ts`), launcher smoke reconnect/keep-alive flow (`launcher/smoke.e2e.test.ts`), mpv plugin shutdown preservation (`scripts/test-plugin-start-gate.lua`), and second-instance start/reconnect behavior (`src/core/services/cli-command.test.ts`).
Tests run:
- `bun test src/core/services/cli-command.test.ts launcher/mpv.test.ts launcher/smoke.e2e.test.ts`
- `lua scripts/test-plugin-start-gate.lua`
- `bun run typecheck`
- `bun run changelog:lint`
Note: the broader `bun run test:launcher:unit:src` lane still has an unrelated pre-existing failure in `launcher/aniskip-metadata.test.ts`.
<!-- SECTION:FINAL_SUMMARY:END -->

75
backlog/tasks/task-131 - Make-default-overlay-fullscreen-and-AniSkip-end-jump-keybindings-easier-to-reach.md
View File

@@ -1,75 +0,0 @@
---
id: TASK-131
title: >-
Make default overlay fullscreen and AniSkip end-jump keybindings easier to
reach
status: Done
assignee:
- codex
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- enhancement
- overlay
- mpv
- aniskip
dependencies: []
ordinal: 43500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Make two default keyboard actions easier to hit during playback: add `f` as the built-in overlay fullscreen toggle, and make AniSkip's default intro-end jump use `Tab`.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Default overlay keybindings include `KeyF` mapped to mpv fullscreen toggle.
- [x] #2 Default AniSkip hint/button key defaults to `Tab` and the plugin registers that binding.
- [x] #3 Automated regression coverage exists for both default bindings.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing TypeScript regression proving default overlay keybindings include fullscreen on `KeyF`.
2. Add a failing Lua/plugin regression proving AniSkip defaults to `Tab`, updates the OSD hint text, and registers the expected keybinding.
3. Patch the default keybinding/config values with minimal behavior changes and keep fallback binding behavior intentional.
4. Run focused tests plus touched verification commands, then record results and a short changelog fragment.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added `KeyF -> ['cycle', 'fullscreen']` to the built-in overlay keybindings in `src/config/definitions/shared.ts`.
Changed the mpv plugin AniSkip default button key from `y-k` to `TAB` in both the runtime default options and the shipped `plugin/subminer.conf`. The AniSkip OSD hint now also falls back to `TAB` when no explicit key is configured.
Adjusted `plugin/subminer/ui.lua` fallback registration so the legacy `y-k` binding is only added for custom non-default AniSkip bindings, instead of always shadowing the new default.
Extended regression coverage:
- `src/config/definitions/domain-registry.test.ts` now asserts the default fullscreen binding on `KeyF`.
- `scripts/test-plugin-start-gate.lua` now isolates plugin runs correctly, records keybinding/observer registration, and asserts the default AniSkip keybinding/prompt behavior for `TAB`.
Verification:
- `bun test src/config/definitions/domain-registry.test.ts`
- `bun run test:config:src`
- `lua scripts/test-plugin-start-gate.lua`
- `bun run changelog:lint`
- `bun run typecheck`
Known unrelated verification gap:
- `bun run test:plugin:src` still fails in `scripts/test-plugin-binary-windows.lua` on this Linux host (`windows env override should resolve .exe suffix`), outside the keybinding changes in this task.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Default overlay playback now has an easier fullscreen toggle on `f`, and AniSkip's default intro-end jump now uses `Tab`. The mpv plugin hint text and registration logic were updated to match the new default, while keeping legacy `y-k` fallback behavior limited to custom non-default bindings.
Regression coverage was added for both defaults, and the plugin test harness now resets plugin bootstrap state between scenarios so keybinding assertions can run reliably.
<!-- SECTION:FINAL_SUMMARY:END -->

70
backlog/tasks/task-132 - Gate-macOS-overlay-shortcuts-to-the-focused-mpv-window.md
View File

@@ -1,70 +0,0 @@
---
id: TASK-132
title: Gate macOS overlay shortcuts to the focused mpv window
status: Done
assignee:
- codex
created_date: '2026-03-08 18:24'
updated_date: '2026-03-18 05:28'
labels:
- bug
- macos
- shortcuts
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-shortcut.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/window-trackers/macos-tracker.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/scripts/get-mpv-window-macos.swift
priority: high
ordinal: 53500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the macOS shortcut handling so SubMiner overlay keybinds do not intercept system or other-app shortcuts while SubMiner is in the background. Overlay shortcuts should only be active while the tracked mpv window is present and focused, and should stop grabbing keyboard input when mpv is not the frontmost window.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 On macOS, overlay shortcuts do not trigger while mpv is not the focused/frontmost window.
- [x] #2 On macOS, overlay shortcuts remain available while the tracked mpv window is open and focused.
- [x] #3 Existing non-macOS shortcut behavior is unchanged.
- [x] #4 Automated tests cover the macOS focus-gating behavior and guard against background shortcut interception.
- [x] #5 Any user-facing docs/config notes affected by the behavior change are updated in the same task if needed.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing macOS-focused shortcut lifecycle test that proves overlay shortcuts stay inactive when the tracked mpv window exists but is not frontmost, and activate when that tracked window becomes frontmost.
2. Add a failing tracker/helper test that covers the focused/frontmost signal parsed from the macOS helper output.
3. Extend the macOS helper/tracker contract to surface both geometry and focused/frontmost state for the tracked mpv window.
4. Wire overlay shortcut activation to require both overlay runtime initialization and tracked-mpv focus on macOS, while leaving non-macOS behavior unchanged.
5. Re-run the targeted shortcut/tracker tests, then the broader related shortcut/runtime suite, and update task notes/acceptance criteria based on results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added a macOS-specific shortcut activation predicate so global overlay shortcuts now require both overlay runtime readiness and a focused tracked mpv window; non-macOS behavior still keys off runtime readiness only.
Extended the base window tracker with optional focus-state callbacks/getters and wired initializeOverlayRuntime to re-sync overlay shortcuts whenever tracker focus changes.
Updated the macOS helper/tracker contract to return geometry plus frontmost/focused state for the tracked mpv process and added parser coverage for focused and unfocused output.
Verified with `bun x tsc -p tsconfig.json --noEmit`, targeted shortcut/tracker tests, and `bun run test:core:src` (439 passing).
No user-facing config or documentation surface changed, so no docs update was required for this fix.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed the macOS background shortcut interception bug by gating SubMiner's global overlay shortcuts on tracked mpv focus instead of overlay-runtime initialization alone. The macOS window helper now reports whether the tracked mpv process is frontmost, the tracker exposes focus change callbacks, and overlay shortcut synchronization re-runs when that focus state flips so `Ctrl+C`/`Ctrl+V` and similar shortcuts are no longer captured while mpv is in the background.
The change keeps existing non-macOS shortcut behavior unchanged. Added regression coverage for the activation decision, tracker focus-change re-sync, and macOS helper output parsing. Verification: `bun x tsc -p tsconfig.json --noEmit`, targeted shortcut/tracker tests, and `bun run test:core:src` (439 passing).
<!-- SECTION:FINAL_SUMMARY:END -->

67
backlog/tasks/task-134 - Harden-Windows-release-signing-against-transient-SignPath-failures.md
View File

@@ -1,67 +0,0 @@
---
id: TASK-134
title: Harden Windows release signing against transient SignPath failures
status: Done
assignee:
- codex
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- ci
- release
- windows
- signing
dependencies: []
references:
- .github/workflows/release.yml
- package.json
- src/release-workflow.test.ts
- 'https://github.com/ksyasuda/SubMiner/actions/runs/22836585479'
priority: high
ordinal: 52500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
The tag-driven Release workflow currently fails the Windows lane if the SignPath connector returns transient 502 errors during submission, and the tagged build scripts also allow electron-builder to implicitly publish unsigned artifacts before the final release job runs. Harden the workflow so transient SignPath outages get bounded retries and release packaging never auto-publishes unsigned assets.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Windows release signing retries transient SignPath submission failures within the release workflow before failing the job.
- [ ] #2 Release packaging scripts disable electron-builder implicit publish so build jobs do not upload unsigned assets on tag builds.
- [ ] #3 Regression coverage fails if SignPath retry scaffolding or publish suppression is removed.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a regression test for the release workflow/package script shape covering SignPath retries and `--publish never`.
2. Patch the Windows release job to retry SignPath submission a bounded number of times and still fail hard if every attempt fails.
3. Update tagged package build scripts to disable implicit electron-builder publishing during release builds.
4. Run targeted release-workflow verification and capture any remaining manual release cleanup needed for `v0.5.0`.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
The failed Windows signing step in GitHub Actions run `22836585479` was not caused by missing secrets or an artifact-shape mismatch. The SignPath GitHub action retried repeated `502` responses from the SignPath connector for several minutes and then failed the job.
Hardened `.github/workflows/release.yml` by replacing the single SignPath submission with three bounded attempts. The second and third submissions only run if the previous attempt failed, and the job now fails with an explicit rerun message only after all three attempts fail. Signed-artifact upload is keyed to the successful attempt so the release job still consumes the normal `windows` artifact name.
Also fixed a separate release regression exposed by the same run: `electron-builder` was implicitly publishing unsigned release assets during tag builds because the packaging scripts did not set `--publish never` and the workflow injected `GH_TOKEN` into build jobs. Updated the relevant package scripts to pass `--publish never`, removed `GH_TOKEN` from the packaging jobs, and made the final publish step force `--draft=false` when editing an existing tag release so previously-created draft releases get published.
Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, and `bun run test:fast` all passed locally after restoring the missing local `libsql` install with `bun install --frozen-lockfile`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Windows release signing is now resilient to transient SignPath connector outages. The release workflow retries the SignPath submission up to three times before failing, and only uploads the signed Windows artifact from the attempt that succeeded.
Release packaging also no longer auto-publishes unsigned assets on tag builds. The `electron-builder` scripts now force `--publish never`, the build jobs no longer pass `GH_TOKEN` into packaging steps, and the final GitHub release publish step explicitly clears draft state when updating an existing tag release.
Validation: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
Manual follow-up for the failed `v0.5.0` release: rerun the `Release` workflow after merging/pushing this fix, then clean up the stray draft/untagged release assets created by the failed run if they remain.
<!-- SECTION:FINAL_SUMMARY:END -->

58
backlog/tasks/task-135 - Cut-patch-release-v0.5.1-for-Windows-signing-fix.md
View File

@@ -1,58 +0,0 @@
---
id: TASK-135
title: Cut patch release v0.5.1 for Windows signing fix
status: Done
assignee:
- codex
created_date: '2026-03-08 20:24'
updated_date: '2026-03-18 05:28'
labels:
- release
- patch
dependencies:
- TASK-134
references:
- package.json
- CHANGELOG.md
- release/release-notes.md
priority: high
ordinal: 51500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Publish a patch release from the workflow-signing fix on `main` by bumping the app version, generating the committed changelog artifacts for the new version, and pushing a new `v0.5.1` tag instead of rewriting the failed `v0.5.0` tag.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Repository version metadata is updated to `0.5.1`.
- [ ] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.1` section and released fragments are removed.
- [ ] #3 New `v0.5.1` commit and tag are pushed to `origin`.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Bump the package version to `0.5.1`.
2. Run the changelog builder so `CHANGELOG.md`/`release-notes.md` match the release workflow contract.
3. Run the relevant verification commands.
4. Commit the release-prep changes, create `v0.5.1`, and push both commit and tag.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Bumped `package.json` from `0.5.0` to `0.5.1`, then ran `bun run changelog:build` so the committed release artifacts match the release workflow contract. That prepended the `v0.5.1` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed changelog fragments from `changes/`.
Verification before tagging: `bun run changelog:lint`, `bun run changelog:check --version 0.5.1`, `bun run typecheck`, and `bun run test:fast`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Prepared patch release `v0.5.1` from the signing-workflow fix on `main` instead of rewriting the failed `v0.5.0` tag. Repository version metadata, changelog, and committed release notes are all aligned with the new release tag, and the consumed changelog fragments were removed.
Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.1`, `bun run typecheck`, `bun run test:fast`.
<!-- SECTION:FINAL_SUMMARY:END -->

62
backlog/tasks/task-136 - Pin-SignPath-artifact-configuration-in-release-workflow.md
View File

@@ -1,62 +0,0 @@
---
id: TASK-136
title: Pin SignPath artifact configuration in release workflow
status: Done
assignee:
- codex
created_date: '2026-03-08 20:41'
updated_date: '2026-03-18 05:28'
labels:
- ci
- release
- windows
- signing
dependencies:
- TASK-134
references:
- .github/workflows/release.yml
- build/signpath-windows-artifact-config.xml
- src/release-workflow.test.ts
priority: high
ordinal: 49500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
The Windows release workflow currently relies on the default SignPath artifact configuration configured in the SignPath UI. Pin the workflow to an explicit artifact-configuration slug so the checked-in signing configuration and CI behavior stay deterministic across future SignPath project changes.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 The Windows release workflow validates a dedicated SignPath artifact-configuration secret/input.
- [ ] #2 Every SignPath submission attempt passes `artifact-configuration-slug`.
- [ ] #3 Regression coverage fails if the explicit SignPath artifact-configuration binding is removed.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing workflow regression test for the explicit SignPath artifact-configuration slug.
2. Patch the Windows signing secret validation and SignPath action inputs to require the slug.
3. Run targeted release-workflow verification plus the standard fast lane.
4. Cut a new patch release so the tag-triggered release workflow runs with the pinned SignPath configuration.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added regression coverage in `src/release-workflow.test.ts` for an explicit SignPath artifact-configuration slug so the release workflow test now fails if the slug validation or action input is removed.
Patched `.github/workflows/release.yml` so Windows signing now requires `SIGNPATH_ARTIFACT_CONFIGURATION_SLUG` during secret validation and passes `artifact-configuration-slug: ${{ secrets.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}` on every SignPath submission attempt.
Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
The release workflow is now pinned to an explicit SignPath artifact configuration instead of relying on whichever SignPath artifact config is marked default in the UI. Windows signing secret validation fails fast if `SIGNPATH_ARTIFACT_CONFIGURATION_SLUG` is missing, and every SignPath submission attempt now includes the pinned slug.
Validation: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
<!-- SECTION:FINAL_SUMMARY:END -->

58
backlog/tasks/task-137 - Cut-patch-release-v0.5.2-for-SignPath-artifact-config-pinning.md
View File

@@ -1,58 +0,0 @@
---
id: TASK-137
title: Cut patch release v0.5.2 for SignPath artifact config pinning
status: Done
assignee:
- codex
created_date: '2026-03-08 20:44'
updated_date: '2026-03-18 05:28'
labels:
- release
- patch
dependencies:
- TASK-136
references:
- package.json
- CHANGELOG.md
- release/release-notes.md
priority: high
ordinal: 50500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Publish a patch release from the SignPath artifact-configuration pinning change by bumping the app version, generating the committed changelog artifacts for the new version, and pushing a new `v0.5.2` tag.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Repository version metadata is updated to `0.5.2`.
- [ ] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.2` section and consumed fragments are removed.
- [ ] #3 New `v0.5.2` commit and tag are pushed to `origin`.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add the release fragment for the SignPath configuration pinning change.
2. Bump `package.json` to `0.5.2` and run the changelog builder.
3. Run changelog/typecheck/test verification.
4. Commit the release-prep change set, create `v0.5.2`, and push commit plus tag.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Bumped `package.json` from `0.5.1` to `0.5.2`, ran `bun run changelog:build`, and committed the generated release artifacts. That prepended the `v0.5.2` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed `changes/signpath-artifact-config-pin.md` fragment.
Verification before tagging: `bun run changelog:lint`, `bun run changelog:check --version 0.5.2`, `bun run typecheck`, and `bun run test:fast`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Prepared patch release `v0.5.2` so the explicit SignPath artifact-configuration pin ships on a fresh release tag. Version metadata, committed changelog artifacts, and release notes are aligned with the new patch version.
Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.2`, `bun run typecheck`, `bun run test:fast`.
<!-- SECTION:FINAL_SUMMARY:END -->

64
backlog/tasks/task-138 - Publish-unsigned-Windows-release-artifacts-and-add-local-unsigned-build-script.md
View File

@@ -1,64 +0,0 @@
---
id: TASK-138
title: Publish unsigned Windows release artifacts and add local unsigned build script
status: Done
assignee:
- codex
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- release
- windows
dependencies: []
references:
- .github/workflows/release.yml
- package.json
- src/release-workflow.test.ts
priority: high
ordinal: 45500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Stop the tag-driven release workflow from depending on SignPath and publish unsigned Windows `.exe` and `.zip` artifacts directly. Add an explicit local `build:win:unsigned` script without changing the existing `build:win` command.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Windows release CI builds unsigned artifacts without requiring SignPath secrets.
- [x] #2 The Windows release job uploads `release/*.exe` and `release/*.zip` directly as the `windows` artifact.
- [x] #3 The repo exposes a local `build:win:unsigned` script for explicit unsigned Windows packaging.
- [x] #4 Regression coverage fails if the workflow reintroduces SignPath submission or drops the unsigned script.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Update workflow regression tests to assert unsigned Windows release behavior and the new local script.
2. Patch `package.json` to add `build:win:unsigned`.
3. Patch `.github/workflows/release.yml` to build unsigned Windows artifacts and upload them directly.
4. Add the release changelog fragment and run focused verification.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Removed the Windows SignPath secret validation and submission steps from `.github/workflows/release.yml`. The Windows release job now runs `bun run build:win:unsigned` and uploads `release/*.exe` and `release/*.zip` directly as the `windows` artifact consumed by the release job.
Added `scripts/build-win-unsigned.mjs` plus the `build:win:unsigned` package script. The wrapper clears Windows code-signing environment variables and disables identity auto-discovery before invoking `electron-builder`, so release CI stays unsigned even if signing credentials are configured elsewhere.
Updated `src/release-workflow.test.ts` to assert the unsigned workflow contract and added the release changelog fragment in `changes/unsigned-windows-release-builds.md`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Windows release CI now publishes unsigned artifacts directly and no longer depends on SignPath. Local developers also have an explicit `bun run build:win:unsigned` path for unsigned packaging without changing the existing `build:win` command.
Verification:
- `bun test src/release-workflow.test.ts`
- `bun run typecheck`
- `node --check scripts/build-win-unsigned.mjs`
<!-- SECTION:FINAL_SUMMARY:END -->

58
backlog/tasks/task-139 - Cut-patch-release-v0.5.3-for-unsigned-Windows-release-builds.md
View File

@@ -1,58 +0,0 @@
---
id: TASK-139
title: Cut patch release v0.5.3 for unsigned Windows release builds
status: Done
assignee:
- codex
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- release
- patch
dependencies:
- TASK-138
references:
- package.json
- CHANGELOG.md
- release/release-notes.md
priority: high
ordinal: 46500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Publish a patch release from the unsigned Windows release-build change by bumping the app version, generating committed changelog artifacts for `v0.5.3`, and pushing the release-prep commit.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Repository version metadata is updated to `0.5.3`.
- [x] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.3` section and consumed fragments are removed.
- [x] #3 New `v0.5.3` release-prep commit is pushed to `origin/main`.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Bump `package.json` from `0.5.2` to `0.5.3`.
2. Run `bun run changelog:build` so committed changelog artifacts match the new patch version.
3. Run changelog/typecheck/test verification.
4. Commit the release-prep change set and push `main`.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Bumped `package.json` from `0.5.2` to `0.5.3`, ran `bun run changelog:build`, and committed the generated release artifacts. That prepended the `v0.5.3` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed `changes/unsigned-windows-release-builds.md` fragment.
Verification before push: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, and `bun run test:fast`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Prepared patch release `v0.5.3` so the unsigned Windows release-build change is captured in committed release metadata on `main`. Version metadata, changelog output, and release notes are aligned with the new patch version.
Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, `bun run test:fast`.
<!-- SECTION:FINAL_SUMMARY:END -->

41
backlog/tasks/task-140 - Fix-guessit-title-parsing-for-character-dictionary-sync.md
View File

@@ -1,41 +0,0 @@
---
id: TASK-140
title: Fix guessit title parsing for character dictionary sync
status: Done
assignee: []
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- dictionary
- anilist
- bug
- guessit
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/src/core/services/anilist/anilist-updater.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/core/services/anilist/anilist-updater.test.ts
priority: high
ordinal: 44500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix AniList character dictionary auto-sync for filenames where `guessit` misparses the full path and our title extraction keeps only the first array segment, causing AniList resolution to match the wrong anime and abort merged dictionary refresh.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 AniList media guessing passes basename-only targets to `guessit` so parent folder names do not corrupt series title detection.
- [x] #2 Guessit title arrays are combined into one usable title instead of truncating to the first segment.
- [x] #3 Regression coverage includes the Bunny Girl Senpai filename shape that previously resolved to the wrong AniList entry.
- [x] #4 Verification confirms the targeted AniList guessing tests pass.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Root repro: `guessit` parsed the Bunny Girl Senpai full path as `title: ["Rascal", "Does-not-Dream-of-Bunny-Girl-Senapi"]`, and our `firstString` helper kept only `Rascal`, which resolved to AniList 3490 (`rayca`) and produced zero character results. Fixed by sending basename-only input to `guessit` and joining multi-part guessit title arrays.
<!-- SECTION:NOTES:END -->

38
backlog/tasks/task-141 - Refresh-current-subtitle-after-character-dictionary-sync-completes.md
View File

@@ -1,38 +0,0 @@
---
id: TASK-141
title: Refresh current subtitle after character dictionary sync completes
status: Done
assignee: []
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- dictionary
- overlay
- bug
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
- /home/sudacode/projects/japanese/SubMiner/src/main.ts
priority: high
ordinal: 42500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
When character dictionary auto-sync finishes after startup tokenization, invalidate cached subtitle tokenization and refresh the current subtitle so character-name highlighting catches up without waiting for the next subtitle line.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Successful character dictionary sync exposes a completion hook for main runtime follow-up.
- [x] #2 Main runtime clears Yomitan parser caches and refreshes the current subtitle after sync completion.
- [x] #3 Regression coverage verifies the sync completion callback fires on successful sync.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Observed on Bunny Girl Senpai startup: autoplay/tokenization became ready around 8s, but snapshot/import/state write completed roughly 31s after launch, leaving the current subtitle tokenized without the newly imported character dictionary. Fixed by adding an auto-sync completion hook that clears parser caches and refreshes the current subtitle.
<!-- SECTION:NOTES:END -->

40
backlog/tasks/task-142 - Show-character-dictionary-auto-sync-progress-on-OSD.md
View File

@@ -1,40 +0,0 @@
---
id: TASK-142
title: Show character dictionary auto-sync progress on OSD
status: Done
assignee: []
created_date: '2026-03-09 01:10'
updated_date: '2026-03-18 05:28'
labels:
- dictionary
- overlay
- ux
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync-notifications.ts
- /home/sudacode/projects/japanese/SubMiner/src/main.ts
priority: medium
ordinal: 41500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
When character dictionary auto-sync runs for a newly opened anime, surface progress so users know why character-name lookup/highlighting is temporarily unavailable via the mpv OSD without desktop notification popups.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Character dictionary auto-sync emits progress events for syncing, importing, ready, and failure states.
- [x] #2 Main runtime routes those progress events through OSD notifications without desktop notifications.
- [x] #3 Regression coverage verifies progress events and notification routing behavior.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
OSD now shows auto-sync phase changes while the dictionary updates. Desktop notifications were removed for this path to avoid startup popup spam.
<!-- SECTION:NOTES:END -->

44
backlog/tasks/task-144 - Sequence-startup-OSD-notifications-for-tokenization-annotations-and-character-dictionary-sync.md
View File

@@ -1,44 +0,0 @@
---
id: TASK-144
title: >-
Sequence startup OSD notifications for tokenization, annotations, and
character dictionary sync
status: Done
assignee: []
created_date: '2026-03-09 10:40'
updated_date: '2026-03-18 05:28'
labels:
- startup
- overlay
- ux
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/main.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/startup-osd-sequencer.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/subtitle-tokenization-main-deps.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync-notifications.ts
priority: medium
ordinal: 37500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Keep startup OSD progress ordered. While tokenization is still pending, only show the tokenization loading message. After tokenization becomes ready, show annotation loading if annotation warmup still remains. Only surface character dictionary auto-sync progress after annotation loading clears, and only if the dictionary work is still active.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Character dictionary progress stays hidden while tokenization startup loading is still active.
- [x] #2 Annotation loading OSD appears after tokenization readiness and before any later character dictionary progress.
- [x] #3 Regression coverage verifies buffered dictionary progress/failure ordering during startup.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added a small startup OSD sequencer in main runtime. Annotation warmup OSD now flows through that sequencer, and character dictionary sync notifications buffer until tokenization plus annotation loading clear. Buffered `ready` updates are dropped if dictionary progress finished before it ever became visible, while buffered failures still surface after annotation loading completes.
<!-- SECTION:NOTES:END -->

44
backlog/tasks/task-145 - Show-checking-and-generation-OSD-for-character-dictionary-auto-sync.md
View File

@@ -1,44 +0,0 @@
---
id: TASK-145
title: Show checking and generation OSD for character dictionary auto-sync
status: Done
assignee: []
created_date: '2026-03-09 11:20'
updated_date: '2026-03-16 05:13'
labels:
- dictionary
- overlay
- ux
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/main.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/startup-osd-sequencer.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
priority: medium
ordinal: 35500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Surface an immediate startup OSD that the character dictionary is being checked, and show a distinct generating message only when the current AniList media actually needs a fresh snapshot build instead of reusing a cached one.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Auto-sync emits a `checking` progress event before snapshot resolution completes.
- [x] #2 Auto-sync emits `generating` only for snapshot cache misses and keeps `updating`/`importing` as later phases.
- [x] #3 Startup OSD sequencing still prioritizes tokenization then annotation loading before buffered dictionary progress.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Character dictionary auto-sync now emits `Checking character dictionary...` as soon as the AniList media is resolved, then emits `Generating character dictionary...` only when the snapshot layer misses and a real rebuild begins. Cached snapshots skip the generating phase and continue straight into the later update/import flow.
Wired those progress callbacks through the character-dictionary runtime boundary, updated the startup OSD sequencer to treat checking/generating as dictionary-progress phases with the same tokenization and annotation precedence, and added regression coverage for cache-hit vs cache-miss behavior plus buffered startup ordering.
<!-- SECTION:FINAL_SUMMARY:END -->

59
backlog/tasks/task-146 - Forward-overlay-Tab-to-mpv-for-AniSkip.md
View File

@@ -1,59 +0,0 @@
---
id: TASK-146
title: Forward overlay Tab to mpv for AniSkip
status: Done
assignee:
- codex
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- bug
- overlay
- aniskip
- linux
dependencies: []
ordinal: 47500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix visible-overlay keyboard handling so bare `Tab` is forwarded to mpv instead of being consumed by Electron focus navigation. This restores the default AniSkip `TAB` binding while the overlay has focus, especially on Linux.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Visible overlay forwards bare `Tab` to mpv as `keypress TAB`.
- [x] #2 Modal overlays keep their existing local `Tab` behavior.
- [x] #3 Automated regression coverage exists for the input handler and overlay factory wiring.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing regression around visible-overlay `before-input-event` handling for bare `Tab`.
2. Add/extend overlay factory tests so the new mpv-forward callback is wired through runtime construction.
3. Patch overlay input handling to intercept visible-overlay `Tab` and send mpv `keypress TAB`.
4. Run focused overlay tests, typecheck, and changelog validation.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Extracted visible-overlay input handling into `src/core/services/overlay-window-input.ts` so the `Tab` forwarding decision can be unit tested without loading Electron window primitives.
Visible overlay `before-input-event` now intercepts bare `Tab`, prevents the browser default, and forwards mpv `keypress TAB` through the existing mpv runtime command path. Modal overlays remain unchanged.
Verification:
- `bun test src/core/services/overlay-window.test.ts src/main/runtime/overlay-window-factory.test.ts src/main/runtime/overlay-window-factory-main-deps.test.ts src/main/runtime/overlay-window-runtime-handlers.test.ts`
- `bun x tsc --noEmit`
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Visible overlay focus no longer blocks the default AniSkip `Tab` binding. Bare `Tab` is now forwarded straight to mpv while the visible overlay is active, and modal overlays still retain their own normal focus behavior.
Added regression coverage for both the input-routing decision and the runtime plumbing that carries the new mpv forwarder into overlay window creation.
<!-- SECTION:FINAL_SUMMARY:END -->

39
backlog/tasks/task-148 - Fix-Windows-plugin-env-binary-override-resolution.md
View File

@@ -1,39 +0,0 @@
---
id: TASK-148
title: Fix Windows plugin env binary override resolution
status: Done
assignee:
- codex
created_date: '2026-03-09 00:00'
updated_date: '2026-03-18 05:28'
labels:
- windows
- plugin
- regression
dependencies: []
priority: medium
ordinal: 48500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the mpv plugin's Windows binary override lookup so `SUBMINER_BINARY_PATH` still resolves when `SUBMINER_APPIMAGE_PATH` is unset. The current Lua resolver builds an array with a leading `nil`, which causes `ipairs` iteration to stop before the later Windows override candidate.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 `scripts/test-plugin-binary-windows.lua` passes the env override regression that expects `.exe` suffix resolution from `SUBMINER_BINARY_PATH`.
- [x] #2 Existing plugin start/binary test gate stays green after the fix.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Updated `plugin/subminer/binary.lua` so env override lookup checks `SUBMINER_APPIMAGE_PATH` and `SUBMINER_BINARY_PATH` sequentially instead of via a Lua array literal that truncates at the first `nil`. This restores Windows `.exe` suffix resolution for `SUBMINER_BINARY_PATH` when the AppImage env var is unset.
Verification:
- `lua scripts/test-plugin-binary-windows.lua`
- `bun run test:plugin:src`
<!-- SECTION:FINAL_SUMMARY:END -->

72
backlog/tasks/task-149 - Cut-patch-release-v0.5.5-for-character-dictionary-updates-and-release-guarding.md
View File

@@ -1,72 +0,0 @@
---
id: TASK-149
title: Cut patch release v0.5.5 for character dictionary updates and release guarding
status: Done
assignee:
- codex
created_date: '2026-03-09 01:10'
updated_date: '2026-03-18 05:28'
labels:
- release
- patch
dependencies:
- TASK-140
- TASK-141
- TASK-142
- TASK-143
- TASK-144
- TASK-145
- TASK-146
- TASK-148
references:
- package.json
- CHANGELOG.md
- scripts/build-changelog.ts
- scripts/build-changelog.test.ts
- docs/RELEASING.md
priority: high
ordinal: 39500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Prepare and publish patch release `v0.5.5` after the failed `v0.5.4` tag by aligning package version metadata, generating committed changelog output from the pending release fragments, and hardening release validation so a future tag cannot ship with a mismatched `package.json` version.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Repository version metadata is updated to `0.5.5`.
- [x] #2 `CHANGELOG.md` contains the committed `v0.5.5` section and the consumed fragments are removed.
- [x] #3 Release validation rejects a requested release version when it differs from `package.json`.
- [x] #4 Release docs capture the required version/changelog prep before tagging.
- [x] #5 New `v0.5.5` release-prep commit and tag are pushed to `origin/main`.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a regression test for tagged-release/package version mismatch.
2. Update changelog validation to reject mismatched explicit release versions.
3. Bump `package.json`, generate committed `v0.5.5` changelog output, and remove consumed fragments.
4. Add a short `docs/RELEASING.md` checklist for the prep flow.
5. Run release verification, commit, tag, and push.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added a regression test in `scripts/build-changelog.test.ts` that proves `changelog:check --version ...` rejects tag/package mismatches. Updated `scripts/build-changelog.ts` so tagged release validation now compares the explicit requested version against `package.json` before looking for pending fragments or the committed changelog section.
Bumped `package.json` from `0.5.3` to `0.5.5`, ran `bun run changelog:build --version 0.5.5 --date 2026-03-09`, and committed the generated `CHANGELOG.md` output while removing the consumed task fragments. Added `docs/RELEASING.md` with the required release-prep checklist so version bump + changelog generation happen before tagging.
Verification: `bun run changelog:lint`, `bun run changelog:check --version 0.5.5`, `bun run typecheck`, `bun run test:fast`, and `bun test scripts/build-changelog.test.ts src/release-workflow.test.ts`. `bun run format:check` still reports many unrelated pre-existing repo-wide Prettier warnings, so touched files were checked/formatted separately with `bunx prettier`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Prepared patch release `v0.5.5` after the failed `v0.5.4` release attempt. Release metadata now matches the upcoming tag, the pending character-dictionary/overlay/plugin fragments are committed into `CHANGELOG.md`, and release validation now blocks future tag/package mismatches before publish.
Docs now include a short release checklist in `docs/RELEASING.md`. Validation passed for changelog lint/check, typecheck, targeted workflow tests, and the full fast test suite. Repo-wide Prettier remains noisy from unrelated existing files, but touched release files were formatted and verified.
<!-- SECTION:FINAL_SUMMARY:END -->

60
backlog/tasks/task-150 - Restore-repo-wide-Prettier-cleanliness-after-release-prep.md
View File

@@ -1,60 +0,0 @@
---
id: TASK-150
title: Restore repo-wide Prettier cleanliness after release prep
status: Done
assignee:
- codex
created_date: '2026-03-09 01:11'
updated_date: '2026-03-18 05:28'
labels:
- tooling
- formatting
dependencies: []
references:
- backlog/config.yml
- backlog/tasks
- config.example.jsonc
- launcher/types.ts
- launcher/util.ts
- launcher/youtube/orchestrator.ts
- scripts/build-win-unsigned.mjs
- src
priority: medium
ordinal: 40500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Bring `bun run format:check` back to green after the `v0.5.5` release-prep work exposed repo-wide Prettier drift across backlog markdown, config files, and maintained TypeScript sources.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 `bun run format:check` passes.
- [x] #2 `bun run changelog:lint` still passes.
- [x] #3 Typecheck and fast tests stay green after the formatting-only rewrite.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Re-run format and lint checks to confirm failing files.
2. Apply Prettier to the warned repo-managed files.
3. Re-run formatting, lint, typecheck, and fast tests.
4. Commit and push the formatting-only cleanup.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Ran `bunx prettier --write` across the repo-managed files reported by `bun run format:check`, covering backlog markdown/YAML, `config.example.jsonc`, selected launcher/scripts files, and maintained TypeScript sources under `src/`.
Verification: `bun run format:check`, `bun run changelog:lint`, `bun run typecheck`, and `bun run test:fast`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Repo-wide Prettier drift is cleaned up, including backlog task markdown, config/example files, and the maintained code files that `format:check` was flagging. Formatting and lint checks are green again, and typecheck/fast tests stayed green after the formatting-only rewrite.
<!-- SECTION:FINAL_SUMMARY:END -->

100
backlog/tasks/task-151 - Keep-JLPT-underline-color-stable-during-Yomitan-text-selection.md
View File

@@ -1,100 +0,0 @@
---
id: TASK-151
title: Keep JLPT underline color stable during Yomitan text selection
status: Done
assignee:
- OpenCode
created_date: '2026-03-10 06:42'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
references:
- src/renderer/style.css
- src/renderer/subtitle-render.test.ts
documentation:
- ../subminer-docs/development.md
- ../subminer-docs/architecture.md
priority: medium
ordinal: 33500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the subtitle overlay so JLPT underlines keep their JLPT color when Yomitan lookups trigger hover/selection styling on tokens that are also known, N+1, or frequency-highlighted.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 JLPT-tagged subtitle tokens keep their JLPT underline color during hover/selection states used by Yomitan lookup.
- [x] #2 Tokens that combine JLPT with known, N+1, name-match, or frequency styling preserve their primary text color while keeping the JLPT underline color.
- [x] #3 Renderer regression coverage verifies the JLPT underline color remains explicit in the stylesheet for combined styling states.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Revert the temporary box-shadow JLPT marker experiment and restore native JLPT underline styling in `src/renderer/style.css`.
2. Add explicit JLPT hover/selection color rules with higher specificity so Yomitan lookup highlight states cannot repaint the underline to the token hover color.
3. Update `src/renderer/subtitle-render.test.ts` to verify JLPT hover/selection rules keep the predefined JLPT underline color, then rerun focused and relevant verification commands.
4. Add JLPT-specific `text-decoration-color` overrides directly on child `.c` spans and their hover/selection states, since Yomitan lookup likely paints the decorated child text runs rather than only the parent token span.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added a renderer regression test that asserts JLPT underline color stays explicit through hover and selection styling.
Updated `src/renderer/style.css` to route JLPT underline color through `--subtitle-jlpt-underline-color` and re-apply it on word/character hover and selection states.
Verification: `bun test src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run test:fast`, `bun run build`, `bun run changelog:lint`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts changes/jlpt-underline-yomitan.md`. `bun run format:check:src` still fails because of unrelated existing formatting issues in `src/main-entry-runtime.test.ts` and `src/main-entry-runtime.ts`.
User verified the original CSS variable propagation fix did not resolve the live issue; continuing investigation and reopening the task.
Confirmed Chromium was repainting native `text-decoration` underlines with the selected text color; reproduced it in a temporary browser repro and verified that switching the JLPT marker to an inset box-shadow keeps the JLPT color stable during selection.
Replaced the previous native underline approach with a fragment-safe JLPT marker using `box-shadow` plus `box-decoration-break`, then updated stylesheet regression coverage to match the new implementation.
Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run test:fast`, `bun run build`.
User requested reverting the box-shadow marker experiment. Narrowing the fix to preserve native JLPT underline color during Yomitan hover/selection instead of changing the underline rendering method.
Reverted the box-shadow experiment per user request. Restored native JLPT underline styling and added explicit JLPT hover/selection rules so Yomitan lookup states keep the predefined JLPT underline color with `!important`.
Verification after revert/fix: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run build`.
Issue still reproduces specifically during Shift-held Yomitan lookup. Investigating decoration propagation onto child `.c` spans during lookup-triggered hover/selection states.
Added JLPT-specific `text-decoration-color` overrides directly to child `.c` spans and their hover/selection states, in addition to the token span itself, so lookup-triggered decoration painting on child runs keeps the JLPT color.
Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run build`.
Added a final high-specificity combined-state JLPT override after the annotation hover/selection rules. It targets tokens that are both JLPT-tagged and known/N+1/name-match/frequency-highlighted, forcing `text-decoration-color` back to the JLPT variable after the later annotation state blocks.
Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run build`.
Switched the JLPT underline from native `text-decoration` to a separate painted underline layer using `background-image` on JLPT tokens. Also changed hover token highlight rules to use `background-color` so the JLPT underline layer survives Shift+Yomitan hover/lookup interactions.
Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run build`.
User reports the latest background-image JLPT underline change introduced grey-looking token highlights. Investigating the interaction between the new underline layer and hover background styling.
The background-image underline layer interacts poorly with hover fills and makes highlighted tokens look grey. Switching the separate JLPT underline layer to an inset box-shadow so hover background color and JLPT underline paint can coexist cleanly.
Adjusted the separate JLPT underline layer from `background-image` to inset `box-shadow`. This keeps the underline decoupled from Yomitan hover color while avoiding the grey-looking underline artifact introduced by the background-image approach.
User reports the separate underline layer still disappears/greys out during lookup. Switching strategy again: use a dedicated `border-bottom` JLPT marker instead of box-shadow/background so the underline stays independent from Yomitan hover paint without blending artifacts.
Replaced the separate JLPT underline layer with `border-bottom` plus a small bottom padding. This keeps the underline visually separate from Yomitan hover paint and avoids the disappearing/grey artifact seen with background-image and box-shadow.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Switched the JLPT underline layer in `src/renderer/style.css` to `border-bottom` plus `padding-bottom`, keeping it independent from Yomitan hover/selection repainting while avoiding the disappearing or grey artifact seen with the background-image and box-shadow approaches.
Updated `src/renderer/subtitle-render.test.ts` to assert the border-bottom-based JLPT underline layer.
Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run build`.
<!-- SECTION:FINAL_SUMMARY:END -->

66
backlog/tasks/task-152 - Fix-early-Electron-userData-path-casing-to-stay-under-SubMiner-config-dir.md
View File

@@ -1,66 +0,0 @@
---
id: TASK-152
title: Fix early Electron userData path casing to stay under SubMiner config dir
status: Done
assignee:
- codex
created_date: '2026-03-10 06:46'
updated_date: '2026-03-16 05:13'
labels:
- bug
- config
- electron
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/main-entry.ts
- /home/sudacode/projects/japanese/SubMiner/src/main.ts
- /home/sudacode/projects/japanese/SubMiner/src/config/path-resolution.ts
documentation:
- /home/sudacode/projects/japanese/subminer-docs/development.md
- /home/sudacode/projects/japanese/subminer-docs/architecture.md
priority: high
ordinal: 34500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Electron startup touches the app object before the main-process bootstrap overrides userData, which can create/write the default lowercase ~/.config/subminer directory on Linux/macOS. Ensure early startup pins the app identity and userData path to the canonical SubMiner config directory before any Electron APIs can materialize the default path, and keep regression coverage around the bootstrap path behavior.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Electron startup uses the canonical SubMiner config directory as userData before other Electron app calls can create the default lowercase directory.
- [x] #2 Regression tests cover the early bootstrap path setup and fail if startup falls back to a lowercase subminer config path.
- [x] #3 Existing config path resolution behavior for SubMiner casing remains intact.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add regression coverage for early Electron bootstrap path setup, including a case that would otherwise fall back to lowercase subminer.
2. Extract a pure helper that computes and applies the canonical app name/userData path from config resolution.
3. Call the helper from main-entry before any Electron app interactions that could materialize the default userData directory.
4. Run focused tests for startup/config path behavior, then the relevant fast gate if green.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added early Electron bootstrap path setup in src/main-entry so app name and userData are pinned to the canonical SubMiner config dir before single-instance/whenReady handling.
Added a regression test in src/main-entry-runtime.test.ts covering the lowercase subminer fallback case.
Validation: bun test src/main-entry-runtime.test.ts src/config/path-resolution.test.ts; bun run typecheck. bun run test:fast still fails on an existing unrelated renderer JLPT CSS test in src/renderer/subtitle-render.test.ts.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Pinned Electron's app identity and userData path during entry bootstrap so startup uses the canonical SubMiner config directory before any other Electron app calls can materialize the default lowercase path. Added a regression test covering the lowercase subminer fallback case and kept existing config-path resolution coverage green.
Validation:
- bun test src/main-entry-runtime.test.ts src/config/path-resolution.test.ts
- bun run typecheck
- bun run test:fast (fails on existing unrelated JLPT CSS renderer test in src/renderer/subtitle-render.test.ts)
<!-- SECTION:FINAL_SUMMARY:END -->

69
backlog/tasks/task-153 - Fix-character-dictionary-MRU-eviction-after-revisits.md
View File

@@ -1,69 +0,0 @@
---
id: TASK-153
title: Fix character dictionary MRU eviction after revisits
status: Done
assignee:
- '@codex'
created_date: '2026-03-10 07:56'
updated_date: '2026-03-16 05:13'
labels:
- character-dictionary
- yomitan
- anilist
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.test.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
documentation:
- /home/sudacode/projects/japanese/subminer-docs/development.md
- /home/sudacode/projects/japanese/subminer-docs/architecture.md
priority: high
ordinal: 32500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Keep merged character dictionary retention truly MRU-based when a currently retained anime is revisited before opening a new title, so the oldest retained title is evicted instead of the revisited one.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Revisiting an anime already retained in the merged character dictionary updates MRU ordering before the next new title is added.
- [x] #2 When retention exceeds maxLoaded after that revisit-plus-new-title sequence, the least recently used retained anime is evicted rather than the revisited title.
- [x] #3 Auto-sync rebuilds or reloads the merged dictionary so an evicted anime becomes available again when reopened.
- [x] #4 Regression tests cover the revisit-before-eviction flow.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Reproduce the revisit-before-eviction scenario with a focused regression test in `src/main/runtime/character-dictionary-auto-sync.test.ts` using a retained set that revisits an existing anime before introducing a new anime.
2. Run the focused test to confirm current behavior fails for the expected MRU ordering / eviction case.
3. Adjust `src/main/runtime/character-dictionary-auto-sync.ts` so retained ordering stays MRU-correct across revisits and subsequent additions without regressing unchanged revisit behavior.
4. Re-run the focused auto-sync suite, then run the relevant broader checks required for handoff.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added a focused regression in `src/main/runtime/character-dictionary-auto-sync.test.ts` for the `1,2,3,1,4,1` revisit-before-eviction flow. The current MRU auto-sync logic passed: merged builds were `[1]`, `[2,1]`, `[3,2,1]`, `[1,3,2]`, `[4,1,3]`, `[1,4,3]`, so I have not reproduced the reported eviction bug in the in-process auto-sync service yet.
Inspected local cache under `~/.config/SubMiner/character-dictionaries/` and found Little Witch Academia snapshot `anilist-21858.json` already present, so the reported regeneration path was not a snapshot-cache miss. The on-disk `merged.zip` revision (`9251ae23e136`) also differed from `auto-sync-state.json` (`bc16c5b5af17`), indicating a rebuilt merged dictionary artifact could land without the MRU state being persisted.
Fixed `src/main/runtime/character-dictionary-auto-sync.ts` to persist the rebuilt retained-set state immediately after a merged dictionary revision/title is known, before later Yomitan mutation steps. This keeps MRU eviction state aligned even if import/settings work fails after the rebuild artifact is written.
Added regression coverage in `src/main/runtime/character-dictionary-auto-sync.test.ts` for the revisit-before-eviction sequence and for post-build import failure preserving the rebuilt MRU state. Verified with `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, and `bun run test:fast`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Persisted merged character-dictionary MRU state as soon as a rebuilt retained set is known in `src/main/runtime/character-dictionary-auto-sync.ts`, so revisits are not lost if later Yomitan import/settings work fails after `merged.zip` has already been rewritten. Added regression coverage for revisit-before-eviction ordering and import-failure state preservation in `src/main/runtime/character-dictionary-auto-sync.test.ts`, plus a changelog fragment in `changes/character-dictionary-mru-state-recovery.md`.
Validation: `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, `bun run test:fast`.
<!-- SECTION:FINAL_SUMMARY:END -->

69
backlog/tasks/task-154 - Avoid-merged-dictionary-rebuilds-on-MRU-reorder-only-revisits.md
View File

@@ -1,69 +0,0 @@
---
id: TASK-154
title: Avoid merged dictionary rebuilds on MRU reorder-only revisits
status: Done
assignee:
- '@codex'
created_date: '2026-03-10 09:16'
updated_date: '2026-03-16 05:13'
labels:
- character-dictionary
- yomitan
- anilist
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.test.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.test.ts
documentation:
- /home/sudacode/projects/japanese/subminer-docs/development.md
- /home/sudacode/projects/japanese/subminer-docs/architecture.md
priority: high
ordinal: 31500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Keep per-title MRU retention ordering for eviction decisions, but do not rebuild or reimport the merged character dictionary when the retained set membership is unchanged and only the MRU order changes.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Revisiting an anime already inside the retained set updates MRU ordering used for later eviction decisions without rebuilding or reimporting the merged dictionary when retained membership is unchanged.
- [x] #2 Merged dictionary revisions and contents are stable for the same retained membership regardless of MRU ordering.
- [x] #3 Adding a new anime that changes retained membership still rebuilds and imports the merged dictionary with the correct eviction behavior.
- [x] #4 Regression tests cover reorder-only revisits and stable merged revisions for equivalent retained sets.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing auto-sync regression showing that a revisit which only reorders MRU state should update `activeMediaIds` but skip merged rebuild/import.
2. Add a runtime-level regression showing `buildMergedDictionary` produces a stable revision for equivalent retained memberships regardless of input order.
3. Update merged-dictionary build normalization and auto-sync rebuild gating so rebuilds are driven by retained membership changes (or snapshot changes), not MRU reordering alone.
4. Re-run focused dictionary tests plus the local verification lanes impacted by the change.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Changed `src/main/runtime/character-dictionary-auto-sync.ts` so MRU order still updates in `activeMediaIds`, but merged rebuild/import now keys off retained membership changes rather than order-only reordering. Order-only revisits no longer force a merged ZIP rewrite or Yomitan reimport.
Changed `src/main/character-dictionary-runtime.ts` to canonicalize merged dictionary media ids before building, which makes merged revisions stable for equivalent retained memberships regardless of MRU ordering.
Updated regression coverage in `src/main/runtime/character-dictionary-auto-sync.test.ts` for reorder-only revisits and membership-change rebuilds, and extended `src/main/character-dictionary-runtime.test.ts` to assert stable merged revisions for reordered inputs. Verified with `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, and `bun run test:fast`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Updated merged character-dictionary syncing so MRU ordering is still tracked for eviction in `src/main/runtime/character-dictionary-auto-sync.ts`, but reorder-only revisits no longer rebuild or reimport the merged dictionary unless retained membership or snapshot data changes. Canonicalized merged build input ordering in `src/main/character-dictionary-runtime.ts` so revisions remain stable for the same retained set regardless of MRU order, and added regressions in `src/main/runtime/character-dictionary-auto-sync.test.ts` plus `src/main/character-dictionary-runtime.test.ts`. Also updated `changes/character-dictionary-mru-state-recovery.md` to cover the new behavior.
Validation: `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, `bun run test:fast`.
<!-- SECTION:FINAL_SUMMARY:END -->

37
backlog/tasks/task-156 - Fix-docs-site-Plausible-geo-attribution-through-analytics-worker.md
View File

@@ -1,37 +0,0 @@
---
id: TASK-156
title: Fix docs-site Plausible geo attribution through analytics worker
status: Done
assignee: []
created_date: '2026-03-11 02:19'
updated_date: '2026-03-16 05:13'
labels:
- docs-site
- analytics
dependencies: []
priority: medium
ordinal: 99500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Investigate and fix missing city/region data for docs.subminer.moe visits in Plausible. The docs site already proxies analytics events to worker.subminer.moe, so the remaining work is to verify and correct the worker-side forwarding contract Plausible needs for geolocation.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 The analytics worker forwards Plausible event requests in a way that preserves the original client IP information needed for location attribution.
- [ ] #2 The docs-site analytics flow remains proxied through worker.subminer.moe after the fix.
- [ ] #3 Coverage or documentation records the worker-side header/forwarding requirement for Plausible geo reporting.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Worker implementation lives in `/home/sudacode/projects/blog-proxy`, not in the SubMiner repo.
Patched `worker.js` to forward client IP via `x-forwarded-for`/`x-real-ip` from `cf-connecting-ip` (fallbacks retained) and added `worker.test.js` regression coverage.
Local verification in `blog-proxy`: `node --test worker.test.js` passes. Deployment not performed in this session.
<!-- SECTION:NOTES:END -->

35
backlog/tasks/task-157 - Fix-Cloudflare-Pages-watch-path-for-docs-site.md
View File

@@ -1,35 +0,0 @@
---
id: TASK-157
title: Fix Cloudflare Pages watch path for docs-site
status: Done
assignee: []
created_date: '2026-03-10 20:15'
updated_date: '2026-03-16 05:13'
labels:
- docs-site
- cloudflare
dependencies: []
priority: medium
ordinal: 98500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Cloudflare Pages skipped a docs-site deployment after the docs repo moved into the main `SubMiner` repository. The documented/configured watch path uses `docs-site/**`, but Pages monorepo watch paths use a single `*` wildcard pattern. Correct the documented setting and leave a regression test so future repo moves or docs rewrites do not reintroduce the bad pattern.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Docs contributor guidance points Cloudflare Pages watch paths at `docs-site/*`, not `docs-site/**`.
- [x] #2 Regression coverage fails if the docs revert to the incorrect watch-path string.
- [x] #3 Implementation notes record that the Cloudflare dashboard setting must be updated manually and the docs deploy retriggered.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added docs regression coverage in `docs-site/docs-sync.test.ts` for the Pages watch-path string, then corrected the Cloudflare Pages instructions in `docs-site/README.md` and `docs-site/development.md`.
Manual follow-up still required outside git: update the Cloudflare Pages project include path from `docs-site/**` to `docs-site/*`, then trigger a fresh deployment against `main`.
<!-- SECTION:NOTES:END -->

44
backlog/tasks/task-158 - Enforce-generated-config-example-drift-checks.md
View File

@@ -1,44 +0,0 @@
---
id: TASK-158
title: Enforce generated config example drift checks
status: Done
assignee: []
created_date: '2026-03-10 20:35'
updated_date: '2026-03-16 05:13'
labels:
- config
- docs-site
dependencies: []
priority: medium
ordinal: 30500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
The generated `config.example.jsonc` artifact is covered by generation-path tests, but there is no hard gate that fails when the checked-in example drifts from the canonical template. The in-repo docs-site copy can also drift silently.
Scope:
- add a first-party verification path that compares generated config-example content against committed artifacts
- fail fast when repo-root `config.example.jsonc` is stale or missing
- fail fast when `docs-site/public/config.example.jsonc` is stale or missing, when the docs site exists
- wire the verification into the normal gate and release flow
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Automated verification fails when repo-root `config.example.jsonc` is missing or stale.
- [x] #2 Automated verification fails when in-repo docs-site `public/config.example.jsonc` is missing or stale, when docs-site exists.
- [x] #3 CI/release or equivalent project gates run the verification automatically.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added `src/verify-config-example.ts`, which renders the canonical config template and compares it against the checked-in repo-root `config.example.jsonc` plus `docs-site/public/config.example.jsonc` when the docs site exists.
Wired the new verification into `package.json` as `bun run verify:config-example`, added regression coverage for missing and stale artifacts, and enforced the new check in both CI and release workflows.
Regenerated the checked-in config example artifacts so the new gate passes in the repo-local docs-site layout, and documented the release-step expectation in `docs/RELEASING.md`.
<!-- SECTION:FINAL_SUMMARY:END -->

59
backlog/tasks/task-159 - Create-SubMiner-automated-testing-skill-for-agents.md
View File

@@ -1,59 +0,0 @@
---
id: TASK-159
title: Create SubMiner automated testing skill for agents
status: Done
assignee:
- codex
created_date: '2026-03-11 05:55'
updated_date: '2026-03-16 05:13'
labels:
- tooling
- testing
- skills
dependencies: []
priority: medium
ordinal: 29500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Design and implement a SubMiner-specific skill that agents can use to verify code changes with automated checks across launcher, mpv, overlay, and related workflows.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Define the skill trigger surface and intended use cases for SubMiner change verification.
- [x] #2 Implement a SubMiner-specific skill package with concise workflow guidance and any required helper scripts or references.
- [x] #3 Document how agents should run automated verification for common SubMiner change types, including launcher/mpv/overlay-sensitive changes.
- [x] #4 Verify the skill itself is usable in this repo context.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a design doc at `docs/plans/2026-03-10-subminer-change-verification-design.md` capturing the approved skill contract, lane selection rules, helper script design, and trigger/workflow guidance.
2. Create an in-repo source package for the new SubMiner-specific verification skill with `SKILL.md` plus helper shell scripts for diff classification and coordinated verification/artifact capture.
3. Implement cheap-first verification logic: map changed paths to verification lanes, run repo-native commands, capture stdout/stderr and metadata under `.tmp/skill-verification/<timestamp>/`, and report pass/fail/skipped states with artifact paths.
4. Encode repo-specific heuristics for docs/config, launcher/plugin, runtime/dist, and optional real-GUI escalation guidance without making GUI launch the default.
5. Verify the skill locally by running the classifier/verifier against representative paths and confirming artifact generation and summaries.
6. Optionally install the finished skill to `~/.codex/skills/subminer-change-verification/` after user approval because that target is outside the writable sandbox.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Planned outputs: SKILL.md plus small helper shell scripts for diff classification and coordinated verification/artifact capture. Default to repo-native commands; only escalate to real GUI/mpv verification when affected paths or requested behavior require it.
2026-03-10: Brainstorming completed with user approval for a SubMiner-specific automated verification skill. Chosen shape: auto-triggering, cheap-first verification workflow with optional real GUI/mpv escalation and artifact capture.
2026-03-10: Added design doc at docs/plans/2026-03-10-subminer-change-verification-design.md and created the in-repo skill source at tools/skills/subminer-change-verification/.
2026-03-10: Verified classifier output with representative launcher/runtime/config/docs paths and ran the verifier in dry-run mode plus one real config lane (`bun run test:config`). Artifacts written under .tmp/skill-verification/20260310-231320 and .tmp/skill-verification/20260310-231326.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented a SubMiner-specific change verification skill source with a concise SKILL.md, a diff classifier, and a cheap-first verifier that captures artifacts under `.tmp/skill-verification/`. Verified the flow with representative path classification, a dry-run multi-lane plan, and a passing real config verification run.
<!-- SECTION:FINAL_SUMMARY:END -->

58
backlog/tasks/task-160 - Create-repo-local-scrum-master-orchestration-skill.md
View File

@@ -1,58 +0,0 @@
---
id: TASK-160
title: Create repo-local scrum master orchestration skill
status: Done
assignee:
- codex
created_date: '2026-03-11 06:32'
updated_date: '2026-03-16 05:13'
labels:
- skills
- workflow
- backlog
- subagents
- automation
dependencies: []
priority: high
ordinal: 28500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Design and implement a repo-local skill that can turn incoming requests/issues into well-scoped Backlog tasks, then coordinate one or more subagents to implement and verify the resulting work using the repo's established skills and verification workflow.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Define the trigger surface, responsibilities, and limits of the scrum master skill for request intake, backlog updates, and execution orchestration.
- [x] #2 Implement the skill package with concise guidance for intake, task search/create/update, planning, and subagent dispatch.
- [x] #3 Specify how the skill coordinates with existing repo workflows, including Backlog.md requirements and SubMiner change verification.
- [x] #4 Verify the skill is usable in this repo context for at least one representative request flow.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a design doc at `docs/plans/2026-03-10-subminer-scrum-master-design.md` capturing the approved contract, backlog decision rules, orchestration policy, and verification handoff.
2. Create the repo-local skill at `.agents/skills/subminer-scrum-master/` with a concise `SKILL.md`.
3. Keep v1 instruction-heavy: backlog-or-not decision first, search/create/update task structure when needed, require planning before dispatch, use parent + subtasks for multi-part work, dispatch conservatively with explicit ownership, and require `subminer-change-verification` before handoff.
4. Include representative flows for trivial no-ticket work, single-task implementation, and multi-part parent+subtask execution.
5. Verify the skill in-repo with one representative request flow and update `TASK-160` with results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
V1 will be instruction-heavy rather than script-heavy. The skill will decide whether backlog is warranted, record plans before dispatch, create parent+subtasks when needed, dispatch conservatively with explicit ownership, and require `subminer-change-verification` before handoff.
2026-03-10: Added design doc at docs/plans/2026-03-10-subminer-scrum-master-design.md and created the repo-local skill at .agents/skills/subminer-scrum-master/.
2026-03-10: Verified the skill against a representative request flow ('Fix launcher auto-start pause bug and make sure it is verified') by checking that the instructions cover backlog decisioning, planning-before-dispatch, single-task execution, explicit worker ownership, and verification via subminer-change-verification.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented a repo-local `subminer-scrum-master` skill that assesses whether backlog tracking is needed, manages task structure and planning when appropriate, dispatches subagents conservatively, and requires verification before handoff. Verified the skill in-repo against a representative launcher bug workflow.
<!-- SECTION:FINAL_SUMMARY:END -->

69
backlog/tasks/task-161 - Add-Arch-Linux-PKGBUILD-and-.SRCINFO-for-SubMiner-release-artifacts.md
View File

@@ -1,69 +0,0 @@
---
id: TASK-161
title: Add Arch Linux PKGBUILD and .SRCINFO for SubMiner release artifacts
status: Done
assignee:
- codex
created_date: '2026-03-11 07:50'
updated_date: '2026-03-16 05:13'
labels:
- packaging
- linux
- docs
dependencies: []
references:
- package.json
- .github/workflows/release.yml
- README.md
documentation:
- docs-site/development.md
- docs-site/installation.md
- docs/RELEASING.md
priority: medium
ordinal: 27500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add repo-maintained Arch packaging metadata so Arch/AUR users can install the packaged SubMiner release artifacts without relying on npm. Cover the binary package flow that matches the current GitHub Releases distribution model and document the install path for Arch users.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 A dedicated Arch packaging directory exists with a PKGBUILD and matching .SRCINFO for the SubMiner binary release flow.
- [x] #2 The package installs the shipped Linux release artifact and wrapper in paths consistent with current runtime auto-detection expectations.
- [x] #3 Package metadata declares the required Arch runtime dependencies for the packaged workflow.
- [x] #4 The packaging files remain isolated from the main app/release/docs surfaces so they can be moved to a separate repository later.
- [x] #5 The packaging metadata is validated with an appropriate local Arch packaging check or an explicitly documented limitation if the tool is unavailable in this environment.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add isolated Arch packaging under packaging/arch/subminer-bin for the binary release flow that matches current GitHub Releases artifacts.
2. Install the Linux AppImage to /opt/SubMiner/SubMiner.AppImage, add PATH symlinks for SubMiner.AppImage and subminer, and ship optional plugin/theme/config assets under /usr/share/subminer.
3. Generate and commit matching .SRCINFO metadata in the same packaging directory.
4. Validate the PKGBUILD metadata locally with shell parsing plus makepkg --printsrcinfo and namcap if available.
5. Leave the new files isolated so they can be moved to a separate packaging repository later.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
User requested no commit and no broad repo integration; keep the Arch packaging files isolated in a dedicated directory for later extraction.
Created isolated Arch packaging under packaging/arch/subminer-bin with PKGBUILD and generated .SRCINFO only; no docs or release workflow changes.
Validation run: bash -n PKGBUILD, makepkg --printsrcinfo > .SRCINFO, namcap PKGBUILD.
PKGBUILD uses current v0.5.6 GitHub release assets and recorded SHA-256 values for SubMiner-0.5.6.AppImage, subminer, and subminer-assets.tar.gz.
Per user follow-up, moved packaging/arch/subminer-bin out of the repo to /home/sudacode/packages/maintaining/subminer-bin for separate maintenance. Repo docs/workflows were still left untouched.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added an isolated Arch Linux packaging directory at packaging/arch/subminer-bin containing a `subminer-bin` PKGBUILD and generated `.SRCINFO`. The package installs the current GitHub release AppImage to `/opt/SubMiner/SubMiner.AppImage`, adds PATH access for `SubMiner.AppImage` and `subminer`, and ships optional plugin/theme/config assets under `/usr/share/subminer`. Verified locally with `bash -n PKGBUILD`, `makepkg --printsrcinfo`, and `namcap PKGBUILD`.
<!-- SECTION:FINAL_SUMMARY:END -->

66
backlog/tasks/task-162 - Normalize-packaged-Linux-paths-to-canonical-SubMiner-directories.md
View File

@@ -1,66 +0,0 @@
---
id: TASK-162
title: Normalize packaged Linux paths to canonical SubMiner directories
status: Done
assignee:
- codex
created_date: '2026-03-11 08:28'
updated_date: '2026-03-18 05:28'
labels:
- linux
- packaging
- docs
dependencies: []
references:
- launcher/mpv.ts
- launcher/picker.ts
- plugin/subminer/binary.lua
- plugin/subminer.conf
- docs-site/installation.md
- docs-site/launcher-script.md
- README.md
priority: medium
ordinal: 116500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Align packaged Linux path conventions so system-installed assets use canonical `SubMiner` directories and match runtime auto-detection. Cover AppImage binary discovery, rofi theme discovery/docs, and related path references while preserving lowercase names only for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Launcher/runtime path discovery prefers canonical packaged Linux locations that use `SubMiner` casing for shared data and config directories.
- [x] #2 Tests cover the expected packaged Linux discovery paths for the AppImage and rofi theme search behavior.
- [x] #3 User-facing docs reference the canonical packaged Linux locations consistently.
- [x] #4 Lowercase names remain only where intentionally required for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing launcher tests for canonical packaged Linux discovery paths: /usr/lib/subminer/SubMiner.AppImage via PATH symlink flow and /usr/share/SubMiner/themes/subminer.rasi for rofi theme lookup.
2. Update launcher runtime path discovery to prefer canonical packaged Linux shared-data locations using SubMiner casing.
3. Update plugin auto-detection comments and binary search defaults so packaged Linux paths stay consistent with launcher/runtime expectations.
4. Update user-facing docs to reference canonical SubMiner-cased config/share paths while keeping lowercase names only for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
5. Run targeted launcher tests plus docs checks.
Remaining work (2026-03-15):
- binary.lua: add lowercase fallback candidates /usr/bin/subminer and /usr/local/bin/subminer after existing title-case entries
- launcher tests: add findAppBinary Linux candidates and findRofiTheme /usr/share + /usr/local/share tests
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
2026-03-15: Adding launcher tests for Linux packaged path discovery (findAppBinary + findRofiTheme). Implementing in mpv.test.ts and new picker.test.ts following node:test / assert/strict patterns from mpv.test.ts.
2026-03-15: AC#2 complete. Added findAppBinary tests (3) to launcher/mpv.test.ts and findRofiTheme tests (4) to new launcher/picker.test.ts. All 76 launcher tests pass. Added picker.test.ts to test:launcher:src script.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
## Completed changes\n\n### `plugin/subminer/binary.lua`\nAdded lowercase fallback candidates after existing title-case entries in the non-Windows `find_binary()` search list:\n- `/usr/local/bin/subminer` (after `/usr/local/bin/SubMiner`)\n- `/usr/bin/subminer` (after `/usr/bin/SubMiner`)\n\n### `plugin/subminer.conf`\nUpdated the comment documenting the Linux binary search list to include the two new lowercase candidates.\n\n### `launcher/mpv.test.ts`\nAdded 3 new tests for `findAppBinary` Linux candidates:\n- Resolves `~/.local/bin/SubMiner.AppImage` when it exists\n- Resolves `/opt/SubMiner/SubMiner.AppImage` when `~/.local/bin` candidate absent\n- Finds `subminer` on PATH when AppImage candidates absent\n\n### `launcher/picker.test.ts` (new file)\nAdded 4 tests for `findRofiTheme` Linux packaged paths:\n- Resolves `/usr/local/share/SubMiner/themes/subminer.rasi`\n- Resolves `/usr/share/SubMiner/themes/subminer.rasi` when `/usr/local/share` absent\n- Resolves `$XDG_DATA_HOME/SubMiner/themes/subminer.rasi` when set\n- Resolves `~/.local/share/SubMiner/themes/subminer.rasi` when `XDG_DATA_HOME` unset\n\n### `package.json`\nAdded `launcher/picker.test.ts` to `test:launcher:src` file list.\n\n## Verification\n- `launcher-plugin` lane: passed (76 launcher tests, 524 fast tests — all green)\n\n## Policy checks\n- Docs update required? No — docs already reflected canonical paths.\n- Changelog fragment required? Yes — user-visible fix to plugin binary auto-detection. Fragment should be added under `changes/`.
<!-- SECTION:FINAL_SUMMARY:END -->

74
backlog/tasks/task-163 - Resolve-current-lint-format-and-style-check-failures.md
View File

@@ -1,74 +0,0 @@
---
id: TASK-163
title: 'Resolve current lint, format, and style check failures'
status: Done
assignee:
- Codex
created_date: '2026-03-11 08:48'
updated_date: '2026-03-16 05:13'
labels:
- maintenance
- tooling
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/package.json
- /home/sudacode/projects/japanese/SubMiner/docs-site/development.md
- /home/sudacode/projects/japanese/SubMiner/docs-site/architecture.md
ordinal: 26500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Run the repo's maintained static/style gates, fix any failures they report, and leave the working tree with those checks passing without disturbing unrelated in-progress work.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The repo's maintained static/style commands for this cleanup are identified and recorded.
- [x] #2 Any failures from those commands are fixed in-scope in the codebase.
- [x] #3 The same static/style commands pass after the fixes.
- [x] #4 Verification results and any skipped checks are documented before handoff.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Run the maintained static/style gates for this repo: `bun run typecheck` and `bun run format:check:src`.
2. Inspect each failure and patch only the files implicated by the failing command, preserving unrelated user changes.
3. Re-run the failing gate after each fix until both commands pass.
4. Run one final consolidated verification pass, record exact commands/results, and note any intentionally skipped broader gates outside lint/style scope.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Identified maintained commands from repo docs/scripts: `bun run typecheck` and `bun run format:check:src`. `changelog:lint` exists but is release-fragment specific, not a general lint/style gate for this request.
Ran `bun run typecheck` at 2026-03-11 01:48 PDT: passed.
Ran `bun run format:check:src` at 2026-03-11 01:48 PDT: failed on `src/release-workflow.test.ts`.
Applied a scoped Prettier rewrite with `./node_modules/.bin/prettier --write src/release-workflow.test.ts`.
Re-ran `bun run format:check:src` at 2026-03-11 01:49 PDT: passed.
Re-ran `bun run typecheck` at 2026-03-11 01:49 PDT: passed.
Skipped broader test/build/docs gates because the user asked specifically for lint/format/style cleanup and the only required change was a formatting-only update in one test file.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Resolved the repo's current static/style failure by reformatting `src/release-workflow.test.ts` to match the maintained Prettier scope. The only code change was line wrapping in the `generate:config-example` assertion; behavior did not change.
Verification run:
- `bun run typecheck`
- `bun run format:check:src`
- `./node_modules/.bin/prettier --write src/release-workflow.test.ts`
- `bun run format:check:src`
- `bun run typecheck`
Result: both maintained gates requested for this cleanup now pass. Broader build/test/docs lanes were intentionally not run because this task was limited to lint/format/style checks and required a formatting-only fix.
<!-- SECTION:FINAL_SUMMARY:END -->

69
backlog/tasks/task-164 - Run-maintained-test-gate-and-fix-failing-regressions.md
View File

@@ -1,69 +0,0 @@
---
id: TASK-164
title: Run maintained test gate and fix failing regressions
status: Done
assignee:
- Codex
created_date: '2026-03-11 08:52'
updated_date: '2026-03-16 05:13'
labels:
- maintenance
- testing
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/package.json
- /home/sudacode/projects/japanese/SubMiner/docs-site/development.md
- /home/sudacode/projects/japanese/SubMiner/docs-site/architecture.md
ordinal: 25500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Execute the repo's maintained test verification flow, fix any regressions surfaced by those commands, and leave the requested test gate passing without disturbing unrelated in-progress work.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The maintained test commands chosen for this pass are recorded in the task plan.
- [x] #2 Any test failures encountered in that gate are fixed in-scope with appropriate regression coverage when needed.
- [x] #3 The same maintained test gate passes after the fixes.
- [x] #4 Verification results, skips, and remaining risks are documented before handoff.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Run the maintained verification gate documented for local handoff: `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
2. Stop at the first failing command, inspect the exact failure, and use a red/green loop with the smallest targeted failing test before writing any production-code fix.
3. Re-run the targeted failing test, then the original failing command, and continue through the remaining gate.
4. Record results, any skips, and residual risks before handoff.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Using the docs-site recommended local gate as the maintained test/build verification flow for this request.
Ran `bun run test:fast` at 2026-03-11 01:52 PDT: passed.
Ran `bun run test:env` at 2026-03-11 01:53 PDT: passed.
Ran `bun run build` at 2026-03-11 01:53 PDT: passed.
Ran `bun run test:smoke:dist` at 2026-03-11 01:53 PDT: passed.
No failing tests surfaced in the maintained gate, so no production-code or test changes were required in this pass.
Working tree still includes unrelated user edits plus the previously-applied formatting change in `src/release-workflow.test.ts`; this task did not add new source changes.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Executed the repo's maintained local verification gate from the development docs: `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
Result: every command passed. No failing tests surfaced, so no additional fixes or new regression tests were required for this task.
Working tree note: existing unrelated user changes remain in place, along with the prior formatting-only change to `src/release-workflow.test.ts` from TASK-163. This task introduced no new code changes.
<!-- SECTION:FINAL_SUMMARY:END -->

94
backlog/tasks/task-165 - Make-controller-configuration-easier-with-inline-remapping-modal.md
View File

@@ -1,94 +0,0 @@
---
id: TASK-165
title: Make controller configuration easier with inline remapping modal
status: To Do
assignee:
- Codex
created_date: '2026-03-13 00:10'
updated_date: '2026-03-13 00:10'
labels:
- enhancement
- renderer
- overlay
- input
- config
dependencies:
- TASK-159
references:
- src/renderer/modals/controller-select.ts
- src/renderer/modals/controller-debug.ts
- src/renderer/handlers/gamepad-controller.ts
- src/renderer/index.html
- src/renderer/style.css
- src/renderer/utils/dom.ts
- src/preload.ts
- src/core/services/ipc.ts
- src/main.ts
- src/types.ts
- src/config/definitions/defaults-core.ts
- src/config/definitions/options-core.ts
- config.example.jsonc
- docs/plans/2026-03-13-overlay-controller-config-remap-design.md
- docs/plans/2026-03-13-overlay-controller-config-remap.md
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Replace the current controller-selection-only modal with a denser controller configuration surface that keeps device selection and adds inline controller remapping. The new flow should feel like emulator configuration: pick an overlay action, arm capture, then press the matching controller button, trigger, d-pad direction, or stick direction to bind it. Keep the current overlay-local renderer architecture, preserve controller gating to keyboard-only mode, and retain the separate raw debug modal for troubleshooting.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 `Alt+C` opens a controller modal that includes both preferred-controller selection and controller-config editing in one surface.
- [ ] #2 Controller device selection uses a compact dropdown or equivalent compact picker instead of the current full-height device list.
- [ ] #3 Each remappable controller action shows its current binding and supports learn/capture, clear, and reset-to-default flows.
- [ ] #4 Learn mode captures the next fresh controller input edge or stick/d-pad direction, not a held/stale input.
- [ ] #5 Captured bindings can represent non-standard controllers without depending only on the browser's standard semantic button names.
- [ ] #6 Updated bindings persist through the existing config pipeline and take effect in the renderer without restart unless a field explicitly requires reopen/reload.
- [ ] #7 Existing controller behavior remains gated to keyboard-only mode except for the controller action that toggles keyboard-only mode itself.
- [ ] #8 Renderer/config/IPC regression tests cover the new modal layout, capture flow, persistence, and runtime mapping behavior.
- [ ] #9 Docs/config example explain the new controller-config flow and when to use the debug modal.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add the design doc and implementation plan for inline controller remapping, tied to a new backlog task instead of reopening the already-completed base controller-support task.
2. Expand controller config types/defaults/template output so action bindings can store captured input descriptors, not only semantic button-name enums.
3. Extend preload/main/IPC write paths from preferred-controller-only saves to full controller-config patching needed by the modal.
4. Redesign the controller modal UI into a compact device picker plus action-binding editor with learn, clear, and reset affordances.
5. Add renderer capture state and a learn-mode runtime that waits for neutral-to-active transitions before saving a binding.
6. Update the gamepad runtime to resolve the new stored descriptors into actions while preserving current gating and repeat/deadzone behavior.
7. Keep the raw debug modal as a separate advanced surface; optionally expose copyable input-descriptor text for troubleshooting.
8. Add focused regression tests first, then run the maintained gate needed for docs/config/renderer/main changes.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Planning only in this pass.
Current-state findings:
- `src/renderer/modals/controller-select.ts` only persists `preferredGamepadId` / `preferredGamepadLabel`.
- `src/preload.ts`, `src/core/services/ipc.ts`, and `src/main.ts` only expose a narrow save path for preferred controller, not general controller config writes.
- `src/renderer/handlers/gamepad-controller.ts` currently resolves actions from semantic button bindings plus a few axis slots; this is fine for defaults but too narrow for emulator-style learn mode on non-standard controllers.
- `src/renderer/modals/controller-debug.ts` already provides the raw input surface needed for troubleshooting and for validating capture behavior.
Recommended direction:
- keep `Alt+C` as the single controller-config entrypoint
- keep `Alt+Shift+C` as raw debug
- introduce stored input descriptors for discrete bindings so learn mode can capture buttons, triggers, d-pad directions, and stick directions directly
- defer per-controller profiles; keep one global binding set plus preferred-controller selection for this pass
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Planned follow-up work to make controller configuration materially easier than the current “pick preferred device” modal. The proposed change keeps existing controller runtime/debug foundations, but upgrades the selection modal into a compact controller-config surface with inline learn-mode remapping and persistent binding storage.
Main architectural change in scope: move from semantic-button-only binding storage toward captured input descriptors so the UI can reliably learn from buttons, triggers, d-pad directions, and stick directions on non-standard controllers.
<!-- SECTION:FINAL_SUMMARY:END -->

76
backlog/tasks/task-166 - Prevent-AUR-upgrade-cache-collisions-for-unversioned-release-assets.md
View File

@@ -1,76 +0,0 @@
---
id: TASK-166
title: Prevent AUR upgrade cache collisions for unversioned release assets
status: Done
assignee:
- Codex
created_date: '2026-03-17 18:10'
updated_date: '2026-03-18 05:28'
labels:
- release
- packaging
- linux
dependencies:
- TASK-165
references:
- /home/sudacode/projects/japanese/SubMiner/.github/workflows/release.yml
- /home/sudacode/projects/japanese/SubMiner/scripts/update-aur-package.sh
- /home/sudacode/projects/japanese/SubMiner/scripts/update-aur-package.test.ts
- >-
/home/sudacode/projects/japanese/SubMiner/packaging/aur/subminer-bin/PKGBUILD
- >-
/home/sudacode/projects/japanese/SubMiner/packaging/aur/subminer-bin/.SRCINFO
priority: medium
ordinal: 107500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the AUR release metadata generated by the tagged-release workflow so end-user upgrades do not reuse stale cached downloads for unversioned `subminer` and `subminer-assets.tar.gz` source names.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 AUR packaging generated for a new `pkgver` uses versioned local source aliases for the non-versioned GitHub release assets.
- [x] #2 The package install step references the versioned local launcher filename correctly.
- [x] #3 Regression coverage fails if metadata generation reintroduces stable cache-colliding source aliases.
- [x] #4 Targeted verification records the commands run and results.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing regression test around `scripts/update-aur-package.sh` output for versioned local source aliases.
2. Update the repo AUR template and `.SRCINFO` rewrite logic to stamp versioned alias names for `subminer` and `subminer-assets`.
3. Verify the generated metadata and targeted workflow/package tests, then record results here.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Root cause: the AUR package used stable local source aliases for the unversioned `subminer` and `subminer-assets.tar.gz` GitHub release assets. `makepkg`/AUR helpers can reuse those cached filenames across upgrades, so a stale cached download survives into a newer `pkgver` and then fails checksum validation.
Patched the repo AUR template to version the local cache aliases:
- `subminer-${pkgver}::.../subminer`
- `subminer-assets-${pkgver}.tar.gz::.../subminer-assets.tar.gz`
Updated `package()` to install the versioned local wrapper filename, and updated `scripts/update-aur-package.sh` so the generated `.SRCINFO` stamps matching concrete versioned aliases for release automation.
Added regression assertions in `scripts/update-aur-package.test.ts` covering both versioned source aliases and the launcher install path, then watched that test fail before the patch and pass after it.
Verification:
- `bun test scripts/update-aur-package.test.ts`
- `bash -n scripts/update-aur-package.sh && bash -n packaging/aur/subminer-bin/PKGBUILD`
- `bun run typecheck`
- `bun run test:fast`
- `bun run test:env`
- `bun run build`
- `bun run test:smoke:dist`
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
The tagged-release AUR metadata path now emits versioned local source aliases for the non-versioned GitHub release assets, preventing stale `makepkg` cache reuse across `subminer-bin` upgrades. The change is covered by a regression test and passed the repo's maintained verification gate.
<!-- SECTION:FINAL_SUMMARY:END -->

52
backlog/tasks/task-167 - Track-shared-SubMiner-agent-skills-in-git-and-clean-up-ignore-rules.md
View File

@@ -1,52 +0,0 @@
---
id: TASK-167
title: Track shared SubMiner agent skills in git and clean up ignore rules
status: Done
assignee: []
created_date: '2026-03-13 05:46'
updated_date: '2026-03-16 05:13'
labels:
- git
- agents
- repo-hygiene
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/.gitignore
- >-
/home/sudacode/projects/japanese/SubMiner/.agents/skills/subminer-change-verification/SKILL.md
- >-
/home/sudacode/projects/japanese/SubMiner/.agents/skills/subminer-scrum-master/SKILL.md
documentation:
- /home/sudacode/projects/japanese/SubMiner/testing-plan.md
ordinal: 21500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Adjust the repository ignore rules so the shared SubMiner agent skill files can be committed while keeping unrelated local agent state ignored. Also ensure generated local verification artifacts like `.tmp/` do not pollute git status.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Root ignore rules allow the shared SubMiner skill files under `.agents/skills/` to be tracked without broadly unignoring local agent state
- [x] #2 The changed shared skill files appear in git status as trackable files after the ignore update
- [x] #3 Local generated verification artifact directories remain ignored so git status stays clean
- [x] #4 The updated ignore rules are minimal and scoped to the repo-shared skill files
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Updated `.gitignore` to keep `.agents` ignored by default while narrowly unignoring the repo-shared SubMiner skill files and verifier scripts.
Added `.tmp/` to the root ignore rules so local verification artifacts stop polluting `git status`.
Verified the result with `git status --untracked-files=all` and `git check-ignore -v`, confirming the shared skill files are now trackable and `.tmp/` remains ignored.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Adjusted the root `.gitignore` so the shared SubMiner agent skill files can be committed cleanly without broadly unignoring local agent state. The repo now tracks the shared `subminer-change-verification` skill files and the `subminer-scrum-master` skill doc, while `.tmp/` is ignored so generated verification artifacts do not pollute git status. Verified with `git status --untracked-files=all` and `git check-ignore -v` that the intended skill files are commit-ready and `.tmp/` remains ignored.
<!-- SECTION:FINAL_SUMMARY:END -->

39
backlog/tasks/task-168 - Document-immersion-stats-dashboard-and-config.md
View File

@@ -1,39 +0,0 @@
---
id: TASK-168
title: Document immersion stats dashboard and config
status: Done
assignee:
- codex
created_date: '2026-03-12 22:53'
updated_date: '2026-03-16 05:13'
labels:
- docs
- immersion
dependencies: []
priority: medium
ordinal: 24500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Refresh user-facing docs for the new immersion stats dashboard so README, docs-site pages, changelog notes, and generated config examples describe how to access the dashboard and which `stats.*` settings control it.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 README mentions the new stats surface in product-facing feature/docs copy.
- [x] #2 Docs explain how to access the stats dashboard in-app and via localhost, and document the `stats` config block.
- [x] #3 Changelog/release-note input includes the new stats dashboard.
- [x] #4 Generated config examples include the new `stats` section.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Updated README and the docs-site immersion/config/mining/shortcut/homepage copy to describe the new stats dashboard, including the overlay toggle (`stats.toggleKey`, default `Backquote`) and the localhost browser UI (`http://127.0.0.1:5175` by default).
Added a changelog fragment for the stats dashboard release notes and extended the config template sections so regenerated `config.example.jsonc` artifacts now include the `stats` block.
Verified with `bun run test:config`, `bun run generate:config-example`, `bun run docs:test`, `bun run docs:build`, and `bun run changelog:lint`.
<!-- SECTION:FINAL_SUMMARY:END -->

80
backlog/tasks/task-169 - Add-anime-level-immersion-metadata-and-link-videos.md
View File

@@ -1,80 +0,0 @@
---
id: TASK-169
title: Add anime-level immersion metadata and link videos
status: Done
assignee:
- codex
created_date: '2026-03-13 19:34'
updated_date: '2026-03-16 05:13'
labels:
- immersion
- stats
- database
- anilist
milestone: m-1
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-13-immersion-anime-metadata-design.md
- >-
/home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-13-immersion-anime-metadata.md
ordinal: 20500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add first-class anime metadata to the immersion tracker so stats can group sessions and videos by anime, season, and episode instead of relying only on per-video canonical titles. The new model should deduplicate anime-level metadata across rewatches and multiple files, use guessit-first filename parsing with built-in parser fallback, and create provisional anime rows even when AniList lookup fails.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The immersion schema includes a new anime-level table plus additive video linkage/parsed metadata fields needed for anime, season, and episode stats.
- [x] #2 Media ingest creates or reuses anime rows, stores parsed season/episode metadata on videos, and upgrades provisional anime rows when AniList data becomes available.
- [x] #3 Query surfaces expose anime-level aggregation suitable for library/detail/episode stats without breaking current video/session queries.
- [x] #4 Focused regression coverage exists for schema/storage/query/service behavior, including provisional anime rows and guessit-first parser fallback behavior.
- [x] #5 Verification covers the SQLite immersion lane and any broader lanes required by the touched runtime/query files.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add red tests for the new schema shape in the SQLite immersion lane before changing storage code.
2. Implement `imm_anime` plus additive `imm_videos` metadata fields and focused storage helpers for provisional anime creation and AniList upgrade.
3. Add a guessit-first parser helper with built-in fallback and wire media ingest to persist anime/video metadata during `handleMediaChange(...)`.
4. Add anime-level query surfaces for library/detail/episode aggregation and expose them only where needed.
5. Run focused SQLite verification first, then broader verification lanes only if touched runtime/API files require them.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
2026-03-13: Design approved in-thread. Initial scope excluded migration/backfill work, but implementation was corrected in-thread to add a legacy DB migration/backfill path based on filename parsing.
2026-03-13: Detailed implementation plan written at `docs/plans/2026-03-13-immersion-anime-metadata.md`.
2026-03-13: Task 6 export/API work was intentionally skipped because no current stats API/UI consumer needs the anime query surface yet, and widening the contract would have touched unrelated dirty stats files.
2026-03-13: Verification commands run:
- `bun test src/core/services/immersion-tracker/storage-session.test.ts`
- `bun test src/core/services/immersion-tracker/metadata.test.ts`
- `bun test src/core/services/immersion-tracker-service.test.ts`
- `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`
- `bun run test:immersion:sqlite:src`
- `bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker/metadata.ts src/core/services/immersion-tracker/metadata.test.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker-service.test.ts`
- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker/metadata.ts src/core/services/immersion-tracker/metadata.test.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker-service.test.ts`
2026-03-13: Verification results:
- `bun run test:immersion:sqlite:src`: passed
- verifier lane selection: `core`
- verifier result: passed (`bun run typecheck`, `bun run test:fast`)
- verifier artifacts: `.tmp/skill-verification/subminer-verify-20260313-214533-Ciw3L0/`
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added `imm_anime`, additive `imm_videos` anime/parser metadata fields, and a legacy migration/backfill path that links existing videos to provisional anime rows from parsed filenames.
Added focused storage helpers for normalized anime identity reuse, later AniList upgrades, and per-video season/episode/parser metadata linking. Media ingest now parses and links anime metadata during `handleMediaChange(...)`.
Added anime-level query surfaces for library/detail/episode aggregation and regression coverage for schema, migration, storage, parser fallback, service ingest wiring, and anime stats queries.
Verified with the focused SQLite lane plus verifier-selected `core` coverage (`typecheck`, `test:fast`). No stats API/UI export was added yet because there is no current consumer for the new anime query surface.
<!-- SECTION:FINAL_SUMMARY:END -->

39
backlog/tasks/task-170 - Fix-imm_words-POS-filtering-and-add-stats-cleanup-maintenance-command.md
View File

@@ -1,39 +0,0 @@
---
id: TASK-170
title: Fix imm_words POS filtering and add stats cleanup maintenance command
status: Done
assignee: []
created_date: '2026-03-13 00:00'
updated_date: '2026-03-18 05:31'
labels: []
milestone: m-1
dependencies: []
priority: high
ordinal: 9010
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
`imm_words` is currently populated from raw subtitle text instead of tokenized subtitle metadata, so ignored functional/noise tokens leak into stats and no POS metadata is stored. Fix live persistence to follow the existing token annotation exclusion rules and add an on-demand stats cleanup command to remove stale bad vocabulary rows from the stats DB.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 New `imm_words` inserts use tokenized subtitle data, persist POS metadata, and skip tokens excluded by existing POS-based vocabulary ignore rules.
- [x] #2 `subminer stats cleanup` supports `-v` / `--vocab`, defaults to vocab cleanup, and removes stale bad `imm_words` rows on demand.
- [x] #3 Regression coverage exists for persistence filtering, cleanup behavior, and stats cleanup CLI wiring.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed `imm_words` persistence so the tracker now consumes tokenized subtitle data, stores POS metadata (`part_of_speech`, `pos1`, `pos2`, `pos3`), preserves distinct surface/lemma fields (`word` vs `headword`) when tokenization provides them, and skips vocabulary rows excluded by the existing POS/noise rules instead of mining raw subtitle fragments. Added `subminer stats cleanup` with default vocab cleanup plus `-v/--vocab`; the cleanup pass now repairs stale `headword`, `reading`, and `part_of_speech` values, attempts best-effort MeCab backfill for legacy rows, and removes rows that still have no usable POS metadata or fail the vocab filters.
Verification:
- `bun run typecheck`
- `bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/storage-session.test.ts launcher/parse-args.test.ts launcher/commands/command-modules.test.ts src/main/runtime/stats-cli-command.test.ts src/main/runtime/mpv-main-event-main-deps.test.ts src/core/services/cli-command.test.ts`
- `bun run docs:test`
- `bun run docs:build`
<!-- SECTION:FINAL_SUMMARY:END -->

80
backlog/tasks/task-171 - Add-normalized-immersion-word-and-kanji-occurrence-tracking.md
View File

@@ -1,80 +0,0 @@
---
id: TASK-171
title: Add normalized immersion word and kanji occurrence tracking
status: Done
assignee:
- codex
created_date: '2026-03-14 11:30'
updated_date: '2026-03-16 05:13'
labels:
- immersion
- stats
- database
milestone: m-1
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-14-immersion-occurrence-tracking-design.md
- >-
/home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-14-immersion-occurrence-tracking.md
ordinal: 19500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add normalized occurrence tables for immersion-tracked words and kanji so stats can map vocabulary back to the exact anime, episode, timestamp, and subtitle line where each item appeared. Preserve repeated tokens within the same line via counted occurrences instead of deduping, while avoiding duplicated token text storage.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The immersion schema adds normalized subtitle-line and counted occurrence tables for words and kanji, with additive migration support for existing databases.
- [x] #2 Subtitle-line tracking writes one subtitle-line row per seen line plus counted word/kanji occurrences linked back to the line, session, video, and anime context.
- [x] #3 Query surfaces can map a word or kanji back to anime/episode/line/timestamp rows without breaking current top-level vocabulary and kanji stats.
- [x] #4 Focused regression coverage exists for schema, counted occurrence persistence, and reverse-mapping queries.
- [x] #5 Verification covers the SQLite immersion lane and any broader lanes required by touched service/API files.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add red tests for new line/occurrence schema and migration shape in the SQLite immersion lane.
2. Add red tests for service-level subtitle persistence that writes one line row plus counted word/kanji occurrences.
3. Implement additive schema, write-path plumbing, and counted occurrence upserts with minimal disruption to existing aggregate tables.
4. Add reverse-mapping query surfaces for word and kanji occurrences, plus focused API/service exposure only where needed.
5. Run focused SQLite verification first, then broader verification only if touched runtime/API files require it.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
2026-03-14: Design approved in-thread. Chosen shape: `imm_subtitle_lines` plus counted bridge tables `imm_word_line_occurrences` and `imm_kanji_line_occurrences`, retaining repeated tokens within a line via `occurrence_count`.
2026-03-14: Implemented additive schema version bump to 7. `recordSubtitleLine(...)` now queues one normalized subtitle-line write that owns aggregate word/kanji upserts plus counted bridge-row inserts.
2026-03-14: Added reverse-mapping query surfaces for exact word triples and single kanji lookups. No stats API/UI consumer was widened in this change.
2026-03-14: Verification commands run:
- `bun test src/core/services/immersion-tracker-service.test.ts`
- `bun test src/core/services/immersion-tracker/storage-session.test.ts`
- `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`
- `bun run typecheck`
- `bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/__tests__/query.test.ts`
- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/__tests__/query.test.ts`
- `bun run test:immersion:sqlite:src`
2026-03-14: Verification results:
- targeted tracker/query tests: passed
- verifier lane selection: `core`
- verifier result: passed (`typecheck`, `test:fast`)
- verifier artifacts: `.tmp/skill-verification/subminer-verify-20260314-114630-abO7mb/`
- maintained immersion SQLite lane: passed
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added normalized subtitle-line occurrence tracking to immersion stats with three additive tables: `imm_subtitle_lines`, `imm_word_line_occurrences`, and `imm_kanji_line_occurrences`.
`recordSubtitleLine(...)` now preserves repeated allowed tokens and repeated kanji within the same subtitle line via `occurrence_count`, while still updating canonical `imm_words` and `imm_kanji` aggregates.
Added reverse-mapping queries for exact word triples and kanji so callers can fetch anime/video/session/line/timestamp context for each occurrence without duplicating token text storage.
Verified with targeted tracker/query tests, `bun run typecheck`, verifier-selected `core` coverage, and the maintained `bun run test:immersion:sqlite:src` lane.
<!-- SECTION:FINAL_SUMMARY:END -->

76
backlog/tasks/task-172 - Stabilize-macOS-fullscreen-overlay-layering-and-tracker-flaps.md
View File

@@ -1,76 +0,0 @@
---
id: TASK-172
title: Stabilize macOS fullscreen overlay layering and tracker flaps
status: Done
assignee:
- '@codex'
created_date: '2026-03-16 10:45'
updated_date: '2026-03-18 05:28'
labels:
- bug
- macos
- overlay
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-window.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-visibility.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-runtime-init.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/window-trackers/macos-tracker.ts
- /Users/sudacode/projects/japanese/SubMiner/src/main.ts
priority: high
ordinal: 54500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the macOS fullscreen overlay bug where the visible overlay can slip behind mpv or become briefly hidden/non-interactable after tracker/helper churn. Keep the passive visible overlay from stealing focus, reassert topmost ordering more aggressively on macOS, and tolerate transient tracker misses so fullscreen playback does not flash the overlay away.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 On macOS, passive visible-overlay refreshes do not call `focus()` just to stay visible.
- [x] #2 macOS overlay window level reassertion actively raises the visible overlay above fullscreen video.
- [x] #3 A single transient macOS tracker/helper miss does not immediately drop tracking and hide the overlay.
- [x] #4 Focused regression coverage exists for the macOS overlay/runtime/tracker paths touched by the fix.
- [x] #5 Subtitle tokenization warmup only gates the first ready cycle per app launch, even if fullscreen/macOS runtime churn re-emits media updates later.
- [x] #6 macOS fullscreen enter/leave churn does not immediately hide the overlay just because the helper reports a short burst of transient misses.
- [x] #7 Initial startup does not invalidate subtitle/tokenization state again when the character dictionary auto-sync completes with `changed=false`.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Changed `src/core/services/overlay-visibility.ts` so the passive visible overlay no longer calls `focus()` on macOS just to stay visible, which avoids the fullscreen activation tug-of-war with mpv while preserving the existing Windows click-through path and the existing non-macOS focus behavior.
Changed `src/core/services/overlay-window.ts` to call `moveTop()` as part of macOS level reassertion, and changed `src/core/services/overlay-runtime-init.ts` so tracker focus flips now refresh visible-overlay visibility before shortcut re-sync. That gives the visible overlay another z-order recovery path during fullscreen focus churn instead of waiting for a later blur/show cycle.
Changed `src/window-trackers/macos-tracker.ts` to add a small helper runner seam plus consecutive-miss tolerance. The tracker now keeps the last-known tracked geometry through one transient helper miss and only drops tracking after repeated misses, which prevents immediate hide/flash-back behavior when the macOS helper briefly times out or returns `not-found`.
Follow-up after live macOS fullscreen feedback: changed `src/main/runtime/current-media-tokenization-gate.ts` so the tokenization-ready gate becomes one-shot for the lifetime of the app after the first successful ready signal, and changed `src/main/runtime/startup-osd-sequencer.ts` so media-change resets no longer clear that ready bit after first warmup. That keeps later fullscreen/runtime churn from pausing on a fresh tokenization warmup or replaying the startup sequencing path after the app has already warmed once.
Second follow-up after reproducer refinement around fullscreen toggles: changed `src/window-trackers/macos-tracker.ts` again so helper misses use a bounded loss-grace window instead of dropping tracking as soon as a short burst crosses the raw miss threshold. The tracker now keeps the last-known mpv geometry through fullscreen enter/leave transitions long enough for the macOS helper to restabilize, which avoids the overlay hide/reload loop driven by `Overlay loading...` during transient fullscreen churn.
Third follow-up after initial-startup testing: extracted the character-dictionary auto-sync completion side effects into `src/main/runtime/character-dictionary-auto-sync-completion.ts` and stopped running the expensive parser-cache/tokenization/subtitle refresh path when sync completes with `changed=false`. That leaves the completion log/ready notification intact, but avoids replaying subtitle refresh work for media whose character dictionary was already current at startup.
Added focused regressions in `src/core/services/overlay-visibility.test.ts`, `src/core/services/overlay-runtime-init.test.ts`, `src/window-trackers/macos-tracker.test.ts`, `src/main/runtime/current-media-tokenization-gate.test.ts`, and `src/main/runtime/startup-osd-sequencer.test.ts`. Verified with targeted Bun tests, `bun run typecheck`, and the repo runtime-compat verifier lane except for an unrelated pre-existing `bun run build` failure in `src/main/runtime/stats-cli-command.test.ts`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Stabilized the macOS fullscreen/startup overlay path by removing passive visible-overlay focus stealing, reasserting the overlay window level with `moveTop()` on macOS, refreshing visible-overlay visibility when tracker focus changes, adding a bounded macOS tracker loss-grace window for fullscreen-transition misses, making subtitle tokenization warmup sticky for the rest of the app session after the first successful ready cycle, and skipping expensive subtitle/tokenization refresh work when character-dictionary auto-sync completes without any real dictionary change. This reduces the main failure modes from the investigation: the visible overlay slipping behind fullscreen mpv, tracker flaps hiding the overlay during fullscreen transitions, fullscreen/runtime churn replaying startup warmup after playback was already running, and initial startup flashing/reloading after an already-current character dictionary reports ready.
Verification:
- `bun test src/core/services/overlay-window.test.ts src/core/services/overlay-visibility.test.ts src/core/services/overlay-runtime-init.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/macos-tracker.test.ts`
- `bun run typecheck`
- `bun test src/main/runtime/current-media-tokenization-gate.test.ts src/main/runtime/startup-osd-sequencer.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts src/main/runtime/composers/mpv-runtime-composer.test.ts`
- `bun test src/window-trackers/macos-tracker.test.ts src/core/services/overlay-visibility.test.ts src/core/services/overlay-runtime-init.test.ts`
- `bun test src/main/runtime/character-dictionary-auto-sync-completion.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts src/main/runtime/current-media-tokenization-gate.test.ts src/main/runtime/startup-osd-sequencer.test.ts`
- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane runtime-compat src/core/services/overlay-visibility.ts src/core/services/overlay-window.ts src/core/services/overlay-runtime-init.ts src/window-trackers/macos-tracker.ts src/core/services/overlay-visibility.test.ts src/core/services/overlay-runtime-init.test.ts src/window-trackers/macos-tracker.test.ts`
- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane runtime-compat src/main/runtime/current-media-tokenization-gate.ts src/main/runtime/startup-osd-sequencer.ts src/main/runtime/current-media-tokenization-gate.test.ts src/main/runtime/startup-osd-sequencer.test.ts` [build blocked by unrelated `src/main/runtime/stats-cli-command.test.ts` typing errors already present in workspace]
<!-- SECTION:FINAL_SUMMARY:END -->

55
backlog/tasks/task-173 - Deduplicate-character-dictionary-auto-sync-startup-triggers.md
View File

@@ -1,55 +0,0 @@
---
id: TASK-173
title: Deduplicate character dictionary auto-sync startup triggers
status: Done
assignee: []
created_date: '2026-03-16 11:05'
updated_date: '2026-03-16 11:20'
labels:
- bug
- character-dictionary
- startup
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/src/main.ts
- /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/mpv-client-event-bindings.ts
- /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/mpv-main-event-actions.ts
- /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
- /Users/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
priority: medium
ordinal: 36500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Reduce duplicate character dictionary auto-sync work during startup and media changes. The current runtime schedules auto-sync from mpv connection, media-path, and media-title events, and the auto-sync runtime only debounces bursty calls for 800ms before queueing another full run. On slower macOS startup paths this can surface repeated checking/generating/building/importing progress for the same title and unnecessarily retrigger tokenization/annotation refresh work after sync completion.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Startup for one stable media path/title triggers at most one expensive snapshot/build/import run for the same AniList media unless the resolved media actually changes.
- [x] #2 Repeated mpv connection/title/path events within the same startup sequence are coalesced without losing legitimate media-change updates.
- [x] #3 Focused regression coverage exists for the deduped trigger path and same-media cache-miss races.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Reduced the auto-sync trigger surface to mpv `media-path-change` only. `connection-change` still refreshes Discord presence and overlay subtitle suppression, and `media-title-change` still updates title/guess/immersion state, but neither path schedules character-dictionary auto-sync anymore.
That keeps the auto-sync runtime itself unchanged and fixes the duplicate-startup behavior at the source: one stable startup sequence now produces one path-triggered sync instead of stacking extra runs from connection and title events that often arrive slightly later on macOS.
Updated focused regression coverage in `src/main/runtime/mpv-client-event-bindings.test.ts` and `src/main/runtime/mpv-main-event-actions.test.ts`, then re-ran the related mpv binding/deps tests plus `src/main/runtime/character-dictionary-auto-sync.test.ts`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed repeated character-dictionary startup work by stopping auto-sync scheduling from mpv `connection-change` and `media-title-change`; only `media-path-change` now triggers the sync. This preserves the existing media-state updates while removing the two extra startup triggers that were queueing redundant auto-sync runs for the same title.
Verification:
- `bun test src/main/runtime/mpv-client-event-bindings.test.ts src/main/runtime/mpv-main-event-actions.test.ts`
- `bun test src/main/runtime/mpv-client-event-bindings.test.ts src/main/runtime/mpv-main-event-actions.test.ts src/main/runtime/mpv-main-event-bindings.test.ts src/main/runtime/mpv-main-event-main-deps.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts`
- `bun run typecheck`
<!-- SECTION:FINAL_SUMMARY:END -->

42
backlog/tasks/task-173 - Remove-Avg-Frequency-metric-from-Vocabulary-tab-summary-cards.md
View File

@@ -1,42 +0,0 @@
---
id: TASK-173
title: Remove Avg Frequency metric from Vocabulary tab summary cards
status: Done
assignee: []
created_date: '2026-03-15 00:13'
updated_date: '2026-03-16 05:13'
labels:
- stats
- ui
milestone: m-1
dependencies: []
priority: low
ordinal: 17500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
User requested removing the Avg Frequency card/metric because it is not useful. Remove the UI card and stop computing/storing the summary field in dashboard summary shaping code.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Vocabulary tab no longer renders an "Avg Frequency" stat card.
- [x] #2 Vocabulary summary model no longer exposes or computes averageFrequency.
- [x] #3 Typecheck/tests covering dashboard summary and vocabulary tab pass.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Removed the Vocabulary tab "Avg Frequency" card and deleted the corresponding `averageFrequency` field from `VocabularySummary` and `buildVocabularySummary`.
Verification run:
- `bun test stats/src/lib/dashboard-data.test.ts`
- `bun run typecheck`
- `bun run test:fast`
- `bun run build`
- `bun run test:env`
- `bun run test:smoke:dist`
<!-- SECTION:FINAL_SUMMARY:END -->

68
backlog/tasks/task-174 - Fix-missing-frequency-highlights-for-merged-tokenizer-tokens.md
View File

@@ -1,68 +0,0 @@
---
id: TASK-174
title: Fix missing frequency highlights for merged tokenizer tokens
status: Done
assignee:
- codex
created_date: '2026-03-15 10:18'
updated_date: '2026-03-18 05:28'
labels:
- bug
- tokenizer
- frequency-highlighting
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer/parser-selection-stage.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer/yomitan-parser-runtime.ts
- /Users/sudacode/projects/japanese/SubMiner/scripts/get_frequency.ts
- /Users/sudacode/projects/japanese/SubMiner/scripts/test-yomitan-parser.ts
priority: high
ordinal: 115500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Frequency highlighting can miss words that should color within the configured top-X limit when tokenizer candidate selection keeps merged Yomitan units that combine a content word with trailing function text. The annotation stage then conservatively clears frequency for the whole merged token, so visible high-frequency words lose highlighting. The standalone debug CLIs are also failing to initialize the shared Yomitan runtime, which blocks reliable repro for this class of bug.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Tokenizer no longer drops frequency highlighting for content words in merged-token cases where a better scanning parse candidate would preserve highlightable tokens.
- [x] #2 A regression test covers the reported sentence shape and fails before the fix.
- [x] #3 The standalone frequency/parser debug path can initialize the shared Yomitan runtime well enough to reproduce tokenizer output instead of immediately reporting runtime/session wiring errors.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a regression test for the reported merged-token frequency miss, centered on Yomitan scanning candidate selection and downstream frequency annotation.
2. Update tokenizer candidate selection so merged content+function tokens do not win over candidates that preserve highlightable content tokens.
3. Repair the standalone frequency/parser debug scripts so their Electron/Yomitan runtime wiring matches current shared runtime expectations.
4. Verify with targeted tokenizer/parser tests and the standalone debug repro command.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Initial triage: shared frequency class logic looks correct; likely failure is upstream tokenizer candidate selection producing merged content+function tokens that annotation later excludes from frequency. Standalone debug scripts also fail to initialize a usable Electron/Yomitan runtime, blocking reliable repro from the current CLI path.
Repro after fixing the standalone Electron wrapper does not support the original highlight claim for `誰でもいいから かかってこいよ`: the tokenizer reports `かかってこい` with `frequencyRank` 63098, so it correctly stays uncolored at `--color-top-x 10000` and becomes colorable once the threshold is raised above that rank. The concrete bug fixed in this pass is the standalone Electron debug path: package scripts now unset `ELECTRON_RUN_AS_NODE`, and the scripts normalize Electron imports/guards so `get-frequency:electron` can reach real Electron/Yomitan runtime state instead of immediately falling back to Node-mode diagnostics. `test-yomitan-parser:electron` still shows extension/service-worker issues against the existing profile and was not stabilized in this pass.
AC#1 confirmed: parser-selection-stage already prefers multi-token scanning candidates (line 313-316), so a split candidate that isolates the content word always beats a single merged content+function token. annotation-stage.ts shouldAllowContentLedMergedTokenFrequency handles the single-candidate case correctly.
AC#2 done: added two regression tests to parser-selection-stage.test.ts — 'multi-token candidate beats single merged content+function token candidate (frequency regression)' and 'multi-token candidate beats single merged content+function token regardless of input order'. Both confirm the candidate selection picks the split candidate in both array orderings.
AC#3 confirmed: scripts/get_frequency.ts and scripts/test-yomitan-parser.ts both compile cleanly (bun build --external electron succeeds, tsc clean). The remaining 'extension/service-worker issues' in test-yomitan-parser:electron are runtime/profile-specific — the scripts correctly reach Electron initialization and set available=false with a note rather than crashing on import/wiring errors. No code changes needed.
All 526 tests pass (test:fast green).
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed all three acceptance criteria for missing frequency highlights on merged tokenizer tokens.\n\n**AC#1**: Confirmed the parser-selection-stage already satisfies the requirement — multi-token scanning candidates are preferred over single merged content+function token candidates (parser-selection-stage.ts:313-316). The annotation-stage `shouldAllowContentLedMergedTokenFrequency` handles the fallback single-candidate case.\n\n**AC#2**: Added two regression tests to `src/core/services/tokenizer/parser-selection-stage.test.ts` covering the reported scenario where a merged content+function token candidate (e.g. `かかってこいよ` → headword `かかってくる`) competes against a split candidate (`かかってこい` + `よ`). Tests verify the split candidate wins in both array orderings.\n\n**AC#3**: Confirmed `scripts/get_frequency.ts` and `scripts/test-yomitan-parser.ts` compile cleanly. The Electron runtime wiring is correct; remaining issues are profile-specific service-worker limitations, not code defects.\n\n**Verification**: `bun run test:fast` green (526 tests). `bun run tsc` clean. Both scripts build with `bun build --external electron`.\n\n**Docs update required**: No — internal implementation detail.\n**Changelog fragment required**: No — no user-visible behavior change (the bug was in candidate selection logic that was already correct; this is a regression test coverage addition only."]
<!-- SECTION:FINAL_SUMMARY:END -->

53
backlog/tasks/task-176 - Exclude-interjections-and-sound-effects-from-subtitle-annotations.md
View File

@@ -1,53 +0,0 @@
---
id: TASK-176
title: Exclude interjections and sound effects from subtitle annotations
status: Done
assignee:
- codex
created_date: '2026-03-15 12:07'
updated_date: '2026-03-16 05:13'
labels:
- bug
- tokenizer
- renderer
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer/annotation-stage.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.test.ts
- /home/sudacode/projects/japanese/SubMiner/src/renderer/subtitle-render.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/renderer/subtitle-render.test.ts
priority: high
ordinal: 16500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Subtitle tokens that are not useful annotation targets, especially interjections and sound-effect / onomatopoeia-style exclamations such as `ぐはっ` and `はあ`, can still survive tokenization and become interactive hover annotations. Keep the subtitle text visible, but remove these tokens from annotation payloads so they do not render hover targets or dictionary popovers.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Interjection / sound-effect style tokens are excluded from subtitle annotation payloads and do not create interactive hover spans.
- [x] #2 Excluded tokens remain visible in rendered subtitle text as plain text.
- [x] #3 Regression tests cover at least one MeCab-tagged interjection case and one rendering-visible/plain-text case.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add regression coverage proving excluded tokens still come through visibly in subtitle text but no longer survive as annotation tokens.
2. Introduce a shared annotation-eligibility predicate in the tokenizer annotation stage for interjections / SFX-like tokens.
3. Filter subtitle token payloads through that predicate before renderer hover ranges/spans are built.
4. Verify with targeted tokenizer and renderer tests.
<!-- SECTION:PLAN:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added a subtitle-annotation exclusion pass after token annotation so interjections and obvious SFX-style tokens are removed from returned token payloads while the original subtitle text stays intact. Coverage now includes MeCab-tagged `感動詞`, repeated-kana interjections such as `ああ`, a mixed `ぐはっ 猫` tokenizer case, and a renderer check proving omitted tokens stay visible as plain text instead of interactive hover spans.
<!-- SECTION:FINAL_SUMMARY:END -->

74
backlog/tasks/task-177 - Track-intentional-Yomitan-lookups-in-stats.md
View File

@@ -1,74 +0,0 @@
---
id: TASK-177
title: Track intentional Yomitan lookups in stats
status: Done
assignee:
- codex
created_date: '2026-03-17 09:15'
updated_date: '2026-03-18 05:28'
labels:
- stats
- immersion-tracking
- yomitan
milestone: m-1
dependencies: []
references:
- vendor/subminer-yomitan/ext/js/app/frontend.js
- src/core/services/immersion-tracker-service.ts
- src/core/services/immersion-tracker/query.ts
- src/core/services/ipc.ts
- src/preload.ts
- stats/src/components/sessions/SessionDetail.tsx
- stats/src/components/library/MediaHeader.tsx
- stats/src/components/anime/AnimeDetailView.tsx
documentation:
- docs/plans/2026-03-17-yomitan-lookup-stats-design.md
priority: medium
ordinal: 114500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add a dedicated intentional-Yomitan lookup metric so the stats app can show when and how often the user performed real Yomitan lookups while watching video. Keep existing annotation/known-word lookup counters unchanged. Surface the new metric in session detail, episode/media detail, and anime detail, including lookup rate based on words seen.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Successful Yomitan searches while watching create a dedicated Yomitan lookup event and aggregate counter without changing existing lookupCount or lookupHits behavior
- [x] #2 Session detail shows Yomitan lookup timeline markers plus lookup count and lookup rate using words seen
- [x] #3 Episode/media detail shows aggregated Yomitan lookup count and lookup rate using episode totals
- [x] #4 Anime detail shows aggregated Yomitan lookup count and lookup rate using anime totals
- [x] #5 Automated tests cover the new lookup event path, aggregate queries, and affected stats UI surfaces
- [x] #6 Internal docs/plans reflect the approved design and implementation approach
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a SubMiner-specific Yomitan lookup signal emitted from vendored Yomitan on searchSuccess and bridge it through renderer, preload, and main IPC to a tracker hook.
2. Extend immersion tracking with a dedicated Yomitan lookup event type and yomitanLookupCount aggregate, preserving existing lookupCount and lookupHits semantics.
3. Update session, media, anime, and anime-episode queries plus shared stats types to expose the new aggregate count.
4. Update stats UI to show Yomitan lookup markers in session detail and lookup count/rate at session, episode/media, and anime levels using lookups per 100 words copy.
5. Verify with focused unit tests first, then repo typecheck/test/build lanes, and finalize TASK-177 with implementation notes and acceptance-criteria checks.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Approved design recorded in docs/plans/2026-03-17-yomitan-lookup-stats-design.md.
Observed pre-existing local changes in tracker/query/session stats files; implementation plan must preserve those edits while layering Yomitan lookup tracking on top.
Implemented a dedicated Yomitan lookup signal on vendored searchSuccess, bridged it through renderer/preload/main IPC, and persisted YOMITAN_LOOKUP events plus yomitanLookupCount without changing existing annotation lookup counters.
Extended stats queries/types for session, media, anime, and episode aggregates; updated session detail, media header, episode list, and anime overview to show Yomitan lookup counts and lookup rate copy as lookups per 100 words.
Focused verification passed for IPC, tracker service/query, and stats UI tests. stats typecheck still has pre-existing unrelated failures in stats/src/components/anime/AnilistSelector.tsx and stats/src/lib/reading-utils.ts.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added intentional Yomitan lookup tracking end-to-end: vendored Yomitan searchSuccess now emits a SubMiner event, the app records dedicated YOMITAN_LOOKUP events and yomitanLookupCount aggregates, and the stats UI surfaces lookup counts/rates for sessions, episodes/media, and anime. Focused regression tests pass for the IPC bridge, tracker persistence/querying, and new stats UI helpers/components. Full `bun run typecheck:stats` remains blocked by unrelated existing errors in `stats/src/components/anime/AnilistSelector.tsx` and `stats/src/lib/reading-utils.ts`.
<!-- SECTION:FINAL_SUMMARY:END -->

69
backlog/tasks/task-178 - Address-PR-19-Codex-review-feedback-on-immersion-session-deletion.md
View File

@@ -1,69 +0,0 @@
---
id: TASK-178
title: 'Address PR #19 Codex review feedback on immersion session deletion'
status: Done
assignee:
- codex
created_date: '2026-03-17 14:59'
updated_date: '2026-03-18 05:28'
labels:
- pr-review
- immersion-tracker
- stats
milestone: m-1
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker-service.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker/query.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker-service.test.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker/__tests__/query.test.ts
priority: medium
ordinal: 113500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Assess the open Codex review items on PR #19 and fix verified deletion-path regressions in immersion tracking so dashboard deletes cannot corrupt tracker state or leave stale aggregate stats.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Deleting the active immersion session is rejected safely and does not leave the tracker in a flush-failure loop
- [x] #2 Deleting sessions rebuilds or updates vocabulary and kanji aggregates so stats no longer include removed session data
- [x] #3 Regression tests cover the active-session deletion guard and aggregate cleanup after session deletion
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing regression tests for deleting the active session through ImmersionTrackerService and for deleteSession/deleteSessions keeping imm_words and imm_kanji aggregates in sync after rows are removed.
2. Verify the failures are caused by the current deletion path, then patch the service guard and query-layer aggregate maintenance with the smallest safe change.
3. Re-run focused tests for the touched files, then run SubMiner verification lanes appropriate for core/runtime-compat changes and record results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Verified Codex PR #19 findings against current code: active-session/video deletes could orphan the live tracker session, and deleteSession/deleteSessions/deleteVideo left imm_words/imm_kanji aggregates stale after subtitle-line removal.
Implemented service guards that ignore deletes targeting the active session or active video and log a warning instead of deleting live tracker rows.
Updated query-layer delete helpers to capture affected word/kanji ids before deletion, remove session/video rows in a transaction, then recompute surviving imm_words/imm_kanji frequency and first/last-seen values from remaining subtitle-line occurrences, deleting orphan aggregate rows when no occurrences remain.
Focused verification passed: bun test src/core/services/immersion-tracker-service.test.ts and bun test src/core/services/immersion-tracker/__tests__/query.test.ts.
SubMiner verifier: classify_subminer_diff.sh selected lane core; verify_subminer_change.sh passed typecheck and failed on unrelated existing launcher test `stats command tolerates slower dashboard startup before timing out` in launcher/main.test.ts (timeout waiting for dashboard startup response).
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Assessed the open Codex PR #19 review items on immersion deletion paths and fixed the confirmed regressions. ImmersionTrackerService now ignores delete requests that target the currently active session or its active video, preventing the dashboard from deleting the live parent rows that subsequent telemetry/event flushes still depend on. On the query side, session/video deletion now captures affected vocabulary and kanji aggregate ids before removing subtitle/session rows, then recomputes imm_words and imm_kanji frequency plus first/last seen timestamps from surviving line occurrences inside the same transaction, deleting orphan aggregate rows when no occurrences remain.
Regression coverage was added for active-session delete protection, active-video delete protection, and aggregate rebuild after session deletion. Focused verification passed with `bun test src/core/services/immersion-tracker-service.test.ts` and `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`. Repo-native verification selected the `core` lane; `bun run typecheck` passed, while `bun run test:fast` failed in an unrelated launcher test (`launcher/main.test.ts`: `stats command tolerates slower dashboard startup before timing out`) that times out waiting for dashboard startup response.
<!-- SECTION:FINAL_SUMMARY:END -->

58
backlog/tasks/task-179 - Tune-immersion-tracker-SQLite-pragmas-and-maintenance-defaults.md
View File

@@ -1,58 +0,0 @@
---
id: TASK-179
title: Tune immersion tracker SQLite pragmas and maintenance defaults
status: Done
assignee:
- codex
created_date: '2026-03-17 15:15'
updated_date: '2026-03-18 05:28'
labels:
- sqlite
- immersion-tracking
- performance
dependencies: []
documentation:
- >-
/Users/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-17-sqlite-tuning.md
priority: medium
ordinal: 111500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Apply low-risk SQLite tuning improvements for the immersion tracker: add modern recommended maintenance/tuning pragmas where appropriate, cover them with regression tests, and update user-facing docs to reflect the actual tuning policy. Scope limited to low-risk local-DB changes already discussed: keep WAL + synchronous=NORMAL, add optimize path, consider WAL growth control, and document workload-dependent knobs left at defaults.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Immersion tracker applies the agreed low-risk SQLite tuning changes without regressing current behavior
- [x] #2 Regression tests cover the new pragma/maintenance behavior
- [x] #3 Immersion tracking docs describe the tuning policy and notable defaults left unchanged
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add regression coverage for connection pragmas and verify the new WAL growth cap fails before implementation.
2. Add regression coverage for maintenance-time PRAGMA optimize and verify the test fails before implementation.
3. Implement the minimal SQLite tuning changes.
4. Update immersion-tracking docs for the new tuning policy.
5. Run targeted SQLite verification lanes and record results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Verification: `bun test src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker/maintenance.test.ts` passed (15 tests).
Verification: `bun run test:immersion:sqlite:src` passed (37 tests).
Verification: `bun run typecheck`, `bun run docs:test`, `bun run docs:build`, `bun run test:fast`, `bun run test:env`, and `bun run build` all passed.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added low-risk SQLite tuning improvements for the immersion tracker: `journal_size_limit` now bounds WAL growth, periodic maintenance runs `PRAGMA optimize`, regression tests cover both behaviors, and the immersion-tracking docs explain the maintained pragmas plus workload-dependent defaults left unchanged.
<!-- SECTION:FINAL_SUMMARY:END -->

62
backlog/tasks/task-180 - Fix-launcher-stats-command-timeout-for-slow-dashboard-startup.md
View File

@@ -1,62 +0,0 @@
---
id: TASK-180
title: Fix launcher stats command timeout for slow dashboard startup
status: Done
assignee:
- codex
created_date: '2026-03-17 15:16'
updated_date: '2026-03-18 05:28'
labels:
- launcher
- stats
- tests
milestone: m-1
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/commands/stats-command.ts
- /Users/sudacode/projects/japanese/SubMiner/launcher/main.test.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/launcher/commands/command-modules.test.ts
priority: medium
ordinal: 112500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Address the failing launcher stats startup path so the CLI tolerates the intended slow dashboard startup window instead of timing out early.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 The launcher stats command no longer times out before the intended slow-start window used by tests
- [x] #2 Regression coverage verifies the slower stats startup path succeeds
- [x] #3 The failing launcher stats startup test passes locally
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a focused launcher command regression that simulates a stats response arriving after the current timeout boundary and expects success.
2. Adjust the stats startup wait timeout in launcher/commands/stats-command.ts to match the intended slow-start tolerance.
3. Re-run the targeted command test, the previously failing launcher/main.test.ts case, and then the full launcher/main.test.ts file.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Verified the failing launcher path: launcher/main.test.ts timed out because launcher/commands/stats-command.ts only waited 8000ms for the stats startup response while the supported slow-start test writes the response after 9s.
Raised the stats startup response timeout to 12000ms so attached stats startup tolerates the existing slow cold-start window without changing command flow.
Verification passed: bun test launcher/commands/command-modules.test.ts --test-name-pattern "stats command launches attached app command with response path|stats command returns after startup response even if app process stays running|stats command throws when stats response reports an error"; bun test launcher/main.test.ts --test-name-pattern "stats command tolerates slower dashboard startup before timing out"; bun test launcher/main.test.ts; bun run test:fast.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed the launcher stats startup timeout by extending the response-file wait window in launcher/commands/stats-command.ts from 8s to 12s. The command flow was left unchanged; the launcher now simply gives the stats dashboard enough time to report readiness during slower cold starts, which matches the existing supported behavior exercised by launcher/main.test.ts.
Verification passed with the targeted launcher command tests, the previously failing slow-start launcher/main.test.ts case, the full launcher/main.test.ts file, and the full `bun run test:fast` gate.
<!-- SECTION:FINAL_SUMMARY:END -->

61
backlog/tasks/task-181 - Add-background-managed-stats-server-lifecycle-commands.md
View File

@@ -1,61 +0,0 @@
---
id: TASK-181
title: Add background-managed stats server lifecycle commands
status: Done
assignee:
- codex
created_date: '2026-03-17 15:31'
updated_date: '2026-03-18 05:28'
labels:
- cli
- launcher
- stats
milestone: m-1
dependencies: []
priority: medium
ordinal: 110500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add a dedicated background stats server mode that can be started and stopped from the launcher without blocking normal SubMiner instances. Launcher UX: `subminer stats -b` starts the stats server in the background, `subminer stats -s` stops the background stats server only, and plain `subminer stats` preserves the existing foreground/open-browser flow.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 `subminer stats -b` starts a background stats server without blocking other SubMiner instances.
- [x] #2 `subminer stats -s` stops only the background stats server and succeeds cleanly when state is stale.
- [x] #3 Plain `subminer stats` preserves current dashboard-open behavior.
- [x] #4 Automated tests cover launcher parsing/dispatch and app-side start-stop lifecycle behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Extend launcher stats parsing so `subminer stats -b` maps to background-start and `subminer stats -s` maps to stop-only while preserving existing cleanup/rebuild parsing.
2. Add launcher execution branches: detached background start with startup acknowledgement wait, stop command forwarding with response wait, and preserve existing attached foreground behavior for plain `stats` and cleanup flows.
3. Extend app CLI args and stats command handler for background start/stop lifecycle responses, including already-running and stale-state handling.
4. Add a dedicated stats-daemon runtime/state-file path in the app and bypass the normal single-instance lock only for that mode.
5. Verify with focused tests first, then launcher/env lane, and update task acceptance criteria/final summary before handoff.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
User approved option 2 design: dedicated app-side stats daemon, `subminer stats -b` to start, `subminer stats -s` to stop server only.
Implemented launcher `stats -b` and `stats -s` flows plus app-side `--stats-background` / `--stats-stop` handling.
Added background stats daemon state-file management and remote-daemon reuse so normal SubMiner instances do not try to bind a second stats server when the daemon is already running.
Verification: `bun test launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/parse-args.test.ts src/main/runtime/stats-cli-command.test.ts src/main/early-single-instance.test.ts`, `bun run typecheck`, `bun run test:env`, `bun run test:fast`, `bun run build`, `bun run test:smoke:dist`, `bun run docs:test`, `bun run docs:build`, `bun run changelog:lint`.
Non-blocking note: `bun run test:launcher` still showed unrelated existing failures in `launcher/picker.test.ts` and an intermittent `launcher/smoke.e2e.test.ts` mpv-status check on this machine; the narrowed launcher suites covering the changed stats paths passed.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added a dedicated background stats-daemon lifecycle for the launcher and app runtime. `subminer stats -b` now starts or reuses a detached stats server and returns after startup acknowledgement, while `subminer stats -s` stops that daemon without touching browser tabs. On the app side, new stats background/stop CLI flags bypass the normal single-instance lock only for daemon helper processes, write/read a daemon state file under user data, and reuse an already-running daemon instead of attempting a second local stats bind when another SubMiner instance needs stats access. Updated docs-site stats docs, added a changelog fragment, and covered the new flows with launcher parse/dispatch tests, app stats CLI handler tests, and single-instance bypass tests. Verification run: `bun run typecheck`, `bun run test:env`, `bun run test:fast`, `bun run build`, `bun run test:smoke:dist`, `bun run docs:test`, `bun run docs:build`, `bun run changelog:lint`, plus narrowed changed-path launcher/app test bundles.
<!-- SECTION:FINAL_SUMMARY:END -->

60
backlog/tasks/task-182 - Fix-session-stats-chart-known-word-totals-exceeding-total-words.md
View File

@@ -1,60 +0,0 @@
---
id: TASK-182
title: Fix session stats chart known-word totals exceeding total words
status: Done
milestone: m-1
assignee:
- codex
created_date: '2026-03-17 16:07'
updated_date: '2026-03-18 05:28'
labels: []
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/src/core/services/stats-server.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionDetail.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/__tests__/stats-server.test.ts
- /Users/sudacode/projects/japanese/SubMiner/stats/src/hooks/useSessions.ts
ordinal: 109500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the session detail stats display so the known-word series cannot exceed the total-word series for the same sample. Ground the fix in the actual immersion-tracker metrics used by the stats UI and cover the regression with automated tests.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Session detail data uses a consistent cumulative word metric so known-word counts do not exceed total words for a sample
- [x] #2 Automated tests cover the session known-word timeline contract and reproduce the regression scenario
- [x] #3 Session stats UI still renders the timeline and tooltip values correctly after the fix
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a regression test for `/api/stats/sessions/:id/known-words-timeline` covering a Japanese-style session where telemetry word counts can be lower than token-derived known-word counts.
2. Update the stats known-word timeline contract/server implementation so the series is expressed in the same cumulative unit used for total words in the session detail view.
3. Adjust the session detail UI/types to consume the corrected series and keep tooltip/legend copy coherent.
4. Run targeted tests for stats server and stats UI transforms, then summarize any wider verification skipped.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Implemented server-side known-word timeline fix to preserve stored line positions and accumulate known-word occurrences rather than compressed unique-headword counts.
Updated session-facing stats views to prefer `tokensSeen` over `wordsSeen` when available so displayed session word totals align with the session chart and lookup-rate denominator.
Verification: `bun test src/core/services/__tests__/stats-server.test.ts`, `bun test stats/src/lib/yomitan-lookup.test.tsx`, `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`, `bun run typecheck` all passed.
Verification skipped/blocker: `bun run typecheck:stats` still fails in pre-existing unrelated files `stats/src/components/anime/AnilistSelector.tsx`, `stats/src/lib/reading-utils.test.ts`, and `stats/src/lib/reading-utils.ts`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed the session stats mismatch that let known words outrun total words. The stats server now preserves actual subtitle-line positions and accumulates known-word occurrences for the session timeline, while session-facing stats views prefer token-based word totals when available. Added regression coverage for the known-word timeline API and for session-row word-count rendering, plus a user-visible changelog fragment.
<!-- SECTION:FINAL_SUMMARY:END -->

64
backlog/tasks/task-182.1 - Remove-misleading-session-new-word-metric-from-session-detail-chart.md
View File

@@ -1,64 +0,0 @@
---
id: TASK-182.1
title: Remove misleading session new-word metric from session detail chart
status: Done
assignee:
- '@codex'
created_date: '2026-03-18 01:41'
updated_date: '2026-03-18 05:28'
labels:
- bug
- stats
- ui
milestone: m-1
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionDetail.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionsTab.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/lib/media-session-list.test.tsx
parent_task_id: TASK-182
ordinal: 101500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Remove the misleading `New words` series from the session detail chart so the stats UI no longer presents a fabricated metric that mirrors total words. Keep the session chart focused on the real cumulative totals already backed by tracker data.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Expanded session detail chart no longer renders or labels a `New words` metric in the graph, tooltip, or legend
- [x] #2 Session detail still renders total-word and known-word series correctly after the metric removal
- [x] #3 Automated frontend coverage prevents the `New words` label from reappearing in expanded session detail
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a focused stats frontend regression test that renders expanded session detail and asserts the misleading `New words` label is absent while `Total words` remains.
2. Remove the fabricated `New words` area series, tooltip mapping, legend chip, and now-unused left-axis chart plumbing from `stats/src/components/sessions/SessionDetail.tsx`.
3. Add a user-visible changelog fragment describing the session chart cleanup.
4. Run targeted frontend tests plus cheap verification and record any blockers.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added a focused server-render regression test for SessionDetail copy to ensure the misleading `New words` label stays removed.
Removed the fabricated `New words` chart series and its legend/tooltip plumbing from the expanded session detail view.
Verification: `bun test stats/src/lib/session-detail.test.tsx stats/src/lib/media-session-list.test.tsx` passed. `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core stats/src/components/sessions/SessionDetail.tsx stats/src/lib/session-detail.test.tsx changes/2026-03-18-remove-session-new-words-series.md` passed and wrote artifacts under `.tmp/skill-verification/subminer-verify-20260317-184440-1aMWkM`.
Manual spot-check note: `bun test stats/src/lib/yomitan-lookup.test.tsx` is currently red on a pre-existing `AnimeOverviewStats` lookup-rate assertion unrelated to this session-detail change.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Removed the misleading `New words` metric from expanded session charts. Session detail now shows only the real total-word and known-word lines, backed by existing tracker data, with regression coverage that prevents the `New words` label from reappearing.
<!-- SECTION:FINAL_SUMMARY:END -->

58
backlog/tasks/task-183 - Fix-blank-stats-vocabulary-page-regression.md
View File

@@ -1,58 +0,0 @@
---
id: TASK-183
title: Fix blank stats vocabulary page regression
status: Done
milestone: m-1
assignee:
- codex
created_date: '2026-03-17 16:23'
updated_date: '2026-03-18 05:28'
labels: []
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/vocabulary/VocabularyTab.tsx
- /Users/sudacode/projects/japanese/SubMiner/stats/src/App.tsx
- /Users/sudacode/projects/japanese/SubMiner/stats/src/lib/api-client.ts
ordinal: 108500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Diagnose and fix the stats dashboard regression where the Vocabulary tab renders blank at runtime. Capture the frontend failure with browser debugging, add regression coverage, and restore the vocabulary view.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Vocabulary tab renders without a blank-screen failure in the stats dashboard
- [x] #2 Automated test coverage reproduces the failing code path and passes with the fix
- [x] #3 Targeted verification covers the affected stats UI/runtime path
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Reproduce the blank Vocabulary tab locally with a browser-visible stats UI instance and capture console/network failure details.
2. Add a focused regression test for the failing Vocabulary tab code path before editing production code.
3. Implement the minimal fix in the stats UI/runtime path.
4. Re-run targeted browser and automated verification, then record any skipped broader checks.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Identified the runtime failure in the browser console: React reported a hook-order change in `VocabularyTab` after the tab moved from loading to loaded state (`Rendered more hooks than during the previous render`).
Fixed `stats/src/components/vocabulary/VocabularyTab.tsx` by removing the late `useMemo` hook and computing `knownWordCount` as a plain derived value after the loading/error guards.
Added regression coverage in `stats/src/lib/vocabulary-tab.test.ts` to assert that `VocabularyTab` declares all hooks before the loading/error early returns.
Verification: `bun test stats/src/lib/vocabulary-tab.test.ts`, `bun test stats/src/lib/yomitan-lookup.test.tsx`, `bun run build:stats`, and a live Playwright check against the Vite app with stubbed stats API data all passed.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Fixed the blank Vocabulary tab regression in the stats UI. The root cause was a late `useMemo` hook declared after the loading/error early returns in `VocabularyTab`, which caused React to crash once vocabulary data finished loading. Removed that late hook, added a regression test guarding hook placement, verified the stats bundle builds, and confirmed in a live browser that the Vocabulary tab now renders loaded content instead of white-screening.
<!-- SECTION:FINAL_SUMMARY:END -->

57
backlog/tasks/task-184 - Stabilize-branch-verification-gate.md
View File

@@ -1,57 +0,0 @@
---
id: TASK-184
title: Stabilize branch verification gate
status: Done
assignee:
- Codex
created_date: '2026-03-17 19:28'
updated_date: '2026-03-18 05:28'
labels:
- stabilization
- ci
dependencies: []
references:
- package.json
- docs/workflow/verification.md
priority: medium
ordinal: 106500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Bring the current PR branch back to a green verification state by fixing any failing lint/format or test checks required for local handoff.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Repo source formatting checks pass for the current branch.
- [x] #2 Required local verification checks for this branch pass without introducing new failures.
- [x] #3 Any code or test adjustments stay scoped to the failing checks and preserve existing branch behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Fix the current source-formatting failures reported by `bun run format:check:src` using the minimal repo-standard Prettier output.
2. Re-run `bun run format:check:src` to confirm the lint/format gate is green.
3. Re-run the default handoff gate from `docs/workflow/verification.md`: `bun run typecheck`, `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
4. Because `docs-site/` is modified on this branch, also run `bun run docs:test` and `bun run docs:build`.
5. If any verification step fails after formatting, fix only the blocking issue and re-run the relevant lane until green.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Initial gate snapshot before edits: `typecheck`, `test:fast`, `test:env`, `build`, and `test:smoke:dist` passed; `format:check:src` failed on 15 files.
Applied repo-standard Prettier formatting to the 15 files reported by `bun run format:check:src`; no additional logic changes were introduced in this stabilization pass.
Verification after formatting: `bun run format:check:src` passed; `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core --lane runtime-compat --lane docs` passed with artifacts under `.tmp/skill-verification/subminer-verify-20260317-122947-hEInF0`; `bun run test:env` passed separately.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Branch verification gate is green again. Fixed the only failing local gate by applying Prettier formatting to the 15 flagged source files, then re-ran the required verification lanes: source format check, core lane (`typecheck` + `test:fast`), runtime-compat lane (`build`, `test:runtime:compat`, `test:smoke:dist`), docs lane (`docs:test`, `docs:build`), and `test:env`. All passed.
<!-- SECTION:FINAL_SUMMARY:END -->

67
backlog/tasks/task-185 - Clarify-library-stats-word-count-labels.md
View File

@@ -1,67 +0,0 @@
---
id: TASK-185
title: Clarify library stats word-count labels
status: Done
assignee:
- codex
created_date: '2026-03-17 22:58'
updated_date: '2026-03-18 05:28'
labels:
- bug
- stats
- ui
milestone: m-1
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/library/MediaHeader.tsx
- /Users/sudacode/projects/japanese/SubMiner/src/core/services/stats-server.ts
- >-
/Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker/query.ts
priority: medium
ordinal: 104500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the library/media detail stats header so occurrence-based subtitle counts are not presented as unique-word vocabulary totals. The UI should clearly distinguish subtitle word occurrences from unique known-word headword coverage to avoid misleading comparisons.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Library/media detail view labels subtitle occurrence totals with wording that does not imply unique vocabulary counts
- [x] #2 Known-words summary in the same view explicitly communicates that its denominator is unique words/headwords
- [x] #3 Frontend tests cover the updated copy so the mismatch does not regress
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a focused stats frontend test for MediaHeader copy that distinguishes occurrence totals from unique known-word coverage.
2. Update MediaHeader labels so occurrence-based totals no longer imply unique vocabulary counts.
3. Update the known-words label copy to explicitly state it is based on unique words/headwords.
4. Run targeted stats tests and record results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Root cause confirmed: library header compares occurrence-based totalWordsSeen against unique-headword known-words summary. Awaiting plan approval before code changes.
Updated library header copy to label totalWordsSeen as word occurrences and known-word coverage as known unique words. Added an optional initialKnownWordsSummary prop to support deterministic server-render tests without changing runtime behavior.
Verification: `bun test stats/src/lib/yomitan-lookup.test.tsx` passes. `bun run typecheck:stats` remains blocked by preexisting unrelated errors in stats/src/components/anime/AnilistSelector.tsx, stats/src/lib/reading-utils.ts, stats/src/lib/reading-utils.test.ts, and stats/src/lib/vocabulary-tab.test.ts.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Clarified the library/media header so occurrence-based subtitle counts are no longer presented as if they were unique vocabulary totals. The header now labels `totalWordsSeen` as `word occurrences`, and the known-words summary explicitly says `known unique words`, which matches the backend's DISTINCT headword calculation.
For regression coverage, added a focused MediaHeader render test that exercises the exact mismatch case (30 occurrences vs 34 unique words) and verifies the new copy. Also updated one stale AnimeOverviewStats assertion in the same targeted test file so the focused stats test lane is green.
Tests run:
- `bun test stats/src/lib/yomitan-lookup.test.tsx` ✅
- `bun run typecheck:stats` ⚠️ blocked by preexisting unrelated errors in AnilistSelector and reading-utils/vocabulary-tab stats files.
<!-- SECTION:FINAL_SUMMARY:END -->

77
backlog/tasks/task-186 - Remove-stats-Library-tab-and-add-episode-detail-navigation-from-anime-page.md
View File

@@ -1,77 +0,0 @@
---
id: TASK-186
title: Remove stats Library tab and add episode detail navigation from anime page
status: Done
assignee:
- codex
created_date: '2026-03-17 23:19'
updated_date: '2026-03-18 05:28'
labels:
- stats
- ui
milestone: m-1
dependencies: []
references:
- /Users/sudacode/projects/japanese/SubMiner/stats/src/App.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/layout/TabBar.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/anime/AnimeDetailView.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/anime/EpisodeList.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/library/MediaDetailView.tsx
priority: medium
ordinal: 103500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Update the stats UI so watched-file detail is no longer exposed as a top-level Library tab. Users should open dedicated episode detail pages from the anime detail page while preserving inline quick-peek session expansion.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Stats navigation no longer shows a top-level Library tab.
- [x] #2 Anime episode rows keep inline quick-peek expansion and also expose an explicit control to open the dedicated episode detail page.
- [x] #3 Dedicated episode detail navigation lands on the existing watched-file detail view with a back action that returns to the originating anime detail page.
- [x] #4 Relevant stats component tests cover the new navigation flow and removed tab behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add app-level stats navigation state for dedicated media detail so anime flows can open watched-file detail without a Library tab.
2. Remove the Library tab from the tab bar and top-level tab panels while preserving existing Overview/Anime/Trends/Vocabulary/Sessions behavior.
3. Update anime detail episode list to keep row expansion for quick peek and add an explicit button that opens the dedicated detail view for the selected episode.
4. Reuse MediaDetailView for episode detail and adjust its back action to return to the originating anime detail page.
5. Add or update stats component tests to cover the removed Library tab and the new anime-to-episode-detail navigation flow.
6. Run targeted stats tests, then targeted SubMiner verification lanes if needed for touched files.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Implemented app-level stats navigation state for dedicated media detail and removed the Library tab from the tab bar and top-level panels.
Anime episode rows now keep inline quick-peek expansion and expose a visible Details button that opens the dedicated watched-file detail view.
Reused MediaDetailView for anime-origin episode navigation with a Back to Anime label and app-level return path.
Verification: bun test stats/src/lib/stats-navigation.test.ts stats/src/lib/stats-ui-navigation.test.tsx; bun run build:stats; bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core ... => passed.
Observed unrelated existing stats workspace issues outside this task when running bun run typecheck:stats, including AnilistSelector/reading-utils/vocabulary-tab and an outdated AnimeOverviewStats test signature.
Reopened for bugfix: episode Details button is a no-op when anime detail is open from within AnimeTab because app-level selectedAnimeId is not retained there. Follow-up fix will pass animeId explicitly through the callback chain instead of depending on App route state.
Bugfix: the Details button now passes animeId explicitly from AnimeTab/AnimeDetailView into app-level media-detail navigation, so dedicated episode navigation works even when the anime page was opened from within the tab rather than seeded by App state.
Bugfix verification: bun test stats/src/lib/stats-navigation.test.ts stats/src/lib/stats-ui-navigation.test.tsx; bun run build:stats => passed.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Removed the stats Library tab and replaced that navigation path with app-level dedicated media-detail routing from the anime page. Episode rows still support inline quick peek, and now also provide a Details button that opens the dedicated episode view and returns cleanly to the anime detail page. Added navigation-focused tests for the removed tab and anime-origin media-detail flow, and verified the change with targeted tests, stats bundle build, and the repo core verification lane.
<!-- SECTION:FINAL_SUMMARY:END -->

81
backlog/tasks/task-187 - Replace-episode-detail-session-history-with-expandable-inline-session-details.md
View File

@@ -1,81 +0,0 @@
---
id: TASK-187
title: Replace episode detail session history with expandable inline session details
status: Done
assignee:
- codex
created_date: '2026-03-17 23:42'
updated_date: '2026-03-18 05:28'
labels:
- stats
- ui
milestone: m-1
dependencies: []
references:
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/library/MediaDetailView.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/library/MediaSessionList.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionRow.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionDetail.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionsTab.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/overview/OverviewTab.tsx
- >-
/Users/sudacode/projects/japanese/SubMiner/stats/src/components/overview/RecentSessions.tsx
documentation:
- >-
/Users/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-17-episode-detail-session-accordion-design.md
- >-
/Users/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-17-episode-detail-session-accordion.md
priority: medium
ordinal: 102500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Update the dedicated episode detail page so its session history uses the same expandable session-row behavior as the Sessions page, including inline timeline details and session deletion, instead of navigating away to the Sessions tab. Also update home-page session navigation so recent session links open the associated episode detail page rather than the Sessions tab.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Dedicated episode detail session history uses expandable inline rows styled like the Sessions page instead of linking to the Sessions tab.
- [x] #2 Expanding a session on the episode detail page shows the full existing session detail panel, including the timeline chart and stats.
- [x] #3 Episode detail session rows retain a session delete control with the same behavior and safeguards as the Sessions page.
- [x] #4 Home-page recent session navigation opens the associated episode detail page when a session is tied to a video, instead of routing to the Sessions tab.
- [x] #5 Relevant stats tests cover the inline session expansion/delete behavior and the updated home-page navigation path.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing tests for media-detail session accordion structure and for overview-to-media-detail navigation, keeping orphan-session fallback coverage.
2. Rework MediaSessionList to reuse SessionRow and SessionDetail with local expansion state and delete affordance matching the Sessions page.
3. Move media-detail session mutation/delete ownership into MediaDetailView so deletes update the current episode page immediately.
4. Add app-level direct media-detail navigation from overview/home-page session rows when videoId exists; keep Sessions-tab fallback for sessions without videoId.
5. Run targeted tests, stats build, and the SubMiner core verification lane; then update TASK-187 with results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added approved design/plan docs at docs/plans/2026-03-17-episode-detail-session-accordion-design.md and docs/plans/2026-03-17-episode-detail-session-accordion.md before implementation.
MediaDetailView now owns local session state and delete handling, derives displayed media aggregates from the current session list, and renders MediaSessionList as an inline accordion instead of a session-page link list.
MediaSessionList now reuses SessionRow and full SessionDetail so episode-level session history matches Sessions-page dropdown behavior and keeps the same delete affordance.
Overview/home-page recent session navigation now prefers dedicated media detail when session.videoId exists and falls back to the Sessions tab only for orphan sessions without videoId.
Verification passed: bun test stats/src/lib/stats-navigation.test.ts stats/src/lib/stats-ui-navigation.test.tsx stats/src/lib/media-session-list.test.tsx; bun run build:stats; bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core stats/src/App.tsx stats/src/components/overview/OverviewTab.tsx stats/src/components/overview/RecentSessions.tsx stats/src/components/library/MediaDetailView.tsx stats/src/components/library/MediaSessionList.tsx stats/src/lib/stats-navigation.ts stats/src/lib/stats-navigation.test.ts stats/src/lib/stats-ui-navigation.test.tsx stats/src/lib/media-session-list.test.tsx => passed.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Dedicated episode detail pages now show inline expandable session rows using the same shared SessionRow + SessionDetail UI as the Sessions page, including per-session delete controls. Overview/home-page recent session clicks now open the episode detail page whenever a backing video exists, with Sessions-tab fallback only for sessions missing videoId. Added navigation and media-session-list tests plus design/implementation docs, and verified the change with targeted tests, stats bundle build, and the SubMiner core verification lane.
<!-- SECTION:FINAL_SUMMARY:END -->

56
backlog/tasks/task-187.1 - Auto-expand-targeted-session-when-opening-media-detail.md
View File

@@ -1,56 +0,0 @@
---
id: TASK-187.1
title: Auto-expand targeted session when opening media detail
status: Done
assignee:
- codex
created_date: '2026-03-18 01:32'
updated_date: '2026-03-18 05:28'
labels:
- stats
- ui
milestone: m-1
dependencies: []
references:
- stats/src/lib/stats-navigation.ts
- stats/src/App.tsx
- stats/src/components/overview/RecentSessions.tsx
- stats/src/components/library/MediaDetailView.tsx
- stats/src/components/library/MediaSessionList.tsx
- stats/src/lib/stats-navigation.test.ts
parent_task_id: TASK-187
priority: medium
ordinal: 117500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
When a navigation path opens episode/media detail with a known session ID, the matching session row in media detail should auto-expand so the user lands directly on the intended session details instead of only the episode history page.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Media detail navigation state can carry an optional target session ID alongside the selected video.
- [x] #2 Any navigation path that opens media detail with a known session ID causes that session row to auto-expand when the episode history loads.
- [x] #3 Session-tab fallback for orphan sessions without a video still behaves as it does now.
- [x] #4 Media detail auto-expansion clears or stabilizes its one-shot navigation state so normal manual expand/collapse behavior still works after landing.
- [x] #5 Relevant navigation/component tests cover the targeted media-detail auto-expand behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Extend media-detail navigation state to optionally carry a target session ID while preserving the existing orphan-session fallback to the Sessions tab.
2. Update app-level navigation helpers and overview recent-session click handling to pass session IDs into media-detail navigation whenever both video and session are known.
3. Thread the one-shot target session ID into MediaDetailView and MediaSessionList so the matching accordion row auto-expands on load, then clear/stabilize that state so manual toggling still behaves normally.
4. Update targeted stats navigation/component tests to cover media-detail auto-expansion and fallback behavior.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Extended media-detail navigation state to carry an optional `initialSessionId`, updated overview/app navigation to pass session IDs into media detail whenever a video-backed session is clicked, and wired `MediaDetailView` + `MediaSessionList` to auto-expand and then consume that one-shot session target.
Updated `stats-navigation.test.ts` to cover the new navigation-state shape. Validation not run in this pass, so acceptance criteria remain unchecked pending verification.
<!-- SECTION:NOTES:END -->

56
backlog/tasks/task-189 - Replace-stats-word-counts-with-Yomitan-token-counts.md
View File

@@ -1,56 +0,0 @@
---
id: TASK-189
title: Replace stats word counts with Yomitan token counts
status: Done
assignee:
- codex
created_date: '2026-03-18 01:35'
updated_date: '2026-03-18 05:28'
labels:
- stats
- tokenizer
- bug
milestone: m-1
dependencies: []
references:
- src/core/services/immersion-tracker-service.ts
- src/core/services/immersion-tracker/reducer.ts
- src/core/services/immersion-tracker/storage.ts
- src/core/services/immersion-tracker/query.ts
- src/core/services/immersion-tracker/lifetime.ts
- stats/src/components
- stats/src/lib/yomitan-lookup.ts
priority: medium
ordinal: 100500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Replace heuristic immersion stats word counting with Yomitan token counts. Session/media/anime stats should use the exact merged Yomitan token stream as the denominator and display metric, with no whitespace/CJK-character fallback and no active `wordsSeen` concept in the runtime, storage, API, or stats UI.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 `recordSubtitleLine` derives session count deltas from Yomitan token arrays instead of `calculateTextMetrics`.
- [x] #2 Active immersion tracking/storage/query code no longer depends on `wordsSeen` / `totalWordsSeen` fields for stats behavior.
- [x] #3 Stats UI labels and lookup-rate copy refer to tokens instead of words where those counts are shown to users.
- [x] #4 Regression tests cover token-count sourcing, zero-count behavior when tokenization payload is absent, and updated stats copy.
- [x] #5 A changelog fragment documents the user-visible stats denominator change.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing tracker tests proving subtitle count metrics come from Yomitan token arrays and stay zero when tokenization is absent.
2. Add failing stats UI tests for token-based copy and token-count display helpers.
3. Remove `wordsSeen` from active tracker/session/query/type paths and use `tokensSeen` as the single stats count field.
4. Update stats UI labels and lookup-rate copy from words to tokens.
5. Run targeted verification, then add the changelog fragment and any needed docs update.
<!-- SECTION:PLAN:END -->
## Outcome
<!-- SECTION:OUTCOME:BEGIN -->
Completed. Stats subtitle counts now come directly from Yomitan merged-token counts, `wordsSeen` is removed from the active tracker/storage/query/UI path, token-facing copy is updated, and focused regression coverage plus `bun run typecheck` are green.
<!-- SECTION:OUTCOME:END -->

54
backlog/tasks/task-190 - Add-hover-popups-for-session-chart-events.md
View File

@@ -1,54 +0,0 @@
---
id: TASK-190
title: Add hover popups for session chart events
status: Done
assignee:
- Codex
created_date: '2026-03-17 22:20'
updated_date: '2026-03-18 05:28'
labels:
- stats
- ui
- bug
milestone: m-1
dependencies: []
references:
- stats/src/components/sessions/SessionDetail.tsx
- stats/src/lib/session-events.ts
- stats/src/hooks/useSessions.ts
- stats/src/lib/api-client.ts
- docs/plans/2026-03-17-session-event-hover-popups-design.md
priority: medium
ordinal: 105500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Add hover/focus popups to session chart event markers so pauses, seeks, lookups, and card-mine events explain themselves inline. Card-mine events should lazy-load available Anki note info and present it in a richer popup with browse affordances.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Hovering or focusing a session-chart marker opens an event-specific popup.
- [x] #2 Pause, seek, and lookup popups show concise event copy derived from marker metadata.
- [x] #3 Card-mine popups lazily fetch and cache Anki note info by note id.
- [x] #4 Card-mine popups show a formatted fallback when note info is missing or still loading.
- [x] #5 Regression tests cover event payload shaping and popup rendering behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing tests for event metadata shaping and popup content selection.
2. Extend session-event shaping to parse payload JSON into typed marker metadata.
3. Add lazy note-info fetch/cache state for card-mine markers.
4. Render interactive marker overlay + custom popup in the session detail chart.
5. Run targeted stats/core verification and update this task with the result.
<!-- SECTION:PLAN:END -->
## Outcome
<!-- SECTION:OUTCOME:BEGIN -->
Completed. Session-chart event markers now open event-specific hover/focus popups, including lazy-loaded Anki note info for card-mine events with browse affordances. Verification passed via targeted stats tests, `bun run typecheck`, and the core verification lane in `.tmp/skill-verification/subminer-verify-20260317-222545-CQzyqK`.
<!-- SECTION:OUTCOME:END -->

62
backlog/tasks/task-193 - Fix-session-chart-event-popup-position-drift.md
View File

@@ -1,62 +0,0 @@
---
id: TASK-193
title: Fix session chart event popup position drift
status: Done
assignee:
- Codex
created_date: '2026-03-17 23:55'
updated_date: '2026-03-17 23:59'
labels:
- stats
- ui
- bug
milestone: m-1
dependencies: []
references:
- stats/src/components/sessions/SessionDetail.tsx
- stats/src/components/sessions/SessionEventOverlay.tsx
- stats/src/lib/session-events.ts
priority: medium
ordinal: 105600
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Fix the session timeline event popup trigger positions so hover markers stay aligned with the underlying chart event lines across the full visible time range.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Event popup triggers stay horizontally aligned with chart event lines from session start through session end.
- [x] #2 Alignment logic uses the rendered chart plot area rather than guessed container percentages.
- [x] #3 Regression coverage locks the marker-position projection math.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing regression test for marker-position projection with chart offsets.
2. Capture the rendered plot box from Recharts and pass it into the overlay.
3. Position overlay markers in plot-area pixels, rerun targeted stats verification, then record the result.
<!-- SECTION:PLAN:END -->
## Outcome
<!-- SECTION:OUTCOME:BEGIN -->
Completed. Session event hover markers now read the actual Recharts plot-area offset and width, then project marker X positions into plot-area pixels instead of full-container percentages. That keeps popup triggers aligned with the underlying reference lines across long session timelines.
Verification:
- `bun test stats/src/lib/session-events.test.ts stats/src/lib/session-detail.test.tsx stats/src/components/sessions/SessionEventPopover.test.tsx`
- `cd stats && bun run build`
- `bun x prettier --check 'stats/src/components/sessions/SessionDetail.tsx' 'stats/src/components/sessions/SessionEventOverlay.tsx' 'stats/src/lib/session-events.ts' 'stats/src/lib/session-events.test.ts' 'backlog/tasks/task-193 - Fix-session-chart-event-popup-position-drift.md'`
- `bun run typecheck:stats` still fails on pre-existing unrelated errors in `src/components/anime/AnilistSelector.tsx`, `src/components/library/LibraryTab.tsx`, `src/lib/reading-utils.test.ts`, `src/lib/reading-utils.ts`, `src/lib/vocabulary-tab.test.ts`, and `src/lib/yomitan-lookup.test.tsx`
<!-- SECTION:OUTCOME:END -->

64
backlog/tasks/task-195 - Keep-final-card-mine-OSD-result-from-being-overwritten-by-progress-spinner.md
View File

@@ -1,64 +0,0 @@
---
id: TASK-195
title: Keep final card-mine OSD result from being overwritten by progress spinner
status: Done
assignee:
- Codex
created_date: '2026-03-18 19:40'
updated_date: '2026-03-18 19:49'
labels:
- anki
- ui
- bug
milestone: m-1
dependencies: []
references:
- src/anki-integration/ui-feedback.ts
- src/anki-integration.ts
- src/anki-integration/card-creation.ts
priority: medium
ordinal: 105610
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
When a card mine finishes, the mpv OSD currently tries to show the final status text but the in-flight Anki progress spinner can immediately overwrite it on the next tick. Stop the spinner first, then show a single-line final result with a success/failure marker and the mined-word notification.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Successful mine/update OSD results render after the spinner is stopped and do not get overwritten by a later spinner tick.
- [x] #2 Failure results that replace the spinner show an `x` marker and stay visible on the same OSD line.
- [x] #3 Regression coverage locks the spinner teardown/result-notification ordering.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add a focused failing regression test around the Anki UI-feedback spinner/result helper.
2. Add a helper that stops progress before emitting the final OSD result line with `✓`/`x`.
3. Route mine/update result notifications through that helper, then run targeted verification.
<!-- SECTION:PLAN:END -->
## Outcome
<!-- SECTION:OUTCOME:BEGIN -->
Added a dedicated Anki UI-feedback result helper that force-clears the in-flight spinner state before emitting the final OSD result line. Successful card-update notifications now render as `✓ Updated card: ...`, and sentence-card creation failures now render as `x Sentence card failed: ...` without a later spinner tick reclaiming the line.
Verification:
- `bun test src/anki-integration/ui-feedback.test.ts`
- `bun test src/anki-integration/ui-feedback.test.ts src/anki-integration/note-update-workflow.test.ts src/anki-integration.test.ts src/core/services/mining.test.ts src/main/runtime/mining-actions.test.ts`
- `bun x prettier --check src/anki-integration/ui-feedback.ts src/anki-integration/ui-feedback.test.ts src/anki-integration.ts src/anki-integration/card-creation.ts "backlog/tasks/task-195 - Keep-final-card-mine-OSD-result-from-being-overwritten-by-progress-spinner.md" changes/2026-03-18-mine-osd-spinner-result.md`
- `bun run changelog:lint`
- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/anki-integration/ui-feedback.ts src/anki-integration/ui-feedback.test.ts src/anki-integration.ts src/anki-integration/card-creation.ts changes/2026-03-18-mine-osd-spinner-result.md`
- Verifier artifacts: `.tmp/skill-verification/subminer-verify-20260318-194614-uZMrAx/`
<!-- SECTION:OUTCOME:END -->

64
backlog/tasks/task-84 - Migrate-AniSkip-metadatalookup-orchestration-to-launcher-Electron.md
View File

@@ -1,64 +0,0 @@
---
id: TASK-84
title: Migrate AniSkip metadata+lookup orchestration to launcher/Electron
status: Done
assignee:
- Codex
created_date: '2026-03-03 08:31'
updated_date: '2026-03-16 05:13'
labels:
- enhancement
- aniskip
- launcher
- mpv-plugin
dependencies: []
references:
- launcher/aniskip-metadata.ts
- launcher/mpv.ts
- plugin/subminer/aniskip.lua
- plugin/subminer/options.lua
- plugin/subminer/state.lua
- plugin/subminer/lifecycle.lua
- plugin/subminer/messages.lua
- plugin/subminer.conf
- launcher/aniskip-metadata.test.ts
documentation:
- docs/mpv-plugin.md
- launcher/aniskip-metadata.ts
- plugin/subminer/aniskip.lua
- docs/architecture.md
priority: medium
ordinal: 97500
---
## 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.
- [x] #4 Standalone mpv/plugin usage without launcher payload continues to function using existing async in-plugin lookup path.
- [x] #5 Docs and defaults are updated to document new script-option contract.
- [x] #6 Launcher tests cover payload generation contract and fallback behavior where metadata is unavailable.
<!-- AC:END -->
## 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.
<!-- 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 -->

65
backlog/tasks/task-85.1 - Address-PR-14-character-dictionary-review-follow-ups.md
View File

@@ -1,65 +0,0 @@
---
id: TASK-85.1
title: 'Address PR #14 character dictionary review follow-ups'
status: Done
assignee:
- codex
created_date: '2026-03-06 07:48'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/launcher/commands/dictionary-command.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
- /home/sudacode/projects/japanese/SubMiner/launcher/types.ts
documentation:
- 'https://docs.anilist.co/guide/rate-limiting'
parent_task_id: TASK-85
ordinal: 93500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Apply the accepted follow-up fixes from Claude's PR review for the AniList character dictionary work: remove dead launcher code, deduplicate video extension handling where practical, and add explicit pacing for AniList character-page requests / character image downloads so the integration stays within AniList rate-limiting expectations.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Launcher dictionary command no longer contains unreachable dead code after the app handoff.
- [x] #2 Character dictionary runtime no longer maintains a separate ad hoc video extension list when existing shared extension data can be reused safely.
- [x] #3 Character dictionary generation spaces outbound AniList-related requests with explicit named delays, and tests cover the pacing behavior and unchanged command forwarding behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Add failing tests for dictionary command handoff semantics and dictionary runtime request pacing.
2. Remove unreachable boolean return path from the launcher dictionary command while preserving call sites.
3. Reuse the shared launcher video extension set inside the character dictionary runtime with extname normalization, then add named AniList pacing constants for page fetches and character image downloads.
4. Run targeted tests, then broader relevant test slices, and update acceptance criteria / notes with the validated result.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Added a shared `src/shared/video-extensions.ts` source and rewired both launcher/runtime consumers to remove the duplicated runtime extension list.
Replaced the hardcoded AniList page sleep with a per-generation AniList request pacer (2000ms between API requests) plus 250ms spacing between character image download attempts, including failed image fetches.
Hardened `runDictionaryCommand` so an unexpected return from the `never`-typed app handoff throws immediately instead of silently falling through.
Validated with targeted and adjacent test slices plus `bun run tsc --noEmit`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Removed the dead post-handoff return from the launcher dictionary command and replaced it with an explicit invariant error if the `never`-typed app handoff ever returns unexpectedly. Extracted video extension data into `src/shared/video-extensions.ts` so the launcher and character dictionary runtime share one source of truth.
Adjusted character dictionary generation to use a per-run AniList request pacer with a conservative 2000ms delay between AniList API calls, and added 250ms spacing between character image download attempts so repeated image fetches are not bursty even when an image URL fails. Added regression coverage for the pacing behavior and the launcher handoff invariant.
Validation: `bun test src/main/character-dictionary-runtime.test.ts`, `bun test launcher/commands/command-modules.test.ts`, `bun test launcher/main.test.ts launcher/parse-args.test.ts src/cli/args.test.ts src/core/services/cli-command.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts`, `bun run tsc --noEmit`.
<!-- SECTION:FINAL_SUMMARY:END -->

55
backlog/tasks/task-86 - Require-target-path-for-launcher-dictionary-command-and-forward-dictionary-target-to-app-runtime.md
View File

@@ -1,55 +0,0 @@
---
id: TASK-86
title: >-
Require target path for launcher dictionary command and forward dictionary
target to app runtime
status: Done
assignee: []
created_date: '2026-03-03 09:22'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
priority: high
ordinal: 95500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Change dictionary flow so launcher uses `subminer dictionary <file-or-directory>` and forwards target to app without playback launch. Keep direct app `--dictionary` behavior for in-session/mpv-triggered use, adding optional `--dictionary-target` path override.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Launcher `dictionary`/`dict` requires a target path argument and parses optional log level.
- [x] #2 Launcher forwards target to app as `--dictionary-target <path>` together with `--dictionary`.
- [x] #3 App CLI parses optional `--dictionary-target` and dictionary command passes it into dictionary runtime.
- [x] #4 Dictionary runtime resolves explicit file/directory target for AniList guess flow; falls back to current playback when target is absent.
- [x] #5 Docs/tests are updated for new launcher invocation syntax.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Launcher dictionary subcommand now requires a positional target path (`subminer dictionary <path>` / `dict <path>`) via commander argument wiring in `launcher/config/cli-parser-builder.ts`.
Added `dictionaryTarget` flow in launcher normalization/types and path validation (must be existing local file or directory) in `launcher/config/args-normalizer.ts`.
Launcher dictionary command now forwards `--dictionary --dictionary-target <resolved-path>` to app binary in `launcher/commands/dictionary-command.ts`.
App CLI now parses optional `--dictionary-target` in `src/cli/args.ts`; dictionary handler passes target through to runtime in `src/core/services/cli-command.ts`.
Dictionary runtime now resolves explicit target inputs in `src/main/character-dictionary-runtime.ts`: file target uses file path/title; directory target selects first video file recursively (fallback to directory name), and still falls back to current playback when target is absent.
Updated context/dependency pass-through for dictionary target argument (`src/main.ts`, `src/main/runtime/cli-command-context-main-deps.ts`).
Updated tests/docs for new syntax and forwarding behavior (`launcher/main.test.ts`, `launcher/parse-args.test.ts`, `launcher/commands/command-modules.test.ts`, `src/cli/args.test.ts`, `src/cli/help.test.ts`, `docs/usage.md`, `docs/launcher-script.md`).
Follow-up noise reduction: dictionary commands now opt into lightweight startup path by extending `shouldSkipHeavyStartup` in `src/main.ts` to include `initialArgs.dictionary`. This skips heavy app-ready initialization (mpv client creation/background warmups/overlay bootstrap) for dictionary CLI runs.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Launcher dictionary flow now uses explicit targets: run `subminer dictionary <file-or-directory>`. It forwards target to app and performs dictionary generation without depending on currently playing media. Direct app `--dictionary` remains available for in-session/mpv-triggered workflows, with optional `--dictionary-target` override support.
<!-- SECTION:FINAL_SUMMARY:END -->

69
backlog/tasks/task-87.1 - Testing-workflow-make-standard-test-commands-reflect-the-maintained-test-surface.md
View File

@@ -1,69 +0,0 @@
---
id: TASK-87.1
title: >-
Testing workflow: make standard test commands reflect the maintained test
surface
status: Done
assignee:
- OpenCode
created_date: '2026-03-06 03:19'
updated_date: '2026-03-16 05:13'
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
ordinal: 86500
---
## 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 -->
- [x] #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.
- [x] #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.
- [x] #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.
- [x] #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. Update `package.json` to replace the current file-by-file test allowlists with a documented lane matrix: keep `test`/`test:fast` as the quick default lane, add `test:full` for the maintained source test surface, and add `test:env` for slower or environment-specific checks.
2. Use directory-based discovery for maintained suites so new tests under stable surfaces such as `src/main`, `src/anki-integration`, and `launcher` are not silently omitted by default script maintenance.
3. Split environment-specific verification into explicit commands for checks such as launcher smoke/plugin coverage and sqlite-gated tests, instead of leaving them undocumented or mixed into the default signal.
4. Update `README.md` with a contributor-facing testing matrix that explains fast, full, and environment-specific verification, including any prerequisites or expected skip behavior.
5. Verify the matrix by running representative targeted tests plus the documented lane commands, demonstrating that previously omitted entry/runtime, Anki integration, and main runtime tests now belong to automated commands.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Reviewed task context via Backlog MCP plus repo audit. Current package.json test scripts still rely on hand-maintained file allowlists and omit large maintained areas including src/main/runtime, src/anki-integration, and src/main-entry-runtime.test.ts. Preparing an implementation plan and contributor-facing test matrix update before code changes.
Saved detailed implementation plan to docs/plans/2026-03-06-testing-workflow-test-matrix.md and recorded the approved direction in the Backlog task before implementation.
Implemented a lane-based test matrix. Added `scripts/run-test-lane.mjs` so Bun-managed `src/**` and launcher unit lanes discover files automatically while excluding a small explicit Node-only set instead of relying on large hand-maintained allowlists. Added `test:node:compat` for `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and `registry` suites, kept `test:env` for launcher smoke/plugin plus SQLite-backed immersion checks, and updated `README.md` with the contributor-facing matrix and exclusions.
Validated the new matrix with `bun run test:fast`, `bun run test:full`, `bun run test:env`, `bun run test:src`, `bun run test:launcher:unit:src`, `bun run test:node:compat`, and targeted `bun test src/core/services/anilist/anilist-updater.test.ts`. Representative previously omitted surfaces now run through automated commands: `src/main-entry-runtime.test.ts` via `test:fast`, `src/anki-integration/anki-connect-proxy.test.ts` via `test:fast`/`test:src`, and `src/main/runtime/registry.test.ts` via `test:node:compat`/`test:full`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Reworked the repository test matrix so standard commands reflect the maintained test surface without relying on brittle file allowlists. Added automated Bun discovery lanes for Bun-compatible `src/**` and launcher unit suites, a documented Node compatibility lane for Electron/sqlite-sensitive tests, and updated the contributor docs with fast/full/environment-specific guidance plus explicit exclusions. Verified with `bun run test:fast`, `bun run test:full`, and `bun run test:env`, along with the component lanes and targeted regression coverage for the updated AniList guessit test seam.
<!-- SECTION:FINAL_SUMMARY:END -->

87
backlog/tasks/task-87.2 - Subtitle-sync-verification-replace-the-no-op-subtitle-lane-with-real-automated-coverage.md
View File

@@ -1,87 +0,0 @@
---
id: TASK-87.2
title: >-
Subtitle sync verification: replace the no-op subtitle lane with real
automated coverage
status: Done
assignee:
- Kyle Yasuda
created_date: '2026-03-06 03:19'
updated_date: '2026-03-16 05:13'
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
ordinal: 92500
---
## 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 -->
- [x] #1 The test:subtitle entrypoint runs real automated verification instead of echoing a placeholder message.
- [x] #2 The subtitle verification lane covers both alass and ffsubsync behavior, including at least one non-happy-path scenario relevant to current functionality.
- [x] #3 Contributor-facing documentation points to the real subtitle verification command and no longer implies a dedicated test lane exists when it does not.
- [x] #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 -->
Plan of record:
1. Replace the placeholder package-script lane with a real `test:subtitle:src` command that runs the maintained subtitle-sync tests directly (`src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`), and point `test:subtitle` at that lane instead of build+echo behavior.
2. Add one focused ffsubsync non-happy-path test in `src/core/services/subsync.test.ts` so the dedicated lane explicitly covers both engines plus failure propagation relevant to current functionality.
3. Update `README.md` contributor guidance to name `bun run test:subtitle` as the subtitle verification command and explain that it reuses the maintained subsync tests already included in broader core coverage.
4. Verify the final strategy by running `bun run test:subtitle` and `bun run test:core:src` so the dedicated lane stays aligned with the repository-wide matrix instead of creating a divergent hidden suite.
Detailed execution plan saved at `docs/plans/2026-03-06-subtitle-sync-verification.md`.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Reviewed task references and current subtitle verification surface. Existing coverage already lives in `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`; `test:subtitle` is still a placeholder build+echo wrapper. The referenced report `docs/reports/2026-02-22-task-100-dead-code-report.md` is not present in the workspace, so planning used the task body plus repository state instead.
Implementation plan written and saved to `docs/plans/2026-03-06-subtitle-sync-verification.md`. Proceeding with execution per the task request.
Replaced the placeholder subtitle lane with `test:subtitle:src` in `package.json`, pointing `test:subtitle` directly at `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts` instead of build+echo behavior.
Added explicit ffsubsync failure-path coverage in `src/core/services/subsync.test.ts`, asserting non-zero command failures surface detailed `ffsubsync synchronization failed` messaging alongside existing alass coverage.
Updated `README.md` verification guidance to point contributors at `bun run test:subtitle` and explain that the lane reuses the maintained subsync tests already included in `bun run test:core`.
Verification: `bun run test:subtitle` passed (15 tests across 2 files). `bun run test:core:src` also passed (373 pass, 6 skip, 0 fail), confirming the dedicated subtitle lane stays aligned with the broader matrix.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented a real subtitle verification lane by replacing the placeholder `test:subtitle` build+echo flow with a source-level `test:subtitle:src` command that runs the maintained subtitle-sync tests directly from `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`. This keeps subtitle verification explicit for contributors while still reusing the same maintained test surface already covered by `test:core`.
Expanded subtitle-sync coverage with an explicit ffsubsync failure-path test so the dedicated lane now exercises both engines plus a user-visible non-happy path. Updated `README.md` to document `bun run test:subtitle` as the contributor-facing subtitle verification command and to explain its relationship to the broader core suite.
Verification run:
- `bun run test:subtitle`
- `bun run test:core:src`
Notes:
- The task reference `docs/reports/2026-02-22-task-100-dead-code-report.md` was not present in the workspace during execution, so implementation used the task body and live repository state as the source of truth.
<!-- SECTION:FINAL_SUMMARY:END -->

76
backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md
View File

@@ -1,76 +0,0 @@
---
id: TASK-87.3
title: >-
Immersion tracking verification: make SQLite-backed persistence tests visible
and reproducible
status: Done
assignee:
- Kyle Yasuda
created_date: '2026-03-06 03:19'
updated_date: '2026-03-16 05:13'
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
ordinal: 90500
---
## 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 -->
- [x] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute.
- [x] #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.
- [x] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on.
- [x] #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 -->
Implementation plan recorded in `docs/plans/2026-03-06-immersion-sqlite-verification.md`.
1. Update `src/core/services/immersion-tracker-service.test.ts` and `src/core/services/immersion-tracker/storage-session.test.ts` so unsupported `node:sqlite` runtimes emit an explicit skip reason instead of a silent top-level skip alias.
2. Add a dedicated `package.json` SQLite verification lane that runs both immersion persistence suites together under a runtime with `node:sqlite` support, likely via built `dist/**` tests executed by Node.
3. Wire that lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` so automated verification includes a real DB-backed persistence/finalization check.
4. Document the new command, prerequisites, and coverage in `README.md`, including the distinction between Bun's default lane and the reproducible SQLite lane.
5. Validate the final lane by running the dedicated command and confirming it exercises persistence/finalization behavior beyond the seam-only tests.
Execution adjustment: the reproducible lane uses `node --experimental-sqlite --test ...` because Node 22 exposes `node:sqlite` behind the experimental flag. Running that lane also exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`, so the final implementation includes a small SQL placeholder fix required for the new cross-runtime verification path.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Confirmed Bun 1.3.5 lacks `node:test` `t.skip()` support, so explicit unsupported-runtime messaging is surfaced with file-level warnings while the SQLite-backed tests remain conditionally skipped.
Added `test:immersion:sqlite:src`, `test:immersion:sqlite:dist`, and `test:immersion:sqlite` scripts; the source lane now prints explicit warnings when `node:sqlite` is unavailable, and the dist lane runs both SQLite-backed immersion suites under Node with `--experimental-sqlite`.
Wired the dist SQLite lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` after the bundle build, with explicit `actions/setup-node@v4` provisioning for Node 22.12.0.
Fixed SQL prepared-statement placeholder counts in `src/core/services/immersion-tracker/storage.ts`, which the new Node-backed SQLite lane surfaced immediately.
Verification: `bun run test:immersion:sqlite:src` -> pass with explicit unsupported-runtime warnings and 10 skips under Bun 1.3.5; `bun run test:immersion:sqlite` -> pass with 14/14 tests under Node 22.12.0 + `--experimental-sqlite`.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added an explicit SQLite-backed immersion verification lane and documented it so persistence-heavy coverage is no longer hidden behind Bun-only skips. `package.json` now exposes source and dist SQLite scripts, the source test files print actionable warnings when `node:sqlite` is unavailable, and `README.md` explains the dedicated contributor command plus its Node 22 `--experimental-sqlite` prerequisite.
Automated verification now includes the new dist lane in both `.github/workflows/ci.yml` and `.github/workflows/release.yml` after build output is available. While wiring the reproducible Node lane, it exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`; fixing those placeholders makes the SQLite-backed persistence/finalization tests pass cross-runtime, covering session finalization, telemetry persistence, and storage-session write paths.
<!-- SECTION:FINAL_SUMMARY:END -->

59
backlog/tasks/task-87.4 - Runtime-composition-root-remove-dead-symbols-and-tighten-module-boundaries-in-src-main.ts.md
View File

@@ -1,59 +0,0 @@
---
id: TASK-87.4
title: >-
Runtime composition root: remove dead symbols and tighten module boundaries in
src/main.ts
status: Done
assignee: []
created_date: '2026-03-06 03:19'
updated_date: '2026-03-16 05:13'
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
ordinal: 78500
---
## 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 -->
- [x] #1 src/main.ts no longer emits dead-symbol diagnostics under a noUnusedLocals/noUnusedParameters compile pass for the areas touched by this cleanup.
- [x] #2 Unused imports, destructured values, and stale locals identified in the current composition root are removed or relocated without behavior changes.
- [x] #3 The resulting composition root has clearer ownership boundaries for at least one runtime slice that is currently buried in the monolith.
- [x] #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 -->
## Completion Notes
- Removed the dead import/destructure backlog from `src/main.ts` and deleted stale wrapper seams that no longer owned runtime behavior after the composer/runtime extractions.
- Tightened module boundaries so the composition root depends on the composed/public runtime surfaces it actually uses instead of retaining unused lower-level domain factory symbols.
- Cleared the remaining strict `noUnusedLocals`/`noUnusedParameters` failures in nearby touched files required for a clean repo-wide pass: `launcher/commands/playback-command.ts`, `src/anki-integration.ts`, `src/anki-integration/field-grouping-workflow.ts`, `src/core/services/tokenizer/yomitan-parser-runtime.test.ts`, and `src/main/runtime/composers/composer-contracts.type-test.ts`.
- Verification:
- `bunx tsc --noEmit -p tsconfig.typecheck.json --noUnusedLocals --noUnusedParameters --pretty false`
- `bun run test:fast`
- Commit: `e659b5d` (`refactor(runtime): remove dead symbols from composition roots`)

62
backlog/tasks/task-87.5 - Dead-architecture-cleanup-delete-unused-registry-and-pipeline-modules-that-are-off-the-live-path.md
View File

@@ -1,62 +0,0 @@
---
id: TASK-87.5
title: >-
Dead architecture cleanup: delete unused registry and pipeline modules that
are off the live path
status: Done
assignee: []
created_date: '2026-03-06 03:20'
updated_date: '2026-03-16 05:13'
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
ordinal: 79500
---
## 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 -->
- [x] #1 Each candidate module identified in the review is either removed as dead code or justified and reconnected to a real supported execution path.
- [x] #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.
- [x] #3 The cleanup does not regress live tokenization or subtitle sync behavior and the relevant verification commands remain green.
- [x] #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 -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
- Traced imports from `src/main.ts`, `src/main/runtime/**`, `src/core/services/subsync-runner.ts`, and `src/core/services/tokenizer.ts`; confirmed the candidate registry/pipeline modules were isolated from the maintained runtime path.
- Deleted dead modules: `src/translators/index.ts`, `src/subsync/engines.ts`, `src/subtitle/pipeline.ts`, `src/subtitle/stages/{merge,normalize,tokenize}.ts`, `src/subtitle/stages/normalize.test.ts`, `src/tokenizers/index.ts`, and `src/token-mergers/index.ts`.
- Moved the useful zero-width separator normalization into the live tokenizer path in `src/core/services/tokenizer.ts` and added regression coverage plus a repository-level dead-architecture guard in `src/dead-architecture-cleanup.test.ts`.
- Verified with `bun test src/core/services/tokenizer.test.ts`, `bun test src/dead-architecture-cleanup.test.ts`, `bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts`, `bun run tsc`, and `bun run test:src`.
<!-- SECTION:NOTES:END -->

53
backlog/tasks/task-87.6 - Anki-integration-maintainability-continue-decomposing-the-oversized-orchestration-layer.md
View File

@@ -1,53 +0,0 @@
---
id: TASK-87.6
title: >-
Anki integration maintainability: continue decomposing the oversized
orchestration layer
status: Done
assignee: []
created_date: '2026-03-06 03:20'
updated_date: '2026-03-16 05:13'
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
ordinal: 83500
---
## 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 -->
- [x] #1 The responsibilities currently concentrated in src/anki-integration.ts are split into clearer modules or services with narrow ownership boundaries.
- [x] #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.
- [x] #3 Existing Anki integration behavior remains covered by automated verification, including note update, field grouping, and proxy-related flows that the refactor touches.
- [x] #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 -->

71
backlog/tasks/task-88 - Fix-second-instance-start-handling-when-overlay-runtime-is-already-initialized.md
View File

@@ -1,71 +0,0 @@
---
id: TASK-88
title: >-
Fix second-instance --start handling when overlay runtime is already
initialized
status: Done
assignee:
- codex
created_date: '2026-03-06 07:30'
updated_date: '2026-03-16 05:13'
labels: []
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.test.ts
priority: medium
ordinal: 94500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Restore the CLI command guard so a second-instance `--start` request does not reconnect or reinitialize overlay work when the overlay runtime is already active, while preserving other second-instance commands.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Second-instance `--start` logs that the app is already running when the overlay runtime is initialized.
- [x] #2 Second-instance `--start` does not reconnect the MPV client when the overlay runtime is already initialized.
- [x] #3 Second-instance commands that include non-start actions still execute those actions.
- [x] #4 Regression coverage documents the guarded second-instance behavior.
<!-- AC:END -->
## Implementation Plan
<!-- SECTION:PLAN:BEGIN -->
1. Reproduce the failing `handleCliCommand` second-instance `--start` regression in `src/core/services/cli-command.test.ts`.
2. Update `src/core/services/cli-command.ts` so second-instance `--start` is ignored when the overlay runtime is already initialized, while still allowing non-start actions in the same invocation.
3. Run focused CLI command tests, then rerun the core test target if practical, and record acceptance criteria/results.
<!-- SECTION:PLAN:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Reproduced the failing second-instance `--start` regression in `src/core/services/cli-command.test.ts` before editing.
Restored a guard in `src/core/services/cli-command.ts` that ignores second-instance `--start` when the overlay runtime is already initialized, but still allows other flags in the same invocation to run.
Verification: `bun test src/core/services/cli-command.test.ts`, `bun run test:core:src`, and `bun run test` all pass; the six immersion tracker tests remain skipped as before.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Restored the missing second-instance `--start` guard in `src/core/services/cli-command.ts`.
- Added an `ignoreSecondInstanceStart` check so `handleCliCommand` logs `Ignoring --start because SubMiner is already running.` when a second-instance `--start` arrives after the overlay runtime is already initialized.
- Updated start gating so pure duplicate `--start` requests no longer reconnect the MPV client, while combined commands such as `--start --toggle-visible-overlay` still execute their non-start behavior and can connect through those paths.
- Verified the regression with existing CLI command coverage and reran the broader test targets.
Tests run:
- `bun test src/core/services/cli-command.test.ts`
- `bun run test:core:src`
- `bun run test`
Notes:
- The six skipped immersion tracker tests are unchanged from the pre-fix baseline.
<!-- SECTION:FINAL_SUMMARY:END -->

58
backlog/tasks/task-89 - Replace-per-anime-Yomitan-imports-with-merged-usage-based-character-dictionary.md
View File

@@ -1,58 +0,0 @@
---
id: TASK-89
title: Replace per-anime Yomitan imports with merged usage-based character dictionary
status: Done
assignee:
- '@codex'
created_date: '2026-03-06 07:59'
updated_date: '2026-03-16 05:13'
labels:
- character-dictionary
- yomitan
- anilist
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/config/definitions/defaults-integrations.ts
priority: high
ordinal: 91500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Replace TTL-based per-anime character dictionary imports with a single merged Yomitan dictionary built from locally stored per-media metadata snapshots. Retain only most-recently-used anime up to configured maxLoaded, rebuild merged import when retained set membership/order changes, and avoid rebuilding on revisits that do not change the retained set.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Character dictionary retention becomes usage-based rather than TTL-based.
- [x] #2 Only one Yomitan character dictionary import is maintained and updated as a merged dictionary.
- [x] #3 Local storage keeps only metadata/snapshots needed to rebuild the merged dictionary; per-anime source zip cache is removed.
- [x] #4 Merged dictionary rebuild occurs when retained-set membership or order changes, not on unchanged revisits.
- [x] #5 Tests cover merged rebuild, MRU eviction, and no-op revisits.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
Replaced per-media auto-sync imports with one merged Yomitan dictionary. Added snapshot persistence in `src/main/character-dictionary-runtime.ts` so auto-sync stores normalized per-media term/image metadata locally under `character-dictionaries/snapshots/` and rebuilds `merged.zip` from the MRU retained media ids.
Updated `src/main/runtime/character-dictionary-auto-sync.ts` to keep only MRU `activeMediaIds` plus merged revision/title state, rebuild/import the merged dictionary only when retained-set membership/order changes or the merged import is missing/stale, and skip rebuild on unchanged revisits.
Kept manual `generateForCurrentMedia` support by generating a one-off per-media zip from the stored snapshot, but removed the old per-media zip cache path from auto-sync state.
Updated config/help text to describe usage-based merged retention and mark legacy TTL/eviction knobs as ignored.
<!-- SECTION:NOTES:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented MRU-based merged character dictionary sync. Auto-sync now stores per-media normalized snapshots locally, rebuilds a single merged Yomitan dictionary when the retained anime set/order changes, and keeps `maxLoaded` as the cap on most-recently-used anime included in that merged import. Unchanged revisits no longer rebuild/import the dictionary.
Validation: `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run tsc --noEmit`.
<!-- SECTION:FINAL_SUMMARY:END -->

39
backlog/tasks/task-90 - Expand-TypeScript-typecheck-coverage-beyond-src.md
View File

@@ -1,39 +0,0 @@
---
id: TASK-90
title: Expand TypeScript typecheck coverage beyond src
status: Done
assignee: []
created_date: '2026-03-06 08:18'
updated_date: '2026-03-16 05:13'
labels:
- tooling
- typescript
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/tsconfig.json
- /home/sudacode/projects/japanese/SubMiner/package.json
- /home/sudacode/projects/japanese/SubMiner/launcher
- /home/sudacode/projects/japanese/SubMiner/scripts
priority: medium
ordinal: 89500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Bring all repository TypeScript entrypoints outside src/ into the enforced typecheck gate so CI and local checks cover launcher/ and script files, then resolve any surfaced diagnostics.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 TypeScript typecheck covers repository TypeScript entrypoints outside src/ that should be maintained in this repo, including launcher/ and script files.
- [x] #2 The enforced typecheck command used by CI and local development passes with the expanded coverage.
- [x] #3 Any diagnostics surfaced by the expanded coverage are fixed without weakening existing strictness for src/.
- [x] #4 Relevant documentation or command wiring is updated if the typecheck entrypoint changes.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added a dedicated repo-wide typecheck config at tsconfig.typecheck.json and wired package.json/CI to use `bun run typecheck` for launcher and scripts coverage without changing the existing src build config. Fixed the strict-null/indexing diagnostics surfaced in launcher/_ and scripts/_, keeping src strictness intact. Verified with `bun run typecheck`, `bun run tsc --noEmit`, and `bun run test:launcher:src` (47 passing, plugin start gate OK).
<!-- SECTION:FINAL_SUMMARY:END -->

36
backlog/tasks/task-91 - Keep-unsupported-subtitle-characters-visible-while-excluding-them-from-token-hover.md
View File

@@ -1,36 +0,0 @@
---
id: TASK-91
title: >-
Keep unsupported subtitle characters visible while excluding them from token
hover
status: Done
assignee: []
created_date: '2026-03-06 08:29'
updated_date: '2026-03-16 05:13'
labels:
- bug
- tokenizer
- renderer
dependencies: []
priority: medium
ordinal: 88500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Tokenizer/rendering bug: symbols and other unsupported characters with no lookup result are removed from the rendered subtitle line after tokenization, causing the displayed line to diverge from the source subtitle text. Update rendering so unsupported spans remain visible as plain text but are not tokenized/hoverable, and add regression coverage.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Subtitle rendering preserves unsupported symbols and special characters from the original line.
- [x] #2 Unsupported symbols and special characters do not create interactive token hover targets.
- [x] #3 Regression tests cover a mixed line containing tokenizable text plus unsupported characters.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Updated tokenized subtitle rendering to preserve unsupported punctuation and symbol spans as plain text while keeping only matched tokens interactive. Added renderer and alignment regression coverage for mixed lines so hover offsets stay correct after non-tokenizable characters remain visible.
<!-- SECTION:FINAL_SUMMARY:END -->

35
backlog/tasks/task-92 - Fix-merged-Yomitan-headword-selection-for-katakana-subtitle-tokens.md
View File

@@ -1,35 +0,0 @@
---
id: TASK-92
title: Fix merged Yomitan headword selection for katakana subtitle tokens
status: Done
assignee: []
created_date: '2026-03-06 08:43'
updated_date: '2026-03-16 05:13'
labels:
- bug
- tokenizer
- yomitan
dependencies: []
priority: medium
ordinal: 87500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Tokenizer/parser-selection bug: when a scanning-parser line is merged from multiple segments, the merged token currently keeps the first segment headword even if a later segment provides the full dictionary-backed term. This truncates katakana names such as バニール to バニ in the lookup payload and prevents correct dictionary matching. Also align kana classification so the prolonged sound mark is treated as kana in tokenizer heuristics.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Merged scanning-parser tokens prefer a full cross-segment headword when one segment expands to the full term.
- [x] #2 Standalone later segment headwords do not override the primary token headword in normal content-word + auxiliary merges.
- [x] #3 Katakana prolonged sound mark is treated as kana in tokenizer heuristics.
- [x] #4 Regression tests cover the merged katakana headword case.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Adjusted merged scanning-parser headword selection so later segments only override the first headword when they provide an expanded cross-segment dictionary term, which fixes truncated katakana lookups like バニール -> バニ. Also updated kana classification to include the katakana prolonged sound mark and added regression coverage for both the expanded-headword case and the normal content-word-plus-auxiliary case.
<!-- SECTION:FINAL_SUMMARY:END -->

35
backlog/tasks/task-93 - Replace-subtitle-tokenizer-with-left-to-right-Yomitan-scanning-parser.md
View File

@@ -1,35 +0,0 @@
---
id: TASK-93
title: Replace subtitle tokenizer with left-to-right Yomitan scanning parser
status: Done
assignee: []
created_date: '2026-03-06 09:02'
updated_date: '2026-03-16 05:13'
labels:
- tokenizer
- yomitan
- refactor
dependencies: []
priority: high
ordinal: 85500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Replace the current parseText candidate-selection tokenizer with a GSM-style left-to-right Yomitan scanning tokenizer for all subtitles. Preserve downstream token contracts for rendering, JLPT/frequency/N+1 annotation, and MeCab enrichment while improving full-term matching for names and katakana compounds.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Subtitle tokenization uses a left-to-right Yomitan scanning strategy instead of parseText candidate selection.
- [x] #2 Token surfaces, readings, headwords, and offsets remain compatible with existing renderer and annotation stages.
- [x] #3 Known problematic name cases such as カズマ and バニール resolve to full-token dictionary matches when Yomitan can match them.
- [x] #4 Regression tests cover left-to-right exact-match scanning, unmatched text handling, and downstream tokenizeSubtitle integration.
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Replaced the live subtitle tokenization path with a left-to-right Yomitan `termsFind` scanner that greedily advances through the normalized subtitle text, preserving downstream `MergedToken` contracts for renderer, MeCab enrichment, JLPT, frequency, and N+1 annotation. Added runtime and integration coverage for exact-match scanning plus name cases like カズマ and kept compatibility fallback handling for older mocked parseText-style test payloads.
<!-- SECTION:FINAL_SUMMARY:END -->

41
backlog/tasks/task-94 - Add-kana-aliases-for-AniList-character-dictionary-entries.md
View File

@@ -1,41 +0,0 @@
---
id: TASK-94
title: Add kana aliases for AniList character dictionary entries
status: Done
assignee: []
created_date: '2026-03-06 09:20'
updated_date: '2026-03-16 05:13'
labels:
- dictionary
- tokenizer
- anilist
dependencies: []
references:
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
- >-
/home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.test.ts
priority: high
ordinal: 84500
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Generate katakana/hiragana-friendly aliases from AniList romanized character names so subtitle katakana names like カズマ match character dictionary entries even when AniList native name is kanji.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 AniList character dictionary generation adds kana aliases for romanized names when native name is not already kana-only
- [x] #2 Generated dictionary entries allow katakana subtitle names like カズマ to resolve against a kanji-native AniList character entry
- [x] #3 Regression tests cover alias generation and resulting term bank output
<!-- AC:END -->
## Final Summary
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Added katakana aliases synthesized from AniList romanized character names during character dictionary generation, so kanji-native entries such as 佐藤和真 / Satou Kazuma now also emit terms like カズマ and サトウカズマ with hiragana readings. Added regression coverage verifying generated term-bank output for the Konosuba case.
Verified with `bun test src/main/character-dictionary-runtime.test.ts` and `bun run tsc --noEmit`.
<!-- SECTION:FINAL_SUMMARY:END -->

Some files were not shown because too many files have changed in this diff Show More