Merge remote-tracking branch 'origin/main' into add-hachidori-backend

# Conflicts:
#	launcher/main.test.ts
#	src/cli/help.test.ts
#	src/core/services/__tests__/stats-server.test.ts
#	src/core/services/cli-command.test.ts
#	src/core/services/tokenizer/yomitan-parser-runtime.test.ts
#	src/main/overlay-runtime.test.ts
#	src/main/runtime/character-dictionary-auto-sync.test.ts
#	src/main/runtime/cli-command-context-deps.test.ts
#	src/main/runtime/cli-command-context-factory.test.ts
#	src/main/runtime/cli-command-context-main-deps.test.ts
#	src/main/runtime/composers/cli-startup-composer.test.ts
#	src/main/runtime/stats-server-runtime.test.ts
#	src/main/runtime/tray-main-actions.test.ts
#	src/main/runtime/tray-main-deps.test.ts
#	src/main/runtime/tray-runtime-handlers.test.ts
#	src/main/runtime/tray-runtime.test.ts
#	src/main/runtime/yomitan-anki-server-sync.test.ts
#	src/preload.ts
#	src/renderer/handlers/mouse.test.ts
#	src/renderer/yomitan-popup.test.ts

AGENTS.md

@@ -8,6 +8,7 @@ Start here, then leave this file.
 - Architecture map: [`docs/architecture/README.md`](./docs/architecture/README.md)
 - Workflow map: [`docs/workflow/README.md`](./docs/workflow/README.md)
 - Verification lanes: [`docs/workflow/verification.md`](./docs/workflow/verification.md)
+- Testing guidelines: [`docs/workflow/testing.md`](./docs/workflow/testing.md)
 - Knowledge-base rules: [`docs/knowledge-base/README.md`](./docs/knowledge-base/README.md)
 - Release guide: [`docs/RELEASING.md`](./docs/RELEASING.md)
 
@@ -47,7 +48,7 @@ Start here, then leave this file.
 - Build/release scripts (`scripts/**`): `bun run test:scripts`
 - Internal docs, `AGENTS.md`, or repo skills: `bun run test:docs:kb`
 - User-facing `docs-site/`: `bun run docs:test`, then `bun run docs:build`
-- macOS mpv window helper: `bun test scripts/get-mpv-window-macos.test.ts`
+- macOS mpv window helper (`scripts/get-mpv-window-macos.swift`): compile it on macOS with `bun run build`
 - Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`
 
 ## Docs Upkeep

CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## v0.20.1 (2026-10-03)
+
+### Added
+- **YouTube Browser Window**:
+  - Browse YouTube with your login kept across restarts. Open it with `subminer youtube`, `subminer yt`, or tray **Browse YouTube**.
+  - Clicking a video plays it in mpv. Middle-click, Shift/Ctrl-click, or the right-click menu adds it to mpv's playlist.
+  - Queued videos get the same Japanese subtitle setup, and the rest of the queue is kept on Windows.
+  - Closing the window quits a SubMiner started by `subminer youtube`.
+- **Whisper Subtitles for YouTube**:
+  - Set `youtube.subtitleSource` to `whisper` to transcribe YouTube videos with Whisper instead of using YouTube's captions.
+  - The video stays paused while Whisper transcribes, and the subtitle generation modal shows progress.
+  - The subtitle generation modal (`Ctrl+Shift+G`) now works on YouTube videos, including Windows stream playback.
+- **Scroll Wheel and Mouse Bindings**: `keybindings` now accepts scroll wheel keys, and the settings key editor can capture them. Mouse button and wheel bindings from mpv now work while the cursor is over the overlay, including on Hyprland.
+- **Run Commands from Session Help**: During playback, press `Enter` or double-click a row in session help to run that command.
+
+### Changed
+- **Release Assets**: Releases no longer include package-size reports.
+
+### Fixed
+- **Hyprland Overlay**: The overlay stays clickable after mpv goes fullscreen with `mpv.backend: x11`, and it no longer interrupts mpv while mpv enters fullscreen.
+- **mpv Key Bindings**: Bindings from mpv such as `9`/`0` for volume now work while the overlay has focus, even if the overlay loaded before mpv connected.
+- **Jellyfin**:
+  - The Japanese subtitle track is selected as soon as it downloads, without waiting for the other tracks.
+  - Japanese and English tracks are auto-selected on episodes whose embedded subtitles are images.
+  - Timing review previews and mined card audio use the audio track you are playing.
+- **Media Timing Review**: Trim handles are now thin lines on the clip edges, and original subtitle boundaries no longer cover the waveform. The preview cursor no longer stutters on macOS with Bluetooth headphones.
+- **YouTube Subtitles**: Japanese subtitles no longer fail with "HTTP 429" on videos where YouTube also lists a machine-translated Japanese track.
+- **Stats**:
+  - Mined cards are counted once in session and lifetime stats.
+  - Word and kanji dates and the new-words charts stay accurate after deleting sessions. Existing data is repaired in the background.
+  - Overview totals, charts, and the activity calendar refresh after deleting sessions.
+- **Yomitan Data Safety**: Electron is updated to 43.7.7. SubMiner now refuses to load your Yomitan data with an unsupported or downgraded runtime. Automatic character dictionary changes stop if Yomitan suddenly reports no dictionaries.
+- **AppImage in Sandboxes**: The AppImage now opens its window when launched in a sandbox such as `firejail --appimage`.
+- **Ctrl+C Crash**: SubMiner no longer crashes with "write EPIPE" when the terminal command that started it is stopped with Ctrl+C.
+
+### Docs
+- **Docs Site**: The docs site is shorter and easier to scan, with a key and default table for each config block. Outdated pages were corrected, and the MeCab install command for Arch Linux is fixed.
+- **Stats Docs**: The docs now cover the Overview refresh after deleting sessions and how discovery dates are kept after old sessions are pruned.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- **Release Notes**: Release notes and `CHANGELOG.md` are now generated as short items per feature or area.
+- **Dev Profile**: Development launches use a separate `SubMiner-dev` profile unless production-profile access is requested.
+- **Dependencies**: undici is updated to 7.29.1 to clear the security advisories that were blocking CI.
+- **Package Checks**: CI no longer compares package sizes. Package content checks still run.
+
+</details>
+
 ## v0.20.0 (2026-09-23)
 
 ### Added

bun.lock

@@ -467,7 +467,7 @@
 
     "hosted-git-info": ["hosted-git-info@4.1.0", "", { "dependencies": { "lru-cache": "^6.0.0" } }, "sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA=="],
 
-    "http-cache-semantics": ["http-cache-semantics@4.2.0", "", {}, "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ=="],
+    "http-cache-semantics": ["http-cache-semantics@4.3.0", "", {}, "sha512-M5t5LlJpS1UHMjvwRQVdFHvPISGeLAxNcrWuJkeGh0KxsqCHZ1O3NXZU/8x7cD0BDcGW8kapxMKTvwlqrNkHkA=="],
 
     "http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
 

changes/README.md

@@ -42,7 +42,7 @@ How fragments turn into a release:
 
 - At release time, `bun run changelog:build` (and `bun run changelog:prerelease-notes`) pipes every pending fragment through `claude -p` to merge related items, drop noise, and rewrite into a clean user-facing release body. Write fragments as raw, informative notes — don't worry about polished prose, deduping across PRs, or line-by-line phrasing. The polish step handles all of that.
 - The polish step treats pending fragments as the final release outcome, not prerelease history. If a feature is added and then renamed or fixed before the stable cut, ship the final feature bullet instead of separate prerelease-only breaking/fix entries.
-- `CHANGELOG.md`, GitHub release notes, and prerelease notes all use short top-level items with one nested bullet per distinct change, instead of packing a release's worth of detail into a single paragraph bullet. An item with only one thing to say stays inline on the top-level bullet. Release notes and prerelease notes additionally cover user benefit and any useful action note in their nested bullets.
+- `CHANGELOG.md`, GitHub release notes, and prerelease notes all use one item per feature or area, inline by default: `- **Name**: one or two short sentences.` Items with several separate changes may use a few short nested bullets instead of a run-on sentence. Items say what changed and how to reach it; implementation details, edge cases, and step-by-step usage belong in the docs, not the release body.
 - `internal` fragments stay in `CHANGELOG.md` (inside a collapsed `<details>` block) but are dropped from the GitHub release notes entirely.
 - The polished `CHANGELOG.md` and `release/release-notes.md` are committed and reviewed before tagging — edit the Markdown by hand if Claude misses something.
 

changes/appimage-sandboxed-launch.md

@@ -1,4 +0,0 @@
-type: fixed
-area: linux
-
-- Fixed the AppImage exiting without opening a window when launched inside a sandbox that mounts the image itself, such as `firejail --appimage` (used by the AppImage catalog test). The detached background app now runs straight from the sandbox's squashfs mount instead of trying to re-mount the AppImage over FUSE.

changes/closed-pipe-crash.md

@@ -1,4 +0,0 @@
-type: fixed
-area: app
-
-- SubMiner no longer crashes with "write EPIPE" when the terminal command that started it is stopped with Ctrl+C.

changes/docs-site-simplify.md

@@ -1,7 +0,0 @@
-type: docs
-area: docs
-
-- Rewrote the docs site to be shorter and easier to scan: pages lead with setup and use, reference material lives in compact tables, and internal detail was cut from user pages.
-- The configuration reference now has a short explanation and a key/default table for each config block.
-- Fixed docs that no longer matched current behavior.
-- Fixed the Arch Linux install command for MeCab, which is only in the AUR (`mecab-git`), and brought the README requirements and quick start in line with the installation guide.

changes/electron43-profile-storage-safety.md

@@ -1,6 +0,0 @@
-type: fixed
-area: dictionary
-
-- Upgraded the desktop runtime to Electron 43.7.7 and added profile guards that block unsupported runtimes and Electron major or minor downgrades before Yomitan storage is loaded. Patch downgrades within the same major and minor version are allowed.
-- Development launches now use a separate `SubMiner-dev` profile unless production-profile access is explicitly requested.
-- Automatic character-dictionary changes now stop when a previously non-empty Yomitan profile suddenly reports zero dictionaries.

changes/hyprland-fullscreen-refresh.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Keep the subtitle overlay mapped during fullscreen transitions on Hyprland, avoiding focus changes from repeated hide/show calls that can cancel mpv fullscreen entry. Preserve the hide/show refresh on Sway.

changes/hyprland-x11-fullscreen-overlay-input.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed the overlay (subtitles and sidebar) becoming unclickable after mpv goes fullscreen on Hyprland with `mpv.backend: x11`. The launcher no longer strips `HYPRLAND_INSTANCE_SIGNATURE` from the X11 environment, so the overlay can lift Hyprland's fullscreen input block again.

changes/jellyfin-fast-subtitle-selection.md

@@ -1,5 +0,0 @@
-type: fixed
-area: jellyfin
-
-- Jellyfin playback now selects the Japanese subtitle track, and starts subtitle annotations, as soon as that track downloads instead of waiting for every other subtitle track. Tracks now download in parallel, so a slow embedded track Jellyfin has to extract no longer delays the primary subtitles.
-- Jellyfin episodes with image-based embedded subtitles (PGS, DVD, DVB) now auto-select the Japanese and English tracks. SubMiner no longer requests those tracks as text, and a subtitle track that fails to download no longer cancels selection of the others.

changes/jellyfin-review-audio-track.md

@@ -1,4 +0,0 @@
-type: fixed
-area: jellyfin
-
-- Timing review previews and mined card audio now use the audio track you are playing on Jellyfin direct-play streams, instead of the track Jellyfin marks as default.

changes/mpv-key-forwarding-late-connect.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed mpv key bindings (input.conf and mpv defaults, e.g. `9`/`0` volume) doing nothing while the overlay had focus when the overlay loaded before SubMiner connected to mpv, common in `mpv.backend: x11` mode. The overlay now reloads mpv's bindings once mpv connects.

changes/overlay-scroll-wheel-bindings.md

@@ -1,5 +0,0 @@
-type: added
-area: overlay
-
-- Added scroll wheel keys (`WHEEL_UP`, `WHEEL_DOWN`, `WHEEL_LEFT`, `WHEEL_RIGHT`, with modifiers) to `keybindings`, including capture from the settings key editor.
-- Mouse button and scroll wheel bindings from mpv (`input.conf` and mpv defaults, e.g. double-click fullscreen, wheel volume, back/forward for playlist) now work while the cursor is over the overlay. On Hyprland, where the overlay always receives input, they previously did nothing. SubMiner bindings and the right-click pause still take priority.

changes/patched-electron-undici.md

@@ -1,4 +0,0 @@
-type: fixed
-area: dependencies
-
-- Updated Electron to 42.10.0 and undici to 7.29.1 to resolve the security advisories blocking CI.

changes/remove-package-size-reports.md

@@ -1,4 +0,0 @@
-type: changed
-area: release
-
-- Removed package-size JSON reports from future releases and their CI size comparisons. Package-content validation remains enabled.

changes/session-help-run-commands.md

@@ -1,4 +0,0 @@
-type: added
-area: overlay
-
-- Session help can run the highlighted command during playback: press `Enter` or double-click a row. Hovering a row with the mouse makes it the `Enter` target. Help opened from the tray with no video loaded stays read-only.

changes/setup-launcher-badge-label.md

@@ -0,0 +1,4 @@
+type: fixed
+area: setup
+
+- First-run setup now labels a missing command-line launcher "Not set up" instead of "Not installed", so the AppImage catalog test no longer reads the setup window as an error screen.

changes/timing-review-macos-cursor.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- On macOS with Bluetooth headphones such as AirPods, the timing review preview cursor now moves smoothly across the selection instead of stuttering and jumping to the end partway through. This affected Opus audio, including Jellyfin streams.

changes/timing-review-thin-handles.md

@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
-- Media timing review trim handles are now thin lines centered on the clip edge, so it's clear where the clip starts and ends and less of the waveform is covered.
-- Original subtitle boundaries use orange bars without text tags, leaving the waveform unobstructed.

changes/youtube-browser-window.md

@@ -1,7 +0,0 @@
-type: added
-area: youtube
-
-- Added a YouTube browser window (`subminer youtube`/`subminer yt`, or tray **Browse YouTube**) that keeps your YouTube login across restarts.
-- Clicking a video plays it in mpv instead of the page; middle-click, Shift/Ctrl-click, or the right-click menu queues it in mpv's playlist.
-- Queued YouTube videos get the same Japanese subtitle setup when mpv reaches them.
-- Closing the YouTube window quits a SubMiner started by `subminer youtube` (after mpv closes, if a video is still playing).

changes/youtube-translated-caption-429.md

@@ -1,4 +0,0 @@
-type: fixed
-area: youtube
-
-- YouTube Japanese subtitles no longer fail with "HTTP 429" on videos where YouTube also lists a machine-translated Japanese track; SubMiner now picks the real track and falls back to yt-dlp if a direct subtitle download is refused.

changes/youtube-whisper-subtitles.md

@@ -1,7 +0,0 @@
-type: added
-area: youtube
-
-- Added `youtube.subtitleSource`: set it to `whisper` to transcribe YouTube videos with Whisper instead of downloading YouTube's captions. The default stays `youtube`.
-- Whisper mode keeps the video paused while it transcribes, with progress in the subtitle generation modal; close the modal to keep watching, or cancel to continue without subtitles.
-- The subtitle generation modal (`Ctrl+Shift+G`) now also works on YouTube videos, whatever `youtube.subtitleSource` is set to.
-- Whisper mode downloads a small audio-only stream and deletes it once generation ends, or when you switch videos, close mpv, or quit.

docs-site/changelog.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## v0.20.1 (2026-10-03)
+
+**Added**
+- **YouTube Browser Window**:
+  - Browse YouTube with your login kept across restarts. Open it with `subminer youtube`, `subminer yt`, or tray **Browse YouTube**.
+  - Clicking a video plays it in mpv. Middle-click, Shift/Ctrl-click, or the right-click menu adds it to mpv's playlist.
+  - Queued videos get the same Japanese subtitle setup, and the rest of the queue is kept on Windows.
+  - Closing the window quits a SubMiner started by `subminer youtube`.
+- **Whisper Subtitles for YouTube**:
+  - Set `youtube.subtitleSource` to `whisper` to transcribe YouTube videos with Whisper instead of using YouTube's captions.
+  - The video stays paused while Whisper transcribes, and the subtitle generation modal shows progress.
+  - The subtitle generation modal (`Ctrl+Shift+G`) now works on YouTube videos, including Windows stream playback.
+- **Scroll Wheel and Mouse Bindings**: `keybindings` now accepts scroll wheel keys, and the settings key editor can capture them. Mouse button and wheel bindings from mpv now work while the cursor is over the overlay, including on Hyprland.
+- **Run Commands from Session Help**: During playback, press `Enter` or double-click a row in session help to run that command.
+
+**Changed**
+- **Release Assets**: Releases no longer include package-size reports.
+
+**Fixed**
+- **Hyprland Overlay**: The overlay stays clickable after mpv goes fullscreen with `mpv.backend: x11`, and it no longer interrupts mpv while mpv enters fullscreen.
+- **mpv Key Bindings**: Bindings from mpv such as `9`/`0` for volume now work while the overlay has focus, even if the overlay loaded before mpv connected.
+- **Jellyfin**:
+  - The Japanese subtitle track is selected as soon as it downloads, without waiting for the other tracks.
+  - Japanese and English tracks are auto-selected on episodes whose embedded subtitles are images.
+  - Timing review previews and mined card audio use the audio track you are playing.
+- **Media Timing Review**: Trim handles are now thin lines on the clip edges, and original subtitle boundaries no longer cover the waveform. The preview cursor no longer stutters on macOS with Bluetooth headphones.
+- **YouTube Subtitles**: Japanese subtitles no longer fail with "HTTP 429" on videos where YouTube also lists a machine-translated Japanese track.
+- **Stats**:
+  - Mined cards are counted once in session and lifetime stats.
+  - Word and kanji dates and the new-words charts stay accurate after deleting sessions. Existing data is repaired in the background.
+  - Overview totals, charts, and the activity calendar refresh after deleting sessions.
+- **Yomitan Data Safety**: Electron is updated to 43.7.7. SubMiner now refuses to load your Yomitan data with an unsupported or downgraded runtime. Automatic character dictionary changes stop if Yomitan suddenly reports no dictionaries.
+- **AppImage in Sandboxes**: The AppImage now opens its window when launched in a sandbox such as `firejail --appimage`.
+- **Ctrl+C Crash**: SubMiner no longer crashes with "write EPIPE" when the terminal command that started it is stopped with Ctrl+C.
+
+**Docs**
+- **Docs Site**: The docs site is shorter and easier to scan, with a key and default table for each config block. Outdated pages were corrected, and the MeCab install command for Arch Linux is fixed.
+- **Stats Docs**: The docs now cover the Overview refresh after deleting sessions and how discovery dates are kept after old sessions are pruned.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- **Release Notes**: Release notes and `CHANGELOG.md` are now generated as short items per feature or area.
+- **Dev Profile**: Development launches use a separate `SubMiner-dev` profile unless production-profile access is requested.
+- **Dependencies**: undici is updated to 7.29.1 to clear the security advisories that were blocking CI.
+- **Package Checks**: CI no longer compares package sizes. Package content checks still run.
+
+</details>
+
 ## v0.20.0 (2026-09-23)
 
 **Added**

docs-site/immersion-tracking.md

@@ -42,6 +42,8 @@ To share stats and watch history between machines, use [`subminer sync <host>`](
 
 Recent sessions, a streak calendar, watch-time history, and totals for completed episodes and shows.
 
+Deleting a session or session group refreshes the Overview totals, charts, calendar, and vocabulary summary automatically. If a refresh fails, Overview keeps the previous totals visible and offers **Retry**.
+
 ![Stats Overview](/screenshots/stats-overview.png)
 
 ### Library
@@ -124,4 +126,6 @@ Leave out `--lookback-days` to scan all history. Word and kanji counts are corre
 
 By default SubMiner keeps everything. To limit history, set `immersionTracking.retentionPreset` to `minimal`, `balanced`, or `deep-history`, or set the `immersionTracking.retention.*Days` values yourself (`0` keeps all). Lifetime totals and vocabulary counts are stored separately and stay exact when old sessions are pruned.
 
+Deleting retained sessions preserves earlier word and kanji discovery dates from pruned history. New occurrences record observation time so deletion can update their dates exactly. Older history used write time, so an earlier discovery date is preserved when its origin cannot be determined.
+
 See [Immersion tracking](/configuration#immersion-tracking) and [Stats dashboard](/configuration#stats-dashboard) in the config reference for every option and default.

docs/knowledge-base/catalog.md

@@ -21,6 +21,7 @@ Read when: finding internal docs or checking verification status
 | Planning guide | `docs/workflow/planning.md` | active | 2026-05-23 | lightweight vs execution plans |
 | Agent skills | `docs/workflow/agent-skills.md` | active | 2026-08-23 | repo-local workflow skill ownership |
 | Verification guide | `docs/workflow/verification.md` | active | 2026-08-13 | maintained verification lanes |
+| Testing guidelines | `docs/workflow/testing.md` | active | 2026-10-04 | test style and anti-patterns |
 | Release guide | `docs/RELEASING.md` | active | 2026-05-23 | release checklist |
 
 ## Update Rules

docs/workflow/README.md

@@ -13,6 +13,7 @@ This section is the internal workflow map for contributors and agents.
 
 - [Planning](./planning.md) - when to write a lightweight plan vs a full execution plan
 - [Verification](./verification.md) - maintained test/build lanes and handoff gate
+- [Testing](./testing.md) - what a good test looks like and what not to write
 - [Agent Skills](./agent-skills.md) - repo-local workflow skill ownership
 - [Release Guide](../RELEASING.md) - tagged release workflow
 

docs/workflow/testing.md

@@ -0,0 +1,49 @@
+<!-- read_when: writing, reviewing, or deleting tests -->
+
+# Testing Guidelines
+
+Status: active  
+Last verified: 2026-10-04  
+Owner: Kyle Yasuda  
+Read when: adding or changing tests
+
+Which lanes to run lives in [Verification](./verification.md). This page covers what a
+good test looks like here.
+
+## Test Behavior, Not Wiring
+
+- Exercise a module through its public interface and assert outcomes: return values,
+  resulting state, files written, rows in sqlite, messages sent to a fake process.
+- Prefer real collaborators that are cheap: tmp dirs, in-memory or tmp sqlite, fake
+  executables, pure parsers. Fake only the edges (Electron, mpv socket, network).
+- Assert call order only when order is the behavior (startup sequencing, ABA races),
+  and then assert relative order, not the whole call log.
+
+## Do Not Write
+
+- Pass-through tests: a builder or handler that only forwards deps (`*-main-deps.ts`,
+  `*-runtime-handlers.ts`) needs no test. TypeScript already checks the shape.
+- Source-text tests: reading `.ts`, `.css`, `.html`, `.lua`, `.swift`, or workflow YAML
+  and asserting with regexes. If the invariant matters, extract the logic and run it
+  (see `src/preload-ipc-listeners.ts`). Policy lints over workflow YAML are the
+  exception and belong in one parsed-YAML check.
+- "Stays deleted" tests for removed modules, flags, or selectors. `tsc` and review
+  catch reintroduction.
+- Tests that restate constants, defaults, labels, or window options.
+- The same rule at several layers. Test a rule once where it lives; keep one
+  end-to-end case (for the tokenizer, the golden corpus) for integration.
+
+## Keep Tests Small
+
+- Shared setup goes in a `makeDeps(overrides)` helper or a `*-test-harness.ts` file, not
+  pasted into every test.
+- Near-identical cases become a table: `for (const c of cases) test(c.name, ...)`.
+- Inject timers, clocks, and loggers instead of patching globals or private members.
+- A bug fix gets a regression test for the behavior that broke, named after the
+  behavior, not the ticket.
+
+## Known Debt
+
+- `src/main/main-wiring.test.ts` and `src/renderer/renderer-init-order.test.ts` still
+  regex `main.ts` / `renderer.ts` to guard startup ordering. Replace each test with a
+  behavioral one as the logic moves out of `main.ts` closures.

docs/workflow/verification.md

@@ -14,8 +14,9 @@ Read when: selecting the right verification lane for a change
   files in `package.json`.
 - `scripts/run-test-lane.mjs` runs each test file in its own `bun test` process
   (per-file isolation with a wall timeout) so a hanging test or leaked global in
-  one file cannot cascade into the rest of the lane. `--jobs N` parallelizes;
-  `--single-process` restores the shared-process mode for debugging.
+  one file cannot cascade into the rest of the lane. Files run in parallel, one
+  worker per CPU by default; `--jobs 1` runs serially and `--single-process`
+  restores the shared-process mode for debugging.
 - `bun run test:fast` is the full source gate: discovered `src/**`, launcher
   unit, and `scripts/**`.
 - `.github/workflows/quality-gate.yml` is the reusable `workflow_call` gate for
@@ -71,7 +72,7 @@ bun run docs:build
 
 - `bun run test:coverage:src` runs the same discovered `bun-src-full` membership as
   `test:src` through a sharded coverage runner: one Bun coverage process per test
-  file, then merged LCOV output.
+  file (parallel, one per CPU unless `--jobs N`), then merged LCOV output.
 - A failing coverage shard stops the runner with a nonzero status. Coverage is a
   source test gate, not a report-only step.
 - Machine-readable output lands at `coverage/test-src/lcov.info`.

launcher/commands/command-modules.test.ts

@@ -150,74 +150,7 @@ test('doctor command exits non-zero for missing hard dependencies', () => {
   );
 });
 
-test('doctor command forwards refresh-known-words to app binary', () => {
-  const context = createContext();
-  context.args.doctor = true;
-  context.args.doctorRefreshKnownWords = true;
-  const forwarded: string[][] = [];
-
-  const handled = runDoctorCommand(context, {
-    commandExists: () => false,
-    configExists: () => true,
-    resolveMainConfigPath: () => '/tmp/SubMiner/config.jsonc',
-    runAppCommandWithInherit: (_appPath, appArgs) => {
-      forwarded.push(appArgs);
-    },
-  });
-
-  assert.equal(handled, true);
-  assert.deepEqual(forwarded, [['--refresh-known-words']]);
-});
-
-test('logs command exports logs and writes archive path', () => {
-  const writes: string[] = [];
-  const context = createContext();
-  context.args.logsExport = true;
-  context.processAdapter = {
-    ...context.processAdapter,
-    writeStdout: (text) => writes.push(text),
-  };
-
-  const handled = runLogsCommand(context, {
-    exportLogsArchive: () => ({
-      zipPath: '/tmp/subminer-logs.zip',
-      exportedFiles: ['/tmp/app.log'],
-      mode: 'current-day',
-    }),
-  });
-
-  assert.equal(handled, true);
-  assert.deepEqual(writes, ['/tmp/subminer-logs.zip\n']);
-});
-
-test('logs command ignores unrelated launcher commands', () => {
-  const context = createContext();
-
-  assert.equal(runLogsCommand(context), false);
-});
-
-test('app command starts default macOS background app detached from launcher', () => {
-  const context = createContext();
-  context.args.appPassthrough = true;
-  context.args.appArgs = [];
-  const calls: string[] = [];
-
-  const handled = runAppPassthroughCommand(context, {
-    runAppCommandWithInherit: () => {
-      calls.push('attached');
-    },
-    launchSyncUiDetached: () => calls.push('sync-ui'),
-    launchYoutubeBrowserDetached: () => calls.push('youtube'),
-    launchAppBackgroundDetached: (appPath, logLevel) => {
-      calls.push(`detached:${appPath}:${logLevel}`);
-    },
-  });
-
-  assert.equal(handled, true);
-  assert.deepEqual(calls, ['detached:/tmp/subminer.app:warn']);
-});
-
-test('app command starts default Linux background app detached from launcher', () => {
+test('app command starts default background app detached from launcher app detached from launcher', () => {
   const context = createContext();
   context.args.appPassthrough = true;
   context.args.appArgs = [];
@@ -389,49 +322,6 @@ test('dictionary command forwards candidate and selection modes to app binary',
   ]);
 });
 
-test('dictionary command returns after app handoff starts', () => {
-  const context = createContext();
-  context.args.dictionary = true;
-
-  const handled = runDictionaryCommand(context, {
-    runAppCommandWithInherit: () => undefined,
-  });
-
-  assert.equal(handled, true);
-});
-
-test('update command runs direct Linux release update without launching Electron', async () => {
-  const context = createContext();
-  context.args.update = true;
-  const calls: string[] = [];
-
-  const handled = await runUpdateCommand(context, {
-    runAppCommandCaptureOutput: () => {
-      throw new Error('unexpected Electron launch');
-    },
-    runDirectReleaseUpdate: async (request) => {
-      calls.push(`direct:${request.appPath}:${request.launcherPath}:${request.channel}`);
-      return {
-        appImage: { status: 'not-found' },
-        launcher: { status: 'updated' },
-        supportAssets: [{ status: 'skipped' }],
-      };
-    },
-    readMainConfig: () => null,
-    log: (level, _configured, message) => {
-      calls.push(`${level}:${message}`);
-    },
-  });
-
-  assert.equal(handled, true);
-  assert.deepEqual(calls, [
-    'direct:/tmp/subminer.app:/tmp/subminer:stable',
-    'info:AppImage update: not-found',
-    'info:Launcher update: updated',
-    'info:Support assets update: skipped',
-  ]);
-});
-
 test('stats command launches attached app command with response path', async () => {
   const harness = createStatsTestHarness({ stats: true, logLevel: 'debug' });
   const handled = await runStatsCommand(harness.context, harness.commandDeps);
@@ -449,16 +339,41 @@ test('stats command launches attached app command with response path', async ()
   assert.equal(harness.removedPaths.length, 1);
 });
 
-test('stats background command launches attached daemon control command with response path', async () => {
-  const harness = createStatsTestHarness({ stats: true, statsBackground: true });
+const STATS_RESPONSE_ARGS = ['--stats-response-path', '/tmp/subminer-stats-test/response.json'];
+
+const statsForwardingCases = [
+  {
+    name: 'stats background command launches the daemon start command',
+    overrides: { statsBackground: true },
+    expected: ['--stats-daemon-start', ...STATS_RESPONSE_ARGS],
+  },
+  {
+    name: 'stats stop command forwards the daemon stop flag',
+    overrides: { statsStop: true },
+    expected: ['--stats-daemon-stop', ...STATS_RESPONSE_ARGS],
+  },
+  {
+    name: 'stats cleanup command forwards cleanup vocab flags',
+    overrides: { statsCleanup: true, statsCleanupVocab: true },
+    expected: ['--stats', ...STATS_RESPONSE_ARGS, '--stats-cleanup', '--stats-cleanup-vocab'],
+  },
+  {
+    name: 'stats cleanup command forwards the lifetime rebuild flag',
+    overrides: { statsCleanup: true, statsCleanupLifetime: true },
+    expected: ['--stats', ...STATS_RESPONSE_ARGS, '--stats-cleanup', '--stats-cleanup-lifetime'],
+  },
+];
+
+for (const c of statsForwardingCases) {
+  test(`${c.name} to the app`, async () => {
+    const harness = createStatsTestHarness({ stats: true, ...c.overrides });
     const handled = await runStatsCommand(harness.context, harness.commandDeps);
 
     assert.equal(handled, true);
-  assert.deepEqual(harness.forwarded, [
-    ['--stats-daemon-start', '--stats-response-path', '/tmp/subminer-stats-test/response.json'],
-  ]);
+    assert.deepEqual(harness.forwarded, [c.expected]);
     assert.equal(harness.removedPaths.length, 1);
   });
+}
 
 test('stats command waits for attached app exit after startup response', async () => {
   const harness = createStatsTestHarness({ stats: true });
@@ -503,45 +418,6 @@ test('stats command throws when attached app exits non-zero after startup respon
   assert.equal(harness.removedPaths.length, 1);
 });
 
-test('stats cleanup command forwards cleanup vocab flags to the app', async () => {
-  const harness = createStatsTestHarness({
-    stats: true,
-    statsCleanup: true,
-    statsCleanupVocab: true,
-  });
-  const handled = await runStatsCommand(harness.context, {
-    ...harness.commandDeps,
-    waitForStatsResponse: async () => ({ ok: true }),
-  });
-
-  assert.equal(handled, true);
-  assert.deepEqual(harness.forwarded, [
-    [
-      '--stats',
-      '--stats-response-path',
-      '/tmp/subminer-stats-test/response.json',
-      '--stats-cleanup',
-      '--stats-cleanup-vocab',
-    ],
-  ]);
-  assert.equal(harness.removedPaths.length, 1);
-});
-
-test('stats stop command forwards stop flag to the app', async () => {
-  const harness = createStatsTestHarness({ stats: true, statsStop: true });
-
-  const handled = await runStatsCommand(harness.context, {
-    ...harness.commandDeps,
-    waitForStatsResponse: async () => ({ ok: true }),
-  });
-
-  assert.equal(handled, true);
-  assert.deepEqual(harness.forwarded, [
-    ['--stats-daemon-stop', '--stats-response-path', '/tmp/subminer-stats-test/response.json'],
-  ]);
-  assert.equal(harness.removedPaths.length, 1);
-});
-
 test('stats stop command exits on process exit without waiting for startup response', async () => {
   const harness = createStatsTestHarness({ stats: true, statsStop: true });
   let waitedForResponse = false;
@@ -563,30 +439,6 @@ test('stats stop command exits on process exit without waiting for startup respo
   assert.equal(harness.removedPaths.length, 1);
 });
 
-test('stats cleanup command forwards lifetime rebuild flag to the app', async () => {
-  const harness = createStatsTestHarness({
-    stats: true,
-    statsCleanup: true,
-    statsCleanupLifetime: true,
-  });
-  const handled = await runStatsCommand(harness.context, {
-    ...harness.commandDeps,
-    waitForStatsResponse: async () => ({ ok: true }),
-  });
-
-  assert.equal(handled, true);
-  assert.deepEqual(harness.forwarded, [
-    [
-      '--stats',
-      '--stats-response-path',
-      '/tmp/subminer-stats-test/response.json',
-      '--stats-cleanup',
-      '--stats-cleanup-lifetime',
-    ],
-  ]);
-  assert.equal(harness.removedPaths.length, 1);
-});
-
 test('stats command throws when stats response reports an error', async () => {
   const harness = createStatsTestHarness({ stats: true });
 
@@ -692,36 +544,3 @@ test('stats command aborts pending response wait when attached app fails to spaw
   assert.equal(aborted, true);
   assert.equal(harness.removedPaths.length, 1);
 });
-
-test('stats cleanup command aborts pending response wait when app exits before startup response', async () => {
-  const harness = createStatsTestHarness({
-    stats: true,
-    statsCleanup: true,
-    statsCleanupVocab: true,
-  });
-  let aborted = false;
-
-  await assert.rejects(async () => {
-    await runStatsCommand(harness.context, {
-      ...harness.commandDeps,
-      runAppCommandAttached: async (...args) => {
-        await harness.runAppCommandAttachedStub(...args);
-        return 2;
-      },
-      waitForStatsResponse: async (_responsePath, signal) =>
-        await new Promise((resolve) => {
-          signal?.addEventListener(
-            'abort',
-            () => {
-              aborted = true;
-              resolve({ ok: false, error: 'aborted' });
-            },
-            { once: true },
-          );
-        }),
-    });
-  }, /Stats app exited before startup response \(status 2\)\./);
-
-  assert.equal(aborted, true);
-  assert.equal(harness.removedPaths.length, 1);
-});

launcher/commands/playback-command.test.ts

@@ -4,72 +4,22 @@ import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import type { Args } from '../types.js';
 import type { LauncherCommandContext } from './context.js';
 import { registerCleanup, runPlaybackCommandWithDeps } from './playback-command.js';
-import { state } from '../mpv.js';
+import { state, type startMpv } from '../mpv.js';
+import { makeLauncherArgs } from '../test-support/args.js';
+import { withEnv } from '../test-support/env.js';
 
-function createContext(): LauncherCommandContext {
+type PlaybackDeps = Parameters<typeof runPlaybackCommandWithDeps>[1];
+type StartMpvOptions = NonNullable<Parameters<typeof startMpv>[6]>;
+
+const YOUTUBE_URL = 'https://www.youtube.com/watch?v=65Ovd7t8sNw';
+
+function makePluginConfig(
+  overrides: Partial<LauncherCommandContext['pluginRuntimeConfig']> = {},
+): LauncherCommandContext['pluginRuntimeConfig'] {
   return {
-    args: {
-      backend: 'auto',
-      directory: '.',
-      recursive: false,
-      profile: '',
-      startOverlay: false,
-      youtubePrimarySubLangs: [],
-      youtubeSecondarySubLangs: [],
-      youtubeAudioLangs: [],
-      useTexthooker: false,
-      autoStartOverlay: false,
-      texthookerOnly: false,
-      texthookerOpenBrowser: false,
-      useRofi: false,
-      history: false,
-      sync: false,
-      syncCliTokens: [],
-      syncUi: false,
-      logLevel: 'info',
-      logRotation: 7,
-      passwordStore: '',
-      target: 'https://www.youtube.com/watch?v=65Ovd7t8sNw',
-      targetKind: 'url',
-      jimakuApiKey: '',
-      jimakuApiKeyCommand: '',
-      jimakuApiBaseUrl: '',
-      jimakuLanguagePreference: 'ja',
-      jimakuMaxEntryResults: 20,
-      jellyfin: false,
-      jellyfinLogin: false,
-      jellyfinLogout: false,
-      jellyfinPlay: false,
-      jellyfinDiscovery: false,
-      dictionary: false,
-      dictionaryCandidates: false,
-      dictionarySelect: false,
-      stats: false,
-      doctor: false,
-      doctorRefreshKnownWords: false,
-      logsExport: false,
-      version: false,
-      settings: false,
-      youtubeBrowser: false,
-      configPath: false,
-      configShow: false,
-      mpvIdle: false,
-      mpvSocket: false,
-      mpvStatus: false,
-      mpvArgs: '',
-      appPassthrough: false,
-      appArgs: [],
-      jellyfinServer: '',
-      jellyfinUsername: '',
-      jellyfinPassword: '',
-      launchMode: 'normal',
-    },
-    scriptPath: '/tmp/subminer',
-    scriptName: 'subminer',
-    mpvSocketPath: '/tmp/subminer.sock',
-    pluginRuntimeConfig: {
     socketPath: '/tmp/subminer.sock',
     binaryPath: '',
     backend: 'auto',
@@ -78,7 +28,29 @@ function createContext(): LauncherCommandContext {
     autoStartPauseUntilReady: true,
     osdMessages: false,
     texthookerEnabled: false,
-    },
+    ...overrides,
+  };
+}
+
+/** A context for a YouTube URL target with logging at info and CLI texthooker off. */
+function createContext(
+  options: {
+    args?: Partial<Args>;
+    plugin?: Partial<LauncherCommandContext['pluginRuntimeConfig']>;
+  } = {},
+): LauncherCommandContext {
+  return {
+    args: makeLauncherArgs({
+      target: YOUTUBE_URL,
+      targetKind: 'url',
+      logLevel: 'info',
+      useTexthooker: false,
+      ...options.args,
+    }),
+    scriptPath: '/tmp/subminer',
+    scriptName: 'subminer',
+    mpvSocketPath: '/tmp/subminer.sock',
+    pluginRuntimeConfig: makePluginConfig(options.plugin),
     appPath: '/tmp/SubMiner.AppImage',
     launcherJellyfinConfig: {},
     processAdapter: {
@@ -93,8 +65,70 @@ function createContext(): LauncherCommandContext {
   };
 }
 
+const FILE_TARGET = { target: '/tmp/movie.mkv', targetKind: 'file' } as const;
+
+/**
+ * Playback harness. Deps are inert by default and record what the tests assert on: the
+ * options mpv was started with, the overlay launches, and an `events` log for the few cases
+ * where relative order is the behavior.
+ */
+function makeHarness(
+  options: {
+    context?: LauncherCommandContext;
+    deps?: Partial<PlaybackDeps>;
+    events?: string[];
+  } = {},
+) {
+  const context = options.context ?? createContext();
+  const events = options.events ?? [];
+  const startMpvOptions: StartMpvOptions[] = [];
+  const overlayCalls: Array<{ extraAppArgs: string[]; configDir?: string }> = [];
+  const deps: PlaybackDeps = {
+    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {
+      events.push('plugin');
+    },
+    chooseTarget: async () => ({
+      target: context.args.target,
+      kind: context.args.targetKind === 'file' ? 'file' : 'url',
+    }),
+    checkDependencies: () => {},
+    registerCleanup: () => {},
+    startMpv: async (_target, _kind, _args, _socket, _appPath, _subtitles, startOptions) => {
+      events.push('startMpv');
+      if (startOptions) startMpvOptions.push(startOptions);
+    },
+    waitForUnixSocketReady: async () => true,
+    startOverlay: async (_appPath, _args, _socket, extraAppArgs = [], configDir) => {
+      events.push('startOverlay');
+      overlayCalls.push({ extraAppArgs, configDir });
+    },
+    launchAppCommandDetached: () => {},
+    log: () => {},
+    cleanupPlaybackSession: async () => {},
+    getMpvProc: () => null,
+    ...options.deps,
+  };
+  return {
+    context,
+    events,
+    startMpvOptions,
+    overlayCalls,
+    run: () => runPlaybackCommandWithDeps(context, deps),
+  };
+}
+
+function assertRanInOrder(events: string[], ...expected: string[]): void {
+  const positions = expected.map((event) => events.indexOf(event));
+  assert.ok(
+    positions.every(
+      (position, index) => position >= 0 && (index === 0 || position > positions[index - 1]!),
+    ),
+    `expected ${expected.join(' -> ')} in order, got ${events.join(', ')}`,
+  );
+}
+
 test('playback cleanup signal handlers are registered once across repeated sessions', () => {
-  assert.equal(typeof registerCleanup, 'function', 'cleanup registration is not exported');
   const context = createContext();
   const registeredSignals: NodeJS.Signals[] = [];
   context.processAdapter.onSignal = (signal) => {
@@ -108,121 +142,41 @@ test('playback cleanup signal handlers are registered once across repeated sessi
 });
 
 test('youtube playback launches overlay with app-owned youtube flow args', async () => {
-  const calls: string[] = [];
-  const context = createContext();
-  context.pluginRuntimeConfig = {
-    ...context.pluginRuntimeConfig,
+  const harness = makeHarness({
+    context: createContext({
+      plugin: {
         autoStart: false,
         autoStartVisibleOverlay: false,
         autoStartPauseUntilReady: false,
-  };
-  const receivedStartMpvOptions: Record<string, unknown>[] = [];
-
-  await runPlaybackCommandWithDeps(context, {
-    ensurePlaybackSetupReady: async () => {},
-    ensureRuntimePluginReady: async () => {},
-    chooseTarget: async (_args, _scriptPath) => ({ target: context.args.target, kind: 'url' }),
-    checkDependencies: () => {},
-    registerCleanup: () => {},
-    startMpv: async (
-      _target,
-      _targetKind,
-      _args,
-      _socketPath,
-      _appPath,
-      _preloadedSubtitles,
-      options,
-    ) => {
-      if (options) {
-        receivedStartMpvOptions.push(options as Record<string, unknown>);
-      }
-      calls.push('startMpv');
       },
-    waitForUnixSocketReady: async () => true,
-    startOverlay: async (_appPath, _args, _socketPath, extraAppArgs = []) => {
-      calls.push(`startOverlay:${extraAppArgs.join(' ')}`);
-    },
-    launchAppCommandDetached: (_appPath: string, appArgs: string[]) => {
-      calls.push(`launch:${appArgs.join(' ')}`);
-    },
-    log: () => {},
-    cleanupPlaybackSession: async () => {},
-    getMpvProc: () => null,
+    }),
   });
 
-  assert.deepEqual(calls, [
-    'startMpv',
-    'startOverlay:--youtube-play https://www.youtube.com/watch?v=65Ovd7t8sNw',
-  ]);
-  assert.equal(receivedStartMpvOptions[0]?.startPaused, true);
-  assert.equal(receivedStartMpvOptions[0]?.disableYoutubeSubtitleAutoLoad, true);
+  await harness.run();
+
+  assertRanInOrder(harness.events, 'startMpv', 'startOverlay');
+  assert.deepEqual(harness.overlayCalls[0]?.extraAppArgs, ['--youtube-play', YOUTUBE_URL]);
+  assert.equal(harness.startMpvOptions[0]?.startPaused, true);
+  assert.equal(harness.startMpvOptions[0]?.disableYoutubeSubtitleAutoLoad, true);
 });
 
 test('youtube app-owned playback disables mpv plugin auto-start', async () => {
-  const context = createContext();
-  context.pluginRuntimeConfig = {
-    ...context.pluginRuntimeConfig,
-    autoStart: true,
-    autoStartVisibleOverlay: true,
-    autoStartPauseUntilReady: true,
-  };
-  const receivedStartMpvOptions: Record<string, unknown>[] = [];
+  const harness = makeHarness();
 
-  await runPlaybackCommandWithDeps(context, {
-    ensurePlaybackSetupReady: async () => {},
-    ensureRuntimePluginReady: async () => {},
-    chooseTarget: async () => ({ target: context.args.target, kind: 'url' }),
-    checkDependencies: () => {},
-    registerCleanup: () => {},
-    startMpv: async (
-      _target,
-      _targetKind,
-      _args,
-      _socketPath,
-      _appPath,
-      _preloadedSubtitles,
-      options,
-    ) => {
-      if (options) {
-        receivedStartMpvOptions.push(options as Record<string, unknown>);
-      }
-    },
-    waitForUnixSocketReady: async () => true,
-    startOverlay: async () => {},
-    launchAppCommandDetached: () => {},
-    log: () => {},
-    cleanupPlaybackSession: async () => {},
-    getMpvProc: () => null,
-  });
+  await harness.run();
 
-  const runtimeConfig = receivedStartMpvOptions[0]?.runtimePluginConfig as
-    | { autoStart?: boolean; autoStartVisibleOverlay?: boolean; autoStartPauseUntilReady?: boolean }
-    | undefined;
+  const runtimeConfig = harness.startMpvOptions[0]?.runtimePluginConfig;
   assert.equal(runtimeConfig?.autoStart, false);
   assert.equal(runtimeConfig?.autoStartVisibleOverlay, false);
   assert.equal(runtimeConfig?.autoStartPauseUntilReady, false);
 });
 
 test('plugin auto-start playback leaves app lifetime to managed-playback owner', async () => {
-  const context = createContext();
-  context.args = {
-    ...context.args,
-    target: '/tmp/movie.mkv',
-    targetKind: 'file',
-    useTexthooker: true,
-  };
-  context.pluginRuntimeConfig = {
-    socketPath: '/tmp/subminer.sock',
-    binaryPath: '',
-    backend: 'auto',
-    autoStart: true,
-    autoStartVisibleOverlay: false,
-    autoStartPauseUntilReady: false,
-    osdMessages: false,
-    texthookerEnabled: false,
-  };
-  const appPath = context.appPath ?? '';
-  state.appPath = appPath;
+  const context = createContext({
+    args: { ...FILE_TARGET, useTexthooker: true },
+    plugin: { autoStartVisibleOverlay: false, autoStartPauseUntilReady: false },
+  });
+  state.appPath = context.appPath ?? '';
   state.overlayManagedByLauncher = false;
   const mpvProc = new EventEmitter() as EventEmitter & {
     exitCode: number | null;
@@ -233,32 +187,28 @@ test('plugin auto-start playback leaves app lifetime to managed-playback owner',
   mpvProc.killed = false;
   mpvProc.kill = () => true;
   let cleanupSawManagedOverlay = true;
-
-  try {
-    await runPlaybackCommandWithDeps(context, {
-      ensurePlaybackSetupReady: async () => {},
-      ensureRuntimePluginReady: async () => {},
-      chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
-      checkDependencies: () => {},
-      registerCleanup: () => {},
+  const harness = makeHarness({
+    context,
+    deps: {
       startMpv: async () => {
         setTimeout(() => {
           mpvProc.exitCode = 0;
           mpvProc.emit('exit', 0);
         }, 5);
       },
-      waitForUnixSocketReady: async () => true,
       startOverlay: async () => {
         throw new Error('startOverlay should not run when plugin auto-start is used');
       },
-      launchAppCommandDetached: () => {},
-      log: () => {},
       cleanupPlaybackSession: async () => {
         cleanupSawManagedOverlay = state.overlayManagedByLauncher;
       },
       getMpvProc: () => mpvProc as NonNullable<typeof state.mpvProc>,
+    },
   });
 
+  try {
+    await harness.run();
+
     assert.equal(cleanupSawManagedOverlay, false);
   } finally {
     state.appPath = '';
@@ -267,258 +217,89 @@ test('plugin auto-start playback leaves app lifetime to managed-playback owner',
 });
 
 test('plugin auto-start playback attaches a warm background app through the launcher', async () => {
-  const context = createContext();
-  context.args = {
-    ...context.args,
-    target: '/tmp/movie.mkv',
-    targetKind: 'file',
-    useTexthooker: true,
-  };
-  context.pluginRuntimeConfig = {
-    socketPath: '/tmp/subminer.sock',
-    binaryPath: '',
-    backend: 'auto',
-    autoStart: true,
-    autoStartVisibleOverlay: true,
-    autoStartPauseUntilReady: true,
-    osdMessages: false,
-    texthookerEnabled: true,
-  };
-  const calls: string[] = [];
-  const receivedStartMpvOptions: Record<string, unknown>[] = [];
-
-  await runPlaybackCommandWithDeps(context, {
-    ensurePlaybackSetupReady: async () => {},
-    ensureRuntimePluginReady: async () => {},
-    chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
-    checkDependencies: () => {},
-    registerCleanup: () => {},
-    startMpv: async (
-      _target,
-      _targetKind,
-      _args,
-      _socketPath,
-      _appPath,
-      _preloadedSubtitles,
-      options,
-    ) => {
-      calls.push('startMpv');
-      if (options) {
-        receivedStartMpvOptions.push(options as Record<string, unknown>);
-      }
-    },
-    waitForUnixSocketReady: async () => true,
-    startOverlay: async (_appPath, _args, _socketPath, extraAppArgs = []) => {
-      calls.push(`startOverlay:${extraAppArgs.join(' ')}`);
-    },
-    launchAppCommandDetached: () => {},
-    log: () => {},
-    cleanupPlaybackSession: async () => {},
-    getMpvProc: () => null,
-    isAppControlServerAvailable: async () => true,
-  } as Parameters<typeof runPlaybackCommandWithDeps>[1] & {
-    isAppControlServerAvailable: () => Promise<boolean>;
+  const harness = makeHarness({
+    context: createContext({
+      args: { ...FILE_TARGET, useTexthooker: true },
+      plugin: { texthookerEnabled: true },
+    }),
+    deps: { isAppControlServerAvailable: async () => true },
   });
 
-  assert.deepEqual(calls, ['startMpv', 'startOverlay:--show-visible-overlay --texthooker']);
-  assert.equal(receivedStartMpvOptions[0]?.startPaused, true);
-  assert.equal(
-    (receivedStartMpvOptions[0]?.runtimePluginConfig as { autoStart?: boolean } | undefined)
-      ?.autoStart,
-    false,
-  );
+  await harness.run();
+
+  assertRanInOrder(harness.events, 'startMpv', 'startOverlay');
+  assert.deepEqual(harness.overlayCalls[0]?.extraAppArgs, [
+    '--show-visible-overlay',
+    '--texthooker',
+  ]);
+  assert.equal(harness.startMpvOptions[0]?.startPaused, true);
+  assert.equal(harness.startMpvOptions[0]?.runtimePluginConfig?.autoStart, false);
 });
 
 test('plugin auto-start attach mode reuses launcher-resolved config dir for app control', async () => {
-  const context = createContext();
-  const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
-  const originalAppData = process.env.APPDATA;
   const xdgConfigHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-test-xdg-'));
   const expectedConfigDir = path.join(xdgConfigHome, 'SubMiner');
   fs.mkdirSync(expectedConfigDir, { recursive: true });
   fs.writeFileSync(path.join(expectedConfigDir, 'config.jsonc'), '{}');
-  context.args = {
-    ...context.args,
-    target: '/tmp/movie.mkv',
-    targetKind: 'file',
-    useTexthooker: true,
-  };
-  context.pluginRuntimeConfig = {
-    socketPath: '/tmp/subminer.sock',
-    binaryPath: '',
-    backend: 'auto',
-    autoStart: true,
-    autoStartVisibleOverlay: true,
-    autoStartPauseUntilReady: true,
-    osdMessages: false,
-    texthookerEnabled: true,
-  };
   let availabilityConfigDir: string | undefined;
-  let overlayConfigDir: string | undefined;
-  let overlayLoadingOsd: boolean | undefined;
-
-  try {
-    process.env.XDG_CONFIG_HOME = xdgConfigHome;
-    process.env.APPDATA = xdgConfigHome;
-
-    await runPlaybackCommandWithDeps(context, {
-      ensurePlaybackSetupReady: async () => {},
-      ensureRuntimePluginReady: async () => {},
-      chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
-      checkDependencies: () => {},
-      registerCleanup: () => {},
-      startMpv: async (
-        _target,
-        _targetKind,
-        _args,
-        _socketPath,
-        _appPath,
-        _preloadedSubtitles,
-        options,
-      ) => {
-        overlayLoadingOsd = (
-          options?.runtimePluginConfig as { overlayLoadingOsd?: boolean } | undefined
-        )?.overlayLoadingOsd;
-      },
-      waitForUnixSocketReady: async () => true,
-      startOverlay: async (_appPath, _args, _socketPath, _extraAppArgs = [], configDir) => {
-        overlayConfigDir = configDir;
-      },
-      launchAppCommandDetached: () => {},
-      log: () => {},
-      cleanupPlaybackSession: async () => {},
-      getMpvProc: () => null,
+  const harness = makeHarness({
+    context: createContext({
+      args: { ...FILE_TARGET, useTexthooker: true },
+      plugin: { texthookerEnabled: true },
+    }),
+    deps: {
       isAppControlServerAvailable: async (_logLevel, configDir) => {
         availabilityConfigDir = configDir;
         return true;
       },
+    },
   });
 
+  try {
+    await withEnv({ XDG_CONFIG_HOME: xdgConfigHome, APPDATA: xdgConfigHome }, () => harness.run());
+
     assert.equal(availabilityConfigDir, expectedConfigDir);
-    assert.equal(overlayConfigDir, expectedConfigDir);
-    assert.equal(overlayLoadingOsd, true);
+    assert.equal(harness.overlayCalls[0]?.configDir, expectedConfigDir);
+    assert.equal(harness.startMpvOptions[0]?.runtimePluginConfig?.overlayLoadingOsd, true);
   } finally {
-    if (originalXdgConfigHome === undefined) {
-      delete process.env.XDG_CONFIG_HOME;
-    } else {
-      process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
-    }
-    if (originalAppData === undefined) {
-      delete process.env.APPDATA;
-    } else {
-      process.env.APPDATA = originalAppData;
-    }
     fs.rmSync(xdgConfigHome, { recursive: true, force: true });
   }
 });
 
 test('plugin auto-start attach mode omits texthooker flag when CLI texthooker is disabled', async () => {
-  const context = createContext();
-  context.args = {
-    ...context.args,
-    target: '/tmp/movie.mkv',
-    targetKind: 'file',
-  };
-  context.pluginRuntimeConfig = {
-    socketPath: '/tmp/subminer.sock',
-    binaryPath: '',
-    backend: 'auto',
-    autoStart: true,
-    autoStartVisibleOverlay: true,
-    autoStartPauseUntilReady: true,
-    osdMessages: false,
-    texthookerEnabled: true,
-  };
-  const calls: string[] = [];
-
-  await runPlaybackCommandWithDeps(context, {
-    ensurePlaybackSetupReady: async () => {},
-    ensureRuntimePluginReady: async () => {},
-    chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
-    checkDependencies: () => {},
-    registerCleanup: () => {},
-    startMpv: async () => {
-      calls.push('startMpv');
-    },
-    waitForUnixSocketReady: async () => true,
-    startOverlay: async (_appPath, _args, _socketPath, extraAppArgs = []) => {
-      calls.push(`startOverlay:${extraAppArgs.join(' ')}`);
-    },
-    launchAppCommandDetached: () => {},
-    log: () => {},
-    cleanupPlaybackSession: async () => {},
-    getMpvProc: () => null,
-    isAppControlServerAvailable: async () => true,
-  } as Parameters<typeof runPlaybackCommandWithDeps>[1] & {
-    isAppControlServerAvailable: () => Promise<boolean>;
+  const harness = makeHarness({
+    context: createContext({ args: FILE_TARGET, plugin: { texthookerEnabled: true } }),
+    deps: { isAppControlServerAvailable: async () => true },
   });
 
-  assert.deepEqual(calls, ['startMpv', 'startOverlay:--show-visible-overlay']);
+  await harness.run();
+
+  assert.deepEqual(harness.overlayCalls[0]?.extraAppArgs, ['--show-visible-overlay']);
 });
 
 test('playback command ensures Linux runtime plugin before mpv launch', async () => {
-  const context = createContext();
-  context.args = {
-    ...context.args,
-    target: '/tmp/movie.mkv',
-    targetKind: 'file',
-  };
-  const calls: string[] = [];
+  const harness = makeHarness({ context: createContext({ args: FILE_TARGET }) });
 
-  await runPlaybackCommandWithDeps(context, {
-    ensurePlaybackSetupReady: async () => {},
-    ensureRuntimePluginReady: async () => {
-      calls.push('plugin');
-    },
-    chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
-    checkDependencies: () => {},
-    registerCleanup: () => {},
-    startMpv: async () => {
-      calls.push('startMpv');
-    },
-    waitForUnixSocketReady: async () => true,
-    startOverlay: async () => {},
-    launchAppCommandDetached: () => {},
-    log: () => {},
-    cleanupPlaybackSession: async () => {},
-    getMpvProc: () => null,
-  });
+  await harness.run();
 
-  assert.deepEqual(calls, ['plugin', 'startMpv']);
+  assertRanInOrder(harness.events, 'plugin', 'startMpv');
 });
 
 test('rofi playback repairs support assets before opening the picker', async () => {
-  const context = createContext();
-  context.args = {
-    ...context.args,
-    target: '',
-    targetKind: '',
-    useRofi: true,
-  };
-  const calls: string[] = [];
-
-  await runPlaybackCommandWithDeps(context, {
-    ensurePlaybackSetupReady: async () => {},
-    ensureRuntimePluginReady: async () => {
-      calls.push('assets');
-    },
+  const events: string[] = [];
+  const harness = makeHarness({
+    events,
+    context: createContext({ args: { target: '', targetKind: '', useRofi: true } }),
+    deps: {
       chooseTarget: async () => {
-      calls.push('picker');
+        events.push('picker');
         return { target: '/tmp/movie.mkv', kind: 'file' };
       },
       checkPickerDependencies: () => {},
-    checkDependencies: () => {},
-    registerCleanup: () => {},
-    startMpv: async () => {
-      calls.push('startMpv');
     },
-    waitForUnixSocketReady: async () => true,
-    startOverlay: async () => {},
-    launchAppCommandDetached: () => {},
-    log: () => {},
-    cleanupPlaybackSession: async () => {},
-    getMpvProc: () => null,
   });
 
-  assert.deepEqual(calls, ['assets', 'picker', 'startMpv']);
+  await harness.run();
+
+  assertRanInOrder(events, 'plugin', 'picker', 'startMpv');
 });

launcher/commands/sync-command.test.ts

@@ -48,49 +48,6 @@ test('runSyncCommand proxies sync argv to the app in --sync-cli mode', async ()
   assert.equal(spawned.length, 1);
 });
 
-test('runSyncCommand forwards tokens verbatim and appends the effective log level', async () => {
-  const spawned: string[][] = [];
-  const deps: Partial<SyncCommandDeps> = {
-    runAppCommand: (_appPath, appArgs) => {
-      spawned.push(appArgs);
-    },
-  };
-
-  await runSyncCommand(
-    makeContext({
-      syncCliTokens: [
-        'media-box',
-        '--pull',
-        '--remote-cmd',
-        '/opt/SubMiner.AppImage',
-        '--db',
-        '/tmp/db.sqlite',
-        '--force',
-        '--json',
-      ],
-      logLevel: 'debug',
-    }),
-    deps,
-  );
-
-  assert.deepEqual(spawned, [
-    [
-      '--sync-cli',
-      'sync',
-      'media-box',
-      '--pull',
-      '--remote-cmd',
-      '/opt/SubMiner.AppImage',
-      '--db',
-      '/tmp/db.sqlite',
-      '--force',
-      '--json',
-      '--log-level',
-      'debug',
-    ],
-  ]);
-});
-
 test('runSyncCommand fails with a clear message when the app binary is missing', async () => {
   const deps: Partial<SyncCommandDeps> = {
     runAppCommand: () => {

launcher/config-domain-parsers.test.ts

@@ -8,7 +8,6 @@ import {
   buildPluginRuntimeScriptOptParts,
   parsePluginRuntimeConfigFromMainConfig,
 } from './config/plugin-runtime-config.js';
-import { getDefaultSocketPath } from './types.js';
 
 test('parseLauncherYoutubeSubgenConfig keeps only valid typed values', () => {
   const parsed = parseLauncherYoutubeSubgenConfig({
@@ -207,10 +206,6 @@ test('buildPluginRuntimeScriptOptParts strips script-option delimiters from stri
   );
 });
 
-test('getDefaultSocketPath returns Windows named pipe default', () => {
-  assert.equal(getDefaultSocketPath('win32'), '\\\\.\\pipe\\subminer-socket');
-});
-
 test('parseLauncherMpvConfig reads configured mpv profile', () => {
   assert.deepEqual(
     parseLauncherMpvConfig({

launcher/config.test.ts

@@ -1,20 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { execFileSync } from 'node:child_process';
-import path from 'node:path';
-
-test('launcher root help lists subcommands', () => {
-  const output = execFileSync('bun', ['run', path.join(process.cwd(), 'launcher/main.ts'), '-h'], {
-    encoding: 'utf8',
-  });
-
-  assert.match(output, /Commands:/);
-  assert.match(output, /jellyfin\|jf/);
-  assert.match(output, /doctor/);
-  assert.match(output, /config/);
-  assert.match(output, /mpv/);
-  assert.match(output, /logs/);
-  assert.match(output, /dictionary\|dict/);
-  assert.match(output, /texthooker/);
-  assert.match(output, /app\|bin/);
-});

launcher/config/args-normalizer.test.ts

@@ -9,6 +9,7 @@ import {
   applyRootOptionsToArgs,
   createDefaultArgs,
 } from './args-normalizer.js';
+import type { CliInvocations } from './cli-parser-builder.js';
 
 function withTempDir<T>(fn: (dir: string) => T): T {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-launcher-args-'));
@@ -19,6 +20,48 @@ function withTempDir<T>(fn: (dir: string) => T): T {
   }
 }
 
+/** An invocations bag with nothing triggered; tests pass only the fields under test. */
+function emptyInvocations(overrides: Partial<CliInvocations> = {}): CliInvocations {
+  return {
+    jellyfinInvocation: null,
+    configInvocation: null,
+    settingsInvocation: null,
+    youtubeBrowserInvocation: null,
+    mpvInvocation: null,
+    appInvocation: null,
+    dictionaryTriggered: false,
+    dictionaryTarget: null,
+    dictionaryLogLevel: null,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
+    dictionaryAnilistId: null,
+    statsTriggered: false,
+    statsBackground: false,
+    statsStop: false,
+    statsCleanup: false,
+    statsCleanupVocab: false,
+    statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
+    statsLogLevel: null,
+    syncTriggered: false,
+    syncCliTokens: [],
+    syncLogLevel: null,
+    syncUiTriggered: false,
+    syncUiLogLevel: null,
+    doctorTriggered: false,
+    doctorLogLevel: null,
+    doctorRefreshKnownWords: false,
+    logsTriggered: false,
+    logsExport: false,
+    texthookerTriggered: false,
+    texthookerLogLevel: null,
+    texthookerOpenBrowser: false,
+    ...overrides,
+  };
+}
+
 test('createDefaultArgs normalizes configured language codes', () => {
   const parsed = createDefaultArgs({
     primarySubLanguages: [' JA ', 'jpn', 'ja'],
@@ -92,7 +135,9 @@ test('applyRootOptionsToArgs rejects unsupported targets', () => {
 test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
   const parsed = createDefaultArgs({});
 
-  applyInvocationsToArgs(parsed, {
+  applyInvocationsToArgs(
+    parsed,
+    emptyInvocations({
       jellyfinInvocation: {
         action: 'play',
         play: true,
@@ -105,40 +150,8 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
         action: 'show',
         logLevel: 'warn',
       },
-    settingsInvocation: null,
-    youtubeBrowserInvocation: null,
-    mpvInvocation: null,
-    appInvocation: null,
-    dictionaryTriggered: false,
-    dictionaryTarget: null,
-    dictionaryLogLevel: null,
-    dictionaryCandidates: false,
-    dictionarySelect: false,
-    dictionaryAnilistId: null,
-    statsTriggered: false,
-    statsBackground: false,
-    statsStop: false,
-    statsCleanup: false,
-    statsCleanupVocab: false,
-    statsCleanupLifetime: false,
-    statsCleanupDuplicateLines: false,
-    statsCleanupDryRun: false,
-    statsCleanupLookbackDays: null,
-    statsLogLevel: null,
-    syncTriggered: false,
-    syncCliTokens: [],
-    syncLogLevel: null,
-    syncUiTriggered: false,
-    syncUiLogLevel: null,
-    doctorTriggered: false,
-    doctorLogLevel: null,
-    doctorRefreshKnownWords: false,
-    logsTriggered: false,
-    logsExport: false,
-    texthookerTriggered: false,
-    texthookerLogLevel: null,
-    texthookerOpenBrowser: false,
-  });
+    }),
+  );
 
   assert.equal(parsed.jellyfin, false);
   assert.equal(parsed.jellyfinPlay, true);
@@ -155,45 +168,14 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
 test('applyInvocationsToArgs maps settings invocation to settings window', () => {
   const parsed = createDefaultArgs({});
 
-  applyInvocationsToArgs(parsed, {
-    jellyfinInvocation: null,
-    configInvocation: null,
+  applyInvocationsToArgs(
+    parsed,
+    emptyInvocations({
       settingsInvocation: {
         logLevel: undefined,
       },
-    youtubeBrowserInvocation: null,
-    mpvInvocation: null,
-    appInvocation: null,
-    dictionaryTriggered: false,
-    dictionaryTarget: null,
-    dictionaryLogLevel: null,
-    dictionaryCandidates: false,
-    dictionarySelect: false,
-    dictionaryAnilistId: null,
-    statsTriggered: false,
-    statsBackground: false,
-    statsStop: false,
-    statsCleanup: false,
-    statsCleanupVocab: false,
-    statsCleanupLifetime: false,
-    statsCleanupDuplicateLines: false,
-    statsCleanupDryRun: false,
-    statsCleanupLookbackDays: null,
-    statsLogLevel: null,
-    syncTriggered: false,
-    syncCliTokens: [],
-    syncLogLevel: null,
-    syncUiTriggered: false,
-    syncUiLogLevel: null,
-    doctorTriggered: false,
-    doctorLogLevel: null,
-    doctorRefreshKnownWords: false,
-    logsTriggered: false,
-    logsExport: false,
-    texthookerTriggered: false,
-    texthookerLogLevel: null,
-    texthookerOpenBrowser: false,
-  });
+    }),
+  );
 
   assert.equal(parsed.settings, true);
   assert.equal(parsed.configPath, false);
@@ -203,45 +185,14 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
   const parsed = createDefaultArgs({});
 
   const error = withProcessExitIntercept(() => {
-    applyInvocationsToArgs(parsed, {
-      jellyfinInvocation: null,
+    applyInvocationsToArgs(
+      parsed,
+      emptyInvocations({
         configInvocation: {
           action: undefined,
         },
-      settingsInvocation: null,
-      youtubeBrowserInvocation: null,
-      mpvInvocation: null,
-      appInvocation: null,
-      dictionaryTriggered: false,
-      dictionaryTarget: null,
-      dictionaryLogLevel: null,
-      dictionaryCandidates: false,
-      dictionarySelect: false,
-      dictionaryAnilistId: null,
-      statsTriggered: false,
-      statsBackground: false,
-      statsStop: false,
-      statsCleanup: false,
-      statsCleanupVocab: false,
-      statsCleanupLifetime: false,
-      statsCleanupDuplicateLines: false,
-      statsCleanupDryRun: false,
-      statsCleanupLookbackDays: null,
-      statsLogLevel: null,
-      syncTriggered: false,
-      syncCliTokens: [],
-      syncLogLevel: null,
-      syncUiTriggered: false,
-      syncUiLogLevel: null,
-      doctorTriggered: false,
-      doctorLogLevel: null,
-      doctorRefreshKnownWords: false,
-      logsTriggered: false,
-      logsExport: false,
-      texthookerTriggered: false,
-      texthookerLogLevel: null,
-      texthookerOpenBrowser: false,
-    });
+      }),
+    );
   });
 
   assert.equal(error.code, 1);
@@ -251,43 +202,13 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
 test('applyInvocationsToArgs maps texthooker browser-open request', () => {
   const parsed = createDefaultArgs({});
 
-  applyInvocationsToArgs(parsed, {
-    jellyfinInvocation: null,
-    configInvocation: null,
-    settingsInvocation: null,
-    youtubeBrowserInvocation: null,
-    mpvInvocation: null,
-    appInvocation: null,
-    dictionaryTriggered: false,
-    dictionaryTarget: null,
-    dictionaryLogLevel: null,
-    dictionaryCandidates: false,
-    dictionarySelect: false,
-    dictionaryAnilistId: null,
-    statsTriggered: false,
-    statsBackground: false,
-    statsStop: false,
-    statsCleanup: false,
-    statsCleanupVocab: false,
-    statsCleanupLifetime: false,
-    statsCleanupDuplicateLines: false,
-    statsCleanupDryRun: false,
-    statsCleanupLookbackDays: null,
-    statsLogLevel: null,
-    syncTriggered: false,
-    syncCliTokens: [],
-    syncLogLevel: null,
-    syncUiTriggered: false,
-    syncUiLogLevel: null,
-    doctorTriggered: false,
-    doctorLogLevel: null,
-    doctorRefreshKnownWords: false,
-    logsTriggered: false,
-    logsExport: false,
+  applyInvocationsToArgs(
+    parsed,
+    emptyInvocations({
       texthookerTriggered: true,
-    texthookerLogLevel: null,
       texthookerOpenBrowser: true,
-  });
+    }),
+  );
 
   assert.equal(parsed.texthookerOnly, true);
   assert.equal(parsed.texthookerOpenBrowser, true);

launcher/jellyfin.test.ts

@@ -1,83 +1,51 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import type { Args } from './types.js';
-import { runJellyfinPlayMenuWithDeps } from './jellyfin.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  buildForwardedJellyfinAppArgs,
+  buildRootSearchGroups,
+  classifyJellyfinChildSelection,
+  deriveJellyfinTokenStorePath,
+  hasStoredJellyfinSession,
+  parseEpisodePathFromDisplay,
+  parseJellyfinErrorFromAppOutput,
+  parseJellyfinItemsFromAppOutput,
+  parseJellyfinLibrariesFromAppOutput,
+  parseJellyfinPreviewAuthResponse,
+  readUtf8FileAppendedSince,
+  runJellyfinPlayMenuWithDeps,
+  shouldRetryWithStartForNoRunningInstance,
+} from './jellyfin.js';
+import { makeLauncherArgs } from './test-support/args.js';
+import { withEnv } from './test-support/env.js';
 
-function createArgs(): Args {
-  return {
-    backend: 'auto',
-    directory: '.',
-    recursive: false,
-    profile: '',
-    startOverlay: false,
-    youtubePrimarySubLangs: [],
-    youtubeSecondarySubLangs: [],
-    youtubeAudioLangs: [],
-    useTexthooker: false,
-    autoStartOverlay: false,
-    texthookerOnly: false,
-    texthookerOpenBrowser: false,
-    useRofi: false,
-    history: false,
-    sync: false,
-    syncCliTokens: [],
-    syncUi: false,
-    logLevel: 'info',
-    logRotation: 7,
-    passwordStore: '',
-    target: '',
-    targetKind: '',
-    jimakuApiKey: '',
-    jimakuApiKeyCommand: '',
-    jimakuApiBaseUrl: '',
-    jimakuLanguagePreference: 'ja',
-    jimakuMaxEntryResults: 20,
-    jellyfin: false,
-    jellyfinLogin: false,
-    jellyfinLogout: false,
-    jellyfinPlay: false,
-    jellyfinDiscovery: false,
-    dictionary: false,
-    dictionaryCandidates: false,
-    dictionarySelect: false,
-    stats: false,
-    doctor: false,
-    doctorRefreshKnownWords: false,
-    logsExport: false,
-    version: false,
-    settings: false,
-    youtubeBrowser: false,
-    configPath: false,
-    configShow: false,
-    mpvIdle: false,
-    mpvSocket: false,
-    mpvStatus: false,
-    mpvArgs: '',
-    appPassthrough: false,
-    appArgs: [],
-    jellyfinServer: 'https://jellyfin.example.test',
-    jellyfinUsername: '',
-    jellyfinPassword: '',
-    launchMode: 'normal',
-  };
+function withTempDir<T>(fn: (dir: string) => T): T {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-jellyfin-test-'));
+  try {
+    return fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
 }
 
-test('Jellyfin playback ensures Linux runtime plugin before detached idle mpv bootstrap', async () => {
-  const originalAccessToken = process.env.SUBMINER_JELLYFIN_ACCESS_TOKEN;
-  const originalUserId = process.env.SUBMINER_JELLYFIN_USER_ID;
-  process.env.SUBMINER_JELLYFIN_ACCESS_TOKEN = 'token';
-  process.env.SUBMINER_JELLYFIN_USER_ID = 'user';
-  const calls: string[] = [];
+class HandoffComplete extends Error {}
 
-  try {
-    await assert.rejects(
-      () =>
-        runJellyfinPlayMenuWithDeps(
-          '/tmp/SubMiner.AppImage',
-          createArgs(),
-          '/tmp/subminer',
-          '/tmp/subminer.sock',
-          {
+type PlayMenuDeps = NonNullable<Parameters<typeof runJellyfinPlayMenuWithDeps>[4]>;
+
+/**
+ * Runs the play menu with fake deps and a direct env session. The app handoff never returns in
+ * production, so the fake throws `HandoffComplete` after recording its args into `handoff`.
+ */
+async function runPlayMenu(options: {
+  socketReady?: boolean;
+  overrides?: Partial<PlayMenuDeps>;
+  args?: Parameters<typeof makeLauncherArgs>[0];
+}) {
+  const launches: string[] = [];
+  const handoff: { appArgs: string[] | null } = { appArgs: null };
+  const deps: PlayMenuDeps = {
     loadLauncherJellyfinConfig: () => ({}),
     findRofiTheme: () => null,
     resolveJellyfinSelection: async () => 'item-123',
@@ -87,42 +55,251 @@ test('Jellyfin playback ensures Linux runtime plugin before detached idle mpv bo
     hasStoredJellyfinSession: () => true,
     requestJellyfinPreviewAuthFromApp: async () => null,
     resolveLauncherMainConfigPath: () => '/tmp/SubMiner/config.jsonc',
-            pathExists: () => false,
+    pathExists: () => options.socketReady ?? false,
     ensureRuntimePluginReady: async () => {
-              calls.push('plugin');
-            },
-            waitForUnixSocketReady: async () => {
-              calls.push('wait');
-              return true;
+      launches.push('plugin');
     },
+    waitForUnixSocketReady: async () => true,
     launchMpvIdleDetached: async () => {
-              calls.push('launch');
+      launches.push('launch');
     },
-            resolveLauncherRuntimePluginPath: () => {
-              calls.push('resolve');
-              return '/tmp/plugin/main.lua';
-            },
-            runAppCommandWithInheritLogged: () => {
-              calls.push('handoff');
-              throw new Error('stop after handoff');
+    resolveLauncherRuntimePluginPath: () => '/tmp/plugin/main.lua',
+    runAppCommandWithInheritLogged: (_appPath, appArgs) => {
+      handoff.appArgs = appArgs;
+      throw new HandoffComplete();
     },
     log: () => {},
-          },
+    ...options.overrides,
+  };
+
+  await withEnv(
+    { SUBMINER_JELLYFIN_ACCESS_TOKEN: 'token', SUBMINER_JELLYFIN_USER_ID: 'user' },
+    () =>
+      assert.rejects(
+        () =>
+          runJellyfinPlayMenuWithDeps(
+            '/tmp/SubMiner.AppImage',
+            makeLauncherArgs({ jellyfinServer: 'https://jellyfin.example.test', ...options.args }),
+            '/tmp/subminer',
+            '/tmp/subminer.sock',
+            deps,
+          ),
+        HandoffComplete,
       ),
-      /stop after handoff/,
   );
 
-    assert.deepEqual(calls, ['plugin', 'resolve', 'launch', 'wait', 'handoff']);
-  } finally {
-    if (originalAccessToken === undefined) {
-      delete process.env.SUBMINER_JELLYFIN_ACCESS_TOKEN;
-    } else {
-      process.env.SUBMINER_JELLYFIN_ACCESS_TOKEN = originalAccessToken;
-    }
-    if (originalUserId === undefined) {
-      delete process.env.SUBMINER_JELLYFIN_USER_ID;
-    } else {
-      process.env.SUBMINER_JELLYFIN_USER_ID = originalUserId;
-    }
+  return { launches, appArgs: handoff.appArgs };
 }
+
+test('Jellyfin playback launches the idle mpv with the runtime plugin, then hands the item to the app', async () => {
+  const { launches, appArgs } = await runPlayMenu({});
+
+  assert.deepEqual(launches, ['plugin', 'launch']);
+  assert.deepEqual(appArgs, ['--start', '--jellyfin-play', '--jellyfin-item-id=item-123']);
+});
+
+test('Jellyfin playback reuses a ready mpv socket instead of launching idle mpv', async () => {
+  const { launches, appArgs } = await runPlayMenu({ socketReady: true });
+
+  assert.deepEqual(launches, []);
+  assert.deepEqual(appArgs, ['--start', '--jellyfin-play', '--jellyfin-item-id=item-123']);
+});
+
+test('parseJellyfinLibrariesFromAppOutput parses prefixed library lines', () => {
+  const parsed = parseJellyfinLibrariesFromAppOutput(`
+[subminer] - 2026-03-01 13:10:34 - INFO - [main] Jellyfin library: Anime [lib1] (tvshows)
+[subminer] - 2026-03-01 13:10:35 - INFO - [main] Jellyfin library: Movies [lib2] (movies)
+`);
+
+  assert.deepEqual(parsed, [
+    { id: 'lib1', name: 'Anime', kind: 'tvshows' },
+    { id: 'lib2', name: 'Movies', kind: 'movies' },
+  ]);
+});
+
+test('parseJellyfinItemsFromAppOutput parses item title/id/type tuples', () => {
+  const parsed = parseJellyfinItemsFromAppOutput(`
+[subminer] - 2026-03-01 13:10:34 - INFO - [main] Jellyfin item: Solo Leveling S01E10 [item-10] (Episode)
+[subminer] - 2026-03-01 13:10:35 - INFO - [main] Jellyfin item: Movie [Alt] [movie-1] (Movie)
+`);
+
+  assert.deepEqual(parsed, [
+    {
+      id: 'item-10',
+      name: 'Solo Leveling S01E10',
+      type: 'Episode',
+      display: 'Solo Leveling S01E10',
+    },
+    {
+      id: 'movie-1',
+      name: 'Movie [Alt]',
+      type: 'Movie',
+      display: 'Movie [Alt]',
+    },
+  ]);
+});
+
+test('buildForwardedJellyfinAppArgs forces app log level for parseable list output', () => {
+  const forwarded = buildForwardedJellyfinAppArgs(
+    {
+      jellyfinServer: 'https://jf.example.test/',
+      passwordStore: 'gnome-libsecret',
+      logLevel: 'info',
+    } as never,
+    ['--jellyfin-libraries'],
+  );
+
+  assert.deepEqual(forwarded, [
+    '--jellyfin-libraries',
+    '--jellyfin-server',
+    'https://jf.example.test',
+    '--password-store',
+    'gnome-libsecret',
+    '--log-level',
+    'info',
+  ]);
+});
+
+test('parseJellyfinErrorFromAppOutput extracts bracketed error lines', () => {
+  const parsed = parseJellyfinErrorFromAppOutput(`
+[subminer] - 2026-03-01 13:10:34 - WARN - [main] test warning
+[2026-03-01T21:11:28.821Z] [ERROR] Missing Jellyfin session. Set SUBMINER_JELLYFIN_ACCESS_TOKEN and SUBMINER_JELLYFIN_USER_ID, then retry.
+`);
+
+  assert.equal(
+    parsed,
+    'Missing Jellyfin session. Set SUBMINER_JELLYFIN_ACCESS_TOKEN and SUBMINER_JELLYFIN_USER_ID, then retry.',
+  );
+});
+
+test('parseJellyfinErrorFromAppOutput extracts main runtime error lines', () => {
+  const parsed = parseJellyfinErrorFromAppOutput(`
+[subminer] - 2026-03-01 13:10:34 - ERROR - [main] runJellyfinCommand failed: {"message":"Missing Jellyfin password."}
+`);
+
+  assert.equal(
+    parsed,
+    '[main] runJellyfinCommand failed: {"message":"Missing Jellyfin password."}',
+  );
+});
+
+test('parseJellyfinPreviewAuthResponse parses valid structured response payload', () => {
+  const parsed = parseJellyfinPreviewAuthResponse(
+    JSON.stringify({
+      serverUrl: 'http://pve-main:8096/',
+      accessToken: 'token-123',
+      userId: 'user-1',
+    }),
+  );
+
+  assert.deepEqual(parsed, {
+    serverUrl: 'http://pve-main:8096',
+    accessToken: 'token-123',
+    userId: 'user-1',
+  });
+});
+
+test('parseJellyfinPreviewAuthResponse returns null for invalid payloads', () => {
+  assert.equal(parseJellyfinPreviewAuthResponse(''), null);
+  assert.equal(parseJellyfinPreviewAuthResponse('{not json}'), null);
+  assert.equal(
+    parseJellyfinPreviewAuthResponse(
+      JSON.stringify({
+        serverUrl: 'http://pve-main:8096',
+        accessToken: '',
+        userId: 'user-1',
+      }),
+    ),
+    null,
+  );
+});
+
+test('hasStoredJellyfinSession checks token-store existence', () => {
+  const configPath = path.join('/home/test', '.config', 'SubMiner', 'config.jsonc');
+  const tokenPath = deriveJellyfinTokenStorePath(configPath);
+  const exists = (candidate: string): boolean => candidate === tokenPath;
+  assert.equal(hasStoredJellyfinSession(configPath, exists), true);
+  assert.equal(
+    hasStoredJellyfinSession(path.join('/home/test', '.config', 'Other', 'alt.jsonc'), exists),
+    false,
+  );
+});
+
+test('shouldRetryWithStartForNoRunningInstance matches expected app lifecycle error', () => {
+  assert.equal(
+    shouldRetryWithStartForNoRunningInstance('No running instance. Use --start to launch the app.'),
+    true,
+  );
+  assert.equal(
+    shouldRetryWithStartForNoRunningInstance(
+      'Missing Jellyfin session. Run --jellyfin-login first.',
+    ),
+    false,
+  );
+});
+
+test('readUtf8FileAppendedSince treats offset as bytes and survives multibyte logs', () => {
+  withTempDir((root) => {
+    const logPath = path.join(root, 'SubMiner.log');
+    const prefix = '[subminer] こんにちは\n';
+    const suffix = '[subminer] Jellyfin library: Movies [lib2] (movies)\n';
+    fs.writeFileSync(logPath, `${prefix}${suffix}`, 'utf8');
+
+    const byteOffset = Buffer.byteLength(prefix, 'utf8');
+    const fromByteOffset = readUtf8FileAppendedSince(logPath, byteOffset);
+    assert.match(fromByteOffset, /Jellyfin library: Movies \[lib2\] \(movies\)/);
+
+    const fromBeyondEnd = readUtf8FileAppendedSince(logPath, byteOffset + 9999);
+    assert.match(fromBeyondEnd, /Jellyfin library: Movies \[lib2\] \(movies\)/);
+  });
+});
+
+test('parseEpisodePathFromDisplay extracts series and season from episode display titles', () => {
+  assert.deepEqual(
+    parseEpisodePathFromDisplay('KONOSUBA S01E03 A Panty Treasure in This Right Hand!'),
+    {
+      seriesName: 'KONOSUBA',
+      seasonNumber: 1,
+    },
+  );
+  assert.deepEqual(parseEpisodePathFromDisplay('Frieren S2E10 Something'), {
+    seriesName: 'Frieren',
+    seasonNumber: 2,
+  });
+});
+
+test('parseEpisodePathFromDisplay returns null for non-episode displays', () => {
+  assert.equal(parseEpisodePathFromDisplay('Movie Title (Movie)'), null);
+  assert.equal(parseEpisodePathFromDisplay('Just A Name'), null);
+});
+
+test('buildRootSearchGroups excludes episodes and keeps containers/movies', () => {
+  const groups = buildRootSearchGroups([
+    { id: 'series-1', name: 'The Eminence in Shadow', type: 'Series', display: 'x' },
+    { id: 'movie-1', name: 'Spirited Away', type: 'Movie', display: 'x' },
+    { id: 'episode-1', name: 'The Eminence in Shadow S01E01', type: 'Episode', display: 'x' },
+  ]);
+
+  assert.deepEqual(groups, [
+    {
+      id: 'series-1',
+      name: 'The Eminence in Shadow',
+      type: 'Series',
+      display: 'The Eminence in Shadow (Series)',
+    },
+    {
+      id: 'movie-1',
+      name: 'Spirited Away',
+      type: 'Movie',
+      display: 'Spirited Away (Movie)',
+    },
+  ]);
+});
+
+test('classifyJellyfinChildSelection keeps container drilldown state instead of flattening', () => {
+  const next = classifyJellyfinChildSelection({ id: 'season-2', type: 'Season' });
+  assert.deepEqual(next, {
+    kind: 'container',
+    id: 'season-2',
+  });
 });

launcher/parse-args.test.ts

@@ -30,12 +30,6 @@ test('parseArgs captures mpv args string', () => {
   assert.equal(parsed.mpvArgs, '--pause=yes --title="movie night"');
 });
 
-test('parseArgs appends CLI mpv profile to configured mpv profile', () => {
-  const parsed = parseArgs(['--profile', 'hdr'], 'subminer', {}, { profile: 'anime' });
-
-  assert.equal(parsed.profile, 'anime,hdr');
-});
-
 test('parseArgs maps root settings window option', () => {
   const parsed = parseArgs(['--settings'], 'subminer', {});
 
@@ -224,14 +218,6 @@ test('parseArgs maps stats cleanup to vocab mode by default', () => {
   assert.equal(parsed.statsCleanupVocab, true);
 });
 
-test('parseArgs maps explicit stats cleanup vocab flag', () => {
-  const parsed = parseArgs(['stats', 'cleanup', '-v'], 'subminer', {});
-
-  assert.equal(parsed.stats, true);
-  assert.equal(parsed.statsCleanup, true);
-  assert.equal(parsed.statsCleanupVocab, true);
-});
-
 test('parseArgs maps lifetime stats cleanup flag', () => {
   const parsed = parseArgs(['stats', 'cleanup', '--lifetime'], 'subminer', {});
 

launcher/runtime-plugin-preflight.test.ts

@@ -8,282 +8,168 @@ import {
   installManagedPluginAssetsViaApp,
 } from './runtime-plugin-preflight';
 
-test('ensureLinuxRuntimePluginAvailable is a no-op on non-Linux platforms', async () => {
-  const calls: string[] = [];
+type EnsureOptions = Parameters<typeof ensureLinuxRuntimePluginAvailable>[0];
 
-  await ensureLinuxRuntimePluginAvailable({
-    platform: 'darwin',
-    detectInstalledPlugin: () => {
-      calls.push('detect');
-      return false;
-    },
-    resolveRuntimePluginPath: () => {
-      calls.push('resolve');
-      return null;
-    },
-    installManagedPluginAssets: async () => {
-      calls.push('install');
-      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
-    },
-    log: () => {
-      calls.push('log');
-    },
-  });
-
-  assert.deepEqual(calls, []);
-});
-
-test('ensureLinuxRuntimePluginAvailable skips install when plugin, theme, and thumbnailer exist', async () => {
-  const calls: string[] = [];
-
-  await ensureLinuxRuntimePluginAvailable({
-    platform: 'linux',
-    detectInstalledPlugin: () => {
-      calls.push('detect');
-      return true;
-    },
-    resolveRuntimePluginPath: () => {
-      calls.push('resolve');
-      return null;
-    },
-    installManagedPluginAssets: async () => {
-      calls.push('install');
-      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
-    },
-    isManagedThemeAvailable: () => {
-      calls.push('theme');
-      return true;
-    },
-    isManagedThumbnailerAvailable: () => {
-      calls.push('thumbnailer');
-      return true;
-    },
-    log: () => {},
-  });
-
-  assert.deepEqual(calls, ['detect', 'theme', 'thumbnailer']);
-});
-
-test('ensureLinuxRuntimePluginAvailable skips install when all managed assets resolve', async () => {
-  const calls: string[] = [];
-
-  await ensureLinuxRuntimePluginAvailable({
-    platform: 'linux',
-    xdgDataHome: '/tmp/xdg-data',
-    detectInstalledPlugin: () => {
-      calls.push('detect');
-      return false;
-    },
-    resolveRuntimePluginPath: () => {
-      calls.push('resolve');
-      return '/tmp/plugin/main.lua';
-    },
-    installManagedPluginAssets: async () => {
-      calls.push('install');
-      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
-    },
-    isManagedThemeAvailable: () => {
-      calls.push('theme');
-      return true;
-    },
-    isManagedThumbnailerAvailable: () => {
-      calls.push('thumbnailer');
-      return true;
-    },
-    log: () => {},
-  });
-
-  assert.deepEqual(calls, ['detect', 'resolve', 'theme', 'thumbnailer']);
-});
-
-test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme is missing', async () => {
-  const calls: string[] = [];
-  let themeAvailable = false;
-
-  await ensureLinuxRuntimePluginAvailable({
-    platform: 'linux',
-    xdgDataHome: '/tmp/xdg-data',
-    detectInstalledPlugin: () => {
-      calls.push('detect');
-      return false;
-    },
-    resolveRuntimePluginPath: () => {
-      calls.push('resolve');
-      return '/tmp/plugin/main.lua';
-    },
-    isManagedThemeAvailable: () => {
-      calls.push('theme');
-      return themeAvailable;
-    },
-    isManagedThumbnailerAvailable: () => {
-      calls.push('thumbnailer');
-      return true;
-    },
-    installManagedPluginAssets: async () => {
-      calls.push('install');
-      themeAvailable = true;
-      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
-    },
-    log: (level, _configured, message) => {
-      calls.push(`${level}:${message}`);
-    },
-  });
-
-  assert.deepEqual(calls, [
-    'detect',
-    'resolve',
-    'theme',
-    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
-    'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
-    'resolve',
-    'theme',
-    'thumbnailer',
-  ]);
-});
-
-test('ensureLinuxRuntimePluginAvailable installs managed assets when thumbnailer is missing', async () => {
-  const calls: string[] = [];
-  let thumbnailerAvailable = false;
-
-  await ensureLinuxRuntimePluginAvailable({
-    platform: 'linux',
-    xdgDataHome: '/tmp/xdg-data',
-    detectInstalledPlugin: () => true,
-    resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
-    isManagedThemeAvailable: () => true,
-    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
-    installManagedPluginAssets: async () => {
-      calls.push('install');
-      thumbnailerAvailable = true;
-      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
-    },
-    log: (_level, _configured, message) => {
-      calls.push(message);
-    },
-  });
-
-  assert.deepEqual(calls, [
-    'Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
-    'install',
-    'Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
-  ]);
-});
-
-test('ensureLinuxRuntimePluginAvailable retains an installed plugin after installing support assets', async () => {
-  const calls: string[] = [];
-  let thumbnailerAvailable = false;
-
-  await ensureLinuxRuntimePluginAvailable({
-    platform: 'linux',
-    xdgDataHome: '/tmp/xdg-data',
-    detectInstalledPlugin: () => true,
-    resolveRuntimePluginPath: () => {
-      calls.push('resolve');
-      return null;
-    },
-    isManagedThemeAvailable: () => true,
-    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
-    installManagedPluginAssets: async () => {
-      calls.push('install');
-      thumbnailerAvailable = true;
-      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
-    },
-    log: () => {},
-  });
-
-  assert.deepEqual(calls, ['install']);
-});
-
-test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves plugin path', async () => {
-  const calls: string[] = [];
-  let resolveCount = 0;
-
-  await ensureLinuxRuntimePluginAvailable({
+/**
+ * Linux preflight harness: by default every managed asset resolves, so tests override only
+ * the probes that should report something missing. Counts installs and collects log messages.
+ */
+function makeEnsureHarness(overrides: Partial<EnsureOptions> = {}) {
+  const state = { installs: 0, logs: [] as string[] };
+  const options: EnsureOptions = {
     platform: 'linux',
     xdgDataHome: '/tmp/xdg-data',
     detectInstalledPlugin: () => false,
-    resolveRuntimePluginPath: () => {
-      resolveCount += 1;
-      calls.push(`resolve:${resolveCount}`);
-      return resolveCount === 1 ? null : '/tmp/plugin/main.lua';
-    },
+    resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
     isManagedThemeAvailable: () => true,
     isManagedThumbnailerAvailable: () => true,
     installManagedPluginAssets: async () => {
-      calls.push('install');
+      state.installs += 1;
       return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
     },
-    log: (level, _configured, message) => {
-      calls.push(`${level}:${message}`);
+    log: (_level, _configured, message) => {
+      state.logs.push(message);
+    },
+    ...overrides,
+  };
+  return { state, run: () => ensureLinuxRuntimePluginAvailable(options) };
+}
+
+test('ensureLinuxRuntimePluginAvailable is a no-op on non-Linux platforms', async () => {
+  const unexpected = () => {
+    throw new Error('probed on a non-Linux platform');
+  };
+  const harness = makeEnsureHarness({
+    platform: 'darwin',
+    detectInstalledPlugin: unexpected,
+    resolveRuntimePluginPath: unexpected,
+    isManagedThemeAvailable: unexpected,
+    isManagedThumbnailerAvailable: unexpected,
+  });
+
+  await harness.run();
+
+  assert.equal(harness.state.installs, 0);
+  assert.deepEqual(harness.state.logs, []);
+});
+
+const skipInstallCases: Array<{ name: string; overrides: Partial<EnsureOptions> }> = [
+  {
+    name: 'plugin, theme, and thumbnailer exist',
+    overrides: { detectInstalledPlugin: () => true, resolveRuntimePluginPath: () => null },
+  },
+  { name: 'all managed assets resolve', overrides: {} },
+];
+
+for (const c of skipInstallCases) {
+  test(`ensureLinuxRuntimePluginAvailable skips install when ${c.name}`, async () => {
+    const harness = makeEnsureHarness(c.overrides);
+
+    await harness.run();
+
+    assert.equal(harness.state.installs, 0);
+    assert.deepEqual(harness.state.logs, []);
+  });
+}
+
+const installWhenMissingCases: Array<{ name: string; missing: 'theme' | 'thumbnailer' }> = [
+  { name: 'rofi theme is missing', missing: 'theme' },
+  { name: 'thumbnailer is missing', missing: 'thumbnailer' },
+];
+
+for (const c of installWhenMissingCases) {
+  test(`ensureLinuxRuntimePluginAvailable installs managed assets when ${c.name}`, async () => {
+    let available = false;
+    const probe = {
+      [c.missing === 'theme' ? 'isManagedThemeAvailable' : 'isManagedThumbnailerAvailable']: () =>
+        available,
+    };
+    const harness = makeEnsureHarness({
+      ...probe,
+      installManagedPluginAssets: async () => {
+        harness.state.installs += 1;
+        available = true;
+        return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
       },
     });
 
-  assert.deepEqual(calls, [
-    'resolve:1',
-    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
-    'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
-    'resolve:2',
-  ]);
+    await harness.run();
+
+    assert.equal(harness.state.installs, 1);
+    assert.equal(harness.state.logs.length, 2);
+    assert.match(harness.state.logs[0]!, /support assets missing; installing/);
+    assert.match(
+      harness.state.logs[1]!,
+      /installed: plugin=\/tmp\/plugin\/main\.lua theme=.*subminer\.rasi thumbnailer=.*\.thumbnailer/,
+    );
+  });
+}
+
+test('ensureLinuxRuntimePluginAvailable retains an installed plugin after installing support assets', async () => {
+  let thumbnailerAvailable = false;
+  const harness = makeEnsureHarness({
+    detectInstalledPlugin: () => true,
+    // An installed plugin means the bundled path is never needed, even after the install.
+    resolveRuntimePluginPath: () => null,
+    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
+    installManagedPluginAssets: async () => {
+      harness.state.installs += 1;
+      thumbnailerAvailable = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
   });
 
-test('ensureLinuxRuntimePluginAvailable fails when install result is not ok', async () => {
-  await assert.rejects(
-    () =>
-      ensureLinuxRuntimePluginAvailable({
-        platform: 'linux',
-        detectInstalledPlugin: () => false,
+  await harness.run();
+
+  assert.equal(harness.state.installs, 1);
+});
+
+test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves plugin path', async () => {
+  let installed = false;
+  const harness = makeEnsureHarness({
+    resolveRuntimePluginPath: () => (installed ? '/tmp/plugin/main.lua' : null),
+    installManagedPluginAssets: async () => {
+      harness.state.installs += 1;
+      installed = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
+  });
+
+  await harness.run();
+
+  assert.equal(harness.state.installs, 1);
+});
+
+const failureCases: Array<{ name: string; overrides: Partial<EnsureOptions>; error: RegExp }> = [
+  {
+    name: 'install result is not ok',
+    overrides: {
       resolveRuntimePluginPath: () => null,
       installManagedPluginAssets: async () => ({
         ok: false,
         status: 'failed',
         error: 'copy failed',
       }),
-        log: () => {},
-      }),
-    /copy failed/,
-  );
-});
+    },
+    error: /copy failed/,
+  },
+  {
+    name: 'runtime path remains unresolved after install',
+    overrides: { resolveRuntimePluginPath: () => null },
+    error: /managed runtime plugin assets could not be installed/i,
+  },
+  {
+    name: 'thumbnailer remains missing after install',
+    overrides: { detectInstalledPlugin: () => true, isManagedThumbnailerAvailable: () => false },
+    error: /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
+  },
+];
 
-test('ensureLinuxRuntimePluginAvailable fails when runtime path remains unresolved after install', async () => {
-  await assert.rejects(
-    () =>
-      ensureLinuxRuntimePluginAvailable({
-        platform: 'linux',
-        detectInstalledPlugin: () => false,
-        resolveRuntimePluginPath: () => null,
-        installManagedPluginAssets: async () => ({
-          ok: true,
-          status: 'installed',
-          path: '/tmp/plugin/main.lua',
-        }),
-        log: () => {},
-      }),
-    /managed runtime plugin assets could not be installed/i,
-  );
-});
-
-test('ensureLinuxRuntimePluginAvailable fails when thumbnailer remains missing after install', async () => {
-  await assert.rejects(
-    () =>
-      ensureLinuxRuntimePluginAvailable({
-        platform: 'linux',
-        xdgDataHome: '/tmp/xdg-data',
-        detectInstalledPlugin: () => true,
-        resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
-        isManagedThemeAvailable: () => true,
-        isManagedThumbnailerAvailable: () => false,
-        installManagedPluginAssets: async () => ({
-          ok: true,
-          status: 'installed',
-          path: '/tmp/plugin/main.lua',
-        }),
-        log: () => {},
-      }),
-    /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
-  );
+for (const c of failureCases) {
+  test(`ensureLinuxRuntimePluginAvailable fails when ${c.name}`, async () => {
+    await assert.rejects(() => makeEnsureHarness(c.overrides).run(), c.error);
   });
+}
 
 test('ensureLinuxRuntimePluginAvailable rejects a thumbnailer directory before and after install', async () => {
   const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-thumbnailer-directory-'));

launcher/setup-gate.test.ts

@@ -7,104 +7,90 @@ import {
 } from './setup-gate';
 import { createDefaultSetupState, type SetupState } from '../src/shared/setup-state';
 
-const commandLineSetupDefaults = {
+/** An in-progress setup state; tests override only the fields that matter. */
+function makeState(overrides: Partial<SetupState> = {}): SetupState {
+  return {
+    version: 4,
+    status: 'in_progress',
+    completedAt: null,
+    completionSource: null,
+    yomitanSetupMode: null,
+    lastSeenYomitanDictionaryCount: 0,
+    pluginInstallStatus: 'unknown',
+    pluginInstallPathSummary: null,
+    windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
+    windowsMpvShortcutLastStatus: 'unknown',
     bunInstallStatus: 'unknown',
     launcherInstallStatus: 'unknown',
     launcherInstallPath: null,
-} satisfies Pick<SetupState, 'bunInstallStatus' | 'launcherInstallStatus' | 'launcherInstallPath'>;
+    ...overrides,
+  };
+}
 
-test('waitForSetupCompletion resolves completed and cancelled states', async () => {
-  const sequence: Array<SetupState | null> = [
-    null,
-    {
-      version: 4,
-      status: 'in_progress',
-      completedAt: null,
-      completionSource: null,
-      yomitanSetupMode: null,
-      lastSeenYomitanDictionaryCount: 0,
-      pluginInstallStatus: 'unknown',
-      pluginInstallPathSummary: null,
-      windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-      windowsMpvShortcutLastStatus: 'unknown',
-      ...commandLineSetupDefaults,
-    },
-    {
-      version: 4,
+function completedState(overrides: Partial<SetupState> = {}): SetupState {
+  return makeState({
     status: 'completed',
     completedAt: '2026-03-07T00:00:00.000Z',
     completionSource: 'user',
     yomitanSetupMode: 'internal',
     lastSeenYomitanDictionaryCount: 1,
-      pluginInstallStatus: 'skipped',
-      pluginInstallPathSummary: null,
-      windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-      windowsMpvShortcutLastStatus: 'skipped',
-      ...commandLineSetupDefaults,
-    },
-  ];
+    ...overrides,
+  });
+}
 
-  const result = await waitForSetupCompletion({
-    readSetupState: () => sequence.shift() ?? null,
-    sleep: async () => undefined,
-    now: (() => {
+const cancelledState = () => makeState({ status: 'cancelled' });
+
+/** Deterministic clock: every `now()` advances 100ms and `sleep` returns immediately. */
+function fakeClock() {
   let value = 0;
-      return () => (value += 100);
-    })(),
+  return {
+    sleep: async () => undefined,
+    now: () => (value += 100),
     timeoutMs: 5_000,
     pollIntervalMs: 100,
+  };
+}
+
+/** Reader that serves `states` in order, then repeats the last one; counts its reads. */
+function sequenceReader(states: Array<SetupState | null>) {
+  const reader = {
+    reads: 0,
+    read: (): SetupState | null => states[Math.min(reader.reads++, states.length - 1)] ?? null,
+  };
+  return reader;
+}
+
+for (const c of [
+  { name: 'completed', last: completedState(), expected: 'completed' },
+  { name: 'cancelled', last: cancelledState(), expected: 'cancelled' },
+] as const) {
+  test(`waitForSetupCompletion resolves ${c.name} state after polling through earlier states`, async () => {
+    const reader = sequenceReader([null, makeState(), c.last]);
+
+    const result = await waitForSetupCompletion({
+      readSetupState: reader.read,
+      ...fakeClock(),
     });
 
-  assert.equal(result, 'completed');
+    assert.equal(result, c.expected);
+    assert.equal(reader.reads, 3);
   });
+}
 
 test('ensureLauncherSetupReady launches setup app and resumes only after completion', async () => {
   const calls: string[] = [];
-  let reads = 0;
+  const reader = sequenceReader([
+    null,
+    makeState(),
+    completedState({ pluginInstallStatus: 'installed', pluginInstallPathSummary: '/tmp/mpv' }),
+  ]);
 
   const ready = await ensureLauncherSetupReady({
-    readSetupState: () => {
-      reads += 1;
-      if (reads === 1) return null;
-      if (reads === 2) {
-        return {
-          version: 4,
-          status: 'in_progress',
-          completedAt: null,
-          completionSource: null,
-          yomitanSetupMode: null,
-          lastSeenYomitanDictionaryCount: 0,
-          pluginInstallStatus: 'unknown',
-          pluginInstallPathSummary: null,
-          windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-          windowsMpvShortcutLastStatus: 'unknown',
-          ...commandLineSetupDefaults,
-        };
-      }
-      return {
-        version: 4,
-        status: 'completed',
-        completedAt: '2026-03-07T00:00:00.000Z',
-        completionSource: 'user',
-        yomitanSetupMode: 'internal',
-        lastSeenYomitanDictionaryCount: 1,
-        pluginInstallStatus: 'installed',
-        pluginInstallPathSummary: '/tmp/mpv',
-        windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-        windowsMpvShortcutLastStatus: 'installed',
-        ...commandLineSetupDefaults,
-      };
-    },
+    readSetupState: reader.read,
     launchSetupApp: () => {
       calls.push('launch');
     },
-    sleep: async () => undefined,
-    now: (() => {
-      let value = 0;
-      return () => (value += 100);
-    })(),
-    timeoutMs: 5_000,
-    pollIntervalMs: 100,
+    ...fakeClock(),
   });
 
   assert.equal(ready, true);
@@ -120,10 +106,7 @@ test('ensureLauncherSetupReady bypasses setup gate when external yomitan is conf
     launchSetupApp: () => {
       calls.push('launch');
     },
-    sleep: async () => undefined,
-    now: () => 0,
-    timeoutMs: 5_000,
-    pollIntervalMs: 100,
+    ...fakeClock(),
   });
 
   assert.equal(ready, true);
@@ -133,76 +116,47 @@ test('ensureLauncherSetupReady bypasses setup gate when external yomitan is conf
 test('ensureLauncherSetupReady waits for finish after legacy mpv plugin removal', async () => {
   const calls: string[] = [];
   let legacyPluginInstalled = true;
-  let reads = 0;
-
-  const ready = await ensureLauncherSetupReady({
-    readSetupState: () => {
-      reads += 1;
-      return {
-        version: 4,
-        status: 'completed',
-        completedAt: reads < 3 ? '2026-03-07T00:00:00.000Z' : '2026-05-12T14:40:00.000Z',
-        completionSource: 'user',
+  // The completion timestamp moves forward once the setup app has finished.
+  const reader = sequenceReader([
+    completedState({ yomitanSetupMode: null, lastSeenYomitanDictionaryCount: 0 }),
+    completedState({ yomitanSetupMode: null, lastSeenYomitanDictionaryCount: 0 }),
+    completedState({
+      completedAt: '2026-05-12T14:40:00.000Z',
       yomitanSetupMode: null,
       lastSeenYomitanDictionaryCount: 0,
-        pluginInstallStatus: 'unknown',
-        pluginInstallPathSummary: null,
-        windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-        windowsMpvShortcutLastStatus: 'unknown',
-        ...commandLineSetupDefaults,
-      };
-    },
+    }),
+  ]);
+
+  const ready = await ensureLauncherSetupReady({
+    readSetupState: reader.read,
     hasLegacyMpvPlugin: () => legacyPluginInstalled,
     launchSetupApp: () => {
       calls.push('launch');
       legacyPluginInstalled = false;
     },
-    sleep: async () => undefined,
-    now: (() => {
-      let value = 0;
-      return () => (value += 100);
-    })(),
-    timeoutMs: 5_000,
-    pollIntervalMs: 100,
+    ...fakeClock(),
   });
 
   assert.equal(ready, true);
   assert.deepEqual(calls, ['launch']);
-  assert.equal(reads >= 3, true);
+  assert.equal(reader.reads >= 3, true);
 });
 
 test('ensureLauncherSetupReady lets users continue without removing a legacy mpv plugin', async () => {
   const calls: string[] = [];
-  let reads = 0;
+  const reader = sequenceReader([
+    completedState({ lastSeenYomitanDictionaryCount: 2 }),
+    completedState({ lastSeenYomitanDictionaryCount: 2 }),
+    completedState({ completedAt: '2026-05-12T14:30:00.000Z', lastSeenYomitanDictionaryCount: 2 }),
+  ]);
 
   const ready = await ensureLauncherSetupReady({
-    readSetupState: () => {
-      reads += 1;
-      return {
-        version: 4,
-        status: 'completed',
-        completedAt: reads < 3 ? '2026-03-07T00:00:00.000Z' : '2026-05-12T14:30:00.000Z',
-        completionSource: 'user',
-        yomitanSetupMode: 'internal',
-        lastSeenYomitanDictionaryCount: 2,
-        pluginInstallStatus: 'unknown',
-        pluginInstallPathSummary: null,
-        windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-        windowsMpvShortcutLastStatus: 'unknown',
-        ...commandLineSetupDefaults,
-      };
-    },
+    readSetupState: reader.read,
     hasLegacyMpvPlugin: () => true,
     launchSetupApp: () => {
       calls.push('launch');
     },
-    sleep: async () => undefined,
-    now: (() => {
-      let value = 0;
-      return () => (value += 100);
-    })(),
-    timeoutMs: 5_000,
-    pollIntervalMs: 100,
+    ...fakeClock(),
   });
 
   assert.equal(ready, true);
@@ -211,90 +165,30 @@ test('ensureLauncherSetupReady lets users continue without removing a legacy mpv
 
 test('ensureLauncherSetupReady fails on timeout/cancelled state', async () => {
   const result = await ensureLauncherSetupReady({
-    readSetupState: () => ({
-      version: 4,
-      status: 'cancelled',
-      completedAt: null,
-      completionSource: null,
-      yomitanSetupMode: null,
-      lastSeenYomitanDictionaryCount: 0,
-      pluginInstallStatus: 'unknown',
-      pluginInstallPathSummary: null,
-      windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-      windowsMpvShortcutLastStatus: 'unknown',
-      ...commandLineSetupDefaults,
-    }),
+    readSetupState: cancelledState,
     launchSetupApp: () => undefined,
-    sleep: async () => undefined,
-    now: (() => {
-      let value = 0;
-      return () => (value += 100);
-    })(),
-    timeoutMs: 5_000,
-    pollIntervalMs: 100,
+    ...fakeClock(),
   });
 
   assert.equal(result, false);
 });
 
 test('ensureLauncherSetupReady ignores stale cancelled state after launching setup app', async () => {
-  let reads = 0;
-
-  const result = await ensureLauncherSetupReady({
-    readSetupState: () => {
-      reads += 1;
-      if (reads <= 2) {
-        return {
-          version: 4,
-          status: 'cancelled',
-          completedAt: null,
-          completionSource: null,
-          yomitanSetupMode: null,
-          lastSeenYomitanDictionaryCount: 0,
-          pluginInstallStatus: 'unknown',
-          pluginInstallPathSummary: null,
-          windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-          windowsMpvShortcutLastStatus: 'unknown',
-          ...commandLineSetupDefaults,
-        };
-      }
-      if (reads === 3) {
-        return {
-          version: 4,
-          status: 'in_progress',
-          completedAt: null,
-          completionSource: null,
-          yomitanSetupMode: null,
-          lastSeenYomitanDictionaryCount: 0,
-          pluginInstallStatus: 'unknown',
-          pluginInstallPathSummary: null,
-          windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-          windowsMpvShortcutLastStatus: 'unknown',
-          ...commandLineSetupDefaults,
-        };
-      }
-      return {
-        version: 4,
-        status: 'completed',
-        completedAt: '2026-03-07T00:00:00.000Z',
+  const reader = sequenceReader([
+    cancelledState(),
+    cancelledState(),
+    makeState(),
+    completedState({
       completionSource: 'legacy_auto_detected',
-        yomitanSetupMode: 'internal',
-        lastSeenYomitanDictionaryCount: 1,
       pluginInstallStatus: 'installed',
       pluginInstallPathSummary: '/tmp/mpv',
-        windowsMpvShortcutPreferences: { startMenuEnabled: true, desktopEnabled: true },
-        windowsMpvShortcutLastStatus: 'unknown',
-        ...commandLineSetupDefaults,
-      };
-    },
+    }),
+  ]);
+
+  const result = await ensureLauncherSetupReady({
+    readSetupState: reader.read,
     launchSetupApp: () => undefined,
-    sleep: async () => undefined,
-    now: (() => {
-      let value = 0;
-      return () => (value += 100);
-    })(),
-    timeoutMs: 5_000,
-    pollIntervalMs: 100,
+    ...fakeClock(),
   });
 
   assert.equal(result, true);

launcher/smoke.e2e.test.ts

@@ -9,7 +9,6 @@ import {
   createDefaultSetupState,
   getDefaultConfigDir,
   getSetupStatePath,
-  readSetupState,
   writeSetupState,
 } from '../src/shared/setup-state.js';
 
@@ -407,23 +406,34 @@ setInterval(() => {}, 1000);
   };
 }
 
-test('launcher smoke fixture seeds completed setup state', () => {
-  const smokeCase = createSmokeCase('setup-state');
+/**
+ * Some sandboxes forbid binding unix sockets (EPERM). The fake mpv needs one, so these tests
+ * cannot pass there; probe once and skip them instead of weakening every assertion.
+ */
+function unixSocketsDenied(): boolean {
+  if (process.platform === 'win32') return false;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-sock-probe-'));
   try {
-    const configDir = getDefaultConfigDir({
-      xdgConfigHome: smokeCase.xdgConfigHome,
-      homeDir: smokeCase.homeDir,
-    });
-    const statePath = getSetupStatePath(configDir);
-
-    assert.equal(readSetupState(statePath)?.status, 'completed');
+    const probe = spawnSync(
+      process.execPath,
+      [
+        '-e',
+        `require('node:net').createServer().on('error', (e) => { process.stderr.write(String(e)); process.exit(1); }).listen(${JSON.stringify(path.join(dir, 's.sock'))}, function () { this.close(() => process.exit(0)); });`,
+      ],
+      { encoding: 'utf8', timeout: 5000 },
+    );
+    return probe.status !== 0 && /eperm|operation not permitted/i.test(probe.stderr);
   } finally {
-    fs.rmSync(smokeCase.root, { recursive: true, force: true });
-    fs.rmSync(smokeCase.socketDir, { recursive: true, force: true });
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
 }
-});
 
-test('launcher mpv status returns ready when socket is connectable', async () => {
+const skipWithoutUnixSockets = unixSocketsDenied() ? 'sandbox denies unix socket binding' : false;
+
+test(
+  'launcher mpv status returns ready when socket is connectable',
+  { skip: skipWithoutUnixSockets },
+  async () => {
     await withSmokeCase('mpv-status', async (smokeCase) => {
       const env = makeTestEnv(smokeCase);
       const fakeMpv = spawn(smokeCase.fakeMpvPath, [`--input-ipc-server=${smokeCase.socketPath}`], {
@@ -439,20 +449,8 @@ test('launcher mpv status returns ready when socket is connectable', async () =>
           env,
           'mpv-status',
         );
-      const fakeMpvEntries = readJsonLines(path.join(smokeCase.artifactsDir, 'fake-mpv.log'));
-      const fakeMpvError = fakeMpvEntries.find(
-        (entry): entry is { error: string } => typeof entry.error === 'string',
-      )?.error;
-      const unixSocketDenied =
-        typeof fakeMpvError === 'string' && /eperm|operation not permitted/i.test(fakeMpvError);
-
-      if (unixSocketDenied) {
-        assert.equal(result.status, 1);
-        assert.match(result.stdout, /socket not ready/i);
-      } else {
         assert.equal(result.status, 0);
         assert.match(result.stdout, /socket ready/i);
-      }
       } finally {
         if (fakeMpv.exitCode === null) {
           await new Promise<void>((resolve) => {
@@ -461,11 +459,12 @@ test('launcher mpv status returns ready when socket is connectable', async () =>
         }
       }
     });
-});
+  },
+);
 
 test(
   'launcher start-overlay run forwards socket/backend and stops owned background app after mpv exits',
-  { timeout: LONG_SMOKE_TEST_TIMEOUT_MS },
+  { timeout: LONG_SMOKE_TEST_TIMEOUT_MS, skip: skipWithoutUnixSockets },
   async () => {
     await withSmokeCase('overlay-start-stop', async (smokeCase) => {
       const env = makeTestEnv(smokeCase);
@@ -484,13 +483,8 @@ test(
       const appStartEntries = readJsonLines(appStartPath);
       const appStopEntries = readJsonLines(appStopPath);
       const mpvEntries = readJsonLines(path.join(smokeCase.artifactsDir, 'fake-mpv.log'));
-      const mpvError = mpvEntries.find(
-        (entry): entry is { error: string } => typeof entry.error === 'string',
-      )?.error;
-      const unixSocketDenied =
-        typeof mpvError === 'string' && /eperm|operation not permitted/i.test(mpvError);
 
-      assert.equal(result.status, unixSocketDenied ? 3 : 0);
+      assert.equal(result.status, 0);
       assert.match(result.stdout, /Starting SubMiner overlay/i);
 
       assert.equal(appStartEntries.length, 1);
@@ -523,7 +517,7 @@ test(
 
 test(
   'launcher start-overlay attaches to a running background app without spawning another app start command',
-  { timeout: LONG_SMOKE_TEST_TIMEOUT_MS },
+  { timeout: LONG_SMOKE_TEST_TIMEOUT_MS, skip: skipWithoutUnixSockets },
   async () => {
     await withSmokeCase('overlay-borrow-background', async (smokeCase) => {
       const controlServer = await startFakeControlServer(smokeCase);
@@ -550,13 +544,8 @@ test(
         const appStopEntries = readJsonLines(appStopPath);
         const controlEntries = readJsonLines(controlServer.logPath);
         const mpvEntries = readJsonLines(path.join(smokeCase.artifactsDir, 'fake-mpv.log'));
-        const mpvError = mpvEntries.find(
-          (entry): entry is { error: string } => typeof entry.error === 'string',
-        )?.error;
-        const unixSocketDenied =
-          typeof mpvError === 'string' && /eperm|operation not permitted/i.test(mpvError);
 
-        assert.equal(result.status, unixSocketDenied ? 3 : 0);
+        assert.equal(result.status, 0);
         if (process.platform === 'linux') {
           assert.equal(appEntries.length > 0, true);
           assert.equal(
@@ -583,7 +572,7 @@ test(
 
 test(
   'launcher starts mpv paused when plugin auto-start visible overlay gate is enabled',
-  { timeout: LONG_SMOKE_TEST_TIMEOUT_MS },
+  { timeout: LONG_SMOKE_TEST_TIMEOUT_MS, skip: skipWithoutUnixSockets },
   async () => {
     await withSmokeCase('autoplay-ready-gate', async (smokeCase) => {
       fs.writeFileSync(
@@ -607,14 +596,9 @@ test(
       );
 
       const mpvEntries = readJsonLines(path.join(smokeCase.artifactsDir, 'fake-mpv.log'));
-      const mpvError = mpvEntries.find(
-        (entry): entry is { error: string } => typeof entry.error === 'string',
-      )?.error;
-      const unixSocketDenied =
-        typeof mpvError === 'string' && /eperm|operation not permitted/i.test(mpvError);
       const mpvFirstArgs = mpvEntries[0]?.argv;
 
-      assert.equal(result.status, unixSocketDenied ? 3 : 0);
+      assert.equal(result.status, 0);
       assert.equal(Array.isArray(mpvFirstArgs), true);
       assert.equal((mpvFirstArgs as string[]).includes('--pause=yes'), true);
       assert.match(

launcher/test-support/args.ts

@@ -0,0 +1,7 @@
+import { parseArgs } from '../config.js';
+import type { Args } from '../types.js';
+
+/** Default launcher `Args` (as if run with no CLI input), with `overrides` applied. */
+export function makeLauncherArgs(overrides: Partial<Args> = {}): Args {
+  return { ...parseArgs([], 'subminer', {}), ...overrides };
+}

launcher/test-support/env.ts

@@ -0,0 +1,25 @@
+/**
+ * Runs `run` with the given process env values (`undefined` deletes a key) and restores the
+ * originals afterwards, even if `run` throws or rejects.
+ */
+export async function withEnv<T>(
+  overrides: Record<string, string | undefined>,
+  run: () => T | Promise<T>,
+): Promise<T> {
+  const originals = Object.fromEntries(
+    Object.keys(overrides).map((key) => [key, process.env[key]]),
+  );
+  const apply = (values: Record<string, string | undefined>): void => {
+    for (const [key, value] of Object.entries(values)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  };
+
+  apply(overrides);
+  try {
+    return await run();
+  } finally {
+    apply(originals);
+  }
+}

launcher/test-support/immersion-db-schema.test.ts

@@ -5,7 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { Database as BunDatabase } from 'bun:sqlite';
 import { ensureSchema } from '../../src/core/services/immersion-tracker/storage.js';
-import { createImmersionDbFixture, insertFixtureSession } from './immersion-db-fixture.js';
+import { createImmersionDbFixture } from './immersion-db-fixture.js';
 
 type SchemaRow = { type: string; name: string; tbl_name: string; sql: string | null };
 
@@ -108,65 +108,3 @@ test('fixture schema stays aligned with production sync-touched tables and index
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
-
-test('fixture leaves lexical rollups pending when their table is absent', () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-fixture-rollup-state-'));
-  const fixturePath = path.join(dir, 'fixture.sqlite');
-  try {
-    createImmersionDbFixture(fixturePath);
-    const db = new BunDatabase(fixturePath, { readonly: true });
-    try {
-      const state = db
-        .query<{ state_value: string }>(
-          `SELECT state_value FROM imm_rollup_state
-           WHERE state_key = 'lexical_daily_rollups_version'`,
-        )
-        .get();
-      const rollupTable = db
-        .query<{ name: string }>(
-          `SELECT name FROM sqlite_schema
-           WHERE type = 'table' AND name = 'imm_lexical_daily_rollups'`,
-        )
-        .get();
-
-      assert.equal(state?.state_value, '0');
-      assert.equal(rollupTable, null);
-    } finally {
-      db.close();
-    }
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('fixture session inserts enforce foreign keys', () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-fixture-foreign-keys-'));
-  const fixturePath = path.join(dir, 'fixture.sqlite');
-  try {
-    createImmersionDbFixture(fixturePath);
-    const db = new BunDatabase(fixturePath, { readwrite: true });
-    try {
-      db.run(`
-        CREATE TRIGGER remove_fixture_video
-        BEFORE INSERT ON imm_sessions
-        BEGIN
-          DELETE FROM imm_videos WHERE video_id = NEW.video_id;
-        END
-      `);
-    } finally {
-      db.close();
-    }
-
-    assert.throws(
-      () =>
-        insertFixtureSession(fixturePath, {
-          uuid: 'foreign-key-check',
-          videoKey: 'foreign-key-check',
-          startedAtMs: Date.UTC(2026, 6, 9),
-        }),
-      /FOREIGN KEY constraint failed/,
-    );
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.20.1-beta.1",
+  "version": "0.20.1",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",

release/prerelease-notes.md

@@ -1,73 +1,76 @@
 > This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.
 
-<!-- prerelease-version: 0.20.1-beta.1 -->
+<!-- prerelease-version: 0.20.1-beta.2; since: v0.20.1-beta.1 -->
+
+## Changes since v0.20.1-beta.1
+
+- Upgraded the desktop runtime to Electron 43.7.7.
+- SubMiner now refuses to start on an unsupported Electron runtime, or after an Electron major or minor downgrade, so your Yomitan profile data stays safe; patch downgrades are still allowed.
+- Automatic character-dictionary updates now stop if a Yomitan profile that had dictionaries suddenly reports none.
+- Development launches now use a separate `SubMiner-dev` profile unless you explicitly ask for the production profile.
+- Sentence mining (single and multi-line) no longer counts each card twice in session and lifetime stats.
+- Deleting sessions now updates word and kanji "first seen" and "last seen" dates correctly, and retention pruning keeps historical discovery dates and counts.
+- Words hidden by the vocabulary filter are no longer counted in the new-words charts, so the charts now match the vocabulary summary.
+- A one-time background repair on next launch fixes stale "last seen" dates and existing chart mismatches.
+- Overview totals, charts, the activity calendar, and the vocabulary summary now refresh after you delete sessions, and a failed refresh keeps the dashboard visible with a retry option.
+- Subtitle generation now works during Windows YouTube playback and loads the generated subtitles into the playing video.
+- On Windows, moving on to a video queued from the YouTube browser window no longer drops the rest of mpv's queue.
+- The stats docs now cover the automatic Overview refresh after deletions and how discovery dates are kept through retention pruning.
 
 ## Highlights
-
 ### Added
 
 - **YouTube Browser Window**:
-  - Open a YouTube browser with `subminer youtube` (or `subminer yt`), or pick **Browse YouTube** from the tray. It stays logged in to YouTube across restarts.
-  - Clicking a video plays it in mpv instead of on the page.
-  - Middle-click, Shift-click, Ctrl-click, or the right-click menu adds a video to mpv's playlist.
-  - When a queued video starts, it gets the same Japanese subtitle setup.
-  - If you started SubMiner with `subminer youtube`, closing the YouTube window quits SubMiner. If a video is still playing, SubMiner quits after mpv closes.
+  - Open it with `subminer youtube` (or `subminer yt`), or pick **Browse YouTube** from the tray. It stays logged in across restarts.
+  - Clicking a video plays it in mpv. Middle-click, Shift-click, Ctrl-click, or the right-click menu adds it to mpv's playlist.
+  - Queued videos get the same Japanese subtitle setup when they start.
+  - Closing the window quits SubMiner if you started it with `subminer youtube`. If a video is still playing, SubMiner waits until mpv closes.
 - **Whisper Subtitles for YouTube**:
-  - Set `youtube.subtitleSource` to `whisper` to make subtitles with Whisper instead of downloading YouTube's captions. The default is still `youtube`.
-  - The video stays paused while Whisper works, and progress shows in the subtitle generation modal. Close the modal to keep watching, or cancel to carry on without subtitles.
-  - The subtitle generation modal (`Ctrl+Shift+G`) now works on YouTube videos with either `youtube.subtitleSource` setting.
-  - Whisper downloads only a small audio stream and deletes it when generation ends, or when you switch videos, close mpv, or quit.
+  - Set `youtube.subtitleSource` to `whisper` to make subtitles with Whisper instead of downloading YouTube's captions.
+  - The video stays paused while Whisper works, and progress shows in the subtitle generation modal. You can close the modal to keep watching, or cancel.
+  - The subtitle generation modal (`Ctrl+Shift+G`) now works on YouTube videos, including on Windows.
 - **Mouse and Scroll Wheel Bindings**:
-  - `keybindings` now accepts scroll wheel keys (`WHEEL_UP`, `WHEEL_DOWN`, `WHEEL_LEFT`, `WHEEL_RIGHT`), with or without modifiers. You can also record them in the settings key editor.
-  - Mouse button and scroll wheel bindings from mpv now work while the cursor is over the overlay. This covers your `input.conf` and mpv's defaults, such as double-click for fullscreen, the wheel for volume, and back/forward for the playlist.
-  - Hyprland users benefit most: the overlay always takes input there, so these bindings did nothing before.
-  - SubMiner's own bindings and right-click pause still win over mpv's.
-- **Session Help Commands**:
-  - During playback, press `Enter` or double-click a row in session help to run that command.
-  - Hovering over a row makes it the target for `Enter`.
-  - Session help opened from the tray with no video loaded is still read-only.
+  - You can now use scroll wheel keys (`WHEEL_UP`, `WHEEL_DOWN`, `WHEEL_LEFT`, `WHEEL_RIGHT`) in `keybindings` and record them in the settings key editor.
+  - mpv's mouse button and wheel bindings now work while the cursor is over the overlay. This matters most on Hyprland, where these bindings did nothing before.
+  - When a binding conflicts, SubMiner's own bindings and right-click pause take priority over mpv's.
+- **Session Help Commands**: During playback, press `Enter` or double-click a row in session help to run that command. Hovering over a row makes it the target for `Enter`.
 
 ### Changed
 
-- **Release Assets**: Releases no longer include package-size JSON reports. Package contents are still validated before release.
+- **Release Assets**: Releases no longer include package-size JSON reports.
 
 ### Fixed
 
 - **Jellyfin Subtitles**:
-  - The Japanese subtitle track is selected, and annotations start, as soon as that track downloads. SubMiner no longer waits for every other track.
-  - Subtitle tracks now download in parallel, so a slow embedded track no longer holds up the main subtitles.
-  - Episodes with image-based subtitles (PGS, DVD, DVB) now select the Japanese and English tracks automatically.
-  - If one subtitle track fails to download, the other tracks are still selected.
-- **Jellyfin Audio Track**: On direct-play Jellyfin streams, timing review previews and mined card audio now use the audio track you're playing, not the one Jellyfin marks as default.
+  - The Japanese track is selected, and annotations start, as soon as it downloads. SubMiner no longer waits for the other tracks.
+  - Japanese and English tracks are now picked automatically on episodes with image-based subtitles (PGS, DVD, DVB).
+  - If one track fails to download, the other tracks are still selected.
+- **Jellyfin Audio Track**: On direct-play streams, timing review previews and mined card audio now use the audio track you're playing.
 - **Media Timing Review**:
-  - Trim handles are now thin lines centered on the clip edges. The start and end of the clip are easier to see, and less of the waveform is hidden.
-  - The original subtitle boundaries are now plain orange bars without text labels, so the waveform stays visible.
-  - On macOS with Bluetooth headphones such as AirPods, the preview cursor now moves smoothly. Before, it stuttered and jumped to the end partway through. This affected Opus audio, including Jellyfin streams.
-- **Hyprland Fullscreen**:
-  - The subtitle overlay now stays visible when mpv enters or leaves fullscreen, so focus changes no longer cancel fullscreen. Sway still refreshes the overlay as before.
-  - With `mpv.backend: x11`, subtitles and the sidebar no longer stop responding to clicks after mpv goes fullscreen.
-- **mpv Key Bindings in the Overlay**:
-  - mpv key bindings, such as `9`/`0` for volume, now work while the overlay has focus.
-  - They used to do nothing if the overlay loaded before SubMiner connected to mpv, which was common with `mpv.backend: x11`. The overlay now reloads mpv's bindings once mpv connects.
-- **YouTube Japanese Subtitles**:
-  - Some videos also list a machine-translated Japanese track. On those, Japanese subtitles no longer fail with "HTTP 429", because SubMiner now picks the real Japanese track.
-  - If YouTube refuses a direct subtitle download, SubMiner retries with yt-dlp.
-- **AppImage in Sandboxes**: The AppImage now opens its window when started in a sandbox that mounts the image itself, such as `firejail --appimage`. Before, it exited without opening a window.
-- **Ctrl+C Crash**: Stopping the terminal command that started SubMiner with Ctrl+C no longer crashes SubMiner with a "write EPIPE" error.
-- **Security Updates**: Electron is updated to 42.10.0 and undici to 7.29.1 to fix known security advisories.
+  - Trim handles are now thin lines centered on the clip edges.
+  - Original subtitle boundaries are now plain orange bars with no labels.
+  - The preview cursor no longer stutters on macOS with Bluetooth headphones such as AirPods.
+- **Hyprland Fullscreen**: The overlay stays visible when mpv enters or leaves fullscreen. With `mpv.backend: x11`, subtitles and the sidebar stay clickable after going fullscreen.
+- **mpv Key Bindings in the Overlay**: mpv key bindings, such as `9`/`0` for volume, now work while the overlay has focus, even when the overlay loaded before mpv connected.
+- **YouTube Japanese Subtitles**: Some videos also list a machine-translated Japanese track. On those, Japanese subtitles no longer fail with "HTTP 429". If YouTube refuses a direct download, SubMiner retries with yt-dlp.
+- **Stats Accuracy**:
+  - Sentence mining no longer counts each card twice in session and lifetime stats.
+  - Overview totals, charts, the activity calendar, and the vocabulary summary now update after you delete sessions.
+  - Word and kanji dates stay correct after deleting sessions. New-word charts now match the vocabulary summary.
+- **Dictionary Safety**: Automatic character dictionary changes now stop if a Yomitan profile that had dictionaries suddenly reports none. SubMiner also refuses to load Yomitan data after a downgrade to an older Electron version.
+- **AppImage in Sandboxes**: The AppImage now opens its window in sandboxes that mount the image themselves, such as `firejail --appimage`.
+- **Ctrl+C Crash**: Stopping the terminal command that started SubMiner with Ctrl+C no longer crashes it with a "write EPIPE" error.
+- **Security Updates**: Electron is updated to 43.7.7 and undici to 7.29.1, which fixes known security advisories.
 
 ### Docs
 
-- **Docs Site Rewrite**:
-  - Pages are shorter and easier to scan. Each one starts with setup and usage, and reference details are in compact tables.
-  - The configuration reference now gives each config block a short explanation and a table of keys and defaults.
-  - Pages that no longer matched how SubMiner works have been corrected.
-- **Arch Linux Install**:
-  - The MeCab install command is fixed. MeCab is only in the AUR, as `mecab-git`.
-  - The README's requirements and quick start now match the installation guide.
+- **Docs Site Rewrite**: Pages are shorter and easier to scan. The configuration reference now has a short explanation and a table of keys and defaults for each config block. Pages that no longer matched current behavior are fixed.
+- **Arch Linux Install**: The MeCab install command now uses the AUR package `mecab-git`. The README now matches the installation guide.
+- **Stats**: The docs now cover the Overview refreshing after you delete sessions, and how first-seen dates are kept when old sessions are cleaned up.
 
 ## What's Changed
 
+- fix(storage): protect Yomitan profiles across Electron runtime changes by @ksyasuda in #211
 - fix(jellyfin): select subtitles faster and survive failed track downloads by @ksyasuda in #270
 - fix(jellyfin): use the current audio track for media generation by @ksyasuda in #271
 - feat(youtube): add YouTube browser window and Whisper subtitle source by @ksyasuda in #273
@@ -77,14 +80,17 @@
 - fix(linux): skip AppImage mount keepalive on sandbox squashfs mounts by @ksyasuda in #277
 - fix(overlay): reload imported mpv keys after mpv connects by @ksyasuda in #278
 - feat(overlay): forward mpv mouse button and wheel bindings by @ksyasuda in #279
+- fix(stats): count mined cards once and keep lexical stats exact after deletes by @ksyasuda in #280
+- fix(youtube): keep mpv queue when advancing to a queued video on Windows by @ksyasuda in #281
+- fix(subtitles): allow Whisper generation during Windows YouTube stream playback by @ksyasuda in #282
 
 ## Installation
 
-See the [installation guide](https://docs.subminer.moe/installation) for full setup steps.
+See the README and docs/installation guide for full setup steps.
 
 ## Assets
 
-- Linux: `SubMiner-*.AppImage`
+- Linux: `SubMiner.AppImage`
 - macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
 - Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
 - Optional extras: `subminer-assets.tar.gz`, the `subminer` launcher, and the Windows `subminer.cmd` launcher

release/release-notes.md

@@ -0,0 +1,66 @@
+## Highlights
+### Added
+- **YouTube Browser Window**:
+  - Browse YouTube in a window that keeps your login across restarts. Open it with `subminer youtube` (or `subminer yt`), or choose **Browse YouTube** from the tray.
+  - Clicking a video plays it in mpv. Middle-click, Shift/Ctrl-click, or the right-click menu adds it to mpv's playlist.
+  - Queued videos get the same Japanese subtitle setup when they start playing.
+- **Whisper Subtitles for YouTube**: Set `youtube.subtitleSource` to `whisper` to transcribe YouTube videos with Whisper instead of using YouTube's captions. The subtitle generation modal (`Ctrl+Shift+G`) now also works on YouTube videos.
+- **Scroll Wheel and Mouse Bindings**: `keybindings` now accepts scroll wheel keys, and the settings key editor can capture them. Mouse button and wheel bindings from mpv now work while the cursor is over the overlay.
+- **Run Commands From Session Help**: Press `Enter` or double-click a row in session help to run that command during playback.
+
+### Fixed
+- **YouTube**:
+  - Japanese subtitles no longer fail with "HTTP 429" on videos that also have a machine-translated Japanese track.
+  - On Windows, the subtitle generation modal now works during YouTube playback.
+  - On Windows, playing a video queued from the YouTube browser window no longer clears the rest of mpv's queue.
+- **Jellyfin**:
+  - The Japanese subtitle track is selected as soon as it downloads, instead of waiting for every other track.
+  - Japanese and English image-based subtitles (PGS, DVD, DVB) are now selected automatically.
+  - Timing review previews and mined card audio use the audio track you are playing.
+- **Hyprland Overlay**: The overlay no longer interrupts mpv when it goes fullscreen. With `mpv.backend: x11`, the overlay stays clickable after mpv goes fullscreen.
+- **mpv Key Bindings**: Keys from mpv's defaults and your `input.conf` (such as `9` and `0` for volume) now work while the overlay has focus, even when the overlay loads before SubMiner connects to mpv.
+- **Media Timing Review**: Trim handles are now thin lines on the clip edges, and the original subtitle boundaries are plain orange bars. On macOS with Bluetooth headphones such as AirPods, the preview cursor now moves smoothly.
+- **Stats**:
+  - Each mined card is counted once instead of twice.
+  - Overview totals, charts, the calendar, and the vocabulary summary update right after you delete sessions.
+  - Word and kanji dates stay correct after deletes and pruning, and the new-words charts now agree with the vocabulary summary. Existing data is repaired in the background on the next launch.
+- **Yomitan Profile Safety**: Electron is updated to 43.7.7, and SubMiner now refuses to load your Yomitan data with an older or unsupported runtime. Automatic character-dictionary updates stop if a profile that had dictionaries suddenly reports none.
+- **Security Updates**: Updated Electron and undici to resolve security advisories.
+- **AppImage in Sandboxes**: The AppImage now opens a window when launched inside a sandbox such as `firejail --appimage`.
+- **Ctrl+C Crash**: SubMiner no longer crashes with "write EPIPE" when you stop the terminal command that started it with Ctrl+C.
+
+### Docs
+- **Docs Site**: The docs site is shorter and easier to scan, and the configuration reference now has a table of keys and defaults for each section. Outdated pages were corrected, and the Arch Linux MeCab install now uses the AUR package `mecab-git`.
+- **Stats**: Added docs on how the Overview refreshes after you delete sessions and how discovery dates are kept after pruning.
+
+## What's Changed
+
+- fix(storage): protect Yomitan profiles across Electron runtime changes by @ksyasuda in #211
+- fix(jellyfin): select subtitles faster and survive failed track downloads by @ksyasuda in #270
+- fix(jellyfin): use the current audio track for media generation by @ksyasuda in #271
+- feat(youtube): add YouTube browser window and Whisper subtitle source by @ksyasuda in #273
+- fix(overlay): thin centered trim handles and label-free subtitle boundaries in timing review by @ksyasuda in #274
+- feat(overlay): run session help commands with Enter or double-click by @ksyasuda in #275
+- fix(overlay): keep overlay mapped during Hyprland/Sway fullscreen by @ksyasuda in #276
+- fix(linux): skip AppImage mount keepalive on sandbox squashfs mounts by @ksyasuda in #277
+- fix(overlay): reload imported mpv keys after mpv connects by @ksyasuda in #278
+- feat(overlay): forward mpv mouse button and wheel bindings by @ksyasuda in #279
+- fix(stats): count mined cards once and keep lexical stats exact after deletes by @ksyasuda in #280
+- fix(youtube): keep mpv queue when advancing to a queued video on Windows by @ksyasuda in #281
+- fix(subtitles): allow Whisper generation during Windows YouTube stream playback by @ksyasuda in #282
+
+## Installation
+
+See the README and docs/installation guide for full setup steps.
+
+## Assets
+
+- Linux: `SubMiner.AppImage`
+- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
+- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
+- Optional extras: `subminer-assets.tar.gz`, the `subminer` launcher, and the Windows `subminer.cmd` launcher
+- Bun corresponding source: `bun-v1.3.5-source.tar.gz` and its `.sha256` file
+
+Both launcher downloads use Bun included with the SubMiner app. Download `subminer` on Linux or macOS and `subminer.cmd` on Windows.
+
+The app bundles an unmodified Bun 1.3.5 runtime. Bun is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). License texts and third-party notices ship inside the app under `resources/bun/licenses`, and the source archive above contains the matching Bun, WebKit, and dependency sources for relinking.

scripts/build-changelog.ts

@@ -476,21 +476,29 @@ You will receive a list of FRAGMENT entries below. Each fragment has metadata (t
 
    </details>
    Do not include the Internal section at all in MODE: release-notes; internal fragments will not be present in the input for that mode.
-4. Each top-level change item should:
-   - Lead with a short feature/area name in title case. Pick the name from the fragment's bullet content, not the raw 'area:' slug.
-   - Be written in user-facing language. Drop implementation jargon, internal class names, file paths, and PR numbers.
-   - Be merged with related bullets when possible. If five fragments all touch Windows overlay z-order/focus/restore, write one or two bullets that summarize the overall improvement instead of five.
+4. Start every item with a short bold feature/area name in title case and a colon. Pick the name from the fragment's bullet content, not the raw 'area:' slug.
+   - Default to inline: put one or two short sentences right after the colon. If the important details fit in two short sentences, stay inline.
+   - Use nested bullets only when an item has several distinct changes a user would care about separately and inline text would turn into a long run-on sentence. Then leave the top-level bullet as just the name and indent two to four nested bullets by two spaces.
+   - Each nested bullet is a single short sentence, roughly 20 words or fewer. Never write paragraph-length bullets. Cut minor details rather than adding sentences.
+5. Keep items brief. Release notes summarize; the docs hold the details.
+   - Say what changed for the user and how to reach it (shortcut, command, setting, or menu). Stop there.
+   - Leave out how it works internally, edge cases, precedence rules, defaults, fallbacks, tool discovery, migration mechanics, and step-by-step usage.
+   - Name a config key only when users must set it to use the change or to keep their current behavior.
+   - Write in user-facing language. Drop implementation jargon, internal class names, file paths, and PR numbers.
+   - Merge aggressively: one item per feature or area. If five fragments touch Jellyfin subtitles, audio, and auth, write one Jellyfin item, not five. Group small unrelated fixes for the same area into one item.
    - Drop bullets that only describe PR housekeeping, CodeRabbit follow-ups, or test-only changes that don't affect users.
-   - Preserve the substance of breaking changes that remain breaking after applying the Release Outcome Rules. Do not soften or omit them.
-5. In both modes, split every item into one nested bullet per distinct change. Write a short bold name on the top-level bullet, then indent the details two spaces:
-   - **Playlist Browser**:
-     - Saved shows now open without rescanning the library.
-     - The picker remembers the last folder you browsed between launches.
-   Each nested bullet covers exactly one change, behavior, or user-visible outcome. Never stack several distinct changes into one long paragraph-shaped bullet.
-   Aim for two to five nested bullets per item. When an item genuinely has only one thing to say, put it inline on the top-level bullet ("- **Playlist Browser**: Saved shows now open without rescanning the library.") instead of emitting a single nested bullet.
-   Keep nested bullets short, concrete, and readable by non-technical users. Avoid paragraph-style release-note bullets.
-   Bullets inside the Internal section may stay single-level.
-6. In MODE: release-notes, nested bullets should also cover user benefit and any user action or compatibility note when useful. Do not require the exact nested labels; natural phrasing is fine. Omit the action bullet when no action is needed.
+   - Preserve the substance of breaking changes that remain breaking after applying the Release Outcome Rules, including any action users must take. Do not soften or omit them.
+6. Match the length and density of this example:
+   ### Added
+   - **Subtitle Selection Modal**: Optional modal for picking primary and secondary subtitle tracks. Enable it in Settings under Behavior, then press g followed by s.
+   ### Changed
+   - **Faster Sync**: Sync between macOS and Linux machines now uses compressed, incremental rsync transfers. Windows and machines without rsync fall back to compressed scp.
+   ### Fixed
+   - **Subtitle Sidebar**: Space keeps its playback action after clicking a cue, and the sidebar no longer jumps away from the current position during subtitle gaps.
+   - **Jellyfin 12**:
+     - Playback, subtitles, artwork, and "Play on SubMiner" now work on Jellyfin 12.
+     - Casting no longer drops after about a minute.
+     - Mined cards get the episode title again.
 7. Do not invent features. Every bullet must be grounded in the input fragments.
 8. Do not include the version heading (## v...) — that wrapper is added by the caller.
 
@@ -791,7 +799,7 @@ function polishFragmentsWithClaude(
     ? [
         '## Existing Prerelease Notes',
         '',
-        'The input includes EXISTING PRERELEASE NOTES before the fragment list. Existing prerelease notes are a baseline, not an immutable changelog. Reuse reviewed highlight bullets when they still describe the current outcome, but replace stale beta or RC wording when new fragments supersede it. Merge in only new or changed fragment material, and deduplicate instead of restating existing bullets. Output only the final highlights body using the section headings above; do not include the prerelease disclaimer, any "Changes since" section, or the Installation or Assets sections.',
+        'The input includes EXISTING PRERELEASE NOTES before the fragment list. Existing prerelease notes are a baseline, not an immutable changelog. Reuse reviewed highlight bullets when they still describe the current outcome, but replace stale beta or RC wording when new fragments supersede it. Merge in only new or changed fragment material, and deduplicate instead of restating existing bullets. The output rules above win over the baseline format: shorten long baseline bullets and collapse nested lists that do not need to be nested. Output only the final highlights body using the section headings above; do not include the prerelease disclaimer, any "Changes since" section, or the Installation or Assets sections.',
         '',
       ].join('\n')
     : '';
@@ -814,7 +822,7 @@ Rules:
 3. ADDED fragments describe changes that are new in this build; summarize them.
 4. MODIFIED fragments include BEFORE and AFTER content. Describe only the behavioral difference between them. If the edit is editorial (rewording, deduplication, reformatting, reconciling stale phrasing) with no user-visible behavior change, omit it entirely.
 5. DELETED fragments mean the described change was removed or reverted before this build; say so explicitly.
-6. Keep bullets short and concrete. Use nested bullets sparingly.
+6. Keep each bullet to one short, concrete sentence. Use nested bullets sparingly.
 7. Do not invent changes. Every bullet must be grounded in the diffs.
 8. If no bullet survives rules 2-5, output exactly this single line:
    - No user-facing changes since PREVIOUS_TAG.

scripts/compare-yomitan-api.test.ts

@@ -1,26 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import test from 'node:test';
-
-const source = readFileSync('scripts/compare-yomitan-api.ts', 'utf8');
-
-test('creates the configured Yomitan user-data directory before Electron uses it', () => {
-  const setPathIndex = source.indexOf(
-    "electronModule.app.setPath('userData', options.yomitanUserDataPath)",
-  );
-  assert.notEqual(setPathIndex, -1);
-
-  const mkdirIndex = source.lastIndexOf(
-    'fs.mkdirSync(options.yomitanUserDataPath, { recursive: true })',
-    setPathIndex,
-  );
-  assert.ok(mkdirIndex > -1, 'must create the user-data directory');
-  assert.ok(mkdirIndex < setPathIndex, 'must create the directory before app.setPath');
-});
-
-test('lets output drain by using exitCode in the top-level completion handlers', () => {
-  const completionHandlers = source.slice(source.lastIndexOf('\nmain()'));
-  assert.match(completionHandlers, /process\.exitCode = process\.exitCode \?\? 0/);
-  assert.match(completionHandlers, /process\.exitCode = 1/);
-  assert.doesNotMatch(completionHandlers, /process\.exit\(/);
-});

scripts/docs-knowledge-base.test.ts

@@ -21,6 +21,7 @@ const requiredDocs = [
   'docs/workflow/README.md',
   'docs/workflow/agent-skills.md',
   'docs/workflow/planning.md',
+  'docs/workflow/testing.md',
   'docs/workflow/verification.md',
 ] as const;
 

scripts/get-mpv-window-macos.test.ts

@@ -1,94 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import test from 'node:test';
-
-const source = readFileSync('scripts/get-mpv-window-macos.swift', 'utf8');
-
-test('minimized Accessibility windows are validated by PID and socket before reporting minimized', () => {
-  const minimizedAssignmentIndex = source.indexOf('foundMinimizedTargetWindow = true');
-  assert.notEqual(minimizedAssignmentIndex, -1);
-
-  const loopStartIndex = source.lastIndexOf('for window in windows', minimizedAssignmentIndex);
-  assert.notEqual(loopStartIndex, -1);
-
-  const pidExtractionIndex = source.indexOf(
-    'AXUIElementGetPid(window, &windowPid)',
-    loopStartIndex,
-  );
-  const appPidMatchIndex = source.indexOf('windowPid != app.processIdentifier', loopStartIndex);
-  const socketCheckIndex = source.indexOf('if !windowHasTargetSocket(windowPid)', loopStartIndex);
-
-  assert.ok(
-    pidExtractionIndex > loopStartIndex && pidExtractionIndex < minimizedAssignmentIndex,
-    'window PID must be extracted before accepting a minimized window',
-  );
-  assert.ok(
-    appPidMatchIndex > pidExtractionIndex && appPidMatchIndex < minimizedAssignmentIndex,
-    'window PID must match the owning app before accepting a minimized window',
-  );
-  assert.ok(
-    socketCheckIndex > appPidMatchIndex && socketCheckIndex < minimizedAssignmentIndex,
-    'target socket must be validated before accepting a minimized window',
-  );
-});
-
-test('focused mpv window follows the frontmost mpv app signal', () => {
-  const focusHelperIndex = source.indexOf('private func isFocusedMpvWindow');
-  assert.notEqual(focusHelperIndex, -1);
-
-  const nextFunctionIndex = source.indexOf('\nprivate func ', focusHelperIndex + 1);
-  const focusHelperBody = source.slice(focusHelperIndex, nextFunctionIndex);
-
-  assert.ok(
-    focusHelperBody.includes('frontmost.pid == ownerPid'),
-    'matching frontmost PID should mark the mpv window focused',
-  );
-  assert.ok(
-    focusHelperBody.includes('frontmost.isMpv && windowHasTargetSocket(ownerPid)'),
-    'frontmost mpv app should mark the target mpv window focused even when PIDs differ',
-  );
-  assert.ok(
-    source.includes('focused: isFocusedMpvWindow(ownerPid: windowPid, frontmost: frontmost)'),
-    'Accessibility path should use the shared focused mpv helper',
-  );
-  assert.ok(
-    source.includes('focused: isFocusedMpvWindow(ownerPid: ownerPid, frontmost: frontmost)'),
-    'CoreGraphics path should use the shared focused mpv helper',
-  );
-});
-
-test('frontmost mpv app emits active state when geometry lookup misses', () => {
-  assert.ok(
-    /case\s+\.active:/.test(source),
-    'helper should expose an active state without window geometry',
-  );
-  assert.ok(
-    source.includes('if windowHasTargetSocket(frontmost.pid)'),
-    'active state should still accept a matching target socket when available',
-  );
-  assert.ok(
-    source.includes('return targetMpvSocketPath != nil'),
-    'active state should preserve frontmost mpv even if command-line socket detection fails',
-  );
-  assert.ok(
-    source.includes('return .active'),
-    'lookup should preserve active mpv state after geometry lookup misses',
-  );
-  assert.ok(source.includes('print("active")'), 'active state should be printed for the tracker');
-});
-
-test('frontmost non-mpv app emits inactive state when geometry lookup misses', () => {
-  assert.ok(
-    /case\s+\.inactive:/.test(source),
-    'helper should expose an inactive state without window geometry',
-  );
-  assert.ok(
-    source.includes('if frontmost != nil'),
-    'helper should distinguish a known non-mpv frontmost app from an unknown miss',
-  );
-  assert.ok(source.includes('return .inactive'), 'known non-mpv focus should return inactive');
-  assert.ok(
-    source.includes('print("inactive")'),
-    'inactive state should be printed for the tracker',
-  );
-});

scripts/get_frequency.test.ts

@@ -1,45 +0,0 @@
-import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import path from 'node:path';
-import test from 'node:test';
-import { spawnSync } from 'node:child_process';
-
-function createWorkspace(name: string): string {
-  const baseDir = path.join(process.cwd(), '.tmp', 'get-frequency-typecheck-test');
-  fs.mkdirSync(baseDir, { recursive: true });
-  return fs.mkdtempSync(path.join(baseDir, `${name}-`));
-}
-
-test('scripts/get_frequency.ts typechecks in isolation', () => {
-  const workspace = createWorkspace('isolated-script');
-  const tsconfigPath = path.join(workspace, 'tsconfig.json');
-
-  fs.writeFileSync(
-    tsconfigPath,
-    JSON.stringify(
-      {
-        extends: '../../../tsconfig.typecheck.json',
-        include: ['../../../scripts/get_frequency.ts'],
-        exclude: [],
-      },
-      null,
-      2,
-    ),
-    'utf8',
-  );
-
-  try {
-    const result = spawnSync('bunx', ['tsc', '--noEmit', '-p', tsconfigPath], {
-      cwd: process.cwd(),
-      encoding: 'utf8',
-    });
-
-    assert.equal(
-      result.status,
-      0,
-      `expected scripts/get_frequency.ts to typecheck\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
-    );
-  } finally {
-    fs.rmSync(workspace, { recursive: true, force: true });
-  }
-});

scripts/package-bun-source.test.ts

@@ -39,24 +39,6 @@ describe('Bun corresponding-source manifest', () => {
     }
   });
 
-  test('pins the source to the revision reported by the distributed binary', async () => {
-    const manifest = parseSourceManifest(
-      JSON.parse(
-        await fs.readFile(path.join(projectRoot, 'build/bun-source-manifest.json'), 'utf8'),
-      ),
-    );
-
-    expect(manifest.version).toBe('1.3.5');
-    expect(manifest.bunRevision).toBe('1e86cebd74a5723e818b5c0555276b646bcf0e4c');
-    expect(manifest.releaseTagCommit).toBe('fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab');
-    expect(manifest.sources.find((source) => source.name === 'WebKit')?.revision).toBe(
-      '6d0f3aac0b817cc01a846b3754b21271adedac12',
-    );
-    expect(manifest.sources.find((source) => source.name === 'tinycc')?.revision).toBe(
-      '29985a3b59898861442fa3b43f663fc1af2591d7',
-    );
-  });
-
   test('parses commit and tag registrations from Bun CMake', () => {
     const registrations = parseRegisteredRepositories(`
       register_repository(

scripts/preload-bundles.test.ts

@@ -1,16 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import path from 'node:path';
-
-test('build:syncui bundles the sandboxed preload and keeps Electron external', () => {
-  const packageJson = JSON.parse(
-    fs.readFileSync(path.join(import.meta.dir, '..', 'package.json'), 'utf8'),
-  ) as { scripts: Record<string, string> };
-  const command = packageJson.scripts['build:syncui'] ?? '';
-
-  assert.match(command, /src\/preload-syncui\.ts/);
-  assert.match(command, /--bundle/);
-  assert.match(command, /--external:electron/);
-  assert.match(command, /--outfile=dist\/preload-syncui\.js/);
-});

scripts/prepare-build-assets.test.ts

@@ -1,27 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import test from 'node:test';
-
-const source = readFileSync('scripts/prepare-build-assets.mjs', 'utf8');
-
-test('macOS helper build creates dist scripts directory before swiftc output', () => {
-  const buildFunctionIndex = source.indexOf('function buildMacosHelper()');
-  assert.notEqual(buildFunctionIndex, -1);
-
-  const swiftcIndex = source.indexOf("'swiftc'", buildFunctionIndex);
-  assert.notEqual(swiftcIndex, -1);
-
-  const ensureDirIndex = source.lastIndexOf('ensureDir(scriptsOutputDir)', swiftcIndex);
-
-  assert.ok(
-    ensureDirIndex > buildFunctionIndex,
-    'buildMacosHelper must create dist/scripts before swiftc writes the helper binary',
-  );
-});
-
-// Regression guard for #213: an untargeted swiftc stamps the build machine's OS
-// version as the helper's minimum, so released builds refuse to load on older macOS.
-test('macOS helper is compiled with an explicit deployment target', () => {
-  assert.match(source, /-target/);
-  assert.match(source, /apple-macos\$\{MACOS_HELPER_DEPLOYMENT_TARGET\}/);
-});

scripts/run-coverage-lane.test.ts

@@ -75,7 +75,7 @@ test('resolveCoverageDir keeps coverage output inside the repository', () => {
   assert.throws(() => resolveCoverageDir(repoRoot, ['--coverage-dir', '/tmp/escape']));
 });
 
-test('runCoverageLane returns a failure when a discovered test fails', () => {
+test('runCoverageLane returns a failure when a discovered test fails', async () => {
   const repoRoot = mkdtempSync(join(tmpdir(), 'subminer-coverage-failure-'));
   try {
     mkdirSync(join(repoRoot, 'src'));
@@ -93,10 +93,10 @@ test('runCoverageLane returns a failure when a discovered test fails', () => {
     );
 
     assert.notEqual(
-      runCoverageLane({
+      await runCoverageLane({
         repoRootDir: repoRoot,
         argv: ['bun-src-full', '--coverage-dir', 'coverage/test-src'],
-        stdio: 'pipe',
+        quiet: true,
       }),
       0,
     );

scripts/run-coverage-lane.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { availableParallelism } from 'node:os';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { collectLaneFiles } from './test-lanes';
 
@@ -201,9 +202,40 @@ export function mergeLcovReports(reports: string[]): string {
   return chunks.length > 0 ? `${chunks.join('\n')}\n` : '';
 }
 
-export function runCoverageLane(
-  options: { repoRootDir?: string; argv?: string[]; stdio?: 'inherit' | 'pipe' } = {},
-): number {
+type ShardResult = { status: number; output: string; lcov: string | null };
+
+// Runs one test file under coverage into its own shard directory, buffering
+// output so parallel shards do not interleave on the terminal.
+function runShard(repoRootDir: string, file: string, shardDir: string): Promise<ShardResult> {
+  return new Promise((resolveShard) => {
+    const child = spawn(
+      'bun',
+      ['test', '--coverage', '--coverage-reporter=lcov', '--coverage-dir', shardDir, `./${file}`],
+      { cwd: repoRootDir },
+    );
+    let output = '';
+    child.stdout.on('data', (chunk) => (output += chunk));
+    child.stderr.on('data', (chunk) => (output += chunk));
+    child.on('error', (error) => resolveShard({ status: 1, output: String(error), lcov: null }));
+    child.on('close', (code) => {
+      const lcovPath = join(shardDir, 'lcov.info');
+      const lcov = existsSync(lcovPath) ? readFileSync(lcovPath, 'utf8') : null;
+      resolveShard({ status: code ?? 1, output, lcov });
+    });
+  });
+}
+
+function parseJobsArg(argv: string[]): number {
+  const index = argv.indexOf('--jobs');
+  if (index === -1) return availableParallelism();
+  return Math.max(1, Number(argv[index + 1]) || 1);
+}
+
+// Shards run in parallel (one per CPU unless --jobs N). The first failing shard
+// stops scheduling new shards and its exit status becomes the lane result.
+export async function runCoverageLane(
+  options: { repoRootDir?: string; argv?: string[]; quiet?: boolean } = {},
+): Promise<number> {
   const repoRootDir = options.repoRootDir ?? repoRoot;
   const argv = options.argv ?? process.argv.slice(2);
   const laneName = argv[0];
@@ -225,40 +257,44 @@ export function runCoverageLane(
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     return 1;
   }
-  const reports: string[] = [];
+
+  const reports: Array<string | null> = new Array(files.length).fill(null);
+  const failures: Array<{ file: string; result: ShardResult }> = [];
+  let nextIndex = 0;
+
+  const worker = async (): Promise<void> => {
+    while (failures.length === 0 && nextIndex < files.length) {
+      const index = nextIndex++;
+      const file = files[index]!;
+      const shardDir = join(shardRoot, String(index + 1).padStart(3, '0'));
+      const result = await runShard(repoRootDir, file, shardDir);
+      if (result.status !== 0) {
+        failures.push({ file, result });
+        return;
+      }
+      if (result.lcov === null && !options.quiet) {
+        process.stdout.write(`Skipping empty coverage shard for ${file}\n`);
+      }
+      reports[index] = result.lcov;
+    }
+  };
 
   try {
-    for (const [index, file] of files.entries()) {
-      const shardDir = join(shardRoot, `${String(index + 1).padStart(3, '0')}`);
-      const result = spawnSync(
-        'bun',
-        ['test', '--coverage', '--coverage-reporter=lcov', '--coverage-dir', shardDir, `./${file}`],
-        {
-          cwd: repoRootDir,
-          stdio: options.stdio ?? 'inherit',
-        },
-      );
+    const jobs = Math.min(parseJobsArg(argv), files.length);
+    await Promise.all(Array.from({ length: jobs }, worker));
 
-      if (result.error) {
-        throw result.error;
+    const [failure] = failures;
+    if (failure !== undefined) {
+      const { file, result } = failure;
+      if (!options.quiet) {
+        process.stderr.write(`${result.output}\nCoverage shard failed: ${file}\n`);
       }
-      if ((result.status ?? 1) !== 0) {
-        return result.status ?? 1;
+      return result.status;
     }
 
-      const lcovPath = join(shardDir, 'lcov.info');
-      if (!existsSync(lcovPath)) {
-        process.stdout.write(`Skipping empty coverage shard for ${file}\n`);
-        continue;
-      }
-
-      reports.push(readFileSync(lcovPath, 'utf8'));
-    }
-
-    writeFileSync(join(coverageDir, 'lcov.info'), mergeLcovReports(reports), 'utf8');
-    process.stdout.write(
-      `Merged LCOV written to ${relative(repoRootDir, join(coverageDir, 'lcov.info'))}\n`,
-    );
+    const lcovPath = join(coverageDir, 'lcov.info');
+    writeFileSync(lcovPath, mergeLcovReports(reports.filter((r) => r !== null)), 'utf8');
+    process.stdout.write(`Merged LCOV written to ${relative(repoRootDir, lcovPath)}\n`);
     return 0;
   } finally {
     rmSync(shardRoot, { recursive: true, force: true });
@@ -267,5 +303,5 @@ export function runCoverageLane(
 
 // @ts-ignore Bun entrypoint detection; TS config for scripts still targets CommonJS.
 if (import.meta.main) {
-  process.exit(runCoverageLane());
+  runCoverageLane().then((status) => process.exit(status));
 }

scripts/run-test-lane.mjs

@@ -1,5 +1,6 @@
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
+import { availableParallelism } from 'node:os';
 import { spawn, spawnSync } from 'node:child_process';
 import { collectLaneFiles } from './test-lanes.ts';
 
@@ -7,6 +8,8 @@ import { collectLaneFiles } from './test-lanes.ts';
 // test file so a hanging test or leaked global in one file cannot poison the
 // rest of the lane. Use --single-process for the old all-in-one-process mode.
 //
+// Files run in parallel, one worker per CPU by default; --jobs 1 runs serially.
+//
 // Usage: bun scripts/run-test-lane.mjs <lane> [--jobs N] [--timeout-secs N] [--single-process]
 
 const repoRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
@@ -34,7 +37,12 @@ for (const signal of ['SIGINT', 'SIGTERM']) {
 }
 
 function parseArgs(argv) {
-  const options = { lane: undefined, jobs: 1, timeoutSecs: 300, singleProcess: false };
+  const options = {
+    lane: undefined,
+    jobs: availableParallelism(),
+    timeoutSecs: 300,
+    singleProcess: false,
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === '--jobs') {

scripts/stage-bun-runtime.test.ts

@@ -61,15 +61,6 @@ test('normalizeTarget maps each supported electron-builder target without using
   assert.throws(() => normalizeTarget('linux', 0), /Unsupported Bun runtime target architecture/);
 });
 
-test('resolveArtifact chooses baseline x64 builds and standard arm64 builds', () => {
-  const config = runtimeConfig();
-  assert.equal(resolveArtifact(config, 'linux', 'x64').file, 'bun-linux-x64-baseline.zip');
-  assert.equal(resolveArtifact(config, 'darwin', 'x64').file, 'bun-darwin-x64-baseline.zip');
-  assert.equal(resolveArtifact(config, 'win32', 'x64').file, 'bun-windows-x64-baseline.zip');
-  assert.equal(resolveArtifact(config, 'linux', 'arm64').file, 'bun-linux-aarch64.zip');
-  assert.equal(resolveArtifact(config, 'darwin', 'arm64').file, 'bun-darwin-aarch64.zip');
-});
-
 test('tracked runtime manifest covers every supported target at the packageManager version', async () => {
   const config = await loadRuntimeConfig();
   assert.equal(config.version, '1.3.5');

src/anki-connect.test.ts

@@ -3,20 +3,6 @@ import assert from 'node:assert/strict';
 import { AnkiConnectClient } from './anki-connect';
 import { setLogLevel } from './logger';
 
-test('AnkiConnectClient disables keep-alive agents to avoid stale socket retries', () => {
-  const client = new AnkiConnectClient('http://127.0.0.1:8765') as unknown as {
-    client: {
-      defaults: {
-        httpAgent?: { options?: { keepAlive?: boolean } };
-        httpsAgent?: { options?: { keepAlive?: boolean } };
-      };
-    };
-  };
-
-  assert.equal(client.client.defaults.httpAgent?.options?.keepAlive, false);
-  assert.equal(client.client.defaults.httpsAgent?.options?.keepAlive, false);
-});
-
 test('AnkiConnectClient includes action name in retry logs', async () => {
   const client = new AnkiConnectClient('http://127.0.0.1:8765') as unknown as {
     client: { post: (url: string, body: unknown, options: unknown) => Promise<unknown> };

src/anki-integration/card-creation-sentence-media.test.ts

@@ -2,9 +2,13 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import { CardCreationService } from './card-creation';
-import type { AnkiConnectConfig } from '../types/anki';
-
-type CardCreationDeps = ConstructorParameters<typeof CardCreationService>[0];
+import {
+  type CardCreationDeps,
+  createAnkiConfig,
+  createCardCreationDeps,
+  createFakeClient,
+  createFakeMediaGenerator,
+} from './card-creation-test-utils';
 
 test('sentence card writes generated audio only to sentence audio field', async () => {
   const addedFields: Record<string, string>[] = [];
@@ -13,28 +17,23 @@ test('sentence card writes generated audio only to sentence audio field', async
   const requestedProperties: string[] = [];
   const audioVolumeScales: Array<number | undefined> = [];
   const audioRanges: Array<{ start: number; end: number; padding: number | undefined }> = [];
+  let review: Awaited<ReturnType<NonNullable<CardCreationDeps['reviewMediaTiming']>>> = {
+    action: 'confirm',
+    startTime: 11.4,
+    endTime: 14.2,
+  };
 
-  const deps: CardCreationDeps = {
+  const service = new CardCreationService(
+    createCardCreationDeps({
       getConfig: () =>
-      ({
-        deck: 'Mining',
+        createAnkiConfig({
           fields: {
             word: 'Expression',
-          sentence: 'Sentence',
             audio: 'ExpressionAudio',
             translation: 'SelectionText',
           },
-        media: {
-          generateAudio: true,
-          generateImage: false,
-          mirrorMpvVolume: true,
-          maxMediaDuration: 30,
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
+          media: { generateAudio: true, mirrorMpvVolume: true, maxMediaDuration: 30 },
+        }),
       getMpvClient: () =>
         ({
           currentVideoPath: '/video.mp4',
@@ -48,12 +47,11 @@ test('sentence card writes generated audio only to sentence audio field', async
             return 40;
           },
         }) as never,
-    client: {
+      client: createFakeClient({
         addNote: async (_deck, _modelName, fields) => {
           addedFields.push(fields);
           return 42;
         },
-      addTags: async () => undefined,
         notesInfo: async () => [
           {
             noteId: 42,
@@ -72,11 +70,8 @@ test('sentence card writes generated audio only to sentence audio field', async
         storeMediaFile: async (filename) => {
           storedMedia.push(filename);
         },
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
+      }),
+      mediaGenerator: createFakeMediaGenerator({
         generateAudio: async (
           _path,
           startTime,
@@ -90,30 +85,7 @@ test('sentence card writes generated audio only to sentence audio field', async
           audioVolumeScales.push(volumeScale);
           return Buffer.from('audio');
         },
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: (noteInfo, ...preferredNames) => {
-      for (const preferredName of preferredNames) {
-        if (preferredName && preferredName in noteInfo.fields) return preferredName;
-      }
-      return null;
-    },
-    resolveNoteFieldName: (noteInfo, preferredName) =>
-      preferredName && preferredName in noteInfo.fields ? preferredName : null,
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: () => undefined,
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
+      }),
       getEffectiveSentenceCardConfig: () => ({
         model: 'Sentence',
         sentenceField: 'Sentence',
@@ -122,19 +94,11 @@ test('sentence card writes generated audio only to sentence audio field', async
         kikuEnabled: false,
         fieldGroupingMode: 'disabled',
       }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    trackLastAddedNoteId: () => undefined,
-    reviewMediaTiming: async () => ({ action: 'confirm', startTime: 11.4, endTime: 14.2 }),
-  };
+      reviewMediaTiming: async () => review,
+    }),
+  );
 
-  const service = new CardCreationService(deps);
-  const created = await service.createSentenceCard('字幕', 12, 14, 'Subtitle');
-
-  assert.equal(created, true);
+  assert.equal(await service.createSentenceCard('字幕', 12, 14, 'Subtitle'), true);
   assert.deepEqual(addedFields[0], {
     Sentence: '字幕',
     SelectionText: 'Subtitle',
@@ -149,11 +113,11 @@ test('sentence card writes generated audio only to sentence audio field', async
   assert.equal(mediaUpdate?.SentenceAudio, `[sound:${storedMedia[0]}]`);
   assert.equal('ExpressionAudio' in mediaUpdate!, false);
 
-  deps.reviewMediaTiming = async () => ({ action: 'discard' });
+  review = { action: 'discard' };
   assert.equal(await service.createSentenceCard('作らない', 20, 22), false);
   assert.equal(addedFields.length, 1);
 
-  deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
+  review = { action: 'skip-media' };
   assert.equal(await service.createSentenceCard('メディアなし', 30, 32), true);
   assert.equal(addedFields.length, 2);
   assert.equal(storedMedia.length, 1);

src/anki-integration/card-creation-test-utils.ts

@@ -0,0 +1,107 @@
+import { CardCreationService } from './card-creation';
+import type { AnkiConnectConfig } from '../types/anki';
+
+export type CardCreationDeps = ConstructorParameters<typeof CardCreationService>[0];
+
+/** Builds the minimal config the service reads; pass only the sections a test cares about. */
+export function createAnkiConfig(
+  overrides: {
+    fields?: Record<string, string>;
+    media?: Record<string, unknown>;
+  } = {},
+): AnkiConnectConfig {
+  return {
+    deck: 'Mining',
+    fields: { sentence: 'Sentence', audio: 'SentenceAudio', ...overrides.fields },
+    media: { generateAudio: false, generateImage: false, ...overrides.media },
+    behavior: {},
+    ai: false,
+  } as AnkiConnectConfig;
+}
+
+/**
+ * Fake CardCreationService dependencies: a bare mpv session, a client that adds note 42, no media,
+ * and field resolvers that match exact field names. Override only what the test exercises.
+ */
+export function createCardCreationDeps(
+  overrides: Partial<CardCreationDeps> = {},
+): CardCreationDeps {
+  return {
+    getConfig: () => createAnkiConfig(),
+    getAiConfig: () => ({}),
+    getTimingTracker: () => ({}) as never,
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentSubText: '字幕',
+        currentSubStart: 1,
+        currentSubEnd: 2,
+        currentTimePos: 1.5,
+        currentAudioStreamIndex: 0,
+      }) as never,
+    client: {
+      addNote: async () => 42,
+      addTags: async () => undefined,
+      notesInfo: async () => [],
+      updateNoteFields: async () => undefined,
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
+    },
+    mediaGenerator: {
+      generateAudio: async () => null,
+      generateScreenshot: async () => null,
+      generateAnimatedImage: async () => null,
+    },
+    showOsdNotification: () => undefined,
+    showUpdateResult: () => undefined,
+    showStatusNotification: () => undefined,
+    showNotification: async () => undefined,
+    beginUpdateProgress: () => undefined,
+    endUpdateProgress: () => undefined,
+    withUpdateProgress: async (_message, action) => action(),
+    resolveConfiguredFieldName: (noteInfo, ...preferredNames) => {
+      for (const preferredName of preferredNames) {
+        if (preferredName && preferredName in noteInfo.fields) return preferredName;
+      }
+      return null;
+    },
+    resolveNoteFieldName: (noteInfo, preferredName) =>
+      preferredName && preferredName in noteInfo.fields ? preferredName : null,
+    getAnimatedImageLeadInSeconds: async () => 0,
+    extractFields: () => ({}),
+    processSentence: (sentence) => sentence,
+    setCardTypeFields: () => undefined,
+    mergeFieldValue: (_existing, newValue) => newValue,
+    formatMiscInfoPattern: () => '',
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: false,
+      kikuEnabled: false,
+      fieldGroupingMode: 'disabled',
+    }),
+    getFallbackDurationSeconds: () => 10,
+    appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
+    isUpdateInProgress: () => false,
+    setUpdateInProgress: () => undefined,
+    trackLastAddedNoteId: () => undefined,
+    ...overrides,
+  };
+}
+
+/** Anki client overrides, kept separate so a test can swap one method without redeclaring the rest. */
+export function createFakeClient(
+  overrides: Partial<CardCreationDeps['client']> = {},
+): CardCreationDeps['client'] {
+  return { ...createCardCreationDeps().client, ...overrides };
+}
+
+export function createFakeMediaGenerator(
+  overrides: Partial<CardCreationDeps['mediaGenerator']> = {},
+): CardCreationDeps['mediaGenerator'] {
+  return { ...createCardCreationDeps().mediaGenerator, ...overrides };
+}

src/anki-integration/card-creation.test.ts

@@ -2,292 +2,83 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import { CardCreationService } from './card-creation';
+import {
+  type CardCreationDeps,
+  createAnkiConfig,
+  createCardCreationDeps,
+  createFakeClient,
+  createFakeMediaGenerator,
+} from './card-creation-test-utils';
 import { toMpvEdlValue } from './mpv-edl-test-utils';
 import type { MediaInput } from '../media-generator';
-import type { AnkiConnectConfig } from '../types/anki';
+
+const YOUTUBE_URL = 'https://www.youtube.com/watch?v=abc123';
+
+const mediaInputPath = (mediaInput: MediaInput): string =>
+  typeof mediaInput === 'string' ? mediaInput : mediaInput.path;
 
 test('CardCreationService counts locally created sentence cards', async () => {
   const minedCards: Array<{ count: number; noteIds?: number[] }> = [];
-  const service = new CardCreationService({
-    getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
-        },
-        media: {
-          generateAudio: false,
-          generateImage: false,
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 1,
-        currentSubEnd: 2,
-        currentTimePos: 1.5,
-        currentAudioStreamIndex: 0,
-      }) as never,
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
-      notesInfo: async () => [],
-      updateNoteFields: async () => undefined,
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
-      generateAudio: async () => null,
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: () => null,
-    resolveNoteFieldName: () => null,
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: () => undefined,
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
-    getEffectiveSentenceCardConfig: () => ({
-      model: 'Sentence',
-      sentenceField: 'Sentence',
-      audioField: 'SentenceAudio',
-      lapisEnabled: false,
-      kikuEnabled: false,
-      fieldGroupingMode: 'disabled',
-    }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    trackLastAddedNoteId: () => undefined,
+  const service = new CardCreationService(
+    createCardCreationDeps({
       recordCardsMinedCallback: (count, noteIds) => {
         minedCards.push({ count, noteIds });
       },
-  });
+    }),
+  );
 
-  const created = await service.createSentenceCard('テスト', 0, 1);
-
-  assert.equal(created, true);
+  assert.equal(await service.createSentenceCard('テスト', 0, 1), true);
   assert.deepEqual(minedCards, [{ count: 1, noteIds: [42] }]);
 });
 
-test('CardCreationService keeps updating after trackLastAddedNoteId throws', async () => {
-  const calls = {
-    notesInfo: 0,
-    updateNoteFields: 0,
-  };
-  const service = new CardCreationService({
-    getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
-        },
-        media: {
-          generateAudio: false,
-          generateImage: false,
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 1,
-        currentSubEnd: 2,
-        currentTimePos: 1.5,
-        currentAudioStreamIndex: 0,
-      }) as never,
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
-      notesInfo: async () => {
-        calls.notesInfo += 1;
-        return [
+const THROWING_HOOKS: Array<{
+  name: string;
+  hook: Partial<CardCreationDeps>;
+}> = [
   {
-            noteId: 42,
-            fields: {
-              Sentence: { value: 'existing' },
-            },
-          },
-        ];
-      },
-      updateNoteFields: async () => {
-        calls.updateNoteFields += 1;
-      },
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
-      generateAudio: async () => null,
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: () => null,
-    resolveNoteFieldName: () => null,
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: (updatedFields) => {
-      updatedFields.CardType = 'sentence';
-    },
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
-    getEffectiveSentenceCardConfig: () => ({
-      model: 'Sentence',
-      sentenceField: 'Sentence',
-      audioField: 'SentenceAudio',
-      lapisEnabled: false,
-      kikuEnabled: false,
-      fieldGroupingMode: 'disabled',
-    }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
+    name: 'trackLastAddedNoteId',
+    hook: {
       trackLastAddedNoteId: () => {
         throw new Error('track failed');
       },
-  });
-
-  const created = await service.createSentenceCard('テスト', 0, 1);
-
-  assert.equal(created, true);
-  assert.equal(calls.notesInfo, 1);
-  assert.equal(calls.updateNoteFields, 1);
-});
-
-test('CardCreationService keeps updating after recordCardsMinedCallback throws', async () => {
-  const calls = {
-    notesInfo: 0,
-    updateNoteFields: 0,
-  };
-  const service = new CardCreationService({
-    getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
     },
-        media: {
-          generateAudio: false,
-          generateImage: false,
   },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 1,
-        currentSubEnd: 2,
-        currentTimePos: 1.5,
-        currentAudioStreamIndex: 0,
-      }) as never,
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
-      notesInfo: async () => {
-        calls.notesInfo += 1;
-        return [
   {
-            noteId: 42,
-            fields: {
-              Sentence: { value: 'existing' },
+    name: 'recordCardsMinedCallback',
+    hook: {
+      recordCardsMinedCallback: () => {
+        throw new Error('record failed');
+      },
     },
   },
 ];
+
+for (const c of THROWING_HOOKS) {
+  test(`CardCreationService keeps updating after ${c.name} throws`, async () => {
+    const calls = { notesInfo: 0, updateNoteFields: 0 };
+    const service = new CardCreationService(
+      createCardCreationDeps({
+        client: createFakeClient({
+          notesInfo: async () => {
+            calls.notesInfo += 1;
+            return [{ noteId: 42, fields: { Sentence: { value: 'existing' } } }];
           },
           updateNoteFields: async () => {
             calls.updateNoteFields += 1;
           },
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
-      generateAudio: async () => null,
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: () => null,
-    resolveNoteFieldName: () => null,
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
+        }),
         setCardTypeFields: (updatedFields) => {
           updatedFields.CardType = 'sentence';
         },
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
-    getEffectiveSentenceCardConfig: () => ({
-      model: 'Sentence',
-      sentenceField: 'Sentence',
-      audioField: 'SentenceAudio',
-      lapisEnabled: false,
-      kikuEnabled: false,
-      fieldGroupingMode: 'disabled',
+        ...c.hook,
       }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    recordCardsMinedCallback: () => {
-      throw new Error('record failed');
-    },
-  });
+    );
 
-  const created = await service.createSentenceCard('テスト', 0, 1);
-
-  assert.equal(created, true);
+    assert.equal(await service.createSentenceCard('テスト', 0, 1), true);
     assert.equal(calls.notesInfo, 1);
     assert.equal(calls.updateNoteFields, 1);
   });
+}
 
 test('CardCreationService uses stream-open-filename for remote media generation', async () => {
   let reviewing = false;
@@ -295,8 +86,6 @@ test('CardCreationService uses stream-open-filename for remote media generation'
   const imageTimes: number[] = [];
   const audioPaths: string[] = [];
   const imagePaths: string[] = [];
-  const recordMediaPath = (mediaInput: MediaInput): string =>
-    typeof mediaInput === 'string' ? mediaInput : mediaInput.path;
   const audioUrl = 'https://audio.example/videoplayback?mime=audio%2Fwebm';
   const videoUrl = 'https://video.example/videoplayback?mime=video%2Fmp4';
   const edlSource = [
@@ -305,32 +94,20 @@ test('CardCreationService uses stream-open-filename for remote media generation'
     '!global_tags,title=test',
   ].join(';');
 
-  const service = new CardCreationService({
+  const service = new CardCreationService(
+    createCardCreationDeps({
       getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
-          image: 'Picture',
-        },
-        media: {
-          generateAudio: true,
-          generateImage: true,
-          imageFormat: 'jpg',
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
+        createAnkiConfig({
+          fields: { image: 'Picture' },
+          media: { generateAudio: true, generateImage: true, imageFormat: 'jpg' },
+        }),
       reviewMediaTiming: async () =>
         reviewing
           ? { action: 'confirm', startTime: 0.2, endTime: 0.8, screenshotTime: 3.125 }
           : { action: 'use-original' },
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
       getMpvClient: () =>
         ({
-        currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+          currentVideoPath: YOUTUBE_URL,
           currentSubText: '字幕',
           currentSubStart: 1,
           currentSubEnd: 2,
@@ -341,9 +118,7 @@ test('CardCreationService uses stream-open-filename for remote media generation'
             return edlSource;
           },
         }) as never,
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
+      client: createFakeClient({
         notesInfo: async () => [
           {
             noteId: 42,
@@ -354,71 +129,32 @@ test('CardCreationService uses stream-open-filename for remote media generation'
             },
           },
         ],
-      updateNoteFields: async () => undefined,
-      storeMediaFile: async () => undefined,
         findNotes: async () => [42],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
+      }),
+      mediaGenerator: createFakeMediaGenerator({
         generateAudio: async (path, start, end, padding) => {
           audioRanges.push([start, end, padding ?? -1]);
-        audioPaths.push(recordMediaPath(path));
+          audioPaths.push(mediaInputPath(path));
           return Buffer.from('audio');
         },
         generateScreenshot: async (path, timestamp) => {
           imageTimes.push(timestamp);
-        imagePaths.push(recordMediaPath(path));
+          imagePaths.push(mediaInputPath(path));
           return Buffer.from('image');
         },
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: (noteInfo, preferredName) => {
-      if (!preferredName) return null;
-      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
-    },
-    resolveNoteFieldName: (noteInfo, preferredName) => {
-      if (!preferredName) return null;
-      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
-    },
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: () => undefined,
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
-    getEffectiveSentenceCardConfig: () => ({
-      model: 'Sentence',
-      sentenceField: 'Sentence',
-      audioField: 'SentenceAudio',
-      lapisEnabled: false,
-      kikuEnabled: false,
-      fieldGroupingMode: 'disabled',
       }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    trackLastAddedNoteId: () => undefined,
-  });
+    }),
+  );
 
-  const created = await service.createSentenceCard('テスト', 0, 1);
-
-  assert.equal(created, true);
+  assert.equal(await service.createSentenceCard('テスト', 0, 1), true);
   assert.deepEqual(audioPaths, [audioUrl]);
   assert.deepEqual(imagePaths, [videoUrl]);
+
   reviewing = true;
   assert.equal(await service.createSentenceCard('テスト', 0, 1), true);
   assert.deepEqual(audioRanges.at(-1), [0.2, 0.8, 0]);
   assert.equal(imageTimes.at(-1), 3.125);
+
   await service.markLastCardAsAudioCard();
   assert.equal(imageTimes.length, 3);
   assert.deepEqual(audioRanges.at(-1), [0.2, 0.8, 0]);
@@ -428,28 +164,16 @@ test('CardCreationService uses stream-open-filename for remote media generation'
 test('CardCreationService does not use mpv stream indexes for ready cached YouTube media', async () => {
   const audioCalls: Array<{ path: string; audioStreamIndex?: number }> = [];
 
-  const service = new CardCreationService({
+  const service = new CardCreationService(
+    createCardCreationDeps({
       getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
-          image: 'Picture',
-        },
-        media: {
-          generateAudio: true,
-          generateImage: false,
-          imageFormat: 'jpg',
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
+        createAnkiConfig({
+          fields: { image: 'Picture' },
+          media: { generateAudio: true, imageFormat: 'jpg' },
+        }),
       getMpvClient: () =>
         ({
-        currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+          currentVideoPath: YOUTUBE_URL,
           currentSubText: '字幕',
           currentSubStart: 10,
           currentSubEnd: 12,
@@ -458,9 +182,7 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
         }) as never,
       getCachedMediaPath: async () => '/tmp/subminer-youtube-media-cache/media.mkv',
       shouldRequireRemoteMediaCache: () => true,
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
+      client: createFakeClient({
         notesInfo: async () => [
           {
             noteId: 42,
@@ -471,65 +193,19 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
             },
           },
         ],
-      updateNoteFields: async () => undefined,
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
+      }),
+      mediaGenerator: createFakeMediaGenerator({
         generateAudio: async (path, _startTime, _endTime, _padding, audioStreamIndex) => {
-        audioCalls.push({ path: typeof path === 'string' ? path : path.path, audioStreamIndex });
+          audioCalls.push({ path: mediaInputPath(path), audioStreamIndex });
           return Buffer.from('audio');
         },
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: (noteInfo, preferredName) => {
-      if (!preferredName) return null;
-      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
-    },
-    resolveNoteFieldName: (noteInfo, preferredName) => {
-      if (!preferredName) return null;
-      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
-    },
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: () => undefined,
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
-    getEffectiveSentenceCardConfig: () => ({
-      model: 'Sentence',
-      sentenceField: 'Sentence',
-      audioField: 'SentenceAudio',
-      lapisEnabled: false,
-      kikuEnabled: false,
-      fieldGroupingMode: 'disabled',
       }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    trackLastAddedNoteId: () => undefined,
-  });
+    }),
+  );
 
-  const created = await service.createSentenceCard('テスト', 10, 12);
-
-  assert.equal(created, true);
+  assert.equal(await service.createSentenceCard('テスト', 10, 12), true);
   assert.deepEqual(audioCalls, [
-    {
-      path: '/tmp/subminer-youtube-media-cache/media.mkv',
-      audioStreamIndex: undefined,
-    },
+    { path: '/tmp/subminer-youtube-media-cache/media.mkv', audioStreamIndex: undefined },
   ]);
 });
 
@@ -551,38 +227,23 @@ test('CardCreationService queues YouTube media when required cache is not ready'
   }> = [];
   let streamRequests = 0;
 
-  const service = new CardCreationService({
+  const service = new CardCreationService(
+    createCardCreationDeps({
       getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
-          image: 'Picture',
-          miscInfo: 'MiscInfo',
-        },
-        media: {
-          generateAudio: true,
-          generateImage: true,
-          imageFormat: 'jpg',
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
+        createAnkiConfig({
+          fields: { image: 'Picture', miscInfo: 'MiscInfo' },
+          media: { generateAudio: true, generateImage: true, imageFormat: 'jpg' },
+        }),
       getMpvClient: () =>
         ({
-        currentVideoPath: 'https://www.youtube.com/watch?v=abc123',
+          currentVideoPath: YOUTUBE_URL,
           currentSubText: '字幕',
           currentSubStart: 10,
           currentSubEnd: 12,
           currentTimePos: 11,
           currentAudioStreamIndex: 2,
           requestProperty: async (name: string) => {
-          if (name === 'volume') {
-            return 35;
-          }
+            if (name === 'volume') return 35;
             streamRequests += 1;
             return 'https://rr1---sn.example.googlevideo.com/videoplayback?id=123';
           },
@@ -592,9 +253,7 @@ test('CardCreationService queues YouTube media when required cache is not ready'
       queuePendingYoutubeMediaUpdate: (job) => {
         queuedUpdates.push(job);
       },
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
+      client: createFakeClient({
         notesInfo: async () => [
           {
             noteId: 42,
@@ -609,12 +268,8 @@ test('CardCreationService queues YouTube media when required cache is not ready'
         updateNoteFields: async (noteId, fields) => {
           updates.push({ noteId, fields });
         },
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
+      }),
+      mediaGenerator: createFakeMediaGenerator({
         generateAudio: async () => {
           mediaCalls.push('audio');
           return Buffer.from('audio');
@@ -623,53 +278,16 @@ test('CardCreationService queues YouTube media when required cache is not ready'
           mediaCalls.push('image');
           return Buffer.from('image');
         },
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: (noteInfo, preferredName) => {
-      if (!preferredName) return null;
-      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
-    },
-    resolveNoteFieldName: (noteInfo, preferredName) => {
-      if (!preferredName) return null;
-      return Object.keys(noteInfo.fields).find((field) => field === preferredName) ?? null;
-    },
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: () => undefined,
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
-    getEffectiveSentenceCardConfig: () => ({
-      model: 'Sentence',
-      sentenceField: 'Sentence',
-      audioField: 'SentenceAudio',
-      lapisEnabled: false,
-      kikuEnabled: false,
-      fieldGroupingMode: 'disabled',
       }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    trackLastAddedNoteId: () => undefined,
-  });
+    }),
+  );
 
-  const created = await service.createSentenceCard('テスト', 10, 12);
-
-  assert.equal(created, true);
+  assert.equal(await service.createSentenceCard('テスト', 10, 12), true);
   assert.equal(streamRequests, 0);
   assert.deepEqual(mediaCalls, []);
   assert.deepEqual(queuedUpdates, [
     {
-      sourceUrl: 'https://www.youtube.com/watch?v=abc123',
+      sourceUrl: YOUTUBE_URL,
       noteId: 42,
       startTime: 10,
       endTime: 12,
@@ -685,67 +303,28 @@ test('CardCreationService queues YouTube media when required cache is not ready'
   assert.deepEqual(updates, []);
 });
 
-test('CardCreationService tracks pre-add duplicate note ids for kiku sentence cards', async () => {
-  const trackedDuplicates: Array<{ noteId: number; duplicateNoteIds: number[] }> = [];
-  const duplicateLookupExpressions: string[] = [];
+const DUPLICATE_TRACKING_CASES = [
+  {
+    name: 'tracks sorted, deduplicated pre-add duplicate note ids for kiku sentence cards',
+    sentence: '重複文',
+    lookupResult: [18, 7, 30, 7],
+    expected: [{ noteId: 42, duplicateNoteIds: [7, 18, 30] }],
+  },
+  {
+    name: 'does not track duplicate ids when pre-add lookup returns none',
+    sentence: '重複なし',
+    lookupResult: [],
+    expected: [],
+  },
+];
 
-  const service = new CardCreationService({
-    getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          word: 'Expression',
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
-        },
-        media: {
-          generateAudio: false,
-          generateImage: false,
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 1,
-        currentSubEnd: 2,
-        currentTimePos: 1.5,
-        currentAudioStreamIndex: 0,
-      }) as never,
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
-      notesInfo: async () => [],
-      updateNoteFields: async () => undefined,
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
-      generateAudio: async () => null,
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: () => null,
-    resolveNoteFieldName: () => null,
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: () => undefined,
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
+for (const c of DUPLICATE_TRACKING_CASES) {
+  test(`CardCreationService ${c.name}`, async () => {
+    const trackedDuplicates: Array<{ noteId: number; duplicateNoteIds: number[] }> = [];
+    const lookedUp: string[] = [];
+    const service = new CardCreationService(
+      createCardCreationDeps({
+        getConfig: () => createAnkiConfig({ fields: { word: 'Expression' } }),
         getEffectiveSentenceCardConfig: () => ({
           model: 'Sentence',
           sentenceField: 'Sentence',
@@ -754,110 +333,18 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
           kikuEnabled: true,
           fieldGroupingMode: 'manual',
         }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    trackLastAddedNoteId: () => undefined,
         findDuplicateNoteIds: async (expression) => {
-      duplicateLookupExpressions.push(expression);
-      return [18, 7, 30, 7];
+          lookedUp.push(expression);
+          return c.lookupResult;
         },
         trackLastAddedDuplicateNoteIds: (noteId, duplicateNoteIds) => {
           trackedDuplicates.push({ noteId, duplicateNoteIds });
         },
-  });
-
-  const created = await service.createSentenceCard('重複文', 0, 1);
-
-  assert.equal(created, true);
-  assert.deepEqual(duplicateLookupExpressions, ['重複文']);
-  assert.deepEqual(trackedDuplicates, [{ noteId: 42, duplicateNoteIds: [7, 18, 30] }]);
-});
-
-test('CardCreationService does not track duplicate ids when pre-add lookup returns none', async () => {
-  const trackedDuplicates: Array<{ noteId: number; duplicateNoteIds: number[] }> = [];
-
-  const service = new CardCreationService({
-    getConfig: () =>
-      ({
-        deck: 'Mining',
-        fields: {
-          word: 'Expression',
-          sentence: 'Sentence',
-          audio: 'SentenceAudio',
-        },
-        media: {
-          generateAudio: false,
-          generateImage: false,
-        },
-        behavior: {},
-        ai: false,
-      }) as AnkiConnectConfig,
-    getAiConfig: () => ({}),
-    getTimingTracker: () => ({}) as never,
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 1,
-        currentSubEnd: 2,
-        currentTimePos: 1.5,
-        currentAudioStreamIndex: 0,
-      }) as never,
-    client: {
-      addNote: async () => 42,
-      addTags: async () => undefined,
-      notesInfo: async () => [],
-      updateNoteFields: async () => undefined,
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
-    },
-    mediaGenerator: {
-      generateAudio: async () => null,
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    showOsdNotification: () => undefined,
-    showUpdateResult: () => undefined,
-    showStatusNotification: () => undefined,
-    showNotification: async () => undefined,
-    beginUpdateProgress: () => undefined,
-    endUpdateProgress: () => undefined,
-    withUpdateProgress: async (_message, action) => action(),
-    resolveConfiguredFieldName: () => null,
-    resolveNoteFieldName: () => null,
-    getAnimatedImageLeadInSeconds: async () => 0,
-    extractFields: () => ({}),
-    processSentence: (sentence) => sentence,
-    setCardTypeFields: () => undefined,
-    mergeFieldValue: (_existing, newValue) => newValue,
-    formatMiscInfoPattern: () => '',
-    getEffectiveSentenceCardConfig: () => ({
-      model: 'Sentence',
-      sentenceField: 'Sentence',
-      audioField: 'SentenceAudio',
-      lapisEnabled: false,
-      kikuEnabled: true,
-      fieldGroupingMode: 'manual',
       }),
-    getFallbackDurationSeconds: () => 10,
-    appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
-    isUpdateInProgress: () => false,
-    setUpdateInProgress: () => undefined,
-    trackLastAddedNoteId: () => undefined,
-    findDuplicateNoteIds: async () => [],
-    trackLastAddedDuplicateNoteIds: (noteId, duplicateNoteIds) => {
-      trackedDuplicates.push({ noteId, duplicateNoteIds });
-    },
-  });
+    );
 
-  const created = await service.createSentenceCard('重複なし', 0, 1);
-
-  assert.equal(created, true);
-  assert.deepEqual(trackedDuplicates, []);
+    assert.equal(await service.createSentenceCard(c.sentence, 0, 1), true);
+    assert.deepEqual(lookedUp, [c.sentence]);
+    assert.deepEqual(trackedDuplicates, c.expected);
   });
+}

src/anki-integration/field-grouping-merge.test.ts

@@ -500,3 +500,38 @@ test('Senren merge keeps duplicate SentenceFurigana when the kept field is empty
 
   assert.equal(merged.SentenceFurigana, '<span class="group">duplicate furigana</span>');
 });
+
+test('computeFieldGroupingMergedFields keeps independent groups for identical sentence, audio, and image values', async () => {
+  const { collaborator } = createCollaborator();
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    202,
+    101,
+    makeNote(202, {
+      Sentence: 'same sentence',
+      SentenceAudio: '[sound:same.mp3]',
+      Picture: '<img src="same.png">',
+      ExpressionAudio: '[sound:same.mp3]',
+    }),
+    makeNote(101, {
+      Sentence: 'same sentence',
+      SentenceAudio: '[sound:same.mp3]',
+      Picture: '<img src="same.png">',
+    }),
+    false,
+  );
+
+  assert.equal(
+    merged.Sentence,
+    '<span data-group-id="202">same sentence</span><span data-group-id="101">same sentence</span>',
+  );
+  assert.equal(
+    merged.SentenceAudio,
+    '<span data-group-id="202">[sound:same.mp3]</span><span data-group-id="101">[sound:same.mp3]</span>',
+  );
+  assert.equal(
+    merged.Picture,
+    '<img data-group-id="202" src="same.png"><img data-group-id="101" src="same.png">',
+  );
+  assert.equal('ExpressionAudio' in merged, false);
+});

src/anki-integration/known-word-cache-maturity.test.ts

@@ -127,18 +127,6 @@ test('lifecycle config key is unchanged when maturity is disabled', () => {
   );
 });
 
-test('a cache built under the old tier rules is invalidated', () => {
-  const config: AnkiConnectConfig = {
-    knownWords: { highlightEnabled: true, maturityEnabled: true, refreshMinutes: 60 },
-  };
-  // v1 rules put lapsed cards in young because the interval queries did not
-  // exclude is:learn; those persisted tiers must not be served under v2.
-  assert.notEqual(
-    getKnownWordCacheLifecycleConfig(config),
-    '{"refreshMinutes":60,"scope":"all","fieldsWord":"","maturity":21}',
-  );
-});
-
 test('refresh fetches tier sets and getKnownWordTier classifies notes', async () => {
   const { manager, calls, clientState, cleanup } = createMaturityHarness(maturityConfig());
 

src/anki-integration/note-update-workflow.test.ts

@@ -245,127 +245,6 @@ test('NoteUpdateWorkflow marks enriched Kiku word cards as word-and-sentence car
   });
 });
 
-test('NoteUpdateWorkflow marks the configured word card kind instead of word-and-sentence', async () => {
-  const harness = createWorkflowHarness();
-  harness.deps.getEffectiveSentenceCardConfig = () => ({
-    sentenceField: 'Sentence',
-    lapisEnabled: false,
-    kikuEnabled: true,
-    fieldGroupingMode: 'manual',
-    wordCardKind: 'click',
-  });
-  harness.deps.client.notesInfo = async () =>
-    [
-      {
-        noteId: 42,
-        fields: {
-          Expression: { value: 'taberu' },
-          Sentence: { value: '' },
-          IsWordAndSentenceCard: { value: 'x' },
-          IsClickCard: { value: '' },
-          IsSentenceCard: { value: '' },
-          IsAudioCard: { value: '' },
-        },
-      },
-    ] satisfies NoteUpdateWorkflowNoteInfo[];
-
-  await harness.workflow.execute(42);
-
-  assert.equal(harness.updates.length, 1);
-  assert.deepEqual(harness.updates[0]?.fields, {
-    Sentence: 'subtitle-text',
-    IsClickCard: 'x',
-    IsWordAndSentenceCard: '',
-    IsSentenceCard: '',
-    IsAudioCard: '',
-  });
-});
-
-test('NoteUpdateWorkflow leaves card type flags alone when the word card kind is none', async () => {
-  const harness = createWorkflowHarness();
-  harness.deps.getEffectiveSentenceCardConfig = () => ({
-    sentenceField: 'Sentence',
-    lapisEnabled: false,
-    kikuEnabled: true,
-    fieldGroupingMode: 'manual',
-    wordCardKind: 'none',
-  });
-  harness.deps.client.notesInfo = async () =>
-    [
-      {
-        noteId: 42,
-        fields: {
-          Expression: { value: 'taberu' },
-          Sentence: { value: '' },
-          IsWordAndSentenceCard: { value: '' },
-          IsSentenceCard: { value: '' },
-          IsAudioCard: { value: '' },
-        },
-      },
-    ] satisfies NoteUpdateWorkflowNoteInfo[];
-
-  await harness.workflow.execute(42);
-
-  assert.equal(harness.updates.length, 1);
-  assert.deepEqual(harness.updates[0]?.fields, {
-    Sentence: 'subtitle-text',
-  });
-});
-
-test('NoteUpdateWorkflow does not set Kiku card flags when Lapis and Kiku are disabled', async () => {
-  const harness = createWorkflowHarness();
-  harness.deps.client.notesInfo = async () =>
-    [
-      {
-        noteId: 42,
-        fields: {
-          Expression: { value: 'taberu' },
-          Sentence: { value: '' },
-          IsWordAndSentenceCard: { value: '' },
-          IsSentenceCard: { value: '' },
-          IsAudioCard: { value: '' },
-        },
-      },
-    ] satisfies NoteUpdateWorkflowNoteInfo[];
-
-  await harness.workflow.execute(42);
-
-  assert.equal(harness.updates.length, 1);
-  assert.deepEqual(harness.updates[0]?.fields, {
-    Sentence: 'subtitle-text',
-  });
-});
-
-test('NoteUpdateWorkflow preserves explicit sentence card type during sentence enrichment', async () => {
-  const harness = createWorkflowHarness();
-  harness.deps.getEffectiveSentenceCardConfig = () => ({
-    sentenceField: 'Sentence',
-    lapisEnabled: true,
-    kikuEnabled: false,
-    fieldGroupingMode: 'disabled',
-  });
-  harness.deps.client.notesInfo = async () =>
-    [
-      {
-        noteId: 42,
-        fields: {
-          Expression: { value: 'sentence expression' },
-          Sentence: { value: '' },
-          IsWordAndSentenceCard: { value: '' },
-          IsSentenceCard: { value: 'x' },
-          IsAudioCard: { value: '' },
-        },
-      },
-    ] satisfies NoteUpdateWorkflowNoteInfo[];
-
-  await harness.workflow.execute(42);
-
-  assert.equal(harness.updates.length, 1);
-  assert.deepEqual(harness.updates[0]?.fields, {
-    Sentence: 'subtitle-text',
-  });
-});
-
 test('NoteUpdateWorkflow no-ops when note info is missing', async () => {
   const harness = createWorkflowHarness();
   harness.deps.client.notesInfo = async () => [];

src/ci-workflow.test.ts

@@ -1,74 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-const ciWorkflowPath = resolve(__dirname, '../.github/workflows/ci.yml');
-const ciWorkflow = readFileSync(ciWorkflowPath, 'utf8');
-const docsPagesWorkflowPath = resolve(__dirname, '../.github/workflows/docs-pages.yml');
-const docsPagesWorkflow = readFileSync(docsPagesWorkflowPath, 'utf8');
-const packageJsonPath = resolve(__dirname, '../package.json');
-const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
-  scripts: Record<string, string>;
-};
-
-test('package scripts expose a sharded maintained source coverage lane with lcov output', () => {
-  assert.equal(
-    packageJson.scripts['test:coverage:src'],
-    'bun run build:yomitan && bun run scripts/run-coverage-lane.ts bun-src-full --coverage-dir coverage/test-src',
-  );
-});
-
-test('source and coverage scripts discover the same maintained source lane', () => {
-  const sourceLane = packageJson.scripts['test:src']?.match(/run-test-lane\.mjs\s+([^\s]+)/)?.[1];
-  const coverageLane = packageJson.scripts['test:coverage:src']?.match(
-    /run-coverage-lane\.ts\s+([^\s]+)/,
-  )?.[1];
-
-  assert.equal(sourceLane, 'bun-src-full');
-  assert.equal(coverageLane, sourceLane);
-});
-
-test('environment suite owns launcher smoke execution', () => {
-  assert.match(
-    packageJson.scripts['test:env'] ?? '',
-    /^bun run test:launcher:smoke:src && bun run test:plugin:src && bun run test:immersion:sqlite:src$/,
-  );
-});
-
-test('ci delegates its gate instead of duplicating quality steps', () => {
-  assert.match(
-    ciWorkflow,
-    /build-test-audit:\s*\n\s*uses: \.\/\.github\/workflows\/quality-gate\.yml/,
-  );
-  assert.doesNotMatch(ciWorkflow, /oven-sh\/setup-bun/);
-  assert.doesNotMatch(ciWorkflow, /bun run test:coverage:src/);
-  assert.doesNotMatch(ciWorkflow, /bun run test:env/);
-});
-
-test('main docs deploy exists, serializes deploys, and uses Cloudflare credentials', () => {
-  assert.match(docsPagesWorkflow, /name: Docs Pages/);
-  assert.match(docsPagesWorkflow, /branches:\s*\n\s*-\s*main/);
-  assert.match(docsPagesWorkflow, /group:\s*docs-pages-production/);
-  assert.match(docsPagesWorkflow, /CLOUDFLARE_API_TOKEN/);
-  assert.match(docsPagesWorkflow, /CLOUDFLARE_ACCOUNT_ID/);
-  assert.match(docsPagesWorkflow, /CLOUDFLARE_PAGES_PROJECT_NAME/);
-  assert.match(docsPagesWorkflow, /pages deploy \.\.\/\.tmp\/docs-versioned-site/);
-  assert.match(docsPagesWorkflow, /--branch main/);
-});
-
-test('docs deploy syncs frozen archives to R2 and ships the archive Pages Function', () => {
-  assert.doesNotMatch(docsPagesWorkflow, /actions\/cache@/);
-  assert.match(docsPagesWorkflow, /DOCS_ARCHIVE_R2_ACCESS_KEY_ID/);
-  assert.match(docsPagesWorkflow, /DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY/);
-  assert.match(docsPagesWorkflow, /--require-archives/);
-  assert.match(docsPagesWorkflow, /--rebuild-archives=\$\{REBUILD_ARCHIVES\}/);
-  assert.match(docsPagesWorkflow, /workingDirectory: docs-site/);
-});
-
-test('docs deploy skips invalid release tags without failing the workflow', () => {
-  assert.match(docsPagesWorkflow, /id:\s*tag_guard/);
-  assert.match(docsPagesWorkflow, /stable_tag=false/);
-  assert.doesNotMatch(docsPagesWorkflow, /exit 78/);
-  assert.match(docsPagesWorkflow, /if:\s*steps\.tag_guard\.outputs\.stable_tag != 'false'/);
-});

src/cli/help.test.ts

@@ -1,37 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { printHelp } from './help';
-
-test('printHelp includes configured texthooker port', () => {
-  const original = console.log;
-  let output = '';
-  console.log = (value?: unknown) => {
-    output += String(value);
-  };
-
-  try {
-    printHelp(7777);
-  } finally {
-    console.log = original;
-  }
-
-  assert.match(output, /--help\s+Show this help/);
-  assert.match(output, /default: 7777/);
-  assert.match(output, /--launch-mpv.*Launch mpv with SubMiner defaults and exit/);
-  assert.match(output, /--stats\s+Open the stats dashboard in your browser/);
-  assert.match(output, /--open-browser\s+Open texthooker in your default browser/);
-  assert.doesNotMatch(output, /--refresh-known-words/);
-  assert.match(output, /--setup\s+Open first-run setup window/);
-  assert.match(output, /--settings\s+Open SubMiner settings window/);
-  assert.match(output, /--yomitan\s+Open Yomitan settings window/);
-  assert.match(output, /--hachidori\s+Open Hachidori settings window/);
-  assert.match(output, /--mark-watched\s+Mark current video watched and advance playlist/);
-  assert.match(output, /--anilist-status/);
-  assert.match(output, /--anilist-retry-queue/);
-  assert.match(output, /--dictionary/);
-  assert.match(output, /--dictionary-target/);
-  assert.match(output, /--jellyfin\s+Open Jellyfin setup window/);
-  assert.match(output, /--jellyfin-login/);
-  assert.match(output, /--jellyfin-subtitles/);
-  assert.match(output, /--jellyfin-play/);
-});

src/config/definitions/domain-registry.test.ts

@@ -2,17 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import { ResolvedConfig } from '../../types/config';
-import {
-  CONFIG_OPTION_REGISTRY,
-  CONFIG_TEMPLATE_SECTIONS,
-  DEFAULT_CONFIG,
-  DEFAULT_KEYBINDINGS,
-  RUNTIME_OPTION_REGISTRY,
-} from '../definitions';
-import { buildCoreConfigOptionRegistry } from './options-core';
-import { buildImmersionConfigOptionRegistry } from './options-immersion';
-import { buildIntegrationConfigOptionRegistry } from './options-integrations';
-import { buildSubtitleConfigOptionRegistry } from './options-subtitle';
+import { CONFIG_OPTION_REGISTRY, CONFIG_TEMPLATE_SECTIONS, DEFAULT_CONFIG } from '../definitions';
 
 function collectConfigLeafPaths(config: ResolvedConfig): string[] {
   const leaves: string[] = [];
@@ -87,58 +77,6 @@ const UNDOCUMENTED_LEAVES: ReadonlySet<string> = new Set([
   'subtitleStyle.wordSpacing',
 ]);
 
-test('config option registry includes critical paths and has unique entries', () => {
-  const paths = CONFIG_OPTION_REGISTRY.map((entry) => entry.path);
-
-  for (const requiredPath of [
-    'logging.level',
-    'logging.files.mpv',
-    'annotationWebsocket.enabled',
-    'controller.enabled',
-    'controller.scrollPixelsPerSecond',
-    'startupWarmups.lowPowerMode',
-    'updates.channel',
-    'youtube.primarySubLanguages',
-    'subtitleStyle.enableJlpt',
-    'subtitleStyle.autoPauseVideoOnYomitanPopup',
-    'ankiConnect.enabled',
-    'subtitleStyle.nameMatchEnabled',
-    'ankiConnect.media.normalizeAudio',
-    'ankiConnect.media.mirrorMpvVolume',
-    'anilist.characterDictionary.collapsibleSections.description',
-    'mpv.executablePath',
-    'mpv.launchMode',
-    'mpv.profile',
-    'mpv.socketPath',
-    'mpv.backend',
-    'mpv.autoStartSubMiner',
-    'mpv.pauseUntilOverlayReady',
-    'mpv.subminerBinaryPath',
-    'mpv.aniskipEnabled',
-    'mpv.aniskipButtonKey',
-    'yomitan.externalProfilePath',
-    'immersionTracking.enabled',
-  ]) {
-    assert.ok(paths.includes(requiredPath), `missing config path: ${requiredPath}`);
-  }
-
-  assert.equal(new Set(paths).size, paths.length);
-});
-
-test('known-word annotation color has one public config path', () => {
-  const leaves = collectConfigLeafPaths(DEFAULT_CONFIG);
-
-  assert.ok(leaves.includes('subtitleStyle.knownWordColor'));
-  assert.ok(!leaves.includes('ankiConnect.knownWords.color'));
-});
-
-test('n+1 annotation color has one public config path', () => {
-  const leaves = collectConfigLeafPaths(DEFAULT_CONFIG);
-
-  assert.ok(leaves.includes('subtitleStyle.nPlusOneColor'));
-  assert.ok(!leaves.includes('ankiConnect.nPlusOne.color'));
-});
-
 test('every DEFAULT_CONFIG leaf is in CONFIG_OPTION_REGISTRY or UNDOCUMENTED_LEAVES', () => {
   const registryPaths = new Set(CONFIG_OPTION_REGISTRY.map((entry) => entry.path));
   const leaves = collectConfigLeafPaths(DEFAULT_CONFIG);
@@ -168,77 +106,10 @@ test('every DEFAULT_CONFIG leaf is in CONFIG_OPTION_REGISTRY or UNDOCUMENTED_LEA
   );
 });
 
-test('config template sections include expected domains and unique keys', () => {
+test('config option paths and template section keys are unique', () => {
+  const paths = CONFIG_OPTION_REGISTRY.map((entry) => entry.path);
+  assert.equal(new Set(paths).size, paths.length);
+
   const keys = CONFIG_TEMPLATE_SECTIONS.map((section) => section.key);
-  const requiredKeys: (typeof keys)[number][] = [
-    'websocket',
-    'annotationWebsocket',
-    'controller',
-    'startupWarmups',
-    'youtube',
-    'subtitleStyle',
-    'ankiConnect',
-    'yomitan',
-    'mpv',
-    'immersionTracking',
-  ];
-
-  for (const requiredKey of requiredKeys) {
-    assert.ok(keys.includes(requiredKey), `missing template section key: ${requiredKey}`);
-  }
-
   assert.equal(new Set(keys).size, keys.length);
 });
-
-test('domain registry builders each contribute entries to composed registry', () => {
-  const domainEntries = [
-    buildCoreConfigOptionRegistry(DEFAULT_CONFIG),
-    buildSubtitleConfigOptionRegistry(DEFAULT_CONFIG),
-    buildIntegrationConfigOptionRegistry(DEFAULT_CONFIG, RUNTIME_OPTION_REGISTRY),
-    buildImmersionConfigOptionRegistry(DEFAULT_CONFIG),
-  ];
-  const composedPaths = new Set(CONFIG_OPTION_REGISTRY.map((entry) => entry.path));
-
-  for (const entries of domainEntries) {
-    assert.ok(entries.length > 0);
-    assert.ok(entries.some((entry) => composedPaths.has(entry.path)));
-  }
-});
-
-test('default keybindings include primary and secondary subtitle track cycling on J keys', () => {
-  const keybindingMap = new Map(
-    DEFAULT_KEYBINDINGS.map((binding) => [binding.key, binding.command]),
-  );
-  assert.deepEqual(keybindingMap.get('KeyJ'), ['cycle', 'sid']);
-  assert.deepEqual(keybindingMap.get('Shift+KeyJ'), ['cycle', 'secondary-sid']);
-  assert.deepEqual(keybindingMap.get('Ctrl+Alt+KeyC'), ['__youtube-picker-open']);
-  assert.deepEqual(keybindingMap.get('Ctrl+Alt+KeyP'), ['__playlist-browser-open']);
-});
-
-test('default keybindings include fullscreen on F', () => {
-  const keybindingMap = new Map(
-    DEFAULT_KEYBINDINGS.map((binding) => [binding.key, binding.command]),
-  );
-  assert.deepEqual(keybindingMap.get('KeyF'), ['cycle', 'fullscreen']);
-});
-
-test('default keybindings include replay and next subtitle controls', () => {
-  const keybindingMap = new Map(
-    DEFAULT_KEYBINDINGS.map((binding) => [binding.key, binding.command]),
-  );
-  assert.deepEqual(keybindingMap.get('Ctrl+Shift+KeyH'), ['__replay-subtitle']);
-  assert.deepEqual(keybindingMap.get('Ctrl+Shift+KeyL'), ['__play-next-subtitle']);
-});
-
-test('default keybindings mirror mpv subtitle delay and sub-step keys', () => {
-  const keybindingMap = new Map(
-    DEFAULT_KEYBINDINGS.map((binding) => [binding.key, binding.command]),
-  );
-  assert.deepEqual(keybindingMap.get('KeyZ'), ['add', 'sub-delay', -0.1]);
-  assert.deepEqual(keybindingMap.get('Shift+KeyZ'), ['add', 'sub-delay', 0.1]);
-  assert.deepEqual(keybindingMap.get('KeyX'), ['add', 'sub-delay', 0.1]);
-  assert.deepEqual(keybindingMap.get('Ctrl+Shift+ArrowLeft'), ['sub-step', -1]);
-  assert.deepEqual(keybindingMap.get('Ctrl+Shift+ArrowRight'), ['sub-step', 1]);
-  assert.equal(keybindingMap.has('Shift+BracketLeft'), false);
-  assert.equal(keybindingMap.has('Shift+BracketRight'), false);
-});

src/config/settings/registry.test.ts

@@ -11,209 +11,6 @@ function field(path: string) {
   return match;
 }
 
-test('settings registry splits viewing into appearance and behavior categories', () => {
-  assert.equal(field('subtitleStyle.fontSize').category, 'appearance');
-  assert.equal(field('subtitleStyle.primaryDefaultMode').category, 'behavior');
-  assert.equal(field('subtitleStyle.primaryDefaultMode').section, 'Subtitle Behavior');
-  assert.equal(field('subtitleStyle.primaryVisibleOnYomitanPopup').category, 'behavior');
-  assert.equal(field('subtitleStyle.primaryVisibleOnYomitanPopup').section, 'Subtitle Behavior');
-  assert.equal(field('secondarySub.defaultMode').category, 'behavior');
-  assert.equal(field('subtitlePosition.yPercent').label, 'Subtitle Position');
-  assert.equal(field('subtitleStyle.frequencyDictionary.mode').label, 'Frequency Mode');
-  assert.equal(field('auto_start_overlay').category, 'behavior');
-  assert.equal(field('auto_start_overlay').section, 'Playback Behavior');
-  assert.equal(field('youtube.primarySubLanguages').category, 'behavior');
-  assert.equal(field('youtube.primarySubLanguages').section, 'YouTube Playback Settings');
-  assert.equal(field('mpv.launchMode').category, 'behavior');
-  assert.equal(field('mpv.launchMode').section, 'mpv Playback');
-  assert.equal(field('mpv.profile').category, 'behavior');
-  assert.equal(field('mpv.profile').section, 'mpv Playback');
-  assert.ok(
-    fields.findIndex((candidate) => candidate.configPath === 'subtitleStyle.primaryDefaultMode') <
-      fields.findIndex(
-        (candidate) => candidate.configPath === 'subtitleStyle.primaryVisibleOnYomitanPopup',
-      ),
-  );
-  assert.ok(
-    fields.findIndex(
-      (candidate) => candidate.configPath === 'subtitleStyle.primaryVisibleOnYomitanPopup',
-    ) < fields.findIndex((candidate) => candidate.configPath === 'secondarySub.defaultMode'),
-  );
-});
-
-test('settings registry groups playback startup controls under playback behavior', () => {
-  for (const path of [
-    'subtitleStyle.autoPauseVideoOnHover',
-    'subtitleStyle.autoPauseVideoOnYomitanPopup',
-    'subtitleSidebar.pauseVideoOnHover',
-    'mpv.autoStartSubMiner',
-    'auto_start_overlay',
-    'mpv.pauseUntilOverlayReady',
-  ]) {
-    assert.equal(field(path).category, 'behavior', path);
-    assert.equal(field(path).section, 'Playback Behavior', path);
-  }
-});
-
-test('settings registry moves AniSkip button key into input shortcuts and hot reload', () => {
-  assert.equal(field('mpv.aniskipButtonKey').category, 'input');
-  assert.equal(field('mpv.aniskipButtonKey').section, 'Overlay Shortcuts');
-  assert.equal(field('mpv.aniskipButtonKey').subsection, 'Playback');
-  assert.equal(field('mpv.aniskipButtonKey').control, 'mpv-key');
-  assert.equal(field('mpv.aniskipButtonKey').restartBehavior, 'hot-reload');
-});
-
-test('settings registry exposes character dictionary panel shortcuts dynamically', () => {
-  assert.equal(
-    field('shortcuts.openCharacterDictionaryManager').label,
-    'Open Character Dictionary Manager',
-  );
-  assert.equal(field('shortcuts.openCharacterDictionaryManager').subsection, 'Open Panels');
-});
-
-test('settings registry hides removed modal-only fields', () => {
-  for (const path of [
-    'shortcuts.multiCopyTimeoutMs',
-    'anilist.characterDictionary.profileScope',
-    'jellyfin.directPlayContainers',
-  ]) {
-    assert.equal(
-      fields.some((candidate) => candidate.configPath === path),
-      false,
-      path,
-    );
-  }
-});
-
-test('settings registry orders websocket server immediately after annotation websocket', () => {
-  const integrationSections = [
-    ...new Set(
-      fields
-        .filter((candidate) => candidate.category === 'integrations')
-        .map((candidate) => candidate.section),
-    ),
-  ];
-  const annotationIndex = integrationSections.indexOf('Annotation WebSocket');
-  assert.equal(integrationSections[annotationIndex + 1], 'WebSocket server');
-});
-
-test('settings registry explains websocket auto mode and keeps it disabled by default', () => {
-  assert.equal(field('websocket.enabled').defaultValue, false);
-  assert.equal(
-    field('websocket.enabled').description,
-    'Built-in subtitle WebSocket server mode. Auto starts the built-in server only when mpv_websocket is not detected; otherwise it defers to the plugin.',
-  );
-});
-
-test('settings registry places immersion tracking after other tracking and app sections', () => {
-  const trackingSections = [
-    ...new Set(
-      fields
-        .filter((candidate) => candidate.category === 'tracking-app')
-        .map((candidate) => candidate.section),
-    ),
-  ];
-  assert.equal(trackingSections.at(-1), 'Immersion tracking');
-});
-
-test('settings registry groups annotation display fields by config group', () => {
-  assert.equal(field('ankiConnect.knownWords.highlightEnabled').section, 'Annotation Display');
-  assert.equal(field('ankiConnect.knownWords.highlightEnabled').subsection, 'Known Words');
-  assert.equal(field('subtitleStyle.knownWordColor').subsection, 'Known Words');
-  assert.equal(field('subtitleStyle.nPlusOneColor').subsection, 'N+1');
-  assert.equal(field('subtitleStyle.enableJlpt').subsection, 'JLPT');
-  assert.equal(field('subtitleStyle.jlptColors.N1').control, 'color');
-});
-
-test('settings registry groups maturity settings under Known Words with color controls', () => {
-  assert.equal(field('ankiConnect.knownWords.maturityEnabled').subsection, 'Known Words');
-  assert.equal(field('ankiConnect.knownWords.matureThresholdDays').subsection, 'Known Words');
-  for (const tier of ['new', 'learning', 'young', 'mature']) {
-    const tierField = field(`subtitleStyle.knownWordMaturityColors.${tier}`);
-    assert.equal(tierField.subsection, 'Known Words');
-    assert.equal(tierField.control, 'color');
-  }
-});
-
-test('settings registry orders maturity colors from least mature to mature', () => {
-  const knownWordsPaths = fields
-    .filter((candidate) => candidate.subsection === 'Known Words')
-    .map((candidate) => candidate.configPath);
-  assert.deepEqual(knownWordsPaths, [
-    'ankiConnect.knownWords.highlightEnabled',
-    'ankiConnect.knownWords.maturityEnabled',
-    'subtitleStyle.knownWordColor',
-    'ankiConnect.knownWords.matureThresholdDays',
-    'subtitleStyle.knownWordMaturityColors.new',
-    'subtitleStyle.knownWordMaturityColors.learning',
-    'subtitleStyle.knownWordMaturityColors.young',
-    'subtitleStyle.knownWordMaturityColors.mature',
-  ]);
-});
-
-test('settings registry routes known words sync, n+1, and frequency config to behavior', () => {
-  assert.equal(field('ankiConnect.knownWords.addMinedWordsImmediately').category, 'behavior');
-  assert.equal(field('ankiConnect.knownWords.addMinedWordsImmediately').section, 'Known Words');
-  assert.equal(field('ankiConnect.knownWords.decks').category, 'behavior');
-  assert.equal(field('ankiConnect.knownWords.decks').section, 'Known Words');
-  assert.equal(field('ankiConnect.knownWords.matchMode').category, 'behavior');
-  assert.equal(field('ankiConnect.knownWords.matchMode').section, 'Known Words');
-  assert.equal(field('ankiConnect.knownWords.refreshMinutes').category, 'behavior');
-  assert.equal(field('ankiConnect.knownWords.refreshMinutes').section, 'Known Words');
-  assert.equal(field('ankiConnect.nPlusOne.minSentenceWords').category, 'behavior');
-  assert.equal(field('ankiConnect.nPlusOne.minSentenceWords').section, 'N+1');
-  assert.equal(field('subtitleStyle.frequencyDictionary.sourcePath').category, 'behavior');
-  assert.equal(
-    field('subtitleStyle.frequencyDictionary.sourcePath').section,
-    'Frequency Highlighting',
-  );
-  assert.equal(field('subtitleStyle.frequencyDictionary.mode').category, 'behavior');
-  assert.equal(field('subtitleStyle.frequencyDictionary.matchMode').category, 'behavior');
-  assert.equal(field('subtitleStyle.frequencyDictionary.topX').category, 'behavior');
-});
-
-test('settings registry exposes mpv aniskip button as an mpv key learn control', () => {
-  assert.equal(field('mpv.aniskipButtonKey').control, 'mpv-key');
-});
-
-test('settings registry exposes specialized controls for config-assisted inputs', () => {
-  assert.equal(field('ankiConnect.deck').control, 'anki-deck');
-  assert.equal(field('ankiConnect.knownWords.decks').control, 'known-words-decks');
-  assert.equal(field('ankiConnect.isLapis.sentenceCardModel').control, 'anki-note-type');
-  assert.equal(field('ankiConnect.fields.word').control, 'anki-field');
-  assert.equal(field('keybindings').control, 'mpv-keybindings');
-  assert.equal(field('subtitleStyle.css').control, 'css-declarations');
-  assert.equal(field('subtitleStyle.secondary.css').control, 'css-declarations');
-  assert.equal(field('shortcuts.copySubtitle').control, 'keyboard-shortcut');
-  assert.equal(field('mpv.aniskipButtonKey').control, 'mpv-key');
-  assert.equal(field('subtitleSidebar.css').control, 'css-declarations');
-  assert.equal(field('stats.toggleKey').control, 'key-code');
-  assert.equal(field('discordPresence.presenceStyle').control, 'select');
-});
-
-test('settings registry exposes mpv volume mirroring as a mining toggle', () => {
-  const volumeField = field('ankiConnect.media.mirrorMpvVolume');
-
-  assert.equal(volumeField.category, 'mining-anki');
-  assert.equal(volumeField.section, 'Media Capture');
-  assert.equal(volumeField.control, 'boolean');
-  assert.equal(volumeField.defaultValue, true);
-});
-
-test('settings registry exposes YouTube media cache mode as a labeled select', () => {
-  const mediaCacheMode = field('youtube.mediaCache.mode');
-  const mediaCacheMaxHeight = field('youtube.mediaCache.maxHeight');
-
-  assert.equal(mediaCacheMode.control, 'select');
-  assert.deepEqual(mediaCacheMode.enumValues, ['direct', 'background']);
-  assert.deepEqual(mediaCacheMode.enumLabels, {
-    direct: 'Direct stream extraction',
-    background: 'Background media cache',
-  });
-  assert.equal(mediaCacheMaxHeight.control, 'number');
-  assert.equal(mediaCacheMaxHeight.defaultValue, 720);
-});
-
 test('settings registry exposes css declaration editor for primary and secondary subtitle appearance', () => {
   const primaryVisible = fields
     .filter(
@@ -268,18 +65,6 @@ test('settings registry exposes css declaration editor for subtitle sidebar appe
   assert.equal(field('subtitleSidebar.layout').settingsHidden, false);
 });
 
-test('settings registry routes playback-related integrations into integrations', () => {
-  assert.equal(field('jimaku.apiBaseUrl').category, 'integrations');
-  assert.equal(field('jimaku.apiBaseUrl').section, 'Jimaku');
-  assert.equal(field('subsync.replace').category, 'integrations');
-  assert.equal(field('subsync.replace').section, 'Subtitle Sync');
-  assert.equal(field('tsukihime.apiBaseUrl').category, 'integrations');
-  assert.equal(field('tsukihime.apiBaseUrl').section, 'TsukiHime');
-  assert.equal(field('tmdb.apiKey').category, 'integrations');
-  assert.equal(field('tmdb.apiKey').section, 'TMDB');
-  assert.equal(field('tmdb.apiKey').secret, true);
-});
-
 test('settings registry puts feature toggles first, then other toggles alphabetically', () => {
   const ankiConnect = fields.filter((candidate) => candidate.section === 'AnkiConnect');
   assert.equal(ankiConnect[0]?.configPath, 'ankiConnect.enabled');
@@ -309,89 +94,3 @@ test('settings registry puts feature toggles first, then other toggles alphabeti
     ['ankiConnect.isLapis.enabled', 'ankiConnect.isKiku.enabled', 'ankiConnect.isSenren.enabled'],
   );
 });
-
-test('settings registry hides app-managed and inactive config surfaces', () => {
-  const paths = new Set(fields.map((candidate) => candidate.configPath));
-  for (const hiddenPath of [
-    'ai.enabled',
-    'ai.apiKey',
-    'ai.apiKeyCommand',
-    'ai.model',
-    'ai.baseUrl',
-    'ai.systemPrompt',
-    'ai.requestTimeoutMs',
-    'ankiConnect.ai.enabled',
-    'ankiConnect.ai.model',
-    'ankiConnect.ai.systemPrompt',
-    'ankiConnect.fields.translation',
-    'controller.bindings',
-    'controller.preferredGamepadId',
-    'controller.preferredGamepadLabel',
-    'controller.profiles',
-    'jellyfin.defaultLibraryId',
-    'subtitleSidebar.toggleKey',
-    'jellyfin.recentServers',
-  ]) {
-    assert.equal(paths.has(hiddenPath), false, `${hiddenPath} should be hidden`);
-  }
-  assert.equal(paths.has('anilist.characterDictionary.enabled'), false);
-});
-
-test('settings registry marks safe live config paths as hot-reloadable', () => {
-  for (const path of [
-    'mpv.aniskipButtonKey',
-    'stats.toggleKey',
-    'stats.markWatchedKey',
-    'logging.level',
-    'logging.rotation',
-    'logging.files.app',
-    'logging.files.launcher',
-    'logging.files.mpv',
-    'youtube.primarySubLanguages',
-    'jimaku.apiBaseUrl',
-    'jimaku.languagePreference',
-    'jimaku.maxEntryResults',
-    'subsync.replace',
-    'ankiConnect.behavior.autoUpdateNewCards',
-    'ankiConnect.deck',
-    'ankiConnect.media.normalizeAudio',
-    'ankiConnect.media.mirrorMpvVolume',
-    'ankiConnect.media.reviewTiming',
-    'ankiConnect.knownWords.highlightEnabled',
-    'ankiConnect.knownWords.refreshMinutes',
-    'ankiConnect.knownWords.addMinedWordsImmediately',
-    'ankiConnect.knownWords.matchMode',
-    'ankiConnect.knownWords.decks',
-    'ankiConnect.nPlusOne.enabled',
-    'ankiConnect.nPlusOne.minSentenceWords',
-    'ankiConnect.fields.word',
-    'ankiConnect.fields.audio',
-    'ankiConnect.fields.wordAudio',
-    'ankiConnect.fields.image',
-    'ankiConnect.fields.sentence',
-    'ankiConnect.fields.miscInfo',
-    'ankiConnect.isLapis.sentenceCardModel',
-    'ankiConnect.isKiku.fieldGrouping',
-    'ankiConnect.isSenren.fieldGrouping',
-  ]) {
-    assert.equal(field(path).restartBehavior, 'hot-reload', path);
-  }
-});
-
-test('settings registry does not expose removed subsync mode option', () => {
-  const paths = new Set(fields.map((candidate) => candidate.configPath));
-  assert.equal(paths.has('subsync.defaultMode'), false);
-});
-
-test('settings registry keeps unsafe config siblings restart-required', () => {
-  for (const path of [
-    'stats.serverPort',
-    'ankiConnect.url',
-    'ankiConnect.proxy.enabled',
-    'mpv.socketPath',
-    'mpv.profile',
-    'websocket.port',
-  ]) {
-    assert.equal(field(path).restartBehavior, 'restart', path);
-  }
-});

src/core/services/__tests__/immersion-tracker-write-queue.test.ts

@@ -5,30 +5,6 @@ import os from 'node:os';
 import path from 'node:path';
 import type { DatabaseSync } from '../immersion-tracker/sqlite';
 
-type ImmersionTrackerService = import('../immersion-tracker-service').ImmersionTrackerService;
-type ImmersionTrackerServiceCtor =
-  typeof import('../immersion-tracker-service').ImmersionTrackerService;
-
-let trackerCtor: ImmersionTrackerServiceCtor | null = null;
-
-async function loadTrackerCtor(): Promise<ImmersionTrackerServiceCtor> {
-  if (trackerCtor) return trackerCtor;
-  const mod = await import('../immersion-tracker-service');
-  trackerCtor = mod.ImmersionTrackerService;
-  return trackerCtor;
-}
-
-function makeDbPath(): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-write-queue-test-'));
-  return path.join(dir, 'immersion.sqlite');
-}
-
-function cleanupDbPath(dbPath: string): void {
-  const dir = path.dirname(dbPath);
-  if (!fs.existsSync(dir)) return;
-  fs.rmSync(dir, { recursive: true, force: true });
-}
-
 interface TrackerInternals {
   db: DatabaseSync;
   queue: unknown[];
@@ -42,155 +18,38 @@ interface TrackerInternals {
   writeLock: { locked: boolean };
 }
 
-test('delete maintenance fails closed when queued writes cannot drain', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-  let deleteRunnerCalls = 0;
+interface TrackerHarness {
+  tracker: TrackerInternals;
+  deleteRunnerCalls: () => number;
+}
 
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor(
-      { dbPath, policy: { batchSize: 2 } },
+/** Runs `fn` against a fresh tracker (batchSize 2) seeded with two library entries. */
+async function withTracker(fn: (harness: TrackerHarness) => Promise<void>): Promise<void> {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-write-queue-test-'));
+  const { ImmersionTrackerService } = await import('../immersion-tracker-service');
+  let deleteRunnerCalls = 0;
+  const service = new ImmersionTrackerService(
+    { dbPath: path.join(dir, 'immersion.sqlite'), policy: { batchSize: 2 } },
     {
       runDeleteMaintenanceTask: async () => {
         deleteRunnerCalls += 1;
       },
     },
   );
-    const internals = tracker as unknown as TrackerInternals;
-    seedTwoEntries(internals.db);
-    queueSubtitleLines(internals, 1);
-    let flushCalls = 0;
-    internals.flushNow = () => {
-      flushCalls += 1;
-      if (flushCalls > 1) throw new Error('bounded no-progress sentinel');
-    };
-
-    await assert.rejects(internals.deleteSession(1), /queue did not drain/i);
-
-    assert.equal(flushCalls, 1);
-    assert.equal(deleteRunnerCalls, 0);
-    assert.equal(internals.writeLock.locked, false);
-  } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
-  }
-});
-
-test('reassignAnimeAnilist fails closed before resolving a conflict when writes cannot drain', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-
   try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
-    const internals = tracker as unknown as TrackerInternals;
-    seedTwoEntries(internals.db);
-    internals.db.prepare('UPDATE imm_anime SET anilist_id = 123 WHERE anime_id = 2').run();
-    queueSubtitleLines(internals, 1);
-    internals.flushNow = () => {};
-
-    await assert.rejects(
-      internals.reassignAnimeAnilist(1, { anilistId: 123 }),
-      /queue did not drain/i,
-    );
-
-    assert.deepEqual(
-      internals.db
-        .prepare(
-          'SELECT anime_id AS animeId, anilist_id AS anilistId FROM imm_anime ORDER BY anime_id',
-        )
-        .all(),
-      [
-        { animeId: 1, anilistId: null },
-        { animeId: 2, anilistId: 123 },
-      ],
-    );
+    const tracker = service as unknown as TrackerInternals;
+    seedTwoEntries(tracker.db);
+    await fn({ tracker, deleteRunnerCalls: () => deleteRunnerCalls });
   } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
+    service.destroy();
+    fs.rmSync(dir, { recursive: true, force: true });
   }
-});
-
-test('mergeAnime fails closed when queued writes cannot drain', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
-    const internals = tracker as unknown as TrackerInternals;
-    seedTwoEntries(internals.db);
-    queueSubtitleLines(internals, 1);
-    internals.flushNow = () => {};
-
-    await assert.rejects(internals.mergeAnime(1, [2]), /queue did not drain/i);
-
-    assert.deepEqual(
-      internals.db
-        .prepare('SELECT anime_id AS animeId FROM imm_anime ORDER BY anime_id')
-        .all()
-        .map((row) => (row as { animeId: number }).animeId),
-      [1, 2],
-    );
-  } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
 }
-});
-
-test('moveVideoToAnime fails closed when queued writes cannot drain', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
-    const internals = tracker as unknown as TrackerInternals;
-    seedTwoEntries(internals.db);
-    queueSubtitleLines(internals, 1);
-    internals.flushNow = () => {};
-
-    await assert.rejects(internals.moveVideoToAnime(2, 1), /queue did not drain/i);
-    assert.equal(
-      (
-        internals.db
-          .prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = 2')
-          .get() as {
-          animeId: number;
-        }
-      ).animeId,
-      2,
-    );
-  } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
-  }
-});
-
-test('rebuildLifetimeSummaries fails closed when queued writes cannot drain', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
-    const internals = tracker as unknown as TrackerInternals;
-    seedTwoEntries(internals.db);
-    queueSubtitleLines(internals, 1);
-    internals.flushNow = () => {};
-
-    await assert.rejects(internals.rebuildLifetimeSummaries(), /queue did not drain/i);
-  } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
-  }
-});
 
 function seedTwoEntries(db: DatabaseSync): void {
   db.exec(`
-    INSERT INTO imm_anime (anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
-      VALUES (1, 'show', 'Show', 1000, 1000), (2, 'show season 1', 'Show Season 1', 1000, 1000);
+    INSERT INTO imm_anime (anime_id, normalized_title_key, canonical_title, anilist_id, CREATED_DATE, LAST_UPDATE_DATE)
+      VALUES (1, 'show', 'Show', NULL, 1000, 1000), (2, 'show season 1', 'Show Season 1', 123, 1000, 1000);
     INSERT INTO imm_videos (video_id, video_key, canonical_title, anime_id, source_type, watched, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
       VALUES (1, 'local:/tmp/a.mkv', 'A', 1, 1, 0, 1440000, 1000, 1000),
              (2, 'local:/tmp/b.mkv', 'B', 2, 1, 0, 1440000, 1000, 1000);
@@ -244,25 +103,53 @@ function queueTelemetry(tracker: TrackerInternals, linesSeen: number): void {
   });
 }
 
-/** The queued telemetry sample only exists in the database once the queue drained fully. */
-function latestTelemetryLinesSeen(db: DatabaseSync, sessionId: number): number | null {
-  const row = db
-    .prepare(
-      `SELECT lines_seen AS linesSeen
-       FROM imm_session_telemetry
-       WHERE session_id = ?
-       ORDER BY sample_ms DESC, telemetry_id DESC
-       LIMIT 1`,
-    )
-    .get(sessionId) as { linesSeen: number } | undefined;
-  return row ? Number(row.linesSeen) : null;
+const SNAPSHOT_TABLES = [
+  'imm_anime',
+  'imm_videos',
+  'imm_sessions',
+  'imm_subtitle_lines',
+  'imm_session_telemetry',
+  'imm_lifetime_global',
+  'imm_lifetime_anime',
+  'imm_lifetime_media',
+  'imm_lifetime_applied_sessions',
+];
+
+function snapshotDb(db: DatabaseSync): Record<string, unknown[]> {
+  return Object.fromEntries(
+    SNAPSHOT_TABLES.map((table) => [table, db.prepare(`SELECT * FROM ${table} ORDER BY 1`).all()]),
+  );
 }
 
-function countLinesForAnime(db: DatabaseSync, animeId: number): number {
-  const row = db
-    .prepare('SELECT COUNT(*) AS total FROM imm_subtitle_lines WHERE anime_id = ?')
-    .get(animeId) as { total: number };
-  return Number(row.total);
+const guardedOperations: Array<{
+  name: string;
+  run: (tracker: TrackerInternals) => Promise<unknown>;
+}> = [
+  { name: 'deleteSession', run: (tracker) => tracker.deleteSession(1) },
+  { name: 'mergeAnime', run: (tracker) => tracker.mergeAnime(1, [2]) },
+  { name: 'moveVideoToAnime', run: (tracker) => tracker.moveVideoToAnime(2, 1) },
+  { name: 'rebuildLifetimeSummaries', run: (tracker) => tracker.rebuildLifetimeSummaries() },
+  {
+    // Anime 2 already owns AniList id 123, so this would otherwise resolve a conflict.
+    name: 'reassignAnimeAnilist',
+    run: (tracker) => tracker.reassignAnimeAnilist(1, { anilistId: 123 }),
+  },
+];
+
+for (const operation of guardedOperations) {
+  test(`${operation.name} fails closed without touching the database when queued writes cannot drain`, async () => {
+    await withTracker(async ({ tracker, deleteRunnerCalls }) => {
+      queueSubtitleLines(tracker, 1);
+      tracker.flushNow = () => {};
+      const before = snapshotDb(tracker.db);
+
+      await assert.rejects(operation.run(tracker), /queue did not drain/i);
+
+      assert.deepEqual(snapshotDb(tracker.db), before);
+      assert.equal(deleteRunnerCalls(), 0);
+      assert.equal(tracker.writeLock.locked, false);
+    });
+  });
 }
 
 /**
@@ -271,52 +158,36 @@ function countLinesForAnime(db: DatabaseSync, animeId: number): number {
  * queue, so anything past `batchSize` would still be unwritten when the merge
  * repoints rows.
  */
-test('mergeAnime drains a queue larger than one batch before repointing rows', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
+const repointingOperations: Array<{
+  name: string;
+  run: (tracker: TrackerInternals) => Promise<unknown>;
+}> = [
+  { name: 'mergeAnime', run: (tracker) => tracker.mergeAnime(1, [2]) },
+  { name: 'moveVideoToAnime', run: (tracker) => tracker.moveVideoToAnime(2, 1) },
+];
 
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
-    const internals = tracker as unknown as TrackerInternals;
+for (const operation of repointingOperations) {
+  test(`${operation.name} drains a queue larger than one batch before repointing rows`, async () => {
+    await withTracker(async ({ tracker }) => {
+      queueSubtitleLines(tracker, 8);
+      queueTelemetry(tracker, 8);
+      assert.ok(tracker.queue.length > 2, 'expected more queued writes than one batch');
 
-    seedTwoEntries(internals.db);
-    queueSubtitleLines(internals, 8);
-    queueTelemetry(internals, 8);
-    assert.ok(internals.queue.length > 2, 'expected more queued writes than one batch');
+      await operation.run(tracker);
 
-    await internals.mergeAnime(1, [2]);
-
-    assert.equal(internals.queue.length, 0);
-    // Every queued line landed, attributed to the surviving entry.
-    assert.equal(countLinesForAnime(internals.db, 1), 8);
-    assert.equal(latestTelemetryLinesSeen(internals.db, 1), 8);
-  } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
-  }
+      assert.equal(tracker.queue.length, 0);
+      // Every queued line and the trailing telemetry sample landed on the surviving entry.
+      const lines = tracker.db
+        .prepare('SELECT COUNT(*) AS total FROM imm_subtitle_lines WHERE anime_id = 1')
+        .get() as { total: number };
+      assert.equal(Number(lines.total), 8);
+      const telemetry = tracker.db
+        .prepare(
+          `SELECT lines_seen AS linesSeen FROM imm_session_telemetry
+           WHERE session_id = 1 ORDER BY sample_ms DESC, telemetry_id DESC LIMIT 1`,
+        )
+        .get() as { linesSeen: number } | undefined;
+      assert.equal(Number(telemetry?.linesSeen), 8);
     });
-
-test('moveVideoToAnime drains a queue larger than one batch before repointing rows', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath, policy: { batchSize: 2 } });
-    const internals = tracker as unknown as TrackerInternals;
-
-    seedTwoEntries(internals.db);
-    queueSubtitleLines(internals, 8);
-    queueTelemetry(internals, 8);
-
-    await internals.moveVideoToAnime(2, 1);
-
-    assert.equal(internals.queue.length, 0);
-    assert.equal(countLinesForAnime(internals.db, 1), 8);
-    assert.equal(latestTelemetryLinesSeen(internals.db, 1), 8);
-  } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
-  }
   });
+}

src/core/services/__tests__/stats-server-route-groups.test.ts

@@ -1,23 +0,0 @@
-import assert from 'node:assert/strict';
-import { describe, test } from 'node:test';
-import {
-  registerStatsAnalyticsRoutes,
-  registerStatsIntegrationRoutes,
-  registerStatsLibraryRoutes,
-  registerStatsMiningRoutes,
-  registerStatsStaticRoutes,
-} from '../stats-server/routes.js';
-
-describe('stats server route groups', () => {
-  test('exposes focused registrars for createStatsApp composition', () => {
-    for (const registrar of [
-      registerStatsAnalyticsRoutes,
-      registerStatsLibraryRoutes,
-      registerStatsIntegrationRoutes,
-      registerStatsMiningRoutes,
-      registerStatsStaticRoutes,
-    ]) {
-      assert.equal(typeof registrar, 'function');
-    }
-  });
-});

src/core/services/anki-jimaku.test.ts

@@ -158,33 +158,6 @@ function createHarness(): RuntimeHarness {
   return { options, registered, state };
 }
 
-test('registerAnkiJimakuIpcRuntime provides full handler surface', () => {
-  const { registered } = createHarness();
-  const expected = [
-    'setAnkiConnectEnabled',
-    'clearAnkiHistory',
-    'refreshKnownWords',
-    'respondFieldGrouping',
-    'buildKikuMergePreview',
-    'getJimakuMediaInfo',
-    'searchJimakuEntries',
-    'listJimakuFiles',
-    'resolveJimakuApiKey',
-    'getCurrentMediaPath',
-    'isRemoteMediaPath',
-    'downloadToFile',
-    'onDownloadedSubtitle',
-    'searchTsukihimeEntries',
-    'listTsukihimeFiles',
-    'downloadTsukihimeSubtitle',
-    'onDownloadedSecondarySubtitle',
-  ];
-
-  for (const key of expected) {
-    assert.equal(typeof registered[key], 'function', `missing handler: ${key}`);
-  }
-});
-
 test('refreshKnownWords throws when integration is unavailable', async () => {
   const { registered } = createHarness();
 
@@ -196,20 +169,6 @@ test('refreshKnownWords throws when integration is unavailable', async () => {
   );
 });
 
-test('refreshKnownWords delegates to integration', async () => {
-  const { registered, state } = createHarness();
-  let refreshed = 0;
-  state.ankiIntegration = {
-    refreshKnownWordCache: async () => {
-      refreshed += 1;
-    },
-  };
-
-  await registered.refreshKnownWords!();
-
-  assert.equal(refreshed, 1);
-});
-
 test('setAnkiConnectEnabled disables active integration and broadcasts changes', () => {
   const { registered, state } = createHarness();
   let destroyed = 0;
@@ -274,30 +233,6 @@ test('buildKikuMergePreview returns guard error when integration is missing', as
   });
 });
 
-test('buildKikuMergePreview delegates to integration when available', async () => {
-  const { registered, state } = createHarness();
-  const calls: unknown[] = [];
-  state.ankiIntegration = {
-    buildFieldGroupingPreview: async (
-      keepNoteId: number,
-      deleteNoteId: number,
-      deleteDuplicate: boolean,
-    ) => {
-      calls.push([keepNoteId, deleteNoteId, deleteDuplicate]);
-      return { ok: true };
-    },
-  };
-
-  const result = await registered.buildKikuMergePreview!({
-    keepNoteId: 3,
-    deleteNoteId: 4,
-    deleteDuplicate: true,
-  });
-
-  assert.deepEqual(calls, [[3, 4, true]]);
-  assert.deepEqual(result, { ok: true });
-});
-
 test('searchJimakuEntries caps results and onDownloadedSubtitle sends sub-add to mpv', async () => {
   const { registered, state } = createHarness();
 

src/core/services/app-ready.test.ts

@@ -103,17 +103,6 @@ test('runAppReadyRuntime starts texthooker on startup when enabled in config', a
   );
 });
 
-test('runAppReadyRuntime creates immersion tracker during heavy startup', async () => {
-  const { deps, calls } = makeDeps({
-    shouldAutoInitializeOverlayRuntimeFromConfig: () => false,
-  });
-
-  await runAppReadyRuntime(deps);
-
-  assert.equal(calls.includes('createImmersionTracker'), false);
-  assert.ok(calls.includes('log:Runtime ready: immersion tracker startup requested.'));
-});
-
 test('runAppReadyRuntime keeps annotation websocket enabled when regular websocket auto-skips', async () => {
   const { deps, calls } = makeDeps({
     getResolvedConfig: () => ({
@@ -226,22 +215,6 @@ test('runAppReadyRuntime skips Jellyfin remote startup when dependency is not wi
   );
 });
 
-test('runAppReadyRuntime logs when createImmersionTracker dependency is missing', async () => {
-  const { deps, calls } = makeDeps({
-    createImmersionTracker: undefined,
-  });
-  await runAppReadyRuntime(deps);
-  assert.ok(calls.includes('log:Runtime ready: immersion tracker dependency is missing.'));
-});
-
-test('runAppReadyRuntime logs defer message when overlay not auto-started', async () => {
-  const { deps, calls } = makeDeps({
-    shouldAutoInitializeOverlayRuntimeFromConfig: () => false,
-  });
-  await runAppReadyRuntime(deps);
-  assert.ok(calls.includes('log:Overlay runtime deferred: waiting for explicit overlay command.'));
-});
-
 test('runAppReadyRuntime applies config logging level during app-ready', async () => {
   const { deps, calls } = makeDeps({
     getResolvedConfig: () => ({

src/core/services/cli-command.test.ts

@@ -1,11 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { CliArgs } from '../../cli/args';
-import {
-  CliCommandServiceDeps,
-  createCliCommandDepsRuntime,
-  handleCliCommand,
-} from './cli-command';
+import { CliCommandServiceDeps, handleCliCommand } from './cli-command';
 
 function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
   return {
@@ -561,136 +557,6 @@ test('handleCliCommand applies socket path and connects on start', () => {
   assert.ok(calls.includes('connectMpvClient'));
 });
 
-test('createCliCommandDepsRuntime reconnects MPV client when reconnect hook exists', () => {
-  const calls: string[] = [];
-  const client = {
-    setSocketPath: (socketPath: string) => {
-      calls.push(`setSocketPath:${socketPath}`);
-    },
-    connect: () => {
-      calls.push('connect');
-    },
-    reconnect: () => {
-      calls.push('reconnect');
-    },
-  };
-  const deps = createCliCommandDepsRuntime({
-    mpv: {
-      getSocketPath: () => '/tmp/runtime.sock',
-      setSocketPath: () => {},
-      getClient: () => client,
-      showOsd: () => {},
-    },
-    texthooker: {
-      service: { isRunning: () => false, start: () => {} },
-      getPort: () => 5174,
-      setPort: () => {},
-      getWebsocketUrl: () => undefined,
-      shouldOpenBrowser: () => false,
-      openInBrowser: () => {},
-    },
-    overlay: {
-      isInitialized: () => true,
-      initialize: () => {},
-      toggleVisible: () => {},
-      togglePrimarySubtitleBar: () => {},
-      setVisible: () => {},
-    },
-    mining: {
-      copyCurrentSubtitle: () => {},
-      startPendingMultiCopy: () => {},
-      mineSentenceCard: async () => {},
-      startPendingMineSentenceMultiple: () => {},
-      updateLastCardFromClipboard: async () => {},
-      refreshKnownWords: async () => {},
-      triggerFieldGrouping: async () => {},
-      triggerSubsyncFromConfig: async () => {},
-      markLastCardAsAudioCard: async () => {},
-    },
-    anilist: {
-      getStatus: () => ({
-        tokenStatus: 'not_checked',
-        tokenSource: 'none',
-        tokenMessage: null,
-        tokenResolvedAt: null,
-        tokenErrorAt: null,
-        queuePending: 0,
-        queueReady: 0,
-        queueDeadLetter: 0,
-        queueLastAttemptAt: null,
-        queueLastError: null,
-      }),
-      clearToken: () => {},
-      openSetup: () => {},
-      getQueueStatus: () => ({
-        pending: 0,
-        ready: 0,
-        deadLetter: 0,
-        lastAttemptAt: null,
-        lastError: null,
-      }),
-      retryQueueNow: async () => ({ ok: true, message: 'ok' }),
-    },
-    dictionary: {
-      generate: async () => ({
-        zipPath: '/tmp/test.zip',
-        fromCache: false,
-        mediaId: 1,
-        mediaTitle: 'Test',
-        entryCount: 0,
-      }),
-      getSelection: async () => ({
-        seriesKey: 'test',
-        guessTitle: null,
-        current: null,
-        override: null,
-        candidates: [],
-      }),
-      setSelection: async () => ({
-        ok: true,
-        seriesKey: 'test',
-        selected: { id: 1, title: 'Test', episodes: null },
-        staleMediaIds: [],
-      }),
-    },
-    jellyfin: {
-      openSetup: () => {},
-      runStatsCommand: async () => {},
-      runCommand: async () => {},
-    },
-    ui: {
-      openFirstRunSetup: () => {},
-      openHachidoriSettings: () => {},
-      openYomitanSettings: () => {},
-      openConfigSettingsWindow: () => {},
-      openSyncUiWindow: () => {},
-      openYoutubeBrowserWindow: () => {},
-      cycleSecondarySubMode: () => {},
-      openRuntimeOptionsPalette: () => {},
-      printHelp: () => {},
-    },
-    app: {
-      stop: () => {},
-      hasMainWindow: () => true,
-      runUpdateCommand: async () => {},
-      runEnsureLinuxRuntimePluginAssetsCommand: async () => {},
-      runYoutubePlaybackFlow: async () => {},
-    },
-    dispatchSessionAction: async () => {},
-    getMultiCopyTimeoutMs: () => 2500,
-    schedule: () => undefined,
-    log: () => {},
-    logDebug: () => {},
-    warn: () => {},
-    error: () => {},
-  });
-
-  deps.setMpvClientSocketPath('/tmp/runtime.sock');
-  deps.connectMpvClient();
-
-  assert.deepEqual(calls, ['setSocketPath:/tmp/runtime.sock', 'reconnect']);
-});
-
 test('handleCliCommand warns when texthooker port override used while running', () => {
   const { deps, calls } = createDeps({
     isTexthookerRunning: () => true,
@@ -887,13 +753,6 @@ test('handleCliCommand dispatches mark-watched session action', async () => {
   });
 });
 
-test('handleCliCommand logs AniList status details', () => {
-  const { deps, calls } = createDeps();
-  handleCliCommand(makeArgs({ anilistStatus: true }), 'initial', deps);
-  assert.ok(calls.some((value) => value.startsWith('log:AniList token status:')));
-  assert.ok(calls.some((value) => value.startsWith('log:AniList queue:')));
-});
-
 test('handleCliCommand runs AniList retry command', async () => {
   const { deps, calls } = createDeps();
   handleCliCommand(makeArgs({ anilistRetryQueue: true }), 'initial', deps);

src/core/services/discord-presence.test.ts

@@ -49,28 +49,6 @@ test('buildDiscordPresenceActivity falls back to idle with default style', () =>
   assert.equal(payload.details, 'Sentence Mining');
 });
 
-test('buildDiscordPresenceActivity uses meme style fallback', () => {
-  const memeConfig = { ...baseConfig, presenceStyle: 'meme' as const };
-  const payload = buildDiscordPresenceActivity(memeConfig, {
-    ...baseSnapshot,
-    connected: false,
-    mediaPath: null,
-  });
-  assert.equal(payload.details, 'Mining and crafting (Anki cards)');
-  assert.equal(payload.smallImageText, 'Sentence Mining');
-});
-
-test('buildDiscordPresenceActivity uses japanese style', () => {
-  const jpConfig = { ...baseConfig, presenceStyle: 'japanese' as const };
-  const payload = buildDiscordPresenceActivity(jpConfig, {
-    ...baseSnapshot,
-    connected: false,
-    mediaPath: null,
-  });
-  assert.equal(payload.details, '文の採掘中');
-  assert.equal(payload.smallImageText, 'イマージョン学習');
-});
-
 test('buildDiscordPresenceActivity uses minimal style', () => {
   const minConfig = { ...baseConfig, presenceStyle: 'minimal' as const };
   const payload = buildDiscordPresenceActivity(minConfig, {

src/core/services/field-grouping-overlay.test.ts

@@ -3,78 +3,6 @@ import assert from 'node:assert/strict';
 import { KikuFieldGroupingChoice } from '../../types';
 import { createFieldGroupingOverlayRuntime } from './field-grouping-overlay';
 
-test('createFieldGroupingOverlayRuntime sends overlay messages and sets restore flag', () => {
-  const sent: unknown[][] = [];
-  let visible = false;
-  const restore = new Set<'runtime-options' | 'subsync'>();
-
-  const runtime = createFieldGroupingOverlayRuntime<'runtime-options' | 'subsync'>({
-    getMainWindow: () => ({
-      isDestroyed: () => false,
-      webContents: {
-        isLoading: () => false,
-        send: (...args: unknown[]) => {
-          sent.push(args);
-        },
-      },
-    }),
-    getVisibleOverlayVisible: () => visible,
-    setVisibleOverlayVisible: (next) => {
-      visible = next;
-    },
-    getResolver: () => null,
-    setResolver: () => {},
-    getRestoreVisibleOverlayOnModalClose: () => restore,
-  });
-
-  const ok = runtime.sendToVisibleOverlay('runtime-options:open', undefined, {
-    restoreOnModalClose: 'runtime-options',
-  });
-
-  assert.equal(ok, true);
-  assert.equal(visible, true);
-  assert.equal(restore.has('runtime-options'), true);
-  assert.deepEqual(sent, [['runtime-options:open']]);
-});
-
-test('createFieldGroupingOverlayRuntime callback cancels when send fails', async () => {
-  let resolver: ((choice: KikuFieldGroupingChoice) => void) | null = null;
-  const runtime = createFieldGroupingOverlayRuntime<'runtime-options' | 'subsync'>({
-    getMainWindow: () => null,
-    getVisibleOverlayVisible: () => false,
-    setVisibleOverlayVisible: () => {},
-    getResolver: () => resolver,
-    setResolver: (next: ((choice: KikuFieldGroupingChoice) => void) | null) => {
-      resolver = next;
-    },
-    getRestoreVisibleOverlayOnModalClose: () => new Set<'runtime-options' | 'subsync'>(),
-  });
-
-  const callback = runtime.createFieldGroupingCallback();
-  const result = await callback({
-    original: {
-      noteId: 1,
-      expression: 'a',
-      sentencePreview: 'a',
-      hasAudio: false,
-      hasImage: false,
-      isOriginal: true,
-    },
-    duplicate: {
-      noteId: 2,
-      expression: 'b',
-      sentencePreview: 'b',
-      hasAudio: false,
-      hasImage: false,
-      isOriginal: false,
-    },
-  });
-
-  assert.equal(result.cancelled, true);
-  assert.equal(result.keepNoteId, 0);
-  assert.equal(result.deleteNoteId, 0);
-});
-
 test('createFieldGroupingOverlayRuntime callback restores hidden visible overlay after resolver settles', async () => {
   let resolver: unknown = null;
   let visible = false;

src/core/services/field-grouping.test.ts

@@ -98,7 +98,13 @@ test('field grouping callback does not reject the next request after a response'
   assert.equal(secondChoice.keepNoteId, 2);
 });
 
-test('field grouping callback dismisses the modal UI when the send fails', async () => {
+const dismissCases = [
+  { name: 'the send fails', sends: false, responseTimeoutMs: undefined },
+  { name: 'the response times out', sends: true, responseTimeoutMs: 5 },
+];
+
+for (const c of dismissCases) {
+  test(`field grouping callback dismisses the modal UI when ${c.name}`, async () => {
     const store = createWrappedResolverStore();
     let dismissed = 0;
     const callback = createFieldGroupingCallback({
@@ -106,10 +112,11 @@ test('field grouping callback dismisses the modal UI when the send fails', async
       setVisibleOverlayVisible: () => {},
       getResolver: store.getResolver,
       setResolver: store.setResolver,
-    sendRequestToVisibleOverlay: () => false,
+      sendRequestToVisibleOverlay: () => c.sends,
       dismissModalUi: () => {
         dismissed += 1;
       },
+      responseTimeoutMs: c.responseTimeoutMs,
     });
 
     const result = await callback(makeRequestData());
@@ -118,7 +125,7 @@ test('field grouping callback dismisses the modal UI when the send fails', async
     assert.equal(store.getResolver(), null);
   });
 
-test('field grouping callback handles modal dismiss failures on send failure', async () => {
+  test(`field grouping callback still cancels and clears the resolver when ${c.name} and dismiss throws`, async () => {
     const store = createWrappedResolverStore();
     const originalConsoleError = console.error;
     console.error = () => {};
@@ -128,10 +135,11 @@ test('field grouping callback handles modal dismiss failures on send failure', a
         setVisibleOverlayVisible: () => {},
         getResolver: store.getResolver,
         setResolver: store.setResolver,
-      sendRequestToVisibleOverlay: () => false,
+        sendRequestToVisibleOverlay: () => c.sends,
         dismissModalUi: () => {
           throw new Error('dismiss failed');
         },
+        responseTimeoutMs: c.responseTimeoutMs,
       });
 
       const result = await callback(makeRequestData());
@@ -142,80 +150,7 @@ test('field grouping callback handles modal dismiss failures on send failure', a
       console.error = originalConsoleError;
     }
   });
-
-test('field grouping callback handles modal dismiss failures on timeout', async () => {
-  const store = createWrappedResolverStore();
-  const originalConsoleError = console.error;
-  console.error = () => {};
-  try {
-    const callback = createFieldGroupingCallback({
-      getVisibleOverlayVisible: () => false,
-      setVisibleOverlayVisible: () => {},
-      getResolver: store.getResolver,
-      setResolver: store.setResolver,
-      sendRequestToVisibleOverlay: () => true,
-      dismissModalUi: () => {
-        throw new Error('dismiss failed');
-      },
-      responseTimeoutMs: 5,
-    });
-
-    const result = await callback(makeRequestData());
-
-    assert.equal(result.cancelled, true);
-    assert.equal(store.getResolver(), null);
-  } finally {
-    console.error = originalConsoleError;
 }
-});
-
-test('field grouping callback reports modal dismiss failures', async () => {
-  const store = createWrappedResolverStore();
-  const errors: unknown[] = [];
-  const originalConsoleError = console.error;
-  console.error = (...args: unknown[]) => {
-    errors.push(args);
-  };
-  try {
-    const callback = createFieldGroupingCallback({
-      getVisibleOverlayVisible: () => false,
-      setVisibleOverlayVisible: () => {},
-      getResolver: store.getResolver,
-      setResolver: store.setResolver,
-      sendRequestToVisibleOverlay: () => false,
-      dismissModalUi: () => {
-        throw new Error('dismiss failed');
-      },
-    });
-
-    await callback(makeRequestData());
-
-    assert.equal(errors.length, 1);
-  } finally {
-    console.error = originalConsoleError;
-  }
-});
-
-test('field grouping callback dismisses the modal UI when the response times out', async () => {
-  const store = createWrappedResolverStore();
-  let dismissed = 0;
-  const callback = createFieldGroupingCallback({
-    getVisibleOverlayVisible: () => false,
-    setVisibleOverlayVisible: () => {},
-    getResolver: store.getResolver,
-    setResolver: store.setResolver,
-    sendRequestToVisibleOverlay: () => true,
-    dismissModalUi: () => {
-      dismissed += 1;
-    },
-    responseTimeoutMs: 5,
-  });
-
-  const result = await callback(makeRequestData());
-  assert.equal(result.cancelled, true);
-  assert.equal(dismissed, 1);
-  assert.equal(store.getResolver(), null);
-});
 
 test('field grouping callback does not dismiss the modal UI on a normal response', async () => {
   const store = createWrappedResolverStore();

src/core/services/hyprland-window-placement.test.ts

@@ -499,36 +499,13 @@ test('ensureHyprlandWindowFloatingByTitle dispatches Lua syntax for Lua-config H
   });
 
   assert.equal(placed, true);
-  assert.deepEqual(
-    calls.map(([, args]) => args),
-    [
-      ['-j', 'clients'],
-      ['-j', 'status'],
-      ['dispatch', 'hl.dsp.window.resize({ x = 1920, y = 1080, window = "address:0xmatch" })'],
-      ['dispatch', 'hl.dsp.window.move({ x = 0, y = 0, window = "address:0xmatch" })'],
-      [
-        'dispatch',
-        'hl.dsp.window.set_prop({ prop = "rounding", value = "0", window = "address:0xmatch" })',
-      ],
-      [
-        'dispatch',
-        'hl.dsp.window.set_prop({ prop = "border_size", value = "0", window = "address:0xmatch" })',
-      ],
-      [
-        'dispatch',
-        'hl.dsp.window.set_prop({ prop = "no_shadow", value = "1", window = "address:0xmatch" })',
-      ],
-      [
-        'dispatch',
-        'hl.dsp.window.set_prop({ prop = "no_blur", value = "1", window = "address:0xmatch" })',
-      ],
-      [
-        'dispatch',
-        'hl.dsp.window.set_prop({ prop = "decorate", value = "0", window = "address:0xmatch" })',
-      ],
-      ['dispatch', 'hl.dsp.window.alter_zorder({ mode = "top", window = "address:0xmatch" })'],
-    ],
-  );
+  const dispatches = calls
+    .map(([, args]) => args as string[])
+    .filter(([verb]) => verb === 'dispatch');
+  assert.ok(dispatches.length > 0);
+  for (const [, dispatcher] of dispatches) {
+    assert.ok(dispatcher!.startsWith('hl.dsp.window.'), dispatcher);
+  }
 });
 
 test('hasHyprlandWindowPlacementBoundsMismatch compares compositor client bounds', () => {

src/core/services/immersion-tracker-service.test.ts

@@ -3,7 +3,6 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { toMonthKey } from './immersion-tracker/maintenance';
 import { enqueueWrite } from './immersion-tracker/queue';
 import { toDbTimestamp } from './immersion-tracker/query-shared';
 import { repairJellyfinStreamVideoLinks } from './immersion-tracker/jellyfin-link-repair';
@@ -137,11 +136,6 @@ test('seam: enqueueWrite drops oldest entries once capacity is exceeded', () =>
   assert.equal((queue[1] as Extract<QueuedWrite, { kind: 'event' }>).eventType, 3);
 });
 
-test('seam: toMonthKey uses UTC calendar month', () => {
-  assert.equal(toMonthKey(-86_400_000), 196912);
-  assert.equal(toMonthKey(0), 197001);
-});
-
 test('startSession generates UUID-like session identifiers', async () => {
   const dbPath = makeDbPath();
   let tracker: ImmersionTrackerService | null = null;
@@ -528,37 +522,6 @@ test('rebuildLifetimeSummaries backfills retained ended sessions and resets stal
   }
 });
 
-test('fresh tracker DB creates lifetime summary tables', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath });
-
-    const db = new Database(dbPath);
-    const tableRows = db
-      .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
-      .all() as Array<{ name: string }>;
-    db.close();
-
-    const tableNames = new Set(tableRows.map((row) => row.name));
-    const expectedTables = [
-      'imm_lifetime_global',
-      'imm_lifetime_anime',
-      'imm_lifetime_media',
-      'imm_lifetime_applied_sessions',
-    ];
-
-    for (const tableName of expectedTables) {
-      assert.ok(tableNames.has(tableName), `Expected ${tableName} to exist`);
-    }
-  } finally {
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('fresh tracker DB skips lexical rollup backfill work', async () => {
   const dbPath = makeDbPath();
   let tracker: ImmersionTrackerService | null = null;
@@ -3773,138 +3736,6 @@ test('monthly rollups are grouped by calendar month', async () => {
   }
 });
 
-test('flushSingle reuses cached prepared statements', async () => {
-  const dbPath = makeDbPath();
-  let tracker: ImmersionTrackerService | null = null;
-  let originalPrepare: DatabaseSync['prepare'] | null = null;
-
-  try {
-    const Ctor = await loadTrackerCtor();
-    tracker = new Ctor({ dbPath });
-    const privateApi = tracker as unknown as {
-      db: DatabaseSync;
-      flushSingle: (write: {
-        kind: 'telemetry' | 'event';
-        sessionId: number;
-        sampleMs: number;
-        eventType?: number;
-        lineIndex?: number | null;
-        segmentStartMs?: number | null;
-        segmentEndMs?: number | null;
-        tokensDelta?: number;
-        cardsDelta?: number;
-        payloadJson?: string | null;
-        totalWatchedMs?: number;
-        activeWatchedMs?: number;
-        linesSeen?: number;
-        tokensSeen?: number;
-        cardsMined?: number;
-        lookupCount?: number;
-        lookupHits?: number;
-        yomitanLookupCount?: number;
-        pauseCount?: number;
-        pauseMs?: number;
-        seekForwardCount?: number;
-        seekBackwardCount?: number;
-        mediaBufferEvents?: number;
-      }) => void;
-    };
-
-    originalPrepare = privateApi.db.prepare;
-    let prepareCalls = 0;
-    privateApi.db.prepare = (...args: Parameters<DatabaseSync['prepare']>) => {
-      prepareCalls += 1;
-      return originalPrepare!.apply(privateApi.db, args);
-    };
-    const preparedRestore = originalPrepare;
-
-    privateApi.db.exec(`
-      INSERT INTO imm_videos (
-        video_id,
-        video_key,
-        canonical_title,
-        source_type,
-        duration_ms,
-        CREATED_DATE,
-        LAST_UPDATE_DATE
-      ) VALUES (
-        1,
-        'local:/tmp/prepared.mkv',
-        'Prepared',
-        1,
-        0,
-        1000,
-        1000
-      )
-    `);
-
-    privateApi.db.exec(`
-      INSERT INTO imm_sessions (
-        session_id,
-        session_uuid,
-        video_id,
-        started_at_ms,
-        status,
-        CREATED_DATE,
-        LAST_UPDATE_DATE,
-        ended_at_ms
-      ) VALUES (
-        1,
-        '33333333-3333-3333-3333-333333333333',
-        1,
-        1000,
-        2,
-        1000,
-        1000,
-        2000
-      )
-    `);
-
-    privateApi.flushSingle({
-      kind: 'telemetry',
-      sessionId: 1,
-      sampleMs: 1500,
-      totalWatchedMs: 1000,
-      activeWatchedMs: 1000,
-      linesSeen: 1,
-      tokensSeen: 2,
-      cardsMined: 0,
-      lookupCount: 0,
-      lookupHits: 0,
-      yomitanLookupCount: 0,
-      pauseCount: 0,
-      pauseMs: 0,
-      seekForwardCount: 0,
-      seekBackwardCount: 0,
-      mediaBufferEvents: 0,
-    });
-
-    privateApi.flushSingle({
-      kind: 'event',
-      sessionId: 1,
-      sampleMs: 1600,
-      eventType: 1,
-      lineIndex: 1,
-      segmentStartMs: 0,
-      segmentEndMs: 1000,
-      tokensDelta: 2,
-      cardsDelta: 0,
-      payloadJson: '{"event":"subtitle-line"}',
-    });
-
-    privateApi.db.prepare = preparedRestore;
-
-    assert.equal(prepareCalls, 0);
-  } finally {
-    if (tracker && originalPrepare) {
-      const privateApi = tracker as unknown as { db: DatabaseSync };
-      privateApi.db.prepare = originalPrepare;
-    }
-    tracker?.destroy();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('reassignAnimeAnilist deduplicates cover blobs and getCoverArt remains compatible', async () => {
   const dbPath = makeDbPath();
   let tracker: ImmersionTrackerService | null = null;

src/core/services/immersion-tracker/__tests__/lexical-removal.test.ts

@@ -5,8 +5,9 @@ import path from 'node:path';
 import test from 'node:test';
 import { Database } from '../sqlite.js';
 import type { DatabaseSync } from '../sqlite.js';
-import { ensureSchema } from '../storage.js';
+import { createTrackerPreparedStatements, ensureSchema, executeQueuedWrite } from '../storage.js';
 import { deleteSession, deleteSessions, deleteVideo } from '../query-maintenance.js';
+import { pruneRawRetention } from '../maintenance.js';
 
 const DAY_MS = 86_400_000;
 const BASE_MS = 1_700_000_000_000;
@@ -30,7 +31,13 @@ function cleanupDbPath(dbPath: string): void {
  */
 function seed(
   db: DatabaseSync,
-  lines: Array<{ session: 1 | 2; wordId: number; dayOffset: number; count?: number }>,
+  lines: Array<{
+    session: 1 | 2;
+    wordId: number;
+    dayOffset: number;
+    msOffset?: number;
+    count?: number;
+  }>,
   options: { legacyRows?: boolean } = {},
 ): void {
   db.exec(`
@@ -65,7 +72,7 @@ function seed(
   let lineId = 0;
   for (const line of lines) {
     lineId += 1;
-    const seenMs = BASE_MS + line.dayOffset * DAY_MS;
+    const seenMs = BASE_MS + line.dayOffset * DAY_MS + (line.msOffset ?? 0);
     insertLine.run(lineId, line.session, line.session, lineId, `line ${lineId}`, seenMs, seenMs);
     insertWord.run(line.wordId, `語${line.wordId}`, `語${line.wordId}`);
     if (options.legacyRows) {
@@ -83,13 +90,13 @@ function seed(
         FROM imm_word_line_occurrences o WHERE o.word_id = imm_words.id
       ),
       first_seen = (
-        SELECT MIN(sl.CREATED_DATE) / 1000
+        SELECT MIN(sl.CREATED_DATE) / 1000.0
         FROM imm_word_line_occurrences o
         JOIN imm_subtitle_lines sl ON sl.line_id = o.line_id
         WHERE o.word_id = imm_words.id
       ),
       last_seen = (
-        SELECT MAX(sl.LAST_UPDATE_DATE) / 1000
+        SELECT MAX(sl.LAST_UPDATE_DATE) / 1000.0
         FROM imm_word_line_occurrences o
         JOIN imm_subtitle_lines sl ON sl.line_id = o.line_id
         WHERE o.word_id = imm_words.id
@@ -200,6 +207,167 @@ test('deleting the latest session moves last_seen back to the surviving line', (
   }
 });
 
+for (const legacyRows of [false, true]) {
+  test(`deleting the latest session keeps fractional seen timestamps exact (legacyRows=${legacyRows})`, () => {
+    // Stored seen values are fractional seconds; whole-second rounding used to miss
+    // the removed extreme (or truncate the refreshed one).
+    const { db, dbPath } = createDb(
+      [
+        { session: 1, wordId: 22, dayOffset: 0, msOffset: 251 },
+        { session: 2, wordId: 22, dayOffset: 5, msOffset: 882 },
+      ],
+      { legacyRows },
+    );
+
+    try {
+      deleteSession(db, 2);
+
+      const word = readWord(db, 22);
+      assert.equal(word?.frequency, 1);
+      assert.equal(word?.firstSeen, (BASE_MS + 251) / 1000);
+      assert.equal(word?.lastSeen, (BASE_MS + 251) / 1000);
+    } finally {
+      db.close();
+      cleanupDbPath(dbPath);
+    }
+  });
+}
+
+test('deleting legacy history preserves first_seen when it predates the flush timestamp', () => {
+  const { db, dbPath } = createDb([
+    { session: 1, wordId: 23, dayOffset: 0, msOffset: 400 },
+    { session: 2, wordId: 23, dayOffset: 5, msOffset: 400 },
+  ]);
+
+  try {
+    // A queue delay and retention-pruned history cannot be distinguished from
+    // the old flush-time timestamp. Preserve the earlier date in either case.
+    db.prepare('UPDATE imm_words SET first_seen = ? WHERE id = 23').run(BASE_MS / 1000);
+
+    deleteSession(db, 1);
+
+    assert.equal(readWord(db, 23)?.firstSeen, BASE_MS / 1000);
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
+for (const legacyRows of [false, true]) {
+  for (const deletedSession of [2, 3]) {
+    test(`deleting retained session ${deletedSession} preserves pruned first_seen (legacyRows=${legacyRows})`, () => {
+      const { db, dbPath } = createDb(
+        [
+          { session: 1, wordId: 24, dayOffset: 0 },
+          { session: 2, wordId: 24, dayOffset: 1 },
+        ],
+        { legacyRows },
+      );
+
+      try {
+        const latestMs = BASE_MS + 2 * DAY_MS;
+        db.exec(`
+          INSERT INTO imm_sessions(session_id, session_uuid, video_id, started_at_ms, ended_at_ms, status, CREATED_DATE, LAST_UPDATE_DATE)
+            VALUES (3, 's3', 2, '${latestMs}', '${latestMs + 1000}', 2, ${latestMs}, ${latestMs});
+          INSERT INTO imm_subtitle_lines(line_id, session_id, video_id, line_index, text, CREATED_DATE, LAST_UPDATE_DATE)
+            VALUES (3, 3, 2, 3, '猫', ${latestMs}, ${latestMs});
+          INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count, seen_ms)
+            VALUES (3, 24, 1, ${legacyRows ? 'NULL' : latestMs});
+          UPDATE imm_words SET frequency = 3, last_seen = ${latestMs / 1000} WHERE id = 24;
+          INSERT INTO imm_kanji(id, kanji, first_seen, last_seen, frequency)
+            SELECT 24, '猫', first_seen, last_seen, frequency FROM imm_words WHERE id = 24;
+          INSERT INTO imm_kanji_line_occurrences(line_id, kanji_id, occurrence_count, seen_ms)
+            SELECT line_id, 24, occurrence_count, seen_ms FROM imm_word_line_occurrences WHERE word_id = 24;
+        `);
+        pruneRawRetention(db, latestMs, {
+          eventsRetentionMs: Infinity,
+          telemetryRetentionMs: Infinity,
+          sessionsRetentionMs: 1.5 * DAY_MS,
+        });
+
+        deleteSession(db, deletedSession);
+
+        for (const table of ['imm_words', 'imm_kanji']) {
+          const row = db
+            .prepare(
+              `SELECT frequency, first_seen AS firstSeen, last_seen AS lastSeen FROM ${table} WHERE id = 24`,
+            )
+            .get() as { frequency: number; firstSeen: number; lastSeen: number };
+          assert.equal(row.frequency, 2);
+          assert.equal(row.firstSeen, BASE_MS / 1000, `${table} keeps the pruned discovery date`);
+          assert.equal(row.lastSeen, (BASE_MS + (deletedSession === 2 ? 2 : 1) * DAY_MS) / 1000);
+        }
+      } finally {
+        db.close();
+        cleanupDbPath(dbPath);
+      }
+    });
+  }
+}
+
+test('deleting a queued subtitle uses observation time despite a delayed flush', () => {
+  const { db, dbPath } = createDb([]);
+
+  try {
+    const stmts = createTrackerPreparedStatements(db);
+    for (const sessionId of [1, 2]) {
+      const seenMs = BASE_MS + (sessionId - 1) * DAY_MS + 400;
+      executeQueuedWrite(
+        {
+          kind: 'subtitleLine',
+          sessionId,
+          videoId: sessionId,
+          lineIndex: 1,
+          segmentStartMs: null,
+          segmentEndMs: null,
+          text: '猫',
+          wordOccurrences: [
+            {
+              headword: '猫',
+              word: '猫',
+              reading: 'ねこ',
+              partOfSpeech: 'noun',
+              pos1: '名詞',
+              pos2: '一般',
+              pos3: '',
+              occurrenceCount: 1,
+              frequencyRank: null,
+            },
+          ],
+          kanjiOccurrences: [{ kanji: '猫', occurrenceCount: 1 }],
+          firstSeen: seenMs / 1000,
+          lastSeen: seenMs / 1000,
+        },
+        stmts,
+      );
+      for (const table of ['imm_word_line_occurrences', 'imm_kanji_line_occurrences']) {
+        const row = db
+          .prepare(`SELECT seen_ms AS seenMs FROM ${table} WHERE line_id = ?`)
+          .get(sessionId) as { seenMs: number };
+        assert.equal(row.seenMs, seenMs);
+      }
+    }
+
+    deleteSession(db, 1);
+
+    for (const table of ['imm_words', 'imm_kanji']) {
+      const row = db
+        .prepare(`SELECT frequency, first_seen AS firstSeen, last_seen AS lastSeen FROM ${table}`)
+        .get() as {
+        frequency: number;
+        firstSeen: number;
+        lastSeen: number;
+      };
+      assert.equal(row.frequency, 1);
+      assert.equal(row.firstSeen, (BASE_MS + DAY_MS + 400) / 1000);
+      assert.equal(row.lastSeen, (BASE_MS + DAY_MS + 400) / 1000);
+    }
+  } finally {
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
+
 test('deleting an interior occurrence leaves the surrounding extremes untouched', () => {
   // Session 2 carries the middle occurrence; sessions bracket it in time.
   const { db, dbPath } = createDb([

src/core/services/immersion-tracker/__tests__/maintenance-source.test.ts

@@ -1,18 +0,0 @@
-import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import path from 'node:path';
-import test from 'node:test';
-
-test('getRollupGroupsForSessions uses only localtime rollup keys', () => {
-  const source = fs.readFileSync(
-    path.join(process.cwd(), 'src/core/services/immersion-tracker/maintenance.ts'),
-    'utf8',
-  );
-  const start = source.indexOf('export function getRollupGroupsForSessions');
-  const end = source.indexOf('export function refreshRollupsForGroupsInTransaction');
-  const functionSource = source.slice(start, end);
-
-  assert.match(functionSource, /'unixepoch', 'localtime'/);
-  assert.doesNotMatch(functionSource, /UNION/);
-  assert.doesNotMatch(functionSource, /86400000/);
-});

src/core/services/immersion-tracker/__tests__/query.test.ts

@@ -602,39 +602,6 @@ test('getSessionTimeline returns the full session when no limit is provided', ()
   }
 });
 
-test('getDailyRollups limits by distinct days (not rows)', () => {
-  const dbPath = makeDbPath();
-  const db = openTestDb(dbPath);
-
-  try {
-    ensureSchema(db);
-
-    const insert = db.prepare(
-      `
-      INSERT INTO imm_daily_rollups (
-        rollup_day, video_id, total_sessions, total_active_min, total_lines_seen,
-        total_tokens_seen, total_cards
-      ) VALUES (?, ?, ?, ?, ?, ?, ?)
-    `,
-    );
-
-    insert.run(10, 1, 1, 1, 0, 0, 2);
-    insert.run(10, 2, 1, 1, 0, 0, 3);
-    insert.run(9, 1, 1, 1, 0, 0, 1);
-    insert.run(8, 1, 1, 1, 0, 0, 1);
-
-    const rows = getDailyRollups(db, 2);
-    assert.equal(rows.length, 3);
-    assert.ok(rows.every((r) => r.rollupDayOrMonth === 10 || r.rollupDayOrMonth === 9));
-    assert.ok(rows.some((r) => r.rollupDayOrMonth === 10 && r.videoId === 1));
-    assert.ok(rows.some((r) => r.rollupDayOrMonth === 10 && r.videoId === 2));
-    assert.ok(rows.some((r) => r.rollupDayOrMonth === 9 && r.videoId === 1));
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('getTrendsDashboard returns chart-ready aggregated series', () => {
   const dbPath = makeDbPath();
   const db = openTestDb(dbPath);
@@ -2075,20 +2042,6 @@ test('getVocabularyStats pages past hidden rows until enough visible rows are co
   }
 });
 
-test('getVocabularyStats returns empty array when no words exist', () => {
-  const dbPath = makeDbPath();
-  const db = openTestDb(dbPath);
-
-  try {
-    ensureSchema(db);
-    const rows = getVocabularyStats(db, 10);
-    assert.deepEqual(rows, []);
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('cleanupVocabularyStats repairs stored POS metadata and removes excluded imm_words rows', async () => {
   const dbPath = makeDbPath();
   const db = openTestDb(dbPath);
@@ -2524,20 +2477,6 @@ test('getKanjiStats returns rows ordered by frequency descending', () => {
   }
 });
 
-test('getKanjiStats returns empty array when no kanji exist', () => {
-  const dbPath = makeDbPath();
-  const db = openTestDb(dbPath);
-
-  try {
-    ensureSchema(db);
-    const rows = getKanjiStats(db, 10);
-    assert.deepEqual(rows, []);
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('getSessionEvents returns events ordered by ts_ms ascending', () => {
   const dbPath = makeDbPath();
   const db = openTestDb(dbPath);
@@ -2643,29 +2582,6 @@ test('getSessionEvents round-trips wall-clock timestamps written through event i
   }
 });
 
-test('getSessionEvents returns empty array for session with no events', () => {
-  const dbPath = makeDbPath();
-  const db = openTestDb(dbPath);
-
-  try {
-    ensureSchema(db);
-
-    const videoId = getOrCreateVideoRecord(db, 'local:/tmp/events-empty.mkv', {
-      canonicalTitle: 'Events Empty',
-      sourcePath: '/tmp/events-empty.mkv',
-      sourceUrl: null,
-      sourceType: SOURCE_TYPE_LOCAL,
-    });
-    const { sessionId } = startSessionRecord(db, videoId, 6_000_000);
-
-    const events = getSessionEvents(db, sessionId, 50);
-    assert.deepEqual(events, []);
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('getSessionEvents filters events to the requested session id', () => {
   const dbPath = makeDbPath();
   const db = openTestDb(dbPath);
@@ -4567,13 +4483,13 @@ test('deleteSession rebuilds word and kanji aggregates from retained subtitle li
 
     assert.ok(sharedWordRow);
     assert.equal(sharedWordRow.frequency, 1);
-    assert.equal(sharedWordRow.first_seen, Math.floor(keptTs / 1000));
-    assert.equal(sharedWordRow.last_seen, Math.floor(keptTs / 1000));
+    assert.equal(sharedWordRow.first_seen, keptTs / 1000);
+    assert.equal(sharedWordRow.last_seen, keptTs / 1000);
     assert.equal(deletedOnlyWordRow ?? null, null);
     assert.ok(sharedKanjiRow);
     assert.equal(sharedKanjiRow.frequency, 1);
-    assert.equal(sharedKanjiRow.first_seen, Math.floor(keptTs / 1000));
-    assert.equal(sharedKanjiRow.last_seen, Math.floor(keptTs / 1000));
+    assert.equal(sharedKanjiRow.first_seen, keptTs / 1000);
+    assert.equal(sharedKanjiRow.last_seen, keptTs / 1000);
     assert.equal(deletedOnlyKanjiRow ?? null, null);
   } finally {
     db.close();

src/core/services/immersion-tracker/lexical-rollups.test.ts

@@ -16,7 +16,8 @@ import {
 } from './query-lexical';
 import { Database } from './sqlite';
 import type { DatabaseSync } from './sqlite';
-import { ensureSchema } from './storage';
+import { createTrackerPreparedStatements, ensureSchema, executeQueuedWrite } from './storage';
+import { BASE_MS, createDb, seedEndedSession, seedVideo } from './__tests__/lifetime-test-fixtures';
 
 function makeDbPath(): string {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-lexical-rollups-'));
@@ -125,6 +126,121 @@ test('lexical rollup rebuild excludes rows hidden by vocabulary persistence rule
   }
 });
 
+test('re-seeing a filtered legacy word keeps charts consistent with the summary', () => {
+  const db = createDb();
+
+  try {
+    const videoId = seedVideo(db, null, 'episode');
+    const sessionId = seedEndedSession(db, videoId, BASE_MS, { activeMs: 1_000 });
+    const firstSeen = BASE_MS / 1000;
+    // Legacy row whose stored merged-token POS fails the persistence filter.
+    db.prepare(
+      `INSERT INTO imm_words(
+         headword, word, reading, part_of_speech, pos1, pos2, pos3, first_seen, last_seen, frequency
+       ) VALUES ('二死', 'にし', 'にし', 'other', '助詞|動詞', '格助詞|自立', '一般|*', ?, ?, 1)`,
+    ).run(firstSeen, firstSeen);
+    rebuildLexicalDailyRollups(db);
+
+    // The incoming token passes the filter, but the upsert keeps the stored POS.
+    executeQueuedWrite(
+      {
+        kind: 'subtitleLine',
+        sessionId,
+        videoId,
+        lineIndex: 1,
+        segmentStartMs: null,
+        segmentEndMs: null,
+        text: 'にし',
+        wordOccurrences: [
+          {
+            headword: '二死',
+            word: 'にし',
+            reading: 'にし',
+            partOfSpeech: 'verb',
+            pos1: '動詞',
+            pos2: '自立',
+            pos3: '*',
+            frequencyRank: null,
+            occurrenceCount: 1,
+          },
+        ],
+        kanjiOccurrences: [],
+        firstSeen: firstSeen + 60,
+        lastSeen: firstSeen + 60,
+      },
+      createTrackerPreparedStatements(db),
+    );
+
+    const plotted = getVocabularyChartData(db).newWordsTimeline.reduce(
+      (sum, day) => sum + day.wordCount,
+      0,
+    );
+    assert.equal(getVocabularySummary(db, null).uniqueWords, 0);
+    assert.equal(plotted, 0);
+  } finally {
+    db.close();
+  }
+});
+
+test('lexical rollup rebuild repairs last_seen left pointing at deleted history', () => {
+  const db = createDb();
+
+  try {
+    const videoId = seedVideo(db, null, 'episode');
+    const sessionId = seedEndedSession(db, videoId, BASE_MS, { activeMs: 1_000 });
+    const lineId = Number(
+      db
+        .prepare(
+          `INSERT INTO imm_subtitle_lines(session_id, video_id, line_index, text, CREATED_DATE, LAST_UPDATE_DATE)
+           VALUES (?, ?, 1, '猫', ?, ?)`,
+        )
+        .run(sessionId, videoId, BASE_MS, BASE_MS).lastInsertRowid,
+    );
+    const seen = (BASE_MS + 251) / 1000;
+    // first_seen this early may be real history pruned by retention; never touched.
+    const earlyFirst = seen - 86_400.5;
+    const staleLast = seen + 86_400.631;
+    db.prepare(
+      `INSERT INTO imm_words(id, headword, word, reading, first_seen, last_seen, frequency)
+       VALUES (1, '猫', '猫', 'ねこ', ?, ?, 1), (2, '犬', '犬', 'いぬ', ?, ?, 1)`,
+    ).run(earlyFirst, staleLast, seen - 0.1, seen - 0.1);
+    db.prepare(
+      `INSERT INTO imm_kanji(id, kanji, first_seen, last_seen, frequency) VALUES (1, '猫', ?, ?, 1)`,
+    ).run(earlyFirst, staleLast);
+    db.prepare(
+      `INSERT INTO imm_word_line_occurrences(line_id, word_id, occurrence_count, seen_ms)
+       VALUES (?, 1, 1, ?), (?, 2, 1, ?)`,
+    ).run(lineId, BASE_MS + 251, lineId, BASE_MS + 251);
+    db.prepare(
+      `INSERT INTO imm_kanji_line_occurrences(line_id, kanji_id, occurrence_count, seen_ms)
+       VALUES (?, 1, 1, ?)`,
+    ).run(lineId, BASE_MS + 251);
+
+    rebuildLexicalDailyRollups(db);
+
+    const bounds = (table: string): Array<[number, number]> =>
+      (
+        db
+          .prepare(`SELECT first_seen AS first, last_seen AS last FROM ${table} ORDER BY id`)
+          .all() as Array<{
+          first: number;
+          last: number;
+        }>
+      ).map((row) => [row.first, row.last]);
+    assert.deepEqual(
+      bounds('imm_words'),
+      [
+        [earlyFirst, seen],
+        [seen - 0.1, seen - 0.1],
+      ],
+      'healthy rows are untouched',
+    );
+    assert.deepEqual(bounds('imm_kanji'), [[earlyFirst, seen]]);
+  } finally {
+    db.close();
+  }
+});
+
 test('lexical rollup rebuild tolerates nullable legacy vocabulary text', () => {
   const dbPath = makeDbPath();
   const db = new Database(dbPath);
@@ -268,7 +384,7 @@ test('current lexical rollup readiness accepts legacy integer state storage', ()
         state_value INTEGER NOT NULL
       );
       INSERT INTO imm_rollup_state(state_key, state_value)
-      VALUES ('lexical_daily_rollups_version', 2);
+      VALUES ('lexical_daily_rollups_version', 3);
     `);
 
     assert.equal(areLexicalDailyRollupsReady(db), true);

src/core/services/immersion-tracker/lexical-rollups.ts

@@ -18,7 +18,9 @@ const LOCAL_EPOCH_DAY_SQL = `
   ) - 2440587.5 AS INTEGER)
 `;
 
-const LEXICAL_DAILY_ROLLUP_VERSION = '2';
+// v3 re-derives visibility for rows a re-seen word forced visible and repairs
+// last_seen values left behind by session deletes.
+const LEXICAL_DAILY_ROLLUP_VERSION = '3';
 const LEXICAL_DAILY_ROLLUP_VERSION_KEY = 'lexical_daily_rollups_version';
 const VOCABULARY_VISIBILITY_SCAN_BATCH_SIZE = 5_000;
 
@@ -26,6 +28,32 @@ export function localEpochDaySql(value: string): string {
   return LOCAL_EPOCH_DAY_SQL.replaceAll('%VALUE%', value);
 }
 
+// Session deletes once rounded removed timestamps to whole seconds, missing
+// fractional last_seen extremes that pointed at deleted history. New seen_ms
+// values match observation time; legacy values were stamped later at flush.
+// Retention prunes the oldest sessions first, so healthy rows never exceed
+// their newest surviving occurrence. Rows with undated occurrences are skipped.
+//
+// first_seen is deliberately not repaired: a stale bound is indistinguishable
+// from real history whose occurrences retention pruned, and frequency does not
+// reliably tell them apart.
+function repairStaleLastSeen(db: DatabaseSync): void {
+  for (const [table, occurrenceTable, col] of [
+    ['imm_words', 'imm_word_line_occurrences', 'word_id'],
+    ['imm_kanji', 'imm_kanji_line_occurrences', 'kanji_id'],
+  ] as const) {
+    const newestSeen = `(SELECT MAX(o.seen_ms) FROM ${occurrenceTable} o WHERE o.${col} = ${table}.id) / 1000.0`;
+    db.exec(`
+      UPDATE ${table}
+      SET last_seen = ${newestSeen}
+      WHERE last_seen > ${newestSeen}
+        AND NOT EXISTS (
+          SELECT 1 FROM ${occurrenceTable} o WHERE o.${col} = ${table}.id AND o.seen_ms IS NULL
+        )
+    `);
+  }
+}
+
 function createWordRollupTriggers(db: DatabaseSync): void {
   const dayForNew = localEpochDaySql('NEW.first_seen');
   const dayForOld = localEpochDaySql('OLD.first_seen');
@@ -186,6 +214,7 @@ export function rebuildLexicalDailyRollups(db: DatabaseSync): void {
       lastId = vocabularyRows[vocabularyRows.length - 1]!.id;
       if (vocabularyRows.length < VOCABULARY_VISIBILITY_SCAN_BATCH_SIZE) break;
     }
+    repairStaleLastSeen(db);
     db.exec('DELETE FROM imm_lexical_daily_rollups');
     db.exec(`
       INSERT INTO imm_lexical_daily_rollups(epoch_day, word_count, word_count_without_names, kanji_count)

src/core/services/immersion-tracker/maintenance.test.ts

@@ -4,12 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { Database } from './sqlite';
-import {
-  pruneRawRetention,
-  pruneRollupRetention,
-  runOptimizeMaintenance,
-  toMonthKey,
-} from './maintenance';
+import { pruneRawRetention, pruneRollupRetention, toMonthKey } from './maintenance';
 import { ensureSchema } from './storage';
 import { toDbTimestamp } from './query-shared';
 
@@ -225,42 +220,3 @@ test('raw retention keeps rollups and rollup retention prunes them separately',
     cleanupDbPath(dbPath);
   }
 });
-
-test('ensureSchema adds sample_ms index for telemetry rollup scans', () => {
-  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
-
-  try {
-    ensureSchema(db);
-    const indexes = db.prepare("PRAGMA index_list('imm_session_telemetry')").all() as Array<{
-      name: string;
-    }>;
-    const hasSampleMsIndex = indexes.some((row) => row.name === 'idx_telemetry_sample_ms');
-    assert.equal(hasSampleMsIndex, true);
-
-    const indexColumns = db.prepare("PRAGMA index_info('idx_telemetry_sample_ms')").all() as Array<{
-      name: string;
-    }>;
-    assert.deepEqual(
-      indexColumns.map((column) => column.name),
-      ['sample_ms'],
-    );
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
-test('runOptimizeMaintenance executes PRAGMA optimize', () => {
-  const executedSql: string[] = [];
-  const db = {
-    exec(source: string) {
-      executedSql.push(source);
-      return this;
-    },
-  } as unknown as Parameters<typeof runOptimizeMaintenance>[0];
-
-  runOptimizeMaintenance(db);
-
-  assert.deepEqual(executedSql, ['PRAGMA optimize']);
-});

src/core/services/immersion-tracker/query-shared.ts

@@ -298,9 +298,11 @@ export function planLexicalRemovalsForVideos(
   return planLexicalRemovals(db, `sl.video_id IN (${makePlaceholders(videoIds)})`, videoIds);
 }
 
+// first_seen/last_seen are REAL seconds that keep millisecond fractions; never round
+// them, or comparisons against stored extremes miss and refreshes drift.
 function toStoredSeenSeconds(ms: number | null): number | null {
   if (ms === null || !Number.isFinite(ms)) return null;
-  return Math.floor(ms / 1000);
+  return ms / 1000;
 }
 
 /**
@@ -320,6 +322,13 @@ export function applyLexicalRemovals(db: DatabaseSync, plan: LexicalRemovalPlan)
   applyRemovalsForEntity(db, 'kanji', plan.kanji);
 }
 
+// A timestamp repair must keep subtraction-exact lifetime counts and any
+// first_seen date that the deleted occurrences cannot account for.
+type LexicalAggregateOverride = {
+  frequency: number | null;
+  firstSeen: number | null;
+};
+
 function applyRemovalsForEntity(
   db: DatabaseSync,
   entity: LexicalEntity,
@@ -358,7 +367,7 @@ function applyRemovalsForEntity(
     `UPDATE ${entityTable} SET frequency = ?, first_seen = ?, last_seen = ? WHERE id = ?`,
   );
 
-  const needsExactRefresh: number[] = [];
+  const needsExactRefresh = new Map<number, LexicalAggregateOverride>();
 
   for (const removal of removals) {
     const current = selectStmt.get(removal.id) as {
@@ -369,17 +378,9 @@ function applyRemovalsForEntity(
     if (!current) continue;
 
     const nextFrequency = (current.frequency ?? 0) - removal.removedFrequency;
-    if (nextFrequency <= 0) {
-      // The rows in scope are already gone by now, so anything still pointing at
-      // this entity means the stored frequency was stale rather than exhausted.
-      if (hasOccurrencesStmt.get(removal.id)) {
-        needsExactRefresh.push(removal.id);
-      } else {
-        deleteStmt.run(removal.id);
-      }
-      continue;
-    }
-
+    // Legacy occurrences use flush time, which can follow the actual observation.
+    // An earlier stored date may also belong to retention-pruned history. Only
+    // move it when the removed timestamps prove that its observation was deleted.
     const removedFirstSeen = toStoredSeenSeconds(removal.removedFirstSeenMs);
     const removedLastSeen = toStoredSeenSeconds(removal.removedLastSeenMs);
     const firstSeenMayHaveMoved =
@@ -388,11 +389,26 @@ function applyRemovalsForEntity(
     const lastSeenMayHaveMoved =
       current.lastSeen === null ||
       (removedLastSeen !== null && removedLastSeen >= current.lastSeen);
+    const exactRefreshOverride = {
+      frequency: nextFrequency > 0 ? nextFrequency : null,
+      firstSeen: firstSeenMayHaveMoved ? null : current.firstSeen,
+    };
+    if (nextFrequency <= 0) {
+      // The rows in scope are already gone by now, so anything still pointing at
+      // this entity means the stored frequency was stale rather than exhausted.
+      if (hasOccurrencesStmt.get(removal.id)) {
+        needsExactRefresh.set(removal.id, exactRefreshOverride);
+      } else {
+        deleteStmt.run(removal.id);
+      }
+      continue;
+    }
+
     if (firstSeenMayHaveMoved || lastSeenMayHaveMoved) {
       // Undated pre-migration occurrences are invisible to the seeks below;
-      // fall back to the full re-aggregate that resolves their dates.
+      // resolve their dates without discarding retention-pruned aggregates.
       if (hasUndatedOccurrenceStmt.get(removal.id)) {
-        needsExactRefresh.push(removal.id);
+        needsExactRefresh.set(removal.id, exactRefreshOverride);
         continue;
       }
       const minSeenMs = (minSeenStmt.get(removal.id) as { value: number | null }).value;
@@ -400,13 +416,13 @@ function applyRemovalsForEntity(
       if (minSeenMs === null || maxSeenMs === null) {
         // Frequency says occurrences remain but none exist: stale row, let the
         // exact refresh reconcile (it deletes rows with nothing left).
-        needsExactRefresh.push(removal.id);
+        needsExactRefresh.set(removal.id, exactRefreshOverride);
         continue;
       }
       updateAggregatesStmt.run(
         nextFrequency,
-        Math.floor(Number(minSeenMs) / 1000),
-        Math.floor(Number(maxSeenMs) / 1000),
+        firstSeenMayHaveMoved ? toStoredSeenSeconds(Number(minSeenMs)) : current.firstSeen,
+        toStoredSeenSeconds(Number(maxSeenMs)),
         removal.id,
       );
       continue;
@@ -416,13 +432,17 @@ function applyRemovalsForEntity(
   }
 
   if (entity === 'word') {
-    refreshWordAggregates(db, needsExactRefresh);
+    refreshWordAggregates(db, [...needsExactRefresh.keys()], needsExactRefresh);
   } else {
-    refreshKanjiAggregates(db, needsExactRefresh);
+    refreshKanjiAggregates(db, [...needsExactRefresh.keys()], needsExactRefresh);
   }
 }
 
-function refreshWordAggregates(db: DatabaseSync, wordIds: number[]): void {
+function refreshWordAggregates(
+  db: DatabaseSync,
+  wordIds: number[],
+  overrides?: ReadonlyMap<number, LexicalAggregateOverride>,
+): void {
   if (wordIds.length === 0) {
     return;
   }
@@ -470,15 +490,19 @@ function refreshWordAggregates(db: DatabaseSync, wordIds: number[]): void {
       continue;
     }
     updateStmt.run(
-      row.frequency,
-      Math.floor(row.firstSeen / 1000),
-      Math.floor(row.lastSeen / 1000),
+      overrides?.get(row.wordId)?.frequency ?? row.frequency,
+      overrides?.get(row.wordId)?.firstSeen ?? toStoredSeenSeconds(row.firstSeen),
+      toStoredSeenSeconds(row.lastSeen),
       row.wordId,
     );
   }
 }
 
-function refreshKanjiAggregates(db: DatabaseSync, kanjiIds: number[]): void {
+function refreshKanjiAggregates(
+  db: DatabaseSync,
+  kanjiIds: number[],
+  overrides?: ReadonlyMap<number, LexicalAggregateOverride>,
+): void {
   if (kanjiIds.length === 0) {
     return;
   }
@@ -526,9 +550,9 @@ function refreshKanjiAggregates(db: DatabaseSync, kanjiIds: number[]): void {
       continue;
     }
     updateStmt.run(
-      row.frequency,
-      Math.floor(row.firstSeen / 1000),
-      Math.floor(row.lastSeen / 1000),
+      overrides?.get(row.kanjiId)?.frequency ?? row.frequency,
+      overrides?.get(row.kanjiId)?.firstSeen ?? toStoredSeenSeconds(row.firstSeen),
+      toStoredSeenSeconds(row.lastSeen),
       row.kanjiId,
     );
   }

src/core/services/immersion-tracker/storage-session.test.ts

@@ -59,34 +59,6 @@ function cleanupDbPath(dbPath: string): void {
   // libsql keeps Windows file handles alive after close when prepared statements were used.
 }
 
-test('applyPragmas sets the SQLite tuning defaults used by immersion tracking', () => {
-  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
-
-  try {
-    applyPragmas(db);
-
-    const journalModeRow = db.prepare('PRAGMA journal_mode').get() as {
-      journal_mode: string;
-    };
-    const synchronousRow = db.prepare('PRAGMA synchronous').get() as { synchronous: number };
-    const foreignKeysRow = db.prepare('PRAGMA foreign_keys').get() as { foreign_keys: number };
-    const busyTimeoutRow = db.prepare('PRAGMA busy_timeout').get() as { timeout: number };
-    const journalSizeLimitRow = db.prepare('PRAGMA journal_size_limit').get() as {
-      journal_size_limit: number;
-    };
-
-    assert.equal(journalModeRow.journal_mode, 'wal');
-    assert.equal(synchronousRow.synchronous, 1);
-    assert.equal(foreignKeysRow.foreign_keys, 1);
-    assert.equal(busyTimeoutRow.timeout, 2500);
-    assert.equal(journalSizeLimitRow.journal_size_limit, 67_108_864);
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('applyPragmas installs the busy timeout before WAL negotiation', () => {
   const statements: string[] = [];
   const db: DatabaseSync = {
@@ -110,76 +82,6 @@ test('applyPragmas installs the busy timeout before WAL negotiation', () => {
   ]);
 });
 
-test('ensureSchema creates immersion core tables', () => {
-  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
-
-  try {
-    ensureSchema(db);
-    const rows = db
-      .prepare(
-        `SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'imm_%' ORDER BY name`,
-      )
-      .all() as Array<{ name: string }>;
-    const tableNames = new Set(rows.map((row) => row.name));
-
-    assert.ok(tableNames.has('imm_videos'));
-    assert.ok(tableNames.has('imm_anime'));
-    assert.ok(tableNames.has('imm_sessions'));
-    assert.ok(tableNames.has('imm_session_telemetry'));
-    assert.ok(tableNames.has('imm_session_events'));
-    assert.ok(tableNames.has('imm_daily_rollups'));
-    assert.ok(tableNames.has('imm_monthly_rollups'));
-    assert.ok(tableNames.has('imm_words'));
-    assert.ok(tableNames.has('imm_kanji'));
-    assert.ok(tableNames.has('imm_subtitle_lines'));
-    assert.ok(tableNames.has('imm_word_line_occurrences'));
-    assert.ok(tableNames.has('imm_kanji_line_occurrences'));
-    assert.ok(tableNames.has('imm_rollup_state'));
-    assert.ok(tableNames.has('imm_cover_art_blobs'));
-    assert.ok(tableNames.has('imm_youtube_videos'));
-    assert.ok(tableNames.has('imm_stats_excluded_words'));
-
-    const videoColumns = new Set(
-      (
-        db.prepare('PRAGMA table_info(imm_videos)').all() as Array<{
-          name: string;
-        }>
-      ).map((row) => row.name),
-    );
-
-    assert.ok(videoColumns.has('anime_id'));
-    assert.ok(videoColumns.has('parsed_basename'));
-    assert.ok(videoColumns.has('parsed_title'));
-    assert.ok(videoColumns.has('parsed_season'));
-    assert.ok(videoColumns.has('parsed_episode'));
-    assert.ok(videoColumns.has('parser_source'));
-    assert.ok(videoColumns.has('parser_confidence'));
-    assert.ok(videoColumns.has('parse_metadata_json'));
-    assert.ok(videoColumns.has('anime_assignment_locked'));
-
-    const mediaArtColumns = new Set(
-      (
-        db.prepare('PRAGMA table_info(imm_media_art)').all() as Array<{
-          name: string;
-        }>
-      ).map((row) => row.name),
-    );
-    assert.ok(mediaArtColumns.has('cover_blob_hash'));
-
-    const rollupStateRow = db
-      .prepare('SELECT state_value FROM imm_rollup_state WHERE state_key = ?')
-      .get('last_rollup_sample_ms') as {
-      state_value: string;
-    } | null;
-    assert.ok(rollupStateRow);
-    assert.equal(Number(rollupStateRow?.state_value ?? 0), 0);
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('ensureSchema adds manual assignment locks when upgrading the previous schema', () => {
   const dbPath = makeDbPath();
   const db = new Database(dbPath);
@@ -752,37 +654,6 @@ test('ensureSchema migrates session event timestamps to text and repairs libsql-
   }
 });
 
-test('ensureSchema creates large-history performance indexes', () => {
-  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
-
-  try {
-    ensureSchema(db);
-    const indexNames = new Set(
-      (
-        db
-          .prepare(`SELECT name FROM sqlite_master WHERE type = 'index' AND name LIKE 'idx_%'`)
-          .all() as Array<{
-          name: string;
-        }>
-      ).map((row) => row.name),
-    );
-
-    assert.ok(indexNames.has('idx_telemetry_sample_ms'));
-    assert.ok(indexNames.has('idx_sessions_started_at'));
-    assert.ok(indexNames.has('idx_sessions_ended_at'));
-    assert.ok(indexNames.has('idx_words_frequency'));
-    assert.ok(indexNames.has('idx_kanji_frequency'));
-    assert.ok(indexNames.has('idx_media_art_anilist_id'));
-    assert.ok(indexNames.has('idx_media_art_cover_url'));
-    assert.ok(indexNames.has('idx_youtube_videos_channel_id'));
-    assert.ok(indexNames.has('idx_youtube_videos_youtube_video_id'));
-  } finally {
-    db.close();
-    cleanupDbPath(dbPath);
-  }
-});
-
 test('ensureSchema adds the subtitle event index to current-version databases', () => {
   const dbPath = makeDbPath();
   const db = new Database(dbPath);

src/core/services/immersion-tracker/storage.ts

@@ -6,6 +6,7 @@ import { normalizeTitleIdentity } from '../../utils/title-normalization';
 import type { DatabaseSync } from './sqlite';
 import { nowMs } from './time';
 import { ensureLexicalDailyRollupTables, markLexicalDailyRollupsReady } from './lexical-rollups';
+import { isVocabularyStatsRowVisible, type VocabularyVisibilityRow } from './vocabulary-visibility';
 import { SCHEMA_VERSION } from './types';
 import type { QueuedWrite, VideoMetadata, YoutubeVideoMetadata } from './types';
 import { toDbMs, toDbTimestamp } from './query-shared';
@@ -17,7 +18,8 @@ export interface TrackerPreparedStatements {
   wordUpsertStmt: ReturnType<DatabaseSync['prepare']>;
   kanjiUpsertStmt: ReturnType<DatabaseSync['prepare']>;
   subtitleLineInsertStmt: ReturnType<DatabaseSync['prepare']>;
-  wordIdSelectStmt: ReturnType<DatabaseSync['prepare']>;
+  wordSelectStmt: ReturnType<DatabaseSync['prepare']>;
+  wordVisibilityUpdateStmt: ReturnType<DatabaseSync['prepare']>;
   kanjiIdSelectStmt: ReturnType<DatabaseSync['prepare']>;
   wordLineOccurrenceUpsertStmt: ReturnType<DatabaseSync['prepare']>;
   kanjiLineOccurrenceUpsertStmt: ReturnType<DatabaseSync['prepare']>;
@@ -1759,7 +1761,6 @@ export function createTrackerPreparedStatements(db: DatabaseSync): TrackerPrepar
         pos1 = COALESCE(NULLIF(imm_words.pos1, ''), excluded.pos1),
         pos2 = COALESCE(NULLIF(imm_words.pos2, ''), excluded.pos2),
         pos3 = COALESCE(NULLIF(imm_words.pos3, ''), excluded.pos3),
-        vocabulary_visible = 1,
         first_seen = MIN(COALESCE(first_seen, excluded.first_seen), excluded.first_seen),
         last_seen = MAX(COALESCE(last_seen, excluded.last_seen), excluded.last_seen),
         frequency_rank = CASE
@@ -1787,10 +1788,16 @@ export function createTrackerPreparedStatements(db: DatabaseSync): TrackerPrepar
         ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
       )
     `),
-    wordIdSelectStmt: db.prepare(`
-      SELECT id FROM imm_words
+    wordSelectStmt: db.prepare(`
+      SELECT id, word, headword, reading, part_of_speech AS partOfSpeech,
+        pos1, pos2, pos3, frequency_rank AS frequencyRank,
+        vocabulary_visible AS vocabularyVisible
+      FROM imm_words
       WHERE headword = ? AND word = ? AND reading = ?
     `),
+    wordVisibilityUpdateStmt: db.prepare(`
+      UPDATE imm_words SET vocabulary_visible = ? WHERE id = ?
+    `),
     kanjiIdSelectStmt: db.prepare(`
       SELECT id FROM imm_kanji
       WHERE kanji = ?
@@ -1842,14 +1849,18 @@ function incrementWordAggregate(
       occurrence.frequencyRank ?? null,
     );
   }
-  const row = stmts.wordIdSelectStmt.get(
-    occurrence.headword,
-    occurrence.word,
-    occurrence.reading,
-  ) as { id: number } | null;
+  const row = stmts.wordSelectStmt.get(occurrence.headword, occurrence.word, occurrence.reading) as
+    | (VocabularyVisibilityRow & { id: number; vocabularyVisible: number })
+    | null;
   if (!row?.id) {
     throw new Error(`Failed to resolve imm_words id for ${occurrence.headword}`);
   }
+  // The upsert keeps the first-seen POS metadata, so derive visibility from the
+  // stored row (as the vocabulary summary does) rather than the incoming token.
+  const visible = isVocabularyStatsRowVisible(row) ? 1 : 0;
+  if (row.vocabularyVisible !== visible) {
+    stmts.wordVisibilityUpdateStmt.run(visible, row.id);
+  }
   return row.id;
 }
 
@@ -1952,18 +1963,16 @@ export function executeQueuedWrite(write: QueuedWrite, stmts: TrackerPreparedSta
       currentMs,
     );
     const lineId = Number(lineResult.lastInsertRowid);
+    // Match aggregate bounds to the observation, even if this write was queued
+    // for a while. Flush time cannot identify which occurrence set first_seen.
+    const seenMs = toDbTimestamp(Math.round(write.firstSeen * 1000));
     for (const occurrence of write.wordOccurrences) {
       const wordId = incrementWordAggregate(stmts, occurrence, write.firstSeen, write.lastSeen);
-      stmts.wordLineOccurrenceUpsertStmt.run(lineId, wordId, occurrence.occurrenceCount, currentMs);
+      stmts.wordLineOccurrenceUpsertStmt.run(lineId, wordId, occurrence.occurrenceCount, seenMs);
     }
     for (const occurrence of write.kanjiOccurrences) {
       const kanjiId = incrementKanjiAggregate(stmts, occurrence, write.firstSeen, write.lastSeen);
-      stmts.kanjiLineOccurrenceUpsertStmt.run(
-        lineId,
-        kanjiId,
-        occurrence.occurrenceCount,
-        currentMs,
-      );
+      stmts.kanjiLineOccurrenceUpsertStmt.run(lineId, kanjiId, occurrence.occurrenceCount, seenMs);
     }
     return;
   }

src/core/services/ipc-command.test.ts

@@ -129,47 +129,32 @@ test('handleMpvCommandFromIpc emits mpv OSD for subtitle step keybinding proxies
   assert.deepEqual(playbackFeedback, []);
 });
 
-test('handleMpvCommandFromIpc does not dispatch retired subtitle-delay shift tokens', () => {
+const specialCommandCases = [
+  { name: 'youtube picker open', command: '__youtube-picker-open', expected: 'youtube-picker' },
+  { name: 'jimaku open', command: '__jimaku-open', expected: 'jimaku' },
+  // Legacy Animetosho command is kept as a TsukiHime alias.
+  {
+    name: 'legacy Animetosho open as a TsukiHime alias',
+    command: '__animetosho-open',
+    expected: 'tsukihime',
+  },
+  {
+    name: 'playlist browser open',
+    command: '__playlist-browser-open',
+    expected: 'playlist-browser',
+  },
+];
+
+for (const c of specialCommandCases) {
+  test(`handleMpvCommandFromIpc dispatches special ${c.name} command`, async () => {
     const { options, calls, sentCommands, osd } = createOptions();
-  handleMpvCommandFromIpc(['__sub-delay-next-line'], options);
-  assert.deepEqual(calls, []);
-  assert.deepEqual(sentCommands, [['__sub-delay-next-line']]);
-  assert.deepEqual(osd, []);
-});
-
-test('handleMpvCommandFromIpc dispatches special youtube picker open command', () => {
-  const { options, calls, sentCommands, osd } = createOptions();
-  handleMpvCommandFromIpc(['__youtube-picker-open'], options);
-  assert.deepEqual(calls, ['youtube-picker']);
-  assert.deepEqual(sentCommands, []);
-  assert.deepEqual(osd, []);
-});
-
-test('handleMpvCommandFromIpc dispatches special jimaku open command', () => {
-  const { options, calls, sentCommands, osd } = createOptions();
-  handleMpvCommandFromIpc(['__jimaku-open'], options);
-  assert.deepEqual(calls, ['jimaku']);
-  assert.deepEqual(sentCommands, []);
-  assert.deepEqual(osd, []);
-});
-
-test('handleMpvCommandFromIpc keeps the legacy Animetosho command as a TsukiHime alias', () => {
-  const { options, calls, sentCommands } = createOptions();
-
-  handleMpvCommandFromIpc(['__animetosho-open'], options);
-
-  assert.deepEqual(calls, ['tsukihime']);
-  assert.deepEqual(sentCommands, []);
-});
-
-test('handleMpvCommandFromIpc dispatches special playlist browser open command', async () => {
-  const { options, calls, sentCommands, osd } = createOptions();
-  handleMpvCommandFromIpc(['__playlist-browser-open'], options);
+    handleMpvCommandFromIpc([c.command], options);
     await new Promise((resolve) => setImmediate(resolve));
-  assert.deepEqual(calls, ['playlist-browser']);
+    assert.deepEqual(calls, [c.expected]);
     assert.deepEqual(sentCommands, []);
     assert.deepEqual(osd, []);
   });
+}
 
 test('handleMpvCommandFromIpc surfaces playlist browser open rejections via mpv osd', async () => {
   const { options, osd } = createOptions({

src/core/services/ipc.test.ts

@@ -3,11 +3,7 @@ import assert from 'node:assert/strict';
 
 import { createIpcDepsRuntime, registerIpcHandlers, type IpcServiceDeps } from './ipc';
 import { IPC_CHANNELS } from '../../shared/ipc/contracts';
-import type {
-  PlaylistBrowserSnapshot,
-  SessionActionDispatchRequest,
-  SubtitleSidebarSnapshot,
-} from '../../types';
+import type { SessionActionDispatchRequest, SubtitleSidebarSnapshot } from '../../types';
 
 interface FakeIpcRegistrar {
   on: Map<string, (event: unknown, ...args: unknown[]) => void>;
@@ -187,107 +183,6 @@ function createFakeImmersionTracker(
   };
 }
 
-test('createIpcDepsRuntime wires AniList handlers', async () => {
-  const calls: string[] = [];
-  const deps = createIpcDepsRuntime({
-    getMainWindow: () => null,
-    getVisibleOverlayVisibility: () => false,
-    onOverlayModalClosed: () => {},
-    onOverlayMouseInteractionChanged: (active) => {
-      calls.push(`overlay-interaction:${active}`);
-    },
-    openYomitanSettings: () => {},
-    quitApp: () => {},
-    toggleVisibleOverlay: () => {},
-    tokenizeCurrentSubtitle: async () => null,
-    getCurrentSubtitleRaw: () => '',
-    getCurrentSubtitleAss: () => '',
-    getSubtitleSidebarSnapshot: async () => createSubtitleSidebarSnapshotFixture(),
-    getPlaybackPaused: () => true,
-    getSubtitlePosition: () => null,
-    getSubtitleStyle: () => null,
-    saveSubtitlePosition: () => {},
-    getMecabTokenizer: () => null,
-    handleMpvCommand: () => {},
-    getKeybindings: () => [],
-    getSessionBindings: () => [],
-    getConfiguredShortcuts: () => ({}),
-    dispatchSessionAction: async () => {},
-    getStatsToggleKey: () => 'Backquote',
-    getMarkWatchedKey: () => 'KeyW',
-    getOverlayNotificationPosition: () => 'top-right',
-    getControllerConfig: () => createControllerConfigFixture(),
-    saveControllerConfig: () => {},
-    saveControllerPreference: () => {},
-    getSecondarySubMode: () => 'hover',
-    getMpvClient: () => null,
-    focusMainWindow: () => {},
-    activatePlaybackWindowForOverlayInteraction: () => false,
-    runSubsyncManual: async () => ({ ok: true, message: 'ok' }),
-    getAnkiConnectStatus: () => false,
-    getRuntimeOptions: () => ({}),
-    setRuntimeOption: () => ({ ok: true }),
-    cycleRuntimeOption: () => ({ ok: true }),
-    reportOverlayContentBounds: () => {},
-    getAnilistStatus: () => ({ tokenStatus: 'resolved' }),
-    clearAnilistToken: () => {
-      calls.push('clearAnilistToken');
-    },
-    openAnilistSetup: () => {
-      calls.push('openAnilistSetup');
-    },
-    getAnilistQueueStatus: () => ({ pending: 1, ready: 0, deadLetter: 0 }),
-    retryAnilistQueueNow: async () => {
-      calls.push('retryAnilistQueueNow');
-      return { ok: true, message: 'done' };
-    },
-    appendClipboardVideoToQueue: () => ({ ok: true, message: 'queued' }),
-    getPlaylistBrowserSnapshot: async () => ({
-      directoryPath: '/tmp',
-      directoryAvailable: true,
-      directoryStatus: '/tmp',
-      directoryItems: [],
-      playlistItems: [],
-      playingIndex: 0,
-      currentFilePath: '/tmp/current.mkv',
-    }),
-    appendPlaylistBrowserFile: async () => ({ ok: true, message: 'append' }),
-    playPlaylistBrowserIndex: async () => ({ ok: true, message: 'play' }),
-    removePlaylistBrowserIndex: async () => ({ ok: true, message: 'remove' }),
-    movePlaylistBrowserIndex: async () => ({ ok: true, message: 'move' }),
-    onYoutubePickerResolve: async () => ({ ok: true, message: 'ok' }),
-  });
-
-  assert.deepEqual(deps.getAnilistStatus(), { tokenStatus: 'resolved' });
-  deps.clearAnilistToken();
-  deps.openAnilistSetup();
-  deps.onOverlayMouseInteractionChanged?.(true, null);
-  assert.deepEqual(deps.getAnilistQueueStatus(), {
-    pending: 1,
-    ready: 0,
-    deadLetter: 0,
-  });
-  assert.deepEqual(await deps.retryAnilistQueueNow(), {
-    ok: true,
-    message: 'done',
-  });
-  assert.equal((await deps.getPlaylistBrowserSnapshot()).directoryAvailable, true);
-  assert.deepEqual(await deps.appendPlaylistBrowserFile('/tmp/new.mkv'), {
-    ok: true,
-    message: 'append',
-  });
-  assert.deepEqual(await deps.playPlaylistBrowserIndex(2), { ok: true, message: 'play' });
-  assert.deepEqual(await deps.removePlaylistBrowserIndex(2), { ok: true, message: 'remove' });
-  assert.deepEqual(await deps.movePlaylistBrowserIndex(2, -1), { ok: true, message: 'move' });
-  assert.deepEqual(calls, [
-    'clearAnilistToken',
-    'openAnilistSetup',
-    'overlay-interaction:true',
-    'retryAnilistQueueNow',
-  ]);
-  assert.equal(deps.getPlaybackPaused(), true);
-});
-
 test('createIpcDepsRuntime ignores overlay content reports from stale visible renderers', () => {
   const mainWindow = { id: 'main', isDestroyed: () => false } as never;
   const staleWindow = { id: 'stale', isDestroyed: () => false } as never;
@@ -332,27 +227,6 @@ test('registerIpcHandlers maps setIgnoreMouseEvents to overlay interaction activ
   assert.deepEqual(calls, ['overlay-interaction:false', 'overlay-interaction:true']);
 });
 
-test('registerIpcHandlers passes sender window to overlay content bounds reports', () => {
-  const { registrar, handlers } = createFakeIpcRegistrar();
-  const senderWindows: unknown[] = [];
-
-  registerIpcHandlers(
-    createRegisterIpcDeps({
-      reportOverlayContentBounds: ((_payload: unknown, senderWindow: unknown) => {
-        senderWindows.push(senderWindow);
-      }) as IpcServiceDeps['reportOverlayContentBounds'],
-    }),
-    registrar,
-  );
-
-  const handler = handlers.on.get(IPC_CHANNELS.command.reportOverlayContentBounds);
-  assert.equal(typeof handler, 'function');
-
-  handler?.({}, { layer: 'visible' });
-
-  assert.deepEqual(senderWindows, [null]);
-});
-
 test('registerIpcHandlers runs AniList update after manual mark watched succeeds', async () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const calls: string[] = [];
@@ -433,71 +307,6 @@ test('registerIpcHandlers skips AniList update when manual mark watched has no a
   assert.deepEqual(calls, ['mark']);
 });
 
-test('registerIpcHandlers exposes playlist browser snapshot and mutations', async () => {
-  const { registrar, handlers } = createFakeIpcRegistrar();
-  const calls: Array<[string, unknown[]]> = [];
-  registerIpcHandlers(
-    createRegisterIpcDeps({
-      getPlaylistBrowserSnapshot: async () => ({
-        directoryPath: '/tmp/videos',
-        directoryAvailable: true,
-        directoryStatus: '/tmp/videos',
-        directoryItems: [],
-        playlistItems: [],
-        playingIndex: 1,
-        currentFilePath: '/tmp/videos/ep2.mkv',
-      }),
-      appendPlaylistBrowserFile: async (filePath) => {
-        calls.push(['append', [filePath]]);
-        return { ok: true, message: 'append-ok' };
-      },
-      playPlaylistBrowserIndex: async (index) => {
-        calls.push(['play', [index]]);
-        return { ok: true, message: 'play-ok' };
-      },
-      removePlaylistBrowserIndex: async (index) => {
-        calls.push(['remove', [index]]);
-        return { ok: true, message: 'remove-ok' };
-      },
-      movePlaylistBrowserIndex: async (index, direction) => {
-        calls.push(['move', [index, direction]]);
-        return { ok: true, message: 'move-ok' };
-      },
-    }),
-    registrar,
-  );
-
-  const snapshot = (await handlers.handle.get(IPC_CHANNELS.request.getPlaylistBrowserSnapshot)?.(
-    {},
-  )) as PlaylistBrowserSnapshot | undefined;
-  const append = await handlers.handle.get(IPC_CHANNELS.request.appendPlaylistBrowserFile)?.(
-    {},
-    '/tmp/videos/ep3.mkv',
-  );
-  const play = await handlers.handle.get(IPC_CHANNELS.request.playPlaylistBrowserIndex)?.({}, 2);
-  const remove = await handlers.handle.get(IPC_CHANNELS.request.removePlaylistBrowserIndex)?.(
-    {},
-    2,
-  );
-  const move = await handlers.handle.get(IPC_CHANNELS.request.movePlaylistBrowserIndex)?.(
-    {},
-    2,
-    -1,
-  );
-
-  assert.equal(snapshot?.playingIndex, 1);
-  assert.deepEqual(append, { ok: true, message: 'append-ok' });
-  assert.deepEqual(play, { ok: true, message: 'play-ok' });
-  assert.deepEqual(remove, { ok: true, message: 'remove-ok' });
-  assert.deepEqual(move, { ok: true, message: 'move-ok' });
-  assert.deepEqual(calls, [
-    ['append', ['/tmp/videos/ep3.mkv']],
-    ['play', [2]],
-    ['remove', [2]],
-    ['move', [2, -1]],
-  ]);
-});
-
 test('registerIpcHandlers rejects malformed runtime-option payloads', async () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const calls: Array<{ id: string; value: unknown }> = [];
@@ -610,45 +419,6 @@ test('registerIpcHandlers rejects malformed runtime-option payloads', async () =
   );
 });
 
-test('registerIpcHandlers exposes subtitle sidebar snapshot request', async () => {
-  const { registrar, handlers } = createFakeIpcRegistrar();
-  const snapshot = createSubtitleSidebarSnapshotFixture();
-  snapshot.cues = [{ startTime: 1, endTime: 2, text: 'line-1' }];
-  snapshot.config.enabled = true;
-
-  registerIpcHandlers(
-    createRegisterIpcDeps({
-      getSubtitleSidebarSnapshot: async () => snapshot,
-    }),
-    registrar,
-  );
-
-  const handler = handlers.handle.get(IPC_CHANNELS.request.getSubtitleSidebarSnapshot);
-  assert.ok(handler);
-  assert.deepEqual(await handler!({}), snapshot);
-});
-
-test('registerIpcHandlers exposes playback window activation request', async () => {
-  const { registrar, handlers } = createFakeIpcRegistrar();
-  const calls: string[] = [];
-  registerIpcHandlers(
-    createRegisterIpcDeps({
-      activatePlaybackWindowForOverlayInteraction: async () => {
-        calls.push('activate');
-        return true;
-      },
-    }),
-    registrar,
-  );
-
-  const handler = handlers.handle.get(
-    IPC_CHANNELS.request.activatePlaybackWindowForOverlayInteraction,
-  );
-  assert.ok(handler);
-  assert.equal(await handler!({}), true);
-  assert.deepEqual(calls, ['activate']);
-});
-
 test('registerIpcHandlers accepts the keep-without-media timing decision', async () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const requests: unknown[] = [];
@@ -757,28 +527,6 @@ test('registerIpcHandlers validates and forwards timing review text and screensh
   assert.equal(requests.length, 1);
 });
 
-test('registerIpcHandlers forwards yomitan lookup tracking commands to immersion tracker', () => {
-  const { registrar, handlers } = createFakeIpcRegistrar();
-  const calls: string[] = [];
-  registerIpcHandlers(
-    createRegisterIpcDeps({
-      immersionTracker: createFakeImmersionTracker({
-        recordYomitanLookup: () => {
-          calls.push('lookup');
-        },
-      }),
-    }),
-    registrar,
-  );
-
-  const handler = handlers.on.get(IPC_CHANNELS.command.recordYomitanLookup);
-  assert.equal(typeof handler, 'function');
-
-  handler?.({}, null);
-
-  assert.deepEqual(calls, ['lookup']);
-});
-
 test('registerIpcHandlers forwards valid subtitle sidebar mining context', () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const contexts: unknown[] = [];
@@ -1369,3 +1117,39 @@ test('mpv discovery has its own request and does not change session bindings', a
   assert.deepEqual(await discovery({}), snapshot);
   assert.deepEqual(await session({}), []);
 });
+
+test('registerIpcHandlers validates playlist browser mutation payloads before forwarding', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const forwarded: unknown[][] = [];
+  const ok = { ok: true, message: 'ok' };
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      appendPlaylistBrowserFile: async (...args) => (forwarded.push(args), ok),
+      playPlaylistBrowserIndex: async (...args) => (forwarded.push(args), ok),
+      removePlaylistBrowserIndex: async (...args) => (forwarded.push(args), ok),
+      movePlaylistBrowserIndex: async (...args) => (forwarded.push(args), ok),
+    }),
+    registrar,
+  );
+  const { request } = IPC_CHANNELS;
+  const cases: Array<{ channel: string; args: unknown[]; valid: boolean }> = [
+    { channel: request.appendPlaylistBrowserFile, args: ['/media/ep01.mkv'], valid: true },
+    { channel: request.appendPlaylistBrowserFile, args: ['   '], valid: false },
+    { channel: request.appendPlaylistBrowserFile, args: [42], valid: false },
+    { channel: request.playPlaylistBrowserIndex, args: [0], valid: true },
+    { channel: request.playPlaylistBrowserIndex, args: [-1], valid: false },
+    { channel: request.removePlaylistBrowserIndex, args: [1.5], valid: false },
+    { channel: request.removePlaylistBrowserIndex, args: ['2'], valid: false },
+    { channel: request.movePlaylistBrowserIndex, args: [2, -1], valid: true },
+    { channel: request.movePlaylistBrowserIndex, args: [2, 2], valid: false },
+    { channel: request.movePlaylistBrowserIndex, args: [Number.NaN, 1], valid: false },
+  ];
+
+  for (const { channel, args, valid } of cases) {
+    forwarded.length = 0;
+    const result = (await handlers.handle.get(channel)?.({}, ...args)) as { ok: boolean };
+    const label = `${channel}(${args.map(String).join(', ')})`;
+    assert.equal(result.ok, valid, label);
+    assert.deepEqual(forwarded, valid ? [args] : [], label);
+  }
+});

src/core/services/jlpt-token-filter.test.ts

@@ -1,51 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-import {
-  getIgnoredPos1Entries,
-  JLPT_EXCLUDED_TERMS,
-  JLPT_IGNORED_MECAB_POS1,
-  JLPT_IGNORED_MECAB_POS1_ENTRIES,
-  JLPT_IGNORED_MECAB_POS1_LIST,
-  shouldIgnoreJlptByTerm,
-  shouldIgnoreJlptForMecabPos1,
-} from './jlpt-token-filter';
-
-test('shouldIgnoreJlptByTerm matches the excluded JLPT lexical terms', () => {
-  assert.equal(shouldIgnoreJlptByTerm('この'), true);
-  assert.equal(shouldIgnoreJlptByTerm('そこ'), true);
-  assert.equal(shouldIgnoreJlptByTerm('猫'), false);
-  assert.deepEqual(Array.from(JLPT_EXCLUDED_TERMS), [
-    'この',
-    'その',
-    'あの',
-    'どの',
-    'これ',
-    'それ',
-    'あれ',
-    'どれ',
-    'ここ',
-    'そこ',
-    'あそこ',
-    'どこ',
-    'こと',
-    'ああ',
-    'ええ',
-    'うう',
-    'おお',
-    'はは',
-    'へえ',
-    'ふう',
-    'ほう',
-  ]);
-});
-
-test('shouldIgnoreJlptForMecabPos1 matches the exported ignored POS1 list', () => {
-  assert.equal(shouldIgnoreJlptForMecabPos1('助詞'), true);
-  assert.equal(shouldIgnoreJlptForMecabPos1('名詞'), false);
-  assert.deepEqual(JLPT_IGNORED_MECAB_POS1, JLPT_IGNORED_MECAB_POS1_LIST);
-  assert.deepEqual(
-    JLPT_IGNORED_MECAB_POS1_ENTRIES.map((entry) => entry.pos1),
-    JLPT_IGNORED_MECAB_POS1_LIST,
-  );
-  assert.deepEqual(getIgnoredPos1Entries(), JLPT_IGNORED_MECAB_POS1_ENTRIES);
-});

src/core/services/mining.test.ts

@@ -276,7 +276,6 @@ test('handleMultiCopyDigit copies backward from the current subtitle after a bac
 test('handleMineSentenceDigit reports async create failures', async () => {
   const osd: string[] = [];
   const logs: Array<{ message: string; err: unknown }> = [];
-  let cardsMined = 0;
 
   handleMineSentenceDigit(2, {
     subtitleTimingTracker: {
@@ -296,9 +295,6 @@ test('handleMineSentenceDigit reports async create failures', async () => {
     getCurrentSecondarySubText: () => 'sub2',
     showMpvOsd: (text) => osd.push(text),
     logError: (message, err) => logs.push({ message, err }),
-    onCardsMined: (count) => {
-      cardsMined += count;
-    },
   });
 
   await new Promise((resolve) => setImmediate(resolve));
@@ -307,37 +303,6 @@ test('handleMineSentenceDigit reports async create failures', async () => {
   assert.equal(logs[0]?.message, 'mineSentenceMultiple failed:');
   assert.equal((logs[0]?.err as Error).message, 'mine boom');
   assert.ok(osd.some((entry) => entry.includes('Mine sentence failed: mine boom')));
-  assert.equal(cardsMined, 0);
-});
-
-test('handleMineSentenceDigit increments successful card count', async () => {
-  const osd: string[] = [];
-  let cardsMined = 0;
-
-  handleMineSentenceDigit(2, {
-    subtitleTimingTracker: {
-      getRecentBlocks: () => ['one', 'two'],
-      getCurrentSubtitle: () => null,
-      findTiming: (text) =>
-        text === 'one' ? { startTime: 1, endTime: 3 } : { startTime: 4, endTime: 7 },
-    },
-    ankiIntegration: {
-      updateLastAddedFromClipboard: async () => {},
-      triggerFieldGroupingForLastAddedCard: async () => {},
-      markLastCardAsAudioCard: async () => {},
-      createSentenceCard: async () => true,
-    },
-    getCurrentSecondarySubText: () => 'sub2',
-    showMpvOsd: (text) => osd.push(text),
-    logError: () => {},
-    onCardsMined: (count) => {
-      cardsMined += count;
-    },
-  });
-
-  await new Promise((resolve) => setImmediate(resolve));
-
-  assert.equal(cardsMined, 1);
 });
 
 test('handleMineSentenceDigit keeps per-entry timings when subtitle text repeats', async () => {

src/core/services/mining.ts

@@ -201,7 +201,6 @@ export function handleMineSentenceDigit(
     getCurrentSecondarySubText: () => string | undefined;
     showMpvOsd: (text: string) => void;
     logError: (message: string, err: unknown) => void;
-    onCardsMined?: (count: number) => void;
   },
 ): void {
   if (!deps.subtitleTimingTracker || !deps.ankiIntegration) return;
@@ -233,14 +232,9 @@ export function handleMineSentenceDigit(
     entries,
     deps.getCurrentSecondarySubText,
   );
-  const cardsToMine = 1;
+  // Card creation records the mined card (with its note id) itself.
   deps.ankiIntegration
     .createSentenceCard(sentence, rangeStart, rangeEnd, secondarySubText)
-    .then((created) => {
-      if (created) {
-        deps.onCardsMined?.(cardsToMine);
-      }
-    })
     .catch((err) => {
       deps.logError('mineSentenceMultiple failed:', err);
       deps.showMpvOsd(`Mine sentence failed: ${(err as Error).message}`);

src/core/services/mpv-control.test.ts

@@ -1,12 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import {
-  playNextSubtitleRuntime,
-  replayCurrentSubtitleRuntime,
-  sendMpvCommandRuntime,
-  setMpvSubVisibilityRuntime,
-  showMpvOsdRuntime,
-} from './mpv';
+import { showMpvOsdRuntime } from './mpv';
 
 test('showMpvOsdRuntime sends show-text when connected', () => {
   const commands: (string | number)[][] = [];
@@ -55,29 +49,3 @@ test('showMpvOsdRuntime logs fallback when disconnected', () => {
   assert.equal(shown, false);
   assert.deepEqual(logs, ['OSD (MPV not connected): hello']);
 });
-
-test('mpv runtime command wrappers call expected client methods', () => {
-  const calls: string[] = [];
-  const client = {
-    connected: true,
-    send: ({ command }: { command: (string | number)[] }) => {
-      calls.push(`send:${command.join(',')}`);
-    },
-    replayCurrentSubtitle: () => {
-      calls.push('replay');
-    },
-    playNextSubtitle: () => {
-      calls.push('next');
-    },
-    setSubVisibility: (visible: boolean) => {
-      calls.push(`subVisible:${visible}`);
-    },
-  };
-
-  replayCurrentSubtitleRuntime(client);
-  playNextSubtitleRuntime(client);
-  sendMpvCommandRuntime(client, ['script-message', 'x']);
-  setMpvSubVisibilityRuntime(client, false);
-
-  assert.deepEqual(calls, ['replay', 'next', 'send:script-message,x', 'subVisible:false']);
-});