chore(release): prepare v0.19.5

- Update changelog generation guidance and tests
- Reformat current release notes and document the new style

.agents/plugins/marketplace.json

@@ -1,20 +0,0 @@
-{
-  "name": "subminer-local",
-  "interface": {
-    "displayName": "SubMiner Local"
-  },
-  "plugins": [
-    {
-      "name": "subminer-workflow",
-      "source": {
-        "source": "local",
-        "path": "./plugins/subminer-workflow"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}

.agents/skills/subminer-change-verification/SKILL.md

@@ -1,22 +1,45 @@
 ---
-name: 'subminer-change-verification'
-description: 'Compatibility shim. Canonical SubMiner change verification workflow now lives in the repo-local subminer-workflow plugin.'
+name: subminer-change-verification
+description: Verify SubMiner changes with repo-native cheap-first test lanes. Use after code, config, launcher, plugin, runtime, stats, documentation, or workflow changes; do not use for read-only questions.
 ---
 
-# Compatibility Shim
+# SubMiner Change Verification
 
-Canonical source:
+Verify the behavior claimed by a change without running unrelated expensive checks by default.
 
-- `plugins/subminer-workflow/skills/subminer-change-verification/SKILL.md`
+## Workflow
 
-Canonical helper scripts:
+1. Inspect the requested scope and changed paths with `git status --short` and `git diff`.
+2. Read `docs/workflow/verification.md` as the source of truth for maintained lanes.
+3. Run the cheapest lane or lanes that cover the changed behavior.
+4. Escalate to the full handoff gate only for substantial or cross-boundary changes.
+5. Report exact commands, results, skipped checks, blockers, and remaining risk.
 
-- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh`
-- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh`
+Do not use hidden wrapper commands. Verification commands are owned by `package.json` and the workflow documentation.
 
-When this shim is invoked:
+## Lane Selection
 
-1. Read the canonical plugin-owned skill.
-2. Follow the plugin-owned skill as the source of truth.
-3. Use the wrapper scripts in this shim directory only for compatibility with existing commands and docs.
-4. Do not duplicate workflow changes here; update the plugin-owned skill and scripts instead.
+- Internal docs, `AGENTS.md`, or `.agents/skills/**`: `bun run test:docs:kb`
+- User-facing `docs-site/**`: `bun run docs:test`, then `bun run docs:build`
+- Config/schema/defaults: `bun run test:config`
+  - If defaults or templates changed, also run `bun run generate:config-example` and `bun run verify:config-example`.
+- General TypeScript source: `bun run typecheck`, then `bun run test:fast`
+- Launcher or mpv plugin: `bun run test:launcher` or `bun run test:env`, based on the behavior changed
+- Runtime compatibility or dist-sensitive wiring: `bun run test:runtime:compat`
+- Stats dashboard: `bun run test:stats`
+- Build/release scripts: `bun run test:scripts`
+
+For substantial changes, use the full gate documented in `AGENTS.md` and `docs/workflow/verification.md`.
+
+## Runtime Escalation
+
+Real runtime checks are required when the claim depends on actual Electron, mpv, overlay, focus, window tracking, launch, or socket behavior. Run the relevant application flow when the environment supports it. Otherwise, report the missing runtime dependency and do not present cheaper checks as authoritative runtime validation.
+
+## Pre-Handoff Checks
+
+Before handoff, reconcile both questions:
+
+1. Do behavior, defaults, flags, shortcuts, ports, APIs, architecture, or workflow changes require documentation updates?
+2. Does the change require a current-outcome fragment under `changes/` according to `changes/README.md`?
+
+Complete required updates before handoff or report the blocker.

.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh

@@ -1,13 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-REPO_ROOT=$(cd "$SCRIPT_DIR/../../../.." && pwd)
-TARGET="$REPO_ROOT/plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh"
-
-if [[ ! -x "$TARGET" ]]; then
-  echo "Missing canonical script: $TARGET" >&2
-  exit 1
-fi
-
-exec "$TARGET" "$@"

.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh

@@ -1,13 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-REPO_ROOT=$(cd "$SCRIPT_DIR/../../../.." && pwd)
-TARGET="$REPO_ROOT/plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh"
-
-if [[ ! -x "$TARGET" ]]; then
-  echo "Missing canonical script: $TARGET" >&2
-  exit 1
-fi
-
-exec "$TARGET" "$@"

.agents/skills/subminer-release/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: subminer-release
+description: Prepare, cut, publish, or repair SubMiner stable and prerelease releases. Use for hands-on release work; do not use for general release questions.
+---
+
+# SubMiner release
+
+Carry out the requested release phase using the repository's current release process.
+
+## Source of truth
+
+Read `docs/RELEASING.md` completely before changing files or release state. Treat it as canonical. Read `changes/README.md` when the work touches change fragments or generated release notes.
+
+Do not copy release commands or policy into this skill. If this skill disagrees with the release guide, follow the guide and reconcile the skill before handoff.
+
+## Workflow
+
+1. Identify whether the request is for a stable release, prerelease, release preparation, publication, or repair.
+2. Inspect the current branch, worktree status, package version, pending change fragments, relevant tags, and latest CI state before making changes.
+3. Follow the matching procedure in `docs/RELEASING.md` in order. Review generated changelog and release-note Markdown before it can be committed or published.
+4. Run every required gate for the requested release phase. Do not treat a cheaper test lane as a substitute for the documented release gate.
+5. Before a stable tag, confirm the package and tag versions match and no pending `changes/*.md` fragments remain. Preserve fragments for prereleases as documented.
+6. Report the resulting version, completed checks, local commit and tag state, remote publication state, skipped platform checks, and any remaining manual work.
+
+## Authorization boundaries
+
+- A request to prepare a release stops before commit, tag, push, or remote publication unless the user also authorizes those actions.
+- A clear request to cut or publish a release includes the documented commit, tag, and push steps. Ask before the first remote mutation when the wording is ambiguous.
+- Do not edit an existing GitHub release, publish to the AUR, change secrets, or alter signing configuration unless the user explicitly requests that operation.
+- Do not switch branches without consent.
+
+## Stop conditions
+
+Stop and report the blocker when required CI or a release gate fails, authentication is missing, versions disagree, required artifacts are absent, or the worktree contains unexpected changes that overlap the release. Do not tag or publish a partially verified release.

.agents/skills/subminer-scrum-master/SKILL.md

@@ -1,18 +0,0 @@
----
-name: 'subminer-scrum-master'
-description: 'Compatibility shim. Canonical SubMiner scrum-master workflow now lives in the repo-local subminer-workflow plugin.'
----
-
-# Compatibility Shim
-
-Canonical source:
-
-- `plugins/subminer-workflow/skills/subminer-scrum-master/SKILL.md`
-
-When this shim is invoked:
-
-1. Read the canonical plugin-owned skill.
-2. Follow the plugin-owned skill as the source of truth.
-3. Do not duplicate workflow changes here; update the plugin-owned skill instead.
-
-This shim exists so existing repo references and prompts keep resolving during the migration to the repo-local plugin workflow.

.github/workflows/docs-pages.yml

@@ -32,9 +32,11 @@ jobs:
       - name: Guard stable docs tag shape
         id: tag_guard
         if: github.ref_type == 'tag'
+        env:
+          TAG_NAME: ${{ github.ref_name }}
         run: |
-          if [[ ! "${{ github.ref_name }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::notice::Skipping non-stable docs tag ${{ github.ref_name }}"
+          if [[ ! "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::notice::Skipping non-stable docs tag $TAG_NAME"
             echo "stable_tag=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi

.github/workflows/prerelease.yml

@@ -274,7 +274,8 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 
       - name: Generate checksums
         run: |
@@ -296,15 +297,22 @@ jobs:
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
       - name: Verify committed prerelease notes
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           if [ ! -s release/prerelease-notes.md ]; then
             echo "::error::release/prerelease-notes.md is missing or empty. Run 'bun run changelog:prerelease-notes --version <version>' locally and commit the file before tagging."
             exit 1
           fi
+          if ! bun run changelog:check-prerelease-notes --version "$RELEASE_VERSION"; then
+            echo "::error::release/prerelease-notes.md was not generated for $RELEASE_VERSION. Rerun 'bun run changelog:prerelease-notes --version $RELEASE_VERSION' locally, commit, and retag."
+            exit 1
+          fi
 
       - name: Publish Prerelease
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
 
@@ -326,27 +334,27 @@ jobs:
             exit 1
           fi
 
-          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
-            gh release edit "${{ steps.version.outputs.VERSION }}" \
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
+            gh release edit "$RELEASE_VERSION" \
               --draft \
               --prerelease \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/prerelease-notes.md
           else
-            gh release create "${{ steps.version.outputs.VERSION }}" \
+            gh release create "$RELEASE_VERSION" \
               --draft \
               --latest=false \
               --prerelease \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/prerelease-notes.md
           fi
 
           for asset in "${artifacts[@]}"; do
-            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
           done
 
-          gh release edit "${{ steps.version.outputs.VERSION }}" \
+          gh release edit "$RELEASE_VERSION" \
             --draft=false \
             --prerelease \
-            --title "${{ steps.version.outputs.VERSION }}" \
+            --title "$RELEASE_VERSION" \
             --notes-file release/prerelease-notes.md

.github/workflows/release.yml

@@ -273,7 +273,8 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 
       - name: Generate checksums
         run: |
@@ -295,33 +296,40 @@ jobs:
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
       - name: Guard against pending changelog fragments
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
-            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version ${{ steps.version.outputs.VERSION }}' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
+            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version $RELEASE_VERSION' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
             exit 1
           fi
 
       - name: Verify changelog is ready for tagged release
-        run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:check --version "$RELEASE_VERSION"
 
       - name: Generate release notes from changelog
-        run: bun run changelog:release-notes --version "${{ steps.version.outputs.VERSION }}"
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:release-notes --version "$RELEASE_VERSION"
 
       - name: Publish Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
 
-          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
             # Do not pass the prerelease flag here; gh defaults to a normal release.
-            gh release edit "${{ steps.version.outputs.VERSION }}" \
+            gh release edit "$RELEASE_VERSION" \
               --draft=false \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/release-notes.md
           else
-            gh release create "${{ steps.version.outputs.VERSION }}" \
-              --title "${{ steps.version.outputs.VERSION }}" \
+            gh release create "$RELEASE_VERSION" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/release-notes.md
           fi
 
@@ -344,7 +352,7 @@ jobs:
           fi
 
           for asset in "${artifacts[@]}"; do
-            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
           done
 
   aur-publish:
@@ -420,9 +428,10 @@ jobs:
         if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
-          version="${{ steps.version.outputs.VERSION }}"
+          version="$RELEASE_VERSION"
           install -dm755 .tmp/aur-release-assets
           gh release download "$version" \
             --dir .tmp/aur-release-assets \
@@ -432,15 +441,17 @@ jobs:
 
       - name: Update AUR packaging metadata
         if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
-          version_no_v="${{ steps.version.outputs.VERSION }}"
+          version_no_v="$RELEASE_VERSION"
           version_no_v="${version_no_v#v}"
           cp packaging/aur/subminer-bin/PKGBUILD aur-subminer-bin/PKGBUILD
           cp packaging/aur/subminer-bin/.SRCINFO aur-subminer-bin/.SRCINFO
           bash scripts/update-aur-package.sh \
             --pkg-dir aur-subminer-bin \
-            --version "${{ steps.version.outputs.VERSION }}" \
+            --version "$RELEASE_VERSION" \
             --appimage ".tmp/aur-release-assets/SubMiner-${version_no_v}.AppImage" \
             --wrapper ".tmp/aur-release-assets/subminer" \
             --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
@@ -450,6 +461,7 @@ jobs:
         working-directory: aur-subminer-bin
         env:
           GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
           if git diff --quiet -- PKGBUILD .SRCINFO; then
@@ -459,7 +471,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add PKGBUILD .SRCINFO
-          git commit -m "Update to ${{ steps.version.outputs.VERSION }}"
+          git commit -m "Update to $RELEASE_VERSION"
 
           attempts=3
           for attempt in $(seq 1 "$attempts"); do

.gitignore

@@ -49,6 +49,7 @@ tests/*
 !.agents/skills/
 .agents/skills/*
 !.agents/skills/subminer-change-verification/
+!.agents/skills/subminer-release/
 !.agents/skills/subminer-scrum-master/
 .agents/skills/subminer-change-verification/*
 !.agents/skills/subminer-change-verification/SKILL.md
@@ -56,6 +57,8 @@ tests/*
 .agents/skills/subminer-change-verification/scripts/*
 !.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
 !.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
+.agents/skills/subminer-release/*
+!.agents/skills/subminer-release/SKILL.md
 .agents/skills/subminer-scrum-master/*
 !.agents/skills/subminer-scrum-master/SKILL.md
 favicon.png

AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.MD
+# AGENTS.md
 
 ## Internal Docs
 
@@ -13,7 +13,7 @@ Start here, then leave this file.
 
 `docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
 
-`CLAUDE.md` is a symlink to this file — there is one project instruction file, not two.
+`CLAUDE.md` is a symlink to this file; there is one project instruction file, not two.
 
 ## Quick Start
 
@@ -25,8 +25,9 @@ Start here, then leave this file.
 
 ## Build / Test
 
-- Runtime/package manager: Bun (`packageManager: bun@1.3.5`)
-- Default handoff gate:
+- Runtime/package manager: Bun; use the version pinned by `package.json`.
+- Follow [`docs/workflow/verification.md`](./docs/workflow/verification.md) and start with the cheapest sufficient lane.
+- Full handoff gate for substantial changes:
   `bun run typecheck`
   `bun run test:fast`
   `bun run test:env`
@@ -44,13 +45,15 @@ Start here, then leave this file.
 - Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
 - Stats dashboard UI (`stats/`): `bun run test:stats`
 - Build/release scripts (`scripts/**`): `bun run test:scripts`
-- Docs-only: `bun run docs:test`, then `bun run docs:build`
+- 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`
 - Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`
 
 ## Docs Upkeep
 
 - Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
-- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it — and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
+- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it, and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
 - Trigger map (touch left → update right):
   - `src/config/definitions/**` (schema/defaults/template) → `bun run generate:config-example`, then reconcile `docs-site/configuration.md` + any feature doc that cites that default
   - shortcuts/keybindings (`shortcuts.*`, `keybindings`, `stats.*Key`, `subtitleSidebar.toggleKey`, controller bindings) → `docs-site/shortcuts.md`
@@ -71,16 +74,10 @@ Start here, then leave this file.
 
 ## Release / PR Notes
 
-- User-visible PRs need reconciled current-outcome fragment(s) in `changes/*.md` — format and rules in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out)
+- User-visible PRs need reconciled current-outcome fragment(s) in `changes/*.md`. Format and rules live in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out).
 - User-visible docs changes get a `type: docs` fragment
 - CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
 - PR review helpers:
-  - `gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'`
+  - `gh pr view --json number,title --jq '"PR #\\(.number): \\(.title)"'`
   - `gh api repos/:owner/:repo/pulls/<num>/comments --paginate`
-
-## Runtime Notes
-
-- Use Codex background for long jobs; tmux only when persistence/interaction is required
-- CI red: `gh run list/view`, rerun, fix, repeat until green
-- TypeScript: keep files small; follow existing patterns
-- Only Swift is the `scripts/get-mpv-window-macos.swift` helper (macOS mpv window detection); validate via `bun test scripts/get-mpv-window-macos.test.ts`
+- For CI debugging, inspect runs with `gh run list/view`; rerun or fix only within the requested scope.

CHANGELOG.md

@@ -1,24 +1,115 @@
 # Changelog
 
-## Unreleased
-
-### Added
-
-- Anime Browser Language Filter: The Extensions tab's available list now has a language chip row above it. Pick one or more languages to narrow a repository index that otherwise lists every language it knows, or "All" to clear the filter — selecting a language replaces "All" rather than sitting beside it. Extension rows name the language ("Japanese" instead of `ja`), and the Available heading shows how many of the offered extensions the filter leaves.
-
-### Changed
-
-- Anime Browser Subtitles: A stream's subtitle tracks are now downloaded to a temp directory and loaded into mpv as files instead of streamed from the source URL, so they can serve as the alass reference in Subsync (the same way Jellyfin subtitles do) — a streamed track had no file on disk and was rejected by the source picker. The format is detected from the file's own content, a track that fails to download falls back to its URL so the episode still plays, and the directory is removed when the next episode starts or the app exits.
+## v0.19.5 (2026-08-30)
 
 ### Fixed
 
-- Anime Browser Window Switching: Opening the anime browser now shows a tray icon on every platform and — on macOS — puts the app in the Cmd+Tab switcher (which requires the Dock icon; the two are inseparable on macOS), so you can switch between it and mpv. Previously the subtitle overlay's fullscreen support hid the whole app from the Dock and Cmd+Tab, leaving no way to reach the window. The Dock icon is released again when the window closes during playback.
-- Anime Browser Playback Session: Launching a video from the anime browser now starts a regular SubMiner session (tray icon plus the on-demand overlay runtime), and in `subminer anime` standalone mode, closing the browser window during playback no longer quits the app and kills the stream — the window can be reopened from the tray while mpv keeps playing.
+- **Anki Card Update Progress**: The card-update spinner now stays visible until audio and image updates finish, instead of disappearing early.
+- **Anki Word-Card Fields**: Word-card enrichment now writes sentence text and audio to the fields configured in AnkiConnect, while the dedicated sentence-card and audio-card actions keep their existing compatible field names.
+- **Overlapping Subtitles**:
+  - Subtitle lines that start while another line is still on screen now appear alongside it, instead of staying hidden until a track switch or seek.
+  - Subtitles shown at the same time now stack by their authored screen position, with top signs and song lines above bottom dialogue.
+  - Half-size ASS furigana is no longer shown as if it were a dialogue line.
+- **YouTube Auto Captions**:
+  - Auto-generated captions now follow their intended timing and two-row roll-up layout.
+  - Long speech is paged instead of covering the video with a wall of text.
+  - Explicitly timed sound cues like `[音楽]` no longer cover later dialogue.
+
+## v0.19.4 (2026-08-25)
+
+### Added
+- **Library Merge & Move**: Duplicate library cards for the same show can now be combined. Select cards in the library grid and use "Merge Selected" to pick which entry to keep and move every episode onto it, preserving sessions, mined cards, and watch time. Episodes can also be reassigned individually via the "→" button, useful when a file lands under a stray title; manual assignments survive later filename parsing, Jellyfin refreshes, and season repair. Exact AniList title matches with compatible seasons now merge automatically, while fuzzy matches surface as dismissible "Possible duplicate" reviews instead of merging silently.
+- **Duplicate Line Cleanup Tool**: The Vocabulary tab's new "Duplicates" button scans a chosen time window (7 days through all time) for old karaoke/typeset duplicate-line bursts, shows what it found, and collapses each run to one line once confirmed; `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>` options. Watch time and lines-seen totals are left unchanged.
+
+### Changed
+- **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
+
+### Fixed
+- **Subtitle & Karaoke Duplication**:
+  - Karaoke and animated signs are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved, instead of flooding the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, and repeated animation events.
+  - Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly.
+  - Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container.
+  - Secondary subtitles go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines.
+  - Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**:
+  - Generation, merged rebuilds, and imports no longer freeze the app on large dictionaries; snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path.
+  - Dictionaries are reused instead of regenerated when MeCab finds no name splits.
+  - Cached portraits restore correctly after the portrait index finishes loading post-tokenization.
+  - Desktop progress notifications on Linux AppImage installs update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**:
+  - The macOS window-tracking helper targets macOS 12.0+ instead of requiring the build machine's exact macOS version, fixing crashes on older systems like Ventura that left the overlay stuck on "Overlay loading".
+  - mpv IPC connection attempts time out and retry, showing an actionable error if content still isn't ready after 30 seconds.
+  - Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly.
+  - On macOS, reused modals and the stats window open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
+- **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
+- **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.
+- **Stats Performance & Reliability**: Immersion stats storage now sets its SQLite busy timeout before WAL setup, avoiding transient lock errors under concurrent writes. Deletes in the stats dashboard no longer freeze the UI, run proportional to what's deleted instead of rebuilding full lifetime summaries, retry safely if the delete worker crashes, and no longer rescan the whole library when deleting very common words; a new index also makes large session deletes drop from minutes to milliseconds. Library merges, video moves, and AniList reassignments got the same lifetime-summary fix.
+- **Vocabulary Stats Accuracy**: Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, new-word history uses corrected daily rollups (fixing legacy timestamp and time-zone issues), summary cards refresh automatically after edits to the exclusion list, and rapid exclusion edits no longer race each other.
+- **Rofi MKV Thumbnails**: Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Docs Site Indexing: Excluded the `/main/` and `/v/<version>/` docs trees from search indexing (self-referential canonical, `noindex,follow`, matching `X-Robots-Tag`) so crawlers focus on current docs instead of ~30 archived copies of every page, and restored `<lastmod>` dates in the docs sitemap that were silently dropped by production builds.
+
+</details>
+
+## v0.19.3 (2026-08-13)
+
+### Added
+- Changelog Modal: Adds an in-app changelog you can open from the tray ("View Changelog") or the "What's New" button on the update notification, so the notification stays reachable while you read. It shows the newest published release notes (falling back to the bundled changelog if that fetch fails), folds older versions while keeping the current one expanded, and supports keyboard navigation (`J`/`K`/arrows, `Enter`, `R`, `Esc`).
+
+### Changed
+- Subtitle Tokenization Performance: Reworks subtitle dictionary lookups to cut per-line work roughly in half, cache repeated lookups across lines, and stop tokenization from competing with on-screen subtitle prefetching. Also fixes several accuracy issues along the way: dropped readings on trailing kana, character names being skipped after a dictionary sync, annotations not refreshing after mining a card, and halfwidth katakana character names losing their reading or being swallowed by other words.
+
+### Fixed
+- Character Dictionary Large Imports: Large character dictionaries (e.g. One Piece) no longer fail to install from a fixed timeout budget; the import now scales its time budget to dictionary size and reports detailed progress (page/character counts, image download progress, elapsed time) instead of one static message.
+- Stats Delete Responsiveness: Deleting sessions, episodes, or library entries no longer freezes the stats page or an active video player; deletes are now batched into a single transaction.
+- Styled Subtitle Cue Parsing: Heavily typeset subtitles (karaoke, signs) no longer flood the subtitle sidebar with garbage; vector drawing commands are no longer shown as text, and duplicate/animation-burst cues now collapse into one.
+- X11 mpv Renderer: Fixes an mpv crash on the first fullscreen toggle for X11/XWayland users with `gpu-next` shaders (e.g. ArtCNN), which was caused by X11 mode forcing the legacy OpenGL renderer.
+- X11 Overlay Display Scaling: Fixes the overlay appearing oversized and offset from mpv on X11/XWayland under fractional or mixed-monitor display scaling.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Subtitle text is now decoded from ASS exactly once at ingest, so the renderer, timing tracker, and tokenizer all share one decoded value instead of each re-deriving it.
+- Added per-stage debug timings (`scanMs`, `mecabMs`, `frequencyMs`, `annotateMs`) to the subtitle tokenization pipeline log.
+
+</details>
+
+## v0.19.2 (2026-08-04)
+
+### Changed
+- Subsync: The sync modal now lets you choose both the reference subtitle (correct timing) and the out-of-sync subtitle to retime, for both alass and ffsubsync. alass can also use the loaded video's audio as a reference for local files. Retiming the secondary track now reloads the result into the secondary slot instead of overwriting the primary subtitle.
+
+### Fixed
+- Streaming Subtitle Tokenization: Jellyfin streams now seed subtitle tokenization directly from the downloaded subtitle file instead of relying on an mpv event that could be missed, and prefetching now runs to the end of the file and clears between episodes. The tokenization cache was raised from 256 to 2500 lines, and parsed cues are no longer lost when the active subtitle track briefly can't be resolved (e.g. switching to an embedded track). Together these prevent episodes from falling back to slow, line-by-line tokenization during playback.
+- Overlay: Subtitle lines now appear immediately at their cue time even on a tokenization cache miss, upgrading in place once tokens and annotations are ready, instead of waiting on a line still being processed. A failed tokenization is no longer cached as plain text, so repeated lines get another chance at annotations.
+- Background Logging: Background startup now respects the configured logging level when no explicit log level is passed.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Patched three high-severity dependency advisories (`undici`, `brace-expansion`, `fast-uri`).
+
+</details>
+
+## v0.19.1 (2026-08-01)
+
+### Added
+- Word Card Type: Adds a setting (Settings > Mining/Anki > Kiku/Lapis Features > "Word Card Type") to choose which card-type flag SubMiner marks on Kiku/Lapis word cards — `word-and-sentence` (default), `click`, `sentence`, `audio`, or `none`. Click cards (`IsClickCard`) can now be flagged, and setting any card-type flag clears the others so a note can't claim two types at once.
+
+### Fixed
+- Yomitan Popup: Fixes the macOS Yomitan popup going inert after mining a card — clicks outside the popup no longer pass through to mpv, and scrolling over the popup scrolls its definitions instead of seeking playback.
+- YouTube Playlist Links: Fixes opening a video from a playlist URL (e.g. a Watch Later link with `list=`/`index=`) timing out while probing subtitles, metadata, or the playback URL.
 
 ## v0.19.0 (2026-07-29)
 
 ### Added
-
 - Anki Maturity Highlighting: Known-word subtitle highlights can now be colored by Anki card maturity (new, learning, young, mature), similar to asbplayer. Tier thresholds and colors are configurable, with a runtime toggle and an updated help legend.
 - Post-Playback Menu: After a watch-history episode ends, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit. The pre-playback series menu now offers the previous episode too.
 - Delete Library Entries: The stats Library detail view can now delete an entire title in one step (episodes, sessions, subtitle lines, rollups, cover art, and vocabulary counts). Delete progress is now shown app-wide via a progress bar and status toast instead of disappearing when you switch tabs.
@@ -26,11 +117,9 @@
 - TsukiHime Subtitle Downloads: Added subtitle downloads for the current video via TsukiHime, loading Japanese as the primary track and your configured secondary language directly into mpv.
 
 ### Changed
-
 - Clipboard-Video Shortcut: The "append clipboard video to queue" shortcut is now configurable.
 
 ### Fixed
-
 - AniList Season Resolution: Season 2+ files now resolve to the correct AniList entry instead of silently falling back to season 1 (which mismatched character dictionaries and watch progress). Manual overrides now stay scoped per season, fix both the dictionary and progress tracking together, and also correct per-season cover art.
 - Subtitle Annotation Accuracy: Fixed several annotation edge cases, including inconsistent POS exclusions on merged quote-particle tokens, dropped annotations on supplementary-plane kanji, katakana punctuation wrongly treated as noise, and certain kanji vocabulary losing N+1 highlighting eligibility.
 - AnkiConnect Proxy Port Conflict: Video startup no longer crashes when another process already holds the configured AnkiConnect proxy port; a notification now explains how to resolve it.
@@ -46,7 +135,6 @@
 <summary>Internal changes</summary>
 
 ### Internal
-
 - Added a golden-file regression test corpus for the tokenizer/annotation pipeline, plus scripts to record new fixtures and diff against stock Yomitan.
 - Consolidated renderer modal state handling into a descriptor registry.
 - Consolidated CI quality checks (PR, stable, and prerelease) into one reusable workflow with mpv plugin tests and dependency audits.
@@ -58,12 +146,10 @@
 ## v0.18.0 (2026-07-10)
 
 ### Added
-
 - Sentence Audio Normalization: Generated sentence audio is now normalized to -23 LUFS by default, and clips mined from playback mirror mpv's software volume curve with a limiter to prevent clipping. Both behaviors are configurable independently.
 - Watch History Command: Added `subminer -H` / `--history` to browse watch history, replay or continue episodes, or pick one via fzf or rofi, with cover art shown in the rofi picker.
 
 ### Changed
-
 - Fzf Preview Layout: Moved fzf previews below launcher menus, giving long titles and metadata more room.
 - Known-Word Highlighting: Now compares subtitle and Anki-card readings, preventing false matches between homographs and unrelated words that share a reading, while still supporting matching across kana and kanji spellings.
 - Annotation Filtering: Standalone suffix tokens (e.g. さん, れる) are now excluded from JLPT/frequency/N+1 highlighting by default, matching how particles and interjections are treated; configurable via the pos2 exclusion setting.
@@ -71,7 +157,6 @@
 - Stats Trend Charts: Overhauled with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and value-sorted tooltips.
 
 ### Fixed
-
 - Background Stats Server: `subminer app` background launches now auto-start the stats server when enabled, and skip startup if one is already running.
 - Character Name Highlighting: Character dictionaries now split unspaced native names more reliably, and portraits, highlights, and hover lookup survive punctuation, unmatched text, and competing dictionary matches without incorrectly splitting longer words.
 - Highlighting Coverage: Frequency/JLPT highlighting and vocabulary stats now include content adverbs (e.g. 確かに, やはり) and kanji nouns MeCab tags as non-independent (e.g. 日, 点, 以外), while still suppressing interjections, pronouns, and grammar fragments; lexicalized kana expressions like かといって keep their annotations.
@@ -85,7 +170,6 @@
 <summary>Internal changes</summary>
 
 ### Internal
-
 - Test lanes moved to `scripts/test-lanes.ts` with per-directory discovery and isolated per-file timeouts; CI now covers previously orphaned stats, scripts, plugin process-retry, and runtime-compat suites, plus a new stats lane in the change-verification workflow.
 
 </details>
@@ -93,18 +177,15 @@
 ## v0.17.2 (2026-06-28)
 
 ### Fixed
-
 - YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
 - YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
 
 ## v0.17.1 (2026-06-27)
 
 ### Added
-
 - YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
 
 ### Fixed
-
 - Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
 - YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
 
@@ -185,7 +266,6 @@
 <summary>Internal changes</summary>
 
 ### Internal
-
 - **Build**: `make deps` now initializes git submodules before installing dependencies on a fresh source checkout.
 - **Release Tooling**: Release notes now credit contributors and first-time authors resolved from changelog fragments via git and the GitHub API.
 - **Changelog Guidance**: PR fragment guidance updated to preserve separate-outcome fragments while directing contributors to consolidate same-PR follow-up notes before adding churn.
@@ -195,11 +275,9 @@
 ## v0.15.2 (2026-06-02)
 
 ### Changed
-
 - Yomitan: Updated the bundled Yomitan build to the latest vendored revision.
 
 ### Fixed
-
 - Anki - Animated AVIF: Clip timing no longer starts or ends early; word-audio lead-in and clip duration are now aligned to frame boundaries.
 - Overlay (Hyprland): Fixed fullscreen overlay alignment - modal, stats, and sidebar content no longer shift below the mpv window.
 - Overlay (macOS): Subtitle bars are now interactive immediately after autoplay starts with "wait for overlay to be ready" enabled, without requiring a manual click.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -2,8 +2,10 @@
 
 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
+THUMBNAILER_SOURCE := assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 LAUNCHER_OUT := dist/launcher/$(APP_NAME)
 THEME_FILE := subminer.rasi
+THUMBNAILER_FILE := subminer-ffmpegthumbnailer.thumbnailer
 
 # Default install prefix for the wrapper script.
 PREFIX ?= $(HOME)/.local
@@ -221,11 +223,13 @@ docs-dev: ensure-bun
 
 
 install-linux: build-launcher
-	@printf '%s\n' "[INFO] Installing Linux wrapper/theme artifacts"
+	@printf '%s\n' "[INFO] Installing Linux wrapper/support artifacts"
 	@install -d "$(BINDIR)"
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(LINUX_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@install -d "$(LINUX_DATA_DIR)/thumbnailers"
+	@install -m 0644 "./$(THUMBNAILER_SOURCE)" "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@install -d "$(LINUX_DATA_DIR)/plugin/subminer"
 	@cp -R ./plugin/subminer/. "$(LINUX_DATA_DIR)/plugin/subminer/"
 	@if [ -n "$(APPIMAGE_SRC)" ]; then \
@@ -234,7 +238,7 @@ install-linux: build-launcher
 		printf '%s\n' "[WARN] No release/SubMiner-*.AppImage found; skipping AppImage install"; \
 		printf '%s\n' "       Build one with: make build"; \
 	fi
-	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 
 install-macos: build-launcher
 	@printf '%s\n' "[INFO] Installing macOS wrapper/theme/app artifacts"
@@ -275,8 +279,9 @@ uninstall:
 uninstall-linux:
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 	@rm -f "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@rm -f "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@rm -rf "$(LINUX_DATA_DIR)/plugin/subminer"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
 
 uninstall-macos:
 	@rm -f "$(BINDIR)/subminer"

README.md

@@ -15,7 +15,7 @@ Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersio
 [![License](https://img.shields.io/github/license/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://www.gnu.org/licenses/gpl-3.0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-1a1a2e?style=flat-square&logo=typescript&logoColor=3178c6)](https://www.typescriptlang.org)
 
-[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/89e61895-e2b7-4b47-8d50-a35afe4132b2)
+[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/7abab8a9-4e4e-4f06-9f3c-9783e15a3807)
 
 </div>
 

assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer

@@ -0,0 +1,4 @@
+[Thumbnailer Entry]
+TryExec=ffmpegthumbnailer
+Exec=ffmpegthumbnailer -i %i -o %o -s %s -f
+MimeType=video/matroska;video/matroska-3d;video/x-matroska;video/x-matroska-3d;

bun.lock

@@ -26,7 +26,7 @@
         "eslint": "^10.8.0",
         "prettier": "^3.8.1",
         "typescript": "^5.9.3",
-        "undici": "7.28.0",
+        "undici": "7.29.0",
       },
     },
   },
@@ -36,16 +36,18 @@
   "overrides": {
     "@xmldom/xmldom": "0.8.13",
     "app-builder-lib": "26.15.3",
-    "brace-expansion": "5.0.8",
+    "brace-expansion": "5.0.9",
     "electron-builder-squirrel-windows": "26.15.3",
+    "fast-uri": "3.1.5",
     "form-data": "4.0.6",
     "ip-address": "10.2.0",
-    "js-yaml": "4.3.0",
+    "js-yaml": "4.3.1",
     "lodash": "4.18.0",
     "minimatch": "10.2.5",
     "picomatch": "4.0.4",
     "tar": "7.5.21",
     "tmp": "0.2.7",
+    "undici": "7.29.0",
   },
   "packages": {
     "@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
@@ -266,7 +268,7 @@
 
     "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],
 
-    "brace-expansion": ["brace-expansion@5.0.8", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-JZyDyq3D4AUifKTPOB7DELf6XsB3WdPuNxCtob1vFXPsSXhdAiHBWJ/tJ8HAc9aH84BK+5JFZLNkJKx3G9kzQg=="],
+    "brace-expansion": ["brace-expansion@5.0.9", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg=="],
 
     "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],
 
@@ -404,7 +406,7 @@
 
     "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
 
-    "fast-uri": ["fast-uri@3.1.4", "", {}, "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw=="],
+    "fast-uri": ["fast-uri@3.1.5", "", {}, "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw=="],
 
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
@@ -496,7 +498,7 @@
 
     "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
 
-    "js-yaml": ["js-yaml@4.3.0", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q=="],
+    "js-yaml": ["js-yaml@4.3.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ=="],
 
     "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
 
@@ -714,7 +716,7 @@
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
-    "undici": ["undici@7.28.0", "", {}, "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA=="],
+    "undici": ["undici@7.29.0", "", {}, "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
@@ -754,8 +756,6 @@
 
     "@discordjs/rest/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],
 
-    "@discordjs/rest/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
-
     "@discordjs/util/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],
 
     "@electron/asar/commander": ["commander@5.1.0", "", {}, "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg=="],
@@ -808,8 +808,6 @@
 
     "node-gyp/env-paths": ["env-paths@2.2.1", "", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],
 
-    "node-gyp/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
-
     "node-gyp/which": ["which@6.0.1", "", { "dependencies": { "isexe": "^4.0.0" }, "bin": { "node-which": "bin/which.js" } }, "sha512-oGLe46MIrCRqX7ytPUf66EAYvdeMIZYn3WaocqqKZAxrBpkqHfL/qvTyJ/bTk5+AqHCjXmrv3CEWgy368zhRUg=="],
 
     "pkijs/@noble/hashes": ["@noble/hashes@1.4.0", "", {}, "sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg=="],

changes/README.md

@@ -42,13 +42,14 @@ 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.
-- GitHub release notes and prerelease notes use short top-level items with nested bullets for the change, user benefit, and any useful action note. The stable `CHANGELOG.md` can stay in compact single-line bullets.
+- `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.
 - `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.
 
 Prerelease notes:
 
 - prerelease tags like `v0.11.3-beta.1` and `v0.11.3-rc.1` reuse the current pending fragments to generate `release/prerelease-notes.md`
+- from the second prerelease of a base version onward, the notes also open with a `## Changes since <previous tag>` section generated from the fragment diff against the previous beta/RC tag; keep fragment edits meaningful. Editorial-only rewording is filtered out of that section, while genuinely changed behavior and deleted fragments (reverted changes) are reported
 - existing prerelease notes are a reviewed baseline; later prerelease runs should replace stale beta/RC wording with the current outcome instead of appending fix churn
 - prerelease note generation does not consume fragments and does not update `CHANGELOG.md` or `docs-site/changelog.md`
 - the final stable release is the point where `bun run changelog:build` consumes fragments into the stable changelog and release notes

changes/anime-browser.md

@@ -1,22 +0,0 @@
-type: added
-area: anime
-
-- Added an anime browser window that searches Aniyomi extension sources, shows cover art and episode lists, and plays an episode in mpv so the overlay and mining tools attach as usual.
-- Added `subminer anime` and the `--anime` flag to open the browser, plus a "Browse Anime" tray entry.
-- Anime extensions are read from `<userData>/anime-extensions`; drop Aniyomi `.apk` files there to add sources.
-- Added a source settings tab so extensions that need configuration (server address, credentials, quality) can be set up from the browser; values persist per source.
-- Added an Extensions tab for adding repository URLs and installing, updating, or removing extensions in place; extensions that fail to load are listed with the reason.
-- Browse, Extensions, and Source settings are tabs, so each one gets the full window instead of sharing it with the search results.
-- Repository URLs only need to be an https URL to a `.json` index; the file name is not restricted to `index.min.json`.
-- The source picker offers "All sources", which searches every installed source at once. Results stream in as each source answers — a fast source is on screen while a slow one is still resolving, with per-source progress in the status bar. Results are tagged with the source they came from, and a source that fails is named in the status bar instead of blanking the grid.
-- The Extensions tab opens with an Installed section listing every extension on disk with Remove — including ones added by hand or whose repository has since been removed — and Update where a configured repository still carries it.
-- Added `anime.repos`, `anime.extensionsDir`, and `anime.preferredQuality` config keys. SubMiner ships no extension repositories and performs no discovery.
-- Anime playback targets Japanese audio: dub-labelled entries are skipped when the source offers an alternative, `alang` prefers Japanese, and the source's own audio and subtitle tracks are loaded into mpv (Japanese selected) instead of being discarded, so all of them can be switched from mpv's track menu.
-- The primary subtitle slot stays reserved for Japanese: a source that only has, say, English subtitles gets them added with a normalized language tag (`English` → `en`) but not selected, so the regular `secondarySub` auto-load can route them to the secondary slot instead.
-- HLS streams pass through a local strip proxy that removes fake image headers some hosts glue onto their video segments, so streams ffmpeg would otherwise probe as "a PNG" and abandon now play in mpv.
-- The strip proxy retries a failed segment fetch once after a short pause and logs upstream error statuses; a host that errors on the very first fetches right after an episode resolves no longer kills the whole playback.
-- The strip proxy no longer forwards `Range` headers to the bridge: ffmpeg opens every HLS segment with `Range: bytes=0-`, the bridge answers some of those with 206, and a partial response bypassed the disguise strip, so whether an episode played depended on the bridge's cache state.
-- A bridge that dies out from under the app (killed, crashed, or stopped mid-operation) no longer leaves the browser failing every request until an app restart: the exit is detected, surfaced in the status bar, and the bridge restarts on the next request.
-- "Playing" is only reported once mpv actually configures a video output; when a stream fails to decode, the browser shows mpv's error instead of claiming playback started while no window ever appeared.
-- The Linux x64 bridge bundle is verified and pinned, so the anime browser starts on Linux instead of refusing with "No pinned checksum for linux-x64-bundle.zip".
-- The bridge bundle is fetched from the pinned release tag rather than whatever release is newest, so an upstream publish no longer breaks every install with a checksum mismatch.

changes/linux-overlay-content-ready-fallback.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed the overlay never loading (stuck on the "Overlay loading" OSD spinner) when the Yomitan content-script reload raced overlay window creation at startup, most visible when playing from the anime browser on Linux/Wayland: a hidden window stops painting after that reload, so the ready-to-show signal that gates showing the overlay never fired. Content-ready now falls back to did-finish-load after a short grace period.

changes/macos-yomitan-popup-passthrough.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed the macOS Yomitan popup going inert after mining a card: clicking outside the popup no longer passes through to mpv (with the overlay flickering hidden and shown), and scrolling over the popup scrolls its definitions again instead of seeking mpv.

changes/word-card-kind.md

@@ -1,6 +0,0 @@
-type: added
-area: anki
-
-- Added `ankiConnect.lapisKiku.wordCardKind` (Settings > Mining/Anki > Kiku/Lapis Features > "Word Card Type") to choose which card-type flag SubMiner marks on Kiku/Lapis word cards: `word-and-sentence` (default, unchanged behavior), `click`, `sentence`, `audio`, or `none` to leave the flags alone. Requested by Kiku users who only want `IsClickCard` set.
-- Word cards can now be flagged as Kiku click cards (`IsClickCard`), which SubMiner previously never set.
-- Setting a card-type flag now clears `IsClickCard` alongside the other card-type flags, so a note can no longer claim two card types at once.

config.example.jsonc

@@ -611,18 +611,6 @@
     } // Lapis kiku setting.
   }, // Automatic Anki updates and media generation options.
 
-  // ==========================================
-  // Anime Browser
-  // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
-  // add a repository index URL here (or drop .apk files in the extensions directory) to have any.
-  // Hot-reload: anime changes apply the next time the anime browser opens.
-  // ==========================================
-  "anime": {
-    "extensionsDir": "", // Directory holding Aniyomi extension .apk files. Empty uses <userData>/anime-extensions.
-    "repos": [], // Extension repository index URLs (any https .json index, e.g. https://.../index.min.json). Empty by default; SubMiner ships no repositories.
-    "preferredQuality": "" // Preferred stream quality label, matched as a substring (for example: 1080). Empty uses the source order.
-  }, // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
-
   // ==========================================
   // Jimaku
   // Jimaku API configuration and defaults.

docs-site/.vitepress/config.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { extname, join, posix, resolve, sep } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
@@ -26,6 +27,9 @@ function optionalEnv(value: string | undefined): string | undefined {
 const base = normalizeBase(optionalEnv(process.env.SUBMINER_DOCS_BASE) ?? '/');
 const outDir = optionalEnv(process.env.SUBMINER_DOCS_OUT_DIR);
 const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? process.cwd();
+// The tracked `docs-site/` checkout, which stays a git working tree even when
+// `docsSourceDir` points at an untracked release snapshot. Used for git lookups only.
+const repoDocsDir = optionalEnv(process.env.SUBMINER_DOCS_REPO_DIR) ?? process.cwd();
 const channel = normalizeChannel(optionalEnv(process.env.SUBMINER_DOCS_CHANNEL));
 const docsVersion = optionalEnv(process.env.SUBMINER_DOCS_VERSION);
 const latestStable = optionalEnv(process.env.SUBMINER_DOCS_LATEST_STABLE) ?? 'v0.18.0';
@@ -82,15 +86,18 @@ function pageToRoute(page: string): string | null {
   return route ? `/${route}` : '/';
 }
 
+// Only the root channel is indexable. `main` and every /v/<version>/ archive are
+// near-verbatim copies of it, so they own their URL via a self-referential canonical
+// and are excluded from the index instead of being consolidated onto root. Uniform
+// self-canonical plus noindex avoids mixing noindex with a cross-page canonical,
+// which Google treats as a conflicting signal.
+const isIndexableChannel = channel === 'stable-root';
+
 function pageToCanonicalHref(page: string): string | null {
   const route = pageToRoute(page);
   if (!route) return null;
 
-  if (channel === 'main') {
-    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
-  }
-
-  if (channel === 'stable-archive' && docsVersion !== latestStable) {
+  if (!isIndexableChannel) {
     return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
   }
 
@@ -106,7 +113,9 @@ function transformPageHead({ page }: TransformContext): HeadConfig[] {
   const href = pageToCanonicalHref(page);
   const head: HeadConfig[] = href ? [['link', { rel: 'canonical', href }]] : [];
 
-  if (channel === 'main') {
+  // Crawlable so links still pass through, but out of the index: ~30 archived copies
+  // of every page otherwise soak up the crawl budget the current docs need.
+  if (!isIndexableChannel) {
     head.push(['meta', { name: 'robots', content: 'noindex,follow' }]);
   }
 
@@ -287,6 +296,39 @@ const versionItems = [
   })),
 ];
 
+function sitemapUrlToPage(url: string): string {
+  const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+// VitePress derives <lastmod> by running `git log` inside its source dir. Production
+// builds point that at an untracked snapshot of the release tag, so the lookup comes
+// back empty and the sitemap ships with no dates at all. Resolve it from the tracked
+// checkout at the ref being built instead.
+function lastModifiedFor(url: string): string | undefined {
+  const ref = docsVersion && docsVersion !== 'main' ? docsVersion : 'HEAD';
+  const result = spawnSync('git', ['log', '-1', '--format=%cI', ref, '--', sitemapUrlToPage(url)], {
+    cwd: repoDocsDir,
+    encoding: 'utf8',
+  });
+
+  return (result.status === 0 && result.stdout.trim()) || undefined;
+}
+
+// Only the root channel publishes a sitemap. Archived and `main` builds would emit
+// their own copies listing the same canonical URLs, which just advertises the
+// duplicate trees we are trying to keep out of the index.
+const sitemap: UserConfig['sitemap'] = isIndexableChannel
+  ? {
+      hostname: DOCS_HOSTNAME,
+      transformItems(items) {
+        return items
+          .filter((item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`)
+          .map((item) => ({ ...item, lastmod: item.lastmod ?? lastModifiedFor(item.url) }));
+      },
+    }
+  : undefined;
+
 const nav: DefaultTheme.NavItem[] = [
   { text: 'Home', link: '/' },
   { text: 'Get Started', link: '/installation' },
@@ -306,7 +348,6 @@ const sidebar: DefaultTheme.SidebarItem[] = [
       { text: 'Usage', link: '/usage' },
       { text: 'Mining Workflow', link: '/mining-workflow' },
       { text: 'Launcher Script', link: '/launcher-script' },
-      { text: 'Feature Demos', link: '/demos' },
     ],
   },
   {
@@ -327,7 +368,6 @@ const sidebar: DefaultTheme.SidebarItem[] = [
       { text: 'Anki', link: '/anki-integration' },
       { text: 'Jellyfin', link: '/jellyfin-integration' },
       { text: 'YouTube', link: '/youtube-integration' },
-      { text: 'Anime Browser', link: '/anime-browser' },
       { text: 'Jimaku', link: '/jimaku-integration' },
       { text: 'TsukiHime', link: '/tsukihime-integration' },
       { text: 'AniList', link: '/anilist-integration' },
@@ -421,14 +461,7 @@ const config: UserConfig = {
   appearance: 'dark',
   cleanUrls: true,
   metaChunk: true,
-  sitemap: {
-    hostname: DOCS_HOSTNAME,
-    transformItems(items) {
-      return items.filter(
-        (item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`,
-      );
-    },
-  },
+  sitemap,
   transformHead: transformPageHead,
   lastUpdated: true,
   srcExclude: ['subagents/**', 'README.md'],

docs-site/.vitepress/theme/mermaid-modal.css

@@ -45,9 +45,7 @@
   border: 1px solid var(--vp-c-border);
   border-radius: 0;
   background: var(--vp-c-bg);
-  box-shadow:
-    0 8px 32px rgba(0, 0, 0, 0.3),
-    0 24px 64px rgba(0, 0, 0, 0.2);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3), 0 24px 64px rgba(0, 0, 0, 0.2);
   overflow: hidden;
 }
 
@@ -64,9 +62,7 @@
   font-family: var(--tui-font-mono);
   font-size: 12px;
   cursor: pointer;
-  transition:
-    border-color 180ms ease,
-    color 180ms ease;
+  transition: border-color 180ms ease, color 180ms ease;
 }
 
 .mermaid-modal__close:hover {

docs-site/.vitepress/theme/status-line.test.ts

@@ -10,5 +10,7 @@ test('status line file path formats version archive home without trailing slash'
 });
 
 test('status line file path keeps normal docs routes as markdown files', () => {
-  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe('v/0.12.0/configuration.md');
+  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe(
+    'v/0.12.0/configuration.md',
+  );
 });

docs-site/.vitepress/theme/tui-theme.css

@@ -22,8 +22,17 @@
 :root {
   --tui-font-mono: 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace;
   --tui-font-body:
-    'Manrope Default', 'M PLUS 1', 'Manrope', 'Noto Sans CJK JP', 'Noto Sans JP',
-    'Hiragino Kaku Gothic ProN', 'Meiryo', 'Yu Gothic', 'Hiragino Sans', system-ui, sans-serif;
+    'Manrope Default',
+    'M PLUS 1',
+    'Manrope',
+    'Noto Sans CJK JP',
+    'Noto Sans JP',
+    'Hiragino Kaku Gothic ProN',
+    'Meiryo',
+    'Yu Gothic',
+    'Hiragino Sans',
+    system-ui,
+    sans-serif;
   --tui-transition: 180ms ease;
 
   /* Theme-specific values — overridden in .dark below */
@@ -87,11 +96,8 @@ button,
 .VPFeature,
 .VPNavBarMenuLink,
 .VPSidebarItem .text {
-  transition:
-    color var(--tui-transition),
-    background var(--tui-transition),
-    border-color var(--tui-transition),
-    opacity var(--tui-transition);
+  transition: color var(--tui-transition), background var(--tui-transition),
+    border-color var(--tui-transition), opacity var(--tui-transition);
 }
 
 /* === Nav bar === */
@@ -212,7 +218,8 @@ button,
   background: var(--vp-c-bg-soft);
   border: 1px solid var(--vp-c-divider);
   color: var(--vp-c-brand-1);
-  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP', monospace;
+  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
+    monospace;
   font-variant-ligatures: none;
 }
 
@@ -221,7 +228,8 @@ button,
   border-radius: 0;
   border: 1px solid var(--vp-c-divider);
   background: var(--vp-c-bg-alt) !important;
-  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP', monospace;
+  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
+    monospace;
   font-variant-ligatures: none;
 }
 
@@ -265,9 +273,7 @@ button,
 .vp-doc a {
   text-decoration: none;
   border-bottom: 1px solid var(--tui-link-underline);
-  transition:
-    border-color var(--tui-transition),
-    color var(--tui-transition);
+  transition: border-color var(--tui-transition), color var(--tui-transition);
 }
 
 .vp-doc a:hover {
@@ -306,45 +312,20 @@ button,
   border-left-width: 1px;
 }
 
-.vp-doc .custom-block.tip {
-  border-color: var(--vp-c-brand-1);
-}
-.vp-doc .custom-block.tip::before {
-  content: '-- tip';
-  color: var(--vp-c-brand-1);
-}
+.vp-doc .custom-block.tip { border-color: var(--vp-c-brand-1); }
+.vp-doc .custom-block.tip::before { content: '-- tip'; color: var(--vp-c-brand-1); }
 
-.vp-doc .custom-block.info {
-  border-color: var(--vp-c-brand-2);
-}
-.vp-doc .custom-block.info::before {
-  content: '-- info';
-  color: var(--vp-c-brand-2);
-}
+.vp-doc .custom-block.info { border-color: var(--vp-c-brand-2); }
+.vp-doc .custom-block.info::before { content: '-- info'; color: var(--vp-c-brand-2); }
 
-.vp-doc .custom-block.warning {
-  border-color: var(--vp-c-warning-1);
-}
-.vp-doc .custom-block.warning::before {
-  content: '-- warning';
-  color: var(--vp-c-warning-1);
-}
+.vp-doc .custom-block.warning { border-color: var(--vp-c-warning-1); }
+.vp-doc .custom-block.warning::before { content: '-- warning'; color: var(--vp-c-warning-1); }
 
-.vp-doc .custom-block.danger {
-  border-color: var(--vp-c-danger-1);
-}
-.vp-doc .custom-block.danger::before {
-  content: '-- danger';
-  color: var(--vp-c-danger-1);
-}
+.vp-doc .custom-block.danger { border-color: var(--vp-c-danger-1); }
+.vp-doc .custom-block.danger::before { content: '-- danger'; color: var(--vp-c-danger-1); }
 
-.vp-doc .custom-block.details {
-  border-color: var(--vp-c-divider);
-}
-.vp-doc .custom-block.details::before {
-  content: '-- details';
-  color: var(--vp-c-text-2);
-}
+.vp-doc .custom-block.details { border-color: var(--vp-c-divider); }
+.vp-doc .custom-block.details::before { content: '-- details'; color: var(--vp-c-text-2); }
 
 .vp-doc .custom-block .custom-block-title {
   font-family: var(--tui-font-mono);
@@ -432,15 +413,11 @@ button,
 }
 
 @keyframes tui-blink {
-  0%,
-  100% {
-    opacity: 1;
-  }
-  50% {
-    opacity: 0;
-  }
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
 }
 
+
 /* === Statusline === */
 .tui-statusline {
   position: fixed;
@@ -480,7 +457,7 @@ button,
   margin-left: -12px;
 }
 
-.tui-statusline__mode[data-mode='HOME'] {
+.tui-statusline__mode[data-mode="HOME"] {
   background: var(--vp-c-brand-2);
 }
 
@@ -584,9 +561,7 @@ body {
 .VPFeatures .VPFeature {
   border-radius: 8px !important;
   border: 1px solid var(--vp-c-divider) !important;
-  transition:
-    border-color var(--tui-transition),
-    background var(--tui-transition),
+  transition: border-color var(--tui-transition), background var(--tui-transition),
     transform var(--tui-transition);
   position: relative;
   overflow: hidden;
@@ -697,7 +672,11 @@ body {
   transform: translateX(-50%);
   width: 600px;
   height: 400px;
-  background: radial-gradient(ellipse at center, var(--tui-hero-glow) 0%, transparent 70%);
+  background: radial-gradient(
+    ellipse at center,
+    var(--tui-hero-glow) 0%,
+    transparent 70%
+  );
   pointer-events: none;
   z-index: -1;
 }

docs-site/README.md

@@ -38,8 +38,10 @@ bun run docs:dev
 The public docs root is stable-only:
 
 - `/` serves the latest stable release docs.
-- `/main/` serves development docs from `main` and is marked `noindex,follow`.
+- `/main/` serves development docs from `main`.
 - `/v/<version>/` serves stable release archives.
 - Prerelease tags do not update the docs site.
 
+Only `/` is indexable. `/main/` and every `/v/<version>/` page carries a self-referential canonical plus `noindex,follow`, and the generated `_headers` file repeats that as an `X-Robots-Tag`. They stay crawlable so their links still resolve, but ~30 archived copies of every page would otherwise consume the crawl budget the current docs need. Only the root build emits `sitemap.xml`, and its `<lastmod>` dates come from `git log` against the tracked checkout at the released tag, because the build renders from an untracked snapshot that VitePress cannot date itself.
+
 Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.

docs-site/anime-browser.md

@@ -1,201 +0,0 @@
-# Anime Browser
-
-Search anime sources, pick an episode, and play it in mpv with SubMiner's overlay
-and mining tools attached — the same way a local file or a Jellyfin stream works.
-
-Open it with `subminer anime`, with `SubMiner.AppImage --anime`, or from
-**Browse Anime** in the tray menu. The window stays open while you watch, so you
-can queue the next episode without reopening it.
-
-While the window is open, SubMiner shows a tray icon and — on macOS — appears
-in the Cmd+Tab switcher and the Dock (macOS ties the two together), so you can
-flip between the browser and mpv. SubMiner normally hides itself from the Dock
-because the subtitle overlay needs that to float above fullscreen video; it
-hides again when the window closes during playback.
-
-Launching an episode starts a full SubMiner playback session, the same as
-playing a local file: the overlay and mining tools attach, and the tray icon
-stays available. In standalone `subminer anime` mode, closing the window while
-a video is playing leaves playback running — reopen the browser from the tray
-(**Browse Anime**). The app only exits with the window when nothing is playing.
-
-## How it works
-
-SubMiner does not implement any anime source itself. It runs **Aniyomi extension
-APKs** through a bundled JVM sidecar ([M-Extension-Server][mes]), asks the
-selected extension to resolve an episode, and hands the resulting URL to mpv.
-
-```
-extension APK  →  bridge (JVM)  →  { url, headers }  →  mpv  →  SubMiner overlay
-```
-
-Because the extension resolves the stream, whichever sources you install decide
-what is available. SubMiner only hosts them.
-
-## Installing extensions
-
-**SubMiner ships no extension repositories and bundles no sources.** There is no
-default repository, no suggested list, and no discovery. Until you add one, the
-browser has nothing to search — that is deliberate, and it is what keeps SubMiner
-a neutral host rather than a distributor.
-
-There are two ways to add extensions.
-
-### From a repository
-
-The window has three tabs — **Browse**, **Extensions**, and **Source settings** —
-and each one fills the window, so a long extension list is not squeezed in above
-the search results.
-
-Open the **Extensions** tab, paste a repository index URL, and choose
-**Add repository**. The URL must be `https` and point at a `.json` index file —
-`index.min.json` is the common Aniyomi name, but repositories are free to publish
-under another one (for example `video.min.json`). Anything else is rejected
-immediately rather than failing later. Everything before the file name is treated
-as the repository root, so `.apk` and icon URLs are resolved relative to it.
-
-Extensions your repositories offer but you do not have appear under
-**Available**, each with **Install**. Repositories are stored in config under
-`anime.repos`, so you can also manage them there and keep them in a dotfile.
-
-### Managing what is installed
-
-The Extensions tab opens with an **Installed** section listing everything in the
-extensions directory, with the sources each one provides and a **Remove**
-button. It is built from the directory rather than from a repository, so an
-extension you dropped in by hand — or one whose repository you have since
-removed — is still listed and still removable.
-
-**Update** appears next to an extension a configured repository still carries;
-it downloads the current version over the existing APK.
-
-### From a file
-
-Drop Aniyomi `.apk` files into the extensions directory, shown at the top of the
-Extensions tab. It defaults to `<userData>/anime-extensions` — on macOS,
-`~/Library/Application Support/SubMiner/anime-extensions` — and can be moved with
-`anime.extensionsDir`.
-
-A single APK may provide several sources; each appears separately in the
-**Source** picker. Extensions that fail to load are listed in the Installed
-section with the reason, so a broken APK is visible rather than silently
-missing.
-
-An extension that fails to load is skipped rather than blocking the others, so
-one bad APK will not hide the rest.
-
-## Searching every source at once
-
-With more than one source installed, the **Source** picker gains an
-**All sources** entry. Searching with it selected runs the query against every
-installed source at once, and each source's results appear the moment that
-source answers — a fast source is on screen while a slow one is still
-resolving. The status bar counts sources as they finish
-(`Searching… 3/5 sources · 42 results`).
-
-Each cover is labelled with the source it came from, and opening one always
-queries that source, whatever the picker says afterwards.
-
-A source that errors is named in the status bar and the rest still show their
-results; one extension that needs a login cannot blank the grid. If every
-source fails, the first error is shown in full.
-
-Typing a new search while one is still running simply starts over: results
-from the superseded search are discarded, even if its sources answer late.
-
-Source settings belong to a single extension, so the **Source settings** tab
-asks you to pick one while **All sources** is selected.
-
-## Settings
-
-| Key                      | Purpose                                                              |
-| ------------------------ | -------------------------------------------------------------------- |
-| `anime.repos`            | Repository index URLs. Empty by default.                             |
-| `anime.extensionsDir`    | Where APKs are read from. Empty uses `<userData>/anime-extensions`.  |
-| `anime.preferredQuality` | Preferred stream label, matched as a substring (for example `1080`). |
-
-## Source settings
-
-Most extensions need configuration before they return anything — a server
-address and credentials, a preferred quality, a language filter. Open the
-**Source settings** tab to edit them. Changes save as you make them and
-persist across restarts in `<userData>/anime-source-preferences.json`.
-
-Each save is handed back to the extension, so it can react: the Jellyfin source
-logs in when the address and password land, then fills in its media-library
-picker. Password-like fields are masked. Because that file can hold
-credentials, it is written with owner-only permissions.
-
-## The bridge
-
-The first launch downloads a platform bundle (~130 MB) containing the server and
-a matching Java runtime, so no system JDK is required. SubMiner pins one
-upstream release tag and the SHA-256 of each asset it has verified; the download
-is checked against that hash before anything runs, then unpacked into
-`<userData>/anime-bridge` and reused after that. Progress appears in the banner
-at the top of the window.
-
-The bridge stays running while the window is open. Resolved video URLs point at
-its own loopback proxy so the extension's cookies and headers apply, which means
-those URLs stop working once it exits — the window keeps it alive for the whole
-session.
-
-Two known limits:
-
-- There is no Android WebView, so extensions that need one (typically for
-  Cloudflare challenges) will fail with an error from the source.
-- Bundles are published for macOS (arm64, x64), Linux (x64), and Windows (x64),
-  but only the ones we have hashed ourselves will run: currently macOS arm64 and
-  Linux x64. The rest stop with "No pinned checksum for …" until a maintainer
-  verifies them. Other platforms are unsupported outright.
-
-## Playback
-
-Selecting an episode resolves the best available stream, applies the source's
-required headers as mpv `http-header-fields`, and loads it. The headers are
-readable back off mpv, so Anki card audio and screenshots fetch correctly too.
-
-HLS streams are routed through a small local proxy before mpv sees them. Some
-hosts disguise their video segments by prepending a fake image header (a real
-1x1 PNG) so scrapers back off; Aniyomi's own player strips this, but ffmpeg
-probes the segment as a picture and playback dies with "no audio or video data
-played". The proxy scans each segment for the first genuine MPEG-TS packet run
-and drops whatever junk sits in front of it. Segments that are not TS (fMP4,
-subtitles, encryption keys) pass through untouched, and direct-file streams
-skip the proxy entirely.
-
-"Playing" in the status bar means playing: after handing mpv the stream,
-SubMiner waits until mpv actually configures a video output before reporting
-success. If mpv gives up instead — a dead host, an undecodable stream — the
-browser shows mpv's error rather than pretending playback started (a failed
-load leaves no mpv window, because the player idles windowless).
-
-### Japanese audio, and switching tracks
-
-Sources often return a dub and the original audio as two separate entries — or
-as two audio tracks of one stream — and the dub is frequently listed first.
-SubMiner always aims at the Japanese audio:
-
-- Entries labelled as a dub are skipped as long as another entry exists. This
-  outranks `anime.preferredQuality`: a 1080p dub is the wrong file, not a better
-  one. If every entry is a dub, it still plays.
-- mpv's `alang` is set to `ja,jpn,jp,japanese` before the file loads, so a
-  stream carrying several audio tracks starts on the Japanese one. With no
-  Japanese track, mpv falls back to the first one as usual.
-- Any audio or subtitle tracks the extension supplies separately are added to
-  mpv with `audio-add` / `sub-add`, tagged with their language, and the
-  Japanese one is selected.
-
-The primary subtitle slot is reserved for Japanese — it is what the overlay
-mines. A source that only carries, say, English subtitles does not get them
-promoted to primary; instead the track is added with a normalized language tag
-(`English` → `en`), and the regular [dual-subtitle settings](configuration.md)
-apply: with `secondarySub.autoLoadSecondarySub` enabled and the language listed
-in `secondarySub.secondarySubLanguages`, it is picked up as the secondary
-subtitle, exactly as it would be for a local file.
-
-Every track is added, including the ones that are not selected, so all of them
-appear in mpv's track menu and can be switched by hand while watching
-(`#` cycles audio, `j` cycles subtitles by default).
-
-[mes]: https://github.com/1Selxo/M-Extension-Server

docs-site/aniskip-integration.md

@@ -45,9 +45,9 @@ Results are cached per file for the app session; only definitive "no intro found
 
 You can trigger AniSkip actions from mpv script-messages:
 
-| Command                                   | Effect                                                                  |
-| ----------------------------------------- | ----------------------------------------------------------------------- |
-| `script-message subminer-skip-intro`      | Skip to the intro end immediately (same as pressing the key)            |
+| Command | Effect |
+| ------- | ------ |
+| `script-message subminer-skip-intro` | Skip to the intro end immediately (same as pressing the key) |
 | `script-message subminer-aniskip-refresh` | Force a fresh lookup for the current file, discarding any cached result |
 
 These are handled by the SubMiner app over the IPC socket.

docs-site/anki-integration.md

@@ -136,6 +136,8 @@ SubMiner maps its data to your Anki note fields. Configure these under `ankiConn
 
 Field names are matched against your Anki note type case-insensitively (an exact match wins, then a lowercase comparison). If a configured field does not exist on the note type, SubMiner skips it without error.
 
+These mappings always control normal word-card enrichment, including Yomitan proxy/polling updates and manual clipboard updates. Enabling Lapis or Kiku does not replace the configured word-card sentence and audio fields with `Sentence` and `SentenceAudio`. The dedicated sentence-card and audio-card shortcuts still use those Lapis/Kiku field names.
+
 Two related options live alongside `fields`: `ankiConnect.deck` (target deck; empty falls back as described above) and `ankiConnect.tags` (tags added to mined cards, default `["SubMiner"]`; set `[]` to disable tagging). The `miscInfo` content is controlled by `ankiConnect.metadata.pattern` (default `[SubMiner] %f (%t)`; tokens: `%f` filename, `%F` filename with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` newline).
 
 ### Minimal Config
@@ -233,7 +235,7 @@ Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`)
 
 When media is available, mined-card overlay and system notifications include the same current-frame thumbnail.
 
-`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio, while leaving the word audio field unchanged.
+`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio in `ankiConnect.fields.audio`, even when `overwriteAudio` is disabled.
 
 ## AI Translation
 
@@ -287,6 +289,8 @@ Sentence card creation and audio card marking require a non-empty `ankiConnect.i
 
 Trigger with the mine sentence shortcut (`Ctrl/Cmd+S` by default). The card is created directly via AnkiConnect with the sentence, audio, and image filled in.
 
+The dedicated sentence-card and audio-card shortcuts use the Lapis/Kiku-compatible `Sentence` and `SentenceAudio` fields. This does not affect the configured fields used to enrich normal word cards.
+
 To mine multiple subtitle lines as one sentence card, use `Ctrl/Cmd+Shift+S` followed by a digit (1–9) to select how many recent lines to combine.
 
 ## Word Card Type (Kiku/Lapis)

docs-site/architecture.md

@@ -75,8 +75,8 @@ src/
   renderer/                # Overlay renderer (modularized UI/runtime)
     handlers/              # Keyboard/mouse/gamepad interaction modules
     modals/                # Modal flows (Jimaku, Kiku, subsync, runtime options, session help,
-                           #   character dictionary, playlist browser, subtitle sidebar,
-                           #   YouTube track picker, controller config/debug/select)
+                           #   changelog, character dictionary, playlist browser, subtitle
+                           #   sidebar, YouTube track picker, controller config/debug/select)
     positioning/           # Subtitle position controller (drag-to-reposition)
   settings/                # Settings window UI (model, controls, markup)
   types/                   # Domain type modules (anki, config, integrations, ...)

docs-site/changelog.md

@@ -1,9 +1,115 @@
 # Changelog
 
+## v0.19.5 (2026-08-30)
+
+**Fixed**
+
+- **Anki Card Update Progress**: The card-update spinner now stays visible until audio and image updates finish, instead of disappearing early.
+- **Anki Word-Card Fields**: Word-card enrichment now writes sentence text and audio to the fields configured in AnkiConnect, while the dedicated sentence-card and audio-card actions keep their existing compatible field names.
+- **Overlapping Subtitles**:
+  - Subtitle lines that start while another line is still on screen now appear alongside it, instead of staying hidden until a track switch or seek.
+  - Subtitles shown at the same time now stack by their authored screen position, with top signs and song lines above bottom dialogue.
+  - Half-size ASS furigana is no longer shown as if it were a dialogue line.
+- **YouTube Auto Captions**:
+  - Auto-generated captions now follow their intended timing and two-row roll-up layout.
+  - Long speech is paged instead of covering the video with a wall of text.
+  - Explicitly timed sound cues like `[音楽]` no longer cover later dialogue.
+
+## v0.19.4 (2026-08-25)
+
+**Added**
+- **Library Merge & Move**: Duplicate library cards for the same show can now be combined. Select cards in the library grid and use "Merge Selected" to pick which entry to keep and move every episode onto it, preserving sessions, mined cards, and watch time. Episodes can also be reassigned individually via the "→" button, useful when a file lands under a stray title; manual assignments survive later filename parsing, Jellyfin refreshes, and season repair. Exact AniList title matches with compatible seasons now merge automatically, while fuzzy matches surface as dismissible "Possible duplicate" reviews instead of merging silently.
+- **Duplicate Line Cleanup Tool**: The Vocabulary tab's new "Duplicates" button scans a chosen time window (7 days through all time) for old karaoke/typeset duplicate-line bursts, shows what it found, and collapses each run to one line once confirmed; `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>` options. Watch time and lines-seen totals are left unchanged.
+
+**Changed**
+- **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
+
+**Fixed**
+- **Subtitle & Karaoke Duplication**:
+  - Karaoke and animated signs are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved, instead of flooding the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, and repeated animation events.
+  - Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly.
+  - Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container.
+  - Secondary subtitles go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines.
+  - Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**:
+  - Generation, merged rebuilds, and imports no longer freeze the app on large dictionaries; snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path.
+  - Dictionaries are reused instead of regenerated when MeCab finds no name splits.
+  - Cached portraits restore correctly after the portrait index finishes loading post-tokenization.
+  - Desktop progress notifications on Linux AppImage installs update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**:
+  - The macOS window-tracking helper targets macOS 12.0+ instead of requiring the build machine's exact macOS version, fixing crashes on older systems like Ventura that left the overlay stuck on "Overlay loading".
+  - mpv IPC connection attempts time out and retry, showing an actionable error if content still isn't ready after 30 seconds.
+  - Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly.
+  - On macOS, reused modals and the stats window open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
+- **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
+- **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.
+- **Stats Performance & Reliability**: Immersion stats storage now sets its SQLite busy timeout before WAL setup, avoiding transient lock errors under concurrent writes. Deletes in the stats dashboard no longer freeze the UI, run proportional to what's deleted instead of rebuilding full lifetime summaries, retry safely if the delete worker crashes, and no longer rescan the whole library when deleting very common words; a new index also makes large session deletes drop from minutes to milliseconds. Library merges, video moves, and AniList reassignments got the same lifetime-summary fix.
+- **Vocabulary Stats Accuracy**: Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, new-word history uses corrected daily rollups (fixing legacy timestamp and time-zone issues), summary cards refresh automatically after edits to the exclusion list, and rapid exclusion edits no longer race each other.
+- **Rofi MKV Thumbnails**: Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Docs Site Indexing: Excluded the `/main/` and `/v/<version>/` docs trees from search indexing (self-referential canonical, `noindex,follow`, matching `X-Robots-Tag`) so crawlers focus on current docs instead of ~30 archived copies of every page, and restored `<lastmod>` dates in the docs sitemap that were silently dropped by production builds.
+
+</details>
+
+## v0.19.3 (2026-08-13)
+
+**Added**
+- Changelog Modal: Adds an in-app changelog you can open from the tray ("View Changelog") or the "What's New" button on the update notification, so the notification stays reachable while you read. It shows the newest published release notes (falling back to the bundled changelog if that fetch fails), folds older versions while keeping the current one expanded, and supports keyboard navigation (`J`/`K`/arrows, `Enter`, `R`, `Esc`).
+
+**Changed**
+- Subtitle Tokenization Performance: Reworks subtitle dictionary lookups to cut per-line work roughly in half, cache repeated lookups across lines, and stop tokenization from competing with on-screen subtitle prefetching. Also fixes several accuracy issues along the way: dropped readings on trailing kana, character names being skipped after a dictionary sync, annotations not refreshing after mining a card, and halfwidth katakana character names losing their reading or being swallowed by other words.
+
+**Fixed**
+- Character Dictionary Large Imports: Large character dictionaries (e.g. One Piece) no longer fail to install from a fixed timeout budget; the import now scales its time budget to dictionary size and reports detailed progress (page/character counts, image download progress, elapsed time) instead of one static message.
+- Stats Delete Responsiveness: Deleting sessions, episodes, or library entries no longer freezes the stats page or an active video player; deletes are now batched into a single transaction.
+- Styled Subtitle Cue Parsing: Heavily typeset subtitles (karaoke, signs) no longer flood the subtitle sidebar with garbage; vector drawing commands are no longer shown as text, and duplicate/animation-burst cues now collapse into one.
+- X11 mpv Renderer: Fixes an mpv crash on the first fullscreen toggle for X11/XWayland users with `gpu-next` shaders (e.g. ArtCNN), which was caused by X11 mode forcing the legacy OpenGL renderer.
+- X11 Overlay Display Scaling: Fixes the overlay appearing oversized and offset from mpv on X11/XWayland under fractional or mixed-monitor display scaling.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Subtitle text is now decoded from ASS exactly once at ingest, so the renderer, timing tracker, and tokenizer all share one decoded value instead of each re-deriving it.
+- Added per-stage debug timings (`scanMs`, `mecabMs`, `frequencyMs`, `annotateMs`) to the subtitle tokenization pipeline log.
+
+</details>
+
+## v0.19.2 (2026-08-04)
+
+**Changed**
+- Subsync: The sync modal now lets you choose both the reference subtitle (correct timing) and the out-of-sync subtitle to retime, for both alass and ffsubsync. alass can also use the loaded video's audio as a reference for local files. Retiming the secondary track now reloads the result into the secondary slot instead of overwriting the primary subtitle.
+
+**Fixed**
+- Streaming Subtitle Tokenization: Jellyfin streams now seed subtitle tokenization directly from the downloaded subtitle file instead of relying on an mpv event that could be missed, and prefetching now runs to the end of the file and clears between episodes. The tokenization cache was raised from 256 to 2500 lines, and parsed cues are no longer lost when the active subtitle track briefly can't be resolved (e.g. switching to an embedded track). Together these prevent episodes from falling back to slow, line-by-line tokenization during playback.
+- Overlay: Subtitle lines now appear immediately at their cue time even on a tokenization cache miss, upgrading in place once tokens and annotations are ready, instead of waiting on a line still being processed. A failed tokenization is no longer cached as plain text, so repeated lines get another chance at annotations.
+- Background Logging: Background startup now respects the configured logging level when no explicit log level is passed.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Patched three high-severity dependency advisories (`undici`, `brace-expansion`, `fast-uri`).
+
+</details>
+
+## v0.19.1 (2026-08-01)
+
+**Added**
+- Word Card Type: Adds a setting (Settings > Mining/Anki > Kiku/Lapis Features > "Word Card Type") to choose which card-type flag SubMiner marks on Kiku/Lapis word cards — `word-and-sentence` (default), `click`, `sentence`, `audio`, or `none`. Click cards (`IsClickCard`) can now be flagged, and setting any card-type flag clears the others so a note can't claim two types at once.
+
+**Fixed**
+- Yomitan Popup: Fixes the macOS Yomitan popup going inert after mining a card — clicks outside the popup no longer pass through to mpv, and scrolling over the popup scrolls its definitions instead of seeking playback.
+- YouTube Playlist Links: Fixes opening a video from a playlist URL (e.g. a Watch Later link with `list=`/`index=`) timing out while probing subtitles, metadata, or the playback URL.
+
 ## v0.19.0 (2026-07-29)
 
 **Added**
-
 - Anki Maturity Highlighting: Known-word subtitle highlights can now be colored by Anki card maturity (new, learning, young, mature), similar to asbplayer. Tier thresholds and colors are configurable, with a runtime toggle and an updated help legend.
 - Post-Playback Menu: After a watch-history episode ends, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit. The pre-playback series menu now offers the previous episode too.
 - Delete Library Entries: The stats Library detail view can now delete an entire title in one step (episodes, sessions, subtitle lines, rollups, cover art, and vocabulary counts). Delete progress is now shown app-wide via a progress bar and status toast instead of disappearing when you switch tabs.
@@ -11,11 +117,9 @@
 - TsukiHime Subtitle Downloads: Added subtitle downloads for the current video via TsukiHime, loading Japanese as the primary track and your configured secondary language directly into mpv.
 
 **Changed**
-
 - Clipboard-Video Shortcut: The "append clipboard video to queue" shortcut is now configurable.
 
 **Fixed**
-
 - AniList Season Resolution: Season 2+ files now resolve to the correct AniList entry instead of silently falling back to season 1 (which mismatched character dictionaries and watch progress). Manual overrides now stay scoped per season, fix both the dictionary and progress tracking together, and also correct per-season cover art.
 - Subtitle Annotation Accuracy: Fixed several annotation edge cases, including inconsistent POS exclusions on merged quote-particle tokens, dropped annotations on supplementary-plane kanji, katakana punctuation wrongly treated as noise, and certain kanji vocabulary losing N+1 highlighting eligibility.
 - AnkiConnect Proxy Port Conflict: Video startup no longer crashes when another process already holds the configured AnkiConnect proxy port; a notification now explains how to resolve it.
@@ -31,7 +135,6 @@
 <summary>Internal changes</summary>
 
 **Internal**
-
 - Added a golden-file regression test corpus for the tokenizer/annotation pipeline, plus scripts to record new fixtures and diff against stock Yomitan.
 - Consolidated renderer modal state handling into a descriptor registry.
 - Consolidated CI quality checks (PR, stable, and prerelease) into one reusable workflow with mpv plugin tests and dependency audits.
@@ -48,12 +151,10 @@
 <h2>v0.18.0 (2026-07-10)</h2>
 
 **Added**
-
 - Sentence Audio Normalization: Generated sentence audio is now normalized to -23 LUFS by default, and clips mined from playback mirror mpv's software volume curve with a limiter to prevent clipping. Both behaviors are configurable independently.
 - Watch History Command: Added `subminer -H` / `--history` to browse watch history, replay or continue episodes, or pick one via fzf or rofi, with cover art shown in the rofi picker.
 
 **Changed**
-
 - Fzf Preview Layout: Moved fzf previews below launcher menus, giving long titles and metadata more room.
 - Known-Word Highlighting: Now compares subtitle and Anki-card readings, preventing false matches between homographs and unrelated words that share a reading, while still supporting matching across kana and kanji spellings.
 - Annotation Filtering: Standalone suffix tokens (e.g. さん, れる) are now excluded from JLPT/frequency/N+1 highlighting by default, matching how particles and interjections are treated; configurable via the pos2 exclusion setting.
@@ -61,7 +162,6 @@
 - Stats Trend Charts: Overhauled with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and value-sorted tooltips.
 
 **Fixed**
-
 - Background Stats Server: `subminer app` background launches now auto-start the stats server when enabled, and skip startup if one is already running.
 - Character Name Highlighting: Character dictionaries now split unspaced native names more reliably, and portraits, highlights, and hover lookup survive punctuation, unmatched text, and competing dictionary matches without incorrectly splitting longer words.
 - Highlighting Coverage: Frequency/JLPT highlighting and vocabulary stats now include content adverbs (e.g. 確かに, やはり) and kanji nouns MeCab tags as non-independent (e.g. 日, 点, 以外), while still suppressing interjections, pronouns, and grammar fragments; lexicalized kana expressions like かといって keep their annotations.
@@ -75,7 +175,6 @@
 <summary>Internal changes</summary>
 
 **Internal**
-
 - Test lanes moved to `scripts/test-lanes.ts` with per-directory discovery and isolated per-file timeouts; CI now covers previously orphaned stats, scripts, plugin process-retry, and runtime-compat suites, plus a new stats lane in the change-verification workflow.
 
 </details>
@@ -88,18 +187,15 @@
 <h2>v0.17.2 (2026-06-28)</h2>
 
 **Fixed**
-
 - YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
 - YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
 
 <h2>v0.17.1 (2026-06-27)</h2>
 
 **Added**
-
 - YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
 
 **Fixed**
-
 - Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
 - YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
 
@@ -185,7 +281,6 @@
 <summary>Internal changes</summary>
 
 **Internal**
-
 - **Build**: `make deps` now initializes git submodules before installing dependencies on a fresh source checkout.
 - **Release Tooling**: Release notes now credit contributors and first-time authors resolved from changelog fragments via git and the GitHub API.
 - **Changelog Guidance**: PR fragment guidance updated to preserve separate-outcome fragments while directing contributors to consolidate same-PR follow-up notes before adding churn.
@@ -200,11 +295,9 @@
 <h2>v0.15.2 (2026-06-02)</h2>
 
 **Changed**
-
 - Yomitan: Updated the bundled Yomitan build to the latest vendored revision.
 
 **Fixed**
-
 - Anki - Animated AVIF: Clip timing no longer starts or ends early; word-audio lead-in and clip duration are now aligned to frame boundaries.
 - Overlay (Hyprland): Fixed fullscreen overlay alignment - modal, stats, and sidebar content no longer shift below the mpv window.
 - Overlay (macOS): Subtitle bars are now interactive immediately after autoplay starts with "wait for overlay to be ready" enabled, without requiring a manual click.

docs-site/configuration.md

@@ -1196,9 +1196,9 @@ See [TsukiHime Integration](/tsukihime-integration) for the modal workflow, lang
 
 ### Subtitle Sync
 
-Sync the active subtitle track from the overlay picker using `alass` or `ffsubsync`. Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).
+Sync a subtitle track from the overlay picker using `alass` or `ffsubsync`. The picker lets you choose which track gets retimed (the active primary track by default) and, for alass, which reference it is aligned against (the secondary subtitle track by default). Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).
 
-- [`alass`](https://github.com/kaegi/alass) - fast, audio-independent sync using a secondary subtitle as reference
+- [`alass`](https://github.com/kaegi/alass) - fast, audio-independent sync using another subtitle as reference; it can also take the local video file as reference (alass extracts the audio itself)
 - [`ffsubsync`](https://github.com/smacke/ffsubsync) - audio-based sync using the video file as reference
 
 ```json

docs-site/demos.md

@@ -5,7 +5,7 @@ Short recordings of SubMiner's key features and integrations from real playback
 <script setup>
 import { withBase } from 'vitepress';
 
-const v = '20260301-1';
+const v = '20260819-1';
 </script>
 
 ## Anki Card Mining & Enrichment

docs-site/development.md

@@ -6,7 +6,7 @@ For internal architecture/workflow guidance, use `docs/README.md` at the repo ro
 
 - [Bun](https://bun.sh)
 - A system `lua` interpreter for `bun run test:launcher` / `bun run test:plugin:src`
-- macOS builds compile a Swift helper via `scripts/build-macos-helper.sh` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)
+- macOS builds compile a Swift helper via `scripts/prepare-build-assets.mjs` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)
 
 ## Setup
 

docs-site/immersion-tracking.md

@@ -34,7 +34,7 @@ The same immersion data powers the stats dashboard.
 - In-app overlay: focus the visible overlay, then press the key from `stats.toggleKey` (default: `` ` `` / `Backquote`).
 - Launcher command: run `subminer stats` to start the local stats server on demand (it also opens the dashboard in your browser when `stats.autoOpenBrowser` is enabled; the default is `false`).
 - Background server: run `subminer stats -b` to start or reuse a dedicated background stats daemon without keeping the launcher attached, and `subminer stats -s` to stop that daemon.
-- Maintenance commands: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand; `subminer stats cleanup -l` repairs lifetime summary tables. `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
+- Maintenance commands: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand; `subminer stats cleanup -l` repairs lifetime summary tables non-destructively (recomputed from per-episode history, so lifetime totals older than the session retention window are kept); `subminer stats cleanup --duplicate-lines` collapses repeated lines left behind by typeset subtitles (see [Repeated Line Cleanup](#repeated-line-cleanup)). `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
 - Browser page: open `http://127.0.0.1:6969` directly if the local stats server is already running.
 
 ### Dashboard Tabs
@@ -57,6 +57,13 @@ Jellyfin stream URLs are normalized to stable item links before stats titles are
 
 When YouTube channel metadata is available, the Library tab groups videos by creator/channel and treats each tracked video as an episode-like entry inside that channel section.
 
+A library entry is identified by its parsed title plus any detected season, so the same show can end up on several cards when releases disagree about the title or omit the season tag. Two fixes are available:
+
+- **Merge duplicates.** Hit **Select** above the grid, tick the cards that are the same show, and choose **Merge Selected**. Pick which entry to keep in the dialog; every episode moves onto it and the other cards are removed. Nothing is deleted, so sessions, mined cards and watch time all carry over. SubMiner remembers the merged title variants, so future episodes parsed with one of those names join the kept entry instead of recreating a duplicate card.
+- **Move a single episode.** Hover an episode row in a title's episode list and use the **→** button to reassign it to another library entry. The correction is remembered, so later filename parsing or Jellyfin metadata cannot move that episode back. For local files, later episodes in the same directory inherit the correction when their detected seasons are compatible and every manual correction there points to the same entry; a file that parses to a title which already has its own library entry keeps that identity instead. Conflicting seasons or manual destinations are left for review. If the move empties the old entry, that card is removed and you are returned to the grid.
+
+Once cover art resolves a series to an AniList entry, cards with compatible seasons are folded together automatically only when the searched title exactly matches an AniList title or synonym. A fuzzy result that points at an AniList entry already used by another card appears as a **Possible duplicate** review above the Library grid instead. Choose **Review merge** to compare the cards and pick which one to keep, or **Not duplicates** to dismiss that suggestion permanently. Entries with conflicting explicit season numbers are left alone rather than merged or suggested.
+
 Open a title and use **Delete Entry** in its header to remove a mistakenly tracked show outright. This deletes every episode of that title along with their sessions, subtitle lines, rollups and cover art, drops the words and kanji that were only seen there, and removes the card from the Library grid. Individual episodes and sessions can still be deleted on their own from the episode list and session rows. Entry deletion is refused while that title is the one currently playing.
 
 ![Stats Library](/screenshots/stats-library.png)
@@ -75,7 +82,7 @@ Expandable session history with new-word activity, cumulative totals, and pause/
 
 #### Vocabulary
 
-Top repeated words (click a bar to open the word), new-word timeline, cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.
+The summary cards show all unique vocabulary and kanji recorded in the local tracking database; **New This Week** is the only weekly figure and uses a rolling seven-day window. The word and kanji tables load first while those complete totals calculate separately. Top Repeated Words and New Words by Day use complete tracking history rather than the table's browsing page. New-word history is maintained as a permanent daily lexical rollup using the same token-visibility rules as the totals, including normalization of older timestamps stored in either seconds or milliseconds and retroactive corrections when tracked material is removed or reprocessed. On the first launch after an applicable upgrade, that history is version-rebuilt in the background and the chart refreshes when it is ready; if it remains unavailable, polling stops and an inline Retry control appears. The cards and charts also refresh automatically after the word exclusion list changes. The rest of the tab includes cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.
 
 ![Stats Vocabulary](/screenshots/stats-vocabulary.png)
 
@@ -125,6 +132,36 @@ Secondary subtitle text (typically English translations) is stored alongside pri
 
 The Vocabulary tab toolbar includes an **Exclusions** button for hiding words from all vocabulary views. Excluded words are stored in the immersion database, with older browser localStorage exclusions imported on first load after upgrade. They can be managed (restored or cleared) from the exclusion modal. Exclusions affect stat cards, charts, the frequency rank table, and the word list.
 
+### Repeated Line Cleanup
+
+Karaoke openings and animated signs are authored as one subtitle event per animation frame, all carrying the same text. Playback reports every one of those frames, so a single OP lyric could be recorded hundreds of times and dominate "Top Repeated Words".
+
+Recording now collapses those runs as they happen, matching what the subtitle sidebar shows:
+
+- When a typeset ASS file stores a clean lyric or sign in a timed authoring comment, or in full-line events surrounding generated fragments, the matching complete line is recorded once. The repeated glyph or clip-animation frames are not recorded. Dialogue spoken while such an animation is on screen records as itself, without the fragment lines beside it.
+- When karaoke styling redraws the same complete lyric across consecutive color or highlight phases, those phases are combined into one line with their full timing. Repeated ordinary dialogue remains separate.
+- When the active subtitle source has been parsed, its cue list has already had duplicate events and animation bursts merged. A line landing inside a surviving cue but after that cue's start is a frame the sidebar merged away, and is not recorded.
+- When no parsed cue covers the live timing, including while a subtitle source is changing or shifted, the strict metadata-free rule applies: a run of identical, contiguous lines each shorter than 0.1s stops being recorded after a few frames. Runs are tracked per line of text, so dual-line karaoke (a kanji and a romaji line frame-flipped together) collapses both lines. Ordinary repeated dialogue, and lines held for a normal beat, always record.
+
+For stats recorded before this, the Vocabulary tab toolbar has a **Duplicates** button:
+
+- Pick how far back to look (7 days, 30 days, 90 days, 1 year, or all time). A narrower window does less work and keeps older history untouched.
+- **Scan** reports the bursts found, the lines they added, and the word and kanji counts they inflated, without writing anything.
+- **Clean Up** applies exactly what the scan reported: each run collapses to its first line (extended to cover the run), and the removed lines' word and kanji occurrences are subtracted from the vocabulary aggregates.
+
+The same thing runs from the terminal:
+
+```bash
+subminer stats cleanup --duplicate-lines --dry-run --lookback-days 30
+subminer stats cleanup --duplicate-lines --lookback-days 30
+```
+
+`--duplicate-lines` (short: `-d`) picks the cleanup mode, so it cannot be combined with `--vocab` or `--lifetime`, and `--dry-run` and `--lookback-days <days>` only apply to it. Omitting `--lookback-days` scans all history; the value must be at least one day.
+
+The cleanup chains runs per line of text, so interleaved dual-line karaoke collapses each of its lines. It also removes the short residue the live rule stores before a run is long enough to recognize: a run one frame short of the usual minimum qualifies when every event is under the strict 0.1s bound.
+
+Runs never cross a session boundary, so rewatching an episode keeps both watches. Session telemetry (watch time, lines seen, tokens seen) and the rollups derived from it are left as recorded: they are cumulative samples taken during playback, and cannot be recomputed for sessions whose raw rows have since been pruned.
+
 ## Retention Defaults
 
 By default, SubMiner keeps all retention tables and raw data (`0` means keep all) while continuing daily/monthly rollup maintenance:
@@ -145,6 +182,7 @@ In practice:
 - Anime and episode pages keep lifetime totals from summary tables while session drill-down still reads retained sessions directly. With the current defaults, both are kept forever.
 - Trends can read the full available history because daily/monthly rollups are also kept forever by default.
 - Vocabulary and kanji totals are cumulative and not bounded by the raw session retention knobs.
+- New-word charts use their own permanent lexical daily rollups, which are not pruned by activity-rollup retention.
 
 ## Storage / Performance Model
 
@@ -314,6 +352,7 @@ Rollup tables:
 
 - `imm_daily_rollups`
 - `imm_monthly_rollups`
+- `imm_lexical_daily_rollups` - permanent first-discovery counts for vocabulary and kanji chart history
 - `imm_rollup_state` - incremental rollup progress bookkeeping
 
 Vocabulary tables:

docs-site/index.md

@@ -88,7 +88,7 @@ features:
 <script setup>
 import { withBase } from 'vitepress';
 
-const demoAssetVersion = '20260223-2';
+const demoAssetVersion = '20260819-1';
 </script>
 
 <div class="landing-shell">

docs-site/installation.md

@@ -392,7 +392,7 @@ subminer -u
 subminer --update
 ```
 
-SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer` plus the rofi theme at `SubMiner/themes/subminer.rasi`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
+SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer`, the rofi theme at `SubMiner/themes/subminer.rasi`, and the scoped Matroska thumbnailer registration under `SubMiner/thumbnailers`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
 
 The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. On Linux it replaces the running `.AppImage` in place via `electron-updater` and refreshes the managed support assets from `subminer-assets.tar.gz`; AppImages managed by a system package (for example the AUR `/opt/SubMiner/SubMiner.AppImage`) are skipped so the package manager stays in charge.
 
@@ -404,7 +404,7 @@ SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IP
 
 The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) - without it the overlay starts but subtitles won't appear.
 
-The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. On Linux, the `subminer` launcher now checks for its managed runtime plugin copy and rofi theme before every mpv-managed launch and installs those support assets from the bundled app automatically if either one is missing. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
+The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. On Linux, the `subminer` launcher checks for its managed runtime plugin copy, rofi theme, and scoped thumbnailer registration before every mpv-managed launch and installs those support assets from the bundled app automatically if one is missing. For a rofi picker launch, this check runs before the picker opens. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
 
 ## Platform Notes
 
@@ -456,18 +456,20 @@ sudo chmod +x /usr/local/bin/subminer
 
 ### Linux Support Assets
 
-SubMiner ships the Linux rofi theme plus the launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:
+SubMiner ships the Linux rofi theme, scoped Matroska thumbnailer registration, and launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:
 
 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/thumbnailers
+cp /tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer ~/.local/share/SubMiner/thumbnailers/
 mkdir -p ~/.local/share/SubMiner/plugin
 cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```
 
-`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs the managed runtime plugin copy and rofi theme from the bundled app if either support asset is missing, so manual extraction is mainly useful for pre-seeding or custom setups.
+`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs all three assets from the bundled app if one is missing, so manual extraction is mainly useful for pre-seeding or custom setups. Rofi receives the SubMiner data path through its process-local `XDG_DATA_DIRS`, so the thumbnailer registration does not change the desktop-wide configuration.
 
 Override the theme path with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.
 

docs-site/ipc-contracts.md

@@ -38,7 +38,7 @@ flowchart TB
 
 ## Runtime Sockets
 
-The renderer↔main bridge above lives _inside_ the Electron app. A separate set of OS sockets connects the app to the other runtimes - mpv and the launcher/plugin. These carry no renderer payloads and bypass the contract/validator layer; they are command and property channels between processes.
+The renderer↔main bridge above lives *inside* the Electron app. A separate set of OS sockets connects the app to the other runtimes - mpv and the launcher/plugin. These carry no renderer payloads and bypass the contract/validator layer; they are command and property channels between processes.
 
 - **mpv IPC socket** (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows): the `MpvIpcClient` in the main process connects here to send JSON commands and subscribe to playback/subtitle properties via `observe_property`. Created by mpv's `--input-ipc-server`.
 - **App control socket** (`/tmp/subminer-control-<uid>-<hash>.sock`, or a named pipe on Windows): the launcher and the mpv plugin send CLI-style commands (`--start`, `--show-visible-overlay`, `--texthooker`) to a running app here. It also dedupes a second `subminer` invocation into the existing instance instead of launching twice.
@@ -69,15 +69,15 @@ How these sockets are established during launch is covered in [Playback Startup
 
 ## Core Surfaces
 
-| File                                   | Role                                                                                                                    |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `src/shared/ipc/contracts.ts`          | Canonical channel names and payload type contracts. Single source of truth for both processes.                          |
-| `src/shared/ipc/validators.ts`         | Runtime payload parsers and type guards. Every `invoke` payload is validated here before the handler runs.              |
-| `src/preload.ts`                       | Renderer-side bridge. Exposes a typed API surface to the renderer - only approved channels are accessible.              |
-| `src/main/ipc-runtime.ts`              | Main-process handler registration and routing. Wires validated channels to domain handlers.                             |
-| `src/core/services/ipc.ts`             | Service-level invoke handling. Applies guardrails (validation, error wrapping) before calling domain logic.             |
-| `src/core/services/anki-jimaku-ipc.ts` | Integration-specific IPC boundary for Anki and Jimaku operations.                                                       |
-| `src/main/cli-runtime.ts`              | CLI/runtime command boundary. Handles commands that originate from the launcher or mpv plugin rather than the renderer. |
+| File | Role |
+| --- | --- |
+| `src/shared/ipc/contracts.ts` | Canonical channel names and payload type contracts. Single source of truth for both processes. |
+| `src/shared/ipc/validators.ts` | Runtime payload parsers and type guards. Every `invoke` payload is validated here before the handler runs. |
+| `src/preload.ts` | Renderer-side bridge. Exposes a typed API surface to the renderer - only approved channels are accessible. |
+| `src/main/ipc-runtime.ts` | Main-process handler registration and routing. Wires validated channels to domain handlers. |
+| `src/core/services/ipc.ts` | Service-level invoke handling. Applies guardrails (validation, error wrapping) before calling domain logic. |
+| `src/core/services/anki-jimaku-ipc.ts` | Integration-specific IPC boundary for Anki and Jimaku operations. |
+| `src/main/cli-runtime.ts` | CLI/runtime command boundary. Handles commands that originate from the launcher or mpv plugin rather than the renderer. |
 
 ## Contract Rules
 

docs-site/jimaku-integration.md

@@ -23,12 +23,12 @@ If no files match the current episode filter, a "Show all files" button lets you
 
 ### Modal Keyboard Shortcuts
 
-| Key                       | Action                       |
-| ------------------------- | ---------------------------- |
-| `Enter` (in text field)   | Search                       |
-| `Enter` (in list)         | Select entry / download file |
-| `Arrow Up` / `Arrow Down` | Navigate entries or files    |
-| `Escape`                  | Close modal                  |
+| Key | Action |
+| --- | --- |
+| `Enter` (in text field) | Search |
+| `Enter` (in list) | Select entry / download file |
+| `Arrow Up` / `Arrow Down` | Navigate entries or files |
+| `Escape` | Close modal |
 
 ## Configuration
 
@@ -41,26 +41,26 @@ Add a `jimaku` section to your `config.jsonc`:
     "apiKeyCommand": "cat ~/.jimaku_key",
     "apiBaseUrl": "https://jimaku.cc",
     "languagePreference": "ja",
-    "maxEntryResults": 10,
-  },
+    "maxEntryResults": 10
+  }
 }
 ```
 
-| Option                      | Type                         | Default               | Description                                                                                                                                              |
-| --------------------------- | ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `jimaku.apiKey`             | `string`                     | -                     | Jimaku API key (plaintext). Mutually exclusive with `apiKeyCommand`.                                                                                     |
-| `jimaku.apiKeyCommand`      | `string`                     | -                     | Shell command that prints the API key to stdout. Useful for secret managers (e.g., `pass jimaku/api-key`).                                               |
-| `jimaku.apiBaseUrl`         | `string`                     | `"https://jimaku.cc"` | Base URL for the Jimaku API. Only change this if using a mirror or local instance.                                                                       |
-| `jimaku.languagePreference` | `"ja"` \| `"en"` \| `"none"` | `"ja"`                | Sort subtitle files by language tag. `"ja"` pushes Japanese-tagged files to the top; `"en"` does the same for English. `"none"` preserves the API order. |
-| `jimaku.maxEntryResults`    | `number`                     | `10`                  | Maximum number of anime entries returned per search.                                                                                                     |
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `jimaku.apiKey` | `string` | - | Jimaku API key (plaintext). Mutually exclusive with `apiKeyCommand`. |
+| `jimaku.apiKeyCommand` | `string` | - | Shell command that prints the API key to stdout. Useful for secret managers (e.g., `pass jimaku/api-key`). |
+| `jimaku.apiBaseUrl` | `string` | `"https://jimaku.cc"` | Base URL for the Jimaku API. Only change this if using a mirror or local instance. |
+| `jimaku.languagePreference` | `"ja"` \| `"en"` \| `"none"` | `"ja"` | Sort subtitle files by language tag. `"ja"` pushes Japanese-tagged files to the top; `"en"` does the same for English. `"none"` preserves the API order. |
+| `jimaku.maxEntryResults` | `number` | `10` | Maximum number of anime entries returned per search. |
 
 The keyboard shortcut is configured separately under `shortcuts`:
 
 ```jsonc
 {
   "shortcuts": {
-    "openJimaku": "Ctrl+Shift+J",
-  },
+    "openJimaku": "Ctrl+Shift+J"
+  }
 }
 ```
 

docs-site/launcher-script.md

@@ -34,18 +34,22 @@ subminer -R -r -d ~/Anime              # rofi picker, recursive
 subminer -R /directory                 # rofi picker, directory shortcut
 ```
 
-rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme plus the Linux launcher-managed runtime plugin copy in the release assets tarball:
+rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme, a scoped `ffmpegthumbnailer` MIME registration, and the Linux launcher-managed runtime plugin copy in the release assets tarball:
 
 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/thumbnailers
+cp /tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer ~/.local/share/SubMiner/thumbnailers/
 mkdir -p ~/.local/share/SubMiner/plugin
 cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```
 
-Once the `SubMiner` data dir exists, `subminer -u` refreshes both assets automatically. Normal Linux launcher playback also checks for the managed runtime plugin copy and rofi theme before mpv launch and installs them from the bundled app automatically if either one is missing.
+Once the `SubMiner` data dir exists, `subminer -u` refreshes these assets automatically. Normal Linux launcher playback checks for all three assets and installs them from the bundled app when one is missing. For `subminer -R`, this repair runs before rofi opens.
+
+When `ffmpegthumbnailer` is installed, SubMiner prepends its own data directory to `XDG_DATA_DIRS` for the rofi process only. This lets rofi recognize the canonical Matroska MIME types used by newer GLib versions without changing the desktop-wide MIME or thumbnailer configuration. An existing registration in your own `$XDG_DATA_HOME/thumbnailers` still takes priority.
 
 The theme is auto-detected from these paths (first match wins):
 
@@ -151,6 +155,7 @@ subminer stats -b                       # start background stats daemon
 | `subminer stats`                           | Start the stats server (opens the dashboard when `stats.autoOpenBrowser` is on)                   |
 | `subminer stats -b` / `-s`                 | Start/reuse or stop the background stats daemon                                                   |
 | `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows (`-v` vocab, `-l` lifetime summaries)           |
+| `subminer stats cleanup -d`                | Collapse repeated lines from typeset subs (`--dry-run`, `--lookback-days <n>`)                    |
 | `subminer stats rebuild` / `backfill`      | Rebuild or backfill rollup data                                                                   |
 | `subminer doctor`                          | Dependency + config + socket diagnostics (`--refresh-known-words` refreshes the known-word cache) |
 | `subminer settings`                        | Open the SubMiner settings window                                                                 |

docs-site/links.test.ts

@@ -21,6 +21,7 @@ function slugify(heading: string): string {
 }
 
 const EXCLUDED_PAGES = new Set(['README.md']);
+const UNLISTED_ROUTES = new Set(['/demos']);
 const PUBLIC_PREFIXES = ['/assets/', '/screenshots/', '/config.example.jsonc', '/favicon'];
 
 function loadPages(): Map<string, string> {
@@ -114,7 +115,7 @@ test('slugify matches the VitePress cases these docs actually rely on', () => {
   expect(slugify('2. Install SubMiner')).toBe('_2-install-subminer');
 });
 
-test('every docs page is reachable from the sidebar', async () => {
+test('every docs page is reachable from the sidebar unless explicitly unlisted', async () => {
   const { default: config } = await import('./.vitepress/config');
   const sidebar = config.themeConfig?.sidebar as Array<{
     items?: Array<{ text: string; link?: string }>;
@@ -127,6 +128,8 @@ test('every docs page is reachable from the sidebar', async () => {
     }
   }
 
-  const orphans = [...pages.keys()].filter((route) => !linked.has(route));
+  const orphans = [...pages.keys()].filter(
+    (route) => !linked.has(route) && !UNLISTED_ROUTES.has(route),
+  );
   expect(orphans).toEqual([]);
 });

docs-site/mining-workflow.md

@@ -41,7 +41,7 @@ If you prefer a hands-on approach (animecards-style), you can copy the current s
    - For multiple lines: press `Ctrl/Cmd+Shift+C`, then a digit `1`–`9` to select how many recent subtitle lines to combine. The combined text is copied to the clipboard.
 3. Press `Ctrl/Cmd+V` to update the last-added card with the clipboard contents plus audio, image, and translation - the same fields auto-update would fill.
 
-Manual clipboard updates always replace generated sentence audio, even when `ankiConnect.behavior.overwriteAudio` is disabled. The word audio field is left unchanged because the word itself does not change in this flow.
+Manual clipboard updates always replace generated sentence audio in `ankiConnect.fields.audio`, even when `ankiConnect.behavior.overwriteAudio` is disabled. Normal word-card updates use the configured sentence and audio fields even when Lapis or Kiku support is enabled.
 
 This is useful when auto-update is disabled or when you want explicit control over which subtitle line gets attached to the card.
 
@@ -108,8 +108,12 @@ The secondary bar is a compact top-strip region in the same overlay window. It s
 - Quick comprehension checks without leaving the mining flow.
 - Auto-populating the translation field on mined cards - when a card is created, SubMiner uses the secondary subtitle text as the translation field value (unless AI translation is configured to override it).
 
+For local media, SubMiner can parse supported embedded secondary tracks into timed cues. For remote URLs and files on network mounts, it uses mpv's live secondary subtitle text instead of scanning the media with ffmpeg.
+
 It is controlled by `secondarySub` configuration and shares its lifecycle with the main overlay window. Cycle which track feeds it with `Shift+J`.
 
+SubMiner collapses duplicate ASS layers in parsed secondary tracks. Exact repeated lines collapse at any length, while distinct simultaneous short lines remain separate. Long dialogue and positioned-sign copies also collapse when they differ only in whitespace or terminal punctuation. Dense multi-row sign layouts, such as translated timetables, are excluded instead of being concatenated into the secondary bar.
+
 ### Display Modes
 
 Both the primary and secondary subtitle bars share the same three visibility modes, and each can be changed independently at runtime:
@@ -161,10 +165,13 @@ If your subtitle file is out of sync with the audio, SubMiner can resynchronize
 
 1. Open the subsync modal from the overlay.
 2. Select the sync engine (alass or ffsubsync).
-3. For alass, select a reference subtitle track from the video.
-4. SubMiner runs the sync and reloads the corrected subtitle.
+3. For alass, pick the **reference** - the subtitle with correct timing. This defaults to the secondary subtitle track. The loaded video file can also be used as the reference (alass extracts the audio itself), but it is never the default.
+4. Pick the **out-of-sync subtitle** - the track that gets retimed. This defaults to the active primary subtitle track and applies to both engines.
+5. SubMiner runs the sync and reloads the corrected subtitle into the slot the out-of-sync track came from: retiming the secondary track keeps it secondary and leaves the primary track selected.
 
-For remote streams, including Jellyfin playback, the modal only offers alass. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync needs direct access to the local media file and is unavailable for stream URLs.
+The reference and the out-of-sync subtitle must be different tracks; the reference list hides whichever track is selected as the target.
+
+For remote streams, including Jellyfin playback, the modal only offers alass with a subtitle reference. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync and the video-file reference need direct access to the local media file and are unavailable for stream URLs.
 
 When you mine a sentence card from the stats dashboard, SubMiner can also use `alass` automatically to align a local English sidecar against the matching local Japanese sidecar before filling the card translation field. The source subtitle files are not modified; SubMiner writes a temporary retimed copy and reuses it while the stats server is running.
 

docs-site/mpv-plugin.md

@@ -31,20 +31,20 @@ input-ipc-server=\\.\pipe\subminer-socket
 
 The plugin reads options from `script-opts` with the `subminer-` prefix (for example `--script-opts=subminer-backend=hyprland`). Managed launches inject these automatically from your SubMiner config; the shipped `subminer.conf` is intentionally empty so command-line opts always win.
 
-| Option                                         | Default          | Description                                                                                     |
-| ---------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
-| `binary_path`                                  | `""`             | Path to the SubMiner binary; empty enables [auto-detection](#binary-auto-detection)             |
-| `socket_path`                                  | platform default | mpv IPC socket path (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows)          |
-| `texthooker_enabled`                           | `no`             | Start the texthooker server with the overlay                                                    |
-| `texthooker_port`                              | `5174`           | Texthooker server port                                                                          |
-| `backend`                                      | `auto`           | Window backend (`auto`, `hyprland`, `sway`, `x11`, `macos`)                                     |
-| `auto_start`                                   | `no`             | Start the overlay app on `file-loaded` (managed launches set this from `mpv.autoStartSubMiner`) |
-| `auto_start_visible_overlay`                   | `no`             | Show the visible overlay on auto-start (from `auto_start_overlay` in config)                    |
-| `overlay_loading_osd`                          | `no`             | Show an OSD loading spinner while the overlay starts                                            |
-| `auto_start_pause_until_ready`                 | `yes`            | Keep mpv paused until the overlay reports tokenization-ready                                    |
-| `auto_start_pause_until_ready_timeout_seconds` | `30`             | Timeout before resuming playback anyway                                                         |
-| `osd_messages`                                 | `yes`            | Show plugin OSD status messages                                                                 |
-| `log_level`                                    | `info`           | Plugin log verbosity                                                                            |
+| Option                                             | Default          | Description                                                                     |
+| -------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------- |
+| `binary_path`                                      | `""`             | Path to the SubMiner binary; empty enables [auto-detection](#binary-auto-detection) |
+| `socket_path`                                      | platform default | mpv IPC socket path (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows) |
+| `texthooker_enabled`                               | `no`             | Start the texthooker server with the overlay                                    |
+| `texthooker_port`                                  | `5174`           | Texthooker server port                                                          |
+| `backend`                                          | `auto`           | Window backend (`auto`, `hyprland`, `sway`, `x11`, `macos`)                     |
+| `auto_start`                                       | `no`             | Start the overlay app on `file-loaded` (managed launches set this from `mpv.autoStartSubMiner`) |
+| `auto_start_visible_overlay`                       | `no`             | Show the visible overlay on auto-start (from `auto_start_overlay` in config)    |
+| `overlay_loading_osd`                              | `no`             | Show an OSD loading spinner while the overlay starts                            |
+| `auto_start_pause_until_ready`                     | `yes`            | Keep mpv paused until the overlay reports tokenization-ready                    |
+| `auto_start_pause_until_ready_timeout_seconds`     | `30`             | Timeout before resuming playback anyway                                         |
+| `osd_messages`                                     | `yes`            | Show plugin OSD status messages                                                 |
+| `log_level`                                        | `info`           | Plugin log verbosity                                                            |
 
 ## Keybindings
 

docs-site/public/config.example.jsonc

@@ -611,18 +611,6 @@
     } // Lapis kiku setting.
   }, // Automatic Anki updates and media generation options.
 
-  // ==========================================
-  // Anime Browser
-  // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
-  // add a repository index URL here (or drop .apk files in the extensions directory) to have any.
-  // Hot-reload: anime changes apply the next time the anime browser opens.
-  // ==========================================
-  "anime": {
-    "extensionsDir": "", // Directory holding Aniyomi extension .apk files. Empty uses <userData>/anime-extensions.
-    "repos": [], // Extension repository index URLs (any https .json index, e.g. https://.../index.min.json). Empty by default; SubMiner ships no repositories.
-    "preferredQuality": "" // Preferred stream quality label, matched as a substring (for example: 1080). Empty uses the source order.
-  }, // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
-
   // ==========================================
   // Jimaku
   // Jimaku API configuration and defaults.

docs-site/seo.test.ts

@@ -56,34 +56,43 @@ test('main docs canonical uses /main/ and emits noindex', async () => {
     { rel: 'canonical', href: 'https://docs.subminer.moe/main/' },
   ]);
   expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+  expect(mainDocsConfig.sitemap).toBeUndefined();
 
   process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
   process.env.SUBMINER_DOCS_BASE = previousBase;
 });
 
-test('latest stable archive canonical points to root equivalent', async () => {
-  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
-  const previousBase = process.env.SUBMINER_DOCS_BASE;
-  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
-  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
-  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
-  process.env.SUBMINER_DOCS_BASE = '/v/0.14.0/';
-  process.env.SUBMINER_DOCS_VERSION = 'v0.14.0';
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  const { default: latestArchiveConfig } = await import('./.vitepress/config?latest-archive');
+test.each([
+  ['latest stable', 'v0.14.0', '/v/0.14.0/', 'https://docs.subminer.moe/v/0.14.0/usage'],
+  ['superseded', 'v0.12.0', '/v/0.12.0/', 'https://docs.subminer.moe/v/0.12.0/usage'],
+])(
+  '%s archive keeps a self-referential canonical and stays out of the index',
+  async (_label, version, base, expectedCanonical) => {
+    const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+    const previousBase = process.env.SUBMINER_DOCS_BASE;
+    const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+    const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+    process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+    process.env.SUBMINER_DOCS_BASE = base;
+    process.env.SUBMINER_DOCS_VERSION = version;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+    try {
+      const { default: archiveConfig } = await import(`./.vitepress/config?archive-${version}`);
 
-  const head = await latestArchiveConfig.transformHead?.(makeTransformContext('usage.md'));
+      const head = await archiveConfig.transformHead?.(makeTransformContext('usage.md'));
 
-  expect(head).toContainEqual([
-    'link',
-    { rel: 'canonical', href: 'https://docs.subminer.moe/usage' },
-  ]);
-
-  process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
-  process.env.SUBMINER_DOCS_BASE = previousBase;
-  process.env.SUBMINER_DOCS_VERSION = previousVersion;
-  process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
-});
+      expect(head).toContainEqual(['link', { rel: 'canonical', href: expectedCanonical }]);
+      expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+      // A sitemap here would advertise the archive tree we just excluded.
+      expect(archiveConfig.sitemap).toBeUndefined();
+    } finally {
+      process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+      process.env.SUBMINER_DOCS_BASE = previousBase;
+      process.env.SUBMINER_DOCS_VERSION = previousVersion;
+      process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    }
+  },
+);
 
 test('stable archive theme links stay on the selected version', async () => {
   const previousCwd = process.cwd();
@@ -433,3 +442,22 @@ test('docs sitemap excludes duplicate README page from indexable URLs', async ()
 
   expect(transformedItems?.map((item) => item.url)).toEqual(['', 'usage']);
 });
+
+test('docs sitemap dates every URL from the tracked checkout', async () => {
+  const previousRepoDir = process.env.SUBMINER_DOCS_REPO_DIR;
+  // Production builds render from an untracked snapshot, so the date has to come from
+  // the real checkout rather than VitePress's own srcDir git lookup.
+  process.env.SUBMINER_DOCS_REPO_DIR = docsSiteDir;
+  try {
+    const { default: sitemapConfig } = await import('./.vitepress/config?sitemap-lastmod');
+
+    const items = await sitemapConfig.sitemap?.transformItems?.([{ url: '' }, { url: 'usage' }]);
+
+    expect(items).toHaveLength(2);
+    for (const item of items ?? []) {
+      expect(item.lastmod).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    }
+  } finally {
+    process.env.SUBMINER_DOCS_REPO_DIR = previousRepoDir;
+  }
+});

docs-site/shortcuts.md

@@ -12,10 +12,10 @@ All shortcuts are configurable in `config.jsonc` under `shortcuts` and `keybindi
 
 ## App-Wide Shortcuts
 
-| Shortcut      | Action                 | Scope                                    | Configurable                           |
-| ------------- | ---------------------- | ---------------------------------------- | -------------------------------------- |
-| `Alt+Shift+O` | Toggle visible overlay | Works while the overlay or mpv has focus | `shortcuts.toggleVisibleOverlayGlobal` |
-| `Alt+Shift+Y` | Open Yomitan settings  | OS-global (registered with the OS)       | Fixed (not configurable)               |
+| Shortcut      | Action                 | Scope                                       | Configurable                           |
+| ------------- | ---------------------- | -------------------------------------------- | -------------------------------------- |
+| `Alt+Shift+O` | Toggle visible overlay | Works while the overlay or mpv has focus     | `shortcuts.toggleVisibleOverlayGlobal` |
+| `Alt+Shift+Y` | Open Yomitan settings  | OS-global (registered with the OS)           | Fixed (not configurable)               |
 
 ::: tip
 `Alt+Shift+O` is dispatched by the overlay window and the mpv plugin, so it works from either surface without OS registration. Only `Alt+Shift+Y` is registered with the OS; if it conflicts with another application, that binding cannot be changed. All `shortcuts.*` keys hot-reload - no restart needed.
@@ -75,21 +75,21 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle
 
 ## Subtitle & Feature Shortcuts
 
-| Shortcut           | Action                                                   | Config key                                                                                      |
-| ------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`                                                                  |
-| `Ctrl/Cmd+D`       | Open loaded character dictionary manager                 | `shortcuts.openCharacterDictionaryManager`                                                      |
-| `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`                                                                  |
-| `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                                                                     |
-| `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                                                                          |
-| `Ctrl+Shift+T`     | Open TsukiHime subtitle search modal (EN/JA tabs)        | `shortcuts.openTsukihime`                                                                       |
-| `Ctrl/Cmd+N`       | Toggle overlay notification history panel                | `shortcuts.toggleNotificationHistory`                                                           |
-| `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                                                                                   |
-| `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                                                                      |
-| `Ctrl/Cmd+A`       | Append clipboard video path to mpv playlist              | `shortcuts.appendClipboardVideoToQueue`                                                         |
+| Shortcut           | Action                                                   | Config key                                 |
+| ------------------ | -------------------------------------------------------- | ------------------------------------------ |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`             |
+| `Ctrl/Cmd+D`       | Open loaded character dictionary manager                 | `shortcuts.openCharacterDictionaryManager` |
+| `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`             |
+| `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                |
+| `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                     |
+| `Ctrl+Shift+T`     | Open TsukiHime subtitle search modal (EN/JA tabs)       | `shortcuts.openTsukihime`                 |
+| `Ctrl/Cmd+N`       | Toggle overlay notification history panel                | `shortcuts.toggleNotificationHistory`      |
+| `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                              |
+| `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                 |
+| `Ctrl/Cmd+A`       | Append clipboard video path to mpv playlist              | `shortcuts.appendClipboardVideoToQueue`    |
 | `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey` (overlay) / `shortcuts.toggleSubtitleSidebar` (mpv session binding) |
-| `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`                                                                               |
-| `W`                | Mark current video watched and advance to next in queue  | `stats.markWatchedKey`                                                                          |
+| `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`                          |
+| `W`                | Mark current video watched and advance to next in queue  | `stats.markWatchedKey`                     |
 
 `shortcuts.openAnimetosho` remains accepted as a deprecated alias for `shortcuts.openTsukihime`. The current name takes precedence when both are configured.
 

docs-site/subtitle-sidebar.md

@@ -9,9 +9,11 @@ The sidebar is enabled by default. Set `subtitleSidebar.enabled` to `false` if y
 When SubMiner parses the active subtitle source into a cue list, the sidebar becomes available. Toggle it with the `\` key (configurable via `subtitleSidebar.toggleKey`). While open:
 
 - The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`).
-- Clicking any cue seeks mpv to that timestamp.
+- Clicking any cue seeks mpv into that line. For overlapping ASS karaoke, SubMiner moves past the previous line's exit animation when the selected cue has enough time remaining.
 - The sidebar stays synchronized with the overlay - media transitions and subtitle source changes update both simultaneously.
 
+For typeset ASS karaoke and animated signs, SubMiner collapses generated animation frames and repeated full-line color phases before they reach the sidebar. It recovers a clean complete line from a matching timed authoring comment or from full-line events surrounding generated fragments. Ordinary ASS comments, editor notes, alternate lines, repeated dialogue, and separately positioned signs remain distinct.
+
 The sidebar only appears when a parsed cue list is available. External subtitle sources that SubMiner cannot parse (for example, embedded ASS tracks rendered directly by mpv) will not populate the sidebar.
 
 ## Layout Modes
@@ -62,23 +64,23 @@ Styling lives under the `css` object, using CSS property names and CSS custom pr
 | `pauseVideoOnHover` | boolean | `true`        | Pause playback while hovering the cue list                                 |
 | `autoScroll`        | boolean | `true`        | Keep the active cue in view during playback                                |
 
-| `css` property                               | Default                                                         | Description                         |
-| -------------------------------------------- | --------------------------------------------------------------- | ----------------------------------- |
-| `font-family`                                | `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP` | Cue text font family                |
-| `color`                                      | `#cad3f5`                                                       | Default cue text color              |
-| `background-color`                           | `rgba(73, 77, 100, 0.9)`                                        | Sidebar shell background color      |
-| `font-size`                                  | `16px`                                                          | Base cue font size                  |
-| `opacity`                                    | `0.95`                                                          | Sidebar opacity between `0` and `1` |
-| `--subtitle-sidebar-max-width`               | `420px`                                                         | Maximum sidebar width               |
-| `--subtitle-sidebar-timestamp-color`         | `#a5adcb`                                                       | Cue timestamp color                 |
-| `--subtitle-sidebar-active-line-color`       | `#f5bde6`                                                       | Active cue text color               |
-| `--subtitle-sidebar-active-background-color` | `rgba(138, 173, 244, 0.22)`                                     | Active cue background color         |
-| `--subtitle-sidebar-hover-background-color`  | `rgba(54, 58, 79, 0.84)`                                        | Hovered cue background color        |
+| `css` property                              | Default                     | Description                  |
+| ------------------------------------------- | --------------------------- | ---------------------------- |
+| `font-family`                               | `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP` | Cue text font family |
+| `color`                                     | `#cad3f5`                   | Default cue text color       |
+| `background-color`                          | `rgba(73, 77, 100, 0.9)`    | Sidebar shell background color |
+| `font-size`                                 | `16px`                      | Base cue font size           |
+| `opacity`                                   | `0.95`                      | Sidebar opacity between `0` and `1` |
+| `--subtitle-sidebar-max-width`              | `420px`                     | Maximum sidebar width        |
+| `--subtitle-sidebar-timestamp-color`        | `#a5adcb`                   | Cue timestamp color          |
+| `--subtitle-sidebar-active-line-color`      | `#f5bde6`                   | Active cue text color        |
+| `--subtitle-sidebar-active-background-color`| `rgba(138, 173, 244, 0.22)` | Active cue background color  |
+| `--subtitle-sidebar-hover-background-color` | `rgba(54, 58, 79, 0.84)`    | Hovered cue background color |
 
 ## Keyboard Shortcut
 
-| Key | Action                  | Config key                  |
-| --- | ----------------------- | --------------------------- |
-| `\` | Toggle subtitle sidebar | `subtitleSidebar.toggleKey` |
+| Key | Action                  | Config key                     |
+| --- | ----------------------- | ------------------------------ |
+| `\` | Toggle subtitle sidebar | `subtitleSidebar.toggleKey`    |
 
 The toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source. See [Keyboard Shortcuts](/shortcuts) for the full shortcut reference.

docs-site/troubleshooting.md

@@ -171,7 +171,9 @@ Without FFmpeg, card creation still works but audio and image fields will be emp
 
 **Audio or screenshot generation hangs**
 
-Media generation has a 30-second timeout (60 seconds for animated AVIF). If your video file is on a slow network mount or the codec requires software decoding, generation may time out. Try:
+Audio extraction has a 2-minute timeout. SubMiner also limits FFmpeg probing when mpv provides the selected audio stream, which avoids scanning unrelated subtitle and font-attachment streams in large MKV files. Screenshots retain a 30-second timeout, and animated AVIF uses 60 seconds.
+
+If your video file is on a slow or unresponsive network mount, generation may still time out. Try:
 
 - Using a local copy of the video file.
 - Reducing `ankiConnect.media.imageQuality` or switching from `avif` to `static` image type.
@@ -227,7 +229,7 @@ Install ffsubsync or configure the path:
 
 If subtitle sync fails (the error message is prefixed with the engine name):
 
-- Ensure the reference subtitle track exists in the video (alass requires a source track).
+- Ensure a reference is selected (alass needs either a second subtitle track or the local video file, and it cannot be the same track that is being retimed).
 - Check that `ffmpeg` is available (used to extract the internal subtitle track).
 - Try running the sync tool manually to see detailed error output.
 - ffsubsync requires local files and cannot handle remote media streams (e.g., streaming URLs).
@@ -405,8 +407,9 @@ On any Wayland session that is not Hyprland or Sway (KDE Plasma, GNOME, and othe
 
 SubMiner handles this automatically:
 
-- It launches its own window under XWayland (it sets `--ozone-platform-hint=x11`).
-- Every mpv it launches (via the `subminer` launcher, Jellyfin, or YouTube) is pinned to XWayland too - Wayland environment hints are stripped and an X11 GPU context (`--gpu-context=x11egl,x11`) is applied.
+- It launches its own window under XWayland (it sets `--ozone-platform=x11`).
+- Every mpv it launches (via the `subminer` launcher, Jellyfin, or YouTube) is pinned to XWayland too - Wayland environment hints are stripped and an X11 GPU context (`--gpu-context=x11vk,x11egl,x11`) is applied. Only the window context is overridden; your `vo`/`gpu-api` and user shaders are left alone.
+- Fractional and mixed-monitor display scaling is handled per screen when SubMiner maps XWayland mpv coordinates to the overlay.
 - While mpv is windowed, the overlay is a managed X11 window owned by the tracked mpv window (`WM_TRANSIENT_FOR`), so it stays above mpv while other foreground X11/Xwayland apps can still cover both windows.
 - While tracked mpv is fullscreen, SubMiner swaps the visible overlay to a focusable-false X11 override-redirect window. That path can stay above the active fullscreen mpv window without requiring a KDE/KWin-specific rule, and SubMiner hides/releases it when mpv is no longer the active X11/Xwayland window.
 - The visible overlay is shown inactive on Linux, so normal hover should not steal keyboard focus from mpv.
@@ -420,7 +423,7 @@ Requirements: `xdotool`, `xprop`, and `xwininfo` must be installed. SubMiner use
 This almost always means mpv came up as a **native Wayland** window that the XWayland overlay cannot cover. It happens when mpv is launched **manually** (your own command), because SubMiner can only force XWayland on the mpv processes it launches itself. Fix it one of these ways:
 
 - Launch playback through SubMiner (the `subminer` launcher or the tray), which forces XWayland for you, or
-- Force XWayland in your own mpv invocation, e.g. `mpv --gpu-context=x11egl …`, or launch with `WAYLAND_DISPLAY= mpv …`, or set `gpu-context=x11egl` in your `mpv.conf`.
+- Force XWayland in your own mpv invocation, e.g. `mpv --gpu-context=x11vk,x11egl,x11 …`, or launch with `WAYLAND_DISPLAY= mpv …`, or set `gpu-context=x11vk` (Vulkan) / `gpu-context=x11egl` (OpenGL) in your `mpv.conf`.
 
 To confirm mpv is on XWayland, `xdotool search --class mpv` should return a window id (a native Wayland mpv returns nothing).
 

docs-site/usage.md

@@ -70,7 +70,6 @@ subminer https://youtu.be/...     # Play a YouTube URL
 subminer stats                    # Open the immersion stats dashboard
 subminer doctor                   # Check dependencies, config, and the mpv socket
 subminer settings                 # Open the SubMiner settings window
-subminer anime                    # Open the anime browser window
 subminer app --setup              # Re-open first-run setup
 subminer -u                       # Check for updates
 ```
@@ -96,6 +95,8 @@ subminer texthooker               # Texthooker-only mode (-o also opens the brow
 subminer stats -b                 # Start/reuse the background stats daemon
 subminer stats -s                 # Stop the background stats daemon
 subminer stats cleanup            # Backfill vocabulary metadata, prune stale rows
+subminer stats cleanup -d --dry-run  # Preview cleanup of repeated typeset subtitle lines
+subminer stats cleanup -d --lookback-days 30  # Clean only lines recorded in the last 30 days
 subminer stats rebuild            # Rebuild rollup data
 subminer doctor --refresh-known-words  # Refresh the known-word cache
 subminer logs -e                  # Export a sanitized log ZIP and print its path
@@ -108,6 +109,8 @@ subminer app --stop               # Stop the background app
 subminer --version                # Print the launcher's version
 ```
 
+`stats cleanup` runs one mode per invocation: `-v`/`--vocab` (the default), `-l`/`--lifetime`, or `-d`/`--duplicate-lines`; explicitly selected modes cannot be combined. `--dry-run` and `--lookback-days <days>` apply to `--duplicate-lines` only and are rejected without it; `--lookback-days` must be at least one day, and leaving it off scans all history.
+
 Jellyfin, cross-machine sync, and character-dictionary commands have their own sections: [Jellyfin](/jellyfin-integration), [Sync Between Machines](/launcher-script#sync-between-machines), and [Character Dictionary](/character-dictionary).
 
 </details>
@@ -132,14 +135,13 @@ SubMiner.AppImage --open-tsukihime        # Open TsukiHime subtitle search
 SubMiner.AppImage --yomitan               # Open Yomitan settings
 SubMiner.AppImage --settings              # Open the SubMiner settings window
 SubMiner.AppImage --jellyfin              # Open the Jellyfin setup window
-SubMiner.AppImage --anime                 # Open the anime browser window
 SubMiner.AppImage --dictionary            # Generate a character dictionary ZIP
 SubMiner.AppImage --start --dev           # Enable app/dev mode
 SubMiner.AppImage --start --log-level debug  # Verbose logging without dev mode
 SubMiner.AppImage --help                  # Show all options
 ```
 
-The remaining flags are internal or scripting-only surfaces: the `--jellyfin-*` family (login, library listing, item playback, cast announce), `--sync-cli` (the app's headless sync entrypoint that `subminer sync` proxies to), `--dictionary-candidates` / `--dictionary-select`, and `--playback-feedback <text>`. Run `SubMiner.AppImage --help` for the complete list. The previous `--open-animetosho` flag is still accepted as a deprecated alias for `--open-tsukihime`.
+The remaining flags are internal or scripting-only surfaces: the `--jellyfin-*` family (login, library listing, item playback, cast announce), `--sync-cli` (the app's headless sync entrypoint that `subminer sync` proxies to), the `--stats-cleanup-*` family that `subminer stats cleanup` forwards (`--stats-cleanup-vocab`, `--stats-cleanup-lifetime`, `--stats-cleanup-duplicate-lines`, and its `--stats-cleanup-dry-run` / `--stats-cleanup-lookback-days <days>` modifiers), `--dictionary-candidates` / `--dictionary-select`, and `--playback-feedback <text>`. Run `SubMiner.AppImage --help` for the complete list. The previous `--open-animetosho` flag is still accepted as a deprecated alias for `--open-tsukihime`.
 
 </details>
 
@@ -147,11 +149,13 @@ The tray menu includes `Export Logs`, which creates the same sanitized local-dat
 
 Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for starting or stopping cast discovery in the current app session without changing config.
 
+The tray menu also includes `View Changelog`, which opens the in-app changelog modal. It fetches the changelog from the newest published release, so you see release notes for versions newer than the one you run; if the download fails it falls back to the changelog bundled with your install and says so. Versions in the current `0.x` line are expanded by default and older lines are folded, matching this site's [Changelog](/changelog). A badge marks the version you have installed, and newer versions are tagged `New`. The same modal opens from the `What's New` button on the update-available overlay notification.
+
 ### Logging and App Mode
 
 - `--log-level` controls logger verbosity.
 - `--dev` and `--debug` are app/dev-mode switches; they are not log-level aliases.
-- `--background` defaults to quieter logging (`warn`) unless `--log-level` is set.
+- `--background` starts at the default quieter logging level (`warn`), then follows `logging.level` after config loads. An explicit `--log-level` remains the override.
 - `--background` launched from a terminal detaches and returns the prompt; stop it with tray Quit or `SubMiner.AppImage --stop` (`SubMiner.exe --stop` on Windows).
 - Linux desktop launcher starts SubMiner with `--background` by default (via electron-builder `linux.executableArgs`).
 - On Hyprland and other Wayland compositors, the tray icon appears only when your panel provides a StatusNotifier/AppIndicator tray host.
@@ -370,6 +374,8 @@ Press `V` to cycle the primary SubMiner subtitle bar through hidden → visible
 
 `Ctrl/Cmd+/` opens the session help modal with the current overlay and mpv keybindings. The same help view is also available through the `y-h` chord in mpv.
 
+The changelog modal (tray > `View Changelog`) works the same way: it renders over mpv when a video is playing and in its own window otherwise. Use `J`/`K` or the arrow keys to move between versions, `Enter` to fold or unfold one, `R` to refetch, and `Esc` to close.
+
 Hovering over subtitle text pauses mpv by default; leaving resumes it. Yomitan popups also pause playback by default. Set `subtitleStyle.autoPauseVideoOnHover: false` or `subtitleStyle.autoPauseVideoOnYomitanPopup: false` to disable either behavior.
 
 ### Drag-and-Drop

docs-site/websocket-texthooker-api.md

@@ -2,7 +2,7 @@
 
 **Who this page is for:** developers and tinkerers who want to consume SubMiner's live subtitle stream from their own tools - a browser tab, an automation script, or another mpv plugin. If you just want subtitles in a browser tab for Yomitan, skip to [Texthooker Integration Guide](#texthooker-integration-guide); the rest is reference for building custom clients.
 
-A _texthooker_ is a page/tool that receives the text currently on screen so a dictionary extension (like Yomitan) can look words up. SubMiner ships its own texthooker UI and also broadcasts subtitle text over local WebSockets that any client can connect to.
+A *texthooker* is a page/tool that receives the text currently on screen so a dictionary extension (like Yomitan) can look words up. SubMiner ships its own texthooker UI and also broadcasts subtitle text over local WebSockets that any client can connect to.
 
 SubMiner exposes a small set of local integration surfaces for browser tools, automation helpers, and mpv-driven workflows:
 
@@ -15,12 +15,12 @@ This page documents those integration points and shows how to build custom consu
 
 ## Quick Reference
 
-| Surface               | Default                     | Purpose                                            |
-| --------------------- | --------------------------- | -------------------------------------------------- |
-| `websocket`           | `ws://127.0.0.1:6677`       | Basic subtitle broadcast stream                    |
-| `annotationWebsocket` | `ws://127.0.0.1:6678`       | Structured stream with token metadata              |
-| `texthooker`          | `http://127.0.0.1:5174`     | Local texthooker UI with injected websocket config |
-| mpv plugin            | `script-message subminer-*` | Start/stop/toggle/status automation inside mpv     |
+| Surface | Default | Purpose |
+| --- | --- | --- |
+| `websocket` | `ws://127.0.0.1:6677` | Basic subtitle broadcast stream |
+| `annotationWebsocket` | `ws://127.0.0.1:6678` | Structured stream with token metadata |
+| `texthooker` | `http://127.0.0.1:5174` | Local texthooker UI with injected websocket config |
+| mpv plugin | `script-message subminer-*` | Start/stop/toggle/status automation inside mpv |
 
 ## Enable and Configure the Services
 
@@ -30,16 +30,16 @@ SubMiner's integration ports are configured in `config.jsonc`. All three service
 {
   "websocket": {
     "enabled": "auto",
-    "port": 6677,
+    "port": 6677
   },
   "annotationWebsocket": {
     "enabled": true,
-    "port": 6678,
+    "port": 6678
   },
   "texthooker": {
     "launchAtStartup": true,
-    "openBrowser": false,
-  },
+    "openBrowser": false
+  }
 }
 ```
 
@@ -64,7 +64,7 @@ Use the basic subtitle websocket when you only need the current subtitle line as
 - **Client auth:** none
 - **Reconnects:** client-managed
 
-When a client connects, SubMiner immediately sends the latest subtitle payload if one is available. After that, it pushes a new message each time the current subtitle changes.
+When a client connects, SubMiner immediately sends the latest subtitle payload if one is available. After that, it pushes a new message each time the current subtitle changes. Annotation-only upgrades do not repeat the same line on this basic stream.
 
 #### Message shape
 
@@ -79,12 +79,12 @@ When a client connects, SubMiner immediately sends the latest subtitle payload i
 
 #### Field reference
 
-| Field      | Type   | Notes                                                                                          |
-| ---------- | ------ | ---------------------------------------------------------------------------------------------- |
-| `version`  | number | Current websocket payload version. Today this is `1`.                                          |
-| `text`     | string | Raw subtitle text.                                                                             |
+| Field | Type | Notes |
+| --- | --- | --- |
+| `version` | number | Current websocket payload version. Today this is `1`. |
+| `text` | string | Raw subtitle text. |
 | `sentence` | string | Plain subtitle text with line breaks represented as `<br>`. No annotation spans or attributes. |
-| `tokens`   | array  | Always empty on the basic subtitle websocket.                                                  |
+| `tokens` | array | Always empty on the basic subtitle websocket. |
 
 ### 2. Annotation WebSocket
 
@@ -96,6 +96,8 @@ Use the annotation websocket for custom clients that want the same structured to
 
 In practice, if you are building a new client, prefer `annotationWebsocket` unless you specifically need compatibility with an existing `websocket` consumer.
 
+On a tokenization cache miss, this stream first sends the cue as plain text with an empty `tokens` array, then sends the annotated replacement when tokenization finishes. Treat each message as the complete current state, replacing the previous payload.
+
 #### Message shape
 
 ```json
@@ -127,22 +129,22 @@ In practice, if you are building a new client, prefer `annotationWebsocket` unle
 
 Each annotation token may include:
 
-| Token field           | Type             | Notes                                            |
-| --------------------- | ---------------- | ------------------------------------------------ |
-| `surface`             | string           | Display text for the token                       |
-| `reading`             | string           | Kana reading when available                      |
-| `headword`            | string           | Dictionary headword when available               |
-| `startPos` / `endPos` | number           | Character offsets in the subtitle text           |
-| `partOfSpeech`        | string           | SubMiner token POS label                         |
-| `isMerged`            | boolean          | Whether this token represents merged content     |
-| `isKnown`             | boolean          | Marked known by SubMiner's known-word logic      |
-| `isNPlusOneTarget`    | boolean          | True when the token is the sentence's N+1 target |
-| `isNameMatch`         | boolean          | True for prioritized character-name matches      |
-| `frequencyRank`       | number           | Frequency rank when available                    |
-| `jlptLevel`           | string           | JLPT level when available                        |
-| `className`           | string           | CSS-ready class list derived from token state    |
-| `frequencyRankLabel`  | string or `null` | Preformatted rank label for UIs                  |
-| `jlptLevelLabel`      | string or `null` | Preformatted JLPT label for UIs                  |
+| Token field | Type | Notes |
+| --- | --- | --- |
+| `surface` | string | Display text for the token |
+| `reading` | string | Kana reading when available |
+| `headword` | string | Dictionary headword when available |
+| `startPos` / `endPos` | number | Character offsets in the subtitle text |
+| `partOfSpeech` | string | SubMiner token POS label |
+| `isMerged` | boolean | Whether this token represents merged content |
+| `isKnown` | boolean | Marked known by SubMiner's known-word logic |
+| `isNPlusOneTarget` | boolean | True when the token is the sentence's N+1 target |
+| `isNameMatch` | boolean | True for prioritized character-name matches |
+| `frequencyRank` | number | Frequency rank when available |
+| `jlptLevel` | string | JLPT level when available |
+| `className` | string | CSS-ready class list derived from token state |
+| `frequencyRankLabel` | string or `null` | Preformatted rank label for UIs |
+| `jlptLevelLabel` | string or `null` | Preformatted JLPT label for UIs |
 
 ### 3. HTML markup conventions
 

docs-site/youtube-integration.md

@@ -11,7 +11,7 @@ SubMiner auto-loads Japanese subtitles when you play a YouTube URL, giving you t
 
 When SubMiner detects a YouTube URL (or `ytsearch:` target), it pauses mpv at startup and runs a subtitle pipeline before resuming playback:
 
-1. **Probe** --- `yt-dlp --dump-single-json` extracts all available subtitle tracks (manual uploads and auto-generated captions) along with video metadata.
+1. **Probe** --- `yt-dlp --dump-single-json` extracts all available subtitle tracks (manual uploads and auto-generated captions) along with video metadata. Every yt-dlp call passes `--no-playlist`, so playlist links (for example a Watch Later URL with `list=`/`index=`) resolve to the single video instead of the whole playlist.
 2. **Discover** --- Each track is normalized into a `YoutubeTrackOption` with language code, kind (`manual` or `auto`), display label, and direct download URL.
 3. **Select** --- SubMiner picks the best primary track (Japanese, preferring manual over auto) and secondary track (English, preferring manual over auto).
 4. **Download** --- Selected tracks are fetched via direct URL when available, falling back to `yt-dlp --write-subs` / `--write-auto-subs`. YouTube TimedText XML formats (`srv1`/`srv2`/`srv3`) are converted to VTT on the fly. Auto-generated VTT captions are normalized to remove rolling-caption duplication.
@@ -110,8 +110,8 @@ Background cache downloads are capped at 720p by default (`youtube.mediaCache.ma
 }
 ```
 
-| Option                | Type       | Description                                                                                                                                                                              |
-| --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Option                | Type       | Description                                                                           |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------- |
 | `primarySubLanguages` | `string[]` | Languages that count as a satisfactory primary subtitle (default `["ja", "jpn"]`). Used by the "primary subtitle missing" notification and by managed local/playlist subtitle selection. |
 
 YouTube auto-selection itself always picks a Japanese track first (manual over auto), then falls back to any manual track — `primarySubLanguages` does not change which YouTube track is auto-picked.
@@ -130,11 +130,11 @@ YouTube secondary selection is fixed: SubMiner always tries an English track (ma
 }
 ```
 
-| Option                  | Type                                 | Description                                                                                                                                                             |
-| ----------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Option                  | Type                                 | Description                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `secondarySubLanguages` | `string[]`                           | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track for local/Jellyfin sidecar files. Default is empty (`[]`). Not used for YouTube. |
 | `autoLoadSecondarySub`  | `boolean`                            | Auto-detect and load a matching secondary sidecar track for local files (default: `false`). Not used for YouTube.                                                       |
-| `defaultMode`           | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`)                                                                                                       |
+| `defaultMode`           | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`)                                                                                                                                   |
 
 These settings come from `config.jsonc` (or built-in defaults); there are no CLI flags or environment variables for subtitle language selection.
 

docs/RELEASING.md

@@ -58,12 +58,15 @@
    `latest*.yml` and `*.blockmap` files under `release/`.
 5. Commit the prerelease prep (package.json version bump + the generated
    `release/prerelease-notes.md`). CI does not regenerate notes — it uses the
-   committed file — so review it before committing. If you add more
-   `changes/*.md` fragments for a later beta/RC, rerun
-   `bun run changelog:prerelease-notes --version <version>`; the generator uses
-   the existing prerelease notes as the baseline only when their hidden
-   `prerelease-base-version` marker matches the current base version, and asks
-   Claude to merge only the new fragment material. Do not run
+   committed file — so review it before committing. Rerun
+   `bun run changelog:prerelease-notes --version <version>` for every later
+   beta/RC, even if no fragments changed: the notes carry a hidden
+   `prerelease-version` marker and CI rejects the tag when the marker does not
+   match it (verify locally with
+   `bun run changelog:check-prerelease-notes --version <version>`). The
+   generator reuses the existing notes as the cumulative baseline when their
+   marker (or legacy `prerelease-base-version` marker) matches the current base
+   version, and asks Claude to merge only the new fragment material. Do not run
    `bun run changelog:build`.
 6. Tag the commit: `git tag v<version>`.
 7. Push commit + tag.
@@ -78,6 +81,8 @@ Notes:
 - Pass `--date` explicitly when you want the release stamped with the local cut date; otherwise the generator uses the current ISO date, which can roll over to the next UTC day late at night.
 - `changelog:check` now rejects tag/package version mismatches.
 - `changelog:prerelease-notes` also rejects tag/package version mismatches and writes `release/prerelease-notes.md` without mutating tracked changelog files. When that file already exists, the generator includes it in the Claude prompt so later beta/RC notes reuse the reviewed text instead of starting over.
+- From the second prerelease of a base version onward, the notes open with a `## Changes since <previous tag>` section above the cumulative `## Highlights`. The generator locates the newest preceding beta/RC tag for the same base version (semver order: all betas before all RCs), diffs `changes/*.md` between that tag and the working tree, and asks Claude to describe only the behavioral beta-to-beta differences — added fragments as new changes, modified fragments by their before/after difference (editorial-only edits are dropped), deleted fragments as removed/reverted changes. If no fragments changed (for example a packaging-only rebuild), the section states that explicitly without a Claude call. The delta section carries no separate contributor attribution; `## What's Changed` stays cumulative like `## Highlights`.
+- `changelog:check-prerelease-notes --version <version>` verifies the committed notes' `prerelease-version` marker matches the version being tagged; the prerelease workflow runs it and fails the release on stale notes.
 - `changelog:build` generates `CHANGELOG.md` + `release/release-notes.md` (both polished by `claude -p`) and removes the released `changes/*.md` fragments. The CHANGELOG keeps internal notes inside a `<details><summary>Internal changes</summary>` collapse; the release notes drop them entirely.
 - `release/release-notes.md` (and `release/prerelease-notes.md`) include GitHub-style attribution after `## Highlights`: a `## What's Changed` list crediting each released fragment as `by @<author> in #<pr>`, plus a `## New Contributors` section for first-time authors. Attribution is resolved per fragment via `git log` (the commit that added the fragment) + `gh api .../commits/<sha>/pulls`, with one `gh` search per author for the first-contribution check. It needs `gh` installed and authenticated; if `gh` is unavailable or a lookup fails, the generator warns and emits notes without the attribution sections rather than failing. The CHANGELOG itself stays attribution-free.
 - The release workflow no longer auto-runs `changelog:build`. If pending `changes/*.md` fragments are present on a tag-based run, CI exits with a clear `::error::` pointing at the local fix. Run `bun run changelog:build --version <version>` locally, commit the polished output, then tag.

docs/architecture/2026-03-15-renderer-performance-design.md

@@ -69,15 +69,27 @@ A cue parser extracts both timing and text content from subtitle files for prefe
 interface SubtitleCue {
   startTime: number; // seconds
   endTime: number; // seconds
-  text: string; // raw subtitle text
+  text: string; // plain text, decoded from the source format
+  source?: 'canonical-ass'; // recovered authored text for generated ASS animation
+  animationStartTime?: number; // full generated-frame envelope; entrance/exit frames
+  animationEndTime?: number; //   run past the authored timing, live matching uses this
 }
 ```
 
 **Supported formats:**
 
 - SRT/VTT: Regex-based parsing of timing lines + text content between timing blocks.
-- ASS: Parse `[Events]` section, extract `Dialogue:` lines, split on the first 9 commas only (ASS v4+ has 10 fields; the last field is Text which can itself contain commas). Strip ASS override tags (`{\...}`) from the text before storing.
-  ASS text fields contain inline override tags like `{\b1}`, `{\an8}`, `{\fad(200,300)}`. The cue parser strips these during extraction so the tokenizer receives clean text.
+- ASS: Parse the `[Events]` section, read the field order from the `Format:` row, and extract timed `Dialogue:` lines. Timed `Comment:` lines are normally ignored, but can supply canonical authored text when they match a nearby generated animation from the same style and actor. Text can itself contain commas.
+
+**ASS decoding.** The parser is where ASS text is decoded, once, via `assToPlainText()` in `src/core/services/ass-text.ts`. That decoder mirrors mpv's `ass_to_plaintext` so a cue read from a file reads identically to the same line arriving live on `sub-text`: `{...}` override blocks are markup, `\pN … \p0` vector drawing runs are dropped rather than shown as text, `\N`/`\n`/`\h` are the only escapes (`\{`, `\}` and `\\` are not), and an unclosed `{` is rendered verbatim. Every layer downstream — renderer, timing tracker, tokenizer, tokenization cache keys — receives plain text and uses `normalizePlainSubtitleText()` for whitespace only, so nothing decodes the same string twice and one authored line always maps to one cache key.
+
+**Duplicate collapsing.** Typeset scripts emit one `Dialogue:` event per animation frame, plus layered copies of the same line. The parser collapses identical text over an identical span unconditionally, and collapses contiguous same-text runs of at least three events when the run looks like an animation. For ASS that means shared style and actor plus authoring evidence: a temporal tag (`\t`, `\move`, `\k`/`\kf`/`\ko`/`\K`, or anything wrapped in `\t(...)`), an animated `Effect` column (`Karaoke`, `Banner`, `Scroll`), or override values that change across the run. Static tags shared by every event (`\pos`, an identical `\clip`) are not evidence. SRT/VTT carry no such metadata, so there collapsing needs at least five contiguous events all under 0.1s — the frame timing left behind by ASS-to-SRT conversion. The parser keeps this authoring metadata (style, actor, layer, `Effect`, parsed override commands, source order) private; `parseSubtitleCues()` returns only `SubtitleCue`.
+
+ASS scripts can also redraw one complete lyric for two or more long color/highlight phases. Those flush-timed phases collapse separately from short animation frames when they share text, style, actor, and layer and carry direct animation evidence, such as temporal tags or changing non-spatial overrides. Spatial command changes do not prove a phase, so separately positioned signs remain distinct.
+
+**Canonical animation recovery.** Some ASS producers keep the readable lyric or sign as a timed `Comment:` and generate hundreds of `Dialogue:` frames containing repeated glyphs or changing clip regions. Others retain the complete line as brief `Dialogue:` events around the generated fragments. A complete event is promoted only when nearby dialogue from the same style and actor forms a proven animation cluster and reconstructs its entire text in source order. The generated frames are then replaced by one cue marked `source: 'canonical-ass'`. This source marker lets the live primary-subtitle path prefer the clean authored text and timing for display, sidebar history, immersion recording, and mining, while unmatched editor notes and alternative translations remain ignored. Secondary selection advances to an entering canonical cue at its generated animation start when the preceding authored cue ends before the new authored span. Unrelated simultaneous cues that continue through the new span remain visible.
+
+**Font texture cleanup.** A clipped repeated-glyph run or frequent changes to secondary alpha marks a texture seed. Clipped runs do not need a font override because some signs build their masks from ordinary `l` glyphs. The parser removes short clipped pieces that share a no-font seed's style and timing, or pieces that share a font seed's style, timing, and font even when the actor changes. It also removes positioned text layers with at least `E0` global alpha when they overlap a seed in the same style. Opaque authored sign text stays publishable when the texture switches fonts or actors around it.
 
 #### Prefetch Service Lifecycle
 

docs/architecture/domains.md

@@ -25,6 +25,8 @@ Read when: you need to find the owner module for a behavior or test surface
 - Anki workflow: `src/anki-integration/`, `src/core/services/anki-jimaku*.ts`
 - Immersion tracking: `src/core/services/immersion-tracker/`
   Includes stats storage/query schema such as `imm_videos`, `imm_media_art`, and `imm_youtube_videos` for per-video and YouTube-specific library metadata.
+  Library-entry identity aliases and merge recommendations are persisted alongside this schema; the stats HTTP and SPA layers only expose and present those domain decisions.
+  `delete-maintenance-scheduler.ts` coalesces and serializes stats deletes; the expensive work runs in `delete-maintenance-worker-thread.ts` while the tracker queues playback writes. Each batch uses one transaction, lexical update, rollup refresh, and incremental lifetime subtraction (`planLifetimeRemovals`/`applyLifetimeRemovals` in `lifetime.ts`). Merges, moves, AniList reassignments, and `stats cleanup -l` use `repairLifetimeSummariesFromMedia` (recompute from the per-video media ledger). The full lifetime rebuild survives only as the empty-table bootstrap; anywhere else it would collapse lifetime totals to the session retention window.
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
 - Window trackers: `src/window-trackers/`

docs/architecture/stats-trends-data-flow.md

@@ -23,7 +23,9 @@ Trend charts now consume one chart-oriented backend payload from `/api/stats/tre
   - lookup rate trends
   - watch-time by day-of-week/hour
 - vocabulary-backed:
-  - new-words trend
+  - new-words trend reads permanent daily lexical rollups
+  - rollup rows count only vocabulary-visible tokens and normalize mixed legacy timestamp units
+  - a persisted rollup version invalidates stale materializations and triggers an atomic background rebuild
 
 ## Metric Semantics
 

docs/architecture/subtitle-overlay-priming.md

@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming
 
 Status: active
-Last verified: 2026-06-14
+Last verified: 2026-08-19
 Owner: Kyle Yasuda
 Read when: debugging subtitle state or blank Linux/X11 overlay windows when the visible overlay is shown or recreated
 
@@ -47,20 +47,116 @@ subtitles do not draw.
    `emitSubtitle(payload)` and `refreshCurrentSubtitle(text)`, then prime secondary subtitles.
 6. Tokenization cache hit: call `consumeCachedSubtitle(text)`, `onSubtitleChange(text)`, and
    `emitSubtitle(cachedPayload)`, then prime secondary subtitles.
-7. Cache miss: call `refreshCurrentSubtitle(text)` and let normal tokenization emit the final
-   payload.
+7. Cache miss: call `refreshCurrentSubtitle(text)`. Normal processing emits a plain payload
+   synchronously, then replaces it with the tokenized payload when ready.
 
-In `src/main.ts`, both `onSubtitleChange` and `refreshCurrentSubtitle` pause
-`subtitlePrefetchService`, notify it with `onSeek(lastObservedTimePos)`, and then call the matching
-`subtitleProcessingController` method. This gives the visible overlay priority over background
-prefetch work and re-centers prefetch around the live playback time.
+Both `onSubtitleChange` and `refreshCurrentSubtitle` pause `subtitlePrefetchService` and then call
+the matching `subtitleProcessingController` method, giving the visible overlay priority over
+background prefetch work. Prefetch is not re-centered here: restarting the run per line
+(`onSeek`) discarded the in-flight tokenization every time the subtitle changed, so only real
+seeks restart it (see `onTimePosUpdate` in `src/main.ts`).
+
+On an uncached autoplay prime the raw payload is emitted here and reported to the controller with
+`notePlainSubtitleEmitted`, so the controller skips its own plain emit for that line and the
+overlay receives one plain payload followed by the annotated one.
+
+The pause is released by the controller's `onProcessingSettled` callback, which fires once it has
+no work left. Emits do not release it: the first emit for an uncached line is the plain payload
+that precedes tokenization, and a run can finish without emitting at all (a suppressed duplicate,
+a failed tokenization). Both controller methods return whether processing is now pending, and the
+caller resumes immediately when it is not — a repeated subtitle schedules no work, so no settle is
+coming and prefetching would otherwise idle for the rest of the cue.
+
+## Live Cue Delivery
+
+- Primary live text first resolves recovered canonical ASS animations. Otherwise, when
+  every live mpv line matches an active parsed cue, it uses the parsed cue text so exact
+  full-span style layers appear once instead of repeating for fill, border, blur, shadow,
+  or equivalent whitespace variants. Any unmatched live line keeps the complete live
+  stack, preserving dialogue or signs that overlap a lyric.
+- A tokenization cache miss emits the plain cue synchronously. Tokenization remains serialized so
+  live work does not contend for Yomitan state.
+- The initial `time-pos`, explicit renderer seeks, and later seek-like jumps reprocess mpv's
+  current raw `sub-text` after the new playback time is stored. Explicit intent matters because
+  adjacent subtitle jumps can be shorter than the general seek-distance threshold. This corrects
+  ASS cleanup when mpv delivered the destination subtitle before the destination timestamp.
+- Renderer `sub-seek` commands use the active parsed cue list when available. Simultaneous cues
+  share one boundary, overlapping lyrics advance from the latest active boundary, and mpv's native
+  command remains the fallback when no parsed destination exists. This prevents generated karaoke
+  frames from consuming next/previous subtitle presses.
+- Subtitle sidebar selections seek past the preceding sanitized cue's overlapping exit span when
+  the selected cue has enough time remaining. This keeps direct row selection on the requested
+  karaoke line while clamping the seek inside that cue.
+- If startup paints raw text before embedded ASS parsing finishes, parsed cue arrival may replace
+  that provisional line. The one-prime-per-media guard still suppresses identical repeats.
+- If a newer cue arrives while an older line is still tokenizing, the newer plain cue or empty
+  clear payload is emitted immediately. The older tokenization result is dropped before it can
+  replace the current cue.
+- The current cue upgrades in place when its tokens and annotations are ready. This can reflow text
+  or character images, but cue visibility does not wait for that work.
+
+## Secondary Subtitle Flow
+
+- `secondary-sub-text` remains the immediate fallback, so unreadable subtitle sources, remote URLs,
+  and still-extracting embedded tracks appear without waiting for file resolution. Embedded-track
+  extraction runs for local and network-mounted files alike (demuxing reads the whole container,
+  about 10 seconds per GB on gigabit, under a generous timeout); only true remote URLs skip it,
+  having no on-disk container to demux.
+- The live fallback also suppresses per-glyph typesetting walls: when many simultaneous
+  one-glyph lines are present (generated karaoke lettering flattened into live text), those
+  lines and their short syllable companions are dropped while concurrent dialogue lines stay.
+  This keeps the overlay clean while extraction is still in flight and for sources that never
+  produce parsed cues.
+- Parsed secondary text and the live fallback remove exact repeated lines at any length. A
+  flattened-line identity also removes long dialogue/sign repetitions that differ only in
+  whitespace or terminal punctuation, while distinct simultaneous short lines remain separate.
+- `secondary-subtitle-track.ts` resolves `secondary-sid` against mpv's track list. External tracks
+  are read directly; supported embedded text tracks are extracted through the same ffmpeg-backed
+  source resolver used by primary subtitle prefetching.
+- The selected source is parsed with `parseSubtitleCues()`, including metadata-aware ASS duplicate
+  and animation collapse. Playback `time-pos` selects the active parsed cue after applying
+  `secondary-sub-delay`.
+- Fragment reconstruction marks tall multi-row positioned parts as a grid only when they read
+  like tiling: a couple of texts repeated across many fragments, the same text re-shown at one
+  spot over time (countdown/animation frames), or scattered single glyphs. Secondary text omits
+  those grids instead of flattening a translated table or schedule into one synthetic line.
+  Wrapped lyric rows, CC-style dialogue blocks, and reconstructed single-line karaoke remain
+  eligible for display.
+- The resolved text is stored in `mpvClient.currentSecondarySubText` before it is broadcast. The
+  overlay, mining, timing tracker, and immersion statistics therefore consume the same secondary
+  text when a readable source is available.
+- Simultaneous parsed cues use whitespace-insensitive identity, so ASS layers that vary only
+  between ordinary, hard, or ideographic spaces appear once.
+- Simultaneous ASS lines are flattened in top-to-bottom positioned order, falling back to their
+  authored source order when no usable position exists.
+- Half-size kana positioned directly above a same-timed kanji caption is treated as ASS
+  furigana. The parser omits it from published cues but retains hidden matching metadata so
+  mpv's raw live text can be reconciled without displaying or mining the reading.
+- Fragment-only ASS karaoke is reconstructed per style before publication. Explicit spaces
+  survive concatenation. Latin fragment typesetting with no literal spaces also recovers word
+  boundaries represented only by materially larger horizontal `\pos` or `\move` gaps within that
+  line. Unpositioned fragments stay compact instead of gaining guessed spaces between syllables.
+  Short runs qualify only when overlapping positioned events also show changing overrides or
+  repeated layer copies; an English or romaji style name alone never turns ordinary dialogue into
+  a lyric.
+- Recovered canonical ASS text remains active for the generated animation envelope. For
+  reconstructed lyric styles, the longest-lived active line wins over brief entrance and exit
+  fragments from the same style.
+- Media and `secondary-sid` changes clear the previous parsed state before refreshing the source;
+  track-list changes refresh without discarding an unchanged source. Observed
+  `secondary-sub-delay` changes retime the active parsed cue without rereading the file. If loading,
+  extraction, or parsing fails, the controller returns to live mpv text and the renderer's
+  conservative short stack heuristic remains the final display fallback.
 
 ## Emitted State
 
-- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`, which sends the normal
-  annotated subtitle payload to overlay windows and subtitle websocket listeners.
-- Secondary priming reads mpv `secondary-sub-text`, stores it in
-  `mpvClient.currentSecondarySubText`, and broadcasts `secondary-subtitle:set` to overlay windows.
+- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`. Overlay windows and annotation
+  websocket listeners receive both the immediate plain cue and its later annotation upgrade.
+- The basic subtitle websocket receives the immediate plain cue only. Because its serialized
+  payload discards annotations, the later upgrade would be an identical duplicate and is skipped
+  when text and cue timing match.
+- Secondary priming reads mpv `secondary-sub-text` and routes it through the secondary track
+  controller. A parsed active cue replaces the live text when the selected source is readable.
 - If secondary `requestProperty` fails, the primary flow stays complete and only a debug line is
   written.
 
@@ -104,7 +200,11 @@ prefetch work and re-centers prefetch around the live playback time.
   path, empty or stale bounding shapes produced invisible or clipped subtitles even though the
   overlay window remained mapped above mpv.
 - Pointer pass-through should continue to use `setIgnoreMouseEvents(true, { forward: true })` and
-  the Linux cursor-poll fallback, not bounding-shape clipping.
+  the Linux cursor-poll fallback, not bounding-shape clipping. Note that on Windows click-through
+  must go through `applyOverlayClickThrough()` (`src/core/services/overlay-click-through.ts`),
+  which omits `forward: true` there: Electron implements forwarding with a global low-level mouse
+  hook that lags mouse input system-wide whenever the main thread stalls; the Windows cursor poll
+  handles overlay wake-up instead.
 - Visible-overlay show/reset marks Linux pointer passthrough state dirty even when the logical
   interaction state is already inactive. The next cursor-poll tick must still reapply
   `setIgnoreMouseEvents(true, { forward: true })`; otherwise a newly shown Electron overlay can keep

docs/knowledge-base/catalog.md

@@ -3,25 +3,25 @@
 # Documentation Catalog
 
 Status: active  
-Last verified: 2026-05-23  
+Last verified: 2026-08-13
 Owner: Kyle Yasuda  
 Read when: finding internal docs or checking verification status
 
-| Area                     | Path                                            | Status | Last verified | Notes                                      |
-| ------------------------ | ----------------------------------------------- | ------ | ------------- | ------------------------------------------ |
-| KB home                  | `docs/README.md`                                | active | 2026-05-23    | internal entrypoint                        |
-| Architecture index       | `docs/architecture/README.md`                   | active | 2026-05-23    | top-level runtime map                      |
-| Domain ownership         | `docs/architecture/domains.md`                  | active | 2026-05-23    | runtime and feature ownership              |
-| Layering rules           | `docs/architecture/layering.md`                 | active | 2026-05-23    | dependency direction and smells            |
-| Subtitle overlay priming | `docs/architecture/subtitle-overlay-priming.md` | active | 2026-06-01    | visible-overlay subtitle startup flow      |
-| KB rules                 | `docs/knowledge-base/README.md`                 | active | 2026-05-23    | maintenance policy                         |
-| Core beliefs             | `docs/knowledge-base/core-beliefs.md`           | active | 2026-03-13    | agent-first principles                     |
-| Quality scorecard        | `docs/knowledge-base/quality.md`                | active | 2026-03-13    | quality grades and gaps                    |
-| Workflow index           | `docs/workflow/README.md`                       | active | 2026-05-23    | execution map                              |
-| Planning guide           | `docs/workflow/planning.md`                     | active | 2026-05-23    | lightweight vs execution plans             |
-| Agent plugins            | `docs/workflow/agent-plugins.md`                | active | 2026-05-23    | repo-local agent workflow plugin ownership |
-| Verification guide       | `docs/workflow/verification.md`                 | active | 2026-05-23    | maintained verification lanes              |
-| Release guide            | `docs/RELEASING.md`                             | active | 2026-05-23    | release checklist                          |
+| Area | Path | Status | Last verified | Notes |
+| --- | --- | --- | --- | --- |
+| KB home | `docs/README.md` | active | 2026-05-23 | internal entrypoint |
+| Architecture index | `docs/architecture/README.md` | active | 2026-05-23 | top-level runtime map |
+| Domain ownership | `docs/architecture/domains.md` | active | 2026-05-23 | runtime and feature ownership |
+| Layering rules | `docs/architecture/layering.md` | active | 2026-05-23 | dependency direction and smells |
+| Subtitle overlay priming | `docs/architecture/subtitle-overlay-priming.md` | active | 2026-06-01 | visible-overlay subtitle startup flow |
+| KB rules | `docs/knowledge-base/README.md` | active | 2026-05-23 | maintenance policy |
+| Core beliefs | `docs/knowledge-base/core-beliefs.md` | active | 2026-03-13 | agent-first principles |
+| Quality scorecard | `docs/knowledge-base/quality.md` | active | 2026-03-13 | quality grades and gaps |
+| Workflow index | `docs/workflow/README.md` | active | 2026-08-13 | execution map |
+| 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 |
+| Release guide | `docs/RELEASING.md` | active | 2026-05-23 | release checklist |
 
 ## Update Rules
 

docs/knowledge-base/quality.md

@@ -11,27 +11,27 @@ Grades are directional, not ceremonial. The point is to keep gaps visible.
 
 ## Product / Runtime Domains
 
-| Area                                    | Grade | Notes                                                                    |
-| --------------------------------------- | ----- | ------------------------------------------------------------------------ |
-| Desktop runtime composition             | B     | strong modularization; still easy for `main` wiring drift to reappear    |
-| Launcher CLI                            | B     | focused surface; generated/stale artifact hazards need constant guarding |
-| mpv plugin                              | B     | modular, but Lua/runtime coupling still specialized                      |
-| Overlay renderer                        | B     | improved modularity; interaction complexity remains                      |
-| Config system                           | A-    | clear defaults/definitions split and good validation surface             |
-| Immersion / AniList / Jellyfin surfaces | B-    | growing product scope; ownership spans multiple services                 |
-| Internal docs system                    | B     | new structure in place; needs habitual maintenance                       |
-| Public docs site                        | B     | strong user docs; must stay separate from internal KB                    |
+| Area | Grade | Notes |
+| --- | --- | --- |
+| Desktop runtime composition | B | strong modularization; still easy for `main` wiring drift to reappear |
+| Launcher CLI | B | focused surface; generated/stale artifact hazards need constant guarding |
+| mpv plugin | B | modular, but Lua/runtime coupling still specialized |
+| Overlay renderer | B | improved modularity; interaction complexity remains |
+| Config system | A- | clear defaults/definitions split and good validation surface |
+| Immersion / AniList / Jellyfin surfaces | B- | growing product scope; ownership spans multiple services |
+| Internal docs system | B | new structure in place; needs habitual maintenance |
+| Public docs site | B | strong user docs; must stay separate from internal KB |
 
 ## Architectural Layers
 
-| Layer                          | Grade | Notes                                                     |
-| ------------------------------ | ----- | --------------------------------------------------------- |
-| `src/main.ts` composition root | B     | direction good; still needs vigilance against logic creep |
-| `src/main/` runtime adapters   | B     | mostly clear; can accumulate wiring debt                  |
-| `src/core/services/`           | B+    | good extraction pattern; some domains remain broad        |
-| `src/renderer/`                | B     | cleaner than before; UI/runtime behavior still dense      |
-| `launcher/`                    | B     | clear command boundaries                                  |
-| `docs/` internal KB            | B     | structure exists; enforcement now guards core rules       |
+| Layer | Grade | Notes |
+| --- | --- | --- |
+| `src/main.ts` composition root | B | direction good; still needs vigilance against logic creep |
+| `src/main/` runtime adapters | B | mostly clear; can accumulate wiring debt |
+| `src/core/services/` | B+ | good extraction pattern; some domains remain broad |
+| `src/renderer/` | B | cleaner than before; UI/runtime behavior still dense |
+| `launcher/` | B | clear command boundaries |
+| `docs/` internal KB | B | structure exists; enforcement now guards core rules |
 
 ## Current Gaps
 

docs/superpowers/specs/2026-04-09-library-summary-replaces-per-day-design.md

@@ -1,184 +0,0 @@
-# Library Summary Replaces Per-Day Trends — Design
-
-**Status:** Draft
-**Date:** 2026-04-09
-**Scope:** `stats/` frontend, `src/core/services/immersion-tracker/query-trends.ts` backend
-
-## Problem
-
-The "Library — Per Day" section on the stats Trends tab (`stats/src/components/trends/TrendsTab.tsx:224-254`) renders six stacked-area charts — Videos, Watch Time, Cards, Words, Lookups, and Lookups/100w, each broken down per title per day.
-
-In practice these charts are not useful:
-
-- Most titles only have activity on one or two days in a window, so they render as isolated bumps on a noisy baseline.
-- Stacking 7+ titles with mostly-zero days makes individual lines hard to follow.
-- The top "Activity" and "Period Trends" sections already answer "what am I doing per day" globally.
-- The "Library — Cumulative" section directly below already answers "which titles am I progressing through" with less noise.
-
-The per-day section occupies significant vertical space without carrying its weight, and the user has confirmed it should be replaced.
-
-## Goal
-
-Replace the six per-day stacked charts with a single "Library — Summary" section that surfaces per-title aggregate statistics over the selected date range. The new view should make it trivially easy to answer: "For the selected window, which titles am I spending time on, how much mining output have they produced, and how efficient is my lookup rate on each?"
-
-## Non-goals
-
-- Changing the "Library — Cumulative" section (stays as-is).
-- Changing the "Activity", "Period Trends", or "Patterns" sections.
-- Adding a new API endpoint — the existing dashboard endpoint is extended in place.
-- Renaming internal `anime*` data-model identifiers (`animeId`, `imm_anime`, etc.). Those stay per the convention established in `c5e778d7`; only new fields/types/user-visible strings use generic "title"/"library" wording.
-- Supporting a true all-time library view on the Trends tab. If that's ever wanted, it belongs on a different tab.
-
-## Solution Overview
-
-Delete the "Library — Per Day" section. In its place, add "Library — Summary", composed of:
-
-1. A horizontal-bar leaderboard chart of watch time per title (top 10, descending).
-2. A sortable table of every title with activity in the selected window, with columns: Title, Watch Time, Videos, Sessions, Cards, Words, Lookups, Lookups/100w, Date Range.
-
-Both controls are scoped to the top-of-page date range selector. The existing shared Anime Visibility filter continues to work — it now gates Summary + Cumulative instead of Per-Day + Cumulative.
-
-## Backend
-
-### New type
-
-Add to `stats/src/types/stats.ts` and the backend query module:
-
-```ts
-type LibrarySummaryRow = {
-  title: string; // display title — anime series, YouTube video title, etc.
-  watchTimeMin: number; // sum(total_active_min) across the window
-  videos: number; // distinct video_id count
-  sessions: number; // session count from imm_sessions
-  cards: number; // sum(total_cards)
-  words: number; // sum(total_tokens_seen)
-  lookups: number; // sum(lookup_count) from imm_sessions
-  lookupsPerHundred: number | null; // lookups / words * 100, null when words == 0
-  firstWatched: number; // min(rollup_day) as epoch day, within the window
-  lastWatched: number; // max(rollup_day) as epoch day, within the window
-};
-```
-
-### Query changes in `src/core/services/immersion-tracker/query-trends.ts`
-
-- Add `librarySummary: LibrarySummaryRow[]` to `TrendsDashboardQueryResult`.
-- Populate it from a single aggregating query over `imm_daily_rollups` joined to `imm_videos` → `imm_anime`, filtered by `rollup_day` within the selected window. Session count and lookup count come from `imm_sessions` aggregated by `video_id` and then grouped by the parent library entry. Use a single query (or at most two joined/unioned) — no N+1.
-- `imm_anime` is the generic library-grouping table; anime series, YouTube videos, and yt-dlp imports all land there. The internal table name stays `imm_anime`; only the new field uses generic naming.
-- Return rows pre-sorted by `watchTimeMin` descending so the leaderboard is zero-cost and the table default sort matches.
-- Emit `lookupsPerHundred: null` when `words == 0`.
-
-### Removed from API response
-
-Drop the entire `animePerDay` field from `TrendsDashboardQueryResult` (both backend in `src/core/services/immersion-tracker/query-trends.ts` and frontend in `stats/src/types/stats.ts`).
-
-Internally, the existing helpers (`buildPerAnimeFromDailyRollups`, `buildEpisodesPerAnimeFromDailyRollups`) are still used as intermediates to build `animeCumulative.*` via `buildCumulativePerAnime`. Keep those helpers — just scope their output to local variables inside `getTrendsDashboard` instead of exposing them on the response. The `buildPerAnimeFromSessions` call for lookups and the `buildLookupsPerHundredPerAnime` helper become unused and can be deleted.
-
-Before removing `animePerDay` from the frontend type, verify no other file under `stats/src/` references it. Based on current inspection, only `TrendsTab.tsx` and `stats/src/types/stats.ts` touch it.
-
-## Frontend
-
-### New component: `stats/src/components/trends/LibrarySummarySection.tsx`
-
-Owns the header, leaderboard chart, visibility-filtered data, and the table. Keeps `TrendsTab.tsx` from growing. Component props: `{ rows: LibrarySummaryRow[]; hiddenTitles: ReadonlySet<string>; windowStart: Date; windowEnd: Date }`.
-
-Internal state: `useState<{ column: ColumnId; direction: 'asc' | 'desc' }>` for sort, defaulting to `{ column: 'watchTimeMin', direction: 'desc' }`.
-
-### Layout
-
-Replaces `TrendsTab.tsx:224-254`:
-
-```
-[SectionHeader: "Library — Summary"]
-[AnimeVisibilityFilter — unchanged, shared with Cumulative below]
-[Card, col-span-full: Leaderboard — horizontal bar chart, ~260px tall]
-[Card, col-span-full: Sortable table, auto height up to ~480px with internal scroll]
-```
-
-Both cards use the existing chart/card wrapper styling.
-
-### Leaderboard chart
-
-- Recharts horizontal bar chart (matches the rest of the page — existing charts use `recharts`, not ECharts).
-- Top 10 titles by watch time. If fewer titles have activity, render what's there.
-- Y-axis: title (category), truncated with ellipsis at container width; full title visible in the Recharts tooltip.
-- X-axis: minutes (number).
-- Use `layout="vertical"` with `YAxis dataKey="title" type="category"` and `XAxis type="number"`.
-- Single series color: `#8aadf4` (matching the existing Watch Time color).
-- Reuse `CHART_DEFAULTS`, `CHART_THEME`, `TOOLTIP_CONTENT_STYLE` from `stats/src/lib/chart-theme.ts` so theming matches the rest of the dashboard.
-- Chart order is fixed at watch-time desc regardless of table sort — the leaderboard's meaning is fixed.
-
-### Table
-
-- Plain HTML `<table>` with Tailwind classes. No new deps.
-- Columns, in order:
-  1. **Title** — left-aligned, sticky, truncated with ellipsis, full title on hover.
-  2. **Watch Time** — formatted `Xh Ym` when ≥60 min, else `Xm`.
-  3. **Videos** — integer.
-  4. **Sessions** — integer.
-  5. **Cards** — integer.
-  6. **Words** — integer.
-  7. **Lookups** — integer.
-  8. **Lookups/100w** — one decimal place, `—` when null.
-  9. **Date Range** — `Mon D → Mon D` using the title's `firstWatched` / `lastWatched` within the window.
-- Click a column header to sort; click again to reverse. Visual arrow on the active column.
-- Numeric columns right-aligned.
-- Null `lookupsPerHundred` sorts as the lowest value in both directions (consistent with "no data").
-- Row hover highlight; no row click action (read-only view).
-- Empty state: "No library activity in the selected window."
-
-### Visibility filter integration
-
-Hiding a title via `AnimeVisibilityFilter` removes it from both the leaderboard and the table. The filter's set of available titles is built from the union of titles that appear in `librarySummary` and the existing `animeCumulative.*` arrays (matches current behavior in `buildAnimeVisibilityOptions`).
-
-### `TrendsTab.tsx` changes
-
-- Remove the `filteredEpisodesPerAnime`, `filteredWatchTimePerAnime`, `filteredCardsPerAnime`, `filteredWordsPerAnime`, `filteredLookupsPerAnime`, `filteredLookupsPerHundredPerAnime` locals.
-- Remove the six `<StackedTrendChart>` calls in the "Library — Per Day" section.
-- Remove the `<SectionHeader>Library — Per Day</SectionHeader>` and the `<AnimeVisibilityFilter>` from that position.
-- Insert `<SectionHeader>Library — Summary</SectionHeader>` + `<AnimeVisibilityFilter>` + `<LibrarySummarySection>` in the same place.
-- Update `buildAnimeVisibilityOptions` input to use `librarySummary` titles instead of the six dropped `animePerDay.*` arrays.
-
-## Data flow
-
-1. `useTrends(range, groupBy)` calls `/api/stats/trends/dashboard`.
-2. Response now includes `librarySummary` (sorted by watch time desc).
-3. `TrendsTab` holds the shared `hiddenAnime` set (unchanged).
-4. `LibrarySummarySection` receives `librarySummary` + `hiddenAnime`, filters out hidden rows, renders the leaderboard from the top-10 slice of the filtered list, renders the table from the filtered list with local sort state applied.
-5. Date-range selector changes trigger a new fetch; `groupBy` toggle does not affect the summary section (it's always window-total).
-
-## Edge cases
-
-- **No activity in window:** Section renders header + empty-state card. Leaderboard card hidden. Visibility filter hidden.
-- **One title only:** Leaderboard renders a single bar; table renders one row. No special-casing.
-- **Title with zero words but non-zero lookups:** `lookupsPerHundred` is `null`, rendered as `—`. Sort treats null as lowest.
-- **Title with zero cards/lookups/words but non-zero watch time:** Normal zero rendering, still shown.
-- **Very long titles:** Ellipsis in chart y-axis labels and table title column; full title in `title` attribute / ECharts tooltip.
-- **Mixed sources (anime + YouTube):** No special case — both land in `imm_anime` and are grouped uniformly.
-
-## Testing
-
-### Backend (`query-trends.ts`)
-
-New unit tests, following the existing pattern:
-
-1. Empty window returns `librarySummary: []`.
-2. Single title with a few rollups: all aggregates are correct; `firstWatched`/`lastWatched` match the bounding days within the window.
-3. Multiple titles: rows returned sorted by watch time desc.
-4. Mixed sources (anime-style + YouTube-style entries in `imm_anime`): both appear in the summary with their own aggregates.
-5. Title with `words == 0`: `lookupsPerHundred` is `null`.
-6. Date range excludes some rollups: excluded rollups are not counted; `firstWatched`/`lastWatched` reflect only within-window activity.
-7. `sessions` and `lookups` come from `imm_sessions`, not `imm_daily_rollups`, and are correctly attributed to the parent library entry.
-
-### Frontend
-
-- Existing Trends tab smoke test should continue to pass after wiring.
-- Optional: a targeted render test for `LibrarySummarySection` (empty state, single title, sort toggle, visibility filter interaction). Not required for merge if the smoke test exercises the happy path.
-
-## Release / docs
-
-- One fragment in `changes/*.md` summarizing the replacement.
-- No user-facing docs (`docs-site/`) changes unless the per-day section was documented there — verify during implementation.
-
-## Open items
-
-None.

docs/superpowers/specs/2026-04-09-stats-dashboard-feedback-pass-design.md

@@ -1,353 +0,0 @@
-# Stats Dashboard Feedback Pass — Design
-
-Date: 2026-04-09
-Scope: Stats dashboard UX follow-ups from user feedback (items 1–7).
-Delivery: **Single PR**, broken into logically scoped commits.
-
-## Goals
-
-Address seven concrete pieces of feedback against the Statistics menu:
-
-1. Library — collapse episodes behind a per-series dropdown.
-2. Sessions — roll up multiple sessions of the same episode within a day.
-3. Trends — add a 365d range option.
-4. Library — delete an episode (video) from its detail view.
-5. Vocabulary — tighten spacing between word and reading in the Top 50 table.
-6. Episode detail — hide cards whose Anki notes have been deleted.
-7. Trend/watch charts — add gridlines, fix tick legibility, unify theming.
-
-Out of scope for this pass: English-token ingestion cleanup and Overview stat-card drill-downs (feedback items 8 and 9). Those require a larger design decision and a migration respectively.
-
-## Files touched (inventory)
-
-Dashboard (`stats/src/`):
-
-- `components/library/LibraryTab.tsx` — collapsible groups (item 1).
-- `components/library/MediaDetailView.tsx`, `components/library/MediaHeader.tsx` — delete-episode action (item 4).
-- `components/sessions/SessionsTab.tsx`, `components/library/MediaSessionList.tsx` — episode rollup (item 2).
-- `components/trends/DateRangeSelector.tsx`, `hooks/useTrends.ts`, `lib/api-client.ts`, `lib/api-client.test.ts` — 365d (item 3).
-- `components/vocabulary/FrequencyRankTable.tsx` — word/reading column collapse (item 5).
-- `components/anime/EpisodeDetail.tsx` — filter deleted Anki cards (item 6).
-- `components/trends/TrendChart.tsx`, `components/trends/StackedTrendChart.tsx`, `components/overview/WatchTimeChart.tsx`, `lib/chart-theme.ts` — chart clarity (item 7).
-- New file: `stats/src/lib/session-grouping.ts` + `session-grouping.test.ts`.
-
-Backend (`src/core/services/`):
-
-- `immersion-tracker/query-trends.ts` — extend `TrendRange` and `TREND_DAY_LIMITS` (item 3).
-- `immersion-tracker/__tests__/query.test.ts` — 365d coverage (item 3).
-- `stats-server.ts` — passthrough if range validation lives here (check before editing).
-- `__tests__/stats-server.test.ts` — 365d coverage (item 3).
-
-## Commit plan
-
-One PR, one feature per commit. Order picks low-risk mechanical changes first so failures in later commits don't block merging of earlier ones.
-
-1. `feat(stats): add 365d range to trends dashboard` (item 3)
-2. `fix(stats): tighten word/reading column in Top 50 table` (item 5)
-3. `fix(stats): hide cards deleted from Anki in episode detail` (item 6)
-4. `feat(stats): delete episode from library detail view` (item 4)
-5. `feat(stats): collapsible series groups in library` (item 1)
-6. `feat(stats): roll up same-episode sessions within a day` (item 2)
-7. `feat(stats): gridlines and unified theme for trend charts` (item 7)
-
-Each commit must pass `bun run typecheck`, `bun run test:fast`, and any change-specific checks listed below.
-
----
-
-## Item 1 — Library collapsible series groups
-
-### Current behavior
-
-`LibraryTab.tsx` groups media via `groupMediaLibraryItems` and always renders the full grid of `MediaCard`s beneath each group header.
-
-### Target behavior
-
-Each group header becomes clickable. Groups with `items.length > 1` default to **collapsed**; single-video groups stay expanded (collapsing them would be visual noise).
-
-### Implementation
-
-- State: `const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(...)`. Initialize from `grouped` where `items.length > 1`.
-- Toggle helper: `toggleGroup(key: string)` adds/removes from the set.
-- Group header: wrap in a `<button>` with `aria-expanded` and a chevron icon (`▶`/`▼`). Keep the existing cover + title + subtitle layout inside the button.
-- Children grid is conditionally rendered on `!collapsedGroups.has(group.key)`.
-- Header summary (`N videos · duration · cards`) stays visible in both states so collapsed groups remain informative.
-
-### Tests
-
-- New `LibraryTab.test.tsx` (if not already present — check first) covering:
-  - Multi-video group renders collapsed on first mount.
-  - Single-video group renders expanded on first mount.
-  - Clicking the header toggles visibility.
-  - Header summary is visible in both states.
-
----
-
-## Item 2 — Sessions episode rollup within a day
-
-### Current behavior
-
-`SessionsTab.tsx:10-24` groups sessions by day label only (`formatSessionDayLabel(startedAtMs)`). Multiple sessions of the same episode on the same day show as independent rows. `MediaSessionList.tsx` has the same problem inside the library detail view.
-
-### Target behavior
-
-Within each day, sessions with the same `videoId` collapse into one parent row showing combined totals. A chevron reveals the individual sessions. Single-session buckets render flat (no pointless nesting).
-
-### Implementation
-
-- New helper in `stats/src/lib/session-grouping.ts`:
-
-  ```ts
-  export interface SessionBucket {
-    key: string; // videoId as string, or `s-${sessionId}` for singletons
-    videoId: number | null;
-    sessions: SessionSummary[];
-    totalActiveMs: number;
-    totalCardsMined: number;
-    representativeSession: SessionSummary; // most recent, for header display
-  }
-  export function groupSessionsByVideo(sessions: SessionSummary[]): SessionBucket[];
-  ```
-
-  Sessions missing a `videoId` become singleton buckets.
-
-- `SessionsTab.tsx`: after day grouping, pipe each `daySessions` through `groupSessionsByVideo`. Render each bucket:
-  - `sessions.length === 1`: existing `SessionRow` behavior, unchanged.
-  - `sessions.length >= 2`: render a **bucket row** that looks like `SessionRow` but shows combined totals and session count (e.g. `3 sessions · 1h 24m · 12 cards`). Chevron state stored in a second `Set<string>` on bucket key. Expanded buckets render the child `SessionRow`s indented (`pl-8`) beneath the header.
-- `MediaSessionList.tsx`: within the media detail view, a single video's sessions are all the same `videoId` by definition — grouping here is by day only, and within a day multiple sessions render nested under a day header. Re-use the same visual pattern; factor the bucket row into a shared `SessionBucketRow` component.
-
-### Delete semantics
-
-- Deleting a bucket header offers "Delete all N sessions in this group" (reuse `confirmDayGroupDelete` pattern with a bucket-specific message, or add `confirmBucketDelete`).
-- Deleting an individual session from inside an expanded bucket keeps the existing single-delete flow.
-
-### Tests
-
-- `session-grouping.test.ts`:
-  - Empty input → empty output.
-  - All unique videos → N singleton buckets.
-  - Two sessions same videoId → one bucket with correct totals and representative (most recent start time).
-  - Missing videoId → singleton bucket keyed by sessionId.
-- `SessionsTab.test.tsx` (extend or add) verifying the rendered bucket rows expand/collapse and delete hooks fire with the right ID set.
-
----
-
-## Item 3 — 365d trends range
-
-### Backend
-
-`src/core/services/immersion-tracker/query-trends.ts`:
-
-- `type TrendRange = '7d' | '30d' | '90d' | '365d' | 'all';`
-- Add `'365d': 365` to `TREND_DAY_LIMITS`.
-- `getTrendDayLimit` picks up the new key automatically because of the `Exclude<TrendRange, 'all'>` generic.
-
-`src/core/services/stats-server.ts`:
-
-- Search for any hardcoded range validation (e.g. allow-list in the trends route handler) and extend it.
-
-### Frontend
-
-- `hooks/useTrends.ts`: widen the `TimeRange` union.
-- `components/trends/DateRangeSelector.tsx`: add `'365d'` to the options list. Display label stays as `365d`.
-- `lib/api-client.ts` / `api-client.test.ts`: if the client validates ranges, add `365d`.
-
-### Tests
-
-- `query.test.ts`: extend the existing range table to cover `365d` returning 365 days of data.
-- `stats-server.test.ts`: ensure the route accepts `range=365d`.
-- `api-client.test.ts`: ensure the client emits the new range.
-
-### Change-specific checks
-
-- `bun run test:config` is not required here (no schema/defaults change).
-- Run `bun run typecheck` + `bun run test:fast`.
-
----
-
-## Item 4 — Delete episode from library detail
-
-### Current behavior
-
-`MediaDetailView.tsx` provides session-level delete only. The backend `deleteVideo` exists (`query-maintenance.ts:509`), the API is exposed at `stats-server.ts:559`, and `api-client.deleteVideo` is already wired (`stats/src/lib/api-client.ts:146`). `EpisodeList.tsx:46` already uses it from the anime tab.
-
-### Target behavior
-
-A "Delete Episode" action in `MediaHeader` (top-right, small, `text-ctp-red`), gated by `confirmEpisodeDelete(title)`. On success, call `onBack()` and make sure the parent `LibraryTab` refetches.
-
-### Implementation
-
-- Add an `onDeleteEpisode?: () => void` prop to `MediaHeader` and render the button only if provided.
-- In `MediaDetailView`:
-  - New handler `handleDeleteEpisode` that calls `apiClient.deleteVideo(videoId)`, then `onBack()`.
-  - Reuse `confirmEpisodeDelete` from `stats/src/lib/delete-confirm.ts`.
-- In `LibraryTab`:
-  - `useMediaLibrary` returns fresh data on mount. The simplest fix: pass a `refresh` function from the hook (extend the hook if it doesn't already expose one) and call it when the detail view signals back.
-  - Alternative: force a remount by incrementing a `libraryVersion` key on the library list. Prefer `refresh` for clarity.
-
-### Tests
-
-- Extend the existing `MediaDetailView.test.tsx`: mock `apiClient.deleteVideo`, click the new button, confirm `onBack` fires after success.
-- `useMediaLibrary.test.ts`: if we add a `refresh` method, cover it.
-
----
-
-## Item 5 — Vocabulary word/reading column collapse
-
-### Current behavior
-
-`FrequencyRankTable.tsx:110-144` uses a 5-column table: `Rank | Word | Reading | POS | Seen`. Word and Reading are auto-sized, producing a large gap.
-
-### Target behavior
-
-Merge Word + Reading into a single column titled "Word". Reading sits immediately after the headword in a muted, smaller style.
-
-### Implementation
-
-- Drop the `<th>Reading</th>` header and cell.
-- Word cell becomes:
-  ```tsx
-  <td className="py-1.5 pr-3">
-    <span className="text-ctp-text font-medium">{w.headword}</span>
-    {reading && <span className="text-ctp-subtext0 text-xs ml-1.5">【{reading}】</span>}
-  </td>
-  ```
-  where `reading = fullReading(w.headword, w.reading)` and differs from `headword`.
-- Keep `fullReading` import from `reading-utils`.
-
-### Tests
-
-- Extend `FrequencyRankTable.test.tsx` (if present — otherwise add a focused test) to assert:
-  - Headword renders.
-  - Reading renders when different from headword.
-  - Reading does not render when equal to headword.
-
----
-
-## Item 6 — Hide Anki-deleted cards in Cards Mined
-
-### Current behavior
-
-`EpisodeDetail.tsx:109-147` iterates `cardEvents`, fetches note info via `ankiNotesInfo(allNoteIds)`, and for each `noteId` renders a row even if no matching `info` came back — the user sees an empty word with an "Open in Anki" button that leads nowhere.
-
-### Target behavior
-
-After `ankiNotesInfo` resolves:
-
-- Drop `noteId`s that are not in the resolved map.
-- Drop `cardEvents` whose `noteIds` list was non-empty but is now empty after filtering.
-- Card events with a positive `cardsDelta` but no `noteIds` (legacy rollup path) still render as `+N cards` — we have no way to cross-reference them, so leave them alone.
-
-### Implementation
-
-- Compute `filteredCardEvents` as a `useMemo` depending on `data.cardEvents` and `noteInfos`.
-- Iterate `filteredCardEvents` instead of `cardEvents` in the render.
-- Surface a subtle note (optional, muted) "N cards hidden (deleted from Anki)" at the end of the list if any were filtered — helps the user understand why counts here diverge from session totals. Final decision on the note can be made at PR review; default: **show it**.
-
-### Tests
-
-- Add a test in `EpisodeDetail.test.tsx` (add the file if not present) that stubs `ankiNotesInfo` to return only a subset of notes and verifies the missing ones are not rendered.
-
-### Other call sites
-
-- Grep so far shows `ankiNotesInfo` is only used in `EpisodeDetail.tsx`. Re-verify before landing the commit; if another call site appears, apply the same filter.
-
----
-
-## Item 7 — Trend/watch chart clarity pass
-
-### Current behavior
-
-`TrendChart.tsx`, `StackedTrendChart.tsx`, and `WatchTimeChart.tsx` render Recharts components with:
-
-- No `CartesianGrid` → no horizontal reference lines.
-- 9px axis ticks → borderline unreadable.
-- Height 120 → cramped.
-- Tooltip uses raw labels (`04/04` etc.).
-- No shared theme object; each chart redefines colors and tooltip styles inline.
-
-`stats/src/lib/chart-theme.ts` already exists and currently exports a single `CHART_THEME` constant with tick/tooltip colors and `barFill`. It will be extended, not replaced, to preserve existing consumers.
-
-### Target behavior
-
-All three charts share a theme, have horizontal gridlines, readable ticks, and sensible tooltips.
-
-### Implementation
-
-Extend `stats/src/lib/chart-theme.ts` with the additional shared defaults (keeping the existing `CHART_THEME` export intact so current consumers don't break):
-
-```ts
-export const CHART_THEME = {
-  tick: '#a5adcb',
-  tooltipBg: '#363a4f',
-  tooltipBorder: '#494d64',
-  tooltipText: '#cad3f5',
-  tooltipLabel: '#b8c0e0',
-  barFill: '#8aadf4',
-  grid: '#494d64',
-  axisLine: '#494d64',
-} as const;
-
-export const CHART_DEFAULTS = {
-  height: 160,
-  tickFontSize: 11,
-  margin: { top: 8, right: 8, bottom: 0, left: 0 },
-  grid: { strokeDasharray: '3 3', vertical: false },
-} as const;
-
-export const TOOLTIP_CONTENT_STYLE = {
-  background: CHART_THEME.tooltipBg,
-  border: `1px solid ${CHART_THEME.tooltipBorder}`,
-  borderRadius: 6,
-  color: CHART_THEME.tooltipText,
-  fontSize: 12,
-};
-```
-
-Apply to each chart:
-
-- Import `CartesianGrid` from recharts.
-- Insert `<CartesianGrid stroke={CHART_THEME.grid} {...CHART_DEFAULTS.grid} />` inside each chart container.
-- `<XAxis tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }} />` and equivalent `YAxis`.
-- `YAxis` gains `axisLine={{ stroke: CHART_THEME.axisLine }}`.
-- `ResponsiveContainer` height changes from 120 → `CHART_DEFAULTS.height`.
-- `Tooltip` `contentStyle` uses `TOOLTIP_CONTENT_STYLE`, and charts pass a `labelFormatter` when the label is a date key (e.g. show `Fri Apr 4`).
-
-### Unit formatters
-
-- `TrendChart` already accepts a `formatter` prop — extend usage sites to pass unit-aware formatters where they aren't already (`formatDuration`, `formatNumber`, etc.).
-
-### Tests
-
-- `chart-theme.test.ts` (if present — otherwise add a trivial snapshot to keep the shape stable).
-- `TrendChart` snapshot/render tests: no regression, gridline element present.
-
----
-
-## Verification gate
-
-Before requesting code review, run:
-
-```
-bun run typecheck
-bun run test:fast
-bun run test:env
-bun run test:runtime:compat   # dist-sensitive check for the charts
-bun run build
-bun run test:smoke:dist
-```
-
-No docs-site changes are planned in this spec; if `docs-site/` ends up touched (e.g. screenshots), also run `bun run docs:test` and `bun run docs:build`.
-
-No config schema changes → `bun run test:config` and `bun run generate:config-example` are not required.
-
-## Risks and open questions
-
-- **MediaDetailView refresh**: `useMediaLibrary` may not expose a `refresh` function. If it doesn't, the simplest path is adding one; the alternative (keying a remount) works but is harder to test. Decide during implementation.
-- **Session bucket delete UX**: "Delete all N sessions in this group" is powerful. The copy must make it clear the underlying sessions are being removed, not just the grouping. Reuse `confirmBucketDelete` wording from existing confirm helpers if possible.
-- **Anki-deleted-cards hidden notice**: Showing a subtle "N cards hidden" footer is a call that can be made at PR review.
-- **Bucket delete helper**: `confirmBucketDelete` does not currently exist in `delete-confirm.ts`. Implementation either adds it or reuses `confirmDayGroupDelete` with bucket-specific wording — decide during the session-rollup commit.
-
-## Changelog entry
-
-User-visible PR → needs a fragment under `changes/*.md`. Suggested title:
-`Stats dashboard: collapsible series, session rollups, 365d trends, chart polish, episode delete.`

docs/workflow/README.md

@@ -3,7 +3,7 @@
 # Workflow
 
 Status: active  
-Last verified: 2026-05-23  
+Last verified: 2026-08-13
 Owner: Kyle Yasuda  
 Read when: planning or executing nontrivial work in this repo
 
@@ -13,7 +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
-- [Agent Plugins](./agent-plugins.md) - repo-local plugin ownership for agent workflow skills
+- [Agent Skills](./agent-skills.md) - repo-local workflow skill ownership
 - [Release Guide](../RELEASING.md) - tagged release workflow
 
 ## Default Flow

docs/workflow/agent-plugins.md

@@ -1,27 +0,0 @@
-<!-- read_when: using or modifying repo-local agent plugins -->
-
-# Agent Plugins
-
-Status: active
-Last verified: 2026-05-23
-Owner: Kyle Yasuda
-Read when: packaging or migrating repo-local agent workflow skills into plugins
-
-## SubMiner Workflow Plugin
-
-- Canonical plugin path: `plugins/subminer-workflow/`
-- Marketplace catalog: `.agents/plugins/marketplace.json`
-- Canonical skill sources:
-  - `plugins/subminer-workflow/skills/subminer-scrum-master/`
-  - `plugins/subminer-workflow/skills/subminer-change-verification/`
-
-## Migration Rule
-
-- Plugin-owned skills are the source of truth.
-- `.agents/skills/subminer-*` remain only as compatibility shims.
-- Existing script entrypoints under `.agents/skills/subminer-change-verification/scripts/` stay as wrappers so historical commands do not break.
-
-## Verification
-
-- For plugin/docs-only changes, start with `bun run test:docs:kb`.
-- Use the plugin-owned verifier when the change crosses from docs into scripts or workflow logic.

docs/workflow/agent-skills.md

@@ -0,0 +1,34 @@
+<!-- read_when: using or modifying repo-local agent skills -->
+
+# Agent Skills
+
+Status: active
+Last verified: 2026-08-23
+Owner: Kyle Yasuda
+Read when: using, adding, or changing a repo-local agent workflow skill
+
+## Canonical Skills
+
+- `.agents/skills/subminer-change-verification/`
+  - Selects the cheapest sufficient repo-native verification lane.
+  - Defers command ownership to `package.json` and `docs/workflow/verification.md`.
+- `.agents/skills/subminer-release/`
+  - Prepares, cuts, publishes, or repairs stable and prerelease releases.
+  - Defers release procedure and policy to `docs/RELEASING.md`.
+
+Repo-local workflows stay as standalone skills. Do not add plugin packaging, marketplace metadata, or compatibility shims unless the workflow is intentionally being distributed beyond this repository.
+
+## Rules
+
+- Keep each skill focused on one repeatable repository task.
+- Prefer instructions over helper scripts unless deterministic tooling provides clear value beyond existing package commands.
+- Keep trigger descriptions narrow enough to avoid invoking skills for unrelated requests.
+- Update this page and the documentation catalog when skill ownership changes.
+
+## Verification
+
+For skill or internal workflow documentation changes, run:
+
+```bash
+bun run test:docs:kb
+```

docs/workflow/verification.md

@@ -3,14 +3,14 @@
 # Verification
 
 Status: active  
-Last verified: 2026-07-06  
+Last verified: 2026-08-13
 Owner: Kyle Yasuda  
 Read when: selecting the right verification lane for a change
 
 ## Lane Infrastructure
 
 - Lane membership is defined once in `scripts/test-lanes.ts` and discovered by
-  directory — new test files join their lane automatically; never hand-list test
+  directory, so new test files join their lane automatically; never hand-list test
   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
@@ -43,8 +43,8 @@ bun run docs:build
 
 ## Cheap-First Lane Selection
 
-- Docs-only boundary/content changes: `bun run docs:test`, `bun run docs:build`
-- Internal KB / `AGENTS.md` changes: `bun run test:docs:kb`
+- User-facing `docs-site/` changes: `bun run docs:test`, `bun run docs:build`
+- Internal KB, `AGENTS.md`, or `.agents/skills/**` changes: `bun run test:docs:kb`
 - Config/schema/defaults: `bun run test:config`, then `bun run generate:config-example` if template/defaults changed
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
 - Runtime-compat / compiled behavior: `bun run test:runtime:compat`

launcher/commands/app-command.ts

@@ -16,10 +16,6 @@ type AppCommandDeps = {
     appPath: string,
     logLevel: LauncherCommandContext['args']['logLevel'],
   ) => void;
-  launchAnimeBrowserDetached: (
-    appPath: string,
-    logLevel: LauncherCommandContext['args']['logLevel'],
-  ) => void;
 };
 
 const defaultAppCommandDeps: AppCommandDeps = {
@@ -27,8 +23,6 @@ const defaultAppCommandDeps: AppCommandDeps = {
   launchSyncUiDetached: (appPath, logLevel) =>
     launchAppCommandDetached(appPath, ['--sync-window'], logLevel, 'sync-ui'),
   launchAppBackgroundDetached,
-  launchAnimeBrowserDetached: (appPath, logLevel) =>
-    launchAppCommandDetached(appPath, ['--anime'], logLevel, 'anime'),
 };
 
 export function runAppPassthroughCommand(
@@ -43,11 +37,6 @@ export function runAppPassthroughCommand(
     deps.runAppCommandWithInherit(appPath, ['--settings']);
     return true;
   }
-  if (args.animeBrowser) {
-    // Detached: the browser window is long-lived and owns the bridge process.
-    deps.launchAnimeBrowserDetached(appPath, args.logLevel);
-    return true;
-  }
   if (args.syncUi) {
     deps.launchSyncUiDetached(appPath, args.logLevel);
     return true;

launcher/commands/command-modules.test.ts

@@ -207,7 +207,6 @@ test('app command starts default macOS background app detached from launcher', (
       calls.push('attached');
     },
     launchSyncUiDetached: () => calls.push('sync-ui'),
-    launchAnimeBrowserDetached: () => {},
     launchAppBackgroundDetached: (appPath, logLevel) => {
       calls.push(`detached:${appPath}:${logLevel}`);
     },
@@ -228,7 +227,6 @@ test('app command starts default Linux background app detached from launcher', (
       calls.push('attached');
     },
     launchSyncUiDetached: () => calls.push('sync-ui'),
-    launchAnimeBrowserDetached: () => {},
     launchAppBackgroundDetached: (appPath, logLevel) => {
       calls.push(`detached:${appPath}:${logLevel}`);
     },
@@ -250,7 +248,6 @@ test('app command keeps explicit passthrough args attached', () => {
       forwarded.push(appArgs);
     },
     launchSyncUiDetached: () => detached.push('sync-ui'),
-    launchAnimeBrowserDetached: () => {},
     launchAppBackgroundDetached: () => {
       detached.push('detached');
     },
@@ -269,7 +266,6 @@ test('sync UI command launches the app detached from the terminal', () => {
   const handled = runAppPassthroughCommand(context, {
     runAppCommandWithInherit: () => calls.push('piped'),
     launchSyncUiDetached: (appPath, logLevel) => calls.push(`sync-ui:${appPath}:${logLevel}`),
-    launchAnimeBrowserDetached: () => calls.push('anime'),
     launchAppBackgroundDetached: () => calls.push('detached'),
   });
 

launcher/commands/history-command.ts

@@ -23,6 +23,7 @@ import {
   type HistorySeriesEntry,
 } from '../history.js';
 import type { Args } from '../types.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import type { LauncherCommandContext } from './context.js';
 
 export type HistorySessionAction = 'previous' | 'replay' | 'next' | 'browse' | 'quit';
@@ -333,6 +334,13 @@ export async function runHistoryCommand(
   const { args, scriptPath } = context;
 
   checkPickerDependencies(args);
+  if (args.useRofi) {
+    await ensureLinuxRuntimePluginAvailable({
+      appPath: context.appPath ?? undefined,
+      scriptPath,
+      logLevel: args.logLevel,
+    });
+  }
   const themePath = args.useRofi ? findRofiTheme(scriptPath) : null;
 
   const dbPath = resolveImmersionDbPath();

launcher/commands/jellyfin-command.ts

@@ -2,6 +2,7 @@ import { fail } from '../log.js';
 import { runAppCommandWithInherit } from '../mpv.js';
 import { commandExists } from '../util.js';
 import { runJellyfinPlayMenu } from '../jellyfin.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import { shouldForwardLogLevel } from '../types.js';
 import type { LauncherCommandContext } from './context.js';
 
@@ -64,6 +65,13 @@ export async function runJellyfinCommand(context: LauncherCommandContext): Promi
     if (args.useRofi && !commandExists('rofi')) {
       fail('rofi not found. Install rofi or omit -R for fzf.');
     }
+    if (args.useRofi) {
+      await ensureLinuxRuntimePluginAvailable({
+        appPath,
+        scriptPath,
+        logLevel: args.logLevel,
+      });
+    }
     await runJellyfinPlayMenu(appPath, args, scriptPath, mpvSocketPath);
     return true;
   }

launcher/commands/playback-command.test.ts

@@ -63,7 +63,6 @@ function createContext(): LauncherCommandContext {
       logsExport: false,
       version: false,
       settings: false,
-      animeBrowser: false,
       configPath: false,
       configShow: false,
       mpvIdle: false,
@@ -497,3 +496,39 @@ test('playback command ensures Linux runtime plugin before mpv launch', async ()
 
   assert.deepEqual(calls, ['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');
+    },
+    chooseTarget: async () => {
+      calls.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']);
+});

launcher/commands/playback-command.ts

@@ -157,6 +157,7 @@ export async function runPlaybackCommand(context: LauncherCommandContext): Promi
       });
     },
     chooseTarget,
+    checkPickerDependencies,
     checkDependencies,
     registerCleanup,
     startMpv,
@@ -177,6 +178,7 @@ type PlaybackCommandDeps = {
     args: Args,
     scriptPath: string,
   ) => Promise<{ target: string; kind: 'file' | 'url' } | null>;
+  checkPickerDependencies?: (args: Args) => void;
   checkDependencies: (args: Args) => void;
   registerCleanup: (context: LauncherCommandContext) => void;
   startMpv: typeof startMpv;
@@ -201,7 +203,18 @@ export async function runPlaybackCommandWithDeps(
   await deps.ensurePlaybackSetupReady(context);
 
   if (!args.target) {
-    checkPickerDependencies(args);
+    (deps.checkPickerDependencies ?? checkPickerDependencies)(args);
+  }
+
+  let runtimeAssetsReady = false;
+  const ensureRuntimeAssetsReady = async (): Promise<void> => {
+    if (runtimeAssetsReady) return;
+    await deps.ensureRuntimePluginReady(context);
+    runtimeAssetsReady = true;
+  };
+
+  if (!args.target && args.useRofi) {
+    await ensureRuntimeAssetsReady();
   }
 
   const targetChoice = await deps.chooseTarget(args, scriptPath);
@@ -266,7 +279,7 @@ export async function runPlaybackCommandWithDeps(
     );
   }
 
-  await deps.ensureRuntimePluginReady(context);
+  await ensureRuntimeAssetsReady();
 
   await deps.startMpv(
     selectedTarget.target,

launcher/commands/stats-command.ts

@@ -157,6 +157,15 @@ export async function runStatsCommand(
     if (args.statsCleanupLifetime) {
       forwarded.push('--stats-cleanup-lifetime');
     }
+    if (args.statsCleanupDuplicateLines) {
+      forwarded.push('--stats-cleanup-duplicate-lines');
+    }
+    if (args.statsCleanupDryRun) {
+      forwarded.push('--stats-cleanup-dry-run');
+    }
+    if (args.statsCleanupLookbackDays) {
+      forwarded.push('--stats-cleanup-lookback-days', String(args.statsCleanupLookbackDays));
+    }
     if (shouldForwardLogLevel(args.logLevel)) {
       forwarded.push('--log-level', args.logLevel);
     }

launcher/commands/update-command.test.ts

@@ -36,6 +36,11 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
         launcher: { status: 'updated' },
         supportAssets: [
           { status: 'updated', component: 'theme', message: 'Installed theme.' },
+          {
+            status: 'updated',
+            component: 'thumbnailer',
+            message: 'Installed rofi thumbnailer.',
+          },
           { status: 'skipped', component: 'plugin', message: 'Plugin already up to date.' },
         ],
       };
@@ -52,6 +57,7 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
     'info:AppImage update: updated',
     'info:Launcher update: updated',
     'info:Support assets (theme) update: updated - Installed theme.',
+    'info:Support assets (thumbnailer) update: updated - Installed rofi thumbnailer.',
     'info:Support assets (plugin) update: skipped - Plugin already up to date.',
   ]);
 });

launcher/commands/update-command.ts

@@ -21,7 +21,10 @@ import {
   parseSha256Sums,
   type FetchLike,
 } from '../../src/main/runtime/update/release-assets.js';
-import { updateSupportAssetsFromRelease } from '../../src/main/runtime/update/support-assets.js';
+import {
+  updateSupportAssetsFromRelease,
+  type SupportAssetsUpdateResult,
+} from '../../src/main/runtime/update/support-assets.js';
 
 type UpdateCommandResponse = {
   ok: boolean;
@@ -36,15 +39,14 @@ type DirectReleaseUpdateRequest = {
   channel: UpdateChannel;
 };
 
+type DirectSupportAssetsUpdateResult = Omit<SupportAssetsUpdateResult, 'status'> & {
+  status: string;
+};
+
 type DirectReleaseUpdateResult = {
   appImage: { status: string; command?: string; message?: string };
   launcher: { status: string; command?: string; message?: string };
-  supportAssets: Array<{
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  }>;
+  supportAssets: DirectSupportAssetsUpdateResult[];
 };
 
 type UpdateCommandDeps = {
@@ -129,12 +131,7 @@ function readUpdateChannel(root: Record<string, unknown> | null): UpdateChannel
 
 function logUpdateResult(
   label: string,
-  result: {
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  },
+  result: DirectSupportAssetsUpdateResult,
   configuredLogLevel: NonNullable<LauncherCommandContext['args']['logLevel']>,
   deps: Pick<UpdateCommandDeps, 'log'>,
 ): void {

launcher/config/args-normalizer.test.ts

@@ -120,7 +120,6 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
       logLevel: 'warn',
     },
     settingsInvocation: null,
-    animeInvocation: null,
     mpvInvocation: null,
     appInvocation: null,
     dictionaryTriggered: false,
@@ -135,6 +134,9 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
     statsLogLevel: null,
     syncTriggered: false,
     syncCliTokens: [],
@@ -172,7 +174,6 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
     settingsInvocation: {
       logLevel: undefined,
     },
-    animeInvocation: null,
     mpvInvocation: null,
     appInvocation: null,
     dictionaryTriggered: false,
@@ -187,6 +188,9 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
     statsLogLevel: null,
     syncTriggered: false,
     syncCliTokens: [],
@@ -217,7 +221,6 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
         action: undefined,
       },
       settingsInvocation: null,
-      animeInvocation: null,
       mpvInvocation: null,
       appInvocation: null,
       dictionaryTriggered: false,
@@ -232,6 +235,9 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
       statsCleanup: false,
       statsCleanupVocab: false,
       statsCleanupLifetime: false,
+      statsCleanupDuplicateLines: false,
+      statsCleanupDryRun: false,
+      statsCleanupLookbackDays: null,
       statsLogLevel: null,
       syncTriggered: false,
       syncCliTokens: [],
@@ -260,7 +266,6 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
     jellyfinInvocation: null,
     configInvocation: null,
     settingsInvocation: null,
-    animeInvocation: null,
     mpvInvocation: null,
     appInvocation: null,
     dictionaryTriggered: false,
@@ -275,6 +280,9 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
     statsLogLevel: null,
     syncTriggered: false,
     syncCliTokens: [],

launcher/config/args-normalizer.ts

@@ -162,13 +162,14 @@ export function createDefaultArgs(
     statsCleanup: false,
     statsCleanupVocab: false,
     statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
     doctor: false,
     doctorRefreshKnownWords: false,
     logsExport: false,
     version: false,
     update: false,
     settings: false,
-    animeBrowser: false,
     configPath: false,
     configShow: false,
     mpvIdle: false,
@@ -259,6 +260,11 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
   if (invocations.statsCleanup) parsed.statsCleanup = true;
   if (invocations.statsCleanupVocab) parsed.statsCleanupVocab = true;
   if (invocations.statsCleanupLifetime) parsed.statsCleanupLifetime = true;
+  if (invocations.statsCleanupDuplicateLines) parsed.statsCleanupDuplicateLines = true;
+  if (invocations.statsCleanupDryRun) parsed.statsCleanupDryRun = true;
+  if (invocations.statsCleanupLookbackDays !== null) {
+    parsed.statsCleanupLookbackDays = invocations.statsCleanupLookbackDays;
+  }
   if (invocations.dictionaryTarget) {
     parsed.dictionaryTarget = parseDictionaryTarget(invocations.dictionaryTarget);
   } else if (
@@ -349,12 +355,6 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
       );
   }
 
-  if (invocations.animeInvocation) {
-    if (invocations.animeInvocation.logLevel) {
-      parsed.logLevel = parseLogLevel(invocations.animeInvocation.logLevel);
-    }
-    parsed.animeBrowser = true;
-  }
   if (invocations.settingsInvocation) {
     if (invocations.settingsInvocation.logLevel) {
       parsed.logLevel = parseLogLevel(invocations.settingsInvocation.logLevel);

launcher/config/cli-parser-builder.ts

@@ -23,7 +23,6 @@ export interface CliInvocations {
   jellyfinInvocation: JellyfinInvocation | null;
   configInvocation: CommandActionInvocation | null;
   settingsInvocation: CommandActionInvocation | null;
-  animeInvocation: CommandActionInvocation | null;
   mpvInvocation: CommandActionInvocation | null;
   appInvocation: { appArgs: string[] } | null;
   dictionaryTriggered: boolean;
@@ -38,6 +37,9 @@ export interface CliInvocations {
   statsCleanup: boolean;
   statsCleanupVocab: boolean;
   statsCleanupLifetime: boolean;
+  statsCleanupDuplicateLines: boolean;
+  statsCleanupDryRun: boolean;
+  statsCleanupLookbackDays: number | null;
   statsLogLevel: string | null;
   syncTriggered: boolean;
   syncCliTokens: string[];
@@ -54,6 +56,16 @@ export interface CliInvocations {
   texthookerOpenBrowser: boolean;
 }
 
+/** `--lookback-days` narrows the duplicate-line cleanup; fractions are floored. */
+function parseStatsLookbackDays(value: unknown): number | null {
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const days = Number(value);
+  if (!Number.isFinite(days) || days < 1) {
+    throw new Error('Stats --lookback-days must be at least one day.');
+  }
+  return Math.floor(days);
+}
+
 function applyRootOptions(program: Command): void {
   program
     .option(
@@ -103,7 +115,6 @@ function getTopLevelCommand(argv: string[]): { name: string; index: number } | n
     'doctor',
     'config',
     'settings',
-    'anime',
     'mpv',
     'logs',
     'dictionary',
@@ -157,7 +168,6 @@ export function parseCliPrograms(
   let jellyfinInvocation: JellyfinInvocation | null = null;
   let configInvocation: CommandActionInvocation | null = null;
   let settingsInvocation: CommandActionInvocation | null = null;
-  let animeInvocation: CommandActionInvocation | null = null;
   let mpvInvocation: CommandActionInvocation | null = null;
   let appInvocation: { appArgs: string[] } | null = null;
   let dictionaryTriggered = false;
@@ -172,6 +182,9 @@ export function parseCliPrograms(
   let statsCleanup = false;
   let statsCleanupVocab = false;
   let statsCleanupLifetime = false;
+  let statsCleanupDuplicateLines = false;
+  let statsCleanupDryRun = false;
+  let statsCleanupLookbackDays: number | null = null;
   let statsLogLevel: string | null = null;
   let syncTriggered = false;
   let syncCliTokens: string[] = [];
@@ -272,6 +285,9 @@ export function parseCliPrograms(
     .option('-s, --stop', 'Stop the background stats server')
     .option('-v, --vocab', 'Clean vocabulary rows in the stats database')
     .option('-l, --lifetime', 'Rebuild lifetime summary rows from retained data')
+    .option('-d, --duplicate-lines', 'Collapse repeated subtitle lines from typeset animations')
+    .option('--dry-run', 'Report what a cleanup would remove without changing anything')
+    .option('--lookback-days <days>', 'Only clean lines recorded in the last N days')
     .option('--log-level <level>', 'Log level')
     .action((action: string | undefined, options: Record<string, unknown>) => {
       statsTriggered = true;
@@ -292,13 +308,35 @@ export function parseCliPrograms(
       if (normalizedAction && (statsBackground || statsStop)) {
         throw new Error('Stats background and stop flags cannot be combined with stats actions.');
       }
-      if (normalizedAction !== 'cleanup' && (options.vocab === true || options.lifetime === true)) {
-        throw new Error('Stats --vocab and --lifetime flags require the cleanup action.');
+      if (
+        normalizedAction !== 'cleanup' &&
+        (options.vocab === true || options.lifetime === true || options.duplicateLines === true)
+      ) {
+        throw new Error(
+          'Stats --vocab, --lifetime and --duplicate-lines flags require the cleanup action.',
+        );
+      }
+      if (
+        options.duplicateLines !== true &&
+        (options.dryRun === true || options.lookbackDays !== undefined)
+      ) {
+        throw new Error('Stats --dry-run and --lookback-days require --duplicate-lines.');
       }
       if (normalizedAction === 'cleanup') {
         statsCleanup = true;
         statsCleanupLifetime = options.lifetime === true;
-        statsCleanupVocab = statsCleanupLifetime ? false : options.vocab !== false;
+        statsCleanupDuplicateLines = options.duplicateLines === true;
+        const explicitModeCount = [options.vocab, options.lifetime, options.duplicateLines].filter(
+          (value) => value === true,
+        ).length;
+        if (explicitModeCount > 1) {
+          throw new Error('Stats cleanup runs one mode at a time.');
+        }
+        // Vocabulary cleanup stays the default so `stats cleanup` keeps its old meaning.
+        statsCleanupVocab =
+          statsCleanupLifetime || statsCleanupDuplicateLines ? false : options.vocab !== false;
+        statsCleanupDryRun = options.dryRun === true;
+        statsCleanupLookbackDays = parseStatsLookbackDays(options.lookbackDays);
       } else if (normalizedAction === 'rebuild' || normalizedAction === 'backfill') {
         statsCleanup = true;
         statsCleanupLifetime = true;
@@ -418,16 +456,6 @@ export function parseCliPrograms(
       };
     });
 
-  commandProgram
-    .command('anime')
-    .description('Open the anime browser window')
-    .option('--log-level <level>', 'Log level')
-    .action((options: Record<string, unknown>) => {
-      animeInvocation = {
-        logLevel: typeof options.logLevel === 'string' ? options.logLevel : undefined,
-      };
-    });
-
   commandProgram
     .command('mpv')
     .description('MPV helpers')
@@ -482,7 +510,6 @@ export function parseCliPrograms(
       jellyfinInvocation,
       configInvocation,
       settingsInvocation,
-      animeInvocation,
       mpvInvocation,
       appInvocation,
       dictionaryTriggered,
@@ -497,6 +524,9 @@ export function parseCliPrograms(
       statsCleanup,
       statsCleanupVocab,
       statsCleanupLifetime,
+      statsCleanupDuplicateLines,
+      statsCleanupDryRun,
+      statsCleanupLookbackDays,
       statsLogLevel,
       syncTriggered,
       syncCliTokens,

launcher/jellyfin.test.ts

@@ -57,7 +57,6 @@ function createArgs(): Args {
     logsExport: false,
     version: false,
     settings: false,
-    animeBrowser: false,
     configPath: false,
     configShow: false,
     mpvIdle: false,

launcher/main.test.ts

@@ -73,20 +73,21 @@ function makeTestEnv(homeDir: string, xdgConfigHome: string): NodeJS.ProcessEnv
   };
 }
 
-// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which —
-// when the runtime plugin/theme are missing — spawns the app with
-// `--ensure-linux-runtime-plugin-assets` and polls up to 30s
+// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which
+// spawns the app with `--ensure-linux-runtime-plugin-assets` when managed
+// support assets are missing and polls up to 30s
 // (RESPONSE_TIMEOUT_MS) for an install response. A fake app that just exits
 // never writes that response, so the launcher hangs and the test times out on
 // Linux CI (the preflight is a no-op on macOS/Windows). This shell prelude makes
-// the fake app install the managed plugin/theme and write the response, matching
+// the fake app install the managed support assets and write the response, matching
 // launcher/smoke.e2e.test.ts. Prepend it to each fake app that reaches playback.
 const RUNTIME_PLUGIN_PREFLIGHT_SH = `if [ "$1" = "--ensure-linux-runtime-plugin-assets" ]; then
   data="\${XDG_DATA_HOME:-$HOME/.local/share}/SubMiner"
-  mkdir -p "$data/plugin/subminer" "$data/themes"
+  mkdir -p "$data/plugin/subminer" "$data/themes" "$data/thumbnailers"
   printf -- '-- test plugin\\n' > "$data/plugin/subminer/main.lua"
   printf 'test=true\\n' > "$data/plugin/subminer.conf"
   printf '/* test theme */\\n' > "$data/themes/subminer.rasi"
+  printf '[Thumbnailer Entry]\\n' > "$data/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"
   if [ "$2" = "--ensure-linux-runtime-plugin-assets-response-path" ] && [ -n "$3" ]; then
     mkdir -p "$(dirname "$3")"
     printf '{"ok":true,"status":"installed","path":"%s"}' "$data/plugin/subminer/main.lua" > "$3"

launcher/mpv.test.ts

@@ -222,7 +222,7 @@ test('buildMpvEnv preserves native Wayland env for supported Hyprland and Sway a
   });
 });
 
-test('buildMpvBackendArgs forces an explicit X11 renderer stack when backend resolves to x11', () => {
+test('buildMpvBackendArgs pins the X11 window context when backend resolves to x11', () => {
   withPlatform('linux', () => {
     assert.deepEqual(
       buildMpvBackendArgs(makeArgs({ backend: 'x11' }), {
@@ -230,12 +230,12 @@ test('buildMpvBackendArgs forces an explicit X11 renderer stack when backend res
         WAYLAND_DISPLAY: 'wayland-0',
         XDG_SESSION_TYPE: 'wayland',
       }),
-      ['--vo=gpu', '--gpu-api=opengl', '--gpu-context=x11egl,x11'],
+      ['--gpu-context=x11vk,x11egl,x11'],
     );
   });
 });
 
-test('buildMpvBackendArgs forces the same X11 renderer stack for unsupported Wayland auto fallback', () => {
+test('buildMpvBackendArgs pins the same X11 window context for unsupported Wayland auto fallback', () => {
   withPlatform('linux', () => {
     assert.deepEqual(
       buildMpvBackendArgs(makeArgs({ backend: 'auto' }), {
@@ -245,7 +245,7 @@ test('buildMpvBackendArgs forces the same X11 renderer stack for unsupported Way
         XDG_CURRENT_DESKTOP: 'KDE',
         XDG_SESSION_DESKTOP: 'plasma',
       }),
-      ['--vo=gpu', '--gpu-api=opengl', '--gpu-context=x11egl,x11'],
+      ['--gpu-context=x11vk,x11egl,x11'],
     );
   });
 });
@@ -292,9 +292,7 @@ test('buildConfiguredMpvDefaultArgs appends maximized launch mode to configured
         '--secondary-sub-visibility=no',
         '--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
         '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
-        '--vo=gpu',
-        '--gpu-api=opengl',
-        '--gpu-context=x11egl,x11',
+        '--gpu-context=x11vk,x11egl,x11',
         '--window-maximized=yes',
       ],
     );
@@ -629,7 +627,6 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
     logsExport: false,
     version: false,
     settings: false,
-    animeBrowser: false,
     configPath: false,
     configShow: false,
     mpvIdle: false,

launcher/parse-args.test.ts

@@ -232,6 +232,75 @@ test('parseArgs maps lifetime stats cleanup flag', () => {
   assert.equal(parsed.statsCleanupLifetime, true);
 });
 
+test('parseArgs maps duplicate-line stats cleanup flags', () => {
+  const parsed = parseArgs(
+    ['stats', 'cleanup', '--duplicate-lines', '--dry-run', '--lookback-days', '30'],
+    'subminer',
+    {},
+  );
+
+  assert.equal(parsed.statsCleanup, true);
+  assert.equal(parsed.statsCleanupVocab, false);
+  assert.equal(parsed.statsCleanupDuplicateLines, true);
+  assert.equal(parsed.statsCleanupDryRun, true);
+  assert.equal(parsed.statsCleanupLookbackDays, 30);
+
+  const fractional = parseArgs(
+    ['stats', 'cleanup', '--duplicate-lines', '--lookback-days', '1.5'],
+    'subminer',
+    {},
+  );
+  assert.equal(fractional.statsCleanupLookbackDays, 1);
+});
+
+test('parseArgs rejects duplicate-line flags without the duplicate-lines mode', () => {
+  const error = withProcessExitIntercept(() => {
+    parseArgs(['stats', 'cleanup', '--dry-run'], 'subminer', {});
+  });
+
+  assert.equal(error.code, 1);
+  assert.match(error.stderr, /--dry-run and --lookback-days require --duplicate-lines/);
+});
+
+test('parseArgs rejects an empty lookback value outside duplicate-line cleanup', () => {
+  const error = withProcessExitIntercept(() => {
+    parseArgs(['stats', '--lookback-days', ''], 'subminer', {});
+  });
+
+  assert.equal(error.code, 1);
+  assert.match(error.stderr, /--dry-run and --lookback-days require --duplicate-lines/);
+});
+
+test('parseArgs rejects combining explicit cleanup modes', () => {
+  for (const modes of [
+    ['--lifetime', '--duplicate-lines'],
+    ['--vocab', '--duplicate-lines'],
+    ['--vocab', '--lifetime'],
+  ]) {
+    const error = withProcessExitIntercept(() => {
+      parseArgs(['stats', 'cleanup', ...modes], 'subminer', {});
+    });
+
+    assert.equal(error.code, 1);
+    assert.match(error.stderr, /Stats cleanup runs one mode at a time/);
+  }
+});
+
+test('parseArgs rejects unusable lookback windows', () => {
+  for (const value of ['0', '0.5', '-5', 'soon']) {
+    const error = withProcessExitIntercept(() => {
+      parseArgs(
+        ['stats', 'cleanup', '--duplicate-lines', '--lookback-days', value],
+        'subminer',
+        {},
+      );
+    });
+
+    assert.equal(error.code, 1);
+    assert.match(error.stderr, /--lookback-days must be at least one day/);
+  }
+});
+
 test('parseArgs rejects cleanup-only stats flags without cleanup action', () => {
   const error = withProcessExitIntercept(() => {
     parseArgs(['stats', '--vocab'], 'subminer', {});
@@ -239,7 +308,10 @@ test('parseArgs rejects cleanup-only stats flags without cleanup action', () =>
 
   assert.equal(error.code, 1);
   assert.match(error.message, /exit:1/);
-  assert.match(error.stderr, /Stats --vocab and --lifetime flags require the cleanup action/);
+  assert.match(
+    error.stderr,
+    /Stats --vocab, --lifetime and --duplicate-lines flags require the cleanup action/,
+  );
 });
 
 test('parseArgs maps stats rebuild action to cleanup lifetime mode', () => {

launcher/picker.test.ts

@@ -3,7 +3,12 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { findRofiTheme, formatRofiPrompt } from './picker';
+import {
+  findRofiTheme,
+  findRofiThumbnailerDataRoot,
+  formatRofiPrompt,
+  prependXdgDataDir,
+} from './picker';
 
 // ── formatRofiPrompt: spacing between prompt and input field ──────────────────
 
@@ -23,6 +28,7 @@ test('formatRofiPrompt leaves an empty prompt empty', () => {
 // ── findRofiTheme: Linux packaged path discovery ──────────────────────────────
 
 const ROFI_THEME_FILE = 'subminer.rasi';
+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';
 
 function makeFile(filePath: string): void {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -121,3 +127,42 @@ test('findRofiTheme resolves ~/.local/share/SubMiner/themes/subminer.rasi when X
     fs.rmSync(baseDir, { recursive: true, force: true });
   }
 });
+
+test('findRofiThumbnailerDataRoot resolves the managed XDG data root', () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-test-xdg-'));
+  const originalXdgDataHome = process.env.XDG_DATA_HOME;
+  try {
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    const dataRoot = path.join(xdgDataHome, 'SubMiner');
+    makeFile(path.join(dataRoot, 'thumbnailers', ROFI_THUMBNAILER_FILE));
+
+    const result = withPlatform('linux', () => findRofiThumbnailerDataRoot('/usr/bin/subminer'));
+    assert.equal(result, dataRoot);
+  } finally {
+    if (originalXdgDataHome === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = originalXdgDataHome;
+    }
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+  }
+});
+
+test('findRofiThumbnailerDataRoot is Linux-only', () => {
+  assert.equal(
+    withPlatform('darwin', () => findRofiThumbnailerDataRoot('/usr/bin/subminer')),
+    null,
+  );
+});
+
+test('prependXdgDataDir preserves existing roots and avoids duplicates', () => {
+  const root = '/tmp/subminer-data';
+  assert.equal(
+    prependXdgDataDir(root, `/opt/share${path.delimiter}${root}${path.delimiter}/usr/share`),
+    `${root}${path.delimiter}/opt/share${path.delimiter}/usr/share`,
+  );
+  assert.equal(
+    prependXdgDataDir(root),
+    `${root}${path.delimiter}/usr/local/share${path.delimiter}/usr/share`,
+  );
+});

launcher/picker.ts

@@ -159,6 +159,9 @@ interface RofiIconEntry {
   iconPath?: string;
 }
 
+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';
+const DEFAULT_XDG_DATA_DIRS = ['/usr/local/share', '/usr/share'];
+
 function showRofiIconMenu(
   entries: RofiIconEntry[],
   prompt: string,
@@ -389,6 +392,47 @@ export function findRofiTheme(scriptPath: string): string | null {
   return null;
 }
 
+export function findRofiThumbnailerDataRoot(scriptPath: string): string | null {
+  if (process.platform !== 'linux') return null;
+
+  const scriptDir = path.dirname(realpathMaybe(scriptPath));
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local/share');
+  const roots = [
+    path.join(xdgDataHome, 'SubMiner'),
+    path.posix.join('/usr/local/share/SubMiner'),
+    path.posix.join('/usr/share/SubMiner'),
+    path.join(scriptDir, 'assets'),
+    path.join(scriptDir, '..', 'assets'),
+  ];
+
+  for (const root of roots) {
+    if (fs.existsSync(path.join(root, 'thumbnailers', ROFI_THUMBNAILER_FILE))) {
+      return root;
+    }
+  }
+
+  return null;
+}
+
+export function prependXdgDataDir(dataRoot: string, currentValue?: string): string {
+  const currentDirs = currentValue
+    ? currentValue.split(path.delimiter).filter(Boolean)
+    : DEFAULT_XDG_DATA_DIRS;
+  return [dataRoot, ...currentDirs.filter((candidate) => candidate !== dataRoot)].join(
+    path.delimiter,
+  );
+}
+
+function buildRofiThumbnailEnvironment(scriptPath: string): NodeJS.ProcessEnv {
+  if (!commandExists('ffmpegthumbnailer')) return process.env;
+  const dataRoot = findRofiThumbnailerDataRoot(scriptPath);
+  if (!dataRoot) return process.env;
+  return {
+    ...process.env,
+    XDG_DATA_DIRS: prependXdgDataDir(dataRoot, process.env.XDG_DATA_DIRS),
+  };
+}
+
 export function showRofiMenu(
   videos: string[],
   dir: string,
@@ -420,6 +464,7 @@ export function showRofiMenu(
   const result = spawnSync('rofi', args, {
     input: buildRofiMenu(videos, dir, recursive),
     encoding: 'utf8',
+    env: buildRofiThumbnailEnvironment(scriptPath),
     stdio: ['pipe', 'pipe', 'ignore'],
   });
   if (result.error) {